Installer

The installer makes Bestie usable outside a project-local checkout. It should not add product scope; it only bootstraps the current CLI, onboarding, Doctor, Telegram, memory, and read-tool foundation.

Commands

Current repo-local development:

./install.sh
./install.sh --skip-onboard

Flags

--skip-onboard      Do not offer to run bestie onboard after install.
--dir <path>        Install source checkout here. Defaults to ~/.local/share/bestie/source.
--bin-dir <path>    Place the bestie command here. Defaults to ~/.local/bin.
--source-dir <path> Copy this local checkout instead of cloning. Intended for smoke tests.

What the installer does

The installer should:

• Verify git, node, and npm are available.
• Require Node.js 20 or newer.
• Choose a local install directory, defaulting to ~/.local/share/bestie/source.
• Clone the repository when missing.
• Update only after confirming an existing install is a Bestie checkout.
• Run npm install and npm run build.
• Expose the bestie command through a predictable user-local bin directory.
• Run bestie doctor after install.
• Offer to run bestie onboard after Doctor succeeds.

Existing installs

If the target directory already exists, the installer should:

• Refuse to overwrite unknown directories.
• Detect a Bestie checkout by package name and CLI entrypoint.
• Preserve .bestie/, .env, config, character, memory database, logs, and transcripts.
• Explain manual recovery if automatic update is unsafe.

Safety rules

The installer must never print or collect API keys, Telegram tokens, or raw .env contents.

It should not run extra network checks beyond dependency installation and repository download unless the user explicitly chooses onboarding or Doctor checks that already require them.

Recovery output

Failures should tell the user:

• what failed
• the command that failed
• the likely fix
• whether user data was touched

Common examples:

• Unsupported Node version: install Node.js 20+.
• Missing git: install Git and rerun.
• npm install failed: fix network or npm cache, then rerun from the checkout.
• Build failed: run npm run build in the checkout and inspect TypeScript errors.

Acceptance checks

npm run build
npm run smoke:installer
npm run smoke:onboard
npm run smoke:doctor
npm run smoke

Fresh install verification:

tmpdir=$(mktemp -d)
HOME="$tmpdir" ./install.sh --skip-onboard
HOME="$tmpdir" ~/.local/bin/bestie doctor

The smoke must not require real provider or Telegram secrets.

Non-goals

• system service installation
• auto-starting Telegram polling
• Zep setup
• hosted accounts
• GUI installer
• shell profile edits without clear user consent