@respan/cli 0.13.3 → 0.14.0

package/dist/commands/collector/config.d.ts

@@ -0,0 +1,21 @@
+import { BaseCommand } from '../../lib/base-command.js';
+export default class CollectorConfig extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        print: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'export-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'data-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'max-size-mib': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'queue-size': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        port: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        '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>;
+}

package/dist/commands/collector/config.js

@@ -0,0 +1,73 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../lib/base-command.js';
+import { expandHome, writeTextFile } from '../../lib/integrate.js';
+import { COLLECTOR_VERSION, buildCollectorConfig, collectorBaseUrl, collectorPaths, } from '../../lib/collector.js';
+import { collectorSizingFlags, resolveExportUrl } from '../../lib/collector-runtime.js';
+class CollectorConfig extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(CollectorConfig);
+        this.globalFlags = flags;
+        try {
+            const paths = collectorPaths();
+            const exportUrl = resolveExportUrl(flags);
+            const dataDir = expandHome(flags['data-dir'] ?? paths.dataDir);
+            const yaml = buildCollectorConfig({
+                exportUrl,
+                dataDir,
+                maxSizeBytes: flags['max-size-mib'] * 1024 * 1024,
+                queueSize: flags['queue-size'],
+                listen: `127.0.0.1:${flags.port}`,
+            });
+            if (flags.print) {
+                process.stdout.write(yaml);
+                return;
+            }
+            const output = expandHome(flags.output ?? paths.configPath);
+            writeTextFile(output, yaml);
+            this.log(`Wrote collector config: ${output}`);
+            this.log('');
+            this.log(`Export URL:   ${exportUrl}`);
+            this.log(`Queue dir:    ${dataDir}`);
+            this.log(`Queue limits: ${flags['max-size-mib']} MiB on disk, ${flags['queue-size']} batches`);
+            this.log('');
+            this.log('Run it:');
+            this.log('  respan collector start');
+            this.log(`  # or: RESPAN_API_KEY=... otelcol-contrib --config ${output}`);
+            this.log('');
+            this.log('Point the SDK at the collector:');
+            this.log(`  export RESPAN_BASE_URL=${collectorBaseUrl(flags.port)}`);
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+}
+CollectorConfig.description = `Write the Respan collector configuration.
+
+The Respan collector is the upstream OpenTelemetry Collector (contrib
+${COLLECTOR_VERSION}) with a config that receives OTLP/HTTP from the Respan SDKs
+on localhost and forwards it to Respan through a bounded, persistent
+(write-ahead-log) queue — spans survive Respan outages and collector
+restarts without unbounded local growth.
+
+The written file never contains your API key: it reads RESPAN_API_KEY from
+the environment. Use "respan collector start" to run it, or run
+otelcol-contrib yourself with --config <file>.`;
+CollectorConfig.examples = [
+    'respan collector config',
+    'respan collector config --print',
+    'respan collector config --output ./collector.yaml --max-size-mib 1024',
+    'respan collector config --export-url https://respan.internal/api/v2/traces',
+];
+CollectorConfig.flags = {
+    ...BaseCommand.baseFlags,
+    ...collectorSizingFlags,
+    output: Flags.string({
+        description: 'Where to write the config (default: ~/.respan/collector/config.yaml)',
+    }),
+    print: Flags.boolean({
+        description: 'Print the config to stdout instead of writing it',
+        default: false,
+    }),
+};
+export default CollectorConfig;

package/dist/commands/collector/start.d.ts

@@ -0,0 +1,26 @@
+import { BaseCommand } from '../../lib/base-command.js';
+export default class CollectorStart extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'export-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'data-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'max-size-mib': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'queue-size': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        port: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        docker: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        binary: 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>;
+    /** Poll the health endpoint behind a spinner that fails visibly on timeout / exit. */
+    private awaitHealth;
+    private printStarted;
+    private resolveApiKey;
+}

package/dist/commands/collector/start.js

@@ -0,0 +1,198 @@
+import * as fs from 'node:fs';
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../lib/base-command.js';
+import { ensureDir, expandHome, writeTextFile } from '../../lib/integrate.js';
+import { COLLECTOR_IMAGE, CONTAINER_NAME, DEFAULT_HEALTH_PORT, VOLUME_NAME, binaryDownloadUrl, buildCollectorConfig, collectorBaseUrl, collectorPaths, dockerRunArgs, dockerVolumeInitArgs, } from '../../lib/collector.js';
+import { checkHealth, collectorModeFlags, collectorSizingFlags, detectRunning, dockerAvailable, dockerVolumeExists, ensureCollectorBinary, healthUrl, isPidAlive, metricsUrl, resolveExportUrl, runDocker, spawnCollectorBinary, tailFile, waitForHealth, } from '../../lib/collector-runtime.js';
+const HEALTH_TIMEOUT_MS = 20000;
+class CollectorStart extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(CollectorStart);
+        this.globalFlags = flags;
+        try {
+            const dryRun = flags['dry-run'];
+            const apiKey = this.resolveApiKey();
+            const paths = collectorPaths();
+            let mode;
+            if (flags.docker) {
+                if (!dockerAvailable()) {
+                    this.error('Docker is not available (`docker info` failed). Start Docker or use --binary.');
+                }
+                mode = 'docker';
+            }
+            else if (flags.binary) {
+                mode = 'binary';
+            }
+            else {
+                mode = dockerAvailable() ? 'docker' : 'binary';
+            }
+            // ── Refuse to double-start ────────────────────────────────────
+            const running = detectRunning(paths);
+            if (running?.mode === 'docker') {
+                const status = running.container?.status ?? 'unknown';
+                this.error(`Container ${CONTAINER_NAME} already exists (${status}). ` +
+                    'Run `respan collector stop` first' +
+                    (status === 'running' ? '.' : `, or resume it with \`docker start ${CONTAINER_NAME}\`.`));
+            }
+            if (running?.mode === 'binary') {
+                this.error(`The collector is already running (pid ${running.pid}). ` +
+                    'See `respan collector status` or stop it with `respan collector stop`.');
+            }
+            if (!dryRun && (await checkHealth()).healthy) {
+                this.error(`Something already answers on ${healthUrl()} (another collector?) but was not started by this CLI. ` +
+                    'Stop it before starting a new one.');
+            }
+            const exportUrl = resolveExportUrl(flags);
+            const port = flags.port;
+            const maxSizeBytes = flags['max-size-mib'] * 1024 * 1024;
+            const queueSize = flags['queue-size'];
+            const dataDir = expandHome(flags['data-dir'] ?? paths.dataDir);
+            const env = { ...process.env, RESPAN_API_KEY: apiKey };
+            if (mode === 'docker') {
+                // Everything is passed as container env; the mounted file is the pure template.
+                const yaml = buildCollectorConfig();
+                const runArgs = dockerRunArgs({ configPath: paths.configPath, port, exportUrl, maxSizeBytes, queueSize });
+                const needsVolume = !dockerVolumeExists();
+                if (flags['data-dir']) {
+                    this.warn(`--data-dir is ignored in docker mode; the queue lives in the ${VOLUME_NAME} volume.`);
+                }
+                if (dryRun) {
+                    this.log('[dry-run] Mode: docker');
+                    this.log(`[dry-run] Would write: ${paths.configPath}`);
+                    if (needsVolume) {
+                        this.log(`[dry-run] Would run: docker ${dockerVolumeInitArgs().join(' ')}`);
+                    }
+                    this.log(`[dry-run] Would run: RESPAN_API_KEY=*** docker ${runArgs.join(' ')}`);
+                    this.log(`[dry-run] Would wait for ${healthUrl()}`);
+                    return;
+                }
+                writeTextFile(paths.configPath, yaml);
+                this.log(`Wrote collector config: ${paths.configPath}`);
+                if (needsVolume) {
+                    const init = await this.spin(`Creating volume ${VOLUME_NAME}`, () => runDocker(dockerVolumeInitArgs()));
+                    if (init.status !== 0) {
+                        this.error(`Failed to prepare volume ${VOLUME_NAME}: ${init.stderr.trim()}`);
+                    }
+                }
+                const started = await this.spin(`Starting ${CONTAINER_NAME} (${COLLECTOR_IMAGE})`, () => runDocker(runArgs, env));
+                if (started.status !== 0) {
+                    this.error(`docker run failed: ${started.stderr.trim()}`);
+                }
+                const health = await this.awaitHealth();
+                if (!health.healthy) {
+                    this.warn(`Collector is not healthy yet (${health.error ?? health.status}). ` +
+                        `Check \`docker logs ${CONTAINER_NAME}\` or \`respan collector status\`.`);
+                }
+                this.printStarted(mode, health, port, exportUrl);
+                return;
+            }
+            // ── Binary mode ───────────────────────────────────────────────
+            const yaml = buildCollectorConfig({ exportUrl, dataDir, maxSizeBytes, queueSize, listen: `127.0.0.1:${port}` });
+            if (dryRun) {
+                this.log('[dry-run] Mode: binary');
+                if (!fs.existsSync(paths.binaryPath)) {
+                    this.log(`[dry-run] Would download ${binaryDownloadUrl()} to ${paths.binDir}`);
+                }
+                this.log(`[dry-run] Would write: ${paths.configPath}  (preview: respan collector config --print)`);
+                this.log(`[dry-run] Would run: RESPAN_API_KEY=*** ${paths.binaryPath} --config ${paths.configPath}`);
+                this.log(`[dry-run]   detached; log: ${paths.logPath}; pid file: ${paths.pidPath}`);
+                this.log(`[dry-run] Would wait for ${healthUrl()}`);
+                return;
+            }
+            await ensureCollectorBinary(paths, this);
+            writeTextFile(paths.configPath, yaml);
+            this.log(`Wrote collector config: ${paths.configPath}`);
+            ensureDir(dataDir);
+            const pid = spawnCollectorBinary(paths, env);
+            this.log(`Started otelcol-contrib (pid ${pid}); log: ${paths.logPath}`);
+            const health = await this.awaitHealth(() => isPidAlive(pid));
+            if (!health.healthy) {
+                if (!isPidAlive(pid)) {
+                    fs.rmSync(paths.pidPath, { force: true });
+                    this.error(`The collector exited during startup. Last lines of ${paths.logPath}:\n${tailFile(paths.logPath, 15)}`);
+                }
+                this.warn(`Collector is not healthy yet (${health.error ?? health.status}). ` +
+                    `Check ${paths.logPath} or \`respan collector status\`.`);
+            }
+            this.printStarted(mode, health, port, exportUrl);
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /** Poll the health endpoint behind a spinner that fails visibly on timeout / exit. */
+    async awaitHealth(isAlive) {
+        let unhealthy;
+        try {
+            return await this.spin('Waiting for the collector to become healthy', async () => {
+                const health = await waitForHealth(DEFAULT_HEALTH_PORT, HEALTH_TIMEOUT_MS, isAlive);
+                if (!health.healthy) {
+                    unhealthy = health;
+                    throw new Error(health.error ?? health.status ?? 'unhealthy');
+                }
+                return health;
+            });
+        }
+        catch (error) {
+            if (unhealthy)
+                return unhealthy;
+            throw error;
+        }
+    }
+    printStarted(mode, health, port, exportUrl) {
+        this.log('');
+        this.log(`Collector ${health.healthy ? 'is healthy' : 'started'} (${mode}).`);
+        this.log(`  Receiver: ${collectorBaseUrl(port)}/api/v2/traces`);
+        this.log(`  Health:   ${healthUrl()}`);
+        this.log(`  Metrics:  ${metricsUrl()}`);
+        this.log(`  Export:   ${exportUrl}`);
+        this.log('');
+        this.log('Point the SDK at the collector:');
+        this.log(`  export RESPAN_BASE_URL=${collectorBaseUrl(port)}`);
+        this.log('');
+        this.log('Check / stop:');
+        this.log('  respan collector status');
+        this.log('  respan collector stop');
+    }
+    resolveApiKey() {
+        const auth = this.getAuth();
+        if (auth.apiKey)
+            return auth.apiKey;
+        if (auth.accessToken) {
+            this.warn('Using access token (JWT) which may expire. Consider using an API key instead.');
+            return auth.accessToken;
+        }
+        this.error('No API key found. Pass --api-key, set RESPAN_API_KEY, or run: respan auth login');
+    }
+}
+CollectorStart.description = `Start a local Respan collector.
+
+Runs the OpenTelemetry Collector (contrib) with the Respan config: the SDKs
+send to http://127.0.0.1:4318, and the collector forwards to Respan through
+a bounded, persistent queue so traces survive outages and restarts.
+
+Modes:
+  --docker   docker run otel/opentelemetry-collector-contrib with the queue in
+             the ${VOLUME_NAME} volume (default when Docker is available)
+  --binary   download otelcol-contrib to ~/.respan/collector/bin and run it
+             detached, logging to ~/.respan/collector/collector.log
+
+The API key is passed to the collector through its environment only; the
+config file never contains it.`;
+CollectorStart.examples = [
+    'respan collector start',
+    'respan collector start --binary',
+    'respan collector start --docker --max-size-mib 1024 --queue-size 20000',
+    'respan collector start --export-url https://respan.internal/api/v2/traces',
+    'respan collector start --dry-run',
+];
+CollectorStart.flags = {
+    ...BaseCommand.baseFlags,
+    ...collectorModeFlags,
+    ...collectorSizingFlags,
+    'dry-run': Flags.boolean({
+        description: 'Show what would be done without starting anything',
+        default: false,
+    }),
+};
+export default CollectorStart;

package/dist/commands/collector/status.d.ts

@@ -0,0 +1,17 @@
+import { BaseCommand } from '../../lib/base-command.js';
+export default class CollectorStatus extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        port: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        docker: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        binary: 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>;
+}

package/dist/commands/collector/status.js

@@ -0,0 +1,113 @@
+import * as fs from 'node:fs';
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../lib/base-command.js';
+import { GREEN, RED, YELLOW, DIM, RESET } from '../../lib/colors.js';
+import { CONTAINER_NAME, DEFAULT_COLLECTOR_PORT, VOLUME_NAME, collectorBaseUrl, collectorPaths, formatBytes, } from '../../lib/collector.js';
+import { checkHealth, collectorModeFlags, detectRunning, directorySize, fetchMetrics, healthUrl, metricsUrl, } from '../../lib/collector-runtime.js';
+class CollectorStatus extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(CollectorStatus);
+        this.globalFlags = flags;
+        try {
+            const paths = collectorPaths();
+            const mode = flags.docker ? 'docker' : flags.binary ? 'binary' : undefined;
+            const running = detectRunning(paths, mode);
+            const health = await checkHealth();
+            const metrics = await fetchMetrics();
+            const dataDirBytes = fs.existsSync(paths.dataDir) ? directorySize(paths.dataDir) : undefined;
+            const isRunning = running?.mode === 'docker' ? Boolean(running.container?.running) : Boolean(running);
+            const result = {
+                mode: running?.mode ?? null,
+                running: isRunning,
+                healthy: health.healthy,
+                health,
+                container: running?.container ?? null,
+                pid: running?.pid ?? null,
+                metrics: metrics ?? null,
+                dataDir: running?.mode === 'docker' ? null : paths.dataDir,
+                dataDirBytes: running?.mode === 'docker' ? null : dataDirBytes ?? null,
+                volume: running?.mode === 'docker' ? VOLUME_NAME : null,
+                configPath: paths.configPath,
+                logPath: running?.mode === 'binary' ? paths.logPath : null,
+                baseUrl: collectorBaseUrl(flags.port),
+            };
+            if (flags.json) {
+                this.outputResult(result);
+                return;
+            }
+            const ok = `${GREEN}✓${RESET}`;
+            const bad = `${RED}✗${RESET}`;
+            const warn = `${YELLOW}!${RESET}`;
+            this.log('');
+            if (running?.mode === 'docker' && running.container) {
+                const c = running.container;
+                const mark = c.running ? ok : bad;
+                this.log(`  ${mark} Mode:    docker (container ${CONTAINER_NAME}: ${c.status}${c.restartCount ? `, ${c.restartCount} restarts` : ''})`);
+                if (c.running && c.startedAt)
+                    this.log(`    Started: ${c.startedAt}`);
+                if (!c.running)
+                    this.log(`    ${DIM}Resume with: docker start ${CONTAINER_NAME}  (or respan collector stop && respan collector start)${RESET}`);
+            }
+            else if (running?.mode === 'binary') {
+                this.log(`  ${ok} Mode:    binary (pid ${running.pid})`);
+                this.log(`    Log:     ${paths.logPath}`);
+            }
+            else {
+                this.log(`  ${bad} Mode:    not running`);
+                this.log(`    ${DIM}Start with: respan collector start${RESET}`);
+            }
+            if (health.healthy) {
+                this.log(`  ${ok} Health:  ${health.status}${health.uptime ? ` (up ${health.uptime})` : ''}  ${DIM}${healthUrl()}${RESET}`);
+            }
+            else {
+                this.log(`  ${bad} Health:  ${health.error ?? health.status ?? 'unreachable'}  ${DIM}${healthUrl()}${RESET}`);
+            }
+            if (metrics) {
+                const queueMark = metrics.queueSize > 0 ? warn : ok;
+                this.log(`  ${queueMark} Queue:   ${metrics.queueSize} / ${metrics.queueCapacity} batches waiting  ${DIM}${metricsUrl()}${RESET}`);
+                this.log(`    Spans:   sent ${metrics.sentSpans}, enqueue-failed ${metrics.enqueueFailedSpans}, send-failed ${metrics.sendFailedSpans}`);
+                if (metrics.enqueueFailedSpans > 0) {
+                    this.log(`    ${warn} ${metrics.enqueueFailedSpans} spans were dropped because the queue was full (raise --max-size-mib / --queue-size).`);
+                }
+                if (metrics.sendFailedSpans > 0) {
+                    this.log(`    ${warn} ${metrics.sendFailedSpans} spans were rejected by Respan (check the API key and export URL).`);
+                }
+            }
+            else {
+                this.log(`  ${DIM}  Metrics: unavailable (${metricsUrl()})${RESET}`);
+            }
+            if (running?.mode === 'docker') {
+                this.log(`    Queue:   docker volume ${VOLUME_NAME}`);
+            }
+            else if (dataDirBytes !== undefined) {
+                this.log(`    Queue:   ${paths.dataDir} (${formatBytes(dataDirBytes)})`);
+            }
+            this.log(`    Config:  ${paths.configPath}${fs.existsSync(paths.configPath) ? '' : ` ${DIM}(not written yet)${RESET}`}`);
+            this.log('');
+            this.log(`  SDK: export RESPAN_BASE_URL=${collectorBaseUrl(flags.port)}`);
+            this.log('');
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+}
+CollectorStatus.description = `Show the local Respan collector's health and queue.
+
+Reports how the collector is running (Docker container or binary), the
+health_check result, and the exporter metrics that matter for delivery:
+queued batches, spans sent, spans dropped because the queue was full
+(enqueue-failed) and spans rejected by Respan (send-failed).`;
+CollectorStatus.examples = [
+    'respan collector status',
+    'respan collector status --json',
+];
+CollectorStatus.flags = {
+    ...BaseCommand.baseFlags,
+    ...collectorModeFlags,
+    port: Flags.integer({
+        description: 'Local OTLP/HTTP port used in the SDK hint',
+        default: DEFAULT_COLLECTOR_PORT,
+    }),
+};
+export default CollectorStatus;

package/dist/commands/collector/stop.d.ts

@@ -0,0 +1,18 @@
+import { BaseCommand } from '../../lib/base-command.js';
+export default class CollectorStop extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        purge: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        docker: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        binary: 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>;
+}

package/dist/commands/collector/stop.js

@@ -0,0 +1,91 @@
+import * as fs from 'node:fs';
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../lib/base-command.js';
+import { CONTAINER_NAME, VOLUME_NAME, collectorPaths } from '../../lib/collector.js';
+import { collectorModeFlags, detectRunning, dockerVolumeExists, runDocker, stopPid, } from '../../lib/collector-runtime.js';
+class CollectorStop extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(CollectorStop);
+        this.globalFlags = flags;
+        try {
+            if (flags.purge && !flags.yes) {
+                this.error('--purge deletes any spans still queued for delivery. Re-run with --yes to confirm.');
+            }
+            const paths = collectorPaths();
+            const mode = flags.docker ? 'docker' : flags.binary ? 'binary' : undefined;
+            const running = detectRunning(paths, mode);
+            let stopped = false;
+            if (running?.mode === 'docker') {
+                const result = await runDocker(['rm', '-f', CONTAINER_NAME]);
+                if (result.status !== 0) {
+                    this.error(`Failed to remove container ${CONTAINER_NAME}: ${result.stderr.trim()}`);
+                }
+                this.log(`Removed container ${CONTAINER_NAME}.`);
+                stopped = true;
+            }
+            else if (running?.mode === 'binary' && running.pid !== undefined) {
+                const outcome = await stopPid(running.pid);
+                fs.rmSync(paths.pidPath, { force: true });
+                if (outcome === 'killed') {
+                    this.log(`Collector (pid ${running.pid}) did not exit after SIGTERM; killed it.`);
+                }
+                else {
+                    this.log(`Stopped collector (pid ${running.pid}).`);
+                }
+                stopped = true;
+            }
+            else {
+                this.log('The collector is not running.');
+            }
+            if (flags.purge) {
+                let purged = false;
+                if (mode !== 'binary' && dockerVolumeExists()) {
+                    const result = await runDocker(['volume', 'rm', VOLUME_NAME]);
+                    if (result.status === 0) {
+                        this.log(`Removed volume ${VOLUME_NAME}.`);
+                        purged = true;
+                    }
+                    else {
+                        this.warn(`Failed to remove volume ${VOLUME_NAME}: ${result.stderr.trim()}`);
+                    }
+                }
+                if (mode !== 'docker' && fs.existsSync(paths.dataDir)) {
+                    fs.rmSync(paths.dataDir, { recursive: true, force: true });
+                    this.log(`Removed queue directory ${paths.dataDir}.`);
+                    purged = true;
+                }
+                if (!purged)
+                    this.log('No queued data to remove.');
+            }
+            else if (stopped) {
+                this.log('Queued spans are kept on disk and will be delivered when the collector starts again.');
+                this.log('To delete them: respan collector stop --purge --yes');
+            }
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+}
+CollectorStop.description = `Stop the local Respan collector.
+
+Removes the ${CONTAINER_NAME} container or stops the detached binary. Spans
+still queued on disk are kept and delivered the next time the collector
+starts; pass --purge --yes to delete them.`;
+CollectorStop.examples = [
+    'respan collector stop',
+    'respan collector stop --purge --yes',
+];
+CollectorStop.flags = {
+    ...BaseCommand.baseFlags,
+    ...collectorModeFlags,
+    purge: Flags.boolean({
+        description: `Also delete the queued data (the ${VOLUME_NAME} volume / data dir). Requires --yes`,
+        default: false,
+    }),
+    yes: Flags.boolean({
+        description: 'Confirm deleting queued spans with --purge',
+        default: false,
+    }),
+};
+export default CollectorStop;

package/dist/commands/integrate/pi.d.ts

@@ -0,0 +1,28 @@
+import { BaseCommand } from '../../lib/base-command.js';
+export default class IntegratePi extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'workflow-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'span-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'trace-scope': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'with-collector': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'collector-port': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        enable: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        disable: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'project-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        attrs: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'customer-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'api-key': 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 resolveApiKey;
+}