# hoody-exec Subskill ## Overview ### What is hoody-exec? hoody-exec is Hoody's script execution service that turns any TypeScript or JavaScript file into a fully managed API endpoint. Powered by Bun, it provides automatic routing, dependency management, scheduling, monitoring, and OpenAPI generation — all from simple script files. ### When to Use hoody-exec Use hoody-exec when you need to: - **Deploy instant REST API endpoints** from TypeScript/JavaScript files without boilerplate - **Handle webhooks** with automatic JSON parsing and structured responses - **Build data transformation pipelines** and ETL workflows as scripts - **Chain scripts together** to compose complex workflows across endpoints - **Create scheduled tasks** that run on cron-like schedules - **Generate OpenAPI documentation** automatically from your scripts - **Monitor script performance** with built-in metrics and logging ### How It Fits Into Hoody Philosophy hoody-exec embodies Hoody's core principle: **turn any script into an API endpoint**. You write a TypeScript or JavaScript file, deploy it with `hoody exec write`, and it immediately becomes a callable HTTP endpoint. No framework setup, no routing configuration, no deployment pipelines. The service handles: - **Automatic routing** using Next.js-style dynamic routes (`[param]`, `[...slug]`, `[[...path]]`) - **Dependency management** via Bun's native package support - **Magic comments** for declarative configuration within script files - **Shared state** for cross-script data persistence - **Scheduling** for cron-based script execution - **Monitoring** with Prometheus-compatible metrics ### Service Architecture ``` ┌─────────────────────────────────────────────────┐ │ hoody-exec │ ├─────────────────────────────────────────────────┤ │ Scripts Layer │ Routing │ Templates │ │ (write/read/ │ (resolve/ │ (generate/ │ │ delete/list) │ discover) │ preview) │ ├─────────────────────────────────────────────────┤ │ Execution Engine (Bun Runtime) │ ├─────────────────────────────────────────────────┤ │ Logs │ Monitoring │ Shared State │ Schedules │ ├─────────────────────────────────────────────────┤ │ Dependencies │ Packages │ SDKs │ OpenAPI │ └─────────────────────────────────────────────────┘ ``` --- ## Common Workflows ### Workflow 1: Create and Deploy a Script This is the fundamental workflow — write a script, deploy it, and call it. **Step 1: Write a script** ``` hoody exec write -c --path "api/hello.ts" --content 'export default function handler(req) { return { message: "Hello from hoody-exec!", timestamp: new Date().toISOString() }; }' ``` **Step 2: Verify the script exists** ``` hoody exec read -c --path "api/hello.ts" ``` **Step 3: List all scripts** ``` hoody exec list -c ``` **Step 4: View the script directory tree** ``` hoody exec tree -c ``` **Step 5: Execute the script via HTTP** The script is automatically available at: ``` https://{projectId}-{containerId}-exec-{serviceId}.{node}.containers.hoody.icu/api/hello ``` --- ### Workflow 2: Validate Scripts Before Deployment Validate scripts for syntax, types, and dependencies before writing them. **Step 1: Validate TypeScript syntax** ``` hoody exec types -c --code 'export default function handler(req: Request): Response { return new Response("ok"); }' ``` **Step 2: Validate syntax only** ``` hoody exec syntax -c --code 'const x = 1; console.log(x);' ``` **Step 3: Validate dependencies** ``` hoody exec dependencies -c --code 'import { z } from "zod"; export default z.object({ name: z.string() });' ``` **Step 4: Validate return type** ``` hoody exec return-type -c --type-definition '{ status: string; count: number }' --value '{"status": "ok", "count": 42}' ``` **Step 5: Validate magic comments** ``` hoody exec magic-comments -c --code '// @method GET // @path /users export default function handler() { return []; }' ``` **Step 6: Full script validation** ``` hoody exec script -c --code 'export default function handler(req) { return { ok: true }; }' ``` --- ### Workflow 3: Template-Based Script Generation Use templates to scaffold scripts quickly. **Step 1: List available templates** ``` hoody exec list -c ``` **Step 2: Preview a template** ``` hoody exec preview -c --name "rest-api" ``` **Step 3: Generate a script from a template** ``` hoody exec generate -c --name "rest-api" ``` **Step 4: Create a custom template** ``` hoody exec create -c --name "my-webhook" --content 'export default function handler(req) { const body = req.body; // Process webhook payload return { received: true, id: body.id }; }' ``` **Step 5: Update a custom template** ``` hoody exec update -c --name "my-webhook" --content 'export default async function handler(req) { const body = await req.json(); return { received: true, id: body.id, processedAt: Date.now() }; }' ``` **Step 6: Delete a custom template** ``` hoody exec delete -c --name "my-webhook" --yes ``` --- ### Workflow 4: Script Management and Organization Manage scripts with move, delete, and tree operations. **Step 1: List all scripts** ``` hoody exec list -c ``` **Step 2: View the script tree structure** ``` hoody exec tree -c ``` **Step 3: Read a specific script** ``` hoody exec read -c --path "api/users.ts" ``` **Step 4: Move a script to a new location** ``` hoody exec move -c --from "api/old-name.ts" --to "api/new-name.ts" ``` **Step 5: Verify the move** ``` hoody exec read -c --path "api/new-name.ts" ``` **Step 6: Delete a script** ``` hoody exec delete -c --path "api/old-name.ts" --yes ``` --- ### Workflow 5: Logging and Debugging Monitor script execution through logs. **Step 1: List available log files** ``` hoody exec list -c ``` **Step 2: Read a specific log file** ``` hoody exec read -c --file "exec-2025-01-15.log" ``` **Step 3: Stream logs in real-time** ``` hoody exec stream -c --file "exec-2025-01-15.log" ``` **Step 4: Search logs for errors** ``` hoody exec search -c --query "error" --level "error" ``` **Step 5: Clear old logs** ``` hoody exec clear -c --yes ``` --- ### Workflow 6: Shared State Management Use shared state for cross-script data persistence. **Step 1: Set shared state** ``` hoody exec set -c --hostname "my-app.local" --value '{"counter": 0, "lastUpdated": "2025-01-15T00:00:00Z"}' ``` **Step 2: Get shared state** ``` hoody exec get -c --hostname "my-app.local" ``` **Step 3: Update shared state** ``` hoody exec set -c --hostname "my-app.local" --value '{"counter": 1, "lastUpdated": "2025-01-15T12:00:00Z"}' ``` **Step 4: Verify the update** ``` hoody exec get -c --hostname "my-app.local" -o json ``` **Step 5: Clear shared state** ``` hoody exec clear -c --hostname "my-app.local" --yes ``` --- ### Workflow 7: Route Discovery and Testing Understand how URLs map to scripts using Next.js-style routing. **Step 1: Discover all routes** ``` hoody exec discover -c ``` **Step 2: Resolve a specific path** ``` hoody exec resolve -c --path "/api/users/123" ``` **Step 3: Test multiple routes in batch** ``` hoody exec test -c --paths '["/api/users", "/api/users/123", "/api/users/123/posts", "/api/health"]' ``` --- ### Workflow 8: Dependency Management Manage Bun dependencies for your scripts. **Step 1: List bundled dependencies** ``` hoody exec list -c ``` **Step 2: Check if dependencies are satisfied** ``` hoody exec check -c --code 'import { z } from "zod"; import { format } from "date-fns";' ``` **Step 3: Install missing dependencies** ``` hoody exec add-modules -c --modules '["zod", "date-fns"]' ``` **Step 4: Verify installation** ``` hoody exec check -c --code 'import { z } from "zod"; import { format } from "date-fns";' ``` --- ### Workflow 9: Package Management Manage the package.json for your exec environment. **Step 1: Read current package.json** ``` hoody exec read -c ``` **Step 2: Initialize package.json** ``` hoody exec init -c ``` **Step 3: Install packages** ``` hoody exec install -c --packages '["lodash", "axios"]' ``` **Step 4: Update packages** ``` hoody exec update -c --packages '["lodash"]' ``` **Step 5: Pin specific versions** ``` hoody exec pin -c --packages '{"lodash": "4.17.21", "axios": "1.6.2"}' ``` **Step 6: Compare package versions** ``` hoody exec compare -c --packages '["lodash", "axios"]' ``` --- ### Workflow 10: Scheduling Scripts Run scripts on cron-like schedules. **Step 1: List current schedules** ``` hoody exec list -c ``` **Step 2: Trigger a schedule manually** ``` hoody exec trigger -c --schedule-id "daily-report" ``` **Step 3: View schedule execution history** ``` hoody exec history -c --schedule-id "daily-report" ``` **Step 4: Reload schedules from configuration** ``` hoody exec reload -c ``` --- ### Workflow 11: Monitoring and Metrics Monitor script performance and system health. **Step 1: Check system health** ``` hoody exec health -c ``` **Step 2: Get overall stats** ``` hoody exec stats -c ``` **Step 3: View active requests** ``` hoody exec active-requests -c ``` **Step 4: Get script performance metrics** ``` hoody exec performance -c --script "api/users.ts" ``` **Step 5: List monitored scripts** ``` hoody exec list -c ``` **Step 6: Export Prometheus metrics** ``` hoody exec prometheus -c ``` --- ### Workflow 12: Magic Comments Configuration Configure scripts declaratively using magic comments. **Step 1: Get the magic comments schema** ``` hoody exec schema -c ``` **Step 2: Read magic comments from a script** ``` hoody exec read -c --path "api/users.ts" ``` **Step 3: Update magic comments for a script** ``` hoody exec update -c --path "api/users.ts" --comments '{"method": "GET", "path": "/users", "cache": {"ttl": 60}}' ``` **Step 4: Bulk update magic comments across scripts** ``` hoody exec bulk-update -c --updates '{"api/users.ts": {"method": "GET"}, "api/posts.ts": {"method": "GET"}}' ``` --- ### Workflow 13: OpenAPI Documentation Generation Generate OpenAPI specs from your scripts automatically. **Step 1: List scripts with schema information** ``` hoody exec list-user -c ``` **Step 2: Generate OpenAPI spec from scripts** ``` hoody exec generate -c ``` **Step 3: Validate a script's schema file** ``` hoody exec user-schema -c --path "api/users.ts" ``` **Step 4: Serve the generated spec** ``` hoody exec serve -c ``` **Step 5: Serve a specific schema file** ``` hoody exec serve-schema -c --path "api/users.schema.ts" ``` **Step 6: Merge multiple OpenAPI specs** ``` hoody exec merge -c --specs '["spec-users.json", "spec-posts.json"]' ``` --- ### Workflow 14: SDK Management Import and manage SDKs for use in scripts. **Step 1: List available SDKs** ``` hoody exec list -c ``` **Step 2: Import an SDK** ``` hoody exec import -c --sdk "stripe" --version "14.0.0" ``` **Step 3: Get SDK details** ``` hoody exec get -c --id "stripe" ``` **Step 4: Delete an SDK** ``` hoody exec delete -c --id "stripe" --yes ``` --- ### Workflow 15: Cache Management Clear the execution cache when needed. **Step 1: Clear the exec cache** ``` hoody exec cache-clear -c ``` **Step 2: Verify cache is cleared by checking health** ``` hoody exec health -c ``` --- ## Advanced Operations ### Advanced Workflow 1: Full Script Lifecycle A complete lifecycle from creation to monitoring. **Step 1: Validate the script** ``` hoody exec script -c --code 'import { z } from "zod"; const UserSchema = z.object({ name: z.string(), email: z.string().email(), age: z.number().min(0).max(150) }); export default async function handler(req) { const body = await req.json(); const user = UserSchema.parse(body); return { success: true, user }; }' ``` **Step 2: Check dependencies** ``` hoody exec dependencies -c --code 'import { z } from "zod";' ``` **Step 3: Install dependencies if needed** ``` hoody exec add-modules -c --modules '["zod"]' ``` **Step 4: Write the script** ``` hoody exec write -c --path "api/users/create.ts" --content 'import { z } from "zod"; const UserSchema = z.object({ name: z.string(), email: z.string().email(), age: z.number().min(0).max(150) }); export default async function handler(req) { const body = await req.json(); const user = UserSchema.parse(body); return { success: true, user }; }' ``` **Step 5: Verify deployment** ``` hoody exec read -c --path "api/users/create.ts" ``` **Step 6: Test the route** ``` hoody exec resolve -c --path "/api/users/create" ``` **Step 7: Monitor execution** ``` hoody exec performance -c --script "api/users/create.ts" ``` **Step 8: Check logs** ``` hoody exec search -c --query "api/users/create" ``` --- ### Advanced Workflow 2: Script Chaining Pattern Create scripts that call other scripts to compose workflows. **Step 1: Create a data fetching script** ``` hoody exec write -c --path "api/data/fetch.ts" --content 'export default async function handler(req) { const { source } = req.query; const response = await fetch(source); const data = await response.json(); return { data, fetchedAt: Date.now() }; }' ``` **Step 2: Create a transformation script** ``` hoody exec write -c --path "api/data/transform.ts" --content 'export default async function handler(req) { const { data, fields } = req.body; const transformed = data.map(item => { const result = {}; fields.forEach(f => { result[f] = item[f]; }); return result; }); return { transformed, count: transformed.length }; }' ``` **Step 3: Create a pipeline script that chains them** ``` hoody exec write -c --path "api/pipeline.ts" --content 'export default async function handler(req) { const { source, fields } = req.body; // Step 1: Fetch data const fetchRes = await fetch("/api/data/fetch?source=" + encodeURIComponent(source)); const { data } = await fetchRes.json(); // Step 2: Transform data const transformRes = await fetch("/api/data/transform", { method: "POST", body: JSON.stringify({ data, fields }) }); const result = await transformRes.json(); return { pipeline: "complete", ...result }; }' ``` **Step 4: Verify all scripts** ``` hoody exec tree -c ``` **Step 5: Test route resolution** ``` hoody exec test -c --paths '["/api/data/fetch", "/api/data/transform", "/api/pipeline"]' ``` --- ### Advanced Workflow 3: Scheduled Data Pipeline Set up a recurring data processing job. **Step 1: Create the processing script** ``` hoody exec write -c --path "jobs/daily-report.ts" --content 'export default async function handler() { const now = new Date(); const report = { date: now.toISOString().split("T")[0], generatedAt: now.toISOString(), metrics: { requests: Math.floor(Math.random() * 1000), errors: Math.floor(Math.random() * 10), avgLatency: Math.floor(Math.random() * 200) } }; // Store in shared state await fetch("/api/exec/shared-state/set", { method: "POST", body: JSON.stringify({ hostname: "reports.local", value: report }) }); return report; }' ``` **Step 2: List schedules to find the schedule ID** ``` hoody exec list -c ``` **Step 3: Trigger the schedule manually for testing** ``` hoody exec trigger -c --schedule-id "daily-report" ``` **Step 4: Check execution history** ``` hoody exec history -c --schedule-id "daily-report" ``` **Step 5: Verify shared state was updated** ``` hoody exec get -c --hostname "reports.local" -o json ``` --- ### Advanced Workflow 4: Error Recovery and Debugging Handle script failures systematically. **Step 1: Check system health** ``` hoody exec health -c ``` **Step 2: Check active requests for stuck executions** ``` hoody exec active-requests -c ``` **Step 3: Search logs for errors** ``` hoody exec search -c --query "error" --level "error" ``` **Step 4: Read the specific error log** ``` hoody exec read -c --file "exec-errors.log" ``` **Step 5: Validate the failing script** ``` hoody exec script -c --code 'import { readFileSync } from "fs"; export default function handler() { return JSON.parse(readFileSync("data.json", "utf8")); }' ``` **Step 6: Check dependencies** ``` hoody exec check -c --code 'import { readFileSync } from "fs";' ``` **Step 7: Clear cache and restart if needed** ``` hoody exec cache-clear -c ``` ``` hoody exec restart -c --yes ``` **Step 8: Check restart status** ``` hoody exec restart-status -c ``` --- ### Advanced Workflow 5: Performance Optimization Monitor and optimize script performance. **Step 1: Get overall system stats** ``` hoody exec stats -c ``` **Step 2: List all monitored scripts** ``` hoody exec list -c ``` **Step 3: Get performance metrics for specific scripts** ``` hoody exec performance -c --script "api/users.ts" ``` **Step 4: Export Prometheus metrics for external monitoring** ``` hoody exec prometheus -c -o json ``` **Step 5: Check active requests for bottlenecks** ``` hoody exec active-requests -c ``` **Step 6: Review magic comments for caching opportunities** ``` hoody exec read -c --path "api/users.ts" ``` **Step 7: Add caching via magic comments** ``` hoody exec update -c --path "api/users.ts" --comments '{"cache": {"ttl": 300, "key": "users-list"}}' ``` --- ### Advanced Workflow 6: OpenAPI Documentation Pipeline Build comprehensive API documentation from scripts. **Step 1: List all user scripts** ``` hoody exec list-user -c ``` **Step 2: Generate OpenAPI spec** ``` hoody exec generate -c ``` **Step 3: Validate each script's schema** ``` hoody exec user-schema -c --path "api/users.ts" ``` ``` hoody exec user-schema -c --path "api/posts.ts" ``` **Step 4: Merge specs if needed** ``` hoody exec merge -c --specs '["users-spec.json", "posts-spec.json"]' ``` **Step 5: Serve the final spec** ``` hoody exec serve -c ``` --- ## Quick Reference ### Essential Commands | Operation | Command | |-----------|---------| | Write script | `hoody exec write -c --path --content ` | | Read script | `hoody exec read -c --path ` | | Delete script | `hoody exec delete -c --path --yes` | | List scripts | `hoody exec list -c ` | | Script tree | `hoody exec tree -c ` | | Move script | `hoody exec move -c --from --to ` | | Validate script | `hoody exec script -c --code ` | | Health check | `hoody exec health -c ` | | List logs | `hoody exec list -c ` | | Stream logs | `hoody exec stream -c --file ` | | Search logs | `hoody exec search -c --query ` | | Clear logs | `hoody exec clear -c --yes` | | Set shared state | `hoody exec set -c --hostname --value ` | | Get shared state | `hoody exec get -c --hostname ` | | Clear shared state | `hoody exec clear -c --hostname --yes` | | Discover routes | `hoody exec discover -c ` | | Resolve route | `hoody exec resolve -c --path ` | | Test routes | `hoody exec test -c --paths ` | | Get stats | `hoody exec stats -c ` | | Active requests | `hoody exec active-requests -c ` | | Script performance | `hoody exec performance -c --script ` | | Prometheus export | `hoody exec prometheus -c ` | | List templates | `hoody exec list -c ` | | Preview template | `hoody exec preview -c --name ` | | Generate from template | `hoody exec generate -c --name ` | | Create custom template | `hoody exec create -c --name --content ` | | Update custom template | `hoody exec update -c --name --content ` | | Delete custom template | `hoody exec delete -c --name --yes` | | List bundled deps | `hoody exec list -c ` | | Check dependencies | `hoody exec check -c --code ` | | Install dependencies | `hoody exec add-modules -c --modules ` | | Read package.json | `hoody exec read -c ` | | Init package.json | `hoody exec init -c ` | | Install packages | `hoody exec install -c --packages ` | | Update packages | `hoody exec update -c --packages ` | | Pin versions | `hoody exec pin -c --packages ` | | Compare packages | `hoody exec compare -c --packages ` | | List schedules | `hoody exec list -c ` | | Trigger schedule | `hoody exec trigger -c --schedule-id ` | | Reload schedules | `hoody exec reload -c ` | | Schedule history | `hoody exec history -c --schedule-id ` | | Get magic comments schema | `hoody exec schema -c ` | | Read magic comments | `hoody exec read -c --path ` | | Update magic comments | `hoody exec update -c --path --comments ` | | Bulk update magic comments | `hoody exec bulk-update -c --updates ` | | Generate OpenAPI | `hoody exec generate -c ` | | List user scripts | `hoody exec list-user -c ` | | Validate user schema | `hoody exec user-schema -c --path ` | | Serve schema | `hoody exec serve-schema -c --path ` | | Serve spec | `hoody exec serve -c ` | | Merge specs | `hoody exec merge -c --specs ` | | Import SDK | `hoody exec import -c --sdk --version ` | | List SDKs | `hoody exec list -c ` | | Get SDK | `hoody exec get -c --id ` | | Delete SDK | `hoody exec delete -c --id --yes` | | Clear cache | `hoody exec cache-clear -c ` | | Restart server | `hoody exec restart -c --yes` | | Restart status | `hoody exec restart-status -c ` | | Validate TypeScript | `hoody exec types -c --code ` | | Validate syntax | `hoody exec syntax -c --code ` | | Validate dependencies | `hoody exec dependencies -c --code ` | | Validate return type | `hoody exec return-type -c --type-definition --value ` | | Validate magic comments | `hoody exec magic-comments -c --code ` | ### Common Flags | Flag | Description | |------|-------------| | `-c ` | Target container ID (required for all commands) | | `-o json` | Output in JSON format | | `--yes` | Skip confirmation prompts (required for destructive operations) | | `-t ` | API token for authentication | | `--profile ` | Use named configuration profile | ### Typical Response Formats **Script list response:** ``` { "scripts": [ { "path": "api/users.ts", "size": 1024, "modified": "2025-01-15T10:30:00Z" } ], "total": 1 } ``` **Health check response:** ``` { "status": "healthy", "uptime": 86400, "version": "1.0.0" } ``` **Route resolution response:** ``` { "path": "/api/users/123", "script": "api/users/[id].ts", "params": { "id": "123" }, "type": "dynamic" } ``` **Validation response:** ``` { "valid": true, "errors": [] } ``` **Stats response:** ``` { "totalRequests": 15000, "activeRequests": 3, "avgResponseTime": 45, "errorRate": 0.02 } ``` ### Route Types | Type | Pattern | Example | |------|---------|---------| | Static | `/path/to/file` | `/api/users` → `api/users.ts` | | Dynamic | `/path/[param]` | `/api/users/[id]` → `api/users/[id].ts` | | Catch-all | `/path/[...slug]` | `/api/docs/[...slug]` → `api/docs/[...slug].ts` | | Optional catch-all | `/path/[[...path]]` | `/api/pages/[[...path]]` → `api/pages/[[...path]].ts` | ### Error Handling Patterns **Destructive operations require `--yes`:** ``` hoody exec delete -c --path "api/temp.ts" --yes hoody exec clear -c --yes hoody exec restart -c --yes ``` **JSON output for automation:** ``` hoody exec list -c -o json | jq '.scripts[].path' ``` **Environment variable targeting:** ``` export HOODY_CONTAINER= hoody exec list hoody exec health ```