@jini-ai/platform 0.5.8 → 0.5.9

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # @jini-ai/platform
 
+## 0.5.9 — 2026-10-16
+
+- `fs`: best-effort directory fsync, so Windows site creation stops failing with EPERM (87720117).
+- `./web` fetch default window is 20,000 characters so one result fits an MCP budget (939300e3).
+
 ## 0.5.8 — 2026-10-15
 
 - SECURITY: the guarded HTTP client forwards only `accept`, `accept-language` and `user-agent` on a cross-origin redirect (4de69b67). It used to strip only Authorization/Cookie, so custom credential headers (`x-api-key`, `X-Shopify-Access-Token`, …) followed a redirect to another origin. Same-origin hops keep all headers.

package/dist/fs/atomic-write.d.ts

@@ -72,10 +72,33 @@ export interface AtomicWriteOptions {
 export declare function createNodeAtomicFilesystem(_required: Record<string, never>, { filesystem }?: {
     filesystem?: AtomicNativeFilesystem;
 }): AtomicFilesystemPort;
+/** Flush directory metadata where supported; Windows cannot fsync directory handles.
+ * Unsupported open/sync errors are ignored because replacement has already landed.
+ * Other failures propagate, and an opened descriptor is always closed.
+ * @complexity O(1) filesystem calls and space.
+ */
+export declare function syncDirectoryBestEffort({ directory, open, sync, close }: {
+    directory: string;
+    open: (path: string, flags: "r") => number;
+    sync: (descriptor: number) => void;
+    close: (descriptor: number) => void;
+}, { platform }: {
+    platform: NodeJS.Platform;
+}): void;
+/** Async directory flush with the same unsupported-error and handle-ownership contract.
+ * @complexity O(1) filesystem calls and space.
+ */
+export declare function syncDirectoryBestEffortAsync({ directory, open }: {
+    directory: string;
+    open: (path: string, flags: "r") => Promise<Pick<fsPromises.FileHandle, "sync" | "close">>;
+}, { platform }: {
+    platform: NodeJS.Platform;
+}): Promise<void>;
 /** Same-directory rename; preserve existing mode exactly, default new files to 0600.
  * Only ENOENT means absent. Stat/write/chmod failures propagate before any rename.
- * Flush file bytes before rename so metadata cannot precede content; then flush the parent dir.
- * A directory-sync failure is reported after replacement, because rename cannot be rolled back safely.
+ * Flush file bytes before rename so metadata cannot precede content; directory flush is best-effort:
+ * skip Windows and ignore unsupported-code failures (EPERM/EISDIR/EINVAL/EACCES/ENOTSUP).
+ * Other directory-flush failures are reported after replacement, because rename cannot be rolled back safely.
  */
 export declare function writeFileAtomic(required: AtomicWriteRequired, options?: AtomicWriteOptions): void;
 /** Pretty JSON delegates to the same mode-preserving atomic primitive. */

package/dist/fs/atomic-write.js

@@ -42,18 +42,65 @@ function assertNotSymlink(info, options) {
     if (info.isSymbolicLink())
         throw new Error((options.messages ?? defaultPlatformMessages).atomicSymlinkRefused());
 }
-function assertOwnerOnly(mode, options) {
+function assertOwnerOnly(mode, options, platform) {
     // Windows has no POSIX group/other bits; secret stores skip this verification there.
-    if (options.verifyOwnerOnly && (options.platform ?? process.platform) !== "win32" && (mode & 0o077) !== 0)
+    if (options.verifyOwnerOnly && platform !== "win32" && (mode & 0o077) !== 0)
         throw new Error((options.messages ?? defaultPlatformMessages).atomicPermissionsRefused());
 }
+function isDirectorySyncUnsupported(error) {
+    return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && ["EPERM", "EISDIR", "EINVAL", "EACCES", "ENOTSUP"].includes(error.code);
+}
+/** Flush directory metadata where supported; Windows cannot fsync directory handles.
+ * Unsupported open/sync errors are ignored because replacement has already landed.
+ * Other failures propagate, and an opened descriptor is always closed.
+ * @complexity O(1) filesystem calls and space.
+ */
+export function syncDirectoryBestEffort({ directory, open, sync, close }, { platform }) {
+    if (platform === "win32")
+        return;
+    let descriptor;
+    try {
+        descriptor = open(directory, "r");
+        sync(descriptor);
+    }
+    catch (error) {
+        if (!isDirectorySyncUnsupported(error))
+            throw error;
+    }
+    finally {
+        if (descriptor !== undefined)
+            close(descriptor);
+    }
+}
+/** Async directory flush with the same unsupported-error and handle-ownership contract.
+ * @complexity O(1) filesystem calls and space.
+ */
+export async function syncDirectoryBestEffortAsync({ directory, open }, { platform }) {
+    if (platform === "win32")
+        return;
+    let handle;
+    try {
+        handle = await open(directory, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        if (!isDirectorySyncUnsupported(error))
+            throw error;
+    }
+    finally {
+        if (handle !== undefined)
+            await handle.close();
+    }
+}
 /** Same-directory rename; preserve existing mode exactly, default new files to 0600.
  * Only ENOENT means absent. Stat/write/chmod failures propagate before any rename.
- * Flush file bytes before rename so metadata cannot precede content; then flush the parent dir.
- * A directory-sync failure is reported after replacement, because rename cannot be rolled back safely.
+ * Flush file bytes before rename so metadata cannot precede content; directory flush is best-effort:
+ * skip Windows and ignore unsupported-code failures (EPERM/EISDIR/EINVAL/EACCES/ENOTSUP).
+ * Other directory-flush failures are reported after replacement, because rename cannot be rolled back safely.
  */
 export function writeFileAtomic(required, options = {}) {
     const { filePath, content, fs: filesystem } = required;
+    const platform = options.platform ?? process.platform;
     let existingMode;
     try {
         if (options.refuseSymlink) {
@@ -77,7 +124,7 @@ export function writeFileAtomic(required, options = {}) {
     try {
         filesystem.write({ descriptor, content });
         filesystem.chmod({ path: temporary, mode });
-        assertOwnerOnly(filesystem.stat({ path: temporary }).mode, options);
+        assertOwnerOnly(filesystem.stat({ path: temporary }).mode, options, platform);
         filesystem.sync({ descriptor });
         const fileDescriptor = descriptor;
         descriptor = undefined;
@@ -93,13 +140,10 @@ export function writeFileAtomic(required, options = {}) {
         }
         filesystem.rename({ from: temporary, to: filePath });
         renamed = true;
-        const directory = filesystem.open({ path: path.dirname(filePath), flags: "r" });
-        try {
-            filesystem.sync({ descriptor: directory });
-        }
-        finally {
-            filesystem.close({ descriptor: directory });
-        }
+        syncDirectoryBestEffort({ directory: path.dirname(filePath),
+            open: (path, flags) => filesystem.open({ path, flags }),
+            sync: descriptor => filesystem.sync({ descriptor }), close: descriptor => filesystem.close({ descriptor }),
+        }, { platform });
     }
     catch (error) {
         if (descriptor !== undefined) {
@@ -129,6 +173,7 @@ export function writeJsonFileAtomic(required, options = {}) {
  * Parent creation supports runtime-state and secret stores without another writer implementation. */
 export async function writeFileAtomicAsync(required, options = {}) {
     const { filePath, content } = required;
+    const platform = options.platform ?? process.platform;
     const filesystem = options.fs ?? fsPromises;
     if (options.createParent)
         await filesystem.mkdir(path.dirname(filePath), { recursive: true });
@@ -151,7 +196,7 @@ export async function writeFileAtomicAsync(required, options = {}) {
     try {
         await handle.writeFile(content, "utf8");
         await handle.chmod(mode);
-        assertOwnerOnly((await handle.stat()).mode, options);
+        assertOwnerOnly((await handle.stat()).mode, options, platform);
         await handle.sync();
         await handle.close();
         closed = true;
@@ -166,13 +211,7 @@ export async function writeFileAtomicAsync(required, options = {}) {
         }
         await filesystem.rename(temporary, filePath);
         renamed = true;
-        const directory = await filesystem.open(path.dirname(filePath), "r");
-        try {
-            await directory.sync();
-        }
-        finally {
-            await directory.close();
-        }
+        await syncDirectoryBestEffortAsync({ directory: path.dirname(filePath), open: (path, flags) => filesystem.open(path, flags) }, { platform });
     }
     catch (error) {
         if (!closed) {

package/dist/fs/durable-json.d.ts

@@ -74,7 +74,9 @@ export interface DurableJsonFile {
 }
 /** Atomic replacement, distinct corrupt reads, quarantine, and token-owned synchronous locks.
  * Lock stealing rechecks inode, bytes and mtime; conditional unlink is not available on all hosts.
- * File fsync precedes rename; directory fsync follows it. Persistence remains filesystem-dependent.
+ * File fsync precedes rename; directory flush afterwards is best-effort: skipped on Windows,
+ * unsupported-code failures ignored (EPERM/EISDIR/EINVAL/EACCES/ENOTSUP), other failures reported
+ * after replacement. Persistence remains filesystem-dependent.
  */
 export declare function createDurableJsonFile({ filePath, filesystem: fs, clock, sleep, process, random, report, notices }: DurableJsonPorts & {
     filePath: string;

package/dist/fs/durable-json.js

@@ -36,7 +36,9 @@ export function createNodeDurableJsonPorts(_required) {
 }
 /** Atomic replacement, distinct corrupt reads, quarantine, and token-owned synchronous locks.
  * Lock stealing rechecks inode, bytes and mtime; conditional unlink is not available on all hosts.
- * File fsync precedes rename; directory fsync follows it. Persistence remains filesystem-dependent.
+ * File fsync precedes rename; directory flush afterwards is best-effort: skipped on Windows,
+ * unsupported-code failures ignored (EPERM/EISDIR/EINVAL/EACCES/ENOTSUP), other failures reported
+ * after replacement. Persistence remains filesystem-dependent.
  */
 export function createDurableJsonFile({ filePath, filesystem: fs, clock, sleep, process, random, report, notices }, { pollMs = 10, staleMs = 30000 } = {}) {
     if (!filePath)
@@ -70,8 +72,9 @@ export function createDurableJsonFile({ filePath, filesystem: fs, clock, sleep,
         return `${filePath}.${pid}.tmp`;
     }
     // Same-directory rename gives readers complete old/new versions rather than a torn intermediate.
-    // Flush bytes before rename so metadata cannot precede content. The canonical writer also syncs
-    // the parent directory; platform/filesystem support determines persistence after that sync.
+    // Flush bytes before rename so metadata cannot precede content. The canonical writer's parent
+    // directory flush is best-effort: skipped on Windows, unsupported-code failures ignored
+    // (EPERM/EISDIR/EINVAL/EACCES/ENOTSUP), other failures reported after replacement.
     // Keep the legacy temp path, pretty JSON bytes and new-file create mode for these shared stores.
     function writeJson(filePath, value) {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });

package/dist/fs/verified-directory-move.d.ts

@@ -19,7 +19,7 @@ export declare function moveDirectoryVerified({ from, to, commit }: {
     from: string;
     to: string;
     commit: () => void;
-}, { excluded, filesystem, prepareDestination, relocateFiles, verifyFile, backupId }?: {
+}, { excluded, filesystem, prepareDestination, relocateFiles, verifyFile, backupId, platform }?: {
     excluded?: readonly string[];
     filesystem?: typeof fs;
     prepareDestination?: (required: {
@@ -33,5 +33,6 @@ export declare function moveDirectoryVerified({ from, to, commit }: {
         path: string;
     }) => string;
     backupId?: () => string;
+    platform?: NodeJS.Platform;
 }): void;
 //# sourceMappingURL=verified-directory-move.d.ts.map

package/dist/fs/verified-directory-move.js

@@ -1,4 +1,5 @@
 import { stageVerifiedFileRelocation } from "./verified-file-relocation.js";
+import { syncDirectoryBestEffort } from "./atomic-write.js";
 import fs from "node:fs";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -45,7 +46,7 @@ export function directoryFingerprint({ dir }, { excluded = [], filesystem = fs }
  * Same-filesystem failures roll the rename back. Commit must atomically update the host registry.
  * @complexity O(bytes + entries log entries), with two verification passes.
  */
-export function moveDirectoryVerified({ from, to, commit }, { excluded = [], filesystem = fs, prepareDestination, relocateFiles, verifyFile, backupId = randomUUID } = {}) {
+export function moveDirectoryVerified({ from, to, commit }, { excluded = [], filesystem = fs, prepareDestination, relocateFiles, verifyFile, backupId = randomUUID, platform = process.platform } = {}) {
     const source = filesystem.realpathSync(from);
     const target = path.resolve(to);
     if (target === source || target.startsWith(source + path.sep))
@@ -88,7 +89,7 @@ export function moveDirectoryVerified({ from, to, commit }, { excluded = [], fil
         if (relocateFiles) {
             if (!verifyFile)
                 throw new Error("File relocation requires a verification port.");
-            staged = stageVerifiedFileRelocation({ groups: relocateFiles({ source, target }), verify: verifyFile }, { filesystem, backupId, backupCovered: ({ from }) => copied && path.resolve(from).startsWith(target + path.sep) });
+            staged = stageVerifiedFileRelocation({ groups: relocateFiles({ source, target }), verify: verifyFile }, { filesystem, backupId, platform, backupCovered: ({ from }) => copied && path.resolve(from).startsWith(target + path.sep) });
         }
         if (copied) {
             const backupRoot = path.join(path.dirname(source), `.relocation-${backupId()}-backup`);
@@ -100,23 +101,11 @@ export function moveDirectoryVerified({ from, to, commit }, { excluded = [], fil
             filesystem.mkdirSync(backupRoot);
             filesystem.renameSync(source, backup);
             retiredSource = backup;
-            const fd = filesystem.openSync(backupRoot, "r");
-            try {
-                filesystem.fsyncSync(fd);
-            }
-            finally {
-                filesystem.closeSync(fd);
-            }
+            syncDirectoryBestEffort({ directory: backupRoot, open: filesystem.openSync, sync: filesystem.fsyncSync, close: filesystem.closeSync }, { platform });
         }
-        // Persist directory-name changes for same-filesystem renames as well as EXDEV retirement.
+        // Where supported, persist directory-name changes for same-filesystem renames as well as EXDEV retirement.
         for (const directory of new Set([path.dirname(source), path.dirname(target)])) {
-            const fd = filesystem.openSync(directory, "r");
-            try {
-                filesystem.fsyncSync(fd);
-            }
-            finally {
-                filesystem.closeSync(fd);
-            }
+            syncDirectoryBestEffort({ directory, open: filesystem.openSync, sync: filesystem.fsyncSync, close: filesystem.closeSync }, { platform });
         }
         commit();
     }

package/dist/fs/verified-file-relocation.d.ts

@@ -14,12 +14,13 @@ export declare function stageVerifiedFileRelocation({ groups, verify }: {
     verify: (required: {
         path: string;
     }) => string;
-}, { filesystem, backupCovered, backupId }?: {
+}, { filesystem, backupCovered, backupId, platform }?: {
     filesystem?: typeof fs;
     backupCovered?: (required: {
         from: string;
     }) => boolean;
     backupId?: () => string;
+    platform?: NodeJS.Platform;
 }): {
     rollback: () => void;
     finalize: () => void;

package/dist/fs/verified-file-relocation.js

@@ -1,12 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { syncDirectoryBestEffort } from "./atomic-write.js";
 /** Stage related files together while both directory identities are reserved by the host. Raw
  * sources remain intact through inspection so even WAL/SHM bytes are retained. Verification opens only
  * stopped databases through an injected read-only inspector; the filesystem owner never uses SQL.
  * @complexity O(total bytes + verification cost), bounded memory via native file copies.
  */
-export function stageVerifiedFileRelocation({ groups, verify }, { filesystem = fs, backupCovered = () => false, backupId = randomUUID } = {}) {
+export function stageVerifiedFileRelocation({ groups, verify }, { filesystem = fs, backupCovered = () => false, backupId = randomUUID, platform = process.platform } = {}) {
     const created = [], retired = [], markers = [], redundantBackups = [];
     const backupSuffix = `.relocation-${backupId()}-backup`;
     const copyExclusive = (from, to) => {
@@ -26,14 +27,8 @@ export function stageVerifiedFileRelocation({ groups, verify }, { filesystem = f
         syncParent(to);
     };
     const syncParent = (file) => {
-        // Directory fsync persists retirement/marker ordering before the host commits its catalog.
-        const fd = filesystem.openSync(path.dirname(file), "r");
-        try {
-            filesystem.fsyncSync(fd);
-        }
-        finally {
-            filesystem.closeSync(fd);
-        }
+        // Where supported, directory fsync persists retirement/marker ordering before the host commits its catalog.
+        syncDirectoryBestEffort({ directory: path.dirname(file), open: filesystem.openSync, sync: filesystem.fsyncSync, close: filesystem.closeSync }, { platform });
     };
     const rollback = () => {
         for (const item of [...retired].reverse()) {

package/dist/web/web-page.d.ts

@@ -9,7 +9,7 @@ import { type PageImage, type PageLink } from "./html-document.js";
  */
 export declare const WEB_FETCH_FORMATS: readonly ["markdown", "text", "html", "raw"];
 export type WebFetchFormat = (typeof WEB_FETCH_FORMATS)[number];
-export declare const DEFAULT_MAX_CHARS = 60000;
+export declare const DEFAULT_MAX_CHARS = 20000;
 export declare const MAX_MAX_CHARS = 200000;
 export declare const MAX_URL_LENGTH = 2048;
 export declare const DEFAULT_TIMEOUT_MS = 15000;

package/dist/web/web-page.js

@@ -10,7 +10,8 @@ import { htmlToText, readHtmlDocument, stripActiveHtml, MAX_LINKS, MAX_IMAGES }
  * This module only pre-validates the URL so the common mistakes get a precise message.
  */
 export const WEB_FETCH_FORMATS = ["markdown", "text", "html", "raw"];
-export const DEFAULT_MAX_CHARS = 60_000;
+// Leave room for page facts inside an agent CLI's MCP result budget.
+export const DEFAULT_MAX_CHARS = 20_000;
 export const MAX_MAX_CHARS = 200_000;
 export const MAX_URL_LENGTH = 2048;
 export const DEFAULT_TIMEOUT_MS = 15_000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/platform",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "Generic OS/platform primitives: process exec and lifecycle, filesystem containment, HTTP readiness polling, toolchain discovery, blob storage, AWS signing, and an SSRF-safe asset cache.",
   "license": "Apache-2.0",
   "repository": {