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

package/dist/internal/runtime.d.ts

@@ -0,0 +1,3 @@
+export { createEditEngineRuntime, EditEngineRuntime, } from "./runtime/EditEngineRuntime.js";
+export type { IEditEngineRuntime } from "./contracts/IEditEngineRuntime.js";
+export type { EditEngineRuntimeOptions, ExternalSourceResolver, ExternalWritebackAdapter, FunctionCallContract, ProjectFileSystem, RuntimeRouteConfig, } from "./runtime/EditEngineRuntimeSnapshot.js";

package/dist/internal/runtime.js

@@ -0,0 +1 @@
+export { createEditEngineRuntime, EditEngineRuntime, } from "./runtime/EditEngineRuntime.js";

package/dist/internal/topology/topology.d.ts

@@ -0,0 +1,6 @@
+import type { RenderSourceGraph } from "../graph/types.js";
+import type { EditableTopology } from "./types.js";
+/**
+ * 从渲染源图构建可编辑拓扑。
+ */
+export declare function buildEditableTopology(renderGraph: RenderSourceGraph): EditableTopology;

package/dist/internal/topology/topology.js

@@ -0,0 +1,98 @@
+// ─── Topology Builder ────────────────────────────────
+// 来源: docs/06-development-checklist.md §5
+//
+// 从 RenderSourceGraph 构建 EditableTopology。
+// 职责:
+//   - 计算 writeTarget（处理 component boundary 代理写回）
+//   - 标记 boundary regions
+//   - 收集 constraints（repeat/conditional/opaque/component-boundary）
+//
+// 关键约束:
+//   - canMove / canInsertChild 不能被误算成 same-file only
+//   - repeat/template 节点的限制必须显式通过 constraint 返回
+/**
+ * 从渲染源图构建可编辑拓扑。
+ */
+export function buildEditableTopology(renderGraph) {
+    const nodes = new Map();
+    // Build topology node for each element
+    for (const [key, element] of renderGraph.elements) {
+        const isComponent = /^[A-Z]/.test(element.tag);
+        // Compute writeTarget
+        const writeTarget = {
+            file: element.sourceFile,
+            componentName: element.componentName,
+            isProxy: isComponent, // component calls are proxies
+        };
+        // Determine boundary kind
+        const boundaryKind = element.boundaryKind;
+        // Collect constraints
+        const constraints = [];
+        // Opaque component constraint
+        if (element.isOpaque) {
+            constraints.push({
+                kind: "opaque-region",
+                reason: `Component '${element.tag}' is opaque: internal structure not editable`,
+            });
+        }
+        // Component boundary constraint
+        if (isComponent && !element.isOpaque) {
+            constraints.push({
+                kind: "component-boundary",
+                reason: `Component '${element.tag}' boundary: editing requires source file access`,
+            });
+        }
+        const topologyNode = {
+            key,
+            writeTarget,
+            boundaryKind,
+            parentKey: element.parentKey,
+            childKeys: [...element.childKeys],
+            constraints,
+        };
+        nodes.set(key, topologyNode);
+    }
+    // Add region-based constraints
+    for (const region of renderGraph.regions) {
+        const constraintKind = region.kind === "repeat-region"
+            ? "repeat-region"
+            : region.kind === "conditional-region"
+                ? "conditional-region"
+                : region.kind === "opaque-region"
+                    ? "opaque-region"
+                    : "component-boundary";
+        const reason = region.kind === "repeat-region"
+            ? "Node is inside a repeat region: operations affect the template, not individual instances"
+            : region.kind === "conditional-region"
+                ? "Node is inside a conditional region: visibility depends on runtime condition"
+                : `Node is inside a ${region.kind}`;
+        // Add constraint to all child keys in this region
+        for (const childKey of region.childKeys) {
+            const node = nodes.get(childKey);
+            if (node) {
+                node.constraints.push({ kind: constraintKind, reason });
+            }
+            // Also propagate to descendants of this child
+            propagateRegionConstraint(childKey, constraintKind, reason, nodes, renderGraph);
+        }
+    }
+    return {
+        nodes,
+        rootKeys: [...renderGraph.rootKeys],
+    };
+}
+/**
+ * 递归向下传播区域约束。
+ */
+function propagateRegionConstraint(parentKey, kind, reason, nodes, graph) {
+    const element = graph.elements.get(parentKey);
+    if (!element)
+        return;
+    for (const childKey of element.childKeys) {
+        const childNode = nodes.get(childKey);
+        if (childNode && !childNode.constraints.some((c) => c.kind === kind)) {
+            childNode.constraints.push({ kind, reason });
+            propagateRegionConstraint(childKey, kind, reason, nodes, graph);
+        }
+    }
+}

package/dist/internal/topology/types.d.ts

@@ -0,0 +1,35 @@
+import type { BoundaryKind, ConstraintKind } from "../protocol.js";
+/**
+ * 拓扑节点 —— 描述一个节点在可编辑拓扑中的位置和特性。
+ */
+export interface TopologyNode {
+    key: string;
+    /** 写回的目标文件（可能与 sourceFile 不同，如 component boundary 场景） */
+    writeTarget: WriteTarget;
+    /** 所属边界类型 */
+    boundaryKind: BoundaryKind | null;
+    /** 父节点 key */
+    parentKey: string | null;
+    /** 子节点 keys */
+    childKeys: string[];
+    /** 此节点的约束 */
+    constraints: Array<{
+        kind: ConstraintKind;
+        reason: string;
+    }>;
+}
+/**
+ * 写回目标 —— 描述实际写回的文件和位置。
+ */
+export interface WriteTarget {
+    file: string;
+    componentName: string;
+    isProxy: boolean;
+}
+/**
+ * 可编辑拓扑 —— 完整的拓扑视图。
+ */
+export interface EditableTopology {
+    nodes: Map<string, TopologyNode>;
+    rootKeys: string[];
+}

package/dist/internal/topology/types.js

@@ -0,0 +1,5 @@
+// ─── Topology 模块类型 ───────────────────────────────
+// 来源: docs/06-development-checklist.md §5
+//
+// topology 从 graph 计算可编辑拓扑。
+export {};

package/dist/internal/types.d.ts

@@ -0,0 +1 @@
+export type { SiteEditProjectFileSystem as ProjectFileSystem } from "../public-file-system.js";

package/dist/internal/types.js

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

package/dist/internal/writeback/in-memory-fs.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectFileSystem } from "./types.js";
+export declare function createInMemoryFileSystem(initialFiles?: Record<string, string>): ProjectFileSystem & {
+    /** 同步版本的 readFile（测试中断言用） */
+    readFileSync(file: string): string;
+    /** 获取所有文件内容 */
+    getAll(): Record<string, string>;
+};

package/dist/internal/writeback/in-memory-fs.js

@@ -0,0 +1,44 @@
+// ── InMemoryFileSystem ─────────────────────────────────────────
+// 用于测试的内存文件系统实现。
+// Layer 1/2 测试不依赖真实 FS。
+export function createInMemoryFileSystem(initialFiles = {}) {
+    const files = new Map(Object.entries(initialFiles));
+    const versions = new Map();
+    // 初始化版本号
+    for (const file of files.keys()) {
+        versions.set(file, 1);
+    }
+    return {
+        async readFile(file) {
+            const content = files.get(file);
+            if (content === undefined) {
+                throw new Error(`File not found: ${file}`);
+            }
+            return content;
+        },
+        async writeFile(file, content) {
+            files.set(file, content);
+        },
+        async exists(file) {
+            return files.has(file);
+        },
+        getVersion(file) {
+            return versions.get(file) ?? 0;
+        },
+        bumpVersion(file) {
+            const v = (versions.get(file) ?? 0) + 1;
+            versions.set(file, v);
+            return v;
+        },
+        readFileSync(file) {
+            const content = files.get(file);
+            if (content === undefined) {
+                throw new Error(`File not found: ${file}`);
+            }
+            return content;
+        },
+        getAll() {
+            return Object.fromEntries(files);
+        },
+    };
+}

package/dist/internal/writeback/types.d.ts

@@ -0,0 +1,45 @@
+import type { FileSnapshot, OperationResult, RewritePlan } from "../planner/types.js";
+import type { RewriteStep_InvokeExternalAdapter } from "../planner/types.js";
+import type { ExternalAdapterCapability, ExternalSourceKind } from "../provenance/types.js";
+export type { ProjectFileSystem } from "../types.js";
+export type { FileSnapshot } from "../planner/types.js";
+export type WritebackResult = {
+    ok: true;
+    /** 变更后各文件的最新内容 */
+    updatedFiles: Map<string, string>;
+    /** 新的文档版本号 */
+    resultVersion: number;
+} | {
+    ok: false;
+    reason: string;
+    /** 是否已成功回滚 */
+    rolledBack: boolean;
+};
+/** 一次操作的 undo 记录 */
+export interface UndoEntry {
+    operationId: string;
+    /** 执行前的文件快照 */
+    preSnapshots: FileSnapshot[];
+    /** 执行后的文件快照 */
+    postSnapshots: FileSnapshot[];
+    /** 操作的 plan（用于 redo 时重放） */
+    plan: RewritePlan;
+}
+export interface WritebackService {
+    execute(plan: RewritePlan): Promise<OperationResult>;
+    undo(): Promise<OperationResult>;
+    redo(): Promise<OperationResult>;
+}
+export interface ExternalAdapterResult {
+    ok: boolean;
+    reason?: string;
+}
+export interface ExternalWritebackAdapter {
+    sourceType: ExternalSourceKind;
+    adapterId?: string;
+    capabilities?: ExternalAdapterCapability[];
+    execute(step: RewriteStep_InvokeExternalAdapter): Promise<ExternalAdapterResult>;
+}
+export interface WritebackServiceOptions {
+    externalAdapters?: ExternalWritebackAdapter[];
+}

package/dist/internal/writeback/types.js

@@ -0,0 +1,7 @@
+// ── Writeback / Undo / Redo 类型 ──────────────────────────────
+// 根文档 03 §5 定义：
+//   - 先做 documentVersion stale check
+//   - 按 steps[].order 顺序执行
+//   - 任一步失败，按 preSnapshots 回滚
+//   - Undo/Redo 基于 operation-level snapshot
+export {};

package/dist/internal/writeback/writeback-service.d.ts

@@ -0,0 +1,7 @@
+import type { RewritePlan, OperationResult } from "../planner/types.js";
+import type { ProjectFileSystem, WritebackServiceOptions } from "./types.js";
+export declare function createWritebackService(fs: ProjectFileSystem, options?: WritebackServiceOptions): {
+    execute: (plan: RewritePlan) => Promise<OperationResult>;
+    undo: () => Promise<OperationResult>;
+    redo: () => Promise<OperationResult>;
+};