@backburner/cli 0.1.0

package/dist/src/onboarding/validators/tool-checker.js

@@ -0,0 +1,153 @@
+const REQUIRED_TOOLS = [
+    {
+        name: "Git",
+        command: "git",
+        versionArgs: ["--version"],
+        versionExtract: (out) => out.trim().replace("git version ", ""),
+        installHint: getInstallHint("git"),
+        required: true
+    },
+    {
+        name: "GitHub CLI",
+        command: "gh",
+        versionArgs: ["--version"],
+        versionExtract: (out) => out.trim().split("\n")[0] ?? out.trim(),
+        installHint: getInstallHint("gh"),
+        required: true
+    },
+    {
+        name: "Node.js",
+        command: "node",
+        versionArgs: ["--version"],
+        versionExtract: (out) => out.trim(),
+        versionCheck: (version) => {
+            const major = parseNodeMajor(version);
+            if (major === undefined) {
+                return `Could not parse Node.js version string: "${version}"`;
+            }
+            if (major < 20) {
+                return `Node.js >= 20 is required (found ${version}).`;
+            }
+            return undefined;
+        },
+        installHint: getInstallHint("node"),
+        required: true
+    }
+];
+export class ToolChecker {
+    commandRunner;
+    platformHelper;
+    constructor(commandRunner, platformHelper = getDefaultPlatform) {
+        this.commandRunner = commandRunner;
+        this.platformHelper = platformHelper;
+    }
+    async checkTool(tool) {
+        const installHint = getInstallHint(toInstallTarget(tool.command), this.platformHelper());
+        try {
+            const result = await this.commandRunner.run(tool.command, tool.versionArgs, {
+                timeoutMs: 5_000
+            });
+            const version = tool.versionExtract?.(result.stdout) ?? result.stdout.trim();
+            const versionError = tool.versionCheck?.(version);
+            if (versionError !== undefined) {
+                return {
+                    name: tool.name,
+                    command: tool.command,
+                    available: false,
+                    version,
+                    issue: {
+                        title: `${tool.name} version requirement not met`,
+                        cause: versionError,
+                        suggestedFix: installHint,
+                        canAutoRemediate: false,
+                        manualSteps: [installHint]
+                    }
+                };
+            }
+            return { name: tool.name, command: tool.command, available: true, version };
+        }
+        catch {
+            return {
+                name: tool.name,
+                command: tool.command,
+                available: false,
+                issue: {
+                    title: `${tool.name} not found`,
+                    cause: `The command "${tool.command}" is not available on PATH`,
+                    suggestedFix: installHint,
+                    canAutoRemediate: false,
+                    manualSteps: [installHint]
+                }
+            };
+        }
+    }
+    async checkAll() {
+        return Promise.all(REQUIRED_TOOLS.map((tool) => this.checkTool(tool)));
+    }
+    static getRequiredTools() {
+        return REQUIRED_TOOLS;
+    }
+}
+/** Parse the major version number from a Node.js version string like "v18.20.0". */
+export function parseNodeMajor(version) {
+    const match = version.replace(/^v/, "").match(/^(\d+)/);
+    if (!match?.[1])
+        return undefined;
+    const n = parseInt(match[1], 10);
+    return Number.isFinite(n) ? n : undefined;
+}
+export function getDefaultPlatform() {
+    return process.platform;
+}
+export function getInstallHint(tool, platform = getDefaultPlatform()) {
+    switch (tool) {
+        case "git":
+            return gitInstallHint(platform);
+        case "gh":
+            return ghInstallHint(platform);
+        case "node":
+            return nodeInstallHint(platform);
+    }
+}
+function gitInstallHint(platform) {
+    if (platform === "darwin") {
+        return "Install Git with Homebrew (`brew install git`) or download it from https://git-scm.com/downloads";
+    }
+    if (platform === "win32") {
+        return "Install Git with winget (`winget install Git.Git`) or download Git for Windows from https://git-scm.com/downloads/win";
+    }
+    if (platform === "linux") {
+        return "Install Git with your distro package manager, for example `sudo apt install git` or `sudo dnf install git`; downloads: https://git-scm.com/downloads";
+    }
+    return "Install Git: https://git-scm.com/downloads";
+}
+function ghInstallHint(platform) {
+    if (platform === "darwin") {
+        return "Install GitHub CLI with Homebrew (`brew install gh`) or follow https://cli.github.com";
+    }
+    if (platform === "win32") {
+        return "Install GitHub CLI with winget (`winget install GitHub.cli`) or use the official installer/docs at https://cli.github.com";
+    }
+    if (platform === "linux") {
+        return "Install GitHub CLI using the official Linux package instructions at https://cli.github.com";
+    }
+    return "Install GitHub CLI: https://cli.github.com";
+}
+function nodeInstallHint(platform) {
+    if (platform === "win32") {
+        return "Install Node.js >= 20 with winget (`winget install OpenJS.NodeJS.LTS`), fnm, or the official installer from https://nodejs.org";
+    }
+    if (platform === "darwin" || platform === "linux") {
+        return "Install Node.js >= 20 with nvm, fnm, or the official downloads from https://nodejs.org";
+    }
+    return "Install Node.js >= 20: https://nodejs.org";
+}
+function toInstallTarget(command) {
+    if (command === "git")
+        return "git";
+    if (command === "gh")
+        return "gh";
+    if (command === "node")
+        return "node";
+    throw new Error(`No install hint configured for required tool command: ${command}`);
+}

package/dist/src/onboarding/validators/workspace.js

@@ -0,0 +1,83 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getDefaultPlatform } from "./tool-checker.js";
+export class WorkspaceChecker {
+    platformHelper;
+    constructor(platformHelper = getDefaultPlatform) {
+        this.platformHelper = platformHelper;
+    }
+    async check(dirPath) {
+        let exists = false;
+        let writable = false;
+        try {
+            await fs.access(dirPath, fs.constants.F_OK);
+            exists = true;
+            try {
+                await fs.access(dirPath, fs.constants.W_OK);
+                writable = true;
+            }
+            catch {
+                // exists but not writable
+            }
+        }
+        catch {
+            // Does not exist. Check the nearest existing ancestor that mkdir -p would use.
+            const parent = await findExistingAncestor(path.dirname(dirPath));
+            try {
+                await fs.access(parent, fs.constants.W_OK);
+                writable = true;
+            }
+            catch {
+                // parent also not writable
+            }
+        }
+        if (!writable) {
+            return {
+                path: dirPath,
+                exists,
+                writable: false,
+                issue: {
+                    title: `Cannot write to directory: ${dirPath}`,
+                    cause: `The directory or its parent is not writable by the current user`,
+                    suggestedFix: "Choose a different directory or fix the permissions",
+                    canAutoRemediate: false,
+                    manualSteps: buildWorkspacePermissionManualSteps(dirPath, this.platformHelper())
+                }
+            };
+        }
+        return { path: dirPath, exists, writable: true };
+    }
+    async ensureDir(dirPath) {
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+}
+async function findExistingAncestor(startPath) {
+    let current = startPath;
+    while (true) {
+        try {
+            await fs.access(current, fs.constants.F_OK);
+            return current;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current) {
+                return current;
+            }
+            current = parent;
+        }
+    }
+}
+export function buildWorkspacePermissionManualSteps(dirPath, platform = getDefaultPlatform()) {
+    if (platform === "win32") {
+        const parentDir = path.win32.dirname(dirPath);
+        return [
+            `Open the directory properties for "${parentDir}" and confirm your user can write there`,
+            `Open the directory properties for "${dirPath}" and confirm your user can write there`,
+            "Or choose a different directory that your Windows user can write to"
+        ];
+    }
+    return [
+        `chmod u+w ${path.dirname(dirPath)}  # if parent not writable`,
+        `chmod u+w ${dirPath}               # if directory not writable`
+    ];
+}

package/dist/src/prompts/resolver.js

@@ -0,0 +1,106 @@
+import { readFile } from "node:fs/promises";
+import * as path from "node:path";
+import { resolveScopePath } from "../retrospectives/scopes.js";
+export function mapTaskKindToPromptKey(taskKind) {
+    switch (taskKind) {
+        case "product_discovery": return "product";
+        case "write_product_spec": return "product";
+        case "write_plan": return "plan";
+        case "implement_plan": return "implement";
+        case "review_pr": return "review";
+        case "respond_issue_comment": return "discuss";
+        case "plan_breakdown": return "breakdown";
+        case "wave_plan_assessment": return "waveAssessment";
+        case "wave_plan_replanning": return "waveReplanning";
+        case "extract_retrospective_problems": return "retrospectiveExtract";
+        case "investigate_learning_opportunity": return "retrospectiveInvestigate";
+        case "draft_management_learning_proposal": return "retrospectiveProposal";
+        default: return undefined;
+    }
+}
+export function mapTaskToPromptKey(task) {
+    if (task.kind === "respond_issue_comment" &&
+        (task.workflowPhase === "product_discovery" || task.workflowPhase === "product_specification")) {
+        return "product";
+    }
+    return mapTaskKindToPromptKey(task.kind);
+}
+export async function resolveTaskPromptContent(taskOrKind, promptsConfig, managementRoot, logger) {
+    const taskKind = typeof taskOrKind === "string" ? taskOrKind : taskOrKind.kind;
+    const key = typeof taskOrKind === "string"
+        ? mapTaskKindToPromptKey(taskOrKind)
+        : mapTaskToPromptKey(taskOrKind);
+    if (!key || !promptsConfig) {
+        logger?.info(`[prompt-resolver] Using built-in constraints for ${taskKind}`);
+        return { source: "built-in" };
+    }
+    const relativeFilePath = promptsConfig.promptProfiles.default[key];
+    if (!relativeFilePath) {
+        logger?.info(`[prompt-resolver] No config entry for "${key}" (${taskKind}); using built-in`);
+        return { source: "built-in" };
+    }
+    const absoluteFilePath = path.join(managementRoot, relativeFilePath);
+    try {
+        const content = await readFile(absoluteFilePath, "utf8");
+        logger?.info(`[prompt-resolver] Using config-file for "${key}" (${taskKind}): ${relativeFilePath}`);
+        return { source: "config-file", filePath: absoluteFilePath, content };
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            logger?.warn(`[prompt-resolver] Prompt file not found for "${key}" (${taskKind}): ${absoluteFilePath}; falling back to built-in`);
+            return { source: "built-in" };
+        }
+        throw err;
+    }
+}
+export async function loadLearningOverlays(ctx, managementRoot, logger) {
+    // Build scopes in broad-to-narrow order:
+    // global → provider → role → task_kind → repo → repo+provider → repo+role → repo+task_kind
+    const scopes = [];
+    scopes.push({ kind: "global" });
+    if (ctx.provider !== undefined) {
+        scopes.push({ kind: "provider", provider: ctx.provider });
+    }
+    if (ctx.role !== undefined) {
+        scopes.push({ kind: "role", role: ctx.role });
+    }
+    scopes.push({ kind: "task_kind", taskKind: ctx.taskKind });
+    if (ctx.repoId !== undefined) {
+        scopes.push({ kind: "repo", repoId: ctx.repoId });
+        if (ctx.provider !== undefined) {
+            scopes.push({ kind: "repo_provider", repoId: ctx.repoId, provider: ctx.provider });
+        }
+        if (ctx.role !== undefined) {
+            scopes.push({ kind: "repo_role", repoId: ctx.repoId, role: ctx.role });
+        }
+        scopes.push({ kind: "repo_task_kind", repoId: ctx.repoId, taskKind: ctx.taskKind });
+    }
+    const overlays = [];
+    for (const scope of scopes) {
+        let filePath;
+        try {
+            filePath = resolveScopePath(scope, managementRoot);
+        }
+        catch {
+            // Should never happen for internally-constructed scopes, but log and skip defensively
+            logger?.warn(`[learning-overlays] Failed to resolve path for scope ${JSON.stringify(scope)}`);
+            continue;
+        }
+        try {
+            const content = await readFile(filePath, "utf8");
+            if (content.trim().length > 0) {
+                overlays.push(content.trimEnd());
+                logger?.info(`[learning-overlays] Loaded overlay: ${filePath}`);
+            }
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                // Missing file is expected for most scopes; silently skip
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    return overlays;
+}

package/dist/src/retrospectives/candidates.js

@@ -0,0 +1,224 @@
+import { classifyManagementPullRequest } from "../github/pr-classification.js";
+import { workflowRegistry } from "../workflows/registry.js";
+export function registerRetrospectiveCandidates(input) {
+    const { previousCandidates, workstreams, issues, pullRequests, tasks, executions, managementPrs, classifyPullRequest = classifyManagementPullRequest, managementRepo, now, } = input;
+    const candidatesMap = new Map();
+    for (const prev of previousCandidates) {
+        candidatesMap.set(prev.id, prev);
+    }
+    const registered = [];
+    const skipped = [];
+    for (const workstream of workstreams) {
+        // 1. Consider only terminal workstreams
+        const isPhaseTerminal = workstream.phase === "resolved" || workstream.phase === "abandoned";
+        const isStatusMergedOrClosed = (workstream.status === "closed" && workstream.resolution === "closed") ||
+            (workstream.status === "merged" && workstream.resolution === "merged");
+        if (!isPhaseTerminal && !isStatusMergedOrClosed) {
+            // 2. Do not register open/unresolved workstreams
+            continue;
+        }
+        if (workstream.resolution !== "closed" && workstream.resolution !== "merged") {
+            continue; // Extra safety check based on plan text
+        }
+        // Identify candidate PRs to classify
+        const prsToClassify = [];
+        if (workstream.origin.type === "pr") {
+            const pr = pullRequests.find((p) => p.number === workstream.origin.number && p.repoSlug === workstream.repoKey);
+            if (pr) {
+                prsToClassify.push({
+                    number: pr.number,
+                    headBranch: pr.headBranch,
+                    baseBranch: pr.baseBranch,
+                });
+            }
+            else {
+                prsToClassify.push({ number: workstream.origin.number });
+            }
+        }
+        else {
+            for (const linkedPr of workstream.linkedPrs) {
+                const pr = pullRequests.find((p) => p.number === linkedPr.number && p.repoSlug === workstream.repoKey);
+                if (pr) {
+                    prsToClassify.push({
+                        number: pr.number,
+                        headBranch: pr.headBranch,
+                        baseBranch: pr.baseBranch,
+                    });
+                }
+                else {
+                    prsToClassify.push({ number: linkedPr.number });
+                }
+            }
+            if (workstream.activePrNumber) {
+                const alreadyIncluded = prsToClassify.some(p => p.number === workstream.activePrNumber);
+                if (!alreadyIncluded) {
+                    const pr = pullRequests.find((p) => p.number === workstream.activePrNumber && p.repoSlug === workstream.repoKey);
+                    if (pr) {
+                        prsToClassify.push({
+                            number: pr.number,
+                            headBranch: pr.headBranch,
+                            baseBranch: pr.baseBranch,
+                        });
+                    }
+                    else {
+                        prsToClassify.push({ number: workstream.activePrNumber });
+                    }
+                }
+            }
+        }
+        // 3. Skip management PR workstreams using early classifier
+        let skipReason = "";
+        for (const prData of prsToClassify) {
+            const classificationInput = {
+                repoId: workstream.repoKey,
+                repoSlug: workstream.repoKey,
+                pullRequestNumber: prData.number,
+                managementPrs,
+            };
+            if (prData.headBranch !== undefined)
+                classificationInput.headBranch = prData.headBranch;
+            if (prData.baseBranch !== undefined)
+                classificationInput.baseBranch = prData.baseBranch;
+            if (managementRepo !== undefined)
+                classificationInput.managementRepo = managementRepo;
+            const classification = classifyPullRequest(classificationInput);
+            if (classification.kind === "management") {
+                skipReason = `Origin or linked PR #${prData.number} classified as management: ${classification.reason}`;
+                break;
+            }
+        }
+        if (skipReason) {
+            skipped.push({ workstreamId: workstream.id, reason: skipReason });
+            continue;
+        }
+        const repoSlug = workstream.repoKey;
+        const originType = workstream.origin.type;
+        const originNumber = workstream.origin.number;
+        const resolution = workstream.resolution;
+        // Stable candidate key
+        const id = `retrospective-candidate:${repoSlug}:${workstream.id}:${originType}-${originNumber}:${resolution}`;
+        // 5. Preserve existing candidate records
+        if (candidatesMap.has(id)) {
+            continue;
+        }
+        const workstreamTasks = tasks.filter((t) => t.workstreamId === workstream.id);
+        const taskIds = workstreamTasks.map((t) => t.id);
+        const workstreamExecutions = executions.filter((e) => taskIds.includes(e.taskId));
+        const taskSummary = {
+            total: workstreamTasks.length,
+            completed: workstreamTasks.filter((t) => t.status === "completed").length,
+            failed: workstreamTasks.filter((t) => t.status === "failed").length,
+            kinds: Array.from(new Set(workstreamTasks.map((t) => t.kind))),
+            taskIds,
+        };
+        const lastExecutionId = workstreamExecutions.length > 0
+            ? workstreamExecutions.sort((a, b) => b.startedAt.localeCompare(a.startedAt))[0]?.id
+            : undefined;
+        if (lastExecutionId !== undefined) {
+            taskSummary.lastExecutionId = lastExecutionId;
+        }
+        const executionRoles = new Set();
+        for (const execution of workstreamExecutions) {
+            const task = workstreamTasks.find((t) => t.id === execution.taskId);
+            if (task) {
+                try {
+                    const definition = workflowRegistry.getDefinition(task.kind);
+                    executionRoles.add(definition.role);
+                }
+                catch (e) {
+                    // Ignore unregistered task kinds for role derivation
+                }
+            }
+        }
+        const executionSummary = {
+            total: workstreamExecutions.length,
+            providers: Array.from(new Set(workstreamExecutions.map((e) => e.agentProvider).filter(p => p !== "unassigned"))),
+            models: Array.from(new Set(workstreamExecutions.map((e) => e.agentModel).filter(Boolean))),
+            roles: Array.from(executionRoles),
+            executionIds: workstreamExecutions.map((e) => e.id),
+        };
+        let title = "";
+        let url = "";
+        const labels = [];
+        let repoIdForCandidate = repoSlug;
+        if (originType === "issue") {
+            const issue = issues.find(i => i.number === originNumber && i.repoSlug === repoSlug);
+            if (issue) {
+                title = issue.title;
+                url = issue.url;
+                labels.push(...issue.labels);
+                repoIdForCandidate = issue.repoId;
+            }
+        }
+        else {
+            const pr = pullRequests.find(p => p.number === originNumber && p.repoSlug === repoSlug);
+            if (pr) {
+                title = pr.title;
+                url = pr.url;
+                labels.push(...pr.labels);
+                repoIdForCandidate = pr.repoId;
+            }
+        }
+        const artifactReferences = [];
+        workstreamExecutions.forEach((e) => {
+            artifactReferences.push(e.promptArtifactPath);
+            artifactReferences.push(e.stdoutArtifactPath);
+            artifactReferences.push(e.stderrArtifactPath);
+            artifactReferences.push(e.promptPacketPath);
+            if (e.streamArtifactPath)
+                artifactReferences.push(e.streamArtifactPath);
+            if (e.settingsArtifactPath)
+                artifactReferences.push(e.settingsArtifactPath);
+        });
+        const evidenceReferences = [];
+        evidenceReferences.push({
+            kind: "workstream",
+            id: workstream.id,
+        });
+        evidenceReferences.push({
+            kind: originType === "issue" ? "issue" : "pull_request",
+            id: `${repoSlug}#${originNumber}`,
+            url,
+        });
+        const candidate = {
+            id,
+            sourceWorkstreamId: workstream.id,
+            repoId: repoIdForCandidate,
+            repoSlug,
+            repoKey: workstream.repoKey,
+            origin: {
+                type: originType,
+                number: originNumber,
+            },
+            terminalResolution: resolution,
+            detectedAt: now,
+            resolvedAt: now, // Since we only pick terminal workstreams
+            status: "new",
+            title,
+            url,
+            labels,
+            sourceSummary: `Terminal operational workstream ${workstream.id}`,
+            taskSummary,
+            executionSummary,
+            artifactReferences,
+            evidenceReferences,
+        };
+        candidatesMap.set(id, candidate);
+        registered.push(candidate);
+    }
+    // 6. Sort the returned candidates deterministically
+    const candidates = Array.from(candidatesMap.values()).sort((a, b) => {
+        const repoComparison = a.repoSlug.localeCompare(b.repoSlug);
+        if (repoComparison !== 0)
+            return repoComparison;
+        const workstreamComparison = a.sourceWorkstreamId.localeCompare(b.sourceWorkstreamId);
+        if (workstreamComparison !== 0)
+            return workstreamComparison;
+        return a.id.localeCompare(b.id);
+    });
+    return {
+        candidates,
+        registered,
+        skipped,
+    };
+}