Make @heyditto/cli easier to install for Bun users (zero-install path + Node-runtime gotcha)

[Peyton-Spencer]

Summary

@heyditto/cli is documented and shipped as an npm-global install (npm install -g @heyditto/cli). For Bun-first users this is a rough on-ramp: the README and docs offer no Bun path, and a global install is the most failure-prone install mode. We should make Bun users first-class.

Real-world friction (encountered installing v1.3.1)

Installing on a Bun-centric machine:

• npm install -g @heyditto/cli → EACCES (mkdir /usr/lib/node_modules/@heyditto) because the global prefix wasn't user-writable.
• bun install -g @heyditto/cli → error: Failed to link @heyditto/cli: EACCES (global bin /usr/local/bin root-owned).
• Worked only after npm config set prefix ~/.local and adding ~/.local/bin to PATH.

Global installs are exactly where permission/PATH footguns live, and the docs point straight at the most fragile mode with no zero-install alternative.

Why this matters for Bun users specifically

1. No Bun instructions anywhere. README.md (lines 15-21) only shows npm install -g and npx -y @heyditto/cli. There is no bunx @heyditto/cli or bun add -g @heyditto/cli. Bun users have to guess the mapping.
2. The bin shebang is #!/usr/bin/env node (src/cli.ts line 1). On a Bun-only machine with no Node installed, even a successful bun add -g @heyditto/cli produces a ditto binary that fails to execute because env node isn't found. This is a silent gotcha unique to Bun-only setups.
3. engines.node >= 20 is declared but there's no Bun signal; bun add -g ignores engines, so nothing tells a Bun user whether they're on a supported runtime.

Proposed improvements

Low effort / docs (do first):

• Add a Bun section to README.md and the landing docs (ditto-cli.md, agent-native-signup.md):
  • Zero-install (recommended): bunx @heyditto/cli init --agent --json — no global dir, no PATH edits, always latest.
  • Global: bun add -g @heyditto/cli (note it needs a writable global bin + that dir on PATH; mention bun pm bin -g to find it).
• Lead the install docs with the zero-install path (bunx / npx -y) since it sidesteps every EACCES/PATH issue, and present global install as the opt-in.

Medium effort / packaging:

• Confirm the published bin works under Bun's runtime. Consider a shebang/runtime strategy that doesn't hard-require Node on the PATH for Bun-only machines (e.g. document that Node ≥20 must be present for the global bin, or provide a Bun-runnable entry). At minimum, document the Node dependency explicitly so the env node failure isn't a surprise.

Higher effort / nice-to-have:

• Ship a standalone compiled binary via bun build --compile (and/or an install script / GitHub Release assets) so users with neither npm nor a writable global dir can install with a single curl | sh. This removes the global-permissions class of failures entirely and is the smoothest path for agents in sandboxed containers (the exact environment where the EACCES failures above happened).

Acceptance criteria

• README + landing docs include a Bun install path, with zero-install (bunx) presented first.
• The Node-runtime requirement for the global bin is documented (or removed via a Bun-runnable entry), so bun add -g users on Node-less machines aren't left with a non-executable binary.
• (Stretch) A no-Node install option exists (compiled binary or install script).

References

• package.json — bin → dist/cli.js, engines.node >=20, type: module
• src/cli.ts:1 — #!/usr/bin/env node
• README.md:15-23 — current install docs (npm + npx only)