Add Rule 2.5: CLI must stay in sync with Web UI

- New mandatory rule: Every web API endpoint must have matching CLI
- Added verification process for API-to-CLI coverage
- Added ongoing maintenance checklist
- Added coverage matrix template
This commit is contained in:
Matt Bruce 2026-02-21 17:31:11 -06:00
parent bcd9ef35f4
commit a7d40fd5c9

View File

@ -60,6 +60,46 @@
--- ---
### 2.5. CLI MUST STAY IN SYNC WITH WEB UI — ALWAYS
**FORBIDDEN:** Web UI has features the CLI can't access
**REQUIRED:** Every web API endpoint has a matching CLI command
**The Rule:**
- Web UI can do it → CLI can do it. No exceptions.
- When adding a web feature, add the CLI command in the SAME commit
- When modifying an API, update the CLI script in the SAME commit
- CLI is not an afterthought — it's part of the feature
**Verification Process (BEFORE committing any API change):**
```bash
# 1. List all API endpoints in the web app
find src/app/api -name "route.ts" | xargs grep -l "export async function"
# 2. Check that each endpoint has a CLI equivalent
# GET /api/items → ./scripts/crud.sh list
# POST /api/items → ./scripts/crud.sh create
# PATCH /api/items/[id] → ./scripts/crud.sh update
# POST /api/items/[id]/attachments → ./scripts/crud.sh attach
# 3. Test the CLI actually works
./scripts/crud.sh list
./scripts/crud.sh create '{"title":"Test"}'
# 4. If any API endpoint lacks CLI coverage → DO NOT COMMIT
```
**Feature Completion Checklist:**
- [ ] Web UI feature implemented
- [ ] API endpoint created/modified
- [ ] CLI command added/updated to match
- [ ] CLI tested and working
- [ ] README.md updated with new CLI usage
- [ ] All changes in SINGLE commit
**Why:** If the web can do it but CLI can't, I can't automate it. I shouldn't need to open a browser to do something the web can do programmatically.
---
### 3. NEVER CLOSE/MARK TASKS AS DONE — MATT DOES THIS ### 3. NEVER CLOSE/MARK TASKS AS DONE — MATT DOES THIS
**FORBIDDEN:** Changing task status to "done" or "complete" **FORBIDDEN:** Changing task status to "done" or "complete"
**ALLOWED:** Attaching files, updating descriptions, adding comments **ALLOWED:** Attaching files, updating descriptions, adding comments
@ -519,11 +559,52 @@ task_id=$(./scripts/crud.sh create '{"title":"Test"}' | jq -r '.id')
- [ ] Test: Can I list items via CLI without browser? - [ ] Test: Can I list items via CLI without browser?
- [ ] Test: Can I attach a file via CLI? - [ ] Test: Can I attach a file via CLI?
- [ ] Test: Can I verify operations via CLI get? - [ ] Test: Can I verify operations via CLI get?
- [ ] **API-to-CLI Coverage Verified:** Every API endpoint has matching CLI command
**If any check fails → NOT READY.** **If any check fails → NOT READY.**
**Template to copy:** `/Users/mattbruce/.openclaw/workspace/CLI_README_TEMPLATE.md` **Template to copy:** `/Users/mattbruce/.openclaw/workspace/CLI_README_TEMPLATE.md`
### Ongoing Development: CLI Sync Maintenance
**Rule 2.5 in practice:** When adding ANY web feature:
```bash
# 1. BEFORE committing, audit API surface area
find src/app/api -name "route.ts" -exec basename $(dirname {}) \; | sort > /tmp/api-endpoints.txt
# 2. Audit CLI coverage
grep -E "^(cmd_|function cmd)" scripts/*.sh | sed 's/.*cmd_//' | sed 's/(.*//' | sort -u > /tmp/cli-commands.txt
# 3. Compare - if API has endpoints CLI doesn't cover → ADD THEM
# Example mismatch:
# API: POST /api/tasks/natural (natural language create)
# CLI: Only has cmd_task_create (manual create)
# → Must add cmd_task_natural to gantt.sh
# 4. Update README.md with new commands
# 5. Test new CLI command works
# 6. Commit web + CLI changes together
```
**Coverage Matrix (maintain in scripts/README.md):**
| API Endpoint | Method | CLI Command | Status |
|--------------|--------|-------------|--------|
| /api/tasks | GET | task list | ✅ |
| /api/tasks | POST | task create | ✅ |
| /api/tasks/natural | POST | task natural | ✅ |
| /api/tasks | DELETE | task delete | ✅ |
| ... | ... | ... | ... |
**Monthly Audit Task:**
Run this during a heartbeat to ensure sync:
```bash
cd /Users/mattbruce/Documents/Projects/OpenClaw/Web/gantt-board
./scripts/audit-cli-coverage.sh # Script that compares API vs CLI
```
**If CLI lags behind API → File a bug task immediately.**
## Quick Commands ## Quick Commands
```bash ```bash