@edupia-tutor/spec-driven-docs 0.14.0

package/scripts/migrate-specs.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+
+/**
+ * migrate-specs.js — migrate a consumer project's specs from the LEGACY
+ * artifact-type-first layout to the FEATURE-PACKAGE layout.
+ *
+ *   OLD                                   NEW
+ *   specs/prd/{domain}/{slug}.md          specs/{domain}/{slug}/prd.md
+ *   specs/bdd/{domain}/{rest}             specs/{domain}/{prd-slug}/bdd/{rest}
+ *   specs/tech-docs/{domain}/{file}       specs/{domain}/{prd-slug}/tech-docs/{file}
+ *   specs/design-spec/{domain}/{file}     specs/{domain}/{prd-slug}/design-spec/{file}
+ *   .trace/{UC-ID}.tsv                    .trace/{domain}/{prd-slug}/{UC-ID}.tsv
+ *
+ * The {prd-slug} for a BDD / tech-doc / design-spec / trace file is resolved by
+ * reading its `@trace.source` header (the PRD it derives from) or its `@trace.uc`
+ * tag (mapped to a PRD via the .feature index). Files that cannot be resolved are
+ * LEFT IN PLACE and listed in the report — never moved to a guessed location.
+ *
+ * DRY-RUN by default (prints the plan, changes nothing). Pass --apply to execute.
+ * Tracked files are moved with `git mv` to preserve history; the rest with fs.rename.
+ * After moving, internal `@trace.source` / path references inside the moved files
+ * are rewritten to the new locations.
+ *
+ * Usage (from the consumer project root):
+ *   node scripts/migrate-specs.js                 # dry-run, prints plan
+ *   node scripts/migrate-specs.js --apply         # execute the migration
+ *   node scripts/migrate-specs.js --specs specs --trace .trace --root .
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ── args ────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+const has  = f => argv.includes(f);
+const flag = (f, d) => { const i = argv.indexOf(f); return i !== -1 ? argv[i + 1] : d; };
+
+const APPLY = has('--apply');
+const ROOT  = path.resolve(flag('--root', '.'));
+const SPECS = flag('--specs', 'specs');
+const TRACE = flag('--trace', '.trace');
+
+const specsAbs = path.join(ROOT, SPECS);
+const traceAbs = path.join(ROOT, TRACE);
+
+// ── git tracked set (for `git mv`) ────────────────────────────────────────────
+let tracked = null;
+try {
+  const out = execSync('git ls-files', { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  tracked = new Set(out.split('\n').filter(Boolean).map(p => p.replace(/\\/g, '/')));
+} catch { tracked = null; }
+
+const rel       = abs => path.relative(ROOT, abs).replace(/\\/g, '/');
+const isTracked = abs => !!(tracked && tracked.has(rel(abs)));
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+function walk(dir) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walk(p));
+    else out.push(p);
+  }
+  return out;
+}
+const head = (file, n = 4096) => { try { return fs.readFileSync(file, 'utf8').slice(0, n); } catch { return ''; } };
+
+const reSource = /@trace\.source\s*[=:]\s*([^\s)'"]+)/;
+const reUc     = /@trace\.(?:uc|id)\s*[=:]\s*([A-Za-z0-9_-]+)/;
+const reUcName = /\b([A-Za-z][A-Za-z0-9]*-UC\d+)\b/;       // e.g. PAY-UC1, FT-UC3
+// extract {domain}/{slug} from a legacy PRD ref like specs/prd/payment/create-invoice.md
+const slugFromPrdRef = ref => { const m = ref && ref.match(/prd\/([^/]+)\/([^/]+)\.md/); return m ? { domain: m[1], slug: m[2] } : null; };
+
+// ── plan state ─────────────────────────────────────────────────────────────────
+const moves      = [];   // { from(abs), to(abs), type }
+const unresolved = [];   // { file(rel), type, reason }
+const prdByDomain = {};  // domain -> Set(slug)
+const ucToSlug    = {};  // `${domain}/${UC}` -> slug
+const ticketToSlug = {}; // `${domain}/${TICKET}` -> slug (from PRD metadata)
+
+const addSlug = (domain, slug) => { (prdByDomain[domain] = prdByDomain[domain] || new Set()).add(slug); };
+const onlySlug = domain => { const s = prdByDomain[domain]; return s && s.size === 1 ? [...s][0] : null; };
+
+// ── Phase 1 — PRDs: specs/prd/{domain}/{slug}.md → specs/{domain}/{slug}/prd.md ──
+const prdRoot = path.join(specsAbs, 'prd');
+for (const file of walk(prdRoot).filter(f => f.endsWith('.md'))) {
+  const parts = rel(file).split('/');                  // [SPECS, 'prd', domain, ...rest, name.md]
+  const after = parts.slice(parts.indexOf('prd') + 1); // [domain, ...rest, name.md]
+  if (after.length !== 2) { unresolved.push({ file: rel(file), type: 'prd', reason: `expected specs/prd/{domain}/{slug}.md (got depth ${after.length})` }); continue; }
+  const [domain, name] = after;
+  const slug = name.replace(/\.md$/, '');
+  addSlug(domain, slug);
+  // map this PRD's Ticket + UC ids → slug (fallback resolution for other artifacts)
+  const body = head(file, 16384);
+  const ticket = (body.match(/\|\s*\*\*(?:PRD ID|Ticket)\*\*\s*\|\s*([A-Za-z0-9_-]+)/) || [])[1];
+  if (ticket) ticketToSlug[`${domain}/${ticket}`] = slug;
+  let m; const reUcG = new RegExp(reUcName.source, 'g');
+  while ((m = reUcG.exec(body))) ucToSlug[`${domain}/${m[1]}`] = ucToSlug[`${domain}/${m[1]}`] || slug;
+  moves.push({ from: file, to: path.join(specsAbs, domain, slug, 'prd.md'), type: 'prd' });
+}
+
+// ── Phase 2 — BDD: specs/bdd/{domain}/{rest} → specs/{domain}/{prd-slug}/bdd/{rest}
+const bddRoot = path.join(specsAbs, 'bdd');
+for (const file of walk(bddRoot).filter(f => f.endsWith('.feature'))) {
+  const after  = rel(file).split('/').slice(rel(file).split('/').indexOf('bdd') + 1); // [domain, ...rest]
+  const domain = after[0];
+  const rest   = after.slice(1).join('/');             // e.g. system/PAY-UC1.feature OR PAY-UC1.feature
+  const h = head(file);
+  let resolved = slugFromPrdRef((h.match(reSource) || [])[1]);
+  const uc = (h.match(reUc) || [])[1] || (path.basename(file).match(reUcName) || [])[1];
+  let slug = resolved && resolved.domain === domain ? resolved.slug : null;
+  if (!slug && uc) slug = ucToSlug[`${domain}/${uc}`];
+  if (!slug) slug = onlySlug(domain);
+  if (!slug) { unresolved.push({ file: rel(file), type: 'bdd', reason: 'cannot resolve prd-slug (no @trace.source / @trace.uc match, and domain has multiple PRDs)' }); continue; }
+  if (uc) ucToSlug[`${domain}/${uc}`] = ucToSlug[`${domain}/${uc}`] || slug;
+  moves.push({ from: file, to: path.join(specsAbs, domain, slug, 'bdd', ...rest.split('/')), type: 'bdd' });
+}
+
+// ── Phase 3 — tech-docs → specs/{domain}/{prd-slug}/tech-docs/{file} ────────────
+const techRoot = path.join(specsAbs, 'tech-docs');
+for (const file of walk(techRoot).filter(f => f.endsWith('.md'))) {
+  const after  = rel(file).split('/').slice(rel(file).split('/').indexOf('tech-docs') + 1);
+  const domain = after[0];
+  const rest   = after.slice(1).join('/');
+  const h = head(file);
+  const src = (h.match(reSource) || [])[1];
+  let slug = (slugFromPrdRef(src) || {}).slug;          // when @trace.source points at the PRD
+  const uc = (h.match(reUc) || [])[1] || (path.basename(file).match(reUcName) || [])[1];
+  if (!slug && uc)  slug = ucToSlug[`${domain}/${uc}`];
+  if (!slug && src) { const m = src.match(/bdd\/(?:.*\/)?([A-Za-z][A-Za-z0-9]*-UC\d+)/); if (m) slug = ucToSlug[`${domain}/${m[1]}`]; }
+  if (!slug) slug = onlySlug(domain);
+  if (!slug) { unresolved.push({ file: rel(file), type: 'tech-docs', reason: 'cannot resolve prd-slug from @trace.source / UC-ID' }); continue; }
+  moves.push({ from: file, to: path.join(specsAbs, domain, slug, 'tech-docs', ...rest.split('/')), type: 'tech-docs' });
+}
+
+// ── Phase 4 — design-spec → specs/{domain}/{prd-slug}/design-spec/{file} ────────
+const dsRoot = path.join(specsAbs, 'design-spec');
+for (const file of walk(dsRoot).filter(f => f.endsWith('.md'))) {
+  const after  = rel(file).split('/').slice(rel(file).split('/').indexOf('design-spec') + 1);
+  const domain = after[0];
+  const rest   = after.slice(1).join('/');
+  const h = head(file);
+  let slug = (slugFromPrdRef((h.match(reSource) || [])[1]) || {}).slug;
+  const ticket = (path.basename(file).match(/^([A-Za-z][A-Za-z0-9]*-\d+|[A-Za-z]+-UC\d+)/) || [])[1];
+  if (!slug && ticket) slug = ticketToSlug[`${domain}/${ticket}`] || ucToSlug[`${domain}/${ticket}`];
+  if (!slug) slug = onlySlug(domain);
+  if (!slug) { unresolved.push({ file: rel(file), type: 'design-spec', reason: 'cannot resolve prd-slug (no @trace.source / ticket match)' }); continue; }
+  moves.push({ from: file, to: path.join(specsAbs, domain, slug, 'design-spec', ...rest.split('/')), type: 'design-spec' });
+}
+
+// ── Phase 5 — trace: flat .trace/{UC-ID}.tsv → .trace/{domain}/{prd-slug}/{UC}.tsv
+if (fs.existsSync(traceAbs)) {
+  for (const file of fs.readdirSync(traceAbs).filter(f => f.endsWith('.tsv'))) {
+    const uc = file.replace(/\.tsv$/, '');
+    const keys = Object.keys(ucToSlug).filter(k => k.endsWith(`/${uc}`));
+    if (keys.length === 0) { unresolved.push({ file: `${TRACE}/${file}`, type: 'trace', reason: `no PRD/feature maps UC ${uc}` }); continue; }
+    if (keys.length > 1)   { unresolved.push({ file: `${TRACE}/${file}`, type: 'trace', reason: `UC ${uc} is ambiguous across domains: ${keys.join(', ')}` }); continue; }
+    const [domain] = keys[0].split('/');
+    const slug = ucToSlug[keys[0]];
+    moves.push({ from: path.join(traceAbs, file), to: path.join(traceAbs, domain, slug, file), type: 'trace' });
+  }
+}
+
+// ── build old→new ref map (repo-root-relative, forward slashes) ────────────────
+const refMap = new Map();
+for (const m of moves) refMap.set(rel(m.from), rel(m.to));
+
+// ── report ──────────────────────────────────────────────────────────────────────
+const byType = moves.reduce((a, m) => ((a[m.type] = (a[m.type] || 0) + 1), a), {});
+console.log('');
+console.log('╔════════════════════════════════════════════╗');
+console.log(`║  migrate-specs  —  ${APPLY ? 'APPLY' : 'DRY RUN'}${' '.repeat(APPLY ? 20 : 18)}║`);
+console.log('╚════════════════════════════════════════════╝');
+console.log(`Root  : ${ROOT}`);
+console.log(`Specs : ${SPECS}/   Trace: ${TRACE}/   Git: ${tracked ? 'yes (git mv)' : 'no (fs move)'}`);
+console.log('');
+if (moves.length === 0 && unresolved.length === 0) {
+  console.log('Nothing to migrate — no legacy specs/prd, specs/bdd, specs/tech-docs, specs/design-spec, or flat .trace/*.tsv found.');
+  process.exit(0);
+}
+console.log(`Planned moves: ${moves.length}  (${Object.entries(byType).map(([k, v]) => `${k}:${v}`).join('  ')})`);
+console.log('');
+for (const m of moves) console.log(`  ${rel(m.from)}\n    → ${rel(m.to)}`);
+if (unresolved.length) {
+  console.log('');
+  console.log(`⚠️  Unresolved (LEFT IN PLACE — fix the file's @trace.source/@trace.uc or move manually):`);
+  for (const u of unresolved) console.log(`  [${u.type}] ${u.file}\n      ${u.reason}`);
+}
+console.log('');
+
+// ── apply ────────────────────────────────────────────────────────────────────────
+function gitMv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  execSync(`git mv -k "${rel(from)}" "${rel(to)}"`, { cwd: ROOT, stdio: ['ignore', 'ignore', 'pipe'] });
+}
+function fsMv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.renameSync(from, to);
+}
+function rewriteRefs(absFile) {
+  if (!/\.(md|feature|tsv|ya?ml)$/.test(absFile)) return 0;
+  let txt; try { txt = fs.readFileSync(absFile, 'utf8'); } catch { return 0; }
+  let n = 0, out = txt;
+  for (const [oldRef, newRef] of refMap) {
+    if (out.includes(oldRef)) { out = out.split(oldRef).join(newRef); n++; }
+  }
+  if (n) fs.writeFileSync(absFile, out, 'utf8');
+  return n;
+}
+function pruneEmptyDirs(root) {
+  if (!fs.existsSync(root)) return;
+  for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+    if (e.isDirectory()) pruneEmptyDirs(path.join(root, e.name));
+  }
+  try { if (fs.readdirSync(root).length === 0) fs.rmdirSync(root); } catch {}
+}
+
+if (!APPLY) {
+  console.log('DRY RUN — nothing changed. Re-run with --apply to execute.');
+  console.log('After applying, grep your CODE for stale spec refs the move did not touch:');
+  console.log('  @trace.source=specs/bdd/...   and   specs/{prd,bdd,tech-docs,design-spec}/');
+  process.exit(0);
+}
+
+let moved = 0, failed = 0;
+for (const m of moves) {
+  try {
+    if (fs.existsSync(m.to)) throw new Error('target already exists');
+    (isTracked(m.from) ? gitMv : fsMv)(m.from, m.to);
+    moved++;
+  } catch (e) {
+    failed++;
+    console.log(`  ❌ ${rel(m.from)} — ${e.message}`);
+  }
+}
+// rewrite internal references in every moved file (now at its new path)
+let rewritten = 0;
+for (const m of moves) if (fs.existsSync(m.to)) rewritten += rewriteRefs(m.to) > 0 ? 1 : 0;
+
+// remove now-empty legacy roots
+[prdRoot, bddRoot, techRoot, dsRoot].forEach(pruneEmptyDirs);
+
+console.log('');
+console.log(`✅ Moved ${moved}/${moves.length} files${failed ? ` (${failed} failed)` : ''}.`);
+console.log(`✅ Rewrote internal references in ${rewritten} file(s).`);
+if (unresolved.length) console.log(`⚠️  ${unresolved.length} file(s) left in place (see list above).`);
+console.log('');
+console.log('Next:');
+console.log('  1. Review the moves (git status / git diff).');
+console.log('  2. Grep CODE for stale refs the move did not touch:');
+console.log('       @trace.source=specs/bdd/...   and   specs/{prd,bdd,tech-docs,design-spec}/');
+console.log('  3. Run /validate-traces to confirm coverage still resolves.');
+console.log('  4. Commit.');
+console.log('');

package/scripts/upgrade.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# upgrade.sh — Upgrade Spec-Driven Docs framework in an existing project.
+#
+# Usage:
+#   bash scripts/upgrade.sh
+#   bash scripts/upgrade.sh --module java-spring   # also upgrade a stack module
+#
+# What it does:
+#   1. Reads current installed version from .agent/FRAMEWORK_VERSION
+#   2. Checks npm registry for the latest published version
+#   3. If newer: runs npx @edupia-tutor/spec-driven-docs@latest --init to update .agent/
+#   4. Reports what changed so you can review before committing
+#
+# Requirements:
+#   - Project was set up with init.sh (or npx ... --init)
+#   - .agent/FRAMEWORK_VERSION exists
+
+set -euo pipefail
+
+AGENT_DIR=".agent"
+VERSION_FILE="${AGENT_DIR}/FRAMEWORK_VERSION"
+
+echo ""
+echo "╔══════════════════════════════════════════╗"
+echo "║   Spec-Driven Docs — Upgrade              ║"
+echo "╚══════════════════════════════════════════╝"
+echo ""
+
+# ── Prerequisite checks ───────────────────────────────────────────────────────
+
+if ! command -v node &> /dev/null; then
+  echo "❌ Node.js is required. Install from https://nodejs.org"
+  exit 1
+fi
+
+if ! command -v npm &> /dev/null; then
+  echo "❌ npm is required. Install Node.js from https://nodejs.org"
+  exit 1
+fi
+
+if [ ! -f "$VERSION_FILE" ]; then
+  echo "❌ .agent/FRAMEWORK_VERSION not found."
+  echo ""
+  echo "   This project was not set up with --init."
+  echo "   To set up the new structure:"
+  echo ""
+  echo "     bash scripts/init.sh"
+  echo "   or:"
+  echo "     npx @edupia-tutor/spec-driven-docs --init"
+  echo ""
+  exit 1
+fi
+
+# ── Version comparison ────────────────────────────────────────────────────────
+
+CURRENT=$(cat "$VERSION_FILE" | tr -d '[:space:]')
+echo "Checking npm registry ..."
+
+LATEST=$(npm view @edupia-tutor/spec-driven-docs version 2>/dev/null || echo "unknown")
+
+echo ""
+echo "  Installed : v${CURRENT}"
+echo "  Latest    : v${LATEST}"
+echo ""
+
+if [ "$LATEST" = "unknown" ]; then
+  echo "⚠️  Could not reach npm registry. Check your internet connection."
+  exit 1
+fi
+
+if [ "$CURRENT" = "$LATEST" ]; then
+  echo "✅ Already up to date (v${CURRENT}). Nothing to do."
+  echo ""
+  exit 0
+fi
+
+# ── Upgrade ───────────────────────────────────────────────────────────────────
+
+echo "Upgrading v${CURRENT} → v${LATEST} ..."
+echo ""
+
+npx -y @edupia-tutor/spec-driven-docs@latest --init "$@"
+
+# ── Post-upgrade guidance ─────────────────────────────────────────────────────
+
+echo ""
+echo "✅ Upgraded to v${LATEST}!"
+echo ""
+echo "Review what changed in .agent/ before committing:"
+echo ""
+echo "  git diff .agent/"
+echo "  git add .agent/"
+echo "  git commit -m 'chore: upgrade spec-driven-docs v${CURRENT} → v${LATEST}'"
+echo ""