toolcraft 0.0.23 → 0.0.25

package/README.md

@@ -211,8 +211,8 @@ defineCommand({
     apiVersion: ">=1.2.0", // fails if runner reports older apiVersion
     check: async (ctx) => ({
       // arbitrary async gate
-      ok: ctx.fs.exists(".lock") === false,
-      message: ".lock present, refusing to run"
+      ok: ctx.fs.exists("READY") === true,
+      message: "READY marker missing, refusing to run"
     })
   }
 });

package/dist/cli.compile-check.js

@@ -13,6 +13,7 @@ const ignoredRoot = defineGroup({
     children: [ignoredCommand],
 });
 const ignoredOptions = {
+    approvals: false,
     casing: "kebab",
     humanInLoop: {},
     version: "1.0.0",

package/dist/cli.d.ts

@@ -4,6 +4,7 @@ import type { HumanInLoopRuntimeOptions } from "./human-in-loop/index.js";
 type Casing = "kebab" | "snake";
 export interface RunCLIOptions<TServices extends object = Record<string, unknown>> {
     apiVersion?: string;
+    approvals?: boolean;
     casing?: Casing;
     humanInLoop?: HumanInLoopRuntimeOptions;
     projectRoot?: string;

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { access, readFile, writeFile } from "node:fs/promises";
+import { access, lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { Command as CommanderCommand, CommanderError, InvalidArgumentError, Option } from "commander";
 import { cancel, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderTable, resetOutputFormatCache, select, text } from "@poe-code/design-system";
@@ -608,10 +608,27 @@ function createOption(field, globalLongOptionFlags) {
     return [option];
 }
 const ALWAYS_GLOBAL_LONG_OPTION_FLAGS = ["--yes", "--output", "--debug", "--verbose"];
-function getGlobalLongOptionFlags(presetsEnabled) {
-    return new Set(presetsEnabled
+function getGlobalLongOptionFlags(presetsEnabled, versionEnabled = false) {
+    const flags = presetsEnabled
         ? ["--preset", ...ALWAYS_GLOBAL_LONG_OPTION_FLAGS]
-        : ALWAYS_GLOBAL_LONG_OPTION_FLAGS);
+        : [...ALWAYS_GLOBAL_LONG_OPTION_FLAGS];
+    if (versionEnabled) {
+        flags.push("--version");
+    }
+    return new Set(flags);
+}
+function validateUniqueOptionFlags(fields) {
+    const fieldsByFlag = new Map();
+    for (const field of fields) {
+        if (field.positionalIndex !== undefined) {
+            continue;
+        }
+        const existing = fieldsByFlag.get(field.optionFlag);
+        if (existing !== undefined) {
+            throw new UserError(`Parameters "${existing.displayPath}" and "${field.displayPath}" use conflicting CLI flag "${field.optionFlag}".`);
+        }
+        fieldsByFlag.set(field.optionFlag, field);
+    }
 }
 function createCommanderOption(flags, description, field) {
     const option = new Option(flags, description);
@@ -1011,7 +1028,7 @@ function buildUsageLine(breadcrumb, rootUsageName, suffix) {
 }
 function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUsageName, isRoot) {
     const sections = [];
-    const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled);
+    const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled, globalOptions.showVersion);
     const commandRows = formatCommandRows(group, scope, casing, globalLongOptionFlags);
     if (commandRows.length > 0) {
         sections.push(`${text.sectionHeader("Commands")}\n${formatHelpCommandList(commandRows)}`);
@@ -1037,7 +1054,7 @@ function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUs
 }
 function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageName) {
     const sections = [];
-    const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled);
+    const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled, globalOptions.showVersion);
     const collected = collectFields(command.params, casing, globalLongOptionFlags);
     const fields = assignPositionals(collected.fields, command.positional);
     const optionRows = fields
@@ -1115,6 +1132,7 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
         const command = new CommanderCommand(node.name);
         const collected = collectFields(node.params, casing, globalLongOptionFlags);
         const fields = assignPositionals(collected.fields, node.positional);
+        validateUniqueOptionFlags(fields);
         if (node.description !== undefined) {
             command.description(node.description);
         }
@@ -1213,18 +1231,30 @@ function setNestedValue(target, path, value) {
     let cursor = target;
     for (let index = 0; index < path.length - 1; index += 1) {
         const segment = path[index] ?? "";
-        const existing = cursor[segment];
+        const existing = Object.prototype.hasOwnProperty.call(cursor, segment)
+            ? cursor[segment]
+            : undefined;
         if (typeof existing === "object" && existing !== null) {
             cursor = existing;
             continue;
         }
         const next = {};
-        cursor[segment] = next;
+        Object.defineProperty(cursor, segment, {
+            value: next,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
         cursor = next;
     }
     const leaf = path[path.length - 1];
     if (leaf !== undefined) {
-        cursor[leaf] = value;
+        Object.defineProperty(cursor, leaf, {
+            value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
     }
 }
 function formatResolvedValue(value) {
@@ -1345,7 +1375,10 @@ function createFs() {
             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) {
@@ -1605,7 +1638,10 @@ function createFixtureFs(definition) {
                 return Boolean(existsEntries[filePath]);
             }
             return Object.prototype.hasOwnProperty.call(readFileEntries, filePath);
-        }
+        },
+        lstat: async () => ({ isSymbolicLink: () => false }),
+        rename: async () => undefined,
+        unlink: async () => undefined
     };
 }
 function resolveFixtureMethodResult(methodName, definition, args) {
@@ -2843,7 +2879,8 @@ function configureCommanderSuggestionOutput(command) {
 }
 export async function runCLI(roots, options = {}) {
     enableSourceMaps();
-    const root = mergeApprovalsGroup(normalizeRoots(roots, process.argv));
+    const normalizedRoot = normalizeRoots(roots, process.argv);
+    const root = options.approvals === false ? normalizedRoot : mergeApprovalsGroup(normalizedRoot);
     await resolveMcpProxies(root, { projectRoot: options.projectRoot });
     const casing = options.casing ?? "kebab";
     const services = (options.services ?? {});
@@ -2869,7 +2906,7 @@ export async function runCLI(roots, options = {}) {
     program.showHelpAfterError();
     program.addHelpCommand(false);
     const presetsEnabled = options.presets === true;
-    const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled);
+    const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled, version !== undefined);
     addGlobalOptions(program, presetsEnabled);
     if (version !== undefined) {
         program.version(version, "--version");

package/dist/error-report.js

@@ -1,4 +1,5 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, realpath, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { CommanderError } from "commander";
@@ -46,6 +47,26 @@ function resolveReportDir(option, projectRoot) {
     }
     return path.isAbsolute(configuredDir) ? configuredDir : path.join(projectRoot, configuredDir);
 }
+function reportDirMustStayWithinProject(option) {
+    const configuredDir = typeof option === "object" ? option.dir : undefined;
+    return configuredDir === undefined || configuredDir.length === 0 || !path.isAbsolute(configuredDir);
+}
+function isWithinDirectory(parent, child) {
+    const relative = path.relative(parent, child);
+    return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+async function assertReportDirWithinProject(projectRoot, reportDir) {
+    if (!isWithinDirectory(path.resolve(projectRoot), path.resolve(reportDir))) {
+        throw new Error("Error report directory resolves outside project root.");
+    }
+    const [canonicalProjectRoot, canonicalReportDir] = await Promise.all([
+        realpath(projectRoot),
+        realpath(reportDir)
+    ]);
+    if (!isWithinDirectory(canonicalProjectRoot, canonicalReportDir)) {
+        throw new Error("Error report directory resolves outside project root.");
+    }
+}
 function resolveProjectRoot(projectRoot) {
     if (projectRoot !== undefined) {
         return projectRoot;
@@ -204,7 +225,12 @@ function ownStructuredFields(error) {
         if (key === "name" || key === "message" || key === "stack" || key === "cause") {
             continue;
         }
-        fields[key] = redactStructuredErrorField(key, error[key]);
+        Object.defineProperty(fields, key, {
+            value: redactStructuredErrorField(key, error[key]),
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
     }
     return fields;
 }
@@ -318,9 +344,12 @@ export async function writeErrorReport(context) {
     }
     const projectRoot = resolveProjectRoot(context.projectRoot);
     const reportDir = resolveReportDir(context.errorReports, projectRoot);
-    const fileName = `${formatTimestamp(new Date())}-${slugifyCommandPath(context.commandPath)}.log`;
+    const fileName = `${formatTimestamp(new Date())}-${slugifyCommandPath(context.commandPath)}-${randomUUID()}.log`;
     const absolutePath = path.join(reportDir, fileName);
     await mkdir(reportDir, { recursive: true });
+    if (reportDirMustStayWithinProject(context.errorReports)) {
+        await assertReportDirWithinProject(projectRoot, reportDir);
+    }
     await writeFile(absolutePath, buildReport(context));
     return {
         absolutePath,

package/dist/human-in-loop/approval-tasks.d.ts

@@ -12,6 +12,7 @@ export interface ApprovalPayload {
     error?: unknown;
 }
 export declare function ensureApprovalList(runtimeOptions: HumanInLoopRuntimeOptions | undefined, deps?: {
+    create?: boolean;
     openTaskList?: (options: OpenTaskListOptions) => Promise<TaskList>;
 }): Promise<{
     taskList: TaskList;

package/dist/human-in-loop/approval-tasks.js

@@ -10,7 +10,7 @@ export async function ensureApprovalList(runtimeOptions, deps = {}) {
         throw new UserError("humanInLoop.taskList required for async-mode commands");
     }
     const listName = runtimeOptions.listName ?? DEFAULT_LIST_NAME;
-    const taskList = await resolveTaskList(runtimeOptions, runtimeOptions.taskList, deps.openTaskList ?? openTaskList);
+    const taskList = await resolveTaskList(runtimeOptions, runtimeOptions.taskList, deps.openTaskList ?? openTaskList, deps.create ?? true);
     const tasks = taskList.list(listName);
     if (!isListValidated(runtimeOptions, listName)) {
         if (!isApprovalStateMachine(tasks.stateMachine)) {
@@ -52,21 +52,23 @@ export async function loadApproval(ctx) {
         throw error;
     }
 }
-async function resolveTaskList(runtimeOptions, taskList, openTaskListFn) {
+async function resolveTaskList(runtimeOptions, taskList, openTaskListFn, create) {
     if (!isTaskListConfig(taskList)) {
         return taskList;
     }
-    const cachedTaskList = openedTaskListsByRuntime.get(runtimeOptions);
+    const cachedTaskList = create ? openedTaskListsByRuntime.get(runtimeOptions) : undefined;
     if (cachedTaskList !== undefined) {
         return cachedTaskList;
     }
     const openedTaskList = openTaskListFn({
-        create: true,
+        create,
         type: taskList.format,
         path: taskList.dir,
         stateMachine: approvalStateMachine
     });
-    openedTaskListsByRuntime.set(runtimeOptions, openedTaskList);
+    if (create) {
+        openedTaskListsByRuntime.set(runtimeOptions, openedTaskList);
+    }
     return openedTaskList;
 }
 function cacheValidatedList(runtimeOptions, listName) {

package/dist/human-in-loop/approvals-commands.js

@@ -1,3 +1,4 @@
+import { TaskNotFoundError } from "@poe-code/task-list";
 import { S } from "toolcraft-schema";
 import { UserError, defineCommand, defineGroup } from "../index.js";
 import { ensureApprovalList } from "./approval-tasks.js";
@@ -11,6 +12,13 @@ const listParams = S.Object({
 const showParams = S.Object({
     approvalId: S.String()
 });
+const runParams = S.Object({
+    approvalId: S.String(),
+    dryRun: S.Optional(S.Boolean({
+        description: "Preview the approval without prompting or executing it",
+        scope: ["cli"]
+    }))
+});
 export const approvalsGroup = markApprovalsBuiltIn(defineGroup({
     name: "approvals",
     description: "Inspect and execute queued approvals.",
@@ -21,8 +29,16 @@ export const approvalsGroup = markApprovalsBuiltIn(defineGroup({
             scope: listScope,
             params: listParams,
             handler: async ({ params, runtimeOptions }) => {
-                const { tasks } = await ensureApprovalList(runtimeOptions);
-                return loadApprovals(tasks, params.state);
+                try {
+                    const { tasks } = await ensureApprovalList(runtimeOptions, { create: false });
+                    return loadApprovals(tasks, params.state);
+                }
+                catch (error) {
+                    if (isMissingStateError(error)) {
+                        return [];
+                    }
+                    throw error;
+                }
             },
             render: {
                 rich: (result, primitives) => renderApprovalList(result, primitives),
@@ -36,8 +52,16 @@ export const approvalsGroup = markApprovalsBuiltIn(defineGroup({
             scope: listScope,
             params: showParams,
             handler: async ({ params, runtimeOptions }) => {
-                const { tasks } = await ensureApprovalList(runtimeOptions);
-                return tasks.get(params.approvalId);
+                try {
+                    const { tasks } = await ensureApprovalList(runtimeOptions, { create: false });
+                    return tasks.get(params.approvalId);
+                }
+                catch (error) {
+                    if (isMissingStateError(error)) {
+                        throw new TaskNotFoundError(`Task "approvals/${params.approvalId}" not found.`);
+                    }
+                    throw error;
+                }
             },
             render: {
                 rich: (result, primitives) => renderApprovalDetails(result, primitives),
@@ -49,8 +73,22 @@ export const approvalsGroup = markApprovalsBuiltIn(defineGroup({
             name: "run",
             description: "Run one queued approval.",
             scope: runScope,
-            params: showParams,
-            handler: async ({ params, runtimeOptions, root }) => runApproval(params.approvalId, runtimeOptions, root)
+            params: runParams,
+            handler: async ({ params, runtimeOptions, root }) => {
+                if (params.dryRun === true) {
+                    const { tasks } = await ensureApprovalList(runtimeOptions, { create: false });
+                    return tasks.get(params.approvalId);
+                }
+                return runApproval(params.approvalId, runtimeOptions, root);
+            },
+            render: {
+                rich: (result, primitives) => {
+                    if (result)
+                        renderApprovalDetails(result, primitives);
+                },
+                markdown: (result) => result ? renderApprovalDetailsMarkdown(result) : "",
+                json: (result) => result
+            }
         })
     ]
 }));
@@ -62,8 +100,10 @@ export function mergeApprovalsGroup(root) {
         }
         throw new UserError("'approvals' is reserved for human-in-loop built-ins");
     }
-    root.children = [...root.children, approvalsGroup];
-    return root;
+    return {
+        ...root,
+        children: [...root.children, approvalsGroup]
+    };
 }
 function markApprovalsBuiltIn(group) {
     Object.defineProperty(group, approvalsGroupSymbol, {
@@ -190,3 +230,6 @@ function stringifyValue(value) {
 function escapeMarkdownCell(value) {
     return value.replaceAll("|", "\\|");
 }
+function isMissingStateError(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}

package/dist/human-in-loop/runner.js

@@ -1,4 +1,5 @@
-import { access, readFile, writeFile } from "node:fs/promises";
+import { access, lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { InvalidTransitionError } from "@poe-code/task-list";
 import { UserError, resolveCommandSecrets } from "../index.js";
 import { ensureApprovalList } from "./approval-tasks.js";
 import { resolveProvider } from "./gate.js";
@@ -11,6 +12,19 @@ export async function runApproval(approvalId, runtimeOptions, root) {
     }
     const approval = readApprovalPayload(task);
     const provider = resolveProvider(runtimeOptions);
+    try {
+        await tasks.fire(approvalId, "claim", {
+            metadataPatch: {
+                pid: process.pid,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof InvalidTransitionError) {
+            return;
+        }
+        throw error;
+    }
     try {
         const approvalResult = await provider.requestApproval({
             message: approval.message,
@@ -28,14 +42,14 @@ export async function runApproval(approvalId, runtimeOptions, root) {
         }
     }
     catch (error) {
-        await failPendingApproval(tasks, approvalId, error);
+        await tasks.fire(approvalId, "fail", {
+            metadataPatch: {
+                error: errorMetadataFromUnknown(error),
+            },
+        });
         return;
     }
-    await tasks.fire(approvalId, "start", {
-        metadataPatch: {
-            pid: process.pid,
-        },
-    });
+    await tasks.fire(approvalId, "start");
     try {
         const command = findCommand(root, approval.commandPath);
         const ctx = createHandlerContext(command, approval.params);
@@ -182,6 +196,9 @@ function createFs() {
                 return false;
             }
         },
+        lstat: async (path) => lstat(path),
+        rename: async (fromPath, toPath) => rename(fromPath, toPath),
+        unlink: async (path) => unlink(path),
     };
 }
 function createEnv(values = process.env) {
@@ -223,15 +240,3 @@ function errorMetadataFromUnknown(error) {
         message: String(error),
     };
 }
-async function failPendingApproval(tasks, approvalId, error) {
-    await tasks.fire(approvalId, "start", {
-        metadataPatch: {
-            pid: process.pid,
-        },
-    });
-    await tasks.fire(approvalId, "fail", {
-        metadataPatch: {
-            error: errorMetadataFromUnknown(error),
-        },
-    });
-}

package/dist/human-in-loop/state-machine.d.ts

@@ -1,4 +1,4 @@
 import type { StateMachineDef } from "@poe-code/task-list";
-export type ApprovalState = "pending" | "approved-running" | "approved-done" | "approved-failed" | "declined";
-export type ApprovalEvent = "start" | "succeed" | "fail" | "decline";
-export declare const approvalStateMachine: StateMachineDef<ApprovalState, ApprovalEvent>;
+export type ApprovalState = "pending" | "prompting" | "approved-running" | "approved-done" | "approved-failed" | "declined";
+export type ApprovalEvent = "claim" | "start" | "succeed" | "fail" | "decline";
+export declare const approvalStateMachine: Readonly<StateMachineDef<ApprovalState, ApprovalEvent>>;

package/dist/human-in-loop/state-machine.js

@@ -1,10 +1,18 @@
-export const approvalStateMachine = {
+const approvalStateMachineDefinition = {
     initial: "pending",
-    states: ["pending", "approved-running", "approved-done", "approved-failed", "declined"],
+    states: ["pending", "prompting", "approved-running", "approved-done", "approved-failed", "declined"],
     events: {
-        start: { from: ["pending"], to: "approved-running" },
+        claim: { from: ["pending"], to: "prompting" },
+        start: { from: ["prompting"], to: "approved-running" },
         succeed: { from: ["approved-running"], to: "approved-done" },
-        fail: { from: ["approved-running"], to: "approved-failed" },
-        decline: { from: ["pending"], to: "declined" },
+        fail: { from: ["prompting", "approved-running"], to: "approved-failed" },
+        decline: { from: ["pending", "prompting"], to: "declined" },
     },
 };
+Object.freeze(approvalStateMachineDefinition.states);
+for (const event of Object.values(approvalStateMachineDefinition.events)) {
+    Object.freeze(event.from);
+    Object.freeze(event);
+}
+Object.freeze(approvalStateMachineDefinition.events);
+export const approvalStateMachine = Object.freeze(approvalStateMachineDefinition);

package/dist/index.d.ts

@@ -35,6 +35,11 @@ export interface HandlerFs {
     readFile(path: string, encoding?: BufferEncoding): Promise<string>;
     writeFile(path: string, contents: string): Promise<void>;
     exists(path: string): Promise<boolean>;
+    lstat(path: string): Promise<{
+        isSymbolicLink(): boolean;
+    }>;
+    rename(fromPath: string, toPath: string): Promise<void>;
+    unlink(path: string): Promise<void>;
 }
 export interface HandlerEnv {
     get(key: string): string | undefined;

package/dist/index.js

@@ -211,7 +211,12 @@ export function resolveCommandSecrets(command, env = process.env) {
             const suggestionLine = suggestions.length > 0 ? `\nDid you mean: ${suggestions.join(", ")}?` : "";
             throw new UserError(`Missing required secret ${secret.env}${details}${suggestionLine}`);
         }
-        secrets[name] = value;
+        Object.defineProperty(secrets, name, {
+            value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
     }
     return secrets;
 }