@jskit-ai/agent-docs 0.1.149 → 0.1.151

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookFormFields.vue

@@ -0,0 +1,52 @@
+<script setup>
+const title = defineModel("title", { type: String, default: "" });
+const author = defineModel("author", { type: String, default: "" });
+const notes = defineModel("notes", { type: String, default: "" });
+
+defineProps({
+  readonly: {
+    type: Boolean,
+    default: false
+  },
+  resolveFieldErrors: {
+    type: Function,
+    required: true
+  }
+});
+</script>
+
+<template>
+  <v-col cols="12" md="6">
+    <v-text-field
+      v-model="title"
+      label="Title"
+      variant="outlined"
+      density="comfortable"
+      maxlength="255"
+      :readonly="readonly"
+      :error-messages="resolveFieldErrors('title')"
+    />
+  </v-col>
+  <v-col cols="12" md="6">
+    <v-text-field
+      v-model="author"
+      label="Author"
+      variant="outlined"
+      density="comfortable"
+      maxlength="255"
+      :readonly="readonly"
+      :error-messages="resolveFieldErrors('author')"
+    />
+  </v-col>
+  <v-col cols="12">
+    <v-textarea
+      v-model="notes"
+      label="Notes"
+      variant="outlined"
+      density="comfortable"
+      auto-grow
+      :readonly="readonly"
+      :error-messages="resolveFieldErrors('notes')"
+    />
+  </v-col>
+</template>

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookListPage.vue

@@ -0,0 +1,50 @@
+<script setup>
+import CrudListScreen from "@jskit-ai/http-web/client/components/CrudListScreen";
+import { useCrudListScreen } from "@jskit-ai/http-web/client/composables/useCrudListScreen";
+import { bookResource } from "@local/books/shared";
+import { listBulkActions, listFilters, listRowActions } from "./listExtensions.js";
+
+const screen = useCrudListScreen({
+  resource: bookResource,
+  resourceNamespace: "books",
+  apiSuffix: "/books",
+  recordIdParam: "bookId",
+  recordIdSelector: (book = {}) => book.id,
+  titleFallbackFieldKey: "title",
+  viewUrlTemplate: "/books/:bookId",
+  editUrlTemplate: "/books/:bookId/edit",
+  newUrlTemplate: "/books/new",
+  listFilters,
+  listBulkActions,
+  listRowActions,
+  requestRecoveryLabel: "Books",
+  fallbackLoadError: "Unable to load books."
+});
+</script>
+
+<template>
+  <CrudListScreen
+    :screen="screen"
+    create-label="Add book"
+    empty-body="Add your first book to begin the catalogue."
+  >
+    <template #card-fields="{ record, formatListCardValue }">
+      <dl class="d-grid ga-2 mb-0">
+        <div>
+          <dt class="text-caption text-medium-emphasis">Author</dt>
+          <dd class="text-body-2 mb-0">{{ formatListCardValue(record.author) }}</dd>
+        </div>
+      </dl>
+    </template>
+
+    <template #table-header>
+      <th>Title</th>
+      <th>Author</th>
+    </template>
+
+    <template #table-row="{ record }">
+      <td>{{ record.title }}</td>
+      <td>{{ record.author }}</td>
+    </template>
+  </CrudListScreen>
+</template>

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookNewPage.vue

@@ -0,0 +1,43 @@
+<script setup>
+import CrudAddEditScreen from "@jskit-ai/http-web/client/components/CrudAddEditScreen";
+import { useCrudAddEditScreen } from "@jskit-ai/http-web/client/composables/useCrudAddEditScreen";
+import { bookResource } from "@local/books/shared";
+import BookFormFields from "./BookFormFields.vue";
+import { bookFormFields } from "./formFields.js";
+
+const screen = useCrudAddEditScreen({
+  mode: "new",
+  saveLabel: "Save book",
+  cancelTo: "/books",
+  resource: bookResource,
+  operationName: "create",
+  formFields: bookFormFields,
+  addEditOptions: {
+    apiSuffix: "/books",
+    placementSource: "crud.books.new",
+    readEnabled: false,
+    writeMethod: "POST",
+    recordIdParam: "bookId",
+    viewUrlTemplate: "/books/:bookId",
+    listUrlTemplate: "/books"
+  },
+  saveSuccess: {
+    invalidateQueryKey: ["crud", "books"],
+    listUrlTemplate: "/books"
+  }
+});
+</script>
+
+<template>
+  <CrudAddEditScreen :screen="screen">
+    <template #fields="fieldRuntime">
+      <BookFormFields
+        v-model:title="fieldRuntime.formState.title"
+        v-model:author="fieldRuntime.formState.author"
+        v-model:notes="fieldRuntime.formState.notes"
+        :readonly="fieldRuntime.addEdit.isFieldLocked"
+        :resolve-field-errors="fieldRuntime.resolveFieldErrors"
+      />
+    </template>
+  </CrudAddEditScreen>
+</template>

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookViewPage.vue

@@ -0,0 +1,49 @@
+<script setup>
+import CrudDeleteAction from "@jskit-ai/http-web/client/components/CrudDeleteAction";
+import CrudViewScreen from "@jskit-ai/http-web/client/components/CrudViewScreen";
+import { useCrudDeleteAction } from "@jskit-ai/http-web/client/composables/useCrudDeleteAction";
+import { useCrudViewScreen } from "@jskit-ai/http-web/client/composables/useCrudViewScreen";
+import { bookResource } from "@local/books/shared";
+
+const screen = useCrudViewScreen({
+  resource: bookResource,
+  resourceNamespace: "books",
+  apiUrlTemplate: "/books/:bookId",
+  recordIdParam: "bookId",
+  titleFallbackFieldKey: "title",
+  listUrlTemplate: "/books",
+  editUrlTemplate: "/books/:bookId/edit",
+  requestRecoveryLabel: "Book",
+  fallbackLoadError: "Unable to load this book."
+});
+
+const deleteAction = useCrudDeleteAction({
+  screen,
+  resource: bookResource,
+  resourceNamespace: "books",
+  apiUrlTemplate: "/books/:bookId"
+});
+</script>
+
+<template>
+  <CrudViewScreen
+    :screen="screen"
+    resource-singular-title="Book"
+    resource-plural-title="Books"
+  >
+    <template #actions>
+      <CrudDeleteAction :action="deleteAction" resource-singular-title="Book" />
+    </template>
+
+    <template #fields="{ view }">
+      <v-col cols="12" md="6">
+        <div class="text-caption text-medium-emphasis">Author</div>
+        <div class="text-body-1">{{ view.record?.author }}</div>
+      </v-col>
+      <v-col cols="12">
+        <div class="text-caption text-medium-emphasis">Notes</div>
+        <div class="text-body-1 text-pre-wrap">{{ view.record?.notes || "No notes" }}</div>
+      </v-col>
+    </template>
+  </CrudViewScreen>
+</template>

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/formFields.js

@@ -0,0 +1,31 @@
+const bookFormFields = Object.freeze([
+  Object.freeze({
+    key: "title",
+    label: "Title",
+    type: "string",
+    nullable: false,
+    inputType: "text",
+    component: "text",
+    maxLength: 255
+  }),
+  Object.freeze({
+    key: "author",
+    label: "Author",
+    type: "string",
+    nullable: false,
+    inputType: "text",
+    component: "text",
+    maxLength: 255
+  }),
+  Object.freeze({
+    key: "notes",
+    label: "Notes",
+    type: "string",
+    nullable: true,
+    inputType: "textarea",
+    component: "textarea",
+    maxLength: 65535
+  })
+]);
+
+export { bookFormFields };

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/listExtensions.js

@@ -0,0 +1,9 @@
+import { defineCrudListBulkActions } from "@jskit-ai/http-web/client/bulkActions";
+import { defineCrudListFilters } from "@jskit-ai/http-web/client/filters";
+import { defineCrudListRowActions } from "@jskit-ai/http-web/client/rowActions";
+
+const listFilters = defineCrudListFilters({});
+const listBulkActions = defineCrudListBulkActions([]);
+const listRowActions = defineCrudListRowActions([]);
+
+export { listBulkActions, listFilters, listRowActions };

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

@@ -0,0 +1,160 @@
+---
+id: crud/json-api-resource-package
+title: JSON API CRUD resource package
+summary: Build a complete application-owned CRUD server package from a migration, resource contract, and one framework module declaration.
+keywords: actions, crud, database, json-api, migration, permissions, provider, repository, routes, service
+requires: @jskit-ai/crud-core, @jskit-ai/resource-crud-core
+---
+
+# JSON API CRUD resource package
+
+## Use when
+
+Use this pattern when a product entity needs conventional JSON API list, view,
+create, patch, and delete behavior. JSKIT owns the repeated repository, service,
+action, route, and provider mechanics. The application owns the migration,
+resource contract, access surface, ownership policy, and package composition.
+
+## Do not use when
+
+Do not use this pattern for a command-oriented workflow, aggregate, import job,
+multi-resource transaction, or domain with materially different operations.
+Use a feature package and explicit services for those cases.
+
+## Product decisions
+
+Decide the entity fields, validation, search, sorting, access surface, ownership,
+enabled operations, route name, permissions, and user-facing messages. Author
+those decisions in normal migration and resource source. Do not derive them
+from a generator questionnaire or treat a live table as the sole contract.
+
+## Invariants
+
+- Migration and resource storage metadata describe the same table.
+- `apiAccess`, surface access, and `autofilter` agree.
+- Public routes use public ownership only.
+- Workspace routes receive explicit scope validators and route-to-action input.
+- Application source contains one module declaration, not copied generic CRUD
+  repository, service, action, route, and provider files.
+- Current migration/resource/source state is authoritative; there is no receipt,
+  provenance marker, generator identity, or field-patching lane.
+
+## Framework APIs
+
+Use `defineCrudResource()` from `@jskit-ai/resource-crud-core` and
+`defineCrudJsonApiFeature()` from `@jskit-ai/crud-core`. The latter composes the
+JSON REST resource, repository, service events, standard CRUD actions, route
+contracts, access policy, and HTTP routes.
+
+## Example files
+
+`example/` contains a complete books package plus a source-controlled migration.
+`BooksFeature.js` is deliberately tiny: it binds the readable resource contract
+to the framework module and exports the resulting provider.
+
+## Variation points
+
+Change the package name, resource fields, table, surface, ownership filter,
+relative route, messages, and migration. Supply explicit permissions when the
+surface uses named policy. For workspace ownership, add the workspace route and
+action validators through the module's `scope` option. The feature exposes the
+operations declared by the resource. Use `operations` only to narrow that
+surface further; do not register unused mutation actions and routes. Use
+`routes: false` only for an internal
+capability/action surface that deliberately has no HTTP API.
+
+When otherwise-standard CRUD earns product behavior, name the exact
+capabilities in `requires` and provide `decorateService({ service, repository,
+resource, ...dependencies })`. Retain the standard methods, override only the
+methods whose CRUD behavior changes, and add resource-related domain methods
+such as `confirmBooking()` or `sendReminder()` directly to that service. Those
+additional methods remain available through the resource capability. When the
+product needs only a few additional queries or locking operations, provide
+`decorateRepository({ repository, database, http, jsonRestApi, resource,
+...dependencies })`; return the standard methods plus only those unique
+persistence operations instead of copying the CRUD repository.
+
+Use `operationLifecycle` for behavior surrounding a standard operation. Its
+per-operation `before`, `execute`, and `after` phases share one repository
+transaction for create, update, and delete. An `execute` hook receives
+`standard(nextInput)` so it can retain the framework write while adjusting its
+input or coordinating other repository work. `afterCommit` runs only after the
+mutation transaction succeeds. Put durable external delivery behind an outbox
+written inside the transaction; do not make an email or webhook the arbiter of
+whether an already-committed request appears successful.
+
+Declare resource-related non-CRUD commands in `actions`. Each named action has
+a normal JSKIT input, permission, audit, events, and `execute({ input, context,
+service, repository, ...dependencies })` contract. Its optional `route`
+declares an HTTP method, path below the resource base, explicit route contract,
+status code, and optional request-to-action input mapper. This is the normal
+home for `confirm`, `publish`, `cancel`, `reorder`, or `sendReminder`. Move to a
+separate explicit feature only when the operation belongs to another domain or
+the resource is no longer principally CRUD.
+
+If a product-specific list filter needs additional transport validation and
+JSON API search mapping, pass its validator as `listFilterQueryValidator` and
+its storage mapping as `searchSchema`; keep that contract next to the feature.
+Use `operationInputs.create` or `operationInputs.update` when a standard CRUD
+operation intentionally accepts a small virtual product field that is handled
+by the service decorator rather than stored on the resource row.
+
+```js
+const BookingsFeature = defineCrudJsonApiFeature({
+  resource: bookingResource,
+  surface: "app",
+  decorateService({ service, repository }) {
+    return {
+      ...service,
+      async confirmBooking(recordId, options) {
+        return repository.confirmBooking(recordId, options);
+      }
+    };
+  },
+  operationLifecycle: {
+    update: {
+      async before({ input, service, trx, context }) {
+        await service.assertUpdateAllowed(input.recordId, { trx, context });
+      },
+      async afterCommit({ result, service, context }) {
+        await service.recordUpdateCompleted(result.data.id, { context });
+      }
+    }
+  },
+  actions: {
+    confirm: {
+      input: confirmBookingInput,
+      permission: { require: "all", permissions: ["bookings.confirm"] },
+      execute({ input, context, service }) {
+        return service.confirmBooking(input.recordId, { context });
+      },
+      route: {
+        method: "POST",
+        path: "/:recordId/confirm",
+        contract: confirmBookingRouteContract,
+        statusCode: 200
+      }
+    }
+  }
+});
+```
+
+## Verification
+
+- Rebuild the table from migrations in disposable MySQL and PostgreSQL databases
+  when both drivers are supported by the application.
+- Validate representative accepted and rejected resource values.
+- Exercise every enabled route and JSON API document shape.
+- Prove positive owner access and negative cross-owner access.
+- Verify public routes require neither identity nor CSRF only when explicitly
+  declared public.
+- Run the package tests and application verifier.
+
+## Avoid
+
+- copied generic repository/service/action/route/provider boilerplate
+- generator subcommands for adding fields
+- editing an applied baseline migration instead of adding a new migration
+- public access combined with user or workspace ownership
+- implicit workspace route parameters or permissions
+- receipt, replay, provenance, ownership-marker, or scaffold-shape files

package/skills/jskit/references/patterns/crud/json-api-resource-package/example/migrations/20260815000000_books.cjs

@@ -0,0 +1,22 @@
+const TABLE_NAME = "books";
+
+exports.up = async function up(knex) {
+  if (await knex.schema.hasTable(TABLE_NAME)) {
+    return;
+  }
+
+  await knex.schema.createTable(TABLE_NAME, (table) => {
+    table.bigIncrements("id").primary();
+    table.bigInteger("user_id").unsigned().notNullable().index()
+      .references("id").inTable("users").onDelete("CASCADE");
+    table.string("title", 255).notNullable();
+    table.string("author", 255).notNullable();
+    table.text("notes").nullable();
+    table.timestamp("created_at", { useTz: false }).notNullable().defaultTo(knex.fn.now());
+    table.timestamp("updated_at", { useTz: false }).notNullable().defaultTo(knex.fn.now());
+  });
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists(TABLE_NAME);
+};

package/skills/jskit/references/patterns/crud/json-api-resource-package/example/packages/books/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@app/books",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    "./server/BooksFeature": "./src/server/BooksFeature.js",
+    "./shared": "./src/shared/index.js"
+  },
+  "dependencies": {
+    "@jskit-ai/crud-core": "0.1.190",
+    "@jskit-ai/resource-crud-core": "0.1.121"
+  },
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "app.books"
+      ],
+      "requires": [
+        "runtime.http",
+        "runtime.json-rest-api",
+        "runtime.actions",
+        "runtime.database"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": [
+          {
+            "entrypoint": "src/server/BooksFeature.js",
+            "export": "BooksFeature"
+          }
+        ]
+      },
+      "client": {
+        "providers": []
+      }
+    }
+  }
+}

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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,83 @@
+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

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

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

@@ -0,0 +1,102 @@
+---
+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.
+- Output, create, and patch participation is explicit on each product field.
+- 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.
+
+## 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