@kvman/testkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Deif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @kvman/testkit
+
+The tools for building and testing a [kvman](https://github.com/ibndeif/kvman) extension: `createTestKernel`, which runs the real kernel in a test, and the bins `kvman-new` (a new extension project), `kvman-check`, `kvman-preset`, `kvman-preview`, and `kvman-docs`.
+
+```
+npx -p @kvman/testkit kvman-new ./notes --name @me/notes --namespace notes
+```
+
+Start with [Getting started](https://github.com/ibndeif/kvman/blob/main/docs/developers/getting-started.md).
+
+## License
+
+MIT

package/dist/bin/bin-failure.d.ts

@@ -0,0 +1,16 @@
+import type { Json } from '@kvman/sdk';
+export declare const binFailureCodes: readonly ["VALIDATION_FAILED", "NOT_FOUND", "NOT_RUNNING", "FOLDER_NOT_EMPTY", "FILE_EXISTS", "NPM_FAILED", "NO_FREE_PORT", "PREVIEW_FAILED"];
+/** A code a bin fails with. */
+export type BinFailureCode = (typeof binFailureCodes)[number];
+/** A structured bin failure: `{ code, message, params? }`. */
+export declare class BinFailure extends Error {
+    /** The machine-readable code. */
+    readonly code: BinFailureCode;
+    /** The machine-readable details, if any. */
+    readonly params: Record<string, Json> | undefined;
+    /** Wraps a code, an English message, and optional JSON params. */
+    constructor(code: BinFailureCode, message: string, params?: Record<string, Json>);
+}
+/** Prints a failure: one JSON object on stderr with `--json`, else the line `error: <message>`. */
+export declare function printFailure(error: unknown, json: boolean): void;
+//# sourceMappingURL=bin-failure.d.ts.map

package/dist/bin/bin-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin-failure.d.ts","sourceRoot":"","sources":["../../src/bin/bin-failure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAKvC,eAAO,MAAM,eAAe,+IAAgJ,CAAC;AAE7K,+BAA+B;AAC/B,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,8DAA8D;AAC9D,qBAAa,UAAW,SAAQ,KAAK;IACnC,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC;IAElD,kEAAkE;gBACtD,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;CAMjF;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAQhE"}

package/dist/bin/bin-failure.js

@@ -0,0 +1,28 @@
+// The failure codes every bin of this package uses (ADR 0010, 20). kvcustomizer turns each into
+// `kvcustomizer/<CODE>`, except `VALIDATION_FAILED`, which stays as it is.
+export const binFailureCodes = ['VALIDATION_FAILED', 'NOT_FOUND', 'NOT_RUNNING', 'FOLDER_NOT_EMPTY', 'FILE_EXISTS', 'NPM_FAILED', 'NO_FREE_PORT', 'PREVIEW_FAILED'];
+/** A structured bin failure: `{ code, message, params? }`. */
+export class BinFailure extends Error {
+    /** The machine-readable code. */
+    code;
+    /** The machine-readable details, if any. */
+    params;
+    /** Wraps a code, an English message, and optional JSON params. */
+    constructor(code, message, params) {
+        super(message);
+        this.name = 'BinFailure';
+        this.code = code;
+        this.params = params;
+    }
+}
+/** Prints a failure: one JSON object on stderr with `--json`, else the line `error: <message>`. */
+export function printFailure(error, json) {
+    if (error instanceof BinFailure && json) {
+        const output = error.params === undefined ? { code: error.code, message: error.message } : { code: error.code, message: error.message, params: error.params };
+        process.stderr.write(`${JSON.stringify(output)}\n`);
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`error: ${message}\n`);
+}
+//# sourceMappingURL=bin-failure.js.map

package/dist/bin/bin-failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin-failure.js","sourceRoot":"","sources":["../../src/bin/bin-failure.ts"],"names":[],"mappings":"AAEA,gGAAgG;AAChG,2EAA2E;AAE3E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,mBAAmB,EAAE,WAAW,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,CAAU,CAAC;AAK7K,8DAA8D;AAC9D,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,iCAAiC;IACxB,IAAI,CAAiB;IAC9B,4CAA4C;IACnC,MAAM,CAAmC;IAElD,kEAAkE;IAClE,YAAY,IAAoB,EAAE,OAAe,EAAE,MAA6B;QAC9E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,mGAAmG;AACnG,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,IAAa;IACxD,IAAI,KAAK,YAAY,UAAU,IAAI,IAAI,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAC9J,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACpD,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,OAAO,IAAI,CAAC,CAAC;AAC9C,CAAC"}

package/dist/bin/program-command.d.ts

@@ -0,0 +1,7 @@
+export type Program = 'npm' | 'npx';
+export type ProgramCommand = {
+    command: string;
+    args: string[];
+};
+export declare function programCommand(platform: NodeJS.Platform, program: Program, args: readonly string[]): ProgramCommand;
+//# sourceMappingURL=program-command.d.ts.map

package/dist/bin/program-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program-command.d.ts","sourceRoot":"","sources":["../../src/bin/program-command.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK,CAAC;AAEpC,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEjE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAGnH"}

package/dist/bin/program-command.js

@@ -0,0 +1,8 @@
+// How the testkit bins start npm and npx, per OS: directly on Linux and macOS; on Windows through
+// `cmd.exe /d /s /c`, since `npm` there is a `.cmd` file.
+export function programCommand(platform, program, args) {
+    if (platform === 'win32')
+        return { command: 'cmd.exe', args: ['/d', '/s', '/c', program, ...args] };
+    return { command: program, args: [...args] };
+}
+//# sourceMappingURL=program-command.js.map

package/dist/bin/program-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program-command.js","sourceRoot":"","sources":["../../src/bin/program-command.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,0DAA0D;AAM1D,MAAM,UAAU,cAAc,CAAC,QAAyB,EAAE,OAAgB,EAAE,IAAuB;IACjG,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;IACpG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;AAC/C,CAAC"}

package/dist/bin/run-program.d.ts

@@ -0,0 +1,10 @@
+import { type Program } from './program-command.ts';
+export type ProgramRun = {
+    exitCode: number;
+    stdout: string;
+    output: string;
+};
+export declare function runProgram(program: Program, args: readonly string[], cwd: string): Promise<ProgramRun>;
+/** The last lines of a run's output, for a failure's message. */
+export declare function lastLines(output: string, count?: number): string;
+//# sourceMappingURL=run-program.d.ts.map

package/dist/bin/run-program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-program.d.ts","sourceRoot":"","sources":["../../src/bin/run-program.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAMpE,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAqBtG;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,MAAM,CAE5D"}

package/dist/bin/run-program.js

@@ -0,0 +1,30 @@
+import { spawn } from 'node:child_process';
+import { BinFailure } from "./bin-failure.js";
+import { programCommand } from "./program-command.js";
+export function runProgram(program, args, cwd) {
+    const start = programCommand(process.platform, program, args);
+    return new Promise((resolve, reject) => {
+        const child = spawn(start.command, start.args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        let stdout = '';
+        let output = '';
+        child.stdout?.setEncoding('utf8').on('data', (text) => {
+            stdout += text;
+            output += text;
+        });
+        child.stderr?.setEncoding('utf8').on('data', (text) => {
+            output += text;
+        });
+        child.once('error', (error) => {
+            const missing = 'code' in error && error.code === 'ENOENT';
+            reject(missing ? new BinFailure('NPM_FAILED', `${program} isn't on the PATH; install Node.js with npm.`, { program }) : error);
+        });
+        child.once('close', (code) => {
+            resolve({ exitCode: code ?? 1, stdout, output });
+        });
+    });
+}
+/** The last lines of a run's output, for a failure's message. */
+export function lastLines(output, count = 20) {
+    return output.trimEnd().split('\n').slice(-count).join('\n');
+}
+//# sourceMappingURL=run-program.js.map

package/dist/bin/run-program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-program.js","sourceRoot":"","sources":["../../src/bin/run-program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAgB,MAAM,sBAAsB,CAAC;AAQpE,MAAM,UAAU,UAAU,CAAC,OAAgB,EAAE,IAAuB,EAAE,GAAW;IAC/E,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC9D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9G,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;YAC5D,MAAM,IAAI,IAAI,CAAC;YACf,MAAM,IAAI,IAAI,CAAC;QACjB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;YAC5D,MAAM,IAAI,IAAI,CAAC;QACjB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC5B,MAAM,OAAO,GAAG,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;YAC3D,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,YAAY,EAAE,GAAG,OAAO,+CAA+C,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACjI,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YAC3B,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,KAAK,GAAG,EAAE;IAClD,OAAO,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC"}

package/dist/check/check-extension.d.ts

@@ -0,0 +1,4 @@
+import type { CheckedFinding } from './finding.ts';
+/** Checks the extension project in `folder`. */
+export declare function checkExtension(folder: string): Promise<CheckedFinding[]>;
+//# sourceMappingURL=check-extension.d.ts.map

package/dist/check/check-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-extension.d.ts","sourceRoot":"","sources":["../../src/check/check-extension.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAgDnD,gDAAgD;AAChD,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAkB9E"}

package/dist/check/check-extension.js

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { ProblemError, z } from '@kvman/sdk';
+import { createTestKernel } from "../index.js";
+import { docsFindings } from "./docs-findings.js";
+import { fieldFindings } from "./field-descriptions.js";
+import { localeFindings } from "./locale-keys.js";
+import { scanProjectTimers } from "./timer-scan.js";
+import { uiKeys } from "./ui-keys.js";
+// `kvman-check` (plan 09 §9.2, ADR 0009, 116): it loads the project's extension alone in a test kernel and reports a
+// refused load (one problem at a time, since a load stops at its first error), public input fields with no
+// description, missing locale keys, docs-pair warnings, and timer warnings.
+const manifestSchema = z.object({ name: z.string(), kvman: z.object({}).loose() }).loose();
+function notAProject() {
+    return { message: 'This folder has no package.json with a kvman field.', hint: 'Run kvman-check in the extension project\'s folder.', warning: false };
+}
+function loadFinding(problem) {
+    return { message: `The extension doesn't load: ${problem.message}`, hint: 'Fix what the kernel names; kvman-check reports the next problem once this one is gone.', warning: false };
+}
+function uiFailure(namespace, problem) {
+    return { message: `${namespace}.ui.get fails with ${problem.code}: ${problem.message}`, hint: 'kvwebui shows no UI from an extension whose ui.get fails; make it return its pages.', warning: false };
+}
+async function uiAnswer(kernel, namespace) {
+    try {
+        return { keys: uiKeys(await kernel.exec(`${namespace}.ui.get`, {})) };
+    }
+    catch (error) {
+        if (error instanceof ProblemError)
+            return { failure: uiFailure(namespace, error.problem) };
+        throw error;
+    }
+}
+async function loadedFindings(kernel, folder, name) {
+    const extension = (await kernel.exec('kernel.extensions.list', {})).find((candidate) => candidate.name === name);
+    if (extension === undefined)
+        return [];
+    const { namespace } = extension;
+    const required = [{ key: `${namespace}.title`, usedBy: 'the Extensions page' }];
+    for (const setting of extension.settings)
+        required.push({ key: `${setting.key}.title`, usedBy: "the extension's page" });
+    const findings = fieldFindings([...extension.commands, ...extension.queries]);
+    findings.push(...(await docsFindings(kernel, namespace, extension.queries)));
+    if (extension.queries.some((query) => query.name === `${namespace}.ui.get`)) {
+        const answer = await uiAnswer(kernel, namespace);
+        if ('failure' in answer)
+            findings.push(answer.failure);
+        else
+            for (const key of answer.keys)
+                required.push({ key, usedBy: `${namespace}.ui.get` });
+    }
+    return [...findings, ...localeFindings(folder, required)];
+}
+/** Checks the extension project in `folder`. */
+export async function checkExtension(folder) {
+    const manifestFile = path.join(folder, 'package.json');
+    if (!existsSync(manifestFile))
+        return [notAProject()];
+    const manifest = manifestSchema.safeParse(JSON.parse(readFileSync(manifestFile, 'utf8')));
+    if (!manifest.success)
+        return [notAProject()];
+    const timers = scanProjectTimers(folder);
+    let kernel;
+    try {
+        kernel = await createTestKernel({ extensions: [folder], logLevel: 'warn' });
+    }
+    catch (error) {
+        if (error instanceof ProblemError)
+            return [loadFinding(error.problem), ...timers];
+        throw error;
+    }
+    try {
+        return [...(await loadedFindings(kernel, folder, manifest.data.name)), ...timers];
+    }
+    finally {
+        await kernel.close();
+    }
+}
+//# sourceMappingURL=check-extension.js.map

package/dist/check/check-extension.js.map

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

package/dist/check/check-output.d.ts

@@ -0,0 +1,4 @@
+import type { CheckedFinding } from './finding.ts';
+export declare function readableFindings(findings: readonly CheckedFinding[]): string;
+export declare function jsonFindings(findings: readonly CheckedFinding[]): string;
+//# sourceMappingURL=check-output.d.ts.map

package/dist/check/check-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-output.d.ts","sourceRoot":"","sources":["../../src/check/check-output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAW,MAAM,cAAc,CAAC;AAK5D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAK5E;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAExE"}

package/dist/check/check-output.js

@@ -0,0 +1,13 @@
+// How `kvman-check` prints its findings (ADR 0009, 116): readable lines for a person, or with `--json` the
+// `[{ file?, message, hint }]` array on one line, which kvcustomizer's `ext check` reads.
+export function readableFindings(findings) {
+    if (findings.length === 0)
+        return 'kvman-check: no findings.';
+    const lines = findings.map((finding) => `${finding.file ?? 'extension'}: ${finding.message}\n  ${finding.hint}`);
+    const errors = findings.filter((finding) => !finding.warning).length;
+    return [...lines, `kvman-check: ${String(errors)} error(s), ${String(findings.length - errors)} warning(s).`].join('\n');
+}
+export function jsonFindings(findings) {
+    return JSON.stringify(findings.map(({ file, message, hint }) => (file === undefined ? { message, hint } : { file, message, hint })));
+}
+//# sourceMappingURL=check-output.js.map

package/dist/check/check-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-output.js","sourceRoot":"","sources":["../../src/check/check-output.ts"],"names":[],"mappings":"AAEA,2GAA2G;AAC3G,0FAA0F;AAE1F,MAAM,UAAU,gBAAgB,CAAC,QAAmC;IAClE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,2BAA2B,CAAC;IAC9D,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,KAAK,OAAO,CAAC,OAAO,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACjH,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IACrE,OAAO,CAAC,GAAG,KAAK,EAAE,gBAAgB,MAAM,CAAC,MAAM,CAAC,cAAc,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3H,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAmC;IAC9D,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAW,EAAE,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAChJ,CAAC"}

package/dist/check/docs-findings.d.ts

@@ -0,0 +1,8 @@
+import type { TestKernel } from '../index.ts';
+import type { CheckedFinding } from './finding.ts';
+/** The docs-pair warnings of the extension's `queries` (plan 09 §9.5): none when neither query is registered. */
+export declare function docsFindings(kernel: TestKernel, namespace: string, queries: readonly {
+    name: string;
+    public: boolean;
+}[]): Promise<CheckedFinding[]>;
+//# sourceMappingURL=docs-findings.d.ts.map

package/dist/check/docs-findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-findings.d.ts","sourceRoot":"","sources":["../../src/check/docs-findings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAiDnD,iHAAiH;AACjH,wBAAsB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAe1J"}

package/dist/check/docs-findings.js

@@ -0,0 +1,65 @@
+import { ProblemError, z } from '@kvman/sdk';
+// The docs-pair warnings (plan 09 §9.5, QA17-E30): an extension's docs reach kvcustomizer and `kvman-docs` only
+// through both `<namespace>.docs.list` and `<namespace>.docs.get` as public queries, so a half-done or wrong pair
+// warns instead of silently hiding the pages. Every finding here is a warning.
+const listAnswerSchema = z.array(z.object({ topic: z.string(), title: z.string() }));
+const pageAnswerSchema = z.object({ topic: z.string(), title: z.string(), markdown: z.string() });
+const topicPattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function docsWarning(message, hint) {
+    return { message, hint, warning: true };
+}
+async function answeredFindings(kernel, list, get) {
+    let answer;
+    try {
+        answer = await kernel.exec(list, {});
+    }
+    catch (error) {
+        if (error instanceof ProblemError)
+            return [docsWarning(`${list} fails with ${error.problem.code}: ${error.problem.message}`, 'docs.list must answer [{ topic, title }].')];
+        throw error;
+    }
+    const listed = listAnswerSchema.safeParse(answer);
+    if (!listed.success)
+        return [docsWarning(`${list} answers something other than [{ topic, title }].`, 'docs.list must answer [{ topic, title }].')];
+    const findings = [];
+    for (const entry of listed.data) {
+        if (!topicPattern.test(entry.topic)) {
+            findings.push(docsWarning(`The docs topic "${entry.topic}" isn't a lowercase kebab-case segment.`, 'Use lowercase letters, digits, and single hyphens, such as getting-started.'));
+            continue;
+        }
+        let page;
+        try {
+            page = await kernel.exec(get, { topic: entry.topic });
+        }
+        catch (error) {
+            if (error instanceof ProblemError) {
+                findings.push(docsWarning(`${get} fails for the topic "${entry.topic}" with ${error.problem.code}: ${error.problem.message}`, 'Every topic that docs.list answers must be answered by docs.get.'));
+                continue;
+            }
+            throw error;
+        }
+        if (!pageAnswerSchema.safeParse(page).success) {
+            findings.push(docsWarning(`${get} answers something other than { topic, title, markdown } for "${entry.topic}".`, 'Every topic that docs.list answers must be answered by docs.get.'));
+        }
+    }
+    return findings;
+}
+/** The docs-pair warnings of the extension's `queries` (plan 09 §9.5): none when neither query is registered. */
+export async function docsFindings(kernel, namespace, queries) {
+    const list = `${namespace}.docs.list`;
+    const get = `${namespace}.docs.get`;
+    const hasList = queries.some((query) => query.name === list);
+    const hasGet = queries.some((query) => query.name === get);
+    if (!hasList && !hasGet)
+        return [];
+    if (!hasList || !hasGet) {
+        const only = hasList ? list : get;
+        return [docsWarning(`Only ${only} is registered; kvcustomizer and kvman-docs show an extension's docs only when it has both ${list} and ${get}.`, 'Register the other as a public query, or remove this one.')];
+    }
+    const privateOnes = [list, get].filter((name) => !queries.some((query) => query.name === name && query.public));
+    if (privateOnes.length > 0) {
+        return privateOnes.map((name) => docsWarning(`${name} isn't public, so kvcustomizer and kvman-docs can't read it.`, 'Add public: true to its registration.'));
+    }
+    return answeredFindings(kernel, list, get);
+}
+//# sourceMappingURL=docs-findings.js.map

package/dist/check/docs-findings.js.map

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

package/dist/check/field-descriptions.d.ts

@@ -0,0 +1,8 @@
+import type { CheckedFinding } from './finding.ts';
+export type Registration = {
+    name: string;
+    public: boolean;
+    input: unknown;
+};
+export declare function fieldFindings(registrations: readonly Registration[]): CheckedFinding[];
+//# sourceMappingURL=field-descriptions.d.ts.map

package/dist/check/field-descriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-descriptions.d.ts","sourceRoot":"","sources":["../../src/check/field-descriptions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAKnD,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAI7E,wBAAgB,aAAa,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,GAAG,cAAc,EAAE,CActF"}

package/dist/check/field-descriptions.js

@@ -0,0 +1,19 @@
+import { z } from '@kvman/sdk';
+const objectSchema = z.object({ properties: z.record(z.string(), z.object({ description: z.string().optional() }).loose()) }).loose();
+export function fieldFindings(registrations) {
+    return registrations
+        .filter((registration) => registration.public)
+        .flatMap((registration) => {
+        const parsed = objectSchema.safeParse(registration.input);
+        if (!parsed.success)
+            return [];
+        return Object.entries(parsed.data.properties)
+            .filter(([, field]) => field.description === undefined)
+            .map(([field]) => ({
+            message: `The input field ${field} of ${registration.name} has no description.`,
+            hint: `Add .describe('…') to ${field}: forms label the field with it, and connector -h shows it.`,
+            warning: false,
+        }));
+    });
+}
+//# sourceMappingURL=field-descriptions.js.map

package/dist/check/field-descriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-descriptions.js","sourceRoot":"","sources":["../../src/check/field-descriptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,YAAY,CAAC;AAQ/B,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;AAEtI,MAAM,UAAU,aAAa,CAAC,aAAsC;IAClE,OAAO,aAAa;SACjB,MAAM,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC;SAC7C,OAAO,CAAC,CAAC,YAAY,EAAE,EAAE;QACxB,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC1D,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;aAC1C,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC;aACtD,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YACjB,OAAO,EAAE,mBAAmB,KAAK,OAAO,YAAY,CAAC,IAAI,sBAAsB;YAC/E,IAAI,EAAE,yBAAyB,KAAK,6DAA6D;YACjG,OAAO,EAAE,KAAK;SACf,CAAC,CAAC,CAAC;IACR,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/check/finding.d.ts

@@ -0,0 +1,11 @@
+/** One thing `kvman-check` found (ADR 0009, 116): `file` is relative to the project, with `:line:col` when it has one. */
+export type Finding = {
+    file?: string;
+    message: string;
+    hint: string;
+};
+/** A finding and whether it's only a warning, which doesn't fail the check. */
+export type CheckedFinding = Finding & {
+    warning: boolean;
+};
+//# sourceMappingURL=finding.d.ts.map

package/dist/check/finding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding.d.ts","sourceRoot":"","sources":["../../src/check/finding.ts"],"names":[],"mappings":"AAAA,0HAA0H;AAC1H,MAAM,MAAM,OAAO,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC"}

package/dist/check/finding.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=finding.js.map

package/dist/check/finding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding.js","sourceRoot":"","sources":["../../src/check/finding.ts"],"names":[],"mappings":""}

package/dist/check/locale-keys.d.ts

@@ -0,0 +1,7 @@
+import type { CheckedFinding } from './finding.ts';
+export type RequiredKey = {
+    key: string;
+    usedBy: string;
+};
+export declare function localeFindings(folder: string, required: readonly RequiredKey[]): CheckedFinding[];
+//# sourceMappingURL=locale-keys.d.ts.map

package/dist/check/locale-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale-keys.d.ts","sourceRoot":"","sources":["../../src/check/locale-keys.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAMnD,MAAM,MAAM,WAAW,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAoB1D,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,cAAc,EAAE,CAkBjG"}

package/dist/check/locale-keys.js

@@ -0,0 +1,40 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from '@kvman/sdk';
+const catalogSchema = z.record(z.string(), z.string());
+const hint = {
+    parity: 'Add the key to every catalog, so each language shows the same texts.',
+    required: 'Add the key to every catalog; without it the UI shows the key itself.',
+};
+function catalogs(folder) {
+    const found = new Map([['en', new Set()]]);
+    const locales = path.join(folder, 'locales');
+    if (!existsSync(locales))
+        return found;
+    for (const file of readdirSync(locales).filter((name) => name.endsWith('.json')).sort()) {
+        const keys = Object.keys(catalogSchema.parse(JSON.parse(readFileSync(path.join(locales, file), 'utf8'))));
+        found.set(file.slice(0, -'.json'.length), new Set(keys));
+    }
+    return found;
+}
+export function localeFindings(folder, required) {
+    const shipped = catalogs(folder);
+    const everyKey = [...new Set([...shipped.values()].flatMap((keys) => [...keys]))].sort();
+    const findings = [];
+    for (const [language, keys] of shipped) {
+        const file = `locales/${language}.json`;
+        for (const key of everyKey.filter((candidate) => !keys.has(candidate))) {
+            const holders = [...shipped].filter(([, other]) => other.has(key)).map(([other]) => `locales/${other}.json`);
+            findings.push({ file, message: `${file} lacks ${key}, which ${holders.join(' and ')} has.`, hint: hint.parity, warning: false });
+        }
+        const seen = new Set();
+        for (const { key, usedBy } of required) {
+            if (seen.has(key) || everyKey.includes(key))
+                continue;
+            seen.add(key);
+            findings.push({ file, message: `${file} lacks ${key} (used by ${usedBy}).`, hint: hint.required, warning: false });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=locale-keys.js.map

package/dist/check/locale-keys.js.map

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

package/dist/check/timer-scan.d.ts

@@ -0,0 +1,6 @@
+import type { CheckedFinding } from './finding.ts';
+export declare function blankCommentsAndStrings(source: string): string;
+export declare function scanTimers(file: string, source: string): CheckedFinding[];
+/** The timer warnings of the project's `src/**\/*.ts`; none when it has no `src`. */
+export declare function scanProjectTimers(folder: string): CheckedFinding[];
+//# sourceMappingURL=timer-scan.d.ts.map

package/dist/check/timer-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer-scan.d.ts","sourceRoot":"","sources":["../../src/check/timer-scan.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAwBnD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAsB9D;AAaD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAWzE;AAWD,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAGlE"}

package/dist/check/timer-scan.js

@@ -0,0 +1,84 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+// The timer warnings (plan 02 §2.2, ADR 0009, 116): a text scan of `src/**/*.ts` with comments skipped. Every
+// `setInterval(` warns, and every `setTimeout(` whose statement doesn't start with `await`, as
+// `await new Promise((resolve) => setTimeout(resolve, ms))` does. It's a scan, not a parser, so it only warns.
+const hint = {
+    interval: 'Repeated work goes to ctx.schedule; a handler\'s work ends when it returns.',
+    timeout: 'Await the timer inside the handler, or move the delayed work to ctx.execAsync or ctx.schedule.',
+};
+function commentEnd(source, index) {
+    if (source.startsWith('//', index)) {
+        const end = source.indexOf('\n', index);
+        return end === -1 ? source.length : end;
+    }
+    if (source.startsWith('/*', index)) {
+        const end = source.indexOf('*/', index + 2);
+        return end === -1 ? source.length : end + 2;
+    }
+    return null;
+}
+// Comments and string contents become spaces, so positions keep their line and column and no text inside them matches.
+export function blankCommentsAndStrings(source) {
+    let result = '';
+    let index = 0;
+    while (index < source.length) {
+        const end = commentEnd(source, index);
+        if (end !== null) {
+            result += source.slice(index, end).replace(/[^\n]/g, ' ');
+            index = end;
+            continue;
+        }
+        const char = source[index] ?? '';
+        if (char === '"' || char === "'" || char === '`') {
+            let close = index + 1;
+            while (close < source.length && source[close] !== char)
+                close += source[close] === '\\' ? 2 : 1;
+            result += char + source.slice(index + 1, close).replace(/[^\n]/g, ' ') + (close < source.length ? char : '');
+            index = close + 1;
+            continue;
+        }
+        result += char;
+        index += 1;
+    }
+    return result;
+}
+function statementStart(text, at) {
+    let start = at;
+    while (start > 0 && !';{}'.includes(text[start - 1] ?? ''))
+        start -= 1;
+    return text.slice(start, at).trimStart();
+}
+function position(text, at) {
+    const before = text.slice(0, at).split('\n');
+    return `${String(before.length)}:${String((before.at(-1) ?? '').length + 1)}`;
+}
+export function scanTimers(file, source) {
+    const text = blankCommentsAndStrings(source);
+    const findings = [];
+    for (const match of text.matchAll(/\bset(Interval|Timeout)\s*\(/g)) {
+        const interval = match[1] === 'Interval';
+        if (!interval && statementStart(text, match.index).startsWith('await'))
+            continue;
+        const call = interval ? 'setInterval' : 'setTimeout';
+        const message = interval ? `Warning: ${call} keeps running after the handler returns.` : `Warning: an unawaited ${call} outlives its handler.`;
+        findings.push({ file: `${file}:${position(text, match.index)}`, message, hint: interval ? hint.interval : hint.timeout, warning: true });
+    }
+    return findings;
+}
+function sourceFiles(folder, relative) {
+    const entries = readdirSync(path.join(folder, relative), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    return entries.flatMap((entry) => {
+        const child = path.posix.join(relative, entry.name);
+        if (entry.isDirectory())
+            return entry.name === 'node_modules' ? [] : sourceFiles(folder, child);
+        return entry.name.endsWith('.ts') ? [child] : [];
+    });
+}
+/** The timer warnings of the project's `src/**\/*.ts`; none when it has no `src`. */
+export function scanProjectTimers(folder) {
+    if (!existsSync(path.join(folder, 'src')))
+        return [];
+    return sourceFiles(folder, 'src').flatMap((file) => scanTimers(file, readFileSync(path.join(folder, file), 'utf8')));
+}
+//# sourceMappingURL=timer-scan.js.map