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

package/src/runtime/capability-router.ts

@@ -0,0 +1,484 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { finishRuntime, usageError } = require('./cli-result.ts');
+const { REPO_ROOT } = require('../helper/repo-root.ts');
+const { validateCapabilityProviders } = require('../registry/index.ts');
+
+// Mirrors bin/doflow.js's own REPO_ROOT computation, relative to this file's location, so
+// handleRouteCommand resolves the same repo root it did before relocation. (D8)
+
+/** POSIX single-quote escaping, for the DISPLAY string only — execution always uses the argv
+ * vector, never a shell string, so retrieved data can never become shell syntax (review R5). */
+function shellQuote(word: any): string {
+  const text = String(word);
+  if (text !== '' && /^[A-Za-z0-9_@%+=:,.\/-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+function parseYamlFile(filePath: string, fsImpl: any = fs): any {
+  try {
+    const text = fsImpl.readFileSync(filePath, 'utf8');
+    return JSON.parse(text);
+  } catch (error: any) {
+    throw new Error(`Failed to parse registry file '${filePath}': ${error.message}`);
+  }
+}
+
+class CapabilityRouter {
+  fsImpl: any;
+  repoRoot: string;
+  projectRoot: string;
+  registryDir: string;
+  binaryChecker: ((binary: string) => boolean) | null;
+  binaryCache: Map<string, boolean>;
+  capabilities!: Record<string, any>;
+  routes!: Record<string, any>;
+
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.repoRoot]
+   * @param {string} [options.registryDir]
+   * @param {Object} [options.capabilities]
+   * @param {Object} [options.routes]
+   * @param {Object} [options.fsImpl]
+   * @param {Function} [options.binaryChecker]
+   */
+  constructor(options: any = {}) {
+    this.fsImpl = options.fsImpl || fs;
+    this.repoRoot = options.repoRoot || REPO_ROOT;
+    // Two roots, deliberately distinct (review A3, surfaced by R5's tests): `repoRoot` locates the
+    // DoFlow install — the registry ships inside it — while `projectRoot` is the repository under
+    // work, whose manifests native.test detection reads. Under an npm install they differ; a
+    // single root made detection read the DoFlow package's own package.json.
+    this.projectRoot = options.projectRoot || options.repoRoot || process.cwd();
+    this.registryDir = options.registryDir || path.join(this.repoRoot, 'core', 'registry');
+    this.binaryChecker = options.binaryChecker || null;
+    this.binaryCache = new Map();
+    
+    if (options.capabilities && options.routes) {
+      this.capabilities = options.capabilities;
+      this.routes = options.routes;
+    } else {
+      this.loadRegistries();
+    }
+  }
+
+  loadRegistries(): void {
+    const capsPath = path.join(this.registryDir, 'capabilities.json');
+    const routesPath = path.join(this.registryDir, 'routes.json');
+    
+    const capsData = parseYamlFile(capsPath, this.fsImpl);
+    const routesData = parseYamlFile(routesPath, this.fsImpl);
+
+    this.capabilities = capsData.capabilities || {};
+    // A provider without a valid `sourceMode` cannot be told apart from an index-backed one, so the
+    // file is refused whole rather than loaded with a guess (068).
+    const providerErrors: string[] = [];
+    validateCapabilityProviders(this.capabilities, providerErrors);
+    if (providerErrors.length > 0) {
+      throw new Error(`Invalid registry file '${capsPath}':\n- ${providerErrors.join('\n- ')}`);
+    }
+    this.routes = routesData.routes || {};
+  }
+
+  /**
+   * Check if an executable binary is present in PATH or environment with caching.
+   * @param {string} binary
+   * @returns {boolean}
+   */
+  isBinaryAvailable(binary: string): boolean {
+    if (!binary) return false;
+    if (this.binaryChecker) {
+      return this.binaryChecker(binary);
+    }
+    if (this.binaryCache.has(binary)) {
+      return this.binaryCache.get(binary) as boolean;
+    }
+    try {
+      const isWin = process.platform === 'win32';
+      const cmd = isWin ? 'where' : 'which';
+      execFileSync(cmd, [binary], { stdio: 'ignore', timeout: 1000 });
+      this.binaryCache.set(binary, true);
+      return true;
+    } catch {
+      this.binaryCache.set(binary, false);
+      return false;
+    }
+  }
+
+  /**
+   * Executes a smoke check command for a provider.
+   * @param {Array<string>} checkCommand
+   * @returns {{ ok: boolean, output?: string, error?: string }}
+   */
+  executeSmokeCheck(checkCommand: any): { ok: boolean; output?: string; error?: string } {
+    if (!Array.isArray(checkCommand) || checkCommand.length === 0) {
+      return { ok: true };
+    }
+    const [bin, ...args] = checkCommand;
+    try {
+      const stdout = execFileSync(bin, args, {
+        encoding: 'utf8',
+        timeout: 2500,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      return { ok: true, output: stdout.trim() };
+    } catch (error: any) {
+      return { ok: false, error: error.message };
+    }
+  }
+
+  /**
+   * Evaluates the health of a single provider.
+   * @param {Object} provider
+   * @param {boolean} [deepCheck=false]
+   * @returns {{ status: 'HEALTHY'|'UNAVAILABLE', details?: string }}
+   */
+  evaluateProviderHealth(provider: any, deepCheck: boolean = false): any {
+    if (!provider) return { status: 'UNAVAILABLE', details: 'No provider declared' };
+
+    // Declared / installed / responsive are DISTINCT facts (review R5): `facts` reports each one
+    // as true, false, or null-for-not-measured, so "healthy" can never silently mean only
+    // "declared in the registry". The summary `status` stays for existing callers.
+    const facts: { declared: boolean; installed: boolean | null; responsive: boolean | null } = { declared: true, installed: null, responsive: null };
+
+    // `native.test` has no binary — its installedness is whether this project's manifests declare
+    // a test command at all. Reporting HEALTHY without that check routed verify-runtime-behavior
+    // to an invented `npm test` on machines where every binary probe failed (review R5).
+    if (provider.id === 'native.test') {
+      const command = this.detectTestCommand();
+      facts.installed = Boolean(command);
+      if (!command) {
+        return { status: 'UNAVAILABLE', details: 'No test command detected in project manifests', facts };
+      }
+      return { status: 'HEALTHY', details: `Project test command: ${command}`, facts };
+    }
+
+    // For native providers, check binary if specified (or fallback to basic availability)
+    if (provider.kind === 'native') {
+      if (provider.binary) {
+        const available = this.isBinaryAvailable(provider.binary);
+        facts.installed = available;
+        if (!available && provider.binary === 'rg') {
+          // If rg is not present, check for standard grep as baseline fallback
+          const grepAvailable = this.isBinaryAvailable('grep');
+          if (grepAvailable) {
+            facts.installed = true;
+            return { status: 'HEALTHY', details: 'Using grep fallback', facts };
+          }
+        }
+        if (!available) {
+          return { status: 'UNAVAILABLE', details: `Native binary '${provider.binary}' not found`, facts };
+        }
+      }
+      return { status: 'HEALTHY', facts };
+    }
+
+    if (provider.binary) {
+      const available = this.isBinaryAvailable(provider.binary);
+      facts.installed = available;
+      if (!available) {
+        return { status: 'UNAVAILABLE', details: `Tool binary '${provider.binary}' not found`, facts };
+      }
+      if (deepCheck && provider.checkCommand) {
+        const smoke = this.executeSmokeCheck(provider.checkCommand);
+        facts.responsive = smoke.ok;
+        if (!smoke.ok) {
+          return { status: 'UNAVAILABLE', details: `Smoke check failed: ${smoke.error}`, facts };
+        }
+      }
+      return { status: 'HEALTHY', facts };
+    }
+
+    return { status: 'HEALTHY', facts };
+  }
+
+  /**
+   * Resolves a capability to its highest-priority healthy provider.
+   * @param {string} capabilityId
+   * @param {Object} [options]
+   * @param {boolean} [options.deepCheck=false]
+   * @returns {{ capabilityId: string, provider: Object|null, status: string, fallbackProviders: Array<Object> }}
+   */
+  resolveCapability(capabilityId: string, { deepCheck = false }: { deepCheck?: boolean } = {}): any {
+    const capability = this.capabilities[capabilityId];
+    if (!capability) {
+      throw new Error(`Unknown capability '${capabilityId}'`);
+    }
+
+    const providers = capability.providers || [];
+    let selectedProvider: any = null;
+    let selectedStatus = 'UNAVAILABLE';
+    const fallbackProviders: any[] = [];
+
+    for (let i = 0; i < providers.length; i++) {
+      const prov = providers[i];
+      const health = this.evaluateProviderHealth(prov, deepCheck);
+      
+      if (health.status === 'HEALTHY') {
+        if (!selectedProvider) {
+          selectedProvider = prov;
+          selectedStatus = i === 0 ? 'HEALTHY' : 'FALLBACK';
+        } else {
+          fallbackProviders.push(prov);
+        }
+      } else {
+        fallbackProviders.push({ ...prov, status: 'UNAVAILABLE', reason: health.details });
+      }
+    }
+
+    return {
+      capabilityId,
+      description: capability.description,
+      provider: selectedProvider,
+      status: selectedStatus,
+      fallbackProviders,
+    };
+  }
+
+  /**
+   * Formats concrete execution instructions for a provider based on intent parameters.
+   *
+   * The executable contract is `argv` — an argument VECTOR, executed without a shell (review R5:
+   * the old interpolated strings turned a query containing `$(...)` into executable shell syntax
+   * and split a path containing spaces). `cliCommand` remains for display and for a human typing
+   * it, built by quoting every argv word; it is never the primary contract. MCP invocations get a
+   * validated tool name plus an argument object using the tool's own parameter names.
+   *
+   * @param {string} intent
+   * @param {Object} provider
+   * @param {Object} params
+   * @returns {Object}
+   */
+  formatExecution(intent: string, provider: any, params: any = {}): any {
+    const query = params.query || params.symbol || params.concept || '';
+    const targetPath = params.path || '.';
+    // The MCP tool name comes from the provider's registry descriptor (`mcp: {server, tool}`), so a
+    // new MCP-backed provider needs no code change here. A caller may pass a bare `{ id }`, so fall
+    // back to the registry entry with that id.
+    const mcp = provider.mcp
+      || Object.values(this.capabilities).flatMap((cap: any) => cap.providers || []).find((p: any) => p.id === provider.id && p.mcp)?.mcp;
+    const mcpTool = mcp ? { mcpTool: `mcp__${mcp.server}__${mcp.tool}` } : {};
+    const withDisplay = (result: any) => ({ ...mcpTool, ...result, ...(result.argv ? { cliCommand: result.argv.map(shellQuote).join(' ') } : {}) });
+
+    if (provider.id === 'semble.search') {
+      const content = params.content || 'code';
+      return withDisplay({
+        // `repo`, not `path`: the MCP tool's schema names the project root `repo` and rejects a
+        // call without it (review R5 — the routed arguments did not fit the tool they named).
+        args: { query, repo: targetPath, content },
+        argv: ['semble', 'search', query, targetPath, '--content', content],
+      });
+    }
+
+    if (provider.id === 'graphify.query') {
+      return withDisplay({
+        args: { query, project_path: targetPath },
+        argv: ['graphify', 'query', query],
+      });
+    }
+
+    if (provider.id === 'native.rg') {
+      const isRg = this.isBinaryAvailable('rg');
+      return withDisplay({
+        argv: isRg ? ['rg', '-i', query, targetPath] : ['grep', '-rn', '-i', query, targetPath],
+        args: { query, path: targetPath },
+      });
+    }
+
+    if (provider.id === 'git.native') {
+      return withDisplay({
+        argv: ['git', 'log', '-n', String(params.maxCommits || 10), `--grep=${query}`],
+        args: { query },
+      });
+    }
+
+    if (provider.id === 'rtk') {
+      // `params.command` is by contract a command the caller already owns, not retrieved data, so
+      // it passes through; there is no argv because splitting a caller's command string here would
+      // corrupt any quoted argument it contains.
+      const rawCmd = params.command || 'git status';
+      return {
+        cliCommand: `rtk ${rawCmd}`,
+        args: { rawCommand: rawCmd },
+      };
+    }
+
+    // `native.test` stands for "whatever this project runs its tests with", read from the project's
+    // own manifests via the shared command detector. No detection, no command: inventing `npm test`
+    // for a project that never declared it hands the model a plausible-looking command that answers
+    // a question nobody asked (review R5).
+    if (provider.id === 'native.test') {
+      const command = params.testCommand || this.detectTestCommand();
+      if (!command) {
+        return {
+          cliCommand: null,
+          argv: null,
+          args: {},
+          reason: 'No test command detected in this project\'s manifests; declare one (plan.md override or package manifest) before routing verify-runtime-behavior here.',
+        };
+      }
+      return withDisplay({
+        argv: [...command.split(' '), ...(query ? [query] : [])],
+        args: { testCommand: command, ...(query ? { filter: query } : {}) },
+      });
+    }
+
+    return withDisplay({
+      argv: [provider.binary || provider.id, query],
+      args: params,
+    });
+  }
+
+  /** The project's own test entrypoint, read from its manifests by the shared command detector —
+   * the same detector `doflow verify` uses, so the two agree. Returns null when no manifest
+   * declares one: a wrong guess here becomes a command the model runs. */
+  detectTestCommand(): string | null {
+    try {
+      const { detectCommands } = require('./command-detect.ts');
+      const detected = detectCommands({ projectRoot: this.projectRoot });
+      return detected.commands?.test?.command || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Resolves a user/task information intent to a structured RetrievalPlan.
+   * @param {string} intentId
+   * @param {Object} [params={}]
+   * @param {Object} [options={}]
+   * @returns {Object} RetrievalPlan
+   */
+  resolveIntent(intentId: string, params: any = {}, { deepCheck = false }: { deepCheck?: boolean } = {}): any {
+    const route = this.routes[intentId];
+    if (!route) {
+      throw new Error(`Unknown route/intent '${intentId}'`);
+    }
+
+    const primaryCapId = route.capability;
+    const primaryResolution = this.resolveCapability(primaryCapId, { deepCheck });
+
+    if (primaryResolution.provider) {
+      return {
+        intent: intentId,
+        description: route.description,
+        capability: primaryCapId,
+        selectedProvider: primaryResolution.provider,
+        status: primaryResolution.status,
+        execution: this.formatExecution(intentId, primaryResolution.provider, params),
+        fallbackChain: (route.fallback || []).map((fbCap: string) => ({
+          capability: fbCap,
+          resolved: this.resolveCapability(fbCap, { deepCheck }),
+        })),
+      };
+    }
+
+    // Primary capability had no healthy providers. Evaluate route fallbacks in order.
+    for (const fallbackCapId of route.fallback || []) {
+      const fallbackResolution = this.resolveCapability(fallbackCapId, { deepCheck });
+      if (fallbackResolution.provider) {
+        return {
+          intent: intentId,
+          description: route.description,
+          capability: fallbackCapId,
+          selectedProvider: fallbackResolution.provider,
+          status: 'FALLBACK',
+          execution: this.formatExecution(intentId, fallbackResolution.provider, params),
+          fallbackChain: [
+            {
+              capability: primaryCapId,
+              status: 'UNAVAILABLE',
+              reason: 'No healthy providers available',
+            },
+          ],
+        };
+      }
+    }
+
+    return {
+      intent: intentId,
+      description: route.description,
+      capability: primaryCapId,
+      selectedProvider: null,
+      status: 'UNAVAILABLE',
+      execution: null,
+      fallbackChain: (route.fallback || []).map((cap: string) => ({ capability: cap, status: 'UNAVAILABLE' })),
+    };
+  }
+
+  /**
+   * Returns a complete diagnostic health report for all registered capabilities and routes.
+   * @param {boolean} [deepCheck=false]
+   * @returns {Array<Object>}
+   */
+  getAllCapabilitiesHealth(deepCheck: boolean = false): any[] {
+    const report: any[] = [];
+    for (const [capId, cap] of Object.entries(this.capabilities)) {
+      const resolution = this.resolveCapability(capId, { deepCheck });
+      report.push({
+        capability: capId,
+        description: cap.description,
+        status: resolution.status,
+        activeProvider: resolution.provider ? resolution.provider.name : 'None',
+        providerId: resolution.provider ? resolution.provider.id : null,
+        totalProviders: cap.providers ? cap.providers.length : 0,
+      });
+    }
+    return report;
+  }
+}
+
+/**
+ * Handles `doflow route` — resolve an information need to a provider that is actually healthy.
+ *
+ * Exits 1 when no provider can serve the intent: that is a finding the caller must act on (the
+ * work still has to be done, by hand or by a different route), not an error in the request.
+ *
+ * @param {Object} options
+ * @param {string|null} options.intent
+ * @param {string} [options.query]
+ * @param {boolean} [options.check=false] deep smoke check instead of a presence check
+ * @param {boolean} [options.json=false]
+ * @param {string} [options.projectRoot]
+ * @returns {number} exit code
+ */
+function handleRouteCommand({ intent, query, check = false, json = false, projectRoot }: any = {}): number {
+  const router = new CapabilityRouter({ repoRoot: REPO_ROOT, projectRoot });
+  if (typeof intent !== 'string' || intent.trim() === '') {
+    return usageError('route', `--intent is required. Declared intents: ${Object.keys(router.routes).join(', ')}`, json);
+  }
+
+  let resolution: any;
+  try {
+    resolution = router.resolveIntent(intent, { query, path: projectRoot || '.' }, { deepCheck: check });
+  } catch (error: any) {
+    return usageError('route', `${error.message}. Declared intents: ${Object.keys(router.routes).join(', ')}`, json, error);
+  }
+
+  if (json) console.log(JSON.stringify(resolution, null, 2));
+  else {
+    console.log(`\nDoFlow Route [${resolution.intent}] — ${resolution.status}:`);
+    console.log('═'.repeat(78));
+    console.log(`Need:       ${resolution.description}`);
+    console.log(`Capability: ${resolution.capability}`);
+    console.log(`Provider:   ${resolution.selectedProvider ? resolution.selectedProvider.name : 'none — no provider on this machine can answer'}`);
+    if (resolution.execution) {
+      console.log('─'.repeat(78));
+      for (const [key, value] of Object.entries(resolution.execution)) console.log(`  ${key.padEnd(12)} ${value}`);
+    }
+    console.log('═'.repeat(78) + '\n');
+  }
+  return finishRuntime(resolution.selectedProvider ? 0 : 1);
+}
+
+module.exports = {
+  CapabilityRouter,
+  parseYamlFile,
+  handleRouteCommand,
+};

package/src/runtime/checkouts.ts

@@ -0,0 +1,170 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { BASE_FILE } = require('./worktree.ts');
+
+// The checkouts of one repository: the main working tree and its linked worktrees.
+//
+// Feature folders, runs and records live in whichever checkout wrote them; a linked worktree has
+// none of the main checkout's gitignored files. A reader that looks only where it stands misses
+// them, and a reader that guesses another path reads the wrong one. `git worktree list` is the one
+// source that names every checkout, and it is asked once per process.
+
+/** realpath(cwd) -> listCheckouts result. */
+const cache = new Map<string, any>();
+
+function realOrNull(p: string, fsImpl: any): string | null {
+  try {
+    return fsImpl.realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function failed(reason: string, detail: string): any {
+  return {
+    ok: false, reason, detail, current: null, main: null, mainReason: null, others: [], isLinked: false, sandbox: false,
+  };
+}
+
+/**
+ * The repository's checkouts as seen from `cwd`, from one `git worktree list --porcelain`.
+ *
+ * `main` is the first porcelain entry (null when it is bare, no longer exists, or `cwd` is in a
+ * DoFlow sandbox); `current` is the entry that is the longest real-path prefix of `cwd`, so a
+ * sandbox nested under the main checkout is told apart from it. A sandbox (a checkout holding
+ * `.doflow-worktree-base`) is never offered as another checkout and sees none itself: it exists
+ * to be isolated. Writes nothing.
+ * @param {Object} options
+ * @param {string} options.cwd
+ * @param {Function} [options.exec] spawnSync-compatible
+ * @param {Object} [options.fsImpl]
+ * @returns {{ok: boolean, reason: string|null, detail: string|null, current: string|null, main: string|null,
+ *   mainReason: string|null, others: Array<string>, isLinked: boolean, sandbox: boolean}}
+ */
+function listCheckouts({ cwd, exec = spawnSync, fsImpl = fs }: { cwd: string; exec?: any; fsImpl?: any }): any {
+  const realCwd = realOrNull(cwd, fsImpl) || path.resolve(cwd);
+  if (cache.has(realCwd)) return cache.get(realCwd);
+
+  let res: any;
+  try {
+    res = exec('git', ['-C', realCwd, 'worktree', 'list', '--porcelain'], { encoding: 'utf8', timeout: 10000 });
+  } catch (error: any) {
+    res = { error };
+  }
+  let result: any;
+  if (res && res.error) {
+    result = res.error.code === 'ENOENT'
+      ? failed('git-unavailable', String(res.error.message || '').trim().slice(0, 200))
+      : failed('worktree-list-failed', String(res.error.message || '').trim().slice(0, 200));
+  } else if (!res || res.status !== 0) {
+    const stderr = String((res && res.stderr) || '').trim().slice(0, 200);
+    result = failed(/not a git repository/.test(stderr) ? 'not-a-git-repository' : 'worktree-list-failed', stderr);
+  } else {
+    result = fromPorcelain(String(res.stdout || ''), realCwd, fsImpl);
+  }
+  cache.set(realCwd, result);
+  return result;
+}
+
+function fromPorcelain(stdout: string, realCwd: string, fsImpl: any): any {
+  const entries: Array<{ real: string | null; bare: boolean; sandbox: boolean }> = [];
+  for (const block of stdout.split(/\n\s*\n/)) {
+    const lines = block.split('\n').filter(Boolean);
+    if (lines.length === 0 || !lines[0].startsWith('worktree ')) continue;
+    const real = realOrNull(lines[0].slice('worktree '.length), fsImpl);
+    entries.push({
+      real,
+      bare: lines.includes('bare'),
+      sandbox: real !== null && fsImpl.existsSync(path.join(real, BASE_FILE)),
+    });
+  }
+
+  let current: any = null;
+  for (const e of entries) {
+    if (e.real === null || e.bare) continue;
+    if ((realCwd === e.real || realCwd.startsWith(e.real + path.sep)) && (current === null || e.real.length > current.real.length)) {
+      current = e;
+    }
+  }
+  const sandbox = Boolean(current && current.sandbox);
+  const first = entries[0];
+  let main: string | null = null;
+  let mainReason: string | null = null;
+  if (sandbox) mainReason = 'sandbox';
+  else if (first && first.bare) mainReason = 'bare';
+  else if (!first || first.real === null) mainReason = 'missing';
+  else main = first.real;
+
+  const others = sandbox ? [] : entries
+    .filter((e) => e.real !== null && !e.bare && !e.sandbox && e !== current)
+    .map((e) => e.real as string);
+  const currentPath = current ? current.real : null;
+  return {
+    ok: true,
+    reason: null,
+    detail: null,
+    current: currentPath,
+    main,
+    mainReason,
+    others: [...new Set(others)],
+    isLinked: currentPath !== null && main !== null && currentPath !== main,
+    sandbox,
+  };
+}
+
+/** Forgets every memoized `listCheckouts` result (tests that rebuild a repository in place). */
+function clearCheckoutCache(): void {
+  cache.clear();
+}
+
+/**
+ * A state file in the checkout the verb resolves to, else in exactly one other checkout.
+ *
+ * The current checkout is read first and, when the file is there, no `git` call is made. Two or
+ * more other checkouts holding it is `ambiguous` rather than a pick: which one is meant is not
+ * something a path can decide. Writes nothing.
+ * @param {Object} options
+ * @param {string} options.stateRoot the root the verb resolves today
+ * @param {string|Array<string>|Function} options.relPath a path under each root, candidate paths taken in
+ *   order (the first that exists in a root is that root's file), or `(root, isCurrent) => string|null`
+ *   for a store whose location differs per checkout (null skips that root)
+ * @param {Function} [options.exec]
+ * @param {Object} [options.fsImpl]
+ * @returns {{status: 'found'|'missing'|'ambiguous', file: string|null, root: string|null,
+ *   origin: 'current'|'other'|null, candidates: Array<string>}}
+ */
+function findStateFile({ stateRoot, relPath, exec = spawnSync, fsImpl = fs }: { stateRoot: string; relPath: any; exec?: any; fsImpl?: any }): any {
+  const at = (root: string, isCurrent: boolean): string | null => {
+    const rel = typeof relPath === 'function' ? relPath(root, isCurrent) : relPath;
+    for (const candidate of Array.isArray(rel) ? rel : [rel]) {
+      if (typeof candidate !== 'string' || candidate === '') continue;
+      const file = path.join(root, candidate);
+      if (fsImpl.existsSync(file)) return file;
+    }
+    return null;
+  };
+  const missing = { status: 'missing', file: null, root: null, origin: null, candidates: [] as string[] };
+
+  const here = at(stateRoot, true);
+  if (here) return { status: 'found', file: here, root: stateRoot, origin: 'current', candidates: [] };
+
+  const checkouts = listCheckouts({ cwd: stateRoot, exec, fsImpl });
+  if (!checkouts.ok || checkouts.sandbox) return missing;
+  const matches: Array<{ file: string; root: string }> = [];
+  for (const root of checkouts.others as string[]) {
+    const file = at(root, false);
+    if (file) matches.push({ file, root });
+  }
+  if (matches.length === 0) return missing;
+  if (matches.length > 1) {
+    return { status: 'ambiguous', file: null, root: null, origin: null, candidates: matches.map((m: { file: string }) => m.file) };
+  }
+  return { status: 'found', file: matches[0].file, root: matches[0].root, origin: 'other', candidates: [] };
+}
+
+module.exports = { listCheckouts, findStateFile, clearCheckoutCache };