Forthcoming Capabilities
Design-stage write-ups of capabilities that are specified in Netsuke's design documents and RFCs but have not shipped. Each page says what is designed, what is implemented on a branch, and which release the preview is targeted at. Names, flags, and file formats here may change before they land.
System Facts
An opt-in, immutable host object — operating system, family, architecture, executable suffix, and path separators, collected once per run with no shell, environment, or network access — so a manifest can branch on its platform without sniffing OS=Windows_NT.
Standard Library Expansion
Structured data readers, configuration layering, build matrices with stable ordering, version tests, cross-platform path text, and Git-aware quality-gate selection — every helper pure, bounded, and capability-scoped.
Read the previewStructured Commands
Argv-safe invoke blocks where an interpolated value can never become syntax: per-command environments and working directories, private temporary directories, shell-free pipelines, and an allow-list of named shells.
Reusable Modules
Manifest composition in three layers: repository-relative includes with namespaces, versioned local bundles with typed parameters and private declarations, and digest-pinned external bundles that build offline from a verified cache.
Read the previewNetsukefile Testing Framework
Manifest-time tests under netsuke test that run through the same compiler as the build. A YAML test dialect beside the manifest, mock and fixture engines so a test never touches the real host, and assertions over the expanded manifest, the build graph, and the generated Ninja.
Netsukefile Linter
Deterministic manifest linting under netsuke check, inspired by mbake. Named rules covering correctness, caching, portability, and clarity; per-rule severity policy; an explainable rule reference; and findings that share the compiler’s own diagnostics envelope. Findings never mutate the manifest.
Property Testing
The testing framework’s next step: quantified assertions over every generated action, bounded forall generation with seeded replay, built-in metamorphic mutations, and a lint that names the rules no property covers.
States and Probes
Named states for what must be ready before a command runs — a directory, a virtual environment, a working service — checked by built-in probes or external functional checks, prepared at most once, and never repaired behind your back.
Read the previewTyped Inputs
Optional types, defaults, and choices for the values a manifest takes, validated before anything runs, with one parameter contract shared by the command line, profiles, and callers.
Read the previewOwned Artefacts
Declare which paths a build owns and who produces them, then clean exactly that scope with clean --artefact — validated before anything is deleted, and never a wildcard.
How to read a preview
- Sketch means the maintainers have stated the shape of a capability and where it belongs, but no RFC has been written. Expect the names on a sketch page to change.
- Proposed RFC or designed means the behaviour is specified in an RFC, ADR, or design document in the Netsuke repository, and the page links to it.
- Implemented on a branch means code exists against the design but has not been merged and released. Treat it as evidence the design is buildable, not as a contract.
- Preview targeted at names the release in which the capability is planned to appear behind a preview label. The roadmap tracks the current sequence, and the task-level roadmap the detail. No release named means exactly that: the design is written down, and nobody has promised when it lands.
- Every preview ends with the same three questions: where the shallow end is and how the deeper water is signposted, what gives you confidence that a build using it is correct, and how it serves accessibility and localization. Nothing here is allowed to make a plain manifest harder to write.