@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/capability-router.js

@@ -84,6 +84,38 @@ class CapabilityRouter {
       throw new Error(`Invalid registry file '${capsPath}':\n- ${providerErrors.join('\n- ')}`);
     }
     this.routes = routesData.routes || {};
+
+    try {
+      const { contributionsFor } = require('./packages/contributions.js');
+      const packageContribs = contributionsFor('capability-provider', 1, {
+        repoRoot: this.repoRoot,
+        fsImpl: this.fsImpl,
+        projectRoot: this.projectRoot,
+      });
+      for (const contrib of packageContribs) {
+        const data = contrib.data;
+        if (data && typeof data === 'object' && data.capability) {
+          if (!this.capabilities[data.capability]) {
+            this.capabilities[data.capability] = {
+              description: data.name || data.capability,
+              providers: [],
+            };
+          }
+          this.capabilities[data.capability].providers.push({
+            id: contrib.qualifiedId,
+            name: data.name,
+            kind: data.kind,
+            sourceMode: data.sourceMode || 'live',
+            costTier: data.costTier || 'free',
+            timeoutMs: data.timeoutMs || 10000,
+            ...data,
+            packageId: contrib.packageId,
+          });
+        }
+      }
+    } catch {
+      // best effort if package contributions cannot be queried
+    }
   }
 
   /**
@@ -179,11 +211,36 @@ class CapabilityRouter {
       return { status: 'HEALTHY', facts };
     }
 
-    if (provider.binary) {
-      const available = this.isBinaryAvailable(provider.binary);
+    if (provider.kind === 'http' || provider.endpoint) {
+      const { validateLoopbackUrl } = require('./capabilities/loopback.js');
+      const valid = validateLoopbackUrl(provider.endpoint);
+      if (!valid.ok) {
+        facts.installed = false;
+        facts.responsive = false;
+        return { status: 'UNAVAILABLE', details: `Disallowed endpoint: ${valid.reason}`, facts };
+      }
+      facts.installed = true;
+      if (deepCheck) {
+        if (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 };
+        }
+        facts.responsive = false;
+        return { status: 'UNAVAILABLE', details: 'HTTP provider reachability cannot be confirmed without checkCommand', facts };
+      }
+      return { status: 'HEALTHY', facts };
+    }
+
+    const binary = provider.binary || provider.program;
+    if (binary) {
+      const available = this.isBinaryAvailable(binary);
       facts.installed = available;
       if (!available) {
-        return { status: 'UNAVAILABLE', details: `Tool binary '${provider.binary}' not found`, facts };
+        return { status: 'UNAVAILABLE', details: `Tool binary '${binary}' not found`, facts };
       }
       if (deepCheck && provider.checkCommand) {
         const smoke = this.executeSmokeCheck(provider.checkCommand);
@@ -329,6 +386,18 @@ class CapabilityRouter {
       });
     }
 
+    if (provider.kind === 'http' || provider.endpoint) {
+      const method = provider.method || 'POST';
+      return {
+        cliCommand: null,
+        argv: null,
+        httpEndpoint: provider.endpoint,
+        method,
+        args: params,
+        display: `HTTP ${method} ${provider.endpoint}`,
+      };
+    }
+
     return withDisplay({
       argv: [provider.binary || provider.id, query],
       args: params,
@@ -432,6 +501,69 @@ class CapabilityRouter {
     }
     return report;
   }
+
+  async executeCapability(
+    capabilityId        ,
+    input      = {},
+    options      = {}
+  )               {
+    const { LocalCapabilityExecutor } = require('./capabilities/executor.js');
+    const executor = new LocalCapabilityExecutor({
+      fsImpl: this.fsImpl,
+      fetchImpl: options.fetchImpl,
+      execFileImpl: options.execFileImpl,
+      maxBufferBytes: options.maxBufferBytes,
+    });
+
+    let targetCapId = capabilityId;
+    let fallbackCaps           = [];
+    if (this.routes[capabilityId]) {
+      targetCapId = this.routes[capabilityId].capability;
+      fallbackCaps = this.routes[capabilityId].fallback || [];
+    } else {
+      const matchingRoute = Object.values(this.routes).find((r     ) => r.capability === capabilityId);
+      if (matchingRoute) fallbackCaps = matchingRoute.fallback || [];
+    }
+
+    const capsToTry = [targetCapId, ...fallbackCaps];
+    for (let c = 0; c < capsToTry.length; c++) {
+      const curCap = capsToTry[c];
+      const capDef = this.capabilities[curCap];
+      if (!capDef || !Array.isArray(capDef.providers) || capDef.providers.length === 0) continue;
+
+      for (const provider of capDef.providers) {
+        const res = await executor.execute(curCap, provider, input, options);
+        if (res.ok) {
+          return {
+            ...res,
+            status: c === 0 ? 'HEALTHY' : 'FALLBACK',
+          };
+        }
+        if (
+          res.status === 'ERROR' ||
+          (res.error && (
+            res.error.includes('DECISION_INJECTION_REFUSED') ||
+            res.error.includes('DISALLOWED_REMOTE_ENDPOINT') ||
+            res.error.includes('exceeded buffer limit')
+          ))
+        ) {
+          return {
+            ...res,
+            status: 'ERROR',
+          };
+        }
+      }
+    }
+
+    return {
+      ok: false,
+      capabilityId,
+      providerId: null,
+      status: 'UNAVAILABLE',
+      data: null,
+      error: 'No available healthy providers found for capability',
+    };
+  }
 }
 
 /**

package/src/runtime/checkouts.js

@@ -27,7 +27,7 @@ function realOrNull(p        , fsImpl     )                {
 
 function failed(reason        , detail        )      {
   return {
-    ok: false, reason, detail, current: null, main: null, mainReason: null, others: [], isLinked: false, sandbox: false,
+    ok: false, reason, detail, current: null, main: null, mainReason: null, others: [], isLinked: false, sandbox: false, entries: [],
   };
 }
 
@@ -38,13 +38,16 @@ function failed(reason        , detail        )      {
  * 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.
+ * to be isolated. `entries` is every non-bare checkout that exists, in porcelain order, with its
+ * branch (`refs/heads/` stripped; null when detached) and HEAD from the same porcelain; from a
+ * sandbox it is the sandbox alone. 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}}
+ *   mainReason: string|null, others: Array<string>, isLinked: boolean, sandbox: boolean,
+ *   entries: Array<{path: string, branch: string|null, head: string|null, sandbox: boolean}>}}
  */
 function listCheckouts({ cwd, exec = spawnSync, fsImpl = fs }                                           )      {
   const realCwd = realOrNull(cwd, fsImpl) || path.resolve(cwd);
@@ -72,15 +75,23 @@ function listCheckouts({ cwd, exec = spawnSync, fsImpl = fs }
 }
 
 function fromPorcelain(stdout        , realCwd        , fsImpl     )      {
-  const entries                                                                  = [];
+  const entries                                                                                                              = [];
   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);
+    const value = (prefix        )                => {
+      const line = lines.find((l) => l.startsWith(prefix));
+      return line === undefined ? null : line.slice(prefix.length);
+    };
+    const ref = value('branch ');
+    const head = value('HEAD ');
     entries.push({
       real,
       bare: lines.includes('bare'),
       sandbox: real !== null && fsImpl.existsSync(path.join(real, BASE_FILE)),
+      branch: ref === null ? null : ref.replace(/^refs\/heads\//, ''),
+      head: head !== null && /^[0-9a-f]{40,64}$/.test(head) && !/^0+$/.test(head) ? head : null,
     });
   }
 
@@ -104,6 +115,10 @@ function fromPorcelain(stdout        , realCwd        , fsImpl     )      {
     .filter((e) => e.real !== null && !e.bare && !e.sandbox && e !== current)
     .map((e) => e.real          );
   const currentPath = current ? current.real : null;
+  const seen = new Set        ();
+  const listed = (sandbox ? [current] : entries)
+    .filter((e     ) => e.real !== null && !e.bare && !seen.has(e.real) && seen.add(e.real))
+    .map((e     ) => ({ path: e.real          , branch: e.branch, head: e.head, sandbox: e.sandbox }));
   return {
     ok: true,
     reason: null,
@@ -114,19 +129,52 @@ function fromPorcelain(stdout        , realCwd        , fsImpl     )      {
     others: [...new Set(others)],
     isLinked: currentPath !== null && main !== null && currentPath !== main,
     sandbox,
+    entries: listed,
   };
 }
 
+/**
+ * The `listCheckouts` entry whose path is the longest real-path prefix of `p` (`p` itself when it
+ * cannot be resolved), or null. A sandbox entry can be the answer, so a caller tells a sandbox
+ * nested under a checkout apart from that checkout. Writes nothing.
+ */
+function checkoutContaining(entries                                           , p         , fsImpl      = fs)      {
+  if (typeof p !== 'string' || !path.isAbsolute(p)) return null;
+  const real = realOrNull(p, fsImpl) || path.resolve(p);
+  let best      = null;
+  for (const e of entries) {
+    if ((real === e.path || real.startsWith(e.path + path.sep)) && (best === null || e.path.length > best.path.length)) best = e;
+  }
+  return best;
+}
+
 /** Forgets every memoized `listCheckouts` result (tests that rebuild a repository in place). */
 function clearCheckoutCache()       {
   cache.clear();
 }
 
+/** Whether `dir` can sit in a linked worktree: the nearest `.git` above it is a file (a worktree's
+ * pointer), not the main checkout's directory. A main checkout then needs no `git worktree list`. */
+function mayBeLinked(dir        , fsImpl      = fs)          {
+  for (let at = path.resolve(dir); ; at = path.dirname(at)) {
+    try { return fsImpl.statSync(path.join(at, '.git')).isFile(); } catch { /* not here */ }
+    if (path.dirname(at) === at) return false;
+  }
+}
+
+/** Whether two files hold the same bytes; a file that cannot be read differs from any other. */
+function sameBytes(a        , b        , fsImpl     )          {
+  try { return fsImpl.readFileSync(a).equals(fsImpl.readFileSync(b)); } catch { return false; }
+}
+
 /**
  * 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
+ * From a linked worktree the main checkout is read first, since every per-task record lives there
+ * (115 IC-004): a copy at the same path in the worktree with other bytes is a `conflict` (C-3),
+ * never a pick; with none in the main checkout the worktree's own is read, then the others. From any
+ * other checkout the current one 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
@@ -135,8 +183,9 @@ function clearCheckoutCache()       {
  *   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>}}
+ * @returns {{status: 'found'|'missing'|'ambiguous'|'conflict', file: string|null, root: string|null,
+ *   origin: 'current'|'other'|null, candidates: Array<string>}} `conflict` names the worktree's file
+ *   then the main checkout's
  */
 function findStateFile({ stateRoot, relPath, exec = spawnSync, fsImpl = fs }                                                               )      {
   const at = (root        , isCurrent         )                => {
@@ -149,14 +198,27 @@ function findStateFile({ stateRoot, relPath, exec = spawnSync, fsImpl = fs }
     return null;
   };
   const missing = { status: 'missing', file: null, root: null, origin: null, candidates: []             };
-
+  const linked = mayBeLinked(stateRoot, fsImpl) ? listCheckouts({ cwd: stateRoot, exec, fsImpl }) : null;
+  const main = linked?.ok && linked.isLinked && !linked.sandbox ? linked.main : null;
+
+  if (main) {
+    const there = at(main, false);
+    if (there) {
+      const copy = path.join(stateRoot, path.relative(main, there));
+      if (fsImpl.existsSync(copy) && !sameBytes(copy, there, fsImpl)) {
+        return { status: 'conflict', file: null, root: null, origin: null, candidates: [copy, there] };
+      }
+      return { status: 'found', file: there, root: main, origin: 'other', candidates: [] };
+    }
+  }
   const here = at(stateRoot, true);
   if (here) return { status: 'found', file: here, root: stateRoot, origin: 'current', candidates: [] };
 
-  const checkouts = listCheckouts({ cwd: stateRoot, exec, fsImpl });
+  const checkouts = linked || listCheckouts({ cwd: stateRoot, exec, fsImpl });
   if (!checkouts.ok || checkouts.sandbox) return missing;
   const matches                                        = [];
   for (const root of checkouts.others            ) {
+    if (root === main) continue;
     const file = at(root, false);
     if (file) matches.push({ file, root });
   }
@@ -167,4 +229,4 @@ function findStateFile({ stateRoot, relPath, exec = spawnSync, fsImpl = fs }
   return { status: 'found', file: matches[0].file, root: matches[0].root, origin: 'other', candidates: [] };
 }
 
-module.exports = { listCheckouts, findStateFile, clearCheckoutCache };
+module.exports = { listCheckouts, findStateFile, clearCheckoutCache, mayBeLinked, checkoutContaining };

package/src/runtime/claims.js

@@ -8,7 +8,7 @@ const crypto = require('node:crypto');
 // Shared with EvidenceLedger so both stores enforce one definition of a safe task id.
 const { assertSafeTaskId, EvidenceLedger } = require('./evidence-ledger.js');
 const { updateTaskState, readTaskState, mergeRecords } = require('./task-state.js');
-const { taskStoreDir } = require('./task-scope.js');
+const { taskRecord } = require('./task-scope.js');
 const { finishRuntime, usageError } = require('./cli-result.js');
 const { REPO_ROOT } = require('../helper/repo-root.js');
 
@@ -67,11 +67,16 @@ class ClaimsManager {
     this.seq = 0;
   }
 
-  /** Where this task's claims file lives: beside its evidence, in the feature's namespace when it has one. */
+  /** Where this task's claims file is written: beside its evidence, in the feature's namespace when it has one. */
   fileFor(taskId     ) {
-    const dir = this.fixedStateDir
-      || taskStoreDir({ projectRoot: this.repoRoot, store: 'evidence', taskId, slug: this.slug });
-    return path.join(dir, `${assertSafeTaskId(taskId)}_claims.json`);
+    return this.recordFor(taskId).file;
+  }
+
+  /** The task's claims file, where it is read from and the write lock's seed (task-scope.ts). */
+  recordFor(taskId     ) {
+    const name = `${assertSafeTaskId(taskId)}_claims.json`;
+    if (this.fixedStateDir) { const file = path.join(this.fixedStateDir, name); return { file, read: file, seed: () => {} }; }
+    return taskRecord({ projectRoot: this.repoRoot, store: 'evidence', taskId, slug: this.slug, name, fsImpl: this.fsImpl });
   }
 
   generateId() {
@@ -193,22 +198,28 @@ class ClaimsManager {
     }
 
     let hasFreshSupport = false;
-    let hasFreshContradiction = false;
     let hasStaleSupport = false;
+    let hasFreshContradiction = false;
+    let hasUnknownContradiction = false;
 
     for (const evId of claim.supportingEvidence) {
       const ev = this.evidenceLedger ? this.evidenceLedger.getEvidence(evId) : null;
       if (!ev || ev.freshness?.status === 'STALE') {
         hasStaleSupport = true;
-      } else {
+      } else if (ev.freshness?.status === 'FRESH') {
         hasFreshSupport = true;
       }
     }
 
     for (const evId of claim.contradictingEvidence) {
       const ev = this.evidenceLedger ? this.evidenceLedger.getEvidence(evId) : null;
-      if (ev && ev.freshness?.status !== 'STALE') {
-        hasFreshContradiction = true;
+      if (ev) {
+        const status = ev.freshness?.status;
+        if (status === 'FRESH') {
+          hasFreshContradiction = true;
+        } else if (status !== 'STALE') {
+          hasUnknownContradiction = true;
+        }
       }
     }
 
@@ -219,9 +230,12 @@ class ClaimsManager {
       // settled. Support that has merely gone stale still counts as support, so a claim that once
       // had backing stays 'conflicted' rather than being declared false on a technicality.
       claim.status = claim.supportingEvidence.length === 0 ? 'rejected' : 'conflicted';
+    } else if (hasUnknownContradiction) {
+      // A contradiction whose freshness is unknown cannot prove the claim false, so it never yields 'rejected' (DEC-016).
+      claim.status = claim.supportingEvidence.length > 0 ? 'conflicted' : 'hypothesis';
     } else if (hasFreshSupport) {
       claim.status = 'supported';
-    } else if (hasStaleSupport && !hasFreshSupport) {
+    } else if (hasStaleSupport) {
       claim.status = 'invalidated';
     } else {
       claim.status = 'hypothesis';
@@ -323,9 +337,10 @@ class ClaimsManager {
    * @returns {string} filePath
    */
   save(taskId = 'default')         {
-    const targetFile = this.fileFor(taskId);
+    const { file: targetFile, seed } = this.recordFor(taskId);
     let merged     ;
     const file = updateTaskState({
+      prepare: seed,
       fsImpl: this.fsImpl,
       file: targetFile,
       build: (disk     ) => {
@@ -346,7 +361,7 @@ class ClaimsManager {
    * @returns {number}
    */
   load(taskId = 'default')         {
-    const targetFile = this.fileFor(taskId);
+    const targetFile = this.recordFor(taskId).read;
     const data = readTaskState(this.fsImpl, targetFile);
     if (data && Array.isArray(data.claims)) {
       for (const item of data.claims) {

package/src/runtime/cli-result.js

@@ -11,6 +11,13 @@
  * it, and requires only the mask module.
  */
 
+const EXIT                         = Object.freeze({
+  OK: 0,
+  EMPTY: 1,
+  USAGE: 2,
+  OVERFLOW: 3,
+});
+
 /**
  * Sets the process exit code.
  * @param {number} code
@@ -46,10 +53,10 @@ function captureCaught(error     , command        , exit        )       {
  * @returns {number} 2 (USAGE error exit code)
  */
 function usageError(verb        , message        , json          , error        )         {
-  if (error !== undefined) captureCaught(error, verb, 2);
-  if (json) console.log(JSON.stringify({ ok: false, status: 'USAGE', exitCode: 2, error: 'usage', summary: message }, null, 2));
+  if (error !== undefined) captureCaught(error, verb, EXIT.USAGE);
+  if (json) console.log(JSON.stringify({ ok: false, status: 'USAGE', exitCode: EXIT.USAGE, error: 'usage', summary: message }, null, 2));
   else console.error(`doflow ${verb}: ${message}`);
-  return finishRuntime(2);
+  return finishRuntime(EXIT.USAGE);
 }
 
-module.exports = { finishRuntime, usageError, captureCaught };
+module.exports = { finishRuntime, usageError, captureCaught, EXIT };