Natively support `gh extension install` / `gh extension upgrade`

[jamietanna]

Follow-up to #7154, we could natively support gh extension installations, which would make it easier to install-tool/uninstall-tool, especially with binarySource=global

[jamietanna]

Claude Opus 5:

# GitHub CLI extensions in Containerbase — research notes

Follow-up research to [#7154](https://github.com/containerbase/base/issues/7154) (`install-tool gh`).

Question: can we support installing `gh` extensions the way `install-gem` / `install-pip` take an
arbitrary package argument, and can the extensions be cached somewhere other than their default
location?

Short answers: **yes** to both, but the second one has exactly one lever, and there is a genuine
design fork on disk layout that trades away `gh extension upgrade`.

All findings below were verified empirically against `gh` v2.97.0 inside a locally built
`containerbase/test:latest` image (arm64), or read from the `cli/cli` v2.97.0 source.

## How extensions work

An extension is a repository named `gh-<name>`, invoked as `gh <name>`. `gh extension install`
resolves it to one of two kinds at install time:

| Kind | Trigger | On-disk result |
| --- | --- | --- |
| Binary | repo has a release with a matching platform asset | asset downloaded to `gh-<name>/gh-<name>`, plus a generated `manifest.yml` |
| Script | no releases | full `git clone` of the repo; entrypoint is `gh-<name>` at the repo root |

- `--pin <ref>` pins the version: a release tag for binary extensions, a commit ref for script ones.
  Script extensions get a `.pin-<sha>` marker file written into the clone.
- Script extensions are cloned with **full history** — there is no shallow-clone option.
- Binary extensions are not small: `dlvhdr/gh-dash` v4.25.2 is 22 MB.
- `git` is required at install time for script extensions.

### Authentication behaviour (relevant to CI test images)

| Command | Works unauthenticated? |
| --- | --- |
| `gh extension install <owner>/<repo>` | ✅ yes |
| `gh <name>` (executing an extension) | ✅ yes |
| `gh extension list` | ❌ requires auth |
| `gh extension upgrade`, even `--dry-run` | ❌ requires auth |

Two consequences:

- The `gh extension upgrade aw --dry-run` check listed in #7154 **cannot run in an unauthenticated
  CI test image** — it fails with "To get started with GitHub CLI, please run: gh auth login"
  regardless of disk layout.
- An **invalid** `GH_TOKEN` breaks `gh extension install`, where having no token at all succeeds.
  Worth knowing before wiring a dummy token into a test image.

### No integrity verification

`pkg/cmd/extension/manager.go` at v2.97.0 has **no** references to checksums, sha256, or
attestation. `gh extension install` downloads and executes release assets with no verification of
any kind.

This is weaker than the `gem` / `npm` / `pip` precedent, where the package manager at least has
registry-supplied integrity metadata, and it sits awkwardly against the Containerbase rule that
every download is checksum-verified (`docs/new-tool.md`: "published checksums — Containerbase
verifies every download"). Worth a maintainer decision before this ships, since it's a policy
question rather than a technical blocker.

## Relocating the extension directory

`XDG_DATA_HOME` is the **only** lever. Probed each candidate by installing the same extension and
finding where it landed:

| Env var set | Extensions landed in |
| --- | --- |
| *(nothing)* | `/root/.local/share/gh/extensions` |
| `XDG_DATA_HOME=/probe/data` | `/probe/data/gh/extensions` ✅ |
| `GH_CONFIG_DIR=/probe/cfg` | `/root/.local/share/gh/extensions` ❌ |
| `XDG_CONFIG_HOME=/probe/xcfg` | `/root/.local/share/gh/extensions` ❌ |

`GH_CONFIG_DIR` — the obvious-sounding candidate, and the only dir-related variable `gh environment`
documents — moves `config.yml` / `hosts.yml` only, **not** extensions. There is no CLI flag either.

### How that composes with Containerbase

- **Where:** `/opt/containerbase/data/gh` (`pathSvc.dataPath`) is the right home — persistent and
  baked into the image. Not `pathSvc.cachePath`, which is `/tmp/containerbase/cache` and would not
  survive.
- **How:** `pathSvc.exportToolEnv('gh', { XDG_DATA_HOME: … })` writes
  `export XDG_DATA_HOME=${XDG_DATA_HOME-…}` into `tools/gh/env.sh`. Per
  `LinkToolService.shellwrapper`, that file is sourced **only** by the `gh` wrapper (and by any tool
  declaring `extraToolEnvs: ['gh']`), so a generic variable stays scoped to `gh` instead of leaking
  to every tool. The `${VAR-default}` form also means a user's own `XDG_DATA_HOME` still wins.
- **Multi-user:** verified that extensions installed as root at build time execute correctly as user
  `12021` at runtime.
- **Runtime installs still work:** the runtime user is `uid=12021 gid=0(root)`, so Containerbase's
  standard 0775 root:root directories are group-writable. A non-root user can `gh extension install`
  into the shared directory at runtime — verified.

## The design fork: symlink vs real directory

The appealing option was to install each extension into a versioned tool path and symlink it into the
shared extensions directory — the trick `docker/compose.ts` already uses for `.docker/cli-plugins`.
Execution works that way, as both root and non-root.

But `manager.go:146` (`list()`) classifies entries by `lstat`:

```go
if f.IsDir() {                    // real dir → BinaryKind (manifest.yml) or GitKind
    …
} else if isSymlink(f.Type()) {   // symlink   → LocalKind
    …
}
```

and `upgradeExtension` (`manager.go:517`) hard-fails on `IsLocal()` with
`local extensions can not be upgraded`. So symlinking silently converts every extension into a
"local" one.

### Option A — real directories in the shared data dir

```text
/opt/containerbase/data/gh/extensions/
  └── gh-dash/
      ├── manifest.yml
      └── gh-dash          (binary)
```

- `gh dash` ✅ (root + non-root) · `gh extension upgrade` ✅ (given auth) · `gh extension list` ✅ native
- `uninstall-tool` ❌ not modelled · no version DB entries · only one version per extension at a time

Upstream-native, and the layout `gh` itself expects. The cost is that extensions sit outside the
Containerbase tool model entirely.

### Option B — versioned tool path + symlink

```text
/opt/containerbase/tools/gh-dash/4.25.2/gh-dash/
  ├── manifest.yml
  └── gh-dash

/opt/containerbase/data/gh/extensions/
  └── gh-dash -> /opt/containerbase/tools/gh-dash/4.25.2/gh-dash
```

- `gh dash` ✅ (root + non-root) · `uninstall-tool` ✅ · version DB ✅ · multiple versions side by side ✅
- `gh extension upgrade` ❌ "local extensions can not be upgraded" · `gh extension list` ⚠️ reported as local

Fits Containerbase's model properly. The argument for accepting the degradation: Containerbase owns
tool versions, and letting `gh extension upgrade` mutate an extension behind its back would desync
the version database anyway — so refusing the upgrade is arguably the correct behaviour, not a
regression. Note `uninstall()` would need an override to remove the symlink, per the
`docs/new-tool.md` guidance about tools that write outside `createVersionedToolPath()`.

**Still open.** Recommendation is B for consistency with the rest of Containerbase; A is the
better choice if native `gh extension upgrade` / `list` fidelity matters more than
`uninstall-tool` support and version pinning.

## Wiring checklist (either option)

Extensions can't reuse `InstallToolType` (`'gem' | 'npm' | 'pip'`) as-is — that type drives the
versioned-install, version-DB and uninstall machinery. A dedicated command mirroring `install-gem`
would touch:

- `src/cli/utils/types.ts` — add to `cliModes` (and `InstallToolType`, if going with option B)
- `src/cli/command/install-gh-extension.ts` + `uninstall-gh-extension.ts` — subclass the
  `InstallToolCommand` pattern from `install-gem.ts`
- `src/cli/command/index.ts` — import the new command modules
- `src/usr/local/containerbase/bin/install-containerbase.sh:98` — `ln -sf` the new binary names into
  `/usr/local/sbin/`, alongside the existing `install-gem` / `uninstall-gem` links
- `src/cli/tools/gh.ts` — export `XDG_DATA_HOME` via `exportToolEnv`, and create/permission the
  shared extensions directory
- `docs/tools.md` — a command reference section, matching the existing `install-gem` entry
- `docs/custom-registries.md` — extension downloads hit arbitrary `github.com/<owner>/<repo>`
  release URLs, which is new for a Containerbase tool and worth documenting for proxy users
- Test images — noting that only `install` and execution can be covered unauthenticated

## Reproducing

```sh
pnpm install && pnpm build && docker buildx bake

# where do extensions land?
docker run --rm containerbase/test:latest bash -c '
  install-tool gh v2.97.0 >/dev/null 2>&1
  export XDG_DATA_HOME=/shared
  gh extension install dlvhdr/gh-dash --pin v4.25.2
  find /shared -maxdepth 4'
```

And:

Written up at `/private/tmp/claude-501/-Users-jamietanna-workspaces-containerbase-base/00205ba1-02ce-4a99-832a-13b8983300fc/scratchpad/gh-extensions-findings.md` — ready to paste into #7154 or a follow-up issue. The headlines:

**Extensions are two things wearing one name.** Binary (release asset + generated `manifest.yml`) or script (full `git clone`, no shallow option). `--pin` takes a tag for the former, a commit for the latter.

**Caching: yes, but `XDG_DATA_HOME` is the only lever.** `GH_CONFIG_DIR` is the obvious-sounding candidate and the only dir-related variable `gh environment` documents — it moves `config.yml`/`hosts.yml` and *not* extensions. `/opt/containerbase/data/gh` is the right target, exported through `tools/gh/env.sh` so a generic variable stays scoped to the `gh` wrapper and users can still override it. Verified that root-built extensions execute as user 12021, and that non-root runtime installs work because the runtime user is `gid=0(root)` and containerbase dirs are 0775.

**Three things that complicate the issue's plan:**

1. `gh extension list` and `gh extension upgrade` require auth — even `--dry-run`. So the `gh extension upgrade aw --dry-run` acceptance check can't run in an unauthenticated CI image at all, whatever layout we pick.
2. An *invalid* `GH_TOKEN` breaks `gh extension install`, while no token succeeds. Counterintuitive, and a trap for test images.
3. `gh` does **no** integrity verification of extension downloads — no checksums, no attestation anywhere in `manager.go`. That's weaker than the gem/npm/pip precedent and rubs against containerbase's verify-every-download rule. It reads to me as a maintainer policy call rather than something to decide in a PR.

**On the layout fork** — I left it open in the doc rather than recording a decision, since your correction suggests the "real dirs" pick may have been a misclick. The trade is real either way: `manager.go` classifies a symlinked extension dir as `LocalKind` via `lstat`, and `upgradeExtension` hard-refuses those, so the containerbase-native versioned-path layout costs you `gh extension upgrade`. My recommendation is still the versioned path, on the grounds that upgrading behind containerbase's back would desync the version DB anyway — but that's a judgement call for the issue thread, and I've written up both with their concrete costs.

Commit `6b3f147a` on `feat/gh-cli` (the `install-tool gh` work) is untouched by any of this and still unpushed.