@smartmemory/compose 0.1.0

package/lib/build-dag.js

@@ -0,0 +1,120 @@
+/**
+ * build-dag.js — Build a dependency DAG from roadmap feature entries.
+ *
+ * Dependencies are positional:
+ * - Items within the same phase depend on the previous item (sequential chain)
+ * - The first item of phase N depends on the last item of phase N-1 (cross-phase edge)
+ */
+
+/**
+ * @typedef {{ code: string, deps: string[] }} DagNode
+ */
+
+/**
+ * Build a DAG from roadmap entries.
+ *
+ * @param {import('./roadmap-parser.js').FeatureEntry[]} entries - Full ordered list from parseRoadmap()
+ * @returns {DagNode[]}
+ */
+export function buildDag(entries) {
+  if (entries.length === 0) return [];
+
+  // Deduplicate by code — keep first occurrence only
+  const seen = new Set();
+  const unique = [];
+  for (const entry of entries) {
+    if (!seen.has(entry.code)) {
+      seen.add(entry.code);
+      unique.push(entry);
+    }
+  }
+
+  // Group by phaseId preserving encounter order
+  const phases = new Map();
+  for (const entry of unique) {
+    if (!phases.has(entry.phaseId)) {
+      phases.set(entry.phaseId, []);
+    }
+    phases.get(entry.phaseId).push(entry);
+  }
+
+  // Build adjacency: code → Set<depCode>
+  const deps = new Map();
+  for (const entry of unique) {
+    deps.set(entry.code, new Set());
+  }
+
+  let lastPhaseLastCode = null;
+
+  for (const [, phaseEntries] of phases) {
+    let prevCode = null;
+
+    for (const entry of phaseEntries) {
+      // Cross-phase edge: first item depends on last item of previous phase
+      if (prevCode === null && lastPhaseLastCode !== null) {
+        deps.get(entry.code).add(lastPhaseLastCode);
+      }
+
+      // Within-phase sequential chain
+      if (prevCode !== null) {
+        deps.get(entry.code).add(prevCode);
+      }
+
+      prevCode = entry.code;
+    }
+
+    lastPhaseLastCode = prevCode;
+  }
+
+  return unique.map(e => ({
+    code: e.code,
+    deps: [...deps.get(e.code)],
+  }));
+}
+
+/**
+ * Topological sort via Kahn's algorithm.
+ * Returns feature codes in build order (dependencies first).
+ *
+ * @param {DagNode[]} nodes
+ * @returns {string[]}
+ * @throws {Error} if a cycle is detected
+ */
+export function topoSort(nodes) {
+  const inDegree = new Map();
+  const successors = new Map();
+
+  for (const node of nodes) {
+    if (!inDegree.has(node.code)) inDegree.set(node.code, 0);
+    if (!successors.has(node.code)) successors.set(node.code, []);
+
+    for (const dep of node.deps) {
+      if (!inDegree.has(dep)) inDegree.set(dep, 0);
+      if (!successors.has(dep)) successors.set(dep, []);
+      successors.get(dep).push(node.code);
+      inDegree.set(node.code, inDegree.get(node.code) + 1);
+    }
+  }
+
+  const queue = [];
+  for (const [code, degree] of inDegree) {
+    if (degree === 0) queue.push(code);
+  }
+
+  const order = [];
+  while (queue.length > 0) {
+    const code = queue.shift();
+    order.push(code);
+    for (const succ of successors.get(code) ?? []) {
+      const newDegree = inDegree.get(succ) - 1;
+      inDegree.set(succ, newDegree);
+      if (newDegree === 0) queue.push(succ);
+    }
+  }
+
+  if (order.length !== inDegree.size) {
+    throw new Error('Cycle detected in feature dependency graph');
+  }
+
+  return order;
+}

package/lib/build-stream-writer.js

@@ -0,0 +1,190 @@
+/**
+ * BuildStreamWriter — appends JSONL events to .compose/build-stream.jsonl
+ *
+ * Used by build.js to emit build lifecycle events that the agent-server's
+ * BuildStreamBridge tails and rebroadcasts via SSE.
+ *
+ * Sync I/O is intentional — JSONL lines are small and the CLI is already
+ * I/O-bound on agent calls between writes.
+ */
+
+import { mkdirSync, appendFileSync, unlinkSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export class BuildStreamWriter {
+  #path;
+  #seq = 0;
+  #featureCode;
+  #closed = false;
+
+  /**
+   * @param {string} composeDir  Path to .compose directory
+   * @param {string} featureCode Feature code (e.g. 'STRAT-COMP-7')
+   * @param {object} [opts]
+   * @param {boolean} [opts.truncate=false] Truncate existing stream (fresh builds only)
+   */
+  constructor(composeDir, featureCode, { truncate = false } = {}) {
+    mkdirSync(composeDir, { recursive: true });
+    this.#path = join(composeDir, 'build-stream.jsonl');
+    this.#featureCode = featureCode;
+
+    // Only truncate on fresh builds — resumed builds append to existing stream
+    if (truncate && existsSync(this.#path)) {
+      unlinkSync(this.#path);
+    }
+
+    // On resume: read the last _seq from the existing JSONL so new events
+    // have monotonically increasing _seq values. The SSE bridge deduplicates
+    // on _seq, so restarting from 0 would cause all resumed events to be dropped.
+    if (!truncate && existsSync(this.#path)) {
+      try {
+        const content = readFileSync(this.#path, 'utf-8').trimEnd();
+        if (content) {
+          const lastLine = content.slice(content.lastIndexOf('\n') + 1);
+          const lastEvent = JSON.parse(lastLine);
+          if (typeof lastEvent._seq === 'number') {
+            this.#seq = lastEvent._seq + 1;
+          }
+        }
+      } catch {
+        // Corrupt file — start from 0, bridge will handle duplicates
+      }
+    }
+  }
+
+  /**
+   * Append a JSONL event with auto-incremented _seq and _ts fields.
+   * @param {object} event  Event payload (must include `type`)
+   */
+  write(event) {
+    const line = JSON.stringify({
+      ...event,
+      _seq: this.#seq++,
+      _ts: Date.now(),
+    });
+    appendFileSync(this.#path, line + '\n');
+  }
+
+  /**
+   * Emit a capability_profile event noting the active template for a step.
+   * Informational only — never blocks or fails the build.
+   *
+   * @param {string}        stepId        Step ID
+   * @param {string}        agent         Full agent string, e.g. "claude:read-only-reviewer"
+   * @param {string|null}   templateName  Template name, or null if no template
+   * @param {string[]|null} allowedTools  Allowed tools list from template
+   * @param {string[]|null} disallowedTools Disallowed tools list from template
+   */
+  writeCapabilityProfile(stepId, agent, templateName, allowedTools, disallowedTools) {
+    this.write({
+      type: 'capability_profile',
+      stepId,
+      agent,
+      template: templateName,
+      allowedTools,
+      disallowedTools,
+    });
+  }
+
+  /**
+   * Emit a capability_violation event for informational audit.
+   * Violations are never blocking in v1.
+   *
+   * @param {string} stepId       Step ID where the violation was detected
+   * @param {string} agent        Full agent string
+   * @param {string} templateName Active template name
+   * @param {string} detail       Description of the violation
+   */
+  writeViolation(stepId, agent, templateName, detail) {
+    this.write({
+      type: 'capability_violation',
+      stepId,
+      agent,
+      template: templateName,
+      detail,
+    });
+  }
+
+  /**
+   * Emit a per-step usage event with token and cost data (COMP-OBS-COST).
+   *
+   * @param {string} stepId    Step ID this usage belongs to
+   * @param {object} usage     Usage object from result-normalizer
+   * @param {number} usage.input_tokens
+   * @param {number} usage.output_tokens
+   * @param {number} [usage.cache_creation_input_tokens]
+   * @param {number} [usage.cache_read_input_tokens]
+   * @param {number} usage.cost_usd
+   * @param {string|null} [usage.model]
+   */
+  writeUsage(stepId, usage) {
+    this.write({
+      type: 'step_usage',
+      stepId,
+      input_tokens: usage.input_tokens ?? 0,
+      output_tokens: usage.output_tokens ?? 0,
+      cache_creation_input_tokens: usage.cache_creation_input_tokens ?? 0,
+      cache_read_input_tokens: usage.cache_read_input_tokens ?? 0,
+      cost_usd: usage.cost_usd ?? 0,
+      model: usage.model ?? null,
+    });
+  }
+
+  /**
+   * Emit a gate_tier_result event for a step's tier classification result (COMP-OBS-GATES).
+   *
+   * @param {string}      stepId   Pipeline step ID (e.g. 'review', 'coverage_check')
+   * @param {string}      tierId   Tier ID (e.g. 'T3')
+   * @param {boolean}     passed   Whether this tier passed
+   * @param {string|null} details  Optional summary / detail string
+   */
+  writeGateTier(stepId, tierId, passed, details = null) {
+    this.write({
+      type: 'gate_tier_result',
+      stepId,
+      tierId,
+      passed,
+      details,
+    });
+  }
+
+  /**
+   * Emit a health_score event with the composite score and dimension breakdown.
+   * COMP-HEALTH item 118: emitted after build_end so consumers can display it.
+   *
+   * @param {number}   score      Composite score 0-100
+   * @param {object}   breakdown  Per-dimension scores { dim: number }
+   * @param {string[]} [missing]  Dimensions not scored (no signal available)
+   */
+  writeHealthScore(score, breakdown, missing = []) {
+    this.write({
+      type: 'health_score',
+      score,
+      breakdown,
+      missing,
+    });
+  }
+
+  /**
+   * Write a build_end sentinel and mark the writer as closed.
+   * Idempotent — calling multiple times writes exactly one build_end.
+   * @param {string} [status='complete']  Build exit status
+   * @param {object} [costTotals]         Optional cumulative cost/token totals
+   */
+  close(status = 'complete', costTotals = null) {
+    if (this.#closed) return;
+    this.#closed = true;
+    const payload = { type: 'build_end', status, featureCode: this.#featureCode };
+    if (costTotals) {
+      payload.total_input_tokens = costTotals.input_tokens ?? 0;
+      payload.total_output_tokens = costTotals.output_tokens ?? 0;
+      payload.total_cost_usd = costTotals.cost_usd ?? 0;
+    }
+    this.write(payload);
+  }
+
+  /** @returns {string} Absolute path to the JSONL file */
+  get filePath() {
+    return this.#path;
+  }
+}