@lyric_dev/data-loom 0.2.4

package/dist/mcp/types.js

@@ -0,0 +1,3 @@
+// MCP topology model. Only sanitized data here ever reaches the browser —
+// ProbeTarget (with real command/url) stays inside the daemon.
+export {};

package/dist/mcpServer.js

@@ -0,0 +1,234 @@
+// data_loom as an MCP server: exposes the open proposals (read) and a
+// dependency-writing action (write `## Depends On`) so an MCP client — the
+// user's own authenticated Claude — can determine and apply the order.
+// Holds no credentials; tools carry only proposal text and change names.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { OpenSpecClient } from "./openspecClient.js";
+import { deriveModel } from "./derive.js";
+// Advertised to the client on connect. The "confirm before writing" gate lives
+// here, in the agent's behavior — the server cannot verify a human approved.
+const INSTRUCTIONS = `This server exposes a project's open OpenSpec proposals and lets you record the dependency order between them. It holds no model and cannot infer anything on its own — the judgment is yours and the decision is the user's.
+
+When you connect, call list_open_proposals and look at each proposal's "dependencyReview" field. For every proposal whose state is "pending" (it has no \`## Depends On\` declaration yet):
+  1. Read its proposal text alongside the others and reason about which changes it should be implemented after.
+  2. PROPOSE the dependencies — or that it is independent — to the user in plain language, with your reasoning.
+  3. Only AFTER the user confirms, record the result: call set_dependency(from, to) for each confirmed edge, or mark_independent(change) for a change that genuinely depends on nothing.
+
+Never write a dependency the user has not confirmed. Proposals already marked "declared" need no action.
+
+Tip: call install_weave_skill once to add a \`/loom:weave\` command (written to the user's global Claude config) that runs this whole review in one step; the user reloads Claude Code to pick it up.`;
+// The `/loom:weave` slash command this server installs into the user's global
+// Claude commands dir. Static content that only orchestrates this server's tools.
+const WEAVE_COMMAND = `---
+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]
+---
+
+Weave the dependency order of this project's open OpenSpec proposals, using the **data-loom** MCP server.
+
+**Prerequisite:** the data-loom MCP server must be registered in this session — its tools are \`list_open_proposals\`, \`set_dependency\`, and \`mark_independent\`. If those tools are not available, tell the user to register it (\`claude mcp add data-loom -- npx data-loom mcp "<project path>"\`) and stop.
+
+Steps:
+
+1. Call \`list_open_proposals\` and note each proposal's \`dependencyReview\` state.
+2. Focus on the proposals whose state is \`pending\` (no \`## Depends On\` declaration yet). Proposals already \`declared\` need no action — leave them alone.
+3. Read the pending proposals alongside the others. Reason about which change should be implemented **after** which, from their capabilities and content: a change that extends or modifies what another change introduces depends on it; changes that touch disjoint areas are independent.
+4. **Propose** your conclusion to the user in plain language — for each pending proposal, the dependencies you would record (or that it is independent), each with a one-line reason. Do not write anything yet.
+5. **Wait for the user to confirm.** Never write a dependency the user has not approved.
+6. After the user confirms, record it:
+   - \`set_dependency(from, to)\` for each confirmed edge (the dependent is \`from\`).
+   - \`mark_independent(change)\` for a proposal the user confirms depends on nothing.
+7. Call \`list_open_proposals\` again and report the resulting phases — what moved, and what is now ready versus blocked.
+
+The reasoning stays the user's to approve: you surface and apply, the user decides.
+`;
+export async function runMcpServer(project) {
+    const client = new OpenSpecClient(project);
+    const changesDir = join(project, "openspec", "changes");
+    const server = new Server({ name: "data-loom", version: "0.2.4" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "list_open_proposals",
+                description: "List the open (non-archived) OpenSpec proposals for this project, each with its proposal text (Why / What Changes / Capabilities) and currently derived dependencies, phase, and readiness. Use this to reason about which proposals should be implemented after which.",
+                inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            },
+            {
+                name: "set_dependency",
+                description: "Declare that one open proposal depends on (should be implemented after) another by writing a `## Depends On` entry into the dependent's proposal. The roadmap then recomputes deterministically from that file.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        from: { type: "string", description: "The dependent change (gets the `## Depends On` entry)" },
+                        to: { type: "string", description: "The change it depends on" },
+                    },
+                    required: ["from", "to"],
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: "mark_independent",
+                description: "Record that an open proposal depends on nothing by writing an empty `## Depends On` declaration into it. Use this — only after the user confirms — for a change that is genuinely parallel, so it moves from `pending` to `declared` dependency review without adding any edge. Validates the change is a known open change and is idempotent.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        change: { type: "string", description: "The open change to mark as having no dependencies" },
+                    },
+                    required: ["change"],
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: "install_weave_skill",
+                description: "Install the `/loom:weave` slash command into the user's global Claude commands directory (~/.claude/commands/loom/weave.md), so this dependency review can be run as a single command from any project where this server is registered. Writes a static command file only (no project data or secrets) and overwrites any existing copy. Run once, then the user reloads Claude Code.",
+                inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        try {
+            if (name === "list_open_proposals") {
+                return ok(await listOpenProposals(client, changesDir));
+            }
+            if (name === "set_dependency") {
+                const from = String(args?.from ?? "");
+                const to = String(args?.to ?? "");
+                return ok(await setDependency(client, changesDir, from, to));
+            }
+            if (name === "mark_independent") {
+                const change = String(args?.change ?? "");
+                return ok(await markIndependent(client, changesDir, change));
+            }
+            if (name === "install_weave_skill") {
+                return ok(await installWeaveSkill());
+            }
+            return err(`unknown tool: ${name}`);
+        }
+        catch (e) {
+            return err(e instanceof Error ? e.message : String(e));
+        }
+    });
+    await server.connect(new StdioServerTransport());
+    // Logs go to stderr so they don't corrupt the stdio JSON-RPC channel.
+    console.error(`[data-loom mcp] serving project ${project}`);
+}
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function err(message) {
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+async function openChanges(client) {
+    const model = await deriveModel(client);
+    return model.changes.filter((c) => !c.archived);
+}
+async function listOpenProposals(client, changesDir) {
+    const changes = await openChanges(client);
+    const proposals = [];
+    for (const c of changes) {
+        let proposal = "";
+        try {
+            proposal = await readFile(join(changesDir, c.name, "proposal.md"), "utf8");
+        }
+        catch {
+            /* no proposal yet */
+        }
+        proposals.push({
+            name: c.name,
+            phase: c.phase,
+            readiness: c.readiness,
+            dependencyReview: c.dependencyReview, // "pending" until a `## Depends On` block exists
+            dependsOn: c.dependsOn,
+            newCapabilities: c.newCapabilities,
+            modifiedCapabilities: c.modifiedCapabilities,
+            proposal, // proposal text only — never config, env, or secrets
+        });
+    }
+    return { proposals };
+}
+async function setDependency(client, changesDir, from, to) {
+    if (!from || !to)
+        throw new Error("both 'from' and 'to' are required");
+    if (from === to)
+        throw new Error("a change cannot depend on itself");
+    const names = new Set((await openChanges(client)).map((c) => c.name));
+    if (!names.has(from))
+        throw new Error(`unknown open change: ${from}`);
+    if (!names.has(to))
+        throw new Error(`unknown open change: ${to}`);
+    const path = join(changesDir, from, "proposal.md");
+    const text = await readFile(path, "utf8");
+    const updated = addDependsOn(text, to);
+    const written = updated !== text;
+    if (written)
+        await writeFile(path, updated);
+    return { from, to, written, dependsOn: await client.readProposalDependsOn(from) };
+}
+async function markIndependent(client, changesDir, change) {
+    if (!change)
+        throw new Error("'change' is required");
+    const names = new Set((await openChanges(client)).map((c) => c.name));
+    if (!names.has(change))
+        throw new Error(`unknown open change: ${change}`);
+    const path = join(changesDir, change, "proposal.md");
+    const text = await readFile(path, "utf8");
+    const updated = ensureDependsOnSection(text);
+    const written = updated !== text; // already declared -> idempotent no-op
+    if (written)
+        await writeFile(path, updated);
+    return { change, written, dependencyReview: "declared" };
+}
+/**
+ * Provision the `/loom:weave` command into the user's GLOBAL Claude commands
+ * dir, so the review runs as one command from any project where this server is
+ * registered. Writes only the static command file; overwrites in place.
+ */
+async function installWeaveSkill() {
+    const dir = join(homedir(), ".claude", "commands", "loom");
+    const path = join(dir, "weave.md");
+    await mkdir(dir, { recursive: true });
+    await writeFile(path, WEAVE_COMMAND);
+    return {
+        installed: true,
+        command: "/loom:weave",
+        path,
+        note: "Reload Claude Code (restart the session) to pick up the new /loom:weave command.",
+    };
+}
+/** Add `- <dep>` under a `## Depends On` section, creating the section if absent. */
+function addDependsOn(text, dep) {
+    const lines = text.split("\n");
+    const headerIdx = lines.findIndex((l) => /^##\s+Depends On\b/.test(l));
+    const bullet = `- ${dep}`;
+    if (headerIdx === -1) {
+        return `${text.replace(/\s*$/, "")}\n\n## Depends On\n${bullet}\n`;
+    }
+    let end = headerIdx + 1;
+    while (end < lines.length && !/^#{1,6}\s/.test(lines[end]))
+        end++;
+    const escaped = dep.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const present = lines
+        .slice(headerIdx + 1, end)
+        .some((l) => new RegExp(`^-\\s+\`?${escaped}\`?\\s*$`).test(l.trim()));
+    if (present)
+        return text;
+    let insert = end;
+    while (insert > headerIdx + 1 && lines[insert - 1].trim() === "")
+        insert--;
+    lines.splice(insert, 0, bullet);
+    return lines.join("\n");
+}
+/** Ensure an empty `## Depends On` section exists. Idempotent: unchanged if a heading is already present. */
+function ensureDependsOnSection(text) {
+    if (/(?:^|\n)##\s+Depends On\b/.test(text))
+        return text;
+    return `${text.replace(/\s*$/, "")}\n\n## Depends On\n`;
+}

package/dist/openspecClient.js

@@ -0,0 +1,145 @@
+// Thin wrapper around the `openspec` CLI plus the small amount of structured
+// proposal metadata the CLI does not expose (capability ownership).
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+const execFileP = promisify(execFile);
+export class OpenSpecClient {
+    repoRoot;
+    constructor(repoRoot) {
+        this.repoRoot = repoRoot;
+    }
+    openspecDir() {
+        return join(this.repoRoot, "openspec");
+    }
+    /** On Windows the CLI is a `.cmd` shim, so it must be invoked through a shell. */
+    async run(args) {
+        const { stdout } = await execFileP("openspec", args, {
+            cwd: this.repoRoot,
+            shell: process.platform === "win32",
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    async runJson(args) {
+        return parseLooseJson(await this.run(args));
+    }
+    /** Resolves to the CLI version string, or throws if the CLI is missing. */
+    async checkAvailable() {
+        return (await this.run(["--version"])).trim();
+    }
+    async listChanges() {
+        const data = await this.runJson(["list", "--json"]);
+        return data.changes ?? [];
+    }
+    /** Distinct (capability, operation) pairs for a change, from the CLI. */
+    async showDeltas(name) {
+        const data = await this.runJson([
+            "show",
+            name,
+            "--json",
+        ]);
+        const seen = new Set();
+        const out = [];
+        for (const d of data.deltas ?? []) {
+            const key = `${d.spec}|${d.operation}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push({ spec: d.spec, operation: d.operation });
+            }
+        }
+        return out;
+    }
+    /** Capability ownership — read from the proposal, since the CLI does not expose it. */
+    async readProposalCaps(name) {
+        const path = join(this.openspecDir(), "changes", name, "proposal.md");
+        let text;
+        try {
+            text = await readFile(path, "utf8");
+        }
+        catch {
+            return { newCaps: [], modifiedCaps: [] };
+        }
+        return {
+            newCaps: capsInSection(text, "New Capabilities"),
+            modifiedCaps: capsInSection(text, "Modified Capabilities"),
+        };
+    }
+    /** Explicit cross-proposal dependencies declared under a `## Depends On` section. */
+    async readProposalDependsOn(name) {
+        const path = join(this.openspecDir(), "changes", name, "proposal.md");
+        try {
+            return dependsOnInSection(await readFile(path, "utf8"));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Whether the proposal declares a `## Depends On` section at all — even an
+     * empty one. Distinct from {@link readProposalDependsOn}, which reports the
+     * entries: a present-but-empty section means "reviewed, depends on nothing".
+     */
+    async hasDependsOnSection(name) {
+        const path = join(this.openspecDir(), "changes", name, "proposal.md");
+        try {
+            return DEPENDS_ON_HEADING.test(await readFile(path, "utf8"));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Archived change names (completed nodes shown in the done band). */
+    async listArchived() {
+        return this.listDirNames(join(this.openspecDir(), "changes", "archive"));
+    }
+    /** Settled capabilities already in the spec baseline. */
+    async listBaselineCapabilities() {
+        return this.listDirNames(join(this.openspecDir(), "specs"));
+    }
+    async listDirNames(dir) {
+        try {
+            const entries = await readdir(dir, { withFileTypes: true });
+            return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+        }
+        catch {
+            return [];
+        }
+    }
+}
+/** Parse JSON that may be preceded by CLI warning lines on stdout. */
+function parseLooseJson(s) {
+    const start = s.search(/[[{]/);
+    if (start < 0) {
+        throw new Error(`No JSON found in openspec CLI output: ${s.slice(0, 160)}`);
+    }
+    return JSON.parse(s.slice(start));
+}
+/** The `## Depends On` section heading — used for both detection and parsing. */
+const DEPENDS_ON_HEADING = /(?:^|\n)##\s+Depends On\b/;
+/** Extract `- <change-name>` bullets under a `## Depends On` heading. */
+function dependsOnInSection(text) {
+    const m = /(?:^|\n)##\s+Depends On\s*([\s\S]*?)(?:\n##\s|\n#\s|$)/.exec(text);
+    if (!m)
+        return [];
+    const out = [];
+    const bullet = /^-\s+`?([a-z0-9-]+)`?/gm;
+    let mm;
+    while ((mm = bullet.exec(m[1])) !== null)
+        out.push(mm[1]);
+    return out;
+}
+/** Extract `- \`cap-name\`: ...` bullets under a `### <heading>` block. */
+function capsInSection(text, heading) {
+    const re = new RegExp(`###\\s+${heading}([\\s\\S]*?)(?:\\n###\\s|\\n##\\s|$)`);
+    const m = re.exec(text);
+    if (!m)
+        return [];
+    const caps = [];
+    const bullet = /^-\s+`([a-z0-9-]+)`/gm;
+    let mm;
+    while ((mm = bullet.exec(m[1])) !== null)
+        caps.push(mm[1]);
+    return caps;
+}

package/dist/projects.js

@@ -0,0 +1,46 @@
+// Discover selectable projects from Claude Code's known projects, limited to
+// those that actually contain an openspec/ workspace.
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, basename } from "node:path";
+/** True when the directory contains an openspec/ workspace. */
+export function isViewableProject(path) {
+    return existsSync(join(path, "openspec"));
+}
+export async function discoverProjects(active) {
+    const byNorm = new Map();
+    const add = (path) => {
+        const key = normalizePath(path);
+        if (byNorm.has(key))
+            return;
+        if (!isViewableProject(path))
+            return;
+        byNorm.set(key, { path, name: basename(path) || path });
+    };
+    // Claude Code known projects
+    try {
+        const cj = JSON.parse(await readFile(join(homedir(), ".claude.json"), "utf8"));
+        for (const p of Object.keys(cj.projects ?? {}))
+            add(p);
+    }
+    catch {
+        /* no config -> only the active project */
+    }
+    // Include the active project (if any) only when it is itself viewable, so the
+    // picker never offers a non-openspec directory. `current` is "" when no
+    // project is active. Reported as the candidate's exact path string so the
+    // client's selected-option comparison works regardless of slash/case.
+    let current = "";
+    if (active && isViewableProject(active)) {
+        const key = normalizePath(active);
+        if (!byNorm.has(key)) {
+            byNorm.set(key, { path: active, name: basename(active) || active });
+        }
+        current = byNorm.get(key).path;
+    }
+    return { current, candidates: [...byNorm.values()] };
+}
+function normalizePath(p) {
+    return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}

package/dist/server.js

@@ -0,0 +1,92 @@
+// Serve the SPA on loopback and push roadmap + MCP + project state over a websocket.
+import { createServer } from "node:http";
+import { extname } from "node:path";
+import { WebSocketServer, WebSocket } from "ws";
+import { loadAsset } from "./assets.js";
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+};
+export async function startServer(opts) {
+    const { publicDir, host, port, getRoadmap, getMcp, checkMcp, getProjects, selectProject } = opts;
+    let wss;
+    const broadcast = (msg) => {
+        const data = JSON.stringify(msg);
+        for (const ws of wss.clients) {
+            if (ws.readyState === WebSocket.OPEN)
+                ws.send(data);
+        }
+    };
+    const http = createServer(async (req, res) => {
+        try {
+            const url = new URL(req.url ?? "/", `http://${host}`);
+            if (url.pathname === "/api/model")
+                return sendJson(res, getRoadmap());
+            if (url.pathname === "/api/mcp")
+                return sendJson(res, getMcp());
+            if (url.pathname === "/api/projects")
+                return sendJson(res, await getProjects());
+            if (url.pathname === "/api/mcp/check" && req.method === "POST") {
+                const server = await checkMcp(url.searchParams.get("name") ?? "");
+                if (!server)
+                    return sendError(res, 404, "unknown server");
+                broadcast({ type: "mcpServer", server });
+                return sendJson(res, server);
+            }
+            if (url.pathname === "/api/project/select" && req.method === "POST") {
+                const path = url.searchParams.get("path") ?? "";
+                try {
+                    return sendJson(res, await selectProject(path));
+                }
+                catch (err) {
+                    return sendError(res, 400, err instanceof Error ? err.message : "invalid project");
+                }
+            }
+            // static assets (served from public/ on the filesystem)
+            const rel = url.pathname === "/" ? "index.html" : url.pathname.replace(/^\/+/, "");
+            if (rel.includes(".."))
+                return sendError(res, 403, "forbidden");
+            const file = await loadAsset(rel, publicDir);
+            if (!file)
+                return sendError(res, 404, "not found");
+            res.writeHead(200, { "content-type": MIME[extname(rel)] ?? "application/octet-stream" });
+            res.end(file);
+        }
+        catch {
+            sendError(res, 500, "error");
+        }
+    });
+    wss = new WebSocketServer({ server: http });
+    wss.on("connection", async (ws) => {
+        const roadmap = getRoadmap();
+        if (roadmap)
+            ws.send(JSON.stringify({ type: "model", model: roadmap }));
+        ws.send(JSON.stringify({ type: "mcp", mcp: getMcp() }));
+        try {
+            ws.send(JSON.stringify({ type: "project", project: await getProjects() }));
+        }
+        catch {
+            /* project list optional */
+        }
+    });
+    await new Promise((resolve) => http.listen(port, host, resolve));
+    return {
+        port,
+        broadcast,
+        close: () => {
+            wss.close();
+            http.close();
+        },
+    };
+}
+function sendJson(res, body) {
+    res.writeHead(200, { "content-type": MIME[".json"] });
+    res.end(JSON.stringify(body));
+}
+function sendError(res, code, message) {
+    res.writeHead(code, { "content-type": MIME[".json"] });
+    res.end(JSON.stringify({ error: message }));
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Shared model types — the contract between the daemon and the browser view.
+export {};

package/dist/watcher.js

@@ -0,0 +1,26 @@
+// Watch the openspec/ directory and fire a debounced callback on any change.
+import { watch } from "node:fs";
+import { join } from "node:path";
+export function watchOpenspec(repoRoot, onChange, debounceMs = 200) {
+    const dir = join(repoRoot, "openspec");
+    let timer;
+    const trigger = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(onChange, debounceMs);
+    };
+    let watcher;
+    try {
+        // Recursive watching is supported on Windows and macOS.
+        watcher = watch(dir, { recursive: true }, trigger);
+    }
+    catch {
+        // Fallback: shallow watch (e.g. Linux without recursive support).
+        watcher = watch(dir, trigger);
+    }
+    return () => {
+        if (timer)
+            clearTimeout(timer);
+        watcher.close();
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@lyric_dev/data-loom",
+  "version": "0.2.4",
+  "description": "Local dashboard for spec-driven development: a phased OpenSpec roadmap (WHAT) and an MCP topology (HOW).",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/groscy/data-loom#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/groscy/data-loom.git"
+  },
+  "bugs": {
+    "url": "https://github.com/groscy/data-loom/issues"
+  },
+  "keywords": [
+    "openspec",
+    "mcp",
+    "dashboard",
+    "roadmap",
+    "spec-driven-development",
+    "claude-code"
+  ],
+  "bin": {
+    "data-loom": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "public"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node --watch dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "@types/ws": "^8.5.12",
+    "typescript": "^5.6.2"
+  }
+}