@lyric_dev/data-loom 0.4.1 → 0.5.0

package/README.md

@@ -38,6 +38,31 @@ With no argument it uses the current directory. Then open <http://127.0.0.1:4317
 
 > Published to npm automatically by CI on version tags (`vX.Y.Z`) via GitHub Actions.
 
+## Run it always-on (background + autostart)
+
+The command above runs in the foreground and stops when you close the terminal. Since the daemon also hosts the MCP endpoint, you usually want it always running. Manage a detached background daemon with:
+
+```
+data-loom start [C:\path\to\project]   # launch detached; returns immediately
+data-loom status                       # is it running? where are the logs?
+data-loom stop                         # stop the background daemon
+data-loom restart [path]               # stop then start
+```
+
+There is at most one instance: `start` while one is already running is a no-op that just reports it. Background output goes to a log file (path shown by `status`) since there's no attached console — on Windows, `%LOCALAPPDATA%\data-loom\daemon.log` (macOS `~/Library/Application Support/data-loom/`, Linux `${XDG_STATE_HOME:-~/.local/state}/data-loom/`).
+
+To have it launch automatically when you log in:
+
+```
+data-loom autostart enable    # register a per-user login item AND start it now
+data-loom autostart status    # is autostart registered?
+data-loom autostart disable   # remove the login item (does not stop a running daemon)
+```
+
+`enable` also starts the daemon immediately; pass `--no-start` to only register for next login. The login item is per-user and needs no admin rights — a Startup-folder shortcut on Windows, a LaunchAgent on macOS, an XDG autostart entry on Linux.
+
+Everything is reversible: `data-loom stop`, `data-loom autostart disable`, and `data-loom disconnect claude-desktop` (below) undo each side effect, and each is idempotent.
+
 ## Run from source (development)
 
 Requires Node.js ≥ 20.
@@ -66,7 +91,15 @@ The running daemon also **hosts an MCP server** over HTTP, so your own Claude se
    claude mcp add --transport http --scope user data-loom http://127.0.0.1:4317/mcp
    ```
 
-   The MCP server lives in the daemon, so **DataLoom must be running** for the tools to be reachable (start it with `npx @lyric_dev/data-loom "C:\path\to\your\project"`). It binds to loopback only.
+   The MCP server lives in the daemon, so **DataLoom must be running** for the tools to be reachable (start it with `data-loom start` or `npx @lyric_dev/data-loom "C:\path\to\your\project"`). It binds to loopback only.
+
+   **Claude Desktop** reaches the same daemon — register it with:
+
+   ```
+   data-loom connect claude-desktop
+   ```
+
+   This adds a `data-loom` entry to Claude Desktop's `claude_desktop_config.json` (additively — your other servers are untouched), pointing at the same loopback endpoint via Claude Desktop's native remote-MCP support. Restart Claude Desktop to pick it up. On older Claude Desktop versions without native remote support, pass `--bridge` to register a stdio↔HTTP bridge (`npx mcp-remote`) instead. Remove it any time with `data-loom disconnect claude-desktop`. As with Claude Code, the daemon must be running for the tools to appear.
 
 2. In any project, ask Claude something like *"review DataLoom's open proposals and set the dependencies."* On connect, the server asks Claude to surface any proposal that hasn't been reviewed for dependencies yet, propose the edges, and **confirm with you before writing**. It exposes these tools:
    - `list_projects` — the selectable OpenSpec workspaces plus the current selection (read-only), to discover/confirm a `project` path.

package/dist/autostart.js

@@ -0,0 +1,141 @@
+// Per-user login autostart: register the background daemon to launch when the
+// user logs in, using the native, no-elevation mechanism for each OS —
+//   Windows  a shortcut in the per-user Startup folder
+//   macOS    a LaunchAgent plist with RunAtLoad
+//   Linux    an XDG autostart .desktop entry
+// Every registration launches `<node> <script> start`, so a login-triggered
+// launch shares the exact same detached/single-instance/logging path as a
+// manual `data-loom start`.
+import { spawn } from "node:child_process";
+import { writeFile, rm, access, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const NODE = process.execPath;
+const SCRIPT = process.argv[1];
+const LABEL = "dev.lyric.data-loom";
+function exists(p) {
+    return access(p).then(() => true, () => false);
+}
+// ---- Windows: Startup-folder shortcut -------------------------------------
+function winStartupLnk() {
+    const appData = process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+    return join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "data-loom.lnk");
+}
+function runPowerShell(script) {
+    return new Promise((resolve, reject) => {
+        const ps = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { windowsHide: true, stdio: "ignore" });
+        ps.on("error", reject);
+        ps.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`powershell exited ${code}`))));
+    });
+}
+async function winEnable() {
+    const lnk = winStartupLnk();
+    await mkdir(dirname(lnk), { recursive: true });
+    // Create the .lnk via WScript.Shell; WindowStyle 7 = minimized so the brief
+    // launcher console doesn't grab focus (the daemon itself is detached).
+    const q = (s) => `'${s.replace(/'/g, "''")}'`;
+    await runPowerShell([
+        "$s = (New-Object -ComObject WScript.Shell).CreateShortcut(" + q(lnk) + ")",
+        "$s.TargetPath = " + q(NODE),
+        '$s.Arguments = ' + q(`"${SCRIPT}" start`),
+        "$s.WindowStyle = 7",
+        "$s.Description = 'DataLoom background daemon'",
+        "$s.Save()",
+    ].join("; "));
+}
+async function winDisable() {
+    await rm(winStartupLnk(), { force: true }).catch(() => { });
+}
+// ---- macOS: LaunchAgent ----------------------------------------------------
+function macPlistPath() {
+    return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+async function macEnable() {
+    const path = macPlistPath();
+    await mkdir(dirname(path), { recursive: true });
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${NODE}</string>
+    <string>${SCRIPT}</string>
+    <string>start</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+</dict>
+</plist>
+`;
+    await writeFile(path, plist, "utf8");
+    await new Promise((resolve) => {
+        const p = spawn("launchctl", ["load", "-w", path], { stdio: "ignore" });
+        p.on("error", () => resolve()); // best-effort; the plist is written regardless
+        p.on("exit", () => resolve());
+    });
+}
+async function macDisable() {
+    const path = macPlistPath();
+    if (await exists(path)) {
+        await new Promise((resolve) => {
+            const p = spawn("launchctl", ["unload", "-w", path], { stdio: "ignore" });
+            p.on("error", () => resolve());
+            p.on("exit", () => resolve());
+        });
+    }
+    await rm(path, { force: true }).catch(() => { });
+}
+// ---- Linux: XDG autostart --------------------------------------------------
+function linuxDesktopPath() {
+    const cfg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(cfg, "autostart", "data-loom.desktop");
+}
+async function linuxEnable() {
+    await mkdir(dirname(linuxDesktopPath()), { recursive: true });
+    const entry = `[Desktop Entry]
+Type=Application
+Name=DataLoom
+Comment=DataLoom background daemon
+Exec="${NODE}" "${SCRIPT}" start
+X-GNOME-Autostart-enabled=true
+`;
+    await writeFile(linuxDesktopPath(), entry, "utf8");
+}
+async function linuxDisable() {
+    await rm(linuxDesktopPath(), { force: true }).catch(() => { });
+}
+// ---- Dispatch --------------------------------------------------------------
+function unsupported() {
+    throw new Error(`[data-loom] autostart is not supported on platform "${process.platform}"`);
+}
+/** Register the daemon to launch at login (idempotent — overwrites any prior). */
+export async function enable() {
+    if (process.platform === "win32")
+        return winEnable();
+    if (process.platform === "darwin")
+        return macEnable();
+    if (process.platform === "linux")
+        return linuxEnable();
+    unsupported();
+}
+/** Remove the login registration (idempotent — succeeds when not enabled). */
+export async function disable() {
+    if (process.platform === "win32")
+        return winDisable();
+    if (process.platform === "darwin")
+        return macDisable();
+    if (process.platform === "linux")
+        return linuxDisable();
+    unsupported();
+}
+/** True iff a login registration currently exists for this user. */
+export async function isEnabled() {
+    if (process.platform === "win32")
+        return exists(winStartupLnk());
+    if (process.platform === "darwin")
+        return exists(macPlistPath());
+    if (process.platform === "linux")
+        return exists(linuxDesktopPath());
+    return false;
+}

package/dist/claudeDesktop.js

@@ -0,0 +1,82 @@
+// Claude Desktop integration: register DataLoom's loopback MCP endpoint into
+// Claude Desktop's claude_desktop_config.json so the same running daemon that
+// serves Claude Code also serves Claude Desktop.
+//
+// By default we write the native remote/HTTP form (a URL entry) — no extra
+// process, one daemon as the single source of truth. Claude Desktop versions
+// without native remote support use the stdio bridge (`npx mcp-remote <url>`),
+// which the caller forces with `--bridge`. Either way the daemon needs no change:
+// it already permits native (no-Origin) MCP clients on loopback.
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { mcpUrl } from "./paths.js";
+const KEY = "data-loom";
+/** Per-OS location of Claude Desktop's config file. */
+export function configPath() {
+    if (process.platform === "win32") {
+        const appData = process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+        return join(appData, "Claude", "claude_desktop_config.json");
+    }
+    if (process.platform === "darwin") {
+        return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    const cfg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(cfg, "Claude", "claude_desktop_config.json");
+}
+/** Read + parse the config, or return {} when absent. Throws on malformed JSON. */
+async function readConfig(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return {};
+    }
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null) {
+            throw new Error("not a JSON object");
+        }
+        return parsed;
+    }
+    catch (e) {
+        throw new Error(`[data-loom] ${path} is not valid JSON (${e instanceof Error ? e.message : "parse error"}); ` +
+            "fix or remove it, then retry — DataLoom will not overwrite it.");
+    }
+}
+async function writeConfig(path, cfg) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+/** The MCP entry we register — native URL form by default, stdio bridge on demand. */
+function entry(bridge) {
+    const url = mcpUrl();
+    return bridge ? { command: "npx", args: ["-y", "mcp-remote", url] } : { type: "http", url };
+}
+/**
+ * Add/update DataLoom's entry under mcpServers, preserving everything else.
+ * Returns the path written so the caller can report it.
+ */
+export async function connect(opts = {}) {
+    const path = configPath();
+    const cfg = await readConfig(path);
+    cfg.mcpServers = { ...(cfg.mcpServers ?? {}), [KEY]: entry(opts.bridge ?? false) };
+    await writeConfig(path, cfg);
+    return path;
+}
+/**
+ * Remove only DataLoom's entry. Idempotent — returns false when nothing was
+ * registered (so the caller can say "nothing to remove").
+ */
+export async function disconnect() {
+    const path = configPath();
+    const cfg = await readConfig(path);
+    if (!cfg.mcpServers || !(KEY in cfg.mcpServers))
+        return { path, removed: false };
+    delete cfg.mcpServers[KEY];
+    await writeConfig(path, cfg);
+    return { path, removed: true };
+}

package/dist/index.js

@@ -12,8 +12,12 @@ import { discover } from "./mcp/discovery.js";
 import { checkServer } from "./mcp/availability.js";
 import { discoverProjects, isViewableProject } from "./projects.js";
 import { resolvePublicDir } from "./assets.js";
-const host = "127.0.0.1";
-const port = Number(process.env.PORT ?? 4317);
+import { HOST, PORT } from "./paths.js";
+import * as lifecycle from "./lifecycle.js";
+import * as autostart from "./autostart.js";
+import * as claudeDesktop from "./claudeDesktop.js";
+const host = HOST;
+const port = PORT;
 // Initial project: CLI argument, then DATA_LOOM_ROOT, then cwd.
 const initialProject = resolve(process.argv[2] ?? process.env.DATA_LOOM_ROOT ?? process.cwd());
 let session;
@@ -124,7 +128,9 @@ function getProjects() {
     return discoverProjects(session?.project ?? "");
 }
 function openBrowser(url) {
-    if (process.env.DATA_LOOM_NO_OPEN)
+    // Detached background runs have no attached console and no user waiting at the
+    // terminal, so never pop a browser for them (nor when explicitly suppressed).
+    if (process.env.DATA_LOOM_NO_OPEN || process.env.DATA_LOOM_DETACHED)
         return;
     try {
         if (process.platform === "win32") {
@@ -141,7 +147,82 @@ function openBrowser(url) {
         /* non-fatal — the URL is already logged */
     }
 }
-main().catch((err) => {
-    console.error(err);
-    process.exit(1);
-});
+// ---- CLI verb dispatch -----------------------------------------------------
+// A leading reserved verb selects a lifecycle/autostart/integration command;
+// anything else falls through to the foreground daemon (with argv[2] as the
+// optional project path), preserving the original invocation unchanged.
+const VERBS = new Set(["start", "stop", "restart", "status", "autostart", "connect", "disconnect"]);
+async function runAutostart(rest) {
+    const sub = rest[0];
+    if (sub === "enable") {
+        await autostart.enable();
+        console.log("[data-loom] autostart enabled (launches on login)");
+        // Enabling also brings the daemon up now, so it's running this session too —
+        // opt out with --no-start.
+        if (!rest.includes("--no-start"))
+            await lifecycle.start();
+        return;
+    }
+    if (sub === "disable") {
+        await autostart.disable();
+        console.log("[data-loom] autostart disabled");
+        return;
+    }
+    if (sub === "status") {
+        console.log((await autostart.isEnabled())
+            ? "[data-loom] autostart is enabled"
+            : "[data-loom] autostart is not enabled");
+        return;
+    }
+    throw new Error("usage: data-loom autostart <enable|disable|status> [--no-start]");
+}
+async function runConnect(rest) {
+    if (rest[0] !== "claude-desktop")
+        throw new Error("usage: data-loom connect claude-desktop [--bridge]");
+    const bridge = rest.includes("--bridge");
+    const path = await claudeDesktop.connect({ bridge });
+    console.log(`[data-loom] registered DataLoom in Claude Desktop (${bridge ? "stdio bridge" : "native HTTP"}) — ${path}`);
+    console.log("[data-loom] restart Claude Desktop to pick it up; DataLoom must be running to serve the tools.");
+}
+async function runDisconnect(rest) {
+    if (rest[0] !== "claude-desktop")
+        throw new Error("usage: data-loom disconnect claude-desktop");
+    const { path, removed } = await claudeDesktop.disconnect();
+    console.log(removed
+        ? `[data-loom] removed DataLoom from Claude Desktop — ${path}`
+        : "[data-loom] DataLoom was not registered in Claude Desktop — nothing to remove");
+}
+async function runCli(argv) {
+    const [verb, ...rest] = argv;
+    switch (verb) {
+        case "start":
+            return lifecycle.start(rest[0]);
+        case "stop":
+            return lifecycle.stop();
+        case "restart":
+            return lifecycle.restart(rest[0]);
+        case "status":
+            return lifecycle.status();
+        case "autostart":
+            return runAutostart(rest);
+        case "connect":
+            return runConnect(rest);
+        case "disconnect":
+            return runDisconnect(rest);
+        default:
+            throw new Error(`unknown command: ${verb}`);
+    }
+}
+const cliArgs = process.argv.slice(2);
+if (cliArgs[0] && VERBS.has(cliArgs[0])) {
+    runCli(cliArgs).catch((err) => {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}
+else {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/dist/lifecycle.js

@@ -0,0 +1,101 @@
+// Background lifecycle for the daemon: start it detached, stop it, restart it,
+// and report status. The loopback port is the authoritative "is it running?"
+// signal — a stale PID file never blocks a start, because the source of truth is
+// whether something actually answers on the port.
+import { spawn } from "node:child_process";
+import { openSync } from "node:fs";
+import { readFile, writeFile, rm } from "node:fs/promises";
+import { get } from "node:http";
+import { HOST, PORT, baseUrl, logFile, pidFile, ensureStateDir } from "./paths.js";
+/** Probe the loopback endpoint; true iff a daemon answers within the timeout. */
+export function isRunning() {
+    return new Promise((resolve) => {
+        const req = get({ host: HOST, port: PORT, path: "/api/model", timeout: 1000 }, (res) => {
+            res.resume(); // drain
+            resolve(true);
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+async function readPid() {
+    try {
+        const n = Number((await readFile(pidFile(), "utf8")).trim());
+        return Number.isInteger(n) && n > 0 ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Start the daemon detached from this terminal. If one already answers on the
+ * port, this is a reported no-op (single-instance guard). The child re-runs this
+ * same entry point in the foreground with DATA_LOOM_DETACHED set so it skips the
+ * browser and logs to the state-dir log file.
+ */
+export async function start(project) {
+    if (await isRunning()) {
+        console.log(`[data-loom] already running — ${baseUrl()}`);
+        return;
+    }
+    await ensureStateDir();
+    const out = openSync(logFile(), "a");
+    const args = [process.argv[1], ...(project ? [project] : [])];
+    const child = spawn(process.execPath, args, {
+        detached: true,
+        windowsHide: true,
+        stdio: ["ignore", out, out],
+        env: { ...process.env, DATA_LOOM_DETACHED: "1" },
+    });
+    child.unref();
+    if (child.pid)
+        await writeFile(pidFile(), String(child.pid), "utf8");
+    console.log(`[data-loom] started in background (pid ${child.pid ?? "?"}) — ${baseUrl()}`);
+    console.log(`[data-loom] logs: ${logFile()}`);
+}
+/** Stop the background daemon; a no-op (with notice) when nothing is running. */
+export async function stop() {
+    const pid = await readPid();
+    const running = await isRunning();
+    if (!running && pid === undefined) {
+        console.log("[data-loom] not running — nothing to stop");
+        return;
+    }
+    if (pid !== undefined) {
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    else if (running) {
+        console.error("[data-loom] a daemon is answering the port but no PID file was found; stop it manually");
+        return;
+    }
+    // Wait for the port to actually free (up to ~5s), then drop the PID file.
+    for (let i = 0; i < 25 && (await isRunning()); i++)
+        await delay(200);
+    await rm(pidFile(), { force: true }).catch(() => { });
+    console.log("[data-loom] stopped");
+}
+/** Restart: stop any running instance, then start a fresh one. */
+export async function restart(project) {
+    await stop();
+    await start(project);
+}
+/** Report whether the daemon is running, and where to reach it / find its logs. */
+export async function status() {
+    if (await isRunning()) {
+        const pid = await readPid();
+        console.log(`[data-loom] running — ${baseUrl()}${pid !== undefined ? ` (pid ${pid})` : ""}`);
+        console.log(`[data-loom] logs: ${logFile()}`);
+    }
+    else {
+        console.log("[data-loom] not running");
+    }
+}

package/dist/paths.js

@@ -0,0 +1,39 @@
+// Shared config + per-user state locations for the daemon and its CLI verbs.
+// The lifecycle commands (start/stop/status), autostart registration, and the
+// Claude Desktop integration all need to agree on the loopback address, the
+// state directory, and the PID/log paths — so they live here, in one place.
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Loopback host + port the daemon binds. Port overridable via env for tests. */
+export const HOST = "127.0.0.1";
+export const PORT = Number(process.env.PORT ?? 4317);
+/** Dashboard base URL and the MCP endpoint hosted on the same authority. */
+export const baseUrl = () => `http://${HOST}:${PORT}`;
+export const mcpUrl = () => `${baseUrl()}/mcp`;
+/**
+ * Per-user state directory, using the OS convention:
+ *   Windows  %LOCALAPPDATA%\data-loom
+ *   macOS    ~/Library/Application Support/data-loom
+ *   Linux    ${XDG_STATE_HOME:-~/.local/state}/data-loom
+ * Holds the PID file and the background log — never the project dir.
+ */
+export function stateDir() {
+    if (process.platform === "win32") {
+        const local = process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local");
+        return join(local, "data-loom");
+    }
+    if (process.platform === "darwin") {
+        return join(homedir(), "Library", "Application Support", "data-loom");
+    }
+    const xdg = process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+    return join(xdg, "data-loom");
+}
+export const pidFile = () => join(stateDir(), "daemon.pid");
+export const logFile = () => join(stateDir(), "daemon.log");
+/** Create the state dir on demand; safe to call repeatedly. */
+export async function ensureStateDir() {
+    const dir = stateDir();
+    await mkdir(dir, { recursive: true });
+    return dir;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyric_dev/data-loom",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Local dashboard for spec-driven development: a phased OpenSpec roadmap (WHAT) and an MCP topology (HOW).",
   "type": "module",
   "license": "MIT",