@syllm/brickly-sdk 0.1.0

package/dist/typegen.js

@@ -0,0 +1,470 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDependencyTypes = generateDependencyTypes;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const RESERVED_WORDS = new Set([
+    'break',
+    'case',
+    'catch',
+    'class',
+    'const',
+    'continue',
+    'debugger',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'export',
+    'extends',
+    'finally',
+    'for',
+    'function',
+    'if',
+    'import',
+    'in',
+    'instanceof',
+    'new',
+    'return',
+    'super',
+    'switch',
+    'this',
+    'throw',
+    'try',
+    'typeof',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield',
+    'enum',
+    'implements',
+    'interface',
+    'let',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'static',
+    'await'
+]);
+function generateDependencyTypes(options = {}) {
+    const manifestPath = (0, node_path_1.resolve)(options.manifestPath ?? 'manifest.json');
+    const brickRoot = (0, node_path_1.resolve)(options.brickRoot ?? (0, node_path_1.dirname)(manifestPath));
+    const bricksDir = (0, node_path_1.resolve)(options.bricksDir ?? (0, node_path_1.dirname)(brickRoot));
+    const outDir = (0, node_path_1.resolve)(options.outDir ?? (0, node_path_1.resolve)(brickRoot, 'runtime', 'node', '_generated', 'deps'));
+    const sdkModule = options.sdkModule ?? inferSdkModule(outDir, brickRoot);
+    const sourceManifest = readManifest(manifestPath);
+    const warnings = [];
+    const dependencies = resolveDependencies(sourceManifest, {
+        bricksDir,
+        dependencyManifestPaths: options.dependencyManifestPaths ?? {},
+        warnings
+    });
+    const files = [];
+    (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    for (const dependency of dependencies) {
+        const basePath = (0, node_path_1.resolve)(outDir, dependency.brickId);
+        (0, node_fs_1.writeFileSync)(`${basePath}.js`, renderDependencyJs(dependency), 'utf8');
+        (0, node_fs_1.writeFileSync)(`${basePath}.d.ts`, renderDependencyDts(dependency), 'utf8');
+        files.push(`${basePath}.js`, `${basePath}.d.ts`);
+    }
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(outDir, 'index.js'), renderIndexJs(dependencies), 'utf8');
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(outDir, 'index.d.ts'), renderIndexDts(dependencies, sdkModule), 'utf8');
+    files.push((0, node_path_1.resolve)(outDir, 'index.js'), (0, node_path_1.resolve)(outDir, 'index.d.ts'));
+    return {
+        manifestPath,
+        outDir,
+        sdkModule,
+        dependencyCount: dependencies.length,
+        commandCount: dependencies.reduce((sum, dependency) => sum + dependency.commands.length, 0),
+        files,
+        warnings
+    };
+}
+function readManifest(manifestPath) {
+    if (!(0, node_fs_1.existsSync)(manifestPath)) {
+        throw new Error(`manifest.json 不存在：${manifestPath}`);
+    }
+    const value = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, 'utf8'));
+    if (!value || typeof value !== 'object' || typeof value.id !== 'string') {
+        throw new Error(`manifest.json 缺少有效 id：${manifestPath}`);
+    }
+    return value;
+}
+function resolveDependencies(sourceManifest, context) {
+    const dependencyEntries = Object.entries(sourceManifest.dependencies ?? {});
+    const namespaceByBrick = uniqueNamespaces(dependencyEntries.map(([brickId]) => brickId));
+    const dependencies = [];
+    for (const [brickId, spec] of dependencyEntries) {
+        const manifestPath = context.dependencyManifestPaths[brickId] ?? (0, node_path_1.resolve)(context.bricksDir, brickId, 'manifest.json');
+        const optional = typeof spec === 'object' && spec !== null && spec.optional === true;
+        if (!(0, node_fs_1.existsSync)(manifestPath)) {
+            const message = `依赖 Brick ${brickId} 未找到：${manifestPath}`;
+            if (optional) {
+                context.warnings.push(message);
+                continue;
+            }
+            throw new Error(message);
+        }
+        const manifest = readManifest(manifestPath);
+        const requestedCommands = typeof spec === 'object' && spec !== null ? spec.commands : undefined;
+        const commands = selectCommands(manifest, requestedCommands, brickId, context.warnings);
+        if (commands.length === 0) {
+            context.warnings.push(`依赖 Brick ${brickId} 没有可生成的命令。`);
+        }
+        dependencies.push({
+            brickId,
+            namespace: namespaceByBrick.get(brickId) ?? toSafeIdentifier(lastBrickSegment(brickId)),
+            manifest,
+            commands: commands.map((command) => ({
+                command,
+                functionName: toCommandFunctionName(command.id),
+                inputTypeName: `${toPascalCase(command.id)}Input`,
+                outputTypeName: `${toPascalCase(command.id)}Output`
+            }))
+        });
+    }
+    return dependencies;
+}
+function selectCommands(manifest, requestedCommands, brickId, warnings) {
+    const commands = manifest.commands ?? [];
+    if (requestedCommands && requestedCommands.length > 0) {
+        const byId = new Map(commands.map((command) => [command.id, command]));
+        const selected = new Map();
+        if (requestedCommands.includes('*')) {
+            for (const command of commands) {
+                if (command.hidden !== true)
+                    selected.set(command.id, command);
+            }
+        }
+        for (const commandId of requestedCommands.filter((item) => item !== '*')) {
+            const command = byId.get(commandId);
+            if (!command) {
+                warnings.push(`依赖 Brick ${brickId} 未声明命令 ${commandId}，已跳过。`);
+                continue;
+            }
+            selected.set(command.id, command);
+        }
+        return [...selected.values()];
+    }
+    warnings.push(`依赖 Brick ${brickId} 未声明 commands，已跳过生成调用包装。`);
+    return [];
+}
+function renderDependencyJs(dependency) {
+    const lines = [
+        "'use strict'",
+        '',
+        `const BRICK_ID = ${JSON.stringify(dependency.brickId)}`,
+        '',
+        'function assertInvokeTarget(target, functionName) {',
+        "  if (target && typeof target.invoke === 'function') return",
+        '  throw new TypeError(',
+        "    `${functionName} 需要传入 BricklyRuntime 或 CommandContext，例如 ${functionName}(ctx, input)；也可以先 const client = bind(ctx)，再调用 client.${functionName}(input)。`",
+        '  )',
+        '}',
+        ''
+    ];
+    for (const item of dependency.commands) {
+        lines.push(renderCommandJsDoc(dependency, item));
+        lines.push(`function ${item.functionName}(target, input, options) {`, `  assertInvokeTarget(target, ${JSON.stringify(item.functionName)})`, `  return target.invoke(BRICK_ID, ${JSON.stringify(item.command.id)}, input, options)`, '}', '');
+    }
+    lines.push('/**', ' * 绑定 BricklyRuntime 或 CommandContext，得到不需要重复传 target 的依赖调用对象。', ' */', 'function bind(target) {', '  return {');
+    for (const item of dependency.commands) {
+        lines.push(`    ${JSON.stringify(item.functionName)}: (input, options) => ${item.functionName}(target, input, options),`);
+    }
+    lines.push('  }', '}', '', 'exports.BRICK_ID = BRICK_ID', 'exports.bind = bind');
+    for (const item of dependency.commands) {
+        lines.push(`exports.${item.functionName} = ${item.functionName}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function renderDependencyDts(dependency) {
+    const lines = [
+        `export const BRICK_ID: ${JSON.stringify(dependency.brickId)}`,
+        '',
+        'export interface InvokeOptions {',
+        '  /** 目标 Brick Profile ID；不传则由宿主选择目标 Brick 默认 Profile。 */',
+        '  profileId?: string',
+        '}',
+        '',
+        'export interface BrickInvokeTarget {',
+        '  invoke<T = unknown>(',
+        '    brickId: string,',
+        '    commandId: string,',
+        '    input?: unknown,',
+        '    options?: InvokeOptions',
+        '  ): Promise<T>',
+        '}',
+        ''
+    ];
+    for (const item of dependency.commands) {
+        lines.push(renderInputType(item), '', renderOutputType(item), '', renderCommandDts(dependency, item), '');
+    }
+    lines.push(`export interface Bound${toPascalCase(dependency.namespace)} {`);
+    for (const item of dependency.commands) {
+        lines.push(renderMethodComment(item, '  '), `  ${item.functionName}(input: ${item.inputTypeName}, options?: InvokeOptions): Promise<${item.outputTypeName}>`);
+    }
+    lines.push('}', '');
+    lines.push(`export function bind(target: BrickInvokeTarget): Bound${toPascalCase(dependency.namespace)}`, '');
+    return lines.join('\n');
+}
+function renderIndexJs(dependencies) {
+    const lines = ["'use strict'", ''];
+    for (const dependency of dependencies) {
+        lines.push(`exports.${dependency.namespace} = require('./${dependency.brickId}')`);
+    }
+    lines.push('', 'exports.byBrickId = {');
+    for (const dependency of dependencies) {
+        lines.push(`  ${JSON.stringify(dependency.brickId)}: exports.${dependency.namespace},`);
+    }
+    lines.push('}');
+    lines.push('');
+    return lines.join('\n');
+}
+function renderIndexDts(dependencies, sdkModule) {
+    const lines = [];
+    for (const dependency of dependencies) {
+        lines.push(`export * as ${dependency.namespace} from './${dependency.brickId}'`);
+    }
+    if (dependencies.length > 0) {
+        lines.push('', 'export const byBrickId: {');
+        for (const dependency of dependencies) {
+            lines.push(`  ${JSON.stringify(dependency.brickId)}: typeof import('./${dependency.brickId}')`);
+        }
+        lines.push('}');
+    }
+    if (dependencies.length > 0) {
+        lines.push('');
+        for (const dependency of dependencies) {
+            const importedTypes = dependency.commands.flatMap((item) => [
+                `${item.inputTypeName} as ${typeAlias(dependency, item.inputTypeName)}`,
+                `${item.outputTypeName} as ${typeAlias(dependency, item.outputTypeName)}`
+            ]);
+            lines.push(`import type { ${importedTypes.join(', ')} } from './${dependency.brickId}'`);
+        }
+        lines.push('');
+        for (const moduleName of commandMapModuleTargets(sdkModule)) {
+            lines.push(`declare module ${JSON.stringify(moduleName)} {`, '  interface CommandMap {');
+            for (const dependency of dependencies) {
+                lines.push(`    ${JSON.stringify(dependency.brickId)}: {`);
+                for (const item of dependency.commands) {
+                    lines.push(`      ${JSON.stringify(item.command.id)}: { input: ${typeAlias(dependency, item.inputTypeName)}; output: ${typeAlias(dependency, item.outputTypeName)} }`);
+                }
+                lines.push('    }');
+            }
+            lines.push('  }', '}', '');
+        }
+    }
+    return lines.join('\n');
+}
+function renderCommandJsDoc(dependency, item) {
+    const commandName = localizedText(item.command.name);
+    const description = localizedText(item.command.description);
+    const lines = ['/**', ` * ${escapeComment(commandName || item.command.id)}`];
+    if (description) {
+        lines.push(' *', ...wrapComment(description).map((line) => ` * ${line}`));
+    }
+    lines.push(' *', ` * @param {import('./${dependency.brickId}').BrickInvokeTarget} target - BricklyRuntime 或 CommandContext。`, ` * @param {import('./${dependency.brickId}').${item.inputTypeName}} input - 命令输入。`, ` * @param {import('./${dependency.brickId}').InvokeOptions} [options] - 调用选项。`, ` * @returns {Promise<import('./${dependency.brickId}').${item.outputTypeName}>}`);
+    const inputs = item.command.io?.inputs ?? [];
+    for (const input of inputs) {
+        const text = socketComment(input);
+        if (text)
+            lines.push(` * @param input.${input.name} - ${escapeComment(text)}`);
+    }
+    lines.push(' */');
+    return lines.join('\n');
+}
+function renderCommandDts(dependency, item) {
+    return [
+        renderMethodComment(item),
+        `export function ${item.functionName}(`,
+        '  target: BrickInvokeTarget,',
+        `  input: ${item.inputTypeName},`,
+        '  options?: InvokeOptions',
+        `): Promise<${item.outputTypeName}>`
+    ].join('\n');
+}
+function renderMethodComment(item, prefix = '') {
+    const commandName = localizedText(item.command.name);
+    const description = localizedText(item.command.description);
+    const lines = [`${prefix}/**`, `${prefix} * ${escapeComment(commandName || item.command.id)}`];
+    if (description) {
+        lines.push(`${prefix} *`, ...wrapComment(description).map((line) => `${prefix} * ${line}`));
+    }
+    lines.push(`${prefix} */`);
+    return lines.join('\n');
+}
+function renderInputType(item) {
+    const inputs = item.command.io?.inputs ?? [];
+    if (inputs.length === 0) {
+        return `export type ${item.inputTypeName} = Record<string, never>`;
+    }
+    const lines = [`export interface ${item.inputTypeName} {`];
+    for (const input of inputs) {
+        const text = socketComment(input);
+        if (text) {
+            lines.push('  /**');
+            for (const line of wrapComment(text))
+                lines.push(`   * ${line}`);
+            lines.push('   */');
+        }
+        const optional = input.required === true ? '' : '?';
+        lines.push(`  ${input.name}${optional}: ${socketToTsType(input)}`);
+    }
+    lines.push('}');
+    return lines.join('\n');
+}
+function renderOutputType(item) {
+    const outputs = item.command.io?.outputs ?? [];
+    if (outputs.length === 0)
+        return `export type ${item.outputTypeName} = unknown`;
+    if (outputs.length === 1)
+        return `export type ${item.outputTypeName} = ${socketToTsType(outputs[0])}`;
+    const lines = [`export interface ${item.outputTypeName} {`];
+    for (const output of outputs) {
+        const text = socketComment(output);
+        if (text) {
+            lines.push('  /**');
+            for (const line of wrapComment(text))
+                lines.push(`   * ${line}`);
+            lines.push('   */');
+        }
+        lines.push(`  ${output.name}: ${socketToTsType(output)}`);
+    }
+    lines.push('}');
+    return lines.join('\n');
+}
+function socketToTsType(socket) {
+    const enumType = enumToTsType(socket.enum);
+    const baseType = enumType ??
+        {
+            string: 'string',
+            number: 'number',
+            boolean: 'boolean',
+            json: 'unknown',
+            image: 'string',
+            audio: 'string',
+            video: 'string',
+            file: 'string',
+            binary: '{ $file: string }',
+            stream: 'AsyncIterable<unknown>',
+            any: 'unknown'
+        }[socket.type];
+    return socket.multi === true ? `Array<${baseType}>` : baseType;
+}
+function enumToTsType(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    const literals = values
+        .map((item) => (typeof item === 'object' ? item.value : item))
+        .filter((value) => typeof value === 'string' || typeof value === 'number');
+    if (literals.length === 0)
+        return undefined;
+    return literals.map((value) => JSON.stringify(value)).join(' | ');
+}
+function socketComment(socket) {
+    const parts = [socket.label, socket.description];
+    if (socket.default !== undefined)
+        parts.push(`默认值：${JSON.stringify(socket.default)}`);
+    return parts.filter(Boolean).join('。');
+}
+function localizedText(value) {
+    if (!value)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    return value['zh-CN'] ?? value.zh ?? value.en ?? Object.values(value)[0] ?? '';
+}
+function wrapComment(text) {
+    const normalized = escapeComment(text).replace(/\s+/g, ' ').trim();
+    if (normalized.length <= 90)
+        return [normalized];
+    const lines = [];
+    let rest = normalized;
+    while (rest.length > 90) {
+        let index = rest.lastIndexOf(' ', 90);
+        if (index <= 0)
+            index = 90;
+        lines.push(rest.slice(0, index));
+        rest = rest.slice(index).trimStart();
+    }
+    if (rest)
+        lines.push(rest);
+    return lines;
+}
+function escapeComment(text) {
+    return text.replace(/\*\//g, '* /');
+}
+function toCommandFunctionName(commandId) {
+    const identifier = toSafeIdentifier(commandId);
+    return RESERVED_WORDS.has(identifier) ? `${identifier}Command` : identifier;
+}
+function toSafeIdentifier(value) {
+    const normalized = toCamelCase(value);
+    const clean = normalized.replace(/[^A-Za-z0-9_$]/g, '');
+    const fallback = clean || 'dependency';
+    return /^[A-Za-z_$]/.test(fallback) ? fallback : `_${fallback}`;
+}
+function toCamelCase(value) {
+    const words = value.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    if (words.length === 0)
+        return '';
+    const [first, ...rest] = words;
+    return first.toLowerCase() + rest.map(capitalize).join('');
+}
+function toPascalCase(value) {
+    const words = value.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const result = words.map(capitalize).join('');
+    return result || 'Value';
+}
+function capitalize(value) {
+    if (!value)
+        return '';
+    return value.slice(0, 1).toUpperCase() + value.slice(1);
+}
+function lastBrickSegment(brickId) {
+    return brickId.split('.').filter(Boolean).at(-1) ?? brickId;
+}
+function uniqueNamespaces(brickIds) {
+    const seen = new Set();
+    const result = new Map();
+    for (const brickId of brickIds) {
+        const segments = brickId.split('.').filter(Boolean);
+        let namespace = '';
+        for (let size = 1; size <= segments.length; size++) {
+            namespace = toSafeIdentifier(segments.slice(-size).join('-'));
+            if (!seen.has(namespace))
+                break;
+        }
+        let unique = namespace;
+        let suffix = 2;
+        while (seen.has(unique)) {
+            unique = `${namespace}${suffix}`;
+            suffix += 1;
+        }
+        seen.add(unique);
+        result.set(brickId, unique);
+    }
+    return result;
+}
+function inferSdkModule(outDir, brickRoot) {
+    const sdkDir = (0, node_path_1.resolve)(brickRoot, 'runtime', 'node', '_sdk');
+    const sdkTypes = (0, node_path_1.resolve)(sdkDir, 'index.d.ts');
+    if (!(0, node_fs_1.existsSync)(sdkTypes))
+        return '@syllm/brickly-sdk';
+    let path = (0, node_path_1.relative)(outDir, sdkDir).replace(/\\/g, '/');
+    if (!path.startsWith('.'))
+        path = `./${path}`;
+    return path;
+}
+function typeAlias(dependency, typeName) {
+    return `${toPascalCase(dependency.namespace)}${typeName}`;
+}
+function commandMapModuleTargets(sdkModule) {
+    const targets = [sdkModule, `${sdkModule}/api`];
+    if (sdkModule === '@syllm/brickly-sdk')
+        targets.push('@syllm/brickly-sdk/dist/api');
+    return [...new Set(targets)];
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@syllm/brickly-sdk",
+  "version": "0.1.0",
+  "description": "Brickly Brick Node runtime 官方 SDK",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "brickly-typegen": "dist/typegen-cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsx --test tests/runtime.test.ts tests/api.test.ts tests/typegen.test.ts",
+    "typegen": "tsx src/typegen-cli.ts",
+    "sync:demo-window-lab": "node scripts/sync-to-brick.mjs com.brickly.demo-window-lab",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^22.19.1",
+    "tsx": "^4.19.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}