Documentation
¶
Overview ¶
Package dev implements `puzzle dev`: an initial development build, a recursive fsnotify watch of the app's source tree, a debounced rebuild loop, a static file server for dist/ with history-API fallback, and SSE-based live reload. It reworks the Phase 1 prototype watcher (compiler/internal/watcher, deleted) per constellation/doc/DOC-BUILD-PLAN.md Phase 3, fixing every sin cataloged in constellation/doc/DOC-CODE-REVIEW.md §1.4:
- notifyReload() was an empty placeholder and the SSE endpoint only pinged; here every successful rebuild broadcasts a real `reload` event.
- nothing injected an EventSource client; here index.html gets the client injected at serve time (dist/index.html on disk stays clean for prod).
- new subdirectories were never watched; here Create events on directories re-add them to the watcher recursively.
- log.Fatal in the server goroutine and select{} for lifetime; here the server error returns through a channel and shutdown is graceful (SIGINT/SIGTERM → http.Server.Shutdown, SSE handlers released via context).
Styles/rebuild speed (D27, amending D26): dev drives an incremental esbuild api.Context (build.WatchBuilder) and a single long-lived `tailwindcss --watch` child (styles.TailwindWatcher) instead of a cold full build + one-shot Tailwind per change. dist/styles.css is recomposed whenever either the watcher rewrites its private output or an esbuild rebuild changes the collected <style>; the two reloads a single edit produces are coalesced. Production `puzzle build` keeps D26's one-shot path.
keys.go implements the portable, TTY-agnostic half of `puzzle dev`'s "press q to quit" affordance. listenKeys is deliberately kept pure over an io.Reader (rather than reaching for os.Stdin directly) so it can be unit tested without a real terminal: a test feeds it a bytes.Reader and asserts on the returned channel. The termios/TTY plumbing that puts a real stdin into cbreak mode lives in the build-tagged keys_unix.go / keys_other.go files.
keys_termios_linux.go pins the Linux ioctl requests for reading and writing the terminal attributes: TCGETS/TCSETS (BSD/darwin use TIOCGETA/TIOCSETA — see keys_termios_bsd.go). This split mirrors how golang.org/x/term selects the constant per platform.
keys_unix.go puts stdin into "cbreak" mode so `puzzle dev` can read a single keypress (the 'q' quit) without waiting for Enter, and without echoing the keystroke to the terminal.
We deliberately use CBREAK, not full raw mode:
- ISIG is left ON, so Ctrl+C still generates SIGINT — the existing signal path keeps working exactly as before; 'q' is an addition, not a replacement.
- The output flags (OPOST/ONLCR) are left untouched, so the rebuild/log lines the dev loop prints keep their normal "\n"→"\r\n" translation and don't stair-step across the terminal.
We only clear ICANON (line buffering) and ECHO (so the typed 'q' is invisible), and set VMIN=1/VTIME=0 for a blocking one-byte read.
The TTY gate is free: IoctlGetTermios fails when stdin is not a terminal (a pipe, file redirect, or CI), and we treat that failure as "not a TTY" and return ok=false — the feature silently switches off and nothing else changes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Serve ¶
Serve runs the dev loop for the app rooted at root (the directory holding app/app.js). It performs an initial development build, serves root/dist, watches root/app, and blocks until SIGINT/SIGTERM or a fatal server error.
A failing build — at startup or on any change — is printed (with esbuild's positioned diagnostics) but never terminates the process: whatever dist/ already holds keeps being served and the next change retries.
Types ¶
type Options ¶
type Options struct {
// Port is the TCP port the static/SSE server listens on. A busy port is not
// fatal: Serve scans upward for the next free one (see portScanLimit) unless
// StrictPort is set.
Port int
// StrictPort, when true, binds Port or fails. Pinned ports exist on purpose
// — container mappings, OAuth redirect URIs, proxy configs — and silently
// moving to a neighbour breaks whatever depends on the number.
StrictPort bool
// Open, when true, best-effort opens the app in the default browser once
// the server is listening.
Open bool
// Fixtures wires the app's app/fixtures.js (or .ts) through the detachable
// fixtures/mock runtime module (`--fixtures`, D98). The wrapper entry is
// generated once, at builder construction, and lives under <root>/.puzzle/ —
// outside every watched directory, so it cannot feed a rebuild loop.
Fixtures bool
// OnReady, when set, runs after the server's ready banner is printed.
OnReady func()
// contains filtered or unexported fields
}
Options configure Serve.