@open-agent-toolkit/cli 0.2.5 → 0.2.6

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

@@ -0,0 +1,289 @@
+import { readFileSync } from 'node:fs';
+
+const RECIPE_SCHEMA_VERSION = 'explainer-kit.recipe/v1';
+const RECIPE_ROOT_KEYS = [
+  'artifacts',
+  'discoveryLimits',
+  'id',
+  'requiredNarrative',
+  'schemaVersion',
+  'sourceRoles',
+  'version',
+];
+const SOURCE_ROLE_KEYS = [
+  'accepts',
+  'maxBindings',
+  'minBindings',
+  'required',
+  'role',
+];
+const ARTIFACT_KEYS = ['id', 'required', 'template', 'type'];
+const DISCOVERY_LIMIT_KEYS = ['consecutiveNoNewFindingsRounds', 'maxRounds'];
+const SOURCE_KINDS = new Set([
+  'file',
+  'directory',
+  'git',
+  'github',
+  'session',
+  'other',
+]);
+const ARTIFACT_TYPES = new Set(['hub', 'diagram', 'explainer', 'deck']);
+const RECIPE_FILES = [
+  'project-explainer.json',
+  'project-recap.json',
+  'engineer-tour.json',
+  'program-recap.json',
+];
+
+const RECIPES = new Map(
+  RECIPE_FILES.map((file) => {
+    const recipe = JSON.parse(
+      readFileSync(new URL(`../../recipes/${file}`, import.meta.url), 'utf8'),
+    );
+    validateRecipe(recipe, file);
+    return [`${recipe.id}@${recipe.version}`, recipe];
+  }),
+);
+
+export function loadRecipe(id, version) {
+  const recipe = RECIPES.get(`${id}@${version}`);
+  if (!recipe) {
+    const error = new Error(`Unsupported recipe: ${id}@${version}`);
+    error.code = 'E_RECIPE_UNSUPPORTED';
+    throw error;
+  }
+  return structuredClone(recipe);
+}
+
+export function validateSourceBindings(recipe, bindings) {
+  const errors = [];
+  if (!Array.isArray(bindings)) {
+    return { valid: false, errors: ['Source bindings must be an array'] };
+  }
+
+  const roles = new Map(recipe.sourceRoles.map((role) => [role.role, role]));
+  const sourceSets = new Map();
+  for (const binding of bindings) {
+    const role = roles.get(binding?.role);
+    if (!role) {
+      errors.push(`Unknown source role: ${binding?.role}`);
+      continue;
+    }
+    const sets = sourceSets.get(role.role) ?? new Set();
+    sets.add(binding.sourceSetId ?? Symbol());
+    sourceSets.set(role.role, sets);
+    if (!role.accepts.includes(binding.kind)) {
+      errors.push(
+        `Source role ${role.role} does not accept kind ${binding.kind}`,
+      );
+    }
+  }
+
+  for (const role of recipe.sourceRoles) {
+    const count = sourceSets.get(role.role)?.size ?? 0;
+    if (role.required && count < role.minBindings) {
+      errors.push(`Missing required source role: ${role.role}`);
+    }
+    if (count > role.maxBindings) {
+      errors.push(
+        `Source role ${role.role} allows at most ${role.maxBindings} binding`,
+      );
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function validateContentModel(recipe, contentModel) {
+  const errors = [];
+  if (!isObject(contentModel)) {
+    return { valid: false, errors: ['Content model must be an object'] };
+  }
+
+  if (
+    !recipe.artifacts.some(
+      (artifact) => artifact.id === contentModel.artifactId,
+    )
+  ) {
+    errors.push(`Unknown recipe artifact: ${contentModel.artifactId}`);
+  }
+  if (!Array.isArray(contentModel.sections)) {
+    errors.push('Content model sections must be an array');
+    return { valid: false, errors };
+  }
+
+  const sectionCounts = new Map();
+  for (const section of contentModel.sections) {
+    if (
+      !isObject(section) ||
+      typeof section.id !== 'string' ||
+      typeof section.content !== 'string'
+    ) {
+      errors.push('Narrative sections require string id and content');
+      continue;
+    }
+    sectionCounts.set(section.id, (sectionCounts.get(section.id) ?? 0) + 1);
+    if (/<\s*script\b/i.test(section.content)) {
+      errors.push(
+        `Narrative section ${section.id} contains raw script content`,
+      );
+    }
+  }
+
+  for (const sectionId of recipe.requiredNarrative) {
+    const count = sectionCounts.get(sectionId) ?? 0;
+    if (count === 0) {
+      errors.push(`Missing required narrative section: ${sectionId}`);
+    } else if (count > 1) {
+      errors.push(`Duplicate narrative section: ${sectionId}`);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function shouldStopDiscovery(recipe, findingsByRound) {
+  if (
+    !Array.isArray(findingsByRound) ||
+    findingsByRound.some((count) => !Number.isInteger(count) || count < 0)
+  ) {
+    throw new TypeError(
+      'Discovery round findings must be an array of non-negative integers',
+    );
+  }
+
+  const { consecutiveNoNewFindingsRounds, maxRounds } = recipe.discoveryLimits;
+  if (findingsByRound.length >= maxRounds) {
+    return true;
+  }
+  if (findingsByRound.length < consecutiveNoNewFindingsRounds) {
+    return false;
+  }
+  return findingsByRound
+    .slice(-consecutiveNoNewFindingsRounds)
+    .every((count) => count === 0);
+}
+
+function validateRecipe(recipe, file) {
+  assertObject(recipe, `${file} recipe`);
+  assertExactKeys(recipe, RECIPE_ROOT_KEYS, `${file} recipe`);
+  assert(
+    recipe.schemaVersion === RECIPE_SCHEMA_VERSION,
+    `${file} has unsupported schemaVersion`,
+  );
+  assertNonEmptyString(recipe.id, `${file} id`);
+  assertNonEmptyString(recipe.version, `${file} version`);
+  assertUniqueNonEmptyStrings(
+    recipe.requiredNarrative,
+    `${file} requiredNarrative`,
+  );
+
+  assert(
+    Array.isArray(recipe.sourceRoles) && recipe.sourceRoles.length > 0,
+    `${file} sourceRoles must be a non-empty array`,
+  );
+  const roleNames = [];
+  for (const role of recipe.sourceRoles) {
+    assertObject(role, `${file} source role`);
+    assertExactKeys(role, SOURCE_ROLE_KEYS, `${file} source role`);
+    assertNonEmptyString(role.role, `${file} source role name`);
+    roleNames.push(role.role);
+    assert(typeof role.required === 'boolean', `${file} role required`);
+    assert(
+      Array.isArray(role.accepts) &&
+        role.accepts.length > 0 &&
+        role.accepts.every((kind) => SOURCE_KINDS.has(kind)),
+      `${file} role accepts unsupported source kinds`,
+    );
+    assert(
+      Number.isInteger(role.minBindings) &&
+        role.minBindings >= 0 &&
+        Number.isInteger(role.maxBindings) &&
+        role.maxBindings >= role.minBindings,
+      `${file} role has invalid binding limits`,
+    );
+    assert(
+      role.required === role.minBindings > 0,
+      `${file} role required flag must match minBindings`,
+    );
+  }
+  assertUnique(roleNames, `${file} source role names`);
+
+  assert(
+    Array.isArray(recipe.artifacts) && recipe.artifacts.length > 0,
+    `${file} artifacts must be a non-empty array`,
+  );
+  const artifactIds = [];
+  for (const artifact of recipe.artifacts) {
+    assertObject(artifact, `${file} artifact`);
+    assertExactKeys(artifact, ARTIFACT_KEYS, `${file} artifact`);
+    assertNonEmptyString(artifact.id, `${file} artifact id`);
+    artifactIds.push(artifact.id);
+    assert(
+      ARTIFACT_TYPES.has(artifact.type),
+      `${file} artifact has unsupported type`,
+    );
+    assertNonEmptyString(artifact.template, `${file} artifact template`);
+    assert(typeof artifact.required === 'boolean', `${file} artifact required`);
+  }
+  assertUnique(artifactIds, `${file} artifact ids`);
+
+  assertObject(recipe.discoveryLimits, `${file} discoveryLimits`);
+  assertExactKeys(
+    recipe.discoveryLimits,
+    DISCOVERY_LIMIT_KEYS,
+    `${file} discoveryLimits`,
+  );
+  assert(
+    recipe.discoveryLimits.consecutiveNoNewFindingsRounds === 2,
+    `${file} discovery must stop after exactly two no-new-findings rounds`,
+  );
+  assert(
+    Number.isInteger(recipe.discoveryLimits.maxRounds) &&
+      recipe.discoveryLimits.maxRounds >= 2,
+    `${file} discovery maxRounds must be an integer of at least two`,
+  );
+}
+
+function assertObject(value, label) {
+  assert(isObject(value), `${label} must be an object`);
+}
+
+function assertExactKeys(value, expected, label) {
+  const actual = Object.keys(value).sort();
+  assert(
+    actual.length === expected.length &&
+      actual.every((key, index) => key === expected[index]),
+    `${label} has unknown or missing keys`,
+  );
+}
+
+function assertNonEmptyString(value, label) {
+  assert(
+    typeof value === 'string' && value.length > 0,
+    `${label} must be a non-empty string`,
+  );
+}
+
+function assertUniqueNonEmptyStrings(value, label) {
+  assert(
+    Array.isArray(value) && value.length > 0,
+    `${label} must be a non-empty array`,
+  );
+  for (const entry of value) {
+    assertNonEmptyString(entry, label);
+  }
+  assertUnique(value, label);
+}
+
+function assertUnique(values, label) {
+  assert(new Set(values).size === values.length, `${label} must be unique`);
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new TypeError(message);
+  }
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,231 @@
+import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { validateContract } from './contracts.mjs';
+import { createConfinedRunRoot, writeJsonAtomic } from './fs-safe.mjs';
+
+const STAGE_IDS = [
+  'validate',
+  'fact-base',
+  'content',
+  'theme',
+  'render',
+  'qa',
+  'durability',
+  'publish',
+];
+const SUCCESSFUL_TERMINAL_STATUSES = new Set(['passed', 'warned', 'skipped']);
+const TERMINAL_STATUSES = new Set([...SUCCESSFUL_TERMINAL_STATUSES, 'failed']);
+const ALLOWED_TRANSITIONS = {
+  pending: new Set(['running', 'failed', 'skipped']),
+  running: new Set(['running', 'passed', 'warned', 'failed']),
+};
+
+export async function initializeRun(request) {
+  if (!isObject(request)) {
+    throw new TypeError('Run request must be an object.');
+  }
+
+  const normalizedRequest = structuredClone(request);
+  normalizedRequest.slug = normalizeRequestSlug(request.slug);
+  normalizedRequest.theme = {
+    ...(isObject(normalizedRequest.theme) ? normalizedRequest.theme : {}),
+    renderStrategy: normalizedRequest.theme?.renderStrategy ?? 'default-only',
+  };
+
+  assertValidContract('run-request', normalizedRequest);
+
+  const paths = await createConfinedRunRoot(
+    normalizedRequest.outputRoot,
+    normalizedRequest.slug,
+  );
+  normalizedRequest.outputRoot = paths.outputRoot;
+
+  const runId = `run-${randomUUID()}`;
+  const startedAt = new Date().toISOString();
+  const buildRecord = {
+    schemaVersion: 'explainer-kit.build-record/v1',
+    runId,
+    renderStrategy: normalizedRequest.theme.renderStrategy,
+    startedAt,
+    stages: STAGE_IDS.map((id) => ({
+      id,
+      status: 'pending',
+      outputPaths: [],
+      warnings: [],
+    })),
+    outcome: 'incomplete',
+  };
+  assertValidContract('build-record', buildRecord);
+
+  const run = {
+    runId,
+    slug: paths.slug,
+    outputRoot: paths.outputRoot,
+    runRoot: paths.runRoot,
+    requestPath: join(paths.runRoot, 'run-request.json'),
+    buildRecordPath: join(paths.runRoot, 'build-record.json'),
+    manifestPath: join(paths.runRoot, 'manifest.json'),
+    request: normalizedRequest,
+  };
+
+  await writeJsonAtomic(run.runRoot, 'build-record.json', buildRecord);
+  await writeJsonAtomic(
+    run.runRoot,
+    'run-request.json',
+    privacySafeRequest(normalizedRequest),
+  );
+
+  return run;
+}
+
+export async function updateBuildRecord(run, stage) {
+  assertRun(run);
+  if (!isObject(stage) || !STAGE_IDS.includes(stage.id)) {
+    throw new Error('Stage update must identify a supported stage.');
+  }
+
+  const record = JSON.parse(await readFile(run.buildRecordPath, 'utf8'));
+  if (record.runId !== run.runId) {
+    throw new Error('Build record does not belong to this run.');
+  }
+
+  const stageIndex = STAGE_IDS.indexOf(stage.id);
+  const current = record.stages[stageIndex];
+  const allowed = ALLOWED_TRANSITIONS[current.status];
+  if (!allowed?.has(stage.status)) {
+    throw new Error(
+      `Stage transitions must be monotonic; ${stage.id} is terminal or cannot move from ${current.status} to ${stage.status}.`,
+    );
+  }
+
+  if (
+    current.status === 'pending' &&
+    stageIndex > 0 &&
+    !record.stages
+      .slice(0, stageIndex)
+      .every(({ status }) => SUCCESSFUL_TERMINAL_STATUSES.has(status))
+  ) {
+    throw new Error(
+      `Stage ${stage.id} cannot start before every prior stage completes in order.`,
+    );
+  }
+
+  const timestamp = new Date().toISOString();
+  const next = {
+    ...current,
+    status: stage.status,
+    outputPaths: stage.outputPaths ?? current.outputPaths,
+    warnings: stage.warnings ?? current.warnings,
+  };
+  if (stage.error !== undefined) {
+    next.error = stage.error;
+  }
+  if (stage.status === 'running' && next.startedAt === undefined) {
+    next.startedAt = timestamp;
+  }
+  if (TERMINAL_STATUSES.has(stage.status)) {
+    next.startedAt ??= timestamp;
+    next.completedAt = timestamp;
+  }
+  if (stage.status === 'failed' && !isObject(next.error)) {
+    throw new Error('Failed stages require structured recovery details.');
+  }
+  if (stage.status !== 'failed' && 'error' in next) {
+    throw new Error('Only failed stages may contain an error.');
+  }
+
+  record.stages[stageIndex] = next;
+  if (stage.status === 'failed') {
+    record.outcome = 'failed';
+    record.completedAt = timestamp;
+  } else if (
+    record.stages.every(({ status }) => TERMINAL_STATUSES.has(status))
+  ) {
+    record.outcome = record.stages.some(({ status }) => status === 'failed')
+      ? 'failed'
+      : 'built-not-durable';
+    record.completedAt = timestamp;
+  } else {
+    record.outcome = 'incomplete';
+    delete record.completedAt;
+  }
+
+  assertValidContract('build-record', record);
+  await writeJsonAtomic(run.runRoot, 'build-record.json', record);
+  return record;
+}
+
+export async function writeManifestAtomic(run, manifest) {
+  assertRun(run);
+  if (!isObject(manifest)) {
+    throw new TypeError('Manifest must be an object.');
+  }
+  if (manifest.runId !== run.runId || manifest.slug !== run.slug) {
+    throw new Error('Manifest identity does not match the initialized run.');
+  }
+
+  const buildRecord = JSON.parse(await readFile(run.buildRecordPath, 'utf8'));
+  assertValidContract('manifest', manifest, { buildRecord });
+  await writeJsonAtomic(run.runRoot, 'manifest.json', manifest);
+  return run.manifestPath;
+}
+
+function normalizeRequestSlug(slug) {
+  if (
+    typeof slug !== 'string' ||
+    slug.includes('/') ||
+    slug.includes('\\') ||
+    slug.includes('\0') ||
+    slug === '.' ||
+    slug === '..'
+  ) {
+    throw new Error('Slug cannot contain path traversal or separators.');
+  }
+
+  const normalized = slug
+    .normalize('NFKD')
+    .replaceAll(/\p{Mark}/gu, '')
+    .toLowerCase()
+    .trim()
+    .replaceAll(/[^a-z0-9]+/g, '-')
+    .replaceAll(/^-+|-+$/g, '');
+  if (!normalized) {
+    throw new Error('Slug must contain at least one letter or number.');
+  }
+  return normalized;
+}
+
+function privacySafeRequest(request) {
+  const persisted = structuredClone(request);
+  const retainRaw = persisted.privacy?.retainRawArtDirection === true;
+  if (!retainRaw && isObject(persisted.theme)) {
+    delete persisted.theme.artDirection;
+  }
+  return persisted;
+}
+
+function assertValidContract(kind, value, context) {
+  const result = validateContract(kind, value, context);
+  if (!result.valid) {
+    const details = result.errors
+      .map(({ path, code, message }) => `${path} [${code}]: ${message}`)
+      .join('; ');
+    throw new Error(`Invalid ${kind}: ${details}`);
+  }
+}
+
+function assertRun(run) {
+  if (
+    !isObject(run) ||
+    typeof run.runId !== 'string' ||
+    typeof run.runRoot !== 'string'
+  ) {
+    throw new TypeError('Run must be returned by initializeRun().');
+  }
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}