magenta-canon 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/magenta-canon-banner.png" alt="Magenta Canon — Verifiable MCP Gateway" width="820">
+  <img src="https://raw.githubusercontent.com/royal-ohio/magenta-canon/main/docs/magenta-canon-banner.png" alt="Magenta Canon — Verifiable MCP Gateway" width="820">
 </p>
 
 # Magenta Canon
@@ -10,6 +10,22 @@ MCP host (Claude Code, Claude Desktop, Cursor, …) and downstream MCP tools, an
 > **allows authorized calls · blocks unauthorized calls · records both · and
 > produces cryptographic evidence anyone can verify.**
 
+## Try it now (nothing to clone)
+
+> **Installing from npm?** The verified cross-platform release is published under
+> the **`next`** dist-tag — **not `latest` yet**. A plain `npm i magenta-canon`
+> fetches the older `latest` (`0.1.0`); lead with `@next` to get the current
+> reference implementation (`0.1.3`, verified on macOS/Linux/Windows).
+
+```bash
+npx magenta-canon@next demo                  # full local proof loop: allow · block · witness · verify · tamper
+npx magenta-canon@next verify --self-test    # verifier self-check: one VERIFIED pass and one tamper FAIL
+npx magenta-canon@next gateway <config.json> # the stdio MCP capability gateway
+```
+
+`@next` is a proven **reference implementation**, not production-hosted infra
+yet. See [what ships vs. what doesn't](#from-the-repo-vs-as-a-cli) below.
+
 ## In 60 seconds
 
 AI agents are starting to take real actions through tools (refunds, deploys,
@@ -31,6 +47,17 @@ and get `VERIFIED` — *without trusting the server that produced it.* Tamper wi
 the record and verification fails. That's the whole point: not "trust our log,"
 but "verify the receipt yourself."
 
+## See it run (30-second demo)
+
+<!-- Pre-wired embed: commit the recording at docs/assets/magenta-canon-demo.gif
+     and it renders here automatically. Capture recipe: docs/DEMO_RECORDING.md. -->
+![Terminal demo showing Magenta Canon allowing one AI-agent tool call, blocking another, verifying the evidence bundle, and detecting tampering.](docs/assets/magenta-canon-demo.gif)
+
+> **Demo asset placeholder — recording in progress.** Until
+> `docs/assets/magenta-canon-demo.gif` is committed, the image above will not
+> render. Caption once live: *One command. One allowed call. One blocked call.
+> Independent verification. Tamper detection.*
+
 ## The proof (we don't rely on claims)
 
 Two recorded, reproducible, live end-to-end runs live in the repo:
@@ -110,9 +137,8 @@ Full walkthrough: [`docs/MCP_GATEWAY.md`](docs/MCP_GATEWAY.md).
 
 - **From a repo checkout** (above): `npm install` then `npm run demo`.
 - **As a package/CLI** — the same three capabilities without cloning internals.
-  The first npm release is **`0.1.0`** under the **`next`** dist-tag (a proven
-  reference implementation, not production-hosted infra yet), so install from
-  `@next`:
+  Published on npm under the **`next`** dist-tag (a proven reference
+  implementation, not production-hosted infra yet), so install from `@next`:
 
   ```bash
   npx magenta-canon@next demo                 # the full local proof loop
@@ -121,10 +147,11 @@ Full walkthrough: [`docs/MCP_GATEWAY.md`](docs/MCP_GATEWAY.md).
   ```
 
   `verify` exits `0` on `VERIFIED`, `1` on `VERIFICATION FAILED`. The packaged
-  `demo` boots a **headless** control plane (no frontend needed). What ships,
-  what doesn't, and how to test the package locally:
-  [`docs/NPM_PACKAGING.md`](docs/NPM_PACKAGING.md). *(Packaging readiness — not yet
-  published to npm.)*
+  `demo` boots a **headless** control plane (no frontend needed) and is verified
+  end-to-end on macOS, Linux, and Windows. What ships, what doesn't, and how to
+  test the package locally:
+  [`docs/NPM_PACKAGING.md`](docs/NPM_PACKAGING.md). *(Published under `next`; not
+  on `latest` yet.)*
 
 ## Connect your MCP host
 

package/docs/NPM_PACKAGING.md

@@ -3,25 +3,39 @@
 How Magenta Canon is packaged as an installable CLI, what ships in the tarball,
 what deliberately does not, and how to verify the package locally.
 
-> **Status: packaging readiness — NOT published.** Nothing here publishes to npm.
-> The package has not been pushed to the registry. Publishing is a separate,
-> explicitly-authorized step.
+> **Status: published under the `next` dist-tag.** The current release is
+> **`magenta-canon@0.1.3`** on npm (`npm i magenta-canon@next`). It is **not** on
+> `latest` yet — see "Release posture" below. Publishing remains an explicitly-
+> authorized step done on an authenticated machine.
 
-## Intended first release
+## Release posture
 
-The first npm release is planned as **`magenta-canon@0.1.0`** published under the
-**`next`** dist-tag (not `latest`). This is deliberate: Magenta Canon is a
-**proven reference implementation**, not production-hosted infrastructure yet, so
-`0.1.0` + `next` signals early-OSS posture and lets adopters opt in explicitly
-(`npm i magenta-canon@next`). It can be promoted to `latest` (and a higher
-version) once production durability and an externally-mirrored witness land. The
-intended command — run only after explicit authorization on an authenticated
-machine — is:
+Magenta Canon ships under the **`next`** dist-tag (not `latest`). This is
+deliberate: it is a **proven reference implementation**, not production-hosted
+infrastructure yet, so `next` signals early-OSS posture and lets adopters opt in
+explicitly (`npm i magenta-canon@next`). It can be promoted to `latest` (and a
+higher version) once production durability and an externally-mirrored witness
+land. The publish command (run only after explicit authorization on an
+authenticated machine) is:
 
 ```bash
 npm publish --tag next --access public
 ```
 
+### Release history (`next`)
+
+| Version | What it delivered |
+|---|---|
+| `0.1.0` | first publish; `verify`/`gateway` work from a real install |
+| `0.1.1` | Windows control-plane bind fix (`127.0.0.1`, no `reusePort`) |
+| `0.1.2` | ship the canon spine assets; Windows-safe demo-driver process cleanup |
+| `0.1.3` | Windows-safe step-3 gateway path (`fileURLToPath`); driver stderr diagnostics |
+
+**Verified on Windows (0.1.3):** `npx magenta-canon@next demo` completes the full
+seven-step proof — control plane healthy, trust root, gateway allow/block,
+downstream absence, evidence `VERIFIED`, tamper `VERIFICATION FAILED` — alongside
+`--version`, `verify --self-test`, and `gateway`.
+
 ## The CLI
 
 The package exposes a single bin, `magenta-canon`, with three commands. Until the
@@ -67,7 +81,7 @@ verifier behavior.
 ## What ships in the tarball
 
 Controlled by the `files` allowlist in `package.json`. Current contents
-(`magenta-canon-0.1.2.tgz` — 77 files, ~215 KB packed, ~870 KB unpacked):
+(`magenta-canon-0.1.3.tgz` — 79 files, ~215 KB packed, ~870 KB unpacked):
 
 | Path | Why |
 |---|---|
@@ -115,7 +129,7 @@ Smoke-test the packed artifact in a throwaway project:
 
 ```bash
 mkdir /tmp/mc-try && cd /tmp/mc-try && npm init -y
-npm install /path/to/magenta-canon-0.1.1.tgz   # installs deps incl. tsx
+npm install /path/to/magenta-canon-0.1.3.tgz   # installs deps incl. tsx
 npx magenta-canon --version
 npx magenta-canon verify --self-test            # VERIFIED + VERIFICATION FAILED
 npx magenta-canon demo                          # full headless proof loop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magenta-canon",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "license": "Apache-2.0",
   "description": "A verifiable MCP accountability gateway for AI-agent tool calls: allows authorized calls, blocks unauthorized calls, records both, and produces cryptographic evidence anyone can verify.",

package/scripts/demo.mjs

@@ -127,17 +127,23 @@ const capture = (cmd, args, opts = {}) =>
 const isWindows = process.platform === "win32";
 const runDriver = (configPath, env) =>
   new Promise((resolve) => {
-    const ch = spawn("node", ["scripts/mcp-demo-drive.mjs", configPath], {
+    // Resolve the driver as an absolute, spawn-safe native path (cwd-independent
+    // and correct under the npm-cache _npx path on Windows).
+    const driverPath = path.join(ROOT, "scripts", "mcp-demo-drive.mjs");
+    const ch = spawn(process.execPath, [driverPath, configPath], {
       // `detached` only buys us a process group on POSIX; skip it on Windows.
-      cwd: ROOT, detached: !isWindows, stdio: ["ignore", "pipe", "ignore"], env,
+      // Capture stderr too, so a child failure surfaces a real cause instead of
+      // an opaque "MCP driver failed".
+      cwd: ROOT, detached: !isWindows, stdio: ["ignore", "pipe", "pipe"], env,
     });
-    let out = "";
+    let out = "", err = "";
     ch.stdout.on("data", (d) => (out += d));
+    ch.stderr.on("data", (d) => (err += d));
     const cleanup = () => killChildTree(ch);
-    const watchdog = setTimeout(() => { cleanup(); resolve({ code: 124, out }); }, 30_000);
+    const watchdog = setTimeout(() => { cleanup(); resolve({ code: 124, out, err }); }, 30_000);
     ch.on("exit", (code) => {
       clearTimeout(watchdog);
-      setTimeout(() => { cleanup(); resolve({ code: code ?? 0, out }); }, 150);
+      setTimeout(() => { cleanup(); resolve({ code: code ?? 0, out, err }); }, 150);
     });
   });
 
@@ -199,6 +205,15 @@ async function main() {
   // ephemeral control plane. Semantics (capabilities, tool map) are unchanged.
   const base = JSON.parse(readFileSync(path.join(ROOT, "examples/magenta-gateway.demo.config.json"), "utf8"));
   base.controlPlane = { url: URL, internalKey: INTERNAL_KEY };
+  // Make the downstream command absolute and launch it with the current Node
+  // (process.execPath) rather than a bare "node" + relative arg — cwd-independent
+  // and correct under the npm-cache _npx path, including on Windows.
+  if (base.downstream && Array.isArray(base.downstream.args)) {
+    base.downstream.command = process.execPath;
+    base.downstream.args = base.downstream.args.map((a) =>
+      a.endsWith(".mjs") || a.endsWith(".js") ? path.join(ROOT, a) : a,
+    );
+  }
   writeFileSync(F.config, JSON.stringify(base, null, 2));
 
   const drive = await runDriver(F.config, {
@@ -208,8 +223,8 @@ async function main() {
     MAGENTA_TSX_CLI: TSX_CLI,
     PATH: `${path.join(ROOT, "node_modules", ".bin")}${path.delimiter}${process.env.PATH}`,
   });
-  if (drive.code !== 0) die("MCP driver failed.", drive.out);
-  if (!/HANDSHAKE_OK/.test(drive.out)) die("MCP handshake did not complete.", drive.out);
+  if (drive.code !== 0) die("MCP driver failed.", [drive.out, drive.err].filter(Boolean).join("\n"));
+  if (!/HANDSHAKE_OK/.test(drive.out)) die("MCP handshake did not complete.", [drive.out, drive.err].filter(Boolean).join("\n"));
   for (const line of drive.out.trim().split("\n")) {
     if (!line.trim()) continue;
     const colored = line.startsWith("ALLOWED") ? grn(line)

package/scripts/mcp-demo-drive.mjs

@@ -8,6 +8,7 @@
  */
 import { spawn } from "node:child_process";
 import readline from "node:readline";
+import { siblingPath } from "./win-paths.mjs";
 
 const cfg = process.argv[2];
 if (!cfg) { console.error("usage: node scripts/mcp-demo-drive.mjs <config>"); process.exit(2); }
@@ -15,7 +16,9 @@ if (!cfg) { console.error("usage: node scripts/mcp-demo-drive.mjs <config>"); pr
 // Launch the gateway. When MAGENTA_TSX_CLI is provided (by the demo orchestrator,
 // incl. the installed-package CLI) run it as `node <tsxCli> mcp-gateway.ts`;
 // otherwise fall back to `npx tsx` for the documented manual flow.
-const gatewayPath = new URL("./mcp-gateway.ts", import.meta.url).pathname;
+// NOTE: use fileURLToPath (via siblingPath), NOT URL.pathname — the latter yields
+// `/C:/…` on Windows, which tsx/node cannot open (broke step 3/7 on Windows).
+const gatewayPath = siblingPath(import.meta.url, "./mcp-gateway.ts");
 const gw = process.env.MAGENTA_TSX_CLI
   ? spawn(process.execPath, [process.env.MAGENTA_TSX_CLI, gatewayPath, cfg], { stdio: ["pipe", "pipe", "inherit"] })
   : spawn("npx", ["tsx", gatewayPath, cfg], { stdio: ["pipe", "pipe", "inherit"] });

package/scripts/win-paths.mjs

@@ -0,0 +1,19 @@
+/**
+ * Windows-safe path helpers for the demo's child-process wiring.
+ *
+ * The MCP demo driver spawns the gateway script by resolving a sibling file from
+ * `import.meta.url`. The naive `new URL("./x.ts", import.meta.url).pathname`
+ * returns a POSIX-style string with a spurious leading slash before the drive
+ * letter on Windows (e.g. `/C:/Users/.../x.ts`), which Node/tsx cannot open —
+ * this broke `npx magenta-canon demo` at step 3/7 on Windows. `fileURLToPath`
+ * produces the correct native path on every platform (`C:\Users\...\x.ts` on
+ * Windows, `/home/.../x.ts` on POSIX).
+ *
+ * Pure; no process/verifier/witness/evidence/gateway semantics.
+ */
+import { fileURLToPath } from "node:url";
+
+/** Resolve a sibling file next to `metaUrl` as a spawn-safe, native absolute path. */
+export function siblingPath(metaUrl, name) {
+  return fileURLToPath(new URL(name, metaUrl));
+}