@backburner/cli 0.1.0

package/dist/src/onboarding/steps/discover-repos.js

@@ -0,0 +1,39 @@
+import { RepoDiscoveryService } from "../services/repo-discovery.js";
+export class DiscoverReposStep {
+    commandRunner;
+    codeRoot;
+    name = "discover-repos";
+    description = "Discovering repositories";
+    constructor(commandRunner, codeRoot) {
+        this.commandRunner = commandRunner;
+        this.codeRoot = codeRoot;
+    }
+    async run(ctx, _prompter) {
+        const service = new RepoDiscoveryService(this.commandRunner);
+        const [githubRepos, localRepos] = await Promise.all([
+            service.discoverGitHubRepos(),
+            service.discoverLocalRepos([this.codeRoot])
+        ]);
+        ctx.discoveredRepos = service.mergeRepos(githubRepos, localRepos);
+        const localCount = ctx.discoveredRepos.filter((r) => r.isLocalClone).length;
+        const remoteOnlyCount = ctx.discoveredRepos.length - localCount;
+        if (ctx.discoveredRepos.length === 0) {
+            return {
+                status: "warning",
+                message: "No repositories discovered",
+                details: [
+                    "No GitHub repos found and no git repos found under the code root.",
+                    "You can enter a repository manually in the next step."
+                ]
+            };
+        }
+        return {
+            status: "passed",
+            message: `Found ${ctx.discoveredRepos.length} repositories`,
+            details: [
+                `${localCount} with a local clone`,
+                `${remoteOnlyCount} on GitHub without a local clone`
+            ]
+        };
+    }
+}

package/dist/src/onboarding/steps/generate-config.js

@@ -0,0 +1,106 @@
+import * as path from "node:path";
+import { ConfigWriter } from "../config-writer.js";
+export class GenerateConfigStep {
+    name = "generate-config";
+    description = "Generating configuration";
+    async run(ctx, prompter) {
+        const writer = new ConfigWriter();
+        const existing = await writer.detectExisting(ctx.managementDir);
+        if (existing.reposExists || existing.agentsExists) {
+            const existingFiles = [];
+            if (existing.reposExists)
+                existingFiles.push(existing.reposFile);
+            if (existing.agentsExists)
+                existingFiles.push(existing.agentsFile);
+            process.stdout.write("\nExisting configuration found:\n");
+            for (const f of existingFiles) {
+                process.stdout.write(`  ${f}\n`);
+            }
+            const overwrite = await prompter.confirm("Overwrite existing configuration?", false);
+            if (!overwrite) {
+                ctx.warnings.push("Configuration was not overwritten. Edit the files manually if needed.");
+                return {
+                    status: "skipped",
+                    message: "Existing configuration preserved",
+                    details: existingFiles.map((f) => `Kept: ${f}`)
+                };
+            }
+        }
+        const draft = buildConfigDraft(ctx);
+        ctx.configDraft = draft;
+        try {
+            const result = await writer.write(draft, {
+                overwriteRepos: true,
+                overwriteAgents: true
+            });
+            const details = [];
+            if (!result.skippedExisting.includes(result.reposFile)) {
+                details.push(`Written: ${result.reposFile}`);
+            }
+            if (!result.skippedExisting.includes(result.agentsFile)) {
+                details.push(`Written: ${result.agentsFile}`);
+            }
+            for (const f of result.skippedExisting) {
+                details.push(`Skipped (already exists): ${f}`);
+            }
+            return {
+                status: "passed",
+                message: "Configuration written",
+                details
+            };
+        }
+        catch (err) {
+            return {
+                status: "failed",
+                message: `Failed to write configuration: ${err instanceof Error ? err.message : String(err)}`,
+                issues: [
+                    {
+                        title: "Configuration write failed",
+                        cause: err instanceof Error ? err.message : String(err),
+                        suggestedFix: `Check that ${ctx.managementDir} is writable`,
+                        canAutoRemediate: false,
+                        manualSteps: [
+                            `Create the management directory if it does not exist: "${ctx.managementDir}"`,
+                            `Confirm your user can write to the management directory: "${ctx.managementDir}"`
+                        ]
+                    }
+                ]
+            };
+        }
+    }
+}
+function buildConfigDraft(ctx) {
+    const repos = ctx.selectedRepos.map((repo) => buildRepoDraft(repo, ctx.codeRoot));
+    const existing = ctx.configDraft;
+    return {
+        codeRoot: ctx.codeRoot,
+        managementDir: ctx.managementDir,
+        outputsDir: ctx.outputsDir,
+        logDir: ctx.logDir,
+        workspacesDir: ctx.workspacesDir,
+        allowedUsers: existing?.allowedUsers ??
+            (ctx.githubUser !== undefined ? [ctx.githubUser] : []),
+        repos,
+        agents: existing?.agents ?? []
+    };
+}
+function buildRepoDraft(repo, codeRoot) {
+    let localPath;
+    if (repo.localPath !== undefined) {
+        localPath = path.relative(codeRoot, repo.localPath);
+        // Fall back to owner/name if the path escapes the code root
+        if (localPath.startsWith("..")) {
+            localPath = `${repo.owner}/${repo.name}`;
+        }
+    }
+    else {
+        localPath = `${repo.owner}/${repo.name}`;
+    }
+    return {
+        owner: repo.owner,
+        name: repo.name,
+        localPath,
+        defaultBranch: repo.defaultBranch || "main",
+        enabled: true
+    };
+}

package/dist/src/onboarding/steps/readiness-validation.js

@@ -0,0 +1,158 @@
+import { ToolChecker } from "../validators/tool-checker.js";
+import { GitHubAuthChecker } from "../validators/github-auth.js";
+import { GitAccessChecker } from "../validators/git-access.js";
+import { WorkspaceChecker } from "../validators/workspace.js";
+export class ReadinessValidationStep {
+    commandRunner;
+    platformHelper;
+    name = "readiness-validation";
+    description = "Running final readiness check";
+    constructor(commandRunner, platformHelper) {
+        this.commandRunner = commandRunner;
+        this.platformHelper = platformHelper;
+    }
+    async run(ctx, _prompter) {
+        const issues = [];
+        const details = [];
+        // 1. Tool check
+        const toolChecker = new ToolChecker(this.commandRunner, this.platformHelper);
+        const toolResults = await toolChecker.checkAll();
+        for (const r of toolResults) {
+            if (r.available) {
+                details.push(`✓ ${r.name}: ${r.version ?? "found"}`);
+            }
+            else {
+                details.push(`✗ ${r.name}: not found`);
+                if (r.issue !== undefined)
+                    issues.push(r.issue);
+            }
+        }
+        // 2. GitHub auth check
+        const authChecker = new GitHubAuthChecker(this.commandRunner);
+        const authResult = await authChecker.check();
+        if (authResult.authenticated) {
+            details.push(`✓ GitHub: authenticated as ${authResult.username ?? ctx.githubUser ?? "unknown"}`);
+        }
+        else {
+            details.push("✗ GitHub: not authenticated");
+            if (authResult.issue !== undefined)
+                issues.push(authResult.issue);
+        }
+        // 3. Git access for repos that have a local clone
+        const accessChecker = new GitAccessChecker(this.commandRunner);
+        const reposWithClone = ctx.selectedRepos.filter((r) => r.localPath !== undefined);
+        const skippedCount = ctx.selectedRepos.length - reposWithClone.length;
+        for (const repo of reposWithClone) {
+            const access = await accessChecker.check(repo.localPath);
+            if (access.canFetch && access.canPush) {
+                details.push(`✓ ${repo.owner}/${repo.name}: fetch and push OK`);
+            }
+            else {
+                if (!access.canFetch) {
+                    details.push(`✗ ${repo.owner}/${repo.name}: cannot fetch`);
+                    if (access.fetchIssue !== undefined)
+                        issues.push(access.fetchIssue);
+                }
+                if (!access.canPush) {
+                    details.push(`⚠ ${repo.owner}/${repo.name}: cannot push (agents will not be able to commit)`);
+                    if (access.pushIssue !== undefined)
+                        issues.push(access.pushIssue);
+                }
+            }
+        }
+        if (skippedCount > 0) {
+            details.push(`- ${skippedCount} repo${skippedCount === 1 ? "" : "s"} without a local clone — git access check skipped`);
+        }
+        // 4. Ensure configured directories exist and are writable
+        const wsChecker = new WorkspaceChecker(this.platformHelper);
+        const directoryPaths = [
+            ctx.managementDir,
+            ctx.outputsDir,
+            ctx.logDir,
+            ctx.workspacesDir
+        ];
+        for (const dirPath of directoryPaths) {
+            const check = await wsChecker.check(dirPath);
+            if (check.writable) {
+                if (!check.exists) {
+                    try {
+                        await wsChecker.ensureDir(check.path);
+                        details.push(`✓ ${check.path}: created`);
+                    }
+                    catch (err) {
+                        details.push(`✗ ${check.path}: could not be created`);
+                        issues.push({
+                            title: `Cannot create directory: ${check.path}`,
+                            cause: err instanceof Error ? err.message : String(err),
+                            suggestedFix: "Choose a different directory or fix the permissions",
+                            canAutoRemediate: false,
+                            ...(check.issue?.manualSteps !== undefined
+                                ? { manualSteps: check.issue.manualSteps }
+                                : {})
+                        });
+                    }
+                }
+                else {
+                    details.push(`✓ ${check.path}: exists and writable`);
+                }
+            }
+            else {
+                details.push(`✗ ${check.path}: not writable`);
+                if (check.issue !== undefined)
+                    issues.push(check.issue);
+            }
+        }
+        // 5. Providers
+        const available = ctx.discoveredProviders.filter((p) => p.available);
+        if (available.length === 0) {
+            details.push("✗ No AI providers available");
+            issues.push({
+                title: "No AI providers installed",
+                cause: "None of agy, gemini, claude, codex, or opencode were found on PATH",
+                suggestedFix: "Install at least one AI provider before running agents",
+                canAutoRemediate: false,
+                manualSteps: [
+                    "Install antigravity: https://antigravity.google/cli",
+                    "Install gemini CLI",
+                    "Install claude: https://claude.ai/code",
+                    "Install codex: https://openai.com/codex",
+                    "Install opencode: https://opencode.ai"
+                ]
+            });
+        }
+        else {
+            details.push(`✓ AI providers: ${available.map((p) => p.name).join(", ")}`);
+        }
+        const hasStrongProductAgent = ctx.configDraft?.agents.some((agent) => agent.enabled && agent.modelClass === "strong" && agent.roles.includes("product")) ?? false;
+        if (hasStrongProductAgent) {
+            details.push("✓ Product role: enabled strong agent configured");
+        }
+        else {
+            details.push("✗ Product role: no enabled strong agent configured");
+            issues.push({
+                title: "No Product agent configured",
+                cause: "Product Discovery and Product Spec tasks require an enabled strong agent with the product role",
+                suggestedFix: "Add product to the roles for an enabled strong agent in agents.json",
+                canAutoRemediate: false,
+                manualSteps: [
+                    'Edit management/agents.json and add "product" to a strong enabled agent roles array',
+                    "Re-run backburner init or the readiness check"
+                ]
+            });
+        }
+        if (issues.length === 0) {
+            return {
+                status: "passed",
+                message: "All readiness checks passed",
+                details
+            };
+        }
+        const hasFatal = toolResults.some((r) => !r.available) || !authResult.authenticated;
+        return {
+            status: hasFatal ? "failed" : "warning",
+            message: `${issues.length} issue${issues.length === 1 ? "" : "s"} found`,
+            details,
+            issues
+        };
+    }
+}

package/dist/src/onboarding/steps/select-repos.js

@@ -0,0 +1,76 @@
+export class SelectReposStep {
+    name = "select-repos";
+    description = "Select repositories to manage";
+    async run(ctx, prompter) {
+        const { discoveredRepos } = ctx;
+        if (discoveredRepos.length === 0) {
+            return await this.promptManualEntry(ctx, prompter);
+        }
+        const byOwner = new Map();
+        for (const repo of discoveredRepos) {
+            const group = byOwner.get(repo.owner) ?? [];
+            group.push(repo);
+            byOwner.set(repo.owner, group);
+        }
+        const selected = [];
+        for (const [owner, repos] of byOwner) {
+            const options = repos.map((repo) => {
+                const note = repo.isLocalClone
+                    ? ` [local: ${repo.localPath ?? "?"}]`
+                    : " [GitHub only]";
+                return `${repo.name}${note}`;
+            });
+            const preSelected = repos.flatMap((repo, i) => (repo.isLocalClone ? [i] : []));
+            const selectedIndices = await prompter.multiSelect(`Select repositories from ${owner}/:`, options, preSelected);
+            for (const i of selectedIndices) {
+                const repo = repos[i];
+                if (repo !== undefined)
+                    selected.push(repo);
+            }
+        }
+        if (selected.length === 0) {
+            const fallback = await prompter.confirm("No repositories selected. Add one manually?", true);
+            if (fallback) {
+                return await this.promptManualEntry(ctx, prompter);
+            }
+            return {
+                status: "warning",
+                message: "No repositories selected",
+                details: ["You can add repositories by editing repos.json later."]
+            };
+        }
+        ctx.selectedRepos = selected;
+        return {
+            status: "passed",
+            message: `${ctx.selectedRepos.length} repositor${ctx.selectedRepos.length === 1 ? "y" : "ies"} selected`,
+            details: ctx.selectedRepos.map((r) => {
+                const note = r.localPath !== undefined ? ` (${r.localPath})` : " (no local clone)";
+                return `${r.owner}/${r.name}${note}`;
+            })
+        };
+    }
+    async promptManualEntry(ctx, prompter) {
+        const owner = (await prompter.ask("Repository owner (e.g. myorg):")).trim();
+        const name = (await prompter.ask("Repository name (e.g. my-repo):")).trim();
+        if (owner.length === 0 || name.length === 0) {
+            return {
+                status: "warning",
+                message: "No repository entered",
+                details: ["You can add repositories by editing repos.json later."]
+            };
+        }
+        const localPath = (await prompter.ask(`Local path to the clone (leave empty if not cloned):`)).trim();
+        const repo = {
+            owner,
+            name,
+            isLocalClone: localPath.length > 0,
+            ...(localPath.length > 0 ? { localPath } : {})
+        };
+        ctx.discoveredRepos = [repo];
+        ctx.selectedRepos = [repo];
+        return {
+            status: "passed",
+            message: `1 repository selected: ${owner}/${name}`
+        };
+    }
+}

package/dist/src/onboarding/steps/show-summary.js

@@ -0,0 +1,97 @@
+import { deriveOverallStatus } from "../engine.js";
+import * as path from "node:path";
+import { defaultBackburnerCodeRoot, defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot } from "../../utils/paths.js";
+export class ShowSummaryStep {
+    name = "show-summary";
+    description = "Summary";
+    async run(ctx, _prompter) {
+        // Derive status from steps that have already completed — the engine will
+        // not have returned yet when this step runs, so we cannot rely on a
+        // finalResult callback. ctx.stepResults is already fully populated up to
+        // (but not including) this step.
+        const priorResults = Array.from(ctx.stepResults.values());
+        const overallStatus = deriveOverallStatus(priorResults);
+        const succeeded = overallStatus === "passed" || overallStatus === "warning";
+        const lines = ["", "=== Backburner Onboarding Complete ===", ""];
+        // Paths
+        lines.push("Directories:");
+        lines.push(`  Code root:   ${ctx.codeRoot}`);
+        lines.push(`  Management:  ${ctx.managementDir}`);
+        lines.push(`  Outputs:     ${ctx.outputsDir}`);
+        lines.push(`  Logs:        ${ctx.logDir}`);
+        lines.push(`  Workspaces:  ${ctx.workspacesDir}`);
+        // Repositories
+        if (ctx.selectedRepos.length > 0) {
+            lines.push("");
+            lines.push("Repositories:");
+            for (const repo of ctx.selectedRepos) {
+                const note = repo.localPath !== undefined ? ` (${repo.localPath})` : " (no local clone)";
+                lines.push(`  - ${repo.owner}/${repo.name}${note}`);
+            }
+        }
+        else {
+            lines.push("");
+            lines.push("Repositories: none selected");
+        }
+        // Providers
+        const available = ctx.discoveredProviders.filter((p) => p.available);
+        if (available.length > 0) {
+            lines.push("");
+            lines.push("Providers:");
+            for (const p of available) {
+                lines.push(`  - ${p.name}${p.version !== undefined ? ` (${p.version})` : ""}`);
+            }
+        }
+        // Agents
+        const agents = ctx.configDraft?.agents ?? [];
+        if (agents.length > 0) {
+            lines.push("");
+            lines.push("Configured agents:");
+            for (const a of agents) {
+                const model = a.model !== undefined ? ` (${a.model})` : "";
+                lines.push(`  - ${a.id}: ${a.provider}${model} [${a.modelClass}]`);
+                lines.push(`    Roles: ${a.roles.join(", ")}`);
+            }
+        }
+        // Warnings
+        if (ctx.warnings.length > 0) {
+            lines.push("");
+            lines.push("Warnings:");
+            for (const w of ctx.warnings) {
+                lines.push(`  ⚠ ${w}`);
+            }
+        }
+        if (succeeded) {
+            lines.push("");
+            lines.push("Next steps:");
+            lines.push("  1. Create the configured GitHub labels on each managed repository");
+            lines.push("  2. Start the orchestrator:");
+            lines.push(`     ${buildRunCommand(ctx)}`);
+            lines.push("  3. Open an issue on a managed repo and apply the 'agent-plan-approved' label");
+            lines.push("  4. Watch Backburner pick it up on the next orchestration cycle");
+        }
+        else {
+            lines.push("");
+            lines.push("Fix the issues listed above, then re-run: backburner init");
+        }
+        lines.push("");
+        process.stdout.write(lines.join("\n"));
+        return { status: "passed", message: "Summary displayed" };
+    }
+}
+function buildRunCommand(ctx) {
+    const args = ["backburner", "run"];
+    if (ctx.codeRoot !== defaultBackburnerCodeRoot()) {
+        args.push("--code-root", ctx.codeRoot);
+    }
+    if (ctx.managementDir !== defaultBackburnerManagementRoot()) {
+        args.push("--management-dir", ctx.managementDir);
+    }
+    if (ctx.outputsDir !== defaultBackburnerOutputsRoot()) {
+        args.push("--outputs-dir", ctx.outputsDir);
+    }
+    if (ctx.logDir !== path.join(ctx.outputsDir, "logs")) {
+        args.push("--log-dir", ctx.logDir);
+    }
+    return args.join(" ");
+}

package/dist/src/onboarding/steps/welcome.js

@@ -0,0 +1,27 @@
+export class WelcomeStep {
+    name = "welcome";
+    description = "Welcome";
+    async run(_ctx, _prompter) {
+        const lines = [
+            "",
+            "Welcome to Backburner!",
+            "",
+            "This wizard configures Backburner to manage your GitHub repositories using local",
+            "AI agents. Work flows through GitHub issues, comments, labels, and pull",
+            "requests. Backburner runs locally and uses your existing credentials.",
+            "",
+            "You will be guided through:",
+            "  1. Checking required tools",
+            "  2. Validating GitHub authentication",
+            "  3. Selecting repositories to manage",
+            "  4. Configuring directories",
+            "  5. Detecting available AI providers",
+            "  6. Assigning models to agent roles",
+            "  7. Generating configuration files",
+            "  8. Running a final readiness check",
+            ""
+        ];
+        process.stdout.write(lines.join("\n"));
+        return { status: "passed", message: "Ready to begin" };
+    }
+}

package/dist/src/onboarding/types.js

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

package/dist/src/onboarding/validators/git-access.js

@@ -0,0 +1,63 @@
+export class GitAccessChecker {
+    commandRunner;
+    constructor(commandRunner) {
+        this.commandRunner = commandRunner;
+    }
+    async checkFetch(repoPath, remote = "origin") {
+        try {
+            await this.commandRunner.run("git", ["fetch", "--dry-run", remote], {
+                cwd: repoPath,
+                timeoutMs: 30_000
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async checkPush(repoPath, remote = "origin") {
+        try {
+            await this.commandRunner.run("git", ["push", "--dry-run", "--porcelain", remote, "HEAD"], { cwd: repoPath, timeoutMs: 30_000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async check(repoPath) {
+        const [canFetch, canPush] = await Promise.all([
+            this.checkFetch(repoPath),
+            this.checkPush(repoPath)
+        ]);
+        const result = { canFetch, canPush };
+        if (!canFetch) {
+            result.fetchIssue = {
+                title: "Cannot fetch from remote",
+                cause: `git fetch --dry-run failed for repository at "${repoPath}"`,
+                suggestedFix: "Verify the remote URL and network or credential access",
+                canAutoRemediate: false,
+                manualSteps: [
+                    `Open a terminal in the repository directory: "${repoPath}"`,
+                    "Run `git remote -v` to verify the remote URL",
+                    "Run `gh auth setup-git` to configure git to use your GitHub credentials",
+                    "Run `git fetch origin` to attempt the fetch manually"
+                ]
+            };
+        }
+        if (!canPush) {
+            result.pushIssue = {
+                title: "Cannot push to remote",
+                cause: `git push --dry-run failed for repository at "${repoPath}"`,
+                suggestedFix: "Verify push permissions on GitHub",
+                canAutoRemediate: false,
+                manualSteps: [
+                    `Open a terminal in the repository directory: "${repoPath}"`,
+                    "Run `gh auth setup-git` to configure git to use your GitHub credentials",
+                    "Run `git push --dry-run origin HEAD` to attempt the push manually",
+                    "Check that you have write access to the repository on GitHub"
+                ]
+            };
+        }
+        return result;
+    }
+}

package/dist/src/onboarding/validators/github-auth.js

@@ -0,0 +1,85 @@
+/** Substrings in `gh auth status` error output that indicate the user is simply not logged in. */
+const AUTH_ERROR_SIGNALS = [
+    "not logged",
+    "not authenticated",
+    "You are not",
+    "no credentials",
+    "authentication required"
+];
+export class GitHubAuthChecker {
+    commandRunner;
+    constructor(commandRunner) {
+        this.commandRunner = commandRunner;
+    }
+    async check() {
+        try {
+            const result = await this.commandRunner.run("gh", ["auth", "status"], {
+                timeoutMs: 15_000
+            });
+            const output = result.stdout + result.stderr;
+            const username = extractUsername(output);
+            return {
+                authenticated: true,
+                ...(username !== undefined ? { username } : {})
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const isAuthError = AUTH_ERROR_SIGNALS.some((signal) => message.toLowerCase().includes(signal.toLowerCase()));
+            if (isAuthError) {
+                return {
+                    authenticated: false,
+                    issue: {
+                        title: "Not authenticated with GitHub",
+                        cause: "The GitHub CLI is not authenticated with a GitHub account",
+                        suggestedFix: "Run: gh auth login",
+                        canAutoRemediate: false,
+                        manualSteps: [
+                            "In PowerShell, Command Prompt, or a POSIX shell, run: gh auth login",
+                            "Follow the prompts to authenticate with your GitHub account",
+                            "Then re-run: backburner init"
+                        ]
+                    }
+                };
+            }
+            // Unexpected failure (network error, Enterprise config, CLI crash, etc.).
+            // Surface it honestly rather than misreporting it as a login problem.
+            return {
+                authenticated: false,
+                issue: {
+                    title: "GitHub CLI check failed unexpectedly",
+                    cause: message,
+                    suggestedFix: "Check that the GitHub CLI is installed and working, then re-run: backburner init",
+                    canAutoRemediate: false,
+                    manualSteps: [
+                        "Run `gh auth status` manually to see the full error",
+                        "Run `gh --version` to verify the CLI is installed and on PATH"
+                    ]
+                }
+            };
+        }
+    }
+    async getAuthenticatedUser() {
+        try {
+            const result = await this.commandRunner.run("gh", ["api", "user", "--jq", ".login"], { timeoutMs: 10_000 });
+            const user = result.stdout.trim();
+            return user.length > 0 ? user : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function extractUsername(output) {
+    const patterns = [
+        /Logged in to github\.com account ([^\s]+)/i,
+        /account:\s+([^\s]+)/i,
+        /as ([^\s]+)\s*\(/i
+    ];
+    for (const pattern of patterns) {
+        const match = output.match(pattern);
+        if (match?.[1])
+            return match[1];
+    }
+    return undefined;
+}