slidemind 0.3.20 → 0.4.0

package/src/workspace/remote-status.mjs

@@ -0,0 +1,359 @@
+// The deck's remote association, in one honest card (contracts §2 destination
+// file, synchronization.md "Binding and publication").
+//
+//   state/destination.json   the FOLDER a pack deck's plan and presentation go
+//                            to — folder only, never a mutable eTag
+//   state/record.json        the shared plan binding (record-state.mjs)
+//   state/remote.json        the published PPTX binding (remote.mjs)
+//   state/workspace-sync.json the plan queue's state (sync lane)
+//
+// `remoteStatus` reads disk and the in-memory capability cache only — it is
+// called on every deck view and must never turn a page load into a network
+// call. "Synced" is the queue's word, not this module's: a chosen folder is
+// destination-only until a record is confirmed, and writes switched off by
+// the deployment show as exactly that.
+//
+// Two write answers, never folded into one: `writes` is the shared PLAN record
+// (the record service AND the deployment's policy), `publishWrites` is the
+// PRESENTATION (the policy alone). A deployment without the record service
+// still publishes the .pptx; one flag for both showed "read-only" on a deck
+// whose presentation was one build away from the folder.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { requireReviewApproved } from "../builders/review.mjs";
+import { backendCapabilitiesCache, backendCapabilitiesResult, sharedRecordsSupport } from "../bridge/client/transport.mjs";
+import { deckSlug, planPageOwner, resolveWorkspace, statePath } from "../lib/deck-paths.mjs";
+import { readRecordState } from "../lib/record-state.mjs";
+import { readRemote } from "../lib/remote.mjs";
+import { revisionStatus } from "../lib/revision.mjs";
+import { coded, writeJsonAtomic } from "./registry.mjs";
+
+export const DESTINATION_FILE = "destination.json";
+export const SYNC_FILE = "workspace-sync.json";
+export const SCHEMA_VERSION = 1;
+
+export function destinationPath(workspaceDir) {
+  return statePath(workspaceDir, DESTINATION_FILE);
+}
+
+function readJson(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { malformed: true, file };
+  }
+}
+
+/** The saved destination, null, or `{malformed,file}` — a broken file is reported, never reset. */
+export function readDestination(workspaceDir) {
+  const d = readJson(destinationPath(workspaceDir));
+  if (d && !d.malformed && d.schemaVersion !== SCHEMA_VERSION) return { malformed: true, file: destinationPath(workspaceDir) };
+  return d;
+}
+
+export function writeDestination(workspaceDir, dest) {
+  const record = { schemaVersion: SCHEMA_VERSION, ...dest, updatedAt: new Date().toISOString() };
+  writeJsonAtomic(destinationPath(workspaceDir), record);
+  return record;
+}
+
+/** A structurally editable plan record exists: the pack's `plan.json` (or the declared record) parses. */
+export function hasEditablePlan(workspaceDir) {
+  const owner = planPageOwner(workspaceDir);
+  const rel = owner.owner === "core" ? null : owner.recordPath ?? "plan.json";
+  if (!rel) return false;
+  const v = readJson(path.join(workspaceDir, rel));
+  return Boolean(v && !v.malformed && typeof v === "object");
+}
+
+const hostOf = (url) => {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+};
+
+async function defaultSession({ backendURL }) {
+  const { sessionsInScope } = await import("../bridge/client/transport.mjs");
+  const { getSharePointToken, sharePointResource } = await import("../bridge/graph-auth.mjs");
+  const { pickBackend } = await import("./remote-links.mjs");
+  const provider = await import("../bridge/sharepoint.mjs");
+  const { getDefaultBackend } = await import("../bridge/config.mjs");
+  const chosen = pickBackend(sessionsInScope(), { backendURL, fallback: getDefaultBackend() });
+  const origin = await sharePointResource(chosen);
+  if (!origin) throw coded("unsupported_link", "this deployment publishes no SharePoint origin");
+  const token = await getSharePointToken(chosen);
+  if (!token) throw coded("login_required", "your Microsoft 365 sign-in is missing or expired — run `slidemind login`");
+  return { backendURL: chosen, provider, client: provider.createClient({ origin, token }) };
+}
+
+// The three-valued write answer: deployment policy AND shared-record support,
+// never folded into one boolean. `refresh:true` bypasses the cache — this runs
+// right before a decision, not on a page view.
+async function defaultWrites(backendURL, { refresh, kind = null }) {
+  if (!refresh) {
+    const cached = backendCapabilitiesCache.get(backendURL);
+    if (!cached) return "unknown";
+  }
+  const s = await sharedRecordsSupport(backendURL, { refresh, kind });
+  if (s.status === "unknown") return "unknown";
+  return s.status === "supported" && s.sharepointPublish ? "enabled" : "disabled";
+}
+
+// The presentation's write answer: the deployment's `sharepointPublish` policy
+// alone — publishing a .pptx needs no record service.
+async function defaultPublishWrites(backendURL, { refresh }) {
+  if (!refresh && !backendCapabilitiesCache.get(backendURL)) return "unknown";
+  const probe = await backendCapabilitiesResult(backendURL, { refresh });
+  if (probe.status === "unknown") return "unknown";
+  return probe.caps?.sharepointPublish === true ? "enabled" : "disabled";
+}
+
+/**
+ * A build `slidemind publish` would upload as it stands: a candidate that still
+ * matches the slides, from a deck whose preview passed its one-time review (an
+ * adopted deck needs none). Disk only.
+ */
+export function hasPublishableBuild(workspaceDir) {
+  let candidate;
+  try {
+    candidate = revisionStatus(workspaceDir)?.candidate;
+  } catch {
+    return false;
+  }
+  return Boolean(candidate && !candidate.stale) && requireReviewApproved(workspaceDir) === null;
+}
+
+/** `slidemind publish <deck> --json` as a child: every gate it enforces stays where it is. */
+async function defaultPublish({ deckRoot, backendURL }) {
+  const { runCli } = await import("./remote-links.mjs");
+  return runCli(["publish", deckRoot], { env: { ...(backendURL ? { SLIDEMIND_BACKEND: backendURL } : {}), SLIDEMIND_NO_UPDATE_CHECK: "1" } });
+}
+
+export const defaultDeps = { session: defaultSession, writes: defaultWrites, publishWrites: defaultPublishWrites, hasEditablePlan, hasPublishableBuild, publish: defaultPublish };
+
+/**
+ * Point a deck at a folder. Verifies the folder, refuses a tenant that differs
+ * from what the deck already binds, refuses a name that is taken (no implicit
+ * overwrite — the caller offers "open existing" or "another name"), then saves
+ * the destination even when writes are disabled: it is destination-only then,
+ * and says so. Record creation itself is the sync lane's (`shouldCreatePlan`).
+ */
+export async function connectDestination({ deckRoot, folderRef, pptxName = null, backendURL = null }, overrides = {}) {
+  const d = { ...defaultDeps, ...overrides };
+  const ws = resolveWorkspace(deckRoot);
+  const s = await d.session({ backendURL });
+  const folder = await s.provider.getFolder(s.client, folderRef);
+
+  const record = readRecordState(ws);
+  let pptx = null;
+  try {
+    pptx = readRemote(ws);
+  } catch {
+    // an unfinished transaction is not a tenant mismatch
+  }
+  const folderHost = hostOf(folder.webUrl);
+  if (record?.tenantId && folder.tenantId && record.tenantId !== folder.tenantId) {
+    throw coded("cross_tenant", `${deckSlug(ws)}'s shared plan lives in another tenant; a destination cannot cross tenants`);
+  }
+  if (pptx?.tenant && folderHost && pptx.tenant !== folderHost) {
+    throw coded("cross_tenant", `${deckSlug(ws)} publishes to ${pptx.tenant}; a destination on ${folderHost} would cross tenants`);
+  }
+  if (record?.backendURL && record.backendURL !== s.backendURL) {
+    throw coded("cross_tenant", `${deckSlug(ws)}'s shared plan is bound to another environment (${record.backendURL})`);
+  }
+
+  const stem = String(pptxName ?? `${deckSlug(ws)}.pptx`).replace(/\.pptx$/i, "");
+  if (!stem || /[\\/]/.test(stem)) throw coded("validation_failed", "pptxName must be a plain .pptx file name");
+  const names = { pptxName: `${stem}.pptx`, name: `${stem}-plan.json` };
+  for (const [key, name] of Object.entries(names)) {
+    // An item bound to THIS deck under that name is not a collision.
+    if (key === "pptxName" && pptx?.name === name && pptx.parentId === folder.id) continue;
+    if (key === "name" && record?.name === name && record.parentId === folder.id) continue;
+    const hit = await s.provider.resolveDestination(s.client, { driveId: folder.driveId, itemId: folder.id }, name);
+    if (hit.exists) {
+      throw coded("name_exists", `${name} already exists in ${folder.name}`, {
+        details: { name, existing: { id: hit.item.itemId, driveId: hit.item.driveId, name: hit.item.name, webUrl: hit.item.webUrl, kind: hit.item.kind } },
+        choices: ["open-existing", "use-another-name"],
+      });
+    }
+  }
+
+  const writes = await d.writes(s.backendURL, { refresh: true });
+  const publishWrites = await d.publishWrites(s.backendURL, { refresh: true });
+  const editable = d.hasEditablePlan(ws);
+  const destination = writeDestination(ws, {
+    backendURL: s.backendURL,
+    tenantId: folder.tenantId ?? null,
+    driveId: folder.driveId,
+    itemId: folder.id,
+    parentId: folder.parentId ?? null,
+    webUrl: folder.webUrl ?? null,
+    folderName: folder.name ?? null,
+    ...names,
+    state: editable ? "ready_to_create" : "waiting_for_plan",
+    writes,
+    publishWrites,
+    connectedAt: new Date().toISOString(),
+  });
+  // A folder connected AFTER the deck was built: the build is uploaded now
+  // (`uploadToDestination`); every later build publishes itself (build-pptx).
+  const shouldPublish = publishWrites === "enabled" && !pptx && d.hasPublishableBuild(ws);
+  return { destination, writes, publishWrites, shouldCreatePlan: editable && writes === "enabled" && !record?.url, shouldPublish };
+}
+
+// The reasons the card words for a person; anything else reads "could not be uploaded".
+const UPLOAD_REASONS = {
+  name_conflict: "name_exists",
+  deck_busy: "deck_busy",
+  login_required: "login_required",
+  remote_saving_disabled: "write_disabled",
+};
+
+/**
+ * Upload the deck's approved build into its saved folder — the first publish of
+ * a folder connected after the build. `slidemind publish` runs as a child, so
+ * the review gate, ownership and the create-only route (a taken name is
+ * refused, never overwritten) stay the command's. The outcome lands in
+ * destination.json's `upload` for the card: `uploading`, then `done` or
+ * `failed` with a reason the page can word.
+ */
+export async function uploadToDestination(deckRoot, overrides = {}) {
+  const d = { ...defaultDeps, ...overrides };
+  const ws = resolveWorkspace(deckRoot);
+  const mark = (upload) => {
+    const current = readDestination(ws);
+    if (current && !current.malformed) writeDestination(ws, { ...current, upload: { ...upload, at: new Date().toISOString() } });
+  };
+  const dest = readDestination(ws);
+  if (!dest || dest.malformed) return { state: "skipped" };
+  mark({ state: "uploading" });
+  let run;
+  try {
+    run = await d.publish({ deckRoot, backendURL: dest.backendURL ?? null });
+  } catch (err) {
+    run = { status: 1, json: null, stderr: err?.message ?? String(err) };
+  }
+  if (run.status === 0 && run.json?.status === "committed") {
+    mark({ state: "done" });
+    return { state: "done", publish: run.json };
+  }
+  const upload = { state: "failed", reason: UPLOAD_REASONS[run.json?.reason] ?? "publish_failed" };
+  mark(upload);
+  return { ...upload, publish: run.json ?? null };
+}
+
+/**
+ * The destination a deck already implies: the saved one, else the folder its
+ * PUBLISHED presentation sits in (synchronization.md "Binding and publication"
+ * — an existing PPTX binding without a record resolves its parent folder).
+ * One network round when derived; null when the deck names no folder at all.
+ */
+export async function ensureDestination(deckRoot, { backendURL = null } = {}, overrides = {}) {
+  const ws = resolveWorkspace(deckRoot);
+  const saved = readDestination(ws);
+  if (saved) return saved;
+  let pptx = null;
+  try {
+    pptx = readRemote(ws);
+  } catch {
+    return null;
+  }
+  if (!pptx?.driveId || !pptx?.itemId) return null;
+  const d = { ...defaultDeps, ...overrides };
+  const s = await d.session({ backendURL });
+  const item = await s.provider.getItem(s.client, { driveId: pptx.driveId, itemId: pptx.itemId });
+  if (!item?.parentId) return null;
+  const { destination } = await connectDestination(
+    { deckRoot, folderRef: { driveId: item.driveId ?? pptx.driveId, itemId: item.parentId }, pptxName: pptx.name ?? item.name, backendURL: s.backendURL },
+    { ...overrides, session: async () => s },
+  );
+  return destination;
+}
+
+/**
+ * The card, from disk: shared plan vs published PPTX vs a mere destination,
+ * each with its own state, plus the write policy as last observed.
+ */
+export async function remoteStatus(deckRoot, overrides = {}) {
+  const d = { ...defaultDeps, ...overrides };
+  const ws = resolveWorkspace(deckRoot);
+  const record = readRecordState(ws);
+  let pptx = null;
+  try {
+    pptx = readRemote(ws);
+  } catch {
+    pptx = null;
+  }
+  const destination = readDestination(ws);
+  const sync = readJson(statePath(ws, SYNC_FILE));
+  const backendURL = record?.backendURL ?? destination?.backendURL ?? null;
+  let writes = "unknown";
+  if (backendURL) {
+    try {
+      writes = await d.writes(backendURL, { refresh: false, kind: record?.recordKind ?? null });
+    } catch {
+      writes = "unknown";
+    }
+  }
+  if (writes === "unknown" && destination?.writes) writes = destination.writes;
+  let publishWrites = "unknown";
+  if (backendURL) {
+    try {
+      publishWrites = await d.publishWrites(backendURL, { refresh: false });
+    } catch {
+      publishWrites = "unknown";
+    }
+  }
+  if (publishWrites === "unknown" && destination?.publishWrites) publishWrites = destination.publishWrites;
+
+  let plan;
+  if (record?.url) {
+    const blocked = sync && !sync.malformed && ["blocked", "outcome-unknown"].includes(sync.state);
+    plan = {
+      state: blocked ? "blocked" : "shared",
+      link: record.link ?? record.url,
+      name: record.name ?? null,
+      lastConfirmedAt: sync?.lastConfirmedAt ?? record.syncedAt ?? null,
+      sync: sync && !sync.malformed ? sync.state : null,
+      reason: blocked ? sync.lastError?.code ?? sync.state : writes === "disabled" ? "write_disabled" : null,
+    };
+  } else if (destination && !destination.malformed) {
+    plan = {
+      state: "destination-only",
+      link: destination.webUrl,
+      name: destination.name,
+      lastConfirmedAt: null,
+      sync: null,
+      reason: writes === "disabled" ? "write_disabled" : writes === "unknown" ? "capability_unknown" : destination.state,
+    };
+  } else {
+    plan = { state: "none", link: null, name: null, lastConfirmedAt: null, sync: null, reason: null };
+  }
+
+  const pptxCard = pptx
+    ? { state: pptx.lastReceipt ? "published" : "bound", link: pptx.webUrl ?? null, name: pptx.name ?? null, lastConfirmedAt: pptx.lastReceipt?.confirmedAt ?? pptx.lastPulledAt ?? null }
+    : { state: "none", link: null, name: null, lastConfirmedAt: null };
+
+  return {
+    plan,
+    pptx: pptxCard,
+    destination: destination && !destination.malformed
+      ? { webUrl: destination.webUrl, folderName: destination.folderName ?? null, name: destination.name, pptxName: destination.pptxName, state: destination.state, upload: destination.upload ?? null }
+      : destination?.malformed
+        ? { malformed: true }
+        : null,
+    writes,
+    publishWrites,
+    backendURL,
+  };
+}