slidemind 0.3.19 → 0.4.0

package/src/cli/remote.mjs

@@ -0,0 +1,818 @@
+import { stageWorkspace } from '../lib/workspace-transaction.mjs';
+import { runDeclared } from '../lib/extensions.mjs';
+// `slidemind open | pull | publish | rename` — the user-facing half of the
+// SharePoint pull/publish protocol (src/lib/publish.mjs).
+//
+// This module owns arguments, credentials and printing. Every decision that
+// could lose work lives in `src/lib/publish.mjs`, so the suite can drive it
+// against a mock provider without a tenant, a token or a network.
+//
+// Two things are deliberately loud here rather than quiet:
+//
+//   • **A switched-off deployment says so.** Every write route is live (doc 20 →
+//     Routes); what still stops a write is the add-in's `sharepointPublish`
+//     policy, and then `publish` refuses with `remote_saving_disabled` and names
+//     `--manual` rather than quietly preparing a manual upload.
+//   • **"Saved" is only ever printed for a confirmed receipt.** Staged, blocked,
+//     pending-manual and unknown-outcome each get their own word, because the
+//     one thing a user must never have to guess is whether their colleague can
+//     now see their edits.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  fail,
+  resolveDeckArg,
+  resolveDeckRoot,
+  deckSlug,
+  splitDeckArg,
+} from "./common.mjs";
+import { acquireOwner, readRevision, revisionStatus } from "../lib/revision.mjs";
+import {
+  bindRemote,
+  computeMode,
+  detachRemote,
+  documentInstance,
+  pendingOperations,
+  readRemote,
+  savedDestination,
+  writeRemote,
+} from "../lib/remote.mjs";
+import {
+  checkFreshness,
+  classifyInstance,
+  classifyOrdinary,
+  contextOfBytes,
+  declaredExtensions,
+  hydrateContext,
+  publishDeck,
+  pullDeck,
+  recoverOperations,
+  renameBound,
+} from "../lib/publish.mjs";
+
+const json = (data) => process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+const note = (line) => process.stderr.write(`  ${line}\n`);
+
+// ---------------------------------------------------------------------------
+// credentials and the provider
+// ---------------------------------------------------------------------------
+
+/**
+ * Everything a remote command needs: which deployment, its SharePoint origin,
+ * the user's own delegated token, and the provider module.
+ *
+ * The origin comes from the backend's published configuration, never from a
+ * hardcoded tenant and never from the link the user typed — a link decides WHICH
+ * ITEM, it does not decide which host slidemind is allowed to send a bearer to.
+ */
+async function remoteSession({ needWrite = false, stop = fail } = {}) {
+  const { sessionsInScope, backendSupportsSharePointPublish } = await import(
+    "../bridge/client/transport.mjs"
+  );
+  const { getSharePointToken, ensureSignedIn, sharePointResource } = await import(
+    "../bridge/graph-auth.mjs"
+  );
+  const provider = await import("../bridge/sharepoint.mjs");
+
+  let sessions;
+  try {
+    sessions = sessionsInScope();
+  } catch (err) {
+    stop(err.message, 1, "not_connected");
+  }
+  if (sessions.length > 1) {
+    stop(
+      `several environments are connected (${sessions.map((s) => s.label).join(", ")}). ` +
+        `Name one with --backend <env>.`,
+      1,
+      "backend_ambiguous",
+    );
+  }
+  const backendURL = sessions[0].backendURL;
+  const origin = await sharePointResource(backendURL);
+  if (!origin) {
+    stop(
+      "this slidemind deployment publishes no SharePoint origin, so there is nothing to open or " +
+        "publish against. Adopt the file from disk instead: `slidemind adopt <file.pptx>`.",
+      1,
+      "no_sharepoint_origin",
+    );
+  }
+  if (needWrite && !(await backendSupportsSharePointPublish(backendURL))) {
+    stop(
+      "publishing back to SharePoint is switched off for this deployment (`remote_saving_disabled`). " +
+        "Prepare a manual handoff instead: `slidemind publish <deck> --manual`.",
+      1,
+      "remote_saving_disabled",
+    );
+  }
+  await ensureSignedIn(backendURL);
+  const token = await getSharePointToken(backendURL);
+  if (!token) {
+    stop(
+      "no SharePoint access token — run `slidemind login`. One sign-in mints both resources; if it " +
+        "succeeds and this still appears, the app registration is missing the SharePoint grant.",
+      1,
+      "login_required",
+    );
+  }
+  const client = provider.createClient({ origin, token });
+  return { provider, client, backendURL, caps: provider.capabilities(client.host) };
+}
+
+function requireBound(deckDir, stop = fail) {
+  const remote = readRemote(deckDir);
+  if (!remote) {
+    stop(
+      `${deckSlug(deckDir)} is not bound to a SharePoint item. ` +
+        `\`slidemind open <link> --deck ${deckSlug(deckDir)}\` binds one.`,
+      1,
+      "identity_unresolved",
+    );
+  }
+  return remote;
+}
+
+// A deck command holds ownership for its whole run, and re-enters an open edit
+// session rather than queueing behind it (SLIDEMIND_OWNER).
+function withOwner(deckDir, command, fn, stop = fail) {
+  let held;
+  try {
+    held = acquireOwner(deckDir, { command });
+  } catch (err) {
+    if (err?.code === "deck_busy") stop(err.message, 2, "deck_busy");
+    throw err;
+  }
+  return Promise.resolve()
+    .then(() => fn(held.token))
+    .finally(() => held.release());
+}
+
+// The typed refusals the protocol raises. Each is a state the user can act on,
+// so each gets a sentence and an exit code — never a stack trace, which tells
+// them nothing and looks like slidemind broke rather than like their file moved.
+const TYPED = {
+  remote_missing: (slug) =>
+    `${slug}'s file is gone from SharePoint. Nothing local was touched and no write will be attempted ` +
+    `until you point the deck somewhere else: \`slidemind open <link> --deck ${slug} --rebind\`.`,
+  identity_unresolved: (slug) =>
+    `${slug} is not bound to a SharePoint item. \`slidemind open <link> --deck ${slug}\` binds one.`,
+  snapshot_raced: () =>
+    `the file kept changing while it was being read, so nothing was staged. Try again in a moment.`,
+  offline: () => `SharePoint could not be reached. Your work and the last known state are untouched.`,
+  conditional_write_unsupported: (slug, message) => message,
+  origin_not_allowed: (slug, message) => message,
+  rebind_required: (slug, message) => message,
+  ownership_lost: (slug, message) => message,
+  generation_moved: (slug, message) => message,
+};
+
+async function guarded(deckDir, fn, stop = fail) {
+  try {
+    return await fn();
+  } catch (err) {
+    const render = TYPED[err?.code];
+    if (render) stop(render(deckSlug(deckDir), err.message), 2, err.code);
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// open
+// ---------------------------------------------------------------------------
+
+// --json is read by an agent, so it carries what the next command needs and
+// nothing it can read from disk: the full receipt and operation journal live
+// under state/receipts and state/operations.
+const pick = (o, keys) => (o ? Object.fromEntries(keys.filter((k) => o[k] !== undefined).map((k) => [k, o[k]])) : o);
+const briefItem = (item) => pick(item, ["itemId", "driveId", "name", "webUrl", "eTag", "size", "lastModifiedDateTime"]);
+const briefRemote = (r) => pick(r, ["documentInstance", "itemId", "driveId", "name", "webUrl", "acceptedETag", "lastPulledAt", "access", "capabilities"]);
+function briefPublish(result) {
+  return {
+    ...pick(result, ["status", "reason", "why", "message", "blockers", "staged", "pendingRefs", "callbackFailed", "advanced"]),
+    // An unknown outcome is only actionable with the recovery verdicts that produced it.
+    ...(result.recovered?.length ? { recovered: result.recovered.map((r) => pick(r, ["operationId", "action", "why"])) } : {}),
+    ...(result.receipt ? { route: result.receipt.route, item: briefItem(result.receipt.item), version: result.receipt.version, candidateId: result.receipt.candidateId } : {}),
+    ...(result.operation ? { operationId: result.operation.operationId } : {}),
+    ...(result.handoff ? { handoff: result.handoff.dir } : {}),
+    ...(result.destination === 'saved' ? { destination: true } : {}),
+  };
+}
+
+export async function cmdOpen(rest) {
+  let target = null;
+  let deck = null;
+  let rebind = false;
+  let detach = false;
+  let keep = false;
+  let slides = null;
+  let asJson = false;
+  let ordinary = false;
+  const companionInputs = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--deck") deck = rest[++i] ?? null;
+    else if (a === "--rebind") rebind = true;
+    else if (a === "--detach") detach = true;
+    else if (a === "--keep") keep = true;
+    else if (a === "--slides") slides = rest[++i] ?? null;
+    else if (a === "--ordinary") ordinary = true;
+    else if (a === "--companion") companionInputs.push(rest[++i]);
+    else if (a === "--json") asJson = true;
+    else if (a.startsWith("-")) fail(`unknown flag: ${a}`);
+    else if (!target) target = a;
+    else fail(`unexpected argument: ${a}`);
+  }
+  if (!target) {
+    fail(
+      `usage: slidemind open <link|file.pptx> --deck <name> [--slides 2,7|all] [--rebind|--keep|--detach]`,
+    );
+  }
+
+  const local = /^[a-zA-Z]:[\\/]|^[./~]|^\\\\/.test(target) || fs.existsSync(target);
+  const slug = deck ?? path.basename(String(target).split(/[?#]/)[0], ".pptx") ?? "deck";
+  const deckRootPath = resolveDeckRoot(slug);
+  fs.mkdirSync(path.join(deckRootPath, ".slidemind"), { recursive: true });
+  let deckDir = resolveDeckArg(slug, { allowUnfinished: true });
+  const activeDir = deckDir;
+  const held = acquireOwner(activeDir, { command: 'open' });
+  const existing = readRemote(activeDir);
+  const previousBase = readRevision(activeDir)?.base?.sha256;
+  const tx = stageWorkspace(activeDir);
+  deckDir = tx.workspace;
+  try {
+
+  if (local) {
+    // A local file says nothing about where a deck should publish. An existing
+    // binding is therefore a question for the user, never an assumption: keeping
+    // it, detaching it, and pointing it somewhere else are three different
+    // intentions and only they know which one this is.
+    if (existing && !keep && !detach) {
+      fail(
+        `${slug} publishes to ${existing.name ?? existing.documentInstance}, and a local file does not ` +
+          `say whether that should stay true. Pass --keep to adopt these bytes and keep publishing there, ` +
+          `or --detach to make this a local-only deck.`,
+        2,
+      );
+    }
+    if (existing && detach) detachRemote(deckDir);
+    const result = await adoptLocal(deckDir, target, { slides });
+    const context = contextOfBytes(fs.readFileSync(target));
+    if (ordinary) classifyOrdinary(deckDir, context);
+    if (context?.context) {
+      const companions = Object.fromEntries(companionInputs.map(value => {
+        const split = value?.indexOf('=') ?? -1;
+        if (split < 1) fail('--companion must be artifactId=/path/to/file');
+        return [value.slice(0, split), fs.readFileSync(path.resolve(value.slice(split + 1)))];
+      }));
+      const restored = await hydrateContext(deckDir, { context, companions, note, provider: {}, client: null });
+      if (restored.blockers.length) fail(restored.blockers.map(b => b.message).join('\n'), 2);
+    }
+    tx.activate();
+    if (asJson) return json({ deck: slug, mode: result.mode, remote: briefRemote(readRemote(deckDir)) });
+    process.stdout.write(
+      `${slug}: ${result.mode} from ${path.basename(target)}` +
+        (existing && keep ? ` (still publishing to ${existing.name})` : "") +
+        (existing && detach ? ` (detached — local only now)` : "") +
+        `\n`,
+    );
+    return;
+  }
+
+  const { provider, client, caps } = await remoteSession();
+  const item = await guarded(deckDir, () => provider.resolveLink(client, target));
+  const tenant = new URL(client.host).hostname;
+  const instance = documentInstance({
+    provider: "sharepoint",
+    tenant,
+    driveId: item.driveId,
+    itemId: item.itemId,
+  });
+  if (existing && existing.documentInstance !== instance && !rebind) {
+    // Dirty work is never in danger here: nothing has been written yet.
+    const status = revisionStatus(deckDir);
+    fail(
+      `${slug} is bound to ${existing.name ?? existing.documentInstance}; that link resolves to a ` +
+        `different item. Pass --rebind to point this deck at it` +
+        (status.localDirty
+          ? ` (${status.dirtySlides.length} slide(s) carry unpublished edits — they are kept either way)`
+          : "") +
+        `, or open the link into a new deck with --deck <other-name>.`,
+      2,
+    );
+  }
+
+  const snapshot = await guarded(deckDir, () =>
+    provider.downloadSnapshot(client, { driveId: item.driveId, itemId: item.itemId }),
+  );
+  const context = contextOfBytes(snapshot.bytes);
+  const identity = classifyInstance({
+    context,
+    resolved: { ...item, tenant },
+    remote: existing,
+  });
+
+  const tmp = path.join(
+    fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-open-")),
+    item.name || `${slug}.pptx`,
+  );
+  fs.writeFileSync(tmp, snapshot.bytes);
+  let adopted;
+  try {
+    adopted = await adoptLocal(deckDir, tmp, { slides });
+  } finally {
+    fs.rmSync(path.dirname(tmp), { recursive: true, force: true });
+  }
+
+  bindRemote(deckDir, {
+    identity: { provider: "sharepoint", tenant, driveId: item.driveId, itemId: item.itemId },
+    labels: { name: item.name, webUrl: item.webUrl, parentId: item.parentId },
+    rebind,
+    acceptedETag: snapshot.revision?.eTag ?? item.eTag,
+    acceptedCTag: snapshot.revision?.cTag ?? item.cTag,
+    acceptedSha256: snapshot.sha256,
+    observedRevision: {
+      eTag: item.eTag,
+      cTag: item.cTag,
+      size: item.size,
+      lastModifiedDateTime: item.lastModifiedDateTime,
+    },
+    lastPulledAt: new Date().toISOString(),
+    // The read just succeeded, so read access is EVIDENCE. Write access stays
+    // unknown on purpose: the only honest way to learn it is the publish the
+    // user actually asks for, never a surprise probe against their library.
+    access: { read: "allowed", write: "unknown" },
+    // Cached so `ready` can report the mode from disk instead of turning every
+    // session start into a SharePoint round trip.
+    capabilities: caps.routes,
+    // A copy does not inherit authority over the original's shared inputs. This
+    // is the default and it is never flipped by metadata — only by the user.
+    sharedWorkbookAuthority: false,
+    ...(identity.kind === "fork"
+      ? { forkedFrom: context?.context?.documentInstance ?? null, deckId: instance }
+      : { deckId: context?.context?.deckId ?? instance }),
+    extensions: context?.context?.extensions ?? existing?.extensions ?? [],
+    committedRefs: context?.context?.extensions?.flatMap((e) => e.refs ?? []) ?? existing?.committedRefs ?? [],
+  });
+
+  const lines = [
+    `${slug}: ${adopted.mode} from ${item.name} (${snapshot.bytes.length} bytes)`,
+  ];
+  if (identity.kind === "fork") {
+    lines.push(
+      `  this is a COPY — it was published from a different item, so its logical identity was reminted ` +
+        `and its mutable context will fork on the first change rather than touch the original's.`,
+    );
+  }
+  if (identity.kind === "unknown") {
+    lines.push(
+      `  this file carries no slidemind context and nothing local describes it, so its origin is UNKNOWN. ` +
+        `Inspect and edit freely; a managed publish needs either recovered context or an explicit ` +
+        `\`--ordinary\` classification.`,
+    );
+    writeRemote(deckDir, { ...readRemote(deckDir), originUnknown: true });
+  }
+  if (context?.corrupt) {
+    lines.push(`  its context tag is present but unreadable (${context.corrupt}) — gates are NOT dropped.`);
+  }
+  if (ordinary) classifyOrdinary(deckDir, context);
+  if (context?.context) {
+    const companions = {};
+    for (const value of companionInputs) {
+      const split = value?.indexOf('=') ?? -1;
+      if (split < 1) fail('--companion must be artifactId=<file-or-link>');
+      const id = value.slice(0, split), location = value.slice(split + 1);
+      if (fs.existsSync(location)) companions[id] = fs.readFileSync(location);
+      else { const item = await provider.resolveLink(client, location); companions[id] = (await provider.downloadSnapshot(client, { driveId: item.driveId, itemId: item.itemId })).bytes; }
+    }
+    const { declarations } = declaredExtensions(deckDir, context);
+    const hydrated = await hydrateContext(deckDir, { provider, client, context, note, companions });
+    if (hydrated.blockers.length) fail(hydrated.blockers.map(b => b.message).join("\n"), 2);
+    if (declarations.length) {
+      lines.push(
+        `  extensions: ${declarations.map((d) => d.id).join(", ")}` +
+          (hydrated.written.length ? ` — restored ${hydrated.written.length} artifact(s)` : ""),
+      );
+    }
+    if (hydrated.slides.length) {
+      lines.push(`  it asks for slides ${hydrated.slides.join(", ")} to be editable: \`slidemind open <link> --deck ${slug} --slides ${hydrated.slides.join(",")}\``);
+    }
+  }
+  if (previousBase && previousBase !== snapshot.sha256) {
+    if ((existing?.extensions ?? []).some(e => e.required !== false && !(context?.context?.extensions ?? []).some(c => c.id === e.id))) fail('The incoming copy lost required context; the active deck is unchanged.', 2);
+    const { declarations } = declaredExtensions(deckDir, context);
+    const assessed = runDeclared(deckDir, declarations, 'assess', { revision: revisionStatus(deckDir), dependencies: context?.context?.extensions?.flatMap(e => e.refs ?? []) ?? [], context: context?.context ?? null });
+    if (assessed.blockers.length) fail(assessed.blockers.map(b => b.message).join('\n'), 2);
+  }
+  tx.activate();
+  if (asJson) {
+    return json({ deck: slug, mode: adopted.mode, identity, remote: briefRemote(readRemote(deckDir)) });
+  }
+  process.stdout.write(`${lines.join("\n")}\n`);
+  } finally { tx.dispose(); held.release(); }
+}
+
+// Adoption itself is the existing route, unchanged: `open` adds identity and
+// context to it, it does not reimplement what `adopt` already does safely.
+async function adoptLocal(deckDir, file, { slides }) {
+  const { adoptWorkspace } = await import("../lib/adopt.mjs");
+  const selection =
+    slides === "all"
+      ? null
+      : slides
+        ? slides.split(",").flatMap((part) => {
+            const range = part.match(/^(\d+)-(\d+)$/);
+            if (!range) return [Number(part)];
+            const out = [];
+            for (let n = Number(range[1]); n <= Number(range[2]); n++) out.push(n);
+            return out;
+          })
+        : null;
+  try {
+    return await withOwner(deckDir, "open", (owner) =>
+      adoptWorkspace({
+        pptxPath: file,
+        deckDir,
+        slides: slides === "all" ? "all" : selection,
+        note,
+        owner,
+      }),
+    );
+  } catch (err) {
+    if (err?.code === "needs_reconcile") fail(err.message, 2);
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// pull
+// ---------------------------------------------------------------------------
+
+export async function cmdPull(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "pull");
+  const asJson = passthrough.includes("--json");
+  const checkOnly = passthrough.includes("--check");
+  for (const a of passthrough) {
+    if (!["--json", "--check"].includes(a)) fail(`unknown flag: ${a}`);
+  }
+  const deckDir = resolveDeckArg(deck, { allowUnfinished: true });
+  requireBound(deckDir);
+  const { provider, client } = await remoteSession();
+
+  if (checkOnly) {
+    // Metadata only, by construction: ten of these download nothing.
+    const freshness = await guarded(deckDir, () => checkFreshness(deckDir, { provider, client }));
+    if (asJson) return json({ ...freshness, item: briefItem(freshness.item) });
+    process.stdout.write(
+      `${deckSlug(deckDir)}: ${freshness.changed ? "the remote copy has changed" : "current"}` +
+        (freshness.renameOnly ? ` (renamed to ${freshness.item.name})` : "") +
+        (freshness.dependencyChanges.length
+          ? `\n  ${freshness.dependencyChanges.length} linked input(s) changed: ` +
+            freshness.dependencyChanges.map((d) => d.ref.artifactId).join(", ")
+          : "") +
+        `\n  observed ${new Date().toISOString()}\n`,
+    );
+    return;
+  }
+
+  const result = await guarded(deckDir, () =>
+    withOwner(deckDir, "pull", async (owner) => {
+      await recoverOperations(deckDir, { provider, client, owner, note });
+      return pullDeck(deckDir, { provider, client, owner, note });
+    }),
+  );
+  if (asJson) return json({ ...result, item: briefItem(result.item) });
+  process.stdout.write(renderPull(deckDir, result));
+}
+
+// Why a staged save was NOT taken in, in the words the gate used. A conflict
+// is not one of these: it is listed slide by slide where it is rendered.
+function notTakenIn(pull) {
+  const reasons = [
+    ...(pull.blockers ?? []).map((b) => b.message),
+    ...(pull.assessment?.blockers ?? []).map((b) => b.message),
+    ...(pull.stagedContext ?? [])
+      .filter((a) => a.error)
+      .map((a) => `the exact '${a.artifactId}' their save pins could not be read (${a.error})`),
+  ];
+  if (!reasons.length && pull.reason === "artifact_missing") {
+    reasons.push("their save does not carry the business context this deck requires");
+  }
+  return (
+    reasons.map((r) => `  - ${r}\n`).join("") +
+    `  This is not a conflict to merge: pulling or publishing again stops here too until it is fixed.\n`
+  );
+}
+
+export function renderPull(deckDir, result) {
+  const slug = deckSlug(deckDir);
+  if (result.status === "current") {
+    return (
+      `${slug}: current — nothing was downloaded.\n` +
+      (result.dependencyChanges.length
+        ? `  but ${result.dependencyChanges.length} linked input(s) changed: ` +
+          `${result.dependencyChanges.map((d) => d.ref.artifactId).join(", ")}\n` +
+          `  that is an incoming business change; the deck's approved pairing is unchanged.\n`
+        : "")
+    );
+  }
+  if (result.status === "renamed") {
+    return `${slug}: renamed to ${result.item.name} — same item, same content, nothing re-hydrated.\n`;
+  }
+  if (result.status === "staged") {
+    if (result.conflicts?.length) {
+      return (
+        `${slug}: a newer save is on SharePoint and ${result.conflicts.length} slide(s) changed on BOTH sides, ` +
+        `so it was STAGED as ${result.staged.revisionId}. Nothing local was touched.\n` +
+        result.conflicts.map((c) => `  [${c.id}] ${c.kind}${c.file ? ` ${c.file}` : ""} — ${c.detail}\n`).join("") +
+        `  Decide them: slidemind rebase ${slug} --incoming ${result.staged.revisionId}\n`
+      );
+    }
+    return (
+      `${slug}: a newer save is on SharePoint; it was STAGED as ${result.staged.revisionId} but not taken in ` +
+      `(${result.reason}). Nothing local was touched.\n` +
+      notTakenIn(result)
+    );
+  }
+  const assessment = result.assessment?.blockers ?? [];
+  return (
+    `${slug}: merged their save ${result.staged.revisionId} (generation ${result.rebase.generation}).\n` +
+    `  from their save: ${result.rebase.refreshed.length} slide(s) changed or added, ` +
+    `${result.rebase.removed.length} removed; your unpublished slide(s) kept: ${result.rebase.stillDirty.length}\n` +
+    (result.rebase.notes ?? []).map((n) => `  note: ${n}\n`).join("") +
+    (assessment.length
+      ? `  business assessment blocks publication: ${assessment.map((b) => b.message).join("; ")}\n`
+      : "")
+  );
+}
+
+// ---------------------------------------------------------------------------
+// publish
+// ---------------------------------------------------------------------------
+
+export async function cmdPublish(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "publish");
+  let candidateId = null;
+  let asJson = false;
+  let manual = false;
+  let sharedWorkbook = false;
+  let folder = null, name = null;
+  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 if (a === "--manual") manual = true;
+    else if (a === "--folder") folder = passthrough[++i] ?? null;
+    else if (a === "--name") name = passthrough[++i] ?? null;
+    else if (a === "--shared-workbook") sharedWorkbook = true;
+    else fail(`unknown flag: ${a}`);
+  }
+  const deckDir = resolveDeckArg(deck, { allowUnfinished: true });
+  if (Boolean(folder) !== Boolean(name)) fail('--folder and --name must be supplied together.');
+  if (name && (!/\.pptx$/i.test(name) || /[\\/]/.test(name))) fail('--name must be a plain .pptx filename.');
+  let result;
+  try {
+    result = await runPublish(deckDir, { candidateId, manual, folder, name, sharedWorkbook });
+  } catch (err) {
+    if (!(err instanceof PublishStop)) throw err;
+    // --json still answers with one document: the typed reason, message on stderr too
+    if (asJson) json(stoppedJson(err));
+    fail(err.message, err.exitCode);
+  }
+  if (asJson) return json(briefPublish(result));
+  process.stdout.write(renderPublish(deckDir, result));
+  if (UNSAVED.includes(result.status)) process.exit(2);
+}
+
+// The outcomes that leave the deck NOT saved to SharePoint — exit 2, built-or-not.
+const UNSAVED = ["blocked", "needs_reconcile", "unknown"];
+
+// A publish that stops before the protocol runs: no session, writes switched
+// off, a busy deck, a typed refusal. `slidemind publish` prints it and exits;
+// a build that publishes itself reports it next to the build that DID happen.
+class PublishStop extends Error {
+  constructor(message, exitCode = 1, reason = "stopped") {
+    super(message);
+    this.exitCode = exitCode;
+    this.reason = reason;
+  }
+}
+const stopPublish = (message, exitCode = 1, reason = "stopped") => {
+  throw new PublishStop(message, exitCode, reason);
+};
+// What a stop is in a --json payload: no protocol result, a typed reason.
+const stoppedJson = (err) => ({ status: "not_published", reason: err.reason, message: err.message });
+
+/**
+ * Everything `slidemind publish` does once its arguments are read: the target
+ * (the binding, explicit --folder/--name, else the folder the workspace saved),
+ * the standing approval, the session, ownership and the protocol itself. Never
+ * exits — a refusal throws a PublishStop — so the command and the build that
+ * publishes itself run the one implementation and every one of its gates.
+ */
+async function runPublish(deckDir, { candidateId = null, manual = false, folder = null, name = null, sharedWorkbook = false } = {}) {
+  // No flags and no binding: the workspace's saved folder (destination.json)
+  // supplies the target, on the backend it was chosen against. The lib reads
+  // the same file, so the CLI only decides whether "not bound" is an error.
+  const saved = !folder && !readRemote(deckDir) ? savedDestination(deckDir) : null;
+  if (!folder && !saved) requireBound(deckDir, stopPublish);
+  if (saved?.backendURL && !process.env.SLIDEMIND_BACKEND?.trim()) process.env.SLIDEMIND_BACKEND = saved.backendURL;
+  if (!readRevision(deckDir)) {
+    stopPublish(
+      `${deckSlug(deckDir)} has no accepted base, so there is nothing to publish AGAINST. ` +
+        `Open it from its link first: slidemind open <link> --deck ${deckSlug(deckDir)}`,
+      1,
+      "no_base",
+    );
+  }
+  // The standing approval, checked here rather than inferred. It is one-time per
+  // deck and `build-pptx` already enforces it, so this cannot prompt a second
+  // time — it only refuses to publish a deck whose preview nobody ever approved.
+  const unapproved = (await import("../builders/review.mjs")).requireReviewApproved(deckDir);
+  if (unapproved) stopPublish(unapproved, 1, "review_required");
+  const { provider, client } = await remoteSession({ needWrite: !manual, stop: stopPublish });
+  const folderItem = folder ? await provider.resolveLink(client, folder) : null;
+  const destination = folderItem ? { driveId: folderItem.driveId, parentId: folderItem.itemId, name } : null;
+
+  return guarded(
+    deckDir,
+    () =>
+      withOwner(
+        deckDir,
+        "publish",
+        (owner) =>
+          publishDeck(deckDir, {
+            provider,
+            client,
+            owner,
+            candidateId,
+            manual,
+            destination,
+            sharedWorkbookAuthority: sharedWorkbook,
+            note,
+            onProgress: ({ uploaded, total }) =>
+              process.stderr.write(`  uploading ${Math.round((uploaded / total) * 100)}%\r`),
+          }),
+        stopPublish,
+      ),
+    stopPublish,
+  );
+}
+
+/**
+ * The publish a build owes a deck connected to SharePoint: the file it was
+ * opened from (state/remote.json) or a folder the user connected in the
+ * workspace (state/destination.json). Read from the deck's own state at every
+ * build, so a folder connected while an agent is mid-deck is honoured by the
+ * very next build — nobody has to remember it. Null for a deck connected to
+ * nothing.
+ *
+ * Never exits and never throws: the build already happened, so a publish that
+ * did not save is REPORTED next to it — `text` for stderr, `json` for the
+ * build's payload — with exit code 2 (built, not on SharePoint). A build that
+ * withholds its own bytes (`withheld`) is reported without an attempt.
+ */
+export async function publishAfterBuild(deckDir, { candidateId = null, withheld = null } = {}) {
+  let connected;
+  try {
+    connected = Boolean(readRemote(deckDir) || savedDestination(deckDir));
+  } catch {
+    // an unfinished activation on a bound deck: publish's own recovery speaks to it
+    connected = true;
+  }
+  if (!connected) return null;
+  // The build itself said it is not ready (`withheld: { reason, message }`):
+  // named, not attempted — and not a second failure on top of the build's own.
+  if (withheld) {
+    return {
+      json: { status: "not_published", reason: withheld.reason, message: withheld.message },
+      text: `${deckSlug(deckDir)}: built, but not published to SharePoint — ${withheld.message}\n`,
+      exitCode: 0,
+    };
+  }
+  try {
+    const result = await runPublish(deckDir, { candidateId });
+    return { json: briefPublish(result), text: renderPublish(deckDir, result), exitCode: UNSAVED.includes(result.status) ? 2 : 0 };
+  } catch (err) {
+    const message = err?.message ?? String(err);
+    return {
+      json: err instanceof PublishStop ? stoppedJson(err) : { status: "not_published", reason: err?.code ?? "error", message },
+      text: `${deckSlug(deckDir)}: built, but not published to SharePoint — ${message}\n`,
+      exitCode: 2,
+    };
+  }
+}
+
+export function renderPublish(deckDir, result) {
+  const slug = deckSlug(deckDir);
+  switch (result.status) {
+    case "committed":
+      return (
+        // The replace response carries no version number, only the new eTag;
+        // its trailing ",N" is the revision SharePoint's history counts by.
+        `${slug}: SAVED to SharePoint as ${
+          result.receipt.version?.versionId
+            ? `version ${result.receipt.version.versionId}`
+            : `revision ${result.receipt.version?.eTag?.match(/,(\d+)"?$/)?.[1] ?? "(unnumbered)"}`
+        }.\n` +
+        `  ${result.receipt.item?.name ?? ""} · ${result.receipt.route}\n` +
+        (result.callbackFailed
+          ? `  local finalization is still pending — re-run publish to retry the callback (not the upload).\n`
+          : "")
+      );
+    case "needs_reconcile":
+      if (result.reason === "merged") {
+        const rebase = result.pull.rebase;
+        return (
+          `${slug}: somebody else saved first, so nothing was overwritten — their save is merged in ` +
+          `(${rebase.refreshed.length} slide(s) changed or added, ${rebase.removed.length} removed; ` +
+          `your ${rebase.stillDirty.length} unpublished slide(s) kept).\n` +
+          (rebase.notes ?? []).map((n) => `  note: ${n}\n`).join("") +
+          `  Rebuild: slidemind build-pptx ${slug} — it publishes again.\n`
+        );
+      }
+      if (result.dependencies) {
+        return (
+          `${slug}: a linked input changed since this deck was paired with it, so nothing was published.\n` +
+          result.dependencies
+            .filter((d) => d.changed || d.unreadable)
+            .map((d) => `  - ${d.ref?.artifactId ?? "input"}: ${d.unreadable ? `unreadable (${d.error})` : "changed"}\n`)
+            .join("") +
+          `  Run \`slidemind pull ${slug}\` and try again.\n`
+        );
+      }
+      return (
+        `${slug}: somebody else saved first, so nothing was overwritten.\n` +
+        (result.pull?.conflicts?.length
+          ? result.pull.conflicts.map((c) => `  [${c.id}] ${c.kind}${c.file ? ` ${c.file}` : ""} — ${c.detail}\n`).join("") +
+            `  Decide them: slidemind rebase ${slug} --incoming ${result.staged.revisionId}\n`
+          : result.pull?.status === "staged"
+            ? `  Their save is STAGED as ${result.staged.revisionId} but could not be taken in (${result.pull.reason}).\n` +
+              notTakenIn(result.pull)
+            : `  Run \`slidemind pull ${slug}\` (it merges their save), then rebuild — \`slidemind build-pptx ${slug}\` publishes again.\n`) +
+        (result.pendingRefs?.length
+          ? `  ${result.pendingRefs.length} uploaded artifact(s) stay PENDING — the stored deck still ` +
+            `points at the context it was approved with.\n`
+          : "")
+      );
+    case "manual":
+      return (
+        `${slug}: prepared for manual upload — nothing was written to SharePoint (${result.reason}).\n` +
+        `  ${result.handoff.dir}\n` +
+        `  status: pendingManualUpload. Upload the files it lists, then \`slidemind pull ${slug}\`.\n`
+      );
+    case "unknown":
+      return (
+        `${slug}: the outcome of this write is UNKNOWN (${result.why}).\n` +
+        `  Nothing will be re-uploaded. Re-run \`slidemind publish ${slug}\` — it inspects first.\n`
+      );
+    default:
+      return (
+        `${slug}: not published (${result.reason}).\n` +
+        (result.message ? `  ${result.message}\n` : "") +
+        (result.blockers ?? []).map((b) => `  - ${b.message}\n`).join("")
+      );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// rename
+// ---------------------------------------------------------------------------
+
+export async function cmdRename(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "rename");
+  let name = null;
+  let asJson = false;
+  for (let i = 0; i < passthrough.length; i++) {
+    const a = passthrough[i];
+    if (a === "--name") name = passthrough[++i] ?? null;
+    else if (a === "--json") asJson = true;
+    else fail(`unknown flag: ${a}`);
+  }
+  if (!name) fail(`usage: slidemind rename <deck> --name <file.pptx>`);
+  if (name.includes("/") || name.includes("\\")) {
+    fail("a rename changes the file's NAME; moving it to another folder needs an explicit rebind.");
+  }
+  const deckDir = resolveDeckArg(deck, { allowUnfinished: true });
+  requireBound(deckDir);
+  const { provider, client } = await remoteSession({ needWrite: true });
+  const result = await guarded(deckDir, () =>
+    withOwner(deckDir, "rename", () => renameBound(deckDir, { provider, client, name, note })),
+  );
+  if (asJson) return json(result);
+  if (result.status === "committed") {
+    process.stdout.write(`${deckSlug(deckDir)}: renamed to ${result.name} — same item, nothing rendered.\n`);
+    return;
+  }
+  process.stdout.write(
+    `${deckSlug(deckDir)}: not renamed (${result.reason})` +
+      (result.reason === "name_conflict" ? ` — '${name}' already exists there.` : "") +
+      `\n`,
+  );
+  process.exit(2);
+}
+
+export { remoteReadiness } from "../lib/remote.mjs";