@devries-cameron20 / composio Mirror · read-only / commits / 32b414305
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 17:15 UTC

refactor(cli): deduplicate setup-failure warning and atomic writes

Also track the installer plan documents that the KD-tagged comments in install.sh and the shell harness reference.

jkomyno committed Aug 3, 2026 at 17:18 UTC 32b414305c53cffed5d592cb6e9e8aec40dbb050
4 files changed +612 -22
docs/plans/2026-07-31-001-feat-mise-style-installer-rewrite-plan.md new
+374
@@ -0,0 +1,374 @@
1 +---
2 +title: Mise-Style CLI Installer Rewrite - Plan
3 +type: feat
4 +date: 2026-07-31
5 +deepened: 2026-07-31
6 +artifact_contract: ce-unified-plan/v1
7 +artifact_readiness: implementation-ready
8 +product_contract_source: ce-plan-bootstrap
9 +execution: code
10 +---
11 +
12 +# Mise-Style CLI Installer Rewrite - Plan
13 +
14 +## Goal Capsule
15 +
16 +- **Objective:** Rewrite `install.sh` as a POSIX-sh, mise-style installer (binary install to `~/.local/bin` by default, install-only default flow, mise-equivalent env-var surface, `/install/zsh|bash|fish` shell variants), extend `composio install` with a `--shell` flag, rewrite the install docs to mise depth, update install-related CI, and add a Docker-based installation e2e workflow.
17 +- **Authority hierarchy:** This plan's Product Contract and KTDs > repo conventions (`AGENTS.md`, nested `AGENTS.md`, `ts/packages/cli/CLAUDE.md`) > implementer judgment. The scope was negotiated with the user across three rounds; do not re-litigate the decisions recorded in KTDs.
18 +- **Execution profile:** Execute in two context-isolated stages. Stage 1 is U1 and ends with a verified stable CLI release. Stage 2 is U2-U8 and consumes only Stage 1's published-contract handoff, not its implementation context. U7-U8 remain an explicit follow-up within Stage 2. See Sequencing and Two-Stage Execution.
19 +- **Stop conditions:** Stop and surface to the user if (a) the Linux e2e falsifies the Bun `process.execPath` symlink-resolution behavior that KTD2 depends on, (b) the Cloudflare redirect rules for `/install/<shell>` cannot be provisioned before docs advertise those URLs, (c) any change would alter product scope (e.g. dropping a preserved env var), (d) the exact U1 beta tag, source commit, six uploaded assets, and installation workflow have not been verified and explicitly approved by the user before `promote-stable`, or (e) `next` does not enforce code-owner review for `install.sh` and `install/**` before U2 merges.
20 +- **Tail ownership:** The implementer owns green CI, docs build, and the Definition of Done checklist. Cloudflare rule changes are external (see Risks & Dependencies) and are requested, not implemented, here.
21 +
22 +---
23 +
24 +## Product Contract
25 +
26 +### Summary
27 +
28 +Replace the current bash-only `install.sh` (which installs everything into `~/.composio`, edits rc files, and installs agent plugins by default) with a POSIX-sh installer modeled on mise: the default `curl -fsSL https://composio.dev/install | sh` performs a verified binary-bundle install and nothing else, the `composio` entry point lands on a directory that is already on PATH on mainstream distros (`~/.local/bin`), and shell-specific setup (rc file, PATH line, completions) moves behind explicit `/install/zsh|bash|fish` endpoints that delegate to the binary's own `composio install --shell <shell>` command. The docs `## Install` section is rewritten to mise depth, install-related CI is updated to the new contract, and a new Docker-based e2e workflow proves the flow end-to-end in fresh zsh and bash-only containers.
29 +
30 +### Problem Frame
31 +
32 +The current installer has caused real "composio: command not found" failures (the user's CTO hit it on a fresh Ubuntu box): `~/.composio` is never on PATH by default, PATH guidance has been silently broken by TTY-gating regressions (#3450, fixed by #3951), and the only channels that gave instant PATH availability (npm, Homebrew) were decommissioned in #3960. The installer is also bash-only while documented as pipe-to-shell, mutates rc files and installs plugins without opt-in, and its behavior is under-documented (a 2-line docs snippet; a factually wrong `INSTALL.md`). Structural fix: install the entry point to `~/.local/bin` (on PATH by default via `~/.profile` on Debian/Ubuntu skeletons), make the default flow install-only like mise, and give shell setup an explicit, documented, idempotent path.
33 +
34 +### Requirements
35 +
36 +**Installer script**
37 +
38 +- R1. The default `curl -fsSL https://composio.dev/install | sh` flow performs only: platform detection, version resolution, download, sha256 verification, bundle install into `COMPOSIO_INSTALL_DIR` (default `~/.composio`), entry-point symlink into `COMPOSIO_BIN_DIR` (default `~/.local/bin`), a `composio --version` smoke probe, and post-install guidance. No rc-file edits, no `composio install` delegation, no plugin setup, no login. The guidance must classify reachability: when the bin dir is missing from the current `PATH`, **or** `~/.bash_profile`/`~/.bash_login` exists (bash login shells read only the first of `~/.bash_profile`, `~/.bash_login`, `~/.profile` — so Debian/Ubuntu's skeleton `~/.profile` line that adds `~/.local/bin` never runs for those users), present the `/install/<shell>` step as a required next step, not an optional one.
39 +- R2. Every served script is POSIX sh: runs under `sh` and `dash` with no bashisms or implementation-specific builtins (no `[[ ]]`, arrays, `pipefail`, process substitution, `local`, `echo -e`, here-strings, `(( ))`). `shellcheck -s sh` passes without suppressing POSIX portability findings.
40 +- R3. Env/arg contract per KTD3's table: existing vars keep their current meaning (`COMPOSIO_INSTALL_DIR` remains the complete bundle directory; `COMPOSIO_INSTALL_PLUGINS`, `COMPOSIO_GITHUB_{OWNER,REPO,URL,API_BASE_URL}`, positional version tag, `--agent`, `--no-plugins`, `-h/--help` remain supported); new vars are `COMPOSIO_BIN_DIR`, `COMPOSIO_INSTALL_VERSION`, `COMPOSIO_QUIET`, `COMPOSIO_DEBUG`, `COMPOSIO_INSTALL_HELP`. `COMPOSIO_INSTALL_PLUGINS` default flips from `1` to `0`.
41 +- R4. Supply-chain guards are preserved and extended: https-only `COMPOSIO_GITHUB_URL`/`COMPOSIO_GITHUB_API_BASE_URL`/`COMPOSIO_INSTALL_SCRIPT_URL` (with the exact-host http exception of KTD6), identifier-safe owner/repo validation, validation of every constructed or API-returned download URL before use, curl protocol restrictions that reject redirect downgrade, sha256 verification against the release's `checksums.txt` (mismatch fatal; missing checksum warn-and-continue, matching current behavior — note this verifies transport and asset integrity only, since `checksums.txt` shares the archive's origin; it is not signing), stable-only automatic resolution (`@composio/cli@X.Y.Z`), strictly validated explicit stable or beta tags (`@composio/cli@X.Y.Z` or `@composio/cli@X.Y.Z-beta.N`) so the release workflow can test published betas, no `git` usage, and the KTD9 single-entrypoint structure on every served script.
42 +- R5. Shell-variant scripts served at `/install/zsh|bash|fish` run the base install then delegate shell setup to `composio install --shell <shell>`, with the fallback chain of KTD5 for older released binaries and broken binaries.
43 +
44 +**CLI command**
45 +
46 +- R6. `composio install` gains a `--shell <zsh|bash|fish>` option that overrides `$SHELL` detection; everything downstream of detection is already a pure function of the shell value.
47 +- R7. `composio install` writes a PATH block that targets the bin dir (resolution order per KTD4), stays marker-idempotent, and keeps completions behavior (bash in `~/.bashrc`, fish separate file, zsh skipped). Auto-detected-shell mode may skip PATH writes when the bin dir is already on the invoking `PATH`; an explicit `--shell` request must configure the requested shell's startup files regardless of the invoking process's `PATH`.
48 +- R8. The restart hint bug is fixed: bash prints `source ~/.bashrc` instead of the literal string `exec $SHELL`; when a login override file (`~/.bash_profile` or `~/.bash_login`) is updated, the hint also says that entry applies to new login shells.
49 +
50 +**Serving**
51 +
52 +- R9. Shell-variant scripts ship as files in this repo (`install/zsh.sh`, `install/bash.sh`, `install/fish.sh`) compatible with the existing Cloudflare-redirect scheme; the redirect model is kept for launch (KTD1). The three new redirect rules are an external dependency.
53 +
54 +**Docs**
55 +
56 +- R10. The `## Install` section of `docs/content/docs/cli.mdx` is rewritten to mirror mise's install docs structure and depth: canonical one-liner, options/env-var table, shell-specific variants, install verification, alternatives (manual GitHub-release install), uninstall.
57 +- R11. Every other occurrence of the install one-liner is updated in lockstep to `curl -fsSL https://composio.dev/install | sh`: `docs/lib/source.ts`, `docs/components/ai-tools-banner.tsx`, `docs/components/home-surfaces.tsx`, `README.md`, `docs/content/docs/claude-code-plugin.mdx`, `INSTALL.md` (full factual rewrite), plus a docs changelog entry.
58 +
59 +**CI and e2e**
60 +
61 +- R12. Install-related CI is updated to the new contract: `test/install-sh-release-resolution.test.sh` (ported to invoke `sh`/`dash`), `.github/workflows/cli.test-installation.yml`, `.github/workflows/cli.install-health-check.yml`, the smoke test in `.github/workflows/build-cli-binaries.yml`, and the literal-string assertions in `test/release-workflow.test.ts`.
62 +- R13. A new Docker-based install e2e exists: two container images (zsh, bash-only), Bun-coordinated under `ts/e2e-tests/cli/` conventions, asserting `composio` is on PATH in a fresh login shell after install. PR mode uses one locally built, explicitly tagged CLI bundle served from a local Bun server. Nightly production coverage runs `latest` on bash and zsh plus one exact pre-`--shell` compatibility case, `@composio/cli@0.3.1` on zsh.
63 +
64 +**Compatibility**
65 +
66 +- R14. Already-released binaries keep working throughout rollout: the default flow never requires new CLI flags, and variant scripts degrade gracefully when `--shell` is unsupported (KTD5).
67 +- R15. Existing installs migrate without reinterpreting `COMPOSIO_INSTALL_DIR`: re-running the installer upgrades the complete bundle in that directory (default `~/.composio`) and creates the entry-point symlink in `COMPOSIO_BIN_DIR` (default `~/.local/bin`). A legacy rc export such as `COMPOSIO_INSTALL_DIR="$HOME/.composio"` therefore remains correct and no longer needs heuristic leak detection; old PATH blocks pointing at the bundle remain functional alongside the new symlink. Setting `COMPOSIO_BIN_DIR=$COMPOSIO_INSTALL_DIR` deliberately selects the legacy single-directory layout with no symlink.
68 +
69 +### Acceptance Examples
70 +
71 +- AE1. **Fresh Ubuntu, bash only** (the CTO scenario): run the default one-liner in a container with no `~/.local/bin`; open a fresh login shell (`bash -ilc`); `composio --version` succeeds because Ubuntu's skeleton `~/.profile` puts `~/.local/bin` on PATH once it exists.
72 +- AE2. **zsh via variant:** `curl -fsSL https://composio.dev/install/zsh | sh` in a zsh container; fresh `zsh -ilc 'composio --version'` succeeds via the rc block written by `composio install --shell zsh`.
73 +- AE3. **Pinned version:** `COMPOSIO_INSTALL_VERSION=0.1.32 sh` and positional `@composio/cli@0.1.32` both install that tag; positional wins when both are set; bare `X.Y.Z` is normalized to `@composio/cli@X.Y.Z`; an explicitly supplied `@composio/cli@X.Y.Z-beta.N` installs that published beta, while automatic resolution never selects a prerelease.
74 +- AE4. **Tampered download:** a zip whose sha256 does not match `checksums.txt` aborts the install with a fatal error before anything is written to the install dirs.
75 +- AE5. **Deliberate legacy layout:** `COMPOSIO_INSTALL_DIR=$HOME/.composio COMPOSIO_BIN_DIR=$HOME/.composio` installs the complete bundle into `~/.composio` and creates no symlink.
76 +- AE5b. **Legacy migration:** on a machine whose rc file contains the old `# Composio CLI` block exporting `COMPOSIO_INSTALL_DIR="$HOME/.composio"`, re-running the installer upgrades the bundle in `~/.composio`, creates `~/.local/bin/composio` because `COMPOSIO_BIN_DIR` is unset, and leaves the old working PATH block untouched.
77 +- AE6. **Upgrade preserves symlink:** with the new layout in place, `composio upgrade` replaces `~/.composio/composio` and its sidecars; `~/.local/bin/composio` remains a symlink pointing at the refreshed binary. U7 proves symlinked execution, bundle-relative sidecar placement, and version lookup; a focused `upgrade-binary` unit test proves replacement leaves the entry-point symlink unchanged.
78 +- AE7. **Variant against an old release:** `/install/zsh` with a pinned pre-`--shell` CLI version detects that `composio install --help` lacks `--shell` and uses the inline rc-append fallback for the requested shell. If `--shell` is advertised but its invocation fails, the same fallback runs. The variant never retries plain `composio install` or configures a different shell.
79 +
80 +### Scope Boundaries
81 +
82 +**In scope:** everything in Requirements; the exact file list per unit.
83 +
84 +**Deferred to Follow-Up Work**
85 +
86 +- Direct-serve (Cloudflare Worker proxy à la `mise.run`, enabling `curl https://composio.dev/install | sh` with no `-L`). Reference implementation: mise's `cloudflare/workers/mise-run.js`. Revisit after the redirect-based launch proves out.
87 +- Additional mise vars not in confirmed scope: `COMPOSIO_INSTALL_OS`/`COMPOSIO_INSTALL_ARCH` overrides, `COMPOSIO_INSTALL_SKIP_IF_EXISTS`, musl/archive-format controls.
88 +- A `composio uninstall` command (docs document manual uninstall for now).
89 +- Client-side protocol pinning in the canonical one-liner (`--proto '=https' --proto-redir '=https'`, the rustup pattern). It would backstop a Cloudflare rule whose redirect target is ever changed to http, but it lengthens the one-liner users have memorized; the primary mitigation (https redirect target, https raw.githubusercontent) already holds.
90 +- A dedicated `/docs/install` page (the rewrite stays in `cli.mdx` per docs conventions).
91 +
92 +**Outside this product's identity**
93 +
94 +- Windows-native support (WSL redirect message stays).
95 +- Re-introducing npm/Homebrew channels (decommissioned in #3960).
96 +
97 +---
98 +
99 +## Planning Contract
100 +
101 +### Key Technical Decisions
102 +
103 +- KTD1. **Keep the Cloudflare 302-redirect serving model for launch; resolve the redirect-vs-direct-serve fork in favor of redirect.** The canonical one-liner keeps `-fsSL` (`-L` follows the 302), which is already the documented muscle memory. Direct-serve requires deploying and owning a Cloudflare Worker from outside this repo (mise's approach); the redirect needs only three one-line rules (`/install/zsh|bash|fish` → `https://raw.githubusercontent.com/ComposioHQ/composio/refs/heads/next/install/<shell>.sh`). mise's strongest argument for direct-serve — baking per-release checksums into the served script — does not apply: Composio verifies checksums dynamically from the release's `checksums.txt`. Direct-serve is recorded as deferred follow-up.
104 +- KTD2. **Two-directory layout with preserved bundle-dir semantics.** The full bundle (binary + run-companion sidecars + `local-tools-binaries/` + `release-tag.txt`) installs to `COMPOSIO_INSTALL_DIR`, whose existing meaning and default (`~/.composio`) remain unchanged. The user-facing entry point is a symlink `$COMPOSIO_BIN_DIR/composio → $COMPOSIO_INSTALL_DIR/composio`, with `COMPOSIO_BIN_DIR` defaulting to `~/.local/bin`. When the resolved directories are equal, the bundle's real binary is already the entry point and no symlink is created. This separation means an inherited legacy `COMPOSIO_INSTALL_DIR="$HOME/.composio"` is valid bundle configuration rather than a value that needs heuristic rc-file detection. **Verified 2026-07-31 (Bun 1.3.10, compiled binary):** `process.execPath` resolves symlinks to the real path for relative symlinks, absolute symlinks, and PATH lookups; on Linux this is guaranteed by `/proc/self/exe` semantics. Consequence: all `path.dirname(process.execPath)` sidecar resolvers (11 call sites incl. `ts/packages/cli/src/services/run-companion-modules.ts`, `effects/version.ts`, `effects/install-skill.ts`, `cli-local-tools/src/bundled-binaries.ts`), companion self-repair, and `services/upgrade-binary.ts` (`replaceBinary` targets `process.execPath`, i.e. the real file) operate on the configured bundle directory with **zero CLI resolver changes**. The e2e (U7) pins this behavior. Sidecar resolvers take `execPath` as a parameter threaded from `process.execPath` at the entry points — grep for `execPath`, not `process.execPath`, when auditing. The installer replaces an existing regular file at the symlink path (a pre-existing copy) and errors if the target is a directory.
105 +- KTD3. **Env-var surface** (mirrors mise capabilities, prefers existing Composio names — user decision):
106 +
107 + | Variable / arg | Default | Behavior |
108 + |---|---|---|
109 + | `COMPOSIO_INSTALL_DIR` | `$HOME/.composio` | Existing. Directory receiving the complete binary bundle and `release-tag.txt`; its meaning does not change. |
110 + | `COMPOSIO_BIN_DIR` | `$HOME/.local/bin` | New. Directory receiving the `composio` entry-point symlink. If it resolves to `COMPOSIO_INSTALL_DIR`, no symlink is needed. |
111 + | `COMPOSIO_INSTALL_VERSION` | latest stable | New. Pins the release. Accepts `@composio/cli@X.Y.Z`, `@composio/cli@X.Y.Z-beta.N`, or the corresponding bare value (normalized). Automatic resolution remains stable-only. **Not** `COMPOSIO_VERSION`: that name is taken by the CLI config service's debug-override surface (`ts/packages/cli/test/src/services/config.test.ts:314`, `DEBUG_OVERRIDE_CONFIG`). |
112 + | positional `version-tag` | — | Highest-precedence version pin (positional > env > latest). Same stable/beta validation and normalization. |
113 + | `COMPOSIO_QUIET` | unset | New. `1`/`true` silences progress info; warnings and errors still print (mise `MISE_QUIET` semantics). |
114 + | `COMPOSIO_DEBUG` | unset | New. `1`/`true` traces commands (curl invocations, resolved URLs, temp paths) to stderr (mise `MISE_DEBUG` semantics). |
115 + | `COMPOSIO_INSTALL_HELP` | unset | New. `0` suppresses the post-install guidance block; set by the shell-variant scripts, which print their own tail (mise `MISE_INSTALL_HELP` semantics). |
116 + | `COMPOSIO_INSTALL_PLUGINS` | `0` (**was `1`**) | `1` opts in to `composio setup --target auto --yes --if-present` after install. |
117 + | `COMPOSIO_GITHUB_{OWNER,REPO,URL,API_BASE_URL}` | unchanged | Same validation as today, plus KTD6's loopback http exception. |
118 + | `--agent` | off | Unchanged: runs `composio login --agent --no-skill-install` after install. |
119 + | `--no-plugins` | — | Kept for back-compat; now matches the default. |
120 +
121 +- KTD4. **`composio install` bin-dir and startup-file rules.** Bin-dir resolution order is `COMPOSIO_BIN_DIR` env (the new installer passes it at delegation) → `~/.local/bin` if `~/.local/bin/composio` exists → `path.dirname(process.execPath)` (the real binary's dir, always a correct PATH target). The rc block becomes marker + literal PATH line only; drop the historical `export COMPOSIO_INSTALL_DIR=...` line because that variable continues to identify the bundle, not the PATH entry point. In auto-detected-shell mode, the command may skip PATH writes when the bin dir is already on the invoking `PATH`. With explicit `--shell`, it must inspect and configure the requested shell's files regardless of the invoking `PATH`. Zsh writes `~/.zshrc`; fish writes `~/.config/fish/config.fish`; bash writes PATH setup to `~/.bashrc` and, when present, also to the first active login override (`~/.bash_profile`, then `~/.bash_login`) so `bash -ilc` cannot bypass it. Bash completions remain in `~/.bashrc` only. Marker checks are per file and remain idempotent. Touching `install.cmd.ts:189-190` requires regenerating `ts/packages/cli/lint-boundaries.json` (`pnpm run validate:boundaries -- --update`), which pins that exact source line.
122 +- KTD5. **Variant delegation with one capability probe.** After the base installer succeeds, locate the installed executable and inspect `"$exe" install --help` for `--shell`. If supported, run `COMPOSIO_BIN_DIR="$bin_dir" "$exe" install --shell <shell>` with stderr attached; if unsupported or that invocation fails, use the inline fallback for the requested shell. Do not add a separate `--version` probe, a requested-vs-current-shell branch, a plain `composio install` retry, or a legacy `COMPOSIO_INSTALL_DIR="$bin_dir"` handoff. Before any inline rc write, validate the resolved bin dir with the CLI's exact unsafe-character policy (`;`, backtick, `$`, `|`, `&`, quotes, parentheses, newline, carriage return, and backslash) and abort without modifying files on rejection; only after validation may rendering substitute a literal `$HOME/` prefix. Inline fallback writes the same per-shell PATH destinations as KTD4: zsh `~/.zshrc`; fish `~/.config/fish/config.fish`; bash `~/.bashrc` plus the first existing login override among `~/.bash_profile`/`~/.bash_login`. An explicit shell variant never suppresses these writes merely because the invoking `PATH` already contains the bin dir. Keeping stderr attached preserves the CLI's PATH guidance via `canDecorate` gating (regression class of #3450).
123 +- KTD6. **Exact-host http exception and redirect policy for hermetic tests:** the https-only validation on `COMPOSIO_GITHUB_URL`/`COMPOSIO_GITHUB_API_BASE_URL`/`COMPOSIO_INSTALL_SCRIPT_URL` additionally accepts `http://` iff the host is true loopback — `localhost`, `127.0.0.1`, `[::1]` (with optional port). `host.docker.internal` is **not** in that set: it is an ordinary hostname that Docker injects into `/etc/hosts` inside containers but that resolves through the normal resolver everywhere else, so allowing it unconditionally would let a rogue LAN resolver serve both the archive and its `checksums.txt` over plaintext. The e2e opts in explicitly via `COMPOSIO_INSTALL_ALLOW_HTTP_HOST=host.docker.internal` (single hostname, exact match, testing-internal — documented in a script comment, never in user docs); without that variable, `http://host.docker.internal` is rejected like any other host. Apply the same parser to every constructed checksum URL and API-returned `browser_download_url`; userinfo and suffix lookalikes never count as an allowed host. Centralize curl calls so https inputs use `--proto '=https' --proto-redir '=https'`, while an explicitly allowed direct-http test URL may enable `http` for the initial request but still permits only https after a redirect. The local server therefore serves allowed http endpoints directly without redirects.
124 +- KTD9. **Single-entrypoint structure, without an arbitrary-truncation guarantee.** `install.sh` and the three variant scripts contain function definitions followed by a single `main "$@"` invocation as the final top-level command. This keeps operational work out of the definition section and avoids an incomplete operational tail. It does **not** promise that every byte-prefix truncation is inert: a stream ending after a syntactically complete `main` token can execute it. That stronger compound-command construction is explicitly out of scope as disproportionate to mise parity. The live `mise.run` script inspected on 2026-07-31 is less strict: after its function definitions it executes bare top-level `install_mise`, then conditionally calls `after_finish_help`; it therefore has the same class of truncation exposure. Variant scripts still download the base installer to a temporary file and require curl success before executing it, as specified in U3.
125 +- KTD7. **Keep existing workflow coverage at launch.** The new Docker e2e adds clean images, fresh-login-shell PATH assertions, and unreleased-CLI validation without replacing either existing workflow. `cli.install-health-check.yml` remains the cheap hourly production monitor with Slack alerting, with assertions updated to the new layout. `cli.test-installation.yml` keeps its current Linux and macOS coverage. After several green scheduled U8 runs, any deduplication is a separate cleanup with its own review; it is not part of U8 or this plan's Definition of Done.
126 +- KTD8. **Version normalization moves into the installer without breaking beta verification:** automatic discovery accepts only stable `@composio/cli@X.Y.Z` releases; explicit positional/env pins accept strictly validated stable or workflow-shaped beta tags (`@composio/cli@X.Y.Z-beta.N`) and normalize the corresponding bare values. This keeps the short docs form (`COMPOSIO_INSTALL_VERSION=0.1.32`) while allowing `build-cli-binaries.yml` to install-test its published beta.
127 +
128 +### High-Level Technical Design
129 +
130 +Install flows (default vs shell-variant, with the KTD5 fallback chain):
131 +
132 +```mermaid
133 +flowchart TB
134 + subgraph default["curl -fsSL composio.dev/install | sh"]
135 + A[validate args + env] --> B[detect platform] --> C[resolve version<br/>positional > COMPOSIO_INSTALL_VERSION > latest stable]
136 + C --> D[download zip + checksums.txt] --> E{sha256 ok?}
137 + E -->|no| F[fatal error]
138 + E -->|yes| G[install bundle to COMPOSIO_INSTALL_DIR<br/>default ~/.composio; write release-tag.txt]
139 + G --> H{COMPOSIO_BIN_DIR == COMPOSIO_INSTALL_DIR?}
140 + H -->|yes| I[legacy layout: no symlink]
141 + H -->|no| J[symlink COMPOSIO_BIN_DIR/composio<br/>-> COMPOSIO_INSTALL_DIR/composio]
142 + I --> K[probe: composio --version]
143 + J --> K
144 + K --> L{COMPOSIO_INSTALL_PLUGINS=1?} -->|yes| M[composio setup --target auto --yes --if-present]
145 + L -->|no| N{COMPOSIO_INSTALL_HELP != 0?}
146 + M --> N
147 + N -->|yes| O[print PATH status + per-shell hint]
148 + end
149 + subgraph variant["curl -fsSL composio.dev/install/zsh | sh"]
150 + V0[download base script to temp file<br/>require curl success; run A..K with args forwarded] --> V2{--shell supported?}
151 + V2 -->|yes| V3[composio install --shell zsh]
152 + V3 -->|fail| V4[inline POSIX rc-append fallback]
153 + V2 -->|no| V4
154 + V3 -->|ok| V6[print restart hint]
155 + V4 --> V6
156 + end
157 +```
158 +
159 +Serving and layout after install:
160 +
161 +```mermaid
162 +flowchart TB
163 + subgraph cloudflare["Cloudflare (external, 302 redirects)"]
164 + R1["composio.dev/install"] --> G1["raw.githubusercontent.com/.../next/install.sh"]
165 + R2["composio.dev/install/zsh|bash|fish"] --> G2["raw.githubusercontent.com/.../next/install/&lt;shell&gt;.sh"]
166 + end
167 + subgraph disk["Resulting layout"]
168 + L1["COMPOSIO_BIN_DIR/composio<br/>default ~/.local/bin (symlink)"] --> L2["COMPOSIO_INSTALL_DIR/composio<br/>default ~/.composio (real binary)"]
169 + L2 -.->|"dirname(process.execPath) resolves here"| L3["bundle dir: acp-adapters/, *.mjs companions,<br/>local-tools-binaries/, release-tag.txt"]
170 + end
171 +```
172 +
173 +### Assumptions
174 +
175 +- A1. `~/.local/bin` reaches PATH via exactly one mechanism on Debian/Ubuntu: the skeleton `~/.profile` guard `if [ -d "$HOME/.local/bin" ]` (evaluated at login — the dir must exist when the shell starts). The entry is lost in three known ways: (a) non-login shells that never source `~/.profile`, (b) bash users with `~/.bash_profile` or `~/.bash_login` — bash reads only the first of `~/.bash_profile`, `~/.bash_login`, `~/.profile`, so `~/.profile` (and its `~/.bashrc` sourcing) is skipped entirely, (c) zsh login shells, which never read `~/.profile`. That is why the default-flow tail must escalate to a required `/install/<shell>` hint in those cases (R1) and why the variant/`--shell` path writes an rc block.
176 +- A2. Bun's compiled-binary `process.execPath` symlink resolution (verified on 1.3.10/darwin; `/proc/self/exe`-backed on Linux) is stable across the Bun versions used by `build-cli-binaries.yml`. The U7 e2e turns this assumption into a regression gate.
177 +- A3. `raw.githubusercontent.com` serves the merged script within its normal CDN staleness window (~5 min); no extra cache-busting is needed.
178 +- A4. The Cloudflare rules are managed by whoever owns the `composio.dev` zone today (outside this repo); requesting them is a coordination task, not a code task.
179 +
180 +### Sequencing
181 +
182 +1. **U1 first, released *stable* before anything else merges.** `install.sh` is served live from `next` on merge and must work against already-released binaries; conversely, the variant scripts want a released CLI that understands `--shell`. Note the release mechanics: merging U1 to `next` only produces a **beta** build (`build-cli-binaries.yml` push trigger), and the installer's automatic tag filter `^@composio/cli@[0-9]+\.[0-9]+\.[0-9]+$` makes betas invisible to latest-version discovery even though explicit beta pins remain valid. After the automatic beta finishes, resolve it from live GitHub state, verify its exact tag and source commit, all six uploaded assets, and the green installation workflow, then stop and obtain explicit user approval for that candidate before dispatching `promote-stable`. U2-U5 may merge only after the resulting stable `@composio/cli@X.Y.Z` containing `--shell` is published. `@composio/cli` is Changesets-ignored — release notes go in `CHANGELOG.md`.
183 +2. **U2-U5 merge together** (installer rewrite + variants + script tests + CI updates) — CI must flip to the new contract in the same PR or the workflows go red.
184 +3. **U6 (docs) merges after the Cloudflare `/install/<shell>` rules are confirmed live** (external dependency), so docs never advertise dead URLs. The base-flow docs changes could ship with U2-U5 if the variant section is the only gated part; prefer one docs PR after confirmation for simplicity.
185 +4. **U7-U8 (e2e) follow after the rewrite lands** — explicit user-sequenced follow-up.
186 +
187 +---
188 +
189 +### Two-Stage Execution
190 +
191 +The stages are sequential, not parallel: Stage 2 requires Stage 1's stable release. They are independent implementation contexts: a Stage 2 implementer treats the published CLI behavior as an external contract and does not need the U1 source diff or its design history.
192 +
193 +#### Stage 1 — CLI capability release
194 +
195 +- **Scope:** U1 only: `composio install --shell`, bin-directory PATH logic, and the restart-hint fix.
196 +- **Completion gate:** Focused CLI tests, boundary validation, root lint/typecheck, then a stable `@composio/cli` release. Verify the exact tag, source commit, six assets, and installation workflow; obtain explicit approval before promoting the verified beta candidate.
197 +- **Handoff artifact:** Record the stable version/tag, source commit, asset-verification evidence, and this immutable CLI contract: `composio install --shell zsh|bash|fish` configures the explicitly requested shell and honors `COMPOSIO_BIN_DIR` for PATH setup.
198 +- **Context rule:** A fresh Stage 2 context reads this handoff plus the installer product contract and U2-U8; it does not need U1 implementation files, tests, or release mechanics.
199 +
200 +#### Stage 2 — Installer rollout and system proof
201 +
202 +- **Scope:** U2-U8: POSIX installer, shell variants, hermetic script tests, CI/CODEOWNERS, docs, Docker e2e, and its workflow.
203 +- **Entry gate:** The Stage 1 handoff is complete and its stable CLI version is publicly installable. Cloudflare redirect confirmation remains a separate gate for U6's variant documentation.
204 +- **Execution contexts:** Use fresh implementation contexts for U2-U5 (atomic live-on-merge installer change), U6 (documentation), and U7-U8 (Docker e2e and CI). Each context relies on the published Stage 1 contract and its own unit-level verification, not on prior context history.
205 +- **Completion gate:** All U2-U8 verification passes, post-merge production checks are green, and the Definition of Done is satisfied.
206 +
207 +---
208 +
209 +## Implementation Units
210 +
211 +### U1. `composio install --shell` flag, bin-dir PATH logic, restart-hint fix
212 +
213 +- **Goal:** The CLI command can be invoked shell-targeted by the variant scripts and writes correct PATH guidance for the new layout.
214 +- **Requirements:** R6, R7, R8; enables R5, R14.
215 +- **Dependencies:** none (ships first).
216 +- **Files:** `ts/packages/cli/src/commands/install.cmd.ts`, `ts/packages/cli/test/src/commands/install.cmd.test.ts`, `ts/packages/cli/lint-boundaries.json` (regenerate), `ts/packages/cli/CHANGELOG.md`.
217 +- **Approach:** Add `Options.choice('shell', ['zsh','bash','fish'] as const).pipe(Options.optional)` and unwrap the resulting `Option` with `Option.getOrUndefined`; the explicit value replaces `detectShell` only when present (precedent: optional `--mode` in `dev.cmd.ts`, not defaulted `--target` in `setup.cmd.ts`). Replace the hardcoded `~/.composio` default at `install.cmd.ts:189-190` with KTD4's `COMPOSIO_BIN_DIR` resolution order; `COMPOSIO_INSTALL_DIR` remains the installer's bundle directory and is no longer the CLI command's PATH input. Rc blocks contain exactly the `# Composio CLI` marker plus a literal PATH line (and the fish equivalent). **Exact-string rules:** the current `pathBlockForShell` interpolates the raw directory (`tildify` is display-only — do not emit `~`, which does not expand inside quotes); emit the absolute bin dir, substituting a literal `$HOME/` prefix for the home directory *after* the `isUnsafePath` check (that check rejects `$`, so the substitution must not run before it). Drop the historical `export COMPOSIO_INSTALL_DIR=...` line everywhere it is emitted, including the undetected-shell fallback message and fish block. Split bash PATH destinations from completion destinations: PATH goes to `~/.bashrc` plus the first existing login override (`~/.bash_profile`, then `~/.bash_login`), while completions remain only in `~/.bashrc`. In auto-detected-shell mode, a bin dir already present on the invoking `PATH` produces no PATH write or restart hint. In explicit `--shell` mode, do not use the invoking `PATH` to suppress the requested shell's marker-idempotent writes. Read `PATH`, `SHELL`, and `COMPOSIO_BIN_DIR` via `effect/Config`, then pass resolved values into pure helpers rather than adding new raw-environment boundaries. Fix restart hints per R8 and keep other completions semantics unchanged. Existing tests at `install.cmd.test.ts:321/:349/:432` assert the old block content and marker-always semantics — rewrite them to the new contract.
218 +- **Patterns to follow:** `ts/packages/cli/src/commands/setup.cmd.ts` for `Options.choice`; existing atomic-write and marker logic in `install.cmd.ts` (keep both); test conventions in `install.cmd.test.ts` (`[When]`/`[Then]`, `TestLive`).
219 +- **Test scenarios:**
220 + - `--shell zsh|bash|fish` overrides a conflicting `$SHELL` (e.g. `SHELL=/bin/bash` + `--shell zsh` writes `~/.zshrc`).
221 + - Existing `composio install` invocation with no `--shell` still parses and follows auto-detection.
222 + - Covers AE2 (partially). `COMPOSIO_BIN_DIR=/custom/bin composio install --shell zsh` writes a PATH line for `/custom/bin`.
223 + - Auto-detected shell + bin dir already on `PATH` → nothing written, "already on PATH" reported, no restart hint; bin dir not on `PATH` → block written.
224 + - Explicit `--shell zsh` with a conflicting invoking shell and with the bin dir already on the invoking `PATH` still writes `~/.zshrc`; re-run produces no duplicate marker or line.
225 + - Emitted PATH line uses `$HOME/`-prefixed absolute path — never a literal `~` (tilde does not expand inside double quotes).
226 + - Env unset, `~/.local/bin/composio` exists → PATH line targets `~/.local/bin`; env unset and no symlink → targets `dirname(process.execPath)`.
227 + - Bash always configures `~/.bashrc`; when `~/.bash_profile` exists it also receives one PATH block, and when only `~/.bash_login` exists that file receives the login PATH block. `bash -ilc 'command -v composio'` succeeds in both cases.
228 + - Bash hint prints `source ~/.bashrc` plus a login-shell note when a login override changed; no literal `exec $SHELL` anywhere in output.
229 + - Existing per-shell, completions, unsafe-path, non-TTY-stderr tests still pass with updated expectations (block no longer contains `COMPOSIO_INSTALL_DIR=`).
230 +- **Verification:** CLI package vitest suite green; `pnpm run validate:boundaries` green; `command pnpm run lint` and `pnpm typecheck` green.
231 +
232 +### U2. Rewrite `install.sh` (POSIX, install-only default, new layout and env surface)
233 +
234 +- **Goal:** The served installer implements R1-R4 and KTD2/KTD3/KTD6/KTD8.
235 +- **Requirements:** R1, R2, R3, R4, R14, R15.
236 +- **Dependencies:** U1 released (only so the ecosystem is ready; the default flow itself has no new-CLI dependency).
237 +- **Files:** `install.sh`.
238 +- **Approach:** Full rewrite as `#!/bin/sh` + `set -eu`, structured per KTD9 (all logic in functions; a single `main "$@"` as the last line). Port every behavior worth keeping from the current script: validation order (args → platform → prereqs, which the tests assert), owner/repo/URL validation, WSL message, Rosetta detection, 5-page GitHub releases pagination with the stable-tag awk/sed filter, `composio-<target>.zip` asset match, checksum handling, `mktemp -d` + `trap` cleanup, bundle install preserving relative paths in `COMPOSIO_INSTALL_DIR`, `release-tag.txt`, `COMPOSIO_CLI_INVOCATION_ORIGIN=installer` tagging, `--agent`/`--no-plugins`/positional-tag parsing. New behavior: KTD3 env surface (`COMPOSIO_BIN_DIR`, `COMPOSIO_INSTALL_VERSION` with KTD8 stable/beta normalization, `COMPOSIO_QUIET` info-gating, `COMPOSIO_DEBUG` tracing, `COMPOSIO_INSTALL_HELP`), KTD2 symlink step comparing the separately resolved bundle/bin dirs and handling existing files/directories, plugins default `0`, install-only default (no `composio install` delegation in the default flow; keep the `--version` probe as a smoke check), KTD6 exact-host/protocol policy applied to configured, constructed, and API-returned URLs, and a mise-style tail: print install status, whether the bin dir is on PATH, and per-`$SHELL` guidance pointing at `/install/<shell>` (suppressed by `COMPOSIO_INSTALL_HELP=0` or `COMPOSIO_QUIET=1`). Automatic release discovery stays stable-only; explicit env/positional tags accept the strict beta shape required by the binary release workflow. Replace bashisms per the inventory (use `printf`, `case` instead of `[[ =~ ]]` where possible or `expr`/`grep` for regex, positional-args iteration instead of arrays, `while read` loops without process substitution); do not use `local` in any served script. Keep external-tool usage PATH-shadowable (`curl`, `unzip`, `uname`, `sha256sum`/`shasum`, `ln`, `mktemp`) — the test harness depends on it; no `git`.
239 +- **Execution note:** Port the unit-test harness (U4) in lockstep. The harness remains Bash, but runs every installer case once with `sh` and again with `dash` when available, creating a fresh home/install/temp fixture per interpreter. The harness is the fastest feedback loop for this file.
240 +- **Test scenarios:** covered by U4 (script-level); U7 is the post-merge system regression gate and is not a completion dependency for U2.
241 +- **Verification:** `bash test/install-sh-release-resolution.test.sh` green with its internal `sh`/`dash` matrix; `shellcheck -s sh install.sh` clean with no POSIX-portability disables.
242 +
243 +### U3. Shell-variant scripts `install/zsh.sh`, `install/bash.sh`, `install/fish.sh`
244 +
245 +- **Goal:** `/install/<shell>` endpoints deliver base install + deterministic shell setup (R5).
246 +- **Requirements:** R5, R9, R14.
247 +- **Dependencies:** U2 (shares the base flow).
248 +- **Files:** `install/zsh.sh`, `install/bash.sh`, `install/fish.sh` (new directory at repo root, beside `install.sh`).
249 +- **Approach:** Three small POSIX scripts generated from one shape (hand-written near-identical files are fine at n=3; a generator is over-engineering — mise generates because it templates checksums, which we don't). Each defines its own `info`/`error` honoring `COMPOSIO_QUIET`/`COMPOSIO_DEBUG`; validates the production or overridden `COMPOSIO_INSTALL_SCRIPT_URL` under KTD6; downloads the base script with the centralized protocol policy to `"$tmpdir/install.sh"`; aborts before any rc write if the download fails or is empty; then runs `COMPOSIO_INSTALL_HELP=0 sh "$tmpdir/install.sh" "$@"`, forwarding every positional flag/version and the caller's environment. Only after that command succeeds does it locate the real binary at `${COMPOSIO_INSTALL_DIR:-$HOME/.composio}/composio`, resolve and safety-check `${COMPOSIO_BIN_DIR:-$HOME/.local/bin}` under KTD5, and apply the fallback chain with `COMPOSIO_CLI_INVOCATION_ORIGIN=installer` set and stderr left attached. Tail prints the restart hint ("restart your shell or run `source ...`") mirroring mise's variant tail. Mode-(b)-style overrides keep working because the child `sh` inherits `COMPOSIO_GITHUB_*`, `COMPOSIO_INSTALL_DIR`, and `COMPOSIO_BIN_DIR`. A piped script cannot know the origin it was itself fetched from, so hardcode the production URL and allow a `COMPOSIO_INSTALL_SCRIPT_URL` override (consumed first by U4's harness, then by U7's e2e; document as internal/testing in a script comment, never in user docs). Structure each variant per KTD9 (function definitions + a final `main "$@"`) without `local` or other non-POSIX builtins.
250 +- **Test scenarios:**
251 + - Covers AE2, AE7 (container-level in U7): variant → fresh-shell PATH assertion; pinned old release → target-specific inline fallback.
252 + - Script-level (U4 harness, fake `curl`/`composio`): capability probe checks `install --help` output for `--shell`; when supported, `--shell <x>` argv is logged; when supported but the run fails, inline fallback fires for the requested shell; when unsupported, inline fallback edits the requested shell's startup files without a plain retry; `COMPOSIO_INSTALL_HELP=0` is exported to the nested install; `COMPOSIO_INSTALL_SCRIPT_URL` override is respected; positional version/flags arrive unchanged at the base script; failed or empty base-script downloads exit non-zero without changing any rc file; an unsafe bin dir exits non-zero before any rc-file change.
253 +- **Verification:** U4 harness cases green; `shellcheck -s sh` clean.
254 +
255 +### U4. Port the installer test harness to the new contract
256 +
257 +- **Goal:** Script-level regression suite proves the rewritten installer and variants without network access.
258 +- **Requirements:** R12 (partial), guards R1-R5.
259 +- **Dependencies:** U2, U3 (developed in lockstep with U2).
260 +- **Files:** `test/install-sh-release-resolution.test.sh`.
261 +- **Approach:** Keep the harness architecture exactly (Bash runner; hermetic `PATH` of fake `curl`/`unzip`/`uname`/`sha256sum` executables; fake `composio` logging argv; no-`git` assertion), but parameterize only the served-script interpreter. Run the full case matrix through `sh` and, when present, `dash`, with a separate home/install/temp fixture for each interpreter so one pass cannot satisfy another. Update expected argv/strings to the new contract (no default `composio install` delegation; `setup` only when `COMPOSIO_INSTALL_PLUGINS=1`; preserved bundle-dir plus separate bin-dir assertions; plugins-default flip; stable/beta explicit-version normalization; quiet/debug/help gating; KTD6 URL/protocol policy). Add variant-script coverage using the same fakes, including fatal/empty download, exact argument forwarding, unsafe-bin-dir no-write, API-returned unsafe URLs, malicious userinfo/suffix hosts, and redirect-downgrade rejection. Keep missing `checksums.txt` as warn-and-continue per R4; if a manifest is downloaded, malformed hashes or mismatches remain fatal. The release-guide literal change moves to U6 so U2-U5 can stay green while `INSTALL.md` still documents the old compatible layout.
262 +- **Test scenarios** (the suite itself — key cases beyond ports of existing ones):
263 + - Default flow performs no rc-file writes and never invokes `composio install` (fake binary logs prove absence).
264 + - Bundle installs to `COMPOSIO_INSTALL_DIR`; symlink is created at default `COMPOSIO_BIN_DIR`; equal resolved directories → no symlink (AE5); a legacy rc export of `COMPOSIO_INSTALL_DIR=$HOME/.composio` with `COMPOSIO_BIN_DIR` unset still creates the default symlink without heuristic rc scanning (AE5b); existing regular file at the symlink path is replaced; directory at the symlink path → fatal.
265 + - Post-install tail escalates to a required `/install/<shell>` hint when `~/.bash_profile` exists or the bin dir is absent from `PATH` (R1).
266 + - Version precedence positional > `COMPOSIO_INSTALL_VERSION` > latest; `0.1.32` normalized (AE3).
267 + - Automatic resolution ignores prereleases; explicit `@composio/cli@98.0.0-beta.123` is accepted and downloaded; malformed prerelease forms are rejected before network access.
268 + - Checksum mismatch fatal (AE4); missing checksums warns and continues.
269 + - `COMPOSIO_QUIET=1` silences info but not errors; `COMPOSIO_DEBUG=1` emits traces; `COMPOSIO_INSTALL_HELP=0` suppresses tail.
270 + - `COMPOSIO_GITHUB_URL=http://127.0.0.1:8929` accepted; `http://evil.example` rejected; `http://host.docker.internal:8929` rejected unless `COMPOSIO_INSTALL_ALLOW_HTTP_HOST=host.docker.internal` is set (KTD6). Same acceptance/rejection matrix for `COMPOSIO_INSTALL_SCRIPT_URL`, constructed checksum URLs, and API-returned asset URLs; userinfo/suffix-host tricks and https-to-http redirects are rejected before extraction.
271 + - Every served script keeps operational work inside functions and has exactly one final top-level `main "$@"` invocation (KTD9 structural check); arbitrary byte-prefix inertness is not tested or claimed.
272 + - Script runs identically under `sh` and `dash` (matrix the interpreter).
273 +- **Verification:** `bash test/install-sh-release-resolution.test.sh` green (including its internal `sh`/`dash` matrix); `pnpm test` green from the root.
274 +
275 +### U5. Update install-related CI workflows to the new contract
276 +
277 +- **Goal:** Existing CI asserts the new layout and keeps its monitoring value (R12, KTD7).
278 +- **Requirements:** R12.
279 +- **Dependencies:** U2-U4 (same PR).
280 +- **Files:** `.github/workflows/cli.test-installation.yml`, `.github/workflows/cli.install-health-check.yml`, `.github/workflows/build-cli-binaries.yml` (executable smoke step only), `.github/CODEOWNERS`.
281 +- **Approach:** `cli.test-installation.yml`: point invocations at `sh install.sh`; assert the real bundle under `COMPOSIO_INSTALL_DIR` (default `$HOME/.composio`) and the entry-point symlink under `COMPOSIO_BIN_DIR` (default `$HOME/.local/bin`); update the rc-grep assertions (blocks now appear only in shell-variant/`--shell` legs; add such a leg or drop the rc assertions from default-flow legs); keep the macOS matrix; fix the always-green "error handling" step to actually fail on unexpected success; add a `shellcheck -s sh install.sh install/*.sh` step (shellcheck is preinstalled on `ubuntu-latest`; no workflow currently runs it). `cli.install-health-check.yml` remains production-only under its existing schedule and manual dispatch: replace the manual `$GITHUB_PATH` push of `~/.composio` with `~/.local/bin`, assert both symlink and bundle exist, and update the between-legs cleanup to remove installer-owned bundle artifacts plus the symlink without deleting CLI user state. Keep pinned-then-latest ordering and Slack alerting. `build-cli-binaries.yml`: update only executable smoke invocations to `sh`; its generated guide moves with `INSTALL.md` in U6 so the static two-guide contract changes atomically. `.github/CODEOWNERS`: add root-anchored `/install.sh @CryogenicPlanet` and `/install/ @CryogenicPlanet`; before merge, verify the live `next` ruleset has `require_code_owner_review: true` rather than treating a request as sufficient.
282 +- **Test scenarios:** Test expectation: none — CI config; `cli.test-installation.yml` proves the PR checkout before merge, and the production health check is proven after merge when `/install` resolves the new script.
283 +- **Verification:** Before merge, `cli.test-installation.yml` is green against the PR ref, `pnpm test` is green with the existing compatible guide literals, and the live `next` ruleset reports code-owner review required. Do not dispatch `build-cli-binaries.yml` merely as validation because its default action publishes a beta; the executable smoke change is covered statically here and exercised by the next authorized beta. After U2-U5 merge, dispatch the production health check and require it green.
284 +
285 +### U6. Docs rewrite (cli.mdx Install section + every one-liner touchpoint)
286 +
287 +- **Goal:** Install docs at mise depth; zero stale one-liners anywhere (R10, R11).
288 +- **Requirements:** R10, R11.
289 +- **Dependencies:** U2-U5 merged; Cloudflare `/install/<shell>` rules confirmed live (external).
290 +- **Files:** `docs/content/docs/cli.mdx`, `docs/lib/source.ts` (the hardcoded snippet at ~line 266 feeding `llms.txt`), `docs/components/ai-tools-banner.tsx`, `docs/components/home-surfaces.tsx`, `README.md`, `docs/content/docs/claude-code-plugin.mdx`, `INSTALL.md`, `.github/workflows/build-cli-binaries.yml` (generated install guide), `test/release-workflow.test.ts`, `docs/content/changelog/<MM-DD-YY>-installer.mdx` (new).
291 +- **Approach:** Rewrite `## Install` in place in `cli.mdx` (convention: everything CLI lives on one page; a separate page would need a `meta.json` allowlist entry and forks content). Structure mirrors mise's install page: canonical one-liner (`curl -fsSL https://composio.dev/install | sh`), "or with options" example, shell-specific setup via `<Tabs groupId="shell" items={['zsh','bash','fish']} persist>` (established idiom — see `docs/content/docs/quickstart.mdx:21` for the `groupId`/`persist` shape) showing the `/install/<shell>` one-liners and what each writes where, an options table (3-column `Variable | Description | Default` — condensed from the 4-column table shape in `ts/packages/cli/README.md:58-70`) covering the full KTD3 surface including the distinct bundle/bin directories, verification steps (`composio --version`, `which composio`), supported platforms, alternatives (manual GitHub-release install), and safe manual uninstall. Normal uninstall removes `${COMPOSIO_BIN_DIR:-$HOME/.local/bin}/composio` and only the exact release-bundle artifacts under `${COMPOSIO_INSTALL_DIR:-$HOME/.composio}` (`composio`, `release-tag.txt`, the five named `run-*.mjs` wrappers, `services/`, `acp-adapters/`, and `local-tools-binaries/`), then removes the `# Composio CLI` blocks; it must not delete the bundle directory itself because that directory also holds auth, configuration, and cache state. Document `rm -rf "${COMPOSIO_INSTALL_DIR:-$HOME/.composio}"` only in a separate, explicit **Purge all CLI state** warning that names the data loss. Voice per `good-docs-writing`: second person, runnable example first, no em-dashes, backtick every command/path/var. Links relative. Update the other six touchpoints and the workflow-generated guide to the same one-liner (`| sh` not `| bash`); `INSTALL.md` gets a full factual rewrite (it currently documents a non-existent `COMPOSIO_INSTALL` var and wrong paths) sharing the cli.mdx content in condensed form. Update `test/release-workflow.test.ts` in the same unit so both guides atomically require the exact literals `cp -Rp "$bundle"/. "$COMPOSIO_INSTALL_DIR/"`, `mkdir -p "$COMPOSIO_BIN_DIR"`, and `ln -sf "$COMPOSIO_INSTALL_DIR/composio" "$COMPOSIO_BIN_DIR/composio"`, while retaining `INSTALL.md`'s `## Manual Installation` / `## Verification` heading pair. Changelog entry follows `docs/agent-guidance/guides/changelog.md` (frontmatter `title` + `date`, sections from `###`, no emojis).
292 +- **Test scenarios:** Test expectation: none — docs; verified by build/link checks and the static tests below.
293 +- **Verification:** From `docs/`: `bun run types:check`, `bun run lint`, `bun run build`, `bun run lint:links`, and `bun test tests/static/` green; from the repo root, `pnpm test:release-workflow` is green. Inventory every `composio.dev/install` and raw `install.sh` URL under `docs/`, `README.md`, `INSTALL.md`, and `.github/workflows`, then require `rg -n '\|[[:space:]]+bash\b|bash[[:space:]]+[^[:space:]]*install\.sh' docs/ README.md INSTALL.md .github/workflows --glob '!docs/plans/**'` to return nothing. This catches literal and Markdown-escaped pipes plus direct Bash invocation. Rendered `llms.txt` contains the new one-liner.
294 +
295 +### U7. Docker install e2e suite (`ts/e2e-tests/cli/install/`)
296 +
297 +- **Goal:** Container-level proof of the install contract: fresh zsh and bash-only machines end with `composio` on PATH in a fresh login shell (R13; pins KTD2's execPath assumption per A2).
298 +- **Requirements:** R13; covers AE1, AE2, AE6, AE7.
299 +- **Dependencies:** U2-U5 landed (follow-up phase).
300 +- **Files:** `ts/e2e-tests/cli/install/{e2e.test.ts,package.json,README.md,release-server.ts}`, `ts/e2e-tests/_utils/Dockerfile.install` (new; build-arg `INSTALL_SHELL=zsh|bash`), extensions in `ts/e2e-tests/_utils/src/image-lifecycle.ts` + `config.ts`/`const.ts` (second image kind: `composio-e2e-install:<shell>`; opt-out of the host `~/.composio` read-only bind mount because an install suite needs a virgin `$HOME`), `ts/packages/cli/test/src/services/upgrade-binary.test.ts`, root `package.json`, generated `pnpm-lock.yaml`, and `turbo.jsonc`.
301 +- **Approach:** New Dockerfile(s) based on `debian:bookworm-slim`/`ubuntu` with `curl`, `unzip`, `ca-certificates`, and either `zsh` (variant leg) or bash-only (default leg); no CLI preinstalled because the existing `Dockerfile.cli` bakes in the binary and uses a different home/PATH contract. Create the test user with `useradd -m -s /bin/bash|/bin/zsh` (`useradd -m` copies `/etc/skel`, including `~/.profile`), set explicit `USER`/`HOME`/`WORKDIR` and a default `PATH` including `/usr/bin`, and do not pre-create `~/.local/bin`. Do not inherit `runCliContainer`'s hardcoded host `~/.composio` bind mount (`image-lifecycle.ts:673`); add the opt-out in `_utils`. Package name `@e2e-tests/cli-install` defines `typecheck: "tsc --noEmit"` and `test:e2e:install`, but no `test:e2e` or `test:e2e:cli` keys because root `test:e2e` filters `@e2e-tests/*`; add the root `test:e2e:install` script, regenerate the lockfile with pnpm, and add the Turbo task. The host-read env contract is `COMPOSIO_INSTALL_E2E_MODE=local|prod`, `COMPOSIO_INSTALL_E2E_SHELL=bash|zsh`, `COMPOSIO_INSTALL_E2E_VERSION=latest|@composio/cli@0.3.1` (prod only), and `COMPOSIO_INSTALL_E2E_RELEASE_DIR=<absolute single-fixture directory>` (local only); allowlist all four on `test:e2e:install` in `turbo.jsonc`, and have the workflow forward each relevant matrix/artifact value explicitly. **Prod mode** curls `https://composio.dev/install[...]` directly. **Local mode** uses a minimal server co-located with the suite; it serves checked-out `install.sh` + `install/*.sh`, `/repos/<o>/<r>/releases?page=N`, and `/releases/download/<tag>/{composio-linux-x64.zip,checksums.txt}` for one fixed `@composio/cli@98.0.0` fixture. It does not emulate the CLI upgrade API. The server is reachable at `http://host.docker.internal:<port>` via `--add-host host.docker.internal:host-gateway`. Inject only the installer overrides `COMPOSIO_GITHUB_URL`, `COMPOSIO_GITHUB_API_BASE_URL`, and `COMPOSIO_INSTALL_SCRIPT_URL`, plus `COMPOSIO_INSTALL_ALLOW_HTTP_HOST=host.docker.internal` required by KTD6. For AE6, extend the existing focused `upgrade-binary.test.ts` suite using `DEBUG_OVERRIDE_UPGRADE_TARGET`: install a real bundle target behind an entry-point symlink, run the replacement, and assert the real target changes while the symlink path and target remain unchanged.
302 +- **Test scenarios:**
303 + - Covers AE1: bash-only image, default install, then `bash -ilc 'composio --version'` succeeds and `command -v composio` resolves to `~/.local/bin/composio`.
304 + - The `~/.bash_profile` trap (B-class regression guard): bash image with a pre-existing one-line `~/.bash_profile` → default install → tail presents `/install/bash` as required; running `/install/bash` then makes `bash -ilc 'composio --version'` pass.
305 + - Covers AE2: zsh image, `/install/zsh` variant, then `zsh -ilc 'composio --version'` succeeds; `~/.zshrc` contains exactly one `# Composio CLI` marker after running the variant twice (idempotency).
306 + - Symlink integrity: install local fixture `@composio/cli@98.0.0`; resolve `~/.local/bin/composio` to `~/.composio/composio`; assert `release-tag.txt` and the packaged run-companion files sit beside that real target; invoke the entry point through `PATH` and require `composio --version` to report `98.0.0` (the KTD2/A2 regression gate).
307 + - Covers AE7 (prod mode, nightly): exact stable `@composio/cli@0.3.1` (published from `98b7fcee272a0ca390eff7467352109f59578a3a`, before U1) installs via positional arg and passes the fresh-shell assertion; first assert its `composio install --help` lacks `--shell`, then run the variant and prove the compatibility fallback configures the requested shell.
308 + - Covers AE6 (focused unit test): replacing the real bundle binary through `DEBUG_OVERRIDE_UPGRADE_TARGET` changes that target without replacing or retargeting its entry-point symlink.
309 + - Failure path: server returning a corrupted zip → installer exits non-zero, nothing installed to `~/.local/bin`.
310 +- **Verification:** `pnpm turbo typecheck --filter=@e2e-tests/cli-install` green; `pnpm vitest run test/src/services/upgrade-binary.test.ts` from `ts/packages/cli` is green; `pnpm turbo test:e2e:install` is green locally in both modes (local mode hermetic; prod mode against live URLs).
311 +
312 +### U8. Install e2e workflow (`.github/workflows/cli.install-e2e.yml`)
313 +
314 +- **Goal:** CI wiring for U7: nightly production coverage and PR-time validation of installer+CLI changes together, producing one tagged local release fixture per workflow run (R13).
315 +- **Requirements:** R13.
316 +- **Dependencies:** U7.
317 +- **Files:** `.github/workflows/cli.install-e2e.yml`.
318 +- **Approach:** Triggers: `schedule` (daily, mirroring `ts.examples-nightly.yml`'s shape: `concurrency` group without cancel, `permissions: contents: read`, `timeout-minutes`, `fail-fast: false`), `workflow_dispatch`, and `pull_request` with `paths:` filter `install.sh`, `install/**`, `test/install-sh-release-resolution.test.sh`, `ts/packages/cli/**`, `ts/packages/cli-local-tools/**`, `ts/e2e-tests/cli/install/**`, `ts/e2e-tests/_utils/**`, `.github/actions/setup-node-pnpm-bun/action.yml`, `.github/workflows/cli.install-e2e.yml`, `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `turbo.jsonc`, `mise.toml`, `mise.lock` (repo convention: plain `paths:` globs, no `dorny/paths-filter`). Guard production jobs to `schedule`/`workflow_dispatch` and local fixture jobs to `pull_request`. **Nightly/dispatch job:** use `matrix.include` for exactly three prod cases: latest on bash, latest on zsh, and `@composio/cli@0.3.1` on zsh. Alert on failure via `SLACK_RELEASE_WEBHOOK_URL` (precedent: `cli.install-health-check.yml`). **PR jobs:** one `build` job runs `./.github/actions/setup-node-pnpm-bun`, `pnpm install --frozen-lockfile`, `pnpm turbo typecheck --filter=@e2e-tests/cli-install`, the focused `upgrade-binary.test.ts` case, and `pnpm build:packages`; then from `ts/packages/cli` it builds/packages once with `RELEASE_TAG=@composio/cli@98.0.0`, stages `composio-linux-x64.zip` plus a freshly generated `checksums.txt` under one fixture directory, and verifies the archive's embedded `release-tag.txt` and executable `--version` before uploading it via `actions/upload-artifact`. `build-cli-binaries.yml` is push-to-next-only and not `workflow_call`-reusable, so PR runs must produce this non-published fixture. A matrix `{shell: [zsh, bash]}` e2e job downloads the artifact and runs U7 in local mode with the relevant U7 env contract. Cache posture: pnpm-store caching via the composite action with `cache-save: 'false'` on PRs; artifact upload/download fans the single build out to both shell jobs.
319 +- **Test scenarios:** Test expectation: none — CI config; local mode is proven by the PR trigger before merge, and production mode is proven by a dispatch after the workflow reaches the default branch.
320 +- **Verification:** Before merge, the focused typecheck, upgrade unit test, and local-mode jobs are green through the workflow's `pull_request` trigger. The new workflow cannot be manually dispatched until its file exists on the default branch. After merge, run `workflow_dispatch` and require all three prod cases green. Leave the existing Linux installation workflow coverage unchanged at launch; consider deduplication only as a separately reviewed cleanup after several green scheduled runs.
321 +
322 +---
323 +
324 +## Verification Contract
325 +
326 +| Gate | Command | Applies to |
327 +|---|---|---|
328 +| Installer unit tests | `bash test/install-sh-release-resolution.test.sh` (the Bash harness internally matrices `sh`/`dash`; also first step of root `pnpm test`) | U2, U3, U4 |
329 +| POSIX lint | `shellcheck -s sh install.sh install/*.sh` | U2, U3 |
330 +| CLI tests | `pnpm vitest run` in `ts/packages/cli` (or `pnpm test` from root) | U1 |
331 +| Upgrade symlink regression | `pnpm vitest run test/src/services/upgrade-binary.test.ts` in `ts/packages/cli` | U7, U8 |
332 +| Boundary manifest | `pnpm run validate:boundaries` (regenerate with `-- --update` when touching registered lines) | U1 |
333 +| Lint / typecheck | `command pnpm run lint` (not `pnpm lint` — a local hook breaks it), `pnpm typecheck` | U1 |
334 +| Install-e2e typecheck | `pnpm turbo typecheck --filter=@e2e-tests/cli-install` | U7, U8 |
335 +| Docs | `bun run types:check && bun run lint && bun run build && bun run lint:links && bun test tests/static/` from `docs/` | U6 |
336 +| Install e2e | `pnpm turbo test:e2e:install` (local mode hermetic; prod mode via env) | U7, U8 |
337 +| Workflows | Before merge: dispatch `cli.test-installation.yml` and require the `cli.install-e2e.yml` PR-triggered local jobs. After merge: dispatch the production health and install-e2e workflows | U5, U8 |
338 +
339 +---
340 +
341 +## Definition of Done
342 +
343 +- All eight units implemented with their per-unit verification green; full `pnpm test`, `pnpm typecheck`, `command pnpm run lint` green at root.
344 +- AE1-AE7 each demonstrably covered by a named U4 script test, U7 container test, or focused CLI unit test.
345 +- Automatic release discovery remains stable-only, while strict explicit stable and beta tags both pass the installer harness.
346 +- The local install e2e uses one explicitly tagged `@composio/cli@98.0.0` fixture and proves symlinked execution, bundle-relative sidecar placement, and version lookup; the focused upgrade unit test proves replacing the real bundle target leaves the entry-point symlink unchanged.
347 +- No stale one-liner: the U6 URL inventory has been reviewed and `rg -n '\|[[:space:]]+bash\b|bash[[:space:]]+[^[:space:]]*install\.sh' docs/ README.md INSTALL.md .github/workflows --glob '!docs/plans/**'` returns nothing; `INSTALL.md` contains no reference to `COMPOSIO_INSTALL` (the non-existent var) or `~/.composio/bin`.
348 +- Normal uninstall documentation removes only the entry-point symlink, exact release-bundle artifacts, and managed rc blocks; deleting the entire bundle directory appears only under an explicit purge-all-state warning.
349 +- CLI release containing U1 published before U2-U6 merge (Sequencing step 1), with the exact beta tag/source commit/six assets/installation run verified and that candidate explicitly approved before promotion; `CHANGELOG.md` entry for the CLI changes; no changeset for `@composio/cli` (Changesets-ignored).
350 +- Cloudflare request for the three `/install/<shell>` redirect rules filed with the zone owner, and docs advertising them merged only after confirmation.
351 +- `.github/CODEOWNERS` has root-anchored owners for `/install.sh` and `/install/`, and the live `next` ruleset reports `require_code_owner_review: true`, before U2 merges — those paths are live-on-merge production.
352 +- No abandoned experimental code left in the diff; no AI attribution in commits/PRs; Conventional Commits style.
353 +
354 +---
355 +
356 +## Risks & Dependencies
357 +
358 +- **External: Cloudflare redirect rules** for `/install/zsh|bash|fish` (and no change needed for `/install` itself). Owner: `composio.dev` zone admin, outside this repo. Blocking only for U6's variant docs section and prod-mode variant e2e legs.
359 +- **Bun execPath behavior** (KTD2/A2): verified empirically on Bun 1.3.10; pinned forever after by U7's symlink-integrity scenario. If a future Bun changes it, the e2e catches it before users do.
360 +- **`~/.local/bin` PATH variance:** guaranteed on Debian/Ubuntu skeletons only when the dir exists at login; zsh login shells never read `~/.profile`. Mitigated by the default flow's PATH-status hint and the variant flow's rc block; measured by AE1/AE2.
361 +- **Live-on-merge exposure is a supply-chain control, not just an operational one:** `install.sh` and `install/**` on `next` become production the moment they merge (≤ ~5 min CDN staleness), with no release gate of the kind the binaries get. U2-U5 merge as one PR after the existing installation workflow is green; U8's new workflow is proven by its PR-triggered local jobs, then by a production dispatch after merge. The default flow requires no unreleased CLI feature (R14), but the required mitigation is root-anchored CODEOWNERS entries plus live `next` enforcement of code-owner review. The current checkout has neither installer ownership entry, and the live ruleset reported `require_code_owner_review: false` on 2026-07-31; both must be corrected and re-verified before U2 merges.
362 +- **The Cloudflare redirect rules are a production supply-chain control living outside this repo's review process.** A changed redirect target reroutes every install with no signal in git. Ask the zone owner whether change alerting exists on the `/install*` rules when filing the rule request.
363 +- **Literal-string couplings:** `test/release-workflow.test.ts:616-619` (release-guide snippets) and `ts/packages/cli/lint-boundaries.json` (exact source lines in `install.cmd.ts`) both break silently-looking builds if forgotten — called out in U6/U1 respectively.
364 +- **`docs/lib/source.ts` divergence:** the llms.txt snippet is a hardcoded string, not derived from `cli.mdx`; U6 updates it in lockstep and the DoD grep catches drift.
365 +
366 +---
367 +
368 +## Sources & Research
369 +
370 +- mise primary artifacts (fetched 2026-07-31): `https://mise.run` script body (function definitions followed by bare top-level `install_mise` and conditional `after_finish_help`; no arbitrary byte-prefix truncation guarantee), `https://mise.run/zsh|bash|fish` variant scripts, `jdx/mise` `cloudflare/workers/mise-run.js` (Worker proxy, 200 + `text/plain`), `scripts/render-mise-run.sh`, `https://mise.jdx.dev/installing-mise.html` (docs structure: options as a short list, shell tabs, verification, alternatives).
371 +- Bun symlink experiment (2026-07-31, Bun 1.3.10): compiled binary invoked via relative symlink, absolute symlink, and PATH lookup all report `process.execPath` = real path.
372 +- Repo ground truth: `install.sh` (full bash contract inventory), `ts/packages/cli/src/commands/install.cmd.ts` (shell detection ~:50, rc blocks ~:91-106, hint bug ~:307-316, hardcoded default ~:189-190), `ts/packages/cli/scripts/package-binaries.ts` (zip manifest), `ts/packages/cli/src/services/run-companion-modules.ts` + `services/upgrade-binary.ts` (execPath resolution table), `test/install-sh-release-resolution.test.sh` (hermetic fake-PATH harness), `.github/workflows/{cli.test-installation,cli.install-health-check,build-cli-binaries}.yml`, `ts/e2e-tests/_utils/` (Dockerfile.cli, image-lifecycle, `mock-agents-server.ts` local-server pattern), `docs/content/docs/cli.mdx` + `docs/lib/source.ts:266` + `docs/content/docs/meta.json` (allowlist), `.agents/skills/{cli-e2e,cli-command,cli-release,docs-decisions,good-docs-writing}`.
373 +- `COMPOSIO_VERSION` collision evidence: `ts/packages/cli/test/src/services/config.test.ts:314` (`DEBUG_OVERRIDE_CONFIG`).
374 +- Scope provenance: user-negotiated handoff (three revision rounds, 2026-07-31); its decisions are recorded as KTDs above.
docs/plans/2026-08-03-001-feat-auto-shell-setup-default-plan.md new
+214
@@ -0,0 +1,214 @@
1 +---
2 +title: Auto Shell Setup as the Installer Default - Plan
3 +type: feat
4 +date: 2026-08-03
5 +status: proposed
6 +depends_on: 2026-07-31-001-feat-mise-style-installer-rewrite-plan.md
7 +execution: code
8 +---
9 +
10 +# Auto Shell Setup as the Installer Default - Plan
11 +
12 +## Goal Capsule
13 +
14 +- **Objective:** Make `curl -fsSL https://composio.dev/install | sh` a single command that infers the user's shell and, for a recognized shell when setup succeeds, puts `composio` on `PATH` automatically for future terminals. Otherwise, give the user runnable fallback guidance. The getting-started page shows exactly one command, and a non-technical user never has to know what zsh/bash/fish is. Keep install-only behavior available as an explicit opt-out. Document only supported public overrides; keep compatibility and test controls internal, and do not advertise shell-specific routes until they are provisioned and verified.
15 +- **Product driver:** Audience now includes non-technical users. One command, no shell vocabulary, no manual "how do I edit my PATH" step.
16 +- **Hard constraint (physics, not preference):** A script piped into `sh` runs in a child process and cannot modify the invoking shell's live environment. No installer can retroactively fix the *current* terminal's `PATH`. If the installed executable is already the command the current terminal resolves, the user can continue immediately. Otherwise, after successful persistent setup, the installer gives one zero-vocabulary instruction: "open a new terminal window." Nothing stronger is implementable without replacing the invoking shell process.
17 +- **Ship vehicle:** New PR stacked on `feat/mise-style-installer-rollout` (see KD1).
18 +
19 +## Key Decisions
20 +
21 +### KD1 — New stacked PR, not more commits on #4015
22 +
23 +Keep the default flip in a separate stacked PR so it has its own review record and revert surface. The stack is three PRs deep, not two: `#4011` (`feat/cli-install-shell-flag` → `next`) adds `composio install --shell` and is still open awaiting review, and `#4015` (`feat/mise-style-installer-rollout`) targets `#4011`'s branch, not `next`. The current local `feat/mise-style-installer-rollout` branch is two commits ahead of the remote head for `#4015`, and neither open PR has a recorded approval; do not treat any layer as reviewed or green yet. First push the two base commits, wait for the updated checks, and obtain the required approval on `#4015`. "Required" may not be mechanically enforced: the base plan recorded `require_code_owner_review: false` on the live `next` ruleset as of 2026-07-31, so re-verify the ruleset, restore that gate if it is still absent, and treat approval as an explicit process step rather than something the merge button guarantees. Then branch `feat/installer-auto-shell-default` from that validated head and target its PR at `feat/mise-style-installer-rollout`.
24 +
25 +`https://composio.dev/install` serves the installer from `next`, so the path to `next` is a release constraint with three merges and one release gate, in order:
26 +
27 +1. Merge the reviewed default-flip PR into `feat/mise-style-installer-rollout`; rerun checks and required review on the now-combined `#4015` head.
28 +2. Merge `#4011` to `next`. That merge alone publishes only an automatic beta, so follow the base plan's promotion protocol — verify the beta's exact tag, source commit, and uploaded assets; obtain explicit user approval; dispatch `promote-stable` — until a stable `@composio/cli` release containing `install --shell` is live. As of 2026-08-03 this gate is unmet: the latest stable, `0.3.1`, predates `--shell` (the pinned e2e compatibility leg depends on exactly that).
29 +3. Retarget `#4015` at `next` (GitHub does this automatically when `feat/cli-install-shell-flag` is deleted on merge — verify the base actually flipped), rerun checks and required review on the final head, then merge `#4015`.
30 +
31 +This preserves separate review history, keeps the base plan's rule that the rollout never merges ahead of a released stable CLI that understands `install --shell`, and ensures the public endpoint never exposes the install-only intermediate state.
32 +
33 +The cross-repository deployment order is also load-bearing. After `#4015` reaches `next`, verify the live `/install` endpoint performs the `auto` contract, including fresh-terminal availability and the `none` opt-out. Only then deploy the linked dashboard and docs copy. The old dashboard command remains compatible with the new installer during this interval; the new dashboard promise is not compatible with the old install-only default. Roll back in reverse dependency order: dashboard/docs copy first, installer behavior second.
34 +
35 +### KD2 — `COMPOSIO_INSTALL_SHELL` grows `auto` (new default) and `none`
36 +
37 +Accepted values: `auto` (default when unset) | `zsh` | `bash` | `fish` | `none`.
38 +
39 +- `auto`: infer the shell from `basename "$SHELL"`. Supported shell → always run the setup chain (made reconciling and idempotent in U1; today it skips on marker presence) so future terminals are configured. Unknown or unset `$SHELL` → degrade to today's install-only behavior plus guidance (never guess, never fail the install).
40 +- `zsh|bash|fish`: always run setup for the requested shell as today; failure handling and final output follow KD3 and KD4.
41 +- `none`: today's install-only default, for CI, Docker, and dotfile-manager users. This is the documented automation spelling.
42 +
43 +`$SHELL` is the right inference source: it names the user's *login* shell — the shell future terminals will run — which is precisely what rc configuration targets. It is independent of the `sh` executing the script.
44 +
45 +### KD3 — `auto` always configures recognized shells idempotently
46 +
47 +In `auto` mode, a recognized login shell always runs the existing `setup_requested_shell` chain (probe → `composio install --shell <shell>` → inline fallback). Do not use the invoking process's live `PATH` or `guidance_required` result to skip persistent setup: neither proves that a future login shell is configured.
48 +
49 +- Snapshot the inherited `PATH` before any installer code can modify it. After successful setup in either `auto` or explicit-shell mode, print Case A only when resolving `composio` against that snapshot selects the newly installed entry point. "Selects" means physical-path identity: resolve `command -v composio` under the snapshot, follow all symlinks, and compare the result against the fully resolved path of the verified installed executable (`$resolved_install_dir/composio`). The entry-point symlink and a bin dir equal to the install dir both satisfy this, and so does a pre-existing symlink elsewhere on `PATH` that resolves to the same installed executable — that terminal genuinely runs the new binary. A path-string comparison against the entry point is wrong in both directions and must not be used. This models what the invoking terminal can run after the child installer exits.
50 +- setup succeeds but the installed entry point does not resolve from the inherited `PATH` snapshot → print Case B.
51 +- setup failure → keep the installed binary, return success, warn that automatic `PATH` setup failed, and print the trusted absolute login command. A startup-file write failure must not turn a successful binary installation into a failed install.
52 +
53 +The setup chain owns exactly one managed PATH block per target startup file. Repeated installs do not duplicate it; when an existing managed block names an old bin directory, replace only that managed block with the current resolved directory and preserve all unmanaged content. Users and automation that prohibit startup-file edits use `COMPOSIO_INSTALL_SHELL=none`. Explicit `zsh|bash|fish` values keep the same always-configure semantics.
54 +
55 +`COMPOSIO_BIN_DIR` is an explicit trust boundary. Preserve current behavior for custom group- or world-writable directories: automatic and explicit shell setup may persist the resolved directory without a permission-mode warning or rejection. The default `~/.local/bin` remains user-owned. Advanced installation docs must state that anyone who can write to a custom executable directory can replace commands that future terminals run.
56 +
57 +### KD4 — Post-install messaging for non-technical users
58 +
59 +Two successful terminal states, both vocabulary-free:
60 +
61 +- **Case A (already reachable):** print the status and action on separate lines, with the command as a plain indented line:
62 +
63 + ```text
64 + composio is ready.
65 +
66 + composio login
67 + ```
68 +- **Case B (configured for future terminals):** print one instruction that is safe regardless of which shell currently interprets the installer:
69 +
70 + ```text
71 + Open a new terminal, then run:
72 +
73 + composio login
74 + ```
75 +
76 +Do not print per-shell `source` or `exec` commands in the installer ending. The configured login shell can differ from the interpreter in the current terminal, so such a command is not universally copy-safe. Advanced docs may explain manual refresh commands to technical users.
77 +
78 +Alternatives considered and rejected for the website command and default ending:
79 +
80 +- `curl … | sh && exec $SHELL` — automates the restart in-window and works in zsh/bash/fish, but replaces the shell process (hostile inside scripts/tmux/IDE terminals), looks scarier to the exact audience this targets, and breaks the single-clean-command aesthetic.
81 +- Per-shell `source <rc>` instructions — can execute syntax for the configured login shell inside a different current interpreter.
82 +- Printing an absolute-path login command after successful setup — works immediately, but gives the normal success path two competing instructions. Reserve the absolute command for setup failure, unknown shells, install-only mode, or command-shadowing recovery.
83 +
84 +Output is a state contract, not ad hoc copy:
85 +
86 +| Mode | Setup outcome | Final visible state |
87 +|---|---|---|
88 +| `auto`, recognized shell, installed command already resolves | Idempotent setup succeeds | Case A |
89 +| `auto`, recognized shell, installed command does not resolve | Idempotent setup succeeds | Case B |
90 +| `auto`, recognized shell | Setup fails | Warning plus the trusted absolute `composio login` command; exit 0 |
91 +| `auto`, unknown or unset shell | Setup skipped | Install-only guidance plus the trusted absolute login command |
92 +| Explicit `zsh`, `bash`, or `fish`, installed command already resolves | Setup succeeds | Case A |
93 +| Explicit `zsh`, `bash`, or `fish`, installed command does not resolve | Setup succeeds | Case B |
94 +| Explicit `zsh`, `bash`, or `fish` | Setup fails | Warning plus the trusted absolute login command; exit 0 |
95 +| `none` | Setup intentionally skipped | Install-only guidance; use the bare command only when it resolves to the installed entry point, otherwise use the trusted absolute command |
96 +| `--agent`, setup succeeds | Agent login succeeds | Agent-login-complete status; never print a second generic login command. If the current terminal cannot resolve the installed command, add only the new-terminal notice |
97 +| `--agent`, setup fails or is skipped | Agent login succeeds | Agent-login-complete status plus the setup warning and trusted installed-path guidance; never print a generic login command |
98 +| Plugins enabled | Any successful state | Plugin output completes before the applicable final state |
99 +| Quiet mode or `COMPOSIO_INSTALL_HELP=0` | Normal success | Preserve suppression: no post-install action block |
100 +| Quiet mode or `COMPOSIO_INSTALL_HELP=0` | Setup fails | Warning plus the applicable trusted recovery command; failure recovery is never suppressed |
101 +
102 +Apply the rows with this precedence: binary or agent-login failure remains fatal; successful agent login replaces any generic login action; setup failure or skipped setup adds recovery guidance appropriate to agent or human mode; plugin output completes before the final state; quiet/help suppression removes only normal-success help, never a setup-failure warning or recovery command.
103 +
104 +### KD7 — Final-block contract (field evidence: the CTO transcript, 2026-07-31)
105 +
106 +The production installer (pre-#4015) already auto-configured the shell — detected bash, updated `~/.bashrc`, added the install dir to `PATH` — and the CTO still ended up at `composio: command not found`, four times in a row. The transcript shows why: the refresh hint (`exec $SHELL`, boxed by clack) printed mid-stream, ~20 lines of `composio setup` plugin output buried it, and the final block said `To get started, run: composio --help` — unrunnable in that session. Users execute the last instruction on screen. **Auto-setup without a truthful ending reproduces the exact failure it was meant to fix.** Hard requirements:
107 +
108 +- **The last block wins.** Except when quiet/help suppression removes normal-success help, the final printed lines are the only action block: state-aware and truthful for the current installation outcome. Setup-failure warnings and recovery commands remain visible. Nothing — no plugin output, no completions notes, no branding — prints after the final block. `main()` ordering already puts shell setup and guidance last; keep that invariant.
109 +- **Copy-paste safe.** Commands in the final block are plain indented lines, never inside box-drawing characters. (Selecting bun-style clack boxes grabs `│` borders.)
110 +- **One voice at the end.** `install.sh` owns the ending. When it delegates to a current CLI, use the already-passed `COMPOSIO_CLI_INVOCATION_ORIGIN=installer` env var to suppress the CLI's boxed restart hint while retaining its concise startup-file update status. An older CLI may not honor that environment variable, so the installer's plain final block must still print afterward and supersede it.
111 +- **Agent flow is complete already.** After successful `composio login --agent`, print an agent-login-complete state, not `composio login`. The agent output tail receives its own regression assertion.
112 +- **Tested, not hoped.** The harness covers every KD4 matrix row and the defined combinations, and asserts the exact final N lines for Case A, Case B, setup failure, plugins, agent mode, and a pinned older CLI. It also asserts that quiet/help suppression removes normal-success help but retains setup-failure recovery.
113 +
114 +### KD5 — Deterministic everywhere; no TTY-gating
115 +
116 +The default does not vary by TTY or CI detection — same behavior piped, scripted, or interactive. Automation that wants install-only sets `COMPOSIO_INSTALL_SHELL=none`. Rc edits on ephemeral CI runners under `auto` are harmless (idempotent marker block), but repo workflows should still set `none` where install-only is the intent, as living documentation.
117 +
118 +### KD6 — Explicit variants remain; hosted routes stay unprovisioned
119 +
120 +`install/{zsh,bash,fish}.sh` keep setting `COMPOSIO_INSTALL_SHELL=<shell>` explicitly and remain release assets for forcing an exact shell. The `/install/<shell>` routes are currently unprovisioned and must remain undocumented until live checks return the expected scripts. The getting-started page shows only the single default command; `cli.mdx` documents the supported public override matrix in an advanced section. Compatibility and test-only controls remain supported but undocumented.
121 +
122 +## Work Breakdown
123 +
124 +### U1 — `install.sh`
125 +
126 +- Extend the `COMPOSIO_INSTALL_SHELL` validation case to `'' | auto | zsh | bash | fish | none` (empty ≡ auto). Fail fast pre-network on anything else (message lists all values).
127 +- Resolve `auto` → concrete shell from `basename "$SHELL"` right after arg parsing; unresolvable → empty `requested_shell` (install-only path).
128 +- Snapshot the inherited `PATH` before any installer helper can modify it. Use only this snapshot when deciding whether the invoking terminal can already run the installed entry point.
129 +- For every recognized `auto` shell, call `setup_requested_shell` unconditionally; do not use `guidance_required` or live `PATH` membership as the setup gate.
130 +- After any successful recognized-shell setup, define Case A only when `command -v composio`, evaluated against the inherited snapshot, resolves — after full symlink resolution, per KD3's physical-path identity rule — to the installed executable. If another executable shadows it, keep the final action on the trusted installed executable until a new terminal resolves correctly.
131 +- Pass the already-resolved absolute `resolved_bin_dir` through delegated and inline setup. Before any startup-file write, apply the existing unsafe-path contract to that resolved value: reject colon, semicolon, backtick, dollar, pipe, ampersand, quotes, parentheses, newline, carriage return, and backslash. Never persist the raw `COMPOSIO_BIN_DIR` value. An unsafe resolved value is a setup failure, not a fatal error: write no startup file, warn naming the rejected path, print the trusted recovery command, and exit 0. The current `inline_shell_setup` behavior — calling `error` after the binary is already installed — violates this contract and must change.
132 +- Preserve the existing permission policy for `COMPOSIO_BIN_DIR`. Treat a custom group- or world-writable directory as caller-trusted, and do not add a permission-mode warning or rejection. This does not weaken syntax validation or resolved-path handling.
133 +- Reconcile managed PATH blocks instead of treating marker presence as success. Preserve exactly one marker block containing the current resolved bin directory and leave unmanaged startup-file content unchanged.
134 +- Make delegated and inline startup-file setup non-fatal after binary installation. Every directory creation, file creation, read, replacement, and append helper returns a status explicitly; `inline_shell_setup` and `setup_requested_shell` propagate those statuses without relying on `set -e` inside a conditional. Capture failure, warn, print the trusted recovery command, and exit 0. Failure recovery travels the stderr `warn` channel, not `print_post_install_help`: that helper returns early under `COMPOSIO_QUIET` and `COMPOSIO_INSTALL_HELP=0`, so wiring recovery through it would silently violate the KD4 suppression rows.
135 +- The trusted recovery executable is always the `--version`-verified installed binary `$resolved_install_dir/composio`, never the entry point: it exists in every recovery row of the KD4 matrix and stays valid when the bin dir was rejected or the entry-point symlink failed. Render it as a POSIX-safe single shell word before appending arguments. Valid paths containing whitespace remain copy-paste safe; unsafe quote characters remain rejected by the path validator.
136 +- Rewrite `print_post_install_help` to implement the full KD4 state matrix. The install-only guidance survives for an unresolvable shell and `none`; neither path may tell the user to run a shadowed bare command.
137 +- Update usage text (`COMPOSIO_INSTALL_SHELL=auto|zsh|bash|fish|none`, default `auto`).
138 +- Enforce KD7 and the KD4 precedence rules: the final action block is the last output in every applicable flow, plugin output always precedes it, and `--agent` ends in its dedicated completed state with no second login command. Quiet/help controls suppress normal-success help only; setup-failure recovery remains visible.
139 +- For inline setup, print a concise status naming each startup file that was updated, or state that its managed block was already current. This disclosure appears before the final action block and never tells the user to source a shell-specific file.
140 +- Invariants: POSIX-guard regex clean, `shellcheck -s sh` clean, `command -v curl` line untouched (sed-patched by CI), argument-error ordering preserved.
141 +
142 +### U1b — `install.cmd.ts` (CLI)
143 +
144 +- Per KD7: when `COMPOSIO_CLI_INVOCATION_ORIGIN=installer`, suppress the CLI's boxed restart-hint note while retaining its concise `Updated <startup-file>` or already-current status. The installer owns final messaging; direct `composio install` invocations keep the hint. Unit-test both paths.
145 +- Reconcile an existing managed PATH block whose bin directory differs from the resolved current directory. Preserve one marker block per physical target file, retain symlink-aware deduplication, and leave unmanaged content unchanged. Unit-test unchanged, replaced, and aliased target files.
146 +
147 +### U2 — Harness and analytics tests
148 +
149 +- Update `test/install-sh-release-resolution.test.sh`: every recognized default-flow shell delegates through the idempotent setup chain; `none` preserves install-only behavior; a recognized shell with the installed command already resolving still takes Case A after setup; unset/unknown shells take the install-only fallback; invalid values list `auto` and `none`.
150 +- Add a shadowing case where the bin directory is on `PATH` but `command -v composio` resolves elsewhere; the ending must not run the shadowed command.
151 +- Add inherited-PATH cases where installer internals mutate their own `PATH`; the ending must still reflect what the invoking terminal inherited.
152 +- Add a pinned-old-CLI case with a relative `COMPOSIO_BIN_DIR`; startup files must remain unchanged and setup must receive only the resolved absolute directory. Assert that any older restart hint is followed and superseded by the installer's exact final tail.
153 +- Add setup-write-failure cases for delegated and inline paths, including failures inside helpers invoked from conditionals under both `sh` and `dash`. They retain the installed binary, exit 0, warn, and end with the trusted recovery command.
154 +- Add reinstall cases that move between two resolved bin directories. Delegated and inline setup must replace the old managed path, preserve unrelated startup-file content, and leave exactly one marker block.
155 +- Add default-`auto` unsafe-path cases using representative metacharacters from the existing validator. Reject before a startup-file write and prove the files remain unchanged; assert the setup-failure contract — exit 0, a warning naming the rejected path, and a final tail ending with the trusted recovery command on the installed executable.
156 +- Add recovery-output coverage for a valid absolute bin directory containing spaces. The printed command must execute the installed binary when pasted into `sh` or `dash`.
157 +- Assert every KD4 state row and defined combination: Case A, Case B, unknown shell, `none`, explicit shells, plugin output ordering, agent completion with each setup outcome, and quiet/help suppression on success and failure. Exact tail assertions prove nothing follows the final block.
158 +- Update `ts/packages/cli/test/src/analytics.events.test.ts`, whose existing base-installer assertion requires install-only behavior and forbids shell-setup delegation.
159 +- Variant cases unchanged (they set the env var explicitly).
160 +
161 +### U3 — Docker e2e (`ts/e2e-tests/cli/install/e2e.test.ts`)
162 +
163 +- Flip "configures an existing bash login profile only through the bash variant": the default installer now always configures a recognized login shell idempotently — assert `bash -ilc 'command -v composio'` succeeds after the plain `curl | sh`, and that the login-override file gets exactly one marker block.
164 +- `auto` infers from `$SHELL`, and Docker execs typically leave it unset — no current e2e leg sets it. Export `SHELL=/bin/bash` (or the matrix shell) in the environment of every default-flow installer invocation, and add a companion leg with `SHELL` unset asserting the install-only fallback inside the container.
165 +- Add a `COMPOSIO_INSTALL_SHELL=none` leg asserting the old install-only contract.
166 +- Keep the virgin-home test (already asserts fresh-login-shell availability) and idempotency legs; extend the pinned-old-CLI compatibility leg to cover the resolved absolute bin directory and non-fatal fallback contract.
167 +
168 +### U4a — Dashboard onboarding (`ComposioHQ/dashboard`)
169 +
170 +- Branch from a refreshed dashboard `main`; do not implement against the stale local checkout. Treat both onboarding cohorts as required: the legacy `/onboarding/cli-setup` selector for flag-off users and the Connect onboarding modal for flag-on users.
171 +- Legacy flow: update `src/app/(private)/onboarding/_components/cli-setup-selector.tsx` and its `steps.ts` configuration. Replace the old bash-piped command with `curl -fsSL https://composio.dev/install | sh`; tell human terminal users to open a new terminal and run `composio login`; disclose that startup files may be updated and link to the `none` opt-out.
172 +- Modal and agent-instruction flow: update the onboarding-modal prompt and the public CLI setup instructions. Because agent fetch caches are keyed on URL and cannot be purged, publish materially revised instructions at a new route path and update the modal's instruction URL in the same deployment. Preserve agent-specific authentication and task-completion behavior instead of substituting the human new-terminal copy.
173 +- Inventory and update every dashboard-rendered public installer copy on current `main`, including the API CLI instruction and route test, client definitions/grid/instruction page, reusable CLI card, OpenClaw helper and test, and day-seven email preview. Replace public install commands with the `sh` form, then assign post-install copy by audience: human terminal flows receive new-terminal/login guidance; agent and API flows retain their specific completion contract.
174 +- Verify the new instruction route and its tests, run dashboard `pnpm check`, and exercise both flag-off legacy onboarding and flag-on modal onboarding in a real browser. Confirm the command, follow-up state, opt-out disclosure, and stable layout on each rendered surface changed by the PR.
175 +
176 +### U4b — Repository docs
177 +
178 +- **Docs funnels** (`docs/content/docs/quickstart`, `docs/lib/source.ts`, `ai-tools-banner.tsx`, `home-surfaces.tsx`): align any surfaced CLI installation command and post-install wording with the dashboard onboarding contract.
179 +- **Repository entrypoints** (`README.md`, `docs/content/docs/claude-code-plugin.mdx`): update the immediate post-install steps and automatic-setup description so they do not retain the old install-only contract.
180 +- **`cli.mdx`**: Install section leads with the single command and what it does now (installs and configures a recognized shell when setup succeeds, with runnable fallback guidance otherwise); "Configure your shell" becomes the override/advanced section (`COMPOSIO_INSTALL_SHELL=<shell|none>` and release-asset variants); env table row updated (`auto` default, `none` documented); unprovisioned `/install/<shell>` routes are not advertised; uninstall section unchanged.
181 +- **`INSTALL.md`**: same reframing; `none` called out for CI/dotfile managers.
182 +- **Custom install directories**: in the advanced environment-variable reference and `INSTALL.md`, state that `COMPOSIO_BIN_DIR` is trusted input. Anyone with write access to that directory can replace commands that future terminals run.
183 +- **Changelog** (`07-31-26-installer.mdx`): the "default flow does not edit shell files" bullet must be updated in this stacked PR — neither PR has shipped, so the entry describes only the final behavior. New bullet: default infers your shell and configures `PATH`; `COMPOSIO_INSTALL_SHELL=none` for install-only.
184 +- **`ts/packages/cli/CLAUDE.md`** commands table: fix the stale `install` description ("Install local-tool integrations" → shell integration) — noted during this work, one-line fix.
185 +
186 +### U5 — CI and workflows
187 +
188 +- `cli.test-installation.yml`: keep no-argument installer steps on `auto` and assert the new persistent-shell behavior. Set `COMPOSIO_INSTALL_SHELL=none` only on steps whose named purpose is install-only; keep the manual `composio install --shell` step because it tests the CLI command directly.
189 +- `cli.install-health-check.yml`: keep the existing secondary no-argument leg as a real-user `auto` check. Add a separate `COMPOSIO_INSTALL_SHELL=none` leg when deterministic install-only coverage is needed; do not replace default-flow coverage with it.
190 +- Preview-comment block in `cli.install-e2e.yml`: single command first, `none` example second.
191 +- `build-cli-binaries.yml`: update its generated installation instructions so release artifacts describe automatic setup, the `none` opt-out, and no unprovisioned routes.
192 +
193 +### U6 — PR mechanics
194 +
195 +- Push the two local `feat/mise-style-installer-rollout` commits, wait for updated checks, and obtain required approval before cutting `feat/installer-auto-shell-default`. Re-verify the `next` ruleset's code-owner review gate first (see KD1); restore it if absent.
196 +- Branch from that validated head; target the new PR at `feat/mise-style-installer-rollout`. Its body records the product decision, the colleague's requirement, and the child-process limitation.
197 +- Merge the reviewed follow-up into `feat/mise-style-installer-rollout` and rerun checks and required review on the combined `#4015` head.
198 +- Clear the `#4011` layer before `#4015` can move: merge `#4011` to `next`, run the base plan's beta verification and user-approved `promote-stable` dispatch, and confirm the resulting stable `@composio/cli` release ships `install --shell`. `#4015` merges only after that stable is live.
199 +- Retarget `#4015` at `next` (automatic when `feat/cli-install-shell-flag` is deleted on merge; verify the base flipped), rerun checks and required review on the final head, then merge `#4015` to `next`. Do not allow the public `next` installer to expose the intermediate default.
200 +- Open the linked `ComposioHQ/dashboard` PR described in U4a, but do not deploy its new behavior promise before the installer stack. After `#4015` reaches `next`, smoke-test the live default and `none` flows, then deploy the dashboard and repository docs. Treat successful live installer verification and both dashboard onboarding cohorts as release-announcement gates.
201 +- Record rollback order in both PRs: restore the prior dashboard/docs copy first, then revert installer behavior if necessary. The old copy remains compatible during an installer rollback; the new promise does not remain valid against the old install-only default.
202 +- Update `#4015`'s body to note the stacked follow-up and to mark shell-specific routes as unprovisioned and undocumented rather than as a merge prerequisite.
203 +
204 +## Risks
205 +
206 +- **Philosophy reversal mid-stack:** #4015's review praised install-only defaults; this flips it. Mitigated by KD1's separate reviewable decision and the explicit `none` opt-out.
207 +- **Dotfile-manager users:** recognized shells now run idempotent startup-file setup by default even when the current command already resolves. Mitigated: a single marker block, the documented `none` opt-out, and existing uninstall cleanup.
208 +- **Startup-file write failure:** binary installation can succeed while persistent setup fails. Mitigated: setup is non-fatal, the ending names the failure, and the trusted absolute login command remains runnable.
209 +- **Stale managed PATH block:** marker presence can hide an obsolete bin directory after reinstall. Mitigated: reconcile the managed block to the resolved current directory and test directory changes through delegated and inline setup.
210 +- **Command shadowing:** a stale or hostile executable may appear earlier on `PATH`. Mitigated: Case A requires resolution to the installed entry point; recovery output uses the trusted absolute executable.
211 +- **Shared custom bin directories:** a caller may intentionally choose a group- or world-writable `COMPOSIO_BIN_DIR`. Accepted policy: preserve current behavior and document the directory as caller-trusted; the user-owned default remains unchanged.
212 +- **Cross-repository rollout:** the public installer follows `next`, while onboarding deploys independently. Mitigated: merge the follow-up into the stack before the combined base reaches `next`; verify the live installer first; deploy dashboard/docs second; roll back copy before behavior.
213 +- **`$SHELL` lies** (csh users, `SHELL=/bin/sh`, exotic setups): degrade to install-only + guidance; never block the install.
214 +- **Docs/e2e churn:** the flip touches many assertions written days ago; U2/U3 enumerate them so nothing flips silently.
install.sh
+5 -5
@@ -506,14 +506,14 @@ print_post_install_help() {
506 # channel so quiet mode and COMPOSIO_INSTALL_HELP=0 cannot suppress it, and the
507 # trusted --version-verified installed executable is always the last output.
508 print_setup_failure_ending() {
509 + if [ "$install_agent" = 1 ] &&
510 + [ "${COMPOSIO_INSTALL_HELP:-1}" != 0 ] && ! is_true "${COMPOSIO_QUIET:-}"; then
511 + printf '\nComposio agent login complete.\n'
512 + fi
513 + warn "Automatic PATH setup for $requested_shell failed. The Composio CLI is installed and unaffected."
514 if [ "$install_agent" = 1 ]; then
510 - if [ "${COMPOSIO_INSTALL_HELP:-1}" != 0 ] && ! is_true "${COMPOSIO_QUIET:-}"; then
511 - printf '\nComposio agent login complete.\n'
512 - fi
513 - warn "Automatic PATH setup for $requested_shell failed. The Composio CLI is installed and unaffected."
515 printf '\nRun composio from its installed location:\n\n %s --help\n' "$(shell_quote "$exe")" >&2
516 else
516 - warn "Automatic PATH setup for $requested_shell failed. The Composio CLI is installed and unaffected."
517 printf '\nTo get started, run:\n\n %s login\n' "$(shell_quote "$exe")" >&2
518 fi
519 }
ts/packages/cli/src/commands/install.cmd.ts
+19 -17
@@ -297,6 +297,23 @@ const planPathBlockWrites = (params: {
297 return { appendPathFiles, replacementsByTarget, loginOverrideWritten };
298 };
299
300 +/** Atomically replace a physical target file's contents, preserving its file mode. */
301 +const atomicWriteWithMode = (
302 + fs: FileSystem.FileSystem,
303 + writeTarget: string,
304 + contents: string
305 +): Effect.Effect<void, PlatformError> =>
306 + Effect.gen(function* () {
307 + const existingTargetInfo = yield* fs.stat(writeTarget).pipe(Effect.option);
308 + const tmpPath = `${writeTarget}.composio-tmp`;
309 +
310 + yield* fs.writeFileString(tmpPath, contents);
311 + if (Option.isSome(existingTargetInfo)) {
312 + yield* fs.chmod(tmpPath, existingTargetInfo.value.mode & 0o7777);
313 + }
314 + yield* fs.rename(tmpPath, writeTarget);
315 + });
316 +
317 /** Atomically rewrite each reconciled physical target, preserving its file mode. */
318 const writeReconciledTargets = (params: {
319 readonly replacementsByTarget: ReadonlyMap<string, ManagedBlockReplacement>;
@@ -306,15 +323,7 @@ const writeReconciledTargets = (params: {
323 }): Effect.Effect<void, PlatformError> =>
324 Effect.gen(function* () {
325 for (const [writeTarget, replacement] of params.replacementsByTarget.entries()) {
309 - const existingTargetInfo = yield* params.fs.stat(writeTarget).pipe(Effect.option);
310 - const tmpPath = `${writeTarget}.composio-tmp`;
311 -
312 - yield* params.fs.writeFileString(tmpPath, replacement.contents);
313 - if (Option.isSome(existingTargetInfo)) {
314 - yield* params.fs.chmod(tmpPath, existingTargetInfo.value.mode & 0o7777);
315 - }
316 - yield* params.fs.rename(tmpPath, writeTarget);
317 -
326 + yield* atomicWriteWithMode(params.fs, writeTarget, replacement.contents);
327 yield* params.report(`Updated ${tildify(replacement.displayPath, params.homedir)}`);
328 }
329 });
@@ -631,7 +640,6 @@ export const installShellIntegration = (params: {
640 // PATH files were already resolved above; only the completion file needs a fresh resolve.
641 const writeTarget =
642 pathFileTargets.get(filePath) ?? (yield* resolveWriteTarget(filePath, fs));
634 - const existingTargetInfo = yield* fs.stat(writeTarget).pipe(Effect.option);
643
644 yield* fs
645 .makeDirectory(path.dirname(writeTarget), { recursive: true })
@@ -642,13 +650,7 @@ export const installShellIntegration = (params: {
650 );
651
652 const appendContent = '\n' + blocks.join('\n\n') + '\n';
645 - const tmpPath = `${writeTarget}.composio-tmp`;
646 -
647 - yield* fs.writeFileString(tmpPath, existingContents + appendContent);
648 - if (Option.isSome(existingTargetInfo)) {
649 - yield* fs.chmod(tmpPath, existingTargetInfo.value.mode & 0o7777);
650 - }
651 - yield* fs.rename(tmpPath, writeTarget);
653 + yield* atomicWriteWithMode(fs, writeTarget, existingContents + appendContent);
654
655 yield* success(`Updated ${tildify(filePath, os.homedir)}`);
656 }