@smartmemory/compose 0.1.6-beta → 0.1.7-beta

package/bin/compose.js

@@ -1180,92 +1180,129 @@ if (cmd === 'hooks') {
   const hooksDir = pjoin(gitDir, 'hooks')
   const { mkdirSync: mSync } = await import('fs')
   mSync(hooksDir, { recursive: true })
-  const hookPath = pjoin(hooksDir, 'post-commit')
-
-  // Marker line used to identify our hooks
-  const HOOK_MARKER = '# Compose post-commit hook —'
 
   // Resolve absolute paths for substitution
   const composeBin = presolve(presolve(futp(import.meta.url), '..'), 'compose.js')
   const composeNode = process.execPath
 
-  if (sub === 'install') {
-    // Read template
-    const templatePath = pjoin(presolve(futp(import.meta.url), '..'), 'git-hooks', 'post-commit.template')
+  // Hook-type table. Each entry knows its template, marker, and destination.
+  const HOOK_TYPES = {
+    'post-commit': {
+      template: pjoin(presolve(futp(import.meta.url), '..'), 'git-hooks', 'post-commit.template'),
+      marker:   '# Compose post-commit hook —',
+      dest:     pjoin(hooksDir, 'post-commit'),
+    },
+    'pre-push': {
+      template: pjoin(presolve(futp(import.meta.url), '..'), 'git-hooks', 'pre-push.template'),
+      marker:   '# Compose pre-push hook —',
+      dest:     pjoin(hooksDir, 'pre-push'),
+    },
+  }
+
+  // Determine which hook types this invocation operates on.
+  // Flags: --pre-push, --post-commit, or none (default = post-commit, back-compat).
+  const selectedTypes = []
+  if (hookFlags['pre-push']) selectedTypes.push('pre-push')
+  if (hookFlags['post-commit']) selectedTypes.push('post-commit')
+  if (selectedTypes.length === 0) selectedTypes.push('post-commit') // default = back-compat
+
+  function installOne(type) {
+    const { template: tplPath, marker, dest } = HOOK_TYPES[type]
     let template
     try {
-      template = rfSync(templatePath, 'utf-8')
+      template = rfSync(tplPath, 'utf-8')
     } catch (err) {
-      console.error(`Error: could not read hook template: ${err.message}`)
-      process.exit(1)
+      console.error(`Error: could not read ${type} template: ${err.message}`)
+      return 1
     }
-
-    // Check existing hook
-    if (exSync(hookPath)) {
-      const existing = rfSync(hookPath, 'utf-8')
-      const isOurs = existing.includes(HOOK_MARKER)
+    if (exSync(dest)) {
+      const existing = rfSync(dest, 'utf-8')
+      const isOurs = existing.includes(marker)
       if (!isOurs && !hookFlags.force) {
-        console.error('Error: a foreign post-commit hook already exists at ' + hookPath)
-        console.error('')
-        console.error('To chain our hook after yours, add this to your existing hook:')
+        console.error(`Error: a foreign ${type} hook already exists at ${dest}`)
         console.error('')
-        console.error(`  "${composeNode}" "${composeBin}" record-completion ...`)
-        console.error('')
-        console.error('Or run `compose hooks install --force` to overwrite.')
-        process.exit(1)
+        console.error(`Run \`compose hooks install --${type} --force\` to overwrite.`)
+        return 1
       }
     }
-
-    // Substitute placeholders
     const substituted = template
       .replace(/__COMPOSE_NODE__/g, composeNode)
       .replace(/__COMPOSE_BIN__/g, composeBin)
-
-    wfSync(hookPath, substituted)
-    chmodSync(hookPath, 0o755)
-    console.log(`Installed post-commit hook at ${hookPath}`)
+    wfSync(dest, substituted)
+    chmodSync(dest, 0o755)
+    console.log(`Installed ${type} hook at ${dest}`)
     console.log(`  COMPOSE_NODE=${composeNode}`)
     console.log(`  COMPOSE_BIN=${composeBin}`)
-    process.exit(0)
+    return 0
   }
 
-  if (sub === 'uninstall') {
-    if (!exSync(hookPath)) {
-      console.log('No post-commit hook installed.')
-      process.exit(0)
+  function uninstallOne(type) {
+    const { marker, dest } = HOOK_TYPES[type]
+    if (!exSync(dest)) {
+      console.log(`No ${type} hook installed.`)
+      return 0
     }
-    const content = rfSync(hookPath, 'utf-8')
-    if (!content.includes(HOOK_MARKER)) {
-      console.warn('Warning: post-commit hook exists but does not appear to be a Compose hook (marker not found). Leaving alone.')
-      process.exit(0)
+    const content = rfSync(dest, 'utf-8')
+    if (!content.includes(marker)) {
+      console.warn(`Warning: ${type} hook exists but does not appear to be a Compose hook (marker not found). Leaving alone.`)
+      return 0
     }
-    const { rmSync: rmS } = await import('fs')
-    rmS(hookPath)
-    console.log(`Removed post-commit hook at ${hookPath}`)
-    process.exit(0)
+    const { rmSync: rmS } = require('fs')
+    rmS(dest)
+    console.log(`Removed ${type} hook at ${dest}`)
+    return 0
   }
 
-  // status (default)
-  if (!sub || sub === 'status') {
-    if (!exSync(hookPath)) {
-      console.log('absent — no post-commit hook installed')
-      process.exit(0)
+  function statusOne(type) {
+    const { marker, dest } = HOOK_TYPES[type]
+    if (!exSync(dest)) {
+      console.log(`${type}: absent — no hook installed`)
+      return
     }
-    const content = rfSync(hookPath, 'utf-8')
-    if (!content.includes(HOOK_MARKER)) {
-      console.log('foreign — post-commit hook exists but is not a Compose hook')
-      process.exit(0)
+    const content = rfSync(dest, 'utf-8')
+    if (!content.includes(marker)) {
+      console.log(`${type}: foreign — hook exists but is not a Compose hook`)
+      return
     }
-    // Check if paths match current
-    const nodeMatch   = content.includes(`COMPOSE_NODE="${composeNode}"`)
-    const binMatch    = content.includes(`COMPOSE_BIN="${composeBin}"`)
+    const nodeMatch = content.includes(`COMPOSE_NODE="${composeNode}"`)
+    const binMatch  = content.includes(`COMPOSE_BIN="${composeBin}"`)
     if (nodeMatch && binMatch) {
-      console.log('installed (current)')
+      console.log(`${type}: installed (current)`)
     } else {
-      console.log('installed (stale paths — re-run install)')
+      console.log(`${type}: installed (stale paths — re-run install)`)
       if (!nodeMatch) console.log(`  expected COMPOSE_NODE="${composeNode}"`)
       if (!binMatch)  console.log(`  expected COMPOSE_BIN="${composeBin}"`)
     }
+  }
+
+  if (sub === 'install') {
+    let exitCode = 0
+    for (const t of selectedTypes) exitCode = installOne(t) || exitCode
+    process.exit(exitCode)
+  }
+
+  if (sub === 'uninstall') {
+    const { rmSync: _rmS } = await import('fs') // ensure fs.rmSync is available
+    // uninstallOne calls require('fs') but we're ESM — replace with import-based deletion
+    for (const t of selectedTypes) {
+      const { marker, dest } = HOOK_TYPES[t]
+      if (!exSync(dest)) { console.log(`No ${t} hook installed.`); continue }
+      const content = rfSync(dest, 'utf-8')
+      if (!content.includes(marker)) {
+        console.warn(`Warning: ${t} hook exists but does not appear to be a Compose hook (marker not found). Leaving alone.`)
+        continue
+      }
+      _rmS(dest)
+      console.log(`Removed ${t} hook at ${dest}`)
+    }
+    process.exit(0)
+  }
+
+  // status (default)
+  if (!sub || sub === 'status') {
+    // Status reports on ALL known hook types (selection flags ignored), so users
+    // see the full picture. Selection only affects install/uninstall.
+    for (const t of Object.keys(HOOK_TYPES)) statusOne(t)
     process.exit(0)
   }
 
@@ -1273,6 +1310,100 @@ if (cmd === 'hooks') {
   process.exit(1)
 }
 
+if (cmd === 'validate') {
+  // compose validate [--scope=feature|project] [--code=CODE] [--block-on=error|warning|info] [--json]
+  let scope = 'project'
+  let code = null
+  let blockOn = 'error'
+  let asJson = false
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--help' || a === '-h') {
+      console.log(`Usage: compose validate [options]
+
+Options:
+  --scope=feature|project     Scope (default: project)
+  --code=CODE                 Feature code (required when scope=feature)
+  --block-on=LEVEL            Exit non-zero if any finding >= LEVEL (default: error)
+                              LEVEL: error | warning | info
+  --json                      Emit findings as JSON (default: human-readable)
+
+Exit codes:
+  0   no findings >= block-on threshold
+  1   findings >= block-on threshold present
+  2   usage error`)
+      process.exit(0)
+    }
+    if (a === '--json') { asJson = true; continue }
+    if (a.startsWith('--scope=')) scope = a.slice('--scope='.length)
+    else if (a === '--scope') scope = args[++i]
+    else if (a.startsWith('--code=')) code = a.slice('--code='.length)
+    else if (a === '--code') code = args[++i]
+    else if (a.startsWith('--block-on=')) blockOn = a.slice('--block-on='.length)
+    else if (a === '--block-on') blockOn = args[++i]
+    else if (a.startsWith('--')) {
+      console.error(`Unknown flag: ${a}`)
+      process.exit(2)
+    }
+  }
+  if (!['feature', 'project'].includes(scope)) {
+    console.error(`Invalid --scope=${scope}; expected feature or project`)
+    process.exit(2)
+  }
+  if (scope === 'feature' && !code) {
+    console.error(`--scope=feature requires --code=<CODE>`)
+    process.exit(2)
+  }
+  if (!['error', 'warning', 'info'].includes(blockOn)) {
+    console.error(`Invalid --block-on=${blockOn}; expected error, warning, or info`)
+    process.exit(2)
+  }
+
+  const { validateFeature, validateProject } = await import('../lib/feature-validator.js')
+  let result
+  try {
+    result = scope === 'feature'
+      ? await validateFeature(process.cwd(), code)
+      : await validateProject(process.cwd())
+  } catch (err) {
+    if (err.code === 'INVALID_INPUT') {
+      console.error(`Error [INVALID_INPUT]: ${err.message}`)
+      process.exit(2)
+    }
+    console.error(`Error: ${err.message}`)
+    process.exit(2)
+  }
+
+  // Threshold: findings at or above this severity block the exit code
+  const SEV_RANK = { error: 3, warning: 2, info: 1 }
+  const threshold = SEV_RANK[blockOn]
+  const blocking = result.findings.filter((f) => SEV_RANK[f.severity] >= threshold)
+
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    const byKind = {}
+    for (const f of result.findings) {
+      const sev = f.severity.toUpperCase()
+      const tag = `[${sev}] ${f.kind}${f.feature_code ? ' ' + f.feature_code : ''}`
+      if (!byKind[tag]) byKind[tag] = []
+      byKind[tag].push(f.detail)
+    }
+    if (result.findings.length === 0) {
+      console.log(`compose validate: no findings (scope=${scope}${code ? ' code=' + code : ''})`)
+    } else {
+      console.log(`compose validate findings (scope=${scope}${code ? ' code=' + code : ''}):`)
+      for (const tag of Object.keys(byKind).sort()) {
+        console.log(`  ${tag}`)
+        for (const detail of byKind[tag]) console.log(`    - ${detail}`)
+      }
+      console.log(`\n${result.findings.length} finding(s); ${blocking.length} at or above --block-on=${blockOn}`)
+    }
+  }
+
+  process.exit(blocking.length > 0 ? 1 : 0)
+}
+
 if (cmd === 'pipeline') {
   const { runPipelineCli } = await import('../lib/pipeline-cli.js')
   try {

package/bin/git-hooks/pre-push.template

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Compose pre-push hook — runs `compose validate` and blocks the push on
+# any error-severity drift finding. Installed by `compose hooks install --pre-push`;
+# placeholders below are substituted at install time.
+
+set -u
+COMPOSE_NODE="__COMPOSE_NODE__"
+COMPOSE_BIN="__COMPOSE_BIN__"
+LOG="${COMPOSE_HOOK_LOG:-.compose/data/pre-push.log}"
+mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
+
+OUTPUT=$("$COMPOSE_NODE" "$COMPOSE_BIN" validate --scope=project --block-on=error 2>&1)
+EXIT_CODE=$?
+
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo "$OUTPUT" | tee -a "$LOG" >&2
+  echo "" >&2
+  echo "compose validate found error-severity drift. Push aborted." >&2
+  echo "Run \`compose validate\` to see findings, then fix and retry." >&2
+  echo "Bypass at your own risk: git push --no-verify" >&2
+  exit "$EXIT_CODE"
+fi
+
+# Below-threshold findings (warnings/info) are still printed for visibility.
+echo "$OUTPUT"
+exit 0

package/contracts/feature-json.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://compose.smartmemory.dev/contracts/feature-json.schema.json",
+  "title": "feature.json",
+  "description": "Per-feature state record at docs/features/<CODE>/feature.json. Codifies the de facto union of fields produced today by typed writers and runtime code. Intentionally permissive (additionalProperties: true) until COMP-MCP-VALIDATE-SCHEMA-TIGHTEN follow-up.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["code"],
+  "properties": {
+    "code": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9-]*[A-Z0-9]$",
+      "description": "Strict feature code. Matches FEATURE_CODE_RE_STRICT."
+    },
+    "description": { "type": "string" },
+    "name": {
+      "type": "string",
+      "description": "Legacy alternative to description (de facto). Prefer description on new files."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["PLANNED", "IN_PROGRESS", "PARTIAL", "COMPLETE", "SUPERSEDED", "PARKED", "BLOCKED", "KILLED"]
+    },
+    "phase": { "type": ["string", "null"] },
+    "complexity": {
+      "oneOf": [
+        { "type": "string", "enum": ["S", "M", "L", "XL"] },
+        { "type": "number" }
+      ],
+      "description": "S/M/L/XL on new files; numeric on legacy files (e.g. COMP-DEBUG-1). Convergence deferred to COMP-MCP-VALIDATE-SCHEMA-TIGHTEN."
+    },
+    "position": { "type": ["integer", "string"] },
+    "parent": { "type": "string" },
+    "depends_on": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "De facto field on legacy files. Cross-feature dependency codes."
+    },
+    "source": {
+      "type": "string",
+      "description": "De facto field on legacy files."
+    },
+    "profile": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object", "additionalProperties": true }
+      ],
+      "description": "Either a string identifier or an inline profile object (de facto on COMP-DEBUG-1 etc.)."
+    },
+    "created": { "type": "string", "format": "date" },
+    "updated": { "type": "string", "format": "date" },
+    "commit_sha": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "artifacts": {
+      "type": "array",
+      "description": "Linked non-canonical artifacts (journal/snapshot pointers, external docs). Canonical artifacts (design.md, plan.md, etc.) under the feature folder are auto-discovered and explicitly NOT registered here.",
+      "items": {
+        "type": "object",
+        "required": ["type", "path"],
+        "properties": {
+          "type": { "type": "string", "enum": ["design", "prd", "architecture", "blueprint", "plan", "report", "journal", "snapshot"] },
+          "path": { "type": "string" },
+          "status": { "type": "string" }
+        }
+      }
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "to_code"],
+        "properties": {
+          "kind": { "type": "string", "enum": ["surfaced_by", "blocks", "depends_on", "follow_up", "supersedes", "related"] },
+          "to_code": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]*[A-Z0-9]$" },
+          "note": { "type": "string" }
+        }
+      }
+    },
+    "completions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["completion_id", "feature_code", "commit_sha"],
+        "properties": {
+          "completion_id": { "type": "string" },
+          "feature_code": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]*[A-Z0-9]$" },
+          "commit_sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+          "commit_sha_short": { "type": "string" },
+          "tests_pass": { "type": "boolean" },
+          "files_changed": { "type": "array", "items": { "type": "string" } },
+          "recorded_at": { "type": "string" },
+          "recorded_by": { "type": "string" },
+          "notes": { "type": "string" }
+        }
+      }
+    },
+    "lifecycle": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "currentPhase": { "type": "string" },
+        "phaseHistory": { "type": "array" }
+      }
+    },
+    "phaseHistory": {
+      "type": "array",
+      "description": "Empty array on every existing file today. Validator does not flag empty."
+    },
+    "filesChanged": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Written by runBuild() on completion. De facto field; not tightened in v1."
+    }
+  }
+}

package/contracts/roadmap-row.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://compose.smartmemory.dev/contracts/roadmap-row.schema.json",
+  "title": "Roadmap Row",
+  "description": "Single parsed ROADMAP.md row, mirroring lib/roadmap-parser.js FeatureEntry typedef. Validator filters out _anon_* sentinel codes (parser emits these for unrecognized rows) before applying this schema.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["code", "description", "status", "phaseId", "position"],
+  "properties": {
+    "code": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9-]*[A-Z0-9]$",
+      "description": "Strict feature code. Anonymous _anon_<n> sentinel codes from the parser are filtered before this schema runs."
+    },
+    "description": { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": ["PLANNED", "IN_PROGRESS", "PARTIAL", "COMPLETE", "SUPERSEDED", "PARKED", "BLOCKED", "KILLED"]
+    },
+    "phaseId": { "type": "string" },
+    "position": { "type": "integer", "minimum": 1 }
+  }
+}

package/contracts/vision-state.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://compose.smartmemory.dev/contracts/vision-state.schema.json",
+  "title": "vision-state.json",
+  "description": "Per-project vision-state document at .compose/data/vision-state.json. Codifies the shape produced by VisionStore (server/vision-store.js).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["items", "connections", "gates"],
+  "properties": {
+    "items": { "type": "array", "items": { "$ref": "#/definitions/Item" } },
+    "connections": { "type": "array" },
+    "gates": { "type": "array" },
+    "version": { "type": ["string", "number"] }
+  },
+  "definitions": {
+    "Item": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "type"],
+      "properties": {
+        "id": { "type": "string", "format": "uuid" },
+        "type": { "type": "string" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "confidence": { "type": ["number", "null"], "minimum": 0, "maximum": 4 },
+        "status": { "type": "string", "enum": ["planned", "in_progress", "complete", "blocked", "parked", "killed", "superseded"] },
+        "phase": { "type": ["string", "null"], "enum": ["vision", "requirements", "specification", "design", "planning", "implementation", "verification", "release", null] },
+        "parentId": { "type": ["string", "null"] },
+        "files": { "type": "array", "items": { "type": "string" } },
+        "priority": { "type": ["string", "number", "null"] },
+        "assignedTo": { "type": ["string", "null"] },
+        "governance": { "type": ["object", "null"] },
+        "featureCode": {
+          "type": ["string", "null"],
+          "description": "Top-level feature code. Current baseline for 41/42 items. lifecycle.featureCode is preferred where present; both are legal. Migration tracked as COMP-VISION-STATE-LIFECYCLE-MIGRATE."
+        },
+        "group": { "type": ["string", "null"] },
+        "slug": { "type": ["string", "null"] },
+        "position": {
+          "type": ["object", "null"],
+          "additionalProperties": true,
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" }
+          }
+        },
+        "createdAt": { "type": "string" },
+        "updatedAt": { "type": "string" },
+        "summary": { "type": ["string", "null"] },
+        "stratumFlowId": { "type": ["string", "null"] },
+        "evidence": { "type": ["object", "array", "null"] },
+        "lifecycle": {
+          "type": ["object", "null"],
+          "additionalProperties": true,
+          "properties": {
+            "featureCode": { "type": ["string", "null"] },
+            "currentPhase": { "type": ["string", "null"] },
+            "lifecycle_ext": { "type": "object", "additionalProperties": true }
+          }
+        }
+      }
+    }
+  }
+}

package/lib/completion-writer.js

@@ -27,12 +27,11 @@ import { join, dirname, posix } from 'path';
 import { readFeature, updateFeature, listFeatures } from './feature-json.js';
 import { appendEvent, normalizeSince } from './feature-events.js';
 import { checkOrInsert } from './idempotency.js';
+import { FEATURE_CODE_RE_STRICT as FEATURE_CODE_RE } from './feature-code.js';
 
 // ---------------------------------------------------------------------------
 // Constants + regexes
 // ---------------------------------------------------------------------------
-
-const FEATURE_CODE_RE = /^[A-Z][A-Z0-9-]*[A-Z0-9]$/;
 const SHA_RE          = /^[0-9a-f]{40}$/i;   // FULL SHA only (Decision 9). Case-insensitive input; normalize to lowercase.
 const SHORT_LEN       = 8;                    // Display only — never the dedup key.
 const DEFAULT_LIMIT   = 50;

package/lib/feature-code.js

@@ -0,0 +1,29 @@
+/**
+ * Strict feature-code regex used by every typed writer to validate input.
+ * Contract: starts with uppercase letter, contains uppercase/digits/hyphens,
+ * ends in uppercase or digit (no trailing hyphen, no leading hyphen).
+ *
+ * Three writer sites import from here: feature-writer, completion-writer,
+ * journal-writer. The roadmap parser deliberately uses a looser regex
+ * (`/^[A-Z][\w-]*-\d+/`) to match anonymous/legacy table rows and is exempt
+ * from this extraction.
+ *
+ * Introduced by COMP-MCP-VALIDATE.
+ */
+
+export const FEATURE_CODE_RE_STRICT = /^[A-Z][A-Z0-9-]*[A-Z0-9]$/;
+
+/**
+ * Throws an Error with `code: 'INVALID_INPUT'` if `code` is not a strict
+ * feature code. Otherwise returns silently.
+ *
+ * @param {unknown} code
+ * @throws {Error & { code: 'INVALID_INPUT' }}
+ */
+export function validateCode(code) {
+  if (typeof code !== 'string' || !FEATURE_CODE_RE_STRICT.test(code)) {
+    const err = new Error(`Invalid feature code: ${JSON.stringify(code)}`);
+    err.code = 'INVALID_INPUT';
+    throw err;
+  }
+}