super-backlog 1.1.0 → 1.1.1

package/README.md

@@ -45,7 +45,7 @@ sbl init --models
 
 # Local install
 npm install super-backlog
-node ./node_modules/super-backlog/dist/cli.js init
+node ./node_modules/super-backlog/dist/bin.js init
 ```
 
 After installation:

package/dist/bin.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// src/bin.ts
+// Always-run CLI entry. Unlike src/cli.ts (a plain module that only exports
+// HELP/runCli for tests), this file self-executes unconditionally so it
+// works when invoked via a symlink (npm's POSIX global/npx/npm-link bins are
+// symlinks, so comparing process.argv[1] against the module's own realpath
+// -- as the old cli.ts guard did -- is false for every such install).
+import process from 'node:process';
+import { runCli } from './cli.js';
+import { assertNode20 } from './lib/version.js';
+assertNode20();
+runCli(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/cli.js

@@ -1,9 +1,8 @@
-#!/usr/bin/env node
 // src/cli.ts
+// Pure library module: exports HELP/runCli for the always-run entry
+// (src/bin.ts) and for tests. Never self-executes -- see src/bin.ts for why.
 import { homedir } from 'node:os';
 import { parseArgs } from 'node:util';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { runDashboard } from './commands/dashboard.js';
 import { runDoctor } from './commands/doctor.js';
@@ -11,7 +10,7 @@ import { runInit } from './commands/init.js';
 import { runModels } from './commands/models.js';
 import { runUninstall } from './commands/uninstall.js';
 import { runUpdate } from './commands/update.js';
-import { assertNode20, KIT_VERSION } from './lib/version.js';
+import { KIT_VERSION } from './lib/version.js';
 import { applyVersionHint, defaultFetchLatest } from './lib/version-check.js';
 export const HELP = `super-backlog (sbl) - equip any project with Backlog.md + Superpowers
 
@@ -64,7 +63,7 @@ export async function runCli(argv) {
         console.log(HELP);
         return 0;
     }
-    void applyVersionHint(KIT_VERSION, {
+    await applyVersionHint(KIT_VERSION, {
         home: homedir(),
         now: () => new Date(),
         fetchLatest: defaultFetchLatest,
@@ -143,15 +142,3 @@ export async function runCli(argv) {
             return 1;
     }
 }
-assertNode20();
-const entry = process.argv[1];
-if (entry && fileURLToPath(import.meta.url) === resolve(entry)) {
-    runCli(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

@@ -81,6 +81,25 @@ function waitForClose(hub) {
         hub.server.once('close', () => resolve());
     });
 }
+/**
+ * Builds the hub shutdown routine: close the hub handle, then clear the
+ * on-disk hub.json owned by `pid`. The returned function is idempotent --
+ * calling it more than once (e.g. once from a signal handler, once from the
+ * caller's own cleanup) only runs the underlying work once and every caller
+ * observes the same result.
+ */
+export function createShutdown(hub, home, pid) {
+    let done = null;
+    return function shutdown() {
+        if (done === null) {
+            done = (async () => {
+                await hub.close();
+                clearHubState(home, pid);
+            })();
+        }
+        return done;
+    };
+}
 async function attachToHub(opts) {
     let res;
     try {
@@ -150,6 +169,10 @@ export async function runDashboard(cwd, args, deps = {}) {
         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}`);
+                    return 1;
+                }
                 return await attachToHub({
                     cwd,
                     port: state.port,
@@ -199,8 +222,9 @@ export async function runDashboard(cwd, args, deps = {}) {
     console.log(`serving dashboard at ${result.url} (press Ctrl+C to stop)`);
     if (!noOpen)
         openBrowser(result.url);
+    const shutdown = createShutdown(hub, home, pid);
     const onSignal = () => {
-        void hub.close();
+        void shutdown();
     };
     process.once('SIGINT', onSignal);
     process.once('SIGTERM', onSignal);
@@ -211,6 +235,6 @@ export async function runDashboard(cwd, args, deps = {}) {
     finally {
         process.removeListener('SIGINT', onSignal);
         process.removeListener('SIGTERM', onSignal);
-        clearHubState(home, pid);
+        await shutdown();
     }
 }

package/dist/dashboard/hub.js

@@ -12,20 +12,17 @@ import { projectSlug, realpathKey } from '../lib/slug.js';
 import { KIT_VERSION } from '../lib/version.js';
 import { createModelApiHandler } from '../models/dashboard-api.js';
 const WATCH_WARN = 'warning: live reload is disabled because Node 24+ on Windows cannot reliably watch directories recursively (libuv fs-event bug); use Node 22 or Linux/macOS for live reload';
-function watchBacklog(cwd, reloader) {
-    const backlogDir = join(cwd, 'backlog');
-    if (recursiveWatchSupported(process.platform, process.versions.node)) {
-        try {
-            const watcher = watch(backlogDir, { persistent: true, recursive: true }, () => reloader.trigger());
-            watcher.on('error', () => { });
-            return watcher;
-        }
-        catch {
-            return null;
-        }
-    }
-    console.warn(WATCH_WARN);
-    return null;
+const ALLOWED_HOST = /^(127\.0\.0\.1|localhost)(:\d+)?$/;
+function isAllowedHost(headerValue) {
+    const value = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+    if (typeof value !== 'string')
+        return false;
+    return ALLOWED_HOST.test(value.trim().toLowerCase());
+}
+function hasJsonContentType(req) {
+    const value = req.headers['content-type'];
+    const ct = Array.isArray(value) ? value[0] : value;
+    return typeof ct === 'string' && ct.toLowerCase().startsWith('application/json');
 }
 function projectUrl(port, slug) {
     return `http://127.0.0.1:${port}/p/${slug}/`;
@@ -66,6 +63,25 @@ export async function startHubServer(opts) {
     const projects = new Map();
     const token = opts.token;
     let port = 0;
+    let watchWarned = false;
+    function watchBacklog(cwd, reloader) {
+        const backlogDir = join(cwd, 'backlog');
+        if (recursiveWatchSupported(process.platform, process.versions.node)) {
+            try {
+                const watcher = watch(backlogDir, { persistent: true, recursive: true }, () => reloader.trigger());
+                watcher.on('error', () => { });
+                return watcher;
+            }
+            catch {
+                return null;
+            }
+        }
+        if (!watchWarned) {
+            watchWarned = true;
+            console.warn(WATCH_WARN);
+        }
+        return null;
+    }
     function disposeEntry(entry) {
         entry.reloader.cancel();
         entry.broker.close();
@@ -82,7 +98,7 @@ export async function startHubServer(opts) {
         if (!computed.ok) {
             return { ok: false, code: 400, message: 'empty slug' };
         }
-        const slug = project.slug ?? computed.slug;
+        const slug = computed.slug;
         if (slug === '') {
             return { ok: false, code: 400, message: 'empty slug' };
         }
@@ -124,7 +140,15 @@ export async function startHubServer(opts) {
         return { ok: true, slug, url };
     }
     async function handle(req, res) {
+        if (!isAllowedHost(req.headers.host)) {
+            sendText(res, 403, 'forbidden');
+            return;
+        }
         const method = req.method ?? 'GET';
+        if (method === 'POST' && !hasJsonContentType(req)) {
+            sendText(res, 415, 'unsupported media type: expected application/json');
+            return;
+        }
         const parsed = new URL(req.url ?? '/', 'http://127.0.0.1');
         const pathname = parsed.pathname;
         if (pathname === '/' && method === 'GET') {

package/dist/lib/hub-state.js

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto';
-import { mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { chmodSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
 import { atomicWrite } from './atomic.js';
@@ -25,7 +25,13 @@ export function readHubState(home) {
 }
 export function writeHubState(home, state) {
     mkdirSync(join(home, '.super-backlog'), { recursive: true });
-    atomicWrite(hubStatePath(home), JSON.stringify(state));
+    const path = hubStatePath(home);
+    atomicWrite(path, JSON.stringify(state));
+    // hub.json carries the hub's auth token; keep it off other local accounts.
+    // win32 has no POSIX mode bits (ACLs govern access there instead).
+    if (process.platform !== 'win32') {
+        chmodSync(path, 0o600);
+    }
 }
 export function clearHubState(home, pid) {
     const current = readHubState(home);

package/dist/lib/version-check.js

@@ -2,7 +2,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
-import { runCapture } from './run.js';
+import spawn from 'cross-spawn';
 const DAY_MS = 24 * 60 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 2000;
 function cachePath(home) {
@@ -45,23 +45,50 @@ function isStale(checkedAt, now) {
     const t = Date.parse(checkedAt);
     if (Number.isNaN(t))
         return true;
-    return now.getTime() - t > DAY_MS;
+    const nowMs = now.getTime();
+    if (t > nowMs)
+        return true; // clock skew: a future checkedAt can never be trusted
+    return nowMs - t > DAY_MS;
+}
+// child.stdout is typed as Readable, but the underlying pipe stream (a
+// net.Socket on POSIX, a Pipe wrap on Windows) always exposes unref() at
+// runtime; the DOM/Node stream typings just don't declare it.
+function unrefStream(stream) {
+    stream?.unref?.();
 }
 export async function defaultFetchLatest() {
-    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-    const work = Promise.resolve().then(() => {
-        const r = runCapture(npm, ['view', 'super-backlog', 'version'], process.cwd());
-        if (r.status !== 0)
-            return null;
-        const line = r.stdout.split(/\r?\n/).find((l) => l.trim() !== '');
-        if (!line)
-            return null;
-        const v = line.trim();
-        return v === '' ? null : v;
+    const work = new Promise((resolvePromise) => {
+        let child;
+        try {
+            child = spawn('npm', ['view', 'super-backlog', 'version'], {
+                cwd: process.cwd(),
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+        }
+        catch {
+            resolvePromise(null);
+            return;
+        }
+        let out = '';
+        unrefStream(child.stdout);
+        child.stdout?.on('data', (chunk) => {
+            out += chunk.toString('utf8');
+        });
+        child.on('error', () => resolvePromise(null));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                resolvePromise(null);
+                return;
+            }
+            const line = out.split(/\r?\n/).find((l) => l.trim() !== '');
+            const v = line?.trim();
+            resolvePromise(v === undefined || v === '' ? null : v);
+        });
+        child.unref();
     });
     let timer;
-    const timeout = new Promise((resolve) => {
-        timer = setTimeout(() => resolve(null), FETCH_TIMEOUT_MS);
+    const timeout = new Promise((resolveTimeout) => {
+        timer = setTimeout(() => resolveTimeout(null), FETCH_TIMEOUT_MS);
         timer.unref();
     });
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-backlog",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "One command to equip any project with Backlog.md + Superpowers, plus a Project Dashboard.",
   "license": "MIT",
   "repository": {
@@ -12,8 +12,8 @@
     "node": ">=20"
   },
   "bin": {
-    "sbl": "dist/cli.js",
-    "super-backlog": "dist/cli.js"
+    "sbl": "dist/bin.js",
+    "super-backlog": "dist/bin.js"
   },
   "files": [
     "dist",

package/dist/commands/backlog-alias.js

@@ -1,18 +0,0 @@
-import spawn from 'cross-spawn';
-import { resolveBacklogBin } from '../lib/run.js';
-/** Run a backlog.md subcommand by delegating to the resolved backlog binary. */
-export function runBacklogSubcommand(cwd, subcommand, args = []) {
-    const bin = resolveBacklogBin(cwd);
-    if (!bin) {
-        console.error('error: backlog CLI not found; is backlog.md installed?');
-        return Promise.resolve(1);
-    }
-    return new Promise((resolve) => {
-        const child = spawn(bin, [subcommand, ...args], {
-            cwd,
-            stdio: 'inherit',
-        });
-        child.on('error', () => resolve(1));
-        child.on('exit', (code) => resolve(code ?? 1));
-    });
-}