Development Loop

Ownership: spice dev is implemented and performance-gated in spice-framework/toolchain; reference applications prove it as black-box consumers.

spice dev is a repository-owned development supervisor. It is not a shell loop and it never builds over the executable that is currently running.

Run

From a Go module containing one preferred package-main @Application:

go tool github.com/spice-framework/toolchain/cmd/spice dev [--target name] [dev-option ...] [package-pattern ...] [-- application-argument ...]

The defaults are:

--quiet=150ms
--max-delay=2s
--poll=500ms
--stop-timeout=15s

--include pattern extends the default relevant-file policy and may be repeated. --exclude pattern removes paths and may also be repeated. Patterns are workspace-relative, accept ordinary Go path globs, and support ** segments.

Application arguments after -- are passed directly to every candidate process without a shell.

Candidate pipeline

Every accepted change batch has one monotonically increasing revision:

1. submit the revision to the shared overlay-aware compiler service, which cancels and rejects obsolete analysis;
2. report the same source-positioned compiler failures used by other CLI commands;
3. render and apply generation through the ownership guard;
4. build the exact package-main target with go build -trimpath;
5. keep the result in a unique temporary directory;
6. request bounded graceful stop only after the candidate is complete;
7. launch the candidate in an isolated process group;
8. release obsolete candidate artifacts idempotently.

If analysis, generation, or compilation fails, the current process is not stopped. The supervisor reports that it remains on the last-known-good revision and continues watching. An initial failure also leaves the watcher active, so saving a correction can produce the first process.

The reusable engine has explicit contracts for file events, clocks/timers, candidate preparation, process launch, graceful stop, and structured events. Tests use synthetic events and a fake clock; the command-level recovery test builds and restarts a real generated package-main application under the race detector.

Watch policy

The portable watcher recursively scans the workspace on Windows and Linux. It discovers new and renamed directory trees without registration races and hashes relevant regular-file contents, so an editor save is detected even when size and modification time are unchanged. Polling is the correctness baseline and will remain the bounded fallback when a native notification accelerator is added.

Defaults observe:

• Go source and go.mod, go.sum, go.work, and go.work.sum;
• JSON, YAML, TOML, SQL, HTML, and common template files;
• additional assets named by --include.

Defaults ignore:

• .git, vendor, node_modules, editor/tool directories, and conventional build output;
• temporary editor files;
• .spice build/dev artifacts;
• all mirrored *_spice_gen.go source units, target orchestrators, generated OpenAPI, ownership manifests, and internal/spicegen output.

Paths are normalized to workspace-relative slash form. Unsafe absolute or parent-traversing include/exclude patterns fail before watching starts.

Process and output policy

Each child owns a process group. Graceful replacement sends the platform interrupt (CTRL_BREAK on Windows and a group signal on Unix), waits for the generated lifecycle and HTTP drain, and escalates only after --stop-timeout. Cancellation of the supervisor uses the same bounded stop path and does not leave an intentionally detached child.

Development observations are concise and structured around change detection, analysis, generation, build, failure, last-known-good retention, restart, start, exit, watcher recovery, and artifact cleanup. The supervisor never prints environment contents, authorization tokens, SQL arguments, message bodies, or attachment contents. Compiler/build output is bounded before it is attached to a failure.

Current boundary

This slice provides the complete CLI supervisor, shared compiler-service integration, and portable fallback watcher. The editor-neutral LSP shares the same compiler analysis and stale-revision semantics, and the first-party Zed adapter supplies completion, navigation, diagnostics, and semantic presentation. A native notification accelerator remains an optional latency improvement rather than a correctness dependency. Generated application code remains ordinary committed Go and requires no Spice compiler at runtime.