[AbuMareBear]

Summary

• Adds bin/dev, modeled on the Jekyll guidedrails script: bundle install if needed, npm install if needed, then exec bundle exec bridgetown start with any extra args passed through (e.g. bin/dev -P 4001).
• Since Stoa is a theme gem with no site of its own, bin/dev serves the test/fixtures site. The fixture now carries a standard Bridgetown esbuild + Tailwind v4 frontend (esbuild.config.js, config/esbuild.defaults.js generated by bridgetown esbuild setup, postcss.config.js with @tailwindcss/postcss, and a frontend/styles/index.css that mirrors the README recipe but imports the partial from the working tree). That's what makes asset_path :css / :js in the layout resolve to real hashed bundles instead of MISSING_FRONTEND_BUNDLING_CONFIG.
• Fixture config/initializers.rb now require_relatives the gem (the CLI path doesn't go through test/helper.rb), adds the gem's layouts/ to additional_watch_paths, and sets fast_refresh = false because fast refresh assumes changed paths live under src/ and errors on the absolute layout path.
• Adds puma to the Gemfile's development group; without it bridgetown start reports "Unable to find a Rack server."
• Excludes bin/ from the gem's files glob and gitignores the fixture's output/ and tmp/.

Background

Bridgetown 2.x's start command doesn't launch the frontend bundler itself. It loads the site's Rakefile and invokes frontend:watcher, which shells out to the site's frontend:dev task, hence the minimal test/fixtures/Rakefile. The official Tailwind automation runs the Tailwind CLI as a sidecar and patches the manifest by hand, but since the layout uses asset_path :css (manifest key styles/index.css), running Tailwind through esbuild's PostCSS pipeline is simpler and matches what a host site following the README actually does.

README fix

While wiring the fixture, the theme partial's rules never showed up in the built CSS. Cause: the README snippet placed @source between @import "tailwindcss" and @import "bridgetown-stoa". CSS requires all @import rules to be consecutive and precede other rules, so both @tailwindcss/postcss and postcss-import silently dropped the second import (postcss-import emits a warning; Tailwind doesn't). Any host site that followed the README as written got no theme styles. The snippet is reordered and the reason noted. CHANGELOG has an entry under Unreleased.

Test plan

• bin/dev -P 4599 boots Puma, esbuild builds index.<hash>.js and index.<hash>.css, and the rendered page links both via /_bridgetown/static/.
• Built CSS contains --color-stoa-* tokens and the html { background: var(--color-stoa-bg) ... } base rule.
• Touching layouts/bridgetown-stoa/layout.serb triggers a clean full rebuild (was a NoMethodError under fast refresh before disabling it).
• Touching frontend/styles/bridgetown-stoa.css makes esbuild rebuild, the manifest change triggers a Bridgetown reload.
• Ctrl-C / SIGINT stops Puma, the build watcher, and the esbuild process together.
• script/cibuild passes (rubocop clean, 4 tests / 20 assertions). The test suite never touches npm.

Notes

• test/fixtures/package-lock.json is excluded by the maintainer's global gitignore, so bin/dev keys its reinstall check off package.json mtime rather than the lockfile. Force-add the lockfile if reproducible npm installs become important.
• The stale root package-lock.json (a leftover from the self-referencing dep bug fixed in Match bridgetown-quick-search plugin conventions #12) was deleted locally; it was untracked.

🤖 Generated with Claude Code