@llm-dev-ops/agentics-cli 2.1.5 → 2.3.0

package/dist/pipeline/auto-chain.js

@@ -87,6 +87,343 @@ function copyDirRecursive(src, dest) {
  * Called after every phase so even if later phases fail, earlier artifacts
  * are still available.
  */
+/**
+ * ADR-PIPELINE-068: scaffold body for `src/simulation-lineage.ts`.
+ *
+ * Exported so unit tests can write the file to a temp directory and
+ * exercise the runtime behavior (env override, manifest walk, fallback)
+ * without having to spin up the full pipeline.
+ *
+ * Invariants enforced by tests:
+ * - Uses `readFileSync` + `fileURLToPath` (NEVER `require(`)
+ * - Exports `loadSimulationLineage`, `requireSimulationLineage`,
+ *   `formatLineageBanner`, and the legacy `loadSimulationId` alias
+ * - Walks up at most 6 directories from the module location and from cwd
+ */
+export const SIMULATION_LINEAGE_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-068)
+// ESM-safe simulation lineage loader. Reads .agentics/plans/manifest.json
+// (or .agentics/runs/latest/manifest.json) using readFileSync — never
+// CommonJS require(). Do NOT reimplement this helper; import from it.
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export type SimulationLineageSource = 'env' | 'manifest' | 'fallback';
+
+export interface SimulationLineage {
+  readonly simulationId: string;
+  readonly traceId: string;
+  readonly runId: string;
+  readonly source: SimulationLineageSource;
+  readonly manifestPath?: string;
+}
+
+const MANIFEST_CANDIDATES: readonly string[] = [
+  '.agentics/plans/manifest.json',
+  '.agentics/runs/latest/manifest.json',
+];
+
+const WALK_DEPTH = 6;
+
+/** Walk up from startDir looking for any manifest candidate path. */
+function findManifest(startDir: string): string | null {
+  let dir = startDir;
+  for (let i = 0; i < WALK_DEPTH; i++) {
+    for (const rel of MANIFEST_CANDIDATES) {
+      const candidate = resolve(dir, rel);
+      if (existsSync(candidate)) return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function moduleDir(): string {
+  try {
+    return dirname(fileURLToPath(import.meta.url));
+  } catch {
+    return process.cwd();
+  }
+}
+
+/**
+ * Load the simulation lineage. Permissive — returns a fallback record when
+ * nothing is available. Callers who need strict behavior should use
+ * requireSimulationLineage() instead.
+ *
+ * Resolution order:
+ *   1. AGENTICS_SIMULATION_ID / AGENTICS_TRACE_ID environment variables
+ *   2. First manifest.json found walking up from this module (then cwd)
+ *   3. Fallback record with source='fallback'
+ */
+export function loadSimulationLineage(): SimulationLineage {
+  const envSim = process.env['AGENTICS_SIMULATION_ID'];
+  const envTrace = process.env['AGENTICS_TRACE_ID'];
+  if (envSim) {
+    return {
+      simulationId: envSim,
+      traceId: envTrace ?? envSim,
+      runId: envSim,
+      source: 'env',
+    };
+  }
+
+  const startDirs = [moduleDir(), process.cwd()];
+  for (const start of startDirs) {
+    try {
+      const manifestPath = findManifest(start);
+      if (!manifestPath) continue;
+      const raw = JSON.parse(readFileSync(manifestPath, 'utf-8')) as Record<string, unknown>;
+      const runId = String(raw['run_id'] ?? raw['runId'] ?? '');
+      const simulationId = String(
+        raw['simulation_id'] ?? raw['simulationId'] ?? raw['execution_id'] ?? runId,
+      );
+      const traceId = String(raw['trace_id'] ?? raw['traceId'] ?? simulationId);
+      if (simulationId) {
+        return { simulationId, traceId, runId: runId || simulationId, source: 'manifest', manifestPath };
+      }
+    } catch {
+      // Try the next start dir. Never throw from the permissive loader.
+    }
+  }
+
+  return {
+    simulationId: 'sim-unknown',
+    traceId: 'trace-unknown',
+    runId: 'run-unknown',
+    source: 'fallback',
+  };
+}
+
+/**
+ * Strict variant — throws ECLI-LIN-068 when no simulation lineage is
+ * available. Use this at startup when the service MUST carry a real
+ * simulation id (audit logs, ERP posts, etc.).
+ */
+export function requireSimulationLineage(): SimulationLineage {
+  const lineage = loadSimulationLineage();
+  if (lineage.source === 'fallback') {
+    throw new Error(
+      'ECLI-LIN-068: simulation lineage unavailable — set AGENTICS_SIMULATION_ID or place .agentics/plans/manifest.json in the project tree',
+    );
+  }
+  return lineage;
+}
+
+/**
+ * Human-readable banner printed by the demo script when the loader falls
+ * back. Makes the break visible instead of letting sim-unknown leak into
+ * downstream audit logs and ERP posts.
+ */
+export function formatLineageBanner(lineage: SimulationLineage): string {
+  if (lineage.source !== 'fallback') {
+    return \`simulation lineage: \${lineage.simulationId} (source: \${lineage.source})\`;
+  }
+  return [
+    '',
+    '⚠️  Simulation lineage unavailable (source: fallback)',
+    '    All audit entries and ERP posts will carry sim-unknown.',
+    '    Fix: place .agentics/plans/manifest.json in the project tree,',
+    '    or set AGENTICS_SIMULATION_ID=<run-id> before running the demo.',
+    '',
+  ].join('\\n');
+}
+
+/** Also exported under the legacy alias some older prompts referenced. */
+export const loadSimulationId = (): string => loadSimulationLineage().simulationId;
+`;
+/**
+ * ADR-PIPELINE-069: scaffold body for `src/circuit-breaker.ts`.
+ *
+ * Extracted from the legacy middleware.ts scaffold so generators can
+ * `import { CircuitBreaker } from './circuit-breaker.js'` without pulling
+ * the entire middleware module. middleware.ts now re-exports this symbol
+ * so existing imports keep working.
+ */
+export const CIRCUIT_BREAKER_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-069)
+// Owned by the scaffold — do NOT redeclare CircuitBreaker in generated code.
+import { createLogger } from './logger.js';
+
+/** Simple circuit breaker for external service calls. */
+export class CircuitBreaker {
+  private failures = 0;
+  private state: 'closed' | 'open' | 'half-open' = 'closed';
+  private nextAttempt = 0;
+
+  constructor(
+    private readonly name: string,
+    private readonly threshold = 5,
+    private readonly cooldownMs = 30000,
+    private readonly logger = createLogger('circuit-breaker'),
+  ) {}
+
+  async call<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') {
+      if (Date.now() < this.nextAttempt) {
+        throw new Error(\`Circuit breaker '\${this.name}' is OPEN — retry after \${new Date(this.nextAttempt).toISOString()}\`);
+      }
+      this.state = 'half-open';
+      this.logger.info('circuit.half-open', { name: this.name });
+    }
+    try {
+      const result = await fn();
+      if (this.state === 'half-open') {
+        this.state = 'closed';
+        this.failures = 0;
+        this.logger.info('circuit.closed', { name: this.name });
+      }
+      return result;
+    } catch (err) {
+      this.failures++;
+      if (this.failures >= this.threshold) {
+        this.state = 'open';
+        this.nextAttempt = Date.now() + this.cooldownMs;
+        this.logger.warn('circuit.open', { name: this.name, failures: this.failures, retryAt: new Date(this.nextAttempt).toISOString() });
+      }
+      throw err;
+    }
+  }
+
+  getState(): string { return this.state; }
+}
+`;
+export const OWNED_SCAFFOLD_MODULES = [
+    {
+        path: 'src/logger.ts',
+        exports: ['Logger', 'createLogger', 'setCorrelationId', 'getCorrelationId'],
+    },
+    {
+        path: 'src/config.ts',
+        exports: ['AppConfig', 'config'],
+    },
+    {
+        path: 'src/errors.ts',
+        exports: ['AppError', 'ValidationError', 'NotFoundError', 'ERPError'],
+    },
+    {
+        path: 'src/middleware.ts',
+        exports: [
+            'correlationId',
+            'requestLogger',
+            'incrementCounter',
+            'recordHistogram',
+            'metricsHandler',
+        ],
+    },
+    {
+        path: 'src/circuit-breaker.ts',
+        exports: ['CircuitBreaker'],
+    },
+    {
+        path: 'src/unit-economics.ts',
+        exports: [
+            'DomainUnit',
+            'UnitEconomicsScope',
+            'UnitEconomics',
+            'writeUnitEconomics',
+            'readUnitEconomics',
+        ],
+    },
+    {
+        path: 'src/simulation-lineage.ts',
+        exports: [
+            'SimulationLineage',
+            'SimulationLineageSource',
+            'loadSimulationLineage',
+            'requireSimulationLineage',
+            'formatLineageBanner',
+            'loadSimulationId',
+        ],
+    },
+];
+export function buildOwnedModulesManifest(now = new Date()) {
+    return {
+        version: '1.0',
+        generated_at: now.toISOString(),
+        owned: OWNED_SCAFFOLD_MODULES,
+    };
+}
+const SCAFFOLD_SCAN_SKIP_DIRS = new Set([
+    'node_modules', 'dist', 'build', '.git', 'coverage', '.next', '.agentics',
+]);
+/**
+ * ADR-PIPELINE-069: Walk a project tree looking for generator-emitted files
+ * that redeclare an export listed in OWNED_SCAFFOLD_MODULES. Skips:
+ *   - the scaffold-owned files themselves (matched by basename)
+ *   - test files
+ *   - node_modules / dist / .agentics
+ *
+ * Returns one finding per (file, export) pair.
+ */
+export function detectScaffoldDuplicates(projectRoot, owned = OWNED_SCAFFOLD_MODULES) {
+    if (!fs.existsSync(projectRoot))
+        return [];
+    // Build (exportName -> ownedPath) lookup once.
+    const exportToOwned = new Map();
+    const ownedBasenames = new Set();
+    for (const mod of owned) {
+        ownedBasenames.add(path.basename(mod.path));
+        for (const ex of mod.exports) {
+            if (!exportToOwned.has(ex))
+                exportToOwned.set(ex, mod.path);
+        }
+    }
+    const findings = [];
+    const walk = (currentDir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (SCAFFOLD_SCAN_SKIP_DIRS.has(entry.name))
+                    continue;
+                walk(path.join(currentDir, entry.name));
+                continue;
+            }
+            if (!entry.name.endsWith('.ts'))
+                continue;
+            // Skip the scaffolded files themselves — they're allowed to declare
+            // their own exports. Match by basename so any project layout works.
+            if (ownedBasenames.has(entry.name))
+                continue;
+            // Skip tests + scripts + demos
+            const lower = entry.name.toLowerCase();
+            if (lower.endsWith('.test.ts') || lower.endsWith('.spec.ts') || lower.endsWith('.d.ts'))
+                continue;
+            const fullPath = path.join(currentDir, entry.name);
+            const lowerFull = fullPath.toLowerCase();
+            if (lowerFull.includes('/tests/') || lowerFull.includes('/__tests__/') || lowerFull.includes('/scripts/'))
+                continue;
+            let content;
+            try {
+                const stat = fs.statSync(fullPath);
+                if (stat.size > 1_000_000)
+                    continue;
+                content = fs.readFileSync(fullPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            for (const [exportName, ownedPath] of exportToOwned) {
+                // Match `export class Foo`, `export function Foo`, `export const Foo`,
+                // `export interface Foo`, `export type Foo`, or `export { Foo }`.
+                const declRe = new RegExp(`\\bexport\\s+(?:class|function|const|let|interface|type|enum)\\s+${exportName}\\b`);
+                const reExportRe = new RegExp(`\\bexport\\s*\\{[^}]*\\b${exportName}\\b[^}]*\\}`);
+                if (declRe.test(content) || reExportRe.test(content)) {
+                    findings.push({ path: fullPath, exportName, ownedPath });
+                }
+            }
+        }
+    };
+    walk(projectRoot);
+    return findings;
+}
 function copyPlanningArtifacts(runDir, targetRoot) {
     try {
         // ADR-051: Use git repo root (or explicit target) instead of process.cwd()
@@ -293,51 +630,161 @@ export function metricsHandler(_req: any, res: any): void {
   res.end(lines.join('\\n'));
 }
 
-/** Simple circuit breaker for external service calls */
-export class CircuitBreaker {
-  private failures = 0;
-  private state: 'closed' | 'open' | 'half-open' = 'closed';
-  private nextAttempt = 0;
+// ADR-PIPELINE-069: CircuitBreaker now lives in its own scaffold module.
+// This re-export keeps existing imports (from './middleware.js') working
+// while making the canonical class importable from a dedicated file.
+export { CircuitBreaker } from './circuit-breaker.js';
+`;
+        fs.writeFileSync(path.join(scaffoldDir, 'middleware.ts'), middlewareCode, 'utf-8');
+        totalCopied += 1;
+        // ADR-PIPELINE-069: standalone scaffolded circuit-breaker module so
+        // generators can import CircuitBreaker without pulling all of
+        // middleware.ts. Owned by the scaffold (see OWNED_SCAFFOLD_MODULES).
+        fs.writeFileSync(path.join(scaffoldDir, 'circuit-breaker.ts'), CIRCUIT_BREAKER_SCAFFOLD, 'utf-8');
+        totalCopied += 1;
+        // ADR-PIPELINE-066: unit-economics helper. The demo script calls
+        // writeUnitEconomics() to emit a machine-readable manifest that the
+        // executive renderer prefers over per-employee heuristics.
+        const unitEconomicsCode = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-066)
+// Writes .agentics/runs/<run-id>/unit-economics.json so the executive
+// renderer can use bottom-up unit economics instead of heuristics.
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface DomainUnit {
+  label: string;   // e.g. "occupied room night"
+  abbrev: string;  // e.g. "orn"
+}
 
-  constructor(
-    private readonly name: string,
-    private readonly threshold = 5,
-    private readonly cooldownMs = 30000,
-    private readonly logger = createLogger('circuit-breaker'),
-  ) {}
+export interface UnitEconomicsScope {
+  properties?: number;
+  rooms?: number;
+  sqft?: number;
+  vehicles?: number;
+  beds?: number;
+  agents?: number;
+  units?: number;
+  employees?: number;
+  region_mix?: Array<'NA' | 'EMEA' | 'APAC' | 'LATAM' | 'MEA'>;
+}
 
-  async call<T>(fn: () => Promise<T>): Promise<T> {
-    if (this.state === 'open') {
-      if (Date.now() < this.nextAttempt) {
-        throw new Error(\`Circuit breaker '\${this.name}' is OPEN — retry after \${new Date(this.nextAttempt).toISOString()}\`);
-      }
-      this.state = 'half-open';
-      this.logger.info('circuit.half-open', { name: this.name });
-    }
-    try {
-      const result = await fn();
-      if (this.state === 'half-open') {
-        this.state = 'closed';
-        this.failures = 0;
-        this.logger.info('circuit.closed', { name: this.name });
-      }
-      return result;
-    } catch (err) {
-      this.failures++;
-      if (this.failures >= this.threshold) {
-        this.state = 'open';
-        this.nextAttempt = Date.now() + this.cooldownMs;
-        this.logger.warn('circuit.open', { name: this.name, failures: this.failures, retryAt: new Date(this.nextAttempt).toISOString() });
-      }
-      throw err;
-    }
+export interface UnitEconomics {
+  run_id: string;
+  sector: string;
+  domain_unit: DomainUnit;
+  measured_scope: UnitEconomicsScope;
+  enterprise_scope: UnitEconomicsScope;
+  unit_savings: Record<string, number>;
+  annual_measured_savings_usd: number;
+  annual_extrapolated_savings_usd: number;
+  extrapolation_method: string;
+  confidence: { directional: number; precision: number };
+  generated_at?: string;
+  source?: 'prototype';
+}
+
+function findRunDir(): string | null {
+  // 1. Explicit override
+  const override = process.env['AGENTICS_RUN_DIR'];
+  if (override && existsSync(override)) return override;
+
+  // 2. Walk upward looking for .agentics/runs/latest
+  let dir: string;
+  try {
+    dir = dirname(fileURLToPath(import.meta.url));
+  } catch {
+    dir = process.cwd();
+  }
+  for (let i = 0; i < 6; i++) {
+    const candidate = join(dir, '.agentics', 'runs', 'latest');
+    if (existsSync(candidate)) return resolve(candidate);
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
   }
 
-  getState(): string { return this.state; }
+  // 3. Build from run id if we can find one
+  const simId = process.env['AGENTICS_SIMULATION_ID'];
+  if (simId) {
+    const dest = join(process.cwd(), '.agentics', 'runs', simId);
+    return dest;
+  }
+
+  return join(process.cwd(), '.agentics', 'runs', 'local-run');
+}
+
+export function writeUnitEconomics(manifest: UnitEconomics): string {
+  const runDir = findRunDir();
+  if (!runDir) throw new Error('ECLI-UE-066: unable to resolve run directory');
+  mkdirSync(runDir, { recursive: true });
+  const out = {
+    source: 'prototype' as const,
+    generated_at: new Date().toISOString(),
+    ...manifest,
+  };
+  const filePath = join(runDir, 'unit-economics.json');
+  writeFileSync(filePath, JSON.stringify(out, null, 2) + '\\n', 'utf-8');
+  return filePath;
+}
+
+export function readUnitEconomics(runDir: string): UnitEconomics | null {
+  const filePath = join(runDir, 'unit-economics.json');
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8')) as UnitEconomics;
+  } catch {
+    return null;
+  }
 }
 `;
-        fs.writeFileSync(path.join(scaffoldDir, 'middleware.ts'), middlewareCode, 'utf-8');
+        fs.writeFileSync(path.join(scaffoldDir, 'unit-economics.ts'), unitEconomicsCode, 'utf-8');
+        totalCopied += 1;
+        // ADR-PIPELINE-068: ESM-safe simulation-lineage helper. Every generated
+        // project gets a loader that reads .agentics/plans/manifest.json using
+        // readFileSync + fileURLToPath. NEVER use CommonJS require() in the
+        // generated project — it is "type": "module" and require() throws at
+        // runtime, producing a silent sim-unknown fallback that severs lineage.
+        // The string body lives at module scope (SIMULATION_LINEAGE_SCAFFOLD)
+        // so it can be unit-tested without invoking copyPlanningArtifacts.
+        fs.writeFileSync(path.join(scaffoldDir, 'simulation-lineage.ts'), SIMULATION_LINEAGE_SCAFFOLD, 'utf-8');
         totalCopied += 1;
+        // ADR-PIPELINE-069: Sidecar manifest listing every scaffold-owned
+        // module + its public exports. Consumed by:
+        //   - prompt-generator.ts (injects "do not reimplement" block)
+        //   - post-generation-validator PGV-012 (bans duplicate declarations)
+        // The manifest is the single source of truth — generators MUST NOT
+        // re-emit any export listed here.
+        const ownedManifestPath = path.join(plansDir, 'scaffold', 'OWNED_MODULES.json');
+        fs.writeFileSync(ownedManifestPath, JSON.stringify(buildOwnedModulesManifest(), null, 2) + '\n', 'utf-8');
+        totalCopied += 1;
+        // ADR-PIPELINE-069: Cleanup pass — scan the project tree for files
+        // that redeclare an export listed in OWNED_MODULES.json. Logs the
+        // count; under AGENTICS_AUTO_DEDUPE=true, deletes the duplicates.
+        try {
+            const projectRootForScan = projectRoot;
+            const dupes = detectScaffoldDuplicates(projectRootForScan, OWNED_SCAFFOLD_MODULES);
+            const autoDedupe = process.env['AGENTICS_AUTO_DEDUPE'] === 'true';
+            if (dupes.length > 0) {
+                console.error(`  [SCAFFOLD] scaffold.duplicate.detected count=${dupes.length}` +
+                    (autoDedupe ? ' (auto-deduping)' : ' (set AGENTICS_AUTO_DEDUPE=true to delete)'));
+                for (const d of dupes) {
+                    console.error(`    - ${d.path} redeclares ${d.exportName} (owned by ${d.ownedPath})`);
+                    if (autoDedupe) {
+                        try {
+                            fs.unlinkSync(d.path);
+                        }
+                        catch { /* best-effort */ }
+                    }
+                }
+            }
+            else {
+                console.error('  [SCAFFOLD] scaffold.duplicate.detected: 0');
+            }
+        }
+        catch {
+            // Cleanup is best-effort — never block scaffold emission on a scan failure.
+        }
         // Python scaffold (if SPARC specifies Python or query mentions it)
         const pyDir = path.join(plansDir, 'scaffold', 'python');
         fs.mkdirSync(pyDir, { recursive: true });
@@ -1562,6 +2009,46 @@ These numbers MUST come from the actual scoring/analysis results on seed data,
 not from generic heuristics. The evaluator checks that the business case
 references specific prototype findings.
 
+## 1c. Unit Economics Manifest (ADR-PIPELINE-066) — REQUIRED
+
+Copy \`src/unit-economics.ts\` from scaffold and call \`writeUnitEconomics(...)\`
+at the end of the demo run. This emits \`.agentics/runs/<run-id>/unit-economics.json\`,
+the machine-readable contract the executive renderer prefers over per-employee
+heuristics.
+
+Required fields (derive every number from the prototype's actual computations,
+NOT from employee headcount):
+
+\`\`\`typescript
+import { writeUnitEconomics } from './unit-economics.js';
+
+writeUnitEconomics({
+  run_id: process.env.AGENTICS_SIMULATION_ID ?? 'local-run',
+  sector: 'hospitality',                          // or the detected sector
+  domain_unit: { label: 'occupied room night', abbrev: 'orn' },
+  measured_scope: { properties: 4, rooms: 1450, region_mix: ['NA','EMEA','APAC'] },
+  enterprise_scope: { properties: 100, rooms: 36250, employees: 91000 },
+  unit_savings: {
+    usd_per_orn: 0.82,          // or usd_per_sqft_year / usd_per_vehicle_mile / ...
+    water_liters_per_orn: 14.5,
+    co2_kg_per_orn: 0.62,
+  },
+  annual_measured_savings_usd: measuredSavings,   // from the pilot scenario
+  annual_extrapolated_savings_usd: enterpriseSavings,
+  extrapolation_method: 'linear_by_rooms_weighted_by_regional_cost',
+  confidence: { directional: 0.92, precision: 0.42 },
+});
+\`\`\`
+
+IMPORTANT:
+- **Do NOT multiply employees × $/employee anywhere** to derive the savings figures.
+- \`measured_scope\` must reflect the real pilot data the prototype analyzed.
+- \`enterprise_scope\` and \`annual_extrapolated_savings_usd\` must use a clearly
+  named extrapolation method (linear by rooms, weighted by region, etc.).
+- The executive renderer will refuse to emit a financial analysis if the printed
+  figures drift more than ±1% from the manifest or the scope ratio deviates by
+  more than ±5% (ECLI-SYN-066).
+
 Also print an "Analysis Confidence" section:
 \`\`\`
 ═══ ANALYSIS CONFIDENCE ═══