@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/artifact-capture.mjs

@@ -0,0 +1,183 @@
+/**
+ * lib/artifact-capture.mjs — Automatic observation capture from session artifacts.
+ *
+ * At session end, extracts meaningful observations from the distilled session
+ * record and git state. Auto-populates the observation store so specialists
+ * build institutional memory over time.
+ *
+ * Invoked from stop-notify.mjs — best-effort, non-blocking.
+ */
+import { execSync } from 'node:child_process';
+import { basename } from 'node:path';
+import { addObservation } from './observation-store.mjs';
+import { createEntity, addRelatedEntity } from './entity-store.mjs';
+
+const MAX_DECISION_OBS = 5;
+const MAX_FILE_PATTERNS = 10;
+
+/**
+ * Capture observations from a completed session record.
+ * Returns the list of created observation IDs.
+ */
+export async function captureSessionArtifacts(rootDir, session) {
+  if (!session) return [];
+  const ids = [];
+  const project = session.project || basename(rootDir);
+
+  // Resolve current HEAD SHA for observation provenance (best effort)
+  let gitSha = null;
+  try {
+    gitSha = execSync(`git -C "${rootDir}" rev-parse HEAD 2>/dev/null`, { timeout: 3000 }).toString().trim().slice(0, 40) || null;
+  } catch { /* not a git repo */ }
+
+  // Only record a session-summary observation when the content is meaningful.
+  // Trivially short summaries (≤25 chars) or known placeholder patterns are skipped
+  // to prevent the observation store filling with noise like "IMPLEMENT: done".
+  const PLACEHOLDER_RE = /^(implement|done|completed|session completed|in_progress)[\s:.]*(done|ok|completed)?$/i;
+  if (session.summary && session.summary.length > 10 && !PLACEHOLDER_RE.test(session.summary.trim())) {
+    const obs = await addObservation(rootDir, {
+      role: 'construct',
+      category: 'session-summary',
+      summary: session.summary,
+      content: buildSessionContent(session),
+      tags: [project, 'session'],
+      project,
+      confidence: 0.9,
+      source: { session: session.id },
+      gitSha,
+    });
+    if (obs) ids.push(obs.id);
+  }
+
+  if (session.decisions?.length) {
+    for (const decision of session.decisions.slice(0, MAX_DECISION_OBS)) {
+      const obs = await addObservation(rootDir, {
+        role: 'construct',
+        category: 'decision',
+        summary: decision,
+        content: decision,
+        tags: [project, 'decision'],
+        project,
+        confidence: 0.85,
+        source: { session: session.id },
+        gitSha,
+      });
+      if (obs) ids.push(obs.id);
+    }
+  }
+
+  if (session.filesChanged?.length) {
+    const patterns = extractFilePatterns(session.filesChanged);
+    for (const pattern of patterns.slice(0, MAX_FILE_PATTERNS)) {
+      createEntity(rootDir, {
+        name: pattern.name,
+        type: 'file-group',
+        summary: pattern.summary,
+        project,
+        observationIds: ids,
+      });
+    }
+  }
+
+  return ids;
+}
+
+/**
+ * Analyze git log for co-change patterns and record as entity relationships.
+ * Runs git commands — returns empty on failure.
+ */
+export function captureDependencyPatterns(rootDir) {
+  const coChanges = new Map();
+
+  try {
+    const commits = execSync(
+      `git -C "${rootDir}" log --format='%H' -20 2>/dev/null`,
+      { timeout: 10000 },
+    ).toString().trim().split('\n').filter(Boolean);
+
+    for (const sha of commits) {
+      try {
+        const files = execSync(
+          `git -C "${rootDir}" diff-tree --no-commit-id --name-only -r ${sha} 2>/dev/null`,
+          { timeout: 5000 },
+        ).toString().trim().split('\n').filter(Boolean);
+
+        const dirs = [...new Set(files.map((f) => f.split('/').slice(0, 2).join('/')))];
+        for (let i = 0; i < dirs.length; i++) {
+          for (let j = i + 1; j < dirs.length; j++) {
+            const key = [dirs[i], dirs[j]].sort().join('↔');
+            coChanges.set(key, (coChanges.get(key) || 0) + 1);
+          }
+        }
+      } catch { /* individual commit failure is fine */ }
+    }
+  } catch { /* git not available or not a repo */ }
+
+  const relationships = [];
+  for (const [key, count] of coChanges) {
+    if (count >= 3) {
+      const [a, b] = key.split('↔');
+      relationships.push({ a, b, count });
+
+      createEntity(rootDir, {
+        name: a,
+        type: 'file-group',
+        summary: `Directory group: ${a}`,
+        project: basename(rootDir),
+      });
+      createEntity(rootDir, {
+        name: b,
+        type: 'file-group',
+        summary: `Directory group: ${b}`,
+        project: basename(rootDir),
+      });
+      addRelatedEntity(rootDir, a, b);
+    }
+  }
+
+  return relationships;
+}
+
+function buildSessionContent(session) {
+  const parts = [];
+  if (session.summary) parts.push(session.summary);
+
+  if (session.decisions?.length) {
+    parts.push('Decisions: ' + session.decisions.join('; '));
+  }
+
+  if (session.filesChanged?.length) {
+    const files = session.filesChanged
+      .slice(0, 10)
+      .map((f) => `${f.path} (${f.reason || 'modified'})`)
+      .join(', ');
+    parts.push('Files: ' + files);
+  }
+
+  if (session.openQuestions?.length) {
+    parts.push('Open: ' + session.openQuestions.join('; '));
+  }
+
+  return parts.join('\n');
+}
+
+function extractFilePatterns(filesChanged) {
+  const dirCounts = new Map();
+  for (const file of filesChanged) {
+    const dir = String(file.path || '').split('/').slice(0, 2).join('/');
+    if (dir) {
+      const entry = dirCounts.get(dir) || { count: 0, reasons: new Set() };
+      entry.count += 1;
+      if (file.reason) entry.reasons.add(file.reason);
+      dirCounts.set(dir, entry);
+    }
+  }
+
+  return [...dirCounts]
+    .filter(([, v]) => v.count >= 2)
+    .sort(([, a], [, b]) => b.count - a.count)
+    .map(([dir, v]) => ({
+      name: dir,
+      summary: `${v.count} files changed: ${[...v.reasons].slice(0, 3).join(', ') || 'various changes'}`,
+    }));
+}

package/lib/audit-trail.mjs

@@ -0,0 +1,149 @@
+/**
+ * lib/audit-trail.mjs — reads the append-only audit log produced by
+ * lib/hooks/audit-trail.mjs and renders it for `construct audit trail`.
+ *
+ * The log is JSONL at ~/.cx/audit-trail.jsonl. Each line carries a
+ * prev_line_hash pointing at the SHA-256 of the previous line — tampering
+ * (reorder, delete, edit) breaks the chain and is surfaced by --verify.
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const AUDIT_FILE = join(homedir(), '.cx', 'audit-trail.jsonl');
+
+function sha256(input) {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+export function readAuditTrail({ limit = 50, since = null, agent = null, tool = null } = {}) {
+  if (!existsSync(AUDIT_FILE)) return [];
+  const lines = readFileSync(AUDIT_FILE, 'utf8').split('\n').filter(Boolean);
+  const sinceMs = since ? new Date(since).getTime() : 0;
+  const filtered = [];
+  for (const line of lines) {
+    try {
+      const row = JSON.parse(line);
+      if (sinceMs && new Date(row.ts).getTime() < sinceMs) continue;
+      if (agent && row.agent !== agent) continue;
+      if (tool && row.tool !== tool) continue;
+      filtered.push(row);
+    } catch { /* skip malformed */ }
+  }
+  return filtered.slice(-limit);
+}
+
+export function verifyChain() {
+  if (!existsSync(AUDIT_FILE)) return { ok: true, verified: 0, broken: [] };
+  const lines = readFileSync(AUDIT_FILE, 'utf8').split('\n').filter(Boolean);
+  const broken = [];
+  let prevHash = null;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    let row;
+    try { row = JSON.parse(line); } catch {
+      broken.push({ line: i + 1, reason: 'malformed JSON' });
+      continue;
+    }
+    if (i > 0 && row.prev_line_hash !== prevHash) {
+      broken.push({
+        line: i + 1,
+        expected: prevHash,
+        actual: row.prev_line_hash,
+        reason: 'prev_line_hash mismatch — chain break',
+      });
+    }
+    prevHash = sha256(line);
+  }
+  return { ok: broken.length === 0, verified: lines.length, broken };
+}
+
+function formatRow(row) {
+  const ts = row.ts?.replace('T', ' ').replace('Z', '') || '?';
+  const agent = (row.agent || '?').padEnd(22);
+  const tool = (row.tool || '?').padEnd(12);
+  const task = row.task?.key ? `task=${row.task.key}` : '';
+  const target = row.target || '';
+  return `${ts}  ${agent}  ${tool}  ${task}${task && target ? '  ' : ''}${target}`;
+}
+
+export async function runAuditTrailCli(args = []) {
+  const flags = new Set();
+  const options = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--verify') flags.add('verify');
+    else if (arg === '--json') flags.add('json');
+    else if (arg === '--all') flags.add('all');
+    else if (arg.startsWith('--limit=')) options.limit = Number(arg.slice(8));
+    else if (arg === '--limit') options.limit = Number(args[++i]);
+    else if (arg.startsWith('--since=')) options.since = arg.slice(8);
+    else if (arg === '--since') options.since = args[++i];
+    else if (arg.startsWith('--agent=')) options.agent = arg.slice(8);
+    else if (arg === '--agent') options.agent = args[++i];
+    else if (arg.startsWith('--tool=')) options.tool = arg.slice(7);
+    else if (arg === '--tool') options.tool = args[++i];
+    else if (arg === '--help' || arg === '-h') flags.add('help');
+  }
+
+  if (flags.has('help')) {
+    console.log(`Usage: construct audit trail [options]
+
+Options:
+  --limit N         Show only the last N records (default: 50, --all for everything)
+  --all             Show all records
+  --since <iso>     Filter to records on or after an ISO timestamp
+  --agent <name>    Filter to a specific agent (e.g. cx-engineer)
+  --tool <name>     Filter to a specific tool (Edit, Write, MultiEdit, NotebookEdit, Bash)
+  --verify          Verify the tamper-evidence chain and exit
+  --json            Emit raw JSONL lines instead of formatted output
+  -h, --help        Show this message
+
+Log location: ${AUDIT_FILE}
+`);
+    return;
+  }
+
+  if (flags.has('verify')) {
+    const result = verifyChain();
+    if (result.ok) {
+      console.log(`Audit chain OK — ${result.verified} records verified.`);
+      return;
+    }
+    console.error(`Audit chain BROKEN — ${result.broken.length} issue${result.broken.length === 1 ? '' : 's'} across ${result.verified} records:`);
+    for (const b of result.broken) {
+      console.error(`  line ${b.line}: ${b.reason}`);
+    }
+    process.exit(1);
+  }
+
+  if (!existsSync(AUDIT_FILE)) {
+    console.log(`No audit trail yet. Log will appear at ${AUDIT_FILE} once mutations occur.`);
+    return;
+  }
+
+  const rows = readAuditTrail({
+    limit: flags.has('all') ? Infinity : (options.limit || 50),
+    since: options.since,
+    agent: options.agent,
+    tool: options.tool,
+  });
+
+  if (rows.length === 0) {
+    console.log('No audit records match the current filter.');
+    return;
+  }
+
+  if (flags.has('json')) {
+    for (const r of rows) console.log(JSON.stringify(r));
+    return;
+  }
+
+  const size = statSync(AUDIT_FILE).size;
+  console.log(`Audit trail — ${rows.length} record${rows.length === 1 ? '' : 's'} (log ${Math.round(size / 1024)} KB at ${AUDIT_FILE})`);
+  console.log('─'.repeat(100));
+  for (const r of rows) console.log(formatRow(r));
+  console.log('');
+  console.log('Use --json for full records, --verify to check the tamper-evidence chain.');
+}