loom-spec 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 René Jesser
+
+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,181 @@
+# loom-spec
+
+> A node-based architecture spec that lives in your repo. AI-readable, AI-writable, git-diffable.
+
+`loom-spec` keeps a structured visual spec of your application's architecture **inside your repo**, designed to be edited by both humans (in a browser-based node editor) and AI coding agents (directly via JSON files).
+
+It's a spec layer, not an execution layer. The nodes don't run — they describe.
+
+## Install
+
+```bash
+# No global install needed — use via npx
+npx loom-spec init
+npx loom-spec view
+```
+
+Or as a dev dependency:
+
+```bash
+npm install --save-dev loom-spec
+```
+
+Then in `package.json`:
+
+```json
+{
+  "scripts": {
+    "loom": "loom-spec view"
+  }
+}
+```
+
+## Commands
+
+### `loom-spec init [--path <dir>] [--force]`
+
+Scaffolds the spec directory and the agent skill in the target project (defaults to current working directory).
+
+Writes:
+
+- `.loom/README.md` — explains the directory to humans
+- `.loom/node-types.json` — five default types (`ui`, `service`, `data`, `event`, `external`)
+- `.loom/diagrams/overview.flow.json` — empty starter diagram
+- `.claude/skills/loom-spec/SKILL.md` — tells Claude Code (and any tool following the Agent Skills standard) when and how to maintain the spec
+
+Refuses to overwrite an existing `.loom/` unless `--force`.
+
+### `loom-spec view [--root <dir>] [--port <n>]`
+
+Starts a local browser editor. Walks up from `--root` (default: cwd) to find the nearest `.loom/`. Opens on port 7777 by default.
+
+### `loom-spec validate [--root <dir>] [--json]`
+
+Checks every diagram for schema validity plus **code-ref drift**: missing files, missing symbols, out-of-range line ranges. Skips nodes marked `planned` or `deprecated` (their code may legitimately not exist). Exit code is non-zero if any issue is found — useful as a CI step or pre-commit hook.
+
+```bash
+loom-spec validate
+# ✗ overview.flow.json — Todo App
+#   5 nodes, 5 edges, 3 code refs checked
+#   ✗ todo-api → src/server/routes/todos.ts#todoRouter: symbol 'todoRouter' not found
+```
+
+### `loom-spec mcp [--root <dir>]`
+
+Starts a **Model Context Protocol** server on stdio. Wire it into Claude Code (or any MCP-capable agent) via the host's `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "loom-spec": {
+      "command": "npx",
+      "args": ["loom-spec", "mcp"]
+    }
+  }
+}
+```
+
+The server exposes semantic tools that validate against the schema before writing, more token-efficient than re-reading and re-writing the JSON on every change:
+
+- `loom_list_diagrams`, `loom_read_diagram`, `loom_read_node_types`
+- `loom_add_node`, `loom_update_node`, `loom_mark_stale`, `loom_delete_node`
+- `loom_add_edge`, `loom_delete_edge`
+- `loom_validate` (same drift check as the CLI)
+
+In the editor you can:
+
+- Drag nodes; edits debounce and write to disk within ~500ms
+- Click a node or edge to inspect and edit fields, code refs, tags, type-specific properties
+- Drag from a node's right handle to another node to create an edge
+- Use the "+ Add" menu in the top bar to add a new node by type
+- Use the diagram switcher (top-left dropdown) to navigate between diagrams or create new ones
+- Use the "Drill into" chevron on any node or group with `drill_down` set to jump to a sub-diagram
+- Toggle light/dark theme; preference is persisted
+
+External edits to the JSON files (e.g. by an AI agent) propagate to the open UI live via Server-Sent Events — no reload needed.
+
+## File format
+
+### `.loom/node-types.json`
+
+Defines the available types for nodes in this project. Each type has a label, color, lucide icon name, optional typed fields (string / number / boolean / enum / markdown / code-ref / array), and optional named ports for typed connections.
+
+```json
+{
+  "types": {
+    "service": {
+      "label": "Service",
+      "color": "#34d399",
+      "icon": "server",
+      "fields": [
+        { "name": "language", "type": "string" },
+        { "name": "runtime", "type": "string" }
+      ]
+    }
+  }
+}
+```
+
+### `.loom/diagrams/*.flow.json`
+
+Each diagram is `{ nodes, edges, groups }`. Nodes:
+
+```json
+{
+  "id": "todo-api",
+  "type": "service",
+  "label": "Todo API",
+  "description": "REST endpoints for todos.",
+  "position": { "x": 400, "y": 160 },
+  "status": "implemented",
+  "code_refs": [
+    { "path": "src/server/routes/todos.ts", "symbol": "todoRouter" }
+  ],
+  "properties": { "language": "typescript", "runtime": "node" },
+  "tags": ["public"]
+}
+```
+
+Edges:
+
+```json
+{
+  "id": "e1",
+  "from": "todo-list-view",
+  "to": "todo-api",
+  "kind": "request",
+  "label": "fetch / mutate"
+}
+```
+
+Status enum: `planned`, `implemented`, `stale`, `deprecated`.
+Edge kinds: `request`, `event`, `data-read`, `data-write`, `signal`, `dependency`, `control`.
+
+Full JSON Schemas ship with the package — see `schema/diagram.schema.json` and `schema/node-types.schema.json`.
+
+## How AI agents use it
+
+`loom-spec init` writes a `SKILL.md` to `.claude/skills/loom-spec/` following the [Agent Skills open standard](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview). Claude Code (and other tools that adopt the convention) auto-discovers it.
+
+The skill tells the agent to:
+
+1. Read the relevant diagram before implementing.
+2. Add new components as `status: planned`, flip to `implemented` after the code lands.
+3. Always populate `code_refs` — prefer `symbol` over `lines` because symbols survive refactors.
+4. On code deletion, set `status: stale` rather than removing the node — humans review.
+5. Don't invent node types — extend `node-types.json` first.
+
+You can extend the skill with project-specific rules; it's committed in your repo.
+
+## Tech
+
+- TypeScript end-to-end
+- [Hono](https://hono.dev/) server (Node), serves the SPA and the REST/SSE API on a single port
+- [React Flow / xyflow](https://reactflow.dev/) for the canvas
+- [Vite](https://vitejs.dev/) for the SPA build
+- [Ajv](https://ajv.js.org/) for runtime schema validation
+- [Chokidar](https://github.com/paulmillr/chokidar) for filesystem watching
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { runInit } from "./init.js";
+import { runView } from "./view.js";
+import { runValidate } from "./validate.js";
+import { runMcp } from "./mcp.js";
+const HELP = `loom-spec — node-based architecture spec for your repo
+
+Usage:
+  loom-spec init [--path <dir>] [--force]
+      Scaffold .loom/ and .claude/skills/loom-spec/ in the target directory.
+      Defaults to current working directory.
+
+  loom-spec view [--root <dir>] [--port <n>] [--dev]
+      Start the local browser editor. Walks up from --root (default: cwd)
+      to find the nearest .loom/ directory.
+
+  loom-spec validate [--root <dir>] [--json]
+      Check every diagram for schema validity and code-ref drift
+      (missing files, missing symbols, out-of-range line refs).
+      Exits non-zero if any issue is found. Use as a CI step or
+      pre-commit hook.
+
+  loom-spec mcp [--root <dir>]
+      Start a Model Context Protocol server on stdio. Exposes
+      loom_list_diagrams, loom_read_diagram, loom_add_node,
+      loom_update_node, loom_mark_stale, loom_delete_node,
+      loom_add_edge, loom_delete_edge, loom_validate as MCP tools.
+      Wire it into Claude Code's mcp.json (or any MCP-capable client).
+
+  loom-spec --help
+      Print this help.
+`;
+function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a)
+            continue;
+        if (a.startsWith("--")) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+    }
+    return flags;
+}
+async function main() {
+    const [, , subcommand, ...rest] = process.argv;
+    const flags = parseFlags(rest);
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        console.log(HELP);
+        return;
+    }
+    if (subcommand === "init") {
+        await runInit({
+            path: flags.path ?? process.cwd(),
+            force: Boolean(flags.force),
+        });
+        return;
+    }
+    if (subcommand === "view") {
+        await runView({
+            root: flags.root ?? process.cwd(),
+            port: flags.port ? Number(flags.port) : 7777,
+            dev: Boolean(flags.dev),
+        });
+        return;
+    }
+    if (subcommand === "validate") {
+        await runValidate({
+            root: flags.root ?? process.cwd(),
+            json: Boolean(flags.json),
+        });
+        return;
+    }
+    if (subcommand === "mcp") {
+        await runMcp({
+            root: flags.root ?? process.cwd(),
+        });
+        return;
+    }
+    console.error(`unknown subcommand: ${subcommand}\n`);
+    console.log(HELP);
+    process.exit(1);
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/init.d.ts

@@ -0,0 +1,5 @@
+export interface InitArgs {
+    path: string;
+    force: boolean;
+}
+export declare function runInit(args: InitArgs): Promise<void>;

package/dist/cli/init.js

@@ -0,0 +1,69 @@
+import { mkdir, readFile, writeFile, readdir, stat } from "node:fs/promises";
+import { resolve, dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+const here = dirname(fileURLToPath(import.meta.url));
+// Templates ship alongside dist/ in the package: dist/cli/init.js → ../../templates/
+const templatesRoot = resolve(here, "../../templates");
+async function copyDir(srcDir, destDir, force) {
+    const written = [];
+    await mkdir(destDir, { recursive: true });
+    const entries = await readdir(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const src = join(srcDir, entry.name);
+        const dest = join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            written.push(...(await copyDir(src, dest, force)));
+        }
+        else {
+            let exists = false;
+            try {
+                await stat(dest);
+                exists = true;
+            }
+            catch {
+                // doesn't exist
+            }
+            if (exists && !force) {
+                console.log(`  skip (exists): ${dest}`);
+                continue;
+            }
+            const contents = await readFile(src);
+            await writeFile(dest, contents);
+            written.push(dest);
+        }
+    }
+    return written;
+}
+export async function runInit(args) {
+    const target = resolve(args.path);
+    console.log(`Initializing loom-spec in ${target}`);
+    // Pre-flight: warn if .loom already exists
+    let existing = false;
+    try {
+        await stat(resolve(target, ".loom"));
+        existing = true;
+    }
+    catch {
+        // fresh install
+    }
+    if (existing && !args.force) {
+        console.error("error: .loom/ already exists. Use --force to overwrite specific files (existing files are preserved unless overwritten).");
+        process.exit(1);
+    }
+    const written = await copyDir(templatesRoot, target, args.force);
+    console.log();
+    if (written.length === 0) {
+        console.log("Nothing to write. Use --force to overwrite existing files.");
+        return;
+    }
+    console.log(`Created ${written.length} file(s):`);
+    for (const f of written) {
+        console.log(`  ${relative(target, f)}`);
+    }
+    console.log();
+    console.log("Next steps:");
+    console.log("  1. Run `npx loom-spec view` to open the editor.");
+    console.log("  2. Edit `.loom/node-types.json` to add project-specific node types.");
+    console.log("  3. Start populating `.loom/diagrams/overview.flow.json`.");
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"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"}

package/dist/cli/mcp.d.ts

@@ -0,0 +1,4 @@
+export interface McpArgs {
+    root: string;
+}
+export declare function runMcp(args: McpArgs): Promise<void>;

package/dist/cli/mcp.js

@@ -0,0 +1,17 @@
+import { findLoomRoot } from "../server/findLoomRoot.js";
+import { startMcpServer } from "../mcp/server.js";
+export async function runMcp(args) {
+    let loomRoot;
+    try {
+        loomRoot = await findLoomRoot(args.root);
+    }
+    catch (e) {
+        // MCP servers communicate over stdio — print errors to stderr only.
+        console.error(`loom-spec mcp: ${e.message}`);
+        process.exit(1);
+    }
+    // Hint goes to stderr (stdout is the MCP transport)
+    console.error(`loom-spec mcp: serving ${loomRoot.loomPath}`);
+    await startMcpServer(loomRoot);
+}
+//# sourceMappingURL=mcp.js.map

package/dist/cli/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/cli/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAMlD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAa;IACxC,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,oEAAoE;QACpE,OAAO,CAAC,KAAK,CAAC,kBAAmB,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,oDAAoD;IACpD,OAAO,CAAC,KAAK,CAAC,0BAA0B,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7D,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC"}

package/dist/cli/validate.d.ts

@@ -0,0 +1,5 @@
+export interface ValidateArgs {
+    root: string;
+    json: boolean;
+}
+export declare function runValidate(args: ValidateArgs): Promise<void>;

package/dist/cli/validate.js

@@ -0,0 +1,77 @@
+import { findLoomRoot } from "../server/findLoomRoot.js";
+import { runDriftCheck } from "../server/drift.js";
+const ICON_OK = "✓";
+const ICON_BAD = "✗";
+const ICON_WARN = "⚠";
+const ICON_INFO = "·";
+function formatIssue(detail, issue) {
+    switch (issue) {
+        case "missing-file":
+            return `file not found`;
+        case "missing-symbol":
+            return detail ?? "symbol not found";
+        case "lines-out-of-range":
+            return `lines ${detail}`;
+        case "invalid-lines":
+            return `invalid line range ${detail}`;
+        default:
+            return issue;
+    }
+}
+function printDiagram(d) {
+    const status = d.schemaErrors.length > 0
+        ? ICON_BAD
+        : d.drift.length > 0
+            ? ICON_WARN
+            : ICON_OK;
+    console.log(`${status} ${d.diagramId}.flow.json — ${d.title}`);
+    console.log(`  ${d.nodeCount} nodes, ${d.edgeCount} edges, ${d.refsChecked} code refs checked${d.staleNodes > 0 ? `, ${d.staleNodes} stale` : ""}`);
+    for (const err of d.schemaErrors) {
+        console.log(`  ${ICON_BAD} schema: ${err}`);
+    }
+    for (const f of d.drift) {
+        console.log(`  ${ICON_BAD} ${f.nodeId} → ${f.ref.path}${f.ref.symbol ? `#${f.ref.symbol}` : ""}: ${formatIssue(f.detail, f.issue)}`);
+    }
+    if (d.schemaErrors.length === 0 && d.drift.length === 0) {
+        console.log(`  ${ICON_INFO} no issues`);
+    }
+}
+export async function runValidate(args) {
+    let loomRoot;
+    try {
+        loomRoot = await findLoomRoot(args.root);
+    }
+    catch (e) {
+        console.error(`error: ${e.message}`);
+        process.exit(1);
+    }
+    const report = await runDriftCheck(loomRoot.rootPath, loomRoot.loomPath);
+    if (args.json) {
+        console.log(JSON.stringify(report, null, 2));
+        process.exit(report.totalDrift + report.totalSchemaErrors > 0 ? 1 : 0);
+        return;
+    }
+    console.log(`loom-spec validate`);
+    console.log(`  root: ${loomRoot.rootPath}`);
+    console.log();
+    for (const d of report.perDiagram) {
+        printDiagram(d);
+        console.log();
+    }
+    const summary = [];
+    if (report.totalSchemaErrors > 0) {
+        summary.push(`${report.totalSchemaErrors} schema error(s)`);
+    }
+    if (report.totalDrift > 0) {
+        summary.push(`${report.totalDrift} drift finding(s)`);
+    }
+    if (summary.length === 0) {
+        console.log(`${ICON_OK} All ${report.perDiagram.length} diagram(s) clean.`);
+        process.exit(0);
+    }
+    else {
+        console.log(`${ICON_BAD} ${summary.join(", ")} across ${report.perDiagram.length} diagram(s).`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/cli/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/cli/validate.ts"],"names":[],"mappings":"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"}

package/dist/cli/view.d.ts

@@ -0,0 +1,6 @@
+export interface ViewArgs {
+    root: string;
+    port: number;
+    dev: boolean;
+}
+export declare function runView(args: ViewArgs): Promise<void>;

package/dist/cli/view.js

@@ -0,0 +1,37 @@
+import { serve } from "@hono/node-server";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findLoomRoot } from "../server/findLoomRoot.js";
+import { createApp } from "../server/app.js";
+import { LoomWatcher } from "../server/watch.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export async function runView(args) {
+    let loomRoot;
+    try {
+        loomRoot = await findLoomRoot(args.root);
+    }
+    catch (e) {
+        console.error(`error: ${e.message}`);
+        process.exit(1);
+    }
+    const watcher = new LoomWatcher(loomRoot.loomPath);
+    const app = createApp({
+        loomRoot,
+        watcher,
+        // In dev, Vite serves the SPA. Otherwise we serve the built bundle.
+        serveSpaFrom: args.dev ? undefined : resolve(here, "../view"),
+    });
+    const server = serve({ fetch: app.fetch, port: args.port }, (info) => {
+        console.log(`loom-spec: http://localhost:${info.port}`);
+        console.log(`  root:  ${loomRoot.rootPath}`);
+        console.log(`  .loom: ${loomRoot.loomPath}`);
+    });
+    const shutdown = async () => {
+        await watcher.close();
+        server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+//# sourceMappingURL=view.js.map

package/dist/cli/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../src/cli/view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAQjD,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAErD,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAc;IAC1C,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,UAAW,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEnD,MAAM,GAAG,GAAG,SAAS,CAAC;QACpB,QAAQ;QACR,OAAO;QACP,oEAAoE;QACpE,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC;KAC9D,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE;QACnE,OAAO,CAAC,GAAG,CAAC,+BAA+B,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACxD,OAAO,CAAC,GAAG,CAAC,YAAY,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC7C,OAAO,CAAC,GAAG,CAAC,YAAY,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACtB,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.0.1";

package/dist/index.js

@@ -0,0 +1,2 @@
+export const VERSION = "0.0.1";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LoomRoot } from "../server/findLoomRoot.js";
+export declare function createMcpServer(loomRoot: LoomRoot): McpServer;
+export declare function startMcpServer(loomRoot: LoomRoot): Promise<void>;