107 lines
2.0 KiB
Markdown
107 lines
2.0 KiB
Markdown
# Script Quality Criteria
|
|
|
|
Scripts provide deterministic reliability and token efficiency.
|
|
|
|
## When to Include Scripts
|
|
|
|
- Same code rewritten repeatedly
|
|
- Deterministic operations needed
|
|
- Complex transformations
|
|
- External tool integrations
|
|
|
|
## Cross-Platform Requirements
|
|
|
|
**Prefer:** Node.js or Python
|
|
**Avoid:** Bash scripts (not well-supported on Windows)
|
|
|
|
If bash required, provide Node.js/Python alternative.
|
|
|
|
## Testing Requirements
|
|
|
|
**Mandatory:** All scripts must have tests
|
|
|
|
```bash
|
|
# Run tests before packaging
|
|
python -m pytest scripts/tests/
|
|
# or
|
|
npm test
|
|
```
|
|
|
|
Tests must pass. No skipping failed tests.
|
|
|
|
## Environment Variables
|
|
|
|
Respect hierarchy (first found wins):
|
|
|
|
1. `process.env` (runtime)
|
|
2. `$HOME/.opencode/skills/<skill-name>/.env` (skill-specific)
|
|
3. `$HOME/.opencode/skills/.env` (shared skills)
|
|
4. `$HOME/.opencode/.env` (global)
|
|
5. `./.opencode/skills/${SKILL}/.env` (cwd)
|
|
6. `./.opencode/skills/.env` (cwd)
|
|
7. `./.opencode/.env` (cwd)
|
|
|
|
**Implementation pattern (Python):**
|
|
|
|
```python
|
|
from dotenv import load_dotenv
|
|
import os
|
|
|
|
# Load in reverse order (last loaded wins if not set)
|
|
load_dotenv('$HOME/.opencode/.env')
|
|
load_dotenv('$HOME/.opencode/skills/.env')
|
|
load_dotenv('$HOME/.opencode/skills/my-skill/.env')
|
|
load_dotenv('./.opencode/skills/my-skill/.env')
|
|
load_dotenv('./.opencode/skills/.env')
|
|
load_dotenv('./.opencode/.env')
|
|
# process.env already takes precedence
|
|
```
|
|
|
|
## Documentation Requirements
|
|
|
|
### .env.example
|
|
Show required variables without values:
|
|
|
|
```
|
|
API_KEY=
|
|
DATABASE_URL=
|
|
DEBUG=false
|
|
```
|
|
|
|
### requirements.txt (Python)
|
|
Pin major versions:
|
|
|
|
```
|
|
requests>=2.28.0
|
|
python-dotenv>=1.0.0
|
|
```
|
|
|
|
### package.json (Node.js)
|
|
Include scripts:
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"test": "jest"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Manual Testing
|
|
|
|
Before packaging, test with real use cases:
|
|
|
|
```bash
|
|
# Example: PDF rotation script
|
|
python scripts/rotate_pdf.py input.pdf 90 output.pdf
|
|
```
|
|
|
|
Verify output matches expectations.
|
|
|
|
## Error Handling
|
|
|
|
- Clear error messages
|
|
- Graceful failures
|
|
- No silent errors
|
|
- Exit codes: 0 success, non-zero failure
|