Runner path types: decide between std::path and camino for the Ninja invocation chain

[leynos]

Observation

The Ninja request API (NinjaBuildRequest, NinjaToolRequest),
configure_ninja_base, and path_with_dir_prepended take
&std::path::Path, where the repository generally prefers camino's
Utf8Path. Raised in review of #497.

Why it was not changed there

Three reasons, in increasing order of weight.

It would be inconsistent if done partially. run_ninja and
run_ninja_tool already take &Path on main; the _with variants added by
#497 mirror them deliberately. Migrating only the new API leaves one module
with two conventions.

It is out of scope for that PR. #497 removes process-environment mutation
from the runner. Path types are orthogonal, and folding a signature migration
into it would bury the change reviewers need to see.

Done fully, it is a behavioural decision rather than a refactor. The values
flow in from Cli.file and Cli.directory, both PathBuf from clap, and from
resolve_ninja_program, which converts down from Utf8PathBuf to PathBuf
at line 78 — the codebase already widens deliberately at this boundary.
Utf8Path cannot represent a non-UTF-8 path, so migrating the whole chain
makes a build file or working directory with a non-UTF-8 name unrepresentable
rather than merely awkward. That may well be the right call, but it needs
deciding, not assuming.

Suggested work

1. Decide whether non-UTF-8 build-file and working-directory paths are
   supported. If they are not, say so explicitly and fail early with a clear
   diagnostic rather than at an arbitrary later point.
2. If they are unsupported, migrate the whole chain together —
   Cli.file, Cli.directory, resolve_ninja_program, the request types,
   configure_ninja_base, and path_with_dir_prepended — so one convention
   holds across the runner.
3. Keep OsStr/OsString for environment-variable payloads, which genuinely
   need not be UTF-8.

Related: #497.

[coderabbitai]

🔗 Related PRs

#323 - Document Ninja executable override (#83) [merged]
#448 - Remove ambient fs [merged]
#468 - Rename internal canonicalize identifiers (#408) [merged]
#478 - Narrow no_std_fs_operations exemptions with Whitaker module-path suppressions (#462) [merged]
#497 - Stop the mock environment mutating the real process environment (#490) [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Decide against non-UTF-8 build-file and working-directory paths, and record the decision in a new ADR and the CHANGELOG.
• Migrate the whole Ninja invocation chain to camino: request types, configure_ninja_base, canonicalize_utf8_path, resolve_ninja_program, the adapter, and the CLI file/directory fields.
• Reject non-UTF-8 file/directory input early with a localised diagnostic at the CLI and post-merge seams, and remove the now-redundant downstream conversions.
• Keep OsStr/OsString for environment-variable payloads, and treat path_with_dir_prepended as absent (no action required).

Design Choices

Design Choice 1: Decide whether non-UTF-8 build-file and working-directory paths need support

Options Considered:

1. Support non-UTF-8 paths. Keep std::path::Path on the chain and do not migrate.
2. Do not support non-UTF-8 paths. Migrate the chain to camino and fail early with a clear diagnostic.

Chosen Option: 2

Rationale: The ticket requires an explicit decision. Utf8Path cannot represent a non-UTF-8 path, so migrating the chain makes such paths unrepresentable. Pick Option 2: it matches the pervasive camino convention (AGENTS.md, docs/netsuke-design.md, ADR-005/ADR-008 precedent) and the ticket's own suggested direction.

Design Choice 2: Decide how the CLI boundary exposes the path type and produces the diagnostic

Options Considered:

1. Change Cli.file/Cli.directory to Utf8PathBuf and rely on clap's FromStr parser. This is simplest, but it emits clap's generic "invalid UTF-8" error, not a localised diagnostic.
2. Change the fields to Utf8PathBuf, attach a custom OsStr-based value parser that emits a localised non-UTF-8 diagnostic, mirror the change in CliConfig.file, and add a post_merge check for config/env sources.

Chosen Option: 2

Rationale: Cli.file/CliConfig.file must stay serde-shape-compatible for the OrthoConfig merge. A direct field-type change interacts with clap decoding and with config/env sources. Pick Option 2: it delivers the clear, localised, early diagnostic that ticket item 1 requires, and it reuses the existing LocalizedValueParser/post_merge patterns in src/cli/.

💡 User Tips

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

Implementation Steps

Phase 1: Record the decision

Document the decision so future work has one authoritative source. Confirm the status of the missing helper named in the ticket.

Task 1: Write an ADR for UTF-8 paths on the Ninja invocation chain

State the decision, rationale, and consequences in a new ADR.

• Create a new ADR file under docs/ that follows the template used by docs/adr-005-typed-which-resolve-error.md and docs/adr-008-environment-seam-taxonomy.md (Status, Date, Context, Decision, Rationale, Consequences, Alternatives, Implementation references).
• State the decision: the Ninja invocation chain requires UTF-8 paths; non-UTF-8 build-file and working-directory paths are unsupported and rejected early.
• Cite the informal convention in AGENTS.md/CRUSH.md, the design rationale in docs/netsuke-design.md, and the error-wrapping precedent (ResolveError, RUNNER_*_UTF8, MANIFEST_*_NON_UTF8 keys).
• Note the deliberate std::path carve-out in src/cli/discovery_paths.rs and record that environment-variable payloads stay OsStr/OsString.
• Record that path_with_dir_prepended does not exist; it maps to the removed prepend_dir_to_path, so it needs no migration.

Task 2: Add a CHANGELOG entry

Record the user-visible behavioural change.

• Update CHANGELOG.md to note that the runner now requires UTF-8 build-file and working-directory paths and reports a clear diagnostic when a path is not valid UTF-8.

🤖 Prompt for AI agents

Implement Phase 1: record the decision to require UTF-8 paths on the Ninja
invocation chain.

- Create a new ADR file under `docs/`, following the structure and headings used
by `docs/adr-005-typed-which-resolve-error.md` and
`docs/adr-008-environment-seam-taxonomy.md` (Status, Date, Context, Decision,
Rationale, Consequences, Alternatives, Implementation references).
- State clearly in the ADR: the Ninja invocation chain requires UTF-8 paths;
non-UTF-8 build-file and working-directory paths are unsupported and get
rejected early.
- Cite the informal `camino` convention in `AGENTS.md`/`CRUSH.md`, the design
rationale in `docs/netsuke-design.md`, and the error-wrapping precedent
(`ResolveError`, `RUNNER_*_UTF8`, `MANIFEST_*_NON_UTF8` keys).
- Note the deliberate `std::path` carve-out in `src/cli/discovery_paths.rs`, and
record that environment-variable payloads stay `OsStr`/`OsString`.
- Record explicitly that `path_with_dir_prepended` does not exist in the
codebase (it maps to the already-removed `prepend_dir_to_path`), so no migration
action is needed for it.
- Update `CHANGELOG.md` with an entry stating that the runner now requires UTF-8
build-file and working-directory paths, and reports a clear diagnostic when a
path is not valid UTF-8.

Phase 2: Migrate the internal Ninja invocation chain to camino

Move the request types and the process layer onto camino uniformly. Keep std::path only at the exact std::process::Command call boundary, where conversion is lossless.

Task 1: Migrate the request types

Change the two path fields on the request structs to camino.

• Update src/runner/process/request.rs to change NinjaBuildRequest.program and NinjaBuildRequest.build_file to &'a Utf8Path, and the same two fields on NinjaToolRequest.
• Leave NinjaProcessOptions.working_dir unchanged; it is already Option<Utf8PathBuf>.
• Leave BuildTargets, CommandEnv, and StderrMode unchanged; targets are opaque Strings and env payloads stay OsStr/OsString.

Task 2: Simplify canonicalisation to take a UTF-8 path

Remove the redundant fallible entry conversion now that callers already hold UTF-8.

• Update src/runner/process/paths.rs so canonicalize_utf8_path accepts &Utf8Path instead of &Path.
• Delete the initial Utf8Path::from_path(...).ok_or_else(...) guard and its "not valid UTF-8" error branch; the helpers already operate on &Utf8Path.

Task 3: Update configure and process layers

Feed UTF-8 paths through configuration and convert to std::path only at the Command boundary.

• Update src/runner/process/configure.rs so configure_ninja_base takes build_file: &Utf8Path; remove the working_dir.as_std_path() round-trip and call canonicalize_utf8_path directly on the Utf8Path.
• Convert to std::path with as_std_path() only where -f <build_file> and current_dir reach std::process::Command.
• Update src/runner/process/mod.rs (run_ninja_with, run_ninja_tool_with, run_ninja_with_status, run_ninja_tool_with_status, and the run_ninja_*_internal chain) to build the Command from a Utf8Path program via as_std_path(); update the embedded doctests to construct requests with Utf8Path values.

Task 4: Return UTF-8 from the Ninja program resolver

Remove the deliberate down-conversion at the public boundary.

• Update src/runner/process/ninja_program.rs so the public resolve_ninja_program returns Utf8PathBuf (fold it into resolve_ninja_program_utf8, or make the public entry return the UTF-8 type and remove the .into() PathBuf conversion).
• Keep the existing non-UTF-8 NETSUKE_NINJA override behaviour: ignore the override and fall back to NINJA_PROGRAM with the existing tracing::debug! event.

Task 5: Update the CLI-facing runner adapter and orchestration

Propagate the UTF-8 types through the adapter and the request construction sites.

• Update src/runner/ninja_process_adapter.rs so run_ninja and run_ninja_tool accept program: &Utf8Path and build_file: &Utf8Path; the existing working_dir conversion in ninja_process_options stays.
• Update src/runner/mod.rs (handle_build, handle_ninja_tool, and the RunContext/context.ninja_program type) so the resolved program and the generated temp build-file path are carried as Utf8Path/Utf8PathBuf.
• Update src/runner/process/file_io.rs (or the temp-file helper create_temp_ninja_file) if it returns a std::path type, so the generated build-file path is available as Utf8Path.

🤖 Prompt for AI agents

Implement Phase 2: migrate the internal Ninja invocation chain to `camino`,
keeping `std::path` only at the exact `std::process::Command` call boundary
where conversion is lossless.

- In `src/runner/process/request.rs`, change `NinjaBuildRequest.program` and
`NinjaBuildRequest.build_file` to `&'a Utf8Path`, and change the same two fields
on `NinjaToolRequest`. Leave `NinjaProcessOptions.working_dir` unchanged
(already `Option<Utf8PathBuf>`). Leave `BuildTargets`, `CommandEnv`, and
`StderrMode` unchanged.
- In `src/runner/process/paths.rs`, change `canonicalize_utf8_path` to accept
`&Utf8Path` instead of `&Path`. Delete the initial
`Utf8Path::from_path(...).ok_or_else(...)` guard and its "not valid UTF-8" error
branch, since callers already hold UTF-8.
- In `src/runner/process/configure.rs`, change `configure_ninja_base` to take
`build_file: &Utf8Path`. Remove the `working_dir.as_std_path()` round-trip and
call `canonicalize_utf8_path` directly on the `Utf8Path`. Convert to `std::path`
with `as_std_path()` only where `-f <build_file>` and `current_dir` reach
`std::process::Command`.
- In `src/runner/process/mod.rs`, update `run_ninja_with`,
`run_ninja_tool_with`, `run_ninja_with_status`, `run_ninja_tool_with_status`,
and the `run_ninja_*_internal` chain to build the `Command` from a `Utf8Path`
program via `as_std_path()`. Fix the embedded doctests to construct requests
with `Utf8Path` values.
- In `src/runner/process/ninja_program.rs`, make the public
`resolve_ninja_program` return `Utf8PathBuf`. Fold it into
`resolve_ninja_program_utf8`, or make the public entry return the UTF-8 type
directly and remove the `.into()` `PathBuf` conversion. Keep the existing
non-UTF-8 `NETSUKE_NINJA` override behaviour: ignore the override, fall back to
`NINJA_PROGRAM`, and keep the existing `tracing::debug!` event.
- In `src/runner/ninja_process_adapter.rs`, change `run_ninja` and
`run_ninja_tool` to accept `program: &Utf8Path` and `build_file: &Utf8Path`.
Keep the existing `working_dir` conversion in `ninja_process_options` unchanged.
- In `src/runner/mod.rs`, update `handle_build`, `handle_ninja_tool`, and the
`RunContext`/`context.ninja_program` type so the resolved program and the
generated temp build-file path are carried as `Utf8Path`/`Utf8PathBuf`.
- In `src/runner/process/file_io.rs` (or the temp-file helper
`create_temp_ninja_file`), update the return type if it currently uses
`std::path`, so the generated build-file path is available as `Utf8Path`.

Phase 3: Migrate the CLI boundary and add the early diagnostic

Change the CLI field types, and reject non-UTF-8 file/directory values early with a localised message. Cover CLI, config-file, and environment sources.

Task 1: Declare the camino serde feature explicitly

Make the build-graph dependency explicit rather than incidental.

• Update Cargo.toml to request camino's serde feature (features = ["serde1"]) for the main crate, because CliConfig will serialise/deserialise a Utf8PathBuf field.

Task 2: Change the CLI and config field types

Move the path fields to camino, keeping the two structs serde-shape-compatible.

• Update src/cli/command.rs so Cli.file becomes Utf8PathBuf and Cli.directory becomes Option<Utf8PathBuf>.
• Update src/cli/config.rs so CliConfig.file becomes Utf8PathBuf and default_manifest_path() returns Utf8PathBuf::from("Netsukefile").
• Keep directory CLI-only; it has no CliConfig counterpart.

Task 3: Add an early, localised UTF-8 diagnostic for file and directory

Reject non-UTF-8 CLI values at parse time and non-UTF-8 merged values at post-merge.

• Add a custom value parser in src/cli/parser.rs (with a helper in src/cli/parsing.rs) that reads the raw &OsStr for --file and --directory, converts it to Utf8PathBuf, and returns a localised error on failure. Follow the existing LocalizedValueParser pattern used for jobs/locale/scheme.
• Add a check in CliConfig::post_merge (src/cli/config.rs) that rejects a non-UTF-8 file value arriving from config files or environment variables, using validation.rs::validation_error.
• Add localisation keys to locales/en-US/messages.ftl in the established style, for example cli.file.non_utf8 = Manifest path '{ $path }' is not valid UTF-8. and cli.directory.non_utf8 = Working directory path '{ $path }' is not valid UTF-8.; reuse runner.manifest.path_utf8/runner.manifest.directory_utf8 if their wording already fits.

Task 4: Remove now-redundant downstream conversions

Delete the per-call-site conversions that the new field types make unnecessary.

• Update src/runner/path_helpers.rs (resolve_manifest_path) to consume Cli.file/Cli.directory as camino directly and drop the Utf8PathBuf::from_path_buf conversions and their RUNNER_MANIFEST_PATH_UTF8/RUNNER_MANIFEST_DIR_UTF8 branches, unless a branch is still reachable from a std::path source.
• Update src/runner/dyndep_publication.rs (open_effective_dir) and src/runner/ninja_process_adapter.rs (ninja_process_options) to consume Cli.directory as camino directly and drop the now-dead conversions.
• Retire the localisation keys that become unreachable, and remove them from locales/en-US/messages.ftl; keep any key still used by a reachable branch.

🤖 Prompt for AI agents

Implement Phase 3: migrate the CLI boundary to `camino` and add an early,
localised diagnostic for non-UTF-8 `file`/`directory` values, covering CLI,
config-file, and environment sources.

- In `Cargo.toml`, request `camino`'s serde feature (`features = ["serde1"]`)
for the main crate, since `CliConfig` will serialise/deserialise a `Utf8PathBuf`
field.
- In `src/cli/command.rs`, change `Cli.file` to `Utf8PathBuf` and
`Cli.directory` to `Option<Utf8PathBuf>`.
- In `src/cli/config.rs`, change `CliConfig.file` to `Utf8PathBuf` and change
`default_manifest_path()` to return `Utf8PathBuf::from("Netsukefile")`. Keep
`directory` as CLI-only; it has no `CliConfig` counterpart.
- Add a custom value parser in `src/cli/parser.rs` (with a helper in
`src/cli/parsing.rs`) that reads the raw `&OsStr` for `--file` and
`--directory`, converts it to `Utf8PathBuf`, and returns a localised error on
failure. Follow the existing `LocalizedValueParser` pattern used for
`jobs`/`locale`/`scheme`.
- Add a check in `CliConfig::post_merge` (`src/cli/config.rs`) that rejects a
non-UTF-8 `file` value coming from config files or environment variables, using
`validation.rs::validation_error`.
- Add localisation keys to `locales/en-US/messages.ftl` in the established
style, for example `cli.file.non_utf8 = Manifest path '{ $path }' is not valid
UTF-8.` and `cli.directory.non_utf8 = Working directory path '{ $path }' is not
valid UTF-8.`. Reuse
`runner.manifest.path_utf8`/`runner.manifest.directory_utf8` if their wording
already fits.
- In `src/runner/path_helpers.rs` (`resolve_manifest_path`), consume
`Cli.file`/`Cli.directory` as `camino` directly, and drop the
`Utf8PathBuf::from_path_buf` conversions and their
`RUNNER_MANIFEST_PATH_UTF8`/`RUNNER_MANIFEST_DIR_UTF8` branches, unless a branch
stays reachable from a `std::path` source.
- In `src/runner/dyndep_publication.rs` (`open_effective_dir`) and
`src/runner/ninja_process_adapter.rs` (`ninja_process_options`), consume
`Cli.directory` as `camino` directly and drop the now-dead conversions.
- Retire localisation keys that become unreachable, and remove them from
`locales/en-US/messages.ftl`; keep any key still used by a reachable branch.

Phase 4: Update tests and fixtures

Bring the test surface in line with the new field types. The migration touches every request-construction site.

Task 1: Update process-layer unit tests

Convert request literals to camino.

• Update src/runner/process/configure.rs tests (build_configuration_preserves_argument_order, tool_configuration_preserves_argument_order), src/runner/process/tests.rs, src/runner/process/exit_status_tests.rs, and src/runner/process/public_ninja_execution_tests.rs to build program/build_file as Utf8Path/Utf8PathBuf, converting tempfile paths with Utf8Path::from_path/Utf8PathBuf::from_path_buf.

Task 2: Update integration, BDD, and UI fixtures

Convert the remaining request-construction and CLI sites.

• Update tests/bdd/steps/process.rs, tests/stderr_routing_tests.rs, tests/env_path_tests.rs, and the trybuild fixture tests/ui/command_env_embedder_pass.rs to use camino for program/build_file.
• Update any CLI-parsing tests that assert Cli.file/Cli.directory types or defaults.

Task 3: Add a test for the early diagnostic

Prove the fail-early behaviour on non-UTF-8 input.

• Add a test (near the CLI parsing tests) that passes a non-UTF-8 --file/--directory value and asserts the new localised diagnostic and an early, non-panicking failure.

🤖 Prompt for AI agents

Implement Phase 4: update tests and fixtures so the test surface matches the new
`camino` field types, and add a test proving the fail-early diagnostic.

- Update `src/runner/process/configure.rs` tests
(`build_configuration_preserves_argument_order`,
`tool_configuration_preserves_argument_order`), `src/runner/process/tests.rs`,
`src/runner/process/exit_status_tests.rs`, and
`src/runner/process/public_ninja_execution_tests.rs` to build
`program`/`build_file` as `Utf8Path`/`Utf8PathBuf`, converting `tempfile` paths
with `Utf8Path::from_path`/`Utf8PathBuf::from_path_buf`.
- Update `tests/bdd/steps/process.rs`, `tests/stderr_routing_tests.rs`,
`tests/env_path_tests.rs`, and the trybuild fixture
`tests/ui/command_env_embedder_pass.rs` to use `camino` for
`program`/`build_file`.
- Update any CLI-parsing tests that assert `Cli.file`/`Cli.directory` types or
defaults.
- Add a test near the CLI parsing tests that passes a non-UTF-8
`--file`/`--directory` value and asserts the new localised diagnostic, and
confirms the failure happens early and without a panic.

Research

Netsuke parses CLI input with clap into the Cli struct (src/cli/command.rs), where file: PathBuf and directory: Option<PathBuf>. A parallel CliConfig struct (src/cli/config.rs) mirrors these fields for OrthoConfig layered merging; the two structs must stay serde-shape-compatible.

The runner resolves the Ninja executable in src/runner/process/ninja_program.rs, where resolve_ninja_program converts Utf8PathBuf down to PathBuf at the public boundary.

The Ninja invocation chain lives in src/runner/process/: request.rs defines NinjaBuildRequest/NinjaToolRequest (with program: &Path and build_file: &Path, but NinjaProcessOptions.working_dir: Option<Utf8PathBuf>), configure.rs defines configure_ninja_base, and paths.rs defines canonicalize_utf8_path.

The repository favours camino per the AGENTS.md convention and docs/netsuke-design.md, but no ADR records this decision.

path_with_dir_prepended does not exist in the codebase; it maps to the already-removed prepend_dir_to_path helper.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: record the decision to require UTF-8 paths on the Ninja
invocation chain.

- Create a new ADR file under `docs/`, following the structure and headings used
by `docs/adr-005-typed-which-resolve-error.md` and
`docs/adr-008-environment-seam-taxonomy.md` (Status, Date, Context, Decision,
Rationale, Consequences, Alternatives, Implementation references).
- State clearly in the ADR: the Ninja invocation chain requires UTF-8 paths;
non-UTF-8 build-file and working-directory paths are unsupported and get
rejected early.
- Cite the informal `camino` convention in `AGENTS.md`/`CRUSH.md`, the design
rationale in `docs/netsuke-design.md`, and the error-wrapping precedent
(`ResolveError`, `RUNNER_*_UTF8`, `MANIFEST_*_NON_UTF8` keys).
- Note the deliberate `std::path` carve-out in `src/cli/discovery_paths.rs`, and
record that environment-variable payloads stay `OsStr`/`OsString`.
- Record explicitly that `path_with_dir_prepended` does not exist in the
codebase (it maps to the already-removed `prepend_dir_to_path`), so no migration
action is needed for it.
- Update `CHANGELOG.md` with an entry stating that the runner now requires UTF-8
build-file and working-directory paths, and reports a clear diagnostic when a
path is not valid UTF-8.
===============================================================================

Task: 2

Implement Phase 2: migrate the internal Ninja invocation chain to `camino`,
keeping `std::path` only at the exact `std::process::Command` call boundary
where conversion is lossless.

- In `src/runner/process/request.rs`, change `NinjaBuildRequest.program` and
`NinjaBuildRequest.build_file` to `&'a Utf8Path`, and change the same two fields
on `NinjaToolRequest`. Leave `NinjaProcessOptions.working_dir` unchanged
(already `Option<Utf8PathBuf>`). Leave `BuildTargets`, `CommandEnv`, and
`StderrMode` unchanged.
- In `src/runner/process/paths.rs`, change `canonicalize_utf8_path` to accept
`&Utf8Path` instead of `&Path`. Delete the initial
`Utf8Path::from_path(...).ok_or_else(...)` guard and its "not valid UTF-8" error
branch, since callers already hold UTF-8.
- In `src/runner/process/configure.rs`, change `configure_ninja_base` to take
`build_file: &Utf8Path`. Remove the `working_dir.as_std_path()` round-trip and
call `canonicalize_utf8_path` directly on the `Utf8Path`. Convert to `std::path`
with `as_std_path()` only where `-f <build_file>` and `current_dir` reach
`std::process::Command`.
- In `src/runner/process/mod.rs`, update `run_ninja_with`,
`run_ninja_tool_with`, `run_ninja_with_status`, `run_ninja_tool_with_status`,
and the `run_ninja_*_internal` chain to build the `Command` from a `Utf8Path`
program via `as_std_path()`. Fix the embedded doctests to construct requests
with `Utf8Path` values.
- In `src/runner/process/ninja_program.rs`, make the public
`resolve_ninja_program` return `Utf8PathBuf`. Fold it into
`resolve_ninja_program_utf8`, or make the public entry return the UTF-8 type
directly and remove the `.into()` `PathBuf` conversion. Keep the existing
non-UTF-8 `NETSUKE_NINJA` override behaviour: ignore the override, fall back to
`NINJA_PROGRAM`, and keep the existing `tracing::debug!` event.
- In `src/runner/ninja_process_adapter.rs`, change `run_ninja` and
`run_ninja_tool` to accept `program: &Utf8Path` and `build_file: &Utf8Path`.
Keep the existing `working_dir` conversion in `ninja_process_options` unchanged.
- In `src/runner/mod.rs`, update `handle_build`, `handle_ninja_tool`, and the
`RunContext`/`context.ninja_program` type so the resolved program and the
generated temp build-file path are carried as `Utf8Path`/`Utf8PathBuf`.
- In `src/runner/process/file_io.rs` (or the temp-file helper
`create_temp_ninja_file`), update the return type if it currently uses
`std::path`, so the generated build-file path is available as `Utf8Path`.
===============================================================================

Task: 3

Implement Phase 3: migrate the CLI boundary to `camino` and add an early,
localised diagnostic for non-UTF-8 `file`/`directory` values, covering CLI,
config-file, and environment sources.

- In `Cargo.toml`, request `camino`'s serde feature (`features = ["serde1"]`)
for the main crate, since `CliConfig` will serialise/deserialise a `Utf8PathBuf`
field.
- In `src/cli/command.rs`, change `Cli.file` to `Utf8PathBuf` and
`Cli.directory` to `Option<Utf8PathBuf>`.
- In `src/cli/config.rs`, change `CliConfig.file` to `Utf8PathBuf` and change
`default_manifest_path()` to return `Utf8PathBuf::from("Netsukefile")`. Keep
`directory` as CLI-only; it has no `CliConfig` counterpart.
- Add a custom value parser in `src/cli/parser.rs` (with a helper in
`src/cli/parsing.rs`) that reads the raw `&OsStr` for `--file` and
`--directory`, converts it to `Utf8PathBuf`, and returns a localised error on
failure. Follow the existing `LocalizedValueParser` pattern used for
`jobs`/`locale`/`scheme`.
- Add a check in `CliConfig::post_merge` (`src/cli/config.rs`) that rejects a
non-UTF-8 `file` value coming from config files or environment variables, using
`validation.rs::validation_error`.
- Add localisation keys to `locales/en-US/messages.ftl` in the established
style, for example `cli.file.non_utf8 = Manifest path '{ $path }' is not valid
UTF-8.` and `cli.directory.non_utf8 = Working directory path '{ $path }' is not
valid UTF-8.`. Reuse
`runner.manifest.path_utf8`/`runner.manifest.directory_utf8` if their wording
already fits.
- In `src/runner/path_helpers.rs` (`resolve_manifest_path`), consume
`Cli.file`/`Cli.directory` as `camino` directly, and drop the
`Utf8PathBuf::from_path_buf` conversions and their
`RUNNER_MANIFEST_PATH_UTF8`/`RUNNER_MANIFEST_DIR_UTF8` branches, unless a branch
stays reachable from a `std::path` source.
- In `src/runner/dyndep_publication.rs` (`open_effective_dir`) and
`src/runner/ninja_process_adapter.rs` (`ninja_process_options`), consume
`Cli.directory` as `camino` directly and drop the now-dead conversions.
- Retire localisation keys that become unreachable, and remove them from
`locales/en-US/messages.ftl`; keep any key still used by a reachable branch.
===============================================================================

Task: 4

Implement Phase 4: update tests and fixtures so the test surface matches the new
`camino` field types, and add a test proving the fail-early diagnostic.

- Update `src/runner/process/configure.rs` tests
(`build_configuration_preserves_argument_order`,
`tool_configuration_preserves_argument_order`), `src/runner/process/tests.rs`,
`src/runner/process/exit_status_tests.rs`, and
`src/runner/process/public_ninja_execution_tests.rs` to build
`program`/`build_file` as `Utf8Path`/`Utf8PathBuf`, converting `tempfile` paths
with `Utf8Path::from_path`/`Utf8PathBuf::from_path_buf`.
- Update `tests/bdd/steps/process.rs`, `tests/stderr_routing_tests.rs`,
`tests/env_path_tests.rs`, and the trybuild fixture
`tests/ui/command_env_embedder_pass.rs` to use `camino` for
`program`/`build_file`.
- Update any CLI-parsing tests that assert `Cli.file`/`Cli.directory` types or
defaults.
- Add a test near the CLI parsing tests that passes a non-UTF-8
`--file`/`--directory` value and asserts the new localised diagnostic, and
confirms the failure happens early and without a panic.

💡 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.

---