@blockspool/cli 0.4.1 → 0.4.2

package/dist/lib/solo-hints.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Hints system for live steering of auto mode.
+ *
+ * Multiple frontends (stdin listener, `solo nudge` CLI) write to
+ * `.blockspool/hints.json`. The scout loop consumes pending hints
+ * and injects them into the scout prompt via `customPrompt`.
+ */
+export interface Hint {
+    id: string;
+    text: string;
+    createdAt: number;
+    consumed: boolean;
+}
+/**
+ * Read all hints from disk, pruning stale consumed ones.
+ */
+export declare function readHints(repoRoot: string): Hint[];
+/**
+ * Add a new hint. Returns the created hint.
+ */
+export declare function addHint(repoRoot: string, text: string): Hint;
+/**
+ * Consume all pending (unconsumed) hints.
+ * Marks them as consumed and returns a formatted prompt block,
+ * or null if there are no pending hints.
+ */
+export declare function consumePendingHints(repoRoot: string): string | null;
+/**
+ * Clear all hints.
+ */
+export declare function clearHints(repoRoot: string): void;
+//# sourceMappingURL=solo-hints.d.ts.map

package/dist/lib/solo-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solo-hints.d.ts","sourceRoot":"","sources":["../../src/lib/solo-hints.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAmBD;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,CAsBlD;AAgBD;;GAEG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAY5D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAanE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEjD"}

package/dist/lib/solo-hints.js

@@ -0,0 +1,98 @@
+/**
+ * Hints system for live steering of auto mode.
+ *
+ * Multiple frontends (stdin listener, `solo nudge` CLI) write to
+ * `.blockspool/hints.json`. The scout loop consumes pending hints
+ * and injects them into the scout prompt via `customPrompt`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+const HINTS_FILE = 'hints.json';
+const HINTS_TMP = 'hints.json.tmp';
+const MAX_HINT_LENGTH = 500;
+const PRUNE_AGE_MS = 60 * 60 * 1000; // 1 hour
+function hintsPath(repoRoot) {
+    return path.join(repoRoot, '.blockspool', HINTS_FILE);
+}
+function hintsTmpPath(repoRoot) {
+    return path.join(repoRoot, '.blockspool', HINTS_TMP);
+}
+function generateId() {
+    return crypto.randomBytes(8).toString('hex');
+}
+/**
+ * Read all hints from disk, pruning stale consumed ones.
+ */
+export function readHints(repoRoot) {
+    const fp = hintsPath(repoRoot);
+    if (!fs.existsSync(fp))
+        return [];
+    try {
+        const raw = fs.readFileSync(fp, 'utf-8');
+        const hints = JSON.parse(raw);
+        const now = Date.now();
+        // Prune consumed hints older than 1 hour
+        const kept = hints.filter((h) => !(h.consumed && now - h.createdAt > PRUNE_AGE_MS));
+        if (kept.length !== hints.length) {
+            atomicWrite(repoRoot, kept);
+        }
+        return kept;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Atomically write hints array to disk.
+ */
+function atomicWrite(repoRoot, hints) {
+    const dir = path.join(repoRoot, '.blockspool');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const tmp = hintsTmpPath(repoRoot);
+    const target = hintsPath(repoRoot);
+    fs.writeFileSync(tmp, JSON.stringify(hints, null, 2), 'utf-8');
+    fs.renameSync(tmp, target);
+}
+/**
+ * Add a new hint. Returns the created hint.
+ */
+export function addHint(repoRoot, text) {
+    const truncated = text.slice(0, MAX_HINT_LENGTH);
+    const hints = readHints(repoRoot);
+    const hint = {
+        id: generateId(),
+        text: truncated,
+        createdAt: Date.now(),
+        consumed: false,
+    };
+    hints.push(hint);
+    atomicWrite(repoRoot, hints);
+    return hint;
+}
+/**
+ * Consume all pending (unconsumed) hints.
+ * Marks them as consumed and returns a formatted prompt block,
+ * or null if there are no pending hints.
+ */
+export function consumePendingHints(repoRoot) {
+    const hints = readHints(repoRoot);
+    const pending = hints.filter((h) => !h.consumed);
+    if (pending.length === 0)
+        return null;
+    for (const h of pending) {
+        h.consumed = true;
+    }
+    atomicWrite(repoRoot, hints);
+    const lines = pending.map((h) => `- "${h.text}"`).join('\n');
+    return `\n## User Steering Hints\n${lines}`;
+}
+/**
+ * Clear all hints.
+ */
+export function clearHints(repoRoot) {
+    atomicWrite(repoRoot, []);
+}
+//# sourceMappingURL=solo-hints.js.map

package/dist/lib/solo-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solo-hints.js","sourceRoot":"","sources":["../../src/lib/solo-hints.ts"],"names":[],"mappings":"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"}

package/dist/lib/solo-remote.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Push safety — remote URL normalization and push-time assertion.
+ */
+/**
+ * Normalize a git remote URL to a canonical form: `github.com/org/repo`
+ * Handles SSH (`git@github.com:org/repo.git`) and HTTPS (`https://github.com/org/repo.git`).
+ */
+export declare function normalizeRemoteUrl(url: string): string;
+/**
+ * Assert that the current origin matches the allowed remote recorded at init time.
+ * Throws on mismatch. If `allowedRemote` is undefined, logs a warning but proceeds (backward compat).
+ */
+export declare function assertPushSafe(cwd: string, allowedRemote: string | undefined): Promise<void>;
+//# sourceMappingURL=solo-remote.d.ts.map

package/dist/lib/solo-remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solo-remote.d.ts","sourceRoot":"","sources":["../../src/lib/solo-remote.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAsBtD;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBlG"}

package/dist/lib/solo-remote.js

@@ -0,0 +1,48 @@
+/**
+ * Push safety — remote URL normalization and push-time assertion.
+ */
+import { execSync } from 'node:child_process';
+/**
+ * Normalize a git remote URL to a canonical form: `github.com/org/repo`
+ * Handles SSH (`git@github.com:org/repo.git`) and HTTPS (`https://github.com/org/repo.git`).
+ */
+export function normalizeRemoteUrl(url) {
+    let u = url.trim();
+    // SSH: git@github.com:org/repo.git → github.com/org/repo
+    const sshMatch = u.match(/^[\w-]+@([^:]+):(.+)$/);
+    if (sshMatch) {
+        u = `${sshMatch[1]}/${sshMatch[2]}`;
+    }
+    else {
+        // HTTPS: https://github.com/org/repo.git → github.com/org/repo
+        // eslint-disable-next-line security/detect-unsafe-regex
+        const httpsMatch = u.match(/^https?:\/\/([^/]+)(\/.*)?$/i);
+        if (httpsMatch) {
+            u = `${httpsMatch[1]}${httpsMatch[2] ?? ''}`;
+        }
+    }
+    // Strip trailing .git
+    u = u.replace(/\.git$/, '');
+    // Strip trailing slash
+    u = u.replace(/\/+$/, '');
+    return u.toLowerCase();
+}
+/**
+ * Assert that the current origin matches the allowed remote recorded at init time.
+ * Throws on mismatch. If `allowedRemote` is undefined, logs a warning but proceeds (backward compat).
+ */
+export async function assertPushSafe(cwd, allowedRemote) {
+    if (allowedRemote === undefined) {
+        console.warn('[push-safety] No allowedRemote configured — skipping push guard. Run "blockspool solo init --force" to set one.');
+        return;
+    }
+    const currentRemote = execSync('git remote get-url origin', { cwd, encoding: 'utf-8' }).trim();
+    const normalizedCurrent = normalizeRemoteUrl(currentRemote);
+    const normalizedAllowed = normalizeRemoteUrl(allowedRemote);
+    if (normalizedCurrent !== normalizedAllowed) {
+        throw new Error(`Push blocked: origin "${currentRemote}" (normalized: ${normalizedCurrent}) does not match ` +
+            `allowed remote "${allowedRemote}" (normalized: ${normalizedAllowed}). ` +
+            'Re-run "blockspool solo init --force" if this is intentional.');
+    }
+}
+//# sourceMappingURL=solo-remote.js.map

package/dist/lib/solo-remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solo-remote.js","sourceRoot":"","sources":["../../src/lib/solo-remote.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAEnB,yDAAyD;IACzD,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAClD,IAAI,QAAQ,EAAE,CAAC;QACb,CAAC,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACtC,CAAC;SAAM,CAAC;QACN,+DAA+D;QAC/D,wDAAwD;QACxD,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAC3D,IAAI,UAAU,EAAE,CAAC;YACf,CAAC,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5B,uBAAuB;IACvB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAE1B,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW,EAAE,aAAiC;IACjF,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC,iHAAiH,CAAC,CAAC;QAChI,OAAO;IACT,CAAC;IAED,MAAM,aAAa,GAAG,QAAQ,CAAC,2BAA2B,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/F,MAAM,iBAAiB,GAAG,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAC5D,MAAM,iBAAiB,GAAG,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAE5D,IAAI,iBAAiB,KAAK,iBAAiB,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CACb,yBAAyB,aAAa,kBAAkB,iBAAiB,mBAAmB;YAC5F,mBAAmB,aAAa,kBAAkB,iBAAiB,KAAK;YACxE,+DAA+D,CAChE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/lib/solo-stdin.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Non-blocking stdin listener for live hints during auto mode.
+ *
+ * When running in a TTY, reads lines from stdin and adds them
+ * as hints via the solo-hints module.
+ */
+/**
+ * Start listening for hint input on stdin.
+ * Returns a cleanup function that stops listening.
+ * Only activates when stdin is a TTY.
+ */
+export declare function startStdinListener(repoRoot: string): () => void;
+//# sourceMappingURL=solo-stdin.d.ts.map

package/dist/lib/solo-stdin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solo-stdin.d.ts","sourceRoot":"","sources":["../../src/lib/solo-stdin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,IAAI,CAoB/D"}

package/dist/lib/solo-stdin.js

@@ -0,0 +1,33 @@
+/**
+ * Non-blocking stdin listener for live hints during auto mode.
+ *
+ * When running in a TTY, reads lines from stdin and adds them
+ * as hints via the solo-hints module.
+ */
+import chalk from 'chalk';
+import { addHint } from './solo-hints.js';
+/**
+ * Start listening for hint input on stdin.
+ * Returns a cleanup function that stops listening.
+ * Only activates when stdin is a TTY.
+ */
+export function startStdinListener(repoRoot) {
+    if (!process.stdin.isTTY) {
+        return () => { };
+    }
+    const onData = (data) => {
+        const text = data.trim();
+        if (!text)
+            return;
+        const hint = addHint(repoRoot, text);
+        console.log(chalk.yellow(`💡 Hint added: "${hint.text}"`));
+    };
+    process.stdin.setEncoding('utf8');
+    process.stdin.resume();
+    process.stdin.on('data', onData);
+    return () => {
+        process.stdin.removeListener('data', onData);
+        process.stdin.pause();
+    };
+}
+//# sourceMappingURL=solo-stdin.js.map

package/dist/lib/solo-stdin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solo-stdin.js","sourceRoot":"","sources":["../../src/lib/solo-stdin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,mBAAmB,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAC7D,CAAC,CAAC;IAEF,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IACvB,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,OAAO,GAAG,EAAE;QACV,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/solo-ticket.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Solo mode ticket execution
+ */
+import { tickets, type StepKind } from '@blockspool/core/repos';
+import type { SoloConfig } from './solo-config.js';
+import { getAdapter } from './solo-config.js';
+/**
+ * Canonical failure reasons for run results
+ */
+export type FailureReason = 'agent_error' | 'scope_violation' | 'spindle_abort' | 'qa_failed' | 'git_error' | 'pr_error' | 'timeout' | 'cancelled';
+/**
+ * Outcome type for successful completions that don't involve code changes
+ */
+export type CompletionOutcome = 'no_changes_needed';
+/**
+ * Spindle abort details for diagnostics
+ */
+export interface SpindleAbortDetails {
+    trigger: 'oscillation' | 'spinning' | 'stalling' | 'repetition' | 'token_budget';
+    confidence: number;
+    estimatedTokens: number;
+    iteration: number;
+    thresholds: {
+        similarityThreshold: number;
+        maxSimilarOutputs: number;
+        maxStallIterations: number;
+        tokenBudgetWarning: number;
+        tokenBudgetAbort: number;
+    };
+    metrics: {
+        similarityScore?: number;
+        iterationsWithoutChange?: number;
+        repeatedPatterns?: string[];
+        oscillationPattern?: string;
+    };
+    recommendations: string[];
+    artifactPath: string;
+}
+/**
+ * Result of running a ticket
+ */
+export interface RunTicketResult {
+    success: boolean;
+    branchName?: string;
+    prUrl?: string;
+    durationMs: number;
+    error?: string;
+    failureReason?: FailureReason;
+    completionOutcome?: CompletionOutcome;
+    spindle?: SpindleAbortDetails;
+    artifacts?: {
+        execution?: string;
+        diff?: string;
+        violations?: string;
+        spindle?: string;
+        runSummary?: string;
+    };
+    scopeExpanded?: {
+        addedPaths: string[];
+        newRetryCount: number;
+    };
+}
+/**
+ * Exit codes for solo run
+ */
+export declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly FAILURE: 1;
+    readonly SPINDLE_ABORT: 2;
+    readonly SIGINT: 130;
+};
+/**
+ * Options for running a ticket
+ */
+export interface RunTicketOptions {
+    ticket: Awaited<ReturnType<typeof tickets.getById>> & {};
+    repoRoot: string;
+    config: SoloConfig | null;
+    adapter: Awaited<ReturnType<typeof getAdapter>>;
+    runId: string;
+    skipQa: boolean;
+    createPr: boolean;
+    draftPr?: boolean;
+    timeoutMs: number;
+    verbose: boolean;
+    onProgress: (msg: string) => void;
+    /** Override the base branch for worktree creation (e.g. milestone branch) */
+    baseBranch?: string;
+    /** Skip pushing the branch to origin */
+    skipPush?: boolean;
+    /** Skip PR creation even if createPr is true */
+    skipPr?: boolean;
+    /** Execution backend override (default: ClaudeExecutionBackend) */
+    executionBackend?: ExecutionBackend;
+    /** Project guidelines context to prepend to execution prompt */
+    guidelinesContext?: string;
+}
+/**
+ * Execution step definitions
+ */
+declare const EXECUTE_STEPS: readonly [{
+    readonly name: "worktree";
+    readonly kind: StepKind;
+}, {
+    readonly name: "agent";
+    readonly kind: StepKind;
+}, {
+    readonly name: "scope";
+    readonly kind: StepKind;
+}, {
+    readonly name: "commit";
+    readonly kind: StepKind;
+}, {
+    readonly name: "push";
+    readonly kind: StepKind;
+}, {
+    readonly name: "qa";
+    readonly kind: StepKind;
+}, {
+    readonly name: "pr";
+    readonly kind: StepKind;
+}, {
+    readonly name: "cleanup";
+    readonly kind: StepKind;
+}];
+export type StepName = typeof EXECUTE_STEPS[number]['name'];
+/**
+ * Build the prompt for Claude from a ticket
+ */
+export declare function buildTicketPrompt(ticket: NonNullable<Awaited<ReturnType<typeof tickets.getById>>>, guidelinesContext?: string): string;
+/**
+ * Execution result with full details for artifact storage
+ */
+export interface ClaudeResult {
+    success: boolean;
+    error?: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    durationMs: number;
+}
+/**
+ * Pluggable execution backend interface
+ */
+export interface ExecutionBackend {
+    /** Human-readable name for logging */
+    readonly name: string;
+    /** Run a prompt against a worktree and return the result */
+    run(opts: {
+        worktreePath: string;
+        prompt: string;
+        timeoutMs: number;
+        verbose: boolean;
+        onProgress: (msg: string) => void;
+    }): Promise<ClaudeResult>;
+}
+/**
+ * Claude Code CLI execution backend (default)
+ */
+export declare class ClaudeExecutionBackend implements ExecutionBackend {
+    readonly name = "claude";
+    run(opts: {
+        worktreePath: string;
+        prompt: string;
+        timeoutMs: number;
+        verbose: boolean;
+        onProgress: (msg: string) => void;
+    }): Promise<ClaudeResult>;
+}
+/**
+ * Codex CLI execution backend
+ *
+ * Default: `--sandbox workspace-write --ask-for-approval never` (safe unattended mode).
+ * Optional: `unsafeBypassSandbox` enables `--dangerously-bypass-approvals-and-sandbox`
+ * for use inside externally hardened/isolated runners only.
+ */
+export declare class CodexExecutionBackend implements ExecutionBackend {
+    readonly name = "codex";
+    private apiKey?;
+    private model;
+    private unsafeBypassSandbox;
+    constructor(opts?: {
+        apiKey?: string;
+        model?: string;
+        unsafeBypassSandbox?: boolean;
+    });
+    run(opts: {
+        worktreePath: string;
+        prompt: string;
+        timeoutMs: number;
+        verbose: boolean;
+        onProgress: (msg: string) => void;
+    }): Promise<ClaudeResult>;
+}
+/**
+ * Run Claude Code CLI
+ */
+export declare function runClaude(opts: {
+    worktreePath: string;
+    prompt: string;
+    timeoutMs: number;
+    verbose: boolean;
+    onProgress: (msg: string) => void;
+}): Promise<ClaudeResult>;
+/**
+ * Execute a ticket in isolation with step tracking
+ *
+ * Steps tracked: worktree → agent → commit → push → qa → pr → cleanup
+ */
+export declare function soloRunTicket(opts: RunTicketOptions): Promise<RunTicketResult>;
+export {};
+//# sourceMappingURL=solo-ticket.d.ts.map

package/dist/lib/solo-ticket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solo-ticket.d.ts","sourceRoot":"","sources":["../../src/lib/solo-ticket.ts"],"names":[],"mappings":"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"}