@stll/folio-cli 0.1.0 → 0.2.0

package/README.md

@@ -105,8 +105,9 @@ Every change commits, so there is no separate save:
   content, not identical ZIP bytes.
 - **Write lease.** A write holds `.<name>.docx.folio-lock` beside the file
   (pid, host, expiry, and a random token), created complete or not at all.
-  Another holder, such as an editor session, makes a write fail with
-  `locked` (exit 10) unless `--force`. Just before journaling and again
+  An editor holding it with unsaved edits is asked to save and release
+  first (see [Saving from an editor](#saving-from-an-editor)); any other
+  holder makes a write fail with `locked` (exit 10) unless `--force`. Just before journaling and again
   before the rename, a write checks that the lock still carries its token, so
   a writer whose lease was taken over stops without writing. Reads ignore the
   lease. A lease whose process has exited, or that expired, is replaced; a
@@ -121,6 +122,27 @@ Every change commits, so there is no separate save:
   reply of one transaction carries one UTC timestamp, `--date` to fix it for
   reproducible output. (`compare` stamps its redline with the current time.)
 
+### Saving from an editor
+
+`folio save <file> --from <saved.docx> --expect-version <fileVersion>` commits
+a whole package a live editor serialized, with the same lease, recovery,
+checks, backup, and journal as a tool call (`tool: "editor_save"`, with
+`--surface` and `--save-strategy` recorded). Unlike the tool commands it may
+rewrite every part, so it is not an MCP tool. `--owner` names the lease holder.
+
+An editor with unsaved edits holds the lease long-lived (`acceptsFlush`, 30 s,
+renewed every 10 s) and watches for `.<name>.docx.folio-flush-<id>` requests.
+A write that finds it writes a request and waits up to `--flush-wait` ms
+(default 5000) for the editor to save under its lease (`--lease-token`) and
+release; the write then runs on the saved version. An agent tool's
+`--expect-version` from before the flush is accepted when the journal shows
+the editor's save from exactly that version and every block it targets is a
+package `w14:paraId` in both versions; its text-hash preconditions decide the
+rest. A call targeting a text-derived id (`blockIdSource: synthetic`), or no
+block, is refused with `stale_version` and re-reads. An editor that does not release in time is
+treated by the ordinary lease rules. `@stll/folio-cli/editor-lease` exports
+the editor side.
+
 ### Journal, retries, and recovery
 
 Each committed transaction appends a line to `.folio/journal.jsonl` beside the

package/dist/cli.js

@@ -9,6 +9,7 @@ import { runRender, runServe } from "./preview-commands.js";
 import { resolveAuthor, resolveTransactionDate } from "./provenance.js";
 import { findCommand, listCommands, toolAccess } from "./registry.js";
 import { resolveRoots } from "./roots.js";
+import { parseFlushWait, runSave } from "./save.js";
 import { Result } from "better-result";
 import { parseArgs } from "node:util";
 //#region src/cli.ts
@@ -100,6 +101,11 @@ const WRITE_FLAGS = [
 		flag: "journal",
 		description: "Journal file (default: .folio/journal.jsonl beside the destination).",
 		option: { type: "string" }
+	},
+	{
+		flag: "flush-wait",
+		description: "Milliseconds to wait for an editor holding the lease to save and release (default 5000).",
+		option: { type: "string" }
 	}
 ];
 const DIRECT_FLAG = {
@@ -147,6 +153,7 @@ const rootHelp = () => {
 		"",
 		"Commands:",
 		...commands,
+		`  ${"save".padEnd(12)}Commit a package an editor serialized (not an MCP tool)`,
 		`  ${"render".padEnd(12)}Render pages to PDF, PNG, or HTML`,
 		`  ${"serve".padEnd(12)}Serve a read-only live preview on 127.0.0.1`,
 		`  ${"mcp".padEnd(12)}Serve these tools over MCP on stdio`,
@@ -284,7 +291,10 @@ const execute = async ({ resolved, values, built, io }) => {
 	if (date.isErr()) return date;
 	const waived = values["no-expect-version"] === true;
 	if (waived && built.expectVersion !== void 0) return Result.err(usageError("Pass --expect-version or --no-expect-version, not both."));
+	const flushWaitMs = parseFlushWait(stringValue(values["flush-wait"]));
+	if (flushWaitMs.isErr()) return flushWaitMs;
 	return await executeWriteTool(tool, call, {
+		...flushWaitMs.value !== void 0 && { flushWaitMs: flushWaitMs.value },
 		sourcePrecondition: waived ? "waived" : "required",
 		destination: destination.value,
 		author: author.value,
@@ -427,6 +437,7 @@ const runFolioCli = async (argv, io) => {
 	if (name === "mcp") return await runMcp(rest, io);
 	if (name === "render") return await runRender(rest, io);
 	if (name === "serve") return await runServe(rest, io);
+	if (name === "save") return await runSave(rest, io);
 	const resolved = findCommand(name);
 	if (resolved === void 0) return emit({
 		io,

package/dist/document.d.ts

@@ -1,18 +1,11 @@
 import { FolioCliError } from "./errors.js";
+import { FileIdentity, NO_FOLLOW, errnoCode, fileVersionOf, sameFile } from "./file-system.js";
 import { Result } from "better-result";
 import { FolioDocxReviewer } from "@stll/folio-core/server";
 //#region src/document.d.ts
 /** Largest `.docx` the CLI opens; larger inputs are refused before reading. */
 declare const MAX_DOCUMENT_BYTES: number;
-/** A file's version: the lowercase hex SHA-256 of its bytes. */
-declare const fileVersionOf: (bytes: Uint8Array) => string;
 declare const isFileVersion: (value: unknown) => value is string;
-/** Which file a path named when it was read: device and inode. */
-type FileIdentity = {
-  dev: number;
-  ino: number;
-};
-declare const sameFile: (left: FileIdentity, right: FileIdentity) => boolean;
 /** The bytes of one input file and the version they hash to. */
 type LoadedFile = {
   /** Real path (symlinks resolved) the bytes were read from. */
@@ -23,13 +16,6 @@ type LoadedFile = {
   /** Hard links to the file; a write refuses a file with more than one. */
   links: number;
 };
-/**
- * `O_NOFOLLOW` where the platform has it: opening a path whose last
- * component is a symlink fails instead of following it.
- */
-declare const NO_FOLLOW: number;
-/** The `code` of a Node.js file-system error, when there is one. */
-declare const errnoCode: (error: unknown) => string | undefined;
 /** Read one input file, refusing directories and files over the size bound. */
 declare const readDocumentFile: (inputPath: string) => Promise<Result<LoadedFile, FolioCliError>>;
 /**
@@ -40,4 +26,4 @@ declare const openReviewer: (file: LoadedFile, author?: string) => Promise<Resul
 /** Refuse when the caller's expected version is not the file's current one. */
 declare const checkExpectedVersion: (file: LoadedFile, expected: string | undefined) => Result<void, FolioCliError>;
 //#endregion
-export { FileIdentity, LoadedFile, MAX_DOCUMENT_BYTES, NO_FOLLOW, checkExpectedVersion, errnoCode, fileVersionOf, isFileVersion, openReviewer, readDocumentFile, sameFile };
+export { type FileIdentity, LoadedFile, MAX_DOCUMENT_BYTES, NO_FOLLOW, checkExpectedVersion, errnoCode, fileVersionOf, isFileVersion, openReviewer, readDocumentFile, sameFile };

package/dist/document.js

@@ -1,6 +1,6 @@
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { NO_FOLLOW, errnoCode, fileVersionOf, sameFile } from "./file-system.js";
 import { Result } from "better-result";
-import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import { open, realpath, stat } from "node:fs/promises";
 import path from "node:path";
@@ -9,20 +9,7 @@ import { FolioDocxReviewer } from "@stll/folio-core/server";
 /** Largest `.docx` the CLI opens; larger inputs are refused before reading. */
 const MAX_DOCUMENT_BYTES = 64 * 1024 * 1024;
 const FILE_VERSION_PATTERN = /^[0-9a-f]{64}$/u;
-/** A file's version: the lowercase hex SHA-256 of its bytes. */
-const fileVersionOf = (bytes) => createHash("sha256").update(bytes).digest("hex");
 const isFileVersion = (value) => typeof value === "string" && FILE_VERSION_PATTERN.test(value);
-const sameFile = (left, right) => left.dev === right.dev && left.ino === right.ino;
-/**
-* `O_NOFOLLOW` where the platform has it: opening a path whose last
-* component is a symlink fails instead of following it.
-*/
-const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
-/** The `code` of a Node.js file-system error, when there is one. */
-const errnoCode = (error) => {
-	if (typeof error !== "object" || error === null || !("code" in error)) return;
-	return typeof error.code === "string" ? error.code : void 0;
-};
 const describeError = (error) => error instanceof Error ? error.message : String(error);
 const fileSystemError = (filePath, error) => errnoCode(error) === "ENOENT" ? cliError({
 	code: FOLIO_CLI_ERROR_CODES.notFound,

package/dist/editor-lease.d.ts

@@ -0,0 +1,114 @@
+import { FolioCliError } from "./errors.js";
+import { AcquiredLease, LockHolder } from "./lock.js";
+import { Result } from "better-result";
+//#region src/editor-lease.d.ts
+/** How long an editor's lease lasts without renewal. */
+declare const EDITOR_LEASE_MS: number;
+/** How often an editor renews its lease while it holds it. */
+declare const EDITOR_RENEW_MS: number;
+/** How long a writer waits for an editor to save and release by default. */
+declare const DEFAULT_FLUSH_WAIT_MS: number;
+/** How often a writer retries the lease, and an editor re-checks for requests. */
+declare const FLUSH_POLL_MS = 100;
+/** A writer's request that the editor holding `leaseToken` save and release. */
+type FlushRequest = {
+  id: string;
+  /** The token of the lease the writer found; an editor answers only its own. */
+  leaseToken: string;
+  /** The writer's lease owner, pid, host, and transaction. */
+  owner: string;
+  pid: number;
+  host: string;
+  txId: string;
+  requestedAt: string;
+  /** After this the writer has stopped waiting; the request is void. */
+  deadline: string;
+};
+declare const flushRequestPathFor: (documentPath: string, id: string) => string;
+/**
+ * The flush requests beside `documentPath` whose writer is still waiting.
+ * Requests past their deadline (a writer that crashed) are removed.
+ */
+declare const pendingFlushRequests: (documentPath: string, now?: Date) => Promise<FlushRequest[]>;
+/** Whether a writer waited for an editor, and what came of it. */
+type FlushOutcome =
+/** The lease was free, stale, or held by a holder that does not flush; no one was asked. */
+{
+  type: "notAsked";
+} |
+/** The holder released within the wait; `versionBefore` is the file's version when asked. */
+{
+  type: "flushed";
+  holder: LockHolder;
+  versionBefore: string | null;
+} |
+/** The holder never released; the lease was taken by the ordinary rules (stale, or `force`). */
+{
+  type: "timedOut";
+  holder: LockHolder;
+};
+type LeaseForWrite = {
+  lease: AcquiredLease;
+  flush: FlushOutcome;
+};
+type AcquireLeaseForWriteOptions = {
+  documentPath: string;
+  txId: string;
+  /** After the wait, take the lease over from a holder that did not release. */
+  force: boolean;
+  owner?: string;
+  /** How long to wait for a flush (default {@link DEFAULT_FLUSH_WAIT_MS}); 0 does not ask. */
+  flushWaitMs?: number;
+  pollMs?: number;
+};
+/**
+ * Take the lease for a write. An editor holding it with unsaved edits is
+ * asked to save and release first; see the module comment for the rules.
+ */
+declare const acquireLeaseForWrite: ({ documentPath, txId, force, owner, flushWaitMs, pollMs }: AcquireLeaseForWriteOptions) => Promise<Result<LeaseForWrite, FolioCliError>>;
+type AcquireEditorLeaseOptions = {
+  documentPath: string;
+  /** The editor's lease owner, such as `folio-vscode`. */
+  owner: string;
+  /** Recorded in the lock; generated when absent. */
+  txId?: string;
+  leaseMs?: number;
+  now?: Date;
+};
+/**
+ * Take the lease for an editor session with unsaved edits: long-lived,
+ * renewable, and answering flush requests. Refused (`locked`) while another
+ * holder has it or a writer's flush request is pending.
+ */
+declare const acquireEditorLease: ({ documentPath, owner, txId, leaseMs, now }: AcquireEditorLeaseOptions) => Promise<Result<AcquiredLease, FolioCliError>>;
+type LeaseKeeper = {
+  stop: () => void;
+};
+/**
+ * Renew `lease` every `intervalMs` until stopped. When a renewal is refused
+ * (the lease was taken over or expired), renewing stops and `onLost` runs:
+ * the editor must not save under it again.
+ */
+declare const keepEditorLeaseAlive: (lease: AcquiredLease, { intervalMs, onLost }: {
+  intervalMs?: number;
+  onLost: (error: FolioCliError) => void;
+}) => LeaseKeeper;
+type FlushWatcher = {
+  close: () => void;
+};
+type WatchFlushRequestsOptions = {
+  documentPath: string;
+  /** The editor's lease token; requests for any other lease are ignored. */
+  token: string;
+  /** Called once per request: save the unsaved edits, then release the lease. */
+  onRequest: (request: FlushRequest) => void;
+  pollMs?: number;
+};
+/**
+ * Watch for flush requests addressed to the lease `token`: a directory
+ * watch for promptness plus a poll every `pollMs`, since watch events can
+ * be dropped or unsupported (network drives).
+ */
+declare const watchFlushRequests: ({ documentPath, token, onRequest, pollMs }: WatchFlushRequestsOptions) => FlushWatcher;
+//#endregion
+export { DEFAULT_FLUSH_WAIT_MS, EDITOR_LEASE_MS, EDITOR_RENEW_MS, FLUSH_POLL_MS, FlushOutcome, FlushRequest, FlushWatcher, LeaseForWrite, LeaseKeeper, acquireEditorLease, acquireLeaseForWrite, flushRequestPathFor, keepEditorLeaseAlive, pendingFlushRequests, watchFlushRequests };

package/dist/editor-lease.js

@@ -0,0 +1,294 @@
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { fileVersionOf } from "./file-system.js";
+import { DEFAULT_LEASE_OWNER, acquireLease, readLease } from "./lock.js";
+import { readSidecarFile, writeNewSidecarFile } from "./sidecar.js";
+import { Result } from "better-result";
+import { watch } from "node:fs";
+import { readFile, readdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { setTimeout } from "node:timers/promises";
+//#region src/editor-lease.ts
+/**
+* The editor lease and the flush handshake: how a live editor (the VS Code
+* custom editor, `folio serve --edit`) and a folio write share one `.docx`
+* so that a write is never refused just because someone is typing, and the
+* user's unsaved edits are saved before the write lands on top of them.
+*
+* Files beside `<dir>/<name>.docx`, all created complete (temporary file,
+* then link or rename) and never followed through a symlink:
+*
+* - `.<name>.docx.folio-lock`: the lease (`lock.ts`). While it has unsaved
+*   edits, an editor holds it long-lived: its own `owner` (`folio-vscode`),
+*   `acceptsFlush: true`, {@link EDITOR_LEASE_MS} long, renewed every
+*   {@link EDITOR_RENEW_MS}. The pid is the editor's long-lived process, so
+*   a crashed editor's lease is stale at once on the same host and within
+*   {@link EDITOR_LEASE_MS} elsewhere.
+* - `.<name>.docx.folio-flush-<id>`: one flush request per waiting writer,
+*   JSON {@link FlushRequest} naming the lease token it asks to let go.
+*
+* A writer (a tool call, or `folio save` without the lease) calls
+* {@link acquireLeaseForWrite}. When a live `acceptsFlush` holder refuses
+* it, it writes a request, then retries the lease every
+* {@link FLUSH_POLL_MS} for up to `flushWaitMs` ({@link DEFAULT_FLUSH_WAIT_MS}).
+* Once the holder has saved and released, the writer takes the lease,
+* removes its request, and re-reads the file: its operations run on the
+* version the editor just saved (block ids and `blockTextHash`
+* preconditions decide whether they still apply). If the holder has not
+* released by the deadline, the writer removes its request and falls back
+* to the ordinary lease rules: an expired lease or one whose process exited
+* is replaced, a live one refuses with `locked` (unless `--force`). Nothing
+* is ever written under a live holder that has not released.
+*
+* The editor:
+* 1. On its first unsaved edit, {@link acquireEditorLease}; keep it with
+*    {@link keepEditorLeaseAlive}. It is refused while a writer's request is
+*    pending (the writer is between the editor's release and its own
+*    acquisition); retry after the writer's commit.
+* 2. {@link watchFlushRequests} with the lease's token. On a request, save
+*    the unsaved edits under the lease (`folio save --lease-token <token>`,
+*    or `saveDocumentBytes` with `leaseToken`), then release it.
+* 3. After a save with no edits pending, release the lease.
+* 4. When the file's version changes on disk (the writer's commit, named by
+*    the journal's newest line), reload it before accepting the next save:
+*    a save names the version it was based on and refuses a stale one.
+*/
+/** How long an editor's lease lasts without renewal. */
+const EDITOR_LEASE_MS = 30 * 1e3;
+/** How often an editor renews its lease while it holds it. */
+const EDITOR_RENEW_MS = 10 * 1e3;
+/** How long a writer waits for an editor to save and release by default. */
+const DEFAULT_FLUSH_WAIT_MS = 5 * 1e3;
+/** How often a writer retries the lease, and an editor re-checks for requests. */
+const FLUSH_POLL_MS = 100;
+const flushPrefixFor = (documentPath) => `.${path.basename(documentPath)}.folio-flush-`;
+const flushRequestPathFor = (documentPath, id) => path.join(path.dirname(documentPath), `${flushPrefixFor(documentPath)}${id}`);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const parseRequest = (text) => {
+	const parsed = Result.try(() => JSON.parse(text));
+	if (parsed.isErr() || !isRecord(parsed.value)) return null;
+	const { id, leaseToken, owner, pid, host, txId, requestedAt, deadline } = parsed.value;
+	return typeof id === "string" && typeof leaseToken === "string" && typeof owner === "string" && typeof pid === "number" && typeof host === "string" && typeof txId === "string" && typeof requestedAt === "string" && typeof deadline === "string" ? {
+		id,
+		leaseToken,
+		owner,
+		pid,
+		host,
+		txId,
+		requestedAt,
+		deadline
+	} : null;
+};
+/**
+* The flush requests beside `documentPath` whose writer is still waiting.
+* Requests past their deadline (a writer that crashed) are removed.
+*/
+const pendingFlushRequests = async (documentPath, now = /* @__PURE__ */ new Date()) => {
+	const directory = path.dirname(documentPath);
+	const prefix = flushPrefixFor(documentPath);
+	const listed = await Result.tryPromise(() => readdir(directory));
+	if (listed.isErr()) return [];
+	const pending = [];
+	for (const name of listed.value.filter((entry) => entry.startsWith(prefix))) {
+		const requestPath = path.join(directory, name);
+		const bytes = await readSidecarFile(requestPath);
+		if (bytes.isErr()) continue;
+		const request = parseRequest(new TextDecoder().decode(bytes.value));
+		if (request === null) continue;
+		if (Date.parse(request.deadline) > now.getTime()) pending.push(request);
+		else await rm(requestPath, { force: true });
+	}
+	return pending;
+};
+const placeRequest = async (documentPath, request) => {
+	const target = flushRequestPathFor(documentPath, request.id);
+	const temporary = path.join(path.dirname(documentPath), `.${path.basename(documentPath)}.folio-flush.${request.id}.tmp`);
+	const written = await writeNewSidecarFile(temporary, new TextEncoder().encode(`${JSON.stringify(request)}\n`));
+	if (written.isErr()) return Result.err(written.error);
+	if ((await Result.tryPromise(() => rename(temporary, target))).isOk()) return Result.ok();
+	await rm(temporary, { force: true });
+	return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.internal,
+		message: `Cannot write ${target}.`
+	}));
+};
+/** The file's version now, or `null` when it cannot be read. */
+const currentVersion = async (documentPath) => {
+	const bytes = await Result.tryPromise(() => readFile(documentPath));
+	return bytes.isOk() ? fileVersionOf(bytes.value) : null;
+};
+const flushableHolder = async (documentPath) => {
+	const state = await readLease(documentPath);
+	return state.type === "held" && state.holder.acceptsFlush === true ? state.holder : null;
+};
+/**
+* Take the lease for a write. An editor holding it with unsaved edits is
+* asked to save and release first; see the module comment for the rules.
+*/
+const acquireLeaseForWrite = async ({ documentPath, txId, force, owner = DEFAULT_LEASE_OWNER, flushWaitMs = DEFAULT_FLUSH_WAIT_MS, pollMs = 100 }) => {
+	const take = (takeOver) => acquireLease({
+		documentPath,
+		txId,
+		owner,
+		force: takeOver,
+		now: /* @__PURE__ */ new Date()
+	});
+	const first = await take(false);
+	if (first.isOk()) return Result.ok({
+		lease: first.value,
+		flush: { type: "notAsked" }
+	});
+	if (first.error.code !== FOLIO_CLI_ERROR_CODES.locked) return Result.err(first.error);
+	let holder = await flushableHolder(documentPath);
+	if (holder === null || flushWaitMs <= 0) {
+		if (!force) return Result.err(first.error);
+		const forced = await take(true);
+		return forced.isOk() ? Result.ok({
+			lease: forced.value,
+			flush: { type: "notAsked" }
+		}) : Result.err(forced.error);
+	}
+	const versionBefore = await currentVersion(documentPath);
+	const deadline = new Date(Date.now() + flushWaitMs);
+	const ask = (target) => ({
+		id: randomUUID(),
+		leaseToken: target.token,
+		owner,
+		pid: process.pid,
+		host: hostname(),
+		txId,
+		requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		deadline: deadline.toISOString()
+	});
+	let request = ask(holder);
+	const placed = await placeRequest(documentPath, request);
+	if (placed.isErr()) return Result.err(placed.error);
+	try {
+		while (Date.now() < deadline.getTime()) {
+			await setTimeout(Math.min(pollMs, Math.max(deadline.getTime() - Date.now(), 0)));
+			const attempt = await take(false);
+			if (attempt.isOk()) return Result.ok({
+				lease: attempt.value,
+				flush: {
+					type: "flushed",
+					holder,
+					versionBefore
+				}
+			});
+			if (attempt.error.code !== FOLIO_CLI_ERROR_CODES.locked) return Result.err(attempt.error);
+			const current = await flushableHolder(documentPath);
+			if (current !== null && current.token !== request.leaseToken) {
+				await rm(flushRequestPathFor(documentPath, request.id), { force: true });
+				holder = current;
+				request = ask(current);
+				const replaced = await placeRequest(documentPath, request);
+				if (replaced.isErr()) return Result.err(replaced.error);
+			}
+		}
+		const last = await take(force);
+		if (last.isOk()) return Result.ok({
+			lease: last.value,
+			flush: {
+				type: "timedOut",
+				holder
+			}
+		});
+		if (last.error.code !== FOLIO_CLI_ERROR_CODES.locked) return Result.err(last.error);
+		return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.locked,
+			message: `${documentPath} is held by ${holder.owner} (pid ${holder.pid} on ${holder.host}), which did not save and release it within ${String(flushWaitMs)} ms.`,
+			hint: "Save or close the document in the editor and retry, or pass --force to take the lease over.",
+			details: {
+				holder,
+				flush: "timedOut",
+				flushWaitMs
+			}
+		}));
+	} finally {
+		await rm(flushRequestPathFor(documentPath, request.id), { force: true });
+	}
+};
+/**
+* Take the lease for an editor session with unsaved edits: long-lived,
+* renewable, and answering flush requests. Refused (`locked`) while another
+* holder has it or a writer's flush request is pending.
+*/
+const acquireEditorLease = async ({ documentPath, owner, txId = `editor-${randomUUID()}`, leaseMs = EDITOR_LEASE_MS, now = /* @__PURE__ */ new Date() }) => {
+	const pending = await pendingFlushRequests(documentPath, now);
+	if (pending.length > 0) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.locked,
+		message: `A write to ${documentPath} is waiting to take the lease.`,
+		hint: "Retry after it commits, then reload the document.",
+		details: { pending }
+	}));
+	return await acquireLease({
+		documentPath,
+		txId,
+		owner,
+		leaseMs,
+		acceptsFlush: true,
+		force: false,
+		now
+	});
+};
+/**
+* Renew `lease` every `intervalMs` until stopped. When a renewal is refused
+* (the lease was taken over or expired), renewing stops and `onLost` runs:
+* the editor must not save under it again.
+*/
+const keepEditorLeaseAlive = (lease, { intervalMs = EDITOR_RENEW_MS, onLost }) => {
+	let stopped = false;
+	const renew = async () => {
+		const renewed = await lease.renew();
+		if (renewed.isErr() && !stopped) {
+			stopped = true;
+			clearInterval(timer);
+			onLost(renewed.error);
+		}
+	};
+	const timer = setInterval(() => void renew(), intervalMs);
+	timer.unref();
+	return { stop: () => {
+		stopped = true;
+		clearInterval(timer);
+	} };
+};
+/**
+* Watch for flush requests addressed to the lease `token`: a directory
+* watch for promptness plus a poll every `pollMs`, since watch events can
+* be dropped or unsupported (network drives).
+*/
+const watchFlushRequests = ({ documentPath, token, onRequest, pollMs = 100 }) => {
+	const seen = /* @__PURE__ */ new Set();
+	const prefix = flushPrefixFor(documentPath);
+	let closed = false;
+	let checking = false;
+	const check = async () => {
+		if (closed || checking) return;
+		checking = true;
+		try {
+			for (const request of await pendingFlushRequests(documentPath)) {
+				if (closed || request.leaseToken !== token || seen.has(request.id)) continue;
+				seen.add(request.id);
+				onRequest(request);
+			}
+		} finally {
+			checking = false;
+		}
+	};
+	const watcher = Result.try(() => watch(path.dirname(documentPath), (_event, name) => {
+		if (name === null || name.startsWith(prefix)) check();
+	}));
+	if (watcher.isOk()) watcher.value.on("error", () => void 0);
+	const timer = setInterval(() => void check(), pollMs);
+	timer.unref();
+	check();
+	return { close: () => {
+		closed = true;
+		clearInterval(timer);
+		if (watcher.isOk()) watcher.value.close();
+	} };
+};
+//#endregion
+export { DEFAULT_FLUSH_WAIT_MS, EDITOR_LEASE_MS, EDITOR_RENEW_MS, FLUSH_POLL_MS, acquireEditorLease, acquireLeaseForWrite, flushRequestPathFor, keepEditorLeaseAlive, pendingFlushRequests, watchFlushRequests };

package/dist/execute-read.d.ts

@@ -1,6 +1,7 @@
 import { FolioCliError } from "./errors.js";
 import { FolioFileToolSpec } from "./registry.js";
 import { Result } from "better-result";
+import { FolioDocxReviewer } from "@stll/folio-core/server";
 //#region src/execute-read.d.ts
 /** One call against one file: the envelope plus the tool's own arguments. */
 type FileToolCall = {
@@ -32,6 +33,7 @@ type FileReadData = {
  */
 type FolioBlockIdSource = "package" | "synthetic";
 type BlockIdSources = ReadonlyMap<string, FolioBlockIdSource>;
+declare const blockIdSources: (reviewer: FolioDocxReviewer) => BlockIdSources;
 type ReadCursor = {
   fileVersion: string;
   afterBlockId: string;
@@ -61,4 +63,4 @@ declare const pageReadDocument: ({ blocks, sources, fileVersion, args, bounds, p
 /** Run one read tool, or a compare without a destination. Never writes. */
 declare const executeReadTool: (tool: FolioFileToolSpec, call: FileToolCall, bounds: FolioReadBounds) => Promise<Result<FileReadData, FolioCliError>>;
 //#endregion
-export { CLI_READ_BOUNDS, FileReadData, FileToolCall, FolioBlockIdSource, FolioReadBounds, encodeReadCursor, executeReadTool, pageReadDocument };
+export { CLI_READ_BOUNDS, FileReadData, FileToolCall, FolioBlockIdSource, FolioReadBounds, blockIdSources, encodeReadCursor, executeReadTool, pageReadDocument };

package/dist/execute-read.js

@@ -217,4 +217,4 @@ const executeReadTool = async (tool, call, bounds) => {
 	}
 };
 //#endregion
-export { CLI_READ_BOUNDS, encodeReadCursor, executeReadTool, pageReadDocument };
+export { CLI_READ_BOUNDS, blockIdSources, encodeReadCursor, executeReadTool, pageReadDocument };

package/dist/execute-write.d.ts

@@ -1,4 +1,6 @@
 import { FolioCliError } from "./errors.js";
+import { FileIdentity } from "./file-system.js";
+import "./document.js";
 import { FolioFileToolSpec } from "./registry.js";
 import { FileToolCall } from "./execute-read.js";
 import { WriteDestination } from "./transaction.js";
@@ -27,10 +29,36 @@ type WriteOptions = {
   journalPath: string | undefined;
   /** For tools whose edit mode is selectable. */
   mode: FolioAIEditApplyMode;
+  /** How long to wait for an editor holding the lease to save and release (`editor-lease.ts`). */
+  flushWaitMs?: number;
 };
 /** How a transaction's bytes were produced. */
 type SaveStrategy = "selective" | "full-repack" | "redline";
+declare const TX_ID_PATTERN: RegExp;
+/** JSON with object keys sorted at every depth, for a stable request hash. */
+declare const canonicalJson: (value: unknown) => string;
+type ResolvedTarget = {
+  sourcePath: string;
+  sourceIdentity: FileIdentity;
+  destinationPath: string;
+};
+/** The `tool` an editor's whole-package save journals (`save.ts`). */
+declare const EDITOR_SAVE_TOOL = "editor_save";
+type ResolveTargetOptions = {
+  sourcePath: string;
+  destination: WriteDestination;
+  /** A redline: never in place, and never onto the revised file either. */
+  redline?: {
+    revisedPath: unknown;
+  };
+};
+/**
+ * Resolve source and destination to real paths and refuse a destination
+ * that is the input under another name (a symlink, a hard link, a
+ * case-insensitive alias): files are compared by device and inode.
+ */
+declare const resolveTarget: ({ sourcePath, destination, redline }: ResolveTargetOptions) => Promise<Result<ResolvedTarget, FolioCliError>>;
 /** Run one write tool as a transaction and return its receipt. */
 declare const executeWriteTool: (tool: FolioFileToolSpec, call: FileToolCall, options: WriteOptions) => Promise<Result<Readonly<Record<string, unknown>>, FolioCliError>>;
 //#endregion
-export { SaveStrategy, type WriteDestination, WriteOptions, executeWriteTool };
+export { EDITOR_SAVE_TOOL, SaveStrategy, TX_ID_PATTERN, type WriteDestination, WriteOptions, canonicalJson, executeWriteTool, resolveTarget };