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

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

@@ -0,0 +1,275 @@
+import type { DirectiveLocator, ExportLocator, JsxAttributeLocator, JsxNodeLocator, Placement, PrimitiveValue, ValueLocator, ValuePathSegment, ValueRootSelector } from "../ast/index.js";
+import type { OperationTarget as ProtocolOperationTarget, OperationRequest as ProtocolOperationRequest, OperationType as ProtocolOperationType, OperationValue as ProtocolOperationValue } from "../protocol.js";
+import type { ExternalAdapterCapability } from "../provenance/types.js";
+export type ExternalSourceKind = "api-field" | "cms-field" | "i18n-message" | "config-entry";
+export type OperationType = ProtocolOperationType;
+export type OperationTarget = ProtocolOperationTarget;
+export type OperationValue = ProtocolOperationValue;
+/**
+ * protocol-facing 请求 — planner 的输入。
+ * targetKey 是 protocol 层 key，不是 source position。
+ */
+export type OperationRequest = ProtocolOperationRequest;
+/**
+ * RewriteStep 是 planner 展开后的执行形状。
+ * 到了这一步，所有 locator / jsx / import 变更已经确定。
+ * writeback 照着执行即可，不需要反查 graph。
+ */
+export type RewriteStep = RewriteStep_UpdateText | RewriteStep_UpdateValue | RewriteStep_SetObjectField | RewriteStep_InsertObjectField | RewriteStep_RemoveObjectField | RewriteStep_UpdateArrayItem | RewriteStep_InsertArrayItem | RewriteStep_RemoveArrayItem | RewriteStep_MoveArrayItem | RewriteStep_ReplaceConditionalExpression | RewriteStep_SetConditionalBranchContent | RewriteStep_RemoveNode | RewriteStep_InsertChild | RewriteStep_MoveNode | RewriteStep_SetJsxProp | RewriteStep_RemoveJsxProp | RewriteStep_SetClassName | RewriteStep_AddClassToken | RewriteStep_RemoveClassToken | RewriteStep_SetStyleProperty | RewriteStep_SetStyleProperties | RewriteStep_SetCssModuleClass | RewriteStep_SetDirective | RewriteStep_RemoveDirective | RewriteStep_SetRouteExport | RewriteStep_SetMetadataField | RewriteStep_SetGenerateMetadata | RewriteStep_InvokeExternalAdapter | RewriteStep_AddImport | RewriteStep_RemoveImport;
+interface RewriteStepBase {
+    /** 步骤序号，writeback 按此顺序执行 */
+    order: number;
+    /** 目标文件路径 */
+    file: string;
+}
+export interface RewriteStep_UpdateText extends RewriteStepBase {
+    type: "update-text";
+    locator: JsxNodeLocator;
+    segmentIndex: number;
+    newText: string;
+}
+export interface RewriteStep_UpdateValue extends RewriteStepBase {
+    type: "update-value";
+    locator: ValueLocator;
+    value: PrimitiveValue;
+}
+export interface RewriteStep_SetObjectField extends RewriteStepBase {
+    type: "set-object-field";
+    locator: ValueLocator;
+    value: PrimitiveValue;
+}
+export interface RewriteStep_InsertObjectField extends RewriteStepBase {
+    type: "insert-object-field";
+    locator: ValueLocator;
+    field: string;
+    value: PrimitiveValue;
+}
+export interface RewriteStep_RemoveObjectField extends RewriteStepBase {
+    type: "remove-object-field";
+    locator: ValueLocator;
+    field: string;
+}
+export interface RewriteStep_UpdateArrayItem extends RewriteStepBase {
+    type: "update-array-item";
+    locator: ValueLocator;
+    value: PrimitiveValue;
+}
+export interface RewriteStep_InsertArrayItem extends RewriteStepBase {
+    type: "insert-array-item";
+    locator: ValueLocator;
+    index: number;
+    value: PrimitiveValue;
+}
+export interface RewriteStep_RemoveArrayItem extends RewriteStepBase {
+    type: "remove-array-item";
+    locator: ValueLocator;
+    index: number;
+}
+export interface RewriteStep_MoveArrayItem extends RewriteStepBase {
+    type: "move-array-item";
+    locator: ValueLocator;
+    fromIndex: number;
+    toIndex: number;
+}
+export interface RewriteStep_ReplaceConditionalExpression extends RewriteStepBase {
+    type: "replace-conditional-expression";
+    locator: JsxNodeLocator;
+    nextExpression: string;
+}
+export interface RewriteStep_SetConditionalBranchContent extends RewriteStepBase {
+    type: "set-conditional-branch-content";
+    locator: JsxNodeLocator;
+    branch: "then" | "else";
+    content: {
+        jsx: string;
+    };
+}
+export interface RewriteStep_RemoveNode extends RewriteStepBase {
+    type: "remove-node";
+    locator: JsxNodeLocator;
+    removeWhitespace?: boolean;
+}
+export interface RewriteStep_InsertChild extends RewriteStepBase {
+    type: "insert-child";
+    parentLocator: JsxNodeLocator;
+    node: {
+        jsx: string;
+    };
+    placement: Placement;
+    anchorLocator?: JsxNodeLocator;
+}
+export interface RewriteStep_MoveNode extends RewriteStepBase {
+    type: "move-node";
+    locator: JsxNodeLocator;
+    targetParentLocator: JsxNodeLocator;
+    placement: Placement;
+    anchorLocator?: JsxNodeLocator;
+}
+export interface RewriteStep_SetJsxProp extends RewriteStepBase {
+    type: "set-jsx-prop";
+    locator: JsxAttributeLocator;
+    value: OperationValue;
+}
+export interface RewriteStep_RemoveJsxProp extends RewriteStepBase {
+    type: "remove-jsx-prop";
+    locator: JsxAttributeLocator;
+}
+export interface RewriteStep_SetClassName extends RewriteStepBase {
+    type: "set-class-name";
+    locator: JsxAttributeLocator;
+    value: string;
+}
+export interface RewriteStep_AddClassToken extends RewriteStepBase {
+    type: "add-class-token";
+    locator: JsxAttributeLocator;
+    token: string;
+}
+export interface RewriteStep_RemoveClassToken extends RewriteStepBase {
+    type: "remove-class-token";
+    locator: JsxAttributeLocator;
+    token: string;
+}
+export interface RewriteStep_SetStyleProperty extends RewriteStepBase {
+    type: "set-style-property";
+    locator: JsxAttributeLocator;
+    property: string;
+    value: OperationValue;
+}
+export interface RewriteStep_SetStyleProperties extends RewriteStepBase {
+    type: "set-style-properties";
+    locator: JsxAttributeLocator;
+    properties: Record<string, OperationValue>;
+}
+export interface RewriteStep_SetCssModuleClass extends RewriteStepBase {
+    type: "set-css-module-class";
+    locator: JsxAttributeLocator;
+    from: string;
+    to: string;
+}
+export interface RewriteStep_SetDirective extends RewriteStepBase {
+    type: "set-directive";
+    mode: "add" | "update";
+    value: DirectiveLocator["value"];
+    currentValue?: DirectiveLocator["value"];
+}
+export interface RewriteStep_RemoveDirective extends RewriteStepBase {
+    type: "remove-directive";
+    value: DirectiveLocator["value"];
+}
+export interface RewriteStep_SetRouteExport extends RewriteStepBase {
+    type: "set-route-export";
+    name: Extract<ExportLocator, {
+        exportKind: "named";
+    }>["name"];
+    value: OperationValue;
+}
+export interface RewriteStep_SetMetadataField extends RewriteStepBase {
+    type: "set-metadata-field";
+    field: string;
+    value: OperationValue | null;
+}
+export interface RewriteStep_SetGenerateMetadata extends RewriteStepBase {
+    type: "set-generate-metadata";
+    field: string;
+    value: OperationValue | null;
+}
+export interface RewriteStep_InvokeExternalAdapter extends RewriteStepBase {
+    type: "invoke-external-adapter";
+    sourceType: ExternalSourceKind;
+    sourceId: string;
+    adapterId?: string;
+    capability?: ExternalAdapterCapability;
+    value: OperationValue;
+}
+export interface RewriteStep_AddImport extends RewriteStepBase {
+    type: "add-import";
+    moduleSpecifier: string;
+    imports: Array<{
+        kind: "named";
+        imported: string;
+        local?: string;
+    } | {
+        kind: "default";
+        local: string;
+    } | {
+        kind: "namespace";
+        local: string;
+    }>;
+}
+export interface RewriteStep_RemoveImport extends RewriteStepBase {
+    type: "remove-import";
+    moduleSpecifier: string;
+    imports: Array<{
+        kind: "named";
+        imported: string;
+    } | {
+        kind: "default";
+    } | {
+        kind: "namespace";
+    }>;
+}
+export interface FileSnapshot {
+    file: string;
+    content: string;
+    version: number;
+}
+export type ResolvedTextWriteTarget = {
+    kind: "value-binding";
+    file: string;
+    locator: ValueLocator | null;
+    root?: ValueRootSelector;
+    path?: ValuePathSegment[];
+    displayExpression: string;
+    sourceKind: "literal" | "binding" | "imported-binding" | "repeat-template";
+    collectionIndexMap?: number[];
+    collectionPathMap?: ValuePathSegment[][];
+} | {
+    kind: "external-entry";
+    file: string;
+    sourceType: ExternalSourceKind;
+    sourceId: string;
+    adapterId?: string;
+    displayExpression: string;
+};
+export interface NodeCapabilitySnapshot {
+    key: string;
+    canUpdateText: boolean;
+    canRemove: boolean;
+    canInsertChild: boolean;
+    canMove: boolean;
+    constraints: string[];
+}
+/**
+ * RewritePlan = planner 的完整产物。
+ * writeback 接收到 plan 后按 steps 顺序执行。
+ */
+export interface RewritePlan {
+    /** 操作唯一 ID */
+    operationId: string;
+    /** 操作类型 */
+    kind: OperationType;
+    /** 协议层目标 */
+    target: OperationTarget;
+    /** 请求时的文档版本号 */
+    documentVersion: number;
+    /** 按顺序执行的步骤 */
+    steps: RewriteStep[];
+    /** 涉及文件的快照（用于 rollback） */
+    preSnapshots: FileSnapshot[];
+    /** 经过校验的能力快照 */
+    validatedCapability?: NodeCapabilitySnapshot;
+}
+export type OperationResult = {
+    ok: true;
+    operationId: string;
+    resultVersion: number;
+    affectedFiles: string[];
+} | {
+    ok: false;
+    operationId: string;
+    errorCode: OperationErrorCode;
+    reason: string;
+    rolledBack?: boolean;
+};
+export type OperationErrorCode = "stale-version" | "capability-denied" | "invalid-params" | "locator-miss" | "route-not-found" | "unsupported-operation" | "invalid-target" | "ast-error" | "writeback-failed" | "rollback-failed" | "unknown";
+export {};

package/dist/internal/planner/types.js

@@ -0,0 +1,6 @@
+// ── RewritePlan / RewriteStep 形状 ─────────────────────────────
+// 根文档 03 §4 定义：
+//   - RewritePlan 是 planner 的产物
+//   - RewriteStep 是执行形状，不是请求形状
+//   - writeback 不再反查 graph、不再把 request 重新解释
+export {};

package/dist/internal/protocol/boundary.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 边界种类 —— 标记节点所处的语义边界。
+ *
+ * - component-boundary: 组件调用边界
+ * - repeat-region: .map() / repeat 区域
+ * - conditional-region: 条件渲染区域
+ * - fragment-region: Fragment 包裹
+ * - opaque-region: 不透明 / 外部组件
+ */
+export type BoundaryKind = "component-boundary" | "repeat-region" | "conditional-region" | "fragment-region" | "opaque-region";

package/dist/internal/protocol/boundary.js

@@ -0,0 +1,3 @@
+// ─── Boundary 契约 ────────────────────────────────────
+// 来源: docs/02-contracts-and-protocol.md §6.2
+export {};

package/dist/internal/protocol/capability.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 节点能力快照 —— 描述该节点支持的操作及约束。
+ *
+ * 重要：canMove = true 意味着支持 reorder / reparent / cross-file move，
+ * 不能被收窄为 "只能同级上下移动"。
+ * canInsertChild = true 意味着支持 native-tag 和 component-call 插入，
+ * 不能被收窄为 "只能插入 button"。
+ */
+export interface NodeCapabilitySnapshot {
+    key: string;
+    canUpdateText: boolean;
+    canInsertChild: boolean;
+    canMove: boolean;
+    canRemove: boolean;
+    editModes?: {
+        updateText?: CapabilityModeView;
+        insertChild?: CapabilityModeView;
+        move?: CapabilityModeView;
+        remove?: CapabilityModeView;
+    };
+    constraints: CapabilityConstraint[];
+}
+export interface CapabilityModeView {
+    mode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+    reasonCode?: string;
+}
+/**
+ * 能力约束 —— 描述为什么某个操作受限。
+ */
+export interface CapabilityConstraint {
+    kind: ConstraintKind;
+    message: string;
+}
+/**
+ * 约束种类枚举。
+ *
+ * 每个 kind 对应一种语义限制：
+ * - component-boundary: 跨组件边界操作需要特殊处理
+ * - repeat-region: repeat/map 区域内的限制
+ * - conditional-region: 条件渲染区域限制
+ * - opaque-region: 不透明组件内部不可编辑
+ * - void-element: 自闭合元素不能有子节点
+ * - read-only: 只读数据源
+ * - cross-file-required: 操作需要跨文件协调
+ * - import-required: 组件插入需要添加 import
+ */
+export type ConstraintKind = "component-boundary" | "repeat-region" | "conditional-region" | "opaque-region" | "void-element" | "read-only" | "cross-file-required" | "import-required";

package/dist/internal/protocol/capability.js

@@ -0,0 +1,8 @@
+// ─── Capability 契约 ──────────────────────────────────
+// 来源: docs/02-contracts-and-protocol.md §4
+//
+// 关键约束:
+//   canMove 不能被解释为只有同级排序
+//   canInsertChild 不能被解释为只有 native tag
+//   repeat / boundary / opaque 的限制必须显式通过 constraint 返回
+export {};

package/dist/internal/protocol/error.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 操作错误码枚举 —— 覆盖从节点查找到写回的所有失败路径。
+ */
+export declare enum OperationErrorCode {
+    /** 目标节点 key 在 graph 中不存在 */
+    NODE_NOT_FOUND = "NODE_NOT_FOUND",
+    /** 目标路由不存在 */
+    ROUTE_NOT_FOUND = "ROUTE_NOT_FOUND",
+    /** capability 检查拒绝（如 canMove = false） */
+    CAPABILITY_REJECTED = "CAPABILITY_REJECTED",
+    /** 约束违反（如试图往 void element 插入子节点） */
+    CONSTRAINT_VIOLATED = "CONSTRAINT_VIOLATED",
+    /** 请求参数不合法 */
+    INVALID_PARAMS = "INVALID_PARAMS",
+    /** planner 无法生成合法执行计划 */
+    PLAN_FAILED = "PLAN_FAILED",
+    /** documentVersion 过期 */
+    VERSION_STALE = "VERSION_STALE",
+    /** AST 解析失败 */
+    AST_PARSE_ERROR = "AST_PARSE_ERROR",
+    /** 操作在当前受支持语法形状外 */
+    UNSUPPORTED_OPERATION = "UNSUPPORTED_OPERATION",
+    /** NodeLocator 定位失败 */
+    LOCATOR_FAILED = "LOCATOR_FAILED",
+    /** 目标关系非法，例如无效父子关系或自闭合元素插子节点 */
+    INVALID_TARGET = "INVALID_TARGET",
+    /** 文件写入 I/O 错误 */
+    WRITE_IO_ERROR = "WRITE_IO_ERROR",
+    /** 并发修改冲突 */
+    CONCURRENT_MODIFIED = "CONCURRENT_MODIFIED",
+    /** 回滚失败 */
+    ROLLBACK_FAILED = "ROLLBACK_FAILED",
+    /** 内部错误 */
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+/**
+ * 操作错误 —— 附带错误码、消息和可选详情。
+ */
+export interface OperationError {
+    code: OperationErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}

package/dist/internal/protocol/error.js

@@ -0,0 +1,38 @@
+// ─── Error 契约 ───────────────────────────────────────
+// 来源: docs/02-contracts-and-protocol.md §6.1
+/**
+ * 操作错误码枚举 —— 覆盖从节点查找到写回的所有失败路径。
+ */
+export var OperationErrorCode;
+(function (OperationErrorCode) {
+    /** 目标节点 key 在 graph 中不存在 */
+    OperationErrorCode["NODE_NOT_FOUND"] = "NODE_NOT_FOUND";
+    /** 目标路由不存在 */
+    OperationErrorCode["ROUTE_NOT_FOUND"] = "ROUTE_NOT_FOUND";
+    /** capability 检查拒绝（如 canMove = false） */
+    OperationErrorCode["CAPABILITY_REJECTED"] = "CAPABILITY_REJECTED";
+    /** 约束违反（如试图往 void element 插入子节点） */
+    OperationErrorCode["CONSTRAINT_VIOLATED"] = "CONSTRAINT_VIOLATED";
+    /** 请求参数不合法 */
+    OperationErrorCode["INVALID_PARAMS"] = "INVALID_PARAMS";
+    /** planner 无法生成合法执行计划 */
+    OperationErrorCode["PLAN_FAILED"] = "PLAN_FAILED";
+    /** documentVersion 过期 */
+    OperationErrorCode["VERSION_STALE"] = "VERSION_STALE";
+    /** AST 解析失败 */
+    OperationErrorCode["AST_PARSE_ERROR"] = "AST_PARSE_ERROR";
+    /** 操作在当前受支持语法形状外 */
+    OperationErrorCode["UNSUPPORTED_OPERATION"] = "UNSUPPORTED_OPERATION";
+    /** NodeLocator 定位失败 */
+    OperationErrorCode["LOCATOR_FAILED"] = "LOCATOR_FAILED";
+    /** 目标关系非法，例如无效父子关系或自闭合元素插子节点 */
+    OperationErrorCode["INVALID_TARGET"] = "INVALID_TARGET";
+    /** 文件写入 I/O 错误 */
+    OperationErrorCode["WRITE_IO_ERROR"] = "WRITE_IO_ERROR";
+    /** 并发修改冲突 */
+    OperationErrorCode["CONCURRENT_MODIFIED"] = "CONCURRENT_MODIFIED";
+    /** 回滚失败 */
+    OperationErrorCode["ROLLBACK_FAILED"] = "ROLLBACK_FAILED";
+    /** 内部错误 */
+    OperationErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+})(OperationErrorCode || (OperationErrorCode = {}));

package/dist/internal/protocol/event.d.ts

@@ -0,0 +1,39 @@
+import type { OperationResult } from "./operation.js";
+import type { OperationError } from "./error.js";
+/**
+ * 设计器事件联合类型 —— engine 向 client 推送的所有事件。
+ *
+ * - document-changed: 文档树结构或内容发生变更
+ * - operation-completed: 操作执行成功
+ * - operation-failed: 操作执行失败
+ * - graph-invalidated: graph 需要重建（如文件变更）
+ * - graph-ready: graph 重建完成
+ * - graph-error: graph 重建失败，但保留最近一次成功结果
+ * - capability-changed: 部分节点的 capability 发生变化
+ */
+export type DesignerEvent = {
+    type: "document-changed";
+    routeId: string;
+    version: number;
+} | {
+    type: "operation-completed";
+    result: OperationResult;
+} | {
+    type: "operation-failed";
+    requestId: string;
+    error: OperationError;
+} | {
+    type: "graph-invalidated";
+    routeId: string;
+} | {
+    type: "graph-ready";
+    routeId: string;
+    version: number;
+} | {
+    type: "graph-error";
+    routeId: string;
+    message: string;
+} | {
+    type: "capability-changed";
+    keys: string[];
+};

package/dist/internal/protocol/event.js

@@ -0,0 +1,3 @@
+// ─── Event 契约 ───────────────────────────────────────
+// 来源: docs/02-contracts-and-protocol.md §6.3
+export {};

package/dist/internal/protocol/identity.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 唯一身份标识，贯穿 DOM → protocol → engine → bridge 全链路。
+ *
+ * key 是唯一语义 key，由 file / component / structuralPath 确定性生成。
+ * 不得携带 SourceRange —— 那是 engine 内部实现细节。
+ */
+export interface SourceIdentity {
+    /** 源文件相对路径，如 "src/app/page.tsx" */
+    file: string;
+    /** 所属组件名，如 "HomePage" */
+    component: string;
+    /** 结构化路径，如 "div#0/span#1" */
+    structuralPath: string;
+    /** 唯一 key = "{file}::{component}::{structuralPath}" */
+    key: string;
+}
+/**
+ * 生成稳定的 SourceIdentity.key。
+ */
+export declare function computeSourceIdentityKey(file: string, component: string, structuralPath: string): string;
+/**
+ * 解析 SourceIdentity.key。
+ *
+ * structuralPath 允许包含分隔符，所以只切前两个段，余下部分全部并回 structuralPath。
+ */
+export declare function parseSourceIdentityKey(key: string): Pick<SourceIdentity, "file" | "component" | "structuralPath"> | null;

package/dist/internal/protocol/identity.js

@@ -0,0 +1,30 @@
+// ─── 身份契约 ───────────────────────────────────────────
+// 来源: docs/02-contracts-and-protocol.md §2
+//
+// 规则:
+//   key = "{file}::{component}::{structuralPath}"
+//   DOM / protocol / engine / bridge 全部统一使用 key
+//   SourceIdentity 不携带 SourceRange（SourceRange 是 engine-internal）
+const SOURCE_IDENTITY_SEPARATOR = "::";
+/**
+ * 生成稳定的 SourceIdentity.key。
+ */
+export function computeSourceIdentityKey(file, component, structuralPath) {
+    return `${file}${SOURCE_IDENTITY_SEPARATOR}${component}${SOURCE_IDENTITY_SEPARATOR}${structuralPath}`;
+}
+/**
+ * 解析 SourceIdentity.key。
+ *
+ * structuralPath 允许包含分隔符，所以只切前两个段，余下部分全部并回 structuralPath。
+ */
+export function parseSourceIdentityKey(key) {
+    const [file, component, ...pathParts] = key.split(SOURCE_IDENTITY_SEPARATOR);
+    if (!file || !component || pathParts.length === 0) {
+        return null;
+    }
+    return {
+        file,
+        component,
+        structuralPath: pathParts.join(SOURCE_IDENTITY_SEPARATOR),
+    };
+}