@jskit-ai/agent-docs 0.1.148 → 0.1.150

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

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

@@ -0,0 +1,87 @@
+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/database/mysql-application/PATTERN.md

@@ -0,0 +1,80 @@
+---
+id: database/mysql-application
+title: MySQL application database
+summary: Configure a JSKIT application for MySQL with a fixed driver, ordinary environment values, and rebuildable Knex migrations.
+keywords: database, knex, mariadb, migrations, mysql, mysql2
+requires: @jskit-ai/database-runtime-mysql
+---
+
+# MySQL application database
+
+## Use when
+
+Use this pattern when an application deliberately chooses MySQL or MariaDB.
+Install `@jskit-ai/database-runtime-mysql`; its normal npm dependencies provide
+the database runtime, Knex, and `mysql2` without a package-setup wizard.
+
+## Do not use when
+
+Do not use this pattern for PostgreSQL, a database-neutral library, or a service
+that does not own its database connection. Do not install both JSKIT drivers
+unless the application genuinely selects between them at runtime.
+
+## Product decisions
+
+Decide the database name, credentials, host, deployment secret source, backup
+policy, and application migrations. Those are application and environment
+decisions, not framework questions.
+
+## Invariants
+
+- The application depends directly on the selected JSKIT driver.
+- Credentials stay outside Git.
+- `knexfile.js` fixes `mysql2`; a single-driver application does not require
+  `DB_CLIENT`.
+- Schema changes are ordinary immutable migrations.
+- The current package graph, environment, and migrations are authoritative.
+
+## Framework APIs
+
+Use `createKnexMigrationConfigFromApp()` from
+`@jskit-ai/database-runtime/server/knexMigrationConfig`. The running JSKIT
+application automatically selects the sole installed database driver, while
+Knex discovers package-owned migrations from the installed dependency graph.
+
+## Example files
+
+`example/package.json` contains the runtime dependency and database scripts.
+`example/knexfile.js` loads an optional local `.env` and fixes the MySQL dialect.
+`example/scripts/prepare-database.js` is the portable migrate-then-seed
+entrypoint for managed sessions and deployments. `example/.env.example` names
+the five connection values without a secret.
+
+## Variation points
+
+Change scripts, migration location, connection values, and secret injection to
+fit the application. Supply `DATABASE_URL` instead of individual values when
+the environment owns a URL. Add `DB_CLIENT=mysql2` only when a shared external
+tool explicitly needs a dialect selector. When the product needs initial data,
+import one idempotent app-owned seed function in `prepare-database.js` and pass
+it as `seed` to `prepareDatabaseFromApp()`.
+
+## Verification
+
+- Install dependencies once with `npm install`.
+- Run `npm run db:prepare` against a fresh disposable database.
+- Run `npm run db:migrate:status` and the application verification command.
+- Exercise one transaction and one negative connection case.
+- When a seed exists, run `db:prepare` twice and require the second run to be safe.
+
+`example/.github/workflows/verify.yml` is a normal app-owned CI workflow with
+an explicit MariaDB service. Adapt it as source rather than generating it from
+package metadata.
+
+## Avoid
+
+- framework questionnaires for credentials
+- generated `.env` secrets
+- depending on a live schema as the source contract
+- a second driver installed “just in case”
+- migration receipts, provenance, replay logs, or generator ownership

package/skills/jskit/references/patterns/database/mysql-application/example/.env.example

@@ -0,0 +1,5 @@
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=application
+DB_USER=application
+DB_PASSWORD=replace-me

package/skills/jskit/references/patterns/database/mysql-application/example/.github/workflows/verify.yml

@@ -0,0 +1,39 @@
+name: Verify
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    services:
+      mariadb:
+        image: mariadb:11.4
+        env:
+          MARIADB_DATABASE: app_test
+          MARIADB_USER: app_test
+          MARIADB_PASSWORD: app_test_password
+          MARIADB_ROOT_PASSWORD: root_test_password
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="healthcheck.sh --connect --innodb_initialized"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+    env:
+      DB_HOST: 127.0.0.1
+      DB_PORT: 3306
+      DB_NAME: app_test
+      DB_USER: app_test
+      DB_PASSWORD: app_test_password
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - run: npm ci
+      - run: npm run db:migrate
+      - run: npm run verify

package/skills/jskit/references/patterns/database/mysql-application/example/knexfile.js

@@ -0,0 +1,11 @@
+import { createKnexMigrationConfigFromApp } from "@jskit-ai/database-runtime/server/knexMigrationConfig";
+
+try {
+  process.loadEnvFile?.(".env");
+} catch (error) {
+  if (error?.code !== "ENOENT") {
+    throw error;
+  }
+}
+
+export default await createKnexMigrationConfigFromApp({ client: "mysql2" });

package/skills/jskit/references/patterns/database/mysql-application/example/package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "db:prepare": "node ./scripts/prepare-database.js",
+    "db:migrate": "knex --knexfile ./knexfile.js migrate:latest",
+    "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
+    "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
+  },
+  "dependencies": {
+    "@jskit-ai/database-runtime-mysql": "0.1.176"
+  }
+}

package/skills/jskit/references/patterns/database/mysql-application/example/scripts/prepare-database.js

@@ -0,0 +1,3 @@
+import { prepareDatabaseFromApp } from "@jskit-ai/database-runtime/server/databaseSetup";
+
+await prepareDatabaseFromApp({ client: "mysql2" });

package/skills/jskit/references/patterns/database/postgres-application/PATTERN.md

@@ -0,0 +1,80 @@
+---
+id: database/postgres-application
+title: PostgreSQL application database
+summary: Configure a JSKIT application for PostgreSQL with a fixed driver, ordinary environment values, and rebuildable Knex migrations.
+keywords: database, knex, migrations, pg, postgres, postgresql
+requires: @jskit-ai/database-runtime-postgres
+---
+
+# PostgreSQL application database
+
+## Use when
+
+Use this pattern when an application deliberately chooses PostgreSQL. Install
+`@jskit-ai/database-runtime-postgres`; its normal npm dependencies provide the
+database runtime, Knex, and `pg` without a package-setup wizard.
+
+## Do not use when
+
+Do not use this pattern for MySQL, a database-neutral library, or a service that
+does not own its database connection. Do not install both JSKIT drivers unless
+the application genuinely selects between them at runtime.
+
+## Product decisions
+
+Decide the database name, credentials, host, deployment secret source, backup
+policy, and application migrations. Those are application and environment
+decisions, not framework questions.
+
+## Invariants
+
+- The application depends directly on the selected JSKIT driver.
+- Credentials stay outside Git.
+- `knexfile.js` fixes `pg`; a single-driver application does not require
+  `DB_CLIENT`.
+- Schema changes are ordinary immutable migrations.
+- The current package graph, environment, and migrations are authoritative.
+
+## Framework APIs
+
+Use `createKnexMigrationConfigFromApp()` from
+`@jskit-ai/database-runtime/server/knexMigrationConfig`. The running JSKIT
+application automatically selects the sole installed database driver, while
+Knex discovers package-owned migrations from the installed dependency graph.
+
+## Example files
+
+`example/package.json` contains the runtime dependency and database scripts.
+`example/knexfile.js` loads an optional local `.env` and fixes the PostgreSQL
+dialect. `example/scripts/prepare-database.js` is the portable
+migrate-then-seed entrypoint for managed sessions and deployments.
+`example/.env.example` names the five connection values without a secret.
+
+## Variation points
+
+Change scripts, migration location, connection values, and secret injection to
+fit the application. Supply `DATABASE_URL` instead of individual values when
+the environment owns a URL. Add `DB_CLIENT=pg` only when a shared external tool
+explicitly needs a dialect selector. When the product needs initial data,
+import one idempotent app-owned seed function in `prepare-database.js` and pass
+it as `seed` to `prepareDatabaseFromApp()`.
+
+## Verification
+
+- Install dependencies once with `npm install`.
+- Run `npm run db:prepare` against a fresh disposable database.
+- Run `npm run db:migrate:status` and the application verification command.
+- Exercise one transaction and one negative connection case.
+- When a seed exists, run `db:prepare` twice and require the second run to be safe.
+
+`example/.github/workflows/verify.yml` is a normal app-owned CI workflow with
+an explicit PostgreSQL service. Adapt it as source rather than generating it
+from package metadata.
+
+## Avoid
+
+- framework questionnaires for credentials
+- generated `.env` secrets
+- depending on a live schema as the source contract
+- a second driver installed “just in case”
+- migration receipts, provenance, replay logs, or generator ownership

package/skills/jskit/references/patterns/database/postgres-application/example/.env.example

@@ -0,0 +1,5 @@
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_NAME=application
+DB_USER=application
+DB_PASSWORD=replace-me

package/skills/jskit/references/patterns/database/postgres-application/example/.github/workflows/verify.yml

@@ -0,0 +1,38 @@
+name: Verify
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_DB: app_test
+          POSTGRES_USER: app_test
+          POSTGRES_PASSWORD: app_test_password
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U app_test -d app_test"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+    env:
+      DB_HOST: 127.0.0.1
+      DB_PORT: 5432
+      DB_NAME: app_test
+      DB_USER: app_test
+      DB_PASSWORD: app_test_password
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - run: npm ci
+      - run: npm run db:migrate
+      - run: npm run verify

package/skills/jskit/references/patterns/database/postgres-application/example/knexfile.js

@@ -0,0 +1,11 @@
+import { createKnexMigrationConfigFromApp } from "@jskit-ai/database-runtime/server/knexMigrationConfig";
+
+try {
+  process.loadEnvFile?.(".env");
+} catch (error) {
+  if (error?.code !== "ENOENT") {
+    throw error;
+  }
+}
+
+export default await createKnexMigrationConfigFromApp({ client: "pg" });

package/skills/jskit/references/patterns/database/postgres-application/example/package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "db:prepare": "node ./scripts/prepare-database.js",
+    "db:migrate": "knex --knexfile ./knexfile.js migrate:latest",
+    "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
+    "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
+  },
+  "dependencies": {
+    "@jskit-ai/database-runtime-postgres": "0.1.175"
+  }
+}

package/skills/jskit/references/patterns/database/postgres-application/example/scripts/prepare-database.js

@@ -0,0 +1,3 @@
+import { prepareDatabaseFromApp } from "@jskit-ai/database-runtime/server/databaseSetup";
+
+await prepareDatabaseFromApp({ client: "pg" });

package/skills/jskit/references/patterns/mobile/android-application/PATTERN.md

@@ -0,0 +1,71 @@
+---
+id: mobile/android-application
+title: Capacitor Android application
+summary: Wrap a JSKIT web application in a Capacitor Android shell using native Capacitor and Android commands.
+keywords: android, capacitor, device, mobile, native, shell, webview
+requires: @jskit-ai/mobile-capacitor, @capacitor/android, @capacitor/app, @capacitor/cli
+---
+
+# Capacitor Android application
+
+## Use when
+
+Use this pattern when the same JSKIT application should run inside a Capacitor
+Android shell and the product accepts a WebView-based native application.
+
+## Do not use when
+
+Do not use this pattern for a browser-only app, for a native UI product, or when
+the target platform is not supported by the selected Capacitor packages.
+
+## Product decisions
+
+Choose the stable application id, display name, built web directory, callback
+URLs, development server policy, and native permissions before creating the
+Android project.
+
+## Framework APIs
+
+Install the declared npm packages normally. Adapt `example/capacitor.config.json`
+into valid JSON, then use Capacitor directly:
+
+```text
+npx cap add android
+npm run build
+npx cap sync android
+npx cap run android
+```
+
+Use `adb devices`, `adb reverse`, Android Studio, and Gradle directly for device
+selection, tunnelling, diagnostics, and release builds. JSKIT does not wrap
+those tools in another command language.
+
+## Example files
+
+`example/capacitor.config.json` shows the small Capacitor configuration shape.
+Replace its obvious values directly; it is not an interpolation template.
+
+## Variation points
+
+Change application id/name, build directory, development server, callback URLs,
+plugins, native permissions, and platform-specific release configuration.
+
+## Invariants
+
+- `webDir` is the actual output of the application's production build.
+- Development origins are explicit and never leak into release configuration.
+- Browser navigation that leaves the app uses the package's public mobile
+  routing capability.
+- Native projects and signing configuration are ordinary app-owned source.
+
+## Verification
+
+Build the web application, sync Android, launch on an explicit device, test
+callback routing and external links, then build the native release variant.
+
+## Avoid
+
+- hidden device selection
+- checking secrets or signing keys into source
+- a JSKIT-specific wrapper around Capacitor, adb, or Gradle
+- generated-operation receipts

package/skills/jskit/references/patterns/mobile/android-application/example/capacitor.config.json

@@ -0,0 +1,10 @@
+{
+  "appId": "__JSKIT_MOBILE_CAPACITOR_APP_ID__",
+  "appName": "__JSKIT_MOBILE_CAPACITOR_APP_NAME__",
+  "webDir": "__JSKIT_MOBILE_CAPACITOR_WEB_DIR__"__JSKIT_MOBILE_CAPACITOR_SERVER_BLOCK__,
+  "plugins": {
+    "CapacitorHttp": {
+      "enabled": true
+    }
+  }
+}

package/skills/jskit/references/patterns/realtime/realtime-application/PATTERN.md

@@ -0,0 +1,69 @@
+---
+id: realtime/realtime-application
+title: Realtime application
+summary: Add JSKIT realtime events with an optional Redis backplane and an explicit shell status contribution.
+keywords: redis, realtime, socket.io, sockets, status, websocket
+requires: @jskit-ai/realtime, @jskit-ai/shell-web
+---
+
+# Realtime application
+
+## Use when
+
+Use this pattern when the product needs server-to-client events or live query
+refresh. Install the realtime package normally, then add only the product's
+listeners and desired shell contribution.
+
+## Do not use when
+
+Do not add realtime merely to poll less often, or before event ownership and
+delivery semantics are clear. A single-process application does not need Redis.
+
+## Product decisions
+
+Decide which events are public contracts, their scopes and payloads, reconnect
+behavior, whether a connection indicator belongs in the UI, and whether the
+deployment needs a Redis backplane.
+
+## Invariants
+
+- Empty `REALTIME_REDIS_URL` means the in-process adapter.
+- Redis credentials stay outside Git.
+- Listeners are registered through the public provider seams.
+- The status indicator is an explicit app placement, not a source mutation.
+- Event payloads do not become an undocumented second API.
+
+## Framework APIs
+
+Server features declare their successful domain events on their actions. The
+installed `RealtimeProvider` delivers only events with an explicit realtime
+name and audience. Client features use `RealtimeClientProvider` and the public
+listener registration helpers from `@jskit-ai/realtime`. Use the normal shell
+placement registry for the optional status component.
+
+## Example files
+
+`example/package.json` declares realtime and shell runtime packages.
+`example/.env.example` documents the optional Redis input.
+`example/src/placement.js` adds the standard connection indicator explicitly.
+
+## Variation points
+
+Omit the placement when the product does not need a visible connection state.
+Change event listeners, Redis provisioning, and client invalidation behavior to
+match the product. Keep transport retry policy in the realtime runtime.
+
+## Verification
+
+- Test in-process delivery without Redis.
+- When Redis is selected, test delivery across two server processes.
+- Disconnect and reconnect a browser and verify recovery behavior.
+- Confirm the status contribution renders in compact and expanded shells.
+
+## Avoid
+
+- prompting for optional Redis configuration during package installation
+- appending source into placement files
+- leaking Redis values to client config
+- generic “data changed” payloads with no scope
+- receipts, provenance, or mutation history

package/skills/jskit/references/patterns/realtime/realtime-application/example/.env.example

@@ -0,0 +1 @@
+REALTIME_REDIS_URL=

package/skills/jskit/references/patterns/realtime/realtime-application/example/package.json

@@ -0,0 +1,8 @@
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@jskit-ai/realtime": "0.1.175",
+    "@jskit-ai/shell-web": "0.1.182"
+  }
+}