From e382fa1e33ba15c784cd8f221fabf14706a7c34e Mon Sep 17 00:00:00 2001 From: wayne Date: Mon, 27 Apr 2026 18:45:09 -0400 Subject: [PATCH] v2.1: add imagemagick, chafa, jp2a for ASCII workflow --- CLAUDE.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++ Dockerfile | 1 + README.md | 133 +++++++++++++++++++++------------------------- 3 files changed, 215 insertions(+), 72 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..11f4621 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,153 @@ +# arch-dev — Project Context for Claude Code + +## What this is +A portable, stateless Arch Linux development environment running in Docker. +Headless, riced, mobile-aware. Built for serious dev work from any box — +including from a phone via Termius. + +The tagline that stuck: **"Riced Neovim IDE"** + +--- + +## The Human + +Wayne. Works primarily from mobile (Android + Termius). +Prefers vim keybindings everywhere. Wants things clean and professional — +"Apple good" was the benchmark set early on. Doesn't want walls of text. +Will call you out if you guess instead of reading docs. +Has a Gitea instance at https://code.waynehayesdevelopment.com + +--- + +## Architecture + +``` +arch-dev/ +├── Dockerfile # Arch rolling release, pacman + AUR (yay) +├── docker-compose.yml # Named volume for stateful /home/dev +├── entrypoint.sh # First-run seeding + dotfile update detection +├── .gitignore +├── workspace/ # Bind mount — host-visible project files +└── dotfiles/ # Baked into /etc/skel-arch-dev/ in image + ├── .zshrc # 256-color only, mobile detection, snapshot fns + ├── .aliases + ├── .screenrc # Mobile multiplexer + ├── .config/ + │ ├── starship.toml # Desktop: 256-color Kanagawa Wave approx + │ ├── starship-mobile.toml # Mobile: single line, no icons + │ ├── tmux/tmux.conf # Desktop mux, Ctrl+Space prefix + │ └── nvim/ # Full LSP/lint/format setup +``` + +--- + +## The Stateful Home System (v1.7) + +`/home/dev` is a **named Docker volume** (`arch-dev-home`). Persists across +`--rm` container exits. NOT wiped on exit — only on `docker volume rm`. + +On first run, entrypoint seeds the volume from `/etc/skel-arch-dev/` +(baked into the image). Subsequent runs detect if image dotfiles are newer +and auto-update (with auto-snapshot first). + +### Git-backed snapshots + +`~/.arch-dev-state/` is a separate-git-dir tracking `/home/dev`. +No `.git` folder in `~` — avoids nested git conflicts with project repos. + +Shell functions (defined in .zshrc): +- `snapshot [msg]` / `snap` — tag current state +- `snapshots` / `snaps` — list tags + recent commits +- `rollback ` / `snapr` — reset to tag (confirms first, auto-snaps) +- `diff-state` / `snapd` — what's changed since last commit +- `show-snapshot ` — inspect a tag +- `unsnapshot ` — delete a tag +- `_archdev_git` — raw git wrapper (separate git dir) + +--- + +## The Color Problem (solved in v1.4+) + +Termius on Android cannot render truecolor RGB escape codes. +They show as **purple/magenta backgrounds** on everything. + +**Rules:** +- No `COLORTERM=truecolor` in compose or shell +- No hex colors (`#7E9CD8`) in starship, zsh-syntax-highlighting, tmux +- All shell-visible configs use 256-color ANSI codes (`fg=110` etc.) +- `termguicolors` in neovim is conditional: `vim.env.MOBILE ~= "1"` +- Mobile colorscheme: `habamax` (built-in, 256-color clean) +- Desktop colorscheme: `kanagawa-wave` (needs termguicolors) +- Bufferline disabled on mobile (emits RGB for tab backgrounds) +- noice.nvim removed entirely (bled colors into terminal) + +**Kanagawa Wave 256-color approximations:** +``` +110 = crystalBlue 106 = springGreen 139 = oniViolet +173 = boatYellow 167 = peachRed 66 = waveAqua +242 = fujiGray 250 = fujiWhite 236 = waveBlue +``` + +--- + +## Mobile Detection + +`MOBILE=1` env var (set in Termius host profile) activates: +- Minimal single-line starship prompt (no icons) +- screen auto-attach instead of tmux +- habamax colorscheme in neovim +- termguicolors disabled +- Bufferline disabled +- Compact aliases (`g` for git, etc.) + +--- + +## Plugin API Changes (hard-won knowledge) + +Every one of these bit us. Read docs before touching: + +| Plugin | Issue | Fix | +|--------|-------|-----| +| `leap.nvim` | Moved GitHub→Codeberg | `url = "https://codeberg.org/andyg/leap.nvim"` | +| `leap.nvim` | `add_default_mappings()` removed | Use `(leap)` keymaps directly | +| `nvim-treesitter` | `.configs` module gone | `require("nvim-treesitter").setup{}`, `branch="main"`, `lazy=false` | +| `nvim-surround` | v4 removed `keymaps` table | `require("nvim-surround").setup()` defaults only | +| `nvim-lspconfig` | Framework deprecated in 0.11 | `vim.lsp.config()` + `vim.lsp.enable()` | +| `vim.lsp.with()` | Deprecated | Handlers in `vim.lsp.config("*", { handlers = {} })` | +| `on_attach` | Old pattern | `LspAttach` autocmd | + +--- + +## What's NOT in v1 (coming in v2) + +- nvm + nodejs +- Claude CLI +- Gemini CLI +- Aider +- nvim AI plugin (copilot/avante/codecompanion) + +v2 plan: install AI tools in the stateful container, snapshot as `ai-tools`, +then layer nodejs on top. + +--- + +## Git / Repo + +- Gitea: https://code.waynehayesdevelopment.com/wayne/neovim-ide +- `main` branch = current stable (v1.7) +- `v2` branch = active development +- `v1.7` tag = frozen reference + +Wayne is new to multi-branch git workflow — be explicit about which branch +to be on before any git operations. + +--- + +## Tone / Style Notes + +- Short responses. Wayne reads on mobile. +- No bullet-point walls. Prose or tight tables. +- Don't guess at APIs — fetch the docs first. +- When something breaks, ask for the actual error before debugging. +- Wayne will test each version and report back with screenshots. +- "Apple good" is the visual quality bar. diff --git a/Dockerfile b/Dockerfile index a7ce3b1..15a654c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -24,6 +24,7 @@ RUN pacman -S --noconfirm --needed \ man-db man-pages \ jq tree wget \ rsync \ + imagemagick chafa jp2a \ && pacman -Scc --noconfirm # ── Crown Jewel #2: AUR ─────────────────────────────────────────────────────── diff --git a/README.md b/README.md index b7a7d2b..ecf1e42 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,49 @@ -# arch-dev v1.7 +# arch-dev ### Riced Neovim IDE · Arch Linux · Stateful · Mobile-Aware > *"Like Gentoo without the compiling."* -> Kanagawa Wave · rolling release · AUR-powered · git-snapshotted home +> *I use Arch BTW* + +Kanagawa Wave · rolling release · AUR-powered · git-snapshotted home --- -## What's new in v1.7 +## Branches -- **Stateful `/home/dev`** — your shell history, plugin state, and config tweaks survive container exit -- **Git-backed snapshot system** — commit good states, roll back when things break -- **Auto-snapshot on dotfile updates** — image upgrades preserve your history -- **Mobile improvements** — bufferline disabled on mobile, dashboard uses thin-line ASCII +| Branch | Purpose | +|---|---| +| `main` | Latest stable | +| `v2` | Active development | +| `v1.7` (tag) | Frozen v1.7 reference | --- -## The Snapshot System +## What's in v2 -Your `/home/dev` is a git repo (state in `~/.arch-dev-state/`). When something works, snapshot it. When something breaks, roll back. +### v2.0 — AI tooling +- Claude Code CLI (snapshot after install + login) +- Gemini CLI +- Aider +- nvm + Node.js (for any AI tool that needs it) -```bash -# Working state — save it -snap node-working "NodeJS env with nvm + pnpm" +### v2.1 — Image & ASCII tooling +- ImageMagick — image manipulation +- chafa — modern terminal image rendering (truecolor + sixel) +- jp2a — fast JPEG/PNG to ASCII art -# List your snapshots -snaps +Workflow: AI rough sketch → `chafa --symbols ascii` → hand-tweak -# See what's changed since last snapshot -snapd +--- -# Try something risky, breaks things... no problem -snapr node-working +## v1.7 — What's there now -# Show what's in a snapshot -show-snapshot node-working - -# Remove a snapshot you don't need -unsnapshot old-thing -``` - -What's tracked: dotfiles, configs, neovim plugins, anything in `~`. -What's ignored: `.cache`, `.zsh_history`, build artifacts, log files. - -Snapshots use real git so you can: -- Branch (`_archdev_git checkout -b experimenting`) -- Push to remote (`_archdev_git remote add origin git@...`) -- Diff between snapshots (`_archdev_git diff snap-a snap-b`) +- Stateful `/home/dev` via named Docker volume +- Git-backed snapshot/rollback system (`snap`, `snaps`, `rollback`) +- Auto-snapshot on dotfile updates +- Mobile detection (`MOBILE=1` for Termius) +- Kanagawa Wave colorscheme (desktop) / habamax (mobile) +- LSP/lint/format for Python, Bash, Lua +- Telescope, oil, lazygit, leap, treesitter --- @@ -56,7 +54,22 @@ docker compose build docker compose run --rm arch-dev ``` -First run seeds the home volume from a baked-in skeleton and creates a `skeleton` tag you can always roll back to. +First run seeds `/home/dev` from the baked-in skeleton and creates a +`skeleton` snapshot you can always roll back to. + +--- + +## Snapshot System + +Your home is a git repo (state in `~/.arch-dev-state/`). Save good states, +roll back when things break. + +```bash +snap node-working "NodeJS env with nvm + pnpm" # save state +snaps # list snapshots +snapd # diff vs last snapshot +rollback node-working # reset to snapshot +``` --- @@ -65,54 +78,30 @@ First run seeds the home volume from a baked-in skeleton and creates a `skeleton | Path | Type | Purpose | |---|---|---| | `/workspace` | bind mount → `./workspace` | Project files, host-visible | -| `/home/dev` | named volume `arch-dev-home` | Stateful user home, survives `--rm` | -| `/etc/skel-arch-dev/` | image layer | Read-only template, used to seed and update | +| `/home/dev` | named volume | Stateful user home | +| `/etc/skel-arch-dev/` | image layer | Read-only template | -**Reset home to factory:** -```bash -docker volume rm arch-dev_arch-dev-home -docker compose run --rm arch-dev -``` - -**Or roll back inside the container:** -```bash -rollback skeleton -``` +Reset home to factory: `docker volume rm _arch-dev-home` --- -## Image Updates +## State Tracking — Two Systems -When you rebuild the image with new dotfiles: +| System | What | Where | +|---|---|---| +| **git on v2 branch** | Dockerfile, dotfiles, build recipe | Gitea repo | +| **`snap` inside container** | Runtime state, installed tools, auth | Docker volume | -1. Container starts, entrypoint compares image dotfiles to home -2. If image is newer, takes an auto-snapshot of current home -3. Updates dotfiles, leaving user data alone (history, project state) -4. You can `rollback` to the auto-snapshot if you don't like the new dotfiles - ---- - -## Known Caveats - -- **AUR/pacman packages** are NOT in snapshots (they live in `/usr/`, not `~`) -- **Docker volume size** grows with snapshots — `_archdev_git gc` periodically -- First `snap` after major changes can take a few seconds (lots to hash) +Both required for full reproducibility — Dockerfile builds the OS, +snapshots restore the user state on top of it. --- ## Mobile (Termius) -`MOBILE=1` activates: -- Minimal starship prompt +Set `MOBILE=1` in Termius host profile env vars to activate: +- Single-line minimal starship prompt - Auto-attach screen on connect -- Bufferline disabled (was showing as purple bar) -- Habamax colorscheme (kanagawa needs truecolor which Termius mangles) - ---- - -## v2 Roadmap - -- nvm + nodejs (snapshot it after install!) -- gemini-cli for AI in the terminal -- copilot.nvim or avante.nvim -- nvim-dap (debugger) +- habamax colorscheme (kanagawa needs truecolor) +- termguicolors disabled in neovim +- Bufferline disabled