l-generator-cli-tester

name: l-generator-cli-tester description: Test a single create-zudo-doc CLI generation pattern. Scaffolds a project, builds it, starts dev server, and verifies expected features. Use when testing generator output for a specific pattern.

Generator CLI Pattern Tester

Test a single create-zudo-doc CLI generation pattern by scaffolding a project, building it, running the dev server briefly, and verifying the expected files and settings.

Usage

/l-generator-cli-tester <pattern>
/l-generator-cli-tester <pattern> --headless

Where <pattern> is one of the test patterns listed below.

Options

• --headless — After standard checks, also run headless browser verification using /headless-browser to confirm pages actually render (Step 8.5). Without this flag, headless checks are skipped.

Test Patterns

Step 0: Build the CLI

Before running any test, set REPO_ROOT and build the CLI:

REPO_ROOT=$(git rev-parse --show-toplevel)
cd packages/create-zudo-doc && pnpm build

If the build fails, stop and report the error.

Step 1: Create Temp Directory

mkdir -p __inbox/generator-test-<pattern>

Step 2: Run the Generator

Set REPO_ROOT to the repository root (absolute path). Run the generator from within the temp directory. Always use --no-install to handle installation separately.

CLI Commands per Pattern

barebone:

cd __inbox/generator-test-barebone && \
  node $REPO_ROOT/packages/create-zudo-doc/dist/index.js test-project --yes \
  --no-search --no-sidebar-filter --no-i18n --no-claude-resources \
  --no-image-enlarge --no-tag-governance \
  --color-scheme-mode single --scheme "Default Dark" --no-install

search:

cd __inbox/generator-test-search && \
  node $REPO_ROOT/packages/create-zudo-doc/dist/index.js test-project --yes \
  --search --no-sidebar-filter --no-i18n --no-claude-resources \
  --color-scheme-mode single --scheme "Default Dark" --no-install

i18n:

cd __inbox/generator-test-i18n && \
  node $REPO_ROOT/packages/create-zudo-doc/dist/index.js test-project --yes \
  --no-search --no-sidebar-filter --i18n --no-claude-resources \
  --color-scheme-mode single --scheme "Default Dark" --no-install

sidebar-filter:

cd __inbox/generator-test-sidebar-filter && \
  node $REPO_ROOT/packages/create-zudo-doc/dist/index.js test-project --yes \
  --no-search --sidebar-filter --no-i18n --no-claude-resources \
  --color-scheme-mode single --scheme "Default Dark" --no-install

Note: sidebarFilter is built into sidebar-tree.tsx and ships in base by design (see src/features/index.ts:37); it is NOT tracked in settings.ts (no field emitted). --no-sidebar-filter currently has no structural effect. This test verifies the flag does not cause errors.

claude-resources:

cd __inbox/generator-test-claude-resources && \
  node $REPO_ROOT/packages/create-zudo-doc/dist/index.js test-project --yes \
  --no-search --no-sidebar-filter --no-i18n --claude-resources \
  --color-scheme-mode single --scheme "Default Dark" --no-install

design-token-panel:

cd __inbox/generator-test-design-token-panel && \
  node $REPO_ROOT/packages/create-zudo-doc/dist/index.js test-project --yes \
  --no-search --no-sidebar-filter --no-i18n --no-claude-resources \
  --no-image-enlarge --no-tag-governance --design-token-panel \
  --color-scheme-mode single --scheme "Default Dark" --no-install

light-dark:

cd __inbox/generator-test-light-dark && \
  node $REPO_ROOT/packages/create-zudo-doc/dist/index.js test-project --yes \
  --no-search --no-sidebar-filter --no-i18n --no-claude-resources \
  --color-scheme-mode light-dark --light-scheme "Default Light" --dark-scheme "Default Dark" \
  --no-install

lang-ja:

cd __inbox/generator-test-lang-ja && \
  node $REPO_ROOT/packages/create-zudo-doc/dist/index.js test-project --yes \
  --no-search --no-sidebar-filter --no-i18n --no-claude-resources \
  --lang ja --color-scheme-mode single --scheme "Default Dark" --no-install

all-features:

cd __inbox/generator-test-all-features && \
  node $REPO_ROOT/packages/create-zudo-doc/dist/index.js test-project --yes \
  --i18n --search --sidebar-filter --claude-resources --claude-skills \
  --design-token-panel --sidebar-resizer --sidebar-toggle --versioning \
  --doc-history --body-foot-util --llms-txt --skill-symlinker \
  --footer-nav-group --image-enlarge --footer-copyright --changelog \
  --tag-governance --doc-tags --footer-taglist \
  --color-scheme-mode light-dark --light-scheme "Default Light" \
  --dark-scheme "Default Dark" --default-mode dark \
  --github-url "https://github.com/example/test-project" --no-install

Step 3: Install Dependencies

cd __inbox/generator-test-<pattern>/test-project && pnpm install

If installation fails, report the error and stop.

Step 4: Build

cd __inbox/generator-test-<pattern>/test-project && pnpm build

If the build fails, report the error and stop.

Step 5: Dev Server Smoke Test

Start the dev server, wait for startup, check it didn't crash, then kill it:

cd __inbox/generator-test-<pattern>/test-project && \
  timeout 15 pnpm dev 2>&1 &
DEV_PID=$!
sleep 8
if kill -0 $DEV_PID 2>/dev/null; then
  echo "DEV_SERVER: OK — process still running"
  kill $DEV_PID 2>/dev/null
  wait $DEV_PID 2>/dev/null
else
  wait $DEV_PID
  EXIT_CODE=$?
  echo "DEV_SERVER: FAILED — process exited with code $EXIT_CODE"
fi

If the dev server crashed, report the error.

Step 6: Verify Files

Check that expected files exist or don't exist in __inbox/generator-test-<pattern>/test-project/.

File Expectations per Pattern

Use these tables to verify. Check each file with test -e <path>.

Note on theme-toggle.tsx: as of the Collapse Wiring Shells change (zudolab/zudo-doc#2420, v2.0.0) the theme toggle is provided by @takazudo/zudo-doc — generated projects no longer ship src/components/theme-toggle.tsx on disk (it collapsed into the package). The expectation tables below assert ABSENT for it.

Note on file extensions: all components are .tsx — there are no .astro files in the generated project. The generator uses zfb/Preact, not Astro.

barebone — minimal, no optional features:

search:

Note: the search feature wires search via the zfb config and package.json deps; it does not copy a dedicated search component file to src/components/. Verify search is enabled by checking package.json devDependencies for "pagefind" and dependencies for "minisearch"; check zfb.config.ts for search-index-plugin.mjs.

i18n:

sidebar-filter:

Note: sidebar-tree.tsx always ships with the base template; the sidebarFilter flag controls whether filtering UI is active at runtime. sidebarFilter is NOT emitted as a field in settings.ts (no field). Confirm via zfb.config.ts or runtime behavior — not a settings field.

claude-resources:

design-token-panel:

light-dark:

lang-ja:

all-features:

Step 7: Verify Settings

Read __inbox/generator-test-<pattern>/test-project/src/config/settings.ts and check:

Settings Expectations per Pattern

barebone:

• colorScheme: "Default Dark"
• colorMode: false
• locales: {} (empty)
• imageEnlarge: false
• tagGovernance: "off" (no tags:audit/tags:suggest scripts, no string-similarity/pluralize devDeps)
• tagVocabulary: false
• designTokenPanel: false
• claudeResources: false

search:

• colorScheme: "Default Dark"
• colorMode: false

i18n:

• locales: should contain ja entry with dir: "src/content/docs-ja"

sidebar-filter:

• Same as barebone but with sidebarFilter defaulting to included

claude-resources:

• claudeResources: should be truthy (object with claudeDir)

design-token-panel:

• designTokenPanel: true

light-dark:

• colorMode: should be an object with defaultMode, lightScheme: "Default Light", darkScheme: "Default Dark"

lang-ja:

• colorScheme: "Default Dark"
• Check src/config/settings.ts for defaultLocale: "ja" — this is the authoritative field emitted by settings-gen.ts; src/config/i18n.ts derives defaultLocale from settings.defaultLocale at runtime and does not hardcode it

all-features:

• colorMode: should be an object (light-dark mode)
• locales: should contain ja entry
• claudeResources: should be truthy
• designTokenPanel: true

Step 8: Compare Against Showcase

For the feature being tested, briefly compare the generated project against the main zudo-doc showcase:

• Read the equivalent component/config in src/ (the showcase) and in the generated project
• Verify they share the same structure (the generated version may have stripped imports/features, but the enabled feature's code should match)

This is a sanity check, not a full diff. Focus on the feature under test.

Step 8.5: Headless Browser Check (only with --headless)

Skip this step unless --headless was passed.

Start the dev server and use /headless-browser (Tier 1: headless-check.js) to verify pages actually render in a browser.

8.5a. Start dev server

cd __inbox/generator-test-<pattern>/test-project
pnpm dev --port 14350 &
DEV_PID=$!
sleep 6

8.5b. Check pages with headless browser

Check the index page and a docs page:

HC=~/.claude/skills/headless-browser/scripts/headless-check.js
node $HC --url "http://localhost:14350/" --screenshot viewport --no-block-resources
node $HC --url "http://localhost:14350/docs/getting-started" --screenshot viewport --no-block-resources

For i18n and all-features patterns, also check the Japanese page:

node $HC --url "http://localhost:14350/ja/docs/getting-started" --screenshot viewport --no-block-resources

8.5c. Verify results

• All pages should return statusCode: 200
• pageErrors should be empty (no JS errors)
• networkErrors.failedRequests — ignore net::ERR_ABORTED (Vite HMR re-optimization, normal in dev). Flag any other failures.
• Read the screenshots with the Read tool and visually confirm:
  • search: search icon (magnifying glass) visible in header
  • i18n: "EN / JA" language switcher in header
  • light-dark: theme toggle icon in header
  • design-token-panel: design token icon in header
  • claude-resources: page renders without errors
  • all-features: all icons present (search, theme toggle, language switcher, color tweak)
  • barebone: no extra icons in header (no search, no theme toggle, no language switcher)
  • lang-ja: Japanese content ("ようこそ" title)

8.5d. Kill dev server

kill $DEV_PID 2>/dev/null; wait $DEV_PID 2>/dev/null

Step 9: Clean Up

rm -rf ./__inbox/generator-test-<pattern>

Always use relative path with ./ prefix for cleanup.

Step 10: Report Results

Provide a clear pass/fail report:

## Pattern: <pattern>

### Scaffold: PASS/FAIL
### Install: PASS/FAIL
### Build: PASS/FAIL
### Dev Server: PASS/FAIL
### File Verification: PASS/FAIL
  - [list any unexpected files present/absent]
### Settings Verification: PASS/FAIL
  - [list any mismatches]
### Showcase Comparison: PASS/FAIL
  - [notes]
### Headless Browser: PASS/FAIL/SKIPPED
  - [only if --headless was passed]

### Overall: PASS/FAIL

Important Notes

• Always cd back to the repo root between major steps (use absolute paths)
• The --yes flag auto-fills all unspecified options with defaults. Feature defaults with --yes: search=true, sidebarFilter=true, imageEnlarge=true, tagGovernance=true, i18n=false, claudeResources=false, designTokenPanel=false (all other features false)
• Use --no-install with CLI to prevent auto-install, then install manually for better error visibility
• sidebarFilter is built into sidebar-tree.tsx by design (not a TODO); no strip step exists in the additive architecture
• The dev server smoke test uses pnpm dev (generated projects have a single dev script)
• If any step fails, still report all steps attempted before stopping
• The --headless flag enables Step 8.5 (headless browser visual check). Without it, only process-level checks are performed