npm - @sigloch/graph-view-edit - Versions diffs - 0.1.0 - Mend

@sigloch/graph-view-edit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +100 -0
package/bin/gve.mjs +41 -0
package/dist/assets/index-Cxy3uYBx.css +1 -0
package/dist/assets/index-UnMYySno.js +180 -0
package/dist/index.html +13 -0
package/package.json +50 -0
package/src/config.mjs +49 -0
package/vite.config.js +411 -0

package/dist/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>graph-view-edit</title>
+    <script type="module" crossorigin src="/assets/index-UnMYySno.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Cxy3uYBx.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/package.json ADDED Viewed

@@ -0,0 +1,50 @@
+{
+  "name": "@sigloch/graph-view-edit",
+  "version": "0.1.0",
+  "description": "React/Vite viewer+editor over @sigloch/graphcode — 12 graph-views + 16 doc-views via a declarative View-Registry, plus an SE-Dashboard sibling route. Reads docs/graph/<member>.graph.json client-side (no 2nd Kuzu handle).",
+  "type": "module",
+  "bin": {
+    "gve": "bin/gve.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "vite.config.js",
+    "src/config.mjs"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "prepack": "npm run build",
+    "test": "vitest run"
+  },
+  "comment:deps": "Runtime = what vite.config.js + bin/gve.mjs load at Node level when serving the prebuilt dist/. The UI libs (react, react-dom, elkjs, @tanstack/react-table, zustand) are bundled INTO dist/ by vite and must stay devDependencies — shipping them would make consumers download the whole UI stack twice.",
+  "dependencies": {
+    "@sigloch/contracts": "^0.8.0",
+    "@sigloch/graph-api-core": "^0.4.1",
+    "@sigloch/graphcode-client": "^0.2.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "vite": "^5.4.11",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@tanstack/react-table": "^8.20.5",
+    "@testing-library/react": "^16.0.1",
+    "elkjs": "^0.11.1",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "vitest": "^2.0.0",
+    "zustand": "^4.5.5"
+  },
+  "author": "andreas@siglochconsulting",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.mjs ADDED Viewed

@@ -0,0 +1,49 @@
+/**
+ * Static config loader (CR-GVE-101 / REQ-ops-config-static).
+ *
+ * Reads a versionable JSON config file (default `config.json`, see
+ * `config.example.json` for the template) and validates it against
+ * `ConfigSchema`. Missing file or missing fields fall back to schema
+ * defaults; a present-but-invalid file throws (fail fast, no silent
+ * fallback — schema-first per REQ-nfr-stack).
+ *
+ * Nested object defaults use `.prefault({})`, not `.default({})` (CR-GVE-221):
+ * since zod 4 `.default()` hands its value through RAW, so `.default({})` on
+ * `graph` would yield `{}` instead of `{path: …, host: null}` — the viewer
+ * would lose the graph path whenever config.json is absent. `.prefault()` runs
+ * the value through the inner schema, i.e. zod 3's `.default()` semantics.
+ * Defaults on primitives are unaffected and stay `.default(…)`.
+ *
+ * @author andreas@siglochconsulting
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+export const ConfigSchema = z.object({
+  graph: z
+    .object({
+      path: z.string().default('docs/graph/graph-view-edit.graph.json'),
+      host: z.string().nullable().default(null),
+    })
+    .prefault({}),
+  port: z.number().int().positive().default(4317),
+  ontologyDescriptor: z.string().default('se'),
+  tokenTheme: z.string().default('default'),
+  viewRegistryDefaults: z
+    .object({
+      view: z.string().nullable().default(null),
+      scope: z.string().nullable().default(null),
+    })
+    .prefault({}),
+  edit: z
+    .object({
+      enabled: z.boolean().default(false),
+    })
+    .prefault({}),
+});
+export function loadConfig(path = process.env.GVE_CONFIG_PATH || resolve(process.cwd(), 'config.json')) {
+  const raw = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : {};
+  return ConfigSchema.parse(raw);
+}

package/vite.config.js ADDED Viewed

@@ -0,0 +1,411 @@
+import { readFileSync, existsSync, readdirSync, statSync, watch } from 'node:fs';
+import { join, basename } from 'node:path';
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { DefaultRuleEngine, SE_DESCRIPTOR } from '@sigloch/graph-api-core';
+import { ONTOLOGY_VERSION, RULES_VERSION } from '@sigloch/contracts/se';
+// CR-GC-265: these eight come from the read-side client, not the substrate.
+// They are pure projection plus a node:net socket call — depending on
+// @sigloch/graphcode for them pulled kuzu-wasm, the MCP SDK and the TypeScript
+// compiler (~99 MB) into a viewer that must never open a store.
+import {
+  computeReadiness,
+  readinessPanel,
+  recommendationsPanel,
+  artifactsPanel,
+  healthPanel,
+  VIEW_FILENAMES,
+  callHost,
+  HOST_SOCK_BASENAME,
+} from '@sigloch/graphcode-client';
+import { loadConfig } from './src/config.mjs';
+/**
+ * Static config (CR-GVE-138 / REQ-ops-config-static) — loadConfig validates
+ * config.json (or GVE_CONFIG_PATH) against ConfigSchema once at server start;
+ * missing file = schema defaults, invalid file = fail fast. The result drives
+ * the dev-server port below and is served to the browser at runtime via
+ * GET /api/config (configApiPlugin → src/app-config.mjs initAppConfig), so
+ * the client reads the SAME validated config — nothing is baked into the
+ * bundle, one prebuilt dist/ serves any repo (CR-GVE-181).
+ *
+ * Unter vitest wird die COMMITTETE config.example.json gepinnt (analog
+ * tests/helpers/dev-server.mjs): eine lokale config.json — z.B. ein User-
+ * Experiment mit anderem graph.path — darf die Suite nicht auf einen fremden
+ * Graphen umleiten. Explizites GVE_CONFIG_PATH gewinnt weiterhin.
+ */
+const APP_CONFIG = loadConfig(
+  process.env.GVE_CONFIG_PATH ?? (process.env.VITEST ? 'config.example.json' : undefined),
+);
+/**
+ * Repo root this app instance reads/writes (CR-GVE-127). Defaults to
+ * process.cwd() — zero behavior change for the normal case (running inside
+ * the repo it's viewing). Overridable via GVE_REPO_ROOT so the SAME app
+ * instance can point at a different repo's docs/graph/*.graph.json +
+ * .graphcode/host.sock — e.g. an isolated sandbox copy, safe for
+ * destructive testing without touching the live tracked project graph.
+ */
+function resolveRepoRoot() {
+  return process.env.GVE_REPO_ROOT || process.cwd();
+}
+/**
+ * Serves docs/graph/*.json from the resolved repo root (CR-GVE-127) instead
+ * of relying on Vite's default static passthrough from its OWN project
+ * root — without this, GVE_REPO_ROOT would redirect the API plugins but
+ * Renderer.jsx's graph fetch would still silently read the wrong repo's
+ * data. No-op (falls through to Vite's own static handling) when
+ * GVE_REPO_ROOT is unset.
+ */
+function graphStaticPlugin() {
+  const middleware = (req, res, next) => {
+    const repoRoot = process.env.GVE_REPO_ROOT;
+    if (!repoRoot || !req.url?.startsWith('/docs/graph/')) return next();
+    const filePath = join(repoRoot, req.url);
+    if (!existsSync(filePath)) return next();
+    res.setHeader('Content-Type', 'application/json');
+    res.end(readFileSync(filePath));
+  };
+  return {
+    name: 'gve-graph-static-override',
+    configureServer(server) {
+      server.middlewares.use(middleware);
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use(middleware);
+    },
+  };
+}
+/**
+ * GET /api/config (CR-GVE-181) — serves the validated server-side config to
+ * the browser at runtime instead of baking it into the bundle via `define`,
+ * so ONE prebuilt dist/ serves any repo. graph.path is resolved against the
+ * active repo root per request: when the configured file doesn't exist there
+ * (a foreign repo without its own gve config.json), the first
+ * docs/graph/*.graph.json wins — the same discovery the dashboard uses, so
+ * `gve --repo <path>` needs no per-repo config to find the graph.
+ */
+function configApiPlugin() {
+  const middleware = (req, res, next) => {
+    if (req.url !== '/api/config') return next();
+    const repoRoot = resolveRepoRoot();
+    const config = structuredClone(APP_CONFIG);
+    if (!existsSync(join(repoRoot, config.graph.path))) {
+      const graphDir = join(repoRoot, 'docs', 'graph');
+      const hit = existsSync(graphDir)
+        ? readdirSync(graphDir).find((f) => f.endsWith('.graph.json'))
+        : null;
+      if (hit) config.graph.path = `docs/graph/${hit}`;
+    }
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify(config));
+  };
+  return {
+    name: 'gve-config-api',
+    configureServer(server) {
+      server.middlewares.use(middleware);
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use(middleware);
+    },
+  };
+}
+/**
+ * SE-Dashboard API (CR-GVE-117) — GET /api/dashboard, computed server-side.
+ * @sigloch/graphcode's panel functions can't be imported into browser code
+ * (Node-only internals break the Vite build — see CR-GVE-120's VIEW_FILENAMES
+ * finding). vite.config.js itself is never bundled for the browser, so this
+ * middleware is the safe place for that computation; the React dashboard
+ * just fetches the JSON like any other static resource.
+ */
+function dashboardApiPlugin() {
+  const cwd = resolveRepoRoot();
+  const GRAPH_DIR = join(cwd, 'docs', 'graph');
+  const VIEWS_DIR = join(cwd, 'docs', 'views');
+  const engine = new DefaultRuleEngine(SE_DESCRIPTOR.version);
+  engine.register(SE_DESCRIPTOR.rules ?? []);
+  function findGraphFile() {
+    if (!existsSync(GRAPH_DIR)) return null;
+    const hit = readdirSync(GRAPH_DIR).find((f) => f.endsWith('.graph.json'));
+    return hit ? join(GRAPH_DIR, hit) : null;
+  }
+  function loadGraph(file) {
+    const json = JSON.parse(readFileSync(file, 'utf8'));
+    const nodes = (json.elements ?? []).map((e) => {
+      const { id, type, name, description, ...rest } = e;
+      return { uid: id, type, name, description: description ?? '', attributes: rest };
+    });
+    const edges = (json.traces ?? []).map((t) => {
+      const { source, target, type, ...rest } = t;
+      return { sourceId: source, targetId: target, edgeType: type, attributes: rest };
+    });
+    return { nodes, edges };
+  }
+  function scanArtifacts(graphFile) {
+    const graphMtime = existsSync(graphFile) ? statSync(graphFile).mtimeMs : 0;
+    const items = Object.entries(VIEW_FILENAMES).map(([id, fname]) => {
+      const p = join(VIEWS_DIR, fname);
+      const exists = existsSync(p);
+      const staleVsGraph = exists ? statSync(p).mtimeMs < graphMtime : false;
+      return { id, label: id, exists, staleVsGraph };
+    });
+    return artifactsPanel(items);
+  }
+  function synthHealth(graph) {
+    return healthPanel({
+      status: 'ok',
+      store: 'committed graph.json (read-only)',
+      gate: 'n/a — dashboard is read-only (writes go through MCP mutate())',
+      versions: {
+        ontology: ONTOLOGY_VERSION,
+        rules: RULES_VERSION,
+        engine: SE_DESCRIPTOR.version,
+        elements: graph.nodes.length,
+        traces: graph.edges.length,
+      },
+    });
+  }
+  function buildDashboard() {
+    const file = findGraphFile();
+    if (!file) return { member: null, empty: true, error: 'no docs/graph/*.graph.json found', computedAt: new Date().toISOString() };
+    const graph = loadGraph(file);
+    const violations = engine.evaluate(graph);
+    const report = computeReadiness(violations, graph);
+    return {
+      member: basename(file).replace(/\.graph\.json$/, ''),
+      empty: graph.nodes.length === 0,
+      readiness: readinessPanel(report),
+      recommendations: recommendationsPanel(violations, 50),
+      artifacts: scanArtifacts(file),
+      health: synthHealth(graph),
+      computedAt: new Date().toISOString(),
+    };
+  }
+  const middleware = (req, res, next) => {
+    if (req.url !== '/api/dashboard') return next();
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify(buildDashboard()));
+  };
+  return {
+    name: 'gve-dashboard-api',
+    configureServer(server) {
+      server.middlewares.use(middleware);
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use(middleware);
+    },
+  };
+}
+/**
+ * The actual request handling for POST /api/mutate (CR-GVE-008), factored
+ * out of the plugin's HTTP glue so it's directly unit-testable (no server,
+ * no sockets) with an injected `callHostImpl` — same DI pattern as
+ * command-bridge.mjs's fetchImpl. Forwards {commands, baseVersion,
+ * consumerId} to graph_mutate over the elected graphcode host's
+ * `.graphcode/host.sock` (CR-GC-241) — never opens a second Kuzu handle.
+ * Fails loud (throws) when the socket is absent/dead instead of a silent
+ * no-op; the plugin's HTTP wrapper turns that into a clear 503.
+ *
+ * graph_mutate does NOT auto-export docs/graph/*.graph.json (graph_export is
+ * a separate tool, "the single sync path" per its own description) — this
+ * repo's read path (Option A) reads that committed file, so without an
+ * export a refetch after editing would still show stale data. On a
+ * successful mutate with real changes, this also calls graph_export with
+ * force:true — graph_export's refuse-to-clobber guard aborts on ANY
+ * deletion by design (not just stale/drifted state — it protects against a
+ * stale/parallel process silently dropping committed data, a real past
+ * incident per its own source comment). That staleness risk doesn't apply
+ * here: this export runs immediately after a mutation that just passed
+ * THIS SAME live gate in THIS SAME request, so the deletion is known-
+ * intentional, not a stale process's guess (best-effort either way: the
+ * data is already safely persisted in Kuzu, so an export failure is
+ * attached as `exportWarning` rather than turning a successful edit into a
+ * failure response).
+ */
+export async function handleMutateRequest(body, { repoRoot = process.cwd(), callHostImpl = callHost } = {}) {
+  const socketPath = join(repoRoot, '.graphcode', HOST_SOCK_BASENAME);
+  const result = await callHostImpl(socketPath, 'graph_mutate', body);
+  if (result.success && result.mutations > 0) {
+    try {
+      await callHostImpl(socketPath, 'graph_export', { force: true });
+    } catch (err) {
+      return { ...result, exportWarning: `graph_export failed after a successful mutate: ${err.message}` };
+    }
+  }
+  return result;
+}
+/**
+ * POST /api/realize (CR-GVE-135 / REQ-real-bind) — same host.sock transport
+ * and post-write export rationale as handleMutateRequest, but for the
+ * graph_realize tool: binds FUNC↔codeRef (R-20) and optionally TEST↔testRef
+ * (R-19) through the same Apply-Gate (graph_realize composes
+ * harness.mutate, no parallel write path).
+ */
+export async function handleRealizeRequest(body, { repoRoot = process.cwd(), callHostImpl = callHost } = {}) {
+  const socketPath = join(repoRoot, '.graphcode', HOST_SOCK_BASENAME);
+  const result = await callHostImpl(socketPath, 'graph_realize', body);
+  if (result.success !== false) {
+    try {
+      await callHostImpl(socketPath, 'graph_export', { force: true });
+    } catch (err) {
+      return { ...result, exportWarning: `graph_export failed after a successful realize: ${err.message}` };
+    }
+  }
+  return result;
+}
+/**
+ * POST /api/mutate (CR-GVE-008) — bridges the edit-surface's write path to
+ * the SAME Apply-Gate this repo's own graphcode MCP session uses, via the
+ * local host.sock shim (CR-GC-241) rather than a second Kuzu owner.
+ * POST /api/realize (CR-GVE-135) rides the same plugin.
+ */
+function mutateApiPlugin() {
+  const cwd = resolveRepoRoot();
+  const middleware = (req, res, next) => {
+    const isMutate = req.url === '/api/mutate';
+    const isRealize = req.url === '/api/realize';
+    if ((!isMutate && !isRealize) || req.method !== 'POST') return next();
+    let raw = '';
+    req.on('data', (chunk) => { raw += chunk; });
+    req.on('end', async () => {
+      res.setHeader('Content-Type', 'application/json');
+      let body;
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        res.statusCode = 400;
+        res.end(JSON.stringify({ success: false, error: 'invalid JSON body' }));
+        return;
+      }
+      try {
+        const result = isRealize
+          ? await handleRealizeRequest(body, { repoRoot: cwd })
+          : await handleMutateRequest(body, { repoRoot: cwd });
+        res.end(JSON.stringify(result));
+      } catch (err) {
+        // A dead/absent socket is a 503 "start a session"; a tool-level
+        // rejection (e.g. graph_realize: unknown funcUid) is the tool's own
+        // message, not a host problem (CR-GVE-135).
+        const hostDown = /ENOENT|ECONNREFUSED|ECONNRESET|EPIPE|socket/i.test(err.message);
+        res.statusCode = hostDown ? 503 : 422;
+        res.end(
+          JSON.stringify({
+            success: false,
+            error: hostDown
+              ? `no graphcode host reachable for this repo (${err.message}) — start a graphcode session first`
+              : err.message,
+          }),
+        );
+      }
+    });
+  };
+  return {
+    name: 'gve-mutate-api',
+    configureServer(server) {
+      server.middlewares.use(middleware);
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use(middleware);
+    },
+  };
+}
+/**
+ * SSE Invalidate hub (CR-GVE-139 / REQ-live-sse), factored out of the plugin
+ * HTTP glue for direct unit-testability (same DI pattern as
+ * handleMutateRequest). GET /api/events holds the response open as a
+ * text/event-stream client; broadcast() pushes an `invalidate`
+ * LiveUpdateEvent naming the affected domains, which sse-client.mjs
+ * (createSSEClient) hands to each panel for a SELECTIVE refresh.
+ */
+export function createEventsHub() {
+  const clients = new Set();
+  return {
+    middleware(req, res, next) {
+      if (req.url !== '/api/events') return next();
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+      });
+      res.write('retry: 3000\n\n');
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+    },
+    broadcast(domains) {
+      const frame = `event: invalidate\ndata: ${JSON.stringify({ domains })}\n\n`;
+      for (const res of clients) res.write(frame);
+    },
+    clientCount: () => clients.size,
+  };
+}
+/**
+ * GET /api/events (CR-GVE-139). The invalidate TRIGGER is a watcher on
+ * docs/graph/*.graph.json — the single point every write converges on
+ * (own edits via /api/mutate's post-mutate export AND external writers like
+ * a graphcode MCP session exporting), so there's exactly one refresh path
+ * instead of a per-writer special case. A graph change also invalidates
+ * rules/readiness — both are derived from the same committed file.
+ */
+function eventsApiPlugin() {
+  const hub = createEventsHub();
+  const graphDir = join(resolveRepoRoot(), 'docs', 'graph');
+  let debounce = null;
+  function armWatcher() {
+    if (!existsSync(graphDir)) return;
+    const watcher = watch(graphDir, (eventType, filename) => {
+      if (!filename?.endsWith('.graph.json')) return;
+      clearTimeout(debounce);
+      debounce = setTimeout(() => hub.broadcast(['graph', 'rules', 'readiness']), 150);
+    });
+    // Never hold the process open (vitest runs this config's plugins too —
+    // an un-unref'd FSWatcher kept its worker from exiting).
+    watcher.unref();
+  }
+  return {
+    name: 'gve-events-api',
+    configureServer(server) {
+      armWatcher();
+      server.middlewares.use(hub.middleware);
+    },
+    configurePreviewServer(server) {
+      armWatcher();
+      server.middlewares.use(hub.middleware);
+    },
+  };
+}
+export default defineConfig({
+  plugins: [react(), graphStaticPlugin(), configApiPlugin(), dashboardApiPlugin(), mutateApiPlugin(), eventsApiPlugin()],
+  // config.port is the default; an explicit CLI --port (e.g. the test suites'
+  // tests/helpers/dev-server.mjs, which picks a free OS-assigned port with
+  // --strictPort) still overrides it, per Vite's precedence.
+  server: { port: APP_CONFIG.port },
+  preview: { port: APP_CONFIG.port },
+  test: {
+    // Vitest's own default (test/spec files) plus the NFR regression guards
+    // (CR-GVE-115), which intentionally use .bench.mjs/.smoke.mjs names to
+    // read as benchmarks/smoke tests rather than unit tests — without this,
+    // `npm test` would silently never run them.
+    include: ['**/*.{test,spec}.?(c|m)[jt]s?(x)', 'tests/nfr/**/*.{bench,smoke}.mjs'],
+    // Setzt den Modul-Singleton-Graph-Store (CR-GVE-192) vor jedem Test zurück,
+    // sonst leckt ein in Test A geladener Graph in Test B.
+    setupFiles: ['tests/setup.mjs'],
+  },
+});