@respan/cli 0.10.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/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/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/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 {};