@picahq/cli 0.2.0 → 0.3.0

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@picahq/cli",
-  "version": "0.2.0",
-  "description": "CLI for managing Pica integrations",
+  "version": "0.3.0",
+  "description": "CLI for managing Pica",
   "type": "module",
+  "files": [
+    "bin",
+    "dist"
+  ],
   "bin": {
     "pica": "./bin/cli.js"
   },

package/.claude/settings.local.json

@@ -1,11 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm run build:*)",
-      "Bash(npm link)",
-      "Bash(pica:*)",
-      "Bash(npm install:*)",
-      "Bash(npm unlink:*)"
-    ]
-  }
-}

package/.github/workflows/publish.yml

@@ -1,29 +0,0 @@
-name: Publish Package to NPM
-on:
-  release:
-    types: [created]
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-          registry-url: 'https://registry.npmjs.org/'
-      - name: Install latest npm
-        run: npm install -g npm@latest
-      - name: Install dependencies
-        run: |
-          if [ -f package-lock.json ]; then
-            npm ci
-          else
-            npm install
-          fi
-      - name: Build
-        run: npm run build
-      - name: Publish
-        run: npm publish --access public

package/skills/pica/SKILL.md

@@ -1,219 +0,0 @@
----
-name: pica
-description: Interact with third-party platforms (Gmail, Slack, HubSpot, Stripe, etc.) via Pica. Use when the user wants to search for available API actions, read API documentation, execute API calls, manage connections, or do anything involving third-party integrations.
-triggers:
-  - "search actions"
-  - "find actions"
-  - "execute action"
-  - "run action"
-  - "list connections"
-  - "add connection"
-  - "list platforms"
-  - "pica"
-  - "integration"
-  - "send email"
-  - "check calendar"
-  - "post to slack"
----
-
-# Pica
-
-Pica gives you access to 200+ third-party platforms (Gmail, Slack, HubSpot, Stripe, Shopify, etc.) through a single interface. It handles auth, rate limiting, and retries so you just call the action you need.
-
-## Two interfaces: MCP and CLI
-
-| Interface | Best for |
-|-----------|----------|
-| **MCP tools** | AI agents doing work (search, inspect, execute actions) |
-| **CLI** (`pica`) | Humans doing setup, OAuth, browsing |
-
-**Rule of thumb:** If you're doing the work, use MCP. If a human needs to interact (OAuth, setup), use CLI.
-
-## MCP tools
-
-The Pica MCP is your primary interface. It gives you structured JSON in/out with no parsing overhead.
-
-| Tool | What it does |
-|------|-------------|
-| `mcp__pica__list_pica_integrations` | List all platforms and active connections |
-| `mcp__pica__search_pica_platform_actions` | Search for actions on a platform |
-| `mcp__pica__get_pica_action_knowledge` | Get full API docs for an action (call before execute) |
-| `mcp__pica__execute_pica_action` | Execute an action on a connected platform |
-
-### Standard workflow
-
-```
-1. list_pica_integrations          -> get connection keys and platform names
-2. search_pica_platform_actions    -> find the right action
-3. get_pica_action_knowledge       -> read the docs (REQUIRED before execute)
-4. execute_pica_action             -> do the thing
-```
-
-### Step 1: List connections and platforms
-
-```
-mcp__pica__list_pica_integrations()
-```
-
-Returns all active connections (with connection keys) and available platforms. Always check this first.
-
-### Step 2: Search for the right action
-
-```
-mcp__pica__search_pica_platform_actions({
-  platform: "gmail",
-  query: "send email",
-  agentType: "execute"
-})
-```
-
-- `agentType: "execute"` when you intend to run the action
-- `agentType: "knowledge"` when you want to understand the API or write code
-- Platform names are kebab-case: `gmail`, `hubspot`, `google-calendar`, `ship-station`
-- Get the exact platform name from `list_pica_integrations`
-
-### Step 3: Get action knowledge (required before execute)
-
-```
-mcp__pica__get_pica_action_knowledge({
-  actionId: "conn_mod_def::ABC123::XYZ789",
-  platform: "gmail"
-})
-```
-
-Returns parameters, request/response schemas, caveats, and examples. You MUST call this before executing.
-
-### Step 4: Execute
-
-```
-mcp__pica__execute_pica_action({
-  actionId: "conn_mod_def::ABC123::XYZ789",
-  connectionKey: "live::gmail::default::abc123",
-  platform: "gmail",
-  data: { to: "someone@example.com", subject: "Hello", body: "Hi there" },
-  pathVariables: { userId: "me" }
-})
-```
-
-Pass: `connectionKey` from step 1, `actionId` from step 2, parameters from step 3.
-
-## CLI reference
-
-For setup, OAuth, and human-facing tasks.
-
-### Setup: `pica init`
-
-First run prompts for API key, validates it, and installs the MCP into your AI agents.
-
-Re-running `pica init` after setup shows a status dashboard:
-
-```
-  Current Setup
-  ──────────────────────────────────────────
-  API Key:  sk_test_...9j-Y
-  Config:   ~/.pica/config.json
-
-  Agent           Global  Project
-  ──────────────  ──────  ───────
-  Claude Code     ● yes   ● yes
-  Claude Desktop  ● yes   -
-  Cursor          ○ no    ○ no
-  Windsurf        -       -
-
-  - = not detected on this machine
-```
-
-Then offers targeted actions (only relevant options shown):
-
-| Action | What it does |
-|--------|-------------|
-| Update API key | Validates new key, re-installs MCP to all agents that have it |
-| Install MCP to more agents | Shows only detected agents missing the MCP |
-| Install MCP for this project | Creates project-level configs in cwd |
-| Start fresh | Full setup from scratch |
-
-Flags: `-y` (skip confirmations), `-g` (global install), `-p` (project install).
-
-### Other commands
-
-| Command | Description |
-|---------|-------------|
-| `pica add <platform>` | Connect a platform via OAuth (opens browser) |
-| `pica list` | List connections with keys |
-| `pica platforms` | Browse all 200+ platforms |
-| `pica search <platform> [query]` | Search for actions |
-| `pica actions knowledge <id>` | Get API docs for an action |
-| `pica exec <id>` | Execute an action |
-
-All commands support `--json` for machine-readable output.
-
-### Aliases
-
-`pica ls` = list, `pica p` = platforms, `pica a search` = actions search, `pica a k` = actions knowledge, `pica a x` = actions execute.
-
-### Exec flags
-
-```bash
-pica exec <actionId> \
-  -c <connectionKey> \
-  -d '{"key": "value"}' \
-  -p pathVar=value \
-  -q queryParam=value \
-  --json
-```
-
-## Key concepts
-
-- **Connection key**: Identifies which authenticated connection to use. Format: `live::gmail::default::abc123`. Get from `list_pica_integrations` or `pica list`.
-- **Action ID**: Identifies a specific API action. Starts with `conn_mod_def::`. Get from search results.
-- **Platform name**: Kebab-case identifier (`gmail`, `hubspot`, `google-calendar`, `ship-station`). Get from `list_pica_integrations`.
-- **Passthrough proxy**: All actions route through Pica's proxy which injects auth, handles rate limits, and normalizes responses. You never touch raw OAuth tokens.
-- **Pagination**: Some actions return `nextPageToken` or similar. Pass it back in subsequent requests to page through results.
-
-## MCP installation details
-
-`pica init` writes MCP configs here:
-
-| Agent | Global | Project |
-|-------|--------|---------|
-| Claude Code | `~/.claude.json` | `.mcp.json` |
-| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | n/a |
-| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` | n/a |
-
-Global = available everywhere. Project = committed to repo, shared with team (each person needs their own API key).
-
-If MCP tools are not available, install and init:
-
-```bash
-cd /Users/moe/projects/one/connection-cli
-npm install && npm run build && npm link
-pica init
-```
-
-## Common patterns
-
-### Send an email
-1. Search: `platform: "gmail", query: "send email"`
-2. Knowledge: get the action docs
-3. Execute with `data: { to, subject, body, connectionKey }`
-
-### Read emails
-1. Search: `platform: "gmail", query: "get emails"`
-2. Knowledge: understand pagination (numberOfEmails, pageToken)
-3. Execute with `data: { connectionKey, numberOfEmails, label, query }`
-
-### Post to Slack
-1. Search: `platform: "slack", query: "post message"`
-2. Knowledge: get channel ID format
-3. Execute with `data: { channel, text }`
-
-### CRM operations
-1. Search: `platform: "hubspot"` or `"attio"`, query: `"create contact"` / `"list contacts"`
-2. Knowledge: understand required fields
-3. Execute with the right data shape
-
-### Calendar
-1. Search: `platform: "google-calendar", query: "list events"`
-2. Knowledge: understand time format, calendar ID
-3. Execute with date range parameters

package/src/commands/actions.ts

@@ -1,385 +0,0 @@
-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');
-}