@ktpartners/dgs-platform 2.6.3 → 2.7.0

package/commands/dgs/sync.md

@@ -0,0 +1,70 @@
+---
+name: dgs:sync
+description: "Pull from and push to all registered repos"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# /dgs:sync -- Remote Synchronisation
+
+Sync your planning and code repos with their remotes.
+
+## Usage
+
+```
+/dgs:sync           -- Pull then push all repos
+/dgs:sync pull      -- Pull only (fetch + fast-forward merge)
+/dgs:sync push      -- Push only
+/dgs:sync status    -- Dry-run check (no changes)
+```
+
+## Steps
+
+<step name="determine_operation">
+Parse the user's argument to determine the operation:
+- No argument or "all" -> pull then push
+- "pull" -> pull only
+- "push" -> push only
+- "status" or "dry-run" -> dry-run pull check
+
+Store as `SYNC_OP`.
+</step>
+
+<step name="execute_sync">
+Run the appropriate dgs-tools sync command(s):
+
+**If SYNC_OP is "pull" or "all":**
+```bash
+PULL_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync pull 2>&1)
+echo "$PULL_RESULT"
+```
+
+**If SYNC_OP is "push" or "all":**
+```bash
+PUSH_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync push 2>&1)
+echo "$PUSH_RESULT"
+```
+
+**If SYNC_OP is "status":**
+```bash
+PULL_STATUS=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync pull --dry-run 2>&1)
+PUSH_STATUS=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync push --dry-run 2>&1)
+echo "$PULL_STATUS"
+echo "$PUSH_STATUS"
+```
+</step>
+
+<step name="report">
+Display the results to the user in a clear format:
+- Show per-repo status (updated/pushed/current/skipped/failed)
+- Show summary line
+- If any repo failed, highlight the failure and suggested fix
+- If pre-flight failed, show all problems and suggest --force or manual fixes
+</step>
+
+## Success Criteria
+
+- [ ] Pull and push operations complete across all registered repos
+- [ ] Per-repo results displayed clearly
+- [ ] Failures reported with actionable fix suggestions

package/deliver-great-systems/bin/dgs-tools.cjs

@@ -169,6 +169,15 @@
  *   repos validate-consistency <plan>  Validate <repos>/<files> consistency
  *   repos migrate <slug>              Migrate v1 install to v2 structure
  *
+ * Sync:
+ *   sync pull [--dry-run] [--force]    Pull from all repos (ff-only)
+ *   sync push [--dry-run] [--force]    Push to all repos
+ *     [--repos name1,name2]            Filter to specific repos
+ *   sync workflow-pull <workflow>      Workflow-level pull check/execute
+ *     [--check-only] [--record-yes] [--mark-hint-shown]
+ *   sync workflow-push <workflow>      Workflow-level push check/execute
+ *     [--check-only] [--mid-workflow] [--record-yes]
+ *
  * Ideas Operations:
  *   ideas create --title T --body B     Create new idea with auto-assigned ID
  *     [--tags "t1,t2"]
@@ -246,7 +255,7 @@
  *   init progress                      All context for progress workflow
  */
 
-const { error } = require('./lib/core.cjs');
+const { error, loadConfig } = require('./lib/core.cjs');
 const state = require('./lib/state.cjs');
 const phase = require('./lib/phase.cjs');
 const roadmap = require('./lib/roadmap.cjs');
@@ -269,6 +278,7 @@ const jobs = require('./lib/jobs.cjs');
 const mergeConflicts = require('./lib/merge-conflicts.cjs');
 const conflictAgent = require('./lib/conflict-agent.cjs');
 const { requireGitIdentity, formatAuthorString, cmdIdentityResolve } = require('./lib/identity.cjs');
+const { pullAll, pushAll, getCadence, checkStaleState, shouldShowFirstRunHint, markFirstRunHintShown, isWithinSuppressionWindow, recordPromptYes } = require('./lib/sync.cjs');
 
 // ─── Identity Gate ────────────────────────────────────────────────────────────
 
@@ -288,6 +298,261 @@ function gateIdentity() {
   }
 }
 
+// ─── Sync Commands ────────────────────────────────────────────────────────────
+
+function cmdSyncPull(cwd, raw, args) {
+  const dryRun = args.includes('--dry-run');
+  const force = args.includes('--force');
+
+  const result = pullAll(cwd, { dryRun, force });
+
+  // If pre-flight failed, output problems
+  if (result.problems) {
+    if (!raw) {
+      process.stderr.write('Pre-flight check failed:\n');
+      for (const p of result.problems) {
+        process.stderr.write(`  * ${p.repo}: ${p.issue}\n`);
+        process.stderr.write(`    Fix: ${p.fix}\n`);
+      }
+      process.stderr.write('\nUse --force to skip pre-flight checks.\n');
+    }
+    console.log(JSON.stringify(result));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  // Format results for human-readable output
+  if (!raw) {
+    for (const r of result.results) {
+      const icon = r.status === 'updated' ? '+' : r.status === 'current' ? '.' : r.status === 'skipped' ? '-' : 'x';
+      process.stderr.write(`  ${icon} ${r.repo}: ${r.message}\n`);
+    }
+    process.stderr.write(`\n${result.summary}\n`);
+  }
+
+  console.log(JSON.stringify(result));
+  if (!result.ok) process.exitCode = 1;
+}
+
+function cmdSyncPush(cwd, raw, args) {
+  const dryRun = args.includes('--dry-run');
+  const force = args.includes('--force');
+
+  // Parse --repos flag
+  let repoFilter = null;
+  const reposIdx = args.indexOf('--repos');
+  if (reposIdx !== -1 && args[reposIdx + 1]) {
+    repoFilter = args[reposIdx + 1].split(',').map(r => r.trim()).filter(Boolean);
+  }
+
+  const result = pushAll(cwd, { dryRun, force, repos: repoFilter });
+
+  // If pre-flight failed, output problems
+  if (result.problems) {
+    if (!raw) {
+      process.stderr.write('Pre-flight check failed:\n');
+      for (const p of result.problems) {
+        process.stderr.write(`  * ${p.repo}: ${p.issue}\n`);
+        process.stderr.write(`    Fix: ${p.fix}\n`);
+      }
+      process.stderr.write('\nUse --force to skip pre-flight checks.\n');
+    }
+    console.log(JSON.stringify(result));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  // Format results
+  if (!raw) {
+    for (const r of result.results) {
+      const icon = r.status === 'pushed' ? '+' : r.status === 'current' ? '.' : r.status === 'skipped' ? '-' : 'x';
+      process.stderr.write(`  ${icon} ${r.repo}: ${r.message}\n`);
+    }
+    process.stderr.write(`\n${result.summary}\n`);
+  }
+
+  console.log(JSON.stringify(result));
+  if (!result.ok) process.exitCode = 1;
+}
+
+function cmdSyncHelp(raw) {
+  const result = {
+    command: 'sync',
+    description: 'Pull from and push to all registered repos',
+    subcommands: [
+      { name: 'pull', usage: 'sync pull [--dry-run] [--force]', description: 'Pull from all repos (fetch + ff-only merge)' },
+      { name: 'push', usage: 'sync push [--dry-run] [--force] [--repos name1,name2]', description: 'Push to all repos' },
+      { name: 'workflow-pull', usage: 'sync workflow-pull <workflow> [--check-only] [--record-yes] [--mark-hint-shown]', description: 'Workflow-level pull check or execute' },
+      { name: 'workflow-push', usage: 'sync workflow-push <workflow> [--check-only] [--mid-workflow] [--record-yes]', description: 'Workflow-level push check or execute' },
+    ],
+  };
+  if (raw) {
+    console.log(JSON.stringify(result));
+  } else {
+    process.stderr.write('Usage:\n');
+    for (const s of result.subcommands) {
+      process.stderr.write(`  ${s.usage}\n    ${s.description}\n`);
+    }
+    console.log(JSON.stringify(result));
+  }
+}
+
+function cmdSyncWorkflowPull(cwd, raw, args) {
+  const workflow = args.find(a => !a.startsWith('--'));
+  if (!workflow) {
+    error('Usage: sync workflow-pull <workflow> [--check-only] [--record-yes] [--mark-hint-shown]');
+  }
+
+  const checkOnly = args.includes('--check-only');
+  const doRecordYes = args.includes('--record-yes');
+  const doMarkHint = args.includes('--mark-hint-shown');
+
+  // Handle side-effect-only flags
+  if (doRecordYes) {
+    recordPromptYes('pull');
+    console.log(JSON.stringify({ recorded: true, direction: 'pull' }));
+    return;
+  }
+  if (doMarkHint) {
+    markFirstRunHintShown(cwd);
+    console.log(JSON.stringify({ marked: true }));
+    return;
+  }
+
+  // Load config for sync mode
+  const config = loadConfig(cwd);
+  const syncMode = config.sync_pull || 'off';
+  const cadence = getCadence(workflow);
+
+  if (checkOnly) {
+    // Return status without executing
+    const suppressed = isWithinSuppressionWindow('pull');
+    const stale = cadence.pull && syncMode === 'off' ? checkStaleState(cwd) : { stale: false, commitsBehind: 0, branch: null };
+    const firstRunHint = shouldShowFirstRunHint(cwd) ? 'Tip: Remote detected. Enable sync with /dgs:settings' : null;
+
+    const result = {
+      should_pull: cadence.pull && syncMode !== 'off',
+      mode: syncMode,
+      cadence_pull: cadence.pull,
+      stale,
+      first_run_hint: firstRunHint,
+      suppressed,
+    };
+    console.log(JSON.stringify(result));
+    return;
+  }
+
+  // Execute pull
+  const result = pullAll(cwd, { force: false });
+
+  // Format results for stderr
+  if (!raw) {
+    for (const r of result.results) {
+      const icon = r.status === 'updated' ? '+' : r.status === 'current' ? '.' : r.status === 'skipped' ? '-' : 'x';
+      process.stderr.write(`  ${icon} ${r.repo}: ${r.message}\n`);
+    }
+    if (result.problems) {
+      for (const p of result.problems) {
+        process.stderr.write(`  x ${p.repo}: ${p.issue}\n`);
+      }
+    }
+  }
+
+  // Build diagnosis for failures
+  let diagnosis = null;
+  if (!result.ok) {
+    const failedRepos = result.results?.filter(r => r.status === 'failed') || [];
+    const diag = failedRepos.map(r => `${r.repo}: ${r.message}`).join('; ');
+    const preflightProblems = result.problems?.map(p => `${p.repo}: ${p.issue} -- ${p.fix}`).join('; ');
+    diagnosis = preflightProblems || diag || result.summary;
+  }
+
+  const output = {
+    action: result.ok ? 'pulled' : 'aborted',
+    ok: result.ok,
+    summary: result.summary,
+    diagnosis,
+  };
+  console.log(JSON.stringify(output));
+  if (!result.ok) process.exitCode = 1;
+}
+
+function cmdSyncWorkflowPush(cwd, raw, args) {
+  const workflow = args.find(a => !a.startsWith('--'));
+  if (!workflow) {
+    error('Usage: sync workflow-push <workflow> [--check-only] [--mid-workflow] [--record-yes]');
+  }
+
+  const checkOnly = args.includes('--check-only');
+  const midWorkflow = args.includes('--mid-workflow');
+  const doRecordYes = args.includes('--record-yes');
+
+  // Handle side-effect-only flags
+  if (doRecordYes) {
+    recordPromptYes('push');
+    console.log(JSON.stringify({ recorded: true, direction: 'push' }));
+    return;
+  }
+
+  // Load config for sync mode
+  const config = loadConfig(cwd);
+  const syncMode = config.sync_push || 'off';
+  const cadence = getCadence(workflow);
+
+  if (checkOnly) {
+    const suppressed = isWithinSuppressionWindow('push');
+    const result = {
+      should_push: cadence.push && syncMode !== 'off',
+      mode: syncMode,
+      cadence_push: cadence.push,
+      suppressed,
+    };
+    console.log(JSON.stringify(result));
+    return;
+  }
+
+  // Determine retry count based on mode
+  const maxRetries = midWorkflow ? (syncMode === 'auto' ? 3 : 1) : 0;
+
+  // Execute push with retries
+  let lastResult;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    lastResult = pushAll(cwd, { force: true }); // force: bypass preflight (already committed)
+    if (lastResult.ok) break;
+    if (!midWorkflow) break;
+  }
+
+  // Format results for stderr
+  if (!raw) {
+    for (const r of lastResult.results) {
+      const icon = r.status === 'pushed' ? '+' : r.status === 'current' ? '.' : r.status === 'skipped' ? '-' : 'x';
+      process.stderr.write(`  ${icon} ${r.repo}: ${r.message}\n`);
+    }
+  }
+
+  // Build summary
+  const totalCommits = lastResult.results.reduce((sum, r) => sum + (r.commits || 0), 0);
+  const repoCount = lastResult.results.filter(r => r.status === 'pushed').length;
+  let summaryMsg = lastResult.summary;
+
+  if (lastResult.ok && repoCount > 0) {
+    if (repoCount > 1) {
+      summaryMsg = `Pushed ${totalCommits} commit${totalCommits !== 1 ? 's' : ''} across ${repoCount} repos`;
+    } else if (totalCommits > 0) {
+      summaryMsg = `Pushed ${totalCommits} commit${totalCommits !== 1 ? 's' : ''}`;
+    }
+  }
+
+  const output = {
+    action: lastResult.ok ? 'pushed' : 'warning',
+    ok: lastResult.ok,
+    summary: summaryMsg,
+    message: lastResult.ok ? summaryMsg : `Warning: push failed. Work saved locally.`,
+  };
+  console.log(JSON.stringify(output));
+  if (!lastResult.ok) process.exitCode = 1;
+}
+
 // ─── CLI Router ───────────────────────────────────────────────────────────────
 
 async function main() {
@@ -852,13 +1117,13 @@ async function main() {
           init.cmdInitAuditPhase(cwd, args[2], raw);
           break;
         case 'phase-op':
-          init.cmdInitPhaseOp(cwd, args[2], raw);
+          init.cmdInitPhaseOp(cwd, args[2], raw, args[3] || null);
           break;
         case 'todos':
-          init.cmdInitTodos(cwd, args[2], raw);
+          init.cmdInitTodos(cwd, args[2], raw, args[3] || null);
           break;
         case 'milestone-op':
-          init.cmdInitMilestoneOp(cwd, raw);
+          init.cmdInitMilestoneOp(cwd, raw, args[2] || null);
           break;
         case 'map-codebase': {
           const onlyIdx = args.indexOf('--only');
@@ -1436,6 +1701,27 @@ async function main() {
       break;
     }
 
+    case 'sync': {
+      const syncSub = args[1];
+      switch (syncSub) {
+        case 'pull':
+          cmdSyncPull(cwd, raw, args.slice(2));
+          break;
+        case 'push':
+          cmdSyncPush(cwd, raw, args.slice(2));
+          break;
+        case 'workflow-pull':
+          cmdSyncWorkflowPull(cwd, raw, args.slice(2));
+          break;
+        case 'workflow-push':
+          cmdSyncWorkflowPush(cwd, raw, args.slice(2));
+          break;
+        default:
+          cmdSyncHelp(raw);
+      }
+      break;
+    }
+
     default:
       error(`Unknown command: ${command}`);
   }