@picahq/cli 0.1.0

package/src/commands/actions.ts

@@ -0,0 +1,385 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { getApiKey } from '../lib/config.js';
+import { PicaApi } from '../lib/api.js';
+import { extractPathVariables, resolveTemplateVariables } from '../lib/actions.js';
+import { printTable } from '../lib/table.js';
+import type { PlatformAction, ActionKnowledge } from '../lib/types.js';
+
+function getApi(): PicaApi {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    p.cancel('Not configured. Run `pica init` first.');
+    process.exit(1);
+  }
+  return new PicaApi(apiKey);
+}
+
+function colorMethod(method: string): string {
+  const m = method.toUpperCase();
+  switch (m) {
+    case 'GET': return pc.green(m);
+    case 'POST': return pc.yellow(m);
+    case 'PUT': return pc.blue(m);
+    case 'PATCH': return pc.cyan(m);
+    case 'DELETE': return pc.red(m);
+    default: return pc.dim(m);
+  }
+}
+
+function padMethod(method: string): string {
+  return method.toUpperCase().padEnd(7);
+}
+
+// --- Search ---
+
+export async function actionsSearchCommand(
+  platform: string,
+  query?: string,
+  options: { json?: boolean; limit?: string } = {}
+): Promise<void> {
+  const api = getApi();
+
+  if (!query) {
+    const input = await p.text({
+      message: `Search actions on ${pc.cyan(platform)}:`,
+      placeholder: 'send email, create contact, list orders...',
+    });
+    if (p.isCancel(input)) {
+      p.cancel('Cancelled.');
+      process.exit(0);
+    }
+    query = input;
+  }
+
+  const spinner = p.spinner();
+  spinner.start(`Searching ${platform} actions...`);
+
+  try {
+    const limit = options.limit ? parseInt(options.limit, 10) : 10;
+    const actions = await api.searchActions(platform, query, limit);
+    spinner.stop(`${actions.length} action${actions.length === 1 ? '' : 's'} found`);
+
+    if (options.json) {
+      console.log(JSON.stringify(actions, null, 2));
+      return;
+    }
+
+    if (actions.length === 0) {
+      p.note(`No actions found for "${query}" on ${platform}.`, 'No Results');
+      return;
+    }
+
+    console.log();
+
+    const rows = actions.map(action => ({
+      method: colorMethod(padMethod(action.method)),
+      path: action.path,
+      title: action.title,
+      id: action._id,
+    }));
+
+    printTable(
+      [
+        { key: 'method', label: 'Method' },
+        { key: 'title', label: 'Title' },
+        { key: 'path', label: 'Path', color: pc.dim },
+        { key: 'id', label: 'Action ID', color: pc.dim },
+      ],
+      rows
+    );
+
+    console.log();
+    p.note(
+      `Get docs:  ${pc.cyan('pica actions knowledge <actionId>')}\n` +
+      `Execute:   ${pc.cyan('pica actions execute <actionId>')}`,
+      'Next Steps'
+    );
+  } catch (error) {
+    spinner.stop('Search failed');
+    p.cancel(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    process.exit(1);
+  }
+}
+
+// --- Knowledge ---
+
+export async function actionsKnowledgeCommand(
+  actionId: string,
+  options: { json?: boolean; full?: boolean } = {}
+): Promise<void> {
+  const api = getApi();
+
+  const spinner = p.spinner();
+  spinner.start('Loading action knowledge...');
+
+  try {
+    const knowledge = await api.getActionKnowledge(actionId);
+    spinner.stop('Action knowledge loaded');
+
+    if (!knowledge) {
+      p.cancel(`No knowledge found for action: ${actionId}`);
+      process.exit(1);
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(knowledge, null, 2));
+      return;
+    }
+
+    printKnowledge(knowledge, options.full);
+  } catch (error) {
+    spinner.stop('Failed to load knowledge');
+    p.cancel(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    process.exit(1);
+  }
+}
+
+function printKnowledge(k: ActionKnowledge, full?: boolean): void {
+  console.log();
+  console.log(pc.bold(`  ${k.title}`));
+  console.log();
+  console.log(`  Platform:  ${pc.cyan(k.connectionPlatform)}`);
+  console.log(`  Method:    ${colorMethod(k.method)}`);
+  console.log(`  Path:      ${k.path}`);
+  console.log(`  Base URL:  ${pc.dim(k.baseUrl)}`);
+
+  if (k.tags?.length) {
+    console.log(`  Tags:      ${k.tags.map(t => pc.dim(t)).join(', ')}`);
+  }
+
+  const pathVars = extractPathVariables(k.path);
+  if (pathVars.length > 0) {
+    console.log(`  Path Vars: ${pathVars.map(v => pc.yellow(`{{${v}}}`)).join(', ')}`);
+  }
+
+  console.log(`  Active:    ${k.active ? pc.green('yes') : pc.red('no')}`);
+  console.log(`  ID:        ${pc.dim(k._id)}`);
+
+  if (k.knowledge) {
+    console.log();
+    console.log(pc.bold('  API Documentation'));
+    console.log(pc.dim('  ' + '─'.repeat(40)));
+    console.log();
+
+    const lines = k.knowledge.split('\n');
+    const displayLines = full ? lines : lines.slice(0, 50);
+
+    for (const line of displayLines) {
+      console.log(`  ${line}`);
+    }
+
+    if (!full && lines.length > 50) {
+      console.log();
+      console.log(pc.dim(`  ... ${lines.length - 50} more lines. Use --full to see all.`));
+    }
+  }
+
+  console.log();
+}
+
+// --- Execute ---
+
+export async function actionsExecuteCommand(
+  actionId: string,
+  options: {
+    json?: boolean;
+    connection?: string;
+    data?: string;
+    pathVar?: string[];
+    query?: string[];
+    formData?: boolean;
+    formUrlencoded?: boolean;
+  } = {}
+): Promise<void> {
+  const api = getApi();
+
+  // 1. Fetch action knowledge to get method + path
+  const spinner = p.spinner();
+  spinner.start('Loading action details...');
+
+  let knowledge: ActionKnowledge;
+  try {
+    const k = await api.getActionKnowledge(actionId);
+    if (!k) {
+      spinner.stop('Action not found');
+      p.cancel(`No action found for: ${actionId}`);
+      process.exit(1);
+    }
+    knowledge = k;
+    spinner.stop(`${colorMethod(knowledge.method)} ${knowledge.path}`);
+  } catch (error) {
+    spinner.stop('Failed to load action');
+    p.cancel(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    process.exit(1);
+  }
+
+  // 2. Resolve connection key
+  let connectionKey = options.connection;
+  if (!connectionKey) {
+    connectionKey = await resolveConnection(api, knowledge.connectionPlatform);
+  }
+
+  // 3. Resolve path variables
+  const pathVarMap = parseKeyValuePairs(options.pathVar || []);
+  const pathVars = extractPathVariables(knowledge.path);
+  for (const v of pathVars) {
+    if (!pathVarMap[v]) {
+      const input = await p.text({
+        message: `Value for path variable ${pc.yellow(`{{${v}}}`)}:`,
+        validate: (val) => val.trim() ? undefined : 'Value is required',
+      });
+      if (p.isCancel(input)) {
+        p.cancel('Cancelled.');
+        process.exit(0);
+      }
+      pathVarMap[v] = input;
+    }
+  }
+
+  // 4. Resolve body data
+  let bodyData: Record<string, unknown> = {};
+  if (options.data) {
+    try {
+      bodyData = JSON.parse(options.data);
+    } catch {
+      p.cancel('Invalid JSON in --data flag.');
+      process.exit(1);
+    }
+  } else if (!['GET', 'DELETE', 'HEAD'].includes(knowledge.method.toUpperCase())) {
+    const input = await p.text({
+      message: 'Request body (JSON):',
+      placeholder: '{"key": "value"} or leave empty',
+    });
+    if (p.isCancel(input)) {
+      p.cancel('Cancelled.');
+      process.exit(0);
+    }
+    if (input.trim()) {
+      try {
+        bodyData = JSON.parse(input);
+      } catch {
+        p.cancel('Invalid JSON.');
+        process.exit(1);
+      }
+    }
+  }
+
+  // 5. Resolve query params
+  const queryParams = parseKeyValuePairs(options.query || []);
+
+  // 6. Resolve template variables in path
+  const { resolvedPath, remainingData } = resolveTemplateVariables(
+    knowledge.path,
+    bodyData,
+    pathVarMap
+  );
+
+  // 7. Show summary
+  console.log();
+  console.log(pc.bold('  Request Summary'));
+  console.log(`  ${colorMethod(knowledge.method)} ${knowledge.baseUrl}${resolvedPath}`);
+  console.log(`  Connection: ${pc.dim(connectionKey)}`);
+  if (Object.keys(remainingData).length > 0) {
+    console.log(`  Body: ${pc.dim(JSON.stringify(remainingData))}`);
+  }
+  if (Object.keys(queryParams).length > 0) {
+    console.log(`  Query: ${pc.dim(JSON.stringify(queryParams))}`);
+  }
+  console.log();
+
+  // 8. Execute
+  const execSpinner = p.spinner();
+  execSpinner.start('Executing...');
+
+  try {
+    const result = await api.executeAction({
+      method: knowledge.method,
+      path: resolvedPath,
+      actionId,
+      connectionKey,
+      data: Object.keys(remainingData).length > 0 ? remainingData : undefined,
+      queryParams: Object.keys(queryParams).length > 0 ? queryParams : undefined,
+      isFormData: options.formData,
+      isFormUrlEncoded: options.formUrlencoded,
+    });
+
+    execSpinner.stop(pc.green('Success'));
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log();
+      console.log(pc.bold('  Response'));
+      console.log(pc.dim('  ' + '─'.repeat(40)));
+      console.log();
+      console.log(formatResponse(result));
+      console.log();
+    }
+  } catch (error) {
+    execSpinner.stop(pc.red('Failed'));
+    const msg = error instanceof Error ? error.message : 'Unknown error';
+    p.cancel(`Execution failed: ${msg}`);
+    process.exit(1);
+  }
+}
+
+// --- Helpers ---
+
+async function resolveConnection(api: PicaApi, platform: string): Promise<string> {
+  const spinner = p.spinner();
+  spinner.start('Loading connections...');
+
+  const connections = await api.listConnections();
+  const matching = connections.filter(
+    c => c.platform.toLowerCase() === platform.toLowerCase()
+  );
+  spinner.stop(`${matching.length} ${platform} connection${matching.length === 1 ? '' : 's'} found`);
+
+  if (matching.length === 0) {
+    p.cancel(
+      `No ${platform} connections found.\n\n` +
+      `Add one with: ${pc.cyan(`pica connection add ${platform}`)}`
+    );
+    process.exit(1);
+  }
+
+  if (matching.length === 1) {
+    p.log.info(`Using connection: ${pc.dim(matching[0].key)}`);
+    return matching[0].key;
+  }
+
+  const selected = await p.select({
+    message: `Multiple ${platform} connections found. Which one?`,
+    options: matching.map(c => ({
+      value: c.key,
+      label: `${c.key}`,
+      hint: c.state,
+    })),
+  });
+
+  if (p.isCancel(selected)) {
+    p.cancel('Cancelled.');
+    process.exit(0);
+  }
+
+  return selected as string;
+}
+
+function parseKeyValuePairs(pairs: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const pair of pairs) {
+    const eqIdx = pair.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = pair.slice(0, eqIdx);
+    const value = pair.slice(eqIdx + 1);
+    result[key] = value;
+  }
+  return result;
+}
+
+function formatResponse(data: unknown, indent = 2): string {
+  const prefix = ' '.repeat(indent);
+  const json = JSON.stringify(data, null, 2);
+  return json.split('\n').map(line => `${prefix}${line}`).join('\n');
+}

package/src/commands/connection.ts

@@ -0,0 +1,196 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { getApiKey } from '../lib/config.js';
+import { PicaApi, TimeoutError } from '../lib/api.js';
+import { openConnectionPage, getConnectionUrl } from '../lib/browser.js';
+import { findPlatform, findSimilarPlatforms } from '../lib/platforms.js';
+import { printTable } from '../lib/table.js';
+import type { Connection } from '../lib/types.js';
+
+export async function connectionAddCommand(platformArg?: string): Promise<void> {
+  p.intro(pc.bgCyan(pc.black(' Pica ')));
+
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    p.cancel('Not configured. Run `pica init` first.');
+    process.exit(1);
+  }
+
+  const api = new PicaApi(apiKey);
+
+  // Get platform list for validation
+  const spinner = p.spinner();
+  spinner.start('Loading platforms...');
+
+  let platforms;
+  try {
+    platforms = await api.listPlatforms();
+    spinner.stop(`${platforms.length} platforms available`);
+  } catch (error) {
+    spinner.stop('Failed to load platforms');
+    p.cancel(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    process.exit(1);
+  }
+
+  // Get or prompt for platform
+  let platform: string;
+
+  if (platformArg) {
+    const found = findPlatform(platforms, platformArg);
+    if (found) {
+      platform = found.platform;
+    } else {
+      const similar = findSimilarPlatforms(platforms, platformArg);
+      if (similar.length > 0) {
+        p.log.warn(`Unknown platform: ${platformArg}`);
+        const suggestion = await p.select({
+          message: 'Did you mean:',
+          options: [
+            ...similar.map(s => ({ value: s.platform, label: `${s.name} (${s.platform})` })),
+            { value: '__other__', label: 'None of these' },
+          ],
+        });
+
+        if (p.isCancel(suggestion) || suggestion === '__other__') {
+          p.note(`Run ${pc.cyan('pica platforms')} to see all available platforms.`);
+          p.cancel('Connection cancelled.');
+          process.exit(0);
+        }
+
+        platform = suggestion as string;
+      } else {
+        p.cancel(`Unknown platform: ${platformArg}\n\nRun ${pc.cyan('pica platforms')} to see available platforms.`);
+        process.exit(1);
+      }
+    }
+  } else {
+    const platformInput = await p.text({
+      message: 'Which platform do you want to connect?',
+      placeholder: 'gmail, slack, hubspot...',
+      validate: (value) => {
+        if (!value.trim()) return 'Platform name is required';
+        return undefined;
+      },
+    });
+
+    if (p.isCancel(platformInput)) {
+      p.cancel('Connection cancelled.');
+      process.exit(0);
+    }
+
+    const found = findPlatform(platforms, platformInput);
+    if (found) {
+      platform = found.platform;
+    } else {
+      p.cancel(`Unknown platform: ${platformInput}\n\nRun ${pc.cyan('pica platforms')} to see available platforms.`);
+      process.exit(1);
+    }
+  }
+
+  // Open browser
+  const url = getConnectionUrl(platform);
+  p.log.info(`Opening browser to connect ${pc.cyan(platform)}...`);
+  p.note(pc.dim(url), 'URL');
+
+  try {
+    await openConnectionPage(platform);
+  } catch {
+    p.log.warn('Could not open browser automatically.');
+    p.note(`Open this URL manually:\n${url}`);
+  }
+
+  // Poll for connection
+  const pollSpinner = p.spinner();
+  pollSpinner.start('Waiting for connection... (complete auth in browser)');
+
+  try {
+    const connection = await api.waitForConnection(platform, 5 * 60 * 1000, 5000);
+    pollSpinner.stop(`${platform} connected!`);
+
+    p.log.success(`${pc.green('✓')} ${connection.platform} is now available to your AI agents.`);
+    p.outro('Connection complete!');
+  } catch (error) {
+    pollSpinner.stop('Connection timed out');
+
+    if (error instanceof TimeoutError) {
+      p.note(
+        `Possible issues:\n` +
+        `  - OAuth flow was not completed in the browser\n` +
+        `  - Browser popup was blocked\n` +
+        `  - Wrong account selected\n\n` +
+        `Try again with: ${pc.cyan(`pica connection add ${platform}`)}`,
+        'Timed Out'
+      );
+    } else {
+      p.log.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+
+    process.exit(1);
+  }
+}
+
+export async function connectionListCommand(): Promise<void> {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    p.cancel('Not configured. Run `pica init` first.');
+    process.exit(1);
+  }
+
+  const api = new PicaApi(apiKey);
+
+  const spinner = p.spinner();
+  spinner.start('Loading connections...');
+
+  try {
+    const connections = await api.listConnections();
+    spinner.stop(`${connections.length} connection${connections.length === 1 ? '' : 's'} found`);
+
+    if (connections.length === 0) {
+      p.note(
+        `No connections yet.\n\n` +
+        `Add one with: ${pc.cyan('pica connection add gmail')}`,
+        'No Connections'
+      );
+      return;
+    }
+
+    console.log();
+
+    const rows = connections.map(conn => ({
+      status: getStatusIndicator(conn.state),
+      platform: conn.platform,
+      state: conn.state,
+      key: conn.key,
+    }));
+
+    printTable(
+      [
+        { key: 'status', label: '' },
+        { key: 'platform', label: 'Platform' },
+        { key: 'state', label: 'Status' },
+        { key: 'key', label: 'Connection Key', color: pc.dim },
+      ],
+      rows
+    );
+
+    console.log();
+    p.note(`Add more with: ${pc.cyan('pica connection add <platform>')}`, 'Tip');
+  } catch (error) {
+    spinner.stop('Failed to load connections');
+    p.cancel(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    process.exit(1);
+  }
+}
+
+function getStatusIndicator(state: Connection['state']): string {
+  switch (state) {
+    case 'operational':
+      return pc.green('●');
+    case 'degraded':
+      return pc.yellow('●');
+    case 'failed':
+      return pc.red('●');
+    default:
+      return pc.dim('○');
+  }
+}