@rubytech/create-maxy-code 0.1.125 → 0.1.126

package/payload/platform/plugins/graph-viewer/mcp/dist/tools/graph-render.js

@@ -0,0 +1,170 @@
+/**
+ * graph-render — produce an inline PNG of an account-scoped Neo4j
+ * subgraph rooted at a given nodeId, walking up to `hopDepth` hops.
+ *
+ * Surface contract:
+ *   - The root node must exist and belong to the caller's account.
+ *     A missing or foreign-account root returns a structured refusal,
+ *     never throws.
+ *   - The expansion is bounded by both `hopDepth` (max 3 to keep the
+ *     image legible) and a hard 200-node cap. Subgraphs that exceed
+ *     the cap render the first 200 nodes and carry a `truncated`
+ *     envelope so the agent can tell the operator.
+ *   - `:Trashed` nodes are excluded everywhere — matches memory-search.
+ *   - One observability line per invocation, prefixed `[graph-render]`.
+ *
+ * The Cypher hopDepth is INLINED into the query string after a strict
+ * validate (`Number.isInteger && 0 <= n <= 3`) because Neo4j does not
+ * parameterise variable-length path bounds. Anything outside that range
+ * fails fast at the param-validation layer, well before string assembly.
+ */
+import { getSession } from "../lib/neo4j.js";
+import { layoutGraph } from "../render/layout.js";
+import { drawGraph } from "../render/draw.js";
+const NODE_CAP = 200;
+const MAX_HOP_DEPTH = 3;
+const IMAGE_WIDTH = 1200;
+const IMAGE_HEIGHT = 900;
+function logLine(line) {
+    process.stderr.write(`${line}\n`);
+}
+export async function graphRender(params) {
+    const { accountId, nodeId } = params;
+    const hopDepth = params.hopDepth;
+    if (!Number.isInteger(hopDepth) || hopDepth < 0 || hopDepth > MAX_HOP_DEPTH) {
+        return {
+            ok: false,
+            reason: "invalid-input",
+            message: `hopDepth must be an integer between 0 and ${MAX_HOP_DEPTH} (got ${String(hopDepth)})`,
+        };
+    }
+    const t0 = Date.now();
+    const session = getSession();
+    try {
+        // Step 1 — confirm root exists and belongs to this account. The
+        // explicit two-step check (rather than relying on the expand to
+        // return zero rows) is what lets us return reason="scope" vs
+        // reason="empty" with a meaningful message.
+        const rootCheck = await session.run(`MATCH (root)
+       WHERE elementId(root) = $nodeId
+       RETURN root.accountId AS rootAccountId, labels(root) AS rootLabels`, { nodeId });
+        if (rootCheck.records.length === 0) {
+            logLine(`[graph-render] reject account=${accountId} reason=scope nodeId=${nodeId} cause=not-found`);
+            return {
+                ok: false,
+                reason: "scope",
+                message: `No node with id ${nodeId} is visible to this account.`,
+            };
+        }
+        const rootAccountId = rootCheck.records[0].get("rootAccountId");
+        if (rootAccountId !== accountId) {
+            logLine(`[graph-render] reject account=${accountId} reason=scope nodeId=${nodeId} cause=foreign-account`);
+            return {
+                ok: false,
+                reason: "scope",
+                message: `Node ${nodeId} is not visible to this account.`,
+            };
+        }
+        logLine(`[graph-render] start account=${accountId} nodeId=${nodeId} hopDepth=${hopDepth}`);
+        // Step 2 — expand. Variable-length path bound is inlined after the
+        // hopDepth validation above. Account filter + trash filter applied to
+        // every node on every path. RELATIONSHIPS only between matched nodes.
+        const expandQuery = `
+      MATCH (root) WHERE elementId(root) = $nodeId
+      MATCH path = (root)-[*0..${hopDepth}]-(n)
+      WHERE n.accountId = $accountId AND NOT n:Trashed
+      WITH collect(DISTINCT n) AS nodes
+      WITH nodes[0..$cap] AS capped, size(nodes) AS totalCount
+      UNWIND capped AS node
+      WITH collect({ id: elementId(node), labels: labels(node), properties: properties(node) }) AS nodeRows,
+           [n IN capped | elementId(n)] AS capIds, totalCount
+      OPTIONAL MATCH (a)-[r]->(b)
+      WHERE elementId(a) IN capIds AND elementId(b) IN capIds
+      RETURN nodeRows,
+             collect(DISTINCT { from: elementId(startNode(r)), to: elementId(endNode(r)), type: type(r) }) AS edgeRows,
+             totalCount
+    `;
+        const result = await session.run(expandQuery, {
+            nodeId,
+            accountId,
+            cap: NODE_CAP,
+        });
+        if (result.records.length === 0) {
+            logLine(`[graph-render] reject account=${accountId} reason=empty nodeId=${nodeId}`);
+            return {
+                ok: false,
+                reason: "empty",
+                message: "Root node found but its neighbourhood is empty after trash filter.",
+            };
+        }
+        const record = result.records[0];
+        const nodeRows = record.get("nodeRows");
+        const edgeRowsRaw = record.get("edgeRows");
+        const totalCountRaw = record.get("totalCount");
+        const totalCount = typeof totalCountRaw === "number"
+            ? totalCountRaw
+            : (totalCountRaw?.toNumber?.() ?? nodeRows.length);
+        // OPTIONAL MATCH on no rels produces one {from:null,to:null,type:null}
+        // row from collect; strip those.
+        const edges = edgeRowsRaw
+            .filter((e) => e.from && e.to && e.type)
+            .map((e) => ({ from: e.from, to: e.to, type: e.type }));
+        if (nodeRows.length === 0) {
+            logLine(`[graph-render] reject account=${accountId} reason=empty nodeId=${nodeId}`);
+            return {
+                ok: false,
+                reason: "empty",
+                message: "Subgraph contained no nodes after trash filter.",
+            };
+        }
+        const layoutNodes = nodeRows.map((n) => ({
+            id: n.id,
+            labels: n.labels,
+        }));
+        const nodeProperties = {};
+        for (const n of nodeRows)
+            nodeProperties[n.id] = n.properties;
+        const layout = layoutGraph(layoutNodes, edges, {
+            width: IMAGE_WIDTH,
+            height: IMAGE_HEIGHT,
+        });
+        let pngBuffer;
+        try {
+            pngBuffer = drawGraph({
+                layout,
+                nodeProperties,
+                width: IMAGE_WIDTH,
+                height: IMAGE_HEIGHT,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logLine(`[graph-render] reject account=${accountId} reason=draw-error nodeId=${nodeId} cause=${message}`);
+            return {
+                ok: false,
+                reason: "draw-error",
+                message: `Canvas draw failed: ${message}`,
+            };
+        }
+        const truncated = totalCount > nodeRows.length
+            ? { rendered: nodeRows.length, total: totalCount }
+            : undefined;
+        const ms = Date.now() - t0;
+        logLine(`[graph-render] ok account=${accountId} ms=${ms} bytes=${pngBuffer.length} ` +
+            `nodeCount=${nodeRows.length} edgeCount=${edges.length} ` +
+            `truncated=${truncated ? "true" : "false"} iterations=${layout.iterations}`);
+        return {
+            ok: true,
+            pngBase64: pngBuffer.toString("base64"),
+            width: IMAGE_WIDTH,
+            height: IMAGE_HEIGHT,
+            nodeCount: nodeRows.length,
+            edgeCount: edges.length,
+            ...(truncated ? { truncated } : {}),
+        };
+    }
+    finally {
+        await session.close();
+    }
+}
+//# sourceMappingURL=graph-render.js.map

package/payload/platform/plugins/graph-viewer/mcp/dist/tools/graph-render.js.map

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

package/payload/platform/plugins/graph-viewer/mcp/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@maxy/graph-viewer",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@napi-rs/canvas": "^0.1.56",
+    "d3-force": "^3.0.0",
+    "neo4j-driver": "^5.28.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/d3-force": "^3.0.10",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.2"
+  }
+}

package/payload/platform/plugins/graph-viewer/mcp/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+    environment: "node",
+  },
+});

package/payload/platform/plugins/graph-viewer/skills/render-graph/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: render-graph
+description: "Render an inline PNG of a Neo4j subgraph for the operator using the graph-render MCP tool. Use when the operator asks to 'see the graph', 'show me the subgraph around X', 'render the owner subgraph', or any request whose outcome is a picture of nodes-and-edges they can look at in chat. Never substitute Mermaid, ASCII, or any other graph stand-in: graph-render is the only correct surface, and if it refuses (foreign account, missing node, empty neighbourhood, draw error) surface the structured error to the operator and stop. The image uses the same palette and short-label strings as the admin /graph page; node positions will differ because the renderer is d3-force not vis-network."
+---
+
+# render-graph
+
+When the operator asks for a picture of a subgraph:
+
+1. Resolve the root node's `elementId` first — usually via `memory-search`
+   or another graph tool the operator already pointed you at. Never pass a
+   property like `name` as `nodeId`.
+2. Pick a `hopDepth` between 0 and 3. Default to 1 unless the operator
+   asks for the wider neighbourhood. Depth 3 on a busy node will hit the
+   200-node cap and return a `truncated` envelope.
+3. Call `graph-render` with `{ accountId, nodeId, hopDepth }`.
+4. If the result is `ok: true`, the image attaches itself to your reply.
+   Tell the operator how many nodes are in view and, if `truncated` is
+   present, that there were more nodes than the cap.
+5. If the result is `ok: false`, surface the structured `reason` and
+   `message` to the operator verbatim. Do not retry with a different
+   nodeId without their input. Do not fall back to Mermaid, ASCII, or any
+   other graph substitute.
+
+## Reasons graph-render can refuse
+
+- `scope` — the nodeId belongs to a different account, or does not exist.
+- `empty` — the root exists but its neighbourhood is empty after the
+  trash filter.
+- `cap-exceeded` — reserved for future use; today subgraphs above 200
+  nodes return `ok: true` with a `truncated` envelope.
+- `draw-error` — the canvas renderer failed. The message contains the
+  underlying error; if it mentions a missing font, the system font fallback
+  is unavailable on this device.
+- `invalid-input` — `hopDepth` was outside the 0-3 range.

package/payload/platform/scripts/check-plugin-tools-mcp-consistency.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// Publish-time gate: every PLUGIN.md with a non-empty `tools:` frontmatter
+// block must also declare an `mcp:` block. The `tools:` block populates the
+// `--allowed-tools mcp__<plugin>__*` spawn argv; without a registered MCP
+// server the agent boots with permissions for tools that have no backend.
+//
+// The session manager throws the same defect at boot
+// (tool-surface.ts 'mcp-block-missing'), but boot is on the operator's
+// device — by then the bad payload has already been published and installed.
+// This gate fires before `npm publish`, in the prepublishOnly chain.
+//
+// Live repro: Task 357 added visitor-graph tools to buyers/PLUGIN.md without
+// the matching mcp: block; the slip-through is what motivates Task 368.
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const MAXY_CODE_ROOT = resolve(__dirname, '..', '..')
+
+const PLUGIN_ROOTS = [
+  // platform/plugins/<plugin>/PLUGIN.md
+  { root: join(MAXY_CODE_ROOT, 'platform', 'plugins'), depth: 1 },
+  // premium-plugins/<bundle>/PLUGIN.md           (shape b)
+  { root: join(MAXY_CODE_ROOT, 'premium-plugins'), depth: 1 },
+  // premium-plugins/<bundle>/plugins/<sub>/PLUGIN.md  (shape a)
+  { root: join(MAXY_CODE_ROOT, 'premium-plugins'), depth: 2, mid: 'plugins' },
+]
+
+function collectPluginDirs() {
+  const dirs = []
+  for (const spec of PLUGIN_ROOTS) {
+    if (!existsSync(spec.root)) continue
+    for (const entry of readdirSync(spec.root)) {
+      if (entry.startsWith('.')) continue
+      const lvl1 = join(spec.root, entry)
+      if (!statSync(lvl1).isDirectory()) continue
+      if (spec.depth === 1) {
+        dirs.push(lvl1)
+        continue
+      }
+      const midDir = join(lvl1, spec.mid)
+      if (!existsSync(midDir)) continue
+      if (!statSync(midDir).isDirectory()) continue
+      for (const sub of readdirSync(midDir)) {
+        if (sub.startsWith('.')) continue
+        const lvl2 = join(midDir, sub)
+        if (!statSync(lvl2).isDirectory()) continue
+        dirs.push(lvl2)
+      }
+    }
+  }
+  return dirs
+}
+
+function extractFrontmatter(md) {
+  if (!md.startsWith('---')) return null
+  const end = md.indexOf('\n---', 3)
+  if (end < 0) return null
+  return md.slice(3, end)
+}
+
+// Detect a top-level key in YAML frontmatter (key at column 0, followed by `:`).
+// The key may be bare (`tools:`) — empty value means "block follows on
+// subsequent indented lines" OR "empty list".
+function findTopLevelKey(frontmatter, key) {
+  const re = new RegExp(`^${key}\\s*:`, 'm')
+  return re.test(frontmatter)
+}
+
+// Returns true when the `tools:` block has at least one list entry. A bare
+// `tools:` with no children, or `tools: []`, is treated as empty (no surface).
+function hasNonEmptyToolsBlock(frontmatter) {
+  const lines = frontmatter.split('\n')
+  let inTools = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (/^tools\s*:/.test(line)) {
+      const after = line.replace(/^tools\s*:/, '').trim()
+      // Inline form: `tools: []` or `tools: [a, b]`
+      if (after.startsWith('[')) {
+        return /\[\s*[^\]\s]/.test(after)
+      }
+      if (after) {
+        // Single-line scalar (unusual for tools, but treat as non-empty).
+        return true
+      }
+      inTools = true
+      continue
+    }
+    if (inTools) {
+      if (/^\S/.test(line) && line.trim() !== '') {
+        // Top-level key after tools: — block ended.
+        return false
+      }
+      if (/^\s*-\s+/.test(line)) return true
+    }
+  }
+  return false
+}
+
+function checkPlugin(pluginDir) {
+  const manifestPath = join(pluginDir, 'PLUGIN.md')
+  if (!existsSync(manifestPath)) return null
+  const raw = readFileSync(manifestPath, 'utf-8')
+  const fm = extractFrontmatter(raw)
+  if (fm === null) return null
+  if (!hasNonEmptyToolsBlock(fm)) return null
+  if (findTopLevelKey(fm, 'mcp')) return null
+  return manifestPath
+}
+
+function main() {
+  const offenders = []
+  for (const dir of collectPluginDirs()) {
+    const offender = checkPlugin(dir)
+    if (offender) offenders.push({ dir, manifestPath: offender })
+  }
+  if (offenders.length === 0) {
+    console.log('[gate] check-plugin-tools-mcp-consistency: PASS')
+    return
+  }
+  for (const { dir, manifestPath } of offenders) {
+    const plugin = dir.split('/').pop()
+    console.error(
+      `[gate] FATAL: plugin=${plugin} has tools: block but no mcp: block.\n` +
+        `  manifest: ${manifestPath}\n` +
+        `  Spawns would pass --allowed-tools mcp__${plugin}__* with no registered server.\n` +
+        `  Add mcp: block or remove tools: entries.`,
+    )
+  }
+  process.exit(1)
+}
+
+main()