@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/cli.js

@@ -9,12 +9,14 @@ const { CapabilityRouter } = require('./capability-router.js');
 const { EvidenceLedger } = require('./evidence-ledger.js');
 const { ClaimsManager } = require('./claims.js');
 const { measureTreeState } = require('./source-version.js');
-const { toEvidence, validateEvidenceItem, EVIDENCE_REFUSED_FIELDS } = require('./candidate.js');
+const { fileRootFor } = require('./freshness.js');
+const { toEvidence, parseLocator, validateEvidenceItem, EVIDENCE_REFUSED_FIELDS } = require('./candidate.js');
 const { sourceModeLookup } = require('./retrieval-plan.js');
 const { evaluateTaskReadiness } = require('./readiness.js');
-const { writeReadinessRecord } = require('./readiness-record.js');
+const { writeReadinessRecord, readReadinessRecord } = require('./readiness-record.js');
+const { resolveTaskScope } = require('./task-scope.js');
 const { parseDeclaredScope } = require('./verification/scope-bound.js');
-const { loadRegistry } = require('../registry/index.js');
+const { loadRegistry, agentToolScopeView } = require('../registry/index.js');
 const { REPO_ROOT } = require('../helper/repo-root.js');
 // One definition of the exit and usage helpers (design §4.2); `finish` is the local spelling of `finishRuntime`.
 const { finishRuntime: finish, usageError } = require('./cli-result.js');
@@ -30,9 +32,10 @@ function handleCapabilitiesCommand({ json = false, check = false, repoRoot }
   const root = repoRoot || REPO_ROOT;
   const router = new CapabilityRouter({ repoRoot: root });
   const report = router.getAllCapabilitiesHealth(check);
+  const agentToolScope = agentToolScopeView(loadRegistry({ repoRoot: root, sources: 'skip' }));
 
   if (json) {
-    console.log(JSON.stringify({ capabilities: report }, null, 2));
+    console.log(JSON.stringify({ capabilities: report, agentToolScope }, null, 2));
     return;
   }
 
@@ -60,7 +63,36 @@ function handleCapabilitiesCommand({ json = false, check = false, repoRoot }
     );
   }
   console.log('═'.repeat(78));
-  console.log(`Mode: ${check ? 'Deep Smoke Check' : 'Fast Presence Check'} · Total Capabilities: ${report.length}\n`);
+  console.log(`Mode: ${check ? 'Deep Smoke Check' : 'Fast Presence Check'} · Total Capabilities: ${report.length}`);
+  console.log('\nAgent tool scope per harness (unenforced: no tool field is projected):');
+  for (const row of agentToolScope) console.log(`  ${row.harness.padEnd(14)}${row.status === 'native' ? `native      ${row.field}` : `unenforced  ${row.reason}`}`);
+  console.log('');
+}
+
+/**
+ * Fills `profile` with the caller-stated inputs the task's last readiness record for this template
+ * holds and this call did not pass. Returns the profile keys it filled.
+ * @returns {Array<string>}
+ */
+function carriedInputs({ profile, taskClass, taskId, slug, state }     )           {
+  const keyOf      = { verificationPlan: 'verificationPlan', scope: 'scopeClear', invariants: 'invariants' };
+  let prior      = null;
+  try {
+    const scope = resolveTaskScope({ projectRoot: state, taskId, slug });
+    const read = readReadinessRecord({ stateRoot: state, taskId, slug: scope.slug || slug || null });
+    if (read.status === 'found' && read.record && read.record.taskClass === taskClass) prior = read.record;
+  } catch {
+    return [];
+  }
+  const filled           = [];
+  for (const [inputKey, profileKey] of Object.entries(keyOf)) {
+    const value = prior && prior.inputs && prior.inputs[inputKey];
+    if (profile[profileKey          ] === undefined && typeof value === 'string' && value.trim() !== '') {
+      profile[profileKey          ] = value;
+      filled.push(profileKey          );
+    }
+  }
+  return filled;
 }
 
 /**
@@ -107,11 +139,16 @@ function handleReadinessCommand({
   if (typeof scopeClear === 'string' && scopeClear.trim() !== '') profile.scopeClear = scopeClear;
   if (typeof invariants === 'string' && invariants.trim() !== '') profile.invariants = invariants;
   if (userDecisionPending) profile.userDecisionPending = true;
+  // An input not passed this call is the one the task's last evaluation for this template stated, so
+  // a bare re-check after evidence changes does not discard the scope and plan a READY verdict rested
+  // on. Passing an input replaces it. Ceiling: an input can be replaced but not dropped, and
+  // `--user-decision-pending` is never carried.
+  const carried = carriedInputs({ profile, taskClass, taskId, slug, state });
   const callerAsserted = Object.keys(profile).filter((k) => k !== 'taskId' && k !== 'taskClass');
 
   let report;
   try {
-    report = evaluateTaskReadiness({ taskProfile: profile, repoRoot: root, projectRoot: state, treeRoot: sourceRoot || state, mode });
+    report = evaluateTaskReadiness({ taskProfile: profile, repoRoot: root, projectRoot: state, treeRoot: sourceRoot || state, sourceRoot: sourceRoot || state, mode });
   } catch (error     ) {
     return usageError('readiness', error.message, json, error);
   }
@@ -139,7 +176,7 @@ function handleReadinessCommand({
   };
 
   if (json) {
-    console.log(JSON.stringify({ ...report, callerAsserted, record: recorded, declaredScope }, null, 2));
+    console.log(JSON.stringify({ ...report, callerAsserted, carriedFromLastRecord: carried, record: recorded, declaredScope }, null, 2));
     reportNotRecorded();
     return finish(exitCode);
   }
@@ -164,6 +201,7 @@ function handleReadinessCommand({
     // Named, not hidden: these requirements were satisfied because the caller said so, and a
     // verdict that mixes measured and stated inputs must say which is which.
     console.log(`Caller-stated: ${callerAsserted.join(', ')} (asserted on the command line, not established by evidence)`);
+    if (carried.length > 0) console.log(`Carried:       ${carried.join(', ')} (stated by the last evaluation of this task; pass the flag to replace it)`);
   }
   console.log('─'.repeat(70));
   console.log('Requirements Breakdown:');
@@ -241,6 +279,30 @@ function readEvidenceBatch(batchPath     , taskId     , root     , slug      = n
   throw new Error('a batch must be a JSON array of evidence items, or an object with an `evidence` array');
 }
 
+/**
+ * Refuses an evidence item whose file locator names a directory, whatever its provenance: a locator
+ * points into a file. An absence item has no locator, and a locator that does not parse is left to
+ * `toEvidence`, which names what is wrong with it.
+ * @throws {Error} naming the locator
+ */
+function refuseDirectoryLocator(raw     , sourceRoot        , root        ) {
+  if (!raw || typeof raw !== 'object' || raw.absence || raw.locator === undefined) return;
+  let locator;
+  try {
+    locator = parseLocator(raw.locator);
+  } catch {
+    return;
+  }
+  if (!locator.file) return;
+  let isDirectory = false;
+  try {
+    isDirectory = fs.statSync(path.resolve(fileRootFor(sourceRoot, root, locator), locator.file)).isDirectory();
+  } catch { /* missing or unreadable: the resolver judges that */ }
+  if (isDirectory) {
+    throw new Error(`the locator '${locator.file}' is a directory, and a directory is not a valid locator; name a file (path[:line])`);
+  }
+}
+
 /**
  * The `--action add` arm: validate the whole batch, then write it.
  * @returns {number} exit code
@@ -268,10 +330,8 @@ function addEvidence({ ledger, root, sourceRoot = root, attemptRoot, taskId, ite
 
   // The whole batch is validated before any of it is written. A half-written stage batch is worse
   // than a rejected one: the half that landed looks complete to every later reader.
-  const treeState = measureTreeState(root);
-  const hasAbsence = raws.some((raw     ) => raw?.absence === true);
-  const absenceTreeState = hasAbsence && path.resolve(sourceRoot) !== path.resolve(root)
-    ? measureTreeState(sourceRoot) : null;
+  // The tree observed is the checkout the verb runs in (115 IC-007), one measurement for every item.
+  const treeState = measureTreeState(sourceRoot);
   const providerFreshness = new Map();
   let sourceModeOf      = null;
   const validated = [];
@@ -280,7 +340,8 @@ function addEvidence({ ledger, root, sourceRoot = root, attemptRoot, taskId, ite
       if (raw && raw.absence && !sourceModeOf) {
         sourceModeOf = sourceModeLookup(new CapabilityRouter({ repoRoot: REPO_ROOT }).capabilities);
       }
-      validated.push(toEvidence({ item: raw }, { taskId, root, treeState, absenceTreeState, probeRoot: sourceRoot, attemptRoot, slug, providerFreshness, sourceModeOf }));
+      refuseDirectoryLocator(raw, sourceRoot, root);
+      validated.push(toEvidence({ item: raw }, { taskId, root, treeState, probeRoot: sourceRoot, sourceRoot, attemptRoot, slug, providerFreshness, sourceModeOf }));
     } catch (error     ) {
       const where = raws.length > 1 ? `batch item ${index + 1} of ${raws.length}: ` : '';
       return usageError('evidence', `${where}${error.message}`, json, error);
@@ -318,8 +379,7 @@ function addEvidence({ ledger, root, sourceRoot = root, attemptRoot, taskId, ite
   }
   console.log('─'.repeat(78));
   console.log(`Wrote ${written.length} item(s) to ${stateFile}`);
-  const observedTree = absenceTreeState || treeState;
-  console.log(`Commit at observation: ${observedTree.gitCommit || (observedTree.prefix !== null ? 'not measured' : 'not a git worktree — freshness cannot expire by diff')}`);
+  console.log(`Commit at observation: ${treeState.gitCommit || (treeState.prefix !== null ? 'not measured' : 'not a git worktree — freshness cannot expire by diff')}`);
   console.log('═'.repeat(78) + '\n');
   return finish(0);
 }
@@ -361,28 +421,69 @@ function supersedeEvidence({ ledger, taskId, evidenceId, replacedBy, json }
   return finish(0);
 }
 
+/**
+ * The `--action retire --stale` arm: retire every active item the ledger classes stale right now,
+ * judged the way readiness judges them (the tree the verb runs in). Items are retired without a
+ * replacement and the reason is recorded on each; fresh items are not touched.
+ * @returns {number} exit code
+ */
+function retireStaleEvidence({ ledger, root, sourceRoot, taskId, slug, stale, json }     ) {
+  if (!stale) {
+    return usageError('evidence', '--action retire retires every stale item and needs --stale; '
+      + 'to retire one item, point it at its replacement with --action supersede', json);
+  }
+  // Staleness is derived, never stored by a read: classify on a separate copy so the ledger being
+  // saved changes only the items retired here.
+  const { FreshnessValidator } = require('./freshness.js');
+  const probe = new EvidenceLedger({ repoRoot: root, slug });
+  let retired       ;
+  try {
+    probe.load(taskId);
+    new FreshnessValidator({ repoRoot: root, treeRoot: sourceRoot, sourceRoot }).validateLedgerFreshness(probe);
+    const staleItems = probe.getAllEvidence().filter((item     ) => item.taskId === taskId
+      && item.freshness?.status === 'STALE' && item.status !== 'superseded');
+    for (const item of staleItems) {
+      ledger.retireEvidence(item.id, `stale: ${item.freshness.staleReason || 'marked stale'}`);
+    }
+    retired = staleItems.map((item     ) => ledger.getEvidence(item.id));
+    if (retired.length > 0) ledger.save(taskId);
+  } catch (error     ) {
+    return usageError('evidence', error.message, json, error);
+  }
+  const ids = retired.map((item     ) => item.id);
+  if (json) {
+    console.log(JSON.stringify({ action: 'retire', taskId, retired: ids.length, ids, evidence: retired }, null, 2));
+    return finish(0);
+  }
+  console.log(ids.length === 0
+    ? `Evidence [Task: ${taskId}]: no stale items to retire.`
+    : `Evidence [Task: ${taskId}]: retired ${ids.length} stale item(s):\n${retired.map((item     ) => `  ${item.id}  ${item.retiredReason}`).join('\n')}`);
+  return finish(0);
+}
+
 /**
  * Handles `doflow evidence` — record a stage's evidence batch, retire a stale item, or query
  * what is recorded.
  *
  * @param {Object} options
  * @param {string} [options.taskId='default']
- * @param {'list'|'status'|'add'|'supersede'} [options.action='list']
+ * @param {'list'|'status'|'add'|'supersede'|'retire'} [options.action='list']
  * @param {Object} [options.item] single-item write, assembled from flags by bin/doflow.js
  * @param {string} [options.batchPath] `add`: a JSON batch file, or `-` for stdin
  * @param {string} [options.evidenceId] `supersede`: the item to retire
  * @param {string} [options.replacedBy] `supersede`: the item that replaces it
+ * @param {boolean} [options.stale] `retire`: retire every item the ledger classes stale
  * @param {boolean} [options.json=false]
  * @param {string} [options.repoRoot]
  * @param {string} [options.stateRoot]
  * @returns {number} exit code
  */
-function handleEvidenceCommand({ taskId = 'default', action = 'list', item = null, batchPath = null, evidenceId = null, replacedBy = null, json = false, repoRoot, stateRoot, sourceRoot, attemptRoot, slug = null }      = {}) {
+function handleEvidenceCommand({ taskId = 'default', action = 'list', item = null, batchPath = null, evidenceId = null, replacedBy = null, stale = false, json = false, repoRoot, stateRoot, sourceRoot, attemptRoot, slug = null }      = {}) {
   // See handleReadinessCommand: evidence is the caller's project state, not DoFlow package state.
   const root = stateRoot || repoRoot || process.cwd();
   const isQuery = action === 'list' || action === 'status';
-  if (!isQuery && action !== 'add' && action !== 'supersede') {
-    return usageError('evidence', `unknown --action '${action}'. Valid: list, add, supersede`, json);
+  if (!isQuery && action !== 'add' && action !== 'supersede' && action !== 'retire') {
+    return usageError('evidence', `unknown --action '${action}'. Valid: list, add, supersede, retire`, json);
   }
   // A write argument on a read action is the defect this verb was reported for: it used to accept
   // append-shaped flags, ignore them, and print the (unchanged) ledger as if the write had landed.
@@ -390,7 +491,7 @@ function handleEvidenceCommand({ taskId = 'default', action = 'list', item = nul
     return usageError('evidence', 'these are write arguments and this action only reads — re-run with --action add', json);
   }
 
-  const ledger = new EvidenceLedger({ repoRoot: root });
+  const ledger = new EvidenceLedger({ repoRoot: root, slug });
   try {
     ledger.load(taskId);
   } catch (error     ) {
@@ -399,6 +500,7 @@ function handleEvidenceCommand({ taskId = 'default', action = 'list', item = nul
 
   if (action === 'add') return addEvidence({ ledger, root, sourceRoot: sourceRoot || root, attemptRoot, taskId, item, batchPath, json, slug });
   if (action === 'supersede') return supersedeEvidence({ ledger, taskId, evidenceId, replacedBy, json });
+  if (action === 'retire') return retireStaleEvidence({ ledger, root, sourceRoot: sourceRoot || root, taskId, slug, stale, json });
 
   const items = ledger.queryEvidence({ taskId });
 
@@ -428,10 +530,85 @@ function handleEvidenceCommand({ taskId = 'default', action = 'list', item = nul
   return finish(0);
 }
 
+const EMIT_NUDGES = ['nudge', 'suppress', 'none'];
+const EMIT_MAX_BYTES = /^[1-9][0-9]{0,9}$/;
+
+/**
+ * 078 IC-005: `doflow-run context-emit`, a thin wrapper over emitContext(). Identity is read from
+ * the environment alone (IC-007); no flag sets it. Exits 0 emitted or silent, 2 usage (including a
+ * launch without a launched identity, or an invalid identity value), 3 refused.
+ */
+function handleContextEmitCommand({ event, cwd, session, harness, nudge, maxBytes, taskId, slug, stateRoot, peek = false, json = false, env = process.env }      = {}) {
+  // Required on use: context-pack.ts loads the whole pack compiler, which no other verb here needs.
+  const { emitContext } = require('./context-pack.js');
+  const { resolveIdentity } = require('./context/identity.js');
+  if (typeof cwd !== 'string' || cwd === '') return usageError('context-emit', '--cwd <dir> is required', json);
+  const dir = path.resolve(cwd);
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return usageError('context-emit', `--cwd '${cwd}' is not a directory`, json);
+  if (nudge !== undefined && !EMIT_NUDGES.includes(nudge)) return usageError('context-emit', `--nudge must be one of ${EMIT_NUDGES.join(', ')}`, json);
+  if (maxBytes !== undefined && !EMIT_MAX_BYTES.test(String(maxBytes))) return usageError('context-emit', '--max-bytes must be a positive integer', json);
+  const sessionId = typeof session === 'string' ? session : '';
+  const identity = resolveIdentity(env, { cwd: dir, sessionId });
+  if (identity.diagnostics.includes('identity-invalid')) {
+    return usageError('context-emit', 'DOFLOW_RUN_ID or DOFLOW_LINEAGE_ID holds an invalid value', json);
+  }
+  let result     ;
+  try {
+    result = emitContext({
+      event, identity, cwd: dir, sessionId, env, peek: peek === true,
+      ...(harness ? { harness } : {}),
+      ...(nudge ? { nudge } : {}),
+      ...(maxBytes !== undefined ? { maxBytes: Number(maxBytes) } : {}),
+      ...(taskId ? { taskId } : {}),
+      ...(slug ? { slug } : {}),
+      ...(stateRoot ? { stateRoot } : {}),
+    });
+  } catch (error     ) {
+    if (error?.code === 'USAGE_ERROR') return usageError('context-emit', error.message.replace(/^emitContext: /, ''), json);
+    throw error;
+  }
+  if (json) {
+    console.log(JSON.stringify({ v: 1, event, identity, decision: result.decision, text: result.text, pack: result.pack, committed: result.committed }));
+  } else if (result.text !== null) {
+    process.stdout.write(result.text.endsWith('\n') ? result.text : `${result.text}\n`);
+  }
+  return finish(result.decision.reason === 'refused:mandatory-over-budget' ? 3 : 0);
+}
+
+/**
+ * 078 IC-013: `doflow-run context-grant`, a thin wrapper over grantSummary(). The source scope
+ * defaults to the caller's identity. Exits 0 created, 1 not found or already granted, 2 usage,
+ * 3 over budget (refused before any write).
+ */
+function handleContextGrantCommand({ summary, toRun, toLineage, fromWorktree, fromRun, fromLineage, maxBytes, json = false, env = process.env }      = {}) {
+  const { grantSummary } = require('./context/summary-store.js');
+  let granted     ;
+  try {
+    granted = grantSummary({
+      summary, toRun, toLineage, env,
+      ...(fromWorktree ? { fromWorktree: path.resolve(fromWorktree) } : {}),
+      ...(fromRun ? { fromRun } : {}),
+      ...(fromLineage ? { fromLineage } : {}),
+      ...(maxBytes !== undefined ? { maxBytes } : {}),
+    });
+  } catch (error     ) {
+    if (error?.name !== 'SummaryStoreError') throw error;
+    if (error.exitCode === 2) return usageError('context-grant', error.message, json);
+    if (json) console.log(JSON.stringify({ v: 1, ok: false, error: error.code, summary: error.message }));
+    else console.error(`doflow context-grant: ${error.message}`);
+    return finish(error.exitCode);
+  }
+  if (json) console.log(JSON.stringify({ v: 1, ok: true, ...granted }));
+  else console.log(`granted ${granted.summaryId} (${granted.bytes} B) -> ${granted.path}`);
+  return finish(0);
+}
+
 module.exports = {
   handleCapabilitiesCommand,
   handleReadinessCommand,
   handleEvidenceCommand,
+  handleContextEmitCommand,
+  handleContextGrantCommand,
   // Exported for bin/doflow.js, which refuses the same names as command-line flags, and for the
   // tests that pin the write boundary.
   EVIDENCE_SCORE_FIELDS,

package/src/runtime/config-home.js

@@ -0,0 +1,42 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The per-machine config home (086 IC-003, DD-7): the one place Node code asks where `<home>/doflow`
+ * lives. `XDG_CONFIG_HOME` when it is set, non-empty and absolute, else `$HOME/.config` when `HOME` is
+ * set, non-empty and absolute, else no config home. A relative or empty value is ignored, never read
+ * against the working directory. It reads the `HOME` variable and never `os.homedir()`, so Node and
+ * the shell blocks (`doflow_config_home` in `doflow-run`, `policies/lib.sh`, ...) agree on every
+ * environment, and an unset HOME is "no home" rather than the account's home.
+ */
+
+const path = require('node:path');
+
+                                              
+
+                      
+                                                                                             
+                      
+                                                     
+                     
+                                                                                                    
+                                             
+ 
+
+function configHome(env      = process.env)             {
+  const ignored                        = [];
+  const usable = (name                            )                => {
+    const value = env[name];
+    if (typeof value !== 'string' || value === '') return null;
+    if (path.isAbsolute(value)) return value;
+    ignored.push(name);
+    return null;
+  };
+  const xdg = usable('XDG_CONFIG_HOME');
+  const home = usable('HOME');
+  const base = xdg !== null ? xdg : home !== null ? path.join(home, '.config') : null;
+  return { base, dir: base === null ? null : path.join(base, 'doflow'), ignored };
+}
+
+module.exports = { configHome };