styles

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Jul 22, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package styles owns the CSS side of a build: running the Tailwind pipeline (constellation/doc/DOC-DECISIONS.md D12/D26) and composing the final dist/styles.css.

Composition (SPEC §3): the final stylesheet is the Tailwind output (when the pipeline is enabled) followed by the collected <styles> blocks. index.html links a single /styles.css, so both layers must land in one file with the Tailwind utilities first and hand-written global CSS appended after.

The Tailwind invocation is behind the Runner interface so builds can be exercised without the real toolchain (unit tests inject a fake), while the production path shells out to the Tailwind CLI via npx.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Compose

func Compose(tailwindCSS, collected string) string

Compose builds the final dist/styles.css contents: the Tailwind layer first, then the collected <styles> blocks. Either part may be empty. A single trailing newline is guaranteed when there is any content.

func DefaultInput

func DefaultInput(appRoot string) string

DefaultInput returns the app's Tailwind input CSS path if the conventional app/styles/styles.css exists, else "" (Tailwind uses its default).

Types

type NpxRunner

type NpxRunner struct{}

NpxRunner runs the Tailwind CLI once per build. It resolves the CLI directly from node_modules first (running `node <@tailwindcss/cli bin>` for v4 or the `.bin/tailwindcss` shim for v3, skipping npx's resolution + a Node cold start — D27), then falls back to `npx @tailwindcss/cli` (v4) and `npx tailwindcss` (v3). If none can run — no Node/npx, offline with nothing cached — Run returns a clear toolchain-missing error so the declared pipeline fails loudly rather than producing a silently empty stylesheet.

func (NpxRunner) Run

func (NpxRunner) Run(opts RunOptions) (string, error)

Run implements Runner. It writes Tailwind's output to a temp file, reads it back, and returns it as a string (keeping the single-output-file contract in Compose's hands rather than letting the CLI own dist/styles.css directly).

type ResolvedCLI

type ResolvedCLI struct {
	// Name identifies the invocation in logs and error messages.
	Name string
	// Exec is the program to run: "node", an absolute path to a .bin shim, or
	// "npx".
	Exec string
	// Args are the leading arguments before the caller appends -i/-o/etc.
	Args []string
}

ResolvedCLI is one runnable Tailwind CLI invocation: an executable plus the fixed leading arguments that precede -i/-o/--watch/--minify. Direct resolutions (`node <bin script>`, or the v3 `.bin/tailwindcss` shim) run with no npx overhead; the npx entries are the portable fallback (D27).

func ResolveCLI

func ResolveCLI(appRoot string) (ResolvedCLI, bool)

ResolveCLI returns the first Tailwind CLI candidate for appRoot. It is used for user-facing status text in paths that run Tailwind one-shot per rebuild.

type RunOptions

type RunOptions struct {
	// AppRoot is the absolute app root (the directory holding app/).
	AppRoot string
	// Input is the absolute path to the input CSS entry, or "" to let Tailwind
	// use its default (which still emits the utility layers).
	Input string
	// Production adds --minify to the CLI invocation.
	Production bool
}

RunOptions parameterize a Tailwind run.

type Runner

type Runner interface {
	// Run generates and returns the Tailwind CSS as a string. A non-nil error
	// must fail the build — a declared pipeline is never silently skipped
	// (constellation/doc/DOC-BUILD-PLAN.md Phase 3).
	Run(opts RunOptions) (string, error)
}

Runner produces the Tailwind CSS layer for an app. The real implementation (NpxRunner) shells out to the Tailwind CLI; tests use a fake.

type TailwindWatcher

type TailwindWatcher struct {
	// OutputPath is the private CSS file the child writes (-o). It must not be
	// served directly; the dev loop reads it to recompose the real styles.css.
	OutputPath string
	// Name is the resolved CLI's human-readable identifier (for logs).
	Name string
	// contains filtered or unexported fields
}

TailwindWatcher manages a long-lived `tailwindcss --watch` child process. It is started ONCE per `puzzle dev` session (D27) instead of re-spawning the CLI on every rebuild (D26's one-shot path, retained for `puzzle build`). The child continuously rewrites its own private output file; the dev loop watches that file and recomposes dist/styles.css when it changes.

Lifecycle: StartWatch launches the process and returns immediately. The process is killed when the supplied context is cancelled (shutdown) or via an explicit Stop. Done() closes when the process exits for any reason — the dev loop selects on it to detect an unexpected death and fall back to one-shot composition so CSS never goes silently stale.

func StartWatch

func StartWatch(ctx context.Context, opts WatchOptions) (*TailwindWatcher, error)

StartWatch resolves the Tailwind CLI (best-first: direct node_modules, then npx), starts it with --watch writing to opts.Output, and returns a handle. It errors only if the process fails to start.

func (*TailwindWatcher) Done

func (w *TailwindWatcher) Done() <-chan struct{}

Done returns a channel closed when the watcher process has exited.

func (*TailwindWatcher) Err

func (w *TailwindWatcher) Err() error

Err returns the process's exit error (nil until it exits; the Wait error after). A killed process reports a signal error, which is expected on Stop.

func (*TailwindWatcher) Stop

func (w *TailwindWatcher) Stop()

Stop kills the watcher process (group) and closes the held-open stdin pipe. Safe to call multiple times.

type WatchOptions

type WatchOptions struct {
	// AppRoot is the app root (the child's working directory and the base for
	// CLI resolution).
	AppRoot string
	// Input is the Tailwind input CSS (-i), or "" for the CLI default.
	Input string
	// Output is the private output CSS file (-o). Required.
	Output string
	// Stderr, when set, receives the child's stderr (diagnostics). Optional.
	Stderr io.Writer
	// CLI overrides the resolved Tailwind CLI. Tests inject a fake long-running
	// command here so the watcher lifecycle can be exercised without Tailwind.
	CLI *ResolvedCLI
}

WatchOptions parameterize StartWatch.

Jump to

Keyboard shortcuts

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