v2.1: add imagemagick, chafa, jp2a for ASCII workflow
This commit is contained in:
parent
f61e99a2eb
commit
e382fa1e33
153
CLAUDE.md
Normal file
153
CLAUDE.md
Normal file
@ -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 <name> [msg]` / `snap` — tag current state
|
||||||
|
- `snapshots` / `snaps` — list tags + recent commits
|
||||||
|
- `rollback <name>` / `snapr` — reset to tag (confirms first, auto-snaps)
|
||||||
|
- `diff-state` / `snapd` — what's changed since last commit
|
||||||
|
- `show-snapshot <name>` — inspect a tag
|
||||||
|
- `unsnapshot <name>` — 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 `<Plug>(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.
|
||||||
@ -24,6 +24,7 @@ RUN pacman -S --noconfirm --needed \
|
|||||||
man-db man-pages \
|
man-db man-pages \
|
||||||
jq tree wget \
|
jq tree wget \
|
||||||
rsync \
|
rsync \
|
||||||
|
imagemagick chafa jp2a \
|
||||||
&& pacman -Scc --noconfirm
|
&& pacman -Scc --noconfirm
|
||||||
|
|
||||||
# ── Crown Jewel #2: AUR ───────────────────────────────────────────────────────
|
# ── Crown Jewel #2: AUR ───────────────────────────────────────────────────────
|
||||||
|
|||||||
133
README.md
133
README.md
@ -1,51 +1,49 @@
|
|||||||
# arch-dev v1.7
|
# arch-dev
|
||||||
### Riced Neovim IDE · Arch Linux · Stateful · Mobile-Aware
|
### Riced Neovim IDE · Arch Linux · Stateful · Mobile-Aware
|
||||||
|
|
||||||
> *"Like Gentoo without the compiling."*
|
> *"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
|
| Branch | Purpose |
|
||||||
- **Git-backed snapshot system** — commit good states, roll back when things break
|
|---|---|
|
||||||
- **Auto-snapshot on dotfile updates** — image upgrades preserve your history
|
| `main` | Latest stable |
|
||||||
- **Mobile improvements** — bufferline disabled on mobile, dashboard uses thin-line ASCII
|
| `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
|
### v2.1 — Image & ASCII tooling
|
||||||
# Working state — save it
|
- ImageMagick — image manipulation
|
||||||
snap node-working "NodeJS env with nvm + pnpm"
|
- chafa — modern terminal image rendering (truecolor + sixel)
|
||||||
|
- jp2a — fast JPEG/PNG to ASCII art
|
||||||
|
|
||||||
# List your snapshots
|
Workflow: AI rough sketch → `chafa --symbols ascii` → hand-tweak
|
||||||
snaps
|
|
||||||
|
|
||||||
# See what's changed since last snapshot
|
---
|
||||||
snapd
|
|
||||||
|
|
||||||
# Try something risky, breaks things... no problem
|
## v1.7 — What's there now
|
||||||
snapr node-working
|
|
||||||
|
|
||||||
# Show what's in a snapshot
|
- Stateful `/home/dev` via named Docker volume
|
||||||
show-snapshot node-working
|
- Git-backed snapshot/rollback system (`snap`, `snaps`, `rollback`)
|
||||||
|
- Auto-snapshot on dotfile updates
|
||||||
# Remove a snapshot you don't need
|
- Mobile detection (`MOBILE=1` for Termius)
|
||||||
unsnapshot old-thing
|
- Kanagawa Wave colorscheme (desktop) / habamax (mobile)
|
||||||
```
|
- LSP/lint/format for Python, Bash, Lua
|
||||||
|
- Telescope, oil, lazygit, leap, treesitter
|
||||||
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`)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -56,7 +54,22 @@ docker compose build
|
|||||||
docker compose run --rm arch-dev
|
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 |
|
| Path | Type | Purpose |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| `/workspace` | bind mount → `./workspace` | Project files, host-visible |
|
| `/workspace` | bind mount → `./workspace` | Project files, host-visible |
|
||||||
| `/home/dev` | named volume `arch-dev-home` | Stateful user home, survives `--rm` |
|
| `/home/dev` | named volume | Stateful user home |
|
||||||
| `/etc/skel-arch-dev/` | image layer | Read-only template, used to seed and update |
|
| `/etc/skel-arch-dev/` | image layer | Read-only template |
|
||||||
|
|
||||||
**Reset home to factory:**
|
Reset home to factory: `docker volume rm <project>_arch-dev-home`
|
||||||
```bash
|
|
||||||
docker volume rm arch-dev_arch-dev-home
|
|
||||||
docker compose run --rm arch-dev
|
|
||||||
```
|
|
||||||
|
|
||||||
**Or roll back inside the container:**
|
|
||||||
```bash
|
|
||||||
rollback skeleton
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 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
|
Both required for full reproducibility — Dockerfile builds the OS,
|
||||||
2. If image is newer, takes an auto-snapshot of current home
|
snapshots restore the user state on top of it.
|
||||||
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)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Mobile (Termius)
|
## Mobile (Termius)
|
||||||
|
|
||||||
`MOBILE=1` activates:
|
Set `MOBILE=1` in Termius host profile env vars to activate:
|
||||||
- Minimal starship prompt
|
- Single-line minimal starship prompt
|
||||||
- Auto-attach screen on connect
|
- Auto-attach screen on connect
|
||||||
- Bufferline disabled (was showing as purple bar)
|
- habamax colorscheme (kanagawa needs truecolor)
|
||||||
- Habamax colorscheme (kanagawa needs truecolor which Termius mangles)
|
- termguicolors disabled in neovim
|
||||||
|
- Bufferline disabled
|
||||||
---
|
|
||||||
|
|
||||||
## v2 Roadmap
|
|
||||||
|
|
||||||
- nvm + nodejs (snapshot it after install!)
|
|
||||||
- gemini-cli for AI in the terminal
|
|
||||||
- copilot.nvim or avante.nvim
|
|
||||||
- nvim-dap (debugger)
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user