toolcraft 0.0.93 → 0.0.94

package/dist/testing/harness.js

@@ -0,0 +1,391 @@
+import { stripAnsi } from "toolcraft-design";
+import { ApprovalDeclinedError, ToolcraftBugError, UserError, assertCommandRequirements, resolveCommandSecrets } from "../index.js";
+import { approvalStateMachine } from "../human-in-loop/state-machine.js";
+import { invokeWithHumanInLoop } from "../human-in-loop/gate.js";
+import { createRuntimeLogger } from "../runtime-logging.js";
+import { createEnv, createFs, validateServices } from "../runtime/io.js";
+import { filterSchemaForScope } from "../schema-scope.js";
+import { validateObjectSchema } from "../sdk.js";
+import { throwValidationErrors } from "../validation-errors.js";
+import { fakeFetch } from "./fakes.js";
+import { createMemoryFs } from "./memory-fs.js";
+import { runParity } from "./parity.js";
+import { createRenderCapture } from "./render-capture.js";
+function isHandlerFs(value) {
+    return typeof value.readFile === "function";
+}
+function asMemoryFs(value) {
+    if (value === undefined || !isHandlerFs(value)) {
+        return createMemoryFs(value);
+    }
+    if ("snapshot" in value && "changes" in value) {
+        return value;
+    }
+    const handlerFs = createFs(value);
+    const changes = [];
+    return {
+        readFile: (path, encoding) => handlerFs.readFile(path, encoding),
+        exists: (path) => handlerFs.exists(path),
+        lstat: (path) => handlerFs.lstat(path),
+        async writeFile(path, contents, options) {
+            await handlerFs.writeFile(path, contents, options);
+            changes.push({ op: "writeFile", path });
+        },
+        async rename(fromPath, toPath) {
+            await handlerFs.rename(fromPath, toPath);
+            changes.push({ op: "rename", path: fromPath, to: toPath });
+        },
+        async unlink(path) {
+            await handlerFs.unlink(path);
+            changes.push({ op: "unlink", path });
+        },
+        snapshot: () => ({}),
+        changes: () => changes.map((change) => ({ ...change }))
+    };
+}
+function hasOwnMcpProxyConfig(group) {
+    const symbol = Object.getOwnPropertySymbols(group).find((candidate) => candidate.description === "toolcraft.group.config");
+    if (symbol === undefined) {
+        return false;
+    }
+    const config = group[symbol];
+    return config?.mcp !== undefined;
+}
+function findChild(group, segment) {
+    return group.children.find((child) => child.name === segment || child.aliases.includes(segment));
+}
+function resolveCommand(root, requestedPath) {
+    const path = requestedPath[0] === root.name ? requestedPath.slice(1) : requestedPath;
+    let group = root;
+    const canonicalPath = [];
+    for (let index = 0; index < path.length; index += 1) {
+        if (hasOwnMcpProxyConfig(group)) {
+            throw new UserError(`Commands under MCP proxy group "${group.name}" need a live server.`);
+        }
+        const segment = path[index];
+        const child = findChild(group, segment);
+        if (child === undefined) {
+            throw new UserError(`Unknown command path "${requestedPath.join(" ")}".`);
+        }
+        canonicalPath.push(child.name);
+        if (child.kind === "command") {
+            if (index !== path.length - 1) {
+                throw new UserError(`Command "${canonicalPath.join(" ")}" has no child commands.`);
+            }
+            return { command: child, path: canonicalPath };
+        }
+        group = child;
+    }
+    if (hasOwnMcpProxyConfig(group)) {
+        throw new UserError(`Commands under MCP proxy group "${group.name}" need a live server.`);
+    }
+    if (group.default !== undefined) {
+        return { command: group.default, path: [...canonicalPath, group.default.name] };
+    }
+    throw new UserError(`Command path "${requestedPath.join(" ")}" resolves to a group.`);
+}
+function createSealedEnv(declarations, env, secrets) {
+    const values = { ...(env ?? {}) };
+    for (const [name, value] of Object.entries(secrets ?? {})) {
+        const definition = declarations[name];
+        if (definition !== undefined) {
+            values[definition.env] = value;
+        }
+    }
+    return Object.freeze(values);
+}
+function isHumanInLoopPending(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.status === "pending-approval");
+}
+function createTaskList() {
+    const tasksById = new Map();
+    const tasks = {
+        name: "approvals",
+        stateMachine: approvalStateMachine,
+        async all() {
+            return [...tasksById.values()];
+        },
+        async get(id) {
+            const task = tasksById.get(id);
+            if (task === undefined) {
+                throw new Error(`Unknown task ${id}`);
+            }
+            return task;
+        },
+        async create(input) {
+            const id = input.id ?? String(tasksById.size + 1);
+            const task = {
+                list: "approvals",
+                id,
+                qualifiedId: `approvals:${id}`,
+                name: input.name,
+                state: approvalStateMachine.initial,
+                description: input.description ?? "",
+                metadata: input.metadata ?? {}
+            };
+            tasksById.set(id, task);
+            return task;
+        },
+        async update(id, patch) {
+            const task = await tasks.get(id);
+            Object.assign(task, patch);
+            return task;
+        },
+        async fire(id) {
+            return tasks.get(id);
+        },
+        async canFire() {
+            return false;
+        },
+        async events() {
+            return [];
+        },
+        async delete(id) {
+            tasksById.delete(id);
+        },
+        async move(id) {
+            return tasks.get(id);
+        },
+        async reorder(ids) {
+            return Promise.all(ids.map((id) => tasks.get(id)));
+        }
+    };
+    return {
+        list: () => tasks,
+        async lists() {
+            return ["approvals"];
+        },
+        async allTasks() {
+            return tasks.all();
+        },
+        async get(qualifiedId) {
+            return tasks.get(qualifiedId.split(":").at(-1) ?? qualifiedId);
+        },
+        async moveBetweenLists(qualifiedId) {
+            return this.get(qualifiedId);
+        }
+    };
+}
+export function createCommandTestHarness(root, options = {}) {
+    const services = options.services ?? {};
+    validateServices(services);
+    const memoryFs = asMemoryFs(options.fs);
+    const runtimeFetch = Array.isArray(options.fetch)
+        ? fakeFetch(options.fetch)
+        : (options.fetch ?? fakeFetch([]));
+    const cumulativeTimeline = [];
+    let sequence = 0;
+    const append = (runTimeline, event) => {
+        const sequenced = { seq: ++sequence, ...event };
+        runTimeline.push(sequenced);
+        cumulativeTimeline.push(sequenced);
+    };
+    return {
+        fs: memoryFs,
+        timeline: cumulativeTimeline,
+        async parity(requestedPath, inputParams = {}) {
+            const resolved = resolveCommand(root, requestedPath);
+            const sealedEnv = createSealedEnv(resolved.command.secrets, options.env, options.secrets);
+            return runParity(root, resolved, inputParams, {
+                services,
+                env: Object.fromEntries(Object.entries(sealedEnv).flatMap(([key, value]) => value === undefined ? [] : [[key, value]])),
+                fs: memoryFs,
+                fetch: runtimeFetch,
+                apiVersion: options.apiVersion
+            });
+        },
+        async run(requestedPath, inputParams = {}) {
+            const logs = [];
+            const progress = [];
+            const confirmations = [];
+            const timeline = [];
+            const rendered = {};
+            const initialChangeCount = memoryFs.changes().length;
+            let stage = "resolve";
+            let value;
+            const result = (overrides = {}) => ({
+                ok: false,
+                value,
+                error: undefined,
+                failedAt: stage,
+                pending: false,
+                logs,
+                progress,
+                confirmations,
+                timeline,
+                fsChanges: memoryFs.changes().slice(initialChangeCount),
+                rendered,
+                ...overrides
+            });
+            try {
+                const resolved = resolveCommand(root, requestedPath);
+                const command = resolved.command;
+                const commandPath = resolved.path.join(".");
+                stage = "secrets";
+                const sealedEnv = createSealedEnv(command.secrets, options.env, options.secrets);
+                const commandSecrets = resolveCommandSecrets(command, sealedEnv);
+                const diagnostics = createRuntimeLogger({
+                    level: options.logLevel ?? "debug",
+                    logger: (event) => logs.push(event)
+                });
+                const instrumentedFs = {
+                    readFile: (path, encoding) => memoryFs.readFile(path, encoding),
+                    exists: (path) => memoryFs.exists(path),
+                    lstat: (path) => memoryFs.lstat(path),
+                    async writeFile(path, contents, fsOptions) {
+                        await memoryFs.writeFile(path, contents, fsOptions);
+                        append(timeline, { kind: "fs", op: "writeFile", path });
+                    },
+                    async rename(fromPath, toPath) {
+                        await memoryFs.rename(fromPath, toPath);
+                        append(timeline, { kind: "fs", op: "rename", path: fromPath });
+                    },
+                    async unlink(path) {
+                        await memoryFs.unlink(path);
+                        append(timeline, { kind: "fs", op: "unlink", path });
+                    }
+                };
+                const instrumentedFetch = async (input, init) => {
+                    const request = new Request(input, init);
+                    append(timeline, {
+                        kind: "fetch",
+                        method: request.method,
+                        url: request.url
+                    });
+                    return runtimeFetch(request);
+                };
+                const instrumentedServices = Object.fromEntries(Object.entries(services).map(([serviceName, service]) => {
+                    if ((typeof service !== "object" || service === null) &&
+                        typeof service !== "function") {
+                        return [serviceName, service];
+                    }
+                    return [
+                        serviceName,
+                        new Proxy(service, {
+                            get(target, property, receiver) {
+                                const member = Reflect.get(target, property, receiver);
+                                if (typeof member !== "function") {
+                                    return member;
+                                }
+                                return (...args) => {
+                                    append(timeline, {
+                                        kind: "service",
+                                        service: serviceName,
+                                        method: String(property),
+                                        args
+                                    });
+                                    return Reflect.apply(member, receiver, args);
+                                };
+                            }
+                        })
+                    ];
+                }));
+                const baseContext = {
+                    ...instrumentedServices,
+                    secrets: commandSecrets,
+                    fetch: instrumentedFetch,
+                    fs: instrumentedFs,
+                    env: createEnv(new Proxy(sealedEnv, {
+                        get(target, property, receiver) {
+                            if (typeof property === "string") {
+                                append(timeline, { kind: "env", key: property });
+                            }
+                            return Reflect.get(target, property, receiver);
+                        }
+                    })),
+                    diagnostics,
+                    progress(message) {
+                        progress.push(message);
+                        append(timeline, { kind: "progress", message });
+                    }
+                };
+                stage = "requirements";
+                await assertCommandRequirements(command, { ...baseContext, params: undefined }, { apiVersion: options.apiVersion, env: sealedEnv });
+                stage = "params";
+                const schema = filterSchemaForScope(command.params, "sdk");
+                if (schema === undefined || schema.kind !== "object") {
+                    throw new ToolcraftBugError(`command "${command.name}" must define an object params schema for SDK.`);
+                }
+                const errors = [];
+                const params = validateObjectSchema(schema, inputParams, "", errors);
+                throwValidationErrors(errors);
+                const decide = async (request) => {
+                    confirmations.push(request);
+                    const approved = options.confirmations === "decline"
+                        ? false
+                        : typeof options.confirmations === "function"
+                            ? await options.confirmations(request)
+                            : true;
+                    append(timeline, { kind: "confirm", message: request.message, approved });
+                    return approved;
+                };
+                stage = "confirm";
+                if (command.confirm && !command.humanInLoop) {
+                    if (!(await decide({ message: "Proceed?" }))) {
+                        throw new ApprovalDeclinedError({ commandPath });
+                    }
+                }
+                const provider = {
+                    id: "toolcraft-test-harness",
+                    async requestApproval(request) {
+                        return (await decide({
+                            message: request.message,
+                            declineInputPrompt: request.declineInputPrompt
+                        }))
+                            ? { outcome: "approved" }
+                            : { outcome: "declined" };
+                    }
+                };
+                const commandWithTrackedHandler = {
+                    ...command,
+                    async handler(context) {
+                        stage = "handler";
+                        return command.handler(context);
+                    }
+                };
+                const invoked = await invokeWithHumanInLoop(commandWithTrackedHandler, { ...baseContext, params }, { provider, taskList: createTaskList() }, commandPath, {
+                    spawnRunner: false,
+                    async enqueueApproval({ tasks, payload }) {
+                        const approvalId = `test-harness:${payload.commandPath}`;
+                        const pending = {
+                            status: "pending-approval",
+                            approvalId,
+                            message: payload.message,
+                            enqueuedAt: ""
+                        };
+                        await tasks.create({
+                            id: approvalId,
+                            name: payload.commandPath,
+                            metadata: { ...payload, approvalId, enqueuedAt: "" }
+                        });
+                        return { approvalId, pending };
+                    }
+                });
+                value = invoked;
+                if (isHumanInLoopPending(invoked)) {
+                    return result({ ok: true, failedAt: undefined, pending: true });
+                }
+                stage = "render";
+                if (command.render?.rich) {
+                    const capture = createRenderCapture();
+                    command.render.rich(invoked, capture.primitives);
+                    rendered.rich = capture.output();
+                }
+                if (command.render?.markdown) {
+                    const capture = createRenderCapture();
+                    rendered.markdown = stripAnsi(command.render.markdown(invoked, capture.primitives));
+                }
+                if (command.render?.json) {
+                    const capture = createRenderCapture();
+                    rendered.json = command.render.json(invoked, capture.primitives);
+                }
+                return result({ ok: true, failedAt: undefined });
+            }
+            catch (error) {
+                return result({ error });
+            }
+        }
+    };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,4 @@
+export { createCommandTestHarness, type CommandTestHarness, type ConfirmationRequest, type EffectEvent, type HarnessOptions, type PipelineStage, type RunResult } from "./harness.js";
+export { fakeFetch, fakeService, type FetchRoute, type ServiceCall } from "./fakes.js";
+export { createMemoryFs, type FsChange, type MemoryFs } from "./memory-fs.js";
+export type { ParityResult, SurfaceOutcome } from "./parity.js";

package/dist/testing/index.js

@@ -0,0 +1,3 @@
+export { createCommandTestHarness } from "./harness.js";
+export { fakeFetch, fakeService } from "./fakes.js";
+export { createMemoryFs } from "./memory-fs.js";

package/dist/testing/memory-fs.d.ts

@@ -0,0 +1,11 @@
+import type { HandlerFs } from "../index.js";
+export type FsChange = {
+    op: "writeFile" | "rename" | "unlink";
+    path: string;
+    to?: string;
+};
+export interface MemoryFs extends HandlerFs {
+    snapshot(): Record<string, string>;
+    changes(): FsChange[];
+}
+export declare function createMemoryFs(files?: Record<string, string>): MemoryFs;

package/dist/testing/memory-fs.js

@@ -0,0 +1,61 @@
+function missingFileError(syscall, path, dest) {
+    const target = dest === undefined ? `'${path}'` : `'${path}' -> '${dest}'`;
+    const error = new Error(`ENOENT: no such file or directory, ${syscall} ${target}`);
+    error.code = "ENOENT";
+    error.errno = -2;
+    error.path = path;
+    error.syscall = syscall;
+    if (dest !== undefined) {
+        error.dest = dest;
+    }
+    return error;
+}
+export function createMemoryFs(files = {}) {
+    const contents = new Map(Object.entries(files).map(([path, value]) => [path, Buffer.from(value, "utf8")]));
+    const changeLog = [];
+    return {
+        async readFile(path, encoding = "utf8") {
+            const value = contents.get(path);
+            if (value === undefined) {
+                throw missingFileError("open", path);
+            }
+            return value.toString(encoding);
+        },
+        async writeFile(path, value, options) {
+            contents.set(path, Buffer.from(value, options?.encoding ?? "utf8"));
+            changeLog.push({ op: "writeFile", path });
+        },
+        async exists(path) {
+            return contents.has(path);
+        },
+        async lstat(path) {
+            if (!contents.has(path)) {
+                throw missingFileError("lstat", path);
+            }
+            return { isSymbolicLink: () => false };
+        },
+        async rename(fromPath, toPath) {
+            const value = contents.get(fromPath);
+            if (value === undefined) {
+                throw missingFileError("rename", fromPath, toPath);
+            }
+            if (fromPath !== toPath) {
+                contents.set(toPath, value);
+                contents.delete(fromPath);
+            }
+            changeLog.push({ op: "rename", path: fromPath, to: toPath });
+        },
+        async unlink(path) {
+            if (!contents.delete(path)) {
+                throw missingFileError("unlink", path);
+            }
+            changeLog.push({ op: "unlink", path });
+        },
+        snapshot() {
+            return Object.fromEntries(Array.from(contents, ([path, value]) => [path, value.toString("utf8")]));
+        },
+        changes() {
+            return changeLog.map((change) => ({ ...change }));
+        }
+    };
+}

package/dist/testing/parity.d.ts

@@ -0,0 +1,25 @@
+import type { Command, Group, HandlerFs } from "../index.js";
+export interface SurfaceOutcome {
+    ok: boolean;
+    value: unknown;
+    error: unknown;
+}
+export interface ParityResult {
+    sdk: SurfaceOutcome;
+    mcp: SurfaceOutcome;
+    cli: SurfaceOutcome;
+    agree: boolean;
+    diff?: string;
+}
+export interface ParityOptions<TServices extends object> {
+    services: TServices;
+    env?: Record<string, string>;
+    fs: HandlerFs;
+    fetch: typeof globalThis.fetch;
+    apiVersion?: string;
+}
+export interface ParityCommand {
+    command: Command<any, any, any, any>;
+    path: string[];
+}
+export declare function runParity<TServices extends object>(root: Group<any>, resolved: ParityCommand, params: Record<string, unknown>, options: ParityOptions<TServices>): Promise<ParityResult>;