@jskit-ai/agent-docs 0.1.283 → 0.1.285

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

@@ -49,7 +49,7 @@ Exports
 ### `scripts/browser-tests.mjs`
 Exports
 - `SETTINGS_VARIABLE`
-- `browserTestConfig({ testDir = "./tests/e2e", port = DEFAULT_PORT, server = "node ./bin/server.js", build = "npm run build", prepare = "", signIn = "", env = {}, health = "/api/health", globalTimeout = GLOBAL_TIMEOUT_MS, environment = process.env, cwd = process.cwd() } = {})`
+- `browserTestConfig({ testDir = "./tests/e2e", port = DEFAULT_PORT, server = "node ./bin/server.js", build = "npm run build", prepare = "", signIn = "", env = {}, health = "/api/health", globalTimeout = GLOBAL_TIMEOUT_MS, actionTimeout = ACTION_TIMEOUT_MS, navigationTimeout = NAVIGATION_TIMEOUT_MS, environment = process.env, cwd = process.cwd() } = {})`
 - `browserTestWorkers({ env = process.env, argv = process.argv } = {})`
 Local functions
 - `positiveInteger(value)`
@@ -66,6 +66,49 @@ Local functions
 - `buildCatalog({ repoRoot, packagesRoot, outputPath })`
 - `main()`
 
+### `scripts/data-access.mjs`
+Exports
+- `checkDataAccess({ projectRoot = process.cwd() } = {})`
+- `formatDataAccessReport(result)`
+- `readTableResourceSources({ projectRoot = process.cwd() } = {})`
+Local functions
+- `escapeRegExp(text)`
+- `skipsDirectory(name)`
+- `blank(text)`
+- `maskStrings(code)`
+- `closingOffset(masked, start)`
+- `nextCodeOffset(text, offset)`
+- `constantValue(code, name)`
+- `readValue(code, masked, offset)`
+- `topLevelKeys(masked, start, end, names)`
+- `objectArgument(masked, callOffset, matchLength)`
+- `keyValue(code, masked, keys, key)`
+- `readSourceFile(source)`
+- `objectKeys(masked, start, end)`
+- `objectAt(masked, offset)`
+- `readSchemaFields(code, masked, keys, ownership)`
+- `readTableResources(file, { code, masked, position })`
+- `readCrudContracts({ code, masked })`
+- `unnamedFields(resources, contracts)`
+- `ownsSystemContextName(source, masked)`
+- `readSystemScopes(file, { source, code, masked, position })`
+- `readInfrastructureExcuses(file, source)`
+- `isDataAccessRule(rule)`
+- `blockComments(source)`
+- `readLintDisables(file, source, position)`
+- `readRuntimeCapabilities(file, { code, masked, position })`
+- `isError(setting)`
+- `appEslint(root)`
+- `checkLintConfig(root, files, baseline, report)`
+- `checkCapabilities(baseline, uses, report)`
+- `readBaseline(root, report)`
+- `checkBaseline(baseline, excuses, scopes, report)`
+- `walk(root, directory, files)`
+- `frameworkPackages(root)`
+- `checkTables(resources, report)`
+- `checkSystemScopes(scopes, report)`
+- `sourceFiles(root)`
+
 ### `scripts/files.mjs`
 Exports
 - `fileExists(absolutePath)`
@@ -278,6 +321,8 @@ Local functions
 - `removeJskitDependencyRecords(dependencies = {}, localPackageNames = new Set())`
 - `alignLockManifestRecord(lockRecord, manifest, localPackageNames)`
 - `preparePackageLockForInstall(projectRoot, manifests, packageLockPath)`
+- `findImports(root, packageIds)`
+- `installedPackageMigrations(root)`
 
 ### `scripts/test-budget.mjs`
 Exports
@@ -300,9 +345,12 @@ Local functions
 ### `scripts/test-databases.mjs`
 Exports
 - `DATABASES_OPTION`
+- `foreignKeyCheckFor(cwd)`
 - `testDatabaseRunFor(count, cwd = process.cwd())`
 Local functions
 - `withOwnEnvironment(load)`
+- `exportedTableResources(namespace, isTableResource)`
+- `keyText({ tableName, columns, referencedTableName, referencedColumns })`
 
 ### `scripts/test-file-stop.mjs`
 Exports
@@ -341,6 +389,7 @@ Local functions
 ### `scripts/verify-packages.mjs`
 Exports
 - `main()`
+- `validateApiSummarySurfaces(packageJson)`
 - `validateCapabilityClosure(packages, { builtinCapabilities = BUILTIN_CAPABILITIES } = {})`
 - `validateMigrations(packageRecord, migrationOwners)`
 - `validateProviderExport(value, label)`

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

@@ -17,6 +17,7 @@ Use this on demand; do not load the full index at startup.
 ### `src/manifests.mjs`
 Exports
 - `DEPENDENCY_FIELDS`
+- `assertNoOutsidePathDependencies(records, repoRoot)`
 - `bumpPatch(version)`
 - `collectPatternPackageJsonPaths(packageRoot, nestedManifests = ["patterns", "examples"])`
 - `collectPublishDependencies(packageJson, localNames)`
@@ -37,6 +38,7 @@ Exports
 Local functions
 - `followVersion(declared, version)`
 - `expandWorkspacePattern(repoRoot, pattern)`
+- `localDependencyPath(spec)`
 - `versionFilePaths(record)`
 
 ### `src/npm-publication.mjs`
@@ -54,6 +56,7 @@ Local functions
 
 ### `src/release.mjs`
 Exports
+- `assertNoOutsidePathDependencies`
 - `assertReleaseCheckout(repoRoot, { allowAhead = false, branch = "main" } = {})`
 - `bumpPatch`
 - `collectPublishDependencies`
@@ -81,6 +84,8 @@ Local functions
 - `git(repoRoot, args)`
 - `commitAll(repoRoot, message)`
 - `releaseCommitMessage(entries)`
+- `catalogPins(record, entry)`
+- `waitUntilServedAsLatest(pins, inspection, { attempts = Number(process.env.JSKIT_RELEASE_SERVE_ATTEMPTS || 20), delayMs = Number(process.env.JSKIT_RELEASE_RETRY_DELAY_MS || 30_000) } = {})`
 - `publishRelease(records, { cwd: repoRoot, registry })`
 - `publishCommand(options)`
 - `forgetPinnedLockEntries(repoRoot, names)`

package/skills/jskit/SKILL.md

@@ -43,13 +43,16 @@ manifests, migrations, tests, and runtime behaviour are the evidence.
 4. Load only relevant references:
    - [port guide](references/existing-application-migration.md) for existing apps.
    - [heuristics index](references/heuristics/INDEX.md) for recurring traps.
+   - Before code that reads or writes a database table, read
+     [data access](references/data-access.md) completely; for connections,
+     migrations and test databases, [database layer](references/database-layer.md).
    - Before writing server code, read [typed features](references/typed-features.md) and its heuristic; client code, [client features](references/client-features.md). `npm run lint` checks both.
    - [multi-homing](references/multi-homing.md) for workspaces or invitations.
    - [translation](references/translation.md) for languages, translated texts
      or error codes.
    - For creation, foundation patterns, or package selection, read
      [application operations](references/app-operations.md).
-   - Before database, schema, CRUD, repository, or persistence work, read
+   - Before schema, CRUD or screen work on a table, also read
      [CRUD operations](references/crud-operations.md) completely; for custom
      form actions, also [form actions](references/crud-form-actions.md).
    - For routes, placements, user-facing UI, or browser verification, read

package/skills/jskit/references/app-operations.md

@@ -96,7 +96,7 @@ normal order is:
 
 1. confirm the product resource, ownership, operations, and fields
 2. author a migration as normal application source
-3. author the shared resource contract through `resource-crud-core`
+3. define the table resource (`defineTableResource`) and, for screens, its CRUD contract (`defineCrudContract`)
 4. use framework APIs for standard repository/service/action/route mechanics
 5. author product-specific screens from the relevant UI pattern
 6. run migrations and direct verification

package/skills/jskit/references/crud-operations.md

@@ -8,9 +8,14 @@ Take database, surface, access, ownership, operations, and fields from product
 intent and current source. Ask when a material choice is missing. Do not
 translate the work into generator options.
 
-Read the narrow package-owned pattern in the [bundled source pattern index](pattern-index.md): `crud/resource-contract` for the resource,
-`crud/json-api-resource-package` for the server, and `crud/crud-screen-set`
-for routed UI. Child-resource and row-policy patterns own those variations.
+Read the package-owned pattern in the [bundled source pattern index](pattern-index.md): `database/table-resource` for the table,
+`crud/crud-contract` for its HTTP surface,
+`crud/crud-feature-package` for the server, and `crud/crud-screen-set`
+for routed UI; the [row
+policies](heuristics/row-policies.md)
+and [child
+CRUDs](heuristics/child-cruds.md)
+heuristics cover those variations.
 
 Normal CRUD tables use one non-null integer primary key. Foreign keys are
 single-column; composite unique indexes are business constraints, not
@@ -20,26 +25,38 @@ Match visibility to real ownership and test allowed plus cross-owner cases.
 ## Author the resource normally
 
 1. Write an immutable app-owned migration.
-2. Define the shared resource contract through `defineCrudResource()`.
-3. Use `defineCrudJsonApiFeature()` for standard repository, service, action,
-   permission, resource-host, and route mechanics.
+2. Define the table resource with `defineTableResource()` and its HTTP surface
+   with `defineCrudContract()`, which names its `namespace`: the routes',
+   messages' and events' public name, never taken from the resource.
+3. Use `defineCrudFeature()` for standard table ownership, service, action,
+   permission, and route mechanics.
 4. Customize through `decorateRepository`, `decorateService`,
    `operationLifecycle`, and named `actions`; do not copy the standard CRUD
    repository/action/route stack.
 5. Build routed screens from the matching `http-web`/CRUD UI pattern.
 
-The resource is canonical for fields, operations, validation, transport,
-messages, and route parameters. Do not duplicate its schema or serializers.
+The table resource is canonical for fields, columns, ownership and search; the
+CRUD contract for operations, validation, transport, messages and route
+parameters. A contract shows and accepts only the fields its `fields` names (stored
+`createdAt` and `updatedAt` show without an entry; `createdAt: { output:
+false }` hides one), so a column added later stays out of every API until a
+contract names it. A CRUD feature's answers follow the same rule: an unnamed
+relationship is left out, and an included record shows only its id, its
+relation's `labelKey` and the fields the including contract lists in that
+field's `output.includeFields` (`{ breed: ["name"] }` in the list shows a
+record it links to, as deep as listed), never another contract's output.
+A package with a CRUD feature lists `crud.contracts` in its descriptor's
+`capabilities.requires`. Do not duplicate their schema or serializers.
 Prefer `useCrudListScreen()`, `useCrudViewScreen()`, and
 `useCrudAddEditScreen()`; use `useCommand()` or `useEndpointResource()` for
 non-standard operations.
 
 Add resource service methods with `decorateService`; expose commands such as
-`confirm`, `publish`, or `cancel` through named `actions`. With `operationLifecycle`, mutation `before`,
-`execute`, and `after` share one repository transaction, `execute` receives
-`standard(nextInput)`, and `afterCommit` follows commit. Repositories persist;
-services and hooks orchestrate. Use a transactional outbox for durable
-external work.
+`confirm` or `cancel` through named `actions`. With `operationLifecycle`, mutation `before`,
+`execute`, and `after` share one transaction, rerun on deadlock, so they touch
+only the database; `execute` receives `standard(nextInput)`. Outside effects go
+in `afterCommit`, run once after commit, or an outbox when durable.
+Repositories persist; services and hooks orchestrate.
 
 ## Choose ownership, API access and client access independently
 
@@ -47,37 +64,31 @@ These controls answer different questions:
 
 | Control | Purpose | Public records | Owner-scoped records |
 | --- | --- | --- | --- |
-| Resource `autofilter` | Which rows belong to the request scope | `"public"`; no ownership column | `"user"`; real non-null `userId` column |
-| Resource `apiAccess` | Who may call the API | `"public"` | `"authenticated"` |
-| Feature `ownershipFilter` | Server route/action ownership scope | `"public"` | `"user"` |
+| Table resource `ownership` | Which rows belong to the request scope | `"public"`; no ownership column | `"user"`; real non-null `userId` column |
+| CRUD contract `apiAccess` | Who may call the API | `"public"` | `"authenticated"` |
+| Feature route visibility | Server route/action scope: the table's `ownership` unless the feature names `visibility` | `"public"` | `"user"` |
 | Client `access` | Whether to require bootstrap permissions | Default `"auto"` with no permission requirements | Default `"auto"`; declare permissions when required |
 
-`access` accepts `auto`, `always`, or `never`, not `public`. With `auto`, a
-screen with no permission requirements does not require a permissions bootstrap.
-`always` does require it. Do not add authentication or workspace machinery to
-compensate for an unnecessary `always` override. Server access and ownership
+`access` accepts `auto`, `always`, or `never`, not `public`. `auto` requires a
+permissions bootstrap only for a screen with permission requirements; `always`
+always does. Do not add authentication or workspace machinery to
+make up for an unneeded `always` override. Server access and ownership
 remain authoritative.
 
-The Books source patterns demonstrate user ownership. For an intentionally
-public create/list resource, use the same patterns with this resource contract:
+The Books source patterns show user ownership. For a public create/list
+resource, use them with this table resource and CRUD contract:
 
 ```js
-const bookResource = defineCrudResource({
-  namespace: "books",
+const bookResource = defineTableResource({
+  name: "books",
   tableName: "books",
-  apiAccess: "public",
-  autofilter: "public",
-  crudOperations: ["list", "view", "create"],
+  ownership: "public",
   schema: {
     title: {
       type: "string",
       required: true,
       minLength: 1,
-      maxLength: 255,
-      operations: {
-        output: { required: true },
-        create: { required: true }
-      }
+      maxLength: 255
     }
   },
   searchSchema: {
@@ -90,20 +101,27 @@ const bookResource = defineCrudResource({
     }
   }
 });
+
+const bookCrud = defineCrudContract(bookResource, {
+  namespace: "books",
+  apiAccess: "public",
+  operations: ["list", "view", "create"],
+  fields: { title: { output: "required", create: "required" } }
+});
 ```
 
-Import `defineCrudResource` from
-`@jskit-ai/resource-crud-core/shared/crudResource`. Its app-owned migration
-creates `books` with an integer primary key `id` and non-null `title`; omit
-`userId` and its foreign key for this public variant. `list` requires `view`
-in the shared resource contract, even when the UI has no detail page. A create
-response uses the resource output contract. Keep operation names such as
-`list`, `view` and `create`; do not invent output-operation aliases.
-
-Bind `defineCrudJsonApiFeature()` with this resource, `ownershipFilter:
-"public"`, `relativePath: "/books"` and the application's configured public
-surface. Keep the existing package/provider and migration registration from
-`crud/json-api-resource-package`.
+Import `defineTableResource` from `@jskit-ai/resource-core/shared/tableResource`
+and `defineCrudContract` from `@jskit-ai/resource-crud-core/shared/crudContract`.
+Its migration creates `books` with an integer `id` and non-null `title`; omit
+`userId` and its foreign key.
+`list` requires `view` in the CRUD contract, even when the UI has no detail
+page. A create response uses the CRUD contract's output. Keep operation names
+such as `list`, `view` and `create`; do not invent output-operation aliases.
+
+Bind `defineCrudFeature()` with `crud: bookCrud`, `relativePath: "/books"`
+and the application's configured public surface; the table's `"public"`
+ownership makes its routes public. Keep the existing package/provider and migration registration from
+`crud/crud-feature-package`.
 
 For the list, keep `BookListPage.vue` thin: use `resourceNamespace: "books"`
 in `useCrudListScreen()` on the configured public surface, remove unsupported