@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/advice/doctor.js

@@ -76,7 +76,7 @@ async function buildAdviceDoctor({ repoRoot = REPO_ROOT, projectRoot = process.c
     const registry = loaded.registry;
     const storage = suppliedStorage || loadStorageRegistry({ repoRoot: root, fsImpl });
     const roots = resolveRoots({ registry: storage, projectRoot, env });
-    const setting = loaded.ok ? resolveSetting({ adviceRegistry: registry, roots, fsImpl }) : {
+    const setting = loaded.ok ? resolveSetting({ adviceRegistry: registry, roots, env, fsImpl }) : {
       state: 'off', reason: 'config-invalid', decidedBy: { user: null, project: null }, modelFrom: null, notes: [loaded.detail],
     };
     const store = selectedStore(roots);

package/src/runtime/advice/elevation.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+const TIER_ORDER                         = Object.freeze({
+  light: 0,
+  standard: 1,
+  frontier: 2,
+});
+
+// Risk order = key order of riskLevels in core/registry/verification.json, read once.
+// An unreadable registry gives an empty order, which means "never elevated".
+function loadVerifyRiskOrder()                         {
+  const order                         = {};
+  try {
+    const registry = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'core/registry/verification.json'), 'utf8'));
+    Object.keys(registry.riskLevels).forEach((level, i) => { order[level.toLowerCase()] = i; });
+  } catch {
+    return Object.freeze({});
+  }
+  return Object.freeze(order);
+}
+
+const VERIFY_RISK_ORDER                         = loadVerifyRiskOrder();
+
+const REVIEW_DEPTH_ORDER                         = Object.freeze({
+  single: 0,
+  deep: 1,
+});
+
+const TASK_CLASS_ORDER                         = Object.freeze({
+  'trivial-edit': 0,
+  'refactor': 1,
+  'bug': 1,
+  'dependency-change': 1,
+  'feature': 2,
+});
+
+function applyElevationInvariant(
+  kind        ,
+  staticPick        ,
+  advisorPick               
+)                                                   {
+  if (!advisorPick || typeof advisorPick !== 'string' || !advisorPick.trim()) {
+    return { effectiveDecision: staticPick, elevated: false };
+  }
+
+  const advisorClean = advisorPick.trim();
+
+  if (kind === 'tier') {
+    const sRank = TIER_ORDER[staticPick.toLowerCase()];
+    const aRank = TIER_ORDER[advisorClean.toLowerCase()];
+    if (sRank !== undefined && aRank !== undefined && aRank > sRank) {
+      return { effectiveDecision: advisorClean, elevated: true };
+    }
+    return { effectiveDecision: staticPick, elevated: false };
+  }
+
+  if (kind === 'verify-risk') {
+    const sRank = VERIFY_RISK_ORDER[staticPick.toLowerCase()];
+    const aRank = VERIFY_RISK_ORDER[advisorClean.toLowerCase()];
+    if (sRank !== undefined && aRank !== undefined && aRank > sRank) {
+      return { effectiveDecision: advisorClean, elevated: true };
+    }
+    return { effectiveDecision: staticPick, elevated: false };
+  }
+
+  if (kind === 'review-depth') {
+    const sRank = REVIEW_DEPTH_ORDER[staticPick.toLowerCase()];
+    const aRank = REVIEW_DEPTH_ORDER[advisorClean.toLowerCase()];
+    if (sRank !== undefined && aRank !== undefined && aRank > sRank) {
+      return { effectiveDecision: advisorClean, elevated: true };
+    }
+    return { effectiveDecision: staticPick, elevated: false };
+  }
+
+  if (kind === 'task-class') {
+    const sRank = TASK_CLASS_ORDER[staticPick.toLowerCase()];
+    const aRank = TASK_CLASS_ORDER[advisorClean.toLowerCase()];
+    if (sRank !== undefined && aRank !== undefined && aRank > sRank) {
+      return { effectiveDecision: advisorClean, elevated: true };
+    }
+    return { effectiveDecision: staticPick, elevated: false };
+  }
+
+  return { effectiveDecision: staticPick, elevated: false };
+}
+
+module.exports = {
+  applyElevationInvariant,
+  TIER_ORDER,
+  VERIFY_RISK_ORDER,
+  REVIEW_DEPTH_ORDER,
+  TASK_CLASS_ORDER,
+};

package/src/runtime/advice/endpoint-guard.js

@@ -68,19 +68,25 @@ function refuse(value     , file         )                                 {
   };
 }
 
-function lookupAll(host        , lookup     , timeoutMs         )               {
+/** `signal`, when given, ends the lookup the way its timeout does; an already-aborted signal skips the lookup. */
+function lookupAll(host        , lookup     , timeoutMs         , signal      )               {
   return new Promise((resolve, reject) => {
+    const aborted = () => Object.assign(new Error('decision model DNS validation aborted by the caller'), { code: 'ADVICE_TIMEOUT' });
+    if (signal?.aborted) { reject(aborted()); return; }
     let settled = false;
+    const onAbort = () => finish(aborted());
     const finish = (error     , addresses      ) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
       if (error) reject(error);
       else resolve(addresses);
     };
     const timer = Number.isFinite(timeoutMs) ? setTimeout(() => {
       finish(Object.assign(new Error('decision model DNS validation timed out'), { code: 'ADVICE_TIMEOUT' }));
     }, Math.max(0, timeoutMs          )) : undefined;
+    signal?.addEventListener?.('abort', onAbort, { once: true });
     try {
       const returned = lookup(host, { all: true, verbatim: true }, finish);
       if (returned && typeof returned.then === 'function') returned.then((addresses     ) => finish(null, addresses), finish);
@@ -103,7 +109,7 @@ function pinnedLookup(address        , family        ) {
   };
 }
 
-async function checkEndpoint(value     , { lookup = dns.lookup, file, timeoutMs }      = {})               {
+async function checkEndpoint(value     , { lookup = dns.lookup, file, timeoutMs, signal }      = {})               {
   const display = displayEndpoint(value);
   let url     ;
   try { url = new URL(display); } catch { return refuse(display, file); }
@@ -117,7 +123,7 @@ async function checkEndpoint(value     , { lookup = dns.lookup, file, timeoutMs
   }
 
   let addresses     ;
-  try { addresses = await lookupAll(host, lookup, timeoutMs); } catch (error     ) {
+  try { addresses = await lookupAll(host, lookup, timeoutMs, signal); } catch (error     ) {
     if (error?.code === 'ADVICE_TIMEOUT') return { ok: false, reason: 'timeout', message: error.message };
     return refuse(display, file);
   }

package/src/runtime/advice/mode.js

@@ -0,0 +1,37 @@
+'use strict';
+
+// How a chosen rollout profile caps advice. One table for the dispatcher (set kinds) and the callers' unset-kind path.
+
+const { resolveRolloutProfile } = require('../profiles/resolve.js');
+
+                                                      
+                                           
+
+/**
+ * The rollout profile's advisor capability, or null when no profile was chosen. It caps advice only when a
+ * profile was chosen (env or settings), a rollback is active or the value is invalid; a project that sets no
+ * profile (origin registry-default) keeps advice as configured.
+ */
+function profileAdvisorCap({ projectRoot, env, fsImpl }                                                                                   = {})                    {
+  const readable = typeof fsImpl?.readFileSync === 'function' ? fsImpl : undefined;
+  const profile = resolveRolloutProfile({ projectRoot, env, fsImpl: readable });
+  if (profile.origin.source === 'default' && profile.origin.detail === 'registry-default') return null;
+  return profile.capabilities.advisor;
+}
+
+/** The mode a set kind runs in under a cap. `staged` means shadow until a contract defines it (D2); anything unknown is off. */
+function capMode(cap         , configuredMode         )             {
+  if (configuredMode !== 'off' && configuredMode !== 'shadow' && configuredMode !== 'act') return 'off';
+  if (cap === null || cap === 'act') return configuredMode;
+  if (cap === 'shadow' || cap === 'staged') return configuredMode === 'act' ? 'shadow' : configuredMode;
+  return 'off';
+}
+
+/** What the unset-kind path does under a cap: the legacy ask (no cap, or act), shadow (record, never show or apply) or off. */
+function unsetKindPath(cap         )                              {
+  if (cap === null || cap === 'act') return 'legacy';
+  if (cap === 'shadow' || cap === 'staged') return 'shadow';
+  return 'off';
+}
+
+module.exports = { profileAdvisorCap, capMode, unsetKindPath };

package/src/runtime/advice/record.js

@@ -40,16 +40,26 @@ function appendLine({ roots, at, line, fsImpl = fs, store }     )
   }
 }
 
+const PICK_ID = /^adv-[0-9]{13}-[0-9a-f]{6}$/;
+
+function newPickId(epoch         = Date.now())         {
+  return `adv-${String(epoch).padStart(13, '0')}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+/**
+ * `pickId` lets a caller that returned an id before the line is written (the shadow dispatcher) keep it; `mode`
+ * and `elevated` are the dispatcher's and are written only when given.
+ */
 function appendPick({
   roots, now = () => new Date(), fsImpl = fs, kind, answer, question,
   staticAnswer = null, provider = null, model = null, state, caller, taskId = null, durationMs = 0,
+  pickId: givenPickId, mode, elevated,
 }      = {})                                                         {
   try {
     if (typeof state !== 'string' || !answer || !question) return null;
     const at = timestamp(now);
     if (!at) return null;
-    const epoch = Date.parse(at);
-    const pickId = `adv-${String(epoch).padStart(13, '0')}-${crypto.randomBytes(3).toString('hex')}`;
+    const pickId = typeof givenPickId === 'string' && PICK_ID.test(givenPickId) ? givenPickId : newPickId(Date.parse(at));
     const options = question.type === 'choice' ? Object.keys(question.options || {})
       : question.type === 'score' ? [...(question.criteria || [])] : ['no', 'yes'];
     const instructions = kind === 'adhoc' && typeof question.instructions === 'string'
@@ -78,6 +88,8 @@ function appendPick({
       taskId: taskId ?? null,
       durationMs: Number.isFinite(durationMs) ? durationMs : 0,
     };
+    if (mode !== undefined) line.mode = mode;
+    if (elevated !== undefined) line.elevated = elevated === true;
     if (answer.type === 'score') {
       line.criteria = [...(question.criteria || [])];
       line.pickIndex = answer.pickIndex;
@@ -90,15 +102,16 @@ function appendPick({
   }
 }
 
-function appendMiss({ roots, now = () => new Date(), fsImpl = fs, kind, caller, reason, model = null, durationMs = 0 }      = {})      {
+function appendMiss({ roots, now = () => new Date(), fsImpl = fs, kind, caller, reason, model = null, durationMs = 0, mode }      = {})      {
   try {
     const at = timestamp(now);
     if (!at) return null;
-    const line = {
+    const line      = {
       schema: 1, type: 'miss', at, kind, caller, reason,
       model: model ?? null,
       durationMs: Number.isFinite(durationMs) ? durationMs : 0,
     };
+    if (mode !== undefined) line.mode = mode;
     return appendLine({ roots, at, line, fsImpl });
   } catch { return null; }
 }
@@ -163,4 +176,4 @@ function findPick({ pickId, roots, now = () => new Date(), fsImpl = fs }      =
   return found ? { pick: found.record, file: found.file, store: found.store } : null;
 }
 
-module.exports = { appendPick, appendMiss, appendOutcome, readWindow, findPick };
+module.exports = { appendPick, appendMiss, appendOutcome, readWindow, findPick, newPickId };

package/src/runtime/advice/registry.js

@@ -9,6 +9,9 @@ const { REPO_ROOT } = require('../../helper/repo-root.js');
 const ADVICE_FILE = 'core/registry/advice.json';
 const MODELS_FILE = 'core/registry/models.json';
 const ADAPTER_DIR = 'src/runtime/advice/providers';
+// The adapter is a sibling module of this file, so it has this file's own extension: `.ts` in a
+// checkout, `.js` in the package `build:package` stages (every module there is stripped to `.js`).
+const ADAPTER_EXT = path.extname(__filename);
 const TIER_KIND = 'tier';
 const LIMIT_FIELDS = ['maxStateBytes', 'maxBodyBytes', 'minQuestions', 'maxQuestions', 'minOptions', 'maxOptions'];
 const BAND_FIELDS                           = {
@@ -107,7 +110,7 @@ function validateAdviceRegistry(registry     , { repoRoot = REPO_ROOT, models, f
         if (!/^[a-z][a-z0-9-]*$/.test(provider.adapter)) {
           addError(errors, `${base}.adapter`, 'must be a safe adapter id');
         } else {
-          const adapterFile = path.resolve(adapterRoot, `${provider.adapter}.ts`);
+          const adapterFile = path.resolve(adapterRoot, `${provider.adapter}${ADAPTER_EXT}`);
           if (!adapterFile.startsWith(`${adapterRoot}${path.sep}`) || !fsImpl.existsSync(adapterFile)) {
             addError(errors, `${base}.adapter`, `must name a file under ${ADAPTER_DIR}`);
           }

package/src/runtime/advice/shadow-config.js

@@ -0,0 +1,229 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveSetting } = require('./config.js');
+const { resolveRoots } = require('../storage/roots.js');
+const { loadStorageRegistry } = require('../storage/registry.js');
+const { configHome } = require('../config-home.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+                                               
+
+                            
+               
+                       
+     
+                                                                                                                    
+                                                                                          
+     
+                   
+                       
+              
+                        
+                         
+    
+                                                                                                      
+                        
+ 
+
+                               
+                       
+                                           
+               
+                                        
+                   
+ 
+
+                                                                                              
+
+function getSettingValue(obj     , key        )      {
+  if (!obj || typeof obj !== 'object') return undefined;
+  if (Object.hasOwn(obj, key)) return obj[key];
+  const parts = key.split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length; i++) {
+    if (!cur || typeof cur !== 'object') return undefined;
+    const p = parts[i];
+    if (Object.hasOwn(cur, p)) {
+      cur = cur[p];
+    } else {
+      const rest = parts.slice(i).join('.');
+      if (Object.hasOwn(cur, rest)) {
+        return cur[rest];
+      }
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+/** An absent file is missing; an unreadable file, bad JSON or a non-object value is an error (fail closed). */
+function readJsonFile(filePath        , fsImpl     )            {
+  let text        ;
+  try {
+    text = fsImpl.readFileSync(filePath, 'utf8');
+  } catch (error     ) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return { missing: true };
+    return { error: `could not be read (${error?.code || error?.message || 'unknown error'})` };
+  }
+  try {
+    const content = JSON.parse(text);
+    if (!content || typeof content !== 'object' || Array.isArray(content)) return { error: 'is not a JSON object' };
+    return { content };
+  } catch {
+    return { error: 'is not valid JSON' };
+  }
+}
+
+function resolveShadowConfig(
+  kind        ,
+  options                      
+)                   {
+  const fsImpl = options?.fsImpl || fs;
+  const env = options?.env ?? process.env;
+  const projectRoot = options?.projectRoot || process.cwd();
+
+  let storageRegistry      = null;
+  try {
+    storageRegistry = loadStorageRegistry({ repoRoot: REPO_ROOT, fsImpl });
+  } catch {
+    // best-effort registry loading
+  }
+
+  let roots = options?.roots;
+  if (!roots && storageRegistry) {
+    try {
+      roots = resolveRoots({ registry: storageRegistry, projectRoot, global: options?.global, env });
+    } catch {
+      roots = null;
+    }
+  }
+
+  // 1. The advice setting's model is the fallback when no layer names one for this kind.
+  let globalSetting      = null;
+  try {
+    globalSetting = resolveSetting({
+      roots,
+      storageRegistry,
+      projectRoot,
+      global: options?.global,
+      env,
+      fsImpl,
+    });
+  } catch {
+    globalSetting = null;
+  }
+
+  // 2. Discover configuration files across layers (project local -> project -> user)
+  const candidateFiles                                         = [];
+
+  if (projectRoot) {
+    candidateFiles.push({
+      layer: 'local',
+      path: path.join(projectRoot, '.doflow', 'settings.local.json'),
+    });
+    candidateFiles.push({
+      layer: 'project',
+      path: path.join(projectRoot, '.doflow', 'settings.json'),
+    });
+  }
+
+  const userHome = roots?.['config-home'] || configHome(env).dir;
+  const userConfigDir = userHome;
+
+  if (userConfigDir) {
+    candidateFiles.push({
+      layer: 'user',
+      path: path.join(userConfigDir, 'settings.json'),
+    });
+  }
+
+  const loadedCandidates                                                           = [];
+  const diagnostics           = [];
+  for (const { layer, path: filePath } of candidateFiles) {
+    const read = readJsonFile(filePath, fsImpl);
+    if ('content' in read) loadedCandidates.push({ layer, filePath, content: read.content });
+    else if ('error' in read) diagnostics.push(`${layer} settings ${filePath} ${read.error}; advice.kinds.${kind} is off`);
+  }
+
+  const defaultModel = globalSetting?.model || null;
+
+  // 3. Check advice.enabled: if explicitly false in any candidate layer, force mode = 'off'
+  let explicitDisabledBy                = null;
+  for (const { layer, filePath, content } of loadedCandidates) {
+    const enabledVal = getSettingValue(content, 'advice.enabled');
+    if (enabledVal === false) {
+      explicitDisabledBy = `${layer}:${filePath}`;
+      break;
+    }
+  }
+
+  const kindSet = diagnostics.length > 0
+    || loadedCandidates.some(({ content }) => getSettingValue(content, `advice.kinds.${kind}`) !== undefined);
+  let resolvedMode                 = 'off';
+  let modeDecidedBy                = null;
+
+  if (explicitDisabledBy) {
+    resolvedMode = 'off';
+    modeDecidedBy = explicitDisabledBy;
+  } else if (diagnostics.length === 0) {
+    // The first layer that has advice.kinds.<kind> decides; an invalid value there is off, never a lower layer's value.
+    for (const { layer, filePath, content } of loadedCandidates) {
+      const modeVal = getSettingValue(content, `advice.kinds.${kind}`);
+      if (modeVal === undefined) continue;
+      modeDecidedBy = `${layer}:${filePath}`;
+      if (modeVal === 'act' || modeVal === 'shadow' || modeVal === 'off') resolvedMode = modeVal;
+      else diagnostics.push(`${layer} settings ${filePath} has invalid advice.kinds.${kind} ${JSON.stringify(modeVal)} (expected off, shadow or act); it is off`);
+      break;
+    }
+  }
+
+  // 4. Resolve model: advice.models.<kind> -> advice.model (string) -> defaultModel
+  let resolvedModel                = null;
+  let modelDecidedBy                = null;
+
+  // Check per-kind model override
+  for (const { layer, filePath, content } of loadedCandidates) {
+    const kindModel = getSettingValue(content, `advice.models.${kind}`);
+    if (typeof kindModel === 'string' && kindModel.trim()) {
+      resolvedModel = kindModel.trim();
+      modelDecidedBy = `${layer}:${filePath}`;
+      break;
+    }
+  }
+
+  // Fallback to general advice.model (string) from candidate files
+  if (!resolvedModel) {
+    for (const { layer, filePath, content } of loadedCandidates) {
+      const generalModel = getSettingValue(content, 'advice.model');
+      if (typeof generalModel === 'string' && generalModel.trim()) {
+        resolvedModel = generalModel.trim();
+        modelDecidedBy = `${layer}:${filePath}`;
+        break;
+      }
+    }
+  }
+
+  // Fallback to defaultModel from global setting
+  if (!resolvedModel) {
+    resolvedModel = defaultModel;
+    modelDecidedBy = globalSetting?.decidedBy?.project || globalSetting?.decidedBy?.user || null;
+  }
+
+  return {
+    kind,
+    mode: resolvedMode,
+    kindSet,
+    model: resolvedModel,
+    decidedBy: {
+      mode: modeDecidedBy,
+      model: modelDecidedBy,
+    },
+    diagnostics,
+  };
+}
+
+module.exports = {
+  resolveShadowConfig,
+};