coaiajs 0.1.0

package/src/langfuse/datasets.ts

@@ -0,0 +1,178 @@
+// coaiajs/src/langfuse/datasets.ts — Dataset operations
+// Port of cofuse.py dataset functions
+
+import { getClient } from './client.js';
+
+export async function listDatasets(): Promise<string> {
+  const client = getClient();
+  const result = await client.request<unknown>('GET', '/api/public/v2/datasets');
+  return JSON.stringify(result, null, 2);
+}
+
+export async function getDataset(name: string): Promise<string> {
+  const client = getClient();
+  const result = await client.request<unknown>(
+    'GET',
+    `/api/public/v2/datasets/${encodeURIComponent(name)}`,
+  );
+  return JSON.stringify(result, null, 2);
+}
+
+export async function createDataset(params: {
+  name: string;
+  description?: string;
+  metadata?: unknown;
+}): Promise<string> {
+  const client = getClient();
+  const data: Record<string, unknown> = { name: params.name };
+
+  if (params.description) data.description = params.description;
+  if (params.metadata) {
+    data.metadata = typeof params.metadata === 'string'
+      ? safeParseJSON(params.metadata)
+      : params.metadata;
+  }
+
+  const result = await client.request<unknown>('POST', '/api/public/v2/datasets', data);
+  return JSON.stringify(result, null, 2);
+}
+
+export async function listDatasetItems(name: string): Promise<string> {
+  const client = getClient();
+  const allItems: unknown[] = [];
+  let page = 1;
+
+  while (true) {
+    const data = await client.request<Record<string, unknown>>(
+      'GET',
+      `/api/public/dataset-items?name=${encodeURIComponent(name)}&page=${page}`,
+    );
+
+    const items = (data as Record<string, unknown>).data;
+    if (!items || !Array.isArray(items) || items.length === 0) break;
+    allItems.push(...items);
+
+    const meta = (data as Record<string, unknown>).meta as Record<string, unknown> | undefined;
+    if (!meta || (meta.page as number ?? page) >= (meta.totalPages as number ?? 1)) break;
+    page++;
+  }
+
+  return JSON.stringify(allItems, null, 2);
+}
+
+export async function createDatasetItem(params: {
+  datasetName: string;
+  input: unknown;
+  expectedOutput?: unknown;
+  metadata?: unknown;
+  sourceTraceId?: string;
+  sourceObservationId?: string;
+}): Promise<string> {
+  const client = getClient();
+  const data: Record<string, unknown> = {
+    datasetName: params.datasetName,
+    input: params.input,
+  };
+
+  if (params.expectedOutput !== undefined) data.expectedOutput = params.expectedOutput;
+  if (params.metadata) data.metadata = params.metadata;
+  if (params.sourceTraceId) data.sourceTraceId = params.sourceTraceId;
+  if (params.sourceObservationId) data.sourceObservationId = params.sourceObservationId;
+
+  const result = await client.request<unknown>('POST', '/api/public/dataset-items', data);
+  return JSON.stringify(result, null, 2);
+}
+
+// ─── Formatters ─────────────────────────────────────────────────────
+
+export function formatDatasetsTable(json: unknown): string {
+  try {
+    const raw = typeof json === 'string' ? JSON.parse(json) : json;
+    const datasets: Record<string, unknown>[] = Array.isArray(raw)
+      ? raw
+      : (raw as Record<string, unknown>).data as Record<string, unknown>[] ?? [];
+
+    if (!datasets.length) return 'No datasets found.';
+
+    const headers = ['Name', 'Description', 'Items', 'Created'];
+    const rows = datasets.map((d) => [
+      trunc(String(d.name ?? 'N/A'), 25),
+      trunc(String(d.description ?? 'N/A'), 30),
+      String(d.items?.toString() ?? 'N/A'),
+      String(d.createdAt ?? 'N/A').slice(0, 10),
+    ]);
+
+    return formatTable(headers, rows) + `\nTotal datasets: ${datasets.length}`;
+  } catch (e) {
+    return `Error formatting datasets: ${e}`;
+  }
+}
+
+export function formatDatasetForFinetuning(
+  items: unknown,
+  format: 'openai' | 'gemini',
+  systemInstruction?: string,
+): string {
+  try {
+    const parsed = (typeof items === 'string' ? JSON.parse(items) : items) as Record<string, unknown>[];
+    const sysInstr = systemInstruction ?? 'You are a helpful assistant.';
+    const lines: string[] = [];
+
+    for (const item of parsed) {
+      const input = item.input;
+      const output = item.expectedOutput;
+      if (!input || !output) continue;
+
+      if (format === 'openai') {
+        lines.push(JSON.stringify({
+          messages: [
+            { role: 'system', content: sysInstr },
+            { role: 'user', content: input },
+            { role: 'assistant', content: output },
+          ],
+        }));
+      } else {
+        lines.push(JSON.stringify({
+          systemInstruction: {
+            role: 'system',
+            parts: [{ text: sysInstr }],
+          },
+          contents: [
+            { role: 'user', parts: [{ text: input }] },
+            { role: 'model', parts: [{ text: output }] },
+          ],
+        }));
+      }
+    }
+
+    return lines.join('\n');
+  } catch (e) {
+    return `Error formatting for fine-tuning: ${e}`;
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function trunc(s: string, len: number): string {
+  return s.length > len ? s.slice(0, len - 3) + '...' : s;
+}
+
+function safeParseJSON(s: string): unknown {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return { note: s };
+  }
+}
+
+function formatTable(headers: string[], rows: string[][]): string {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)),
+  );
+  const sep = '+' + widths.map((w) => '-'.repeat(w + 2)).join('+') + '+';
+  const hdr = '| ' + headers.map((h, i) => h.padEnd(widths[i])).join(' | ') + ' |';
+  const body = rows.map(
+    (r) => '| ' + r.map((c, i) => (c ?? '').padEnd(widths[i])).join(' | ') + ' |',
+  );
+  return [sep, hdr, sep, ...body, sep].join('\n');
+}

package/src/langfuse/index.ts

@@ -0,0 +1,33 @@
+// coaiajs/src/langfuse/index.ts — Barrel export
+
+export { LangfuseClient, LangfuseApiError, getClient, resetClient, nowISO } from './client.js';
+export type { IngestionEvent, LangfuseClientConfig } from './client.js';
+
+export { addTrace, patchTraceOutput, listTraces, getTrace, formatTracesTable, formatTraceTree } from './traces.js';
+export type { TraceFilters } from './traces.js';
+
+export { addObservation, getObservation, formatObservationDisplay } from './observations.js';
+
+export { listPrompts, getPrompt, createPrompt, formatPromptsTable, formatPromptDisplay } from './prompts.js';
+
+export {
+  listDatasets, getDataset, createDataset, listDatasetItems, createDatasetItem,
+  formatDatasetsTable, formatDatasetForFinetuning,
+} from './datasets.js';
+
+export {
+  createScore, applyScoreToTrace, createScoreForTarget, listScores,
+  listScoreConfigs, getScoreConfig, createScoreConfig,
+  exportScoreConfigs, importScoreConfigs,
+  applyScoreConfig,
+  getBuiltInPresets, installPreset,
+  formatScoresTable, formatScoreConfigsTable,
+} from './scores.js';
+export type { ScoreFilters } from './scores.js';
+
+export { listComments, getComment, createComment } from './comments.js';
+export type { CommentFilters } from './comments.js';
+
+export {
+  uploadAndAttachMedia, getMedia, detectContentType, formatMediaDisplay,
+} from './media.js';

package/src/langfuse/media.ts

@@ -0,0 +1,193 @@
+// coaiajs/src/langfuse/media.ts — Media upload operations
+// Port of cofuse.py media functions
+
+import { readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, extname } from 'node:path';
+import { getClient } from './client.js';
+
+const SUPPORTED_CONTENT_TYPES = new Set([
+  'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml',
+  'image/tiff', 'image/bmp', 'image/avif',
+  'audio/mpeg', 'audio/mp4', 'audio/wav', 'audio/ogg', 'audio/webm', 'audio/flac',
+  'video/mp4', 'video/webm', 'video/ogg', 'video/quicktime',
+  'application/pdf',
+  'text/plain', 'text/html', 'text/css', 'text/csv',
+  'application/json', 'application/xml',
+]);
+
+const EXTENSION_MAP: Record<string, string> = {
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
+  '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+  '.tiff': 'image/tiff', '.tif': 'image/tiff', '.bmp': 'image/bmp',
+  '.avif': 'image/avif',
+  '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4', '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg', '.flac': 'audio/flac', '.weba': 'audio/webm',
+  '.mp4': 'video/mp4', '.webm': 'video/webm', '.ogv': 'video/ogg',
+  '.mov': 'video/quicktime',
+  '.pdf': 'application/pdf',
+  '.txt': 'text/plain', '.html': 'text/html', '.htm': 'text/html',
+  '.css': 'text/css', '.csv': 'text/csv',
+  '.json': 'application/json', '.xml': 'application/xml',
+};
+
+const TRUSTED_DOMAINS = [
+  'amazonaws.com',
+  's3.amazonaws.com',
+  'storage.googleapis.com',
+  'blob.core.windows.net',
+  'r2.cloudflarestorage.com',
+];
+
+export async function uploadAndAttachMedia(params: {
+  filePath: string;
+  traceId: string;
+  field?: string;
+  observationId?: string;
+  contentType?: string;
+}): Promise<string> {
+  const { filePath, traceId, observationId } = params;
+  const field = params.field ?? 'input';
+
+  // Detect content type
+  const contentType = params.contentType ?? detectContentType(filePath);
+  if (!SUPPORTED_CONTENT_TYPES.has(contentType)) {
+    return JSON.stringify({ error: `Unsupported content type: ${contentType}` });
+  }
+
+  // Calculate file info
+  const stat = statSync(filePath);
+  const fileData = readFileSync(filePath);
+  const sha256 = createHash('sha256').update(fileData).digest('base64');
+
+  const client = getClient();
+
+  // Step 1: Get presigned upload URL
+  const uploadReqData: Record<string, unknown> = {
+    traceId,
+    contentType,
+    contentLength: stat.size,
+    sha256Hash: sha256,
+    field,
+  };
+  if (observationId) uploadReqData.observationId = observationId;
+
+  const uploadInfo = await client.request<Record<string, unknown>>(
+    'POST',
+    '/api/public/media',
+    uploadReqData,
+  );
+
+  const uploadUrl = uploadInfo.uploadUrl as string;
+  const mediaId = uploadInfo.mediaId as string;
+
+  if (!uploadUrl || !mediaId) {
+    return JSON.stringify({ error: 'Failed to get upload URL', detail: uploadInfo });
+  }
+
+  // Step 2: Validate upload URL domain
+  const url = new URL(uploadUrl);
+  if (!isTrustedDomain(url.hostname)) {
+    return JSON.stringify({
+      error: `Security: Upload URL domain '${url.hostname}' is not trusted`,
+    });
+  }
+
+  // Step 3: Upload to presigned URL
+  const startTime = Date.now();
+  const uploadResponse = await fetch(uploadUrl, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': contentType,
+      'x-amz-checksum-sha256': sha256,
+    },
+    body: fileData,
+  });
+  const uploadTimeMs = Date.now() - startTime;
+
+  // Step 4: Patch status
+  await client.request('PATCH', `/api/public/media/${mediaId}`, {
+    uploadHttpStatus: uploadResponse.status,
+    uploadTimeMs,
+    uploadedAt: new Date().toISOString(),
+  });
+
+  if (!uploadResponse.ok) {
+    return JSON.stringify({
+      error: `Upload failed: ${uploadResponse.status}`,
+      mediaId,
+    });
+  }
+
+  // Build media token
+  const token = `@@@langfuseMedia:type=${contentType}|id=${mediaId}|source=file@@@`;
+
+  return JSON.stringify({
+    success: true,
+    mediaId,
+    fileName: basename(filePath),
+    contentType,
+    contentLength: stat.size,
+    traceId,
+    field,
+    observationId: observationId ?? null,
+    uploadTimeMs,
+    mediaToken: token,
+  }, null, 2);
+}
+
+export async function getMedia(mediaId: string): Promise<string> {
+  const client = getClient();
+  const result = await client.request<unknown>('GET', `/api/public/media/${mediaId}`);
+  return JSON.stringify(result, null, 2);
+}
+
+export function detectContentType(filePath: string): string {
+  const ext = extname(filePath).toLowerCase();
+  return EXTENSION_MAP[ext] ?? 'application/octet-stream';
+}
+
+export function formatMediaDisplay(json: unknown): string {
+  try {
+    const media = (typeof json === 'string' ? JSON.parse(json) : json) as Record<string, unknown>;
+    if ('error' in media) return `Error: ${media.error}`;
+
+    const contentType = String(media.contentType ?? 'unknown');
+    let glyph = '📎';
+    if (contentType.startsWith('image/')) glyph = '🖼️';
+    else if (contentType.startsWith('video/')) glyph = '🎥';
+    else if (contentType.startsWith('audio/')) glyph = '🎵';
+    else if (contentType === 'application/pdf') glyph = '📄';
+
+    const lines: string[] = [];
+    lines.push(`${glyph} Media: ${media.fileName ?? 'Unnamed'}`);
+    lines.push(`├── 🆔 ID: ${media.id ?? media.mediaId ?? 'N/A'}`);
+    lines.push(`├── 📝 Content Type: ${contentType}`);
+    lines.push(`├── 📏 Size: ${media.contentLength ?? 0} bytes`);
+    lines.push(`├── 🔗 Trace ID: ${media.traceId ?? 'N/A'}`);
+
+    if (media.observationId) lines.push(`├── 👁️ Observation ID: ${media.observationId}`);
+    if (media.field) lines.push(`├── 🏷️ Field: ${media.field}`);
+    if (media.uploadedAt) lines.push(`├── ⏰ Uploaded: ${String(media.uploadedAt).slice(0, 19)}`);
+
+    // Fix last line to └──
+    if (lines.length > 1) {
+      const last = lines[lines.length - 1];
+      lines[lines.length - 1] = last.replace('├── ', '└── ');
+    }
+
+    return lines.join('\n');
+  } catch (e) {
+    return `Error formatting media: ${e}`;
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function isTrustedDomain(hostname: string): boolean {
+  const lower = hostname.toLowerCase();
+  for (const domain of TRUSTED_DOMAINS) {
+    if (lower === domain || lower.endsWith(`.${domain}`)) return true;
+  }
+  return false;
+}

package/src/langfuse/observations.ts

@@ -0,0 +1,131 @@
+// coaiajs/src/langfuse/observations.ts — Observation operations
+// Port of cofuse.py observation functions
+
+import { v4 as uuidv4 } from 'uuid';
+import { getClient, nowISO } from './client.js';
+import type { IngestionEvent } from './client.js';
+
+export async function addObservation(params: {
+  observationId?: string;
+  traceId: string;
+  type?: string;
+  name: string;
+  parentId?: string;
+  inputData?: unknown;
+  outputData?: unknown;
+  metadata?: unknown;
+  startTime?: string;
+  endTime?: string;
+  level?: string;
+  model?: string;
+  usage?: unknown;
+}): Promise<string> {
+  const client = getClient();
+  const now = nowISO();
+  const obsId = params.observationId ?? uuidv4();
+
+  const body: Record<string, unknown> = {
+    id: obsId,
+    traceId: params.traceId,
+    type: params.type ?? 'EVENT',
+    startTime: params.startTime ?? now,
+    level: params.level ?? 'DEFAULT',
+  };
+
+  if (params.name) body.name = params.name;
+  if (params.inputData) body.input = params.inputData;
+  if (params.outputData) body.output = params.outputData;
+  if (params.metadata) body.metadata = params.metadata;
+  if (params.parentId) body.parentObservationId = params.parentId;
+  if (params.endTime) body.endTime = params.endTime;
+  if (params.model) body.model = params.model;
+  if (params.usage) body.usage = params.usage;
+
+  const event: IngestionEvent = {
+    id: `${obsId}-event`,
+    timestamp: now,
+    type: 'observation-create',
+    body,
+  };
+
+  await client.ingest([event]);
+
+  return JSON.stringify({
+    success: true,
+    observationId: obsId,
+    traceId: params.traceId,
+    name: params.name,
+    type: params.type ?? 'EVENT',
+  }, null, 2);
+}
+
+export async function getObservation(observationId: string): Promise<string> {
+  const client = getClient();
+  const result = await client.request<unknown>('GET', `/api/public/observations/${observationId}`);
+  return JSON.stringify(result, null, 2);
+}
+
+// ─── Formatters ─────────────────────────────────────────────────────
+
+const TYPE_GLYPHS: Record<string, string> = {
+  SPAN: '🔗',
+  GENERATION: '🤖',
+  EVENT: '⚡',
+  DEFAULT: '📦',
+};
+
+export function formatObservationDisplay(json: unknown): string {
+  try {
+    const obs = (typeof json === 'string' ? JSON.parse(json) : json) as Record<string, unknown>;
+    if ('error' in obs) return `Error: ${obs.error}`;
+
+    const obsType = String(obs.type ?? 'UNKNOWN').toUpperCase();
+    const glyph = TYPE_GLYPHS[obsType] ?? TYPE_GLYPHS.DEFAULT;
+
+    const lines: string[] = [];
+    lines.push(`${glyph} Observation: ${obs.name ?? 'Unnamed'}`);
+    lines.push(`├── 🆔 ID: ${obs.id ?? 'N/A'}`);
+    lines.push(`├── 📋 Type: ${obsType}`);
+    lines.push(`├── 🔗 Trace: ${obs.traceId ?? 'N/A'}`);
+    lines.push(`├── ⏰ Start: ${String(obs.startTime ?? 'N/A').slice(0, 19)}`);
+
+    if (obs.endTime) lines.push(`├── ⏰ End: ${String(obs.endTime).slice(0, 19)}`);
+    if (obs.level && obs.level !== 'DEFAULT') lines.push(`├── 📊 Level: ${obs.level}`);
+    if (obs.model) lines.push(`├── 🤖 Model: ${obs.model}`);
+
+    if (obs.parentObservationId) {
+      lines.push(`├── 👆 Parent: ${obs.parentObservationId}`);
+    }
+
+    if (obs.input) {
+      const txt = String(obs.input).replace(/\n/g, ' ');
+      lines.push(`├── 📥 Input: ${txt.length > 100 ? txt.slice(0, 100) + '...' : txt}`);
+    }
+    if (obs.output) {
+      const txt = String(obs.output).replace(/\n/g, ' ');
+      lines.push(`├── 📤 Output: ${txt.length > 100 ? txt.slice(0, 100) + '...' : txt}`);
+    }
+
+    const metadata = obs.metadata as Record<string, unknown> | undefined;
+    if (metadata && typeof metadata === 'object' && Object.keys(metadata).length) {
+      lines.push(`└── 📋 Metadata:`);
+      const entries = Object.entries(metadata);
+      entries.forEach(([k, v], i) => {
+        const pre = i === entries.length - 1 ? '└── ' : '├── ';
+        lines.push(`    ${pre}${k}: ${JSON.stringify(v)}`);
+      });
+    } else {
+      // Fix last ├── to └──
+      if (lines.length > 0) {
+        const last = lines[lines.length - 1];
+        if (last.startsWith('├── ')) {
+          lines[lines.length - 1] = last.replace('├── ', '└── ');
+        }
+      }
+    }
+
+    return lines.join('\n');
+  } catch (e) {
+    return `Error formatting observation: ${e}`;
+  }
+}

package/src/langfuse/prompts.ts

@@ -0,0 +1,157 @@
+// coaiajs/src/langfuse/prompts.ts — Prompt operations
+// Port of cofuse.py prompt functions
+
+import { getClient } from './client.js';
+
+export async function listPrompts(): Promise<string> {
+  const client = getClient();
+  const allPrompts: unknown[] = [];
+  let page = 1;
+
+  while (true) {
+    const data = await client.request<Record<string, unknown>>(
+      'GET',
+      `/api/public/v2/prompts?page=${page}`,
+    );
+
+    const prompts = (data as Record<string, unknown>).data;
+    if (!prompts || !Array.isArray(prompts) || prompts.length === 0) break;
+    allPrompts.push(...prompts);
+
+    const meta = (data as Record<string, unknown>).meta as Record<string, unknown> | undefined;
+    if (meta?.totalPages && (meta.page as number ?? page) >= (meta.totalPages as number)) break;
+    if (!(data as Record<string, unknown>).hasNextPage && !meta?.totalPages) break;
+    page++;
+  }
+
+  return JSON.stringify(allPrompts, null, 2);
+}
+
+export async function getPrompt(name: string, label?: string): Promise<string> {
+  const client = getClient();
+  const params = label ? `?label=${encodeURIComponent(label)}` : '';
+  const result = await client.request<unknown>(
+    'GET',
+    `/api/public/v2/prompts/${encodeURIComponent(name)}${params}`,
+  );
+  return JSON.stringify(result, null, 2);
+}
+
+export async function createPrompt(params: {
+  name: string;
+  content: string | unknown[];
+  commitMessage?: string;
+  labels?: string[];
+  tags?: string[];
+  promptType?: 'text' | 'chat';
+  config?: Record<string, unknown>;
+}): Promise<string> {
+  const client = getClient();
+
+  const data: Record<string, unknown> = {
+    type: params.promptType ?? 'text',
+    name: params.name,
+    prompt: params.content,
+  };
+
+  if (params.commitMessage) data.commitMessage = params.commitMessage;
+  if (params.labels) data.labels = params.labels;
+  if (params.tags) data.tags = params.tags;
+  if (params.config) data.config = params.config;
+
+  const result = await client.request<unknown>('POST', '/api/public/v2/prompts', data);
+  return JSON.stringify(result, null, 2);
+}
+
+// ─── Formatters ─────────────────────────────────────────────────────
+
+export function formatPromptsTable(json: unknown): string {
+  try {
+    const raw = typeof json === 'string' ? JSON.parse(json) : json;
+    const prompts: Record<string, unknown>[] = Array.isArray(raw)
+      ? raw
+      : (raw as Record<string, unknown>).data as Record<string, unknown>[] ?? [];
+
+    if (!prompts.length) return 'No prompts found.';
+
+    const headers = ['Name', 'Version', 'Created', 'Tags/Labels'];
+    const rows = prompts.map((p) => [
+      trunc(String(p.name ?? 'N/A'), 30),
+      String(p.version ?? 'N/A'),
+      String(p.createdAt ?? 'N/A').slice(0, 10),
+      ((p.labels as string[]) ?? []).join(', ') || 'None',
+    ]);
+
+    return formatTable(headers, rows) + `\nTotal prompts: ${prompts.length}`;
+  } catch (e) {
+    return `Error formatting prompts: ${e}`;
+  }
+}
+
+export function formatPromptDisplay(json: unknown): string {
+  try {
+    const prompt = (typeof json === 'string' ? JSON.parse(json) : json) as Record<string, unknown>;
+    if ('error' in prompt) return `Error: ${prompt.error}`;
+
+    const name = String(prompt.name ?? 'Unnamed');
+    const version = String(prompt.version ?? 'N/A');
+    const type = String(prompt.type ?? 'text');
+    const isActive = Boolean(prompt.isActive);
+    const created = String(prompt.createdAt ?? 'N/A').slice(0, 19);
+    const updated = String(prompt.updatedAt ?? 'N/A').slice(0, 19);
+    const labels = (prompt.labels as string[]) ?? [];
+    const tags = (prompt.tags as string[]) ?? [];
+    const commitMsg = String(prompt.commitMessage ?? '');
+    const config = prompt.config as Record<string, unknown> | undefined;
+    const content = String(prompt.prompt ?? '');
+
+    const header = `🎯 PROMPT: ${name}${version !== 'N/A' ? ` (v${version})` : ''}`;
+    const sep = '='.repeat(header.length);
+
+    const lines = [sep, header, sep, ''];
+    lines.push('📋 METADATA:');
+    lines.push(`   Type: ${type}`);
+    lines.push(`   Active: ${isActive ? '✅ Yes' : '❌ No'}`);
+    lines.push(`   Created: ${created}`);
+    lines.push(`   Updated: ${updated}`);
+    lines.push(`   Labels: ${labels.length ? labels.join(', ') : 'None'}`);
+    if (tags.length) lines.push(`   Tags: ${tags.join(', ')}`);
+    if (commitMsg) lines.push(`   Commit: ${commitMsg}`);
+    lines.push('');
+
+    if (config && Object.keys(config).length) {
+      lines.push('⚙️ CONFIGURATION:');
+      for (const [k, v] of Object.entries(config)) {
+        lines.push(`   ${k}: ${v}`);
+      }
+      lines.push('');
+    }
+
+    lines.push('📝 PROMPT CONTENT:');
+    lines.push('-'.repeat(50));
+    lines.push(content || '(No content)');
+    lines.push('-'.repeat(50));
+
+    return lines.join('\n');
+  } catch (e) {
+    return `Error formatting prompt: ${e}`;
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function trunc(s: string, len: number): string {
+  return s.length > len ? s.slice(0, len - 3) + '...' : s;
+}
+
+function formatTable(headers: string[], rows: string[][]): string {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)),
+  );
+  const sep = '+' + widths.map((w) => '-'.repeat(w + 2)).join('+') + '+';
+  const hdr = '| ' + headers.map((h, i) => h.padEnd(widths[i])).join(' | ') + ' |';
+  const body = rows.map(
+    (r) => '| ' + r.map((c, i) => (c ?? '').padEnd(widths[i])).join(' | ') + ' |',
+  );
+  return [sep, hdr, sep, ...body, sep].join('\n');
+}