@jskit-ai/agent-docs 0.1.131 → 0.1.132

package/patterns/server-search.md

@@ -12,7 +12,7 @@ Core rule:
 - repositories may add internal-only filter keys before forwarding the query to JSON REST
 - structured list filters should use `createCrudListFilterContract(...)` so route/action validators, JSON REST search schema, and repository query normalization are derived from one definition
 
-Fresh generated CRUD repositories already follow this path:
+The standard CRUD repository pattern follows this path:
 
 ```js
 return api.resources.contacts.query({
@@ -31,7 +31,7 @@ The normal layer split is:
 Use `search: true` on a schema field when:
 - the public filter key should be the same as the field name
 - direct field filtering is enough
-- you are happy with the generated/effective search entry for that one field
+- you are happy with the effective search entry for that one field
 
 Example:
 
@@ -162,7 +162,7 @@ Append validators separately only for genuinely additional, non-filter query
 input. Standard view actions use
 `createStandardCrudViewQueryValidators()`.
 
-For structured list filters, prefer the generated contract shape:
+For structured list filters, prefer the standard contract shape:
 
 ```js
 const receivalListFilterContract = createCrudListFilterContract(

package/patterns/shell-foundation/PATTERN.md

@@ -0,0 +1,104 @@
+---
+id: app/shell-foundation
+title: Adaptive-shell JSKIT application foundation
+summary: A concrete JSKIT web application foundation with responsive shell navigation, settings, placements, and browser verification.
+keywords: app, foundation, material, navigation, placements, shell, vite, vue
+requires: @jskit-ai/http-runtime, @jskit-ai/kernel, @jskit-ai/shell-web
+---
+
+# Adaptive-shell JSKIT application foundation
+
+## Use when
+
+Use this pattern for a new browser application that needs the normal JSKIT
+adaptive shell: responsive navigation, route surfaces, settings, placement
+topology, app-local providers, server/runtime composition, and representative
+browser coverage. It is the normal starting point for a full JSKIT product.
+
+The example is a concrete `reading-room` application. An agent may copy it
+directly, adapt a narrow set of files, or use it as evidence while authoring a
+different layout through the same public framework APIs.
+
+## Do not use when
+
+Do not impose this tree on an existing application. Do not use it for a
+command-line service, an API-only service, or a product whose navigation model
+is still unknown. Use the minimal foundation when the shell would be
+premature.
+
+## Product decisions
+
+Decide the application name, initial surface, navigation vocabulary, public or
+authenticated access, and which settings actually exist. Decide database,
+authentication, tenancy, and domain capabilities separately. The pattern does
+not convert those choices into a generator questionnaire.
+
+## Invariants
+
+- Materialize source inside the existing project without disturbing `.git` or
+  any existing project/agent context.
+- Inspect and resolve file collisions; never force-overwrite product source.
+- Keep placements and topology explicit and use shell public components.
+- Keep one app-owned `npm run develop` entry that runs the API on loopback and
+  Vite on the host-supplied preview port; do not require a host to infer or
+  supervise framework-specific processes.
+- Keep `packages/main` as composition and light glue, not a feature dumping
+  ground.
+- Preserve accessible navigation, 48px compact interaction targets, warm-cache
+  state hydration, skeleton loading, and toast-based transient errors.
+- Use public shell controls in browser tests rather than implementation-detail
+  scrims or coordinates.
+- Do not attach generator provenance, receipts, completion state, or replay
+  history to copied source.
+
+## Framework APIs
+
+The example uses `@jskit-ai/shell-web` for layout, navigation, placement, and
+adaptive shell testing; `@jskit-ai/kernel` for provider/runtime composition;
+and `@jskit-ai/http-runtime` for the server boundary. Application routes,
+placement declarations, surface access, and app-local providers remain normal
+source files.
+
+## Example files
+
+`example/` contains the complete reference tree. Rename `example/gitignore` to
+`.gitignore` when copying it to an app. Managed preview identity belongs to the
+authentication surface pattern, not the shell foundation.
+
+Read these together before adapting the shell:
+
+- `example/src/App.vue`
+- `example/src/components/ShellLayout.vue`
+- `example/src/placement.js`
+- `example/src/placementTopology.js`
+- `example/config/surfaceAccessPolicies.js`
+- `example/src/pages/home.vue`
+- `example/src/pages/home/settings.vue`
+- `example/tests/e2e/adaptive-shell.spec.ts`
+
+## Variation points
+
+Rename the example, replace the home content, add or remove settings routes,
+and change placements through their public contracts. Use package-owned
+patterns for auth, users, databases, CRUD, realtime, and other capabilities.
+Do not preinstall capabilities solely because they appear in another app.
+
+## Verification
+
+Install the declared packages once, run `npm run develop` for the live
+application, then run lint, server tests, client tests, the production build,
+and the adaptive browser smoke at compact, medium, and expanded viewports.
+Verify navigation through accessible controls and confirm there is no
+horizontal overflow.
+
+## Avoid
+
+- Do not run `create-app` or reproduce its options in another command.
+- Do not create a temporary scaffold directory.
+- Do not require `.generated-ui-screen` or another magic class to recognize a
+  valid screen.
+- Do not add spinners for ordinary screen loading; use structure-matching
+  skeletons.
+- Do not push content down with persistent transient-error banners; use the
+  standard toast/error presentation.
+- Do not preserve historical template ownership after copying.

package/patterns/shell-foundation/example/.nvmrc

@@ -0,0 +1 @@
+26

package/patterns/shell-foundation/example/AGENTS.md

@@ -0,0 +1,17 @@
+# App Agent Instructions
+
+Use current project context, JSKIT public APIs, and the installed JSKIT pattern
+index as the source of truth for application work.
+
+Recommended references:
+
+- `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`
+- `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md`
+
+Before database, schema, CRUD, repository, or persistence work, inspect the
+relevant package-owned pattern from
+`node_modules/@jskit-ai/agent-docs/reference/autogen/PATTERN_INDEX.md`.
+
+Copied pattern source is ordinary application source. Do not add generator
+provenance, receipts, completion ledgers, or tooling-operation history. Keep
+changes scoped to the user request and verify runtime behavior directly.

package/patterns/shell-foundation/example/Procfile

@@ -0,0 +1,2 @@
+release: npm run db:migrate
+web: npm run start

package/patterns/shell-foundation/example/app.json

@@ -0,0 +1,14 @@
+{
+  "name": "reading-room",
+  "healthchecks": {
+    "web": [
+      {
+        "type": "startup",
+        "name": "web-ready",
+        "description": "Application responds to /api/health",
+        "path": "/api/health",
+        "attempts": 6
+      }
+    ]
+  }
+}

package/patterns/shell-foundation/example/bin/develop.js

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+import { startServer } from "../server.js";
+
+const LOOPBACK_HOST = "127.0.0.1";
+
+function requiredPort(value, fallback = 3000) {
+  const normalized = String(value || "").trim();
+  const parsed = Number.parseInt(normalized || String(fallback), 10);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535) {
+    throw new Error(`Invalid development port: ${normalized || "(empty)"}.`);
+  }
+  return parsed;
+}
+
+function waitForChild(child) {
+  return new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve({ code, signal }));
+  });
+}
+
+const previewHost = String(process.env.HOST || "").trim() || "0.0.0.0";
+const previewPort = requiredPort(process.env.PORT);
+let apiServer = null;
+let viteProcess = null;
+let requestedSignal = "";
+
+function requestShutdown(signal) {
+  requestedSignal = signal;
+  if (viteProcess && !viteProcess.killed) {
+    viteProcess.kill(signal);
+  }
+}
+
+process.once("SIGINT", () => requestShutdown("SIGINT"));
+process.once("SIGTERM", () => requestShutdown("SIGTERM"));
+
+try {
+  apiServer = await startServer({ host: LOOPBACK_HOST, port: 0 });
+  const apiPort = requiredPort(apiServer.server.address()?.port);
+  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+  viteProcess = spawn(
+    npmCommand,
+    ["run", "dev", "--", "--host", previewHost, "--port", String(previewPort), "--strictPort"],
+    {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        HOST: previewHost,
+        PORT: String(previewPort),
+        VITE_API_PROXY_TARGET: `http://${LOOPBACK_HOST}:${apiPort}`,
+        VITE_DEV_PORT: String(previewPort)
+      },
+      stdio: "inherit"
+    }
+  );
+
+  const result = await waitForChild(viteProcess);
+  if (!requestedSignal && result.code !== 0) {
+    throw new Error(
+      `Vite development server stopped unexpectedly (${result.signal || `exit ${result.code ?? "unknown"}`}).`
+    );
+  }
+} catch (error) {
+  console.error("Failed to start the development application:", error);
+  process.exitCode = 1;
+} finally {
+  if (apiServer) {
+    await apiServer.close().catch(() => {});
+  }
+}

package/patterns/shell-foundation/example/bin/server.js

@@ -0,0 +1,8 @@
+import { startServer } from "../server.js";
+
+try {
+  await startServer();
+} catch (error) {
+  console.error("Failed to start reading-room server:", error);
+  process.exitCode = 1;
+}

package/patterns/shell-foundation/example/config/public.js

@@ -0,0 +1,40 @@
+import { surfaceAccessPolicies } from "./surfaceAccessPolicies.js";
+
+export const config = {};
+
+config.surfaceModeAll = "all";
+config.surfaceDefaultId = "home";
+config.webRootAllowed = "no";
+config.surfaceAccessPolicies = surfaceAccessPolicies;
+config.mobile = {
+  enabled: false,
+  strategy: "",
+  appId: "",
+  appName: "",
+  assetMode: "bundled",
+  devServerUrl: "",
+  apiBaseUrl: "",
+  auth: {
+    callbackPath: "/auth/login",
+    customScheme: "",
+    appLinkDomains: []
+  },
+  android: {
+    packageName: "",
+    minSdk: 26,
+    targetSdk: 35,
+    versionCode: 1,
+    versionName: "1.0.0"
+  }
+};
+config.surfaceDefinitions = {};
+config.surfaceDefinitions.home = {
+  id: "home",
+  label: "Home",
+  pagesRoot: "home",
+  enabled: true,
+  requiresAuth: false,
+  requiresWorkspace: false,
+  accessPolicyId: "public",
+  origin: ""
+};

package/patterns/shell-foundation/example/config/server.js

@@ -0,0 +1 @@
+export const config = {};

package/patterns/shell-foundation/example/config/surfaceAccessPolicies.js

@@ -0,0 +1,3 @@
+export const surfaceAccessPolicies = {};
+
+surfaceAccessPolicies.public = {};

package/patterns/shell-foundation/example/eslint.config.mjs

@@ -0,0 +1,19 @@
+import { baseConfig, nodeConfig, vueConfig, webConfig } from "@jskit-ai/config-eslint/server";
+
+export default [
+  {
+    ignores: ["dist/**", "node_modules/**", "coverage/**", "test-results/**", ".jskit/**"]
+  },
+  {
+    files: ["src/pages/**/*.vue"],
+    languageOptions: {
+      globals: {
+        definePage: "readonly"
+      }
+    }
+  },
+  ...baseConfig,
+  ...vueConfig,
+  ...webConfig,
+  ...nodeConfig
+];

package/patterns/shell-foundation/example/favicon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="12" fill="#111827" />
+  <path
+    d="M20 16h24v8H28v20c0 6-4 10-10 10h-2v-8h2c2 0 2-1 2-3V16z"
+    fill="#22d3ee"
+  />
+</svg>

package/patterns/shell-foundation/example/gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+coverage/
+test-results/
+# Generated by vue-router/vite on the first dev or build scan.
+src/typed-router.d.ts
+.env
+.env.*
+!.env.example

package/patterns/shell-foundation/example/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>Reading Room</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/patterns/shell-foundation/example/jsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}

package/patterns/shell-foundation/example/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "reading-room",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "JSKIT shell-web app (Fastify + Vue)",
+  "engines": {
+    "node": "26.x"
+  },
+  "scripts": {
+    "server": "node ./bin/server.js",
+    "server:all": "node ./bin/server.js",
+    "server:home": "SERVER_SURFACE=home node ./bin/server.js",
+    "start": "node ./bin/server.js",
+    "develop": "node ./bin/develop.js",
+    "dev": "vite",
+    "dev:all": "vite",
+    "dev:home": "VITE_SURFACE=home vite",
+    "build": "vite build",
+    "build:all": "vite build",
+    "build:home": "VITE_SURFACE=home vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "test": "node --test",
+    "test:client": "vitest run tests/client",
+    "test:e2e": "playwright test tests/e2e",
+    "verify": "npm run lint && npm run test && npm run test:client && npm run build"
+  },
+  "dependencies": {
+    "@local/main": "file:packages/main",
+    "@fastify/static": "^10.1.3",
+    "@jskit-ai/kernel": "0.1.160",
+    "@tanstack/vue-query": "^5.101.0",
+    "fastify": "^5.8.5",
+    "json-rest-schema": "^1.0.17",
+    "pinia": "^3.0.4",
+    "vue": "^3.5.38",
+    "vue-router": "^5.1.0",
+    "vuetify": "^4.1.2",
+    "@jskit-ai/http-runtime": "0.1.158",
+    "@mdi/js": "^7.4.47",
+    "@jskit-ai/shell-web": "0.1.164"
+  },
+  "devDependencies": {
+    "@jskit-ai/agent-docs": "0.1.132",
+    "@jskit-ai/config-eslint": "0.1.157",
+    "@playwright/test": "1.61.1",
+    "@vitejs/plugin-vue": "^6.0.7",
+    "eslint": "^10.8.0",
+    "vite": "^8.2.1",
+    "vite-plugin-vuetify": "^2.1.3",
+    "vitest": "^4.1.9"
+  },
+  "allowScripts": {
+    "fsevents@2.3.2": true,
+    "fsevents@2.3.3": true,
+    "vue-demi@0.14.10": true
+  }
+}

package/patterns/shell-foundation/example/packages/main/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@local/main",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./client": "./src/client/index.js",
+    "./shared": "./src/shared/index.js"
+  },
+  "description": "App-local runtime composition and lightweight glue.",
+  "dependencies": {
+    "@jskit-ai/kernel": "0.1.160"
+  },
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [],
+      "requires": []
+    },
+    "runtime": {
+      "client": {
+        "providers": [
+          {
+            "entrypoint": "src/client/providers/MainClientProvider.js",
+            "export": "MainClientProvider"
+          }
+        ]
+      }
+    },
+    "metadata": {
+      "jskit": {
+        "ownershipGuidance": {
+          "title": "App-local main lane",
+          "summary": "Keep @local/main focused on app composition and lightweight glue. Substantial server features should become dedicated packages instead of growing inside packages/main.",
+          "responsibilities": [
+            "packages/main server code: bootstraps app-local configuration and lightweight wiring only",
+            "substantial server features: author a dedicated app-local package from the relevant framework pattern",
+            "packages/main: do not add service/controller/route/repository feature trees here"
+          ],
+          "examples": [
+            "packages/booking-engine owns booking operations",
+            "packages/availability-engine owns availability orchestration"
+          ]
+        }
+      },
+      "server": {
+        "routes": []
+      },
+      "ui": {
+        "routes": [],
+        "elements": [],
+        "overrides": []
+      }
+    }
+  }
+}

package/patterns/shell-foundation/example/packages/main/src/client/index.js

@@ -0,0 +1,9 @@
+/**
+ * Client entrypoint for @local/main.
+ *
+ * Export browser-facing modules from here.
+ *
+ * This package contributes its named UI components through one explicit
+ * capability provider.
+ */
+export { MainClientProvider } from "./providers/MainClientProvider.js";

package/patterns/shell-foundation/example/packages/main/src/client/providers/MainClientProvider.js

@@ -0,0 +1,18 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import MenuLinkItem from "/src/components/menus/MenuLinkItem.vue";
+import SurfaceAwareMenuLinkItem from "/src/components/menus/SurfaceAwareMenuLinkItem.vue";
+import TabLinkItem from "/src/components/menus/TabLinkItem.vue";
+
+const MainClientProvider = defineProvider({
+  id: "local.main.client",
+  requires: {
+    components: "client.components"
+  },
+  setup({ components }) {
+    components.register("local.main.ui.menu-link-item", MenuLinkItem);
+    components.register("local.main.ui.surface-aware-menu-link-item", SurfaceAwareMenuLinkItem);
+    components.register("local.main.ui.tab-link-item", TabLinkItem);
+  }
+});
+
+export { MainClientProvider };

package/patterns/shell-foundation/example/packages/main/src/shared/index.js

@@ -0,0 +1,10 @@
+/**
+ * Shared entrypoint for code used by both client and server.
+ *
+ * Keep this for genuinely app-local shared glue only.
+ *
+ * Example:
+ * export * from "./schemas/index.js";
+ * export * from "./constants/index.js";
+ */
+export {};

package/patterns/shell-foundation/example/packages/main/src/shared/schemas/index.js

@@ -0,0 +1,22 @@
+/**
+ * App-local shared transport validators/resources live here.
+ * Dedicated feature packages should keep their own schemas with the feature.
+ *
+ * Example:
+ * import { createSchema } from "json-rest-schema";
+ *
+ * export const helloQuerySchema = createSchema({
+ *   name: { type: "string", minLength: 1, maxLength: 80 }
+ * });
+ *
+ * export const helloResponseSchema = {
+ *   type: "object",
+ *   additionalProperties: false,
+ *   required: ["ok", "message"],
+ *   properties: {
+ *     ok: { type: "boolean" },
+ *     message: { type: "string", minLength: 1 }
+ *   }
+ * };
+ */
+export {};

package/patterns/shell-foundation/example/playwright.config.mjs

@@ -0,0 +1,31 @@
+import { defineConfig } from "@playwright/test";
+
+const managedBaseUrl = String(process.env.PLAYWRIGHT_BASE_URL || "")
+  .trim()
+  .replace(/\/+$/u, "");
+const baseURL = managedBaseUrl || "http://127.0.0.1:4173";
+const storageState = String(process.env.VIBE64_PLAYWRIGHT_STORAGE_STATE || "").trim();
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  timeout: 60_000,
+  expect: {
+    timeout: 10_000
+  },
+  use: {
+    baseURL,
+    headless: true,
+    ...(storageState ? { storageState } : {})
+  },
+  ...(managedBaseUrl ? {} : {
+    webServer: {
+      command: "npm run build && node ./bin/server.js",
+      env: {
+        PORT: "4173"
+      },
+      url: `${baseURL}/api/health`,
+      reuseExistingServer: true,
+      timeout: 180_000
+    }
+  })
+});

package/patterns/shell-foundation/example/server/lib/runtimeEnv.js

@@ -0,0 +1,45 @@
+import { createRequire } from "node:module";
+import { surfaceRuntime } from "./surfaceRuntime.js";
+
+const require = createRequire(import.meta.url);
+
+function toPort(value, fallback = 3000) {
+  const parsed = Number.parseInt(String(value || "").trim(), 10);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallback;
+}
+
+let envLoaded = false;
+
+function ensureRuntimeEnvLoaded() {
+  if (envLoaded) {
+    return;
+  }
+  try {
+    const dotenvModule = require("dotenv");
+    const loadDotEnv = dotenvModule?.config;
+    if (typeof loadDotEnv === "function") {
+      loadDotEnv();
+    }
+  } catch {
+    // dotenv is optional in base-shell; bundles can add it when needed.
+  }
+  envLoaded = true;
+}
+
+function resolveRuntimeEnv() {
+  ensureRuntimeEnvLoaded();
+  const serverSurface = surfaceRuntime.normalizeSurfaceMode(
+    process.env.JSKIT_SERVER_SURFACE || process.env.SERVER_SURFACE
+  );
+  return {
+    ...process.env,
+    SERVER_SURFACE: serverSurface,
+    PORT: toPort(process.env.PORT, 3000),
+    HOST: String(process.env.HOST || "").trim() || "0.0.0.0"
+  };
+}
+
+export { resolveRuntimeEnv };

package/patterns/shell-foundation/example/server/lib/surfaceRuntime.js

@@ -0,0 +1,10 @@
+import { createSurfaceRuntime } from "@jskit-ai/kernel/shared/surface/runtime";
+import { config } from "../../config/public.js";
+
+const surfaceRuntime = createSurfaceRuntime({
+  allMode: config.surfaceModeAll,
+  surfaces: config.surfaceDefinitions,
+  defaultSurfaceId: config.surfaceDefaultId
+});
+
+export { surfaceRuntime };