Expose run API for downstream workflows

[nhlmg93]

Summary

This keeps pi.nvim's built-in feature set small while exposing a reusable engine API for downstream workflows.

Core still only registers:

• :PiAsk
• :PiAskSelection
• :PiCancel
• :PiLog

New public API:

• require("pi").get_cmd() returns the configured pi command table
• require("pi").run({ ... }) starts a session with custom context/behavior
  • message
  • build_context
  • bufnr
  • cmd
  • skip_reload
  • on_done(session)

This should let users implement things like PiSearch or PiTutorial in their own config/plugin without making those commands part of pi.nvim core.

Closes #13.

Tests

• make test — 30/30 passing

Summary by CodeRabbit

• Documentation

  • Added an API section documenting new programmatic session APIs, options, and usage examples.

• New Features

  • Exposed a public session-runner API allowing custom context builders, per-session completion callbacks, command overrides, and optional control over buffer reloads.

• Tests

  • Added tests covering context injection, command overrides, completion callbacks, reload behavior, and error handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6a5f837c-747d-4fe1-b2ac-8d2fa3410e6f

📥 Commits

Reviewing files that changed from the base of the PR and between 825029c and 3b9d9cf.

📒 Files selected for processing (3)

• README.md
• lua/pi/init.lua
• tests/test_pi_commands.lua

✅ Files skipped from review due to trivial changes (1)

• README.md

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

• tests/test_pi_commands.lua
• lua/pi/init.lua

---

Walkthrough

This PR exposes two new public functions to enable downstream pi.nvim workflows. M.get_cmd() returns the configured pi RPC command from setup config, handling binary selection and CLI flags. M.run(opts) starts a pi session with customizable message, context builder, source buffer, command override, reload behavior, and completion callback. The session lifecycle was updated to invoke optional on_done callbacks and respect skip_reload flags. Existing prompt_with_buffer and prompt_with_selection commands now delegate to M.run(). Comprehensive test coverage validates context injection, command overrides, callback sequencing, error handling, and reload behavior. README documents the new API surface.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant M_run as require("pi").run()
  participant Session
  participant UI
  participant ContextBuilder as build_context
  participant Runner as runner.start
  User->>M_run: call run(opts)
  M_run->>Session: create session + snapshot buffers
  M_run->>Session: set skip_reload and on_done
  M_run->>UI: open UI
  M_run->>Session: set status "collecting_context"
  M_run->>ContextBuilder: invoke build_context()
  ContextBuilder-->>M_run: returns context
  M_run->>Runner: start(session, cmd, payload with Context)

Loading

Possibly related PRs

• pablopunk/pi.nvim#7: Modifies the same command construction logic in lua/pi/init.lua to handle system-prompt/append-system-prompt flags.

🚥 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 and specifically describes the main change: exposing a run API for downstream workflows, which aligns with the primary objective of the PR.
Linked Issues check	✅ Passed	The PR successfully implements all coding objectives from issue #13: exposes get_cmd() and run() APIs with required options (message, build_context, bufnr, cmd, skip_reload, on_done), updates existing commands to use the new API, and includes comprehensive test coverage.
Out of Scope Changes check	✅ Passed	All changes are within scope: API exposure in init.lua, README documentation of the public API, and test coverage for the new functionality align directly with issue #13 objectives.

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

---

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

[pablopunk]

hey @nhlmg93 ! thanks for the PR, I like the approach and I might even use this myself 🌝

One small thing, could you keep the README more minimal? The API docs are fine but the PiSearch example might be too much (very cool tho). If you have a public dotfiles repo where you've implemented this feel free to link it as an example in the README