@lyric_dev/data-loom 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cyril Grossenbacher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# DataLoom
+
+A fully-local dashboard for spec-driven development. Two views of the same workflow:
+
+- **WHAT do I develop?** — an interactive, phased [OpenSpec](https://github.com/Fission-AI/OpenSpec) roadmap. Changes are laid out by derived dependency phase and coloured by status, with archived work in a done-band and dependency cycles / dangling deps surfaced as conflicts.
+- **HOW / with what?** — a topology of your local MCP setup: a hub-and-spoke graph centred on Claude Code, with passive, never-launch liveness for each server.
+
+It runs as a small local daemon (a Node HTTP + WebSocket server) and a browser view on `localhost`. The daemon is the single source of truth; the page is a thin, live-updating view.
+
+## Prerequisite
+
+DataLoom reads your workspace through the **OpenSpec CLI**, which is **not bundled**. Install it separately:
+
+```
+npm install -g openspec
+```
+
+(data-loom invokes your installed `openspec`; if it's missing, it exits with this guidance instead of showing a blank dashboard.)
+
+## Get it (recommended): install from npm
+
+Requires [Node.js](https://nodejs.org) ≥ 20.
+
+Run it directly with `npx` (no install), pointing at a project (any directory containing an `openspec/` workspace):
+
+```
+npx @lyric_dev/data-loom "C:\path\to\your\project"
+```
+
+Or install it globally and run the `data-loom` command:
+
+```
+npm install -g @lyric_dev/data-loom
+data-loom "C:\path\to\your\project"
+```
+
+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 from source (development)
+
+Requires Node.js ≥ 20.
+
+```
+npm install
+npm start            # serves the current directory's project
+# or: npm start -- "C:\path\to\project"
+```
+
+(The npm package is `@lyric_dev/data-loom` — unscoped `data-loom` is blocked by npm as too similar to an existing package; the product is branded **DataLoom** and installs a `data-loom` command.)
+
+## Using the dashboard
+
+- **Project selector** (top-right): switch which project is displayed. The list is your Claude Code known projects that contain an `openspec/` workspace, plus the active one. Switching re-scopes the roadmap, the file-watching, and the MCP project-scope live.
+- **Roadmap tab**: changes by phase × status. Click a node to inspect its phase, status, and the capabilities it adds/modifies. A conflicts banner appears if the dependency graph has a cycle or a dangling dependency.
+- **MCP Topology tab**: your servers around the Claude Code hub. Click **check** on a server to passively probe it — DataLoom never starts a server or its backing app; it only reports what's reachable so you know what to start yourself.
+
+## Plan dependencies with your Claude (MCP server)
+
+DataLoom can also run as an **MCP server**, so your own Claude session determines and applies the order of interdependent proposals — DataLoom holds no API key and the reasoning runs under your authenticated Claude.
+
+1. Register it in Claude Code (stdio server):
+
+   ```
+   claude mcp add data-loom -- npx @lyric_dev/data-loom mcp "C:\path\to\your\project"
+   ```
+
+   (From source: `node dist/index.js mcp "C:\path\to\project"`.)
+
+2. In that 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 three tools:
+   - `list_open_proposals` — the open changes with their proposal text, current phase/readiness, and dependency-review state (read-only; proposal text only, no secrets).
+   - `set_dependency(from, to)` — writes a `## Depends On` entry into a proposal.
+   - `mark_independent(change)` — records that a proposal genuinely depends on nothing, by writing an empty `## Depends On` block.
+   - `install_weave_skill` — installs the `/loom:weave` shortcut command (one-time setup, see below).
+
+   Each write is an explicit, reviewable `## Depends On` edit; the roadmap then recomputes deterministically. Proposals that still need a dependency decision are flagged in the roadmap with a **"needs review"** badge, and DataLoom appears as a server in its own MCP Topology tab once registered.
+
+3. **One command for it all: `/loom:weave`.** Ask Claude to *"install the weave skill"* (it calls `install_weave_skill`). That writes a `/loom:weave` slash command into your global Claude config (`~/.claude/commands/loom/weave.md`); reload Claude Code, and from then on `/loom:weave` runs the whole review — list, propose, confirm, apply — in any project where DataLoom is registered.
+
+## Design principles
+
+- **Derived, not stored** — phase/order is a pure function of the OpenSpec files, recomputed on every change. Nothing about ordering is persisted.
+- **Mechanical dependencies** — an edge is "change B modifies a capability that change A introduces"; no NLP, no guessing.
+- **Mirror, never launcher** — MCP liveness is observed passively (connect to listening URLs; scan the process table for stdio servers). The dashboard never spawns anything.
+- **openspec stays external** — data-loom ships the app, but not openspec; it invokes your installed `openspec` CLI.
+
+## Built with itself
+
+DataLoom was specified and built with OpenSpec; its own `openspec/` workspace is in this repo, and early in development the dashboard rendered its own build plan.

package/dist/assets.js

@@ -0,0 +1,24 @@
+// Static asset access: read the SPA's files from the public/ directory on disk.
+// public/ is shipped alongside the compiled code in the published npm package.
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+/** Location of the public/ directory, resolved relative to the compiled module. */
+export function resolvePublicDir() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return join(here, "..", "public");
+    }
+    catch {
+        return join(process.cwd(), "public");
+    }
+}
+/** Load a static asset by its relative key (e.g. "index.html") from publicDir. */
+export async function loadAsset(rel, publicDir) {
+    try {
+        return await readFile(join(publicDir, rel));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/derive.js

@@ -0,0 +1,209 @@
+// The heart of the roadmap: turn OpenSpec data into a phase x status model.
+// Derivation is a pure function of the current workspace — nothing is stored.
+export async function deriveModel(client) {
+    const [list, archived, baseline] = await Promise.all([
+        client.listChanges(),
+        client.listArchived(),
+        client.listBaselineCapabilities(),
+    ]);
+    const baselineSet = new Set(baseline);
+    const names = list.map((c) => c.name);
+    // Per-change capability ownership declarations (New / Modified).
+    const caps = new Map();
+    await Promise.all(names.map(async (n) => caps.set(n, await client.readProposalCaps(n))));
+    // Explicit `## Depends On` declarations per change.
+    const explicitDeps = new Map();
+    await Promise.all(names.map(async (n) => explicitDeps.set(n, await client.readProposalDependsOn(n))));
+    // Dependency-review state: whether a `## Depends On` section exists at all
+    // (even empty). Pure metadata — never feeds the edges or phases below.
+    const reviewed = new Map();
+    await Promise.all(names.map(async (n) => reviewed.set(n, await client.hasDependsOnSection(n))));
+    const nameSet = new Set(names);
+    const archivedBare = new Set(archived.map((a) => a.replace(/^\d{4}-\d{2}-\d{2}-/, "")));
+    // owner[capability] = the change that introduces it (lists it under New).
+    const owner = new Map();
+    for (const n of names) {
+        for (const cap of caps.get(n).newCaps) {
+            if (!owner.has(cap))
+                owner.set(cap, n);
+        }
+    }
+    // Build nodes + dependency edges.
+    const depMap = new Map();
+    const nodes = [];
+    for (const c of list) {
+        const { newCaps, modifiedCaps } = caps.get(c.name);
+        const dependsOn = new Set();
+        const unsatisfied = [];
+        for (const cap of modifiedCaps) {
+            if (baselineSet.has(cap))
+                continue; // satisfied by the settled baseline
+            const o = owner.get(cap);
+            if (o && o !== c.name)
+                dependsOn.add(o);
+            else if (!o)
+                unsatisfied.push(cap); // dangling / out-of-order (surfaced in Phase 2)
+        }
+        // Explicit cross-proposal dependencies, merged with the capability edges.
+        for (const dep of explicitDeps.get(c.name) ?? []) {
+            if (dep === c.name)
+                continue;
+            if (nameSet.has(dep))
+                dependsOn.add(dep); // active change -> edge
+            else if (archivedBare.has(dep))
+                continue; // archived/done -> satisfied
+            else
+                unsatisfied.push(dep); // unknown name -> conflict
+        }
+        depMap.set(c.name, [...dependsOn]);
+        nodes.push({
+            name: c.name,
+            phase: 0,
+            status: deriveStatus(c, false),
+            readiness: "done",
+            newCapabilities: newCaps,
+            modifiedCapabilities: modifiedCaps,
+            dependsOn: [...dependsOn],
+            unsatisfiedDependencies: unsatisfied,
+            dependencyReview: reviewed.get(c.name) ? "declared" : "pending",
+            archived: false,
+            completedTasks: c.completedTasks,
+            totalTasks: c.totalTasks,
+        });
+    }
+    // Archived changes -> done band (not part of the active DAG).
+    for (const a of archived) {
+        if (names.includes(a))
+            continue;
+        nodes.push({
+            name: a,
+            phase: 0,
+            status: "done",
+            readiness: "done",
+            newCapabilities: [],
+            modifiedCapabilities: [],
+            dependsOn: [],
+            unsatisfiedDependencies: [],
+            dependencyReview: "declared",
+            archived: true,
+            completedTasks: 0,
+            totalTasks: 0,
+        });
+    }
+    // Phase = longest-path depth in the DAG, with a cycle guard so a malformed
+    // graph still yields a layout instead of crashing.
+    const memo = new Map();
+    const inStack = new Set();
+    const depth = (n) => {
+        const cached = memo.get(n);
+        if (cached !== undefined)
+            return cached;
+        if (inStack.has(n))
+            return 1; // back-edge: break the cycle defensively
+        inStack.add(n);
+        let d = 1;
+        for (const dep of depMap.get(n) ?? []) {
+            if (depMap.has(dep))
+                d = Math.max(d, depth(dep) + 1);
+        }
+        inStack.delete(n);
+        memo.set(n, d);
+        return d;
+    };
+    for (const node of nodes) {
+        if (!node.archived)
+            node.phase = depth(node.name);
+    }
+    // Group into ordered phases.
+    const byPhase = new Map();
+    for (const node of nodes) {
+        if (node.archived)
+            continue;
+        const list = byPhase.get(node.phase) ?? [];
+        list.push(node.name);
+        byPhase.set(node.phase, list);
+    }
+    const phases = [...byPhase.entries()]
+        .sort((a, b) => a[0] - b[0])
+        .map(([phase, changeNames]) => ({ phase, changeNames }));
+    // Readiness: ready when every active dependency is done; blocked otherwise.
+    const statusByName = new Map(nodes.map((n) => [n.name, n.status]));
+    for (const node of nodes) {
+        if (node.archived || node.status === "done") {
+            node.readiness = "done";
+        }
+        else {
+            node.readiness = node.dependsOn.some((d) => statusByName.get(d) !== "done") ? "blocked" : "ready";
+        }
+    }
+    // Surface conflicts (detection never aborts the rest of the derivation).
+    const conflicts = [];
+    try {
+        for (const cyc of findCycles(depMap)) {
+            conflicts.push({
+                type: "cycle",
+                changes: cyc,
+                description: `Dependency cycle: ${[...cyc, cyc[0]].join(" → ")}`,
+            });
+        }
+        for (const node of nodes) {
+            for (const cap of node.unsatisfiedDependencies) {
+                conflicts.push({
+                    type: "dangling",
+                    changes: [node.name],
+                    capability: cap,
+                    description: `${node.name} modifies "${cap}", which no change adds and no baseline provides`,
+                });
+            }
+        }
+    }
+    catch {
+        /* leave conflicts empty rather than failing the roadmap */
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        changes: nodes,
+        phases,
+        baselineCapabilities: baseline,
+        conflicts,
+    };
+}
+/** Find dependency cycles via DFS back-edge detection over the dependency map. */
+function findCycles(depMap) {
+    const color = new Map(); // 0 = unvisited, 1 = on stack, 2 = done
+    const stack = [];
+    const cycles = [];
+    const dfs = (n) => {
+        color.set(n, 1);
+        stack.push(n);
+        for (const dep of depMap.get(n) ?? []) {
+            if (!depMap.has(dep))
+                continue;
+            const c = color.get(dep) ?? 0;
+            if (c === 1) {
+                const idx = stack.indexOf(dep);
+                if (idx >= 0)
+                    cycles.push(stack.slice(idx));
+            }
+            else if (c === 0) {
+                dfs(dep);
+            }
+        }
+        stack.pop();
+        color.set(n, 2);
+    };
+    for (const n of depMap.keys()) {
+        if ((color.get(n) ?? 0) === 0)
+            dfs(n);
+    }
+    return cycles;
+}
+function deriveStatus(c, archived) {
+    if (archived)
+        return "done";
+    if (c.totalTasks > 0 && c.completedTasks >= c.totalTasks)
+        return "done";
+    if (c.completedTasks > 0)
+        return "in-progress";
+    return "draft";
+}

package/dist/index.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// data_loom daemon entry point: verify the openspec CLI, derive the roadmap,
+// discover the MCP setup, serve the SPA, and keep it live — for a selectable
+// project that can be switched at runtime.
+import { resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { OpenSpecClient } from "./openspecClient.js";
+import { deriveModel } from "./derive.js";
+import { watchOpenspec } from "./watcher.js";
+import { startServer } from "./server.js";
+import { discover } from "./mcp/discovery.js";
+import { checkServer } from "./mcp/availability.js";
+import { discoverProjects, isViewableProject } from "./projects.js";
+import { resolvePublicDir } from "./assets.js";
+import { runMcpServer } from "./mcpServer.js";
+const host = "127.0.0.1";
+const port = Number(process.env.PORT ?? 4317);
+// 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;
+let server;
+async function main() {
+    // openspec is an external prerequisite — fail loudly with install guidance.
+    try {
+        const version = await new OpenSpecClient(initialProject).checkAvailable();
+        console.log(`[data-loom] openspec CLI ${version}`);
+    }
+    catch {
+        console.error("[data-loom] ERROR: the `openspec` CLI was not found.\n" +
+            "data_loom does not bundle it — install it separately, e.g. `npm i -g openspec`, then retry.");
+        process.exit(1);
+    }
+    // Resolve a viewable project: the launch dir, else the first discovered one,
+    // else none. Never exit just because the launch dir isn't a project.
+    let active = isViewableProject(initialProject) ? initialProject : null;
+    if (!active) {
+        const candidates = (await discoverProjects(initialProject)).candidates;
+        active = candidates[0]?.path ?? null;
+    }
+    if (active) {
+        session = await buildSession(active);
+    }
+    else {
+        console.log("[data-loom] no openspec project found at launch — open the dashboard and pick one");
+    }
+    server = await startServer({
+        publicDir: resolvePublicDir(),
+        host,
+        port,
+        getRoadmap: () => session?.model ?? null,
+        getMcp,
+        checkMcp,
+        getProjects,
+        selectProject,
+    });
+    console.log(`[data-loom] dashboard ready at http://${host}:${server.port}`);
+    if (session)
+        console.log(`[data-loom] project: ${session.project}`);
+    openBrowser(`http://${host}:${server.port}`);
+    const shutdown = () => {
+        session?.stopWatch();
+        server?.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+async function buildSession(project) {
+    const client = new OpenSpecClient(project);
+    const model = await deriveModel(client);
+    let mcpServers = [];
+    let probes = new Map();
+    try {
+        const disc = await discover(project);
+        mcpServers = disc.servers;
+        probes = disc.probes;
+    }
+    catch (err) {
+        console.error("[data-loom] MCP discovery failed:", err);
+    }
+    const stopWatch = watchOpenspec(project, () => recompute());
+    console.log(`[data-loom] loaded ${model.changes.filter((c) => !c.archived).length} change(s), ${mcpServers.length} MCP server(s)`);
+    return { project, client, model, mcpServers, probes, stopWatch };
+}
+async function recompute() {
+    if (!session)
+        return;
+    try {
+        session.model = await deriveModel(session.client);
+        server?.broadcast({ type: "model", model: session.model });
+        console.log(`[data-loom] roadmap recomputed — ${session.model.phases.length} phase(s)`);
+    }
+    catch (err) {
+        console.error("[data-loom] derivation failed:", err);
+    }
+}
+async function selectProject(path) {
+    const target = resolve(path);
+    if (!isViewableProject(target)) {
+        throw new Error(`No openspec/ workspace at ${target}`);
+    }
+    session?.stopWatch();
+    session = await buildSession(target);
+    const projects = await getProjects();
+    server?.broadcast({ type: "project", project: projects });
+    server?.broadcast({ type: "model", model: session.model });
+    server?.broadcast({ type: "mcp", mcp: getMcp() });
+    console.log(`[data-loom] switched project -> ${target}`);
+    return projects;
+}
+function getMcp() {
+    return { hub: "Claude Code", servers: session?.mcpServers ?? [] };
+}
+async function checkMcp(name) {
+    const target = session?.probes.get(name);
+    const sv = session?.mcpServers.find((s) => s.name === name);
+    if (!target || !sv)
+        return null;
+    sv.liveness = await checkServer(target);
+    sv.lastChecked = new Date().toISOString();
+    return sv;
+}
+function getProjects() {
+    return discoverProjects(session?.project ?? "");
+}
+function openBrowser(url) {
+    if (process.env.DATA_LOOM_NO_OPEN)
+        return;
+    try {
+        if (process.platform === "win32") {
+            spawn("cmd", ["/c", "start", "", url], { stdio: "ignore", detached: true }).unref();
+        }
+        else if (process.platform === "darwin") {
+            spawn("open", [url], { stdio: "ignore", detached: true }).unref();
+        }
+        else {
+            spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+        }
+    }
+    catch {
+        /* non-fatal — the URL is already logged */
+    }
+}
+if (process.argv[2] === "mcp") {
+    // MCP stdio server mode: `data-loom mcp [project]`
+    const project = resolve(process.argv[3] ?? process.env.DATA_LOOM_ROOT ?? process.cwd());
+    runMcpServer(project).catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}
+else {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/dist/mcp/availability.js

@@ -0,0 +1,59 @@
+// Passive availability checks. NEVER spawns an MCP server or backing app —
+// it only observes: connect to URL endpoints that already listen, and read the
+// OS process table for stdio servers.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileP = promisify(execFile);
+export async function checkServer(target) {
+    if (target.transport === "stdio") {
+        return (await isProcessRunning(target)) ? "already-running" : "on-demand";
+    }
+    if (target.url) {
+        return checkUrl(target.url);
+    }
+    return "unknown";
+}
+/** Connect to an already-listening endpoint. Connecting is not launching. */
+async function checkUrl(url) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 2500);
+    try {
+        const res = await fetch(url, { method: "GET", signal: ctrl.signal, redirect: "manual" });
+        if (res.status === 401 || res.status === 403)
+            return "needs-auth";
+        return "available";
+    }
+    catch {
+        return "unreachable";
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Best-effort: is a process whose command line matches this stdio server running? */
+async function isProcessRunning(target) {
+    const needle = distinctive(target);
+    if (!needle)
+        return false;
+    try {
+        const lines = await processCommandLines();
+        const n = needle.toLowerCase();
+        return lines.some((l) => l.toLowerCase().includes(n));
+    }
+    catch {
+        return false; // can't read the table -> resting state is on-demand
+    }
+}
+/** The most identifying token: the longest non-flag argument, else the command. */
+function distinctive(t) {
+    const args = (t.args ?? []).filter((a) => !a.startsWith("-")).sort((a, b) => b.length - a.length);
+    return args[0] ?? t.command;
+}
+async function processCommandLines() {
+    if (process.platform === "win32") {
+        const { stdout } = await execFileP("powershell", ["-NoProfile", "-Command", "Get-CimInstance Win32_Process | Select-Object -ExpandProperty CommandLine"], { maxBuffer: 32 * 1024 * 1024, windowsHide: true });
+        return stdout.split(/\r?\n/);
+    }
+    const { stdout } = await execFileP("ps", ["-axww", "-o", "args="], { maxBuffer: 32 * 1024 * 1024 });
+    return stdout.split(/\r?\n/);
+}

package/dist/mcp/discovery.js

@@ -0,0 +1,122 @@
+// Merge MCP server definitions from Claude Code config sources into a single,
+// de-duplicated, secret-free list. The hub is always Claude Code.
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, basename } from "node:path";
+export async function discover(repoRoot) {
+    const servers = new Map();
+    const probes = new Map();
+    const add = (name, cfg, scope, source) => {
+        const existing = servers.get(name);
+        if (existing) {
+            // Collapse duplicates; a project-scoped entry is the most specific.
+            if (existing.scope === "project")
+                return;
+            if (scope === "global")
+                return; // both global — keep the first
+            // existing global + new project -> overwrite below
+        }
+        const { server, probe } = sanitize(name, cfg, scope, source);
+        servers.set(name, server);
+        probes.set(name, probe);
+    };
+    const home = homedir();
+    const claudeJson = await readJsonSafe(join(home, ".claude.json"));
+    const userMcp = await readJsonSafe(join(home, ".claude", ".mcp.json"));
+    // Global: ~/.claude.json mcpServers
+    for (const [n, c] of entriesOf(claudeJson?.mcpServers)) {
+        if (isServerCfg(c))
+            add(n, c, "global", "~/.claude.json");
+    }
+    // Global/user: ~/.claude/.mcp.json (bare map or { mcpServers })
+    const userServers = userMcp?.mcpServers ?? userMcp;
+    for (const [n, c] of entriesOf(userServers)) {
+        if (isServerCfg(c))
+            add(n, c, "global", "~/.claude/.mcp.json");
+    }
+    // Project: ~/.claude.json projects[<repoRoot>].mcpServers (match path variants)
+    const target = normalizePath(repoRoot);
+    for (const [p, pv] of entriesOf(claudeJson?.projects)) {
+        if (normalizePath(p) !== target)
+            continue;
+        const ms = pv?.mcpServers;
+        for (const [n, c] of entriesOf(ms)) {
+            if (isServerCfg(c))
+                add(n, c, "project", `project: ${p}`);
+        }
+    }
+    return { servers: [...servers.values()], probes };
+}
+function sanitize(name, cfg, scope, source) {
+    const transport = transportOf(cfg);
+    const probe = { name, transport, command: cfg.command, args: cfg.args, url: cfg.url };
+    const server = { name, transport, scope, source, liveness: "unknown" };
+    if (transport === "stdio") {
+        server.command = cfg.command ? basename(cfg.command) : undefined;
+        server.detail = redactArgs(cfg.args);
+    }
+    else {
+        server.url = safeUrl(cfg.url);
+        server.detail = server.url;
+    }
+    return { server, probe };
+}
+function transportOf(cfg) {
+    if (cfg.type === "http" || cfg.type === "streamable-http")
+        return "http";
+    if (cfg.type === "sse")
+        return "sse";
+    if (cfg.type === "stdio")
+        return "stdio";
+    if (cfg.command)
+        return "stdio";
+    if (cfg.url)
+        return "http";
+    return "unknown";
+}
+function isServerCfg(c) {
+    return !!c && typeof c === "object" && ("command" in c || "url" in c || "type" in c);
+}
+// --- redaction (secrets must never reach the client) ---
+function redactArgs(args) {
+    if (!args || !args.length)
+        return "";
+    const sensitiveFlag = /(token|secret|key|password|passwd|auth|bearer|cred)/i;
+    const tokenish = /^(ghp_|gho_|sk-|xox|eyJ)|^[A-Fa-f0-9]{24,}$/;
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (sensitiveFlag.test(args[i - 1] ?? "") || tokenish.test(a))
+            out.push("***");
+        else if (/^https?:\/\//i.test(a))
+            out.push(safeUrl(a));
+        else
+            out.push(a);
+    }
+    return out.join(" ").slice(0, 100);
+}
+function safeUrl(url) {
+    if (!url)
+        return "";
+    try {
+        const u = new URL(url);
+        return `${u.protocol}//${u.host}`;
+    }
+    catch {
+        return "";
+    }
+}
+function normalizePath(p) {
+    return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+function entriesOf(v) {
+    return v && typeof v === "object" ? Object.entries(v) : [];
+}
+async function readJsonSafe(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}