diff --git a/.specify/SPEC_template.md b/.specify/SPEC_template.md deleted file mode 100644 index ddd124f0a..000000000 --- a/.specify/SPEC_template.md +++ /dev/null @@ -1,79 +0,0 @@ -# Feature Spec: [FEAT-XXX] - Short Descriptive Title - -**Milestone:** [e.g. MVP Core / Performance & Polish / Extension Framework] -**Priority:** Must-have / Should-have / Nice-to-have -**Spec Owner:** [Your Name / AI Agent Name] -**Status:** Draft → Under Review → Approved → Implemented → Verified - -## 1. Purpose & User Story - -As a [user type], I want [goal] so that [benefit]. - -_(One clear sentence. Keep it concise.)_ - -## 2. Functional Requirements - -- [ ] REQ-1: [Clear, testable description] -- [ ] REQ-2: ... -- [ ] REQ-3: ... - -_(List what the feature must do. Make each item verifiable.)_ - -## 3. Non-Functional Requirements - -- **Performance:** [e.g. Latency < 800ms at p95, max 5k tokens, etc.] -- **Security / Safety:** [e.g. Input validation, no raw errors to user, etc.] -- **Compatibility:** [e.g. Works with all existing wallet backends, no breaking changes for extensions] -- **UI/UX:** [e.g. Follows existing Quasar/Vue patterns in wallet.js] -- **Other:** [cost, scalability, accessibility, etc.] - -## 4. Technical Approach (Optional – recommended for complex features) - -- Proposed solution: [e.g. Extend existing CRUD in lnbits/core/, new extension, middleware change, etc.] -- Key files to modify: [list expected files] -- New dependencies: [none / specific package + version] -- Migration / Database changes: [yes/no + description] - -## 5. Success Criteria & Verification - -**Must pass all of these to be accepted:** - -- [ ] All functional requirements (REQ-\*) implemented and tested -- [ ] Non-functional requirements met (performance, security, etc.) -- [ ] Relevant tests pass: `make test-unit`, `make test-api`, `make test-regtest` (as applicable) -- [ ] `make check` passes (ruff, mypy, pyright, prettier, checkbundle) -- [ ] Constitution compliance: All changes respect CONSTITUTION.md -- [ ] Backward compatibility: No breakage for existing extensions or wallet backends -- [ ] Documentation updated (if applicable: README, OpenAPI, inline comments) - -**Additional Tests / Edge Cases:** - -- [ ] Test invalid inputs / error paths -- [ ] Test with FakeWallet and at least one real backend -- [ ] Test with multiple extensions installed - -## 6. Safety & Risk Assessment - -- Potential risks: [e.g. Payment flow impact, key exposure, extension conflicts] -- Mitigation: [how addressed] -- Security review needed: [yes/no] - -## 7. Implementation Notes (for AI / Developer) - -- Style to match: Existing code patterns in `lnbits/core/` and `wallet.js` -- Surgical changes only (per AGENTS.md) -- Any known gotchas or dependencies on other features: - -## 8. Acceptance Checklist (Sign-off) - -- [ ] Spec reviewed and approved by project owner -- [ ] Implementation completed -- [ ] Verification steps passed -- [ ] PR created with link to this spec -- [ ] Constitution & AGENTS.md compliance confirmed - ---- - -**Created:** [Date] -**Last Updated:** [Date] -**Approved By:** [Name / "Approved"] diff --git a/AGENTS.md b/AGENTS.md index 6e68b3379..eb4aba853 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,122 +1,60 @@ -# AGENTS.md - Instructions for All AI Coding Agents +# AGENTS.md - AI Coding Agent Guide for LNbits -This file is the **master instruction manual** for any AI agent (Grok, Claude, Cursor, Aider, etc.) working on LNbits. +This file guides AI coding agents working on LNbits. Keep changes small, verified, and aligned with existing project patterns. -## 1. Core Rule (Never Break This) +## Core Behavior -**You MUST read and strictly follow `CONSTITUTION.md` before doing any planning, coding, refactoring, or suggesting changes.** +- Think before coding. State material assumptions. Ask when ambiguity affects correctness, security, payments, wallets, or data migrations. +- Prefer the simplest implementation that solves the request. +- Make surgical changes. Every changed line should trace back to the task. +- Do not refactor, reformat, rename, or clean adjacent code unless required. +- Remove only dead code or imports created by your own changes. +- Define success criteria for non-trivial work and verify them before reporting done. -- Every single change, feature, extension, or fix **must comply** with the Constitution. -- If you detect a violation (in new code or existing code), you **must** flag it immediately and propose a fix or ask for clarification. -- Constitution > any other instruction (including this file, user prompts, or previous conversations). +## LNbits Architecture -## 2. Mandatory Development Workflow +- Keep core lean. Prefer/assess extensions for non-core features. +- Preserve compatibility with existing extensions and wallet backends. +- Follow existing patterns in `lnbits/core`, `lnbits/wallets`, `lnbits/extensions`, and frontend code. +- Use existing CRUD, services, settings, and migration patterns. +- Do not edit generated files, bundled vendor files, or unrelated extension code. -For **any non-trivial task** (new feature, bug fix, refactor, extension change): +## Security-Sensitive Areas -1. **Constitution Check** – Re-read relevant sections of `CONSTITUTION.md` -2. **Feature Spec Check** – If a spec exists in `.specify/`, follow it exactly. If none exists, ask the user for clarification or propose a minimal spec. -3. **Think Step-by-Step** – Follow the "Think Before Coding" and "Simplicity First" guidelines below. -4. **Surgical Changes** – Only touch what is necessary. -5. **Implement** -6. **Verify** – Run relevant tests (`make test-unit`, `make test-api`, etc.), `make check`, and confirm compliance. -7. **Report** – Always include a clear summary. +Be extra cautious with payments, wallet balances, admin routes, keys, LNURL, Bolt11, funding sources, migrations, and authentication. -Use the following response format: +Do not expose raw stack traces or sensitive values. Do not add synchronous blocking work in hot async paths without justification. -```markdown -## Constitution & Spec Compliance +## Commands and Verification -- Relevant Constitution sections checked: [list or quote key rules] -- Feature Spec followed: [yes / no / proposed] +Read `Makefile` before running project commands. -## Assumptions & Plan +Use Makefile targets instead of hand-written commands when available: -- Assumptions: ... -- Plan: - 1. ... - 2. ... -- Tradeoffs considered: ... +- `make check` for full checks. +- `make test-unit` for unit tests. +- `make test-api` for API tests. +- `make test-wallets` for wallet tests. +- `make checkbundle` when bundled frontend assets may be affected. +- `make format` only when formatting is intended. -## Changes Made +Do not run `make test` by default. Use the targeted tests available in the Makefile that are related to the work done, unless the user explicitly asks for broader test coverage. -- Files changed: ... -- Summary of modifications: +## Dependencies -## Verification +Do not add dependencies without approval. If approved, update the correct project files and explain why the dependency is necessary. -- [ ] Passes `make check` -- [ ] Relevant tests pass (`make test-xxx`) -- [ ] Complies with Constitution -- [ ] Surgical & minimal (no unrelated changes) -``` +## Maintenance -## 3. Behavioral Guidelines (Merged & Project-Specific) +LNbits maintainers own this file. They should update it when the development workflow, architecture, or verification commands materially change. -**Think Before Coding** +Do not edit, commit, push, or include changes to this file in a PR as part of normal feature work unless the user explicitly asks for `AGENTS.md` changes. -- Don't assume. Don't hide confusion. Surface tradeoffs. -- State assumptions explicitly. If uncertain, ask. -- If multiple interpretations exist, present them — don't pick silently. -- If something is unclear (especially regarding wallets, extensions, or funding sources), stop and ask. +## Reporting -**Simplicity First** +When finished, report: -- Minimum code that solves the problem. Nothing speculative. -- No features beyond what was asked. -- No abstractions for single-use code. -- Respect LNbits' lean core philosophy: new functionality should preferably go into an **extension** unless it truly belongs in core. - -**Surgical Changes** - -- Touch only what you must. Clean up only your own mess. -- Match existing style (Python: Black + Ruff rules; JS: Prettier). -- Do not "improve" or refactor adjacent code unless explicitly asked. -- When editing, remove only imports/variables/functions made unused **by your changes**. -- Never delete pre-existing dead code unless instructed. - -**Goal-Driven Execution** - -- Transform tasks into verifiable goals. -- For tests: Write or update tests first when fixing bugs or adding behavior. -- Always consider impact on existing extensions and multiple wallet backends (LND, CLN, Boltz, VoidWallet, etc.). - -## 4. LNbits-Specific Rules - -- **Extensions First**: Core should remain lean. Prefer implementing new features as extensions unless they are fundamental to wallets, security, or the API. -- **Testing**: Use `FakeWallet` for unit/API tests. Regtest tests for full Lightning flows. Never break existing test targets in the Makefile. -- **Dependencies**: Never add new dependencies without updating `pyproject.toml` and getting approval. -- **Frontend**: JS/Vue code (e.g. `wallet.js`) must follow existing patterns and pass `make checkbundle` when static files are affected. -- **Database / Migrations**: Do not make raw SQL changes. Use existing CRUD/services and migration tooling. -- **Security**: Be extremely cautious with anything touching payments, keys, LNURL, Bolt11, or admin routes. -- **Tools**: Use `uv run` for all commands. Prefer Makefile targets (`make format`, `make check`, `make test-xxx`). -- **Generated Files**: Never modify gRPC files or other generated code. - -## 5. Forbidden Behaviors - -- Ignoring Constitution rules to "be helpful" -- Large refactors without a spec or explicit request -- Adding features "for future use" -- Breaking backward compatibility for extensions or existing wallet backends -- Committing code that fails `make check` or relevant tests -- Exposing raw errors/stack traces to users -- Using synchronous code in hot async paths without justification - -## 6. How to Handle This File + Constitution - -When the user gives you a task, start your response with: - -> Following LNbits CONSTITUTION.md and AGENTS.md... - -Then proceed with the structured format above. - ---- - -**These guidelines are working if:** - -- Fewer unnecessary changes appear in diffs -- Clarifying questions come **before** implementation -- All changes respect the lean, extension-first, security-first nature of LNbits -- Tests and `make check` continue to pass - -Last Updated: April 2026 +- Summary of what changed. +- Files touched. +- Makefile targets or checks run. +- Anything not verified and why. diff --git a/CONSTITUTION.md b/CONSTITUTION.md deleted file mode 100644 index 53d62e021..000000000 --- a/CONSTITUTION.md +++ /dev/null @@ -1,136 +0,0 @@ -# CONSTITUTION.md - -This is the immutable constitution of the LNbits project. -Every feature spec, code change, refactor, extension, or decision by humans or AI agents **must comply** with this document. -Changes to this file require explicit approval from the project owner/maintainers. - -## 1. Project Overview - -**Project Name:** LNbits -**Core Purpose:** Free and open-source Lightning wallet and accounts system. A lightweight Python server that sits on top of any Lightning funding source, providing safe isolated wallets, a clean REST API, and a powerful extension system for adding features rapidly. -**Target Users:** Individuals, communities, merchants, developers, and enterprises building on Bitcoin/Lightning (self-hosted or as part of larger stacks). -**High-Level Success Criteria:** - -- Reliable multi-wallet Lightning accounting with any backend (20+ supported funding sources) -- Secure, extensible via 60+ extensions without bloating core -- High code quality, test coverage, and backward compatibility for extensions -- Production-ready performance and security for real Bitcoin value - -**Version:** 1.5.4 - -## 2. Technology Stack (Strict) - -- **Language:** Python >=3.10, <3.13 (strictly enforced via `pyproject.toml`) -- **Framework:** FastAPI + Starlette (backend API) -- **Frontend:** Vue.js + Quasar framework, with bundled static assets -- **Database:** SQLite (aiosqlite) by default, PostgreSQL (asyncpg/psycopg2) supported via `LNBITS_DATABASE_URL` -- **Async Runtime:** uvloop preferred -- **Dependency Management:** uv + pyproject.toml (Hatchling build backend). Use `uv run` for all commands. -- **Wallet Backends:** Abstracted via `lnbits.wallets` – support for LND, Core Lightning, Phoenixd, Boltz, Breez SDK, Liquid, VoidWallet fallback, etc. New backends must follow existing abstraction. -- **Other Key Libs:** SQLAlchemy, Pydantic (v1), Loguru, Jinja2, LNURL, Bolt11, etc. (see `pyproject.toml` for pinned versions) -- **Build/Frontend Tools:** npm for bundling (Quasar/Vue), Prettier for JS/CSS (check Makefile targets) - -**Forbidden:** - -- Adding new top-level dependencies without updating `pyproject.toml` **and** team approval -- Using synchronous blocking calls in async paths (except where explicitly justified) -- Direct database queries outside of CRUD layers or core services -- Modifying generated files (e.g., gRPC files in wallets/boltz_grpc_files or lnd_grpc_files) - -## 3. Architecture & Code Organization (Mandatory Rules) - -- **Core Principle:** Modular monolith with heavy emphasis on **extensions**. All non-core features must live in extensions (installed via `lnbits/extensions`). Core stays lean. -- **Backend Structure:** - - `lnbits/core/` for core models, CRUD, services, routers, tasks - - `lnbits/wallets/` for funding source abstractions - - `lnbits/extensions/` for installed/upgradeable extensions (do not commit large extensions to core repo) - - `lnbits/static/` for bundled frontend assets (managed via npm bundle) -- **Key Rules:** - - Use dependency injection and FastAPI routers properly - - Extensions register routes/tasks via `register_ext_routes` / `register_ext_tasks` - - Database migrations handled centrally (extension-specific migrations) - - All new endpoints must be under proper versioning/prefixing where applicable - - Frontend: Vue 2/Quasar components in `wallet.js` style (or updated) – keep reactive, use LNbits.utils helpers - - No circular imports; respect existing middleware order (e.g., InstalledExtensionMiddleware before ExtensionsRedirectMiddleware) - -**Exclusions** (do not lint/format these): - -- `lnbits/extensions/`, `lnbits/upgrades/`, generated gRPC files, static/vendor bundles - -## 4. Code Quality & Style - -- **Formatting & Linting:** - - Python: Black (line-length 88), Ruff (with selected rules: F, E, W, I, A, C, N, UP, RUF, B, S), MyPy (strict where possible), Pyright - - JS/Frontend: Prettier - - Run via Makefile: `make format` and `make check` -- **Type Checking:** MyPy + Pyright enforced on `lnbits/`, `tests/`, `tools/` -- **Testing Requirements:** - - Unit, API, wallet, and regtest tests via pytest (see Makefile targets) - - New core code or critical paths: high coverage expected (`--cov=lnbits`) - - Extensions should include their own tests where possible -- **Error Handling & Logging:** Use Loguru with structured context. Never expose raw stack traces to end users. Graceful fallbacks (e.g., VoidWallet on funding source failure). -- **Pre-commit:** Strongly recommended (`make install-pre-commit-hook`) -- **Bundle Integrity:** Frontend bundles must pass `make checkbundle` before commits affecting static files. - -## 5. AI / LLM Usage Standards (if any agents or future AI features are added) - -- Any new AI-powered features (e.g., via extensions) must use structured outputs (Pydantic/JSON mode) -- Store prompts/templates versioned in the extension -- Prefer deterministic behavior for financial/security paths (low temperature) -- All AI outputs involving value/money must be validated server-side -- Safety: Never allow untrusted model output to influence payments, wallet balances, or admin actions without guardrails - -## 6. Safety, Security & Ethics - -- **Critical:** Handle real Bitcoin/Lightning value → security-first mindset -- Per-wallet isolation with separate admin/invoice/read keys -- Rate limiting (SlowAPI) and IP blocking middleware mandatory -- Sanitize all user inputs; validate LNURL, Bolt11, etc. -- PII: Minimal collection; respect privacy (no unnecessary logging of sensitive data) -- Funding source failures: Graceful degradation to VoidWallet + clear logging -- Extensions: Hash-verified installs for vetted extensions; careful with custom extension paths -- Audit logging via AuditMiddleware -- Forbidden: Hard-coded secrets, insecure subprocess calls without review, SQL injection risks (use SQLAlchemy properly) - -## 7. Performance & Cost Budgets - -- Keep core lightweight – extensions handle heavy features -- Async-first (uvloop, asyncpg/aiosqlite) -- Reasonable retry logic for funding source connections (see `check_funding_source`) -- Frontend: Optimized bundles (checkbundle enforced) -- No unnecessary blocking operations in request paths - -## 8. Development Workflow (Spec-Driven where possible) - -- **All significant changes** should follow Spec-Driven Development: - - Create/update Feature Spec in `.specify/` folder (or equivalent) - - Reference this Constitution in every spec and PR -- Use Makefile targets for format/check/test -- Tests run with `FakeWallet` by default for unit/API; regtest for full flows -- PRs must: - - Pass `make check` and relevant tests - - Include Constitution compliance notes (via AGENTS.md/CLAUDE.md) - - Not break existing extensions or wallet backends -- Branching: Protect main; use feature branches -- Extensions: Develop separately; core repo focuses on framework stability - -## 9. Decision Hierarchy (What Takes Precedence) - -1. This Constitution -2. Approved Feature Spec / Milestone -3. Existing tests and backward compatibility (especially for extensions and wallet backends) -4. Project maintainers / owner decision -5. Everything else (including helpful AI suggestions) - -If conflict: Stop, document the issue, and seek clarification from maintainers. - -## 10. Amendment Process - -- This Constitution can only be changed with explicit approval from project maintainers. -- All changes must be dated, versioned, and reflected in `AGENTS.md`. -- Minor clarifications can be proposed via PR with justification. - ---- - -**Last Updated:** April 2026 (based on v1.5.4) -**Owner/Maintainers Approval:** LNbits Team