feat: add pharn list command

[PrzemekGalarowicz]

Summary

• Adds pharn list — a read-only command that shows installed vs. available modules and category:skill skills, with update markers when the manifest has newer versions
• --json flag emits a single machine-readable inventory object on stdout (diagnostics to stderr) for scripting/CI use
• Updates help text, README commands table, docs index, roadmap, and CHANGELOG

Test plan

• npm test passes (new tests/list.test.ts + extended tests/index.test.ts)
• npm run typecheck passes
• npm run lint passes
• npm run format:check passes
• Manual smoke: pharn list in a project with pharn.config.json shows installed modules and available ones
• Manual smoke: pharn list --json prints clean JSON with no decorative output

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added remove command to uninstall modules or individual skills with confirmation prompt and --yes flag
  • Added list command to display installed and available modules/skills with optional --json output format
  • Added status command for version and drift auditing with --strict and --no-drift options

• Documentation

  • Added comprehensive CLI documentation for all new commands and their options

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0982d6a1-351f-40e5-9ac3-a9389b6f8ef7

📥 Commits

Reviewing files that changed from the base of the PR and between c8ca765 and 6a8995b.

📒 Files selected for processing (19)

• CHANGELOG.md
• CLAUDE.md
• README.md
• docs/README.md
• docs/commands/list.md
• docs/commands/remove.md
• docs/commands/status.md
• docs/roadmap.md
• src/commands/list.ts
• src/commands/remove.ts
• src/commands/status.ts
• src/index.ts
• src/lib/diff.ts
• src/lib/install-modules.ts
• tests/diff.test.ts
• tests/index.test.ts
• tests/list.test.ts
• tests/remove.test.ts
• tests/status.test.ts

---

📝 Walkthrough

Walkthrough

Adds three new CLI commands to pharn-cli: pharn list (read-only installed/available module inventory with --json output), pharn remove (skill and module deletion with dependency guards, confirmation flow, and protected-path enforcement), and pharn status (drift and version audit using a new SHA-256 byte-level diff library). The CLI entry point, help text, and documentation are updated to reflect all new commands.

Changes

New CLI Commands: list, remove, status

Layer / File(s)	Summary
Byte-level drift diff library src/lib/diff.ts, src/lib/install-modules.ts, tests/diff.test.ts	Introduces InstallDiff interface and diffInstalled function that builds an expected .claude/-relative file set from module manifests and skill definitions, excludes user-owned paths (CONSTITUTION.md, memory-bank/), and compares each entry via SHA-256 hash. Exports safeJoin from install-modules.ts for shared path-traversal protection. Tests cover directory/file installs, skill subtrees, exclusions, path-escape guards, and read-only invariant.
pharn list command src/commands/list.ts, tests/list.test.ts	runList reads pharn.config.json, fetches the remote manifest, builds an installed-vs-available inventory snapshot, and outputs either human-formatted CLI sections (INSTALLED / AVAILABLE TO ADD, wizard-aware) or a pure JSON object on stdout. Error handling routes to stderr in JSON mode and exits with code 1. Tests cover human and JSON mode rendering, update markers, "(all installed)" messaging, schemaVersion 1 manifests, and missing-config/fetch-failure paths.
pharn remove command src/commands/remove.ts, tests/remove.test.ts	runRemove routes to skill removal (local-only: deletes .claude/skills/<name>/, updates installedSkills), module removal (clone-based: computes exact contributed file set via collectModuleFiles, enforces dependency guards via installedDependents, deletes files, prunes empty directories, rewrites config), or an interactive picker. Protected paths (CONSTITUTION.md, memory-bank/) are never deleted. safeUnderClaude enforces .claude/-containment. Tests cover all refusal conditions, deletion precision, config preservation, confirmation flow, clone-failure cleanup, and interactive picker.
pharn status command src/commands/status.ts, tests/status.test.ts	runStatus supports --no-drift (fetch-only, lightweight version check) and full-drift mode (clone + diffInstalled). Prints VERSION and DRIFT note sections via clack prompts. --strict causes exit code 1 on any outdated/modified/missing condition. repo.cleanup() always runs in a finally block. Tests verify all flag combinations, section output contents, strict/non-strict exit behavior, and cleanup invocation.
CLI entry point wiring src/index.ts, tests/index.test.ts	Imports runRemove, runList, runStatus; extends USAGE help text; registers json, yes, strict, drift boolean flags and y/rm aliases in minimist; adds remove, rm, list, status case clauses to the dispatcher. Dispatch routing is verified with explicit option-shape assertions.
Documentation docs/commands/list.md, docs/commands/remove.md, docs/commands/status.md, docs/README.md, docs/roadmap.md, README.md, CLAUDE.md, CHANGELOG.md	Adds full command-reference pages for list, remove, and status. Updates docs index, roadmap capability table, root README commands table, CLAUDE.md dispatcher notes, and CHANGELOG unreleased section to reflect all new commands and flags.

Sequence Diagram

sequenceDiagram
  participant User
  participant CLI as src/index.ts
  participant Remove as runRemove
  participant Status as runStatus
  participant Repo as fetchRepo/cloneRepo
  participant Diff as diffInstalled
  participant FS as .claude/ + pharn.config.json

  rect rgba(255, 100, 100, 0.5)
    note over User,FS: pharn remove <module>
    User->>CLI: pharn remove review-module
    CLI->>Remove: runRemove("review-module", {yes})
    Remove->>Repo: cloneRepo (spinner)
    Repo-->>Remove: repoDir
    Remove->>Remove: installedDependents guard
    Remove->>Remove: collectModuleFiles → file set
    Remove->>FS: delete files, pruneEmptyDirs
    Remove->>FS: rewrite pharn.config.json
    Remove-->>User: removed
  end

  rect rgba(100, 100, 255, 0.5)
    note over User,FS: pharn status
    User->>CLI: pharn status [--strict] [--no-drift]
    CLI->>Status: runStatus({strict, drift})
    Status->>Repo: fetchRepo (remote manifest)
    Repo-->>Status: remoteManifest
    Status->>Repo: cloneRepo (drift mode only)
    Repo-->>Status: repoDir
    Status->>Diff: diffInstalled(repoDir, claudeDir, modules, skills)
    Diff-->>Status: InstallDiff {modified, missing, okCount}
    Status-->>User: VERSION + DRIFT notes
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐇 Hop, hop! Three commands now bloom,
remove sweeps the old skill's room,
list shows what grows in .claude/ ground,
status checks each file that's found.
SHA-256 guards every byte—
no memory-bank lost in the night!
— a very tidy rabbit 🌿

✨ 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 update-commands

---

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 and usage tips.}