8826d62bcc
- maubot.nix: Declarative bot framework with plugin deployment - backup.nix: Local backup service for Matrix/bridge data - sna-instagram-bot: Instagram content bridge plugin - beads: Issue tracking workflow integrated - spec 004: Browser-based dev environment design - nixpkgs bump: Oct 22 → Dec 2 - Fix maubot health check (401 = healthy)
49 lines
3.3 KiB
Markdown
49 lines
3.3 KiB
Markdown
# Beads Issue Tracking
|
|
|
|
**Session start**: Run `bd ready` to see available work.
|
|
|
|
## Commands
|
|
- `bd ready` - Issues with no blockers
|
|
- `bd show <id>` - Issue details
|
|
- `bd update <id> --status=in_progress` - Claim work
|
|
- `bd close <id>` - Complete work
|
|
- `bd create --title="..." --type=task|bug|feature` - New issue
|
|
- `bd dep add <issue> <depends-on>` - Add dependency
|
|
|
|
## Session End
|
|
Before finishing: `git status`, `git add`, `git commit`. This is an ephemeral branch - merge to main locally.
|
|
|
|
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- `configuration.nix` holds shared system defaults; adjust service toggles in host overlays instead of editing it directly.
|
|
- `hosts/ops-jrz1.nix` and `hosts/ops-jrz1-vm.nix` override environment-specific networking, secrets, and hardware details; mirror changes across both when possible.
|
|
- `modules/` contains composable NixOS modules (`matrix-continuwuity.nix`, `mautrix-*.nix`, `security/*`); keep new modules kebab-cased and expose options via `lib.mkOption`.
|
|
- `scripts/` provides sanitization utilities. Stage external imports under `staging/`, run `./scripts/sanitize-files.sh SRC staging/modules`, then promote files into `modules/` once validation passes.
|
|
- `specs/` and `docs/` capture design intent and runbooks; update the relevant spec when changing feature scope.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `nix flake check` validates module wiring, options, and formatting before review.
|
|
- `nix build .#nixosConfigurations.ops-jrz1` produces the deployable system closure; use this to catch evaluation regressions.
|
|
- `nixos-rebuild switch --flake .#ops-jrz1 --target-host root@ops-jrz1` deploys to the VPS; replace the target host when testing elsewhere.
|
|
- `./scripts/validate-sanitization.sh modules/` ensures redacted content before commit; rerun after manual edits to sanitized files.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Prefer two-space indentation in Nix files; align attribute sets and option blocks for readability.
|
|
- Use `lowerCamelCase` for option names, kebab-case for file names, and leave explanatory comments above non-obvious logic paths only.
|
|
- Format Nix with `nix fmt` (nixpkgs-fmt) or equivalent before committing to keep diffs minimal.
|
|
|
|
## Testing Guidelines
|
|
- Treat `nix flake check` as the minimum gate; add targeted VM tests in `hosts/ops-jrz1-vm.nix` when introducing new services.
|
|
- Name ad-hoc verification scripts under `scripts/local-*` and avoid committing transient debug helpers.
|
|
- Capture manual verification steps in `docs/worklogs/` immediately after deploys for traceability.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- Follow the existing Git log style: single-line, capitalized summaries in ~70 characters (e.g., `Tighten bridge secret validation`).
|
|
- Reference related specs or worklogs in the body, and list `nix flake check` (and any VM smoke tests) under a short "Validation" block.
|
|
- PRs should link the tracked task, summarize scope, highlight sanitization steps, and mention any secrets or infra touchpoints reviewers must provision.
|
|
|
|
## Security & Secrets Handling
|
|
- Never commit decrypted material; use `sops secrets/secrets.yaml` for edits and confirm `git status` shows only encrypted blobs.
|
|
- Replace real domains, IPs, and tokens with repository-safe placeholders. When importing upstream configs, run the sanitize and validate scripts before staging changes.
|