deepline 0.0.1 → 0.1.1

package/dist/repo/sdk/src/cli/commands/tools.ts

@@ -0,0 +1,687 @@
+import { Command } from 'commander';
+import { DeeplineClient } from '../../client.js';
+import { DeeplineError } from '../../errors.js';
+import type { PlayDescription, PlayListItem, ToolDefinition } from '../../types.js';
+import {
+  extractSummaryFields,
+  tryConvertToList,
+  writeCsvOutputFile,
+  writeJsonOutputFile,
+} from '../../tool-output.js';
+import { argsWantJson, printJsonError, shouldEmitJson } from '../utils.js';
+
+type OutputFormat = 'auto' | 'csv' | 'csv_file' | 'json' | 'json_file';
+type ToolInputField = {
+  name?: unknown;
+  type?: unknown;
+  required?: unknown;
+  description?: unknown;
+  default?: unknown;
+};
+type CliToolMetadata = ToolDefinition & Record<string, unknown>;
+
+type ListedTool = ToolDefinition & {
+  id: string;
+  type: 'tool';
+  callCommand: string;
+};
+
+function toListedTool(tool: ToolDefinition): ListedTool {
+  return {
+    ...tool,
+    id: tool.toolId,
+    type: 'tool',
+    callCommand: `deepline tools call ${tool.toolId}`,
+  };
+}
+
+async function listTools(args: string[]): Promise<number> {
+  const client = new DeeplineClient();
+  const items = (await client.listTools()).map(toListedTool);
+
+  if (argsWantJson(args)) {
+    process.stdout.write(`${JSON.stringify(items)}\n`);
+    return 0;
+  }
+
+  console.log(`${items.length} tools available:\n`);
+  for (const item of items) {
+    const cats = item.categories.length ? ` [${item.categories.join(', ')}]` : '';
+    const listHint = item.listExtractorPaths?.length
+      ? ` listExtractorPaths=${item.listExtractorPaths.join(',')}`
+      : '';
+    console.log(`  ${item.toolId}${cats}`);
+    console.log(`    ${item.description}${listHint}`);
+  }
+  return 0;
+}
+
+function toolMatchesQuery(tool: ToolDefinition, terms: string[]): boolean {
+  const haystack = [
+    tool.toolId,
+    tool.provider,
+    tool.displayName,
+    tool.description,
+    tool.operation,
+    tool.operationId,
+    ...(tool.operationAliases ?? []),
+    ...(tool.categories ?? []),
+    tool.inputSchema ? JSON.stringify(tool.inputSchema) : '',
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+  return terms.every((term) => haystack.includes(term));
+}
+
+async function searchTools(args: string[]): Promise<number> {
+  const query = args[0]?.trim();
+  if (!query) {
+    console.error('Usage: deepline tools search <query> [--json]');
+    return 1;
+  }
+
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const client = new DeeplineClient();
+  const items = (await client.listTools())
+    .filter((tool) => toolMatchesQuery(tool, terms))
+    .map(toListedTool);
+
+  if (argsWantJson(args)) {
+    process.stdout.write(`${JSON.stringify({ tools: items })}\n`);
+    return 0;
+  }
+
+  console.log(`${items.length} tools found:\n`);
+  for (const item of items) {
+    const cats = item.categories.length ? ` [${item.categories.join(', ')}]` : '';
+    console.log(`  ${item.toolId}${cats}`);
+    console.log(`    ${item.description}`);
+    if (item.inputSchema) {
+      console.log('    inputSchema: yes');
+    }
+  }
+  return 0;
+}
+
+function playIdentifiers(play: PlayListItem | PlayDescription): string[] {
+  return [play.name, play.reference, ...(play.aliases ?? [])]
+    .filter((value): value is string => Boolean(value?.trim()))
+    .map((value) => value.trim());
+}
+
+async function findPlayForToolId(
+  client: DeeplineClient,
+  toolId: string,
+): Promise<PlayDescription | null> {
+  const requested = toolId.trim();
+  if (!requested) {
+    return null;
+  }
+
+  const plays = await client.searchPlays({ query: requested, compact: true });
+  return (
+    plays.find((play) => playIdentifiers(play).includes(requested)) ?? null
+  );
+}
+
+function printPlayAliasToolError(toolId: string, play: PlayDescription): void {
+  const playName = play.reference ?? play.name;
+  console.error(
+    `${toolId} is a play, not a tool.\n` +
+      `Use: deepline plays run ${playName} --input '{...}' --watch\n` +
+      `Inspect its schema with: deepline plays describe ${playName} --json`,
+  );
+}
+
+export function registerToolsCommands(program: Command): void {
+  const tools = program
+    .command('tools')
+    .description('Search, describe, and call atomic provider tools.')
+    .addHelpText(
+      'after',
+      `
+Concepts:
+  Tools are atomic provider/API operations. Plays are workflows and must be run
+  through the plays namespace.
+
+Common commands:
+  deepline tools search email --json
+  deepline tools get hunter_email_verifier --json
+  deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
+`,
+    );
+
+  tools
+    .command('list')
+    .description('List available tools.')
+    .option('--json', 'Emit JSON output')
+    .action(async (options) => {
+      process.exitCode = await listTools([
+        ...(options.json ? ['--json'] : []),
+      ]);
+    });
+
+  tools
+    .command('search <query>')
+    .description('Search available tools.')
+    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
+    .action(async (query, options) => {
+      process.exitCode = await searchTools([
+        query,
+        ...(options.json ? ['--json'] : []),
+      ]);
+    });
+
+  tools
+    .command('get <toolId>')
+    .alias('describe')
+    .description('Show metadata for a tool.')
+    .addHelpText(
+      'after',
+      `
+Notes:
+  Shows the tool contract, input schema, output schema, costs, aliases, and metadata.
+
+Examples:
+  deepline tools get hunter_email_verifier
+  deepline tools get hunter_email_verifier --json | jq '.inputSchema'
+`,
+    )
+    .option('--json', 'Emit JSON output. Also automatic when stdout is piped')
+    .action(async (toolId, options) => {
+      process.exitCode = await getTool([
+        toolId,
+        ...(options.json ? ['--json'] : []),
+      ]);
+    });
+
+  tools
+    .command('call <toolId>')
+    .alias('execute')
+    .alias('run')
+    .description('Execute a tool by id.')
+    .addHelpText(
+      'after',
+      `
+Notes:
+  Use tools for one atomic provider/API operation. Use plays for composed workflows,
+  waterfalls, row maps, checkpoints, and retries.
+
+Examples:
+  deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline tools call hunter_email_verifier -p email=a@b.com
+  deepline tools call test_rate_limit --input '{"key":"smoke"}' --json | jq '.status'
+`,
+    )
+    .option('-p, --param <key=value>', 'Pass one parameter. Repeat for multiple values.', (value, acc: string[]) => {
+      acc.push(value);
+      return acc;
+    }, [])
+    .option('--json [payload]', 'Emit JSON output. Use `--input` or `--payload` for passing JSON params.')
+    .option('--input <payload>', 'Merge a JSON object into the tool params')
+    .option('--payload <payload>', 'Merge a JSON object into the tool params')
+    .option(
+      '--output-format <format>',
+      'Output format: auto, csv, csv_file, json, or json_file',
+    )
+    .option('--full-output', 'Emit the full JSON payload')
+    .option('--no-preview', 'Only print the extracted output path when applicable')
+    .action(async (toolId, options) => {
+      const args = [
+        toolId,
+        ...((options.param as string[]).flatMap((value) => ['--param', value])),
+        ...(options.json === true ? ['--json'] : []),
+        ...(typeof options.json === 'string' ? ['--json', options.json] : []),
+        ...(options.input ? ['--input', options.input] : []),
+        ...(options.payload ? ['--payload', options.payload] : []),
+        ...(options.outputFormat ? ['--output-format', options.outputFormat] : []),
+        ...(options.fullOutput ? ['--full-output'] : []),
+        ...(options.preview === false ? ['--no-preview'] : []),
+      ];
+      process.exitCode = await executeTool(args);
+    });
+}
+
+async function getTool(args: string[]): Promise<number> {
+  const toolId = args[0];
+  if (!toolId) {
+    console.error('Usage: deepline tools get <toolId> [--json]');
+    return 1;
+  }
+
+  const client = new DeeplineClient();
+  let tool: CliToolMetadata;
+  try {
+    tool = (await client.getTool(toolId)) as unknown as CliToolMetadata;
+  } catch (error) {
+    const play = await findPlayForToolId(client, toolId);
+    if (play) {
+      printPlayAliasToolError(toolId, play);
+      return 2;
+    }
+    throw error;
+  }
+
+  if (argsWantJson(args)) {
+    process.stdout.write(`${JSON.stringify(tool)}\n`);
+    return 0;
+  }
+
+  printToolDetails(tool as CliToolMetadata, toolId);
+  return 0;
+}
+
+function printToolDetails(tool: CliToolMetadata, requestedToolId: string): void {
+  const toolId = String(tool.toolId || requestedToolId);
+  const operation = typeof tool.operation === 'string' ? tool.operation : '';
+  const displayBase =
+    operation && operation.startsWith(`${tool.provider}_`)
+      ? operation.slice(String(tool.provider).length + 1)
+      : operation
+        ? `${tool.provider} ${operation}`.trim()
+        : toolId;
+  const displayName = titleCase(displayBase || String(tool.displayName || toolId));
+  const cost = isRecord(tool.cost) ? tool.cost : null;
+  const deeplineCredits = numberField(tool, 'deeplineCreditsPerPricingUnit', 'deepline_credits_per_pricing_unit');
+  const deeplineUsdPerPricingUnit = numberField(tool, 'deeplineUsdPerPricingUnit', 'deepline_usd_per_pricing_unit');
+  const deeplineUsdPerCredit = numberField(tool, 'deeplineUsdPerCredit', 'deepline_usd_per_credit');
+  const billingSource = stringField(tool, 'billingSource', 'billing_source');
+  const billingSourceLabel = stringField(tool, 'billingSourceLabel', 'billing_source_label');
+  const estimatedCreditsRange = stringField(tool, 'estimatedCreditsRange', 'estimated_credits_range');
+  const estimatedUsdRange = stringField(tool, 'estimatedUsdRange', 'estimated_usd_range');
+  const estimateModelVersion = stringField(tool, 'estimateModelVersion', 'estimate_model_version');
+  const estimateBasedOnTools = arrayField(tool, 'estimateBasedOnTools', 'estimate_based_on_tools')
+    .map((item) => String(item).trim())
+    .filter(Boolean);
+  const stepContributions = arrayField(tool, 'stepContributions', 'step_contributions');
+  const playExpansion = recordField(tool, 'playExpansion', 'play_expansion');
+  const samples = recordField(tool, 'samples');
+
+  console.log(`Tool: ${toolId}`);
+  if (displayName) {
+    console.log('  Display name:');
+    console.log(`    ${displayName}`);
+  }
+  if (tool.categories.length > 0) {
+    console.log('  Categories:');
+    console.log(`    ${tool.categories.join(', ')}`);
+  }
+
+  const printedCost = printToolCost({
+    cost,
+    billingSource,
+    deeplineCredits,
+    deeplineUsdPerPricingUnit,
+  });
+  if (!printedCost && ['run_javascript', 'call_local_codex', 'call_local_claude_code'].includes(toolId)) {
+    console.log('  Cost: free');
+  }
+  if (billingSourceLabel) {
+    console.log(`  Billing source: ${billingSourceLabel}`);
+  }
+  if (typeof deeplineUsdPerCredit === 'number') {
+    console.log(`  Deepline rate: $${deeplineUsdPerCredit.toFixed(2)} per credit`);
+  }
+
+  if (estimatedCreditsRange) {
+    const usdSuffix = estimatedUsdRange ? ` (~${estimatedUsdRange})` : '';
+    console.log(`  Estimated play spend: ${estimatedCreditsRange}${usdSuffix}`);
+    if (estimateModelVersion) console.log(`    model: ${estimateModelVersion}`);
+    if (estimateBasedOnTools.length) console.log(`    based on: ${estimateBasedOnTools.join(', ')}`);
+    if (stepContributions.length) {
+      console.log('    step contributions:');
+      for (const item of stepContributions) {
+        if (!isRecord(item)) continue;
+        const stepTool = typeof item.tool === 'string' ? item.tool.trim() : '';
+        const low = typeof item.lowCredits === 'number' ? item.lowCredits : null;
+        const high = typeof item.highCredits === 'number' ? item.highCredits : null;
+        const lowUsd = typeof item.lowUsd === 'number' ? item.lowUsd : null;
+        const highUsd = typeof item.highUsd === 'number' ? item.highUsd : null;
+        if (!stepTool || low === null || high === null) continue;
+        const stepUsdSuffix = lowUsd !== null && highUsd !== null ? ` (~${formatUsd(lowUsd)}-${formatUsd(highUsd)})` : '';
+        console.log(`      - ${stepTool}: ${formatDecimal(low)}-${formatDecimal(high)} credits${stepUsdSuffix}`);
+      }
+    }
+  }
+
+  if (playExpansion && Object.keys(playExpansion).length > 0) {
+    const group = typeof playExpansion.group === 'string' ? playExpansion.group.trim() : '';
+    console.log('  Play expansion:');
+    if (group) console.log(`    group: ${group}`);
+  }
+
+  const fields = toolInputFieldsForDisplay(recordField(tool, 'inputSchema', 'input_schema'));
+  if (fields.length) {
+    console.log('  Inputs (operation-specific):');
+    for (const field of fields) {
+      const name = String(field.name || '');
+      const typeName = String(field.type || 'unknown');
+      const requiredLabel = field.required ? 'required' : 'optional';
+      const defaultSuffix = Object.prototype.hasOwnProperty.call(field, 'default')
+        ? `, default: ${JSON.stringify(field.default)}`
+        : '';
+      const desc = typeof field.description === 'string' && field.description.trim() ? ` - ${field.description.trim()}` : '';
+      console.log(`    - ${name} (${typeName}, ${requiredLabel}${defaultSuffix})${desc}`);
+    }
+    console.log('  Tip: pass --payload with a JSON object.');
+  }
+
+  printSamples(samples);
+
+  if (isPlayTool(tool)) {
+    console.log('  Play contract:');
+    console.log('    - This is a deepline-native waterfall; the returned rows are extracted by target getters, not by hand-authored payload shape.');
+    if (playExpansion && typeof playExpansion.group === 'string' && playExpansion.group.trim()) {
+      console.log(`    - Output alias/runtime group is: ${playExpansion.group.trim()}`);
+    }
+    const getters = recordField(tool, 'resultIdentityGetters', 'result_identity_getters');
+    const targets = Object.keys(getters).filter(Boolean).sort();
+    if (targets.length) {
+      console.log(`    - Built-in extract targets: ${targets.join(', ')}`);
+    }
+  }
+
+  console.log('');
+  console.log('Usage:');
+  const requestPayload = samplePayload(samples, 'request');
+  if (isPlayTool(tool)) {
+    if (requestPayload !== undefined) {
+      console.log(`  deepline enrich --with '${JSON.stringify({ alias: 'result', tool: toolId, payload: requestPayload })}'`);
+    } else {
+      console.log(`  deepline enrich --with '{"alias":"result","tool":"${toolId}","payload":{...}}'`);
+    }
+  } else if (requestPayload !== undefined) {
+    console.log(`  deepline tools execute ${toolId} --payload '${JSON.stringify(requestPayload)}'`);
+  } else {
+    console.log(`  deepline tools execute ${toolId} --payload '{...}'`);
+  }
+  console.log('  deepline tools get <tool_id> --json  # full machine-readable output');
+}
+
+function printToolCost(input: {
+  cost: Record<string, unknown> | null;
+  billingSource: string;
+  deeplineCredits: number | null;
+  deeplineUsdPerPricingUnit: number | null;
+}): boolean {
+  const { cost, billingSource, deeplineCredits, deeplineUsdPerPricingUnit } = input;
+  if (!cost) return false;
+  const pricingModel = typeof cost.pricingModel === 'string' ? cost.pricingModel : typeof cost.pricing_model === 'string' ? cost.pricing_model : '';
+  const billingMode = typeof cost.billingMode === 'string' ? cost.billingMode : typeof cost.billing_mode === 'string' ? cost.billing_mode : '';
+  const providerPrice = typeof cost.providerPricePerPricingModel === 'number' ? cost.providerPricePerPricingModel : null;
+  if (pricingModel === 'fixed' && providerPrice === 0) {
+    console.log('  Cost: free');
+    return true;
+  }
+  if (billingSource === 'own_provider_credentials') {
+    console.log('  Cost: free through Deepline');
+    return true;
+  }
+  if (pricingModel && billingMode && deeplineCredits !== null) {
+    const unit = pricingModel === 'per_page' ? 'page' : pricingModel === 'per_result' ? 'result' : 'call';
+    const usdText = deeplineUsdPerPricingUnit !== null ? ` / ${formatUsd(deeplineUsdPerPricingUnit)}` : '';
+    console.log(`  Cost: ${formatDecimal(deeplineCredits)} Deepline credits${usdText} per ${unit} (${billingMode})`);
+    return true;
+  }
+  if (pricingModel && billingMode && providerPrice !== null) {
+    const unit = pricingModel === 'per_page' ? 'page' : pricingModel === 'per_result' ? 'result' : 'call';
+    console.log(`  Cost: ${formatDecimal(providerPrice)} provider credits per ${unit} (${billingMode})`);
+    return true;
+  }
+  return false;
+}
+
+function toolInputFieldsForDisplay(inputSchema: Record<string, unknown>): ToolInputField[] {
+  if (Array.isArray(inputSchema.fields)) return inputSchema.fields.filter(isRecord) as ToolInputField[];
+  const jsonSchema = isRecord(inputSchema.jsonSchema) ? inputSchema.jsonSchema : inputSchema;
+  const properties = isRecord(jsonSchema.properties) ? jsonSchema.properties : {};
+  const required = Array.isArray(jsonSchema.required) ? new Set(jsonSchema.required.map(String)) : new Set<string>();
+  return Object.entries(properties).map(([name, value]) => {
+    const property = isRecord(value) ? value : {};
+    return {
+      name,
+      type: typeof property.type === 'string' ? property.type : 'unknown',
+      required: required.has(name),
+      description: property.description,
+      ...(Object.prototype.hasOwnProperty.call(property, 'default') ? { default: property.default } : {}),
+    };
+  });
+}
+
+function printSamples(samples: Record<string, unknown>): void {
+  const requestPayload = samplePayload(samples, 'request');
+  const responsePayload = samplePayload(samples, 'response');
+  if (requestPayload === undefined && responsePayload === undefined) return;
+  console.log('  Samples:');
+  if (requestPayload !== undefined) printJsonPreview('Example payload', requestPayload);
+  if (responsePayload !== undefined) printJsonPreview('Example response', responsePayload);
+}
+
+function printJsonPreview(label: string, payload: unknown): void {
+  console.log(`  ${label}:`);
+  const rendered = JSON.stringify(payload, null, 2);
+  for (const line of rendered.split('\n')) {
+    console.log(`    ${line}`);
+  }
+}
+
+function samplePayload(samples: Record<string, unknown>, key: 'request' | 'response'): unknown {
+  const entry = samples[key];
+  if (!isRecord(entry)) return undefined;
+  return Object.prototype.hasOwnProperty.call(entry, 'payload') ? entry.payload : entry;
+}
+
+function isPlayTool(tool: Record<string, unknown>): boolean {
+  const provider = typeof tool.provider === 'string' ? tool.provider : '';
+  return provider === 'deepline_native' && Boolean(recordField(tool, 'playExpansion', 'play_expansion'));
+}
+
+function titleCase(value: string): string {
+  return value
+    .replace(/[_-]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map((part) => {
+      const lower = part.toLowerCase();
+      const special: Record<string, string> = { linkedin: 'LinkedIn', crm: 'CRM', api: 'API' };
+      return special[lower] ?? `${part[0]?.toUpperCase() ?? ''}${part.slice(1)}`;
+    })
+    .join(' ');
+}
+
+function formatDecimal(value: number): string {
+  const text = value.toFixed(12).replace(/0+$/, '').replace(/\.$/, '');
+  return text || '0';
+}
+
+function formatUsd(value: number): string {
+  return `$${formatDecimal(value)}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function stringField(source: Record<string, unknown>, ...keys: string[]): string {
+  for (const key of keys) {
+    const value = source[key];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return '';
+}
+
+function numberField(source: Record<string, unknown>, ...keys: string[]): number | null {
+  for (const key of keys) {
+    const value = source[key];
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+  }
+  return null;
+}
+
+function arrayField(source: Record<string, unknown>, ...keys: string[]): unknown[] {
+  for (const key of keys) {
+    const value = source[key];
+    if (Array.isArray(value)) return value;
+  }
+  return [];
+}
+
+function recordField(source: Record<string, unknown>, ...keys: string[]): Record<string, unknown> {
+  for (const key of keys) {
+    const value = source[key];
+    if (isRecord(value)) return value;
+  }
+  return {};
+}
+
+function normalizeOutputFormat(raw: string | null): OutputFormat {
+  switch ((raw || 'auto').trim().toLowerCase()) {
+    case 'auto':
+      return 'auto';
+    case 'csv':
+      return 'csv';
+    case 'csv_file':
+      return 'csv_file';
+    case 'json':
+      return 'json';
+    case 'json_file':
+      return 'json_file';
+    default:
+      throw new Error(`Invalid value for --output-format: ${raw}`);
+  }
+}
+
+function parseExecuteOptions(args: string[]) {
+  const toolId = args[0];
+  if (!toolId) {
+    throw new Error('Usage: deepline tools call <toolId> [--param key=value ...] [--input \'{"k":"v"}\'] [--output-format auto|csv|csv_file|json|json_file] [--full-output] [--no-preview]');
+  }
+
+  const params: Record<string, unknown> = {};
+  let outputFormat: OutputFormat = 'auto';
+  let noPreview = false;
+
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if ((arg === '--param' || arg === '-p') && args[index + 1]) {
+      const kv = args[++index]!;
+      const eqIdx = kv.indexOf('=');
+      if (eqIdx > 0) params[kv.slice(0, eqIdx)] = kv.slice(eqIdx + 1);
+      continue;
+    }
+    if (arg === '--json') {
+      const next = args[index + 1];
+      outputFormat = 'json';
+      if (next && !next.startsWith('--')) {
+        Object.assign(params, JSON.parse(args[++index]!));
+      }
+      continue;
+    }
+    if ((arg === '--input' || arg === '--payload') && args[index + 1]) {
+      Object.assign(params, JSON.parse(args[++index]!));
+      continue;
+    }
+    if (arg === '--output-format' && args[index + 1]) {
+      outputFormat = normalizeOutputFormat(args[++index]!);
+      continue;
+    }
+    if (arg === '--full-output') {
+      outputFormat = 'json';
+      continue;
+    }
+    if (arg === '--no-preview') {
+      noPreview = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return { toolId, params, outputFormat, noPreview };
+}
+
+async function executeTool(args: string[]): Promise<number> {
+  let parsed: ReturnType<typeof parseExecuteOptions>;
+  try {
+    parsed = parseExecuteOptions(args);
+  } catch (error) {
+    if (argsWantJson(args)) {
+      printJsonError(error);
+    } else {
+      console.error(error instanceof Error ? error.message : String(error));
+    }
+    return 1;
+  }
+
+  const client = new DeeplineClient();
+  let metadata: Awaited<ReturnType<DeeplineClient['getTool']>>;
+  try {
+    metadata = await client.getTool(parsed.toolId);
+  } catch (error) {
+    const play = await findPlayForToolId(client, parsed.toolId);
+    if (play) {
+      printPlayAliasToolError(parsed.toolId, play);
+      return 2;
+    }
+    if (error instanceof DeeplineError) {
+      throw error;
+    }
+    throw error;
+  }
+  const rawResponse = await client.executeToolRaw(parsed.toolId, parsed.params);
+
+  const listConversion = tryConvertToList(rawResponse, {
+    listExtractorPaths: metadata.listExtractorPaths ?? [],
+  });
+  const summary = extractSummaryFields(rawResponse);
+
+  if (parsed.outputFormat === 'json' || (parsed.outputFormat === 'auto' && shouldEmitJson())) {
+    process.stdout.write(`${JSON.stringify(rawResponse, null, 2)}\n`);
+    return 0;
+  }
+
+  if (parsed.outputFormat === 'json_file') {
+    const jsonPath = writeJsonOutputFile(rawResponse, `payload_${parsed.toolId}`);
+    console.log(jsonPath);
+    return 0;
+  }
+
+  if (!listConversion) {
+    if (parsed.outputFormat === 'csv' || parsed.outputFormat === 'csv_file') {
+      const jsonPath = writeJsonOutputFile(rawResponse, `payload_${parsed.toolId}`);
+      console.log(jsonPath);
+      return 0;
+    }
+    process.stdout.write(`${JSON.stringify(rawResponse, null, 2)}\n`);
+    return 0;
+  }
+
+  const csv = writeCsvOutputFile(listConversion.rows, `${parsed.toolId}_output`);
+  if (parsed.outputFormat === 'csv_file') {
+    process.stdout.write(`${JSON.stringify({
+      extracted_csv: csv.path,
+      extracted_csv_rows: csv.rowCount,
+      extracted_csv_columns: csv.columns,
+      preview: csv.preview,
+      list_strategy: listConversion.strategy,
+      list_source_path: listConversion.sourcePath,
+      summary,
+    })}\n`);
+    return 0;
+  }
+
+  if (parsed.noPreview) {
+    console.log(csv.path);
+    return 0;
+  }
+
+  console.log(`${csv.path} (${csv.rowCount} rows)`);
+  if (csv.columns.length > 0) {
+    console.log(`columns: ${JSON.stringify(csv.columns)}`);
+  }
+  if (Object.keys(summary).length > 0) {
+    console.log(`summary: ${Object.entries(summary).map(([key, value]) => `${key}=${String(value)}`).join(', ')}`);
+  }
+  console.log(`preview: ${JSON.stringify(csv.preview)}`);
+  return 0;
+}