slidemind 0.3.20 → 0.4.1

package/src/workspace/remote-links.mjs

@@ -0,0 +1,397 @@
+// Remote link intake (contracts §1/§3/§7): a pasted link becomes a JOB that
+// resolves to one of four things — a PPTX item, a shared plan record, a folder
+// (a SELECTION the user picks from, never a guessed child) — or a blocker the
+// user can act on. The browser and the CLI call the same functions; the job
+// file under `<sessionConfigDir>/workspace/jobs/` is what either reads back.
+//
+// Nothing here replaces local work: a link opened INTO a registered deck that
+// already holds another item, or carries unpublished edits, is refused with
+// `already_bound` / `dirty_target`. A deck already bound to the linked item is
+// offered as-is (`existing:true`). Opening a PPTX or a record into a fresh deck
+// reuses the existing `slidemind open` / `slidemind record open` commands as a
+// subprocess — the adopt/bind/hydrate gates stay where they are.
+//
+// `deps` injects the network (a signed-in provider client, the record service)
+// and the two open workflows so the suite runs against a mock host.
+
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { BIN_PATH, resolveDecksDir } from "../cli/common.mjs";
+import { resolveWorkspace } from "../lib/deck-paths.mjs";
+import { getRecord } from "../lib/record-client.mjs";
+import { readRecordState } from "../lib/record-state.mjs";
+import { readRemote } from "../lib/remote.mjs";
+import { revisionStatus } from "../lib/revision.mjs";
+import { jobPath, jobsDir, readJob } from "./discovery.mjs";
+import { addDeck, coded, getDeck, listDecks, listRoots, writeJsonAtomic } from "./registry.mjs";
+
+export const SELECTION_TTL_MS = 15 * 60 * 1000;
+const PPTX_RE = /\.(pptx|pptm|potx|potm|ppsx|ppsm)$/i;
+const JSON_RE = /\.json$/i;
+// The user can act on these; everything else is an operational failure.
+const BLOCKED = new Set([
+  "backend_ambiguous", "select_deck", "dirty_target", "already_bound", "login_required",
+  "access_denied", "name_exists", "selection_expired", "unsupported_link", "not_a_deck",
+]);
+
+const now = () => new Date().toISOString();
+
+// ---------------------------------------------------------------------------
+// defaults: sessions, provider client, record service, open workflows
+// ---------------------------------------------------------------------------
+
+/** Which paired backend serves this link: explicit scope > hosted-page origin > the only one > prod > the default; else ambiguous. */
+export function pickBackend(sessions, { backendURL = null, hint = null, fallback = null } = {}) {
+  const match = (want) =>
+    sessions.filter((s) => s.backendURL === want || s.label === want || s.backendURL.includes(want));
+  if (backendURL) {
+    const hits = match(backendURL);
+    if (hits.length === 1) return hits[0].backendURL;
+    throw coded("backend_ambiguous", `--backend ${backendURL} names ${hits.length} paired environment(s)`, {
+      choices: sessions.map((s) => ({ label: s.label, backendURL: s.backendURL })),
+    });
+  }
+  if (hint) {
+    const hits = sessions.filter((s) => safeOrigin(s.backendURL) === hint);
+    if (hits.length === 1) return hits[0].backendURL;
+  }
+  if (sessions.length === 1) return sessions[0].backendURL;
+  // The browser has no --backend to type, so an ambiguity here is a dead end.
+  // Prod serves the real tenant a share link belongs to, so it wins; otherwise
+  // the configured default decides.
+  const auto = sessions.find((s) => s.label === "prod") ?? sessions.find((s) => s.backendURL === fallback);
+  if (auto) return auto.backendURL;
+  throw coded("backend_ambiguous", "several environments are connected; name one with --backend <env>", {
+    choices: sessions.map((s) => ({ label: s.label, backendURL: s.backendURL })),
+  });
+}
+
+function safeOrigin(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+async function defaultSession({ backendURL, hint }) {
+  const { sessionsInScope } = await import("../bridge/client/transport.mjs");
+  const { getDefaultBackend } = await import("../bridge/config.mjs");
+  const { getSharePointToken, sharePointResource } = await import("../bridge/graph-auth.mjs");
+  const provider = await import("../bridge/sharepoint.mjs");
+  const chosen = pickBackend(sessionsInScope(), { backendURL, hint, 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 }) };
+}
+
+/** `slidemind <args>` as a child, one JSON value expected on stdout. */
+export function runCli(args, { env = {} } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [BIN_PATH, ...args, "--json"], {
+      env: { ...process.env, ...env },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (c) => (out += c));
+    child.stderr.on("data", (c) => (err += c));
+    child.on("close", (status) => {
+      let json = null;
+      try {
+        json = JSON.parse(out);
+      } catch {
+        // not JSON: the error text is on stderr
+      }
+      resolve({ status, json, stderr: err });
+    });
+  });
+}
+
+function decksDir() {
+  return listRoots()[0] ?? resolveDecksDir();
+}
+
+// A fresh deck directory for a link opened without a target: the item's stem,
+// suffixed only when that name is taken.
+function freshDeckPath(name) {
+  const stem = String(name ?? "deck").replace(/\.[^.]+$/, "").replace(/[^\w.-]+/g, "-").replace(/^-+|-+$/g, "") || "deck";
+  const base = decksDir();
+  let candidate = path.join(base, stem);
+  for (let n = 2; fs.existsSync(candidate); n++) candidate = path.join(base, `${stem}-${n}`);
+  return candidate;
+}
+
+async function defaultOpenPptx({ link, deckPath, backendURL }) {
+  const r = await runCli(["open", link, "--deck", deckPath], { env: { SLIDEMIND_BACKEND: backendURL, SLIDEMIND_DECKS: decksDir() } });
+  if (r.status !== 0) throw coded("open_failed", r.stderr.trim().split("\n").pop() || `slidemind open exited ${r.status}`);
+  return deckPath;
+}
+
+async function defaultOpenRecord({ link, deckPath, backendURL }) {
+  const file = path.join(deckPath, ".slidemind", "plan.json");
+  const r = await runCli(["record", "open", link, "--deck", deckPath, "--file", file], { env: { SLIDEMIND_BACKEND: backendURL, SLIDEMIND_DECKS: decksDir() } });
+  if (r.status !== 0) throw coded(r.json?.error ?? "open_failed", r.json?.message ?? r.stderr.trim().split("\n").pop() ?? `record open exited ${r.status}`);
+  return deckPath;
+}
+
+export const defaultDeps = {
+  session: defaultSession,
+  getRecord,
+  openPptx: defaultOpenPptx,
+  openRecord: defaultOpenRecord,
+};
+
+// ---------------------------------------------------------------------------
+// jobs
+// ---------------------------------------------------------------------------
+
+function newJob(kind, input) {
+  const job = { schemaVersion: 1, id: randomUUID(), kind, state: "running", input, result: null, error: null, selection: null, startedAt: now(), finishedAt: null };
+  writeJsonAtomic(jobPath(job.id), job);
+  return job;
+}
+
+function settle(job, fn) {
+  return fn(job).then(
+    (result) => {
+      job.state = "completed";
+      job.result = result ?? job.result;
+      job.finishedAt = now();
+      writeJsonAtomic(jobPath(job.id), job);
+      return job;
+    },
+    (err) => {
+      const code = err?.code ?? "internal";
+      job.state = BLOCKED.has(code) ? "blocked" : "failed";
+      job.error = { code, message: err?.message ?? String(err), ...(err?.choices ? { choices: err.choices } : {}), ...(err?.details ? { details: err.details } : {}) };
+      job.finishedAt = now();
+      writeJsonAtomic(jobPath(job.id), job);
+      return job;
+    },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// link classification
+// ---------------------------------------------------------------------------
+
+/** A hosted APP page that names a record (`…/<page>.html?record=<webUrl>`) → its record link + origin hint. */
+export function parseHostedLink(url) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return null;
+  }
+  const record = u.searchParams.get("record");
+  if (!/\.html$/i.test(u.pathname) || !record) return null;
+  return { record, hint: u.origin };
+}
+
+// A registered deck already bound to this item (PPTX binding or record binding).
+function boundDeck(match) {
+  for (const d of listDecks({ hidden: true, limit: 10_000 }).decks) {
+    if (d.missing) continue;
+    let ws;
+    try {
+      ws = resolveWorkspace(d.path);
+    } catch {
+      continue;
+    }
+    if (match(ws)) return d;
+  }
+  return null;
+}
+
+const samePptx = (item) => (ws) => {
+  try {
+    const r = readRemote(ws);
+    return Boolean(r && r.driveId === item.driveId && r.itemId === item.itemId);
+  } catch {
+    return false;
+  }
+};
+const sameRecord = (record) => (ws) => {
+  const s = readRecordState(ws);
+  if (!s) return false;
+  if (s.driveId && s.itemId && record.identity) return s.driveId === record.identity.driveId && s.itemId === record.identity.itemId;
+  return Boolean(s.url && s.url === record.url);
+};
+
+function targetDeck(deckId) {
+  const deck = getDeck(deckId);
+  if (!deck) throw coded("unknown_deck", `no registered deck ${deckId}`);
+  if (!fs.existsSync(deck.path)) throw coded("missing_path", `${deck.path} is not there any more`);
+  return { ...deck, workspaceDir: resolveWorkspace(deck.path) };
+}
+
+// Where a PPTX may land. Never replaces: another binding → already_bound,
+// unpublished local edits (or any adopted generation) → dirty_target.
+function pptxTarget(deckId, item) {
+  if (!deckId) return { deckPath: freshDeckPath(item.name), fresh: true };
+  const deck = targetDeck(deckId);
+  let bound = null;
+  try {
+    bound = readRemote(deck.workspaceDir);
+  } catch (err) {
+    throw coded("dirty_target", `${deck.name} has an unfinished workspace transaction: ${err.message}`);
+  }
+  if (bound && bound.driveId === item.driveId && bound.itemId === item.itemId) return { deckPath: deck.path, existing: deck };
+  if (bound) throw coded("already_bound", `${deck.name} publishes to ${bound.name ?? bound.documentInstance}; open the link into another deck`, { deckId: deck.id });
+  const status = revisionStatus(deck.workspaceDir);
+  if (status.adopted) {
+    throw coded("dirty_target", `${deck.name} already holds an adopted deck${status.localDirty ? ` with ${status.dirtySlides.length} unpublished slide edit(s)` : ""}; open the link into another deck`, { deckId: deck.id });
+  }
+  return { deckPath: deck.path, existing: null };
+}
+
+function recordTarget(deckId, record) {
+  if (!deckId) return { deckPath: freshDeckPath(record.name ?? "plan"), fresh: true };
+  const deck = targetDeck(deckId);
+  const state = readRecordState(deck.workspaceDir);
+  if (state && sameRecord(record)(deck.workspaceDir)) return { deckPath: deck.path, existing: deck };
+  if (state?.url) throw coded("already_bound", `${deck.name} already shares ${state.name ?? state.url}`, { deckId: deck.id });
+  const planFile = path.join(deck.workspaceDir, "plan.json");
+  if (fs.existsSync(planFile)) throw coded("dirty_target", `${deck.name} already has a local plan; open the record into another deck`, { deckId: deck.id });
+  return { deckPath: deck.path, existing: null };
+}
+
+const supported = (child) => child.kind === "folder" || (child.kind === "file" && (PPTX_RE.test(child.name ?? "") || JSON_RE.test(child.name ?? "")));
+
+async function openSelection(job, { provider, client, backendURL }, folder) {
+  const page = await provider.listChildren(client, { driveId: folder.driveId, itemId: folder.itemId });
+  job.selection = {
+    selectionId: randomUUID(),
+    expiresAt: new Date(Date.now() + SELECTION_TTL_MS).toISOString(),
+    backendURL,
+    folder: { driveId: folder.driveId, itemId: folder.itemId, name: folder.name ?? null, webUrl: folder.webUrl ?? null },
+    choices: page.items.filter(supported),
+    cursor: page.nextCursor,
+  };
+  return { type: "folder", selectionId: job.selection.selectionId, choices: job.selection.choices, nextCursor: page.nextCursor };
+}
+
+// The one open path for both entry points (a pasted link, a selected child).
+async function openItem(job, s, { item, link, deckId }) {
+  const { provider, client, backendURL } = s;
+  if (item.kind === "folder") return openSelection(job, s, item);
+  if (item.kind !== "file") throw coded("unsupported_link", `${item.name ?? "that item"} is neither a file nor a folder`);
+  if (JSON_RE.test(item.name ?? "")) {
+    // A JSON file is a plan only if the record service says so.
+    const record = await s.deps.getRecord(backendURL, { url: link });
+    const already = boundDeck(sameRecord(record));
+    if (already && (!deckId || already.id === deckId)) return { type: "record", deckId: already.id, existing: true, name: record.name ?? null };
+    const target = recordTarget(deckId, record);
+    if (target.existing) return { type: "record", deckId: target.existing.id, existing: true, name: record.name ?? null };
+    const opened = await s.deps.openRecord({ link, deckPath: target.deckPath, backendURL, record });
+    return { type: "record", deckId: addDeck(opened).id, existing: false, name: record.name ?? null };
+  }
+  if (!PPTX_RE.test(item.name ?? "")) throw coded("unsupported_link", `${item.name} is not a presentation, a plan record or a folder`);
+  const already = boundDeck(samePptx(item));
+  if (already && (!deckId || already.id === deckId)) return { type: "pptx", deckId: already.id, existing: true, name: item.name };
+  const target = pptxTarget(deckId, item);
+  if (target.existing) return { type: "pptx", deckId: target.existing.id, existing: true, name: item.name };
+  const opened = await s.deps.openPptx({ link, deckPath: target.deckPath, backendURL, item });
+  return { type: "pptx", deckId: addDeck(opened).id, existing: false, name: item.name };
+}
+
+async function resolveItem(s, link) {
+  try {
+    return await s.provider.resolveLink(s.client, link);
+  } catch (err) {
+    if (err?.code === "identity_unresolved" || err?.status === 400 || err?.status === 404) {
+      throw coded("unsupported_link", "that link does not name a SharePoint file or folder (a site or list link cannot be opened)");
+    }
+    if (err?.status === 403) throw coded("access_denied", "you cannot reach that item");
+    if (err?.code === "bridge_timeout" || /ECONNREFUSED|fetch failed/i.test(String(err?.message))) throw coded("offline", "SharePoint could not be reached");
+    throw err;
+  }
+}
+
+/**
+ * Resolve a pasted link. Returns the settled job: `completed` with
+ * `result.type` pptx | record | folder (a selection), `blocked` with an
+ * actionable `error.code`, or `failed`.
+ */
+export async function resolveRemoteLink({ url, backendURL = null, deckId = null }, overrides = {}) {
+  const d = { ...defaultDeps, ...overrides };
+  const job = newJob("remote-resolve", { url, backendURL, deckId });
+  return settle(job, async () => {
+    if (typeof url !== "string" || !/^https?:\/\//i.test(url)) throw coded("validation_failed", "a remote link starts with https://");
+    const hosted = parseHostedLink(url);
+    const s = { ...(await d.session({ backendURL, hint: hosted?.hint ?? null })), deps: d };
+    const link = hosted ? hosted.record : url;
+    const item = await resolveItem(s, link);
+    return openItem(job, s, { item, link, deckId });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// selections
+// ---------------------------------------------------------------------------
+
+/** The job carrying a live selection, or null. ponytail: scans the jobs dir; index it if jobs pile up. */
+export function findSelection(selectionId) {
+  let names = [];
+  try {
+    names = fs.readdirSync(jobsDir());
+  } catch {
+    return null;
+  }
+  for (const n of names) {
+    if (!n.endsWith(".json")) continue;
+    const job = readJob(n.slice(0, -5));
+    if (job?.selection?.selectionId === selectionId) return job;
+  }
+  return null;
+}
+
+function liveSelection(job, selectionId) {
+  if (!job?.selection || job.selection.selectionId !== selectionId) throw coded("selection_expired", "that selection is not one this workspace issued");
+  if (Date.parse(job.selection.expiresAt) < Date.now()) throw coded("selection_expired", "that selection has expired — resolve the link again");
+  return job.selection;
+}
+
+/** The next page of a selection's folder, appended to the choices the selection may later accept. */
+export async function listSelectionChildren({ selectionId, cursor = null }, overrides = {}) {
+  const d = { ...defaultDeps, ...overrides };
+  const job = findSelection(selectionId);
+  const sel = liveSelection(job, selectionId);
+  const s = await d.session({ backendURL: sel.backendURL });
+  const page = await s.provider.listChildren(s.client, sel.folder, { cursor: cursor ?? sel.cursor });
+  const items = page.items.filter(supported);
+  const known = new Set(sel.choices.map((c) => c.id));
+  for (const c of items) if (!known.has(c.id)) sel.choices.push(c);
+  sel.cursor = page.nextCursor;
+  writeJsonAtomic(jobPath(job.id), job);
+  return { items, nextCursor: page.nextCursor };
+}
+
+/**
+ * Resume a selection: the chosen child is re-resolved (identity and access are
+ * checked again, never trusted from the stored page) and opened exactly like a
+ * pasted link. A folder choice yields the next selection on the same job.
+ */
+export async function selectChoice(jobId, { selectionId, choiceId, localTarget = null }, overrides = {}) {
+  const d = { ...defaultDeps, ...overrides };
+  const job = readJob(jobId);
+  if (!job) throw coded("unknown_job", `no job ${jobId}`);
+  const sel = liveSelection(job, selectionId);
+  const choice = sel.choices.find((c) => c.id === choiceId);
+  if (!choice) throw coded("validation_failed", "that choice is not part of this selection");
+  job.state = "running";
+  job.selection = null;
+  job.finishedAt = null;
+  writeJsonAtomic(jobPath(job.id), job);
+  return settle(job, async () => {
+    const s = { ...(await d.session({ backendURL: sel.backendURL })), deps: d };
+    const item = await s.provider.getItem(s.client, { driveId: choice.driveId, itemId: choice.id });
+    return openItem(job, s, { item, link: item.webUrl, deckId: localTarget });
+  });
+}