@jskit-ai/agent-docs 0.1.149 → 0.1.150

package/skills/jskit/references/patterns/app/minimal-foundation/example/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "reading-room",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Minimal JSKIT base app (Fastify + Vue)",
+  "engines": {
+    "node": "26.x"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "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",
+    "jskit:update": "npx --yes @jskit-ai/jskit-catalog@latest update",
+    "jskit:check": "jskit check",
+    "verify": "npm run jskit:check && npm run lint && npm run test && npm run test:client && npm run build"
+  },
+  "dependencies": {
+    "@local/main": "0.1.0",
+    "@fastify/static": "^10.1.3",
+    "@jskit-ai/kernel": "0.1.178",
+    "@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.176"
+  },
+  "devDependencies": {
+    "@jskit-ai/config-eslint": "0.1.175",
+    "@jskit-ai/jskit-catalog": "0.1.203",
+    "@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/skills/jskit/references/patterns/app/minimal-foundation/example/packages/main/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@local/main",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./shared": "./src/shared/index.js"
+  },
+  "description": "App-local runtime composition and lightweight glue.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [],
+      "requires": []
+    },
+    "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/skills/jskit/references/patterns/app/minimal-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/skills/jskit/references/patterns/app/minimal-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/skills/jskit/references/patterns/app/minimal-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/skills/jskit/references/patterns/app/minimal-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/skills/jskit/references/patterns/app/minimal-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 };

package/skills/jskit/references/patterns/app/minimal-foundation/example/server.js

@@ -0,0 +1,195 @@
+import Fastify from "fastify";
+import fastifyStatic from "@fastify/static";
+import { resolveRuntimeEnv } from "./server/lib/runtimeEnv.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import {
+  createInstalledRuntime,
+  registerSurfaceRequestConstraint,
+  resolveRuntimeProfileFromSurface
+} from "@jskit-ai/kernel/server/platform";
+import { loadAppConfigFromAppRoot } from "@jskit-ai/kernel/server/support";
+import { matchesPathPrefix, normalizePathname } from "@jskit-ai/kernel/shared/surface/paths";
+import { surfaceRuntime } from "./server/lib/surfaceRuntime.js";
+
+const SPA_INDEX_FILE = "index.html";
+const API_BASE_PATH = "/api";
+const STATIC_GLOBAL_UI_PATHS = Object.freeze([
+  "/assets",
+  "/favicon.svg",
+  "/favicon.ico",
+  "/robots.txt",
+  "/manifest.webmanifest"
+]);
+
+function toRequestPathname(urlValue) {
+  const rawUrl = String(urlValue || "").trim() || "/";
+  try {
+    return normalizePathname(new URL(rawUrl, "http://localhost").pathname || "/");
+  } catch {
+    return normalizePathname(rawUrl.split("?")[0] || "/");
+  }
+}
+
+function isApiPath(pathname) {
+  return matchesPathPrefix(pathname, API_BASE_PATH);
+}
+
+function hasFileExtension(pathname) {
+  return path.extname(normalizePathname(pathname)) !== "";
+}
+
+function resolveGlobalUiPaths(runtimeGlobalUiPaths = []) {
+  const paths = new Set(Array.isArray(runtimeGlobalUiPaths) ? runtimeGlobalUiPaths : []);
+  for (const staticPath of STATIC_GLOBAL_UI_PATHS) {
+    paths.add(staticPath);
+  }
+  return [...paths];
+}
+
+function resolveStaticFilePath(pathname) {
+  const normalizedPathname = normalizePathname(pathname);
+
+  const relativePath = normalizedPathname.replace(/^\/+/, "");
+  if (!relativePath || relativePath.endsWith("/")) {
+    return "";
+  }
+
+  const normalizedRelativePath = path.posix.normalize(relativePath);
+  if (
+    !normalizedRelativePath ||
+    normalizedRelativePath === "." ||
+    normalizedRelativePath === ".." ||
+    normalizedRelativePath.startsWith("../") ||
+    normalizedRelativePath.includes("/../")
+  ) {
+    return "";
+  }
+
+  return normalizedRelativePath;
+}
+
+function canServeStaticFile(distRoot, relativePath) {
+  if (!distRoot || !relativePath) {
+    return false;
+  }
+
+  const normalizedDistRoot = path.resolve(distRoot);
+  const resolvedPath = path.resolve(normalizedDistRoot, relativePath);
+  if (!(resolvedPath === normalizedDistRoot || resolvedPath.startsWith(`${normalizedDistRoot}${path.sep}`))) {
+    return false;
+  }
+
+  return existsSync(resolvedPath);
+}
+
+async function createServer({ runtimeEnv = resolveRuntimeEnv() } = {}) {
+  const app = Fastify({
+    logger: true,
+    ajv: {
+      customOptions: {
+        allowUnionTypes: true
+      }
+    }
+  });
+
+  app.get("/api/health", async () => {
+    return {
+      ok: true,
+      app: "reading-room"
+    };
+  });
+  const appRoot = path.resolve(process.cwd());
+  const distRoot = path.resolve(appRoot, "dist");
+  const hasWebBuild = existsSync(path.resolve(distRoot, SPA_INDEX_FILE));
+  const spaDocument = hasWebBuild ? readFileSync(path.resolve(distRoot, SPA_INDEX_FILE), "utf8") : "";
+  const runtime = await createInstalledRuntime({
+    appRoot,
+    profile: resolveRuntimeProfileFromSurface({
+      surfaceRuntime,
+      serverSurface: runtimeEnv.SERVER_SURFACE
+    }),
+    config: await loadAppConfigFromAppRoot({ appRoot }),
+    env: runtimeEnv,
+    logger: app.log,
+    fastify: app
+  });
+
+  registerSurfaceRequestConstraint({
+    fastify: app,
+    surfaceRuntime,
+    serverSurface: runtimeEnv.SERVER_SURFACE,
+    globalUiPaths: resolveGlobalUiPaths(runtime?.globalUiPaths || [])
+  });
+
+  if (hasWebBuild) {
+    await app.register(fastifyStatic, {
+      root: distRoot,
+      index: false,
+      serve: false
+    });
+  } else {
+    app.log.warn("Frontend build not found (dist/index.html). Page routes will return 404 until `npm run build`.");
+  }
+
+  app.setNotFoundHandler(async (request, reply) => {
+    const pathname = toRequestPathname(request?.url);
+    const method = String(request?.method || "GET")
+      .trim()
+      .toUpperCase();
+    if (isApiPath(pathname) || (method !== "GET" && method !== "HEAD")) {
+      return reply.code(404).send({
+        message: `Route ${method}:${pathname} not found`,
+        error: "Not Found",
+        statusCode: 404
+      });
+    }
+    if (hasFileExtension(pathname)) {
+      const staticFilePath = resolveStaticFilePath(pathname);
+      if (hasWebBuild && staticFilePath && canServeStaticFile(distRoot, staticFilePath)) {
+        return reply.sendFile(staticFilePath);
+      }
+      return reply.code(404).send({
+        message: `Route ${method}:${pathname} not found`,
+        error: "Not Found",
+        statusCode: 404
+      });
+    }
+    if (!hasWebBuild) {
+      return reply.code(404).send({
+        error: "Frontend build is not available. Run `npm run build`."
+      });
+    }
+    return reply.type("text/html; charset=utf-8").send(spaDocument);
+  });
+
+  app.log.info(
+    {
+      surface: surfaceRuntime.normalizeSurfaceMode(runtimeEnv.SERVER_SURFACE),
+      providerPackages: runtime.providerPackageOrder,
+      packageOrder: runtime.packageOrder,
+      capabilities: runtime.diagnostics.capabilityIds
+    },
+    "Started JSKIT installed runtime."
+  );
+
+  return app;
+}
+
+async function startServer(options = {}) {
+  const runtimeEnv = resolveRuntimeEnv();
+  const configuredPort = options?.port === undefined ? runtimeEnv.PORT : Number(options.port);
+  const port = Number.isInteger(configuredPort) && configuredPort >= 0 ? configuredPort : runtimeEnv.PORT;
+  const host = String(options?.host || "").trim() || runtimeEnv.HOST;
+  const app = await createServer({
+    runtimeEnv: {
+      ...runtimeEnv,
+      HOST: host,
+      PORT: port
+    }
+  });
+  await app.listen({ port, host });
+  return app;
+}
+
+export { createServer, startServer };

package/skills/jskit/references/patterns/app/minimal-foundation/example/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/app/minimal-foundation/example/src/main.js

@@ -0,0 +1,85 @@
+import { createApp } from "vue";
+import { createPinia } from "pinia";
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
+import { createRouter, createWebHistory } from "vue-router/auto";
+import { routes } from "vue-router/auto-routes";
+import "vuetify/styles";
+import { createVuetify } from "vuetify";
+import { aliases as mdiAliases, mdi } from "vuetify/iconsets/mdi-svg";
+import App from "./App.vue";
+import NotFoundView from "./views/NotFound.vue";
+import { bootInstalledClientModules } from "virtual:jskit-client-bootstrap";
+import { createSurfaceRuntime } from "@jskit-ai/kernel/shared/surface/runtime";
+import {
+  shouldRetryTransientQueryFailure,
+  transientQueryRetryDelay
+} from "@jskit-ai/kernel/shared/support";
+import {
+  bootstrapClientShellApp,
+  createShellRouter
+} from "@jskit-ai/kernel/client";
+import { config } from "../config/public.js";
+
+const surfaceRuntime = createSurfaceRuntime({
+  allMode: config.surfaceModeAll,
+  surfaces: config.surfaceDefinitions,
+  defaultSurfaceId: config.surfaceDefaultId
+});
+
+const surfaceMode = surfaceRuntime.normalizeSurfaceMode(import.meta.env.VITE_SURFACE);
+const { router, fallbackRoute } = createShellRouter({
+  createRouter,
+  history: createWebHistory(),
+  routes,
+  surfaceRuntime,
+  surfaceMode,
+  notFoundComponent: NotFoundView,
+  guard: {
+    surfaceDefinitions: config.surfaceDefinitions,
+    defaultSurfaceId: config.surfaceDefaultId,
+    webRootAllowed: config.webRootAllowed
+  }
+});
+
+const vuetify = createVuetify({
+  theme: {
+    defaultTheme: "light"
+  },
+  icons: {
+    defaultSet: "mdi",
+    aliases: mdiAliases,
+    sets: { mdi }
+  }
+});
+const pinia = createPinia();
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: true,
+      retry: shouldRetryTransientQueryFailure,
+      retryDelay: transientQueryRetryDelay
+    }
+  }
+});
+
+void bootstrapClientShellApp({
+  createApp,
+  rootComponent: App,
+  appConfig: config,
+  appPlugins: [
+    pinia,
+    [VueQueryPlugin, { queryClient }],
+    vuetify
+  ],
+  pinia,
+  queryClient,
+  router,
+  bootClientModules: bootInstalledClientModules,
+  surfaceRuntime,
+  surfaceMode,
+  env: import.meta.env,
+  fallbackRoute
+}).catch((error) => {
+  console.error("Failed to bootstrap client app.", error);
+});

package/skills/jskit/references/patterns/app/minimal-foundation/example/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/app/minimal-foundation/example/src/pages/home.vue

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

package/skills/jskit/references/patterns/app/minimal-foundation/example/src/views/NotFound.vue

@@ -0,0 +1,13 @@
+<script setup>
+const title = "Not Found";
+const message = "The page you requested does not exist.";
+</script>
+
+<template>
+  <v-container class="fill-height d-flex align-center justify-center">
+    <v-card class="pa-6 text-center" max-width="560" rounded="lg">
+      <v-card-title class="text-h4">{{ title }}</v-card-title>
+      <v-card-text class="text-medium-emphasis">{{ message }}</v-card-text>
+    </v-card>
+  </v-container>
+</template>

package/skills/jskit/references/patterns/app/minimal-foundation/example/tests/client/smoke.vitest.js

@@ -0,0 +1,7 @@
+import { describe, expect, it } from "vitest";
+
+describe("reading-room client smoke", () => {
+  it("runs vitest in reading-room", () => {
+    expect(true).toBe(true);
+  });
+});

package/skills/jskit/references/patterns/app/minimal-foundation/example/tests/e2e/base-shell.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "@playwright/test";
+
+const VIEWPORTS = Object.freeze([
+  Object.freeze({ name: "compact", width: 390, height: 844 }),
+  Object.freeze({ name: "medium", width: 768, height: 1024 }),
+  Object.freeze({ name: "expanded", width: 1280, height: 900 })
+]);
+
+test.describe("application responsive smoke", () => {
+  for (const viewport of VIEWPORTS) {
+    test(`${viewport.name} home route renders without horizontal overflow`, async ({ page }) => {
+      await page.setViewportSize(viewport);
+      await page.goto("/home");
+      await expect(page.getByRole("heading", { name: "Home base" })).toBeVisible();
+
+      const dimensions = await page.evaluate(() => ({
+        clientWidth: document.documentElement.clientWidth,
+        scrollWidth: document.documentElement.scrollWidth
+      }));
+      expect(dimensions.scrollWidth).toBeLessThanOrEqual(dimensions.clientWidth + 1);
+    });
+  }
+});

package/skills/jskit/references/patterns/app/minimal-foundation/example/tests/server/smoke.test.js

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createServer } from "../../server.js";
+
+test("GET /api/health returns built-in health response", async () => {
+  const app = await createServer();
+  const response = await app.inject({
+    method: "GET",
+    url: "/api/health"
+  });
+
+  assert.equal(response.statusCode, 200);
+  assert.equal(response.json().ok, true);
+
+  await app.close();
+});