trying to rework database migrations

2026-02-05 11:42:04 -06:00
parent 3b14c65998
commit 343488b3eb
83 changed files with 5793 additions and 876 deletions
--- a/docs/QUICKREF-dev-packs.md
+++ b/docs/QUICKREF-dev-packs.md
@@ -0,0 +1,177 @@
+# Quick Reference: Development Packs
+
+## Setup (One Time)
+
+```bash
+# Directory is already created, just start Docker
+docker compose up -d
+```
+
+## Create a Pack
+
+```bash
+./scripts/dev-pack.sh create my-pack
+```
+
+Creates:
+- `packs.dev/my-pack/pack.yaml`
+- `packs.dev/my-pack/actions/example.sh`
+- Example action YAML
+- README
+
+## List Packs
+
+```bash
+./scripts/dev-pack.sh list
+```
+
+## Validate Pack
+
+```bash
+./scripts/dev-pack.sh validate my-pack
+```
+
+Checks:
+- ✓ pack.yaml exists
+- ✓ Action scripts exist and are executable
+- ✓ Entry points match
+
+## Register Pack in Attune
+
+```bash
+# Get token first
+export ATTUNE_TOKEN=$(attune auth login test@attune.local --password TestPass123!)
+
+# Register pack
+curl -X POST http://localhost:8080/api/v1/packs \
+  -H "Authorization: Bearer $ATTUNE_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "ref": "my-pack",
+    "label": "My Pack",
+    "version": "1.0.0",
+    "enabled": true
+  }'
+```
+
+## Execute Action
+
+```bash
+curl -X POST http://localhost:8080/api/v1/executions \
+  -H "Authorization: Bearer $ATTUNE_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "action": "my-pack.example",
+    "parameters": {
+      "message": "Hello!"
+    }
+  }'
+```
+
+## Directory Layout
+
+```
+packs.dev/
+├── examples/              # Example packs (in git)
+│   ├── basic-pack/       # Shell action example
+│   └── python-pack/      # Python action example
+└── my-pack/              # Your packs (not in git)
+    ├── pack.yaml
+    ├── actions/
+    ├── triggers/
+    ├── sensors/
+    └── workflows/
+```
+
+## File Locations in Docker
+
+- **Core pack**: `/opt/attune/packs` (read-only)
+- **Dev packs**: `/opt/attune/packs.dev` (read-write)
+
+## Development Workflow
+
+1. Create pack: `./scripts/dev-pack.sh create my-pack`
+2. Edit files: `vim packs.dev/my-pack/actions/my_action.sh`
+3. Validate: `./scripts/dev-pack.sh validate my-pack`
+4. Register: See "Register Pack" above
+5. Test: Execute action via API
+6. Iterate: Changes are immediately visible!
+
+## Action Script Template
+
+```bash
+#!/bin/bash
+set -e
+
+# Get parameters from environment
+PARAM="${ATTUNE_ACTION_param:-default}"
+
+# Validate
+if [ -z "$PARAM" ]; then
+    echo '{"error": "param required"}' >&2
+    exit 1
+fi
+
+# Do work
+result=$(echo "Processed: $PARAM")
+
+# Return JSON
+echo "{\"result\": \"$result\"}"
+```
+
+## Common Commands
+
+```bash
+# List all packs
+./scripts/dev-pack.sh list
+
+# Validate pack structure
+./scripts/dev-pack.sh validate my-pack
+
+# View pack in container
+docker exec attune-api ls -la /opt/attune/packs.dev/
+
+# Check worker logs
+docker logs -f attune-worker-shell
+
+# Sync workflows after changes
+curl -X POST http://localhost:8080/api/v1/packs/my-pack/workflows/sync \
+  -H "Authorization: Bearer $ATTUNE_TOKEN"
+
+# Clean up dev packs
+./scripts/dev-pack.sh clean
+```
+
+## Troubleshooting
+
+### "Pack not found"
+```bash
+# Check if registered
+curl http://localhost:8080/api/v1/packs/my-pack \
+  -H "Authorization: Bearer $ATTUNE_TOKEN"
+
+# Check if files exist in container
+docker exec attune-api ls /opt/attune/packs.dev/my-pack/
+```
+
+### "Entry point not found"
+```bash
+# Make script executable
+chmod +x packs.dev/my-pack/actions/*.sh
+
+# Verify in container
+docker exec attune-worker-shell ls -la /opt/attune/packs.dev/my-pack/actions/
+```
+
+### Changes not reflected
+```bash
+# For action scripts: should be immediate
+# For action YAML: re-register pack
+# For workflows: run sync endpoint
+```
+
+## See Also
+
+- [Full Documentation](development/packs-dev-directory.md)
+- [Pack Structure](packs/pack-structure.md)
+- [Examples](../packs.dev/examples/)