dev

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 25, 2026 License: MIT Imports: 28 Imported by: 0

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

func Serve(root string, opts Options) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL