Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .github/workflows/e2e-install.yml
Original file line number Diff line number Diff line change
Expand Up @@ -363,7 +363,9 @@ jobs:
Write-Host "pwsh: $($PSVersionTable.PSVersion)"

Write-Host "--- Node toolchain ---"
Assert-Command 'nvm' 'version'
# Windows runners may already provide the pinned Node version.
# In that case setup skips reinstall, so assert the usable toolchain
# here and leave nvm installer behavior to the dedicated PS tests.
Assert-Command 'node' '--version'
Assert-Command 'npm' '--version'

Expand Down
4 changes: 3 additions & 1 deletion .tool-versions
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
nodejs 22.11.0
nodejs 22.23.2
nvm 0.39.7
nvm-windows 1.2.2
uv 0.4.18
Expand All @@ -7,3 +7,5 @@ squad-cli 0.10.0
gh 2.92.0
delta 0.19.2
lazygit 0.63.0
pi 0.86.1
herdr 0.9.1
8 changes: 6 additions & 2 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Run `bash setup.sh` (Unix) or `powershell -File setup.ps1` (Windows) and walk aw
dev-setup/
|---- setup.sh # Entry point -- Unix (Linux / macOS / WSL); thin router
|---- setup.ps1 # Entry point -- Windows (PowerShell); thin router
|---- .tool-versions # asdf-style pinned versions (node, nvm, uv, gh, copilot-cli)
|---- .tool-versions # asdf-style pinned versions (node, nvm, uv, gh, copilot-cli, pi, herdr)
|---- .gitattributes # eol=lf for *.sh / *.md / *.yml; eol=crlf for *.ps1 / *.psm1 / *.psd1
|---- ARCHITECTURE.md # This file
|---- CHANGELOG.md # Keep-a-Changelog format
Expand All @@ -44,7 +44,9 @@ dev-setup/
| | |---- auth.sh # GitHub CLI authentication (interactive)
| | |---- copilot-cli.sh # Install GitHub Copilot CLI (pin from .tool-versions)
| | |---- gh.sh # Install GitHub CLI (pin from .tool-versions)
| | |---- herdr.sh # Install Herdr (pin from .tool-versions)
| | |---- nvm.sh # Install nvm + Node (pin from .tool-versions)
| | |---- pi.sh # Install pi CLI (pin from .tool-versions)
| | |---- uv.sh # Install uv Python package manager (pin from .tool-versions)
| | `---- zsh.sh # Install zsh + set as default shell
| |
Expand All @@ -61,7 +63,9 @@ dev-setup/
| |---- dotfiles.ps1 # Apply config/dotfiles/ on Windows
| |---- gh.ps1 # GitHub CLI (pin from .tool-versions)
| |---- git.ps1 # Git configuration
| |---- herdr.ps1 # Herdr (pin from .tool-versions)
| |---- nvm.ps1 # nvm-windows + Node (pin from .tool-versions)
| |---- pi.ps1 # pi CLI (pin from .tool-versions)
| |---- profile.ps1 # PowerShell profile injection (PS 5.1 + PS 7+ paths)
| |---- psmux.ps1 # psmux terminal multiplexer (Windows tmux alias)
| |---- uv.ps1 # uv Python package manager (pin from .tool-versions)
Expand Down Expand Up @@ -414,7 +418,7 @@ Tool versions are pinned in the repo-root [`.tool-versions`](./.tool-versions) f
- `scripts/lib/Read-ToolVersion.ps1` -- exposes `Get-ToolVersion -Name <toolname>` (PowerShell)
- `scripts/lib/read-tool-version.sh` -- same contract for POSIX shells (prints to stdout)

Currently pinned: `nodejs`, `nvm`, `nvm-windows`, `uv`, `copilot-cli`, `gh`. Tool installers (e.g. `scripts/windows/tools/nvm.ps1`, `scripts/linux/tools/uv.sh`) call the library at install time so version bumps are a single-file edit.
Currently pinned: `nodejs`, `nvm`, `nvm-windows`, `uv`, `copilot-cli`, `gh`, `pi`, `herdr`. Tool installers (e.g. `scripts/windows/tools/nvm.ps1`, `scripts/linux/tools/uv.sh`) call the library at install time so version bumps are a single-file edit.

---

Expand Down
14 changes: 10 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@
| `gh` | GitHub CLI |
| GitHub Copilot CLI | AI pair programmer in your terminal (`gh copilot`) |
| `squad` CLI | Multi-agent copilot orchestrator (`gosquad` launcher) |
| `pi` | Pi coding agent CLI (opt-in via `--only=pi` / `-Only 'pi'`) |
| `herdr` | Herdr terminal workspace manager (opt-in via `--only=herdr` / `-Only 'herdr'`) |
| `vim` | Modal text editor -- installed on all platforms |
| `tmux` | Terminal multiplexer (Linux/macOS) |
| `psmux` | Terminal multiplexer (Windows) |
Expand Down Expand Up @@ -218,6 +220,8 @@ dev-setup/
| | \-- tools/ -- Individual tool install scripts
| | +-- auth.sh -- GitHub CLI authentication (interactive)
| | +-- copilot-cli.sh
| | +-- herdr.sh
| | +-- pi.sh
| | +-- squad-cli.sh
| +-- gh.sh
| | +-- nvm.sh
Expand All @@ -229,9 +233,9 @@ dev-setup/
| \-- tools/ -- Per-tool install scripts
| +-- auth.ps1 -- GitHub CLI authentication (interactive)
| +-- copilot.ps1, dotfiles.ps1, gh.ps1, git.ps1, nvm.ps1
| +-- profile.ps1, psmux.ps1, squad-cli.ps1
| +-- herdr.ps1, pi.ps1, profile.ps1, psmux.ps1, squad-cli.ps1
| +-- uv.ps1, vim.ps1
| \-- (10 files total)
| \-- (12 files total)
+-- config/
| \-- dotfiles/ -- Dotfile templates (.aliases, .gitconfig, .editorconfig, etc.)
| \-- install.sh -- Dotfile installer
Expand Down Expand Up @@ -363,12 +367,14 @@ python scripts/lib/ascii-sweep.py # apply in-place
Tool versions are pinned in `.tool-versions` at the repo root (asdf/mise format). This file is the single source of truth for every tool version installed by setup, including `nvm-windows`. Setup scripts read it directly via `scripts/lib/read-tool-version.sh` (POSIX) and `scripts/lib/Read-ToolVersion.ps1` (`Get-ToolVersion`) -- no asdf or mise dependency needed.

```
nodejs 22.11.0
nodejs 22.23.2
nvm 0.39.7
nvm-windows 1.2.2
uv 0.4.18
copilot-cli 1.0.48
copilot-cli 1.0.69
gh 2.92.0
pi 0.86.1
herdr 0.9.1
```

To bump a tool version, edit the version number in `.tool-versions` and re-run setup. Each line is `toolname version`, one per line. Blank lines and lines starting with `#` are ignored.
Expand Down
83 changes: 83 additions & 0 deletions scripts/linux/tools/herdr.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
#!/usr/bin/env bash
# scripts/linux/tools/herdr.sh -- Install Herdr at pinned version via the official installer
#
# Called by: scripts/linux/setup.sh
# Idempotent: yes -- version-aware; upgrades if installed version != pinned version.
# Opt-in: NOT in DEFAULT_TOOLS; only runs when requested via --only=herdr.
#
# Source basis:
# - Official Unix installer: https://herdr.dev/install.sh
# - Stable release manifest: https://herdr.dev/latest.json
#
# This wrapper keeps dev-setup's version pinning contract by requiring the
# pinned version to match the current stable manifest before running the
# official installer.

set -euo pipefail

# shellcheck disable=SC1091
. "$(dirname "${BASH_SOURCE[0]}")/../lib/log.sh"

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
HERDR_VERSION="$(sh "${SCRIPT_DIR}/../../lib/read-tool-version.sh" herdr)"
MANIFEST_URL="https://herdr.dev/latest.json"
INSTALLER_URL="https://herdr.dev/install.sh"
INSTALL_DIR="${HERDR_INSTALL_DIR:-$HOME/.local/bin}"

INSTALLED_VERSION=""
if command -v herdr &>/dev/null; then
INSTALLED_VERSION="$(timeout 10 herdr --version 2>&1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true)"
fi

if [ "${INSTALLED_VERSION}" = "${HERDR_VERSION}" ]; then
log_ok "herdr already at pinned version ${HERDR_VERSION}"
exit 0
fi

if [ -n "${INSTALLED_VERSION}" ]; then
log_info "herdr ${INSTALLED_VERSION} installed; upgrading to pinned ${HERDR_VERSION}..."
else
log_info "Installing herdr ${HERDR_VERSION}..."
fi

MANIFEST="$(curl -fsSL --retry 3 --connect-timeout 10 --max-time 20 "$MANIFEST_URL")" || {
log_error "Unable to fetch ${MANIFEST_URL}"
exit 1
}
MANIFEST_VERSION="$(awk -F '"' '/^[[:space:]]*"version"[[:space:]]*:/ { print $4; found=1 } END { if (!found) exit 1 }' <<EOF
$MANIFEST
EOF
)" || {
log_error "Could not determine Herdr stable version from ${MANIFEST_URL}"
exit 1
}
if [ -z "$MANIFEST_VERSION" ]; then
log_error "Could not determine Herdr stable version from ${MANIFEST_URL}"
exit 1
fi
if [ "$MANIFEST_VERSION" != "$HERDR_VERSION" ]; then
log_error "Pinned herdr version ${HERDR_VERSION} does not match current stable manifest version ${MANIFEST_VERSION}"
log_error "Update .tool-versions to the current stable release before using the official Herdr installer path"
exit 1
fi

TMP_DIR="$(mktemp -d)"
trap 'rm -rf "$TMP_DIR"' EXIT
INSTALLER_PATH="${TMP_DIR}/install.sh"

curl -fsSL "$INSTALLER_URL" -o "$INSTALLER_PATH"
chmod +x "$INSTALLER_PATH"
HERDR_INSTALL_DIR="$INSTALL_DIR" sh "$INSTALLER_PATH"

ACTUAL_VERSION=""
if command -v herdr &>/dev/null; then
ACTUAL_VERSION="$(timeout 10 herdr --version 2>&1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true)"
elif [ -x "${INSTALL_DIR}/herdr" ]; then
ACTUAL_VERSION="$(timeout 10 "${INSTALL_DIR}/herdr" --version 2>&1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true)"
fi
if [ "$ACTUAL_VERSION" != "$HERDR_VERSION" ]; then
log_error "herdr install completed but version check failed (expected ${HERDR_VERSION}, got ${ACTUAL_VERSION:-missing})"
exit 1
fi

log_ok "herdr installed at ${HERDR_VERSION}"
53 changes: 53 additions & 0 deletions scripts/linux/tools/pi.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
#!/usr/bin/env bash
# scripts/linux/tools/pi.sh -- Install pi CLI globally via npm at pinned version
#
# Called by: scripts/linux/setup.sh
# Idempotent: yes -- version-aware; upgrades if installed version != pinned version.
# Opt-in: NOT in DEFAULT_TOOLS; only runs when requested via --only=pi.
#
# Install mechanism: npm install -g --ignore-scripts @earendil-works/pi-coding-agent@<version>
# This is the documented install path and supports exact version pinning.

set -euo pipefail

# shellcheck disable=SC1091
. "$(dirname "${BASH_SOURCE[0]}")/../lib/log.sh"

# Source nvm if available, to get node/npm on PATH in this subshell.
export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
# shellcheck source=/dev/null
if [ -s "$NVM_DIR/nvm.sh" ]; then
. "$NVM_DIR/nvm.sh" --no-use
nvm use default 2>/dev/null || true
fi

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PI_VERSION="$(sh "${SCRIPT_DIR}/../../lib/read-tool-version.sh" pi)"
PI_PACKAGE='@earendil-works/pi-coding-agent'

log_info "Pinned pi version: ${PI_VERSION}"

# Detect installed version; use timeout to avoid hangs from shell startup hooks.
INSTALLED_VERSION=""
if command -v pi &>/dev/null; then
INSTALLED_VERSION="$(timeout 10 pi --version 2>&1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true)"
fi

if [ "${INSTALLED_VERSION}" = "${PI_VERSION}" ]; then
log_ok "pi already at pinned version ${PI_VERSION}"
exit 0
fi

if [ -n "${INSTALLED_VERSION}" ]; then
log_info "pi ${INSTALLED_VERSION} installed; upgrading to pinned ${PI_VERSION}..."
else
log_info "Installing pi ${PI_VERSION}..."
fi

if ! command -v npm &>/dev/null; then
log_warn "npm not found -- cannot install pi via npm; run 'npm install -g --ignore-scripts ${PI_PACKAGE}@${PI_VERSION}' once Node is available"
exit 0
fi

npm install -g --no-fund --no-audit --ignore-scripts "${PI_PACKAGE}@${PI_VERSION}"
log_ok "pi installed at ${PI_VERSION}"
4 changes: 4 additions & 0 deletions scripts/windows/setup.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ $ErrorActionPreference = 'Stop'
. "$PSScriptRoot\tools\git-hook.ps1"
. "$PSScriptRoot\tools\delta.ps1"
. "$PSScriptRoot\tools\lazygit.ps1"
. "$PSScriptRoot\tools\pi.ps1"
. "$PSScriptRoot\tools\herdr.ps1"

# ---------------------------------------------------------------------------
# $DefaultTools -- single ordered source of truth for a no-arg default run.
Expand Down Expand Up @@ -97,6 +99,8 @@ $ToolRegistry = [ordered]@{
'git-hook' = { Install-GitHook }
'delta' = { Install-Delta }
'lazygit' = { Install-Lazygit }
'pi' = { Install-Pi }
'herdr' = { Install-Herdr }
}

# ---------------------------------------------------------------------------
Expand Down
79 changes: 79 additions & 0 deletions scripts/windows/tools/herdr.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# scripts/windows/tools/herdr.ps1 - Herdr installer
#
# Installs Herdr at pinned version via the official Windows installer.
# Version-aware: upgrades if installed version != pinned version.
# Opt-in: NOT in $DefaultTools; only runs when requested via -Only 'herdr'.
#
# Source basis:
# - Official Windows installer: https://herdr.dev/install.ps1
# - Stable release manifest: https://herdr.dev/latest.json
#
# This wrapper keeps dev-setup's version pinning contract by requiring the
# pinned version to match the current stable manifest before running the
# official installer.

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

. "$PSScriptRoot\..\lib\logging.ps1"
. "$PSScriptRoot\..\lib\path.ps1"
. "$PSScriptRoot\..\..\lib\Read-ToolVersion.ps1"

function Install-Herdr {
$HerdrVersion = Get-ToolVersion -Name 'herdr'
$ManifestUrl = 'https://herdr.dev/latest.json'
$InstallerUrl = 'https://herdr.dev/install.ps1'

$InstalledVersion = ''
if (Get-Command herdr -ErrorAction SilentlyContinue) {
$raw = (herdr --version 2>&1) | Select-Object -First 1 | Out-String
$m = [regex]::Match($raw, '[0-9]+\.[0-9]+\.[0-9]+')
if ($m.Success) { $InstalledVersion = $m.Value }
}

if ($InstalledVersion -eq $HerdrVersion) {
Write-Ok "herdr already at pinned version $HerdrVersion"
return
}

if ($InstalledVersion) {
Write-Info "herdr $InstalledVersion installed; upgrading to pinned $HerdrVersion..."
} else {
Write-Info "Installing herdr $HerdrVersion..."
}

$manifest = Invoke-RestMethod -Uri $ManifestUrl
if (-not $manifest.version) {
throw "Could not determine Herdr stable version from $ManifestUrl"
}
if ([string]$manifest.version -ne $HerdrVersion) {
throw "Pinned herdr version $HerdrVersion does not match current stable manifest version $($manifest.version)"
}

$tmpDir = Join-Path $env:TEMP ("herdr-dev-setup-" + [guid]::NewGuid().ToString('N'))
$installerPath = Join-Path $tmpDir 'install.ps1'
New-Item -ItemType Directory -Path $tmpDir -Force | Out-Null
try {
Invoke-WebRequest -Uri $InstallerUrl -OutFile $installerPath -UseBasicParsing
& powershell -NoProfile -ExecutionPolicy Bypass -File $installerPath -Channel stable
if ($LASTEXITCODE -ne 0) {
throw "Herdr installer exited with code $LASTEXITCODE"
}
}
finally {
Remove-Item -LiteralPath $tmpDir -Recurse -Force -ErrorAction SilentlyContinue
}

Refresh-SessionPath
$ActualVersion = ''
if (Get-Command herdr -ErrorAction SilentlyContinue) {
$raw = (herdr --version 2>&1) | Select-Object -First 1 | Out-String
$m = [regex]::Match($raw, '[0-9]+\.[0-9]+\.[0-9]+')
if ($m.Success) { $ActualVersion = $m.Value }
}
if ($ActualVersion -ne $HerdrVersion) {
throw "herdr install completed but version check failed (expected $HerdrVersion, got $ActualVersion)"
}

Write-Ok "herdr installed at $HerdrVersion"
}
46 changes: 46 additions & 0 deletions scripts/windows/tools/pi.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# scripts/windows/tools/pi.ps1 - pi CLI installer
#
# Installs pi globally via npm at pinned version from .tool-versions.
# Version-aware: upgrades if installed version != pinned version.
# Package: @earendil-works/pi-coding-agent

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

. "$PSScriptRoot\..\lib\logging.ps1"
. "$PSScriptRoot\..\lib\path.ps1"
. "$PSScriptRoot\..\..\lib\Read-ToolVersion.ps1"

function Install-Pi {
$PiVersion = Get-ToolVersion -Name 'pi'
$PiPackage = '@earendil-works/pi-coding-agent'

# Detect installed version
$InstalledVersion = ''
if (Get-Command pi -ErrorAction SilentlyContinue) {
$raw = (pi --version 2>&1) | Select-Object -First 1 | Out-String
$m = [regex]::Match($raw, '[0-9]+\.[0-9]+\.[0-9]+')
if ($m.Success) { $InstalledVersion = $m.Value }
}

if ($InstalledVersion -eq $PiVersion) {
Write-Ok "pi already at pinned version $PiVersion"
return
}

if ($InstalledVersion) {
Write-Info "pi $InstalledVersion installed; upgrading to pinned $PiVersion..."
} else {
Write-Info "Installing pi $PiVersion..."
}

Refresh-SessionPath
if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
Write-Warn "npm not found -- cannot install pi via npm; run 'npm install -g --ignore-scripts `"$PiPackage@$PiVersion`"' once Node is available"
return
}

npm install -g --no-fund --no-audit --ignore-scripts "$PiPackage@$PiVersion"
Assert-LastExit -ToolName 'pi'
Write-Ok "pi installed at $PiVersion"
}
Loading
Loading