@respan/cli 0.3.3 → 0.4.0

package/dist/commands/integrate/claude-code.d.ts

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

package/dist/commands/integrate/claude-code.js

@@ -0,0 +1,167 @@
+import * as fs from 'node:fs';
+import { execSync } from 'node:child_process';
+import { BaseCommand } from '../../lib/base-command.js';
+import { integrateFlags, deepMerge, readJsonFile, writeJsonFile, writeTextFile, expandHome, parseAttrs, getHookScript, resolveScope, findProjectRoot, DEFAULT_BASE_URL, } from '../../lib/integrate.js';
+class IntegrateClaudeCode extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(IntegrateClaudeCode);
+        this.globalFlags = flags;
+        try {
+            const apiKey = this.resolveApiKey();
+            const baseUrl = flags['base-url'];
+            const projectId = flags['project-id'];
+            const attrs = parseAttrs(flags.attrs);
+            const dryRun = flags['dry-run'];
+            // Claude Code default: both global + local
+            const scope = resolveScope(flags, 'both');
+            const doGlobal = scope === 'global' || scope === 'both';
+            const doLocal = scope === 'local' || scope === 'both';
+            // ── Global: hook script + registration ────────────────────────
+            if (doGlobal) {
+                // 1. Ensure Python 'requests' is available
+                if (!dryRun) {
+                    try {
+                        execSync('python3 -c "import requests"', { stdio: 'pipe' });
+                    }
+                    catch {
+                        this.log('Installing Python requests package...');
+                        try {
+                            execSync('pip3 install requests', { stdio: 'pipe' });
+                            this.log('Installed requests.');
+                        }
+                        catch {
+                            this.warn('Could not install Python requests package automatically.\n' +
+                                'Install it manually: pip3 install requests');
+                        }
+                    }
+                }
+                else {
+                    this.log('[dry-run] Would verify Python requests package');
+                }
+                // 2. Write hook script
+                const hookPath = expandHome('~/.respan/hook.py');
+                if (dryRun) {
+                    this.log(`[dry-run] Would write hook script to: ${hookPath}`);
+                }
+                else {
+                    writeTextFile(hookPath, getHookScript());
+                    fs.chmodSync(hookPath, 0o755);
+                    this.log(`Wrote hook script: ${hookPath}`);
+                }
+                // 3. Register Stop hook in global settings (no credentials here)
+                const globalSettingsPath = expandHome('~/.claude/settings.json');
+                const globalSettings = readJsonFile(globalSettingsPath);
+                const hookEntry = {
+                    matcher: '',
+                    hooks: [{ type: 'command', command: `python3 ${hookPath}` }],
+                };
+                const hooksSection = (globalSettings.hooks || {});
+                const stopHooks = Array.isArray(hooksSection.Stop)
+                    ? [...hooksSection.Stop]
+                    : [];
+                const existingIdx = stopHooks.findIndex((entry) => {
+                    const inner = Array.isArray(entry.hooks)
+                        ? entry.hooks
+                        : [];
+                    return inner.some((h) => typeof h.command === 'string' &&
+                        (h.command.includes('respan') || h.command.includes('hook.py')));
+                });
+                if (existingIdx >= 0) {
+                    stopHooks[existingIdx] = hookEntry;
+                }
+                else {
+                    stopHooks.push(hookEntry);
+                }
+                const mergedGlobal = deepMerge(globalSettings, {
+                    hooks: { ...hooksSection, Stop: stopHooks },
+                });
+                if (dryRun) {
+                    this.log(`[dry-run] Would update: ${globalSettingsPath}`);
+                    this.log(JSON.stringify(mergedGlobal, null, 2));
+                }
+                else {
+                    writeJsonFile(globalSettingsPath, mergedGlobal);
+                    this.log(`Updated global settings: ${globalSettingsPath}`);
+                }
+            }
+            // ── Local: credentials + enable in .claude/settings.local.json ─
+            if (doLocal) {
+                const projectRoot = findProjectRoot();
+                const localSettingsPath = `${projectRoot}/.claude/settings.local.json`;
+                const localSettings = readJsonFile(localSettingsPath);
+                const envBlock = {
+                    TRACE_TO_RESPAN: 'true',
+                    RESPAN_API_KEY: apiKey,
+                };
+                if (baseUrl !== DEFAULT_BASE_URL) {
+                    envBlock.RESPAN_BASE_URL = baseUrl;
+                }
+                const metadata = { ...attrs };
+                if (projectId) {
+                    metadata.project_id = projectId;
+                }
+                if (Object.keys(metadata).length > 0) {
+                    envBlock.RESPAN_METADATA = JSON.stringify(metadata);
+                }
+                const mergedLocal = deepMerge(localSettings, { env: envBlock });
+                if (dryRun) {
+                    this.log(`[dry-run] Would update: ${localSettingsPath}`);
+                    this.log(JSON.stringify(mergedLocal, null, 2));
+                }
+                else {
+                    writeJsonFile(localSettingsPath, mergedLocal);
+                    this.log(`Updated project settings: ${localSettingsPath}`);
+                }
+            }
+            // ── Done ──────────────────────────────────────────────────────
+            this.log('');
+            if (doGlobal && doLocal) {
+                this.log('Claude Code integration complete (global hook + project config).');
+            }
+            else if (doGlobal) {
+                this.log('Claude Code global hook installed.');
+                this.log('Run without --global in a project to enable tracing there.');
+            }
+            else {
+                this.log('Claude Code tracing enabled for this project.');
+            }
+            this.log('');
+            this.log('Set dynamic metadata before a session:');
+            this.log("  export RESPAN_METADATA='{\"task_id\":\"T-123\"}'");
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    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');
+    }
+}
+IntegrateClaudeCode.description = `Integrate Respan with Claude Code.
+
+Installs a Stop hook that reads conversation transcripts and sends
+them to Respan as structured spans (chat, tool, thinking).
+
+Scope:
+  --global   Install hook script + register in ~/.claude/settings.json
+  --local    Write credentials + enable flag to .claude/settings.local.json
+  (default)  Both: install hook globally + enable for current project`;
+IntegrateClaudeCode.examples = [
+    'respan integrate claude-code',
+    'respan integrate claude-code --global',
+    'respan integrate claude-code --local --project-id my-project',
+    'respan integrate claude-code --attrs \'{"env":"prod"}\'',
+    'respan integrate claude-code --dry-run',
+];
+IntegrateClaudeCode.flags = {
+    ...BaseCommand.baseFlags,
+    ...integrateFlags,
+};
+export default IntegrateClaudeCode;

package/dist/commands/integrate/codex-cli.d.ts

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

package/dist/commands/integrate/codex-cli.js

@@ -0,0 +1,97 @@
+import * as path from 'node:path';
+import { BaseCommand } from '../../lib/base-command.js';
+import { integrateFlags, readTextFile, writeTextFile, expandHome, parseAttrs, toOtelResourceAttrs, resolveScope, findProjectRoot, } from '../../lib/integrate.js';
+class IntegrateCodexCli extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(IntegrateCodexCli);
+        this.globalFlags = flags;
+        try {
+            const apiKey = this.resolveApiKey();
+            const baseUrl = (flags['base-url']).replace(/\/+$/, '');
+            const projectId = flags['project-id'];
+            const attrs = parseAttrs(flags.attrs);
+            const dryRun = flags['dry-run'];
+            const scope = resolveScope(flags, 'local');
+            // Resolve target config file
+            const configPath = scope === 'global'
+                ? expandHome('~/.codex/config.toml')
+                : path.join(findProjectRoot(), '.codex', 'config.toml');
+            const existing = readTextFile(configPath);
+            // Check for existing [otel] block
+            if (/^\[otel\]/m.test(existing)) {
+                this.warn(`[otel] section already exists in ${configPath} — skipping to avoid overwrite.`);
+                this.warn('Remove or rename the existing [otel] section and re-run to update.');
+                return;
+            }
+            // Build resource attributes
+            const resourceAttrs = {
+                'service.name': 'codex-cli',
+                ...attrs,
+            };
+            if (projectId) {
+                resourceAttrs['respan.project_id'] = projectId;
+            }
+            const otelResStr = toOtelResourceAttrs(resourceAttrs);
+            // Build TOML block
+            const lines = [
+                '',
+                '# Respan observability (added by respan integrate codex-cli)',
+                '[otel]',
+                `endpoint = "${baseUrl}/v2/traces"`,
+                `api_key = "${apiKey}"`,
+            ];
+            if (otelResStr) {
+                lines.push(`resource_attributes = "${otelResStr}"`);
+            }
+            lines.push('');
+            const block = lines.join('\n');
+            const updated = existing.trimEnd() + '\n' + block;
+            if (dryRun) {
+                this.log(`[dry-run] Would append to: ${configPath}`);
+                this.log(block);
+            }
+            else {
+                writeTextFile(configPath, updated);
+                this.log(`Updated config: ${configPath}`);
+            }
+            this.log('');
+            this.log(`Codex CLI integration complete (${scope}).`);
+            this.log('');
+            this.log('Set dynamic attributes before a session:');
+            this.log('  export OTEL_RESOURCE_ATTRIBUTES="env=prod,task_id=T-123"');
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    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');
+    }
+}
+IntegrateCodexCli.description = `Integrate Respan with Codex CLI.
+
+Codex CLI has native OTel traces (prompts, tool approvals, results)
+so we append an [otel] block to its TOML config.
+
+Scope:
+  --local    Write to .codex/config.toml in project root (default)
+  --global   Write to ~/.codex/config.toml
+  If [otel] already exists in the target file, warns and does not overwrite.`;
+IntegrateCodexCli.examples = [
+    'respan integrate codex-cli',
+    'respan integrate codex-cli --global',
+    'respan integrate codex-cli --project-id my-project --attrs \'{"env":"prod"}\'',
+    'respan integrate codex-cli --dry-run',
+];
+IntegrateCodexCli.flags = {
+    ...BaseCommand.baseFlags,
+    ...integrateFlags,
+};
+export default IntegrateCodexCli;

package/dist/commands/integrate/gemini-cli.d.ts

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

package/dist/commands/integrate/gemini-cli.js

@@ -0,0 +1,90 @@
+import * as path from 'node:path';
+import { BaseCommand } from '../../lib/base-command.js';
+import { integrateFlags, deepMerge, readJsonFile, writeJsonFile, expandHome, parseAttrs, toOtelResourceAttrs, resolveScope, findProjectRoot, } from '../../lib/integrate.js';
+class IntegrateGeminiCli extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(IntegrateGeminiCli);
+        this.globalFlags = flags;
+        try {
+            const apiKey = this.resolveApiKey();
+            const baseUrl = (flags['base-url']).replace(/\/+$/, '');
+            const projectId = flags['project-id'];
+            const attrs = parseAttrs(flags.attrs);
+            const dryRun = flags['dry-run'];
+            const scope = resolveScope(flags, 'local');
+            // Resolve target settings file
+            const settingsPath = scope === 'global'
+                ? expandHome('~/.gemini/settings.json')
+                : path.join(findProjectRoot(), '.gemini', 'settings.json');
+            const existing = readJsonFile(settingsPath);
+            // Build resource attributes
+            const resourceAttrs = {
+                'service.name': 'gemini-cli',
+                ...attrs,
+            };
+            if (projectId) {
+                resourceAttrs['respan.project_id'] = projectId;
+            }
+            const patch = {
+                telemetry: {
+                    enabled: true,
+                    otlpEndpoint: `${baseUrl}/v2/traces`,
+                    headers: {
+                        Authorization: `Bearer ${apiKey}`,
+                    },
+                },
+            };
+            const otelResStr = toOtelResourceAttrs(resourceAttrs);
+            if (otelResStr) {
+                patch.env = { OTEL_RESOURCE_ATTRIBUTES: otelResStr };
+            }
+            const merged = deepMerge(existing, patch);
+            if (dryRun) {
+                this.log(`[dry-run] Would update: ${settingsPath}`);
+                this.log(JSON.stringify(merged, null, 2));
+            }
+            else {
+                writeJsonFile(settingsPath, merged);
+                this.log(`Updated settings: ${settingsPath}`);
+            }
+            this.log('');
+            this.log(`Gemini CLI integration complete (${scope}).`);
+            this.log('');
+            this.log('Set dynamic attributes before a session:');
+            this.log('  export OTEL_RESOURCE_ATTRIBUTES="env=prod,task_id=T-123"');
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    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');
+    }
+}
+IntegrateGeminiCli.description = `Integrate Respan with Gemini CLI.
+
+Gemini CLI has native OTel traces (tool_call, llm_call, agent_call)
+so we configure it to send telemetry directly to the Respan OTLP
+endpoint.
+
+Scope:
+  --local    Write to .gemini/settings.json in project root (default)
+  --global   Write to ~/.gemini/settings.json`;
+IntegrateGeminiCli.examples = [
+    'respan integrate gemini-cli',
+    'respan integrate gemini-cli --global',
+    'respan integrate gemini-cli --project-id my-project --attrs \'{"env":"prod"}\'',
+    'respan integrate gemini-cli --dry-run',
+];
+IntegrateGeminiCli.flags = {
+    ...BaseCommand.baseFlags,
+    ...integrateFlags,
+};
+export default IntegrateGeminiCli;

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

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

package/dist/commands/integrate/opencode.js

@@ -0,0 +1,100 @@
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+import { BaseCommand } from '../../lib/base-command.js';
+import { integrateFlags, writeJsonFile, expandHome, parseAttrs, resolveScope, findProjectRoot, } from '../../lib/integrate.js';
+class IntegrateOpencode extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(IntegrateOpencode);
+        this.globalFlags = flags;
+        try {
+            const apiKey = this.resolveApiKey();
+            const baseUrl = (flags['base-url']).replace(/\/+$/, '');
+            const projectId = flags['project-id'];
+            const attrs = parseAttrs(flags.attrs);
+            const dryRun = flags['dry-run'];
+            const scope = resolveScope(flags, 'local');
+            // ── 1. Install opencode-otel (always global) ─────────────────
+            if (dryRun) {
+                this.log('[dry-run] Would run: npm install -g opencode-otel');
+            }
+            else {
+                this.log('Installing opencode-otel...');
+                try {
+                    execSync('npm install -g opencode-otel', { stdio: 'pipe' });
+                    this.log('Installed opencode-otel globally.');
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    this.warn(`Failed to install opencode-otel: ${msg}`);
+                    this.warn('You may need to install it manually: npm install -g opencode-otel');
+                }
+            }
+            // ── 2. Write plugin config ────────────────────────────────────
+            const pluginPath = scope === 'global'
+                ? expandHome('~/.config/opencode/plugins/otel.json')
+                : path.join(findProjectRoot(), '.opencode', 'plugins', 'otel.json');
+            const resourceAttrs = {
+                'service.name': 'opencode',
+                ...attrs,
+            };
+            if (projectId) {
+                resourceAttrs['respan.project_id'] = projectId;
+            }
+            const pluginConfig = {
+                tracesEndpoint: `${baseUrl}/v2/traces`,
+                logsEndpoint: `${baseUrl}/v2/logs`,
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                resourceAttributes: resourceAttrs,
+            };
+            if (dryRun) {
+                this.log(`[dry-run] Would write: ${pluginPath}`);
+                this.log(JSON.stringify(pluginConfig, null, 2));
+            }
+            else {
+                writeJsonFile(pluginPath, pluginConfig);
+                this.log(`Wrote plugin config: ${pluginPath}`);
+            }
+            // ── Done ──────────────────────────────────────────────────────
+            this.log('');
+            this.log(`OpenCode integration complete (${scope}).`);
+            this.log('');
+            this.log('Set dynamic attributes before a session:');
+            this.log('  export OTEL_RESOURCE_ATTRIBUTES="env=prod,task_id=T-123"');
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    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');
+    }
+}
+IntegrateOpencode.description = `Integrate Respan with OpenCode.
+
+OpenCode's built-in OTel does not work reliably, so this uses the
+community opencode-otel plugin instead.
+
+Scope:
+  --local    Write plugin config to project root (default)
+  --global   Write to ~/.config/opencode/plugins/otel.json
+  The opencode-otel package is always installed globally.`;
+IntegrateOpencode.examples = [
+    'respan integrate opencode',
+    'respan integrate opencode --global',
+    'respan integrate opencode --project-id my-project --attrs \'{"env":"prod"}\'',
+    'respan integrate opencode --dry-run',
+];
+IntegrateOpencode.flags = {
+    ...BaseCommand.baseFlags,
+    ...integrateFlags,
+};
+export default IntegrateOpencode;

package/dist/lib/integrate.d.ts

@@ -0,0 +1,51 @@
+/** Default Respan API base (SaaS). Enterprise users override this. */
+export declare const DEFAULT_BASE_URL = "https://api.respan.ai/api";
+export declare const integrateFlags: {
+    local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    global: 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>;
+    'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+export type Scope = 'local' | 'global' | 'both';
+/**
+ * Resolve whether to write local, global, or both configs.
+ *
+ * - `--global` → 'global'
+ * - `--local`  → 'local'
+ * - neither    → tool-specific default (passed by each command)
+ */
+export declare function resolveScope(flags: {
+    local: boolean;
+    global: boolean;
+}, defaultScope?: Scope): Scope;
+/**
+ * Find the project root (git root, or cwd if not in a repo).
+ */
+export declare function findProjectRoot(): string;
+/**
+ * Return the bundled Claude Code hook script contents.
+ *
+ * The .py file lives in src/assets/ and is copied to dist/assets/ during
+ * build.  Reading at runtime keeps the hook version-locked to the CLI
+ * version — upgrading the CLI and re-running integrate updates the hook.
+ */
+export declare function getHookScript(): string;
+/**
+ * Deep merge source into target.
+ * Objects are recursively merged; arrays and primitives from source overwrite.
+ */
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+export declare function ensureDir(dirPath: string): void;
+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;
+export declare function expandHome(p: string): string;
+export declare function parseAttrs(raw: string): Record<string, string>;
+/**
+ * Convert a Record to OTel resource attributes string.
+ * Format: key1=value1,key2=value2
+ */
+export declare function toOtelResourceAttrs(attrs: Record<string, string>): string;