@backburner/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elad Aviv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,329 @@
+# Backburner CLI
+
+Backburner is a local GitHub-driven agent orchestration CLI. It uses GitHub labels, issues, and pull requests as the control plane, keeps configuration and state as readable JSON on your machine, and dispatches eligible work to provider CLIs that you already have installed locally.
+
+Backburner currently supports:
+
+- `backburner init` for interactive or non-interactive local setup
+- `backburner run` for one orchestration cycle
+- `backburner run-loop` for repeated cycles on a fixed interval
+- `backburner journal` for reading persisted run and workflow events
+- `backburner broker` for a local GitHub broker MCP endpoint
+- a plan-first label workflow for product approval, plan approval, review requests, and parent-branch sync approval
+- local provider CLIs for Antigravity, Codex, Gemini, Claude, and OpenCode
+
+## Prerequisites
+
+- Node.js `>=20`
+- npm
+- git
+- GitHub CLI authenticated for the account and repositories you want Backburner to manage:
+
+```sh
+gh auth status
+```
+
+- at least one supported provider CLI on `PATH`: `agy`, `codex`, `gemini`, `claude`, or `opencode`
+
+Backburner uses your local `git`, `gh`, and provider CLI credentials. It does not provide hosted execution or cloud credentials.
+
+## Install
+
+From a source checkout:
+
+```sh
+npm install
+npm run build
+node dist/src/cli/run.js init
+```
+
+Windows PowerShell:
+
+```powershell
+npm install
+npm run build
+node .\dist\src\cli\run.js init
+```
+
+For active local development, link this checkout into your global npm bin directory:
+
+```sh
+npm run link:local
+backburner init
+```
+
+To install and verify the locally packed package:
+
+```sh
+npm run install:local
+backburner journal --json
+```
+
+To install the local package into a temporary npm prefix:
+
+macOS/Linux:
+
+```sh
+npm run install:local -- --prefix /tmp/backburner-local
+/tmp/backburner-local/bin/backburner journal --json
+```
+
+Windows PowerShell:
+
+```powershell
+npm run install:local -- --prefix "$env:TEMP\backburner-local"
+& "$env:TEMP\backburner-local\backburner.cmd" journal --json
+```
+
+Once the current package is published:
+
+```sh
+npm install -g @backburner/cli
+backburner init
+```
+
+The package bin is `backburner`.
+
+The npm package intentionally includes the compiled CLI under `dist/src`, `README.md`, `LICENSE`, and package metadata. Contributor docs and generated docs are kept in the source repository and are not part of the install tarball.
+
+## Quick Start
+
+Run onboarding:
+
+```sh
+backburner init
+```
+
+Source checkout equivalent:
+
+```sh
+node dist/src/cli/run.js init
+```
+
+Non-interactive setup accepts defaults:
+
+```sh
+backburner init --yes
+```
+
+Useful `init` flags:
+
+```text
+--code-root <path>       Root where managed repos are cloned
+--management-dir <path>  Directory for configuration files
+--outputs-dir <path>     Directory for generated state, journal, and logs
+--log-dir <path>         Directory for execution logs
+--workspaces-dir <path>  Directory used by onboarding readiness checks
+--yes, -y                Accept defaults without prompts
+```
+
+`backburner init` checks local requirements, confirms `gh auth status`, discovers repositories, detects provider CLIs, and writes these files into the management directory:
+
+- `repos.json`
+- `agents.json`
+
+If either file already exists, onboarding asks before overwriting it. With `--yes`, defaults are accepted non-interactively.
+
+## Default Directories
+
+By default, Backburner stores data under `~/.backburner`:
+
+- code root: `~/.backburner/code`
+- management directory: `~/.backburner/management`
+- outputs directory: `~/.backburner/outputs`
+- state directory: `~/.backburner/outputs/state`
+- journal directory: `~/.backburner/outputs/journal`
+- log directory: `~/.backburner/outputs/logs`
+- onboarding workspaces directory: `<code-root>/_worktrees`
+
+Set `BACKBURNER_ROOT` to change the root used for the default code, management, and outputs directories.
+
+## Configuration
+
+Backburner configuration lives in the management directory.
+
+Minimal `repos.json`:
+
+```json
+{
+  "allowedUsers": [
+    "your-github-user"
+  ],
+  "repos": [
+    {
+      "id": "your-github-user-example-repo",
+      "owner": "your-github-user",
+      "name": "example-repo",
+      "defaultBranch": "main",
+      "localPath": "your-github-user/example-repo",
+      "enabled": true,
+      "labels": {
+        "agentInProgress": "agent-in-progress",
+        "agentProductApproved": "agent-product-approved",
+        "agentPlanApproved": "agent-plan-approved",
+        "agentReview": "agent-review",
+        "planBreakdownNeeded": "plan-breakdown-needed",
+        "agentSyncParentBranch": "agent-sync-parent-branch",
+        "prepareForMerge": "prepare-for-merge"
+      }
+    }
+  ]
+}
+```
+
+Minimal `agents.json`:
+
+```json
+{
+  "agents": [
+    {
+      "id": "codex-strong",
+      "provider": "codex",
+      "modelClass": "strong",
+      "model": "gpt-5",
+      "roles": [
+        "product",
+        "planning",
+        "review",
+        "discussion",
+        "implementation_manager"
+      ],
+      "command": "codex",
+      "enabled": true
+    },
+    {
+      "id": "opencode-cheap",
+      "provider": "opencode",
+      "modelClass": "cheap",
+      "model": "your-fast-model",
+      "roles": [
+        "implementation",
+        "discussion"
+      ],
+      "command": "opencode",
+      "enabled": true
+    }
+  ]
+}
+```
+
+`allowedUsers` limits which GitHub users can feed issues, comments, reviews, and pull requests into task derivation. `localPath` must be relative to `--code-root`.
+
+Agent selection filters enabled agents by required role and `modelClass`, then breaks ties by lowest agent `id`. Provider model names are passed through to the provider CLI and are not validated against vendor catalogs.
+
+## Label Control Plane
+
+Configure labels per repository in `repos.json`. The common defaults are:
+
+- `agent-product-approved`: approves product discovery and allows Backburner to create the implementation PR/worktree flow for an issue
+- `agent-plan-approved`: approves an implementation plan and allows implementation tasks to run
+- `agent-review`: requests an explicit code review; review tasks are dispatched when the PR has this label and its head SHA changed since the last review
+- `agent-sync-parent-branch`: authorizes Backburner to sync a blocked parent implementation branch from the repository default branch
+
+Backburner also uses `agent-in-progress`, `plan-breakdown-needed`, and `prepare-for-merge` when those labels are configured.
+
+## Commands
+
+Run one cycle:
+
+```sh
+backburner run
+```
+
+Source checkout:
+
+```sh
+node dist/src/cli/run.js run
+```
+
+Common run flags:
+
+```text
+--code-root <path>
+--management-dir <path>
+--outputs-dir <path>
+--log-dir <path>
+--broker-port <port>
+--headless
+--once
+```
+
+Run continuously:
+
+```sh
+backburner run-loop --interval-minutes 5
+```
+
+`run-loop` accepts the same path and broker flags as `run`, plus either `--interval-seconds <seconds>` or `--interval-minutes <minutes>`. The default interval is 5 minutes. `SIGINT` and `SIGTERM` request a graceful stop after the current cycle.
+
+Read the journal:
+
+```sh
+backburner journal --last 20
+backburner journal --repo your-github-user-example-repo --json
+```
+
+Journal filters:
+
+```text
+--outputs-dir <path>
+--repo <id>
+--workstream <id>
+--issue <number>
+--pr <number>
+--since <ISO timestamp>
+--last <number>
+--json
+--verbose
+```
+
+Start the GitHub broker MCP:
+
+```sh
+backburner broker --port 4444
+```
+
+Broker flags:
+
+```text
+--management-dir <path>
+--host <host>
+--port <port>
+```
+
+The broker serves:
+
+- `POST /mcp`
+- `GET /health`
+
+It exposes managed-repository tools for issue, PR, comment, check-run, code-search, PR creation, and PR review-comment reply workflows, plus plan-breakdown and wave-assessment tools used by Backburner providers.
+
+Smoke-test the broker after building:
+
+```sh
+npm run smoke:github-broker
+npm run smoke:github-broker -- --repo your-github-user/example-repo --issue-number 123
+```
+
+## What A Run Does
+
+`backburner run` loads configuration, prepares local management and outputs directories, loads state, syncs enabled repositories, scans GitHub through `gh`, derives tasks, starts a local GitHub broker for provider access, dispatches eligible tasks to configured provider CLIs, writes state and logs, and prints a run summary.
+
+Generated files are readable JSON. Control-plane state is written under `<outputs-dir>/state`, including repository sync status, issues, PRs, comments, tasks, worktrees, attention records, MCP status, provider limits, and job memory. Execution logs and artifacts are written under `<outputs-dir>/logs`. Journal events are written under `<outputs-dir>/journal`.
+
+## Platform Support
+
+Backburner is intended to run on macOS, Linux, and Windows with Node.js 20 or newer. The current CI workflow in this checkout runs on Ubuntu, macOS, and Windows with Node 20 and 22, and includes build, typecheck, tests, package dry-run, and local package install smoke checks.
+
+## Verification
+
+Use these checks before publishing or changing behavior:
+
+```sh
+npm run build
+npm run typecheck
+npm test
+npm pack --dry-run
+```
+
+For docs-only changes, at minimum verify that documented commands, package contents, and public-safety scrub patterns still match the repository.

package/dist/src/agents/antigravity-launch.js

@@ -0,0 +1,162 @@
+import { copyFile, mkdir, readFile } from "node:fs/promises";
+import * as path from "node:path";
+import { writeJsonFileAtomic } from "../utils/json.js";
+export function mapPermissionToAntigravityMode(permission) {
+    switch (permission) {
+        case "read-only":
+            return "sandbox";
+        case "workspace-write":
+            return "always-proceed";
+    }
+}
+export function buildAntigravityCliArgs(options) {
+    const args = [
+        "--print-timeout",
+        options.printTimeout,
+        "--log-file",
+        options.logFilePath
+    ];
+    if (options.model) {
+        args.push("--model", options.model);
+    }
+    if (options.conversationId) {
+        args.push("--conversation", options.conversationId);
+    }
+    if (options.permissionMode === "sandbox") {
+        args.push("--sandbox");
+    }
+    else {
+        args.push("--dangerously-skip-permissions");
+    }
+    args.push("--print", "-");
+    return args;
+}
+export async function writeAntigravitySettings(settingsPath, options) {
+    await writeJsonFileAtomic(settingsPath, {
+        allowNonWorkspaceAccess: false,
+        enableTerminalSandbox: options.permissionMode === "sandbox",
+        toolPermission: options.permissionMode === "sandbox" ? "proceed-in-sandbox" : "always-proceed",
+        trustedWorkspaces: [options.cwd],
+        ...(options.model ? { model: options.model } : {})
+    });
+}
+export async function writeAntigravityMcpConfig(configPath, options) {
+    const config = options.mcp ? buildMcpConfig(options.mcp) : { mcpServers: {} };
+    await writeJsonFileAtomic(configPath, config);
+}
+export async function ensureAntigravityMcpConfig(antigravityHome, mcp, options = {}) {
+    const configPath = path.join(antigravityHome, "mcp_config.json");
+    await mkdir(antigravityHome, { recursive: true });
+    const existing = await readExistingMcpConfig(configPath);
+    const config = existing.config;
+    const mcpServers = normalizeMcpServers(config["mcpServers"]);
+    const existingServer = normalizeServerRecord(mcpServers[mcp.serverName]);
+    const configuredUrl = getConfiguredServerUrl(existingServer);
+    if (configuredUrl === mcp.serverUrl) {
+        return { configPath, changed: false };
+    }
+    let backupPath;
+    if (existing.existed) {
+        backupPath = `${configPath}.backup-before-backburner-${formatBackupTimestamp(options.now?.() ?? new Date().toISOString())}`;
+        await copyFile(configPath, backupPath);
+    }
+    const nextConfig = {
+        ...config,
+        mcpServers: {
+            ...mcpServers,
+            [mcp.serverName]: {
+                ...existingServer,
+                serverUrl: mcp.serverUrl
+            }
+        }
+    };
+    await writeJsonFileAtomic(configPath, nextConfig);
+    return {
+        configPath,
+        changed: true,
+        ...(backupPath ? { backupPath } : {})
+    };
+}
+function buildMcpConfig(mcp) {
+    return {
+        mcpServers: {
+            [mcp.serverName]: {
+                serverUrl: mcp.serverUrl
+            }
+        }
+    };
+}
+async function readExistingMcpConfig(configPath) {
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf8");
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return { existed: false, config: {} };
+        }
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Antigravity MCP config at ${configPath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Antigravity MCP config at ${configPath} must be a JSON object.`);
+    }
+    return { existed: true, config: parsed };
+}
+function normalizeMcpServers(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function normalizeServerRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function getConfiguredServerUrl(serverRecord) {
+    return typeof serverRecord["serverUrl"] === "string"
+        ? serverRecord["serverUrl"]
+        : typeof serverRecord["url"] === "string"
+            ? serverRecord["url"]
+            : undefined;
+}
+function formatBackupTimestamp(timestamp) {
+    return timestamp.replace(/[^0-9A-Za-z_-]+/g, "-");
+}
+export function getAntigravityEnvOverrides() {
+    return {
+        AGY_HOME: undefined,
+        ANTIGRAVITY_HOME: undefined
+    };
+}
+export function buildGlobalAntigravityLaunchInstructions(input) {
+    return [
+        "# Global Antigravity Instructions",
+        "",
+        "These instructions apply across repositories for this orchestrated run.",
+        "",
+        "## MCP Server",
+        `Use the local MCP server \`${input.mcp.serverName}\` for managed GitHub operations.`,
+        "- Invoke broker tools instead of using `gh` directly.",
+        "- If a needed GitHub capability is missing from the broker, report the gap clearly instead of silently bypassing it.",
+        "",
+        "Enabled broker tools for this run:",
+        ...input.mcp.toolAllowList.map((tool) => `- \`${tool}\``),
+        "",
+        "Any GitHub-authored message you post must begin with `🤖`."
+    ].join("\n");
+}
+export function prependGlobalAntigravityLaunchInstructions(promptText, options) {
+    if (!options.mcp) {
+        return promptText;
+    }
+    return `${buildGlobalAntigravityLaunchInstructions({ mcp: options.mcp })}\n\n${promptText}`;
+}