slidemind 0.3.20 → 0.4.1

package/src/workspace/operations.mjs

@@ -0,0 +1,200 @@
+// Per-deck mutation wrapper for the persistent workspace.
+//
+// Every supported writer — browser save, task response, adapter action, sync
+// apply — runs through `runDeckOperation`. It reuses the ONE deck lock
+// (`acquireOwner`, revision.mjs) and adds what the lock alone does not give:
+//
+//   - a per-deck in-process queue, so two requests inside the daemon never race
+//     for the same deck and re-entry from inside an operation fails loudly
+//     instead of deadlocking on its own queue;
+//   - a durable operation intent (`state/workspace-operation.json`, atomic
+//     temp+rename) written BEFORE the mutation and cleared after it, so a crash
+//     mid-commit is found by the next writer as `recovery_required` rather than
+//     silently half-applied;
+//   - a busy answer (`deck_busy`) for a live agent session lock. A session is
+//     never stolen; the browser keeps its buffer and retries.
+//
+// Network work is never done under the lock. A remote save is two operations:
+// one to claim and snapshot, the network call outside, one to apply. The queue
+// keeps the pair ordered against other local writers; the sync record
+// (`workspace-sync.json`, sync lane) keeps the network claim.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { acquireOwner } from "../lib/revision.mjs";
+
+export const OPERATION_FILE = "workspace-operation.json";
+export const SCHEMA_VERSION = 1;
+
+const queues = new Map(); // deck key → tail promise
+const active = new AsyncLocalStorage(); // deck key of the operation this code runs inside
+
+const nowIso = () => new Date().toISOString();
+
+export function operationPath(workspaceDir) {
+  return path.join(workspaceDir, "state", OPERATION_FILE);
+}
+
+function deckKey(workspaceDir) {
+  try {
+    return fs.realpathSync(workspaceDir);
+  } catch {
+    return path.resolve(workspaceDir);
+  }
+}
+
+function writeAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+  fs.renameSync(tmp, file);
+}
+
+function typed(code, message, extra = {}) {
+  return Object.assign(new Error(message), { code, ...extra });
+}
+
+/**
+ * The unfinished operation on a deck, if any.
+ *
+ * `{ intent }` for a readable record, `{ malformed: true, raw }` for a file that
+ * is there but not a v1 record (kept on disk — it is recovery evidence, not
+ * garbage), `null` when the deck is clean.
+ */
+export function readOperationIntent(workspaceDir) {
+  const file = operationPath(workspaceDir);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return null;
+    throw err;
+  }
+  try {
+    const intent = JSON.parse(raw);
+    if (intent?.schemaVersion === SCHEMA_VERSION && typeof intent.id === "string") return { intent };
+    return { malformed: true, raw };
+  } catch {
+    return { malformed: true, raw };
+  }
+}
+
+/**
+ * Finish or refuse an unfinished operation. Runs before every mutation.
+ *
+ * `recover(intent)` is the caller's chance to complete or roll back what the
+ * intent describes (it has the before/after hashes the operation noted). It
+ * returns truthy when the deck is consistent again; the intent is then cleared.
+ * Without a recoverer, or when it declines, the deck stays as it is and
+ * `recovery_required` carries the intent — nobody manufactures a result.
+ */
+export function recoverDeckOperation(workspaceDir, { recover = null } = {}) {
+  const pending = readOperationIntent(workspaceDir);
+  if (!pending) return { recovered: false, intent: null };
+  if (pending.malformed) {
+    throw typed(
+      "recovery_required",
+      `${OPERATION_FILE} is unreadable; inspect it before mutating this deck.`,
+      { intent: null, malformed: true },
+    );
+  }
+  const { intent } = pending;
+  if (recover && recover(intent)) {
+    fs.rmSync(operationPath(workspaceDir), { force: true });
+    return { recovered: true, intent };
+  }
+  throw typed(
+    "recovery_required",
+    `operation ${intent.id} (${intent.kind}) did not finish; recover it before mutating this deck.`,
+    { intent },
+  );
+}
+
+/**
+ * Run one mutation on a deck under its lock, serialized with every other
+ * operation on that deck in this process.
+ *
+ * `fn(op)` receives `{ token, generation, intent, note(patch) }`. `token` is
+ * the owner token to hand to a CHILD adapter process for this operation only;
+ * it never goes to a browser. `note(patch)` merges evidence (before/after
+ * hashes, partial results) into the durable intent so recovery can finish or
+ * refuse precisely.
+ *
+ * Options: `operationId` (default a fresh UUID), `kind`, `expected` (hashes the
+ * caller verified before asking), `command` (lock label), `owner` — `undefined`
+ * inherits `SLIDEMIND_OWNER` (a headless command re-entering its own session),
+ * a string re-enters that token, `false` refuses to inherit any token (the
+ * daemon: it is nobody's session), `recover` (see recoverDeckOperation).
+ *
+ * Throws `deck_busy` (live session or another process), `recovery_required`,
+ * `operation_reentrant` (fn called runDeckOperation on the same deck — the
+ * queue would wait on itself), or whatever `fn` throws — with the intent kept
+ * on disk for the next writer to recover.
+ */
+export async function runDeckOperation(workspaceDir, options, fn) {
+  if (typeof options === "function") {
+    fn = options;
+    options = {};
+  }
+  const { operationId = randomUUID(), kind = "mutation", expected = null, command = "workspace", owner, recover = null } =
+    options ?? {};
+  const key = deckKey(workspaceDir);
+  if (active.getStore() === key) {
+    throw typed("operation_reentrant", "an operation may not start another on the same deck; split it or compose the work.");
+  }
+  const prev = queues.get(key) ?? Promise.resolve();
+  const run = prev.catch(() => {}).then(() => active.run(key, () => locked()));
+  queues.set(key, run);
+  try {
+    return await run;
+  } finally {
+    if (queues.get(key) === run) queues.delete(key);
+  }
+
+  async function locked() {
+    const held = takeOwner();
+    try {
+      recoverDeckOperation(workspaceDir, { recover });
+      const file = operationPath(workspaceDir);
+      let intent = {
+        schemaVersion: SCHEMA_VERSION,
+        id: operationId,
+        kind,
+        expected,
+        pid: process.pid,
+        startedAt: nowIso(),
+        notes: {},
+      };
+      writeAtomic(file, intent);
+      const result = await fn({
+        token: held.token,
+        generation: held.generation,
+        get intent() {
+          return intent;
+        },
+        note(patch) {
+          intent = { ...intent, notes: { ...intent.notes, ...patch }, updatedAt: nowIso() };
+          writeAtomic(file, intent);
+          return intent;
+        },
+      });
+      fs.rmSync(file, { force: true });
+      return result;
+    } finally {
+      held.release();
+    }
+  }
+
+  function takeOwner() {
+    const env = process.env.SLIDEMIND_OWNER;
+    if (owner === false) delete process.env.SLIDEMIND_OWNER;
+    try {
+      return acquireOwner(workspaceDir, { command, owner: typeof owner === "string" ? owner : null });
+    } finally {
+      if (owner === false && env !== undefined) process.env.SLIDEMIND_OWNER = env;
+    }
+  }
+}

package/src/workspace/pick-folder.mjs

@@ -0,0 +1,152 @@
+// The OS folder dialog, opened by the daemon on the user's behalf. A browser
+// page can never learn a picked folder's absolute path, so the workspace page
+// asks the daemon, which owns the machine, to show Finder / Explorer / zenity
+// and hand the choice back. Resolves to the absolute path, or null when the
+// user cancelled. Throws `picker_unavailable` when no dialog can be shown
+// (headless Linux without zenity/kdialog, a remote session).
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const DIALOG_TIMEOUT_MS = 10 * 60_000; // the dialog waits for a human
+
+const commands = {
+  darwin: (title) => ["osascript", ["-e", 'tell application "System Events" to activate', "-e", `POSIX path of (choose folder with prompt "${title}")`]],
+  win32: (title) => [
+    "powershell",
+    [
+      "-NoProfile",
+      "-STA",
+      "-Command",
+      `Add-Type -AssemblyName System.Windows.Forms; $d = New-Object System.Windows.Forms.FolderBrowserDialog; $d.Description = '${title}'; $d.ShowNewFolderButton = $false; if ($d.ShowDialog() -eq 'OK') { $d.SelectedPath }`,
+    ],
+  ],
+  linux: (title) => ["zenity", ["--file-selection", "--directory", `--title=${title}`]],
+};
+
+let inFlight = null; // one dialog at a time; a second request joins the first
+
+export function pickFolder({ title = "Choose a deck folder" } = {}) {
+  if (inFlight) return inFlight;
+  const safeTitle = title.replace(/["'\\]/g, "");
+  const [cmd, args] = (commands[process.platform] ?? commands.linux)(safeTitle);
+  inFlight = new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: DIALOG_TIMEOUT_MS, windowsHide: false }, (err, stdout) => {
+      const out = String(stdout ?? "").trim();
+      if (out) return resolve(out.length > 1 ? out.replace(/[\\/]+$/, "") : out);
+      // cancel: osascript exits 1 ("User canceled"), zenity exits 1, PowerShell prints nothing
+      if (!err || err.code === 1 || /cancel/i.test(err.message ?? "")) return resolve(null);
+      const e = new Error(`no folder dialog could be shown here (${err.code === "ENOENT" ? `${cmd} is not installed` : err.message}); type the path instead`);
+      e.code = "picker_unavailable";
+      reject(e);
+    });
+  }).finally(() => (inFlight = null));
+  return inFlight;
+}
+
+function launch(cmd, args, { tolerateExit1 = process.platform === "win32", timeout = 0 } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { windowsHide: true, timeout }, (err, _stdout, stderr) => {
+      // explorer.exe answers 1 even when it opened the window; a PowerShell that
+      // threw answers 1 too, so a caller that must know opts out
+      if (err && !(tolerateExit1 && err.code === 1)) {
+        return reject(new Error(err.code === "ENOENT" ? `${cmd} is not installed` : String(stderr || "").trim() || err.message));
+      }
+      resolve();
+    });
+  });
+}
+
+/** Show `dir` in the OS file manager (Finder / Explorer / xdg-open). */
+export function revealFolder(dir) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [dir]] : process.platform === "win32" ? ["explorer", [dir]] : ["xdg-open", [dir]];
+  return launch(cmd, args).catch((err) => {
+    const e = new Error(`could not open the folder here (${err.message})`);
+    e.code = "reveal_unavailable";
+    throw e;
+  });
+}
+
+/**
+ * Open `file` in its desktop app. PowerPoint is named explicitly on macOS —
+ * `open` alone hands a .pptx to whatever claims the extension (Keynote on a
+ * fresh Mac) — and falls back to the default handler when it is not installed.
+ */
+export async function openFile(file) {
+  const tries =
+    process.platform === "darwin"
+      ? [["open", ["-a", "Microsoft PowerPoint", file]], ["open", [file]]]
+      : process.platform === "win32"
+        ? [["explorer", [file]]]
+        : [["xdg-open", [file]]];
+  let last = null;
+  for (const [cmd, args] of tries) {
+    try {
+      return await launch(cmd, args);
+    } catch (err) {
+      last = err;
+    }
+  }
+  const e = new Error(`could not open this file here (${last ? last.message : "no handler"})`);
+  e.code = "open_unavailable";
+  throw e;
+}
+
+const powerShellString = (s) => `'${s.replace(/'/g, "''")}'`;
+
+/**
+ * Move `dir` to the OS trash. Recoverable on purpose: the workspace never calls
+ * fs.rm on a user's deck, so a wrong click is undone from the Trash. Node has no
+ * API for this and we add no dependency.
+ *
+ * macOS moves the folder into ~/.Trash directly. Asking Finder over AppleScript
+ * is the documented way and it is NOT usable here: the first call raises the
+ * automation-permission prompt and blocks the daemon until a human answers it
+ * (observed: `AppleEvent timed out (-1712)` after two minutes). A rename needs
+ * no permission and no prompt. Elsewhere the platform's own trash command runs,
+ * under a timeout.
+ *
+ * The result is VERIFIED — a command that exits 0 without removing the folder is
+ * a failure, not a success. Throws `trash_unavailable` when this machine has no
+ * trash to move it to.
+ */
+export async function trashFolder(dir) {
+  let failure = null;
+  try {
+    if (process.platform === "darwin") moveToHomeTrash(dir);
+    else if (process.platform === "win32") {
+      await launch("powershell", ["-NoProfile", "-Command", `$ErrorActionPreference='Stop'; Add-Type -AssemblyName Microsoft.VisualBasic; [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteDirectory(${powerShellString(dir)}, 'OnlyErrorDialogs', 'SendToRecycleBin')`], { tolerateExit1: false, timeout: TRASH_TIMEOUT_MS });
+    } else await launch("gio", ["trash", dir], { tolerateExit1: false, timeout: TRASH_TIMEOUT_MS });
+  } catch (err) {
+    failure = err;
+  }
+  if (!fs.existsSync(dir)) return dir;
+  const e = new Error(`could not move the folder to the Trash here (${failure ? failure.message : "it is still on disk"}); delete it in your file manager instead`);
+  e.code = "trash_unavailable";
+  throw e;
+}
+
+const TRASH_TIMEOUT_MS = 60_000; // a trash move is local work; a prompt or a hang must not own the daemon
+
+/**
+ * ~/.Trash/<name>, with " 2", " 3"… when that name is taken, exactly as Finder
+ * numbers a collision.
+ * ponytail: same-volume only. A deck on an external disk belongs in that
+ * volume's /Volumes/X/.Trashes/<uid>; EXDEV is reported instead of copying
+ * gigabytes behind the user's back.
+ */
+function moveToHomeTrash(dir) {
+  const trash = path.join(os.homedir(), ".Trash");
+  fs.mkdirSync(trash, { recursive: true });
+  const base = path.basename(dir);
+  let target = path.join(trash, base);
+  for (let n = 2; fs.existsSync(target); n++) target = path.join(trash, `${base} ${n}`);
+  try {
+    fs.renameSync(dir, target);
+  } catch (err) {
+    if (err?.code !== "EXDEV") throw err;
+    throw new Error(`${dir} is on another volume than your home folder; move it to the Trash in Finder`);
+  }
+  return target;
+}