<!--
hoody-watch Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T18:26:53.271Z
Model: mimo-v2.5-pro
Mode: http


Tokens: 4716

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

# hoody-watch Subskill

## Overview

### What is hoody-watch?

hoody-watch is a filesystem monitoring service within the Hoody Kit ecosystem. It enables real-time tracking of file and directory changes across your container's filesystem. When files are created, modified, or deleted in watched paths, hoody-watch captures these events and makes them available through multiple streaming interfaces.

### When to Use hoody-watch

- **Build pipelines**: Trigger actions when source files change
- **Configuration monitoring**: Detect unauthorized config modifications
- **Log aggregation**: Stream new log entries as they're written
- **Development workflows**: Hot-reload or rebuild on file saves
- **Data processing**: React to new files dropped in input directories

### Hoody Philosophy Alignment

hoody-watch embodies the Hoody principle of **autonomous container services**. Each container gets its own isolated watcher instance, accessible via the standard Hoody proxy routing pattern:

```
https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu
```

No external dependencies required — the service runs entirely within your container's context, watching paths relative to your container's filesystem.

### Service Architecture

| Component | Description |
|-----------|-------------|
| Watchers | Configured path monitors with unique IDs |
| Events | Filesystem change records (create, modify, delete) |
| Streaming | SSE and WebSocket interfaces for real-time events |

---

## Common Workflows

### Workflow 1: Health Check

Always verify service availability before operations.

```
# Replace with your actual service URL
BASE_URL="https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"

curl -s "${BASE_URL}/api/v1/watch/health"
```

**Expected Response:**
```
{
  "status": "ok"
}
```

### Workflow 2: Create a File Watcher

Create a watcher to monitor one or more filesystem paths.

```
BASE_URL="https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"

curl -s -X POST "${BASE_URL}/watchers" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["/app/src", "/app/config"]
  }'
```

**Expected Response:**
```
{
  "id": "watcher_abc123",
  "paths": ["/app/src", "/app/config"],
  "status": "active",
  "createdAt": "2025-01-15T10:30:00Z"
}
```

**Save the watcher ID** — you'll need it for all subsequent operations.

### Workflow 3: List All Active Watchers

Retrieve all configured watchers to verify state.

```
BASE_URL="https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"

curl -s "${BASE_URL}/watchers"
```

**Expected Response:**
```
{
  "watchers": [
    {
      "id": "watcher_abc123",
      "paths": ["/app/src", "/app/config"],
      "status": "active",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
}
```

### Workflow 4: Get Watcher Details

Inspect a specific watcher's configuration and status.

```
BASE_URL="https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"
WATCHER_ID="watcher_abc123"

curl -s "${BASE_URL}/watchers/${WATCHER_ID}"
```

**Expected Response:**
```
{
  "id": "watcher_abc123",
  "paths": ["/app/src", "/app/config"],
  "status": "active",
  "createdAt": "2025-01-15T10:30:00Z",
  "eventCount": 42
}
```

### Workflow 5: Poll for Events (HTTP)

Fetch a batch of captured filesystem events.

```
BASE_URL="https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"
WATCHER_ID="watcher_abc123"

curl -s "${BASE_URL}/watchers/${WATCHER_ID}/events"
```

**Expected Response:**
```
{
  "events": [
    {
      "type": "modify",
      "path": "/app/src/index.js",
      "timestamp": "2025-01-15T10:35:00Z"
    },
    {
      "type": "create",
      "path": "/app/config/new.yaml",
      "timestamp": "2025-01-15T10:36:00Z"
    }
  ]
}
```

### Workflow 6: Stream Events via SSE

Subscribe to real-time events using Server-Sent Events.

```
BASE_URL="https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"
WATCHER_ID="watcher_abc123"

curl -s -N "${BASE_URL}/watchers/${WATCHER_ID}/events/sse"
```

**SSE Stream Format:**
```
data: {"type":"modify","path":"/app/src/index.js","timestamp":"2025-01-15T10:35:00Z"}

data: {"type":"create","path":"/app/src/utils.js","timestamp":"2025-01-15T10:35:01Z"}
```

### Workflow 7: Stream Events via WebSocket

For bidirectional or high-throughput event streaming.

```
# Using websocat (install separately)
BASE_URL="wss://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"
WATCHER_ID="watcher_abc123"

websocat "${BASE_URL}/watchers/${WATCHER_ID}/events/ws"
```

### Workflow 8: Delete a Watcher

Clean up watchers when monitoring is no longer needed.

```
BASE_URL="https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"
WATCHER_ID="watcher_abc123"

curl -s -X DELETE "${BASE_URL}/watchers/${WATCHER_ID}"
```

**Expected Response:**
```
{
  "id": "watcher_abc123",
  "deleted": true
}
```

---

## Advanced Operations

### Multi-Path Watcher with Event Processing

Create a watcher and process events in a pipeline:

```
BASE_URL="https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"

# Step 1: Create watcher for multiple critical paths
RESPONSE=$(curl -s -X POST "${BASE_URL}/watchers" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["/app/data", "/app/logs", "/app/config"]
  }')

# Step 2: Extract watcher ID
WATCHER_ID=$(echo "$RESPONSE" | jq -r '.id')

# Step 3: Verify creation
curl -s "${BASE_URL}/watchers/${WATCHER_ID}"

# Step 4: Stream and process events
curl -s -N "${BASE_URL}/watchers/${WATCHER_ID}/events/sse" | \
  while IFS= read -r line; do
    if [[ "$line" == data:* ]]; then
      EVENT="${line#data: }"
      echo "Processing: $EVENT"
      # Add your event handling logic here
    fi
  done
```

### Error Recovery Pattern

Handle common failure scenarios:

```
BASE_URL="https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"

# Attempt health check with retry
MAX_RETRIES=3
RETRY_COUNT=0

while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
  HEALTH=$(curl -s "${BASE_URL}/api/v1/watch/health")
  STATUS=$(echo "$HEALTH" | jq -r '.status')
  
  if [ "$STATUS" = "ok" ]; then
    echo "Service healthy"
    break
  fi
  
  RETRY_COUNT=$((RETRY_COUNT + 1))
  echo "Retry $RETRY_COUNT of $MAX_RETRIES"
  sleep 2
done

if [ $RETRY_COUNT -eq $MAX_RETRIES ]; then
  echo "Service unavailable after $MAX_RETRIES attempts"
  exit 1
fi
```

### Watcher Lifecycle Management

Complete create-monitor-cleanup workflow:

```
BASE_URL="https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu"

# Create watcher
CREATE_RESPONSE=$(curl -s -X POST "${BASE_URL}/watchers" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["/tmp/uploads"]
  }')

WATCHER_ID=$(echo "$CREATE_RESPONSE" | jq -r '.id')
echo "Created watcher: $WATCHER_ID"

# Monitor for specific duration (e.g., 60 seconds)
timeout 60 curl -s -N "${BASE_URL}/watchers/${WATCHER_ID}/events/sse" || true

# Cleanup
curl -s -X DELETE "${BASE_URL}/watchers/${WATCHER_ID}"
echo "Watcher deleted"
```

### Performance Considerations

| Consideration | Recommendation |
|---------------|----------------|
| Path count | Limit to essential paths; each path adds overhead |
| Event volume | Use SSE for high-frequency changes; HTTP polling for low-frequency |
| Connection limits | Reuse SSE/WebSocket connections; avoid creating multiple streams |
| Cleanup | Always delete watchers when done to free resources |

---

## Quick Reference

### Endpoint Summary

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/watch/health` | Service health check |
| GET | `/watchers` | List all watchers |
| POST | `/watchers` | Create watcher (requires `paths` array) |
| GET | `/watchers/{id}` | Get watcher details |
| DELETE | `/watchers/{id}` | Delete watcher |
| GET | `/watchers/{id}/events` | Poll for events |
| GET | `/watchers/{id}/events/sse` | Stream events (SSE) |
| GET | `/watchers/{id}/events/ws` | Stream events (WebSocket) |

### Base URL Pattern

```
https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.icu
```

### Essential Parameters

| Endpoint | Parameter | Type | Required |
|----------|-----------|------|----------|
| POST `/watchers` | `paths` | array | Yes |
| GET/DELETE `/watchers/{id}` | `id` (path) | string | Yes |
| GET `/watchers/{id}/events*` | `id` (path) | string | Yes |

### Typical Response Formats

**Single Resource:**
```
{
  "id": "watcher_abc123",
  "paths": ["/app/src"],
  "status": "active",
  "createdAt": "2025-01-15T10:30:00Z"
}
```

**Collection:**
```
{
  "watchers": []
}
```

**Event:**
```
{
  "type": "modify",
  "path": "/app/src/file.js",
  "timestamp": "2025-01-15T10:35:00Z"
}
```

### curl Flags Reference

| Flag | Purpose |
|------|---------|
| `-s` | Silent mode (required) |
| `` | 10-minute timeout (required) |
| `-N` | No buffer (for SSE streaming) |
| `-X POST/DELETE` | HTTP method override |