@syllm/brickly-sdk 0.1.0

package/dist/runtime.d.ts

@@ -0,0 +1,64 @@
+import { EventEmitter } from 'node:events';
+import type { Readable, Writable } from 'node:stream';
+import type { BppMessage } from './protocol';
+export interface BppTransportOptions {
+    /** Brick id，用于生成请求 id 前缀与 runtime.ready 身份。 */
+    brickId: string;
+    /** stdin 流，默认 process.stdin。测试时可注入 mock。 */
+    stdin?: Readable;
+    /** stdout 流，默认 process.stdout。 */
+    stdout?: Writable;
+    /** stderr 流，默认 process.stderr。SDK 仅用于日志，不写协议。 */
+    stderr?: Writable;
+    /**
+     * 宿主管道断开时是否触发 host-disconnect。
+     * 默认：使用真实 process.stdin 时开启；测试/自定义 stdin 默认关闭。
+     */
+    exitOnHostDisconnect?: boolean;
+}
+/**
+ * 底层 BPP 传输层：负责 stdin 行读取、stdout 行写入、host.* 请求-响应路由与 id 分配。
+ * 不感知 command / event 业务语义，那部分由上层 BricklyRuntime（api.ts）实现。
+ *
+ * 事件：
+ *   - 'message'   (msg)  收到任意一条 BPP 消息（含 host.result/host.error 等）
+ *   - 'command'   (msg)  仅 command.invoke / command.cancel
+ *   - 'event'     (msg)  仅 event.notify
+ *   - 'shutdown'  ()     收到 runtime.shutdown
+ *   - 'error'     (err)  解析失败 / 内部异常
+ */
+export declare class BppTransport extends EventEmitter {
+    readonly brickId: string;
+    private readonly stdin;
+    private readonly stdout;
+    private readonly stderr;
+    private readonly exitOnHostDisconnect;
+    private buffer;
+    private idCounter;
+    private started;
+    private pending;
+    constructor(opts: BppTransportOptions);
+    /** 启动 stdin 监听。重复调用安全。 */
+    start(): void;
+    /** 停止监听并拒掉所有 pending host 调用。 */
+    stop(reason?: string): void;
+    /** 写一条 BPP 消息到 stdout。线程安全（Node 单线程，单次 write 是原子的）。 */
+    send(message: BppMessage): void;
+    /** 写 stderr 日志。stdout 永远只写协议；Brick 身份由宿主日志中心附加。 */
+    log(...parts: unknown[]): void;
+    /**
+     * 发起一个需要等待 host.result/host.error 回复的 host.* 调用。
+     * 入参省略 id（SDK 自动分配），返回 result 字段。
+     */
+    hostCall<T = unknown>(msg: Omit<Extract<BppMessage, {
+        id: string;
+    }>, 'id'> & {
+        type: string;
+    }): Promise<T>;
+    nextHostId(): string;
+    private nextId;
+    private handleChunk;
+    private handleInputClosed;
+    private handleInputError;
+    private dispatch;
+}

package/dist/runtime.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BppTransport = void 0;
+const node_events_1 = require("node:events");
+const errors_1 = require("./errors");
+/**
+ * 底层 BPP 传输层：负责 stdin 行读取、stdout 行写入、host.* 请求-响应路由与 id 分配。
+ * 不感知 command / event 业务语义，那部分由上层 BricklyRuntime（api.ts）实现。
+ *
+ * 事件：
+ *   - 'message'   (msg)  收到任意一条 BPP 消息（含 host.result/host.error 等）
+ *   - 'command'   (msg)  仅 command.invoke / command.cancel
+ *   - 'event'     (msg)  仅 event.notify
+ *   - 'shutdown'  ()     收到 runtime.shutdown
+ *   - 'error'     (err)  解析失败 / 内部异常
+ */
+class BppTransport extends node_events_1.EventEmitter {
+    brickId;
+    stdin;
+    stdout;
+    stderr;
+    exitOnHostDisconnect;
+    buffer = '';
+    idCounter = 0;
+    started = false;
+    pending = new Map();
+    constructor(opts) {
+        super();
+        this.brickId = opts.brickId;
+        this.stdin = opts.stdin ?? process.stdin;
+        this.stdout = opts.stdout ?? process.stdout;
+        this.stderr = opts.stderr ?? process.stderr;
+        this.exitOnHostDisconnect = opts.exitOnHostDisconnect ?? !opts.stdin;
+    }
+    /** 启动 stdin 监听。重复调用安全。 */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        if (typeof this.stdin.setEncoding ===
+            'function') {
+            ;
+            this.stdin.setEncoding('utf8');
+        }
+        this.stdin.on('data', this.handleChunk);
+        this.stdin.on('end', this.handleInputClosed);
+        this.stdin.on('close', this.handleInputClosed);
+        this.stdin.on('error', this.handleInputError);
+    }
+    /** 停止监听并拒掉所有 pending host 调用。 */
+    stop(reason = 'transport stopped') {
+        if (!this.started)
+            return;
+        this.started = false;
+        this.stdin.off?.('data', this.handleChunk);
+        this.stdin.off?.('end', this.handleInputClosed);
+        this.stdin.off?.('close', this.handleInputClosed);
+        this.stdin.off?.('error', this.handleInputError);
+        for (const [, waiter] of this.pending) {
+            waiter.reject(new errors_1.BppError('PROCESS_EXITED', reason));
+        }
+        this.pending.clear();
+    }
+    /** 写一条 BPP 消息到 stdout。线程安全（Node 单线程，单次 write 是原子的）。 */
+    send(message) {
+        const line = JSON.stringify(message) + '\n';
+        this.stdout.write(line);
+    }
+    /** 写 stderr 日志。stdout 永远只写协议；Brick 身份由宿主日志中心附加。 */
+    log(...parts) {
+        const line = `${parts.map((p) => (typeof p === 'string' ? p : JSON.stringify(p))).join(' ')}\n`;
+        this.stderr.write(line);
+    }
+    /**
+     * 发起一个需要等待 host.result/host.error 回复的 host.* 调用。
+     * 入参省略 id（SDK 自动分配），返回 result 字段。
+     */
+    hostCall(msg) {
+        const id = this.nextId();
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: (v) => resolve(v),
+                reject
+            });
+            this.send({ ...msg, id });
+        });
+    }
+    nextHostId() {
+        return this.nextId();
+    }
+    nextId() {
+        this.idCounter += 1;
+        return `${this.brickId}-${process.pid}-${this.idCounter}`;
+    }
+    handleChunk = (chunk) => {
+        this.buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        const lines = this.buffer.split(/\r?\n/);
+        this.buffer = lines.pop() ?? '';
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch (err) {
+                this.emit('error', new errors_1.BppError('PROTOCOL_ERROR', `Invalid JSON line: ${line}`, { cause: String(err) }));
+                continue;
+            }
+            this.dispatch(msg);
+        }
+    };
+    handleInputClosed = () => {
+        this.emit('end');
+        if (this.exitOnHostDisconnect) {
+            this.emit('host-disconnect', new errors_1.BppError('PROCESS_EXITED', 'host pipe closed'));
+        }
+        this.stop('host pipe closed');
+    };
+    handleInputError = (error) => {
+        this.emit('error', error);
+        if (this.exitOnHostDisconnect) {
+            this.emit('host-disconnect', new errors_1.BppError('PROCESS_EXITED', 'host pipe error', { error }));
+        }
+        this.stop('host pipe error');
+    };
+    dispatch(msg) {
+        // 优先处理 host.* 应答（请求-响应配对）
+        if (msg.type === 'host.invoke.progress' ||
+            msg.type === 'host.invoke.chunk' ||
+            msg.type === 'host.invoke.output') {
+            this.emit('message', msg);
+            return;
+        }
+        if (msg.type === 'host.result') {
+            const waiter = this.pending.get(msg.id);
+            if (waiter) {
+                this.pending.delete(msg.id);
+                waiter.resolve(msg.result);
+                return;
+            }
+            this.emit('message', msg);
+            return;
+        }
+        if (msg.type === 'host.error') {
+            const waiter = this.pending.get(msg.id);
+            if (waiter) {
+                this.pending.delete(msg.id);
+                waiter.reject((0, errors_1.payloadToError)(msg.error));
+                return;
+            }
+            this.emit('message', msg);
+            return;
+        }
+        // 心跳由 transport 自动处理
+        if (msg.type === 'runtime.ping') {
+            this.send({ type: 'runtime.pong', id: msg.id });
+            return;
+        }
+        if (msg.type === 'runtime.shutdown') {
+            this.emit('shutdown');
+            return;
+        }
+        if (msg.type === 'event.notify') {
+            this.emit('event', msg);
+            this.emit('message', msg);
+            return;
+        }
+        if (msg.type === 'command.invoke' || msg.type === 'command.cancel') {
+            this.emit('command', msg);
+            this.emit('message', msg);
+            return;
+        }
+        this.emit('message', msg);
+    }
+}
+exports.BppTransport = BppTransport;

package/dist/typegen-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/typegen-cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const typegen_1 = require("./typegen");
+function main(argv) {
+    const options = parseArgs(argv);
+    const result = (0, typegen_1.generateDependencyTypes)(options);
+    for (const warning of result.warnings) {
+        console.warn(`! ${warning}`);
+    }
+    console.log(`✓ generated ${result.commandCount} command wrapper(s) for ${result.dependencyCount} dependency Brick(s)`);
+    console.log(`  out: ${result.outDir}`);
+    console.log(`  sdk module: ${result.sdkModule}`);
+}
+function parseArgs(argv) {
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--help' || arg === '-h') {
+            printHelp();
+            process.exit(0);
+        }
+        const value = argv[index + 1];
+        if (!value || value.startsWith('-')) {
+            throw new Error(`参数 ${arg} 缺少值。`);
+        }
+        index += 1;
+        switch (arg) {
+            case '--manifest':
+                options.manifestPath = value;
+                break;
+            case '--brick-root':
+                options.brickRoot = value;
+                break;
+            case '--bricks-dir':
+                options.bricksDir = value;
+                break;
+            case '--out':
+                options.outDir = value;
+                break;
+            case '--sdk-module':
+                options.sdkModule = value;
+                break;
+            default:
+                throw new Error(`未知参数：${arg}`);
+        }
+    }
+    return options;
+}
+function printHelp() {
+    console.log(`Usage: brickly-typegen [options]
+
+Options:
+  --manifest <path>     当前 Brick 的 manifest.json，默认 ./manifest.json
+  --brick-root <path>   当前 Brick 根目录，默认 manifest 所在目录
+  --bricks-dir <path>   所有 Brick 所在目录，默认当前 Brick 根目录的父目录
+  --out <path>          输出目录，默认 runtime/node/_generated/deps
+  --sdk-module <name>   CommandMap 扩展的 SDK 模块名，默认自动推导
+  -h, --help            显示帮助
+`);
+}
+try {
+    main(process.argv.slice(2));
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+}

package/dist/typegen.d.ts

@@ -0,0 +1,24 @@
+export interface TypegenOptions {
+    /** 当前 Brick 的 manifest.json 路径。默认读取 cwd/manifest.json。 */
+    manifestPath?: string;
+    /** Brick 根目录。默认取 manifest 所在目录。 */
+    brickRoot?: string;
+    /** 所有 Brick 所在目录。默认取当前 Brick 根目录的父目录。 */
+    bricksDir?: string;
+    /** 已加载依赖 Brick 的真实 manifest 路径索引；优先级高于 bricksDir/<brickId>/manifest.json。 */
+    dependencyManifestPaths?: Record<string, string>;
+    /** 输出目录。默认写到 runtime/node/_generated/deps。 */
+    outDir?: string;
+    /** 生成 CommandMap 扩展时使用的 SDK 模块名。默认自动推导。 */
+    sdkModule?: string;
+}
+export interface TypegenResult {
+    manifestPath: string;
+    outDir: string;
+    sdkModule: string;
+    dependencyCount: number;
+    commandCount: number;
+    files: string[];
+    warnings: string[];
+}
+export declare function generateDependencyTypes(options?: TypegenOptions): TypegenResult;