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

package/src/runtime/mcp-reach.js

@@ -0,0 +1,157 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * MCP reach: for each harness the ledgers say is installed, which MCP servers does that harness
+ * have — selected from DoFlow's catalog, configured by hand, absent, or out of the catalog's reach.
+ * Read-only: it reads the same ledgers `evaluateReach` reads and asks each adapter's `discover()`
+ * for the server names it can see (`mcpConfigured`) and whether that view is complete
+ * (`mcpComplete`). A server is reported absent only from a complete view; otherwise its state is
+ * unknown. It never starts a server and opens no connection, so the same inputs give the same answer.
+ *
+ * Server names come from the registries only (`mcp.json`, and the `mcp.server` of capability
+ * providers); nothing here names one.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { readLedger } = require('../state/index.js');
+const { resolveAdapter } = require('../adapters/index.js');
+const { evaluateReach } = require('./reach.js');
+
+const SCOPE_ORDER                         = { project: 0, global: 1 };
+
+/** Every server id the answer covers: the MCP catalog, then each provider's own MCP server. */
+function serverIdsOf(registry     ) {
+  const ids = (registry.mcp || []).map((server     ) => server.id);
+  for (const capability of (Object.values(registry.capabilities || {})         )) {
+    for (const provider of capability.providers || []) if (provider.mcp?.server) ids.push(provider.mcp.server);
+  }
+  return [...new Set(ids)];
+}
+
+/** The MCP file an adapter's discovery could not read and the fixed reason it gives, or null.
+ * Reasons come from the adapters (invalid JSON, wrong shape), never from file content. */
+function unreadableDetail(discovery     ) {
+  for (const [file, read] of (Object.entries(discovery.mcpSnapshot || {})                   )) if (read?.ok === false) return { detail: read.reason, file };
+  for (const [file, read] of (Object.entries(discovery.mcp || {})                   )) if (read?.doc?.ok === false) return { detail: read.doc.reason, file };
+  if (discovery.settings?.error) return { detail: 'invalid JSON', ...(discovery.paths?.settings ? { file: discovery.paths.settings } : {}) };
+  return null;
+}
+
+/** A server is absent (`not-taken`, `not-selected`) only where the adapter read every source its
+ * harness merges (`mcpComplete: true`); anywhere else absence is no proof and the state is unknown. */
+function stateOf(row     , id     ) {
+  if (row.selected.has(id)) return 'selected';
+  if (row.configured?.includes(id)) return 'configured';
+  if (row.unreadable || row.configured === null || !row.complete) return 'unknown';
+  return row.catalog === 'not-taken' ? 'not-taken' : 'not-selected';
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} options.registry loaded registry
+ * @param {string} options.projectRoot
+ * @param {string} [options.homeDir]
+ * @param {Object} [options.fsImpl]
+ * @param {Object} options.adapters adapter registry (`buildAdapterRegistry()`)
+ * @returns {{harnesses: Object[], unreadable: Object[]}} plain data; `anyHarnessHas` and `addCommand` ride along unenumerated
+ */
+function mcpReach({ registry, projectRoot, homeDir = os.homedir(), fsImpl = fs, adapters }     ) {
+  const serverIds = serverIdsOf(registry);
+  const catalogIds = (registry.mcp || []).map((server     ) => server.id);
+  const harnessOrder = registry.harnesses.map((harness     ) => harness.id);
+  const { rows: reached } = evaluateReach({ registry, projectRoot, homeDir, fsImpl });
+
+  const ledgers = new Map();
+  const ledgerOf = ({ scope, installRoot }     ) => {
+    const key = `${scope}\0${installRoot}`;
+    if (!ledgers.has(key)) {
+      let ledger = null;
+      try { ledger = readLedger(path.join(installRoot, '.doflow', 'state'), { fsImpl }); } catch { /* evaluateReach reports it */ }
+      ledgers.set(key, ledger);
+    }
+    return ledgers.get(key);
+  };
+
+  const unreadable = [];
+  const seen = new Set();
+  const rows        = [];
+  for (const { harness: id, scope, installRoot } of reached) {
+    const key = `${id}\0${scope}\0${installRoot}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const harness = registry.harnesses.find((item     ) => item.id === id);
+    const ledger = ledgerOf({ scope, installRoot });
+    const mcp = harness.capabilities?.mcp;
+    const row = {
+      id, scope, installRoot, displayName: harness.displayName || id,
+      catalog: mcp?.status === 'supported' ? 'taken' : 'not-taken',
+      note: mcp?.note ?? mcp?.verification,
+      selected: new Set((ledger?.resources || [])
+        .filter((resource     ) => resource.harness === id && resource.kind === 'mcp-server').map((resource     ) => resource.identity)),
+      configured: null,
+      complete: false,
+      unreadable: false,
+    };
+    try {
+      const discovery = resolveAdapter(adapters, harness).discover({
+        scope, scopeRoot: installRoot, homeDir, mcp: [], mcpAdoptable: [], ledger, registry, context: { homeDir },
+      });
+      row.configured = Array.isArray(discovery.mcpConfigured) ? discovery.mcpConfigured : null;
+      row.complete = discovery.mcpComplete === true;
+      const found = unreadableDetail(discovery);
+      if (found) { row.unreadable = true; unreadable.push({ harness: id, scope, ...found }); }
+    } catch (error     ) {
+      row.unreadable = true;
+      unreadable.push({ harness: id, scope, detail: error.message });
+    }
+    rows.push(row);
+  }
+  rows.sort((a, b) => harnessOrder.indexOf(a.id) - harnessOrder.indexOf(b.id)
+    || SCOPE_ORDER[a.scope] - SCOPE_ORDER[b.scope] || a.installRoot.localeCompare(b.installRoot));
+
+  const result = {
+    harnesses: rows.map((row) => {
+      const entry      = { id: row.id, scope: row.scope, catalog: row.catalog };
+      if (row.catalog === 'not-taken' && row.note) entry.note = row.note;
+      entry.servers = Object.fromEntries(serverIds.map((server) => [server, stateOf(row, server)]));
+      return entry;
+    }),
+    unreadable,
+  };
+
+  /** `true` when a server is selected or configured on some installed harness, `false` only when
+   * every installed harness read every source it merges and says it is absent, `null` (unknown)
+   * otherwise, including when none is installed. */
+  const anyHarnessHas = (server     ) => {
+    const states = rows.map((row) => stateOf(row, server));
+    if (states.some((state) => state === 'selected' || state === 'configured')) return true;
+    return states.length > 0 && states.every((state) => state === 'not-selected' || state === 'not-taken') ? false : null;
+  };
+
+  /** The command that adds `serverId` for a harness at a scope, or where to configure it by hand. */
+  const addCommand = (harnessId     , scope     , serverId     ) => {
+    const harness = registry.harnesses.find((item     ) => item.id === harnessId);
+    const name = harness?.displayName || harnessId;
+    if (harness?.capabilities?.mcp?.status !== 'supported') {
+      return `configure it in ${name}'s own MCP settings; DoFlow's catalog does not reach it`;
+    }
+    if (!catalogIds.includes(serverId)) {
+      return `configure it in ${name}'s own MCP settings; DoFlow's catalog does not carry ${serverId}`;
+    }
+    const chosen = new Set([serverId]);
+    for (const row of rows) if (row.id === harnessId && row.scope === scope) for (const id of row.selected) chosen.add(id);
+    return `doflow install${scope === 'global' ? ' -g' : ''} --target ${harnessId} --mcp ${catalogIds.filter((id     ) => chosen.has(id)).join(',')}`;
+  };
+
+  Object.defineProperties(result, {
+    anyHarnessHas: { value: anyHarnessHas },
+    addCommand: { value: addCommand },
+  });
+  return result;
+}
+
+module.exports = { mcpReach };

package/src/runtime/model-router.js

@@ -0,0 +1,153 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Model role router. DoFlow binds no model for the harness's own work; the runtime calls a
+// configured local decision model only for advisory picks. This resolves an abstract role from
+// core/registry/models.json into availability-annotated provider candidates that skills,
+// orchestration snapshots, or operators act on through each harness's native model selection.
+// Policy strings (prefer/fallback/require) pass through verbatim — the registry owns them; this
+// module owns matching them against providers' declared tiers and what is installed right now.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadRegistry } = require('../registry/index.js');
+const { finishRuntime, usageError, captureCaught } = require('./cli-result.js');
+const { REPO_ROOT } = require('../helper/repo-root.js');
+
+/** The machine-level command each provider's backend answers to. A provider without a local CLI
+ * (hosted-only access through another harness) reports backendCli null and is never "available". */
+const BACKEND_CLI                                   = Object.freeze({ claude: 'claude', codex: 'codex', copilot: 'copilot', ollama: 'ollama' });
+
+function whichLike(command                    , { fsImpl = fs, pathEnv = process.env.PATH }                                     = {})          {
+  if (!command) return false;
+  for (const dir of String(pathEnv ?? '').split(path.delimiter)) {
+    if (!dir) continue;
+    try {
+      const candidate = path.join(dir, command);
+      fsImpl.accessSync(candidate, fs.constants.X_OK);
+      return true;
+    } catch { /* keep scanning */ }
+  }
+  return false;
+}
+
+/** Providers whose backend CLI resolves on PATH. Injectable in tests; never guessed otherwise. */
+function availableProviderIds({ fsImpl = fs }                   = {})           {
+  return Object.entries(BACKEND_CLI)
+    .filter(([, cli]) => whichLike(cli, { fsImpl }))
+    .map(([id]) => id);
+}
+
+/**
+ * Resolve one role to ranked candidates.
+ * Ordering: available first, then preferred-tier match, then fallback-tier match, registry order
+ * breaking ties. `exclude` drops provider ids entirely (e.g. the implementer when the role is
+ * review with require:different-family) and is reported back rather than hidden.
+ * Availability unknown stays null — absence of evidence is not reported as absent.
+ */
+function resolveModelRole({ registry, roleId, isAvailable = null, exclude = [] }      = {})      {
+  const role = (registry.modelRoles || []).find((entry     ) => entry.id === roleId);
+  if (!role) {
+    throw new Error(`Unknown model role '${roleId}'; valid: ${(registry.modelRoles || []).map((r     ) => r.id).join(', ')}`);
+  }
+  const excluded = new Set(exclude);
+  const candidates        = [];
+  for (const [index, provider] of (registry.modelProviders || []).entries()) {
+    if (excluded.has(provider.id)) continue;
+    const tiers = provider.tiers ?? [];
+    candidates.push({
+      id: provider.id,
+      kind: provider.kind,
+      displayName: provider.displayName,
+      backendCli: BACKEND_CLI[provider.id] ?? null,
+      available: isAvailable ? Boolean(isAvailable(provider.id)) : null,
+      servesPreferredTier: role.prefer ? tiers.includes(role.prefer) : null,
+      servesFallbackTier: role.fallback ? tiers.includes(role.fallback) : null,
+      _index: index,
+    });
+  }
+  const rank = (candidate     )           => [
+    candidate.available === true ? 0 : candidate.available === false ? 1 : 2,
+    candidate.servesPreferredTier ? 0 : 1,
+    candidate.servesFallbackTier ? 0 : 1,
+    candidate._index,
+  ];
+  candidates.sort((a     , b     ) => {
+    const ra = rank(a); const rb = rank(b);
+    for (let i = 0; i < ra.length; i += 1) if (ra[i] !== rb[i]) return ra[i] - rb[i];
+    return 0;
+  });
+  for (const candidate of candidates) delete candidate._index;
+  return {
+    roleId,
+    policy: { prefer: role.prefer ?? null, fallback: role.fallback ?? null, require: role.require ?? null },
+    candidates,
+    excluded: [...excluded],
+  };
+}
+
+/**
+ * Resolve one optional dense/rerank retrieval slot from core/registry/models.json. A slot binds a
+ * retrieval stage (`dense` embedding lookup, `rerank` cross-encoder pass) to one declared provider
+ * and the concrete model that provider serves; it takes effect only while `enabled`. Absent or
+ * disabled slots resolve to `{active:false}` and every caller stays on its existing lexical/graph
+ * path unchanged — this function never routes anywhere on its own. An enabled slot resolves to the
+ * bound provider with availability probed through the same injected seam resolveModelRole uses
+ * (PATH scan for the provider's backend CLI); `available:false` or `null` tells the caller to stay
+ * lexical rather than guess. Unknown slot ids also resolve to `{active:false}` rather than
+ * throwing: absence of a slot is every install's normal state, unlike an unknown role.
+ */
+function resolveRetrievalSlot({ registry, slotId, isAvailable = null }      = {})      {
+  const slot = (registry.retrievalSlots || []).find((entry     ) => entry.id === slotId);
+  if (!slot || !slot.enabled) return { slotId, active: false, reason: slot ? 'disabled' : 'undeclared' };
+  const provider = (registry.modelProviders || []).find((entry     ) => entry.id === slot.provider);
+  if (!provider) return { slotId, active: false, reason: 'provider-missing' };
+  return {
+    slotId,
+    active: true,
+    reason: null,
+    provider: provider.id,
+    displayName: provider.displayName,
+    kind: provider.kind,
+    backendCli: BACKEND_CLI[provider.id] ?? null,
+    model: slot.model,
+    available: isAvailable ? Boolean(isAvailable(provider.id)) : null,
+  };
+}
+
+/** CLI handler for `doflow model-role`. Read-only advisory routing; exits 1 on an unknown role
+ * because a silently-empty candidate list would read as "no providers" rather than "bad input". */
+function handleModelRoleCommand({ role, exclude, json = false, repoRoot }      = {})                     {
+  if (!role) return usageError('model-role', '--role is required (one of the roles in core/registry/models.json)', json);
+  const registry = (() => {
+    try { return loadRegistry({ repoRoot: repoRoot || REPO_ROOT }); }
+    catch (error     ) { captureCaught(error, 'model-role', 1); console.error(`[ERROR] model-role: ${error.message}`); return finishRuntime(1); }
+  })();
+  if (!registry) return undefined;
+  const available = new Set(availableProviderIds());
+  try {
+    const resolution = resolveModelRole({
+      registry,
+      roleId: role,
+      isAvailable: (providerId        ) => available.has(providerId),
+      exclude: Array.isArray(exclude) ? exclude : String(exclude ?? '').split(',').map((s        ) => s.trim()).filter(Boolean),
+    });
+    if (json) console.log(JSON.stringify(resolution, null, 2));
+    else {
+      console.log(`Role '${resolution.roleId}' — prefer:${resolution.policy.prefer ?? '—'} fallback:${resolution.policy.fallback ?? '—'} require:${resolution.policy.require ?? '—'}`);
+      for (const candidate of resolution.candidates) {
+        const availability = candidate.available === null ? '?' : candidate.available ? 'yes' : 'no';
+        console.log(`  ${candidate.available ? '*' : ' '} ${candidate.id} (${candidate.kind}, via ${candidate.backendCli ?? 'hosted'}) available=${availability}${resolution.policy.prefer && candidate.servesPreferredTier ? ` serves ${resolution.policy.prefer}` : ''}`);
+      }
+      if (resolution.excluded.length) console.log(`Excluded: ${resolution.excluded.join(', ')}`);
+    }
+    return finishRuntime(0);
+  } catch (error     ) {
+    captureCaught(error, 'model-role', 1);
+    console.error(`[ERROR] model-role: ${error.message}`);
+    return finishRuntime(1);
+  }
+}
+
+module.exports = { resolveModelRole, resolveRetrievalSlot, handleModelRoleCommand, availableProviderIds, BACKEND_CLI };