toolcraft 0.0.93 → 0.0.95

package/dist/runtime/io.js

@@ -0,0 +1,50 @@
+import { access, lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
+export const RESERVED_SERVICE_NAMES = new Set([
+    "params",
+    "secrets",
+    "fetch",
+    "fs",
+    "env",
+    "diagnostics",
+    "progress",
+    "runtimeOptions",
+    "root"
+]);
+const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
+export function createFs(fs) {
+    if (fs !== undefined) {
+        return fs;
+    }
+    return {
+        readFile: async (path, encoding = "utf8") => readFile(path, { encoding }),
+        writeFile: async (path, contents, options) => {
+            await writeFile(path, contents, options);
+        },
+        exists: async (path) => {
+            try {
+                await access(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        lstat: async (path) => lstat(path),
+        rename: async (fromPath, toPath) => rename(fromPath, toPath),
+        unlink: async (path) => unlink(path)
+    };
+}
+export function createEnv(values = process.env) {
+    return {
+        get(key) {
+            return values[key];
+        }
+    };
+}
+export function validateServices(services) {
+    for (const name of Object.keys(services)) {
+        if (RESERVED_SERVICE_NAMES.has(name)) {
+            throw new Error(`Service name "${name}" is reserved. Choose a different name. ${RESERVED_SERVICE_NAMES_MESSAGE}`);
+        }
+    }
+}

package/dist/sdk.d.ts

@@ -1,7 +1,8 @@
 import type { ObjectSchema, Static } from "toolcraft-schema";
-import type { Group, LogLevel, RuntimeLoggerInput, Scope } from "./index.js";
+import type { Group, HandlerFs, LogLevel, RuntimeLoggerInput, Scope } from "./index.js";
 import { type ErrorReportsOption } from "./error-report.js";
 import type { HumanInLoopPending, HumanInLoopRuntimeOptions } from "./human-in-loop/index.js";
+import { type ValidationError } from "./validation-errors.js";
 type ScopeInput = readonly Scope[] | undefined;
 type HumanInLoopMode = "sync" | "async";
 type HumanInLoopModeInput = HumanInLoopMode | null | undefined;
@@ -30,7 +31,7 @@ type CamelCase<TValue extends string> = JoinCamelWords<SplitCamelWords<TValue>>;
 type Camelize<TValue> = TValue extends Primitive ? TValue : TValue extends readonly (infer TItem)[] ? Array<Camelize<TItem>> : TValue extends object ? {
     [TKey in keyof TValue as TKey extends string ? CamelCase<TKey> : TKey]: Camelize<TValue[TKey]>;
 } : TValue;
-type SDKResult<TResult, THumanInLoopMode extends HumanInLoopMode | undefined> = THumanInLoopMode extends "async" ? HumanInLoopPending : TResult;
+type SDKResult<TResult, THumanInLoopMode extends HumanInLoopMode | undefined> = [THumanInLoopMode] extends ["async"] ? ["async"] extends [THumanInLoopMode] ? HumanInLoopPending : TResult : TResult;
 type SDKMethod<TParamsSchema extends ObjectSchema<any>, TResult> = (params: Camelize<Static<TParamsSchema>>) => Promise<TResult>;
 type UnionToIntersection<TValue> = (TValue extends unknown ? (value: TValue) => void : never) extends (value: infer TResult) => void ? TResult : never;
 type Simplify<TValue> = {
@@ -62,7 +63,9 @@ type SDKNodeShape<TNode, TInheritedScope extends ScopeInput, TInheritedHumanInLo
 type SDKChildrenShape<TChildren, TInheritedScope extends ScopeInput, TInheritedHumanInLoopMode extends HumanInLoopMode | undefined> = Simplify<UnionToIntersection<SDKNodeShape<RawChildrenValue<TChildren>, TInheritedScope, TInheritedHumanInLoopMode>>>;
 export interface CreateSDKOptions<TServices extends object = Record<string, unknown>> {
     approvals?: boolean;
+    env?: Record<string, string>;
     fetch?: typeof globalThis.fetch;
+    fs?: HandlerFs;
     services?: TServices;
     casing?: "camel";
     humanInLoop?: HumanInLoopRuntimeOptions;
@@ -72,10 +75,11 @@ export interface CreateSDKOptions<TServices extends object = Record<string, unkn
     logLevel?: LogLevel;
     logger?: RuntimeLoggerInput;
 }
-export declare function createSDK<TRootInfo, TServices extends object = Record<string, unknown>>(root: Group<any> & {
-    readonly __agentKitGroupTypeInfo: TRootInfo;
-}, options?: CreateSDKOptions<TServices>): TRootInfo extends {
-    children: infer TChildren extends readonly unknown[];
-} ? SDKChildrenShape<TChildren, undefined, undefined> : EmptyRecord;
-export declare function createSDK<TServices extends object = Record<string, unknown>>(root: Group<TServices>, options?: CreateSDKOptions<TServices>): Record<string, unknown>;
+export declare function validateObjectSchema(schema: ObjectSchema<any>, value: unknown, label: string, errors: ValidationError[]): Record<string, unknown>;
+type SDKRootShape<TRoot> = TRoot extends {
+    readonly __agentKitGroupTypeInfo: {
+        children: infer TChildren extends readonly unknown[];
+    };
+} ? SDKChildrenShape<TChildren, undefined, undefined> : Record<string, unknown>;
+export declare function createSDK<TRoot extends Group<any>, TServices extends object = Record<string, unknown>>(root: TRoot, options?: CreateSDKOptions<TServices>): SDKRootShape<TRoot>;
 export {};

package/dist/sdk.js

@@ -1,4 +1,3 @@
-import { access, lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { ToolcraftBugError, UserError, assertCommandRequirements, resolveCommandSecrets } from "./index.js";
 import { writeErrorReport } from "./error-report.js";
 import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
@@ -10,18 +9,7 @@ import { enableSourceMaps } from "./stack-trim.js";
 import { suggest } from "./suggest.js";
 import { throwValidationErrors } from "./validation-errors.js";
 import { createRuntimeLogger } from "./runtime-logging.js";
-const RESERVED_SERVICE_NAMES = new Set([
-    "params",
-    "secrets",
-    "fetch",
-    "fs",
-    "env",
-    "diagnostics",
-    "progress",
-    "runtimeOptions",
-    "root"
-]);
-const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
+import { createEnv, createFs, validateServices } from "./runtime/io.js";
 function splitWords(value) {
     const words = [];
     let current = "";
@@ -73,40 +61,6 @@ function isOptional(schema) {
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function createFs() {
-    return {
-        readFile: async (path, encoding = "utf8") => readFile(path, { encoding }),
-        writeFile: async (path, contents, options) => {
-            await writeFile(path, contents, options);
-        },
-        exists: async (path) => {
-            try {
-                await access(path);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        },
-        lstat: async (path) => lstat(path),
-        rename: async (fromPath, toPath) => rename(fromPath, toPath),
-        unlink: async (path) => unlink(path)
-    };
-}
-function createEnv(values = process.env) {
-    return {
-        get(key) {
-            return values[key];
-        }
-    };
-}
-function validateServices(services) {
-    for (const name of Object.keys(services)) {
-        if (RESERVED_SERVICE_NAMES.has(name)) {
-            throw new Error(`Service name "${name}" is reserved. Choose a different name. ${RESERVED_SERVICE_NAMES_MESSAGE}`);
-        }
-    }
-}
 function formatAvailableList(values) {
     return `Available: ${[...values].sort().join(", ")}.`;
 }
@@ -260,7 +214,7 @@ function validateArrayConstraints(schema, value, label, errors) {
         });
     }
 }
-function validateObjectSchema(schema, value, label, errors) {
+export function validateObjectSchema(schema, value, label, errors) {
     if (!isPlainObject(value)) {
         errors.push({
             path: label,
@@ -381,22 +335,23 @@ function createResolvedSDK(root, options = {}) {
                 let secrets;
                 let validatedParams;
                 try {
-                    secrets = resolveCommandSecrets(node);
+                    secrets = resolveCommandSecrets(node, options.env);
                     const baseContext = {
                         ...services,
                         runtimeOptions,
                         root,
                         secrets,
                         fetch: runtimeFetch,
-                        fs: createFs(),
-                        env: createEnv(),
+                        fs: createFs(options.fs),
+                        env: createEnv(options.env),
                         diagnostics,
                         progress(message) {
                             diagnostics.emit({ level: "info", message, category: "progress" });
                         }
                     };
                     await assertCommandRequirements(node, { ...baseContext, params: undefined }, {
-                        apiVersion: options.apiVersion
+                        apiVersion: options.apiVersion,
+                        env: options.env
                     });
                     const paramsSchema = filterSchemaForScope(node.params, "sdk");
                     if (paramsSchema === undefined || paramsSchema.kind !== "object") {

package/dist/task-list.d.ts

@@ -0,0 +1 @@
+export * from "@poe-code/task-list";

package/dist/task-list.js

@@ -0,0 +1 @@
+export * from "@poe-code/task-list";

package/dist/testing/fakes.d.ts

@@ -0,0 +1,20 @@
+export interface ServiceCall {
+    method: string;
+    args: unknown[];
+    result?: unknown;
+    error?: unknown;
+}
+export interface FetchRoute {
+    method?: string;
+    url: string | ((url: string) => boolean);
+    status?: number;
+    json?: unknown;
+    text?: string;
+    error?: Error;
+}
+export declare function fakeService<T extends object>(stubs?: Partial<T>): T & {
+    calls: ServiceCall[];
+};
+export declare function fakeFetch(routes: FetchRoute[]): typeof globalThis.fetch & {
+    calls: Request[];
+};

package/dist/testing/fakes.js

@@ -0,0 +1,83 @@
+function isPromiseLike(value) {
+    return (((typeof value === "object" && value !== null) || typeof value === "function") &&
+        typeof value.then === "function");
+}
+export function fakeService(stubs = {}) {
+    const calls = [];
+    return new Proxy(stubs, {
+        get(target, property, receiver) {
+            if (property === "calls") {
+                return calls;
+            }
+            const stub = Reflect.get(target, property, receiver);
+            if (typeof stub !== "function") {
+                if (stub !== undefined) {
+                    return stub;
+                }
+                return (...args) => {
+                    const method = String(property);
+                    const error = new Error(`Unstubbed service method "${method}" was called.`);
+                    calls.push({ method, args, error });
+                    throw error;
+                };
+            }
+            return (...args) => {
+                const method = String(property);
+                const call = { method, args };
+                calls.push(call);
+                try {
+                    const result = Reflect.apply(stub, receiver, args);
+                    if (!isPromiseLike(result)) {
+                        call.result = result;
+                        return result;
+                    }
+                    return Promise.resolve(result).then((value) => {
+                        call.result = value;
+                        return value;
+                    }, (error) => {
+                        call.error = error;
+                        throw error;
+                    });
+                }
+                catch (error) {
+                    call.error = error;
+                    throw error;
+                }
+            };
+        }
+    });
+}
+function routeDescription(route) {
+    const method = route.method?.toUpperCase() ?? "*";
+    const url = typeof route.url === "string" ? route.url : "<predicate>";
+    return `${method} ${url}`;
+}
+function routeMatches(route, request) {
+    if (route.method !== undefined && route.method.toUpperCase() !== request.method.toUpperCase()) {
+        return false;
+    }
+    return typeof route.url === "string" ? route.url === request.url : route.url(request.url);
+}
+export function fakeFetch(routes) {
+    const calls = [];
+    const fetch = async (input, init) => {
+        const request = new Request(input, init);
+        calls.push(request);
+        const route = routes.find((candidate) => routeMatches(candidate, request));
+        if (route === undefined) {
+            const configuredRoutes = routes.map(routeDescription).join(", ") || "none";
+            throw new Error(`No fake fetch route matched ${request.method} ${request.url}. Configured routes: ${configuredRoutes}.`);
+        }
+        if (route.error !== undefined) {
+            throw route.error;
+        }
+        if (Object.hasOwn(route, "json")) {
+            return new Response(JSON.stringify(route.json), {
+                status: route.status ?? 200,
+                headers: { "content-type": "application/json" }
+            });
+        }
+        return new Response(route.text ?? null, { status: route.status ?? 200 });
+    };
+    return Object.assign(fetch, { calls });
+}

package/dist/testing/fixtures.d.ts

@@ -0,0 +1,8 @@
+import { type Group } from "../index.js";
+export interface FixtureService {
+    execute(value: string): Promise<string>;
+}
+export interface FixtureServices {
+    fakeService: FixtureService;
+}
+export declare function createHarnessFixtureGroup(): Group<FixtureServices>;

package/dist/testing/fixtures.js

@@ -0,0 +1,248 @@
+import { S } from "toolcraft-schema";
+import { NotFoundError, UserError, defineCommand, defineGroup } from "../index.js";
+const emptyParams = S.Object({});
+function defineFixtureCommand(config) {
+    return defineCommand(config);
+}
+export function createHarnessFixtureGroup() {
+    const params = defineFixtureCommand({
+        name: "params",
+        params: S.Object({
+            name: S.String(),
+            count: S.Optional(S.Number({ default: 2 }))
+        }),
+        handler: async ({ params: values }) => values
+    });
+    const secrets = defineFixtureCommand({
+        name: "secrets",
+        params: emptyParams,
+        secrets: {
+            required: { env: "FIXTURE_REQUIRED_SECRET" },
+            optional: { env: "FIXTURE_OPTIONAL_SECRET", optional: true }
+        },
+        handler: async ({ secrets: values }) => values
+    });
+    const otherSecrets = defineFixtureCommand({
+        name: "other-secrets",
+        params: emptyParams,
+        secrets: {
+            required: { env: "FIXTURE_OTHER_REQUIRED_SECRET" }
+        },
+        handler: async ({ secrets: values }) => values
+    });
+    const auth = defineFixtureCommand({
+        name: "auth",
+        params: emptyParams,
+        requires: { auth: true },
+        handler: async () => "authenticated"
+    });
+    const check = defineFixtureCommand({
+        name: "check",
+        params: emptyParams,
+        requires: {
+            check: async () => ({ ok: false, message: "Fixture check failed." })
+        },
+        handler: async () => "checked"
+    });
+    const confirm = defineFixtureCommand({
+        name: "confirm",
+        params: emptyParams,
+        confirm: true,
+        handler: async () => "confirmed"
+    });
+    const humanInLoop = defineFixtureCommand({
+        name: "human-in-loop",
+        params: S.Object({ target: S.String() }),
+        humanInLoop: {
+            mode: "sync",
+            message: ({ params: values }) => `Deploy ${values.target}?`
+        },
+        handler: async () => "deployed"
+    });
+    const humanInLoopPath = defineFixtureCommand({
+        name: "human-in-loop-path",
+        params: emptyParams,
+        humanInLoop: {
+            mode: "sync",
+            message: ({ commandPath }) => `Approve ${commandPath}?`
+        },
+        handler: async () => "approved"
+    });
+    const asyncHumanInLoop = defineFixtureCommand({
+        name: "async-human-in-loop",
+        params: S.Object({ target: S.String() }),
+        humanInLoop: {
+            mode: "async",
+            message: ({ params: values }) => `Queue ${values.target}?`
+        },
+        handler: async () => "deployed"
+    });
+    const rich = defineFixtureCommand({
+        name: "rich",
+        params: emptyParams,
+        handler: async () => ({ value: "rich" }),
+        render: {
+            rich: (result, primitives) => {
+                primitives.logger.info(`\u001b[31m${result.value}\u001b[0m`);
+                primitives.logger.info(primitives.getTheme().intro("intro"));
+                primitives.logger.info(primitives.renderTable({
+                    theme: primitives.getTheme(),
+                    variant: "detail",
+                    maxWidth: 24,
+                    columns: [
+                        { name: "label", title: "Label", alignment: "left", maxLen: 11 },
+                        { name: "value", title: "Value", alignment: "left", maxLen: 8 }
+                    ],
+                    rows: [
+                        {
+                            label: "Description",
+                            value: "A deterministic renderer wraps this detail using a fixed eighty-column width."
+                        }
+                    ]
+                }));
+                primitives.note("captured note", "Capture");
+            }
+        }
+    });
+    const markdown = defineFixtureCommand({
+        name: "markdown",
+        params: emptyParams,
+        handler: async () => ({ value: "markdown" }),
+        render: {
+            markdown: (result, primitives) => primitives.getTheme().header(`# ${result.value}`)
+        }
+    });
+    const json = defineFixtureCommand({
+        name: "json",
+        params: emptyParams,
+        handler: async () => ({ value: "json" }),
+        render: {
+            json: (result, primitives) => ({ value: primitives.getTheme().success(result.value) })
+        }
+    });
+    const renderError = defineFixtureCommand({
+        name: "render-error",
+        params: emptyParams,
+        handler: async () => "handled",
+        render: {
+            rich: (_result, primitives) => primitives.logger.info("rendered before failure"),
+            markdown: () => {
+                throw new Error("Fixture renderer failed.");
+            }
+        }
+    });
+    const service = defineFixtureCommand({
+        name: "service",
+        params: S.Object({ value: S.String() }),
+        handler: async ({ fakeService, params: values }) => fakeService.execute(values.value)
+    });
+    const fs = defineFixtureCommand({
+        name: "fs",
+        params: emptyParams,
+        handler: async ({ fs: handlerFs }) => {
+            await handlerFs.writeFile("/result.txt", "written");
+            return "written";
+        }
+    });
+    const fsRoundTrip = defineFixtureCommand({
+        name: "fs-roundtrip",
+        params: emptyParams,
+        handler: async ({ fs: handlerFs }) => {
+            await handlerFs.writeFile("/roundtrip.txt", "written");
+            return handlerFs.readFile("/roundtrip.txt");
+        }
+    });
+    const effects = defineFixtureCommand({
+        name: "effects",
+        params: emptyParams,
+        handler: async (context) => {
+            context.diagnostics.emit({ level: "debug", message: "starting effects" });
+            const envValue = context.env.get("FIXTURE_VALUE");
+            context.progress("halfway");
+            const serviceValue = await context.fakeService.execute(envValue ?? "missing");
+            const response = await context.fetch("https://fixture.test/value", { method: "POST" });
+            await context.fs.writeFile("/effects.txt", await response.text());
+            return serviceValue;
+        }
+    });
+    const alias = defineFixtureCommand({
+        name: "canonical",
+        aliases: ["alias"],
+        params: emptyParams,
+        handler: async () => "alias"
+    });
+    const hidden = defineFixtureCommand({
+        name: "hidden",
+        hidden: true,
+        params: emptyParams,
+        handler: async () => "hidden"
+    });
+    const defaultCommand = defineFixtureCommand({
+        name: "show",
+        params: emptyParams,
+        handler: async () => "default"
+    });
+    const nested = defineGroup({
+        name: "nested",
+        children: [defaultCommand],
+        default: defaultCommand
+    });
+    const deferred = defineGroup({
+        name: "deferred",
+        mcp: { transport: "stdio", command: "fixture-server" },
+        children: []
+    });
+    const userError = defineFixtureCommand({
+        name: "user-error",
+        params: emptyParams,
+        handler: async () => {
+            throw new UserError("Fixture user error.");
+        }
+    });
+    const notFound = defineFixtureCommand({
+        name: "not-found",
+        params: emptyParams,
+        handler: async () => {
+            throw new NotFoundError({
+                request: { method: "GET", url: "https://fixture.test/missing", headers: {} },
+                response: { status: 404, statusText: "Not Found", headers: {}, body: null }
+            });
+        }
+    });
+    const plainError = defineFixtureCommand({
+        name: "plain-error",
+        params: emptyParams,
+        handler: async () => {
+            throw new Error("Fixture plain error.");
+        }
+    });
+    return defineGroup({
+        name: "fixture",
+        children: [
+            params,
+            secrets,
+            otherSecrets,
+            auth,
+            check,
+            confirm,
+            humanInLoop,
+            humanInLoopPath,
+            asyncHumanInLoop,
+            rich,
+            markdown,
+            json,
+            renderError,
+            service,
+            fs,
+            fsRoundTrip,
+            effects,
+            alias,
+            hidden,
+            nested,
+            deferred,
+            userError,
+            notFound,
+            plainError
+        ]
+    });
+}

package/dist/testing/harness.d.ts

@@ -0,0 +1,76 @@
+import { type Group, type HandlerFs } from "../index.js";
+import { type DiagnosticLogEvent, type LogLevel } from "../runtime-logging.js";
+import { type FetchRoute } from "./fakes.js";
+import { type FsChange, type MemoryFs } from "./memory-fs.js";
+import { type ParityResult } from "./parity.js";
+export type PipelineStage = "resolve" | "secrets" | "requirements" | "params" | "confirm" | "handler" | "render";
+export type EffectEvent = {
+    seq: number;
+    kind: "fetch";
+    method: string;
+    url: string;
+} | {
+    seq: number;
+    kind: "fs";
+    op: "writeFile" | "rename" | "unlink";
+    path: string;
+} | {
+    seq: number;
+    kind: "service";
+    service: string;
+    method: string;
+    args: unknown[];
+} | {
+    seq: number;
+    kind: "env";
+    key: string;
+} | {
+    seq: number;
+    kind: "progress";
+    message: string;
+} | {
+    seq: number;
+    kind: "confirm";
+    message: string;
+    approved: boolean;
+};
+export interface ConfirmationRequest {
+    message: string;
+    declineInputPrompt?: string;
+}
+export interface HarnessOptions<TServices extends object> {
+    services?: TServices;
+    env?: Record<string, string | undefined>;
+    secrets?: Record<string, string>;
+    fs?: Record<string, string> | HandlerFs;
+    fetch?: typeof globalThis.fetch | FetchRoute[];
+    confirmations?: "approve" | "decline" | ((request: ConfirmationRequest) => boolean | Promise<boolean>);
+    apiVersion?: string;
+    logLevel?: LogLevel;
+}
+export interface RunResult<T> {
+    ok: boolean;
+    value?: T;
+    error?: unknown;
+    failedAt?: PipelineStage;
+    pending: boolean;
+    logs: DiagnosticLogEvent[];
+    progress: string[];
+    confirmations: ConfirmationRequest[];
+    timeline: EffectEvent[];
+    fsChanges: FsChange[];
+    rendered: {
+        rich?: string;
+        markdown?: string;
+        json?: unknown;
+    };
+}
+export interface CommandTestHarness {
+    run<T>(path: string[], params?: Record<string, unknown>): Promise<RunResult<T>>;
+    parity(path: string[], params?: Record<string, unknown>): Promise<ParityResult>;
+    fs: MemoryFs;
+    timeline: EffectEvent[];
+}
+type EmptyHarnessServices = Record<string, never>;
+export declare function createCommandTestHarness<TServices extends object = EmptyHarnessServices>(root: Group, options?: HarnessOptions<TServices>): CommandTestHarness;
+export {};