note the bootstrap installer design for next session

2026-08-13 02:10:07 +00:00
parent 28d58728cf
commit ed925a14b8
1 changed files with 43 additions and 0 deletions
@@ -0,0 +1,43 @@
+# TODO
+
+## Bootstrap installer (next session — 2026-08-14)
+
+**Goal:** clone this repo on any machine, run one command, and every file lands
+where the tooling expects it.
+
+    git clone <this repo> ~/projects/claude-mds && ~/projects/claude-mds/install.sh
+
+### Shape
+
+- **A manifest, not a script full of paths.** Declare `repo path -> target path`
+  in one file and let `install.sh` walk it. Adding a doc later should mean one
+  manifest line, not editing shell.
+- **Symlinks, not copies.** Same reason as here: two copies drift, and the point
+  of the repo is that an edit lands in git. `ln -sfn`.
+- **Idempotent.** Safe to re-run after every `git pull`. Re-linking an existing
+  correct link is a no-op.
+- **Conditional targets.** `user/CLAUDE.md` installs everywhere. `officer.dev/`
+  only where that workspace exists. A manifest entry needs a "only if this path
+  exists" condition.
+- **Never clobber silently.** If the target is a real file and not our link,
+  back it up (`.bak-<date>`) and say so. That file may be the only copy of
+  something written by hand on that machine.
+- **Dry run by default, or at least `--dry-run`.** Show what it would link.
+
+### Known problem to fix while doing it
+
+`user/CLAUDE.md` hardcodes `~/projects/claude-mds/tools/mask-secret.py`. That
+path is this machine's. Options: have the installer rewrite the path at install
+time, put the tools on `PATH` (`~/.local/bin/mask-secret`), or resolve it from
+`$CLAUDE_MDS_HOME`. Prefer the `PATH` option — the doc then names a command
+rather than a location, which is true everywhere.
+
+### Open questions
+
+- Which files are genuinely universal vs this-machine-only? Right now
+  `officer.dev/CLAUDE.md` is the only machine-specific one, but the
+  `platform-appstore/` set is a candidate and was never folded in.
+- Should `settings.json` / hooks be managed here too, or only `.md` files? The
+  repo is named for the docs but already carries `tools/`.
+- Bootstrapping the bootstrap: the machine needs git and the repo URL before any
+  of this runs. Worth a one-line `curl | sh`, or deliberately not.