@kvman/kvbuilder 0.2.0

package/dist/connectors/ext.d.ts

@@ -0,0 +1,40 @@
+export declare const extConnector: {
+    name: string;
+    optIn: true;
+    description: string;
+    commands: ({
+        name: string;
+        command: string;
+        examples: ({
+            description: string;
+            input: {
+                name: string;
+                namespace: string;
+                folder: string;
+                web?: never;
+            };
+        } | {
+            description: string;
+            input: {
+                name: string;
+                namespace: string;
+                folder: string;
+                web: boolean;
+            };
+        })[];
+    } | {
+        name: string;
+        command: string;
+        examples?: never;
+    } | {
+        name: string;
+        command: string;
+        examples: {
+            description: string;
+            input: {
+                folder: string;
+            };
+        }[];
+    })[];
+};
+//# sourceMappingURL=ext.d.ts.map

package/dist/connectors/ext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext.d.ts","sourceRoot":"","sources":["../../src/connectors/ext.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAUxB,CAAC"}

package/dist/connectors/ext.js

@@ -0,0 +1,13 @@
+// The `ext` connector (plan 09 §9.1): builds extension projects in the workspace, through the testkit's bins.
+export const extConnector = {
+    name: 'ext',
+    optIn: true,
+    description: 'Create, list, check, and test kvman extension projects in the workspace. Use it for any work on an extension, and run check, then test, after changing one.',
+    commands: [
+        { name: 'new', command: 'kvbuilder.ext.new', examples: [{ description: 'Scaffold a notes extension', input: { name: 'notes', namespace: 'notes', folder: 'notes' } }, { description: 'Scaffold one with a Vue component', input: { name: 'cards', namespace: 'cards', folder: 'cards', web: true } }] },
+        { name: 'list', command: 'kvbuilder.ext.list' },
+        { name: 'check', command: 'kvbuilder.ext.check', examples: [{ description: 'Check the notes project', input: { folder: 'notes' } }] },
+        { name: 'test', command: 'kvbuilder.ext.test', examples: [{ description: 'Test the notes project', input: { folder: 'notes' } }] },
+    ],
+};
+//# sourceMappingURL=ext.js.map

package/dist/connectors/ext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext.js","sourceRoot":"","sources":["../../src/connectors/ext.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,KAAK;IACX,KAAK,EAAE,IAAa;IACpB,WAAW,EAAE,6JAA6J;IAC1K,QAAQ,EAAE;QACR,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,4BAA4B,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,mCAAmC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE;QACvS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE;QAC/C,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,yBAAyB,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE;QACrI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,wBAAwB,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE;KACnI;CACF,CAAC"}

package/dist/connectors/kvman.d.ts

@@ -0,0 +1,113 @@
+export declare const kvmanConnector: {
+    name: string;
+    optIn: true;
+    description: string;
+    commands: ({
+        name: string;
+        command: string;
+        asks?: never;
+        examples?: never;
+    } | {
+        name: string;
+        command: string;
+        asks: true;
+        examples: {
+            description: string;
+            input: {
+                model: string;
+            };
+        }[];
+    } | {
+        name: string;
+        command: string;
+        asks: true;
+        examples: {
+            description: string;
+            input: {
+                key: string;
+                value: string;
+                scope: string;
+            };
+        }[];
+    } | {
+        name: string;
+        command: string;
+        asks: true;
+        examples: {
+            description: string;
+            input: {
+                key: string;
+                scope: string;
+            };
+        }[];
+    } | {
+        name: string;
+        command: string;
+        asks: true;
+        examples: {
+            description: string;
+            input: {
+                source: string;
+            };
+        }[];
+    } | {
+        name: string;
+        command: string;
+        asks: true;
+        examples: {
+            description: string;
+            input: {
+                name: string;
+            };
+        }[];
+    } | {
+        name: string;
+        command: string;
+        asks: true;
+        examples: {
+            description: string;
+            input: {};
+        }[];
+    } | {
+        name: string;
+        command: string;
+        examples: {
+            description: string;
+            input: {
+                status: string;
+                limit: number;
+            };
+        }[];
+        asks?: never;
+    } | {
+        name: string;
+        command: string;
+        examples: {
+            description: string;
+            input: {
+                id: string;
+            };
+        }[];
+        asks?: never;
+    } | {
+        name: string;
+        command: string;
+        examples: ({
+            description: string;
+            input: {
+                name: string;
+                input: {
+                    limit: number;
+                };
+            };
+        } | {
+            description: string;
+            input: {
+                name: string;
+                input?: never;
+            };
+        })[];
+        asks?: never;
+    })[];
+};
+//# sourceMappingURL=kvman.d.ts.map

package/dist/connectors/kvman.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kvman.d.ts","sourceRoot":"","sources":["../../src/connectors/kvman.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsC1B,CAAC"}

package/dist/connectors/kvman.js

@@ -0,0 +1,41 @@
+// The `kvman` connector (plan 09 §9.1; ADR 0010, 8; ADR 0022, 5, 7, and 8; ADR 0027, 13): shows and changes the app
+// the agent runs in. Each command wraps a kernel command or query. The ones that change the app ask the person first.
+export const kvmanConnector = {
+    name: 'kvman',
+    optIn: true,
+    description: 'See and change the app you are running in: its default model, settings, extensions, and preset, and its workspaces, jobs, processes, and health. Use it for any change to kvman itself. The person is asked before each change. query-get runs a public query of any installed extension. A change to the extensions or the preset is saved to the preset file and applies at the next start of kvman.',
+    commands: [
+        { name: 'model-list', command: 'kvbuilder.app.model.list' },
+        { name: 'model-set', command: 'kvbuilder.app.model.set', asks: true, examples: [{ description: 'Use another model', input: { model: 'anthropic/claude-sonnet-5-5' } }] },
+        { name: 'settings-list', command: 'kvbuilder.app.settings.list' },
+        { name: 'settings-set', command: 'kvbuilder.app.settings.set', asks: true, examples: [{ description: 'Set a setting for everyone', input: { key: 'kvwebui.theme', value: 'dark', scope: 'global' } }] },
+        { name: 'settings-reset', command: 'kvbuilder.app.settings.reset', asks: true, examples: [{ description: 'Go back to the default', input: { key: 'kvwebui.theme', scope: 'global' } }] },
+        { name: 'extensions-list', command: 'kvbuilder.app.extensions.list' },
+        {
+            name: 'extensions-install',
+            command: 'kvbuilder.app.extensions.install',
+            asks: true,
+            examples: [
+                { description: 'Add an npm extension', input: { source: 'npm:@acme/notes@1.2.3' } },
+                { description: 'Add the project in the workspace folder notes', input: { source: 'path:notes' } },
+            ],
+        },
+        { name: 'extensions-uninstall', command: 'kvbuilder.app.extensions.uninstall', asks: true, examples: [{ description: 'Remove one', input: { name: '@acme/notes' } }] },
+        { name: 'restart', command: 'kvbuilder.app.restart', asks: true, examples: [{ description: 'Restart kvman to finish adding the notes page', input: {} }] },
+        { name: 'preset-get', command: 'kvbuilder.app.preset.get' },
+        { name: 'workspaces-list', command: 'kvbuilder.app.workspaces.list' },
+        { name: 'jobs-list', command: 'kvbuilder.app.jobs.list', examples: [{ description: 'See the jobs that failed', input: { status: 'failed', limit: 20 } }] },
+        { name: 'jobs-get', command: 'kvbuilder.app.jobs.get', examples: [{ description: 'Read one job', input: { id: 'the job id' } }] },
+        { name: 'processes-list', command: 'kvbuilder.app.processes.list' },
+        { name: 'health-get', command: 'kvbuilder.app.health.get' },
+        {
+            name: 'query-get',
+            command: 'kvbuilder.app.query.get',
+            examples: [
+                { description: "Read an installed extension's data", input: { name: 'kvcoder.session.list', input: { limit: 10 } } },
+                { description: 'Run a query that takes nothing', input: { name: 'kvai.provider.list' } },
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=kvman.js.map

package/dist/connectors/kvman.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kvman.js","sourceRoot":"","sources":["../../src/connectors/kvman.ts"],"names":[],"mappings":"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"}

package/dist/connectors/preset.d.ts

@@ -0,0 +1,26 @@
+export declare const presetConnector: {
+    name: string;
+    optIn: true;
+    description: string;
+    commands: ({
+        name: string;
+        command: string;
+        examples: {
+            description: string;
+            input: {
+                name: string;
+                file: string;
+            };
+        }[];
+    } | {
+        name: string;
+        command: string;
+        examples: {
+            description: string;
+            input: {
+                file: string;
+            };
+        }[];
+    })[];
+};
+//# sourceMappingURL=preset.d.ts.map

package/dist/connectors/preset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preset.d.ts","sourceRoot":"","sources":["../../src/connectors/preset.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;CAQ3B,CAAC"}

package/dist/connectors/preset.js

@@ -0,0 +1,11 @@
+// The `preset` connector (plan 09 §9.1): writes and checks preset files.
+export const presetConnector = {
+    name: 'preset',
+    optIn: true,
+    description: 'Write and check kvman presets. Use it to create a preset file, and to check it before running it.',
+    commands: [
+        { name: 'new', command: 'kvbuilder.preset.new', examples: [{ description: 'Write a preset for a notes app', input: { name: 'notes-app', file: 'notes-app.json' } }] },
+        { name: 'check', command: 'kvbuilder.preset.check', examples: [{ description: 'Check that preset', input: { file: 'notes-app.json' } }] },
+    ],
+};
+//# sourceMappingURL=preset.js.map

package/dist/connectors/preset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preset.js","sourceRoot":"","sources":["../../src/connectors/preset.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,IAAa;IACpB,WAAW,EAAE,mGAAmG;IAChH,QAAQ,EAAE;QACR,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,gCAAgC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,CAAC,EAAE;QACrK,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,mBAAmB,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,CAAC,EAAE;KAC1I;CACF,CAAC"}

package/dist/connectors/preview.d.ts

@@ -0,0 +1,41 @@
+export declare const previewConnector: {
+    name: string;
+    optIn: true;
+    description: string;
+    commands: ({
+        name: string;
+        command: string;
+        examples: {
+            description: string;
+            input: {
+                extensions: string[];
+            };
+        }[];
+    } | {
+        name: string;
+        command: string;
+        examples?: never;
+    } | {
+        name: string;
+        command: string;
+        examples: {
+            description: string;
+            input: {
+                name: string;
+            };
+        }[];
+    } | {
+        name: string;
+        command: string;
+        examples: {
+            description: string;
+            input: {
+                name: string;
+                input: {
+                    text: string;
+                };
+            };
+        }[];
+    })[];
+};
+//# sourceMappingURL=preview.d.ts.map

package/dist/connectors/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/connectors/preview.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAY5B,CAAC"}

package/dist/connectors/preview.js

@@ -0,0 +1,14 @@
+// The `preview` connector (plan 09 §9.1 and §9.3; ADR 0022, 8): runs projects in a separate kvman, and calls them there.
+export const previewConnector = {
+    name: 'preview',
+    optIn: true,
+    description: 'Run kvman extension projects in a separate kvman with a temporary home. Use it to show the person an extension project working, to check a project by calling its commands and queries, and stop it when you are done. It runs nothing else: start any other app or page with shell.',
+    commands: [
+        { name: 'start', command: 'kvbuilder.preview.start', examples: [{ description: 'Preview the notes project', input: { extensions: ['notes'] } }] },
+        { name: 'stop', command: 'kvbuilder.preview.stop' },
+        { name: 'status', command: 'kvbuilder.preview.status' },
+        { name: 'query-get', command: 'kvbuilder.preview.query.get', examples: [{ description: "Read the previewed project's data", input: { name: 'notes.item.list' } }] },
+        { name: 'command-run', command: 'kvbuilder.preview.command.run', examples: [{ description: 'Run a command of the previewed project', input: { name: 'notes.item.add', input: { text: 'Milk' } } }] },
+    ],
+};
+//# sourceMappingURL=preview.js.map

package/dist/connectors/preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../src/connectors/preview.ts"],"names":[],"mappings":"AAAA,yHAAyH;AACzH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,IAAa;IACpB,WAAW,EACT,sRAAsR;IACxR,QAAQ,EAAE;QACR,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,2BAA2B,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,EAAE;QACjJ,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,EAAE;QACnD,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,0BAA0B,EAAE;QACvD,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,6BAA6B,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,mCAAmC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,EAAE,CAAC,EAAE;QACnK,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,+BAA+B,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,wCAAwC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE;KACrM;CACF,CAAC"}

package/dist/docs/guides.d.ts

@@ -0,0 +1,54 @@
+import { z, type Ctx } from '@kvman/sdk';
+export declare const guidePageSchema: z.ZodObject<{
+    extension: z.ZodString;
+    topic: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>;
+export declare const guideListSchema: z.ZodObject<{
+    pages: z.ZodArray<z.ZodObject<{
+        extension: z.ZodString;
+        topic: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>>;
+    problems: z.ZodArray<z.ZodObject<{
+        extension: z.ZodString;
+        problem: z.ZodObject<{
+            code: z.ZodUnion<readonly [z.ZodEnum<{
+                VALIDATION_FAILED: "VALIDATION_FAILED";
+                NOT_FOUND: "NOT_FOUND";
+                NOT_PUBLIC: "NOT_PUBLIC";
+                NOT_A_COMMAND: "NOT_A_COMMAND";
+                READ_ONLY: "READ_ONLY";
+                NO_JOB: "NO_JOB";
+                TOO_LARGE: "TOO_LARGE";
+                TOO_DEEP: "TOO_DEEP";
+                TIMEOUT: "TIMEOUT";
+                CANCELLED: "CANCELLED";
+                WORKER_CRASHED: "WORKER_CRASHED";
+                INTERRUPTED: "INTERRUPTED";
+                HANDLER_FAILED: "HANDLER_FAILED";
+                FORBIDDEN_ORIGIN: "FORBIDDEN_ORIGIN";
+                PROCESS_RUNNING: "PROCESS_RUNNING";
+                PORT_IN_USE: "PORT_IN_USE";
+                EXTENSION_INVALID: "EXTENSION_INVALID";
+                KVMAN_RUNNING: "KVMAN_RUNNING";
+            }>, z.ZodString]>;
+            message: z.ZodString;
+            params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("@kvman/sdk").Json, unknown, z.core.$ZodTypeInternals<import("@kvman/sdk").Json, unknown>>>>;
+        }, z.core.$strict>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const guideSchema: z.ZodObject<{
+    extension: z.ZodString;
+    topic: z.ZodString;
+    title: z.ZodString;
+    markdown: z.ZodString;
+}, z.core.$strip>;
+/** Every page: the built-in guides first, then each documenting extension's, with the extensions whose docs failed. */
+export declare function listGuides(ctx: Ctx): Promise<z.output<typeof guideListSchema>>;
+/** One page: a built-in guide with no extension (or `kvman`), else the extension's own page. */
+export declare function getGuide(ctx: Ctx, input: {
+    extension?: string | undefined;
+    topic: string;
+}): Promise<z.output<typeof guideSchema>>;
+//# sourceMappingURL=guides.d.ts.map

package/dist/docs/guides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guides.d.ts","sourceRoot":"","sources":["../../src/docs/guides.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,CAAC,EAAE,KAAK,GAAG,EAAgB,MAAM,YAAY,CAAC;AAWpF,eAAO,MAAM,eAAe;;;;iBAA4E,CAAC;AAEzG,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG1B,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;iBAAmD,CAAC;AAoB5E,uHAAuH;AACvH,wBAAsB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC,CAcpF;AAED,gGAAgG;AAChG,wBAAsB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC,CAcxI"}

package/dist/docs/guides.js

@@ -0,0 +1,68 @@
+import { ProblemError, problemSchema, z } from '@kvman/sdk';
+import { invalid } from "../problems.js";
+import { testkitDocsFolder } from "../run-bin.js";
+import { listPages, noSuchTopic, readPage, topicPattern } from "./pages.js";
+// The `docs` connector's two queries (plan 09 §9.1 and §9.5, ADR 0010, 15–17 and 22): the built-in guides of kvman
+// (the testkit's `docs/`), then the pages every loaded extension serves through its public `<namespace>.docs.list`
+// and `<namespace>.docs.get`. kvbuilder pulls them, so no extension registers anything with it.
+const builtIn = 'kvman';
+export const guidePageSchema = z.object({ extension: z.string(), topic: z.string(), title: z.string() });
+export const guideListSchema = z.object({
+    pages: z.array(guidePageSchema),
+    problems: z.array(z.object({ extension: z.string(), problem: problemSchema })),
+});
+export const guideSchema = guidePageSchema.extend({ markdown: z.string() });
+const listAnswerSchema = z.array(z.strictObject({ topic: z.string(), title: z.string() }));
+const pageAnswerSchema = z.strictObject({ topic: z.string(), title: z.string(), markdown: z.string() });
+// The loaded extensions that serve docs: both queries, public.
+async function documentedExtensions(ctx) {
+    const extensions = await ctx.exec('kernel.extensions.list', {});
+    return extensions
+        .filter((extension) => [`${extension.namespace}.docs.list`, `${extension.namespace}.docs.get`].every((wanted) => extension.queries.some((query) => query.name === wanted && query.public)))
+        .map((extension) => ({ name: extension.name, namespace: extension.namespace }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function invalidAnswer(extension, query, what) {
+    return { code: 'VALIDATION_FAILED', message: `${extension.namespace}.${query} answered something other than ${what}.` };
+}
+/** Every page: the built-in guides first, then each documenting extension's, with the extensions whose docs failed. */
+export async function listGuides(ctx) {
+    const pages = listPages(testkitDocsFolder()).map((entry) => ({ extension: builtIn, ...entry }));
+    const problems = [];
+    for (const extension of await documentedExtensions(ctx)) {
+        try {
+            const answer = listAnswerSchema.safeParse(await ctx.exec(`${extension.namespace}.docs.list`, {}));
+            if (answer.success)
+                for (const entry of answer.data)
+                    pages.push({ extension: extension.name, ...entry });
+            else
+                problems.push({ extension: extension.name, problem: invalidAnswer(extension, 'docs.list', 'a list of pages') });
+        }
+        catch (error) {
+            if (!(error instanceof ProblemError))
+                throw error;
+            problems.push({ extension: extension.name, problem: error.problem });
+        }
+    }
+    return { pages, problems };
+}
+/** One page: a built-in guide with no extension (or `kvman`), else the extension's own page. */
+export async function getGuide(ctx, input) {
+    if (!topicPattern.test(input.topic))
+        throw invalid(`"${input.topic}" isn't a lowercase kebab-case topic.`, { topic: input.topic });
+    if (input.extension === undefined || input.extension === builtIn) {
+        const page = readPage(testkitDocsFolder(), input.topic);
+        if (page === undefined)
+            throw noSuchTopic(input.topic, builtIn);
+        return { extension: builtIn, ...page };
+    }
+    const documented = (await documentedExtensions(ctx)).find((extension) => extension.name === input.extension);
+    if (documented === undefined) {
+        throw new ProblemError({ code: 'NOT_FOUND', message: `${input.extension} isn't loaded or doesn't serve docs.`, params: { extension: input.extension } });
+    }
+    const page = pageAnswerSchema.safeParse(await ctx.exec(`${documented.namespace}.docs.get`, { topic: input.topic }));
+    if (!page.success)
+        throw invalid(invalidAnswer(documented, 'docs.get', 'a page').message, { extension: documented.name, topic: input.topic });
+    return { extension: documented.name, ...page.data };
+}
+//# sourceMappingURL=guides.js.map

package/dist/docs/guides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guides.js","sourceRoot":"","sources":["../../src/docs/guides.ts"],"names":[],"mappings":"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"}

package/dist/docs/own-docs.d.ts

@@ -0,0 +1,5 @@
+import { type Ctx } from '@kvman/sdk';
+/** The guide `/build-kvman` gives a chat (`docs/guide.md`). */
+export declare function readGuide(): string;
+export declare function registerOwnDocs(ctx: Ctx): void;
+//# sourceMappingURL=own-docs.d.ts.map

package/dist/docs/own-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-docs.d.ts","sourceRoot":"","sources":["../../src/docs/own-docs.ts"],"names":[],"mappings":"AACA,OAAO,EAAK,KAAK,GAAG,EAAE,MAAM,YAAY,CAAC;AAUzC,+DAA+D;AAC/D,wBAAgB,SAAS,IAAI,MAAM,CAIlC;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAmB9C"}

package/dist/docs/own-docs.js

@@ -0,0 +1,36 @@
+import { fileURLToPath } from 'node:url';
+import { z } from '@kvman/sdk';
+import { listPages, noSuchTopic, readPage } from "./pages.js";
+// kvbuilder's own docs pair (plan 09 §9.5, ADR 0010, 22): the pages in its `docs/` folder, except `guide.md`, which
+// is the section `/build-kvman` sets in a chat (ADR 0027, 12 and 13). The folder sits next to `src/` and `dist/`.
+const docsFolder = fileURLToPath(new URL('../../docs/', import.meta.url));
+const notPages = ['guide'];
+/** The guide `/build-kvman` gives a chat (`docs/guide.md`). */
+export function readGuide() {
+    const page = readPage(docsFolder, 'guide');
+    if (page === undefined)
+        throw new Error('docs/guide.md is missing.');
+    return page.markdown;
+}
+export function registerOwnDocs(ctx) {
+    ctx.registerQuery('kvbuilder.docs.list', {
+        description: 'Lists the documentation pages of kvbuilder.',
+        public: true,
+        input: z.object({}),
+        output: z.array(z.object({ topic: z.string(), title: z.string() })),
+        handle: () => listPages(docsFolder, notPages),
+    });
+    ctx.registerQuery('kvbuilder.docs.get', {
+        description: 'Gives one documentation page of kvbuilder.',
+        public: true,
+        input: z.object({ topic: z.string().describe('The page topic, such as building.') }),
+        output: z.object({ topic: z.string(), title: z.string(), markdown: z.string() }),
+        handle: (input) => {
+            const page = readPage(docsFolder, input.topic, notPages);
+            if (page === undefined)
+                throw noSuchTopic(input.topic, 'kvbuilder');
+            return page;
+        },
+    });
+}
+//# sourceMappingURL=own-docs.js.map

package/dist/docs/own-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-docs.js","sourceRoot":"","sources":["../../src/docs/own-docs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,CAAC,EAAY,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE9D,oHAAoH;AACpH,kHAAkH;AAElH,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1E,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAU,CAAC;AAEpC,+DAA+D;AAC/D,MAAM,UAAU,SAAS;IACvB,MAAM,IAAI,GAAG,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACrE,OAAO,IAAI,CAAC,QAAQ,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAQ;IACtC,GAAG,CAAC,aAAa,CAAC,qBAAqB,EAAE;QACvC,WAAW,EAAE,6CAA6C;QAC1D,MAAM,EAAE,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACnB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACnE,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,QAAQ,CAAC;KAC9C,CAAC,CAAC;IACH,GAAG,CAAC,aAAa,CAAC,oBAAoB,EAAE;QACtC,WAAW,EAAE,4CAA4C;QACzD,MAAM,EAAE,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC,EAAE,CAAC;QACpF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QAChF,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;YAChB,MAAM,IAAI,GAAG,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YACzD,IAAI,IAAI,KAAK,SAAS;gBAAE,MAAM,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;YACpE,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/docs/pages.d.ts

@@ -0,0 +1,18 @@
+import { ProblemError } from '@kvman/sdk';
+export declare const topicPattern: RegExp;
+/** A page in a listing. */
+export type PageEntry = {
+    topic: string;
+    title: string;
+};
+/** A page with its content. */
+export type Page = PageEntry & {
+    markdown: string;
+};
+/** The page files of `folder` (without `exclude`), sorted by topic. */
+export declare function listPages(folder: string, exclude?: readonly string[]): PageEntry[];
+/** The page on `topic`, or `undefined` when the topic isn't a valid name or has no file. */
+export declare function readPage(folder: string, topic: string, exclude?: readonly string[]): Page | undefined;
+/** The `NOT_FOUND` Problem for a topic with no page. */
+export declare function noSuchTopic(topic: string, whose: string): ProblemError;
+//# sourceMappingURL=pages.d.ts.map

package/dist/docs/pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/docs/pages.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK1C,eAAO,MAAM,YAAY,QAA6B,CAAC;AAEvD,2BAA2B;AAC3B,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,+BAA+B;AAC/B,MAAM,MAAM,IAAI,GAAG,SAAS,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAapD,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,SAAS,MAAM,EAAO,GAAG,SAAS,EAAE,CAOtF;AAED,4FAA4F;AAC5F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,SAAS,MAAM,EAAO,GAAG,IAAI,GAAG,SAAS,CASzG;AAED,wDAAwD;AACxD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAEtE"}

package/dist/docs/pages.js

@@ -0,0 +1,44 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { ProblemError } from '@kvman/sdk';
+// Documentation pages as Markdown files in a folder (plan 09 §9.5): topic = file name without `.md`, which must be a
+// lowercase kebab-case segment; title = the first line that starts with `# `, else the topic.
+export const topicPattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function titleOf(topic, markdown) {
+    for (const line of markdown.split('\n')) {
+        if (line.startsWith('# '))
+            return line.slice('# '.length);
+    }
+    return topic;
+}
+function hasCode(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+/** The page files of `folder` (without `exclude`), sorted by topic. */
+export function listPages(folder, exclude = []) {
+    return readdirSync(folder)
+        .filter((entry) => entry.endsWith('.md'))
+        .map((entry) => entry.slice(0, -'.md'.length))
+        .filter((topic) => topicPattern.test(topic) && !exclude.includes(topic))
+        .sort()
+        .map((topic) => ({ topic, title: titleOf(topic, readFileSync(path.join(folder, `${topic}.md`), 'utf8')) }));
+}
+/** The page on `topic`, or `undefined` when the topic isn't a valid name or has no file. */
+export function readPage(folder, topic, exclude = []) {
+    if (!topicPattern.test(topic) || exclude.includes(topic))
+        return undefined;
+    try {
+        const markdown = readFileSync(path.join(folder, `${topic}.md`), 'utf8');
+        return { topic, title: titleOf(topic, markdown), markdown };
+    }
+    catch (error) {
+        if (hasCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+}
+/** The `NOT_FOUND` Problem for a topic with no page. */
+export function noSuchTopic(topic, whose) {
+    return new ProblemError({ code: 'NOT_FOUND', message: `${whose} has no documentation page "${topic}".`, params: { topic } });
+}
+//# sourceMappingURL=pages.js.map

package/dist/docs/pages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.js","sourceRoot":"","sources":["../../src/docs/pages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,qHAAqH;AACrH,8FAA8F;AAE9F,MAAM,CAAC,MAAM,YAAY,GAAG,0BAA0B,CAAC;AAQvD,SAAS,OAAO,CAAC,KAAa,EAAE,QAAgB;IAC9C,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,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,uEAAuE;AACvE,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,UAA6B,EAAE;IACvE,OAAO,WAAW,CAAC,MAAM,CAAC;SACvB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SACxC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;SAC7C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SACvE,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAChH,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,KAAa,EAAE,UAA6B,EAAE;IACrF,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3E,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QACxE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC9D,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;AACH,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,KAAa;IACtD,OAAO,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,KAAK,+BAA+B,KAAK,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;AAC/H,CAAC"}

package/dist/docs/register-docs.d.ts

@@ -0,0 +1,3 @@
+import { type Ctx } from '@kvman/sdk';
+export declare function registerDocs(ctx: Ctx): void;
+//# sourceMappingURL=register-docs.d.ts.map

package/dist/docs/register-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-docs.d.ts","sourceRoot":"","sources":["../../src/docs/register-docs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAK,KAAK,GAAG,EAAE,MAAM,YAAY,CAAC;AAMzC,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAmB3C"}