@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/src/cli/commands/reconcile.ts

@@ -0,0 +1,120 @@
+'use strict';
+// `doflow reconcile` — converge observed state onto the doflow.lock pin: report drift, then heal
+// it on confirmation. Never re-prompts for MCP; selections ride exactly as pinned.
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const { toolDirs } = require('../../install/targets.ts');
+const { resolveContext, printContext } = require('../../install/context.ts');
+const { writeManifest } = require('../../install/manifest.ts');
+const { confirm } = require('../../helper/prompt.ts');
+const { sourceCommit } = require('../../helper/git.ts');
+const { loadRegistry } = require('../../registry/index.ts');
+const { applyLifecycle, recordMcpOwnership } = require('../../lifecycle/index.ts');
+const {
+  registryLifecycleView, assertSafeRegistryPlan,
+} = require('../../lifecycle/view.ts');
+const { recordedMcpSelections } = require('../../install/mcp.ts');
+const {
+  REPO_ROOT, SCRIPT_DIR, pkg, scopeOf, installPaths, scopeSelectionState, printRecordedMcpOwnership, buildAdapterRegistry,
+  refuseHomeRootedProject, holdRunLock, checkpointRunLock,
+} = require('../shared.ts');
+
+/** Classify desired-vs-observed drift for one lifecycle view. The plan IS the diff: its changes
+ * are the operations needed to converge, its conflicts and prerequisites are the drift that must
+ * not be silently healed. */
+function reconcileReport(view: any): any {
+  const drifts = [];
+  const perHarness = new Map();
+  for (const target of view.plan.targets) {
+    if (target.skipped) continue;
+    const entry: any = { create: 0, update: 0, remove: 0 };
+    for (const change of target.changes) {
+      if (entry[change.operation] !== undefined) entry[change.operation] += 1;
+      drifts.push({ harness: target.harness, operation: change.operation, assetId: change.assetId, target: change.target });
+    }
+    perHarness.set(target.harness, entry);
+  }
+  return {
+    drifts,
+    conflicts: view.plan.conflicts,
+    prerequisites: view.plan.prerequisites,
+    perHarness: Object.fromEntries(perHarness),
+    clean: drifts.length === 0 && view.plan.conflicts.length === 0,
+  };
+}
+
+function printReconcileReport(report: any, lock: any): void {
+  console.log(`[INFO] Reconciling against doflow.lock (sourceVersion ${lock.sourceVersion ?? 'unknown'})`);
+  for (const [harness, counts] of Object.entries<any>(report.perHarness)) {
+    const total = counts.create + counts.update + counts.remove;
+    console.log(`[INFO] ${harness}: ${total === 0 ? 'clean' : `${total} drift(s) (${counts.create} create, ${counts.update} update, ${counts.remove} remove)`}`);
+  }
+  for (const conflict of report.conflicts) console.log(`[CONFLICT] ${conflict.harness}: ${conflict.reason}`);
+  for (const prerequisite of report.prerequisites) console.log(`[PENDING-TRUST] ${prerequisite.harness}: ${prerequisite.prerequisite}`);
+  if (report.clean) console.log('[OK] Observed state matches doflow.lock.');
+}
+
+function cmdReconcile(o: any): void {
+  refuseHomeRootedProject(o, 'reconcile');
+  const scope = scopeOf(o);
+  const hold = holdRunLock(o, scope, 'reconcile');
+  try {
+    const dirs = toolDirs(scope);
+    const lifecyclePaths = installPaths(scope);
+    const { lock, ledger, manifestServers } = scopeSelectionState(scope);
+    // A harness the ledger holds but the lock does not pin is installed and outside reconcile's reach.
+    // Said, not converged: the lock records choices, and reconcile has no choice to record for it.
+    const pinned = new Set((lock?.targets ?? []).map((entry: any) => entry.harness));
+    const unpinned = [...new Set((ledger?.resources ?? []).map((resource: any) => resource.harness))].filter((harness) => !pinned.has(harness)).sort();
+    for (const harness of unpinned) {
+      const count = ledger.resources.filter((resource: any) => resource.harness === harness).length;
+      console.log(`[WARN] ${harness}: installed (ledger holds ${count} resource(s)) but absent from doflow.lock; reconcile does not converge it.`);
+    }
+    if (!lock || !lock.targets.length) {
+      // Reconcile converges onto what install pinned; with no pin there is no desired state to
+      // converge to, and guessing one from the registry would silently adopt targets the user
+      // never chose.
+      console.log('[INFO] No doflow.lock in this scope — nothing pinned to reconcile against. Run `doflow install` first.');
+      return;
+    }
+    const targets = lock.targets.map((entry: any) => entry.harness);
+    const registry = loadRegistry({ repoRoot: REPO_ROOT });
+    printContext(resolveContext({ repoRoot: REPO_ROOT, targets, dirs, sourceCommit: sourceCommit(SCRIPT_DIR), ...scope }));
+    // Each harness converges onto its own pinned selection — reconcile never re-prompts and never
+    // lends one harness's servers to another.
+    const recorded = recordedMcpSelections({ registry, lock, ledger, targets, manifestServers });
+    const lifecycleView = registryLifecycleView({ registry, repoRoot: REPO_ROOT, scope, dirs, targets,
+      mcpSelections: recorded.selections, mcpAdoptable: recorded.adoptable, retainedMcpIds: [], force: true });
+    if (!lifecycleView.plan.safe) { assertSafeRegistryPlan(lifecycleView); return; }
+
+    const report = reconcileReport(lifecycleView);
+    printReconcileReport(report, lock);
+    if (o.json) console.log(JSON.stringify({ scope: lock.scope, sourceVersion: lock.sourceVersion, targets, unpinned, ...report }, null, 2));
+    if (o.dryRun) {
+      console.log('[DRY] Reconcile plan complete — no changes written');
+      if (!report.clean) process.exitCode = 1; // CI-friendly: drifted check must fail loudly.
+      return;
+    }
+    if (report.clean) {
+      // Converged already; an entry the plan finds DoFlow's without writing it still needs its row.
+      const owned = recordMcpOwnership({ plan: lifecycleView.plan, registry: lifecycleView.registry, adapters: lifecycleView.adapters,
+        stateRoot: lifecycleView.stateRoot, ledger: lifecycleView.ledger });
+      printRecordedMcpOwnership(owned.recorded);
+      return;
+    }
+
+    if (!confirm(`Reconcile ${targets.join(', ')} by applying ${report.drifts.length} change(s)?`, o.force)) {
+      console.error('[INFO]  Aborted.');
+      process.exit(1);
+    }
+    checkpointRunLock(hold);
+    applyLifecycle({ plan: lifecycleView.plan, registry: lifecycleView.registry,
+      adapters: buildAdapterRegistry(),
+      stateRoot: lifecycleView.stateRoot, ledger: lifecycleView.ledger });
+    writeManifest({ scopeRoot: lifecyclePaths.scopeRoot, scriptVersion: pkg.version, operation: 'update', repoRoot: SCRIPT_DIR, sourceCommit: sourceCommit(SCRIPT_DIR), backupId: '', tools: targets, date: new Date() });
+    console.log('[OK] Reconciliation complete — state converged onto doflow.lock.');
+  } finally {
+    hold?.release();
+  }
+}
+
+module.exports = cmdReconcile;

package/src/cli/commands/remove.ts

@@ -0,0 +1,82 @@
+'use strict';
+// `doflow remove` — remove only lifecycle-owned native resources; user-owned files are preserved
+// and what remains standing (shared destinations) is reported, not implied.
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const os = require('node:os');
+const path = require('node:path');
+const { resolveTargets, toolDirs } = require('../../install/targets.ts');
+const { confirm } = require('../../helper/prompt.ts');
+const { loadRegistry } = require('../../registry/index.ts');
+const { storageForgetScope } = require('../../runtime/storage/upkeep.ts');
+const { removeLifecycle, retentionSummary } = require('../../lifecycle/index.ts');
+const {
+  codexScope, registryLifecycleView, printRegistryLifecycle, LIFECYCLE_HARNESSES,
+  assertSafeRegistryPlan, lockDocument, recordLock,
+} = require('../../lifecycle/view.ts');
+const { recordedMcpSelections } = require('../../install/mcp.ts');
+const {
+  REPO_ROOT, scopeOf, scopeSelectionState, buildAdapterRegistry, refuseHomeRootedProject, holdRunLock, checkpointRunLock,
+} = require('../shared.ts');
+
+function cmdRemove(o: any): void {
+  refuseHomeRootedProject(o, 'remove');
+  const targets = resolveTargets(o.targets);
+  const scope = scopeOf(o);
+  const hold = holdRunLock(o, scope, 'remove');
+  try {
+    const dirs = toolDirs(scope);
+    const lifecycleTargets = targets.filter((t: string) => LIFECYCLE_HARNESSES.includes(t));
+    if (!lifecycleTargets.length) {
+      console.log('[INFO] No lifecycle-owned native resources selected; legacy compatibility assets are never broadly removed.');
+      return;
+    }
+    const registry = loadRegistry({ repoRoot: REPO_ROOT });
+    // Read before the removal rewrites the ledger: an entry DoFlow wrote before it kept MCP rows is
+    // removed only while it still equals DoFlow's own rendering.
+    const { lock, ledger, manifestServers } = scopeSelectionState(scope);
+    // No selection: every removed harness's MCP selection is none, so it removes what it owns. The
+    // harnesses that stay keep their recorded servers in the MCP index.
+    const { adoptable: mcpAdoptable, retainedMcpIds } = recordedMcpSelections({ registry, lock, ledger, targets: lifecycleTargets, manifestServers });
+    const view = registryLifecycleView({ registry, repoRoot: REPO_ROOT, scope, dirs, targets: lifecycleTargets, mcpAdoptable, retainedMcpIds, operation: 'remove',
+      permissions: o.permissions === true, statusline: o.statusline === true });
+    if (!view.plan.safe) { assertSafeRegistryPlan(view); return; }
+    if (o.dryRun) {
+      printRegistryLifecycle(view, '[DRY]');
+      console.log('[DRY] Remove plan complete — no changes written');
+      return;
+    }
+    if (!confirm(`Remove DoFlow-owned native resources for: ${lifecycleTargets.join(', ')}? User-owned files are preserved.`, o.force)) {
+      // Exit 1, not 0: a declined prompt is a decision, and it must not share an exit code with a
+      // completed run. With no stdin the prompt auto-declines, so `doflow install <path>` in a script
+      // or CI step printed "Aborted.", wrote zero files, and reported success. It also silently
+      // corrupted a set of install-timing measurements during the D.4 sweep, which is how it surfaced.
+      console.error('[INFO]  Aborted.');
+      process.exit(1);
+    }
+    checkpointRunLock(hold);
+    const result = removeLifecycle({ registry: view.registry,
+      adapters: buildAdapterRegistry(),
+      scope: codexScope(scope), scopeRoot: scope.global ? os.homedir() : path.resolve(scope.projectRoot),
+      targets: lifecycleTargets, mcpAdoptable, retainedMcpIds, stateRoot: view.stateRoot, ledger: view.ledger,
+      context: view.plan.targets[0].adapterInput.context });
+    // Shared destinations (one .doflow/scripts tree for claude/codex/gemini, one .agents for
+    // gemini/copilot) mean a removal can legitimately leave files standing. Saying only "removed"
+    // would be half the truth, so what was kept and who still claims it is printed, not implied.
+    for (const line of retentionSummary(result.retained)) console.log(`[INFO] ${line}`);
+    console.log(`[OK] Removed ${result.ledger.resources.length === 0 ? 'all' : 'eligible'} native resource(s) for ${lifecycleTargets.join(', ')}; ${result.ledger.resources.length} owned record(s) remain.`);
+
+    // Re-pin what still stands: every harness the ledger still holds keeps its pin and its recorded
+    // selection, a removed harness with nothing left leaves the lock, and the lock goes only when no
+    // harness remains. Shared destinations are handled naturally — their claims belong to whichever
+    // harness still holds them in the ledger.
+    const next = lockDocument({ registry, scope: codexScope(scope), scopeRoot: scope.global ? os.homedir() : path.resolve(scope.projectRoot),
+      previous: lock, ledger: result.ledger });
+    const removalLock = recordLock(scope.global ? { scope: 'global', homeDir: os.homedir() } : { scope: 'project', projectRoot: path.resolve(scope.projectRoot) }, next);
+    if (lock || next) console.log(`[INFO] doflow.lock: ${removalLock.summary}`);
+    if (lock && !next) storageForgetScope({ scope: scope.global ? 'global' : 'project', scopeRoot: scope.global ? os.homedir() : path.resolve(scope.projectRoot) });
+  } finally {
+    hold?.release();
+  }
+}
+
+module.exports = cmdRemove;

package/src/cli/commands/rollback.ts

@@ -0,0 +1,172 @@
+'use strict';
+// `doflow rollback` — restore from a backup (interactive pick when the id is omitted). Works out the
+// whole restore first, then snapshots exactly the files it will overwrite (regardless of
+// --no-backup), then restores. A per-file backup restores every file it holds unless --target
+// narrows it, and the ledger rows of exactly the files it restores; a backup from an earlier DoFlow
+// restores per tool, as it always did.
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const path = require('node:path');
+const { resolveTargets, toolDirs } = require('../../install/targets.ts');
+const { resolveContext, printContext } = require('../../install/context.ts');
+const {
+  BackupError, createFileBackup, planRestore, executeRestore, listBackups, formatBytes,
+} = require('../../install/backup.ts');
+const { backupSetFromPaths } = require('../../install/backup-set.ts');
+const { writeManifest } = require('../../install/manifest.ts');
+const { stateRoot, ledgerPath } = require('../../state/index.ts');
+const { confirm, promptLine } = require('../../helper/prompt.ts');
+const { sourceCommit } = require('../../helper/git.ts');
+const { captureCaught } = require('../../runtime/cli-result.ts');
+const {
+  REPO_ROOT, SCRIPT_DIR, pkg, installPaths, printBackupTable, holdRunLock, checkpointRunLock,
+} = require('../shared.ts');
+
+const LISTED_ABSENT = 10;
+
+function fail(error: any): void {
+  captureCaught(error, 'rollback', 1);
+  console.error(`[ERROR] ${error.message}`);
+  console.error('[ERROR] Use --list-backups to see available backups');
+  process.exit(1);
+}
+
+function cmdRollback(o: any): void {
+  const targets = resolveTargets(o.targets);
+  const dirs = toolDirs({ global: o.global, projectRoot: '.' });
+  const scope = { global: o.global, projectRoot: '.' };
+  const hold = holdRunLock(o, scope, 'rollback');
+  try {
+    const scopeName = o.global ? 'global' : 'project';
+    const lifecyclePaths = installPaths(scope);
+    const backupRoot = lifecyclePaths.backupRoot;
+    const commit = sourceCommit(SCRIPT_DIR);
+    const explicitTargets = o.targets.length > 0;
+
+    let bid = o.positional[0] || '';
+    if (!bid) {
+      printBackupTable(listBackups(backupRoot), backupRoot);
+      bid = promptLine('Enter backup ID to restore (or press Enter to cancel): ');
+      if (!bid) { console.error('[INFO]  Aborted.'); process.exit(1); }
+    }
+
+    // Worked out before anything is written. Reads only, so a bad id fails here, before the prompt.
+    let plan: any;
+    try {
+      const neutralStateRoot = stateRoot({ scope: scopeName, projectRoot: lifecyclePaths.scopeRoot, homeDir: lifecyclePaths.scopeRoot });
+      plan = planRestore({ bid, backupRoot, scope: scopeName, scopeRoot: lifecyclePaths.scopeRoot, targets, explicitTargets, dirs,
+        ledgerFile: ledgerPath(neutralStateRoot) });
+    } catch (error) {
+      fail(error);
+    }
+    // A per-file backup restores the harnesses it holds (only those in --target when given), so the
+    // banner and the install manifest name those, not the default target.
+    const restoredTools = plan.format === 2
+      ? [...new Set(plan.restore.flatMap((item: any) => item.harnesses))].filter((h) => !explicitTargets || targets.includes(h)).sort()
+      : targets;
+    printContext(resolveContext({ repoRoot: REPO_ROOT, targets: restoredTools, dirs, sourceCommit: commit, global: o.global, projectRoot: '.' }));
+
+    // PARITY-with-UX: install/update skip the confirm prompt entirely under --dry-run (nothing
+    // destructive happens, so there's nothing to confirm) — rollback used to prompt regardless of
+    // --dry-run, which meant a non-interactive `doflow rollback <id> --dry-run` (no --force) would
+    // block on stdin instead of just previewing. Match install/update's convention here.
+    if (!o.dryRun && !confirm(`Restore from '${bid}'? This overwrites your current config.`, o.force)) {
+      // Exit 1, not 0: a declined prompt is a decision, and it must not share an exit code with a
+      // completed run. With no stdin the prompt auto-declines, so `doflow install <path>` in a script
+      // or CI step printed "Aborted.", wrote zero files, and reported success. It also silently
+      // corrupted a set of install-timing measurements during the D.4 sweep, which is how it surfaced.
+      console.error('[INFO]  Aborted.');
+      process.exit(1);
+    }
+    checkpointRunLock(hold);
+
+    if (plan.format === 1 && plan.type === 'full') {
+      for (const { tool, dstDir } of plan.v1.tools) {
+        console.error(`[INFO]  ${bid} is a whole-home archive from an earlier DoFlow; restoring ${tool}.tar.gz into ${dstDir}`);
+      }
+    }
+
+    snapshotBeforeRestore({ o, plan, bid, backupRoot, lifecyclePaths, scopeName, commit });
+
+    let result: any;
+    try {
+      result = executeRestore(plan, { backupRoot, dryRun: o.dryRun });
+    } catch (error) {
+      fail(error);
+    }
+
+    const writeRollbackManifest = () => writeManifest({ scopeRoot: lifecyclePaths.scopeRoot, scriptVersion: pkg.version, operation: 'rollback',
+      repoRoot: SCRIPT_DIR, sourceCommit: commit, backupId: bid, tools: restoredTools, date: new Date(), dryRun: o.dryRun });
+    if (result.legacy) {
+      writeRollbackManifest();
+      console.log(o.dryRun ? '[DRY] Dry run complete' : `[OK] Rollback to '${bid}' complete!`);
+      return;
+    }
+
+    if (result.untargeted > 0) console.error(`[INFO]  Skipped ${result.untargeted} file(s) of harnesses not in --target`);
+    const left = result.absent.length;
+    if (left > 0) {
+      console.error(`[INFO]  Left in place ${left} file(s) that did not exist when the backup was taken:`);
+      for (const file of result.absent.slice(0, LISTED_ABSENT)) console.error(`        ${file}`);
+      if (left > LISTED_ABSENT) {
+        console.error(`        ... and ${left - LISTED_ABSENT} more (listed with "existed": false in ${path.join(plan.bkDir, '.manifest.json')})`);
+      }
+    }
+    const problems = [...result.refused, ...result.failed];
+    for (const problem of problems) console.error(`[ERROR] Could not restore ${problem.path}: ${problem.reason}`);
+    const restored = result.restored.length;
+
+    if (o.dryRun) {
+      console.log(`[DRY]  Would restore ${restored} file(s), leave ${left} in place, could not restore ${problems.length}`);
+      console.log('[DRY] Dry run complete');
+      return;
+    }
+    if (problems.length > 0) {
+      console.error(`[ERROR] Rollback to '${bid}' incomplete: restored ${restored}, could not restore ${problems.length}`);
+      process.exit(1);
+    }
+    writeRollbackManifest();
+    console.log(`[OK] Rollback to '${bid}' complete: restored ${restored} file(s)${left > 0 ? `, left ${left} in place` : ''}`);
+  } finally {
+    hold?.release();
+  }
+}
+
+/** A backup of exactly the files the restore will overwrite, taken regardless of --no-backup:
+ * rollback is destructive enough that skipping it is not offered. Skipped when the restore
+ * overwrites nothing, so an empty snapshot never pushes a real restore point out of retention. */
+function snapshotBeforeRestore({ o, plan, bid, backupRoot, lifecyclePaths, scopeName, commit }: any): void {
+  if (o.dryRun) {
+    console.log(`[DRY]  Would snapshot ${plan.snapshot.length} file(s) before restoring`);
+    return;
+  }
+  const nothing = '[INFO]  Pre-rollback snapshot: nothing to snapshot (the restore overwrites no file)';
+  if (plan.snapshot.length === 0) {
+    console.error(nothing);
+    return;
+  }
+  console.error('[INFO]  Creating pre-rollback safety snapshot...');
+  let snapshot;
+  try {
+    const neutralStateRoot = stateRoot({ scope: scopeName, projectRoot: lifecyclePaths.scopeRoot, homeDir: lifecyclePaths.scopeRoot });
+    const set = backupSetFromPaths({
+      items: plan.snapshot, scope: scopeName, scopeRoot: lifecyclePaths.scopeRoot,
+      exclude: [backupRoot, neutralStateRoot, lifecyclePaths.manifestPath, path.join(lifecyclePaths.doflowRoot, 'doflow.lock')],
+      // A backup restores the ledger rows of its files (backup.ts mergeRestoredLedger), so the
+      // snapshot of what the restore overwrites holds the current ledger too.
+      records: [ledgerPath(neutralStateRoot)],
+    });
+    snapshot = createFileBackup({ operation: 'pre-rollback', set, backupRoot, repoRoot: SCRIPT_DIR, sourceCommit: commit,
+      version: pkg.version, date: new Date(), restores: bid });
+  } catch (error: any) {
+    if (!(error instanceof BackupError)) throw error;
+    console.error(`[ERROR] Pre-rollback snapshot failed, nothing was restored: ${error.message}`);
+    process.exit(1);
+  }
+  if (!snapshot) {
+    console.error(nothing);
+    return;
+  }
+  console.error(`[INFO]  Pre-rollback snapshot: ${snapshot.id} (${snapshot.files} file(s), ${formatBytes(snapshot.bytes)})`);
+}
+
+module.exports = cmdRollback;

package/src/cli/commands/self-update.ts

@@ -0,0 +1,33 @@
+'use strict';
+// `doflow self-update` — git fetch/pull the checkout, then re-run the install path so the
+// installed trees match the freshly pulled source.
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const { execFileSync } = require('node:child_process');
+const { REPO_ROOT } = require('../shared.ts');
+const cmdInstall = require('./install.ts');
+
+function cmdSelfUpdate(o: any): void {
+  console.log('[INFO] Self-update: checking for upstream changes...');
+  let pulled = false;
+  let fetchOk = false;
+  try {
+    execFileSync('git', ['-C', REPO_ROOT, 'fetch', '--depth=1', 'origin'], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 10000 });
+    fetchOk = true;
+  } catch {
+    console.error('[WARN]  git fetch failed (offline or no remote configured) — installing from current HEAD');
+  }
+  if (fetchOk) {
+    try {
+      execFileSync('git', ['-C', REPO_ROOT, 'pull', '--ff-only'], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 10000 });
+      pulled = true;
+      const commit = execFileSync('git', ['-C', REPO_ROOT, 'rev-parse', '--short', 'HEAD']).toString().trim();
+      console.log(`[INFO] Updated to commit: ${commit}`);
+    } catch {
+      console.error('[WARN]  Fast-forward not possible — using current local state');
+    }
+  }
+  console.log(`[INFO] Running install (after ${pulled ? 'a git pull' : 'checking for updates'})...`);
+  cmdInstall(o);
+}
+
+module.exports = cmdSelfUpdate;

package/src/cli/commands/status.ts

@@ -0,0 +1,138 @@
+'use strict';
+// `doflow status` — resolved context plus installed state from the manifest, with per-harness
+// lifecycle verification. Must stay usable even when the local registry is invalid (--json for
+// scripting).
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const path = require('node:path');
+const { resolveTargets, toolDirs } = require('../../install/targets.ts');
+const { resolveContext, printContext } = require('../../install/context.ts');
+const { readInstallManifest } = require('../../install/manifest.ts');
+const { sourceCommit } = require('../../helper/git.ts');
+const { loadRegistry, mcpCapable } = require('../../registry/index.ts');
+const { recordedMcpSelections } = require('../../install/mcp.ts');
+const { pinnedSelections } = require('../../state/lockfile.ts');
+const { readLedger } = require('../../state/index.ts');
+const { verifyLifecycle } = require('../../lifecycle/index.ts');
+const { registryLifecycleView, LIFECYCLE_HARNESSES } = require('../../lifecycle/view.ts');
+const { REPO_ROOT, SCRIPT_DIR, installPaths, scopeOf, scopeSelectionState } = require('../shared.ts');
+
+function cmdStatus(o: any): void {
+  const targets = resolveTargets(o.targets);
+  const scope = scopeOf(o);
+  const dirs = toolDirs(scope);
+  const lifecyclePaths = installPaths(scope);
+  const ctx: any = resolveContext({ repoRoot: REPO_ROOT, targets, dirs, sourceCommit: sourceCommit(SCRIPT_DIR), ...scope });
+  const manifest = readInstallManifest({ scopeRoot: lifecyclePaths.scopeRoot });
+  let registryView: any = null;
+  // Per MCP-capable target, the servers doflow.lock records for it, or null when it records none.
+  let mcpSelections: any = null;
+  try {
+    const registry = loadRegistry({ repoRoot: REPO_ROOT });
+    const { lock, ledger, manifestServers } = scopeSelectionState(scope);
+    const recorded = recordedMcpSelections({ registry, lock, ledger, targets, manifestServers });
+    const rows = pinnedSelections(lock);
+    mcpSelections = Object.fromEntries(targets.filter((harness: string) => mcpCapable(registry, harness))
+      .map((harness: string) => [harness, rows[harness] ?? null]));
+    registryView = registryLifecycleView({ registry, repoRoot: REPO_ROOT, scope, dirs, targets,
+      mcpSelections: recorded.selections, mcpAdoptable: recorded.adoptable, retainedMcpIds: recorded.retainedMcpIds });
+    ctx.registry = {
+      directory: registryView.registry.directory,
+      versions: registryView.registry.versions,
+      stateRoot: registryView.stateRoot,
+      ledgerPresent: Boolean(readLedger(registryView.stateRoot)),
+      plan: { changes: registryView.plan.changes.length, conflicts: registryView.plan.conflicts, prerequisites: registryView.plan.prerequisites },
+    };
+    // Per-harness status must derive from that harness's own plan target, not the flattened
+    // registryView.plan.changes/conflicts across every target — otherwise, e.g., Codex having
+    // pending changes when it isn't installed yet would make Claude's line falsely report
+    // 'drift-or-pending-change' even though Claude itself has nothing pending.
+    const harnessPlan = (harness: string) => registryView.plan.targets.find((target: any) => target.harness === harness);
+    // Hook-wiring status needs the same general per-harness verification every install/update run
+    // already flows through (src/lifecycle's verifyLifecycle) rather than a Codex-only hardcode:
+    // it is the one place that can tell 'installed and active' apart from 'installed but pending a
+    // prerequisite' (Codex's unreviewed trust, Gemini's live hook-trust check) from 'absent'.
+    const verification = verifyLifecycle({ plan: registryView.plan, adapters: registryView.adapters, context: { registry } });
+    const hooksFor = (harness: string) => verification.verifications.find((item: any) => item.harness === harness)?.hookWiring ?? null;
+    const harnessStatus = (harness: string) => {
+      const target = harnessPlan(harness);
+      if (!target) return { status: 'verified', resources: [], errors: [], hooks: hooksFor(harness) };
+      const resources = registryView.ledger.resources.filter((resource: any) => resource.harness === harness);
+      // A conflict is reported first: a user-owned file in the way is not the same as nothing being
+      // installed. With no conflict, a harness the ledger owns nothing of was never installed: its
+      // whole plan is pending, which is not drift from an installation that does not exist.
+      return {
+        status: target.conflicts.length ? 'conflict-or-invalid'
+          : !resources.length ? 'not-installed'
+            : (target.changes.length ? 'drift-or-pending-change' : 'verified'),
+        resources,
+        errors: target.conflicts,
+        hooks: hooksFor(harness),
+      };
+    };
+    // Every lifecycle-wired harness gets the same per-harness status treatment — not just the
+    // four that historically had it — so 'doflow status --target copilot/opencode/pi --json'
+    // reports 'verified'/'conflict-or-invalid' instead of silently omitting the harness.
+    for (const harness of LIFECYCLE_HARNESSES) {
+      if (targets.includes(harness)) ctx[harness] = harnessStatus(harness);
+    }
+  } catch (error: any) {
+    // Status must remain usable for an existing installation even if a local registry is invalid.
+    ctx.registry = { status: 'invalid', error: error.message };
+  }
+
+  if (o.json) {
+    console.log(JSON.stringify({ context: ctx, manifest, codex: ctx.codex ?? null, mcpSelections }, null, 2));
+    return;
+  }
+
+  const hookLine = (label: string, hooks: any) => {
+    if (!hooks || hooks.status === 'absent') return null;
+    const prereqSuffix = hooks.prerequisites.length ? ` (unmet: ${hooks.prerequisites.join(', ')})` : '';
+    return `  ${label} hooks: ${hooks.status}${prereqSuffix}`;
+  };
+
+  printContext(ctx);
+  if (!manifest) {
+    console.log("[WARN] No install manifest found — run 'doflow install' to get started");
+    return;
+  }
+
+  console.log('\nInstall Status');
+  console.log(`  Last operation:       ${manifest.operation}`);
+  console.log(`  Last run:             ${manifest.lastRun}`);
+  console.log(`  Source commit:        ${manifest.sourceCommit}`);
+  console.log(`  Last backup ID:       ${manifest.backupId}`);
+  console.log(`  Script version:       ${manifest.scriptVersion}`);
+  if (mcpSelections && Object.keys(mcpSelections).length) {
+    const recordedText = (ids: any) => (ids === null ? 'not recorded' : ids.join(', ') || 'none');
+    console.log(`  MCP selections:       ${Object.entries(mcpSelections).map(([harness, ids]) => `${harness} ${recordedText(ids)}`).join('; ')}`);
+  }
+  // Printed in the same order LIFECYCLE_HARNESSES declares, so every wired harness gets a line —
+  // not just the four that historically had a hand-written block — with Codex keeping its extra
+  // capability-gap line since that note is Codex-specific, not a general per-harness property.
+  for (const harness of LIFECYCLE_HARNESSES) {
+    const status = ctx[harness];
+    if (!status) continue;
+    const label = `${harness.charAt(0).toUpperCase()}${harness.slice(1)}`;
+    console.log(`  ${`${label} verification:`.padEnd(24)}${status.status}`);
+    console.log(`  ${`${label} resources:`.padEnd(24)}${status.resources.length} manifest-owned`);
+    const line = hookLine(label, status.hooks);
+    if (line) console.log(line);
+    if (status.errors.length) console.log(`  ${`${label} issues:`.padEnd(24)}${status.errors.join('; ')}`);
+    if (harness === 'codex') {
+      console.log('  Codex capability gaps: no Claude-only event emulation is installed; review docs/capability-map.md#codex-capability-detail');
+    }
+  }
+  if (ctx.registry) {
+    console.log(`  Registry lifecycle:   ${ctx.registry.status === 'invalid' ? ctx.registry.error : `${ctx.registry.plan.changes} pending, ${ctx.registry.plan.conflicts.length} conflict(s)`}`);
+    if (ctx.registry.status !== 'invalid') console.log(`  Neutral state:         ${ctx.registry.stateRoot}${ctx.registry.ledgerPresent ? ' (ledger present)' : ' (not yet created)'}`);
+  }
+  console.log('\n  TOOL         STATUS         LAST UPDATED');
+  for (const tool of LIFECYCLE_HARNESSES) {
+    const t = manifest.tools[tool];
+    const status = t?.installed ? 'installed' : 'not installed';
+    console.log(`  ${tool.padEnd(12)} ${status.padEnd(14)} ${t?.last_updated ?? 'never'}`);
+  }
+}
+
+module.exports = cmdStatus;

package/src/cli/commands/tools.ts

@@ -0,0 +1,92 @@
+'use strict';
+// `doflow tools` — inspect or manage registered external tools (status/install/update/uninstall).
+// --force is deliberately unavailable: every mutation gets its own confirmation.
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const { confirm, promptLine } = require('../../helper/prompt.ts');
+const { loadRegistry } = require('../../registry/index.ts');
+const { commandText, planToolLifecycle, executeToolLifecycle } = require('../../install/tool-lifecycle.ts');
+const { REPO_ROOT } = require('../shared.ts');
+
+function selectExternalTools(registry: any, o: any): any[] {
+  let requested = o.tools;
+  if (!requested) {
+    const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+    if (!interactive) throw new Error("doflow tools: --tool is required when stdin is not an interactive terminal");
+    const answer = promptLine('Select tools (rtk, graphify; comma-separated): ');
+    requested = answer.split(',').map((item: string) => item.trim()).filter(Boolean);
+  }
+  if (!requested.length) throw new Error('doflow tools: select at least one tool');
+  const available = new Set(registry.externalTools.map((tool: any) => tool.id));
+  const unknown = [...new Set(requested)].filter((id) => !available.has(id));
+  if (unknown.length) throw new Error(`doflow tools: unknown tool id(s): ${unknown.join(', ')}; expected: ${[...available].join(', ')}`);
+  const wanted = new Set(requested);
+  return registry.externalTools.filter((tool: any) => wanted.has(tool.id));
+}
+
+function toolJsonResults(plan: any, execution: any = null): any[] {
+  const executed = new Map((execution?.results || []).map((result: any) => [result.tool, result]));
+  return plan.tools.map((item: any) => ({
+    tool: item.tool.id,
+    state: item.state,
+    inspections: item.inspections,
+    prerequisites: item.prerequisites.map((prerequisite: any) => ({ name: prerequisite.name, available: prerequisite.available })),
+    action: item.action,
+    result: executed.get(item.tool.id) ?? (item.action.applicable
+      ? { tool: item.tool.id, status: 'not-attempted', command: [...item.action.command] }
+      : { tool: item.tool.id, status: 'skipped', reason: item.action.reason }),
+  }));
+}
+
+function cmdTools(o: any): void {
+  if (o.force) throw new Error("doflow tools: --force is not supported; each lifecycle command requires its own confirmation");
+  if (!['status', 'install', 'update', 'uninstall'].includes(o.action)) {
+    throw new Error(`doflow tools: unsupported action '${o.action}'; expected: status, install, update, uninstall`);
+  }
+  const registry = loadRegistry({ repoRoot: REPO_ROOT });
+  const tools = selectExternalTools(registry, o);
+  const plan = planToolLifecycle({ registry: { ...registry, externalTools: tools }, action: o.action });
+
+  if (o.dryRun) {
+    if (!o.json) {
+      console.log(`[DRY] External-tool ${o.action} plan:`);
+      for (const item of plan.tools) {
+        if (item.action.applicable) console.log(`[DRY]  ${item.tool.id}: ${commandText(item.action.command)}`);
+        else console.log(`[DRY]  ${item.tool.id}: skipped (${item.action.reason})`);
+      }
+      console.log('[DRY] Dry run complete — no lifecycle commands executed');
+    }
+    if (o.json) console.log(JSON.stringify({ action: o.action, dryRun: true, results: toolJsonResults(plan) }, null, 2));
+    return;
+  }
+
+  if (o.action === 'status') {
+    if (o.json) {
+      console.log(JSON.stringify({ action: o.action, dryRun: false, results: toolJsonResults(plan) }, null, 2));
+      return;
+    }
+    for (const item of plan.tools) {
+      console.log(`${item.tool.displayName}: ${item.state}${item.action.reason ? ` (${item.action.reason})` : ''}`);
+    }
+    return;
+  }
+
+  const execution = executeToolLifecycle({
+    plan,
+    displayCommand: (command: string[], tool: any) => console.error(`[INFO]  ${tool.displayName}: ${commandText(command)}`),
+    confirmCommand: (command: string[], tool: any, action: string) => confirm(`Run ${tool.displayName} ${action}: ${commandText(command)}?`, false),
+  });
+  // Keep processing independent tools so the user receives every outcome, but make a confirmed
+  // command failure visible to scripts and CI through the process result as well as the report.
+  const hasFailures = execution.results.some((result: any) => result.status === 'failed');
+  if (o.json) {
+    console.log(JSON.stringify({ action: o.action, dryRun: false, results: toolJsonResults(plan, execution) }, null, 2));
+    if (hasFailures) process.exitCode = 1;
+    return;
+  }
+  for (const result of execution.results) {
+    console.log(`${result.tool}: ${result.status}${result.reason ? ` (${result.reason})` : ''}`);
+  }
+  if (hasFailures) process.exitCode = 1;
+}
+
+module.exports = cmdTools;