40 lines
3.1 KiB
Markdown
40 lines
3.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What this repo is
|
|
|
|
Master dotfiles repo for a Hyprland desktop on Arch Linux. It has two halves:
|
|
|
|
- `src/` — a small interactive TypeScript CLI (install/update/remove) that manages packages and dotfiles.
|
|
- `packages/` — the actual dotfiles, laid out as [GNU Stow](https://www.gnu.org/software/stow/) packages (one top-level dir per app, mirroring `$HOME`, e.g. `packages/waybar/.config/waybar/config`).
|
|
|
|
The CLI is the only orchestration layer; it shells out to the real `stow`, `pacman`, and `yay` binaries rather than reimplementing symlinking or package management.
|
|
|
|
## Commands
|
|
|
|
```
|
|
npm install
|
|
npm start install # interactive: choose packages, installs them, backs up conflicting files, symlinks into $HOME
|
|
npm start update # pacman -Syu + yay -Syu, then re-links (stow --restow) any new files
|
|
npm start remove # removes symlinks (stow -D), restores the most recent backup (does NOT uninstall packages)
|
|
npx tsc --noEmit # typecheck (no test suite or lint script exists)
|
|
```
|
|
|
|
There is no build step — `tsx` runs the TypeScript directly.
|
|
|
|
## Architecture
|
|
|
|
- `src/packages.ts` — the package model. Each entry has a `tier` (`required` installs with no prompt; `recommended` is offered via checkbox), an optional `group` for mutually-exclusive alternatives (e.g. `waybar` vs `ags` both have `group: "bar"`, only one gets picked via a select prompt), and an optional `dir` when the Stow directory name differs from the package name (e.g. package `rofi-wayland` → dir `rofi`). `toDirs()` converts chosen package names to their Stow directory names.
|
|
- `src/stow.ts` — all filesystem/process side effects live here: bootstrapping `yay` and oh-my-zsh/zinit if missing, installing packages via `yay`, backing up real (non-symlink) files that would collide with a Stow target into `~/.dotfiles-backup/<timestamp>/`, and wrapping `stow`/`--restow`/`-D` (always invoked with an explicit `-d <PACKAGES_DIR>` so behavior doesn't depend on cwd). Also reads/writes `~/.config/dotfiles/state.json`, which records which package dirs were chosen at install time — `update` and `remove` act on this list rather than re-prompting.
|
|
- `src/install.ts`, `src/update.ts`, `src/remove.ts` — the three subcommands, each a thin sequence of calls into `stow.ts`, using `@clack/prompts` for interactive selection in `install.ts`.
|
|
- `src/cli.ts` — dispatches `install|update|remove` via Node's built-in `node:util.parseArgs`.
|
|
|
|
### Adding a new app
|
|
|
|
Add a directory under `packages/` mirroring its `$HOME` layout (e.g. `packages/foo/.config/foo/config`), then add a matching entry to `src/packages.ts` (`dir` if the Stow directory name differs from the package name, `group` if it's a mutually-exclusive alternative to another package).
|
|
|
|
### Backup/restore
|
|
|
|
Backups are stored under `~/.dotfiles-backup/<timestamp>/`, mirroring the relative path of whatever real file was moved aside before stowing. `remove` restores only the most recent backup automatically; restoring an older one is a manual `cp -a ~/.dotfiles-backup/<timestamp>/. ~/`.
|