@open-agent-toolkit/cli 0.2.73 → 0.2.75

package/assets/skills/oat-explainer-kit/scripts/check-terminal-outcome.mjs

@@ -1,26 +1,52 @@
-import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from 'node:path';
 import { pathToFileURL } from 'node:url';
 
-const TERMINAL_OUTCOMES = new Set([
-  'built-durable',
-  'built-not-durable',
-  'built-needs-review',
-  'failed',
-]);
+import { validateContract } from '../../explainer-kit/scripts/lib/contracts.mjs';
+import { isFlowFailureStage } from '../../explainer-kit/scripts/lib/failure.mjs';
+import { loadRecipe } from '../../explainer-kit/scripts/lib/recipes.mjs';
+import { validateSatisfiedRunPackage } from '../../explainer-kit/scripts/lib/run-package.mjs';
 
 /**
  * A skip reason is the recorded `source` of the skip decision, so the guard
  * accepts exactly the sources that may produce a `skip` recap record.
  */
-const SKIP_REASONS = new Set(['interactive', 'capability_probe']);
+const SKIP_REASONS = new Set([
+  'interactive',
+  'failed_attempt',
+  'capability_probe',
+]);
 
-export function checkTerminalOutcome({ intent, outcome, reason }) {
+export function checkTerminalOutcome({
+  intent,
+  reason,
+  manifest = null,
+  failure = null,
+  failureRootHash = null,
+}) {
   if (reason !== undefined && !SKIP_REASONS.has(reason)) {
     throw recapOutcomeError(
       `Recap skip reason must be one of ${[...SKIP_REASONS].join(', ')}.`,
     );
   }
   if (intent === 'skip') {
+    if (
+      reason === 'failed_attempt' &&
+      !(isFailedManifest(manifest) || isFlowFailure(failure, failureRootHash))
+    ) {
+      throw recapOutcomeError(
+        'failed_attempt requires a failed or incomplete manifest or failure.json.',
+      );
+    }
     return { ok: true, intent, outcome: null, reason: reason ?? null };
   }
   if (reason !== undefined) {
@@ -31,19 +57,106 @@ export function checkTerminalOutcome({ intent, outcome, reason }) {
   if (intent !== 'generate') {
     throw recapOutcomeError('Recap intent must be generate or skip.');
   }
-  if (!TERMINAL_OUTCOMES.has(outcome)) {
+  throw recapOutcomeError(
+    'A terminal recap outcome requires a complete satisfied project-recap package.',
+  );
+}
+
+async function main(argv) {
+  const { intent, manifestPath, failurePath, projectRoot, reason } =
+    parseArguments(argv);
+  if (manifestPath !== undefined && failurePath !== undefined) {
+    throw recapOutcomeError(
+      'Use either --manifest or --failure as failed-attempt evidence, not both.',
+    );
+  }
+  if (intent === 'generate') {
+    if (
+      reason !== undefined ||
+      failurePath !== undefined ||
+      manifestPath === undefined ||
+      basename(manifestPath) !== 'manifest.json'
+    ) {
+      throw recapOutcomeError(
+        'Generated project recaps require the canonical manifest.json for a complete satisfied package.',
+      );
+    }
+    try {
+      const manifest = await validateSatisfiedRunPackage(
+        dirname(manifestPath),
+        loadRecipe('project-recap', '2'),
+      );
+      return { ok: true, intent, outcome: manifest.outcome };
+    } catch (error) {
+      throw recapOutcomeError(
+        `Generated project recap package assurance failed: ${error.message}`,
+      );
+    }
+  }
+  if (
+    (manifestPath !== undefined || failurePath !== undefined) &&
+    reason !== 'failed_attempt'
+  ) {
     throw recapOutcomeError(
-      'Generated project recaps require a terminal recap outcome before approval.',
+      'Failed-attempt evidence is accepted only for a skip/failed_attempt intent.',
     );
   }
-  return { ok: true, intent, outcome };
+  if (projectRoot !== undefined && reason !== 'failed_attempt') {
+    throw recapOutcomeError(
+      'A failed-attempt project root applies only to skip/failed_attempt evidence.',
+    );
+  }
+  if (reason === 'failed_attempt') {
+    if (intent !== 'skip') {
+      throw recapOutcomeError(
+        'Failed-attempt evidence is accepted only for a skip/failed_attempt intent.',
+      );
+    }
+    if (projectRoot !== undefined) {
+      const suppliedPath = manifestPath ?? failurePath;
+      if (suppliedPath === undefined) {
+        return validateFailedAttemptEvidence({});
+      }
+      const canonicalProjectRoot = await realpath(projectRoot);
+      const locator = relative(canonicalProjectRoot, resolve(suppliedPath))
+        .split(sep)
+        .join('/');
+      const evidence = await resolveProjectFailedAttemptEvidence({
+        projectPath: canonicalProjectRoot,
+        locator,
+      });
+      if ((evidence.kind === 'manifest') !== (manifestPath !== undefined)) {
+        throw recapOutcomeError(
+          'Failed-attempt evidence kind does not match its guard flag.',
+        );
+      }
+      return validateFailedAttemptEvidence({
+        ...(evidence.kind === 'manifest'
+          ? { manifestPath: evidence.path }
+          : { failurePath: evidence.path }),
+      });
+    }
+    return validateFailedAttemptEvidence({ manifestPath, failurePath });
+  }
+  return checkTerminalOutcome({
+    intent,
+    ...(reason !== undefined && { reason }),
+  });
 }
 
-async function main(argv) {
-  const { intent, manifestPath, reason } = parseArguments(argv);
-  let outcome;
+export async function validateFailedAttemptEvidence({
+  manifestPath,
+  failurePath,
+}) {
+  if (manifestPath !== undefined && failurePath !== undefined) {
+    throw recapOutcomeError(
+      'Use either --manifest or --failure as failed-attempt evidence, not both.',
+    );
+  }
+  let manifest;
+  let failure;
+  let failureRootHash;
   if (manifestPath !== undefined) {
-    let manifest;
     try {
       manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
     } catch (error) {
@@ -51,18 +164,105 @@ async function main(argv) {
         `Recap manifest could not be read: ${error.message}`,
       );
     }
-    outcome = manifest?.outcome;
+  }
+  if (failurePath !== undefined) {
+    if (basename(failurePath) !== 'failure.json') {
+      throw recapOutcomeError(
+        'Failed-attempt evidence must name a failure.json file.',
+      );
+    }
+    try {
+      failure = JSON.parse(await readFile(failurePath, 'utf8'));
+      failureRootHash = hashText(await realpath(dirname(failurePath)));
+    } catch (error) {
+      throw recapOutcomeError(
+        `Recap failure evidence could not be read: ${error.message}`,
+      );
+    }
   }
   return checkTerminalOutcome({
-    intent,
-    outcome,
-    ...(reason !== undefined && { reason }),
+    intent: 'skip',
+    manifest,
+    failure,
+    failureRootHash,
+    reason: 'failed_attempt',
   });
 }
 
+export async function resolveProjectFailedAttemptEvidence({
+  projectPath,
+  locator,
+}) {
+  try {
+    if (typeof locator !== 'string') {
+      throw new Error('the persisted locator is not a string');
+    }
+    const parts = locator.split('/');
+    const runSlug = parts[1];
+    const fileName = parts[2];
+    if (
+      parts.length !== 3 ||
+      parts[0] !== 'explainers' ||
+      typeof runSlug !== 'string' ||
+      !/^[a-z0-9][a-z0-9._-]*$/.test(runSlug) ||
+      !['manifest.json', 'failure.json'].includes(fileName)
+    ) {
+      throw new Error(
+        'the locator must name explainers/<run-slug>/manifest.json or failure.json',
+      );
+    }
+
+    const projectRoot = await realpath(projectPath);
+    const explainersRoot = await realpath(join(projectRoot, 'explainers'));
+    if (!isContained(projectRoot, explainersRoot)) {
+      throw new Error('the explainers root escapes the project root');
+    }
+    const runRoot = await realpath(join(explainersRoot, runSlug));
+    if (!isContained(explainersRoot, runRoot)) {
+      throw new Error('the evidence run escapes the explainers root');
+    }
+    const evidencePath = await realpath(join(projectRoot, locator));
+    if (
+      !isContained(runRoot, evidencePath) ||
+      basename(evidencePath) !== fileName
+    ) {
+      throw new Error('the evidence path escapes its declared run root');
+    }
+    const evidenceInfo = await lstat(evidencePath);
+    if (!evidenceInfo.isFile()) {
+      throw new Error('the evidence path is not a regular file');
+    }
+
+    const kind = fileName === 'manifest.json' ? 'manifest' : 'failure';
+    await validateFailedAttemptEvidence({
+      ...(kind === 'manifest'
+        ? { manifestPath: evidencePath }
+        : { failurePath: evidencePath }),
+    });
+    return { kind, path: evidencePath };
+  } catch (error) {
+    if (error?.code === 'E_RECAP_OUTCOME') throw error;
+    throw recapOutcomeError(
+      `Failed-attempt evidence containment failed: ${error.message}`,
+    );
+  }
+}
+
+function isContained(root, candidate) {
+  const relation = relative(root, candidate);
+  return (
+    relation !== '' &&
+    relation !== '..' &&
+    !relation.startsWith(`..${sep}`) &&
+    !isAbsolute(relation)
+  );
+}
+
 function parseArguments(argv) {
   let intent;
   let manifestPath;
+  let failurePath;
+  let projectRoot;
   let reason;
   for (let index = 0; index < argv.length; index += 2) {
     const flag = argv[index];
@@ -74,13 +274,48 @@ function parseArguments(argv) {
       intent = value;
     } else if (flag === '--manifest') {
       manifestPath = value;
+    } else if (flag === '--failure') {
+      failurePath = value;
+    } else if (flag === '--project-root') {
+      projectRoot = value;
     } else if (flag === '--skip-reason') {
       reason = value;
     } else {
       throw recapOutcomeError(`Unsupported argument: ${flag}.`);
     }
   }
-  return { intent, manifestPath, reason };
+  return { intent, manifestPath, failurePath, projectRoot, reason };
+}
+
+function isFailedManifest(value) {
+  if (!value || !validateContract('manifest', value).valid) return false;
+  return (
+    ['failed', 'incomplete'].includes(value.outcome) &&
+    value.artifacts.length > 0 &&
+    value.artifacts.every(({ status }) => status === 'failed')
+  );
+}
+
+function isFlowFailure(value, expectedRootHash) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  return (
+    keys.length === 5 &&
+    keys.every((key) =>
+      ['schemaVersion', 'runRootHash', 'stage', 'cause', 'at'].includes(key),
+    ) &&
+    value.schemaVersion === 'explainer-kit.failure/v1' &&
+    value.runRootHash === expectedRootHash &&
+    isFlowFailureStage(value.stage) &&
+    typeof value.cause === 'string' &&
+    value.cause.length > 0 &&
+    typeof value.at === 'string' &&
+    !Number.isNaN(Date.parse(value.at))
+  );
+}
+
+function hashText(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
 }
 
 function recapOutcomeError(message) {

package/assets/skills/oat-explainer-kit/scripts/persist-intent.mjs

@@ -2,7 +2,10 @@ import { createHash, randomUUID } from 'node:crypto';
 import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 
-import { validateIntentRecord } from './resolve-intent.mjs';
+import {
+  validateIntentRecord,
+  validateWritableIntentRecord,
+} from './resolve-intent.mjs';
 
 const FRONTMATTER_KEYS = Object.freeze({
   projectExplainer: 'oat_project_explainer',
@@ -17,7 +20,7 @@ export function hashStateContent(content) {
 }
 
 export function updateStateFrontmatter(content, product, record) {
-  validateIntentRecord(product, record);
+  validateWritableIntentRecord(product, record);
   if (typeof content !== 'string') {
     throw new TypeError('State content must be a string.');
   }
@@ -47,6 +50,9 @@ export function updateStateFrontmatter(content, product, record) {
     `  decision: ${record.decision}`,
     `  source: ${record.source}`,
     `  decided_at: '${record.decided_at}'`,
+    ...(Object.hasOwn(record, 'failed_attempt_evidence')
+      ? [`  failed_attempt_evidence: '${record.failed_attempt_evidence}'`]
+      : []),
   ];
   if (matches.length === 0) {
     lines.splice(closingIndex, 0, ...replacement);
@@ -66,6 +72,69 @@ export function updateStateFrontmatter(content, product, record) {
   return lines.join(newline);
 }
 
+export function readIntentFromStateContent(content, product) {
+  if (typeof content !== 'string') {
+    throw new TypeError('State content must be a string.');
+  }
+  const key = FRONTMATTER_KEYS[product];
+  if (!key) {
+    throw new Error(`Unsupported lifecycle product: ${String(product)}`);
+  }
+  const lines = content.split(/\r?\n/);
+  if (lines[0] !== '---') {
+    throw new Error('Project state must begin with YAML frontmatter.');
+  }
+  const closingIndex = lines.indexOf('---', 1);
+  if (closingIndex < 0) {
+    throw new Error('Project state has no closing frontmatter delimiter.');
+  }
+
+  const keyPattern = new RegExp(`^${key}\\s*:\\s*(.*)$`);
+  const matches = [];
+  for (let index = 1; index < closingIndex; index += 1) {
+    const match = lines[index].match(keyPattern);
+    if (match) matches.push({ index, value: match[1].trim() });
+  }
+  if (matches.length > 1) {
+    throw new Error(`Project state contains duplicate ${key} fields.`);
+  }
+  if (matches.length === 0 || ['null', '~'].includes(matches[0].value)) {
+    return null;
+  }
+  if (matches[0].value !== '') {
+    throw new Error(`${key} must use a lifecycle decision block.`);
+  }
+
+  const record = {};
+  for (
+    let index = matches[0].index + 1;
+    index < closingIndex && /^[ \t]/.test(lines[index]);
+    index += 1
+  ) {
+    if (lines[index].trim() === '') continue;
+    const field = lines[index].match(
+      /^\s+(decision|source|decided_at|failed_attempt_evidence)\s*:\s*(.+?)\s*$/,
+    );
+    if (!field || Object.hasOwn(record, field[1])) {
+      throw new Error(`${key} contains an invalid lifecycle decision field.`);
+    }
+    record[field[1]] = parseStateScalar(field[2]);
+  }
+  validateIntentRecord(product, record);
+  return record;
+}
+
+export async function readPersistedIntent({ statePath, product }) {
+  if (typeof statePath !== 'string' || basename(statePath) !== 'state.md') {
+    throw new Error('Lifecycle intent may only be read from state.md.');
+  }
+  const fileInfo = await lstat(statePath);
+  if (fileInfo.isSymbolicLink() || !fileInfo.isFile()) {
+    throw new Error('Project state must be a regular file, not a symlink.');
+  }
+  return readIntentFromStateContent(await readFile(statePath, 'utf8'), product);
+}
+
 export async function persistIntent({
   statePath,
   product,
@@ -84,7 +153,7 @@ export async function persistIntent({
   ) {
     throw new TypeError('expectedHash must be a SHA-256 state content hash.');
   }
-  validateIntentRecord(product, record);
+  validateWritableIntentRecord(product, record);
 
   const fileInfo = await lstat(statePath);
   if (fileInfo.isSymbolicLink() || !fileInfo.isFile()) {
@@ -128,3 +197,13 @@ function assertExpectedHash(content, expectedHash) {
   error.code = 'E_INTENT_STALE_WRITE';
   throw error;
 }
+
+function parseStateScalar(value) {
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1).replaceAll("''", "'");
+  }
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return JSON.parse(value);
+  }
+  return value;
+}

package/assets/skills/oat-explainer-kit/scripts/resolve-config.mjs

@@ -1,5 +1,4 @@
 import { execFile } from 'node:child_process';
-import { join } from 'node:path';
 import { promisify } from 'node:util';
 
 import { resolveSourceAwarePath } from './resolve-paths.mjs';
@@ -11,12 +10,6 @@ export const EXPLAINER_CONFIG_KEYS = Object.freeze([
   'explainers.defaults.palette',
   'explainers.defaults.visualProfile',
   'explainers.defaults.themeBundlePath',
-  'explainers.publish.provider',
-  'explainers.publish.s3Uri',
-  'explainers.publish.publicBaseUrl',
-  'explainers.publish.awsRegion',
-  'explainers.publish.publicAccess',
-  'explainers.publish.awsProfile',
   'workflow.explainers.projectExplainer',
   'workflow.explainers.projectRecap',
 ]);
@@ -116,7 +109,6 @@ export async function resolveExplainerConfig({
     }
   }
 
-  const { publish, publishReport } = resolvePublish(values, sources);
   const preferences = {
     projectExplainer: resolvePreference(
       'workflow.explainers.projectExplainer',
@@ -132,77 +124,11 @@ export async function resolveExplainerConfig({
     values,
     sources,
     theme,
-    publish,
-    publishReport,
     preferences,
     warnings,
   };
 }
 
-export function toExplainerRunRequest({
-  resolvedConfig,
-  recipe,
-  slug,
-  outputRoot,
-  factBase,
-  mode,
-  durabilityStrategy = 'none',
-  artDirection,
-  defaultMode,
-  renderStrategy,
-  retainRawArtDirection = false,
-}) {
-  if (!resolvedConfig || !outputRoot || !factBase) {
-    throw new TypeError(
-      'resolvedConfig, outputRoot, and factBase are required to build a run request.',
-    );
-  }
-  if (retainRawArtDirection && !nullableString(artDirection)) {
-    throw new Error(
-      'retainRawArtDirection requires a non-empty artDirection runtime input.',
-    );
-  }
-
-  const theme = {
-    ...resolvedConfig.theme,
-    ...(nullableString(artDirection)
-      ? { artDirection: artDirection.trim() }
-      : {}),
-    ...(defaultMode ? { defaultMode } : {}),
-    ...(renderStrategy ? { renderStrategy } : {}),
-  };
-  const durability = { strategy: durabilityStrategy };
-  if (durabilityStrategy === 'publish') {
-    if (!resolvedConfig.publish) {
-      throw new Error(
-        'Publish durability requires a complete explainer publish configuration.',
-      );
-    }
-    durability.publish = {
-      schemaVersion: 'explainer-kit.publish-request/v2',
-      ...resolvedConfig.publish,
-      publicAccess: resolvedConfig.publish.publicAccess ?? 'public',
-      siteRoot: join(outputRoot, slug, 'site'),
-      manifestPath: join(outputRoot, slug, 'manifest.json'),
-    };
-  }
-
-  return {
-    schemaVersion: 'explainer-kit.run-request/v1',
-    recipe: {
-      id: recipe,
-      version: recipe === 'project-recap' ? '2' : '1',
-    },
-    slug,
-    outputRoot,
-    factBase,
-    ...(Object.keys(theme).length > 0 ? { theme } : {}),
-    durability,
-    privacy: { retainRawArtDirection },
-    mode,
-  };
-}
-
 async function getConfigFromCli(repoRoot, key) {
   let stdout;
   try {
@@ -264,15 +190,6 @@ function normalizeRuntimeValue(key, value) {
     );
   }
   const normalized = value.trim();
-  if (key === 'explainers.publish.provider' && normalized !== 's3-static') {
-    throw new Error(`${key} runtime override must be s3-static.`);
-  }
-  if (
-    key === 'explainers.publish.publicAccess' &&
-    !['public', 'protected'].includes(normalized)
-  ) {
-    throw new Error(`${key} runtime override must be public or protected.`);
-  }
   if (key === 'explainers.defaults.style' && !STYLES.has(normalized)) {
     throw new Error(
       `${key} runtime override must name a curated explainer style.`,
@@ -281,88 +198,9 @@ function normalizeRuntimeValue(key, value) {
   if (key.startsWith('workflow.explainers.') && !PREFERENCES.has(normalized)) {
     throw new Error(`${key} runtime override must be always, ask, or never.`);
   }
-  if (
-    key === 'explainers.publish.s3Uri' &&
-    !/^s3:\/\/[^/\s]+(?:\/.*)?$/.test(normalized)
-  ) {
-    throw new Error(`${key} runtime override must be an s3:// URI.`);
-  }
-  if (
-    key === 'explainers.publish.publicBaseUrl' &&
-    !/^https:\/\/[^\s]+$/.test(normalized)
-  ) {
-    throw new Error(`${key} runtime override must be an https:// URL.`);
-  }
-  if (
-    key === 'explainers.publish.s3Uri' ||
-    key === 'explainers.publish.publicBaseUrl'
-  ) {
-    return normalized.replace(/\/+$/, '');
-  }
   return normalized;
 }
 
-function resolvePublish(values, sources) {
-  const fields = {
-    provider: nullableString(values['explainers.publish.provider']),
-    s3Uri: nullableString(values['explainers.publish.s3Uri']),
-    publicBaseUrl: nullableString(values['explainers.publish.publicBaseUrl']),
-    awsRegion: nullableString(values['explainers.publish.awsRegion']),
-  };
-  if (fields.provider && fields.provider !== 's3-static') {
-    throw new Error(
-      `Unsupported explainer publish provider: ${fields.provider}`,
-    );
-  }
-  const missing = Object.entries(fields)
-    .filter(([, value]) => !value)
-    .map(([key]) => key);
-  if (missing.length > 0) {
-    return {
-      publish: null,
-      publishReport: {
-        mode: 'build-only',
-        publishCapable: false,
-        missing,
-      },
-    };
-  }
-  if (!/^s3:\/\/[^/\s]+(?:\/.*)?$/.test(fields.s3Uri)) {
-    throw new Error('explainers.publish.s3Uri must be a valid s3:// URI.');
-  }
-  if (!/^https:\/\/[^\s]+$/.test(fields.publicBaseUrl)) {
-    throw new Error(
-      'explainers.publish.publicBaseUrl must be a valid https:// URL.',
-    );
-  }
-
-  const awsProfile = nullableString(values['explainers.publish.awsProfile']);
-  const publicAccess =
-    nullableString(values['explainers.publish.publicAccess']) ?? 'public';
-  if (!['public', 'protected'].includes(publicAccess)) {
-    throw new Error(
-      'explainers.publish.publicAccess must be public or protected.',
-    );
-  }
-  return {
-    publish: {
-      provider: fields.provider,
-      s3Uri: fields.s3Uri.replace(/\/+$/, ''),
-      publicBaseUrl: fields.publicBaseUrl.replace(/\/+$/, ''),
-      awsRegion: fields.awsRegion,
-      ...(sources['explainers.publish.publicAccess'] !== 'default'
-        ? { publicAccess }
-        : {}),
-      ...(awsProfile ? { awsProfile } : {}),
-    },
-    publishReport: {
-      mode: 'publish-capable',
-      publishCapable: true,
-      missing: [],
-    },
-  };
-}
-
 function resolvePreference(key, value) {
   const preference = nullableString(value) ?? 'ask';
   if (!PREFERENCES.has(preference)) {