feat(create-bestax): scaffold .claude/launch.json with the AI skills opt-in

[allxsmith]

Pull Request

Description

When the user accepts the "Install the bestax AI skills?" prompt, create-bestax now also writes a .claude/launch.json into the scaffolded project (both vite and vite-ts templates), so Claude Code's browser preview can preview_start the app's dev server by name instead of rediscovering the command from package.json.

• bulma-ui (@allxsmith/bestax-bulma)
• create-bestax (create-bestax)
• docs (@allxsmith/bestax-docs)
• Other (please specify):

Details, per the issue's design decisions:

• Gated behind the skills opt-in — written in setupSkills alongside the .claude/skills copy; users who declined AI files get nothing new (and the degenerate missing-bundle build still writes nothing).
• Package-manager-neutral — runtimeExecutable: "npm" with npm run dev, which works regardless of which PM installed the project.
• Port pinned loudly — runtimeArgs pass -- --strictPort so Vite fails when 5173 is busy instead of silently drifting to 5174 and desyncing from the declared port.

Also touched:

• MESSAGES.SKILLS_ADDED now mentions .claude/launch.json.
• The scaffolded CLAUDE.md template tells agents the file exists and to start the dev server from it.
• Docs: a new "AI-ready scaffolds" section in the AI-Assisted Development guide, and the LLMs guide's "Starting a new app?" paragraph now enumerates the file.

Related Issue(s)

Fixes #337

Type of Change

• Bug fix
• New feature
• Refactor
• Documentation
• Performance
• Build tooling
• Other (please describe):

Checklist

• My code follows the project style guidelines
• I have performed a self-review of my code
• I have added tests that prove my fix is effective or that my feature works
• I have added/updated documentation as needed
• I have updated Storybook stories as needed (bulma-ui)
• My changes require a change to the documentation
• All new and existing tests passed
• Any relevant dependencies are updated
• If this PR changes commands, conventions, or package structure, the affected CLAUDE.md files are updated

Tests: new unit coverage for the LAUNCH_JSON constant (valid JSON, npm + --strictPort, port 5173), the setupSkills write path, and create()-level gating (skills accepted → file written; declined → not). create-bestax suite: 197 passed; coverage above the 95% bar; typecheck/lint/format green.

Screenshots / Demos

Scaffolded with the opt-in accepted:

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev", "--", "--strictPort"],
      "port": 5173
    }
  ]
}

Smoke-tested by scaffolding real apps from dist/: with -y (skills default on) the file lands in .claude/ next to skills/ and the success line reads ✔ Installed bestax AI skills into .claude/skills/ (+ CLAUDE.md, .claude/launch.json); with --no-skills no .claude/ directory is created.

Additional Context

Commit type is feat(create-bestax) → minor release of create-bestax only. The bundled templates/skills copy was not edited (build re-syncs it).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Fh5j4Th9cdaEpZnVirseot

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • New projects with AI skills enabled now include a .claude/launch.json configuration for browser previews.
  • The configuration starts the development server on port 5173 with strict port handling.
  • Generated project guidance now documents the browser preview setup.

• Documentation

  • Updated AI development and LLM guides to explain AI-ready scaffolds and launch configuration.

[coderabbitai]

Warning

Review limit reached

@allxsmith, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 47 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: b462278e-b816-4603-bf53-2c5f6ffe2fe9

📥 Commits

Reviewing files that changed from the base of the PR and between 1e200cc and 093d239.

📒 Files selected for processing (1)

• create-bestax/e2e/utils/scaffold.ts

Walkthrough

The scaffold now exports a .claude/launch.json template, writes it when AI skills are enabled, validates the behavior with tests, and documents the generated configuration in CLAUDE.md and the AI development guides.

Changes

Scaffold launch configuration

Layer / File(s)	Summary
Launch configuration contract create-bestax/src/constants.ts, create-bestax/src/__tests__/constants.test.ts	Adds a dev launch configuration using npm run dev -- --strictPort on port 5173, updates generated CLAUDE.md, and tests the serialized structure and message text.
Skills setup writes launch configuration create-bestax/src/project-creator.ts, create-bestax/src/__tests__/project-creator.test.ts	Writes .claude/launch.json during skills setup and verifies presence when enabled and absence when disabled.
AI-ready scaffold documentation docs/docs/guides/getting-started/ai-development.md, docs/docs/guides/llms/index.md	Documents the generated launch configuration and its browser-preview dev-server behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant ProjectCreator
  participant FileSystem
  participant ClaudeCode
  User->>ProjectCreator: enables AI skills during project creation
  ProjectCreator->>FileSystem: writes .claude/skills/
  ProjectCreator->>FileSystem: writes .claude/CLAUDE.md
  ProjectCreator->>FileSystem: writes .claude/launch.json
  ClaudeCode->>FileSystem: reads the dev configuration
  ClaudeCode->>ProjectCreator: starts npm run dev with --strictPort on port 5173

Loading

Possibly related PRs

• allxsmith/bestax#271: Both update the scaffold setup flow and generated CLAUDE.md.
• allxsmith/bestax#302: Both update the generated CLAUDE.md content.
• allxsmith/bestax#329: Both modify the generated CLAUDE.md skill guidance.

Suggested labels: deep-review

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the main create-bestax change: scaffolding .claude/launch.json for the AI skills opt-in.
Description check	✅ Passed	The description matches the template well, covering summary, affected packages, issue link, change type, checklist, screenshots, and context.
Linked Issues check	✅ Passed	The changes implement #337's required gated .claude/launch.json scaffold with the requested npm, port 5173, and --strictPort config.
Out of Scope Changes check	✅ Passed	The additional docs, tests, and CLAUDE.md/message updates are all directly related to the requested scaffold change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/issue-337-rp64g0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Preview Deployment

Preview URL: https://d2a6017d.bestax.pages.dev

[allxsmith]

@claude please do a deep review of this PR.

---

Generated by Claude Code

[claude]

Claude finished @allxsmith's task in 1m 21s —— View job

---

Deep review complete

• Gather context (PR description, diff, CLAUDE.md)
• Review create-bestax/src/constants.ts changes
• Review create-bestax/src/project-creator.ts changes
• Review test coverage
• Review docs changes
• Post final review

Verdict: LGTM. This is a small, well-scoped, well-tested change with no bugs found.

What I checked

• Schema correctness — the generated LAUNCH_JSON shape (version, configurations[].name/runtimeExecutable/runtimeArgs/port) exactly matches this repo's own real .claude/launch.json (root of the repo, docs/storybook configs), which is strong evidence the template is schema-correct for whatever consumes it.
• Write ordering (create-bestax/src/project-creator.ts:120-124) — .claude/launch.json is written after fs.copy(skillsSrc, .../.claude/skills), so the .claude/ parent directory already exists by the time fs.writeFile runs (fs-extra's plain writeFile doesn't auto-mkdir, unlike outputFile). Correct as written.
• Gating — confirmed setupSkills early-returns before either write when the bundled skills dir is missing, so a degenerate build writes neither skills/ nor launch.json, matching the PR description. Covered by the two create()-level tests (accepted → written, declined → not written).
• Port consistency — neither templates/vite/vite.config.js nor templates/vite-ts/vite.config.ts overrides the dev port, so the hardcoded 5173 in LAUNCH_JSON matches Vite's actual default for both templates. If a template ever adds an explicit server.port, this constant would silently drift — not a concern today, just worth remembering if that changes.
• Package-manager neutrality — runtimeExecutable: "npm" with npm run dev -- --strictPort is a sound choice regardless of which PM scaffolded the project (pnpm/yarn/npm all populate a dev script npm can invoke).
• Docs — both ai-development.md and llms/index.md updates are accurate and consistent with the implementation; no drift between what's documented and what's written to disk.
• Tests — new coverage in constants.test.ts (valid JSON, npm + --strictPort, port 5173, message text) and project-creator.test.ts (setupSkills write path + create()-level accept/decline gating) are meaningful, not just snapshot padding. CI is green (CI, Visual Regression, Dependency Review, etc. all passing).

Minor, non-blocking observations

• No e2e (create-bestax/e2e/) assertion for launch.json presence — existing e2e suite doesn't check for it. Not a blocker given the unit coverage and the manual smoke test described in the PR body, but worth a follow-up if the e2e suite is meant to be the source of truth for "what a real scaffold contains."
• The version: '0.0.1' field is a fixed literal duplicated between this template and the repo's own .claude/launch.json — if that schema version ever bumps, both would need updating in lockstep, but that's an acceptable amount of duplication for a two-line constant.

No changes requested.

[github-actions]

Preview Deployment

Preview URL: https://71043ce3.bestax.pages.dev

[github-actions]

🎉 This PR is included in version 3.5.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 5.8.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀