npm - loom-spec - Versions diffs - 0.1.0 - Mend

loom-spec 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (57) hide show

package/LICENSE +21 -0
package/README.md +181 -0
package/dist/cli/index.d.ts +2 -0
package/dist/cli/index.js +96 -0
package/dist/cli/index.js.map +1 -0
package/dist/cli/init.d.ts +5 -0
package/dist/cli/init.js +69 -0
package/dist/cli/init.js.map +1 -0
package/dist/cli/mcp.d.ts +4 -0
package/dist/cli/mcp.js +17 -0
package/dist/cli/mcp.js.map +1 -0
package/dist/cli/validate.d.ts +5 -0
package/dist/cli/validate.js +77 -0
package/dist/cli/validate.js.map +1 -0
package/dist/cli/view.d.ts +6 -0
package/dist/cli/view.js +37 -0
package/dist/cli/view.js.map +1 -0
package/dist/index.d.ts +1 -0
package/dist/index.js +2 -0
package/dist/index.js.map +1 -0
package/dist/mcp/server.d.ts +4 -0
package/dist/mcp/server.js +293 -0
package/dist/mcp/server.js.map +1 -0
package/dist/server/app.d.ts +9 -0
package/dist/server/app.js +135 -0
package/dist/server/app.js.map +1 -0
package/dist/server/drift.d.ts +29 -0
package/dist/server/drift.js +128 -0
package/dist/server/drift.js.map +1 -0
package/dist/server/fileOps.d.ts +13 -0
package/dist/server/fileOps.js +56 -0
package/dist/server/fileOps.js.map +1 -0
package/dist/server/findLoomRoot.d.ts +9 -0
package/dist/server/findLoomRoot.js +28 -0
package/dist/server/findLoomRoot.js.map +1 -0
package/dist/server/watch.d.ts +29 -0
package/dist/server/watch.js +83 -0
package/dist/server/watch.js.map +1 -0
package/dist/types/diagram.d.ts +99 -0
package/dist/types/diagram.js +7 -0
package/dist/types/diagram.js.map +1 -0
package/dist/types/node-types.d.ts +55 -0
package/dist/types/node-types.js +7 -0
package/dist/types/node-types.js.map +1 -0
package/dist/validate.d.ts +11 -0
package/dist/validate.js +47 -0
package/dist/validate.js.map +1 -0
package/dist/view/assets/index-Cst6HUW5.css +1 -0
package/dist/view/assets/index-jlp2cU4j.js +205 -0
package/dist/view/index.html +24 -0
package/package.json +83 -0
package/schema/diagram.schema.json +173 -0
package/schema/node-types.schema.json +116 -0
package/templates/.claude/skills/loom-spec/SKILL.md +278 -0
package/templates/.loom/README.md +25 -0
package/templates/.loom/diagrams/overview.flow.json +8 -0
package/templates/.loom/node-types.json +56 -0

package/dist/view/index.html ADDED Viewed

@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="en" data-theme="light">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>loom-spec</title>
+    <script>
+      // Apply persisted theme before paint to avoid flash.
+      try {
+        const t = localStorage.getItem("loom-theme");
+        if (t === "light" || t === "dark") {
+          document.documentElement.setAttribute("data-theme", t);
+        } else if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
+          document.documentElement.setAttribute("data-theme", "dark");
+        }
+      } catch {}
+    </script>
+    <script type="module" crossorigin src="/assets/index-jlp2cU4j.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Cst6HUW5.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/package.json ADDED Viewed

@@ -0,0 +1,83 @@
+{
+  "name": "loom-spec",
+  "version": "0.1.0",
+  "description": "Node-based architecture spec that lives in your repo. AI-readable, AI-writable, git-diffable.",
+  "type": "module",
+  "author": "René Jesser",
+  "license": "MIT",
+  "homepage": "https://github.com/renejes/loom-spec#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/renejes/loom-spec.git",
+    "directory": "packages/loom-spec"
+  },
+  "bugs": {
+    "url": "https://github.com/renejes/loom-spec/issues"
+  },
+  "keywords": [
+    "architecture",
+    "architecture-as-code",
+    "diagram",
+    "node-based",
+    "spec",
+    "specification",
+    "visual-programming",
+    "flow-chart",
+    "ai",
+    "ai-agent",
+    "claude",
+    "agent-skills",
+    "react-flow",
+    "xyflow",
+    "developer-tools"
+  ],
+  "bin": {
+    "loom-spec": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "schema",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./schema": "./schema/diagram.schema.json",
+    "./node-types-schema": "./schema/node-types.schema.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && vite build --config src/view/vite.config.ts",
+    "dev": "concurrently -n server,view -c blue,magenta \"pnpm dev:server\" \"pnpm dev:view\"",
+    "dev:server": "tsx src/cli/index.ts view --dev --root ../../examples/todo-app --port 7778",
+    "dev:view": "vite --config src/view/vite.config.ts",
+    "init:example": "tsx src/cli/index.ts init --path /tmp/loom-init-test --force",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p src/view/tsconfig.json --noEmit",
+    "generate-types": "tsx scripts/generate-types.ts",
+    "validate-examples": "tsx scripts/validate-examples.ts"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.7",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@xyflow/react": "^12.3.5",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "chokidar": "^4.0.1",
+    "hono": "^4.6.13",
+    "lucide-react": "^0.460.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "concurrently": "^9.1.0",
+    "json-schema-to-typescript": "^15.0.3",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.0",
+    "vite": "^5.4.11"
+  }
+}

package/schema/diagram.schema.json ADDED Viewed

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://loom-spec.dev/schema/diagram-v1.json",
+  "title": "Loom Diagram",
+  "description": "A node-based architecture spec file.",
+  "type": "object",
+  "required": ["version", "id", "title", "nodes", "edges"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": "1" },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "description": "Diagram identifier. Should match the filename without extension."
+    },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "nodes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Node" }
+    },
+    "edges": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Edge" }
+    },
+    "groups": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Group" },
+      "default": []
+    }
+  },
+  "$defs": {
+    "Node": {
+      "type": "object",
+      "required": ["id", "type", "label", "position", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+$",
+          "description": "Unique within this diagram."
+        },
+        "type": {
+          "type": "string",
+          "description": "References a key in node-types.json."
+        },
+        "label": { "type": "string", "minLength": 1, "maxLength": 60 },
+        "description": {
+          "type": "string",
+          "description": "Markdown allowed."
+        },
+        "position": {
+          "type": "object",
+          "required": ["x", "y"],
+          "additionalProperties": false,
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" }
+          }
+        },
+        "status": {
+          "type": "string",
+          "enum": ["planned", "implemented", "stale", "deprecated"],
+          "description": "planned = spec exists, code does not. implemented = both present. stale = code refs are broken, needs review. deprecated = kept for history, no longer active."
+        },
+        "code_refs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/CodeRef" },
+          "default": []
+        },
+        "properties": {
+          "type": "object",
+          "description": "Custom fields defined by the node's type in node-types.json.",
+          "default": {}
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": []
+        },
+        "drill_down": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+$",
+          "description": "ID of another diagram file to navigate into when this node is opened."
+        }
+      }
+    },
+    "Edge": {
+      "type": "object",
+      "required": ["id", "from", "to", "kind"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "from": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+(:[a-z0-9_-]+)?$",
+          "description": "Source node id, optionally with :port-name suffix."
+        },
+        "to": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+(:[a-z0-9_-]+)?$",
+          "description": "Target node id, optionally with :port-name suffix."
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["request", "event", "data-read", "data-write", "signal", "dependency", "control"]
+        },
+        "label": { "type": "string", "maxLength": 60 },
+        "description": { "type": "string" },
+        "direction": {
+          "type": "string",
+          "enum": ["forward", "bidirectional"],
+          "default": "forward"
+        }
+      }
+    },
+    "Group": {
+      "type": "object",
+      "required": ["id", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+        "label": { "type": "string", "minLength": 1 },
+        "children": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Node ids contained in this group.",
+          "default": []
+        },
+        "subgroups": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Group ids nested inside this group.",
+          "default": []
+        },
+        "color": {
+          "type": "string",
+          "pattern": "^#[0-9a-fA-F]{6}$"
+        },
+        "collapsed": { "type": "boolean", "default": false },
+        "drill_down": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+$"
+        }
+      }
+    },
+    "CodeRef": {
+      "type": "object",
+      "required": ["path"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Repo-relative file path."
+        },
+        "symbol": {
+          "type": "string",
+          "description": "Function, class, or component name. Preferred over lines because it survives refactors."
+        },
+        "lines": {
+          "type": "string",
+          "pattern": "^[0-9]+(-[0-9]+)?(,[0-9]+(-[0-9]+)?)*$",
+          "description": "Line range(s) like '1-80' or '12,45-50'. Use only when no symbol applies."
+        }
+      }
+    }
+  }
+}

package/schema/node-types.schema.json ADDED Viewed

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://loom-spec.dev/schema/node-types-v1.json",
+  "title": "Loom Node Types",
+  "description": "Defines the node type vocabulary for a project.",
+  "type": "object",
+  "required": ["types"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "types": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/NodeType" },
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" }
+    }
+  },
+  "$defs": {
+    "NodeType": {
+      "type": "object",
+      "required": ["label", "color"],
+      "additionalProperties": false,
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "color": {
+          "type": "string",
+          "pattern": "^#[0-9a-fA-F]{6}$"
+        },
+        "icon": {
+          "type": "string",
+          "description": "Lucide icon name."
+        },
+        "fields": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Field" },
+          "default": []
+        },
+        "ports": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "in": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/Port" },
+              "default": []
+            },
+            "out": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/Port" },
+              "default": []
+            }
+          }
+        }
+      }
+    },
+    "Field": {
+      "type": "object",
+      "required": ["name", "type"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["string", "number", "boolean", "enum", "markdown", "code-ref", "array"]
+        },
+        "required": { "type": "boolean", "default": false },
+        "description": { "type": "string" },
+        "default": {},
+        "values": {
+          "type": "array",
+          "description": "Required when type is 'enum'."
+        },
+        "items": {
+          "type": "string",
+          "enum": ["string", "number"],
+          "description": "Required when type is 'array'."
+        },
+        "min": { "type": "number" },
+        "max": { "type": "number" },
+        "pattern": { "type": "string" },
+        "max_length": { "type": "number", "minimum": 1 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "enum" } }, "required": ["type"] },
+          "then": { "required": ["values"] }
+        },
+        {
+          "if": { "properties": { "type": { "const": "array" } }, "required": ["type"] },
+          "then": { "required": ["items"] }
+        }
+      ]
+    },
+    "Port": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_-]*$"
+        },
+        "signal": {
+          "type": "string",
+          "description": "Free-form signal type tag, e.g. 'audio', 'midi', 'http', 'control'."
+        }
+      }
+    }
+  }
+}

package/templates/.claude/skills/loom-spec/SKILL.md ADDED Viewed

@@ -0,0 +1,278 @@
+---
+name: loom-spec
+description: |
+  Use when modifying application architecture, components, services, data flow,
+  events, or any code with corresponding nodes in .loom/diagrams/. Reads and
+  updates the visual architecture spec, keeps code_refs accurate, and flags
+  stale nodes. Trigger on: new features, refactors, file moves, module
+  deletions, or when the user references "the diagram", "the architecture",
+  or "the spec".
+---
+# loom-spec — Architecture Spec Maintenance
+This project keeps a node-based architecture spec in `.loom/`. Treat it as
+source-of-truth documentation that must stay in sync with code.
+## Quick-start workflow
+For any task that touches structure:
+1. **Read first.** Find the relevant diagram(s) before editing code.
+2. **Plan in the spec.** Add planned nodes/edges for what you're about to build.
+3. **Implement the code.**
+4. **Update the spec.** Flip status to `implemented`, set accurate `code_refs`.
+5. **Validate.** Run `loom_validate` (MCP) or `loom-spec validate` (CLI) to
+   confirm no drift.
+## Rules
+### Before implementing a feature
+- List `.loom/diagrams/` and read the relevant file(s).
+- Check existing node IDs to avoid collisions within a diagram.
+- Confirm available node types in `.loom/node-types.json`. If you need a type
+  that doesn't exist, add it there first (with a sensible color and icon).
+### When adding code
+- New component / service / store → add a node with `status: "planned"` first
+  while scaffolding, then flip to `"implemented"` once it works.
+- Always set `code_refs` to actual files. **Prefer `symbol` over `lines`** —
+  symbols survive refactors; line numbers do not.
+- Use only types defined in `.loom/node-types.json`.
+### When editing code
+- If you touch a file referenced by a node, verify the `symbol` still exists
+  and the `path` is still accurate. Update if not.
+- If you rename or move a file, update every `code_refs` pointing at it.
+### When deleting code
+- Don't delete the node. Set `status: "stale"`. Humans review staleness —
+  silent deletion loses architectural history.
+### When the user describes a new subsystem
+- If it's clearly its own area (auth, billing, ingestion), create a new
+  `<name>.flow.json` instead of cramming it into an existing diagram.
+- Link from the overview with a `drill_down` reference if appropriate.
+## Preferred tools (when the MCP server is wired up)
+If a `loom-spec` MCP server is registered with the host (e.g. via
+`.mcp.json`), prefer its tools over raw JSON edits:
+- `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` (schema + code-ref drift across every diagram)
+They validate against the schema before writing, so invalid edits fail fast
+instead of corrupting the file. They're also more token-efficient than
+re-reading + re-writing JSON on every mutation.
+If the MCP server is not available, edit the JSON files directly using the
+rules above — the format is stable and tools-agnostic by design.
+---
+## Examples
+### 1. User asks for a new feature
+> User: "Add a payments service. The checkout flow calls it to charge the card."
+```
+# Step 1: Inspect the current state
+loom_read_diagram("overview")
+# Step 2: Add the new service as planned
+loom_add_node({
+  diagram: "overview",
+  type: "service",
+  label: "Payments",
+  description: "Stripe wrapper. Handles charges, refunds, and the webhook.",
+  status: "planned",
+  code_refs: [{ path: "src/server/payments.ts" }],
+  properties: { language: "typescript", runtime: "node" }
+})
+# → { ok: true, id: "service-2" }
+# Step 3: Connect it
+loom_add_edge({
+  diagram: "overview",
+  from: "checkout-flow",
+  to: "service-2",
+  kind: "request",
+  label: "charge card"
+})
+# Step 4: Write the code (using your normal Write/Edit tools).
+# Step 5: Update the node to reflect reality
+loom_update_node({
+  diagram: "overview",
+  id: "service-2",
+  patch: {
+    status: "implemented",
+    code_refs: [
+      { path: "src/server/payments.ts", symbol: "createCharge" },
+      { path: "src/server/payments.ts", symbol: "handleWebhook" }
+    ]
+  }
+})
+```
+### 2. User describes a multi-step agent (e.g. LangGraph)
+> User: "agent.py has a LangGraph with three steps: decide_step, call_tool, format_response."
+Two valid shapes, choose by **how much the flow between steps matters**:
+**A) Tightly coupled, internal detail — one node with many refs:**
+```
+loom_add_node({
+  diagram: "overview",
+  type: "service",
+  label: "Agent",
+  description: "LangGraph agent. Steps inside agent.py.",
+  status: "implemented",
+  code_refs: [
+    { path: "agent.py", symbol: "decide_step" },
+    { path: "agent.py", symbol: "call_tool" },
+    { path: "agent.py", symbol: "format_response" }
+  ]
+})
+```
+**B) Step flow itself is the architecture — drill down to a sub-diagram:**
+```
+# Top-level: one node, drill_down to detail
+loom_add_node({
+  diagram: "overview",
+  type: "service",
+  label: "Agent",
+  status: "implemented",
+  code_refs: [{ path: "agent.py" }],
+  drill_down: "agent-internals"
+})
+# Create the sub-diagram via the file system (no dedicated MCP tool):
+# Write .loom/diagrams/agent-internals.flow.json
+{
+  "version": "1",
+  "id": "agent-internals",
+  "title": "Agent — internal steps",
+  "nodes": [
+    { "id": "decide", "type": "service", "label": "decide_step",
+      "position": { "x": 80, "y": 100 }, "status": "implemented",
+      "code_refs": [{ "path": "agent.py", "symbol": "decide_step" }] },
+    { "id": "call", "type": "service", "label": "call_tool",
+      "position": { "x": 380, "y": 100 }, "status": "implemented",
+      "code_refs": [{ "path": "agent.py", "symbol": "call_tool" }] },
+    { "id": "format", "type": "service", "label": "format_response",
+      "position": { "x": 680, "y": 100 }, "status": "implemented",
+      "code_refs": [{ "path": "agent.py", "symbol": "format_response" }] }
+  ],
+  "edges": [
+    { "id": "e1", "from": "decide", "to": "call",
+      "kind": "control", "label": "if tool needed" },
+    { "id": "e2", "from": "decide", "to": "format",
+      "kind": "control", "label": "if final answer" },
+    { "id": "e3", "from": "call", "to": "format",
+      "kind": "control", "label": "after tool" }
+  ]
+}
+```
+**B is usually right for LangGraph** because the structure between steps *is*
+the logic — the diagram makes routing errors visible at a glance.
+### 3. User renames or moves a function
+> User refactored `validate_email` → `validateEmail` and moved it to `lib/validation.ts`.
+```
+# Step 1: Find the drift
+loom_validate()
+# → reports nodes whose code_refs no longer resolve
+# Step 2: For each affected node, update the ref
+loom_update_node({
+  diagram: "overview",
+  id: "auth-form",
+  patch: {
+    code_refs: [{ path: "lib/validation.ts", symbol: "validateEmail" }]
+  }
+})
+# Step 3: Re-validate
+loom_validate()
+# → clean
+```
+### 4. User deletes a chunk of code
+> User: "I removed the legacy /v1 API."
+```
+loom_read_diagram("overview")
+# → identify nodes whose code is gone
+# Mark them stale instead of deleting:
+loom_mark_stale({ diagram: "overview", id: "api-v1-router" })
+loom_mark_stale({ diagram: "overview", id: "api-v1-auth" })
+```
+The user will review and decide whether to truly remove, archive, or
+re-purpose those nodes.
+### 5. The user wants a new domain
+> User: "Build out billing — invoices, subscriptions, dunning."
+Don't pile this into `overview.flow.json`. Create a dedicated diagram:
+```
+# Write .loom/diagrams/billing.flow.json with the planned nodes/edges.
+# Then, in overview, add a single placeholder node that drills into billing:
+loom_add_node({
+  diagram: "overview",
+  type: "service",
+  label: "Billing",
+  status: "planned",
+  drill_down: "billing"
+})
+```
+---
+## Format reference
+- Status enum: `planned`, `implemented`, `stale`, `deprecated`.
+- Edge kinds: `request`, `event`, `data-read`, `data-write`, `signal`,
+  `dependency`, `control`.
+- A node's `id` must match `^[a-z0-9-]+$`.
+- Use `from`/`to` like `node-id:port-name` only when the node's type declares
+  ports in `node-types.json`.
+## Don't
+- Don't create new top-level diagrams without checking if one already covers
+  the area.
+- Don't move node `position` coordinates unless explicitly asked — the user
+  arranges the canvas.
+- Don't invent node types — extend `node-types.json` first.
+- Don't write invalid JSON. The validator (server-side or `loom_validate`)
+  will refuse it.
+- Don't add a node for every function. A node is a **concept**; multiple
+  functions per node is normal (use `code_refs[]`).
+- Don't create a diagram per directory. Create one per **subsystem** or
+  **flow**.
+- Don't leave `drill_down` pointing at a non-existent diagram id.
+- Don't `loom_delete_node` for code that was just removed — `mark_stale` it.