@open-agent-toolkit/cli 0.2.26 → 0.2.27

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

@@ -34,12 +34,14 @@ const TOKEN_PATTERN = /{{([A-Z][A-Z_]*)}}/g;
 export async function renderArtifact({
   recipeArtifact,
   content,
+  factBase,
   theme,
   renderStrategy,
   publicBaseUrl,
 }) {
   assertRecipeArtifact(recipeArtifact);
   assertContent(content, recipeArtifact);
+  assertFactBase(factBase);
   assertTheme(theme);
   assertRenderStrategy(renderStrategy);
 
@@ -52,6 +54,7 @@ export async function renderArtifact({
   const sections = content.sections.map((section) => ({
     ...section,
     anchor: section.id,
+    backlinks: sourceBacklinksForSection(factBase, section.id),
     ...prepareSectionMarkdown(section.content, theme),
   }));
   const links = content.artifactLinks ?? [];
@@ -109,7 +112,14 @@ export function substituteTemplate(template, values) {
     throw new Error(`Unresolved template token: ${missing[0]}.`);
   }
 
-  const rendered = template.replace(TOKEN_PATTERN, (_, key) => values[key]);
+  const normalizedTemplate = normalizeEmptySubstitutionWhitespace(
+    template,
+    values,
+  );
+  const rendered = normalizedTemplate.replace(
+    TOKEN_PATTERN,
+    (_, key) => values[key],
+  );
   const unresolved = rendered.match(TOKEN_PATTERN)?.[1];
   if (unresolved) {
     throw new Error(`Unresolved template token: ${unresolved}.`);
@@ -117,6 +127,19 @@ export function substituteTemplate(template, values) {
   return rendered;
 }
 
+function normalizeEmptySubstitutionWhitespace(template, values) {
+  let normalized = template;
+  let previous;
+  do {
+    previous = normalized;
+    normalized = normalized.replace(
+      /[ \t]*{{([A-Z][A-Z_]*)}}[ \t]*(?=\r?$)/gm,
+      (match, key) => (values[key] === '' ? '' : match),
+    );
+  } while (normalized !== previous);
+  return normalized;
+}
+
 function templateValues({
   recipeArtifact,
   content,
@@ -193,6 +216,7 @@ function templateValues({
                 `<span>${escapeHtml(section.title ?? humanize(section.id))}</span>`,
             )
             .join(''),
+          renderSourceBacklinks(sections.flatMap(({ backlinks }) => backlinks)),
           renderRelatedLinks(links, content.slug, renderedPath, baseUrl),
         ].join(''),
       };
@@ -217,7 +241,7 @@ function renderSections(sections, { tour = false } = {}) {
       const tourAttributes = tour
         ? ` data-active-nodes="node-${index + 1}" data-active-edges=""`
         : '';
-      return `<section id="${escapeAttribute(section.anchor)}"${tourAttributes}><h2>${escapeHtml(section.title ?? humanize(section.id))}</h2>${renderMarkdownNodes(section.ast.children)}</section>`;
+      return `<section id="${escapeAttribute(section.anchor)}"${tourAttributes}><h2>${escapeHtml(section.title ?? humanize(section.id))}</h2>${renderMarkdownNodes(section.ast.children)}${renderSourceBacklinks(section.backlinks)}</section>`;
     })
     .join('');
 }
@@ -349,7 +373,7 @@ function renderSlides(sections, links, slug, renderedPath, baseUrl) {
   const slides = sections
     .map(
       (section) =>
-        `<section class="slide" id="${escapeAttribute(section.anchor)}"><div class="slide__content"><h2>${escapeHtml(section.title ?? humanize(section.id))}</h2><p>${escapeHtml(section.content)}</p></div></section>`,
+        `<section class="slide" id="${escapeAttribute(section.anchor)}"><div class="slide__content"><h2>${escapeHtml(section.title ?? humanize(section.id))}</h2><p>${escapeHtml(section.content)}</p>${renderSourceBacklinks(section.backlinks)}</div></section>`,
     )
     .join('');
   const related = renderRelatedLinks(links, slug, renderedPath, baseUrl);
@@ -387,6 +411,38 @@ function renderRelatedLinks(links, slug, renderedPath, baseUrl) {
     .join(' ');
 }
 
+function sourceBacklinksForSection(factBase, sectionId) {
+  if (factBase === undefined) return [];
+  return [...factBase.claims, ...factBase.unresolvedClaims]
+    .filter(
+      (claim) =>
+        claim.sections === undefined || claim.sections.includes(sectionId),
+    )
+    .flatMap((claim) =>
+      claim.citations
+        .filter(({ url }) => typeof url === 'string')
+        .map((citation) => ({
+          claimId: claim.id,
+          claimText: claim.text,
+          repository: citation.repository,
+          path: citation.path,
+          lineRange: citation.lineRange,
+          url: citation.url,
+        })),
+    );
+}
+
+function renderSourceBacklinks(backlinks) {
+  if (backlinks.length === 0) return '';
+  const items = backlinks
+    .map(
+      (backlink) =>
+        `<li><span>${escapeHtml(backlink.claimText)}</span> <a href="${escapeAttribute(backlink.url)}">${escapeHtml(`${backlink.repository}/${backlink.path}:L${backlink.lineRange.start}${backlink.lineRange.end === backlink.lineRange.start ? '' : `-L${backlink.lineRange.end}`}`)}</a></li>`,
+    )
+    .join('');
+  return `<aside class="source-backlinks" aria-label="Sources"><h3>Sources</h3><ul>${items}</ul></aside>`;
+}
+
 export function artifactPath(artifact, slug) {
   const directory = TYPE_DIRECTORIES.get(artifact.type);
   if (!directory)
@@ -559,6 +615,14 @@ function assertContent(content, recipeArtifact) {
   }
 }
 
+function assertFactBase(factBase) {
+  if (factBase === undefined) return;
+  const validation = validateContract('fact-base', factBase);
+  if (!validation.valid) {
+    throw new TypeError('Renderer requires a validated fact base.');
+  }
+}
+
 function assertTheme(theme) {
   const validation = validateContract('theme', theme);
   const identity = isObject(theme) ? structuredClone(theme) : {};

package/assets/skills/explainer-kit/scripts/lib/s3-static.mjs

@@ -12,6 +12,12 @@ import { tmpdir } from 'node:os';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
 
+import {
+  catalogFromManifest,
+  initiativeCatalogPath,
+  serializeInitiativeCatalog,
+  validateInitiativeCatalog,
+} from './catalog.mjs';
 import { validateContract } from './contracts.mjs';
 
 const execFile = promisify(execFileCallback);
@@ -131,15 +137,47 @@ export async function publishS3Static(request, dependencies = {}) {
     randomBytes,
   );
   const sentinelTargetPath = targetPath(sentinelRelativePath, roots);
+  const catalog = catalogFromManifest(manifest, roots.publicBaseUrl);
+  const catalogValidation = validateInitiativeCatalog(
+    catalog,
+    manifest,
+    roots.publicBaseUrl,
+  );
+  if (!catalogValidation.valid) {
+    throw publishError(
+      'E_PUBLISH_INPUT',
+      `Invalid initiative catalog: ${catalogValidation.errors[0].message}`,
+    );
+  }
+  const catalogBody = Buffer.from(serializeInitiativeCatalog(catalog));
+  const catalogManifestPath = initiativeCatalogPath(manifest.slug);
+  const catalogPublishPath = catalogManifestPath.slice('site/'.length);
+  if (artifacts.some(({ publishPath }) => publishPath === catalogPublishPath)) {
+    throw publishError(
+      'E_PUBLISH_INPUT',
+      `Generated catalog path collides with a manifest artifact: ${catalogManifestPath}`,
+    );
+  }
   const sentinelDirectory = await mkdtemp(
     join(tmpdir(), 'explainer-sentinel-'),
   );
   const sentinelBodyPath = join(sentinelDirectory, 'sentinel.txt');
+  const catalogBodyPath = join(sentinelDirectory, 'catalog.json');
+  const catalogArtifact = {
+    manifestPath: catalogManifestPath,
+    publishPath: catalogPublishPath,
+    filePath: catalogBodyPath,
+    hash: fileHash(catalogBody),
+    contentType: 'application/json',
+    cacheControl: 'public, max-age=300',
+  };
+  const publicationArtifacts = [...artifacts, catalogArtifact];
   let sentinelUploaded = false;
   let sentinelDeleted = false;
 
   try {
     await writeFile(sentinelBodyPath, SENTINEL_BODY, 'utf8');
+    await writeFile(catalogBodyPath, catalogBody);
     await runAws(
       command,
       putObjectArgs({
@@ -178,7 +216,7 @@ export async function publishS3Static(request, dependencies = {}) {
     sentinelDeleted = true;
 
     const receiptArtifacts = [];
-    for (const artifact of artifacts) {
+    for (const artifact of publicationArtifacts) {
       const target = targetPath(artifact.publishPath, roots);
       const metadata = await readExistingMetadata(
         command,
@@ -251,6 +289,10 @@ export async function publishS3Static(request, dependencies = {}) {
     };
     const receiptValidation = validateContract('publish-receipt', receipt, {
       manifest,
+      catalogArtifact: {
+        relativePath: catalogArtifact.manifestPath,
+        hash: catalogArtifact.hash,
+      },
     });
     if (!receiptValidation.valid) {
       throw publishError(

package/assets/skills/explainer-kit/scripts/lib/set-plan.mjs

@@ -0,0 +1,208 @@
+import { canonicalHash, validateContract } from './contracts.mjs';
+import { recipeExpansion, recipeFloor } from './recipes.mjs';
+
+export async function planExplainerSet({
+  recipe,
+  factBase,
+  discovery,
+  planSet,
+}) {
+  const sourceIds = factBase.sources
+    .map(({ id }) => id)
+    .filter((id) => !id.startsWith('critic:'));
+  const request = deepFreeze({
+    schemaVersion: 'explainer-kit.set-plan-request/v1',
+    recipe: structuredClone(recipe),
+    factBase: structuredClone(factBase),
+    discovery: structuredClone(discovery),
+  });
+  const callback =
+    typeof planSet === 'function' ? planSet : createBaselineSetPlan;
+  const candidate = await callback(structuredClone(request));
+  const validation = validateContract('set-plan', candidate);
+  if (!validation.valid) {
+    throw setPlanError(
+      validation.errors
+        .map(({ path, code, message }) => `${path} [${code}]: ${message}`)
+        .join('; '),
+    );
+  }
+  validateAgainstInputs(candidate, { recipe, sourceIds });
+
+  const plan = deepFreeze(structuredClone(candidate));
+  const retainedRequest = deepFreeze({
+    schemaVersion: request.schemaVersion,
+    recipe: { id: recipe.id, version: recipe.version },
+    factBaseHash: canonicalHash(factBase),
+    sourceIds,
+    discovery: structuredClone(discovery),
+  });
+  return { request: retainedRequest, plan };
+}
+
+export function plannedArtifacts(recipe, plan) {
+  const floor = new Map(
+    recipeFloor(recipe).map((artifact) => [artifact.id, artifact]),
+  );
+  const profiles = new Map(
+    recipeExpansion(recipe).profiles.map((profile) => [
+      profile.profileId,
+      profile,
+    ]),
+  );
+  return plan.portfolio.map((planned) => {
+    const floorArtifact = floor.get(planned.artifactId);
+    if (floorArtifact) {
+      return {
+        ...floorArtifact,
+        origin: 'floor',
+        shell:
+          floorArtifact.authoring === 'html'
+            ? floorArtifact.template
+            : undefined,
+        plannedArtifact: planned,
+      };
+    }
+    const profile = profiles.get(planned.profileId);
+    return {
+      id: planned.artifactId,
+      type: profile.type,
+      authoring: profile.authoring,
+      briefRef: profile.briefRef,
+      shell: profile.shell,
+      template:
+        profile.authoring === 'markdown'
+          ? templateForType(profile.type)
+          : profile.shell,
+      required: false,
+      origin: 'expansion',
+      profileId: profile.profileId,
+      plannedArtifact: planned,
+    };
+  });
+}
+
+function createBaselineSetPlan({ recipe, factBase }) {
+  const sourceIds = factBase.sources
+    .map(({ id }) => id)
+    .filter((id) => !id.startsWith('critic:'));
+  return {
+    schemaVersion: 'explainer-kit.set-plan/v1',
+    planId: `${recipe.id}-set`,
+    recipe: { id: recipe.id, version: recipe.version },
+    sourceIds,
+    ledger: { terminology: [], statuses: [], numbers: [] },
+    portfolio: recipeFloor(recipe).map((artifact) => ({
+      artifactId: artifact.id,
+      artifactType: artifact.type,
+      profileId: 'recipe-floor',
+      required: true,
+      sourceIds,
+      draft: `Compose ${artifact.id} from the reconciled fact base.`,
+      visualIntent: 'Follow the bundled brief and selected medium.',
+    })),
+  };
+}
+
+function validateAgainstInputs(plan, { recipe, sourceIds }) {
+  if (plan.recipe.id !== recipe.id || plan.recipe.version !== recipe.version) {
+    throw setPlanError('Set plan recipe does not match the active recipe.');
+  }
+  const availableSources = new Set(sourceIds);
+  for (const sourceId of plan.sourceIds) {
+    if (!availableSources.has(sourceId)) {
+      throw setPlanError(
+        `Set plan references unknown reconciled source ${sourceId}.`,
+      );
+    }
+  }
+  const plannedSources = new Set(plan.sourceIds);
+  const omittedSources = sourceIds.filter(
+    (sourceId) => !plannedSources.has(sourceId),
+  );
+  if (
+    omittedSources.length > 0 ||
+    plannedSources.size !== availableSources.size
+  ) {
+    throw setPlanError(
+      `Set plan must declare every reconciled non-critic source; omitted ${omittedSources.join(', ') || 'none'}.`,
+    );
+  }
+  const coveredSources = new Set(
+    plan.portfolio.flatMap(({ sourceIds: artifactSourceIds }) =>
+      Array.isArray(artifactSourceIds) ? artifactSourceIds : [],
+    ),
+  );
+  const uncoveredSources = plan.sourceIds.filter(
+    (sourceId) => !coveredSources.has(sourceId),
+  );
+  if (uncoveredSources.length > 0) {
+    throw setPlanError(
+      `Every declared source must cover at least one portfolio artifact; uncovered ${uncoveredSources.join(', ')}.`,
+    );
+  }
+
+  const plannedById = new Map(
+    plan.portfolio.map((artifact) => [artifact.artifactId, artifact]),
+  );
+  for (const floorArtifact of recipeFloor(recipe)) {
+    const planned = plannedById.get(floorArtifact.id);
+    if (
+      !planned ||
+      planned.required !== true ||
+      planned.artifactType !== floorArtifact.type
+    ) {
+      throw setPlanError(
+        `Set plan is missing required draft ${floorArtifact.id}.`,
+      );
+    }
+  }
+
+  const floorIds = new Set(recipeFloor(recipe).map(({ id }) => id));
+  const profiles = new Map(
+    recipeExpansion(recipe).profiles.map((profile) => [
+      profile.profileId,
+      profile,
+    ]),
+  );
+  for (const artifact of plan.portfolio) {
+    if (floorIds.has(artifact.artifactId)) continue;
+    const profile = profiles.get(artifact.profileId);
+    if (
+      !profile ||
+      artifact.required !== false ||
+      artifact.artifactType !== profile.type
+    ) {
+      throw setPlanError(
+        `Optional artifact ${artifact.artifactId} does not match an allowed recipe profile.`,
+      );
+    }
+  }
+}
+
+function templateForType(type) {
+  return (
+    {
+      hub: 'house-style',
+      diagram: 'diagram-shell',
+      explainer: 'engineer-tour',
+      deck: 'deck-shell',
+    }[type] ?? 'house-style'
+  );
+}
+
+function deepFreeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) {
+      deepFreeze(child);
+    }
+  }
+  return value;
+}
+
+function setPlanError(message) {
+  const error = new Error(`Invalid set plan: ${message}`);
+  error.code = 'E_SET_PLAN';
+  return error;
+}

package/assets/skills/explainer-kit/scripts/lib/source-backlinks.mjs

@@ -0,0 +1,218 @@
+export const SOURCE_BACKLINK_CONTRACT_VERSION =
+  'explainer-kit.source-backlinks/v1';
+
+const REPOSITORY_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const REVISION_PATTERN = /^[a-f0-9]{40}$/;
+const LINE_FRAGMENT_PATTERN = /^L([1-9][0-9]*)(?:-L([1-9][0-9]*))?$/;
+
+export function canonicalGithubBlobBacklink(tuple) {
+  const normalized = normalizeBacklinkTuple(tuple);
+  const encodedPath = normalized.path
+    .split('/')
+    .map((segment) => encodeURIComponent(segment))
+    .join('/');
+  const fragment =
+    normalized.lineRange.start === normalized.lineRange.end
+      ? `L${normalized.lineRange.start}`
+      : `L${normalized.lineRange.start}-L${normalized.lineRange.end}`;
+  return `https://github.com/${normalized.repository}/blob/${normalized.revision}/${encodedPath}#${fragment}`;
+}
+
+export function validateCanonicalGithubBlobTuple(tuple) {
+  try {
+    const normalized = normalizeBacklinkTuple(tuple);
+    if (
+      typeof tuple?.url !== 'string' ||
+      tuple.url !== canonicalGithubBlobBacklink(normalized)
+    ) {
+      return false;
+    }
+    return sameTuple(parseCanonicalGithubBlobUrl(tuple.url), {
+      ...normalized,
+      url: tuple.url,
+    });
+  } catch {
+    return false;
+  }
+}
+
+export function parseCanonicalGithubBlobUrl(value) {
+  if (typeof value !== 'string') {
+    throw backlinkError('GitHub backlink URL must be a string.');
+  }
+  if (
+    !value.startsWith('https://github.com/') ||
+    value.includes('?') ||
+    value.includes('\\')
+  ) {
+    throw backlinkError(
+      'GitHub backlink must use canonical credential-free HTTPS without query.',
+    );
+  }
+  const hashIndex = value.indexOf('#');
+  if (hashIndex < 0 || value.indexOf('#', hashIndex + 1) >= 0) {
+    throw backlinkError(
+      'GitHub backlink requires one canonical line fragment.',
+    );
+  }
+  const rawPath = value.slice('https://github.com/'.length, hashIndex);
+  const fragment = value.slice(hashIndex + 1);
+  const rawSegments = rawPath.split('/');
+  if (
+    rawSegments.length < 5 ||
+    rawSegments.some((segment) => segment.length === 0)
+  ) {
+    throw backlinkError('GitHub backlink path contains an empty segment.');
+  }
+  const [owner, repositoryName, blob, revision, ...rawFileSegments] =
+    rawSegments;
+  if (
+    blob !== 'blob' ||
+    !REPOSITORY_PATTERN.test(`${owner}/${repositoryName}`) ||
+    !REVISION_PATTERN.test(revision)
+  ) {
+    throw backlinkError(
+      'GitHub backlink requires a canonical repository and full commit SHA.',
+    );
+  }
+  const fileSegments = rawFileSegments.map(decodeCanonicalSegment);
+  const lineMatch = fragment.match(LINE_FRAGMENT_PATTERN);
+  if (!lineMatch) {
+    throw backlinkError('GitHub backlink requires a canonical line range.');
+  }
+  const start = Number(lineMatch[1]);
+  const end = Number(lineMatch[2] ?? lineMatch[1]);
+  if (end < start) {
+    throw backlinkError('GitHub backlink line range is reversed.');
+  }
+  const tuple = {
+    repository: `${owner}/${repositoryName}`,
+    revision,
+    path: fileSegments.join('/'),
+    lineRange: { start, end },
+  };
+  const canonical = canonicalGithubBlobBacklink(tuple);
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw backlinkError('GitHub backlink URL is malformed.');
+  }
+  if (
+    parsed.protocol !== 'https:' ||
+    parsed.hostname !== 'github.com' ||
+    parsed.port ||
+    parsed.username ||
+    parsed.password ||
+    parsed.search ||
+    parsed.href !== canonical ||
+    value !== canonical
+  ) {
+    throw backlinkError('GitHub backlink URL is not canonical.');
+  }
+  return { ...tuple, url: canonical };
+}
+
+function normalizeBacklinkTuple(tuple) {
+  if (
+    !tuple ||
+    typeof tuple !== 'object' ||
+    !REPOSITORY_PATTERN.test(tuple.repository ?? '') ||
+    !REVISION_PATTERN.test(tuple.revision ?? '')
+  ) {
+    throw backlinkError(
+      'GitHub backlink tuple requires a canonical repository and full commit SHA.',
+    );
+  }
+  const path = normalizeRepositoryPath(tuple.path);
+  const lineRange = normalizeLineRange(tuple.lineRange);
+  return {
+    repository: tuple.repository,
+    revision: tuple.revision,
+    path,
+    lineRange,
+  };
+}
+
+function normalizeRepositoryPath(value) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.startsWith('/') ||
+    value.includes('\\')
+  ) {
+    throw backlinkError(
+      'GitHub backlink tuple requires a repository-relative path.',
+    );
+  }
+  const segments = value.split('/');
+  if (
+    segments.some(
+      (segment) =>
+        segment.length === 0 ||
+        segment === '.' ||
+        segment === '..' ||
+        segment.includes('/') ||
+        segment.includes('\\') ||
+        segment.includes('\0'),
+    )
+  ) {
+    throw backlinkError('GitHub backlink path contains an unsafe segment.');
+  }
+  return segments.join('/');
+}
+
+function normalizeLineRange(value) {
+  if (
+    !value ||
+    !Number.isInteger(value.start) ||
+    !Number.isInteger(value.end) ||
+    value.start < 1 ||
+    value.end < value.start
+  ) {
+    throw backlinkError(
+      'GitHub backlink tuple requires a valid inclusive line range.',
+    );
+  }
+  return { start: value.start, end: value.end };
+}
+
+function decodeCanonicalSegment(rawSegment) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(rawSegment);
+  } catch {
+    throw backlinkError('GitHub backlink path has malformed encoding.');
+  }
+  if (
+    decoded.length === 0 ||
+    decoded === '.' ||
+    decoded === '..' ||
+    decoded.includes('/') ||
+    decoded.includes('\\') ||
+    decoded.includes('\0') ||
+    encodeURIComponent(decoded) !== rawSegment
+  ) {
+    throw backlinkError(
+      'GitHub backlink path has an unsafe or noncanonical encoded segment.',
+    );
+  }
+  return decoded;
+}
+
+function sameTuple(left, right) {
+  return (
+    left.repository === right.repository &&
+    left.revision === right.revision &&
+    left.path === right.path &&
+    left.lineRange.start === right.lineRange.start &&
+    left.lineRange.end === right.lineRange.end &&
+    left.url === right.url
+  );
+}
+
+function backlinkError(message) {
+  const error = new TypeError(message);
+  error.code = 'E_SOURCE_BACKLINK';
+  return error;
+}