feat(install): add --minimal binary-only install mode#989
Conversation
install.sh installs the plannotator binary and then writes a large amount of extra state: the sem sidecar, the agent-terminal runtime, and per-agent skills, hooks, slash commands, and config for Claude, Codex, OpenCode, Gemini, and Kiro. There is no way to get just the binary — even the --no-extras path still writes ~/.claude skills and OpenCode commands. Add a --minimal flag (aliased --binary-only) plus a PLANNOTATOR_MINIMAL env var for `curl | bash` runs. Minimal mode installs only the binary to ~/.local/bin, prints PATH advice, and exits before any sidecar download, agent integration, skill checkout, config write, cache clear, or cleanup migration. Precedence: flag > env var > default (off). The PATH-advice block is extracted into print_path_advice() so both the minimal early exit and the normal flow reuse it. Closes backnotprop#977
There was a problem hiding this comment.
Pull request overview
Adds a binary-only installation path to the Unix installer so users can install plannotator without any agent integrations or extra runtime/sidecar downloads, addressing the “installer writes trash” complaint in #977.
Changes:
- Introduces
--minimal(alias--binary-only) plusPLANNOTATOR_MINIMAL=1to enable binary-only installs. - Extracts PATH guidance into
print_path_advice()and reuses it in both minimal and normal flows. - Adds tests validating documentation, precedence resolution, early-exit ordering, and PATH advice reuse; updates README install docs.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| scripts/install.sh | Adds minimal/binary-only mode gating and extracts reusable PATH advice. |
| scripts/install.test.ts | Adds assertions for minimal mode documentation, precedence, early exit ordering, and PATH advice reuse. |
| README.md | Documents --minimal / PLANNOTATOR_MINIMAL=1 as a binary-only install option. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Binary-only mode. Installs just the plannotator binary (to $INSTALL_DIR) and | ||
| # nothing else — no sem sidecar, no agent-terminal runtime, no skills, hooks, | ||
| # slash commands, or per-agent config (Claude, Codex, OpenCode, Gemini, Kiro). | ||
| # -1 = flag not set (fall through to env var); 0 = off; 1 = on. Resolved after | ||
| # arg parsing so PLANNOTATOR_MINIMAL can enable it for `curl | bash` runs. | ||
| MINIMAL_FLAG=-1 |
There was a problem hiding this comment.
Fixed in c112e39. Added an explicit --no-minimal (sets MINIMAL_FLAG=0), so a CLI flag can now override PLANNOTATOR_MINIMAL=1 in either direction and the -1/0/1 states in the comment are all reachable. --minimal/--no-minimal are mutually exclusive, mirroring --extras/--no-extras. Same flag added to install.ps1 (-NoMinimal) and install.cmd for parity.
| --minimal Install only the plannotator binary. Skips the sem | ||
| semantic-diff sidecar, the agent-terminal runtime, and | ||
| every per-agent integration (skills, hooks, slash | ||
| commands, and config for Claude, Codex, OpenCode, | ||
| Gemini, and Kiro). Nothing is written outside | ||
| $HOME/.local/bin. Also enabled by exporting | ||
| PLANNOTATOR_MINIMAL=1. |
There was a problem hiding this comment.
Fixed in c112e39. The usage text now documents the --binary-only alias and the new --no-minimal, and the wording is softened to "No persistent state is written outside $HOME/.local/bin (a temp download file is still used and removed)" to avoid overpromising about mktemp/curl temp files and the config-dir read.
| # Binary-only mode stops here: the binary is installed, so print PATH advice and | ||
| # exit before any sidecar download, agent integration, skill checkout, config | ||
| # write, cache clear, or cleanup migration runs. Nothing outside $INSTALL_DIR is | ||
| # touched. See the MINIMAL_FLAG / PLANNOTATOR_MINIMAL resolution near the top. |
There was a problem hiding this comment.
Fixed in c112e39. Reworded to "No persistent state is written outside $INSTALL_DIR (the temp download file was already cleaned up above; the config dir may have been read, never written)."
Extend the binary-only install mode to full cross-installer parity and address the Copilot review on backnotprop#989. install.sh: - Add --no-minimal (MINIMAL_FLAG=0) so a CLI flag can override PLANNOTATOR_MINIMAL=1 in both directions; the -1/0/1 comment is now accurate. --minimal/--no-minimal are mutually exclusive. - Document the --binary-only alias and soften the absolute "nothing written outside ..." wording to "no persistent state" (minimal mode still uses a temp download file and may read the config dir). install.ps1 / install.cmd: - Add -Minimal (alias BinaryOnly)/-NoMinimal and --minimal/--binary-only/ --no-minimal with PLANNOTATOR_MINIMAL resolution, mirroring install.sh. - Extract PATH advice into Show-PathAdvice / :PrintPathAdvice and reuse it in both the minimal early exit and the normal flow. - Early-exit after the binary is placed, before the sidecar/agent/skill/ config work. Tests: add minimal-mode assertions to the install.ps1 and install.cmd describe blocks plus a shared-behavior test asserting all three installers support it; extend the sh tests for --no-minimal. Docs: document --minimal / PLANNOTATOR_MINIMAL in the installation guide (noting minimal mode needs no git) and add PLANNOTATOR_MINIMAL (and backfill PLANNOTATOR_SKIP_SEM_INSTALL) to the env-var registries.
| # Binary-only mode stops here (see the $minimal resolution near the top): the | ||
| # binary is installed, so add it to PATH and exit before any sidecar download, | ||
| # agent integration, skill checkout, config write, or cleanup runs. No | ||
| # persistent state is written outside $installDir. |
There was a problem hiding this comment.
Good catch — fixed in 7634fc5. You're right that the PowerShell path calls Show-PathAdvice, which persistently writes the user PATH (unlike install.sh / install.cmd, which only print PATH advice). Reworded the comment to drop the "no persistent state" claim and instead describe what minimal mode skips (sidecar, agent-terminal runtime, per-agent skills/hooks/config), noting the binary and its PATH entry are still added.
| <details> | ||
| <summary><strong>Binary-only install (nothing but the CLI)</strong></summary> | ||
|
|
||
| Pass `--minimal` (aliased `--binary-only`) to install **only** the `plannotator` binary — no sem semantic-diff sidecar, no agent-terminal runtime, and none of the per-agent skills, hooks, slash commands, or config for Claude, Codex, OpenCode, Gemini, or Kiro. No persistent state is written outside the install directory, and because it skips the sparse checkout, **minimal mode does not require `git`**. |
There was a problem hiding this comment.
Fixed in 7634fc5. Reworded the docs to: "The only thing installed is the binary (the Windows PowerShell installer also adds the install directory to your user PATH) …" so it no longer claims nothing persistent is written outside the install dir.
The PowerShell installer's minimal path calls Show-PathAdvice, which persistently writes the user PATH — so "no persistent state is written outside $installDir" overpromised. Reword the install.ps1 comment and the installation docs to describe what minimal mode skips (sidecar, agent runtime, per-agent integrations) and note the binary + PATH entry are still added on Windows. Addresses the second Copilot review on backnotprop#989.
Summary
Closes #977.
scripts/install.shinstalls theplannotatorbinary and then writes a large amount of extra state: the sem semantic-diff sidecar, the agent-terminal runtime, and per-agent skills, hooks, slash commands, and config for Claude, Codex, OpenCode, Gemini, and Kiro. As the reporter notes, there's no way to get just the binary — even--no-extrasstill writes~/.claudeskills and OpenCode command stubs.This adds a binary-only mode across all three installers:
--minimalflag (aliased--binary-only) and--no-minimalto force a full installPLANNOTATOR_MINIMAL=1env var, socurl … | bashruns can opt in without a flag — matching the existingPLANNOTATOR_SKIP_SEM_INSTALLidiom--minimal/--no-minimal) > env var > default (off)Minimal mode installs only the binary, prints PATH advice, and exits before any sidecar download, agent integration, skill checkout, config write, cache clear, or cleanup migration. No persistent state is written outside the install dir, and because it skips the sparse checkout, it does not require
git.Changes
install.sh:--minimal/--binary-only/--no-minimal+PLANNOTATOR_MINIMAL; PATH advice extracted intoprint_path_advice(); early-exit gate after the binary install.install.ps1:-Minimal(aliasBinaryOnly)/-NoMinimal+PLANNOTATOR_MINIMAL; PATH logic extracted intoShow-PathAdvice; earlyexit 0.install.cmd:--minimal/--binary-only/--no-minimal+PLANNOTATOR_MINIMAL; PATH advice extracted into a:PrintPathAdvicesubroutine; earlyexit /b 0; usage string updated.install.test.ts: minimal-mode assertions in theinstall.sh,install.ps1, andinstall.cmddescribe blocks, plus an "all three installers support minimal mode" shared-behavior test.PLANNOTATOR_MINIMAL(+ backfilledPLANNOTATOR_SKIP_SEM_INSTALL) added to the env-var registries (environment-variables.md,AGENTS.md/CLAUDE.md).Usage
Testing
bash -n scripts/install.shclean.install.sh:--minimalandPLANNOTATOR_MINIMAL=1each create only the binary (exit 0);--minimal --no-minimalerrors;PLANNOTATOR_MINIMAL=1 --no-minimalruns the full install.bun/pwsharen't available in my local env, so the fullbun testsuite and the ps1/cmd runtime behavior are validated by CI (bun test+ theinstall-ps1-windows/install-cmd-windowsintegration jobs). Every new test assertion string was checked against the actual scripts.Addressed all three Copilot review comments (the
MINIMAL_FLAGstate comment → real--no-minimal; documented the--binary-onlyalias; softened the "nothing written outside" wording to "no persistent state").