openhome-cli 0.1.0

package/src/validation/rules.ts

@@ -0,0 +1,71 @@
+export const REQUIRED_FILES = ["main.py", "README.md", "__init__.py"];
+
+export const BLOCKED_IMPORTS = [
+  "redis",
+  "from src.utils.db_handler",
+  "connection_manager",
+  "user_config",
+];
+
+export interface BlockedPattern {
+  regex: RegExp;
+  message: string;
+}
+
+export const BLOCKED_PATTERNS: BlockedPattern[] = [
+  {
+    regex: /\bprint\s*\(/,
+    message: "Use self.worker.editor_logging_handler instead of print()",
+  },
+  {
+    regex: /\basyncio\.sleep\s*\(/,
+    message: "Use self.worker.session_tasks.sleep() instead",
+  },
+  {
+    regex: /\basyncio\.create_task\s*\(/,
+    message: "Use self.worker.session_tasks.create() instead",
+  },
+  { regex: /\bexec\s*\(/, message: "exec() not allowed" },
+  { regex: /\beval\s*\(/, message: "eval() not allowed" },
+  { regex: /\bpickle\./, message: "pickle not allowed" },
+  { regex: /\bdill\./, message: "dill not allowed" },
+  { regex: /\bshelve\./, message: "shelve not allowed" },
+  { regex: /\bmarshal\./, message: "marshal not allowed" },
+  {
+    regex: /\bopen\s*\(/,
+    message: "raw open() not allowed — use capability_worker file helpers",
+  },
+  { regex: /\bassert\s+/, message: "assert not allowed" },
+  { regex: /\bhashlib\.md5\s*\(/, message: "MD5 not allowed" },
+];
+
+export interface RequiredPattern {
+  regex: RegExp;
+  message: string;
+}
+
+export const REQUIRED_PATTERNS: RequiredPattern[] = [
+  {
+    regex: /resume_normal_flow\s*\(/,
+    message: "resume_normal_flow() must be called",
+  },
+  {
+    regex: /class\s+\w+.*MatchingCapability/,
+    message: "Class must extend MatchingCapability",
+  },
+  { regex: /def\s+call\s*\(/, message: "Must have a call() method" },
+  {
+    regex: /worker\s*:\s*AgentWorker\s*=\s*None/,
+    message: "Must declare worker: AgentWorker = None",
+  },
+  {
+    regex: /capability_worker\s*:\s*CapabilityWorker\s*=\s*None/,
+    message: "Must declare capability_worker: CapabilityWorker = None",
+  },
+];
+
+export const REGISTER_CAPABILITY_PATTERN = /#\s?\{\{register[_ ]capability\}\}/;
+
+export const HARDCODED_KEY_PATTERN = /(sk_|sk-|key_)[a-zA-Z0-9]{20,}/;
+
+export const MULTIPLE_CLASSES_PATTERN = /^class\s+/gm;

package/src/validation/validator.ts

@@ -0,0 +1,204 @@
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import {
+  REQUIRED_FILES,
+  BLOCKED_IMPORTS,
+  BLOCKED_PATTERNS,
+  REQUIRED_PATTERNS,
+  REGISTER_CAPABILITY_PATTERN,
+  HARDCODED_KEY_PATTERN,
+  MULTIPLE_CLASSES_PATTERN,
+} from "./rules.js";
+
+export interface ValidationIssue {
+  severity: "error" | "warning";
+  message: string;
+  file?: string;
+}
+
+export interface ValidationResult {
+  passed: boolean;
+  errors: ValidationIssue[];
+  warnings: ValidationIssue[];
+}
+
+function readFile(filePath: string): string | null {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export function validateAbility(dirPath: string): ValidationResult {
+  const errors: ValidationIssue[] = [];
+  const warnings: ValidationIssue[] = [];
+
+  // 1. Check required files exist
+  for (const required of REQUIRED_FILES) {
+    const fullPath = join(dirPath, required);
+    if (!existsSync(fullPath)) {
+      errors.push({
+        severity: "error",
+        message: `Missing required file: ${required}`,
+        file: required,
+      });
+    }
+  }
+
+  // 2. Validate config.json
+  const configPath = join(dirPath, "config.json");
+  if (existsSync(configPath)) {
+    const configContent = readFile(configPath);
+    if (configContent) {
+      try {
+        const config = JSON.parse(configContent) as Record<string, unknown>;
+        if (typeof config.unique_name !== "string" || !config.unique_name) {
+          errors.push({
+            severity: "error",
+            message: "config.json: unique_name must be a non-empty string",
+            file: "config.json",
+          });
+        }
+        if (
+          !Array.isArray(config.matching_hotwords) ||
+          !(config.matching_hotwords as unknown[]).every(
+            (h) => typeof h === "string",
+          )
+        ) {
+          errors.push({
+            severity: "error",
+            message:
+              "config.json: matching_hotwords must be an array of strings",
+            file: "config.json",
+          });
+        }
+      } catch {
+        errors.push({
+          severity: "error",
+          message: "config.json: invalid JSON",
+          file: "config.json",
+        });
+      }
+    }
+  } else {
+    errors.push({
+      severity: "error",
+      message: "Missing required file: config.json",
+      file: "config.json",
+    });
+  }
+
+  // 3. Validate main.py in detail
+  const mainPath = join(dirPath, "main.py");
+  const mainContent = readFile(mainPath);
+
+  if (mainContent) {
+    const lines = mainContent.split("\n");
+
+    // Check blocked imports — only match actual import/from statements, not substrings in strings
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      // Skip lines that are clearly string content (inside quotes)
+      if (
+        !line.startsWith("import ") &&
+        !line.startsWith("from ") &&
+        !line.includes("import ")
+      )
+        continue;
+      for (const blocked of BLOCKED_IMPORTS) {
+        if (line.includes(blocked)) {
+          errors.push({
+            severity: "error",
+            message: `Blocked import "${blocked}" on line ${i + 1}`,
+            file: "main.py",
+          });
+        }
+      }
+    }
+
+    // Check blocked patterns (line by line)
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      for (const { regex, message } of BLOCKED_PATTERNS) {
+        if (regex.test(line)) {
+          errors.push({
+            severity: "error",
+            message: `${message} (line ${i + 1})`,
+            file: "main.py",
+          });
+        }
+      }
+    }
+
+    // Check required patterns (whole file)
+    for (const { regex, message } of REQUIRED_PATTERNS) {
+      if (!regex.test(mainContent)) {
+        errors.push({ severity: "error", message, file: "main.py" });
+      }
+    }
+
+    // Check register_capability tag
+    if (!REGISTER_CAPABILITY_PATTERN.test(mainContent)) {
+      errors.push({
+        severity: "error",
+        message: "Missing #{{register_capability}} tag in main.py",
+        file: "main.py",
+      });
+    }
+
+    // Check for hardcoded keys (warning)
+    const keyMatches = mainContent.match(HARDCODED_KEY_PATTERN);
+    if (keyMatches) {
+      warnings.push({
+        severity: "warning",
+        message: `Possible hardcoded API key detected in main.py — use capability_worker.get_single_key() instead`,
+        file: "main.py",
+      });
+    }
+
+    // Check for multiple classes (warning)
+    const classMatches = mainContent.match(MULTIPLE_CLASSES_PATTERN);
+    if (classMatches && classMatches.length > 1) {
+      warnings.push({
+        severity: "warning",
+        message: `Multiple class definitions found (${classMatches.length}). Only one MatchingCapability class is expected.`,
+        file: "main.py",
+      });
+    }
+  }
+
+  // 4. Scan all .py files for blocked patterns
+  let pyFiles: string[] = [];
+  try {
+    pyFiles = readdirSync(dirPath).filter(
+      (f) => f.endsWith(".py") && f !== "main.py",
+    );
+  } catch {
+    // ignore
+  }
+
+  for (const pyFile of pyFiles) {
+    const content = readFile(join(dirPath, pyFile));
+    if (!content) continue;
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      for (const { regex, message } of BLOCKED_PATTERNS) {
+        if (regex.test(line)) {
+          errors.push({
+            severity: "error",
+            message: `${message} (line ${i + 1})`,
+            file: pyFile,
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    passed: errors.length === 0,
+    errors,
+    warnings,
+  };
+}

package/tasks/feature-request-sdk-api.md

@@ -0,0 +1,246 @@
+# Feature Request: SDK API Endpoints for Ability Management
+
+**From:** OpenHome CLI Team
+**Date:** 2026-03-18
+**Priority:** High
+**Context:** Building an open-source CLI tool (`openhome-cli`) for developers to manage abilities from the terminal
+
+---
+
+## Summary
+
+The OpenHome SDK currently exposes one endpoint (`POST /api/sdk/get_personalities`). To enable CLI-based ability deployment, we need CRUD endpoints for abilities.
+
+The CLI is fully built and ready to call these endpoints — it currently falls back to saving a zip locally with instructions to upload via the web dashboard.
+
+---
+
+## Current State
+
+| Capability | Web Dashboard | SDK/API | CLI Ready? |
+|-----------|--------------|---------|------------|
+| List agents | Yes | **Yes** (`get_personalities`) | Yes |
+| Create ability | Yes | No | Yes (blocked) |
+| List abilities | Yes | No | Yes (blocked) |
+| Get ability detail | Yes | No | Yes (blocked) |
+| Delete ability | Yes | No | Not yet |
+| Update ability code | Yes (Live Editor) | No | Not yet |
+
+---
+
+## Requested Endpoints
+
+### 1. `POST /api/sdk/abilities` — Create/Upload Ability
+
+Upload a new ability with all metadata matching the web form.
+
+**Request:** `multipart/form-data`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `api_key` | string | Yes | Authentication |
+| `ability` | file (zip) | Yes | Ability code archive |
+| `image` | file (png/jpg) | Yes | Marketplace icon |
+| `name` | string | Yes | Unique ability name |
+| `description` | string | Yes | Marketplace description |
+| `category` | enum | Yes | `skill`, `brain_skill`, `background_daemon` |
+| `matching_hotwords` | JSON string | Yes | Array of trigger words |
+| `personality_id` | string | No | Agent to attach ability to |
+
+**Response (200):**
+```json
+{
+  "ability_id": "abl_abc123",
+  "unique_name": "my-weather-bot",
+  "version": 1,
+  "status": "processing",
+  "message": "Ability uploaded successfully"
+}
+```
+
+**Errors:**
+- `401` — Invalid API key
+- `400 VALIDATION_FAILED` — Missing files, bad config, blocked imports
+- `409` — Ability with this name already exists (use update endpoint instead)
+
+---
+
+### 2. `GET /api/sdk/abilities` — List User's Abilities
+
+**Request:**
+```
+POST /api/sdk/abilities/list
+Content-Type: application/json
+
+{
+  "api_key": "..."
+}
+```
+
+(Using POST with `api_key` in body to match the existing `get_personalities` pattern.)
+
+**Response (200):**
+```json
+{
+  "abilities": [
+    {
+      "ability_id": "abl_abc123",
+      "unique_name": "weather-check",
+      "name": "Weather Check",
+      "description": "Check the weather by city",
+      "category": "skill",
+      "version": 3,
+      "status": "active",
+      "personality_ids": ["pers_alice"],
+      "created_at": "2026-01-10T12:00:00Z",
+      "updated_at": "2026-03-01T09:30:00Z"
+    }
+  ]
+}
+```
+
+---
+
+### 3. `POST /api/sdk/abilities/get` — Get Ability Detail
+
+**Request:**
+```json
+{
+  "api_key": "...",
+  "ability_id": "abl_abc123"
+}
+```
+
+**Response:** Same as list item plus:
+```json
+{
+  "matching_hotwords": ["check weather", "weather please"],
+  "validation_errors": [],
+  "deploy_history": [
+    {
+      "version": 3,
+      "status": "success",
+      "timestamp": "2026-03-01T09:30:00Z"
+    }
+  ]
+}
+```
+
+---
+
+### 4. `POST /api/sdk/abilities/delete` — Delete Ability
+
+**Request:**
+```json
+{
+  "api_key": "...",
+  "ability_id": "abl_abc123"
+}
+```
+
+**Response (200):**
+```json
+{
+  "message": "Ability deleted",
+  "ability_id": "abl_abc123"
+}
+```
+
+---
+
+## Authentication Pattern
+
+Following the existing `get_personalities` pattern: `api_key` in the JSON body rather than Bearer header. This keeps the SDK consistent. (The CLI also sends a Bearer header for forward compatibility.)
+
+---
+
+## Why This Matters
+
+1. **Developer experience** — Developers want to stay in their terminal during ability development: edit code → deploy → test → iterate
+2. **CI/CD** — Teams can automate ability deployment in their pipelines
+3. **Open source adoption** — A CLI lowers the barrier for the developer community
+4. **Parity with modern platforms** — Vercel, Netlify, Cloudflare Workers, etc. all have CLI deploy tools
+
+---
+
+## What's Already Built
+
+The CLI (`openhome-cli`) handles:
+- Login/logout with API key (macOS Keychain + config fallback)
+- Agent listing (using existing `get_personalities`)
+- Ability scaffolding with templates (Skill, Brain Skill, Background Daemon)
+- Validation (required files, Python patterns, blocked imports)
+- ZIP creation with security exclusions
+- Multipart form upload with name, description, image, category, trigger words
+- Graceful fallback when endpoints return NOT_IMPLEMENTED
+- Interactive arrow-key menu (bare `openhome` command)
+- Direct subcommands (`openhome deploy ./my-ability --dry-run`)
+- Mock mode for testing without network
+
+**The CLI is ready to ship the moment these endpoints are live.**
+
+---
+
+## Already Working: WebSocket Chat + Ability Triggering
+
+We discovered the WebSocket endpoint is live:
+
+```
+wss://app.openhome.com/websocket/voice-stream/{API_KEY}/{AGENT_ID}
+```
+
+The CLI now has an `openhome chat` command that connects to this WebSocket and lets developers:
+- Send text messages to their agent from the terminal
+- **Trigger abilities by sending trigger words** (e.g., typing "play aquaprime" activates the ability)
+- Receive text responses back in real-time
+- Test ability trigger words without needing voice/browser
+
+This is a powerful development tool — developers can test whether their trigger words activate abilities correctly without leaving the terminal.
+
+---
+
+## Additional Feature Requests: Device/Agent Control
+
+The dashboard exposes these controls that would be valuable as SDK endpoints:
+
+### 5. Agent Control Endpoints (Proposed)
+
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /api/sdk/agents/restart` | Restart an agent (equivalent to "Restart Agent" button) |
+| `POST /api/sdk/agents/settings` | Update agent settings (voice, LLM, STT provider, temperature, etc.) |
+| `GET /api/sdk/agents/settings` | Read current agent settings |
+
+These would enable CLI commands like:
+- `openhome restart [agent]` — restart an agent remotely
+- `openhome config [agent] --voice <id>` — change voice settings
+- `openhome config [agent] --temperature 0.7` — adjust LLM temperature
+
+### 6. DevKit Hardware Control (Future)
+
+For OpenHome DevKit (Raspberry Pi) users, these would enable remote management:
+- Volume control
+- Start/stop agent session
+- Reboot device
+
+---
+
+## Category Enum Clarification
+
+The web form uses three buttons: **Skill**, **Brain Skill**, **Background Daemon**. What string values should we send in the API?
+
+Suggested: `"skill"`, `"brain_skill"`, `"background_daemon"`
+
+Please confirm the exact enum values the backend expects.
+
+---
+
+## Open Questions
+
+1. What are the exact category enum values? (`skill` / `brain_skill` / `background_daemon`?)
+2. Is there a max file size for the zip upload?
+3. Is there a max image size or required dimensions for the icon?
+4. Should `name` be globally unique or scoped to the user's account?
+5. Can an ability be updated (new version) via the same create endpoint, or is a separate update endpoint needed?
+6. Are there rate limits on the upload endpoint?
+7. Should the response include a URL to the ability in the web editor?