@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/scaffold/generate.js

@@ -336,13 +336,13 @@ function planSourceStubs({ byPath, scaffoldDir, repoRoot, fsImpl, slug, message,
         ? reqs.map((r     ) => `requirement:   ${r.id} — ${r.summary}`)
         : ['requirement:   none — no user story on the owning task resolves to a requirement']),
       ...(comps.length
-        ? comps.map((c     ) => `component:     ${c.id} — ${c.name} (design.md §3)`)
+        ? comps.map((c     ) => `component:     ${c.id} — ${c.name} (design.md Components & Boundaries)`)
         : ['component:     none — no design component serves this task\'s requirements']),
     ];
 
     const bodyParts           = [''];
     if (declared.length) {
-      header.push(`shape:         declared in design.md §4 (${[...new Set(declared.map((d     ) => d.component))].join(', ')}), quoted below`);
+      header.push(`shape:         declared in design.md API / Interface Contracts (${[...new Set(declared.map((d     ) => d.component))].join(', ')}), quoted below`);
       for (const decl of declared) {
         const lines = decl.block.split('\n');
         const shown = lines.slice(0, 40);
@@ -354,11 +354,11 @@ function planSourceStubs({ byPath, scaffoldDir, repoRoot, fsImpl, slug, message,
         ].join('\n'));
       }
     } else {
-      header.push('shape:         not declared in design.md §4 — placeholder signature below');
+      header.push('shape:         not declared in design.md API / Interface Contracts — placeholder signature below');
       // Not a skip — the file was emitted. Conflating the two would let 29 "we wrote it, but the
       // design never said what it should look like" rows hide inside a skip count, which is the
       // opposite of what the manifest is for.
-      shapeUndeclared.push({ path: path.join('src', file) + STUB_SUFFIX, why: 'design.md §4 declares no interface for this file\'s component — the signature below is a placeholder, not a contract' });
+      shapeUndeclared.push({ path: path.join('src', file) + STUB_SUFFIX, why: 'design.md API / Interface Contracts declares no interface for this file\'s component — the signature below is a placeholder, not a contract' });
     }
 
     const pkg = snake(words(path.basename(path.dirname(file)) || 'scaffold')).replace(/_/g, '');
@@ -422,7 +422,7 @@ function planTestStubs({ requirement, componentsForRequirement, language, slug,
           'reads as coverage. Replace the body, do not delete the failure.',
           '',
           `requirement:   ${id}${req ? ` — ${req.summary}` : ' — not present in the requirement index'}`,
-          ...(comps.length ? comps.map((c     ) => `component:     ${c.id} — ${c.name} (design.md §3)`) : []),
+          ...(comps.length ? comps.map((c     ) => `component:     ${c.id} — ${c.name} (design.md Components & Boundaries)`) : []),
           `criteria:      ${cases.length} from requirement.md §6`,
           `language:      ${language.id} (detected from ${language.signal} by command-detect.ts)`,
         ];
@@ -442,15 +442,27 @@ function planTestStubs({ requirement, componentsForRequirement, language, slug,
 /**
  * contracts/ — partitioned here, generated by the prose algorithm. See the module header for why
  * the walk-up is not reimplemented in code.
+ * A task-id `depends-on:` value (`taskDeps`) is an edge in the task graph, not a service, so it
+ * gets no frame. A task whose `external-contract:` is left with no external value after that
+ * filter is pushed onto `notEvaluated` as `external-contract-orphaned` rather than dropped (IC-001).
  * @param {Array<Object>} tasks from `plan.tasks`
  * @param {Set<string>} ownedPaths every path a task in this plan already owns
+ * @param {Array<Object>} notEvaluated mutated with one entry per orphaned `external-contract:`
  * @returns {Array<Object>} externalDependencies
  */
-function partitionExternalDependencies(tasks       , ownedPaths             )        {
+function partitionExternalDependencies(tasks       , ownedPaths             , notEvaluated       )        {
   const externalDependencies        = [];
   const dependencyTasks = new Map               ();
   for (const task of tasks) {
-    for (const dep of task.dependsOn) {
+    const taskDeps = new Set(task.taskDeps || []);
+    const external = task.dependsOn.filter((dep        ) => !taskDeps.has(dep));
+    if (task.externalContract && external.length === 0) {
+      notEvaluated.push({
+        what: `plan.md → ${task.id} external-contract: ${task.externalContract}`,
+        why: 'external-contract-orphaned — no external depends-on: value remains once task-id dependencies are removed, so no contract frame is generated from it',
+      });
+    }
+    for (const dep of external) {
       if (!dependencyTasks.has(dep)) dependencyTasks.set(dep, []);
       dependencyTasks.get(dep) .push(task);
     }
@@ -714,7 +726,7 @@ function generateScaffold(options      = {})      {
   const planned = new Map([...sourcePlanned, ...testPlanned]);
 
   const ownedPaths = new Set([...byPath.keys()]);
-  const externalDependencies = partitionExternalDependencies(plan.tasks, ownedPaths);
+  const externalDependencies = partitionExternalDependencies(plan.tasks, ownedPaths, notEvaluated);
 
   const { written, unchanged, preserved } = applyPlannedFiles({ planned, blocked, scaffoldDir, fsImpl });
 
@@ -777,7 +789,7 @@ function renderManifest(result     , planned                  )         {
     '_Nothing generated._');
 
   lines.push('## Emitted without a declared shape', '');
-  lines.push('These files exist and are traceable, but `design.md` §4 never declared an interface for',
+  lines.push('These files exist and are traceable, but `design.md` API / Interface Contracts never declared an interface for',
     'them, so their signature is a placeholder rather than a contract. Reviewing the placeholder as',
     'if it were the designed API is the mistake this section exists to prevent.', '');
   table(['Path', 'Why'], result.shapeUndeclared.map((s     ) => [s.path, s.why]),

package/src/runtime/settings/autopilot.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * The roadmap autopilot kill switch (feature 108 IC-011, FR-016; decisions C9, C4, C20). It lives
+ * with the settings it reads, so the orchestrator and the roadmap loop share one reader without the
+ * orchestrator importing the loop.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+                                                  
+
+/** `<config home>/autopilot/off`, or null with no config home (which already reads as off). */
+function sentinelFile(env     )                {
+  const { configHome } = require('../config-home.js');
+  const home = configHome(env).dir;
+  return home ? path.join(home, 'autopilot', 'off') : null;
+}
+
+/**
+ * Read fresh on every call (never memoised: a copied env defeats the resolver cache), so a switch
+ * set between two boundaries stops the next one. Any layer saying off wins and is named, in the
+ * order env (DOFLOW_AUTOPILOT_ENABLED), the `autopilot/off` sentinel, the settings file. The
+ * sentinel is stat'ed here: any error but ENOENT (EACCES, ENOTDIR) reads as present, because the
+ * resolver reads every stat error as absent. Absent, invalid or unreadable settings read as off.
+ */
+function readKillSwitch(env      = process.env, fsImpl      = fs)                                                   {
+  const off = (layer             ) => ({ enabled: false, switch: layer });
+  try {
+    const { loadSettings } = require('./resolve.js');
+    const resolution = loadSettings({ global: true, env: { ...env } }).get('autopilot.enabled', 'global');
+    if (resolution.candidates.some((c     ) => c.layer === 'env' && c.value === 'off')) return off('env');
+    const file = sentinelFile(env);
+    if (file) {
+      try { fsImpl.statSync(file); return off('sentinel'); }
+      catch (error     ) { if (error?.code !== 'ENOENT') return off('sentinel'); }
+    }
+    if (resolution.candidates.some((c     ) => c.legacy && c.value === 'off')) return off('sentinel');
+    return resolution.value === 'on' ? { enabled: true, switch: null } : off('setting');
+  } catch {
+    return off('setting');
+  }
+}
+
+/** Seed writes require an independently verified durable off, so uncertainty refuses the write. */
+function readSeedSwitch(env      = process.env, fsImpl      = fs)                                                   {
+  const refuse = () => ({ enabled: true, switch: null });
+  const off = (layer             ) => ({ enabled: false, switch: layer });
+  try {
+    const { configHome } = require('../config-home.js');
+    const home = configHome(env).dir;
+    if (!home) return refuse();
+
+    const settingsEnv = { ...env };
+    delete settingsEnv.DOFLOW_AUTOPILOT_ENABLED;
+    const { loadSettings } = require('./resolve.js');
+    const settings = loadSettings({ global: true, env: settingsEnv, fsImpl });
+    const resolution = settings.get('autopilot.enabled', 'global');
+    if (resolution.state === 'invalid' || resolution.candidates.some((candidate     ) => candidate.status === 'invalid')) {
+      return refuse();
+    }
+    if (settings.errors.some((entry     ) => entry.key === 'autopilot.enabled' || entry.key === null)) {
+      return refuse();
+    }
+
+    const file = path.join(home, 'autopilot', 'off');
+    try {
+      fsImpl.statSync(file);
+      return off('sentinel');
+    } catch (error     ) {
+      if (error?.code !== 'ENOENT') return off('sentinel');
+    }
+
+    const legacyOff = resolution.candidates.some((candidate     ) => candidate.legacy && candidate.value === 'off');
+    if (resolution.value === 'off' || legacyOff) return off('setting');
+    return refuse();
+  } catch {
+    return refuse();
+  }
+}
+
+/**
+ * maint-thin: whether a review is unattended, so the class seat floor binds. Fail closed: only a verifiably off
+ * switch (the seed reader: a resolved config home whose setting or sentinel says off) reads as attended. An uncertain
+ * switch, unreadable settings or no config home count as unattended. The one other attended case is an explicit,
+ * process-local `DOFLOW_AUTOPILOT_ENABLED=off`: a caller can always lower its own run that way, and that costs nothing,
+ * because roadmap gate-b judges the recorded seats against the class floor itself and denies too few.
+ */
+function reviewUnattended(env      = process.env, fsImpl      = fs)          {
+  if (env?.DOFLOW_AUTOPILOT_ENABLED === 'off') return false;
+  return readSeedSwitch(env, fsImpl).enabled !== false;
+}
+
+/** Tripwire (narrowing only): writes the kill-switch sentinel; only a person removes it. */
+function tripSentinel(env     , line        , fsImpl      = fs)          {
+  const file = sentinelFile(env);
+  // No config home already reads as off (needsConfigHome), so there is nothing to narrow.
+  if (!file) return false;
+  fsImpl.mkdirSync(path.dirname(file), { recursive: true });
+  try { fsImpl.writeFileSync(file, `${line}\n`, { flag: 'wx', mode: 0o600 }); }
+  catch (error     ) { if (error.code !== 'EEXIST') throw error; }
+  return true;
+}
+
+module.exports = { readKillSwitch, readSeedSwitch, reviewUnattended, tripSentinel };

package/src/runtime/settings/cli.js

@@ -0,0 +1,280 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { configHome } = require('../config-home.js');
+const { finishRuntime, usageError } = require('../cli-result.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { loadSettingsRegistry, REGISTRY_FILE } = require('./registry.js');
+const { loadSettings } = require('./resolve.js');
+const { maskUrl } = require('./shared.js');
+
+function safeValue(value     , meta     )      {
+  return meta?.type === 'url' && typeof value === 'string' ? maskUrl(value) : value;
+}
+
+function safeResolution(resolution     )      {
+  const meta = resolution?.meta || {};
+  return {
+    ...resolution,
+    value: safeValue(resolution.value, meta),
+    origin: resolution.origin ? { ...resolution.origin } : resolution.origin,
+    candidates: (resolution.candidates || []).map((candidate     ) => ({
+      ...candidate,
+      value: safeValue(candidate.value, meta),
+      display: meta.type === 'url' && typeof candidate.display === 'string'
+        ? maskUrl(candidate.display) : candidate.display,
+    })),
+    meta: { ...meta, default: safeValue(meta.default, meta) },
+  };
+}
+
+function safeReport(report     )      {
+  const keys                      = {};
+  for (const [key, value] of Object.entries(report.keys || {})) {
+    if (value && typeof value === 'object' && !('key' in value)
+      && 'project' in value && 'global' in value) {
+      keys[key] = { project: safeResolution((value       ).project), global: safeResolution((value       ).global) };
+    } else {
+      keys[key] = safeResolution(value);
+    }
+  }
+  return { ...report, keys };
+}
+
+/** The settings-only part of doctor output; values are omitted, while present files and faults remain. */
+function settingsReport(view     )      {
+  const report = view.report();
+  return {
+    schema: 1,
+    scope: report.scope,
+    configHome: report.configHome,
+    project: report.project,
+    files: report.files,
+    errors: report.errors,
+    notes: report.notes,
+  };
+}
+
+function buildSettingsReport({ repoRoot = REPO_ROOT, projectRoot = process.cwd(), global = false,
+  env = process.env, fsImpl = fs }      = {})      {
+  const loaded = loadSettingsRegistry({ repoRoot, fsImpl });
+  if (!loaded.ok) {
+    const home = configHome(env);
+    return {
+      schema: 1,
+      scope: global ? 'global' : 'project',
+      configHome: { dir: home.dir, ignored: [...home.ignored] },
+      project: { root: global ? null : path.resolve(projectRoot), layersFrom: null, checkout: null },
+      files: [],
+      errors: [{ key: null, layer: 'default', source: path.join(repoRoot, REGISTRY_FILE), legacy: false,
+        code: 'settings-registry-invalid', reason: loaded.detail, offset: null }],
+      notes: [],
+    };
+  }
+  try {
+    const view = loadSettings({ projectRoot, global, env, fsImpl, registry: loaded.registry });
+    return settingsReport(view);
+  } catch (error     ) {
+    const home = configHome(env);
+    return {
+      schema: 1,
+      scope: global ? 'global' : 'project',
+      configHome: { dir: home.dir, ignored: [...home.ignored] },
+      project: { root: global ? null : path.resolve(projectRoot), layersFrom: null, checkout: null },
+      files: [],
+      errors: [{ key: null, layer: 'default', source: path.join(repoRoot, REGISTRY_FILE), legacy: false,
+        code: 'settings-unavailable', reason: error?.message || String(error), offset: null }],
+      notes: [],
+    };
+  }
+}
+
+function settingValue(value     , meta     )         {
+  const safe = safeValue(value, meta);
+  if (safe === null || safe === undefined) return '(none)';
+  if (typeof safe === 'string') return JSON.stringify(safe);
+  return JSON.stringify(safe);
+}
+
+function originLabel(resolution     )         {
+  const { origin } = resolution;
+  const source = origin.source || (origin.via === 'no-config-home' ? 'no config home' : REGISTRY_FILE);
+  return `${origin.layer}: ${source}`;
+}
+
+function printResolution(key        , resolution     , showOrigin         , suffix = '')       {
+  if (resolution.meta?.needsConfigHome && resolution.origin?.via === 'no-config-home') {
+    console.log(`${key}${suffix} = ${settingValue(resolution.value, resolution.meta)}  (no config home: capture skipped)`);
+  } else {
+    const origin = showOrigin ? `  (${originLabel(resolution)})` : '';
+    console.log(`${key}${suffix} = ${settingValue(resolution.value, resolution.meta)}${origin}`);
+  }
+  if (!showOrigin) return;
+  for (const candidate of resolution.candidates || []) {
+    const display = typeof candidate.display === 'string' && candidate.display !== '' ? candidate.display : '(none)';
+    const reason = candidate.reason ? `: ${candidate.reason}` : '';
+    console.log(`    ${candidate.layer} ${candidate.source}: ${display} — ${candidate.status}${reason}`);
+  }
+}
+
+function printSettingsList(report     , showOrigin         )       {
+  const home = report.configHome;
+  const ignored = home.ignored || [];
+  const homeLabel = home.dir
+    ? `${home.dir}${ignored.length ? ` | ${ignored.join(', ')} ignored` : ''}`
+    : `none${ignored.length ? ` (${ignored.join(', ')} ignored)` : ''}`;
+  console.log(`config home: ${homeLabel}`);
+  for (const name of ignored) console.log(`note: ignored relative ${name}`);
+  const project = report.project;
+  console.log(`project: ${project.root || '(none)'}${project.checkout ? ` (${project.checkout})` : ''}`);
+
+  for (const [key, value] of Object.entries(report.keys || {})) {
+    const dualView = value && typeof value === 'object' && !('key' in (value       ))
+      && 'project' in (value       ) && 'global' in (value       )
+      && Array.isArray((value       ).project?.meta?.views) && (value       ).project.meta.views.includes('global');
+    if (dualView) {
+      printResolution(key, (value       ).project, showOrigin, ' [project roots]');
+      printResolution(key, (value       ).global, showOrigin, ' [user roots]');
+    } else {
+      const views = (value       )?.meta?.views;
+      const suffix = Array.isArray(views) && views.includes('global')
+        ? ((value       ).view === 'global' ? ' [user roots]' : ' [project roots]')
+        : '';
+      printResolution(key, value, showOrigin, suffix);
+    }
+  }
+  for (const error of report.errors || []) {
+    console.log(`error: ${error.key || 'settings'} (${error.layer}: ${error.source}): ${error.reason}`);
+  }
+  for (const note of report.notes || []) console.log(`note: ${note.text}`);
+}
+
+function securityFault(report     )          {
+  const check = (resolution     )          => {
+    if (resolution && resolution.meta?.securityRelevant
+      && ['fail-safe', 'cross-key'].includes(resolution.origin?.via)) return true;
+    if (resolution && typeof resolution === 'object' && 'project' in resolution && 'global' in resolution) {
+      return check(resolution.project) || check(resolution.global);
+    }
+    return false;
+  };
+  return Object.values(report.keys || {}).some(check);
+}
+
+const CONFIG_ACTIONS = ['list', 'schema', 'validate', 'set', 'unset'];
+const CONFIG_LAYERS = ['user', 'project', 'local'];
+/** Positional words after the action: the key and, for validate and set, a JSON value. */
+const CONFIG_OPERANDS                         = { schema: 0, validate: 2, set: 2, unset: 1 };
+
+                                                                                                                                   
+
+/** Splits `config [list] [path] | schema | validate <key> <value> | set <key> <value> | unset <key>` and its flags. */
+function configArguments(positional     , { layer, global, showOrigin, preparedRun }     )             {
+  const args = Array.isArray(positional) ? [...positional] : [];
+  const fail = (error        )             => ({ action: 'list', project: null, key: null, valueText: null, error });
+  let action = 'list';
+  if (CONFIG_ACTIONS.includes(args[0])) action = args.shift();
+  else if (args.length === 1 && !args[0].includes(path.sep) && !fs.existsSync(args[0])) {
+    return fail(`unknown action '${args[0]}'; expected ${CONFIG_ACTIONS.join(', ')}`);
+  }
+  if (layer !== undefined && !CONFIG_LAYERS.includes(layer)) return fail(`--layer must be one of ${CONFIG_LAYERS.join(', ')}`);
+  if (action === 'list') {
+    if (args.length > 1) return fail('expected config [list] [project path]');
+    if (layer !== undefined) return fail('--layer is only for validate, set and unset');
+    if (preparedRun !== undefined) return fail('--prepared-run is only for config validate');
+    return { action, project: args[0] || null, key: null, valueText: null, error: null };
+  }
+  if (showOrigin) return fail('--show-origin is only for config list');
+  if (global) return fail(`-g is not for config ${action}`);
+  if (action === 'schema' && layer !== undefined) return fail('--layer is only for validate, set and unset');
+  if (preparedRun !== undefined) {
+    if (action !== 'validate') return fail('--prepared-run is only for config validate');
+    if (args.length) return fail('config validate --prepared-run <file> takes no key or value');
+    if (layer !== undefined) return fail('--layer is not for config validate --prepared-run (its settings are judged at the project layer)');
+    return { action, project: null, key: null, valueText: null, error: null };
+  }
+  const want = CONFIG_OPERANDS[action];
+  if (args.length !== want) {
+    const usage = { schema: 'config schema', validate: 'config validate <key> <json-value> [--layer user|project|local] | config validate --prepared-run <file>',
+      set: 'config set <key> <json-value> --layer user|project|local', unset: 'config unset <key> --layer user|project|local' }[action];
+    return fail(`expected ${usage}`);
+  }
+  if ((action === 'set' || action === 'unset') && layer === undefined) return fail(`config ${action} needs --layer user|project|local`);
+  return { action, project: null, key: args[0] ?? null, valueText: args[1] ?? null, error: null };
+}
+
+function handleConfigCommand({ json = false, global = false, showOrigin = false, positional = [], layer, preparedRun,
+  projectRoot, repoRoot = REPO_ROOT, env = process.env, fsImpl = fs }      = {})         {
+  const args = configArguments(positional, { layer, global, showOrigin, preparedRun });
+  if (args.error) return usageError('config', args.error, json);
+  const loaded = loadSettingsRegistry({ repoRoot, fsImpl });
+  if (!loaded.ok) {
+    const detail = loaded.detail || 'settings registry is invalid';
+    if (json) console.log(JSON.stringify({ ok: false, status: 'ERROR', exitCode: 2,
+      error: 'settings-registry-invalid', detail }, null, 2));
+    else console.error(`doflow config: settings registry unavailable: ${detail}`);
+    return finishRuntime(2);
+  }
+
+  if (preparedRun !== undefined) {
+    return require('./prepared-run.js').handlePreparedRun({
+      file: preparedRun, json, registry: loaded.registry, repoRoot, projectRoot: projectRoot || process.cwd(), env, fsImpl,
+    });
+  }
+
+  if (args.action !== 'list') {
+    // loaded on demand: the writer and the protocol registry stay off the read-only list path
+    return require('./config-write.js').handleConfigAction({
+      action: args.action, key: args.key, valueText: args.valueText, layer, json, registry: loaded.registry,
+      repoRoot, projectRoot: projectRoot || process.cwd(), env, fsImpl,
+    });
+  }
+
+  try {
+    const root = global ? null : path.resolve(args.project || projectRoot || process.cwd());
+    const view = loadSettings({ projectRoot: root, global, env, fsImpl, registry: loaded.registry });
+    const report = safeReport(view.report());
+    if (json) console.log(JSON.stringify(report, null, 2));
+    else printSettingsList(report, showOrigin);
+    return finishRuntime(securityFault(report) ? 1 : 0);
+  } catch (error     ) {
+    const detail = error?.message || String(error);
+    if (json) console.log(JSON.stringify({ ok: false, status: 'ERROR', exitCode: 2,
+      error: 'settings-registry-invalid', detail }, null, 2));
+    else console.error(`doflow config: settings registry unavailable: ${detail}`);
+    return finishRuntime(2);
+  }
+}
+
+function printSettingsReport(report     )       {
+  console.log('\n[Settings]');
+  console.log(`  config home: ${report.configHome.dir || 'none'}`);
+  for (const name of report.configHome.ignored || []) {
+    console.log(`  ignored relative ${name} (ignored)`);
+  }
+  if (report.project.root) {
+    console.log(`  project: ${report.project.root}${report.project.checkout ? ` (${report.project.checkout})` : ''}`);
+  }
+  const present = (report.files || []).filter((file     ) => file.status !== 'absent');
+  if (!present.length) console.log('  files: none');
+  for (const file of present) {
+    const deprecated = file.kind === 'legacy' ? ' (deprecated)' : '';
+    console.log(`  ${file.layer} ${file.path}: ${file.status}${deprecated}`);
+  }
+  for (const note of report.notes || []) console.log(`  note: ${note.text}`);
+  for (const error of report.errors || []) {
+    console.log(`  error: ${error.key || 'settings'} (${error.layer}: ${error.source}): ${error.reason}`);
+  }
+}
+
+module.exports = {
+  maskUrl,
+  safeReport,
+  settingsReport,
+  buildSettingsReport,
+  printSettingsReport,
+  handleConfigCommand,
+};