@kvman/testkit 0.1.0

package/dist/preview/preview-port.js

@@ -0,0 +1,22 @@
+import { createServer } from 'node:net';
+import { BinFailure } from "../bin/bin-failure.js";
+// The preview's port (plan 09 §9.3): the first free port from 3738 to 3837 on 127.0.0.1, which is the only address
+// the bin ever binds (CLAUDE.md §6).
+export const firstPreviewPort = 3738;
+export const lastPreviewPort = 3837;
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+    });
+}
+/** The first free preview port, or `NO_FREE_PORT` when 3738 to 3837 are all taken. */
+export async function previewPort(isFree = isPortFree) {
+    for (let port = firstPreviewPort; port <= lastPreviewPort; port += 1) {
+        if (await isFree(port))
+            return port;
+    }
+    throw new BinFailure('NO_FREE_PORT', 'Ports 3738 to 3837 are all taken; stop something that listens on one.');
+}
+//# sourceMappingURL=preview-port.js.map

package/dist/preview/preview-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-port.js","sourceRoot":"","sources":["../../src/preview/preview-port.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,mHAAmH;AACnH,qCAAqC;AAErC,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,SAA6C,UAAU;IACvF,KAAK,IAAI,IAAI,GAAG,gBAAgB,EAAE,IAAI,IAAI,eAAe,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QACrE,IAAI,MAAM,MAAM,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACtC,CAAC;IACD,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,uEAAuE,CAAC,CAAC;AAChH,CAAC"}

package/dist/preview/preview-preset.d.ts

@@ -0,0 +1,14 @@
+import type { Preset } from '@kvman/sdk';
+/** An extension folder to preview, by package name. */
+export type PreviewExtension = {
+    name: string;
+    folder: string;
+};
+/** A preset the preview builds on, with the folder its `path:` entries resolve against. */
+export type GivenPreset = {
+    preset: Preset;
+    folder: string;
+};
+/** Builds the preview's preset from the dev extensions, optionally over a given preset. */
+export declare function previewPreset(extensions: readonly PreviewExtension[], given?: GivenPreset): Preset;
+//# sourceMappingURL=preview-preset.d.ts.map

package/dist/preview/preview-preset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-preset.d.ts","sourceRoot":"","sources":["../../src/preview/preview-preset.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,2FAA2F;AAC3F,MAAM,MAAM,WAAW,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAQ7D,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM,CAMlG"}

package/dist/preview/preview-preset.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+function absoluteSources(given) {
+    return Object.fromEntries(Object.entries(given.preset.extensions).map(([name, source]) => [name, source.startsWith('path:') ? `path:${path.resolve(given.folder, source.slice('path:'.length))}` : source]));
+}
+/** Builds the preview's preset from the dev extensions, optionally over a given preset. */
+export function previewPreset(extensions, given) {
+    const dev = Object.fromEntries(extensions.map((extension) => [extension.name, `path:${extension.folder}`]));
+    if (given === undefined) {
+        return { name: 'preview', extensions: { '@kvman/kvai': 'bundled', '@kvman/kvwebui': 'bundled', ...dev }, settings: { 'kvwebui.home': 'kvwebui.extensions' } };
+    }
+    return { ...given.preset, extensions: { ...absoluteSources(given), ...dev } };
+}
+//# sourceMappingURL=preview-preset.js.map

package/dist/preview/preview-preset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-preset.js","sourceRoot":"","sources":["../../src/preview/preview-preset.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAa7B,SAAS,eAAe,CAAC,KAAkB;IACzC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAClL,CAAC;AACJ,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,aAAa,CAAC,UAAuC,EAAE,KAAmB;IACxF,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAA8B,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACxI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,EAAE,SAAS,EAAE,GAAG,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,cAAc,EAAE,oBAAoB,EAAE,EAAE,CAAC;IAChK,CAAC;IACD,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC,EAAE,GAAG,GAAG,EAAE,EAAE,CAAC;AAChF,CAAC"}

package/dist/preview/preview-run.d.ts

@@ -0,0 +1,14 @@
+/** What the preview runs: folders resolved against the current working folder, preset and entry files with them. */
+export type PreviewRunOptions = {
+    /** Extension project folders, resolved against the current working folder. */
+    folders: readonly string[];
+    /** A preset file the preview builds on, or `undefined` for the generated one. */
+    preset?: string | undefined;
+    /** The kvman entry file to run, or `undefined` for the `kvman` on the PATH. */
+    kvman?: string | undefined;
+    /** Names the home `<os temp>/kvman-preview-<name>`. */
+    name: string;
+};
+/** Runs the preview until SIGINT or SIGTERM, or the preview kvman exits; failures are `BinFailure`s. */
+export declare function runPreview(options: PreviewRunOptions, onReady: (url: string) => void): Promise<void>;
+//# sourceMappingURL=preview-run.d.ts.map

package/dist/preview/preview-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-run.d.ts","sourceRoot":"","sources":["../../src/preview/preview-run.ts"],"names":[],"mappings":"AA2BA,oHAAoH;AACpH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAwLF,wGAAwG;AACxG,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAiC1G"}

package/dist/preview/preview-run.js

@@ -0,0 +1,241 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { envelopeSchema, healthSchema, presetSchema, z } from '@kvman/sdk';
+import { BinFailure } from "../bin/bin-failure.js";
+import { lastLines, runProgram } from "../bin/run-program.js";
+import { preparePreviewHome } from "./preview-home.js";
+import { readPreviewProject } from "./preview-manifest.js";
+import { previewPort } from "./preview-port.js";
+import { previewPreset } from "./preview-preset.js";
+import { isRunning, killProcessTree, spawnCommand, stopPreviewChild, trackChild } from "./process-tree.js";
+// `kvman-preview`'s run (plan 09 §9.3, ADR 0010, 7, 21): a fresh home and generated preset, one `web:build` then a
+// `web:watch` child per project that has one, the preview kvman as a child, and its URL once it answers
+// `kernel.health.get`. `shutdown` stops the preview, the watchers, and removes the home on every exit path, so no
+// child or home is ever left behind. The readiness poll and the preview's stop wait are the only timers.
+const readyWithinMs = 30_000;
+const pollEveryMs = 200;
+const stopPreviewWithinMs = 10_000;
+const maxPreviewOutput = 65_536;
+function hasCode(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+function checkProjects(folders) {
+    return folders.map((folder) => {
+        const project = readPreviewProject(path.resolve(folder));
+        if (project === undefined)
+            throw new BinFailure('VALIDATION_FAILED', `${folder} has no package.json with a kvman field.`, { folder });
+        return { given: folder, absolute: path.resolve(folder), name: project.name, webWatch: project.webWatch };
+    });
+}
+function readGivenPreset(file) {
+    if (file === undefined)
+        return undefined;
+    const absolute = path.resolve(file);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(absolute, 'utf8'));
+    }
+    catch {
+        throw new BinFailure('VALIDATION_FAILED', `The preset ${file} is invalid; run kvman-preset check on it.`, { preset: file });
+    }
+    const parsed = presetSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new BinFailure('VALIDATION_FAILED', `The preset ${file} is invalid; run kvman-preset check on it.`, { preset: file });
+    return { preset: parsed.data, folder: path.dirname(absolute) };
+}
+function checkKvmanEntry(entry) {
+    if (entry === undefined)
+        return undefined;
+    if (!existsSync(path.resolve(entry))) {
+        throw new BinFailure('VALIDATION_FAILED', `The kvman entry ${entry} doesn't exist; pass the entry file of the kvman to run.`, { kvman: entry });
+    }
+    return path.resolve(entry);
+}
+function waitForSignals() {
+    const listeners = new Set();
+    let fired = false;
+    const fire = () => {
+        if (fired)
+            return;
+        fired = true;
+        for (const listener of [...listeners])
+            listener();
+    };
+    const onSigint = () => fire();
+    const onSigterm = () => fire();
+    process.on('SIGINT', onSigint);
+    process.on('SIGTERM', onSigterm);
+    return {
+        signalled: () => fired,
+        onSignal: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        dispose: () => {
+            process.off('SIGINT', onSigint);
+            process.off('SIGTERM', onSigterm);
+            listeners.clear();
+        },
+    };
+}
+async function answers(url) {
+    let response;
+    try {
+        response = await fetch(`${url}api/queries/kernel.health.get`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: '{"input":{}}',
+            signal: AbortSignal.timeout(pollEveryMs * 5),
+        });
+    }
+    catch (error) {
+        // A refused connection is a TypeError; a preview that accepts and never replies ends the attempt with a TimeoutError.
+        if (error instanceof TypeError || (error instanceof DOMException && error.name === 'TimeoutError'))
+            return false;
+        throw error;
+    }
+    if (!response.ok)
+        return false;
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return false;
+    }
+    const parsed = envelopeSchema({ output: healthSchema, jobId: z.string() }).safeParse(body);
+    return parsed.success && parsed.data.ok;
+}
+function previewStopped(state) {
+    const preview = state.preview;
+    if (preview === undefined || isRunning(preview))
+        return undefined;
+    if (state.kvmanFromPath && preview.spawnError !== undefined && hasCode(preview.spawnError, 'ENOENT')) {
+        return new BinFailure('PREVIEW_FAILED', `kvman isn't on the PATH; install it with npm i -g kvman, or pass --kvman <entry>.`);
+    }
+    return new BinFailure('PREVIEW_FAILED', `The preview kvman exited before it answered:\n${lastLines(state.previewOutput())}`);
+}
+async function waitUntilReady(url, state, signals) {
+    const deadline = Date.now() + readyWithinMs;
+    while (Date.now() < deadline) {
+        if (signals.signalled())
+            return false;
+        if (await answers(url))
+            return true;
+        const stopped = previewStopped(state);
+        if (stopped !== undefined)
+            throw stopped;
+        if (signals.signalled())
+            return false;
+        await delay(pollEveryMs);
+    }
+    throw new BinFailure('PREVIEW_FAILED', `The preview kvman didn't answer within 30 s:\n${lastLines(state.previewOutput())}`);
+}
+async function startWatchers(projects, state, signals) {
+    for (const project of projects) {
+        if (!project.webWatch || signals.signalled())
+            continue;
+        const build = await runProgram('npm', ['run', 'web:build'], project.absolute);
+        if (build.exitCode !== 0)
+            throw new BinFailure('PREVIEW_FAILED', `npm run web:build failed in ${project.given}:\n${lastLines(build.output)}`);
+        if (signals.signalled())
+            return;
+        const watch = spawnCommand(process.platform, 'npm', ['run', 'web:watch']);
+        const child = spawn(watch.command, watch.args, { cwd: project.absolute, stdio: 'ignore', detached: watch.detached, windowsHide: true });
+        state.watchers.push(trackChild(child));
+    }
+}
+function startPreviewChild(state, options) {
+    const kvmanArgs = ['--home', options.home, '--port', String(options.port), '--yes', '--no-open', '--preset', options.presetFile];
+    const start = options.kvmanEntry === undefined
+        ? spawnCommand(process.platform, 'kvman', kvmanArgs)
+        : spawnCommand(process.platform, process.execPath, [...process.execArgv, options.kvmanEntry, ...kvmanArgs]);
+    const child = spawn(start.command, start.args, { cwd: process.cwd(), stdio: ['ignore', 'pipe', 'pipe'], detached: start.detached, windowsHide: true });
+    const tracked = trackChild(child);
+    state.preview = tracked;
+    let output = '';
+    const append = (text) => {
+        output += text;
+        if (output.length > maxPreviewOutput)
+            output = output.slice(-maxPreviewOutput);
+    };
+    child.stdout?.setEncoding('utf8').on('data', append);
+    child.stderr?.setEncoding('utf8').on('data', append);
+    state.previewOutput = () => output;
+}
+async function waitWhileRunning(state, signals) {
+    const preview = state.preview;
+    if (preview === undefined || signals.signalled() || !isRunning(preview))
+        return signals.signalled() ? 'signalled' : 'exited';
+    return await new Promise((resolve) => {
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            offSignal();
+            preview.child.off('exit', onExit);
+            preview.child.off('close', onExit);
+            resolve(outcome);
+        };
+        const offSignal = signals.onSignal(() => settle('signalled'));
+        const onExit = () => settle('exited');
+        preview.child.once('exit', onExit);
+        preview.child.once('close', onExit);
+        if (signals.signalled() || !isRunning(preview))
+            settle(signals.signalled() ? 'signalled' : 'exited');
+    });
+}
+// The one stop every exit path uses: the preview first (SIGINT, 10 s, then its group; the tree on Windows), then
+// each `web:watch` tree, then the home.
+async function shutdown(state) {
+    if (state.preview !== undefined)
+        await stopPreviewChild(state.preview, stopPreviewWithinMs);
+    for (const watcher of state.watchers)
+        await killProcessTree(watcher);
+    rmSync(state.home, { recursive: true, force: true });
+}
+/** Runs the preview until SIGINT or SIGTERM, or the preview kvman exits; failures are `BinFailure`s. */
+export async function runPreview(options, onReady) {
+    const projects = checkProjects(options.folders);
+    const given = readGivenPreset(options.preset);
+    const kvmanEntry = checkKvmanEntry(options.kvman);
+    const home = preparePreviewHome(options.name);
+    const state = { home, preview: undefined, previewOutput: () => '', watchers: [], kvmanFromPath: kvmanEntry === undefined };
+    const signals = waitForSignals();
+    let failure;
+    try {
+        const port = await previewPort();
+        const presetFile = path.join(home, 'preview-preset.json');
+        writeFileSync(presetFile, JSON.stringify(previewPreset(projects.map((project) => ({ name: project.name, folder: project.absolute })), given)));
+        if (!signals.signalled()) {
+            await startWatchers(projects, state, signals);
+            if (!signals.signalled()) {
+                startPreviewChild(state, { home, port, presetFile, kvmanEntry });
+                const url = `http://127.0.0.1:${String(port)}/`;
+                if (await waitUntilReady(url, state, signals)) {
+                    onReady(url);
+                    if ((await waitWhileRunning(state, signals)) === 'exited') {
+                        failure = new BinFailure('PREVIEW_FAILED', `The preview kvman exited:\n${lastLines(state.previewOutput())}`);
+                    }
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (!(error instanceof BinFailure))
+            throw error;
+        failure = error;
+    }
+    finally {
+        signals.dispose();
+        await shutdown(state);
+    }
+    if (failure !== undefined)
+        throw failure;
+}
+//# sourceMappingURL=preview-run.js.map

package/dist/preview/preview-run.js.map

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

package/dist/preview/process-tree.d.ts

@@ -0,0 +1,40 @@
+import { type ChildProcess } from 'node:child_process';
+/** How to kill a child's whole process tree: its group on Linux and macOS, `taskkill /T /F` on Windows. */
+export type TreeKill = {
+    kind: 'group';
+    pid: number;
+} | {
+    kind: 'taskkill';
+    command: 'taskkill';
+    args: string[];
+};
+/** How to kill a child's whole process tree, per OS. */
+export declare function treeKill(platform: NodeJS.Platform, pid: number): TreeKill;
+/** How to start `program` with `args`: directly on Linux and macOS, through `cmd.exe /d /s /c` on Windows. */
+export type SpawnCommand = {
+    command: string;
+    args: string[];
+    detached: boolean;
+};
+/** How to start `program` with `args`, per OS. */
+export declare function spawnCommand(platform: NodeJS.Platform, program: string, args: readonly string[]): SpawnCommand;
+/** A spawned child with its exit watched from the start, so stopping it never misses the event it waits for. */
+export type TrackedChild = {
+    /** The child process. */
+    child: ChildProcess;
+    /** Resolves once the child has exited, closed, or failed to spawn. */
+    exited: Promise<void>;
+    /** The spawn failure, when the child never started. */
+    spawnError: unknown;
+};
+/** Tracks `child` from now on: `exited` resolves on its first exit, close, or spawn error. */
+export declare function trackChild(child: ChildProcess): TrackedChild;
+/** Whether the child may still run: no exit, no signal, and no spawn failure. */
+export declare function isRunning(tracked: TrackedChild): boolean;
+/** Kills a child's whole process tree and resolves once it has exited. */
+export declare function killProcessTree(tracked: TrackedChild): Promise<void>;
+/** Resolves whether the child exits within `withinMs`; the wait ends on the exit, never on a fixed sleep. */
+export declare function exitWithin(tracked: TrackedChild, withinMs: number): Promise<boolean>;
+/** Stops a preview child: SIGINT first (it stops on it), then SIGKILL to its group; on Windows the tree is killed. */
+export declare function stopPreviewChild(tracked: TrackedChild, withinMs: number): Promise<void>;
+//# sourceMappingURL=process-tree.d.ts.map

package/dist/preview/process-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-tree.d.ts","sourceRoot":"","sources":["../../src/preview/process-tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAM9D,2GAA2G;AAC3G,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAElH,wDAAwD;AACxD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAKzE;AAED,8GAA8G;AAC9G,MAAM,MAAM,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAElF,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,CAK9G;AAMD,gHAAgH;AAChH,MAAM,MAAM,YAAY,GAAG;IACzB,yBAAyB;IACzB,KAAK,EAAE,YAAY,CAAC;IACpB,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,uDAAuD;IACvD,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,8FAA8F;AAC9F,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAa5D;AAED,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAExD;AAED,0EAA0E;AAC1E,wBAAsB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB1E;AAED,6GAA6G;AAC7G,wBAAgB,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASpF;AAED,sHAAsH;AACtH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS7F"}

package/dist/preview/process-tree.js

@@ -0,0 +1,92 @@
+import { spawn } from 'node:child_process';
+/** How to kill a child's whole process tree, per OS. */
+export function treeKill(platform, pid) {
+    if (platform === 'win32')
+        return { kind: 'taskkill', command: 'taskkill', args: ['/PID', String(pid), '/T', '/F'] };
+    if (platform === 'darwin')
+        return { kind: 'group', pid };
+    if (platform === 'linux')
+        return { kind: 'group', pid };
+    return { kind: 'group', pid };
+}
+/** How to start `program` with `args`, per OS. */
+export function spawnCommand(platform, program, args) {
+    if (platform === 'win32')
+        return { command: 'cmd.exe', args: ['/d', '/s', '/c', program, ...args], detached: false };
+    if (platform === 'darwin')
+        return { command: program, args: [...args], detached: true };
+    if (platform === 'linux')
+        return { command: program, args: [...args], detached: true };
+    return { command: program, args: [...args], detached: true };
+}
+function hasCode(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+/** Tracks `child` from now on: `exited` resolves on its first exit, close, or spawn error. */
+export function trackChild(child) {
+    let resolveExited = () => { };
+    const exited = new Promise((resolve) => {
+        resolveExited = resolve;
+    });
+    const tracked = { child, exited, spawnError: undefined };
+    child.once('error', (error) => {
+        tracked.spawnError = error;
+        resolveExited();
+    });
+    child.once('exit', () => resolveExited());
+    child.once('close', () => resolveExited());
+    return tracked;
+}
+/** Whether the child may still run: no exit, no signal, and no spawn failure. */
+export function isRunning(tracked) {
+    return tracked.child.exitCode === null && tracked.child.signalCode === null && tracked.spawnError === undefined;
+}
+/** Kills a child's whole process tree and resolves once it has exited. */
+export async function killProcessTree(tracked) {
+    if (tracked.child.pid !== undefined) {
+        const kill = treeKill(process.platform, tracked.child.pid);
+        if (kill.kind === 'taskkill') {
+            await new Promise((resolve) => {
+                const taskkill = spawn(kill.command, kill.args, { stdio: 'ignore', windowsHide: true });
+                taskkill.once('error', () => resolve());
+                taskkill.once('close', () => resolve());
+            });
+        }
+        else {
+            try {
+                process.kill(-kill.pid, 'SIGKILL');
+            }
+            catch (error) {
+                if (!hasCode(error, 'ESRCH'))
+                    throw error;
+            }
+        }
+    }
+    await tracked.exited;
+}
+/** Resolves whether the child exits within `withinMs`; the wait ends on the exit, never on a fixed sleep. */
+export function exitWithin(tracked, withinMs) {
+    let timer;
+    const done = tracked.exited.then(() => true);
+    const timedOut = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), withinMs);
+    });
+    return Promise.race([done, timedOut]).finally(() => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
+}
+/** Stops a preview child: SIGINT first (it stops on it), then SIGKILL to its group; on Windows the tree is killed. */
+export async function stopPreviewChild(tracked, withinMs) {
+    if (!isRunning(tracked))
+        return;
+    if (process.platform === 'win32') {
+        await killProcessTree(tracked);
+        return;
+    }
+    tracked.child.kill('SIGINT');
+    if (await exitWithin(tracked, withinMs))
+        return;
+    await killProcessTree(tracked);
+}
+//# sourceMappingURL=process-tree.js.map

package/dist/preview/process-tree.js.map

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

package/dist/running/call-query.d.ts

@@ -0,0 +1,5 @@
+import { z, type Json } from '@kvman/sdk';
+import { type RunningKvman } from './running-kvman.ts';
+/** Calls a public query on the running kvman and returns its validated output. */
+export declare function callQuery<Output>(running: RunningKvman, name: string, input: Json, outputSchema: z.ZodType<Output>): Promise<Output>;
+//# sourceMappingURL=call-query.d.ts.map

package/dist/running/call-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-query.d.ts","sourceRoot":"","sources":["../../src/running/call-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,CAAC,EAAE,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAyB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAc9E,kFAAkF;AAClF,wBAAsB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAe1I"}

package/dist/running/call-query.js

@@ -0,0 +1,34 @@
+import { envelopeSchema, ProblemError, z } from '@kvman/sdk';
+import { KvmanUnreachableError } from "./running-kvman.js";
+// Calling the running kvman (plan 04 §4.1–4.2): `POST /api/queries/<name>` with `{ input }` and no `Origin` header,
+// answered with the envelope. A refused connection means it isn't running.
+function isConnectionRefused(error) {
+    let current = error;
+    while (current instanceof Error) {
+        if ('code' in current && current.code === 'ECONNREFUSED')
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+/** Calls a public query on the running kvman and returns its validated output. */
+export async function callQuery(running, name, input, outputSchema) {
+    let response;
+    try {
+        response = await fetch(`${running.baseUrl}/api/queries/${name}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ input }),
+        });
+    }
+    catch (error) {
+        if (isConnectionRefused(error))
+            throw new KvmanUnreachableError(`The kvman at ${running.baseUrl} refused the connection.`);
+        throw error;
+    }
+    const answer = envelopeSchema({ output: outputSchema, jobId: z.string() }).parse(await response.json());
+    if (!answer.ok)
+        throw new ProblemError(answer.problem);
+    return answer.output;
+}
+//# sourceMappingURL=call-query.js.map

package/dist/running/call-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-query.js","sourceRoot":"","sources":["../../src/running/call-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,EAAa,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAqB,MAAM,oBAAoB,CAAC;AAE9E,oHAAoH;AACpH,2EAA2E;AAE3E,SAAS,mBAAmB,CAAC,KAAc;IACzC,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,OAAO,OAAO,YAAY,KAAK,EAAE,CAAC;QAChC,IAAI,MAAM,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,cAAc;YAAE,OAAO,IAAI,CAAC;QACtE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,SAAS,CAAS,OAAqB,EAAE,IAAY,EAAE,KAAW,EAAE,YAA+B;IACvH,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,CAAC,OAAO,gBAAgB,IAAI,EAAE,EAAE;YAC/D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC;SAChC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,mBAAmB,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,qBAAqB,CAAC,gBAAgB,OAAO,CAAC,OAAO,0BAA0B,CAAC,CAAC;QAC3H,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,cAAc,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACxG,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,IAAI,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvD,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC"}

package/dist/running/running-kvman.d.ts

@@ -0,0 +1,14 @@
+/** A kvman that answers queries over HTTP. */
+export type RunningKvman = {
+    baseUrl: string;
+};
+/** The kvman can't be reached; the caller treats it as not running. */
+export declare class KvmanUnreachableError extends Error {
+    constructor(message: string);
+}
+/** Finds the running kvman: `undefined` when no lock file, stale lock, or portless lock says one runs. */
+export declare function findRunningKvman(options: {
+    home?: string;
+    url?: string;
+}): RunningKvman | undefined;
+//# sourceMappingURL=running-kvman.d.ts.map

package/dist/running/running-kvman.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"running-kvman.d.ts","sourceRoot":"","sources":["../../src/running/running-kvman.ts"],"names":[],"mappings":"AASA,8CAA8C;AAC9C,MAAM,MAAM,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C,uEAAuE;AACvE,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AA0DD,0GAA0G;AAC1G,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,GAAG,SAAS,CAInG"}