super-backlog 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 super-backlog contributors
+
+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,87 @@
+# super-backlog
+
+[![CI](https://github.com/adam-s-k-i/super-backlog/actions/workflows/ci.yml/badge.svg)](https://github.com/adam-s-k-i/super-backlog/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-adam--s--k--i.github.io%2Fsuper--backlog-blue)](https://adam-s-k-i.github.io/super-backlog/)
+
+![Super Backlog](docs/assets/super-backlog-logo.jpg)
+
+One command to equip any project with [Backlog.md](https://github.com/MrLesk/Backlog.md) + [Superpowers](https://github.com/obra/superpowers), plus a Project Dashboard.
+
+## What & why
+
+Superpowers and Backlog.md are strong on their own, but nothing wires them together: Superpowers defines *how* agents should work (brainstorming → plans → TDD → review), Backlog.md defines *what* is tracked (markdown tasks, Kanban board, browser UI). Connecting them today means hand-copying glue from project to project — workflow blocks in `AGENTS.md`, bridge skills like `spec-to-backlog`, npm scripts, plugin config. super-backlog is the glue orchestrator that installs and maintains all of it in one step, with a guaranteed-clean exit path (`sbl uninstall`).
+
+## Requirements
+
+- Node >= 20
+- A package manager (npm, pnpm, or bun) for dependency installation
+- Works with **OpenCode** and **Claude Code** (both configured by default)
+
+## Quickstart
+
+```bash
+npx super-backlog init        # install everything into the current project
+npm run board                 # open the Backlog.md kanban board
+sbl dashboard --serve         # live Project Dashboard on http://localhost:6428
+                              # (or: npx super-backlog dashboard --serve)
+```
+
+On Windows PowerShell, `npx super-backlog init` may fail with an execution-policy error before the CLI starts. Run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once in PowerShell, or run `sbl doctor` for the exact policy and fix.
+
+`init` is idempotent — safe to re-run any time; re-running with a newer kit version is the upgrade path for all injected files.
+
+## What gets installed
+
+| Target | Content | Ownership model |
+|---|---|---|
+| `package.json` devDependencies | `backlog.md@latest` + `super-backlog@latest` | merged |
+| `backlog/` | created by `backlog init --defaults` (upstream owns it) | delegated |
+| `opencode.json` | `plugin[] += superpowers@git+https://github.com/obra/superpowers.git` | merged; other keys untouched |
+| `.claude/` | Superpowers via official marketplace — init prints the exact command to paste (`/plugin install superpowers@claude-plugins-official`); file-based skills work immediately | instructed/delegated |
+| `AGENTS.md` | `<!-- SUPER-BACKLOG:x.y.z START -->` … `<!-- SUPER-BACKLOG END -->` workflow block | marker-scoped |
+| `CLAUDE.md` | one-line pointer to the AGENTS.md block | marker-scoped |
+| `.opencode/skill/<skill>/SKILL.md` (3 glue skills) | skill templates | fingerprint header line |
+| `.claude/skills/<skill>/SKILL.md` | same templates | fingerprint header line |
+| `package.json` scripts | `tasks` → `backlog task list`, `board` → `backlog board`, `browser` → `backlog browser`, `dashboard` → `super-backlog dashboard` (never overwrite existing values) | merged, add-only-if-absent |
+| `dashboard.html` | generated Project Dashboard | regenerated wholesale |
+| `.git/hooks/post-commit` | dashboard freshness block — regenerates `dashboard.html` after commits that touch `backlog/` (default; opt out with `--no-refresh-hook`) | appended marker block |
+| `.git/hooks/pre-commit` | integrity guard hook — only with `--guard` (opt-in) | appended marker block |
+
+Commands: `sbl init` · `sbl doctor` · `sbl uninstall [--with-backlog]` · `sbl update` · `sbl dashboard [--serve] [--port <n>] [--no-open] [--out <file>]`. See `sbl help` for every flag.
+
+## Project Dashboard
+
+`sbl dashboard` generates a single self-contained `dashboard.html`: a dark, HTS-style cockpit rendered from your Backlog data in seven sections — Board & Quick Actions, Status (donut), Milestones, Tasks (sortable/filterable table with a click-in detail panel per task), Feature Cycle (pipeline stepper), Activity (30-day sparkline), and Decisions & Docs. A layered dependency graph maps task `depends-on` relations (cycle- and dangling-ref-tolerant): hover highlights edges, click opens the task. Glossary tooltips explain domain terms inline; extend or override them project-wide via `backlog/docs/glossary.md` (`## Term` heading plus the text below it). No CDNs, no external fonts — works offline, diffs cleanly in git, hostable anywhere. Use `--serve` for live mode: it watches `backlog/`, regenerates on change, and serves on port 6428 by default.
+
+### Keeping it fresh
+
+By default `init` installs a `post-commit` hook block that regenerates `dashboard.html` whenever the commit touched `backlog/`. The block is marker-delimited, so it composes with the guard hook and foreign hook content, `uninstall` removes exactly that block, and `update` refreshes it. It never blocks a commit: failures print a one-line stderr note and the exit status stays 0. Opt out with `--no-refresh-hook`.
+
+![Project Dashboard](docs/assets/dashboard.png)
+
+## Uninstall guarantee
+
+super-backlog uninstall removes only provably owned artifacts and keeps your Backlog task data unless you pass --with-backlog. Every removal decision is reported line by line as removed / kept / skipped; files whose ownership cannot be proven are left untouched.
+
+## Harness support
+
+- **OpenCode** — native: `opencode.json` plugin entry plus file-based skills under `.opencode/skill/` (spec-to-backlog, backlog-status-report, task-review-gate).
+- **Claude Code** — file-based skills under `.claude/skills/` always work immediately; the marketplace plugin cannot be installed from a script, so init prints the exact command to paste (`/plugin install superpowers@claude-plugins-official`) and exits with a warning (exit code 4).
+
+Details and matrix: [docs/guide/harness-support.md](docs/guide/harness-support.md).
+
+## Troubleshooting
+
+Windows OpenCode fallback, exit codes, and environment seams: [docs/guide/troubleshooting.md](docs/guide/troubleshooting.md). Architecture deep-dive: [docs/guide/architecture.md](docs/guide/architecture.md). Guard hook details: [docs/guide/guard.md](docs/guide/guard.md).
+
+## Development
+
+```bash
+npm ci          # install dependencies
+npm test        # build + vitest suite
+npm run lint    # markdownlint + cspell over all Markdown
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// src/cli.ts
+import { parseArgs } from 'node:util';
+import process from 'node:process';
+import { runDashboard } from './commands/dashboard.js';
+import { runDoctor } from './commands/doctor.js';
+import { runInit } from './commands/init.js';
+import { runUninstall } from './commands/uninstall.js';
+import { runUpdate } from './commands/update.js';
+import { assertNode20, KIT_VERSION } from './lib/version.js';
+const HELP = `super-backlog (sbl) - equip any project with Backlog.md + Superpowers
+
+Usage: sbl <command> [options]
+
+Commands:
+  init        Install the kit into the current project
+  uninstall   Remove kit-managed files (project data kept unless --with-backlog)
+  update      Refresh kit-managed files and report upstream versions
+  dashboard   Generate the single-file project dashboard (--serve for live mode)
+  doctor      Check the environment (node, PowerShell policy, backlog CLI)
+
+init options:
+  --pm <auto|npm|pnpm|bun|skip>   Package manager to use (default: auto)
+  --harness <opencode|claude>     Target harness; repeatable or comma-separated (default: both)
+  --guard                         Install the integrity pre-commit hook (opt-in)
+  --no-dashboard                  Skip generating the project dashboard
+  --no-refresh-hook               Skip the post-commit dashboard freshness hook
+  --dry-run                       Show what would be done without writing anything
+
+uninstall options:
+  --with-backlog                  Also permanently delete the backlog/ data directory
+
+update options:
+  (none)                          Refreshes injected files, skills, hook; prints upstream versions
+
+dashboard options:
+  --serve                         Live mode: watch backlog/ and regenerate on changes
+  --port <n>                      Port for --serve (default: 6428)
+  --no-open                       With --serve: do not open the browser automatically
+  --out <file>                    Output file name or path (default: dashboard.html)
+
+doctor options:
+  (none)                          Prints one [ok]/[warn]/[skip] line per check; exit 4 on any warn
+
+Global options:
+  --version                       Print the super-backlog version and exit
+
+Exit codes:
+  0 ok | 1 usage/detection failure | 2 ownership or merge refusal
+  3 upstream command failure | 4 success with warnings`;
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === '--version' || command === '-v') {
+        console.log(KIT_VERSION);
+        return 0;
+    }
+    if (command === undefined || command === 'help' || command === '--help' || command === '-h') {
+        console.log(HELP);
+        return 0;
+    }
+    switch (command) {
+        case 'init': {
+            const parsed = parseArgs({
+                args: rest,
+                allowPositionals: true,
+                options: {
+                    pm: { type: 'string' },
+                    harness: { type: 'string', multiple: true },
+                    guard: { type: 'boolean' },
+                    'no-dashboard': { type: 'boolean' },
+                    'no-refresh-hook': { type: 'boolean' },
+                    'dry-run': { type: 'boolean' },
+                },
+            });
+            return await runInit(process.cwd(), {
+                values: parsed.values,
+                positionals: parsed.positionals,
+            });
+        }
+        case 'uninstall': {
+            const parsed = parseArgs({
+                args: rest,
+                allowPositionals: true,
+                options: { 'with-backlog': { type: 'boolean' } },
+            });
+            return runUninstall(process.cwd(), {
+                values: parsed.values,
+                positionals: parsed.positionals,
+            });
+        }
+        case 'update': {
+            const parsed = parseArgs({ args: rest, allowPositionals: true, options: {} });
+            return await runUpdate(process.cwd(), {
+                values: parsed.values,
+                positionals: parsed.positionals,
+            });
+        }
+        case 'dashboard': {
+            const parsed = parseArgs({
+                args: rest,
+                allowPositionals: true,
+                options: {
+                    serve: { type: 'boolean' },
+                    port: { type: 'string' },
+                    'no-open': { type: 'boolean' },
+                    out: { type: 'string' },
+                },
+            });
+            return await runDashboard(process.cwd(), {
+                values: parsed.values,
+                positionals: parsed.positionals,
+            });
+        }
+        case 'doctor':
+            return runDoctor(process.cwd());
+        default:
+            console.error(`Unknown command "${command}".\n`);
+            console.error(HELP);
+            return 1;
+    }
+}
+assertNode20();
+main(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

package/dist/commands/dashboard.js

@@ -0,0 +1,69 @@
+// src/commands/dashboard.ts
+import { isAbsolute, join, resolve } from 'node:path';
+import { collectDashboardData } from '../dashboard/data.js';
+import { renderDashboard } from '../dashboard/render.js';
+import { DASHBOARD_PORT, startServeServer } from '../dashboard/server.js';
+import { atomicWrite } from '../lib/atomic.js';
+import { KIT_VERSION } from '../lib/version.js';
+async function regenerateInto(outPath, cwd) {
+    const data = collectDashboardData(cwd, { kitVersion: KIT_VERSION });
+    atomicWrite(outPath, renderDashboard(data));
+}
+/**
+ * Generate dashboard.html for the project; with `{ serve: true }`, start the
+ * live-reload server afterwards (the listening socket keeps the process up).
+ * Called by `sbl init` with serve disabled.
+ */
+export async function generateDashboard(cwd, o) {
+    const outPath = join(cwd, 'dashboard.html');
+    await regenerateInto(outPath, cwd);
+    if (o.serve) {
+        // Dynamic import keeps init resilient if the serve module is unavailable.
+        const specifier = '../dashboard/server.js';
+        const mod = (await import(specifier));
+        if (typeof mod.startServeServer !== 'function') {
+            throw new Error('serve module does not export startServeServer');
+        }
+        await mod.startServeServer(cwd, {
+            port: DASHBOARD_PORT,
+            regenerate: () => regenerateInto(outPath, cwd),
+            openBrowser: true,
+        });
+    }
+    return outPath;
+}
+/** CLI entry for `sbl dashboard [--serve] [--port N] [--no-open] [--out FILE]`. */
+export async function runDashboard(cwd, args) {
+    const values = args.values;
+    let port = DASHBOARD_PORT;
+    if (values['port'] !== undefined) {
+        const parsed = Number(values['port']);
+        if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+            console.error(`error: invalid --port "${String(values['port'])}" (expected 0-65535)`);
+            return 1;
+        }
+        port = parsed;
+    }
+    const serve = values['serve'] === true;
+    const noOpen = values['no-open'] === true;
+    const outFile = values['out'] === undefined ? 'dashboard.html' : String(values['out']);
+    const outPath = isAbsolute(outFile) ? outFile : resolve(cwd, outFile);
+    try {
+        await regenerateInto(outPath, cwd);
+        console.log(`dashboard written: ${outPath}`);
+        if (serve) {
+            console.log(`serving dashboard at http://127.0.0.1:${port}/ (press Ctrl+C to stop)`);
+            await startServeServer(cwd, {
+                port,
+                file: outPath,
+                regenerate: () => regenerateInto(outPath, cwd),
+                openBrowser: !noOpen,
+            });
+        }
+        return 0;
+    }
+    catch (err) {
+        console.error(`error: dashboard generation failed (${err instanceof Error ? err.message : String(err)})`);
+        return 1;
+    }
+}

package/dist/commands/doctor.js

@@ -0,0 +1,65 @@
+// src/commands/doctor.ts
+import process from 'node:process';
+import { getEffectiveExecutionPolicy, isBlockingExecutionPolicy, } from '../lib/powershell.js';
+import { resolveBacklogBin } from '../lib/run.js';
+const MARK = { ok: '[ok]  ', warn: '[warn]', skip: '[skip]' };
+export function runDoctor(cwd, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const nodeVersion = deps.nodeVersion ?? process.versions.node;
+    const resolveBacklog = deps.resolveBacklog ?? resolveBacklogBin;
+    const log = deps.log ?? ((line) => console.log(line));
+    let okCount = 0;
+    let warnCount = 0;
+    let skipCount = 0;
+    const emit = (status, line, extra = []) => {
+        if (status === 'ok')
+            okCount += 1;
+        else if (status === 'warn')
+            warnCount += 1;
+        else
+            skipCount += 1;
+        log(`${MARK[status]} ${line}`);
+        for (const extraLine of extra)
+            log(`        ${extraLine}`);
+    };
+    // check 1: node >= 20
+    const major = Number(nodeVersion.split('.')[0]);
+    if (Number.isNaN(major)) {
+        emit('warn', `node version unreadable ("${nodeVersion}") - super-backlog requires Node >= 20`);
+    }
+    else if (major >= 20) {
+        emit('ok', `node v${nodeVersion} (>= 20)`);
+    }
+    else {
+        emit('warn', `node v${nodeVersion} is too old - super-backlog requires Node >= 20`, [
+            'fix: upgrade Node.js (https://nodejs.org)',
+        ]);
+    }
+    // check 2: PowerShell execution policy (win32 only, fakeable via SBL_FAKE_POLICY)
+    const policy = getEffectiveExecutionPolicy({ platform, executor: deps.executor });
+    if (policy === null) {
+        emit('skip', 'PowerShell execution policy check (not Windows or undetectable)');
+    }
+    else if (isBlockingExecutionPolicy(policy)) {
+        emit('warn', `PowerShell execution policy "${policy}" blocks .ps1 shims - direct npm/npx/sbl calls in PowerShell will fail`, [
+            'fix: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned',
+            'alt: call the .cmd shims explicitly (npx.cmd, sbl.cmd) or run from cmd.exe',
+            'note: "npm run ..." scripts are unaffected (they execute via cmd.exe)',
+        ]);
+    }
+    else {
+        emit('ok', `PowerShell execution policy: ${policy}`);
+    }
+    // check 3: backlog binary resolvability
+    const backlogBin = resolveBacklog(cwd);
+    if (backlogBin !== null) {
+        emit('ok', `backlog CLI resolvable at ${backlogBin}`);
+    }
+    else {
+        emit('warn', 'backlog CLI not found - run sbl init or npm install first', [
+            'fix: npx.cmd super-backlog init',
+        ]);
+    }
+    log(`doctor summary: ${okCount} ok, ${warnCount} warn, ${skipCount} skip`);
+    return warnCount > 0 ? 4 : 0;
+}

package/dist/commands/init.js

@@ -0,0 +1,138 @@
+// src/commands/init.ts
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { detectPackageManager } from '../lib/pm.js';
+import { getEffectiveExecutionPolicy, isBlockingExecutionPolicy, policyWarningLines, } from '../lib/powershell.js';
+import { KIT_VERSION } from '../lib/version.js';
+import { executeActions, InvalidJsonError, RefusalError, UpstreamError } from '../init/execute.js';
+import { planInit } from '../init/planner.js';
+const HARNESS_VALUES = ['opencode', 'claude'];
+const PM_VALUES = ['auto', 'npm', 'pnpm', 'bun', 'skip'];
+function isHarness(value) {
+    return HARNESS_VALUES.includes(value);
+}
+function describeAction(action) {
+    switch (action.kind) {
+        case 'upstream-install':
+            return `upstream-install via ${action.pm}`;
+        case 'merge-json':
+            return `merge-json ${action.path} (${action.transform})`;
+        case 'inject-agents-block':
+            return 'inject-agents-block AGENTS.md';
+        case 'write-claude-pointer':
+            return 'write-claude-pointer CLAUDE.md';
+        case 'copy-skills':
+            return 'copy-skills (.opencode/skill + .claude/skills)';
+        case 'install-guard-hook':
+            return 'install-guard-hook .git/hooks/pre-commit';
+        case 'install-refresh-hook':
+            return 'install-refresh-hook .git/hooks/post-commit';
+        case 'generate-dashboard':
+            return 'generate-dashboard';
+        case 'write':
+            return `write ${action.path}`;
+    }
+}
+function maybePrintPolicyWarning() {
+    const policy = getEffectiveExecutionPolicy();
+    if (isBlockingExecutionPolicy(policy)) {
+        for (const line of policyWarningLines(policy)) {
+            console.log(line);
+        }
+    }
+}
+export async function runInit(cwd, args) {
+    const harnesses = [];
+    const rawHarnesses = args.values.harness;
+    const listed = Array.isArray(rawHarnesses)
+        ? rawHarnesses
+        : rawHarnesses === undefined
+            ? []
+            : [rawHarnesses];
+    for (const entry of listed) {
+        for (const part of String(entry).split(',')) {
+            const name = part.trim();
+            if (name === '')
+                continue;
+            if (!isHarness(name)) {
+                console.error(`Invalid --harness "${name}" (expected: ${HARNESS_VALUES.join(', ')})`);
+                return 1;
+            }
+            if (!harnesses.includes(name))
+                harnesses.push(name);
+        }
+    }
+    if (harnesses.length === 0)
+        harnesses.push('opencode', 'claude');
+    const rawPm = args.values.pm === undefined ? 'auto' : String(args.values.pm);
+    if (!PM_VALUES.includes(rawPm)) {
+        console.error(`Invalid --pm "${rawPm}" (expected: ${PM_VALUES.join(', ')})`);
+        return 1;
+    }
+    const pm = rawPm;
+    const guard = args.values.guard === true; // opt-in per spec D8
+    const dashboard = args.values['no-dashboard'] !== true;
+    const refreshHook = args.values['no-refresh-hook'] !== true; // default on, opt-out flag
+    const dryRun = args.values['dry-run'] === true;
+    const projectName = args.positionals[0] ?? basename(resolve(cwd));
+    let opencodeConfig;
+    const opencodePath = join(cwd, 'opencode.json');
+    if (existsSync(opencodePath)) {
+        try {
+            opencodeConfig = JSON.parse(readFileSync(opencodePath, 'utf8'));
+        }
+        catch {
+            console.error('error: opencode.json is not valid JSON - fix it manually, then re-run');
+            return 1; // detection failure, consistent with uninstall
+        }
+    }
+    const state = {
+        cwd,
+        detectedPm: detectPackageManager(cwd),
+        hasBacklogConfig: existsSync(join(cwd, 'backlog', 'config.yml')),
+        agentsExists: existsSync(join(cwd, 'AGENTS.md')),
+        claudeMdExists: existsSync(join(cwd, 'CLAUDE.md')),
+        opencodeConfig,
+        pkgExists: existsSync(join(cwd, 'package.json')),
+    };
+    const opts = { projectName, harnesses, pm, guard, dashboard, refreshHook, skipInstall: false };
+    const plan = planInit(state, opts, KIT_VERSION);
+    if (dryRun) {
+        console.log(`dry-run for "${projectName}": ${plan.actions.length} action(s) planned, nothing written`);
+        for (const action of plan.actions)
+            console.log(`  - ${describeAction(action)}`);
+        for (const warning of plan.warnings)
+            console.log(`warning: ${warning}`);
+        maybePrintPolicyWarning();
+        return plan.warnings.length > 0 ? 4 : 0;
+    }
+    try {
+        const result = await executeActions(cwd, plan.actions, {
+            version: KIT_VERSION,
+            projectName,
+            hasBacklogConfig: state.hasBacklogConfig,
+        });
+        const warnings = [...plan.warnings, ...result.warnings];
+        console.log(`super-backlog init complete - planned ${plan.actions.length}, applied ${result.applied}, skipped ${result.skipped}`);
+        for (const warning of warnings)
+            console.log(`warning: ${warning}`);
+        maybePrintPolicyWarning();
+        return warnings.length > 0 ? 4 : 0;
+    }
+    catch (err) {
+        if (err instanceof UpstreamError) {
+            console.error(`error: upstream command failed: ${err.message}`);
+            return 3;
+        }
+        if (err instanceof InvalidJsonError) {
+            // detection failure, not ownership refusal: exit 1 per contract
+            console.error(`error: ${err.message}`);
+            return 1;
+        }
+        if (err instanceof RefusalError) {
+            console.error(`error: ${err.message}`);
+            return 2;
+        }
+        throw err;
+    }
+}