@kvman/testkit 0.1.0

package/dist/running/running-kvman.js

@@ -0,0 +1,80 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { z } from '@kvman/sdk';
+import { BinFailure } from "../bin/bin-failure.js";
+/** The kvman can't be reached; the caller treats it as not running. */
+export class KvmanUnreachableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KvmanUnreachableError';
+    }
+}
+const lockSchema = z.object({ pid: z.number().int().positive(), port: z.number().int().min(1).max(65_535).optional() });
+function hasCode(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (hasCode(error, 'ESRCH'))
+            return false;
+        if (hasCode(error, 'EPERM'))
+            return true;
+        throw error;
+    }
+}
+function baseUrlFromOption(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new BinFailure('VALIDATION_FAILED', `--url ${JSON.stringify(url)} isn't a URL; give an http: URL for 127.0.0.1 or localhost with an explicit port, such as http://127.0.0.1:3737.`);
+    }
+    if (parsed.protocol !== 'http:' || (parsed.hostname !== '127.0.0.1' && parsed.hostname !== 'localhost') || parsed.port === '') {
+        throw new BinFailure('VALIDATION_FAILED', `--url ${JSON.stringify(url)} isn't usable; give an http: URL for 127.0.0.1 or localhost with an explicit port, such as http://127.0.0.1:3737.`);
+    }
+    return `http://${parsed.hostname}:${parsed.port}`;
+}
+function resolveHome(home) {
+    if (home !== undefined)
+        return home;
+    const fromEnvironment = process.env.KVMAN_HOME;
+    if (fromEnvironment !== undefined && fromEnvironment !== '')
+        return fromEnvironment;
+    return path.join(homedir(), '.kvman');
+}
+function baseUrlFromLock(home) {
+    let text;
+    try {
+        text = readFileSync(path.join(home, 'kvman.lock'), 'utf8');
+    }
+    catch (error) {
+        if (hasCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const lock = lockSchema.safeParse(parsed);
+    if (!lock.success || lock.data.port === undefined || !isAlive(lock.data.pid))
+        return undefined;
+    return `http://127.0.0.1:${String(lock.data.port)}`;
+}
+/** Finds the running kvman: `undefined` when no lock file, stale lock, or portless lock says one runs. */
+export function findRunningKvman(options) {
+    if (options.url !== undefined)
+        return { baseUrl: baseUrlFromOption(options.url) };
+    const baseUrl = baseUrlFromLock(resolveHome(options.home));
+    return baseUrl === undefined ? undefined : { baseUrl };
+}
+//# sourceMappingURL=running-kvman.js.map

package/dist/running/running-kvman.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"running-kvman.js","sourceRoot":"","sources":["../../src/running/running-kvman.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,CAAC,EAAE,MAAM,YAAY,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAQnD,uEAAuE;AACvE,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAExH,SAAS,OAAO,CAAC,KAAc,EAAE,IAAY;IAC3C,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AAC1E,CAAC;AAED,SAAS,OAAO,CAAC,GAAW;IAC1B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1C,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QACzC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,UAAU,CAAC,mBAAmB,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,kHAAkH,CAAC,CAAC;IAC5L,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,WAAW,IAAI,MAAM,CAAC,QAAQ,KAAK,WAAW,CAAC,IAAI,MAAM,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QAC9H,MAAM,IAAI,UAAU,CAAC,mBAAmB,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,mHAAmH,CAAC,CAAC;IAC7L,CAAC;IACD,OAAO,UAAU,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;AACpD,CAAC;AAED,SAAS,WAAW,CAAC,IAAwB;IAC3C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;IAC/C,IAAI,eAAe,KAAK,SAAS,IAAI,eAAe,KAAK,EAAE;QAAE,OAAO,eAAe,CAAC;IACpF,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,eAAe,CAAC,IAAY;IACnC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC;YAAE,OAAO,SAAS,CAAC;QAC/C,MAAM,KAAK,CAAC;IACd,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/F,OAAO,oBAAoB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACtD,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,gBAAgB,CAAC,OAAwC;IACvE,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;IAClF,MAAM,OAAO,GAAG,eAAe,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3D,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;AACzD,CAAC"}

package/docs/i18n.md

@@ -0,0 +1,20 @@
+# Texts and languages
+
+- Every text a person sees is a translation key. An extension ships `locales/<lang>.json` files: one flat JSON object of strings, with every key under its namespace, such as `{ "notes.pages.list": "Notes" }`. kvman's own extensions ship `en` and `ar`; ship at least those two.
+- Placeholders use `{name}`: `"notes.count": "Notes: {count}"`, filled by a view's `params` or `kvman.t(key, { count })`.
+- A key missing in a language falls back to `en`, then to the key itself.
+
+## Conventions
+
+| Key | Is |
+|---|---|
+| `<namespace>.title` | the extension's display name |
+| `<setting>.title` | a setting's short title, where the setting is shown |
+| `<setting>.options.<value>` | the name of one choice of a setting whose value is one of a list of strings (otherwise the value shows) |
+| `<name>.description` | a translated description of a setting, command, or query (else the English `description`) |
+| `<command>.fields.<field>` | a form field's label (else the field's `.describe()` text) |
+| `<namespace>.errors.<CODE>` | the text of an error code |
+
+- `ar`, `he`, `fa`, and `ur` are right-to-left; styles use logical properties so pages mirror.
+- Text sent to a model stays English.
+- `npm run check` reports a key one catalog has and another lacks, every key your `ui.get` uses that is missing, and missing `<namespace>.title` and setting titles.

package/docs/presets.md

@@ -0,0 +1,15 @@
+# Presets
+
+A preset is the whole app for one run: which extensions load, and the preset-level value of any setting.
+
+```json
+{ "name": "notes-app",
+  "extensions": { "@kvman/kvai": "bundled", "@kvman/kvwebui": "bundled", "notes": "path:./notes" },
+  "settings": { "kvwebui.home": "notes.list", "kvwebui.title": "notes.app.title" } }
+```
+
+- **Sources.** `bundled` (kvai, kvwebui, kvcoder, kvcustomizer), `npm:<exact version>`, or `path:<folder>` relative to the preset file. A `path:` extension loads `kvman.source` with no build, and reloads on every save.
+- **Settings.** Any registered key, checked against its schema once the extensions load. A key with no default must be set by the preset. `kvwebui.home` is required whenever kvwebui loads: a page with no params, such as `kvwebui.extensions`.
+- **Running.** `kvman --preset ./notes-app.json` (a file, relative to the start folder) or `kvman --preset notes-app` for `<home>/presets/notes-app.json`. Non-bundled extensions ask to be trusted at start.
+- `kvman-preset new` writes a preset that runs as-is; `kvman-preset check` checks its schema, its extensions, its settings, and its home page.
+- `kvman-preview --preset notes-app.json` runs it in a separate kvman with a temporary home.

package/docs/sdk.md

@@ -0,0 +1,77 @@
+# The extension API (`@kvman/sdk`)
+
+An extension is a package whose `package.json` has `main` and a `kvman` field, and lists `@kvman/sdk` as a peerDependency:
+
+```json
+{ "name": "notes", "version": "0.1.0", "type": "module", "main": "dist/index.js",
+  "peerDependencies": { "@kvman/sdk": "^0.1.0" },
+  "kvman": { "namespace": "notes", "source": "src/index.ts", "dependencies": {} } }
+```
+
+`src/index.ts` default-exports one function of `ctx`. It only registers; it runs once in every worker.
+
+```ts
+import { z, type Ctx } from '@kvman/sdk';
+
+const note = z.object({ text: z.string() });
+
+export default (ctx: Ctx): void => {
+  ctx.registerCommand('notes.note.add', {
+    description: 'Adds a note to this workspace.',
+    public: true,
+    input: z.object({ text: z.string().describe('The note.') }),
+    output: z.object({ id: z.string() }),
+    handle: async (input) => ({ id: (await ctx.store.collection('notes', note).insert({ text: input.text })).id }),
+  });
+  ctx.registerQuery('notes.note.list', {
+    description: 'Lists the notes of this workspace.',
+    public: true,
+    input: z.object({ limit: z.number().int().max(1000).describe('How many to list.') }),
+    output: z.array(z.object({ id: z.string(), text: z.string() })),
+    handle: (input) => ctx.store.collection('notes', note).find({}, { limit: input.limit }),
+  });
+  ctx.registerSetting('notes.greeting', { description: 'The greeting shown above notes.', schema: z.string(), default: 'Hello' });
+};
+```
+
+## Rules the kernel enforces at load
+
+- Every name starts with `<namespace>.`, in lowercase kebab-case segments. A command ends in an imperative verb (`add`, `run`); a query ends in a read verb (`get`, `list`, `search`, `count`).
+- Every registration has a one-sentence `description`. A name registered twice, or an invalid registration, stops the load with `EXTENSION_INVALID`.
+- Use the SDK's `z` for every schema: inputs, outputs, and settings are validated at runtime.
+- Registrations are private unless `public: true`. Forms, HTTP, connectors, and other extensions need `public: true`.
+- Error codes of an extension are `<namespace>/UPPER_SNAKE`: `throw ctx.problem('notes/NOT_FOUND', { id })`.
+
+## Jobs
+
+- `ctx.exec(name, input)` runs a command or query now; `ctx.execAsync(name, input)` queues a command (it survives restarts and retries); `ctx.schedule(name, input, { at } | { cron })` runs one later.
+- Commands may write; queries are read-only. Commands take `retries` (default 3) and `timeoutMs` (default 600 000).
+- Inside a handler, `ctx.job` holds `{ id, rootId, workspace: { id, name, path }, caller, signal, progress(data) }`.
+- A handler's work ends when it returns: no `setInterval`, unawaited `setTimeout`, or promise left running. Long work goes to `execAsync` or `ctx.schedule`; long-lived child processes to `ctx.processes`.
+- Handlers keep no state in memory between jobs; anything that lasts goes in the store.
+
+## Storage, settings, secrets
+
+- `ctx.store.kv` and `ctx.store.collection(name, schema)` are per workspace; `ctx.store.global` is shared by every workspace. Every call returns a Promise; `ctx.store.transaction((tx) => …)` is synchronous.
+- `ctx.settings.get(key)` reads any key; an extension sets only its own keys.
+- `ctx.secrets.get/set/delete(name)` keep secrets in `secrets.json` only. Never log, store, or return a secret.
+- `ctx.log.info(message, fields)` writes to the kvman log; never log payloads, settings values, or secrets.
+
+## Handler points
+
+`ctx.registerHandler(point, { description, handle })` runs a handler when the kernel reaches a point: `kernel.started`, `kernel.stopping`, `kernel.workspace.opened`, `kernel.job.failed`, `kernel.job.succeeded`, `kernel.job.cancelled`, or `kernel.process.exited`. There are no events or listeners beyond these.
+
+## Typing calls to other extensions
+
+An extension augments `Commands` and `Queries` of `@kvman/sdk` for its public names. A caller gets typed `ctx.exec` after `import type {} from '<that extension>'`, allowed only when it is a `kvman.dependencies` entry.
+
+## Testing
+
+`npm test` runs `node --test` with `@kvman/testkit`:
+
+```ts
+const kernel = await createTestKernel({ extensions: ['./'], settings: { 'notes.greeting': 'Hi' } });
+await kernel.exec('notes.note.add', { text: 'hi' });                         // as the user
+await kernel.exec('notes.note.add', { text: 'hi' }, { as: '@acme/other' });  // as an extension
+await kernel.close();
+```

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kvman/testkit",
+  "version": "0.1.0",
+  "description": "createTestKernel: the real kvman kernel for extension tests.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ibndeif/kvman.git",
+    "directory": "packages/testkit"
+  },
+  "homepage": "https://github.com/ibndeif/kvman#readme",
+  "bugs": {
+    "url": "https://github.com/ibndeif/kvman/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "@kvman/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./fake-openai": {
+      "@kvman/source": "./src/fake-openai.ts",
+      "types": "./dist/fake-openai.d.ts",
+      "default": "./dist/fake-openai.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "kvman-check": "./dist/check-bin.js",
+    "kvman-docs": "./dist/docs/docs-bin.js",
+    "kvman-new": "./dist/new/new-bin.js",
+    "kvman-preset": "./dist/preset/preset-bin.js",
+    "kvman-preview": "./dist/preview/preview-bin.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "templates"
+  ],
+  "dependencies": {
+    "@kvman/kernel": "0.1.0",
+    "@kvman/sdk": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}

package/templates/AGENTS.md.template

@@ -0,0 +1,13 @@
+# __NAME__
+
+This folder is the kvman extension `__NAME__` (namespace `__NAMESPACE__`).
+
+- Read `docs/` first: the platform guides `sdk.md`, `i18n.md`, and `presets.md`.
+- For the docs of the extensions this one builds on, run `kvman-docs list` and `kvman-docs get <extension> <topic>`; they need a running kvman.
+- Keep this extension's own docs in `extension-docs/`; they are served by `__NAMESPACE__.docs.list` and `__NAMESPACE__.docs.get`.
+- After every change, run `npm run check` and `npm test`.
+- `src/index.ts` is loaded directly by a kvman that has this folder as a `path:` extension, so there is no build step while developing.
+- Never edit `dist/` or `node_modules/`.
+- User-facing text is always a translation key with `en` and `ar` entries in `locales/`.
+- Names are `<namespace>.<segment>`, lowercase kebab-case segments.
+__WEB_AGENTS__

package/templates/README.md.template

@@ -0,0 +1,12 @@
+# __NAME__
+
+A kvman extension, namespace `__NAMESPACE__`.
+
+- `src/index.ts` registers its commands, queries, and settings. A kvman that loads this folder as `path:` (a preset entry `"__NAME__": "path:<folder>"`) reloads it on every save, with no build.
+- `locales/en.json` and `locales/ar.json` hold its texts.
+- `extension-docs/usage.md` documents the extension for other builders, served by `__NAMESPACE__.docs.list` and `__NAMESPACE__.docs.get`.
+- `AGENTS.md` guides an agent working here; `docs/` holds the platform guides (`sdk`, `i18n`, `presets`).
+- `npm test` runs `test/` against a real kernel (`@kvman/testkit`).
+- `npm run check` loads it in a test kernel and reports what kvman would refuse or show untranslated.
+- `npm run build` compiles `dist/`, for publishing.
+__WEB_README__

package/templates/extension-docs/usage.md.template

@@ -0,0 +1,8 @@
+# Using __NAMESPACE__
+
+__NAME__ is a kvman extension (namespace `__NAMESPACE__`). Its public queries are:
+
+- `__NAMESPACE__.greeting.get` gives the greeting.
+- `__NAMESPACE__.ui.get` gives its pages and navigation.
+- `__NAMESPACE__.docs.list` lists these documentation pages.
+- `__NAMESPACE__.docs.get` gives one page by topic.

package/templates/src/docs.ts.template

@@ -0,0 +1,46 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ProblemError } from '@kvman/sdk';
+
+// The documentation pages of __NAMESPACE__ (plan 09 §9.5): the Markdown files in `extension-docs/`, served by
+// `__NAMESPACE__.docs.list` and `__NAMESPACE__.docs.get`. The folder sits next to this module, from `src/` and
+// from `dist/`.
+
+const pagesFolder = fileURLToPath(new URL('../extension-docs/', import.meta.url));
+
+const topicPattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+function notFound(topic: string): ProblemError {
+  return new ProblemError({ code: 'NOT_FOUND', message: `There is no documentation page ${topic}.` });
+}
+
+function titleOf(topic: string, markdown: string): string {
+  for (const line of markdown.split('\n')) {
+    if (line.startsWith('# ')) return line.slice('# '.length);
+  }
+  return topic;
+}
+
+/** Lists the documentation pages, sorted by topic. */
+export function listDocs(): { topic: string; title: string }[] {
+  return readdirSync(pagesFolder)
+    .filter((entry) => entry.endsWith('.md'))
+    .map((entry) => entry.slice(0, -'.md'.length))
+    .filter((topic) => topicPattern.test(topic))
+    .sort()
+    .map((topic) => ({ topic, title: titleOf(topic, readFileSync(path.join(pagesFolder, `${topic}.md`), 'utf8')) }));
+}
+
+/** Gives one documentation page; an unknown or invalid topic is `NOT_FOUND`. */
+export function getDoc(topic: string): { topic: string; title: string; markdown: string } {
+  if (!topicPattern.test(topic)) throw notFound(topic);
+  let markdown: string;
+  try {
+    markdown = readFileSync(path.join(pagesFolder, `${topic}.md`), 'utf8');
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') throw notFound(topic);
+    throw error;
+  }
+  return { topic, title: titleOf(topic, markdown), markdown };
+}

package/templates/src/index.ts.template

@@ -0,0 +1,42 @@
+import { z, type Ctx } from '@kvman/sdk';
+import { getDoc, listDocs } from './docs.ts';
+
+// The __NAMESPACE__ extension. A kvman that loads this folder as `path:` reloads it on every save, with no build.
+export default (ctx: Ctx): void => {
+  ctx.registerQuery('__NAMESPACE__.greeting.get', {
+    description: 'Gives the greeting.',
+    public: true,
+    input: z.object({}),
+    output: z.object({ text: z.string() }),
+    handle: () => ({ text: 'Hello from __NAMESPACE__!' }),
+  });
+
+  ctx.registerQuery('__NAMESPACE__.docs.list', {
+    description: 'Lists the documentation pages of __NAMESPACE__.',
+    public: true,
+    input: z.object({}),
+    output: z.array(z.object({ topic: z.string(), title: z.string() })),
+    handle: () => listDocs(),
+  });
+
+  ctx.registerQuery('__NAMESPACE__.docs.get', {
+    description: 'Gives one documentation page of __NAMESPACE__.',
+    public: true,
+    input: z.object({ topic: z.string().describe('The page topic, such as usage.') }),
+    output: z.object({ topic: z.string(), title: z.string(), markdown: z.string() }),
+    handle: (input) => getDoc(input.topic),
+  });
+
+  ctx.registerQuery('__NAMESPACE__.ui.get', {
+    description: 'Gives the pages and navigation of __NAMESPACE__.',
+    public: true,
+    input: z.object({}),
+    output: z.json(),
+    handle: () => ({
+      pages: [{ id: 'hello', title: '__NAMESPACE__.pages.hello', view: __PAGE_VIEW__ }],
+      nav: [{ id: 'hello', page: 'hello', title: '__NAMESPACE__.pages.hello', icon: 'puzzle', order: 50 }],
+      panels: [],
+      status: [],
+    }),
+  });
+};

package/templates/test/extension.test.ts.template

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { z } from '@kvman/sdk';
+import { createTestKernel } from '@kvman/testkit';
+
+const pageSchema = z.object({ topic: z.string(), title: z.string(), markdown: z.string() });
+
+test('__NAMESPACE__.greeting.get gives the greeting', async () => {
+  const kernel = await createTestKernel({ extensions: ['./'] });
+  try {
+    assert.deepEqual(await kernel.exec('__NAMESPACE__.greeting.get', {}), { text: 'Hello from __NAMESPACE__!' });
+  } finally {
+    await kernel.close();
+  }
+});
+
+test('__NAMESPACE__.docs.list and __NAMESPACE__.docs.get serve the usage page', async () => {
+  const kernel = await createTestKernel({ extensions: ['./'] });
+  try {
+    assert.deepEqual(await kernel.exec('__NAMESPACE__.docs.list', {}), [{ topic: 'usage', title: 'Using __NAMESPACE__' }]);
+    const page = pageSchema.parse(await kernel.exec('__NAMESPACE__.docs.get', { topic: 'usage' }));
+    assert.equal(page.topic, 'usage');
+    assert.equal(page.title, 'Using __NAMESPACE__');
+    assert.ok(page.markdown.startsWith('# Using __NAMESPACE__'));
+    await assert.rejects(kernel.exec('__NAMESPACE__.docs.get', { topic: 'no-such-page' }));
+  } finally {
+    await kernel.close();
+  }
+});

package/templates/web/components/Hello.vue.template

@@ -0,0 +1,42 @@
+<script setup lang="ts">
+import { inject, ref } from 'vue';
+import type { Kvman } from '@kvman/sdk/web';
+
+// A custom component (kvman plan 06 §6.4): kvwebui's CSS variables and logical properties for its look, and the
+// injected kvman for its texts.
+const kvman = inject<Kvman>('kvman');
+const count = ref(0);
+</script>
+
+<template>
+  <div class="hello">
+    <p class="hello-text">{{ kvman?.t('__NAMESPACE__.hello.text') }}</p>
+    <button type="button" class="hello-button" @click="count += 1">{{ kvman?.t('__NAMESPACE__.hello.count', { count }) }}</button>
+  </div>
+</template>
+
+<style scoped>
+.hello {
+  display: flex;
+  align-items: center;
+  gap: var(--kv-space-md);
+  padding: var(--kv-space-md);
+  border: 1px solid var(--kv-color-border);
+  border-radius: var(--kv-radius);
+  background: var(--kv-color-surface);
+  color: var(--kv-color-text);
+}
+.hello-text {
+  margin: 0;
+  flex: 1 1 auto;
+}
+.hello-button {
+  padding-block: var(--kv-space-sm);
+  padding-inline: var(--kv-space-md);
+  border: 0;
+  border-radius: var(--kv-radius);
+  background: var(--kv-color-primary);
+  color: var(--kv-color-on-primary);
+  cursor: pointer;
+}
+</style>

package/templates/web-build.ts.template

@@ -0,0 +1,26 @@
+import { readdirSync, rmSync } from 'node:fs';
+import vue from '@vitejs/plugin-vue';
+import { build } from 'vite';
+
+// Each web/components/<Name>.vue builds on its own into dist/web/components/<name>.js and <name>.css, the two files
+// kvwebui loads for the custom component `__NAMESPACE__.<name>`; `vue` comes from kvwebui's import map. With
+// `--watch` (npm run web:watch), each rebuilds when it changes, and a page refresh shows it.
+const watch = process.argv.includes('--watch');
+const kebab = (name: string): string => name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+
+if (!watch) rmSync('dist/web', { recursive: true, force: true });
+for (const file of readdirSync('web/components').filter((entry) => entry.endsWith('.vue'))) {
+  const name = kebab(file.slice(0, -'.vue'.length));
+  await build({
+    configFile: false,
+    logLevel: 'warn',
+    plugins: [vue()],
+    build: {
+      outDir: 'dist/web/components',
+      emptyOutDir: false,
+      watch: watch ? {} : null,
+      lib: { entry: `web/components/${file}`, formats: ['es'], fileName: () => `${name}.js`, cssFileName: name },
+      rolldownOptions: { external: ['vue'] },
+    },
+  });
+}