@respan/cli 0.9.0 → 0.11.0

package/dist/commands/setup/tracing.d.ts

@@ -0,0 +1,16 @@
+import { SetupBaseCommand } from '../../lib/setup-base-command.js';
+export default class SetupTracing extends SetupBaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        agent: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'no-instrument': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        csv: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/setup/tracing.js

@@ -0,0 +1,33 @@
+import { Flags } from '@oclif/core';
+import { SetupBaseCommand } from '../../lib/setup-base-command.js';
+class SetupTracing extends SetupBaseCommand {
+    async run() {
+        const { flags } = await this.parse(SetupTracing);
+        this.globalFlags = flags;
+        await this.runSetup('tracing', {
+            agent: flags.agent,
+            noInstrument: flags['no-instrument'],
+        });
+    }
+}
+SetupTracing.description = `Set up Respan SDK tracing in this project.
+
+Runs the tracing setup flow directly (skips the "Tracing or Gateway?"
+question). Sets up your API key, installs the Respan skill, and optionally
+opens your coding agent to instrument the project.`;
+SetupTracing.examples = [
+    'respan setup tracing',
+    'respan setup tracing --agent claude-code',
+    'respan setup tracing --no-instrument',
+];
+SetupTracing.flags = {
+    ...SetupBaseCommand.baseFlags,
+    agent: Flags.string({
+        description: 'Agent to configure (claude-code, cursor, codex-cli, gemini-cli, opencode)',
+    }),
+    'no-instrument': Flags.boolean({
+        description: 'Skip opening the agent after setup',
+        default: false,
+    }),
+};
+export default SetupTracing;

package/dist/commands/traces/get.js

@@ -6,7 +6,7 @@ class TracesGet extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const data = await this.spin('Fetching trace', () => client.traces.retrieveTrace({ trace_unique_id: args.id }));
+            const data = await this.spin('Fetching trace', () => client.traces.retrieveTrace({ Authorization: this.getAuthHeader(), trace_unique_id: args.id }));
             this.log(JSON.stringify(data, null, 2));
         }
         catch (error) {

package/dist/commands/traces/list.js

@@ -8,22 +8,20 @@ class TracesList extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            let bodyFilters = {};
+            let bodyFilters;
             if (flags.filter && flags.filter.length > 0) {
                 bodyFilters = parseFilters(flags.filter);
             }
-            const queryParams = {
+            const data = await this.spin('Fetching traces', () => client.traces.listTraces({
+                Authorization: this.getAuthHeader(),
                 page_size: flags.limit,
                 page: flags.page,
                 sort_by: flags['sort-by'],
-            };
-            if (flags['start-time'])
-                queryParams.start_time = flags['start-time'];
-            if (flags['end-time'])
-                queryParams.end_time = flags['end-time'];
-            if (flags.environment)
-                queryParams.environment = flags.environment;
-            const data = await this.spin('Fetching traces', () => client.traces.list({ filters: bodyFilters }, { queryParams }));
+                ...(flags['start-time'] ? { start_time: flags['start-time'] } : {}),
+                ...(flags['end-time'] ? { end_time: flags['end-time'] } : {}),
+                ...(flags.environment ? { environment: flags.environment } : {}),
+                ...(bodyFilters ? { filters: bodyFilters } : {}),
+            }));
             this.outputResult(data, [
                 'trace_unique_id', 'name', 'duration', 'span_count', 'total_cost', 'error_count', 'start_time',
             ]);

package/dist/commands/traces/summary.js

@@ -6,7 +6,11 @@ class TracesSummary extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const data = await this.spin('Fetching traces summary', () => client.traces.retrieveTracesSummary({ start_time: flags['start-time'], end_time: flags['end-time'] }));
+            const data = await this.spin('Fetching traces summary', () => client.spans.getSpansSummary({
+                Authorization: this.getAuthHeader(),
+                start_time: flags['start-time'],
+                end_time: flags['end-time'],
+            }));
             this.log(JSON.stringify(data, null, 2));
         }
         catch (error) {
@@ -14,7 +18,7 @@ class TracesSummary extends BaseCommand {
         }
     }
 }
-TracesSummary.description = 'Get a summary of traces for a time range';
+TracesSummary.description = 'Get a span-level summary of activity for a time range (counts, latency, cost, errors aggregated across spans)';
 TracesSummary.flags = {
     ...BaseCommand.baseFlags,
     'start-time': Flags.string({ description: 'Start time (ISO 8601)', required: true }),

package/dist/commands/users/get.js

@@ -6,7 +6,7 @@ class UsersGet extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const data = await this.spin('Fetching user', () => client.users.retrieveUser({ customer_identifier: args.id }));
+            const data = await this.spin('Fetching user', () => client.users.retrieveUser({ Authorization: this.getAuthHeader(), customer_identifier: args.id }));
             this.log(JSON.stringify(data, null, 2));
         }
         catch (error) {

package/dist/commands/users/list.js

@@ -7,15 +7,13 @@ class UsersList extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const params = {
+            const data = await this.spin('Fetching users', () => client.users.listCustomers({
+                Authorization: this.getAuthHeader(),
                 page_size: flags.limit,
                 page: flags.page,
-            };
-            if (flags['sort-by'])
-                params.sort_by = flags['sort-by'];
-            if (flags.environment)
-                params.environment = flags.environment;
-            const data = await this.spin('Fetching users', () => client.users.list(params));
+                ...(flags['sort-by'] ? { sort_by: flags['sort-by'] } : {}),
+                ...(flags.environment ? { environment: flags.environment } : {}),
+            }));
             this.outputResult(data, [
                 'customer_identifier', 'name', 'email', 'number_of_requests', 'total_cost', 'last_active_timeframe',
             ]);

package/dist/lib/agents.d.ts

@@ -0,0 +1,16 @@
+export type CliTool = 'claude-code' | 'cursor' | 'codex-cli' | 'gemini-cli' | 'opencode';
+export interface ToolMeta {
+    name: string;
+    binary: string;
+    description: string;
+    configDirs: string[];
+}
+export declare const CLI_TOOLS: Record<CliTool, ToolMeta>;
+export interface DetectionSignal {
+    tool: CliTool;
+    onPath: boolean;
+    hasConfigDir: boolean;
+    reason: string;
+}
+export declare function isBinaryInstalled(binary: string): boolean;
+export declare function detectAgents(projectRoot: string, home: string): DetectionSignal[];

package/dist/lib/agents.js

@@ -0,0 +1,75 @@
+// Coding-agent registry and detection primitives.
+//
+// This is the single source of truth for the agents Respan can configure.
+// commands/setup/index.ts and commands/setup/doctor.ts previously maintained
+// parallel copies of this metadata.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+export const CLI_TOOLS = {
+    'claude-code': {
+        name: 'Claude Code',
+        binary: 'claude',
+        description: 'Anthropic\'s coding agent',
+        configDirs: ['~/.claude', '.claude'],
+    },
+    'cursor': {
+        name: 'Cursor',
+        binary: 'cursor',
+        description: 'AI-powered code editor',
+        configDirs: ['.cursor', '.cursorrc'],
+    },
+    'codex-cli': {
+        name: 'Codex CLI',
+        binary: 'codex',
+        description: 'OpenAI\'s coding agent',
+        configDirs: ['~/.codex', '.codex'],
+    },
+    'gemini-cli': {
+        name: 'Gemini CLI',
+        binary: 'gemini',
+        description: 'Google\'s coding agent',
+        configDirs: ['~/.gemini', '.gemini'],
+    },
+    'opencode': {
+        name: 'OpenCode',
+        binary: 'opencode',
+        description: 'Open-source coding agent',
+        configDirs: ['.opencode'],
+    },
+};
+export function isBinaryInstalled(binary) {
+    try {
+        execSync(`command -v ${binary}`, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function detectAgents(projectRoot, home) {
+    const signals = [];
+    for (const [id, meta] of Object.entries(CLI_TOOLS)) {
+        const onPath = isBinaryInstalled(meta.binary);
+        const hasConfigDir = meta.configDirs.some((dir) => {
+            const resolved = dir.startsWith('~')
+                ? path.join(home, dir.slice(1))
+                : dir.startsWith('.')
+                    ? path.join(projectRoot, dir)
+                    : dir;
+            return fs.existsSync(resolved);
+        });
+        const reasons = [];
+        if (onPath)
+            reasons.push('binary on PATH');
+        if (hasConfigDir)
+            reasons.push('config directory found');
+        signals.push({
+            tool: id,
+            onPath,
+            hasConfigDir,
+            reason: reasons.length > 0 ? reasons.join(', ') : 'not detected',
+        });
+    }
+    return signals;
+}

package/dist/lib/auth.js

@@ -1,4 +1,6 @@
+import * as path from 'node:path';
 import { getCredential } from './config.js';
+import { findProjectRoot, readTextFile, extractEnvVar } from './integrate.js';
 export const DEFAULT_BASE_URL = 'https://api.respan.ai';
 export const ENTERPRISE_BASE_URL = 'https://endpoint.respan.ai';
 function normalizeBaseUrl(baseUrl) {
@@ -9,6 +11,19 @@ function resolveConfiguredBaseUrl(credential, flagBaseUrl) {
     // the main persistent configuration path for CLI users.
     return normalizeBaseUrl(flagBaseUrl || process.env.RESPAN_API_BASE_URL || credential?.baseUrl || DEFAULT_BASE_URL);
 }
+/**
+ * Read RESPAN_API_KEY from the project's `.env`. setup writes it there as the
+ * project source of truth, so in-project commands (e.g. `respan logs list`)
+ * work right after setup without a separate `respan auth login`.
+ */
+function readProjectEnvKey() {
+    try {
+        return extractEnvVar(readTextFile(path.join(findProjectRoot(), '.env')), 'RESPAN_API_KEY');
+    }
+    catch {
+        return undefined;
+    }
+}
 export function resolveAuth(flags) {
     const credential = getCredential(flags.profile);
     const baseUrl = resolveConfiguredBaseUrl(credential, flags['base-url']);
@@ -21,6 +36,15 @@ export function resolveAuth(flags) {
             baseUrl,
         };
     }
+    // The project .env key wins over a saved credential — but an explicit
+    // --profile selects a specific credential (and its base URL), so don't let
+    // an ambient .env key override that choice and break enterprise setups.
+    if (!flags.profile) {
+        const projectEnvKey = readProjectEnvKey();
+        if (projectEnvKey) {
+            return { apiKey: projectEnvKey, baseUrl };
+        }
+    }
     if (credential) {
         return credentialToAuth(credential, baseUrl);
     }

package/dist/lib/base-command.d.ts

@@ -14,6 +14,8 @@ export declare abstract class BaseCommand extends Command {
     protected globalFlags: GlobalFlags;
     protected getAuth(): AuthConfig;
     protected getClient(): RespanClient;
+    protected getAuthHeader(): string;
+    protected getBaseUrl(): string;
     protected getOutputFormat(): 'json' | 'csv' | 'table';
     protected outputResult(data: unknown, columns?: string[]): void;
     protected spin<T>(label: string, fn: () => Promise<T>): Promise<T>;

package/dist/lib/base-command.js

@@ -17,10 +17,20 @@ export class BaseCommand extends Command {
         if (!token)
             throw new Error('No API key or access token available.');
         return new RespanClient({
-            token,
+            headers: { Authorization: `Bearer ${token}` },
             ...(auth.baseUrl ? { environment: auth.baseUrl } : {}),
         });
     }
+    getAuthHeader() {
+        const auth = this.getAuth();
+        const token = auth.apiKey || auth.accessToken;
+        if (!token)
+            throw new Error('No API key or access token available.');
+        return `Bearer ${token}`;
+    }
+    getBaseUrl() {
+        return this.getAuth().baseUrl || 'https://api.respan.ai';
+    }
     getOutputFormat() {
         if (this.globalFlags.json)
             return 'json';

package/dist/lib/colors.d.ts

@@ -0,0 +1,7 @@
+export declare const PC = "\u001B[38;2;100;131;240m";
+export declare const RESET = "\u001B[0m";
+export declare const DIM = "\u001B[2m";
+export declare const GREEN = "\u001B[32m";
+export declare const BOLD = "\u001B[1m";
+export declare const RED = "\u001B[31m";
+export declare const YELLOW = "\u001B[33m";

package/dist/lib/colors.js

@@ -0,0 +1,10 @@
+// Shared ANSI color/style constants for setup-related commands.
+// Consolidated from the copies previously inlined in commands/setup/index.ts
+// and commands/setup/doctor.ts.
+export const PC = '\x1b[38;2;100;131;240m';
+export const RESET = '\x1b[0m';
+export const DIM = '\x1b[2m';
+export const GREEN = '\x1b[32m';
+export const BOLD = '\x1b[1m';
+export const RED = '\x1b[31m';
+export const YELLOW = '\x1b[33m';

package/dist/lib/eval/runner.d.ts

@@ -0,0 +1,15 @@
+import { RespanClient } from '@respan/respan-api';
+export interface RunEvalResult {
+    prompt_id: string;
+    prompt_version_id?: string;
+    prompt_version_deployed?: number;
+    dataset_id: string;
+    evaluator_workflow_ids: string[];
+    experiment_id: string;
+    created_prompt: boolean;
+    created_dataset: boolean;
+    created_experiment: boolean;
+    evaluators_created: number;
+    rows_added: number;
+}
+export declare function runEval(filePath: string, client: RespanClient, authHeader: string, baseUrl: string, log?: (msg: string) => void): Promise<RunEvalResult>;

package/dist/lib/eval/runner.js

@@ -0,0 +1,292 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { parseEvalFile } from './schema.js';
+export async function runEval(filePath, client, authHeader, baseUrl, log = () => { }) {
+    const raw = readFileSync(filePath, 'utf8');
+    const evalFile = parseEvalFile(raw);
+    const promptResult = await ensurePrompt(evalFile, client, authHeader, log);
+    persist(filePath, evalFile);
+    const datasetResult = await ensureDataset(evalFile, client, authHeader, log);
+    persist(filePath, evalFile);
+    const evaluatorResult = await ensureEvaluatorWorkflows(evalFile, client, authHeader, baseUrl, log);
+    persist(filePath, evalFile);
+    const experimentResult = await ensureExperiment(evalFile, promptResult.id, datasetResult.id, evaluatorResult.workflow_ids, client, authHeader, log);
+    persist(filePath, evalFile);
+    return {
+        prompt_id: promptResult.id,
+        prompt_version_id: promptResult.version_id,
+        prompt_version_deployed: promptResult.deployed_version,
+        dataset_id: datasetResult.id,
+        evaluator_workflow_ids: evaluatorResult.workflow_ids,
+        experiment_id: experimentResult.id,
+        created_prompt: promptResult.created,
+        created_dataset: datasetResult.created,
+        created_experiment: experimentResult.created,
+        evaluators_created: evaluatorResult.created_count,
+        rows_added: datasetResult.rows_added,
+    };
+}
+async function ensurePrompt(evalFile, client, Authorization, log) {
+    const { prompt } = evalFile;
+    if (prompt.id) {
+        log(`prompt: reusing ${prompt.id}`);
+        return { id: prompt.id, version_id: prompt.version_id, created: false };
+    }
+    log(`prompt: creating "${prompt.name}"`);
+    const created = (await client.prompts.createPrompt({
+        Authorization,
+        name: prompt.name,
+        ...(prompt.description ? { description: prompt.description } : {}),
+    }));
+    const promptId = String(created.id ?? created.prompt_id ?? '');
+    if (!promptId)
+        throw new Error('createPrompt: response missing id');
+    prompt.id = promptId;
+    log(`prompt: creating version on ${promptId}`);
+    const version = (await client.prompts.createPromptVersion({
+        Authorization,
+        prompt_id: promptId,
+        messages: prompt.messages,
+        model: prompt.model,
+        ...(prompt.temperature !== undefined ? { temperature: prompt.temperature } : {}),
+        ...(prompt.max_tokens !== undefined ? { max_tokens: prompt.max_tokens } : {}),
+        ...(prompt.top_p !== undefined ? { top_p: prompt.top_p } : {}),
+    }));
+    const versionId = String(version.id ?? version.version_id ?? '');
+    if (versionId)
+        prompt.version_id = versionId;
+    const versionNumber = typeof version.version === 'number'
+        ? version.version
+        : Number.parseInt(String(version.version ?? '1'), 10);
+    log(`prompt: committing draft version ${versionNumber}`);
+    await client.prompts.commitPromptVersion({ Authorization, prompt_id: promptId });
+    log(`prompt: deploying version ${versionNumber}`);
+    await client.prompts.deployPromptVersion({ Authorization, prompt_id: promptId, version: versionNumber });
+    return {
+        id: promptId,
+        version_id: versionId || undefined,
+        deployed_version: versionNumber,
+        created: true,
+    };
+}
+async function ensureDataset(evalFile, client, Authorization, log) {
+    const { dataset } = evalFile;
+    if (dataset.id) {
+        log(`dataset: reusing ${dataset.id}`);
+        return { id: dataset.id, created: false, rows_added: 0 };
+    }
+    log(`dataset: creating "${dataset.name}"`);
+    const created = (await client.datasets.createDataset({
+        Authorization,
+        name: dataset.name,
+        is_empty: true,
+        ...(dataset.description ? { description: dataset.description } : {}),
+    }));
+    const datasetId = String(created.id ?? created.dataset_id ?? '');
+    if (!datasetId)
+        throw new Error('createDataset: response missing id');
+    dataset.id = datasetId;
+    const logs = dataset.rows.map((row) => {
+        const { expected_output, ...variables } = row;
+        return {
+            input: variables,
+            ...(expected_output !== undefined ? { expected_output } : {}),
+        };
+    });
+    const result = (await client.datasets.bulkCreateDatasetLogs({
+        Authorization,
+        dataset_id: datasetId,
+        logs,
+    }));
+    const successCount = typeof result.success_count === 'number' ? result.success_count : 0;
+    const errorCount = typeof result.error_count === 'number' ? result.error_count : 0;
+    log(`dataset: added ${successCount}/${logs.length} row(s)` + (errorCount ? ` (${errorCount} errors)` : ''));
+    return { id: datasetId, created: true, rows_added: successCount };
+}
+async function ensureEvaluatorWorkflows(evalFile, client, Authorization, baseUrl, log) {
+    const experiment = evalFile.experiment ?? (evalFile.experiment = {});
+    const evaluators = experiment.evaluators ?? [];
+    const explicitWorkflowIds = experiment.evaluator_workflow_ids ?? [];
+    let createdCount = 0;
+    const workflowIds = [];
+    // Resolve user-supplied workflow IDs to their deployed-version row IDs.
+    // The experiment API expects version IDs (the `evaluator_workflow_ids` field
+    // name is misleading), so we look up each workflow's deployed version.
+    for (const wfId of explicitWorkflowIds) {
+        const versionRowId = await getDeployedWorkflowVersionId(Authorization, baseUrl, wfId);
+        if (!versionRowId) {
+            throw new Error(`workflow ${wfId} (from experiment.evaluator_workflow_ids) has no deployed version.`);
+        }
+        workflowIds.push(versionRowId);
+    }
+    for (const ev of evaluators) {
+        if (!ev.evaluator_id) {
+            log(`evaluator: creating "${ev.name}" (${ev.type})`);
+            const created = (await client.evaluators.createEvaluator({
+                Authorization,
+                name: ev.name,
+                type: ev.type,
+                score_value_type: ev.score_value_type,
+                ...(ev.description ? { description: ev.description } : {}),
+                ...(ev.score_config ? { score_config: ev.score_config } : {}),
+                ...(ev.passing_conditions ? { passing_conditions: ev.passing_conditions } : {}),
+                ...(ev.llm_config ? { llm_config: ev.llm_config } : {}),
+                ...(ev.code_config ? { code_config: ev.code_config } : {}),
+            }));
+            const evaluatorId = String(created.id ?? created.evaluator_id ?? '');
+            if (!evaluatorId)
+                throw new Error('createEvaluator: response missing id');
+            ev.evaluator_id = evaluatorId;
+            createdCount += 1;
+        }
+        else {
+            log(`evaluator: reusing ${ev.evaluator_id}`);
+        }
+        if (!ev.workflow_id) {
+            const workflowName = `${ev.name} workflow`;
+            log(`workflow: creating "${workflowName}" wrapping evaluator ${ev.evaluator_id}`);
+            const nodeIdSeed = ev.evaluator_id.slice(0, 8);
+            const blocklyNodeId = safeNodeId(nodeIdSeed);
+            const taskId = `blockly_hidden_eval_task_${blocklyNodeId}`;
+            const taskLabel = `blockly_hidden_eval_${blocklyNodeId}`;
+            const outputField = outputFieldForScoreType(ev.score_value_type);
+            const taskConfig = {
+                evaluator_id: ev.evaluator_id,
+                score_value_type: ev.score_value_type,
+                score_config: ev.score_config ?? {},
+                is_auto_persist_enabled: true,
+                _blockly_hidden_eval: true,
+                _blockly_is_result: true,
+                _blockly_node_id: blocklyNodeId,
+                ...(outputField ? { _blockly_output_field: outputField } : {}),
+                _blockly_evaluator_kind: ev.type,
+                ...(ev.llm_config ? { llm_config: ev.llm_config } : {}),
+                ...(ev.code_config ? { code_config: ev.code_config } : {}),
+            };
+            const createdWf = (await client.workflows.createWorkflow({
+                Authorization,
+                type: 'evaluators',
+                trigger_event_type: 'eval_only',
+                name: workflowName,
+                tasks: [{
+                        id: taskId,
+                        type: 'eval',
+                        generation_method: ev.type,
+                        label: taskLabel,
+                        config: taskConfig,
+                        next: null,
+                    }],
+            }));
+            const workflowId = String(createdWf.workflow_id ?? createdWf.id ?? '');
+            if (!workflowId)
+                throw new Error('createWorkflow: response missing workflow_id');
+            ev.workflow_id = workflowId;
+            log(`workflow: committing draft v1`);
+            await commitWorkflow(Authorization, baseUrl, workflowId);
+            log(`workflow: deploying v1`);
+            const deployed = (await client.workflows.deployWorkflow({
+                Authorization,
+                workflow_id: workflowId,
+                version: 1,
+            }));
+            const deployedVersion = typeof deployed.version === 'number' ? deployed.version : 1;
+            ev.workflow_version_deployed = deployedVersion;
+            const versionRowId = String(deployed.id ?? '');
+            if (versionRowId)
+                ev.workflow_version_id = versionRowId;
+        }
+        else {
+            log(`workflow: reusing ${ev.workflow_id}`);
+        }
+        if (!ev.workflow_version_id) {
+            log(`workflow: looking up deployed version row id for ${ev.workflow_id}`);
+            const versionRowId = await getDeployedWorkflowVersionId(Authorization, baseUrl, ev.workflow_id);
+            if (!versionRowId) {
+                throw new Error(`workflow ${ev.workflow_id} has no deployed version; rerun after committing/deploying.`);
+            }
+            ev.workflow_version_id = versionRowId;
+        }
+        workflowIds.push(ev.workflow_version_id);
+    }
+    return { workflow_ids: workflowIds, created_count: createdCount };
+}
+async function ensureExperiment(evalFile, promptId, datasetId, workflowIds, client, Authorization, log) {
+    const experiment = evalFile.experiment ?? (evalFile.experiment = {});
+    if (experiment.id) {
+        log(`experiment: reusing ${experiment.id}`);
+        return { id: experiment.id, created: false };
+    }
+    const name = experiment.name ?? evalFile.experiment_name ?? `${evalFile.name} run`;
+    const evaluatorSlugs = experiment.evaluator_slugs ?? [];
+    if (workflowIds.length === 0 && evaluatorSlugs.length === 0) {
+        throw new Error('experiment requires at least one evaluator. Add `experiment.evaluators[]` to your eval file ' +
+            '(or `experiment.evaluator_workflow_ids` / `experiment.evaluator_slugs` for existing ones).');
+    }
+    const evaluatorSummary = workflowIds.length > 0
+        ? `evaluator_workflow_ids: ${workflowIds.join(', ')}`
+        : `evaluator_slugs: ${evaluatorSlugs.join(', ')}`;
+    log(`experiment: creating "${name}" with ${evaluatorSummary}`);
+    const created = (await client.experiments.createExperiment({
+        Authorization,
+        name,
+        dataset_id: datasetId,
+        ...(experiment.description ? { description: experiment.description } : {}),
+        workflow: [{ type: 'prompt', config: { prompt_id: promptId } }],
+        ...(workflowIds.length > 0 ? { evaluator_workflow_ids: workflowIds } : {}),
+        ...(evaluatorSlugs.length > 0 ? { evaluator_slugs: evaluatorSlugs } : {}),
+    }));
+    const experimentId = String(created.id ?? created.experiment_id ?? '');
+    if (!experimentId)
+        throw new Error('createExperiment: response missing id');
+    experiment.id = experimentId;
+    if (!experiment.name)
+        experiment.name = name;
+    return { id: experimentId, created: true };
+}
+function safeNodeId(raw) {
+    const sanitized = raw.replace(/[^a-zA-Z0-9_]/g, '_').slice(0, 30);
+    return sanitized || 'node';
+}
+function outputFieldForScoreType(scoreValueType) {
+    switch (scoreValueType) {
+        case 'boolean':
+            return 'boolean_value';
+        case 'single_select':
+        case 'text':
+        case 'comment':
+            return 'string_value';
+        case 'multi_select':
+        case 'json':
+            return null;
+        default:
+            return 'primary_score';
+    }
+}
+async function getDeployedWorkflowVersionId(Authorization, baseUrl, workflowId) {
+    const url = `${normalizeBaseUrl(baseUrl)}/api/workflows/${encodeURIComponent(workflowId)}/versions/`;
+    const response = await fetch(url, { headers: { Authorization } });
+    if (!response.ok)
+        return null;
+    const body = (await response.json());
+    const results = body.results ?? [];
+    const deployed = results.find((v) => v.is_enabled === true && v.is_read_only === true)
+        ?? results.find((v) => v.is_read_only === true);
+    return deployed ? String(deployed.id ?? '') : null;
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, '').replace(/\/api$/, '');
+}
+async function commitWorkflow(Authorization, baseUrl, workflowId) {
+    const url = `${normalizeBaseUrl(baseUrl)}/api/workflows/${encodeURIComponent(workflowId)}/commits/`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization },
+        body: JSON.stringify({}),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`commitWorkflow ${response.status}: ${text || response.statusText}`);
+    }
+}
+function persist(filePath, evalFile) {
+    writeFileSync(filePath, JSON.stringify(evalFile, null, 2) + '\n', 'utf8');
+}