Add CLI components and supporting logic

[wlix13]

Type of change

• Bug fix (fixes an issue in a rune, mold or deploy behaviour)
• Feature (adds a new rune, mold or CLI capability)
• Enhancement (improves existing provisioning logic or output)
• Refactor (restructures code without changing behaviour)
• Breaking change (changes existing mold schemas, CLI usage, or deploy behaviour)
• Security (security-related fix or hardening)

Description

Why is this change needed?

To improve UX with running runes

Related Issues

Testing

• Unit tests added or updated (uv run poe tests)
• Deployed to a real host
• No testing required (documentation changes only)

Checklist

• Code follows project style guidelines
• Self-review completed
• Linter and type checker pass (uv run poe check)
• Documentation updated (if applicable)

Summary by CodeRabbit

• New Features
  • Added the nullforge command-line interface for casting all features or selected runes.
  • Added preparation, dry-run, diff, verbosity, connection, parallelism, host-limit, and data override options.
  • Added built-in rune listing and shell completion for Bash, Zsh, Fish, and PowerShell.
  • Added direct nullforge command installation and improved command output labeling.
• Documentation
  • Replaced deployment instructions with comprehensive CLI usage guidance, including PowerShell quoting notes.

[coderabbitai]

Warning

Review limit reached

@wlix13, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 44 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1946e711-d4cc-4f6d-bc29-0ffb2640655e

📥 Commits

Reviewing files that changed from the base of the PR and between 54a09f6 and edefd62.

📒 Files selected for processing (28)

• README.md
• nullforge/cli/__init__.py
• nullforge/cli/__main__.py
• nullforge/cli/app.py
• nullforge/cli/components/__init__.py
• nullforge/cli/components/completion/__init__.py
• nullforge/cli/components/completion/component.py
• nullforge/cli/components/completion/controller.py
• nullforge/cli/components/completion/errors.py
• nullforge/cli/components/completion/powershell.py
• nullforge/cli/components/foundry/__init__.py
• nullforge/cli/components/foundry/component.py
• nullforge/cli/components/foundry/controller.py
• nullforge/cli/components/foundry/errors.py
• nullforge/cli/components/runes/__init__.py
• nullforge/cli/components/runes/component.py
• nullforge/cli/components/runes/controller.py
• nullforge/cli/core/__init__.py
• nullforge/cli/core/application.py
• nullforge/cli/core/component.py
• nullforge/cli/core/controller.py
• nullforge/cli/core/errors.py
• nullforge/cli/core/types.py
• nullforge/cli/display.py
• nullforge/cli/types.py
• nullforge/foundry/_pyinfra.py
• nullforge/foundry/cast.py
• pyproject.toml

📝 Walkthrough

Walkthrough

This PR adds a Click-based nullforge CLI with cast orchestration, selective rune execution, Pyinfra integration, shell completion, built-in rune listing, structured errors, display helpers, and updated CLI documentation.

Changes

CLI framework and application wiring

Layer / File(s)	Summary
CLI framework and application wiring README.md, nullforge/cli/core/*, nullforge/cli/app.py, nullforge/cli/__main__.py, nullforge/cli/display.py, pyproject.toml	Adds the application registry, component/controller abstractions, CLI entrypoint, Rich output handling, console script, and documentation for the new commands.

Cast command and Pyinfra pipeline

Layer / File(s)	Summary
Cast command and Pyinfra pipeline nullforge/cli/types.py, nullforge/cli/components/foundry/*, nullforge/foundry/*	Adds typed CLI arguments, rune and inventory selection, staged casting, Pyinfra argument construction and execution, selective rune inclusion, and rune-based Pyinfra output labels.

Completion and rune-listing commands

Layer / File(s)	Summary
Completion and rune-listing commands nullforge/cli/components/completion/*, nullforge/cli/components/runes/*	Adds shell completion generation and installation for Bash, Zsh, Fish, and PowerShell, plus built-in rune discovery and table rendering.

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

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant FoundryController
  participant PyinfraWrapper
  participant cast_selected
  CLI->>FoundryController: cast inventory, runes, and options
  FoundryController->>PyinfraWrapper: execute assembled Pyinfra command
  PyinfraWrapper->>cast_selected: run selective cast module
  cast_selected->>cast_selected: validate and include selected runes

Loading

Possibly related PRs

• wlix13/NullForge#3: Adds the full_cast script used by the new cast stage fallback.

Suggested labels: runes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.67% 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
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding new CLI components and the supporting CLI/foundry logic.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/add-cli

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@nullforge/cli/components/completion/powershell.py`:
- Around line 73-74: Update format_completion to normalize carriage-return and
newline characters in item.help before constructing the tab-separated PowerShell
completion record. Preserve the existing empty-help fallback and replace
multiline breaks with a single-line representation so each completion remains
one record.
- Around line 25-29: Update the completion branch to handle "file" and "dir"
types separately. Keep the "file" path using Get-ChildItem with the existing
ProviderItem completion metadata, and make the "dir" path use Get-ChildItem with
the -Directory filter and ProviderContainer result type so only directories are
suggested as native containers.

In `@README.md`:
- Around line 8-35: Update every documented nullforge CLI invocation in the
README CLI section to run through the uv project environment, using the uv run
prefix so the examples work immediately after uv sync without requiring shell
activation.

🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4458dbd9-cd06-44c0-8e59-e7b84b827f19

📥 Commits

Reviewing files that changed from the base of the PR and between 0ad48d4 and 54a09f6.

📒 Files selected for processing (28)

• README.md
• nullforge/cli/__init__.py
• nullforge/cli/__main__.py
• nullforge/cli/app.py
• nullforge/cli/components/__init__.py
• nullforge/cli/components/completion/__init__.py
• nullforge/cli/components/completion/component.py
• nullforge/cli/components/completion/controller.py
• nullforge/cli/components/completion/errors.py
• nullforge/cli/components/completion/powershell.py
• nullforge/cli/components/foundry/__init__.py
• nullforge/cli/components/foundry/component.py
• nullforge/cli/components/foundry/controller.py
• nullforge/cli/components/foundry/errors.py
• nullforge/cli/components/runes/__init__.py
• nullforge/cli/components/runes/component.py
• nullforge/cli/components/runes/controller.py
• nullforge/cli/core/__init__.py
• nullforge/cli/core/application.py
• nullforge/cli/core/component.py
• nullforge/cli/core/controller.py
• nullforge/cli/core/errors.py
• nullforge/cli/core/types.py
• nullforge/cli/display.py
• nullforge/cli/types.py
• nullforge/foundry/_pyinfra.py
• nullforge/foundry/cast.py
• pyproject.toml