@open-agent-toolkit/cli 0.2.29 → 0.2.31

package/assets/skills/explainer-kit/scripts/lib/package-coverage.mjs

@@ -1,4 +1,6 @@
 import { createHash } from 'node:crypto';
+import { lstat, readdir, realpath, rm } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
 
 import { browserCaptureIdentity } from './browser-runtime.mjs';
 import { canonicalHash, validateContract } from './contracts.mjs';
@@ -17,6 +19,94 @@ const REVIEW_VIEWPORTS = Object.freeze(['mobile', 'tablet', 'desktop']);
 const SUCCESSFUL_OUTCOMES = new Set(['built-not-durable', 'built-durable']);
 const PARTIAL_REVIEW_OUTCOME = 'built-needs-review';
 
+export function permissibleRunPackagePaths(
+  manifest,
+  { includeManifest = true, includeTerminalEvidence = false } = {},
+) {
+  if (!isObject(manifest) || !isObject(manifest.immutableHashes)) {
+    throw new TypeError(
+      'Run package inventory requires a manifest with immutable hashes.',
+    );
+  }
+  const paths = new Set([
+    ...Object.keys(manifest.immutableHashes),
+    'build-record.json',
+    ...(includeManifest ? ['manifest.json'] : []),
+    ...(includeTerminalEvidence ? ['terminal-evidence.json'] : []),
+  ]);
+  for (const path of paths) assertInventoryPath(path);
+  return [...paths].sort();
+}
+
+export async function enforceRunPackageInventory(
+  runRoot,
+  manifest,
+  {
+    includeManifest = true,
+    includeTerminalEvidence = false,
+    removeUnexpected = false,
+  } = {},
+) {
+  if (typeof runRoot !== 'string' || runRoot.length === 0) {
+    throw new TypeError('Run package inventory requires a run root.');
+  }
+  const rootStats = await lstat(runRoot);
+  const canonicalRoot = await realpath(runRoot);
+  if (rootStats.isSymbolicLink() || !rootStats.isDirectory()) {
+    throw new Error('Run package inventory root is not a real directory.');
+  }
+
+  const allowedFiles = new Set(
+    permissibleRunPackagePaths(manifest, {
+      includeManifest,
+      includeTerminalEvidence,
+    }),
+  );
+  const allowedDirectories = new Set();
+  for (const path of allowedFiles) {
+    let parent = dirname(path);
+    while (parent !== '.') {
+      allowedDirectories.add(parent);
+      parent = dirname(parent);
+    }
+  }
+
+  const presentFiles = new Set();
+  let unexpected = false;
+  async function inspect(relativeRoot = '') {
+    const entries = await readdir(join(canonicalRoot, relativeRoot));
+    for (const entry of entries) {
+      const relativePath = relativeRoot ? `${relativeRoot}/${entry}` : entry;
+      const absolutePath = join(canonicalRoot, relativePath);
+      const stats = await lstat(absolutePath);
+      const allowed =
+        (stats.isDirectory() && allowedDirectories.has(relativePath)) ||
+        (stats.isFile() && allowedFiles.has(relativePath));
+      if (stats.isSymbolicLink() || !allowed) {
+        unexpected = true;
+        if (removeUnexpected) {
+          await rm(absolutePath, { recursive: true, force: true });
+        }
+        continue;
+      }
+      if (stats.isDirectory()) {
+        await inspect(relativePath);
+      } else {
+        presentFiles.add(relativePath);
+      }
+    }
+  }
+  await inspect();
+
+  const missing = [...allowedFiles].some((path) => !presentFiles.has(path));
+  if (unexpected || missing) {
+    throw new Error(
+      'Run package inventory does not match the exact permissible tree.',
+    );
+  }
+  return [...presentFiles].sort();
+}
+
 export function requiredImmutablePackagePaths(manifest, { runMode } = {}) {
   if (!isObject(manifest)) {
     throw new TypeError(
@@ -93,6 +183,11 @@ export async function validateImmutablePackageEvidence(
   if (manifest?.recipe?.id !== 'project-recap') return;
 
   const recorded = Object.keys(manifest.immutableHashes ?? {});
+  if (recorded.some(isLegacyReviewMaterial)) {
+    throw new Error(
+      'Legacy review-gate evidence is not part of the canonical package.',
+    );
+  }
   const successful = SUCCESSFUL_OUTCOMES.has(manifest.outcome);
   const retainsReviewMaterial = recorded.some(isReviewMaterial);
   if (manifest.outcome === PARTIAL_REVIEW_OUTCOME) return;
@@ -274,12 +369,17 @@ export async function validateImmutablePackageEvidence(
 
     const resultPath = `${root}/result.json`;
     const result = parseJson(await readVerified(resultPath), resultPath);
-    const resultValidation = validateContract('visual-review-result', result, {
-      visualReviewRequest: request,
-    });
+    const resultValidation = validateContract(
+      'visual-review-evidence',
+      result,
+      {
+        visualReviewRequest: request,
+        attempt,
+      },
+    );
     if (!resultValidation.valid) {
       throw new Error(
-        `Immutable visual-review result ${resultPath} is invalid: ${resultValidation.errors
+        `Immutable visual-review evidence ${resultPath} is invalid: ${resultValidation.errors
           .map(({ code }) => code)
           .join(', ')}.`,
       );
@@ -309,18 +409,17 @@ function addVisualReviewAttemptPaths(required, manifest, attempt) {
 }
 
 function isReviewMaterial(path) {
-  return (
-    path.startsWith('qa/browser/') ||
-    path.startsWith('qa/visual-review/') ||
-    path.startsWith('qa/review-gate/')
-  );
+  return path.startsWith('qa/browser/') || path.startsWith('qa/visual-review/');
+}
+
+function isLegacyReviewMaterial(path) {
+  return path.startsWith('qa/review-gate/');
 }
 
 function isAttemptTwoMaterial(path) {
   return (
     path === VISUAL_REVISION_PATH ||
-    path.startsWith('qa/visual-review/attempt-2/') ||
-    path.startsWith('qa/review-gate/attempt-2')
+    path.startsWith('qa/visual-review/attempt-2/')
   );
 }
 
@@ -328,6 +427,25 @@ function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function assertInventoryPath(path) {
+  if (
+    typeof path !== 'string' ||
+    path.length === 0 ||
+    path.includes('\\') ||
+    isAbsolute(path) ||
+    path
+      .split('/')
+      .some(
+        (segment) => segment === '' || segment === '.' || segment === '..',
+      ) ||
+    relative('.', path).startsWith(`..${sep}`)
+  ) {
+    throw new TypeError(
+      'Run package inventory paths must be normalized relative paths.',
+    );
+  }
+}
+
 function isPng(bytes) {
   return (
     bytes.length >= 8 &&

package/assets/skills/explainer-kit/scripts/lib/publication-policy.mjs

@@ -0,0 +1,54 @@
+const SUCCESSFUL_STAGE_STATUSES = new Set(['passed', 'warned', 'skipped']);
+
+export function assertManifestPublishable(manifest, { buildRecord } = {}) {
+  const outcome = manifest?.outcome;
+  const reviewFlagged = (manifest?.warnings ?? []).some((warning) =>
+    String(warning).startsWith('visual-review-required:'),
+  );
+  const durableClean = outcome === 'built-durable' && !reviewFlagged;
+  const inFlightClean =
+    outcome === 'incomplete' &&
+    !reviewFlagged &&
+    isCleanPublicationTransition(buildRecord);
+
+  if (!durableClean && !inFlightClean) {
+    throw publicationOutcomeError(
+      `Manifest outcome ${String(outcome ?? 'missing')} is not eligible for publication.`,
+    );
+  }
+  return manifest;
+}
+
+function isCleanPublicationTransition(buildRecord) {
+  if (
+    !buildRecord ||
+    buildRecord.outcome !== 'incomplete' ||
+    !Array.isArray(buildRecord.stages)
+  ) {
+    return false;
+  }
+  const publishIndex = buildRecord.stages.findIndex(
+    ({ id }) => id === 'publish',
+  );
+  if (
+    publishIndex < 0 ||
+    buildRecord.stages[publishIndex]?.status !== 'running'
+  ) {
+    return false;
+  }
+  return buildRecord.stages
+    .slice(0, publishIndex)
+    .every(
+      ({ status, warnings = [] }) =>
+        SUCCESSFUL_STAGE_STATUSES.has(status) &&
+        !warnings.some((warning) =>
+          String(warning).startsWith('visual-review-required:'),
+        ),
+    );
+}
+
+function publicationOutcomeError(message) {
+  const error = new Error(message);
+  error.code = 'E_PUBLISH_OUTCOME';
+  return error;
+}

package/assets/skills/explainer-kit/scripts/lib/recipes.mjs

@@ -62,7 +62,8 @@ const AUTHORING_TYPES = new Set(['markdown', 'html']);
 const SAFE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const RECIPE_FILES = [
   'project-explainer.json',
-  'project-recap.json',
+  'project-recap.v1.json',
+  'project-recap.v2.json',
   'engineer-tour.json',
   'program-recap.json',
 ];

package/assets/skills/explainer-kit/scripts/lib/records.mjs

@@ -15,6 +15,11 @@ import {
   validateImmutablePackageEvidence,
 } from './package-coverage.mjs';
 import { resolveRootConfinedPath } from './safe-paths.mjs';
+import {
+  assertTerminalEvidence,
+  createTerminalEvidence,
+  createVisualReviewEvidence,
+} from './terminal-evidence.mjs';
 
 export {
   PACKAGE_COVERAGE_VERSION,
@@ -137,10 +142,10 @@ export async function updateBuildRecord(run, stage) {
     ...current,
     status: stage.status,
     outputPaths: stage.outputPaths ?? current.outputPaths,
-    warnings: stage.warnings ?? current.warnings,
+    warnings: structuredClone(stage.warnings ?? current.warnings),
   };
   if (stage.error !== undefined) {
-    next.error = stage.error;
+    next.error = localStageFailure(stage.id);
   }
   if (stage.status === 'running' && next.startedAt === undefined) {
     next.startedAt = timestamp;
@@ -202,9 +207,50 @@ export async function writeVisualReviewAttempt(run, { attempt, review } = {}) {
       'Visual review records must contain valid bound contracts.',
     );
   }
+  const retainedResult = createVisualReviewEvidence({
+    request: review.request,
+    attempt,
+    result: review.result,
+  });
+  return writeRetainedVisualReview(run, {
+    attempt,
+    request: review.request,
+    retainedResult,
+  });
+}
+
+export async function writeVisualReviewFailure(
+  run,
+  { attempt, request, kind = 'provider-failure' } = {},
+) {
+  assertRun(run);
+  if (
+    ![1, 2].includes(attempt) ||
+    !isObject(request) ||
+    !['provider-failure', 'pipeline-failure'].includes(kind)
+  ) {
+    throw new TypeError(
+      'Visual review failures require a bound request, attempt, and local failure kind.',
+    );
+  }
+  const retainedResult = createVisualReviewEvidence({
+    request,
+    attempt,
+    failureKind: kind,
+  });
+  return writeRetainedVisualReview(run, {
+    attempt,
+    request,
+    retainedResult,
+  });
+}
 
+async function writeRetainedVisualReview(
+  run,
+  { attempt, request, retainedResult },
+) {
   const directory = `qa/visual-review/attempt-${attempt}`;
-  const retainedRequest = structuredClone(review.request);
+  const retainedRequest = structuredClone(request);
   const paths = [];
   for (const artifact of retainedRequest.renderedArtifacts) {
     for (const evidence of artifact.evidence) {
@@ -228,36 +274,99 @@ export async function writeVisualReviewAttempt(run, { attempt, review } = {}) {
   const requestPath = `${directory}/request.json`;
   const resultPath = `${directory}/result.json`;
   await writeJsonAtomic(run.runRoot, requestPath, retainedRequest);
-  await writeJsonAtomic(run.runRoot, resultPath, review.result);
+  await writeJsonAtomic(run.runRoot, resultPath, retainedResult);
   return [...paths, requestPath, resultPath];
 }
 
-export async function writeVisualReviewFailure(
+export async function writeTerminalEvidence(run, input = {}) {
+  assertRun(run);
+  const allowed = new Set([
+    'outcome',
+    'manifest',
+    'reasons',
+    'evidenceDisposition',
+  ]);
+  const unsupported = Object.keys(input).filter((key) => !allowed.has(key));
+  if (unsupported.length > 0) {
+    throw new TypeError(
+      `Terminal evidence rejects legacy or diagnostic fields: ${unsupported.join(', ')}.`,
+    );
+  }
+  const { outcome, manifest, reasons, evidenceDisposition } = input;
+  if (
+    !['built-needs-review', 'failed'].includes(outcome) ||
+    !['retained', 'partial', 'superseded', 'unavailable'].includes(
+      evidenceDisposition,
+    ) ||
+    !Array.isArray(reasons) ||
+    reasons.some((reason) => !isObject(reason))
+  ) {
+    throw new TypeError('Terminal evidence has an invalid compact shape.');
+  }
+  if (
+    manifest !== undefined &&
+    (!isObject(manifest) ||
+      manifest.runId !== run.runId ||
+      manifest.slug !== run.slug)
+  ) {
+    throw new Error(
+      'Terminal evidence manifest identity does not match the run.',
+    );
+  }
+  const path = 'terminal-evidence.json';
+  try {
+    await access(join(run.runRoot, path));
+    throw new Error('Terminal evidence is immutable once retained.');
+  } catch (caught) {
+    if (caught?.code !== 'ENOENT') throw caught;
+  }
+  const evidence = createTerminalEvidence({
+    runId: run.runId,
+    outcome,
+    manifest,
+    reasons,
+    evidenceDisposition,
+  });
+  await writeJsonAtomic(run.runRoot, path, evidence);
+  return path;
+}
+
+export async function supersedeTerminalEvidence(
   run,
-  { attempt, error, evidence = [] } = {},
+  { manifest, supersededBy } = {},
 ) {
   assertRun(run);
   if (
-    ![1, 2].includes(attempt) ||
-    !(error instanceof Error) ||
-    !Array.isArray(evidence)
+    !isObject(manifest) ||
+    manifest.runId !== run.runId ||
+    manifest.slug !== run.slug
   ) {
-    throw new TypeError(
-      'Visual review failures require an attempt, Error, and evidence array.',
+    throw new Error(
+      'Terminal evidence manifest identity does not match the run.',
     );
   }
-  const path = `qa/review-gate/attempt-${attempt}-error.json`;
-  await writeJsonAtomic(run.runRoot, path, {
-    schemaVersion: 'explainer-kit.visual-review-error/v1',
-    attempt,
-    code: error.code ?? 'E_VISUAL_REVIEW',
-    message: error.message,
-    evidencePaths: evidence.flatMap(({ screenshotPath, metricsPath }) => [
-      screenshotPath,
-      metricsPath,
-    ]),
+  const path = 'terminal-evidence.json';
+  const retained = JSON.parse(await readFile(join(run.runRoot, path), 'utf8'));
+  assertTerminalEvidence(retained, { manifest });
+  if (retained.evidenceDisposition === 'superseded') {
+    throw new Error('Terminal evidence is already superseded.');
+  }
+  const superseded = createTerminalEvidence({
+    runId: run.runId,
+    outcome: manifest.outcome,
+    manifest,
+    reasons: [
+      {
+        stage: 'finalization',
+        kind: 'superseded',
+        count: 1,
+      },
+    ],
+    evidenceDisposition: 'superseded',
+    supersededBy,
   });
-  return [path];
+  await writeJsonAtomic(run.runRoot, path, superseded);
+  return path;
 }
 
 export async function writeVisualRevision(run, { artifactIds, changes } = {}) {
@@ -764,6 +873,14 @@ function assertValidContract(kind, value, context) {
   }
 }
 
+function localStageFailure(stageId) {
+  return {
+    code: `E_${stageId.toUpperCase().replaceAll('-', '_')}`,
+    message: `The ${stageId} stage failed.`,
+    recovery: [`Correct the ${stageId} stage and start a new run.`],
+  };
+}
+
 function assertRun(run) {
   if (
     !isObject(run) ||