@miadi/stateloom-mcp 0.2.5 → 0.3.0

package/README.md

@@ -116,8 +116,28 @@ outside the root. `generate_code` writes only to a temporary directory. Note tha
 | `generate_code` | Emit Python or TypeScript from the definition |
 | `generate_rispec` | Emit a RISE rispec in markdown, folding in the source PDE's intent when the SMDF carries one |
 | `render_diagram` | Draw the machine as `png`, `svg`, `mermaid` or `ascii`, write it beside the document, and hand a `png` back inside the tool result so the agent sees what it designed |
-| `set_project_file` | Re-point the loom at another `.smdf.json` mid-session — disk target and live room both move |
+| `set_project_file` | Re-point the loom at another document mid-session — a `.smdf.json` or a `.erdf.json`; disk target and live room both move |
 | `get_project_file` | The active document path, whether it exists, and bridge status |
+| `get_notes` | Every note in the active document in one call — the diagram's own first, then each shape that has one |
+| `set_notes` | Save (or, with an empty string, clear) working notes on the diagram or on one state / entity. Kept in the document for whoever opens it next; ignored by engines and codegen |
+
+### Entity-relationship diagrams
+
+The same server designs the **data** beside the machines, in a sibling `.erdf.json`. The
+active document's type is its extension: while an ERD is active, `get_definition`,
+`load_definition` and `render_diagram` (mermaid `erDiagram`) answer for it, and the
+state-machine tools refuse to write a machine over it.
+
+| Tool | What it does |
+|---|---|
+| `create_erd` | Start an ERD beside the active document and make it the active one |
+| `add_entity` / `update_entity` / `remove_entity` | An entity, optionally `weak`; removing one takes its relationships with it |
+| `add_attribute` / `remove_attribute` | `type`, `key` (`pk` / `uk`), `references` (the foreign key), `nullable`, and `stateOf` — the state machine whose state this attribute stores |
+| `add_relationship` / `remove_relationship` | `1:1`, `1:N`, `N:1`, `N:M`, read left to right, with a verb as the label |
+| `validate_erd` | Rules E001–E005 |
+| `check_links` | Rules L001–L004: what a state machine names — an object's class, a field in a guard, a `stateOf` — that the ERD does not carry |
+
+Format and rules: [Spec 80 — ERDF](https://github.com/jgwill/smcraft/blob/main/rispecs/80-erdf-format.spec.md).
 
 Also exposed: the resource `smcraft://definition` (the current definition), and the prompt `design-state-machine` — a guided conversation for building one from a domain description.
 

package/dist/atomicWrite.d.ts

@@ -0,0 +1 @@
+export declare function writeFileAtomic(path: string, text: string): void;

package/dist/atomicWrite.js

@@ -0,0 +1,28 @@
+/**
+ * Write a document whole or not at all: to a temp file beside it, then rename.
+ *
+ * A reader (the hub's file watch, a canvas, another tool) never sees half a
+ * file. An existing file that is not writable stays refused — a rename would
+ * replace it regardless of its mode, and a read-only document is a person's
+ * word that it should not change — and the new file keeps the old one's mode.
+ */
+import { accessSync, chmodSync, constants, existsSync, renameSync, rmSync, statSync, writeFileSync } from "fs";
+import { basename, dirname, join } from "path";
+export function writeFileAtomic(path, text) {
+    let mode;
+    if (existsSync(path)) {
+        accessSync(path, constants.W_OK);
+        mode = statSync(path).mode & 0o7777;
+    }
+    const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}.tmp`);
+    try {
+        writeFileSync(temp, text, "utf8");
+        if (mode !== undefined)
+            chmodSync(temp, mode);
+        renameSync(temp, path);
+    }
+    catch (e) {
+        rmSync(temp, { force: true });
+        throw e;
+    }
+}

package/dist/erd.d.ts

@@ -25,6 +25,8 @@ export interface ErdHost {
     emitFull(def: EntityRelationshipDefinition): void;
     /** The refusal for a path outside the permitted document root, if any. */
     outsideRoot(path: string): string | undefined;
+    /** check_links from a sequence or a system: the whole system's check (check_system). */
+    checkSystem?(): Promise<ToolResult>;
 }
 type ToolResult = {
     content: {
@@ -43,5 +45,12 @@ export declare function erdRender(host: ErdHost, opts: {
     path?: string;
     stamp?: boolean;
 }): ToolResult;
+/** One block per note, the diagram's own first. What `get_notes` answers with for either document type. */
+export declare function formatNotes(name: string, path: string, entries: {
+    target: string | null;
+    notes: string;
+}[]): string;
+export declare function erdGetNotes(host: ErdHost): ToolResult;
+export declare function erdSetNotes(host: ErdHost, target: string | undefined, notes: string): ToolResult;
 export declare function registerErdTools(server: McpServer, host: ErdHost): void;
 export {};

package/dist/erd.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "fs";
 import { dirname, join, resolve } from "path";
-import { addAttribute, addEntity, addRelationship, checkLinks, checkStateOf, emptyErd, ERD_CARDINALITIES, isErdDefinition, isErdfPath, removeAttribute, removeEntity, removeRelationship, renderMermaidEr, updateEntity, summarizeErd, validateErd, } from "@miadi/stateloom-protocol";
+import { addAttribute, addEntity, addRelationship, checkLinks, checkStateOf, collectNotes, emptyErd, ERD_CARDINALITIES, isErdDefinition, isErdfPath, isSqdfPath, isSysdfPath, removeAttribute, removeEntity, removeRelationship, renderMermaidEr, updateEntity, updateErdSettings, summarizeErd, validateErd, } from "@miadi/stateloom-protocol";
 import { stampedOutputPath } from "@miadi/stateloom-cli/render";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
@@ -101,6 +101,22 @@ export function erdRender(host, opts) {
         ],
     };
 }
+/** One block per note, the diagram's own first. What `get_notes` answers with for either document type. */
+export function formatNotes(name, path, entries) {
+    if (entries.length === 0)
+        return `No notes in '${name}' (${path}).`;
+    const blocks = entries.map((n) => `[${n.target ?? "diagram"}]\n${n.notes}`);
+    return `${entries.length} note(s) in '${name}' (${path}):\n\n${blocks.join("\n\n")}`;
+}
+export function erdGetNotes(host) {
+    const def = readErd(host.projectFile());
+    if (!def)
+        return fail(`No ERD at ${host.projectFile()}.`);
+    return ok(formatNotes(def.settings?.name ?? "", host.projectFile(), collectNotes(def)));
+}
+export function erdSetNotes(host, target, notes) {
+    return mutate(host, (def) => (target ? updateEntity(def, target, { notes }) : updateErdSettings(def, { notes })), () => `${notes.trim() ? "Saved" : "Cleared"} the notes on ${target ? `entity '${target}'` : "the diagram"}.`);
+}
 const formatErrors = (errors) => errors.map((e) => `[${e.ruleId}] ${e.message}`).join("\n");
 function readSmdf(path) {
     if (!existsSync(path))
@@ -177,8 +193,11 @@ export function registerErdTools(server, host) {
             ? fail(`${errors.length} problem(s) in '${def.settings?.name ?? ""}':\n${formatErrors(errors)}\n\n${body}`)
             : ok(`ERD '${def.settings?.name ?? ""}' is valid.\n${body}`);
     });
-    server.tool("check_links", "Check the names a state machine uses for its data against an ERD (rules L001–L004): the class of each object a guard reads a field of must be an entity, each <instance>.<field> in a guard must be an attribute of it, and an attribute's stateOf must point at a machine built with that entity. With no arguments: when the active document is an ERD, every .smdf.json beside it is checked; when it is a state machine, pass erd_path.", { erd_path: z.string().optional(), smdf_paths: z.array(z.string()).optional() }, async ({ erd_path, smdf_paths }) => {
+    server.tool("check_links", "Check the names a state machine uses for its data against an ERD (rules L001–L004): the class of each object a guard reads a field of must be an entity, each <instance>.<field> in a guard must be an attribute of it, and an attribute's stateOf must point at a machine built with that entity. With no arguments: when the active document is an ERD, every .smdf.json beside it is checked; when it is a state machine, pass erd_path; when it is a sequence or a system, the whole system is checked (check_system).", { erd_path: z.string().optional(), smdf_paths: z.array(z.string()).optional() }, async ({ erd_path, smdf_paths }) => {
         const active = host.projectFile();
+        if (!erd_path && !smdf_paths?.length && host.checkSystem && (isSqdfPath(active) || isSysdfPath(active))) {
+            return host.checkSystem();
+        }
         const erdPath = erd_path ? resolve(erd_path) : isErdfPath(active) ? active : undefined;
         if (!erdPath) {
             return fail(`The active document ${active} is a state machine — pass erd_path, the .erdf.json to check it against.`);

package/dist/live.d.ts

@@ -0,0 +1,26 @@
+import { type PatchOp, type ViewEnvelope } from "@miadi/stateloom-protocol";
+export interface LiveOutcome {
+    ok: boolean;
+    text: string;
+    /** No bridge is configured: nothing was attempted. */
+    off?: true;
+}
+export interface Live {
+    /** Granular ops to a machine's room. `def` is what the file now holds. */
+    patch(docId: string, ops: PatchOp[], def: unknown, mtime: number): Promise<LiveOutcome>;
+    /** A whole document (ERD, sequence, system) to its room. */
+    full(docId: string, def: unknown, mtime: number): Promise<LiveOutcome>;
+    /** A view to a system's room; needs a connection, not a join. */
+    view(view: Omit<ViewEnvelope, "origin"> & {
+        origin?: string;
+    }): Promise<LiveOutcome>;
+}
+export interface LiveTarget {
+    /** The hub. Undefined: every push reports that the bridge is not configured. */
+    url?: string;
+    token?: string;
+    name?: string;
+    /** How long to wait for the hub at each step. Default 3000 ms. */
+    timeoutMs?: number;
+}
+export declare function liveBridge(target: LiveTarget): Live;

package/dist/live.js

@@ -0,0 +1,131 @@
+/**
+ * One-shot pushes to rooms other than the active document's (Spec 82).
+ *
+ * The server's own bridge client is joined to the active document's room, and
+ * the hub makes a socket that re-joins leave its old room. So when a scenario
+ * upgrades a machine, or an agent asks the system's canvas to show something,
+ * the push goes through a short-lived client of its own: join that room, send,
+ * wait for the hub's answer, disconnect.
+ *
+ * Every push is best-effort and comes AFTER the file is written: an unreachable
+ * hub leaves the file standing, and the outcome says so in words.
+ *
+ * Joining a room the hub has not opened yet seeds it from disk, which already
+ * holds the change; applying the ops on top would add them twice. So a push is
+ * skipped when the room's snapshot already equals what was written.
+ */
+import { createBridgeClient } from "@miadi/stateloom-client";
+import { hashDef, } from "@miadi/stateloom-protocol";
+const message = (e) => (e instanceof Error ? e.message : String(e));
+function withTimeout(p, ms, what) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${what} took longer than ${ms} ms`)), ms);
+        p.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+/** The hub's answer to a patch or a full: an ack with its seq, or an error frame. */
+function answer(client, ms) {
+    return new Promise((resolve) => {
+        const offs = [];
+        const done = (r) => {
+            clearTimeout(timer);
+            for (const off of offs)
+                off();
+            resolve(r);
+        };
+        const timer = setTimeout(() => done({ error: `no answer from the hub in ${ms} ms` }), ms);
+        offs.push(client.on("ack", (a) => done({ seq: a.seq })));
+        offs.push(client.on("error", (e) => done({ error: e.message || e.code })));
+    });
+}
+/** The hub said no: a refused token, or a frame it could not take. */
+class Refused extends Error {
+}
+/**
+ * The first error frame the hub sends this client, as a rejection. A failed
+ * connection is left to `connect()`, which rejects on it by itself.
+ */
+function refusal(client) {
+    let off = () => { };
+    const promise = new Promise((_, reject) => {
+        off = client.on("error", (e) => {
+            if (e.code !== "connect_error")
+                reject(new Refused(e.message || e.code));
+        });
+    });
+    promise.catch(() => { });
+    return { promise, off };
+}
+export function liveBridge(target) {
+    const ms = target.timeoutMs ?? 3000;
+    const unconfigured = {
+        ok: false,
+        off: true,
+        text: "not live: the bridge is not configured (STATELOOM_BRIDGE_URL unset)",
+    };
+    const open = (docId) => createBridgeClient({
+        url: target.url,
+        role: "agent",
+        docId,
+        name: target.name ?? "mcp-agent",
+        token: target.token,
+        autoResync: false,
+    });
+    async function send(docId, def, kind, emit) {
+        if (!target.url)
+            return unconfigured;
+        const client = open(docId);
+        const refused = refusal(client);
+        try {
+            const joined = await withTimeout(Promise.race([client.join(), refused.promise]), ms, "joining the room");
+            const held = joined.snapshot?.def;
+            if (held && hashDef(held) === hashDef(def)) {
+                return { ok: true, text: "the room already holds it" };
+            }
+            const reply = answer(client, ms);
+            emit(client);
+            const r = await reply;
+            return r.error
+                ? { ok: false, text: `the hub refused the ${kind}: ${r.error}` }
+                : { ok: true, text: `${kind} sent live (seq ${r.seq})` };
+        }
+        catch (e) {
+            const why = e instanceof Refused ? `the hub refused the ${kind}: ${e.message}` : message(e);
+            return { ok: false, text: `not live: ${why}; the file stands` };
+        }
+        finally {
+            refused.off();
+            client.disconnect();
+        }
+    }
+    return {
+        patch: (docId, ops, def, mtime) => send(docId, def, "patch", (c) => c.emitPatch(ops, mtime)),
+        full: (docId, def, mtime) => send(docId, def, "document", (c) => c.emitFull(def, mtime)),
+        async view(view) {
+            if (!target.url)
+                return unconfigured;
+            const client = open(view.docId);
+            const refused = refusal(client);
+            try {
+                await withTimeout(Promise.race([client.emitView({ ...view, origin: view.origin ?? target.name ?? "agent" }), refused.promise]), ms, "reaching the hub");
+                // The hub acks no view, but it answers a refused one with an error
+                // frame: wait a moment for that before calling the view delivered.
+                await Promise.race([new Promise((r) => setTimeout(r, Math.min(ms, 250))), refused.promise]);
+                return { ok: true, text: "view sent to the hub" };
+            }
+            catch (e) {
+                return { ok: false, text: e instanceof Refused ? `the hub refused the view: ${e.message}` : `not sent: ${message(e)}` };
+            }
+            finally {
+                refused.off();
+                client.disconnect();
+            }
+        },
+    };
+}

package/dist/projectSwitch.d.ts

@@ -10,8 +10,12 @@ export interface SwitchResult {
 }
 export declare function chronicleRoot(env?: Record<string, string | undefined>): string;
 /**
- * Resolve `miadi-chronicle://<episode>/[diagrams/]<name>[.smdf.json]` to the
- * absolute path `<root>/<episode-dir>/diagrams/<name>.smdf.json`.
+ * Resolve `miadi-chronicle://<episode>/[diagrams/]<name>[.<type>.json]` to the
+ * absolute path `<root>/<episode-dir>/diagrams/<name>.<type>.json`. The loom
+ * weaves four types, told apart by extension: `.smdf.json` (state machine),
+ * `.erdf.json` (ERD), `.sqdf.json` (sequence), `.sysdf.json` (system). An
+ * explicit extension is kept; `.smdf`/`.erdf`/`.sqdf`/`.sysdf` without `.json`
+ * gets it; a bare name is a state machine, `<name>.smdf.json`, as it always was.
  *
  * Episode matching: exact folder name first; else a bare number matches
  * `-episode-NNN-` folders. Episode numbers are NOT unique in the chronicle

package/dist/projectSwitch.js

@@ -1,6 +1,7 @@
 /**
  * Pure logic behind the `set_project_file` MCP tool (path power — the agent
- * chooses which `.smdf.json` document the loom weaves).
+ * chooses which document the loom weaves: a `.smdf.json`, `.erdf.json`,
+ * `.sqdf.json` or `.sysdf.json`).
  *
  * Two modalities, by William's orientation (2026-08-07): STANDALONE — a plain
  * path, no episode, just designing — and RELATIONAL — the document lives
@@ -17,8 +18,12 @@ export function chronicleRoot(env = process.env) {
     return env.MIADI_CHRONICLE_ROOT ?? "/srv/miadi/episodes/miadi-chronicle";
 }
 /**
- * Resolve `miadi-chronicle://<episode>/[diagrams/]<name>[.smdf.json]` to the
- * absolute path `<root>/<episode-dir>/diagrams/<name>.smdf.json`.
+ * Resolve `miadi-chronicle://<episode>/[diagrams/]<name>[.<type>.json]` to the
+ * absolute path `<root>/<episode-dir>/diagrams/<name>.<type>.json`. The loom
+ * weaves four types, told apart by extension: `.smdf.json` (state machine),
+ * `.erdf.json` (ERD), `.sqdf.json` (sequence), `.sysdf.json` (system). An
+ * explicit extension is kept; `.smdf`/`.erdf`/`.sqdf`/`.sysdf` without `.json`
+ * gets it; a bare name is a state machine, `<name>.smdf.json`, as it always was.
  *
  * Episode matching: exact folder name first; else a bare number matches
  * `-episode-NNN-` folders. Episode numbers are NOT unique in the chronicle
@@ -64,13 +69,20 @@ export function resolveChronicleUri(uri, env = process.env) {
     if (matches.length > 1) {
         throw new Error(`episode '${episodeRef}' is ambiguous — candidates:\n  ${matches.sort().join("\n  ")}\nName the full folder.`);
     }
-    const file = name.endsWith(".json") ? name : `${name}.smdf.json`;
-    return join(root, matches[0], "diagrams", file);
+    return join(root, matches[0], "diagrams", loomFileName(name));
+}
+/** `<name>` → `<name>.smdf.json`; a loom type without `.json` gets it; any `.json` is kept. */
+function loomFileName(name) {
+    if (name.toLowerCase().endsWith(".json"))
+        return name;
+    if (/\.(smdf|erdf|sqdf|sysdf)$/i.test(name))
+        return `${name}.json`;
+    return `${name}.smdf.json`;
 }
 export function resolveProjectSwitch(next, previous) {
     const path = CHRONICLE_SCHEME.test(next) ? resolveChronicleUri(next) : resolve(next);
     if (!path.endsWith(".json")) {
-        throw new Error(`project file must be a .json document (got '${path}') — the loom weaves .smdf.json files`);
+        throw new Error(`project file must be a .json document (got '${path}') — the loom weaves .smdf.json (state machine), .erdf.json (ERD), .sqdf.json (sequence) and .sysdf.json (system) files`);
     }
     return {
         path,

package/dist/sequence.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The sequence half of the MCP server (Spec 81).
+ *
+ * A sequence (`.sqdf.json`) is a usage scenario: who sends what to whom, in
+ * order. The tools here act on the active document when it is an SQDF;
+ * `create_sequence` is the one that also moves the active document.
+ *
+ * People and tools count from 1: a main message is addressed by its number
+ * (`"9"`), a fragment's message as `f<fragment>.<n>` (`"f1.2"`), a fragment by
+ * its number. The protocol's edits count from 0; the conversion happens here.
+ *
+ * A sequence travels to the live canvas as a whole document (`emitFull`), as an
+ * ERD does. After each edit that changes the scenario, `afterEdit` gives the
+ * system a chance to reconcile (Spec 82 reconcile mode), and its one line is
+ * appended to the tool result.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type SequenceDefinition } from "@miadi/stateloom-protocol";
+export interface SequenceHost {
+    /** The active document's absolute path. */
+    projectFile(): string;
+    /** Re-point the active document under set_project_file's guards. Returns the refusal, if any. */
+    switchTo(path: string): string | undefined;
+    /** Mirror the whole document to the live bridge room. Best-effort. */
+    emitFull(def: SequenceDefinition): void;
+    /** The refusal for a path outside the permitted document root, if any. */
+    outsideRoot(path: string): string | undefined;
+    /** After an edit that changed the scenario was written: one line to append (reconcile mode), or nothing. */
+    afterEdit?(path: string): Promise<string | undefined>;
+}
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+};
+export declare function readSequence(path: string): SequenceDefinition | null;
+/** One line for set_project_file / get_project_file when the active document is an SQDF. */
+export declare function sequenceSummary(path: string): string;
+export declare function sequenceGetDefinition(host: SequenceHost): ToolResult;
+export declare function sequenceLoadDefinition(host: SequenceHost, json: string): Promise<ToolResult>;
+export declare function sequenceRender(host: SequenceHost, opts: {
+    format?: string;
+    path?: string;
+    stamp?: boolean;
+}): ToolResult;
+export declare function sequenceGetNotes(host: SequenceHost): ToolResult;
+/**
+ * `target` is a participant's name, a message address (`9`, `f1.2`, or `message 9`
+ * as get_notes prints it), or `fragment N`. Omitted: the whole sequence.
+ */
+export declare function sequenceSetNotes(host: SequenceHost, target: string | undefined, notes: string): Promise<ToolResult>;
+export declare function registerSequenceTools(server: McpServer, host: SequenceHost): void;
+export {};