voratiq 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/cli/prune.js

@@ -1,14 +1,30 @@
-import { Command } from "commander";
-import { executePruneCommand } from "../commands/prune/command.js";
+import { Command, Option } from "commander";
+import { executePruneAllCommand, executePruneCommand, } from "../commands/prune/command.js";
 import { resolveCliContext } from "../preflight/index.js";
-import { renderPruneTranscript } from "../render/transcripts/prune.js";
+import { renderPruneAllTranscript, renderPruneTranscript, } from "../render/transcripts/prune.js";
 import { createConfirmationWorkflow } from "./confirmation.js";
-import { NonInteractiveShellError } from "./errors.js";
+import { parseExternalPruneExecutionInput, parsePruneCommandSelection, } from "./contract.js";
+import { CliError, NonInteractiveShellError } from "./errors.js";
+import { buildPruneOperatorEnvelope, writeOperatorResultEnvelope, } from "./operator-envelope.js";
 import { writeCommandOutput } from "./output.js";
 export async function runPruneCommand(options) {
     const { runId } = options;
+    const all = Boolean(options.all);
     const purge = Boolean(options.purge);
     const assumeYes = Boolean(options.yes);
+    if (options.json && !assumeYes) {
+        try {
+            parseExternalPruneExecutionInput({
+                scope: runId ? "run" : "all",
+                ...(runId ? { runId } : {}),
+                purge: purge || undefined,
+                confirmed: assumeYes,
+            });
+        }
+        catch {
+            throw new CliError("JSON-mode prune requires explicit confirmation.", [], ["Re-run with `--yes` to confirm the prune."]);
+        }
+    }
     const { root, workspacePaths } = await resolveCliContext();
     const confirmation = createConfirmationWorkflow({
         assumeYes,
@@ -17,6 +33,20 @@ export async function runPruneCommand(options) {
         },
     });
     try {
+        if (all) {
+            const result = await executePruneAllCommand({
+                root,
+                runsDir: workspacePaths.runsDir,
+                runsFilePath: workspacePaths.runsFile,
+                confirm: confirmation.confirm,
+                purge,
+            });
+            const body = renderPruneAllTranscript(result);
+            return { result, body };
+        }
+        if (!runId) {
+            throw new CliError("Missing prune target.", [], ["Provide a run id with `--run <run-id>`."]);
+        }
         const result = await executePruneCommand({
             root,
             runsDir: workspacePaths.runsDir,
@@ -34,18 +64,33 @@ export async function runPruneCommand(options) {
 }
 export function createPruneCommand() {
     return new Command("prune")
-        .description("Remove artifacts for a recorded run")
-        .requiredOption("--run <run-id>", "Identifier of the run to delete")
+        .description("Remove run workspaces and mark runs as pruned")
+        .addOption(new Option("--run <run-id>", "Run ID to prune").conflicts("all"))
+        .addOption(new Option("--all", "Prune all non-pruned runs").conflicts("run"))
         .option("--purge", "Delete all associated configs and artifacts")
-        .option("-y, --yes", "Assume yes for all prompts")
-        .addHelpText("after", "\nThis command removes agent workspaces, deletes agent branches, and marks runs as pruned. \nPass --purge to also delete all associated configs and artifacts.")
+        .option("-y, --yes", "Skip interactive confirmations")
+        .option("--json", "Emit a machine-readable result envelope")
         .allowExcessArguments(false)
-        .action(async (options) => {
+        .action(async (options, command) => {
+        const selection = parsePruneCommandSelection(options, command);
         const result = await runPruneCommand({
-            runId: options.run,
-            purge: Boolean(options.purge),
-            yes: Boolean(options.yes),
+            runId: selection.runId,
+            all: selection.all,
+            purge: Boolean(selection.purge),
+            yes: Boolean(selection.yes),
+            json: Boolean(options.json),
+            writeOutput: writeCommandOutput,
         });
+        if (options.json) {
+            writeOperatorResultEnvelope(buildPruneOperatorEnvelope({
+                status: result.result.status,
+                ...("runId" in result.result ? { runId: result.result.runId } : {}),
+                ...("runPath" in result.result && result.result.runPath
+                    ? { runPath: result.result.runPath }
+                    : {}),
+            }), result.exitCode);
+            return;
+        }
         writeCommandOutput({
             body: result.body,
             exitCode: result.exitCode,

package/dist/cli/reduce.d.ts

@@ -0,0 +1,29 @@
+import { Command } from "commander";
+import type { ReductionRecord, ReductionTarget } from "../domain/reduce/model/types.js";
+import type { CommandOutputWriter } from "./output.js";
+export interface ReduceCommandOptions {
+    target: ReductionTarget;
+    agentIds?: string[];
+    agentOverrideFlag?: string;
+    profile?: string;
+    maxParallel?: number;
+    extraContext?: string[];
+    json?: boolean;
+    suppressHint?: boolean;
+    writeOutput?: CommandOutputWriter;
+    stdout?: Pick<NodeJS.WriteStream, "write"> & {
+        isTTY?: boolean;
+    };
+    stderr?: Pick<NodeJS.WriteStream, "write"> & {
+        isTTY?: boolean;
+    };
+}
+export interface ReduceCommandResult {
+    reductionId: string;
+    status: ReductionRecord["status"];
+    target: ReductionTarget;
+    body: string;
+    exitCode?: number;
+}
+export declare function runReduceCommand(options: ReduceCommandOptions): Promise<ReduceCommandResult>;
+export declare function createReduceCommand(): Command;

package/dist/cli/reduce.js

@@ -0,0 +1,211 @@
+import { readFile } from "node:fs/promises";
+import { Command, Option } from "commander";
+import { checkPlatformSupport } from "../agents/runtime/sandbox.js";
+import { executeReduceCommand } from "../commands/reduce/command.js";
+import { buildMarkdownPreviewLines, extractMarkdownSection, } from "../commands/shared/preview.js";
+import { resolveExtraContextFiles } from "../competition/shared/extra-context.js";
+import { readReductionArtifact, } from "../domain/reduce/competition/reduction.js";
+import { readReductionRecords } from "../domain/reduce/persistence/adapter.js";
+import { ensureSandboxDependencies, resolveCliContext, } from "../preflight/index.js";
+import { createReduceRenderer, formatReduceElapsed, formatReducerDuration, renderReduceTranscript, } from "../render/transcripts/reduce.js";
+import { createStageStartLineEmitter } from "../render/utils/stage-output.js";
+import { normalizePathForDisplay, relativeToRoot, resolvePath, } from "../utils/path.js";
+import { parsePositiveInteger } from "../utils/validators.js";
+import { resolveWorkspacePath, VORATIQ_MESSAGE_FILE, VORATIQ_REDUCTION_FILE, VORATIQ_VERIFICATION_FILE, } from "../workspace/structure.js";
+import { parseReduceExecutionCommandOptions } from "./contract.js";
+import { buildReduceOperatorEnvelope, createSilentCliWriter, writeOperatorResultEnvelope, } from "./operator-envelope.js";
+import { writeCommandOutput } from "./output.js";
+export async function runReduceCommand(options) {
+    const { target, agentIds, agentOverrideFlag, profile, maxParallel, extraContext, json = false, suppressHint, writeOutput, stdout, stderr, } = options;
+    const effectiveWriteOutput = json
+        ? undefined
+        : (writeOutput ?? writeCommandOutput);
+    const rendererStdout = json ? createSilentCliWriter() : stdout;
+    const rendererStderr = json ? createSilentCliWriter() : stderr;
+    const { root, workspacePaths } = await resolveCliContext();
+    checkPlatformSupport();
+    ensureSandboxDependencies();
+    const extraContextFiles = await resolveExtraContextFiles({
+        root,
+        paths: extraContext,
+    });
+    const startLine = createStageStartLineEmitter((message) => {
+        effectiveWriteOutput?.({
+            alerts: [{ severity: "info", message }],
+        });
+    });
+    if (effectiveWriteOutput) {
+        startLine.emit("Reducing artifacts…");
+    }
+    const renderer = createReduceRenderer({
+        stdout: rendererStdout,
+        stderr: rendererStderr,
+    });
+    const execution = await executeReduceCommand({
+        root,
+        specsFilePath: workspacePaths.specsFile,
+        runsFilePath: workspacePaths.runsFile,
+        reductionsFilePath: workspacePaths.reductionsFile ?? resolveReductionIndexPath(root),
+        messagesFilePath: workspacePaths.messagesFile ??
+            resolveWorkspacePath(root, VORATIQ_MESSAGE_FILE),
+        verificationsFilePath: workspacePaths.verificationsFile ??
+            resolveWorkspacePath(root, VORATIQ_VERIFICATION_FILE),
+        target,
+        agentIds,
+        agentOverrideFlag,
+        profileName: profile,
+        maxParallel,
+        extraContextFiles,
+        renderer,
+    });
+    const record = await readReductionSessionRecord({
+        root,
+        reductionsFilePath: workspacePaths.reductionsFile ?? resolveReductionIndexPath(root),
+        reductionId: execution.reductionId,
+    });
+    if (!record) {
+        throw new Error(`Reduction session \`${execution.reductionId}\` record not found after execution.`);
+    }
+    const reducers = await Promise.all(record.reducers.map(async (reducer) => {
+        const duration = formatReducerDuration({
+            status: reducer.status,
+            startedAt: reducer.startedAt,
+            completedAt: reducer.completedAt,
+        });
+        let previewLines;
+        if (reducer.status === "succeeded") {
+            try {
+                const reductionData = await readReductionArtifact(resolvePath(root, reducer.dataPath ??
+                    reducer.outputPath.replace(/reduction\.md$/u, "reduction.json")));
+                previewLines = buildMarkdownPreviewLines(formatReductionSnippet(reductionData));
+            }
+            catch {
+                try {
+                    const markdown = await readFile(resolvePath(root, reducer.outputPath), "utf8");
+                    const synthesisSection = extractMarkdownSection(markdown, {
+                        heading: "Synthesis",
+                        level: 2,
+                    }) ??
+                        extractMarkdownSection(markdown, {
+                            heading: "Reduction",
+                            level: 2,
+                        }) ??
+                        markdown.trim();
+                    previewLines = buildMarkdownPreviewLines(synthesisSection);
+                }
+                catch {
+                    previewLines = undefined;
+                }
+            }
+        }
+        return {
+            reducerAgentId: reducer.agentId,
+            status: reducer.status,
+            duration,
+            outputPath: reducer.outputPath,
+            dataPath: reducer.dataPath,
+            previewLines,
+            errorLine: reducer.error ?? undefined,
+        };
+    }));
+    const body = renderReduceTranscript({
+        reductionId: execution.reductionId,
+        createdAt: record.createdAt,
+        elapsed: formatReduceElapsed({
+            status: record.status,
+            startedAt: record.startedAt,
+            completedAt: record.completedAt,
+        }) ?? "—",
+        workspacePath: normalizePathForDisplay(relativeToRoot(root, resolvePath(root, `.voratiq/reduce/sessions/${execution.reductionId}`))),
+        status: record.status,
+        reducers,
+        suppressHint,
+        isTty: stdout?.isTTY ?? process.stdout.isTTY,
+        includeSummarySection: !(stdout?.isTTY ?? process.stdout.isTTY),
+    });
+    return {
+        reductionId: execution.reductionId,
+        status: record.status,
+        target: record.target,
+        body,
+        exitCode: record.status === "succeeded" ? 0 : 1,
+    };
+}
+function formatReductionSnippet(reduction) {
+    const lines = ["## Reduction", `**Summary**: ${reduction.summary}`];
+    if (reduction.directives.length > 0) {
+        lines.push("", "**Directives**:");
+        for (const directive of reduction.directives) {
+            lines.push(`- ${directive}`);
+        }
+    }
+    if (reduction.risks.length > 0) {
+        lines.push("", "**Risks**:");
+        for (const risk of reduction.risks) {
+            lines.push(`- ${risk}`);
+        }
+    }
+    return lines.join("\n");
+}
+function collectAgentOption(value, previous) {
+    return [...previous, value];
+}
+function collectExtraContextOption(value, previous) {
+    return [...previous, value];
+}
+function parseMaxParallelOption(value) {
+    return parsePositiveInteger(value, "Expected positive integer after --max-parallel", "--max-parallel must be greater than 0");
+}
+export function createReduceCommand() {
+    return new Command("reduce")
+        .description("Reduce artifact sets into a summarized form")
+        .addOption(new Option("--spec <spec-id>", "Spec to reduce"))
+        .addOption(new Option("--run <run-id>", "Run to reduce"))
+        .addOption(new Option("--reduce <reduce-id>", "Reduction to reduce"))
+        .addOption(new Option("--verify <verify-id>", "Verification to reduce"))
+        .addOption(new Option("--message <message-id>", "Message session to reduce"))
+        .addOption(new Option("--agent <agent-id>", "Set reducers directly (repeatable; order preserved)")
+        .default([], "")
+        .argParser(collectAgentOption))
+        .option("--profile <name>", 'Orchestration profile (default: "default")')
+        .option("--max-parallel <count>", "Max concurrent reducers (default: all)", parseMaxParallelOption)
+        .addOption(new Option("--extra-context <path>", "Stage an extra context file into each reducer workspace (repeatable)")
+        .default([], "")
+        .argParser(collectExtraContextOption))
+        .option("--json", "Emit a machine-readable result envelope")
+        .allowExcessArguments(false)
+        .action(async (options, command) => {
+        const input = parseReduceExecutionCommandOptions(options, command);
+        const result = await runReduceCommand({
+            target: input.target,
+            agentIds: input.agentIds,
+            profile: input.profile,
+            maxParallel: input.maxParallel,
+            extraContext: input.extraContext,
+            json: Boolean(options.json),
+            writeOutput: options.json ? undefined : writeCommandOutput,
+        });
+        if (options.json) {
+            writeOperatorResultEnvelope(buildReduceOperatorEnvelope({
+                reductionId: result.reductionId,
+                target: result.target,
+                status: result.status,
+            }), result.exitCode);
+            return;
+        }
+        writeCommandOutput({ body: result.body, exitCode: result.exitCode });
+    });
+}
+async function readReductionSessionRecord(options) {
+    const { root, reductionsFilePath, reductionId } = options;
+    const records = await readReductionRecords({
+        root,
+        reductionsFilePath,
+        limit: 1,
+        predicate: (record) => record.sessionId === reductionId,
+    });
+    return records[0];
+}
+function resolveReductionIndexPath(root) {
+    return resolvePath(root, `.voratiq/${VORATIQ_REDUCTION_FILE}`);
+}

package/dist/cli/root-launcher.d.ts

@@ -0,0 +1,4 @@
+import type { RootLauncherCommandOptions } from "../commands/root-launcher/command.js";
+export type { RootLauncherCommandOptions as RootLauncherOptions } from "../commands/root-launcher/command.js";
+export declare function shouldStartRootLauncher(argv: readonly string[], detectInteractive?: () => boolean): boolean;
+export declare function runInteractiveRootLauncher(options?: RootLauncherCommandOptions): Promise<void>;

package/dist/cli/root-launcher.js

@@ -0,0 +1,15 @@
+import { runRootLauncherCommand } from "../commands/root-launcher/command.js";
+import { isInteractiveShell } from "../utils/terminal.js";
+import { createConfirmationWorkflow } from "./confirmation.js";
+export function shouldStartRootLauncher(argv, detectInteractive = () => isInteractiveShell()) {
+    return argv.length <= 2 && detectInteractive();
+}
+export async function runInteractiveRootLauncher(options = {
+    createWorkflow: (workflowOptions) => createConfirmationWorkflow(workflowOptions),
+}) {
+    await runRootLauncherCommand({
+        ...options,
+        createWorkflow: options.createWorkflow ??
+            ((workflowOptions) => createConfirmationWorkflow(workflowOptions)),
+    });
+}

package/dist/cli/run.d.ts

@@ -1,8 +1,25 @@
 import { Command } from "commander";
-import type { RunReport } from "../records/types.js";
+import type { RunReport } from "../domain/run/model/types.js";
+import type { CommandOutputWriter } from "./output.js";
 export interface RunCommandOptions {
     specPath: string;
+    agentIds?: string[];
+    agentOverrideFlag?: string;
+    profile?: string;
     maxParallel?: number;
+    branch?: boolean;
+    extraContext?: string[];
+    json?: boolean;
+    suppressHint?: boolean;
+    suppressLeadingBlankLine?: boolean;
+    suppressTrailingBlankLine?: boolean;
+    stdout?: Pick<NodeJS.WriteStream, "write"> & {
+        isTTY?: boolean;
+    };
+    stderr?: Pick<NodeJS.WriteStream, "write"> & {
+        isTTY?: boolean;
+    };
+    writeOutput?: CommandOutputWriter;
 }
 export interface RunCommandResult {
     report: RunReport;
@@ -10,4 +27,13 @@ export interface RunCommandResult {
     exitCode?: number;
 }
 export declare function runRunCommand(options: RunCommandOptions): Promise<RunCommandResult>;
+/**
+ * Derives a branch name from a spec file path by extracting the basename without extension.
+ *
+ * Examples:
+ * - `specs/separate-verification-outcomes.md` → `separate-verification-outcomes`
+ * - `specs/foo/bar.md` → `bar`
+ * - `my-feature.md` → `my-feature`
+ */
+export declare function deriveBranchNameFromSpecPath(specPath: string): string;
 export declare function createRunCommand(): Command;

package/dist/cli/run.js

@@ -1,48 +1,140 @@
-import { Command } from "commander";
+import { basename } from "node:path";
+import { Command, Option } from "commander";
+import { checkPlatformSupport } from "../agents/runtime/sandbox.js";
 import { executeRunCommand } from "../commands/run/command.js";
-import { checkPlatformSupport } from "../commands/run/sandbox.js";
+import { resolveExtraContextFiles } from "../competition/shared/extra-context.js";
+import { checkoutOrCreateBranch } from "../preflight/branch.js";
 import { ensureCleanWorkingTree, ensureSandboxDependencies, ensureSpecPath, resolveCliContext, } from "../preflight/index.js";
 import { createRunRenderer } from "../render/transcripts/run.js";
+import { renderWorkspaceAutoInitializedNotice } from "../render/transcripts/shared.js";
+import { createStageStartLineEmitter } from "../render/utils/stage-output.js";
+import { mapRunStatusToExitCode } from "../status/index.js";
 import { parsePositiveInteger } from "../utils/validators.js";
+import { parseRunExecutionCommandOptions } from "./contract.js";
+import { buildRunOperatorEnvelope, createSilentCliWriter, writeOperatorResultEnvelope, } from "./operator-envelope.js";
 import { writeCommandOutput } from "./output.js";
 export async function runRunCommand(options) {
-    const { specPath, maxParallel } = options;
-    const { root, workspacePaths } = await resolveCliContext();
+    const { specPath, agentIds, agentOverrideFlag, profile, maxParallel, branch, extraContext, json = false, suppressHint, suppressLeadingBlankLine, suppressTrailingBlankLine, stdout, stderr, writeOutput, } = options;
+    const effectiveWriteOutput = json
+        ? undefined
+        : (writeOutput ?? writeCommandOutput);
+    const rendererStdout = json ? createSilentCliWriter() : stdout;
+    const rendererStderr = json ? createSilentCliWriter() : stderr;
+    const { root, workspacePaths, workspaceAutoInitialized } = await resolveCliContext({
+        workspaceAutoInitMode: "when-missing",
+    });
+    const workspaceNotice = workspaceAutoInitialized
+        ? renderWorkspaceAutoInitializedNotice()
+        : undefined;
+    if (workspaceNotice && effectiveWriteOutput) {
+        effectiveWriteOutput({
+            alerts: [{ severity: "info", message: workspaceNotice }],
+            leadingNewline: false,
+        });
+    }
     checkPlatformSupport();
     ensureSandboxDependencies();
     await ensureCleanWorkingTree(root);
     const { absolutePath, displayPath } = await ensureSpecPath(specPath, root);
-    const renderer = createRunRenderer();
+    const extraContextFiles = await resolveExtraContextFiles({
+        root,
+        paths: extraContext,
+    });
+    if (branch) {
+        const branchName = deriveBranchNameFromSpecPath(displayPath);
+        await checkoutOrCreateBranch(root, branchName);
+    }
+    if (effectiveWriteOutput) {
+        const startLine = createStageStartLineEmitter((message) => {
+            effectiveWriteOutput({
+                alerts: [{ severity: "info", message }],
+            });
+        });
+        startLine.emit("Executing run…");
+    }
+    const renderer = createRunRenderer({
+        stdout: rendererStdout,
+        stderr: rendererStderr,
+        suppressLeadingBlankLine,
+        suppressTrailingBlankLine,
+    });
     const report = await executeRunCommand({
         root,
         runsFilePath: workspacePaths.runsFile,
         specAbsolutePath: absolutePath,
         specDisplayPath: displayPath,
+        agentIds,
+        agentOverrideFlag,
+        profileName: profile,
         maxParallel,
+        extraContextFiles,
         renderer,
     });
-    const body = renderer.complete(report);
-    // Unlike other commands, `run` signals a degraded outcome via exit code 1
-    // when any agent or eval fails. All other CLI commands either throw on error
-    // or return a clean success with exit code 0, so keep this deviation explicit.
-    const exitCode = report.hadAgentFailure || report.hadEvalFailure ? 1 : undefined;
+    const body = renderer.complete(report, { suppressHint });
+    const exitCode = mapRunStatusToExitCode(report.status);
     return { report, body, exitCode };
 }
+/**
+ * Derives a branch name from a spec file path by extracting the basename without extension.
+ *
+ * Examples:
+ * - `specs/separate-verification-outcomes.md` → `separate-verification-outcomes`
+ * - `specs/foo/bar.md` → `bar`
+ * - `my-feature.md` → `my-feature`
+ */
+export function deriveBranchNameFromSpecPath(specPath) {
+    const base = basename(specPath);
+    const lastDotIndex = base.lastIndexOf(".");
+    if (lastDotIndex <= 0) {
+        return base;
+    }
+    return base.slice(0, lastDotIndex);
+}
+function collectAgentOption(value, previous) {
+    return [...previous, value];
+}
+function collectExtraContextOption(value, previous) {
+    return [...previous, value];
+}
 function parseMaxParallelOption(value) {
     return parsePositiveInteger(value, "Expected positive integer after --max-parallel", "--max-parallel must be greater than 0");
 }
 export function createRunCommand() {
     return new Command("run")
-        .description("Execute configured agents against a spec")
-        .requiredOption("--spec <path>", "Path to the specification to execute")
-        .option("--max-parallel <count>", "Maximum number of agents to run concurrently", parseMaxParallelOption)
+        .description("Execute agents against a spec")
+        .requiredOption("--spec <path>", "Path to the spec file")
+        .addOption(new Option("--agent <agent-id>", "Set agents directly (repeatable; order preserved)")
+        .default([], "")
+        .argParser(collectAgentOption))
+        .option("--profile <name>", 'Orchestration profile (default: "default")')
+        .option("--max-parallel <count>", "Max concurrent agents (default: all)", parseMaxParallelOption)
+        .option("--branch", "Create or checkout a branch named after the spec")
+        .addOption(new Option("--extra-context <path>", "Stage an extra context file into each agent workspace (repeatable)")
+        .default([], "")
+        .argParser(collectExtraContextOption))
+        .option("--json", "Emit a machine-readable result envelope")
         .allowExcessArguments(false)
-        .action(async (options) => {
+        .action(async (options, command) => {
+        const input = parseRunExecutionCommandOptions(options, command);
         const runOptions = {
-            specPath: options.spec,
-            maxParallel: options.maxParallel,
+            specPath: input.specPath,
+            agentIds: input.agentIds,
+            profile: input.profile,
+            maxParallel: input.maxParallel,
+            branch: input.branch,
+            extraContext: input.extraContext,
+            json: Boolean(options.json),
+            writeOutput: options.json ? undefined : writeCommandOutput,
         };
         const result = await runRunCommand(runOptions);
+        if (options.json) {
+            writeOperatorResultEnvelope(buildRunOperatorEnvelope({
+                runId: result.report.runId,
+                specPath: result.report.spec.path,
+                status: result.report.status,
+            }), result.exitCode);
+            return;
+        }
         writeCommandOutput({
             body: result.body,
             exitCode: result.exitCode,

package/dist/cli/spec.d.ts

@@ -0,0 +1,31 @@
+import { Command } from "commander";
+import { type CommandOutputWriter } from "./output.js";
+export interface SpecCommandOptions {
+    description: string;
+    agentIds?: string[];
+    profile?: string;
+    maxParallel?: number;
+    title?: string;
+    extraContext?: string[];
+    json?: boolean;
+    suppressHint?: boolean;
+    suppressLeadingBlankLine?: boolean;
+    suppressTrailingBlankLine?: boolean;
+    stdout?: Pick<NodeJS.WriteStream, "write"> & {
+        isTTY?: boolean;
+    };
+    stderr?: Pick<NodeJS.WriteStream, "write"> & {
+        isTTY?: boolean;
+    };
+    writeOutput?: CommandOutputWriter;
+}
+export interface SpecCommandResult {
+    body: string;
+    sessionId?: string;
+    generatedSpecPaths: string[];
+    /** Derived convenience path only when exactly one spec artifact was generated. */
+    specPath?: string;
+    sessionPath?: string;
+}
+export declare function runSpecCommand(options: SpecCommandOptions): Promise<SpecCommandResult>;
+export declare function createSpecCommand(): Command;