mrplex 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brendan Baldwin
+
+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,284 @@
+# mrplex
+
+*Markdown Repos, plexed.*
+
+**Turn ordinary Markdown folders into queryable, versioned, graph-aware knowledge stores — without giving up files.** Your notes stay plain `.md` on disk; agents and humans share the same repository, every write is versioned, and links survive renames.
+
+## Install
+
+Node ≥ 20.11:
+
+```bash
+npm install -g mrplex
+```
+
+Prefer not to install globally? `npx mrplex …` works the same way.
+
+Point every command at a database and default repo once (the tour below uses `starship`):
+
+```bash
+export MRPLEX_DATABASE=./demo.db
+export MRPLEX_REPO=starship
+```
+
+Or persist settings in `~/.config/mrplex/config.json`:
+
+```bash
+mrplex config set-database ./demo.db
+mrplex config set-repo starship
+```
+
+Each setting resolves **flag → env → config file → default**, so one-off overrides never require editing anything.
+
+> **From a git checkout?** Run `npm install && npm link` (or `npm run cli -- …`). Every `mrplex …` command below is equivalent to `npx mrplex …`.
+
+## A five-minute tour
+
+This walkthrough uses the **USS Meridian** — a sample starship knowledge base in [`fixtures/starship/`](fixtures/starship/): crew files, mission records, officer logs, and equipment status, all ordinary Markdown with YAML frontmatter.
+
+### 1. Sync the sample corpus
+
+Clone the repo (for the fixture files), install, and sync the folder into a fresh mrplex repo:
+
+```bash
+git clone https://github.com/usergenic/mrplex
+cd mrplex
+npm install && npm link    # skip if you installed globally above
+
+export MRPLEX_DATABASE=./demo.db
+export MRPLEX_REPO=starship
+
+mrplex repos create starship
+mrplex sync fixtures/starship --once -r starship
+```
+
+`sync` is the normal way to load a Markdown folder: it pushes local files into the repo, materializes version metadata, and keeps a cursor for two-way updates. Frontmatter values written as repo-root paths (`/crew/foo.md`) and embedded wikilinks/inline links are indexed automatically — no link-config setup step.
+
+No bootstrap, no token — local mode is full-trust (whoever can run the binary owns the database).
+
+### 2. Query it like data
+
+Frontmatter is queryable with [CEL](https://github.com/google/cel-spec) filters:
+
+```bash
+# What's broken or offline right now?
+mrplex query --filter 'status == "damaged" || status == "offline"'
+
+# Who reports directly to the captain?
+mrplex query --filter '$has_static("crew/kestrel-vance.md", "reports_to")'
+```
+
+```text
+PATH                              STATUS
+equipment/plasma-manifold-3.md    damaged
+equipment/shuttle-corvid.md       offline
+…
+
+PATH                    TITLE
+crew/aria-okonkwo.md    Commander Aria Okonkwo
+crew/dax-thorne.md      Lieutenant Commander Dax Thorne
+crew/quill-vasquez.md   Doctor Quill Vasquez
+```
+
+Compose with full-text search — filter, text, and semantic (when configured) all AND together:
+
+```bash
+mrplex query --text 'manifold coolant'
+mrplex query --filter 'type == "mission"' --text 'Halloway'
+```
+
+### 3. Follow the links as a graph
+
+Markdown links, wikilinks, and frontmatter repo-root paths (`/crew/foo.md`) build a derived index bound to document *identity*, so backlinks survive renames. Query membership in CEL:
+
+```bash
+# Every mission indexed by the mission log MOC
+mrplex query --filter '$in_static("moc/missions.md")'
+
+# What touches the damaged plasma manifold? (maintainer field, body links, logs…)
+mrplex query --filter '$has_static("equipment/plasma-manifold-3.md")'
+```
+
+Explore *how* documents connect — neighborhood expansion from a root set:
+
+```bash
+mrplex graph --roots missions/the-hollow-signal.md --degrees 2 --direction both --render summary
+```
+
+The missing officer, his mission, the encounter, and the logs that mention him appear as a connected neighborhood — the kind of thread a flat file listing can't give you.
+
+Mermaid for slides or docs:
+
+```bash
+mrplex graph --roots crew/kestrel-vance.md --degrees 2 --direction out --render mermaid
+```
+
+### 4. Change something safely
+
+Every write inserts a new version; nothing is overwritten. Rename a document and the link graph follows its identity:
+
+```bash
+# See current version id, then move the manifold note
+V=$(mrplex --json docs get equipment/plasma-manifold-3.md | jq -r .version_id)
+mrplex docs mv equipment/manifold-3.md --prev "$V"
+
+# Backlinks still resolve — the graph never broke; link text may need repair
+mrplex query --filter '$has_static("equipment/manifold-3.md")'
+mrplex links stale
+```
+
+History and unified diff between any two versions:
+
+```bash
+mrplex docs history equipment/manifold-3.md
+mrplex docs diff equipment/manifold-3.md --from v1 --to v2
+```
+
+Deletion moves a document to a system-namespace path (`:deleted/…`); restore is a normal `docs put` back to user territory.
+
+### 5. Connect an agent
+
+CLI, MCP, and REST are surfaces over the same model. Point Cursor (or any MCP client) at your local database:
+
+```json
+{
+  "mcpServers": {
+    "mrplex": {
+      "command": "mrplex",
+      "args": ["mcp-stdio", "--unsafe", "--database", "./demo.db"],
+      "env": { "MRPLEX_REPO": "starship" }
+    }
+  }
+}
+```
+
+An agent can now ask relational questions — *"What's broken on the ship, who maintains it, and which missions were affected?"* — and recover structured answers through `query` and `graph` instead of reading every file into context.
+
+Serve HTTP for remote clients or Streamable HTTP MCP:
+
+```bash
+mrplex serve --unsafe --port 8321 &
+mrplex --server http://127.0.0.1:8321 query --filter 'status == "missing"'
+```
+
+For shared or networked deployments, run the authenticating shell instead — see [Authentication](#authentication) below. Never expose the raw kernel (`serve --unsafe`) directly to an untrusted network.
+
+## How it works
+
+| Concept | What it means |
+|--------|----------------|
+| **Document** | One Markdown file with YAML frontmatter, addressed by repo-relative path |
+| **Version** | Every write appends; `prev_version_id` optimistic concurrency rejects stale writes |
+| **Query** | CEL filters over frontmatter + `$path` / `$body` / `$updated_at` intrinsics; composes with FTS and semantic search |
+| **Link graph** | Derived index over inline links, wikilinks, and frontmatter repo-root paths; `$in`, `$has`, `$backlinks`, `$links` in CEL |
+| **Graph** | BFS neighborhood expansion over the link index — *how* things connect, not just *which* match |
+| **Surfaces** | `mrplex` CLI (local or `--server`), MCP at `/mcp` or `mcp-stdio`, REST at `/repos/{repo}/…` |
+
+Two layers: a **full-trust kernel** (no in-engine auth) and an optional **access-and-identity shell** (API keys, OIDC, per-path write policy, audit log). See [docs/archive/security.md](docs/archive/security.md) for trust boundaries and deployment shapes.
+
+## Features
+
+<details>
+<summary>Full feature list</summary>
+
+- **Versioned Markdown store** — every write inserts; `docs.put` handles in-place update and move; any past state is addressable
+- **Byte-exact frontmatter** — `frontmatter_raw` (verbatim YAML) or `frontmatter` (JSON); exactly one; round-trips are byte-exact via raw
+- **Optimistic concurrency** — stale `prev_version_id` → `stale_prev` with current version returned
+- **Deletion as move** — `:deleted/…` paths; idempotent delete; restore via `docs.put`
+- **Unified diff** — `docs.diff`, REST `/diff`, MCP `docs_diff`, CLI `mrplex docs diff`; `patch(1)`-applicable output
+- **CEL filter queries** — frontmatter fields + `$`-intrinsics; `list()` polymorphism for scalar-or-list fields
+- **Link graph** — inline, wikilink, and frontmatter path extraction (no per-field config); backlinks survive renames; set algebra (`$in("moc/**") && !$in("moc/draft.md")`); `$in_static` for link-only membership; `links stale` / `repair` / `backfill`
+- **Graph exploration** — BFS with direction lens, visibility filter, graph-only `$degrees` intrinsic; CLI `--render summary|yaml|mermaid|json`
+- **Full-text search** — SQLite FTS5 or Postgres `websearch_to_tsquery`; composes with filter via AND
+- **Semantic search** — pluggable `--embedder` hook; chunker + backlog worker; `$semantic_score` in `select`; no hook → `semantic_unavailable`
+- **HTTP surfaces** — MCP (Streamable HTTP + STDIO), REST with `If-Match` / content negotiation / `MOVE`
+- **CLI** — thin MCP client; `--database` local or `--server` remote; identical commands over both
+- **Storage** — SQLite (default) or Postgres+pgvector; same kernel test suite on both
+- **Path policy** — configurable sigils and disallowed chars; NFC + case-insensitive identity, case-preserved storage
+- **Canonical paths** — API responses use slashless repo-relative paths; leading `/` accepted as root alias on input only
+
+Prior design docs in [docs/archive/](docs/archive/) may be out of date where later work supersedes them.
+
+</details>
+
+## Authentication
+
+For anything beyond single-user local use, run the **authenticating shell** — `serve --policy`. It reads declarative YAML (roles, principals, grants, key hashes, OIDC bindings), authenticates each request, and dispatches against a per-principal *guarded* kernel: read visibility narrowed, writes enforced per-path, author derived from the credential, every call audited.
+
+```yaml
+# policy.yaml
+roles:
+  editor:
+    grants:
+      - repo: notes
+        read: "**"
+        write: ["drafts/**", "inbox/**"]
+  operator:
+    grants:
+      - { repo: "*", read: "**", write: "**" }
+    destructive: true
+
+principals:
+  brendan:
+    author: Brendan Baldwin <brendan@example.com>
+    roles: [operator]
+    keys:
+      - sha256:...        # `mrplex key mint brendan --policy policy.yaml`
+  ann:
+    roles: [editor]
+    oidc: { email: ann@example.com }
+```
+
+```bash
+mrplex key mint brendan --policy policy.yaml
+mrplex serve --policy policy.yaml --audit audit.jsonl --port 8321 &
+curl -H "Authorization: Bearer $KEY" http://127.0.0.1:8321/repos
+```
+
+Three deployment shapes — **embedded** (`serve --policy`), **launcher** (`mcp-stdio --policy`), and **fronting proxy** (`proxy --policy --upstream`). Edit the policy and `kill -HUP` to reload grants without restart. OIDC device-flow login via `mrplex login`. Full details in [docs/archive/security.md](docs/archive/security.md).
+
+## Embeddings
+
+mrplex never calls an embedding provider itself — wire one with `--embedder` (subprocess command or HTTP URL). For local CPU embeddings:
+
+```bash
+npm install -g @mrplex/embedder
+export MRPLEX_EMBEDDER=mrplex-embedder
+
+mrplex serve --unsafe --embedder mrplex-embedder
+mrplex embed backfill -r starship
+mrplex query -r starship --semantic 'distress beacon star map'
+```
+
+Resolution: **flag → `MRPLEX_EMBEDDER` → `mrplex config set-embedder` → unset**. See [packages/embedder/README.md](packages/embedder/README.md) for protocol details.
+
+## Development
+
+```bash
+npm install
+npm link
+npm test
+npm run typecheck
+npm run lint
+npm run build
+```
+
+Seed the full dev fixture set (notes + starship):
+
+```bash
+npm run seed -- --database ./mrplex.db
+```
+
+CI runs typecheck + lint + tests on Ubuntu & macOS × Node 20 & 22, plus Postgres+pgvector parity. If tests fail with a `NODE_MODULE_VERSION` error from `better-sqlite3`, run `npm rebuild better-sqlite3`.
+
+### Postgres locally
+
+```bash
+npm run pg:up
+export MRPLEX_DATABASE=postgres://mrplex:mrplex@localhost:5432/mrplex
+mrplex serve --unsafe
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/cli/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CLI config loading + saving — `~/.config/mrplex/config.json` (m1-plan §5
+ * said toml; we ship JSON in M1 for zero deps, and the format is trivial
+ * to migrate to toml later without breaking existing files).
+ *
+ * The config holds:
+ *   • database  — the URL used when --database is absent
+ *   • token     — the bearer token used when --token / MRPLEX_TOKEN absent
+ *
+ * File is chmod 600 on save (best-effort — Windows doesn't honor POSIX
+ * modes; the file will simply be user-readable there).
+ */
+export type CliConfig = {
+    database?: string;
+    server?: string;
+    token?: string;
+    repo?: string;
+    author?: string;
+    /** Default --embedder (command or http(s):// URL). */
+    embedder?: string;
+    /** @deprecated Use `embedder`. */
+    embed_url?: string;
+    /** @deprecated Use `embedder`. */
+    embed_cmd?: string;
+};
+export declare function configPath(): string;
+export declare function loadConfig(): CliConfig;
+export declare function saveConfig(next: CliConfig): void;

package/dist/cli/config.js

@@ -0,0 +1,48 @@
+/**
+ * CLI config loading + saving — `~/.config/mrplex/config.json` (m1-plan §5
+ * said toml; we ship JSON in M1 for zero deps, and the format is trivial
+ * to migrate to toml later without breaking existing files).
+ *
+ * The config holds:
+ *   • database  — the URL used when --database is absent
+ *   • token     — the bearer token used when --token / MRPLEX_TOKEN absent
+ *
+ * File is chmod 600 on save (best-effort — Windows doesn't honor POSIX
+ * modes; the file will simply be user-readable there).
+ */
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export function configPath() {
+    const xdgConfig = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(xdgConfig, "mrplex", "config.json");
+}
+export function loadConfig() {
+    const path = configPath();
+    try {
+        const text = readFileSync(path, "utf8");
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return {};
+        }
+        return parsed;
+    }
+    catch (err) {
+        // File missing or malformed → empty config; the CLI treats this as normal.
+        if (err.code === "ENOENT")
+            return {};
+        return {};
+    }
+}
+export function saveConfig(next) {
+    const path = configPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // POSIX mode unsupported on this platform — best-effort.
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/cli/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAgB1C,MAAM,UAAU,UAAU;IACxB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IAC5E,OAAO,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;QAC3C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3E,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,MAAmB,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,2EAA2E;QAC3E,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAChE,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAe;IACxC,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3E,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;IAC3D,CAAC;AACH,CAAC"}

package/dist/cli/exit-codes.d.ts

@@ -0,0 +1,13 @@
+/**
+ * CLI exit-code families — design §7.3.
+ *
+ *   1  validation
+ *   2  concurrency / conflict     (M1)
+ *   3  auth                        (M1)
+ *   4  not-found
+ *   10 network / transport         (M3)
+ *
+ * Everything else exits 1.
+ */
+import type { KernelErrorCode } from "../kernel/errors.js";
+export declare function exitCodeForKernelError(code: KernelErrorCode): number;

package/dist/cli/exit-codes.js

@@ -0,0 +1,39 @@
+/**
+ * CLI exit-code families — design §7.3.
+ *
+ *   1  validation
+ *   2  concurrency / conflict     (M1)
+ *   3  auth                        (M1)
+ *   4  not-found
+ *   10 network / transport         (M3)
+ *
+ * Everything else exits 1.
+ */
+export function exitCodeForKernelError(code) {
+    switch (code) {
+        case "repo_not_found":
+        case "doc_not_found":
+        case "version_not_found":
+            return 4;
+        case "stale_prev":
+        case "create_conflict":
+        case "path_taken":
+        case "slug_taken":
+            return 2;
+        case "forbidden":
+            return 3;
+        case "slug_invalid":
+        case "path_invalid":
+        case "frontmatter_invalid":
+        case "filter_invalid":
+        case "link_config_invalid":
+        case "version_not_in_document":
+        case "precondition_required":
+        case "payload_too_large":
+        case "semantic_unavailable":
+            return 1;
+        default:
+            return 1;
+    }
+}
+//# sourceMappingURL=exit-codes.js.map

package/dist/cli/exit-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../../src/cli/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,UAAU,sBAAsB,CAAC,IAAqB;IAC1D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,gBAAgB,CAAC;QACtB,KAAK,eAAe,CAAC;QACrB,KAAK,mBAAmB;YACtB,OAAO,CAAC,CAAC;QACX,KAAK,YAAY,CAAC;QAClB,KAAK,iBAAiB,CAAC;QACvB,KAAK,YAAY,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,CAAC,CAAC;QACX,KAAK,WAAW;YACd,OAAO,CAAC,CAAC;QACX,KAAK,cAAc,CAAC;QACpB,KAAK,cAAc,CAAC;QACpB,KAAK,qBAAqB,CAAC;QAC3B,KAAK,gBAAgB,CAAC;QACtB,KAAK,qBAAqB,CAAC;QAC3B,KAAK,yBAAyB,CAAC;QAC/B,KAAK,uBAAuB,CAAC;QAC7B,KAAK,mBAAmB,CAAC;QACzB,KAAK,sBAAsB;YACzB,OAAO,CAAC,CAAC;QACX;YACE,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/cli/format.d.ts

@@ -0,0 +1,22 @@
+import type { GraphResult, QueryHit, Repo, Version } from "../kernel/wire.js";
+/**
+ * Pretty-printers for CLI output. `--json` bypasses these entirely.
+ */
+export declare function renderVersionAsMarkdown(v: Version): string;
+export declare function renderReposTable(repos: Repo[]): string;
+export declare function renderQueryTable(hits: QueryHit[]): string;
+export declare function renderHistoryTable(versions: Version[]): string;
+/**
+ * YAML dump of the structured payload — a better *reading* format than JSON
+ * for a human or LLM skimming a subgraph. Hand-rolled (the shape is flat and
+ * known) rather than pulling in a YAML serializer.
+ */
+export declare function renderGraphYaml(result: GraphResult): string;
+/**
+ * Mermaid flowchart — passthrough-renderable by most chat/markdown surfaces.
+ * The id-sanitization rule is load-bearing: generated ids (`d0`, `d1`, …) with
+ * the path only ever as a quoted label — a path as a mermaid id would break on
+ * slashes, dots, and colons. Roots (degrees 0) get a classDef; a trailing `%%`
+ * comment echoes truncation.
+ */
+export declare function renderGraphMermaid(result: GraphResult): string;

package/dist/cli/format.js

@@ -0,0 +1,148 @@
+import { join as joinFrontmatter } from "../markdown/frontmatter.js";
+/**
+ * Pretty-printers for CLI output. `--json` bypasses these entirely.
+ */
+export function renderVersionAsMarkdown(v) {
+    return joinFrontmatter({ frontmatter_raw: v.frontmatter_raw, body: v.body });
+}
+export function renderReposTable(repos) {
+    if (repos.length === 0)
+        return "(no repos)";
+    const rows = repos.map((r) => [r.repo, r.path_config ? "custom" : "default"]);
+    return renderTable(["REPO", "PATH CONFIG"], rows);
+}
+export function renderQueryTable(hits) {
+    if (hits.length === 0)
+        return "(no results)";
+    // Columns are the union of projected keys, in first-seen order across hits —
+    // `select` decides which fields are present, so the table follows suit.
+    const columns = [];
+    const seen = new Set();
+    for (const hit of hits) {
+        for (const key of Object.keys(hit)) {
+            if (!seen.has(key)) {
+                seen.add(key);
+                columns.push(key);
+            }
+        }
+    }
+    const rows = hits.map((hit) => columns.map((key) => renderCell(hit[key])));
+    return renderTable(columns, rows);
+}
+function renderCell(value) {
+    // A key absent from this hit (not selected, or missing frontmatter) is an
+    // empty cell; a present-but-null intrinsic (e.g. $next_version_id on the
+    // current version) renders as "null" to match the MCP text renderer.
+    if (value === undefined)
+        return "";
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return value;
+    return JSON.stringify(value);
+}
+export function renderHistoryTable(versions) {
+    if (versions.length === 0)
+        return "(no history)";
+    const rows = versions.map((v) => [
+        v.version_id,
+        v.created_at,
+        v.author,
+        v.next_version_id === null ? "current" : "",
+    ]);
+    return renderTable(["VERSION", "CREATED_AT", "AUTHOR", "STATE"], rows);
+}
+function renderTable(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+    const line = (cells) => cells
+        .map((c, i) => c.padEnd(widths[i] ?? 0))
+        .join("  ")
+        .trimEnd();
+    return [
+        line(headers),
+        line(headers.map((_, i) => "-".repeat(widths[i] ?? 0))),
+        ...rows.map(line),
+    ].join("\n");
+}
+// -----------------------------------------------------------------------------
+// Graph renders (docs/graph-plan.md §2.3). CLI-only presentations of the
+// structured GraphResult; the `summary` render is shared with the MCP text
+// half (mcp/render.ts renderGraphSummary). These are pure functions of the
+// result — presentation is a surface concern, never a call parameter.
+// -----------------------------------------------------------------------------
+/**
+ * YAML dump of the structured payload — a better *reading* format than JSON
+ * for a human or LLM skimming a subgraph. Hand-rolled (the shape is flat and
+ * known) rather than pulling in a YAML serializer.
+ */
+export function renderGraphYaml(result) {
+    const lines = [];
+    lines.push("documents:");
+    if (result.documents.length === 0)
+        lines.push("  []");
+    for (const doc of result.documents) {
+        lines.push(`  - $path: ${yamlScalar(doc.$path)}`);
+        lines.push(`    $degrees: ${doc.$degrees}`);
+        lines.push(`    $links: ${doc.$links}`);
+        lines.push(`    $backlinks: ${doc.$backlinks}`);
+        for (const [key, value] of Object.entries(doc)) {
+            if (key === "$path" || key === "$degrees" || key === "$links" || key === "$backlinks") {
+                continue;
+            }
+            lines.push(`    ${key}: ${yamlScalar(value)}`);
+        }
+    }
+    lines.push("links:");
+    if (result.links.length === 0)
+        lines.push("  []");
+    for (const l of result.links) {
+        lines.push(`  - source: ${yamlScalar(l.source)}`);
+        lines.push(`    target: ${yamlScalar(l.target)}`);
+        lines.push(`    field: ${yamlScalar(l.field)}`);
+    }
+    lines.push(`frontier: [${result.frontier.map(yamlScalar).join(", ")}]`);
+    lines.push(`complete_degrees: ${result.complete_degrees}`);
+    lines.push(`truncated: ${result.truncated}`);
+    return lines.join("\n");
+}
+/** Quote a scalar for YAML when it isn't a safe bare token. */
+function yamlScalar(v) {
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    const s = String(v);
+    if (s === "" || /[:#\-?\[\]{},&*!|>'"%@`]/.test(s) || /^\s|\s$/.test(s)) {
+        return JSON.stringify(s);
+    }
+    return s;
+}
+/**
+ * Mermaid flowchart — passthrough-renderable by most chat/markdown surfaces.
+ * The id-sanitization rule is load-bearing: generated ids (`d0`, `d1`, …) with
+ * the path only ever as a quoted label — a path as a mermaid id would break on
+ * slashes, dots, and colons. Roots (degrees 0) get a classDef; a trailing `%%`
+ * comment echoes truncation.
+ */
+export function renderGraphMermaid(result) {
+    const lines = ["flowchart LR"];
+    const idByPath = new Map();
+    result.documents.forEach((doc, i) => {
+        const id = `d${i}`;
+        idByPath.set(doc.$path, id);
+        const rootClass = doc.$degrees === 0 ? ":::root" : "";
+        lines.push(`  ${id}[${JSON.stringify(doc.$path)}]${rootClass}`);
+    });
+    for (const l of result.links) {
+        const s = idByPath.get(l.source);
+        const t = idByPath.get(l.target);
+        if (s === undefined || t === undefined)
+            continue;
+        lines.push(`  ${s} -->|${JSON.stringify(l.field)}| ${t}`);
+    }
+    if (result.documents.some((d) => d.$degrees === 0)) {
+        lines.push("  classDef root stroke-width:3px");
+    }
+    const note = `complete through ${result.complete_degrees} degree${result.complete_degrees === 1 ? "" : "s"}${result.truncated ? " · truncated" : ""}`;
+    lines.push(`  %% ${note}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=format.js.map

package/dist/cli/format.js.map

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

package/dist/cli/main.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * mrplex CLI — reads + writes + config + serve + remote mode.
+ *
+ * The CLI is a thin client over the MCP surface (§7.3). When `--server` is
+ * set, commands drive `tools/call` against `<server>/mcp`; otherwise the CLI
+ * opens the local SQLite file and calls the kernel in-process. The
+ * transport seam is `KernelClient` (`src/client/*`).
+ *
+ * No-auth (noauth plan): there is no bootstrap / tokens / users. Identity is
+ * one opaque `author` string (--author → MRPLEX_AUTHOR → config → "mrplex");
+ * `--scope <json>` narrows read visibility. In remote mode an optional --token
+ * is forwarded verbatim as a bearer for a shell fronting the server; mrplex
+ * itself ignores it. serve deliberately bypasses the seam — it IS the server.
+ */
+export {};