Structured Commands

Argv-safe commands with invoke

command gains two new forms beside the existing ones: a mapping with an invoke key, and a list that mixes strings, invoke blocks, rule: items, and script: items. With shell absent or false, invoke is an argv template. Quotes group words and are removed; a backslash outside quotes is literal, so C:\tools\bin survives; unquoted |, &, ;, <, and > are errors that catch accidental pipelines and redirections; and nothing expands — no $HOME, %TEMP%, globs, or $(…).

# Existing scalar shell command.
command: cargo test

# New structured command block.
command:
  invoke: cargo test
  env:
    RUST_BACKTRACE: "1"

# New heterogeneous command list.
command:
  - invoke: cargo build
  - rule: package
  - script: |
      printf '%s\n' 'package complete'

command:
  invoke: frobnicate --output={{ destination }}
# destination = "release files; delete nothing"
# argv: ["frobnicate", "--output=release files; delete nothing"]

vars:
  coverage_args: [--all-targets, --all-features]
command:
  invoke: cargo llvm-cov {{ coverage_args }}
# argv: ["cargo", "llvm-cov", "--all-targets", "--all-features"]

command:
  invoke: clang {{ ins }} -o {{ outs }}
# one argv element per path, spaces and all

A scalar fills exactly one word. A list splices its elements only when it stands as a whole unquoted word. A stray $in or $out earns a targeted diagnostic pointing at {{ ins }} and {{ outs }}. On Windows, direct mode refuses a resolved cmd.exe, .bat, or .cmd target, because cmd.exe can reread separate arguments as shell source. Ninja still schedules the build: a structured edge calls a hidden Netsuke action runner by opaque ID, and the generated Ninja line carries no rendered user arguments or environment values.

Roadmap 12.1 Command structure before values · 12.2 Isolated execution · 12.3 Build and generate workflows

Environments and working directories

A block's env is an exact overlay for that one child process. It needs no shell quoting and does not persist to later blocks. Duplicate keys are invalid, compared case-insensitively on Windows. RFC 0009 adds cwd, so a structured command no longer has to fall back to shell: true and cd dir && ….

actions:
  - name: coverage
    command:
      - invoke: 'echo "coverage linker flags: -fuse-ld=lld"'
      - invoke: >-
          cargo llvm-cov --lcov --output-path lcov.info
          --all-targets --all-features
        env:
          CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER: clang
          RUSTFLAGS: -D warnings -C link-arg=-fuse-ld=lld
          CFLAGS: -fuse-ld=lld
          LDFLAGS: -fuse-ld=lld

command:
  invoke: cargo test --all-targets
  cwd: rust_extension

command:
  - invoke: generator --format json
    cwd: producer
    pipe: true
  - invoke: validator --schema schema.json
    cwd: consumer
    stdout: validated.json

Roadmap 12.2 Exact overlays and literal cwd · 15.1 Additional environment surfaces

Runtime bindings and private scratch space

RFC 0010 lets one execution unit pass a discovered value to the next without a shell. A block's standard output can be captured into a named binding, and a later block can use it as its working directory. A block can also ask the runner for a private temporary directory and name it for its successors.

command:
  - invoke: workspace-locator --relative
    stdout:
      env: WORKSPACE_DIR
  - invoke: cargo test --all-targets
    cwd:
      env: WORKSPACE_DIR

command:
  - invoke: prepare-fixture
    cwd:
      tempdir:
        env: FIXTURE_DIR
  - invoke: verify-fixture
    cwd:
      env: FIXTURE_DIR

Runtime bindings are scoped data owned by the action runner, not mutations of the parent process environment. Text captured from a child cannot grant filesystem authority merely by containing an absolute path. — RFC 0010

Roadmap 14.1 Discovery results · 14.2 Temporary-directory authority · 14.3 Downstream-style proof

Streams and pipelines without a shell

Redirection and piping become fields: stdin, stdout, stderr, tee, pipe, and capture_stdout. Output files are create-or-truncate, with append mode reserved. Pipes and tees carry arbitrary bytes. Before anything is truncated, every destination in a unit is opened provisionally and compared, so relative aliases, symlinks, and hard links that name the same file are caught first.

command:
  - invoke: producer --format=json
    pipe: true
  - invoke: jq ".items[]"
    pipe: true
  - invoke: consumer
    stdout: result.txt

command:
  - invoke: compiler invalid-source.rs
    pipe: stderr
  - invoke: normalize-diagnostics
    stdout: normalized-errors.txt

command:
  - export MODE=fast
  - echo "$MODE"   # Same legacy shell group: prints fast.
  - invoke: tool
  - echo "$MODE"   # New legacy shell group: MODE is not retained.

Roadmap 13.1 Stream binding · 13.2 Pipelines · 13.3 Stream validation · 15.2 Append, merged streams, and more

Named, allow-listed shells

Some recipes need a shell. RFC 0011 widens shell from a Boolean to a Boolean or a name. true resolves to sh on Unix-like hosts and powershell on Windows; a name picks one of four built-ins. Any shell — shell: true or a named one — gives up direct mode's argv-safety. The selector changes the interpreter, not the safety boundary.

command:
  - invoke: cargo test --workspace
    shell: false          # direct: argv-safe
  - invoke: Write-Output $env:TARGET
    shell: true           # platform default: shell text
  - invoke: set -o pipefail; build-project
    shell: bash           # named: shell text
  - invoke: Get-ChildItem Env:
    shell: pwsh           # named: shell text

Roadmap 11.1 Contract (done) · 11.2 Trusted resolution · 11.3 Execution boundaries

From the shallow end

Nothing existing has to move. Scalar command strings keep their shell semantics, an all-string list behaves exactly as it does now, and no manifest is converted to direct invocation automatically. Structured mappings will sit behind an additive manifest minor version, provisionally 1.1.0, so older Netsuke releases reject the new syntax cleanly rather than misreading it.

1. 1 · Leave it

   command: "…" strings keep working unchanged. Recipes that depend on shell state should stay legacy, or use shell: true or a named shell.

2. 2 · Convert one item

   Lists may mix strings, invoke blocks, rule:, and script: items, so one line can move at a time. Migrate a legacy list only when no shell state must persist between its entries.

3. 3 · Replace the idioms

   Swap cd for cwd, command substitution for capture, and 2>&1 | for pipe: stderr where merged output is not required. A migration guide with executed examples is task 14.3.2.

# Before
command: cd rust_extension && cargo clippy --all-targets

# After
command:
  invoke: cargo clippy --all-targets
  cwd: rust_extension

# Before
command: WORKSPACE_DIR=$(tool locate) && cd "$WORKSPACE_DIR" && cargo test

# After
command:
  - invoke: tool locate --relative
    stdout:
      env: WORKSPACE_DIR
  - invoke: cargo test
    cwd:
      env: WORKSPACE_DIR

The deeper end is separate work. Recipes that must be ready before they run — a virtual environment, a live service — are the subject of States and Probes, which proposes states as further execution units on this same structured runner rather than a template-time subprocess facility.

Confidence

The central claim is small enough to test: a scalar interpolation cannot change process structure or argv boundaries. The RFCs plan evidence for it at several strengths. None of that is written yet; what ships is the equivalent work for today's legacy placeholders.

Accessibility and localization