@ktpartners/dgs-platform 2.6.3 → 2.7.0

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

@@ -1,11 +1,15 @@
 /**
- * Config — Planning config CRUD operations
+ * Config -- Planning config CRUD operations
  *
- * Uses getConfigPath(cwd, mode) for all config file path resolution:
- *   - 'read' mode: prefers dgs.config.json, falls back to config.json (dual-read)
- *   - 'write' mode: always targets dgs.config.json (write-forward migration)
+ * Two-file config layout:
+ *   - config.json (tracked): shared team settings (mode, workflows, git, model_profile, etc.)
+ *   - config.local.json (gitignored): per-machine state (current_project, planningRoot, hint flags)
  *
- * Zero hardcoded .planning/config.json paths — all resolved via getPlanningRoot.
+ * LOCAL_KEYS defines which keys route to config.local.json.
+ * writeConfigField routes writes to the correct file based on isLocalKey().
+ * loadConfig (in core.cjs) merges both files with local overriding shared.
+ *
+ * Zero hardcoded .planning/config.json paths -- all resolved via getPlanningRoot.
  */
 
 const fs = require('fs');
@@ -13,6 +17,17 @@ const path = require('path');
 const { output, error } = require('./core.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 
+/**
+ * Keys that belong in config.local.json (per-machine state).
+ * These are stored as top-level keys in config.local.json.
+ */
+const LOCAL_KEYS = new Set([
+  'current_project',
+  'planningRoot',
+  'v2_hint_shown',
+  'sync_hint_shown',
+]);
+
 const VALID_CONFIG_KEYS = new Set([
   'mode', 'granularity', 'parallelization', 'commit_docs', 'model_profile',
   'search_gitignored', 'brave_search',
@@ -20,31 +35,144 @@ const VALID_CONFIG_KEYS = new Set([
   'workflow.nyquist_validation', 'workflow.ui_phase', 'workflow.ui_safety_gate',
   'workflow._auto_chain_active', 'workflow.discipline',
   'git.base_branch', 'git.branching_strategy', 'git.phase_branch_template', 'git.milestone_branch_template',
+  'git.sync', 'git.sync_push', 'git.sync_pull',
   'planning.commit_docs', 'planning.search_gitignored',
 ]);
 
 /**
+ * Get the path to the shared (tracked) config file.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {string} Absolute path to config.json
+ */
+function getSharedConfigPath(cwd) {
+  return path.join(getPlanningRoot(cwd), 'config.json');
+}
+
+/**
+ * Get the path to the local (gitignored) config file.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {string} Absolute path to config.local.json
+ */
+function getLocalConfigPath(cwd) {
+  return path.join(getPlanningRoot(cwd), 'config.local.json');
+}
+
+/**
+ * @deprecated Use getSharedConfigPath or getLocalConfigPath instead.
  * Resolve the config file path for the given cwd and mode.
+ * Now returns config.json (shared) for both read and write modes.
+ * Falls back to legacy dgs.config.json for read mode.
  *
  * @param {string} cwd - Working directory
- * @param {'read'|'write'} mode - 'read' for dual-check (dgs.config.json first, config.json fallback),
- *                                  'write' for always dgs.config.json
+ * @param {'read'|'write'} mode - 'read' or 'write'
  * @returns {string} Absolute path to the config file
  */
 function getConfigPath(cwd, mode) {
   const root = getPlanningRoot(cwd);
-  const newPath = path.join(root, 'dgs.config.json');
-  if (mode === 'write') return newPath;
-  // Read mode: prefer dgs.config.json, fall back to config.json
-  if (fs.existsSync(newPath)) return newPath;
-  const legacyPath = path.join(root, 'config.json');
+  const sharedPath = path.join(root, 'config.json');
+  if (mode === 'write') return sharedPath;
+  // Read mode: prefer config.json, fall back to legacy dgs.config.json
+  if (fs.existsSync(sharedPath)) return sharedPath;
+  const legacyPath = path.join(root, 'dgs.config.json');
   if (fs.existsSync(legacyPath)) return legacyPath;
-  return newPath; // default when neither exists
+  return sharedPath; // default when neither exists
+}
+
+/**
+ * Check if a key path should be stored in config.local.json.
+ *
+ * @param {string} keyPath - Dot-notation key (e.g., 'current_project', 'workflow.research')
+ * @returns {boolean} True if the key belongs in config.local.json
+ */
+function isLocalKey(keyPath) {
+  // Check the key itself or its top-level segment
+  if (LOCAL_KEYS.has(keyPath)) return true;
+  const topLevel = keyPath.split('.')[0];
+  return LOCAL_KEYS.has(topLevel);
+}
+
+/**
+ * Read a JSON file safely.
+ * @param {string} filePath
+ * @returns {object}
+ */
+function _readJsonSafe(filePath) {
+  try {
+    if (fs.existsSync(filePath)) {
+      return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+  } catch { /* ignore */ }
+  return {};
+}
+
+/**
+ * Write a JSON object to a file, creating parent directories as needed.
+ * @param {string} filePath
+ * @param {object} data
+ */
+function _writeJson(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+/**
+ * Perform a one-time migration of legacy dgs.config.json to the two-file layout.
+ * Separates local keys from shared keys and writes to the appropriate files.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {boolean} True if migration was performed
+ */
+function _migrateLegacyConfig(cwd) {
+  const root = getPlanningRoot(cwd);
+  const legacyPath = path.join(root, 'dgs.config.json');
+  const sharedPath = path.join(root, 'config.json');
+  const localPath = path.join(root, 'config.local.json');
+
+  if (!fs.existsSync(legacyPath)) return false;
+  if (fs.existsSync(sharedPath) || fs.existsSync(localPath)) return false;
+
+  try {
+    const legacy = JSON.parse(fs.readFileSync(legacyPath, 'utf-8'));
+    const shared = {};
+    const local = {};
+
+    for (const [key, value] of Object.entries(legacy)) {
+      if (LOCAL_KEYS.has(key)) {
+        local[key] = value;
+      } else if (key === 'git' && typeof value === 'object') {
+        // Split git section: sync_hint_shown is local, rest is shared
+        const gitShared = {};
+        for (const [gk, gv] of Object.entries(value)) {
+          if (gk === 'sync_hint_shown') {
+            local.sync_hint_shown = gv;
+          } else {
+            gitShared[gk] = gv;
+          }
+        }
+        if (Object.keys(gitShared).length > 0) {
+          shared.git = gitShared;
+        }
+      } else {
+        shared[key] = value;
+      }
+    }
+
+    if (Object.keys(shared).length > 0) _writeJson(sharedPath, shared);
+    if (Object.keys(local).length > 0) _writeJson(localPath, local);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 function cmdConfigEnsureSection(cwd, raw) {
-  const writePath = getConfigPath(cwd, 'write');
-  const parentDir = path.dirname(writePath);
+  const sharedPath = getSharedConfigPath(cwd);
+  const parentDir = path.dirname(sharedPath);
 
   // Ensure parent directory exists
   try {
@@ -55,9 +183,18 @@ function cmdConfigEnsureSection(cwd, raw) {
     error('Failed to create config directory: ' + err.message);
   }
 
-  // Check if config already exists (either dgs.config.json or legacy config.json)
-  const readPath = getConfigPath(cwd, 'read');
-  if (fs.existsSync(readPath)) {
+  // Check if config already exists (shared config.json or legacy dgs.config.json)
+  if (fs.existsSync(sharedPath)) {
+    const result = { created: false, reason: 'already_exists' };
+    output(result, raw, 'exists');
+    return;
+  }
+
+  // Check for legacy dgs.config.json and migrate if found
+  const root = getPlanningRoot(cwd);
+  const legacyPath = path.join(root, 'dgs.config.json');
+  if (fs.existsSync(legacyPath)) {
+    _migrateLegacyConfig(cwd);
     const result = { created: false, reason: 'already_exists' };
     output(result, raw, 'exists');
     return;
@@ -87,6 +224,7 @@ function cmdConfigEnsureSection(cwd, raw) {
   }
 
   // Create default config (user-level defaults override hardcoded defaults)
+  // Only shared settings go to config.json -- no local keys
   const hardcoded = {
     model_profile: 'balanced',
     commit_docs: true,
@@ -102,6 +240,10 @@ function cmdConfigEnsureSection(cwd, raw) {
       nyquist_validation: true,
       discipline: true,
     },
+    git: {
+      sync_push: 'prompt',
+      sync_pull: 'prompt',
+    },
     parallelization: true,
     brave_search: hasBraveSearch,
   };
@@ -109,14 +251,20 @@ function cmdConfigEnsureSection(cwd, raw) {
     ...hardcoded,
     ...userDefaults,
     workflow: { ...hardcoded.workflow, ...(userDefaults.workflow || {}) },
+    git: { ...hardcoded.git, ...(userDefaults.git || {}) },
   };
 
+  // Remove any local keys that might have leaked in from userDefaults
+  for (const lk of LOCAL_KEYS) {
+    delete defaults[lk];
+  }
+
   try {
-    fs.writeFileSync(writePath, JSON.stringify(defaults, null, 2), 'utf-8');
-    const result = { created: true, path: path.relative(cwd, writePath) || writePath };
+    fs.writeFileSync(sharedPath, JSON.stringify(defaults, null, 2), 'utf-8');
+    const result = { created: true, path: path.relative(cwd, sharedPath) || sharedPath };
     output(result, raw, 'created');
   } catch (err) {
-    error('Failed to create dgs.config.json: ' + err.message);
+    error('Failed to create config.json: ' + err.message);
   }
 }
 
@@ -129,21 +277,38 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
     error(`Unknown config key: "${keyPath}". Valid keys: ${[...VALID_CONFIG_KEYS].sort().join(', ')}`);
   }
 
+  // Validate sync mode values
+  const VALID_SYNC_MODES = new Set(['off', 'prompt', 'auto']);
+  if ((keyPath === 'git.sync_push' || keyPath === 'git.sync_pull' || keyPath === 'git.sync') && !VALID_SYNC_MODES.has(value)) {
+    error(`Invalid sync mode: "${value}". Valid values: off, prompt, auto`);
+  }
+
   // Parse value (handle booleans and numbers)
   let parsedValue = value;
   if (value === 'true') parsedValue = true;
   else if (value === 'false') parsedValue = false;
   else if (!isNaN(value) && value !== '') parsedValue = Number(value);
 
-  // Load existing config from read path (may be legacy config.json)
-  const readPath = getConfigPath(cwd, 'read');
-  let config = {};
-  try {
-    if (fs.existsSync(readPath)) {
-      config = JSON.parse(fs.readFileSync(readPath, 'utf-8'));
+  // Load existing shared config
+  const sharedPath = getSharedConfigPath(cwd);
+  let config = _readJsonSafe(sharedPath);
+
+  // git.sync is a virtual shorthand -- sets both sync_push and sync_pull in shared config
+  if (keyPath === 'git.sync') {
+    if (!config.git || typeof config.git !== 'object') {
+      config.git = {};
     }
-  } catch (err) {
-    error('Failed to read config: ' + err.message);
+    config.git.sync_push = parsedValue;
+    config.git.sync_pull = parsedValue;
+
+    try {
+      _writeJson(sharedPath, config);
+      const result = { updated: true, key: keyPath, value: parsedValue, expanded: ['git.sync_push', 'git.sync_pull'] };
+      output(result, raw, `git.sync_push=${parsedValue}, git.sync_pull=${parsedValue}`);
+    } catch (err) {
+      error('Failed to write config.json: ' + err.message);
+    }
+    return; // output() calls process.exit, but guard with return
   }
 
   // Set nested value using dot notation (e.g., "workflow.research")
@@ -158,14 +323,13 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
   }
   current[keys[keys.length - 1]] = parsedValue;
 
-  // Write to dgs.config.json (write-forward migration)
-  const writePath = getConfigPath(cwd, 'write');
+  // Write to shared config.json (all VALID_CONFIG_KEYS are shared)
   try {
-    fs.writeFileSync(writePath, JSON.stringify(config, null, 2), 'utf-8');
+    _writeJson(sharedPath, config);
     const result = { updated: true, key: keyPath, value: parsedValue };
     output(result, raw, `${keyPath}=${parsedValue}`);
   } catch (err) {
-    error('Failed to write dgs.config.json: ' + err.message);
+    error('Failed to write config.json: ' + err.message);
   }
 }
 
@@ -174,17 +338,21 @@ function cmdConfigGet(cwd, keyPath, raw) {
     error('Usage: config-get <key.path>');
   }
 
-  const readPath = getConfigPath(cwd, 'read');
-  let config = {};
-  try {
-    if (fs.existsSync(readPath)) {
-      config = JSON.parse(fs.readFileSync(readPath, 'utf-8'));
-    } else {
-      error('No config file found at ' + readPath);
+  // Read both files and merge (local overrides shared)
+  const shared = _readJsonSafe(getSharedConfigPath(cwd));
+  const local = _readJsonSafe(getLocalConfigPath(cwd));
+
+  // Fall back to legacy dgs.config.json if neither new file has data
+  let config;
+  if (Object.keys(shared).length === 0 && Object.keys(local).length === 0) {
+    const root = getPlanningRoot(cwd);
+    const legacyPath = path.join(root, 'dgs.config.json');
+    config = _readJsonSafe(legacyPath);
+    if (Object.keys(config).length === 0) {
+      error('No config file found at ' + getSharedConfigPath(cwd));
     }
-  } catch (err) {
-    if (err.message.startsWith('No config file')) throw err;
-    error('Failed to read config: ' + err.message);
+  } else {
+    config = { ...shared, ...local };
   }
 
   // Traverse dot-notation path (e.g., "workflow.auto_advance")
@@ -206,28 +374,46 @@ function cmdConfigGet(cwd, keyPath, raw) {
 
 /**
  * Programmatically set a config field. Uses same dot-notation as cmdConfigSet.
- * Does NOT call output()/process.exit() — returns the updated config.
+ * Does NOT call output()/process.exit() -- returns the updated merged config.
  *
- * Reads from legacy config.json if it exists, writes to dgs.config.json (auto-migration).
+ * Routes writes to the correct file based on isLocalKey():
+ *   - Local keys (current_project, planningRoot, v2_hint_shown, sync_hint_shown) -> config.local.json
+ *   - Shared keys (everything else) -> config.json
  *
  * @param {string} cwd - Working directory
  * @param {string} keyPath - Dot-notation key (e.g., "product_name" or "workflow.research")
  * @param {*} value - Value to set
- * @returns {object} Updated config object
+ * @returns {object} Updated merged config object
  */
 function writeConfigField(cwd, keyPath, value) {
-  const readPath = getConfigPath(cwd, 'read');
-  let config = {};
-  try {
-    if (fs.existsSync(readPath)) {
-      config = JSON.parse(fs.readFileSync(readPath, 'utf-8'));
+  // Attempt migration if needed
+  const sharedPath = getSharedConfigPath(cwd);
+  const localPath = getLocalConfigPath(cwd);
+  if (!fs.existsSync(sharedPath) && !fs.existsSync(localPath)) {
+    _migrateLegacyConfig(cwd);
+  }
+
+  // git.sync is a virtual shorthand -- sets both sync_push and sync_pull in shared config
+  if (keyPath === 'git.sync') {
+    let config = _readJsonSafe(sharedPath);
+    if (!config.git || typeof config.git !== 'object') {
+      config.git = {};
     }
-  } catch {
-    // Start with empty config if parse fails
+    config.git.sync_push = value;
+    config.git.sync_pull = value;
+    _writeJson(sharedPath, config);
+    // Return merged config
+    const local = _readJsonSafe(localPath);
+    return { ...config, ...local };
   }
 
+  // Determine target file
+  const targetPath = isLocalKey(keyPath) ? localPath : sharedPath;
+  let targetConfig = _readJsonSafe(targetPath);
+
+  // Set the value using dot-notation
   const keys = keyPath.split('.');
-  let current = config;
+  let current = targetConfig;
   for (let i = 0; i < keys.length - 1; i++) {
     const key = keys[i];
     if (current[key] === undefined || typeof current[key] !== 'object') {
@@ -237,9 +423,12 @@ function writeConfigField(cwd, keyPath, value) {
   }
   current[keys[keys.length - 1]] = value;
 
-  const writePath = getConfigPath(cwd, 'write');
-  fs.writeFileSync(writePath, JSON.stringify(config, null, 2), 'utf-8');
-  return config;
+  _writeJson(targetPath, targetConfig);
+
+  // Return merged config for backward compat
+  const shared = _readJsonSafe(sharedPath);
+  const local = _readJsonSafe(localPath);
+  return { ...shared, ...local };
 }
 
 /**
@@ -360,8 +549,8 @@ function checkConfigGitignore(cwd) {
 }
 
 /**
- * Ensure config files and review-keys.json are in .gitignore.
- * Appends entries for dgs.config.json, config.json, and review-keys.json if not already present.
+ * Ensure config.local.json and review-keys.json are in .gitignore.
+ * config.json is TRACKED (shared settings), so it is NOT added to .gitignore.
  *
  * @param {string} cwd - Working directory
  * @returns {object} { added: boolean, reason?: string }
@@ -378,22 +567,21 @@ function ensureConfigGitignored(cwd) {
     // If unreadable, start fresh
   }
 
-  // Check if already present (either legacy or new name)
+  // Check if already present
   const lines = content.split('\n').map((l) => l.trim());
-  const hasLegacy = lines.some((line) => line === '.planning/config.json');
-  const hasNew = lines.some((line) => line === '.planning/dgs.config.json' || line === 'dgs.config.json');
+  const hasLocalConfig = lines.some((line) => line === 'config.local.json' || line === '.planning/config.local.json');
   const hasReviewKeys = lines.some((line) => line === 'review-keys.json' || line === '.planning/review-keys.json');
 
-  if (hasLegacy && hasNew && hasReviewKeys) {
+  if (hasLocalConfig && hasReviewKeys) {
     return { added: false, reason: 'already_present' };
   }
 
   // Append missing entries
   let entry = '';
-  if (!hasNew || !hasLegacy) {
-    entry += '\n# DGS config (contains API keys)\n';
-    if (!hasNew) entry += 'dgs.config.json\n';
-    if (!hasLegacy) entry += '.planning/config.json\n';
+  if (!hasLocalConfig) {
+    entry += '\n# DGS local config (per-machine state)\n';
+    entry += 'config.local.json\n';
+    entry += '.planning/config.local.json\n';
   }
   if (!hasReviewKeys) {
     entry += '\n# DGS review keys (contains API keys)\n';
@@ -405,7 +593,11 @@ function ensureConfigGitignored(cwd) {
 }
 
 module.exports = {
+  LOCAL_KEYS,
   getConfigPath,
+  getSharedConfigPath,
+  getLocalConfigPath,
+  isLocalKey,
   getReviewKeysPath,
   cmdConfigEnsureSection,
   cmdConfigSet,

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

@@ -67,9 +67,6 @@ function safeReadFile(filePath) {
 
 function loadConfig(cwd) {
   const root = getPlanningRoot(cwd);
-  const newConfigPath = path.join(root, 'dgs.config.json');
-  const legacyConfigPath = path.join(root, 'config.json');
-  const configPath = fs.existsSync(newConfigPath) ? newConfigPath : legacyConfigPath;
   const defaults = {
     model_profile: 'balanced',
     commit_docs: true,
@@ -78,6 +75,8 @@ function loadConfig(cwd) {
     phase_branch_template: 'dgs/{project}/phase-{phase}-{slug}',
     milestone_branch_template: 'dgs/{project}/{milestone}-{slug}',
     base_branch: 'main',
+    sync_push: 'off',
+    sync_pull: 'off',
     research: true,
     plan_checker: true,
     verifier: true,
@@ -85,16 +84,55 @@ function loadConfig(cwd) {
     brave_search: false,
   };
 
+  // Read shared config (config.json)
+  let shared = {};
+  const sharedPath = path.join(root, 'config.json');
   try {
-    const raw = fs.readFileSync(configPath, 'utf-8');
-    const parsed = JSON.parse(raw);
+    if (fs.existsSync(sharedPath)) {
+      shared = JSON.parse(fs.readFileSync(sharedPath, 'utf-8'));
+    }
+  } catch { /* ignore */ }
+
+  // Read local config (config.local.json)
+  let local = {};
+  const localPath = path.join(root, 'config.local.json');
+  try {
+    if (fs.existsSync(localPath)) {
+      local = JSON.parse(fs.readFileSync(localPath, 'utf-8'));
+    }
+  } catch { /* ignore */ }
 
+  // Fall back to legacy dgs.config.json if neither new file exists
+  let hasNewConfig = Object.keys(shared).length > 0 || Object.keys(local).length > 0;
+  if (!hasNewConfig) {
+    const legacyPath = path.join(root, 'dgs.config.json');
+    try {
+      if (fs.existsSync(legacyPath)) {
+        shared = JSON.parse(fs.readFileSync(legacyPath, 'utf-8'));
+        hasNewConfig = true;
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (!hasNewConfig) {
+    return { ...defaults, current_project: null, v2_hint_shown: false, sync_hint_shown: false };
+  }
+
+  // Merge: local overrides shared for overlapping keys
+  const parsed = { ...shared, ...local };
+
+  try {
     // Migrate deprecated "depth" key to "granularity" with value mapping
     if ('depth' in parsed && !('granularity' in parsed)) {
       const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' };
       parsed.granularity = depthToGranularity[parsed.depth] || parsed.depth;
       delete parsed.depth;
-      try { fs.writeFileSync(configPath, JSON.stringify(parsed, null, 2), 'utf-8'); } catch {}
+      // Write back to shared config if that's where depth was
+      if ('depth' in shared) {
+        shared.granularity = parsed.granularity;
+        delete shared.depth;
+        try { fs.writeFileSync(sharedPath, JSON.stringify(shared, null, 2), 'utf-8'); } catch {}
+      }
     }
 
     const get = (key, nested) => {
@@ -120,18 +158,21 @@ function loadConfig(cwd) {
       phase_branch_template: get('phase_branch_template', { section: 'git', field: 'phase_branch_template' }) ?? defaults.phase_branch_template,
       milestone_branch_template: get('milestone_branch_template', { section: 'git', field: 'milestone_branch_template' }) ?? defaults.milestone_branch_template,
       base_branch: get('base_branch', { section: 'git', field: 'base_branch' }) ?? defaults.base_branch,
+      sync_push: get('sync_push', { section: 'git', field: 'sync_push' }) ?? defaults.sync_push,
+      sync_pull: get('sync_pull', { section: 'git', field: 'sync_pull' }) ?? defaults.sync_pull,
+      sync_hint_shown: get('sync_hint_shown', { section: 'git', field: 'sync_hint_shown' }) ?? false,
       research: get('research', { section: 'workflow', field: 'research' }) ?? defaults.research,
       plan_checker: get('plan_checker', { section: 'workflow', field: 'plan_check' }) ?? defaults.plan_checker,
       verifier: get('verifier', { section: 'workflow', field: 'verifier' }) ?? defaults.verifier,
       parallelization,
       brave_search: get('brave_search') ?? defaults.brave_search,
       model_overrides: parsed.model_overrides || null,
-      // v2 fields — passed through directly from config
+      // v2 fields -- passed through directly from config (now from config.local.json)
       current_project: get('current_project') ?? null,
       v2_hint_shown: get('v2_hint_shown') ?? false,
     };
   } catch {
-    return { ...defaults, current_project: null, v2_hint_shown: false };
+    return { ...defaults, current_project: null, v2_hint_shown: false, sync_hint_shown: false };
   }
 }