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

package/dist/internal/writeback/writeback-service.js

@@ -0,0 +1,568 @@
+// ── WritebackService 骨架 ──────────────────────────────────────
+// 根文档 03 §5 定义：
+//   1. 先做 documentVersion stale check
+//   2. 按 steps[].order 顺序执行
+//   3. 任一步失败，按 preSnapshots 回滚
+//   4. undo/redo 基于 operation-level snapshot
+import { addImport, addDirective, addTailwindClass, removeImport, removeDirective, removeJsxAttribute, removeTailwindClass, setJsxAttribute, updateClassName, updateCssModuleClassReference, updateDirective, updateGenerateMetadata, updateMetadataField, updateNamedExport, updateStyleProperties, updateStyleProperty, updateValue, insertArrayElement, removeArrayElement, moveArrayElement, insertObjectProperty, removeObjectProperty, replaceConditionalExpression, setConditionalBranchContent, updateText as astUpdateText, removeNode as astRemoveNode, insertChild as astInsertChild, moveNode as astMoveNode, } from "../ast/primitives/index.js";
+import { createJsxAttribute, parseMutationSource, printMutationWithOperation, resolveRequiredJsxElement, } from "../ast/primitives/shared.js";
+import { primitiveFailure } from "../ast/diagnostics/index.js";
+/* ------------------------------------------------------------------ */
+/*  createWritebackService                                            */
+/* ------------------------------------------------------------------ */
+export function createWritebackService(fs, options = {}) {
+    const undoStack = [];
+    const redoStack = [];
+    const externalAdapters = options.externalAdapters ?? [];
+    // Allow file systems that don't implement versioning (e.g., minimal test stubs).
+    const _localVersions = new Map();
+    function _getVersion(file) {
+        return typeof fs.getVersion === "function"
+            ? fs.getVersion(file)
+            : (_localVersions.get(file) ?? 0);
+    }
+    function _bumpVersion(file) {
+        if (typeof fs.bumpVersion === "function") {
+            return fs.bumpVersion(file);
+        }
+        const v = (_localVersions.get(file) ?? 0) + 1;
+        _localVersions.set(file, v);
+        return v;
+    }
+    return {
+        execute,
+        undo,
+        redo,
+    };
+    /* ---------------------------------------------------------------- */
+    /*  execute                                                          */
+    /* ---------------------------------------------------------------- */
+    async function execute(plan) {
+        // ── 1. 拍下 pre-snapshots ──
+        const preSnapshots = [];
+        const involvedFiles = new Set(plan.steps
+            .filter((step) => step.type !== "invoke-external-adapter")
+            .map((s) => s.file));
+        for (const file of involvedFiles) {
+            try {
+                const content = await fs.readFile(file);
+                const version = _getVersion(file);
+                preSnapshots.push({ file, content, version });
+            }
+            catch {
+                // 文件不存在时用空内容
+                preSnapshots.push({ file, content: "", version: 0 });
+            }
+        }
+        // ── 2. 按 order 排序步骤 ──
+        const sortedSteps = [...plan.steps].sort((a, b) => a.order - b.order);
+        // ── 3. 顺序执行 ──
+        // 保存当前文件内容的 working copies
+        const workingCopies = new Map();
+        for (const snap of preSnapshots) {
+            workingCopies.set(snap.file, snap.content);
+        }
+        for (let index = 0; index < sortedSteps.length;) {
+            const step = sortedSteps[index];
+            if (step.type === "invoke-external-adapter") {
+                const requiredCapability = step.capability ?? "write-text";
+                const adapter = externalAdapters.find((candidate) => candidate.sourceType === step.sourceType &&
+                    (step.adapterId === undefined ||
+                        candidate.adapterId === step.adapterId) &&
+                    (candidate.capabilities === undefined ||
+                        candidate.capabilities.includes(requiredCapability)));
+                if (!adapter) {
+                    await rollback(preSnapshots);
+                    return {
+                        ok: false,
+                        operationId: plan.operationId,
+                        errorCode: "unsupported-operation",
+                        reason: `No external adapter registered for ${step.sourceType}`,
+                        rolledBack: true,
+                    };
+                }
+                const result = await adapter.execute(step);
+                if (!result.ok) {
+                    await rollback(preSnapshots);
+                    return {
+                        ok: false,
+                        operationId: plan.operationId,
+                        errorCode: "writeback-failed",
+                        reason: result.reason ?? `External adapter failed for ${step.sourceType}`,
+                        rolledBack: true,
+                    };
+                }
+                index += 1;
+                continue;
+            }
+            const currentContent = workingCopies.get(step.file) ?? "";
+            const batchedSetJsxPropSteps = collectAdjacentSetJsxPropSteps(sortedSteps, index);
+            const batchedRemoveJsxPropSteps = collectAdjacentRemoveJsxPropSteps(sortedSteps, index);
+            const result = batchedSetJsxPropSteps.length > 1
+                ? executeSetJsxPropBatch(batchedSetJsxPropSteps, currentContent)
+                : batchedRemoveJsxPropSteps.length > 1
+                    ? executeRemoveJsxPropBatch(batchedRemoveJsxPropSteps, currentContent)
+                    : executeStep(step, currentContent);
+            if (!result.ok) {
+                // ── 4. 回滚 ──
+                await rollback(preSnapshots);
+                return {
+                    ok: false,
+                    operationId: plan.operationId,
+                    errorCode: result.errorCode,
+                    reason: result.reason,
+                    rolledBack: true,
+                };
+            }
+            workingCopies.set(step.file, result.source);
+            index += Math.max(1, batchedSetJsxPropSteps.length, batchedRemoveJsxPropSteps.length);
+        }
+        // ── 5. 写回文件 ──
+        const postSnapshots = [];
+        for (const [file, content] of workingCopies) {
+            await fs.writeFile(file, content);
+            const version = _bumpVersion(file);
+            postSnapshots.push({ file, content, version });
+        }
+        // ── 6. 压入 undo 栈 ──
+        undoStack.push({
+            operationId: plan.operationId,
+            preSnapshots,
+            postSnapshots,
+            plan,
+        });
+        // 新操作清空 redo 栈
+        redoStack.length = 0;
+        return {
+            ok: true,
+            operationId: plan.operationId,
+            resultVersion: Math.max(1, ...postSnapshots.map((s) => s.version)),
+            affectedFiles: [...involvedFiles],
+        };
+    }
+    /* ---------------------------------------------------------------- */
+    /*  undo                                                             */
+    /* ---------------------------------------------------------------- */
+    async function undo() {
+        const entry = undoStack.pop();
+        if (!entry) {
+            return {
+                ok: false,
+                operationId: "",
+                errorCode: "unknown",
+                reason: "Nothing to undo",
+            };
+        }
+        // 恢复 preSnapshots
+        for (const snap of entry.preSnapshots) {
+            await fs.writeFile(snap.file, snap.content);
+            _bumpVersion(snap.file);
+        }
+        redoStack.push(entry);
+        return {
+            ok: true,
+            operationId: entry.operationId,
+            resultVersion: Math.max(...entry.preSnapshots.map((s) => s.version + 1)),
+            affectedFiles: entry.preSnapshots.map((s) => s.file),
+        };
+    }
+    /* ---------------------------------------------------------------- */
+    /*  redo                                                             */
+    /* ---------------------------------------------------------------- */
+    async function redo() {
+        const entry = redoStack.pop();
+        if (!entry) {
+            return {
+                ok: false,
+                operationId: "",
+                errorCode: "unknown",
+                reason: "Nothing to redo",
+            };
+        }
+        // 恢复 postSnapshots
+        for (const snap of entry.postSnapshots) {
+            await fs.writeFile(snap.file, snap.content);
+            _bumpVersion(snap.file);
+        }
+        undoStack.push(entry);
+        return {
+            ok: true,
+            operationId: entry.operationId,
+            resultVersion: Math.max(...entry.postSnapshots.map((s) => s.version + 1)),
+            affectedFiles: entry.postSnapshots.map((s) => s.file),
+        };
+    }
+    /* ---------------------------------------------------------------- */
+    /*  rollback                                                         */
+    /* ---------------------------------------------------------------- */
+    async function rollback(snapshots) {
+        for (const snap of snapshots) {
+            try {
+                await fs.writeFile(snap.file, snap.content);
+            }
+            catch {
+                // rollback 失败时继续尝试恢复其他文件
+            }
+        }
+    }
+}
+function executeStep(step, source) {
+    switch (step.type) {
+        case "invoke-external-adapter":
+            return {
+                ok: false,
+                reason: "External adapter steps must be executed asynchronously",
+                errorCode: "unsupported-operation",
+            };
+        case "add-import":
+            return toStepResult(addImport({
+                source,
+                moduleSpecifier: step.moduleSpecifier,
+                imports: step.imports,
+            }));
+        case "remove-import":
+            return toStepResult(removeImport({
+                source,
+                moduleSpecifier: step.moduleSpecifier,
+                imports: step.imports,
+            }));
+        case "remove-node":
+            return toStepResult(astRemoveNode({
+                source,
+                locator: step.locator,
+                removeWhitespace: step.removeWhitespace,
+            }));
+        case "insert-child":
+            return toStepResult(astInsertChild({
+                source,
+                locator: step.parentLocator,
+                node: step.node,
+                placement: step.placement,
+                anchorLocator: step.anchorLocator,
+            }));
+        case "update-text":
+            return toStepResult(astUpdateText({
+                source,
+                locator: step.locator,
+                segmentIndex: step.segmentIndex,
+                newText: step.newText,
+            }));
+        case "update-value":
+            return toStepResult(updateValue({
+                source,
+                locator: step.locator,
+                next: step.value,
+            }));
+        case "set-object-field":
+            return toStepResult(updateValue({
+                source,
+                locator: step.locator,
+                next: step.value,
+            }));
+        case "insert-object-field":
+            return toStepResult(insertObjectProperty({
+                source,
+                locator: step.locator,
+                property: {
+                    key: step.field,
+                    value: step.value,
+                },
+            }));
+        case "remove-object-field":
+            return toStepResult(removeObjectProperty({
+                source,
+                locator: step.locator,
+                key: step.field,
+            }));
+        case "update-array-item":
+            return toStepResult(updateValue({
+                source,
+                locator: step.locator,
+                next: step.value,
+            }));
+        case "insert-array-item":
+            return toStepResult(insertArrayElement({
+                source,
+                locator: step.locator,
+                index: step.index,
+                value: step.value,
+            }));
+        case "remove-array-item":
+            return toStepResult(removeArrayElement({
+                source,
+                locator: step.locator,
+                index: step.index,
+            }));
+        case "move-array-item":
+            return toStepResult(moveArrayElement({
+                source,
+                locator: step.locator,
+                fromIndex: step.fromIndex,
+                toIndex: step.toIndex,
+            }));
+        case "replace-conditional-expression":
+            return toStepResult(replaceConditionalExpression({
+                source,
+                locator: step.locator,
+                nextExpression: step.nextExpression,
+            }));
+        case "set-conditional-branch-content":
+            return toStepResult(setConditionalBranchContent({
+                source,
+                locator: step.locator,
+                branch: step.branch,
+                content: step.content,
+            }));
+        case "move-node":
+            return toStepResult(astMoveNode({
+                source,
+                locator: step.locator,
+                targetParentLocator: step.targetParentLocator,
+                placement: step.placement,
+                anchorLocator: step.anchorLocator,
+            }));
+        case "set-jsx-prop":
+            return toStepResult(setJsxAttribute({
+                source,
+                locator: step.locator,
+                value: step.value,
+            }));
+        case "remove-jsx-prop":
+            return toStepResult(removeJsxAttribute({
+                source,
+                locator: step.locator,
+            }));
+        case "set-class-name":
+            return toStepResult(updateClassName({
+                source,
+                locator: step.locator,
+                value: step.value,
+            }));
+        case "add-class-token":
+            return toStepResult(addTailwindClass({
+                source,
+                locator: step.locator,
+                token: step.token,
+            }));
+        case "remove-class-token":
+            return toStepResult(removeTailwindClass({
+                source,
+                locator: step.locator,
+                token: step.token,
+            }));
+        case "set-style-property":
+            return toStepResult(updateStyleProperty({
+                source,
+                locator: step.locator,
+                property: step.property,
+                value: step.value,
+            }));
+        case "set-style-properties":
+            return toStepResult(updateStyleProperties({
+                source,
+                locator: step.locator,
+                properties: step.properties,
+            }));
+        case "set-css-module-class":
+            return toStepResult(updateCssModuleClassReference({
+                source,
+                locator: step.locator,
+                nextClass: step.to,
+            }));
+        case "set-directive":
+            return toStepResult(step.mode === "add"
+                ? addDirective({
+                    source,
+                    value: step.value,
+                })
+                : updateDirective({
+                    source,
+                    locator: {
+                        kind: "directive",
+                        value: step.currentValue ?? step.value,
+                    },
+                    nextValue: step.value,
+                }));
+        case "remove-directive":
+            return toStepResult(removeDirective({
+                source,
+                locator: { kind: "directive", value: step.value },
+            }));
+        case "set-route-export":
+            return toStepResult(updateNamedExport({
+                source,
+                locator: { kind: "export", exportKind: "named", name: step.name },
+                next: step.value,
+            }));
+        case "set-metadata-field":
+            return toStepResult(updateMetadataField({
+                source,
+                locator: { kind: "export", exportKind: "metadata" },
+                path: [{ kind: "property", name: step.field }],
+                next: step.value,
+            }));
+        case "set-generate-metadata":
+            return toStepResult(updateGenerateMetadata({
+                source,
+                locator: { kind: "export", exportKind: "generate-metadata" },
+                path: [{ kind: "property", name: step.field }],
+                next: step.value,
+            }));
+        default:
+            return {
+                ok: false,
+                reason: `Unknown step type: ${step.type}`,
+                errorCode: "unknown",
+            };
+    }
+}
+function collectAdjacentSetJsxPropSteps(steps, startIndex) {
+    const first = steps[startIndex];
+    if (first?.type !== "set-jsx-prop") {
+        return [];
+    }
+    const result = [];
+    for (let index = startIndex; index < steps.length; index += 1) {
+        const step = steps[index];
+        if (step.type !== "set-jsx-prop" || step.file !== first.file) {
+            break;
+        }
+        result.push(step);
+    }
+    return result;
+}
+function collectAdjacentRemoveJsxPropSteps(steps, startIndex) {
+    const first = steps[startIndex];
+    if (first?.type !== "remove-jsx-prop") {
+        return [];
+    }
+    const result = [];
+    for (let index = startIndex; index < steps.length; index += 1) {
+        const step = steps[index];
+        if (step.type !== "remove-jsx-prop" || step.file !== first.file) {
+            break;
+        }
+        result.push(step);
+    }
+    return result;
+}
+function executeSetJsxPropBatch(steps, source) {
+    const parsed = parseMutationSource(source, "jsx-attribute");
+    if (!parsed.ok) {
+        return toStepResult(parsed.result);
+    }
+    for (const step of steps) {
+        const result = applySetJsxAttributeMutation(parsed.ast, source, step);
+        if (!result.ok) {
+            return toStepResult(result);
+        }
+    }
+    return toStepResult(printMutationWithOperation(parsed.ast, source, {
+        kind: "set-jsx-attribute",
+        target: "jsx-attribute",
+        inverse: "remove-jsx-attribute",
+    }));
+}
+function executeRemoveJsxPropBatch(steps, source) {
+    const parsed = parseMutationSource(source, "jsx-attribute");
+    if (!parsed.ok) {
+        return toStepResult(parsed.result);
+    }
+    for (const step of steps) {
+        const result = applyRemoveJsxAttributeMutation(parsed.ast, source, step);
+        if (!result.ok) {
+            return toStepResult(result);
+        }
+    }
+    return toStepResult(printMutationWithOperation(parsed.ast, source, {
+        kind: "remove-jsx-attribute",
+        target: "jsx-attribute",
+        inverse: "set-jsx-attribute",
+    }));
+}
+function applySetJsxAttributeMutation(ast, source, step) {
+    const elementMatch = resolveRequiredJsxElement(ast, step.locator.element, source);
+    if (!elementMatch.ok) {
+        return elementMatch.result;
+    }
+    const attributes = elementMatch.match.path.node.openingElement.attributes;
+    const targetIndex = attributes.findIndex((attribute) => attribute.type === "JSXAttribute" &&
+        attribute.name.type === "JSXIdentifier" &&
+        attribute.name.name === step.locator.name);
+    if (targetIndex >= 0 &&
+        attributes.some((attribute, index) => index > targetIndex && attribute.type === "JSXSpreadAttribute")) {
+        return primitiveFailure(source, "unsupported-syntax", "cannot edit explicit attribute when spread props follow it", "jsx-attribute");
+    }
+    const existing = attributes.find((attribute) => attribute.type === "JSXAttribute" &&
+        attribute.name.type === "JSXIdentifier" &&
+        attribute.name.name === step.locator.name);
+    if (existing?.type === "JSXAttribute") {
+        existing.value = createJsxAttribute(step.locator.name, step.value).value;
+    }
+    else {
+        attributes.push(createJsxAttribute(step.locator.name, step.value));
+    }
+    return {
+        ok: true,
+        source,
+    };
+}
+function applyRemoveJsxAttributeMutation(ast, source, step) {
+    const elementMatch = resolveRequiredJsxElement(ast, step.locator.element, source);
+    if (!elementMatch.ok) {
+        return elementMatch.result;
+    }
+    elementMatch.match.path.node.openingElement.attributes =
+        elementMatch.match.path.node.openingElement.attributes.filter((attribute) => attribute.type !== "JSXAttribute" ||
+            attribute.name.type !== "JSXIdentifier" ||
+            attribute.name.name !== step.locator.name);
+    return {
+        ok: true,
+        source,
+    };
+}
+function toStepResult(result) {
+    if (result.ok) {
+        return { ok: true, source: result.source };
+    }
+    switch (result.diagnostic.code) {
+        case "locator-miss":
+            return {
+                ok: false,
+                reason: result.diagnostic.message,
+                errorCode: "locator-miss",
+            };
+        case "unsupported-syntax":
+        case "binding-not-found":
+        case "export-not-found":
+        case "property-not-found":
+        case "array-index-out-of-range":
+        case "directive-conflict":
+        case "metadata-shape-unsupported":
+            return {
+                ok: false,
+                reason: result.diagnostic.message,
+                errorCode: "unsupported-operation",
+            };
+        case "invalid-parent-child-relation":
+        case "self-closing-element":
+            return {
+                ok: false,
+                reason: result.diagnostic.message,
+                errorCode: "invalid-target",
+            };
+        case "parse-failed":
+        case "printer-failed":
+            return {
+                ok: false,
+                reason: result.diagnostic.message,
+                errorCode: "ast-error",
+            };
+        default:
+            return {
+                ok: false,
+                reason: result.diagnostic.message,
+                errorCode: "writeback-failed",
+            };
+    }
+}

package/dist/internal-adapter.d.ts

@@ -0,0 +1,18 @@
+import type { SiteEditEvent, SiteEditObjectContentDetail, SiteEditObjectDetail, SiteEditObjectEditContext, SiteEditObjectMediaDetail, SiteEditObjectStyleDetail, SiteEditObjectSummary, SiteEditOperationRequest, SiteEditOperationResult, SiteEditRenderDocument } from "@trojanbox-vcp-test/contracts";
+import type { DesignerEvent, OperationRequest, OperationResult, RenderDocument, RenderObjectDetail } from "./internal/protocol.js";
+export declare function toInternalOperationRequest(request: SiteEditOperationRequest): OperationRequest;
+export declare function toSiteEditOperationResult(result: OperationResult): SiteEditOperationResult;
+export declare function toSiteEditRenderDocument(document: RenderDocument, context: {
+    siteId: string;
+    snapshotId: string;
+}): SiteEditRenderDocument;
+export declare function toSiteEditObjectSummary(detail: RenderObjectDetail): SiteEditObjectSummary;
+export declare function toSiteEditObjectEditContext(detail: RenderObjectDetail): SiteEditObjectEditContext;
+export declare function toSiteEditObjectStyleDetail(detail: RenderObjectDetail): SiteEditObjectStyleDetail;
+export declare function toSiteEditObjectContentDetail(detail: RenderObjectDetail): SiteEditObjectContentDetail;
+export declare function toSiteEditObjectMediaDetail(detail: RenderObjectDetail): SiteEditObjectMediaDetail;
+export declare function toSiteEditObjectDetail(detail: RenderObjectDetail): SiteEditObjectDetail;
+export declare function toSiteEditEvent(event: DesignerEvent, context: {
+    siteId: string;
+    snapshotId: string;
+}): SiteEditEvent | null;