@lincoln504/pi-research 0.0.0

package/src/stackexchange/cache.ts

@@ -0,0 +1,111 @@
+/**
+ * Simple file-based cache for Stack Exchange API responses
+ */
+
+import * as fs from 'node:fs';
+import { logger } from '../logger.ts';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+const CACHE_DIR = path.join(os.homedir(), '.pi', 'cache', 'stackexchange');
+
+// Lazy-initialize cache directory on first use (prevents race conditions)
+let cacheInitialized = false;
+
+function ensureCacheDir(): void {
+  if (cacheInitialized) {
+    return;
+  }
+  try {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+    cacheInitialized = true;
+  } catch {
+    // Directory might already exist
+    cacheInitialized = true;
+  }
+}
+
+export interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  ttl: number;
+}
+
+export function cacheGet<T>(key: string): T | null {
+  ensureCacheDir();
+  try {
+    const cachePath = path.join(CACHE_DIR, `${key}.json`);
+    const content = fs.readFileSync(cachePath, 'utf-8');
+    const entry: CacheEntry<T> = JSON.parse(content) as CacheEntry<T>;
+
+    // Check if cache entry is still valid
+    const now = Date.now();
+    const age = (now - entry.timestamp) / 1000; // Age in seconds
+
+    if (age > entry.ttl) {
+      // Cache expired
+      try {
+        fs.unlinkSync(cachePath);
+      } catch {
+        // Ignore errors when deleting expired cache
+      }
+      return null;
+    }
+
+    return entry.data;
+  } catch {
+    // Cache file doesn't exist or is invalid
+    return null;
+  }
+}
+
+export function cacheSet<T>(key: string, data: T, ttl: number): void {
+  ensureCacheDir();
+  try {
+    const cachePath = path.join(CACHE_DIR, `${key}.json`);
+    const entry: CacheEntry<T> = {
+      data,
+      timestamp: Date.now(),
+      ttl,
+    };
+    fs.writeFileSync(cachePath, JSON.stringify(entry));
+  } catch (error) {
+    logger.warn('[StackExchange] Failed to write cache:', error);
+  }
+}
+
+export function cacheClear(): void {
+  try {
+    const files = fs.readdirSync(CACHE_DIR);
+    for (const file of files) {
+      fs.unlinkSync(path.join(CACHE_DIR, file));
+    }
+  } catch (error) {
+    logger.warn('[StackExchange] Failed to clear cache:', error);
+  }
+}
+
+export function cacheGetStats(): { count: number; size: number } {
+  try {
+    const files = fs.readdirSync(CACHE_DIR);
+    let totalSize = 0;
+    for (const file of files) {
+      const filePath = path.join(CACHE_DIR, file);
+      const stats = fs.statSync(filePath);
+      totalSize += stats.size;
+    }
+    return {
+      count: files.length,
+      size: totalSize,
+    };
+  } catch {
+    return { count: 0, size: 0 };
+  }
+}
+
+// Sanitize cache keys (replace special characters)
+export function sanitizeCacheKey(key: string): string {
+  return key
+    .replace(/[^a-zA-Z0-9_-]/g, '_')
+    .substring(0, 100); // Limit length
+}

package/src/stackexchange/index.ts

@@ -0,0 +1,352 @@
+/**
+ * Stack Exchange Integration for pi-research
+ * Main command handler
+ */
+
+import type { Question, Answer, User, Site, StackExchangeConfig } from './types.ts';
+import { StackExchangeClient } from './rest-client.ts';
+import {
+  buildSearchQuery,
+  buildQuestionsQuery,
+  buildUserQuery,
+  buildSitesQuery,
+  Filters,
+} from './queries.ts';
+import {
+  formatQuestionsTable,
+  formatAnswersTable,
+  formatUsersTable,
+  formatSitesTable,
+  formatCompactQuestions,
+} from './output/index.ts';
+import {
+  formatUsersCompact,
+  formatSitesCompact,
+} from './output/compact.ts';
+import type { ExtensionContext, AgentToolResult } from '@mariozechner/pi-coding-agent';
+
+function notify(
+  ctx: ExtensionContext,
+  message: string,
+  type: 'info' | 'warning' | 'error',
+): void {
+  ctx.ui?.notify?.(message, type);
+}
+
+/**
+ * Load configuration from environment variables or defaults
+ */
+function loadConfig(): StackExchangeConfig {
+  return {
+    defaultSite: 'stackoverflow.com',
+    apiKey: process.env['STACKEXCHANGE_API_KEY'] ?? null,
+    requestTimeout: 30000, // 30 seconds
+  };
+}
+
+/**
+ * Main command handler for Stack Exchange operations
+ */
+export async function stackexchangeCommand(options: {
+  command: string;
+  params: Record<string, unknown>;
+  ctx: ExtensionContext;
+  signal?: AbortSignal;
+  onUpdate?: (_update: unknown) => void;
+}): Promise<AgentToolResult<unknown>> {
+  const { command, params, ctx, signal, onUpdate: _onUpdate } = options;
+
+  // Load config
+  const config = loadConfig();
+
+  // Initialize client
+  const client = new StackExchangeClient(
+    config.apiKey,
+    config.requestTimeout,
+  );
+
+  try {
+    // Check quota before making requests
+    if (client.isQuotaExhausted()) {
+      const quota = client.getQuotaInfo();
+      notify(
+        ctx,
+        `Stack Exchange API quota exhausted (${quota.remaining}/${quota.max} remaining)`,
+        'error',
+      );
+      return {
+        content: [{ type: 'text', text: `❌ Stack Exchange API quota exhausted (${quota.remaining}/${quota.max} remaining). Please wait until the quota resets.` }],
+        details: {
+          quota,
+          command,
+        },
+      };
+    }
+
+    // Warn if quota is low
+    if (client.isQuotaLow()) {
+      const quota = client.getQuotaInfo();
+      notify(
+        ctx,
+        `Stack Exchange API quota low: ${quota.remaining}/${quota.max} remaining`,
+        'warning',
+      );
+    }
+
+    // Execute command
+    let result: unknown;
+    switch (command) {
+    case 'search':
+      result = await executeSearch(params, client, config, signal);
+      break;
+    case 'get':
+      result = await executeGet(params, client, config, signal);
+      break;
+    case 'user':
+      result = await executeUser(params, client, config, signal);
+      break;
+    case 'site':
+      result = await executeSite(params, client, config, signal);
+      break;
+    default:
+      throw new Error(`Unknown command: ${command}`);
+    }
+
+    // Format output
+    const format = (params['format'] as string | undefined) ?? 'table';
+    let output: string;
+
+    if (format === 'json') {
+      output = JSON.stringify(result, null, 2);
+    } else if (format === 'compact') {
+      output = formatCompact(result);
+    } else {
+      output = formatTable(result);
+    }
+
+    // Add quota info
+    const quota = client.getQuotaInfo();
+    output += `\n---\n**API Quota:** ${quota.remaining}/${quota.max} remaining\n`;
+
+    return {
+      content: [{ type: 'text', text: output }],
+      details: {
+        quota,
+        command,
+      },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    notify(ctx, `Stack Exchange error: ${message}`, 'error');
+    return {
+      content: [{ type: 'text', text: `❌ Stack Exchange error: ${message}` }],
+      details: {
+        quota: client.getQuotaInfo(),
+        command,
+      },
+    };
+  }
+}
+
+/**
+ * Execute search command
+ */
+async function executeSearch(
+  params: Record<string, unknown>,
+  client: StackExchangeClient,
+  config: StackExchangeConfig,
+  signal?: AbortSignal,
+): Promise<Question[]> {
+  const query = params['query'] as string | undefined;
+  const site = (params['site'] as string | undefined) ?? config.defaultSite;
+  const limit = Math.min((params['limit'] as number | undefined) ?? 10, 100);
+  const tagsInput = params['tags'] as string | null;
+  // Convert tags: "tag1,tag2" is converted to semicolon-separated for API
+  const tags = tagsInput ? tagsInput.split(',').map(t => t.trim()).filter(t => t.length > 0).join(';') : undefined;
+
+  // Build query parameters
+  const queryParams = {
+    order: 'desc' as const,
+    sort: 'relevance' as const,
+    q: query ?? undefined,
+    tagged: tags ?? undefined,
+    pagesize: limit,
+    site,
+  };
+
+  const searchParams = buildSearchQuery(queryParams);
+
+  // Make request
+  const response = await client.request<Question>(
+    { method: 'GET', endpoint: '/search/advanced', params: searchParams },
+    signal,
+  );
+
+  return response.items;
+}
+
+/**
+ * Execute get command (get question by ID)
+ */
+async function executeGet(
+  params: Record<string, unknown>,
+  client: StackExchangeClient,
+  config: StackExchangeConfig,
+  signal?: AbortSignal,
+): Promise<{ question: Question; answers: Answer[] }> {
+  const id = params['id'] as string | number | undefined;
+  const site = (params['site'] as string | undefined) ?? config.defaultSite;
+
+  if (id === undefined) {
+    throw new Error('ID parameter is required for get command');
+  }
+
+  // Get question with full body
+  const questionParams = buildQuestionsQuery({
+    ids: id,
+    site,
+    filter: Filters.WITH_BODY,
+  });
+
+  const response = await client.request<Question>(
+    { method: 'GET', endpoint: `/questions/${id}`, params: questionParams },
+    signal,
+  );
+
+  if (response.items.length === 0) {
+    throw new Error(`Question not found: ${id}`);
+  }
+
+  const question = response.items[0];
+  if (question === undefined) {
+    throw new Error('Question not found');
+  }
+
+  // Always get answers
+  const answersParams = buildQuestionsQuery({
+    ids: id,
+    site,
+    filter: Filters.ANSWERS_WITH_BODY,
+  });
+
+  const answersResponse = await client.request<Answer>(
+    { method: 'GET', endpoint: `/questions/${id}/answers`, params: answersParams },
+    signal,
+  );
+
+  return { question, answers: answersResponse.items };
+}
+
+/**
+ * Execute user command
+ */
+async function executeUser(
+  params: Record<string, unknown>,
+  client: StackExchangeClient,
+  config: StackExchangeConfig,
+  signal?: AbortSignal,
+): Promise<User[]> {
+  const id = params['id'] as string | number | undefined;
+  const site = (params['site'] as string | undefined) ?? config.defaultSite;
+  const limit = Math.min((params['limit'] as number | undefined) ?? 1, 100);
+
+  if (id === undefined) {
+    throw new Error('ID parameter is required for user command');
+  }
+
+  const userParams = buildUserQuery({
+    ids: id,
+    site,
+    pagesize: limit,
+  });
+
+  const response = await client.request<User>(
+    { method: 'GET', endpoint: `/users/${id}`, params: userParams },
+    signal,
+  );
+
+  if (response.items.length === 0) {
+    throw new Error(`User not found: ${id}`);
+  }
+
+  return response.items;
+}
+
+/**
+ * Execute site command
+ */
+async function executeSite(
+  _params: Record<string, unknown>,
+  client: StackExchangeClient,
+  _config: StackExchangeConfig,
+  signal?: AbortSignal,
+): Promise<Site[]> {
+  const sitesParams = buildSitesQuery({ pagesize: 100 });
+
+  const response = await client.request<Site>(
+    { method: 'GET', endpoint: '/sites', params: sitesParams },
+    signal,
+  );
+
+  return response.items;
+}
+
+/**
+ * Format results as table
+ */
+function formatTable(result: unknown): string {
+  if (Array.isArray(result)) {
+    const first = result[0] as Record<string, unknown> | undefined;
+    if (first && typeof first === 'object') {
+      if ('badge_counts' in first) {
+        // Users
+        return formatUsersTable(result as User[]);
+      }
+      if ('api_site_parameter' in first) {
+        // Sites
+        return formatSitesTable(result as Site[]);
+      }
+      if ('question_id' in first || 'answer_id' in first) {
+        // Questions or Answers
+        if ('answer_id' in first) {
+          return formatAnswersTable(result as Answer[]);
+        }
+        return formatQuestionsTable(result as Question[]);
+      }
+    }
+  } else if (typeof result === 'object' && result !== null) {
+    if ('question' in result && 'answers' in result) {
+      // Question with answers
+      const r = result as { question: Question; answers: Answer[] };
+      let output = formatQuestionsTable([r.question]);
+      if (r.answers.length > 0) {
+        output += `\n${  formatAnswersTable(r.answers)}`;
+      }
+      return output;
+    }
+  }
+
+  // Fallback to JSON
+  return JSON.stringify(result, null, 2);
+}
+
+/**
+ * Format results as compact
+ */
+function formatCompact(result: unknown): string {
+  if (Array.isArray(result)) {
+    const first = result[0] as Record<string, unknown> | undefined;
+    if (first && typeof first === 'object') {
+      if ('badge_counts' in first) {
+        return formatUsersCompact(result as User[]);
+      }
+      if ('api_site_parameter' in first) {
+        return formatSitesCompact(result as Site[]);
+      }
+      if ('question_id' in first) {
+        return formatCompactQuestions(result as Question[]);
+      }
+    }
+  }
+  return JSON.stringify(result);
+}

package/src/stackexchange/output/compact.ts

@@ -0,0 +1,64 @@
+/**
+ * Compact output formatter for Stack Exchange results
+ */
+
+import type { Question, Answer, User, Site } from '../types';
+
+export function formatQuestionsCompact(questions: Question[]): string {
+  if (questions.length === 0) {
+    return 'No questions found.';
+  }
+
+  const lines: string[] = [];
+  let index = 1;
+  for (const q of questions) {
+    const accepted = q.accepted_answer_id ? '✓' : ' ';
+    lines.push(`${index}. ${accepted} [${q.title}](${q.link}) (${q.score} pts, ${q.answer_count} ans, ${q.view_count} views)`);
+    index++;
+  }
+  return lines.join('\n');
+}
+
+export function formatAnswersCompact(answers: Answer[]): string {
+  if (answers.length === 0) {
+    return 'No answers found.';
+  }
+
+  const lines: string[] = [];
+  let index = 1;
+  for (const a of answers) {
+    const accepted = a.is_accepted ? '✓' : ' ';
+    const authorName = a.owner?.display_name ?? 'Unknown';
+    lines.push(`${index}. ${accepted} by ${authorName} (${a.score} pts)`);
+    index++;
+  }
+  return lines.join('\n');
+}
+
+export function formatUsersCompact(users: User[]): string {
+  if (users.length === 0) {
+    return 'No users found.';
+  }
+
+  const lines: string[] = [];
+  let index = 1;
+  for (const u of users) {
+    lines.push(`${index}. ${u.display_name} (rep: ${u.reputation}, 🥇${u.badge_counts.gold} 🥈${u.badge_counts.silver} 🥉${u.badge_counts.bronze})`);
+    index++;
+  }
+  return lines.join('\n');
+}
+
+export function formatSitesCompact(sites: Site[]): string {
+  if (sites.length === 0) {
+    return 'No sites found.';
+  }
+
+  const lines: string[] = [];
+  let index = 1;
+  for (const s of sites) {
+    lines.push(`${index}. ${s.name} (\`${s.api_site_parameter}\`) - ${s.audience || 'N/A'}`);
+    index++;
+  }
+  return lines.join('\n');
+}

package/src/stackexchange/output/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Output formatters for Stack Exchange results
+ */
+
+export * from './table.ts';
+export * from './json.ts';
+export * from './compact.ts';

package/src/stackexchange/output/json.ts

@@ -0,0 +1,21 @@
+/**
+ * JSON output formatter for Stack Exchange results
+ */
+
+import type { Question, Answer, User, Site } from '../types';
+
+export function formatQuestionsJSON(questions: Question[]): string {
+  return JSON.stringify(questions, null, 2);
+}
+
+export function formatAnswersJSON(answers: Answer[]): string {
+  return JSON.stringify(answers, null, 2);
+}
+
+export function formatUsersJSON(users: User[]): string {
+  return JSON.stringify(users, null, 2);
+}
+
+export function formatSitesJSON(sites: Site[]): string {
+  return JSON.stringify(sites, null, 2);
+}

package/src/stackexchange/output/table.ts

@@ -0,0 +1,123 @@
+/**
+ * Table output formatter for Stack Exchange results
+ */
+
+import type { Question, Answer, User, Site } from '../types';
+
+export function formatQuestionsTable(questions: Question[]): string {
+  if (questions.length === 0) {
+    return 'No questions found.\n';
+  }
+
+  let output = '# Stack Exchange Questions\n\n';
+  output += `Found: ${questions.length} question${questions.length !== 1 ? 's' : ''}\n\n`;
+
+  for (const q of questions) {
+    output += `## ${q.title}\n\n`;
+    output += `- **Score:** ${q.score}\n`;
+    output += `- **Views:** ${q.view_count}\n`;
+    output += `- **Answers:** ${q.answer_count}${q.accepted_answer_id ? ' ✓' : ''}\n`;
+    output += `- **Tags:** ${q.tags.join(', ')}\n`;
+    if (q.owner) {
+      output += `- **Author:** ${q.owner.display_name} (rep: ${q.owner.reputation})\n`;
+    }
+    output += `- **Link:** ${q.link}\n`;
+    output += `- **Created:** ${new Date(q.creation_date * 1000).toLocaleString()}\n`;
+
+    if (q.body && q.body.length < 1000) {
+      output += `- **Body:** ${q.body.substring(0, 500)}...\n`;
+    }
+
+    output += '\n---\n\n';
+  }
+
+  return output;
+}
+
+export function formatAnswersTable(answers: Answer[]): string {
+  if (answers.length === 0) {
+    return 'No answers found.\n';
+  }
+
+  let output = '# Stack Exchange Answers\n\n';
+  output += `Found: ${answers.length} answer${answers.length !== 1 ? 's' : ''}\n\n`;
+
+  for (const a of answers) {
+    const authorName = a.owner?.display_name ?? 'Unknown';
+    output += `## Answer by ${authorName}\n\n`;
+    output += `- **Score:** ${a.score}${a.is_accepted ? ' ✓ (Accepted)' : ''}\n`;
+    if (a.owner) {
+      output += `- **Author:** ${a.owner.display_name} (rep: ${a.owner.reputation})\n`;
+    }
+    output += `- **Question ID:** ${a.question_id}\n`;
+    output += `- **Created:** ${new Date(a.creation_date * 1000).toLocaleString()}\n`;
+
+    if (a.body && a.body.length < 2000) {
+      output += `\n### Answer Body\n\n${a.body}\n`;
+    }
+
+    output += '\n---\n\n';
+  }
+
+  return output;
+}
+
+export function formatUsersTable(users: User[]): string {
+  if (users.length === 0) {
+    return 'No users found.\n';
+  }
+
+  let output = '# Stack Exchange Users\n\n';
+  output += `Found: ${users.length} user${users.length !== 1 ? 's' : ''}\n\n`;
+
+  for (const u of users) {
+    output += `## ${u.display_name}\n\n`;
+    output += `- **Reputation:** ${u.reputation}\n`;
+    output += `- **Badges:** 🥇 ${u.badge_counts.gold} 🥈 ${u.badge_counts.silver} 🥉 ${u.badge_counts.bronze}\n`;
+    output += `- **User ID:** ${u.user_id}\n`;
+    output += `- **Member since:** ${new Date(u.creation_date * 1000).toLocaleDateString()}\n`;
+    if (u.location) {
+      output += `- **Location:** ${u.location}\n`;
+    }
+    if (u.website_url) {
+      output += `- **Website:** ${u.website_url}\n`;
+    }
+    output += `- **Profile:** ${u.link}\n`;
+    output += '\n---\n\n';
+  }
+
+  return output;
+}
+
+export function formatSitesTable(sites: Site[]): string {
+  if (sites.length === 0) {
+    return 'No sites found.\n';
+  }
+
+  let output = '# Stack Exchange Sites\n\n';
+  output += `Found: ${sites.length} site${sites.length !== 1 ? 's' : ''}\n\n`;
+
+  output += '| Site | API Parameter | Audience |\n';
+  output += '|------|---------------|----------|\n';
+
+  for (const s of sites) {
+    output += `| ${s.name} | \`${s.api_site_parameter}\` | ${s.audience || 'N/A'} |\n`;
+  }
+
+  return `${output}\n`;
+}
+
+export function formatCompactQuestions(questions: Question[]): string {
+  if (questions.length === 0) {
+    return 'No questions found.\n';
+  }
+
+  let output = '';
+  let index = 1;
+  for (const q of questions) {
+    const accepted = q.accepted_answer_id ? '✓' : ' ';
+    output += `${index}. [${q.title}](${q.link}) ${accepted} (score: ${q.score}, answers: ${q.answer_count})\n`;
+    index++;
+  }
+  return output;
+}