<!--
hoody-app Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-20T00:38:50.942Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: http


Tokens: 11294

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-app Subskill

## Overview

The **hoody-app** service is the application resolution and execution engine for the Hoody platform. It discovers runnable applications across configured package sources, resolves them into concrete execution plans, and optionally delegates to `hoody-terminal` for direct execution.

### Core Capabilities

- **Application Discovery**: Search across npm, GitHub, Homebrew, and other configured package sources
- **Execution Resolution**: Convert search queries into concrete shell commands with full path resolution
- **Source Management**: Configure and manage package source integrations with sync capabilities
- **Profile System**: Manage user preferences and source overrides that apply across requests
- **Recipe Templates**: Save and reuse complex selector configurations as named templates
- **Batch Operations**: Process multiple search or run operations in a single request
- **Async Job Queue**: Offload long-running searches to background jobs with polling support

### When to Use hoody-app

- Finding applications by name across multiple package registries
- Resolving application selectors to executable commands
- Managing package source configurations and priorities
- Setting user-specific defaults and preferences
- Creating reusable application templates
- Running applications in specific terminals
- Processing multiple application lookups efficiently

### Service Architecture

hoody-app is a **Hoody Kit service** with 33 endpoints across 8 files. Access via the standardized container routing pattern:

```
https://{projectId}-{containerId}-app-{serviceId}.{node}.containers.hoody.com
```

**Key relationships**:
- Works with `hoody-terminal` for actual execution delegation
- Integrates with `hoody-config` for persistence
- Uses `hoody-discovery` for service registration

---

## Common Workflows

### 1. Health Check and Service Verification

Verify service availability before operations:

```
# Health check (unauthenticated)
curl -s \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/health"
```

**Expected Response:**
```
{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00Z",
  "version": "1.0.0",
  "uptime": 86400,
  "connections": 5,
  "memory": {
    "rss": 45000000,
    "heapUsed": 20000000,
    "heapTotal": 30000000
  },
  "dependencies": {
    "terminal": "ok",
    "config": "ok"
  }
}
```

**Verification**: HTTP 200 with `status: ok` confirms service is healthy.

---

### 2. Application Search and Discovery

#### Basic Search (GET)

Search for applications with query parameters:

```
# Search for VS Code
curl -s \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/search?app=vscode"
```

**Expected Response:**
```
{
  "set_id": "abc123-def456",
  "query": {
    "app": "vscode"
  },
  "candidates": [
    {
      "rank": 1,
      "source": "npm",
      "name": "code",
      "version": "1.85.0",
      "install_command": "npm install -g code",
      "run_command": "code",
      "confidence": 0.95
    },
    {
      "rank": 2,
      "source": "homebrew",
      "name": "visual-studio-code",
      "version": "1.85.0",
      "install_command": "brew install --cask visual-studio-code",
      "run_command": "code",
      "confidence": 0.90
    }
  ],
  "total": 2,
  "cached": false
}
```

#### Advanced Search (POST)

For complex queries with full selector:

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/search/paged" \
  -H "Content-Type: application/json" \
  -d '{
    "selector": {
      "app": "python",
      "os": "linux",
      "version": "3.11"
    }
  }'
```

**Expected Response:**
```
{
  "set_id": "xyz789-abc123",
  "query": {
    "app": "python",
    "os": "linux",
    "version": "3.11"
  },
  "candidates": [
    {
      "rank": 1,
      "source": "apt",
      "name": "python3.11",
      "version": "3.11.6",
      "install_command": "sudo apt install python3.11",
      "run_command": "python3.11",
      "confidence": 0.98
    }
  ],
  "total": 1,
  "has_more": false,
  "cursor": null
}
```

**Verification**: Check `candidates` array is populated and `total > 0`.

---

### 3. Application Execution

#### Run via Query Parameters (GET)

Execute an application with minimal configuration:

```
# Run VS Code (returns command only, no terminal delegation)
curl -s \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/run?app=vscode"
```

**Expected Response:**
```
{
  "command": "code",
  "args": [],
  "env": {},
  "cwd": "/home/user",
  "resolved": true,
  "source": "npm",
  "install_command": "npm install -g code"
}
```

#### Run via JSON Body (POST)

For programmatic clients with complex selectors:

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/run" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "node",
    "version": "18",
    "args": ["--version"]
  }'
```

**Expected Response:**
```
{
  "command": "node",
  "args": ["--version"],
  "env": {},
  "cwd": "/home/user",
  "resolved": true,
  "source": "nvm",
  "install_command": "nvm install 18"
}
```

**Verification**: `resolved: true` confirms successful resolution. Use `install_command` if application is missing.

---

### 4. Path-Based Execution (Clean URLs)

#### Direct Application Path

Use clean, bookmarkable URLs for common applications:

```
# Run VS Code via path
curl -s \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/go/vscode"
```


#### Terminal-Anchored Path

Specify both terminal and application:

```
# Run VS Code in specific terminal
curl -s \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/t/term-123/go/vscode"
```

**Use Case**: Bookmarkable URLs for frequently used applications with specific terminals.

---

### 5. Source Management

#### List All Sources

```
curl -s \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/sources"
```

**Expected Response:**
```
[
  {
    "source_id": "npm-registry",
    "provider": "npm",
    "source_type": "registry",
    "enabled": true,
    "priority": 10,
    "config": {
      "registry_url": "https://registry.npmjs.org"
    },
    "pin": {
      "url": null
    }
  },
  {
    "source_id": "homebrew-core",
    "provider": "homebrew",
    "source_type": "formula",
    "enabled": true,
    "priority": 5,
    "config": {
      "tap": "homebrew/core"
    },
    "pin": {
      "url": null
    }
  }
]
```

#### Add New Source

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/sources" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "custom-registry",
    "enabled": true,
    "priority": 15,
    "provider": "npm",
    "source_type": "registry",
    "config": {
      "registry_url": "https://custom-registry.example.com"
    },
    "pin": {
      "url": "https://custom-registry.example.com/packages"
    }
  }'
```

#### Update Source Configuration

```
# Update priority and enable source
curl -s -X PATCH \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/sources/npm-registry" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "priority": 20
  }'
```

#### Delete Source

```
curl -s -X DELETE \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/sources/custom-registry"
```

**Verification**: DELETE returns 204 No Content on success.

---

### 6. Profile Management

#### List Profiles

```
curl -s \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/profiles"
```

#### Create Profile

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/profiles" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "developer",
    "sources": [
      {
        "source_id": "npm-registry",
        "priority": 10
      }
    ]
  }'
```

#### Select Profile

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/profiles/developer/select"
```

**Verification**: After selection, subsequent requests apply profile defaults automatically.

---

## Advanced Operations

### 7. Async Job Processing

#### Queue Background Search

For large result sets or complex queries:

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/search/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "database"
  }'
```

**Expected Response:**
```
{
  "job_id": "job-abc123-def456",
  "status": "queued",
  "created_at": "2025-01-15T10:30:00Z",
  "poll_url": "/api/v1/run/jobs/job-abc123-def456"
}
```

#### Poll Job Status

```
# Poll until completion (long-polling)
curl -s \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/jobs/job-abc123-def456?wait=done&timeout_ms=30000"
```

**Expected Response (completed):**
```
{
  "job_id": "job-abc123-def456",
  "status": "completed",
  "result": {
    "set_id": "set-789",
    "candidates": [
      {
        "rank": 1,
        "source": "apt",
        "name": "postgresql",
        "version": "15.4",
        "install_command": "sudo apt install postgresql",
        "run_command": "psql",
        "confidence": 0.95
      }
    ],
    "total": 1
  },
  "completed_at": "2025-01-15T10:30:05Z"
}
```

**Error Handling**: Check `status` field for `queued`, `running`, `completed`, or `failed`.

---

### 8. Preflight Validation

Validate execution plan without scheduling:

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/preflight" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "docker",
    "os": "linux"
  }'
```

**Expected Response:**
```
{
  "resolved": true,
  "command": "docker",
  "args": [],
  "env": {},
  "cwd": "/home/user",
  "source": "apt",
  "install_command": "sudo apt install docker.io",
  "requirements": {
    "sudo": true,
    "disk_space_mb": 500
  },
  "warnings": []
}
```

**Use Case**: Pre-validate applications before committing to execution.

---

### 9. Batch Operations

Process multiple queries efficiently:

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "request_id": "req-001",
        "mode": "search",
        "selector": {
          "app": "python"
        }
      },
      {
        "request_id": "req-002",
        "mode": "search",
        "selector": {
          "app": "node"
        }
      },
      {
        "request_id": "req-003",
        "mode": "run",
        "selector": {
          "app": "git"
        }
      }
    ]
  }'
```

**Expected Response:**
```
{
  "results": [
    {
      "request_id": "req-001",
      "success": true,
      "result": {
        "set_id": "set-001",
        "candidates": [],
        "total": 3
      }
    },
    {
      "request_id": "req-002",
      "success": true,
      "result": {
        "set_id": "set-002",
        "candidates": [],
        "total": 2
      }
    },
    {
      "request_id": "req-003",
      "success": true,
      "result": {
        "command": "git",
        "args": [],
        "resolved": true
      }
    }
  ],
  "completed": 3,
  "failed": 0
}
```

**Verification**: Check `success` field per item. All items should have `success: true`.

---

### 10. Recipe Management

#### Create Reusable Recipe

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/recipes" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "python-dev-env",
    "selector": {
      "app": "python",
      "version": "3.11"
    },
    "overrides": {
      "install_command": "sudo apt install python3.11 python3.11-venv python3.11-dev"
    }
  }'
```

#### Execute Recipe

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/recipes/python-dev-env/run" \
  -H "Content-Type: application/json" \
  -d '{
    "overrides": {
      "args": ["--version"]
    }
  }'
```

**Verification**: Recipe execution applies stored defaults with runtime overrides.

---

### 11. Source Sync and Diagnostics

#### Sync Specific Source

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/sources/npm-registry/sync"
```

**Expected Response:**
```
{
  "job_id": "sync-abc123",
  "status": "queued",
  "source_id": "npm-registry"
}
```

#### Sync All Sources

```
curl -s -X POST \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/sources/sync"
```

#### Check Source Diagnostics

```
curl -s \
  "https://{PROJECT_ID}-{CONTAINER_ID}-app-{SERVICE_ID}.{NODE}.containers.hoody.com/api/v1/run/sources/npm-registry/diagnostics"
```

**Expected Response:**
```
{
  "source_id": "npm-registry",
  "status": "healthy",
  "last_sync": "2025-01-15T08:00:00Z",
  "last_success": "2025-01-15T08:00:00Z",
  "last_failure": null,
  "error_count": 0,
  "avg_response_ms": 150,
  "packages_indexed": 1250000
}
```

**Error Recovery**: If `status` shows `degraded` or `unhealthy`, check `last_failure` for details.

---

## Quick Reference

### Essential Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/api/v1/run/health` | Service health check |
| `GET` | `/api/v1/run/search?app={name}` | Basic application search |
| `POST` | `/api/v1/run/search/paged` | Advanced paged search |
| `GET` | `/api/v1/run/run?app={name}` | Run application (GET) |
| `POST` | `/api/v1/run/run` | Run application (POST) |
| `GET` | `/api/v1/run/go/{rest}` | Path-based execution |
| `GET` | `/api/v1/run/sources` | List package sources |
| `POST` | `/api/v1/run/sources` | Add package source |
| `GET` | `/api/v1/run/profiles` | List user profiles |
| `POST` | `/api/v1/run/profiles/{name}/select` | Activate profile |
| `GET` | `/api/v1/run/recipes` | List saved recipes |
| `POST` | `/api/v1/run/recipes/{name}/run` | Execute recipe |

### Base URL Pattern

```
https://{projectId}-{containerId}-app-{serviceId}.{node}.containers.hoody.com
```

### Key Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `app` | string | Application name or identifier (required) |
| `os` | string | Target operating system |
| `version` | string | Desired application version |
| `args` | array | Command-line arguments |
| `terminal_id` | string | Target terminal for execution |
| `rest` | string | Path segments for clean URLs |

### Response Patterns

**Successful Search:**
```
{
  "set_id": "uuid",
  "candidates": [],
  "total": 0
}
```

**Successful Run:**
```
{
  "command": "string",
  "args": [],
  "resolved": true
}
```

**Job Queued:**
```
{
  "job_id": "uuid",
  "status": "queued"
}
```

### Workflow Summary

1. **Health Check** → Verify service availability
2. **Search** → Find applications across sources
3. **Preflight** → Validate execution plan
4. **Run** → Execute application or get command
5. **Manage** → Configure sources, profiles, recipes

### Performance Tips

- Use `set_id` from search results for pagination consistency
- Prefer POST `/run` for complex selectors over GET with query params
- Use batch operations for multiple lookups (reduces round trips)
- Enable long-polling (`wait=done`) for async job monitoring
- Sync sources during off-peak hours for best performance