@smartmemory/compose 0.1.5-beta → 0.1.6-beta

package/lib/feature-writer.js

@@ -16,8 +16,10 @@
  * be called from MCP tools, the CLI, or future REST routes.
  */
 
+import { existsSync, realpathSync, statSync } from 'fs';
+import { resolve, normalize, sep, basename, dirname } from 'path';
+
 import { readFeature, writeFeature, listFeatures, updateFeature } from './feature-json.js';
-// eslint-disable-next-line no-unused-vars
 const _listFeatures = listFeatures;
 import { writeRoadmap } from './roadmap-gen.js';
 import { appendEvent, readEvents } from './feature-events.js';
@@ -119,7 +121,16 @@ export async function addRoadmapEntry(cwd, args) {
     if (args.tags && args.tags.length) feature.tags = args.tags;
 
     writeFeature(cwd, feature);
-    const roadmapPath = writeRoadmap(cwd);
+    let roadmapPath;
+    try {
+      roadmapPath = writeRoadmap(cwd);
+    } catch (err) {
+      throw partialWriteError(
+        `add_roadmap_entry: feature.json for "${args.code}" was written but ROADMAP.md regeneration failed. ` +
+        `Recover with \`compose roadmap generate\`.`,
+        err,
+      );
+    }
 
     safeAppendEvent(cwd, {
       tool: 'add_roadmap_entry',
@@ -150,6 +161,18 @@ function nextPositionInPhase(cwd, phase) {
   return maxPos + 1;
 }
 
+// Wrap a mid-flight failure (feature.json committed, ROADMAP.md regen
+// failed) in a typed envelope so MCP callers can distinguish committed vs
+// uncommitted state. The wrapper at server/compose-mcp.js serializes
+// err.cause as `Caused by [CODE]: message`, so the underlying writeRoadmap
+// error stays observable across the MCP boundary.
+function partialWriteError(message, cause) {
+  const err = new Error(message);
+  err.code = 'ROADMAP_PARTIAL_WRITE';
+  if (cause) err.cause = cause;
+  return err;
+}
+
 // Audit-log writes are best-effort: a failed append must NOT roll back a
 // committed mutation (per design Decision 2 and docs/mcp.md). Log a warning
 // and continue.
@@ -207,7 +230,15 @@ export async function setFeatureStatus(cwd, args) {
     const updates = { status: to };
     if (args.commit_sha) updates.commit_sha = args.commit_sha;
     updateFeature(cwd, args.code, updates);
-    writeRoadmap(cwd);
+    try {
+      writeRoadmap(cwd);
+    } catch (err) {
+      throw partialWriteError(
+        `set_feature_status: feature.json for "${args.code}" was updated (${from} → ${to}) but ROADMAP.md regeneration failed. ` +
+        `Recover with \`compose roadmap generate\`.`,
+        err,
+      );
+    }
 
     const event = {
       tool: 'set_feature_status',
@@ -258,8 +289,297 @@ export function roadmapDiff(cwd, args = {}) {
   return { events, added, status_changed };
 }
 
+// ---------------------------------------------------------------------------
+// Linker — COMP-MCP-ARTIFACT-LINKER
+// ---------------------------------------------------------------------------
+
+const LINK_KINDS = new Set([
+  'surfaced_by', 'blocks', 'depends_on',
+  'follow_up', 'supersedes', 'related',
+]);
+
+const CANONICAL_ARTIFACT_NAMES = new Set([
+  'design.md', 'prd.md', 'architecture.md',
+  'blueprint.md', 'plan.md', 'report.md',
+]);
+
+function validateRepoPath(cwd, path) {
+  if (typeof path !== 'string' || path.length === 0) {
+    throw new Error('feature-writer: path must be a non-empty string');
+  }
+  if (path.startsWith('/') || path.startsWith('~')) {
+    throw new Error(`feature-writer: path must be repo-relative, got "${path}"`);
+  }
+  const normalized = normalize(path);
+  if (normalized.split(sep).includes('..')) {
+    throw new Error(`feature-writer: path must not contain ".." after normalization, got "${path}"`);
+  }
+  const realCwd = realpathSync(cwd);
+  const resolved = resolve(realCwd, normalized);
+  if (!resolved.startsWith(realCwd + sep) && resolved !== realCwd) {
+    throw new Error(`feature-writer: path "${path}" resolves outside cwd`);
+  }
+  if (!existsSync(resolved)) {
+    throw new Error(`feature-writer: path "${path}" does not exist`);
+  }
+  // Resolve symlinks AFTER existence check and verify the real target also
+  // lives under cwd. This blocks repo-internal symlinks that escape (e.g.
+  // docs/features/FOO/leak -> /etc/passwd). Mirrors the symlink hardening
+  // in server/artifact-manager.js.
+  const realResolved = realpathSync(resolved);
+  if (!realResolved.startsWith(realCwd + sep) && realResolved !== realCwd) {
+    throw new Error(`feature-writer: path "${path}" symlinks outside cwd`);
+  }
+  if (!statSync(realResolved).isFile()) {
+    throw new Error(`feature-writer: path "${path}" must point at a file (got directory or other)`);
+  }
+  return normalized;
+}
+
+function rejectCanonicalArtifact(featureCode, normalizedPath) {
+  // Reject paths like docs/features/<CODE>/design.md, prd.md, etc.
+  const file = basename(normalizedPath);
+  if (!CANONICAL_ARTIFACT_NAMES.has(file)) return;
+  // The canonical files live under the feature folder. If this path points
+  // inside the feature's own folder, refuse — those are auto-discovered.
+  const parent = dirname(normalizedPath);
+  if (parent.endsWith(`docs/features/${featureCode}`)) {
+    throw new Error(
+      `feature-writer: "${file}" inside the feature folder is a canonical artifact; ` +
+      `it is auto-discovered by assess_feature_artifacts and should not be linked explicitly.`
+    );
+  }
+}
+
+/**
+ * Register a non-canonical artifact (snapshot, journal, finding, etc.) on a
+ * feature. Canonical artifacts (design.md, plan.md, ...) are auto-discovered
+ * by ArtifactManager and rejected here.
+ *
+ * @param {string} cwd
+ * @param {object} args
+ * @param {string} args.feature_code
+ * @param {string} args.artifact_type
+ * @param {string} args.path - repo-relative
+ * @param {string} [args.status]
+ * @param {boolean} [args.force]
+ * @param {string} [args.idempotency_key]
+ */
+export async function linkArtifact(cwd, args) {
+  validateCode(args.feature_code);
+  if (!args.artifact_type || typeof args.artifact_type !== 'string') {
+    throw new Error('feature-writer: artifact_type is required (non-empty string)');
+  }
+  const normalizedPath = validateRepoPath(cwd, args.path);
+  rejectCanonicalArtifact(args.feature_code, normalizedPath);
+
+  return maybeIdempotent({ ...args, cwd }, () => {
+    const feature = readFeature(cwd, args.feature_code);
+    if (!feature) {
+      throw new Error(`feature-writer: feature "${args.feature_code}" not found`);
+    }
+
+    const artifacts = Array.isArray(feature.artifacts) ? [...feature.artifacts] : [];
+    const matchIdx = artifacts.findIndex(
+      a => a.type === args.artifact_type && a.path === normalizedPath
+    );
+
+    if (matchIdx !== -1 && !args.force) {
+      return {
+        feature_code: args.feature_code,
+        artifact_type: args.artifact_type,
+        path: normalizedPath,
+        noop: true,
+      };
+    }
+
+    const entry = { type: args.artifact_type, path: normalizedPath };
+    if (args.status) entry.status = args.status;
+
+    if (matchIdx !== -1) artifacts[matchIdx] = entry;
+    else artifacts.push(entry);
+
+    updateFeature(cwd, args.feature_code, { artifacts });
+
+    safeAppendEvent(cwd, {
+      tool: 'link_artifact',
+      code: args.feature_code,
+      artifact_type: args.artifact_type,
+      path: normalizedPath,
+      forced: matchIdx !== -1 ? true : undefined,
+      idempotency_key: args.idempotency_key,
+    });
+
+    return {
+      feature_code: args.feature_code,
+      artifact_type: args.artifact_type,
+      path: normalizedPath,
+    };
+  });
+}
+
+/**
+ * Register a typed cross-feature link.
+ *
+ * @param {string} cwd
+ * @param {object} args
+ * @param {string} args.from_code
+ * @param {string} args.to_code
+ * @param {string} args.kind - one of LINK_KINDS
+ * @param {string} [args.note]
+ * @param {boolean} [args.force]
+ * @param {string} [args.idempotency_key]
+ */
+export async function linkFeatures(cwd, args) {
+  validateCode(args.from_code);
+  validateCode(args.to_code);
+  if (args.from_code === args.to_code) {
+    throw new Error(`feature-writer: cannot link a feature to itself ("${args.from_code}")`);
+  }
+  if (!LINK_KINDS.has(args.kind)) {
+    throw new Error(
+      `feature-writer: invalid link kind "${args.kind}". ` +
+      `Allowed: ${[...LINK_KINDS].join(', ')}`
+    );
+  }
+
+  return maybeIdempotent({ ...args, cwd }, () => {
+    const feature = readFeature(cwd, args.from_code);
+    if (!feature) {
+      throw new Error(`feature-writer: feature "${args.from_code}" not found`);
+    }
+
+    const links = Array.isArray(feature.links) ? [...feature.links] : [];
+    const matchIdx = links.findIndex(
+      l => l.kind === args.kind && l.to_code === args.to_code
+    );
+
+    if (matchIdx !== -1 && !args.force) {
+      return { from_code: args.from_code, to_code: args.to_code, kind: args.kind, noop: true };
+    }
+
+    const entry = { kind: args.kind, to_code: args.to_code };
+    if (args.note) entry.note = args.note;
+
+    if (matchIdx !== -1) links[matchIdx] = entry;
+    else links.push(entry);
+
+    updateFeature(cwd, args.from_code, { links });
+
+    safeAppendEvent(cwd, {
+      tool: 'link_features',
+      code: args.from_code,
+      to_code: args.to_code,
+      kind: args.kind,
+      note: args.note,
+      forced: matchIdx !== -1 ? true : undefined,
+      idempotency_key: args.idempotency_key,
+    });
+
+    return { from_code: args.from_code, to_code: args.to_code, kind: args.kind };
+  });
+}
+
+/**
+ * Read both canonical and linked artifacts for a feature in one call.
+ *
+ * Canonical artifacts (design.md/prd.md/architecture.md/blueprint.md/
+ * plan.md/report.md inside the feature folder) come from ArtifactManager
+ * via a dynamic import (kept out of the static import graph because lib/
+ * is consumed by stdio MCP code paths and we don't want to pay
+ * server/-side load costs unless the caller asks).
+ *
+ * Linked artifacts come from feature.json's artifacts[]; each is stamped
+ * with a current existence check.
+ *
+ * @param {string} cwd
+ * @param {object} args
+ * @param {string} args.feature_code
+ */
+export async function getFeatureArtifacts(cwd, args) {
+  validateCode(args.feature_code);
+  const feature = readFeature(cwd, args.feature_code);
+  if (!feature) {
+    throw new Error(`feature-writer: feature "${args.feature_code}" not found`);
+  }
+
+  const realCwd = realpathSync(cwd);
+  const linked = (feature.artifacts ?? []).map(a => ({
+    type: a.type,
+    path: a.path,
+    status: a.status,
+    exists: existsSync(resolve(realCwd, a.path)),
+  }));
+
+  let canonical = null;
+  try {
+    const { ArtifactManager } = await import('../server/artifact-manager.js');
+    const featureRoot = resolve(realCwd, 'docs', 'features');
+    if (existsSync(featureRoot)) {
+      const manager = new ArtifactManager(featureRoot);
+      canonical = manager.assess(args.feature_code);
+    }
+  } catch (err) {
+    // Don't fail the whole read if ArtifactManager isn't available — surface
+    // the issue via canonical: null and a one-line note.
+    canonical = { error: err.message };
+  }
+
+  return { feature_code: args.feature_code, canonical, linked };
+}
+
+/**
+ * Read outgoing and/or incoming links for a feature. Outgoing reads from
+ * the source feature's links[]; incoming iterates listFeatures and finds
+ * entries that target the requested code.
+ *
+ * @param {string} cwd
+ * @param {object} args
+ * @param {string} args.feature_code
+ * @param {'outgoing'|'incoming'|'both'} [args.direction='both']
+ * @param {string} [args.kind]
+ */
+export function getFeatureLinks(cwd, args) {
+  validateCode(args.feature_code);
+  const direction = args.direction ?? 'both';
+  if (!['outgoing', 'incoming', 'both'].includes(direction)) {
+    throw new Error(
+      `feature-writer: invalid direction "${direction}". Allowed: outgoing, incoming, both.`
+    );
+  }
+  const kind = args.kind;
+
+  const out = { feature_code: args.feature_code };
+
+  if (direction === 'outgoing' || direction === 'both') {
+    const feature = readFeature(cwd, args.feature_code);
+    if (!feature) {
+      throw new Error(`feature-writer: feature "${args.feature_code}" not found`);
+    }
+    out.outgoing = (feature.links ?? [])
+      .filter(l => !kind || l.kind === kind)
+      .map(l => ({ kind: l.kind, to_code: l.to_code, note: l.note }));
+  }
+
+  if (direction === 'incoming' || direction === 'both') {
+    const all = _listFeatures(cwd);
+    const incoming = [];
+    for (const f of all) {
+      if (f.code === args.feature_code) continue;
+      for (const l of (f.links ?? [])) {
+        if (l.to_code !== args.feature_code) continue;
+        if (kind && l.kind !== kind) continue;
+        incoming.push({ kind: l.kind, from_code: f.code, note: l.note });
+      }
+    }
+    out.incoming = incoming;
+  }
+
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Exports for tests / introspection
 // ---------------------------------------------------------------------------
 
-export const _internals = { TRANSITIONS, STATUSES, COMPLEXITIES };
+export const _internals = { TRANSITIONS, STATUSES, COMPLEXITIES, LINK_KINDS };