specs - leafscale/repoman

root / docs / superpowers / specs
specs Plain Text 1226 lines 67.1 KB
# repoman v0.1 — Design Spec

**Status:** v0.1 design, locked
**Date:** 2026-04-29
**Implementation language:** reef-lang 0.5.10
**Origin:** [VISION.md](../../../VISION.md) (intent) + bash prototype at `~/.local/bin/repoman` (behavioral spec for `new`/`sync`)
**Outcome:** the contract for the first reef build of repoman.

---

## Reef version target

This spec targets **reef 0.5.10**, which shipped the stdlib additions requested in [`docs/reef-feedback.md`](../../reef-feedback.md) (response in [`docs/reef-feedback-response.md`](../../reef-feedback-response.md)). All four feedback sprints landed in a single 0.5.10 release on 2026-04-29:

- `io.path.expand_home`, `io.path.join` (canonical synonym for `join_path`).
- `test.framework.assert_contains_string`, `assert_ok_int/_str/_bool`, `assert_err_int/_str/_bool`.
- `encoding.toml.toml_parse_status`, `encoding.json.json_parse_status` (truncation-aware parse).
- `io.file.rename`, `io.file.fsync` (atomic-write primitives; parent-directory fsync still pending).
- `sys.flag.flag_parser_from(args)` for sliced argv (subcommand dispatch).
- `core.result_generic` — `Result[T, E]` with `is_ok`, `is_err`, `unwrap_ok`, `unwrap_err`, `unwrap_or`. Construction uses explicit type args: `@Result[int, string].Ok(42)`. Cross-module use unblocked by BUG-037 fix in the same release.
- `encoding.toml.TomlDoc` + `toml_parse_doc` (struct-bundled parse output, replacing parallel-array threading).
- `encoding.toml.TomlBuilder` and `encoding.json.JsonBuilder` (streaming serializers — closes the reader-without-writer asymmetry).

**Deferred to 0.5.11** (does not affect repoman v0.1):
- Cobra-style declarative `subcommand_parser` API. Phase 1 (`flag_parser_from`) is sufficient for repoman's subcommand dispatch — we hand-roll the outer dispatch on `argv[1]`, then feed each subcommand a sliced argv.
- `expand_user("~user/...")`. Current `expand_home` passes `~user/...` through unchanged.

§2 (architecture's CLI parser hedge) and §3.4 (atomic-write fsync hedge) were originally written against 0.5.9 workarounds. They have been retargeted to the 0.5.10 APIs in rev 3.

---

## 1. Scope

v0.1 is "match-then-surpass": ship feature-parity with the bash prototype's two subcommands plus the one v0.1-only differentiator that's cheap to add now and expensive to retrofit (the Incus `project` namespace). Everything else from VISION (the remaining subcommands, REST integration, interactive wizard, JSON output mode) is deferred.

**In scope:**
- `repoman new <name> [--repo <dirname>] [--image <img>]`
- `repoman sync [name] [--no-delete] [--dry-run]`
- `repoman --version` / `repoman --help` / `repoman` (no args → full help)
- Central registry at `~/.config/repoman/repoman.toml`
- Per-project overrides at `~/.config/repoman/repos.d/<name>.toml`
- Incus `project repoman` as the namespace for every container repoman creates

**Out of scope (deferred to v0.2 or later):**
- Subcommands: `setup`, `list`, `shell`, `remove`, `status`, `update`, `config`, `adopt`
- Incus REST-over-unix-socket integration (v0.1 shells out to the `incus` CLI)
- Interactive wizard / line-prompt mode for missing args
- Auto-rollback when a `new` step fails midway
- JSON output mode for automation
- CI / public-forge release artifacts (prebuilt binaries)
- Migration from the bash prototype's containers (which live in Incus's `default` project)
- `repoman` config-by-env-var compatibility (`LOCAL_REPOS`/`NFS_REPOS`)
- Incus profile management (e.g., `repoman profile new dotfiles` interactive create/edit). v0.1 expects users to author profiles directly via `incus profile create/edit` and reference them in `[defaults].profiles`. README documents the recommended `dotfiles` profile pattern (bind-mount `~/.hgrc`/`~/.gitconfig`/etc.) for shared host config.
- `[defaults].seed_files` (copy-at-create semantics). Bind-mount via Incus profile is sufficient for the v0.1 dotfiles use case; revisit if a real copy-on-create need surfaces.

---

## 2. Architecture

Six modules under `src/`, no nesting:

| File | Module | Responsibility | Pure? |
|---|---|---|---|
| `src/main.reef` | (entry) | `proc main()` → `cli.dispatch(sys.args.argv())` and exit. | — |
| `src/cli.reef` | `cli` | Subcommand routing, flag parsing, usage/version output. Returns exit codes. Hand-rolls outer dispatch on `argv[1]`, then feeds each subcommand a sliced argv via `sys.flag.flag_parser_from(args)`. Migrates to the declarative `subcommand_parser` API in 0.5.11+. | mostly |
| `src/config.reef` | `config` | Registry types (`Defaults`, `Project`, `Registry`), per-project override (`Override`), `EffectiveConfig`. Load-or-init from disk (atomic write); merge defaults+override. | yes |
| `src/incus.reef` | `incus` | Thin wrappers over the `incus` CLI via `process_spawn(prog, argv)` — `project_ensure`, `container_exists`, `launch`, `bind_repo`, `set_env`, `restart`. Plus pure `validate_name`. | wrappers thin; `validate_name` pure |
| `src/sync.reef` | `sync` | `ensure_nfs_mounted` (stat → mountpoint → findmnt -t nfs4 chain), pure `build_rsync_args(opts)`, effectful `run(opts)` that spawns rsync and inherits stdio. | arg builder pure |
| `src/path.reef` | `path` | `expand_home`, `join`, `exists`, `is_dir`. Thin wrappers over `io.path` / `io.dir`. | yes |

**Boundaries.** Pure logic (TOML schemas, name validation, rsync arg construction, path expansion, defaults merging) is unit-tested. Effectful wrappers (subprocess invocation, NFS mount checks, file write) are kept narrow so they can be smoke-tested via integration but don't need fakes. `core.result_generic` (`Result[T, string]`) carries errors out of every fallible function; `main` translates `Result.Err` into a stderr message + non-zero exit code. Construction syntax is `@Result[T, string].Ok(value)` / `@Result[T, string].Err(msg)` per 0.5.10 generics.

**Subprocess discipline.** Every external invocation goes through `sys.process.process_spawn(program, argv)` — never `process_spawn_shell`. This is non-negotiable: user-derived names (container, repo, paths) must not pass through a shell's word-splitting or globbing.

**Dependency graph.** `main → cli → {config, incus, sync, path}`. `incus` and `sync` are independent of each other. `config` depends only on `encoding.toml`, `io.file`, `path`. No cycles.

**Concurrency.** v0.1 is fully sequential. No Active Objects, no parallel sync. VISION's parallel-sync-across-N-projects idea is a v0.2 candidate.

---

## 3. Data shapes

### 3.1 Central registry — `~/.config/repoman/repoman.toml`

```toml
[repoman]
schema = 1

[defaults]
repos_root     = "~/repos"
backup_root    = "/nfs/repos"
incus_project  = "repoman"
default_image  = "images:ubuntu/26.04/cloud"
profiles       = ["default", "claude-share"]

[[project]]
name        = "isurus"
repo        = "isurus-project"
image       = "images:ubuntu/26.04/cloud"
profiles    = ["default", "claude-share"]
created     = "2026-04-28T15:00:00Z"
last_sync   = ""           # "" = never synced
backup      = true         # false → sync skips
```

**Fields:**
- `[repoman].schema` — registry schema version. v0.1 writes `1`. Loader rejects any other value with a clear error and a hint to upgrade repoman.
- `[defaults].repos_root` / `backup_root` — `~` expanded by `path.expand_home` at load time.
- `[[project]].repo` — repo dirname relative to `repos_root`. Defaults to `name` if unspecified.
- `[[project]].image` and `[[project]].profiles` — **effective** (post-merge) values used at container-create time, snapshotted for the registry. If override `repos.d/<name>.toml` had `[container].profiles`, those (not defaults) get stored here. Stored explicitly so v0.2 `list`/`status` doesn't need to query Incus to display them.
- `[[project]].created` / `last_sync` — ISO 8601 UTC strings. `""` for never.
- `[[project]].backup` — opt-out flag. Default `true`.

### 3.2 Per-project override — `~/.config/repoman/repos.d/<name>.toml`

User-authored before `repoman new`. Optional. Read by `new` only.

```toml
[container]
image    = "images:debian/12/cloud"
profiles = ["default", "claude-share", "node-dev"]

[[mount]]
source = "~/.npm"          # host path, ~ expanded
path   = "/home/ctusa/.npm" # container path

[env]
NODE_ENV = "development"
```

Filename keys off the **container name** (`<name>`), not the repo dirname. So `repoman new isurus --repo isurus-project` reads `repos.d/isurus.toml`.

### 3.3 Merge semantics (`new` only)

Effective config priority:

| Field | Priority |
|---|---|
| `image` | `--image` flag → `override.container.image` → `defaults.default_image` |
| `profiles` | `override.container.profiles` (replace, not merge) → `defaults.profiles` |
| `mounts` | `[auto repo bind]` ++ `override.[[mount]]` (additive; the auto repo bind is always present) |
| `env` | `override.[env]` (key-by-key; empty if absent) |

Replace semantics for `profiles` is deliberate: VISION's example shows the override containing the full profiles list (including the defaults), and predictable replace beats subtle additive surprises.

### 3.4 Atomic write

Central registry is rewritten atomically on every change:
1. `io.file.writeFile("repoman.toml.tmp", contents)` in the same directory as the target.
2. `io.file.fsync("repoman.toml.tmp")` to push contents to disk before the rename.
3. `io.file.rename("repoman.toml.tmp", "repoman.toml")`.

Parent-directory fsync is not yet exposed (per the 0.5.10 changelog), so a power-loss window for the rename itself remains. Acceptable for a homelab dev tool; revisit when the runtime adds it.

TOML serialization is via `encoding.toml.TomlBuilder` from 0.5.10 — explicit `toml_set_string` / `toml_set_string_array` / `toml_array_append_table` for `[[project]]` entries, then `toml_render` to a string.

The override file is never written by repoman in v0.1. User authors it.

### 3.5 Validation on registry load

- `[repoman].schema == 1` — error otherwise.
- All `[[project]].name` values pass `incus.validate_name`.
- No duplicate `name` across `[[project]]` entries.
- `repos_root` and `backup_root` resolve to non-empty strings after `~` expansion.

Failure → `Result.Err` with a clear message including the offending field. Exit code 3 (environment).

---

## 4. Subcommand flows

### 4.1 `repoman new <name> [--repo <dirname>] [--image <img>]`

1. Parse args. `name` required; bad usage → exit 2.
2. `incus.validate_name(name)` — pure check (alnum + hyphen, ≤63, no leading hyphen). Fail → exit 1.
3. `config.load_or_init()` — read or create the registry with default `[repoman]`/`[defaults]`.
4. Reject if `name` already exists in `[[project]]` → exit 4 with hint.
5. Resolve repo path: `<defaults.repos_root>/<repo>`. Error if directory doesn't exist (matches bash) → exit 3.
6. Read `~/.config/repoman/repos.d/<name>.toml` if present; parse into `Override`.
7. Compute `EffectiveConfig` per the merge table in §3.3.
8. `incus.project_ensure(defaults.incus_project)` — list, create if missing. Idempotent.
9. `incus.container_exists(project, name)` — error if already present → exit 4 with `incus delete --project <p> <name>` hint.
10. `incus launch --project <p> --profile P1 --profile P2 ... <image> <name>` (one `process_spawn`).
11. For each effective mount (always: the auto repo bind at `<repo_path>:<repo_path>`; then any override mounts), `incus config device add --project <p> <name> <devname> disk source=<src> path=<dst>`. Device names: `repo` for the auto bind, `mount-N` (N=1..) for overrides.
12. For each `[env]` entry, `incus config set --project <p> <name> environment.KEY=VALUE`.
13. `incus restart --project <p> <name>` so binds and env take effect.
14. Append a `[[project]]` entry with all snapshot fields; `config.save(reg)` atomically.
15. Print "ready" + a correct shell-in hint using `getuid()` and `$HOME` (not hardcoded `1000`/`/home/ctusa` like bash).

**Rollback policy.** v0.1 does **not** auto-destroy on partial-failure. If launch succeeds but a downstream step fails (device-add, env-set, restart, registry write), surface the error and the exact `incus delete --project <p> <name>` command for manual cleanup. v0.2 candidate: `--rollback-on-error`.

### 4.2 `repoman sync [name] [--no-delete] [--dry-run]`

1. Parse args.
2. `config.load_or_init()`.
3. `sync.ensure_nfs_mounted(defaults.backup_root)` — three calls: `stat <backup_root>` (triggers autofs), `mountpoint -q <backup_root>`, `findmnt -t nfs4 <backup_root>`. Each via `process_spawn`. Any failure → exit 3 with a clear message identifying which step failed.
4. Resolve sync target:
   - **With `name`:** find in registry. Missing → exit 1 with hint. `backup = false` → exit 1 (user explicitly asked, refusing is more honest than silent skip). `src = <repos_root>/<repo>/`, `dst = <backup_root>/<repo>/`.
   - **Without `name`:** `src = <repos_root>/`, `dst = <backup_root>/`. Build excludes from the standard list (see §4.3) plus `<repo>/` for every project where `backup = false`.
5. Pure `sync.build_rsync_args(opts)` produces argv. See §4.3 for the full set.
6. Print one-line tag to stderr: `==> rsync (dry-run) (additive) <src> → <dst>` (tags conditional on flags).
7. `process_spawn("rsync", argv)`. Inherit parent stdout/stderr — user sees rsync's progress live; we don't capture or reformat.
8. If rsync exit 0: update `last_sync` to current ISO 8601 UTC and `config.save(reg)` atomically. "Affected" = the named project (single-project mode), or every project where `backup != false` (whole-tree mode).
9. Exit code = rsync's exit code (passthrough). 0 = success; 23 = partial transfer; 24 = vanished files; etc.

### 4.3 rsync invocation

Base flags: `-aHAX`.

Adaptive info flags:
- Dry-run: `--dry-run --itemize-changes --info=stats2`
- Interactive (TTY on stdout): `--info=stats2,progress2`
- Otherwise (cron / piped): `--info=stats2`

Delete: `--delete` unless `--no-delete`.

Excludes (hardcoded for v0.1 — matches bash prototype):
```
node_modules/
target/
build/
dist/
.next/
__pycache__/
*.pyc
.venv/
venv/
.cache/
.tox/
.pytest_cache/
.mypy_cache/
.ruff_cache/
```

Whole-tree mode appends `--exclude=<repo>/` for every project where `backup = false`.

**`backup = false` semantics:**
- Whole-tree sync: that repo is excluded by rsync; not synced; its `last_sync` is not touched.
- Single-project sync: errors. The user explicitly named it.

---

## 5. CLI surface and error UX

### 5.1 Subcommands

```
repoman new <name> [--repo <dirname>] [--image <img>]
repoman sync [name] [--no-delete] [--dry-run]
repoman --version | -V
repoman --help    | -h | help
repoman                         # no args → print full help
```

### 5.2 Output discipline

- All informational chatter (`==> incus launch ...`, `==> rsync (dry-run) ...`) goes to **stderr**.
- **stdout is reserved** for future machine-readable output. v0.1 produces no stdout (matches bash prototype, keeps cron logs clean).
- Errors prefixed `repoman: error: <message>` to stderr. Append a `hint:` line where a clear next step exists.

### 5.3 Exit codes

| Code | Meaning |
|---|---|
| `0` | success |
| `1` | generic / unhandled error |
| `2` | bad usage (unknown subcommand, missing required arg, bad flag) |
| `3` | environment problem (NFS unreachable, repo dir missing, registry corrupt) |
| `4` | state conflict (container already exists, name already in registry) |
| (rsync codes) | for `sync`: rsync's own exit code passes through when rsync itself fails. Pre-rsync errors use 1–4. |

The rsync passthrough is deliberate: cron consumers can distinguish "couldn't even start" (3/4) from "rsync hit a problem" (rsync's own codes).

### 5.4 Error UX matrix

| Class | Example | Code | What the user sees |
|---|---|---|---|
| Bad usage | `repoman new` | 2 | error msg + short usage hint |
| Validation | invalid container name | 1 | error msg + offending value |
| State conflict | name already in registry | 4 | error msg + cleanup hint |
| Environment | NFS not mounted | 3 | "backup_root /nfs/repos is not mounted (autofs/server unreachable)" |
| Subprocess (incus) | `incus launch` failed | 1 | our error msg + incus's stderr passed through |
| Subprocess (rsync) | rsync mid-transfer error | rsync's | rsync's own stderr (we don't capture) |

### 5.5 No interactive mode in v0.1

Missing required args produce a usage error, not a prompt. Wizard mode is v0.2.

---

## 6. Testing strategy

### 6.1 Unit-tested (pure logic) — full coverage expected

| Module | What's tested |
|---|---|
| `path` | `expand_home` (`~/`, `~`, no-op cases), `join` (trailing-slash handling) |
| `incus` | `validate_name` — valid, leading-hyphen, too-long, dot/underscore, empty, exactly-63-char boundary |
| `config` | TOML round-trip (parse → serialize → reparse equals original); schema rejection (unknown `schema`); `load_or_init` against a temp `XDG_CONFIG_HOME`; `merge_with_defaults` for image/profiles/mounts/env priority cases; `add_project` rejects duplicates; `update_last_sync` on known/unknown name |
| `sync` | `build_rsync_args` covers every branch: dry-run on/off, delete on/off, TTY/non-TTY info flags, `backup=false` exclude generation, single-project vs whole-tree, every standard exclude present |

### 6.2 Smoke-tested (effectful) — manual, not automated

- `incus.project_ensure`, `launch`, `bind_repo`, `restart` — need a real Incus daemon.
- `sync.ensure_nfs_mounted`, `sync.run` — need a real NFS mount and rsync.

Smoke test recipe (in README):
```bash
# In an existing repo dir under ~/repos:
repoman new test-foo
repoman sync test-foo --dry-run
incus delete --project repoman test-foo
```

Three commands, ~30 seconds, catches integration regressions before each release tag.

### 6.3 Test runner

Reef idiom: `reefc run tests/test_<module>.reef` per file, each a standalone program using `test.framework`'s `TestRunner`. Documented loop in README:
```bash
for t in tests/test_*.reef; do
    echo "== $t =="
    reefc run "$t" || exit 1
done
```

### 6.4 Not tested in v0.1

- `main.reef` — 5-line dispatcher, exercised by every invocation in dev.
- CLI flag-parsing fine grain — exercised by manual usage during dogfooding; revisit in v0.2.
- Exact rsync exit-code passthrough — trusts rsync.

### 6.5 No CI in v0.1

Public-forge + CI is post-v0.1 work. Bar for v0.1: the test loop runs cleanly locally.

---

## 7. Build, install, distribution

### 7.1 `reef.toml` manifest

```toml
[package]
name        = "repoman"
version     = "0.1.0"
author      = "Chris Tusa <christusa@gmail.com>"
description = "Per-project Incus containers + opinionated NFS/ZFS backup"
license     = "MIT"           # placeholder — open product question
url         = ""              # forge TBD

[build]
entry        = "src/main.reef"
output       = "repoman"
output_dir   = "build"
source_dirs  = ["src"]

[docs]
output           = "docs/api"
include_private  = false
```

### 7.2 Repo layout

```
~/repos/repoman/
├── reef.toml
├── Makefile             # 10-line install/uninstall wrapper for packagers
├── README.md            # quickstart + test loop + smoke-test recipe + recommended `dotfiles` Incus profile pattern
├── VISION.md            # design intent (stays at root)
├── .hgignore            # build/, *.o, etc.
├── docs/
│   ├── superpowers/specs/2026-04-29-repoman-v0.1-design.md  # this file
│   └── api/             # generated by `reefc doc`
├── src/
│   ├── main.reef
│   ├── cli.reef
│   ├── config.reef
│   ├── incus.reef
│   ├── sync.reef
│   └── path.reef
├── tests/
│   ├── test_path.reef
│   ├── test_config.reef
│   ├── test_incus.reef
│   └── test_sync.reef
└── build/               # generated; hg-ignored
```

### 7.3 Build / clean / docs

Reef-native:
- `reefc build` → `build/repoman`
- `reefc clean`
- `reefc doc` → `docs/api/`

### 7.4 Tests

Documented shell loop in README (§6.3); no wrapper.

### 7.5 Install

10-line `Makefile`, install/uninstall only (packagers expect `DESTDIR`/`PREFIX`):

```make
PREFIX ?= /usr/local
DESTDIR ?=

build/repoman:
	reefc build

install: build/repoman
	install -d $(DESTDIR)$(PREFIX)/bin
	install -m 755 build/repoman $(DESTDIR)$(PREFIX)/bin/repoman

uninstall:
	rm -f $(DESTDIR)$(PREFIX)/bin/repoman

.PHONY: install uninstall
```

`make install PREFIX=$HOME/.local` and `sudo make install` both work; `DESTDIR` honored for fakeroot staging.

### 7.6 Single-binary distribution

Reef compiles to C → native. `build/repoman` statically links `libreef_runtime.a`. v0.1 doesn't use TLS (no REST yet) → `libreef_tls.a` not pulled in. Runtime deps: libc + the external `incus`, `rsync`, `findmnt`, `mountpoint`, `stat` binaries.

### 7.7 Release artifacts (post-v0.1)

Source tarball minimum; prebuilt binaries per platform once forge is chosen. Out of scope for v0.1.

### 7.8 v0.1 verification checklist

1. `reefc build` succeeds clean.
2. The test loop passes for every file in `tests/`.
3. `make install PREFIX=$HOME/.local` (or `sudo make install`) puts `repoman` on PATH.
4. Smoke test: `repoman new test-foo` (against an existing test repo) → `repoman sync test-foo --dry-run` → manual `incus delete --project repoman test-foo`. All exit 0.
5. `repoman --version` prints `0.1.0`.

---

## 8. Open product questions (do not block v0.1 dev)

1. **License.** MIT placeholder in `reef.toml`. Final choice (MIT vs Apache-2.0) before public release.
2. **Forge.** GitHub / Codeberg / self-hosted — affects release artifact pipeline.
3. **Env-var compatibility.** Bash prototype reads `LOCAL_REPOS` / `NFS_REPOS`. Reef v0.1 does not — TOML registry is canonical. Decide before the bash version is retired whether to honor `REPOMAN_REPOS_ROOT` / `REPOMAN_BACKUP_ROOT` as overrides.
4. **Logging / observability.** v0.1 = stderr only. JSON-lines mode is a v0.2 candidate.

---

## 9. Implementation pinned at scaffold-time (not now)

These are decisions deliberately deferred to the moment the code lands, because a 10-minute look at the actual reef API resolves them better than abstract debate:

1. **CLI parser.** Hand-roll an `argv[1]` switch in `cli.reef`, then call `sys.flag.flag_parser_from(argv[2..])` per subcommand. The surface to the rest of the code is `cli.dispatch(argv: [string]): int`. Migrate to `subcommand_parser` when 0.5.11 ships it.
2. **`incus config show` output parsing.** Anywhere v0.1 needs to query Incus state (e.g., `container_exists`), prefer `incus list --format csv` or `--format json` over text scraping. Lock the format choice when implementing each call.

---

## 10. References

- [VISION.md](../../../VISION.md) — design intent, audience, differentiators, open product questions.
- `~/.local/bin/repoman` — bash prototype (behavioral spec for `new` ≈ `create` and `sync`).
- `~/reef-lang-0.5.10-source/docs/language/reference/031_PROJECT_STRUCTURE.md` — reef project conventions (`reefc init`, `reef.toml`, module-to-file mapping).
- `~/reef-lang-0.5.10-source/reef-stdlib/sys/process.reef` — `process_spawn` / `process_exec` / wait/kill API used throughout.
- `~/reef-lang-0.5.10-source/reef-stdlib/encoding/toml.reef` — TOML codec for the registry.
# repoman v0.3 — Setup wizard + LLM stack integration

## Scope reduction (2026-05-08)

The `--hermes`/`--no-hermes`/`--purge-hermes` flag-based provisioning described in
this spec was **removed during smoke testing** and will not ship in v0.3.

Root cause: the bind-mount-the-host-runtime architecture does not survive Python venv
portability constraints. Hermes' venv pins to a uv-vendored host-only path; bind-
mounting it into a container where that path doesn't exist fails at import time. Uid
mapping for the bind also does not generalize cleanly. Copying the venv breaks shebang
paths.

v0.4 will revisit per-container hermes provisioning via pre-built incus images that
embed a self-contained hermes install rather than sharing the host runtime.

**v0.3 still ships:** `repoman setup` wizard, `llm-share` profile (ollama client
wiring), schema-2 migration, and the `hermes` module helpers as a library for v0.4.

---

**Status:** v0.3 design, under review
**Date:** 2026-05-06
**Implementation language:** reef-lang 0.5.20 (no new stdlib requirements vs v0.2)
**Origin:** [VISION.md §4 (`repoman setup`)](../../../VISION.md), [v0.1 spec](2026-04-29-repoman-v0.1-design.md), conversation 2026-05-06 with hermes Docker docs at `https://hermes-agent.nousresearch.com/docs/user-guide/docker`
**Outcome:** the contract for v0.3 — the first version of repoman that productizes the host-side bootstrap and bundles local-LLM tooling.

---

## 0. What's new vs v0.2

v0.2 shipped `new`/`sync`/`list`/`status`/`remove`/`shell`. It assumes the host is already prepared (Incus project exists, `claude-share` profile authored, ZFS/NFS available). v0.3 closes that gap by introducing the host-bootstrap subcommand and adds first-class support for local LLM tooling (ollama + hermes) since that's the most common reason a fresh host needs more than just `claude-share`.

Two threads, one release:

1. **`repoman setup`** — idempotent host bootstrap. Replaces the README's manual incus-project-create / profile-edit walkthrough with a guided wizard.
2. **LLM stack integration** — `llm-share` profile, ollama client wiring, per-container hermes data dirs with selective seeding.

The two are coupled because the wizard is the natural place to *offer* LLM-stack setup as an option, and the per-container hermes seeding adds new behavior to `repoman new`.

---

## 1. Scope

**In scope:**
- `repoman setup` — interactive + flag-driven (`--non-interactive`, `--with-llm`, `--without-llm`).
- `llm-share` Incus profile, repoman-managed (created/refreshed by `setup`).
- `repoman new --hermes` — opt-in flag that provisions a per-container hermes data dir.
- `repoman new --no-hermes` (and `--llm/--no-llm` umbrella) for explicit opt-out when defaults change.
- Selective hermes seeding from host's `~/.hermes/` into `~/.local/share/repoman/hermes/<name>/`.
- `repoman remove --purge-hermes` — delete the per-container hermes data dir (default: leave it for safety).
- Host LAN-IP detection for `OLLAMA_HOST` (read once at `setup`, written into profile).
- `[defaults].llm = { enabled, hermes_default, ollama_url, hermes_seed }` block in `repoman.toml`.

**Out of scope (deferred to v0.4 or later):**
- Adopting an existing host hermes install whose `~/.hermes` should *be* one of the project dirs (no migration tool yet — user can `mv` manually).
- Re-keying / rotating `.env` API keys across N seeded containers.
- Bind-mounting `/opt/ollama/imports` into containers for in-container `ollama create`. Will be added if real demand surfaces; for v0.3, model imports stay a host operation.
- `claude-share` lifecycle. v0.3 *checks* its existence in `setup` and tells the user how to create it if missing, but does not author or edit it. (Same boundary as v0.2.)
- Hermes server-side gateway (port 8642) exposure to the LAN as a shared service. The hermes docs explicitly reject the daemon model; we don't fight it.
- YAML rewriting of seeded `config.yaml`. v0.3 issues a warning if `localhost:11434` is detected in the seed source and asks the user to fix once on the host; we do not parse YAML.

---

## 2. Architecture additions

Two new modules, plus targeted edits to `cli.reef`, `config.reef`, `incus.reef`:

| File | Module | Responsibility | Pure? |
|---|---|---|---|
| `src/setup.reef` | `setup` | The wizard: detect state (incus project, profiles, ollama, hermes binary, host LAN IP), print summary, prompt yes/no per stage, apply changes. Composes `incus.*` and `hermes.*`. | wrappers thin |
| `src/hermes.reef` | `hermes` | Per-container data-dir management: `seed_data_dir(name, source, dest, seed_list)`, `purge_data_dir(dest)`. Pure helpers `default_seed_list()` (returns the allow-list), `state_dir_for(name)` (resolves `~/.local/share/repoman/hermes/<name>/`). | helpers pure; copy effectful |

Edits:

- `cli.reef` — add `cmd_setup` dispatch, extend `cmd_new` to honor `--hermes` / `--no-hermes`, extend `cmd_remove` to honor `--purge-hermes`.
- `config.reef` — add `[defaults].llm` substructure, schema bump to `2`, migration path for `schema = 1` registries.
- `incus.reef` — add `profile_exists(name, project)`, `profile_create_or_edit(name, project, yaml)`, `container_add_disk_device(name, device, source, path, opts)`. The disk-device add is needed because `hermes-state` is a *per-container* device, not a profile-level one.

**Dependency graph addition:** `cli → setup → {incus, hermes, config, path}`. `hermes → {path, io.file, io.dir}`. No cycles.

**Non-goal: a new abstraction over Incus profiles.** `setup` constructs `llm-share` from a string-template embedded in the binary — we don't build a profile-modeling layer in reef just yet.

---

## 3. The `llm-share` profile

Created and maintained by `repoman setup`, in the `repoman` Incus project:

```yaml
name: llm-share
description: |
  Local LLM client tools (ollama client + hermes runtime) and host-daemon wiring.
  Created by repoman setup; do not hand-edit (changes will be overwritten).
config:
  environment.OLLAMA_HOST: "http://<HOST_LAN_IP>:11434"
devices:
  ollama-bin:
    type: disk
    source: /usr/local/bin/ollama
    path: /usr/local/bin/ollama
    readonly: "true"
  ollama-state:
    type: disk
    source: /home/<USER>/.ollama
    path: /home/<USER>/.ollama
    shift: "true"
```

`<HOST_LAN_IP>` is the address bound to `br0` on the host, resolved at `setup` time by parsing `ip -4 addr show br0`. `<USER>` is the invoking user. Both are baked into the YAML at write time — `repoman setup` is the single source of truth.

**Notably absent:** any hermes bind-mount. Hermes data is per-container (see §4).

**Refresh policy.** Re-running `repoman setup` rewrites `llm-share` from template if and only if the on-disk content differs. `setup` tells the user what it changed and why.

---

## 4. Per-container hermes data dirs

Host hermes' `~/.hermes/` is left untouched. For each container that opts into hermes, repoman provisions:

- A host directory at `~/.local/share/repoman/hermes/<container-name>/`, owned by the invoking user.
- Selective seed from `~/.hermes/` into that directory (see §4.2).
- An Incus disk device on the container itself (not a profile) bind-mounting that host dir to `/home/<USER>/.hermes` inside.

The hermes binary at `~/.local/bin/hermes` is reachable inside the container via the existing `claude-share` profile's bind on `~/.local/bin/`. (We **verify** this assumption in §6.1; if `claude-share` doesn't share `~/.local/bin`, the wizard tells the user to add it.)

### 4.1 Why per-container, not shared

Per the [hermes Docker guide](https://hermes-agent.nousresearch.com/docs/user-guide/docker):

> Never run two Hermes gateway containers against the same data directory simultaneously — session files and memory stores are not designed for concurrent write access.

`state.db` is SQLite + WAL. Sharing the data dir between host and N containers risks corruption. Per-container dirs eliminate the risk entirely and align with the hermes team's recommended pattern (one data dir per profile/container).

### 4.2 Seed list

Default `[defaults].llm.hermes_seed`:

```toml
hermes_seed = [
  ".env",                 # API keys
  "config.yaml",          # model defaults, daemon URL
  "SOUL.md",              # persona
  "skills/",              # user-authored skills (recursive)
  "hooks/",               # user hooks (recursive)
  "hermes-agent/",        # vendored runtime — symlink (see §4.3)
  "node/",                # vendored node — symlink
  "bin/",                 # extra binaries — symlink
]
```

**Not seeded** (per-instance state, must be fresh): `sessions/`, `memories/`, `logs/`, `state.db`, `state.db-shm`, `state.db-wal`, `audio_cache/`, `image_cache/`, `sandboxes/`, `cron/`, `pairing/`, `models_dev_cache.json`, `ollama_cloud_models_cache.json`, `context_length_cache.yaml`, `.skills_prompt_snapshot.json`, `.update_check`, `.hermes_history`, `auth.lock`.

The seed list is in `[defaults].llm.hermes_seed` so users can adjust it without rebuilding.

### 4.3 Symlink vs copy for runtime dirs

`hermes-agent/`, `node/`, `bin/` are *runtime*, not user data. By default we **symlink** them from the host's `~/.hermes/` (so a `hermes` upgrade on the host applies to every container with no rebuild), and **copy** the credential/config files. A future `--hermes-isolate-runtime` flag can flip everything to copy for users who want hermes versions to diverge per container.

Symlinks must point at the host path *as visible from inside the container* — i.e., the symlink target must already be reachable through some other bind. Since `~/` is bind-mounted in or mappable, this works as long as the user paths align. **Open question O-3 (§9)** owns the cross-mount-namespace symlink correctness check.

### 4.4 Storage location: why `~/.local/share/repoman/hermes/<name>/`

Considered: `~/.hermes-<name>/` (parallel to `~/.hermes`).

Chose `~/.local/share/repoman/hermes/<name>/` because:
- All repoman-owned per-project state ends up under one tree (`~/.local/share/repoman/`), which matters for backups and for users who want to know "what does repoman own?"
- `~/.hermes-*` pollutes `$HOME` and risks collision with hypothetical future hermes profile features.
- XDG Base Directory convention.

---

## 5. Subcommand flows

### 5.1 `repoman setup [--non-interactive] [--with-llm | --without-llm]`

Stages, run sequentially. Each stage prints what it found, what it'd change, and (interactive mode) waits for `[Y/n]`. `--non-interactive` accepts every default; `--with-llm`/`--without-llm` non-interactively pin the LLM stage.

1. **Detect environment.** incus reachable, current user, host LAN IP via `br0`, ollama binary, hermes binary, `~/.hermes/` presence, ZFS/NFS roots from registry defaults.
2. **Incus project `repoman`.** Create if missing. (No-op if v0.1 already created it.)
3. **`claude-share` profile.** Verify it exists in the `repoman` project and bind-mounts `~/.local/bin/`. If missing or doesn't bind that path, print the recommended `incus profile edit` snippet and exit non-zero with a clear message — we do not author `claude-share`.
4. **LLM stack (gated on `--with-llm` or interactive yes).**
   1. Verify ollama daemon is reachable on `<host-lan-ip>:11434`. If only on loopback, print the systemd-override snippet to make it LAN-listen and exit non-zero.
   2. Write/refresh the `llm-share` profile in the `repoman` project from template (§3).
   3. Verify hermes binary at `~/.local/bin/hermes` and host data dir at `~/.hermes/`. If absent, print install pointer (link to hermes user guide) and skip per-container hermes seeding default.
5. **Registry defaults.** Write `[defaults].profiles = ["default", "claude-share", "llm-share"]` if user said yes to LLM stack; write `[defaults].llm.{enabled = true, hermes_default = false, ollama_url, hermes_seed = [...]}` block. Schema bumps to `2`.
6. **Summary.** Print `setup complete` summary with three follow-on hints: `repoman new <name>`, `repoman new <name> --hermes`, `repoman list`.

Exit codes: `0` success, `2` bad usage, `3` environment (incus unreachable, ollama not LAN-bound, br0 missing), `4` user said no to a required stage in non-interactive mode.

**Idempotency:** every stage is rerunnable. Re-running `setup` after a hermes upgrade refreshes the `llm-share` profile if its content changed and is otherwise a no-op.

### 5.2 `repoman new <name> [...] [--hermes | --no-hermes]`

Existing v0.2 flow plus:

- After the container launch, **if** `--hermes` (explicit) or `[defaults].llm.hermes_default = true` and not `--no-hermes`:
  1. Compute `dest = ~/.local/share/repoman/hermes/<name>/`.
  2. Refuse if `dest` already exists and is non-empty (exit 4 with hint to `repoman remove --purge-hermes <name>` first).
  3. Run the seed (§4.2): copy the credential/config files, symlink the runtime dirs.
  4. `incus.container_add_disk_device(<name>, "hermes-state", source=dest, path=/home/<USER>/.hermes, shift=true)`.
  5. Restart the container so the device takes effect.
- The registry's `[[project]]` entry gains a `hermes = true|false` field so `list`/`status` can show it.

If the LLM stack wasn't enabled at `setup` time, `--hermes` errors out with a hint to `repoman setup --with-llm`.

### 5.3 `repoman remove <name> [--purge-hermes]`

Existing v0.2 flow plus:

- Container removal proceeds as today.
- If the project had `hermes = true`, the per-container data dir is **left in place by default**. The user's reauthorized `.env` and skills survive the container teardown.
- `--purge-hermes` (or `--purge` umbrella, see open question O-1) deletes `~/.local/share/repoman/hermes/<name>/`. Logged loudly because this destroys session/memory state.

### 5.4 `repoman status <name>` / `repoman list`

Show `hermes: yes/no` per project. No new flags.

---

## 6. Data shapes

### 6.1 Registry schema bump (1 → 2)

```toml
[repoman]
schema = 2

[defaults]
repos_root     = "~/repos"
backup_root    = "/nfs/repos"
incus_project  = "repoman"
default_image  = "images:ubuntu/26.04/cloud"
profiles       = ["default", "claude-share", "llm-share"]   # llm-share added if user opted in

[defaults.llm]
enabled        = true
hermes_default = false                                       # false → opt-in via --hermes
ollama_url     = "http://192.168.168.42:11434"               # LAN IP captured at setup
hermes_seed    = [
  ".env", "config.yaml", "SOUL.md",
  "skills/", "hooks/",
  "hermes-agent/", "node/", "bin/",
]

[[project]]
name        = "isurus"
repo        = "isurus-project"
image       = "images:ubuntu/26.04/cloud"
profiles    = ["default", "claude-share", "llm-share"]
created     = "2026-04-28T15:00:00Z"
last_sync   = ""
backup      = true
hermes      = true                                           # NEW; defaults false
```

**Migration from schema 1:** `config.load_or_init` recognizes `schema = 1`, prints a one-line note, populates `[defaults].llm` with `enabled = false` (i.e., user must opt in via `setup`), sets `hermes = false` on every existing `[[project]]`, writes back as `schema = 2`. Idempotent. No data loss.

### 6.2 Per-project override addition

Override files (`~/.config/repoman/repos.d/<name>.toml`) gain an optional field:

```toml
[hermes]
enabled = true   # equivalent to passing --hermes; flag wins if both specified
```

Unknown to v0.2; harmless to v0.2 since override parser ignores unknown sections.

### 6.3 Profile YAML template

Embedded as a `string` constant in `setup.reef`:

```reef
let LLM_SHARE_TEMPLATE: string =
  "name: llm-share\n" ++
  "description: |\n" ++
  "  Local LLM client tools (ollama client + hermes runtime) and host-daemon wiring.\n" ++
  "  Created by repoman setup; do not hand-edit (changes will be overwritten).\n" ++
  "config:\n" ++
  "  environment.OLLAMA_HOST: \"http://{HOST_LAN_IP}:11434\"\n" ++
  "devices:\n" ++
  "  ollama-bin:\n" ++
  "    type: disk\n" ++
  "    source: /usr/local/bin/ollama\n" ++
  "    path: /usr/local/bin/ollama\n" ++
  "    readonly: \"true\"\n" ++
  "  ollama-state:\n" ++
  "    type: disk\n" ++
  "    source: /home/{USER}/.ollama\n" ++
  "    path: /home/{USER}/.ollama\n" ++
  "    shift: \"true\"\n"
```

Substitutions are literal `{HOST_LAN_IP}` / `{USER}` replacement — no template engine. Validated with a roundtrip test (substitution → YAML parse via the bundled toolchain → assert structure).

---

## 7. Testing

Mirrors the v0.1 boundary: pure logic gets unit tests; effectful wrappers get smoke-tested via integration. Specifically:

**Pure tests** (run on every build):
- `hermes.default_seed_list()` returns the documented allow-list.
- `hermes.state_dir_for("foo")` resolves to `<expand_home("~")>/.local/share/repoman/hermes/foo/`.
- Profile template substitution: given known `HOST_LAN_IP`/`USER`, the rendered YAML matches a golden string.
- Schema migration: load `schema = 1` toml, get back `schema = 2` toml with expected defaults populated and existing `[[project]]` entries unchanged except for `hermes = false`.
- Seed-list partition: given the documented hermes dir contents (test fixture), the seeded vs not-seeded sets match §4.2.
- `setup` stage planner: given a fixture environment description (profile present, ollama on LAN, hermes installed), the planner returns the expected list of "would change" actions and "no-op" actions.

**Smoke tests** (require an Incus host, gated on `REPOMAN_SMOKE=1`):
- `repoman setup --non-interactive --with-llm` on a fresh-ish host produces a working baseline.
- `repoman new foo --hermes` then `incus exec foo -- ls /home/$USER/.hermes` shows the seeded layout, and `incus exec foo -- hermes --version` runs.
- `repoman remove foo` leaves the data dir; `repoman remove foo --purge-hermes` removes it.
- Symlink correctness: from inside the container, `readlink ~/.hermes/hermes-agent` resolves to a real path (no broken link).

---

## 8. Risks / mitigations

| Risk | Mitigation |
|---|---|
| Symlinks for runtime dirs break across mount namespaces. | Smoke test 4 above. If broken, fall back to copy for runtime dirs and surface as O-3. |
| Host LAN IP changes (DHCP renewal). | `setup --refresh` re-detects and rewrites `llm-share`. Documented as the recovery step in `repoman status` when ollama health-check fails. |
| Hermes upgrades change the on-disk layout (`hermes-agent/` schema, etc.). | Symlinking the runtime dirs means upgrades flow through automatically. Seed list is config (`[defaults].llm.hermes_seed`) so users can adjust without recompiling. |
| `.env` shared across N containers means a leaked container key is the user's main key. | Same trust model as `claude-share`. Documented in README. Future v0.4 work on rotation is explicitly out of scope here. |
| User has hermes installed in a non-default location (not `~/.hermes/`). | `setup` reads `HERMES_HOME`-equivalent if set; otherwise hardcoded default. Open question O-2. |
| `setup` partial-fails midway (e.g., wrote `llm-share` but couldn't restart a container). | Each stage is independently idempotent. `setup` is safe to rerun. No transactional rollback in v0.3 — same posture as v0.1's container-create. |

---

## 9. Open questions

- **O-1: `--purge-hermes` vs `--purge`.** Should `repoman remove` have a single `--purge` flag that removes both the hermes data dir and any future per-container repoman state, or stay tool-specific (`--purge-hermes`, `--purge-claude`, …)? Defaulting to `--purge-hermes` for v0.3.
- **O-2: Hermes home env var.** Does the hermes CLI honor a `HERMES_HOME` (or similar) env var to redirect from `~/.hermes/`? If yes, the per-container path could be set via env rather than bind-mount-overlay. Needs probe.
- **O-3: Symlink correctness across the bind boundary.** Validate empirically that `~/.local/share/repoman/hermes/<name>/hermes-agent → /home/<USER>/.hermes/hermes-agent` resolves correctly inside the container when only the per-container dir is bind-mounted. If not, fall back to copy and document.
- **O-4: `claude-share` baseline check.** v0.3 currently *checks* that `claude-share` bind-mounts `~/.local/bin/`. If that's a fragile assumption (the user may name their profile differently), should `setup` accept a `--claude-share-profile=<name>` override?
- **O-5: Authoring `claude-share` itself.** Out of scope for v0.3 (§1), but eventually repoman should manage `claude-share` the same way it manages `llm-share`. v0.4 candidate.
- **O-6: Multi-host repoman.** If a user runs repoman on two hosts and their LAN IPs differ, the registry's `ollama_url` is host-specific. v0.3 treats `repoman.toml` as host-local; document.

---

## 10. Build sequence

Suggested order so each step produces a working binary:

1. **Schema bump.** `config.reef` adds `[defaults].llm` parsing + schema 1→2 migration. Tests pass; v0.2 behavior unchanged.
2. **`incus.profile_*` and `container_add_disk_device` wrappers.** Pure plumbing; no caller yet.
3. **`hermes.reef` module.** `default_seed_list`, `state_dir_for`, `seed_data_dir`, `purge_data_dir`. Unit-tested.
4. **`setup.reef` module.** Detection + planner + applier. The interactive prompt scaffolding is `io.console`-based; matches the wizard pattern named in VISION.
5. **`cli.cmd_setup`** — wire it up.
6. **`cmd_new` extensions** — `--hermes`/`--no-hermes`, registry write of `hermes` field, post-launch seed + device-add + restart.
7. **`cmd_remove` extensions** — `--purge-hermes`.
8. **`list`/`status` display** — show `hermes: yes/no`.
9. **README + VISION updates** — document `setup`, document `--hermes`, link to hermes Docker docs as the source for the per-container-data-dir decision.
10. **Smoke run on a fresh host** — fold findings back as bug fixes, then tag v0.3.0.
# repoman v0.4 — Profile library + scope trim

**Status:** v0.4 design, under review
**Date:** 2026-05-08
**Implementation language:** reef-lang 0.5.20 (no new stdlib requirements vs v0.3)
**Origin:** brainstorm 2026-05-08 — re-anchoring on repoman's actual mission after v0.3 LLM-stack work overshot scope. Builds on [v0.3 spec](2026-05-06-repoman-v0.3-llm-and-setup.md) (which was scope-reduced before shipping; see addendum at top of that file).
**Outcome:** the contract for v0.4 — repoman becomes a profile-library-driven container provisioner, with the v0.3 LLM-specific surface either generalized into the profile system or removed.

---

## 0. Mission re-anchor

Repoman's mission is narrowly:
1. Provision per-project Incus containers that bind-mount the user's git/hg repos (`cmd_new`)
2. Backup `~/repos/` to NFS via rsync (`cmd_sync`)
3. Manage the Incus profiles that share host-side resources (configs, agents, bind-mountable runtimes) into containers
4. Quality-of-life subcommands over the above (`list`, `status`, `remove`, `shell`, `setup`)

**What repoman is NOT:** a host-configuration tool. It does not install or configure host services (ollama, hermes runtime, kernel modules). It does not build or maintain container images. It does not run arbitrary install scripts on the user's behalf.

**Where v0.3 drifted:** `setup --with-llm` checks whether the host's ollama daemon listens on the LAN IP and tells the user how to configure it if not. This was halfway across the host-config line. v0.4 pulls back to the line.

**The unifying insight from this brainstorm:** `claude-share` (user-managed since v0.1) and `llm-share` (repoman-managed since v0.3) are the same kind of thing — incus profiles that bind something host-side into containers. The split was incidental, not principled. v0.4 unifies them under a single profile library.

---

## 1. Scope

**In scope (additions):**
- Profile library layout: vendor profiles at `/usr/local/share/repoman/profiles/`, user profiles at `~/.config/repoman/profiles.d/`, user shadows vendor.
- `repoman profile` subcommand family: `list`, `install`, `diff`, `remove`, `show`.
- Templated YAML profile files. Substitution syntax: `${VAR}` (shell-style). Variables: `${HOST_LAN_IP}`, `${USER}`, `${HOME}`.
- `[host].lan_ip` field in the registry, populated by `repoman setup`'s detection.
- Registry schema 2 → schema 3 migration (drops `[defaults].llm` entirely, extracts `lan_ip` from the old `ollama_url` if present).
- Three vendor profiles ship in v0.4: `claude-share.yml`, `llm-share.yml`, `dotfiles.yml`.
- Pre-launch validation in `repoman new`: error early with actionable hint if a referenced profile isn't installed in incus.

**In scope (trims/removals):**
- `repoman setup --with-llm` and `--without-llm` flags — removed. Setup no longer touches profiles.
- `setup`'s ollama LAN-listening check — removed. Reading host LAN IP from `ip -4 addr show br0` stays (read-only host introspection, not configuration).
- `[defaults].llm` registry block (enabled, hermes_default, ollama_url, hermes_seed) — removed entirely.
- The string-template-embedded-in-binary approach for `llm-share` in `setup.reef` — removed. `llm-share` becomes a vendor profile YAML file.
- `setup`'s `apply_stage` for `llm_share_profile` and `registry_defaults` — those stages move to `repoman profile install` and registry init respectively.

**Out of scope (deferred or rejected):**
- Image management (`repoman image build/refresh/etc.`) — rejected during brainstorm. Maintenance burden too high for a homelab tool with low container churn. v0.5+ may revisit if real demand surfaces.
- `[install]` block in override files — rejected during brainstorm. Per-project install commands are shell-script territory; not repoman's job.
- Configuring host ollama (installer, systemd override, model pulls) — rejected as scope creep across the host-config boundary.
- Remote profile registries / fetching profiles over HTTP — out of scope. Library is local files only.
- Profile dependencies (`profile A includes profile B`) — YAGNI. Each profile is independent.
- Profile YAML schema validation — trust incus. v0.4 just substitutes templates; incus rejects malformed YAML at apply time with clear errors.
- Per-host portability automation — registry is per-host (lives in `~/.config/repoman/`); document that fact rather than automate it.

---

## 2. Architecture

### 2.1 New module: `src/profile.reef`

Single new module covering the profile library. Composes `incus`, `path`, `config`, and stdlib I/O.

| Responsibility | Pure? |
|---|---|
| `vendor_dir(): string` — `/usr/local/share/repoman/profiles` | yes |
| `user_dir(home: string): string` — `<home>/.config/repoman/profiles.d` | yes |
| `lookup(name: string, home: string): Result[string, string]` — search user dir then vendor dir, return path to YAML file or Err if not found | side-effecting (filesystem reads) |
| `list_all(home: string): [ProfileEntry]` — enumerate both dirs, return list with source (user/vendor) tags | side-effecting |
| `render(yaml: string, host: HostFacts): string` — substitute `${HOST_LAN_IP}`, `${USER}`, `${HOME}` | yes |
| `install(name: string, home: string, host: HostFacts): Result[bool, string]` — lookup → render → `incus.profile_create_or_edit` | side-effecting |
| `diff(name: string, home: string, host: HostFacts): Result[string, string]` — render the file, fetch the live incus profile, return unified diff | side-effecting |
| `remove(name: string): Result[bool, string]` — `incus profile delete` (no-op if not installed) | side-effecting |
| `show(name: string, home: string, host: HostFacts): Result[string, string]` — return rendered YAML for inspection | side-effecting |

Pure helpers (`render`, `vendor_dir`, `user_dir`) get unit tests. Effectful wrappers are smoke-tested via `cmd_*`.

### 2.2 Edits to existing modules

- `src/setup.reef`: drop `render_llm_share_template`, `template_contains_placeholder`, the `apply_stage` cases for `llm_share_profile` and `registry_defaults`, and the `--with-llm`/`--without-llm` flag plumbing in `cmd_setup`. Setup becomes: detect environment → print plan → ensure incus project → write registry with `[host].lan_ip` populated. The wizard still has `--non-interactive`. Two stages remain (down from up to four): `incus_project`, `registry_defaults`.
- `src/cli.reef`: add `cmd_profile` dispatch covering 5 subcommands. Add pre-launch validation in `cmd_new`: before `incus.launch`, iterate `eff.profiles` and call `incus.profile_exists("default", name)` for each — error early with `hint: repoman profile install <name>` if any are missing. Update `print_usage()` help text.
- `src/config.reef`: add `Host` substruct (`lan_ip: string`) and `Registry.host: Host` field. Drop `LlmDefaults` and `Defaults.llm`. Bump schema constant to 3. Add migration: if loading schema 2, extract `[defaults.llm.ollama_url]`, parse the host portion of the URL into `[host].lan_ip`, drop the rest.
- `src/incus.reef`: add `profile_get(name): Result[string, string]` (`incus profile show <name>` capturing stdout) — needed for `profile diff`.
- `src/main.reef`: dispatch already routes through `cli.dispatch`; no changes.

### 2.3 Build/install changes

`Makefile`:
- New target dependency: `install` copies `profiles/*.yml` into `/usr/local/share/repoman/profiles/`.
- New target: `uninstall` removes them.

```makefile
PROFILES_DIR = $(DESTDIR)$(PREFIX)/share/repoman/profiles

install: build
    install -d $(DESTDIR)$(BINDIR)
    install -m 0755 build/repoman $(DESTDIR)$(BINDIR)/repoman
    install -d $(PROFILES_DIR)
    install -m 0644 profiles/*.yml $(PROFILES_DIR)/

uninstall:
    rm -f $(DESTDIR)$(BINDIR)/repoman
    rm -rf $(PROFILES_DIR)
```

### 2.4 Repository layout addition

```
~/repos/repoman/
├── profiles/
│   ├── claude-share.yml      # bind ${HOME}/.claude
│   ├── llm-share.yml         # bind /usr/local/bin/ollama, ${HOME}/.ollama; OLLAMA_HOST env
│   └── dotfiles.yml          # bind ${HOME}/.gitconfig, ${HOME}/.hgrc
├── src/
│   ├── profile.reef          # NEW
│   ├── ...
└── ...
```

`profiles/` is a tracked directory in the source repo (versioned alongside code). The files are templates; substitutions happen at install time.

---

## 3. Data shapes

### 3.1 Vendor profile templates (v0.4 starter library)

**`profiles/claude-share.yml`:**
```yaml
name: claude-share
description: Share host's Claude CLI state (auth, history, plugins) into containers.
config: {}
devices:
  claude-state:
    type: disk
    source: ${HOME}/.claude
    path: ${HOME}/.claude
    shift: "true"
  claude-bin:
    type: disk
    source: ${HOME}/.local/bin/claude
    path: /usr/local/bin/claude
    readonly: "true"
    shift: "true"
```

(Note: `claude-bin` assumes claude is installed via npm/pipx into `~/.local/bin/`. Users with system-installed claude shadow this profile.)

**`profiles/llm-share.yml`:**
```yaml
name: llm-share
description: Wire containers to the host ollama daemon over LAN.
config:
  environment.OLLAMA_HOST: "http://${HOST_LAN_IP}:11434"
devices:
  ollama-bin:
    type: disk
    source: /usr/local/bin/ollama
    path: /usr/local/bin/ollama
    readonly: "true"
  ollama-state:
    type: disk
    source: ${HOME}/.ollama
    path: ${HOME}/.ollama
    shift: "true"
```

**`profiles/dotfiles.yml`:**
```yaml
name: dotfiles
description: Bind common host dotfiles (.gitconfig, .hgrc) into containers.
config: {}
devices:
  gitconfig:
    type: disk
    source: ${HOME}/.gitconfig
    path: ${HOME}/.gitconfig
    readonly: "true"
    shift: "true"
  hgrc:
    type: disk
    source: ${HOME}/.hgrc
    path: ${HOME}/.hgrc
    readonly: "true"
    shift: "true"
```

Users add their own dotfiles by shadowing — copy `dotfiles.yml` into `~/.config/repoman/profiles.d/` and add `.zshrc`, `.tmux.conf`, etc.

### 3.2 Registry schema 3

```toml
[repoman]
schema = 3
output = "quiet"

[host]
lan_ip = "192.168.168.124"           # populated by `repoman setup` from `ip -4 addr show br0`

[defaults]
repos_root     = "~/repos"
backup_root    = "/nfs/repos"
logdir         = "~/.local/state/repoman"
incus_project  = "repoman"
default_image  = "images:ubuntu/26.04/cloud"
profiles       = ["default"]                    # safe default; users add others by editing or via override files

# [defaults.llm] block removed (was in schema 2).

[[project]]
name        = "isurus"
repo        = "isurus-project"
image       = "images:ubuntu/26.04/cloud"
profiles    = ["default", "claude-share", "llm-share"]
created     = "2026-04-28T15:00:00Z"
last_sync   = ""
backup      = true
```

### 3.3 Schema 2 → 3 migration

Implicit (no migration function — same pattern as v0.3's 1→2):
- `parse_registry` accepts schemas 1, 2, or 3.
- When loading schema 2: read `[defaults.llm.ollama_url]` (e.g., `"http://192.168.168.124:11434"`), strip `http://` prefix and `:11434` suffix, store remainder in `[host].lan_ip`. If parse fails or the field is missing, leave `lan_ip` empty (will be re-detected on next `setup` run).
- When loading schema 1: same behavior as schema 2 except `[host].lan_ip = ""` (no llm block to extract from).
- Final `Registry` literal in `parse_registry` always returns `schema: 3`.
- `default_registry` returns `schema: 3` with `[host].lan_ip = ""` (populated by `setup`).
- `serialize_registry` writes schema 3 with `[host]` block; never writes `[defaults.llm]`.

### 3.4 ProfileEntry struct (for `list_all`)

```reef
type ProfileEntry = struct
    name:        string       // e.g., "claude-share"
    source:      string       // "user" or "vendor"
    file_path:   string       // resolved path
    installed:   bool         // present in incus state
    drift:       bool         // installed-and-rendered-file-differs (computed lazily; false if not installed)
end ProfileEntry
```

### 3.5 HostFacts (substitution context)

```reef
type HostFacts = struct
    lan_ip: string
    user:   string
    home:   string
end HostFacts
```

Constructed at command entry (read from registry + env), passed to `profile.render`/`install`/etc.

---

## 4. Subcommand flows

### 4.1 `repoman profile list`

1. Resolve user dir + vendor dir.
2. Enumerate `*.yml` in each. Build a name → source map; user wins on collision (note as "user (shadows vendor)" in source column).
3. For each, query `incus profile show --project repoman <name>` to determine `installed`.
4. For installed entries, render the file and compute `drift = (rendered != incus_show_output)`.
5. Print a table:

```
NAME            SOURCE                 INSTALLED   DRIFT
claude-share    vendor                 yes         no
llm-share       user (shadows vendor)  yes         yes
dotfiles        vendor                 no          n/a
my-experiment   user                   no          n/a
```

Exit 0 always (informational).

### 4.2 `repoman profile install <name>` (or `--all`)

1. Resolve `name` to a file path via shadow lookup.
2. Read file → render with `HostFacts` (registry `[host].lan_ip`, env `USER`, env `HOME`). If `${HOST_LAN_IP}` is in the file but registry has empty `lan_ip`, fail with hint to run `repoman setup`.
3. Call `incus.profile_create_or_edit("repoman", name, rendered_yaml)`.
4. Print `==> installed <name> (source: user|vendor)`.

`--all`: enumerate the union of user and vendor profile names; install each (user shadows resolve correctly).

Exit 0 success, 1 install failure, 3 missing host facts.

### 4.3 `repoman profile diff <name>`

1. Resolve and render the file.
2. Fetch `incus profile show --project repoman <name>` stdout. If not installed, print "not installed; would install <name>" and the rendered content.
3. Compute and print a unified diff between rendered file and live incus state. Exit 0 if no diff, 1 if diff exists, 3 on resolution failure.

(Useful for "what will `profile install` change?" before running it.)

### 4.4 `repoman profile remove <name>`

1. `incus profile delete --project default <name>`. If it doesn't exist in incus, that's an error from incus — surface it to the user with exit 1 and a hint that they may not need to remove it.
2. Does NOT delete the file from `~/.config/repoman/profiles.d/<name>.yml`. User's files are user's. Print: `==> removed <name> from incus (file at <path> untouched)`.
3. If any project in the registry references the just-removed profile in its `profiles` list, print a warning naming the projects that will fail to relaunch — but exit 0; the removal succeeded.

### 4.5 `repoman profile show <name>`

1. Resolve and render. Print to stdout. Exit 0.

Useful for debugging templating, piping into other tools, or sanity-checking before install.

### 4.6 `repoman setup` (revised — much smaller)

Stages reduce from four to two:

1. **`incus_project`** — ensure `repoman` project exists (unchanged).
2. **`registry_defaults`** — write registry with `schema = 3`, `[host].lan_ip` populated from `detect_host_lan_ip()`, default `[defaults].profiles = ["default", "claude-share"]`.

The `claude_share_check` and `llm_share_profile` stages from v0.3 are gone. Profile installation is now `repoman profile install --all`.

Flags: `--non-interactive` only. No `--with-llm`/`--without-llm`.

Help text:

```
setup [--non-interactive]
    First-time host bootstrap: ensures Incus project 'repoman' exists,
    detects host LAN IP, writes initial registry. Run `repoman profile
    install --all` afterwards to install the vendor profile library.
```

### 4.7 `repoman new` (small addition: pre-launch profile validation)

Just before `incus.launch`, iterate `eff.profiles`. For each name except the magic incus default `"default"`, call `incus.profile_exists("default", name)`. (All repoman-managed profiles install into the incus `default` project — see §6 below — and our `features.profiles=false` setting on the `repoman` project means containers in it inherit profiles from `default`.) If any check returns false:

```
repoman: error: container references profile 'foo' but it's not installed in incus.
hint: repoman profile install foo
hint: repoman profile install --all   (to install the vendor library)
```

Exit 4 (resource-conflict class).

---

## 5. Testing

Mirrors the v0.3 testing posture: pure logic gets unit tests; effectful wrappers are smoke-tested.

**Pure tests** (run on every build):
- `profile.render` — given a YAML string with `${HOST_LAN_IP}`, `${USER}`, `${HOME}` and a `HostFacts`, returns the substituted output. Test cases: all three present, only some present, none present (no-op), unknown variable left as literal.
- `profile.vendor_dir` and `profile.user_dir` — given a `home`, return the documented paths.
- Schema 2 → 3 migration: load a fixture toml with `[defaults.llm.ollama_url]` set, verify `[host].lan_ip` is populated correctly; load one with the field missing, verify empty string; load schema 1, verify both work.
- Registry schema-3 round-trip serialize → parse.

**Smoke tests** (require an Incus host, gated on `REPOMAN_SMOKE=1`):
- `repoman profile install claude-share` against a fresh host produces a working profile.
- `repoman profile diff` correctly identifies drift between an edited file and the installed profile.
- `repoman profile remove` removes from incus but leaves the file.
- `repoman new <name>` against a registry with `profiles = [..., "missing-profile"]` errors early with the expected hint, before any incus mutation.
- Schema 2 registry on disk loads cleanly and re-saves as schema 3, with `[host].lan_ip` extracted from the old `ollama_url`.

---

## 6. Risks / mitigations

| Risk | Mitigation |
|---|---|
| Existing users have hand-authored `claude-share` profiles in incus that differ from the vendor `claude-share.yml`. `repoman profile install claude-share` would overwrite. | Document migration: before `install`, run `repoman profile diff claude-share` to see what would change; user can `cp /usr/local/share/repoman/profiles/claude-share.yml ~/.config/repoman/profiles.d/`, edit to match their hand-authored version, then `install` (user file wins). README has a "migrating to v0.4" section. |
| Vendor `dotfiles.yml` binds `~/.gitconfig` but a user doesn't have one. Container fails to launch. | Minimal initial set (.gitconfig, .hgrc) reduces this surface. README documents shadowing as the way to tailor. Future v0.5 could explore `optional: true` semantics if incus supports it. |
| `${HOST_LAN_IP}` can't be substituted if registry's `[host].lan_ip` is empty (e.g., `setup` couldn't detect br0). | `profile install` errors with a clear "run `repoman setup` first" hint. Detection happens in `setup`; it's the documented path. |
| User edits vendor profile file directly at `/usr/local/share/repoman/profiles/<name>.yml`. Next `make install` overwrites. | Document: vendor dir is owned by the package; user changes go in `~/.config/repoman/profiles.d/`. |
| `repoman profile install --all` order dependencies (e.g., what if profile A references profile B?). | YAGNI for v0.4 — no dependencies model. `--all` installs in alphabetical order; user re-installs if needed. Document. |
| `incus profile show` output format differs from what we render — diff always shows noise. | The render → install → show roundtrip should be stable for the limited template surface we use. If incus rewrites/normalizes the YAML, `diff` will show normalization noise; we accept this for v0.4 and document. v0.5 could add a smarter diff. |

---

## 7. Decisions and open questions

### Resolved decisions (locked into spec)

- **All repoman-managed profiles install in the incus `default` project.** v0.1/v0.2 already placed `claude-share` there; v0.3's `llm-share` was inconsistent (placed in `repoman` project). v0.4 unifies: every vendor and user profile installed via `repoman profile install` lands in `default`. The `repoman` project's `features.profiles=false` setting means containers in it inherit profiles from `default`, so this works without any per-profile project metadata. Users who want a different project can `incus profile copy` manually after install.
- **`repoman profile remove` does not touch the registry.** It only deletes from incus; if `[defaults].profiles` or any project's `profiles` list still names the removed profile, those references fail at next `new` (caught by pre-launch validation). `remove` prints a warning if removal would orphan a reference, but doesn't auto-edit the registry.
- **`profile diff` supports `--vendor` for shadow-vs-vendor comparison.** Default is rendered-file-vs-incus (most useful day-to-day). `--vendor` shows the user shadow vs the vendor file (useful when upgrading repoman). If the named profile isn't shadowed (no user file), `--vendor` errors with a clear hint.
- **Initial `[defaults].profiles = ["default"]`.** Just the magic incus `default` profile. Users add others (claude-share, llm-share, etc.) explicitly — via override files in `repos.d/` or by editing `repoman.toml` — after they've run `profile install` for whatever they want.

### Open questions

- **O-1: Per-host portability of `[host].lan_ip`.** A user moving `repoman.toml` between hosts would carry the old IP. Out of scope to automate — registry is per-host. Document.
- **O-2: Vendor `dotfiles.yml` failure mode.** If a user lacks `~/.gitconfig` or `~/.hgrc` on the host, the bind fails at container start. The minimal initial set reduces but doesn't eliminate this risk. Investigate whether incus supports `optional: true` on disk devices (newer incus versions may); if yes, add to the vendor profile. If no, document and let users shadow.
- **O-3: `incus profile show` output format stability.** If incus normalizes/reorders YAML on write, `profile diff` shows formatting noise rather than semantic drift. Acceptable for v0.4; revisit if it's painful in practice.
- **O-4: What if vendor library grows in v0.5+?** Users who shadowed an existing profile keep their shadow (good). Users who didn't get the new ones automatically (good). Risk: vendor adds a name that collides with a user's custom. Shadowing handles this — user wins. Documented in §6's risks.

---

## 8. Build sequence (suggested order)

1. Schema 3 plumbing in `config.reef`: add `[host]` substruct, drop `[defaults].llm`, schema 2→3 migration, schema constant bump in `default_registry`. Round-trip + migration tests.
2. `incus.profile_get(name)` wrapper. Small, used by `profile diff`/`list`/`show`.
3. `profile.reef` module skeleton + pure helpers (`vendor_dir`, `user_dir`, `render`). Unit tests.
4. `profile.lookup` and `profile.list_all` (filesystem-effectful). Smoke test by inspection.
5. `profile.install`, `profile.remove`, `profile.show`. Smoke-tested via subcommand wiring in step 8.
6. `profile.diff`. Smoke-tested via subcommand wiring.
7. Trim `setup.reef`: remove llm-stage, remove flag plumbing for `--with-llm`/`--without-llm`, remove `render_llm_share_template` + `template_contains_placeholder`. Update `apply_stage` to handle only `incus_project` and `registry_defaults` (with `[host].lan_ip` writing).
8. Wire `cmd_profile` dispatch in `cli.reef` covering all 5 verbs. Update `print_usage`. Add pre-launch validation in `cmd_new`.
9. `Makefile`: install profiles into `/usr/local/share/repoman/profiles/`.
10. Author the three vendor profile YAML files in `profiles/`.
11. README + VISION updates: profile library section, migration guide for users coming from v0.3, document the new subcommands.
12. Smoke run on a fresh host: `setup` → `profile install --all` → `new myproj` (with profiles) → `shell` → verify everything works → `profile remove` → `profile diff` to verify drift detection. Tag v0.4.0.