@smartmemory/compose 0.1.5-beta → 0.1.7-beta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.1.5-beta",
+  "version": "0.1.7-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",
@@ -8,6 +8,10 @@
   "bin": {
     "compose": "./bin/compose.js"
   },
+  "exports": {
+    "./mcp": "./server/compose-mcp.js",
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "dev": "node server/supervisor.js 2>&1 | tee /tmp/compose-server.log",
     "dev:server": "node server/supervisor.js",

package/server/compose-mcp-tools.js

@@ -216,6 +216,86 @@ export async function toolRoadmapDiff(args) {
   return roadmapDiff(getTargetRoot(), args);
 }
 
+export async function toolLinkArtifact(args) {
+  const { linkArtifact } = await import('../lib/feature-writer.js');
+  return linkArtifact(getTargetRoot(), args);
+}
+
+export async function toolLinkFeatures(args) {
+  const { linkFeatures } = await import('../lib/feature-writer.js');
+  return linkFeatures(getTargetRoot(), args);
+}
+
+export async function toolGetFeatureArtifacts(args) {
+  const { getFeatureArtifacts } = await import('../lib/feature-writer.js');
+  return getFeatureArtifacts(getTargetRoot(), args);
+}
+
+export async function toolGetFeatureLinks(args) {
+  const { getFeatureLinks } = await import('../lib/feature-writer.js');
+  return getFeatureLinks(getTargetRoot(), args);
+}
+
+// ---------------------------------------------------------------------------
+// Changelog writer — COMP-MCP-CHANGELOG-WRITER
+// ---------------------------------------------------------------------------
+
+export async function toolAddChangelogEntry(args) {
+  const { addChangelogEntry } = await import('../lib/changelog-writer.js');
+  return addChangelogEntry(getTargetRoot(), args);
+}
+
+export async function toolGetChangelogEntries(args) {
+  const { getChangelogEntries } = await import('../lib/changelog-writer.js');
+  return getChangelogEntries(getTargetRoot(), args);
+}
+
+// ---------------------------------------------------------------------------
+// Journal writer — COMP-MCP-JOURNAL-WRITER
+// ---------------------------------------------------------------------------
+
+export async function toolWriteJournalEntry(args) {
+  const { writeJournalEntry } = await import('../lib/journal-writer.js');
+  return writeJournalEntry(getTargetRoot(), args);
+}
+
+export async function toolGetJournalEntries(args) {
+  const { getJournalEntries } = await import('../lib/journal-writer.js');
+  return getJournalEntries(getTargetRoot(), args);
+}
+
+// ---------------------------------------------------------------------------
+// Completion writer — COMP-MCP-COMPLETION
+// ---------------------------------------------------------------------------
+
+export async function toolRecordCompletion(args) {
+  const { recordCompletion } = await import('../lib/completion-writer.js');
+  return recordCompletion(getTargetRoot(), args);
+}
+
+export async function toolGetCompletions(args) {
+  const { getCompletions } = await import('../lib/completion-writer.js');
+  return getCompletions(getTargetRoot(), args);
+}
+
+export async function toolValidateFeature(args = {}) {
+  const { validateFeature } = await import('../lib/feature-validator.js');
+  const { feature_code, external_prefixes, feature_json_mode } = args;
+  return validateFeature(getTargetRoot(), feature_code, {
+    externalPrefixes: external_prefixes,
+    featureJsonMode: feature_json_mode,
+  });
+}
+
+export async function toolValidateProject(args = {}) {
+  const { validateProject } = await import('../lib/feature-validator.js');
+  const { external_prefixes, feature_json_mode } = args;
+  return validateProject(getTargetRoot(), {
+    externalPrefixes: external_prefixes,
+    featureJsonMode: feature_json_mode,
+  });
+}
+
 export async function toolBindSession({ featureCode }) {
   const postData = JSON.stringify({ featureCode });
   return new Promise((resolve, reject) => {

package/server/compose-mcp.js

@@ -46,6 +46,18 @@ import {
   toolAddRoadmapEntry,
   toolSetFeatureStatus,
   toolRoadmapDiff,
+  toolLinkArtifact,
+  toolLinkFeatures,
+  toolGetFeatureArtifacts,
+  toolGetFeatureLinks,
+  toolAddChangelogEntry,
+  toolGetChangelogEntries,
+  toolWriteJournalEntry,
+  toolGetJournalEntries,
+  toolRecordCompletion,
+  toolGetCompletions,
+  toolValidateFeature,
+  toolValidateProject,
 } from './compose-mcp-tools.js';
 
 // ---------------------------------------------------------------------------
@@ -312,6 +324,212 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'validate_feature',
+    description: 'Cross-check a single feature against ROADMAP, vision-state, feature.json, folder contents, linked artifacts, and cross-references. Returns structured findings with severity (error/warning/info). FEATURE_NOT_FOUND emitted as a finding (not thrown) when the code matches strict regex but exists in no source.',
+    inputSchema: {
+      type: 'object',
+      required: ['feature_code'],
+      properties: {
+        feature_code: { type: 'string', description: 'Strict feature code, e.g. "COMP-MCP-VALIDATE"' },
+        external_prefixes: { type: 'array', items: { type: 'string' }, description: 'Code prefixes (e.g. ["STRAT-"]) treated as external; downgrades ORPHAN_FOLDER to info' },
+        feature_json_mode: { type: 'boolean', description: 'Default true. Set false to skip feature.json comparisons in legacy projects.' },
+      },
+    },
+  },
+  {
+    name: 'validate_project',
+    description: 'Run validate_feature for every code in vision-state, ROADMAP, and folders, plus cross-cutting checks (orphan folders, dangling cross-refs, CHANGELOG references, journal index drift). Returns the union of all findings.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        external_prefixes: { type: 'array', items: { type: 'string' } },
+        feature_json_mode: { type: 'boolean' },
+      },
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // Linker — COMP-MCP-ARTIFACT-LINKER
+  // -------------------------------------------------------------------------
+  {
+    name: 'link_artifact',
+    description: 'Register a non-canonical artifact (snapshot, journal entry, finding, etc.) on a feature. Canonical artifacts (design.md, plan.md, …) inside the feature folder are auto-discovered and rejected here. Stores in feature.json artifacts[]; dedups on (type, path); appends an audit event (best-effort).',
+    inputSchema: {
+      type: 'object',
+      required: ['feature_code', 'artifact_type', 'path'],
+      properties: {
+        feature_code: { type: 'string' },
+        artifact_type: { type: 'string', description: 'e.g. "journal", "snapshot", "finding", "report-supplement", "link", "external"' },
+        path: { type: 'string', description: 'Repo-relative path. Must exist; cannot contain ".." after normalization.' },
+        status: { type: 'string', enum: ['current', 'superseded', 'historical'] },
+        force: { type: 'boolean', description: 'Overwrite an existing entry with the same (type, path)' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'link_features',
+    description: 'Register a typed cross-feature relationship. Stores on the source feature; query the inverse via get_feature_links(direction:"incoming"). Closed enum on kind; self-links rejected; dedups on (kind, to_code).',
+    inputSchema: {
+      type: 'object',
+      required: ['from_code', 'to_code', 'kind'],
+      properties: {
+        from_code: { type: 'string' },
+        to_code: { type: 'string', description: 'Target feature code. Need not exist yet (you can link to a code you are about to create).' },
+        kind: { type: 'string', enum: ['surfaced_by', 'blocks', 'depends_on', 'follow_up', 'supersedes', 'related'] },
+        note: { type: 'string' },
+        force: { type: 'boolean' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'get_feature_artifacts',
+    description: 'Read both canonical (auto-discovered: design.md, plan.md, …) and linked (snapshots, journals, findings) artifacts for a feature in one call. Each linked entry includes a current existence check.',
+    inputSchema: {
+      type: 'object',
+      required: ['feature_code'],
+      properties: {
+        feature_code: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'get_feature_links',
+    description: 'Read outgoing and/or incoming feature links. Default returns both directions; filter by kind if needed.',
+    inputSchema: {
+      type: 'object',
+      required: ['feature_code'],
+      properties: {
+        feature_code: { type: 'string' },
+        direction: { type: 'string', enum: ['outgoing', 'incoming', 'both'] },
+        kind: { type: 'string' },
+      },
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // Changelog writer — COMP-MCP-CHANGELOG-WRITER
+  // -------------------------------------------------------------------------
+  {
+    name: 'add_changelog_entry',
+    description: 'Insert (or replace, with force: true) a typed entry in compose/CHANGELOG.md. Idempotent on (date_or_version, code) at storage level; optional caller-supplied idempotency_key for retry safety. Audit-log append is best-effort. Use this instead of editing CHANGELOG.md by hand.',
+    inputSchema: {
+      type: 'object',
+      required: ['date_or_version', 'code', 'summary'],
+      properties: {
+        date_or_version: { type: 'string', description: 'ISO date "YYYY-MM-DD" or semver "vX.Y.Z"' },
+        code: { type: 'string', description: 'Feature code (e.g. "COMP-FOO-1"). Uppercase A-Z, digits, dashes; cannot start or end with a dash.' },
+        summary: { type: 'string', description: 'One-line summary; renders as the "— summary" tail of the entry header.' },
+        body: { type: 'string', description: 'Free paragraphs between header and labeled subsections.' },
+        sections: {
+          type: 'object',
+          description: 'Optional labeled subsections; emitted in fixed order Added → Changed → Fixed → Snapshot.',
+          properties: {
+            added:    { type: 'array', items: { type: 'string' } },
+            changed:  { type: 'array', items: { type: 'string' } },
+            fixed:    { type: 'array', items: { type: 'string' } },
+            snapshot: { type: 'array', items: { type: 'string' } },
+          },
+          additionalProperties: false,
+        },
+        force: { type: 'boolean', description: 'If true and an entry with the same (date_or_version, code) exists, replace it in place.' },
+        idempotency_key: { type: 'string', description: 'Optional caller-supplied key. Same key replays return the cached result without re-mutating.' },
+      },
+    },
+  },
+  {
+    name: 'get_changelog_entries',
+    description: 'Read parsed entries from compose/CHANGELOG.md. Filter by code (exact) or since (shorthand "24h"/"7d"/"30m" or ISO date — date-only; version surfaces always pass through).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since: { type: 'string', description: 'Window: shorthand like "24h"/"7d"/"30m" or ISO date. Date-only filter; version surfaces are always returned.' },
+        code: { type: 'string' },
+        limit: { type: 'number', description: 'Default 50; capped at 500.' },
+      },
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // Journal writer — COMP-MCP-JOURNAL-WRITER
+  // -------------------------------------------------------------------------
+  {
+    name: 'write_journal_entry',
+    description: 'Write a typed entry to compose/docs/journal/ with auto-numbered global session and inserted index row. Idempotent on (date, slug) at storage level; optional caller idempotency_key for retry safety. Audit-log append is best-effort.',
+    inputSchema: {
+      type: 'object',
+      required: ['date', 'slug', 'sections', 'summary_for_index'],
+      properties: {
+        date: { type: 'string', description: 'ISO date "YYYY-MM-DD".' },
+        slug: { type: 'string', description: 'Kebab-case slug for the filename, e.g. "mcp-journal-writer".' },
+        sections: {
+          type: 'object',
+          required: ['what_happened', 'what_we_built', 'what_we_learned', 'open_threads'],
+          properties: {
+            what_happened:   { type: 'string' },
+            what_we_built:   { type: 'string' },
+            what_we_learned: { type: 'string' },
+            open_threads:    { type: 'string' },
+          },
+          additionalProperties: false,
+        },
+        summary_for_index: { type: 'string', description: 'Single-line summary for the README index row. No newlines, no "|".' },
+        feature_code:      { type: 'string', description: 'Optional feature code stamped in entry frontmatter.' },
+        closing_line:      { type: 'string', description: 'Optional final italicized one-liner.' },
+        force:             { type: 'boolean', description: 'If true and an entry with the same (date, slug) exists, overwrite in place.' },
+        idempotency_key:   { type: 'string', description: 'Optional caller-supplied key. Same key replays return the cached result without re-mutating.' },
+      },
+    },
+  },
+  {
+    name: 'get_journal_entries',
+    description: 'Read parsed entries from compose/docs/journal/. Filter by feature_code (exact), session (exact), or since (shorthand "24h"/"7d"/"30m" or ISO date).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since:        { type: 'string' },
+        feature_code: { type: 'string' },
+        session:      { type: 'number' },
+        limit:        { type: 'number', description: 'Default 50; capped at 500.' },
+      },
+    },
+  },
+  // -------------------------------------------------------------------------
+  // Completion writer — COMP-MCP-COMPLETION
+  // -------------------------------------------------------------------------
+  {
+    name: 'record_completion',
+    description: 'Record a completion bound to a commit SHA. Stores in feature.json completions[]; idempotent on (feature_code, commit_sha); when set_status:true (default) also flips status to COMPLETE via set_feature_status. Audit append best-effort. Status-flip failure rethrows as STATUS_FLIP_AFTER_COMPLETION_RECORDED with err.cause; the completion record is still persisted.',
+    inputSchema: {
+      type: 'object',
+      required: ['feature_code', 'commit_sha', 'tests_pass', 'files_changed'],
+      properties: {
+        feature_code:    { type: 'string' },
+        commit_sha:      { type: 'string', description: 'Full 40-char hex SHA (Decision 9). Short prefixes are rejected on write. Stored verbatim; commit_sha_short is derived for display only.' },
+        tests_pass:      { type: 'boolean' },
+        files_changed:   { type: 'array', items: { type: 'string' } },
+        notes:           { type: 'string' },
+        set_status:      { type: 'boolean', description: 'Default true. When true, flips status to COMPLETE via set_feature_status.' },
+        force:           { type: 'boolean', description: 'If true and a record with the same (feature_code, commit_sha) exists, replace it in place.' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'get_completions',
+    description: 'Read completion records from feature.json files. Filter by feature_code (exact), commit_sha (short or full prefix), or since (shorthand or ISO date).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        feature_code: { type: 'string' },
+        commit_sha:   { type: 'string' },
+        since:        { type: 'string' },
+        limit:        { type: 'number', description: 'Default 50; capped at 500.' },
+      },
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -352,6 +570,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'add_roadmap_entry':        result = await toolAddRoadmapEntry(args); break;
       case 'set_feature_status':       result = await toolSetFeatureStatus(args); break;
       case 'roadmap_diff':             result = await toolRoadmapDiff(args); break;
+      case 'link_artifact':            result = await toolLinkArtifact(args); break;
+      case 'link_features':            result = await toolLinkFeatures(args); break;
+      case 'get_feature_artifacts':    result = await toolGetFeatureArtifacts(args); break;
+      case 'get_feature_links':        result = await toolGetFeatureLinks(args); break;
+      case 'add_changelog_entry':      result = await toolAddChangelogEntry(args); break;
+      case 'get_changelog_entries':    result = await toolGetChangelogEntries(args); break;
+      case 'write_journal_entry':      result = await toolWriteJournalEntry(args); break;
+      case 'get_journal_entries':      result = await toolGetJournalEntries(args); break;
+      case 'record_completion':        result = await toolRecordCompletion(args); break;
+      case 'get_completions':          result = await toolGetCompletions(args); break;
+      case 'validate_feature':         result = await toolValidateFeature(args); break;
+      case 'validate_project':         result = await toolValidateProject(args); break;
       // agent_run removed — STRAT-DEDUP-AGENTRUN v1. Use mcp__stratum__stratum_agent_run.
       default:
         return {
@@ -363,8 +593,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
     };
   } catch (err) {
+    // Surface typed error codes (e.g. INVALID_INPUT, CHANGELOG_FORMAT) when
+    // tools attach them, so MCP callers can branch deterministically. Plain
+    // errors fall back to the original "Error: <message>" shape.
+    // When err.cause is an Error-shaped object, append it so callers can
+    // distinguish partial-write sub-errors (e.g. rollback succeeded vs failed).
+    let text = err && err.code
+      ? `Error [${err.code}]: ${err.message}`
+      : `Error: ${err.message}`;
+    if (err && err.cause && typeof err.cause.message === 'string') {
+      text += err.cause.code
+        ? `\n  Caused by [${err.cause.code}]: ${err.cause.message}`
+        : `\n  Caused by: ${err.cause.message}`;
+    }
     return {
-      content: [{ type: 'text', text: `Error: ${err.message}` }],
+      content: [{ type: 'text', text }],
       isError: true,
     };
   }

package/server/schema-validator.js

@@ -5,26 +5,43 @@ import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const SCHEMA_PATH = resolve(__dirname, '../contracts/comp-obs-contract.schema.json');
+const DEFAULT_SCHEMA_PATH = resolve(__dirname, '../contracts/comp-obs-contract.schema.json');
 
-let cached = null;
+// Per-path cache. Each entry: { schema, ajv }.
+const cache = new Map();
 
-function load() {
-  if (cached) return cached;
-  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+function load(schemaPath = DEFAULT_SCHEMA_PATH) {
+  if (cache.has(schemaPath)) return cache.get(schemaPath);
+  const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
   const ajv = new Ajv({ strict: false, allErrors: true });
   addFormats(ajv);
   ajv.addSchema(schema);
-  cached = { schema, ajv };
-  return cached;
+  const entry = { schema, ajv };
+  cache.set(schemaPath, entry);
+  return entry;
+}
+
+/**
+ * Load (and cache) a schema by absolute path. Returns `{ schema, ajv }`.
+ * Used by code that wants to compile arbitrary `$ref`s against the schema
+ * without going through the SchemaValidator class.
+ */
+export function loadSchema(schemaPath) {
+  return load(schemaPath);
 }
 
 export class SchemaValidator {
-  constructor() {
-    const { schema, ajv } = load();
+  /**
+   * @param {string} [schemaPath] Absolute path to a JSON Schema file.
+   *   Default is the comp-obs-contract schema (back-compat for existing
+   *   callers that pass no args).
+   */
+  constructor(schemaPath = DEFAULT_SCHEMA_PATH) {
+    const { schema, ajv } = load(schemaPath);
     this.schema = schema;
     this.ajv = ajv;
     this._validators = new Map();
+    this._rootValidator = null;
   }
 
   _getValidator(defName) {
@@ -39,11 +56,35 @@ export class SchemaValidator {
     return v;
   }
 
+  /**
+   * Validate `obj` against `schema.definitions[defName]`. Used by the
+   * comp-obs-contract code paths.
+   */
   validate(defName, obj) {
     const v = this._getValidator(defName);
     const valid = v(obj);
     return { valid: !!valid, errors: valid ? [] : (v.errors || []) };
   }
+
+  /**
+   * Validate `obj` against the schema's root (no $defs/$ref indirection).
+   * Used by feature-json / vision-state / roadmap-row schemas, which are
+   * top-level shapes without nested definitions.
+   */
+  validateRoot(obj) {
+    if (!this._rootValidator) {
+      // ajv.getSchema by $id returns the root validator if the schema was
+      // added via addSchema (which load() does).
+      let v = this.schema.$id ? this.ajv.getSchema(this.schema.$id) : null;
+      if (!v) v = this.ajv.compile(this.schema);
+      this._rootValidator = v;
+    }
+    const v = this._rootValidator;
+    const valid = v(obj);
+    return { valid: !!valid, errors: valid ? [] : (v.errors || []) };
+  }
 }
 
+// Back-compat export — points at the comp-obs schema version. Existing
+// callers consuming SCHEMA_VERSION continue to work unchanged.
 export const SCHEMA_VERSION = load().schema.version;