re-uploading work

2026-02-04 17:46:30 -06:00
commit 3b14c65998
1388 changed files with 381262 additions and 0 deletions
--- a/crates/cli/README.md
+++ b/crates/cli/README.md
@@ -0,0 +1,591 @@
+# Attune CLI
+
+The Attune CLI is a command-line interface for interacting with the Attune automation platform. It provides an intuitive and flexible interface for managing packs, actions, rules, sensors, triggers, and executions.
+
+## Installation
+
+### From Source
+
+```bash
+cargo install --path crates/cli
+```
+
+The binary will be named `attune`.
+
+### Development Build
+
+```bash
+cargo build -p attune-cli
+./target/debug/attune --help
+```
+
+### Release Build
+
+```bash
+cargo build -p attune-cli --release
+./target/release/attune --help
+```
+
+## Configuration
+
+The CLI stores configuration in `~/.config/attune/config.yaml` (or `$XDG_CONFIG_HOME/attune/config.yaml`).
+
+Default configuration:
+```yaml
+api_url: http://localhost:8080
+auth_token: null
+refresh_token: null
+output_format: table
+```
+
+### Environment Variables
+
+- `ATTUNE_API_URL`: Override the API endpoint URL
+- Standard XDG environment variables for config directory location
+
+### Global Flags
+
+All commands support these global flags:
+
+- `--api-url <URL>`: Override the API endpoint (also via `ATTUNE_API_URL`)
+- `--output <FORMAT>`: Output format (`table`, `json`, `yaml`)
+- `-j, --json`: Output as JSON (shorthand for `--output json`)
+- `-y, --yaml`: Output as YAML (shorthand for `--output yaml`)
+- `-v, --verbose`: Enable verbose logging
+
+## Authentication
+
+### Login
+
+```bash
+# Interactive password prompt
+attune auth login --username admin
+
+# With password (not recommended for interactive use)
+attune auth login --username admin --password secret
+
+# With custom API URL
+attune auth login --username admin --api-url https://attune.example.com
+```
+
+### Logout
+
+```bash
+attune auth logout
+```
+
+### Check Current User
+
+```bash
+attune auth whoami
+```
+
+## Pack Management
+
+### List Packs
+
+```bash
+# List all packs
+attune pack list
+
+# Filter by name
+attune pack list --name core
+
+# JSON output (long form)
+attune pack list --output json
+
+# JSON output (shorthand)
+attune pack list -j
+
+# YAML output (shorthand)
+attune pack list -y
+```
+
+### Show Pack Details
+
+```bash
+# By name
+attune pack show core
+
+# By ID
+attune pack show 1
+```
+
+### Install Pack
+
+```bash
+# From git repository
+attune pack install https://github.com/example/attune-pack-example
+
+# From git with specific branch/tag
+attune pack install https://github.com/example/attune-pack-example --ref v1.0.0
+
+# Force reinstall
+attune pack install https://github.com/example/attune-pack-example --force
+```
+
+### Register Local Pack
+
+```bash
+# Register from local directory
+attune pack register /path/to/pack
+```
+
+### Uninstall Pack
+
+```bash
+# Interactive confirmation
+attune pack uninstall core
+
+# Skip confirmation
+attune pack uninstall core --yes
+```
+
+## Action Management
+
+### List Actions
+
+```bash
+# List all actions
+attune action list
+
+# Filter by pack
+attune action list --pack core
+
+# Filter by name
+attune action list --name execute
+```
+
+### Show Action Details
+
+```bash
+# By pack.action reference
+attune action show core.echo
+
+# By ID
+attune action show 1
+```
+
+### Execute Action
+
+```bash
+# With key=value parameters
+attune action execute core.echo --param message="Hello World" --param count=3
+
+# With JSON parameters
+attune action execute core.echo --params-json '{"message": "Hello", "count": 5}'
+
+# Wait for completion
+attune action execute core.long_task --wait
+
+# Wait with custom timeout (default 300 seconds)
+attune action execute core.long_task --wait --timeout 600
+```
+
+## Rule Management
+
+### List Rules
+
+```bash
+# List all rules
+attune rule list
+
+# Filter by pack
+attune rule list --pack core
+
+# Filter by enabled status
+attune rule list --enabled true
+```
+
+### Show Rule Details
+
+```bash
+# By pack.rule reference
+attune rule show core.on_webhook
+
+# By ID
+attune rule show 1
+```
+
+### Enable/Disable Rules
+
+```bash
+# Enable a rule
+attune rule enable core.on_webhook
+
+# Disable a rule
+attune rule disable core.on_webhook
+```
+
+### Create Rule
+
+```bash
+attune rule create \
+  --name my_rule \
+  --pack core \
+  --trigger core.webhook \
+  --action core.notify \
+  --description "Notify on webhook" \
+  --enabled
+
+# With criteria
+attune rule create \
+  --name filtered_rule \
+  --pack core \
+  --trigger core.webhook \
+  --action core.notify \
+  --criteria '{"trigger.payload.severity": "critical"}'
+```
+
+### Delete Rule
+
+```bash
+# Interactive confirmation
+attune rule delete core.my_rule
+
+# Skip confirmation
+attune rule delete core.my_rule --yes
+```
+
+## Execution Monitoring
+
+### List Executions
+
+```bash
+# List recent executions (default: last 50)
+attune execution list
+
+# Filter by pack
+attune execution list --pack core
+
+# Filter by action
+attune execution list --action core.echo
+
+# Filter by status
+attune execution list --status succeeded
+
+# Search in execution results
+attune execution list --result "error"
+
+# Combine filters
+attune execution list --pack monitoring --status failed --result "timeout"
+
+# Limit results
+attune execution list --limit 100
+```
+
+### Show Execution Details
+
+```bash
+attune execution show 123
+```
+
+### View Execution Logs
+
+```bash
+# Show logs
+attune execution logs 123
+
+# Follow logs (real-time)
+attune execution logs 123 --follow
+```
+
+### Cancel Execution
+
+```bash
+# Interactive confirmation
+attune execution cancel 123
+
+# Skip confirmation
+attune execution cancel 123 --yes
+```
+
+### Get Raw Execution Result
+
+Get just the result data from a completed execution, useful for piping to other tools.
+
+```bash
+# Get result as JSON (default)
+attune execution result 123
+
+# Get result as YAML
+attune execution result 123 --format yaml
+
+# Pipe to jq for processing
+attune execution result 123 | jq '.data.field'
+
+# Extract specific field
+attune execution result 123 | jq -r '.status'
+```
+
+## Trigger Management
+
+### List Triggers
+
+```bash
+# List all triggers
+attune trigger list
+
+# Filter by pack
+attune trigger list --pack core
+```
+
+### Show Trigger Details
+
+```bash
+attune trigger show core.webhook
+```
+
+## Sensor Management
+
+### List Sensors
+
+```bash
+# List all sensors
+attune sensor list
+
+# Filter by pack
+attune sensor list --pack core
+```
+
+### Show Sensor Details
+
+```bash
+attune sensor show core.file_watcher
+```
+
+## CLI Configuration
+
+### List Configuration
+
+```bash
+attune config list
+```
+
+### Get Configuration Value
+
+```bash
+attune config get api_url
+```
+
+### Set Configuration Value
+
+```bash
+# Set API URL
+attune config set api_url https://attune.example.com
+
+# Set output format
+attune config set output_format json
+```
+
+### Show Configuration File Path
+
+```bash
+attune config path
+```
+
+## Output Formats
+
+### Table (Default)
+
+Human-readable table format with colored output:
+
+```bash
+attune pack list
+```
+
+### JSON
+
+Machine-readable JSON for scripting:
+
+```bash
+# Long form
+attune pack list --output json
+
+# Shorthand
+attune pack list -j
+```
+
+### YAML
+
+YAML format:
+
+```bash
+# Long form
+attune pack list --output yaml
+
+# Shorthand
+attune pack list -y
+```
+
+## Examples
+
+### Complete Workflow Example
+
+```bash
+# 1. Login
+attune auth login --username admin
+
+# 2. Install a pack
+attune pack install https://github.com/example/monitoring-pack
+
+# 3. List available actions
+attune action list --pack monitoring
+
+# 4. Execute an action
+attune action execute monitoring.check_health --param endpoint=https://api.example.com
+
+# 5. Enable a rule
+attune rule enable monitoring.alert_on_failure
+
+# 6. Monitor executions
+attune execution list --action monitoring.check_health
+```
+
+### Scripting Example
+
+```bash
+#!/bin/bash
+# Deploy and test a pack
+
+set -e
+
+PACK_URL="https://github.com/example/my-pack"
+PACK_NAME="my-pack"
+
+# Install pack
+echo "Installing pack..."
+attune pack install "$PACK_URL" -j | jq -r '.id'
+
+# Verify installation
+echo "Verifying pack..."
+PACK_ID=$(attune pack list --name "$PACK_NAME" -j | jq -r '.[0].id')
+
+if [ -z "$PACK_ID" ]; then
+  echo "Pack installation failed"
+  exit 1
+fi
+
+echo "Pack installed successfully with ID: $PACK_ID"
+
+# List actions in the pack
+echo "Actions in pack:"
+attune action list --pack "$PACK_NAME"
+
+# Enable all rules in the pack
+attune rule list --pack "$PACK_NAME" -j | \
+  jq -r '.[].id' | \
+  xargs -I {} attune rule enable {}
+
+echo "All rules enabled"
+```
+
+### Process Execution Results
+
+```bash
+#!/bin/bash
+# Extract and process execution results
+
+EXECUTION_ID=123
+
+# Get raw result
+RESULT=$(attune execution result $EXECUTION_ID)
+
+# Extract specific fields
+STATUS=$(echo "$RESULT" | jq -r '.status')
+MESSAGE=$(echo "$RESULT" | jq -r '.message')
+
+echo "Status: $STATUS"
+echo "Message: $MESSAGE"
+
+# Or pipe directly
+attune execution result $EXECUTION_ID | jq -r '.errors[]'
+```
+
+## Troubleshooting
+
+### Authentication Issues
+
+If you get authentication errors:
+
+1. Check you're logged in: `attune auth whoami`
+2. Try logging in again: `attune auth login --username <user>`
+3. Verify API URL: `attune config get api_url`
+
+### Connection Issues
+
+If you can't connect to the API:
+
+1. Verify the API is running: `curl http://localhost:8080/health`
+2. Check the configured URL: `attune config get api_url`
+3. Override the URL: `attune --api-url http://localhost:8080 auth whoami`
+
+### Verbose Logging
+
+Enable verbose logging for debugging:
+
+```bash
+attune --verbose pack list
+```
+
+## Development
+
+### Building
+
+```bash
+cargo build -p attune-cli
+```
+
+### Testing
+
+```bash
+cargo test -p attune-cli
+```
+
+### Code Structure
+
+```
+crates/cli/
+├── src/
+│   ├── main.rs           # Entry point and CLI structure
+│   ├── client.rs         # HTTP client for API calls
+│   ├── config.rs         # Configuration management
+│   ├── output.rs         # Output formatting (table, JSON, YAML)
+│   └── commands/         # Command implementations
+│       ├── auth.rs       # Authentication commands
+│       ├── pack.rs       # Pack management commands
+│       ├── action.rs     # Action commands
+│       ├── rule.rs       # Rule commands
+│       ├── execution.rs  # Execution commands
+│       ├── trigger.rs    # Trigger commands
+│       ├── sensor.rs     # Sensor commands
+│       └── config.rs     # Config commands
+└── Cargo.toml
+```
+
+## Features
+
+- ✅ JWT authentication with token storage
+- ✅ Multiple output formats (table, JSON, YAML)
+- ✅ Colored and formatted table output
+- ✅ Interactive prompts for sensitive operations
+- ✅ Configuration management
+- ✅ Advanced execution search (by pack, action, status, result content)
+- ✅ Comprehensive pack management
+- ✅ Action execution with parameter support
+- ✅ Rule creation and management
+- ✅ Execution monitoring and logs with advanced filtering
+- ✅ Raw result extraction for piping to other tools
+- ✅ Shorthand output flags (`-j`, `-y`) for CLI convenience
+- ✅ Environment variable overrides
+
+## Dependencies
+
+Key dependencies:
+- `clap`: CLI argument parsing
+- `reqwest`: HTTP client
+- `serde_json` / `serde_yaml`: Serialization
+- `colored`: Terminal colors
+- `comfy-table`: Table formatting
+- `dialoguer`: Interactive prompts
+- `indicatif`: Progress indicators (for future use)