loopgraph 0.1.0

package/dist/views/validate-mermaid.js

@@ -0,0 +1,110 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const INSTALL_HINT = '@mermaid-js/mermaid-cli is not installed — run "pnpm add -D @mermaid-js/mermaid-cli puppeteer" to enable mermaid diagram validation';
+/**
+ * Walks up from `fromFile` looking for the package.json whose `name`
+ * matches `packageName`. Needed because @mermaid-js/mermaid-cli's own
+ * `exports` map doesn't expose `./package.json` as a resolvable
+ * subpath (only `.` is), so `require.resolve("<pkg>/package.json")`
+ * throws even when the package is installed — this walks up from a
+ * subpath resolution that IS allowed (the package's main entry) instead
+ * of relying on an exports-restricted path.
+ */
+function findPackageRoot(fromFile, packageName) {
+    let dir = dirname(fromFile);
+    while (true) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (pkg.name === packageName)
+                    return dir;
+            }
+            catch {
+                // malformed package.json at this level — keep climbing, it's not necessarily the package root
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Resolves the installed `mmdc` script's absolute path via node module
+ * resolution (not `npx`/`PATH` lookup) — deterministic regardless of the
+ * caller's cwd or shell PATH, and never reaches the network: if the
+ * package isn't resolvable, this returns undefined rather than falling
+ * back to fetching it.
+ */
+function resolveMmdcBin() {
+    try {
+        const require = createRequire(import.meta.url);
+        const entryPath = require.resolve("@mermaid-js/mermaid-cli"); // the "." export — always resolvable if installed
+        const pkgRoot = findPackageRoot(entryPath, "@mermaid-js/mermaid-cli");
+        if (!pkgRoot)
+            return undefined;
+        const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"));
+        const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.mmdc;
+        return binRel ? join(pkgRoot, binRel) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractErrorMessage(err) {
+    const withStderr = err;
+    const text = withStderr.stderr && withStderr.stderr.trim().length > 0
+        ? withStderr.stderr
+        : withStderr.message;
+    return (text ?? String(err)).trim();
+}
+/**
+ * Renders `mermaidText` with mermaid-cli (`mmdc`) to a throwaway SVG and
+ * reports whether it actually rendered — the "写出即验证" enforcement
+ * from Decision record 004 技术点 5. A generated diagram nobody opens
+ * until much later isn't validated, it's just written; this is the
+ * module that makes "validated" mean something.
+ *
+ * Deliberately NOT on loopgraph's default `view` CLI path (see
+ * src/cli/commands/view.ts): mmdc needs a real puppeteer-launched
+ * browser (~300MB Chromium download on first install), which the
+ * project's own lightness principle (proposal 001 §6: views generation
+ * isn't in the CI gating path) says shouldn't be a hard runtime
+ * requirement for every consumer that installs loopgraph. It's a
+ * devDependency here so loopgraph's OWN test suite can prove the
+ * generator produces valid mermaid (test/validate-mermaid.test.ts,
+ * test/view-cli.test.ts), and available to end users only when they
+ * opt in with `loopgraph view --validate` AND have separately installed
+ * `@mermaid-js/mermaid-cli` themselves.
+ */
+export async function validateMermaid(mermaidText, options = {}) {
+    const bin = options.mmdcBinPath ?? resolveMmdcBin();
+    if (!bin || !existsSync(bin))
+        return { status: "unavailable", reason: INSTALL_HINT };
+    const dir = await mkdtemp(join(tmpdir(), "loopgraph-mmdc-"));
+    try {
+        const inputPath = join(dir, "diagram.mmd");
+        const outputPath = join(dir, "diagram.svg");
+        await writeFile(inputPath, mermaidText, "utf8");
+        try {
+            await execFileAsync(process.execPath, [bin, "-i", inputPath, "-o", outputPath], {
+                timeout: 60_000,
+            });
+            return { status: "valid" };
+        }
+        catch (err) {
+            return { status: "invalid", error: extractErrorMessage(err) };
+        }
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=validate-mermaid.js.map

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "loopgraph",
+  "version": "0.1.0",
+  "description": "Model-driven engineering control system: behavioral model as spec source of truth, code/tests/observability as projections and evidence.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "loopgraph": "dist/cli/index.js"
+  },
+  "//files": "Ship the dist engine only; seeds/examples/research/docs are excluded so the published package carries no target-repo internals.",
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "packageManager": "pnpm@10.17.1",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write ."
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "typescript": "5.9.3",
+    "yaml": "^2.6.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@mermaid-js/mermaid-cli": "^11.16.0",
+    "@types/node": "^22.10.5",
+    "puppeteer": "^25.3.0",
+    "tsx": "^4.19.2",
+    "vitest": "^2.1.8"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "puppeteer"
+    ]
+  }
+}