Allow help targets for manifests with build-only Jinja helpers

[leynos]

Problem

netsuke help targets rejects manifests containing Jinja helpers that are not
part of its restricted query surface, even when those helpers occur only in a
recipe that target discovery does not need to execute.

For example, Catnap could select its test runner declaratively at manifest
compile time:

- name: test
  description: Run tests with cargo-nextest or Cargo
  command: >-
    RUSTFLAGS='-D warnings'
    cargo {% if command_available("cargo-nextest") %}nextest run{% else %}test{% endif %}
    --all-targets --all-features

The manifest is valid for a normal build, but netsuke help targets fails
because its restricted renderer rejects command_available(). The equivalent
two-action form using opposing when: command_available(...) expressions has
the same discovery problem.

Catnap therefore has to defer selection to a runtime shell conditional:

https://github.com/leynos/catnap/blob/de453cb63aa030844ef08e1c60d4981b6d25d949/Netsukefile#L18-L23

That workaround is more verbose, less declarative, and unnecessarily couples
a portable manifest decision to shell syntax.

Requirement

netsuke help targets should be able to list action and target metadata when
build-only fields use Jinja helpers that are unavailable in query mode. Target
discovery must not fail merely because a recipe contains
command_available(), env(), or another normal-build helper.

A suitable implementation might avoid rendering recipe-only fields during
metadata discovery. Conditional actions whose when expression uses such a
helper also need a defined discovery policy, such as listing them as
conditional, but the command should not fail wholesale.

Acceptance criteria

• netsuke help targets succeeds for an action whose command contains the
  inline command_available() example above.
• Define and test discovery behaviour for when expressions that use
  build-only helpers.
• Human-readable and JSON target-help output continue to include descriptions.
• Target discovery does not execute recipes or create build outputs.
• Helpers that are intentionally unavailable in query mode are not executed
  merely to render recipe fields.
• Normal build, generate, and manifest-rendering semantics remain
  unchanged.

Related to #551.

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

Skip recipe rendering in ManifestQuery mode so build-only helpers in command/script are never executed during discovery. Drive this with a mode flag threaded from from_str_named into render_manifest.

Convert absent build-only helpers into explicit, classifiable disabled stubs in query mode, and treat a query-disabled helper inside a when expression as a conditional entry rather than a fatal error.

Carry a conditional marker from when expansion through a new typed Target field into HelpEntry, and surface it in text and JSON output with a localised marker.

Preserve build, generate, description rendering, and impure-description rejection semantics unchanged, and lock the behaviour with render, expansion, catalogue, snapshot, and BDD tests.

Design Choices

Design Choice 1: How a conditional marker travels from when evaluation to the catalogue

Options Considered:

1. Add a declared field conditional to Target with #[serde(default)], and inject "conditional": true into the raw map during expansion. The marker deserialises naturally and expands to every resolved name in help_query.rs.
2. Reuse the vars channel (the inject_iteration_vars precedent) by injecting a reserved key, then read and strip it in help_query.rs.

Chosen Option: 1

Rationale: A declared field is explicit, satisfies deny_unknown_fields, expands cleanly per name, and avoids polluting vars that feed recipe rendering and IR.

Design Choice 2: How to classify query-mode "disabled helper" errors without fragile message matching

Options Considered:

1. Centralise both the error construction and its classification in src/stdlib/register.rs, so a single helper produces the error and a single predicate recognises it (checking ErrorKind::InvalidOperation plus the fixed marker text).
2. Introduce a new dedicated ErrorKind.

Chosen Option: 1

Rationale: ErrorKind is non-exhaustive and cannot be extended by us, so a single owned helper plus a single owned predicate keeps one source of truth and follows the existing manifest_query_operation_error precedent.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Skip recipe rendering during metadata discovery

This phase removes the direct cause of the reported failure. Target discovery needs description, name, sources, deps, and order_only_deps, but it does not need rendered recipe content. BuildGraph::from_manifest validates structure and tolerates unrendered recipe text, and its result is discarded during discovery. Skip recipe rendering in query mode so a command that uses command_available() passes without executing any build-only helper.

Task 1: Thread a query-mode flag into the renderer

Give render_manifest a mode flag so it can skip recipe-only rendering.

• Update src/manifest/render.rs so render_manifest, render_target, and render_rule accept a small mode value (for example RenderMode with Full and ManifestQuery, or a boolean skip_recipe).
• When the mode is ManifestQuery, skip the render_recipe call in render_target and render_rule. Render vars, description, name, sources, deps, and order_only_deps unchanged.
• Keep the Full path identical to today so build, generate, and manifest rendering stay unchanged.

Task 2: Supply the mode from the load pipeline

Provide the mode from the single caller of render_manifest.

• Update src/manifest/mod.rs::from_str_named to capture the mode from stdlib_registration before the match consumes it (for example let is_manifest_query = matches!(stdlib_registration, Some(StdlibRegistration::ManifestQuery));).
• Pass that mode into the render_manifest call at the tail of from_str_named.
• Do not change the ordering of stdlib registration, expand_foreach, deserialisation, or rendering.

Task 3: Cover recipe-skip behaviour with tests

Prove that recipes are not rendered in query mode and that build rendering is unchanged.

• Add a case to src/manifest/render_tests.rs that renders a manifest in ManifestQuery mode with a recipe that contains a build-only helper, and asserts rendering succeeds and the recipe text is left unrendered.
• Add a companion case that renders the same manifest in Full mode and asserts recipe rendering still occurs.

🤖 Prompt for AI agents

Implement recipe-rendering skip logic for manifest query mode.

- In `src/manifest/render.rs`, add a small mode value (for example `RenderMode`
with `Full` and `ManifestQuery` variants, or a boolean `skip_recipe`) as a
parameter to `render_manifest`, `render_target`, and `render_rule`.
- When the mode is `ManifestQuery`, skip the `render_recipe` call inside
`render_target` and `render_rule`. Continue to render `vars`, `description`,
`name`, `sources`, `deps`, and `order_only_deps` in all modes.
- Keep the `Full` mode path identical to the current behaviour, so build,
generate, and manifest rendering do not change.
- In `src/manifest/mod.rs::from_str_named`, capture the mode from
`stdlib_registration` before the `match` consumes it (for example `let
is_manifest_query = matches!(stdlib_registration,
Some(StdlibRegistration::ManifestQuery));`), and pass this mode into the
`render_manifest` call at the end of the function. Do not change the ordering of
stdlib registration, `expand_foreach`, deserialisation, or rendering.
- In `src/manifest/render_tests.rs`, add a test case that renders a manifest in
`ManifestQuery` mode with a recipe containing a build-only helper, and assert
that rendering succeeds and the recipe text stays unrendered. Add a companion
test case that renders the same manifest in `Full` mode and asserts recipe
rendering still happens.

Phase 2: Define a discovery policy for when expressions that use build-only helpers

This phase gives a defined, testable answer for conditional entries. Today a when clause that calls command_available() fails in query mode. The policy: when a when expression cannot be resolved in query mode because it uses a helper that is disabled in query mode, keep the entry and mark it conditional instead of failing. In build mode these helpers are registered and evaluate normally, so the policy does not change build behaviour.

Task 1: Make all build-only helpers fail uniformly and classifiably in query mode

Convert absent build-only helpers into explicit, classifiable disabled stubs.

• Update src/stdlib/register.rs::register_disabled_query_helpers to also stub the build-only helpers that are currently absent in query mode, at least command_available, which, and now, and the host-touching filters (size, linecount, hash, digest, realpath, expanduser), each returning manifest_query_operation_error.
• Add one classification predicate next to manifest_query_operation_error (for example is_manifest_query_disabled_error(&minijinja::Error) -> bool) that recognises the fixed ErrorKind::InvalidOperation and the fixed marker text. Keep construction and classification in this one module.
• Keep the hard-coded English message pattern used for the existing disabled stubs; these are manifest-author diagnostics, consistent with the current convention.

Task 2: Treat query-disabled when failures as conditional

Change when evaluation so a query-disabled helper marks the entry conditional rather than failing.

• Update src/manifest/expand.rs so eval_when/when_allows return a small resolution value with three outcomes: include, exclude, and conditional (rather than a bare bool).
• When compiled.eval(...) or the template-render fallback fails, downcast the root cause to minijinja::Error and apply the Task 2.1 predicate. If it matches, return the conditional outcome. Otherwise propagate the error exactly as today.
• Update expand_target so a conditional outcome keeps the entry (for both the foreach and non-foreach paths) and injects the "conditional": true marker into the raw map. An exclude outcome keeps the existing filter-and-count behaviour.
• Because these stubs exist only in query mode, build-mode when evaluation is unaffected.

Task 3: Carry the conditional marker into the typed AST

Let the marker survive deserialisation.

• Update src/ast/target.rs to add a conditional: bool field with #[serde(default)], documented as internal discovery metadata.
• Confirm #[serde(deny_unknown_fields)] still holds and that omitting the key defaults to false.

Task 4: Cover the when policy with expansion tests

Prove conditional retention and marking.

• Extend src/manifest/expand_test_cases/action_condition_cases.rs and target_command_available_cases.rs (or add adjacent cases) to assert that, when a query-disabled stub is present, a when: command_available(...) entry is retained and marked conditional, and that an ordinary false when (for example item != 'skip') is still filtered out.
• Add a case that asserts a genuine unrelated when error (not a query-disabled helper) still propagates as an error.

🤖 Prompt for AI agents

Implement the conditional-entry policy for `when` expressions that call
build-only helpers during query mode.

- In `src/stdlib/register.rs::register_disabled_query_helpers`, stub the
build-only helpers currently absent in query mode: at least `command_available`,
`which`, `now`, and the host-touching filters `size`, `linecount`, `hash`,
`digest`, `realpath`, `expanduser`. Each stub must return
`manifest_query_operation_error`.
- Add one classification predicate next to `manifest_query_operation_error` (for
example `is_manifest_query_disabled_error(&minijinja::Error) -> bool`) that
recognises the fixed `ErrorKind::InvalidOperation` and the fixed marker text.
Keep both the error construction and this predicate in this one module as the
single source of truth. Keep the hard-coded English message pattern used by the
existing disabled stubs.
- In `src/manifest/expand.rs`, change `eval_when`/`when_allows` to return a
three-way resolution value: include, exclude, or conditional, instead of a bare
`bool`. When `compiled.eval(...)` or the template-render fallback fails,
downcast the root cause to `minijinja::Error` and apply the new predicate. If it
matches, return the conditional outcome; otherwise propagate the error exactly
as before.
- Update `expand_target` so a conditional outcome keeps the entry (for both
`foreach` and non-`foreach` paths) and injects `"conditional": true` into the
raw map. An exclude outcome must keep the current filter-and-count behaviour.
Note that these stubs exist only in query mode, so build-mode `when` evaluation
must not change.
- In `src/ast/target.rs`, add a `conditional: bool` field with
`#[serde(default)]`, documented as internal discovery metadata. Confirm
`#[serde(deny_unknown_fields)]` still holds and that omitting the key defaults
to `false`.
- Extend `src/manifest/expand_test_cases/action_condition_cases.rs` and
`target_command_available_cases.rs` (or add adjacent cases) to assert: a `when:
command_available(...)` entry is retained and marked conditional when a
query-disabled stub is present; an ordinary false `when` (for example `item !=
'skip'`) is still filtered out; and a genuine unrelated `when` error (not a
query-disabled helper) still propagates as an error.

Phase 3: Surface conditional entries in help output, localisation, and tests

This phase makes the policy visible and locks in behaviour. The catalogue must show conditional entries in both text and JSON output while continuing to include descriptions.

Task 1: Extend the catalogue model and output

Add the conditional signal to the discovery catalogue and both renderers.

• Update src/runner/help_query.rs so HelpEntry carries a conditional: bool, and so append_target_entries copies target.conditional onto every resolved name.
• Update src/runner/help.rs so HelpEntryJson gains a conditional field (default false, always emitted like default), and so render_text/render_section append a conditional marker analogous to default_marker.
• Keep description rendering and the existing [★ default] marker unchanged.

Task 2: Add localisation for the conditional marker

Follow the existing default-marker localisation pattern.

• Add a new key (for example CLI_HELP_CONDITIONAL_MARKER → cli.help.conditional_marker) to src/localization/keys.rs.
• Add a theme-aware glyph and localised label, and add the key with a value to every locales/*/messages.ftl file in the same change, to satisfy the localisation audit gate.

Task 3: Update snapshots and add discovery tests

Re-record snapshots and add fixtures that exercise the new behaviour.

• Update the affected snapshots under src/snapshots/help_targets/ (json_catalogue, text_catalogue, accessible_catalogue, localized_catalogue_es_es) for the added JSON field and the new text marker.
• Add an rstest in tests/runner_help_targets_tests/catalogue.rs that runs help targets on the inline command-with-command_available() example from the ticket and asserts success, that stdout still contains the descriptions, and that no build outputs and no .netsuke directory are created.
• Add an rstest that runs help targets on the two-action opposing when: command_available(...) form and asserts both actions are listed and marked conditional, with descriptions present, and no side effects.
• Extend the unit/proptest coverage in src/runner/help_tests.rs so catalogue construction preserves the conditional flag alongside order, names, descriptions, and defaults.
• Add one Gherkin scenario to tests/features/help_targets.feature, backed by tests/bdd/steps/help_targets.rs, that lists a conditional action successfully.

🤖 Prompt for AI agents

Surface the conditional flag in help output, add localisation, and lock
behaviour with tests.

- In `src/runner/help_query.rs`, add a `conditional: bool` field to `HelpEntry`,
and update `append_target_entries` to copy `target.conditional` onto every
resolved name.
- In `src/runner/help.rs`, add a `conditional` field to `HelpEntryJson` (default
`false`, always emitted, following the `default` field's pattern), and update
`render_text`/`render_section` to append a conditional marker analogous to
`default_marker`. Keep description rendering and the existing `[★ default]`
marker unchanged.
- In `src/localization/keys.rs`, add a new key (for example
`CLI_HELP_CONDITIONAL_MARKER` mapped to `cli.help.conditional_marker`). Add a
theme-aware glyph and localised label, and add the key with a value to every
`locales/*/messages.ftl` file in the same change, to satisfy the localisation
audit gate.
- Update the affected snapshots under `src/snapshots/help_targets/`
(`json_catalogue`, `text_catalogue`, `accessible_catalogue`,
`localized_catalogue_es_es`) to include the added JSON field and the new text
marker.
- Add an rstest in `tests/runner_help_targets_tests/catalogue.rs` that runs
`help targets` on the inline `command`-with-`command_available()` example from
the ticket, asserting success, that stdout still contains the descriptions, and
that no build outputs and no `.netsuke` directory are created.
- Add an rstest that runs `help targets` on the two-action opposing `when:
command_available(...)` form, asserting both actions are listed and marked
conditional, with descriptions present, and no side effects.
- Extend the unit/proptest coverage in `src/runner/help_tests.rs` so catalogue
construction preserves the conditional flag alongside order, names,
descriptions, and defaults.
- Add one Gherkin scenario to `tests/features/help_targets.feature`, backed by
`tests/bdd/steps/help_targets.rs`, that lists a conditional action successfully.

Research

netsuke help targets runs a pure query pipeline. src/runner/help_query.rs loads the manifest through crate::manifest::from_path_for_manifest_query, which selects ManifestLoadMode::ManifestQuery. This maps to StdlibRegistration::ManifestQuery in src/manifest/mod.rs::from_str_named. In query mode src/stdlib/register.rs::register_manifest_query installs a restricted Jinja surface: it allowlists lexical path filters, collection filters, and timedelta, and it stubs env, glob, fetch, shell, grep, and contents with manifest_query_operation_error. Build-only helpers such as command_available, which, and now are simply not registered, so they raise a generic MiniJinja "unknown function" error.

from_str_named parses YAML, registers helpers, expands foreach/when on the raw JSON tree (src/manifest/expand.rs), deserialises into the typed AST (src/ast/target.rs, src/ast/mod.rs), then renders every field through src/manifest/render.rs::render_manifest. render_target renders vars, description, name, sources, deps, order_only_deps, and finally the recipe. BuildGraph::from_manifest validates structure only and its result is discarded during discovery. The catalogue (HelpEntry) is built purely from name, description, and defaults. The when filter in expand.rs is destructive: filtered entries are dropped and no conditional marker survives.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement recipe-rendering skip logic for manifest query mode.

- In `src/manifest/render.rs`, add a small mode value (for example `RenderMode`
with `Full` and `ManifestQuery` variants, or a boolean `skip_recipe`) as a
parameter to `render_manifest`, `render_target`, and `render_rule`.
- When the mode is `ManifestQuery`, skip the `render_recipe` call inside
`render_target` and `render_rule`. Continue to render `vars`, `description`,
`name`, `sources`, `deps`, and `order_only_deps` in all modes.
- Keep the `Full` mode path identical to the current behaviour, so build,
generate, and manifest rendering do not change.
- In `src/manifest/mod.rs::from_str_named`, capture the mode from
`stdlib_registration` before the `match` consumes it (for example `let
is_manifest_query = matches!(stdlib_registration,
Some(StdlibRegistration::ManifestQuery));`), and pass this mode into the
`render_manifest` call at the end of the function. Do not change the ordering of
stdlib registration, `expand_foreach`, deserialisation, or rendering.
- In `src/manifest/render_tests.rs`, add a test case that renders a manifest in
`ManifestQuery` mode with a recipe containing a build-only helper, and assert
that rendering succeeds and the recipe text stays unrendered. Add a companion
test case that renders the same manifest in `Full` mode and asserts recipe
rendering still happens.
===============================================================================

Task: 2

Implement the conditional-entry policy for `when` expressions that call
build-only helpers during query mode.

- In `src/stdlib/register.rs::register_disabled_query_helpers`, stub the
build-only helpers currently absent in query mode: at least `command_available`,
`which`, `now`, and the host-touching filters `size`, `linecount`, `hash`,
`digest`, `realpath`, `expanduser`. Each stub must return
`manifest_query_operation_error`.
- Add one classification predicate next to `manifest_query_operation_error` (for
example `is_manifest_query_disabled_error(&minijinja::Error) -> bool`) that
recognises the fixed `ErrorKind::InvalidOperation` and the fixed marker text.
Keep both the error construction and this predicate in this one module as the
single source of truth. Keep the hard-coded English message pattern used by the
existing disabled stubs.
- In `src/manifest/expand.rs`, change `eval_when`/`when_allows` to return a
three-way resolution value: include, exclude, or conditional, instead of a bare
`bool`. When `compiled.eval(...)` or the template-render fallback fails,
downcast the root cause to `minijinja::Error` and apply the new predicate. If it
matches, return the conditional outcome; otherwise propagate the error exactly
as before.
- Update `expand_target` so a conditional outcome keeps the entry (for both
`foreach` and non-`foreach` paths) and injects `"conditional": true` into the
raw map. An exclude outcome must keep the current filter-and-count behaviour.
Note that these stubs exist only in query mode, so build-mode `when` evaluation
must not change.
- In `src/ast/target.rs`, add a `conditional: bool` field with
`#[serde(default)]`, documented as internal discovery metadata. Confirm
`#[serde(deny_unknown_fields)]` still holds and that omitting the key defaults
to `false`.
- Extend `src/manifest/expand_test_cases/action_condition_cases.rs` and
`target_command_available_cases.rs` (or add adjacent cases) to assert: a `when:
command_available(...)` entry is retained and marked conditional when a
query-disabled stub is present; an ordinary false `when` (for example `item !=
'skip'`) is still filtered out; and a genuine unrelated `when` error (not a
query-disabled helper) still propagates as an error.
===============================================================================

Task: 3

Surface the conditional flag in help output, add localisation, and lock
behaviour with tests.

- In `src/runner/help_query.rs`, add a `conditional: bool` field to `HelpEntry`,
and update `append_target_entries` to copy `target.conditional` onto every
resolved name.
- In `src/runner/help.rs`, add a `conditional` field to `HelpEntryJson` (default
`false`, always emitted, following the `default` field's pattern), and update
`render_text`/`render_section` to append a conditional marker analogous to
`default_marker`. Keep description rendering and the existing `[★ default]`
marker unchanged.
- In `src/localization/keys.rs`, add a new key (for example
`CLI_HELP_CONDITIONAL_MARKER` mapped to `cli.help.conditional_marker`). Add a
theme-aware glyph and localised label, and add the key with a value to every
`locales/*/messages.ftl` file in the same change, to satisfy the localisation
audit gate.
- Update the affected snapshots under `src/snapshots/help_targets/`
(`json_catalogue`, `text_catalogue`, `accessible_catalogue`,
`localized_catalogue_es_es`) to include the added JSON field and the new text
marker.
- Add an rstest in `tests/runner_help_targets_tests/catalogue.rs` that runs
`help targets` on the inline `command`-with-`command_available()` example from
the ticket, asserting success, that stdout still contains the descriptions, and
that no build outputs and no `.netsuke` directory are created.
- Add an rstest that runs `help targets` on the two-action opposing `when:
command_available(...)` form, asserting both actions are listed and marked
conditional, with descriptions present, and no side effects.
- Extend the unit/proptest coverage in `src/runner/help_tests.rs` so catalogue
construction preserves the conditional flag alongside order, names,
descriptions, and defaults.
- Add one Gherkin scenario to `tests/features/help_targets.feature`, backed by
`tests/bdd/steps/help_targets.rs`, that lists a conditional action successfully.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!