Install Bootstrap
=================

`install.sh` is the repo-root bootstrap entrypoint for a blank developer
machine. It is a checkout-only helper: the file ships in the repository and
release tarball for explicit operator use, but CPAN and `cpanm` do not install
it into the global command namespace.

Supported platforms
-------------------

- Debian
- Ubuntu
- macOS

Release-gate note
-----------------

Linux remains the required release gate for packaged installation checks.
macOS support stays available for manual validation and Homebrew-specific
debugging, but it is not a mandatory release gate.

Basic usage
-----------

Run the installer from a checkout:

```bash
./install.sh
```

What it does
------------

1. Detects the current platform.
2. On Debian-family hosts, reads the repo-root `aptfile`, runs `apt-get update`,
   and installs the listed packages. When the current user is not root, it uses
   `sudo`.
3. On macOS, reads the repo-root `brewfile` and installs the listed packages
   through `brew install`.
4. Verifies that `node`, `npm`, and `npx` are available after those package
   installs, because skill `package.json` dependency handling uses
   `npx --yes npm install`.
5. Bootstraps user-space Perl tooling under `~/perl5` with:

   ```bash
   cpanm --local-lib-contained "$HOME/perl5" local::lib App::cpanminus
   ```

6. Appends exactly one `local::lib` bootstrap line to the active shell startup
   file. Bash users get `~/.bashrc`, zsh users get `~/.zshrc`, and generic POSIX
   `sh` users fall back to `~/.profile`.
7. Prefers Homebrew Perl on macOS when `brew --prefix perl` exposes a brewed
   interpreter, so the user-space runtime does not drift back to the system Perl.
8. On Debian-family hosts where the packaged system Perl is older than `5.38`,
   bootstraps a user-space `perlbrew` Perl under `~/perl5/perlbrew` first so
   the checkout can still install on older stable releases such as Debian 12.
9. Installs Developer Dashboard into the user account with:

   ```bash
   cpanm --notest Developer::Dashboard
   ```

10. Runs `dashboard init` so the runtime exists immediately after the install.

Useful examples
---------------

Default install:

```bash
./install.sh
```

Force zsh startup-file selection:

```bash
SHELL=/bin/zsh ./install.sh
```

Test the installer against a specific tarball instead of the CPAN package name:

```bash
DD_INSTALL_CPAN_TARGET=./Developer-Dashboard-X.XX.tar.gz ./install.sh
```
