attune/packs/core/DEPENDENCIES.md

Core Pack Dependencies

Philosophy: The core pack has zero runtime dependencies beyond standard system utilities.

Why Zero Dependencies?

1. Portability: Works in any environment with standard Unix utilities
2. Reliability: No version conflicts, no package installation failures
3. Security: Minimal attack surface, no third-party library vulnerabilities
4. Performance: Fast startup, no runtime initialization overhead
5. Simplicity: Easy to audit, test, and maintain

Required System Utilities

All core pack actions rely only on utilities available in standard Linux/Unix environments:

Utility	Purpose	Used By
bash	Shell scripting	All shell actions
jq	JSON parsing/generation	All actions (parameter handling)
curl	HTTP client	http_request.sh
Standard Unix tools	Text processing, file operations	Various actions

These utilities are:

• ✅ Pre-installed in all Attune worker containers
• ✅ Standard across Linux distributions
• ✅ Stable, well-tested, and widely used
• ✅ Available via package managers if needed

No Runtime Dependencies

The core pack does not require:

• ❌ Python interpreter or packages
• ❌ Node.js runtime or npm modules
• ❌ Ruby, Perl, or other scripting languages
• ❌ Third-party libraries or frameworks
• ❌ Package installations at runtime

Action Implementation Guidelines

✅ Preferred Approaches

Use bash + standard utilities:

#!/bin/bash
# Read params with jq
INPUT=$(cat)
PARAM=$(echo "$INPUT" | jq -r '.param // "default"')

# Process with standard tools
RESULT=$(echo "$PARAM" | tr '[:lower:]' '[:upper:]')

# Output with jq
jq -n --arg result "$RESULT" '{result: $result}'

Use curl for HTTP:

# Make HTTP requests with curl
curl -s -X POST "$URL" \
    -H "Content-Type: application/json" \
    -d '{"key": "value"}'

Use jq for JSON processing:

# Parse JSON responses
echo "$RESPONSE" | jq '.data.items[] | .name'

# Generate JSON output
jq -n \
    --arg status "success" \
    --argjson count 42 \
    '{status: $status, count: $count}'

❌ Avoid

Don't add runtime dependencies:

# ❌ DON'T DO THIS
pip install requests
python3 script.py

# ❌ DON'T DO THIS
npm install axios
node script.js

# ❌ DON'T DO THIS
gem install httparty
ruby script.rb

Don't use language-specific features:

# ❌ DON'T DO THIS in core pack
#!/usr/bin/env python3
import requests  # External dependency!
response = requests.get(url)

Instead, use bash + curl:

# ✅ DO THIS in core pack
#!/bin/bash
response=$(curl -s "$url")

When Runtime Dependencies Are Acceptable

For custom packs (not core pack), runtime dependencies are fine:

• ✅ Pack-specific Python libraries (installed in pack virtualenv)
• ✅ Pack-specific npm modules (installed in pack node_modules)
• ✅ Language runtimes (Python, Node.js) for complex logic
• ✅ Specialized tools for specific integrations

The core pack serves as a foundation with zero dependencies. Custom packs can have dependencies managed via:

• requirements.txt for Python packages
• package.json for Node.js modules
• Pack runtime environments (isolated per pack)

Migration from Runtime Dependencies

If an action currently uses a runtime dependency, consider:

1. Can it be done with bash + standard utilities?

   • Yes → Rewrite in bash
   • No → Consider if it belongs in core pack

2. Is the functionality complex?

   • Simple HTTP/JSON → Use curl + jq
   • Complex API client → Move to custom pack

3. Is it a specialized integration?

   • Yes → Move to integration-specific pack
   • No → Keep in core pack with bash implementation

Example: http_request Migration

Before (Python with dependency):

#!/usr/bin/env python3
import requests  # ❌ External dependency

response = requests.get(url, headers=headers)
print(response.json())

After (Bash with standard utilities):

#!/bin/bash
# ✅ No dependencies beyond curl + jq

response=$(curl -s -H "Authorization: Bearer $TOKEN" "$URL")
echo "$response" | jq '.'

Testing Without Dependencies

Core pack actions can be tested anywhere with standard utilities:

# Local testing (no installation needed)
echo '{"param": "value"}' | ./action.sh

# Docker testing (minimal base image)
docker run --rm -i alpine:latest sh -c '
    apk add --no-cache bash jq curl &&
    /bin/bash < action.sh
'

# CI/CD testing (standard tools available)
./action.sh < test-params.json

Benefits Realized

For Developers

• No dependency management overhead
• Immediate action execution (no runtime setup)
• Easy to test locally
• Simple to audit and debug

For Operators

• No version conflicts between packs
• No package installation failures
• Faster container startup
• Smaller container images

For Security

• Minimal attack surface
• No third-party library vulnerabilities
• Easier to audit (standard tools only)
• No supply chain risks

For Performance

• Fast action startup (no runtime initialization)
• Low memory footprint
• No package loading overhead
• Efficient resource usage

Standard Utility Reference

jq (JSON Processing)

# Parse input
VALUE=$(echo "$JSON" | jq -r '.key')

# Generate output
jq -n --arg val "$VALUE" '{result: $val}'

# Transform data
echo "$JSON" | jq '.items[] | select(.active)'

curl (HTTP Client)

# GET request
curl -s "$URL"

# POST with JSON
curl -s -X POST "$URL" \
    -H "Content-Type: application/json" \
    -d '{"key": "value"}'

# With authentication
curl -s -H "Authorization: Bearer $TOKEN" "$URL"

Standard Text Tools

# grep - Pattern matching
echo "$TEXT" | grep "pattern"

# sed - Text transformation
echo "$TEXT" | sed 's/old/new/g'

# awk - Text processing
echo "$TEXT" | awk '{print $1}'

# tr - Character translation
echo "$TEXT" | tr '[:lower:]' '[:upper:]'

Future Considerations

The core pack will:

• ✅ Continue to have zero runtime dependencies
• ✅ Use only standard Unix utilities
• ✅ Serve as a reference implementation
• ✅ Provide foundational actions for workflows

Custom packs may:

• ✅ Have runtime dependencies (Python, Node.js, etc.)
• ✅ Use specialized libraries for integrations
• ✅ Require specific tools or SDKs
• ✅ Manage dependencies via pack environments

Summary

Core Pack = Zero Dependencies + Standard Utilities

This philosophy ensures the core pack is:

• Portable across all environments
• Reliable without version conflicts
• Secure with minimal attack surface
• Performant with fast startup
• Simple to test and maintain

For actions requiring runtime dependencies, create custom packs with proper dependency management via requirements.txt, package.json, or similar mechanisms.