@dyzsasd/dev-loop 0.22.0

package/dist/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// `dev-loop` — the unified CLI for the standalone hub (P4 packaging, design daemon-multicli §6).
+// A THIN dispatcher over the existing zero-build entry points (each keeps its own arg-parsing). After
+// `npm i -g dev-loop` this is on PATH, so a product `.mcp.json` can say {command:"dev-loop", args:["shim"]}
+// or {args:["serve"]} instead of a fragile absolute `node .../hub/src/server.ts` path. Zero build: Node
+// >=23.6 type-strips the .ts entries directly; the bin shebang runs THIS file the same way.
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+const here = dirname(fileURLToPath(import.meta.url)); // hub/src (dev) | dist (published)
+// Resolve siblings by THIS file's own extension: `.ts` when run from source (zero-build dev), `.js` when
+// run from the compiled, published package (node refuses to type-strip under node_modules — P4 ships JS).
+const EXT = fileURLToPath(import.meta.url).endsWith(".js") ? ".js" : ".ts";
+const [cmd, ...rest] = process.argv.slice(2);
+// subcommand → [entry base (no ext), ...prefix args]; the entry's OWN dispatcher consumes the rest unchanged.
+const ROUTES = {
+    serve: ["server"], // the stdio MCP server (the agent transport; = the dev-loop-hub bin)
+    shim: ["shim"], // thin stdio MCP → loopback daemon op-API (DL-55)
+    daemon: ["server", "daemon"], // up | down | status | ensure (DL-41)
+    doctor: ["server", "doctor"],
+    seed: ["seed"],
+    "init-service": ["init-service"], // turnkey bootstrap (DL-60)
+    "mcp-merge": ["mcp-merge"], // merge into a product .mcp.json, never clobbers (DL-61)
+    "identity-check": ["server", "identity-check"], // the portability gate (PORTABILITY.md §4)
+    "resolve-project": ["server", "resolve-project"],
+    tickets: ["cli-tickets", "tickets"], // read-only terminal board list (DL-90)
+    ticket: ["cli-tickets", "ticket"], // read-only single-ticket detail + comments (DL-90)
+    // NB: `release-version` is deliberately NOT routed here — it mutates repo-only manifests
+    // (.claude-plugin/*) absent from the npm package, so it's a source-tree-only tool: run it in-repo
+    // via `node hub/src/release-version.ts <semver>` (Codex review 2026-06-27).
+};
+const version = () => {
+    try {
+        return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+};
+const usage = () => {
+    console.log(`dev-loop ${version()} — standalone coordination hub (daemon + MCP + CLI)
+
+Usage: dev-loop <command> [args]
+
+  serve                       run the stdio MCP server (the agent transport; same as the dev-loop-hub bin)
+  shim                        run the thin stdio MCP shim → the loopback daemon op-API (hub.transport:"daemon")
+  daemon up|down|status       per-project daemon lifecycle — idempotent, auto-starts the localhost web UI
+  init-service <key> <name> <PREFIX>   turnkey-bootstrap a service-backend project (seed → doctor → daemon up)
+  mcp-merge <args>            merge dev-loop-hub into a product .mcp.json (never clobbers other servers)
+  seed <key> <name> [PREFIX]  seed a project + actors + labels into the hub db
+  doctor                      health-check the hub system-of-record (DOCTOR_OK)
+  identity-check [--expect <actor>[/<project>]]   verify this shell resolves the intended identity
+  tickets [--all] [--state S] [--type T] [--owner O] [--label L] [--q TEXT]   read-only: list the resolved project's board (no daemon)
+  ticket <id>                 read-only: show one ticket — detail + comments
+  version | help
+
+Identity rides DEVLOOP_ACTOR (per pane); project DEVLOOP_PROJECT (or the cwd); db DEVLOOP_HUB_DB.
+Docs: https://github.com/dyzsasd/dev-loop  (docs/RUNNING.md, docs/PORTABILITY.md, docs/HUB-ARCHITECTURE.md)`);
+};
+if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    usage();
+    process.exit(0);
+}
+if (cmd === "version" || cmd === "--version" || cmd === "-v") {
+    console.log(version());
+    process.exit(0);
+}
+const route = ROUTES[cmd];
+if (!route) {
+    console.error(`dev-loop: unknown command '${cmd}'\n`);
+    usage();
+    process.exit(2);
+}
+const [entryBase, ...prefix] = route;
+const r = spawnSync(process.execPath, [join(here, entryBase + EXT), ...prefix, ...rest], { stdio: "inherit" });
+process.exit(r.status ?? 1);

package/dist/daemon-lifecycle.js

@@ -0,0 +1,372 @@
+// dev-loop hub daemon — the per-project process-lifecycle / supervisor subsystem (DL-74 extraction).
+//
+// DL-41: idempotent per-project daemon lifecycle (up | ensure | down | status). A thin, additive wrapper
+// around the foreground boot that lives in `daemon.ts` (this module's sibling): `up` resolves the project
+// (cwd or DEVLOOP_PROJECT), picks a stable per-project port, and spawns `daemon.ts` detached so the web UI
+// survives the launching shell; `down`/`status` operate on a machine-local runfile. Designed so the DL-42
+// SessionStart hook can call `up` unconditionally: a non-service / unresolved project is a clean no-op +
+// exit 0, and a second `up` never double-starts. The foreground boot path (`npm run daemon`) is NOT touched
+// by any of this — daemon.ts's own top-level dispatch routes a lifecycle subcommand here before its
+// foreground `if` is reached. This module has NO top-level side effects (pure declarations), so importing
+// it is always safe (server.ts delegates `dev-loop-hub daemon <sub>` to it; daemon.ts imports the dispatch).
+import { spawn } from "node:child_process";
+import { createServer as netCreateServer } from "node:net";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync, openSync, closeSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { openDb } from "./db.js";
+import { findProject } from "./seed.js";
+import { loadProjectsConfig, resolveProjectFromCwd } from "./resolve-project.js";
+// The runfile lives next to the hub DB (machine-local, never committed — ~/.dev-loop by default), one
+// file per project so distinct projects never clobber each other. DEVLOOP_RUN_DIR overrides for tests.
+function lcDbPath() { return process.env.DEVLOOP_HUB_DB ?? `${homedir()}/.dev-loop/hub.db`; }
+function lcRunDir() { return process.env.DEVLOOP_RUN_DIR ?? dirname(lcDbPath()); }
+function lcRunfile(key) { return join(lcRunDir(), `daemon-${key}.json`); }
+function lcReadRun(key) {
+    try {
+        return JSON.parse(readFileSync(lcRunfile(key), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function lcWriteRun(info) {
+    mkdirSync(lcRunDir(), { recursive: true });
+    const f = lcRunfile(info.project), tmp = `${f}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(info, null, 2));
+    renameSync(tmp, f); // atomic replace (§11 atomic-write discipline) — a partial write never yields invalid JSON
+}
+function lcRemoveRun(key) { try {
+    unlinkSync(lcRunfile(key));
+}
+catch { /* already gone */ } }
+function lcLockfile(key) { return join(lcRunDir(), `daemon-${key}.lock`); }
+function lcReadLockAt(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function lcReadLock(key) { return lcReadLockAt(lcLockfile(key)); }
+// staleMs MUST exceed daemonUp's worst-case in-lock hold (lcStop ≤3s + lcWaitHealthy ≤8s + probing ≈ ≤15s)
+// so a legitimately-busy live holder is never broken, AND stay well under totalMs so stale-recovery wins
+// before a waiter's own acquire deadline fires (else a pid-reused stale lock is breakable only at the exact
+// instant the waiter gives up). 30s/60s gives ~2× margin on each side.
+async function lcAcquireLock(key, totalMs = 60000, staleMs = 30000) {
+    const lf = lcLockfile(key);
+    const bf = `${lf}.break`; // DL-51: a dedicated O_EXCL break-mutex that serializes stale-lock breaking (below)
+    mkdirSync(lcRunDir(), { recursive: true });
+    const deadline = Date.now() + totalMs;
+    const stamp = () => JSON.stringify({ pid: process.pid, at: new Date().toISOString() });
+    // Stale ⇔ holder gone, or older than staleMs (a crashed `up`, or a dead holder whose pid got recycled).
+    // `!(age <= staleMs)` (not `age > staleMs`) so a missing/corrupt `at` → NaN → stale (never trust an
+    // unparseable lock to be fresh). A dead pid reads stale immediately (no need to wait out staleMs).
+    const isStale = (h) => {
+        const age = h ? Date.now() - Date.parse(h.at) : Infinity;
+        return !h || !lcIsAlive(h.pid) || !(age <= staleMs);
+    };
+    // Throw once we've waited out totalMs on a LIVE holder/breaker. A stale lock is always broken (the break
+    // path below is never deadline-gated), so a recoverable stale lock present at the deadline is cleared and
+    // acquired, not reported as a hard failure (preserving the pre-DL-51 break-past-the-deadline behavior).
+    const checkDeadline = () => {
+        if (Date.now() < deadline)
+            return;
+        const h = lcReadLock(key);
+        throw new Error(`could not acquire daemon cold-start lock for '${key}'${h ? ` (held by pid ${h.pid})` : ""}`);
+    };
+    for (;;) {
+        try {
+            // `wx` = O_CREAT|O_EXCL|O_WRONLY — the OS guarantees exactly one creator wins (atomic, race-free).
+            // This wx-create is the SINGLE arbiter of who acquires: the stale-break below only ever REMOVES a
+            // stale lock so a wx-create can proceed — it never itself grants ownership — so two racers can never
+            // both acquire, even if both decide to break.
+            writeFileSync(lf, stamp(), { flag: "wx" });
+            let released = false;
+            // Ownership-checked release: only remove the lock if it's still OURS. If our hold somehow outlived
+            // staleMs and another `up` broke + re-took it, deleting unconditionally would clobber the NEW owner's
+            // lock and re-admit a concurrent cold start — so re-read and unlink only when the pid is still ours.
+            return () => { if (released)
+                return; released = true; try {
+                if (lcReadLock(key)?.pid === process.pid)
+                    unlinkSync(lf);
+            }
+            catch { /* already gone */ } };
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e; // a real fs error, not "held"
+            if (!isStale(lcReadLock(key))) {
+                checkDeadline();
+                await new Promise((r) => setTimeout(r, 100));
+                continue;
+            } // live, fresh `up` — wait
+            // DL-51 — break a stale lock under a dedicated O_EXCL break-mutex. Breaking lf directly is a TOCTOU that
+            // re-admits a 2nd cold start (the DL-46 orphan): two `up`s both read the OLD lock stale; one breaks it and
+            // wx-creates a FRESH lock, and the other's path-keyed remove (which cannot say "only if STILL the stale
+            // one") then clobbers that VALID lock. Under the mutex exactly ONE racer breaks at a time and re-confirms
+            // staleness while holding it: while `lf` exists nobody can wx-create over it and only the mutex-holder
+            // removes it, so this read→remove only ever deletes a STILL-stale lock; a fresh lock is left intact. The
+            // top-of-loop wx-create stays the SOLE arbiter of acquisition, so a break can never itself admit a second.
+            try {
+                writeFileSync(bf, stamp(), { flag: "wx" }); // sole breaker
+                try {
+                    if (isStale(lcReadLock(key))) {
+                        try {
+                            unlinkSync(lf);
+                        }
+                        catch { /* already gone */ }
+                    }
+                }
+                // Ownership-checked release (mirrors the lf release): only unlink bf if it's still OURS, so we never
+                // clobber a mutex a racer legitimately re-took (the same hazard the lf release guards against).
+                finally {
+                    try {
+                        if (lcReadLockAt(bf)?.pid === process.pid)
+                            unlinkSync(bf);
+                    }
+                    catch { /* already released */ }
+                }
+            }
+            catch (be) {
+                if (be.code !== "EEXIST")
+                    throw be;
+                // Another racer holds the break-mutex: clear a dead/stale breaker (a crash mid-break can't wedge the
+                // next `up`); wait out a live breaker (it holds the mutex for only a couple of fs ops).
+                if (isStale(lcReadLockAt(bf))) {
+                    try {
+                        unlinkSync(bf);
+                    }
+                    catch { /* already gone */ }
+                }
+                else {
+                    checkDeadline();
+                    await new Promise((r) => setTimeout(r, 100));
+                }
+            }
+            // loop: the stale lock (if any) is now gone → the wx-create at the top arbitrates the single acquirer.
+        }
+    }
+}
+// A stable, deterministic per-project port (FNV-1a of the key → a fixed high port) so the URL is the
+// same across restarts even before a runfile exists; probed for freeness at `up` time so a hash
+// collision between two projects just shifts the loser to the next free port (then records it).
+function lcPortFor(key) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < key.length; i++) {
+        h ^= key.charCodeAt(i);
+        h = Math.imul(h, 16777619) >>> 0;
+    }
+    return 20000 + (h % 20000); // 20000–39999: clear of the registered-port crush and the 8787 default
+}
+function lcIsAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+// Stop a pid gracefully: SIGTERM, wait up to graceMs, then escalate to SIGKILL so a wedged/slow daemon
+// is never leaked. Shared by `down` and `up`'s reclaim + failed-spawn paths (one shutdown semantics).
+async function lcStop(pid, graceMs = 3000) {
+    if (!lcIsAlive(pid))
+        return;
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch { /* already gone */ }
+    const deadline = Date.now() + graceMs;
+    while (Date.now() < deadline && lcIsAlive(pid))
+        await new Promise((r) => setTimeout(r, 100));
+    if (lcIsAlive(pid)) {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch { /* ignore */ }
+    }
+}
+function lcTryBind(port, host) {
+    return new Promise((res) => {
+        const s = netCreateServer();
+        s.once("error", () => res(false));
+        s.listen(port, host, () => s.close(() => res(true)));
+    });
+}
+async function lcFreePort(start, host, tries = 64) {
+    for (let i = 0; i < tries; i++) {
+        const p = start + i;
+        if (p > 65535)
+            break;
+        if (await lcTryBind(p, host))
+            return p;
+    }
+    return start; // give up probing — the spawned daemon will surface EADDRINUSE loudly rather than silently
+}
+async function lcProbe(url, key, timeoutMs = 1000) {
+    try {
+        const ac = new AbortController();
+        const t = setTimeout(() => ac.abort(), timeoutMs);
+        const r = await fetch(`${url}/api/health`, { signal: ac.signal }).finally(() => clearTimeout(t));
+        if (r.status !== 200)
+            return false;
+        const b = (await r.json().catch(() => null));
+        return !!b && b.ok === true && b.project === key; // confirm it's OUR project on that port, not a stranger
+    }
+    catch {
+        return false;
+    }
+}
+async function lcWaitHealthy(url, key, totalMs = 8000) {
+    const deadline = Date.now() + totalMs;
+    while (Date.now() < deadline) {
+        if (await lcProbe(url, key, 800))
+            return true;
+        await new Promise((r) => setTimeout(r, 150));
+    }
+    return false;
+}
+// Resolve the project key like the MCP server / DL-13 launcher: explicit DEVLOOP_PROJECT wins; else
+// match cwd against the configured repo paths. null ⇒ unresolved (the caller no-ops, never guesses).
+function lcResolveKey() {
+    const explicit = process.env.DEVLOOP_PROJECT?.trim();
+    if (explicit)
+        return explicit; // parity with server.ts:22 — a present-but-empty/whitespace value is NOT a key
+    const cfg = loadProjectsConfig();
+    return cfg ? resolveProjectFromCwd(process.cwd(), cfg) : null;
+}
+async function daemonUp() {
+    const key = lcResolveKey();
+    if (!key) {
+        console.log("[daemon] up: no project resolved from cwd and DEVLOOP_PROJECT is unset — nothing to start.");
+        return 0;
+    }
+    // Serveable ⇔ seeded in the hub DB. A non-service / unknown project is never in the hub ⇒ clean no-op.
+    const dbPath = lcDbPath();
+    let serveable = false;
+    try {
+        const probe = openDb(dbPath);
+        try {
+            serveable = !!findProject(probe, key);
+        }
+        finally {
+            probe.close();
+        }
+    }
+    catch {
+        serveable = false;
+    }
+    if (!serveable) {
+        console.log(`[daemon] up: '${key}' is not a service-backend hub project (not seeded) — nothing to start.`);
+        return 0;
+    }
+    const host = "127.0.0.1"; // §16 localhost-only
+    // Fast path (lock-free): a healthy daemon is already running ⇒ no-op without taking the lock. This is the
+    // common case (the DL-42 hook fires `up` on every pane, but the daemon is usually already up), so routine
+    // `up`s never serialize on the lock — only an actual cold start does.
+    const pre = lcReadRun(key);
+    if (pre && lcIsAlive(pre.pid) && await lcProbe(pre.url, key)) {
+        console.log(`[daemon] up: already running for '${key}' → ${pre.url} (pid ${pre.pid})`);
+        return 0;
+    }
+    // DL-46: serialize cold start under the per-project lock — the second concurrent `up` waits here, then
+    // re-reads the runfile below and no-ops on the winner (no second spawn, no last-writer-wins runfile race).
+    let release;
+    try {
+        release = await lcAcquireLock(key);
+    }
+    catch (e) {
+        console.error(`[daemon] up: ${e.message}`);
+        return 1;
+    }
+    try {
+        const existing = lcReadRun(key);
+        if (existing && lcIsAlive(existing.pid)) {
+            if (await lcProbe(existing.url, key)) {
+                console.log(`[daemon] up: already running for '${key}' → ${existing.url} (pid ${existing.pid})`);
+                return 0;
+            }
+            // alive but not answering /api/health (now a real DB-writable probe) — a bound-but-wedged daemon;
+            // fully stop it (SIGTERM→SIGKILL) so we cleanly restart on its port rather than no-op onto a dead one.
+            await lcStop(existing.pid);
+        }
+        // port: explicit env override > recorded (stable across restarts) > deterministic; probe for free.
+        const envPort = process.env.DEVLOOP_DAEMON_PORT ? Number(process.env.DEVLOOP_DAEMON_PORT) : 0;
+        const port = envPort > 0 ? envPort : await lcFreePort(existing?.port || lcPortFor(key), host);
+        const url = `http://${host}:${port}`;
+        // Spawn the daemon ENTRY POINT — the foreground boot lives in daemon.ts (this module's sibling), so
+        // resolve it relative to here (NOT import.meta.url, which is this lifecycle module and has no server).
+        const self = fileURLToPath(new URL("./daemon.ts", import.meta.url));
+        mkdirSync(lcRunDir(), { recursive: true });
+        const logFd = openSync(join(lcRunDir(), `daemon-${key}.log`), "a");
+        const child = spawn(process.execPath, [self], {
+            detached: true, // survive the launching session (DL-42 hook)
+            stdio: ["ignore", logFd, logFd],
+            env: { ...process.env, DEVLOOP_PROJECT: key, DEVLOOP_DAEMON_PORT: String(port), DEVLOOP_HUB_DB: dbPath },
+        });
+        child.unref();
+        closeSync(logFd);
+        if (!child.pid) {
+            console.error("[daemon] up: failed to spawn the daemon process.");
+            return 1;
+        }
+        if (!(await lcWaitHealthy(url, key))) {
+            console.error(`[daemon] up: spawned daemon for '${key}' did not become healthy at ${url} (see ${join(lcRunDir(), `daemon-${key}.log`)}).`);
+            await lcStop(child.pid); // never leak a slow/wedged child — escalate to SIGKILL if SIGTERM doesn't take
+            return 1;
+        }
+        lcWriteRun({ project: key, pid: child.pid, port, host, url, startedAt: new Date().toISOString() });
+        console.log(`[daemon] up: started '${key}' → ${url} (pid ${child.pid})`);
+        return 0;
+    }
+    finally {
+        release();
+    }
+}
+async function daemonDown() {
+    const key = lcResolveKey();
+    if (!key) {
+        console.log("[daemon] down: no project resolved — nothing to stop.");
+        return 0;
+    }
+    const info = lcReadRun(key);
+    if (!info) {
+        console.log(`[daemon] down: no daemon recorded for '${key}'.`);
+        return 0;
+    }
+    if (lcIsAlive(info.pid)) {
+        await lcStop(info.pid); // SIGTERM→SIGKILL; stops a wedged daemon too (down must work even when unhealthy)
+        console.log(`[daemon] down: stopped '${key}' (pid ${info.pid}).`);
+    }
+    else {
+        console.log(`[daemon] down: '${key}' was not running (stale runfile cleared).`);
+    }
+    lcRemoveRun(key);
+    return 0;
+}
+async function daemonStatus() {
+    const key = lcResolveKey();
+    if (!key) {
+        console.log("[daemon] status: no project resolved (DEVLOOP_PROJECT unset, cwd outside every repo). Set DEVLOOP_PROJECT=<key>, or run from inside a configured repo.");
+        return 0;
+    }
+    const info = lcReadRun(key);
+    if (info && lcIsAlive(info.pid) && (await lcProbe(info.url, key))) {
+        console.log(`[daemon] status: '${key}' RUNNING → ${info.url} (pid ${info.pid})`);
+        return 0;
+    }
+    if (info && !lcIsAlive(info.pid))
+        lcRemoveRun(key); // a dead pid must never read as "running" — clear it
+    console.log(`[daemon] status: '${key}' stopped. Start it with \`dev-loop daemon up\`.`);
+    return 0;
+}
+export const LIFECYCLE_SUBS = ["up", "ensure", "down", "status"];
+export async function daemonLifecycle(sub) {
+    const code = sub === "up" || sub === "ensure" ? await daemonUp() : sub === "down" ? await daemonDown() : await daemonStatus();
+    process.exit(code);
+}