@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/ops/destructive-action-gate.d.ts

@@ -0,0 +1,44 @@
+import type { EditPlan, PageDoc } from "@avocadostudio-ai/shared";
+/**
+ * Tier 1 destructive-action gate. Evaluates an edit plan and decides whether
+ * it should be held for explicit human approval before applying, regardless
+ * of undo/redo availability.
+ *
+ * Undo protects against recovery; it does not protect against:
+ *   - AI misinterpretation (LLM deleted the wrong block)
+ *   - Cross-page ops (undo is per-page, not atomic across pages)
+ *   - Cognitive slip (user didn't notice until redo stack was cleared)
+ *   - Server restart wiping the in-memory undo stack
+ *
+ * Tier 1 triggers (no toggle — always required):
+ *   1. remove_page (always — even empty pages represent structural site content)
+ *   2. Multi-page AI plans (ops touch more than one slug)
+ *   3. Bulk delete: >= BULK_REMOVE_BLOCK_THRESHOLD remove_block ops in a
+ *      single plan, OR a plan that removes > HALF of the blocks on any page
+ */
+export type DestructiveReason = {
+    kind: "remove_page";
+    slug: string;
+    blockCount: number;
+} | {
+    kind: "multi_page_plan";
+    slugs: string[];
+} | {
+    kind: "bulk_remove_blocks";
+    totalRemoveOps: number;
+} | {
+    kind: "majority_page_wipe";
+    slug: string;
+    removing: number;
+    total: number;
+};
+export type DestructiveEvaluation = {
+    requiresApproval: boolean;
+    reasons: DestructiveReason[];
+    messages: string[];
+};
+export declare const BULK_REMOVE_BLOCK_THRESHOLD = 3;
+export declare const MAJORITY_WIPE_RATIO = 0.5;
+export type PageLookup = (slug: string) => PageDoc | null;
+export declare function evaluateDestructiveActions(plan: Pick<EditPlan, "ops">, getPage: PageLookup): DestructiveEvaluation;
+export declare function describeDestructiveReason(reason: DestructiveReason): string;

package/dist/ops/destructive-action-gate.js

@@ -0,0 +1,90 @@
+export const BULK_REMOVE_BLOCK_THRESHOLD = 3;
+export const MAJORITY_WIPE_RATIO = 0.5;
+function slugsTouchedByOps(ops) {
+    const set = new Set();
+    for (const op of ops) {
+        if (op.op === "create_page") {
+            set.add(op.page.slug);
+            continue;
+        }
+        if (op.op === "update_site_config")
+            continue;
+        // duplicate_page: pageSlug is the SOURCE (read-only); newPageSlug is the
+        // only page being modified. Skip the generic pageSlug add below so the
+        // source isn't counted as "touched" and a duplicate-and-modify plan
+        // doesn't trip the multi-page approval gate spuriously.
+        if (op.op === "duplicate_page") {
+            if (typeof op.newPageSlug === "string")
+                set.add(op.newPageSlug);
+            continue;
+        }
+        // duplicate_block to a different page: pageSlug is the SOURCE; toPageSlug
+        // is the only page being modified. Same rationale as duplicate_page.
+        if (op.op === "duplicate_block" && typeof op.toPageSlug === "string" && op.toPageSlug !== op.pageSlug) {
+            set.add(op.toPageSlug);
+            continue;
+        }
+        if ("pageSlug" in op && typeof op.pageSlug === "string")
+            set.add(op.pageSlug);
+        if (op.op === "duplicate_block" && typeof op.toPageSlug === "string")
+            set.add(op.toPageSlug);
+        if (op.op === "rename_page" && typeof op.newPageSlug === "string")
+            set.add(op.newPageSlug);
+    }
+    return Array.from(set);
+}
+export function evaluateDestructiveActions(plan, getPage) {
+    const reasons = [];
+    const ops = plan.ops;
+    // 1. remove_page — always destructive regardless of block count
+    for (const op of ops) {
+        if (op.op !== "remove_page")
+            continue;
+        const page = getPage(op.pageSlug);
+        const blockCount = page?.blocks?.length ?? 0;
+        reasons.push({ kind: "remove_page", slug: op.pageSlug, blockCount });
+    }
+    // 2. Multi-page plan (>1 slug touched in a single chat turn)
+    const touchedSlugs = slugsTouchedByOps(ops);
+    if (touchedSlugs.length > 1) {
+        reasons.push({ kind: "multi_page_plan", slugs: touchedSlugs });
+    }
+    // 3a. Bulk remove_block — absolute count across the whole plan
+    const removeBlockOps = ops.filter((op) => op.op === "remove_block");
+    if (removeBlockOps.length >= BULK_REMOVE_BLOCK_THRESHOLD) {
+        reasons.push({ kind: "bulk_remove_blocks", totalRemoveOps: removeBlockOps.length });
+    }
+    // 3b. Majority-wipe — plan removes > 50% of blocks on any single page
+    const removesBySlug = new Map();
+    for (const op of removeBlockOps) {
+        if (op.op !== "remove_block")
+            continue;
+        removesBySlug.set(op.pageSlug, (removesBySlug.get(op.pageSlug) ?? 0) + 1);
+    }
+    for (const [slug, removing] of removesBySlug) {
+        const page = getPage(slug);
+        const total = page?.blocks?.length ?? 0;
+        if (total > 0 && removing / total > MAJORITY_WIPE_RATIO) {
+            // Avoid duplicating with bulk_remove_blocks when both apply — both are
+            // informative, so we keep them.
+            reasons.push({ kind: "majority_page_wipe", slug, removing, total });
+        }
+    }
+    return {
+        requiresApproval: reasons.length > 0,
+        reasons,
+        messages: reasons.map(describeDestructiveReason)
+    };
+}
+export function describeDestructiveReason(reason) {
+    switch (reason.kind) {
+        case "remove_page":
+            return `You can still undo this later if you change your mind.`;
+        case "multi_page_plan":
+            return `This will apply changes across ${reason.slugs.length} pages at once (${reason.slugs.join(", ")}).`;
+        case "bulk_remove_blocks":
+            return `This will remove ${reason.totalRemoveOps} blocks at once.`;
+        case "majority_page_wipe":
+            return `This will remove most of the content on ${reason.slug} (${reason.removing} of ${reason.total} blocks).`;
+    }
+}

package/dist/ops/ops-engine.d.ts

@@ -0,0 +1,151 @@
+import { type BlockManifest, type Operation } from "@avocadostudio-ai/shared";
+import { type GuardrailErrorCategory, toErrorDetail as _unifiedToErrorDetail } from "../errors.ts";
+import type { ContentSource } from "../state/content-source.ts";
+import type { PublishDiff } from "@avocadostudio-ai/shared";
+export declare const toErrorDetail: typeof _unifiedToErrorDetail;
+export declare function isNoEffectiveChangeError(reason: string): boolean;
+export declare function classifyGuardrailError(reason: string): GuardrailErrorCategory;
+export declare function formatValidationError(reason: string): string;
+export declare function isDeterministicRepairEligible(reason: string): boolean;
+/**
+ * Extracts structured fields from a planner schema_violation reason so the
+ * repair prompt can tell the LLM exactly which path to fix and what kind of
+ * violation it was. The reason format produced by planner.ts is:
+ *   `<zodMessage> at <path>. Parsed sample: <truncated json>`
+ *
+ * Falls back gracefully when fields are missing (e.g. non-zod failures that
+ * still classify as schema_violation via the keyword matcher).
+ */
+export declare function parseSchemaViolationReason(reason: string): {
+    path: string | null;
+    zodMessage: string;
+    kind: "unknown_key" | "missing_required" | "type_mismatch" | "invalid_enum" | "invalid_discriminator" | "out_of_range" | "string_constraint" | "unknown";
+};
+export declare function buildDeterministicRepairFeedback(reason: string): string;
+export type SkippedOperation = {
+    index: number;
+    op: Operation["op"];
+    reason: "empty_patch" | "unchanged_value";
+    pageSlug?: string;
+    blockId?: string;
+};
+export type FuzzyMatch = {
+    requestedId: string;
+    resolvedId: string;
+    resolvedIndex: number;
+    strategy: "strip_copy_suffix" | "append_copy_suffix" | "type_prefix";
+};
+/**
+ * Per-op outcome, collected for every op in the plan. `applied` and `skipped`
+ * mirror the existing all-or-nothing behaviour; `failed` only ever appears under
+ * `dryRun`, where a failing op is reported instead of aborting the whole plan so
+ * a preview can show "3 of 4 changes will apply".
+ */
+export type OpResult = {
+    index: number;
+    op: Operation["op"];
+    status: "applied" | "skipped" | "failed";
+    reason?: string;
+    category?: string;
+};
+export type ApplyOpsOptions = {
+    componentsManifest?: BlockManifest;
+    contentSource?: ContentSource;
+    /**
+     * Validate-only: run every op against a clone, collect per-op results and a
+     * before→after diff, but never commit. Hard failures become `failed` op
+     * results (the plan does not abort), and each op is snapshot-isolated so a
+     * failure leaves no partial mutation that would corrupt the preview.
+     */
+    dryRun?: boolean;
+    /**
+     * Return a wholly-ineffective batch as `{ appliedCount: 0, skippedOps }` instead
+     * of throwing `no_effective_change`. Used by per-op streamed/progressive apply:
+     * applying ONE op at a time means an already-correct block (e.g. a section that's
+     * already in the target translation language) is a benign skip, not a plan-level
+     * failure. Without this, the first such op throws, the whole multi-op plan rolls
+     * back, and genuinely-changed blocks are discarded too.
+     */
+    allowNoEffectiveChange?: boolean;
+};
+export declare function isStructuralOperation(op: Operation): op is {
+    op: "add_block";
+    pageSlug: string;
+    block: {
+        id: string;
+        props: Record<string, unknown>;
+        type: string;
+    };
+    afterBlockId?: string | undefined;
+} | {
+    op: "remove_block";
+    pageSlug: string;
+    blockId: string;
+} | {
+    op: "move_block";
+    pageSlug: string;
+    blockId: string;
+    afterBlockId?: string | undefined;
+} | {
+    op: "duplicate_block";
+    pageSlug: string;
+    blockId: string;
+    toPageSlug?: string | undefined;
+    newBlockId?: string | undefined;
+    afterBlockId?: string | undefined;
+} | {
+    op: "add_item";
+    pageSlug: string;
+    blockId: string;
+    listKey: string;
+    item: Record<string, unknown>;
+    afterItemId?: string | undefined;
+    afterIndex?: number | undefined;
+} | {
+    op: "remove_item";
+    pageSlug: string;
+    blockId: string;
+    listKey: string;
+    itemId?: string | undefined;
+    index?: number | undefined;
+} | {
+    op: "move_item";
+    pageSlug: string;
+    blockId: string;
+    listKey: string;
+    itemId?: string | undefined;
+    index?: number | undefined;
+    afterItemId?: string | undefined;
+    afterIndex?: number | undefined;
+};
+/**
+ * Validate an array of operations against the canonical Zod schema.
+ * Returns the parsed (typed) operations or throws an `OperationError`
+ * with category `schema_violation`.
+ */
+export declare function validateOperations(ops: unknown[]): Operation[];
+export declare function applyOpsAtomically(session: string, ops: Operation[], options?: ApplyOpsOptions): Promise<{
+    appliedCount: number;
+    skippedOps: SkippedOperation[];
+    fuzzyMatches: FuzzyMatch[];
+    duplicatedPages: {
+        slug: string;
+        blockIdMap: Record<string, string>;
+    }[];
+    opResults: OpResult[];
+    preview: PublishDiff;
+    dryRun: true;
+} | {
+    appliedCount: number;
+    skippedOps: SkippedOperation[];
+    fuzzyMatches: FuzzyMatch[];
+    duplicatedPages: {
+        slug: string;
+        blockIdMap: Record<string, string>;
+    }[];
+    opResults: OpResult[];
+    preview: PublishDiff | undefined;
+    dryRun: false;
+}>;
+export declare function pickFocusBlockId(ops: Operation[]): string | undefined;
+export declare function pickUpdatedSlug(session: string, currentSlug: string, ops: Operation[]): string | undefined;