@useconductor/conductor 1.0.0

package/src/plugins/builtin/homekit.ts

@@ -0,0 +1,389 @@
+/**
+ * HomeKit Plugin — TheAlxLabs / Conductor
+ *
+ * Control HomeKit smart home devices via the Homebridge UI REST API
+ * (homebridge-config-ui-x). Requires Homebridge with the UI plugin installed.
+ *
+ * Setup:
+ *   1. Install Homebridge: https://homebridge.io
+ *      (homebridge-config-ui-x is included by default with most install methods)
+ *   2. Run: conductor plugins config homekit base_url http://homebridge.local:8581
+ *   3. Run: conductor plugins config homekit username admin
+ *   4. Run: conductor plugins config homekit password <YOUR_PASSWORD>
+ *
+ * Keychain entries: homekit/base_url, homekit/username, homekit/password
+ */
+
+import { Plugin, PluginTool } from '../manager.js';
+import { Conductor } from '../../core/conductor.js';
+import { Keychain } from '../../security/keychain.js';
+
+export class HomeKitPlugin implements Plugin {
+  name = 'homekit';
+  description = 'Control HomeKit smart home devices via Homebridge — list, get, and control accessories';
+  version = '1.0.0';
+
+  configSchema = {
+    fields: [
+      {
+        key: 'base_url',
+        label: 'Homebridge URL',
+        type: 'string' as const,
+        required: true,
+        secret: false,
+        description: 'e.g. http://homebridge.local:8581 or http://192.168.1.100:8581',
+      },
+      {
+        key: 'username',
+        label: 'Homebridge Username',
+        type: 'string' as const,
+        required: true,
+        secret: false,
+        description: 'Your Homebridge UI login username (default: admin)',
+      },
+      {
+        key: 'password',
+        label: 'Homebridge Password',
+        type: 'password' as const,
+        required: true,
+        secret: true,
+        service: 'homekit',
+      },
+    ],
+    setupInstructions:
+      'Install Homebridge (https://homebridge.io) on your local network. ' +
+      'The homebridge-config-ui-x plugin must be installed (it is by default with most install methods). ' +
+      'Find your Homebridge URL by opening the Homebridge UI in a browser (usually http://homebridge.local:8581 ' +
+      'or http://<your-pi-ip>:8581).',
+  };
+
+  private keychain!: Keychain;
+  private cachedToken: string | null = null;
+  private tokenExpiry: number = 0;
+
+  async initialize(conductor: Conductor): Promise<void> {
+    this.keychain = new Keychain(conductor.getConfig().getConfigDir());
+  }
+
+  isConfigured(): boolean {
+    return true;
+  }
+
+  private async getCredentials(): Promise<{ baseUrl: string; username: string; password: string }> {
+    const rawUrl = await this.keychain.get('homekit', 'base_url');
+    const username = await this.keychain.get('homekit', 'username');
+    const password = await this.keychain.get('homekit', 'password');
+
+    if (!rawUrl) {
+      throw new Error(
+        'Homebridge URL not configured.\n' +
+          'Run: conductor plugins config homekit base_url http://homebridge.local:8581',
+      );
+    }
+    if (!username) {
+      throw new Error('Homebridge username not configured.\n' + 'Run: conductor plugins config homekit username admin');
+    }
+    if (!password) {
+      throw new Error(
+        'Homebridge password not configured.\n' + 'Run: conductor plugins config homekit password <YOUR_PASSWORD>',
+      );
+    }
+
+    return { baseUrl: rawUrl.replace(/\/$/, ''), username, password };
+  }
+
+  private async getToken(): Promise<string> {
+    if (this.cachedToken && Date.now() < this.tokenExpiry - 5 * 60 * 1000) {
+      return this.cachedToken;
+    }
+
+    const { baseUrl, username, password } = await this.getCredentials();
+
+    const res = await fetch(`${baseUrl}/api/auth/sign-in`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username, password }),
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => res.statusText);
+      throw new Error(`Homebridge auth failed (${res.status}): ${text}`);
+    }
+
+    const data = (await res.json()) as any;
+    if (!data.access_token) {
+      throw new Error('Homebridge did not return an access token. Check credentials.');
+    }
+
+    this.cachedToken = data.access_token;
+    this.tokenExpiry = Date.now() + (data.expires_in ?? 28_800) * 1000;
+    return this.cachedToken!;
+  }
+
+  private async homebridgeFetch(path: string, options: { method?: string; body?: any } = {}): Promise<any> {
+    const { baseUrl } = await this.getCredentials();
+    const token = await this.getToken();
+
+    const res = await fetch(`${baseUrl}${path}`, {
+      method: options.method ?? 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+
+    if (res.status === 204) return {};
+
+    if (res.status === 401) {
+      this.cachedToken = null;
+      throw new Error('Homebridge session expired. Please retry the request.');
+    }
+
+    if (!res.ok) {
+      const err = (await res.json().catch(() => ({ message: res.statusText }))) as any;
+      throw new Error(`Homebridge API ${res.status}: ${err.message ?? res.statusText}`);
+    }
+
+    return res.json();
+  }
+
+  private formatAccessory(acc: any) {
+    return {
+      uniqueId: acc.uniqueId,
+      name: acc.serviceName ?? acc.displayName ?? 'Unknown',
+      type: acc.humanType ?? acc.type ?? 'Unknown',
+      room: acc.roomName ?? null,
+      values: acc.values ?? {},
+      on: acc.values?.On ?? null,
+      reachable: acc.reachable ?? true,
+    };
+  }
+
+  getTools(): PluginTool[] {
+    return [
+      // ── homekit_status ────────────────────────────────────────────────────
+      {
+        name: 'homekit_status',
+        description: 'Check Homebridge connection status, version, and a summary of all accessories',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+          const [accessoriesResult, serverResult] = await Promise.allSettled([
+            this.homebridgeFetch('/api/accessories'),
+            this.homebridgeFetch('/api/server/version'),
+          ]);
+
+          const accessories = accessoriesResult.status === 'fulfilled' ? (accessoriesResult.value as any[]) : [];
+          const server = serverResult.status === 'fulfilled' ? (serverResult.value as any) : {};
+
+          const byType: Record<string, number> = {};
+          for (const acc of accessories) {
+            const type = acc.humanType ?? 'Unknown';
+            byType[type] = (byType[type] ?? 0) + 1;
+          }
+
+          const { baseUrl } = await this.getCredentials();
+
+          return {
+            connected: accessoriesResult.status === 'fulfilled',
+            homebridgeUrl: baseUrl,
+            homebridgeVersion: server.homebridgeVersion ?? server.currentVersion ?? 'unknown',
+            nodeVersion: server.nodeVersion ?? 'unknown',
+            totalAccessories: accessories.length,
+            byType,
+          };
+        },
+      },
+
+      // ── homekit_accessories ───────────────────────────────────────────────
+      {
+        name: 'homekit_accessories',
+        description: 'List all HomeKit accessories with their current state',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            type: {
+              type: 'string',
+              description: 'Filter by accessory type (e.g. "Lightbulb", "Switch", "Thermostat", "Lock", "Fan")',
+            },
+            room: {
+              type: 'string',
+              description: 'Filter by room name (partial match, case-insensitive)',
+            },
+          },
+        },
+        handler: async ({ type, room }: any) => {
+          const accessories = (await this.homebridgeFetch('/api/accessories')) as any[];
+          let filtered = accessories;
+
+          if (type) {
+            const q = type.toLowerCase();
+            filtered = filtered.filter((a: any) => (a.humanType ?? a.type ?? '').toLowerCase().includes(q));
+          }
+
+          if (room) {
+            const q = room.toLowerCase();
+            filtered = filtered.filter((a: any) => (a.roomName ?? '').toLowerCase().includes(q));
+          }
+
+          return {
+            count: filtered.length,
+            accessories: filtered.map(this.formatAccessory.bind(this)),
+          };
+        },
+      },
+
+      // ── homekit_get_accessory ─────────────────────────────────────────────
+      {
+        name: 'homekit_get_accessory',
+        description: 'Get the current state and all characteristics of a specific HomeKit accessory',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            uniqueId: {
+              type: 'string',
+              description: 'Accessory uniqueId (from homekit_accessories)',
+            },
+          },
+          required: ['uniqueId'],
+        },
+        handler: async ({ uniqueId }: any) => {
+          const acc = await this.homebridgeFetch(`/api/accessories/${encodeURIComponent(uniqueId)}`);
+          return {
+            ...this.formatAccessory(acc),
+            serviceCharacteristics: (acc.serviceCharacteristics ?? []).map((c: any) => ({
+              type: c.type,
+              description: c.description,
+              value: c.value,
+              format: c.format,
+              unit: c.unit ?? null,
+              minValue: c.minValue ?? null,
+              maxValue: c.maxValue ?? null,
+              canRead: c.canRead ?? true,
+              canWrite: c.canWrite ?? false,
+            })),
+          };
+        },
+      },
+
+      // ── homekit_set ───────────────────────────────────────────────────────
+      {
+        name: 'homekit_set',
+        description:
+          'Set a characteristic on a HomeKit accessory. ' +
+          'Common examples: On (true/false), Brightness (0-100), ' +
+          'TargetTemperature (degrees), Hue (0-360), Saturation (0-100), ' +
+          'LockTargetState (0=unsecured, 1=secured).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            uniqueId: {
+              type: 'string',
+              description: 'Accessory uniqueId (from homekit_accessories)',
+            },
+            characteristicType: {
+              type: 'string',
+              description: 'The characteristic to set (e.g. "On", "Brightness", "TargetTemperature", "Hue")',
+            },
+            value: {
+              description: 'The value to set (boolean, number, or string)',
+            },
+          },
+          required: ['uniqueId', 'characteristicType', 'value'],
+        },
+        requiresApproval: true,
+        handler: async ({ uniqueId, characteristicType, value }: any) => {
+          await this.homebridgeFetch(`/api/accessories/${encodeURIComponent(uniqueId)}`, {
+            method: 'PUT',
+            body: { characteristicType, value },
+          });
+
+          const updated = await this.homebridgeFetch(`/api/accessories/${encodeURIComponent(uniqueId)}`);
+
+          return {
+            success: true,
+            set: { characteristicType, value },
+            accessory: this.formatAccessory(updated),
+          };
+        },
+      },
+
+      // ── homekit_toggle ────────────────────────────────────────────────────
+      {
+        name: 'homekit_toggle',
+        description:
+          'Toggle a HomeKit accessory on or off by name. ' +
+          'Finds the accessory by partial name match and flips (or sets) its On state.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'Accessory name (partial match, case-insensitive)',
+            },
+            on: {
+              type: 'boolean',
+              description: 'Force on (true) or off (false). If omitted, toggles the current state.',
+            },
+          },
+          required: ['name'],
+        },
+        requiresApproval: true,
+        handler: async ({ name, on }: any) => {
+          const accessories = (await this.homebridgeFetch('/api/accessories')) as any[];
+          const q = name.toLowerCase();
+          const acc = accessories.find((a: any) => (a.serviceName ?? a.displayName ?? '').toLowerCase().includes(q));
+
+          if (!acc) {
+            const available = accessories
+              .map((a: any) => a.serviceName ?? a.displayName)
+              .filter(Boolean)
+              .join(', ');
+            return {
+              error: `No accessory found matching "${name}".`,
+              available,
+            };
+          }
+
+          const currentOn = acc.values?.On ?? false;
+          const targetOn = on !== undefined ? on : !currentOn;
+
+          await this.homebridgeFetch(`/api/accessories/${encodeURIComponent(acc.uniqueId)}`, {
+            method: 'PUT',
+            body: { characteristicType: 'On', value: targetOn },
+          });
+
+          return {
+            success: true,
+            accessory: acc.serviceName ?? acc.displayName,
+            uniqueId: acc.uniqueId,
+            previousState: currentOn,
+            on: targetOn,
+          };
+        },
+      },
+
+      // ── homekit_rooms ─────────────────────────────────────────────────────
+      {
+        name: 'homekit_rooms',
+        description: 'Get the room layout from Homebridge — shows which accessories are in which rooms',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+          const layout = (await this.homebridgeFetch('/api/accessories/layout')) as any[];
+          return {
+            count: layout.length,
+            rooms: layout.map((room: any) => ({
+              name: room.name ?? 'Default Room',
+              accessories: (room.services ?? []).map((s: any) => ({
+                uniqueId: s.uniqueId,
+                name: s.customName ?? s.serviceName ?? s.displayName,
+                type: s.humanType ?? s.type,
+              })),
+            })),
+          };
+        },
+      },
+    ];
+  }
+}

package/src/plugins/builtin/index.ts

@@ -0,0 +1,116 @@
+import { Plugin } from '../manager.js';
+
+// ── Core utilities ─────────────────────────────────────────────────────────
+import { CryptoPlugin } from './crypto.js';
+import { WeatherPlugin } from './weather.js';
+import { SystemInfoPlugin } from './system.js';
+import { URLToolsPlugin } from './url-tools.js';
+import { FunPlugin } from './fun.js';
+import { HashPlugin } from './hash.js';
+import { TranslatePlugin } from './translate.js';
+import { CalculatorPlugin } from './calculator.js';
+import { ColorPlugin } from './colors.js';
+import { NetworkPlugin } from './network.js';
+import { TextToolsPlugin } from './text-tools.js';
+import { GitHubPlugin } from './github.js';
+import { TimezonePlugin } from './timezone.js';
+
+// ── Memory & scheduling ────────────────────────────────────────────────────
+import { MemoryPlugin } from './memory.js';
+import { NotesPlugin } from './notes.js';
+import { CronPlugin } from './cron.js';
+
+// ── Google services ────────────────────────────────────────────────────────
+import { GmailPlugin } from './gmail.js';
+import { GoogleCalendarPlugin } from './gcal.js';
+import { GoogleDrivePlugin } from './gdrive.js';
+
+// ── Developer tools ────────────────────────────────────────────────────────
+import { GitHubActionsPlugin } from './github-actions.js';
+import { VercelPlugin } from './vercel.js';
+import { N8nPlugin } from './n8n.js';
+
+// ── Infrastructure ─────────────────────────────────────────────────────────
+import { DockerPlugin } from './docker.js';
+import { DatabasePlugin } from './database.js';
+import { ShellPlugin } from './shell.js';
+
+// ── Third-party services ───────────────────────────────────────────────────
+import { NotionPlugin } from './notion.js';
+import { XPlugin } from './x.js';
+import { SpotifyPlugin } from './spotify.js';
+import { HomeKitPlugin } from './homekit.js';
+import { SlackPlugin } from './slack.js';
+import { TodoistPlugin } from './todoist.js';
+
+// ── Project management ─────────────────────────────────────────────────────
+import { LinearPlugin } from './linear.js';
+import { JiraPlugin } from './jira.js';
+
+// ── Finance & commerce ─────────────────────────────────────────────────────
+import { StripePlugin } from './stripe.js';
+
+// ── Lumen — agentic AI coding assistant ───────────────────────────────────
+import { LumenPlugin } from './lumen.js';
+
+/** Returns all builtin plugins (not initialized — just constructed). */
+export function getAllBuiltinPlugins(): Plugin[] {
+  return [
+    // ── Utilities (zero config, always available) ──────────────────────────
+    new CryptoPlugin(),
+    new WeatherPlugin(),
+    new SystemInfoPlugin(),
+    new URLToolsPlugin(),
+    new FunPlugin(),
+    new HashPlugin(),
+    new TranslatePlugin(),
+    new CalculatorPlugin(),
+    new ColorPlugin(),
+    new NetworkPlugin(),
+    new TextToolsPlugin(),
+    new GitHubPlugin(),
+    new TimezonePlugin(),
+
+    // ── Memory & productivity (zero config) ────────────────────────────────
+    new MemoryPlugin(),
+    new NotesPlugin(),
+    new CronPlugin(),
+
+    // ── Infrastructure (zero config for shell, needs URLs for database) ────
+    new ShellPlugin(),
+    new DockerPlugin(),
+    new DatabasePlugin(),
+
+    // ── Google (require Google OAuth) ──────────────────────────────────────
+    new GmailPlugin(),
+    new GoogleCalendarPlugin(),
+    new GoogleDrivePlugin(),
+
+    // ── Developer (require API tokens) ────────────────────────────────────
+    new GitHubActionsPlugin(),
+    new VercelPlugin(),
+    new N8nPlugin(),
+
+    // ── Services (require API tokens) ─────────────────────────────────────
+    new NotionPlugin(),
+    new XPlugin(),
+    new SpotifyPlugin(),
+    new TodoistPlugin(),
+
+    // ── Smart home ────────────────────────────────────────────────────────
+    new HomeKitPlugin(),
+
+    // ── Messaging ─────────────────────────────────────────────────────────
+    new SlackPlugin(),
+
+    // ── Project management ─────────────────────────────────────────────────
+    new LinearPlugin(),
+    new JiraPlugin(),
+
+    // ── Finance & commerce ─────────────────────────────────────────────────
+    new StripePlugin(),
+
+    // ── Lumen — agentic AI coding assistant ───────────────────────────────
+    new LumenPlugin(),
+  ];
+}