@backburner/cli 0.1.0

package/dist/src/tasks/mcp-skip.js

@@ -0,0 +1,10 @@
+// Matches: "mcp-skip: <taskId> <mcpHandle>"
+// Case-insensitive prefix; tolerant of leading/trailing whitespace.
+export const MCP_SKIP_PATTERN = /^\s*mcp-skip:\s+(\S+)\s+(\S+)\s*$/i;
+export function extractMcpSkipCommand(body) {
+    const match = MCP_SKIP_PATTERN.exec(body);
+    if (!match) {
+        return undefined;
+    }
+    return { taskId: match[1], mcpHandle: match[2] };
+}

package/dist/src/tasks/retry.js

@@ -0,0 +1,10 @@
+// Matches exactly: "retry: <github issuecomment URL>"
+// Captures the numeric comment ID from the URL fragment.
+export const RETRY_LINK_PATTERN = /^\s*retry:\s+https:\/\/github\.com\/[^/\s]+\/[^/\s]+\/(?:issues|pull)\/\d+#issuecomment-(\d+)\s*$/i;
+export function extractRetryCommentId(body) {
+    const match = RETRY_LINK_PATTERN.exec(body);
+    return match ? match[1] : undefined;
+}
+export function isRetryLinkCommand(body) {
+    return RETRY_LINK_PATTERN.test(body);
+}

package/dist/src/tasks/task.js

@@ -0,0 +1,184 @@
+export class Task {
+    record;
+    constructor(record) {
+        this.record = record;
+    }
+    static from(record) {
+        return new Task(record);
+    }
+    get id() {
+        return this.record.id;
+    }
+    get waitingOnProvider() {
+        return this.record.waitingOnProvider;
+    }
+    get kind() {
+        return this.record.kind;
+    }
+    get sourceKind() {
+        return this.record.sourceKind;
+    }
+    get sourceId() {
+        return this.record.sourceId;
+    }
+    get parentSourceKind() {
+        return this.record.parentSourceKind;
+    }
+    get parentSourceId() {
+        return this.record.parentSourceId;
+    }
+    getOwningThreadKind() {
+        if (this.record.parentSourceKind) {
+            return this.record.parentSourceKind;
+        }
+        if (this.record.sourceKind === "issue" || this.record.sourceKind === "pull_request") {
+            return this.record.sourceKind;
+        }
+        return undefined;
+    }
+    getOwningThreadId() {
+        return this.record.parentSourceId ?? (this.record.sourceKind === "comment" ? undefined : this.record.sourceId);
+    }
+    owningPullRequestNumber() {
+        const pullRequestId = this.getOwningThreadKind() === "pull_request" ? this.getOwningThreadId() : undefined;
+        if (!pullRequestId) {
+            return undefined;
+        }
+        const match = pullRequestId.match(/:(\d+)$/);
+        return match ? Number(match[1]) : undefined;
+    }
+    owningThreadNumber() {
+        const owningThreadId = this.getOwningThreadId() ?? this.record.sourceId;
+        const match = owningThreadId.match(/:(\d+)$/);
+        return match ? Number(match[1]) : undefined;
+    }
+    resolveSourceIssue(lookups) {
+        switch (this.record.sourceKind) {
+            case "issue":
+                return lookups.issuesById?.get(this.record.sourceId);
+            case "pull_request":
+                return undefined;
+            case "comment":
+                return this.resolveCommentParentIssue(lookups, this.record.sourceId);
+        }
+    }
+    resolveOwningIssue(lookups) {
+        const owningThreadId = this.getOwningThreadId();
+        if (this.getOwningThreadKind() === "issue" && owningThreadId) {
+            return lookups.issuesById?.get(owningThreadId);
+        }
+        if (this.record.sourceKind === "issue") {
+            return lookups.issuesById?.get(this.record.sourceId);
+        }
+        if (this.record.sourceKind === "comment") {
+            return this.resolveCommentParentIssue(lookups, this.record.sourceId);
+        }
+        return undefined;
+    }
+    resolveSourcePullRequest(lookups) {
+        switch (this.record.sourceKind) {
+            case "issue":
+                return undefined;
+            case "pull_request":
+                return lookups.pullRequestsById?.get(this.record.sourceId);
+            case "comment":
+                return this.resolveCommentParentPullRequest(lookups, this.record.sourceId);
+        }
+    }
+    resolveOwningPullRequest(lookups) {
+        const owningThreadId = this.getOwningThreadId();
+        if (this.getOwningThreadKind() === "pull_request" && owningThreadId) {
+            return lookups.pullRequestsById?.get(owningThreadId);
+        }
+        if (this.record.sourceKind === "pull_request") {
+            return lookups.pullRequestsById?.get(this.record.sourceId);
+        }
+        if (this.record.sourceKind === "comment") {
+            return this.resolveCommentParentPullRequest(lookups, this.record.sourceId);
+        }
+        return undefined;
+    }
+    resolveSourceComment(lookups) {
+        if (this.record.sourceKind !== "comment") {
+            return undefined;
+        }
+        return lookups.commentsById?.get(this.record.sourceId);
+    }
+    resolveOwningComment(lookups) {
+        if (this.record.sourceKind !== "comment") {
+            return undefined;
+        }
+        return lookups.commentsById?.get(this.record.sourceId);
+    }
+    isSourceIssue(issue) {
+        return this.record.sourceKind === "issue" && this.record.sourceId === issue.id;
+    }
+    isOwningIssue(issue) {
+        return this.getOwningThreadKind() === "issue" && this.getOwningThreadId() === issue.id;
+    }
+    isSourcePullRequest(pullRequest) {
+        return this.record.sourceKind === "pull_request" && this.record.sourceId === pullRequest.id;
+    }
+    isOwningPullRequest(pullRequest) {
+        return this.getOwningThreadKind() === "pull_request" && this.getOwningThreadId() === pullRequest.id;
+    }
+    isSourceComment(comment) {
+        return this.record.sourceKind === "comment" && this.record.sourceId === comment.id;
+    }
+    isOwningComment(comment) {
+        return this.record.sourceKind === "comment" && this.record.sourceId === comment.id;
+    }
+    isRelatedToIssue(issue) {
+        return this.isSourceIssue(issue) || this.isOwningIssue(issue);
+    }
+    isRelatedToPullRequest(pullRequest) {
+        return this.isSourcePullRequest(pullRequest) || this.isOwningPullRequest(pullRequest);
+    }
+    isCommentOriginated() {
+        return this.record.sourceKind === "comment";
+    }
+    getSourceCommentId() {
+        if (this.record.sourceKind !== "comment") {
+            return undefined;
+        }
+        if (this.record.sourceReactionTargetId) {
+            return this.record.sourceReactionTargetId;
+        }
+        const match = this.record.sourceId.match(/:(\d+)$/);
+        if (match) {
+            return match[1];
+        }
+        return /^\d+$/.test(this.record.sourceId) ? this.record.sourceId : undefined;
+    }
+    getSourceCommentKind() {
+        if (this.record.sourceKind !== "comment") {
+            return undefined;
+        }
+        const match = this.record.sourceId.match(/^comment:[^:]+\/[^:]+:(issue_comment|pull_request_comment|pull_request_review|pull_request_review_comment):/);
+        return match?.[1];
+    }
+    getSourceEntityNumber() {
+        // If it's an issue or PR, its ID ends with :number
+        if (this.record.sourceKind === "issue" || this.record.sourceKind === "pull_request") {
+            const match = this.record.sourceId.match(/:(\d+)$/);
+            return match ? Number(match[1]) : undefined;
+        }
+        // For comments, we usually want the parent's number for reactions/feedback if no commentId is used
+        // but the lifecycle notifier will use the precise source.
+        return undefined;
+    }
+    resolveCommentParentIssue(lookups, commentId) {
+        const comment = lookups.commentsById?.get(commentId);
+        if (!comment || comment.parentType !== "issue") {
+            return undefined;
+        }
+        return lookups.issuesByKey?.get(comment.parentKey);
+    }
+    resolveCommentParentPullRequest(lookups, commentId) {
+        const comment = lookups.commentsById?.get(commentId);
+        if (!comment || comment.parentType !== "pull_request") {
+            return undefined;
+        }
+        return lookups.pullRequestsByKey?.get(comment.parentKey);
+    }
+}

package/dist/src/tasks/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/command-runner.js

@@ -0,0 +1,192 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const crossSpawn = require("cross-spawn");
+export class CommandExecutionError extends Error {
+    command;
+    args;
+    exitCode;
+    stdout;
+    stderr;
+    constructor(message, command, args, exitCode, stdout, stderr) {
+        super(message);
+        this.command = command;
+        this.args = args;
+        this.exitCode = exitCode;
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+}
+const COMMAND_TIMEOUT_EXIT_CODE = 124;
+const PROCESS_GROUP_TERMINATION_GRACE_MS = 250;
+const TIMEOUT_SETTLE_FALLBACK_MS = 1000;
+export class ExecFileCommandRunner {
+    spawnProcess;
+    killProcess;
+    platform;
+    constructor(dependencies = {}) {
+        this.spawnProcess = dependencies.spawnProcess ?? crossSpawn;
+        this.killProcess = dependencies.killProcess ?? process.kill.bind(process);
+        this.platform = dependencies.platform ?? process.platform;
+    }
+    run(command, args, options = {}) {
+        return new Promise((resolve, reject) => {
+            const child = this.spawnProcess(command, args, {
+                cwd: options.cwd,
+                env: options.env === undefined ? process.env : { ...process.env, ...options.env },
+                detached: this.platform !== "win32",
+                stdio: ["pipe", "pipe", "pipe"],
+                windowsHide: this.platform === "win32"
+            });
+            let stdout = "";
+            let stderr = "";
+            let settled = false;
+            let timedOut = false;
+            let timeoutHandle;
+            let killGraceHandle;
+            let timeoutFallbackHandle;
+            const settleResolve = (result) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimers();
+                resolve(result);
+            };
+            const settleReject = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimers();
+                reject(error);
+            };
+            const clearTimers = () => {
+                if (timeoutHandle !== undefined) {
+                    clearTimeout(timeoutHandle);
+                    timeoutHandle = undefined;
+                }
+                if (killGraceHandle !== undefined) {
+                    clearTimeout(killGraceHandle);
+                    killGraceHandle = undefined;
+                }
+                if (timeoutFallbackHandle !== undefined) {
+                    clearTimeout(timeoutFallbackHandle);
+                    timeoutFallbackHandle = undefined;
+                }
+            };
+            child.stdout?.setEncoding("utf8");
+            child.stderr?.setEncoding("utf8");
+            child.stdout?.on("data", (chunk) => {
+                stdout += chunk;
+                if (!settled) {
+                    options.onOutputChunk?.("stdout", chunk);
+                }
+            });
+            child.stderr?.on("data", (chunk) => {
+                stderr += chunk;
+                if (!settled) {
+                    options.onOutputChunk?.("stderr", chunk);
+                }
+            });
+            child.once("error", (error) => {
+                settleReject(new CommandExecutionError(formatCommandError(command, args, error.message, stderr), command, args, 1, stdout, stderr));
+            });
+            child.once("close", (code, signal) => {
+                if (timedOut) {
+                    settleReject(new CommandExecutionError(formatTimeoutError(command, args, options.timeoutMs ?? 0, stderr), command, args, COMMAND_TIMEOUT_EXIT_CODE, stdout, stderr));
+                    return;
+                }
+                const exitCode = extractExitCodeFromClose(code, signal);
+                if (exitCode === 0) {
+                    settleResolve({
+                        stdout,
+                        stderr,
+                        exitCode: 0
+                    });
+                    return;
+                }
+                settleReject(new CommandExecutionError(formatCommandError(command, args, `command exited with code ${exitCode}`, stderr), command, args, exitCode, stdout, stderr));
+            });
+            if (options.input !== undefined) {
+                child.stdin?.end(options.input);
+            }
+            if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+                timeoutHandle = setTimeout(() => {
+                    if (settled || child.pid === undefined) {
+                        return;
+                    }
+                    timedOut = true;
+                    terminateProcessTree(child, "SIGTERM", {
+                        spawnProcess: this.spawnProcess,
+                        killProcess: this.killProcess,
+                        platform: this.platform
+                    });
+                    killGraceHandle = setTimeout(() => {
+                        if (settled || child.pid === undefined) {
+                            return;
+                        }
+                        terminateProcessTree(child, "SIGKILL", {
+                            spawnProcess: this.spawnProcess,
+                            killProcess: this.killProcess,
+                            platform: this.platform
+                        });
+                    }, PROCESS_GROUP_TERMINATION_GRACE_MS);
+                    timeoutFallbackHandle = setTimeout(() => {
+                        if (settled) {
+                            return;
+                        }
+                        settleReject(new CommandExecutionError(formatTimeoutError(command, args, options.timeoutMs ?? 0, stderr), command, args, COMMAND_TIMEOUT_EXIT_CODE, stdout, stderr));
+                    }, TIMEOUT_SETTLE_FALLBACK_MS);
+                }, options.timeoutMs);
+            }
+        });
+    }
+}
+function extractExitCodeFromClose(code, signal) {
+    if (typeof code === "number") {
+        return code;
+    }
+    if (signal !== null) {
+        return 1;
+    }
+    return 1;
+}
+export function terminateProcessTree(child, signal, dependencies = {}) {
+    if (child.pid === undefined) {
+        return;
+    }
+    const platform = dependencies.platform ?? process.platform;
+    const spawnProcess = dependencies.spawnProcess ?? crossSpawn;
+    const killProcess = dependencies.killProcess ?? process.kill.bind(process);
+    if (platform === "win32") {
+        const taskkill = spawnProcess("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+            stdio: "ignore",
+            windowsHide: true
+        });
+        taskkill.once("error", () => undefined);
+        taskkill.unref();
+        return;
+    }
+    try {
+        killProcess(-child.pid, signal);
+    }
+    catch {
+        try {
+            killProcess(child.pid, signal);
+        }
+        catch {
+            // Ignore termination failures. The fallback timeout will surface the timeout error.
+        }
+    }
+}
+function formatCommandError(command, args, message, stderr) {
+    const renderedCommand = [command, ...args].join(" ");
+    const suffix = stderr.trim() === "" ? message : stderr.trim();
+    return `${renderedCommand}: ${suffix}`;
+}
+function formatTimeoutError(command, args, timeoutMs, stderr) {
+    const renderedCommand = [command, ...args].join(" ");
+    const timeoutMessage = `timed out after ${timeoutMs}ms`;
+    const suffix = stderr.trim() === "" ? timeoutMessage : `${timeoutMessage}: ${stderr.trim()}`;
+    return `${renderedCommand}: ${suffix}`;
+}

package/dist/src/utils/json.js

@@ -0,0 +1,38 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+export async function readJsonFile(filePath) {
+    try {
+        const raw = await readFile(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error(`${filePath}: invalid JSON (${error.message})`);
+        }
+        if (error.code === "ENOENT") {
+            throw new Error(`${filePath}: file not found`);
+        }
+        throw error;
+    }
+}
+export async function readJsonFileIfExists(filePath) {
+    try {
+        return await readJsonFile(filePath);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === `${filePath}: file not found`) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export async function writeJsonFileAtomic(filePath, value) {
+    const directory = path.dirname(filePath);
+    await mkdir(directory, { recursive: true });
+    const temporaryFile = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    await writeFile(temporaryFile, toPrettyJson(value), "utf8");
+    await rename(temporaryFile, filePath);
+}
+export function toPrettyJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}

package/dist/src/utils/logger.js

@@ -0,0 +1,43 @@
+import { createWriteStream } from "node:fs";
+import { mkdirSync } from "node:fs";
+import * as path from "node:path";
+export const defaultStderrLogger = {
+    info: (message) => process.stderr.write(`${message}\n`),
+    warn: (message) => process.stderr.write(`${message}\n`),
+    error: (message) => process.stderr.write(`${message}\n`)
+};
+export function createTeeFileLogger(baseLogger, filePath) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    const stream = createWriteStream(filePath, {
+        flags: "a",
+        encoding: "utf8"
+    });
+    const writeLine = (message) => {
+        stream.write(`${message}\n`);
+    };
+    return {
+        info(message) {
+            baseLogger.info(message);
+            writeLine(message);
+        },
+        warn(message) {
+            baseLogger.warn(message);
+            writeLine(message);
+        },
+        error(message) {
+            baseLogger.error?.(message);
+            writeLine(message);
+        },
+        async close() {
+            await new Promise((resolve, reject) => {
+                stream.end((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        }
+    };
+}

package/dist/src/utils/paths.js

@@ -0,0 +1,38 @@
+import * as path from "node:path";
+import * as os from "node:os";
+import { fileURLToPath } from "node:url";
+const currentFile = fileURLToPath(import.meta.url);
+const currentDirectory = path.dirname(currentFile);
+export const projectRoot = path.resolve(currentDirectory, "../../..");
+export const managementRoot = path.join(projectRoot, "management");
+export const outputsRoot = path.join(projectRoot, "outputs");
+export const outputsStateRoot = path.join(outputsRoot, "state");
+export const outputsLogsRoot = path.join(outputsRoot, "logs");
+export function resolveOutputsStateRoot(outputsDir) {
+    return path.join(outputsDir, "state");
+}
+export function resolveOutputsLogsRoot(outputsDir) {
+    return path.join(outputsDir, "logs");
+}
+export const outputsJournalRoot = path.join(outputsRoot, "journal");
+export function resolveOutputsJournalRoot(outputsDir) {
+    return path.join(outputsDir, "journal");
+}
+export function defaultBackburnerRoot() {
+    if (process.env.BACKBURNER_ROOT !== undefined && process.env.BACKBURNER_ROOT.trim() !== "") {
+        return process.env.BACKBURNER_ROOT;
+    }
+    return path.join(os.homedir(), ".backburner");
+}
+export function defaultBackburnerCodeRoot() {
+    return path.join(defaultBackburnerRoot(), "code");
+}
+export function defaultBackburnerManagementRoot() {
+    return path.join(defaultBackburnerRoot(), "management");
+}
+export function defaultBackburnerOutputsRoot() {
+    return path.join(defaultBackburnerRoot(), "outputs");
+}
+export function defaultWorkspacesRootForCodeRoot(codeRoot) {
+    return path.join(codeRoot, "_worktrees");
+}

package/dist/src/utils/slug.js

@@ -0,0 +1,10 @@
+/**
+ * Converts a string into a URL-safe, filesystem-safe, and git-ref-safe slug.
+ */
+export function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+}