fix: tighten agents file (#3966)
This commit is contained in:
Tiago Vasconcelos
@@ -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"]
|
||||
@@ -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.
|
||||
|
||||
-136
@@ -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
|
||||
Reference in New Issue
Block a user