@chatu-ai/builder-sdk-mock 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chatu-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @chatu-ai/builder-sdk-mock
+
+Scripted `BuilderClient` for developing UIs against [`@chatu-ai/builder-sdk`](https://www.npmjs.com/package/@chatu-ai/builder-sdk) without a backend: event replay with configurable latency and disconnect injection. Same event schema as core, so swapping in the real client needs no glue.
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * createMockBuilderClient —— 按脚本回放事件序列（08 §6）。
+ * 支持延时与断线注入；断线后 resubscribe 从 lastSeq 续传（与真实服务端语义一致），
+ * 因此 UI 对 mock 与真实 client 的行为观感完全相同。
+ */
+import type { BuilderClient, BuilderEvent, FileNode, SandboxStatus } from '@chatu-ai/builder-sdk';
+export interface MockScriptStep {
+    event: BuilderEvent;
+    delayMs?: number;
+    /** 在该步之后注入一次断线（验证 resubscribe/seq 去重） */
+    dropConnectionAfter?: boolean;
+}
+export interface MockScript {
+    name: string;
+    steps: MockScriptStep[];
+    /** 初始文件树（fileDiff 事件会在其上演进） */
+    initialTree?: FileNode[];
+}
+export interface MockBuilderClient extends BuilderClient {
+    /** 测试辅助：当前沙箱状态（随 preview 事件演进） */
+    readonly currentStatus: SandboxStatus;
+}
+export declare function createMockBuilderClient(script: MockScript): MockBuilderClient;
+export * from './scenarios';

package/dist/index.js

@@ -0,0 +1,82 @@
+import { resilientStream } from '@chatu-ai/builder-sdk';
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+export function createMockBuilderClient(script) {
+    let status = { state: 'creating' };
+    const versions = [];
+    let tree = script.initialTree ?? [];
+    let dropped = false; // 每脚本只断线一次
+    function applySideEffects(ev) {
+        if (ev.kind === 'ack')
+            status = { state: ev.sandbox.state, previewUrl: ev.sandbox.previewUrl };
+        if (ev.kind === 'preview')
+            status = {
+                ...status,
+                state: ev.state === 'ready' ? 'ready' : status.state,
+                previewUrl: ev.url ?? status.previewUrl,
+                devServer: { running: ev.state === 'ready', lastError: ev.error ?? undefined },
+            };
+        if (ev.kind === 'version')
+            versions.unshift({
+                sha: ev.sha, message: ev.message, filesChanged: ev.filesChanged, createdAt: new Date().toISOString(),
+            });
+        if (ev.kind === 'fileDiff')
+            tree = upsertPath(tree, ev.path, ev.action === 'delete');
+    }
+    async function* replay(fromSeq) {
+        for (const step of script.steps) {
+            const ev = step.event;
+            if (ev.kind !== 'ack' && ev.seq <= fromSeq)
+                continue; // 服务端回放语义
+            if (step.delayMs)
+                await sleep(step.delayMs);
+            applySideEffects(ev);
+            yield ev;
+            if (step.dropConnectionAfter && !dropped) {
+                dropped = true;
+                throw new Error('mock: connection dropped');
+            }
+        }
+    }
+    const stream = (fromSeq) => resilientStream({ open: () => replay(fromSeq), reopen: seq => replay(seq) }, { baseDelayMs: 10 });
+    return {
+        get currentStatus() { return status; },
+        chat: {
+            stream: () => stream(0),
+            resubscribe: (_c, _x, lastSeq) => stream(lastSeq),
+            cancel: async () => { status = { ...status, state: 'ready' }; },
+        },
+        sandbox: {
+            status: async () => status,
+            heartbeat: async () => { },
+            previewToken: async () => ({ token: 'mock-token', previewUrl: `${status.previewUrl ?? ''}/?t=mock-token` }),
+            wake: async () => { status = { ...status, state: 'ready' }; return status; },
+        },
+        versions: {
+            list: async () => versions,
+            restore: async (_id, sha) => {
+                const i = versions.findIndex(v => v.sha === sha);
+                if (i < 0)
+                    throw new Error(`mock: unknown version ${sha}`);
+                versions.splice(0, i); // 回滚 = 丢弃更新的版本
+            },
+        },
+        files: {
+            tree: async () => tree,
+            read: async (_id, path) => `// mock content of ${path}\n`,
+            downloadUrl: () => 'https://mock.invalid/download.zip',
+        },
+    };
+}
+/** 极简树维护：仅保证 path 出现/消失，目录按需创建 */
+function upsertPath(tree, path, remove) {
+    const [head, ...rest] = path.split('/');
+    const next = tree.filter(n => n.path !== head);
+    if (remove && rest.length === 0)
+        return next;
+    const existing = tree.find(n => n.path === head);
+    if (rest.length === 0)
+        return [...next, { path: head, type: 'file' }];
+    const dir = existing?.type === 'dir' ? existing : { path: head, type: 'dir', children: [] };
+    return [...next, { ...dir, children: upsertPath(dir.children ?? [], rest.join('/'), remove) }];
+}
+export * from './scenarios';

package/dist/mock.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mock.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { createMockBuilderClient, scenario1, scenario2 } from './index';
+async function collect(src) {
+    const out = [];
+    for await (const e of src)
+        out.push(e);
+    return out;
+}
+describe('mock client', () => {
+    it('replays scenario1 completely and updates status/versions/tree', async () => {
+        const client = createMockBuilderClient(structuredClone(scenario1));
+        const events = await collect(client.chat.stream('c1', 'make a landing page'));
+        expect(events.at(0)?.kind).toBe('ack');
+        expect(events.at(-1)).toMatchObject({ kind: 'done', state: 'completed' });
+        expect(client.currentStatus.state).toBe('ready');
+        expect(client.currentStatus.devServer?.running).toBe(true);
+        expect(await client.versions.list('c1')).toHaveLength(1);
+        const tree = await client.files.tree('c1');
+        expect(tree.find(n => n.path === 'app')).toBeTruthy();
+    });
+    it('scenario2 survives injected disconnect with no gaps or dupes', async () => {
+        const client = createMockBuilderClient(structuredClone(scenario2));
+        const events = await collect(client.chat.stream('c1', 'change color'));
+        const seqs = events.filter(e => e.kind !== 'ack').map(e => e.seq);
+        expect(seqs).toEqual([1, 2, 3, 4, 5, 6]); // 断线后续传，无重无漏
+        expect(events.at(-1)?.kind).toBe('done');
+    });
+    it('restore rolls back version list', async () => {
+        const client = createMockBuilderClient(structuredClone(scenario1));
+        await collect(client.chat.stream('c1', 'x'));
+        await client.versions.restore('c1', 'aaa111');
+        expect((await client.versions.list('c1'))[0]?.sha).toBe('aaa111');
+    });
+});

package/dist/scenarios.d.ts

@@ -0,0 +1,6 @@
+/** 内置脚本：DoD 场景 1（生成落地页）与场景 2（增量修改+断线注入）。 */
+import type { MockScript } from './index';
+/** DoD 场景 1：prompt → 任务卡渐进 → 文件生成 → 预览就绪 → 版本 → done */
+export declare const scenario1: MockScript;
+/** DoD 场景 2：增量修改（改主色）+ 中途断线（验证重连与 seq 去重） */
+export declare const scenario2: MockScript;

package/dist/scenarios.js

@@ -0,0 +1,39 @@
+const X = 'xid-mock-1';
+const PREVIEW = 'https://sbx-mock.n.example.com';
+/** DoD 场景 1：prompt → 任务卡渐进 → 文件生成 → 预览就绪 → 版本 → done */
+export const scenario1 = {
+    name: 'dod-1-landing-page',
+    steps: [
+        { event: { kind: 'ack', xid: X, seq: 0, sandbox: { sandboxId: 'sbx-mock', state: 'warming', previewUrl: PREVIEW } } },
+        { event: { kind: 'taskCard', xid: X, seq: 1, id: 'tc1', label: '初始化模板', state: 'running' }, delayMs: 300 },
+        { event: { kind: 'taskCard', xid: X, seq: 2, id: 'tc1', label: '初始化模板', state: 'done' }, delayMs: 500 },
+        { event: { kind: 'taskCard', xid: X, seq: 3, id: 'tc2', label: '生成页面', state: 'running' }, delayMs: 200 },
+        { event: { kind: 'message', xid: X, seq: 4, role: 'assistant', text: '正在为你创建产品落地页，包含 Hero、特性与 CTA 区块……' }, delayMs: 300 },
+        { event: { kind: 'fileDiff', xid: X, seq: 5, path: 'app/page.tsx', action: 'create', bytes: 4096, truncated: false, diff: '+ export default function Landing() { ... }' }, delayMs: 600 },
+        { event: { kind: 'fileDiff', xid: X, seq: 6, path: 'components/hero.tsx', action: 'create', bytes: 2048, truncated: false }, delayMs: 400 },
+        { event: { kind: 'taskCard', xid: X, seq: 7, id: 'tc2', label: '生成页面', state: 'done' }, delayMs: 200 },
+        { event: { kind: 'taskCard', xid: X, seq: 8, id: 'tc3', label: '启动开发服务器', state: 'running' }, delayMs: 300 },
+        { event: { kind: 'preview', xid: X, seq: 9, state: 'starting' }, delayMs: 800 },
+        { event: { kind: 'preview', xid: X, seq: 10, state: 'ready', url: PREVIEW }, delayMs: 700 },
+        { event: { kind: 'taskCard', xid: X, seq: 11, id: 'tc3', label: '启动开发服务器', state: 'done' } },
+        { event: { kind: 'version', xid: X, seq: 12, sha: 'aaa111', message: 'create landing page', filesChanged: 2 }, delayMs: 200 },
+        { event: { kind: 'done', xid: X, seq: 13, state: 'completed' } },
+    ],
+};
+/** DoD 场景 2：增量修改（改主色）+ 中途断线（验证重连与 seq 去重） */
+export const scenario2 = {
+    name: 'dod-2-incremental-with-drop',
+    initialTree: [
+        { path: 'app', type: 'dir', children: [{ path: 'page.tsx', type: 'file' }] },
+        { path: 'components', type: 'dir', children: [{ path: 'hero.tsx', type: 'file' }] },
+    ],
+    steps: [
+        { event: { kind: 'ack', xid: X, seq: 0, sandbox: { sandboxId: 'sbx-mock', state: 'ready', previewUrl: PREVIEW } } },
+        { event: { kind: 'taskCard', xid: X, seq: 1, id: 'tc1', label: '定位样式定义', state: 'running' }, delayMs: 300 },
+        { event: { kind: 'taskCard', xid: X, seq: 2, id: 'tc1', label: '定位样式定义', state: 'done' }, delayMs: 400, dropConnectionAfter: true },
+        { event: { kind: 'fileDiff', xid: X, seq: 3, path: 'app/globals.css', action: 'modify', bytes: 512, truncated: false, diff: '- --primary: blue\n+ --primary: green' }, delayMs: 300 },
+        { event: { kind: 'preview', xid: X, seq: 4, state: 'ready', url: PREVIEW }, delayMs: 400 },
+        { event: { kind: 'version', xid: X, seq: 5, sha: 'bbb222', message: 'change primary color to green', filesChanged: 1 } },
+        { event: { kind: 'done', xid: X, seq: 6, state: 'completed' } },
+    ],
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@chatu-ai/builder-sdk-mock",
+  "version": "0.1.0",
+  "description": "Mock BuilderClient for @chatu-ai/builder-sdk: scripted event replay with latency & disconnect injection",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chatu-ai/chatu-builder-sdk.git",
+    "directory": "packages/mock"
+  },
+  "homepage": "https://github.com/chatu-ai/chatu-builder-sdk/tree/main/packages/mock#readme",
+  "bugs": "https://github.com/chatu-ai/chatu-builder-sdk/issues",
+  "keywords": [
+    "chatu",
+    "builder",
+    "ai",
+    "app-builder",
+    "sdk",
+    "mock",
+    "testing"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@chatu-ai/builder-sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}