@jskit-ai/agent-docs 0.1.149 → 0.1.150

package/skills/jskit/references/patterns/realtime/realtime-application/example/src/placement.js

@@ -0,0 +1,17 @@
+import { createPlacementRegistry } from "@jskit-ai/shell-web/client/placement";
+
+const registry = createPlacementRegistry();
+const { addPlacement } = registry;
+
+addPlacement({
+  id: "realtime.connection.indicator",
+  target: "shell.status",
+  kind: "component",
+  surfaces: ["*"],
+  order: 950,
+  componentToken: "realtime.web.connection.indicator"
+});
+
+export default function getPlacements() {
+  return registry.build();
+}

package/skills/jskit/references/patterns/server/feature-package/PATTERN.md

@@ -0,0 +1,108 @@
+---
+id: server/feature-package
+title: App-local server feature package
+summary: Define a server feature through explicit capabilities and first-class actions, adding services or repositories only when its domain earns them.
+keywords: actions, feature, json-rest, knex, orchestration, package, provider, repository, routes, server
+requires: @jskit-ai/kernel
+---
+
+# App-local server feature package
+
+## Use when
+
+Use this pattern when a server capability has its own product language and
+should not grow inside `packages/main`. It shows the smallest normal shape: a
+feature declaration, named capability inputs and outputs, and first-class
+actions whose implementations capture those exact dependencies.
+
+The concrete `booking-engine` example is intentionally repository-free. The
+`variations/` directory preserves the two important escalations: a meaningful
+orchestration service and an explicit custom Knex repository for a domain that
+cannot fit the normal resource APIs.
+
+## Do not use when
+
+Do not create a package for a tiny composition callback or one route with no
+domain behavior. Use the CRUD resource patterns when ordinary resource
+operations fit. Do not select custom Knex merely because SQL is familiar; it
+is an explicit exception for persistence behavior the higher-level APIs cannot
+express.
+
+## Product decisions
+
+Decide the feature's public operations, access surface, authentication policy,
+input and output contracts, transactional boundary, and whether it truly owns
+persistence. Decide whether HTTP routes are needed or another package will call
+its actions internally. These decisions come from the product, not a JSKIT
+questionnaire.
+
+## Invariants
+
+- `packages/main` composes the application; substantial feature logic lives in
+  the feature package.
+- `defineFeature()` receives only declared capabilities and returns only
+  declared feature APIs.
+- Actions define the public operation contract and close over the feature APIs
+  they need. They never resolve arbitrary dependencies at execution time.
+- The service orchestrates the feature and does not issue SQL directly.
+- A repository owns persistence and accepts transaction/context options.
+- The normal persistence lane uses a public or documented high-level resource
+  API; custom Knex is an explicit, reviewed exception.
+- Ordinary HTTP and assistant exposure is projected from actions. Explicit
+  route code exists only for a genuinely custom transport.
+- Register routes, actions, contributors, and other catalogue entries during
+  `setup()`. Runtime catalogues may be sealed before provider `boot()` begins.
+  Reserve `boot()` for starting long-lived work such as consumers, schedulers,
+  or notification loops after the application structure is complete.
+- Application source contains no scaffold-shape, lane, provenance, receipt, or
+  authoring-history metadata.
+
+## Framework APIs
+
+The provider uses `defineFeature()` from
+`@jskit-ai/kernel/server/features`. The runtime supplies named capabilities
+and the feature publishes its actions through the dedicated action catalogue.
+The custom persistence variation uses `createWithTransaction()` from
+`@jskit-ai/database-runtime/shared`.
+
+## Example files
+
+`example/booking-engine/` is a concrete app-local package showing the preferred
+small-feature boundary. Its status query is deliberately small: product logic
+can grow inside the returned feature API without creating ceremonial layers.
+
+`example/variations/AvailabilityEngineProvider.js` and
+`example/variations/orchestratorService.js` show the repository-free lane.
+`example/variations/InvoiceRollupProvider.js` and
+`example/variations/customKnexRepository.js` show the explicit custom
+persistence lane.
+
+## Variation points
+
+Rename the package, capability id, actions, validators, and domain methods.
+Select the correct channels and surfaces in `actionDefaults`, overriding them
+only for exceptional actions. Add a service when orchestration is shared or
+stateful. Add a repository only when the feature owns persistence. Replace the
+illustrative status query with narrow product language before shipping.
+
+## Verification
+
+- Import the feature and verify its declared capability inputs and outputs.
+- Exercise actions through the action runtime, including invalid input and
+  denied access.
+- Exercise HTTP routes only when the package owns them.
+- Test service orchestration independently from persistence.
+- Test repository transaction and context forwarding.
+- Rebuild any schema from immutable migrations in a disposable database.
+- Run the app's package, server, and integration verification.
+
+## Avoid
+
+- product logic in the provider or `packages/main`
+- registering routes or action catalogue entries from `boot()`
+- direct SQL in actions, routes, or services
+- a repository for an orchestration-only feature
+- generic `execute(anything)` operations in finished product code
+- `app.make()`, `scope.make()`, container tokens, or service-location helpers
+- metadata claiming which authoring tool or pattern created the package
+- field questionnaires, overwrite switches, or durable operation records

package/skills/jskit/references/patterns/server/feature-package/example/booking-engine/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@local/booking-engine",
+  "version": "0.1.0",
+  "description": "App-local booking orchestration package.",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@jskit-ai/kernel": "0.1.178",
+    "json-rest-schema": "^1.0.17"
+  },
+  "exports": {
+    "./server/actions": "./src/server/actions.js"
+  },
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "feature.booking-engine"
+      ],
+      "requires": [
+        "runtime.actions"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": [
+          {
+            "entrypoint": "src/server/BookingEngineProvider.js",
+            "export": "BookingEngineProvider"
+          }
+        ]
+      },
+      "client": {
+        "providers": []
+      }
+    },
+    "metadata": {
+      "apiSummary": {
+        "surfaces": [
+          {
+            "subpath": "./server/actions",
+            "summary": "Exports booking-engine action definitions."
+          }
+        ]
+      }
+    }
+  }
+}

package/skills/jskit/references/patterns/server/feature-package/example/booking-engine/src/server/BookingEngineProvider.js

@@ -0,0 +1,33 @@
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { createActions } from "./actions.js";
+
+const BookingEngineProvider = defineFeature({
+  id: "feature.booking-engine",
+  domain: "booking",
+  provides: {
+    bookingEngine: "feature.booking-engine"
+  },
+  actionDefaults: {
+    channels: ["api", "assistant", "internal"],
+    surfaces: ["app"]
+  },
+  setup() {
+    return {
+      bookingEngine: Object.freeze({
+        async readStatus(input = {}) {
+          return {
+            ok: true,
+            feature: "booking-engine",
+            scope: input.scope || "default",
+            verbose: input.verbose === true
+          };
+        }
+      })
+    };
+  },
+  actions({ bookingEngine }) {
+    return createActions({ bookingEngine });
+  }
+});
+
+export { BookingEngineProvider };

package/skills/jskit/references/patterns/server/feature-package/example/booking-engine/src/server/actions.js

@@ -0,0 +1,26 @@
+import { statusQueryInputValidator } from "./inputSchemas.js";
+
+const ACTION_GET_STATUS = "feature.booking-engine.status.read";
+function createActions({ bookingEngine } = {}) {
+  if (!bookingEngine || typeof bookingEngine.readStatus !== "function") {
+    throw new TypeError("createActions requires bookingEngine.readStatus().");
+  }
+
+  return Object.freeze([
+    {
+      id: ACTION_GET_STATUS,
+      version: 1,
+      kind: "query",
+      input: statusQueryInputValidator,
+      output: null,
+      idempotency: "none",
+      audit: { actionName: ACTION_GET_STATUS },
+      observability: {},
+      async execute(input) {
+        return bookingEngine.readStatus(input);
+      }
+    }
+  ]);
+}
+
+export { ACTION_GET_STATUS, createActions };

package/skills/jskit/references/patterns/server/feature-package/example/booking-engine/src/server/inputSchemas.js

@@ -0,0 +1,19 @@
+import { deepFreeze } from "@jskit-ai/kernel/shared/support/deepFreeze";
+import { createSchema } from "json-rest-schema";
+
+const statusQueryInputValidator = deepFreeze({
+  schema: createSchema({
+    scope: {
+      type: "string",
+      required: false,
+      minLength: 1
+    },
+    verbose: {
+      type: "boolean",
+      required: false
+    }
+  }),
+  mode: "patch"
+});
+
+export { statusQueryInputValidator };

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

@@ -0,0 +1,31 @@
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { emptyInputValidator } from "@jskit-ai/kernel/shared/actions/actionContributorHelpers";
+import { createService } from "./orchestratorService.js";
+
+const AvailabilityEngineProvider = defineFeature({
+  id: "feature.availability-engine",
+  domain: "availability",
+  provides: {
+    availabilityEngine: "feature.availability-engine"
+  },
+  actionDefaults: {
+    channels: ["api", "assistant", "internal"],
+    surfaces: ["app"]
+  },
+  setup() {
+    return { availabilityEngine: createService() };
+  },
+  actions({ availabilityEngine }) {
+    return [{
+      id: "availability.status.read",
+      kind: "query",
+      input: emptyInputValidator,
+      idempotency: "none",
+      async execute(input) {
+        return availabilityEngine.getStatus(input);
+      }
+    }];
+  }
+});
+
+export { AvailabilityEngineProvider };

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

@@ -0,0 +1,36 @@
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { emptyInputValidator } from "@jskit-ai/kernel/shared/actions/actionContributorHelpers";
+import { createRepository } from "./repository.js";
+
+const InvoiceRollupProvider = defineFeature({
+  id: "feature.invoice-rollup",
+  domain: "invoices",
+  requires: {
+    database: "runtime.database"
+  },
+  provides: {
+    invoiceRollup: "feature.invoice-rollup"
+  },
+  actionDefaults: {
+    channels: ["api", "assistant", "internal"],
+    surfaces: ["admin"]
+  },
+  setup({ database }) {
+    return {
+      invoiceRollup: createRepository({ knex: database.knex })
+    };
+  },
+  actions({ invoiceRollup }) {
+    return [{
+      id: "invoices.rollup.status.read",
+      kind: "query",
+      input: emptyInputValidator,
+      idempotency: "none",
+      async execute(input, context) {
+        return invoiceRollup.getStatus(input, { context });
+      }
+    }];
+  }
+});
+
+export { InvoiceRollupProvider };

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

@@ -0,0 +1,34 @@
+import { createWithTransaction } from "@jskit-ai/database-runtime/shared";
+
+function createRepository({ knex } = {}) {
+  if (!knex) {
+    throw new TypeError("createRepository requires knex.");
+  }
+
+  return Object.freeze({
+    withTransaction: createWithTransaction(knex),
+    async getStatus(input = {}, options = {}) {
+      return {
+        ok: true,
+        feature: "invoice-rollup",
+        persistence: "custom-knex",
+        tableName: "invoice_rollups",
+        hasTransaction: Boolean(options.trx),
+        input
+      };
+    },
+    async 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."
+      };
+    }
+  });
+}
+
+export { createRepository };

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

@@ -0,0 +1,23 @@
+function createService() {
+  return Object.freeze({
+    async getStatus(input = {}) {
+      return {
+        ok: true,
+        feature: "availability-engine",
+        mode: "orchestrator",
+        input
+      };
+    },
+    async execute(input = {}) {
+      return {
+        accepted: false,
+        feature: "availability-engine",
+        mode: "orchestrator",
+        input,
+        message: "Replace this example with calls to the feature's injected collaborators."
+      };
+    }
+  });
+}
+
+export { createService };

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

@@ -0,0 +1,66 @@
+---
+id: shell/application-shell
+title: Responsive application shell
+summary: Compose the JSKIT responsive shell, semantic placements, settings navigation, and accessible adaptive-shell browser checks.
+keywords: adaptive, app, layout, navigation, placement, responsive, settings, shell
+requires: @jskit-ai/kernel, @jskit-ai/shell-web
+---
+
+# Responsive application shell
+
+## Use when
+
+Use this pattern when adding the standard responsive JSKIT shell to an existing
+application foundation.
+
+## Do not use when
+
+Do not copy the entire shell into an application that already has a coherent
+JSKIT shell. Use the narrower page-and-placement pattern for incremental UI.
+
+## Product decisions
+
+Choose the product navigation, settings sections, surfaces, labels, icons, and
+which controls remain visible at compact, medium, and expanded widths.
+
+## Framework APIs
+
+Use the shell provider, `ShellLayout`, `ShellOutlet`, link components,
+placement registry, topology, and adaptive smoke helper exported by
+`@jskit-ai/shell-web`.
+
+## Invariants
+
+- `App.vue`, the shell layout, placements, topology, and route pages agree.
+- Navigation uses semantic placements rather than direct component injection.
+- Compact controls have accessible names and at least 48 CSS-pixel targets.
+- Cached route/resource state hydrates writable UI state synchronously or with
+  immediate watchers.
+- Loading uses stable skeletons, not spinners or shifting status banners.
+- The adaptive browser check closes navigation through its public close control.
+
+## Example files
+
+`example/src/` contains the complete shell composition, standard link
+components, settings routes, placement registry, and topology. The browser
+example under `example/tests/` exercises the public adaptive-shell contract.
+The `expected-existing/` files show the minimal foundation shapes replaced by
+the complete shell; they are reference inputs, not merge instructions.
+
+## Variation points
+
+Change product navigation, surfaces, routes, settings sections, placements,
+responsive outlet mappings, labels, icons, and application-owned components.
+
+## Verification
+
+Exercise direct navigation, browser back/forward with a warm cache, keyboard
+navigation, current-link state, and compact/medium/expanded layouts. Run client
+tests and a production build.
+
+## Avoid
+
+- custom navigation registries beside placements
+- clicking Vuetify scrims or coordinates in browser tests
+- magic generated-page classes
+- source mutation or overwrite machinery

package/skills/jskit/references/patterns/shell/application-shell/example/expected-existing/src/App.vue

@@ -0,0 +1,13 @@
+<template>
+  <v-app>
+    <v-main>
+      <v-container class="py-10 py-md-14">
+        <v-row justify="center">
+          <v-col cols="12" sm="11" md="10" lg="8" xl="7">
+            <RouterView />
+          </v-col>
+        </v-row>
+      </v-container>
+    </v-main>
+  </v-app>
+</template>

package/skills/jskit/references/patterns/shell/application-shell/example/expected-existing/src/pages/home/index.vue

@@ -0,0 +1,48 @@
+<template>
+  <section class="home-start-screen d-flex flex-column ga-4">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Home</p>
+      <h1 class="home-start-screen__title">Home base</h1>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        The app runtime is online and ready for the first real workflow.
+      </p>
+    </header>
+
+    <v-sheet rounded="lg" border class="home-start-screen__panel">
+      <h2 class="text-h6 mb-2">No activity yet</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        Recent work, saved records, and next actions will appear here once this app has data.
+      </p>
+    </v-sheet>
+  </section>
+</template>
+
+<style scoped>
+.home-start-screen {
+  --home-start-title-size: 2rem;
+  --home-start-panel-padding: 1rem;
+}
+
+.home-start-screen {
+  margin-inline: auto;
+  max-width: 48rem;
+}
+
+.home-start-screen__title {
+  font-size: var(--home-start-title-size);
+  font-weight: 700;
+  letter-spacing: 0;
+  line-height: 1.08;
+  margin: 0 0 0.45rem;
+}
+
+.home-start-screen__panel {
+  padding: var(--home-start-panel-padding);
+}
+
+@media (max-width: 640px) {
+  .home-start-screen {
+    --home-start-title-size: 1.5rem;
+  }
+}
+</style>

package/skills/jskit/references/patterns/shell/application-shell/example/expected-existing/src/pages/home.vue

@@ -0,0 +1,13 @@
+<route lang="json">
+{
+  "meta": {
+    "jskit": {
+      "surface": "home"
+    }
+  }
+}
+</route>
+
+<template>
+  <RouterView />
+</template>

package/skills/jskit/references/patterns/shell/application-shell/example/src/App.vue

@@ -0,0 +1,11 @@
+<script setup>
+import { RouterView } from "vue-router";
+import ShellErrorHost from "@jskit-ai/shell-web/client/components/ShellErrorHost";
+</script>
+
+<template>
+  <v-app>
+    <RouterView />
+    <ShellErrorHost />
+  </v-app>
+</template>

package/skills/jskit/references/patterns/shell/application-shell/example/src/components/ShellLayout.vue

@@ -0,0 +1,13 @@
+<script>
+import { h } from "vue";
+import PackageShellLayout from "@jskit-ai/shell-web/client/components/ShellLayout";
+
+export default {
+  name: "ShellLayout",
+  inheritAttrs: false,
+  setup(_, { attrs, slots }) {
+    // Keep drawerWidth, railWidth, navigationItemSpacing, and future shell props package-owned.
+    return () => h(PackageShellLayout, attrs, slots);
+  }
+};
+</script>

package/skills/jskit/references/patterns/shell/application-shell/example/src/components/menus/MenuLinkItem.vue

@@ -0,0 +1,30 @@
+<script setup>
+import ShellMenuLinkItem from "@jskit-ai/shell-web/client/components/ShellMenuLinkItem";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  icon: {
+    type: String,
+    default: ""
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  },
+  exact: {
+    type: Boolean,
+    default: false
+  }
+});
+</script>
+
+<template>
+  <ShellMenuLinkItem v-bind="props" />
+</template>

package/skills/jskit/references/patterns/shell/application-shell/example/src/components/menus/SurfaceAwareMenuLinkItem.vue

@@ -0,0 +1,42 @@
+<script setup>
+import ShellSurfaceAwareMenuLinkItem from "@jskit-ai/shell-web/client/components/ShellSurfaceAwareMenuLinkItem";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  icon: {
+    type: String,
+    default: ""
+  },
+  surface: {
+    type: String,
+    default: ""
+  },
+  scopedSuffix: {
+    type: String,
+    default: "/"
+  },
+  unscopedSuffix: {
+    type: String,
+    default: "/"
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  },
+  exact: {
+    type: Boolean,
+    default: false
+  }
+});
+</script>
+
+<template>
+  <ShellSurfaceAwareMenuLinkItem v-bind="props" />
+</template>

package/skills/jskit/references/patterns/shell/application-shell/example/src/components/menus/TabLinkItem.vue

@@ -0,0 +1,42 @@
+<script setup>
+import ShellTabLinkItem from "@jskit-ai/shell-web/client/components/ShellTabLinkItem";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  icon: {
+    type: String,
+    default: ""
+  },
+  surface: {
+    type: String,
+    default: ""
+  },
+  scopedSuffix: {
+    type: String,
+    default: "/"
+  },
+  unscopedSuffix: {
+    type: String,
+    default: "/"
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  },
+  exact: {
+    type: Boolean,
+    default: false
+  }
+});
+</script>
+
+<template>
+  <ShellTabLinkItem v-bind="props" />
+</template>