docs: showcase folder layout + bootstrap/dev/worktree flow
Adds two sections to the README: - `## Layout` — annotated tree of the actual files in the repo, with `(stub)` markers on the modules whose bodies are TODO. Replaces the previous "Planned shape" bullet list (was aspirational and lying about files that didn't exist, e.g. `modules/lnbits/`). - `## Development flow` — three subsections: first-time bootstrap (clone, settings, nixos-generate-config, flake check, switch), day-to-day via the `dev` CLI, and project worktrees from `devEnv.projects`. Status line bumped from "scaffold in progress" to "eval-green skeleton" to match where we actually are — module schema + flake wiring are real, CLI + dev-env bootstrap remain stubs. Renames `## Development` to `## Contributing` since "Development flow" is now the user-facing section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
45c44f550e
commit
6959d13120
1 changed files with 96 additions and 13 deletions
109
README.md
109
README.md
|
|
@ -1,6 +1,7 @@
|
|||
# lnbits-sensei
|
||||
|
||||
> **Status:** scaffold in progress. Not yet usable.
|
||||
> **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.
|
||||
|
||||
Opinionated, bare-skeleton scaffold for running an LNbits stack
|
||||
— inspired by the [omnixy](https://github.com/TheArctesian/omnixy)
|
||||
|
|
@ -41,21 +42,103 @@ See [`docs/remotes.md`](docs/remotes.md) for the three canonical
|
|||
patterns (upstream-only, github-fork-for-PRs, multi-remote-with-private
|
||||
host on forgejo / gitea / codeberg / sourcehut).
|
||||
|
||||
## Planned shape
|
||||
## Layout
|
||||
|
||||
- `flake.nix` — pins `lnbits/lnbits` upstream + dev tooling.
|
||||
- `settings.nix` — single source of truth (user, host, timezone, remote
|
||||
topology). Consumer fills in.
|
||||
- `modules/core.nix` — `lnbits-sensei.*` option schema (features, bind addr).
|
||||
- `modules/git/remotes.nix` — remote topology abstraction.
|
||||
- `modules/dev-env/` — the `dev` CLI, worktree mgmt, regtest stack
|
||||
spin-up, tmux session launcher, upstream-PR helper. Generalized off
|
||||
any private-host assumptions.
|
||||
```
|
||||
flake.nix # inputs: nixpkgs, home-manager, lnbits-src
|
||||
flake.lock
|
||||
settings.nix # consumer fills in: user, host, identity, remotes
|
||||
configuration.nix # NixOS entry — thin imports list
|
||||
home.nix # home-manager entry — thin
|
||||
hardware-configuration.nix # placeholder; overwrite with nixos-generate-config
|
||||
|
||||
## Development
|
||||
modules/
|
||||
├── core.nix # lnbits-sensei.* option schema
|
||||
├── lib.nix # shared helpers — config.lnbits-sensei.lib (stub)
|
||||
├── 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)
|
||||
└── scripts/
|
||||
└── dev.sh # `dev` CLI dispatcher (stub)
|
||||
|
||||
This repo is iterated on under the sandboxed-claude policy from
|
||||
omnixy's `scripts/sandbox-claude.sh` — a per-launch `.claude/settings.json`
|
||||
docs/
|
||||
└── 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)
|
||||
|
||||
1. **Clone** the repo into a working directory of your choice.
|
||||
|
||||
2. **Edit `settings.nix`** — fill in `user`, `hostName`, `timeZone`,
|
||||
`gitName`, `gitEmail`, and `git.remotes` (see
|
||||
[docs/remotes.md](docs/remotes.md) for topology patterns).
|
||||
|
||||
3. **Replace the placeholder hardware config** with your real one:
|
||||
|
||||
```sh
|
||||
sudo nixos-generate-config --root / --dir $(pwd)
|
||||
```
|
||||
|
||||
(The shipped `hardware-configuration.nix` evaluates but won't boot —
|
||||
intentional, so a forgotten regeneration fails loudly rather than
|
||||
silently booting on someone else's disk layout.)
|
||||
|
||||
4. **Validate** the schema before activating anything:
|
||||
|
||||
```sh
|
||||
nix flake check --no-build
|
||||
```
|
||||
|
||||
Should print `all checks passed!`.
|
||||
|
||||
5. **Switch** when ready:
|
||||
|
||||
```sh
|
||||
sudo nixos-rebuild switch --flake .#<hostName>
|
||||
```
|
||||
|
||||
### Day-to-day (planned — `dev.sh` is a stub today)
|
||||
|
||||
The `dev` CLI is the single entry point. See the top of this README
|
||||
for the verb set.
|
||||
|
||||
### Project worktrees (planned)
|
||||
|
||||
Declare the projects you work in via `settings.nix`:
|
||||
|
||||
```nix
|
||||
devEnv.projects = {
|
||||
lnbits = {
|
||||
url = "https://github.com/lnbits/lnbits";
|
||||
worktrees = {
|
||||
main = { branch = "main"; };
|
||||
dev = { branch = "dev"; };
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
The forthcoming bootstrap script will materialize a bare repo at
|
||||
`${devEnv.root}/repos/lnbits.git` and check out one worktree per
|
||||
declared entry. Navigation helpers (`cd`-shortcuts à la omnixy's
|
||||
`lb dev`) get generated from the same project list.
|
||||
|
||||
## Contributing
|
||||
|
||||
Iteration happens under the sandboxed-claude policy from omnixy's
|
||||
`scripts/sandbox-claude.sh` — a per-launch `.claude/settings.json`
|
||||
that allows nix/git/inspection and hard-denies sudo, push/remote,
|
||||
container engines, etc. Substantive scaffolding work happens in that
|
||||
sandbox; promotion (`git push`) is done from the main shell after
|
||||
|
|
|
|||
Reference in a new issue