Plan: Make Jinja command helpers match the documented ergonomics (3.14.8)

[leynos]

Summary

This branch carries the pre-implementation execution plan for roadmap task
3.14.8, which reconciles the Jinja template helpers Netsuke documents with the
ones it actually registers. No production code changes: the branch adds one
document and authorizes the implementation described in it, subject to approval.

Roadmap task: (3.14.8)

Execplan:
docs/execplans/3-14-8-jinja-command-helpers-to-match-documented-ergonomics.md

The task closes four documentation debts: env(name) gains the default=
keyword argument its design contract already specifies; the shell_escape
filter the user guide describes as "not implemented in beta3" is resolved; and
shell_join and compact are implemented so that a manifest author can build
an optional RUSTFLAGS value without reaching for ${RUSTFLAGS:+$RUSTFLAGS },
which is a construct the Ninja backend has to escape around and which does not
work at all on Windows.

Two deviations that need a decision

Both are recorded in the plan's
Decision log
and both were confirmed by the requester before drafting.

D1 — the helper ships as shell_quote, not shell_escape. RFC 0006 §13.3
states that roadmap 3.14.8 "owns the shell-quoting capability and ships first"
and contributes "the canonical name shell_quote and the dialect argument;
the roadmap task should adopt them so the two do not diverge". Roadmap 6.8.3
repeats this. Shipping the superseded name would force a public rename later.

D2 — dialect accepts sh and powershell, defaulting to the active
recipe shell. RFC 0006 §8.9 specifies sh as the only dialect, on the stated
premise that it matches "the single shell-quote feature Netsuke enables". That
premise does not hold: Netsuke runs Windows recipes under Windows PowerShell,
not cmd.exe and not a POSIX shell, and
src/ir/cmd_interpolate/mod.rs::quote_path already implements a second dialect
for exactly that case. An sh-only filter would emit POSIX quoting into a
PowerShell recipe, which is a silent injection-safety defect in the helper whose
stated purpose is to prevent one. RFC 0006 §§8.9 and 13.3 are amended as part of
the work.

Review walkthrough

• Start with
  Purpose / big picture
  for the manifest a user can write afterwards and the four things they can
  observe. Note the two load-bearing details of that example: the interpolation
  sits in unquoted position, and the recipe uses ; rather than &&, because
  Windows PowerShell 5.1 has no &&.
• Then
  The quoting that already exists,
  which inventories five encoders in the tree today and identifies the single
  one this work extracts. Constraint 4 becomes a clippy.toml gate rather than
  prose.
• The
  Threat model
  names the attacker the design document leaves implicit. shell_quote is a
  safe primitive, not an enforced control: it protects a trusted manifest that
  interpolates an attacker-influenced value from env(), glob(), fetch(),
  or shell(). It is opt-in and nothing warns when it is omitted, so the
  unqualified phrase "non-negotiable security feature" is amended.
• The
  Verification plan
  carries thirteen obligations, each with a negative control. The strongest is a
  property test round-tripping generated values through a real /bin/sh; Verus
  and Kani are excluded with stated reasons rather than omitted.
• EP-M4
  explains why filter registration and runner plumbing are one milestone rather
  than two. Splitting them would ship a state where, on a Windows host with
  NETSUKE_WINDOWS_SHELL=bash, the filters quote for PowerShell while the
  recipe runs under Bash — and PowerShell's doubled single quote is valid
  POSIX syntax, so a'b silently becomes ab with no error anywhere.
• Finish with the
  Risks,
  particularly R9: the in-flight issue-651 branch restructures the same
  manifest files, so the plan names its new module to converge with that work
  rather than conflict with it.

How the plan was produced

Reconnaissance ran as a team of read-only agents over the manifest loader, the
three stdlib registration surfaces, the recipe-shell contract, the 35-catalogue
localization gate, and the executed-documentation machinery. The draft was then
stress-tested by a six-lens community-of-experts panel — structural integrity,
alternative futures, contracts, failure modes, cost, and long-term viability.

That review falsified four claims in the first draft, each verified before being
acted on:

• Value::try_iter() is not a sequence check. It accepts none and undefined
  as empty, a string as its characters, and a map as its keys, so
  {{ 'abc' | shell_join }} would have quoted three characters into a command
  line. The helpers now gate on ValueKind.
• Kwargs::get::<Option<String>> does not raise on a type mismatch; it
  stringifies, so env('A', default=['a','b']) would have pasted the JSON
  fragment ["a", "b"] into a recipe — the silent coercion RFC 0006 §6.6
  forbids.
• The plan's own acceptance transcript placed the interpolation inside double
  quotes, where the quoting inserts literal quote characters and corrupts the
  value. None of the original obligations would have caught it, because each
  exercised the filter in isolation.
• quote_path is in src/ir/cmd_interpolate/mod.rs, not substitution.rs, so
  an implementer following the plan literally would have edited the wrong file.

The panel's preferred simplification — dropping dialect entirely, which would
cut eleven message keys to one — is preserved as decision D11 with its full
trade-off analysis. It is cheap to adopt before EP-M4 and expensive afterwards,
so it is worth settling at approval time.

Validation

Documentation-only branch, so only the Markdown gates apply. make test,
make lint, and make typecheck were deliberately not run: there is no Rust
change to gate.

• make check-fmt: pass — cargo fmt --check and ruff format --check clean
• make nixie: pass — all Mermaid diagrams validated
• make markdownlint: pass — markdownlint-cli2 linted 133 files with 0
  errors, and its spelling prerequisite (the typos gate plus the 34-case
  typos_rollout suite) ran to completion. It failed twice first, both times
  in that prerequisite and both times on this branch's own file:
  both times on this branch's own new file. typos enforces en-GB-oxendict
  spelling and rejected hand-written (wanting handwritten), then read the
  bare acronym AX in the AX-1..AX-5 axiom labels as a misspelling of
  AXE. Fixed in c53b7af9 and f574e857 by correcting the spelling and
  spelling the labels out as AXIOM-n, rather than by widening the
  accepted-word list.

The expected quoting strings throughout the plan are derived from
shell-quote-0.7.2's escape_chars and Char::from, then confirmed against a
real /bin/sh, rather than guessed. Two results are counter-intuitive and are
called out so a reviewer does not "correct" them: quoting opens and closes
around runs, so a b becomes a' b'; and the equals sign is not inert, so
target-cpu=native becomes target-cpu'=native'.

Notes

The plan is DRAFT and must be approved before implementation begins. On
completion the implementor marks roadmap 3.14.8 done and adds a note to 6.8.3
recording that this task delivered the canonical name and the dialect argument.

References

• Lody session: https://lody.ai/leynos/sessions/c72b2360-e95a-451a-b637-1e84cf3eb4b8

Summary by Sourcery

Add a draft execution plan for implementing the documented Jinja command helpers and aligning their cross-platform shell behavior, registration, testing, and documentation.

Enhancements:

• Add a draft execution plan for reconciling documented Jinja command helpers with the supported template ergonomics across environment defaults, collection handling, and shell recipe text.
• Define the cross-platform shell quoting contract, including the canonical shell_quote name, sh and PowerShell dialects, recipe-shell integration, security boundaries, and localization requirements.
• Specify milestone-based implementation, testing, documentation, and acceptance work for the planned helpers without changing production code.

Documentation:

• Document the planned helper behavior, design decisions, threat model, verification obligations, implementation milestones, and roadmap/RFC reconciliation.

Tests:

• Define comprehensive unit, property, integration, BDD, query-surface, and executed-documentation verification for the future implementation.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's Guide

This documentation-only PR adds a DRAFT ExecPlan for implementing the documented Jinja command helpers, with explicit API decisions, cross-platform quoting safety, registration and runner-plumbing design, localization/documentation work, and detailed staged verification. Production behavior is unchanged and implementation is gated on plan approval.

Sequence diagram for dialect-aware recipe rendering

sequenceDiagram
    participant Manifest
    participant Loader as ManifestLoader
    participant Jinja as JinjaEnvironment
    participant Config as StdlibConfig
    participant Runner
    participant IR
    participant Ninja as NinjaGenerator
    participant Shell as RecipeInterpreter

    Manifest->>Loader: from_str_with_env_and_config
    Loader->>Jinja: render template helpers
    Jinja->>Config: dialect()
    Config-->>Jinja: ShellDialect
    Jinja-->>Loader: rendered recipe text
    Loader->>Runner: resolve recipe shell
    Runner->>IR: interpolate_command_with_bindings
    IR->>Ninja: generate recipe text
    Ninja->>Shell: execute dialect-compatible command

Loading

Flow diagram for optional RUSTFLAGS construction

flowchart TD
    Start[base_flags and env RUSTFLAGS default empty] --> Compact[compact]
    Compact --> Join[join with one space]
    Join --> Quote[shell_quote with explicit dialect]
    Quote --> Recipe[Unquoted recipe interpolation]
    Recipe --> Build[Generated Ninja recipe]
    Build --> Cargo[cargo receives one intact RUSTFLAGS word]

Loading

File-Level Changes

Change	Details	Files
Adds a draft execution plan for reconciling documented Jinja helper behavior with the eventual implementation.	Defines env(default=...), compact, shell_quote, and shell_join contracts and registration surfaces. Specifies shell-dialect handling, including the shell_quote name and sh/powershell deviation decisions. Lays out shared quoting extraction, runner-shell plumbing, localization updates, documentation changes, and ADR/roadmap reconciliation. Provides threat modeling, milestone sequencing, integration/property-test obligations, negative controls, and acceptance gates.	docs/execplans/3-14-8-jinja-command-helpers-to-match-documented-ergonomics.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[codescene-access]

No quality gates enabled for this code.