@open-agent-toolkit/cli 0.2.20 → 0.2.21

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

@@ -2,6 +2,8 @@ import { readFile } from 'node:fs/promises';
 import { posix } from 'node:path';
 
 import { canonicalHash, validateContract } from './contracts.mjs';
+import { renderDiagram as renderDiagramBlock } from './diagram.mjs';
+import { MarkdownSafetyError, parseMarkdownDocument } from './markdown.mjs';
 
 const RENDER_STRATEGIES = new Set(['default-only', 'user-switchable']);
 const TEMPLATE_BY_TYPE = new Map([
@@ -50,6 +52,7 @@ export async function renderArtifact({
   const sections = content.sections.map((section) => ({
     ...section,
     anchor: section.id,
+    ...prepareSectionMarkdown(section.content, theme),
   }));
   const links = content.artifactLinks ?? [];
   const values = templateValues({
@@ -82,6 +85,7 @@ export async function renderArtifact({
       : undefined,
     mediaType: 'text/html',
     html,
+    warnings: sections.flatMap((section) => section.warnings),
   };
 }
 
@@ -164,7 +168,7 @@ function templateValues({
           baseUrl,
         ),
         CONTENT: renderSections(sections, { tour: true }),
-        DIAGRAM: renderDiagram(sections),
+        DIAGRAM: renderLegacyDiagram(sections),
         FOOTER: footer,
       };
     case 'deck-shell':
@@ -181,7 +185,7 @@ function templateValues({
     case 'diagram-shell':
       return {
         ...common,
-        DIAGRAM: renderDiagram(sections),
+        DIAGRAM: renderLegacyDiagram(sections),
         LEGEND: [
           sections
             .map(
@@ -213,11 +217,134 @@ function renderSections(sections, { tour = false } = {}) {
       const tourAttributes = tour
         ? ` data-active-nodes="node-${index + 1}" data-active-edges=""`
         : '';
-      return `<section id="${escapeAttribute(section.anchor)}"${tourAttributes}><div class="section-number">${index + 1}</div><h2>${escapeHtml(section.title ?? humanize(section.id))}</h2><p>${escapeHtml(section.content)}</p></section>`;
+      return `<section id="${escapeAttribute(section.anchor)}"${tourAttributes}><h2>${escapeHtml(section.title ?? humanize(section.id))}</h2>${renderMarkdownNodes(section.ast.children)}</section>`;
     })
     .join('');
 }
 
+function prepareSectionMarkdown(content, theme) {
+  try {
+    const parsed = parseMarkdownDocument(content);
+    const diagramWarnings = [];
+    visitMarkdownNodes(parsed.ast.children, (node) => {
+      if (node.type !== 'diagram') return;
+      const rendered = renderDiagramBlock(node.source, { theme });
+      node.renderedHtml = rendered.html;
+      diagramWarnings.push(...rendered.warnings);
+    });
+    return {
+      ...parsed,
+      warnings: [...parsed.warnings, ...diagramWarnings],
+    };
+  } catch (error) {
+    if (
+      !(error instanceof MarkdownSafetyError) ||
+      !/raw html|node type: html/i.test(error.message)
+    ) {
+      throw error;
+    }
+    return {
+      ast: {
+        type: 'document',
+        children: [
+          {
+            type: 'paragraph',
+            children: [{ type: 'text', value: content }],
+          },
+        ],
+      },
+      warnings: [
+        {
+          code: 'legacy-raw-html-escaped',
+          message: 'Legacy section markup was rendered as escaped text.',
+        },
+      ],
+    };
+  }
+}
+
+function visitMarkdownNodes(nodes, callback) {
+  for (const node of nodes) {
+    callback(node);
+    if (Array.isArray(node.children)) {
+      visitMarkdownNodes(node.children, callback);
+    }
+  }
+}
+
+function renderMarkdownNodes(nodes) {
+  return nodes.map(renderMarkdownNode).join('');
+}
+
+function renderMarkdownNode(node) {
+  switch (node.type) {
+    case 'text':
+      return escapeHtml(node.value);
+    case 'paragraph':
+      if (node.children.length === 1 && node.children[0].type === 'figure') {
+        return renderMarkdownNode(node.children[0]);
+      }
+      return `<p>${renderMarkdownNodes(node.children)}</p>`;
+    case 'heading':
+      return `<h${node.depth}>${renderMarkdownNodes(node.children)}</h${node.depth}>`;
+    case 'strong':
+      return `<strong>${renderMarkdownNodes(node.children)}</strong>`;
+    case 'emphasis':
+      return `<em>${renderMarkdownNodes(node.children)}</em>`;
+    case 'delete':
+      return `<del>${renderMarkdownNodes(node.children)}</del>`;
+    case 'inlineCode':
+      return `<code>${escapeHtml(node.value)}</code>`;
+    case 'link':
+      return `<a href="${escapeAttribute(node.url)}"${node.title ? ` title="${escapeAttribute(node.title)}"` : ''}>${renderMarkdownNodes(node.children)}</a>`;
+    case 'figure':
+      return `<figure><a href="${escapeAttribute(node.url)}">${escapeHtml(node.alt || 'View figure')}</a>${node.title || node.alt ? `<figcaption>${escapeHtml(node.title ?? node.alt)}</figcaption>` : ''}</figure>`;
+    case 'blockquote':
+      return `<blockquote>${renderMarkdownNodes(node.children)}</blockquote>`;
+    case 'callout':
+      return `<aside class="callout callout--${escapeAttribute(node.kind)}" data-callout="${escapeAttribute(node.kind)}"><div class="callout__label">${escapeHtml(humanize(node.kind))}</div>${renderMarkdownNodes(node.children)}</aside>`;
+    case 'timeline':
+      return `<ol class="timeline">${node.entries
+        .map(
+          (entry) =>
+            `<li><time>${escapeHtml(entry.date)}</time><span>${escapeHtml(entry.label)}</span></li>`,
+        )
+        .join('')}</ol>`;
+    case 'code':
+      return `<pre><code${node.language ? ` class="language-${escapeAttribute(node.language)}"` : ''}>${escapeHtml(node.value)}</code></pre>`;
+    case 'diagram':
+      return `<div class="diagram-scroll">${node.renderedHtml}</div>`;
+    case 'list':
+      return renderMarkdownList(node);
+    case 'listItem':
+      return `<li>${node.checked === null ? '' : `<input type="checkbox" disabled${node.checked ? ' checked' : ''} aria-label="${node.checked ? 'Completed' : 'Incomplete'} task" />`}${renderMarkdownNodes(node.children)}</li>`;
+    case 'table':
+      return `<div class="table-scroll"><table><thead><tr>${node.header
+        .map((cell) => `<th>${renderMarkdownNodes(cell)}</th>`)
+        .join('')}</tr></thead><tbody>${node.rows
+        .map(
+          (row) =>
+            `<tr>${row
+              .map((cell) => `<td>${renderMarkdownNodes(cell)}</td>`)
+              .join('')}</tr>`,
+        )
+        .join('')}</tbody></table></div>`;
+    default:
+      throw new MarkdownSafetyError(
+        `Unsupported markdown render node: ${String(node.type)}.`,
+      );
+  }
+}
+
+function renderMarkdownList(node) {
+  const tag = node.ordered ? 'ol' : 'ul';
+  const attributes = [
+    node.task ? ' class="task-list"' : '',
+    node.ordered && node.start !== 1 ? ` start="${node.start}"` : '',
+  ].join('');
+  return `<${tag}${attributes}>${renderMarkdownNodes(node.children)}</${tag}>`;
+}
+
 function renderSlides(sections, links, slug, renderedPath, baseUrl) {
   const slides = sections
     .map(
@@ -231,11 +358,18 @@ function renderSlides(sections, links, slug, renderedPath, baseUrl) {
     : slides;
 }
 
-function renderDiagram(sections) {
+// Nodes must fit the shell's 360x540 viewBox, so the step shrinks as sections
+// are added rather than overflowing the canvas.
+function renderLegacyDiagram(sections) {
+  const margin = 16;
+  const span = 540 - margin * 2;
+  const step = Math.min(96, span / Math.max(sections.length, 1));
+  const height = Math.max(24, step - 16);
   return sections
     .map((section, index) => {
-      const y = 80 + index * 120;
-      return `<g data-node="node-${index + 1}" class="node"><rect x="80" y="${y}" width="360" height="72" rx="8"></rect><text x="104" y="${y + 43}">${escapeHtml(section.title ?? humanize(section.id))}</text></g>`;
+      const y = margin + index * step;
+      const label = section.title ?? humanize(section.id);
+      return `<g data-node="node-${index + 1}" class="node"><rect x="${margin}" y="${y}" width="${360 - margin * 2}" height="${height}" rx="8"></rect><text x="${margin + 14}" y="${y + height / 2 + 5}">${escapeHtml(label)}</text></g>`;
     })
     .join('');
 }
@@ -253,12 +387,18 @@ function renderRelatedLinks(links, slug, renderedPath, baseUrl) {
     .join(' ');
 }
 
-function artifactPath(artifact, slug) {
+export function artifactPath(artifact, slug) {
   const directory = TYPE_DIRECTORIES.get(artifact.type);
   if (!directory)
     throw new Error(`Unsupported artifact type: ${artifact.type}.`);
   const parts = ['site', directory, slug];
-  if (['diagram', 'deck'].includes(artifact.type)) parts.push(artifact.id);
+  const origin = artifact.origin ?? 'floor';
+  if (
+    origin === 'expansion' ||
+    (origin === 'floor' && ['diagram', 'deck'].includes(artifact.type))
+  ) {
+    parts.push(artifact.id);
+  }
   parts.push('index.html');
   return parts.join('/');
 }
@@ -337,11 +477,19 @@ function switchableThemeControl(theme) {
 }
 
 function assertRecipeArtifact(artifact) {
+  const hasLegacyKeys =
+    isObject(artifact) &&
+    hasExactKeys(artifact, ['id', 'type', 'template', 'required']);
+  const hasOriginKeys =
+    isObject(artifact) &&
+    hasExactKeys(artifact, ['id', 'type', 'template', 'required', 'origin']);
   if (
     !isObject(artifact) ||
-    !hasExactKeys(artifact, ['id', 'type', 'template', 'required']) ||
+    (!hasLegacyKeys && !hasOriginKeys) ||
     !SLUG_PATTERN.test(artifact.id ?? '') ||
-    typeof artifact.required !== 'boolean'
+    typeof artifact.required !== 'boolean' ||
+    (artifact.origin !== undefined &&
+      !['floor', 'expansion'].includes(artifact.origin))
   ) {
     throw new TypeError(
       'Recipe artifact is not a validated artifact descriptor.',
@@ -391,12 +539,18 @@ function assertContent(content, recipeArtifact) {
     throw new TypeError('Artifact links must be an array.');
   }
   for (const link of links) {
+    const hasLegacyKeys =
+      isObject(link) && hasExactKeys(link, ['id', 'type', 'label']);
+    const hasOriginKeys =
+      isObject(link) && hasExactKeys(link, ['id', 'type', 'label', 'origin']);
     if (
       !isObject(link) ||
-      !hasExactKeys(link, ['id', 'type', 'label']) ||
+      (!hasLegacyKeys && !hasOriginKeys) ||
       !SLUG_PATTERN.test(link.id ?? '') ||
       !TYPE_DIRECTORIES.has(link.type) ||
-      typeof link.label !== 'string'
+      typeof link.label !== 'string' ||
+      (link.origin !== undefined &&
+        !['floor', 'expansion'].includes(link.origin))
     ) {
       throw new TypeError(
         'Artifact cross-links must use typed artifact targets.',

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

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
 
 import { readFile } from 'node:fs/promises';
-import { basename } from 'node:path';
+import { createServer } from 'node:http';
+import { basename, posix, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
-import { auditArtifactSet } from './lib/qa.mjs';
+import {
+  RENDER_QA_WARNING_IDS,
+  auditArtifactSet,
+  renderQaWarningIds,
+  runBrowserProbes,
+} from './lib/qa.mjs';
 import { renderArtifact } from './lib/render.mjs';
 import { resolveTheme } from './lib/theme.mjs';
 
@@ -49,6 +55,62 @@ export const RELEASE_ARTIFACTS = Object.freeze([
   }),
 ]);
 
+export async function runRenderQaStage({
+  siteDir,
+  artifacts,
+  browserProbe,
+  widths,
+} = {}) {
+  assertStageInput(siteDir, artifacts);
+  // Render QA is opt-in: the stage drives a probe the caller supplies and never
+  // launches a runtime of its own.
+  if (typeof browserProbe !== 'function') {
+    return {
+      valid: true,
+      skipped: true,
+      warnings: [RENDER_QA_WARNING_IDS.skippedNoProbe],
+      issues: [],
+      probes: 0,
+    };
+  }
+
+  return probeSiteArtifacts({ siteDir, artifacts, probe: browserProbe, widths });
+}
+
+async function probeSiteArtifacts({ siteDir, artifacts, probe, widths }) {
+  return withSiteServer(siteDir, async (origin) => {
+    const probeArtifacts = await Promise.all(
+      artifacts.map(async (artifact) => {
+        const relativePath = siteRelativePath(artifact.renderedPath);
+        return {
+          id: artifact.id,
+          type: artifact.type,
+          html: await readFile(
+            resolve(siteDir, ...relativePath.split('/')),
+            'utf8',
+          ),
+          url: `${origin}/${relativePath
+            .split('/')
+            .map(encodeURIComponent)
+            .join('/')}`,
+        };
+      }),
+    );
+    const browser = await runBrowserProbes({
+      artifacts: probeArtifacts,
+      probe,
+      ...(widths && { widths }),
+    });
+    return {
+      valid: true,
+      skipped: false,
+      warnings: renderQaWarningIds(browser.issues),
+      issues: browser.issues,
+      probes: browser.probes,
+    };
+  });
+}
+
 export function selectReleaseVisualMatrix() {
   const paletteModeCases = RELEASE_PALETTES.flatMap((palette, paletteIndex) =>
     RELEASE_MODES.map((mode, modeIndex) => ({
@@ -265,6 +327,89 @@ function releaseContent(artifactId) {
   };
 }
 
+function assertStageInput(siteDir, artifacts) {
+  if (typeof siteDir !== 'string' || siteDir.length === 0) {
+    throw new TypeError('Render QA stage requires a built site directory.');
+  }
+  if (
+    !Array.isArray(artifacts) ||
+    artifacts.length === 0 ||
+    artifacts.some(
+      (artifact) =>
+        typeof artifact?.id !== 'string' ||
+        typeof artifact?.type !== 'string' ||
+        typeof artifact?.renderedPath !== 'string',
+    )
+  ) {
+    throw new TypeError(
+      'Render QA stage requires artifacts with id, type, and renderedPath.',
+    );
+  }
+  for (const artifact of artifacts) siteRelativePath(artifact.renderedPath);
+}
+
+function siteRelativePath(renderedPath) {
+  const withoutPrefix = renderedPath.startsWith('site/')
+    ? renderedPath.slice('site/'.length)
+    : renderedPath;
+  const normalized = posix.normalize(withoutPrefix);
+  if (
+    normalized === '.' ||
+    normalized.startsWith('../') ||
+    posix.isAbsolute(normalized)
+  ) {
+    throw new TypeError(`Unsafe render QA artifact path: ${renderedPath}`);
+  }
+  return normalized;
+}
+
+async function withSiteServer(siteDir, callback) {
+  const root = resolve(siteDir);
+  const server = createServer(async (request, response) => {
+    try {
+      const pathname = decodeURIComponent(
+        new URL(request.url ?? '/', 'http://127.0.0.1').pathname,
+      );
+      const candidate = resolve(root, `.${pathname}`);
+      if (candidate !== root && !candidate.startsWith(`${root}${sep}`)) {
+        response.writeHead(403).end();
+        return;
+      }
+      const body = await readFile(candidate);
+      response.writeHead(200, {
+        'content-type': candidate.endsWith('.html')
+          ? 'text/html; charset=utf-8'
+          : 'application/octet-stream',
+        'cache-control': 'no-store',
+      });
+      response.end(body);
+    } catch {
+      response.writeHead(404).end();
+    }
+  });
+  await new Promise((resolveListen, rejectListen) => {
+    server.once('error', rejectListen);
+    server.listen(0, '127.0.0.1', resolveListen);
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    await closeServer(server);
+    throw new Error('Render QA server did not expose a TCP address.');
+  }
+
+  try {
+    return await callback(`http://127.0.0.1:${address.port}`);
+  } finally {
+    await closeServer(server);
+  }
+}
+
+function closeServer(server) {
+  return new Promise((resolveClose, rejectClose) => {
+    server.close((error) => (error ? rejectClose(error) : resolveClose()));
+  });
+}
+
 if (
   process.argv[1] &&
   pathToFileURL(process.argv[1]).href === import.meta.url