patchwork-os 0.2.0-alpha.0

package/dist/claudeMdPatch.js

@@ -0,0 +1,164 @@
+/**
+ * CLAUDE.md versioned-block patching helpers.
+ *
+ * Extracted from src/index.ts so tests can import the pure helpers without
+ * triggering the top-level CLI side effects (parseConfig + Bridge.start)
+ * that otherwise cause ports like 55000 to be bound from a test run.
+ */
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { PACKAGE_VERSION } from "./version.js";
+/**
+ * Returns the sentinel comment that opens a versioned bridge block in CLAUDE.md.
+ * Format: <!-- claude-ide-bridge:start:VERSION -->
+ */
+export function bridgeBlockStartMarker(version) {
+    return `<!-- claude-ide-bridge:start:${version} -->`;
+}
+/** Sentinel comment that closes a versioned bridge block in CLAUDE.md. */
+export const BRIDGE_BLOCK_END = "<!-- claude-ide-bridge:end -->";
+/** Regex that matches ANY versioned bridge block (any version). */
+export const BRIDGE_BLOCK_RE = /<!-- claude-ide-bridge:start:[^\s>]+ -->[\s\S]*?<!-- claude-ide-bridge:end -->/g;
+/** Regex that matches a versioned bridge block with a specific version captured. */
+const BRIDGE_BLOCK_VERSION_RE = /<!-- claude-ide-bridge:start:([^\s>]+) -->[\s\S]*?<!-- claude-ide-bridge:end -->/;
+/**
+ * Returns the version embedded in an existing versioned bridge block in
+ * CLAUDE.md content, or null if no block is present.
+ */
+export function extractClaudeMdBlockVersion(content) {
+    const m = BRIDGE_BLOCK_VERSION_RE.exec(content);
+    return m?.[1] ?? null;
+}
+/**
+ * Wraps the bridge section (marker line + import line) in versioned sentinels.
+ */
+function buildVersionedBlock(marker, importLine, version) {
+    return `${bridgeBlockStartMarker(version)}\n${marker}\n${importLine}\n${BRIDGE_BLOCK_END}`;
+}
+/**
+ * Patches CLAUDE.md with a versioned bridge block that init can detect and
+ * update on re-run.
+ *
+ * Logic:
+ *   - If a versioned block with the current version exists → "already-current"
+ *   - If a versioned block with a different version exists → replace it → "updated"
+ *   - If the unversioned marker exists but no versioned block → wrap it → "patched"
+ *   - If the import line exists standalone (no marker block) → "already-present"
+ *   - Otherwise → "no-section"
+ *
+ * All writes are atomic (write to .tmp with exclusive-create, backup original,
+ * rename into place).
+ */
+export function patchClaudeMdImport(targetPath, marker, importLine, version = PACKAGE_VERSION) {
+    if (!existsSync(targetPath))
+        return "no-section";
+    const existing = readFileSync(targetPath, "utf-8");
+    // Case 1: versioned block present — check if current
+    const existingVersion = extractClaudeMdBlockVersion(existing);
+    if (existingVersion !== null) {
+        if (existingVersion === version)
+            return "already-current";
+        // Stale versioned block → replace
+        const newBlock = buildVersionedBlock(marker, importLine, version);
+        const patched = existing.replace(BRIDGE_BLOCK_RE, newBlock);
+        if (patched === existing)
+            return "no-section"; // safety guard
+        const remaining = (patched.match(/<!-- claude-ide-bridge:start:/g) ?? [])
+            .length;
+        if (remaining > 1) {
+            console.warn(`[patchClaudeMdImport] ${remaining} bridge start sentinels remain after replace — manual cleanup may be needed in ${targetPath}`);
+        }
+        writePatchedClaudeMd(targetPath, patched);
+        return "updated";
+    }
+    // Case 2: unversioned marker present — wrap it
+    if (existing.includes(marker)) {
+        if (existing.includes(importLine)) {
+            // marker + import present but not versioned — wrap the whole block
+            const normalised = existing.endsWith("\n") ? existing : `${existing}\n`;
+            // Replace the old "marker\n\nimportLine\n" pattern with versioned block
+            const oldBlock1 = `${marker}\n\n${importLine}\n`;
+            const oldBlock2 = `${marker}\n${importLine}\n`;
+            const newBlock = `${buildVersionedBlock(marker, importLine, version)}\n`;
+            const patched = normalised.includes(oldBlock1)
+                ? normalised.replace(oldBlock1, newBlock)
+                : normalised.includes(oldBlock2)
+                    ? normalised.replace(oldBlock2, newBlock)
+                    : null;
+            if (patched === null || patched === normalised) {
+                // Can't safely restructure — just mark as already-present
+                return "already-present";
+            }
+            writePatchedClaudeMd(targetPath, patched);
+            return "patched";
+        }
+        // marker present, import missing — replace the marker line with the full
+        // versioned block (marker included inside sentinels) so that BRIDGE_BLOCK_RE
+        // can match it on future passes. Preserves any content that follows.
+        const normalised = existing.endsWith("\n") ? existing : `${existing}\n`;
+        const markerIdx = normalised.indexOf(marker);
+        const markerLineEnd = normalised.indexOf("\n", markerIdx);
+        if (markerLineEnd === -1)
+            return "no-section";
+        const versionedBlock = buildVersionedBlock(marker, importLine, version);
+        const patched = normalised.slice(0, markerIdx) +
+            versionedBlock +
+            "\n" +
+            normalised.slice(markerLineEnd + 1);
+        writePatchedClaudeMd(targetPath, patched);
+        return "patched";
+    }
+    // Case 3: import line present with no marker section at all
+    if (existing.includes(importLine))
+        return "already-present";
+    return "no-section";
+}
+/** Atomically write patched CLAUDE.md content, backing up the original. */
+function writePatchedClaudeMd(targetPath, patched) {
+    // Use a unique tmp path to avoid EEXIST from a concurrent init run.
+    // Do NOT pre-unlink — let `wx` (exclusive create) handle collision on its own.
+    const tmpPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(tmpPath, patched, { encoding: "utf-8", flag: "wx" });
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            throw new Error(`Concurrent init detected: tmp file ${tmpPath} already exists. Retry once the other process finishes.`);
+        }
+        throw err;
+    }
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupPath = `${targetPath}.${ts}.bak`;
+    try {
+        renameSync(targetPath, backupPath);
+        try {
+            renameSync(tmpPath, targetPath);
+        }
+        catch (err) {
+            // step-2 failed — restore original from backup before re-throwing
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch {
+                /* best-effort tmp cleanup */
+            }
+            try {
+                renameSync(backupPath, targetPath);
+            }
+            catch (restoreErr) {
+                console.error(`[writePatchedClaudeMd] Failed to restore backup ${backupPath} → ${targetPath}:`, restoreErr);
+            }
+            throw err;
+        }
+    }
+    catch (err) {
+        // step-1 failed (backup rename) — just clean up tmp
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=claudeMdPatch.js.map

package/dist/claudeMdPatch.js.map

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

package/dist/claudeOrchestrator.d.ts

@@ -0,0 +1,171 @@
+import type { IClaudeDriver } from "./claudeDriver.js";
+export type TaskStatus = "pending" | "running" | "done" | "error" | "cancelled" | "interrupted";
+export type CancelReason = "timeout" | "startup_timeout" | "user" | "shutdown";
+export interface ClaudeTask {
+    id: string;
+    sessionId: string;
+    prompt: string;
+    contextFiles: string[];
+    status: TaskStatus;
+    createdAt: number;
+    startedAt?: number;
+    doneAt?: number;
+    /** Full output text, capped at 50KB. */
+    output?: string;
+    errorMessage?: string;
+    timeoutMs: number;
+    /** Estimated token count for the prompt (used for token-budget concurrency). */
+    tokenEstimate: number;
+    /** Optional model override passed to the driver (e.g. "claude-haiku-4-5-20251001"). */
+    model?: string;
+    /** Effort level for the task (low/medium/high/max). */
+    effort?: "low" | "medium" | "high" | "max";
+    /** Fallback model when the primary is overloaded. */
+    fallbackModel?: string;
+    /** Maximum spend cap in USD for this task. */
+    maxBudgetUsd?: number;
+    /** Abort the task if no assistant output arrives within this many ms of spawn. */
+    startupTimeoutMs?: number;
+    /** True when this task was spawned by an automation hook. */
+    isAutomationTask?: boolean;
+    /** Hook name that triggered this task (e.g. "onFileSave", "onDiagnosticsError"). */
+    triggerSource?: string;
+    /** Custom system prompt passed via --system-prompt to the subprocess. */
+    systemPrompt?: string;
+    /** If true, this task was dispatched to the ant binary instead of claude. */
+    useAnt?: boolean;
+    /** Set when status === "cancelled": what triggered the cancel. */
+    cancelReason?: CancelReason;
+    /** Last ~2KB of subprocess stderr — populated on timeout and other aborts. */
+    stderrTail?: string;
+    /** True when the subprocess was aborted (signal). */
+    wasAborted?: boolean;
+    /** Milliseconds from spawn to first assistant output. Undefined if no output arrived before timeout. */
+    startupMs?: number;
+}
+export type EnqueueOpts = {
+    prompt: string;
+    contextFiles?: string[];
+    timeoutMs?: number;
+    sessionId?: string;
+    onChunk?: (chunk: string) => void;
+    /** Optional model override, e.g. "claude-haiku-4-5-20251001". */
+    model?: string;
+    /** Effort level for the task (low/medium/high/max). */
+    effort?: "low" | "medium" | "high" | "max";
+    /** Fallback model when the primary is overloaded. */
+    fallbackModel?: string;
+    /** Maximum spend cap in USD for this task. */
+    maxBudgetUsd?: number;
+    /** Abort the task if no assistant output arrives within this many ms of spawn. */
+    startupTimeoutMs?: number;
+    /** Custom system prompt passed via --system-prompt to the subprocess. */
+    systemPrompt?: string;
+    /** Original creation timestamp — used when re-enqueuing persisted tasks. */
+    createdAt?: number;
+    /** True when this task was spawned by an automation hook (prevents infinite chain in onTaskSuccess). */
+    isAutomationTask?: boolean;
+    /** Hook name that created this task (e.g. "onFileSave", "onDiagnosticsError"). Logged at task start for observability. */
+    triggerSource?: string;
+    /** If true, spawn ant binary instead of claude. */
+    useAnt?: boolean;
+};
+export declare class ClaudeOrchestrator {
+    private readonly driver;
+    private readonly workspace;
+    private readonly log;
+    /** Called for each stdout chunk of every task (for VS Code output channel). */
+    private readonly notifyChunk?;
+    /** Called when a task reaches a terminal state. */
+    private readonly notifyDone?;
+    /** Optional checkpoint to save after each task completes or fails. */
+    private readonly checkpoint?;
+    static readonly MAX_CONCURRENT = 10;
+    static readonly MAX_QUEUE = 20;
+    static readonly MAX_HISTORY = 500;
+    static readonly DEFAULT_TIMEOUT_MS = 120000;
+    /** Maximum total estimated tokens in-flight across all running tasks. */
+    static readonly MAX_TOKEN_BUDGET = 500000;
+    private tasks;
+    /** Per-task streaming callback (set by callers of enqueue/runAndWait). */
+    private taskCallbacks;
+    /** Per-task completion callbacks (set by runAndWait). */
+    private completionCallbacks;
+    private queue;
+    private running;
+    private controllers;
+    /** Cancel-reason map populated by `cancel()` before aborting the controller. */
+    private cancelReasons;
+    /** Sum of tokenEstimate for all currently-running tasks. */
+    private _activeTokens;
+    /** Current total estimated tokens in-flight across all running tasks. */
+    get activeTokens(): number;
+    constructor(driver: IClaudeDriver, workspace: string, log: (msg: string) => void, 
+    /** Called for each stdout chunk of every task (for VS Code output channel). */
+    notifyChunk?: ((taskId: string, chunk: string) => void) | undefined, 
+    /** Called when a task reaches a terminal state. */
+    notifyDone?: ((taskId: string, status: TaskStatus) => void) | undefined, 
+    /** Optional checkpoint to save after each task completes or fails. */
+    checkpoint?: {
+        save(): void | Promise<void>;
+    } | undefined);
+    /**
+     * Enqueue a task and return its ID immediately.
+     * The task will start running as soon as a concurrent slot is available.
+     */
+    enqueue(opts: EnqueueOpts): string;
+    private _enqueueWithId;
+    /**
+     * Enqueue a task and wait until it reaches a terminal state (done/error/cancelled).
+     * The returned Promise always resolves (never rejects) — check task.status for the outcome.
+     * The task's own timeoutMs is the upper bound on how long this can take.
+     */
+    runAndWait(opts: EnqueueOpts): Promise<ClaudeTask>;
+    getTask(id: string): ClaudeTask | undefined;
+    /**
+     * Resolve a task ID, with support for UUID prefixes (≥8 chars).
+     * Returns `{task}` on unique exact/prefix match, `{ambiguous: true, candidates}` when
+     * multiple prefix matches exist (caller should surface as error), or `{}` for no match.
+     *
+     * Optional `visible(task)` predicate scopes both the match AND the candidate list
+     * to tasks the caller is allowed to see — prevents cross-session prefix enumeration.
+     * When omitted, all tasks are visible (internal callers only).
+     */
+    findTaskByPrefix(id: string, visible?: (task: ClaudeTask) => boolean): {
+        task?: ClaudeTask;
+        ambiguous?: boolean;
+        candidates?: string[];
+    };
+    list(status?: TaskStatus): ClaudeTask[];
+    /**
+     * Cancel a pending or running task.
+     * @param reason "user" (default) for explicit user cancellation, "shutdown"
+     * for bridge shutdown. Timeouts are detected internally in `_runTask` and
+     * do not flow through this method.
+     * Returns true if the task was found and cancellation was initiated.
+     */
+    cancel(id: string, reason?: Exclude<CancelReason, "timeout">): boolean;
+    private _drain;
+    private _runTask;
+    private _fireCompletion;
+    /** Build the serialisable task list for disk persistence.
+     * running tasks are saved as "interrupted" so on reload they appear as a
+     * known-terminal state rather than a stale "running" entry. */
+    private _buildTasksPayload;
+    /** Persist all tasks to disk for cross-session resumability. Best-effort. */
+    persistTasks(port: number): Promise<void>;
+    /** Synchronous flush called during shutdown — captures tasks at their true
+     * pre-cancellation state (pending = still pending, running = interrupted).
+     * Must be called BEFORE cancel() so the status snapshot is accurate. */
+    flushTasksToDisk(port: number): void;
+    /** Load persisted tasks from disk on startup. Best-effort.
+     *
+     * File format:
+     * - v0 (array at root): terminal tasks only — loaded as history, no re-enqueue
+     * - v1 ({version:1, tasks:[]}): pending tasks are re-enqueued; interrupted/terminal
+     *   tasks are restored as history; unknown future versions fall back to terminal-only
+     */
+    loadPersistedTasks(port: number): Promise<void>;
+    private _restoreTerminalTask;
+    private _pruneHistory;
+}