@fairfox/polly 0.73.1 → 0.74.1

package/dist/tools/visualize/src/cli.js

@@ -667,7 +667,7 @@ function detectProjectConfig(projectRoot) {
 var init_project_detector = () => {};
 
 // tools/visualize/src/cli.ts
-import * as fs6 from "node:fs";
+import * as fs7 from "node:fs";
 import * as path6 from "node:path";
 
 // tools/analysis/src/extract/architecture.ts
@@ -4590,6 +4590,122 @@ async function analyzeArchitecture(options) {
   return analyzer.analyze();
 }
 
+// src/shared/lib/derive-document-id.ts
+import {
+  interpretAsDocumentId
+} from "@automerge/automerge-repo/slim";
+import nacl from "tweetnacl";
+var DOC_ID_DOMAIN = "polly/meshState/v1";
+var keyEncoder = new TextEncoder;
+function deriveDocumentId(key) {
+  const digest = nacl.hash(keyEncoder.encode(`${DOC_ID_DOMAIN}:${key}`));
+  const bytes = digest.slice(0, 16);
+  return interpretAsDocumentId(bytes);
+}
+
+// tools/visualize/src/mesh-snapshot.ts
+import * as fs5 from "node:fs";
+
+class MeshSnapshotError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MeshSnapshotError";
+  }
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireStringArray(value, path5) {
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+    throw new MeshSnapshotError(`${path5} must be an array of strings`);
+  }
+  return value;
+}
+function validateHandle(value, path5) {
+  if (!isObject(value)) {
+    throw new MeshSnapshotError(`${path5} must be an object`);
+  }
+  if (typeof value["docSynchronizerExists"] !== "boolean") {
+    throw new MeshSnapshotError(`${path5}.docSynchronizerExists must be a boolean`);
+  }
+  const knowsPeer = value["docSynchronizerKnowsPeer"];
+  if (knowsPeer !== undefined && typeof knowsPeer !== "boolean") {
+    throw new MeshSnapshotError(`${path5}.docSynchronizerKnowsPeer must be a boolean or absent`);
+  }
+  const status = value["peerDocumentStatus"];
+  if (status !== undefined && typeof status !== "string") {
+    throw new MeshSnapshotError(`${path5}.peerDocumentStatus must be a string or absent`);
+  }
+  return value;
+}
+function validatePeer(value, path5) {
+  if (!isObject(value)) {
+    throw new MeshSnapshotError(`${path5} must be an object`);
+  }
+  if (typeof value["peerId"] !== "string") {
+    throw new MeshSnapshotError(`${path5}.peerId must be a string`);
+  }
+  const slot = value["slot"];
+  if (slot !== undefined && slot !== null) {
+    if (!isObject(slot)) {
+      throw new MeshSnapshotError(`${path5}.slot must be an object or absent`);
+    }
+    const handles = slot["handles"];
+    if (!isObject(handles)) {
+      throw new MeshSnapshotError(`${path5}.slot.handles must be an object`);
+    }
+    for (const [docId, handle] of Object.entries(handles)) {
+      validateHandle(handle, `${path5}.slot.handles[${docId}]`);
+    }
+  }
+  return value;
+}
+function validateMeshSnapshot(data) {
+  if (!isObject(data)) {
+    throw new MeshSnapshotError("snapshot must be a JSON object");
+  }
+  if (typeof data["localPeerId"] !== "string") {
+    throw new MeshSnapshotError("snapshot.localPeerId must be a string");
+  }
+  requireStringArray(data["knownPeerIds"], "snapshot.knownPeerIds");
+  requireStringArray(data["presentPeerIds"], "snapshot.presentPeerIds");
+  const peers = data["peers"];
+  if (!Array.isArray(peers)) {
+    throw new MeshSnapshotError("snapshot.peers must be an array");
+  }
+  peers.forEach((peer, i) => {
+    validatePeer(peer, `snapshot.peers[${i}]`);
+  });
+  return data;
+}
+function loadMeshSnapshot(filePath) {
+  let raw;
+  try {
+    raw = fs5.readFileSync(filePath, "utf-8");
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new MeshSnapshotError(`cannot read snapshot file '${filePath}': ${reason}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new MeshSnapshotError(`snapshot file '${filePath}' is not valid JSON: ${reason}`);
+  }
+  return validateMeshSnapshot(parsed);
+}
+function collectSnapshotPeerIds(snapshot) {
+  const ids = new Set([snapshot.localPeerId]);
+  for (const id of snapshot.knownPeerIds)
+    ids.add(id);
+  for (const id of snapshot.presentPeerIds)
+    ids.add(id);
+  for (const peer of snapshot.peers)
+    ids.add(peer.peerId);
+  return [...ids];
+}
+
 // tools/visualize/src/types/structurizr.ts
 var DEFAULT_COLORS = {
   messageHandler: "#1168bd",
@@ -4690,6 +4806,46 @@ var DEFAULT_RELATIONSHIP_STYLES = {
     color: DEFAULT_COLORS.database
   }
 };
+var MESH_OVERLAY_ELEMENT_STYLES = {
+  "Mesh Peer": {
+    shape: "Person",
+    background: "#495057",
+    color: DEFAULT_COLORS.textLight
+  },
+  "Local Mesh Peer": {
+    shape: "Person",
+    background: DEFAULT_COLORS.messageHandler,
+    color: DEFAULT_COLORS.textLight
+  },
+  "Snapshot Document": {
+    shape: "Cylinder",
+    background: "#adb5bd",
+    color: DEFAULT_COLORS.textDark,
+    border: "Dashed"
+  }
+};
+var MESH_OVERLAY_RELATIONSHIP_STYLES = {
+  "sync:has": {
+    color: "#2f9e44",
+    style: "Solid",
+    thickness: 3
+  },
+  "sync:wants": {
+    color: "#f08c00",
+    style: "Dashed",
+    thickness: 2
+  },
+  "sync:unavailable": {
+    color: "#e03131",
+    style: "Dashed",
+    thickness: 2
+  },
+  "sync:unknown": {
+    color: "#868e96",
+    style: "Dotted",
+    thickness: 2
+  }
+};
 var DEFAULT_THEME = "https://static.structurizr.com/themes/default/theme.json";
 
 // tools/visualize/src/codegen/structurizr.ts
@@ -4715,10 +4871,18 @@ var MESH_TRANSPORT_NODES = [
     description: "The rendezvous server peers exchange WebRTC offers through"
   }
 ];
+function syncStatusOf(handle) {
+  const status = handle.peerDocumentStatus;
+  if (status === "has" || status === "wants" || status === "unavailable") {
+    return status;
+  }
+  return "unknown";
+}
 
 class StructurizrDSLGenerator {
   analysis;
   options;
+  overlayPlanCache;
   constructor(analysis, options = {}) {
     this.analysis = analysis;
     this.options = {
@@ -4737,10 +4901,12 @@ class StructurizrDSLGenerator {
         theme: options.styles?.theme || DEFAULT_THEME,
         elements: {
           ...DEFAULT_ELEMENT_STYLES,
+          ...options.snapshot ? MESH_OVERLAY_ELEMENT_STYLES : {},
           ...options.styles?.elements
         },
         relationships: {
           ...DEFAULT_RELATIONSHIP_STYLES,
+          ...options.snapshot ? MESH_OVERLAY_RELATIONSHIP_STYLES : {},
           ...options.styles?.relationships
         }
       }
@@ -4774,6 +4940,9 @@ class StructurizrDSLGenerator {
     const parts = [];
     parts.push("  model {");
     parts.push(this.generatePeople());
+    const meshPeers = this.generateMeshPeers();
+    if (meshPeers)
+      parts.push(meshPeers);
     parts.push(this.generateExternalSystems());
     parts.push(this.generateMainSystem());
     if (this.options.deploymentNodes && this.options.deploymentNodes.length > 0) {
@@ -4814,6 +4983,9 @@ class StructurizrDSLGenerator {
     const meshDocs = this.generateMeshDocuments();
     if (meshDocs)
       parts.push(meshDocs);
+    const snapshotDocs = this.generateSnapshotOnlyDocuments();
+    if (snapshotDocs)
+      parts.push(snapshotDocs);
     const meshTransport = this.generateMeshTransport();
     if (meshTransport)
       parts.push(meshTransport);
@@ -5202,6 +5374,7 @@ class StructurizrDSLGenerator {
     parts.push(...this.generateExternalAPIRelationships());
     parts.push(...this.generateMeshRelationships());
     parts.push(...this.generateMeshTransportRelationships());
+    parts.push(...this.generateMeshOverlayRelationships());
     return parts.join(`
 `);
   }
@@ -5268,6 +5441,130 @@ class StructurizrDSLGenerator {
     }
     return parts;
   }
+  getOverlayPlan() {
+    const snapshot = this.options.snapshot;
+    if (!snapshot)
+      return;
+    if (!this.overlayPlanCache) {
+      this.overlayPlanCache = this.buildOverlayPlan(snapshot);
+    }
+    return this.overlayPlanCache;
+  }
+  buildOverlayPlan(snapshot) {
+    const docIdToNode = this.buildDocIdNodeMap();
+    const { peers, peerDslById } = this.buildOverlayPeers(snapshot);
+    const { edges, snapshotOnlyDocs } = this.buildOverlayEdges(snapshot, docIdToNode, peerDslById);
+    return { peers, edges, snapshotOnlyDocs };
+  }
+  buildDocIdNodeMap() {
+    const docIdToNode = new Map;
+    const seenKeys = new Set;
+    for (const sig of this.analysis.meshOrPeerSignals ?? []) {
+      if (seenKeys.has(sig.key))
+        continue;
+      seenKeys.add(sig.key);
+      docIdToNode.set(String(deriveDocumentId(sig.key)), this.meshDocId(sig.key));
+    }
+    return docIdToNode;
+  }
+  buildOverlayPeers(snapshot) {
+    const peers = [];
+    const peerDslById = new Map;
+    const usedPeerIds = new Set;
+    for (const peerId of collectSnapshotPeerIds(snapshot)) {
+      const base = `peer_${this.toId(peerId)}`;
+      let id = base;
+      let suffix = 2;
+      while (usedPeerIds.has(id))
+        id = `${base}_${suffix++}`;
+      usedPeerIds.add(id);
+      peerDslById.set(peerId, id);
+      peers.push({ id, peerId, isLocal: peerId === snapshot.localPeerId });
+    }
+    return { peers, peerDslById };
+  }
+  buildOverlayEdges(snapshot, docIdToNode, peerDslById) {
+    const edges = [];
+    const snapshotOnlyDocs = [];
+    const snapshotOnlyById = new Map;
+    for (const peer of snapshot.peers) {
+      const handles = peer.slot?.handles;
+      const fromId = peerDslById.get(peer.peerId);
+      if (!handles || !fromId)
+        continue;
+      for (const [docId, handle] of Object.entries(handles)) {
+        const nodeId = this.resolveOverlayDocNode(docId, docIdToNode, snapshotOnlyById, snapshotOnlyDocs);
+        const status = syncStatusOf(handle);
+        edges.push({
+          fromId,
+          toRef: `extension.${nodeId}`,
+          status,
+          label: this.overlayEdgeLabel(status, handle)
+        });
+      }
+    }
+    return { edges, snapshotOnlyDocs };
+  }
+  resolveOverlayDocNode(docId, docIdToNode, snapshotOnlyById, snapshotOnlyDocs) {
+    const staticNode = docIdToNode.get(docId);
+    if (staticNode)
+      return staticNode;
+    const existing = snapshotOnlyById.get(docId);
+    if (existing)
+      return existing;
+    const nodeId = `mesh_doc_${this.toId(docId)}`;
+    snapshotOnlyById.set(docId, nodeId);
+    snapshotOnlyDocs.push({ id: nodeId, docId });
+    return nodeId;
+  }
+  overlayEdgeLabel(status, handle) {
+    if (!handle.docSynchronizerExists)
+      return `${status} · no synchronizer`;
+    if (handle.docSynchronizerKnowsPeer === false)
+      return `${status} · peer not added`;
+    return status;
+  }
+  generateMeshPeers() {
+    const plan = this.getOverlayPlan();
+    if (!plan || plan.peers.length === 0)
+      return "";
+    const parts = [];
+    for (const peer of plan.peers) {
+      const tag = peer.isLocal ? "Local Mesh Peer" : "Mesh Peer";
+      const description = peer.isLocal ? "Local mesh peer (this node)" : "Runtime mesh peer";
+      parts.push(`    ${peer.id} = person "${this.escape(peer.peerId)}" "${description}" {`);
+      parts.push(`      tags "${tag}"`);
+      parts.push("    }");
+    }
+    return parts.join(`
+`);
+  }
+  generateSnapshotOnlyDocuments() {
+    const plan = this.getOverlayPlan();
+    if (!plan || plan.snapshotOnlyDocs.length === 0)
+      return "";
+    const parts = [];
+    for (const doc of plan.snapshotOnlyDocs) {
+      const description = `Mesh document seen only in the runtime snapshot — docId ${doc.docId}`;
+      parts.push(`      ${doc.id} = container "${this.escape(doc.docId)}" "${this.escape(description)}" "snapshot" {`);
+      parts.push('        tags "Snapshot Document"');
+      parts.push("      }");
+    }
+    return parts.join(`
+`);
+  }
+  generateMeshOverlayRelationships() {
+    const plan = this.getOverlayPlan();
+    if (!plan)
+      return [];
+    const parts = [];
+    for (const edge of plan.edges) {
+      parts.push(`      ${edge.fromId} -> ${edge.toRef} "${this.escape(edge.label)}" {`);
+      parts.push(`        tags "sync:${edge.status}"`);
+      parts.push("      }");
+    }
+    return parts;
+  }
   generateUserRelationships() {
     const parts = [];
     const uiContexts = ["popup", "options", "devtools"];
@@ -6015,7 +6312,7 @@ function generateStructurizrDSL(analysis, options) {
 
 // tools/visualize/src/runner/export.ts
 import { spawn } from "node:child_process";
-import * as fs5 from "node:fs";
+import * as fs6 from "node:fs";
 import * as path5 from "node:path";
 
 class DiagramExporter {
@@ -6023,15 +6320,15 @@ class DiagramExporter {
   static DEFAULT_TIMEOUT = 120000;
   async export(options) {
     const { dslPath, outputDir, timeout = DiagramExporter.DEFAULT_TIMEOUT } = options;
-    if (!fs5.existsSync(dslPath)) {
+    if (!fs6.existsSync(dslPath)) {
       return {
         success: false,
         siteDir: "",
         error: `DSL file not found: ${dslPath}`
       };
     }
-    if (!fs5.existsSync(outputDir)) {
-      fs5.mkdirSync(outputDir, { recursive: true });
+    if (!fs6.existsSync(outputDir)) {
+      fs6.mkdirSync(outputDir, { recursive: true });
     }
     const dockerAvailable = await this.isDockerAvailable();
     if (!dockerAvailable) {
@@ -6179,7 +6476,7 @@ async function main() {
   switch (command) {
     case "--generate":
     case "generate":
-      await generateCommand();
+      await generateCommand(args.slice(1));
       break;
     case "--export":
     case "export":
@@ -6196,22 +6493,64 @@ async function main() {
       showHelp();
       break;
     default:
-      await generateCommand();
+      await generateCommand(args);
   }
 }
-async function generateCommand() {
+async function generateCommand(args) {
   console.log(color(`
 \uD83D\uDCCA Analyzing architecture...
 `, COLORS.blue));
   try {
+    const { snapshotPath } = parseGenerateArgs(args);
+    const snapshot = snapshotPath ? loadAndReportSnapshot(snapshotPath) : undefined;
     const { tsConfigPath, projectRoot } = findAndDisplayProjectConfig();
     const analysis = await analyzeAndDisplayResults(tsConfigPath, projectRoot);
-    const dslPath = generateAndWriteDSL(analysis);
+    const dslPath = generateAndWriteDSL(analysis, snapshot);
     displayNextSteps(dslPath);
   } catch (_error) {
     process.exit(1);
   }
 }
+function parseGenerateArgs(args) {
+  const result = {};
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--snapshot") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("--")) {
+        console.log(color(`
+✗ --snapshot requires a file path
+`, COLORS.red));
+        process.exit(1);
+      }
+      result.snapshotPath = next;
+      i++;
+    } else if (arg?.startsWith("--snapshot=")) {
+      result.snapshotPath = arg.slice("--snapshot=".length);
+    }
+  }
+  return result;
+}
+function loadAndReportSnapshot(snapshotPath) {
+  let snapshot;
+  try {
+    snapshot = loadMeshSnapshot(snapshotPath);
+  } catch (error) {
+    const message = error instanceof MeshSnapshotError ? error.message : String(error);
+    console.log(color(`
+✗ Snapshot error: ${message}
+`, COLORS.red));
+    process.exit(1);
+  }
+  const isEmpty = snapshot.knownPeerIds.length === 0 && snapshot.presentPeerIds.length === 0 && snapshot.peers.length === 0;
+  if (isEmpty) {
+    console.log(color("⚠ Snapshot has no peers — generating the static diagram only.", COLORS.yellow));
+    return;
+  }
+  const peerCount = collectSnapshotPeerIds(snapshot).length;
+  console.log(color(`✓ Loaded runtime snapshot: ${peerCount} peer(s)`, COLORS.green));
+  return snapshot;
+}
 function findAndDisplayProjectConfig() {
   const tsConfigPath = findTsConfig();
   if (!tsConfigPath) {
@@ -6227,7 +6566,7 @@ function findAndDisplayProjectConfig() {
   return { tsConfigPath, projectRoot };
 }
 function displayProjectType(projectRoot) {
-  const hasManifest = fs6.existsSync(path6.join(projectRoot, "manifest.json"));
+  const hasManifest = fs7.existsSync(path6.join(projectRoot, "manifest.json"));
   const projectType = hasManifest ? "Chrome Extension" : "Detecting from project structure...";
   console.log(color(`   Type: ${projectType}`, COLORS.gray));
 }
@@ -6261,7 +6600,7 @@ function displayArchitectureSummary(analysis) {
     }
   }
 }
-function generateAndWriteDSL(analysis) {
+function generateAndWriteDSL(analysis, snapshot) {
   console.log(color(`
 \uD83D\uDCDD Generating Structurizr DSL...
 `, COLORS.blue));
@@ -6269,14 +6608,15 @@ function generateAndWriteDSL(analysis) {
   const dsl = generateStructurizrDSL(analysis, {
     includeDynamicDiagrams: true,
     includeComponentDiagrams: true,
-    componentDiagramContexts: contextTypes.length > 0 ? contextTypes : ["background"]
+    componentDiagramContexts: contextTypes.length > 0 ? contextTypes : ["background"],
+    snapshot
   });
   const outputDir = path6.join(process.cwd(), "docs");
-  if (!fs6.existsSync(outputDir)) {
-    fs6.mkdirSync(outputDir, { recursive: true });
+  if (!fs7.existsSync(outputDir)) {
+    fs7.mkdirSync(outputDir, { recursive: true });
   }
   const dslPath = path6.join(outputDir, "architecture.dsl");
-  fs6.writeFileSync(dslPath, dsl, "utf-8");
+  fs7.writeFileSync(dslPath, dsl, "utf-8");
   return dslPath;
 }
 function displayNextSteps(dslPath) {
@@ -6312,7 +6652,7 @@ async function exportCommand(_args) {
 `, COLORS.blue));
   try {
     const dslPath = path6.join(process.cwd(), "docs", "architecture.dsl");
-    if (!fs6.existsSync(dslPath)) {
+    if (!fs7.existsSync(dslPath)) {
       process.exit(1);
     }
     const outputDir = path6.join(process.cwd(), "docs", "site");
@@ -6350,7 +6690,7 @@ async function serveCommand(args) {
   try {
     const siteDir = path6.join(process.cwd(), "docs", "site");
     const indexPath = path6.join(siteDir, "index.html");
-    if (!fs6.existsSync(indexPath)) {
+    if (!fs7.existsSync(indexPath)) {
       process.exit(1);
     }
     const portArg = args.find((arg) => arg.startsWith("--port="));
@@ -6367,7 +6707,7 @@ async function serveCommand(args) {
       fetch(req) {
         const url = new URL(req.url);
         const filePath = path6.join(siteDir, url.pathname === "/" ? "index.html" : url.pathname);
-        if (fs6.existsSync(filePath) && fs6.statSync(filePath).isFile()) {
+        if (fs7.existsSync(filePath) && fs7.statSync(filePath).isFile()) {
           const file = BunGlobal.file(filePath);
           return new Response(file);
         }
@@ -6411,6 +6751,10 @@ ${color("Commands:", COLORS.blue)}
   ${color("bun visualize --generate", COLORS.green)}
     Analyze codebase and generate Structurizr DSL
 
+  ${color("bun visualize generate --snapshot <path>", COLORS.green)}
+    Overlay a captured MeshClientPeerStateSnapshot — runtime mesh peers
+    and sync-state-coloured replication edges — onto the diagram
+
   ${color("bun visualize --export", COLORS.green)}
     Generate static HTML site with interactive diagrams (requires Docker)
 
@@ -6447,7 +6791,7 @@ function findTsConfig() {
     path6.join(process.cwd(), "..", "tsconfig.json")
   ];
   for (const loc of locations) {
-    if (fs6.existsSync(loc)) {
+    if (fs7.existsSync(loc)) {
       return loc;
     }
   }
@@ -6456,7 +6800,7 @@ function findTsConfig() {
 function findProjectRoot() {
   const locations = [process.cwd(), path6.join(process.cwd(), "..")];
   for (const loc of locations) {
-    if (fs6.existsSync(path6.join(loc, "manifest.json")) || fs6.existsSync(path6.join(loc, "package.json")) || fs6.existsSync(path6.join(loc, "tsconfig.json"))) {
+    if (fs7.existsSync(path6.join(loc, "manifest.json")) || fs7.existsSync(path6.join(loc, "package.json")) || fs7.existsSync(path6.join(loc, "tsconfig.json"))) {
       return loc;
     }
   }
@@ -6466,4 +6810,4 @@ main().catch((_error) => {
   process.exit(1);
 });
 
-//# debugId=2FC255DE0B3BC47C64756E2164756E21
+//# debugId=4CFC761842CDF97B64756E2164756E21