profclaw 2.0.0 → 2.4.0

package/dist/cli/commands/plan.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Plan Mode CLI Commands
+ *
+ * View and manage agent plans created during plan-mode sessions.
+ *
+ * Usage:
+ *   profclaw plan list
+ *   profclaw plan show <id>
+ *   profclaw plan approve <id>
+ */
+import { Command } from 'commander';
+export declare function planCommands(): Command;
+//# sourceMappingURL=plan.d.ts.map

package/dist/cli/commands/plan.js

@@ -0,0 +1,184 @@
+/**
+ * Plan Mode CLI Commands
+ *
+ * View and manage agent plans created during plan-mode sessions.
+ *
+ * Usage:
+ *   profclaw plan list
+ *   profclaw plan show <id>
+ *   profclaw plan approve <id>
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { planManager } from '../../agents/plan-mode.js';
+import { createTable, formatRelativeTime, success, error, warn, truncate, } from '../utils/output.js';
+// ─── Status formatting ───────────────────────────────────────────────────────
+const PLAN_STATUS_COLORS = {
+    draft: chalk.yellow,
+    approved: chalk.blue,
+    in_progress: chalk.cyan,
+    completed: chalk.green,
+    rejected: chalk.red,
+};
+const STEP_STATUS_SYMBOLS = {
+    pending: chalk.dim('○'),
+    in_progress: chalk.cyan('◑'),
+    completed: chalk.green('●'),
+    skipped: chalk.gray('–'),
+};
+function formatPlanStatus(status) {
+    const colorFn = PLAN_STATUS_COLORS[status] ?? chalk.white;
+    return colorFn(status.toUpperCase().replace('_', ' '));
+}
+// ─── Command builder ─────────────────────────────────────────────────────────
+export function planCommands() {
+    const plan = new Command('plan').description('Manage agent implementation plans');
+    // ── list ──────────────────────────────────────────────────────────────────
+    plan
+        .command('list')
+        .alias('ls')
+        .description('List all plans')
+        .option('-s, --status <status>', 'Filter by status (draft|approved|in_progress|completed|rejected)')
+        .option('--json', 'Output as JSON')
+        .action((options) => {
+        let plans = planManager.list();
+        if (options.status) {
+            plans = plans.filter((p) => p.status === options.status);
+        }
+        if (options.json) {
+            console.log(JSON.stringify(plans, null, 2));
+            return;
+        }
+        if (plans.length === 0) {
+            console.log(chalk.dim('No plans found.'));
+            return;
+        }
+        const table = createTable(['ID', 'Title', 'Status', 'Steps', 'Created']);
+        for (const p of plans) {
+            const doneSteps = p.steps.filter((s) => s.status === 'completed' || s.status === 'skipped').length;
+            table.push([
+                p.id.slice(0, 8),
+                truncate(p.title, 40),
+                formatPlanStatus(p.status),
+                `${doneSteps}/${p.steps.length}`,
+                formatRelativeTime(new Date(p.createdAt)),
+            ]);
+        }
+        console.log(table.toString());
+        console.log(chalk.dim(`\n${plans.length} plan(s) total`));
+    });
+    // ── show ──────────────────────────────────────────────────────────────────
+    plan
+        .command('show <id>')
+        .alias('get')
+        .description('Show plan details and step list')
+        .option('--json', 'Output as JSON')
+        .action((id, options) => {
+        // Support partial ID prefix matching
+        const allPlans = planManager.list();
+        const found = allPlans.find((p) => p.id === id || p.id.startsWith(id));
+        if (!found) {
+            error(`Plan not found: ${id}`);
+            process.exit(1);
+        }
+        if (options.json) {
+            console.log(JSON.stringify(found, null, 2));
+            return;
+        }
+        console.log('');
+        console.log(chalk.bold(`Plan: ${found.id}`));
+        console.log(`Title:   ${found.title}`);
+        console.log(`Status:  ${formatPlanStatus(found.status)}`);
+        console.log(`Created: ${formatRelativeTime(new Date(found.createdAt))}`);
+        if (found.approvedAt) {
+            console.log(`Approved: ${formatRelativeTime(new Date(found.approvedAt))}`);
+        }
+        if (found.completedAt) {
+            console.log(`Completed: ${formatRelativeTime(new Date(found.completedAt))}`);
+        }
+        if (found.rejectionReason) {
+            console.log(`Rejection reason: ${chalk.red(found.rejectionReason)}`);
+        }
+        if (found.taskId) {
+            console.log(`Task ID: ${found.taskId}`);
+        }
+        console.log('');
+        console.log(chalk.bold('Steps:'));
+        for (const step of found.steps) {
+            const symbol = STEP_STATUS_SYMBOLS[step.status];
+            const effort = step.estimatedEffort ? chalk.dim(` [${step.estimatedEffort}]`) : '';
+            console.log(`  ${symbol} ${step.index}. ${step.description}${effort}`);
+            if (step.files && step.files.length > 0) {
+                for (const f of step.files) {
+                    console.log(`       ${chalk.dim(f)}`);
+                }
+            }
+        }
+        console.log('');
+    });
+    // ── approve ───────────────────────────────────────────────────────────────
+    plan
+        .command('approve <id>')
+        .description('Approve a pending plan so the agent can begin implementation')
+        .option('--json', 'Output as JSON')
+        .action((id, options) => {
+        const allPlans = planManager.list();
+        const found = allPlans.find((p) => p.id === id || p.id.startsWith(id));
+        if (!found) {
+            error(`Plan not found: ${id}`);
+            process.exit(1);
+        }
+        if (found.status !== 'draft') {
+            warn(`Plan ${found.id.slice(0, 8)} is already ${found.status}, cannot approve.`);
+            process.exit(1);
+        }
+        try {
+            const approved = planManager.approve(found.id);
+            if (options.json) {
+                console.log(JSON.stringify(approved, null, 2));
+                return;
+            }
+            success(`Plan approved: ${approved.id.slice(0, 8)} — "${approved.title}"`);
+            console.log(chalk.dim('The agent will now begin implementation.'));
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : 'Failed to approve plan');
+            process.exit(1);
+        }
+    });
+    // ── reject ────────────────────────────────────────────────────────────────
+    plan
+        .command('reject <id>')
+        .description('Reject a pending plan')
+        .option('-r, --reason <reason>', 'Reason for rejection')
+        .option('--json', 'Output as JSON')
+        .action((id, options) => {
+        const allPlans = planManager.list();
+        const found = allPlans.find((p) => p.id === id || p.id.startsWith(id));
+        if (!found) {
+            error(`Plan not found: ${id}`);
+            process.exit(1);
+        }
+        if (found.status !== 'draft') {
+            warn(`Plan ${found.id.slice(0, 8)} is already ${found.status}, cannot reject.`);
+            process.exit(1);
+        }
+        try {
+            const rejected = planManager.reject(found.id, options.reason);
+            if (options.json) {
+                console.log(JSON.stringify(rejected, null, 2));
+                return;
+            }
+            console.log(chalk.red('✗') + ` Plan rejected: ${rejected.id.slice(0, 8)}`);
+            if (options.reason) {
+                console.log(chalk.dim(`Reason: ${options.reason}`));
+            }
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : 'Failed to reject plan');
+            process.exit(1);
+        }
+    });
+    return plan;
+}
+//# sourceMappingURL=plan.js.map

package/dist/cli/commands/receipt.d.ts

@@ -0,0 +1,7 @@
+/**
+ * profclaw receipt: verify, view and key generation for run receipts.
+ * Spec: docs/specs/run-receipt-v0.md
+ */
+import { Command } from 'commander';
+export declare function receiptCommand(): Command;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/cli/commands/receipt.js

@@ -0,0 +1,90 @@
+/**
+ * profclaw receipt: verify, view and key generation for run receipts.
+ * Spec: docs/specs/run-receipt-v0.md
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { verifyReceiptText, parseReceiptText } from '../../agents/receipt/receipt-verify.js';
+import { renderHtml, renderTerminalSummary } from '../../agents/receipt/receipt-view.js';
+import { generateKeyPairFiles } from '../../agents/receipt/receipt-cli.js';
+import { error, info, success } from '../utils/output.js';
+function readOrExit(file) {
+    try {
+        return readFileSync(file, 'utf-8');
+    }
+    catch (err) {
+        error(`Cannot read ${file}: ${err instanceof Error ? err.message : 'unknown error'}`);
+        process.exitCode = 1;
+        return null;
+    }
+}
+export function receiptCommand() {
+    const cmd = new Command('receipt').description('Verify, view and sign tamper-evident run receipts');
+    cmd
+        .command('verify')
+        .description('Check a receipt: exit 0 if intact, 1 if tampered, truncated or invalid')
+        .argument('<file>', 'Path to receipt.jsonl')
+        .option('--pubkey <file>', 'Trusted Ed25519 public key (PEM); the receipt must be signed by it')
+        .option('--require-signature', 'Fail if the receipt is not signed')
+        .action((file, opts) => {
+        const text = readOrExit(file);
+        if (text === null)
+            return;
+        let expectedPublicKey;
+        if (opts.pubkey) {
+            const key = readOrExit(opts.pubkey);
+            if (key === null)
+                return;
+            expectedPublicKey = key;
+        }
+        const result = verifyReceiptText(text, { expectedPublicKey, requireSignature: opts.requireSignature });
+        if (result.ok) {
+            success(result.message);
+            info('This shows the receipt was not altered after it was written. It does not prove the run happened.');
+            process.exitCode = 0;
+        }
+        else {
+            error(`TAMPERED or invalid at seq ${result.firstBadSeq ?? 0} (${result.reason ?? 'unknown'}): ${result.message}`);
+            process.exitCode = 1;
+        }
+    });
+    cmd
+        .command('view')
+        .description('Print a summary, or write a self-contained HTML viewer with --html')
+        .argument('<file>', 'Path to receipt.jsonl')
+        .option('--html <out>', 'Write a single-file HTML viewer to this path')
+        .action((file, opts) => {
+        const text = readOrExit(file);
+        if (text === null)
+            return;
+        const verify = verifyReceiptText(text);
+        const events = parseReceiptText(text);
+        if (opts.html) {
+            writeFileSync(opts.html, renderHtml(events, verify), 'utf-8');
+            info(`Wrote ${opts.html}`);
+        }
+        else {
+            process.stdout.write(renderTerminalSummary(events, verify));
+        }
+        if (!verify.ok)
+            process.exitCode = 1;
+    });
+    cmd
+        .command('keygen')
+        .description('Write an Ed25519 keypair for signing receipts (private key mode 0600)')
+        .argument('<dir>', 'Directory to write receipt-key.pem and receipt-key.pub.pem into')
+        .action((dir) => {
+        try {
+            const files = generateKeyPairFiles(dir);
+            success(`Private key: ${files.privateKeyPath} (keep it off the machine that runs agents if you can)`);
+            info(`Public key:  ${files.publicKeyPath}`);
+            info('Sign with --sign-key <private key> or env PROFCLAW_RECEIPT_KEY; check with: profclaw receipt verify <file> --pubkey <public key>');
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : 'Key generation failed');
+            process.exitCode = 1;
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=receipt.js.map

package/dist/cli/commands/run.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Verified Run CLI Command
+ *
+ * Usage:
+ *   profclaw run "<goal>" --verify "pnpm test"                 (built-in agent)
+ *   profclaw run "<goal>" --verify "pnpm test" --agent-cmd "my-agent-cli"
+ *
+ * Done means verified: the run only succeeds when the verify command exits 0.
+ * Work happens in an isolated git worktree on a local branch. Nothing is
+ * pushed and no PR is opened.
+ *
+ * By default the built-in model-backed agent runs inside the worktree, starting
+ * on the smart router's cheap model and escalating a tier after repeated
+ * verifier failures. --agent-cmd overrides it with an external agent; the goal
+ * and feedback are written to that agent's stdin, never interpolated into a
+ * shell string.
+ */
+import { Command } from 'commander';
+import type { AgentAttemptInput, AgentAttemptResult, AgentRunner } from '../../agents/verified-run.js';
+/** Runs an external agent command, feeding the prompt on stdin. */
+export declare class CommandAgent implements AgentRunner {
+    private readonly command;
+    constructor(command: string);
+    runAttempt(input: AgentAttemptInput): Promise<AgentAttemptResult>;
+}
+export declare function buildPrompt(input: AgentAttemptInput): string;
+export declare function runCommand(): Command;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/commands/run.js

@@ -0,0 +1,204 @@
+/**
+ * Verified Run CLI Command
+ *
+ * Usage:
+ *   profclaw run "<goal>" --verify "pnpm test"                 (built-in agent)
+ *   profclaw run "<goal>" --verify "pnpm test" --agent-cmd "my-agent-cli"
+ *
+ * Done means verified: the run only succeeds when the verify command exits 0.
+ * Work happens in an isolated git worktree on a local branch. Nothing is
+ * pushed and no PR is opened.
+ *
+ * By default the built-in model-backed agent runs inside the worktree, starting
+ * on the smart router's cheap model and escalating a tier after repeated
+ * verifier failures. --agent-cmd overrides it with an external agent; the goal
+ * and feedback are written to that agent's stdin, never interpolated into a
+ * shell string.
+ */
+import { spawn } from 'node:child_process';
+import { Command } from 'commander';
+import { describeSandbox, resolveSandboxMode } from '../../agents/command-sandbox.js';
+import { CommandVerifier } from '../../agents/verifier.js';
+import { runVerifiedGoal, resolveLimits } from '../../agents/verified-run.js';
+import { createDefaultExecutorRunner } from '../../agents/executor-runner.js';
+import { setupRunReceipt, toolVersion } from '../../agents/receipt/receipt-cli.js';
+import { error, info, success, warn, formatCost, formatTokens } from '../utils/output.js';
+/** Runs an external agent command, feeding the prompt on stdin. */
+export class CommandAgent {
+    command;
+    constructor(command) {
+        this.command = command;
+    }
+    runAttempt(input) {
+        const prompt = buildPrompt(input);
+        return new Promise((resolve, reject) => {
+            const child = spawn('/bin/sh', ['-c', this.command], {
+                cwd: input.workdir,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let out = '';
+            child.stdout.on('data', (d) => {
+                out = (out + d.toString('utf-8')).slice(-4000);
+            });
+            child.stderr.on('data', (d) => {
+                out = (out + d.toString('utf-8')).slice(-4000);
+            });
+            input.signal?.addEventListener('abort', () => child.kill('SIGTERM'), { once: true });
+            child.on('error', reject);
+            child.on('close', (code) => {
+                if (code === 0)
+                    resolve({ summary: out.trim().slice(-500), tokensUsed: 0, costUsd: 0 });
+                else
+                    reject(new Error(`agent command exited with code ${code ?? 'null'}: ${out.trim().slice(-500)}`));
+            });
+            child.stdin.on('error', () => undefined);
+            child.stdin.end(prompt);
+        });
+    }
+}
+export function buildPrompt(input) {
+    const parts = [
+        `Goal: ${input.goal}`,
+        `Work only inside: ${input.workdir}`,
+        `Your work is judged by running: ${input.verifyCommand}`,
+        'Do not push to any remote or open pull requests.',
+    ];
+    if (input.feedback)
+        parts.push('', `Attempt ${input.attempt}. Previous attempt feedback:`, input.feedback);
+    return parts.join('\n') + '\n';
+}
+function parseNumber(raw, name) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        throw new Error(`${name} must be a non-negative number`);
+    return n;
+}
+function formatAttemptUsage(record) {
+    const parts = [`${formatTokens(record.tokensUsed)} tokens`];
+    if (record.cacheHitRate !== undefined)
+        parts.push(`cache hit ${(record.cacheHitRate * 100).toFixed(0)}%`);
+    parts.push(formatCost(record.costUsd));
+    if (record.model)
+        parts.push(record.model);
+    return parts.join(', ');
+}
+function printRunnerEvent(event) {
+    const { attempt, choice, escalated } = event;
+    const prefix = escalated ? 'Escalating to' : 'Using';
+    info(`Attempt ${attempt}: ${prefix} ${choice.provider}/${choice.model} (${choice.tier})`);
+}
+function printEvent(event) {
+    if (event.type === 'start')
+        info(`Run ${event.runId} on branch ${event.branch}`);
+    else if (event.type === 'attempt_start')
+        info(`Attempt ${event.attempt}...`);
+    else if (event.type === 'attempt_end') {
+        const { record } = event;
+        const line = `Attempt ${record.attempt}: ${record.outcome}${record.rolledBack ? ' (rolled back)' : ''} [${formatAttemptUsage(record)}]`;
+        if (record.outcome === 'verified')
+            success(line);
+        else
+            warn(line);
+    }
+}
+export function runCommand() {
+    return new Command('run')
+        .description('Run an agent toward a goal and only finish when a verify command passes')
+        .argument('<goal>', 'What the agent should accomplish')
+        .requiredOption('--verify <command>', 'Command that must exit 0 (tests, typecheck, lint, build)')
+        .option('--agent-cmd <command>', 'External agent command (overrides the built-in agent); receives the prompt on stdin')
+        .option('--model <ids>', 'Model, or comma separated ladder cheapest first (env PROFCLAW_RUN_MODEL); default: smart router')
+        .option('--escalate-after <n>', 'Verifier failures in a row before moving up a model tier, 0 disables (env PROFCLAW_RUN_ESCALATE_AFTER)')
+        .option('--max-attempts <n>', 'Maximum attempts (env PROFCLAW_RUN_MAX_ATTEMPTS)')
+        .option('--max-tokens <n>', 'Token budget, 0 disables (env PROFCLAW_RUN_MAX_TOKENS)')
+        .option('--max-cost <usd>', 'Dollar budget, 0 disables (env PROFCLAW_RUN_MAX_COST_USD)')
+        .option('--breaker <n>', 'Non-improving attempts before the circuit breaker trips (env PROFCLAW_RUN_BREAKER_THRESHOLD)')
+        .option('--verify-timeout <ms>', 'Verifier timeout (env PROFCLAW_RUN_VERIFY_TIMEOUT_MS)')
+        .option('--branch <name>', 'Branch name for the run (default profclaw/run-<id>)')
+        .option('--sandbox-verify', 'Also run the verify command under the OS sandbox (env PROFCLAW_RUN_SANDBOX_VERIFY=1); default off')
+        .option('--cleanup', 'Remove the worktree afterwards (the branch is kept)')
+        .option('--no-receipt', 'Do not write a tamper-evident receipt.jsonl for the run')
+        .option('--sign-key <path>', 'Ed25519 private key (PEM) to sign the receipt (env PROFCLAW_RECEIPT_KEY)')
+        .option('--json', 'Output the result as JSON')
+        .action(async (goal, options) => {
+        try {
+            const flags = {
+                maxAttempts: parseNumber(options.maxAttempts, '--max-attempts'),
+                maxTokens: parseNumber(options.maxTokens, '--max-tokens'),
+                maxCostUsd: parseNumber(options.maxCost, '--max-cost'),
+                breakerThreshold: parseNumber(options.breaker, '--breaker'),
+                verifyTimeoutMs: parseNumber(options.verifyTimeout, '--verify-timeout'),
+            };
+            for (const key of Object.keys(flags)) {
+                if (flags[key] === undefined)
+                    delete flags[key];
+            }
+            const verifyCommand = options.verify;
+            const sandboxMode = resolveSandboxMode();
+            const sandboxVerify = options.sandboxVerify === true || process.env.PROFCLAW_RUN_SANDBOX_VERIFY === '1';
+            if (!options.json)
+                info(`${describeSandbox(sandboxMode)}${sandboxVerify ? '; verify command sandboxed' : ''}`);
+            const limits = resolveLimits(flags);
+            const rc = setupRunReceipt({ enabled: options.receipt !== false, projectRoot: process.cwd(), signKeyPath: options.signKey });
+            const agent = options.agentCmd
+                ? new CommandAgent(options.agentCmd)
+                : await createDefaultExecutorRunner({
+                    goal,
+                    model: options.model,
+                    config: { escalateAfter: parseNumber(options.escalateAfter, '--escalate-after') },
+                    maxTokens: limits.maxTokens,
+                    maxCostUsd: limits.maxCostUsd,
+                    onEvent: options.json ? undefined : printRunnerEvent,
+                    onToolCall: rc.onToolCall,
+                });
+            const result = await runVerifiedGoal({
+                goal,
+                verifyCommand,
+                agent,
+                projectRoot: process.cwd(),
+                runId: rc.runId,
+                receipt: rc.receipt,
+                toolInfo: { name: 'profclaw', version: toolVersion() },
+                limits: flags,
+                branchName: options.branch,
+                removeWorktree: options.cleanup,
+                onEvent: options.json ? undefined : printEvent,
+                createVerifier: (cwd) => new CommandVerifier(verifyCommand, {
+                    cwd,
+                    timeoutMs: flags.verifyTimeoutMs ?? Number(process.env.PROFCLAW_RUN_VERIFY_TIMEOUT_MS ?? 600_000),
+                    maxOutputChars: Number(process.env.PROFCLAW_RUN_MAX_OUTPUT_CHARS ?? 4_000),
+                    sandbox: sandboxVerify ? { mode: sandboxMode } : undefined,
+                }),
+            });
+            if (options.json) {
+                console.log(JSON.stringify({ ...result, diff: undefined }, null, 2));
+            }
+            else if (result.verified) {
+                success(`Verified after ${result.attempts.length} attempt(s), cost ${formatCost(result.totalCostUsd)}`);
+                info(`Branch ${result.branch} is ready for review (not pushed).`);
+                if (result.reportPath)
+                    info(`Evidence: ${result.reportPath}`);
+                if (rc.receipt)
+                    info(`Receipt: ${rc.receipt.path}`);
+            }
+            else if (result.stopReason === 'already_passing') {
+                warn('The verify command already passes before any change, so no attempt was made.');
+                if (result.reportPath)
+                    info(`Report: ${result.reportPath}`);
+            }
+            else {
+                error(`Not verified (${result.stopReason}) after ${result.attempts.length} attempt(s)`);
+                if (result.reportPath)
+                    info(`Report: ${result.reportPath}`);
+            }
+            process.exitCode = result.verified || result.stopReason === 'already_passing' ? 0 : 1;
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : 'Verified run failed');
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/commands/serve.d.ts

@@ -1,3 +1,10 @@
 import { Command } from 'commander';
+export declare function checkPortAvailable(port: number): Promise<boolean>;
+/**
+ * Try to find an available port starting at `startPort`.
+ * Attempts up to MAX_PORT_ATTEMPTS consecutive ports.
+ * Returns the available port, or null if all attempts fail.
+ */
+export declare function resolvePort(startPort: number): Promise<number | null>;
 export declare function serveCommand(): Command;
 //# sourceMappingURL=serve.d.ts.map