super-backlog 0.6.0 → 0.7.0

package/dist/cli.js

@@ -29,10 +29,12 @@ init options:
   --no-models                     Explicitly opt out of the model router
   --no-dashboard                  Skip generating the project dashboard
   --no-refresh-hook               Skip the post-commit dashboard freshness hook
+  --fix-all                       Repair environment problems automatically (no prompts)
   --dry-run                       Show what would be done without writing anything
 
 uninstall options:
   --with-backlog                  Also permanently delete the backlog/ data directory
+  --fix-all                       Also remove the global npm package (no prompts)
 
 update options:
   (none)                          Refreshes injected files, skills, hook; prints upstream versions
@@ -75,6 +77,7 @@ async function main(argv) {
                     'no-models': { type: 'boolean' },
                     'no-dashboard': { type: 'boolean' },
                     'no-refresh-hook': { type: 'boolean' },
+                    'fix-all': { type: 'boolean' },
                     'dry-run': { type: 'boolean' },
                 },
             });
@@ -87,7 +90,7 @@ async function main(argv) {
             const parsed = parseArgs({
                 args: rest,
                 allowPositionals: true,
-                options: { 'with-backlog': { type: 'boolean' } },
+                options: { 'with-backlog': { type: 'boolean' }, 'fix-all': { type: 'boolean' } },
             });
             return runUninstall(process.cwd(), {
                 values: parsed.values,

package/dist/commands/init.js

@@ -1,11 +1,16 @@
 // src/commands/init.ts
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
+import process from 'node:process';
 import { detectPackageManager } from '../lib/pm.js';
 import { getEffectiveExecutionPolicy, isBlockingExecutionPolicy, policyWarningLines, } from '../lib/powershell.js';
+import { runPreflight } from '../lib/preflight.js';
+import { runDoctor } from './doctor.js';
 import { KIT_VERSION } from '../lib/version.js';
 import { executeActions, InvalidJsonError, RefusalError, UpstreamError } from '../init/execute.js';
 import { planInit } from '../init/planner.js';
+/** Units that make sense before init; install-type fixes belong to init itself. */
+const INIT_PREFLIGHT_UNITS = ['node-version', 'execution-policy', 'npm-command'];
 const HARNESS_VALUES = ['opencode', 'claude'];
 const PM_VALUES = ['auto', 'npm', 'pnpm', 'bun', 'skip'];
 function isHarness(value) {
@@ -43,7 +48,23 @@ function maybePrintPolicyWarning() {
         }
     }
 }
-export async function runInit(cwd, args) {
+/** Synchronous Y/n prompt; defaults to "no" when stdin is not interactive. */
+export function promptYesNo(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    process.stdout.write(`${question} [y/N] `);
+    const buf = Buffer.alloc(64);
+    let n = 0;
+    try {
+        n = readSync(process.stdin.fd, buf, 0, 64, null);
+    }
+    catch {
+        return false;
+    }
+    const answer = buf.subarray(0, n).toString('utf8').trim().toLowerCase();
+    return answer === 'y' || answer === 'yes';
+}
+export async function runInit(cwd, args, deps = {}) {
     const harnesses = [];
     const rawHarnesses = args.values.harness;
     const listed = Array.isArray(rawHarnesses)
@@ -109,6 +130,25 @@ export async function runInit(cwd, args) {
         maybePrintPolicyWarning();
         return plan.warnings.length > 0 ? 4 : 0;
     }
+    const preflightRun = deps.preflight ?? runPreflight;
+    const preflightResult = preflightRun(cwd, {
+        units: INIT_PREFLIGHT_UNITS,
+        fixAll: args.values['fix-all'] === true,
+        confirm: deps.confirm ?? promptYesNo,
+        log: (line) => console.log(line),
+    });
+    const failed = preflightResult.reports.filter((r) => r.status === 'failed');
+    if (failed.length > 0) {
+        for (const f of failed) {
+            console.error(`error: preflight fix failed (${f.id}): ${f.detail}`);
+            if (f.manualCommand !== undefined) {
+                console.error(`       fix it manually: ${f.manualCommand}`);
+            }
+        }
+        return 1;
+    }
+    // needs-manual reports (declined or non-interactive consent) are surfaced with
+    // their manual command by preflight but must not change the exit code.
     try {
         const result = await executeActions(cwd, plan.actions, {
             version: KIT_VERSION,
@@ -119,8 +159,14 @@ export async function runInit(cwd, args) {
         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;
+        const doctor = deps.doctor ?? ((c) => runDoctor(c));
+        console.log('post-install verification (doctor):');
+        const doctorCode = doctor(cwd);
+        const unverified = doctorCode !== 0;
+        if (unverified) {
+            console.log('warning: post-install verification reported warnings (see doctor output above)');
+        }
+        return warnings.length > 0 || unverified ? 4 : 0;
     }
     catch (err) {
         if (err instanceof UpstreamError) {

package/dist/commands/uninstall.js

@@ -1,14 +1,17 @@
 // src/commands/uninstall.ts
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
+import process from 'node:process';
 import { findGitDir, POINTER_HEADING_RE } from '../init/execute.js';
 import { atomicWrite } from '../lib/atomic.js';
-import { removeGuardHook, removeRefreshHook } from '../lib/hooks.js';
+import { GUARD_RE, REFRESH_RE, removeGuardHook, removeRefreshHook } from '../lib/hooks.js';
 import { stripOwned } from '../lib/markers.js';
 import { PLUGIN_SPEC } from '../lib/opencode.js';
 import { isOwnedSkillFile } from '../lib/ownership.js';
 import { WANTED_SCRIPTS } from '../lib/pkgjson.js';
 import { uninstallModelRouter } from '../models/uninstall.js';
+import { promptYesNo } from './init.js';
 const OWNED_SKILL_DIRS = [
     '.opencode/skill/spec-to-backlog',
     '.opencode/skill/backlog-status-report',
@@ -133,9 +136,90 @@ function uninstallPluginEntry(cwd, config, report) {
         report.push({ verdict: 'skipped', label: 'opencode.json plugin entry (no kit entry)' });
     }
 }
-export function runUninstall(cwd, args) {
+/** Probes for kit-owned artifacts that survived the uninstall. */
+export function verifyRemnants(cwd) {
+    const remnants = [];
+    const agentsPath = join(cwd, 'AGENTS.md');
+    try {
+        if (existsSync(agentsPath) && stripOwned(readFileSync(agentsPath, 'utf8')).removed) {
+            remnants.push('AGENTS.md managed block');
+        }
+    }
+    catch {
+        remnants.push('AGENTS.md (unreadable)');
+    }
+    const claudePath = join(cwd, 'CLAUDE.md');
+    try {
+        if (existsSync(claudePath) && POINTER_HEADING_RE.test(readFileSync(claudePath, 'utf8'))) {
+            remnants.push('CLAUDE.md pointer section');
+        }
+    }
+    catch {
+        remnants.push('CLAUDE.md (unreadable)');
+    }
+    for (const rel of OWNED_SKILL_DIRS) {
+        const skillMd = join(cwd, ...rel.split('/'), 'SKILL.md');
+        if (existsSync(skillMd) && isOwnedSkillFile(readFileSync(skillMd, 'utf8'))) {
+            remnants.push(`${rel}/`);
+        }
+    }
+    const ocPath = join(cwd, 'opencode.json');
+    if (existsSync(ocPath)) {
+        try {
+            const config = JSON.parse(readFileSync(ocPath, 'utf8'));
+            const raw = config.plugin;
+            const list = Array.isArray(raw) ? raw : raw === undefined ? [] : [raw];
+            if (list.some((entry) => typeof entry === 'string' && entry === PLUGIN_SPEC)) {
+                remnants.push('opencode.json plugin entry');
+            }
+        }
+        catch {
+            // unparsable config was already reported during validation
+        }
+    }
+    const gitDir = findGitDir(cwd);
+    if (gitDir) {
+        const pre = join(gitDir, 'hooks', 'pre-commit');
+        if (existsSync(pre) && GUARD_RE.test(readFileSync(pre, 'utf8'))) {
+            remnants.push('git pre-commit guard hook');
+        }
+        const post = join(gitDir, 'hooks', 'post-commit');
+        if (existsSync(post) && REFRESH_RE.test(readFileSync(post, 'utf8'))) {
+            remnants.push('git post-commit dashboard-refresh hook');
+        }
+    }
+    const dashboardPath = join(cwd, 'dashboard.html');
+    if (existsSync(dashboardPath) && isKitDashboard(readFileSync(dashboardPath, 'utf8'))) {
+        remnants.push('dashboard.html');
+    }
+    return remnants;
+}
+function defaultRemoveGlobal() {
+    const cmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const r = spawnSync(cmd, ['uninstall', '-g', 'super-backlog'], {
+        encoding: 'utf8',
+        windowsHide: true,
+        shell: process.platform === 'win32',
+    });
+    if (r.error)
+        return 1;
+    return r.status ?? 1;
+}
+export function runUninstall(cwd, args, deps = {}) {
     const withBacklog = args.values['with-backlog'] === true;
+    const fixAll = args.values['fix-all'] === true;
     const report = [];
+    // A failing step must not abort the remaining steps: collect it as an error
+    // line and continue. The JSON validation above stays fail-fast on purpose.
+    const attempt = (label, fn) => {
+        try {
+            fn();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            report.push({ verdict: 'error', label: `${label} (${msg})` });
+        }
+    };
     // validate both JSON files up front - no mutation happens unless parsing succeeds
     let pkg = null;
     const pkgPath = join(cwd, 'package.json');
@@ -160,113 +244,133 @@ export function runUninstall(cwd, args) {
         }
     }
     const agentsPath = join(cwd, 'AGENTS.md');
-    if (!existsSync(agentsPath)) {
-        report.push({ verdict: 'skipped', label: 'AGENTS.md managed block (file not found)' });
-    }
-    else {
-        const stripped = stripOwned(readFileSync(agentsPath, 'utf8'));
-        if (stripped.removed) {
-            atomicWrite(agentsPath, stripped.content);
-            report.push({ verdict: 'removed', label: 'AGENTS.md managed block' });
+    attempt('AGENTS.md managed block', () => {
+        if (!existsSync(agentsPath)) {
+            report.push({ verdict: 'skipped', label: 'AGENTS.md managed block (file not found)' });
         }
         else {
-            report.push({ verdict: 'skipped', label: 'AGENTS.md managed block (none found)' });
+            const stripped = stripOwned(readFileSync(agentsPath, 'utf8'));
+            if (stripped.removed) {
+                atomicWrite(agentsPath, stripped.content);
+                report.push({ verdict: 'removed', label: 'AGENTS.md managed block' });
+            }
+            else {
+                report.push({ verdict: 'skipped', label: 'AGENTS.md managed block (none found)' });
+            }
         }
-    }
+    });
     const claudePath = join(cwd, 'CLAUDE.md');
-    if (!existsSync(claudePath)) {
-        report.push({ verdict: 'skipped', label: 'CLAUDE.md pointer section (file not found)' });
-    }
-    else {
-        const res = removePointerSection(readFileSync(claudePath, 'utf8'));
-        if (res.removed) {
-            atomicWrite(claudePath, res.content);
-            report.push({ verdict: 'removed', label: 'CLAUDE.md pointer section' });
+    attempt('CLAUDE.md pointer section', () => {
+        if (!existsSync(claudePath)) {
+            report.push({ verdict: 'skipped', label: 'CLAUDE.md pointer section (file not found)' });
         }
         else {
-            report.push({ verdict: 'skipped', label: 'CLAUDE.md pointer section (none found)' });
+            const res = removePointerSection(readFileSync(claudePath, 'utf8'));
+            if (res.removed) {
+                atomicWrite(claudePath, res.content);
+                report.push({ verdict: 'removed', label: 'CLAUDE.md pointer section' });
+            }
+            else {
+                report.push({ verdict: 'skipped', label: 'CLAUDE.md pointer section (none found)' });
+            }
         }
-    }
+    });
     for (const rel of OWNED_SKILL_DIRS) {
-        const abs = join(cwd, ...rel.split('/'));
-        const skillMd = join(abs, 'SKILL.md');
-        if (!existsSync(skillMd)) {
-            report.push(existsSync(abs)
-                ? { verdict: 'kept', label: `${rel}/ (no SKILL.md - left untouched)` }
-                : { verdict: 'skipped', label: `${rel}/ (not found)` });
+        attempt(`${rel}/`, () => {
+            const abs = join(cwd, ...rel.split('/'));
+            const skillMd = join(abs, 'SKILL.md');
+            if (!existsSync(skillMd)) {
+                report.push(existsSync(abs)
+                    ? { verdict: 'kept', label: `${rel}/ (no SKILL.md - left untouched)` }
+                    : { verdict: 'skipped', label: `${rel}/ (not found)` });
+            }
+            else if (isOwnedSkillFile(readFileSync(skillMd, 'utf8'))) {
+                rmSync(abs, { recursive: true, force: true });
+                report.push({ verdict: 'removed', label: `${rel}/` });
+            }
+            else {
+                report.push({
+                    verdict: 'kept',
+                    label: `${rel}/ (SKILL.md not managed by super-backlog)`,
+                });
+            }
+        });
+    }
+    attempt('package.json scripts/devDependencies', () => {
+        uninstallPackageJson(cwd, pkg, withBacklog, report);
+    });
+    attempt('opencode.json plugin entry', () => {
+        uninstallPluginEntry(cwd, opencodeConfig, report);
+    });
+    const gitDir = findGitDir(cwd);
+    attempt('git pre-commit guard hook', () => {
+        if (!gitDir) {
+            report.push({ verdict: 'skipped', label: 'git pre-commit guard hook (no .git directory)' });
+        }
+        else if (!existsSync(join(gitDir, 'hooks', 'pre-commit'))) {
+            report.push({ verdict: 'skipped', label: 'git pre-commit guard hook (not installed)' });
         }
-        else if (isOwnedSkillFile(readFileSync(skillMd, 'utf8'))) {
-            rmSync(abs, { recursive: true, force: true });
-            report.push({ verdict: 'removed', label: `${rel}/` });
+        else if (removeGuardHook(gitDir)) {
+            report.push({ verdict: 'removed', label: 'git pre-commit guard hook' });
         }
         else {
             report.push({
                 verdict: 'kept',
-                label: `${rel}/ (SKILL.md not managed by super-backlog)`,
+                label: 'git pre-commit hook (no super-backlog guard block)',
             });
         }
-    }
-    uninstallPackageJson(cwd, pkg, withBacklog, report);
-    uninstallPluginEntry(cwd, opencodeConfig, report);
-    const gitDir = findGitDir(cwd);
-    if (!gitDir) {
-        report.push({ verdict: 'skipped', label: 'git pre-commit guard hook (no .git directory)' });
-    }
-    else if (!existsSync(join(gitDir, 'hooks', 'pre-commit'))) {
-        report.push({ verdict: 'skipped', label: 'git pre-commit guard hook (not installed)' });
-    }
-    else if (removeGuardHook(gitDir)) {
-        report.push({ verdict: 'removed', label: 'git pre-commit guard hook' });
-    }
-    else {
-        report.push({
-            verdict: 'kept',
-            label: 'git pre-commit hook (no super-backlog guard block)',
-        });
-    }
-    if (!gitDir) {
-        report.push({ verdict: 'skipped', label: 'git post-commit dashboard-refresh hook (no .git directory)' });
-    }
-    else if (!existsSync(join(gitDir, 'hooks', 'post-commit'))) {
-        report.push({ verdict: 'skipped', label: 'git post-commit dashboard-refresh hook (not installed)' });
-    }
-    else if (removeRefreshHook(gitDir)) {
-        report.push({ verdict: 'removed', label: 'git post-commit dashboard-refresh hook' });
-    }
-    else {
-        report.push({
-            verdict: 'kept',
-            label: 'git post-commit hook (no super-backlog dashboard-refresh block)',
-        });
-    }
+    });
+    attempt('git post-commit dashboard-refresh hook', () => {
+        if (!gitDir) {
+            report.push({ verdict: 'skipped', label: 'git post-commit dashboard-refresh hook (no .git directory)' });
+        }
+        else if (!existsSync(join(gitDir, 'hooks', 'post-commit'))) {
+            report.push({ verdict: 'skipped', label: 'git post-commit dashboard-refresh hook (not installed)' });
+        }
+        else if (removeRefreshHook(gitDir)) {
+            report.push({ verdict: 'removed', label: 'git post-commit dashboard-refresh hook' });
+        }
+        else {
+            report.push({
+                verdict: 'kept',
+                label: 'git post-commit hook (no super-backlog dashboard-refresh block)',
+            });
+        }
+    });
     const dashboardPath = join(cwd, 'dashboard.html');
-    if (!existsSync(dashboardPath)) {
-        report.push({ verdict: 'skipped', label: 'dashboard.html (not found)' });
-    }
-    else if (isKitDashboard(readFileSync(dashboardPath, 'utf8'))) {
-        rmSync(dashboardPath);
-        report.push({ verdict: 'removed', label: 'dashboard.html' });
-    }
-    else {
-        report.push({ verdict: 'kept', label: 'dashboard.html (not generated by super-backlog)' });
-    }
+    attempt('dashboard.html', () => {
+        if (!existsSync(dashboardPath)) {
+            report.push({ verdict: 'skipped', label: 'dashboard.html (not found)' });
+        }
+        else if (isKitDashboard(readFileSync(dashboardPath, 'utf8'))) {
+            rmSync(dashboardPath);
+            report.push({ verdict: 'removed', label: 'dashboard.html' });
+        }
+        else {
+            report.push({ verdict: 'kept', label: 'dashboard.html (not generated by super-backlog)' });
+        }
+    });
     let dataDeleted = false;
     const backlogDir = join(cwd, 'backlog');
-    if (!existsSync(backlogDir)) {
-        report.push({ verdict: 'skipped', label: 'backlog/ (not found)' });
-    }
-    else if (withBacklog) {
-        rmSync(backlogDir, { recursive: true, force: true });
-        dataDeleted = true;
-        report.push({ verdict: 'removed', label: 'backlog/ (project task data)' });
-    }
-    else {
-        report.push({
-            verdict: 'kept',
-            label: 'backlog/ (project task data preserved - pass --with-backlog to delete)',
-        });
-    }
-    uninstallModelRouter(cwd, report);
+    attempt('backlog/ (project task data)', () => {
+        if (!existsSync(backlogDir)) {
+            report.push({ verdict: 'skipped', label: 'backlog/ (not found)' });
+        }
+        else if (withBacklog) {
+            rmSync(backlogDir, { recursive: true, force: true });
+            dataDeleted = true;
+            report.push({ verdict: 'removed', label: 'backlog/ (project task data)' });
+        }
+        else {
+            report.push({
+                verdict: 'kept',
+                label: 'backlog/ (project task data preserved - pass --with-backlog to delete)',
+            });
+        }
+    });
+    attempt('model router', () => {
+        uninstallModelRouter(cwd, report);
+    });
     console.log('super-backlog uninstall');
     for (const line of report)
         console.log(`${line.verdict}: ${line.label}`);
@@ -277,5 +381,34 @@ export function runUninstall(cwd, args) {
         console.log('was permanently removed. This cannot be undone.');
         console.log('============================================================');
     }
-    return 0;
+    // verification pass: prove nothing kit-owned survives (or say what does)
+    const remnants = verifyRemnants(cwd);
+    if (remnants.length === 0) {
+        console.log('verification: clean');
+    }
+    else {
+        console.log('verification: leftover kit artifacts');
+        for (const remnant of remnants)
+            console.log(`  - ${remnant}`);
+    }
+    // global self-removal as the very last step
+    const removeGlobal = deps.removeGlobal ?? defaultRemoveGlobal;
+    const confirm = deps.confirm ?? promptYesNo;
+    let removalFailed = false;
+    if (fixAll || confirm('Remove the global super-backlog npm package as well?')) {
+        const status = removeGlobal();
+        if (status !== 0) {
+            removalFailed = true;
+            console.log('error: global package removal failed');
+            console.log('       manual: npm uninstall -g super-backlog');
+        }
+        else {
+            console.log('removed: global npm package super-backlog');
+        }
+    }
+    else {
+        console.log('note: global npm package kept - remove it with: npm uninstall -g super-backlog');
+    }
+    const hadError = report.some((line) => line.verdict === 'error');
+    return hadError || removalFailed ? 1 : 0;
 }

package/dist/lib/preflight.js

@@ -0,0 +1,233 @@
+// src/lib/preflight.ts
+// Check -> Fix -> Verify units that repair a broken super-backlog environment.
+// System-changing fixes (node install, execution policy) require consent or fixAll;
+// safe fixes run unconditionally. Every fix is verified and reports a manual
+// fallback command on failure.
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import process from 'node:process';
+import { getEffectiveExecutionPolicy, isBlockingExecutionPolicy, } from './powershell.js';
+import { resolveBacklogBin } from './run.js';
+const defaultExecutor = (cmd, args) => {
+    // shell on win32 — .cmd/.ps1 shims (npm.cmd etc.) are not directly executable.
+    // Safe only because callers pass constant args; never pass user input here.
+    const r = spawnSync(cmd, args, {
+        encoding: 'utf8',
+        windowsHide: true,
+        shell: process.platform === 'win32',
+    });
+    if (r.error)
+        return { status: null, stdout: '', stderr: String(r.error.message) };
+    return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+};
+function parseMajor(version) {
+    if (version === null)
+        return null;
+    const major = Number(version.replace(/^v/, '').split('.')[0]);
+    return Number.isNaN(major) ? null : major;
+}
+function allowed(ctx, question) {
+    if (ctx.fixAll)
+        return true;
+    return ctx.confirm?.(question) === true;
+}
+function checkNodeVersion(ctx) {
+    const id = 'node-version';
+    const version = ctx.getNodeVersion();
+    const major = parseMajor(version);
+    if (major !== null && major >= 20) {
+        return { id, status: 'ok', detail: `node v${version} (>= 20)` };
+    }
+    const installArgs = ctx.platform === 'win32'
+        ? { cmd: 'winget', args: ['install', '-e', '--id', 'OpenJS.NodeJS', '--accept-source-agreements', '--accept-package-agreements'] }
+        : { cmd: 'brew', args: ['install', 'node'] };
+    const manual = `${installArgs.cmd} ${installArgs.args.join(' ')}`;
+    if (!allowed(ctx, `Node.js >= 20 is required (found ${version ?? 'none'}). Install it now?`)) {
+        return { id, status: 'needs-manual', detail: `node ${version ?? 'not found'} is too old or missing`, manualCommand: manual };
+    }
+    const r = ctx.executor(installArgs.cmd, installArgs.args);
+    if (r.status !== 0) {
+        return { id, status: 'failed', detail: `node install failed: ${r.stderr.trim() || 'unknown error'}`, manualCommand: manual };
+    }
+    const after = parseMajor(ctx.getNodeVersion());
+    if (after !== null && after >= 20) {
+        return { id, status: 'fixed', detail: 'node installed via package manager' };
+    }
+    return {
+        id,
+        status: 'failed',
+        detail: 'node still not >= 20 after install (open a new terminal and retry)',
+        manualCommand: 'install Node.js >= 20 manually: https://nodejs.org/en/download/',
+    };
+}
+function checkExecutionPolicy(ctx) {
+    const id = 'execution-policy';
+    if (ctx.platform !== 'win32') {
+        return { id, status: 'skipped', detail: 'not Windows' };
+    }
+    const policy = ctx.getPolicy();
+    if (policy === null) {
+        return { id, status: 'skipped', detail: 'policy not detectable' };
+    }
+    if (!isBlockingExecutionPolicy(policy)) {
+        return { id, status: 'ok', detail: `execution policy: ${policy}` };
+    }
+    const manual = 'Set-ExecutionPolicy -Scope CurrentUser RemoteSigned';
+    if (!allowed(ctx, `PowerShell execution policy "${policy}" blocks npm/npx/sbl shims. Set CurrentUser to RemoteSigned?`)) {
+        return { id, status: 'needs-manual', detail: `PowerShell execution policy "${policy}" blocks .ps1 shims`, manualCommand: manual };
+    }
+    const r = ctx.executor('powershell.exe', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        `${manual} -Force`,
+    ]);
+    if (r.status !== 0) {
+        return { id, status: 'failed', detail: `Set-ExecutionPolicy failed: ${r.stderr.trim() || 'unknown error'}`, manualCommand: manual };
+    }
+    const after = ctx.getPolicy();
+    if (!isBlockingExecutionPolicy(after)) {
+        return { id, status: 'fixed', detail: 'execution policy set to RemoteSigned (CurrentUser)' };
+    }
+    return { id, status: 'failed', detail: `policy still "${after ?? 'unknown'}" after fix`, manualCommand: manual };
+}
+function checkNpmCommand(ctx) {
+    const id = 'npm-command';
+    const probe = ctx.executor('npm', ['--version']);
+    if (probe.status === 0) {
+        ctx.npmCmd = 'npm';
+        return { id, status: 'ok', detail: `npm ${probe.stdout.trim()}` };
+    }
+    if (ctx.platform === 'win32') {
+        const fallback = ctx.executor('npm.cmd', ['--version']);
+        if (fallback.status === 0) {
+            ctx.npmCmd = 'npm.cmd';
+            return { id, status: 'fixed', detail: 'npm not directly callable; using npm.cmd shim' };
+        }
+    }
+    return {
+        id,
+        status: 'failed',
+        detail: 'npm is not callable',
+        manualCommand: 'reinstall Node.js (bundles npm): https://nodejs.org/en/download/',
+    };
+}
+function checkPartialInstall(ctx) {
+    const id = 'partial-install';
+    const pkgJson = join(ctx.cwd, 'package.json');
+    if (!ctx.exists(pkgJson)) {
+        return { id, status: 'skipped', detail: 'no package.json (init installs upstream itself)' };
+    }
+    const pkgDir = join(ctx.cwd, 'node_modules', 'super-backlog');
+    const shim = join(ctx.cwd, 'node_modules', '.bin', ctx.platform === 'win32' ? 'sbl.cmd' : 'sbl');
+    if (!ctx.exists(pkgDir) || ctx.exists(shim)) {
+        return { id, status: 'ok', detail: 'local install consistent (or absent)' };
+    }
+    const r = ctx.executor(ctx.npmCmd, ['install']);
+    if (r.status !== 0) {
+        return { id, status: 'failed', detail: `npm install failed: ${r.stderr.trim() || 'unknown error'}`, manualCommand: 'npm install' };
+    }
+    if (ctx.exists(shim)) {
+        return { id, status: 'fixed', detail: 'repaired partial install (missing .bin shim restored)' };
+    }
+    return { id, status: 'failed', detail: 'partial install persists after npm install', manualCommand: 'npm install' };
+}
+function checkBacklogBin(ctx) {
+    const id = 'backlog-bin';
+    if (!ctx.exists(join(ctx.cwd, 'package.json'))) {
+        return { id, status: 'skipped', detail: 'no package.json (init installs upstream itself)' };
+    }
+    const found = ctx.resolveBacklog(ctx.cwd);
+    if (found !== null) {
+        return { id, status: 'ok', detail: `backlog CLI at ${found}` };
+    }
+    const r = ctx.executor(ctx.npmCmd, ['install']);
+    if (r.status !== 0) {
+        return { id, status: 'failed', detail: `npm install failed: ${r.stderr.trim() || 'unknown error'}`, manualCommand: 'npm install' };
+    }
+    const after = ctx.resolveBacklog(ctx.cwd);
+    if (after !== null) {
+        return { id, status: 'fixed', detail: 'backlog CLI restored via npm install' };
+    }
+    return { id, status: 'failed', detail: 'backlog CLI still not resolvable after npm install', manualCommand: 'npm install' };
+}
+function checkSblOnPath(ctx) {
+    const id = 'sbl-on-path';
+    if (ctx.lookupCommand('sbl') !== null) {
+        return { id, status: 'ok', detail: 'sbl resolvable on PATH' };
+    }
+    const binProbe = ctx.executor(ctx.npmCmd, ['bin', '-g']);
+    if (binProbe.status !== 0 || binProbe.stdout.trim() === '') {
+        return {
+            id,
+            status: 'failed',
+            detail: 'sbl not on PATH and npm global bin directory could not be determined',
+            manualCommand: 'run "npm bin -g", add the printed directory to your PATH, open a new terminal',
+        };
+    }
+    const binDir = binProbe.stdout.trim().split(/\r?\n/)[0];
+    const current = ctx.getEnv('PATH') ?? '';
+    ctx.setEnv('PATH', current === '' ? binDir : `${binDir}${delimiter}${current}`);
+    if (ctx.lookupCommand('sbl') !== null) {
+        return { id, status: 'fixed', detail: `session PATH refreshed with ${binDir}` };
+    }
+    return {
+        id,
+        status: 'failed',
+        detail: `sbl still not resolvable after adding ${binDir} to the session PATH`,
+        manualCommand: `add "${binDir}" to your user PATH permanently and open a new terminal`,
+    };
+}
+export function runPreflight(cwd, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const executor = deps.executor ?? defaultExecutor;
+    const ctx = {
+        platform,
+        cwd,
+        executor,
+        getNodeVersion: deps.getNodeVersion ?? (() => process.versions.node),
+        getPolicy: deps.getPolicy ??
+            (() => getEffectiveExecutionPolicy({ platform, executor })),
+        lookupCommand: deps.lookupCommand ??
+            ((name) => {
+                const probe = executor(platform === 'win32' ? 'where' : 'which', [name]);
+                if (probe.status !== 0)
+                    return null;
+                const first = probe.stdout.split(/\r?\n/).find(Boolean);
+                if (!first)
+                    return null;
+                return first.trim().replace(/\.ps1$/i, '.cmd');
+            }),
+        setEnv: deps.setEnv ?? ((name, value) => { process.env[name] = value; }),
+        getEnv: deps.getEnv ?? ((name) => process.env[name] ?? null),
+        resolveBacklog: deps.resolveBacklog ?? resolveBacklogBin,
+        exists: deps.exists ?? existsSync,
+        log: deps.log ?? ((line) => console.log(line)),
+        confirm: deps.confirm,
+        fixAll: deps.fixAll ?? false,
+        npmCmd: platform === 'win32' ? 'npm.cmd' : 'npm',
+    };
+    const unitNames = [
+        ['node-version', checkNodeVersion],
+        ['execution-policy', checkExecutionPolicy],
+        ['npm-command', checkNpmCommand],
+        ['partial-install', checkPartialInstall],
+        ['backlog-bin', checkBacklogBin],
+        ['sbl-on-path', checkSblOnPath],
+    ];
+    const units = deps.units === undefined
+        ? unitNames.map(([, fn]) => fn)
+        : unitNames.filter(([name]) => deps.units.includes(name)).map(([, fn]) => fn);
+    const reports = [];
+    for (const unit of units) {
+        const report = unit(ctx);
+        reports.push(report);
+        ctx.log(`[${report.status}] ${report.id}: ${report.detail}`);
+        if (report.manualCommand !== undefined && report.status !== 'ok') {
+            ctx.log(`       manual: ${report.manualCommand}`);
+        }
+    }
+    const ok = reports.every((r) => r.status === 'ok' || r.status === 'fixed' || r.status === 'skipped');
+    return { reports, ok };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-backlog",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "One command to equip any project with Backlog.md + Superpowers, plus a Project Dashboard.",
   "license": "MIT",
   "repository": {