aios-core
Version:
Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework
391 lines (281 loc) • 8.19 kB
Markdown
# Task: Apply Seed Data
**Purpose**: Safely apply seed data to database with idempotent operations
**Elicit**: true
## Execution Modes
**Choose your execution mode:**
### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
- Autonomous decision making with logging
- Minimal user interaction
- **Best for:** Simple, deterministic tasks
### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
- Explicit decision checkpoints
- Educational explanations
- **Best for:** Learning, complex decisions
### 3. Pre-Flight Planning - Comprehensive Upfront Planning
- Task analysis phase (identify all ambiguities)
- Zero ambiguity execution
- **Best for:** Ambiguous requirements, critical work
**Parameter:** `mode` (optional, default: `interactive`)
## Task Definition (AIOS Task Format V1.0)
```yaml
task: dbSeed()
responsável: Dara (Sage)
responsavel_type: Agente
atomic_layer: Config
**Entrada:**
- campo: query
tipo: string
origem: User Input
obrigatório: true
validação: Valid SQL query
- campo: params
tipo: object
origem: User Input
obrigatório: false
validação: Query parameters
- campo: connection
tipo: object
origem: config
obrigatório: true
validação: Valid PostgreSQL connection via Supabase
**Saída:**
- campo: query_result
tipo: array
destino: Memory
persistido: false
- campo: records_affected
tipo: number
destino: Return value
persistido: false
- campo: execution_time
tipo: number
destino: Memory
persistido: false
```
## Pre-Conditions
**Purpose:** Validate prerequisites BEFORE task execution (blocking)
**Checklist:**
```yaml
pre-conditions:
- [ ] Database connection established; query syntax valid
tipo: pre-condition
blocker: true
validação: |
Check database connection established; query syntax valid
error_message: "Pre-condition failed: Database connection established; query syntax valid"
```
## Post-Conditions
**Purpose:** Validate execution success AFTER task completes
**Checklist:**
```yaml
post-conditions:
- [ ] Query executed; results returned; transaction committed
tipo: post-condition
blocker: true
validação: |
Verify query executed; results returned; transaction committed
error_message: "Post-condition failed: Query executed; results returned; transaction committed"
```
## Acceptance Criteria
**Purpose:** Definitive pass/fail criteria for task completion
**Checklist:**
```yaml
acceptance-criteria:
- [ ] Data persisted correctly; constraints respected; no orphaned data
tipo: acceptance-criterion
blocker: true
validação: |
Assert data persisted correctly; constraints respected; no orphaned data
error_message: "Acceptance criterion not met: Data persisted correctly; constraints respected; no orphaned data"
```
## Tools
**External/shared resources used by this task:**
- **Tool:** neo4j-driver
- **Purpose:** Neo4j database connection and query execution
- **Source:** npm: neo4j-driver
- **Tool:** query-validator
- **Purpose:** Cypher query syntax validation
- **Source:** .aios-core/utils/db-query-validator.js
## Scripts
**Agent-specific code for this task:**
- **Script:** db-query.js
- **Purpose:** Execute Neo4j queries with error handling
- **Language:** JavaScript
- **Location:** .aios-core/scripts/db-query.js
## Error Handling
**Strategy:** retry
**Common Errors:**
1. **Error:** Connection Failed
- **Cause:** Unable to connect to Neo4j database
- **Resolution:** Check connection string, credentials, network
- **Recovery:** Retry with exponential backoff (max 3 attempts)
2. **Error:** Query Syntax Error
- **Cause:** Invalid Cypher query syntax
- **Resolution:** Validate query syntax before execution
- **Recovery:** Return detailed syntax error, suggest fix
3. **Error:** Transaction Rollback
- **Cause:** Query violates constraints or timeout
- **Resolution:** Review query logic and constraints
- **Recovery:** Automatic rollback, preserve data integrity
## Performance
**Expected Metrics:**
```yaml
duration_expected: 2-10 min (estimated)
cost_estimated: $0.001-0.008
token_usage: ~800-2,500 tokens
```
**Optimization Notes:**
- Validate configuration early; use atomic writes; implement rollback checkpoints
## Metadata
```yaml
story: N/A
version: 1.0.0
dependencies:
- N/A
tags:
- database
- infrastructure
updated_at: 2025-11-17
```
## Inputs
- `path` (string): Path to SQL seed file
## Process
### 1. Pre-Flight Checks
Ask user to confirm:
- Seed file: `{path}`
- Database: `$SUPABASE_DB_URL` (redacted)
- Environment: (dev/staging/production)
- Idempotent? (uses INSERT...ON CONFLICT or similar)
**CRITICAL**: Never seed production without explicit confirmation!
### 2. Validate Seed File
Check that seed file is idempotent:
```bash
echo "Validating seed file..."
# Check for dangerous patterns
if grep -qi "TRUNCATE\|DELETE FROM" {path}; then
echo "⚠️ WARNING: Seed contains TRUNCATE/DELETE"
echo " This is destructive. Continue? (yes/no)"
read CONFIRM
[ "$CONFIRM" != "yes" ] && { echo "Aborted"; exit 1; }
fi
# Check for INSERT...ON CONFLICT (idempotent pattern)
if ! grep -qi "ON CONFLICT" {path}; then
echo "⚠️ WARNING: No ON CONFLICT detected"
echo " Seed may not be idempotent. Continue? (yes/no)"
read CONFIRM
[ "$CONFIRM" != "yes" ] && { echo "Aborted"; exit 1; }
fi
echo "✓ Seed file validated"
```
### 3. Create Snapshot (Optional but Recommended)
```bash
TS=$(date +%Y%m%d%H%M%S)
mkdir -p supabase/snapshots
echo "Creating pre-seed snapshot..."
pg_dump "$SUPABASE_DB_URL" --schema-only --clean --if-exists \
> "supabase/snapshots/${TS}_before_seed.sql"
echo "✓ Snapshot: supabase/snapshots/${TS}_before_seed.sql"
```
### 4. Apply Seed Data
Run seed in transaction with error handling:
```bash
echo "Applying seed data..."
psql "$SUPABASE_DB_URL" \
-v ON_ERROR_STOP=1 \
-f {path}
if [ $? -eq 0 ]; then
echo "✓ Seed data applied successfully"
else
echo "❌ Seed failed"
echo " Rollback snapshot: supabase/snapshots/${TS}_before_seed.sql"
exit 1
fi
```
### 5. Verify Seed Data
Run basic verification:
```bash
echo "Verifying seed data..."
# Count inserted rows (example - customize per seed)
psql "$SUPABASE_DB_URL" -c \
"SELECT
'users' AS table, COUNT(*) AS rows FROM users
UNION ALL
SELECT
'categories', COUNT(*) FROM categories
ORDER BY table;"
echo "✓ Verification complete"
```
### 6. Document Seed
Log what was seeded:
```bash
cat >> supabase/docs/SEED_LOG.md << EOF
## Seed Applied: ${TS}
- File: {path}
- Date: $(date -u +"%Y-%m-%d %H:%M:%S UTC")
- Environment: ${ENVIRONMENT:-unknown}
- Applied by: ${USER:-unknown}
EOF
echo "✓ Logged to supabase/docs/SEED_LOG.md"
```
## Output
Display summary:
```
✅ SEED COMPLETE
File: {path}
Timestamp: {TS}
Snapshot: supabase/snapshots/{TS}_before_seed.sql
Log: supabase/docs/SEED_LOG.md
Next steps:
- Verify data manually in database
- Run smoke tests if appropriate
- Commit seed file to git
```
## Idempotent Seed Pattern
Best practice example for seed files:
```sql
-- ✅ GOOD: Idempotent seed
INSERT INTO categories (id, name, slug)
VALUES
('cat-1', 'Technology', 'technology'),
('cat-2', 'Design', 'design')
ON CONFLICT (id) DO UPDATE SET
name = EXCLUDED.name,
slug = EXCLUDED.slug;
-- ✅ GOOD: Conditional insert
INSERT INTO users (id, email, role)
SELECT 'user-1', 'admin@example.com', 'admin'
WHERE NOT EXISTS (
SELECT 1 FROM users WHERE email = 'admin@example.com'
);
-- ❌ BAD: Not idempotent
INSERT INTO categories (name, slug)
VALUES ('Technology', 'technology'); -- Will fail on retry
```
## Error Handling
If seed fails:
1. Check error message in terminal
2. Fix seed file
3. Restore snapshot if needed: `*rollback {TS}_before_seed`
4. Re-run seed: `*seed {path}`
## Notes
- Seeds should be idempotent (safe to run multiple times)
- Use `ON CONFLICT` or `INSERT...WHERE NOT EXISTS`
- Never TRUNCATE in production seeds
- Test seeds in dev/staging first
- Version seed files in git (supabase/seeds/)