aws-runtime-bridge 1.0.0

package/dist/utils/file-utils.js

@@ -0,0 +1,140 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import axios from 'axios';
+import { schedulerBaseUrl, runtimeToken } from '../config.js';
+export async function ensureDir(targetDir) {
+    await fs.mkdir(targetDir, { recursive: true });
+    return targetDir;
+}
+export async function downloadSkillZip(skillPackage, targetDir) {
+    if (!skillPackage || !skillPackage.downloadUrl) {
+        return null;
+    }
+    const url = String(skillPackage.downloadUrl).trim();
+    if (!url) {
+        return null;
+    }
+    let absoluteUrl = url;
+    if (absoluteUrl.startsWith('/')) {
+        absoluteUrl = `${schedulerBaseUrl}${absoluteUrl}`;
+    }
+    const fileName = skillPackage.fileName && String(skillPackage.fileName).trim()
+        ? String(skillPackage.fileName).trim()
+        : 'skill-package.zip';
+    const outputPath = path.join(targetDir, fileName);
+    const response = await axios.get(absoluteUrl, {
+        responseType: 'arraybuffer',
+        headers: {
+            'X-Runtime-Token': runtimeToken,
+        },
+    });
+    const bytes = Buffer.from(response.data);
+    await fs.writeFile(outputPath, bytes);
+    if (skillPackage.sha256) {
+        const hash = createHash('sha256').update(bytes).digest('hex');
+        if (hash !== String(skillPackage.sha256).trim().toLowerCase()) {
+            throw new Error('skill zip checksum mismatch');
+        }
+    }
+    return {
+        fileName,
+        outputPath,
+        bytes: bytes.length,
+    };
+}
+export async function runCommand(command, args) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            stderr += String(chunk || '');
+        });
+        child.on('error', (error) => {
+            reject(error);
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(stderr || `${command} exited with code ${code}`));
+                return;
+            }
+            resolve();
+        });
+    });
+}
+export function escapePowerShellLiteral(text) {
+    return String(text || '').replace(/'/g, "''");
+}
+export async function extractSkillZip(zipFilePath, extractRootDir) {
+    await fs.rm(extractRootDir, { recursive: true, force: true });
+    await fs.mkdir(extractRootDir, { recursive: true });
+    if (process.platform === 'win32') {
+        const zipLiteral = escapePowerShellLiteral(zipFilePath);
+        const targetLiteral = escapePowerShellLiteral(extractRootDir);
+        await runCommand('powershell.exe', [
+            '-NoLogo',
+            '-NoProfile',
+            '-Command',
+            `Expand-Archive -LiteralPath '${zipLiteral}' -DestinationPath '${targetLiteral}' -Force`,
+        ]);
+        return;
+    }
+    await runCommand('unzip', ['-o', zipFilePath, '-d', extractRootDir]);
+}
+export async function resolveSkillSourceDirFromExtractRoot(extractRootDir) {
+    const entries = await fs.readdir(extractRootDir, { withFileTypes: true });
+    const visible = entries.filter((entry) => !entry.name.startsWith('.'));
+    if (visible.length === 1 && visible[0].isDirectory()) {
+        return path.join(extractRootDir, visible[0].name);
+    }
+    return extractRootDir;
+}
+export function toSdkAppsFromEnabledTools(enabledTools) {
+    const tools = Array.isArray(enabledTools) ? enabledTools : [];
+    const includes = (name) => tools.includes(name);
+    return {
+        claude: includes('claude'),
+        claudecode: includes('claudecode'),
+        codex: includes('codex'),
+        gemini: includes('gemini'),
+        opencode: includes('opencode'),
+        openclaw: includes('openclaw'),
+    };
+}
+export function resolveSkillSourceDir(skill) {
+    const sourceDirCandidate = String(skill?.sourceDir || skill?.directory || skill?.filePath || '').trim();
+    if (!sourceDirCandidate) {
+        throw new Error('skill.sourceDir is required');
+    }
+    return path.resolve(sourceDirCandidate);
+}
+export async function ensureDirectoryExists(directoryPath) {
+    const stat = await fs.stat(directoryPath);
+    if (!stat.isDirectory()) {
+        throw new Error(`not a directory: ${directoryPath}`);
+    }
+}
+export async function installSkillPackageToSdk(sdk, skillPackage, skillDir, sdkApps) {
+    const downloaded = await downloadSkillZip(skillPackage, skillDir);
+    if (!downloaded) {
+        return null;
+    }
+    const extractRootDir = path.join(skillDir, `${path.parse(downloaded.fileName).name}-${randomUUID()}`);
+    await extractSkillZip(downloaded.outputPath, extractRootDir);
+    const sourceDir = await resolveSkillSourceDirFromExtractRoot(extractRootDir);
+    const desiredName = String(skillPackage?.skillName || downloaded.fileName || '').trim() || downloaded.fileName;
+    const allSkills = sdk.getAllSkills();
+    const existing = allSkills.find((item) => String(item?.name || '').trim() === desiredName);
+    if (existing) {
+        return sdk.updateSkill(existing.id, {
+            name: desiredName,
+            apps: sdkApps,
+        });
+    }
+    return sdk.installSkill({
+        sourceDir,
+        name: desiredName,
+        apps: sdkApps,
+    });
+}

package/dist/utils/file-utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=file-utils.test.d.ts.map

package/dist/utils/file-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.test.d.ts","sourceRoot":"","sources":["../../src/utils/file-utils.test.ts"],"names":[],"mappings":""}

package/dist/utils/file-utils.test.js

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import { ensureDir, escapePowerShellLiteral, resolveSkillSourceDirFromExtractRoot, toSdkAppsFromEnabledTools, resolveSkillSourceDir, } from './file-utils.js';
+// Mock axios for download tests
+vi.mock('axios', () => ({
+    default: {
+        get: vi.fn(),
+        post: vi.fn(),
+    },
+}));
+// Mock config
+vi.mock('../config.js', () => ({
+    schedulerBaseUrl: 'http://localhost:8080',
+    runtimeToken: 'test-token',
+}));
+describe('file-utils', () => {
+    describe('ensureDir', () => {
+        const tempDir = path.join(os.tmpdir(), `aws-file-utils-test-${Date.now()}`);
+        afterEach(async () => {
+            try {
+                await fs.rm(tempDir, { recursive: true, force: true });
+            }
+            catch {
+                // ignore
+            }
+        });
+        it('should create directory if not exists', async () => {
+            const result = await ensureDir(tempDir);
+            expect(result).toBe(tempDir);
+            const stat = await fs.stat(tempDir);
+            expect(stat.isDirectory()).toBe(true);
+        });
+        it('should create nested directories', async () => {
+            const nestedDir = path.join(tempDir, 'level1', 'level2', 'level3');
+            const result = await ensureDir(nestedDir);
+            expect(result).toBe(nestedDir);
+            const stat = await fs.stat(nestedDir);
+            expect(stat.isDirectory()).toBe(true);
+        });
+        it('should return path if directory already exists', async () => {
+            await fs.mkdir(tempDir, { recursive: true });
+            const result = await ensureDir(tempDir);
+            expect(result).toBe(tempDir);
+        });
+    });
+    describe('escapePowerShellLiteral', () => {
+        it('should escape single quotes by doubling them', () => {
+            expect(escapePowerShellLiteral("test'value")).toBe("test''value");
+        });
+        it('should handle multiple single quotes', () => {
+            expect(escapePowerShellLiteral("a'b'c")).toBe("a''b''c");
+        });
+        it('should return empty string for empty input', () => {
+            expect(escapePowerShellLiteral('')).toBe('');
+        });
+        it('should handle null/undefined gracefully', () => {
+            expect(escapePowerShellLiteral(null)).toBe('');
+            expect(escapePowerShellLiteral(undefined)).toBe('');
+        });
+        it('should not modify strings without quotes', () => {
+            expect(escapePowerShellLiteral('normal path')).toBe('normal path');
+        });
+        it('should handle path with special characters', () => {
+            expect(escapePowerShellLiteral("C:\\Users\\Test's Folder")).toBe("C:\\Users\\Test''s Folder");
+        });
+    });
+    describe('resolveSkillSourceDirFromExtractRoot', () => {
+        const tempRoot = path.join(os.tmpdir(), `aws-skill-extract-test-${Date.now()}`);
+        beforeEach(async () => {
+            await fs.mkdir(tempRoot, { recursive: true });
+        });
+        afterEach(async () => {
+            try {
+                await fs.rm(tempRoot, { recursive: true, force: true });
+            }
+            catch {
+                // ignore
+            }
+        });
+        it('should return subdirectory when single visible directory exists', async () => {
+            const subDir = path.join(tempRoot, 'skill-package');
+            await fs.mkdir(subDir, { recursive: true });
+            await fs.writeFile(path.join(subDir, 'skill.md'), 'test', 'utf-8');
+            const result = await resolveSkillSourceDirFromExtractRoot(tempRoot);
+            expect(result).toBe(subDir);
+        });
+        it('should return root when multiple visible directories exist', async () => {
+            const subDir1 = path.join(tempRoot, 'dir1');
+            const subDir2 = path.join(tempRoot, 'dir2');
+            await fs.mkdir(subDir1, { recursive: true });
+            await fs.mkdir(subDir2, { recursive: true });
+            const result = await resolveSkillSourceDirFromExtractRoot(tempRoot);
+            expect(result).toBe(tempRoot);
+        });
+        it('should return root when files exist at root level', async () => {
+            await fs.writeFile(path.join(tempRoot, 'skill.md'), 'test', 'utf-8');
+            await fs.writeFile(path.join(tempRoot, 'README.md'), 'readme', 'utf-8');
+            const result = await resolveSkillSourceDirFromExtractRoot(tempRoot);
+            expect(result).toBe(tempRoot);
+        });
+        it('should ignore hidden directories (starting with dot)', async () => {
+            const visibleDir = path.join(tempRoot, 'visible');
+            const hiddenDir = path.join(tempRoot, '.hidden');
+            await fs.mkdir(visibleDir, { recursive: true });
+            await fs.mkdir(hiddenDir, { recursive: true });
+            const result = await resolveSkillSourceDirFromExtractRoot(tempRoot);
+            expect(result).toBe(visibleDir);
+        });
+        it('should return root when no visible entries exist', async () => {
+            const hiddenDir = path.join(tempRoot, '.hidden');
+            await fs.mkdir(hiddenDir, { recursive: true });
+            const result = await resolveSkillSourceDirFromExtractRoot(tempRoot);
+            expect(result).toBe(tempRoot);
+        });
+    });
+    describe('toSdkAppsFromEnabledTools', () => {
+        it('should map enabled tools to app flags', () => {
+            const result = toSdkAppsFromEnabledTools(['claude', 'opencode']);
+            expect(result.claude).toBe(true);
+            expect(result.opencode).toBe(true);
+            expect(result.codex).toBe(false);
+            expect(result.gemini).toBe(false);
+        });
+        it('should handle all known tools', () => {
+            const result = toSdkAppsFromEnabledTools([
+                'claude',
+                'claudecode',
+                'codex',
+                'gemini',
+                'opencode',
+                'openclaw',
+            ]);
+            expect(result.claude).toBe(true);
+            expect(result.codex).toBe(true);
+            expect(result.gemini).toBe(true);
+            expect(result.opencode).toBe(true);
+            expect(result.openclaw).toBe(true);
+        });
+        it('should return all false for empty array', () => {
+            const result = toSdkAppsFromEnabledTools([]);
+            expect(result.claude).toBe(false);
+            expect(result.codex).toBe(false);
+            expect(result.gemini).toBe(false);
+            expect(result.opencode).toBe(false);
+            expect(result.openclaw).toBe(false);
+        });
+        it('should handle null/undefined input', () => {
+            const resultNull = toSdkAppsFromEnabledTools(null);
+            const resultUndefined = toSdkAppsFromEnabledTools(undefined);
+            expect(resultNull.claude).toBe(false);
+            expect(resultUndefined.claude).toBe(false);
+        });
+        it('should ignore unknown tools', () => {
+            const result = toSdkAppsFromEnabledTools(['unknown-tool', 'claude']);
+            expect(result.claude).toBe(true);
+        });
+    });
+    describe('resolveSkillSourceDir', () => {
+        it('should return sourceDir when available', () => {
+            const skill = { sourceDir: '/path/to/source' };
+            expect(resolveSkillSourceDir(skill)).toBe(path.resolve('/path/to/source'));
+        });
+        it('should fallback to directory when sourceDir not available', () => {
+            const skill = { directory: '/path/to/directory' };
+            expect(resolveSkillSourceDir(skill)).toBe(path.resolve('/path/to/directory'));
+        });
+        it('should fallback to filePath when sourceDir and directory not available', () => {
+            const skill = { filePath: '/path/to/file.yaml' };
+            expect(resolveSkillSourceDir(skill)).toBe(path.resolve('/path/to/file.yaml'));
+        });
+        it('should prioritize sourceDir over directory and filePath', () => {
+            const skill = {
+                sourceDir: '/source',
+                directory: '/directory',
+                filePath: '/file',
+            };
+            expect(resolveSkillSourceDir(skill)).toBe(path.resolve('/source'));
+        });
+        it('should throw error when no path is available', () => {
+            const skill = {};
+            expect(() => resolveSkillSourceDir(skill)).toThrow('skill.sourceDir is required');
+        });
+        it('should throw error when skill is null', () => {
+            expect(() => resolveSkillSourceDir(null)).toThrow('skill.sourceDir is required');
+        });
+        it('should throw error when path is empty string', () => {
+            const skill = { sourceDir: '' };
+            expect(() => resolveSkillSourceDir(skill)).toThrow('skill.sourceDir is required');
+        });
+        it('should throw error when path is whitespace only', () => {
+            const skill = { sourceDir: '   ' };
+            expect(() => resolveSkillSourceDir(skill)).toThrow('skill.sourceDir is required');
+        });
+        it('should trim whitespace from path', () => {
+            const skill = { sourceDir: '  /path/to/source  ' };
+            expect(resolveSkillSourceDir(skill)).toBe(path.resolve('/path/to/source'));
+        });
+    });
+});

package/dist/utils/logger.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 统一日志模块
+ *
+ * 提供结构化日志输出，支持不同日志级别和格式化
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogConfig {
+    level: LogLevel;
+    prefix?: string;
+    timestamp?: boolean;
+}
+/**
+ * 日志器类
+ */
+export declare class Logger {
+    private readonly level;
+    private readonly prefix;
+    private readonly timestamp;
+    constructor(config?: LogConfig);
+    private shouldLog;
+    private formatMessage;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    /**
+     * 创建子日志器
+     */
+    child(prefix: string): Logger;
+}
+export declare const logger: {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    child: (prefix: string) => Logger;
+};
+export declare function createLogger(prefix: string, config?: Partial<LogConfig>): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAkCD;;GAEG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;gBAExB,MAAM,GAAE,SAA6B;IAMjD,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;IAkBrB,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM9B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/B;;OAEG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;CAO9B;AAQD,eAAO,MAAM,MAAM;qBACA,OAAO,EAAE,KAAG,IAAI;oBACjB,OAAO,EAAE,KAAG,IAAI;oBAChB,OAAO,EAAE,KAAG,IAAI;qBACf,OAAO,EAAE,KAAG,IAAI;oBACjB,MAAM,KAAG,MAAM;CAChC,CAAC;AAGF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,CAMhF"}

package/dist/utils/logger.js

@@ -0,0 +1,110 @@
+/**
+ * 统一日志模块
+ *
+ * 提供结构化日志输出，支持不同日志级别和格式化
+ */
+const LOG_LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/**
+ * 格式化时间戳
+ */
+function formatTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * 格式化日志参数
+ */
+function formatArgs(args) {
+    return args
+        .map((arg) => {
+        if (typeof arg === 'object' && arg !== null) {
+            try {
+                return JSON.stringify(arg, null, 2);
+            }
+            catch {
+                return String(arg);
+            }
+        }
+        return String(arg);
+    })
+        .join(' ');
+}
+/**
+ * 日志器类
+ */
+export class Logger {
+    constructor(config = { level: 'info' }) {
+        this.level = config.level;
+        this.prefix = config.prefix || '';
+        this.timestamp = config.timestamp ?? true;
+    }
+    shouldLog(level) {
+        return LOG_LEVEL_PRIORITY[level] >= LOG_LEVEL_PRIORITY[this.level];
+    }
+    formatMessage(level, args) {
+        const parts = [];
+        if (this.timestamp) {
+            parts.push(`[${formatTimestamp()}]`);
+        }
+        parts.push(`[${level.toUpperCase()}]`);
+        if (this.prefix) {
+            parts.push(`[${this.prefix}]`);
+        }
+        parts.push(formatArgs(args));
+        return parts.join(' ');
+    }
+    debug(...args) {
+        if (this.shouldLog('debug')) {
+            console.debug(this.formatMessage('debug', args));
+        }
+    }
+    info(...args) {
+        if (this.shouldLog('info')) {
+            console.info(this.formatMessage('info', args));
+        }
+    }
+    warn(...args) {
+        if (this.shouldLog('warn')) {
+            console.warn(this.formatMessage('warn', args));
+        }
+    }
+    error(...args) {
+        if (this.shouldLog('error')) {
+            console.error(this.formatMessage('error', args));
+        }
+    }
+    /**
+     * 创建子日志器
+     */
+    child(prefix) {
+        return new Logger({
+            level: this.level,
+            prefix: this.prefix ? `${this.prefix}:${prefix}` : prefix,
+            timestamp: this.timestamp,
+        });
+    }
+}
+// 默认日志器实例
+const defaultLogger = new Logger({
+    level: process.env.LOG_LEVEL || 'info',
+});
+// 导出便捷方法
+export const logger = {
+    debug: (...args) => defaultLogger.debug(...args),
+    info: (...args) => defaultLogger.info(...args),
+    warn: (...args) => defaultLogger.warn(...args),
+    error: (...args) => defaultLogger.error(...args),
+    child: (prefix) => defaultLogger.child(prefix),
+};
+// 创建带前缀的日志器
+export function createLogger(prefix, config) {
+    return new Logger({
+        level: config?.level || process.env.LOG_LEVEL || 'info',
+        prefix,
+        timestamp: config?.timestamp,
+    });
+}

package/dist/utils/logger.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=logger.test.d.ts.map

package/dist/utils/logger.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.test.d.ts","sourceRoot":"","sources":["../../src/utils/logger.test.ts"],"names":[],"mappings":""}

package/dist/utils/logger.test.js

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Logger, createLogger, logger } from './logger';
+describe('Logger', () => {
+    let consoleSpy;
+    beforeEach(() => {
+        consoleSpy = {
+            debug: vi.spyOn(console, 'debug').mockImplementation(() => { }),
+            info: vi.spyOn(console, 'info').mockImplementation(() => { }),
+            warn: vi.spyOn(console, 'warn').mockImplementation(() => { }),
+            error: vi.spyOn(console, 'error').mockImplementation(() => { }),
+        };
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('log levels', () => {
+        it('should not log debug when level is info', () => {
+            const log = new Logger({ level: 'info' });
+            log.debug('test message');
+            expect(consoleSpy.debug).not.toHaveBeenCalled();
+        });
+        it('should log info when level is info', () => {
+            const log = new Logger({ level: 'info' });
+            log.info('test message');
+            expect(consoleSpy.info).toHaveBeenCalled();
+        });
+        it('should log warn when level is info', () => {
+            const log = new Logger({ level: 'info' });
+            log.warn('test message');
+            expect(consoleSpy.warn).toHaveBeenCalled();
+        });
+        it('should log error when level is info', () => {
+            const log = new Logger({ level: 'info' });
+            log.error('test message');
+            expect(consoleSpy.error).toHaveBeenCalled();
+        });
+        it('should log all levels when level is debug', () => {
+            const log = new Logger({ level: 'debug' });
+            log.debug('debug message');
+            log.info('info message');
+            log.warn('warn message');
+            log.error('error message');
+            expect(consoleSpy.debug).toHaveBeenCalled();
+            expect(consoleSpy.info).toHaveBeenCalled();
+            expect(consoleSpy.warn).toHaveBeenCalled();
+            expect(consoleSpy.error).toHaveBeenCalled();
+        });
+    });
+    describe('prefix', () => {
+        it('should include prefix in log message', () => {
+            const log = new Logger({ level: 'info', prefix: 'test-module' });
+            log.info('test message');
+            expect(consoleSpy.info).toHaveBeenCalledWith(expect.stringContaining('[test-module]'));
+        });
+    });
+    describe('timestamp', () => {
+        it('should include timestamp by default', () => {
+            const log = new Logger({ level: 'info' });
+            log.info('test message');
+            expect(consoleSpy.info).toHaveBeenCalledWith(expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/));
+        });
+    });
+    describe('child logger', () => {
+        it('should create child logger with combined prefix', () => {
+            const parentLog = new Logger({ level: 'info', prefix: 'parent' });
+            const childLog = parentLog.child('child');
+            childLog.info('test message');
+            expect(consoleSpy.info).toHaveBeenCalledWith(expect.stringContaining('[parent:child]'));
+        });
+    });
+    describe('object formatting', () => {
+        it('should format objects in log message', () => {
+            const log = new Logger({ level: 'info' });
+            log.info('test', { key: 'value' });
+            expect(consoleSpy.info).toHaveBeenCalledWith(expect.stringContaining('"key"'));
+        });
+    });
+});
+describe('createLogger', () => {
+    it('should create logger with prefix', () => {
+        const log = createLogger('test-prefix');
+        expect(log).toBeInstanceOf(Logger);
+    });
+});
+describe('default logger', () => {
+    it('should export logger methods', () => {
+        expect(typeof logger.debug).toBe('function');
+        expect(typeof logger.info).toBe('function');
+        expect(typeof logger.warn).toBe('function');
+        expect(typeof logger.error).toBe('function');
+        expect(typeof logger.child).toBe('function');
+    });
+});

package/dist/utils/mcp-utils.d.ts

@@ -0,0 +1,73 @@
+/**
+ * MCP 工具函数
+ *
+ * 提供 MCP 服务器配置的构建、转换和规范化功能
+ */
+import type { LegacyMcpStateItem, McpPayload, McpServerConfig, SdkApps } from '../types.js';
+import type { McpServerSpec } from '@cc-switch/sdk';
+/**
+ * 构建 MCP 配置内容
+ *
+ * @param mcpServers - MCP 服务器列表
+ * @returns JSON 格式的配置内容
+ */
+export declare function buildMcpConfigContent(mcpServers: LegacyMcpStateItem[]): string;
+/**
+ * 规范化 MCP Payload
+ *
+ * @param payload - 原始 payload
+ * @returns 规范化后的 MCP Payload，无效返回 null
+ */
+export declare function normalizeMcpPayload(payload: unknown): McpPayload | null;
+/**
+ * 规范化 SDK App 标志
+ *
+ * @param rawApps - 原始 apps 配置
+ * @returns 规范化后的 SdkApps
+ */
+export declare function normalizeSdkAppFlags(rawApps: unknown): SdkApps | undefined;
+/**
+ * 规范化 SDK MCP 服务器规格
+ *
+ * @param rawMcp - 原始 MCP 配置
+ * @returns 规范化后的服务器配置
+ */
+export declare function normalizeSdkMcpServerSpec(rawMcp: unknown): McpServerSpec;
+/**
+ * SDK MCP 服务器接口
+ */
+export interface McpServerFromSdk {
+    id?: string;
+    name?: string;
+    server?: McpServerConfig;
+    apps?: SdkApps;
+}
+/**
+ * 转换为 Legacy MCP State Item
+ *
+ * @param mcpServer - SDK MCP 服务器对象
+ * @returns Legacy MCP State Item
+ */
+export declare function toLegacyMcpStateItem(mcpServer: McpServerFromSdk): LegacyMcpStateItem;
+/**
+ * 转换为 Legacy Skill State Item
+ *
+ * @param skill - Skill 对象
+ * @returns Legacy Skill State Item
+ */
+export declare function toLegacySkillStateItem(skill: {
+    id?: string;
+    name?: string;
+    directory?: string;
+    sourceDir?: string;
+    filePath?: string;
+    installedAt?: string | number;
+}): {
+    id: string;
+    name: string;
+    fileName: string;
+    filePath: string;
+    bytes: number;
+    installedAt: string;
+};
+//# sourceMappingURL=mcp-utils.d.ts.map

package/dist/utils/mcp-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-utils.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EACV,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,OAAO,EACR,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAgD9E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAoBvE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAY1E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,CA6BxE;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,gBAAgB,GAAG,kBAAkB,CAcpF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B,GAAG;IACF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAA;CACpB,CAUA"}