From 3d73e02d6b07e94f3911749485dc43d6cabb1f46 Mon Sep 17 00:00:00 2001 From: Padreug Date: Mon, 15 Jun 2026 21:18:56 +0200 Subject: [PATCH] docs(readme): reflect the now-real dev-env tooling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The root README pitched a unified 'dev up' CLI and called the dev-env stubs — both stale now that the real implementation has landed. Rewrite the status header, the day-to-day command set, the module file tree, and drop the (planned)/(stub) markers on bootstrap, prb, and nav helpers. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 114 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 78 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 76cc987..b1eaed9 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,36 @@ # lnbits-sensei -> **Status:** eval-green skeleton. Module schema + flake wiring are real; -> the `dev` CLI and dev-env bootstrap are stubs. Not yet usable end-to-end. +> **Status:** working dev-env. Module schema, flake wiring, and the +> dev-env tooling (bootstrap, worktree/nav helpers, regtest wrappers, +> upstream-PR flow, deploy wrapper, declarative tmux) are all real and +> `nix flake check`-green. Fill in `settings.nix` + a project list and +> it's usable end-to-end. Opinionated, bare-skeleton scaffold for running an LNbits stack — inspired by the [omnixy](https://github.com/TheArctesian/omnixy) NixOS module pattern but stripped of any personal identity so the template is consumable as-is. -The goal: clone, fill in your identity + remote topology, and get a -working LNbits dev environment driven by one command: +The goal: clone, fill in your identity + remote topology + a project +list, rebuild, and get a working multi-project LNbits dev environment — +bare repos + worktrees materialized in one command, with navigation, +sync, regtest, and upstream-PR helpers on PATH: ``` -dev up # default: FakeWallet — no docker, instant -dev up --regtest # full multi-node regtest stack (LND + CLN + Eclair - # + bitcoind + electrs); for channel/payment - # integration testing -dev down # tear down whatever's running -dev logs # follow lnbits (+ docker, if regtest) -dev shell # drop into the lnbits venv (or a regtest container) +dev-env-bootstrap # materialize bare repos + worktrees on disk +lb dev # cd to the lnbits dev worktree +dev-status # dirty + ahead/behind across every worktree +regtest-start dev # build lnbits from a worktree, bring up regtest +prb lnbits fix-x # spin a throwaway worktree for an upstream PR ``` -`--fakewallet` is the default mode because the iteration loop for -extension and frontend work doesn't need real chains. `--regtest` -exists for the moments when it does. +See [`modules/dev-env/README.md`](modules/dev-env/README.md) for the +full command set and bootstrap walkthrough. + +FakeWallet (`LNBITS_BACKEND_WALLET_CLASS=FakeWallet`) is the default +iteration path for extension/frontend work — no docker needed. The +`regtest-*` helpers (gated on `devEnv.regtest.enable`) exist for the +moments you need real channels/payments. ## Remote topology @@ -54,27 +61,36 @@ hardware-configuration.nix # placeholder; overwrite with nixos-generate-con modules/ ├── core.nix # lnbits-sensei.* option schema -├── lib.nix # shared helpers — config.lnbits-sensei.lib (stub) +├── lib.nix # shared helpers — config.lnbits-sensei.lib +├── secrets.nix # sops-nix wiring (inert until you add a secret) ├── git/ │ └── remotes.nix # remote topology (upstream / fork / extras) └── dev-env/ - ├── default.nix # module entry; imports options + config + lib - ├── options.nix # devEnv schema (projects, regtest, tmux) - ├── config.nix # wires the schema into NixOS config (stub) - ├── lib.nix # dev-env-internal helpers (stub) + ├── README.md # command set + bootstrap walkthrough + ├── default.nix # module entry; imports options + lib + config + ├── options.nix # devEnv schema (projects, deploy, regtest, tmux) + ├── lib.nix # mkProject + path/remote helpers + ├── config.nix # renders /etc/dev-env/*, installs scripts + ├── presets/example.nix # worked, generic project list — copy and edit + ├── tests/smoke.nix # nix flake check schema test └── scripts/ - └── dev.sh # `dev` CLI dispatcher (stub) + ├── bootstrap.sh # materialize bare repos + worktrees + ├── nav.sh # lb / g / ext / dep / prs / shared / repos + ├── worktree.sh # wt / wts / wtu / wtn + lnbits sync helpers + ├── pr-helpers.sh # prb / prc / prl — upstream-PR worktrees + ├── rebase.sh # safe fork-onto-upstream rebase + ├── status.sh # dev-status — divergence across worktrees + ├── deploy.sh # dev-deploy — nixos-rebuild wrapper + ├── regtest.sh # regtest-start/-stop/-status (gated) + ├── tmux-launch.sh # dev-tm — declarative tmux sessions + └── git-hooks/pre-commit # shared secret-scanner hook -docs/ +docs/ # human-facing references (also seeded to ~/dev/) └── remotes.md # the three remote-topology patterns LICENSE # MIT (placeholders — fill in year + holder) ``` -`(stub)` files contain option schemas and TODO bodies; they evaluate -cleanly but don't do real work yet. Substantive implementations land -in follow-up passes. - ## Development flow ### First-time bootstrap (per machine) @@ -109,12 +125,29 @@ in follow-up passes. sudo nixos-rebuild switch --flake .# ``` -### Day-to-day (planned — `dev.sh` is a stub today) +### Day-to-day -The `dev` CLI is the single entry point. See the top of this README -for the verb set. See **[Claude orientation](#claude-orientation)** -below if you want AI-assisted work to pick up the project's gotchas -for free. +After a rebuild, the dev-env helpers are on PATH (standalone commands) +or sourced into interactive shells (navigation/worktree functions). +Run `dev-env-bootstrap` once to materialize the repos + worktrees you +declared, then: + +``` +dev-env-bootstrap # bring the ~/dev/ tree up to spec (idempotent) +lb dev / g # navigate worktrees +dev-status # divergence + dirty state across everything +wts / wtu # sync worktrees / fetch upstream + show divergence +rebase status # which forks need rebasing onto upstream +regtest-start dev # build lnbits from a worktree, bring up regtest +prb lnbits fix-x # throwaway worktree for an upstream PR +dev-tm # launch a declared tmux session +dev-deploy # nixos-rebuild against your deploy flake +``` + +The full command table + bootstrap walkthrough lives in +[`modules/dev-env/README.md`](modules/dev-env/README.md). See +**[Claude orientation](#claude-orientation)** below if you want +AI-assisted work to pick up the project's gotchas for free. ### Workspace layout (the `~/dev/` tree) @@ -161,9 +194,14 @@ devEnv.projects = { }; ``` -The forthcoming bootstrap (`dev bootstrap`, name TBD) materializes the -bare repo at `~/dev/repos/lnbits.git` and checks out one worktree per -declared entry. +`dev-env-bootstrap` materializes the bare repo at +`~/dev/repos/lnbits.git`, wires its remotes, and checks out one +worktree per declared entry. It's idempotent — re-running only fills in +what's missing, and never touches a worktree whose branch has drifted +from the spec. See [`docs/remotes.md`](docs/remotes.md) and +[`modules/dev-env/presets/example.nix`](modules/dev-env/presets/example.nix) +for richer project declarations (explicit `url`, `upstream`, `fork`, +`category`, single-clone projects). **Why bare repos + worktrees** (rather than fresh clones per branch): @@ -179,19 +217,23 @@ PRs against upstream repos (e.g. `lnbits/lnbits`) want to branch from the per-project tree pollutes the branch list and tempts "I'll just commit this here" accidents. The `upstream-prs/` tree makes the contract explicit: this worktree is on `upstream/main`, branch off, -push to your fork, open the PR. Helper (planned): +push to your fork, open the PR. The `prb` helper does this: ``` prb lnbits fix-payment-race # create ~/dev/upstream-prs/lnbits-fix-payment-race # branched from upstream/main, fork as push target +prc lnbits fix-payment-race # remove the worktree after the PR merges +prl # list active PR worktrees ``` -**Navigation helpers** (planned) — short aliases generated from -`devEnv.projects`: +**Navigation helpers** — shell functions sourced into interactive +shells, driven by what's on disk under `~/dev/`: ``` lb dev # cd ~/dev/lnbits/dev lb fix-issue-123 # cd ~/dev/lnbits/fix-issue-123 +g extensions myext # cd ~/dev/extensions/myext +ext # cd ~/dev/shared/extensions/ ``` ## Claude orientation