@smartmemory/compose 0.1.43-beta → 0.2.0

package/bin/compose.js

@@ -119,6 +119,9 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('  roadmap generate   Regenerate ROADMAP.md from feature.json files')
   console.log('  roadmap migrate    Extract ROADMAP.md entries into feature.json files')
   console.log('  roadmap check      Verify feature.json and ROADMAP.md are in sync')
+  console.log('  roadmap xref-sync  Pull-reconcile feature.json external links to live state')
+  console.log('  items              List vision items from local state (no server)')
+  console.log('  items show <id>    Show detail for a specific vision item')
   console.log('  triage    Analyze a feature and recommend build profile')
   console.log('  qa-scope  Show affected routes from a feature\'s changed files')
   console.log('  init      Initialize Compose in the current project')
@@ -1034,22 +1037,47 @@ _This is a seed design doc created by \`compose feature\`. The \`compose build\`
 if (cmd === 'roadmap') {
   const subcmd = args[0]
 
-  // compose roadmap generate — regenerate ROADMAP.md from feature.json files
+  // compose roadmap generate — regenerate ROADMAP.md from feature.json files,
+  // converging to a fixed point before finishing.
   if (subcmd === 'generate' || subcmd === 'gen') {
     const { writeRoadmap } = await import('../lib/roadmap-gen.js')
+    const { checkRoundtrip } = await import('../lib/roadmap-roundtrip.js')
+    const { listFeatures } = await import('../lib/feature-json.js')
+    const { loadExternalPrefixes } = await import('../lib/project-paths.js')
+    const { isNarrativeOwned } = await import('../lib/roadmap-config.js')
     const { root: cwd } = resolveCwdWithWorkspace(args)
+    // Narrative-owned workspaces (#39): ROADMAP.md is hand-authored, not a render
+    // of feature.json. writeRoadmap already no-ops, but the canonicalization pass
+    // below would still overwrite the file (or crash if it's absent) — skip the
+    // whole generate path here so the hand-authored file is never touched.
+    if (isNarrativeOwned(cwd)) {
+      console.log('narrative-owned workspace (roadmap.narrative=true) — ROADMAP.md is hand-authored; generate skipped.')
+      process.exit(0)
+    }
     const path = writeRoadmap(cwd)
-    console.log(`Generated ${path} from feature.json files`)
+    const externalPrefixes = loadExternalPrefixes(cwd)
+    // checkRoundtrip's now:'0000-00-00' is only used to detect/canonicalize
+    // structural non-convergence — once the file has headings, readPreamble
+    // preserves the existing preamble date verbatim, so no sentinel date leaks.
+    const rt = checkRoundtrip(readFileSync(path, 'utf-8'), listFeatures(cwd), { now: '0000-00-00', externalPrefixes })
+    if (!rt.fixedPoint) {
+      writeFileSync(path, rt.canonical)
+      console.log(`Generated ${path} (canonicalized over ${rt.passes} passes)`)
+    } else {
+      console.log(`Generated ${path} from feature.json files`)
+    }
     process.exit(0)
   }
 
   // compose roadmap migrate — extract ROADMAP.md entries into feature.json files
   if (subcmd === 'migrate') {
     const { migrateRoadmap } = await import('../lib/migrate-roadmap.js')
+    const { loadExternalPrefixes } = await import('../lib/project-paths.js')
     const { root: cwd } = resolveCwdWithWorkspace(args)
     const dryRun = args.includes('--dry-run')
     const overwrite = args.includes('--overwrite')
-    const result = migrateRoadmap(cwd, { dryRun, overwrite })
+    const externalPrefixes = loadExternalPrefixes(cwd)
+    const result = migrateRoadmap(cwd, { dryRun, overwrite, externalPrefixes })
     if (!dryRun) {
       console.log(`Created: ${result.created.length} feature.json files`)
       if (result.created.length > 0) console.log(`  ${result.created.join(', ')}`)
@@ -1057,6 +1085,9 @@ if (cmd === 'roadmap') {
       if (result.updated.length > 0) console.log(`  ${result.updated.join(', ')}`)
       console.log(`Skipped: ${result.skipped.length} (already exist, use --overwrite to replace)`)
       if (result.skipped.length > 0) console.log(`  ${result.skipped.join(', ')}`)
+      const ext = result.skippedExternal ?? []
+      console.log(`Skipped (external, cross-project refs): ${ext.length}`)
+      if (ext.length > 0) console.log(`  ${ext.join(', ')}`)
     }
     process.exit(0)
   }
@@ -1064,49 +1095,56 @@ if (cmd === 'roadmap') {
   // compose roadmap check — verify feature.json ↔ ROADMAP.md consistency
   if (subcmd === 'check') {
     const { listFeatures } = await import('../lib/feature-json.js')
-    const { parseRoadmap } = await import('../lib/roadmap-parser.js')
+    const { checkRoundtrip, describeLossyDiff } = await import('../lib/roadmap-roundtrip.js')
+    const { loadExternalPrefixes } = await import('../lib/project-paths.js')
     const { root: cwd } = resolveCwdWithWorkspace(args)
     const roadmapPath = join(cwd, 'ROADMAP.md')
     if (!existsSync(roadmapPath)) {
       console.error('No ROADMAP.md found. Run: compose roadmap generate')
       process.exit(1)
     }
-    const features = listFeatures(cwd)
-    const roadmapEntries = parseRoadmap(readFileSync(roadmapPath, 'utf-8'))
-    const roadmapCodes = new Set(roadmapEntries.filter(e => !e.code.startsWith('_anon_')).map(e => e.code))
-    const featureCodes = new Set(features.map(f => f.code))
-
-    let clean = true
-    // Features in feature.json but missing from ROADMAP.md
-    for (const f of features) {
-      if (!roadmapCodes.has(f.code)) {
-        console.log(`MISSING from ROADMAP.md: ${f.code}`)
-        clean = false
-      }
+    // Narrative-owned workspaces (#39): ROADMAP.md is hand-authored, not a render
+    // of feature.json — the roundtrip would always report false drift. The file
+    // must still EXIST (checked above); we only skip the drift comparison.
+    const { isNarrativeOwned } = await import('../lib/roadmap-config.js')
+    if (isNarrativeOwned(cwd)) {
+      console.log('narrative-owned workspace (roadmap.narrative=true) — ROADMAP.md is hand-authored; roundtrip check skipped.')
+      process.exit(0)
     }
-    // Features in ROADMAP.md but missing feature.json
-    for (const e of roadmapEntries) {
-      if (e.code.startsWith('_anon_')) continue
-      if (!featureCodes.has(e.code)) {
-        console.log(`NO feature.json: ${e.code}`)
-        clean = false
-      }
+    const externalPrefixes = loadExternalPrefixes(cwd)
+    const rt = checkRoundtrip(readFileSync(roadmapPath, 'utf-8'), listFeatures(cwd), { now: '0000-00-00', externalPrefixes })
+    if (rt.fixedPoint && rt.lossless) {
+      console.log('feature.json and ROADMAP.md are in sync (fixed point, lossless).')
+      process.exit(0)
     }
-    // Status mismatches
-    const roadmapMap = new Map(roadmapEntries.map(e => [e.code, e]))
-    for (const f of features) {
-      const rm = roadmapMap.get(f.code)
-      if (rm && rm.status !== f.status) {
-        console.log(`STATUS MISMATCH: ${f.code} — feature.json=${f.status}, ROADMAP.md=${rm.status}`)
-        clean = false
-      }
+    if (!rt.fixedPoint) {
+      const d = rt.diffs.find(x => x.kind === 'FIXED_POINT_DIVERGENCE')
+      console.log(`NOT A FIXED POINT: ${d?.detail ?? 'ROADMAP.md changes on regen'}`)
     }
+    for (const d of rt.diffs.filter(x => x.kind.startsWith('LOSSLESS_'))) {
+      console.log(describeLossyDiff(d))
+    }
+    console.log('\nRun `compose roadmap generate` to regenerate ROADMAP.md from feature.json.')
+    process.exit(1)
+  }
 
-    if (clean) {
-      console.log('feature.json and ROADMAP.md are in sync.')
+  // compose roadmap xref-sync — pull-reconcile feature.json external links'
+  // expect= to live target state (COMP-ROADMAP-XREF-SYNC v1). Never writes external.
+  if (subcmd === 'xref-sync') {
+    const { syncExternalRefs } = await import('../lib/xref-sync.js')
+    const { root: cwd } = resolveCwdWithWorkspace(args)
+    const dryRun = args.includes('--dry-run')
+    const res = await syncExternalRefs(cwd, { dryRun })
+    const verb = dryRun ? 'would update' : 'updated'
+    if (res.synced.length === 0) {
+      console.log(`No external-link drift to reconcile (${res.scanned} resolvable link(s) checked, ${res.unchanged} already in sync).`)
     } else {
-      console.log('\nRun `compose roadmap generate` to regenerate ROADMAP.md from feature.json.')
-      process.exit(1)
+      console.log(`${dryRun ? 'Would reconcile' : 'Reconciled'} ${res.synced.length} external link(s):`)
+      for (const s of res.synced) console.log(`  ${s.code}  ${s.provider} ${s.target}: expect ${s.from} → ${s.to} (${verb})`)
+    }
+    if (res.skipped.length > 0) {
+      console.log(`\nSkipped ${res.skipped.length} unresolved link(s):`)
+      for (const s of res.skipped) console.log(`  ${s.code}  ${s.provider} ${s.target}: ${s.reason}`)
     }
     process.exit(0)
   }
@@ -2692,6 +2730,112 @@ if (cmd === 'build') {
     process.exit(1)
   }
 
+} else if (cmd === 'items') {
+  // ---------------------------------------------------------------------------
+  // compose items — read vision-state.json directly (no server required)
+  // ---------------------------------------------------------------------------
+  const itemsSub = args[0] && !args[0].startsWith('-') ? args[0] : 'list'
+  const jsonFlag = args.includes('--json')
+
+  const { root: itemsCwd } = resolveCwdWithWorkspace(args)
+  const vsPath = join(itemsCwd, '.compose', 'data', 'vision-state.json')
+
+  if (!existsSync(vsPath)) {
+    console.error('No vision state found at .compose/data/vision-state.json')
+    console.error('Run `compose start` at least once to generate it, then you can use `compose items` offline.')
+    process.exit(1)
+  }
+
+  let visionState
+  try {
+    visionState = JSON.parse(readFileSync(vsPath, 'utf-8'))
+  } catch (err) {
+    console.error(`Failed to read vision state: ${err.message}`)
+    process.exit(1)
+  }
+
+  const allItems = visionState.items || []
+
+  if (itemsSub === 'list') {
+    if (jsonFlag) {
+      console.log(JSON.stringify(allItems, null, 2))
+      process.exit(0)
+    }
+
+    if (allItems.length === 0) {
+      console.log('No items found.')
+      process.exit(0)
+    }
+
+    // Table output: id (truncated), title, status, type
+    const header = { id: 'ID', title: 'TITLE', status: 'STATUS', type: 'TYPE' }
+    const rows = allItems.map(it => ({
+      id: (it.id || '').slice(0, 8),
+      title: (it.title || '(untitled)').slice(0, 50),
+      status: it.status || '-',
+      type: it.type || '-',
+    }))
+
+    // Compute column widths
+    const cols = ['id', 'title', 'status', 'type']
+    const widths = {}
+    for (const c of cols) {
+      widths[c] = Math.max(header[c].length, ...rows.map(r => r[c].length))
+    }
+
+    const pad = (s, w) => s + ' '.repeat(Math.max(0, w - s.length))
+    const line = cols.map(c => pad(header[c], widths[c])).join('  ')
+    console.log(line)
+    console.log(cols.map(c => '-'.repeat(widths[c])).join('  '))
+    for (const r of rows) {
+      console.log(cols.map(c => pad(r[c], widths[c])).join('  '))
+    }
+    process.exit(0)
+
+  } else if (itemsSub === 'show') {
+    const positionalArgs = args.filter(a => !a.startsWith('-'))
+    const showId = positionalArgs[1]
+    if (!showId) {
+      console.error('Usage: compose items show <id>')
+      process.exit(1)
+    }
+
+    const matches = allItems.filter(it => it.id === showId || it.id.startsWith(showId))
+    if (matches.length > 1) {
+      console.error(`Ambiguous ID prefix '${showId}' matches ${matches.length} items:`)
+      for (const m of matches) console.error(`  ${(m.id || '').slice(0, 8)}  ${m.title || '(untitled)'}`)
+      process.exit(1)
+    }
+    const match = matches[0]
+    if (!match) {
+      console.error(`No item found matching: ${showId}`)
+      process.exit(1)
+    }
+
+    if (jsonFlag) {
+      console.log(JSON.stringify(match, null, 2))
+    } else {
+      for (const [key, val] of Object.entries(match)) {
+        if (val == null) continue
+        if (typeof val === 'object') {
+          console.log(`${key}: ${JSON.stringify(val)}`)
+        } else {
+          console.log(`${key}: ${val}`)
+        }
+      }
+    }
+    process.exit(0)
+
+  } else {
+    console.error(`Unknown items subcommand: ${itemsSub}`)
+    console.error('Usage:')
+    console.error('  compose items              List all items')
+    console.error('  compose items list         List all items')
+    console.error('  compose items show <id>    Show detail for a specific item')
+    console.error('  --json                     Output as JSON')
+    process.exit(1)
+  }
+
 } else {
   console.error(`Unknown command: ${cmd}`)
   process.exit(1)