@jskit-ai/agent-docs 0.1.283 → 0.1.284

package/skills/jskit/references/heuristics/crud-repository-mapping.md

@@ -1,140 +0,0 @@
-<!-- Generated from `packages/agent-docs/heuristics/crud-repository-mapping.md`. -->
-
-# CRUD Repository Mapping
-
-Use when:
-- a CRUD resource needs explicit DB column mapping
-- a field should exist in API output but is not a real DB column
-- the user mentions computed fields or projections
-
-Default JSKIT pattern:
-1. Treat the schema as the API contract only.
-2. Put persistence mapping on the field definitions themselves.
-3. Use `actualField` for explicit DB column overrides.
-4. Let generic CRUD runtime handle standard writable `date-time` fields automatically at the DB write seam.
-5. Use `storage.writeSerializer` only for non-default write serialization.
-6. Use `storage: { virtual: true }` for computed output fields.
-7. For `createCrudResourceRuntime(...)` repositories, register computed SQL projections once with `virtualFields`.
-8. For internal JSON REST repositories, register SQL-selected output fields with `createJsonRestResourceScopeOptions(resource, { queryFields })`.
-9. Let generic read paths apply those projections automatically.
-
-Field metadata rules:
-- for a normal override, write:
-
-```js
-createdAt: {
-  type: "dateTime",
-  required: true,
-  actualField: "created_at"
-}
-```
-
-- for a non-default write serializer override, write:
-
-```js
-arrivalDatetime: {
-  type: "dateTime",
-  required: true,
-  storage: {
-    writeSerializer: "datetime-utc"
-  }
-}
-```
-
-- for a computed output field, write:
-
-```js
-remainingBatchWeight: {
-  type: "number",
-  required: true,
-  storage: {
-    virtual: true
-  }
-}
-```
-
-- omit `actualField`/`storage` when the field is column-backed and the default snake_case mapping is correct
-- standard writable `format: "date-time"` fields do not need explicit `storage.writeSerializer`
-- use `storage.writeSerializer` only for non-default DB write behavior
-- `storage: { virtual: true }` cannot also define `actualField` or `storage.column`
-- `storage: { virtual: true }` cannot also define `storage.writeSerializer`
-- `storage: { virtual: true }` fields must not appear in create/patch write schemas
-
-Repository pattern:
-- build the runtime with `createCrudResourceRuntime(resource, knex, { ... })`, passing the application's Knex instance
-- register computed projections in `virtualFields`
-- keep SQL in the repository, not in shared metadata
-- let generic CRUD runtime apply `storage.writeSerializer` during create/update writes
-
-Example:
-
-```js
-const repositoryRuntime = createCrudResourceRuntime(resource, knex, {
-  context: "receivals repository",
-  list: LIST_CONFIG,
-  virtualFields: {
-    remainingBatchWeight: {
-      applyProjection(dbQuery, { knex, tableName, alias }) {
-        const { sql, bindings } = getRemainingBatchWeightSqlParts({ tableName });
-        dbQuery.select(knex.raw(`${sql} as ??`, [...bindings, alias]));
-      }
-    }
-  }
-});
-```
-
-Internal JSON REST pattern:
-- keep the API field in the resource schema as `storage: { virtual: true }`
-- pass server-only SQL projection callbacks through `createJsonRestResourceScopeOptions(...)`
-- keep query projection SQL in the provider/server registration file, not in browser-imported page code
-
-Example:
-
-```js
-await addResourceIfMissing(
-  api,
-  "receivals",
-  createJsonRestResourceScopeOptions(resource, {
-    queryFields: {
-      remainingProcessableWeight: {
-        type: "number",
-        select({ knex, column }) {
-          return knex.raw("?? - coalesce(??, 0)", [
-            column("received_weight"),
-            column("processed_weight")
-          ]);
-        }
-      }
-    }
-  })
-);
-```
-
-If the resource module is server-only, a field may also declare `storage.queryProjection`; `createJsonRestResourceScopeOptions(...)` moves it into JSON REST `queryFields` and removes the virtual field from the storage schema. Prefer the `queryFields` option when the resource module is shared with client code.
-
-What CRUD core does for you:
-- default select columns include only column-backed output fields
-- create/update write payloads serialize standard writable `date-time` fields centrally
-- database reads serialize `date`, `time`, and `dateTime` values to their
-  strict `json-rest-schema` string contracts before resource validation,
-  respecting `temporalPrecision`
-- create/update write payloads also apply any explicit field write serializers centrally
-- `list`, `findById`, `listByIds`, and `listByForeignIds` apply registered virtual projections automatically
-- search and parent-filter fallback derivation only use column-backed fields
-- `listByIds(..., { valueKey })` requires that `valueKey` be column-backed
-
-Avoid:
-- manual `clearSelect()` / re-select hacks in individual repository methods just to add computed fields
-- putting SQL fragments or joins into shared field metadata
-- inventing `storage` modes beyond the documented `virtual` contract
-
-Review checks:
-- schema defines contract, not storage
-- field definitions own mapping
-- standard datetime DB write serialization stays automatic and runtime-owned
-- any non-default DB write serialization lives in `storage.writeSerializer`, not in per-repository hooks
-- computed fields use `storage: { virtual: true }`
-- repository runtime registers matching `virtualFields`, or the JSON REST provider registers matching `queryFields`
-- no per-method projection duplication when generic CRUD reads already cover the field
-- no JavaScript `Date` object crosses a strict resource validation boundary;
-  custom repositories return ISO/RFC 3339 strings explicitly

package/skills/jskit/references/patterns/crud/json-api-resource-package/example/packages/books/src/server/BooksFeature.js

@@ -1,13 +0,0 @@
-import { defineCrudJsonApiFeature } from "@jskit-ai/crud-core/server/defineCrudJsonApiFeature";
-import { bookResource } from "../shared/bookResource.js";
-
-const BooksFeature = defineCrudJsonApiFeature({
-  resource: bookResource,
-  id: "app.books",
-  capability: "app.books",
-  surface: "app",
-  ownershipFilter: "user",
-  relativePath: "/books"
-});
-
-export { BooksFeature };

package/skills/jskit/references/patterns/crud/json-api-resource-package/example/packages/books/src/shared/bookResource.js

@@ -1,83 +0,0 @@
-import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
-
-const bookResource = defineCrudResource({
-  namespace: "books",
-  tableName: "books",
-  apiAccess: "authenticated",
-  autofilter: "user",
-  schema: {
-    userId: {
-      type: "id",
-      required: true,
-      hidden: true,
-      operations: {}
-    },
-    title: {
-      type: "string",
-      maxLength: 255,
-      required: true,
-      search: true,
-      operations: {
-        output: { required: true },
-        create: { required: true },
-        patch: { required: false }
-      }
-    },
-    author: {
-      type: "string",
-      maxLength: 255,
-      required: true,
-      search: true,
-      operations: {
-        output: { required: true },
-        create: { required: true },
-        patch: { required: false }
-      }
-    },
-    notes: {
-      type: "string",
-      maxLength: 65535,
-      nullable: true,
-      search: true,
-      operations: {
-        output: { required: true },
-        create: { required: false },
-        patch: { required: false }
-      }
-    },
-    createdAt: {
-      type: "dateTime",
-      temporalPrecision: 0,
-      default: "now()",
-      storage: { writeSerializer: "datetime-utc" },
-      operations: { output: { required: true } }
-    },
-    updatedAt: {
-      type: "dateTime",
-      temporalPrecision: 0,
-      default: "now()",
-      storage: { writeSerializer: "datetime-utc" },
-      operations: { output: { required: true } }
-    }
-  },
-  searchSchema: {
-    id: { type: "id", actualField: "id" },
-    q: {
-      type: "string",
-      oneOf: ["title", "author", "notes"],
-      filterOperator: "like",
-      splitBy: " ",
-      matchAll: true
-    }
-  },
-  defaultSort: ["-createdAt"],
-  messages: {
-    validation: "Fix invalid values and try again.",
-    saveSuccess: "Book saved.",
-    saveError: "Unable to save this book.",
-    deleteSuccess: "Book deleted.",
-    deleteError: "Unable to delete this book."
-  }
-});
-
-export { bookResource };

package/skills/jskit/references/patterns/crud/json-api-resource-package/example/packages/books/src/shared/index.js

@@ -1 +0,0 @@
-export { bookResource } from "./bookResource.js";

package/skills/jskit/references/patterns/crud/resource-contract/PATTERN.md

@@ -1,155 +0,0 @@
----
-id: crud/resource-contract
-title: Owner-scoped CRUD resource contract
-summary: Define an authenticated application resource whose records belong to the current user.
-keywords: authenticated, crud, database, owner-scoped, resource, user
-requires: @jskit-ai/resource-crud-core
----
-
-# Owner-scoped CRUD resource contract
-
-## Use when
-
-Use this pattern when an authenticated application stores records that belong
-to one user and standard list, view, create, patch, and delete behaviour fits
-the product.
-
-The example is intentionally a normal source file. Copy it directly when the
-shape fits, adapt its fields and language for another entity, or read it as a
-reference for `defineCrudResource()`.
-
-## Do not use when
-
-Do not use this pattern for public records, workspace-owned records, inherited
-ownership, composite identities, or a domain whose operations do not match
-normal CRUD behaviour. Select a pattern matching the real ownership and
-operation model instead of changing `autofilter` merely to make a test pass.
-
-## Product decisions
-
-Know these decisions before adapting the example:
-
-- whether records truly belong to the current user
-- which fields are required, optional, nullable, searchable, or hidden
-- whether a value is free text or a constrained vocabulary
-- which operations the product actually exposes
-- the user-facing success and failure language
-
-Those decisions come from the product conversation or existing application,
-not from a JSKIT questionnaire.
-
-## Invariants
-
-- The persisted table has a normal single-column primary key.
-- User ownership is represented by a non-null `user_id` column.
-- The resource's hidden `userId` field maps to that ownership column.
-- `autofilter: "user"` is used only for genuine current-user ownership.
-- Each product field's output, create, and patch participation is its
-  `operations` block, or the default `defineCrudResource()` gives a field
-  without one (see Field operations and lookups below).
-- Temporal database values use the declared storage serializer.
-- The source-controlled migration and resource contract agree.
-- Server policy tests prove that one user cannot read or mutate another user's
-  records.
-
-## Framework APIs
-
-The example uses `defineCrudResource()` from
-`@jskit-ai/resource-crud-core/shared/crudResource`. That API derives the normal
-CRUD operation validators from one readable field contract.
-
-Higher layers should consume this resource through JSKIT's CRUD service,
-repository, route, and UI APIs. They should not rebuild field validators or
-serialize requests independently.
-
-## Field operations and lookups
-
-A field's `operations` name the operations it takes part in: `output` (the
-record in every response), and `create` and `patch` (the request bodies; an
-enabled `replace` uses the `create` fields unless a field names `replace`). A
-field that leaves `operations` out takes the default:
-
-| Field | Default `operations` |
-| --- | --- |
-| `primary: true` | `{}`: no operation; every record output already carries its `id` |
-| `hidden: true` | `{}`: no operation |
-| `readOnly: true` | `{ output: { required: true } }` |
-| any other field | `{ output: { required: true }, create: { required: <the field's required> }, patch: { required: false } }` |
-
-So a `required: true` field is required on create, and any other field is
-optional there. An `operations` block you write always wins, for example
-`operations: { output: {}, create: {}, patch: {} }` for a field that is
-optional everywhere. Write the block only where it differs from the default:
-
-```js
-schema: {
-  userId: { type: "id", required: true, hidden: true },
-  title: { type: "string", maxLength: 255, required: true, search: true },
-  notes: { type: "string", maxLength: 65535, nullable: true, search: true },
-  createdAt: { type: "dateTime", default: "now()", readOnly: true, storage: { writeSerializer: "datetime-utc" } }
-}
-```
-
-A field that looks up a record of another resource can name that resource's
-namespace with `lookup`:
-
-```js
-shelfId: { type: "id", nullable: true, search: true, lookup: "shelves" }
-```
-
-`defineCrudResource()` expands it, where `lookup` stood, to:
-
-```js
-relation: { kind: "lookup", namespace: "shelves", valueKey: "id" },
-belongsTo: "shelves",  // the namespace's JSON REST resource, camel-cased
-as: "shelf",           // the field key without its Id suffix
-ui: { formControl: "autocomplete" }
-```
-
-Keys you write beside `lookup` win: `belongsTo` and `as` replace the
-filled-in values, and `relation` and `ui` are merged over them, so
-`relation: { labelKey: "name" }` adds a label key and
-`ui: { formControl: "select" }` picks a select. A field whose key has no `Id`
-suffix must write `as`. The built resource equals one that writes the expanded
-keys out.
-
-## Example files
-
-- `example/bookResource.js` is a complete resource contract for personal book
-  records.
-
-The example deliberately uses a concrete domain. Rename and edit normal source
-rather than feeding it through placeholder interpolation.
-
-## Variation points
-
-Safe adaptations include:
-
-- namespace and table name
-- product fields and validation
-- searchable fields and default sort
-- enabled CRUD operations
-- user-facing messages
-- lookup relationships supported by the resource APIs
-
-Changing ownership, access, identity, or persistence architecture selects a
-different pattern and requires corresponding policy and migration evidence.
-
-## Verification
-
-- Import the resource and prove all intended operations exist.
-- Validate representative accepted and rejected field values.
-- Rebuild the table from source-controlled migrations in a disposable database.
-- Run positive current-user CRUD tests.
-- Run negative cross-user read and mutation tests.
-- Run the application's focused tests and broad verifier at sign-off.
-
-## Avoid
-
-- generator provenance or scaffold-shape metadata
-- a field-by-field questionnaire
-- a live table as the only source of schema truth
-- app-specific request serializers that duplicate the resource contract
-- hidden ownership aliases other than the framework's explicit ownership field
-- durable receipts recording that this pattern was copied
-- changing an installed baseline migration instead of adding a new migration

package/skills/jskit/references/patterns/crud/resource-contract/example/bookResource.js

@@ -1,87 +0,0 @@
-import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
-
-const bookResource = defineCrudResource({
-  namespace: "books",
-  tableName: "books",
-  apiAccess: "authenticated",
-  schema: {
-    userId: {
-      type: "id",
-      required: true,
-      hidden: true,
-      operations: {}
-    },
-    title: {
-      type: "string",
-      maxLength: 255,
-      required: true,
-      search: true,
-      operations: {
-        output: { required: true },
-        create: { required: true },
-        patch: { required: false }
-      }
-    },
-    author: {
-      type: "string",
-      maxLength: 255,
-      required: true,
-      search: true,
-      operations: {
-        output: { required: true },
-        create: { required: true },
-        patch: { required: false }
-      }
-    },
-    notes: {
-      type: "string",
-      maxLength: 65535,
-      nullable: true,
-      search: true,
-      operations: {
-        output: { required: true },
-        create: { required: false },
-        patch: { required: false }
-      }
-    },
-    createdAt: {
-      type: "dateTime",
-      temporalPrecision: 0,
-      default: "now()",
-      storage: { writeSerializer: "datetime-utc" },
-      operations: {
-        output: { required: true }
-      }
-    },
-    updatedAt: {
-      type: "dateTime",
-      temporalPrecision: 0,
-      default: "now()",
-      storage: { writeSerializer: "datetime-utc" },
-      operations: {
-        output: { required: true }
-      }
-    }
-  },
-  searchSchema: {
-    id: { type: "id", actualField: "id" },
-    q: {
-      type: "string",
-      oneOf: ["title", "author", "notes"],
-      filterOperator: "like",
-      splitBy: " ",
-      matchAll: true
-    }
-  },
-  defaultSort: ["-createdAt"],
-  autofilter: "user",
-  messages: {
-    validation: "Fix invalid values and try again.",
-    saveSuccess: "Book saved.",
-    saveError: "Unable to save this book.",
-    deleteSuccess: "Book deleted.",
-    deleteError: "Unable to delete this book."
-  }
-});
-
-export { bookResource };

package/skills/jskit/references/patterns/server/feature-package/example/variations/customKnexRepository.js

@@ -1,40 +0,0 @@
-import { createWithTransaction } from "@jskit-ai/database-runtime/shared";
-
-/**
- * The invoice rollup's persistence: a reviewed custom Knex repository.
- * @param {{ knex: import("@jskit-ai/database-runtime/server/types").RuntimeKnex }} dependencies
- */
-function createInvoiceRollup({ knex }) {
-  const withTransaction = createWithTransaction(knex);
-
-  async function getStatus(input, options = {}) {
-    return {
-      ok: true,
-      feature: "invoice-rollup",
-      persistence: "custom-knex",
-      tableName: "invoice_rollups",
-      hasTransaction: Boolean(options.trx),
-      input
-    };
-  }
-
-  async function execute(input, options = {}) {
-    return {
-      accepted: false,
-      feature: "invoice-rollup",
-      persistence: "custom-knex",
-      tableName: "invoice_rollups",
-      hasTransaction: Boolean(options.trx),
-      input,
-      message: "Replace this example with the reviewed domain-specific query."
-    };
-  }
-
-  return Object.freeze({
-    withTransaction,
-    getStatus,
-    execute
-  });
-}
-
-export { createInvoiceRollup };

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/src/shared/userResource.js

@@ -1,69 +0,0 @@
-import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
-
-const resource = defineCrudResource({
-  namespace: "users",
-  tableName: "users",
-  crudOperations: ["list", "view"],
-  schema: {
-    name: {
-      type: "string",
-      required: true,
-      minLength: 1,
-      maxLength: 160,
-      actualField: "display_name",
-      search: true,
-      operations: {
-        output: { required: false }
-      }
-    },
-    email: {
-      type: "string",
-      required: true,
-      search: true,
-      operations: {
-        output: { required: false }
-      }
-    },
-    username: {
-      type: "string",
-      required: true,
-      search: true,
-      operations: {
-        output: { required: false }
-      }
-    },
-    createdAt: {
-      type: "dateTime",
-      required: true,
-      storage: { writeSerializer: "datetime-utc" },
-      operations: {
-        output: { required: true }
-      }
-    },
-    updatedAt: {
-      type: "dateTime",
-      required: true,
-      storage: { writeSerializer: "datetime-utc" },
-      operations: {
-        output: { required: true }
-      }
-    }
-  },
-  searchSchema: {
-    id: {
-      type: "id",
-      actualField: "id"
-    },
-    q: {
-      type: "string",
-      oneOf: ["name", "email", "username"],
-      filterOperator: "like",
-      splitBy: " ",
-      matchAll: true
-    }
-  },
-  defaultSort: ["name", "email"],
-  autofilter: "public"
-});
-
-export { resource };

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/shared/userResource.js

@@ -1,56 +0,0 @@
-import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
-
-const resource = defineCrudResource({
-  namespace: "users",
-  tableName: "users",
-  crudOperations: ["list", "view"],
-  schema: {
-    name: {
-      type: "string",
-      required: true,
-      minLength: 1,
-      maxLength: 160,
-      actualField: "display_name",
-      search: true,
-      operations: { output: { required: false } }
-    },
-    email: {
-      type: "string",
-      required: true,
-      search: true,
-      operations: { output: { required: false } }
-    },
-    username: {
-      type: "string",
-      required: true,
-      search: true,
-      operations: { output: { required: false } }
-    },
-    createdAt: {
-      type: "dateTime",
-      required: true,
-      storage: { writeSerializer: "datetime-utc" },
-      operations: { output: { required: true } }
-    },
-    updatedAt: {
-      type: "dateTime",
-      required: true,
-      storage: { writeSerializer: "datetime-utc" },
-      operations: { output: { required: true } }
-    }
-  },
-  searchSchema: {
-    id: { type: "id", actualField: "id" },
-    q: {
-      type: "string",
-      oneOf: ["name", "email", "username"],
-      filterOperator: "like",
-      splitBy: " ",
-      matchAll: true
-    }
-  },
-  defaultSort: ["name", "email"],
-  autofilter: "public"
-});
-
-export { resource };