spinup-ts 0.1.0

package/template/.devcontainer/README.md

@@ -0,0 +1,223 @@
+# Claude Code Devcontainer
+
+A Claude Code–optimised development environment for any project. Mirrors the local macOS
+toolchain inside a Linux container so agents can run with `--dangerously-skip-permissions`
+with a contained blast radius.
+
+---
+
+## Quick start
+
+### Using this repo as your devcontainer
+
+1. Open the `devcontainer/` repo in VS Code
+2. When prompted, choose **"Reopen in Container"** (or run `Dev Containers: Reopen in Container`)
+3. The image builds once; subsequent opens are fast
+
+### Adding this devcontainer to another project
+
+Run from your host terminal:
+
+```bash
+# add the alias once (to ~/.zshrc or ~/.aliases.zsh)
+alias devcontainer-init='~/github/joeblackwaslike/devcontainer/.devcontainer/scripts/init-project.sh'
+
+# then, in any project root:
+cd ~/github/myproject
+devcontainer-init
+```
+
+---
+
+## Scripts reference
+
+### `scripts/setup.sh` — post-create one-time setup
+
+**When it runs:** automatically via `postCreateCommand` the first time the container is built.
+Does not re-run on subsequent attaches.
+
+**What it does:**
+
+| Step | Detail |
+| --- | --- |
+| Skills symlink | Recreates `~/.claude/skills → ~/.agents/skills` inside the container so Claude Code can find all installed skills from the host mount |
+| mkcert CA | Installs the local CA generated by `mkcert` so self-signed TLS certs are trusted in this container |
+
+**Manual re-run** (if setup failed or mounts changed):
+
+```bash
+bash .devcontainer/scripts/setup.sh
+```
+
+#### Extending setup.sh
+
+Add any one-time initialisation that should run exactly once per image build.
+For steps that should repeat on every attach, use `custom-setup.sh` instead (see below).
+
+---
+
+### `scripts/discover-deps.sh` — per-attach dependency installation
+
+**When it runs:** automatically via `postAttachCommand` every time you attach VS Code to the
+running container. It is fast when nothing has changed (package managers skip work when
+lock files haven't changed).
+
+**What it detects** (first match per language wins):
+
+| Signal file | Action |
+| --- | --- |
+| `pnpm-lock.yaml` | `pnpm install` |
+| `bun.lockb` | `bun install` |
+| `yarn.lock` | `yarn install` |
+| `package-lock.json` | `npm ci` |
+| `package.json` (no lock) | `npm install` |
+| `pyproject.toml` | `uv sync` |
+| `requirements.txt` | `uv pip install -r requirements.txt` |
+| `Cargo.toml` | `cargo fetch` |
+| `go.mod` | `go mod download` |
+| `Gemfile` | `bundle install` |
+| `.devcontainer/custom-setup.sh` | `bash .devcontainer/custom-setup.sh` |
+
+**Manual re-run:**
+
+```bash
+bash .devcontainer/scripts/discover-deps.sh
+```
+
+**Skip discovery** (useful in CI or when you want full control):
+
+```bash
+DISCOVER_DEPS_SKIP=1 bash .devcontainer/scripts/discover-deps.sh
+# or set it permanently in devcontainer.json remoteEnv:
+#   "DISCOVER_DEPS_SKIP": "1"
+```
+
+**Per-project customisation** — create `.devcontainer/custom-setup.sh` in the project repo.
+It runs last, after all auto-detection. The `init-project.sh` CLI generates a stub for you.
+
+```bash
+#!/usr/bin/env bash
+# .devcontainer/custom-setup.sh — project-specific hook
+
+# Install a project-specific CLI tool
+npm install -g @myorg/dev-tools
+
+# Seed the local database on first attach
+psql -U postgres -c "CREATE DATABASE myapp;" 2>/dev/null || true
+psql -U postgres myapp < db/seed.sql 2>/dev/null || true
+
+# Add a project env var to the shell
+echo 'export APP_ENV=devcontainer' >> ~/.zshrc
+```
+
+See [DISCOVER-DEPS.md](DISCOVER-DEPS.md) for full documentation.
+
+---
+
+### `scripts/init-project.sh` — bootstrap devcontainer into a project
+
+**Purpose:** copies this `.devcontainer/` directory into any project so it gets the full
+Claude Code environment without duplicating the config.
+
+**Install the alias** (add to `~/.zshrc` or `~/.aliases.zsh` on your host machine):
+
+```bash
+alias devcontainer-init='~/github/joeblackwaslike/devcontainer/.devcontainer/scripts/init-project.sh'
+```
+
+**Usage:**
+
+```text
+devcontainer-init [target-dir] [options]
+
+Arguments:
+  target-dir    Project to initialise (default: current directory)
+
+Options:
+  --name NAME   Override the devcontainer name (default: project dir name)
+  --force       Overwrite an existing .devcontainer/ without prompting
+  --dry-run     Show what would happen without writing any files
+  --help        Show help
+```
+
+**Examples:**
+
+```bash
+# Initialise the current directory
+cd ~/github/myproject && devcontainer-init
+
+# Initialise a specific directory
+devcontainer-init ~/github/anotherproject
+
+# Preview what would happen (no writes)
+devcontainer-init --dry-run
+
+# Replace an existing config
+devcontainer-init --force
+
+# Set a custom container name
+devcontainer-init --name "myproject-dev"
+```
+
+**What it does step by step:**
+
+1. Validates the target is a git repository root
+2. Copies `.devcontainer/` from this repo into the target project
+3. Sets the `"name"` field in `devcontainer.json` to match the project name
+4. Creates a `.devcontainer/custom-setup.sh` stub with inline usage examples
+5. Optionally adds `.devcontainer/` to `.gitignore` (prompts you — the config is maintained
+   centrally here so projects usually don't need to commit it)
+6. Prints next-step instructions
+
+**After running:**
+
+```bash
+cd ~/github/myproject
+code .   # open in VS Code
+# Then: "Dev Containers: Reopen in Container"
+# Edit .devcontainer/custom-setup.sh for project-specific setup
+```
+
+---
+
+## How the environment is mirrored from your Mac
+
+All mounts are read-only unless Claude Code needs to write state to the path.
+
+| Mount | Mode | Purpose |
+| --- | --- | --- |
+| `~/.claude` | read-write | Claude Code: sessions, memory, settings, plugins |
+| `~/.claude.json` | read-write | Claude Code account config |
+| `~/.agents` | read-only | Shared skills and agent definitions |
+| `~/.ssh` | read-only | SSH keys (git push, remote access) |
+| `~/.gitconfig` | read-only | Git identity and config |
+| `~/.config/gh` | read-only | GitHub CLI auth tokens |
+| `~/github/joeblackwaslike` | read-only | Local repos — resolves MCP server paths from settings.json |
+| `~/.gemini` | read-write | Gemini CLI: settings, history, skills, session state |
+| `~/.codex` | read-write | Codex CLI: config, auth, memories, skills, plugins, logs |
+| `~/.openclaw` | read-write | openclaw: credentials, settings, workspace, logs |
+| `~/.config/opencode` | read-write | opencode settings |
+| `~/.local/share/opencode` | read-write | opencode runtime data |
+| `~/.orbstack/run/docker.sock` | read-write | Docker socket (OrbStack) |
+
+### MCP server path compatibility
+
+`settings.json` on the host contains MCP server paths like
+`/Users/joe/github/joeblackwaslike/mcp-exec/dist/src/server.js`.
+The Dockerfile adds a symlink `ln -sf /home/vscode /Users/joe` so these
+paths resolve correctly inside the container once `~/github/joeblackwaslike`
+is mounted.
+
+### API keys
+
+All keys are passed through `remoteEnv` in `devcontainer.json` from your
+local environment. Nothing is baked into the image. Make sure the keys are
+exported in your shell before opening the container.
+
+---
+
+## Reference
+
+- [TOOLS.md](TOOLS.md) — complete catalog of every installed tool, version strategy, and install method
+- [DISCOVER-DEPS.md](DISCOVER-DEPS.md) — deep dive on dependency auto-detection and per-project customisation
+- [SETUP.md](SETUP.md) — one-time host setup: API keys, 1Password service account token, aliases, directory checks

package/template/.devcontainer/SETUP.md

@@ -0,0 +1,191 @@
+# Host Setup Guide
+
+One-time setup steps for your macOS host before opening the devcontainer for the first time.
+These steps only need to be done once per machine.
+
+---
+
+## 1. Export required API keys
+
+The container receives all secrets via `remoteEnv` — nothing is baked into the image.
+Add these exports to your `~/.zshrc` or `~/.aliases.zsh` and source the file (or open a new shell):
+
+```bash
+# Anthropic / Claude
+export ANTHROPIC_API_KEY="sk-ant-..."
+export ANTHROPIC_MODEL="claude-opus-4-5"
+export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5-20251001"
+
+# OpenAI / Codex
+export OPENAI_API_KEY="sk-..."
+export OPENAI_ORG_ID="org-..."
+
+# 1Password CLI (see section 2)
+export OP_SERVICE_ACCOUNT_TOKEN="ops1_..."
+
+# MCP server keys
+export CONTEXT7_API_KEY="..."
+export EXA_API_KEY="..."
+export TAVILY_API_KEY="..."
+export FIRECRAWL_API_KEY="..."
+export PERPLEXITY_API_KEY="..."
+export BRAVE_API_KEY="..."
+export REF_API_KEY="..."
+```
+
+The container will silently pass through any variable that isn't set — tools that depend on
+missing keys will fail at runtime, not at container build time.
+
+---
+
+## 2. 1Password CLI setup
+
+The container uses the **1Password Service Account** authentication method. This is the right
+approach when the host has no 1Password desktop app socket to mount (OrbStack containers
+can't access the macOS GUI app socket).
+
+### Create a service account token
+
+1. Open [1Password.com](https://1password.com) → your account → **Developer Tools** → **Service Accounts**
+2. Click **New Service Account**
+3. Give it a name (e.g., `devcontainer`)
+4. Grant access to the vaults the container needs (e.g., `cloudflare`, `porkbun`, `dev`)
+5. Click **Generate Token** — copy it immediately (shown only once)
+
+Docs: https://developer.1password.com/docs/service-accounts/
+
+### Export the token
+
+```bash
+# In ~/.zshrc or ~/.aliases.zsh (already listed in section 1):
+export OP_SERVICE_ACCOUNT_TOKEN="ops1_..."
+```
+
+### Verify inside the container
+
+After opening the container:
+
+```bash
+op whoami
+# Should print: account URL, user ID, and service account name
+```
+
+### Usage in MCP server commands
+
+The `op` CLI is used with `op run` to inject secrets into MCP server processes:
+
+```bash
+# Example: inject secrets into a Cloudflare MCP server
+op run --env-file=.env.op -- node dist/server.js
+```
+
+MCP server configurations that need 1Password secrets reference `op://vault/item/field`
+directly in their environment files.
+
+---
+
+## 3. Install the `devcontainer-init` alias
+
+Add this alias to your macOS `~/.zshrc` (not the container's) so you can bootstrap the
+devcontainer into any project from anywhere:
+
+```bash
+alias devcontainer-init='~/github/joeblackwaslike/devcontainer/.devcontainer/scripts/init-project.sh'
+```
+
+Then run `source ~/.zshrc` or open a new terminal.
+
+Usage:
+
+```bash
+# Bootstrap the devcontainer into a project
+cd ~/github/myproject && devcontainer-init
+
+# Or target a directory directly
+devcontainer-init ~/github/anotherproject
+
+# Preview without writing
+devcontainer-init --dry-run
+```
+
+See [init-project.sh](scripts/init-project.sh) and [README.md](README.md) for full documentation.
+
+---
+
+## 4. Verify required host directories exist
+
+The devcontainer mounts several directories from your home folder. Most are created by their
+respective tools, but double-check before first use:
+
+```bash
+ls ~/.claude       # Claude Code config — must exist
+ls ~/.claude.json  # Claude Code account — created on first claude login
+ls ~/.agents       # Skills + agent definitions
+ls ~/.ssh          # SSH keys
+ls ~/.gitconfig    # Git identity (can be a file, not a dir)
+ls ~/.config/gh    # GitHub CLI auth
+ls ~/.gemini       # Gemini CLI — created on first gemini run
+ls ~/.codex        # Codex CLI — created on first codex run
+ls ~/.openclaw     # openclaw — created on first run
+ls ~/.config/opencode
+ls ~/.local/share/opencode
+ls ~/.orbstack/run/docker.sock  # OrbStack Docker socket
+```
+
+Directories that don't exist will cause the container to fail to start. Create missing ones:
+
+```bash
+mkdir -p ~/.agents ~/.gemini ~/.codex ~/.openclaw ~/.config/opencode ~/.local/share/opencode
+```
+
+---
+
+## 5. Open the container
+
+```bash
+cd ~/github/joeblackwaslike/devcontainer
+code .
+# VS Code: "Dev Containers: Reopen in Container"
+```
+
+The first build takes several minutes. Subsequent opens are fast (image is cached).
+
+---
+
+## 6. Publish the pre-built image (optional, one-time)
+
+Building the image once and pushing it to GHCR means no project ever has to build it locally.
+The `devcontainer-init` script automatically configures new projects to pull the pre-built image.
+
+### Authenticate to GHCR
+
+```bash
+# Generate a token at https://github.com/settings/tokens
+# Scopes required: write:packages, read:packages, delete:packages
+echo $GITHUB_TOKEN | docker login ghcr.io -u joeblackwaslike --password-stdin
+```
+
+### Build and push
+
+```bash
+cd ~/github/joeblackwaslike/devcontainer
+make push
+```
+
+This builds a multi-arch image (`linux/amd64` + `linux/arm64`) and pushes it to
+`ghcr.io/joeblackwaslike/devcontainer:latest`.
+
+### Make the package public (one-time)
+
+After the first push, go to
+`https://github.com/users/joeblackwaslike/packages/container/devcontainer/settings`
+and set visibility to **Public** so projects can pull it without authentication.
+
+### Re-publish after Dockerfile changes
+
+```bash
+make push
+```
+
+Projects pull `latest` on the next container rebuild — no changes needed in their
+`devcontainer.json`.

package/template/.devcontainer/TOOLS.md

@@ -0,0 +1,215 @@
+# Installed Tools Catalog
+
+Comprehensive reference for everything installed in this devcontainer image.
+Each section lists the install method, version strategy, and purpose.
+Update this file whenever you add, remove, or upgrade a tool.
+
+---
+
+## System packages (apt / Aptfile)
+
+Installed at image build time via `seatgeek/bash-aptfile` running against `Aptfile`.
+
+| Package | Purpose |
+|---|---|
+| autoconf, automake, cmake, ninja-build, make | Build tooling |
+| build-essential, gcc, llvm | C/C++ compiler toolchain |
+| libssl-dev, libffi-dev, libreadline-dev, libsqlite3-dev, + ~30 more libs | Dev headers for language runtimes |
+| bat | `cat` with syntax highlighting |
+| curl, wget, httpie | HTTP clients |
+| fzf | Fuzzy finder |
+| git, git-lfs | Version control |
+| gnupg, gpg | Cryptography |
+| graphviz, imagemagick, tesseract-ocr, ghostscript | Graphics / OCR |
+| jq, yq | JSON/YAML processors (system fallback; asdf versions take precedence) |
+| neovim, vim, tmux | Terminal editors / multiplexer |
+| pgcli, pgloader | PostgreSQL clients |
+| pipx | Python CLI tool installer (system fallback; asdf version used at runtime) |
+| redis-server | In-container Redis |
+| ripgrep | Fast grep |
+| shellcheck, shfmt | Shell script linting / formatting |
+| sqlite3, libsqlite3-dev | SQLite |
+| procps, tree, lsof, rsync, unzip | General utilities |
+| zsh, locales | Shell + locale |
+
+---
+
+## PostgreSQL 18 (PGDG apt repo)
+
+Added via the [official PGDG apt repository](https://www.postgresql.org/download/linux/ubuntu/).
+
+| Package | Version | Notes |
+|---|---|---|
+| postgresql-18 | latest 18.x | Server |
+| postgresql-client-18 | latest 18.x | `psql` client |
+| libpq-dev | latest 18.x | C headers for psql bindings |
+
+To upgrade: update the PGDG source list in the Dockerfile and rebuild.
+
+---
+
+## 1Password CLI
+
+Installed via the [official 1Password apt repo](https://developer.1password.com/docs/cli/get-started/).
+
+| Tool | Command | Purpose |
+|---|---|---|
+| 1Password CLI | `op` | `op run` wraps MCP server commands with secrets from 1Password vaults (cloudflare, porkbun MCP servers) |
+
+---
+
+## Language runtimes (asdf)
+
+All managed by [asdf](https://asdf-vm.com/) v0.18.1. `ASDF_DATA_DIR=/home/vscode/.asdf`.
+Version specs use `latest:N` to pin major while tracking minor/patch updates.
+
+| Plugin | Version spec | Command(s) | Notes |
+|---|---|---|---|
+| python | `latest:3` | `python3`, `pip3` | Primary Python runtime |
+| nodejs | `lts` | `node`, `npm` | LTS line |
+| ruby | `latest:4` | `ruby`, `gem` | Ruby 4.x |
+| golang | `latest:1` | `go` | Go 1.x |
+| rust | `stable` | `cargo`, `rustc`, `rustup` | Stable toolchain |
+| bun | `latest:1` | `bun`, `bunx` | JS runtime / bundler |
+| pnpm | `latest:10` | `pnpm`, `pnpx` | pnpm 10.x |
+| deno | `latest` | `deno` | Deno runtime |
+| awscli | `latest:2` | `aws` | AWS CLI v2 |
+| gcloud | `latest` | `gcloud`, `gsutil` | Google Cloud SDK |
+| pipx | `latest:1` | `pipx` | Python CLI tool isolation |
+| supabase-cli | `latest` | `supabase` | Supabase management CLI |
+| yarn | `latest` | `yarn` | Yarn package manager |
+| jq | `latest` | `jq` | JSON processor (asdf version shadows apt) |
+| yq | `latest` | `yq` | YAML/JSON processor |
+| just | `latest` | `just` | Command runner (Justfile) |
+
+To add a new asdf plugin: `asdf plugin add <name> && asdf install <name> latest && asdf set -u <name> latest`
+
+---
+
+## Package managers
+
+| Tool | Install method | Purpose |
+|---|---|---|
+| uv | `curl -LsSf https://astral.sh/uv/install.sh` → `/usr/local/bin` | Fast Python package/project manager |
+| pipx | asdf (listed above) | Isolated Python CLI tool environments |
+| pnpm | asdf (listed above) | Node package manager |
+| yarn | asdf (listed above) | Node package manager |
+| volta | `curl https://get.volta.sh` → `/usr/local/share/volta` | Supplemental JS toolchain for volta-pinned repos |
+
+---
+
+## CLI tools — Rust / cargo
+
+Installed with `CARGO_INSTALL_ROOT=/usr/local` → binaries land in `/usr/local/bin/`.
+
+| Crate | Command | Purpose |
+|---|---|---|
+| diskus | `diskus` | Fast `du` replacement |
+| du-dust | `dust` | Directory size visualiser |
+| eza | `eza` | Modern `ls` replacement |
+| hyperfine | `hyperfine` | CLI benchmarking tool |
+| procs | `procs` | Modern `ps` replacement |
+| sad | `sad` | CLI search-and-replace (stream ed) |
+| git-delta | `delta` | Syntax-highlighted git diffs |
+
+To add a cargo tool: add to the `cargo install` block in the Dockerfile and add a row here.
+
+---
+
+## CLI tools — Go
+
+Installed with `GOPATH=/usr/local` → binaries land in `/usr/local/bin/`.
+
+| Module | Command | Purpose |
+|---|---|---|
+| `github.com/steveyegge/beads/cmd/bd` | `bd` | Beads task manager (Claude Code plugin) |
+| `golang.org/x/tools/cmd/stringer` | `stringer` | Go generate string methods for types |
+| `github.com/gastownhall/gastown/cmd/gt` | `gt` | Multi-agent workspace manager |
+| `github.com/walles/moor/v2/cmd/moor` | `moor` | Terminal pager (used as PAGER / MANPAGER) |
+
+---
+
+## CLI tools — npm globals
+
+Installed with `npm install -g` into the asdf-managed Node installation.
+After install, `asdf reshim nodejs` regenerates shims in `$ASDF_DATA_DIR/shims/`.
+
+| Package | Command | Purpose |
+|---|---|---|
+| `@anthropic-ai/claude-code` | `claude` | Claude Code CLI |
+| `@devcontainers/cli` | `devcontainer` | Dev Containers CLI |
+| `@google/gemini-cli` | `gemini` | Google Gemini CLI |
+| `tsx` | `tsx` | TypeScript execute (ts-node alternative) |
+
+---
+
+## CLI tools — binary releases (GitHub)
+
+Architecture-aware: ARM64 or amd64 selected at build time via `uname -m`.
+
+| Tool | GitHub repo | Command | Purpose |
+|---|---|---|---|
+| dolt | `dolthub/dolt` | `dolt` | Git for data — versioned SQL database |
+| glow | `charmbracelet/glow` | `glow` | Markdown renderer for the terminal |
+| mkcert | `FiloSottile/mkcert` | `mkcert` | Local CA and TLS certificate generator |
+| step | `smallstep/cli` | `step` | Smallstep certificate + PKI CLI |
+
+All binaries installed to `/usr/local/bin/`.
+To upgrade, bump the `latest` release logic in the Dockerfile or pin a tag.
+
+---
+
+## Python tools (pipx)
+
+Installed with `PIPX_HOME=/usr/local/pipx` and `PIPX_BIN_DIR=/usr/local/bin`.
+Executables land directly in `/usr/local/bin/`.
+
+| Package | Commands | Purpose |
+|---|---|---|
+| sqlfluff | `sqlfluff` | SQL linter and formatter |
+| csvkit | `csvcut`, `csvjoin`, `csvstat`, `in2csv`, `sql2csv`, + more | CSV Swiss army knife |
+
+---
+
+## oh-my-posh
+
+Installed via `curl -s https://ohmyposh.dev/install.sh` to `/usr/local/bin/oh-my-posh`.
+Theme configured in `.devcontainer/.mytheme.omp.yaml` (copied into the container image).
+
+---
+
+## AI / agent tools summary
+
+| Tool | Source | Notes |
+|---|---|---|
+| claude (Claude Code) | npm: `@anthropic-ai/claude-code` | Alias `claude='claude --dangerously-skip-permissions'` set in .zshrc |
+| gemini-cli | npm: `@google/gemini-cli` | Google Gemini terminal agent |
+| beads (`bd`) | Go: `github.com/steveyegge/beads` | Task management for Claude Code |
+| gastown (`gt`) | Go: `github.com/gastownhall/gastown` | Multi-agent workspace orchestration; depends on dolt |
+| opencode | **not yet installed** | Binary not on npm; TODO: add GitHub release download when stable |
+
+---
+
+## Devcontainer features
+
+| Feature | Purpose |
+|---|---|
+| `ghcr.io/devcontainers/features/docker-in-docker:2` | Docker daemon inside the container (non-root enabled) |
+| `ghcr.io/devcontainers/features/node:1` | Configures npm global prefix for non-root user |
+
+---
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-05-21 | Initial comprehensive install: PostgreSQL 18, 1Password CLI, deno, just, eza, diskus, du-dust, hyperfine, procs, sad, git-delta, beads, stringer, gastown, moor, oh-my-posh, uv, volta, dolt, glow, mkcert, step, sqlfluff, csvkit, @anthropic-ai/claude-code, @devcontainers/cli, @google/gemini-cli, tsx |
+| 2026-05-21 | Bug fix: asdf `ASDF_DATA_DIR=/home/vscode/.asdf` so runtime user can access shims |
+| 2026-05-21 | Bug fix: removed ghost Homebrew init from .zshrc |
+| 2026-05-21 | Added macOS path alias `/Users/joe → /home/vscode` for settings.json MCP path compat |
+| 2026-05-21 | Added mounts: ~/.agents, ~/.gitconfig, ~/.config/gh, ~/github/joeblackwaslike |
+| 2026-05-21 | Added remoteEnv passthrough for all API keys |
+| 2026-05-21 | Added discover-deps.sh auto-dependency install on attach |
+| 2026-05-21 | Added init-project.sh CLI for bootstrapping new projects |
+| 2026-05-21 | Added mounts: ~/.gemini (Gemini CLI), ~/.codex (Codex/openclaw), ~/.openclaw (openclaw workspace) |
+| 2026-05-21 | Added OP_SERVICE_ACCOUNT_TOKEN to remoteEnv (1Password CLI — no socket on this host) |