@respan/cli 0.9.0 → 0.11.0

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

@@ -0,0 +1,67 @@
+export interface EvalPromptMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface EvalPromptBlock {
+    id?: string;
+    version_id?: string;
+    name: string;
+    description?: string;
+    model: string;
+    messages: EvalPromptMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+}
+export interface EvalDatasetBlock {
+    id?: string;
+    name: string;
+    description?: string;
+    rows: Record<string, unknown>[];
+}
+export interface EvalEvaluatorBlock {
+    evaluator_id?: string;
+    workflow_id?: string;
+    workflow_version_id?: string;
+    workflow_version_deployed?: number;
+    name: string;
+    type: 'llm' | 'code' | 'human';
+    score_value_type: 'numerical' | 'boolean' | 'percentage' | 'single_select' | 'multi_select' | 'json' | 'text' | 'categorical' | 'comment';
+    description?: string;
+    score_config?: {
+        min_score?: number;
+        max_score?: number;
+        choices?: {
+            name?: string;
+            value?: string;
+        }[];
+    };
+    passing_conditions?: Record<string, unknown>;
+    llm_config?: {
+        model: string;
+        evaluator_definition: string;
+        scoring_rubric?: string;
+        temperature?: number;
+        max_tokens?: number;
+        top_p?: number;
+    };
+    code_config?: {
+        eval_code_snippet: string;
+    };
+}
+export interface EvalExperimentBlock {
+    id?: string;
+    name?: string;
+    description?: string;
+    evaluators?: EvalEvaluatorBlock[];
+    evaluator_slugs?: string[];
+    evaluator_workflow_ids?: string[];
+}
+export interface EvalFile {
+    name: string;
+    experiment_name?: string;
+    prompt: EvalPromptBlock;
+    dataset: EvalDatasetBlock;
+    experiment?: EvalExperimentBlock;
+}
+export declare function parseEvalFile(raw: string): EvalFile;

package/dist/lib/eval/schema.js

@@ -0,0 +1,22 @@
+export function parseEvalFile(raw) {
+    const data = JSON.parse(raw);
+    if (!data.name)
+        throw new Error('eval file: `name` is required');
+    if (!data.prompt)
+        throw new Error('eval file: `prompt` block is required');
+    if (!data.prompt.name)
+        throw new Error('eval file: `prompt.name` is required');
+    if (!data.prompt.model)
+        throw new Error('eval file: `prompt.model` is required');
+    if (!Array.isArray(data.prompt.messages) || data.prompt.messages.length === 0) {
+        throw new Error('eval file: `prompt.messages` must be a non-empty array');
+    }
+    if (!data.dataset)
+        throw new Error('eval file: `dataset` block is required');
+    if (!data.dataset.name)
+        throw new Error('eval file: `dataset.name` is required');
+    if (!Array.isArray(data.dataset.rows)) {
+        throw new Error('eval file: `dataset.rows` must be an array');
+    }
+    return data;
+}

package/dist/lib/integrate.d.ts

@@ -51,6 +51,12 @@ export declare function readJsonFile(filePath: string): Record<string, unknown>;
 export declare function writeJsonFile(filePath: string, data: Record<string, unknown>): void;
 export declare function readTextFile(filePath: string): string;
 export declare function writeTextFile(filePath: string, content: string): void;
+/**
+ * Read a `KEY=value` line from .env-style content. Trims before stripping a
+ * single layer of surrounding quotes — the closing quote can sit inside
+ * trailing whitespace, so order matters. Returns undefined if absent or empty.
+ */
+export declare function extractEnvVar(content: string, key: string): string | undefined;
 export declare function expandHome(p: string): string;
 export declare function parseAttrs(raw: string): Record<string, string>;
 /**

package/dist/lib/integrate.js

@@ -148,6 +148,17 @@ export function writeTextFile(filePath, content) {
     ensureDir(path.dirname(filePath));
     fs.writeFileSync(filePath, content);
 }
+/**
+ * Read a `KEY=value` line from .env-style content. Trims before stripping a
+ * single layer of surrounding quotes — the closing quote can sit inside
+ * trailing whitespace, so order matters. Returns undefined if absent or empty.
+ */
+export function extractEnvVar(content, key) {
+    const match = content.match(new RegExp(`^${key}=(.+)$`, 'm'));
+    if (!match)
+        return undefined;
+    return match[1].trim().replace(/^["']|["']$/g, '').trim() || undefined;
+}
 export function expandHome(p) {
     if (p.startsWith('~')) {
         return path.join(os.homedir(), p.slice(1));

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

@@ -0,0 +1,84 @@
+import { BaseCommand } from './base-command.js';
+import { CliTool, DetectionSignal } from './agents.js';
+export type SetupMode = 'tracing' | 'gateway';
+interface RunSetupOptions {
+    agent?: string;
+    noInstrument?: boolean;
+}
+/**
+ * Intermediate base class for the `respan setup` family of commands
+ * (`setup`, `setup tracing`, `setup gateway`).
+ *
+ * It deliberately sits between the concrete commands and {@link BaseCommand}
+ * so that setup-only concerns (interactive prompts, the agent registry, and
+ * multi-kilobyte skill content) never leak onto the root command class that
+ * every other command extends.
+ */
+export declare abstract class SetupBaseCommand extends BaseCommand {
+    static baseFlags: {
+        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>;
+    };
+    /**
+     * Shared setup flow for all three entry points.
+     *
+     *   1. askApiKey()       // .env → global credential → prompt
+     *   2. if mode is undefined → ask "Tracing or Gateway?" (interactive only)
+     *   3. verifyApiKey(mode) // both re-prompt on a rejected key; can pause setup
+     *   4. selectAgent()      // drives only the launch
+     *   5. installSkill()     // full bundle, for all agents, regardless of selection
+     *   6. launchAgent(mode)  // only if an agent was selected
+     */
+    protected runSetup(mode?: SetupMode, opts?: RunSetupOptions): Promise<void>;
+    protected askMode(step: number): Promise<SetupMode>;
+    protected askApiKey(projectRoot: string): Promise<string>;
+    /**
+     * Verify the key for the chosen mode. Both paths re-prompt on a rejected key
+     * and return false if the user abandons the check, so the caller can pause
+     * setup instead of reporting success with a key that doesn't work.
+     */
+    protected verifyApiKey(apiKey: string, mode: SetupMode, projectRoot: string): Promise<boolean>;
+    /** Prompt for a replacement key and persist it to the project .env. */
+    private reenterApiKey;
+    private verifyTracingKey;
+    /**
+     * Gateway verification gates on a real request succeeding: there is no
+     * credit-balance endpoint, so a 200 is the only proof of a valid key with a
+     * positive balance. A rejected key (401/403) re-prompts; any other failure
+     * loops on the user's say-so. Returns true on success, false if abandoned.
+     */
+    private verifyGatewayKey;
+    /**
+     * Build a rich demo OTLP trace that mimics a customer support agent workflow:
+     *   workflow: customer_support_pipeline
+     *     └── agent: support_agent
+     *           ├── tool: lookup_order
+     *           ├── chat: openai.chat (classify intent)
+     *           ├── tool: process_refund
+     *           ├── chat: openai.chat (generate response)
+     *           └── task: log_resolution
+     */
+    protected buildDemoTrace(email?: string): Record<string, unknown>;
+    /**
+     * Minimal chat completion sent through the gateway to prove auth + routing
+     * and drop a real logged request into the user's account.
+     */
+    protected buildDemoCompletion(): Record<string, unknown>;
+    protected selectAgent(flagAgent: CliTool | undefined, detected: DetectionSignal[]): Promise<CliTool | null>;
+    protected installSkill(): Promise<void>;
+    protected launchAgent(tool: CliTool, projectRoot: string, mode: SetupMode): Promise<void>;
+    protected logStep(num: number, label: string): void;
+    protected saveToEnv(envPath: string, existingContent: string, key: string, value: string): void;
+    protected getGitEmail(): string | undefined;
+    /**
+     * Send a lightweight setup notification (email only).
+     * This helps the team know when new users set up Respan so we can
+     * reach out and help with onboarding.
+     */
+    protected notifySetup(email?: string): Promise<void>;
+}
+export {};