{"_id":"@pypl100/rune","_rev":"3-61b8e5c50845c5fac2d94218cb111a63","name":"@pypl100/rune","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@pypl100/rune","version":"0.1.0","keywords":["ai","mcp","code-understanding","software-intelligence","react","nextjs","express","static-analysis"],"author":"","license":"MIT","_id":"@pypl100/rune@0.1.0","maintainers":[{"name":"pypl100","email":"a07735198@gmail.com"}],"bin":{"rune":"bin/rune.js"},"dist":{"shasum":"c4020343e6212109a47855e7a0d6439cbbf0c856","tarball":"https://registry.npmjs.org/@pypl100/rune/-/rune-0.1.0.tgz","fileCount":17,"integrity":"sha512-QwVpRn6YdkOLLdXyHk39a8WLWREG6YHjMvzvlCgFn7kh7TrHe5ukCV6OxBSHNbCYlxQyGhi0jMtN4O30AMwNwQ==","signatures":[{"sig":"MEUCIC8GXD8qNPsotrQpvr7bfyuS63T6Ib5MR1CYvml8zt8fAiEAj9LwIfq4asITxSYdjR5ij2U6VIr51rdX8Njk/rrQKbs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43331},"main":"./src/index.js","type":"module","engines":{"node":">=18"},"gitHead":"1125b8b450f338fe55a57efd2df1e03ee2a96dee","scripts":{"scan":"node ./bin/rune.js scan","test":"node --test test/*.test.js","serve":"node ./bin/rune.js serve","verify:mcp":"node scripts/verify-mcp-server.mjs"},"_npmUser":{"name":"pypl100","email":"a07735198@gmail.com"},"_npmVersion":"10.8.2","description":"The Software Intelligence Runtime — persistent, explainable software understanding for any AI.","directories":{},"_nodeVersion":"20.19.0","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/rune_0.1.0_1785302744136_0.5727047786087416","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@pypl100/rune","version":"0.1.1","keywords":["ai","mcp","code-understanding","software-intelligence","react","nextjs","express","static-analysis"],"author":"","license":"MIT","_id":"@pypl100/rune@0.1.1","maintainers":[{"name":"pypl100","email":"a07735198@gmail.com"}],"bin":{"rune":"bin/rune.js"},"dist":{"shasum":"822aaa898d9f52fb7d1006dbcc7d69e6cb12e289","tarball":"https://registry.npmjs.org/@pypl100/rune/-/rune-0.1.1.tgz","fileCount":17,"integrity":"sha512-+KXZh7FIl/Ryma5aCaU8ZTVghNVcC2mJweza+A+PT7DLxax6v08NqlX47j2kOAhUl8xRv7wAJM46qa+YlUOClA==","signatures":[{"sig":"MEUCIHRCRyAUqmSp2T5wbZEeiMXqUI3M7a59UdEeIktULRwWAiEA6gWY5m8FNLIM/IuA7s/c8fUuKUF+HNRXCyh1DTdM2C4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44625},"main":"./src/index.js","type":"module","engines":{"node":">=18"},"gitHead":"9248d98b96f1ffc9a4fa816842c91a79a392294c","scripts":{"scan":"node ./bin/rune.js scan","test":"node --test test/*.test.js","serve":"node ./bin/rune.js serve","verify:mcp":"node scripts/verify-mcp-server.mjs"},"_npmUser":{"name":"pypl100","email":"a07735198@gmail.com"},"_npmVersion":"10.8.2","description":"The Software Intelligence Runtime — persistent, explainable software understanding for any AI.","directories":{},"_nodeVersion":"20.19.0","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/rune_0.1.1_1785324243207_0.9817777127828817","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@pypl100/rune","version":"0.2.0","description":"The Software Intelligence Runtime — persistent, explainable software understanding for any AI.","type":"module","bin":{"rune":"bin/rune.js"},"main":"./src/index.js","publishConfig":{"access":"public"},"engines":{"node":">=18"},"scripts":{"scan":"node ./bin/rune.js scan","serve":"node ./bin/rune.js serve","test":"node --test test/*.test.js","verify:mcp":"node scripts/verify-mcp-server.mjs"},"keywords":["ai","mcp","code-understanding","software-intelligence","react","nextjs","express","static-analysis"],"author":"","license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.25.0"},"_id":"@pypl100/rune@0.2.0","gitHead":"1e575650b16afc8c3b2bff34df14085e10aeed3b","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-8ZrrN8O/E/aRywGUZBdMMjaIWIlqFqNHcZQGFLAmGMcLZxGfbExVCbuOYdH8oKUh9+KYyX24FpN051SXBdQBXQ==","shasum":"67f32b4d3e2f97fa63ad180579f490dcb66bfd1b","tarball":"https://registry.npmjs.org/@pypl100/rune/-/rune-0.2.0.tgz","fileCount":18,"unpackedSize":52635,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICStl2R9K7Z8yZ8Awl1B/AvGpUWitISmScfnfjbXPJTUAiEAwpcMkCSvV3YRLLivXLZiKhJH4bUPWVOUQpny9lmjuNM="}]},"_npmUser":{"name":"pypl100","email":"a07735198@gmail.com"},"directories":{},"maintainers":[{"name":"pypl100","email":"a07735198@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rune_0.2.0_1785409705472_0.18998719570602707"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-29T05:25:43.968Z","modified":"2026-07-30T11:08:25.951Z","0.1.0":"2026-07-29T05:25:44.329Z","0.1.1":"2026-07-29T11:24:03.353Z","0.2.0":"2026-07-30T11:08:25.663Z"},"license":"MIT","keywords":["ai","mcp","code-understanding","software-intelligence","react","nextjs","express","static-analysis"],"description":"The Software Intelligence Runtime — persistent, explainable software understanding for any AI.","maintainers":[{"name":"pypl100","email":"a07735198@gmail.com"}],"readme":"# Rune\n\n**The Software Intelligence Runtime.**\n\nCursor, Codex, and Claude Code write your code — one session at a time. Open a session, they read your files cold, reason about them, make changes, and when the session ends, whatever they figured out is gone. Next session, same cold start.\n\nRune doesn't write code. It's the thing that runs underneath all of them, continuously — watching your codebase, keeping a standing, evidence-backed understanding of it current, so every session (yours or an agent's) starts already knowing the architecture instead of re-deriving it from scratch.\n\nNo more re-explaining your routes and components every time. No more every assistant independently rediscovering the same things. Connect an AI to Rune, and it already understands your codebase — and can show you exactly why.\n\n*Under the hood, Rune continuously builds an evidence-backed understanding of your software and exposes it through MCP — see [How it works](#how-it-works) if you want the internals.*\n\n---\n\n## What Rune does\n\n- **Always current** — `rune watch` keeps the understanding graph up to date as you edit, not just when someone remembers to re-run a scan. It's a runtime, not a one-shot CLI.\n- **Persistent** — understanding survives past any single session. Every AI you connect starts already knowing your software, instead of re-reading it cold.\n- **Shared** — one understanding, many AI clients. Claude, GPT, Gemini, whatever you're running next month — they all ask the same Rune instance instead of maintaining separate, inconsistent mental models of your code.\n- **Explainable** — nothing Rune tells an AI is a black box. Ask it to justify any claim and it shows the exact source location behind it.\n- **Read-only, suggest-only** — Rune never writes to your source. That's the actual moat: everything else in this space is racing toward autonomous code-writing; Rune stays strictly on the reading, understanding, and (later) suggesting side of that line. It never becomes the thing you have to double-check for silently breaking your code.\n\n## How it works\n\nYou don't need to think about this to use Rune — it's here for anyone extending or debugging it.\n\nInternally, Rune keeps two distinct layers:\n\n- **Facts** — directly observed things: an import statement, an `app.get(...)` call, a function that returns JSX, a file convention that defines a Next.js route. Every fact records its file, line, and the exact matched source text.\n- **Derived understanding** — conclusions built *from* facts: an architecture summary, a unified API surface across Express and Next.js, a component index, file-level dependency relationships. Every conclusion lists exactly which facts it's based on.\n\nNothing in the derived layer is asserted without a traceable path back to evidence. Call `rune explain <id>` (or the `rune_explain` MCP tool) on anything and get the fact chain behind it. That's the whole trust story: an AI using Rune isn't guessing about your architecture, and neither is Rune.\n\n## Install\n\n```bash\nnpm install @pypl100/rune\n```\n\n*A Python distribution exists at [`python/`](python/) with full feature parity (same fact/derived model, same detectors, same MCP tool surface) for teams who'd rather not require Node.js — published as `pip install north-rune` (the CLI command is still `rune`; see [python/README.md](python/README.md)).*\n\n> **If you install both** (`@pypl100/rune` via npm globally, and `north-rune` via pip) on the same machine, only one `rune` command will actually be on your `PATH` — whichever your shell finds first, not whichever you installed most recently. Check with `which -a rune`; if it lists more than one path, that's why. There's no version-detection magic here — it's plain OS `PATH` resolution, same as any two unrelated tools that happen to install a same-named binary. If you need a specific one, invoke it by its full path rather than relying on bare `rune`.\n\n## Quickstart\n\n```bash\ncd your-project\nnpm install -g @pypl100/rune   # or: npx -p @pypl100/rune rune <command>\nrune init      # sets up Rune in your project\nrune watch &    # keeps the understanding current in the background as you work\nrune serve      # starts an MCP server exposing it to any AI client\n```\n\n`rune watch` is the recommended default — it's what makes Rune a runtime instead of a tool you have to remember to re-run. `rune scan` (a one-shot version of the same thing) still works if you'd rather trigger it manually, e.g. in CI.\n\nThen point any MCP-compatible client (Claude Desktop, Claude Code, custom agents, etc.) at the `rune serve` process. Every connected AI now shares the same, continuously current understanding instead of re-deriving it per session.\n\nExample MCP client config entry:\n\n```json\n{\n  \"mcpServers\": {\n    \"rune\": {\n      \"command\": \"npx\",\n      \"args\": [\"-p\", \"@pypl100/rune\", \"rune\", \"serve\", \"/absolute/path/to/your-project\"]\n    }\n  }\n}\n```\n\n## CLI\n\n| Command | What it does |\n|---|---|\n| `rune init [dir]` | Sets up `.rune/` in the current (or given) project |\n| `rune scan [dir]` | Builds (or rebuilds) the understanding graph, once |\n| `rune watch [dir]` | Keeps the understanding graph current as files change (Ctrl+C to stop) |\n| `rune serve [dir]` | Starts the MCP server |\n| `rune explain <id>` | Prints the evidence trail behind any fact or conclusion |\n| `rune --version` | Prints the installed Rune version |\n\n## Configuration\n\n`rune init` writes `.rune/config.json`. The only setting in v0.1 is `ignore` — an array of directory/file names to exclude from scanning, on top of the built-in defaults (`node_modules`, `.git`, `dist`, `build`, `.next`, `coverage`, etc., and all dotfiles unconditionally):\n\n```json\n{\n  \"ignore\": [\"legacy\", \"vendor\"],\n  \"version\": 1\n}\n```\n\n## MCP tools exposed\n\n| Tool | Purpose |\n|---|---|\n| `rune_get_overview` | Architecture summary — start here |\n| `rune_list_components` | All detected React components |\n| `rune_list_routes` | Unified Express + Next.js route list |\n| `rune_search` | Find facts/derived nodes by name, file, or route substring |\n| `rune_explain` | Full evidence trail for any id |\n| `rune_get_file_dependencies` | Internal import graph for a file |\n| `rune_rescan` | Re-scan on demand after code changes |\n\n## v0.1 scope and honest limitations\n\nRune v0.1 is intentionally narrow:\n\n- **Framework support:** React, Next.js (pages + app router), Express. Everything else gets generic file/import scanning only.\n- **Extraction method:** heuristic, regex-based pattern matching — not a full AST parser. This keeps v0.1 dependency-free and fast, and every fact still carries file/line/matched-text evidence, but it will miss unusual code shapes (e.g. components returned via `React.createElement` with no JSX, dynamically constructed route strings, deeply re-exported components). A real AST-based extractor is the natural v0.2 upgrade — the fact schema is designed so extraction method can be swapped without touching anything downstream.\n- **No cross-file route-prefix resolution:** an Express route mounted via `app.use('/api', router)` in one file and defined in another isn't stitched into a single path yet.\n- **Read-only:** Rune never writes to your source files. It only ever writes its own graph to `.rune/graph.json`.\n- **Single-process, stdio MCP transport** in v0.1 — no multi-client daemon yet.\n\n## Security notes\n\n- Rune **never scans dotfiles or dot-directories** (`.env`, `.env.*.js`, `.git`, `.ssh`, editor configs, etc.), with no exceptions. This is enforced in the scanner and covered by a regression test — a config file with a matching code extension (e.g. `.env.js`) will not have its contents read or embedded as evidence.\n- Symlinks are not traversed, so a symlink pointing outside the project root can't pull external files into the scan.\n- `.rune/graph.json` is excluded from git by `rune init` (it creates `.gitignore` if one doesn't already exist).\n- The graph itself is the only thing Rune writes. If you share `.rune/graph.json` with an AI client, you're sharing everything in it — treat it like any other file that quotes snippets of your source.\n\n## Verifying the MCP server\n\nThe unit test suite (`npm test`) covers scanning and the understanding graph, but doesn't spin up a real MCP client. `scripts/verify-mcp-server.mjs` does: it spawns `rune serve` as a real child process and drives it through the actual JSON-RPC handshake (`initialize` → `notifications/initialized` → `tools/list` → `tools/call`), checks that all expected tools are exposed, and confirms a genuinely invalid call is rejected cleanly rather than crashing the server.\n\n```bash\nnpm install\nnpm run verify:mcp\n# or against a real project instead of the bundled fixture:\nnpm run verify:mcp -- /path/to/your-project\n```\n\n## Roadmap\n\n- AST-based extraction (swap-in replacement for the regex scanner)\n- Cross-file route resolution\n- Data-flow tracing between frontend calls and backend routes\n- True incremental re-scan — `rune watch` exists now, but it still does a full rebuild on every change, not a diff of just what changed. Fine for small-to-medium projects; will matter on very large ones.\n- Suggestion tools (e.g. flagging a known-vulnerable dependency pattern with evidence, proposing a reviewable fix) — strictly additive to the read-only model, never auto-applied\n\n## License\n\nMIT\n\n---\n\nIf you want to support the circus: ETH `0xbc0979dde621c353737d21f6d7b4eb361f7bc11f`\n","readmeFilename":"README.md"}