@respan/cli 0.10.0 → 0.12.0

package/dist/lib/demo/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared types for the `respan demo` orchestrator and its per-service seeders.
+ *
+ * The orchestrator (`commands/demo/*`) is service-agnostic: it knows only the
+ * {@link Seeder} contract and aggregates {@link SeederResult}s. Each service
+ * (prompts today; traces/datasets/evaluators later) ships its own `seed-*.ts`
+ * that implements {@link Seeder}, so adding a service is a drop-in.
+ */
+import { RespanClient } from '@respan/respan-api';
+/** Authed handles every seeder needs to talk to the platform. */
+export interface SeederContext {
+    client: RespanClient;
+    /** `"Bearer <token>"`, as the SDK request objects expect. */
+    authHeader: string;
+    /**
+     * Resolved API base URL (e.g. `https://api.respan.ai`). Needed by seeders that
+     * bypass the SDK — the traces seeder POSTs raw OTLP to `/v2/traces`, which the
+     * SDK does not expose. Prompt seeding ignores this.
+     */
+    baseUrl: string;
+}
+/** A demo resource that already exists in the account (matched by name). */
+export interface ExistingResource {
+    name: string;
+    id: string;
+}
+/** Outcome for a single resource. */
+export interface SeedItemResult {
+    name: string;
+    status: 'created' | 'skipped' | 'deleted';
+    /** Resource ID — the new ID when created, the removed ID when deleted. */
+    id?: string;
+    /** Why it was skipped (e.g. "already exists" / "not found"). */
+    reason?: string;
+}
+/** Aggregated outcome for one service's seed or clear run. */
+export interface SeederResult {
+    /** Machine key, e.g. `"prompts"`. */
+    service: string;
+    /** Human label for summaries, e.g. `"Prompts"`. */
+    label: string;
+    items: SeedItemResult[];
+}
+/** A per-service seeder. Owns its fixtures and all create/find/delete logic for
+ * one service, so the orchestrator stays service-agnostic. Both `run` and
+ * `clear` must be safely re-runnable (idempotent). */
+export interface Seeder {
+    service: string;
+    label: string;
+    /** Create any missing demo resources, deploying them live. Skips existing. */
+    run(ctx: SeederContext): Promise<SeederResult>;
+    /** Delete the demo resources this seeder owns (matched by fixture name). */
+    clear(ctx: SeederContext): Promise<SeederResult>;
+    /** Find demo resources that currently exist in the account (by fixture name),
+     * without modifying anything. Used for dedup and for clear previews. */
+    findExisting(ctx: SeederContext): Promise<ExistingResource[]>;
+}

package/dist/lib/demo/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared types for the `respan demo` orchestrator and its per-service seeders.
+ *
+ * The orchestrator (`commands/demo/*`) is service-agnostic: it knows only the
+ * {@link Seeder} contract and aggregates {@link SeederResult}s. Each service
+ * (prompts today; traces/datasets/evaluators later) ships its own `seed-*.ts`
+ * that implements {@link Seeder}, so adding a service is a drop-in.
+ */
+export {};

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 {};