@continuedev/continuous-ai 1.0.0

package/README.md

@@ -0,0 +1,170 @@
+# @continuedev/continuous-ai
+
+CLI tool for interacting with Continue agent checks on pull requests.
+
+## Installation
+
+```bash
+npm install -g @continuedev/continuous-ai
+```
+
+## Usage
+
+### Setup
+
+Get your API key from [hub.continue.dev/settings/api-keys](https://hub.continue.dev/settings/api-keys) and set it:
+
+```bash
+export CONTINUE_API_KEY="con-xxx"
+```
+
+Or pass it with the `--token` flag to each command.
+
+### Commands
+
+#### `cai status <pr-url>`
+
+List all agent checks for a pull request with their current status.
+
+```bash
+cai status https://github.com/owner/repo/pull/123
+```
+
+Options:
+- `--org <slug>` - Organization context
+- `--token <key>` - API key (or use CONTINUE_API_KEY env var)
+- `--format json|table` - Output format (default: table)
+
+#### `cai wait <pr-url>`
+
+Block until all agent checks complete or fail.
+
+```bash
+cai wait https://github.com/owner/repo/pull/123
+```
+
+Options:
+- `--org <slug>` - Organization context
+- `--token <key>` - API key
+- `--timeout <seconds>` - Max wait time (default: 600)
+- `--fail-fast` - Exit immediately on first failure
+- `--format json|table` - Output format
+
+#### `cai logs <session-id>`
+
+View logs/state for a specific agent session.
+
+```bash
+cai logs A0042
+```
+
+Options:
+- `--org <slug>` - Organization context
+- `--token <key>` - API key
+- `--tail <lines>` - Show last N lines (default: all)
+
+#### `cai diff <session-id>`
+
+View code diff for an agent session.
+
+```bash
+cai diff A0042
+```
+
+Options:
+- `--org <slug>` - Organization context
+- `--token <key>` - API key
+- `--format unified|json` - Output format (default: unified)
+
+#### `cai approve <pr-url>`
+
+Approve changes and optionally merge the PR.
+
+```bash
+cai approve https://github.com/owner/repo/pull/123 --merge
+```
+
+Options:
+- `--org <slug>` - Organization context
+- `--token <key>` - API key
+- `--merge` - Also merge the PR (default: just mark ready)
+- `--merge-method squash|merge|rebase` - Merge method (default: squash)
+
+#### `cai reject <pr-url>`
+
+Reject changes and close the PR.
+
+```bash
+cai reject https://github.com/owner/repo/pull/123 --reason "Does not meet requirements"
+```
+
+Options:
+- `--org <slug>` - Organization context
+- `--token <key>` - API key
+- `--reason <text>` - Optional rejection reason
+
+## Exit Codes
+
+- `0` - Success
+- `1` - General error (API error, not found, etc.)
+- `2` - No sessions found for PR
+- `124` - Timeout reached
+
+## Configuration
+
+You can save your API key in `~/.continue/cli-config.json`:
+
+```json
+{
+  "apiKey": "con-xxx",
+  "apiUrl": "https://api.continue.dev"
+}
+```
+
+### Using Staging Environment
+
+For internal testing with the staging environment, configure the staging API URL:
+
+```json
+{
+  "apiKey": "con-xxx",
+  "apiUrl": "https://api.continue-stage.tools"
+}
+```
+
+Get your staging API key from [hub.continue-stage.tools/settings/api-keys](https://hub.continue-stage.tools/settings/api-keys).
+
+You can also use environment variables:
+
+```bash
+export CONTINUE_API_KEY="con-your-staging-key"
+export CONTINUE_API_URL="https://api.continue-stage.tools"
+```
+
+## Example Workflow
+
+```bash
+#!/bin/bash
+# Wait for agents, then approve and merge if successful
+
+export CONTINUE_API_KEY="con-xxx"
+PR_URL="https://github.com/owner/repo/pull/123"
+
+# Wait for completion with 5 minute timeout
+cai wait "$PR_URL" --timeout 300 --fail-fast
+
+# If successful, approve and merge
+if [ $? -eq 0 ]; then
+  echo "All agents passed! Merging PR..."
+  cai approve "$PR_URL" --merge --merge-method squash
+else
+  echo "Agents failed. Checking logs..."
+  # Get first failed session ID from status output
+  SESSION_ID=$(cai status "$PR_URL" --format json | jq -r '.sessions[] | select(.status == "failed") | .id' | head -1)
+  cai logs "$SESSION_ID"
+fi
+```
+
+## License
+
+MIT

package/bin/cai.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/index.js';

package/bin/continuous-ai.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/index.js';

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@continuedev/continuous-ai",
+  "version": "1.0.0",
+  "description": "CLI tool for interacting with Continue agent checks on pull requests",
+  "type": "module",
+  "bin": {
+    "cai": "./bin/cai.js",
+    "continuous-ai": "./bin/continuous-ai.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "echo 'No build step needed - continuous-ai uses plain JavaScript'",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "continue",
+    "agent",
+    "cli",
+    "github",
+    "pull-request"
+  ],
+  "author": "Continue",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/continuedev/remote-config-server",
+    "directory": "packages/continuous-ai"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "node-fetch": "^3.3.2"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.3",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "semantic-release": "^24.2.7",
+    "semantic-release-monorepo": "^8.0.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/approve.js

@@ -0,0 +1,52 @@
+import chalk from 'chalk';
+import { getApiKey, getApiUrl, requireApiKey } from '../lib/auth.js';
+import { ApiClient } from '../lib/api-client.js';
+import { parsePrUrl } from '../lib/pr-parser.js';
+import { createSpinner } from '../lib/formatters.js';
+
+export function approveCommand(program) {
+  program
+    .command('approve <pr-url>')
+    .description('Approve changes and optionally merge the PR')
+    .option('--org <slug>', 'Organization context')
+    .option('--token <key>', 'API key')
+    .option('--merge', 'Also merge the PR', false)
+    .option('--merge-method <method>', 'Merge method (squash|merge|rebase)', 'squash')
+    .action(async (prUrl, options) => {
+      const spinner = createSpinner('Approving pull request...');
+      try {
+        // Get API key
+        const apiKey = getApiKey(options.token);
+        requireApiKey(apiKey);
+
+        // Parse PR URL
+        const pr = parsePrUrl(prUrl);
+
+        // Create API client
+        const client = new ApiClient(getApiUrl(), apiKey);
+
+        spinner.start();
+
+        // Approve PR
+        const result = await client.approvePr(pr.url, {
+          organizationSlug: options.org,
+          autoMerge: options.merge,
+          mergeMethod: options.mergeMethod,
+        });
+
+        spinner.stop();
+
+        if (result.merged) {
+          console.log(chalk.green('✓') + ' Pull request approved and merged!');
+          console.log(`  ${prUrl}`);
+        } else {
+          console.log(chalk.green('✓') + ' Pull request marked as ready for review!');
+          console.log(`  ${prUrl}`);
+        }
+      } catch (error) {
+        spinner.stop();
+        console.error('ERROR:', error.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/diff.js

@@ -0,0 +1,40 @@
+import { getApiKey, getApiUrl, requireApiKey } from '../lib/auth.js';
+import { ApiClient } from '../lib/api-client.js';
+
+export function diffCommand(program) {
+  program
+    .command('diff <session-id>')
+    .description('View code diff for an agent session')
+    .option('--token <key>', 'API key')
+    .option('--format <type>', 'Output format (unified|json)', 'unified')
+    .action(async (sessionId, options) => {
+      try {
+        // Get API key
+        const apiKey = getApiKey(options.token);
+        requireApiKey(apiKey);
+
+        // Create API client
+        const client = new ApiClient(getApiUrl(), apiKey);
+
+        // Get session diff
+        const diff = await client.getSessionDiff(sessionId);
+
+        // Format output
+        if (options.format === 'json') {
+          console.log(JSON.stringify(diff, null, 2));
+        } else if (typeof diff === 'string') {
+          // Already a unified diff string
+          console.log(diff);
+        } else if (diff.diff) {
+          // Diff is in a property
+          console.log(diff.diff);
+        } else {
+          // Pretty print whatever we got
+          console.log(JSON.stringify(diff, null, 2));
+        }
+      } catch (error) {
+        console.error('ERROR:', error.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/logs.js

@@ -0,0 +1,42 @@
+import { getApiKey, getApiUrl, requireApiKey } from '../lib/auth.js';
+import { ApiClient } from '../lib/api-client.js';
+
+export function logsCommand(program) {
+  program
+    .command('logs <session-id>')
+    .description('View logs/state for a specific agent session')
+    .option('--token <key>', 'API key')
+    .option('--tail <lines>', 'Show last N lines', parseInt)
+    .action(async (sessionId, options) => {
+      try {
+        // Get API key
+        const apiKey = getApiKey(options.token);
+        requireApiKey(apiKey);
+
+        // Create API client
+        const client = new ApiClient(getApiUrl(), apiKey);
+
+        // Get session state
+        const state = await client.getSessionState(sessionId);
+
+        // Format state as readable output
+        if (typeof state === 'string') {
+          console.log(state);
+        } else {
+          // Pretty print JSON state
+          const stateStr = JSON.stringify(state, null, 2);
+
+          if (options.tail) {
+            const lines = stateStr.split('\n');
+            const tailLines = lines.slice(-options.tail);
+            console.log(tailLines.join('\n'));
+          } else {
+            console.log(stateStr);
+          }
+        }
+      } catch (error) {
+        console.error('ERROR:', error.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/reject.js

@@ -0,0 +1,48 @@
+import chalk from 'chalk';
+import { getApiKey, getApiUrl, requireApiKey } from '../lib/auth.js';
+import { ApiClient } from '../lib/api-client.js';
+import { parsePrUrl } from '../lib/pr-parser.js';
+import { createSpinner } from '../lib/formatters.js';
+
+export function rejectCommand(program) {
+  program
+    .command('reject <pr-url>')
+    .description('Reject changes and close the PR')
+    .option('--org <slug>', 'Organization context')
+    .option('--token <key>', 'API key')
+    .option('--reason <text>', 'Optional rejection reason')
+    .action(async (prUrl, options) => {
+      const spinner = createSpinner('Rejecting pull request...');
+      try {
+        // Get API key
+        const apiKey = getApiKey(options.token);
+        requireApiKey(apiKey);
+
+        // Parse PR URL
+        const pr = parsePrUrl(prUrl);
+
+        // Create API client
+        const client = new ApiClient(getApiUrl(), apiKey);
+
+        spinner.start();
+
+        // Reject PR
+        const result = await client.rejectPr(pr.url, {
+          organizationSlug: options.org,
+          reason: options.reason,
+        });
+
+        spinner.stop();
+
+        console.log(chalk.red('✗') + ' Pull request rejected and closed.');
+        console.log(`  ${prUrl}`);
+        if (options.reason) {
+          console.log(`  Reason: ${options.reason}`);
+        }
+      } catch (error) {
+        spinner.stop();
+        console.error('ERROR:', error.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/status.js

@@ -0,0 +1,58 @@
+import { getApiKey, getApiUrl, requireApiKey } from '../lib/auth.js';
+import { ApiClient } from '../lib/api-client.js';
+import { parsePrUrl } from '../lib/pr-parser.js';
+import { formatSessionsTable, formatSessionsJson } from '../lib/formatters.js';
+
+export function statusCommand(program) {
+  program
+    .command('status <pr-url>')
+    .description('List all agent checks for a pull request')
+    .option('--org <slug>', 'Organization context')
+    .option('--token <key>', 'API key')
+    .option('--format <type>', 'Output format (table|json)', 'table')
+    .action(async (prUrl, options) => {
+      try {
+        // Get API key
+        const apiKey = getApiKey(options.token);
+        requireApiKey(apiKey);
+
+        // Parse PR URL
+        const pr = parsePrUrl(prUrl);
+
+        // Create API client
+        const client = new ApiClient(getApiUrl(), apiKey);
+
+        // Get agent sessions
+        const result = await client.getAgentSessions(pr.url, {
+          organizationId: options.org,
+        });
+
+        const sessions = result.sessions || [];
+
+        // Calculate summary
+        const terminalStates = ['completed', 'failed', 'cancelled', 'suspended'];
+        const summary = {
+          total: sessions.length,
+          completed: sessions.filter(s => s.status === 'completed').length,
+          running: sessions.filter(s => !terminalStates.includes(s.status)).length,
+          failed: sessions.filter(s => s.status === 'failed').length,
+          pending: sessions.filter(s => s.status === 'pending').length,
+        };
+
+        // Format output
+        if (options.format === 'json') {
+          console.log(formatSessionsJson(sessions, summary));
+        } else {
+          console.log(formatSessionsTable(sessions, summary));
+        }
+
+        // Exit with error if no sessions found
+        if (sessions.length === 0) {
+          process.exit(2);
+        }
+      } catch (error) {
+        console.error('ERROR:', error.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/wait.js

@@ -0,0 +1,77 @@
+import { getApiKey, getApiUrl, requireApiKey } from '../lib/auth.js';
+import { ApiClient } from '../lib/api-client.js';
+import { parsePrUrl } from '../lib/pr-parser.js';
+import { formatSessionsTable, formatSessionsJson, createSpinner } from '../lib/formatters.js';
+
+export function waitCommand(program) {
+  program
+    .command('wait <pr-url>')
+    .description('Block until all agent checks complete or fail')
+    .option('--org <slug>', 'Organization context')
+    .option('--token <key>', 'API key')
+    .option('--timeout <seconds>', 'Max wait time', parseInt, 600)
+    .option('--fail-fast', 'Exit immediately on first failure', false)
+    .option('--format <type>', 'Output format (table|json)', 'table')
+    .action(async (prUrl, options) => {
+      let spinner;
+      try {
+        // Get API key
+        const apiKey = getApiKey(options.token);
+        requireApiKey(apiKey);
+
+        // Parse PR URL
+        const pr = parsePrUrl(prUrl);
+
+        // Create API client
+        const client = new ApiClient(getApiUrl(), apiKey);
+
+        // Show spinner for table format
+        if (options.format !== 'json') {
+          spinner = createSpinner('Waiting for agent checks to complete...');
+          spinner.start();
+        }
+
+        // Wait for completion
+        const result = await client.waitForCompletion(pr.url, {
+          timeout: options.timeout,
+          failFast: options.failFast,
+          organizationId: options.org,
+        });
+
+        if (spinner) {
+          spinner.stop();
+        }
+
+        const sessions = result.sessions || [];
+        const summary = result.summary;
+
+        // Format output
+        if (options.format === 'json') {
+          console.log(formatSessionsJson(sessions, summary));
+        } else {
+          console.log(formatSessionsTable(sessions, summary));
+        }
+
+        // Exit codes
+        if (summary.failed > 0) {
+          process.exit(1); // Any failed
+        } else if (result.shouldContinuePolling) {
+          process.exit(124); // Timeout
+        } else {
+          process.exit(0); // Success
+        }
+      } catch (error) {
+        if (spinner) {
+          spinner.stop();
+        }
+
+        if (error.message.includes('Timeout')) {
+          console.error('ERROR: Timeout reached. Agent checks are still running.');
+          process.exit(124);
+        } else {
+          console.error('ERROR:', error.message);
+          process.exit(1);
+        }
+      }
+    });
+}

package/src/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { statusCommand } from './commands/status.js';
+import { waitCommand } from './commands/wait.js';
+import { logsCommand } from './commands/logs.js';
+import { diffCommand } from './commands/diff.js';
+import { approveCommand } from './commands/approve.js';
+import { rejectCommand } from './commands/reject.js';
+
+const program = new Command();
+
+program
+  .name('cai')
+  .description('CLI tool for interacting with Continue agent checks on pull requests')
+  .version('0.1.0');
+
+// Register commands
+statusCommand(program);
+waitCommand(program);
+logsCommand(program);
+diffCommand(program);
+approveCommand(program);
+rejectCommand(program);
+
+program.parse(process.argv);

package/src/lib/api-client.js

@@ -0,0 +1,149 @@
+import fetch from 'node-fetch';
+
+/**
+ * API client wrapper for Continue API
+ */
+export class ApiClient {
+  constructor(apiUrl, apiKey) {
+    this.apiUrl = apiUrl;
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Make a GET request
+   */
+  async get(path, queryParams = {}) {
+    const url = new URL(path, this.apiUrl);
+    Object.entries(queryParams).forEach(([key, value]) => {
+      if (value !== undefined && value !== null) {
+        url.searchParams.append(key, String(value));
+      }
+    });
+
+    const response = await fetch(url.toString(), {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`API Error (${response.status}): ${error}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Make a POST request
+   */
+  async post(path, body = {}) {
+    const url = new URL(path, this.apiUrl);
+
+    const response = await fetch(url.toString(), {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`API Error (${response.status}): ${error}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Wait for agent completion (with polling)
+   */
+  async waitForCompletion(pullRequestUrl, options = {}) {
+    const { timeout = 600, failFast = false, organizationId } = options;
+    const startTime = Date.now();
+    const maxTime = timeout * 1000;
+    let backoffDelay = 1000; // Start with 1s
+
+    while (Date.now() - startTime < maxTime) {
+      const result = await this.get('/agents/wait-for-completion', {
+        pullRequestUrl,
+        organizationId,
+        timeout: 30, // Server-side timeout
+        failFast: failFast ? 'true' : 'false',
+      });
+
+      if (!result.shouldContinuePolling) {
+        return result;
+      }
+
+      // Wait with exponential backoff
+      await new Promise(resolve => setTimeout(resolve, Math.min(backoffDelay, 5000)));
+      backoffDelay = Math.min(backoffDelay * 1.5, 5000);
+    }
+
+    throw new Error('Timeout reached waiting for agent completion');
+  }
+
+  /**
+   * Get agent sessions for a PR
+   */
+  async getAgentSessions(pullRequestUrl, options = {}) {
+    const { organizationId, limit = 100, offset = 0 } = options;
+    return this.get('/agents', {
+      pullRequestUrl,
+      organizationId,
+      limit,
+      offset,
+    });
+  }
+
+  /**
+   * Get agent session summary
+   */
+  async getSessionSummary(sessionId) {
+    return this.get(`/agents/${sessionId}/summary`);
+  }
+
+  /**
+   * Get agent session state (logs)
+   */
+  async getSessionState(sessionId) {
+    return this.get(`/agents/${sessionId}/state`);
+  }
+
+  /**
+   * Get agent session diff
+   */
+  async getSessionDiff(sessionId) {
+    return this.get(`/agents/${sessionId}/diff`);
+  }
+
+  /**
+   * Approve a PR and optionally merge
+   */
+  async approvePr(pullRequestUrl, options = {}) {
+    const { organizationSlug, autoMerge = false, mergeMethod = 'squash' } = options;
+    return this.post('/agents/approve-pr', {
+      pullRequestUrl,
+      organizationSlug,
+      autoMerge,
+      mergeMethod,
+    });
+  }
+
+  /**
+   * Reject a PR (close it)
+   */
+  async rejectPr(pullRequestUrl, options = {}) {
+    const { organizationSlug, reason } = options;
+    return this.post('/agents/reject-pr', {
+      pullRequestUrl,
+      organizationSlug,
+      reason,
+    });
+  }
+}

package/src/lib/auth.js

@@ -0,0 +1,71 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Get API key from multiple sources (priority order):
+ * 1. --token flag
+ * 2. CONTINUE_API_KEY env var
+ * 3. ~/.continue/cli-config.json
+ */
+export function getApiKey(tokenFlag) {
+  // 1. Check --token flag
+  if (tokenFlag) {
+    return tokenFlag;
+  }
+
+  // 2. Check environment variable
+  if (process.env.CONTINUE_API_KEY) {
+    return process.env.CONTINUE_API_KEY;
+  }
+
+  // 3. Check config file
+  const configPath = path.join(os.homedir(), '.continue', 'cli-config.json');
+  try {
+    if (fs.existsSync(configPath)) {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (config.apiKey) {
+        return config.apiKey;
+      }
+    }
+  } catch (error) {
+    // Ignore config file errors, will show error below
+  }
+
+  return null;
+}
+
+/**
+ * Get API URL from config or use default
+ */
+export function getApiUrl() {
+  const configPath = path.join(os.homedir(), '.continue', 'cli-config.json');
+  try {
+    if (fs.existsSync(configPath)) {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (config.apiUrl) {
+        return config.apiUrl;
+      }
+    }
+  } catch (error) {
+    // Ignore config file errors, use default
+  }
+
+  return process.env.CONTINUE_API_URL || 'https://api.continue.dev';
+}
+
+/**
+ * Validate that an API key is provided and show helpful error if not
+ */
+export function requireApiKey(apiKey) {
+  if (!apiKey) {
+    // Use hub.continue.dev for the settings page (web UI), not the API URL
+    console.error(`ERROR: No API key provided. Get one at https://hub.continue.dev/settings/api-keys (or your self-hosted hub)`);
+    console.error('');
+    console.error('Set it with:');
+    console.error('  export CONTINUE_API_KEY="con-xxx"');
+    console.error('Or pass it with:');
+    console.error('  cai <command> --token "con-xxx"');
+    process.exit(1);
+  }
+}

package/src/lib/formatters.js

@@ -0,0 +1,126 @@
+import chalk from 'chalk';
+
+/**
+ * Format agent session status as a table
+ */
+export function formatSessionsTable(sessions, summary) {
+  if (sessions.length === 0) {
+    return 'No agent sessions found for this PR.';
+  }
+
+  // Header
+  let output = '\nAgent Checks\n\n';
+
+  // Table header
+  const headers = ['Session', 'Status', 'Updated'];
+  const columnWidths = [12, 20, 20];
+
+  output += headers.map((h, i) => h.padEnd(columnWidths[i])).join('  ') + '\n';
+  output += columnWidths.map(w => '-'.repeat(w)).join('  ') + '\n';
+
+  // Table rows
+  for (const session of sessions) {
+    const sessionId = session.shortId || session.id.substring(0, 8);
+    const status = formatStatus(session.status);
+    const updated = formatRelativeTime(session.updatedAt);
+
+    output += [
+      sessionId.padEnd(columnWidths[0]),
+      status.padEnd(columnWidths[1] + 10), // +10 for ANSI codes
+      updated.padEnd(columnWidths[2]),
+    ].join('  ') + '\n';
+  }
+
+  // Summary
+  output += '\n';
+  output += `Summary: ${summary.completed} completed, ${summary.running} running, ${summary.failed} failed`;
+  if (summary.pending > 0) {
+    output += `, ${summary.pending} pending`;
+  }
+  output += '\n';
+
+  return output;
+}
+
+/**
+ * Format status with color and symbol
+ */
+function formatStatus(status) {
+  switch (status) {
+    case 'completed':
+      return chalk.green('✓ Completed');
+    case 'failed':
+      return chalk.red('✗ Failed');
+    case 'running':
+    case 'in_progress':
+      return chalk.yellow('⏳ Running');
+    case 'pending':
+      return chalk.gray('⏸ Pending');
+    case 'suspended':
+    case 'cancelled':
+      return chalk.gray('⚠ Cancelled');
+    default:
+      return chalk.gray(status);
+  }
+}
+
+/**
+ * Format timestamp as relative time
+ */
+function formatRelativeTime(timestamp) {
+  const now = Date.now();
+  const then = new Date(timestamp).getTime();
+  const diff = Math.abs(now - then) / 1000; // seconds
+
+  if (diff < 60) {
+    return 'just now';
+  } else if (diff < 3600) {
+    const mins = Math.floor(diff / 60);
+    return `${mins} minute${mins > 1 ? 's' : ''} ago`;
+  } else if (diff < 86400) {
+    const hours = Math.floor(diff / 3600);
+    return `${hours} hour${hours > 1 ? 's' : ''} ago`;
+  } else {
+    const days = Math.floor(diff / 86400);
+    return `${days} day${days > 1 ? 's' : ''} ago`;
+  }
+}
+
+/**
+ * Format sessions as JSON
+ */
+export function formatSessionsJson(sessions, summary) {
+  return JSON.stringify({ sessions, summary }, null, 2);
+}
+
+/**
+ * Show spinner with message
+ */
+export function createSpinner(message) {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  let interval;
+
+  return {
+    start() {
+      interval = setInterval(() => {
+        process.stdout.write(`\r${chalk.cyan(frames[i])} ${message}`);
+        i = (i + 1) % frames.length;
+      }, 80);
+    },
+    stop() {
+      if (interval) {
+        clearInterval(interval);
+        process.stdout.write('\r');
+      }
+    },
+    succeed(text) {
+      this.stop();
+      console.log(chalk.green('✓') + ' ' + text);
+    },
+    fail(text) {
+      this.stop();
+      console.log(chalk.red('✗') + ' ' + text);
+    },
+  };
+}

package/src/lib/pr-parser.js

@@ -0,0 +1,34 @@
+/**
+ * Parse a GitHub PR URL into its components
+ */
+export function parsePrUrl(url) {
+  try {
+    // More strict regex: must be HTTPS GitHub URL with proper format
+    const match = url.match(/^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/pull\/(\d+)(?:[?#].*)?$/);
+    if (!match) {
+      throw new Error('Invalid GitHub PR URL format. Expected: https://github.com/owner/repo/pull/123');
+    }
+
+    const [, owner, repo, prNumber] = match;
+    return {
+      owner,
+      repo,
+      prNumber: parseInt(prNumber, 10),
+      url,
+    };
+  } catch (error) {
+    throw new Error(`Failed to parse PR URL: ${error.message}`);
+  }
+}
+
+/**
+ * Validate a PR URL
+ */
+export function isValidPrUrl(url) {
+  try {
+    parsePrUrl(url);
+    return true;
+  } catch {
+    return false;
+  }
+}