@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/bin/lib/projects.cjs

@@ -42,9 +42,11 @@ function createProjectSubfolder(cwd, slug, name, options) {
   // Create project directory
   fs.mkdirSync(projectDir, { recursive: true });
 
-  // Create standard subdirectories
+  // Create standard subdirectories with .gitkeep so git tracks empty folders
   for (const dir of STANDARD_DIRS) {
-    fs.mkdirSync(path.join(projectDir, dir), { recursive: true });
+    const dirPath = path.join(projectDir, dir);
+    fs.mkdirSync(dirPath, { recursive: true });
+    fs.writeFileSync(path.join(dirPath, '.gitkeep'), '');
   }
 
   // Create standard files with templates
@@ -163,21 +165,25 @@ function scanProjectReposTags(cwd, slug) {
   return Array.from(allRepos).sort();
 }
 
-// ─── PROJECTS.md Regeneration ───────────────────────────────────────────────
+// ─── Projects Readonly Listing ──────────────────────────────────────────────
 
 /**
- * Regenerate PROJECTS.md by scanning all project subfolders.
+ * Enumerate all project subfolders and build a { projects, warnings } result
+ * WITHOUT writing PROJECTS.md. Pure read function — no side effects.
  *
- * Reads each project's STATE.md for status/phase/progress, scans plan
- * <repos> tags for repos touched, and writes the derived PROJECTS.md.
+ * Thin-skeleton projects (PROJECT.md present, STATE.md absent) yield a placeholder
+ * entry with status "No milestone yet" and emit no warning — this is the post-thin-skeleton
+ * contract where /dgs:new-project writes only PROJECT.md and STATE.md is created later
+ * by /dgs:new-milestone.
  *
- * Ghost project guard: projects whose STATE.md is missing or unreadable
- * are warned about and omitted from the output.
+ * Ghost-project guard (defensive): a directory with neither PROJECT.md nor STATE.md is
+ * normally filtered out by getProjectFolders before reaching here. If a future caller
+ * passes such a slug directly, the legacy warning is preserved and the entry is omitted.
  *
  * @param {string} cwd - Working directory (product root)
  * @returns {{ projects: Array, warnings: string[] }}
  */
-function regenerateProjectsMd(cwd) {
+function listProjectsReadonly(cwd) {
   const slugs = getProjectFolders(cwd);
   const warnings = [];
   const projects = [];
@@ -185,7 +191,22 @@ function regenerateProjectsMd(cwd) {
   for (const slug of slugs) {
     const state = readProjectState(cwd, slug);
     if (!state) {
-      warnings.push(`Ghost project: ${slug} (STATE.md missing or unreadable)`);
+      // No STATE.md (or unreadable): if PROJECT.md is present, treat as thin-skeleton
+      // and emit a placeholder row. Only warn when neither marker is present (defensive
+      // guard for direct callers that bypass getProjectFolders).
+      const projectMdPath = path.join(getProjectDir(cwd, slug), 'PROJECT.md');
+      if (fs.existsSync(projectMdPath)) {
+        projects.push({
+          name: slug,
+          status: 'No milestone yet',
+          repos_touched: '',
+          current_phase: '',
+          completed_date: '',
+          progress: '',
+        });
+      } else {
+        warnings.push(`Ghost project: ${slug} (STATE.md missing or unreadable)`);
+      }
       continue;
     }
 
@@ -200,6 +221,25 @@ function regenerateProjectsMd(cwd) {
     });
   }
 
+  return { projects, warnings };
+}
+
+// ─── PROJECTS.md Regeneration ───────────────────────────────────────────────
+
+/**
+ * Regenerate PROJECTS.md by scanning all project subfolders.
+ *
+ * Reads each project's STATE.md for status/phase/progress, scans plan
+ * <repos> tags for repos touched, and writes the derived PROJECTS.md.
+ *
+ * Delegates the read phase to listProjectsReadonly.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @returns {{ projects: Array, warnings: string[] }}
+ */
+function regenerateProjectsMd(cwd) {
+  const { projects, warnings } = listProjectsReadonly(cwd);
+
   // Write PROJECTS.md
   let content = '# Projects\n\n';
   content += '## Active\n\n';
@@ -652,6 +692,20 @@ function cmdProjectsReactivate(cwd, options, raw) {
   const regenResult = regenerateProjectsMd(cwd);
   const remainingActive = regenResult.projects.filter(p => !p.status.toLowerCase().includes('completed'));
 
+  // Commit STATE.md and PROJECTS.md so reactivation is persisted
+  const planningRoot = getPlanningRoot(cwd);
+  const projectDir = getProjectDir(cwd, slug);
+  const statePath = path.join(projectDir, 'STATE.md');
+  const projectsPath = path.join(planningRoot, 'PROJECTS.md');
+  const filesToCommit = [statePath, projectsPath].filter(f => fs.existsSync(f));
+  try {
+    const { execSync } = require('child_process');
+    for (const f of filesToCommit) {
+      execSync(`git add "${f}"`, { cwd: planningRoot, stdio: 'pipe' });
+    }
+    execSync(`git commit -m "docs: reactivate project ${slug}" --allow-empty`, { cwd: planningRoot, stdio: 'pipe' });
+  } catch { /* commit may fail if nothing changed — safe to ignore */ }
+
   output({ reactivated: true, slug, set_as_current: !!opts.set_current, remaining_active: remainingActive.length }, raw);
 }
 
@@ -677,6 +731,7 @@ module.exports = {
   createProjectSubfolder,
   readProjectState,
   scanProjectReposTags,
+  listProjectsReadonly,
   regenerateProjectsMd,
   completeProject,
   reactivateProject,

package/deliver-great-systems/bin/lib/projects.test.cjs

@@ -11,22 +11,57 @@ const os = require('os');
 
 const { createTempDir, cleanupDir, createFixture , initGitRepo } = require('./test-helpers.cjs');
 const { resetPaths } = require('./paths.cjs');
-const { getProjectRoot } = require('./core.cjs');
+const { getProjectRoot, loadConfig } = require('./core.cjs');
 
 // Helper: create projects/ directory structure
 function setupPlanning(cwd) {
   fs.mkdirSync(path.join(cwd, 'projects'), { recursive: true });
 }
 
-// Helper: create a project subfolder with STATE.md manually under projects/<slug>/
+// Helper: create a fully-scaffolded project subfolder under projects/<slug>/
+// (writes PROJECT.md as the canonical project marker plus optional STATE.md for milestone state)
 function createProjectManually(cwd, slug, stateContent) {
   const projDir = path.join(cwd, 'projects', slug);
   fs.mkdirSync(projDir, { recursive: true });
+  fs.writeFileSync(path.join(projDir, 'PROJECT.md'), `# Project: ${slug}\n`);
   if (stateContent) {
     fs.writeFileSync(path.join(projDir, 'STATE.md'), stateContent);
   }
 }
 
+// Helper: create a thin-skeleton project (PROJECT.md only, no STATE.md) — mirrors what
+// /dgs:new-project writes before /dgs:new-milestone creates STATE.md.
+function createThinSkeletonProject(cwd, slug) {
+  const projDir = path.join(cwd, 'projects', slug);
+  fs.mkdirSync(projDir, { recursive: true });
+  fs.writeFileSync(path.join(projDir, 'PROJECT.md'), `# Project: ${slug}\n`);
+}
+
+// Capture stdout helper for cmdProjects* CLI calls (mirrors commands.test.cjs:48-70).
+function captureStdout(fn) {
+  const chunks = [];
+  const origWrite = process.stdout.write.bind(process.stdout);
+  const origExit = process.exit;
+  let exitCode = null;
+  process.stdout.write = (data) => { chunks.push(String(data)); return true; };
+  process.exit = (code) => {
+    exitCode = code == null ? 0 : code;
+    throw new Error('__EXIT__');
+  };
+  try {
+    fn();
+  } catch (e) {
+    if (e && e.message !== '__EXIT__') throw e;
+  } finally {
+    process.stdout.write = origWrite;
+    process.exit = origExit;
+  }
+  const stdout = chunks.join('');
+  let json = null;
+  try { json = JSON.parse(stdout); } catch { /* not JSON */ }
+  return { stdout, exitCode, json };
+}
+
 // Helper: create plan file with <repos> tags under projects/<slug>/phases/
 function createPlanFile(cwd, slug, phaseDir, planName, content) {
   const dir = path.join(cwd, 'projects', slug, 'phases', phaseDir);
@@ -39,10 +74,12 @@ const {
   readProjectState,
   scanProjectReposTags,
   regenerateProjectsMd,
+  listProjectsReadonly,
   completeProject,
   reactivateProject,
   parseProjectsMd,
   checkSlugPrefixCollision,
+  cmdProjectsSwitch,
 } = require('./projects.cjs');
 
 // ─── createProjectSubfolder ─────────────────────────────────────────────────
@@ -321,6 +358,131 @@ describe('regenerateProjectsMd', () => {
     const content = fs.readFileSync(path.join(tmpDir, 'PROJECTS.md'), 'utf-8');
     assert.ok(content.startsWith('# Projects'));
   });
+
+  it('writes thin-skeleton placeholder row into Active table', () => {
+    createThinSkeletonProject(tmpDir, 'word-gen');
+    regenerateProjectsMd(tmpDir);
+    const content = fs.readFileSync(path.join(tmpDir, 'PROJECTS.md'), 'utf-8');
+    const [activeSection, completedSection] = content.split('## Completed');
+    // Active row should match: | word-gen | No milestone yet |  |  |
+    assert.match(activeSection, /\|\s*word-gen\s*\|\s*No milestone yet\s*\|\s*\|\s*\|/);
+    // word-gen must NOT appear in the Completed section
+    assert.ok(!completedSection.includes('word-gen'), 'thin-skeleton project must not appear in Completed section');
+  });
+});
+
+// ─── listProjectsReadonly ───────────────────────────────────────────────────
+
+describe('listProjectsReadonly', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir(); tmpDir = fs.realpathSync(tmpDir); initGitRepo(tmpDir);
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => { resetPaths(); cleanupDir(tmpDir); });
+
+  it('returns same projects shape as regenerateProjectsMd for a fixture with 2 active + 1 completed', () => {
+    createProjectManually(tmpDir, 'active-a', '# Project State\n\nPhase: 1\nStatus: In progress\nProgress: [##--------] 20%\n');
+    createProjectManually(tmpDir, 'active-b', '# Project State\n\nPhase: 3\nStatus: Active\nProgress: [#####-----] 50%\n');
+    createProjectManually(tmpDir, 'done-c', '# Project State\n\nPhase: 10\nStatus: completed\nProgress: [##########] 100%\nCompleted: 2026-02-15\n');
+
+    const readResult = listProjectsReadonly(tmpDir);
+    const regenResult = regenerateProjectsMd(tmpDir);
+
+    assert.ok(Array.isArray(readResult.projects));
+    assert.ok(Array.isArray(readResult.warnings));
+    assert.strictEqual(readResult.projects.length, regenResult.projects.length);
+    // Projects should have identical fields
+    const readByName = Object.fromEntries(readResult.projects.map(p => [p.name, p]));
+    const regenByName = Object.fromEntries(regenResult.projects.map(p => [p.name, p]));
+    for (const name of Object.keys(readByName)) {
+      assert.deepStrictEqual(readByName[name], regenByName[name]);
+    }
+  });
+
+  it('does NOT write PROJECTS.md', () => {
+    createProjectManually(tmpDir, 'proj-a', '# Project State\n\nPhase: 2\nStatus: Active\n');
+    const projectsMdPath = path.join(tmpDir, 'PROJECTS.md');
+    assert.strictEqual(fs.existsSync(projectsMdPath), false);
+
+    const result = listProjectsReadonly(tmpDir);
+    assert.ok(Array.isArray(result.projects));
+
+    assert.strictEqual(fs.existsSync(projectsMdPath), false, 'listProjectsReadonly must not create PROJECTS.md');
+  });
+
+  it('does NOT modify an existing PROJECTS.md', () => {
+    createProjectManually(tmpDir, 'proj-a', '# Project State\n\nPhase: 2\nStatus: Active\n');
+    const projectsMdPath = path.join(tmpDir, 'PROJECTS.md');
+    const sentinel = '# Projects\n\nSENTINEL CONTENT — should not be overwritten by listProjectsReadonly\n';
+    fs.writeFileSync(projectsMdPath, sentinel);
+
+    listProjectsReadonly(tmpDir);
+
+    const after = fs.readFileSync(projectsMdPath, 'utf-8');
+    assert.strictEqual(after, sentinel, 'listProjectsReadonly must not modify existing PROJECTS.md');
+  });
+
+  it('returns a project entry with all expected fields', () => {
+    createProjectManually(tmpDir, 'proj-a', '# Project State\n\nPhase: 5\nStatus: Active\nProgress: [###-------] 30%\n');
+    const result = listProjectsReadonly(tmpDir);
+    assert.strictEqual(result.projects.length, 1);
+    const p = result.projects[0];
+    assert.strictEqual(p.name, 'proj-a');
+    assert.strictEqual(p.status, 'Active');
+    assert.strictEqual(p.current_phase, '5');
+    assert.strictEqual(p.progress, 30);
+    assert.strictEqual(typeof p.repos_touched, 'string');
+    assert.ok('completed_date' in p);
+  });
+
+  it('returns ghost-project behavior consistent with regenerateProjectsMd (omits projects without STATE.md)', () => {
+    // Ghost project: directory exists but no STATE.md
+    fs.mkdirSync(path.join(tmpDir, 'projects', 'ghost-project'), { recursive: true });
+    // Real project
+    createProjectManually(tmpDir, 'real-project', '# State\n\nStatus: Active\n');
+
+    const result = listProjectsReadonly(tmpDir);
+    assert.ok(Array.isArray(result.warnings));
+    assert.ok(!result.projects.some(p => p.name === 'ghost-project'), 'ghost project should be omitted from projects array');
+  });
+
+  it('empty projects directory returns { projects: [], warnings: [] }', () => {
+    const result = listProjectsReadonly(tmpDir);
+    assert.deepStrictEqual(result.projects, []);
+    assert.ok(Array.isArray(result.warnings));
+  });
+
+  it('returns placeholder entry with status "No milestone yet" for thin-skeleton (PROJECT.md only) and emits no warning for that slug', () => {
+    createThinSkeletonProject(tmpDir, 'word-gen');
+    const result = listProjectsReadonly(tmpDir);
+    assert.strictEqual(result.projects.length, 1);
+    assert.deepStrictEqual(result.projects[0], {
+      name: 'word-gen',
+      status: 'No milestone yet',
+      repos_touched: '',
+      current_phase: '',
+      completed_date: '',
+      progress: '',
+    });
+    assert.ok(Array.isArray(result.warnings));
+    assert.ok(!result.warnings.some(w => w.includes('word-gen')), 'no warning should mention word-gen');
+  });
+
+  it('preserves ghost-warning code path when neither PROJECT.md nor STATE.md exists', () => {
+    // Genuine ghost: no marker files at all — getProjectFolders filters it out, so it
+    // never reaches listProjectsReadonly's loop. Real project alongside to keep suite non-empty.
+    fs.mkdirSync(path.join(tmpDir, 'projects', 'ghost'), { recursive: true });
+    createProjectManually(tmpDir, 'real-project', '# State\n\nStatus: Active\n');
+
+    const result = listProjectsReadonly(tmpDir);
+    assert.ok(Array.isArray(result.warnings));
+    assert.ok(!result.projects.some(p => p.name === 'ghost'), 'ghost dir should be omitted from projects array');
+    // The warnings array remains a defensive code path; legacy callers may still trip it.
+    // No assertion on warnings content here — discovery layer (getProjectFolders) handles ghost exclusion.
+  });
 });
 
 // ─── completeProject ────────────────────────────────────────────────────────
@@ -857,6 +1019,7 @@ describe('cmdProjectsSwitch guards', () => {
       'config.json': JSON.stringify({ current_project: 'finished-proj' }),
       'PROJECTS.md': '# Projects\n\n## Active\n\n| Project | Status | Repos Touched | Current Phase |\n|---------|--------|---------------|---------------|\n\n## Completed\n\n| Project | Completed | Duration |\n|---------|-----------|----------|\n| finished-proj | 2026-02-20 | |\n',
       'REPOS.md': '# Repos\n\n| Name | Path |\n',
+      'projects/finished-proj/PROJECT.md': '# Project: Finished Proj\n',
       'projects/finished-proj/STATE.md': '# Project State\n\nStatus: completed\nCompleted: 2026-02-20\n',
     });
 
@@ -870,3 +1033,36 @@ describe('cmdProjectsSwitch guards', () => {
     }
   });
 });
+
+// ─── cmdProjectsSwitch thin-skeleton ────────────────────────────────────────
+
+describe('cmdProjectsSwitch thin-skeleton', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir(); tmpDir = fs.realpathSync(tmpDir); initGitRepo(tmpDir);
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => { resetPaths(); cleanupDir(tmpDir); });
+
+  it('cmdProjectsSwitch succeeds on a thin-skeleton slug and writes current_project to config.json', () => {
+    // v2 prerequisites: config.json, PROJECTS.md, REPOS.md at planning root,
+    // plus the thin-skeleton project under projects/<slug>/PROJECT.md
+    fs.writeFileSync(path.join(tmpDir, 'config.json'), '{}');
+    fs.writeFileSync(path.join(tmpDir, 'PROJECTS.md'), '# Projects\n');
+    fs.writeFileSync(path.join(tmpDir, 'REPOS.md'), '# Repos\n');
+    createThinSkeletonProject(tmpDir, 'word-gen');
+
+    const { exitCode } = captureStdout(() => {
+      cmdProjectsSwitch(tmpDir, 'word-gen', true);
+    });
+
+    // exitCode 0 (or unset null = success path that did not throw) signals success
+    assert.ok(exitCode === 0 || exitCode === null, `expected success exit, got ${exitCode}`);
+
+    // config.json must now contain current_project: word-gen
+    const config = loadConfig(tmpDir);
+    assert.strictEqual(config.current_project, 'word-gen');
+  });
+});