@lyric_dev/data-loom 0.5.0 → 0.7.0

package/dist/mcpShim.js

@@ -0,0 +1,144 @@
+// MCP stdio shim: spawned by a client (typically Claude Code's stdio
+// registration), it ensures the daemon is running, then proxies MCP traffic
+// between its own stdio and the daemon's loopback HTTP `/mcp` endpoint for the
+// life of the client session.
+//
+// Pure proxy — no tools, prompts, or sessions of its own. The daemon remains
+// the single MCP server and source of truth (including per-call project
+// resolution); this file only launches (if needed) and forwards raw JSON-RPC
+// messages both ways.
+import { readFile } from "node:fs/promises";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { isInitializeRequest, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import * as lifecycle from "./lifecycle.js";
+import { mcpUrl, logFile } from "./paths.js";
+const LAUNCH_TIMEOUT_MS = 10_000;
+const POLL_INTERVAL_MS = 300;
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Ensure the daemon answers on the loopback port, starting it (through the
+ * normal detached lifecycle path) if it does not. Bounded wait — never hangs.
+ * A concurrent second shim racing to start is harmless: the daemon's own
+ * single-instance guard (the port probe in lifecycle.start) means at most one
+ * daemon results, and both shims' polls succeed against it.
+ */
+async function ensureDaemonUp() {
+    if (await lifecycle.isRunning())
+        return { ok: true };
+    await lifecycle.start();
+    const deadline = Date.now() + LAUNCH_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await lifecycle.isRunning())
+            return { ok: true };
+        await delay(POLL_INTERVAL_MS);
+    }
+    return { ok: false, diagnosis: await diagnoseFailure() };
+}
+/** Best-effort explanation of why the daemon never came up, from its own log tail. */
+async function diagnoseFailure() {
+    let tail = "";
+    try {
+        tail = (await readFile(logFile(), "utf8")).slice(-4000);
+    }
+    catch {
+        /* no log yet — daemon likely never got far enough to write one */
+    }
+    if (/openspec.*was not found/i.test(tail)) {
+        return ("DataLoom could not start: the `openspec` CLI is missing. Install it (e.g. `npm i -g openspec`), then retry. " +
+            `Log: ${logFile()}`);
+    }
+    return ("DataLoom's daemon did not come up in time. Run `data-loom status` to check what's wrong, and see the log at " +
+        logFile());
+}
+function extractId(msg) {
+    return "id" in msg ? msg.id : undefined;
+}
+function errorResponse(id, message) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: ErrorCode.InternalError, message },
+    };
+}
+/**
+ * stdout is the MCP transport's wire — reserved exclusively for framed
+ * JSON-RPC messages. Reused helpers here (lifecycle.start/isRunning) predate
+ * the shim and log human-readable status with console.log, which writes to
+ * that same stdout; left alone, those lines interleave with JSON-RPC frames
+ * and corrupt the client's stream. Redirect the stdout-writing console
+ * methods to stderr for this process's whole lifetime (console.warn/error
+ * already go to stderr).
+ */
+function keepStdoutForTransportOnly() {
+    console.log = console.error;
+    console.info = console.error;
+    console.debug = console.error;
+}
+/**
+ * Entry point for `data-loom mcp-shim`. Never resolves until the client
+ * session ends (or the launch fails and the handshake has been answered) —
+ * the caller (index.ts) just awaits and lets the process exit naturally.
+ */
+export async function runShim() {
+    keepStdoutForTransportOnly();
+    const stdio = new StdioServerTransport();
+    // Buffer whatever arrives while the daemon is (maybe) still starting, so
+    // nothing sent before the proxy is wired up is lost.
+    const pending = [];
+    stdio.onmessage = (msg) => {
+        pending.push(msg);
+    };
+    stdio.onerror = (err) => console.error("[data-loom mcp-shim] stdio error:", err);
+    await stdio.start();
+    const readiness = await ensureDaemonUp();
+    if (!readiness.ok) {
+        const initMsg = pending.find((m) => isInitializeRequest(m));
+        const id = initMsg ? extractId(initMsg) : undefined;
+        if (id !== undefined) {
+            await stdio.send(errorResponse(id, readiness.diagnosis));
+        }
+        else {
+            // No handshake to answer yet — still surface the failure, just not as
+            // an MCP response. Never exit without saying why.
+            console.error(`[data-loom mcp-shim] ${readiness.diagnosis}`);
+        }
+        await stdio.close();
+        process.exitCode = 1;
+        return;
+    }
+    const client = new StreamableHTTPClientTransport(new URL(mcpUrl()));
+    let closing = false;
+    // The shim's whole job ends with its client session — one side closing
+    // (client disconnects, or the daemon connection drops) tears down the
+    // other, but the daemon itself is never touched.
+    const closeBoth = () => {
+        if (closing)
+            return;
+        closing = true;
+        void stdio.close();
+        void client.close();
+        process.exit(0);
+    };
+    client.onmessage = (msg) => {
+        void stdio.send(msg);
+    };
+    client.onerror = (err) => console.error("[data-loom mcp-shim] daemon connection error:", err);
+    client.onclose = closeBoth;
+    stdio.onerror = (err) => console.error("[data-loom mcp-shim] stdio error:", err);
+    stdio.onclose = closeBoth;
+    // StdioServerTransport only ever calls onclose when *we* call close() — it
+    // does not itself listen for stdin ending. The client process closing its
+    // end of the pipe (the real "session ended" signal) only shows up as
+    // stdin's own 'end'/'close' event, so that is what actually has to trigger
+    // teardown here.
+    process.stdin.on("end", closeBoth);
+    process.stdin.on("close", closeBoth);
+    await client.start();
+    for (const msg of pending)
+        await client.send(msg);
+    // From here on, every message from the client goes straight through.
+    stdio.onmessage = (msg) => {
+        void client.send(msg);
+    };
+}

package/dist/paths.js

@@ -31,6 +31,12 @@ export function stateDir() {
 }
 export const pidFile = () => join(stateDir(), "daemon.pid");
 export const logFile = () => join(stateDir(), "daemon.log");
+/**
+ * The stable launcher OS supervisors invoke (Scheduled Task / LaunchAgent /
+ * systemd unit) — a fixed path that never changes across Node version or
+ * package-location churn, unlike the `node` + script paths it wraps.
+ */
+export const launcherFile = () => join(stateDir(), process.platform === "win32" ? "daemon.cmd" : "daemon.sh");
 /** Create the state dir on demand; safe to call repeatedly. */
 export async function ensureStateDir() {
     const dir = stateDir();

package/dist/server.js

@@ -15,7 +15,7 @@ const MIME = {
     ".svg": "image/svg+xml",
 };
 export async function startServer(opts) {
-    const { publicDir, host, port, getRoadmap, getMcp, checkMcp, getProjects, selectProject, getCurrentProject } = opts;
+    const { publicDir, host, port, getRoadmap, getMcp, checkMcp, getProjects, selectProject, getCurrentProject, onShutdown } = opts;
     let wss;
     const broadcast = (msg) => {
         const data = JSON.stringify(msg);
@@ -117,6 +117,16 @@ export async function startServer(opts) {
                     sendError(res, 413, "request body too large");
                 return;
             }
+            if (e instanceof InvalidJsonError) {
+                // A body that never parsed is the caller's encoding fault — answer with
+                // a JSON-RPC parse error, not a 500. The classic trigger is a Windows
+                // path with unescaped backslashes ("D:\projects\…" — \p is not a valid
+                // JSON escape), so name that in the hint. The detail only ever echoes
+                // the parser's complaint about the caller's own body, never host state.
+                if (!res.headersSent)
+                    sendRpcParseError(res, e.message);
+                return;
+            }
             // Unexpected failures stay in the server log; the client gets nothing
             // about the host (no paths, no stack).
             console.error("[data-loom] mcp request error:", e);
@@ -137,6 +147,15 @@ export async function startServer(opts) {
                 return sendJson(res, getMcp());
             if (url.pathname === "/api/projects")
                 return sendJson(res, await getProjects());
+            if (url.pathname === "/api/shutdown" && req.method === "POST") {
+                // Loopback-only (isAllowed already ran) graceful stop. Answer first,
+                // then trigger shutdown once the response has flushed so the caller
+                // gets its 200 before the process exits.
+                res.writeHead(200, { "content-type": MIME[".json"] });
+                res.end(JSON.stringify({ stopping: true }));
+                res.on("finish", () => setImmediate(() => onShutdown?.()));
+                return;
+            }
             if (url.pathname === "/api/mcp/check" && req.method === "POST") {
                 const server = await checkMcp(url.searchParams.get("name") ?? "");
                 if (!server)
@@ -174,6 +193,16 @@ export async function startServer(opts) {
         server: http,
         verifyClient: (info) => isAllowed(info.req),
     });
+    // ws re-emits the underlying server's 'error'; without a listener a bind
+    // failure (EADDRINUSE) becomes an unhandled 'error' event that crashes the
+    // process. The listen() promise below surfaces startup bind errors to the
+    // caller, so ignore those here (avoids a scary duplicate stack on the normal
+    // "already running" path); log only unexpected post-startup socket errors.
+    wss.on("error", (err) => {
+        if (err.code !== "EADDRINUSE") {
+            console.error("[data-loom] websocket error:", err);
+        }
+    });
     wss.on("connection", async (ws) => {
         const roadmap = getRoadmap();
         if (roadmap)
@@ -186,7 +215,18 @@ export async function startServer(opts) {
             /* project list optional */
         }
     });
-    await new Promise((ready) => http.listen(port, host, ready));
+    // Reject (rather than crash) if the port is taken — the caller decides how to
+    // report an already-running instance. After a clean listen, later server
+    // errors are logged, not fatal.
+    await new Promise((resolve, reject) => {
+        const onError = (err) => reject(err);
+        http.once("error", onError);
+        http.listen(port, host, () => {
+            http.removeListener("error", onError);
+            http.on("error", (err) => console.error("[data-loom] http server error:", err));
+            resolve();
+        });
+    });
     const actualPort = http.address()?.port ?? port;
     setAllowed(actualPort);
     return {
@@ -207,9 +247,29 @@ function sendError(res, code, message) {
     res.writeHead(code, { "content-type": MIME[".json"] });
     res.end(JSON.stringify({ error: message }));
 }
+/**
+ * Answer a request whose body was not valid JSON with a JSON-RPC parse error
+ * (-32700) over HTTP 400, per the Streamable-HTTP spec. `detail` is the JSON
+ * parser's message about the caller's own payload — safe to echo, and the hint
+ * names the most common cause on Windows (unescaped path backslashes).
+ */
+function sendRpcParseError(res, detail) {
+    res.writeHead(400, { "content-type": MIME[".json"] });
+    res.end(JSON.stringify({
+        jsonrpc: "2.0",
+        error: {
+            code: -32700,
+            message: `Parse error: request body is not valid JSON (${detail}). If the payload contains Windows paths, JSON-escape the backslashes ("D:\\\\projects\\\\…") or use forward slashes.`,
+        },
+        id: null,
+    }));
+}
 /** Raised when a request body exceeds the cap; mapped to HTTP 413. */
 class PayloadTooLargeError extends Error {
 }
+/** Raised when a request body is not parseable JSON; mapped to HTTP 400 / -32700. */
+class InvalidJsonError extends Error {
+}
 /** Largest request body we will buffer (JSON-RPC tool calls are tiny). */
 const MAX_BODY_BYTES = 4 * 1024 * 1024;
 /** Read and JSON-parse a request body; returns undefined for an empty body. */
@@ -239,7 +299,7 @@ function readJsonBody(req) {
                 resolve(JSON.parse(data));
             }
             catch (e) {
-                reject(e instanceof Error ? e : new Error("invalid JSON body"));
+                reject(new InvalidJsonError(e instanceof Error ? e.message : "invalid JSON body"));
             }
         });
         req.on("error", reject);

package/dist/tray.js

@@ -0,0 +1,142 @@
+// System-tray presence for the running daemon — a glanceable "is DataLoom
+// running?" signal for the detached/background mode that has no console or
+// window. Windows-first and dependency-free: a hidden PowerShell helper draws
+// the DataLoom mark, shows a tooltip, and offers Open / Copy / Stop; menu
+// clicks arrive back as stdout lines. Any failure (non-Windows, no PowerShell,
+// headless/session-0, DATA_LOOM_NO_TRAY) is a silent no-op, so the tray never
+// affects the daemon's ability to serve (mirror-not-launcher, DataLoom-only).
+import { spawn } from "node:child_process";
+const NOOP = { dispose: () => { } };
+/**
+ * Show a tray icon for the running daemon. Returns a disposer. Never throws:
+ * on any unsupported/headless host or failure it returns a no-op tray so the
+ * caller can wire it unconditionally.
+ */
+export function initTray(opts) {
+    if (process.env.DATA_LOOM_NO_TRAY)
+        return NOOP;
+    // Windows-first: elsewhere (and headless) we degrade to no tray.
+    if (process.platform !== "win32")
+        return NOOP;
+    try {
+        return startWindowsTray(opts);
+    }
+    catch (err) {
+        opts.log?.(`[data-loom] tray unavailable (continuing without it): ${err instanceof Error ? err.message : err}`);
+        return NOOP;
+    }
+}
+function startWindowsTray(opts) {
+    const script = buildScript(opts.url, process.pid);
+    // -EncodedCommand takes base64 of the UTF-16LE script, sidestepping all shell
+    // quoting. powershell.exe (Windows PowerShell 5.1) runs STA, which WinForms
+    // / NotifyIcon require.
+    const encoded = Buffer.from(script, "utf16le").toString("base64");
+    const child = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encoded], { windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+    let disposed = false;
+    child.stdout?.setEncoding("utf8");
+    let buf = "";
+    child.stdout?.on("data", (chunk) => {
+        buf += chunk;
+        let nl;
+        while ((nl = buf.indexOf("\n")) >= 0) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (!line)
+                continue;
+            if (line === "open")
+                opts.onOpen();
+            else if (line === "copy")
+                opts.onCopy();
+            else if (line === "stop")
+                opts.onStop();
+        }
+    });
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+        // PowerShell serializes its progress/verbose streams to stderr as CLIXML
+        // when piped (e.g. "Preparing modules for first use") — benign noise. Only
+        // surface genuine error records.
+        if (!/S="error"/i.test(chunk))
+            return;
+        opts.log?.(`[data-loom] tray helper error: ${chunk.trim()}`);
+    });
+    child.on("error", (err) => opts.log?.(`[data-loom] tray helper error: ${err.message}`));
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            // Intentionally not killed here: the helper polls for its parent (this
+            // daemon) and, once we exit, disposes its own NotifyIcon and quits — a
+            // clean icon removal. A hard kill would skip that and leave a ghost icon
+            // in the tray until the user hovers it. dispose() is only called during
+            // shutdown, which exits the process immediately afterward.
+            try {
+                child.stdout?.removeAllListeners();
+                child.stderr?.removeAllListeners();
+            }
+            catch {
+                /* nothing to clean up */
+            }
+        },
+    };
+}
+/**
+ * The PowerShell helper. Built as joined lines (no backticks, so it survives a
+ * JS template context) with the URL and parent PID inlined. It draws the woven
+ * DataLoom mark, shows a NotifyIcon with a tooltip and a context menu, reports
+ * menu clicks on stdout, and self-terminates (removing its icon) as soon as the
+ * parent daemon is gone.
+ */
+function buildScript(url, parentPid) {
+    const safeUrl = url.replace(/'/g, "''"); // single-quote escape for PS literal
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        "$ProgressPreference = 'SilentlyContinue'",
+        "Add-Type -AssemblyName System.Windows.Forms",
+        "Add-Type -AssemblyName System.Drawing",
+        "$url = '" + safeUrl + "'",
+        "$parent = " + String(parentPid),
+        // Draw the woven-lattice mark (faint horizontals + accent-blue verticals).
+        "$bmp = New-Object System.Drawing.Bitmap 32,32",
+        "$g = [System.Drawing.Graphics]::FromImage($bmp)",
+        "$g.SmoothingMode = 'AntiAlias'",
+        "$g.Clear([System.Drawing.Color]::Transparent)",
+        "$accent = New-Object System.Drawing.Pen ([System.Drawing.Color]::FromArgb(255,37,99,184)), 2.4",
+        "$faint = New-Object System.Drawing.Pen ([System.Drawing.Color]::FromArgb(255,144,163,190)), 2.4",
+        "foreach ($y in 7,16,25) { $g.DrawLine($faint, 6, $y, 26, $y) }",
+        "foreach ($x in 8,16,24) { $g.DrawLine($accent, $x, 6, $x, 26) }",
+        "$g.Dispose()",
+        "$icon = [System.Drawing.Icon]::FromHandle($bmp.GetHicon())",
+        // Tray icon + tooltip.
+        "$notify = New-Object System.Windows.Forms.NotifyIcon",
+        "$notify.Icon = $icon",
+        "$notify.Text = 'DataLoom - running - ' + $url",
+        "$notify.Visible = $true",
+        // Context menu — DataLoom-only actions, reported to the daemon on stdout.
+        "$menu = New-Object System.Windows.Forms.ContextMenuStrip",
+        "$mOpen = $menu.Items.Add('Open Dashboard')",
+        "$mOpen.add_Click({ try { [Console]::Out.WriteLine('open'); [Console]::Out.Flush() } catch {} })",
+        "$mCopy = $menu.Items.Add('Copy URL')",
+        "$mCopy.add_Click({ try { [Console]::Out.WriteLine('copy'); [Console]::Out.Flush() } catch {} })",
+        "$mStop = $menu.Items.Add('Stop DataLoom')",
+        "$mStop.add_Click({ try { [Console]::Out.WriteLine('stop'); [Console]::Out.Flush() } catch {} })",
+        "$notify.ContextMenuStrip = $menu",
+        // Clean removal of the icon, however we exit.
+        "$cleanup = { try { $notify.Visible = $false } catch {}; try { $notify.Dispose() } catch {}; try { $icon.Dispose() } catch {}; try { $bmp.Dispose() } catch {} }",
+        // Pump WinForms messages (so the icon shows and the menu responds) while the
+        // parent daemon is alive; when it goes, remove our icon and quit. A manual
+        // DoEvents loop keeps $parent/$cleanup in the main scope, avoiding the scope
+        // pitfalls of .NET event-handler scriptblocks. The menu handlers above use
+        // only string literals, so they capture nothing.
+        "try {",
+        "  while (Get-Process -Id $parent -ErrorAction SilentlyContinue) {",
+        "    [System.Windows.Forms.Application]::DoEvents()",
+        "    Start-Sleep -Milliseconds 150",
+        "  }",
+        "} finally {",
+        "  & $cleanup",
+        "}",
+    ].join("\n");
+}

package/dist/version.js

@@ -0,0 +1,18 @@
+// The advertised package version — read from the manifest shipped next to the
+// compiled code, so it can never drift from the released version again (it was
+// hardcoded in mcpServer.ts and stuck at 0.4.1 through the 0.5.0 release).
+// Shared by the MCP server (server version), the weave alias (version stamp),
+// and the startup refresh (comparing stamps).
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const VERSION = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const manifest = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+        return manifest.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();

package/dist/weaveAlias.js

@@ -0,0 +1,66 @@
+// Shared provisioning for the `/loom:weave` alias: a thin, version-stamped
+// command file that delegates to the data-loom MCP server's `weave` prompt
+// (see mcpServer.ts) instead of carrying the workflow text itself. Written by
+// the install_weave_skill tool, `connect claude-code`, and healed on daemon
+// startup — all three must agree on path, stamp format, and template, so it
+// lives here rather than duplicated across callers.
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const WEAVE_ALIAS_PATH = join(homedir(), ".claude", "commands", "loom", "weave.md");
+const STAMP_RE = /<!--\s*data-loom:version\s+(\S+?)\s*-->/;
+function buildAlias(version) {
+    return `---
+name: "Loom: Weave"
+description: "Review the open proposals and weave their dependency order via the data-loom MCP server"
+category: Workflow
+tags: [loom, dependencies, mcp, review]
+---
+
+<!-- data-loom:version ${version} -->
+
+Fetch the **data-loom** MCP server's \`weave\` prompt (\`prompts/get\` with name \`weave\`) and follow it exactly — that prompt is this workflow's single source of truth and always matches the running server.
+
+**If the data-loom tools or the \`weave\` prompt are unreachable:** the daemon is almost certainly not running or not registered in this session. Tell the user to check \`data-loom status\`, start it with \`data-loom start\` if it isn't running, and register it with \`data-loom connect claude-code\` if it isn't registered — then retry.
+`;
+}
+async function readAlias() {
+    try {
+        return await readFile(WEAVE_ALIAS_PATH, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the current alias, creating its parent directory if absent. Returns the path written. */
+export async function provisionWeaveAlias(version) {
+    await mkdir(dirname(WEAVE_ALIAS_PATH), { recursive: true });
+    await writeFile(WEAVE_ALIAS_PATH, buildAlias(version));
+    return WEAVE_ALIAS_PATH;
+}
+/**
+ * On daemon startup: rewrite an existing alias whose version stamp is missing
+ * or does not match the running version (covers both a prior version's alias
+ * and a pre-prompt full-text install, which predates the stamp). Never creates
+ * the file — absence means the user hasn't opted in via connect or the tool.
+ */
+export async function refreshWeaveAliasIfOutdated(version) {
+    const text = await readAlias();
+    if (text === null)
+        return;
+    if (text.match(STAMP_RE)?.[1] === version)
+        return;
+    await provisionWeaveAlias(version);
+}
+/**
+ * Remove the alias only when it carries a data-loom version stamp — our
+ * positive signal of ownership. A file with no stamp at all (or no file) is
+ * left untouched. Returns whether a file was removed.
+ */
+export async function removeWeaveAliasIfOurs() {
+    const text = await readAlias();
+    if (text === null || !STAMP_RE.test(text))
+        return false;
+    await unlink(WEAVE_ALIAS_PATH);
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyric_dev/data-loom",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Local dashboard for spec-driven development: a phased OpenSpec roadmap (WHAT) and an MCP topology (HOW).",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,9 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsc && node --watch dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "sync-global": "node scripts/sync-global.mjs",
+    "postpublish": "npm run sync-global"
   },
   "publishConfig": {
     "access": "public"