@jskit-ai/agent-docs 0.1.148 → 0.1.150

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

@@ -0,0 +1,54 @@
+<script setup>
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+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 route = useRoute();
+const routeRecordId = computed(() => String(route.params.bookId || "").trim());
+
+const screen = useCrudAddEditScreen({
+  mode: "edit",
+  title: "Edit book",
+  subtitle: "Update this catalogue entry.",
+  saveLabel: "Save changes",
+  cancelTo: "/books/:bookId",
+  preserveCancelQuery: true,
+  resource: bookResource,
+  operationName: "patch",
+  formFields: bookFormFields,
+  addEditOptions: {
+    apiUrlTemplate: "/books/:bookId",
+    placementSource: "crud.books.edit",
+    writeMethod: "PATCH",
+    requestRecoveryLabel: "Book",
+    fallbackLoadError: "Unable to load this book.",
+    fallbackSaveError: "Unable to save this book.",
+    recordIdParam: "bookId",
+    routeRecordId,
+    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/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,54 @@
+<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"
+    title-label="Books"
+    heading-title="My books"
+    subtitle="Search and maintain your catalogue."
+    create-label="Add book"
+    empty-title="No books yet"
+    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,45 @@
+<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",
+  title: "Add book",
+  subtitle: "Add a book to your catalogue.",
+  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,50 @@
+<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"
+    description="Review this catalogue entry."
+  >
+    <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.189",
+    "@jskit-ai/resource-crud-core": "0.1.120"
+  },
+  "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";