@mindrian_os/install 1.13.0-beta.11

package/lib/core/graph-ops.cjs

@@ -0,0 +1,258 @@
+/**
+ * MindrianOS Plugin -- Graph Operations
+ * Wraps existing Bash scripts via execSync AND lazygraph-ops.cjs for SQLite.
+ * build-graph: Bash script wrapper (JSON export for dashboard).
+ * index/rebuild/query/stats: SQLite via lazygraph-ops.cjs (per-project graph).
+ *
+ * All lazygraph functions use open-use-close pattern to avoid DB locking.
+ */
+
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+const lazygraph = require('./lazygraph-ops.cjs');
+const { acquireLock, releaseLock } = require('./write-lock.cjs');
+
+// Promise-chain write queue: serializes all SQLite writes.
+// Read operations bypass this queue (SQLite WAL allows concurrent reads).
+let writeQueue = Promise.resolve();
+
+function enqueueWrite(roomDir, fn) {
+  const op = writeQueue.then(async () => {
+    acquireLock(roomDir);
+    try {
+      return await fn();
+    } finally {
+      releaseLock(roomDir);
+    }
+  });
+  writeQueue = op.catch(() => {}); // prevent unhandled rejection from blocking queue
+  return op;
+}
+
+const SCRIPTS_DIR = path.resolve(__dirname, '../../scripts');
+
+/**
+ * Run build-graph script against a room directory.
+ * @param {string} roomDir - Path to room directory
+ * @param {string} [outputPath] - Output path for graph JSON (defaults to ./dashboard/graph.json)
+ * @returns {{ success: boolean, outputPath: string }} Result object
+ */
+function buildGraph(roomDir, outputPath) {
+  const resolved = path.resolve(roomDir);
+  const resolvedOutput = outputPath || './dashboard/graph.json';
+  const scriptPath = path.join(SCRIPTS_DIR, 'build-graph');
+  try {
+    execSync(`bash "${scriptPath}" "${resolved}" "${resolvedOutput}"`, {
+      timeout: 30000,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { success: true, outputPath: resolvedOutput };
+  } catch (e) {
+    throw new Error(`build-graph failed: ${e.message}`);
+  }
+}
+
+/**
+ * Index a single artifact into the per-project SQLite graph.
+ * Opens graph, indexes artifact, closes graph (open-use-close pattern).
+ * @param {string} roomDir - Path to room directory
+ * @param {string} filePath - Path to .md file to index
+ * @returns {Promise<{ success: boolean, id: string, section: string, title: string }>}
+ */
+async function indexArtifact(roomDir, filePath) {
+  return enqueueWrite(roomDir, async () => {
+    const { db, conn } = await lazygraph.openGraph(roomDir);
+    try {
+      const result = await lazygraph.indexArtifact(conn, roomDir, filePath);
+      return { success: true, id: result.id, section: result.section, title: result.title };
+    } finally {
+      await lazygraph.closeGraph(db);
+    }
+  });
+}
+
+/**
+ * Rebuild the entire per-project SQLite graph from all room artifacts.
+ * Opens graph, clears and re-indexes everything, closes graph.
+ * @param {string} roomDir - Path to room directory
+ * @returns {Promise<{ success: boolean, artifacts: number, sections: number }>}
+ */
+async function rebuildGraph(roomDir) {
+  return enqueueWrite(roomDir, async () => {
+    const { db, conn } = await lazygraph.openGraph(roomDir);
+    try {
+      const result = await lazygraph.rebuildGraph(conn, roomDir);
+      return { success: true, artifacts: result.artifacts, sections: result.sections };
+    } finally {
+      await lazygraph.closeGraph(db);
+    }
+  });
+}
+
+/**
+ * Execute a SQL query against the per-project SQLite graph.
+ * Opens graph, runs query, closes graph.
+ * @param {string} roomDir - Path to room directory
+ * @param {string} sql - SQL query string
+ * @returns {Promise<{ success: boolean, rows: Array<object>, count: number }>}
+ */
+async function queryGraph(roomDir, sql) {
+  const { db, conn } = await lazygraph.openGraph(roomDir);
+  try {
+    const rows = await lazygraph.queryGraph(conn, sql);
+    return { success: true, rows, count: rows.length };
+  } finally {
+    await lazygraph.closeGraph(db);
+  }
+}
+
+/**
+ * Get graph statistics from the per-project SQLite graph.
+ * Opens graph, gets stats, closes graph.
+ * @param {string} roomDir - Path to room directory
+ * @returns {Promise<{ nodes: object, edges: object, total: { nodes: number, edges: number } }>}
+ */
+async function graphStats(roomDir) {
+  const { db, conn } = await lazygraph.openGraph(roomDir);
+  try {
+    return await lazygraph.graphStats(conn);
+  } finally {
+    await lazygraph.closeGraph(db);
+  }
+}
+
+/**
+ * Build graph.json from SQLite as primary source.
+ * Falls back to file-scanning buildGraph if SQLite fails.
+ * NOTE: This function calls the build-graph-from-sqlite.cjs script.
+ * @param {string} roomDir - Path to room directory
+ * @param {string} [outputPath] - Output path for graph JSON
+ * @returns {{ success: boolean, outputPath: string, source: string }}
+ */
+function buildGraphFromSQLite(roomDir, outputPath) {
+  const resolved = path.resolve(roomDir);
+  const resolvedOutput = outputPath || path.join(resolved, '.presentation', 'graph.json');
+  const scriptPath = path.join(SCRIPTS_DIR, 'build-graph-from-sqlite.cjs');
+
+  try {
+    execSync(`node "${scriptPath}" "${resolved}" "${resolvedOutput}"`, {
+      timeout: 10000,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    // Check if file was actually created (script exits 0 even on graceful degradation)
+    const fs = require('fs');
+    if (fs.existsSync(resolvedOutput)) {
+      return { success: true, outputPath: resolvedOutput, source: 'sqlite' };
+    }
+  } catch (_e) {
+    // Fall through to file-scanning fallback
+  }
+
+  // Fallback to existing file-scanning build-graph
+  try {
+    const result = buildGraph(roomDir, resolvedOutput);
+    return { success: true, outputPath: resolvedOutput, source: 'fallback-filescan' };
+  } catch (_e2) {
+    return { success: false, outputPath: resolvedOutput, source: 'none' };
+  }
+}
+
+// Keep legacy name as alias for backward compatibility
+const buildGraphFromKuzu = buildGraphFromSQLite;
+
+/**
+ * Persist a decision edge (INVALIDATES/CONFIRMS/DEFERRED) to SQLite.
+ * Uses enqueueWrite for serialized access + open-use-close pattern.
+ *
+ * @param {string} roomDir - Path to room directory
+ * @param {string} sourceArtifactId - Source artifact ID
+ * @param {string} targetArtifactId - Target artifact ID
+ * @param {'INVALIDATES'|'CONFIRMS'|'DEFERRED'} edgeType - Edge type from recordDecision
+ * @param {Object} [properties={}] - Edge properties (reason, timestamp)
+ * @returns {Promise<{ success: boolean, edgeType: string }>}
+ */
+async function persistDecisionEdge(roomDir, sourceArtifactId, targetArtifactId, edgeType, properties = {}) {
+  return enqueueWrite(roomDir, async () => {
+    const { db, conn } = await lazygraph.openGraph(roomDir);
+    try {
+      const edgeProps = JSON.stringify({
+        reason: properties.reason || '',
+        timestamp: properties.timestamp || new Date().toISOString(),
+      });
+
+      conn.prepare(
+        'INSERT INTO edges (source, target, type, properties) VALUES (?, ?, ?, ?) ON CONFLICT(source, target, type) DO UPDATE SET properties = excluded.properties'
+      ).run(sourceArtifactId, targetArtifactId, edgeType, edgeProps);
+
+      return { success: true, edgeType };
+    } finally {
+      await lazygraph.closeGraph(db);
+    }
+  });
+}
+
+/**
+ * Index an opportunity into the per-project SQLite graph.
+ * Creates Opportunity node, ADDRESSES edges to domain artifacts, IN_DOMAIN edge to section.
+ * Uses enqueueWrite for serialized SQLite access (open-use-close pattern).
+ *
+ * @param {string} roomDir - Path to room directory
+ * @param {object} opportunity - Opportunity object with problem_hash, domain, etc.
+ * @returns {Promise<{success: boolean, problem_hash: string}>}
+ */
+async function indexOpportunity(roomDir, opportunity) {
+  return enqueueWrite(roomDir, async () => {
+    const { db, conn } = await lazygraph.openGraph(roomDir);
+    try {
+      // Create opportunity node (upsert = idempotent)
+      if (typeof lazygraph.createOpportunityNode === 'function') {
+        await lazygraph.createOpportunityNode(conn, opportunity);
+      } else {
+        // Fallback: create as generic node
+        const props = JSON.stringify(opportunity);
+        conn.prepare(
+          'INSERT INTO nodes (id, type, properties) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET properties = excluded.properties'
+        ).run(opportunity.problem_hash, 'Opportunity', props);
+      }
+
+      // ADDRESSES edge: link to artifacts in the opportunity's domain section
+      if (opportunity.domain) {
+        const rows = conn.prepare(
+          "SELECT id FROM nodes WHERE type = 'Artifact' AND json_extract(properties, '$.section') = ? LIMIT 5"
+        ).all(opportunity.domain);
+
+        for (const row of rows) {
+          if (typeof lazygraph.createAddressesEdge === 'function') {
+            await lazygraph.createAddressesEdge(conn, opportunity.problem_hash, row.id);
+          } else {
+            conn.prepare(
+              'INSERT INTO edges (source, target, type) VALUES (?, ?, ?) ON CONFLICT DO NOTHING'
+            ).run(opportunity.problem_hash, row.id, 'ADDRESSES');
+          }
+        }
+      }
+
+      // IN_DOMAIN edge: link to section node
+      if (opportunity.domain) {
+        if (typeof lazygraph.createInDomainEdge === 'function') {
+          await lazygraph.createInDomainEdge(conn, opportunity.problem_hash, opportunity.domain);
+        } else {
+          conn.prepare(
+            'INSERT INTO edges (source, target, type) VALUES (?, ?, ?) ON CONFLICT DO NOTHING'
+          ).run(opportunity.problem_hash, opportunity.domain, 'IN_DOMAIN');
+        }
+      }
+
+      return { success: true, problem_hash: opportunity.problem_hash };
+    } finally {
+      await lazygraph.closeGraph(db);
+    }
+  });
+}
+
+module.exports = { buildGraph, buildGraphFromKuzu, buildGraphFromSQLite, indexArtifact, rebuildGraph, queryGraph, graphStats, enqueueWrite, persistDecisionEdge, indexOpportunity };

package/lib/core/hat-persistence.cjs

@@ -0,0 +1,362 @@
+/**
+ * MindrianOS Plugin -- De Bono Hat Persistence
+ * Manages persistent hat state across sessions for each room.
+ *
+ * Storage layout:
+ *   room/.mindrian/hats/{color}/STATE.md     - Current hat state (focus, concerns, opportunities)
+ *   room/.mindrian/hats/{color}/session-log/YYYY-MM-DD.md - Daily session findings
+ *
+ * Exports: loadHatState, saveHatState, logSession, loadAllHatStates, getRecentLogs
+ *
+ * Pure Node.js built-ins only (zero npm deps per Phase 10 decision).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const HAT_COLORS = ['white', 'red', 'black', 'yellow', 'green', 'blue'];
+
+const HAT_LABELS = {
+  white: 'Facts & Data',
+  red: 'Emotions & Intuition',
+  black: 'Risks & Dangers',
+  yellow: 'Benefits & Opportunities',
+  green: 'Creativity & Alternatives',
+  blue: 'Process & Meta',
+};
+
+// ---------------------------------------------------------------------------
+// Directory helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the hat directory for a given color within a room.
+ * @param {string} roomDir - Absolute path to room directory
+ * @param {string} color - Hat color (white|red|black|yellow|green|blue)
+ * @returns {string}
+ */
+function hatDir(roomDir, color) {
+  return path.join(path.resolve(roomDir), '.mindrian', 'hats', color);
+}
+
+/**
+ * Ensure hat directories exist for a given color.
+ * @param {string} roomDir
+ * @param {string} color
+ */
+function ensureHatDirs(roomDir, color) {
+  const dir = hatDir(roomDir, color);
+  fs.mkdirSync(path.join(dir, 'session-log'), { recursive: true });
+}
+
+// ---------------------------------------------------------------------------
+// STATE.md parsing / serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a hat STATE.md into structured data.
+ * @param {string} content - Raw markdown content
+ * @returns {{ current_focus: string, last_analysis: string, top_concerns: string[], top_opportunities: string[], methodology_notes: string[], session_count: number }}
+ */
+function parseHatState(content) {
+  const state = {
+    current_focus: '',
+    last_analysis: '',
+    top_concerns: [],
+    top_opportunities: [],
+    methodology_notes: [],
+    session_count: 0,
+  };
+
+  if (!content || typeof content !== 'string') return state;
+
+  // Parse frontmatter
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (fmMatch) {
+    const lines = fmMatch[1].split('\n');
+    for (const line of lines) {
+      const kvMatch = line.match(/^([a-z_]+):\s*(.*)$/);
+      if (kvMatch) {
+        const key = kvMatch[1];
+        const val = kvMatch[2].trim();
+        if (key === 'current_focus') state.current_focus = val;
+        if (key === 'last_analysis') state.last_analysis = val;
+        if (key === 'session_count') state.session_count = parseInt(val, 10) || 0;
+      }
+      const listMatch = line.match(/^\s+-\s+(.+)$/);
+      if (listMatch) {
+        // Determine which list this belongs to based on preceding key
+        // Simple heuristic: check what the last key was
+      }
+    }
+  }
+
+  // Parse sections from body
+  const bodyStart = content.indexOf('---', content.indexOf('---') + 3);
+  const body = bodyStart >= 0 ? content.slice(bodyStart + 3) : content;
+
+  const concernsMatch = body.match(/## Top Concerns\n([\s\S]*?)(?=\n## |$)/);
+  if (concernsMatch) {
+    state.top_concerns = concernsMatch[1]
+      .split('\n')
+      .filter(l => l.trim().startsWith('-'))
+      .map(l => l.replace(/^\s*-\s*/, '').trim())
+      .filter(Boolean);
+  }
+
+  const oppsMatch = body.match(/## Top Opportunities\n([\s\S]*?)(?=\n## |$)/);
+  if (oppsMatch) {
+    state.top_opportunities = oppsMatch[1]
+      .split('\n')
+      .filter(l => l.trim().startsWith('-'))
+      .map(l => l.replace(/^\s*-\s*/, '').trim())
+      .filter(Boolean);
+  }
+
+  const methMatch = body.match(/## Methodology Notes\n([\s\S]*?)(?=\n## |$)/);
+  if (methMatch) {
+    state.methodology_notes = methMatch[1]
+      .split('\n')
+      .filter(l => l.trim().startsWith('-'))
+      .map(l => l.replace(/^\s*-\s*/, '').trim())
+      .filter(Boolean);
+  }
+
+  return state;
+}
+
+/**
+ * Serialize hat state to STATE.md markdown content.
+ * @param {string} color
+ * @param {object} state
+ * @returns {string}
+ */
+function serializeHatState(color, state) {
+  const label = HAT_LABELS[color] || color;
+  const concerns = (state.top_concerns || []).map(c => `- ${c}`).join('\n') || '- None yet';
+  const opps = (state.top_opportunities || []).map(o => `- ${o}`).join('\n') || '- None yet';
+  const meth = (state.methodology_notes || []).map(m => `- ${m}`).join('\n') || '- None yet';
+
+  return `---
+hat: ${color}
+hat_label: ${label}
+current_focus: ${state.current_focus || 'General analysis'}
+last_analysis: ${state.last_analysis || 'never'}
+session_count: ${state.session_count || 0}
+---
+
+# ${color.charAt(0).toUpperCase() + color.slice(1)} Hat -- ${label}
+
+## Top Concerns
+${concerns}
+
+## Top Opportunities
+${opps}
+
+## Methodology Notes
+${meth}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Core API
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the persistent state for a given hat color.
+ * Returns default state if no STATE.md exists yet.
+ * @param {string} roomDir - Absolute path to room directory
+ * @param {string} color - Hat color
+ * @returns {{ current_focus: string, last_analysis: string, top_concerns: string[], top_opportunities: string[], methodology_notes: string[], session_count: number }}
+ */
+function loadHatState(roomDir, color) {
+  if (!HAT_COLORS.includes(color)) {
+    return { error: `Invalid hat color: ${color}. Must be one of: ${HAT_COLORS.join(', ')}` };
+  }
+
+  const statePath = path.join(hatDir(roomDir, color), 'STATE.md');
+  try {
+    const content = fs.readFileSync(statePath, 'utf-8');
+    return parseHatState(content);
+  } catch (e) {
+    // No state yet -- return defaults
+    return {
+      current_focus: 'General analysis',
+      last_analysis: 'never',
+      top_concerns: [],
+      top_opportunities: [],
+      methodology_notes: [],
+      session_count: 0,
+    };
+  }
+}
+
+/**
+ * Save hat state to disk. Creates directories if needed.
+ * @param {string} roomDir - Absolute path to room directory
+ * @param {string} color - Hat color
+ * @param {object} state - State to persist
+ * @returns {{ saved: boolean, path: string }}
+ */
+function saveHatState(roomDir, color, state) {
+  if (!HAT_COLORS.includes(color)) {
+    return { error: `Invalid hat color: ${color}` };
+  }
+
+  ensureHatDirs(roomDir, color);
+  const statePath = path.join(hatDir(roomDir, color), 'STATE.md');
+
+  // Merge with existing state to preserve fields not in this update
+  const existing = loadHatState(roomDir, color);
+  const merged = {
+    current_focus: state.current_focus || existing.current_focus,
+    last_analysis: state.last_analysis || new Date().toISOString().split('T')[0],
+    top_concerns: state.top_concerns || existing.top_concerns,
+    top_opportunities: state.top_opportunities || existing.top_opportunities,
+    methodology_notes: state.methodology_notes || existing.methodology_notes,
+    session_count: (state.session_count !== undefined) ? state.session_count : existing.session_count,
+  };
+
+  const content = serializeHatState(color, merged);
+  fs.writeFileSync(statePath, content, 'utf-8');
+
+  return { saved: true, path: statePath };
+}
+
+/**
+ * Log a session's findings for a hat color. Appends to the daily log file.
+ * @param {string} roomDir - Absolute path to room directory
+ * @param {string} color - Hat color
+ * @param {{ focus: string, findings: string[], concerns: string[], opportunities: string[], artifact?: string }} findings
+ * @returns {{ logged: boolean, path: string }}
+ */
+function logSession(roomDir, color, findings) {
+  if (!HAT_COLORS.includes(color)) {
+    return { error: `Invalid hat color: ${color}` };
+  }
+
+  ensureHatDirs(roomDir, color);
+
+  const today = new Date().toISOString().split('T')[0];
+  const time = new Date().toISOString().split('T')[1].replace(/\.\d+Z/, 'Z');
+  const logPath = path.join(hatDir(roomDir, color), 'session-log', `${today}.md`);
+
+  const label = HAT_LABELS[color] || color;
+  const entry = [
+    '',
+    `## Session at ${time}`,
+    '',
+    `**Focus:** ${findings.focus || 'General analysis'}`,
+    findings.artifact ? `**Artifact:** ${findings.artifact}` : '',
+    '',
+    '### Findings',
+    ...(findings.findings || []).map(f => `- ${f}`),
+    '',
+    '### Concerns',
+    ...(findings.concerns || []).map(c => `- ${c}`),
+    '',
+    '### Opportunities',
+    ...(findings.opportunities || []).map(o => `- ${o}`),
+    '',
+    '---',
+  ].filter(l => l !== undefined).join('\n');
+
+  // If file exists, append. Otherwise create with header.
+  let content;
+  try {
+    content = fs.readFileSync(logPath, 'utf-8');
+    content += '\n' + entry;
+  } catch (e) {
+    content = `# ${color.charAt(0).toUpperCase() + color.slice(1)} Hat -- ${label} Session Log (${today})\n` + entry;
+  }
+
+  fs.writeFileSync(logPath, content, 'utf-8');
+
+  // Update session count in STATE.md
+  const state = loadHatState(roomDir, color);
+  state.session_count = (state.session_count || 0) + 1;
+  state.last_analysis = today;
+
+  // Merge new concerns/opportunities into state (keep last 5 each)
+  if (findings.concerns && findings.concerns.length > 0) {
+    const merged = [...findings.concerns, ...(state.top_concerns || [])];
+    state.top_concerns = [...new Set(merged)].slice(0, 5);
+  }
+  if (findings.opportunities && findings.opportunities.length > 0) {
+    const merged = [...findings.opportunities, ...(state.top_opportunities || [])];
+    state.top_opportunities = [...new Set(merged)].slice(0, 5);
+  }
+  if (findings.focus) {
+    state.current_focus = findings.focus;
+  }
+
+  saveHatState(roomDir, color, state);
+
+  return { logged: true, path: logPath };
+}
+
+/**
+ * Load all 6 hat states for a room. Returns map of color -> state.
+ * @param {string} roomDir
+ * @returns {Object<string, object>}
+ */
+function loadAllHatStates(roomDir) {
+  const states = {};
+  for (const color of HAT_COLORS) {
+    states[color] = loadHatState(roomDir, color);
+  }
+  return states;
+}
+
+/**
+ * Get recent session logs for a hat (last N days).
+ * @param {string} roomDir
+ * @param {string} color
+ * @param {number} [days=7] - How many days back to look
+ * @returns {Array<{ date: string, content: string }>}
+ */
+function getRecentLogs(roomDir, color, days = 7) {
+  if (!HAT_COLORS.includes(color)) return [];
+
+  const logDir = path.join(hatDir(roomDir, color), 'session-log');
+  let files;
+  try {
+    files = fs.readdirSync(logDir).filter(f => f.endsWith('.md')).sort().reverse();
+  } catch (e) {
+    return [];
+  }
+
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - days);
+  const cutoffStr = cutoff.toISOString().split('T')[0];
+
+  const logs = [];
+  for (const file of files) {
+    const date = file.replace('.md', '');
+    if (date < cutoffStr) break;
+    try {
+      const content = fs.readFileSync(path.join(logDir, file), 'utf-8');
+      logs.push({ date, content });
+    } catch (e) {
+      // skip unreadable
+    }
+  }
+
+  return logs;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  HAT_COLORS,
+  HAT_LABELS,
+  loadHatState,
+  saveHatState,
+  logSession,
+  loadAllHatStates,
+  getRecentLogs,
+};

package/lib/core/index.cjs

@@ -0,0 +1,60 @@
+/**
+ * MindrianOS Plugin — Shared Core Helpers
+ * Pure Node.js built-ins only. No npm dependencies.
+ *
+ * Replicates the GSD gsd-tools.cjs output pattern:
+ * - JSON to stdout for structured data
+ * - Large payloads (>50KB) written to tmpfile with @file: prefix
+ * - Errors to stderr with exit 1
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/** Root of the plugin repository */
+const PLUGIN_ROOT = path.resolve(__dirname, '../..');
+
+/**
+ * Output structured result to stdout.
+ * If raw mode, write rawValue directly.
+ * Otherwise JSON-stringify; if >50KB, write to tmpfile with @file: prefix.
+ */
+function output(result, raw, rawValue) {
+  if (raw && rawValue !== undefined) {
+    process.stdout.write(String(rawValue));
+  } else {
+    const json = JSON.stringify(result, null, 2);
+    if (json.length > 50000) {
+      const tmpPath = path.join(os.tmpdir(), `mindrian-${Date.now()}.json`);
+      fs.writeFileSync(tmpPath, json, 'utf-8');
+      process.stdout.write('@file:' + tmpPath);
+    } else {
+      process.stdout.write(json);
+    }
+  }
+  process.exit(0);
+}
+
+/**
+ * Write error message to stderr and exit 1.
+ */
+function error(msg) {
+  process.stderr.write('ERROR: ' + msg + '\n');
+  process.exit(1);
+}
+
+/**
+ * Read file contents safely. Returns string or null if not found.
+ */
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch (e) {
+    return null;
+  }
+}
+
+module.exports = { output, error, safeReadFile, PLUGIN_ROOT };