Skip to content

Commit d7291c4

Browse files
allanbatistaallanbatista
committed
docs: update documentation with new commands and testing requirements
AGENTS.md: - Add non-negotiable testing requirements section - Document test structure and patterns - Add all new commands documentation README.md: - Add documentation for all new commands - Update command reference
1 parent 3786dad commit d7291c4

2 files changed

Lines changed: 401 additions & 2 deletions

File tree

‎AGENTS.md‎

Lines changed: 192 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ ai-linux-dev-utilities/
1010
│ ├── ab # Main command (dispatcher)
1111
│ ├── ab-config # Configuration CLI wrapper
1212
│ ├── ab-git # Sub-dispatcher for git commands
13+
│ ├── ab-models # Models listing wrapper
1314
│ ├── ab-util # Sub-dispatcher for utilities
1415
│ └── ab-prompt # Prompt wrapper
1516
│
@@ -21,10 +22,16 @@ ai-linux-dev-utilities/
2122
│ ├── commands/ # CLI commands
2223
│ │ ├── __init__.py
2324
│ │ ├── auto_commit.py # Generate commit messages via LLM
25+
│ │ ├── branch_name.py # Generate branch names from descriptions
26+
│ │ ├── changelog.py # Generate changelog from commits
27+
│ │ ├── config_cli.py # Configuration management CLI
28+
│ │ ├── explain.py # Explain code, errors, or concepts
29+
│ │ ├── gen_script.py # Generate scripts from descriptions
30+
│ │ ├── models.py # List available LLM models
2431
│ │ ├── pr_description.py # Generate PR title/description via LLM
25-
│ │ ├── rewrite_history.py # Rewrite commit messages via LLM
2632
│ │ ├── prompt.py # CLI to send context to OpenRouter
27-
│ │ └── config_cli.py # Configuration management CLI
33+
│ │ ├── resolve_conflict.py # Resolve merge conflicts via LLM
34+
│ │ └── rewrite_history.py # Rewrite commit messages via LLM
2835
│ └── utils/
2936
│ └── __init__.py
3037
│
@@ -48,6 +55,77 @@ ai-linux-dev-utilities/
4855

4956
User settings are stored in `~/.ab/config.json`. Call history in `~/.ab/history/`.
5057

58+
---
59+
60+
## Testing Requirements (NON-NEGOTIABLE)
61+
62+
**Tests are a mandatory requirement for all code changes.** This is not optional.
63+
64+
### Rules
65+
66+
1. **Every new command MUST have integration tests** in `tests/integration/test_<command>.py`
67+
2. **Every new utility function MUST have unit tests** in `tests/unit/`
68+
3. **All tests MUST pass before any code is considered complete**
69+
4. **PRs without tests will NOT be accepted**
70+
71+
### Test Structure
72+
73+
```
74+
tests/
75+
├── conftest.py # Shared fixtures (mock_git_repo, mock_config, etc.)
76+
├── unit/ # Unit tests for isolated functions
77+
│ ├── test_config.py
78+
│ ├── test_config_cli.py
79+
│ └── test_utils.py
80+
└── integration/ # Integration tests for commands
81+
├── test_auto_commit.py
82+
├── test_branch_name.py
83+
├── test_changelog.py
84+
├── test_explain.py
85+
├── test_gen_script.py
86+
├── test_pr_description.py
87+
├── test_resolve_conflict.py
88+
└── test_rewrite_history.py
89+
```
90+
91+
### Running Tests
92+
93+
```bash
94+
# Run all tests
95+
python -m pytest tests/ -v
96+
97+
# Run specific test file
98+
python -m pytest tests/integration/test_gen_script.py -v
99+
100+
# Run with coverage
101+
python -m pytest tests/ --cov=src/ab_cli --cov-report=term-missing
102+
```
103+
104+
### What to Test
105+
106+
For each command, test:
107+
- **Helper functions** (parsing, validation, git operations)
108+
- **main() entry point** with different flags
109+
- **Error cases** (not in git repo, file not found, etc.)
110+
- **Edge cases** (empty input, special characters, etc.)
111+
112+
### Test Patterns
113+
114+
Use fixtures from `conftest.py`:
115+
```python
116+
def test_example(self, mock_git_repo, monkeypatch, mock_config):
117+
monkeypatch.chdir(mock_git_repo)
118+
# ... test code
119+
```
120+
121+
Mock LLM calls to avoid external dependencies:
122+
```python
123+
with patch('ab_cli.commands.xxx.find_prompt_command') as mock:
124+
mock.side_effect = FileNotFoundError('abort test')
125+
```
126+
127+
---
128+
51129
## Available Commands
52130

53131
### ab (unified command)
@@ -61,6 +139,7 @@ ab util <command> # General utilities
61139
# Root commands:
62140
ab prompt # Send context to LLM (OpenRouter)
63141
ab config # Manage configuration
142+
ab models # List available LLM models
64143
ab help # Show help
65144
```
66145

@@ -75,29 +154,85 @@ ab config edit # Open config in editor
75154
ab config list-keys # List all available config keys
76155
```
77156

157+
### ab models (list LLM models)
158+
List and explore available LLM models from OpenRouter API.
159+
```bash
160+
ab models # List all models (table format)
161+
ab models list # Same as above
162+
ab models list --free # Show only free models
163+
ab models list --search <term> # Search by name/description
164+
ab models list --context-min <n> # Filter by minimum context length
165+
ab models list --modality <type> # Filter by modality (text, image, audio, video)
166+
ab models list --sort <field> # Sort by: name, context, price
167+
ab models list --limit <n> # Limit results (default: 50)
168+
ab models list --json # Output as JSON
169+
ab models info <model-id> # Show detailed info for a model
170+
ab models info <model-id> --json # Model details as JSON
171+
```
172+
173+
**Examples:**
174+
```bash
175+
ab models list --free --search llama # Free Llama models
176+
ab models list --context-min 128000 # Models with 128k+ context
177+
ab models list --modality image # Vision models
178+
ab models info openai/gpt-4o # Details for GPT-4o
179+
```
180+
78181
### ab git (git commands)
79182
```bash
80183
ab git auto-commit # Generate commit message via LLM
184+
ab git branch-name # Generate branch name from task description
185+
ab git changelog # Generate changelog from commits
81186
ab git pr-description # Generate PR title/description via LLM
187+
ab git resolve-conflict # Resolve merge conflicts via LLM
82188
ab git rewrite-history # Rewrite commit messages via LLM
83189
ab git help # Show category help
84190
```
85191

86192
### ab util (utilities)
87193
```bash
194+
ab util explain # Explain code, errors, or concepts via LLM
195+
ab util gen-script # Generate scripts from natural language
88196
ab util passgenerator # Secure password generator
89197
ab util help # Show category help
90198
```
91199

92200
### ab git auto-commit
93201
Automatically generate commit messages by analyzing staged diff.
202+
203+
**Protected branch detection**: When on `master` or `main`, auto-commit will suggest creating a feature branch before committing.
204+
94205
```bash
95206
ab git auto-commit # Generate message and confirm
96207
ab git auto-commit -a # Add all files (git add -A)
97208
ab git auto-commit -y # Skip confirmation
98209
ab git auto-commit -a -y # Add all and commit without confirmation
99210
```
100211

212+
### ab git branch-name
213+
Generate branch names from task descriptions using LLM.
214+
```bash
215+
ab git branch-name "fix login bug" # Suggest: fix/login-bug
216+
ab git branch-name "add user authentication" # Suggest: feature/add-user-authentication
217+
ab git branch-name "JIRA-123: implement payment" # Suggest: feature/JIRA-123-implement-payment
218+
ab git branch-name -c "new feature" # Create and checkout the branch
219+
ab git branch-name --prefix fix "button alignment" # Force prefix: fix/button-alignment
220+
ab git branch-name -y "task description" # Skip confirmation when creating
221+
```
222+
223+
### ab git changelog
224+
Generate changelog/release notes from commits using LLM.
225+
```bash
226+
ab git changelog # Since last tag to HEAD
227+
ab git changelog v1.0.0..v2.0.0 # Between two tags
228+
ab git changelog HEAD~10..HEAD # Last 10 commits
229+
ab git changelog --format markdown # Markdown output (default)
230+
ab git changelog --format plain # Plain text output
231+
ab git changelog --format json # JSON output
232+
ab git changelog -c # Group by type (feat/fix/chore)
233+
ab git changelog -o CHANGELOG.md # Write to file
234+
```
235+
101236
### ab git pr-description
102237
Generate PR title and description by analyzing commits and diff relative to base branch.
103238
```bash
@@ -129,6 +264,21 @@ ab git rewrite-history --smart # LLM decides which need rewriting
129264
- Warning if commits were already pushed (requires force push)
130265
- `--dry-run` mode for full preview
131266

267+
### ab git resolve-conflict
268+
Analyze and resolve merge conflicts using LLM.
269+
```bash
270+
ab git resolve-conflict # Interactive mode for all conflicted files
271+
ab git resolve-conflict file.py # Resolve specific file
272+
ab git resolve-conflict -y # Auto-apply suggestions
273+
ab git resolve-conflict --dry-run # Preview suggestions only
274+
```
275+
276+
**Features:**
277+
- Detects conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
278+
- Extracts both versions with surrounding context
279+
- Suggests intelligent merged resolution
280+
- Option to edit manually before applying
281+
132282
### ab prompt
133283
Send file context to OpenRouter and return LLM response.
134284
```bash
@@ -140,6 +290,46 @@ ab prompt --only-output -p "hi" # Return only response
140290
ab prompt --set-default-model "model" # Set default model
141291
```
142292

293+
### ab util explain
294+
Explain code, errors, or technical concepts using LLM with automatic context gathering.
295+
```bash
296+
ab util explain file.py # Explain entire file
297+
ab util explain file.py:42 # Explain specific line
298+
ab util explain file.py:10-50 # Explain line range
299+
ab util explain "error: ECONNREFUSED" # Explain error message
300+
ab util explain --concept "dependency injection" # Explain concept
301+
echo "stack trace" | ab util explain - # Explain from stdin
302+
ab util explain --history 20 "error" # Include last 20 bash commands as context
303+
ab util explain --with-files "not found" # Include directory listing
304+
ab util explain -v "complex topic" # Verbose/detailed explanation
305+
```
306+
307+
**Context gathering:**
308+
- `--history N`: Include last N lines from bash history
309+
- `--with-files`: Include `ls -la` output and auto-read files mentioned in errors
310+
- `--context-dir PATH`: Specify directory for context gathering
311+
312+
### ab util gen-script
313+
Generate bash/python scripts from natural language descriptions.
314+
315+
**Default**: Generates minimal one-liner commands. Use `--full` for complete scripts.
316+
317+
```bash
318+
ab util gen-script "list all files larger than 100MB" # One-liner output
319+
ab util gen-script --full "backup database" # Full script with error handling
320+
ab util gen-script --type cron "backup daily at 3am" # Cron-suitable script
321+
ab util gen-script --lang python "parse CSV sum col 3" # Python one-liner
322+
ab util gen-script -o backup.sh "compress and upload" # Auto-full when saving
323+
ab util gen-script --run "show disk usage" # Execute immediately
324+
```
325+
326+
**Options:**
327+
- `--lang`: Script language (bash, python, sh, perl, ruby, node)
328+
- `--type`: Script type (script, cron, oneshot - default: oneshot)
329+
- `--full`: Generate complete script with error handling
330+
- `-o`: Output file path (auto-enables full mode)
331+
- `--run`: Execute the generated script immediately
332+
143333
### ab util passgenerator
144334
Generate secure passwords with validations.
145335
```bash

0 commit comments

Comments
 (0)