slidemind 0.3.20 → 0.4.0

package/src/lib/durable-ids.mjs

@@ -0,0 +1,47 @@
+// Durable identity for the things an edit operation names.
+//
+// SLIDE identity already exists and is NOT re-minted here: `mintSlideGuid()`
+// (`src/pptx/tags.mjs`) mints `sm-<uuid>` and `src/lib/slide-guids.mjs` keeps a
+// deck's sidecar of them across renames/reorders. A `slideKey` in the operation
+// and preservation records IS one of those GUIDs (or, for a deck that predates
+// them, whatever durable key the workspace already carries) — never a position.
+//
+// ELEMENT identity had no minter. Three flavours exist in the product already:
+// concept-spec slugs (`stage-1-card`), the converted dialect's OOXML
+// `data-sm-source-id={20}`, and ids an agent writes by hand. All three are
+// durable because something outside the JSX remembers them, so this module
+// only has to (a) mint one for a node the agent authors fresh and (b) say what
+// counts as an id at all. Matching an unlabelled node back to a requirement is
+// deliberately NOT here: the guide asks for ambiguity to be surfaced, and that
+// comparison belongs to the preservation verdict (phase 5), not to id minting.
+
+import { randomUUID } from "node:crypto";
+
+/** Prefix of a freshly minted element id, so its provenance is readable. */
+export const ELEMENT_ID_PREFIX = "sm-el-";
+
+const MAX_ID_LENGTH = 128;
+
+/**
+ * An id for a new agent-authored node. 48 bits of the uuid — short enough to
+ * read in a JSX attribute, and uniqueness is checked per slide by the
+ * preservation validator rather than assumed globally.
+ */
+export function mintElementId() {
+  return `${ELEMENT_ID_PREFIX}${randomUUID().replace(/-/g, "").slice(0, 12)}`;
+}
+
+/** Was this id minted here (as opposed to a spec slug or a source id)? */
+export function isMintedElementId(id) {
+  return typeof id === "string" && new RegExp(`^${ELEMENT_ID_PREFIX}[0-9a-f]{12}$`).test(id);
+}
+
+/**
+ * Anything usable as a durable identity: a non-empty, whitespace-free, bounded
+ * string. Deliberately permissive — the three existing flavours must all pass,
+ * and a shape the CLI has never seen (a pack's own ids) must not be refused by
+ * a validator that only had to check that an id is an id.
+ */
+export function isDurableId(id) {
+  return typeof id === "string" && id.length > 0 && id.length <= MAX_ID_LENGTH && !/\s/.test(id);
+}

package/src/lib/edit-operations.mjs

@@ -0,0 +1,316 @@
+// The edit-operation record — what an agent is allowed to change on this run.
+//
+// Contract from `openspec/changes/safeguard-slide-editing/implementation-guide.md`
+// section 1. Persisted at `<deck>/.slidemind/state/edit-operations.json`; the
+// add-in keeps the same record in its workspace persistence. This module is the
+// SHARED definition of the shape and the only place that decides whether one is
+// valid — it is mirrored byte-for-byte into the add-in
+// (`scripts/sync-transcription-runtime.mjs`), so the two clients cannot drift
+// into disagreeing about what a caller just handed them.
+//
+// Everything here is pure: no disk, no mutation of the argument, and no throw.
+// A malformed record is a returned error list, because the callers (phase 3.2 /
+// 3.3) must be able to refuse a write while leaving the bytes on disk exactly
+// as they found them.
+
+import { isDurableId } from "./durable-ids.mjs";
+
+/** Sidecar name under the workspace's `state/`. */
+export const EDIT_OPERATIONS_FILE = "edit-operations.json";
+
+/** The only schema version this build understands. */
+export const EDIT_OPERATION_VERSION = 1;
+
+/**
+ * What the operation is for. The manager derives it from the request and the
+ * selected slide ids; a worker cannot upgrade one kind into another by editing
+ * a pragma (that gate is task 3.4 — this module only refuses a record whose
+ * kind and payload disagree).
+ */
+export const OPERATION_KINDS = ["create", "targeted-edit", "repair", "redesign"];
+
+export const OPERATION_STATUSES = ["prepared", "validated", "committed", "conflicted", "aborted"];
+
+/** Where the source being edited came from, and therefore what it proves. */
+export const TARGET_PROVENANCE = ["live", "saved", "local"];
+
+export const CHANGE_ACTIONS = ["add", "update", "remove"];
+
+/**
+ * The property vocabulary shared by an operation's declared changes and a
+ * preservation requirement's protected set. These are the structural
+ * projection's own fields (`computeProjection`, src/pptx/tags.mjs) plus
+ * `native` for an opaque object's package dependency closure — so a scope name
+ * always points at something the render evidence can actually compare, and a
+ * scope nobody can verify cannot be written into a record in the first place.
+ */
+export const PROPERTY_SCOPES = ["geom", "text", "fill", "line", "media", "chart", "native"];
+
+const SHA256_RE = /^[0-9a-f]{64}$/;
+
+// --- error collection -------------------------------------------------------
+
+const err = (out, path, code, message) => out.push({ path, code, message });
+
+const isPlainObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+
+const isNonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+
+function checkVersion(record, path, out) {
+  if (record.version === EDIT_OPERATION_VERSION) return true;
+  err(
+    out,
+    `${path}.version`,
+    "unsupported_version",
+    `schema version ${JSON.stringify(record.version ?? null)} is not supported; ` +
+      `this build reads version ${EDIT_OPERATION_VERSION}. Leave the record untouched ` +
+      `and upgrade slidemind (\`slidemind update\`) before editing this deck.`,
+  );
+  return false;
+}
+
+function checkEnum(value, allowed, path, code, out) {
+  if (allowed.includes(value)) return true;
+  err(out, path, code, `${JSON.stringify(value ?? null)} is not one of ${allowed.join(" | ")}`);
+  return false;
+}
+
+// --- one target -------------------------------------------------------------
+
+function validateTarget(target, kind, path, seenSlideKeys, out) {
+  if (!isPlainObject(target)) {
+    err(out, path, "invalid_record", "a target must be an object");
+    return;
+  }
+
+  if (!isDurableId(target.slideKey)) {
+    err(out, `${path}.slideKey`, "missing_field", "slideKey must be a durable slide identity, never a position");
+  } else if (seenSlideKeys.has(target.slideKey)) {
+    err(
+      out,
+      `${path}.slideKey`,
+      "duplicate_slide_key",
+      `slideKey ${target.slideKey} is targeted twice by one operation; a slide has exactly one scope per operation`,
+    );
+  } else {
+    seenSlideKeys.add(target.slideKey);
+  }
+
+  if (!isNonEmptyString(target.jsxPath)) {
+    err(out, `${path}.jsxPath`, "missing_field", "jsxPath must name the slide's current source file");
+  }
+  if (target.liveSlideId != null && !isNonEmptyString(target.liveSlideId)) {
+    err(out, `${path}.liveSlideId`, "invalid_value", "liveSlideId, when present, must be the Office id string");
+  }
+
+  const provenanceOk = checkEnum(target.provenance, TARGET_PROVENANCE, `${path}.provenance`, "invalid_value", out);
+
+  // A base revision is what makes an edit safe to publish. `create` has no
+  // base by definition, so demanding one there would be nonsense; every other
+  // kind is editing something that already exists and must name it exactly.
+  if (kind === "create") {
+    if (target.baseSourceHash != null) {
+      err(
+        out,
+        `${path}.baseSourceHash`,
+        "invalid_value",
+        "a create target has no base source; use targeted-edit or redesign to change existing source",
+      );
+    }
+    if (provenanceOk && target.provenance !== "local") {
+      err(out, `${path}.provenance`, "invalid_value", "a create target is authored locally; provenance must be local");
+    }
+  } else if (!SHA256_RE.test(String(target.baseSourceHash ?? ""))) {
+    err(
+      out,
+      `${path}.baseSourceHash`,
+      "missing_base_revision",
+      "baseSourceHash (sha256 of the exact source prepared for editing) is required to edit existing source",
+    );
+  }
+
+  // Provenance is a claim about freshness, and each claim has its own proof.
+  // Saved bytes never prove equality with unsaved live content (E08), so the
+  // two are recorded separately rather than collapsed into one flag.
+  if (target.provenance === "live" && !isNonEmptyString(target.baseLiveFingerprint)) {
+    err(
+      out,
+      `${path}.baseLiveFingerprint`,
+      "missing_base_revision",
+      "live provenance claims the live slide was verified; record the fingerprint it was verified against",
+    );
+  }
+  if (target.provenance === "saved" && !isNonEmptyString(target.sourceRevision)) {
+    err(
+      out,
+      `${path}.sourceRevision`,
+      "missing_base_revision",
+      "saved provenance must name the saved-file revision it read",
+    );
+  }
+
+  if (target.repairPolicy != null) {
+    if (!isPlainObject(target.repairPolicy)) {
+      err(out, `${path}.repairPolicy`, "invalid_value", "repairPolicy must be an object");
+    }
+    if (kind !== "repair") {
+      err(
+        out,
+        `${path}.repairPolicy`,
+        "invalid_value",
+        `a repair budget only applies to a repair operation, not to ${kind}`,
+      );
+    }
+  }
+
+  if (!Array.isArray(target.changes)) {
+    err(out, `${path}.changes`, "missing_field", "changes must be an array (empty is allowed)");
+    return;
+  }
+  const seenElements = new Set();
+  target.changes.forEach((change, i) => validateChange(change, `${path}.changes[${i}]`, seenElements, out));
+}
+
+function validateChange(change, path, seenElements, out) {
+  if (!isPlainObject(change)) {
+    err(out, path, "invalid_record", "a change must be an object");
+    return;
+  }
+  if (!isDurableId(change.elementId)) {
+    err(out, `${path}.elementId`, "missing_field", "elementId must be a durable element identity");
+  } else if (seenElements.has(change.elementId)) {
+    err(
+      out,
+      `${path}.elementId`,
+      "duplicate_element_id",
+      `element ${change.elementId} is declared twice on one target; state the whole intent for it once`,
+    );
+  } else {
+    seenElements.add(change.elementId);
+  }
+
+  checkEnum(change.action, CHANGE_ACTIONS, `${path}.action`, "invalid_value", out);
+
+  if (!Array.isArray(change.properties)) {
+    err(out, `${path}.properties`, "missing_field", "properties must be an array of property scopes");
+    return;
+  }
+  change.properties.forEach((scope, i) => {
+    if (!PROPERTY_SCOPES.includes(scope)) {
+      err(
+        out,
+        `${path}.properties[${i}]`,
+        "invalid_property_scope",
+        `${JSON.stringify(scope ?? null)} is not a known property scope (${PROPERTY_SCOPES.join(", ")})`,
+      );
+    }
+  });
+  if (change.action === "update" && change.properties.length === 0) {
+    err(out, `${path}.properties`, "missing_field", "an update must name the properties it is allowed to change");
+  }
+}
+
+// --- public surface ---------------------------------------------------------
+
+/**
+ * Validate one operation record.
+ *
+ * @param {unknown} record
+ * @returns {{ ok: boolean, errors: Array<{path: string, code: string, message: string}> }}
+ */
+export function validateEditOperation(record, { path = "operation" } = {}) {
+  const errors = [];
+  if (!isPlainObject(record)) {
+    err(errors, path, "invalid_record", "an operation record must be an object");
+    return { ok: false, errors };
+  }
+  // A version we do not understand stops here: reporting field errors against
+  // a foreign schema would be noise, and the caller must preserve those bytes.
+  if (!checkVersion(record, path, errors)) return { ok: false, errors };
+
+  if (!isNonEmptyString(record.operationId)) {
+    err(errors, `${path}.operationId`, "missing_field", "operationId is required");
+  }
+  const kindOk = checkEnum(record.kind, OPERATION_KINDS, `${path}.kind`, "invalid_value", errors);
+  checkEnum(record.status, OPERATION_STATUSES, `${path}.status`, "invalid_value", errors);
+  if (!isNonEmptyString(record.requestSummary)) {
+    err(
+      errors,
+      `${path}.requestSummary`,
+      "missing_field",
+      "requestSummary is required: a concise trace of what the user asked for",
+    );
+  }
+
+  if (!Array.isArray(record.targets) || record.targets.length === 0) {
+    err(errors, `${path}.targets`, "missing_field", "targets must be a non-empty array");
+    return { ok: errors.length === 0, errors };
+  }
+  const seenSlideKeys = new Set();
+  const kind = kindOk ? record.kind : null;
+  record.targets.forEach((t, i) => validateTarget(t, kind, `${path}.targets[${i}]`, seenSlideKeys, errors));
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Validate the whole sidecar: `{ version, operations: [...] }`.
+ */
+export function validateEditOperationsFile(doc, { path = "edit-operations" } = {}) {
+  const errors = [];
+  if (!isPlainObject(doc)) {
+    err(errors, path, "invalid_record", "the operations file must be an object");
+    return { ok: false, errors };
+  }
+  if (!checkVersion(doc, path, errors)) return { ok: false, errors };
+  if (!Array.isArray(doc.operations)) {
+    err(errors, `${path}.operations`, "missing_field", "operations must be an array");
+    return { ok: false, errors };
+  }
+  const seen = new Set();
+  doc.operations.forEach((op, i) => {
+    const at = `${path}.operations[${i}]`;
+    const id = isPlainObject(op) ? op.operationId : null;
+    if (isNonEmptyString(id)) {
+      if (seen.has(id)) {
+        err(errors, `${at}.operationId`, "duplicate_operation_id", `operationId ${id} appears twice`);
+      } else {
+        seen.add(id);
+      }
+    }
+    errors.push(...validateEditOperation(op, { path: at }).errors);
+  });
+  return { ok: errors.length === 0, errors };
+}
+
+/** The slide keys an operation is scoped to — what a preservation update may touch. */
+export function operationSlideKeys(record) {
+  if (!isPlainObject(record) || !Array.isArray(record.targets)) return [];
+  return record.targets.filter(isPlainObject).map((t) => t.slideKey).filter(isDurableId);
+}
+
+/**
+ * A transition the governing operation's kind does not authorize, or null — the
+ * one rule both clients enforce: the add-in at every write, the CLI (whose agent
+ * writes files itself) before anything is rendered or delivered.
+ *
+ *   out_of_scope     a slide the scope does not name — another slide, or a
+ *                    `-2.jsx` sibling beside a target
+ *   dialect_dropped  an imported slide re-authored without its converted-dialect
+ *                    pragma by anything but a redesign
+ *
+ * `scoped` lists the slides the scope authorizes, in the caller's own identity
+ * (the add-in's jsx paths, the CLI's slide keys), and is null when nothing is
+ * scoped: no operation, or a `create`, which has no targets to stay inside.
+ * `kind` null reads as `targeted-edit` — a redesign is always declared, so no
+ * record means "not a redesign".
+ *
+ * @param {{ kind?: string | null, scoped?: string[] | null }} scope
+ * @param {{ slide: string, imported?: boolean, keepsPragma?: boolean }} change
+ * @returns {"out_of_scope" | "dialect_dropped" | null}
+ */
+export function editTransitionViolation({ kind = null, scoped = null }, { slide, imported = false, keepsPragma = true }) {
+  if (Array.isArray(scoped) && !scoped.includes(slide)) return "out_of_scope";
+  if (imported && !keepsPragma && (kind ?? "targeted-edit") !== "redesign") return "dialect_dropped";
+  return null;
+}