@jskit-ai/agent-docs 0.1.148 → 0.1.150

package/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/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 };

package/skills/jskit/references/patterns/app/shell-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/shell-foundation/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/app/shell-foundation/example/src/components/ShellLayout.vue

@@ -0,0 +1,12 @@
+<script>
+import { h } from "vue";
+import PackageShellLayout from "@jskit-ai/shell-web/client/components/ShellLayout";
+
+export default {
+  name: "ShellLayout",
+  inheritAttrs: false,
+  setup(_, { attrs, slots }) {
+    return () => h(PackageShellLayout, attrs, slots);
+  }
+};
+</script>

package/skills/jskit/references/patterns/app/shell-foundation/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/app/shell-foundation/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/app/shell-foundation/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>

package/skills/jskit/references/patterns/app/shell-foundation/example/src/error.js

@@ -0,0 +1,19 @@
+import { createDefaultErrorPolicy } from "@jskit-ai/shell-web/client/error";
+
+/**
+ * App-owned error handling contract.
+ * - intent chooses default presentation: resource-load, action-feedback, app-recoverable, blocking.
+ * - policy(event, ctx): decide channel + presenter + message.
+ * - defaultPresenterId: used when policy does not set presenterId.
+ * - presenters: optional custom presenters registered at boot.
+ */
+export default Object.freeze({
+  defaultPresenterId: "material.snackbar",
+  policy: createDefaultErrorPolicy({
+    resourceLoadChannel: "silent",
+    actionFeedbackChannel: "snackbar",
+    appRecoverableChannel: "banner",
+    blockingChannel: "dialog"
+  }),
+  presenters: []
+});

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

@@ -0,0 +1,116 @@
+<script setup>
+import { computed } from "vue";
+import { useQuery } from "@tanstack/vue-query";
+
+const healthQuery = useQuery({
+  queryKey: ["shell-web", "health"],
+  queryFn: async () => {
+    const response = await fetch("/api/health");
+    if (!response.ok) {
+      throw new Error("Health request failed.");
+    }
+    return response.json();
+  },
+  refetchOnWindowFocus: false
+});
+
+const health = computed(() => {
+  if (healthQuery.error.value) {
+    return "unreachable";
+  }
+
+  return healthQuery.data.value?.ok ? "ok" : "unhealthy";
+});
+
+const healthPending = computed(
+  () => healthQuery.isPending.value || healthQuery.isFetching.value
+);
+</script>
+
+<template>
+  <section class="home-surface-screen d-flex flex-column ga-4">
+    <header class="home-surface-screen__header">
+      <div>
+        <p class="text-overline text-medium-emphasis mb-1">Home</p>
+        <h1 class="home-surface-screen__title">Ready</h1>
+        <p class="text-body-2 text-medium-emphasis mb-0">
+          Core services are available.
+        </p>
+      </div>
+      <v-btn color="primary" variant="flat" to="/home/settings/general">Settings</v-btn>
+    </header>
+
+    <v-sheet rounded="lg" border class="home-surface-screen__panel">
+      <div class="home-surface-screen__status">
+        <span class="text-caption text-medium-emphasis">Service health</span>
+        <v-skeleton-loader
+          v-if="healthPending"
+          aria-label="Loading service health"
+          class="home-surface-screen__health-skeleton"
+          type="text"
+        />
+        <strong v-else>{{ health }}</strong>
+      </div>
+      <v-divider vertical class="d-none d-sm-block" />
+      <div class="home-surface-screen__status">
+        <span class="text-caption text-medium-emphasis">Route</span>
+        <strong>/home</strong>
+      </div>
+    </v-sheet>
+  </section>
+</template>
+
+<style scoped>
+.home-surface-screen {
+  --home-surface-title-size: 2rem;
+  --home-surface-panel-padding: 1rem;
+}
+
+.home-surface-screen__header {
+  align-items: flex-start;
+  display: flex;
+  gap: 1rem;
+  justify-content: space-between;
+}
+
+.home-surface-screen__title {
+  font-size: var(--home-surface-title-size);
+  font-weight: 700;
+  letter-spacing: 0;
+  line-height: 1.1;
+  margin: 0 0 0.4rem;
+}
+
+.home-surface-screen__panel {
+  align-items: stretch;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  padding: var(--home-surface-panel-padding);
+}
+
+.home-surface-screen__status {
+  display: grid;
+  gap: 0.15rem;
+  min-width: 9rem;
+}
+
+.home-surface-screen__health-skeleton {
+  max-width: 5rem;
+}
+
+@media (max-width: 640px) {
+  .home-surface-screen {
+    --home-surface-title-size: 1.5rem;
+  }
+
+  .home-surface-screen__header {
+    flex-direction: column;
+  }
+
+  .home-surface-screen__header :deep(.v-btn) {
+    min-height: 48px;
+    width: 100%;
+  }
+}
+</style>

package/skills/jskit/references/patterns/app/shell-foundation/example/src/pages/home/settings/general/index.vue

@@ -0,0 +1,40 @@
+<script setup>
+import { computed } from "vue";
+import { useShellLayoutState } from "@jskit-ai/shell-web/client/composables/useShellLayoutState";
+
+const { drawerDefaultOpen, setDrawerDefaultOpen } = useShellLayoutState();
+
+const drawerDefaultOpenModel = computed({
+  get() {
+    return drawerDefaultOpen.value;
+  },
+  set(value) {
+    setDrawerDefaultOpen(Boolean(value));
+  }
+});
+</script>
+
+<template>
+  <section class="settings-general-screen d-flex flex-column ga-4">
+    <div>
+      <h2 class="text-h6 mb-2">Navigation</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        On wider screens, collapsed navigation remains available as a rail. Phone layouts close the drawer and keep primary navigation in the bottom bar.
+      </p>
+    </div>
+
+    <v-switch
+      v-model="drawerDefaultOpenModel"
+      color="primary"
+      inset
+      hide-details="auto"
+      label="Start with expanded navigation on wider screens"
+    />
+  </section>
+</template>
+
+<style scoped>
+.settings-general-screen :deep(.v-switch) {
+  min-height: 48px;
+}
+</style>

package/skills/jskit/references/patterns/app/shell-foundation/example/src/pages/home/settings/index.vue

@@ -0,0 +1,7 @@
+<script setup>
+import { redirectToChild } from "@jskit-ai/kernel/client/pageRedirects";
+
+definePage({
+  redirect: redirectToChild("general")
+});
+</script>