Skip to content

Commit 4b775a8

Browse files
alvagantealvagante
committed
Added refresh-versions action, consolidated prompts, cleanup code
1 parent 04497d2 commit 4b775a8

52 files changed

Lines changed: 6088 additions & 1039 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.kiro/steering/structure.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,17 @@
22

33
## Root Directory Organization
44
- **Documentation**: `docs/` - Comprehensive documentation including API reference, CLI guide, deployment
5+
- **Summaries** : `docs/summaries` - All Kiro's summaries of vice or spec activites must be stored here and not in the main dir
56
- **Examples**: `examples/` - Usage examples, configurations, and use cases
67
- **Schemas**: `schemas/` - JSON schema definitions
78
- **Scripts**: `scripts/` - Build, deployment, and utility scripts
9+
- **Development Scripts**: `scripts/development/` - All the scripts generated by Kiro to test or perform activities duing development should be stored here and not in the main dir.
810
- **Tests**: `tests/` - Comprehensive test suite with fixtures
911
- **Saidata**: Repository-based saidata (cached in `~/.sai/cache/repositories/`)
1012
- **Providerdata**: `providerdata/` - Provider data to support actions
1113

14+
15+
1216
## Core Package Structure
1317

1418
### SAI CLI Tool (`sai/`)

‎docs/refresh-versions-command.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# Refresh Versions Command
2+
3+
## Overview
4+
5+
The `refresh-versions` command updates package version information in existing saidata files by querying package repositories directly, without using LLM services. This provides a fast, cost-free way to keep saidata files synchronized with upstream package versions.
6+
7+
## Features
8+
9+
- **No LLM costs**: Queries repositories directly
10+
- **Fast execution**: Typically completes in seconds
11+
- **Safe updates**: Creates backups before modifying files
12+
- **Selective updates**: Target specific providers
13+
- **Check mode**: Preview changes without modifying files
14+
- **Batch processing**: Update multiple files at once (via shell)
15+
16+
## Usage
17+
18+
### Basic Usage
19+
20+
```bash
21+
# Refresh all package versions in a saidata file
22+
saigen refresh-versions nginx.yaml
23+
24+
# Check for updates without modifying the file
25+
saigen refresh-versions --check-only nginx.yaml
26+
27+
# Refresh specific providers only
28+
saigen refresh-versions --providers apt,brew nginx.yaml
29+
30+
# Save to a different file
31+
saigen refresh-versions --output nginx-updated.yaml nginx.yaml
32+
33+
# Skip cache for latest data
34+
saigen refresh-versions --no-cache nginx.yaml
35+
36+
# Show all packages including unchanged ones
37+
saigen --verbose refresh-versions --show-unchanged nginx.yaml
38+
```
39+
40+
### Options
41+
42+
- `--output, -o PATH`: Output file path (default: overwrite input file)
43+
- `--providers TEXT`: Target specific providers (e.g., apt, brew, winget)
44+
- `--backup / --no-backup`: Create backup of original file (default: enabled)
45+
- `--backup-dir PATH`: Directory for backup files (default: same as input file)
46+
- `--check-only`: Check for version updates without modifying files
47+
- `--show-unchanged`: Show packages that are already up-to-date
48+
- `--use-cache / --no-cache`: Use cached repository data (default: enabled)
49+
50+
### Global Options
51+
52+
- `--verbose, -v`: Enable verbose output
53+
- `--dry-run`: Show what would be done without executing
54+
55+
## How It Works
56+
57+
1. **Load saidata**: Reads the existing saidata YAML file
58+
2. **Extract packages**: Collects all packages with version information from:
59+
- Top-level packages
60+
- Provider-specific packages
61+
- Package sources
62+
- Repository packages
63+
- Binaries
64+
- Sources
65+
- Scripts
66+
3. **Query repositories**: Searches package repositories for current versions
67+
4. **Update versions**: Updates version fields in the saidata object
68+
5. **Save changes**: Writes the updated saidata back to file
69+
70+
## What Gets Updated
71+
72+
The command updates version information in these locations:
73+
74+
- `packages[].version`
75+
- `providers.<provider>.packages[].version`
76+
- `providers.<provider>.package_sources[].packages[].version`
77+
- `providers.<provider>.repositories[].packages[].version`
78+
- `providers.<provider>.binaries[].version`
79+
- `providers.<provider>.sources[].version`
80+
- `providers.<provider>.scripts[].version`
81+
82+
All other fields remain unchanged, preserving manual customizations.
83+
84+
## Examples
85+
86+
### Check for Outdated Versions
87+
88+
```bash
89+
# Check which packages need updates
90+
saigen refresh-versions --check-only nginx.yaml
91+
```
92+
93+
Output:
94+
```
95+
Check Results for nginx:
96+
Total packages checked: 5
97+
Updates available: 2
98+
Already up-to-date: 3
99+
Execution time: 1.23s
100+
101+
Available Updates:
102+
• apt/nginx: 1.20.1 → 1.24.0
103+
• brew/nginx: 1.20.1 → 1.25.3
104+
```
105+
106+
### Update Specific Providers
107+
108+
```bash
109+
# Only update apt and brew packages
110+
saigen refresh-versions --providers apt,brew nginx.yaml
111+
```
112+
113+
### Batch Update Multiple Files
114+
115+
```bash
116+
# Update all saidata files in a directory
117+
for file in saidata/*.yaml; do
118+
saigen refresh-versions "$file"
119+
done
120+
```
121+
122+
### CI/CD Integration
123+
124+
```bash
125+
# Check for outdated versions in CI pipeline
126+
if saigen refresh-versions --check-only nginx.yaml | grep -q "Updates available: [1-9]"; then
127+
echo "Versions are outdated!"
128+
exit 1
129+
fi
130+
```
131+
132+
## Backup Management
133+
134+
By default, the command creates timestamped backups before modifying files:
135+
136+
```
137+
nginx.yaml
138+
nginx.backup.20250410_143022.yaml
139+
```
140+
141+
To disable backups:
142+
143+
```bash
144+
saigen refresh-versions --no-backup nginx.yaml
145+
```
146+
147+
To specify a backup directory:
148+
149+
```bash
150+
saigen refresh-versions --backup-dir ./backups nginx.yaml
151+
```
152+
153+
## Repository Cache
154+
155+
The command uses cached repository data by default for faster execution. Cache is stored in:
156+
157+
```
158+
~/.saigen/cache/repositories/
159+
```
160+
161+
To force fresh queries:
162+
163+
```bash
164+
saigen refresh-versions --no-cache nginx.yaml
165+
```
166+
167+
## Troubleshooting
168+
169+
### Package Not Found
170+
171+
If a package cannot be found in the repository:
172+
173+
```
174+
Warnings:
175+
⚠ Could not find version for nginx in apt repository
176+
```
177+
178+
This can happen if:
179+
- The package name doesn't match the repository's naming
180+
- The repository cache is outdated (try `--no-cache`)
181+
- The repository is not available
182+
183+
### Version Mismatch
184+
185+
If the command finds a different package:
186+
187+
```
188+
Using closest match: nginx-full v1.24.0
189+
```
190+
191+
This indicates the exact package name wasn't found, and a similar package was used instead. Verify the package name is correct.
192+
193+
## Best Practices
194+
195+
1. **Use check-only first**: Always preview changes before applying
196+
2. **Keep backups enabled**: Allows easy rollback if needed
197+
3. **Target specific providers**: Faster and more predictable
198+
4. **Use in CI/CD**: Automate version checking in pipelines
199+
5. **Combine with validate**: Run validation after updates
200+
201+
```bash
202+
# Safe update workflow
203+
saigen refresh-versions --check-only nginx.yaml
204+
saigen refresh-versions nginx.yaml
205+
saigen validate nginx.yaml
206+
```
207+
208+
## Comparison with Update Command
209+
210+
| Feature | refresh-versions | update |
211+
|---------|-----------------|--------|
212+
| LLM usage | No | Yes |
213+
| Cost | Free | Costs tokens |
214+
| Speed | Fast (seconds) | Slower (minutes) |
215+
| Updates | Versions only | All metadata |
216+
| Use case | Version sync | Full regeneration |
217+
218+
Use `refresh-versions` for routine version updates, and `update` for comprehensive metadata refreshes.

‎docs/refresh-versions-quick-reference.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# refresh-versions Quick Reference
2+
3+
## One-Line Summary
4+
Update package versions in saidata files from repository data without LLM costs.
5+
6+
## Basic Commands
7+
8+
```bash
9+
# Check for updates
10+
saigen refresh-versions --check-only nginx.yaml
11+
12+
# Apply updates
13+
saigen refresh-versions nginx.yaml
14+
15+
# Specific providers
16+
saigen refresh-versions --providers apt,brew nginx.yaml
17+
18+
# Save to new file
19+
saigen refresh-versions -o nginx-new.yaml nginx.yaml
20+
21+
# Fresh data (skip cache)
22+
saigen refresh-versions --no-cache nginx.yaml
23+
24+
# Verbose output
25+
saigen --verbose refresh-versions nginx.yaml
26+
27+
# Dry run
28+
saigen --dry-run refresh-versions nginx.yaml
29+
```
30+
31+
## Common Options
32+
33+
| Option | Description |
34+
|--------|-------------|
35+
| `--check-only` | Preview changes without modifying |
36+
| `--providers TEXT` | Target specific providers (apt, brew, etc.) |
37+
| `--no-cache` | Skip cache, query repositories directly |
38+
| `--output, -o PATH` | Save to different file |
39+
| `--no-backup` | Disable automatic backup |
40+
| `--show-unchanged` | Show packages already up-to-date |
41+
| `--backup-dir PATH` | Custom backup directory |
42+
43+
## Global Options
44+
45+
| Option | Description |
46+
|--------|-------------|
47+
| `--verbose, -v` | Enable verbose output |
48+
| `--dry-run` | Show what would happen |
49+
50+
## What Gets Updated
51+
52+
✅ Package versions
53+
✅ Binary versions
54+
✅ Source versions
55+
✅ Script versions
56+
❌ Descriptions (unchanged)
57+
❌ URLs (unchanged)
58+
❌ Other metadata (unchanged)
59+
60+
## Workflow
61+
62+
```bash
63+
# 1. Check what would change
64+
saigen refresh-versions --check-only nginx.yaml
65+
66+
# 2. Apply updates
67+
saigen refresh-versions nginx.yaml
68+
69+
# 3. Validate result
70+
saigen validate nginx.yaml
71+
```
72+
73+
## CI/CD Example
74+
75+
```yaml
76+
# .github/workflows/check-versions.yml
77+
- name: Check for outdated versions
78+
run: |
79+
saigen refresh-versions --check-only saidata/*.yaml
80+
```
81+
82+
## Batch Processing
83+
84+
```bash
85+
# Update all files in directory
86+
for file in saidata/*.yaml; do
87+
saigen refresh-versions "$file"
88+
done
89+
90+
# Or with find
91+
find saidata -name "*.yaml" -exec saigen refresh-versions {} \;
92+
```
93+
94+
## Troubleshooting
95+
96+
### Package not found
97+
```
98+
⚠ Could not find version for nginx in apt repository
99+
```
100+
**Solution**: Check package name, try `--no-cache`, or verify repository availability
101+
102+
### Version mismatch
103+
```
104+
Using closest match: nginx-full v1.24.0
105+
```
106+
**Solution**: Verify exact package name in repository
107+
108+
### Cache issues
109+
```bash
110+
# Force fresh queries
111+
saigen refresh-versions --no-cache nginx.yaml
112+
113+
# Or clear cache
114+
saigen cache clear
115+
```
116+
117+
## Comparison
118+
119+
| Feature | refresh-versions | update | generate |
120+
|---------|-----------------|--------|----------|
121+
| LLM | ❌ | ✅ | ✅ |
122+
| Cost | Free | $$ | $$ |
123+
| Speed | Seconds | Minutes | Minutes |
124+
| Updates | Versions | All | New file |
125+
126+
## Tips
127+
128+
💡 Use `--check-only` first
129+
💡 Keep backups enabled
130+
💡 Target specific providers for speed
131+
💡 Use `--no-cache` for latest data
132+
💡 Validate after updates
133+
134+
## Help
135+
136+
```bash
137+
saigen refresh-versions --help
138+
```
139+
140+
## Documentation
141+
142+
- Full docs: `docs/refresh-versions-command.md`
143+
- Implementation: `docs/summaries/refresh-versions-implementation.md`

0 commit comments

Comments
 (0)