@picahq/cli 0.1.0

package/src/index.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { initCommand } from './commands/init.js';
+import { connectionAddCommand, connectionListCommand } from './commands/connection.js';
+import { platformsCommand } from './commands/platforms.js';
+import { actionsSearchCommand, actionsKnowledgeCommand, actionsExecuteCommand } from './commands/actions.js';
+
+const program = new Command();
+
+program
+  .name('pica')
+  .description('CLI for managing Pica integrations')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Set up Pica and install MCP to your AI agents')
+  .option('-y, --yes', 'Skip confirmations')
+  .option('-g, --global', 'Install MCP globally (available in all projects)')
+  .option('-p, --project', 'Install MCP for this project only (creates .mcp.json)')
+  .action(async (options) => {
+    await initCommand(options);
+  });
+
+const connection = program
+  .command('connection')
+  .description('Manage connections');
+
+connection
+  .command('add [platform]')
+  .alias('a')
+  .description('Add a new connection')
+  .action(async (platform) => {
+    await connectionAddCommand(platform);
+  });
+
+connection
+  .command('list')
+  .alias('ls')
+  .description('List your connections')
+  .action(async () => {
+    await connectionListCommand();
+  });
+
+program
+  .command('platforms')
+  .alias('p')
+  .description('List available platforms')
+  .option('-c, --category <category>', 'Filter by category')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    await platformsCommand(options);
+  });
+
+// Shortcuts
+program
+  .command('add [platform]')
+  .description('Shortcut for: connection add')
+  .action(async (platform) => {
+    await connectionAddCommand(platform);
+  });
+
+program
+  .command('list')
+  .alias('ls')
+  .description('Shortcut for: connection list')
+  .action(async () => {
+    await connectionListCommand();
+  });
+
+// Actions command group
+const actions = program
+  .command('actions')
+  .alias('a')
+  .description('Discover and execute platform actions');
+
+actions
+  .command('search <platform> [query]')
+  .description('Search actions on a platform')
+  .option('--json', 'Output as JSON')
+  .option('-l, --limit <limit>', 'Max results', '10')
+  .action(async (platform: string, query: string | undefined, options: { json?: boolean; limit?: string }) => {
+    await actionsSearchCommand(platform, query, options);
+  });
+
+actions
+  .command('knowledge <actionId>')
+  .alias('k')
+  .description('Get API docs for an action')
+  .option('--json', 'Output as JSON')
+  .option('--full', 'Show full knowledge (no truncation)')
+  .action(async (actionId: string, options: { json?: boolean; full?: boolean }) => {
+    await actionsKnowledgeCommand(actionId, options);
+  });
+
+actions
+  .command('execute <actionId>')
+  .alias('x')
+  .description('Execute an action')
+  .option('-c, --connection <key>', 'Connection key to use')
+  .option('-d, --data <json>', 'Request body as JSON')
+  .option('-p, --path-var <key=value...>', 'Path variable', collectValues)
+  .option('-q, --query <key=value...>', 'Query parameter', collectValues)
+  .option('--form-data', 'Send as multipart/form-data')
+  .option('--form-urlencoded', 'Send as application/x-www-form-urlencoded')
+  .option('--json', 'Output as JSON')
+  .action(async (actionId: string, options) => {
+    await actionsExecuteCommand(actionId, options);
+  });
+
+// Top-level shortcuts
+program
+  .command('search <platform> [query]')
+  .description('Shortcut for: actions search')
+  .option('--json', 'Output as JSON')
+  .option('-l, --limit <limit>', 'Max results', '10')
+  .action(async (platform: string, query: string | undefined, options: { json?: boolean; limit?: string }) => {
+    await actionsSearchCommand(platform, query, options);
+  });
+
+program
+  .command('exec <actionId>')
+  .description('Shortcut for: actions execute')
+  .option('-c, --connection <key>', 'Connection key to use')
+  .option('-d, --data <json>', 'Request body as JSON')
+  .option('-p, --path-var <key=value...>', 'Path variable', collectValues)
+  .option('-q, --query <key=value...>', 'Query parameter', collectValues)
+  .option('--form-data', 'Send as multipart/form-data')
+  .option('--form-urlencoded', 'Send as application/x-www-form-urlencoded')
+  .option('--json', 'Output as JSON')
+  .action(async (actionId: string, options) => {
+    await actionsExecuteCommand(actionId, options);
+  });
+
+function collectValues(value: string, previous: string[]): string[] {
+  return (previous || []).concat([value]);
+}
+
+program.parse();

package/src/lib/actions.ts

@@ -0,0 +1,59 @@
+const ACTION_ID_PREFIX = 'conn_mod_def::';
+
+/**
+ * Ensure action ID has the required prefix.
+ */
+export function normalizeActionId(id: string): string {
+  if (id.startsWith(ACTION_ID_PREFIX)) return id;
+  return `${ACTION_ID_PREFIX}${id}`;
+}
+
+/**
+ * Extract {{variable}} names from a path string.
+ */
+export function extractPathVariables(path: string): string[] {
+  const matches = path.match(/\{\{(\w+)\}\}/g);
+  if (!matches) return [];
+  return matches.map(m => m.replace(/\{\{|\}\}/g, ''));
+}
+
+/**
+ * Replace {{variable}} placeholders in a path with provided values.
+ */
+export function replacePathVariables(
+  path: string,
+  vars: Record<string, string>
+): string {
+  let result = path;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replace(`{{${key}}}`, encodeURIComponent(value));
+  }
+  return result;
+}
+
+/**
+ * Resolve path variables from data object and pathVars overrides.
+ * Returns the resolved path and the remaining data (with used keys removed).
+ */
+export function resolveTemplateVariables(
+  path: string,
+  data: Record<string, unknown>,
+  pathVars: Record<string, string>
+): { resolvedPath: string; remainingData: Record<string, unknown> } {
+  const variables = extractPathVariables(path);
+  const merged: Record<string, string> = { ...pathVars };
+  const remaining = { ...data };
+
+  // Fill from data if not already provided in pathVars
+  for (const v of variables) {
+    if (!merged[v] && data[v] != null) {
+      merged[v] = String(data[v]);
+      delete remaining[v];
+    }
+  }
+
+  return {
+    resolvedPath: replacePathVariables(path, merged),
+    remainingData: remaining,
+  };
+}

package/src/lib/agents.ts

@@ -0,0 +1,191 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import type { Agent } from './types.js';
+
+export type InstallScope = 'global' | 'project';
+
+function expandPath(p: string): string {
+  if (p.startsWith('~/')) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+function getClaudeDesktopConfigPath(): string {
+  switch (process.platform) {
+    case 'darwin':
+      return '~/Library/Application Support/Claude/claude_desktop_config.json';
+    case 'win32':
+      return path.join(process.env.APPDATA || '', 'Claude', 'claude_desktop_config.json');
+    default:
+      return '~/.config/Claude/claude_desktop_config.json';
+  }
+}
+
+function getClaudeDesktopDetectDir(): string {
+  switch (process.platform) {
+    case 'darwin':
+      return '~/Library/Application Support/Claude';
+    case 'win32':
+      return path.join(process.env.APPDATA || '', 'Claude');
+    default:
+      return '~/.config/Claude';
+  }
+}
+
+function getWindsurfConfigPath(): string {
+  if (process.platform === 'win32') {
+    return path.join(process.env.USERPROFILE || os.homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+  }
+  return '~/.codeium/windsurf/mcp_config.json';
+}
+
+function getWindsurfDetectDir(): string {
+  if (process.platform === 'win32') {
+    return path.join(process.env.USERPROFILE || os.homedir(), '.codeium', 'windsurf');
+  }
+  return '~/.codeium/windsurf';
+}
+
+function getCursorConfigPath(): string {
+  if (process.platform === 'win32') {
+    return path.join(process.env.USERPROFILE || os.homedir(), '.cursor', 'mcp.json');
+  }
+  return '~/.cursor/mcp.json';
+}
+
+const AGENTS: Agent[] = [
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    configPath: '~/.claude.json',
+    configKey: 'mcpServers',
+    detectDir: '~/.claude',
+    projectConfigPath: '.mcp.json',
+  },
+  {
+    id: 'claude-desktop',
+    name: 'Claude Desktop',
+    configPath: getClaudeDesktopConfigPath(),
+    configKey: 'mcpServers',
+    detectDir: getClaudeDesktopDetectDir(),
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    configPath: getCursorConfigPath(),
+    configKey: 'mcpServers',
+    detectDir: '~/.cursor',
+    projectConfigPath: '.cursor/mcp.json',
+  },
+  {
+    id: 'windsurf',
+    name: 'Windsurf',
+    configPath: getWindsurfConfigPath(),
+    configKey: 'mcpServers',
+    detectDir: getWindsurfDetectDir(),
+  },
+];
+
+export function getAllAgents(): Agent[] {
+  return AGENTS;
+}
+
+export function detectInstalledAgents(): Agent[] {
+  return AGENTS.filter(agent => {
+    const detectDir = expandPath(agent.detectDir);
+    return fs.existsSync(detectDir);
+  });
+}
+
+export function supportsProjectScope(agent: Agent): boolean {
+  return agent.projectConfigPath !== undefined;
+}
+
+export function getAgentConfigPath(agent: Agent, scope: InstallScope = 'global'): string {
+  if (scope === 'project' && agent.projectConfigPath) {
+    return path.join(process.cwd(), agent.projectConfigPath);
+  }
+  return expandPath(agent.configPath);
+}
+
+export function readAgentConfig(agent: Agent, scope: InstallScope = 'global'): Record<string, unknown> {
+  const configPath = getAgentConfigPath(agent, scope);
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+  try {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+
+export function writeAgentConfig(agent: Agent, config: Record<string, unknown>, scope: InstallScope = 'global'): void {
+  const configPath = getAgentConfigPath(agent, scope);
+  const configDir = path.dirname(configPath);
+
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+}
+
+export function getMcpServerConfig(apiKey: string): Record<string, unknown> {
+  return {
+    command: 'npx',
+    args: ['-y', '@picahq/mcp'],
+    env: {
+      PICA_SECRET: apiKey,
+    },
+  };
+}
+
+export function installMcpConfig(agent: Agent, apiKey: string, scope: InstallScope = 'global'): void {
+  const config = readAgentConfig(agent, scope);
+  const configKey = agent.configKey;
+
+  const mcpServers = (config[configKey] as Record<string, unknown>) || {};
+  mcpServers['pica'] = getMcpServerConfig(apiKey);
+
+  config[configKey] = mcpServers;
+  writeAgentConfig(agent, config, scope);
+}
+
+export function isMcpInstalled(agent: Agent, scope: InstallScope = 'global'): boolean {
+  const config = readAgentConfig(agent, scope);
+  const configKey = agent.configKey;
+  const mcpServers = config[configKey] as Record<string, unknown> | undefined;
+  return mcpServers?.['pica'] !== undefined;
+}
+
+export function getProjectConfigPaths(agents: Agent[]): string[] {
+  const paths: string[] = [];
+  for (const agent of agents) {
+    if (agent.projectConfigPath) {
+      paths.push(path.join(process.cwd(), agent.projectConfigPath));
+    }
+  }
+  return paths;
+}
+
+export interface AgentStatus {
+  agent: Agent;
+  detected: boolean;
+  globalMcp: boolean;
+  projectMcp: boolean | null; // null = agent doesn't support project scope
+}
+
+export function getAgentStatuses(): AgentStatus[] {
+  return AGENTS.map(agent => {
+    const detected = fs.existsSync(expandPath(agent.detectDir));
+    const globalMcp = detected && isMcpInstalled(agent, 'global');
+    const projectMcp = agent.projectConfigPath
+      ? isMcpInstalled(agent, 'project')
+      : null;
+    return { agent, detected, globalMcp, projectMcp };
+  });
+}

package/src/lib/api.ts

@@ -0,0 +1,191 @@
+import type {
+  Connection,
+  ConnectionsResponse,
+  Platform,
+  PlatformsResponse,
+  PlatformAction,
+  ActionsSearchResponse,
+  ActionKnowledge,
+  KnowledgeResponse,
+} from './types.js';
+import { normalizeActionId } from './actions.js';
+
+const API_BASE = 'https://api.picaos.com/v1';
+
+export class ApiError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+export class PicaApi {
+  constructor(private apiKey: string) {}
+
+  private async request<T>(path: string): Promise<T> {
+    return this.requestFull<T>({ path });
+  }
+
+  private async requestFull<T>(opts: {
+    path: string;
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    queryParams?: Record<string, string>;
+  }): Promise<T> {
+    let url = `${API_BASE}${opts.path}`;
+    if (opts.queryParams && Object.keys(opts.queryParams).length > 0) {
+      const params = new URLSearchParams(opts.queryParams);
+      url += `?${params.toString()}`;
+    }
+
+    const headers: Record<string, string> = {
+      'x-pica-secret': this.apiKey,
+      'Content-Type': 'application/json',
+      ...opts.headers,
+    };
+
+    const fetchOpts: RequestInit = {
+      method: opts.method || 'GET',
+      headers,
+    };
+
+    if (opts.body !== undefined) {
+      fetchOpts.body = JSON.stringify(opts.body);
+    }
+
+    const response = await fetch(url, fetchOpts);
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new ApiError(response.status, text || `HTTP ${response.status}`);
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  async validateApiKey(): Promise<boolean> {
+    try {
+      await this.listConnections();
+      return true;
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 401) {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  async listConnections(): Promise<Connection[]> {
+    const response = await this.request<ConnectionsResponse>('/vault/connections');
+    return response.rows || [];
+  }
+
+  async listPlatforms(): Promise<Platform[]> {
+    const allPlatforms: Platform[] = [];
+    let page = 1;
+    let totalPages = 1;
+
+    do {
+      const response = await this.request<PlatformsResponse>(`/available-connectors?page=${page}&limit=100`);
+      allPlatforms.push(...(response.rows || []));
+      totalPages = response.pages || 1;
+      page++;
+    } while (page <= totalPages);
+
+    return allPlatforms;
+  }
+
+  async searchActions(platform: string, query?: string, limit = 10): Promise<PlatformAction[]> {
+    const queryParams: Record<string, string> = {
+      limit: String(limit),
+      executeAgent: 'true',
+    };
+    if (query) queryParams.query = query;
+
+    const response = await this.requestFull<ActionsSearchResponse>({
+      path: `/available-actions/search/${encodeURIComponent(platform)}`,
+      queryParams,
+    });
+    return response.rows || [];
+  }
+
+  async getActionKnowledge(actionId: string): Promise<ActionKnowledge | null> {
+    const normalized = normalizeActionId(actionId);
+    const response = await this.requestFull<KnowledgeResponse>({
+      path: '/knowledge',
+      queryParams: { _id: normalized },
+    });
+    return response.rows?.[0] ?? null;
+  }
+
+  async executeAction(opts: {
+    method: string;
+    path: string;
+    actionId: string;
+    connectionKey: string;
+    data?: unknown;
+    queryParams?: Record<string, string>;
+    headers?: Record<string, string>;
+    isFormData?: boolean;
+    isFormUrlEncoded?: boolean;
+  }): Promise<unknown> {
+    const headers: Record<string, string> = {
+      'x-pica-connection-key': opts.connectionKey,
+      'x-pica-action-id': normalizeActionId(opts.actionId),
+      ...opts.headers,
+    };
+
+    if (opts.isFormData) {
+      headers['Content-Type'] = 'multipart/form-data';
+    } else if (opts.isFormUrlEncoded) {
+      headers['Content-Type'] = 'application/x-www-form-urlencoded';
+    }
+
+    return this.requestFull<unknown>({
+      path: `/passthrough${opts.path}`,
+      method: opts.method.toUpperCase(),
+      body: opts.data,
+      headers,
+      queryParams: opts.queryParams,
+    });
+  }
+
+  async waitForConnection(
+    platform: string,
+    timeoutMs = 5 * 60 * 1000,
+    pollIntervalMs = 5000,
+    onPoll?: () => void
+  ): Promise<Connection> {
+    const startTime = Date.now();
+    const existingConnections = await this.listConnections();
+    const existingIds = new Set(existingConnections.map(c => c.id));
+
+    while (Date.now() - startTime < timeoutMs) {
+      await sleep(pollIntervalMs);
+      onPoll?.();
+
+      const currentConnections = await this.listConnections();
+      const newConnection = currentConnections.find(
+        c => c.platform.toLowerCase() === platform.toLowerCase() && !existingIds.has(c.id)
+      );
+
+      if (newConnection) {
+        return newConnection;
+      }
+    }
+
+    throw new TimeoutError(`Timed out waiting for ${platform} connection`);
+  }
+}
+
+export class TimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TimeoutError';
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/lib/browser.ts

@@ -0,0 +1,20 @@
+import open from 'open';
+
+const PICA_APP_URL = 'https://app.picaos.com';
+
+export function getConnectionUrl(platform: string): string {
+  return `${PICA_APP_URL}/connections?#open=${platform}`;
+}
+
+export function getApiKeyUrl(): string {
+  return `${PICA_APP_URL}/settings/api-keys`;
+}
+
+export async function openConnectionPage(platform: string): Promise<void> {
+  const url = getConnectionUrl(platform);
+  await open(url);
+}
+
+export async function openApiKeyPage(): Promise<void> {
+  await open(getApiKeyUrl());
+}

package/src/lib/config.ts

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import type { Config } from './types.js';
+
+const CONFIG_DIR = path.join(os.homedir(), '.pica');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+export function getConfigPath(): string {
+  return CONFIG_FILE;
+}
+
+export function configExists(): boolean {
+  return fs.existsSync(CONFIG_FILE);
+}
+
+export function readConfig(): Config | null {
+  if (!configExists()) {
+    return null;
+  }
+  try {
+    const content = fs.readFileSync(CONFIG_FILE, 'utf-8');
+    return JSON.parse(content) as Config;
+  } catch {
+    return null;
+  }
+}
+
+export function writeConfig(config: Config): void {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { mode: 0o700 });
+  }
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+export function getApiKey(): string | null {
+  const config = readConfig();
+  return config?.apiKey ?? null;
+}
+
+export function updateInstalledAgents(agentIds: string[]): void {
+  const config = readConfig();
+  if (config) {
+    config.installedAgents = agentIds;
+    writeConfig(config);
+  }
+}