amalgm 0.1.88 → 0.1.89

package/runtime/scripts/amalgm-mcp/project-context/store.js

@@ -0,0 +1,671 @@
+'use strict';
+
+/**
+ * Project context store — the canonical mutation path for project memory.
+ *
+ * Files stay human-readable on disk, but every write should flow through this
+ * store so timestamps, revisions, the SQLite `project_context` row, and Local
+ * Live events stay coherent:
+ *
+ *   change-log.md     append-only via appendChangeLog (runtime owns the
+ *                     timestamp; entries land directly under the title)
+ *   project-state.md  latest write wins; revision kept as metadata only
+ *   instructions.md   user-authored; latest write wins via the UI path
+ *
+ * Direct disk edits (editors, agents with their own file tools) are picked up
+ * by the per-project fs watcher and the fs REST hooks, which funnel into the
+ * same reconcile path. Reconcile is idempotent: unchanged revisions emit no
+ * events.
+ *
+ * Everything that emits events runs in the amalgm-mcp process — Local Live
+ * only streams events appended in-process. chat-core (chat-server process)
+ * must stay read-only against this table.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const { openLocalDb } = require('../state/db');
+const { insertStateEvent, publishStateEvent } = require('../state/events');
+const { AMALGM_DIR } = require('../config');
+const { canonicalProjectPath } = require('../../lib/project-paths');
+const {
+  CHANGE_LOG_TITLE,
+  INSTRUCTIONS_TITLE,
+  PROJECT_STATE_TITLE,
+  changeLogEntryHeading,
+  changeLogRecentWindow,
+  cappedDocContent,
+  contextPaths,
+  insertChangeLogEntry,
+  isEmptyContextDoc,
+  latestChangeLogEntry,
+  localTimestamp,
+  projectPathForContextPath,
+  sanitizeChangeLogBody,
+} = require('./paths');
+
+const RESOURCE = 'project_context';
+const WATCH_DEBOUNCE_MS = 200;
+// The system scope carries user-authored instructions that apply to every
+// session on this computer. It has no change log or project state.
+const SYSTEM_CONTEXT_ID = 'system';
+
+const watchers = new Map(); // projectId -> { watcher, timer, projectPath }
+
+function systemProject() {
+  return { id: SYSTEM_CONTEXT_ID, path: path.resolve(AMALGM_DIR), name: 'Amalgm System' };
+}
+
+function systemContextPaths() {
+  // AMALGM_DIR *is* the .amalgm dir, so the system context sits directly
+  // under it — no extra .amalgm segment like project contexts have.
+  const root = path.join(path.resolve(AMALGM_DIR), 'context');
+  return { root, instructions: path.join(root, 'instructions.md') };
+}
+
+function isSystemProject(project) {
+  return project?.id === SYSTEM_CONTEXT_ID;
+}
+
+/**
+ * Containment check against the system context dir that tolerates symlinked
+ * roots (macOS /var vs /private/var): compare both the configured and the
+ * realpathed form.
+ */
+function isWithinSystemContext(targetPath) {
+  const resolved = cleanString(targetPath) ? path.resolve(targetPath) : '';
+  if (!resolved) return false;
+  const systemRoot = systemContextPaths().root;
+  const candidates = new Set([systemRoot]);
+  try {
+    candidates.add(fs.realpathSync(systemRoot));
+  } catch {
+    // Dir may not exist yet.
+  }
+  let realTarget = resolved;
+  try {
+    realTarget = fs.realpathSync(resolved);
+  } catch {
+    // Path may not exist; compare the resolved string.
+  }
+  for (const root of candidates) {
+    if (resolved === root || isWithin(root, resolved)) return true;
+    if (realTarget === root || isWithin(root, realTarget)) return true;
+  }
+  return false;
+}
+
+function contextPathsFor(project) {
+  return isSystemProject(project) ? systemContextPaths() : contextPaths(project.path);
+}
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function hash(value) {
+  return crypto.createHash('sha256').update(String(value ?? '')).digest('hex');
+}
+
+function isWithin(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/**
+ * Map any path to the registered workspace that contains it (deepest wins).
+ * The system, not the model, owns project identity — tool callers may pass a
+ * cwd or any path inside a project and land on the canonical workspace.
+ */
+function resolveProject(inputPath) {
+  const expanded = canonicalProjectPath(inputPath);
+  if (!expanded) return null;
+  let resolved = expanded;
+  try {
+    resolved = fs.realpathSync(expanded);
+  } catch {
+    // Path may not exist (yet); match on the resolved string.
+  }
+  // The system context dir is more specific than any workspace — check first.
+  if (isWithinSystemContext(resolved)) {
+    return systemProject();
+  }
+  let workspaces = [];
+  try {
+    workspaces = require('../workspace/store').listWorkspaces();
+  } catch {
+    return null;
+  }
+  let best = null;
+  for (const workspace of workspaces) {
+    if (!workspace?.path) continue;
+    if (!isWithin(workspace.path, resolved)) continue;
+    if (!best || String(workspace.path).length > String(best.path).length) best = workspace;
+  }
+  if (!best) return null;
+  return { id: best.id, path: best.path, name: best.name || path.basename(best.path) };
+}
+
+function projectFromInput(input) {
+  if (input && typeof input === 'object' && cleanString(input.path)) {
+    return {
+      id: cleanString(input.id) || null,
+      path: path.resolve(input.path),
+      name: cleanString(input.name) || path.basename(path.resolve(input.path)),
+    };
+  }
+  return resolveProject(input);
+}
+
+function atomicWrite(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmpPath, content, 'utf8');
+  fs.renameSync(tmpPath, filePath);
+}
+
+function readDoc(filePath) {
+  let content = '';
+  let stat = null;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+    stat = fs.statSync(filePath);
+  } catch {
+    return { content: '', revision: hash('').slice(0, 16), exists: false, empty: true, size: 0, mtimeMs: 0, updatedAt: null };
+  }
+  return {
+    content,
+    revision: hash(content).slice(0, 16),
+    exists: true,
+    empty: isEmptyContextDoc(content),
+    size: stat.size,
+    mtimeMs: Math.round(stat.mtimeMs),
+    updatedAt: stat.mtime.toISOString(),
+  };
+}
+
+function statFingerprint(paths) {
+  return [paths.instructions, paths.changeLog, paths.projectState]
+    .filter(Boolean)
+    .map((filePath) => {
+      try {
+        const stat = fs.statSync(filePath);
+        return `${Math.round(stat.mtimeMs)}:${stat.size}`;
+      } catch {
+        return 'missing';
+      }
+    })
+    .join('|');
+}
+
+function docMeta(doc) {
+  return {
+    revision: doc.revision,
+    exists: doc.exists,
+    empty: doc.empty,
+    size: doc.size,
+    updatedAt: doc.updatedAt,
+  };
+}
+
+function buildContextRecord(project) {
+  if (isSystemProject(project)) {
+    const paths = systemContextPaths();
+    const instructions = readDoc(paths.instructions);
+    return {
+      id: SYSTEM_CONTEXT_ID,
+      projectId: SYSTEM_CONTEXT_ID,
+      kind: 'system',
+      name: project.name || 'Amalgm System',
+      projectPath: project.path,
+      contextRevision: hash(instructions.revision).slice(0, 20),
+      statFingerprint: statFingerprint(paths),
+      paths,
+      files: {
+        instructions: docMeta(instructions),
+      },
+      prompt: {
+        instructions: instructions.empty ? '' : cappedDocContent(instructions.content),
+      },
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  const paths = contextPaths(project.path);
+  const instructions = readDoc(paths.instructions);
+  const changeLog = readDoc(paths.changeLog);
+  const projectState = readDoc(paths.projectState);
+  const latestEntry = latestChangeLogEntry(changeLog.content);
+  const contextRevision = hash(
+    [instructions.revision, changeLog.revision, projectState.revision].join(':'),
+  ).slice(0, 20);
+
+  return {
+    id: project.id,
+    projectId: project.id,
+    kind: 'project',
+    name: project.name,
+    projectPath: project.path,
+    contextRevision,
+    statFingerprint: statFingerprint(paths),
+    paths,
+    files: {
+      instructions: docMeta(instructions),
+      changeLog: {
+        ...docMeta(changeLog),
+        latestEntryAt: latestEntry.iso,
+        latestEntryAtMs: latestEntry.ms,
+      },
+      projectState: docMeta(projectState),
+    },
+    prompt: {
+      instructions: instructions.empty ? '' : cappedDocContent(instructions.content),
+      projectState: projectState.empty ? '' : cappedDocContent(projectState.content),
+      changeLogRecent: changeLog.empty ? '' : changeLogRecentWindow(changeLog.content),
+    },
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function parseRow(row) {
+  if (!row) return null;
+  try {
+    return JSON.parse(row.context_json);
+  } catch {
+    return null;
+  }
+}
+
+function readContextRow(projectId) {
+  if (!projectId) return null;
+  const row = openLocalDb()
+    .prepare('SELECT * FROM project_context WHERE project_id = ?')
+    .get(projectId);
+  return parseRow(row);
+}
+
+function upsertContextRow(record, options = {}) {
+  const db = openLocalDb();
+  let event = null;
+  db.transaction(() => {
+    db.prepare(`
+      INSERT INTO project_context (project_id, project_path, context_revision, updated_at, context_json)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(project_id) DO UPDATE SET
+        project_path = excluded.project_path,
+        context_revision = excluded.context_revision,
+        updated_at = excluded.updated_at,
+        context_json = excluded.context_json
+    `).run(record.projectId, record.projectPath, record.contextRevision, record.updatedAt, JSON.stringify(record));
+    event = insertStateEvent(db, {
+      resource: RESOURCE,
+      op: 'update',
+      id: record.projectId,
+      value: record,
+      source: options.source || 'project-context',
+    });
+  })();
+  publishStateEvent(event);
+  return record;
+}
+
+/**
+ * Bring the SQLite row in line with disk. Cheap when nothing moved: a stat
+ * fingerprint short-circuits before any file is read, and an unchanged
+ * contextRevision emits no event.
+ */
+function reconcileProjectContext(input, options = {}) {
+  const project = projectFromInput(input);
+  if (!project) return null;
+  if (!project.id) {
+    const registered = resolveProject(project.path);
+    if (!registered) return null;
+    project.id = registered.id;
+    project.path = registered.path;
+    project.name = registered.name;
+  }
+
+  const existing = readContextRow(project.id);
+  if (!options.force && existing?.statFingerprint === statFingerprint(contextPathsFor(project))) {
+    return existing;
+  }
+
+  const record = buildContextRecord(project);
+  if (!options.force && existing?.contextRevision === record.contextRevision) {
+    // Content identical; refresh the fingerprint quietly so the fast path
+    // works next time (e.g. after a touch with no content change).
+    if (existing.statFingerprint !== record.statFingerprint) {
+      openLocalDb()
+        .prepare('UPDATE project_context SET context_json = ? WHERE project_id = ?')
+        .run(JSON.stringify({ ...existing, statFingerprint: record.statFingerprint }), project.id);
+    }
+    return existing;
+  }
+  return upsertContextRow(record, options);
+}
+
+const INSTRUCTIONS_TEMPLATE = `${INSTRUCTIONS_TITLE}\n`;
+const CHANGE_LOG_TEMPLATE = `${CHANGE_LOG_TITLE}\n`;
+const PROJECT_STATE_TEMPLATE = `${PROJECT_STATE_TITLE}\n`;
+
+function ensureContextFiles(project) {
+  const paths = contextPathsFor(project);
+  const docs = isSystemProject(project)
+    ? [[paths.instructions, INSTRUCTIONS_TEMPLATE]]
+    : [
+      [paths.instructions, INSTRUCTIONS_TEMPLATE],
+      [paths.changeLog, CHANGE_LOG_TEMPLATE],
+      [paths.projectState, PROJECT_STATE_TEMPLATE],
+    ];
+  const created = [];
+  fs.mkdirSync(paths.root, { recursive: true });
+  for (const [filePath, template] of docs) {
+    if (!fs.existsSync(filePath)) {
+      atomicWrite(filePath, template);
+      created.push(filePath);
+    }
+  }
+  return created;
+}
+
+/**
+ * Registration-time setup: create the context folder (additive — never touches
+ * .gitignore or any existing file), sync the row, and start watching.
+ */
+function ensureProjectContext(workspace, options = {}) {
+  const project = projectFromInput(workspace);
+  if (!project?.id || !project?.path) return null;
+  try {
+    ensureContextFiles(project);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[ProjectContext] Could not create context files for ${project.path}: ${message}`);
+    return null;
+  }
+  const record = reconcileProjectContext(project, {
+    source: options.source || 'project-context:ensure',
+  });
+  watchProjectContext(project);
+  return record;
+}
+
+function getProjectContext(inputPath, options = {}) {
+  const project = projectFromInput(inputPath);
+  if (!project?.id) return null;
+  if (options.reconcile === false) return readContextRow(project.id);
+  return reconcileProjectContext(project, { source: options.source || 'project-context:read' });
+}
+
+/**
+ * Read-only freshness: the stored row when disk hasn't moved, otherwise a
+ * record built straight from disk with NO row/event write. Prompt composition
+ * runs in the chat-server process, which must not publish Local Live events —
+ * only the amalgm-mcp process streams them.
+ */
+function peekProjectContext(inputPath) {
+  const project = projectFromInput(inputPath);
+  if (!project?.id) return null;
+  const existing = readContextRow(project.id);
+  if (existing?.statFingerprint === statFingerprint(contextPathsFor(project))) {
+    return existing;
+  }
+  return buildContextRecord(project);
+}
+
+function listProjectContexts(options = {}) {
+  let workspaces = [];
+  try {
+    workspaces = require('../workspace/store').listWorkspaces();
+  } catch {
+    return [];
+  }
+  const records = [];
+  try {
+    const system = options.reconcile === false
+      ? readContextRow(SYSTEM_CONTEXT_ID)
+      : reconcileProjectContext(systemProject(), { source: 'project-context:list' });
+    if (system) records.push(system);
+  } catch {
+    // System context is best-effort; projects still list.
+  }
+  for (const workspace of workspaces) {
+    if (!workspace?.path) continue;
+    try {
+      const record = options.reconcile === false
+        ? readContextRow(workspace.id)
+        : reconcileProjectContext(workspace, { source: 'project-context:list' });
+      if (record) records.push(record);
+    } catch {
+      // One broken project must not take down the snapshot.
+    }
+  }
+  return records;
+}
+
+/**
+ * Append-only change-log write. The model supplies the body; the runtime owns
+ * the timestamp (local time with offset + IANA zone), placement directly under
+ * the title, the row update, and the Local Live event.
+ */
+function appendChangeLog(inputPath, body, options = {}) {
+  const project = projectFromInput(inputPath);
+  if (!project?.id) {
+    throw new Error(`No registered Amalgm project contains: ${cleanString(typeof inputPath === 'string' ? inputPath : inputPath?.path) || '(no path)'}`);
+  }
+  if (isSystemProject(project)) {
+    throw new Error('The system context has instructions only — change logs are per-project.');
+  }
+  const entryBody = sanitizeChangeLogBody(body);
+  if (!entryBody) throw new Error('Change log entry body is required');
+
+  ensureContextFiles(project);
+  const stamp = localTimestamp();
+  const entry = `${changeLogEntryHeading(stamp)}\n\n${entryBody}`;
+  const filePath = contextPaths(project.path).changeLog;
+  let current = '';
+  try {
+    current = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    current = '';
+  }
+  atomicWrite(filePath, insertChangeLogEntry(current, entry));
+  const record = reconcileProjectContext(project, {
+    force: true,
+    source: options.source || 'project-context:append-change-log',
+  });
+  watchProjectContext(project);
+  return { project, entry, timestamp: stamp, record };
+}
+
+function writeContextDoc(inputPath, docKey, content, options = {}) {
+  const project = projectFromInput(inputPath);
+  if (!project?.id) {
+    throw new Error(`No registered Amalgm project contains: ${cleanString(typeof inputPath === 'string' ? inputPath : inputPath?.path) || '(no path)'}`);
+  }
+  if (isSystemProject(project) && docKey !== 'instructions') {
+    throw new Error('The system context has instructions only — change logs and project state are per-project.');
+  }
+  if (typeof content !== 'string') throw new Error('content must be a string');
+  ensureContextFiles(project);
+  const filePath = contextPathsFor(project)[docKey];
+  const normalized = content.replace(/\r\n/g, '\n');
+  atomicWrite(filePath, normalized.endsWith('\n') || normalized === '' ? normalized : `${normalized}\n`);
+  const record = reconcileProjectContext(project, {
+    force: true,
+    source: options.source || `project-context:write-${docKey}`,
+  });
+  watchProjectContext(project);
+  return { project, record };
+}
+
+/** project-state.md: latest write wins; revision is metadata, not a lock. */
+function writeProjectState(inputPath, content, options = {}) {
+  return writeContextDoc(inputPath, 'projectState', content, {
+    source: options.source || 'project-context:write-project-state',
+  });
+}
+
+/** instructions.md: user-authored; latest write wins via the UI path. */
+function writeInstructions(inputPath, content, options = {}) {
+  return writeContextDoc(inputPath, 'instructions', content, {
+    source: options.source || 'project-context:write-instructions',
+  });
+}
+
+/**
+ * change-log.md full write — the human curation path (UI editor). Agents must
+ * use appendChangeLog; this exists so the user can prune or fix history.
+ */
+function writeChangeLog(inputPath, content, options = {}) {
+  return writeContextDoc(inputPath, 'changeLog', content, {
+    source: options.source || 'project-context:write-change-log',
+  });
+}
+
+function removeProjectContext(projectId, options = {}) {
+  if (!projectId || projectId === SYSTEM_CONTEXT_ID) return;
+  closeWatcher(projectId);
+  const db = openLocalDb();
+  let event = null;
+  db.transaction(() => {
+    const removed = db.prepare('DELETE FROM project_context WHERE project_id = ?').run(projectId);
+    if (removed.changes > 0) {
+      event = insertStateEvent(db, {
+        resource: RESOURCE,
+        op: 'delete',
+        id: projectId,
+        source: options.source || 'project-context:remove',
+      });
+    }
+  })();
+  publishStateEvent(event);
+}
+
+function closeWatcher(projectId) {
+  const entry = watchers.get(projectId);
+  if (!entry) return;
+  if (entry.timer) clearTimeout(entry.timer);
+  try {
+    entry.watcher.close();
+  } catch {
+    // Already closed.
+  }
+  watchers.delete(projectId);
+}
+
+/**
+ * Watch a project's context dir so out-of-band edits (VS Code, agents with
+ * their own file tools) reconcile into the canonical row. Self-writes are
+ * harmless: by the time the debounce fires, disk matches the row and no event
+ * is emitted.
+ */
+function watchProjectContext(input) {
+  const project = projectFromInput(input);
+  if (!project?.id || !project?.path) return;
+  const existing = watchers.get(project.id);
+  if (existing?.projectPath === project.path) return;
+  if (existing) closeWatcher(project.id);
+
+  const root = contextPathsFor(project).root;
+  let watcher;
+  try {
+    watcher = fs.watch(root, { persistent: false }, () => {
+      const entry = watchers.get(project.id);
+      if (!entry) return;
+      if (entry.timer) clearTimeout(entry.timer);
+      entry.timer = setTimeout(() => {
+        entry.timer = null;
+        try {
+          reconcileProjectContext(project, { source: 'project-context:watch' });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          console.warn(`[ProjectContext] Watch reconcile failed for ${project.path}: ${message}`);
+        }
+      }, WATCH_DEBOUNCE_MS);
+      if (typeof entry.timer.unref === 'function') entry.timer.unref();
+    });
+  } catch {
+    // Context dir missing or unwatchable — best effort; REST hooks still cover writes.
+    return;
+  }
+  watcher.on('error', () => closeWatcher(project.id));
+  if (typeof watcher.unref === 'function') watcher.unref();
+  watchers.set(project.id, { watcher, timer: null, projectPath: project.path });
+}
+
+/** fs REST hook: reconcile when a context doc is touched outside the store. */
+function notifyProjectContextPathChanged(filePath, source = 'fs') {
+  try {
+    if (isWithinSystemContext(filePath)) {
+      reconcileProjectContext(systemProject(), { source: `project-context:${source}` });
+      watchProjectContext(systemProject());
+      return;
+    }
+    const projectPath = projectPathForContextPath(filePath);
+    if (!projectPath) return;
+    const project = resolveProject(projectPath);
+    if (!project) return;
+    reconcileProjectContext(project, { source: `project-context:${source}` });
+    watchProjectContext(project);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[ProjectContext] Reconcile after ${source} failed: ${message}`);
+  }
+}
+
+/**
+ * Boot-time pass: every registered workspace gets context files, a fresh row,
+ * and a watcher. Existing projects registered before this feature are picked
+ * up here.
+ */
+function startProjectContextService() {
+  try {
+    ensureProjectContext(systemProject(), { source: 'project-context:boot' });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[ProjectContext] System context setup failed: ${message}`);
+  }
+  let workspaces = [];
+  try {
+    workspaces = require('../workspace/store').listWorkspaces();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[ProjectContext] Could not list workspaces at boot: ${message}`);
+    return;
+  }
+  for (const workspace of workspaces) {
+    if (!workspace?.path) continue;
+    try {
+      if (!fs.existsSync(workspace.path)) continue;
+      ensureProjectContext(workspace, { source: 'project-context:boot' });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[ProjectContext] Boot setup failed for ${workspace.path}: ${message}`);
+    }
+  }
+}
+
+function stopProjectContextService() {
+  for (const projectId of Array.from(watchers.keys())) closeWatcher(projectId);
+}
+
+module.exports = {
+  RESOURCE,
+  appendChangeLog,
+  ensureProjectContext,
+  getProjectContext,
+  listProjectContexts,
+  notifyProjectContextPathChanged,
+  peekProjectContext,
+  reconcileProjectContext,
+  removeProjectContext,
+  resolveProject,
+  startProjectContextService,
+  stopProjectContextService,
+  watchProjectContext,
+  writeChangeLog,
+  writeInstructions,
+  writeProjectState,
+};