@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/src/knowledge/retrieval/graph-builder.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// graph-builder.mjs — Builds a knowledge graph from forward links and backlinks.
+//
+// Reads forward links from markdown files + backlinks from .backlinks.json.
+// Output: operator/knowledge/.graph.json
+//
+// CLI: node graph-builder.mjs [--root /path/to/repo]
+
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve, dirname, relative, normalize } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = resolve(__dirname, '../../../..');
+
+const USAGE = `
+graph-builder — Build a knowledge graph from markdown links and backlinks
+
+Usage:
+  node graph-builder.mjs [options]
+
+Options:
+  --root <path>    Repository root (default: 4 levels up from this script)
+  --help, -h       Show this help
+
+Reads forward links from .md files in operator/knowledge/ and core/knowledge/.
+Reads backlinks from operator/knowledge/.backlinks.json.
+
+Output: operator/knowledge/.graph.json
+`.trim();
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+async function walkDir(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return results;
+    throw err;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith('.')) continue;
+      results.push(...await walkDir(full));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function extractTitle(content) {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : null;
+}
+
+function extractForwardLinks(content, sourcePath, repoRoot) {
+  const links = [];
+  const sourceDir = dirname(sourcePath);
+
+  // Wiki-style: [[target]]
+  const wikiRe = /\[\[([^\]]+)\]\]/g;
+  let m;
+  while ((m = wikiRe.exec(content)) !== null) {
+    let target = m[1].trim();
+    if (!target.endsWith('.md')) target += '.md';
+    links.push(normalize(target));
+  }
+
+  // Markdown-style: [text](relative/path.md)
+  const mdRe = /\[([^\]]*)\]\(([^)]+)\)/g;
+  while ((m = mdRe.exec(content)) !== null) {
+    const href = m[2].trim();
+    if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('#') || href.startsWith('mailto:')) continue;
+    const path = href.split('#')[0];
+    if (!path || !path.endsWith('.md')) continue;
+    const abs = resolve(sourceDir, path);
+    const rel = relative(repoRoot, abs);
+    links.push(normalize(rel));
+  }
+
+  return [...new Set(links)];
+}
+
+function deriveDomain(relPath) {
+  const parts = relPath.split('/');
+  if (parts.length >= 3 && (parts[0] === 'operator' || parts[0] === 'core') && parts[1] === 'knowledge') {
+    return parts[2];
+  }
+  return null;
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+
+async function main(args) {
+  let root = DEFAULT_ROOT;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') {
+      console.log(USAGE);
+      return 0;
+    }
+    if (a === '--root') {
+      root = resolve(args[++i]);
+    }
+  }
+
+  const scanDirs = [
+    join(root, 'operator', 'knowledge'),
+    join(root, 'core', 'knowledge'),
+  ];
+
+  const allFiles = [];
+  for (const dir of scanDirs) {
+    allFiles.push(...await walkDir(dir));
+  }
+
+  const nodesMap = new Map();
+  const edges = [];
+  const edgeSet = new Set();
+
+  for (const filePath of allFiles) {
+    const content = await readFile(filePath, 'utf8');
+    const relPath = relative(root, filePath);
+    const title = extractTitle(content) || relPath.split('/').pop().replace('.md', '');
+    const domain = deriveDomain(relPath);
+
+    nodesMap.set(relPath, { id: relPath, title, domain });
+
+    const forwardLinks = extractForwardLinks(content, filePath, root);
+    for (const target of forwardLinks) {
+      const edgeKey = `link:${relPath}->${target}`;
+      if (!edgeSet.has(edgeKey)) {
+        edgeSet.add(edgeKey);
+        edges.push({ from: relPath, to: target, type: 'link' });
+      }
+    }
+  }
+
+  // Read backlinks and add backlink edges
+  const backlinksPath = join(root, 'operator', 'knowledge', '.backlinks.json');
+  try {
+    const raw = await readFile(backlinksPath, 'utf8');
+    const backlinksData = JSON.parse(raw);
+    const bl = backlinksData.backlinks || {};
+    for (const [target, sources] of Object.entries(bl)) {
+      for (const source of sources) {
+        const edgeKey = `backlink:${target}->${source}`;
+        if (!edgeSet.has(edgeKey)) {
+          edgeSet.add(edgeKey);
+          edges.push({ from: target, to: source, type: 'backlink' });
+        }
+        if (!nodesMap.has(target)) {
+          nodesMap.set(target, { id: target, title: target.split('/').pop().replace('.md', ''), domain: deriveDomain(target) });
+        }
+        if (!nodesMap.has(source)) {
+          nodesMap.set(source, { id: source, title: source.split('/').pop().replace('.md', ''), domain: deriveDomain(source) });
+        }
+      }
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    console.warn('No .backlinks.json found — run backlink-indexer.mjs first. Building graph from forward links only.');
+  }
+
+  const nodes = [...nodesMap.values()].sort((a, b) => a.id.localeCompare(b.id));
+
+  const output = {
+    version: '1.0',
+    generatedAt: new Date().toISOString(),
+    nodes,
+    edges,
+  };
+
+  const outPath = join(root, 'operator', 'knowledge', '.graph.json');
+  await writeFile(outPath, JSON.stringify(output, null, 2) + '\n', 'utf8');
+  console.log(`Wrote ${outPath} (${nodes.length} nodes, ${edges.length} edges)`);
+  return 0;
+}
+
+const exitCode = await main(process.argv.slice(2));
+process.exit(exitCode ?? 0);

package/dist/engineering-pa-core/src/knowledge/retrieval/index-builder.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// index-builder.mjs — Builds a domain index from operator/knowledge/ directories.
+//
+// Walks top-level directories under operator/knowledge/, extracts metadata
+// from each domain's README.md, and outputs operator/knowledge/domains.json.
+//
+// CLI: node index-builder.mjs [--root /path/to/repo]
+
+import { readdir, readFile, writeFile, stat } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = process.env.DAVE_ROOT
+  ? resolve(process.env.DAVE_ROOT)
+  : resolve(__dirname, '../../../..');
+
+const USAGE = `
+index-builder — Build a domain index from operator knowledge directories
+
+Usage:
+  node index-builder.mjs [options]
+
+Options:
+  --root <path>    Repository root (default: $DAVE_ROOT if set, else 4 levels up from this script)
+  --help, -h       Show this help
+
+Walks top-level directories under operator/knowledge/.
+Extracts domain metadata from each directory's README.md (first paragraph).
+
+Output: operator/knowledge/domains.json
+`.trim();
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function slugToName(slug) {
+  return slug
+    .split('-')
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+function extractFirstParagraph(content) {
+  const lines = stripFrontMatter(content).split('\n');
+  let collecting = false;
+  const para = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('#')) {
+      if (collecting) break;
+      continue;
+    }
+    if (trimmed === '') {
+      if (collecting) break;
+      continue;
+    }
+    collecting = true;
+    para.push(trimmed);
+  }
+  return para.join(' ') || null;
+}
+
+// Parses a leading `---`-delimited YAML front-matter block. Only supports
+// the flat `key: value` pairs we need (displayName primarily). Returns an
+// object of parsed keys (string values) or {} when no front-matter is
+// present or parsing fails.
+//
+// We deliberately DO NOT pull in a YAML dependency — the platform is
+// zero-dep by policy, and domain READMEs only need a handful of scalar
+// fields. A strict line-based parser is both sufficient and auditable.
+export function parseFrontMatter(content) {
+  if (typeof content !== 'string') return {};
+  if (!content.startsWith('---')) return {};
+  const lines = content.split(/\r?\n/);
+  if (lines[0].trim() !== '---') return {};
+  const out = {};
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '---') return out;
+    const m = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line);
+    if (!m) continue;
+    let value = m[2].trim();
+    // Strip matching quotes.
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    out[m[1]] = value;
+  }
+  // Unterminated front-matter — treat as no front-matter so the body
+  // parses as written.
+  return {};
+}
+
+// Returns `content` with the leading `---`-delimited front-matter block
+// removed. If there's no front-matter, returns the content unchanged.
+export function stripFrontMatter(content) {
+  if (typeof content !== 'string') return '';
+  if (!content.startsWith('---')) return content;
+  const lines = content.split(/\r?\n/);
+  if (lines[0].trim() !== '---') return content;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      return lines.slice(i + 1).join('\n');
+    }
+  }
+  return content;
+}
+
+async function countMdFiles(dir) {
+  let count = 0;
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory() && !entry.name.startsWith('.')) {
+      count += await countMdFiles(full);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      count++;
+    }
+  }
+  return count;
+}
+
+async function getLatestMtime(dir) {
+  let latest = new Date(0);
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory() && !entry.name.startsWith('.')) {
+      const sub = await getLatestMtime(full);
+      if (sub > latest) latest = sub;
+    } else if (entry.isFile()) {
+      const s = await stat(full);
+      if (s.mtime > latest) latest = s.mtime;
+    }
+  }
+  return latest;
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+
+async function main(args) {
+  let root = DEFAULT_ROOT;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') {
+      console.log(USAGE);
+      return 0;
+    }
+    if (a === '--root') {
+      root = resolve(args[++i]);
+    }
+  }
+
+  const knowledgeDir = join(root, 'operator', 'knowledge');
+  let entries;
+  try {
+    entries = await readdir(knowledgeDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      console.error(`Knowledge directory not found: ${knowledgeDir}`);
+      return 1;
+    }
+    throw err;
+  }
+
+  const domains = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.')) continue;
+
+    const domainPath = join(knowledgeDir, entry.name);
+    const id = entry.name;
+    const name = slugToName(id);
+    const relPath = `operator/knowledge/${id}`;
+
+    let description = null;
+    let displayName = null;
+    try {
+      const readme = await readFile(join(domainPath, 'README.md'), 'utf8');
+      const fm = parseFrontMatter(readme);
+      if (fm && typeof fm.displayName === 'string' && fm.displayName.length) {
+        displayName = fm.displayName;
+      }
+      description = extractFirstParagraph(readme);
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+
+    const fileCount = await countMdFiles(domainPath);
+    const lastUpdated = await getLatestMtime(domainPath);
+
+    // displayName is emitted only when explicitly set in front-matter.
+    // Consumers fall back to `name` (capitalised id) when absent — this
+    // keeps the field optional and the downstream schema additive.
+    const record = {
+      id,
+      name,
+      path: relPath,
+      description,
+      fileCount,
+      lastUpdated: lastUpdated.toISOString(),
+    };
+    if (displayName) record.displayName = displayName;
+    domains.push(record);
+  }
+
+  domains.sort((a, b) => a.id.localeCompare(b.id));
+
+  const output = {
+    version: '1.0',
+    generatedAt: new Date().toISOString(),
+    domains,
+  };
+
+  const outPath = join(knowledgeDir, 'domains.json');
+  await writeFile(outPath, JSON.stringify(output, null, 2) + '\n', 'utf8');
+  console.log(`Wrote ${outPath} (${domains.length} domains indexed)`);
+  return 0;
+}
+
+const exitCode = await main(process.argv.slice(2));
+process.exit(exitCode ?? 0);

package/dist/engineering-pa-core/src/knowledge/retrieval/query.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+// query.mjs — Knowledge graph query functions and CLI.
+//
+// Exports:
+//   findRelated(path, root)          — files linked to/from the given path
+//   getBacklinks(path, root)         — files that link TO the given path
+//   traverseFrom(path, depth, root)  — BFS traversal, reachable nodes within depth
+//   searchByDomain(domain, root)     — all files in a domain
+//
+// CLI:
+//   node query.mjs backlinks <path>
+//   node query.mjs related <path>
+//   node query.mjs traverse <path> [depth]
+//   node query.mjs domain <name>
+
+import { readFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { join, resolve, dirname, normalize } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = resolve(__dirname, '../../../..');
+
+const USAGE = `
+query — Query the knowledge graph
+
+Usage:
+  node query.mjs <command> [args]
+
+Commands:
+  backlinks <path>          Files that link TO the given path
+  related <path>            Files linked to/from the given path (forward + back)
+  traverse <path> [depth]   BFS traversal from a node (default depth: 2)
+  domain <name>             All files in a domain
+
+Options:
+  --root <path>             Repository root (default: 4 levels up from this script)
+  --help, -h                Show this help
+
+Reads from:
+  operator/knowledge/.backlinks.json
+  operator/knowledge/.graph.json
+  operator/knowledge/domains.json
+`.trim();
+
+// ── Index readers ───────────────────────────────────────────────────
+
+async function readBacklinks(root) {
+  const path = join(root, 'operator', 'knowledge', '.backlinks.json');
+  try {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') return { backlinks: {} };
+    throw err;
+  }
+}
+
+async function readGraph(root) {
+  const path = join(root, 'operator', 'knowledge', '.graph.json');
+  try {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') return { nodes: [], edges: [] };
+    throw err;
+  }
+}
+
+async function readDomains(root) {
+  const path = join(root, 'operator', 'knowledge', 'domains.json');
+  try {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') return { domains: [] };
+    throw err;
+  }
+}
+
+// ── Exported query functions ────────────────────────────────────────
+
+export async function findRelated(path, root = DEFAULT_ROOT) {
+  const normPath = normalize(path);
+  const graph = await readGraph(root);
+  const related = new Set();
+
+  for (const edge of graph.edges) {
+    if (normalize(edge.from) === normPath) related.add(edge.to);
+    if (normalize(edge.to) === normPath) related.add(edge.from);
+  }
+
+  return [...related].sort();
+}
+
+export async function getBacklinks(path, root = DEFAULT_ROOT) {
+  const normPath = normalize(path);
+  const data = await readBacklinks(root);
+  const bl = data.backlinks || {};
+
+  for (const [target, sources] of Object.entries(bl)) {
+    if (normalize(target) === normPath) {
+      return [...sources].sort();
+    }
+  }
+
+  return [];
+}
+
+export async function traverseFrom(path, depth = 2, root = DEFAULT_ROOT) {
+  const normPath = normalize(path);
+  const graph = await readGraph(root);
+
+  // Build adjacency list from all edges (undirected traversal)
+  const adj = new Map();
+  for (const edge of graph.edges) {
+    const from = normalize(edge.from);
+    const to = normalize(edge.to);
+    if (!adj.has(from)) adj.set(from, new Set());
+    if (!adj.has(to)) adj.set(to, new Set());
+    adj.get(from).add(to);
+    adj.get(to).add(from);
+  }
+
+  // BFS
+  const visited = new Set([normPath]);
+  let frontier = [normPath];
+
+  for (let d = 0; d < depth && frontier.length > 0; d++) {
+    const nextFrontier = [];
+    for (const node of frontier) {
+      const neighbours = adj.get(node) || new Set();
+      for (const n of neighbours) {
+        if (!visited.has(n)) {
+          visited.add(n);
+          nextFrontier.push(n);
+        }
+      }
+    }
+    frontier = nextFrontier;
+  }
+
+  visited.delete(normPath);
+  return [...visited].sort();
+}
+
+export async function searchByDomain(domain, root = DEFAULT_ROOT) {
+  const graph = await readGraph(root);
+  return graph.nodes
+    .filter((n) => n.domain === domain)
+    .map((n) => n.id)
+    .sort();
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────
+
+async function main(args) {
+  let root = DEFAULT_ROOT;
+
+  const filtered = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--root') {
+      root = resolve(args[++i]);
+    } else {
+      filtered.push(args[i]);
+    }
+  }
+
+  if (!filtered.length || filtered[0] === '--help' || filtered[0] === '-h') {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const cmd = filtered[0];
+
+  if (cmd === 'backlinks') {
+    const target = filtered[1];
+    if (!target) {
+      console.error('Usage: query.mjs backlinks <path>');
+      return 1;
+    }
+    const results = await getBacklinks(target, root);
+    if (!results.length) {
+      console.log('No backlinks found.');
+    } else {
+      for (const r of results) console.log(r);
+    }
+    return 0;
+  }
+
+  if (cmd === 'related') {
+    const target = filtered[1];
+    if (!target) {
+      console.error('Usage: query.mjs related <path>');
+      return 1;
+    }
+    const results = await findRelated(target, root);
+    if (!results.length) {
+      console.log('No related files found.');
+    } else {
+      for (const r of results) console.log(r);
+    }
+    return 0;
+  }
+
+  if (cmd === 'traverse') {
+    const target = filtered[1];
+    if (!target) {
+      console.error('Usage: query.mjs traverse <path> [depth]');
+      return 1;
+    }
+    const depth = parseInt(filtered[2], 10) || 2;
+    const results = await traverseFrom(target, depth, root);
+    if (!results.length) {
+      console.log('No reachable nodes found.');
+    } else {
+      for (const r of results) console.log(r);
+    }
+    return 0;
+  }
+
+  if (cmd === 'domain') {
+    const name = filtered[1];
+    if (!name) {
+      console.error('Usage: query.mjs domain <name>');
+      return 1;
+    }
+    const results = await searchByDomain(name, root);
+    if (!results.length) {
+      console.log('No files found in domain.');
+    } else {
+      for (const r of results) console.log(r);
+    }
+    return 0;
+  }
+
+  console.error(`Unknown command: ${cmd}`);
+  console.error('Run `node query.mjs --help` for usage.');
+  return 1;
+}
+
+// ISMAIN-AUDIT (bug-3 sweep): path.resolve() normalises path segments but
+// does not dereference symlinks, so this had the same class of fragility
+// as the endsWith idiom fixed elsewhere in the scheduler — an argv[1]
+// reached via a symlinked path (pnpm .bin shim, workspace link) would not
+// equal the realpath-resolved import.meta.url. This file is not currently
+// registered as a package `bin` (only invoked directly via `node
+// .../query.mjs` per its own usage docs), so it is not proven to fire in
+// production, but is fixed defensively to match the robust pattern used
+// across the repo.
+function isDirectlyInvoked() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectlyInvoked()) {
+  const exitCode = await main(process.argv.slice(2));
+  process.exit(exitCode ?? 0);
+}