Skip to main content
Version: 0.1.0-alpha.3

Capability Dependencies

Capability dependencies verify that required system capabilities are available before your command runs. Invowk™ supports network connectivity, container engine availability, and interactive TTY checks.

Available Capabilities​

CapabilityDescription
local-area-networkChecks for LAN connectivity
internetChecks for internet connectivity
containersChecks that Docker or Podman is installed and responding
ttyChecks that Invowk is running in an interactive TTY

Basic Usage​

depends_on: {
    capabilities: [
        {alternatives: ["internet"]},
        {alternatives: ["local-area-network"]}
    ]
}

If internet connectivity isn't available:

✗ Dependencies not satisfied

Command 'deploy' has unmet dependencies:

Missing Capabilities:
  • internet - no internet connectivity

Ensure the required capabilities are available and try again.

Internet Connectivity​

Check for working internet access:

depends_on: {
    capabilities: [
        {alternatives: ["internet"]}
    ]
}

This checks:

  • DNS resolution is working
  • Can reach external hosts
  • Network is not blocked

Use Cases​

// Download dependencies
{
    name: "deps"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: "go mod download"
        runtimes: [{name: "native"}]
    }]
}

// Deploy to cloud
{
    name: "deploy"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: "kubectl apply -f k8s/"
        runtimes: [{name: "native"}]
    }]
}

// Fetch remote data
{
    name: "sync"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: "curl -o data.json https://api.example.com/data"
        runtimes: [{name: "native"}]
    }]
}

Local Area Network​

Check for LAN connectivity:

depends_on: {
    capabilities: [
        {alternatives: ["local-area-network"]}
    ]
}

This checks:

  • Network interface is up
  • Can communicate on local network
  • Useful for on-premise services

Use Cases​

// Connect to local database
{
    name: "db connect"
    depends_on: {
        capabilities: [{alternatives: ["local-area-network"]}]
    }
    implementations: [{
        script: "psql -h db.local -U admin"
        runtimes: [{name: "native"}]
    }]
}

// Access local services
{
    name: "check services"
    depends_on: {
        capabilities: [{alternatives: ["local-area-network"]}]
    }
    implementations: [{
        script: "curl http://service.local:8080/health"
        runtimes: [{name: "native"}]
    }]
}

Container Engine​

Check that a container engine is installed and ready:

depends_on: {
    capabilities: [
        {alternatives: ["containers"]}
    ]
}

This checks:

  • Docker or Podman is present in PATH
  • The engine responds to a version command

Use Cases​

Use this when a command shells out to Docker/Podman directly or requires container builds.

Interactive TTY​

Check that Invowk is running in an interactive terminal:

depends_on: {
    capabilities: [
        {alternatives: ["tty"]}
    ]
}

This checks:

  • stdin is a terminal
  • stdout is a terminal

Use Cases​

Use this for interactive prompts, TUI components, or scripts that require keyboard input.

Alternatives (OR Semantics)​

Require either capability:

depends_on: {
    capabilities: [
        // Either internet OR LAN is fine
        {alternatives: ["internet", "local-area-network"]}
    ]
}

This is useful when a command can work with either:

  • Remote cloud services (internet)
  • Local on-premise services (LAN)

Real-World Examples​

Package Installation​

{
    name: "install"
    description: "Install project dependencies"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
        tools: [{alternatives: ["npm", "pnpm", "yarn"]}]
    }
    implementations: [{
        script: "npm install"
        runtimes: [{name: "native"}]
    }]
}

CI Pipeline​

{
    name: "ci"
    description: "Run CI pipeline with remote checks"
    depends_on: {
        capabilities: [
            {alternatives: ["internet"]}  // For dependency download
        ]
        tools: [
            {alternatives: ["go"]},
            {alternatives: ["git"]},
        ]
    }
    implementations: [{
        script: """
            go mod download
            go build ./...
            go test ./...
            """
        runtimes: [{name: "native"}]
    }]
}

Hybrid Environment​

{
    name: "backup"
    description: "Backup to available storage"
    depends_on: {
        // Can backup to cloud (internet) or NAS (LAN)
        capabilities: [{alternatives: ["internet", "local-area-network"]}]
    }
    implementations: [{
        script: """
            if ping -c 1 nas.local > /dev/null 2>&1; then
                rsync -av ./data nas.local:/backup/
            else
                aws s3 sync ./data s3://my-backup-bucket/
            fi
            """
        runtimes: [{name: "native"}]
    }]
}

Offline-First Pattern​

Design commands that work offline when possible:

cmds: [
    // Online version - downloads latest
    {
        name: "update deps"
        depends_on: {
            capabilities: [{alternatives: ["internet"]}]
        }
        implementations: [{
            script: "go mod download"
            runtimes: [{name: "native"}]
        }]
    },
    
    // Offline version - uses cache
    {
        name: "build"
        // No internet requirement - uses cached dependencies
        depends_on: {
            filepaths: [{alternatives: ["go.mod"]}]
        }
        implementations: [{
            script: "go build -mod=readonly ./..."
            runtimes: [{name: "native"}]
        }]
    }
]

Container Context​

For container runtime, capability checks are performed on the host, not inside the container:

{
    name: "deploy"
    depends_on: {
        // Internet check happens on HOST
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: """
            apt-get update && apt-get install -y kubectl
            kubectl apply -f k8s/
            """
        runtimes: [{name: "container", image: "debian:stable-slim"}]
    }]
}

This makes sense because:

  • Container networking inherits from host
  • You're checking if the deployment can reach external services
  • Container network is ephemeral

Best Practices​

  1. Only check when necessary: Don't require internet for offline-capable tasks
  2. Use alternatives: When local or cloud services are interchangeable
  3. Fail fast: Check connectivity before starting long operations
  4. Provide fallbacks: Offer offline alternatives when possible

Next Steps​