feat: add typed manpage integrations

[ian-pascoe]

Summary

• add a typed man_page package integration with manifest validation, optional single-file names, glob source declarations, and host platform filtering
• expand manpage globs against the extracted install root with globset and persist concrete per-file projections for status and cleanup
• reject duplicate concrete manpage projection paths before copying
• install manpages into share/man/man
  and prune empty man directories on removal
• expose Crosspack's man root from Unix shell init through MANPATH

Validation

• cargo fmt --all --check
• cargo build --workspace --locked
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo test --workspace
• cargo test -p crosspack-core man_page
• cargo test -p crosspack-installer man_page
• cargo test -p crosspack-cli integration_list_reports_man_page_projection_and_enable_is_unsupported

Summary by CodeRabbit

• New Features

  • Man-page integration support: installed man pages live under share/man and are exposed to Unix shells via MANPATH (Bash, Zsh, Fish). init-shell/installer now keep PATH, MANPATH, and completions in sync.

• Documentation

  • Quick Start, architecture, install-flow, and manifest spec updated with shell setup and man-page integration details.

• Behavior

  • Man-page integrations are listed in outputs but cannot be enabled/disabled via activation records.

[greptile-apps]

ian-pascoe has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cb0c8c19-7c6a-4d82-bc93-f8bd33496822

📥 Commits

Reviewing files that changed from the base of the PR and between e69a689 and d8d317c.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (17)

• Cargo.toml
• README.md
• crates/crosspack-cli/src/completion.rs
• crates/crosspack-cli/src/core_flows.rs
• crates/crosspack-cli/src/main.rs
• crates/crosspack-cli/src/tests.rs
• crates/crosspack-core/src/lib.rs
• crates/crosspack-core/src/manifest.rs
• crates/crosspack-core/src/tests.rs
• crates/crosspack-installer/Cargo.toml
• crates/crosspack-installer/src/exposure.rs
• crates/crosspack-installer/src/layout.rs
• crates/crosspack-installer/src/lib.rs
• crates/crosspack-installer/src/tests.rs
• docs/architecture.md
• docs/install-flow.md
• docs/manifest-spec.md

---

📝 Walkthrough

Walkthrough

Adds a new man_page integration: manifest shape and validation, installer layout/projection/exposure (including glob expansion and man-dir routing), CLI shell-init changes to export MANPATH, tests across crates, docs updates, and a globset dependency.

Changes

Man Page Integration

Layer / File(s)	Summary
Data Shape & Validation crates/crosspack-core/src/manifest.rs	Adds PackageIntegration::ManPage { name: Option<String>, section: String, source: String, platforms: Vec<IntegrationHostPlatform> }, IntegrationHostPlatform enum, and validation helpers enforcing section ∈ 1..9 and source suffix .N or .N.gz (with glob rules).
Public Exports crates/crosspack-core/src/lib.rs	Re-exports new IntegrationHostPlatform.
Installer Layout crates/crosspack-installer/src/layout.rs	Adds PrefixLayout::man_dir() -> <prefix>/share/man and includes it in base dir creation.
Projection / Exposure Core crates/crosspack-installer/src/exposure.rs, crates/crosspack-installer/src/lib.rs	Implements man-page projection utilities (man_page_file_name, man_page_projection, man_page_name_from_source), glob expansion (expand_man_page_glob, collect_files), install-root-aware APIs (projected_integrations_for_install_root, projected_integration_sources_for_install_root), routes man paths into man dir, and adds pruning for empty man dirs; exposes new projection/state helpers in crate API.
CLI Wiring / Sync crates/crosspack-cli/src/core_flows.rs, crates/crosspack-cli/src/main.rs	Switches projection calls to install-root-aware variants (projected_integrations_for_install_root) and updates imports/test-only uses.
Shell Init & Completions crates/crosspack-cli/src/completion.rs, README.md	Shell init snippet now computes man = layout.man_dir() and emits a MANPATH export (Bash/Zsh) or set -gx MANPATH (Fish) when the man dir exists; README updated to document MANPATH and man-page exposure.
Tests crates/crosspack-cli/src/tests.rs, crates/crosspack-core/src/tests.rs, crates/crosspack-installer/src/tests.rs	Adds tests: init-shell snippet includes MANPATH for Unix shells only; manifest parse/validation for man_page (glob and invalid cases); installer exposure/removal E2E for man pages under share/man.
Docs README.md, docs/architecture.md, docs/install-flow.md, docs/manifest-spec.md	Documents man_page integration kind, install path <prefix>/share/man/, MANPATH exposure via init-shell, install-flow artifacts/state, and Quick Start snippet.
Build / Dependency Cargo.toml, crates/crosspack-installer/Cargo.toml	Adds workspace dependency globset = "0.4" and enables globset.workspace = true in installer crate for glob expansion.

Sequence Diagram(s)

sequenceDiagram
  participant Manifest as Manifest
  participant Core as Core (manifest)
  participant Installer as Installer (exposure)
  participant FS as FileSystem (install-root / share/man)
  participant CLI as CLI (init-shell)

  Manifest->>Core: parse manifest with `man_page` integrations
  Core-->>Manifest: validated `ManPage` integration
  CLI->>Installer: request projected_integrations_for_install_root(...)
  Installer->>Installer: expand glob(s) and build projections
  Installer->>FS: write projections under `<prefix>/share/man/`
  Installer-->>CLI: return projections
  CLI->>FS: check layout.man_dir() exists
  CLI->>CLI: emit shell init snippet including MANPATH when applicable

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• spiritledsoftware/crosspack#122: Overlaps in integration handling and manifest parsing changes.
• spiritledsoftware/crosspack#132: Related edits to shell init/completion generation in crates/crosspack-cli/src/completion.rs.
• spiritledsoftware/crosspack#124: Related host-platform–aware projection/exposure changes and CLI wiring.

"I hopped through manifests with whiskers bright,
MANPATH ribbon trailing, share/man in sight,
Globs turned to pages, names tidy and true,
Shells now know where the manuals grew,
A rabbit cheers — small paws, big delight!" 🐇📚

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title directly and accurately describes the main feature being added: typed man-page integrations across the codebase. It is concise, clear, and specific.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/add-manpage-integration

---

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

[greptile-apps]

ian-pascoe has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[greptile-apps]

ian-pascoe has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.