@jskit-ai/agent-docs 0.1.98 → 0.1.99

package/guide/agent/app-setup/database-layer.md

@@ -613,6 +613,7 @@ const dialectId = resolveDatabaseClientFromEnvironment(process.env);
 const client = toKnexClientId(dialectId);
 const defaultPort = dialectId === "pg" ? 5432 : 3306;
 const migrationsDirectory = path.resolve(appRoot, normalizeText(process.env.DB_MIGRATIONS_DIR) || "migrations");
+const deferredConstraintsDirectory = path.join(migrationsDirectory, "constraints");
 
 export default {
   client,
@@ -622,8 +623,9 @@ export default {
     context: "knex migrations"
   }),
   migrations: {
-    directory: migrationsDirectory,
-    extension: "cjs"
+    directory: [migrationsDirectory, deferredConstraintsDirectory],
+    extension: "cjs",
+    sortDirsSeparately: true
   }
 };
 ```
@@ -643,6 +645,14 @@ So there are really two separate database entry points:
 
 That separation is good. It keeps the operational CLI workflow and the app runtime wiring clear.
 
+The two migration directories are one ordered migration plan. Knex completes
+the ordinary `migrations/` files before it reads
+`migrations/constraints/`. CRUD scaffolding uses that second phase for foreign
+keys, so two tables may validly reference one another without either
+table-creation migration depending on a table that has not been created yet.
+Rollback reverses the order and removes those constraints before dropping
+tables.
+
 ### The MySQL package registers the driver, and the generic runtime builds the Knex client
 
 On the server side, the two installed packages split responsibilities very deliberately.

package/guide/agent/generators/crud-generators.md

@@ -248,6 +248,13 @@ needs a different persistence model, record the durable decision in
 `.jskit/APP_BLUEPRINT.md` and use the explicit table-ownership exception path
 instead of modifying generated CRUD files.
 
+Mutual foreign keys are valid when each side still follows that key contract.
+The server generator keeps table creation and foreign-key installation in
+separate migration phases: every ordinary migration creates its table first,
+then migrations under `migrations/constraints/` add the constraints. Do not
+move those constraints back into the table-creation migrations or disable
+foreign-key checks to work around ordering.
+
 ## Example 1: `contacts`
 
 This is the baseline pattern. If you understand this example, the rest of the chapter becomes much easier.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.98",
+  "version": "0.1.99",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/crud-scaffolding.md

@@ -51,6 +51,10 @@ Rules:
 - If the table should already be CRUD-owned but should not expose public CRUD HTTP routes yet, scaffold it with `jskit generate crud-server-generator scaffold ... --internal` instead of dropping to direct knex or a hand-built pseudo-repository.
 - Create the real table directly in the database before scaffolding. `crud-server-generator` reads the live table shape.
 - If `crud-server-generator` is going to own the CRUD, do not hand-write a separate CRUD migration for that table. The generator installs and manages the CRUD migration scaffold itself.
+- Keep generated table creation in `migrations/` and generated foreign keys in
+  `migrations/constraints/`. The database runtime deliberately runs those
+  phases in that order so valid mutual foreign keys rebuild cleanly without
+  disabling constraint checks.
 - Do not scaffold CRUD UI, hand-build CRUD routes, or hand-build CRUD endpoints before the server CRUD package and shared resource file exist.
 - Treat the generated shared resource file as the canonical CRUD contract for later UI scaffolding and CRUD behavior changes.
 - Treat the exact columns `workspace_id` and `user_id` as reserved JSKIT ownership columns. They are the only standard columns used for generated ownership filtering and create-time owner stamping.

package/reference/autogen/packages/crud-server-generator.md

@@ -78,6 +78,8 @@ Local functions
 - `renderMigrationIndexLines(snapshot)`
 - `renderMigrationForeignKeyLine(foreignKey = {})`
 - `renderMigrationForeignKeyLines(snapshot)`
+- `renderMigrationDropForeignKeyLine(foreignKey = {})`
+- `renderMigrationDropForeignKeyLines(snapshot)`
 - `renderMigrationCheckConstraintLines(snapshot)`
 - `mergeFieldMetaEntries(...entryGroups)`
 - `resolveLookupNamespaceFromTableName(tableName = "")`
@@ -157,6 +159,10 @@ Exports
 
 ### templates
 
+### `templates/migrations/crud_foreign_keys.cjs`
+Exports
+- None
+
 ### `templates/migrations/crud_initial.cjs`
 Exports
 - None

package/reference/autogen/tooling/jskit-cli.md

@@ -582,7 +582,9 @@ Exports
 ### `src/server/commandHandlers/appCommands/updatePackages.js`
 Exports
 - `collectChangedInstalledPackageIds(lock = {}, latestVersions = new Map())`
+- `findRangeIntersectionVersion(ranges = [])`
 - `formatElapsedTime(elapsedMilliseconds = 0)`
+- `resolveRequiredDirectPeerUpdates({ createCliError, packageJson = {}, packageManifests = new Map() } = {})`
 - `reapplyChangedInstalledPackages({ appRoot, createCliError, dryRun, latestVersions, loadLockFile, stderr, stdout })`
 - `runAppUpdatePackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr })`
 - `runWithProgress(task, { activity, progressIntervalMs = PROGRESS_INTERVAL_MS, stdout, step } = {})`
@@ -593,6 +595,9 @@ Local functions
 - `resolveMajorRange(packageName = "", version = "", createCliError)`
 - `resolveRegistryArgs(registryUrl = "")`
 - `resolveInstallSpecs(packageNames = [], latestVersions = new Map())`
+- `parseRegistryPackageManifest(rawValue, packageName, createCliError)`
+- `resolveRegistryPackageManifests(packageNames = [], latestVersions = new Map(), { appRoot, createCliError, registryArgs, stderr, stdout })`
+- `resolveDeclaredDependencySection(packageJson = {}, packageName = "")`
 - `hasNpmWorkspaces(packageJson = {})`
 - `readJson(filePath)`
 - `readOptionalFile(filePath)`