@ai-setting/roy-agent-cli 1.3.19 → 1.3.22

package/dist/core/src/env/log-trace/opentelemetry/propagation-env.js

@@ -1,109 +0,0 @@
-/**
- * @fileoverview Propagation Env Module
- *
- * 提供便捷的环境变量注入功能，用于在子进程执行时传递 trace context。
- *
- * @example
- * ```typescript
- * import { injectToEnv, injectToEnvWithContext } from "./propagation-env.js";
- *
- * // 在 Bash 工具中执行子进程前：
- * const traceEnv = injectToEnv();  // 从当前 OTelTracerProvider 获取并注入
- * const options = {
- *   env: { ...process.env, ...traceEnv, ...env },
- * };
- * spawn(command, args, options);
- * ```
- */
-import { propagation } from "./propagation.js";
-import { getTracerProvider } from "./tracer-provider.js";
-// ============================================================================
-// Core Functions
-// ============================================================================
-/**
- * 从当前 OTelTracerProvider 获取上下文并注入到环境变量
- *
- * 这是一个便捷函数，封装了常见的注入模式：
- * 1. 从全局 TracerProvider 获取当前 Tracer
- * 2. 获取当前 span context
- * 3. 注入到目标环境变量
- *
- * @param env 目标环境变量对象（默认：{}）
- * @returns 注入了 TRACEPARENT 的环境变量对象
- *
- * @example
- * ```typescript
- * const env = injectToEnv({ PATH: '/usr/bin' });
- * // env.TRACEPARENT = '00-{traceId}-{spanId}-01'
- * // env.PATH = '/usr/bin'
- * ```
- */
-export function injectToEnv(env = {}) {
-    const provider = getTracerProvider();
-    // 如果 provider 未初始化，尝试获取 tracer（可能会自动初始化）
-    const tracer = provider.getTracer('roy-tracer');
-    tracer.injectToEnv(env);
-    return env;
-}
-/**
- * 将指定的 SpanContext 直接注入到环境变量
- *
- * 与 injectToEnv 不同，这个函数不需要访问全局 TracerProvider，
- * 直接使用传入的 SpanContext 进行注入。
- *
- * @param env 目标环境变量对象
- * @param context 要注入的 SpanContext
- * @returns 注入了 TRACEPARENT 的环境变量对象
- *
- * @example
- * ```typescript
- * const span = tracer.startSpan('my-span');
- * const env = injectToEnvWithContext({}, span.spanContext);
- * ```
- */
-export function injectToEnvWithContext(env, context) {
-    propagation.inject(env, context);
-    return env;
-}
-/**
- * 从源环境变量 carrier 复制 TRACEPARENT 到目标 carrier
- *
- * 用于将一个环境变量对象中的 trace context 传递到另一个：
- * - 从 process.env 复制到子进程的环境变量
- * - 从父进程环境变量复制到子进程环境变量
- *
- * @param target 目标 carrier（将被修改）
- * @param source 源 carrier
- * @returns 目标 carrier
- *
- * @example
- * ```typescript
- * // 在 fork 子进程时继承父进程的 trace context
- * const childEnv = injectToEnvFromCarrier({}, process.env);
- * ```
- */
-export function injectToEnvFromCarrier(target, source) {
-    const extracted = propagation.extract(source);
-    if (extracted) {
-        // 将提取的上下文重新注入到目标
-        // ExtractedContext 包含发送方的 traceId 和 spanId
-        // 需要构造新的 SpanContext 用于传播
-        const context = {
-            traceId: extracted.traceId,
-            spanId: extracted.spanId, // 使用发送方的 spanId
-            parentSpanId: undefined, // 新的 span 将作为根 span（但会继承 traceId）
-        };
-        propagation.inject(target, context);
-    }
-    return target;
-}
-// ============================================================================
-// Utility Functions
-// ============================================================================
-/**
- * 获取 TRACEPARENT 字段名
- */
-export function getTraceparentHeader() {
-    return propagation.getTraceparentHeader();
-}
-//# sourceMappingURL=propagation-env.js.map

package/dist/core/src/env/log-trace/opentelemetry/propagation-env.test.d.ts

@@ -1,9 +0,0 @@
-/**
- * @fileoverview Propagation Env 测试
- *
- * 测试 propagation-env 模块：
- * - injectToEnv: 从当前 OTelTracerProvider 获取上下文并注入环境变量
- * - injectToEnvWithContext: 直接注入指定 SpanContext
- */
-export {};
-//# sourceMappingURL=propagation-env.test.d.ts.map

package/dist/core/src/env/log-trace/opentelemetry/propagation-env.test.js

@@ -1,143 +0,0 @@
-/**
- * @fileoverview Propagation Env 测试
- *
- * 测试 propagation-env 模块：
- * - injectToEnv: 从当前 OTelTracerProvider 获取上下文并注入环境变量
- * - injectToEnvWithContext: 直接注入指定 SpanContext
- */
-import { describe, test, expect, beforeEach, vi } from 'bun:test';
-import { injectToEnv, injectToEnvWithContext, injectToEnvFromCarrier, } from "./propagation-env.js";
-import { propagation } from "./propagation.js";
-// Mock the tracer-provider module
-const mockInjectToEnv = vi.fn();
-const mockGetCurrentContext = vi.fn();
-vi.mock('./tracer-provider', () => ({
-    getTracerProvider: vi.fn().mockReturnValue({
-        getTracer: vi.fn().mockReturnValue({
-            injectToEnv: mockInjectToEnv,
-            getCurrentContext: mockGetCurrentContext,
-        }),
-        isInitialized: vi.fn().mockReturnValue(true),
-    }),
-}));
-describe('propagation-env', () => {
-    beforeEach(() => {
-        vi.clearAllMocks();
-    });
-    describe('injectToEnv', () => {
-        test('should inject TRACEPARENT to provided env object', async () => {
-            // Create a mock tracer with current context
-            const mockSpanContext = {
-                traceId: '0af7651916cd43dd8448eb211c80319c',
-                spanId: 'b7ad6b7169203331',
-                parentSpanId: undefined,
-            };
-            mockGetCurrentContext.mockReturnValue(mockSpanContext);
-            mockInjectToEnv.mockImplementation((env) => {
-                env['TRACEPARENT'] = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
-            });
-            const env = {};
-            injectToEnv(env);
-            expect(env['TRACEPARENT']).toBeDefined();
-            expect(env['TRACEPARENT']).toMatch(/^00-[0-9a-f]{32}-[0-9a-f]{16}-01$/);
-        });
-        test('should not inject if no current context', () => {
-            mockGetCurrentContext.mockReturnValue(undefined);
-            mockInjectToEnv.mockImplementation((_env) => { });
-            const env = {};
-            injectToEnv(env);
-            // injectToEnv should not set TRACEPARENT when no context
-            expect(mockInjectToEnv).toHaveBeenCalledWith(env);
-        });
-        test('should preserve existing env variables', () => {
-            const mockSpanContext = {
-                traceId: '0af7651916cd43dd8448eb211c80319c',
-                spanId: 'b7ad6b7169203331',
-                parentSpanId: undefined,
-            };
-            mockGetCurrentContext.mockReturnValue(mockSpanContext);
-            mockInjectToEnv.mockImplementation((env) => {
-                env['TRACEPARENT'] = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
-            });
-            const env = {
-                HOME: '/home/user',
-                PATH: '/usr/bin',
-                CUSTOM_VAR: 'custom-value',
-            };
-            injectToEnv(env);
-            expect(env['HOME']).toBe('/home/user');
-            expect(env['PATH']).toBe('/usr/bin');
-            expect(env['CUSTOM_VAR']).toBe('custom-value');
-            expect(env['TRACEPARENT']).toBeDefined();
-        });
-    });
-    describe('injectToEnvWithContext', () => {
-        test('should inject given SpanContext to env', () => {
-            const context = {
-                traceId: '0af7651916cd43dd8448eb211c80319c',
-                spanId: 'b7ad6b7169203331',
-                parentSpanId: 'a1b2c3d4e5f67890',
-            };
-            const env = {};
-            injectToEnvWithContext(env, context);
-            // 验证 propagation.inject 被正确调用
-            expect(env['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
-        });
-        test('should inject traceparent format correctly', () => {
-            const context = {
-                traceId: '0af7651916cd43dd8448eb211c80319c',
-                spanId: 'b7ad6b7169203331',
-                parentSpanId: undefined,
-            };
-            const env = {};
-            injectToEnvWithContext(env, context);
-            const traceparent = env['TRACEPARENT'];
-            expect(traceparent).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
-        });
-        test('should overwrite existing TRACEPARENT', () => {
-            const context = {
-                traceId: '0af7651916cd43dd8448eb211c80319c',
-                spanId: 'b7ad6b7169203331',
-                parentSpanId: undefined,
-            };
-            const env = {
-                TRACEPARENT: '00-old-trace-old-span-old-flags',
-            };
-            injectToEnvWithContext(env, context);
-            expect(env['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
-        });
-    });
-    describe('injectToEnvFromCarrier', () => {
-        test('should inject from source carrier to target carrier', () => {
-            const sourceCarrier = {
-                TRACEPARENT: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01',
-            };
-            const targetCarrier = {};
-            injectToEnvFromCarrier(targetCarrier, sourceCarrier);
-            expect(targetCarrier['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
-        });
-        test('should return undefined if source has no TRACEPARENT', () => {
-            const sourceCarrier = {};
-            const targetCarrier = {};
-            injectToEnvFromCarrier(targetCarrier, sourceCarrier);
-            expect(targetCarrier['TRACEPARENT']).toBeUndefined();
-        });
-    });
-});
-describe('propagation-env integration', () => {
-    test('should produce valid W3C traceparent format', () => {
-        const context = {
-            traceId: '0af7651916cd43dd8448eb211c80319c',
-            spanId: 'b7ad6b7169203331',
-            parentSpanId: undefined,
-        };
-        const env = {};
-        injectToEnvWithContext(env, context);
-        // Parse and verify format
-        const parsed = propagation.extract(env);
-        expect(parsed).toBeDefined();
-        expect(parsed.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
-        expect(parsed.spanId).toBe('b7ad6b7169203331');
-    });
-});
-//# sourceMappingURL=propagation-env.test.js.map

package/dist/core/src/env/log-trace/opentelemetry/propagation.d.ts

@@ -1,80 +0,0 @@
-/**
- * @fileoverview W3C TraceContext Propagation
- *
- * 实现 W3C Trace Context 标准中的 traceparent 格式：
- * https://www.w3.org/TR/trace-context/#traceparent-header
- *
- * 格式: 00-{traceId}-{parentSpanId}-{flags}
- * - version: 2字符，固定 "00"
- * - traceId: 32字符，128位追踪ID
- * - parentSpanId: 16字符，64位父Span ID
- * - flags: 2字符，采样标志（当前固定 "01"）
- */
-import type { SpanContext } from "../types";
-/**
- * 将 SpanContext 序列化为 traceparent 字符串
- *
- * W3C TraceContext 语义：
- * - traceparent 中的 spanId 是"发送方 span"的 ID
- * - 接收方会将其作为新 span 的 parentSpanId
- * - 所以应该使用 context.spanId，而非 parentSpanId
- *
- * @param context SpanContext
- * @returns traceparent 格式字符串
- */
-export declare function serialize(context: SpanContext): string;
-/**
- * 提取的 Trace Context
- *
- * W3C TraceContext 格式: 00-{traceId}-{spanId}-{flags}
- * - {spanId} 是发送方 span 的 ID
- * - 接收方应将其作为新 span 的 parentSpanId
- */
-export interface ExtractedContext {
-    traceId: string;
-    /** 发送方 span 的 ID，接收方应作为新 span 的 parentSpanId */
-    spanId: string;
-}
-/**
- * 将 traceparent 字符串反序列化为 ExtractedContext
- *
- * W3C TraceContext 语义：
- * - traceparent 中的 "span-id" 是发送方 span 的 ID
- * - 接收方应该：
- *   - 使用提取的 traceId
- *   - 将提取的 spanId 作为 parentSpanId
- *   - 生成自己的新 spanId
- *
- * @param traceparent traceparent 格式字符串
- * @returns 接收方 ExtractedContext 或 undefined（格式无效）
- */
-export declare function parse(traceparent: string): ExtractedContext | undefined;
-/**
- * W3C TraceContext Propagation 实现
- *
- * 用于在进程间传递 trace 上下文：
- * - inject: 将 SpanContext 注入到 carrier（环境变量）
- * - extract: 从 carrier（环境变量）提取 SpanContext
- */
-export declare const propagation: {
-    /**
-     * 将 SpanContext 注入到 carrier
-     *
-     * @param carrier 载体对象（通常是环境变量对象）
-     * @param context Span 上下文
-     */
-    inject(carrier: Record<string, string | undefined>, context: SpanContext): void;
-    /**
-     * 从 carrier 提取 SpanContext
-     *
-     * @param carrier 载体对象（通常是环境变量对象）
-     * @returns ExtractedContext 或 undefined
-     */
-    extract(carrier: Record<string, string | undefined>): ExtractedContext | undefined;
-    /**
-     * 获取 traceparent 字段名
-     */
-    getTraceparentHeader(): string;
-};
-export type { SpanContext } from "../types";
-//# sourceMappingURL=propagation.d.ts.map

package/dist/core/src/env/log-trace/opentelemetry/propagation.js

@@ -1,163 +0,0 @@
-/**
- * @fileoverview W3C TraceContext Propagation
- *
- * 实现 W3C Trace Context 标准中的 traceparent 格式：
- * https://www.w3.org/TR/trace-context/#traceparent-header
- *
- * 格式: 00-{traceId}-{parentSpanId}-{flags}
- * - version: 2字符，固定 "00"
- * - traceId: 32字符，128位追踪ID
- * - parentSpanId: 16字符，64位父Span ID
- * - flags: 2字符，采样标志（当前固定 "01"）
- */
-// ============================================================================
-// Constants
-// ============================================================================
-/** W3C TraceContext 版本号 */
-const TRACE_CONTEXT_VERSION = "00";
-/** 采样标志（01 = sampled） */
-const TRACE_FLAGS_SAMPLED = "01";
-/** traceparent 字段名 */
-const TRACEPARENT_HEADER = "TRACEPARENT";
-/** 版本号长度 */
-const VERSION_LENGTH = 2;
-/** traceId 长度 */
-const TRACE_ID_LENGTH = 32;
-/** parentSpanId 长度 */
-const PARENT_SPAN_ID_LENGTH = 16;
-/** flags 长度 */
-const FLAGS_LENGTH = 2;
-// ============================================================================
-// Utility Functions
-// ============================================================================
-/**
- * 左补零到指定长度
- */
-function padLeft(str, length) {
-    return str.padStart(length, "0");
-}
-/**
- * 验证是否为有效的十六进制字符串
- */
-function isValidHex(str) {
-    return /^[0-9a-f]+$/i.test(str);
-}
-// ============================================================================
-// Serialization (SpanContext -> traceparent)
-// ============================================================================
-/**
- * 将 SpanContext 序列化为 traceparent 字符串
- *
- * W3C TraceContext 语义：
- * - traceparent 中的 spanId 是"发送方 span"的 ID
- * - 接收方会将其作为新 span 的 parentSpanId
- * - 所以应该使用 context.spanId，而非 parentSpanId
- *
- * @param context SpanContext
- * @returns traceparent 格式字符串
- */
-export function serialize(context) {
-    const traceId = padLeft(context.traceId.toLowerCase(), TRACE_ID_LENGTH);
-    const spanId = padLeft(context.spanId.toLowerCase(), PARENT_SPAN_ID_LENGTH);
-    // 格式: 00-{traceId}-{spanId}-{flags}
-    // 注意：使用 spanId 而非 parentSpanId，因为这是发送方 span 的 ID
-    const parts = [
-        TRACE_CONTEXT_VERSION,
-        traceId,
-        spanId,
-        TRACE_FLAGS_SAMPLED,
-    ];
-    return parts.join("-");
-}
-/**
- * 将 traceparent 字符串反序列化为 ExtractedContext
- *
- * W3C TraceContext 语义：
- * - traceparent 中的 "span-id" 是发送方 span 的 ID
- * - 接收方应该：
- *   - 使用提取的 traceId
- *   - 将提取的 spanId 作为 parentSpanId
- *   - 生成自己的新 spanId
- *
- * @param traceparent traceparent 格式字符串
- * @returns 接收方 ExtractedContext 或 undefined（格式无效）
- */
-export function parse(traceparent) {
-    if (!traceparent || typeof traceparent !== "string") {
-        return undefined;
-    }
-    const trimmed = traceparent.trim();
-    const parts = trimmed.split("-");
-    // 必须有 4 个部分
-    if (parts.length !== 4) {
-        return undefined;
-    }
-    const [version, traceId, senderSpanId, flags] = parts;
-    // 验证版本（当前只支持 "00"）
-    if (version !== TRACE_CONTEXT_VERSION) {
-        // 未来版本兼容：对于 "ff" 及以上的未来版本，忽略
-        if (version > TRACE_CONTEXT_VERSION) {
-            return undefined;
-        }
-    }
-    // 验证 traceId 长度和格式
-    if (traceId.length !== TRACE_ID_LENGTH || !isValidHex(traceId)) {
-        return undefined;
-    }
-    // 验证 spanId 长度和格式（W3C 标准中叫 span-id，但这是发送方 span 的 ID）
-    if (senderSpanId.length !== PARENT_SPAN_ID_LENGTH || !isValidHex(senderSpanId)) {
-        return undefined;
-    }
-    // 验证 flags 长度（当前忽略 flags 值，只验证格式）
-    if (flags.length !== FLAGS_LENGTH || !isValidHex(flags)) {
-        return undefined;
-    }
-    // 返回提取的上下文
-    // - traceId: 保持不变
-    // - spanId: 发送方 span 的 ID（接收方应作为新 span 的 parentSpanId）
-    return {
-        traceId: traceId.toLowerCase(),
-        spanId: senderSpanId.toLowerCase(),
-    };
-}
-// ============================================================================
-// Propagation Interface
-// ============================================================================
-/**
- * W3C TraceContext Propagation 实现
- *
- * 用于在进程间传递 trace 上下文：
- * - inject: 将 SpanContext 注入到 carrier（环境变量）
- * - extract: 从 carrier（环境变量）提取 SpanContext
- */
-export const propagation = {
-    /**
-     * 将 SpanContext 注入到 carrier
-     *
-     * @param carrier 载体对象（通常是环境变量对象）
-     * @param context Span 上下文
-     */
-    inject(carrier, context) {
-        carrier[TRACEPARENT_HEADER] = serialize(context);
-    },
-    /**
-     * 从 carrier 提取 SpanContext
-     *
-     * @param carrier 载体对象（通常是环境变量对象）
-     * @returns ExtractedContext 或 undefined
-     */
-    extract(carrier) {
-        const traceparent = carrier[TRACEPARENT_HEADER];
-        if (!traceparent) {
-            return undefined;
-        }
-        return parse(traceparent);
-    },
-    /**
-     * 获取 traceparent 字段名
-     */
-    getTraceparentHeader() {
-        return TRACEPARENT_HEADER;
-    },
-};
-//# sourceMappingURL=propagation.js.map

package/dist/core/src/env/log-trace/opentelemetry/propagation.test.d.ts

@@ -1,11 +0,0 @@
-/**
- * @fileoverview W3C TraceContext Propagation 测试
- *
- * 测试 W3C TraceContext 标准的 traceparent 格式：
- * - 注入 (inject): 将 SpanContext 序列化到环境变量
- * - 提取 (extract): 从环境变量反序列化 SpanContext
- * - 序列化 (serialize): SpanContext -> traceparent 字符串
- * - 反序列化 (parse): traceparent 字符串 -> SpanContext
- */
-export {};
-//# sourceMappingURL=propagation.test.d.ts.map