Current version v0.1.0-beta3

Roadmap

v0.1.0-beta3 is a useful preview for early adopters, not a declaration that Netsuke is finished. This page tracks what shipped, what is honestly still rough, and the order of the work ahead.

Shipped in v0.1.0-beta3

The core build-system compiler is implemented and packaged for Linux, macOS, and Windows. The public beta releases so far cover the following; items marked beta3 are new in this release.

Manifest language

  • YAML 1.2 parsing with duplicate-key and schema validation
  • Jinja variables, macros, foreach, when, and globbing
  • Environment helpers, executable discovery, and opt-in network helpers
  • Rules, targets, actions, defaults, and explicit, implicit, and order-only dependencies
  • Ordered command lists with fail-fast && chaining, and description metadata on rules, targets, and actions
  • Dependency-only aggregates: an action or target with a non-empty deps list may omit its recipe beta3
  • Ordinary shell dollars: write $PATH as-is; Netsuke escapes it for Ninja after lowering the {{ ins }} and {{ outs }} markers beta3

Compiler & execution

  • A deterministic build graph with duplicate-output, missing-rule, and cycle checks
  • Ninja generation and execution, plus clean and standalone manifest generation
  • Dependency graphs as Graphviz DOT or self-contained, accessible HTML
  • Serial dependency ordering with dependency_order: serial, backed by Ninja dyndep
  • Windows legacy recipes run in Windows PowerShell by default, with an explicit Git Bash or MSYS2 compatibility route beta3
  • UTF-8 build-file and working-directory paths are required, with a clear diagnostic otherwise beta3

Operator experience

  • Layered configuration, localized output, and accessibility preferences
  • Progress reporting, stage timings, and versioned JSON results or diagnostics
  • A netsuke help targets catalogue of targets and actions, now listing conditional entries without rendering recipe bodies beta3
  • Configuration-selection diagnostics, cached configuration discovery, and bounded metrics under --verbose
  • Thirty-five locale catalogues; beta3 adds a published localization style guide and glossary beta3

Confidence & packaging

  • Unit, behavioural, integration, property, snapshot, and initial Kani verification coverage
  • Packages for Linux (.deb, .rpm), macOS (.pkg), and Windows (.msi)
  • Jinja glob() rejects matched filenames that cannot be inserted as one portable unquoted shell word beta3
  • A Windows CI job covering lint, compile, and test alongside the Linux and macOS matrix beta3

Known limitations

The compiler pipeline and ordinary local-build workflow are substantial; the command-line interface, configuration vocabulary, and advanced recipe model remain pre-stable. Pin the Netsuke version in automation and expect some command names, flags, diagnostic schemas, and manifest details to change before 1.0. The following limitations apply to v0.1.0-beta3.

Recipes remain shell strings: Unix scripts use /bin/sh -e, Windows legacy recipes use Windows PowerShell by default, and the Windows Bash compatibility route is an explicit opt-in. Structured executable arguments and recipe environment mappings are not implemented yet.

Beta3 fixes beta2's shell-dollar limitation with Ninja-aware escaping, so ordinary shell expressions are written normally. Beta2 manifests that spelled $$PATH or used the $in/$out placeholders need migration to $PATH and {{ ins }}/{{ outs }}; see the safety boundary.

Compiler-generated dependency imports, such as GCC depfiles, are planned but not yet part of the manifest model.

--json emits exactly one versioned result or diagnostic document per command, but the schema may still change before 1.0.

Accessibility still needs assistive-technology verification, and terminal rendering needs regression coverage.

Colour rendering is not implemented: --color affects mode selection but does not add coloured terminal text.

A Netsukefile can execute commands and use impure template helpers. Treat it with the same care as a Makefile: review untrusted manifests before running them. Netsuke quotes supported path substitutions, but it is not a sandbox.

The road ahead

Work after the first release is organized around three near-term priorities and a set of larger capability tracks, each validating one hypothesis. The detailed roadmap tracks the task-level sequence; completed foundations live in a separate archive so the active list stays honest. Two of the capability tracks have their own preview write-ups on the forthcoming capabilities pages.

Stabilize the command-line contract

Keep a pleasant, accessible local experience while making every command predictable for CI, editors, and agents.

In progress
  • Canonical command and flag names replacing the pre-0.1.0 surface
  • Non-interactive and mutation-safety guarantees (--no-input, --force, --dry-run)
  • Canonical structured --json output with stable exit codes and enumerable errors
  • Bounded output for every large response
  • Assistive-technology verification of accessible output
  • Regression coverage for the configuration precedence ladder
  • Regression coverage for terminal rendering and colour policy

Make recipes safer and clearer

Close the gap between shell-string recipes and a structured, argv-safe recipe model.

In progress
  • Structured exec recipes for argv-safe commands
  • Structured recipe environment mappings
  • Rule-level deps_from for compiler dependency imports (GCC depfiles)
  • Backend dollar escaping after placeholder lowering
  • Dependency-only aggregates in place of no-op recipes
  • Verbose reporting of why manifest-time when branches were included or skipped
  • env(name, default=...), shell_join, and compact helpers for deliberate shell recipes

Strengthen confidence

State and check the core compiler invariants strongly enough that future features cannot erode deterministic builds.

Started
  • Kani tooling, CI smoke job, and harnesses for manifest-to-IR safety and cycle canonicalization
  • Kani harnesses for command interpolation
  • Property tests for deterministic Ninja emission, expansion invariants, and render stability
  • Documented placeholder and cycle-detection contracts; evaluation of a minimal Verus proof kernel

Compounding features for humans and agents

Make repeated human, CI, editor, and agent usage improve through introspection, memory, and delivery.

Planned
  • Machine-readable context: netsuke context --json and skill-path
  • A run ledger: runs list, runs get, and runs prune
  • Named profiles with redaction and secret handling
  • Structured artefact delivery and local-first feedback

Netsukefile linter under netsuke check

Deterministic manifest linting inspired by mbake: style, correctness, and portability rules over the compiler's own stages; findings never mutate the manifest. Preview targeted at v0.2.0.

Preview: v0.2.0
  • netsuke check as the canonical validation command, with --json findings
  • A stable rule catalogue with per-rule enable, disable, and severity configuration
  • A --fail-on threshold, bounded --limit output, and --explain for the rule reference
  • Read the linter preview →

Netsukefile testing framework

Manifest-time tests that run through the same compiler as the build: deterministic, mock-friendly, and reported like any other Netsuke command. Preview targeted at v0.4.0.

Preview: v0.4.0
  • A netsuke test command and a YAML test dialect beside the manifest
  • Mock and fixture engines so tests never touch the real host
  • Assertions over the expanded manifest, the graph, and the generated Ninja
  • Read the testing framework preview →

Template standard-library expansion

Absorb common manifest operations into the standard library without weakening determinism or the capability boundary.

Planned
  • Structured data readers, configuration layering, and build matrices with stable ordering
  • Text and version conditions, cross-platform path composition, and query-gated host probes
  • Proportionate quality-gate selection from a deterministic Git changeset
  • Specified in RFC 0006