slidemind 0.3.20 → 0.4.0

package/src/cli/revision.mjs

@@ -0,0 +1,686 @@
+// `slidemind revision <sub>` and `slidemind rebase <deck>` — the user-facing
+// half of the local revision protocol (src/lib/revision.mjs).
+//
+// Two things live here that nothing else in the CLI does:
+//
+//   • OWNERSHIP that outlives one command. A skill editing a deck writes raw
+//     .jsx files, runs several commands and fans work out to parallel lanes;
+//     a per-command lock protects none of that. `revision begin` hands back an
+//     owner token, the session exports it as SLIDEMIND_OWNER, and every
+//     command underneath re-enters under it instead of blocking.
+//   • ACCEPTANCE as a deliberate act. A build produces a candidate; it does not
+//     decide that the candidate is the deck. `revision accept --candidate <id>`
+//     is where a local-only deck moves its accepted base, and it refuses a
+//     stale one, a conflicted deck, and a deck bound to a remote copy (there,
+//     only a confirmed publish receipt may advance the base).
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { fail, resolveDeckArg, deckSlug, splitDeckArg, requireReviewApproved } from "./common.mjs";
+import {
+  acquireOwner,
+  candidateStale,
+  journalIncomplete,
+  listCandidates,
+  readBusy,
+  readCandidate,
+  readConflicts,
+  readRevision,
+  releaseStaleOwner,
+  revisionStatus,
+  stageIncoming,
+  acceptCandidate,
+} from "../lib/revision.mjs";
+import {
+  SESSION_OPERATION_KINDS,
+  applyRequirementAmendment,
+  checkRedesignTransition,
+  closeOpenOperations,
+  migrateEditState,
+  openOperations,
+  openRedesigns,
+  parseSlideSelection,
+  recordOperation,
+  resolveSlideTargets,
+} from "../lib/edit-state.mjs";
+import { EDIT_OPERATION_VERSION } from "../lib/edit-operations.mjs";
+import { editTransitionRefusals } from "../lib/edit-transitions.mjs";
+
+const json = (data) => process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+
+/**
+ * Refuse a deck whose slides changed in a way the open scopes do not authorize —
+ * another slide or a sibling beside a target, an import's pragma dropped outside
+ * a redesign. The add-in refuses the same transitions at the write; here the
+ * first command that reads the deck does (view-draft, build-pptx, push).
+ */
+export function requireAuthorizedEdits(deckDir) {
+  const refusals = editTransitionRefusals(deckDir);
+  if (refusals.length === 0) return;
+  fail(`nothing was rendered — this change is outside what the edit was authorized to do:\n${refusals.map((r) => `  ${r}`).join("\n")}`, 2);
+}
+
+function requireAdopted(deckDir) {
+  const revision = readRevision(deckDir);
+  if (!revision) {
+    fail(
+      `${deckSlug(deckDir)} has no accepted base — it was authored here rather than adopted from a .pptx. ` +
+        `\`slidemind adopt <file.pptx> --deck ${deckSlug(deckDir)}\` establishes one.`,
+    );
+  }
+  return revision;
+}
+
+// Every open redesign on this deck must have replaced its target, not sat next
+// to it. Reports every violation at once — an agent that has to be told one
+// problem per run will fix them one per run.
+function assertRedesignsReplaced(deckDir) {
+  for (const operation of openRedesigns(deckDir)) {
+    const { ok, violations } = checkRedesignTransition(deckDir, operation);
+    if (ok) continue;
+    fail(
+      `redesign ${operation.operationId} did not replace what it was scoped to:\n` +
+        violations.map((v) => `  [${v.code}] ${v.detail}`).join("\n"),
+      2,
+    );
+  }
+}
+
+/**
+ * Seed a preservation record for every rendered slide that has none, from its
+ * current evidence — the add-in seeds at every render the same way
+ * (`preservation-seed.ts`), so what a slide owes is checked from its first
+ * draft on, not only once a scope or an adopt happened to capture it.
+ */
+export function seedRenderedSlides(deckDir, files) {
+  const selection = (files ?? []).filter((f) => /\.jsx$/i.test(f));
+  if (selection.length === 0) return;
+  try {
+    migrateEditState(deckDir, { selection });
+  } catch {
+    // An unreadable record is never rewritten; the diagnostics name it and
+    // delivery refuses on it.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// revision
+// ---------------------------------------------------------------------------
+
+export async function cmdRevision(rest) {
+  const sub = rest[0];
+  const args = rest.slice(1);
+  switch (sub) {
+    case "begin":
+      return revisionBegin(args);
+    case "finish":
+      return revisionFinish(args);
+    case "status":
+      return revisionStatusCmd(args);
+    case "accept":
+      return revisionAccept(args);
+    default:
+      fail(
+        `usage: slidemind revision <begin|finish|status|accept> <deck> [options]\n` +
+          `  begin   take local ownership of the deck for a whole edit session\n` +
+          `            --operation ${SESSION_OPERATION_KINDS.join("|")}  scope this session to one kind of edit\n` +
+          `            --slides <sel>   which slides it may touch — '2,7', '2-4', 'all' or a file name\n` +
+          `                             (required with --operation; resolved to durable slide ids at once)\n` +
+          `            --scope <file.json>  per-slide declared changes / live identity / repair budget\n` +
+          `            --summary <text> what the user asked for, in one line\n` +
+          `            --command <name> label for the ownership record (default: session)\n` +
+          `  finish  release it (work and candidates are kept; open edit scopes are closed)\n` +
+          `  status  accepted base, generation, dirty slides, candidates, staged snapshots, open scopes\n` +
+          `  accept  --candidate <id>: make a validated local candidate the accepted base\n` +
+          `  --json  machine-readable result (begin | status | accept)`,
+      );
+  }
+}
+
+// A structured scope file is how an operation says more than "these slides":
+// the declared changes, the live slide it was read from, a repair budget. Keyed
+// by slide key, file name, stem or 1-based number — whatever the caller already
+// has — and merged onto the resolved target.
+const SCOPE_TARGET_KEYS = [
+  "liveSlideId",
+  "provenance",
+  "baseLiveFingerprint",
+  "sourceRevision",
+  "repairPolicy",
+  "changes",
+];
+
+function readScopeFile(file) {
+  if (!fs.existsSync(file)) fail(`no such file: ${file}`);
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (err) {
+    fail(`${file} is not readable JSON: ${err.message}`);
+  }
+  if (!parsed || typeof parsed !== "object") fail(`${file} must be a JSON object`);
+  const targets = parsed.targets ?? {};
+  if (typeof targets !== "object" || Array.isArray(targets)) {
+    fail(`${file}: "targets" must be an object keyed by slide id, file name or slide number`);
+  }
+  for (const [key, entry] of Object.entries(targets)) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      fail(`${file}: targets["${key}"] must be an object`);
+    }
+    for (const k of Object.keys(entry)) {
+      if (!SCOPE_TARGET_KEYS.includes(k)) {
+        fail(`${file}: targets["${key}"].${k} is not part of an operation target (${SCOPE_TARGET_KEYS.join(", ")})`);
+      }
+    }
+  }
+  return { requestSummary: parsed.requestSummary ?? null, targets };
+}
+
+function revisionBegin(args) {
+  // Parsed here rather than through splitDeckArg: every flag below takes a
+  // value, and a positional-scanning split would read `--operation repair`'s
+  // value as the deck.
+  let deck = null;
+  let command = "session";
+  let asJson = false;
+  let operation = null;
+  let slides = null;
+  let scopeFile = null;
+  let summary = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--command") command = args[++i] ?? command;
+    else if (a === "--operation") operation = args[++i] ?? null;
+    else if (a === "--slides") slides = args[++i] ?? null;
+    else if (a === "--scope") scopeFile = args[++i] ?? null;
+    else if (a === "--summary") summary = args[++i] ?? null;
+    else if (a === "--json") asJson = true;
+    else if (a.startsWith("-")) fail(`unknown flag: ${a}`);
+    else if (deck === null) deck = a;
+    else fail(`unexpected argument: ${a}`);
+  }
+  if (!deck) {
+    fail(
+      `usage: slidemind revision begin <deck> [--operation ${SESSION_OPERATION_KINDS.join("|")} --slides <sel>]\n` +
+        `                                     [--scope <file.json>] [--summary <text>] [--command <name>] [--json]`,
+    );
+  }
+  if (operation && !SESSION_OPERATION_KINDS.includes(operation)) {
+    fail(
+      `--operation must be one of ${SESSION_OPERATION_KINDS.join(", ")} (got '${operation}'). ` +
+        `\`create\` is what a build infers for a genuinely new slide, not something a session claims.`,
+    );
+  }
+  // A scope with no slides is not a scope: it would silently claim the deck.
+  if (operation && !slides) fail(`--operation ${operation} needs --slides <sel> — the slides it may touch`);
+  if (!operation && (slides || scopeFile)) fail(`--slides/--scope describe an operation; add --operation <kind>`);
+  const scope = scopeFile ? readScopeFile(scopeFile) : null;
+
+  const deckDir = resolveDeckArg(deck, { allowUnfinished: true });
+  let held;
+  try {
+    held = acquireOwner(deckDir, { command: operation ? `${command} (${operation})` : command, session: true });
+  } catch (err) {
+    if (err?.code === "deck_busy") fail(err.message, 2);
+    throw err;
+  }
+
+  let recorded = null;
+  let migration = null;
+  let amended = null;
+  if (operation) {
+    try {
+      // Capture what the slides owe BEFORE the first safeguarded edit: a deck
+      // that predates these records stays editable, its obligations read from
+      // the source actually on disk.
+      migration = migrateEditState(deckDir);
+      recorded = recordOperation(deckDir, buildOperation({ deckDir, kind: operation, slides, scope, summary }));
+      // A declared removal or addition amends the record HERE, against the base
+      // the scope was just written for — not at commit, when the source has
+      // moved and nothing can be tied to it any more.
+      amended = applyRequirementAmendment(deckDir, recorded);
+    } catch (err) {
+      // Nothing was opened, so nothing stays held: a session token for a scope
+      // that was refused would lock the deck behind an edit that never began.
+      held.release();
+      if (
+        [
+          "operation_conflict",
+          "operation_invalid",
+          "state_invalid",
+          "unsupported_version",
+          "state_unreadable",
+          "bad_selection",
+          "no_preservation_record",
+          "source_moved",
+          "source_missing",
+        ].includes(err?.code)
+      ) {
+        fail(err.message, 2);
+      }
+      throw err;
+    }
+  }
+
+  // The scope IS the unit of repair, and this command is the only thing that
+  // records one — so the next step is named here rather than left to be
+  // guessed. `--repair` runs the whole scope: it refuses a targeted-edit scope
+  // by name, and refuses `--only NN` inside a wider one (a partial run would
+  // mark the operation done for slides it never touched).
+  if (recorded?.kind === "repair") {
+    process.stderr.write(
+      `slidemind: run the repair inside this session — \`slidemind transcribe ${deck} --repair\` ` +
+        `(the whole scope; re-open with --slides NN to repair one slide alone).\n`,
+    );
+  }
+  const status = revisionStatus(deckDir);
+  if (asJson) {
+    // The token LAST: revisionStatus also reports an `owner` (who holds the
+    // deck), and spreading it over the token would hand the caller an object
+    // where it asked for a string.
+    json({
+      ...status,
+      heldBy: status.owner,
+      owner: held.token,
+      nested: held.nested,
+      operation: recorded,
+      migration,
+      amended,
+    });
+    return;
+  }
+  process.stdout.write(
+    `Owner token for ${deckSlug(deckDir)}: ${held.token}\n` +
+      `Export it so every command in this session runs under it:\n` +
+      `  export SLIDEMIND_OWNER=${held.token}\n` +
+      `Release it when the session ends: slidemind revision finish ${deck}\n` +
+      `Generation ${status.generation}${status.localDirty ? `, ${status.dirtySlides.length} slide(s) with unpublished edits` : ", clean"}\n` +
+      (recorded
+        ? `Scope ${recorded.operationId}: ${recorded.kind} on ${recorded.targets.length} slide(s)\n` +
+          (recorded.kind === "redesign"
+            ? `Redesign replaces these slides in place: rewrite each file listed below, keep its ` +
+              `native placeholders, and do not add a slide beside it.\n`
+            : ``) +
+          recorded.targets
+            .map((t) => `  ${t.jsxPath}  ${t.slideKey}  base ${String(t.baseSourceHash ?? "").slice(0, 12)}\n`)
+            .join("") +
+          (amended?.superseded.length || amended?.added.length
+            ? `Amended on request: ${amended.superseded.length} obligation(s) retired, ` +
+              `${amended.added.length} required addition(s).\n`
+            : ``) +
+          (migration?.seeded.length
+            ? `Captured preservation records for ${migration.seeded.length} slide(s) from their current source ` +
+              `(${[...new Set(migration.seeded.map((e) => e.origin))].join(", ")}); evidence: unknown until a render verdict.\n` +
+              migration.seeded
+                .flatMap((e) => e.limitations.map((l) => `  limitation ${path.basename(e.jsxPath)}: ${l}\n`))
+                .join("")
+            : ``)
+        : ``),
+  );
+}
+
+// One operation record from the resolved targets. `changes` stays whatever the
+// scope file declared — empty when it declared none, which authorizes no
+// deletion and no property change.
+function buildOperation({ deckDir, kind, slides, scope, summary }) {
+  // The whole deck first: `preparedSlideKeys` is what later lets a redesign
+  // tell a slide that appeared since from one that was always there
+  // (checkRedesignTransition). Resolved here because this is the moment the
+  // scope is taken — afterwards nobody can reconstruct it.
+  const deckSlides = resolveSlideTargets(deckDir);
+  const selection = parseSlideSelection(slides);
+  const targets = selection
+    ? resolveSlideTargets(deckDir, { selection })
+    : deckSlides;
+  if (targets.length === 0) fail(`--slides matched no slide in ${deckSlug(deckDir)}`);
+  const scoped = (target) => {
+    const entry =
+      scope?.targets?.[target.slideKey] ??
+      scope?.targets?.[target.file] ??
+      scope?.targets?.[target.file.replace(/\.(jsx|pptx)$/i, "")] ??
+      scope?.targets?.[String(target.number)] ??
+      null;
+    return entry ?? {};
+  };
+  return {
+    version: EDIT_OPERATION_VERSION,
+    operationId: `op-${randomUUID()}`,
+    kind,
+    preparedSlideKeys: deckSlides.map((t) => t.slideKey),
+    // Every slide's bytes as the scope opened: what tells a slide changed outside
+    // the scope (or a sibling written beside a target) from one left alone
+    // (src/lib/edit-transitions.mjs).
+    preparedSourceHashes: Object.fromEntries(deckSlides.map((t) => [t.slideKey, t.sourceHash])),
+    requestSummary:
+      summary ?? scope?.requestSummary ?? `${kind} on ${targets.map((t) => t.file).join(", ")}`,
+    status: "prepared",
+    targets: targets.map((t) => ({
+      slideKey: t.slideKey,
+      jsxPath: t.jsxPath,
+      baseSourceHash: t.sourceHash,
+      provenance: "local",
+      changes: [],
+      ...scoped(t),
+    })),
+  };
+}
+
+function revisionFinish(args) {
+  const { deck, passthrough } = splitDeckArg(args, "revision finish");
+  let owner = process.env.SLIDEMIND_OWNER ?? null;
+  let force = false;
+  for (let i = 0; i < passthrough.length; i++) {
+    const a = passthrough[i];
+    if (a === "--owner") owner = passthrough[++i] ?? owner;
+    else if (a === "--force") force = true;
+    else fail(`unknown flag: ${a}`);
+  }
+  const deckDir = resolveDeckArg(deck, { allowUnfinished: true });
+  const busy = readBusy(deckDir);
+  if (!busy) {
+    process.stdout.write(`${deckSlug(deckDir)} has no owner — nothing to release.\n`);
+    return;
+  }
+  const released = releaseStaleOwner(deckDir, { owner, force });
+  if (!released) {
+    fail(
+      (busy.kind === "session"
+        ? `${deckSlug(deckDir)} is held by an edit session (\`${busy.command}\`, started ${busy.startedAt}).`
+        : `${deckSlug(deckDir)} is owned by a running \`${busy.command}\` (pid ${busy.pid}, since ${busy.startedAt}).`) +
+        ` Pass --owner <token> to release your own session (export SLIDEMIND_OWNER and it is read from there), ` +
+        `or --force to release it anyway.`,
+      2,
+    );
+  }
+  // Releasing ownership is NOT discarding work: the dirty files, the candidates
+  // and any journaled operation are all exactly where they were. What DOES end
+  // is the edit scope — a prepared operation whose session is over authorizes
+  // nothing, and leaving it open would lease those slides forever.
+  let closed = [];
+  try {
+    closed = closeOpenOperations(deckDir);
+  } catch (err) {
+    // An unreadable scope file is not a reason to refuse releasing the deck.
+    process.stderr.write(`slidemind: open edit scopes were left as they are — ${err.message}\n`);
+  }
+  const status = revisionStatus(deckDir);
+  process.stdout.write(
+    `Released ${deckSlug(deckDir)} (was ${released.command}).\n` +
+      (closed.length ? `Closed ${closed.length} open edit scope(s): ${closed.join(", ")}\n` : ``) +
+      (status.localDirty
+        ? `${status.dirtySlides.length} slide(s) still carry unpublished edits — they are untouched.\n`
+        : `Nothing unpublished.\n`),
+  );
+}
+
+// Reporting must survive a record it cannot read: `status` is the command
+// somebody runs BECAUSE the deck is in a strange state.
+function openScopes(deckDir) {
+  try {
+    return openOperations(deckDir);
+  } catch {
+    return [];
+  }
+}
+
+function revisionStatusCmd(args) {
+  const { deck, passthrough } = splitDeckArg(args, "revision status");
+  const asJson = passthrough.includes("--json");
+  const deckDir = resolveDeckArg(deck, { allowUnfinished: true });
+  const status = revisionStatus(deckDir);
+  if (asJson) return json(status);
+  if (!status.adopted) {
+    // A deck authored here still has edit scopes, and they are the only thing
+    // this command can report about it.
+    process.stdout.write(
+      `${deckSlug(deckDir)} has no accepted base (authored here, not adopted from a .pptx).\n` +
+        openScopes(deckDir)
+          .map((op) => `  scope       ${op.operationId} ${op.kind} (${op.status}) on ${op.targets.length} slide(s)\n`)
+          .join(""),
+    );
+    return;
+  }
+  const lines = [
+    `${deckSlug(deckDir)} — generation ${status.generation}`,
+    status.base
+      ? `  base        ${status.base.sha256.slice(0, 12)} · ${status.base.slideCount} slide(s) · accepted ${status.base.acceptedAt}`
+      : `  base        none — authored here; the first confirmed publish (or \`revision accept\`) sets it`,
+    `  origin      ${status.origin?.kind ?? "unknown"}${status.origin?.file ? ` (${status.origin.file})` : ""}`,
+    `  local       ${status.localDirty ? `${status.dirtySlides.length} slide(s) changed: ${status.dirtySlides.join(", ")}` : "clean"}`,
+  ];
+  if (status.added.length) lines.push(`  added       ${status.added.join(", ")}`);
+  if (status.removed.length) lines.push(`  removed     ${status.removed.join(", ")}`);
+  if (status.orderChanged) lines.push(`  order       changed locally`);
+  if (status.designMoved) {
+    lines.push(`  design      moved since the accepted base — untouched slides keep the old design until \`build-pptx --refresh-design\``);
+  }
+  if (status.unverified.length) {
+    lines.push(
+      `  unverified  ${status.unverified.length} slide(s) carry a chart, whose data this CLI cannot hash — ` +
+        `"unchanged" is not proved for them`,
+    );
+  }
+  lines.push(
+    `  candidate   ${
+      status.candidate
+        ? `${status.candidate.candidateId}${status.candidate.stale ? ` (stale: ${status.candidate.stale})` : " (ready to accept)"}`
+        : "none"
+    }`,
+  );
+  if (status.staged.length) {
+    lines.push(`  staged      ${status.staged.map((s) => s.revisionId).join(", ")}`);
+  }
+  if (status.conflicts) lines.push(`  conflicts   ${status.conflicts} unresolved`);
+  if (status.owner) {
+    lines.push(`  owner       ${status.owner.command} (pid ${status.owner.pid}, since ${status.owner.startedAt})`);
+  }
+  if (status.journal) lines.push(`  journal     an unfinished ${status.journal} — re-run it to recover`);
+  for (const op of openScopes(deckDir)) {
+    lines.push(`  scope       ${op.operationId} ${op.kind} (${op.status}) on ${op.targets.length} slide(s)`);
+  }
+  process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+async function revisionAccept(args) {
+  const { deck, passthrough } = splitDeckArg(args, "revision accept");
+  let candidateId = null;
+  let asJson = false;
+  for (let i = 0; i < passthrough.length; i++) {
+    const a = passthrough[i];
+    if (a === "--candidate") candidateId = passthrough[++i] ?? null;
+    else if (a === "--json") asJson = true;
+    else fail(`unknown flag: ${a}`);
+  }
+  const deckDir = resolveDeckArg(deck, { allowUnfinished: true });
+  requireAdopted(deckDir);
+  if (!candidateId) {
+    const available = listCandidates(deckDir);
+    fail(
+      `usage: slidemind revision accept <deck> --candidate <id>\n` +
+        (available.length
+          ? `candidates:\n${available
+              .map((c) => {
+                const why = candidateStale(deckDir, c);
+                return `  ${c.candidateId}  ${c.createdAt}  ${why ? `stale — ${why}` : "ready"}`;
+              })
+              .join("\n")}`
+          : `this deck has no candidates yet — run \`slidemind build-pptx ${deck}\` first`),
+    );
+  }
+  const held = acquireOwner(deckDir, { command: "revision accept" });
+  try {
+    await requireReviewApproved(deckDir);
+    // An explicit redesign is authorized by the request — it is never asked
+    // about again here. What IS checked is that it replaced what it was pointed
+    // at: same identity, required content carried forward, native packages
+    // still backed, and no second slide left beside the original (E18). The
+    // base may not move onto a candidate that failed that.
+    assertRedesignsReplaced(deckDir);
+    const next = acceptCandidate(deckDir, candidateId, { owner: held.token });
+    const status = revisionStatus(deckDir);
+    if (asJson) return json({ accepted: candidateId, ...status });
+    process.stdout.write(
+      `Accepted ${candidateId} as the base of ${deckSlug(deckDir)} (generation ${next.generation}).\n` +
+        (status.localDirty
+          ? `${status.dirtySlides.length} slide(s) still carry edits made since that build.\n`
+          : `The workspace matches the accepted base.\n`),
+    );
+  } catch (err) {
+    if (["remote_bound", "conflicted", "candidate_stale", "candidate_invalid", "generation_moved", "ownership_lost"].includes(err?.code)) {
+      fail(err.message, 2);
+    }
+    throw err;
+  } finally {
+    held.release();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// rebase
+// ---------------------------------------------------------------------------
+
+export async function cmdRebase(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "rebase");
+  let incoming = null;
+  let resolve = null;
+  let dryRun = false;
+  let asJson = false;
+  for (let i = 0; i < passthrough.length; i++) {
+    const a = passthrough[i];
+    if (a === "--incoming") {
+      incoming = passthrough[++i] ?? null;
+      if (!incoming) fail("--incoming expects a .pptx file or a staged revision id");
+    } else if (a === "--resolve") {
+      resolve = passthrough[++i] ?? null;
+      if (!resolve) fail("--resolve expects a resolution .json file");
+    } else if (a === "--dry-run") {
+      dryRun = true;
+    } else if (a === "--json") {
+      asJson = true;
+    } else {
+      fail(`unknown flag: ${a}`);
+    }
+  }
+  const deckDir = resolveDeckArg(deck, { allowUnfinished: true });
+  requireAdopted(deckDir);
+  const { applyRebase, classifyRebase, resolutionTemplate, resumeRebase } = await import(
+    "../lib/rebase.mjs"
+  );
+
+  // No flags, but an unfinished rebase on disk: that is the recovery call. Every
+  // other command refuses this deck until the half-applied generation resolves,
+  // and re-running from the staged bytes is how it resolves.
+  const open = journalIncomplete(deckDir);
+  if (!incoming && !resolve && open?.op === "rebase") {
+    const held = acquireOwner(deckDir, { command: "rebase" });
+    try {
+      const resumed = resumeRebase(deckDir, open, { owner: held.token });
+      if (asJson) return json(resumed);
+      process.stdout.write(
+        resumed.resumed
+          ? `Finished the interrupted rebase of ${deckSlug(deckDir)} (generation ${resumed.generation}).\n` +
+            (resumed.stillDirty.length
+              ? `Still unpublished: ${resumed.stillDirty.join(", ")}\n`
+              : `The workspace matches the accepted base.\n`)
+          : `Nothing to finish: ${resumed.reason}\n`,
+      );
+      return;
+    } finally {
+      held.release();
+    }
+  }
+  if (!incoming && !resolve) {
+    fail(
+      `usage: slidemind rebase <deck> --incoming <file.pptx | revisionId> [--dry-run]\n` +
+        `       slidemind rebase <deck> --resolve <resolution.json>\n` +
+        `       slidemind rebase <deck>            (finish an interrupted rebase)`,
+    );
+  }
+
+  // Resolving continues the rebase the conflict manifest belongs to.
+  let revisionId = null;
+  let resolutions = null;
+  if (resolve) {
+    if (!fs.existsSync(resolve)) fail(`no such file: ${resolve}`);
+    try {
+      resolutions = JSON.parse(fs.readFileSync(resolve, "utf8"));
+    } catch (err) {
+      fail(`${resolve} is not readable JSON: ${err.message}`);
+    }
+    revisionId = resolutions.revisionId ?? readConflicts(deckDir)?.revisionId ?? null;
+    if (!revisionId) fail(`${resolve} names no revisionId, and this deck has no open conflict manifest`);
+  } else if (/\.(pptx|pptm|potx|potm|ppsx|ppsm)$/i.test(incoming)) {
+    const file = path.resolve(incoming);
+    if (!fs.existsSync(file)) fail(`no such file: ${incoming}`);
+    revisionId = stageIncoming(deckDir, {
+      bytes: fs.readFileSync(file),
+      source: { kind: "file", path: file, name: path.basename(file) },
+    }).revisionId;
+  } else {
+    revisionId = incoming;
+  }
+
+  if (dryRun) {
+    const classified = classifyRebase(deckDir, revisionId);
+    if (asJson) return json(classified);
+    process.stdout.write(
+      `${deckSlug(deckDir)} vs ${revisionId}:\n` +
+        `  incoming-only  ${classified.remoteOnly.length}\n` +
+        `  local-only     ${classified.localOnly.length}\n` +
+        `  unchanged      ${classified.unchanged.length}\n` +
+        `  conflicts      ${classified.conflicts.length}\n` +
+        classified.notes.map((n) => `  note: ${n}\n`).join("") +
+        classified.conflicts.map((c) => `    [${c.id}] ${c.kind}${c.file ? ` ${c.file}` : ""} — ${c.detail}\n`).join(""),
+    );
+    if (classified.conflicts.length > 0) {
+      const out = path.join(deckDir, "state", "staged", revisionId, "resolution.json");
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, `${JSON.stringify(resolutionTemplate(classified), null, 2)}\n`);
+      process.stdout.write(
+        `  Fill in one choice per conflict and apply it:\n    slidemind rebase ${deck} --resolve ${out}\n`,
+      );
+    }
+    return;
+  }
+
+  const held = acquireOwner(deckDir, { command: "rebase" });
+  try {
+    const result = applyRebase(deckDir, revisionId, { owner: held.token, resolutions });
+    if (asJson) return json(result);
+    process.stdout.write(
+      `Rebased ${deckSlug(deckDir)} onto ${revisionId} (generation ${result.generation}).\n` +
+        `  refreshed from the incoming file: ${result.refreshed.length}\n` +
+        `  removed (deleted there):          ${result.removed.length}\n` +
+        `  kept as unpublished local work:   ${result.localOnly.length}\n` +
+        result.notes.map((n) => `  note: ${n}\n`).join("") +
+        (result.stillDirty.length
+          ? `Still unpublished: ${result.stillDirty.join(", ")}\n`
+          : `The workspace matches the new accepted base.\n`),
+    );
+  } catch (err) {
+    if (err?.code === "rebase_conflicts") {
+      const classified = classifyRebase(deckDir, revisionId);
+      const out = path.join(deckDir, "state", "staged", revisionId, "resolution.json");
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, `${JSON.stringify(resolutionTemplate(classified), null, 2)}\n`);
+      process.stderr.write(
+        `slidemind: ${err.message}\n` +
+          err.conflicts.map((c) => `  [${c.id}] ${c.kind}${c.file ? ` ${c.file}` : ""} — ${c.detail}\n`).join("") +
+          `A resolution skeleton with every hash already filled in is at:\n  ${out}\n` +
+          `Set each "choice" to local, incoming or merged, then:\n` +
+          `  slidemind rebase ${deck} --resolve ${out}\n`,
+      );
+      process.exit(2);
+    }
+    if (["resolution_stale", "no_such_revision", "no_base", "generation_moved", "ownership_lost"].includes(err?.code)) {
+      fail(err.message, 2);
+    }
+    throw err;
+  } finally {
+    held.release();
+  }
+}
+
+export { readCandidate, revisionStatus };