@smartmemory/compose 0.1.0

package/server/settings-routes.js

@@ -0,0 +1,35 @@
+/**
+ * settings-routes.js — Settings REST API.
+ *
+ * Routes:
+ *   GET    /api/settings        — current merged settings
+ *   PATCH  /api/settings        — partial update
+ *   POST   /api/settings/reset  — reset all or a section
+ */
+
+/**
+ * @param {object} app — Express app
+ * @param {{ settingsStore: object, broadcastMessage: function }} deps
+ */
+export function attachSettingsRoutes(app, { settingsStore, broadcastMessage }) {
+  app.get('/api/settings', (_req, res) => {
+    res.json(settingsStore.get());
+  });
+
+  app.patch('/api/settings', (req, res) => {
+    try {
+      const updated = settingsStore.update(req.body);
+      broadcastMessage({ type: 'settingsUpdated', settings: updated });
+      res.json(updated);
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/settings/reset', (req, res) => {
+    const section = req.body?.section || undefined;
+    const updated = settingsStore.reset(section);
+    broadcastMessage({ type: 'settingsUpdated', settings: updated });
+    res.json(updated);
+  });
+}

package/server/settings-store.js

@@ -0,0 +1,234 @@
+/**
+ * Settings Store — JSON-file-backed storage for user preferences.
+ * Loads from disk on startup, saves after every mutation.
+ * Returns merged view: contract defaults + user overrides.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDataDir as getDefaultDataDir } from './project-root.js';
+
+const VALID_VIEWS = ['graph', 'tree', 'pipeline', 'gates', 'docs', 'design', 'sessions', 'settings'];
+const VALID_THEMES = ['light', 'dark', 'system'];
+const VALID_THINKING_MODES = ['adaptive', 'off'];
+const VALID_EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+export class SettingsStore {
+  constructor(dataDir, contract) {
+    const dir = dataDir || getDefaultDataDir();
+    this._file = path.join(dir, 'settings.json');
+    this._contract = contract;
+    this._userSettings = {};
+    this._load();
+  }
+
+  _load() {
+    try {
+      const raw = fs.readFileSync(this._file, 'utf-8');
+      this._userSettings = JSON.parse(raw);
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        console.error('[settings] Failed to load settings, using defaults:', err.message);
+      }
+      this._userSettings = {};
+    }
+  }
+
+  _save() {
+    try {
+      fs.mkdirSync(path.dirname(this._file), { recursive: true });
+      fs.writeFileSync(this._file, JSON.stringify(this._userSettings, null, 2), 'utf-8');
+    } catch (err) {
+      console.error('[settings] Failed to save settings:', err.message);
+    }
+  }
+
+  _defaults() {
+    return {
+      policies: Object.fromEntries(
+        this._contract.phases.map(p => [p.id, p.defaultPolicy])
+      ),
+      iterations: { ...this._contract.iterationDefaults },
+      models: {
+        interactive: 'claude-sonnet-4-6',
+        agentRun: process.env.CLAUDE_MODEL || 'claude-sonnet-4-6',
+        summarizer: process.env.SUMMARIZER_MODEL || 'haiku',
+      },
+      ui: { theme: 'system', defaultView: 'graph' },
+      // COMP-CAPS-ENFORCE: runtime capability enforcement policy
+      capabilities: { enforcement: 'log' },
+      // COMP-HEALTH: quantified quality score settings
+      health: {
+        enabled: true,
+        gate_threshold: null, // null = off, number = min_score required
+        weights: {},          // dimension weight overrides (must sum to 1.0 ± 0.01)
+      },
+      // Claude thinking/effort controls. mode='tier' inherits the tier default
+      // (critical → adaptive+xhigh, standard → adaptive+high, fast → off).
+      // effort=null likewise inherits the tier default.
+      thinking: {
+        mode: 'tier',    // 'tier' | 'adaptive' | 'off'
+        effort: null,    // null (tier default) | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+      },
+    };
+  }
+
+  /** Returns merged defaults + user overrides. */
+  get() {
+    const defaults = this._defaults();
+    const user = this._userSettings;
+    return {
+      policies: { ...defaults.policies, ...user.policies },
+      iterations: {
+        review: { ...defaults.iterations.review, ...user.iterations?.review },
+        coverage: { ...defaults.iterations.coverage, ...user.iterations?.coverage },
+      },
+      models: { ...defaults.models, ...user.models },
+      ui: { ...defaults.ui, ...user.ui },
+      capabilities: { ...defaults.capabilities, ...user.capabilities },
+      // COMP-HEALTH: merge health settings
+      health: {
+        ...defaults.health,
+        ...user.health,
+        weights: { ...defaults.health.weights, ...user.health?.weights },
+      },
+      thinking: { ...defaults.thinking, ...user.thinking },
+    };
+  }
+
+  /** Validate and apply a partial settings update. */
+  update(patch) {
+    this._validate(patch);
+    // Deep merge into user settings
+    for (const section of ['policies', 'iterations', 'models', 'ui', 'capabilities', 'health', 'thinking']) {
+      if (patch[section]) {
+        if (!this._userSettings[section]) this._userSettings[section] = {};
+        if (section === 'iterations') {
+          for (const [key, val] of Object.entries(patch.iterations)) {
+            this._userSettings.iterations[key] = { ...this._userSettings.iterations[key], ...val };
+          }
+        } else {
+          Object.assign(this._userSettings[section], patch[section]);
+        }
+      }
+    }
+    this._save();
+    return this.get();
+  }
+
+  /** Reset user overrides. If section given, reset only that section. */
+  reset(section) {
+    if (section) {
+      delete this._userSettings[section];
+    } else {
+      this._userSettings = {};
+    }
+    this._save();
+    return this.get();
+  }
+
+  _validate(patch) {
+    const validModes = new Set(this._contract.policyModes);
+
+    // Reject unknown top-level keys
+    for (const key of Object.keys(patch)) {
+      if (!['policies', 'iterations', 'models', 'ui', 'capabilities', 'health', 'thinking'].includes(key)) {
+        throw new Error(`Unknown settings section: ${key}`);
+      }
+    }
+
+    if (patch.policies) {
+      for (const [phase, mode] of Object.entries(patch.policies)) {
+        if (mode !== null && !validModes.has(mode)) {
+          throw new Error(`Invalid policy mode for ${phase}: ${mode}`);
+        }
+      }
+    }
+
+    if (patch.iterations) {
+      for (const [type, config] of Object.entries(patch.iterations)) {
+        if (config.maxIterations !== undefined) {
+          const n = config.maxIterations;
+          if (!Number.isInteger(n) || n < 1 || n > 100) {
+            throw new Error(`Invalid maxIterations for ${type}: must be integer 1-100`);
+          }
+        }
+        if (config.timeout !== undefined) {
+          const t = config.timeout;
+          if (!Number.isInteger(t) || t < 1 || t > 120) {
+            throw new Error(`Invalid timeout for ${type}: must be integer 1-120 (minutes)`);
+          }
+        }
+        if (config.maxTotal !== undefined) {
+          const m = config.maxTotal;
+          if (!Number.isInteger(m) || m < 1 || m > 200) {
+            throw new Error(`Invalid maxTotal for ${type}: must be integer 1-200`);
+          }
+        }
+      }
+    }
+
+    if (patch.models) {
+      for (const [key, val] of Object.entries(patch.models)) {
+        if (typeof val !== 'string' || val.length === 0) {
+          throw new Error(`Invalid model for ${key}: must be non-empty string`);
+        }
+      }
+    }
+
+    if (patch.ui) {
+      if (patch.ui.theme !== undefined && !VALID_THEMES.includes(patch.ui.theme)) {
+        throw new Error(`Invalid theme: ${patch.ui.theme} (must be ${VALID_THEMES.join(', ')})`);
+      }
+      if (patch.ui.defaultView !== undefined && !VALID_VIEWS.includes(patch.ui.defaultView)) {
+        throw new Error(`Invalid defaultView: ${patch.ui.defaultView} (must be ${VALID_VIEWS.join(', ')})`);
+      }
+    }
+
+    if (patch.capabilities) {
+      if (patch.capabilities.enforcement !== undefined) {
+        const VALID_ENFORCEMENT = ['log', 'block'];
+        if (!VALID_ENFORCEMENT.includes(patch.capabilities.enforcement)) {
+          throw new Error(`Invalid enforcement: ${patch.capabilities.enforcement} (must be ${VALID_ENFORCEMENT.join(', ')})`);
+        }
+      }
+    }
+
+    if (patch.thinking) {
+      if (patch.thinking.mode !== undefined) {
+        const m = patch.thinking.mode;
+        if (m !== 'tier' && !VALID_THINKING_MODES.includes(m)) {
+          throw new Error(`Invalid thinking.mode: ${m} (must be tier, ${VALID_THINKING_MODES.join(', ')})`);
+        }
+      }
+      if (patch.thinking.effort !== undefined && patch.thinking.effort !== null) {
+        if (!VALID_EFFORT_LEVELS.includes(patch.thinking.effort)) {
+          throw new Error(`Invalid thinking.effort: ${patch.thinking.effort} (must be null or ${VALID_EFFORT_LEVELS.join(', ')})`);
+        }
+      }
+    }
+
+    if (patch.health) {
+      // Validate gate_threshold: must be null or 0-100
+      if (patch.health.gate_threshold !== undefined && patch.health.gate_threshold !== null) {
+        const t = patch.health.gate_threshold;
+        if (typeof t !== 'number' || t < 0 || t > 100) {
+          throw new Error(`Invalid health.gate_threshold: must be null or a number 0-100`);
+        }
+      }
+      // Validate weights: each value must be a number; sum must be 1.0 ± 0.01
+      if (patch.health.weights !== undefined) {
+        const vals = Object.values(patch.health.weights);
+        if (vals.some(v => typeof v !== 'number' || v < 0)) {
+          throw new Error('Invalid health.weights: all values must be non-negative numbers');
+        }
+        if (vals.length > 0) {
+          const sum = vals.reduce((s, v) => s + v, 0);
+          if (Math.abs(sum - 1.0) > 0.01) {
+            throw new Error(`Invalid health.weights: values must sum to 1.0 ± 0.01 (got ${sum.toFixed(4)})`);
+          }
+        }
+      }
+    }
+  }
+}

package/server/stratum-api.js

@@ -0,0 +1,102 @@
+/**
+ * stratum-api.js — Express router for Stratum pipeline monitor + gate UI.
+ *
+ * Pure transport adapter: calls stratum-client, maps results to HTTP.
+ * Zero domain logic — all gate semantics live in stratum.
+ *
+ * Routes:
+ *   GET  /api/stratum/flows
+ *   GET  /api/stratum/flows/:flowId
+ *   GET  /api/stratum/gates
+ *   POST /api/stratum/gates/:flowId/:stepId/approve
+ *   POST /api/stratum/gates/:flowId/:stepId/reject
+ *   POST /api/stratum/gates/:flowId/:stepId/revise
+ */
+
+import { Router } from 'express';
+import * as _defaultClient from './stratum-client.js';
+
+/** Wrap an async route handler so rejections call next(err) instead of going unhandled. */
+function ar(fn) {
+  return (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
+}
+
+/**
+ * @param {object} [client] — override stratum-client (for tests only)
+ */
+export function createStratumRouter(client) {
+  const stratum = client ?? _defaultClient;
+  const router = Router();
+
+  // -- Read routes -----------------------------------------------------------
+
+  router.get('/flows', ar(async (_req, res) => {
+    const result = await stratum.queryFlows();
+    if (result?.error) return res.status(_errorStatus(result.error.code)).json(result);
+    res.json(result);
+  }));
+
+  router.get('/flows/:flowId', ar(async (req, res) => {
+    const result = await stratum.queryFlow(req.params.flowId);
+    if (result?.error) return res.status(_errorStatus(result.error.code)).json(result);
+    res.json(result);
+  }));
+
+  router.get('/gates', ar(async (_req, res) => {
+    const result = await stratum.queryGates();
+    if (result?.error) return res.status(_errorStatus(result.error.code)).json(result);
+    res.json(result);
+  }));
+
+  // -- Gate mutation routes --------------------------------------------------
+
+  router.post('/gates/:flowId/:stepId/approve', ar(async (req, res) => {
+    const { flowId, stepId } = req.params;
+    const { note, resolvedBy } = req.body || {};
+    const result = await stratum.gateApprove(flowId, stepId, note, resolvedBy);
+    res.status(_mutationStatus(result)).json(result);
+  }));
+
+  router.post('/gates/:flowId/:stepId/reject', ar(async (req, res) => {
+    const { flowId, stepId } = req.params;
+    const { note, resolvedBy } = req.body || {};
+    const result = await stratum.gateReject(flowId, stepId, note, resolvedBy);
+    res.status(_mutationStatus(result)).json(result);
+  }));
+
+  router.post('/gates/:flowId/:stepId/revise', ar(async (req, res) => {
+    const { flowId, stepId } = req.params;
+    const { note, resolvedBy } = req.body || {};
+    const result = await stratum.gateRevise(flowId, stepId, note, resolvedBy);
+    res.status(_mutationStatus(result)).json(result);
+  }));
+
+  // -- Error middleware (catches ENOENT, unexpected throws, etc.) -------------
+  // eslint-disable-next-line no-unused-vars
+  router.use((err, _req, res, _next) => {
+    console.error('[stratum-api] unhandled error:', err.message);
+    res.status(503).json({ error: { code: 'UNAVAILABLE', message: err.message, detail: '' } });
+  });
+
+  return router;
+}
+
+// ---------------------------------------------------------------------------
+// Status code mapping — error codes → HTTP status
+// ---------------------------------------------------------------------------
+
+function _errorStatus(code) {
+  switch (code) {
+    case 'NOT_FOUND':  return 404;
+    case 'TIMEOUT':    return 504;
+    case 'INVALID':    return 400;
+    default:           return 500;
+  }
+}
+
+function _mutationStatus(result) {
+  if (result?.conflict)     return 409;
+  if (result?.error)        return _errorStatus(result.error.code);
+  if (result?.ok === true)  return 200;
+  return 500;
+}

package/server/stratum-client.js

@@ -0,0 +1,192 @@
+/**
+ * stratum-client.js — Single adapter for all stratum-mcp subprocess calls.
+ *
+ * This is the ONLY module in compose that spawns stratum-mcp processes.
+ * All query and mutation calls go through the exported functions below.
+ * No other file may call execFile/spawn with 'stratum-mcp' as the command.
+ *
+ * Contract:
+ *   - Query calls:   5s timeout, 1 retry on timeout, no retry on error
+ *   - Mutation calls: 10s timeout, no retry (mutations are not idempotent to retry)
+ *   - Exit 0  → parse stdout as JSON, return result
+ *   - Exit 2  → conflict (idempotency), return { conflict: true, ... }
+ *   - Non-zero → log stderr internally, return { error: { code, message, detail } }
+ *   - stderr is NEVER forwarded to callers
+ */
+
+import { execFile as _execFileDefault } from 'node:child_process';
+
+const STRATUM_BIN = 'stratum-mcp';
+
+// Injected executor — replaced by tests only. Production code never calls this setter.
+let _execFile = _execFileDefault;
+export function _testOnly_setExecFile(fn) { _execFile = fn; }
+const QUERY_TIMEOUT_MS = 5_000;
+const MUTATION_TIMEOUT_MS = 10_000;
+
+// ---------------------------------------------------------------------------
+// Core subprocess runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn stratum-mcp with args. Returns a Promise resolving to { stdout, code }.
+ * Rejects only on spawn failure (binary not found).
+ *
+ * @param {string[]} args
+ * @param {number}   timeoutMs
+ * @returns {Promise<{ stdout: string, stderr: string, code: number }>}
+ */
+function spawnStratum(args, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let stdout = '';
+    let stderr = '';
+
+    const proc = _execFile(STRATUM_BIN, args, { timeout: timeoutMs }, (err, out, err2) => {
+      stdout = out || '';
+      stderr = err2 || '';
+      const code = err?.code === 'ETIMEDOUT' ? -1
+        : (typeof err?.code === 'number' ? err.code : 0);
+      resolve({ stdout, stderr, code });
+    });
+
+    proc.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        reject(new Error(`stratum-mcp not found. Install with: pip install stratum-mcp`));
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+
+/**
+ * Run a query command (read-only). Retries once on timeout.
+ *
+ * @returns {Promise<any>} parsed JSON result, or throws StratumError
+ */
+async function runQuery(args) {
+  let result = await spawnStratum(args, QUERY_TIMEOUT_MS);
+
+  if (result.code === -1) {
+    // Retry once on timeout
+    result = await spawnStratum(args, QUERY_TIMEOUT_MS);
+    if (result.code === -1) {
+      return { error: { code: 'TIMEOUT', message: 'stratum-mcp query timed out', detail: '' } };
+    }
+  }
+
+  if (result.code !== 0) {
+    console.error('[stratum-client] query error stderr:', result.stderr);
+    try {
+      return JSON.parse(result.stdout);
+    } catch {
+      return { error: { code: 'UNKNOWN', message: 'stratum-mcp query failed', detail: '' } };
+    }
+  }
+
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return { error: { code: 'PARSE_ERROR', message: 'stratum-mcp returned invalid JSON', detail: '' } };
+  }
+}
+
+/**
+ * Run a mutation command (gate approve/reject/revise). No retry.
+ *
+ * @returns {Promise<any>} parsed JSON result, or { conflict }, or { error }
+ */
+async function runMutation(args) {
+  const result = await spawnStratum(args, MUTATION_TIMEOUT_MS);
+
+  if (result.code === -1) {
+    return { error: { code: 'TIMEOUT', message: 'stratum-mcp gate timed out', detail: '' } };
+  }
+
+  if (result.code === 2) {
+    try {
+      return JSON.parse(result.stdout);   // { conflict: true, ... }
+    } catch {
+      return { conflict: true, detail: '' };
+    }
+  }
+
+  if (result.code !== 0) {
+    console.error('[stratum-client] mutation error stderr:', result.stderr);
+    try {
+      return JSON.parse(result.stdout);
+    } catch {
+      return { error: { code: 'UNKNOWN', message: 'stratum-mcp gate failed', detail: '' } };
+    }
+  }
+
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return { error: { code: 'PARSE_ERROR', message: 'stratum-mcp returned invalid JSON', detail: '' } };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** List all persisted flows. @returns {Promise<FlowSummary[]|ErrorResult>} */
+export async function queryFlows() {
+  return runQuery(['query', 'flows']);
+}
+
+/** Full state for a single flow. @returns {Promise<FlowState|ErrorResult>} */
+export async function queryFlow(flowId) {
+  return runQuery(['query', 'flow', flowId]);
+}
+
+/** List all pending gate steps. @returns {Promise<PendingGate[]|ErrorResult>} */
+export async function queryGates() {
+  return runQuery(['query', 'gates']);
+}
+
+/**
+ * Approve a gate step. Stratum is the mutation authority.
+ * @param {string} flowId
+ * @param {string} stepId
+ * @param {string} [note]
+ * @param {'human'|'agent'|'system'} [resolvedBy]
+ * @returns {Promise<GateMutationResult|ConflictResult|ErrorResult>}
+ */
+export async function gateApprove(flowId, stepId, note = '', resolvedBy = 'human') {
+  const args = ['gate', 'approve', flowId, stepId];
+  if (note) args.push('--note', note);
+  if (resolvedBy !== 'human') args.push('--resolved-by', resolvedBy);
+  return runMutation(args);
+}
+
+/**
+ * Reject (kill) a gate step.
+ * @param {string} flowId
+ * @param {string} stepId
+ * @param {string} [note]
+ * @param {'human'|'agent'|'system'} [resolvedBy]
+ * @returns {Promise<GateMutationResult|ConflictResult|ErrorResult>}
+ */
+export async function gateReject(flowId, stepId, note = '', resolvedBy = 'human') {
+  const args = ['gate', 'reject', flowId, stepId];
+  if (note) args.push('--note', note);
+  if (resolvedBy !== 'human') args.push('--resolved-by', resolvedBy);
+  return runMutation(args);
+}
+
+/**
+ * Send a gate step back for revision.
+ * @param {string} flowId
+ * @param {string} stepId
+ * @param {string} [note]
+ * @param {'human'|'agent'|'system'} [resolvedBy]
+ * @returns {Promise<GateMutationResult|ConflictResult|ErrorResult>}
+ */
+export async function gateRevise(flowId, stepId, note = '', resolvedBy = 'human') {
+  const args = ['gate', 'revise', flowId, stepId];
+  if (note) args.push('--note', note);
+  if (resolvedBy !== 'human') args.push('--resolved-by', resolvedBy);
+  return runMutation(args);
+}