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

package/src/install/context.js

@@ -0,0 +1,58 @@
+'use strict';
+// context.js — resolved-scope/properties view, shown by `install --dry-run` and `status`.
+// Purpose: once install targets can be $HOME (global) OR a project path, it stops being obvious
+// at a glance which one a given invocation resolves to — this makes that explicit for debugging.
+//
+// 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('../install/context.js')` keeps working while the tree is still `.js`.
+const path = require('node:path');
+const { sourceCommit: gitSourceCommit } = require('../helper/git.js');
+
+                               
+                   
+                  
+                      
+                    
+                               
+                        
+                              
+ 
+
+/**
+ * `sourceCommit` lets a caller (bin/doflow.js) pass an already-resolved commit instead of this
+ * module spawning its own `git rev-parse`; omit it to resolve here (e.g. tests calling this module
+ * directly). Returns a plain properties object (used by both the text and --json renderers).
+ */
+function resolveContext({ repoRoot, global, projectRoot, targets, dirs, sourceCommit, managedResources }                     )      {
+  const context      = {
+    scope: global ? 'global' : 'project',
+    scopeRoot: global ? path.dirname(dirs.claude) : path.resolve(projectRoot),
+    targets,
+    dirs: Object.fromEntries(targets.map((t) => [t, dirs[t]])),
+    repoRoot,
+    sourceCommit: sourceCommit ?? gitSourceCommit(repoRoot),
+    nodeVersion: process.version,
+  };
+  // The lifecycle engine may provide its ownership ledger for status/verify output. Do not add
+  // an empty field for existing callers: their JSON/text output remains backwards compatible.
+  if (managedResources !== undefined) context.managedResources = managedResources;
+  return context;
+}
+
+/** Human-readable "Resolved context" block, printed to stderr (keeps stdout clean like sync.sh's log()). */
+function printContext(ctx     )       {
+  const lines = [
+    '[CONTEXT] Resolved install context',
+    `  scope         : ${ctx.scope}  (root: ${ctx.scopeRoot})`,
+    `  targets       : ${ctx.targets.join(', ')}`,
+    ...ctx.targets.map((t        ) => `    ${t.padEnd(7)}-> ${ctx.dirs[t]}`),
+    `  repo root     : ${ctx.repoRoot}`,
+    `  source commit : ${ctx.sourceCommit}`,
+    `  node          : ${ctx.nodeVersion}`,
+  ];
+  if (ctx.managedResources !== undefined) lines.push(`  managed resources: ${ctx.managedResources.length}`);
+  console.error(lines.join('\n'));
+}
+
+module.exports = { resolveContext, printContext };

package/src/install/manifest.js

@@ -0,0 +1,145 @@
+'use strict';
+// manifest.js — port of sync.sh's write_manifest/read_manifest.
+// PARITY: schema {script_version,last_operation,last_run,source_path,source_commit,last_backup_id,
+// tools:{tool:{installed,last_updated}}}; atomic write via tmp file + rename (never partial-write
+// the manifest, matching sync.sh's `mktemp` + `mv`).
+//
+// 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('../install/manifest.js')` keeps working while the tree is still `.js`.
+const fs = require('node:fs');
+const path = require('node:path');
+const { sourceCommit: gitSourceCommit } = require('../helper/git.js');
+
+// Explicit migration bridge: pre-registry installations stored this record beneath .claude.
+// Lifecycle commands use the scope-neutral .doflow location; only the neutral-state importer
+// calls the legacy reader below.
+const LEGACY_MANIFEST_FILE_NAME = '.install-manifest.json';
+const MANIFEST_FILE_NAME = LEGACY_MANIFEST_FILE_NAME;
+
+function manifestPath(claudeDir        )         {
+  return path.join(claudeDir, MANIFEST_FILE_NAME);
+}
+
+function canonicalManifestPath(scopeRoot        )         {
+  return path.join(path.resolve(scopeRoot), '.doflow', MANIFEST_FILE_NAME);
+}
+
+                              
+                     
+                     
+                        
+                    
+                   
+                    
+                  
+             
+                   
+                        
+                              
+ 
+
+/**
+ * `sourceCommit` lets a caller (bin/doflow.js) pass an already-resolved commit instead of this
+ * module spawning its own `git rev-parse`; omit it to resolve here (e.g. tests calling this module
+ * directly). An `mcp_servers` list a 1.18.0 install recorded is carried over as it is and never
+ * written anew: doflow.lock records each harness's MCP selection now, and the old list is read only
+ * as a fallback for a harness the lock lacks. `managedResources` is the optional ownership ledger
+ * for fine-grained Codex resources. Each record uses {target,scope,kind,identity,sourceVersion,
+ * fingerprint,selection,recoveryPoint}. Omit it to preserve a ledger written by a newer command.
+ */
+function writeManifest({ scopeRoot, claudeDir, scriptVersion, operation, repoRoot, backupId = '', tools, date, dryRun = false, sourceCommit, managedResources }                    )         {
+  if (!scopeRoot && !claudeDir) throw new Error('scopeRoot is required for lifecycle metadata');
+  const file = scopeRoot ? canonicalManifestPath(scopeRoot) : manifestPath(claudeDir          );
+  if (dryRun) return file;
+
+  // Preserve per-tool last_updated for tools NOT part of this operation (matches sync.sh's
+  // incremental jq merge, which only touches the tools passed to write_manifest).
+  let existingTools                      = {};
+  let existingMcpServers     ;
+  let existingManagedResources     ;
+  const existingFile = file;
+  if (existingFile && fs.existsSync(existingFile)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(existingFile, 'utf8'));
+      existingTools = existing.tools || {};
+      existingMcpServers = existing.mcp_servers;
+      // `managedResources` is accepted as a short-lived compatibility alias for manifests
+      // written by pre-release lifecycle work. New writes use the established snake_case
+      // top-level convention, while resource field names stay camelCase as specified by the
+      // ownership contract.
+      existingManagedResources = existing.managed_resources ?? existing.managedResources;
+    } catch { /* start fresh */ }
+  }
+  const ts = date.toISOString().replace(/\.\d+Z$/, 'Z');
+  const toolsOut                      = { ...existingTools };
+  for (const t of tools) toolsOut[t] = { installed: true, last_updated: ts };
+
+  const manifest      = {
+    script_version: scriptVersion,
+    last_operation: operation,
+    last_run: ts,
+    source_path: repoRoot,
+    source_commit: sourceCommit ?? gitSourceCommit(repoRoot),
+    last_backup_id: backupId,
+    tools: toolsOut,
+    mcp_servers: existingMcpServers,
+  };
+  const resources = managedResources ?? existingManagedResources;
+  if (resources !== undefined) manifest.managed_resources = resources;
+
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Security: the temp file must live next to `file` itself, not a shared os.tmpdir() — a
+  // world-writable /tmp plus a PID+timestamp-derived (i.e. guessable) name is a symlink-race
+  // waiting to happen (plant a symlink at the predicted path, the write clobbers its target).
+  // 'wx' (O_CREAT|O_EXCL) refuses to open through an existing symlink or file at all, and being
+  // on the same filesystem as `file` makes the final rename a guaranteed atomic same-fs op
+  // (os.tmpdir() offered no such guarantee — e.g. containers where /tmp is a separate tmpfs mount).
+  const tmp = path.join(path.dirname(file), `.install-manifest-${process.pid}-${date.getTime()}.json.tmp`);
+  fs.writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
+  fs.renameSync(tmp, file); // atomic on the same filesystem, matches sync.sh's mktemp + mv
+  return file;
+}
+
+/** null if no manifest yet. */
+function readManifestFile(file        )      {
+  if (!fs.existsSync(file)) return null;
+  try {
+    const m = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return {
+      operation: m.last_operation ?? 'none',
+      lastRun: m.last_run ?? 'none',
+      sourceCommit: m.source_commit ?? 'none',
+      backupId: m.last_backup_id ?? 'none',
+      tools: m.tools ?? {},
+      scriptVersion: m.script_version ?? 'none',
+      mcpServers: m.mcp_servers ?? null,
+      // Older manifests have no ownership ledger. Returning an empty list gives lifecycle
+      // callers a migration-safe baseline without changing their legacy install state.
+      managedResources: Array.isArray(m.managed_resources)
+        ? m.managed_resources
+        : (Array.isArray(m.managedResources) ? m.managedResources : []),
+    };
+  } catch {
+    return {
+      operation: 'error', lastRun: 'error', sourceCommit: 'error', backupId: 'error',
+      tools: {}, scriptVersion: 'error', mcpServers: null, managedResources: [],
+    };
+  }
+}
+
+/** Read only the canonical scope-neutral manifest used by lifecycle commands. */
+function readInstallManifest({ scopeRoot }                       )      {
+  if (!scopeRoot) throw new Error('scopeRoot is required');
+  return readManifestFile(canonicalManifestPath(scopeRoot));
+}
+
+/** Read only the legacy path; neutral-state migration uses this deliberately. */
+function readManifest(claudeDir        )      {
+  return readManifestFile(manifestPath(claudeDir));
+}
+
+module.exports = {
+  LEGACY_MANIFEST_FILE_NAME, MANIFEST_FILE_NAME, manifestPath, canonicalManifestPath,
+  writeManifest, readManifest, readInstallManifest,
+};

package/src/install/mcp.js

@@ -0,0 +1,254 @@
+'use strict';
+// mcp.js — MCP server selection: which of the registry's servers each harness gets, from --mcp,
+// the interactive checkbox, doflow.lock, the ledger or a 1.18.0 manifest. Writing a harness's MCP
+// file is that harness's adapter's job (src/adapters/<id>/), never this module's.
+//
+// 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('../install/mcp.js')` keeps working while the tree is still `.js`. The
+// `../registry` and `../state/lockfile` requires stay bare while those modules are still `.js`.
+const { readSyncBlocking } = require('../helper/prompt.js');
+const { selectMcpServers, nativeMcpCatalog, mcpCapable } = require('../registry/index.js');
+const { pinnedSelections } = require('../state/lockfile.js');
+
+const ESC = String.fromCharCode(27);
+const CTRL_C = String.fromCharCode(3);
+
+/** `registry` is a loaded registry (src/registry#loadRegistry); returns server names in registry
+ * declaration order. */
+function readAllServers(registry     )           {
+  return nativeMcpCatalog(selectMcpServers(registry)).allServers;
+}
+
+/** Parse `--mcp`: `all` and `none` are keywords that cannot be mixed with names or each other, an
+ * empty list and an unknown name are errors, names are deduplicated. `null` when the flag is absent. */
+function parseMcpFlag(requested                      , catalogIds          )                  {
+  if (!requested) return null;
+  const keywords = requested.filter((s) => s === 'all' || s === 'none');
+  if (keywords.length) {
+    if (keywords.length !== requested.length) {
+      throw new Error(`--mcp keyword '${keywords[0]}' cannot be combined with server names`);
+    }
+    if (new Set(requested).size > 1) {
+      throw new Error("Choose either '--mcp all' or '--mcp none', not both");
+    }
+    return keywords[0] === 'all' ? [...catalogIds] : [];
+  }
+  if (requested.length === 0) {
+    throw new Error("--mcp requires at least one server; use '--mcp none' for an explicit empty selection");
+  }
+  const invalid = requested.filter((s) => !catalogIds.includes(s));
+  if (invalid.length) {
+    throw new Error(`Unknown MCP server(s): ${invalid.join(', ')} (valid: ${catalogIds.join(', ')})`);
+  }
+  return [...new Set(requested)];
+}
+
+const holdsRows = (ledger     , harness        ) => (ledger?.resources ?? []).some((row     ) => row.harness === harness);
+
+/** Ids of `lists` that the catalog still declares, as one union in registry order. */
+const catalogUnion = (catalogIds          , lists            ) => catalogIds.filter((id) => lists.some((ids) => ids.includes(id)));
+
+/** 1.18.0 wrote lock rows only for claude and codex, and only non-empty ones. Any other row was
+ * written by a later run, which already settled which of that harness's entries are DoFlow's. */
+const LEGACY_LOCK_HARNESSES = ['claude', 'codex'];
+
+function settledByLaterRun(rows                          , harness        )          {
+  return harness in rows && (!LEGACY_LOCK_HARNESSES.includes(harness) || rows[harness].length === 0);
+}
+
+/** The servers a 1.18.0 install recorded writing for this harness, from state no later run writes:
+ * the manifest's MCP list, Antigravity's rows that carry no fingerprint, and Copilot's whole-map
+ * registration row, which covers the manifest's list or, with none, the catalog 1.18.0 wrote. */
+function legacyRecordedIds({ catalogIds, ledger, harness, manifestServers }                                                                                                      )           {
+  const rows = (ledger?.resources ?? []).filter((row     ) => row.harness === harness);
+  const ids = [...(manifestServers ?? [])];
+  for (const row of rows) if (row.kind === 'mcp-server' && (row.fingerprint ?? null) === null) ids.push(row.identity);
+  if (!manifestServers && rows.some((row     ) => row.ownershipIdentity === `${harness}:mcp:registration`)) ids.push(...catalogIds);
+  return catalogUnion(catalogIds, [ids]);
+}
+
+/** Per MCP-capable harness, the servers DoFlow may adopt when their entries already equal its own:
+ * only what a 1.18.0 install recorded for a harness the ledger holds, and only until a later run
+ * has recorded the harness's own selection. An entry a user wrote is never adoptable merely because
+ * DoFlow installed something else for that harness. Retired ids are dropped. */
+function adoptableMcpIds({ registry, lock, ledger, harnesses, manifestServers = null }                                                                                                   )                           {
+  const catalogIds = readAllServers(registry);
+  const rows = pinnedSelections(lock);
+  return Object.fromEntries(harnesses.filter((harness) => mcpCapable(registry, harness)).map((harness) => {
+    if (!holdsRows(ledger, harness) || settledByLaterRun(rows, harness)) return [harness, []];
+    return [harness, legacyRecordedIds({ catalogIds, ledger, harness, manifestServers })];
+  }));
+}
+
+/** Servers another harness of this scope still has recorded: the union of the lock rows of the lock's
+ * harnesses that are not targeted, registry order. */
+function retainedMcpIds(catalogIds          , rows                          , targets          )           {
+  return catalogUnion(catalogIds, Object.entries(rows).filter(([harness]) => !targets.includes(harness)).map(([, ids]) => ids));
+}
+
+/**
+ * Decide each targeted MCP-capable harness's servers. Per harness, the first step that applies:
+ *   1. --mcp <list>|all|none  -> the parsed ids                                        (flag)
+ *   2. install on a real TTY  -> one checkbox for every harness; a null answer falls through (prompt)
+ *   3. a lock row             -> that row                                              (recorded)
+ *   4. ledger rows            -> 'keep': the servers the harness owns now               (kept)
+ *   5. a 1.18.0 manifest list -> that list                                             (manifest)
+ *   6. otherwise              -> none                                                  (default)
+ * Lock and manifest ids the registry retired are dropped and reported once through `onStale`; an
+ * explicit --mcp naming one stays an error. Pure apart from `promptFn` and `onStale`.
+ */
+function resolveMcpSelections({
+  cmd, requested, targets, registry, lock, ledger, manifestServers = null, interactive = false, promptFn, onStale,
+}     )      {
+  const catalogIds = readAllServers(registry);
+  const flagged = parseMcpFlag(requested, catalogIds);
+  const rows = pinnedSelections(lock);
+  const capable = targets.filter((harness        ) => mcpCapable(registry, harness));
+  const retired = new Set        ();
+  const known = (ids          ) => {
+    for (const id of ids) if (!catalogIds.includes(id)) retired.add(id);
+    return catalogUnion(catalogIds, [ids]);
+  };
+
+  let prompted                  = null;
+  if (!flagged && cmd === 'install' && interactive && capable.length) {
+    const recorded = capable.filter((harness        ) => harness in rows).map((harness        ) => rows[harness]);
+    const seed = recorded.length ? catalogUnion(catalogIds, recorded.map(known))
+      : manifestServers ? known(manifestServers) : [...catalogIds];
+    prompted = promptFn(catalogIds, seed);
+  }
+
+  const pick = (harness        )                              => {
+    if (flagged) return [flagged, 'flag'];
+    if (prompted !== null) return [prompted, 'prompt'];
+    if (harness in rows) return [known(rows[harness]), 'recorded'];
+    if (holdsRows(ledger, harness)) return ['keep', 'kept'];
+    if (manifestServers) return [known(manifestServers), 'manifest'];
+    return [[], 'default'];
+  };
+  const selections                                    = {};
+  const sources                         = {};
+  for (const harness of capable) [selections[harness], sources[harness]] = pick(harness);
+  for (const [harness, ids] of Object.entries(rows)) if (!targets.includes(harness)) known(ids            );
+  if (retired.size && onStale) onStale([...retired].sort());
+
+  return {
+    selections,
+    sources,
+    adoptable: adoptableMcpIds({ registry, lock, ledger, harnesses: capable, manifestServers }),
+    retainedMcpIds: retainedMcpIds(catalogIds, rows, targets),
+  };
+}
+
+/** The selections a scope has recorded, for readers that never prompt (reconcile, status, inventory):
+ * each targeted MCP-capable harness's lock row, or 'keep' when the lock has none. Retired ids are
+ * dropped silently. */
+function recordedMcpSelections({ registry, lock, ledger, targets, manifestServers = null }     )      {
+  const catalogIds = readAllServers(registry);
+  const rows = pinnedSelections(lock);
+  const capable = targets.filter((harness        ) => mcpCapable(registry, harness));
+  return {
+    selections: Object.fromEntries(capable.map((harness        ) => [harness,
+      harness in rows ? catalogUnion(catalogIds, [rows[harness]]) : 'keep'])),
+    adoptable: adoptableMcpIds({ registry, lock, ledger, harnesses: capable, manifestServers }),
+    retainedMcpIds: retainedMcpIds(catalogIds, rows, targets),
+  };
+}
+
+const KEY = {
+  UP: `${ESC}[A`,
+  DOWN: `${ESC}[B`,
+  SPACE: ' ',
+  ENTER_CR: '\r',
+  ENTER_LF: '\n',
+  CTRL_C,
+  ALL: 'a',
+};
+
+/**
+ * Block for one raw-mode keypress, via prompt.js's readSyncBlocking (retries the EAGAIN-while-TTY
+ * case, bounded by a deadline for a genuinely unusable fd). Returns the decoded chunk, or null if
+ * the fd is unusable.
+ */
+function readKeypress(buf        )                {
+  try {
+    const n = readSyncBlocking(0, buf);
+    return buf.toString('utf8', 0, n);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Synchronous raw-mode checkbox prompt (arrow keys / j-k to move, space to toggle, 'a' to
+ * toggle-all, enter to confirm). Matches src/prompt.js's synchronous-read style — this CLI has no
+ * async control flow to hang off, so a real TTY read loop is built directly on fs.readSync(0, ...),
+ * the same primitive confirm()/promptLine() already use.
+ * Returns selected server names, or null if no usable TTY (caller falls back).
+ */
+function promptMcpCheckbox(servers          , initialSelected          , message = 'Select MCP servers to install:')                  {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return null;
+  if (servers.length === 0) return [];
+
+  const selected = new Set(initialSelected);
+  let cursor = 0;
+  const help = '  (up/down or j/k move, space toggle, a toggle-all, enter confirm)';
+
+  const render = (first         ) => {
+    if (!first) process.stdout.write(`${ESC}[${servers.length + 2}A`);
+    console.log(message);
+    console.log(help);
+    for (let i = 0; i < servers.length; i++) {
+      const mark = selected.has(servers[i]) ? '[x]' : '[ ]';
+      const pointer = i === cursor ? '>' : ' ';
+      console.log(`${pointer} ${mark} ${servers[i]}`);
+    }
+  };
+
+  let wasRaw = false;
+  let aborted = false;
+  try {
+    wasRaw = Boolean(process.stdin.isRaw);
+    process.stdin.setRawMode(true);
+    render(true);
+    const buf = Buffer.alloc(16);
+    for (;;) {
+      const chunk = readKeypress(buf);
+      if (chunk === null) {
+        aborted = true;
+        break;
+      }
+      if (chunk === KEY.ENTER_CR || chunk === KEY.ENTER_LF) break;
+      if (chunk === KEY.CTRL_C) {
+        console.log('\n[INFO]  Aborted.');
+        process.exit(130);
+      }
+      if (chunk === KEY.UP || chunk === 'k') cursor = (cursor - 1 + servers.length) % servers.length;
+      else if (chunk === KEY.DOWN || chunk === 'j') cursor = (cursor + 1) % servers.length;
+      else if (chunk === KEY.SPACE) {
+        const s = servers[cursor];
+        if (selected.has(s)) selected.delete(s);
+        else selected.add(s);
+      } else if (chunk === KEY.ALL) {
+        if (selected.size === servers.length) selected.clear();
+        else for (const s of servers) selected.add(s);
+      }
+      render(false);
+    }
+  } finally {
+    process.stdin.setRawMode(wasRaw);
+  }
+  console.log('');
+  if (aborted) return null; // fd went unusable mid-prompt — caller falls back to manifest/all
+  return servers.filter((s) => selected.has(s));
+}
+
+module.exports = {
+  readAllServers,
+  parseMcpFlag,
+  resolveMcpSelections,
+  recordedMcpSelections,
+  adoptableMcpIds,
+  promptMcpCheckbox,
+};

package/src/install/paths.js

@@ -0,0 +1,84 @@
+'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('../install/paths.js')` keeps working while the rest of the tree is still `.js`.
+const path = require('node:path');
+
+const DOFLOW_DIR_NAME = '.doflow';
+const BACKUP_DIR_NAME = 'backups';
+const INSTALL_MANIFEST_FILE_NAME = '.install-manifest.json';
+
+// Explicit migration bridge, mirroring manifest.js's: before 7de6d5f ("centralize lifecycle
+// metadata under .doflow") both the install manifest and the backup root were anchored to the
+// Claude harness directory, so restore points landed in `<scopeRoot>/.claude/backups` — $HOME
+// globally, the project root otherwise. That commit moved the write location to `.doflow/` and
+// bridged the manifest, leaving every pre-move restore point unreachable. The two names below
+// exist so the READ side of rollback/list-backups can still see what the move left behind.
+// Nothing may ever write, prune or delete here: those directories are a user's only recovery
+// material and DoFlow no longer owns their lifecycle.
+const LEGACY_BACKUP_ANCHOR_DIR_NAME = '.claude';
+
+                      
+                    
+ 
+
+                       
+                    
+                     
+                     
+                               
+                       
+ 
+
+/** Read-only legacy backup location for a scope. Never a write or prune target — see the note above. */
+function legacyBackupReadRoot({ scopeRoot }            )         {
+  if (typeof scopeRoot !== 'string' || !scopeRoot) throw new Error('scopeRoot is required');
+  return path.join(path.resolve(scopeRoot), LEGACY_BACKUP_ANCHOR_DIR_NAME, BACKUP_DIR_NAME);
+}
+
+/** True for `<anything>/.claude/backups` — used to refuse writes/prunes against the legacy root. */
+function isLegacyBackupReadRoot(candidate         )          {
+  if (typeof candidate !== 'string' || !candidate) return false;
+  const resolved = path.resolve(candidate);
+  return path.basename(resolved) === BACKUP_DIR_NAME
+    && path.basename(path.dirname(resolved)) === LEGACY_BACKUP_ANCHOR_DIR_NAME;
+}
+
+/** Inverse of `doflowPaths().backupRoot`: recover the scope root from a canonical backup root so a
+ * read path handed only that root can still derive the legacy one. Returns null for any path that
+ * is not shaped `<scopeRoot>/.doflow/backups` (a test fixture, a hand-passed directory) — the
+ * bridge then stays inert rather than inventing a sibling `.claude` next to an arbitrary path. */
+function scopeRootFromCanonicalBackupRoot(backupRoot         )                {
+  if (typeof backupRoot !== 'string' || !backupRoot) return null;
+  const resolved = path.resolve(backupRoot);
+  if (path.basename(resolved) !== BACKUP_DIR_NAME) return null;
+  const doflowRoot = path.dirname(resolved);
+  if (path.basename(doflowRoot) !== DOFLOW_DIR_NAME) return null;
+  return path.dirname(doflowRoot);
+}
+
+/** Resolve DoFlow-owned lifecycle metadata without anchoring it to a harness directory. */
+function doflowPaths({ scopeRoot }            )              {
+  if (typeof scopeRoot !== 'string' || !scopeRoot) throw new Error('scopeRoot is required');
+  const root = path.resolve(scopeRoot);
+  const doflowRoot = path.join(root, DOFLOW_DIR_NAME);
+  return {
+    scopeRoot: root,
+    doflowRoot,
+    backupRoot: path.join(doflowRoot, BACKUP_DIR_NAME),
+    legacyBackupReadRoot: legacyBackupReadRoot({ scopeRoot: root }),
+    manifestPath: path.join(doflowRoot, INSTALL_MANIFEST_FILE_NAME),
+  };
+}
+
+module.exports = {
+  DOFLOW_DIR_NAME,
+  BACKUP_DIR_NAME,
+  INSTALL_MANIFEST_FILE_NAME,
+  LEGACY_BACKUP_ANCHOR_DIR_NAME,
+  doflowPaths,
+  legacyBackupReadRoot,
+  isLegacyBackupReadRoot,
+  scopeRootFromCanonicalBackupRoot,
+};

package/src/install/targets.js

@@ -0,0 +1,90 @@
+'use strict';
+// targets.js — target validation + install-dir resolution.
+// PARITY: sync.sh is global-only — $HOME/.{claude,codex,gemini}, hardcoded, NOT CLAUDE_CONFIG_DIR.
+// doflow extends this with a second, DoFlow-only scope: project-local install (this repo's own
+// .claude/ is a real precedent — Claude Code, Codex, and Copilot all support project-scoped config
+// alongside global, see agent-docs/research/context-setup-claude-codex-copilot.md).
+//
+// Scope is explicit, never inferred: -g/--global -> $HOME-based (sync.sh parity); default (no -g) ->
+// rooted at an explicit project path, defaulting to cwd ('.') when no path is given. The parity
+// harness must pass -g for doflow, since sync.sh has no project mode to compare against.
+//
+// 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('../install/targets.js')` keeps working while the rest of the tree is still `.js`.
+const os = require('node:os');
+const path = require('node:path');
+
+const VALID = ['claude', 'codex', 'gemini', 'copilot', 'kiro', 'opencode', 'pi', 'antigravity'];
+
+/** The target used when `--target` is omitted. Deliberately one harness, not all of VALID: an
+ * install with no flag should touch the one tool the user almost certainly has, not write
+ * configuration into every harness DoFlow knows about — several of which may not be installed at
+ * all. That mattered less when VALID was three entries and matters more as it grows. Ask for the
+ * rest explicitly with `--target claude,codex,gemini`. */
+const DEFAULT_TARGETS = ['claude'];
+
+const TARGET_ALIASES                         = {
+  agy: 'antigravity',
+};
+
+/** Default to DEFAULT_TARGETS; validate any explicitly requested. */
+function resolveTargets(requested                      )           {
+  const rawTargets = requested && requested.length ? requested : [...DEFAULT_TARGETS];
+  const targets = rawTargets.map((t) => TARGET_ALIASES[t] || t);
+  for (const t of targets) {
+    if (!VALID.includes(t)) {
+      throw new Error(`Unknown target: '${t}' (valid: ${VALID.join(', ')})`);
+    }
+  }
+  return [...new Set(targets)];
+}
+
+                           
+                   
+                       
+ 
+
+/**
+ * Map tool -> install root.
+ *   global=true         -> $HOME/.{claude,codex,gemini,copilot,kiro,pi}, $HOME/.config/opencode
+ *                          (sync.sh parity for claude/codex/gemini; the four new harnesses follow
+ *                          each one's own documented global root — see below)
+ *   global=false (dflt) -> <resolved projectRoot>/.{claude,codex,kiro,opencode,pi}, but .agents for
+ *     gemini and .github for copilot — both deliberately asymmetric with their own global-scope
+ *     directory, for reasons native to each harness (see per-key notes below).
+ *
+ *   gemini   -> project-scoped Gemini config follows the Antigravity customization convention, not
+ *               `.gemini/`, so it is asymmetric with its own global directory and with the other
+ *               targets.
+ *   copilot  -> Copilot has no single native root the way Claude's `.claude` is one: instructions,
+ *               skills, agents, and MCP each live under a different path (see design.md §4's
+ *               native-surfaces table). `.github` is the project root DoFlow treats as Copilot's
+ *               "home" here because that is where `copilot-instructions.md` and `.github/agents`
+ *               live; `~/.copilot` is the equivalent global root.
+ *   kiro     -> `.kiro` / `~/.kiro` is the one native root that actually holds everything Kiro
+ *               reads (steering, agents, hooks, settings/mcp.json), so — unlike copilot — this is
+ *               the clean, symmetric case.
+ *   opencode -> Global config is `~/.config/opencode`, NOT `~/.opencode/` — a path DoFlow's own
+ *               docs asserted incorrectly for several releases (see src/adapters/opencode/index.js).
+ *               Project scope is `.opencode`, asymmetric with the global path the same way gemini's
+ *               is.
+ *   pi       -> Global config is `~/.pi/agent` — note the `agent/` segment; `~/.pi/settings.json`
+ *               is not a location Pi reads. Project scope is `.pi` (see
+ *               src/adapters/pi/index.js's own `nativePaths()`, which this mirrors exactly).
+ */
+function toolDirs(opts                  = {})                         {
+  const { global = false, projectRoot = '.' } = opts;
+  const root = global ? os.homedir() : path.resolve(projectRoot);
+  return {
+    claude: path.join(root, '.claude'),
+    codex: path.join(root, '.codex'),
+    gemini: global ? path.join(root, '.gemini') : path.join(root, '.agents'),
+    copilot: global ? path.join(root, '.copilot') : path.join(root, '.github'),
+    kiro: path.join(root, '.kiro'),
+    opencode: global ? path.join(root, '.config', 'opencode') : path.join(root, '.opencode'),
+    pi: global ? path.join(root, '.pi', 'agent') : path.join(root, '.pi'),
+  };
+}
+
+module.exports = { VALID, DEFAULT_TARGETS, resolveTargets, toolDirs };