@trojanbox-vcp-test/site-edit-engine 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# `@trojanbox-vcp-test/site-edit-engine`
+
+VCP 的源码级 site edit 引擎。它读取 snapshot 或项目文件，构建 render
+document / object detail，并把高层编辑操作规划为 patch plan 或直接执行到预览工作区。
+
+## 环境要求
+
+- Node.js `>=24`
+
+## 安装
+
+```bash
+npm install @trojanbox-vcp-test/contracts @trojanbox-vcp-test/site-edit-engine
+```
+
+## 主入口能力
+
+主入口 `@trojanbox-vcp-test/site-edit-engine` 只暴露稳定 runtime facade：
+
+- `createSiteEditEngineRuntime`
+- `SnapshotSiteEditEngineRuntime`
+- `createPreviewSiteEditEngineRuntime`
+- `PreviewFileSystemSiteEditEngineRuntime`
+- 相关 runtime public types
+
+## 子路径
+
+- `@trojanbox-vcp-test/site-edit-engine/next-app-router`
+  Next App Router 路由扫描与 routeId 解析工具。
+- `@trojanbox-vcp-test/site-edit-engine/source-watcher`
+  预览场景使用的源码监听器。
+- `@trojanbox-vcp-test/site-edit-engine/webpack-loader`
+  仅用于 preview / instrumentation 的 webpack loader。
+
+## Snapshot runtime 示例
+
+```ts
+import { createSiteEditEngineRuntime } from "@trojanbox-vcp-test/site-edit-engine";
+
+const runtime = createSiteEditEngineRuntime({
+  siteId: "site_123",
+  snapshotId: "snapshot_123",
+  files: [
+    {
+      path: "app/page.tsx",
+      content: "export default function Page(){return <main>Hello</main>}",
+    },
+  ],
+  routes: [{ routeId: "/", entryFile: "app/page.tsx" }],
+});
+
+const document = runtime.getDocument("/");
+runtime.dispose();
+```
+
+## Preview runtime 示例
+
+```ts
+import { createPreviewSiteEditEngineRuntime } from "@trojanbox-vcp-test/site-edit-engine";
+
+const runtime = createPreviewSiteEditEngineRuntime({
+  siteId: "site_123",
+  snapshotId: "snapshot_123",
+  projectRoot: "/tmp/site",
+  routes: [{ routeId: "/", entryFile: "app/page.tsx" }],
+});
+
+await runtime.setActiveRoute("/");
+runtime.dispose();
+```
+
+## `webpack-loader` 说明
+
+`@trojanbox-vcp-test/site-edit-engine/webpack-loader` 只用于开发态 preview instrumentation，
+负责给 JSX / TSX 注入 VCP 编辑运行时属性。它不是通用的 Webpack / Next.js 插件平台，
+也不承诺覆盖 preview instrumentation 之外的构建场景。
+
+## 非目标
+
+`@trojanbox-vcp-test/site-edit-engine` 不负责：
+
+- 持久化 snapshot 或管理数据库记录
+- 启动或管理 sandbox 生命周期
+- 直接执行生产发布
+- 暴露 `site-edit-bridge` 的 transport / WebSocket server API

package/dist/execute-integration/execute-fixture-harness.d.ts

@@ -0,0 +1,25 @@
+import type { SiteEditOperationErrorCode, SiteEditOperationParams } from "@trojanbox-vcp-test/contracts";
+type FixtureFile = {
+    path: string;
+    content: string;
+};
+type ExecuteFixtureTarget = {
+    kind: "tag";
+    tag: string;
+    index?: number;
+} | {
+    kind: "key";
+    key: string;
+} | {
+    kind: "route";
+    routeId?: string;
+};
+export declare function expectExecuteFixture(input: {
+    files: readonly FixtureFile[];
+    routeId?: string;
+    target: ExecuteFixtureTarget;
+    operation: SiteEditOperationParams;
+    expectedFiles?: readonly FixtureFile[];
+    expectedErrorCode?: SiteEditOperationErrorCode;
+}): Promise<void>;
+export {};

package/dist/execute-integration/execute-fixture-harness.js

@@ -0,0 +1,37 @@
+import { expect } from "vitest";
+import { createSourceWritebackHarness } from "../source-writeback-test-harness.js";
+export async function expectExecuteFixture(input) {
+    const harness = createSourceWritebackHarness({
+        files: [...input.files],
+        routeId: input.routeId,
+    });
+    await harness.setActiveRoute(input.routeId ?? "/");
+    const before = new Map(input.files.map((file) => [file.path, harness.getSource(file.path)]));
+    const result = await executeByTarget(harness, input.target, input.operation);
+    if (input.expectedErrorCode) {
+        expect(result).toMatchObject({
+            ok: false,
+            error: { code: input.expectedErrorCode },
+        });
+        for (const file of input.files) {
+            expect(harness.getSource(file.path)).toBe(before.get(file.path));
+        }
+        return;
+    }
+    expect(result).toMatchObject({ ok: true });
+    for (const expectedFile of input.expectedFiles ?? []) {
+        expect(harness.getSource(expectedFile.path)).toBe(expectedFile.content);
+    }
+}
+async function executeByTarget(harness, target, operation) {
+    if (target.kind === "route") {
+        return harness.executeRouteOperation({
+            routeId: target.routeId,
+            params: operation,
+        });
+    }
+    const key = target.kind === "key"
+        ? target.key
+        : harness.findEntryByTag(target.tag, target.index ?? 0).key;
+    return harness.executeNodeOperation({ key, params: operation });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createSiteEditEngineRuntime, SnapshotSiteEditEngineRuntime, } from "./runtime.js";
+export { createPreviewSiteEditEngineRuntime, PreviewFileSystemSiteEditEngineRuntime, } from "./preview-runtime.js";
+export type { PreviewSiteEditEngineRuntime, PreviewSiteEditEngineRuntimeOptions, SiteEditProjectFileSystem, SiteEditEngineRoute, SiteEditEngineRuntime, SiteEditEngineRuntimeOptions, SiteEditPlanOperationResult, SiteEditSnapshotFile, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createSiteEditEngineRuntime, SnapshotSiteEditEngineRuntime, } from "./runtime.js";
+export { createPreviewSiteEditEngineRuntime, PreviewFileSystemSiteEditEngineRuntime, } from "./preview-runtime.js";

package/dist/internal/ast/diagnostics/index.d.ts

@@ -0,0 +1,5 @@
+import type { AstDiagnostic, AstDiagnosticCode, AstLocatorKind, AstPrimitiveResult, ResolveLocatorResult } from "../types.js";
+export declare function createDiagnostic(code: AstDiagnosticCode, message: string, locatorKind?: AstLocatorKind, details?: Record<string, unknown>): AstDiagnostic;
+export declare function primitiveFailure(source: string, code: AstDiagnosticCode, message: string, locatorKind?: AstLocatorKind, details?: Record<string, unknown>): AstPrimitiveResult;
+export declare function locatorFailure(source: string, code: AstDiagnosticCode, message: string, locatorKind?: AstLocatorKind, details?: Record<string, unknown>): ResolveLocatorResult;
+export declare function parseFailure(source: string, message: string, locatorKind?: AstLocatorKind): AstPrimitiveResult;

package/dist/internal/ast/diagnostics/index.js

@@ -0,0 +1,25 @@
+export function createDiagnostic(code, message, locatorKind, details) {
+    return {
+        code,
+        message,
+        locatorKind,
+        details,
+    };
+}
+export function primitiveFailure(source, code, message, locatorKind, details) {
+    return {
+        ok: false,
+        source,
+        diagnostic: createDiagnostic(code, message, locatorKind, details),
+    };
+}
+export function locatorFailure(source, code, message, locatorKind, details) {
+    return {
+        ok: false,
+        source,
+        diagnostic: createDiagnostic(code, message, locatorKind, details),
+    };
+}
+export function parseFailure(source, message, locatorKind) {
+    return primitiveFailure(source, "parse-failed", message, locatorKind);
+}

package/dist/internal/ast/history/index.d.ts

@@ -0,0 +1,15 @@
+import type { HistoryEntry, OperationDescription } from "../types.js";
+export type { HistoryEntry, OperationDescription } from "../types.js";
+export interface HistoryPushOptions {
+    coalesce?: boolean;
+}
+export interface History {
+    readonly length: number;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    push(operation: OperationDescription, options?: HistoryPushOptions): void;
+    undo(): HistoryEntry | undefined;
+    redo(): HistoryEntry | undefined;
+    current(): HistoryEntry | undefined;
+}
+export declare function createHistory(): History;

package/dist/internal/ast/history/index.js

@@ -0,0 +1,62 @@
+const DEFAULT_COALESCE_WINDOW_MS = 1000;
+export function createHistory() {
+    const past = [];
+    const future = [];
+    return {
+        get length() {
+            return past.length;
+        },
+        canUndo() {
+            return past.length > 0;
+        },
+        canRedo() {
+            return future.length > 0;
+        },
+        push(operation, options) {
+            const timestamp = Date.now();
+            const entry = {
+                operation: { ...operation, timestamp },
+                timestamp,
+            };
+            if (options?.coalesce && past.length > 0) {
+                const lastEntry = past[past.length - 1];
+                if (lastEntry && shouldCoalesce(lastEntry, entry)) {
+                    past[past.length - 1] = entry;
+                    return;
+                }
+            }
+            past.push(entry);
+            future.length = 0;
+        },
+        undo() {
+            const entry = past.pop();
+            if (!entry)
+                return undefined;
+            future.push(entry);
+            return entry;
+        },
+        redo() {
+            const entry = future.pop();
+            if (!entry)
+                return undefined;
+            past.push(entry);
+            return entry;
+        },
+        current() {
+            return past[past.length - 1];
+        },
+    };
+}
+function shouldCoalesce(lastEntry, newEntry) {
+    const lastOperation = lastEntry.operation;
+    const newOperation = newEntry.operation;
+    if (lastOperation.type !== "text-update")
+        return false;
+    if (newOperation.type !== "text-update")
+        return false;
+    if (lastOperation.target !== newOperation.target)
+        return false;
+    if (lastOperation.kind !== newOperation.kind)
+        return false;
+    return newEntry.timestamp - lastEntry.timestamp <= DEFAULT_COALESCE_WINDOW_MS;
+}

package/dist/internal/ast/index.d.ts

@@ -0,0 +1,8 @@
+export type { AstLocator, AstLocatorKind, JsxNodeLocator, JsxAttributeLocator, ValueLocator, ExpressionLocator, DirectiveLocator, ExportLocator, ValuePathSegment, ValueRootSelector, AstDiagnosticCode, AstDiagnostic, AstPrimitiveResult, LocatorMatch, ResolveLocatorResult, PrimitiveValue, SourceRange, Placement, OperationDescription, HistoryEntry, } from "./types.js";
+export type { History, HistoryPushOptions } from "./history/index.js";
+export { resolveLocator } from "./locators/index.js";
+export { printAst } from "./printer/index.js";
+export * from "./primitives/index.js";
+export { createHistory } from "./history/index.js";
+export { detectParserProfile, parseWithProfile, parseForLocator, parseForMutation, } from "./parser/index.js";
+export type { ParseResult, ParserProfile } from "./parser/index.js";

package/dist/internal/ast/index.js

@@ -0,0 +1,5 @@
+export { resolveLocator } from "./locators/index.js";
+export { printAst } from "./printer/index.js";
+export * from "./primitives/index.js";
+export { createHistory } from "./history/index.js";
+export { detectParserProfile, parseWithProfile, parseForLocator, parseForMutation, } from "./parser/index.js";

package/dist/internal/ast/locators/index.d.ts

@@ -0,0 +1 @@
+export { resolveLocator, resolveLocatorPath, type InternalLocatorMatch, } from "./resolve-locator.js";

package/dist/internal/ast/locators/index.js

@@ -0,0 +1 @@
+export { resolveLocator, resolveLocatorPath, } from "./resolve-locator.js";

package/dist/internal/ast/locators/resolve-locator.d.ts

@@ -0,0 +1,16 @@
+import { type NodePath } from "@babel/traverse";
+import type * as t from "@babel/types";
+import type { AstDiagnostic, AstLocator, LocatorMatch, ResolveLocatorResult } from "../types.js";
+export interface InternalLocatorMatch extends LocatorMatch {
+    path: NodePath<any>;
+}
+type InternalResolveResult = {
+    ok: true;
+    match: InternalLocatorMatch;
+} | {
+    ok: false;
+    diagnostic: AstDiagnostic;
+};
+export declare function resolveLocator(source: string, locator: AstLocator): ResolveLocatorResult;
+export declare function resolveLocatorPath(ast: t.File, locator: AstLocator): InternalResolveResult;
+export {};