aiolabs/lnbits-sensei
Archived
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(readme): reflect the now-real dev-env tooling

Browse source 
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) <noreply@anthropic.com>
This commit is contained in:
Padreug 2026-06-15 21:18:56 +02:00
commit 3d73e02d6b
1 changed files with 79 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

114
README.md
View file

@ -1,29 +1,36 @@
# lnbits-sensei # lnbits-sensei
> **Status:** eval-green skeleton. Module schema + flake wiring are real; > **Status:** working dev-env. Module schema, flake wiring, and the
> the `dev` CLI and dev-env bootstrap are stubs. Not yet usable end-to-end. > 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 Opinionated, bare-skeleton scaffold for running an LNbits stack
— inspired by the [omnixy](https://github.com/TheArctesian/omnixy) — inspired by the [omnixy](https://github.com/TheArctesian/omnixy)
NixOS module pattern but stripped of any personal identity so the NixOS module pattern but stripped of any personal identity so the
template is consumable as-is. template is consumable as-is.
The goal: clone, fill in your identity + remote topology, and get a The goal: clone, fill in your identity + remote topology + a project
working LNbits dev environment driven by one command: 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-env-bootstrap # materialize bare repos + worktrees on disk
dev up --regtest # full multi-node regtest stack (LND + CLN + Eclair lb dev # cd to the lnbits dev worktree
# + bitcoind + electrs); for channel/payment dev-status # dirty + ahead/behind across every worktree
# integration testing regtest-start dev # build lnbits from a worktree, bring up regtest
dev down # tear down whatever's running prb lnbits fix-x # spin a throwaway worktree for an upstream PR
dev logs # follow lnbits (+ docker, if regtest)
dev shell # drop into the lnbits venv (or a regtest container)
``` ```
`--fakewallet` is the default mode because the iteration loop for See [`modules/dev-env/README.md`](modules/dev-env/README.md) for the
extension and frontend work doesn't need real chains. `--regtest` full command set and bootstrap walkthrough.
exists for the moments when it does.
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 ## Remote topology
@ -54,27 +61,36 @@ hardware-configuration.nix # placeholder; overwrite with nixos-generate-con
modules/ modules/
├── core.nix # lnbits-sensei.* option schema ├── 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/ ├── git/
│ └── remotes.nix # remote topology (upstream / fork / extras) │ └── remotes.nix # remote topology (upstream / fork / extras)
└── dev-env/ └── dev-env/
├── default.nix # module entry; imports options + config + lib ├── README.md # command set + bootstrap walkthrough
├── options.nix # devEnv schema (projects, regtest, tmux) ├── default.nix # module entry; imports options + lib + config
├── config.nix # wires the schema into NixOS config (stub) ├── options.nix # devEnv schema (projects, deploy, regtest, tmux)
├── lib.nix # dev-env-internal helpers (stub) ├── 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/ └── 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 └── remotes.md # the three remote-topology patterns
LICENSE # MIT (placeholders — fill in year + holder) 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 ## Development flow
### First-time bootstrap (per machine) ### First-time bootstrap (per machine)
@ -109,12 +125,29 @@ in follow-up passes.
sudo nixos-rebuild switch --flake .#<hostName> sudo nixos-rebuild switch --flake .#<hostName>
``` ```
### 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 After a rebuild, the dev-env helpers are on PATH (standalone commands)
for the verb set. See **[Claude orientation](#claude-orientation)** or sourced into interactive shells (navigation/worktree functions).
below if you want AI-assisted work to pick up the project's gotchas Run `dev-env-bootstrap` once to materialize the repos + worktrees you
for free. declared, then:
```
dev-env-bootstrap # bring the ~/dev/ tree up to spec (idempotent)
lb dev / g <cat> <repo> # navigate worktrees
dev-status # divergence + dirty state across everything
wts / wtu <repo> # 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 <session> # launch a declared tmux session
dev-deploy <host> # 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) ### Workspace layout (the `~/dev/` tree)
@ -161,9 +194,14 @@ devEnv.projects = {
}; };
``` ```
The forthcoming bootstrap (`dev bootstrap`, name TBD) materializes the `dev-env-bootstrap` materializes the bare repo at
bare repo at `~/dev/repos/lnbits.git` and checks out one worktree per `~/dev/repos/lnbits.git`, wires its remotes, and checks out one
declared entry. 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): **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 the per-project tree pollutes the branch list and tempts "I'll just
commit this here" accidents. The `upstream-prs/` tree makes the commit this here" accidents. The `upstream-prs/` tree makes the
contract explicit: this worktree is on `upstream/main`, branch off, 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 prb lnbits fix-payment-race # create ~/dev/upstream-prs/lnbits-fix-payment-race
# branched from upstream/main, fork as push target # 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 **Navigation helpers** — shell functions sourced into interactive
`devEnv.projects`: shells, driven by what's on disk under `~/dev/`:
``` ```
lb dev # cd ~/dev/lnbits/dev lb dev # cd ~/dev/lnbits/dev
lb fix-issue-123 # cd ~/dev/lnbits/fix-issue-123 lb fix-issue-123 # cd ~/dev/lnbits/fix-issue-123
g extensions myext # cd ~/dev/extensions/myext
ext <name> # cd ~/dev/shared/extensions/<name>
``` ```
## Claude orientation ## Claude orientation