feat: add setup hooks for agent session integration

[Freudator86]

What this adds

forgejo-axi setup hooks -- the SessionStart hook registration that makes this tool's context ambient in an agent session.

Principle 7 asks for exactly this, axi-sdk-js ships installSessionStartHooks for it, and this tool did not call it. Every agent had to be told about forgejo-axi by hand.

The command writes the registration for Claude Code (~/.claude/settings.json), Codex (~/.codex/hooks.json and ~/.codex/config.toml) and OpenCode (~/.config/opencode/plugins/). It contacts no host and reads no credential, so it works before the CLI is configured at all -- which is when a first-time user runs it. Rerunning is a no-op, so it is the repair path as well as the install path.

The part I would most like reviewed

installSessionStartHooks declines silently when the entry point is not an installed forgejo-axi binary -- a dev checkout, a .ts entry under a loader, some other runner. That refusal is correct and I did not want to defeat it.

But a thin wrapper around it would have printed installed: true while writing nothing, which is a confident lie about a file that does not exist. So the command asks the SDK's own exported predicate shouldInstallHooksForNodeAxiExecPath first, and when it says no, reports:

hooks:
  installed: false
  reason: entry_point_not_an_installed_binary
  entry_point: /usr/bin/some-other-tool
next[1]: "Install the CLI with `npm install -g forgejo-axi`, then rerun `forgejo-axi setup hooks`"

Exit 0, because that is a definite answer about a supported situation rather than a failure -- the same reading the contract already gives an unsupported capability. A target that genuinely could not be written is different: that is SETUP_FAILED and exit 1, with the offending paths in details.

If you would rather the decline be an error, or the predicate call be dropped in favour of trusting the SDK, say so and I will change it -- it is the one judgement call in this PR.

Other notes

• setup is registered through the existing dispatch helper, so setup --help, setup hooks --help, and Unknown setup command: <x> all behave like the other families for free.
• MainOptions gains an optional execPath, defaulting to process.argv[1]. That is what lets the tests drive both outcomes, the same way stdout, stdin and env are already injected there. Under vitest argv[1] is the vitest binary, so without this the tests would exercise the decline path only and silently prove nothing about installation.
• No SDK version bump needed: installSessionStartHooks and shouldInstallHooksForNodeAxiExecPath are both in the pinned 0.1.9.

Verification

• npm run check passes: lint, typecheck, 243 tests (237 before, 6 added in a new test/setup.test.ts), smoke.
• npm run gen:skill regenerated; the byte comparison in check passes.
• Tests cover: all four target files written; second run byte-identical; the decline path writing nothing; an unwritable target producing SETUP_FAILED and exit 1; unknown subcommand exit 2; and both help texts.
• Every test and every manual run used a mkdtemp scratch HOME. I also confirmed by hand that my real ~/.claude/settings.json was untouched, since a test for a command that writes to the home directory is not one to take on trust.

Live lanes: neither was run. This change touches no API request, response handling, or fixture, so docs/live-test-matrix.md does not call for one. Stating it explicitly per CONTRIBUTING.

Summary by CodeRabbit

• New Features
  • Added setup hooks to install or repair supported agent session integrations.
  • Supports human-readable and JSON output with installation status and next steps.
  • Repeated runs are safe and idempotent.
  • Reports unsupported entry points without making changes and provides clear setup errors.
  • Added --fields LIST|all to pull request, issue, and workflow run details.
  • Added command-specific help and documentation.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1a99fa3e-e4f2-4168-b67f-e49ff12bfe96

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ad3f05e7-d4b5-44b4-a245-994b02e16523

📥 Commits

Reviewing files that changed from the base of the PR and between 53193ea and 2046aca.

📒 Files selected for processing (4)

• docs/contract.md
• skills/forgejo-axi/SKILL.md
• src/cli.ts
• src/help.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

The CLI adds local SessionStart hook installation for Claude Code, Codex, and OpenCode. It also adds ordered field selection for pull request, issue, and workflow-run detail views.

Changes

Setup hooks

Layer / File(s)	Summary
Command contract and documentation docs/contract.md, skills/forgejo-axi/SKILL.md	Documents setup hooks [--json], local execution, response fields, refusal behavior, and SETUP_FAILED errors.
Setup hooks CLI flow src/cli.ts, src/help.ts	Registers the command, validates executable eligibility, installs hooks through the SDK, and returns structured results.
Invocation wiring and behavior coverage test/server.ts, test/setup.test.ts	Passes execPath into the CLI and tests installation, idempotency, refusal, write failures, invalid commands, and help output.

Detail field selection

Layer / File(s)	Summary
Field selection contracts and help docs/contract.md, src/help.ts	Documents --fields LIST|all, requested order, primary-object scope, and omission of unavailable fields.
Detail view filtering src/cli.ts	Adds field catalogs and filters pull request, issue, and workflow-run objects without changing sibling response data.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: 🔵 Low · up to 2046a

The new command registers forgejo-axi across Claude, Codex, and OpenCode configuration files. If installation fails partway through or is interrupted, the environments may be left in different states, so owners should confirm that rerunning reliably repairs every target; otherwise the PR is mergeable with that follow-up awareness.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant SDKHookInstaller
  participant AgentConfigFiles
  CLI->>CLI: validate execPath and arguments
  CLI->>SDKHookInstaller: install session hooks
  SDKHookInstaller->>AgentConfigFiles: write agent settings
  AgentConfigFiles-->>SDKHookInstaller: return write results
  SDKHookInstaller-->>CLI: return status or failures

Loading

Suggested reviewers: escidmore

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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 identifies the main change: adding setup hooks for agent session integration.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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