@booklib/core 2.0.0

package/lib/engine/corrections.js

@@ -0,0 +1,198 @@
+// lib/engine/corrections.js
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { pipeline } from '@huggingface/transformers';
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+export const LEVEL_THRESHOLDS = [
+  { level: 4, min: 10 },
+  { level: 3, min: 5 },
+  { level: 2, min: 3 },
+  { level: 1, min: 1 },
+];
+
+const DEDUP_THRESHOLD = 0.85;
+const MAX_INJECTED    = 20;
+
+export const MARKER_START = '<!-- booklib-learned-start -->';
+export const MARKER_END   = '<!-- booklib-learned-end -->';
+
+// ── Embedding model (lazy-loaded, module-level singleton) ────────────────────
+
+let _extractor = null;
+
+async function _getEmbedding(text) {
+  if (!_extractor) {
+    _extractor = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+  }
+  const output = await _extractor(text, { pooling: 'mean', normalize: true });
+  return Array.from(output.data);
+}
+
+// ── Pure functions ────────────────────────────────────────────────────────────
+
+export function levelFromMentions(n) {
+  for (const { level, min } of LEVEL_THRESHOLDS) {
+    if (n >= min) return level;
+  }
+  return 1;
+}
+
+export function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na  += a[i] * a[i];
+    nb  += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+function _generateId() {
+  return randomUUID().replace(/-/g, '').slice(0, 8);
+}
+
+function _escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ── File paths ────────────────────────────────────────────────────────────────
+
+function _correctionsPath(home) {
+  return path.join(home, '.booklib', 'corrections.jsonl');
+}
+
+function _claudeMdPath(home) {
+  return path.join(home, '.claude', 'CLAUDE.md');
+}
+
+// ── Storage ───────────────────────────────────────────────────────────────────
+
+export function loadCorrections(home = os.homedir()) {
+  const p = _correctionsPath(home);
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .reduce((acc, line) => {
+      try {
+        acc.push(JSON.parse(line));
+      } catch {
+        process.stderr.write(`Warning: skipping corrupt line in corrections.jsonl: ${line.slice(0, 40)}\n`);
+      }
+      return acc;
+    }, []);
+}
+
+function _saveCorrections(corrections, home) {
+  const p = _correctionsPath(home);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const lines = corrections.map(c => JSON.stringify(c)).join('\n');
+  fs.writeFileSync(p, corrections.length ? lines + '\n' : '');
+}
+
+// ── CLAUDE.md injection ────────────────────────────────────────────────────────
+
+export function rebuildLearnedSection(home = os.homedir()) {
+  const corrections = loadCorrections(home);
+  const active = corrections
+    .filter(c => c.level >= 3)
+    .sort((a, b) => b.mentions - a.mentions)
+    .slice(0, MAX_INJECTED);
+
+  const claudeFile = _claudeMdPath(home);
+  fs.mkdirSync(path.dirname(claudeFile), { recursive: true });
+
+  let existing = '';
+  try { existing = fs.readFileSync(claudeFile, 'utf8'); } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  if (active.length === 0) {
+    const re = new RegExp(
+      `\\n?${_escapeRegex(MARKER_START)}[\\s\\S]*?${_escapeRegex(MARKER_END)}\\n?`
+    );
+    const updated = existing.replace(re, '').trimEnd();
+    fs.writeFileSync(claudeFile, updated ? updated + '\n' : '');
+    return;
+  }
+
+  const bullets = active.map(c => `- ${c.text.slice(0, 120)}`).join('\n');
+  const section = [
+    MARKER_START,
+    '## Learned Corrections (BookLib)',
+    '',
+    '> When the user corrects your approach, run: booklib correction add "brief rule"',
+    '',
+    bullets,
+    '',
+    MARKER_END,
+  ].join('\n');
+
+  const re = new RegExp(
+    `${_escapeRegex(MARKER_START)}[\\s\\S]*?${_escapeRegex(MARKER_END)}`
+  );
+  const updated = existing.includes(MARKER_START)
+    ? existing.replace(re, section)
+    : (existing.trimEnd() ? `${existing.trimEnd()}\n\n${section}\n` : `${section}\n`);
+
+  fs.writeFileSync(claudeFile, updated);
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+export function listCorrections(home = os.homedir()) {
+  return loadCorrections(home).sort((a, b) => b.mentions - a.mentions);
+}
+
+export function removeCorrection(id, home = os.homedir()) {
+  const corrections = loadCorrections(home);
+  const idx = corrections.findIndex(c => c.id === id);
+  if (idx === -1) return null;
+  const [removed] = corrections.splice(idx, 1);
+  _saveCorrections(corrections, home);
+  if (removed.level >= 3) rebuildLearnedSection(home);
+  return removed;
+}
+
+export async function addCorrection(text, home = os.homedir(), embedFn = _getEmbedding) {
+  const corrections = loadCorrections(home);
+  const now = new Date().toISOString();
+  const newVec = await embedFn(text);
+
+  for (const c of corrections) {
+    const existVec = c.embedding ?? await embedFn(c.text);
+    if (!c.embedding) c.embedding = existVec; // backfill on first encounter
+    const sim = cosine(newVec, existVec);
+    if (sim >= DEDUP_THRESHOLD) {
+      const oldLevel = c.level;
+      c.mentions += 1;
+      c.level = levelFromMentions(c.mentions);
+      c.lastSeen = now;
+      c.sessions.push(now);
+      _saveCorrections(corrections, home);
+      if (c.level >= 3 && c.level !== oldLevel) rebuildLearnedSection(home);
+      const { embedding: _emb, ...rest } = c;
+      return { ...rest, wasExisting: true };
+    }
+  }
+
+  const entry = {
+    id: _generateId(),
+    text,
+    mentions: 1,
+    level: levelFromMentions(1),
+    sessions: [now],
+    firstSeen: now,
+    lastSeen: now,
+    embedding: newVec,
+  };
+  corrections.push(entry);
+  _saveCorrections(corrections, home);
+  const { embedding: _emb, ...rest } = entry;
+  return { ...rest, wasExisting: false };
+}

package/lib/engine/doctor.js

@@ -0,0 +1,195 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { resolveBookLibPaths } from '../paths.js';
+import { SKILL_LIMIT } from '../wizard/skill-recommender.js';
+import { countInstalledSlots, listInstalledSkillNames } from '../skill-fetcher.js';
+
+const MARKER_START = '<!-- booklib-standards-start -->';
+
+/**
+ * Runs all diagnostic checks and returns an array of findings.
+ * @param {string} cwd - project root
+ * @returns {Array<{ check: string, severity: 'error'|'warning'|'info', message: string, fixable: boolean, data?: object }>}
+ */
+export function runDiagnostics(cwd = process.cwd()) {
+  const findings = [];
+
+  checkSlotOverload(findings);
+  checkOversizedConfigs(findings, cwd);
+  checkMissingIndex(findings, cwd);
+  checkMissingConfigFiles(findings, cwd);
+  checkStaleSkills(findings);
+  checkOrphanedSkills(findings);
+
+  return findings;
+}
+
+/** Check 1: Slot overload */
+function checkSlotOverload(findings) {
+  const slotsUsed = countInstalledSlots();
+  if (slotsUsed > SKILL_LIMIT) {
+    findings.push({
+      check: 'slot-overload',
+      severity: 'warning',
+      message: `${slotsUsed} skills installed (limit: ${SKILL_LIMIT}). Agent context is overloaded.`,
+      fixable: true,
+    });
+  }
+}
+
+/** Check 2: Oversized config files */
+function checkOversizedConfigs(findings, cwd) {
+  const configFiles = [
+    { file: 'CLAUDE.md', path: path.join(cwd, 'CLAUDE.md') },
+    { file: '.github/copilot-instructions.md', path: path.join(cwd, '.github', 'copilot-instructions.md') },
+    { file: '.gemini/context.md', path: path.join(cwd, '.gemini', 'context.md') },
+  ];
+
+  for (const cf of configFiles) {
+    if (fs.existsSync(cf.path)) {
+      const content = fs.readFileSync(cf.path, 'utf8');
+      const lines = content.split('\n').length;
+      if (lines > 500 && content.includes(MARKER_START)) {
+        findings.push({
+          check: 'oversized-config',
+          severity: 'warning',
+          message: `${cf.file} is ${lines} lines. Recommended: under 200.`,
+          fixable: true,
+          data: { file: cf.file, absPath: cf.path, lines },
+        });
+      }
+    }
+  }
+}
+
+/** Check 3: Missing index */
+function checkMissingIndex(findings, cwd) {
+  try {
+    const { indexPath } = resolveBookLibPaths(cwd);
+    if (!fs.existsSync(indexPath)) {
+      findings.push({
+        check: 'missing-index',
+        severity: 'error',
+        message: 'No search index found. Search and recommendations won\'t work.',
+        fixable: true,
+      });
+    }
+  } catch {
+    findings.push({
+      check: 'missing-index',
+      severity: 'error',
+      message: 'No search index found. Search and recommendations won\'t work.',
+      fixable: true,
+    });
+  }
+}
+
+/** Check 4: Missing config files for configured tools */
+function checkMissingConfigFiles(findings, cwd) {
+  const configPath = path.join(cwd, 'booklib.config.json');
+  if (!fs.existsSync(configPath)) return;
+
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const toolFileMap = {
+      claude: 'CLAUDE.md',
+      copilot: '.github/copilot-instructions.md',
+      gemini: '.gemini/context.md',
+      codex: 'AGENTS.md',
+      cursor: '.cursor/rules/booklib-standards.mdc',
+    };
+
+    for (const tool of (config.tools ?? [])) {
+      const expectedFile = toolFileMap[tool];
+      if (expectedFile && !fs.existsSync(path.join(cwd, expectedFile))) {
+        findings.push({
+          check: 'missing-config',
+          severity: 'warning',
+          message: `${tool} configured but ${expectedFile} not found.`,
+          fixable: true,
+          data: { tool, file: expectedFile },
+        });
+      }
+    }
+  } catch { /* malformed config, skip */ }
+}
+
+/** Check 5: Stale skills (installed but never used) */
+function checkStaleSkills(findings) {
+  const usagePath = path.join(os.homedir(), '.booklib', 'usage.json');
+  if (!fs.existsSync(usagePath)) return;
+
+  try {
+    const usage = JSON.parse(fs.readFileSync(usagePath, 'utf8'));
+    const usedNames = new Set(
+      usage.map(u => u.skill?.toLowerCase()).filter(Boolean),
+    );
+    const installed = listInstalledSkillNames();
+    const stale = installed.filter(n => !usedNames.has(n.toLowerCase()));
+
+    if (stale.length > 5) {
+      findings.push({
+        check: 'stale-skills',
+        severity: 'info',
+        message: `${stale.length} skills have no recorded usage.`,
+        fixable: true,
+        data: { staleNames: stale },
+      });
+    }
+  } catch { /* no usage data, skip */ }
+}
+
+/** Check 6: Orphaned skills (have .booklib marker but not in any catalog/index) */
+function checkOrphanedSkills(findings) {
+  const claudeSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+  if (!fs.existsSync(claudeSkillsDir)) return;
+
+  try {
+    const installed = listInstalledSkillNames();
+    // Read the bundled skills directory to find known skill names
+    const packageRoot = path.resolve(
+      new URL('.', import.meta.url).pathname, '..', '..',
+    );
+    const bundledSkillsDir = path.join(packageRoot, 'skills');
+    const bundledNames = new Set();
+    if (fs.existsSync(bundledSkillsDir)) {
+      for (const entry of fs.readdirSync(bundledSkillsDir, { withFileTypes: true })) {
+        if (entry.isDirectory()) bundledNames.add(entry.name);
+      }
+    }
+
+    const orphaned = installed.filter(n => !bundledNames.has(n));
+    for (const name of orphaned) {
+      findings.push({
+        check: 'orphaned-skill',
+        severity: 'info',
+        message: `${name} -- not found in any catalog. May be outdated.`,
+        fixable: false,
+      });
+    }
+  } catch { /* skip orphan check on error */ }
+}
+
+/**
+ * Prints diagnostic results to stdout.
+ * @param {Array<{ check: string, severity: string, message: string, fixable: boolean }>} findings
+ */
+export function printDiagnostics(findings) {
+  if (findings.length === 0) {
+    console.log('  No issues found. BookLib is healthy.\n');
+    return;
+  }
+
+  for (const f of findings) {
+    const icon = f.severity === 'error' ? '\u2717' : f.severity === 'warning' ? '\u26A0' : '\u2139';
+    console.log(`  ${icon} ${f.message}`);
+  }
+
+  const fixable = findings.filter(f => f.fixable).length;
+  if (fixable > 0) {
+    console.log(`\n  ${fixable} issue(s) fixable. Run: booklib doctor --cure\n`);
+  } else {
+    console.log('');
+  }
+}

package/lib/engine/graph-injector.js

@@ -0,0 +1,137 @@
+// lib/engine/graph-injector.js
+import { minimatch } from 'minimatch';
+import {
+  listNodes, loadNode, loadEdges, traverseEdges,
+  parseNodeFrontmatter, resolveKnowledgePaths,
+} from './graph.js';
+
+// ── Component matching ────────────────────────────────────────────────────────
+
+/**
+ * Returns component nodes whose path globs match filePath.
+ * @param {string} filePath
+ * @param {Array<{id: string, paths: string[], title: string}>} components
+ */
+export function findOwningComponents(filePath, components) {
+  return components.filter(comp =>
+    (comp.paths ?? []).some(glob => minimatch(filePath, glob, { matchBase: true }))
+  );
+}
+
+// ── Ranking ───────────────────────────────────────────────────────────────────
+
+/**
+ * Deduplicates nodes by id (keeping highest score) and sorts descending by score.
+ * @param {Array<{id: string, score: number, text: string, hop: number}>} nodes
+ */
+export function scoreAndRankNodes(nodes) {
+  const best = new Map();
+  for (const node of nodes) {
+    const existing = best.get(node.id);
+    if (!existing || node.score > existing.score) {
+      best.set(node.id, node);
+    }
+  }
+  return [...best.values()].sort((a, b) => b.score - a.score);
+}
+
+// ── Main injection pipeline ───────────────────────────────────────────────────
+
+/**
+ * Builds a ranked list of relevant knowledge nodes for the given context.
+ *
+ * Pipeline:
+ * 1. Find component nodes that own the current file (path matching)
+ * 2. Semantic search for nodes matching the task context
+ * 3. BFS graph traversal from all start nodes (components + semantic hits)
+ * 4. Deduplicate and rank by score
+ * 5. Return top N with full content loaded
+ *
+ * @param {object} opts
+ * @param {string|null} opts.filePath - File being edited (used for component matching)
+ * @param {string} opts.taskContext - Task description for semantic search
+ * @param {object} opts.searcher - BookLibSearcher instance
+ * @param {number} [opts.limit=8] - Max nodes to return
+ * @param {number} [opts.minScore=0.35] - Minimum semantic similarity score
+ * @returns {Promise<Array<{id: string, title: string, type: string, body: string, score: number}>>}
+ */
+export async function buildGraphContext({ filePath, taskContext, searcher, limit = 8, minScore = 0.35 }) {
+  const { nodesDir } = resolveKnowledgePaths();
+  const allNodeIds = listNodes({ nodesDir });
+  if (allNodeIds.length === 0) return [];
+
+  const edges = loadEdges();
+
+  // Load all component nodes for path matching
+  const componentNodes = allNodeIds
+    .map(id => {
+      const raw = loadNode(id, { nodesDir });
+      return raw ? parseNodeFrontmatter(raw) : null;
+    })
+    .filter(n => n?.type === 'component');
+
+  // 1. Component nodes that own the current file
+  const owningComponents = filePath
+    ? findOwningComponents(filePath, componentNodes)
+    : [];
+
+  // 2. Semantic search — only knowledge nodes (nodeKind: 'knowledge')
+  let semanticResults = [];
+  if (taskContext) {
+    try {
+      const raw = await searcher.search(taskContext, 20, minScore);
+      semanticResults = raw
+        .filter(r => r.metadata?.nodeKind === 'knowledge' && r.metadata?.id)
+        .map(r => ({
+          id: r.metadata.id,
+          title: r.metadata.title,
+          type: r.metadata.type,
+          text: r.text,
+          score: r.score,
+          hop: 0,
+        }));
+    } catch {
+      // Index may not exist yet — skip semantic step gracefully
+    }
+  }
+
+  // 3. BFS traversal from all start nodes
+  const startIds = new Set([
+    ...owningComponents.map(c => c.id),
+    ...semanticResults.map(r => r.id),
+  ]);
+
+  const traversalHits = [];
+  for (const startId of startIds) {
+    const hops = traverseEdges(startId, edges, 2);
+    for (const { id, hop } of hops) {
+      const raw = loadNode(id, { nodesDir });
+      if (!raw) continue;
+      const parsed = parseNodeFrontmatter(raw);
+      traversalHits.push({
+        id,
+        title: parsed.title,
+        type: parsed.type,
+        text: parsed.body ?? '',
+        score: 0.5 / hop, // distance penalty: hop 1 → 0.5, hop 2 → 0.25
+        hop,
+      });
+    }
+  }
+
+  // 4. Merge, deduplicate, rank
+  const ranked = scoreAndRankNodes([...semanticResults, ...traversalHits]);
+
+  // 5. Load full content for top results
+  return ranked.slice(0, limit).map(node => {
+    const raw = loadNode(node.id, { nodesDir });
+    const parsed = raw ? parseNodeFrontmatter(raw) : {};
+    return {
+      id: node.id,
+      title: parsed.title ?? node.title,
+      type: parsed.type ?? node.type,
+      body: parsed.body ?? node.text,
+      score: node.score,
+    };
+  });
+}

package/lib/engine/graph.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import matter from 'gray-matter';
+import { resolveBookLibPaths } from '../paths.js';
+
+export function resolveKnowledgePaths() {
+  const { indexPath } = resolveBookLibPaths();
+  const bookLibDir = path.dirname(indexPath);
+  return {
+    nodesDir: path.join(bookLibDir, 'knowledge', 'nodes'),
+    graphFile: path.join(bookLibDir, 'knowledge', 'graph.jsonl'),
+  };
+}
+
+export const EDGE_TYPES = Object.freeze([
+  'implements', 'contradicts', 'extends', 'applies-to',
+  'see-also', 'inspired-by', 'supersedes', 'depends-on',
+]);
+
+export function generateNodeId(prefix = 'node') {
+  return `${prefix}_${randomBytes(4).toString('hex')}`;
+}
+
+/** Serializes a knowledge node to a gray-matter markdown string. */
+export function serializeNode({
+  id, type, title, content = '',
+  sources = [], tags = [], area = null,
+  confidence = 'high', nodePaths = [],
+  raw = null,
+}) {
+  const data = { id, type, title, created: new Date().toISOString().split('T')[0] };
+  if (sources.length) data.sources = sources;
+  if (tags.length) data.tags = tags;
+  if (area) data.area = area;
+  if (confidence !== 'high') data.confidence = confidence;
+  if (nodePaths.length) data.paths = nodePaths;
+  if (raw) data.raw = raw;
+  return matter.stringify(content.trim(), data);
+}
+
+export function saveNode(nodeContent, id, { nodesDir } = {}) {
+  const dir = nodesDir ?? resolveKnowledgePaths().nodesDir;
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, `${id}.md`);
+  fs.writeFileSync(filePath, nodeContent, 'utf8');
+  return filePath;
+}
+
+export function loadNode(id, { nodesDir } = {}) {
+  const dir = nodesDir ?? resolveKnowledgePaths().nodesDir;
+  const filePath = path.join(dir, `${id}.md`);
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+/** Parses a node markdown file, returning frontmatter fields plus a `body` property. */
+export function parseNodeFrontmatter(content) {
+  const { data, content: body } = matter(content);
+  return { ...data, body: body.trim() };
+}
+
+export function listNodes({ nodesDir } = {}) {
+  const { nodesDir: defaultDir } = resolveKnowledgePaths();
+  const dir = nodesDir ?? defaultDir;
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.replace(/\.md$/, ''));
+}
+
+// ── Edge primitives ──────────────────────────────────────────────────────────
+
+export function appendEdge(edge, { graphFile } = {}) {
+  const file = graphFile ?? resolveKnowledgePaths().graphFile;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(edge) + '\n', 'utf8');
+}
+
+export function loadEdges({ graphFile } = {}) {
+  const file = graphFile ?? resolveKnowledgePaths().graphFile;
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map(line => JSON.parse(line));
+}
+
+/**
+ * Resolves a node reference (exact ID or partial case-insensitive title) to a node ID.
+ * Returns the matched node ID, or throws an Error with a helpful message.
+ * @param {string} ref - Exact node ID or partial title string.
+ * @param {{ nodesDir?: string }} [opts]
+ */
+export function resolveNodeRef(ref, { nodesDir } = {}) {
+  const dir = nodesDir ?? resolveKnowledgePaths().nodesDir;
+  const allIds = listNodes({ nodesDir: dir });
+
+  // Exact ID match
+  if (allIds.includes(ref)) return ref;
+
+  // Title match (case-insensitive, partial)
+  const matches = allIds
+    .map(id => {
+      const raw = loadNode(id, { nodesDir: dir });
+      if (!raw) return null;
+      const parsed = parseNodeFrontmatter(raw);
+      return { id, title: parsed.title ?? '', type: parsed.type ?? '' };
+    })
+    .filter(n => n && n.title.toLowerCase().includes(ref.toLowerCase()));
+
+  if (matches.length === 1) return matches[0].id;
+
+  if (matches.length === 0) {
+    throw new Error(`No node found matching "${ref}". Run: booklib nodes list`);
+  }
+
+  const list = matches.map(m => `  ${m.id}  [${m.type}]  ${m.title}`).join('\n');
+  throw new Error(`Multiple nodes match "${ref}" — use the exact ID:\n${list}`);
+}
+
+// ── Graph traversal (BFS, max 2 hops by default) ────────────────────────────
+
+export function traverseEdges(startId, edges, maxHops = 2) {
+  const results = [];
+  const visited = new Set([startId]);
+  const queue = [{ id: startId, hop: 0 }];
+
+  while (queue.length > 0) {
+    const { id, hop } = queue.shift();
+    if (hop >= maxHops) continue;
+
+    const connected = edges.filter(e => e.from === id || e.to === id);
+    for (const edge of connected) {
+      const neighborId = edge.from === id ? edge.to : edge.from;
+      if (!visited.has(neighborId)) {
+        visited.add(neighborId);
+        results.push({ id: neighborId, edge, hop: hop + 1 });
+        queue.push({ id: neighborId, hop: hop + 1 });
+      }
+    }
+  }
+  return results;
+}
+
+/**
+ * Parses a links argument string like "effective-kotlin:applies-to,design-patterns:see-also"
+ * into an array of { to, type } pairs. Skips entries without a colon separator.
+ * @param {string} linksArg
+ * @returns {{ to: string, type: string }[]}
+ */
+export function parseCaptureLinkArgs(linksArg) {
+  if (!linksArg) return [];
+  return linksArg.split(',')
+    .map(pair => {
+      const colonIdx = pair.lastIndexOf(':');
+      if (colonIdx === -1) return null;
+      return { to: pair.slice(0, colonIdx).trim(), type: pair.slice(colonIdx + 1).trim() };
+    })
+    .filter(Boolean);
+}