feat(exec): add process replacement mode

[davdroman]

Summary

• add fnox exec --replace on Linux, macOS, and other Unix-like systems so environment-only workloads can replace fnox while retaining the same PID
• reject file-based secrets and credential leases before secret resolution because replacement prevents post-command cleanup
• omit ambient FNOX_AGE_KEY and FNOX_AGE_KEY_FILE values while allowing explicitly selected secrets with those names
• preserve inherited ignored SIGINT and SIGTERM dispositions and handle those signals during secret resolution
• document the flag and add Bats coverage for PID preservation, signals, exit status, missing secrets, daemon-backed resolution, and unsupported resources

Discussion: #652

This pull request was prepared with AI assistance and reviewed by the author.

Summary by CodeRabbit

• New Features
  • Added Unix-only fnox exec --replace to run the command via process replacement, preserving the PID and enabling direct signal delivery.
  • Allows environment-only secrets without creating credential leases; scrubs ambient age credentials while supporting explicit age credential selection.
• Bug Fixes
  • Improved error reporting for unsupported --replace scenarios (file-based secrets, credential leases, and signal setup failures) and missing secret failures.
• Documentation
  • Updated exec CLI docs, command reference, and usage synopsis to document --replace behavior and platform availability.
• Tests
  • Added Bats coverage for PID/signal behavior, compatibility checks, and failure modes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 487ad482-78f8-445f-acd8-39fecdb9ce7b

📥 Commits

Reviewing files that changed from the base of the PR and between ac5dbcf and 29ff7de.

📒 Files selected for processing (2)

• src/commands/exec.rs
• test/exec_replace.bats

🚧 Files skipped from review as they are similar to previous changes (2)

• src/commands/exec.rs
• test/exec_replace.bats

---

📝 Walkthrough

Walkthrough

Adds Unix-only fnox exec --replace, which validates incompatible secrets and leases, sanitizes ambient age credentials, installs signal handling, replaces the process via exec, updates CLI documentation, and adds platform and integration tests.

Changes

Exec replacement

Layer / File(s)	Summary
CLI contract and documentation src/commands/exec.rs, fnox.usage.kdl, docs/cli/..., src/commands/mod.rs	Adds the Unix-only --replace flag and documents its process, signal, environment, lease, and platform behavior.
Replacement validation and signal setup crates/fnox-core/src/error.rs, src/commands/exec.rs	Rejects file-based secrets and leases, and adds conditional SIGINT/SIGTERM handler setup with dedicated errors.
Environment scrubbing and process replacement src/commands/exec.rs	Removes ambient age credentials and uses cmd.exec() to replace the current process, wrapping failures as command-execution errors.
Process, signal, and compatibility tests test/exec_replace.bats	Tests PID preservation, signal delivery, environment handling, resolver interruption, missing secrets, daemon resolution, and incompatible configurations.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ExecCommand
  participant SecretResolver
  participant TargetProcess
  ExecCommand->>SecretResolver: Resolve configured secrets
  SecretResolver-->>ExecCommand: Return environment values
  ExecCommand->>ExecCommand: Scrub ambient age credentials
  ExecCommand->>TargetProcess: Replace process with cmd.exec()
  TargetProcess-->>ExecCommand: Return exec failure if startup fails

Loading

Poem

A rabbit hops where processes gleam,
Replacing a shell with a Unix dream.
Signals arrive, credentials flee,
Secrets resolve carefully.
“Hop-hop!” says the bunny, “the PID stays with me!”

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding exec process replacement mode.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[greptile-apps]

Greptile Summary

Adds Unix process replacement support to fnox exec.

• Introduces the --replace flag and executes the target command in the existing process.
• Rejects file-based secrets and credential leases that require post-command cleanup.
• Removes ambient age credentials while permitting explicitly configured replacements.
• Adds signal handling, documentation, platform checks, and integration coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/commands/exec.rs	Implements replacement-mode validation, environment construction, temporary signal handling, and Unix process replacement.
test/exec_replace.bats	Covers PID preservation, signal behavior, environment handling, exit status, resolution failures, daemon resolution, and unsupported resources.
src/commands/mod.rs	Adds a platform-sensitive CLI assertion for availability of the replacement flag.
crates/fnox-core/src/error.rs	Adds diagnostics for replacement-mode resource incompatibilities and signal setup failures.
fnox.usage.kdl	Publishes the Unix-only replacement mode in the CLI usage specification.

_{Reviews (2): Last reviewed commit: "test(exec): wait for replacement before ..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@fnox.usage.kdl`:
- Line 56: Make --replace platform-aware across fnox.usage.kdl: do not include
it in generic usage syntax, and describe it as Unix-only where appropriate.
Update docs/cli/commands.json (lines 250-275) and docs/cli/exec.md (lines 5-20)
to show the flag only for Unix or clearly separate Unix-only syntax from
portable fnox exec syntax; remove --replace from the platform-neutral command
index in docs/cli/index.md (line 65).

In `@test/exec_replace.bats`:
- Around line 209-213: Replace the one-time `ps -p "$REPLACEMENT_PID" -o comm=`
assertion in the replacement verification with a bounded polling loop that
repeatedly checks for `sleep`, allowing time for the target process to complete
`exec sleep 30` before failing.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: c31b77c9-3ce3-489f-aa86-b25535b74baa

📥 Commits

Reviewing files that changed from the base of the PR and between e7c2e34 and ac5dbcf.

📒 Files selected for processing (8)

• crates/fnox-core/src/error.rs
• docs/cli/commands.json
• docs/cli/exec.md
• docs/cli/index.md
• fnox.usage.kdl
• src/commands/exec.rs
• src/commands/mod.rs
• test/exec_replace.bats