@miadi/stateloom-mcp 0.3.2 → 0.3.4

package/dist/atomicWrite.d.ts

@@ -1 +1,13 @@
+/**
+ * Create the folder a document is about to be written into, one level only.
+ *
+ * Earned 2026-10-01 (Episode 550, L1): `miadi-chronicle://550/screenwalk`
+ * resolves to `<episode>/diagrams/screenwalk.smdf.json`, and naming a missing
+ * file is how an episode's first diagram is created — but a fresh episode has
+ * no `diagrams/` yet, so the first write failed with ENOENT. The folder is
+ * created only when ITS parent exists (an episode's `diagrams/` room, a new
+ * folder beside existing work); a path whose ancestors are missing is a typo,
+ * and it still fails loudly instead of growing a tree.
+ */
+export declare function ensureParentFolder(path: string): void;
 export declare function writeFileAtomic(path: string, text: string): void;

package/dist/atomicWrite.js

@@ -6,9 +6,29 @@
  * 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 { accessSync, chmodSync, constants, existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from "fs";
 import { basename, dirname, join } from "path";
+/**
+ * Create the folder a document is about to be written into, one level only.
+ *
+ * Earned 2026-10-01 (Episode 550, L1): `miadi-chronicle://550/screenwalk`
+ * resolves to `<episode>/diagrams/screenwalk.smdf.json`, and naming a missing
+ * file is how an episode's first diagram is created — but a fresh episode has
+ * no `diagrams/` yet, so the first write failed with ENOENT. The folder is
+ * created only when ITS parent exists (an episode's `diagrams/` room, a new
+ * folder beside existing work); a path whose ancestors are missing is a typo,
+ * and it still fails loudly instead of growing a tree.
+ */
+export function ensureParentFolder(path) {
+    const dir = dirname(path);
+    if (existsSync(dir))
+        return;
+    if (!existsSync(dirname(dir)))
+        return;
+    mkdirSync(dir);
+}
 export function writeFileAtomic(path, text) {
+    ensureParentFolder(path);
     let mode;
     if (existsSync(path)) {
         accessSync(path, constants.W_OK);

package/dist/erd.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, readdirSync, writeFileSync } from "fs";
 import { dirname, join, resolve } from "path";
 import { addAttribute, addEntity, addRelationship, checkLinks, checkStateOf, collectNotes, emptyErd, ERD_CARDINALITIES, isErdDefinition, isErdfPath, isSqdfPath, isSysdfPath, removeAttribute, removeEntity, removeRelationship, renderMermaidEr, updateEntity, updateErdSettings, summarizeErd, validateErd, normalizeNotes } from "@miadi/stateloom-protocol";
 import { stampedOutputPath } from "@miadi/stateloom-cli/render";
+import { writeFileAtomic } from "./atomicWrite.js";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
 export function readErd(path) {
@@ -17,7 +18,7 @@ export function readErd(path) {
     }
 }
 function writeErd(path, def) {
-    writeFileSync(path, JSON.stringify(def, null, 2) + "\n", "utf8");
+    writeFileAtomic(path, JSON.stringify(def, null, 2) + "\n");
 }
 /** One line for set_project_file / get_project_file when the active document is an ERDF. */
 export function erdSummary(path) {

package/dist/server.js

@@ -72,6 +72,7 @@ import { registerErdTools, erdSummary, erdGetDefinition, erdLoadDefinition, erdR
 import { registerSequenceTools, sequenceSummary, sequenceGetDefinition, sequenceLoadDefinition, sequenceRender, sequenceGetNotes, sequenceSetNotes, } from "./sequence.js";
 import { registerSystemTools, checkSystemReport, reconcileAfterEdit, reconcileModeLine, systemSummary, systemGetDefinition, systemLoadDefinition, systemRender, systemGetNotes, systemSetNotes, systemRispec, } from "./system.js";
 import { liveBridge } from "./live.js";
+import { writeFileAtomic } from "./atomicWrite.js";
 // STATELOOM_* read first, SMCRAFT_* legacy twin honored — the live MCP
 // registration bakes SMCRAFT_PROJECT_FILE and must keep working (2026-07-27
 // rename brief). Resolved once at boot, like the direct reads they replace.
@@ -130,7 +131,7 @@ function writeDef(def) {
     catch {
         // A new or unreadable file is written in the loom's own shape.
     }
-    writeFileSync(PROJECT_FILE, JSON.stringify(bare ? def : { stateMachine: def }, null, 2) + (bare ? "\n" : ""), "utf8");
+    writeFileAtomic(PROJECT_FILE, JSON.stringify(bare ? def : { stateMachine: def }, null, 2) + (bare ? "\n" : ""));
 }
 // ─── Optional real-time design bridge (env-gated, best-effort) ───────
 // When STATELOOM_BRIDGE_URL (or legacy SMCRAFT_BRIDGE_URL) is set, each
@@ -784,6 +785,78 @@ function buildServer() {
             content: [{ type: "text", text: `Added state '${name}' under '${parentName}' (${kind ?? "normal"}).` }],
         };
     });
+    server.tool("add_object", "Declare an object the machine is constructed with: `instance` is the name guards use (`walk` in `walk.state`), `class` is its type — an ERD entity when it is data. Fixes L001/L003 without rewriting the machine. Refused when the instance already exists.", { instance: z.string(), class: z.string() }, async ({ instance, class: className }) => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
+        if (!instance.trim() || !className.trim())
+            return { content: [{ type: "text", text: "An object needs an instance and a class." }], isError: true };
+        const objects = [...(def.settings.objects ?? [])];
+        if (objects.some((o) => o.instance === instance)) {
+            return { content: [{ type: "text", text: `The machine already has an object '${instance}'.` }], isError: true };
+        }
+        objects.push({ instance, class: className });
+        def.settings.objects = objects;
+        writeDef(def);
+        bridgeEmitPatch([{ op: "settings.update", patch: { objects } }]);
+        return { content: [{ type: "text", text: `Object '${instance}' : ${className} declared on '${def.settings.name}'.` }] };
+    });
+    server.tool("update_state", "Change what a state says about itself without rewriting the machine: its description, its kind (normal, final, history) or its prompt. Omitted fields stay as they are; an empty description or prompt clears it. Use it after a scenario built states in auto mode, to say what each one is.", {
+        name: z.string(),
+        description: z.string().optional(),
+        kind: z.enum(["normal", "final", "history"]).optional(),
+        prompt: z.string().optional(),
+    }, async ({ name, description, kind, prompt }) => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
+        const target = findState(def.state, name);
+        if (!target)
+            return { content: [{ type: "text", text: `State '${name}' not found.` }], isError: true };
+        const patch = {};
+        const said = [];
+        if (description !== undefined) {
+            if (description.trim())
+                target.description = description;
+            else
+                delete target.description;
+            patch.description = description;
+            said.push(description.trim() ? "description" : "description cleared");
+        }
+        if (kind !== undefined) {
+            target.kind = kind;
+            patch.kind = kind;
+            said.push(`kind ${kind}`);
+        }
+        if (prompt !== undefined) {
+            if (prompt.trim())
+                target.prompt = prompt;
+            else
+                delete target.prompt;
+            patch.prompt = prompt.trim() ? prompt : "";
+            said.push(prompt.trim() ? "prompt" : "prompt cleared");
+        }
+        if (!said.length)
+            return { content: [{ type: "text", text: `Nothing to change on '${name}': give a description, a kind or a prompt.` }], isError: true };
+        writeDef(def);
+        bridgeEmitPatch([{ op: "state.update", name, patch }]);
+        return { content: [{ type: "text", text: `Updated '${name}': ${said.join(", ")}.` }] };
+    });
+    server.tool("update_event", "Change an event's description without rewriting the machine. An empty description clears it.", { id: z.string(), description: z.string() }, async ({ id, description }) => {
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
+        const event = (def.events ?? []).flatMap((s) => s.events ?? []).find((e) => e.id === id);
+        if (!event)
+            return { content: [{ type: "text", text: `Event '${id}' not found.` }], isError: true };
+        if (description.trim())
+            event.description = description;
+        else
+            delete event.description;
+        writeDef(def);
+        bridgeEmitPatch([{ op: "event.update", id, patch: { description } }]);
+        return { content: [{ type: "text", text: description.trim() ? `Described event '${id}'.` : `Cleared the description of '${id}'.` }] };
+    });
     server.tool("set_prompt", "Say what an agent is asked to resolve while the machine is in a state: the instruction it receives when the state is entered — an opening message, the frame of every later turn. `description` says what the state is and notes are the conversation about it; the prompt is what to do in it. The text replaces what was there; an empty string clears it. Engines and code generation ignore it; get_definition and generate_rispec show it.", { state: z.string(), prompt: z.string() }, async ({ state, prompt }) => {
         const def = readDef();
         if (!def)
@@ -1025,7 +1098,11 @@ function buildServer() {
             : "bridge not configured (STATELOOM_BRIDGE_URL unset)";
         return {
             content: [
-                { type: "text", text: `Active document: ${PROJECT_FILE}\n${summary}\n${bridgeNote}\nCanvas: ${canvasLink(PROJECT_FILE)}` },
+                {
+                    type: "text",
+                    // The version is said so an agent can tell when its pin is behind (Episode 550, L4).
+                    text: `Active document: ${PROJECT_FILE}\n${summary}\n${bridgeNote}\nCanvas: ${canvasLink(PROJECT_FILE)}\nLoom: @miadi/stateloom-mcp ${PACKAGE_VERSION} (\`npm view @miadi/stateloom-mcp version\` names the latest)`,
+                },
             ],
         };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/stateloom-mcp",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "MCP server for miadi-stateloom (formerly smcraft-mcp) — lets LLM agents design state machines through conversation",
   "repository": {
     "type": "git",
@@ -38,9 +38,9 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@miadi/stateloom-cli": "^0.1.3",
+    "@miadi/stateloom-cli": "^0.1.4",
     "@miadi/stateloom-client": "^0.1.3",
-    "@miadi/stateloom-protocol": "^0.1.11",
+    "@miadi/stateloom-protocol": "^0.1.13",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^4.3.6"
   },