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

package/dist/transaction.js

@@ -0,0 +1,218 @@
+import { fileVersionOf, readDocumentFile, sameFile } from "./document.js";
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { appendJournal, stagePathFor } from "./journal.js";
+import { checkPackageIntegrity } from "./package-parts.js";
+import { inspectPath, readSidecarFile, sidecarDirectory, syncDirectory, unsafePath, writeNewSidecarFile } from "./sidecar.js";
+import { Result } from "better-result";
+import { readdir, realpath, rename, rm } from "node:fs/promises";
+import path from "node:path";
+//#region src/transaction.ts
+/**
+* Commit one transaction's bytes to its destination: under the document's
+* lease, re-check the source and destination versions, stage the package
+* beside the destination, validate it, back up whatever the write replaces,
+* confirm the lease is still ours, journal the commit, and rename the stage
+* into place. Every step before the rename leaves the destination untouched.
+*/
+/** Backups kept per document. */
+const MAX_BACKUPS = 20;
+const fileSystemError = (message, error) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.internal,
+	message: `${message}: ${error instanceof Error ? error.message : String(error)}`
+});
+const BACKUP_NAME = /^[0-9a-f]{64}\.docx$/u;
+/** `.folio/backups/<document name>`, created private and never through a symlink. */
+const backupDirectoryFor = (documentPath) => sidecarDirectory(documentPath, "backups", path.basename(documentPath));
+/**
+* Keep the newest `keep` backups in one document's backup directory. Only
+* regular files named `<version>.docx` count; nothing else is touched.
+*/
+const pruneBackups = async (directory, keep) => {
+	const names = await Result.tryPromise(() => readdir(directory));
+	if (names.isErr()) return Result.err(fileSystemError(`Cannot list ${directory}`, names.error.cause));
+	const backups = [];
+	for (const name of names.value.filter((entry) => BACKUP_NAME.test(entry))) {
+		const entry = await inspectPath(path.join(directory, name));
+		if (entry.isErr()) return Result.err(entry.error);
+		if (entry.value.type === "file") backups.push({
+			name,
+			modifiedMs: entry.value.modifiedMs
+		});
+	}
+	const stale = backups.toSorted((left, right) => right.modifiedMs - left.modifiedMs || right.name.localeCompare(left.name)).slice(keep);
+	for (const { name } of stale) await rm(path.join(directory, name), { force: true });
+	return Result.ok();
+};
+/**
+* Write the bytes a transaction replaces to
+* `.folio/backups/<document name>/<version>.docx`, flushed with its
+* directory. A backup of the same version already there is kept when it
+* holds those bytes.
+*/
+const backUp = async ({ documentPath, version, bytes }) => {
+	const directory = await backupDirectoryFor(documentPath);
+	if (directory.isErr()) return Result.err(directory.error);
+	const backupPath = path.join(directory.value, `${version}.docx`);
+	const existing = await inspectPath(backupPath);
+	if (existing.isErr()) return Result.err(existing.error);
+	if (existing.value.type !== "missing") {
+		const kept = await readSidecarFile(backupPath);
+		if (kept.isErr()) return Result.err(kept.error);
+		if (fileVersionOf(kept.value) !== version) return Result.err(unsafePath(`${backupPath} does not hold the version its name says.`));
+	} else {
+		const written = await writeNewSidecarFile(backupPath, bytes);
+		if (written.isErr()) return Result.err(written.error);
+		const synced = await syncDirectory(directory.value);
+		if (synced.isErr()) return Result.err(synced.error);
+	}
+	const pruned = await pruneBackups(directory.value, 20);
+	return pruned.isErr() ? Result.err(pruned.error) : Result.ok(backupPath);
+};
+/** The destination as it is now: missing, or a regular single-link file read without following a symlink. */
+const readDestination = async (destinationPath) => {
+	const entry = await inspectPath(destinationPath);
+	if (entry.isErr()) return Result.err(entry.error);
+	if (entry.value.type === "missing") return Result.ok({ type: "missing" });
+	if (entry.value.type !== "file" || entry.value.links !== 1) return Result.err(unsafePath(`${destinationPath} is not a regular file with a single link; folio does not replace it.`));
+	const bytes = await readSidecarFile(destinationPath);
+	if (bytes.isErr()) return Result.err(bytes.error);
+	return Result.ok({
+		type: "file",
+		identity: entry.value.identity,
+		version: fileVersionOf(bytes.value),
+		bytes: bytes.value
+	});
+};
+const staleError = (message, expected, actual) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.staleVersion,
+	message,
+	hint: "Re-read the document and retry against its current fileVersion.",
+	details: {
+		expected,
+		actual
+	}
+});
+/** The replaced destination must be exactly the version the caller named. */
+const checkDestination = (request, existing) => {
+	const { destination, destinationPath } = request;
+	if (destination.type === "inPlace" || existing.type === "missing") return destination.type === "file" && destination.expectedVersion !== void 0 ? Result.err(staleError(`${destinationPath} does not exist, but a destination version was expected.`, destination.expectedVersion, null)) : Result.ok();
+	if (!destination.overwrite) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.destinationExists,
+		message: `${destinationPath} already exists.`,
+		hint: "Pass --overwrite with --expect-destination-version to replace it, or choose another -o path."
+	}));
+	if (destination.expectedVersion === void 0) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.invalidInput,
+		message: `Replacing ${destinationPath} needs its current fileVersion.`,
+		hint: "Read it (folio read) and pass --expect-destination-version (MCP: expectedDestinationVersion)."
+	}));
+	return destination.expectedVersion === existing.version ? Result.ok() : Result.err(staleError(`${destinationPath} changed since it was read; nothing was written.`, destination.expectedVersion, existing.version));
+};
+const sameEntry = (entry, identity) => entry.type === "file" && entry.links === 1 && sameFile(entry.identity, identity);
+/**
+* Just before the rename: the directory still resolves where it did, the
+* stage is still the file written, and the destination is still the file
+* checked (or still absent).
+*/
+const checkBeforeRename = async (guard) => {
+	const parent = await Result.tryPromise(() => realpath(path.dirname(guard.destinationPath)));
+	if (parent.isErr() || parent.value !== guard.parentRealPath) return Result.err(unsafePath(`${path.dirname(guard.destinationPath)} moved during the write.`));
+	const stage = await inspectPath(guard.stagePath);
+	if (stage.isErr()) return Result.err(stage.error);
+	if (!sameEntry(stage.value, guard.stageIdentity)) return Result.err(unsafePath(`${guard.stagePath} was replaced during the write.`));
+	const destination = await inspectPath(guard.destinationPath);
+	if (destination.isErr()) return Result.err(destination.error);
+	return (guard.existing.type === "missing" ? destination.value.type === "missing" : sameEntry(destination.value, guard.existing.identity)) ? Result.ok() : Result.err(unsafePath(`${guard.destinationPath} was replaced during the write.`));
+};
+/**
+* Commit under a lease the caller already holds. Refuses when the source
+* changed since it was read, when a new destination already exists, or when
+* an existing destination is not the version the caller named.
+*/
+const commitTransaction = async (request) => {
+	const { txId, destinationPath, sourcePath, fromVersion, bytes } = request;
+	const source = await readDocumentFile(sourcePath);
+	const sourceVersion = source.isOk() ? source.value.fileVersion : null;
+	if (sourceVersion !== fromVersion || !source.isOk() || !sameFile(source.value.identity, request.sourceIdentity)) return Result.err(staleError(`${sourcePath} changed while this transaction ran; nothing was written.`, fromVersion, sourceVersion));
+	const existing = await readDestination(destinationPath);
+	if (existing.isErr()) return Result.err(existing.error);
+	const destinationChecked = checkDestination(request, existing.value);
+	if (destinationChecked.isErr()) return Result.err(destinationChecked.error);
+	const destinationVersionBefore = existing.value.type === "file" ? existing.value.version : null;
+	const parentRealPath = await Result.tryPromise(() => realpath(path.dirname(destinationPath)));
+	if (parentRealPath.isErr()) return Result.err(fileSystemError(`Cannot resolve ${destinationPath}`, parentRealPath.error.cause));
+	const stagePath = stagePathFor(destinationPath, txId);
+	const staged = await writeNewSidecarFile(stagePath, bytes);
+	if (staged.isErr()) return Result.err(staged.error);
+	const discardStage = async (error) => {
+		await rm(stagePath, { force: true });
+		return Result.err(error);
+	};
+	const valid = await checkPackageIntegrity(bytes, request.changedParts);
+	if (valid.isErr()) return await discardStage(valid.error);
+	let backup;
+	if (existing.value.type === "file") {
+		const backedUp = await backUp({
+			documentPath: destinationPath,
+			version: existing.value.version,
+			bytes: existing.value.bytes
+		});
+		if (backedUp.isErr()) return await discardStage(backedUp.error);
+		backup = backedUp.value;
+	}
+	const stillOurs = await request.verifyLease();
+	if (stillOurs.isErr()) return await discardStage(stillOurs.error);
+	const toVersion = fileVersionOf(bytes);
+	const receipt = {
+		...request.receipt,
+		fileVersion: toVersion,
+		...backup !== void 0 && { backup }
+	};
+	const journaled = await appendJournal(request.journalPath, {
+		type: "commit",
+		...request.entry,
+		path: destinationPath,
+		toVersion,
+		destinationVersionBefore,
+		stage: path.basename(stagePath),
+		receipt
+	});
+	if (journaled.isErr()) return await discardStage(journaled.error);
+	const abandon = async (reason, error) => {
+		await rm(stagePath, { force: true });
+		const recorded = await appendJournal(request.journalPath, {
+			type: "recovery",
+			txId,
+			path: destinationPath,
+			time: request.entry.time,
+			action: "discarded",
+			reason
+		});
+		return Result.err(recorded.isErr() ? recorded.error : error);
+	};
+	const fenced = await request.verifyLease();
+	if (fenced.isErr()) return await abandon("leaseLost", fenced.error);
+	const guarded = await checkBeforeRename({
+		parentRealPath: parentRealPath.value,
+		stagePath,
+		stageIdentity: staged.value,
+		destinationPath,
+		existing: existing.value
+	});
+	if (guarded.isErr()) return await abandon("renameRefused", guarded.error);
+	const renamed = await Result.tryPromise(() => rename(stagePath, destinationPath));
+	if (renamed.isErr()) return Result.err(fileSystemError(`Cannot move the staged package into ${destinationPath}`, renamed.error.cause));
+	const synced = await syncDirectory(path.dirname(destinationPath));
+	if (synced.isErr()) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.internal,
+		message: `${destinationPath} was replaced, but its directory could not be flushed to disk: ${synced.error.message}`,
+		details: { receipt }
+	}));
+	return Result.ok({
+		toVersion,
+		backup,
+		receipt
+	});
+};
+//#endregion
+export { MAX_BACKUPS, backupDirectoryFor, commitTransaction, pruneBackups };

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "@stll/folio-cli",
-  "version": "0.0.1-placeholder.0",
-  "description": "Placeholder to bootstrap npm trusted publishing. Real releases are published from stella/folio via GitHub Actions.",
-  "license": "Apache-2.0"
+  "version": "0.1.1",
+  "description": "Command line and stdio MCP server for reading, reviewing, and redlining .docx files with folio: tracked-change edits, comments, and comparisons written atomically with version preconditions.",
+  "keywords": [
+    "cli",
+    "docx",
+    "mcp",
+    "ooxml",
+    "redline",
+    "tracked-changes",
+    "word"
+  ],
+  "homepage": "https://github.com/stella/folio",
+  "bugs": {
+    "url": "https://github.com/stella/folio/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "STLL",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stella/folio.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "folio": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./src/bin.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsdown",
+    "prepack": "bun run build",
+    "pack:dry-run": "bun pm pack --dry-run",
+    "typecheck": "bun ../../scripts/tsc-native.ts --noEmit -p tsconfig.build.json",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@fontsource/arimo": "^5.2.8",
+    "@fontsource/caladea": "^5.2.8",
+    "@fontsource/carlito": "^5.2.8",
+    "@fontsource/cousine": "^5.2.7",
+    "@fontsource/lato": "^5.2.7",
+    "@fontsource/noto-sans-arabic": "^5.2.7",
+    "@fontsource/source-sans-3": "^5.2.9",
+    "@fontsource/tinos": "^5.2.7",
+    "@modelcontextprotocol/server": "2.0.0",
+    "@stll/folio-agents": "^0.14.0",
+    "@stll/folio-core": "^0.50.0",
+    "better-result": "3.0.1",
+    "fast-xml-parser": "^5.10.1",
+    "jszip": "3.10.1"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
+    "playwright-core": "1.61.1"
+  },
+  "peerDependencies": {
+    "playwright-core": ">=1.50.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/cli.js",
+  "types": "./dist/cli.d.ts"
 }