super-backlog 1.3.1 → 1.3.2

package/README.md

@@ -73,7 +73,9 @@ sbl dashboard                   # live Project Dashboard on http://localhost:642
 | `dashboard.html` | generated Project Dashboard | not installed in user projects; generated on demand by `sbl dashboard` |
 | `.git/hooks/pre-commit` | integrity guard hook — only with `--guard` (opt-in) | appended marker block |
 
-Commands: `sbl init` · `sbl models` · `sbl doctor` · `sbl uninstall [--with-backlog]` · `sbl update` · `sbl dashboard [--port <n>] [--no-open]`. See `sbl help` for every flag.
+Commands: `sbl init` · `sbl models` · `sbl doctor` · `sbl uninstall [--with-backlog]` · `sbl update` · `sbl dashboard [--port <n>] [--no-open]` (alias: `sbl db`). See `sbl help` for every flag.
+
+`sbl update` first self-updates a globally installed CLI to the latest npm version and re-runs itself (opt out with `--no-self` or `SBL_SKIP_UPDATE_CHECK`), then refreshes injected files.
 
 ## Model router (opt-in)
 

package/dist/cli.js

@@ -20,7 +20,7 @@ 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   Start the project dashboard server (live-reload)
+  dashboard   Start the project dashboard server (live-reload) (alias: db)
   models      Manage the model router (show, enable, disable, discover)
   doctor      Check the environment (node, PowerShell policy, backlog CLI)
 
@@ -38,7 +38,7 @@ uninstall options:
   --fix-all                       Also remove the global npm package (no prompts)
 
 update options:
-  (none)                          Refreshes injected files, skills, hook; prints upstream versions
+  --no-self                       Skip self-updating the CLI before refreshing
 
 dashboard options:
   --port <n>                      Port for the dashboard server (default: 6428)
@@ -102,12 +102,17 @@ export async function runCli(argv) {
             });
         }
         case 'update': {
-            const parsed = parseArgs({ args: rest, allowPositionals: true, options: {} });
+            const parsed = parseArgs({
+                args: rest,
+                allowPositionals: true,
+                options: { 'no-self': { type: 'boolean' } },
+            });
             return await runUpdate(process.cwd(), {
                 values: parsed.values,
                 positionals: parsed.positionals,
             });
         }
+        case 'db':
         case 'dashboard': {
             const parsed = parseArgs({
                 args: rest,

package/dist/commands/dashboard.js

@@ -11,6 +11,9 @@ import { atomicWrite } from '../lib/atomic.js';
 import { clearHubState, isPidAlive, newHubToken, readHubState, writeHubState } from '../lib/hub-state.js';
 import { projectSlug } from '../lib/slug.js';
 import { KIT_VERSION } from '../lib/version.js';
+/** Max time to wait for an outdated hub to exit after killPid, in 100ms polls. */
+const STOP_POLL_MAX_ATTEMPTS = 50;
+const STOP_POLL_INTERVAL_MS = 100;
 async function regenerateInto(outPath, cwd) {
     const data = collectDashboardData(cwd, { kitVersion: KIT_VERSION });
     atomicWrite(outPath, renderDashboard(data));
@@ -151,6 +154,9 @@ export async function runDashboard(cwd, args, deps = {}) {
     const attach = deps.attach ?? defaultAttach;
     const openBrowser = deps.openBrowser ?? defaultOpenBrowser;
     const pid = (deps.nowPid ?? (() => process.pid))();
+    const isAlive = deps.isAlive ?? isPidAlive;
+    const killPid = deps.killPid ?? ((p) => { process.kill(p); });
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     let slugResult;
     try {
         slugResult = projectSlug(cwd);
@@ -165,22 +171,44 @@ export async function runDashboard(cwd, args, deps = {}) {
     }
     const slug = slugResult.slug;
     const state = readHubState(home);
-    if (state !== null && isPidAlive(state.pid)) {
+    if (state !== null && isAlive(state.pid)) {
         try {
             const status = await attach(`http://127.0.0.1:${state.port}/api/hub/status?token=${encodeURIComponent(state.token)}`, undefined);
             if (status.status === 200) {
-                if (values['port'] !== undefined && port !== state.port) {
-                    console.error(`error: a hub is already running on ${state.port}`);
+                const statusJson = typeof status.json === 'object' && status.json !== null
+                    ? status.json
+                    : undefined;
+                const liveVersion = typeof statusJson?.version === 'string' ? statusJson.version : undefined;
+                const effectiveVersion = liveVersion ?? state.version;
+                if (effectiveVersion === KIT_VERSION) {
+                    if (values['port'] !== undefined && port !== state.port) {
+                        console.error(`error: a hub is already running on ${state.port}`);
+                        return 1;
+                    }
+                    return await attachToHub({
+                        cwd,
+                        port: state.port,
+                        token: state.token,
+                        attach,
+                        openBrowser,
+                        noOpen,
+                    });
+                }
+                console.error(`hub v${effectiveVersion ?? 'unknown'} does not match this CLI (v${KIT_VERSION}) — restarting it`);
+                killPid(state.pid);
+                let dead = !isAlive(state.pid);
+                for (let attempt = 0; !dead && attempt < STOP_POLL_MAX_ATTEMPTS; attempt++) {
+                    await sleep(STOP_POLL_INTERVAL_MS);
+                    dead = !isAlive(state.pid);
+                }
+                if (dead) {
+                    clearHubState(home, state.pid);
+                    // fall through to the fresh-start path below
+                }
+                else {
+                    console.error(`error: could not stop the outdated hub (pid ${state.pid}) — stop it manually and re-run`);
                     return 1;
                 }
-                return await attachToHub({
-                    cwd,
-                    port: state.port,
-                    token: state.token,
-                    attach,
-                    openBrowser,
-                    noOpen,
-                });
             }
         }
         catch {
@@ -206,7 +234,7 @@ export async function runDashboard(cwd, args, deps = {}) {
         console.error(`error: dashboard serve failed (${err instanceof Error ? err.message : String(err)})`);
         return 1;
     }
-    writeHubState(home, { pid, port: hub.port, token });
+    writeHubState(home, { pid, port: hub.port, token, version: KIT_VERSION });
     const result = hub.register({ cwd, file: outPath, regenerate });
     if (!result.ok) {
         await hub.close();

package/dist/commands/update.js

@@ -1,13 +1,86 @@
 // src/commands/update.ts
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import process from 'node:process';
+import spawn from 'cross-spawn';
 import { executeActions, findGitDir, InvalidJsonError, validateJsonFile, RefusalError, UpstreamError } from '../init/execute.js';
 import { planInit } from '../init/planner.js';
 import { GUARD_RE } from '../lib/hooks.js';
 import { detectPackageManager } from '../lib/pm.js';
 import { resolveBacklogBin, runCapture } from '../lib/run.js';
+import { detectInstallKind, runSelfUpdate } from '../lib/self-update.js';
 import { KIT_VERSION } from '../lib/version.js';
+import { fetchLatestVersion } from '../lib/version-check.js';
+/** Longer than the startup version-hint fetch: this one blocks `sbl update` directly. */
+const SELF_UPDATE_FETCH_TIMEOUT_MS = 10000;
+function resolveGlobalRoot(cwd) {
+    const r = runCapture('npm', ['root', '-g'], cwd);
+    if (r.status !== 0)
+        return null;
+    const line = firstLine(r.stdout);
+    return line === '' ? null : line;
+}
+function resolveBinRealPath() {
+    const argvBin = process.argv[1];
+    if (!argvBin)
+        return null;
+    try {
+        return realpathSync(argvBin);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Runs the self-update check/install and, when a new version was installed,
+ * re-execs the new binary once (env-guarded via SBL_SELF_UPDATED) and
+ * returns its exit code. Returns null when the caller should fall through
+ * to the normal refresh (no update available, offline, install failed, or
+ * the update was skipped entirely).
+ */
+async function maybeSelfUpdate(cwd, args, override) {
+    const skip = args.values['no-self'] === true ||
+        Boolean(process.env.SBL_SELF_UPDATED) ||
+        Boolean(process.env.SBL_SKIP_UPDATE_CHECK) ||
+        Boolean(process.env.SBL_FORCE_OFFLINE);
+    if (skip)
+        return null;
+    const binRealPath = override.binRealPath !== undefined ? override.binRealPath : resolveBinRealPath();
+    const globalRoot = override.globalRoot !== undefined ? override.globalRoot : resolveGlobalRoot(cwd);
+    const installKind = binRealPath === null ? 'unknown' : detectInstallKind(binRealPath, cwd, globalRoot);
+    const fetchLatest = override.fetchLatest ?? (() => fetchLatestVersion(SELF_UPDATE_FETCH_TIMEOUT_MS));
+    const npmInstallGlobal = override.npmInstallGlobal ?? ((spec) => runCapture('npm', ['i', '-g', spec], cwd));
+    const result = await runSelfUpdate({
+        installed: KIT_VERSION,
+        fetchLatest,
+        installKind,
+        npmInstallGlobal,
+        log: (line) => console.log(line),
+        warn: (line) => console.warn(`warning: ${line}`),
+    });
+    if (result.kind !== 'updated')
+        return null;
+    // npm rewrites the global package's files in place, so process.argv[1]
+    // still points at a valid path after the install -- re-resolve anyway in
+    // case the realpath target moved (e.g. a version-pinned symlink).
+    const updatedBinPath = override.binRealPath !== undefined ? override.binRealPath : resolveBinRealPath();
+    if (updatedBinPath === null)
+        return null; // can't re-exec without a bin path; fall through on the old version
+    const spawnSelf = override.spawnSelf ??
+        ((binPath, rArgs, execCwd, env) => {
+            const r = spawn.sync(process.execPath, [binPath, 'update', ...rArgs], {
+                cwd: execCwd,
+                stdio: 'inherit',
+                env,
+            });
+            return { status: r.status ?? 1 };
+        });
+    const res = spawnSelf(updatedBinPath, args.positionals, cwd, {
+        ...process.env,
+        SBL_SELF_UPDATED: '1',
+    });
+    return res.status ?? 1;
+}
 const REFRESH_KINDS = new Set([
     'inject-agents-block',
     'write-claude-pointer',
@@ -29,7 +102,10 @@ function guardHookInstalled(cwd) {
         return false;
     return GUARD_RE.test(readFileSync(hookPath, 'utf8'));
 }
-export async function runUpdate(cwd, _args) {
+export async function runUpdate(cwd, args, selfUpdateOverride = {}) {
+    const selfUpdateExitCode = await maybeSelfUpdate(cwd, args, selfUpdateOverride);
+    if (selfUpdateExitCode !== null)
+        return selfUpdateExitCode;
     // Up-front detection-failure check (mirrors uninstall): refuse before mutating anything.
     for (const f of ['package.json', 'opencode.json']) {
         const p = join(cwd, f);
@@ -100,14 +176,17 @@ export async function runUpdate(cwd, _args) {
             warnings.push(`\`${bin} --version\` failed with exit code ${local.status}`);
         }
     }
+    const probePublished = selfUpdateOverride.probePublished ??
+        (() => {
+            // test seam: SBL_FORCE_OFFLINE makes e2e runs take the offline path deterministically
+            if (process.env.SBL_FORCE_OFFLINE)
+                throw new Error('forced offline');
+            const view = runCapture('npm', ['view', 'backlog.md', 'version'], cwd);
+            return view.status === 0 ? firstLine(view.stdout) : null;
+        });
     let published = null;
     try {
-        // test seam: SBL_FORCE_OFFLINE makes e2e runs take the offline path deterministically
-        if (process.env.SBL_FORCE_OFFLINE)
-            throw new Error('forced offline');
-        const view = runCapture('npm', ['view', 'backlog.md', 'version'], cwd);
-        if (view.status === 0)
-            published = firstLine(view.stdout);
+        published = probePublished();
     }
     catch {
         published = null;

package/dist/dashboard/hub.js

@@ -166,7 +166,7 @@ export async function startHubServer(opts) {
                 sendText(res, 401, 'unauthorized');
                 return;
             }
-            sendJson(res, 200, { pid: process.pid, port });
+            sendJson(res, 200, { pid: process.pid, port, version: KIT_VERSION });
             return;
         }
         if (pathname === '/api/hub/register' && method === 'POST') {

package/dist/lib/hub-state.js

@@ -16,8 +16,8 @@ export function readHubState(home) {
             typeof parsed.token !== 'string') {
             return null;
         }
-        const { pid, port, token } = parsed;
-        return { pid, port, token };
+        const { pid, port, token, version } = parsed;
+        return typeof version === 'string' ? { pid, port, token, version } : { pid, port, token };
     }
     catch {
         return null;

package/dist/lib/self-update.js

@@ -0,0 +1,57 @@
+// src/lib/self-update.ts
+import { join } from 'node:path';
+import process from 'node:process';
+import { isNewerVersion } from './version-check.js';
+/**
+ * Normalizes separators for prefix comparison and, on win32, case as well:
+ * `npm root -g` and `realpathSync` can disagree on drive-letter/path casing
+ * (`C:\` vs `c:\`) even for the same install, and Windows paths are
+ * case-insensitive anyway, so comparing case-sensitively there would
+ * misclassify a real global install as `unknown`. Takes an optional
+ * `caseInsensitive` override (default: `process.platform === 'win32'`) so
+ * the function stays pure and testable for both platforms' behavior.
+ */
+function normalizeForCompare(p, caseInsensitive) {
+    const withForwardSlashes = p.replace(/\\/g, '/');
+    return caseInsensitive ? withForwardSlashes.toLowerCase() : withForwardSlashes;
+}
+function isUnder(path, root) {
+    return path === root || path.startsWith(`${root}/`);
+}
+/**
+ * Classifies the running binary's real path as a local (project
+ * node_modules) install, a global npm install, or unknown (treated the
+ * same as local: never mutated, hint only). Pure function -- callers
+ * gather binRealPath (from `process.argv[1]` + `realpathSync`) and
+ * globalRoot (from `npm root -g`, captured once, null on failure).
+ */
+export function detectInstallKind(binRealPath, cwd, globalRoot, caseInsensitive = process.platform === 'win32') {
+    const bin = normalizeForCompare(binRealPath, caseInsensitive);
+    const localRoot = normalizeForCompare(join(cwd, 'node_modules'), caseInsensitive);
+    if (isUnder(bin, localRoot))
+        return 'local';
+    if (globalRoot !== null && isUnder(bin, normalizeForCompare(globalRoot, caseInsensitive)))
+        return 'global';
+    return 'unknown';
+}
+export async function runSelfUpdate(deps) {
+    const latest = await deps.fetchLatest();
+    if (latest === null) {
+        deps.warn('could not check for a newer super-backlog (offline?)');
+        return { kind: 'unavailable' };
+    }
+    if (!isNewerVersion(latest, deps.installed)) {
+        return { kind: 'current' };
+    }
+    if (deps.installKind !== 'global') {
+        deps.log(`a newer super-backlog (${latest}) is available; update the dependency yourself, e.g. npm i -D super-backlog@${latest}`);
+        return { kind: 'skipped-local', latest };
+    }
+    const result = deps.npmInstallGlobal(`super-backlog@${latest}`);
+    if (result.status === 0) {
+        deps.log(`self-updated to ${latest}, re-running update...`);
+        return { kind: 'updated', latest };
+    }
+    deps.warn(`self-update to ${latest} failed (npm install exited ${String(result.status)}); continuing with ${deps.installed}`);
+    return { kind: 'failed', latest };
+}

package/dist/lib/version-check.js

@@ -57,7 +57,8 @@ function isStale(checkedAt, now) {
 function unrefStream(stream) {
     stream?.unref?.();
 }
-export async function defaultFetchLatest() {
+/** Queries the npm registry for the latest published version, racing a timeout. */
+export async function fetchLatestVersion(timeoutMs = FETCH_TIMEOUT_MS) {
     const work = new Promise((resolvePromise) => {
         let child;
         try {
@@ -89,7 +90,7 @@ export async function defaultFetchLatest() {
     });
     let timer;
     const timeout = new Promise((resolveTimeout) => {
-        timer = setTimeout(() => resolveTimeout(null), FETCH_TIMEOUT_MS);
+        timer = setTimeout(() => resolveTimeout(null), timeoutMs);
         timer.unref();
     });
     try {
@@ -103,12 +104,15 @@ export async function defaultFetchLatest() {
             clearTimeout(timer);
     }
 }
+export async function defaultFetchLatest() {
+    return fetchLatestVersion(FETCH_TIMEOUT_MS);
+}
 export async function applyVersionHint(installed, deps) {
     if (deps.env.SBL_SKIP_UPDATE_CHECK)
         return;
     const cache = readCache(deps.home);
     if (cache && isNewerVersion(cache.latest, installed)) {
-        deps.log(`super-backlog ${cache.latest} is available (installed ${installed}). Update: npm i -g super-backlog`);
+        deps.log(`super-backlog ${cache.latest} is available (installed ${installed}). Update: sbl update (or npm i -g super-backlog)`);
     }
     if (!cache || isStale(cache.checkedAt, deps.now())) {
         void deps

package/dist/templates/dashboard.html

@@ -659,7 +659,7 @@
     var upd = el('button', 'update-badge');
     upd.type = 'button';
     upd.appendChild(el('span', 'cmd-title', 'v' + data.latestVersion + ' available'));
-    upd.setAttribute('data-tip', 'Update: npm i -g super-backlog (click to copy)');
+    upd.setAttribute('data-tip', 'Update: run sbl update (click copies npm i -g super-backlog)');
     upd.addEventListener('click', function () { copyCommand(upd, 'npm i -g super-backlog'); });
     sideVersion.appendChild(upd);
   }

package/package.json

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