Review: ci: render catalog previews on PR

Solid foundation — the script follows the established generate-template-previews.ts patterns well, and the workflow structure is clean. However, the CI run already exposed two real bugs, plus there are a few things worth tightening up before this lands.

Critical (must fix)

1. grep -P lookbehind fails on Ubuntu runner

The CI logs show:

grep: lookbehind assertion is not fixed length

This is the line:

grep -oP '(?<=registry/(blocks|components)/)[^/]+'

grep -P with a variable-length lookbehind ((blocks|components) has alternation of different lengths) is not supported by PCRE on the Ubuntu runner's grep. This silently fails, meaning no items are ever detected as changed.

Fix — use sed or awk instead:

sed -n 's|^registry/\(blocks\|components\)/\([^/]*\)/.*|\2|p' | sort -u

Or restructure as two greps:

grep -E '^registry/(blocks|components)/' | sed 's|^registry/[^/]*/\([^/]*\)/.*|\1|' | sort -u

2. origin/main ref does not exist — shallow checkout

The CI logs also show:

fatal: bad revision 'origin/main...HEAD'

actions/checkout@v4 performs a shallow clone of the PR merge ref by default. origin/main is not fetched. The workflow needs to either:

(a) Add fetch-depth: 0 to checkout (fetches full history — heavier), or
(b) Use ${{ github.event.pull_request.base.sha }} instead of origin/main:

git diff --name-only ${{ github.event.pull_request.base.sha }}...HEAD -- registry/blocks/ registry/components/

Option (b) is more precise since it diffs against the actual PR base, not main (the PR's base branch is 04-14-feat_registry_seed_components_..., not main). But it still requires fetching the base SHA. Consider:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

Or fetch just the base:

- uses: actions/checkout@v4
- run: git fetch origin ${{ github.event.pull_request.base.sha }} --depth=1

Both bugs together mean the workflow currently never renders anything — it always falls through to "No block/component changes detected." The CI passed only because the step has continue-on-error: true and the upload step uses if-no-files-found: ignore.

Important (should fix)

3. continue-on-error: true masks all failures

The render step has continue-on-error: true, which means even if the grep/git bugs above were fixed and rendering genuinely fails, the job still reports green. This defeats the purpose of CI feedback.

The script already has per-item try/catch with ::warning:: annotations. Remove continue-on-error: true from the step and let the exit code propagate. If the intent is "don't block merge on preview failures," make the job non-required in branch protection instead.

4. Script hardcodes origin/main as diff base in the workflow

Even after fixing the checkout issue, diffing against origin/main is wrong when the PR targets a feature branch (like this one targets 04-14-feat_registry_seed_components_...). Use the PR base ref:

git diff --name-only $GITHUB_BASE_REF...HEAD -- registry/blocks/ registry/components/

or use the base SHA from the event payload.

5. The --type example CLI flag is accepted but has no effect

The PR description and doc comment say the script supports --type example, but the ItemKind type is "block" | "component" and the discovery function only scans blocks/ and components/. Passing --type example would silently return zero items (since "example" fails the kindFilter !== kind check for both block and component).

Either:

• Remove mentions of "example" from the doc comment and PR description, or
• Add a proper error message for invalid --type values (currently only "block" and "component" are validated in parseArgs, so "example" would hit the error — actually wait, I re-read: parseArgs does validate and process.exit(1) on invalid type. Good. But the doc comment at the top still says "Examples: renders index.html" which is misleading since examples aren't handled by this script.)

Update the doc comment to remove the "Examples" bullet point and clarify this script handles blocks and components only.

Suggestions (nice to have)

6. Pin Chrome and FFmpeg versions

browser-actions/setup-chrome@v1 with chrome-version: stable and FedericoCarboni/setup-ffmpeg@v3 without a version pin mean the rendering environment can change between runs. For reproducible previews, consider pinning to a specific Chrome version or at least latest-stable with a comment.

7. Consider per-item timeout

A single broken HTML file with an infinite animation loop could hang the entire 30-minute job. The producer APIs might handle this, but worth confirming there's a render timeout at the producer level. If not, wrapping each item render in a timeout command in the shell loop would add resilience:

if ! timeout 120 npx tsx scripts/generate-catalog-previews.ts --only "$item" --skip-video; then

8. Temp directory cleanup on script crash

If the script crashes between prepareProjectDir and the finally block (e.g., during createFileServer), the temp dir leaks. Not a big deal in CI (ephemeral runners), but for local use the /tmp/hf-catalog-* dirs accumulate. The existing template preview script has the same pattern, so this is consistent — just noting it.

9. Registry-item.json files field access is unvalidated

const compFile = manifest.files?.find(
  (f: { type: string }) => f.type === "hyperframes:composition",
);
entryFile = compFile?.path ?? `${e.name}.html`;

If manifest.files exists but contains entries without a path property, compFile?.path is undefined and falls back correctly. But manifest.files could also be a non-array (malformed JSON). A quick Array.isArray(manifest.files) guard would be more defensive.

Summary

The two critical bugs (grep PCRE failure + missing git ref) mean the workflow currently does nothing on any PR. These need to be fixed and verified with a re-run before merging. The continue-on-error: true masked both failures, which is why CI shows green despite zero items rendered.

The script itself is well-structured, follows the existing template preview patterns, and the producer API usage looks correct.

One additional finding — the entryFile discovery/usage gap means the preview script likely navigates to a directory listing instead of the composition.

CI issues are addressed in #270. Approving.