toolcraft 0.0.89 → 0.0.90

package/dist/cli.compile-check.js

@@ -1,6 +1,6 @@
 import { S } from "toolcraft-schema";
 import { defineCommand, defineGroup } from "./index.js";
-import { runCLI } from "./cli.js";
+import { createCLICommandTreeSnapshot, runCLI } from "./cli.js";
 const ignoredCommand = defineCommand({
     name: "deploy",
     params: S.Object({
@@ -37,4 +37,12 @@ const ignoredServiceOptions = {
 };
 void runCLI(ignoredRoot, ignoredOptions);
 void runCLI([ignoredRoot], ignoredOptions);
+const ignoredSnapshot = createCLICommandTreeSnapshot(ignoredRoot, {
+    approvals: true,
+    casing: "kebab",
+    controls: ignoredOptions.controls,
+    presets: true,
+    version: ignoredOptions.version,
+});
+void ignoredSnapshot;
 void ignoredServiceOptions;

package/dist/cli.d.ts

@@ -30,4 +30,59 @@ export interface RunCLIOptions<TServices extends object = Record<string, unknown
     presets?: boolean;
     errorReports?: ErrorReportsOption;
 }
+export interface CLICommandTreeSnapshotOption {
+    name: string;
+    flags: string[];
+    type: string;
+    required: boolean;
+    hidden: boolean;
+    description?: string;
+    default?: unknown;
+    positional?: boolean;
+    global?: boolean;
+    dynamic?: boolean;
+}
+export interface CLICommandTreeSnapshotCommand {
+    kind: "command";
+    name: string;
+    path: string[];
+    aliases: string[];
+    hidden: boolean;
+    default: boolean;
+    description?: string;
+    options: CLICommandTreeSnapshotOption[];
+}
+export interface CLICommandTreeSnapshotGroup {
+    kind: "group";
+    name: string;
+    path: string[];
+    aliases: string[];
+    hidden: false;
+    default: boolean;
+    description?: string;
+    children: CLICommandTreeSnapshotNode[];
+}
+export type CLICommandTreeSnapshotNode = CLICommandTreeSnapshotCommand | CLICommandTreeSnapshotGroup;
+export interface CLICommandTreeSnapshot {
+    schemaVersion: 1;
+    globalOptions: CLICommandTreeSnapshotOption[];
+    root: CLICommandTreeSnapshotGroup;
+}
+export interface CLICommandTreeSnapshotOptions {
+    approvals?: boolean;
+    argv?: readonly string[];
+    casing?: Casing;
+    controls?: CLIControls;
+    presets?: boolean;
+    version?: string;
+}
+/**
+ * Returns the resolved CLI command surface as deterministic plain data.
+ *
+ * Schema version 1 is independent of human-facing help layout. Nodes and options retain
+ * declaration order, paths exclude the root name, non-CLI nodes are omitted, hidden commands
+ * remain present, and Toolcraft-controlled global options are reported separately. A future
+ * incompatible shape change will increment `schemaVersion`.
+ */
+export declare function createCLICommandTreeSnapshot<TServices extends object>(roots: Group<TServices> | Group<TServices>[], options?: CLICommandTreeSnapshotOptions): Promise<CLICommandTreeSnapshot>;
 export declare function runCLI<TServices extends object = Record<string, unknown>>(roots: Group<TServices> | Group<TServices>[], options?: RunCLIOptions<TServices>): Promise<void>;

package/dist/cli.js

@@ -39,6 +39,29 @@ const optionalModulePaths = {
 function importOptionalModule(specifier) {
     return import(specifier);
 }
+/**
+ * Returns the resolved CLI command surface as deterministic plain data.
+ *
+ * Schema version 1 is independent of human-facing help layout. Nodes and options retain
+ * declaration order, paths exclude the root name, non-CLI nodes are omitted, hidden commands
+ * remain present, and Toolcraft-controlled global options are reported separately. A future
+ * incompatible shape change will increment `schemaVersion`.
+ */
+export async function createCLICommandTreeSnapshot(roots, options = {}) {
+    const argv = [...(options.argv ?? ["node", "toolcraft"])];
+    const normalizedRoot = normalizeRoots(roots, argv);
+    const root = options.approvals === true
+        ? (await importOptionalModule(optionalModulePaths.approvals)).mergeApprovalsGroup(normalizedRoot)
+        : normalizedRoot;
+    const controls = resolveCLIControls(options.controls);
+    const presetsEnabled = options.presets === true;
+    const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled, options.version !== undefined, controls);
+    return {
+        schemaVersion: 1,
+        globalOptions: createGlobalSnapshotOptions(presetsEnabled, options.version !== undefined, controls),
+        root: createSnapshotGroup(root, options.casing ?? "kebab", globalLongOptionFlags, [], false)
+    };
+}
 function inferProgramName(argv) {
     const entrypoint = argv[1];
     if (typeof entrypoint !== "string" || entrypoint.length === 0) {
@@ -1482,6 +1505,150 @@ function getToolcraftReservedChildNames(command) {
 function getNodeCommandNames(node) {
     return [node.name, ...node.aliases].filter((name) => name.length > 0);
 }
+function createGlobalSnapshotOptions(presetsEnabled, versionEnabled, controls) {
+    const options = [
+        {
+            name: "help",
+            flags: ["-h", "--help"],
+            type: "boolean",
+            required: false,
+            hidden: false,
+            description: "Display help for command."
+        }
+    ];
+    if (presetsEnabled) {
+        options.push({
+            name: "preset",
+            flags: ["--preset"],
+            type: "string",
+            required: false,
+            hidden: true,
+            description: "Load parameter defaults from a JSON file."
+        });
+    }
+    if (controls.yes) {
+        options.push({
+            name: "yes",
+            flags: ["--yes"],
+            type: "boolean",
+            required: false,
+            hidden: true,
+            description: "Accept defaults and skip prompts."
+        });
+    }
+    if (controls.output) {
+        options.push({
+            name: "output",
+            flags: ["--output"],
+            type: "enum",
+            required: false,
+            hidden: true,
+            description: "Output format."
+        });
+    }
+    if (controls.debug) {
+        options.push({
+            name: "debug",
+            flags: ["--debug"],
+            type: "enum",
+            required: false,
+            hidden: true,
+            description: "Print stack traces for unexpected errors."
+        });
+    }
+    if (controls.logLevel) {
+        options.push({
+            name: "logLevel",
+            flags: ["--log-level"],
+            type: "enum",
+            required: false,
+            hidden: true,
+            description: "Set runtime diagnostic log level."
+        });
+    }
+    if (controls.verbose) {
+        options.push({
+            name: "verbose",
+            flags: ["-v", "--verbose"],
+            type: "boolean",
+            required: false,
+            hidden: true,
+            description: "Print detailed runtime diagnostics."
+        });
+    }
+    if (versionEnabled) {
+        options.push({
+            name: "version",
+            flags: ["--version"],
+            type: "boolean",
+            required: false,
+            hidden: false,
+            description: "Output the version number."
+        });
+    }
+    return options;
+}
+function createSnapshotGroup(group, casing, globalLongOptionFlags, pathSegments, isDefault) {
+    const children = group.children
+        .filter((child) => isNodeVisibleInScope(child, "cli"))
+        .map((child) => createSnapshotNode(child, casing, globalLongOptionFlags, [...pathSegments, child.name], group.default === child));
+    return {
+        kind: "group",
+        name: group.name,
+        path: pathSegments,
+        aliases: [...group.aliases],
+        hidden: false,
+        default: isDefault,
+        ...(group.description === undefined ? {} : { description: group.description }),
+        children
+    };
+}
+function createSnapshotNode(node, casing, globalLongOptionFlags, pathSegments, isDefault) {
+    if (node.kind === "group") {
+        return createSnapshotGroup(node, casing, globalLongOptionFlags, pathSegments, isDefault);
+    }
+    const collected = collectFields(node.params, casing, globalLongOptionFlags);
+    const fields = assignPositionals(collected.fields, node.positional);
+    validateUniqueOptionFlags(fields, globalLongOptionFlags);
+    return {
+        kind: "command",
+        name: node.name,
+        path: pathSegments,
+        aliases: [...node.aliases],
+        hidden: node.hidden,
+        default: isDefault,
+        ...(node.description === undefined ? {} : { description: node.description }),
+        options: [
+            ...fields.map((field) => createFieldSnapshotOption(field, globalLongOptionFlags)),
+            ...collected.dynamicFields.flatMap((field) => createDynamicSnapshotOptions(field, casing))
+        ]
+    };
+}
+function createFieldSnapshotOption(field, globalLongOptionFlags) {
+    return {
+        name: field.displayPath,
+        flags: formatHelpFieldFlags(field, globalLongOptionFlags).split(", "),
+        type: formatJsonHelpSchemaType(field.schema),
+        required: field.requiredWhenActive,
+        hidden: false,
+        ...(field.description === undefined ? {} : { description: field.description }),
+        ...(field.hasDefault ? { default: field.defaultValue } : {}),
+        ...(field.positionalIndex === undefined ? {} : { positional: true }),
+        ...(field.global === true ? { global: true } : {})
+    };
+}
+function createDynamicSnapshotOptions(field, casing) {
+    return formatDynamicHelpFields(field, casing).map((row) => ({
+        name: field.displayPath,
+        flags: [row.flags],
+        type: describeDynamicFieldType(field),
+        required: field.requiredWhenActive,
+        hidden: false,
+        ...(field.description === undefined ? {} : { description: field.description }),
+        ...(field.hasDefault ? { default: field.defaultValue } : {}),
+        dynamic: true
+    }));
+}
 function addGlobalOptions(command, presetsEnabled, controls) {
     const options = [];
     if (presetsEnabled) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.89",
+  "version": "0.0.90",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     "postpack": "node ../../scripts/manage-bundled-workspace-deps.mjs cleanup . toolcraft-design @poe-code/frontmatter @poe-code/agent-mcp-config @poe-code/agent-human-in-loop @poe-code/task-list @poe-code/agent-defs @poe-code/config-mutations @poe-code/process-runner tiny-mcp-client mcp-oauth auth-store"
   },
   "dependencies": {
-    "toolcraft-schema": "0.0.89",
+    "toolcraft-schema": "0.0.90",
     "commander": "^13.1.0",
     "fast-string-width": "^3.0.2",
     "fast-wrap-ansi": "^0.2.0",