notfiles/docs/superpowers/specs/2026-03-31-notfiles-workspace-architecture-design.md

# notfiles Workspace Architecture Design

**Date:** 2026-03-31
**Status:** Approved

## Overview

`notfiles` is a pure-Rust dotfiles manager replacing GNU Stow. This design expands it into a **Cargo workspace** of focused crates that together replace the entire `dotfiles/` shell script ecosystem — including bootstrapping a new machine from scratch.

The primary pain points being solved:

- New machine setup requires too many manual steps before the bootstrap script even runs
- Secrets/1Password setup is fragile — keys aren't available early enough
- Too many shell scripts that are hard to maintain and test
- Nix/Homebrew split is unclear; Rust tools are preferred

---

## Workspace Structure

```
notfiles/                          # Cargo workspace root
├── Cargo.toml                     # [workspace] members
├── notfiles.toml                  # dotfiles symlink config
├── notstrap.toml                  # bootstrap hook/phase config
├── crates/
│   ├── notcore/                   # shared types, config, paths, errors
│   ├── notfiles/                  # symlink engine (stow replacement)
│   ├── notsecrets/                # age key retrieval + sops decrypt
│   ├── nothooks/                  # hook execution engine
│   └── notstrap/                  # new-machine bootstrap orchestrator
└── tests/                         # workspace-level integration tests
```

### Crate Summary

| Crate | Type | Role |
|-------|------|------|
| `notcore` | lib | Shared types, config, paths, errors |
| `notfiles` | lib + bin | Symlink engine (stow replacement) |
| `notsecrets` | lib | Age key retrieval → sops decrypt |
| `nothooks` | lib + bin | Hook execution, phase tracking |
| `notstrap` | bin | Orchestrates everything on a new machine |

---

## Crate Designs

### `notcore` — Shared Foundation

Pure library. No binary. Every other crate depends on it; it depends on nothing in the workspace.

**Contents:**
- `NotfilesError` — unified error enum via `thiserror`
- `Config` — parses `notfiles.toml` + `notstrap.toml`
- `Paths` — `expand_tilde`, `dotfiles_dir()`, standard path resolution
- `HookSpec` — name, script path, phase (`dot` | `setup`)
- `PackageSpec` — name, link method (`symlink` | `copy`), target dir
- `Report` / `Step` — shared types for the end-of-run summary table

**Migration from current code:** `config.rs`, `paths.rs`, `error.rs` move from the current `notfiles/src/` into `notcore`.

---

### `notfiles` — Symlink Engine

Library + binary. The stow replacement. Operates on a dotfiles directory of "packages" (subdirectories) and symlinks their contents into a target (typically `$HOME`).

**Responsibilities:**
- `link` — create symlinks or copies from package dirs to target
- `unlink` — remove symlinks, clean up empty parent dirs
- `status` — diff expected state (config + disk) vs actual state (symlinks + state file)
- `State` — serialize/deserialize `.notfiles-state.toml` (tracks every linked file)
- Conflict detection and `--force` backup handling
- Glob-based ignore matching via `globset`

**Migration from current code:** `linker.rs`, `package.rs`, `ignore.rs`, `status.rs` stay in `notfiles`. Config/paths/error types are imported from `notcore`.

Used as a library by `notstrap` (`notfiles::link()` called directly).

---

### `notsecrets` — Secrets Bootstrap

Library. Retrieves the age private key and decrypts `secrets.sops.env` before anything else runs.

**Age key sources (tried in order):**

1. **Bitwarden CLI** (`bw`) — non-interactive if session is cached; prompts for master password if not
2. **File** — `--key-file <path>` (USB drive, external storage)
3. **Interactive prompt** — user pastes the age key directly

Implemented as a port: `AgeKeySource` trait with three implementations (`BitwardenSource`, `FileSource`, `PromptSource`). `notstrap` iterates sources until one succeeds.

Once the age key is in hand: writes it to `~/.config/sops/age/keys.txt`, then runs `sops --decrypt secrets.sops.env` to produce a live env file. The decrypted env contains all critical credentials: op, bw, github, openai, anthropic, etc.

1Password (`op`) is NOT used at this stage — it's installed later as a hook, after secrets are already available.

---

### `nothooks` — Hook Execution Engine

Library + binary. Replaces `run_hook`, `run_dot_hooks`, `run_setup_hooks` from `bootstrap.sh`.

**Hook phases:**
- `dot` — fast, re-runnable (shell config, git config, AI tool configs)
- `setup` — slow, run-once (package installs, language runtimes, dev tools)

**Responsibilities:**
- Read hook specs from `notstrap.toml` — ordered list with name, script path, phase
- Execute hooks in declared order, capturing stdout/stderr
- Track which `setup` hooks have already run in `.nothooks-state.toml` — skip on re-run unless `--force`
- Feed per-hook pass/skip/fail results into `Report` from `notcore`

**Does NOT handle:** package management (invoked as hooks), secret handling (done before hooks run).

CLI: `nothooks run --phase dot` or `nothooks run --phase setup`

---

### `notstrap` — New Machine Orchestrator

Binary only. The single entry point on a fresh machine.

**Install:**
```bash
cargo install notstrap
notstrap run
```

**Execution order:**

1. Check prerequisites (`op`, `bw`, `sops`, `age` — print exactly what's missing and stop)
2. Run `notsecrets` — retrieve age key → decrypt `secrets.sops.env` → inject into env
3. Clone dotfiles repo if not present (URL from `notstrap.toml`)
4. Run `notfiles link` — stow all packages
5. Run `nothooks run --phase dot` — fast hooks
6. Run `nothooks run --phase setup` — slow hooks (includes `op` install + sign-in)
7. Print `Report` summary table

---

## Day-One Flow

```
cargo install notstrap
notstrap run
  └─ notsecrets
       ├─ try: bw unlock → age key
       ├─ fallback: --key-file <path>
       └─ fallback: interactive prompt
           └─ sops decrypt secrets.sops.env → env injected
  └─ notfiles link (all packages)
  └─ nothooks --phase dot
       └─ shell config, git config, AI tool configs (~seconds)
  └─ nothooks --phase setup
       └─ Homebrew/Nix packages, mise runtimes, dev tools, op install (~minutes)
  └─ Report: ✓ linked 142 files, ✓ 3 dot hooks, ✓ 7 setup hooks
```

---

## Migration Strategy

Migration from `dotfiles/` is gradual — shell scripts die as their Rust equivalents ship:

| Phase | What ships | What it replaces |
|-------|-----------|-----------------|
| 1 | `notfiles` workspace (this design) | GNU Stow |
| 2 | `notsecrets` + `notstrap` skeleton | `setup-secrets.sh`, `install.sh` |
| 3 | `nothooks` | `bootstrap.sh` hook runner |
| 4 | Hook-by-hook Rust rewrites | Individual `setup-*.sh` scripts |
| 5 | `dotfiles/` repo archived | — |

Existing `.rs` scripts (`drift-check.rs`, `redact-audit.rs`, `claude-sessions.rs`, etc.) can migrate into `nothooks` hook scripts or dedicated crates as needed.

---

## Dependencies

| Crate | Key dependencies |
|-------|-----------------|
| `notcore` | `serde`, `toml`, `thiserror`, `dirs`, `anyhow` |
| `notfiles` | `notcore`, `clap`, `globset`, `chrono` |
| `notsecrets` | `notcore`, `clap`, `rpassword`, `which` |
| `nothooks` | `notcore`, `clap`, `serde`, `toml` |
| `notstrap` | `notcore`, `notfiles`, `notsecrets`, `nothooks`, `clap` |

---

## Open Questions

- Should `notstrap` be published to crates.io, or installed from the dotfiles repo directly via `cargo install --path`?
- Should `notsecrets` support a fourth source: a second Bitwarden-compatible backend (Vaultwarden self-hosted)?
- Hook scripts: keep as shell scripts invoked by `nothooks`, or migrate each to a Rust binary over time?