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

package/src/cli/runtime-commands.js

@@ -0,0 +1,281 @@
+'use strict';
+// The runtime verbs (design §4.2) — dispatch only.
+//
+// Every verb's own implementation — `scaffold`, `classify`, `workflow`, `route`, `claim`,
+// `context-pack`, `verify` and `recover` — lives in its engine module under src/runtime/ and is
+// imported below; this file only forwards parsed CLI arguments to it, exactly as the verb-table
+// doctrine requires: one implementation per verb, one table that names them. `bin/doflow.js`
+// forwards here from src/cli/index.js; nothing outside src/runtime/ implements a verb.
+//
+// Uniform contract, shared by every one of those handlers: `--json` prints the library's own
+// object, unmodified; exit 0 = answered, 1 = a finding the caller must act on, 2 = the CLI could
+// not do what was asked (a missing or unusable argument, or input the library cannot resolve). No
+// handler ever converts a library's own status into a different one, and none of them substitutes
+// a default for an identity the library refuses to guess.
+//
+// Guard note: test/guards/reachability.test.js and test/guards/runtime-unification.test.js parse
+// this switch — each case written as the single expression `case '<name>': return
+// handle<Name>Command(...)` — to cross-check the dispatcher's verb table in both directions. Keep
+// every case in exactly that shape.
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const {
+  handleCapabilitiesCommand, handleReadinessCommand, handleEvidenceCommand,
+} = require('../runtime/cli.js');
+// `doctor` comes from the health module rather than src/runtime/cli.js: the health-probe report
+// (FR-013) supersedes the presence-check version, and one verb must have one implementation.
+const { handleDoctorCommand } = require('../runtime/health.js');
+const { handleTraceCommand, handleStatsCommand, handleDiscoverCommand, resolveRunsLocation } = require('../runtime/trace/ledger.js');
+const { handleIndicatorsCommand } = require('../runtime/trace/indicators.js');
+// The rest of the verb surface design §4.2 declares. `classify`, `workflow`, `route`, `claim`,
+// `context-pack`, `verify`, `recover` and `scaffold` each have exactly one implementation, in the
+// engine module named on the right; this file only dispatches to them.
+const { ReadinessEngine } = require('../runtime/readiness.js');
+const { handleClaimCommand } = require('../runtime/claims.js');
+const { handleClassifyCommand } = require('../runtime/task-classifier.js');
+const { handleWorkflowCommand } = require('../runtime/workflow-engine.js');
+const { handleOrchestrateCommand } = require('../runtime/workflow-orchestrator.js');
+const { handleResearchRequestCommand } = require('../runtime/research-request.js');
+const { handleTaskAttemptCommand } = require('../runtime/task-attempts.js');
+const { handleRetrieveCommand } = require('../runtime/knowledge/retrieval.js');
+const { handleModelRoleCommand } = require('../runtime/model-router.js');
+const { handleRouteCommand } = require('../runtime/capability-router.js');
+const { handleContextPackCommand } = require('../runtime/context-pack.js');
+const { handleRetrievalPlanCommand } = require('../runtime/retrieval-plan.js');
+const { handleOutcomeCommand } = require('../runtime/outcome.js');
+const { handleVerifyCommand } = require('../runtime/verification/engine.js');
+const { handleLeakScanCommand } = require('../runtime/leak-scan.js');
+const { handleRecoverCommand } = require('../runtime/recovery.js');
+const { handleScaffoldCommand } = require('../runtime/scaffold/generate.js');
+const { handleDecisionCommand } = require('../runtime/decision-register.js');
+const { handleFollowupCommand, handleLifecycleCommand, handleGoalCommand } = require('../runtime/lifecycle/cli.js');
+const { projectRoot: lifecycleProjectRoot } = require('../runtime/lifecycle/root.js');
+const { upkeepAfterVerb } = require('../runtime/storage/upkeep.js');
+const { handleStorageCommand } = require('../runtime/storage/cli.js');
+// Required on first use, so a CLI whose failure modules cannot be loaded still runs every other verb.
+function handleFailureCommand(options     )      { return require('../runtime/failure/cli.js').handleFailureCommand(options); }
+const { handleInventoryCommand } = require('../runtime/inventory/index.js');
+const { finishRuntime, usageError } = require('../runtime/cli-result.js');
+const { setDefaultSlug, invalidSlugRefusal, slugNamesNoFeature } = require('../runtime/task-scope.js');
+const { listCheckouts } = require('../runtime/checkouts.js');
+const { featureSlugFor } = require('../runtime/implementation-gate.js');
+const { handleBriefToolsCommand } = require('../runtime/brief-tools.js');
+const { handleAdviseCommand } = require('../runtime/advice/cli.js');
+const { REPO_ROOT, buildAdapterRegistry } = require('./shared.js');
+
+/** Where `readiness`/`evidence` read and write per-task state. Mirrors scopeOf()'s rules so these
+ * commands are scope-aware like the rest of the CLI, rather than defaulting to the DoFlow install
+ * directory — which for an npm install is inside node_modules/. */
+function evidenceRoot(o     )         {
+  return o.global ? os.homedir() : path.resolve(o.positional[0] || '.');
+}
+
+/**
+ * The task class the caller named, or exit 2 naming the valid set.
+ *
+ * `readiness` previously read `o.taskClass || 'feature'`. That is the identity defect readiness.ts
+ * fixed this morning, reinstated one layer up: omitting `--task-class` produced a confident
+ * READY/NEEDS_EVIDENCE verdict computed from the wrong contract, and nothing in the output said so.
+ * The valid set comes from the readiness registry rather than a list written here, so it cannot
+ * drift from the templates that actually exist.
+ */
+function requireTaskClass(o     )         {
+  if (typeof o.taskClass === 'string' && o.taskClass.trim() !== '') return o.taskClass;
+  let valid = '';
+  try {
+    valid = ` Valid: ${Object.keys(new ReadinessEngine({ repoRoot: REPO_ROOT }).templates).join(', ')}.`;
+  } catch { /* the registry is unreadable; the missing argument is still the thing to report */ }
+  usageError(o.cmd, `--task-class is required — the contract is per class, so guessing one would grade the wrong task.${valid}`, o.json);
+  process.exit(2);
+}
+
+/** The task id the caller named, or exit 2. Same reasoning as requireTaskClass. */
+function requireTaskId(o     )         {
+  if (typeof o.taskId === 'string' && o.taskId.trim() !== '') return o.taskId;
+  usageError(o.cmd, '--task-id is required — evidence and claims belong to one task, so guessing an id would report on a different one.', o.json);
+  process.exit(2);
+}
+
+/**
+ * The single-item spelling of an evidence write, assembled from exactly the flags the caller gave.
+ *
+ * Absent flags stay absent. Filling a gap here with 'unknown'/'general' would move the omission out
+ * of the caller's error message and into the stored record, where it reads as a measurement.
+ */
+function evidenceItemFromFlags(o     )      {
+  const item      = {};
+  if (o.kind !== undefined) item.kind = o.kind;
+  if (o.provenance !== undefined) item.provenance = o.provenance;
+  if (o.locator !== undefined) item.locator = o.locator;
+  if (o.content !== undefined) item.content = o.content;
+  if (o.establishes !== undefined) item.establishes = o.establishes;
+  // Both halves of an observation travel together; a lone half must reach the write boundary as
+  // the partial object it is, so the refusal names the missing field instead of dropping the pair.
+  if (o.observedCommand !== undefined || o.observedExit !== undefined) {
+    item.observation = {};
+    if (o.observedCommand !== undefined) item.observation.command = o.observedCommand;
+    if (o.observedExit !== undefined) item.observation.exitCode = o.observedExit;
+  }
+  const source      = {};
+  if (o.provider !== undefined) source.provider = o.provider;
+  if (o.capability !== undefined) source.capability = o.capability;
+  if (Object.keys(source).length > 0) item.source = source;
+  return item;
+}
+
+/** Verbs that read or write per-task records, and so accept `--slug` (IC-002). */
+const TASK_STORE_VERBS = new Set(['evidence', 'claim', 'readiness', 'context-pack', 'research-request', 'outcome', 'retrieval-plan']);
+
+/** Verbs that build a task's readiness: run from a linked worktree whose feature folder lives only
+ * in the main checkout, they keep the task's records there, beside the folder their evidence names. */
+const FEATURE_STORE_VERBS = new Set(['evidence', 'claim', 'readiness']);
+
+/**
+ * The main checkout, when `o` runs one of FEATURE_STORE_VERBS in a linked worktree that lacks the
+ * task's feature folder and the main checkout holds it; null otherwise. The feature is `--slug`,
+ * else the branch's. A locator such as `agent-docs/doflow/<slug>/plan.md` resolves only there, and
+ * the readiness record written there is the one verify, orchestrate and the edit hook read from
+ * the worktree.
+ */
+function featureStoreRoot(o     )                                        {
+  if (!FEATURE_STORE_VERBS.has(o.cmd) || o.global) return null;
+  const checkouts = listCheckouts({ cwd: evidenceRoot(o) });
+  if (!checkouts.isLinked) return null;
+  const slug = featureSlugFor({ projectRoot: checkouts.current, slug: o.slug });
+  const folder = (root        ) => path.join(root, 'agent-docs', 'doflow', slug || '');
+  if (!slug || fs.existsSync(folder(checkouts.current)) || !fs.existsSync(folder(checkouts.main))) return null;
+  return { root: checkouts.main, slug };
+}
+
+/**
+ * Forward one parsed invocation to its runtime verb's implementation, or exit 1 naming an unknown
+ * command. Argument shaping stays here (requireTaskClass/requireTaskId/evidenceItemFromFlags
+ * validate parsed CLI arguments, which is the CLI's job, not a library's); everything else belongs
+ * to the engine module each case names.
+ */
+function dispatchRuntimeCommandInner(o     , moment     )      {
+  // A slug becomes a directory name and a state key, so one that could name a path is refused
+  // here, once, for every verb that reads `--slug`, before any of them reads or writes state
+  // (FR-013, IC-009). A well-formed slug that names no feature is the verbs' own business.
+  const refusal = invalidSlugRefusal(o.slug);
+  if (refusal) {
+    if (o.json) console.log(JSON.stringify(refusal, null, 2));
+    else console.error(`doflow ${o.cmd}: ${refusal.error}: ${refusal.message}`);
+    return finishRuntime(2);
+  }
+  // `--slug` names the feature a task-store verb's records belong to (task-scope.js). Set once
+  // here so the verbs whose handlers build their own ledger (readiness, evidence) route the same
+  // way as the ones that take `slug` directly. The orchestration journal is keyed by slug already.
+  // Reset on every dispatch, so one invocation's slug can never carry into the next in-process call.
+  const featureStore = featureStoreRoot(o);
+  const storeRoot = featureStore ? featureStore.root : evidenceRoot(o);
+  // Use the same root resolver as the handler: task redirection, the nearest run ledger,
+  // and lifecycle's shared main-worktree store are deliberately different scopes.
+  try {
+    if (['trace', 'stats', 'discover'].includes(o.cmd)) {
+      moment.projectRoot = path.dirname(resolveRunsLocation({ start: evidenceRoot(o), global: o.global }).configDir);
+    } else if (['followup', 'lifecycle', 'goal', 'task-attempt'].includes(o.cmd)) {
+      moment.projectRoot = lifecycleProjectRoot(evidenceRoot(o));
+    } else {
+      moment.projectRoot = storeRoot;
+    }
+  } catch { /* a failed upkeep lookup must not change the verb's answer */ }
+  const storeSlug = featureStore ? featureStore.slug : o.slug;
+  setDefaultSlug(TASK_STORE_VERBS.has(o.cmd) ? storeSlug : null);
+  if (featureStore) {
+    console.error(`doflow ${o.cmd}: note: feature '${storeSlug}' lives in the main checkout ${storeRoot}; this task's records are read and written there`);
+  }
+  // A well-formed slug that names no feature changes nothing (the records go to the shared task
+  // store), but the caller typed it expecting an effect, so say so once, on stderr only.
+  if (!featureStore && TASK_STORE_VERBS.has(o.cmd) && typeof o.slug === 'string' && o.slug !== ''
+    && slugNamesNoFeature({ projectRoot: evidenceRoot(o), slug: o.slug })) {
+    console.error(`doflow ${o.cmd}: note: --slug '${o.slug}' names no feature; using the shared task store`);
+  }
+  switch (o.cmd) {
+    // REPO_ROOT locates the capability registry; projectRoot is the tree whose index freshness
+    // and build/test commands are being reported on, which follows the usual scope rules.
+    case 'capabilities': return handleCapabilitiesCommand({ json: o.json, check: o.check, repoRoot: REPO_ROOT });
+    case 'doctor': return handleDoctorCommand({ json: o.json, repoRoot: REPO_ROOT, projectRoot: evidenceRoot(o), adapters: buildAdapterRegistry() });
+    // REPO_ROOT locates the registry (templates ship with the package); stateRoot locates the
+    // caller's evidence, which follows the same scope rules as every other command: -g means
+    // $HOME, otherwise the positional project root (default cwd).
+    // `o.taskClass || 'feature'` and `o.taskId || 'default'` used to sit here. Both re-created
+    // the identity defect readiness.ts fails closed on: omitting either argument produced a
+    // confident verdict about a task or a contract the caller never named. Required now, and the
+    // valid class set is named in the refusal.
+    // The task-profile arguments are the caller's own statements and are forwarded only when
+    // given. They exist because without them no readiness template can ever reach READY —
+    // every one of the five has at least one requirement satisfied from the profile rather
+    // than from evidence, so the gate had one reachable answer for every task. Forwarding is
+    // all this does: the handler names them back under `callerAsserted` so a stated input is
+    // never mistaken for a measured one.
+    case 'readiness': return handleReadinessCommand({ taskClass: requireTaskClass(o), taskId: requireTaskId(o), verificationPlan: o.verificationPlan, scopeClear: o.scope, invariants: o.invariants, userDecisionPending: o.userDecisionPending, mode: o.mode, slug: storeSlug, json: o.json, repoRoot: REPO_ROOT, stateRoot: storeRoot });
+    case 'evidence': return handleEvidenceCommand({ taskId: requireTaskId(o), action: o.action, item: evidenceItemFromFlags(o), batchPath: o.batchPath, evidenceId: o.evidenceId, replacedBy: o.replacedBy, json: o.json, repoRoot: REPO_ROOT, stateRoot: storeRoot });
+    // Run-ledger views. They resolve their own ledger the way the dispatcher does (nearest
+    // `.doflow` walking up, or the global one) rather than assuming cwd is the project root, so
+    // a view invoked from a subdirectory reads the runs that were actually recorded.
+    // Exit codes follow design §4.2 and are set by the handler itself: 0 = answered, 1 = a
+    // finding the caller must act on.
+    case 'trace': return handleTraceCommand({ json: o.json, days: o.days, global: o.global, projectRoot: evidenceRoot(o) });
+    case 'stats': return handleStatsCommand({ json: o.json, days: o.days, global: o.global, projectRoot: evidenceRoot(o) });
+    case 'indicators': return handleIndicatorsCommand({ json: o.json, projectRoot: evidenceRoot(o) });
+    case 'discover': return handleDiscoverCommand({ json: o.json, days: o.days, global: o.global, projectRoot: evidenceRoot(o) });
+    // Deliberately NOT evidenceRoot(o): this is the one verb that reads both scopes in one
+    // invocation (IC-001), so the project root is always the positional (default cwd) and never
+    // $HOME, and `-g` is forwarded to be refused by the handler rather than silently narrowing a
+    // report whose whole purpose is to be cross-scope. The global scope's own root is derived from
+    // the process home directory inside the lifecycle view (design R7) and is not an argument.
+    case 'inventory': return handleInventoryCommand({ json: o.json, global: o.global, targets: o.targets, repoRoot: REPO_ROOT, projectRoot: path.resolve(o.positional[0] || '.') });
+    case 'storage': return handleStorageCommand({ action: o.actionGiven ? o.action : 'report', json: o.json, global: o.global, projectRoot: evidenceRoot(o) });
+    // No REPO_ROOT: the scaffold's repo root is the *caller's* repo, reported by the resolver,
+    // because the plan's `files:` paths are relative to it. Passing the DoFlow install here
+    // would detect the wrong language and mirror the wrong tree.
+    case 'scaffold': return handleScaffoldCommand({ json: o.json, projectRoot: evidenceRoot(o), slug: o.slug });
+    // The feature is resolved from the working directory (or --slug) by the same resolver
+    // `scaffold` uses; the flags are the caller's own statements, validated by the register module.
+    case 'decision': return handleDecisionCommand({ action: o.action, projectRoot: evidenceRoot(o), slug: o.slug, json: o.json, flags: { topic: o.topic, statement: o.statement, channel: o.channel, stage: o.stage, rationale: o.rationale, supersedes: o.supersedes, refs: o.refs, source: o.source, batch: o.batchPath, all: o.all } });
+    // Feature 046: the project's follow-up store lives at the repository root (never `-g`, which
+    // the handlers refuse), so the working directory is the starting point, not a scope switch.
+    case 'followup': return handleFollowupCommand({ action: o.actionGiven ? o.action : undefined, cwd: evidenceRoot(o), global: o.global, slug: o.slug, json: o.json, flags: { statement: o.statement, stage: o.stage, source: o.source, taskClass: o.taskClass, taskId: o.taskId, release: o.release, batch: o.batchPath, channel: o.channel, state: o.state, ids: o.ids, as: o.as, reason: o.reason, evidence: o.evidence, title: o.title, file: o.file, stdin: o.stdin, text: o.text, feature: o.feature, tag: o.tag, confirm: o.confirm, exclude: o.exclude } });
+    case 'lifecycle': return handleLifecycleCommand({ action: o.actionGiven ? o.action : undefined, cwd: evidenceRoot(o), global: o.global, slug: o.slug, json: o.json, flags: { take: o.take, intent: o.intent, goal: o.goal, maintain: o.maintain, since: o.since, tag: o.tag, confirm: o.confirm, feature: o.feature, exclude: o.exclude, reason: o.reason, channel: o.channel } });
+    case 'goal': return handleGoalCommand({ action: o.actionGiven ? o.action : undefined, cwd: evidenceRoot(o), global: o.global, slug: o.slug, json: o.json, flags: { goal: o.goal, statement: o.statement, item: o.item, text: o.text, evidence: o.evidence, unmet: o.unmet, replace: o.replace, reason: o.reason, channel: o.channel } });
+    // The failure store is per machine, so `-g` changes nothing and the working directory only matters
+    // to `settle --as imported`, which looks for the DoFlow repository from there.
+    case 'failure': return handleFailureCommand({ action: o.actionGiven ? o.action : undefined, cwd: path.resolve(o.positional[0] || '.'), json: o.json, all: o.all, flags: { fp: o.fp, as: o.as, reason: o.reason, set: o.set } });
+    // The rest of design §4.2's Node arm. REPO_ROOT locates the registries that ship with the
+    // package (workflows, capabilities, verification); evidenceRoot(o) locates the caller's own
+    // state and source tree, following the same scope rules as every other command.
+    case 'classify': return handleClassifyCommand({ taskClass: o.taskClass, rationale: o.rationale, proposedBy: o.proposedBy, callingSkill: o.callingSkill, request: o.request, requestFile: o.requestFile, taskId: o.taskId, projectRoot: evidenceRoot(o), json: o.json });
+    case 'workflow': return handleWorkflowCommand({ taskClass: o.taskClass, json: o.json });
+    case 'orchestrate': return handleOrchestrateCommand({ action: o.action, taskId: o.taskId, taskClass: o.taskClass, stage: o.stage, gate: o.gate, node: o.node, decision: o.decision, note: o.note, reason: o.reason, forced: o.forced, verificationPlan: o.verificationPlan, scope: o.scope, invariants: o.invariants, result: o.result, mcpOutcome: o.mcpOutcome, callingSkill: o.callingSkill, slug: o.slug, json: o.json, repoRoot: REPO_ROOT, stateRoot: evidenceRoot(o), buildAdapters: buildAdapterRegistry });
+    case 'research-request': return handleResearchRequestCommand({ slug: o.slug, action: o.action === 'status' ? 'list' : o.action, taskId: requireTaskId(o), stageId: o.stageId, question: o.question, reason: o.reason, blocking: o.blocking === undefined ? undefined : o.blocking === 'true' ? true : o.blocking === 'false' ? false : o.blocking, requestId: o.requestId, outcome: o.researchOutcome, claimId: o.claimId, evidenceIds: o.evidenceIds, gap: o.gap, json: o.json, projectRoot: evidenceRoot(o) });
+    // The store is shared by every linked worktree of the clone (lifecycle's main-worktree root); the
+    // feature is `--slug`, else the branch's, resolved the way decision and scaffold resolve it.
+    case 'task-attempt': return handleTaskAttemptCommand({ action: o.actionGiven ? o.action : undefined, slug: o.slug, task: o.task, owner: o.owner, mode: o.mode, token: o.token, result: o.result, evidenceId: o.evidenceId, reason: o.reason, json: o.json, cwd: evidenceRoot(o), resolveSlug: (cwd        ) => featureSlugFor({ projectRoot: cwd }) });
+    case 'retrieve': return handleRetrieveCommand({ query: o.query, top: o.top, json: o.json });
+    case 'brief-tools': return handleBriefToolsCommand({ owner: o.owner, tier: o.tier, harness: o.harness, slug: o.slug, headingLevel: o.headingLevel, tasks: o.tasks, json: o.json, repoRoot: REPO_ROOT, projectRoot: storeRoot, buildAdapters: buildAdapterRegistry });
+    case 'advise': return handleAdviseCommand({ action: o.action, actionGiven: o.actionGiven, kind: o.kind, server: o.server, state: o.state, stateFile: o.stateFile, staticAnswer: o.staticAnswer, questionsFile: o.questionsFile, taskId: o.taskId, pickId: o.pickId, actual: o.actual, model: o.model, endpoint: o.endpoint, off: o.off, project: o.project, force: o.force, global: o.global, json: o.json, projectRoot: evidenceRoot(o) });
+    case 'model-role': return handleModelRoleCommand({ role: o.role, exclude: o.exclude, json: o.json, repoRoot: REPO_ROOT });
+    case 'route': return handleRouteCommand({ intent: o.intent, query: o.query, check: o.check, json: o.json, projectRoot: evidenceRoot(o) });
+    case 'claim': return handleClaimCommand({ slug: storeSlug, taskId: requireTaskId(o), action: o.action, statement: o.statement, claimId: o.claimId, evidenceId: o.evidenceId, replacedBy: o.replacedBy, relation: o.relation, role: o.role, json: o.json, stateRoot: storeRoot });
+    case 'context-pack': return handleContextPackCommand({ taskId: requireTaskId(o), taskClass: o.taskClass, objective: o.objective, json: o.json, stateRoot: evidenceRoot(o), slug: o.slug });
+    case 'retrieval-plan': return handleRetrievalPlanCommand({ slug: o.slug, taskId: requireTaskId(o), action: o.action, need: o.need, stage: o.stage, json: o.json, repoRoot: REPO_ROOT, stateRoot: evidenceRoot(o) });
+    case 'outcome': return handleOutcomeCommand({ slug: o.slug, taskId: requireTaskId(o), action: o.action, state: o.state, taskClass: o.taskClass, stage: o.stage, readiness: o.readiness, verification: o.verification, json: o.json, repoRoot: REPO_ROOT, stateRoot: evidenceRoot(o) });
+    case 'verify': return handleVerifyCommand({ slug: o.slug, taskId: requireTaskId(o), action: o.action, risk: o.risk, planPath: o.planPath, scope: o.scope, verificationInput: o.verificationInput, verificationPhase: o.verificationPhase, baselineRef: o.baselineRef, json: o.json, projectRoot: evidenceRoot(o) });
+    case 'leak-scan': return handleLeakScanCommand({ paths: o.paths, exclude: o.exclude, json: o.json, repoRoot: evidenceRoot(o) });
+    case 'recover': return handleRecoverCommand({ errorMessage: o.errorMessage, failedChecks: o.failedChecks, iteration: o.iteration, agent: o.agent, json: o.json });
+    default: console.error(`doflow: unknown command '${o.cmd}'`); process.exit(1);
+  }
+}
+
+/** Await the verb without changing its return value, output or exit code; usage exits never return. */
+async function dispatchRuntimeCommand(o     )               {
+  const moment      = {};
+  const result = await dispatchRuntimeCommandInner(o, moment);
+  if (o.cmd !== 'storage') upkeepAfterVerb({ projectRoot: moment.projectRoot });
+  return result;
+}
+
+module.exports = { dispatchRuntimeCommand };

package/src/cli/shared.js

@@ -0,0 +1,218 @@
+'use strict';
+// Shared plumbing for the CLI command handlers (src/cli/commands/*) and their dispatch
+// (src/cli/index.js, src/cli/runtime-commands.js). This module owns the facts every command
+// needs: where the package root and the entrypoint directory are, the package version, the ONE
+// adapter-registry factory, and the helpers more than one command uses (scope resolution, MCP
+// selection, backup-table printing). Nothing here is harness-specific — native quirks belong in
+// src/adapters/<id>/.
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { REPO_ROOT } = require('../helper/repo-root.js');
+const { doflowPaths } = require('../install/paths.js');
+const { readInstallManifest } = require('../install/manifest.js');
+const { DEFAULT_BACKUP_RETENTION, formatBytes } = require('../install/backup.js');
+const { stateRoot, readLedger } = require('../state/index.js');
+const { readLock } = require('../state/lockfile.js');
+const { acquireRunLock, RunLockTimeoutError, RunLockError, RunLockLostError } = require('../state/run-lock.js');
+const { createAdapterRegistry } = require('../adapters/index.js');
+const { declaredHarnessPaths } = require('../helper/harness-paths.js');
+const claudeAdapter = require('../adapters/claude/index.js');
+const codexAdapter = require('../adapters/codex/index.js');
+const { createGeminiAdapter } = require('../adapters/gemini/index.js');
+const { createOpenCodeAdapter } = require('../adapters/opencode/index.js');
+const { createPiAdapter } = require('../adapters/pi/index.js');
+const { createCopilotAdapter } = require('../adapters/copilot/index.js');
+const { createKiroAdapter } = require('../adapters/kiro/index.js');
+const { createAntigravityAdapter } = require('../adapters/antigravity/index.js');
+
+// The directory of the `doflow` entrypoint. Derived from the shared package root rather than
+// __dirname so its value survives this code physically moving between directories: manifests,
+// backups and the source-commit lookup all record this exact path (<repo>/bin).
+const SCRIPT_DIR = path.join(REPO_ROOT, 'bin');
+
+// Tolerant because the projected runtime under `.doflow/runtime/` ships bin/, src/ and
+// core/registry/ but no package.json — see the `runtime.*` assets in core/registry/assets.json.
+// A hard require here would make every Node-backed verb fail in an install, which is the exact
+// defect that projection exists to fix. Only version reporting depends on this.
+function loadPkg()      {
+  try { return require('../../package.json'); } catch { return { version: '0.0.0-installed', name: '@khoavu882/doflow' }; }
+}
+const pkg = loadPkg();
+
+/**
+ * The one adapter registry construction, used by install/update/remove/reconcile. There used to
+ * be three inline copies of the same construction (one per mutating command); a fourth variant
+ * once grew in src/lifecycle/view.js and silently fell behind (fixed in 96006da) — which is why
+ * the registry guard pins every declared harness into each call site by parsing them.
+ * Build one here rather than copying the object literal again. Stage 3: each adapter factory
+ * receives its harness's declared native paths from core/registry/harnesses.json, so the CLI
+ * consumes exactly what the loader validates.
+ */
+function buildAdapterRegistry()      {
+  const declared = declaredHarnessPaths();
+  return createAdapterRegistry({
+    claude: claudeAdapter.createClaudeAdapter({ declaredPaths: declared.claude }),
+    codex: codexAdapter.createCodexAdapter({ declaredPaths: declared.codex }),
+    gemini: createGeminiAdapter({ declaredPaths: declared.gemini }),
+    opencode: createOpenCodeAdapter({ declaredPaths: declared.opencode }),
+    pi: createPiAdapter({ declaredPaths: declared.pi }),
+    copilot: createCopilotAdapter({ declaredPaths: declared.copilot }),
+    kiro: createKiroAdapter({ declaredPaths: declared.kiro }),
+    antigravity: createAntigravityAdapter({ declaredPaths: declared.antigravity }),
+  });
+}
+
+/** Resolve {global, projectRoot} scope options for src/install/targets.js#toolDirs from parsed args. */
+function scopeOf(o     )                                           {
+  return { global: o.global, projectRoot: o.positional[0] || '.' };
+}
+
+function installPaths(scope     )      {
+  const scopeRoot = scope.global ? os.homedir() : path.resolve(scope.projectRoot);
+  return doflowPaths({ scopeRoot });
+}
+
+/** Whether two paths name the same directory. Device and inode follow symlinks (macOS reaches
+ * /var through /private/var) and ignore letter case on a case-insensitive volume; a file system
+ * that reports inode 0 falls back to real paths, and paths that do not exist to resolved strings. */
+function sameDirectory(a        , b        , { fsImpl = fs }      = {})          {
+  const ra = path.resolve(a);
+  const rb = path.resolve(b);
+  try {
+    const sa = fsImpl.statSync(ra);
+    const sb = fsImpl.statSync(rb);
+    if (sa.ino !== 0 && sb.ino !== 0) return sa.dev === sb.dev && sa.ino === sb.ino;
+  } catch { /* fall through to real paths */ }
+  try {
+    return fsImpl.realpathSync.native(ra) === fsImpl.realpathSync.native(rb);
+  } catch {
+    return ra === rb;
+  }
+}
+
+/** A project install, update, remove or reconcile rooted at the home directory would share the
+ * global install's files and records, and its remove could delete them. Refuses that run with one
+ * line and exit 1 before anything is read, locked or written; `-g` and every other root pass. */
+function refuseHomeRootedProject(o     , command        )       {
+  if (o.global) return;
+  const projectRoot = o.positional[0] || '.';
+  if (!sameDirectory(projectRoot, os.homedir())) return;
+  const targets = o.targets.length ? ` -t ${o.targets.join(',')}` : '';
+  console.error(`[ERROR] ${path.resolve(projectRoot)} is your home directory: a project ${command} there shares the global install's files and records and can delete them. Nothing was changed. Run: doflow ${command} -g${targets}`);
+  process.exit(1);
+}
+
+/** Takes the scope's run lock for a mutating command, or returns null under --dry-run. A run that
+ * cannot take it prints the one reason line and exits 1 before it has read or changed anything. */
+function holdRunLock(o     , scope     , command        )      {
+  if (o.dryRun) return null;
+  try {
+    return acquireRunLock({ scopeRoot: installPaths(scope).scopeRoot, scope: scope.global ? 'global' : 'project', command });
+  } catch (err) {
+    if (!(err instanceof RunLockTimeoutError || err instanceof RunLockError)) throw err;
+    console.error((err       ).message);
+    process.exit(1);
+  }
+}
+
+/** After the confirm prompt: renews the hold, and exits 1 before the first write if another run
+ * took the lock over while the prompt waited. */
+function checkpointRunLock(hold     )       {
+  if (!hold) return;
+  try {
+    hold.checkpoint();
+  } catch (err) {
+    if (!(err instanceof RunLockLostError)) throw err;
+    console.error((err       ).message);
+    process.exit(1);
+  }
+}
+
+/** Surface a reconciled-away MCP server rather than dropping it silently: the user picked it once,
+ * so its disappearance from their config should be explained, not discovered. */
+function reportRetiredMcp(retired          )       {
+  console.error(`[WARN]  Dropping MCP server(s) no longer in the registry: ${retired.join(', ')}`);
+  console.error('        They were removed from DoFlow; your saved selection is being reconciled.');
+}
+
+/** The scope's doflow.lock, ledger and 1.18.0 manifest MCP list, as the MCP selection functions in
+ * src/install/mcp.js read them. */
+function scopeSelectionState(scope     )      {
+  const scopeRoot = scope.global ? os.homedir() : path.resolve(scope.projectRoot);
+  return {
+    lock: readLock(scope.global ? { scope: 'global', homeDir: scopeRoot } : { scope: 'project', projectRoot: scopeRoot }),
+    ledger: readLedger(stateRoot({ scope: scope.global ? 'global' : 'project', projectRoot: scopeRoot, homeDir: scopeRoot })),
+    manifestServers: readInstallManifest({ scopeRoot })?.mcpServers ?? null,
+  };
+}
+
+const MCP_SOURCE_WORDS = Object.freeze({ flag: '--mcp', prompt: 'prompt', recorded: 'recorded', kept: 'kept', manifest: 'remembered', default: 'default' }                          );
+
+/** The one line a run names its MCP selections in, from what the plan resolved for each harness:
+ * harnesses with the same servers and source share a group, groups follow target order. Prints
+ * nothing when no target takes MCP servers, except that an explicit --mcp is said to do nothing. */
+function printMcpSelection(view     , sources     , { requested, prefix = '[INFO]' }      = {})       {
+  const groups        = [];
+  for (const target of view.plan.targets) {
+    if (target.skipped || !Array.isArray(target.mcpSelected) || !(target.harness in sources)) continue;
+    const ids = target.mcpSelected.join(', ') || 'none';
+    const source = MCP_SOURCE_WORDS[sources[target.harness]];
+    const group = groups.find((item) => item.ids === ids && item.source === source);
+    if (group) group.harnesses.push(target.harness);
+    else groups.push({ harnesses: [target.harness], ids, source });
+  }
+  if (groups.length) {
+    console.log(`${prefix} MCP selection: ${groups.map((group) => `${group.harnesses.join(', ')}: ${group.ids} (${group.source})`).join('; ')}`);
+  } else if (requested) {
+    console.log(`${prefix} MCP: no targeted harness takes MCP servers; --mcp has no effect.`);
+  }
+}
+
+/** Says which MCP entries a run with no native change recorded as DoFlow's (lifecycle
+ * recordMcpOwnership), or, under --dry-run, would record. */
+function printRecordedMcpOwnership(recorded     , { dryRun = false }      = {})       {
+  for (const [harness, ids] of Object.entries     (recorded)) {
+    const what = `${ids.length} MCP ${ids.length === 1 ? 'entry' : 'entries'} (${ids.join(', ')})`;
+    console.log(dryRun ? `[DRY]  ${harness}: would record DoFlow's ownership of ${what}` : `[INFO] ${harness}: recorded DoFlow's ownership of ${what}`);
+  }
+}
+
+/** What each planned harness that takes MCP servers will hold, as doflow.lock records it. */
+function plannedMcpSelections(view     )      {
+  return Object.fromEntries(view.plan.targets.filter((target     ) => !target.skipped && Array.isArray(target.mcpSelected))
+    .map((target     ) => [target.harness, target.mcpSelected]));
+}
+
+/** Total size of some rows, noting when any of them could not be measured. */
+function rowsSize(rows       )         {
+  const total = formatBytes(rows.reduce((sum, r) => sum + (r.bytes ?? 0), 0));
+  return rows.some((r) => r.bytes === null) ? `${total} (some sizes unknown)` : total;
+}
+
+function printBackupTable(rows       , rootLabel        )       {
+  if (rows.length === 0) { console.log(`[INFO] No backups found in ${rootLabel}`); return; }
+  const header = `${'BACKUP ID'.padEnd(42)} ${'OPERATION'.padEnd(14)} ${'TYPE'.padEnd(9)} ${'ORIGIN'.padEnd(9)} ${'SIZE'.padEnd(11)} TIMESTAMP`;
+  console.log(`\n${header}`);
+  console.log('─'.repeat(header.length));
+  for (const r of rows) {
+    const when = r.complete === false ? '- (incomplete: no manifest)' : r.timestamp;
+    console.log(`${r.id.padEnd(42)} ${r.operation.padEnd(14)} ${r.type.padEnd(9)} ${r.origin.padEnd(9)} ${formatBytes(r.bytes).padEnd(11)} ${when}`);
+  }
+  console.log(`\n${rows.length} backup(s) in ${rootLabel}`);
+  const current = rows.filter((r) => r.origin === 'current');
+  const legacy = rows.filter((r) => r.origin === 'legacy');
+  if (current.length) {
+    console.log(`current: ${current.length} backup(s), ${rowsSize(current)}; install and update keep the newest ${DEFAULT_BACKUP_RETENTION} (--prune N)`);
+  }
+  if (legacy.length) {
+    console.log(`legacy: ${legacy.length} backup(s), ${rowsSize(legacy)} in ${[...new Set(legacy.map((r) => r.backupRoot))].join(', ')}; read-only, never pruned`);
+  }
+  console.log('');
+}
+
+module.exports = {
+  REPO_ROOT, SCRIPT_DIR, pkg, buildAdapterRegistry, scopeOf, installPaths, sameDirectory, refuseHomeRootedProject,
+  holdRunLock, checkpointRunLock, reportRetiredMcp, scopeSelectionState, printMcpSelection, printRecordedMcpOwnership, plannedMcpSelections, printBackupTable,
+};

package/src/helper/bash-helper.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+// native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
+// caller's `require('../helper/bash-helper.js')` keeps working while the rest of the tree is still
+// `.js`. The `./repo-root` require stays bare while repo-root is still `.js`; it gains `.ts` in the
+// same slice that converts repo-root.
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('./repo-root.js');
+
+/**
+ * Where a bash helper (`do-paths.sh`, `do-git-state.sh`) is: inside the package (a checkout or a
+ * source install), else projected next to the runtime. An installed runtime lives at
+ * `<install>/.doflow/runtime` and carries only bin/, src/ and core/registry/; the helpers are
+ * projected at `<install>/.doflow/scripts/doflow/bash/`, a sibling of the runtime directory.
+ * The package copy wins when both exist. Null when neither does, which callers report as a
+ * missing install rather than as the question the helper would have answered.
+ * @param name file name under `scripts/doflow/bash/`
+ * @param repoRoot the runtime root; only a test moves it
+ */
+function resolveBashHelper(
+  name        ,
+  repoRoot         = REPO_ROOT,
+  existsImpl                            = fs.existsSync,
+)                {
+  const candidates = [
+    path.join(repoRoot, 'core', 'shared', 'scripts', 'doflow', 'bash', name),
+    path.resolve(repoRoot, '..', 'scripts', 'doflow', 'bash', name),
+  ];
+  return candidates.find((candidate        ) => existsImpl(candidate)) || null;
+}
+
+module.exports = { resolveBashHelper };

package/src/helper/git.js

@@ -0,0 +1,24 @@
+'use strict';
+// git.ts — shared git helpers. Single source of truth for `sourceCommit()`, previously duplicated
+// verbatim in src/install/backup.js, src/install/manifest.js, and src/install/context.js (each ran
+// its own `git rev-parse` — up to 3 spawns per `doflow install` for the same value).
+//
+// First module of the TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md). Authored as `.ts` and
+// run directly by Node's native type-stripping (process.features.typescript === 'strip', Node
+// ^22.18.0 || >=24.3.0), so no build step and no runtime dependency are added. The body stays CommonJS
+// (`module.exports`) so a `require('../helper/git.js')` from a `.js` caller keeps working while the
+// rest of the tree is still `.js`; the explicit `.ts` extension on those requires is what the
+// CommonJS resolver needs to find this file.
+const { execFileSync } = require('node:child_process');
+
+/** Short HEAD commit of the repo at `repoRoot`, or 'unknown' if not a git repo / git unavailable. */
+function sourceCommit(repoRoot        )         {
+  try {
+    return execFileSync('git', ['-C', repoRoot, 'rev-parse', '--short', 'HEAD'], { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString().trim() || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+module.exports = { sourceCommit };

package/src/helper/guardrails.js

@@ -0,0 +1,49 @@
+'use strict';
+
+// DoFlow's destructive-command blocklist has exactly one authored home: the `permissions.deny`
+// array in core/harnesses/claude/settings/settings.json (the projection Claude Code has shipped
+// since the first release). Every other harness's opt-in permission projection DERIVES its
+// entries from that file at plan time rather than restating the list, so the blocklist cannot
+// drift between harnesses.
+//
+// Claude deny rules look like `Bash(<command glob>:*)`; the wrapper syntax is Claude-specific and
+// the inner command glob is what every other harness wants.
+//
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+// native type-stripping (process.features.typescript === 'strip', Node ^22.18.0 || >=24.3.0) — no build step and
+// no runtime dependency. The body stays CommonJS so a `.js` caller's `require('../helper/guardrails.js')`
+// keeps working while the rest of the tree is still `.js`; the explicit `.ts` extension is what the
+// CommonJS resolver needs to find this file.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DENY_RULE = /^Bash\((.*):\*\)$/;
+
+                          
+                                                       
+ 
+
+                                          
+                   
+                          
+ 
+
+/** Read the canonical blocklist as bare command globs, e.g. `git push --force*`. Throws when the
+ * authored file is missing or malformed — a silent empty blocklist would look like success while
+ * projecting no protection at all. */
+function destructiveCommandGlobs({ repoRoot, fsImpl = fs }                                 = {}                                  )           {
+  const file = path.join(repoRoot, 'core', 'harnesses', 'claude', 'settings', 'settings.json');
+  const parsed = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+  const deny = parsed?.permissions?.deny;
+  if (!Array.isArray(deny) || deny.length === 0) {
+    throw new Error(`guardrails: no permissions.deny list in ${file}`);
+  }
+  return deny.map((rule        ) => {
+    const m = DENY_RULE.exec(rule);
+    if (!m) throw new Error(`guardrails: unrecognized deny rule '${rule}' in ${file}`);
+    return m[1];
+  });
+}
+
+module.exports = { destructiveCommandGlobs };