slidemind 0.3.19 → 0.4.0

package/src/cli/maintenance.mjs

@@ -0,0 +1,104 @@
+// `slidemind clean <deck>` — the one command that operates on the deck DIRECTORY
+// rather than on its contents. It removes only what a build reproduces: preview/
+// and abandoned downloads. Concepts cost a model call, gate state is a human
+// decision, and a journal is the only record of an operation in flight, so all
+// three stay.
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { deckSlug, previewPath } from "../lib/deck-paths.mjs";
+import { fail, resolveDeckRoot, resolveWorkspace, splitDeckArg, SRC_DIR } from "./common.mjs";
+
+function rel(p) {
+  const r = path.relative(process.cwd(), p);
+  return r.startsWith("..") ? p : r;
+}
+
+function posix(p) {
+  return p.split(path.sep).join("/");
+}
+
+// ---------------------------------------------------------------------------
+// clean
+// ---------------------------------------------------------------------------
+
+// A `.part` still being written is an engine download in flight, not an
+// abandoned one. ponytail: mtime heuristic — exact would need a lock file, and
+// nothing writes one today.
+const ACTIVE_PART_MS = 2 * 60 * 1000;
+
+function partDownloads(dir) {
+  const out = [];
+  const walk = (d) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith(".part")) out.push(p);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+export async function cmdClean(rest) {
+  const { deck } = splitDeckArg(rest, "clean");
+  const root = resolveDeckRoot(deck);
+  if (!root || !fs.existsSync(root)) fail(`deck '${deck}' not found`);
+  const workspace = resolveWorkspace(root);
+
+  const removed = [];
+  const kept = [];
+
+  for (const dir of [
+    previewPath(workspace),
+    path.join(workspace, ".draft-preview"),
+    path.join(workspace, ".build-preview"),
+  ]) {
+    if (!fs.existsSync(dir)) continue;
+    fs.rmSync(dir, { recursive: true, force: true });
+    removed.push(dir);
+  }
+
+  // The revision protocol's state is NEVER cleanable. A candidate is the only
+  // copy of a build nobody has accepted yet, `base.pptx` is the only record of
+  // what the deck was adopted from, and a journal is the only way an interrupted
+  // operation resolves — none of the three is something a build reproduces.
+  const { PROTECTED_STATE } = await import(
+    pathToFileURL(path.join(SRC_DIR, "lib", "revision.mjs")).href
+  );
+  for (const name of PROTECTED_STATE) {
+    if (fs.existsSync(path.join(workspace, "state", name))) kept.push(`state/${name}`);
+  }
+
+  const now = Date.now();
+  for (const part of partDownloads(path.join(workspace, "assets"))) {
+    if (now - fs.statSync(part).mtimeMs < ACTIVE_PART_MS) {
+      kept.push(`${posix(path.relative(workspace, part))} (still downloading)`);
+      continue;
+    }
+    fs.rmSync(part, { force: true });
+    removed.push(part);
+  }
+
+  const keptLines = kept.map((k) => `  kept    ${k}\n`).join("");
+  if (removed.length === 0) {
+    process.stdout.write(`Nothing to clean in ${rel(workspace)}\n${keptLines}`);
+    return;
+  }
+  process.stdout.write(
+    `Cleaned ${rel(workspace)}:\n` +
+      removed.map((p) => `  removed ${rel(p)}\n`).join("") +
+      keptLines +
+      `Slides, assets, conversions, state (the accepted base, candidates and journals ` +
+      `included) and concepts are untouched; ` +
+      `\`slidemind view-draft ${deckSlug(workspace)}\` regenerates the previews.\n`,
+  );
+}

package/src/cli/read.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { fail, LOCAL_PPTX_RE, SRC_DIR } from "./common.mjs";
+import { resolveWorkspace, writeStateFile } from "../lib/deck-paths.mjs";
 
 // Print a read result — the `{ ok, mode, slideCount, slides[] }` shape, whether
 // it came from the add-in (open presentation) or a local .pptx. Shared by both
@@ -134,5 +135,5 @@ export function saveLayoutContext(deck, result, target) {
    if (slide.layout && !slide.hidden) counts.set(slide.layout, (counts.get(slide.layout) || 0) + 1);
    return counts;
   }, new Map())) };
- fs.writeFileSync(path.join(deckDir, ".layout-context.json"), JSON.stringify(context, null, 2) + "\n");
+ writeStateFile(resolveWorkspace(deckDir), "layout-context.json", JSON.stringify(context, null, 2) + "\n");
 }

package/src/cli/ready.mjs

@@ -7,6 +7,7 @@ import { publicConnectionStatus, backendBlocker, connectionBlocker } from "./con
 import { readDesignName, cachedDesigns, designRows, designsHumanLines, windowsHumanLine } from "./designs.mjs";
 import { runDiagnose } from "./diagnose.mjs";
 import { deckStage, stageHumanLines } from "./status.mjs";
+import { deckSlug as slugOf } from "../lib/deck-paths.mjs";
 
 // The one-command agent preflight. Collapses the old 4-call session start
 // (list windows → pick → download-bundle → download-bundle-to-bind) into a
@@ -78,7 +79,7 @@ export async function cmdReady(rest) {
         `deck '${deckArg}' not found — run \`slidemind ready\` (no deck) to set up, then \`slidemind new ${deckArg}\``,
       );
     }
-    deckSlug = path.basename(deckDir);
+    deckSlug = slugOf(deckDir);
     deckPresFP = bundle.readDeckBundleRef(deckDir)?.presFP ?? null;
   }
 
@@ -161,7 +162,7 @@ export async function cmdReady(rest) {
           backends: statusRaw.backends,
         });
       } catch {
-        engineInfo = { available: false, envs: [] };
+        engineInfo = { available: false, envs: [], unknown: [] };
       }
     }
     return engineInfo;
@@ -329,7 +330,9 @@ export async function cmdReady(rest) {
     const nextAction = noWindow
       ? eng.available
         ? "Ready (no PowerPoint window — authoring, engine search and build-pptx all work; only push/insert-slide and reading an open presentation need one)."
-        : "Ready (no PowerPoint window — build-pptx/build/review/view-draft work; push/search/read need a pane)."
+        : eng.unknown?.length
+          ? `Ready (no PowerPoint window — authoring and build-pptx work; whether engine search runs off the connection could not be checked [${eng.unknown.join(", ")}]: the capability probe got no answer, and a search retries it).`
+          : "Ready (no PowerPoint window — build-pptx/build/review/view-draft work; push/search/read need a pane)."
       : paneReady
         ? "Ready (design resolved without targeting a window; a registered PowerPoint window is available for push/insert-slide)."
         : eng.available

package/src/cli/record.mjs

@@ -0,0 +1,522 @@
+// `slidemind record create | open | sync | status` — one JSON file shared
+// through the backend's record service.
+//
+// Deliberately content-blind: the CLI sends a JSON file, stores what came
+// back, and reports what the service says changed under it. It never validates
+// the document, never merges it, and never learns what its fields mean.
+//
+// This is the thin entry point: the network lives in src/lib/record-client.mjs,
+// the binding in src/lib/record-state.mjs, and a response is written back
+// ONLY by the explicit apply step here — never inside the request.
+
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+
+import { deckSlug, fail, resolveDeckArg, resolveDeckRoot } from "./common.mjs";
+import { WORKSPACE_DIRNAME } from "../lib/deck-paths.mjs";
+import {
+  REFUSALS,
+  createRecord,
+  getRecord,
+  putRecord,
+  recordSelector,
+  refusalCode,
+  resolveRecordBackend,
+} from "../lib/record-client.mjs";
+import {
+  applyRecordResponse,
+  conflictsPath,
+  pageLink,
+  planToSend,
+  readConflicts,
+  readRecordState,
+  recordStateFrom,
+  resolveStoredFile,
+  writeConflicts,
+  writeRecordFile,
+  writeRecordState,
+} from "../lib/record-state.mjs";
+
+const USAGE =
+  "usage: slidemind record create <deck> --folder <link> --name <file.json> --file <path> [--kind <kind>]\n" +
+  "       slidemind record open   <link> --deck <slug> --file <path>\n" +
+  "       slidemind record sync   <deck> --file <path> [--approval] [--resolve <file>]\n" +
+  "       slidemind record status <deck>\n" +
+  "       (every subcommand takes --json)";
+
+const emit = (data) => process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+
+function readJsonFile(file, what) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    fail(`${what} not found: ${file}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    fail(`${what} is not valid JSON (${file}): ${err.message}`);
+  }
+}
+
+function readJsonOrNull(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function backendFor(binding) {
+  try {
+    return await resolveRecordBackend(binding);
+  } catch (err) {
+    fail(err.message);
+  }
+}
+
+function failCall(err, asJson) {
+  const code = refusalCode(err);
+  if (!code) throw err;
+  if (asJson) {
+    emit({ ok: false, error: code, message: REFUSALS[code] });
+    process.exit(1);
+  }
+  fail(`${code} — ${REFUSALS[code]}`);
+}
+
+function requireState(deckDir, slug) {
+  const state = readRecordState(deckDir);
+  if (!state?.url) {
+    fail(
+      `${slug} has no shared record. Create one with \`slidemind record create ${slug} ` +
+        "--folder <link> --name <file.json> --file <path>`, or open an existing one with " +
+        "`slidemind record open <link> --deck " +
+        `${slug} --file <path>\`.`,
+    );
+  }
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// arguments
+// ---------------------------------------------------------------------------
+
+function parseArgs(rest, sub) {
+  const args = {
+    target: null,
+    folder: null,
+    name: null,
+    file: null,
+    deck: null,
+    resolve: null,
+    approval: false,
+    json: false,
+  };
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--folder") args.folder = rest[++i] ?? null;
+    else if (a === "--name") args.name = rest[++i] ?? null;
+    else if (a === "--file") args.file = rest[++i] ?? null;
+    else if (a === "--deck") args.deck = rest[++i] ?? null;
+    else if (a === "--resolve") args.resolve = rest[++i] ?? null;
+    else if (a === "--kind") args.kind = rest[++i] ?? null;
+    else if (a === "--approval") args.approval = true;
+    else if (a === "--json") args.json = true;
+    else if (a.startsWith("-")) fail(`unknown flag: ${a}\n${USAGE}`);
+    else if (!args.target) args.target = a;
+    else fail(`unexpected argument: ${a}\n${USAGE}`);
+  }
+  if (!args.target) fail(`slidemind record ${sub} needs a ${sub === "open" ? "link" : "deck"}.\n${USAGE}`);
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+
+async function cmdCreate(rest) {
+  const args = parseArgs(rest, "create");
+  if (!args.folder || !args.name || !args.file) {
+    fail(`record create needs --folder, --name and --file.\n${USAGE}`);
+  }
+  const deckDir = resolveDeckArg(args.target);
+  const file = path.resolve(args.file);
+  const plan = readJsonFile(file, "the record");
+  const backendURL = await backendFor(readRecordState(deckDir));
+
+  let data;
+  try {
+    data = await createRecord(backendURL, { kind: args.kind ?? null, folderUrl: args.folder, name: args.name, plan });
+  } catch (err) {
+    failCall(err, args.json);
+  }
+  const link = pageLink(data);
+  // The local file is NOT rewritten: create shares what the caller wrote, and
+  // rewriting it here would make "share" look like an edit. `plan` as sent is
+  // the right base when the service echoes none: it is exactly the bytes it
+  // just stored.
+  writeRecordState(
+    deckDir,
+    recordStateFrom(
+      { ...data, name: data.name ?? args.name, plan: data.plan ?? plan },
+      { file, deckDir, link, backendURL },
+    ),
+  );
+  if (args.json) {
+    emit({
+      ok: true,
+      url: data.url,
+      name: data.name ?? args.name,
+      eTag: data.eTag ?? null,
+      versionLabel: data.versionLabel ?? null,
+      link,
+    });
+    return;
+  }
+  process.stdout.write(
+    `Shared ${data.name ?? args.name}${data.versionLabel ? ` (v${data.versionLabel})` : ""}.\n` +
+      `${link}\n`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// open
+// ---------------------------------------------------------------------------
+
+async function cmdOpenRecord(rest) {
+  const args = parseArgs(rest, "open");
+  if (!args.deck || !args.file) {
+    fail(`record open needs --deck and --file.\n${USAGE}`);
+  }
+  const backendURL = await backendFor(null);
+  let data;
+  try {
+    data = await getRecord(backendURL, { url: args.target }, { kind: args.kind ?? null });
+  } catch (err) {
+    failCall(err, args.json);
+  }
+  // The workspace may not exist yet — this is how a colleague's machine first
+  // hears about the deck at all.
+  const root = resolveDeckRoot(args.deck);
+  fs.mkdirSync(path.join(root, WORKSPACE_DIRNAME), { recursive: true });
+  const deckDir = resolveDeckArg(args.deck, { allowUnfinished: true });
+  const file = path.resolve(args.file);
+  writeRecordFile(file, data.plan);
+  const link = pageLink(data, args.target);
+  writeRecordState(deckDir, recordStateFrom(data, { file, deckDir, link, backendURL }));
+  if (args.json) {
+    emit({
+      ok: true,
+      url: data.url,
+      name: data.name ?? null,
+      eTag: data.eTag ?? null,
+      versionLabel: data.versionLabel ?? null,
+      link,
+      file,
+      deck: root,
+    });
+    return;
+  }
+  process.stdout.write(
+    `Wrote ${path.relative(process.cwd(), file)}${data.versionLabel ? ` (v${data.versionLabel})` : ""}.\n` +
+      `${link}\n`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// sync
+// ---------------------------------------------------------------------------
+
+const preview = (value) => {
+  const text = JSON.stringify(value ?? null);
+  return text.length > 120 ? `${text.slice(0, 117)}…` : text;
+};
+
+async function cmdSync(rest) {
+  const args = parseArgs(rest, "sync");
+  const sendFrom = args.resolve ? path.resolve(args.resolve) : args.file ? path.resolve(args.file) : null;
+  const writeTo = args.file ? path.resolve(args.file) : sendFrom;
+  if (!sendFrom) fail(`record sync needs --file (or --resolve <file>).\n${USAGE}`);
+
+  const deckDir = resolveDeckArg(args.target);
+  const slug = deckSlug(deckDir);
+  const state = requireState(deckDir, slug);
+  // A deck the workspace queue already manages drains through the shared
+  // coordinator: same claim as the daemon, so the two never both send.
+  if (!args.resolve && !args.approval && (await queuedSync(deckDir, state, writeTo, args.json))) return;
+  const mine = planToSend(readJsonFile(sendFrom, "the record"), { approval: args.approval });
+
+  let base;
+  if (args.resolve) {
+    const conflicts = readConflicts(deckDir);
+    if (!conflicts?.eTag) {
+      fail(
+        `${slug} has no conflicts to resolve (${path.relative(process.cwd(), conflictsPath(deckDir))} is missing). ` +
+          "Run `slidemind record sync` without --resolve.",
+      );
+    }
+    // Resolving means "against the version the conflicts came from", not
+    // against whatever this machine last loaded — and `current` is the ONLY
+    // field that is that version. `merged` is not a substitute: it carries
+    // MINE at every non-conflicting path, so sending it as the base would tell
+    // the next merge that my own edits were already in the shared record, and
+    // it would attribute them to everyone else.
+    if (!conflicts.current) {
+      fail(
+        `${slug}'s conflicts file carries no \`current\` — it predates this CLI. ` +
+          "Run `slidemind record sync` again to get a fresh conflict list, then resolve that one.",
+      );
+    }
+    base = { eTag: conflicts.eTag, plan: conflicts.current };
+  } else {
+    base = { eTag: state.eTag, plan: state.base ?? null };
+  }
+
+  const backendURL = await backendFor(state);
+  let data;
+  try {
+    data = await putRecord(backendURL, { kind: state.recordKind ?? null, selector: recordSelector(state), base, plan: mine });
+  } catch (err) {
+    if (err?.code === "conflict") return reportConflicts(deckDir, slug, err.body, args.json);
+    if (err?.code === "stale") return reportStale(err.body, args.json);
+    if (err?.code === "version_unknown") {
+      data = await recoverVersion(backendURL, state, args.json, err);
+    } else {
+      failCall(err, args.json);
+    }
+  }
+
+  // The explicit apply: the write landed, so the response is this deck's new
+  // base and whatever conflicts were pending are settled by it.
+  applyRecordResponse(deckDir, data, {
+    file: writeTo,
+    link: state.link ?? pageLink(data),
+    backendURL,
+    previous: state,
+  });
+
+  const applied = Array.isArray(data.applied) ? data.applied : [];
+  if (args.json) {
+    emit({
+      ok: true,
+      url: data.url ?? state.url,
+      eTag: data.eTag ?? null,
+      versionLabel: data.versionLabel ?? null,
+      applied,
+      file: writeTo,
+      ...(data.recovered ? { versionReadAfterWrite: true } : {}),
+    });
+    return;
+  }
+  process.stdout.write(
+    `synced v${data.versionLabel ?? data.eTag ?? "?"}` +
+      (data.recovered ? " (version read after write)" : "") +
+      "\n" +
+      (applied.length
+        ? `  ${applied.length} change(s) came back from the shared record:\n` +
+          applied.map((p) => `    ${p}\n`).join("")
+        : ""),
+  );
+}
+
+// synchronization.md: the headless drain of a deck whose plan is queued by
+// the workspace (state/workspace-sync.json exists and the plan is pack-owned).
+// Returns false when this deck is not queued, so the classic path runs.
+async function queuedSync(deckDir, state, writeTo, asJson) {
+  const { drainOnce, syncStatus } = await import("../workspace/sync.mjs");
+  if (!syncStatus(deckDir).exists) return false;
+  const { planPageOwner } = await import("../lib/deck-paths.mjs");
+  const owner = planPageOwner(deckDir).owner;
+  if (!owner || owner === "core") return false;
+  const { resolveWorkspaceAdapter } = await import("../workspace/adapters.mjs");
+  const adapter = resolveWorkspaceAdapter(owner === "extension" ? null : owner);
+  if (!adapter.entry) fail(`${adapter.blocker?.code ?? "extension_missing"} — ${adapter.blocker?.message ?? "the plan's extension is not installed"}`);
+  let result;
+  try {
+    // A CLI save may have changed the file since the queue became idle. Accept
+    // and enqueue that current value under the same lock as browser edits before
+    // draining; an idle queue is not evidence that the file is still synced.
+    const { savePlanLocal, readAcceptedEdit } = await import("../workspace/edit.mjs");
+    const { dispatchAdapter } = await import("../workspace/adapters.mjs");
+    const accepted = readAcceptedEdit(deckDir);
+    const current = await dispatchAdapter(adapter.entry, { method: "read", deckRoot: path.dirname(deckDir) });
+    if (current.status !== "ok") throw Object.assign(new Error(current.error?.message ?? "cannot read plan"), { code: current.error?.code });
+    const value = current.data.value;
+    const saved = await savePlanLocal({ workspaceDir: deckDir, adapter, base: { hash: current.data.hash, value }, value });
+    if (!saved.ok) throw Object.assign(new Error(saved.message ?? saved.code), { code: saved.code });
+    result = await drainOnce(deckDir, { adapter });
+  } catch (err) {
+    if (err?.code === "deck_busy" || err?.code === "recovery_required") {
+      if (asJson) {
+        emit({ ok: false, error: err.code, message: err.message });
+        process.exit(2);
+      }
+      fail(`${err.code} — ${err.message}`);
+    }
+    throw err;
+  }
+  const after = readRecordState(deckDir) ?? state;
+  if (result.state === "blocked" && result.lastError?.code === "remote_conflict") {
+    if (asJson) {
+      emit({ ok: false, error: "conflict", conflicts: result.conflict?.conflicts ?? [], eTag: result.conflict?.currentETag ?? null, conflictId: result.conflict?.conflictId ?? null });
+      process.exit(3);
+    }
+    process.stdout.write(`${result.conflict?.conflicts?.length ?? 0} conflict(s) — nothing was written, both values are kept. Resolve them in the workspace.\n`);
+    process.exit(3);
+  }
+  if (result.state === "blocked") {
+    const code = result.lastError?.code ?? "blocked";
+    if (asJson) {
+      emit({ ok: false, error: code, message: result.lastError?.message ?? REFUSALS[code] ?? code });
+      process.exit(code === "stale" ? 3 : 1);
+    }
+    fail(`${code} — ${result.lastError?.message ?? REFUSALS[code] ?? code}`);
+  }
+  if (asJson) {
+    emit({ ok: true, url: after.url, eTag: after.eTag ?? null, versionLabel: after.versionLabel ?? null, applied: [], file: writeTo ?? resolveStoredFile(deckDir, after.file), state: result.state, synced: result.synced, ...(result.retryAt ? { retryAt: result.retryAt } : {}) });
+    return true;
+  }
+  process.stdout.write(result.synced ? `synced v${after.versionLabel ?? after.eTag ?? "?"}\n` : `${result.state}${result.lastError ? ` (${result.lastError.code})` : ""}${result.retryAt ? `, retry at ${result.retryAt}` : ""}\n`);
+  return true;
+}
+
+// The one answer where a non-2xx means the write SUCCEEDED: the bytes are in
+// SharePoint and only the version read after them failed (twice, server-side).
+//
+// Reporting that as a failed save is the worst answer available — the user's
+// edit is safe, and a plain re-read recovers everything the PUT could not say.
+// Storing the OLD eTag is the second worst: it is stale by exactly one version,
+// so every later sync would be refused against a version that no longer exists.
+// Hence: re-read and carry on, or change nothing at all and say so.
+async function recoverVersion(backendURL, state, asJson, err) {
+  try {
+    const data = await getRecord(backendURL, recordSelector(state), { kind: state.recordKind ?? null });
+    if (!data?.plan || !data?.eTag) throw new Error("the re-read carried no version");
+    return { ...data, applied: [], recovered: true };
+  } catch {
+    // The code leads the line so this is recognisable without parsing JSON —
+    // and it must never read as "your work is gone".
+    const message =
+      "your save landed in SharePoint, but the version it produced could not be read. " +
+      "Nothing local was changed, so this record now reads as one version behind until " +
+      "something re-reads it — run `slidemind record sync` again to pick it up.";
+    if (asJson) {
+      emit({
+        ok: false,
+        error: "version_unknown",
+        // Forwarded, never assumed: it is what tells a caller the write landed.
+        written: err?.body?.written === true,
+        message,
+      });
+      process.exit(1);
+    }
+    fail(`version_unknown — ${message}`);
+  }
+}
+
+function reportConflicts(deckDir, slug, body, asJson) {
+  const conflicts = Array.isArray(body.conflicts) ? body.conflicts : [];
+  const file = writeConflicts(deckDir, body);
+  if (asJson) {
+    emit({
+      ok: false,
+      error: "conflict",
+      conflicts,
+      eTag: body.eTag ?? null,
+      conflictsFile: file,
+    });
+    process.exit(3);
+  }
+  process.stdout.write(
+    `${conflicts.length} conflict(s) — nothing was written, both values are kept.\n` +
+      conflicts
+        .map(
+          (c) =>
+            `  ${c.path}\n      theirs: ${preview(c.theirs)}\n      mine:   ${preview(c.mine)}\n`,
+        )
+        .join("") +
+      `Edit "merged" in ${path.relative(process.cwd(), file)}, then: ` +
+      `slidemind record sync ${slug} --resolve <file>\n`,
+  );
+  process.exit(3);
+}
+
+function reportStale(body, asJson) {
+  if (asJson) {
+    emit({ ok: false, error: "stale", eTag: body.eTag ?? null });
+    process.exit(3);
+  }
+  // The code leads the line: conflict and stale both exit 3, and a caller
+  // reading plain output has nothing else to tell them apart by.
+  //
+  // A stale answer carries the current eTag but no version label (the service
+  // sends one only where it has fetched the item), and an eTag is a GUID with a
+  // counter — printing it after a "v" would read as a version nobody can match
+  // to anything. So it is named only when there is a label to name.
+  process.stdout.write(
+    `stale — the shared record moved${body.versionLabel ? ` to v${body.versionLabel}` : " on"}; ` +
+      "run `slidemind record sync` again to merge it.\n",
+  );
+  process.exit(3);
+}
+
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+
+async function cmdStatus(rest) {
+  const args = parseArgs(rest, "status");
+  const deckDir = resolveDeckArg(args.target);
+  const state = requireState(deckDir, deckSlug(deckDir));
+  const backendURL = await backendFor(state);
+  let data;
+  try {
+    data = await getRecord(backendURL, recordSelector(state), { kind: state.recordKind ?? null });
+  } catch (err) {
+    failCall(err, args.json);
+  }
+  const behind = Boolean(data.eTag) && data.eTag !== state.eTag;
+  // A local edit is the file differing from the version last RECEIVED — key
+  // order and whitespace are not edits, so the comparison is structural.
+  const local = resolveStoredFile(deckDir, state.file);
+  const localPlan = local ? readJsonOrNull(local) : null;
+  const localEdits = Boolean(localPlan) && !isDeepStrictEqual(localPlan, state.base);
+
+  if (args.json) {
+    emit({
+      ok: true,
+      url: state.url,
+      state: behind ? "behind" : "current",
+      behind,
+      localEdits,
+      eTag: data.eTag ?? null,
+      versionLabel: data.versionLabel ?? null,
+      link: state.link ?? null,
+    });
+    return;
+  }
+  const parts = [behind ? `behind (v${data.versionLabel ?? data.eTag})` : "current"];
+  if (localEdits) parts.push("local edits");
+  process.stdout.write(`${parts.join(", ")}\n`);
+}
+
+// ---------------------------------------------------------------------------
+
+const SUBCOMMANDS = {
+  create: cmdCreate,
+  open: cmdOpenRecord,
+  sync: cmdSync,
+  status: cmdStatus,
+};
+
+export async function cmdRecord(rest) {
+  const [sub, ...args] = rest;
+  const run = SUBCOMMANDS[sub];
+  if (!run) {
+    fail(sub ? `unknown record subcommand: ${sub}\n${USAGE}` : USAGE);
+  }
+  await run(args);
+}