code-as-plan 2.0.0

package/cap/bin/lib/monorepo-context.cjs

@@ -0,0 +1,224 @@
+// @gsd-context Monorepo context resolver -- assembles per-app planning paths and agent context for scoped operations
+// @gsd-decision Separate module from workspace-detector to keep detection (read-only) separate from planning structure (write operations)
+// @gsd-constraint Zero external dependencies -- uses only Node.js built-ins (fs, path)
+// @gsd-ref(ref:AC-3) Each scoped app gets its own .planning/ directory with independent CODE-INVENTORY.md, PRD.md, and FEATURES.md
+// @gsd-ref(ref:AC-7) Root .planning/ holds global decisions; app .planning/ holds app-specific work
+// @gsd-pattern Two-level planning: root .planning/ for global context, app-path/.planning/ for scoped work
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// @gsd-api resolveAppPlanningDir(rootPath, appRelativePath) -- returns absolute path to app-scoped .planning/ directory
+
+/**
+ * @typedef {Object} MonorepoContext
+ * @property {string} rootPlanningDir - Absolute path to root .planning/
+ * @property {string} appPlanningDir - Absolute path to app-scoped .planning/
+ * @property {string} appRoot - Absolute path to the scoped app directory
+ * @property {string} appName - Name of the scoped app
+ * @property {string[]} manifestPaths - Paths to relevant package manifests for this app
+ * @property {Object} globalContext - Parsed global planning docs (lightweight refs)
+ */
+
+/**
+ * Resolve the .planning/ directory for an app-scoped operation.
+ *
+ * @param {string} rootPath - Monorepo root
+ * @param {string} appRelativePath - Relative path to the app (e.g., 'apps/dashboard')
+ * @returns {string} Absolute path to app .planning/ directory
+ */
+function resolveAppPlanningDir(rootPath, appRelativePath) {
+  return path.join(rootPath, appRelativePath, '.planning');
+}
+
+/**
+ * Initialize the per-app .planning/ directory structure.
+ * Creates the directory and placeholder files mirroring root .planning/.
+ *
+ * @param {string} rootPath - Monorepo root
+ * @param {string} appRelativePath - Relative path to the app
+ * @param {Object} [options]
+ * @param {string} [options.appName] - Display name for headers
+ * @returns {string} Path to created .planning/ directory
+ */
+function initAppPlanning(rootPath, appRelativePath, options) {
+  options = options || {};
+  const appPlanningDir = resolveAppPlanningDir(rootPath, appRelativePath);
+  const appName = options.appName || path.basename(appRelativePath);
+
+  fs.mkdirSync(appPlanningDir, { recursive: true });
+  fs.mkdirSync(path.join(appPlanningDir, 'prototype'), { recursive: true });
+
+  // @gsd-decision Create stub PRD.md and FEATURES.md in app .planning/ -- agents expect these files to exist
+  const prdPath = path.join(appPlanningDir, 'PRD.md');
+  if (!fs.existsSync(prdPath)) {
+    fs.writeFileSync(prdPath, `# ${appName} -- PRD\n\nApp-scoped PRD. Generated by monorepo-init.\n`, 'utf-8');
+  }
+
+  const featuresPath = path.join(appPlanningDir, 'FEATURES.md');
+  if (!fs.existsSync(featuresPath)) {
+    fs.writeFileSync(featuresPath, `# ${appName} -- Feature Map\n\nAuto-generated. Run extract-plan --app ${appRelativePath} to populate.\n`, 'utf-8');
+  }
+
+  // Create prototype/CODE-INVENTORY.md stub
+  const codeInventoryPath = path.join(appPlanningDir, 'prototype', 'CODE-INVENTORY.md');
+  if (!fs.existsSync(codeInventoryPath)) {
+    fs.writeFileSync(codeInventoryPath, `# CODE-INVENTORY.md\n\nRun /gsd:extract-plan --app ${appRelativePath} to populate.\n`, 'utf-8');
+  }
+
+  return appPlanningDir;
+}
+
+/**
+ * Build the full MonorepoContext for an app-scoped operation.
+ * This is the primary function agents consume to get focused context.
+ *
+ * @param {string} rootPath - Monorepo root
+ * @param {string} appRelativePath - Relative path to app
+ * @param {Object} [options]
+ * @param {string} [options.appName] - App display name
+ * @param {string[]} [options.appDependencies] - Package names this app depends on
+ * @returns {MonorepoContext}
+ */
+// @gsd-api buildMonorepoContext(rootPath, appRelativePath, options) -- returns MonorepoContext with local + global planning refs
+function buildMonorepoContext(rootPath, appRelativePath, options) {
+  options = options || {};
+  const appAbsPath = path.join(rootPath, appRelativePath);
+  const appPlanningDir = resolveAppPlanningDir(rootPath, appRelativePath);
+  const rootPlanningDir = path.join(rootPath, '.planning');
+  const manifestsDir = path.join(rootPlanningDir, 'manifests');
+
+  const manifestPaths = resolveRelevantManifests(manifestsDir, appAbsPath, options.appDependencies || []);
+
+  // @gsd-decision Load global context lazily -- only read file headers, not full content, to minimize token usage
+  const globalContext = loadGlobalContextRefs(rootPlanningDir);
+
+  return {
+    rootPlanningDir,
+    appPlanningDir,
+    appRoot: appAbsPath,
+    appName: options.appName || path.basename(appRelativePath),
+    manifestPaths,
+    globalContext,
+  };
+}
+
+/**
+ * Find package manifests relevant to a specific app based on its dependencies.
+ *
+ * @param {string} manifestsDir - Path to .planning/manifests/
+ * @param {string} appAbsPath - Absolute path to the app
+ * @param {string[]} knownDeps - Package names from workspace detection
+ * @returns {string[]} Paths to relevant manifest .md files
+ */
+function resolveRelevantManifests(manifestsDir, appAbsPath, knownDeps) {
+  // @gsd-risk If app package.json is missing or malformed, no manifests are resolved -- agent gets no package context
+  const manifestPaths = [];
+
+  if (!fs.existsSync(manifestsDir)) return manifestPaths;
+
+  // Read app's package.json for its dependencies
+  const appPkgPath = path.join(appAbsPath, 'package.json');
+  let appDeps = [...knownDeps];
+
+  try {
+    const appPkg = JSON.parse(fs.readFileSync(appPkgPath, 'utf-8'));
+    const allDeps = { ...(appPkg.dependencies || {}), ...(appPkg.devDependencies || {}) };
+    for (const [name, version] of Object.entries(allDeps)) {
+      if (typeof version === 'string' && version.startsWith('workspace:')) {
+        if (!appDeps.includes(name)) appDeps.push(name);
+      }
+    }
+  } catch {
+    // No package.json or malformed -- use knownDeps only
+  }
+
+  // Match dependency names to manifest files
+  try {
+    const manifestFiles = fs.readdirSync(manifestsDir).filter(f => f.endsWith('.md'));
+    for (const file of manifestFiles) {
+      const baseName = file.replace('.md', '').replace(/__/g, '/');
+      // Check if any app dependency matches this manifest (with or without @ prefix)
+      const matches = appDeps.some(dep => {
+        const depNorm = dep.replace(/^@/, '');
+        return baseName === depNorm || baseName === dep;
+      });
+      if (matches) {
+        manifestPaths.push(path.join(manifestsDir, file));
+      }
+    }
+  } catch {
+    // manifestsDir not readable
+  }
+
+  return manifestPaths;
+}
+
+/**
+ * Load lightweight references from global .planning/ docs.
+ * Reads only headers and first paragraphs to minimize context size.
+ *
+ * @param {string} rootPlanningDir - Path to root .planning/
+ * @returns {Object} Global context references
+ */
+function loadGlobalContextRefs(rootPlanningDir) {
+  const refs = {
+    hasProject: false,
+    hasRoadmap: false,
+    hasRequirements: false,
+    projectSummary: null,
+  };
+
+  const projectPath = path.join(rootPlanningDir, 'PROJECT.md');
+  if (fs.existsSync(projectPath)) {
+    refs.hasProject = true;
+    try {
+      const content = fs.readFileSync(projectPath, 'utf-8');
+      // Extract first 5 lines as summary
+      refs.projectSummary = content.split('\n').slice(0, 5).join('\n');
+    } catch {
+      // Ignore
+    }
+  }
+
+  refs.hasRoadmap = fs.existsSync(path.join(rootPlanningDir, 'ROADMAP.md'));
+  refs.hasRequirements = fs.existsSync(path.join(rootPlanningDir, 'REQUIREMENTS.md'));
+
+  return refs;
+}
+
+/**
+ * Modify extract-tags scan path to scope to an app directory.
+ * Used by the --app flag in gsd-tools.cjs extract-tags case.
+ *
+ * @param {string} rootPath - Monorepo root
+ * @param {string} appRelativePath - App-scoped path
+ * @param {Object} originalOpts - Original extract-tags options
+ * @returns {Object} Modified options with scoped targetPath and outputFile
+ */
+// @gsd-api scopeExtractTags(rootPath, appRelativePath, originalOpts) -- returns modified options for app-scoped tag extraction
+function scopeExtractTags(rootPath, appRelativePath, originalOpts) {
+  const appAbsPath = path.join(rootPath, appRelativePath);
+  const appPlanningDir = resolveAppPlanningDir(rootPath, appRelativePath);
+
+  return {
+    ...originalOpts,
+    // Override target path to scan only the app directory
+    targetPath: appAbsPath,
+    // Write output to app-scoped .planning/prototype/
+    outputFile: originalOpts.outputFile
+      ? path.join(appPlanningDir, 'prototype', path.basename(originalOpts.outputFile))
+      : originalOpts.outputFile,
+  };
+}
+
+module.exports = {
+  resolveAppPlanningDir,
+  initAppPlanning,
+  buildMonorepoContext,
+  resolveRelevantManifests,
+  loadGlobalContextRefs,
+  scopeExtractTags,
+};