@open-agent-toolkit/cli 0.2.25 → 0.2.27

package/assets/skills/explainer-kit/scripts/lib/browser-runtime.mjs

@@ -1,6 +1,8 @@
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
 import { createServer } from 'node:http';
+import { dirname } from 'node:path';
 
 // Locations a headless Chromium may already exist at on a developer or CI
 // machine. The core never installs a browser; it only uses one that is there.
@@ -23,6 +25,7 @@ const PROBE_REQUEST_FIELDS = new Set([
   'media',
   'reducedMotion',
   'scenario',
+  'screenshotPath',
   'themeToggle',
   'viewport',
   'wideContent',
@@ -34,6 +37,13 @@ const DISABLE_ANIMATIONS_CSS = `*, *::before, *::after {
   transition-duration: 0s !important;
   scroll-behavior: auto !important;
 }`;
+const BROWSER_SESSION_BRANDS = new WeakSet();
+const CAPTURE_SETTINGS = deepFreeze({
+  format: 'png',
+  fullPage: false,
+  reducedMotion: 'reduce',
+  animationsDisabled: true,
+});
 
 export const RUNTIME_UNAVAILABLE_REASONS = Object.freeze({
   driverMissing: 'browser-driver-not-installed',
@@ -134,6 +144,13 @@ export async function createBrowserProbeSession(options = {}) {
   }
 
   const browser = await runtime.launch();
+  let browserRuntime;
+  try {
+    browserRuntime = launchedBrowserRuntime(browser);
+  } catch (cause) {
+    await browser.close();
+    throw cause;
+  }
   const pages = new Map();
   const server = createServer((request, response) => {
     const html = pages.get(request.url);
@@ -156,9 +173,10 @@ export async function createBrowserProbeSession(options = {}) {
     throw cause;
   }
 
-  return {
+  return brandBrowserProbeSession({
     available: true,
-    runtime: { name: runtime.name, version: browser.version() },
+    runtime: browserRuntime,
+    capture: CAPTURE_SETTINGS,
     probe: async (probeRequest) => {
       const route = `/${randomBytes(12).toString('hex')}.html`;
       pages.set(route, probeRequest.artifact.html);
@@ -175,7 +193,49 @@ export async function createBrowserProbeSession(options = {}) {
     close: async () => {
       await Promise.allSettled([browser.close(), closeServer(server)]);
     },
-  };
+  });
+}
+
+/**
+ * Deterministic probes are useful for bounded unit and integration tests, but
+ * they are never trusted production browser evidence.
+ */
+export function createFixtureBrowserProbeSession({ probe } = {}) {
+  if (typeof probe !== 'function') {
+    throw new TypeError('Fixture browser sessions require a probe callback.');
+  }
+  return brandBrowserProbeSession({
+    available: true,
+    runtime: {
+      kind: 'fixture',
+      name: 'chromium',
+      version: 'deterministic-fixture',
+    },
+    capture: CAPTURE_SETTINGS,
+    probe,
+    close: async () => {},
+  });
+}
+
+export function assertBrowserProbeSession(
+  session,
+  { allowFixture = false } = {},
+) {
+  if (
+    !session ||
+    typeof session !== 'object' ||
+    !BROWSER_SESSION_BRANDS.has(session)
+  ) {
+    throw new TypeError(
+      'Browser evidence requires a trusted browser session brand created by createBrowserProbeSession().',
+    );
+  }
+  if (session.runtime.kind === 'fixture' && !allowFixture) {
+    throw new TypeError(
+      'Deterministic fixture browser sessions are not allowed for production evidence.',
+    );
+  }
+  return session;
 }
 
 export async function probeRenderedPage(browser, url, request) {
@@ -222,6 +282,13 @@ export async function probeRenderedPage(browser, url, request) {
     const themeToggle = request.themeToggle
       ? await probeThemeToggle(page, request.themeToggle)
       : layout.themeToggle;
+    if (request.screenshotPath) {
+      await mkdir(dirname(request.screenshotPath), { recursive: true });
+      await page.screenshot({
+        path: request.screenshotPath,
+        fullPage: false,
+      });
+    }
     return {
       ...layout,
       keyboard,
@@ -256,6 +323,13 @@ function assertProbeRequestFields(request) {
   ) {
     throw new TypeError('Browser probe injectedCss must be a string.');
   }
+  if (
+    request.screenshotPath !== undefined &&
+    (typeof request.screenshotPath !== 'string' ||
+      request.screenshotPath.length === 0)
+  ) {
+    throw new TypeError('Browser probe screenshotPath must be a path string.');
+  }
 }
 
 function probeStylesheet(request) {
@@ -440,3 +514,73 @@ function listen(server) {
 function closeServer(server) {
   return new Promise((resolveClose) => server.close(resolveClose));
 }
+
+function launchedBrowserRuntime(browser) {
+  const name = browser?.browserType?.().name?.();
+  const version = browser?.version?.();
+  if (
+    name !== 'chromium' ||
+    typeof version !== 'string' ||
+    version.trim().length === 0
+  ) {
+    throw new TypeError(
+      'Launched Chromium did not expose a trusted browser type and version.',
+    );
+  }
+  return deepFreeze({
+    kind: 'launched',
+    name,
+    version: version.trim(),
+  });
+}
+
+function brandBrowserProbeSession({
+  available,
+  runtime,
+  capture,
+  probe,
+  close,
+}) {
+  const trustedRuntime = deepFreeze(structuredClone(runtime));
+  const trustedCapture = deepFreeze(structuredClone(capture));
+  const session = Object.freeze({
+    available,
+    runtime: trustedRuntime,
+    capture: trustedCapture,
+    captureIdentity: browserCaptureIdentity(trustedRuntime, trustedCapture),
+    probe,
+    close,
+  });
+  BROWSER_SESSION_BRANDS.add(session);
+  return session;
+}
+
+export function browserCaptureIdentity(runtime, capture) {
+  return `sha256:${createHash('sha256')
+    .update(canonicalStringify({ runtime, capture }))
+    .digest('hex')}`;
+}
+
+function canonicalStringify(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, canonicalize(value[key])]),
+    );
+  }
+  return value;
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) {
+    return value;
+  }
+  for (const nested of Object.values(value)) deepFreeze(nested);
+  return Object.freeze(value);
+}

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

@@ -0,0 +1,243 @@
+import { canonicalStringify, validateContract } from './contracts.mjs';
+
+const CATALOG_SCHEMA_VERSION = 'explainer-kit.initiative-catalog/v1';
+
+export function initiativeCatalogPath(slug) {
+  if (typeof slug !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) {
+    throw new TypeError('Initiative catalog requires a safe initiative slug.');
+  }
+  return `site/initiatives/${slug}/catalog.json`;
+}
+
+export function catalogFromManifest(manifest, publicBaseUrl) {
+  const validation = validateContract('manifest', manifest);
+  if (!validation.valid) {
+    throw new TypeError(
+      `Initiative catalog requires a valid finalized manifest: ${validation.errors[0].message}`,
+    );
+  }
+  const baseUrl = normalizePublicBaseUrl(publicBaseUrl);
+  const artifacts = manifest.artifacts.map((artifact) => {
+    if (
+      artifact.status !== 'built' ||
+      typeof artifact.renderedPath !== 'string' ||
+      !artifact.renderedPath.startsWith('site/') ||
+      typeof artifact.hash !== 'string'
+    ) {
+      throw new TypeError(
+        `Initiative catalog cannot publish non-built artifact ${artifact.id}.`,
+      );
+    }
+    return {
+      id: artifact.id,
+      type: artifact.type,
+      status: artifact.status,
+      renderedPath: artifact.renderedPath,
+      ...(artifact.mediaType && { mediaType: artifact.mediaType }),
+      hash: artifact.hash,
+      url: absoluteArtifactUrl(baseUrl, artifact.renderedPath),
+    };
+  });
+
+  return {
+    schemaVersion: CATALOG_SCHEMA_VERSION,
+    runId: manifest.runId,
+    slug: manifest.slug,
+    recipe: structuredClone(manifest.recipe),
+    createdAt: manifest.createdAt,
+    artifacts,
+    sourceBacklinks: structuredClone(manifest.source.backlinks ?? []),
+  };
+}
+
+export function validateInitiativeCatalog(catalog, manifest, publicBaseUrl) {
+  const errors = [];
+  let normalizedPublicBaseUrl;
+  try {
+    normalizedPublicBaseUrl = normalizePublicBaseUrl(publicBaseUrl);
+  } catch (error) {
+    add(
+      errors,
+      '$.artifacts',
+      'catalog-public-root',
+      error instanceof Error
+        ? error.message
+        : 'Initiative catalog requires an HTTPS public base URL.',
+    );
+  }
+  if (!catalog || typeof catalog !== 'object' || Array.isArray(catalog)) {
+    return {
+      valid: false,
+      errors: [
+        {
+          path: '$',
+          code: 'catalog-shape',
+          message: 'Initiative catalog must be an object.',
+        },
+      ],
+    };
+  }
+  const expectedRootKeys = new Set([
+    'schemaVersion',
+    'runId',
+    'slug',
+    'recipe',
+    'createdAt',
+    'artifacts',
+    'sourceBacklinks',
+  ]);
+  if (Object.keys(catalog).some((key) => !expectedRootKeys.has(key))) {
+    add(
+      errors,
+      '$',
+      'catalog-shape',
+      'Initiative catalog contains an unknown property.',
+    );
+  }
+
+  for (const [field, expected] of [
+    ['schemaVersion', CATALOG_SCHEMA_VERSION],
+    ['runId', manifest?.runId],
+    ['slug', manifest?.slug],
+    ['createdAt', manifest?.createdAt],
+  ]) {
+    if (catalog[field] !== expected) {
+      add(
+        errors,
+        `$.${field}`,
+        'catalog-manifest-mismatch',
+        `Catalog ${field} does not match the finalized manifest.`,
+      );
+    }
+  }
+  if (
+    canonicalStringify(catalog.recipe) !== canonicalStringify(manifest?.recipe)
+  ) {
+    add(
+      errors,
+      '$.recipe',
+      'catalog-manifest-mismatch',
+      'Catalog recipe does not match the finalized manifest.',
+    );
+  }
+
+  const catalogArtifacts = Array.isArray(catalog.artifacts)
+    ? catalog.artifacts
+    : [];
+  const manifestArtifacts = Array.isArray(manifest?.artifacts)
+    ? manifest.artifacts
+    : [];
+  if (
+    !Array.isArray(catalog.artifacts) ||
+    catalogArtifacts.length !== manifestArtifacts.length
+  ) {
+    add(
+      errors,
+      '$.artifacts',
+      'catalog-artifact-parity',
+      'Catalog artifacts must exactly cover the finalized manifest artifacts.',
+    );
+  }
+  for (const [index, artifact] of manifestArtifacts.entries()) {
+    const entry = catalogArtifacts[index];
+    const expected = {
+      id: artifact.id,
+      type: artifact.type,
+      status: artifact.status,
+      renderedPath: artifact.renderedPath,
+      ...(artifact.mediaType && { mediaType: artifact.mediaType }),
+      hash: artifact.hash,
+      url:
+        normalizedPublicBaseUrl === undefined
+          ? undefined
+          : absoluteArtifactUrl(normalizedPublicBaseUrl, artifact.renderedPath),
+    };
+    const actual = entry && typeof entry === 'object' ? entry : undefined;
+    if (canonicalStringify(actual) !== canonicalStringify(expected)) {
+      add(
+        errors,
+        `$.artifacts[${index}]`,
+        'catalog-artifact-mismatch',
+        `Catalog artifact ${artifact.id} is stale or does not match the finalized manifest.`,
+      );
+    }
+  }
+
+  if (
+    canonicalStringify(catalog.sourceBacklinks) !==
+    canonicalStringify(manifest?.source?.backlinks ?? [])
+  ) {
+    add(
+      errors,
+      '$.sourceBacklinks',
+      'catalog-source-mismatch',
+      'Catalog source backlinks do not match the finalized manifest.',
+    );
+  }
+  for (const [index, backlink] of (Array.isArray(catalog.sourceBacklinks)
+    ? catalog.sourceBacklinks
+    : []
+  ).entries()) {
+    if (
+      typeof backlink?.sourceId !== 'string' ||
+      !isImmutableGithubUrl(backlink?.url)
+    ) {
+      add(
+        errors,
+        `$.sourceBacklinks[${index}]`,
+        'catalog-source-url',
+        'Catalog source backlinks must be immutable absolute GitHub URLs.',
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function serializeInitiativeCatalog(catalog) {
+  return `${JSON.stringify(catalog, null, 2)}\n`;
+}
+
+function normalizePublicBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TypeError(
+      'Initiative catalog requires an HTTPS public base URL.',
+    );
+  }
+  if (
+    url.protocol !== 'https:' ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  ) {
+    throw new TypeError(
+      'Initiative catalog requires credential-free HTTPS without query or fragment.',
+    );
+  }
+  return url.href.replace(/\/+$/, '');
+}
+
+function absoluteArtifactUrl(baseUrl, renderedPath) {
+  return `${baseUrl}/${renderedPath
+    .slice('site/'.length)
+    .split('/')
+    .map((part) => encodeURIComponent(part))
+    .join('/')}`;
+}
+
+function isImmutableGithubUrl(value) {
+  return (
+    typeof value === 'string' &&
+    /^https:\/\/github\.com\/[^/]+\/[^/]+\/blob\/[a-f0-9]{40}\/.+#L[1-9][0-9]*(?:-L[1-9][0-9]*)?$/.test(
+      value,
+    )
+  );
+}
+
+function add(errors, path, code, message) {
+  errors.push({ path, code, message });
+}