@stll/folio-cli 0.0.1-placeholder.0 → 0.1.0

package/dist/journal.js

@@ -0,0 +1,212 @@
+import { errnoCode, fileVersionOf, sameFile } from "./document.js";
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { checkPackageIntegrity } from "./package-parts.js";
+import { SIDECAR_DIRECTORY, ensureSidecarParent, inspectPath, openSidecarFile, readSidecarFile, syncDirectory } from "./sidecar.js";
+import { Result } from "better-result";
+import { constants } from "node:fs";
+import { readdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+//#region src/journal.ts
+/**
+* The transaction journal: `.folio/journal.jsonl` beside the document (or
+* `--journal`), one JSON line per committed transaction plus one per crash
+* recovery. A `commit` line is written, and synced, after the staged package
+* validates and before it is renamed into place, so the line is the commit
+* point: a stage left behind by a crash is rolled forward when its line
+* names this document, the stage is the validated package it recorded, and
+* the destination is still what the transaction replaced. Anything else is
+* discarded. The journal, like every sidecar file, is never read or written
+* through a symlink or a hard link.
+*/
+const RECOVERY_DISCARD_REASONS = [
+	"notJournaled",
+	"otherDocument",
+	"notRegularFile",
+	"stageChanged",
+	"invalidPackage",
+	"destinationMoved",
+	"leaseLost",
+	"renameRefused"
+];
+const journalPathFor = (documentPath, override) => override === void 0 ? path.join(path.dirname(documentPath), SIDECAR_DIRECTORY, "journal.jsonl") : path.resolve(override);
+const journalError = (message, error) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.internal,
+	message: `${message}: ${error instanceof Error ? error.message : String(error)}`
+});
+/** Append one line and sync it to disk before returning. */
+const appendJournal = async (journalPath, entry) => {
+	const parent = await ensureSidecarParent(journalPath);
+	if (parent.isErr()) return Result.err(parent.error);
+	const opened = await openSidecarFile(journalPath, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT);
+	if (opened.isErr()) return Result.err(opened.error);
+	const { handle } = opened.value;
+	const written = await Result.tryPromise(async () => {
+		try {
+			await handle.writeFile(`${JSON.stringify(entry)}\n`);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	});
+	if (written.isErr()) return Result.err(journalError(`Cannot append to ${journalPath}`, written.error.cause));
+	return await syncDirectory(path.dirname(journalPath));
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const parseCommit = (line) => {
+	const parsed = Result.try(() => JSON.parse(line));
+	if (parsed.isErr() || !isRecord(parsed.value)) return null;
+	const { type, txId, path: committedPath, requestHash, toVersion, destinationVersionBefore, receipt } = parsed.value;
+	return type === "commit" && typeof txId === "string" && typeof committedPath === "string" && typeof requestHash === "string" && typeof toVersion === "string" && (typeof destinationVersionBefore === "string" || destinationVersionBefore === null) && isRecord(receipt) ? {
+		txId,
+		path: committedPath,
+		requestHash,
+		toVersion,
+		destinationVersionBefore,
+		receipt
+	} : null;
+};
+const isDiscardRecord = (line, txId) => {
+	const parsed = Result.try(() => JSON.parse(line));
+	return parsed.isOk() && isRecord(parsed.value) && parsed.value["type"] === "recovery" && parsed.value["txId"] === txId && parsed.value["action"] === "discarded";
+};
+/**
+* The committed transaction with `txId`, if the journal has one and recovery
+* did not discard it. Torn or foreign lines (a crash mid-append) are skipped.
+* A journal (or `.folio`) that is a symlink or hard link is refused.
+*/
+const findCommit = async (journalPath, txId) => {
+	const journal = await inspectPath(journalPath);
+	if (journal.isErr()) return Result.err(journal.error);
+	if (journal.value.type === "missing") {
+		const parent = await inspectPath(path.dirname(journalPath));
+		if (parent.isErr()) return Result.err(parent.error);
+		return parent.value.type === "missing" || parent.value.type === "directory" ? Result.ok(void 0) : Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.unsafePath,
+			message: `${path.dirname(journalPath)} is not a plain directory.`
+		}));
+	}
+	const parent = await ensureSidecarParent(journalPath);
+	if (parent.isErr()) return Result.err(parent.error);
+	const bytes = await readSidecarFile(journalPath);
+	if (bytes.isErr()) return Result.err(bytes.error);
+	let found;
+	for (const line of new TextDecoder().decode(bytes.value).split("\n")) {
+		if (!line.includes(txId)) continue;
+		if (isDiscardRecord(line, txId)) return Result.ok(void 0);
+		const commit = parseCommit(line);
+		if (commit?.txId === txId) found ??= commit;
+	}
+	return Result.ok(found);
+};
+const stagePrefixFor = (documentPath) => `.${path.basename(documentPath)}.folio-stage-`;
+const stagePathFor = (documentPath, txId) => path.join(path.dirname(documentPath), `${stagePrefixFor(documentPath)}${txId}`);
+/** The destination's current version, read without following a symlink; `null` when missing. */
+const destinationVersion = async (documentPath) => {
+	const entry = await inspectPath(documentPath);
+	if (entry.isErr()) return Result.err(entry.error);
+	if (entry.value.type === "missing") return Result.ok(null);
+	const bytes = await readSidecarFile(documentPath);
+	return bytes.isErr() ? Result.err(bytes.error) : Result.ok(fileVersionOf(bytes.value));
+};
+/**
+* Whether a journaled stage may complete its rename: its line names this
+* document, it is a regular single-link file (a symlink is never followed),
+* its bytes are the version the line recorded and still parse as a package,
+* and the destination is still what the transaction replaced.
+*/
+const judgeStage = async ({ documentPath, stagePath, commit }) => {
+	if (commit.path !== documentPath) return Result.ok({
+		type: "discard",
+		reason: "otherDocument"
+	});
+	const entry = await inspectPath(stagePath);
+	if (entry.isErr()) return Result.err(entry.error);
+	if (entry.value.type !== "file" || entry.value.links !== 1) return Result.ok({
+		type: "discard",
+		reason: "notRegularFile"
+	});
+	const opened = await openSidecarFile(stagePath, constants.O_RDONLY);
+	if (opened.isErr()) return Result.ok({
+		type: "discard",
+		reason: "notRegularFile"
+	});
+	const { handle, identity } = opened.value;
+	const read = await Result.tryPromise(async () => new Uint8Array(await handle.readFile()));
+	await handle.close();
+	if (read.isErr() || !sameFile(identity, entry.value.identity)) return Result.ok({
+		type: "discard",
+		reason: "stageChanged"
+	});
+	if (fileVersionOf(read.value) !== commit.toVersion) return Result.ok({
+		type: "discard",
+		reason: "stageChanged"
+	});
+	if ((await checkPackageIntegrity(read.value, [])).isErr()) return Result.ok({
+		type: "discard",
+		reason: "invalidPackage"
+	});
+	const current = await destinationVersion(documentPath);
+	if (current.isErr()) return Result.err(current.error);
+	return current.value === commit.destinationVersionBefore ? Result.ok({ type: "rollForward" }) : Result.ok({
+		type: "discard",
+		reason: "destinationMoved"
+	});
+};
+/**
+* Settle every stage a crashed transaction left beside `documentPath`. The
+* caller holds the document's lease, so no live transaction owns a stage.
+* Removing a discarded stage unlinks the name only; a symlink's target is
+* never touched.
+*/
+const recoverStages = async ({ documentPath, journalPath, now }) => {
+	const directory = path.dirname(documentPath);
+	const prefix = stagePrefixFor(documentPath);
+	const listed = await Result.tryPromise(() => readdir(directory));
+	if (listed.isErr()) return errnoCode(listed.error.cause) === "ENOENT" ? Result.ok([]) : Result.err(journalError(`Cannot list ${directory}`, listed.error.cause));
+	const actions = [];
+	for (const stage of listed.value.filter((name) => name.startsWith(prefix))) {
+		const txId = stage.slice(prefix.length);
+		const stagePath = path.join(directory, stage);
+		const commit = await findCommit(journalPath, txId);
+		if (commit.isErr()) return Result.err(commit.error);
+		if (commit.value === void 0) {
+			await rm(stagePath, { force: true });
+			continue;
+		}
+		const verdict = await judgeStage({
+			documentPath,
+			stagePath,
+			commit: commit.value
+		});
+		if (verdict.isErr()) return Result.err(verdict.error);
+		let action;
+		if (verdict.value.type === "rollForward") {
+			const renamed = await Result.tryPromise(() => rename(stagePath, documentPath));
+			if (renamed.isErr()) return Result.err(journalError(`Cannot complete ${stage}`, renamed.error.cause));
+			const synced = await syncDirectory(directory);
+			if (synced.isErr()) return Result.err(synced.error);
+			action = {
+				txId,
+				action: "rolledForward"
+			};
+		} else {
+			await rm(stagePath, { force: true });
+			action = {
+				txId,
+				action: "discarded",
+				reason: verdict.value.reason
+			};
+		}
+		const recorded = await appendJournal(journalPath, {
+			type: "recovery",
+			path: documentPath,
+			time: now,
+			...action
+		});
+		if (recorded.isErr()) return Result.err(recorded.error);
+		actions.push(action);
+	}
+	return Result.ok(actions);
+};
+//#endregion
+export { RECOVERY_DISCARD_REASONS, appendJournal, findCommit, journalPathFor, recoverStages, stagePathFor, stagePrefixFor };

package/dist/lock.d.ts

@@ -0,0 +1,55 @@
+import { FolioCliError } from "./errors.js";
+import { Result } from "better-result";
+//#region src/lock.d.ts
+/** How long a command-line transaction's lease lasts without renewal. */
+declare const TRANSACTION_LEASE_MS: number;
+type LockHolder = {
+  owner: string;
+  pid: number;
+  host: string;
+  txId: string;
+  /** Random per acquisition; the fencing check compares it. */
+  token: string;
+  acquiredAt: string;
+  expiresAt: string;
+};
+declare const lockPathFor: (documentPath: string) => string;
+/** What is beside the document: no lock, or a lock with its parsed holder when it has one. */
+type LeaseState = {
+  type: "free";
+} | {
+  type: "held";
+  holder: LockHolder;
+  modifiedMs: number;
+} | {
+  type: "unreadable";
+  modifiedMs: number;
+};
+/**
+ * Whether a lock no longer protects anything. One that cannot be read is
+ * held until it is older than a whole lease, so a lock another process is
+ * writing is never taken for abandoned.
+ */
+declare const isStaleLease: (state: LeaseState, now: Date) => boolean;
+/** The lease currently beside `documentPath`. A symlinked lock reads as unreadable. */
+declare const readLease: (documentPath: string) => Promise<LeaseState>;
+type AcquiredLease = {
+  holder: LockHolder;
+  /** Refuse unless the lock still carries this lease's token. */
+  verify: () => Promise<Result<void, FolioCliError>>;
+  release: () => Promise<void>;
+};
+type AcquireLeaseOptions = {
+  documentPath: string;
+  txId: string;
+  /** Take the lease over even when another live holder has it. */
+  force: boolean;
+  now?: Date;
+};
+/**
+ * Take the lease for one transaction. A stale lease is replaced; a live or
+ * unreadable one refuses with `locked` unless `force`.
+ */
+declare const acquireLease: ({ documentPath, txId, force, now }: AcquireLeaseOptions) => Promise<Result<AcquiredLease, FolioCliError>>;
+//#endregion
+export { AcquiredLease, LeaseState, LockHolder, TRANSACTION_LEASE_MS, acquireLease, isStaleLease, lockPathFor, readLease };

package/dist/lock.js

@@ -0,0 +1,157 @@
+import { errnoCode } from "./document.js";
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { inspectPath, readSidecarFile, writeNewSidecarFile } from "./sidecar.js";
+import { Result } from "better-result";
+import { randomUUID } from "node:crypto";
+import { link, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { hostname } from "node:os";
+//#region src/lock.ts
+/**
+* Cooperative write lease: `.<name>.folio-lock` beside the document, holding
+* the owner's pid, host, expiry, and a random token. A folio write takes it
+* for the whole transaction and checks, just before it journals and renames,
+* that the lock still carries its token; a writer whose lease was taken over
+* stops there. A long-lived holder (an editor session) renews it.
+*
+* The lock appears complete or not at all: it is written to a private
+* temporary file and hard-linked into place, which fails when a lock exists.
+* A lease is stale once it expires or, on the same host, once its process has
+* exited. A lock that cannot be parsed is treated as held until it is older
+* than a lease. Reads never consult it.
+*/
+/** How long a command-line transaction's lease lasts without renewal. */
+const TRANSACTION_LEASE_MS = 300 * 1e3;
+const lockPathFor = (documentPath) => path.join(path.dirname(documentPath), `.${path.basename(documentPath)}.folio-lock`);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const parseHolder = (text) => {
+	const parsed = Result.try(() => JSON.parse(text));
+	if (parsed.isErr() || !isRecord(parsed.value)) return null;
+	const { owner, pid, host, txId, token, acquiredAt, expiresAt } = parsed.value;
+	return typeof owner === "string" && typeof pid === "number" && typeof host === "string" && typeof txId === "string" && typeof token === "string" && typeof acquiredAt === "string" && typeof expiresAt === "string" ? {
+		owner,
+		pid,
+		host,
+		txId,
+		token,
+		acquiredAt,
+		expiresAt
+	} : null;
+};
+const processIsAlive = (pid) => {
+	const probe = Result.try(() => process.kill(pid, 0));
+	return probe.isOk() || errnoCode(probe.error.cause) === "EPERM";
+};
+/**
+* Whether a lock no longer protects anything. One that cannot be read is
+* held until it is older than a whole lease, so a lock another process is
+* writing is never taken for abandoned.
+*/
+const isStaleLease = (state, now) => {
+	switch (state.type) {
+		case "free": return true;
+		case "unreadable": return state.modifiedMs + TRANSACTION_LEASE_MS <= now.getTime();
+		case "held": {
+			const expires = Date.parse(state.holder.expiresAt);
+			if (Number.isNaN(expires) || expires <= now.getTime()) return true;
+			return state.holder.host === hostname() && !processIsAlive(state.holder.pid);
+		}
+		default: return state;
+	}
+};
+/** The lease currently beside `documentPath`. A symlinked lock reads as unreadable. */
+const readLease = async (documentPath) => {
+	const lockPath = lockPathFor(documentPath);
+	const entry = await inspectPath(lockPath);
+	if (entry.isErr()) return {
+		type: "unreadable",
+		modifiedMs: Date.now()
+	};
+	if (entry.value.type === "missing") return { type: "free" };
+	const modifiedMs = entry.value.type === "file" ? entry.value.modifiedMs : Date.now();
+	const bytes = await readSidecarFile(lockPath);
+	const holder = bytes.isOk() ? parseHolder(new TextDecoder().decode(bytes.value)) : null;
+	return holder === null ? {
+		type: "unreadable",
+		modifiedMs
+	} : {
+		type: "held",
+		holder,
+		modifiedMs
+	};
+};
+const lockedError = (documentPath, state) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.locked,
+	message: `${documentPath} is being written by another process${state.type === "held" ? ` (${state.holder.owner}, pid ${state.holder.pid} on ${state.holder.host})` : ""}.`,
+	hint: "Retry after it finishes, or pass --force to take the lease over.",
+	details: state.type === "held" ? { holder: state.holder } : void 0
+});
+const fileSystemError = (message, error) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.internal,
+	message: `${message}: ${error instanceof Error ? error.message : String(error)}`
+});
+/**
+* Put a complete lock in place: write it to a private temporary file, then
+* `link` it to the lock path (fails when one exists) or, taking over,
+* `rename` it there. The lock path never names a partly written file.
+*/
+const placeLock = async (lockPath, contents, mode) => {
+	const temporary = `${lockPath}.${randomUUID()}.tmp`;
+	const written = await writeNewSidecarFile(temporary, contents);
+	if (written.isErr()) return Result.err(written.error);
+	try {
+		const placed = await Result.tryPromise(() => mode === "create" ? link(temporary, lockPath) : rename(temporary, lockPath));
+		if (placed.isOk()) return Result.ok({ type: "placed" });
+		return errnoCode(placed.error.cause) === "EEXIST" ? Result.ok({ type: "exists" }) : Result.err(fileSystemError(`Cannot create ${lockPath}`, placed.error.cause));
+	} finally {
+		await rm(temporary, { force: true });
+	}
+};
+/**
+* Take the lease for one transaction. A stale lease is replaced; a live or
+* unreadable one refuses with `locked` unless `force`.
+*/
+const acquireLease = async ({ documentPath, txId, force, now = /* @__PURE__ */ new Date() }) => {
+	const lockPath = lockPathFor(documentPath);
+	const holder = {
+		owner: "folio-cli",
+		pid: process.pid,
+		host: hostname(),
+		txId,
+		token: randomUUID(),
+		acquiredAt: now.toISOString(),
+		expiresAt: new Date(now.getTime() + TRANSACTION_LEASE_MS).toISOString()
+	};
+	const contents = new TextEncoder().encode(`${JSON.stringify(holder)}\n`);
+	const holds = async () => {
+		const current = await readLease(documentPath);
+		return current.type === "held" && current.holder.token === holder.token;
+	};
+	const lease = {
+		holder,
+		verify: async () => await holds() ? Result.ok() : Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.locked,
+			message: `Another process took over the write lease on ${documentPath}; nothing was written.`,
+			hint: "Re-read the document and retry."
+		})),
+		release: async () => {
+			if (await holds()) await rm(lockPath, { force: true });
+		}
+	};
+	for (let attempt = 0; attempt < 2; attempt++) {
+		const placed = await placeLock(lockPath, contents, "create");
+		if (placed.isErr()) return Result.err(placed.error);
+		if (placed.value.type === "placed") return Result.ok(lease);
+		const existing = await readLease(documentPath);
+		if (force) {
+			const replaced = await placeLock(lockPath, contents, "replace");
+			if (replaced.isErr()) return Result.err(replaced.error);
+			return Result.ok(lease);
+		}
+		if (!isStaleLease(existing, now)) return Result.err(lockedError(documentPath, existing));
+		await rm(lockPath, { force: true });
+	}
+	return Result.err(lockedError(documentPath, { type: "free" }));
+};
+//#endregion
+export { TRANSACTION_LEASE_MS, acquireLease, isStaleLease, lockPathFor, readLease };

package/dist/mcp.d.ts

@@ -0,0 +1,28 @@
+import { FolioFileToolSpec, JsonObjectSchema } from "./registry.js";
+import { FolioReadBounds } from "./execute-read.js";
+import { AllowedRoots } from "./roots.js";
+import { Readable, Writable } from "node:stream";
+import { Server, Tool } from "@modelcontextprotocol/server";
+//#region src/mcp.d.ts
+/** Limits on what one MCP tool call returns. */
+declare const MCP_READ_BOUNDS: FolioReadBounds;
+type FolioMcpServerOptions = {
+  roots: AllowedRoots;
+  /** Author for every change; `undefined` refuses writes with `author_required`. */
+  author: string | undefined;
+  bounds?: FolioReadBounds;
+  now?: () => Date;
+};
+/** The tool's MCP input schema: its own arguments plus the file envelope. */
+declare const mcpInputSchema: (tool: FolioFileToolSpec) => JsonObjectSchema;
+declare const listMcpTools: () => Tool[];
+/** A low-level MCP server exposing the file tools; connect it to a transport. */
+declare const createFolioMcpServer: (options: FolioMcpServerOptions) => Server;
+type ServeOptions = FolioMcpServerOptions & {
+  input: Readable;
+  output: Writable;
+};
+/** Serve the file tools over stdio until the client disconnects. */
+declare const serveFolioMcp: ({ input, output, ...options }: ServeOptions) => Promise<void>;
+//#endregion
+export { FolioMcpServerOptions, MCP_READ_BOUNDS, createFolioMcpServer, listMcpTools, mcpInputSchema, serveFolioMcp };