# hoody-app Subskill ## Overview The `hoody-app` service provides application resolution and execution across multiple package sources. It enables searching, selecting, and running applications from configured sources with support for profiles, recipes, and batch operations. **When to use this service:** - Searching for available applications across package sources - Running or preflight-checking application execution - Managing package sources (add, remove, sync, diagnose) - Creating and managing user profiles with different preferences - Saving and reusing selector templates as recipes - Executing batch operations across multiple applications **How it fits into Hoody philosophy:** - Provides unified access to applications regardless of source - Supports authenticated, container-targeted operations via `hoody` CLI - Enables reproducible workflows through profiles and recipes - Integrates with Hoody's job system for async operations **Key concepts:** - **Sources**: Package registries or repositories where applications are found - **Profiles**: Named configurations with default preferences and source overrides - **Recipes**: Saved selector templates for repeatable application resolution - **Selectors**: Query objects that identify target applications --- ## Common Workflows ### 1. Health Check Verify the service is running: ``` hoody app health -c ``` ``` { "status": "healthy", "version": "1.0.0", "uptime": 3600, "timestamp": "2025-01-15T10:30:00Z", "service": "hoody-app", "environment": "production", "region": "us-east-1", "instance": "abc123" } ``` ### 2. Search for Applications Find applications matching a query: ``` hoody app search --app "node" -c ``` ``` { "candidates": [ { "app": "node", "version": "20.10.0", "source": "npm-registry", "rank": 1 } ], "set_id": "search-abc123", "total": 1 } ``` ### 3. Run an Application Execute an application directly: ``` hoody app run --app "node@20" -c ``` ``` { "command": "node", "args": ["--version"], "resolved_app": "node@20.10.0", "source": "npm-registry" } ``` ### 4. Preflight Check Validate execution plan without running: ``` hoody app preflight --app "python@3.11" -c ``` ``` { "app": "python@3.11", "resolved_version": "3.11.7", "source": "pypi", "command": "python3.11", "available": true } ``` ### 5. Manage Package Sources **List all sources:** ``` hoody app sources list -c ``` ``` { "sources": [ { "source_id": "npm-registry", "source_type": "npm", "provider": "npmjs", "enabled": true, "priority": 100, "pin": { "url": "https://registry.npmjs.org" } } ] } ``` **Add a new source:** ``` hoody app sources create \ --source-id "custom-registry" \ --source-type "npm" \ --provider "custom" \ --enabled true \ --priority 50 \ --pin.url "https://custom.registry.com" \ -c ``` ``` { "source_id": "custom-registry", "source_type": "npm", "provider": "custom", "enabled": true, "priority": 50, "pin": { "url": "https://custom.registry.com" } } ``` **Sync a specific source:** ``` hoody app sources sync npm-registry -c ``` ``` { "job_id": "sync-job-abc123", "status": "queued", "source_id": "npm-registry" } ``` **Sync all sources:** ``` hoody app sources sync-all -c ``` ``` { "job_id": "sync-all-job-def456", "status": "queued" } ``` **Get source diagnostics:** ``` hoody app sources diagnostics npm-registry -c ``` ``` { "source_id": "npm-registry", "health": "healthy", "last_sync": "2025-01-15T09:00:00Z", "last_search": "2025-01-15T10:25:00Z", "recent_failures": [] } ``` **Delete a source:** ``` hoody app sources delete custom-registry -c ``` ### 6. Manage Profiles **List profiles:** ``` hoody app profiles list -c ``` ``` { "profiles": [ { "name": "default", "description": "Default profile", "defaults": {}, "sources_mode": "all", "sources": [] } ], "selected": "default" } ``` **Create a profile:** ``` hoody app profiles create \ --name "production" \ --description "Production environment profile" \ -c ``` ``` { "name": "production", "description": "Production environment profile", "defaults": {}, "sources_mode": "all", "sources": [] } ``` **Select a profile:** ``` hoody app profiles select production -c ``` ``` { "selected": "production", "message": "Profile 'production' is now active" } ``` **Delete a profile:** ``` hoody app profiles delete old-profile -c ``` ### 7. Manage Recipes **List recipes:** ``` hoody app recipes list -c ``` ``` { "recipes": [ { "name": "node-lts", "selector": { "app": "node@lts" } } ] } ``` **Create a recipe:** ``` hoody app recipes create \ --name "python-data" \ --selector.app "python@3.11" \ -c ``` ``` { "name": "python-data", "selector": { "app": "python@3.11" } } ``` **Run a recipe:** ``` hoody app recipes run python-data -c ``` ``` { "command": "python3.11", "args": [], "resolved_app": "python@3.11.7", "source": "pypi" } ``` ### 8. Monitor Async Jobs **Check job status:** ``` hoody app jobs sync-job-abc123 -c ``` ``` { "job_id": "sync-job-abc123", "status": "completed", "progress": 100, "result": { "synced": 1500, "errors": 0 } } ``` **Wait for job completion:** ``` hoody app jobs sync-job-abc123 --wait done --timeout-ms 30000 -c ``` ### 9. Get Configuration View full runtime configuration: ``` hoody app config -c ``` ``` { "sources": [], "profiles": [], "selected_profile": "default" } ``` ### 10. Get API Documentation Retrieve OpenAPI spec: ``` hoody app openapi --format yaml -c ``` ``` hoody app openapi --format json -c ``` --- ## Advanced Operations ### Batch Operations Process multiple search or run requests in a single call: ``` hoody app batch \ --items '[ { "request_id": "req-1", "mode": "search", "selector": { "app": "node" } }, { "request_id": "req-2", "mode": "run", "selector": { "app": "python@3.11" } } ]' \ -c ``` ``` { "results": [ { "request_id": "req-1", "status": "success", "candidates": [ { "app": "node", "version": "20.10.0" } ] }, { "request_id": "req-2", "status": "success", "command": "python3.11" } ] } ``` ### Paged Search For large result sets, use paged search with cursor-based pagination: ``` hoody app search-paged \ --selector.app "tool" \ --page-size 10 \ -c ``` ``` { "candidates": [], "cursor": "eyJwYWdlIjoxfQ==", "has_more": true, "total": 150 } ``` **Next page:** ``` hoody app search-paged \ --selector.app "tool" \ --page-size 10 \ --cursor "eyJwYWdlIjoxfQ==" \ -c ``` ### Async Search Jobs Queue long-running searches in the background: ``` hoody app search-jobs --app "complex-query" -c ``` ``` { "job_id": "search-job-xyz789", "status": "queued" } ``` Poll for results: ``` hoody app jobs search-job-xyz789 --wait done -c ``` ### Path-Based Application Resolution Use clean URLs for application resolution: ``` hoody app go "node@20" -c ``` ``` hoody app go "linux/python@3.11" -c ``` ### Terminal-Anchored Resolution Specify both terminal and application in a single path: ``` hoody app go-terminal --terminal-id term-abc --rest "node@20" -c ``` ### Error Recovery Patterns **Source sync failure recovery:** 1. Check source diagnostics: ``` hoody app sources diagnostics failing-source -c ``` 2. If source is unhealthy, disable it: ``` hoody app sources update failing-source --enabled false -c ``` 3. After fixing, re-enable and sync: ``` hoody app sources update failing-source --enabled true -c hoody app sources sync failing-source -c ``` **Job timeout handling:** If a job times out, check its status without waiting: ``` hoody app jobs -c ``` If stuck, the job may need to be retried by re-running the original command. ### Performance Considerations - **Use profiles** to avoid repeating common source configurations - **Use recipes** for frequently-run applications to skip search resolution - **Batch operations** reduce network overhead for multiple requests - **Paged search** prevents memory issues with large result sets - **Async jobs** prevent blocking on long-running sync or search operations - **Source priority** affects search order—put fastest sources first --- ## Quick Reference ### Essential Commands | Command | Description | |---------|-------------| | `hoody app health` | Check service health | | `hoody app search --app ` | Search for applications | | `hoody app run --app ` | Run an application | | `hoody app preflight --app ` | Validate without running | | `hoody app sources list` | List package sources | | `hoody app sources sync` | Sync all sources | | `hoody app profiles list` | List profiles | | `hoody app profiles select ` | Activate a profile | | `hoody app recipes list` | List saved recipes | | `hoody app recipes run ` | Run a saved recipe | | `hoody app jobs ` | Check job status | | `hoody app config` | View full configuration | ### Common Parameters | Parameter | Description | |-----------|-------------| | `-c ` | Target container (required) | | `-o json` | Output as JSON | | `--app ` | Application selector (required for search/run) | | `--name ` | Name for profiles/recipes | | `--enabled ` | Enable/disable sources | | `--priority ` | Source priority (higher = searched first) | | `--wait ` | Wait for job status (e.g., `done`) | | `--timeout-ms ` | Timeout for wait operations | ### Typical Response Formats **Health response** (9 fields): ``` { "status": "healthy", "version": "1.0.0", "uptime": 3600, "timestamp": "2025-01-15T10:30:00Z", "service": "hoody-app", "environment": "production", "region": "us-east-1", "instance": "abc123" } ``` **Job status response:** ``` { "job_id": "job-abc123", "status": "completed", "progress": 100, "result": {} } ``` **Search response:** ``` { "candidates": [], "set_id": "search-abc123", "total": 0 } ``` **Run response:** ``` { "command": "app-name", "args": [], "resolved_app": "app@version", "source": "source-id" } ``` ### Authentication ``` # Login with credentials hoody auth login --username --password # Use token directly hoody app health --token -c # Use environment variable export HOODY_TOKEN= hoody app health -c ```