@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdd/bin/lib/workstream-inventory.cjs

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * Workstream Inventory Module
+ *
+ * Owns discovery and read-only projection of .planning/workstreams/* state.
+ * Command handlers should render outputs from this inventory instead of
+ * rescanning workstream directories directly.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { toPosixPath, readSubdirectories } = require('./core.cjs');
+const scanPhasePlans = require('./plan-scan.cjs');
+const { planningPaths, planningRoot, getActiveWorkstream } = require('./planning-workspace.cjs');
+const { stateExtractField } = require('./state-document.cjs');
+
+function workstreamsRoot(cwd) {
+  return path.join(planningRoot(cwd), 'workstreams');
+}
+
+function countRoadmapPhases(roadmapPath, fallbackCount) {
+  try {
+    const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+    const matches = roadmapContent.match(/^#{2,4}\s+Phase\s+[\w][\w.-]*/gm);
+    return matches ? matches.length : fallbackCount;
+  } catch {
+    return fallbackCount;
+  }
+}
+
+function countPhaseFiles(phaseDir) {
+  const scan = scanPhasePlans(phaseDir);
+  return { planCount: scan.planCount, summaryCount: scan.summaryCount };
+}
+
+function readStateProjection(statePath) {
+  try {
+    const stateContent = fs.readFileSync(statePath, 'utf-8');
+    return {
+      status: stateExtractField(stateContent, 'Status') || 'unknown',
+      current_phase: stateExtractField(stateContent, 'Current Phase'),
+      last_activity: stateExtractField(stateContent, 'Last Activity'),
+    };
+  } catch {
+    return {
+      status: 'unknown',
+      current_phase: null,
+      last_activity: null,
+    };
+  }
+}
+
+function inspectWorkstream(cwd, name, options = {}) {
+  const wsDir = path.join(workstreamsRoot(cwd), name);
+  if (!fs.existsSync(wsDir)) return null;
+
+  const active = options.active === undefined ? getActiveWorkstream(cwd) : options.active;
+  const p = planningPaths(cwd, name);
+  const phaseDirs = readSubdirectories(p.phases);
+  const phases = [];
+  let completedPhases = 0;
+  let totalPlans = 0;
+  let completedPlans = 0;
+
+  for (const dir of phaseDirs.sort()) {
+    const counts = countPhaseFiles(path.join(p.phases, dir));
+    const status = counts.summaryCount >= counts.planCount && counts.planCount > 0
+      ? 'complete'
+      : counts.planCount > 0
+        ? 'in_progress'
+        : 'pending';
+
+    totalPlans += counts.planCount;
+    completedPlans += Math.min(counts.summaryCount, counts.planCount);
+    if (status === 'complete') completedPhases++;
+
+    phases.push({
+      directory: dir,
+      status,
+      plan_count: counts.planCount,
+      summary_count: counts.summaryCount,
+    });
+  }
+
+  const roadmapPhaseCount = countRoadmapPhases(p.roadmap, phaseDirs.length);
+  const state = readStateProjection(p.state);
+
+  return {
+    name,
+    path: toPosixPath(path.relative(cwd, wsDir)),
+    active: name === active,
+    files: {
+      roadmap: fs.existsSync(p.roadmap),
+      state: fs.existsSync(p.state),
+      requirements: fs.existsSync(p.requirements),
+    },
+    status: state.status,
+    current_phase: state.current_phase,
+    last_activity: state.last_activity,
+    phases,
+    phase_count: phases.length,
+    completed_phases: completedPhases,
+    roadmap_phase_count: roadmapPhaseCount,
+    total_plans: totalPlans,
+    completed_plans: completedPlans,
+    progress_percent: roadmapPhaseCount > 0 ? Math.min(100, Math.round((completedPhases / roadmapPhaseCount) * 100)) : 0,
+  };
+}
+
+function listWorkstreamInventories(cwd) {
+  const wsRoot = workstreamsRoot(cwd);
+  if (!fs.existsSync(wsRoot)) {
+    return {
+      mode: 'flat',
+      active: null,
+      workstreams: [],
+      count: 0,
+      message: 'No workstreams — operating in flat mode',
+    };
+  }
+
+  const active = getActiveWorkstream(cwd);
+  const entries = fs.readdirSync(wsRoot, { withFileTypes: true });
+  const workstreams = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const inventory = inspectWorkstream(cwd, entry.name, { active });
+    if (inventory) workstreams.push(inventory);
+  }
+
+  return {
+    mode: 'workstream',
+    active,
+    workstreams,
+    count: workstreams.length,
+  };
+}
+
+function isCompletedInventory(inventory) {
+  const status = String(inventory && inventory.status ? inventory.status : '').toLowerCase();
+  return status.includes('milestone complete') || status.includes('archived');
+}
+
+function getOtherActiveWorkstreamInventories(cwd, excludeWs) {
+  return listWorkstreamInventories(cwd).workstreams
+    .filter(inventory => inventory.name !== excludeWs)
+    .filter(inventory => !isCompletedInventory(inventory));
+}
+
+module.exports = {
+  countPhaseFiles,
+  countRoadmapPhases,
+  getOtherActiveWorkstreamInventories,
+  inspectWorkstream,
+  isCompletedInventory,
+  listWorkstreamInventories,
+  workstreamsRoot,
+};

package/sdd/bin/lib/workstream-name-policy.cjs

@@ -0,0 +1,33 @@
+/**
+ * Workstream Name Policy Module
+ *
+ * Owns canonical name validation and slug normalization used by workstream and
+ * active-pointer callers.
+ */
+
+const ACTIVE_WORKSTREAM_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+function toWorkstreamSlug(name) {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function hasInvalidPathSegment(name) {
+  const value = String(name || '');
+  return /[/\\]/.test(value) || value === '.' || value === '..' || value.includes('..');
+}
+
+function isValidActiveWorkstreamName(name) {
+  const value = String(name || '');
+  if (value === '..' || value.startsWith('../') || value.includes('..')) return false;
+  return ACTIVE_WORKSTREAM_RE.test(value);
+}
+
+module.exports = {
+  toWorkstreamSlug,
+  hasInvalidPathSegment,
+  isValidActiveWorkstreamName,
+};
+

package/sdd/bin/lib/workstream.cjs

@@ -10,8 +10,15 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error, planningPaths, planningRoot, toPosixPath, getMilestoneInfo, generateSlugInternal, setActiveWorkstream, getActiveWorkstream, filterPlanFiles, filterSummaryFiles, readSubdirectories } = require('./core.cjs');
-const { stateExtractField } = require('./state.cjs');
+const { output, error, toPosixPath, getMilestoneInfo, generateSlugInternal } = require('./core.cjs');
+const { platformWriteSync, platformEnsureDir } = require('./shell-command-projection.cjs');
+const { planningRoot, setActiveWorkstream, getActiveWorkstream } = require('./planning-workspace.cjs');
+const { toWorkstreamSlug, hasInvalidPathSegment, isValidActiveWorkstreamName } = require('./workstream-name-policy.cjs');
+const {
+  getOtherActiveWorkstreamInventories,
+  inspectWorkstream,
+  listWorkstreamInventories,
+} = require('./workstream-inventory.cjs');
 
 // ─── Migration ──────────────────────────────────────────────────────────────
 
@@ -22,7 +29,7 @@ const { stateExtractField } = require('./state.cjs');
  * milestones/, research/, codebase/, todos/) stay in place.
  */
 function migrateToWorkstreams(cwd, workstreamName) {
-  if (!workstreamName || /[/\\]/.test(workstreamName) || workstreamName === '.' || workstreamName === '..') {
+  if (!workstreamName || hasInvalidPathSegment(workstreamName)) {
     throw new Error('Invalid workstream name for migration');
   }
 
@@ -40,7 +47,7 @@ function migrateToWorkstreams(cwd, workstreamName) {
     { name: 'phases', type: 'dir' },
   ];
 
-  fs.mkdirSync(wsDir, { recursive: true });
+  platformEnsureDir(wsDir);
 
   const filesMoved = [];
   try {
@@ -71,14 +78,14 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
     error('workstream name required. Usage: workstream create <name>');
   }
 
-  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const slug = toWorkstreamSlug(name);
   if (!slug) {
     error('Invalid workstream name — must contain at least one alphanumeric character');
   }
 
   const baseDir = planningRoot(cwd);
   if (!fs.existsSync(baseDir)) {
-    error('.planning/ directory not found — run /sdd-new-project first');
+    error('.planning/ directory not found — run /sdd:new-project first');
   }
 
   const wsRoot = path.join(baseDir, 'workstreams');
@@ -100,7 +107,15 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
       const migrateName = options.migrateName || null;
       let existingWsName;
       if (migrateName) {
-        existingWsName = migrateName;
+        existingWsName = toWorkstreamSlug(migrateName);
+        if (!existingWsName) {
+          output({
+            created: false,
+            error: 'migration_failed',
+            message: 'Invalid migrate-name — must contain at least one alphanumeric character',
+          }, raw);
+          return;
+        }
       } else {
         try {
           const milestone = getMilestoneInfo(cwd);
@@ -117,12 +132,12 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
         return;
       }
     } else {
-      fs.mkdirSync(wsRoot, { recursive: true });
+      platformEnsureDir(wsRoot);
     }
   }
 
-  fs.mkdirSync(wsDir, { recursive: true });
-  fs.mkdirSync(path.join(wsDir, 'phases'), { recursive: true });
+  platformEnsureDir(wsDir);
+  platformEnsureDir(path.join(wsDir, 'phases'));
 
   const today = new Date().toISOString().split('T')[0];
   const stateContent = [
@@ -151,7 +166,7 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
 
   const statePath = path.join(wsDir, 'STATE.md');
   if (!fs.existsSync(statePath)) {
-    fs.writeFileSync(statePath, stateContent, 'utf-8');
+    platformWriteSync(statePath, stateContent);
   }
 
   setActiveWorkstream(cwd, slug);
@@ -169,59 +184,29 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
 }
 
 function cmdWorkstreamList(cwd, raw) {
-  const wsRoot = path.join(planningRoot(cwd), 'workstreams');
-
-  if (!fs.existsSync(wsRoot)) {
-    output({ mode: 'flat', workstreams: [], message: 'No workstreams — operating in flat mode' }, raw);
+  const inventory = listWorkstreamInventories(cwd);
+  if (inventory.mode === 'flat') {
+    output({ mode: 'flat', workstreams: [], message: inventory.message }, raw);
     return;
   }
 
-  const entries = fs.readdirSync(wsRoot, { withFileTypes: true });
-  const workstreams = [];
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-
-    const wsDir = path.join(wsRoot, entry.name);
-    const phasesDir = path.join(wsDir, 'phases');
-
-    const phaseDirs = readSubdirectories(phasesDir);
-    const phaseCount = phaseDirs.length;
-    let completedCount = 0;
-    for (const d of phaseDirs) {
-      try {
-        const phaseFiles = fs.readdirSync(path.join(phasesDir, d));
-        const plans = filterPlanFiles(phaseFiles);
-        const summaries = filterSummaryFiles(phaseFiles);
-        if (plans.length > 0 && summaries.length >= plans.length) completedCount++;
-      } catch {}
-    }
-
-    let status = 'unknown', currentPhase = null;
-    try {
-      const stateContent = fs.readFileSync(path.join(wsDir, 'STATE.md'), 'utf-8');
-      status = stateExtractField(stateContent, 'Status') || 'unknown';
-      currentPhase = stateExtractField(stateContent, 'Current Phase');
-    } catch {}
-
-    workstreams.push({
-      name: entry.name,
-      path: toPosixPath(path.relative(cwd, wsDir)),
-      has_roadmap: fs.existsSync(path.join(wsDir, 'ROADMAP.md')),
-      has_state: fs.existsSync(path.join(wsDir, 'STATE.md')),
-      status,
-      current_phase: currentPhase,
-      phase_count: phaseCount,
-      completed_phases: completedCount,
-    });
-  }
+  const workstreams = inventory.workstreams.map(ws => ({
+    name: ws.name,
+    path: ws.path,
+    has_roadmap: ws.files.roadmap,
+    has_state: ws.files.state,
+    status: ws.status,
+    current_phase: ws.current_phase,
+    phase_count: ws.phase_count,
+    completed_phases: ws.completed_phases,
+  }));
 
   output({ mode: 'workstream', workstreams, count: workstreams.length }, raw);
 }
 
 function cmdWorkstreamStatus(cwd, name, raw) {
   if (!name) error('workstream name required. Usage: workstream status <name>');
-  if (/[/\\]/.test(name) || name === '.' || name === '..') error('Invalid workstream name');
+  if (hasInvalidPathSegment(name)) error('Invalid workstream name');
 
   const wsDir = path.join(planningRoot(cwd), 'workstreams', name);
   if (!fs.existsSync(wsDir)) {
@@ -229,56 +214,25 @@ function cmdWorkstreamStatus(cwd, name, raw) {
     return;
   }
 
-  const p = planningPaths(cwd, name);
-  const relPath = toPosixPath(path.relative(cwd, wsDir));
-
-  const files = {
-    roadmap: fs.existsSync(p.roadmap),
-    state: fs.existsSync(p.state),
-    requirements: fs.existsSync(p.requirements),
-  };
-
-  const phases = [];
-  for (const dir of readSubdirectories(p.phases).sort()) {
-    try {
-      const phaseFiles = fs.readdirSync(path.join(p.phases, dir));
-      const plans = filterPlanFiles(phaseFiles);
-      const summaries = filterSummaryFiles(phaseFiles);
-      phases.push({
-        directory: dir,
-        status: summaries.length >= plans.length && plans.length > 0 ? 'complete' :
-                plans.length > 0 ? 'in_progress' : 'pending',
-        plan_count: plans.length,
-        summary_count: summaries.length,
-      });
-    } catch {}
-  }
-
-  let stateInfo = {};
-  try {
-    const stateContent = fs.readFileSync(p.state, 'utf-8');
-    stateInfo = {
-      status: stateExtractField(stateContent, 'Status') || 'unknown',
-      current_phase: stateExtractField(stateContent, 'Current Phase'),
-      last_activity: stateExtractField(stateContent, 'Last Activity'),
-    };
-  } catch {}
+  const inventory = inspectWorkstream(cwd, name);
 
   output({
     found: true,
     workstream: name,
-    path: relPath,
-    files,
-    phases,
-    phase_count: phases.length,
-    completed_phases: phases.filter(ph => ph.status === 'complete').length,
-    ...stateInfo,
+    path: inventory.path,
+    files: inventory.files,
+    phases: inventory.phases,
+    phase_count: inventory.phase_count,
+    completed_phases: inventory.completed_phases,
+    status: inventory.status,
+    current_phase: inventory.current_phase,
+    last_activity: inventory.last_activity,
   }, raw);
 }
 
 function cmdWorkstreamComplete(cwd, name, options, raw) {
   if (!name) error('workstream name required. Usage: workstream complete <name>');
-  if (/[/\\]/.test(name) || name === '.' || name === '..') error('Invalid workstream name');
+  if (hasInvalidPathSegment(name)) error('Invalid workstream name');
 
   const root = planningRoot(cwd);
   const wsRoot = path.join(root, 'workstreams');
@@ -300,7 +254,7 @@ function cmdWorkstreamComplete(cwd, name, options, raw) {
     archivePath = path.join(archiveDir, `ws-${name}-${today}-${suffix++}`);
   }
 
-  fs.mkdirSync(archivePath, { recursive: true });
+  platformEnsureDir(archivePath);
 
   const filesMoved = [];
   try {
@@ -349,8 +303,8 @@ function cmdWorkstreamSet(cwd, name, raw) {
     return;
   }
 
-  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
-    output({ active: null, error: 'invalid_name', message: 'Workstream name must be alphanumeric, hyphens, and underscores only' }, raw);
+  if (!isValidActiveWorkstreamName(name)) {
+    output({ active: null, error: 'invalid_name', message: 'Workstream name must be alphanumeric, hyphens, underscores, or dots' }, raw);
     return;
   }
 
@@ -371,64 +325,23 @@ function cmdWorkstreamGet(cwd, raw) {
 }
 
 function cmdWorkstreamProgress(cwd, raw) {
-  const root = planningRoot(cwd);
-  const wsRoot = path.join(root, 'workstreams');
-
-  if (!fs.existsSync(wsRoot)) {
-    output({ mode: 'flat', workstreams: [], message: 'No workstreams — operating in flat mode' }, raw);
+  const inventory = listWorkstreamInventories(cwd);
+  if (inventory.mode === 'flat') {
+    output({ mode: 'flat', workstreams: [], message: inventory.message }, raw);
     return;
   }
 
-  const active = getActiveWorkstream(cwd);
-  const entries = fs.readdirSync(wsRoot, { withFileTypes: true });
-  const workstreams = [];
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-
-    const wsDir = path.join(wsRoot, entry.name);
-    const phasesDir = path.join(wsDir, 'phases');
-
-    const phaseDirsProgress = readSubdirectories(phasesDir);
-    const phaseCount = phaseDirsProgress.length;
-    let completedCount = 0, totalPlans = 0, completedPlans = 0;
-    for (const d of phaseDirsProgress) {
-      try {
-        const phaseFiles = fs.readdirSync(path.join(phasesDir, d));
-        const plans = filterPlanFiles(phaseFiles);
-        const summaries = filterSummaryFiles(phaseFiles);
-        totalPlans += plans.length;
-        completedPlans += Math.min(summaries.length, plans.length);
-        if (plans.length > 0 && summaries.length >= plans.length) completedCount++;
-      } catch {}
-    }
-
-    let roadmapPhaseCount = phaseCount;
-    try {
-      const roadmapContent = fs.readFileSync(path.join(wsDir, 'ROADMAP.md'), 'utf-8');
-      const phaseMatches = roadmapContent.match(/^###?\s+Phase\s+\d/gm);
-      if (phaseMatches) roadmapPhaseCount = phaseMatches.length;
-    } catch {}
-
-    let status = 'unknown', currentPhase = null;
-    try {
-      const stateContent = fs.readFileSync(path.join(wsDir, 'STATE.md'), 'utf-8');
-      status = stateExtractField(stateContent, 'Status') || 'unknown';
-      currentPhase = stateExtractField(stateContent, 'Current Phase');
-    } catch {}
-
-    workstreams.push({
-      name: entry.name,
-      active: entry.name === active,
-      status,
-      current_phase: currentPhase,
-      phases: `${completedCount}/${roadmapPhaseCount}`,
-      plans: `${completedPlans}/${totalPlans}`,
-      progress_percent: roadmapPhaseCount > 0 ? Math.round((completedCount / roadmapPhaseCount) * 100) : 0,
-    });
-  }
-
-  output({ mode: 'workstream', active, workstreams, count: workstreams.length }, raw);
+  const workstreams = inventory.workstreams.map(ws => ({
+    name: ws.name,
+    active: ws.active,
+    status: ws.status,
+    current_phase: ws.current_phase,
+    phases: `${ws.completed_phases}/${ws.roadmap_phase_count}`,
+    plans: `${ws.completed_plans}/${ws.total_plans}`,
+    progress_percent: ws.progress_percent,
+  }));
+
+  output({ mode: 'workstream', active: inventory.active, workstreams, count: workstreams.length }, raw);
 }
 
 // ─── Collision Detection ────────────────────────────────────────────────────
@@ -439,47 +352,12 @@ function cmdWorkstreamProgress(cwd, raw) {
  * when a workstream finishes its last phase.
  */
 function getOtherActiveWorkstreams(cwd, excludeWs) {
-  const wsRoot = path.join(planningRoot(cwd), 'workstreams');
-  if (!fs.existsSync(wsRoot)) return [];
-
-  const entries = fs.readdirSync(wsRoot, { withFileTypes: true });
-  const others = [];
-
-  for (const entry of entries) {
-    if (!entry.isDirectory() || entry.name === excludeWs) continue;
-
-    const wsDir = path.join(wsRoot, entry.name);
-    const statePath = path.join(wsDir, 'STATE.md');
-
-    let status = 'unknown', currentPhase = null;
-    try {
-      const content = fs.readFileSync(statePath, 'utf-8');
-      status = stateExtractField(content, 'Status') || 'unknown';
-      currentPhase = stateExtractField(content, 'Current Phase');
-    } catch {}
-
-    if (status.toLowerCase().includes('milestone complete') ||
-        status.toLowerCase().includes('archived')) {
-      continue;
-    }
-
-    const phasesDir = path.join(wsDir, 'phases');
-    const phaseDirsOther = readSubdirectories(phasesDir);
-    const phaseCount = phaseDirsOther.length;
-    let completedCount = 0;
-    for (const d of phaseDirsOther) {
-      try {
-        const phaseFiles = fs.readdirSync(path.join(phasesDir, d));
-        const plans = filterPlanFiles(phaseFiles);
-        const summaries = filterSummaryFiles(phaseFiles);
-        if (plans.length > 0 && summaries.length >= plans.length) completedCount++;
-      } catch {}
-    }
-
-    others.push({ name: entry.name, status, current_phase: currentPhase, phases: `${completedCount}/${phaseCount}` });
-  }
-
-  return others;
+  return getOtherActiveWorkstreamInventories(cwd, excludeWs).map(ws => ({
+    name: ws.name,
+    status: ws.status,
+    current_phase: ws.current_phase,
+    phases: `${ws.completed_phases}/${ws.phase_count}`,
+  }));
 }
 
 module.exports = {