@geraldmaron/construct 1.0.0

package/lib/distill.mjs

@@ -0,0 +1,403 @@
+#!/usr/bin/env node
+/**
+ * lib/distill.mjs — <one-line purpose>
+ *
+ * <2–6 line summary.>
+ */
+import { readdirSync, statSync, readFileSync, writeFileSync, existsSync, mkdirSync, openSync, readSync, closeSync } from 'fs';
+import { join, extname, relative, dirname, basename } from 'path';
+import { execSync, spawnSync } from 'child_process';
+import { homedir } from 'os';
+import { getActiveOverlays } from './headhunt.mjs';
+
+const TEXT_EXTS = new Set([
+  '.md', '.txt', '.rst', '.adoc', '.json', '.yaml', '.yml', '.toml',
+  '.js', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.sh', '.bash',
+  '.html', '.css', '.csv', '.xml', '.env', '.env.example', '.conf', '.ini', '.tf', '.hcl',
+]);
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.next', 'dist', 'build', '__pycache__', '.cache']);
+const MAX_FILE_BYTES = 80_000;
+const MAX_DISCOVER_FILE_BYTES = 5_000_000;
+const MAX_TOTAL_BYTES = 600_000;
+const MAX_FILES = 80;
+const DEFAULT_CHUNK_BYTES = 4_000;
+const DEFAULT_CHUNK_OVERLAP = 400;
+
+function discoverFiles(dir, maxDepth = 3, allowedExts = null) {
+  const files = [];
+  function walk(current, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = readdirSync(current); } catch { return; }
+    for (const entry of entries.sort()) {
+      if (entry.startsWith('.') && entry !== '.env.example') continue;
+      const full = join(current, entry);
+      let stat;
+      try { stat = statSync(full); } catch { continue; }
+      if (stat.isDirectory()) {
+        if (!SKIP_DIRS.has(entry)) walk(full, depth + 1);
+      } else {
+        const ext = extname(entry).toLowerCase();
+        const match = allowedExts ? allowedExts.has(ext) : TEXT_EXTS.has(ext);
+        if (match && stat.size > 0 && stat.size <= MAX_DISCOVER_FILE_BYTES) files.push({ path: full, size: stat.size, ext });
+      }
+    }
+  }
+  walk(dir, 0);
+  return files;
+}
+
+function decodeBytes(buffer) {
+  return Buffer.from(buffer).toString('utf8').replace(/\u0000/g, '');
+}
+
+function readBoundedText(filePath, size) {
+  if (size <= MAX_FILE_BYTES) {
+    return {
+      content: readFileSync(filePath, 'utf8'),
+      truncated: false,
+      sampledBytes: size,
+      originalBytes: size,
+    };
+  }
+
+  const headBytes = Math.floor(MAX_FILE_BYTES * 0.6);
+  const tailBytes = MAX_FILE_BYTES - headBytes;
+  const fd = openSync(filePath, 'r');
+  try {
+    const headBuffer = Buffer.alloc(headBytes);
+    const tailBuffer = Buffer.alloc(tailBytes);
+    const headRead = readSync(fd, headBuffer, 0, headBytes, 0);
+    const tailRead = readSync(fd, tailBuffer, 0, tailBytes, Math.max(0, size - tailBytes));
+    const gap = size - headRead - tailRead;
+    return {
+      content: `${decodeBytes(headBuffer.subarray(0, headRead))}\n\n… [middle omitted: ${Math.max(0, gap)} bytes skipped from large file] …\n\n${decodeBytes(tailBuffer.subarray(0, tailRead))}`,
+      truncated: true,
+      sampledBytes: headRead + tailRead,
+      originalBytes: size,
+    };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function inferDocumentTitle(relPath, content) {
+  const firstHeading = content.match(/^(?:#{1,2}\s+.+|title:\s*.+)$/im)?.[0];
+  if (firstHeading) return firstHeading.replace(/^#{1,2}\s+|^title:\s*/i, '').trim();
+  return basename(relPath);
+}
+
+function detectHeadings(content) {
+  const headings = [];
+  for (const match of content.matchAll(/^(#{1,6}[ \t]+.+)$/gm)) {
+    headings.push({ index: match.index || 0, text: match[1].replace(/^#{1,6}[ \t]+/, '').trim() });
+  }
+  return headings;
+}
+
+function headingForOffset(headings, offset) {
+  let current = null;
+  for (const heading of headings) {
+    if (heading.index > offset) break;
+    current = heading.text;
+  }
+  return current;
+}
+
+function chunkContent(relPath, content, { chunkBytes = DEFAULT_CHUNK_BYTES, overlap = DEFAULT_CHUNK_OVERLAP, truncated = false, originalBytes = content.length, sampledBytes = content.length } = {}) {
+  const title = inferDocumentTitle(relPath, content);
+  const headings = detectHeadings(content);
+  const chunks = [];
+  let offset = 0;
+  let index = 0;
+  while (offset < content.length) {
+    const end = Math.min(content.length, offset + chunkBytes);
+    const text = content.slice(offset, end);
+    if (!text.trim()) break;
+    chunks.push({
+      id: `${relPath}#${index + 1}`,
+      rel: relPath,
+      title,
+      section: headingForOffset(headings, offset),
+      start: offset,
+      end,
+      text,
+      truncated,
+      originalBytes,
+      sampledBytes,
+    });
+    if (end >= content.length) break;
+    offset = Math.max(end - overlap, offset + 1);
+    index += 1;
+  }
+  return chunks;
+}
+
+function scoreChunk(chunk, queryTerms) {
+  if (queryTerms.length === 0) return 0;
+  const haystack = `${chunk.title || ''}\n${chunk.section || ''}\n${chunk.text}`.toLowerCase();
+  let score = 0;
+  for (const term of queryTerms) {
+    if (haystack.includes(term)) score += 1;
+  }
+  if (chunk.section && queryTerms.some((term) => chunk.section.toLowerCase().includes(term))) score += 1;
+  return score;
+}
+
+function selectChunks(chunks, query, maxChunks = 24) {
+  if (!query) return chunks.slice(0, maxChunks);
+  const queryTerms = Array.from(new Set(query.toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length >= 3)));
+  return chunks
+    .map((chunk) => ({ chunk, score: scoreChunk(chunk, queryTerms) }))
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => b.score - a.score || a.chunk.rel.localeCompare(b.chunk.rel) || a.chunk.start - b.chunk.start)
+    .slice(0, maxChunks)
+    .map(({ chunk }) => chunk);
+}
+
+function evaluateSufficiency(chunks, query) {
+  if (!query) return { status: 'not_applicable', matchedTerms: [], missingTerms: [] };
+  const queryTerms = Array.from(new Set(query.toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length >= 3)));
+  if (queryTerms.length === 0) return { status: 'not_applicable', matchedTerms: [], missingTerms: [] };
+
+  const haystack = chunks.map((chunk) => `${chunk.title || ''}\n${chunk.section || ''}\n${chunk.text}`.toLowerCase()).join('\n');
+  const matchedTerms = queryTerms.filter((term) => haystack.includes(term));
+  const missingTerms = queryTerms.filter((term) => !haystack.includes(term));
+
+  let status = 'insufficient';
+  if (missingTerms.length === 0 && chunks.length > 0) status = 'sufficient';
+  else if (matchedTerms.length > 0 && chunks.length > 0) status = 'partial';
+
+  return { status, matchedTerms, missingTerms };
+}
+
+function readFiles(files, dir, options = {}) {
+  const chunks = [];
+  let totalBytes = 0;
+  let truncatedFileCount = 0;
+  for (const file of files) {
+    if (chunks.length >= MAX_FILES) break;
+    if (totalBytes >= MAX_TOTAL_BYTES) break;
+    try {
+      const bounded = readBoundedText(file.path, file.size);
+      totalBytes += bounded.sampledBytes;
+      if (bounded.truncated) truncatedFileCount += 1;
+      chunks.push(...chunkContent(relative(dir, file.path), bounded.content, {
+        ...options,
+        truncated: bounded.truncated,
+        originalBytes: bounded.originalBytes,
+        sampledBytes: bounded.sampledBytes,
+      }));
+    } catch { /* skip unreadable files */ }
+  }
+  return { chunks, totalBytes, truncatedFileCount };
+}
+
+function buildPrompt(dir, chunks, { format, query, mode }) {
+  const overlays = getActiveOverlays(dir);
+  const instructions = {
+    summary: `Produce a structured distillation with sections: Executive Summary, Key Themes, Decisions & Actions, Open Questions, File Index.`,
+    decisions: `Focus only on decisions, recommendations, owners, deadlines, blockers, and action items.`,
+    full: `Produce a comprehensive distillation with Executive Summary, Background & Context, Key Themes, Architecture & Design Decisions, Decisions & Actions, Risks & Open Questions, Glossary, and File Index.`,
+    extract: `Answer the query using only the provided evidence. Output sections: Answer, Evidence, Gaps, Sufficiency (sufficient | partial | insufficient).`,
+  };
+
+  const fileBlocks = chunks.map((chunk) => {
+    const meta = [
+      `source=${chunk.rel}`,
+      `chunk=${chunk.id}`,
+      `range=${chunk.start}-${chunk.end}`,
+      chunk.title ? `title=${chunk.title}` : null,
+      chunk.section ? `section=${chunk.section}` : null,
+    ].filter(Boolean).join(' | ');
+    return `### ${meta}\n\n${chunk.text}`;
+  }).join('\n\n');
+
+  const overlayBlock = overlays.length > 0
+    ? `Active domain overlays:\n${overlays.map((overlay) => `- ${overlay.domain}: ${overlay.objective}${overlay.scope ? ` (scope: ${overlay.scope})` : ''}`).join('\n')}\n\nUse overlays only as temporary scope guidance, not as permanent truth.\n\n`
+    : '';
+
+  return `You are analyzing document evidence from: ${dir}\n\nMode: ${mode}\n${query ? `Query: ${query}\n` : ''}${instructions[format] || instructions.summary}\n\nRules:\n- Use only provided evidence.\n- Prefer query-focused extraction when a query is provided.\n- Every substantive claim must cite one or more chunk IDs in inline form like [source: path#chunk].\n- If evidence is incomplete, say so explicitly.\n- Do not invent facts.\n\n${overlayBlock}---\n\n${fileBlocks}`;
+}
+
+function buildStructuredOutput(dir, chunks, { format, query, mode }) {
+  const overlays = getActiveOverlays(dir);
+  const sufficiency = evaluateSufficiency(chunks, query);
+  const files = new Map();
+  for (const chunk of chunks) {
+    if (!files.has(chunk.rel)) {
+      files.set(chunk.rel, {
+        file: chunk.rel,
+        title: chunk.title || basename(chunk.rel),
+        sections: new Set(),
+        chunkIds: [],
+        truncated: Boolean(chunk.truncated),
+        sampledBytes: Number(chunk.sampledBytes || 0),
+        originalBytes: Number(chunk.originalBytes || 0),
+      });
+    }
+    const entry = files.get(chunk.rel);
+    if (chunk.section) entry.sections.add(chunk.section);
+    entry.chunkIds.push(chunk.id);
+    entry.truncated = entry.truncated || Boolean(chunk.truncated);
+    entry.sampledBytes = Math.max(entry.sampledBytes, Number(chunk.sampledBytes || 0));
+    entry.originalBytes = Math.max(entry.originalBytes, Number(chunk.originalBytes || 0));
+  }
+
+  return {
+    mode,
+    format,
+    query: query || null,
+    overlays: overlays.map((overlay) => ({
+      id: overlay.id,
+      domain: overlay.domain,
+      objective: overlay.objective,
+      scope: overlay.scope,
+      attachTo: overlay.attachTo,
+    })),
+    fileCount: files.size,
+    chunkCount: chunks.length,
+    sufficiency,
+    files: Array.from(files.values()).map((entry) => ({
+      file: entry.file,
+      title: entry.title,
+      sections: Array.from(entry.sections),
+      chunkIds: entry.chunkIds,
+      truncated: entry.truncated,
+      sampledBytes: entry.sampledBytes,
+      originalBytes: entry.originalBytes,
+    })),
+    evidence: chunks.map((chunk) => ({
+      id: chunk.id,
+      file: chunk.rel,
+      title: chunk.title,
+      section: chunk.section,
+      citation: `[source: ${chunk.id}]`,
+      truncated: Boolean(chunk.truncated),
+      text: chunk.text,
+    })),
+    prompt: buildPrompt(dir, chunks, { format, query, mode }),
+  };
+}
+
+function hasClaude() {
+  try {
+    execSync('claude --version', { stdio: 'pipe', timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseArgs(argv) {
+  const positional = argv.filter((arg) => !arg.startsWith('--'));
+  const flags = Object.fromEntries(argv.filter((arg) => arg.startsWith('--')).map((arg) => {
+    const [k, ...v] = arg.slice(2).split('=');
+    return [k, v.length ? v.join('=') : true];
+  }));
+  return { positional, flags };
+}
+
+export async function distill(dir, { format = 'summary', query = '', mode = 'auto', out = null, depth = 3, ext = null } = {}) {
+  const resolvedDir = dir.startsWith('/') ? dir : join(process.cwd(), dir);
+  if (!existsSync(resolvedDir)) throw new Error(`Directory not found: ${resolvedDir}`);
+
+  const allowedExts = ext ? new Set(ext.split(',').map((value) => value.trim().startsWith('.') ? value.trim() : `.${value.trim()}`)) : null;
+  const files = discoverFiles(resolvedDir, depth, allowedExts);
+  if (files.length === 0) throw new Error(`No readable text files found in ${resolvedDir}`);
+
+  process.stderr.write(`\n🔬 Distilling ${files.length} file(s) from ${resolvedDir}\n`);
+  if (files.length > MAX_FILES) process.stderr.write(`   (scanning first ${MAX_FILES} files by name order)\n`);
+
+  const { chunks, totalBytes, truncatedFileCount } = readFiles(files, resolvedDir);
+  process.stderr.write(`   Built ${chunks.length} chunk(s) · ${Math.round(totalBytes / 1024)} KB\n`);
+  if (truncatedFileCount > 0) process.stderr.write(`   Sampled ${truncatedFileCount} large file(s) with bounded head/tail reads\n`);
+
+  const selectedChunks = query ? selectChunks(chunks, query) : chunks.slice(0, 24);
+  process.stderr.write(`   Selected ${selectedChunks.length} chunk(s) for analysis${query ? ' using query-focused retrieval' : ''}\n`);
+
+  const structured = buildStructuredOutput(resolvedDir, selectedChunks, { format, query, mode });
+
+  if (mode === 'json') {
+    const output = `${JSON.stringify(structured, null, 2)}\n`;
+    if (out) {
+      try { mkdirSync(dirname(out), { recursive: true }); } catch { /* exists */ }
+      writeFileSync(out, output);
+      process.stderr.write(`✓ Distillation JSON written to: ${out}\n`);
+    } else {
+      process.stdout.write(output);
+    }
+    return structured;
+  }
+
+  const prompt = structured.prompt;
+  if (mode === 'prompt' || !hasClaude()) {
+    const tmpFile = out || join(homedir(), '.cx', 'distill-prompt.txt');
+    try { mkdirSync(dirname(tmpFile), { recursive: true }); } catch { /* exists */ }
+    writeFileSync(tmpFile, prompt);
+    process.stderr.write(`\n⚠ Prompt written to: ${tmpFile}\n`);
+    if (mode !== 'prompt' && !hasClaude()) process.stderr.write('   claude CLI not found. Paste the prompt into your preferred model interface.\n\n');
+    return structured;
+  }
+
+  process.stderr.write('   Invoking claude --print …\n\n');
+  const result = spawnSync('claude', ['--print', prompt], {
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024,
+    timeout: 120_000,
+  });
+
+  if (result.error) throw result.error;
+  const output = result.stdout || '';
+  const errOut = result.stderr || '';
+  if (result.status !== 0) {
+    if (errOut) process.stderr.write(`${errOut}\n`);
+    throw new Error(`claude exited with status ${result.status}`);
+  }
+
+  if (out) {
+    try { mkdirSync(dirname(out), { recursive: true }); } catch { /* exists */ }
+    writeFileSync(out, output);
+    process.stderr.write(`✓ Distillation written to: ${out}\n`);
+  } else {
+    process.stdout.write(output);
+  }
+
+  return structured;
+}
+
+export async function runDistillCli(argv = process.argv.slice(2)) {
+  const { positional, flags } = parseArgs(argv);
+  const dir = positional[0];
+  if (!dir) throw new Error('Usage: construct distill <dir> [--format=summary|decisions|full|extract] [--query=TEXT] [--mode=auto|prompt|json] [--out=FILE] [--depth=N] [--ext=LIST]');
+  return distill(dir, {
+    format: flags.format || 'summary',
+    query: typeof flags.query === 'string' ? flags.query : '',
+    mode: flags.mode || 'auto',
+    out: flags.out || null,
+    depth: flags.depth ? parseInt(flags.depth, 10) : 3,
+    ext: flags.ext || null,
+  });
+}
+
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  const dir = positional[0];
+  if (!dir) {
+    process.stderr.write('Usage: construct distill <dir> [--format=summary|decisions|full|extract] [--query=TEXT] [--mode=auto|prompt|json] [--out=FILE] [--depth=N] [--ext=LIST]\n');
+    process.exit(1);
+  }
+  distill(dir, {
+    format: flags.format || 'summary',
+    query: typeof flags.query === 'string' ? flags.query : '',
+    mode: flags.mode || 'auto',
+    out: flags.out || null,
+    depth: flags.depth ? parseInt(flags.depth, 10) : 3,
+    ext: flags.ext || null,
+  }).catch((err) => {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/lib/efficiency.mjs

@@ -0,0 +1,139 @@
+/**
+ * lib/efficiency.mjs — session read-efficiency reporting.
+ *
+ * Reads ~/.cx/session-efficiency.json, summarizes repeated/large reads, and
+ * formats actionable recommendations for the construct efficiency command.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const HIGH_BYTES_THRESHOLD = 750_000;
+const HIGH_REPEATED_RATIO = 0.4;
+const HIGH_LARGE_READ_COUNT = 3;
+
+export function readEfficiencyLog(homeDir) {
+  const filePath = join(homeDir, '.cx', 'session-efficiency.json');
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function topRepeatedFiles(files = {}) {
+  return Object.entries(files)
+    .map(([filePath, value]) => ({
+      path: filePath,
+      count: Number(value?.count || 0),
+      size: Number(value?.size || 0),
+      lastReadAt: value?.lastReadAt || null,
+    }))
+    .filter((entry) => entry.count > 1)
+    .sort((a, b) => b.count - a.count || b.size - a.size || a.path.localeCompare(b.path))
+    .slice(0, 10);
+}
+
+export function summarizeEfficiencyData(stats) {
+  if (!stats) {
+    return {
+      status: 'unavailable',
+      summary: 'No read-efficiency data recorded yet',
+      recommendation: 'Continue. Efficiency tracking will appear after file reads.',
+      readCount: 0,
+      uniqueFileCount: 0,
+      repeatedReadCount: 0,
+      largeReadCount: 0,
+      totalBytesRead: 0,
+      repeatedReadRatio: 0,
+      topRepeatedFiles: [],
+      lastUpdatedAt: null,
+    };
+  }
+
+  const readCount = Number(stats.readCount || 0);
+  const uniqueFileCount = Number(stats.uniqueFileCount || 0);
+  const repeatedReadCount = Number(stats.repeatedReadCount || 0);
+  const largeReadCount = Number(stats.largeReadCount || 0);
+  const totalBytesRead = Number(stats.totalBytesRead || 0);
+  const repeatedReadRatio = readCount > 0 ? Number((repeatedReadCount / readCount).toFixed(3)) : 0;
+  const repeatedFiles = topRepeatedFiles(stats.files);
+
+  let status = 'healthy';
+  let recommendation = 'Continue. Read pattern is compact enough for the current session.';
+  if (totalBytesRead >= HIGH_BYTES_THRESHOLD) {
+    status = 'degraded';
+    recommendation = 'Run construct distill with a focused query, then compact context before more broad exploration.';
+  } else if (repeatedReadRatio >= HIGH_REPEATED_RATIO || repeatedReadCount >= 5) {
+    status = 'degraded';
+    recommendation = 'Use rg to narrow the next file set, or run construct distill instead of re-reading the same files.';
+  } else if (largeReadCount >= HIGH_LARGE_READ_COUNT) {
+    status = 'configured';
+    recommendation = 'Prefer targeted reads under 400 lines before another large read.';
+  }
+
+  const summary = [
+    `${readCount} reads`,
+    `${uniqueFileCount} files`,
+    repeatedReadCount ? `${repeatedReadCount} repeated` : null,
+    largeReadCount ? `${largeReadCount} large` : null,
+    totalBytesRead ? `${Math.round(totalBytesRead / 1024)} KB` : null,
+  ].filter(Boolean).join(' · ');
+
+  return {
+    status,
+    summary,
+    recommendation,
+    readCount,
+    uniqueFileCount,
+    repeatedReadCount,
+    largeReadCount,
+    totalBytesRead,
+    repeatedReadRatio,
+    topRepeatedFiles: repeatedFiles,
+    lastUpdatedAt: stats.lastUpdatedAt || null,
+  };
+}
+
+export function buildCompactEfficiencyDigest(stats) {
+  const data = summarizeEfficiencyData(stats);
+  const repeated = data.topRepeatedFiles.slice(0, 3).map((file) => `${file.count}x ${file.path}`).join(' · ');
+
+  return {
+    ...data,
+    repeated,
+    compact: data.status === 'unavailable'
+      ? data.summary
+      : repeated
+        ? `${data.summary} · ${data.recommendation} · Hot spots: ${repeated}`
+        : `${data.summary} · ${data.recommendation}`,
+  };
+}
+
+export function formatEfficiencyReport(data, colors = {}) {
+  const C = { bold: '', dim: '', reset: '', green: '', yellow: '', red: '', ...colors };
+  const statusColor = data.status === 'healthy' ? C.green : data.status === 'configured' ? C.yellow : data.status === 'degraded' ? C.red : '';
+  const lines = [];
+  lines.push(`${C.bold}Construct Efficiency Report${C.reset}`);
+  lines.push('═══════════════════════════');
+  lines.push('');
+  lines.push(`Status:          ${statusColor}${data.status}${C.reset}`);
+  lines.push(`Reads:           ${data.readCount.toLocaleString()} (${data.uniqueFileCount.toLocaleString()} unique files)`);
+  lines.push(`Repeated reads:  ${data.repeatedReadCount.toLocaleString()} (${(data.repeatedReadRatio * 100).toFixed(1)}%)`);
+  lines.push(`Large reads:     ${data.largeReadCount.toLocaleString()}`);
+  lines.push(`Bytes read:      ${Math.round(data.totalBytesRead / 1024).toLocaleString()} KB`);
+  if (data.lastUpdatedAt) lines.push(`${C.dim}Last updated: ${data.lastUpdatedAt}${C.reset}`);
+  lines.push('');
+  lines.push(`Recommendation:  ${data.recommendation}`);
+
+  if (data.topRepeatedFiles.length > 0) {
+    lines.push('');
+    lines.push('Top Repeated Files:');
+    for (const file of data.topRepeatedFiles) {
+      lines.push(`  ${String(file.count).padStart(3)}x  ${file.path}`);
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}

package/lib/env-config.mjs

@@ -0,0 +1,53 @@
+/**
+ * lib/env-config.mjs — <one-line purpose>
+ *
+ * <2–6 line summary: what it does, who calls it, key side effects.>
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export function parseEnvFile(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return {};
+  const env = {};
+  for (const rawLine of fs.readFileSync(filePath, 'utf8').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    env[key] = rawValue.replace(/^["']|["']$/g, '');
+  }
+  return env;
+}
+
+export function getUserConfigDir(homeDir = os.homedir()) {
+  return path.join(homeDir, '.construct');
+}
+
+export function getUserEnvPath(homeDir = os.homedir()) {
+  return path.join(getUserConfigDir(homeDir), 'config.env');
+}
+
+export function ensureUserConfigDir(homeDir = os.homedir()) {
+  const dir = getUserConfigDir(homeDir);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function writeEnvValues(filePath, values = {}) {
+  const existing = parseEnvFile(filePath);
+  const merged = { ...existing, ...values };
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const content = Object.entries(merged)
+    .filter(([, value]) => value !== undefined && value !== null && value !== '')
+    .map(([key, value]) => `${key}=${value}`)
+    .join('\n');
+  fs.writeFileSync(filePath, `${content}\n`, 'utf8');
+}
+
+export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = process.env } = {}) {
+  const rootEnv = rootDir ? parseEnvFile(path.join(rootDir, '.env')) : {};
+  const userEnv = parseEnvFile(getUserEnvPath(homeDir));
+  return { ...rootEnv, ...userEnv, ...env };
+}

package/lib/eval-harness.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * lib/eval-harness.mjs — <one-line purpose>
+ *
+ * <2–6 line summary.>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.join(__dirname, "..");
+
+/**
+ * Basic evaluation harness for Construct agents.
+ * This script runs "dry runs" or simulated interactions against agent prompts
+ * to verify they would call the right tools or produce the right outcomes.
+ */
+
+export async function runEval(agentName, input, expectedPatterns = []) {
+  const registry = JSON.parse(fs.readFileSync(path.join(root, "agents", "registry.json"), "utf8"));
+  const agent = registry.agents.find(a => a.name === agentName) || 
+                registry.personas.find(p => p.name === agentName);
+  
+  if (!agent) throw new Error(`Agent ${agentName} not found in registry`);
+
+  // In a real production setup, this would call the LLM.
+  // For this harness, we are checking the "Static Intent" — 
+  // can the agent logically fulfill the request based on its prompt?
+  
+  const results = {
+    agent: agentName,
+    input,
+    passed: true,
+    findings: []
+  };
+
+  for (const pattern of expectedPatterns) {
+    const regex = new RegExp(pattern, "i");
+    const foundInPrompt = regex.test(agent.prompt || "");
+    const foundInShared = (registry.sharedGuidance || []).some(g => regex.test(g));
+    
+    if (!foundInPrompt && !foundInShared) {
+      results.passed = false;
+      results.findings.push(`MISSING: Pattern "${pattern}" not supported by agent prompt or shared guidance`);
+    } else {
+      results.findings.push(`OK: Pattern "${pattern}" is supported`);
+    }
+  }
+
+  return results;
+}
+
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  // Simple example run
+  const testAgent = process.argv[2] || "engineer";
+  const result = await runEval(testAgent, "Fix the bug", ["Edit", "Read", "Bash"]);
+  console.log(JSON.stringify(result, null, 2));
+}