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

package/dist/cli/spec.js

@@ -0,0 +1,180 @@
+import { Command, Option } from "commander";
+import { checkPlatformSupport } from "../agents/runtime/sandbox.js";
+import { buildMarkdownPreviewLines } from "../commands/shared/preview.js";
+import { executeSpecCommand } from "../commands/spec/command.js";
+import { resolveExtraContextFiles } from "../competition/shared/extra-context.js";
+import { readSpecData } from "../domain/spec/model/output.js";
+import { ensureSandboxDependencies, resolveCliContext, } from "../preflight/index.js";
+import { renderWorkspaceAutoInitializedNotice } from "../render/transcripts/shared.js";
+import { createSpecRenderer, formatSpecAgentDuration, formatSpecElapsed, renderSpecTranscript, } from "../render/transcripts/spec.js";
+import { createStageStartLineEmitter } from "../render/utils/stage-output.js";
+import { resolvePath } from "../utils/path.js";
+import { parsePositiveInteger } from "../utils/validators.js";
+import { getSpecSessionDirectoryPath } from "../workspace/structure.js";
+import { parseSpecExecutionCommandOptions } from "./contract.js";
+import { buildSpecOperatorEnvelope, createSilentCliWriter, writeOperatorResultEnvelope, } from "./operator-envelope.js";
+import { writeCommandOutput } from "./output.js";
+export async function runSpecCommand(options) {
+    const { description, agentIds, profile, maxParallel, title, 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();
+    const extraContextFiles = await resolveExtraContextFiles({
+        root,
+        paths: extraContext,
+    });
+    const startLine = createStageStartLineEmitter((message) => {
+        effectiveWriteOutput?.({
+            alerts: [{ severity: "info", message }],
+        });
+    });
+    const renderer = createSpecRenderer({
+        stdout: rendererStdout,
+        stderr: rendererStderr,
+        suppressLeadingBlankLine,
+        suppressTrailingBlankLine,
+    });
+    const result = await executeSpecCommand({
+        root,
+        specsFilePath: workspacePaths.specsFile,
+        description,
+        agentIds,
+        profileName: profile,
+        maxParallel,
+        title,
+        extraContextFiles,
+        onStatus: (message) => {
+            startLine.emit(message);
+        },
+        renderer,
+    });
+    const body = renderSpecTranscript({
+        sessionId: result.sessionId,
+        createdAt: result.record.createdAt,
+        elapsed: formatSpecElapsed({
+            status: result.record.status,
+            startedAt: result.record.startedAt,
+            completedAt: result.record.completedAt,
+        }) ?? "—",
+        workspacePath: `.voratiq/spec/sessions/${result.sessionId}`,
+        status: result.record.status,
+        agents: await Promise.all(result.agents.map(async (agent) => ({
+            agentId: agent.agentId,
+            status: agent.status,
+            duration: formatSpecAgentDuration({
+                status: agent.status,
+                startedAt: agent.startedAt,
+                completedAt: agent.completedAt,
+            }),
+            outputPath: agent.outputPath,
+            dataPath: agent.dataPath,
+            previewLines: agent.status === "succeeded" && agent.dataPath
+                ? buildMarkdownPreviewLines(formatSpecPreview(await readSpecData(resolvePath(root, agent.dataPath))))
+                : undefined,
+            errorLine: agent.error ?? undefined,
+        }))),
+        nextCommandLines: ["voratiq run --spec <path>"],
+        isTty: stdout?.isTTY ?? process.stdout.isTTY,
+        includeSummarySection: !(stdout?.isTTY ?? process.stdout.isTTY),
+    }, { suppressHint });
+    const generatedSpecPaths = result.agents
+        .filter((agent) => agent.status === "succeeded" && agent.outputPath)
+        .map((agent) => agent.outputPath)
+        .filter((outputPath) => outputPath !== undefined);
+    return {
+        body,
+        sessionId: result.sessionId,
+        generatedSpecPaths,
+        specPath: generatedSpecPaths.length === 1 ? generatedSpecPaths[0] : undefined,
+        sessionPath: getSpecSessionDirectoryPath(result.sessionId),
+    };
+}
+function formatSpecPreview(spec) {
+    const lines = [`# ${spec.title}`, "", "## Objective", "", spec.objective];
+    if (spec.scope.length > 0) {
+        lines.push("", "## Scope");
+        for (const item of spec.scope) {
+            lines.push(`- ${item}`);
+        }
+    }
+    if (spec.acceptanceCriteria.length > 0) {
+        lines.push("", "## Acceptance Criteria");
+        for (const criterion of spec.acceptanceCriteria) {
+            lines.push(`- ${criterion}`);
+        }
+    }
+    if (spec.constraints.length > 0) {
+        lines.push("", "## Constraints");
+        for (const item of spec.constraints) {
+            lines.push(`- ${item}`);
+        }
+    }
+    if (spec.outOfScope && spec.outOfScope.length > 0) {
+        lines.push("", "## Out of Scope");
+        for (const item of spec.outOfScope) {
+            lines.push(`- ${item}`);
+        }
+    }
+    lines.push("", "## Exit Signal", "", spec.exitSignal);
+    return lines.join("\n");
+}
+export function createSpecCommand() {
+    const parseMaxParallelOption = (value) => parsePositiveInteger(value, "Expected positive integer after --max-parallel", "--max-parallel must be greater than 0");
+    const collectAgentOption = (value, previous) => [
+        ...previous,
+        value,
+    ];
+    const collectExtraContextOption = (value, previous) => [...previous, value];
+    return new Command("spec")
+        .description("Generate a spec from a task description")
+        .requiredOption("--description <text>", "Task description")
+        .addOption(new Option("--agent <agent-id>", "Set agents directly (repeatable; order preserved)")
+        .default([], "")
+        .argParser(collectAgentOption))
+        .option("--profile <name>", 'Orchestration profile (default: "default")')
+        .addOption(new Option("--max-parallel <count>", "Max concurrent agents")
+        .argParser(parseMaxParallelOption)
+        .hideHelp())
+        .option("--title <text>", "Spec title; agent infers if omitted")
+        .addOption(new Option("--extra-context <path>", "Stage an extra context file into the spec workspace (repeatable)")
+        .default([], "")
+        .argParser(collectExtraContextOption))
+        .option("--json", "Emit a machine-readable result envelope")
+        .allowExcessArguments(false)
+        .action(async (options, command) => {
+        const input = parseSpecExecutionCommandOptions(options, command);
+        const result = await runSpecCommand({
+            description: input.description,
+            agentIds: input.agentIds,
+            profile: input.profile,
+            maxParallel: input.maxParallel,
+            title: input.title,
+            extraContext: input.extraContext,
+            json: Boolean(options.json),
+        });
+        if (options.json) {
+            writeOperatorResultEnvelope(buildSpecOperatorEnvelope({
+                sessionId: result.sessionId,
+                generatedSpecPaths: result.generatedSpecPaths,
+            }));
+            return;
+        }
+        writeCommandOutput({ body: result.body });
+    });
+}

package/dist/cli/verify.d.ts

@@ -0,0 +1,35 @@
+import { Command } from "commander";
+import type { VerifyTargetSelection } from "../commands/verify/targets.js";
+import { type VerificationRecord } from "../domain/verify/model/types.js";
+import { type VerificationSelectionPolicyOutput } from "../policy/index.js";
+import type { CommandOutputWriter } from "./output.js";
+export interface VerifyCommandOptions {
+    target: VerifyTargetSelection;
+    agentIds?: string[];
+    agentOverrideFlag?: string;
+    profile?: string;
+    maxParallel?: number;
+    extraContext?: string[];
+    json?: boolean;
+    suppressHint?: boolean;
+    stdout?: Pick<NodeJS.WriteStream, "write"> & {
+        isTTY?: boolean;
+    };
+    stderr?: Pick<NodeJS.WriteStream, "write"> & {
+        isTTY?: boolean;
+    };
+    writeOutput?: CommandOutputWriter;
+}
+export interface VerifyCommandResult {
+    verificationId: string;
+    status: VerificationRecord["status"];
+    target: VerificationRecord["target"];
+    body: string;
+    exitCode?: number;
+    outputPath: string;
+    selectedSpecPath?: string;
+    selection?: VerificationSelectionPolicyOutput;
+    warningMessage?: string;
+}
+export declare function runVerifyCommand(options: VerifyCommandOptions): Promise<VerifyCommandResult>;
+export declare function createVerifyCommand(): Command;

package/dist/cli/verify.js

@@ -0,0 +1,297 @@
+import { readFile } from "node:fs/promises";
+import { Command, Option } from "commander";
+import { checkPlatformSupport } from "../agents/runtime/sandbox.js";
+import { buildMarkdownPreviewLines } from "../commands/shared/preview.js";
+import { executeVerifyCommand } from "../commands/verify/command.js";
+import { resolveExtraContextFiles } from "../competition/shared/extra-context.js";
+import { isBlindedCandidateAlias } from "../domain/verify/blinding/aliases.js";
+import { verificationResultArtifactSchema, } from "../domain/verify/model/types.js";
+import { readRubricResultNarrative, readRubricResultNextActions, readRubricResultPreferred, readRubricResultRationale, } from "../domain/verify/rubric-result.js";
+import { loadVerificationSelectionPolicyOutput, } from "../policy/index.js";
+import { ensureSandboxDependencies, resolveCliContext, } from "../preflight/index.js";
+import { createVerifyRenderer, formatVerifyElapsed, renderVerifyTranscript, } from "../render/transcripts/verify.js";
+import { formatRenderLifecycleDuration } from "../render/utils/duration.js";
+import { createStageStartLineEmitter } from "../render/utils/stage-output.js";
+import { renderTable } from "../render/utils/table.js";
+import { getCheckStatusStyle } from "../status/colors.js";
+import { TERMINAL_VERIFICATION_STATUSES } from "../status/index.js";
+import { colorize } from "../utils/colors.js";
+import { toErrorMessage } from "../utils/errors.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, VORATIQ_VERIFICATION_SESSIONS_DIR, } from "../workspace/structure.js";
+import { parseVerifyExecutionCommandOptions } from "./contract.js";
+import { buildVerifyOperatorEnvelope, createSilentCliWriter, writeOperatorResultEnvelope, } from "./operator-envelope.js";
+import { writeCommandOutput } from "./output.js";
+export async function runVerifyCommand(options) {
+    const { target, agentIds, agentOverrideFlag, profile, maxParallel, extraContext, json = false, suppressHint, stdout, stderr, writeOutput, } = 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("Verifying…");
+    }
+    const renderer = createVerifyRenderer({
+        stdout: rendererStdout,
+        stderr: rendererStderr,
+    });
+    const isTty = json ? false : (stdout?.isTTY ?? process.stdout.isTTY);
+    const execution = await executeVerifyCommand({
+        root,
+        specsFilePath: workspacePaths.specsFile,
+        runsFilePath: workspacePaths.runsFile,
+        reductionsFilePath: workspacePaths.reductionsFile ??
+            resolveWorkspacePath(root, VORATIQ_REDUCTION_FILE),
+        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 methodBlocks = await Promise.all(execution.record.methods.map(async (method) => {
+        const bodyLines = await buildMethodBodyLines({
+            root,
+            aliasMap: execution.record.blinded?.aliasMap,
+            method,
+            isTty,
+        });
+        return {
+            verifierLabel: formatMethodVerifierLabel(method),
+            agentLabel: formatMethodAgentLabel(method),
+            status: method.status,
+            duration: formatMethodDuration(method),
+            artifactPath: method.artifactPath,
+            bodyLines,
+            errorLine: method.error ?? undefined,
+        };
+    }));
+    let selectionPolicyWarning;
+    const selection = await loadVerificationSelectionPolicyOutput({
+        root,
+        record: execution.record,
+    }).catch((error) => {
+        selectionPolicyWarning = [
+            "Warning: failed to load verification selection policy output; apply hint unavailable.",
+            toErrorMessage(error),
+        ].join("\n");
+        return undefined;
+    });
+    const selectionWarnings = (selection?.warnings ?? []).map((warning) => `Warning: ${warning}`);
+    const warningMessage = [
+        ...selectionWarnings,
+        ...(selectionPolicyWarning ? [selectionPolicyWarning] : []),
+    ].join("\n");
+    const recommendedRunAgent = execution.record.target.kind === "run" &&
+        selection !== undefined &&
+        selection.decision.state === "resolvable"
+        ? selection.decision.selectedCanonicalAgentId
+        : undefined;
+    const hintMessage = suppressHint ||
+        selectionPolicyWarning ||
+        execution.record.target.kind !== "run" ||
+        execution.record.status !== "succeeded"
+        ? undefined
+        : `To apply a solution:\n  voratiq apply --run ${execution.record.target.sessionId} --agent ${recommendedRunAgent ?? "<agent-id>"}`;
+    const outputPath = normalizePathForDisplay(relativeToRoot(root, resolveWorkspacePath(root, VORATIQ_VERIFICATION_SESSIONS_DIR, execution.verificationId)));
+    const body = renderVerifyTranscript({
+        verificationId: execution.verificationId,
+        createdAt: execution.record.createdAt,
+        elapsed: formatVerifyElapsed({
+            status: execution.record.status,
+            startedAt: execution.record.startedAt,
+            completedAt: execution.record.completedAt,
+        }) ?? "—",
+        workspacePath: normalizePathForDisplay(relativeToRoot(root, resolveWorkspacePath(root, VORATIQ_VERIFICATION_SESSIONS_DIR, execution.verificationId))),
+        target: execution.record.target,
+        status: execution.record.status,
+        methods: methodBlocks,
+        suppressHint,
+        ...(warningMessage ? { warningMessage } : {}),
+        hintMessage,
+        isTty,
+        includeSummarySection: !isTty,
+    });
+    return {
+        verificationId: execution.verificationId,
+        status: execution.record.status,
+        target: execution.record.target,
+        body,
+        exitCode: execution.record.status === "succeeded" ? 0 : 1,
+        outputPath,
+        ...(execution.record.target.kind === "spec" &&
+            typeof execution.record.target.specPath === "string"
+            ? { selectedSpecPath: execution.record.target.specPath }
+            : {}),
+        selection,
+        ...(warningMessage ? { warningMessage } : {}),
+    };
+}
+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 createVerifyCommand() {
+    return new Command("verify")
+        .description("Verify a recorded spec, run, reduction, or message session")
+        .addOption(new Option("--spec <spec-id>", "Spec to verify"))
+        .addOption(new Option("--run <run-id>", "Run to verify"))
+        .addOption(new Option("--reduce <reduce-id>", "Reduction to verify"))
+        .addOption(new Option("--message <message-id>", "Message session to verify"))
+        .addOption(new Option("--agent <agent-id>", "Set verifiers directly (repeatable; order preserved)")
+        .default([], "")
+        .argParser(collectAgentOption))
+        .option("--profile <name>", 'Orchestration profile (default: "default")')
+        .option("--max-parallel <count>", "Max concurrent verifiers (default: all)", parseMaxParallelOption)
+        .addOption(new Option("--extra-context <path>", "Stage an extra context file into each verifier workspace (repeatable)")
+        .default([], "")
+        .argParser(collectExtraContextOption))
+        .option("--json", "Emit a machine-readable result envelope")
+        .allowExcessArguments(false)
+        .action(async (options, command) => {
+        const input = parseVerifyExecutionCommandOptions(options, command);
+        const result = await runVerifyCommand({
+            target: input.target,
+            agentIds: input.agentIds,
+            profile: input.profile,
+            maxParallel: input.maxParallel,
+            extraContext: input.extraContext,
+            json: Boolean(options.json),
+        });
+        if (options.json) {
+            writeOperatorResultEnvelope(buildVerifyOperatorEnvelope({
+                verificationId: result.verificationId,
+                target: result.target,
+                outputPath: result.outputPath,
+                status: result.status,
+                selection: result.selection?.decision,
+                selectedSpecPath: result.selectedSpecPath,
+                warningMessage: result.warningMessage,
+            }), result.exitCode);
+            return;
+        }
+        writeCommandOutput({ body: result.body, exitCode: result.exitCode });
+    });
+}
+function formatMethodDuration(method) {
+    return (formatRenderLifecycleDuration({
+        lifecycle: {
+            status: method.status,
+            startedAt: method.startedAt,
+            completedAt: method.completedAt,
+        },
+        terminalStatuses: TERMINAL_VERIFICATION_STATUSES,
+    }) ?? "—");
+}
+function formatMethodVerifierLabel(method) {
+    if (method.method === "programmatic") {
+        return "programmatic";
+    }
+    return method.template ?? "rubric";
+}
+function formatMethodAgentLabel(method) {
+    if (method.method === "programmatic") {
+        return undefined;
+    }
+    return method.verifierId;
+}
+async function buildMethodBodyLines(options) {
+    const { root, aliasMap, method, isTty } = options;
+    if (!method.artifactPath) {
+        return undefined;
+    }
+    try {
+        const raw = await readFile(resolvePath(root, method.artifactPath), "utf8");
+        const parsed = JSON.parse(raw);
+        const validation = verificationResultArtifactSchema.safeParse(parsed);
+        if (!validation.success) {
+            return undefined;
+        }
+        const artifact = validation.data;
+        if (artifact.method === "programmatic") {
+            if (artifact.scope === "run") {
+                return renderTable({
+                    columns: [
+                        {
+                            header: "AGENT",
+                            accessor: (row) => row.candidateId,
+                        },
+                        {
+                            header: "CHECKS",
+                            accessor: (row) => row.results
+                                .map((result) => isTty
+                                ? colorize(result.slug, getCheckStatusStyle(result.status).cli)
+                                : result.slug)
+                                .join(" "),
+                        },
+                    ],
+                    rows: [...artifact.candidates],
+                });
+            }
+            return [`Results: ${artifact.results.length}`];
+        }
+        const lines = [];
+        const preferred = readRubricResultPreferred(artifact.result);
+        const rationale = readRubricResultRationale(artifact.result);
+        const nextActions = readRubricResultNextActions(artifact.result);
+        if (preferred) {
+            lines.push(`**Preferred**: ${deblindText(preferred, aliasMap)}`);
+        }
+        if (rationale) {
+            lines.push(`**Rationale**: ${deblindText(rationale, aliasMap)}`);
+        }
+        if (nextActions && nextActions.length > 0) {
+            lines.push("**Next Actions**:");
+            lines.push(...nextActions.map((action) => deblindText(action, aliasMap)));
+        }
+        if (lines.length > 0) {
+            return buildMarkdownPreviewLines(lines.join("\n"));
+        }
+        if (lines.length === 0) {
+            const narrative = readRubricResultNarrative(artifact.result);
+            if (narrative) {
+                lines.push(deblindText(narrative, aliasMap));
+            }
+        }
+        return lines.length > 0 ? lines : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function deblindText(value, aliasMap) {
+    if (!aliasMap) {
+        return value;
+    }
+    let result = value;
+    for (const [alias, canonicalId] of Object.entries(aliasMap).sort((a, b) => b[0].length - a[0].length)) {
+        result = result.split(alias).join(canonicalId);
+    }
+    return result.replace(/v_[a-z0-9]{10,16}/gu, (selector) => isBlindedCandidateAlias(selector)
+        ? `[unknown blinded alias: ${selector}]`
+        : selector);
+}

package/dist/commands/apply/command.d.ts

@@ -2,8 +2,10 @@ import type { ApplyResult } from "./types.js";
 export interface ApplyCommandInput {
     root: string;
     runsFilePath: string;
+    verificationsFilePath?: string;
     runId: string;
     agentId: string;
     ignoreBaseMismatch: boolean;
+    commit?: boolean;
 }
 export declare function executeApplyCommand(input: ApplyCommandInput): Promise<ApplyResult>;