notex-companion 0.1.0

package/dist/cli.js

@@ -0,0 +1,875 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { existsSync } from "node:fs";
+import { resolve as resolve2 } from "node:path";
+
+// src/graph.ts
+import { createHash } from "node:crypto";
+import { execSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+// src/scoring.ts
+var STOPWORDS = new Set(("a an the and or but if of to in on for with from by at as is are was were " + "do does did how what where when which who why can could should would we " + "our it its this that these those there here about into over under not no " + "you your i me my be been being have has had will shall may might must " + "get got make made use used using does happen happens work works").split(" "));
+function shatter(text) {
+  return String(text).replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).map((t) => t.toLowerCase()).filter(Boolean);
+}
+function terms(question) {
+  return [...new Set(shatter(question).filter((t) => t.length >= 3 && !STOPWORDS.has(t)))];
+}
+function scoreNodes(index, queryTerms) {
+  const scored = [];
+  for (const entry of index) {
+    let score = 0;
+    let exact = false;
+    for (const term of queryTerms) {
+      let best = 0;
+      if (entry.labelLower === term) {
+        best = 6;
+        exact = true;
+      } else if (entry.labelTokens.has(term)) {
+        best = 3;
+        exact = true;
+      } else {
+        for (const tok of entry.labelTokens) {
+          if (tok.length >= 4 && (tok.startsWith(term) || term.startsWith(tok))) {
+            best = Math.max(best, 1.5);
+          } else if (term.length >= 4 && tok.includes(term)) {
+            best = Math.max(best, 1);
+          }
+        }
+      }
+      if (best === 0) {
+        if (entry.pathTokens.has(term)) {
+          best = 1.2;
+        } else {
+          for (const tok of entry.pathTokens) {
+            if (tok.length >= 4 && term.length >= 4 && tok.startsWith(term))
+              best = 0.6;
+          }
+        }
+      }
+      score += best;
+    }
+    if (score > 0)
+      scored.push({ id: entry.id, score: Math.round(score * 100) / 100, exact });
+  }
+  return scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}
+
+// src/types.ts
+var ERROR_CODES = {
+  unauthorized: "unauthorized",
+  notFound: "not_found",
+  graphUnreadable: "graph_unreadable",
+  invalidRequest: "invalid_request",
+  graphLoading: "graph_loading"
+};
+
+class OpError extends Error {
+  code;
+  detail;
+  constructor(code, message, detail) {
+    super(message);
+    this.name = "OpError";
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+// src/graph.ts
+function rootPrefixFor(checkoutPath, graphRoot) {
+  if (graphRoot === checkoutPath)
+    return "";
+  const boundary = checkoutPath.endsWith("/") ? checkoutPath : `${checkoutPath}/`;
+  if (!graphRoot.startsWith(boundary))
+    return "";
+  return graphRoot.slice(boundary.length);
+}
+function readGraphRoot(checkoutPath) {
+  try {
+    return readFileSync(resolve(checkoutPath, "graphify-out/.graphify_root"), "utf8").trim();
+  } catch {
+    return checkoutPath;
+  }
+}
+function readHeadSha(checkoutPath) {
+  try {
+    return execSync("git rev-parse HEAD", { cwd: checkoutPath, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+function loadGraph(checkoutPath) {
+  const graphPath = resolve(checkoutPath, "graphify-out/graph.json");
+  let raw;
+  try {
+    raw = readFileSync(graphPath, "utf8");
+  } catch (err) {
+    throw new OpError("graph_unreadable", `graph.json not found at ${graphPath}`, err);
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    throw new OpError("graph_unreadable", `graph.json at ${graphPath} is not valid JSON`, err);
+  }
+  const graphRoot = readGraphRoot(checkoutPath);
+  const rootPrefix = rootPrefixFor(checkoutPath, graphRoot);
+  const checkoutRelative = (sourceFile) => rootPrefix ? `${rootPrefix}/${sourceFile}` : sourceFile;
+  const stamp = {
+    builtAt: statSync(graphPath).mtime.toISOString(),
+    graphHash: createHash("sha256").update(raw).digest("hex").slice(0, 16),
+    nodeCount: doc.nodes.length,
+    edgeCount: doc.links.length,
+    communityCount: new Set(doc.nodes.map((n) => n.community)).size,
+    checkoutPath,
+    headSha: readHeadSha(checkoutPath),
+    graphRoot,
+    rootPrefix
+  };
+  const nodesById = new Map(doc.nodes.map((n) => [n.id, n]));
+  const adjacency = new Map;
+  for (const e of doc.links) {
+    if (!adjacency.has(e.source))
+      adjacency.set(e.source, []);
+    if (!adjacency.has(e.target))
+      adjacency.set(e.target, []);
+    adjacency.get(e.source).push({ other: e.target, edge: e });
+    adjacency.get(e.target).push({ other: e.source, edge: e });
+  }
+  const scoreIndex = doc.nodes.map((n) => ({
+    id: n.id,
+    labelTokens: new Set([...shatter(n.label), ...shatter(n.norm_label ?? "")]),
+    pathTokens: new Set(shatter(n.source_file ?? "")),
+    labelLower: String(n.label).toLowerCase()
+  }));
+  const project = (n) => ({
+    id: n.id,
+    label: n.label,
+    sourceFile: checkoutRelative(n.source_file),
+    sourceLocation: n.source_location,
+    fileType: n.file_type,
+    community: n.community == null ? null : { id: n.community, name: n.community_name ?? "" }
+  });
+  const projectEdge = (e) => ({
+    source: e.source,
+    target: e.target,
+    relation: e.relation,
+    weight: e.weight,
+    confidence: e.confidence,
+    sourceFile: checkoutRelative(e.source_file),
+    sourceLocation: e.source_location
+  });
+  return { stamp, nodesById, edges: doc.links, adjacency, scoreIndex, project, projectEdge };
+}
+
+// src/http.ts
+import { timingSafeEqual } from "node:crypto";
+
+// src/cors.ts
+var DEV_ORIGIN = "http://localhost:3000";
+function resolveOrigins(configured, nodeEnv, productionOrigin) {
+  const origins = [...configured];
+  if (productionOrigin && !origins.includes(productionOrigin))
+    origins.push(productionOrigin);
+  if (nodeEnv !== "production" && !origins.includes(DEV_ORIGIN))
+    origins.push(DEV_ORIGIN);
+  return origins;
+}
+function corsHeaders(origins, requestOrigin) {
+  if (requestOrigin === undefined || !origins.includes(requestOrigin))
+    return {};
+  return { "Access-Control-Allow-Origin": requestOrigin, Vary: "Origin" };
+}
+function preflightHeaders(origins, requestOrigin) {
+  const base = corsHeaders(origins, requestOrigin);
+  if (Object.keys(base).length === 0)
+    return {};
+  return {
+    ...base,
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "content-type, authorization",
+    "Access-Control-Max-Age": "600",
+    "Access-Control-Allow-Private-Network": "true"
+  };
+}
+
+// src/context.ts
+function buildContext(question, stamp, nodes, edges, opts = {}) {
+  const lines = [];
+  const builtDate = stamp.builtAt.slice(0, 10);
+  lines.push(`# ${question}`, "");
+  lines.push(`built ${builtDate} · ${nodes.length} nodes`, "");
+  const groups = new Map;
+  for (const n of nodes) {
+    const key = n.community?.name ? n.community.name : "Ungrouped";
+    if (!groups.has(key))
+      groups.set(key, []);
+    groups.get(key).push(n);
+  }
+  const groupNames = [...groups.keys()].sort((a, b) => a === "Ungrouped" ? 1 : b === "Ungrouped" ? -1 : a.localeCompare(b));
+  for (const name of groupNames) {
+    lines.push(`## ${name}`);
+    const members = [...groups.get(name)].sort((a, b) => a.label.localeCompare(b.label) || a.id.localeCompare(b.id));
+    for (const n of members)
+      lines.push(`- ${n.label} — ${n.sourceFile}:${n.sourceLocation}`);
+    lines.push("");
+  }
+  if (edges.length > 0) {
+    const labelById = new Map(nodes.map((n) => [n.id, n.label]));
+    lines.push("## Relations");
+    for (const e of edges) {
+      const tag = e.confidence === "EXTRACTED" ? "" : ` [${e.confidence}]`;
+      lines.push(`- ${labelById.get(e.source) ?? e.source} —${e.relation}→ ${labelById.get(e.target) ?? e.target}${tag}`);
+    }
+    lines.push("");
+  }
+  if (opts.truncated) {
+    lines.push(`> Retrieval was truncated (${opts.truncated.reason}); ${opts.truncated.omittedCount} related nodes were omitted.`, "");
+  }
+  if (opts.degraded) {
+    lines.push("> Matched literally — no vocabulary expansion was applied to the question.", "");
+  }
+  while (lines.length > 0 && lines[lines.length - 1] === "")
+    lines.pop();
+  return lines.join(`
+`);
+}
+
+// src/footer.ts
+function isoDate(date) {
+  return date.toISOString().slice(0, 10);
+}
+function buildFooter(stamp, sources, opts = {}) {
+  const draftDate = opts.draftDate ?? isoDate(new Date);
+  const builtDate = stamp.builtAt.slice(0, 10);
+  const graphLine = stamp.headSha ? `Graph built ${builtDate} (${stamp.graphHash}) at commit ${stamp.headSha.slice(0, 7)}.` : `Graph built ${builtDate} (${stamp.graphHash}).`;
+  const noteClauses = [];
+  if (opts.truncated) {
+    noteClauses.push(`Retrieval was truncated (${opts.truncated.reason}); some related code may be missing.`);
+  }
+  if (opts.degraded) {
+    noteClauses.push("Retrieval matched literally; vocabulary was not expanded.");
+  }
+  const sortedSources = [...new Set(sources.map((s) => `${s.file}:${s.location}`))].sort();
+  const lines = [
+    "---",
+    `Drafted from the code graph on ${draftDate}.`,
+    graphLine,
+    ...noteClauses.length > 0 ? [noteClauses.join(" ")] : [],
+    "Sources:",
+    ...sortedSources.map((s) => `- ${s}`)
+  ];
+  return `
+` + lines.join(`
+`);
+}
+
+// src/traversal.ts
+function traverse(adjacency, allEdges, seedIds, depth, maxNodes) {
+  const kept = new Set;
+  const overflow = new Set;
+  let frontier = [];
+  for (const s of seedIds) {
+    if (kept.size < maxNodes) {
+      kept.add(s);
+      frontier.push(s);
+    } else {
+      overflow.add(s);
+    }
+  }
+  let d = 0;
+  for (;d < depth; d++) {
+    const candidates = [];
+    for (const id of frontier) {
+      for (const { other, edge } of adjacency.get(id) ?? []) {
+        if (!kept.has(other))
+          candidates.push({ other, weight: edge.weight ?? 1 });
+      }
+    }
+    candidates.sort((a, b) => b.weight - a.weight);
+    const next = [];
+    for (const c of candidates) {
+      if (kept.has(c.other))
+        continue;
+      if (kept.size >= maxNodes) {
+        overflow.add(c.other);
+        continue;
+      }
+      kept.add(c.other);
+      next.push(c.other);
+    }
+    frontier = next;
+    if (frontier.length === 0)
+      break;
+  }
+  let truncated = null;
+  if (overflow.size > 0) {
+    truncated = { reason: "maxNodes", omittedCount: overflow.size };
+  } else if (d === depth && frontier.length > 0) {
+    const beyond = new Set;
+    for (const id of frontier) {
+      for (const { other } of adjacency.get(id) ?? []) {
+        if (!kept.has(other))
+          beyond.add(other);
+      }
+    }
+    if (beyond.size > 0)
+      truncated = { reason: "depth", omittedCount: beyond.size };
+  }
+  const edges = allEdges.filter((e) => kept.has(e.source) && kept.has(e.target));
+  return { nodeIds: [...kept], edges, truncated };
+}
+
+// src/ops.ts
+var API_VERSION = "0.1.0";
+var CAPABILITIES = ["search", "query", "path", "node"];
+var MAX_NODES_CEILING = 1000;
+var MAX_DEPTH_CEILING = 3;
+var DEFAULT_DEPTH = 1;
+var DEFAULT_MAX_NODES = 60;
+var DEFAULT_SEED_COUNT = 5;
+var DEFAULT_SEARCH_LIMIT = 20;
+var MAX_SEARCH_LIMIT = 100;
+function status(index) {
+  return {
+    graph: index.stamp,
+    apiVersion: API_VERSION,
+    capabilities: [...CAPABILITIES],
+    limits: { maxNodes: MAX_NODES_CEILING, maxDepth: MAX_DEPTH_CEILING }
+  };
+}
+function search(index, req) {
+  const limit = Math.max(0, Math.min(req.limit ?? DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT));
+  const scored = scoreNodes(index.scoreIndex, terms(req.q)).slice(0, limit);
+  return {
+    graph: index.stamp,
+    results: scored.map((s) => ({ ...index.project(index.nodesById.get(s.id)), score: s.score }))
+  };
+}
+function query(index, req) {
+  const depth = Math.min(req.depth ?? DEFAULT_DEPTH, MAX_DEPTH_CEILING);
+  const maxNodes = Math.min(req.maxNodes ?? DEFAULT_MAX_NODES, MAX_NODES_CEILING);
+  const seedCount = Math.max(0, req.seeds ?? DEFAULT_SEED_COUNT);
+  const include = req.include ?? ["subgraph"];
+  const queryTerms = req.terms?.length ? req.terms.map((t) => t.toLowerCase()) : terms(req.question);
+  const degraded = req.terms?.length ? undefined : { expansion: "none" };
+  const scored = scoreNodes(index.scoreIndex, queryTerms);
+  const scoredById = new Map(scored.map((s) => [s.id, s]));
+  const seedIds = scored.slice(0, seedCount).map((s) => s.id);
+  const topScore = scored[0]?.score ?? 0;
+  const clearsFloor = seedIds.some((id) => scoredById.get(id)?.exact);
+  const lowConfidence = clearsFloor ? undefined : { topScore };
+  if (seedIds.length === 0) {
+    const empty = {
+      graph: index.stamp,
+      ...degraded ? { degraded } : {},
+      ...lowConfidence ? { lowConfidence } : {},
+      subgraph: { nodes: [], edges: [], seeds: [] }
+    };
+    if (include.includes("context")) {
+      empty.context = { markdown: buildContext(req.question, index.stamp, [], [], { degraded }), sources: [] };
+    }
+    if (include.includes("footer")) {
+      empty.footer = buildFooter(index.stamp, [], { degraded });
+    }
+    return empty;
+  }
+  const { nodeIds, edges: rawEdges, truncated } = traverse(index.adjacency, index.edges, seedIds, depth, maxNodes);
+  const nodes = nodeIds.map((id) => index.project(index.nodesById.get(id)));
+  const edges = rawEdges.map((e) => index.projectEdge(e));
+  const response = {
+    graph: index.stamp,
+    ...degraded ? { degraded } : {},
+    ...truncated ? { truncated } : {},
+    ...lowConfidence ? { lowConfidence } : {},
+    subgraph: { nodes, edges, seeds: seedIds }
+  };
+  if (include.includes("context")) {
+    response.context = {
+      markdown: buildContext(req.question, index.stamp, nodes, edges, { truncated: truncated ?? undefined, degraded }),
+      sources: sourcesFrom(nodes)
+    };
+  }
+  if (include.includes("footer")) {
+    response.footer = buildFooter(index.stamp, sourcesFrom(nodes), { truncated: truncated ?? undefined, degraded });
+  }
+  return response;
+}
+function sourcesFrom(nodes) {
+  const keys = [...new Set(nodes.map((n) => `${n.sourceFile}:${n.sourceLocation}`))].sort();
+  return keys.map((k) => {
+    const i = k.lastIndexOf(":");
+    return { file: k.slice(0, i), location: k.slice(i + 1) };
+  });
+}
+function path(index, req) {
+  const { from, to, maxDepth } = req;
+  if (!index.nodesById.has(from))
+    throw new OpError("not_found", `Unknown node id: ${from}`);
+  if (!index.nodesById.has(to))
+    throw new OpError("not_found", `Unknown node id: ${to}`);
+  if (from === to) {
+    return {
+      graph: index.stamp,
+      found: true,
+      nodes: [index.project(index.nodesById.get(from))],
+      edges: []
+    };
+  }
+  const cameFrom = new Map;
+  const depthOf = new Map([[from, 0]]);
+  const queue = [from];
+  let qi = 0;
+  let found = false;
+  outer:
+    while (qi < queue.length) {
+      const id = queue[qi++];
+      const d = depthOf.get(id);
+      if (maxDepth !== undefined && d >= maxDepth)
+        continue;
+      for (const { other, edge } of index.adjacency.get(id) ?? []) {
+        if (depthOf.has(other))
+          continue;
+        depthOf.set(other, d + 1);
+        cameFrom.set(other, { prev: id, edge });
+        if (other === to) {
+          found = true;
+          break outer;
+        }
+        queue.push(other);
+      }
+    }
+  if (!found)
+    return { graph: index.stamp, found: false, nodes: [], edges: [] };
+  const nodeIds = [to];
+  const rawEdges = [];
+  let cur = to;
+  while (cur !== from) {
+    const step = cameFrom.get(cur);
+    rawEdges.push(step.edge);
+    cur = step.prev;
+    nodeIds.push(cur);
+  }
+  nodeIds.reverse();
+  rawEdges.reverse();
+  return {
+    graph: index.stamp,
+    found: true,
+    nodes: nodeIds.map((id) => index.project(index.nodesById.get(id))),
+    edges: rawEdges.map((e) => index.projectEdge(e))
+  };
+}
+function node(index, req) {
+  const raw = index.nodesById.get(req.id);
+  if (!raw)
+    throw new OpError("not_found", `Unknown node id: ${req.id}`);
+  const neighbours = (index.adjacency.get(req.id) ?? []).map(({ other, edge }) => ({
+    node: index.project(index.nodesById.get(other)),
+    edge: index.projectEdge(edge)
+  }));
+  return { graph: index.stamp, node: index.project(raw), neighbours };
+}
+
+// src/http.ts
+var ERROR_STATUS = {
+  [ERROR_CODES.unauthorized]: 401,
+  [ERROR_CODES.notFound]: 404,
+  [ERROR_CODES.graphUnreadable]: 409,
+  [ERROR_CODES.invalidRequest]: 422,
+  [ERROR_CODES.graphLoading]: 503
+};
+function createHandler(opts) {
+  return async (req) => {
+    const url = new URL(req.url);
+    const origin = req.headers.get("origin") ?? undefined;
+    if (req.method === "OPTIONS") {
+      return new Response(null, { status: 204, headers: preflightHeaders(opts.origins, origin) });
+    }
+    const cors = corsHeaders(opts.origins, origin);
+    try {
+      const body = await dispatch(req, url, opts);
+      return jsonResponse(200, body, cors);
+    } catch (err) {
+      if (err instanceof OpError)
+        return jsonResponse(ERROR_STATUS[err.code], errorBody(err), cors);
+      return jsonResponse(500, { error: { code: "internal_error", message: "Internal server error" } }, cors);
+    }
+  };
+}
+async function dispatch(req, url, opts) {
+  const { pathname } = url;
+  const method = req.method;
+  if (method === "GET" && pathname === "/v1/ping")
+    return { ok: true, apiVersion: API_VERSION };
+  requireAuth(req, opts.token);
+  const index = requireGraph(opts.getGraphState());
+  if (method === "GET" && pathname === "/v1/status")
+    return status(index);
+  if (method === "POST" && pathname === "/v1/search")
+    return search(index, parseSearchRequest(await readJsonBody(req)));
+  if (method === "POST" && pathname === "/v1/query")
+    return query(index, parseQueryRequest(await readJsonBody(req)));
+  if (method === "POST" && pathname === "/v1/path")
+    return path(index, parsePathRequest(await readJsonBody(req)));
+  if (method === "GET" && pathname.startsWith("/v1/node/")) {
+    return node(index, { id: decodeNodeId(pathname.slice("/v1/node/".length)) });
+  }
+  throw new OpError("not_found", `No such route: ${method} ${pathname}`);
+}
+function decodeNodeId(raw) {
+  let id;
+  try {
+    id = decodeURIComponent(raw);
+  } catch {
+    throw new OpError("invalid_request", "Malformed node id");
+  }
+  if (!id)
+    throw new OpError("not_found", "Missing node id");
+  return id;
+}
+function requireAuth(req, token) {
+  const header = req.headers.get("authorization");
+  const provided = header?.startsWith("Bearer ") ? header.slice("Bearer ".length) : undefined;
+  if (!provided || !safeEqual(provided, token))
+    throw new OpError("unauthorized", "Missing or invalid bearer token");
+}
+function safeEqual(a, b) {
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  return bufA.length === bufB.length && timingSafeEqual(bufA, bufB);
+}
+function requireGraph(state) {
+  if (state.kind === "loading")
+    throw new OpError("graph_loading", "Graph not yet loaded");
+  if (state.kind === "error")
+    throw state.error;
+  return state.index;
+}
+async function readJsonBody(req) {
+  let parsed;
+  try {
+    parsed = await req.json();
+  } catch {
+    throw new OpError("invalid_request", "Request body must be valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new OpError("invalid_request", "Request body must be a JSON object");
+  }
+  return parsed;
+}
+function requireString(body, key) {
+  const v = body[key];
+  if (typeof v !== "string" || v.length === 0)
+    throw new OpError("invalid_request", `"${key}" must be a non-empty string`);
+  return v;
+}
+function optionalCount(body, key) {
+  const v = body[key];
+  if (v === undefined)
+    return;
+  if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
+    throw new OpError("invalid_request", `"${key}" must be a non-negative integer`);
+  }
+  return v;
+}
+function optionalStringArray(body, key) {
+  const v = body[key];
+  if (v === undefined)
+    return;
+  if (!Array.isArray(v) || !v.every((x) => typeof x === "string")) {
+    throw new OpError("invalid_request", `"${key}" must be an array of strings`);
+  }
+  return v;
+}
+var INCLUDE_VALUES = new Set(["subgraph", "context", "footer"]);
+function optionalInclude(body) {
+  const v = body.include;
+  if (v === undefined)
+    return;
+  if (!Array.isArray(v) || !v.every((x) => typeof x === "string" && INCLUDE_VALUES.has(x))) {
+    throw new OpError("invalid_request", '"include" must be an array of "subgraph" | "context" | "footer"');
+  }
+  return v;
+}
+function parseSearchRequest(body) {
+  return { q: requireString(body, "q"), limit: optionalCount(body, "limit") };
+}
+function parseQueryRequest(body) {
+  return {
+    question: requireString(body, "question"),
+    terms: optionalStringArray(body, "terms"),
+    depth: optionalCount(body, "depth"),
+    maxNodes: optionalCount(body, "maxNodes"),
+    seeds: optionalCount(body, "seeds"),
+    include: optionalInclude(body)
+  };
+}
+function parsePathRequest(body) {
+  return { from: requireString(body, "from"), to: requireString(body, "to"), maxDepth: optionalCount(body, "maxDepth") };
+}
+function errorBody(err) {
+  const detail = err.detail instanceof Error ? { name: err.detail.name, message: err.detail.message } : err.detail;
+  return { error: { code: err.code, message: err.message, ...detail !== undefined ? { detail } : {} } };
+}
+function jsonResponse(statusCode, body, cors) {
+  return new Response(JSON.stringify(body), { status: statusCode, headers: { "Content-Type": "application/json", ...cors } });
+}
+
+// src/net.ts
+import { createServer } from "node:http";
+function detectRuntime() {
+  return typeof Bun !== "undefined" ? "bun" : "node";
+}
+function startServer(opts, runtime = detectRuntime()) {
+  return runtime === "bun" ? Bun.serve(opts) : startNodeServer(opts);
+}
+function startNodeServer(opts) {
+  if (opts.port === 0) {
+    throw new Error("net.startNodeServer: a dynamic port (0) is not supported on the Node fallback — pass a fixed port");
+  }
+  const server = createServer((req, res) => {
+    res.on("error", () => {});
+    handleRequest(req, res, opts.fetch);
+  });
+  server.listen(opts.port, opts.hostname);
+  return {
+    hostname: opts.hostname,
+    port: opts.port,
+    stop(closeActiveConnections) {
+      if (closeActiveConnections)
+        server.closeAllConnections?.();
+      server.close();
+    }
+  };
+}
+async function handleRequest(req, res, fetch) {
+  try {
+    const request = await toWebRequest(req);
+    const response = await fetch(request);
+    res.statusCode = response.status;
+    response.headers.forEach((value, key) => res.setHeader(key, value));
+    res.end(Buffer.from(await response.arrayBuffer()));
+  } catch {
+    if (res.headersSent || res.writableEnded)
+      return;
+    res.statusCode = 500;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ error: { code: "internal_error", message: "Internal server error" } }));
+  }
+}
+async function toWebRequest(req) {
+  const url = `http://${req.headers.host ?? "127.0.0.1"}${req.url ?? "/"}`;
+  const headers = new Headers;
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === undefined)
+      continue;
+    if (Array.isArray(value))
+      for (const v of value)
+        headers.append(key, v);
+    else
+      headers.set(key, value);
+  }
+  const hasBody = req.method !== "GET" && req.method !== "HEAD";
+  let body;
+  if (hasBody) {
+    const chunks = [];
+    for await (const chunk of req)
+      chunks.push(chunk);
+    body = Buffer.concat(chunks);
+  }
+  return new Request(url, { method: req.method, headers, body });
+}
+
+// src/pairing.ts
+import { mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname, join } from "node:path";
+function pairingFilePath(checkoutPath) {
+  return join(checkoutPath, ".notex", "companion.json");
+}
+function generateToken() {
+  return randomBytes(32).toString("base64url");
+}
+function readExistingToken(path2) {
+  try {
+    const parsed = JSON.parse(readFileSync2(path2, "utf8"));
+    return typeof parsed.token === "string" ? parsed.token : undefined;
+  } catch {
+    return;
+  }
+}
+function tokenContents(token) {
+  return JSON.stringify({ token }, null, 2);
+}
+function createTokenFileExclusive(path2, token) {
+  mkdirSync(dirname(path2), { recursive: true });
+  writeFileSync(path2, tokenContents(token), { mode: 384, flag: "wx" });
+}
+function rewriteTokenFile(path2, token) {
+  mkdirSync(dirname(path2), { recursive: true });
+  const tmpPath = `${path2}.${process.pid}.tmp`;
+  writeFileSync(tmpPath, tokenContents(token), { mode: 384, flag: "wx" });
+  renameSync(tmpPath, path2);
+}
+function loadOrCreateToken(checkoutPath, opts = {}) {
+  const path2 = pairingFilePath(checkoutPath);
+  if (opts.rotate) {
+    const token2 = generateToken();
+    rewriteTokenFile(path2, token2);
+    return token2;
+  }
+  const existing = readExistingToken(path2);
+  if (existing !== undefined)
+    return existing;
+  const token = generateToken();
+  try {
+    createTokenFileExclusive(path2, token);
+    return token;
+  } catch (err) {
+    if (err.code !== "EEXIST")
+      throw err;
+    const winner = readExistingToken(path2);
+    if (winner !== undefined)
+      return winner;
+    rewriteTokenFile(path2, token);
+    return token;
+  }
+}
+function pairingLine(baseUrl, token) {
+  return `${baseUrl}/#token=${token}`;
+}
+
+// src/serve.ts
+var DEFAULT_PORT = 7717;
+function serve(opts) {
+  const origins = resolveOrigins(opts.origins ?? [], opts.nodeEnv ?? "development", process.env.VITE_APP_URL);
+  const token = loadOrCreateToken(opts.checkoutPath, { rotate: opts.rotateToken });
+  let graphState = { kind: "loading" };
+  const handler = createHandler({ token, origins, getGraphState: () => graphState });
+  const server = startServer({
+    hostname: "127.0.0.1",
+    port: opts.port ?? DEFAULT_PORT,
+    fetch: handler
+  });
+  queueMicrotask(() => {
+    try {
+      graphState = { kind: "ready", index: loadGraph(opts.checkoutPath) };
+    } catch (err) {
+      graphState = { kind: "error", error: err instanceof OpError ? err : new OpError("graph_unreadable", String(err)) };
+    }
+    opts.onGraphState?.(graphState);
+  });
+  const baseUrl = `http://127.0.0.1:${server.port}`;
+  return { server, token, baseUrl, pairingLine: pairingLine(baseUrl, token) };
+}
+
+// src/mcp.ts
+function startMcpStub() {
+  console.error("notex-companion mcp: stdio server not yet implemented — see TBR-69");
+  process.stdin.resume();
+}
+
+// src/cli.ts
+var HELP = `notex-companion — local retrieval companion over a checkout's graphify-out/graph.json
+
+Usage:
+  notex-companion [serve] [options]   Start the loopback HTTP server (default command)
+  notex-companion mcp                 Start the stdio MCP server
+
+Options for serve:
+  --port <n>       Port to bind (default 7717)
+  --origin <url>   Additional allowed CORS origin, beyond the built-in defaults. Repeatable.
+  --rotate-token   Generate a new pairing token, invalidating the old one
+  -h, --help       Show this message
+`;
+
+class CliUsageError extends Error {
+}
+function parseServeArgs(args) {
+  const origins = [];
+  let port;
+  let rotateToken = false;
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--port": {
+        const value = args[++i];
+        const parsed = value === undefined ? NaN : Number(value);
+        if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+          throw new CliUsageError(`--port needs an integer between 0 and 65535, got ${value ?? "(nothing)"}`);
+        }
+        port = parsed;
+        break;
+      }
+      case "--origin": {
+        const value = args[++i];
+        if (!value)
+          throw new CliUsageError("--origin needs a value");
+        origins.push(value);
+        break;
+      }
+      case "--rotate-token":
+        rotateToken = true;
+        break;
+      default:
+        throw new CliUsageError(`unrecognised option "${arg}"`);
+    }
+  }
+  return { port, origins, rotateToken };
+}
+function runServe(args) {
+  const { port, origins, rotateToken } = parseServeArgs(args);
+  const checkoutPath = process.cwd();
+  const graphPath = resolve2(checkoutPath, "graphify-out/graph.json");
+  if (!existsSync(graphPath)) {
+    console.error(`notex-companion: no graphify-out/graph.json found in ${checkoutPath}
+` + `Generate a graph for this checkout before running notex-companion.`);
+    process.exit(1);
+  }
+  const handle = serve({
+    checkoutPath,
+    port,
+    origins,
+    rotateToken,
+    onGraphState: (state) => {
+      if (state.kind === "ready") {
+        const { stamp } = state.index;
+        console.log(`graph: ${stamp.nodeCount} nodes, ${stamp.edgeCount} edges, ${stamp.communityCount} communities (built ${stamp.builtAt})`);
+      } else if (state.kind === "error") {
+        console.error(`notex-companion: graph.json could not be read: ${state.error.message}`);
+      }
+    }
+  });
+  console.log(`notex-companion serving ${checkoutPath}`);
+  console.log(handle.pairingLine);
+}
+function main(argv = process.argv.slice(2)) {
+  const [command, ...rest] = argv;
+  if (command === "-h" || command === "--help") {
+    console.log(HELP);
+    return;
+  }
+  try {
+    if (command === "mcp") {
+      startMcpStub();
+    } else if (command === undefined || command === "serve" || command.startsWith("-")) {
+      runServe(command === "serve" ? rest : argv);
+    } else {
+      throw new CliUsageError(`unknown command "${command}"`);
+    }
+  } catch (err) {
+    if (err instanceof CliUsageError) {
+      console.error(`notex-companion: ${err.message}
+
+${HELP}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+// src/bin.ts
+main();