gsdd-cli 0.18.4 → 0.19.0

package/bin/lib/templates.mjs

@@ -1,224 +1,225 @@
-// templates.mjs - Project template and role installation/refresh helpers
-
-import { existsSync, mkdirSync, readdirSync, cpSync, unlinkSync } from 'fs';
-import { join } from 'path';
-import { fileHash, readManifest } from './manifest.mjs';
-
-export function installProjectTemplates({ planningDir, distilledDir, agentsDir }) {
-  const localTemplatesDir = join(planningDir, 'templates');
-  const globalTemplatesDir = join(distilledDir, 'templates');
-
-  if (!existsSync(localTemplatesDir)) {
-    if (existsSync(globalTemplatesDir)) {
-      cpSync(globalTemplatesDir, localTemplatesDir, { recursive: true });
-      console.log('  - copied templates to .planning/templates/');
-      // Warn-only by design: init should not fail on missing templates because
-      // the user may still proceed and fix later. The hard gate lives in
-      // `gsdd health` (E6/E7/E8) which reports these as errors. This is the
-      // first layer of the 3-layer scaffold defense (warn at init, error at
-      // health, regression tests in manifest suite).
-      const expectedSubdirs = ['delegates', 'research', 'codebase'];
-      for (const subdir of expectedSubdirs) {
-        if (!existsSync(join(localTemplatesDir, subdir))) {
-          console.log(`  - WARN: missing expected template subdir: ${subdir}/`);
-        }
-      }
-      const expectedRootFiles = ['spec.md', 'roadmap.md', 'auth-matrix.md'];
-      for (const file of expectedRootFiles) {
-        if (!existsSync(join(localTemplatesDir, file))) {
-          console.log(`  - WARN: missing expected root template file: ${file}`);
-        }
-      }
-    } else {
-      console.log('  - WARN: missing distilled/templates/; cannot copy templates');
-    }
-  } else {
-    console.log('  - .planning/templates/ already exists');
-  }
-
-  const localRolesDir = join(localTemplatesDir, 'roles');
-  if (!existsSync(localRolesDir)) {
-    if (existsSync(agentsDir)) {
-      mkdirSync(localRolesDir, { recursive: true });
-      for (const file of listRoleFiles(agentsDir)) {
-        cpSync(join(agentsDir, file), join(localRolesDir, file));
-      }
-      console.log('  - copied role contracts to .planning/templates/roles/');
-    } else {
-      console.log('  - WARN: missing agents/; cannot copy role contracts');
-    }
-  } else {
-    console.log('  - .planning/templates/roles/ already exists');
-  }
-}
-
-export function refreshTemplates({ planningDir, distilledDir, agentsDir, isDry = false }) {
-  const existingManifest = readManifest(planningDir);
-  const globalTemplatesDir = join(distilledDir, 'templates');
-  const localTemplatesDir = join(planningDir, 'templates');
-
-  const categories = [
-    { name: 'delegates', src: join(globalTemplatesDir, 'delegates'), dest: join(localTemplatesDir, 'delegates'), manifestKey: 'delegates' },
-    { name: 'research', src: join(globalTemplatesDir, 'research'), dest: join(localTemplatesDir, 'research'), manifestKey: 'research' },
-    { name: 'codebase', src: join(globalTemplatesDir, 'codebase'), dest: join(localTemplatesDir, 'codebase'), manifestKey: 'codebase' },
-  ];
-
-  for (const category of categories) {
-    refreshCategory(category, existingManifest, isDry);
-  }
-
-  refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingManifest, isDry);
-  refreshRoles(agentsDir, join(localTemplatesDir, 'roles'), existingManifest, isDry);
-}
-
-function listRoleFiles(agentsDir) {
-  return readdirSync(agentsDir).filter(
-    (file) => file.endsWith('.md') && file !== 'README.md' && !file.startsWith('_')
-  );
-}
-
-function refreshCategory({ name, src, dest, manifestKey }, existingManifest, isDry) {
-  if (!existsSync(src)) return;
-  if (!existsSync(dest) && !isDry) {
-    mkdirSync(dest, { recursive: true });
-  }
-
-  const manifestHashes = existingManifest?.templates?.[manifestKey] || null;
-  const sourceFiles = readdirSync(src).filter((file) => file.endsWith('.md'));
-  const installedFiles = existsSync(dest) ? readdirSync(dest).filter((file) => file.endsWith('.md')) : [];
-
-  for (const file of sourceFiles) {
-    const srcPath = join(src, file);
-    const destPath = join(dest, file);
-    const srcHash = fileHash(srcPath);
-
-    if (existsSync(destPath)) {
-      const destHash = fileHash(destPath);
-      if (destHash === srcHash) continue;
-
-      const manifestHash = manifestHashes?.[file];
-      if (manifestHash && destHash !== manifestHash) {
-        console.log(`  - WARN: ${name}/${file} was modified locally; overwriting with framework source`);
-      }
-    }
-
-    if (isDry) {
-      console.log(`  - would refresh ${name}/${file}`);
-    } else {
-      cpSync(srcPath, destPath);
-      console.log(`  - refreshed ${name}/${file}`);
-    }
-  }
-
-  for (const file of installedFiles) {
-    if (!sourceFiles.includes(file)) {
-      if (isDry) {
-        console.log(`  - would remove orphan ${name}/${file}`);
-      } else {
-        const orphanPath = join(dest, file);
-        if (existsSync(orphanPath)) {
-          unlinkSync(orphanPath);
-        }
-        console.log(`  - removed orphan ${name}/${file}`);
-      }
-    }
-  }
-}
-
-function refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingManifest, isDry) {
-  if (!existsSync(globalTemplatesDir)) return;
-
-  const manifestHashes = existingManifest?.templates?.root || null;
-  const sourceFiles = readdirSync(globalTemplatesDir).filter((file) => file.endsWith('.md'));
-
-  for (const file of sourceFiles) {
-    const srcPath = join(globalTemplatesDir, file);
-    const destPath = join(localTemplatesDir, file);
-    const srcHash = fileHash(srcPath);
-
-    if (existsSync(destPath)) {
-      const destHash = fileHash(destPath);
-      if (destHash === srcHash) continue;
-
-      const manifestHash = manifestHashes?.[file];
-      if (manifestHash && destHash !== manifestHash) {
-        console.log(`  - WARN: templates/${file} was modified locally; overwriting with framework source`);
-      }
-    }
-
-    if (isDry) {
-      console.log(`  - would refresh templates/${file}`);
-    } else {
-      cpSync(srcPath, destPath);
-      console.log(`  - refreshed templates/${file}`);
-    }
-  }
-
-  const installedRootFiles = existsSync(localTemplatesDir)
-    ? readdirSync(localTemplatesDir).filter((file) => file.endsWith('.md'))
-    : [];
-
-  for (const file of installedRootFiles) {
-    if (!sourceFiles.includes(file)) {
-      if (isDry) {
-        console.log(`  - would remove orphan templates/${file}`);
-      } else {
-        const orphanPath = join(localTemplatesDir, file);
-        if (existsSync(orphanPath)) {
-          unlinkSync(orphanPath);
-        }
-        console.log(`  - removed orphan templates/${file}`);
-      }
-    }
-  }
-}
-
-function refreshRoles(agentsDir, localRolesDir, existingManifest, isDry) {
-  if (!existsSync(agentsDir)) return;
-  if (!existsSync(localRolesDir) && !isDry) {
-    mkdirSync(localRolesDir, { recursive: true });
-  }
-
-  const manifestHashes = existingManifest?.roles || null;
-  const sourceFiles = listRoleFiles(agentsDir);
-  const installedFiles = existsSync(localRolesDir)
-    ? readdirSync(localRolesDir).filter((file) => file.endsWith('.md'))
-    : [];
-
-  for (const file of sourceFiles) {
-    const srcPath = join(agentsDir, file);
-    const destPath = join(localRolesDir, file);
-    const srcHash = fileHash(srcPath);
-
-    if (existsSync(destPath)) {
-      const destHash = fileHash(destPath);
-      if (destHash === srcHash) continue;
-
-      const manifestHash = manifestHashes?.[file];
-      if (manifestHash && destHash !== manifestHash) {
-        console.log(`  - WARN: roles/${file} was modified locally; overwriting with framework source`);
-      }
-    }
-
-    if (isDry) {
-      console.log(`  - would refresh roles/${file}`);
-    } else {
-      cpSync(srcPath, destPath);
-      console.log(`  - refreshed roles/${file}`);
-    }
-  }
-
-  for (const file of installedFiles) {
-    if (!sourceFiles.includes(file)) {
-      if (isDry) {
-        console.log(`  - would remove orphan roles/${file}`);
-      } else {
-        const orphanPath = join(localRolesDir, file);
-        if (existsSync(orphanPath)) {
-          unlinkSync(orphanPath);
-        }
-        console.log(`  - removed orphan roles/${file}`);
-      }
-    }
-  }
-}
+// templates.mjs - Project template and role installation/refresh helpers
+
+import { existsSync, mkdirSync, readdirSync, cpSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { fileHash, readManifest } from './manifest.mjs';
+
+export function installProjectTemplates({ planningDir, distilledDir, agentsDir }) {
+  const localTemplatesDir = join(planningDir, 'templates');
+  const globalTemplatesDir = join(distilledDir, 'templates');
+
+  if (!existsSync(localTemplatesDir)) {
+    if (existsSync(globalTemplatesDir)) {
+      cpSync(globalTemplatesDir, localTemplatesDir, { recursive: true });
+      console.log('  - copied templates to .planning/templates/');
+      // Warn-only by design: init should not fail on missing templates because
+      // the user may still proceed and fix later. The hard gate lives in
+      // `gsdd health` (E6/E7/E8) which reports these as errors. This is the
+      // first layer of the 3-layer scaffold defense (warn at init, error at
+      // health, regression tests in manifest suite).
+      const expectedSubdirs = ['delegates', 'research', 'codebase', 'brownfield-change'];
+      for (const subdir of expectedSubdirs) {
+        if (!existsSync(join(localTemplatesDir, subdir))) {
+          console.log(`  - WARN: missing expected template subdir: ${subdir}/`);
+        }
+      }
+      const expectedRootFiles = ['spec.md', 'roadmap.md', 'auth-matrix.md'];
+      for (const file of expectedRootFiles) {
+        if (!existsSync(join(localTemplatesDir, file))) {
+          console.log(`  - WARN: missing expected root template file: ${file}`);
+        }
+      }
+    } else {
+      console.log('  - WARN: missing distilled/templates/; cannot copy templates');
+    }
+  } else {
+    console.log('  - .planning/templates/ already exists');
+  }
+
+  const localRolesDir = join(localTemplatesDir, 'roles');
+  if (!existsSync(localRolesDir)) {
+    if (existsSync(agentsDir)) {
+      mkdirSync(localRolesDir, { recursive: true });
+      for (const file of listRoleFiles(agentsDir)) {
+        cpSync(join(agentsDir, file), join(localRolesDir, file));
+      }
+      console.log('  - copied role contracts to .planning/templates/roles/');
+    } else {
+      console.log('  - WARN: missing agents/; cannot copy role contracts');
+    }
+  } else {
+    console.log('  - .planning/templates/roles/ already exists');
+  }
+}
+
+export function refreshTemplates({ planningDir, distilledDir, agentsDir, isDry = false }) {
+  const existingManifest = readManifest(planningDir);
+  const globalTemplatesDir = join(distilledDir, 'templates');
+  const localTemplatesDir = join(planningDir, 'templates');
+
+  const categories = [
+    { name: 'delegates', src: join(globalTemplatesDir, 'delegates'), dest: join(localTemplatesDir, 'delegates'), manifestKey: 'delegates' },
+    { name: 'research', src: join(globalTemplatesDir, 'research'), dest: join(localTemplatesDir, 'research'), manifestKey: 'research' },
+    { name: 'codebase', src: join(globalTemplatesDir, 'codebase'), dest: join(localTemplatesDir, 'codebase'), manifestKey: 'codebase' },
+    { name: 'brownfield-change', src: join(globalTemplatesDir, 'brownfield-change'), dest: join(localTemplatesDir, 'brownfield-change'), manifestKey: 'brownfieldChange' },
+  ];
+
+  for (const category of categories) {
+    refreshCategory(category, existingManifest, isDry);
+  }
+
+  refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingManifest, isDry);
+  refreshRoles(agentsDir, join(localTemplatesDir, 'roles'), existingManifest, isDry);
+}
+
+function listRoleFiles(agentsDir) {
+  return readdirSync(agentsDir).filter(
+    (file) => file.endsWith('.md') && file !== 'README.md' && !file.startsWith('_')
+  );
+}
+
+function refreshCategory({ name, src, dest, manifestKey }, existingManifest, isDry) {
+  if (!existsSync(src)) return;
+  if (!existsSync(dest) && !isDry) {
+    mkdirSync(dest, { recursive: true });
+  }
+
+  const manifestHashes = existingManifest?.templates?.[manifestKey] || null;
+  const sourceFiles = readdirSync(src).filter((file) => file.endsWith('.md'));
+  const installedFiles = existsSync(dest) ? readdirSync(dest).filter((file) => file.endsWith('.md')) : [];
+
+  for (const file of sourceFiles) {
+    const srcPath = join(src, file);
+    const destPath = join(dest, file);
+    const srcHash = fileHash(srcPath);
+
+    if (existsSync(destPath)) {
+      const destHash = fileHash(destPath);
+      if (destHash === srcHash) continue;
+
+      const manifestHash = manifestHashes?.[file];
+      if (manifestHash && destHash !== manifestHash) {
+        console.log(`  - WARN: ${name}/${file} was modified locally; overwriting with framework source`);
+      }
+    }
+
+    if (isDry) {
+      console.log(`  - would refresh ${name}/${file}`);
+    } else {
+      cpSync(srcPath, destPath);
+      console.log(`  - refreshed ${name}/${file}`);
+    }
+  }
+
+  for (const file of installedFiles) {
+    if (!sourceFiles.includes(file)) {
+      if (isDry) {
+        console.log(`  - would remove orphan ${name}/${file}`);
+      } else {
+        const orphanPath = join(dest, file);
+        if (existsSync(orphanPath)) {
+          unlinkSync(orphanPath);
+        }
+        console.log(`  - removed orphan ${name}/${file}`);
+      }
+    }
+  }
+}
+
+function refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingManifest, isDry) {
+  if (!existsSync(globalTemplatesDir)) return;
+
+  const manifestHashes = existingManifest?.templates?.root || null;
+  const sourceFiles = readdirSync(globalTemplatesDir).filter((file) => file.endsWith('.md'));
+
+  for (const file of sourceFiles) {
+    const srcPath = join(globalTemplatesDir, file);
+    const destPath = join(localTemplatesDir, file);
+    const srcHash = fileHash(srcPath);
+
+    if (existsSync(destPath)) {
+      const destHash = fileHash(destPath);
+      if (destHash === srcHash) continue;
+
+      const manifestHash = manifestHashes?.[file];
+      if (manifestHash && destHash !== manifestHash) {
+        console.log(`  - WARN: templates/${file} was modified locally; overwriting with framework source`);
+      }
+    }
+
+    if (isDry) {
+      console.log(`  - would refresh templates/${file}`);
+    } else {
+      cpSync(srcPath, destPath);
+      console.log(`  - refreshed templates/${file}`);
+    }
+  }
+
+  const installedRootFiles = existsSync(localTemplatesDir)
+    ? readdirSync(localTemplatesDir).filter((file) => file.endsWith('.md'))
+    : [];
+
+  for (const file of installedRootFiles) {
+    if (!sourceFiles.includes(file)) {
+      if (isDry) {
+        console.log(`  - would remove orphan templates/${file}`);
+      } else {
+        const orphanPath = join(localTemplatesDir, file);
+        if (existsSync(orphanPath)) {
+          unlinkSync(orphanPath);
+        }
+        console.log(`  - removed orphan templates/${file}`);
+      }
+    }
+  }
+}
+
+function refreshRoles(agentsDir, localRolesDir, existingManifest, isDry) {
+  if (!existsSync(agentsDir)) return;
+  if (!existsSync(localRolesDir) && !isDry) {
+    mkdirSync(localRolesDir, { recursive: true });
+  }
+
+  const manifestHashes = existingManifest?.roles || null;
+  const sourceFiles = listRoleFiles(agentsDir);
+  const installedFiles = existsSync(localRolesDir)
+    ? readdirSync(localRolesDir).filter((file) => file.endsWith('.md'))
+    : [];
+
+  for (const file of sourceFiles) {
+    const srcPath = join(agentsDir, file);
+    const destPath = join(localRolesDir, file);
+    const srcHash = fileHash(srcPath);
+
+    if (existsSync(destPath)) {
+      const destHash = fileHash(destPath);
+      if (destHash === srcHash) continue;
+
+      const manifestHash = manifestHashes?.[file];
+      if (manifestHash && destHash !== manifestHash) {
+        console.log(`  - WARN: roles/${file} was modified locally; overwriting with framework source`);
+      }
+    }
+
+    if (isDry) {
+      console.log(`  - would refresh roles/${file}`);
+    } else {
+      cpSync(srcPath, destPath);
+      console.log(`  - refreshed roles/${file}`);
+    }
+  }
+
+  for (const file of installedFiles) {
+    if (!sourceFiles.includes(file)) {
+      if (isDry) {
+        console.log(`  - would remove orphan roles/${file}`);
+      } else {
+        const orphanPath = join(localRolesDir, file);
+        if (existsSync(orphanPath)) {
+          unlinkSync(orphanPath);
+        }
+        console.log(`  - removed orphan roles/${file}`);
+      }
+    }
+  }
+}

package/bin/lib/workspace-root.mjs

@@ -0,0 +1,132 @@
+import { existsSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+function normalizePath(value, cwd) {
+  return resolve(cwd, String(value));
+}
+
+function hasPlanningMarker(root) {
+  return existsSync(join(root, '.planning', 'config.json')) || existsSync(join(root, '.planning'));
+}
+
+export function consumeWorkspaceRootArg(rawArgs = []) {
+  const args = [];
+  let workspaceRootArg = null;
+  let invalid = false;
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg !== '--workspace-root') {
+      args.push(arg);
+      continue;
+    }
+
+    const value = rawArgs[index + 1] ?? null;
+    if (!value || value.startsWith('--')) {
+      invalid = true;
+      continue;
+    }
+
+    workspaceRootArg = value;
+    index += 1;
+  }
+
+  return { args, workspaceRootArg, invalid };
+}
+
+export function findWorkspaceRoot(startDir = process.cwd()) {
+  let current = resolve(startDir);
+
+  while (true) {
+    if (hasPlanningMarker(current)) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export function deriveWorkspaceRootFromHelperLocation(entryFileUrl) {
+  if (!entryFileUrl) return null;
+
+  const entryPath = entryFileUrl.startsWith('file:')
+    ? fileURLToPath(entryFileUrl)
+    : resolve(String(entryFileUrl));
+  const binDir = dirname(entryPath);
+  const planningDir = dirname(binDir);
+  const workspaceRoot = dirname(planningDir);
+
+  if (hasPlanningMarker(workspaceRoot) && binDir === join(planningDir, 'bin')) {
+    return workspaceRoot;
+  }
+
+  return null;
+}
+
+export function resolveWorkspaceContext(rawArgs = [], { cwd = process.cwd(), env = process.env } = {}) {
+  const { args, workspaceRootArg, invalid } = consumeWorkspaceRootArg(rawArgs);
+  if (invalid) {
+    return {
+      args,
+      invalid: true,
+      error: 'Usage: --workspace-root <path>',
+      workspaceRoot: resolve(cwd),
+      planningDir: join(resolve(cwd), '.planning'),
+    };
+  }
+
+  if (workspaceRootArg) {
+    const explicitRoot = normalizePath(workspaceRootArg, cwd);
+    if (!hasPlanningMarker(explicitRoot)) {
+      return {
+        args,
+        invalid: true,
+        error: `Workspace root does not contain .planning/: ${workspaceRootArg}`,
+        workspaceRoot: explicitRoot,
+        planningDir: join(explicitRoot, '.planning'),
+      };
+    }
+  }
+
+  const candidates = [];
+
+  if (workspaceRootArg) candidates.push(normalizePath(workspaceRootArg, cwd));
+
+  const discovered = findWorkspaceRoot(cwd);
+  if (discovered) candidates.push(discovered);
+
+  if (env.GSDD_WORKSPACE_ROOT) candidates.push(normalizePath(env.GSDD_WORKSPACE_ROOT, cwd));
+
+  candidates.push(resolve(cwd));
+
+  for (const candidate of candidates) {
+    if (hasPlanningMarker(candidate)) {
+      return {
+        args,
+        invalid: false,
+        workspaceRoot: candidate,
+        planningDir: join(candidate, '.planning'),
+      };
+    }
+  }
+
+  const fallbackRoot = candidates[0] ?? resolve(cwd);
+  return {
+    args,
+    invalid: false,
+    workspaceRoot: fallbackRoot,
+    planningDir: join(fallbackRoot, '.planning'),
+  };
+}
+
+export function bootstrapHelperWorkspace(entryFileUrl, env = process.env) {
+  const helperRoot = deriveWorkspaceRootFromHelperLocation(entryFileUrl);
+  if (!helperRoot) return null;
+  env.GSDD_WORKSPACE_ROOT = helperRoot;
+  try {
+    process.chdir(helperRoot);
+  } catch {
+    // best-effort: commands also resolve from env/upward search
+  }
+  return helperRoot;
+}