slidemind 0.3.20 → 0.4.1

package/src/lib/reconcile-ack.mjs

@@ -11,14 +11,15 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { statePath, writeStateFile } from "./deck-paths.mjs";
 
-const SIDECAR = ".reconcile-ack.json";
+const SIDECAR = "reconcile-ack.json";
 
 /** { [fileName]: nowHash } — `{}` when the deck has no sidecar (or a broken one). */
 export function loadReconcileAcks(deckDir) {
   let parsed;
   try {
-    parsed = JSON.parse(fs.readFileSync(path.join(deckDir, SIDECAR), "utf8"));
+    parsed = JSON.parse(fs.readFileSync(statePath(deckDir, SIDECAR), "utf8"));
   } catch {
     return {};
   }
@@ -39,8 +40,5 @@ export function saveReconcileAcks(deckDir, acks) {
   for (const [file, hash] of Object.entries(acks)) {
     if (typeof hash === "string" && hash) merged[path.basename(file)] = hash;
   }
-  fs.writeFileSync(
-    path.join(deckDir, SIDECAR),
-    `${JSON.stringify(merged, null, 2)}\n`,
-  );
+  writeStateFile(deckDir, SIDECAR, `${JSON.stringify(merged, null, 2)}\n`);
 }

package/src/lib/reconcile.mjs

@@ -20,13 +20,16 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { slideOrderPaths } from "../pptx/ooxml.mjs";
+import { foldPickedSlides } from "../pptx/slide-swap.mjs";
 import {
+  TAG_GUID,
   computeProjection,
   decodeSourceTags,
+  readSlideTags,
   withoutChartHashes,
 } from "../pptx/tags.mjs";
 import { unzip } from "../pptx/zip.mjs";
-import { loadConversions } from "./conversions.mjs";
 import { detectManualEdits, manualEditsError } from "./overwrite-guard.mjs";
 import { loadReconcileAcks, saveReconcileAcks } from "./reconcile-ack.mjs";
 import { reconcileSlideGuids } from "./slide-guids.mjs";
@@ -41,7 +44,8 @@ export function collectReconcileInputs({ deckDir, outFile, force = false }) {
   // the blind build the CLI did before any of this existed.
   if (force) return null;
   const edits = detectManualEdits(outFile);
-  if (edits.length === 0) return null;
+  const charted = chartedSlides(outFile).filter((c) => !edits.some((e) => e.slidePath === c.slidePath));
+  if (edits.length === 0 && charted.length === 0) return null;
 
   // GUID → slide file name. reconcileSlideGuids, not loadSlideGuids: a reorder
   // renames every file, so the raw sidecar can still be keyed by the old names
@@ -51,33 +55,32 @@ export function collectReconcileInputs({ deckDir, outFile, force = false }) {
   for (const [slidePath, guid] of Object.entries(reconcileSlideGuids(deckDir))) {
     fileByGuid.set(guid, path.basename(slidePath));
   }
-  // B3 exclusion — CONVERTED slides (`slidemind adopt`). Their drift protection
-  // is the conversion-gate machinery, which already holds a baseline of the
-  // ORIGINAL slide; driving a second reconcile from the render bake's baseline
-  // would have two mechanisms arguing over one slide. Matched by GUID, not file
-  // name, so a reorder cannot smuggle one back in before the records rehome.
-  const convertedGuids = new Set(
-    Object.values(loadConversions(deckDir, { includeSource: false }))
-      .map((record) => record.guid)
-      .filter(Boolean),
-  );
+  // A CONVERTED slide (`slidemind adopt`) reconciles like any other, as in the
+  // add-in: the conversion gate compares a candidate with the ORIGINAL import,
+  // never with what the user changed in the delivered file since, so leaving
+  // it out here let the next build overwrite a manual edit without a word.
 
   const acks = loadReconcileAcks(deckDir);
   const reconcile = {};
   const refusals = [];
-  for (const edit of edits) {
-    if (edit.guid && convertedGuids.has(edit.guid)) continue;
+  let bytes = null;
+  for (const edit of [...edits, ...charted]) {
     const fileName = edit.guid ? fileByGuid.get(edit.guid) : null;
-    // B3 exclusion — a slide with no jsx of ours behind it: a native reused
-    // .pptx, or a slide pushed by another deck. There is nothing to fold an
-    // edit INTO, so Phase A's refusal still governs it.
+    // A slide with no jsx of ours behind it — a native reused .pptx, or a slide
+    // pushed by another deck — has nothing to fold an edit INTO, so Phase A's
+    // refusal still governs a visible edit to it.
     if (!fileName) {
-      refusals.push(edit);
+      if (edits.includes(edit)) refusals.push(edit);
       continue;
     }
+    // A slide holding a chart travels as its package: only the add-in can read
+    // a chart, so it projects the current state and folds a chart edit too.
+    bytes ??= hasChart(edit.baseline) ? fs.readFileSync(outFile) : null;
     reconcile[fileName] = {
       baseline: edit.baseline,
-      current: edit.current,
+      ...(hasChart(edit.baseline)
+        ? { package: Buffer.from(foldPickedSlides(bytes, [edit.slideIndex])[0].bytes).toString("base64") }
+        : { current: edit.current }),
       ...(acks[fileName] ? { ack: acks[fileName] } : {}),
     };
   }
@@ -85,6 +88,35 @@ export function collectReconcileInputs({ deckDir, outFile, force = false }) {
   return Object.keys(reconcile).length > 0 ? reconcile : null;
 }
 
+/** Does a baked baseline hold a chart — something only the add-in can compare? */
+function hasChart(baseline) {
+  return (baseline?.shapes ?? []).some((shape) => shape?.chart != null);
+}
+
+/**
+ * Slides of the previous output whose baseline holds a chart. Their chart-only
+ * edits are invisible to this repo's projection (`chart: null`, the CHART HASH
+ * note in pptx/tags.mjs), so they go to the add-in whether or not anything
+ * else about them changed.
+ */
+function chartedSlides(outFile) {
+  if (!outFile || !fs.existsSync(outFile)) return [];
+  let files;
+  try {
+    files = unzip(fs.readFileSync(outFile));
+  } catch {
+    return [];
+  }
+  const out = [];
+  slideOrderPaths(files).forEach((slidePath, i) => {
+    const tags = readSlideTags(files, slidePath);
+    const baseline = decodeSourceTags(tags)?.baseline ?? null;
+    if (!hasChart(baseline)) return;
+    out.push({ slideIndex: i + 1, slidePath, guid: tags[TAG_GUID] ?? null, baseline });
+  });
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Live deck (push --replace) — plan Phase C2
 // ---------------------------------------------------------------------------
@@ -228,10 +260,16 @@ export async function collectLiveReconcileInputs({
     if (!baseline) continue;
     // The BYTES carry the current state; the TAGS carry the baseline. Never the
     // other way round — exportAsBase64 strips tags (office-js #6104).
-    // Chart hashes are dropped from BOTH sides — this repo cannot produce one
-    // (CHART HASH note in pptx/tags.mjs), and sending a null against the
-    // baseline's real hash would make the SERVER report a chart edit that never
-    // happened.
+    // A slide holding a chart goes to the add-in as those bytes: only it can
+    // read a chart, so it projects the current state and folds a chart edit.
+    if (hasChart(baseline)) {
+      reconcile[fileName] = {
+        baseline,
+        package: slide.base64,
+        ...(acks[fileName] ? { ack: acks[fileName] } : {}),
+      };
+      continue;
+    }
     const current = withoutChartHashes(
       computeProjection(unzip(Buffer.from(slide.base64, "base64"))),
     );
@@ -311,7 +349,7 @@ export function applyReconcileResponse({ deckDir, sent, result }) {
         "utf8",
       );
       process.stderr.write(
-        `note: folded ${entry.appliedTextEdits ?? 0} manual text edit(s) from ` +
+        `note: folded ${entry.appliedTextEdits ?? 0} manual edit(s) (text, charts) from ` +
           `PowerPoint into slides/${safeName}\n`,
       );
     }

package/src/lib/record-client.mjs

@@ -0,0 +1,175 @@
+// Network half of `slidemind record`: the backend's record service, and
+// nothing else. No filesystem, no deck state — what a response means for the
+// local binding is src/lib/record-state.mjs's job, and applying it is an
+// explicit step the caller takes AFTER the network call (a background sync
+// that wrote straight into the file would discard an edit made while the
+// request was in flight — see synchronization.md).
+//
+// Results are the service's JSON as sent, plus `identity` when the backend
+// advertises stable item identity (contracts.md §6). Refusals arrive as
+// errors carrying `code` (one of REFUSALS' keys, `conflict`, `stale`,
+// `version_unknown`, `backend_ambiguous`) and, where the service sent one,
+// `body`. Legacy wire codes are mapped HERE and only here.
+
+// The record service lives at `/api/cli/<kind>/record`, where the kind is the
+// CLIENT's namespace. A backend advertising `sharedRecords.kinds: ["*"]` takes
+// any name, and this client then uses one plain default; a backend that lists
+// kinds is served exactly those. This file names no pack. A caller that knows
+// its kind (a binding's `recordKind`, `--kind`) passes it.
+export const DEFAULT_RECORD_KIND = "record";
+export async function resolveRecordKind(backendURL, explicit = null) {
+  if (typeof explicit === "string" && explicit.trim()) return explicit.trim();
+  const { backendCapabilities } = await import("../bridge/client/transport.mjs");
+  const kinds = (await backendCapabilities(backendURL))?.sharedRecords?.kinds;
+  const list = Array.isArray(kinds) ? kinds.filter((k) => typeof k === "string" && k) : [];
+  if (list.includes("*")) return DEFAULT_RECORD_KIND;
+  if (list.length === 1) return list[0];
+  const err = new Error(
+    list.length
+      ? `this backend serves several record kinds (${list.join(", ")}); name one with --kind <kind>.`
+      : "this backend advertises no shared record kind (sharedRecords.kinds); it cannot host a record.",
+  );
+  err.code = list.length ? "kind_ambiguous" : "unsupported";
+  throw err;
+}
+const routeFor = (kind) => `/api/cli/${encodeURIComponent(kind)}/record`;
+
+// The refusals a user can act on. Everything else is re-thrown for the
+// top-level handler — a stack trace is a bug report, not a remedy.
+export const REFUSALS = {
+  login_required:
+    "your Microsoft 365 sign-in is missing or expired — run `slidemind login`, then repeat this command.",
+  access_denied:
+    "you cannot reach that record. Ask whoever owns the folder to share it with you, then try again.",
+  offline:
+    "the slidemind backend could not be reached. Nothing was sent and nothing local was changed.",
+  not_found: "no record at that link — check the link, or create one first.",
+  name_exists:
+    "a file of that name already exists in that folder. Pick another --name.",
+  sharepoint_write_disabled:
+    "this deployment has record writing switched off. Nothing was written.",
+  backend_ambiguous:
+    "several environments are connected. Name one with --backend <env>.",
+};
+
+export function refusalCode(err) {
+  if (err?.code === "backend_ambiguous") return "backend_ambiguous";
+  // login_required arrives as a 403 too, so it is read before the status.
+  if (err?.code === "login_required") return "login_required";
+  if (err?.status === 403) return "access_denied";
+  if (err?.status === 404 && err?.body?.error === "not_found") return "not_found";
+  if (
+    err?.code === "bridge_timeout" ||
+    /relay unreachable/i.test(String(err?.message ?? ""))
+  ) {
+    return "offline";
+  }
+  const named = typeof err?.body?.error === "string" ? err.body.error : null;
+  return named && REFUSALS[named] ? named : null;
+}
+
+// Which paired backend a record call goes to. Pure over the session list so
+// the rule is testable without a config dir:
+//   1. an explicit scope (`--backend` / SLIDEMIND_BACKEND) must name exactly one;
+//   2. else the binding's own pinned backend, if it is still paired;
+//   3. else the only paired backend;
+//   4. else `backend_ambiguous` — a record lives in one tenant, and the global
+//      default is not evidence of which one.
+export function pickRecordBackend(sessions, { binding = null, scoped = false } = {}) {
+  const ambiguous = () => {
+    const err = new Error(
+      `several environments are connected (${sessions.map((s) => s.label).join(", ")}). ` +
+        "Name one with --backend <env>.",
+    );
+    err.code = "backend_ambiguous";
+    return err;
+  };
+  if (scoped) {
+    if (sessions.length !== 1) throw ambiguous();
+    return sessions[0].backendURL;
+  }
+  const pinned = binding?.backendURL;
+  if (pinned && sessions.some((s) => s.backendURL === pinned)) return pinned;
+  if (sessions.length === 1) return sessions[0].backendURL;
+  throw ambiguous();
+}
+
+export async function resolveRecordBackend(binding = null) {
+  const { sessionsInScope } = await import("../bridge/client/transport.mjs");
+  const scoped = Boolean(process.env.SLIDEMIND_BACKEND?.trim());
+  return pickRecordBackend(sessionsInScope(), { binding, scoped });
+}
+
+// `{driveId,itemId}` once the binding carries stable identity, else the url.
+// Never both: the service refuses mixed selectors.
+export function recordSelector(binding) {
+  if (binding?.driveId && binding?.itemId) {
+    return { driveId: binding.driveId, itemId: binding.itemId };
+  }
+  return { url: binding?.url ?? null };
+}
+
+// The user's OWN identity rides every call: the service reads and writes the
+// file as them, so folder permissions stay the access model.
+async function request(backendURL, method, { kind = null, query = "", body = null } = {}) {
+  const { bridgeFetch, graphHeaders } = await import(
+    "../bridge/client/transport.mjs"
+  );
+  const recordKind = await resolveRecordKind(backendURL, kind);
+  const headers = { accept: "application/json", ...(await graphHeaders(backendURL)) };
+  if (body) headers["content-type"] = "application/json";
+  try {
+    const res = await bridgeFetch(
+      `${routeFor(recordKind)}${query}`,
+      { method, headers, ...(body ? { body: JSON.stringify(body) } : {}) },
+      backendURL,
+    );
+    // the kind rides on the result so the binding remembers which service holds the record
+    return { ...normalize((await res.json()) ?? {}), recordKind };
+  } catch (err) {
+    throw typed(err);
+  }
+}
+
+// One `code` per error so callers switch on it, never on status+body pairs.
+function typed(err) {
+  if (!err || typeof err !== "object") return err;
+  if (err.status === 409 && err.body?.error === "conflict") err.code = "conflict";
+  else if (err.status === 409 && err.body?.error === "stale") err.code = "stale";
+  else if (err.body?.error === "version_unknown") err.code = "version_unknown";
+  else {
+    const code = refusalCode(err);
+    if (code) err.code = code;
+  }
+  return err;
+}
+
+// Older services answer without `identity`; a newer one's is passed through
+// only when it is the well-formed object §6 promises.
+function normalize(data) {
+  const id = data?.identity;
+  if (!id || typeof id !== "object" || typeof id.itemId !== "string") {
+    return data;
+  }
+  return { ...data, identity: id };
+}
+
+function queryFor(selector) {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(selector)) if (v) q.set(k, v);
+  return `?${q.toString()}`;
+}
+
+export function createRecord(backendURL, { kind = null, folderUrl, name, plan }) {
+  return request(backendURL, "POST", { kind, body: { folderUrl, name, plan } });
+}
+
+export function getRecord(backendURL, selector, { kind = null } = {}) {
+  return request(backendURL, "GET", { kind, query: queryFor(selector) });
+}
+
+// `plan` is sent as given: stripping `approval` from an ordinary save is the
+// caller's decision (record-state.planToSend), not the transport's.
+export function putRecord(backendURL, { kind = null, selector, base, plan }) {
+  return request(backendURL, "PUT", { kind, body: { ...selector, base, plan } });
+}

package/src/lib/record-state.mjs

@@ -0,0 +1,151 @@
+// Local half of `slidemind record`: the binding in `state/record.json` and the
+// conflicts sidecar. Content-blind, like the command — it stores what the
+// service sent and never learns what a field means.
+//
+//   state/record.json            url, name, eTag, versionLabel, the plan as
+//                                last RECEIVED (`base`), the permanent link,
+//                                the local file it syncs — plus, once a backend
+//                                says so, the stable identity: backendURL,
+//                                tenantId, driveId, itemId, parentId, recordKind.
+//   state/record-conflicts.json  written only when a sync came back with
+//                                same-field conflicts.
+//
+// `base` is load-bearing: it is the version this machine loaded, and it is what
+// the service diffs "mine" against. It is updated ONLY from a response
+// (applyRecordResponse), never from the local file.
+//
+// Identity is additive and lazy: a legacy binding stays valid, and the fields
+// fill in from the next response that carries them. Nothing here guesses a
+// backend — see record-client.pickRecordBackend.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { deckRoot, statePath } from "./deck-paths.mjs";
+
+export const RECORD_FILE = "record.json";
+export const CONFLICTS_FILE = "record-conflicts.json";
+export const SCHEMA_VERSION = 1;
+
+const IDENTITY_FIELDS = ["tenantId", "driveId", "itemId", "parentId"];
+
+function readJsonOrNull(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// Write-then-rename: a kill mid-write must not leave half a binding behind.
+function writeJsonAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+export function recordStatePath(deckDir) {
+  return statePath(deckDir, RECORD_FILE);
+}
+
+export function conflictsPath(deckDir) {
+  return statePath(deckDir, CONFLICTS_FILE);
+}
+
+export function readRecordState(deckDir) {
+  return readJsonOrNull(recordStatePath(deckDir));
+}
+
+export function writeRecordState(deckDir, state) {
+  return writeJsonAtomic(recordStatePath(deckDir), state);
+}
+
+export function readConflicts(deckDir) {
+  return readJsonOrNull(conflictsPath(deckDir));
+}
+
+export function writeConflicts(deckDir, body) {
+  return writeJsonAtomic(conflictsPath(deckDir), {
+    merged: body.merged ?? null,
+    conflicts: Array.isArray(body.conflicts) ? body.conflicts : [],
+    current: body.current ?? null,
+    eTag: body.eTag ?? null,
+  });
+}
+
+export function clearConflicts(deckDir) {
+  fs.rmSync(conflictsPath(deckDir), { force: true });
+}
+
+// The local file is stored relative to the deck when it lives inside it, so a
+// moved or copied deck still knows which file its record syncs.
+export function storeFile(deckDir, file) {
+  const rel = path.relative(deckRoot(deckDir), file);
+  return rel && !rel.startsWith("..") && !path.isAbsolute(rel)
+    ? rel.split(path.sep).join("/")
+    : file;
+}
+
+export function resolveStoredFile(deckDir, stored) {
+  if (!stored) return null;
+  return path.isAbsolute(stored) ? stored : path.join(deckRoot(deckDir), stored);
+}
+
+export function writeRecordFile(file, plan) {
+  writeJsonAtomic(file, plan);
+}
+
+// The link a colleague opens. The service mints it (it alone knows the page's
+// origin); `url` is the fallback so a response without one still prints
+// something a human can follow.
+export const pageLink = (data, fallback = null) => data?.link ?? fallback ?? data?.url ?? null;
+
+// The binding a response describes. `previous` keeps whatever the response
+// leaves out — a sync answers about a record the binding already identifies,
+// so losing the url (or the identity) here would strand the deck.
+export function recordStateFrom(
+  data,
+  { file, deckDir, link, backendURL = null, previous = null },
+) {
+  const identity = data?.identity ?? {};
+  const state = {
+    schemaVersion: SCHEMA_VERSION,
+    url: data.url ?? previous?.url ?? null,
+    name: data.name ?? previous?.name ?? null,
+    eTag: data.eTag ?? null,
+    versionLabel: data.versionLabel ?? null,
+    base: data.plan ?? null,
+    link: link ?? previous?.link ?? pageLink(data),
+    file: storeFile(deckDir, file),
+    syncedAt: new Date().toISOString(),
+    backendURL: backendURL ?? previous?.backendURL ?? null,
+    recordKind: previous?.recordKind ?? data?.recordKind ?? null,
+  };
+  for (const k of IDENTITY_FIELDS) {
+    const v = identity[k] ?? previous?.[k] ?? null;
+    if (v !== null) state[k] = v;
+  }
+  return state;
+}
+
+// What an ordinary save sends. `approval` is the service's to keep: it is only
+// ever accepted from the one command that means it, and stripped from every
+// other write so a sync cannot carry an approval nobody asked for.
+export function planToSend(plan, { approval = false } = {}) {
+  const mine = { ...plan };
+  if (!approval) delete mine.approval;
+  return mine;
+}
+
+// The explicit writeback step after a network call succeeded: plan file,
+// binding, and the conflicts the write settled. Callers decide WHEN — never
+// inside the request, and never for a response that is not this deck's.
+export function applyRecordResponse(deckDir, data, { file, link, backendURL, previous }) {
+  writeRecordFile(file, data.plan);
+  const state = recordStateFrom(data, { file, deckDir, link, backendURL, previous });
+  writeRecordState(deckDir, state);
+  clearConflicts(deckDir);
+  return state;
+}