@respan/cli 0.10.0 → 0.12.0

package/dist/commands/demo/clear.d.ts

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../lib/base-command.js';
+/**
+ * Tear down what `respan demo` created. Each seeder owns how it identifies its own
+ * demo resources — prompts by exact fixture name, traces by the `demo` workflow —
+ * so a resource that was manually renamed/relabeled may not be matched, the same
+ * identity contract used when seeding.
+ */
+export default class DemoClear extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        yes: 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>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        csv: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private previewDeletions;
+    private printSummary;
+}

package/dist/commands/demo/clear.js

@@ -0,0 +1,114 @@
+import { Flags } from '@oclif/core';
+import { confirm } from '@inquirer/prompts';
+import { BaseCommand } from '../../lib/base-command.js';
+import { getActiveProfile, getCredential } from '../../lib/config.js';
+import { GREEN, DIM, BOLD, RESET } from '../../lib/colors.js';
+import { SEEDERS } from '../../lib/demo/seeders.js';
+/**
+ * Tear down what `respan demo` created. Each seeder owns how it identifies its own
+ * demo resources — prompts by exact fixture name, traces by the `demo` workflow —
+ * so a resource that was manually renamed/relabeled may not be matched, the same
+ * identity contract used when seeding.
+ */
+class DemoClear extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(DemoClear);
+        this.globalFlags = flags;
+        const profile = flags.profile || getActiveProfile();
+        if (!getCredential(profile) && !flags['api-key']) {
+            this.error('Not authenticated. Run `respan auth login` (or set RESPAN_API_KEY) before running `respan demo clear`.', { exit: 1 });
+        }
+        try {
+            const client = this.getClient();
+            const ctx = {
+                client,
+                authHeader: this.getAuthHeader(),
+                baseUrl: this.getBaseUrl(),
+            };
+            // Preview what exists before deleting anything.
+            const existing = [];
+            for (const seeder of SEEDERS) {
+                const matches = await this.spin(`Finding ${seeder.label}`, () => seeder.findExisting(ctx));
+                existing.push({ label: seeder.label, matches });
+            }
+            const total = existing.reduce((n, e) => n + e.matches.length, 0);
+            if (total === 0) {
+                this.log('');
+                this.log(`Nothing to clear in account ${DIM}(${profile})${RESET}.`);
+                this.log('');
+                return;
+            }
+            if (!flags.yes && !flags.json) {
+                this.previewDeletions(profile, existing);
+                if (!process.stdin.isTTY) {
+                    this.error('Refusing to delete without confirmation. Re-run with --yes.', { exit: 1 });
+                }
+                const proceed = await confirm({
+                    message: `Delete ${total} demo resource(s) from account "${profile}"?`,
+                    default: false,
+                });
+                if (!proceed) {
+                    this.log('Aborted. Nothing was deleted.');
+                    return;
+                }
+            }
+            const results = [];
+            for (const seeder of SEEDERS) {
+                const result = await this.spin(`Clearing ${seeder.label}`, () => seeder.clear(ctx));
+                results.push(result);
+            }
+            this.printSummary(profile, results);
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    previewDeletions(profile, existing) {
+        this.log('');
+        this.log(`${BOLD}respan demo clear${RESET} will delete from account ${DIM}(${profile})${RESET}:`);
+        for (const { label, matches } of existing) {
+            if (matches.length === 0)
+                continue;
+            this.log('');
+            this.log(`  ${BOLD}${label}${RESET}`);
+            for (const m of matches) {
+                this.log(`  ${DIM}- ${m.name}  (id: ${m.id})${RESET}`);
+            }
+        }
+        this.log('');
+    }
+    printSummary(profile, results) {
+        if (this.globalFlags.json) {
+            this.outputResult(results);
+            return;
+        }
+        this.log('');
+        this.log(`${GREEN}✓${RESET} ${BOLD}respan demo clear${RESET} — account ${DIM}(${profile})${RESET}`);
+        for (const result of results) {
+            if (result.items.length === 0)
+                continue; // e.g. traces, which are never deleted
+            this.log('');
+            this.log(`  ${BOLD}${result.label}${RESET}`);
+            for (const item of result.items) {
+                if (item.status === 'deleted') {
+                    this.log(`  ${GREEN}Deleted${RESET}   ${item.name}  ${DIM}(id: ${item.id})${RESET}`);
+                }
+                else {
+                    this.log(`  ${DIM}Skipped   ${item.name}  (${item.reason})${RESET}`);
+                }
+            }
+        }
+        const deletedCount = results.reduce((n, r) => n + r.items.filter((i) => i.status === 'deleted').length, 0);
+        const skippedCount = results.reduce((n, r) => n + r.items.filter((i) => i.status === 'skipped').length, 0);
+        this.log('');
+        this.log(`  ${DIM}${deletedCount} deleted, ${skippedCount} not found${RESET}`);
+        this.log('');
+    }
+}
+DemoClear.description = 'Delete the sample prompts, datasets, and evaluators created by `respan demo`. Demo traces are left in place (each run is timestamped history). Idempotent — safe to re-run.';
+DemoClear.examples = ['<%= config.bin %> demo clear', '<%= config.bin %> demo clear --yes'];
+DemoClear.flags = {
+    ...BaseCommand.baseFlags,
+    yes: Flags.boolean({ char: 'y', description: 'Skip the confirmation prompt', default: false }),
+};
+export default DemoClear;

package/dist/commands/demo/index.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../lib/base-command.js';
+export default class Demo extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        '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>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        csv: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private printSummary;
+}

package/dist/commands/demo/index.js

@@ -0,0 +1,81 @@
+import { BaseCommand } from '../../lib/base-command.js';
+import { getActiveProfile, getCredential } from '../../lib/config.js';
+import { GREEN, DIM, BOLD, RESET } from '../../lib/colors.js';
+import { SEEDERS } from '../../lib/demo/seeders.js';
+const PLATFORM_BASE = 'https://platform.respan.ai/platform';
+/** Dashboard link for a seeded service, deep-linked/filtered where possible so the
+ * user lands directly on what was just created. Traces are pre-filtered to the
+ * `demo` workflow so they're isolated from any existing traffic. */
+function viewLink(service) {
+    switch (service) {
+        case 'prompts':
+            return `${PLATFORM_BASE}/prompts`;
+        case 'datasets':
+            return `${PLATFORM_BASE}/datasets`;
+        case 'evaluators':
+            return `${PLATFORM_BASE}/evaluators`;
+        case 'traces':
+            return `${PLATFORM_BASE}/traces?span_workflow_name=demo`;
+        default:
+            return undefined;
+    }
+}
+class Demo extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(Demo);
+        this.globalFlags = flags;
+        const profile = flags.profile || getActiveProfile();
+        if (!getCredential(profile) && !flags['api-key']) {
+            this.error('Not authenticated. Run `respan auth login` (or set RESPAN_API_KEY) before running `respan demo`.', { exit: 1 });
+        }
+        try {
+            const client = this.getClient();
+            const ctx = {
+                client,
+                authHeader: this.getAuthHeader(),
+                baseUrl: this.getBaseUrl(),
+            };
+            const results = [];
+            for (const seeder of SEEDERS) {
+                const result = await this.spin(`Seeding ${seeder.label}`, () => seeder.run(ctx));
+                results.push(result);
+            }
+            this.printSummary(profile, results);
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    printSummary(profile, results) {
+        if (this.globalFlags.json) {
+            this.outputResult(results);
+            return;
+        }
+        this.log('');
+        this.log(`${GREEN}✓${RESET} ${BOLD}respan demo${RESET} — seeded into account ${DIM}(${profile})${RESET}`);
+        for (const result of results) {
+            this.log('');
+            this.log(`  ${BOLD}${result.label}${RESET}`);
+            for (const item of result.items) {
+                if (item.status === 'created') {
+                    this.log(`  ${GREEN}Created${RESET}   ${item.name}  ${DIM}(id: ${item.id})${RESET}`);
+                }
+                else {
+                    this.log(`  ${DIM}Skipped   ${item.name}  (${item.reason})${RESET}`);
+                }
+            }
+            const link = viewLink(result.service);
+            if (link)
+                this.log(`  ${DIM}View:${RESET} ${link}`);
+        }
+        const createdCount = results.reduce((n, r) => n + r.items.filter((i) => i.status === 'created').length, 0);
+        const skippedCount = results.reduce((n, r) => n + r.items.filter((i) => i.status === 'skipped').length, 0);
+        this.log('');
+        this.log(`  ${DIM}${createdCount} created, ${skippedCount} skipped${RESET}`);
+        this.log('');
+    }
+}
+Demo.description = 'Seed your account with sample data (prompts and traces) so you have something to explore. Idempotent — safe to re-run.';
+Demo.examples = ['<%= config.bin %> demo'];
+Demo.flags = { ...BaseCommand.baseFlags };
+export default Demo;

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

@@ -13,5 +13,4 @@ export default class SetupDoctor extends BaseCommand {
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
-    private isBinaryInstalled;
 }

package/dist/commands/setup/doctor.js

@@ -5,12 +5,8 @@ import { execSync } from 'node:child_process';
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../lib/base-command.js';
 import { findProjectRoot, expandHome, readTextFile } from '../../lib/integrate.js';
-const GREEN = '\x1b[32m';
-const RED = '\x1b[31m';
-const YELLOW = '\x1b[33m';
-const DIM = '\x1b[2m';
-const BOLD = '\x1b[1m';
-const RESET = '\x1b[0m';
+import { GREEN, RED, YELLOW, DIM, BOLD, RESET } from '../../lib/colors.js';
+import { isBinaryInstalled } from '../../lib/agents.js';
 class SetupDoctor extends BaseCommand {
     async run() {
         const { flags } = await this.parse(SetupDoctor);
@@ -43,7 +39,7 @@ class SetupDoctor extends BaseCommand {
         this.log('');
         // ── 2. Respan CLI ──────────────────────────────────────────────
         this.log(`  ${BOLD}Respan CLI${RESET}`);
-        const respanInstalled = this.isBinaryInstalled('respan');
+        const respanInstalled = isBinaryInstalled('respan');
         if (respanInstalled) {
             try {
                 const version = execSync('respan --version', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
@@ -66,44 +62,44 @@ class SetupDoctor extends BaseCommand {
                 name: 'Claude Code',
                 globalConfigs: ['~/.claude/settings.json'],
                 localConfigs: ['.claude/settings.local.json'],
-                globalSkills: ['~/.claude/skills/respan/SKILL.md', '~/.agents/skills/respan/SKILL.md'],
-                localSkills: ['.claude/skills/respan/SKILL.md', '.agents/skills/respan/SKILL.md'],
+                globalSkills: ['~/.claude/skills/respan/SKILL.md'],
+                localSkills: ['.claude/skills/respan/SKILL.md'],
             },
             'cursor': {
                 binary: 'cursor',
                 name: 'Cursor',
                 globalConfigs: ['~/.cursor/rules'],
                 localConfigs: ['.cursor/rules'],
-                globalSkills: ['~/.cursor/skills/respan/SKILL.md', '~/.agents/skills/respan/SKILL.md'],
-                localSkills: ['.cursor/skills/respan/SKILL.md', '.agents/skills/respan/SKILL.md'],
+                globalSkills: ['~/.agents/skills/respan/SKILL.md', '~/.cursor/skills/respan/SKILL.md'],
+                localSkills: ['.agents/skills/respan/SKILL.md', '.cursor/skills/respan/SKILL.md'],
             },
             'codex-cli': {
                 binary: 'codex',
                 name: 'Codex CLI',
                 globalConfigs: ['~/.codex/config.toml'],
                 localConfigs: ['.codex/respan.json'],
-                globalSkills: ['~/.codex/skills/respan/SKILL.md', '~/.agents/skills/respan/SKILL.md'],
-                localSkills: ['.codex/skills/respan/SKILL.md', '.agents/skills/respan/SKILL.md'],
+                globalSkills: ['~/.agents/skills/respan/SKILL.md', '~/.codex/skills/respan/SKILL.md'],
+                localSkills: ['.agents/skills/respan/SKILL.md', '.codex/skills/respan/SKILL.md'],
             },
             'gemini-cli': {
                 binary: 'gemini',
                 name: 'Gemini CLI',
                 globalConfigs: ['~/.gemini/settings.json'],
                 localConfigs: ['.gemini/settings.json'],
-                globalSkills: ['~/.gemini/skills/respan/SKILL.md', '~/.agents/skills/respan/SKILL.md'],
-                localSkills: ['.gemini/skills/respan/SKILL.md', '.agents/skills/respan/SKILL.md'],
+                globalSkills: ['~/.agents/skills/respan/SKILL.md', '~/.gemini/skills/respan/SKILL.md'],
+                localSkills: ['.agents/skills/respan/SKILL.md', '.gemini/skills/respan/SKILL.md'],
             },
             'opencode': {
                 binary: 'opencode',
                 name: 'OpenCode',
                 globalConfigs: ['~/.config/opencode'],
                 localConfigs: ['.opencode'],
-                globalSkills: ['~/.config/opencode/skills/respan/SKILL.md', '~/.agents/skills/respan/SKILL.md'],
-                localSkills: ['.opencode/skills/respan/SKILL.md', '.agents/skills/respan/SKILL.md'],
+                globalSkills: ['~/.agents/skills/respan/SKILL.md', '~/.config/opencode/skills/respan/SKILL.md'],
+                localSkills: ['.agents/skills/respan/SKILL.md', '.opencode/skills/respan/SKILL.md'],
             },
         };
         for (const [id, tool] of Object.entries(tools)) {
-            const binaryFound = this.isBinaryInstalled(tool.binary);
+            const binaryFound = isBinaryInstalled(tool.binary);
             this.log(`    ${BOLD}${tool.name}${RESET} ${DIM}(${tool.binary})${RESET}`);
             // Binary
             if (binaryFound) {
@@ -129,24 +125,22 @@ class SetupDoctor extends BaseCommand {
                     }
                 }
             }
-            // Skills
+            // Skills \u2014 each tool only lists dirs it actually reads (the shared
+            // ~/.agents, or ~/.claude for Claude Code) plus its own dir as a
+            // fallback. Report the first match.
             let hasSkill = false;
             if (checkGlobal) {
-                for (const skill of tool.globalSkills) {
-                    const resolved = expandHome(skill);
-                    if (fs.existsSync(resolved)) {
-                        this.log(`      ${GREEN}\u2713${RESET} Global skill: ${DIM}${skill}${RESET}`);
-                        hasSkill = true;
-                    }
+                const found = tool.globalSkills.find((skill) => fs.existsSync(expandHome(skill)));
+                if (found) {
+                    this.log(`      ${GREEN}\u2713${RESET} Global skill: ${DIM}${found}${RESET}`);
+                    hasSkill = true;
                 }
             }
             if (checkLocal) {
-                for (const skill of tool.localSkills) {
-                    const resolved = path.join(projectRoot, skill);
-                    if (fs.existsSync(resolved)) {
-                        this.log(`      ${GREEN}\u2713${RESET} Local skill: ${DIM}${skill}${RESET}`);
-                        hasSkill = true;
-                    }
+                const found = tool.localSkills.find((skill) => fs.existsSync(path.join(projectRoot, skill)));
+                if (found) {
+                    this.log(`      ${GREEN}\u2713${RESET} Local skill: ${DIM}${found}${RESET}`);
+                    hasSkill = true;
                 }
             }
             if (binaryFound && !hasSkill) {
@@ -193,15 +187,6 @@ class SetupDoctor extends BaseCommand {
         }
         this.log('');
     }
-    isBinaryInstalled(binary) {
-        try {
-            execSync(`command -v ${binary}`, { stdio: 'pipe' });
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
 }
 SetupDoctor.description = 'Diagnose coding-agent setup for Respan';
 SetupDoctor.examples = [

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

@@ -0,0 +1,16 @@
+import { SetupBaseCommand } from '../../lib/setup-base-command.js';
+export default class SetupGateway 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/gateway.js

@@ -0,0 +1,33 @@
+import { Flags } from '@oclif/core';
+import { SetupBaseCommand } from '../../lib/setup-base-command.js';
+class SetupGateway extends SetupBaseCommand {
+    async run() {
+        const { flags } = await this.parse(SetupGateway);
+        this.globalFlags = flags;
+        await this.runSetup('gateway', {
+            agent: flags.agent,
+            noInstrument: flags['no-instrument'],
+        });
+    }
+}
+SetupGateway.description = `Set up Respan gateway routing in this project.
+
+Runs the gateway 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 route the detected framework through the gateway.`;
+SetupGateway.examples = [
+    'respan setup gateway',
+    'respan setup gateway --agent claude-code',
+    'respan setup gateway --no-instrument',
+];
+SetupGateway.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 SetupGateway;

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

@@ -1,45 +1,16 @@
-import { BaseCommand } from '../../lib/base-command.js';
-export default class Setup extends BaseCommand {
+import { SetupBaseCommand } from '../../lib/setup-base-command.js';
+export default class Setup 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>;
-        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        csv: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
-    private askApiKey;
-    private verifyApiKey;
-    /**
-     * 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
-     */
-    private buildDemoTrace;
-    private detectAgents;
-    private selectAgent;
-    private installSkill;
-    private runInstrumentAgent;
-    private getSkillMd;
-    private logStep;
-    private isBinaryInstalled;
-    private extractEnvVar;
-    private saveToEnv;
-    private getGitEmail;
-    /**
-     * 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.
-     */
-    private notifySetup;
 }