archer-wizard 0.1.0

package/src/lib/webhook.ts

@@ -0,0 +1,69 @@
+import { stderrAction, stderrSuccess, stderrError } from './ascii.js';
+import type { WebhookOptions, WebhookPayload } from '../types/index.js';
+
+// ─── Retry Config ───────────────────────────────────────────
+
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 2000;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── Fire Webhook ───────────────────────────────────────────
+
+export async function fireWebhook(options: WebhookOptions): Promise<boolean> {
+  const { url, payload, event } = options;
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      stderrAction(`webhook → ${url} (attempt ${attempt}/${MAX_RETRIES})`);
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'User-Agent': 'Archer/0.1.0',
+          'X-Archer-Event': event,
+        },
+        body: JSON.stringify(payload),
+      });
+
+      if (response.ok) {
+        stderrSuccess(`webhook delivered → ${response.status}`);
+        return true;
+      }
+
+      stderrError(`webhook failed → ${response.status} ${response.statusText}`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      stderrError(`webhook error → ${message}`);
+    }
+
+    if (attempt < MAX_RETRIES) {
+      stderrAction(`retrying in ${RETRY_DELAY_MS / 1000}s...`);
+      await sleep(RETRY_DELAY_MS);
+    }
+  }
+
+  stderrError(`webhook exhausted all ${MAX_RETRIES} retries`);
+  return false;
+}
+
+// ─── Build Payload ──────────────────────────────────────────
+
+export function buildWebhookPayload(
+  watchId: string,
+  event: string,
+  data: Record<string, unknown>,
+): WebhookPayload {
+  return {
+    archer: {
+      watchId,
+      event,
+      source: 'supabase',
+      firedAt: new Date().toISOString(),
+    },
+    data,
+  };
+}

package/src/tools/watch.ts

@@ -0,0 +1,223 @@
+import crypto from 'node:crypto';
+import type { RealtimeChannel } from '@supabase/supabase-js';
+import { WatchInputSchema, type WatchInput, type WatchResult, type PostgresEvent } from '../types/index.js';
+import { createAuthChannel, createTableChannel } from '../lib/supabase.js';
+import { fireWebhook, buildWebhookPayload } from '../lib/webhook.js';
+import { stderrAction, stderrSuccess, stderrError } from '../lib/ascii.js';
+
+// ─── Active Subscriptions ───────────────────────────────────
+
+interface ActiveWatch {
+  watchId: string;
+  channel: RealtimeChannel;
+  event: string;
+  table?: string;
+  condition?: string;
+  webhookUrl: string;
+}
+
+const activeWatches = new Map<string, ActiveWatch>();
+
+// ─── Condition Evaluator ────────────────────────────────────
+
+function evaluateCondition(
+  data: Record<string, unknown>,
+  condition: string,
+): boolean {
+  // Parse: "field operator value"
+  // Supported: "ends with", "starts with", "contains", "equals"
+  const operators = ['ends with', 'starts with', 'contains', 'equals'] as const;
+
+  const conditionLower = condition.toLowerCase();
+  let matchedOperator: (typeof operators)[number] | null = null;
+  let splitIndex = -1;
+
+  for (const op of operators) {
+    const idx = conditionLower.indexOf(op);
+    if (idx !== -1) {
+      matchedOperator = op;
+      splitIndex = idx;
+      break;
+    }
+  }
+
+  if (!matchedOperator || splitIndex === -1) {
+    stderrError(`unknown condition format: "${condition}"`);
+    return true; // Pass through if condition can't be parsed
+  }
+
+  const field = condition.slice(0, splitIndex).trim();
+  const value = condition.slice(splitIndex + matchedOperator.length).trim();
+  const fieldValue = String(data[field] ?? '');
+
+  switch (matchedOperator) {
+    case 'ends with':
+      return fieldValue.endsWith(value);
+    case 'starts with':
+      return fieldValue.startsWith(value);
+    case 'contains':
+      return fieldValue.includes(value);
+    case 'equals':
+      return fieldValue === value;
+    default:
+      return true;
+  }
+}
+
+// ─── Map Event To Postgres Event ────────────────────────────
+
+function toPostgresEvent(event: string): PostgresEvent {
+  switch (event) {
+    case 'table.insert': return 'INSERT';
+    case 'table.update': return 'UPDATE';
+    case 'table.delete': return 'DELETE';
+    default: return 'INSERT';
+  }
+}
+
+// ─── Event Handler ──────────────────────────────────────────
+
+function createEventHandler(watch: ActiveWatch) {
+  return async (data: Record<string, unknown>) => {
+    stderrAction(`event received → ${watch.event}${watch.table ? ` on ${watch.table}` : ''}`);
+
+    // Apply condition filter
+    if (watch.condition && !evaluateCondition(data, watch.condition)) {
+      stderrAction(`condition not met → "${watch.condition}", skipping`);
+      return;
+    }
+
+    // Build and fire webhook
+    const payload = buildWebhookPayload(watch.watchId, watch.event, data);
+    await fireWebhook({
+      url: watch.webhookUrl,
+      payload,
+      event: watch.event,
+    });
+  };
+}
+
+// ─── Main Watch Implementation ──────────────────────────────
+
+export function executeWatch(rawInput: unknown): WatchResult {
+  // Validate input
+  const parseResult = WatchInputSchema.safeParse(rawInput);
+  if (!parseResult.success) {
+    const errors = parseResult.error.issues.map((e) => e.message).join(', ');
+    return {
+      success: false,
+      watchId: '',
+      message: `validation failed: ${errors}`,
+      condition: null,
+    };
+  }
+
+  const input: WatchInput = parseResult.data;
+  const watchId = `watch_${crypto.randomUUID().slice(0, 8)}`;
+
+  stderrAction(`creating watch ${watchId} for ${input.event}`);
+
+  try {
+    let channel: RealtimeChannel;
+
+    if (input.event === 'auth.signup') {
+      // Auth signup → watch auth.users table
+      const handler = createEventHandler({
+        watchId,
+        channel: null as unknown as RealtimeChannel,
+        event: input.event,
+        condition: input.condition,
+        webhookUrl: input.webhookUrl,
+      });
+
+      channel = createAuthChannel(watchId, handler);
+    } else {
+      // Table events → watch specific table
+      const table = input.table!;
+      const pgEvent = toPostgresEvent(input.event);
+
+      const handler = createEventHandler({
+        watchId,
+        channel: null as unknown as RealtimeChannel,
+        event: input.event,
+        table,
+        condition: input.condition,
+        webhookUrl: input.webhookUrl,
+      });
+
+      channel = createTableChannel(watchId, table, pgEvent, handler);
+    }
+
+    // Store active watch
+    const watch: ActiveWatch = {
+      watchId,
+      channel,
+      event: input.event,
+      table: input.table,
+      condition: input.condition,
+      webhookUrl: input.webhookUrl,
+    };
+
+    activeWatches.set(watchId, watch);
+
+    const tableInfo = input.table ? ` on table "${input.table}"` : '';
+    const conditionInfo = input.condition ? ` where ${input.condition}` : '';
+    const message = `watching ${input.event}${tableInfo}${conditionInfo} → ${input.webhookUrl}`;
+
+    stderrSuccess(message);
+
+    return {
+      success: true,
+      watchId,
+      message,
+      condition: input.condition ?? null,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    stderrError(`watch failed: ${message}`);
+
+    return {
+      success: false,
+      watchId,
+      message: `watch failed: ${message}`,
+      condition: input.condition ?? null,
+    };
+  }
+}
+
+// ─── Tool Schema (for MCP registration) ─────────────────────
+
+export const WATCH_TOOL_SCHEMA = {
+  name: 'archer_watch',
+  description:
+    'Watch real-time events from Supabase. Monitors auth signups, table inserts, updates, and deletes. Fires a webhook when conditions are met.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      source: {
+        type: 'string' as const,
+        enum: ['supabase'],
+        description: 'Event source (currently only "supabase")',
+      },
+      event: {
+        type: 'string' as const,
+        enum: ['auth.signup', 'table.insert', 'table.update', 'table.delete'],
+        description: 'Event type to watch for',
+      },
+      table: {
+        type: 'string' as const,
+        description: 'Table name (required for table.* events)',
+      },
+      condition: {
+        type: 'string' as const,
+        description:
+          'Optional filter like "email ends with @gmail.com". Supports: ends with, starts with, contains, equals',
+      },
+      webhookUrl: {
+        type: 'string' as const,
+        description: 'URL to receive POST notifications when events match',
+      },
+    },
+    required: ['source', 'event', 'webhookUrl'],
+  },
+};

package/src/types/index.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+
+// ─── Framework Detection ────────────────────────────────────
+
+export type Framework = 'nextjs' | 'vite' | 'unknown';
+
+// ─── Scanner Types ──────────────────────────────────────────
+
+export interface ScanResult {
+  supabaseUrl: string | null;
+  serviceRoleKey: string | null;
+  anonKey: string | null;
+  framework: Framework;
+  hasSupabaseInstalled: boolean;
+  foundInFile: string | null;
+}
+
+export interface ValidatedCredentials {
+  supabaseUrl: string;
+  serviceRoleKey: string;
+  anonKey: string | null;
+}
+
+// ─── Agent Detection ────────────────────────────────────────
+
+export interface AgentInfo {
+  name: string;
+  installed: boolean;
+  configPath: string;
+  configExists: boolean;
+}
+
+export type AgentName = 'cursor' | 'claude-code' | 'opencode' | 'antigravity' | 'windsurf';
+
+export interface AgentConfigFormat {
+  name: AgentName;
+  displayName: string;
+  configKey: 'mcpServers' | 'mcp';
+  rulesPath: (cwd: string) => string;
+}
+
+// ─── Watch Tool Types ───────────────────────────────────────
+
+export const WatchEventSchema = z.enum([
+  'auth.signup',
+  'table.insert',
+  'table.update',
+  'table.delete',
+]);
+
+export type WatchEvent = z.infer<typeof WatchEventSchema>;
+
+export const WatchInputSchema = z.object({
+  source: z.literal('supabase'),
+  event: WatchEventSchema,
+  table: z.string().optional(),
+  condition: z.string().optional(),
+  webhookUrl: z.string().url('webhookUrl must be a valid URL'),
+}).refine(
+  (data) => {
+    if (data.event !== 'auth.signup' && !data.table) {
+      return false;
+    }
+    return true;
+  },
+  {
+    message: 'table is required when event is not auth.signup',
+    path: ['table'],
+  }
+);
+
+export type WatchInput = z.infer<typeof WatchInputSchema>;
+
+export interface WatchResult {
+  success: boolean;
+  watchId: string;
+  message: string;
+  condition: string | null;
+}
+
+// ─── Webhook Types ──────────────────────────────────────────
+
+export interface WebhookPayload {
+  archer: {
+    watchId: string;
+    event: string;
+    source: 'supabase';
+    firedAt: string;
+  };
+  data: Record<string, unknown>;
+}
+
+export interface WebhookOptions {
+  url: string;
+  payload: WebhookPayload;
+  event: string;
+}
+
+// ─── Supabase Realtime Types ────────────────────────────────
+
+export type PostgresEvent = 'INSERT' | 'UPDATE' | 'DELETE';
+
+export interface RealtimeChannelConfig {
+  table: string;
+  event: PostgresEvent;
+}
+
+// ─── Injection Types ────────────────────────────────────────
+
+export interface InjectionResult {
+  agent: string;
+  success: boolean;
+  error?: string;
+}
+
+export interface McpServerEntry {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+}

package/src/wizard/detector.ts

@@ -0,0 +1,151 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import type { AgentInfo } from '../types/index.js';
+
+// ─── Agent Config Paths ─────────────────────────────────────
+
+interface AgentPathConfig {
+  name: string;
+  paths: {
+    darwin: string;
+    linux: string;
+    win32: string;
+  };
+}
+
+const AGENTS: AgentPathConfig[] = [
+  {
+    name: 'cursor',
+    paths: {
+      darwin: path.join(os.homedir(), '.cursor', 'mcp.json'),
+      linux: path.join(os.homedir(), '.cursor', 'mcp.json'),
+      win32: path.join(process.env['APPDATA'] ?? os.homedir(), 'Cursor', 'mcp.json'),
+    },
+  },
+  {
+    name: 'claude-code',
+    paths: {
+      darwin: path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+      linux: path.join(os.homedir(), '.config', 'claude', 'claude_desktop_config.json'),
+      win32: path.join(process.env['APPDATA'] ?? os.homedir(), 'Claude', 'claude_desktop_config.json'),
+    },
+  },
+  {
+    name: 'opencode',
+    paths: {
+      darwin: path.join(os.homedir(), '.config', 'opencode', 'config.json'),
+      linux: path.join(os.homedir(), '.config', 'opencode', 'config.json'),
+      win32: path.join(process.env['APPDATA'] ?? os.homedir(), 'opencode', 'config.json'),
+    },
+  },
+  {
+    name: 'antigravity',
+    paths: {
+      darwin: path.join(os.homedir(), '.config', 'antigravity', 'config.json'),
+      linux: path.join(os.homedir(), '.config', 'antigravity', 'config.json'),
+      win32: path.join(process.env['APPDATA'] ?? os.homedir(), 'Antigravity', 'config.json'),
+    },
+  },
+  {
+    name: 'windsurf',
+    paths: {
+      darwin: path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json'),
+      linux: path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json'),
+      win32: path.join(process.env['APPDATA'] ?? os.homedir(), 'Windsurf', 'mcp_config.json'),
+    },
+  },
+];
+
+// ─── Platform Detection ─────────────────────────────────────
+
+function getPlatform(): 'darwin' | 'linux' | 'win32' {
+  const platform = os.platform();
+  if (platform === 'darwin' || platform === 'linux' || platform === 'win32') {
+    return platform;
+  }
+  // Default to linux for other Unix-like systems
+  return 'linux';
+}
+
+// ─── Get Config Path For Agent ──────────────────────────────
+
+function getConfigPath(agent: AgentPathConfig): string {
+  const platform = getPlatform();
+  return agent.paths[platform];
+}
+
+// ─── Check If Path Exists ───────────────────────────────────
+
+function fileExists(filePath: string): boolean {
+  try {
+    // Check if the file itself OR its parent directory exists
+    // The config file might not exist yet, but the parent app directory should
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+function parentDirExists(filePath: string): boolean {
+  try {
+    const dir = path.dirname(filePath);
+    return fs.existsSync(dir);
+  } catch {
+    return false;
+  }
+}
+
+// ─── Detect Installed Agents ────────────────────────────────
+
+export function detectAgents(): AgentInfo[] {
+  const detected: AgentInfo[] = [];
+
+  for (const agent of AGENTS) {
+    const configPath = getConfigPath(agent);
+    const configExists = fileExists(configPath);
+    const dirExists = parentDirExists(configPath);
+
+    // Agent is "installed" if its parent directory exists
+    // (the config file might not exist yet)
+    if (dirExists) {
+      detected.push({
+        name: agent.name,
+        installed: true,
+        configPath,
+        configExists,
+      });
+    }
+  }
+
+  return detected;
+}
+
+// ─── Get Config Key For Agent ───────────────────────────────
+
+export function getConfigKey(agentName: string): 'mcpServers' | 'mcp' {
+  if (agentName === 'opencode') {
+    return 'mcp';
+  }
+  // cursor, claude-code, antigravity, windsurf all use mcpServers
+  return 'mcpServers';
+}
+
+// ─── Get Rules Path For Agent ───────────────────────────────
+
+export function getRulesPath(agentName: string, cwd: string): string {
+  switch (agentName) {
+    case 'cursor':
+      return path.join(cwd, '.cursor', 'rules', 'archer.mdc');
+    case 'claude-code':
+      return path.join(cwd, 'CLAUDE.md');
+    case 'opencode':
+      return path.join(cwd, '.opencode', 'rules.md');
+    case 'antigravity':
+      return path.join(cwd, '.antigravity', 'rules.md');
+    case 'windsurf':
+      return path.join(cwd, '.windsurf', 'rules.md');
+    default:
+      return path.join(cwd, '.archer', 'rules.md');
+  }
+}

package/src/wizard/index.ts

@@ -0,0 +1,69 @@
+import * as clack from '@clack/prompts';
+import pc from 'picocolors';
+import { showAsciiArt, logAction, logSuccess, showSuccessBox } from '../lib/ascii.js';
+import { scanProject, promptForMissing } from './scanner.js';
+import { detectAgents } from './detector.js';
+import { injectIntoAgents } from './injector.js';
+import { injectRules } from './rules.js';
+
+// ─── Wizard Sequence ────────────────────────────────────────
+
+export async function runWizard(): Promise<void> {
+  const cwd = process.cwd();
+
+  // ─ Step 1: ASCII Art ─
+  showAsciiArt();
+
+  // ─ Step 2: Start clack ─
+  clack.intro(pc.bgGreen(pc.black(' archer setup ')));
+
+  // ─ Step 3: Scanning ─
+  logAction('scanning project for Supabase credentials...');
+  console.log();
+
+  // ─ Step 4-6: Scan env files ─
+  const scan = await scanProject(cwd);
+  console.log();
+
+  // ─ Step 7: Framework detection ─
+  if (scan.framework !== 'unknown') {
+    logSuccess(`detected ${pc.bold(scan.framework)} project`);
+  }
+  if (scan.hasSupabaseInstalled) {
+    logSuccess('found @supabase/supabase-js');
+  }
+
+  // ─ Step 8: Prompt for missing credentials ─
+  const credentials = await promptForMissing(scan);
+  console.log();
+
+  // ─ Step 9: Detect agents ─
+  logAction('detecting AI agents...');
+  const agents = detectAgents();
+  console.log();
+
+  // ─ Step 10-11: Inject into agents ─
+  const injectionResults = await injectIntoAgents(
+    agents,
+    credentials.supabaseUrl,
+    credentials.serviceRoleKey,
+  );
+  console.log();
+
+  // ─ Step 12: Filter successful injections ─
+  const successfulAgents = agents.filter((a) =>
+    injectionResults.some((r) => r.agent === a.name && r.success),
+  );
+
+  // ─ Step 13: Inject rules ─
+  if (successfulAgents.length > 0) {
+    logAction('writing agent rules...');
+    injectRules(successfulAgents, cwd);
+    console.log();
+  }
+
+  // ─ Step 14: Success ─
+  showSuccessBox(successfulAgents.length);
+
+  clack.outro(pc.dim('docs → github.com/archer-mcp'));
+}