stitchkit 0.104.1 → 0.105.0

package/dist/{index-za6j7nwy.js → index-dsnjzb62.js}

@@ -3,19 +3,27 @@ import {
   ProcessInstanceSchema2,
   readProcessInstance,
   probeProcessOwner2
-} from "./index-5csmzesf.js";
+} from "./index-azx12jgv.js";
+import {
+  BoundedFileReadError,
+  readBoundedFile
+} from "./index-m616f0yz.js";
+import {
+  AtomicFilePublicationError2,
+  publishAtomicFile
+} from "./index-b56nnscm.js";
 import {
   isRecord
 } from "./index-9jfdm5tg.js";
 
 // src/internal/exclusive-lock.ts
-import { lstat, open as open2, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { lstat, open, readdir, unlink } from "node:fs/promises";
 import { hostname } from "node:os";
+import { dirname, join } from "node:path";
 import { z } from "zod";
 
 // src/internal/exclusive-lock-read.ts
-import { constants } from "node:fs";
-import { open } from "node:fs/promises";
 var OWNER_RECORD_BYTES = 16 * 1024;
 
 class LockRecordError extends Error {
@@ -26,42 +34,28 @@ class LockRecordError extends Error {
     this.code = code;
   }
 }
-async function readLockRecord(path, openDescriptor = open, signal) {
-  signal?.throwIfAborted();
-  if (!constants.O_NOFOLLOW || !constants.O_NONBLOCK) {
-    throw new LockRecordError("LOCK_UNSAFE_RECORD", "Safe lock descriptor flags are unavailable");
-  }
-  const handle = await openDescriptor(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+var LOCK_CODE = {
+  FILE_UNSUPPORTED: "LOCK_UNSAFE_RECORD",
+  FILE_NOT_REGULAR: "LOCK_UNSAFE_RECORD",
+  FILE_UNSAFE_LINK: "LOCK_UNSAFE_RECORD",
+  FILE_TOO_LARGE: "LOCK_RECORD_TOO_LARGE",
+  FILE_CHANGED: "LOCK_RECORD_CHANGED"
+};
+async function readLockRecord(path, {
+  openDescriptor,
+  signal,
+  singleLink = true
+} = {}) {
   try {
-    signal?.throwIfAborted();
-    const before = await handle.stat();
-    signal?.throwIfAborted();
-    if (!before.isFile() || before.nlink !== 1) {
-      throw new LockRecordError("LOCK_UNSAFE_RECORD", "Lock record must be a regular file with one link");
-    }
-    if (before.size > OWNER_RECORD_BYTES) {
-      throw new LockRecordError("LOCK_RECORD_TOO_LARGE", "Lock owner record exceeds its byte cap");
-    }
-    const bytes = Buffer.alloc(OWNER_RECORD_BYTES + 1);
-    let length = 0;
-    while (length < bytes.length) {
-      signal?.throwIfAborted();
-      const read = await handle.read(bytes, length, bytes.length - length, length);
-      if (read.bytesRead === 0)
-        break;
-      length += read.bytesRead;
-    }
-    if (length > OWNER_RECORD_BYTES) {
-      throw new LockRecordError("LOCK_RECORD_TOO_LARGE", "Lock owner record grew beyond its byte cap");
-    }
-    const after = await handle.stat();
-    signal?.throwIfAborted();
-    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || before.nlink !== after.nlink || length !== after.size) {
-      throw new LockRecordError("LOCK_RECORD_CHANGED", "Lock owner record changed during its read");
-    }
-    return { text: bytes.subarray(0, length).toString("utf8"), info: after };
-  } finally {
-    await handle.close();
+    const { bytes, observation } = await readBoundedFile(path, OWNER_RECORD_BYTES, { rejectSymlinks: true, singleLink, stable: true, ...signal && { signal } }, openDescriptor);
+    return {
+      text: new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes),
+      info: observation
+    };
+  } catch (error) {
+    if (error instanceof BoundedFileReadError)
+      throw new LockRecordError(LOCK_CODE[error.code], error.message);
+    throw error;
   }
 }
 
@@ -104,14 +98,43 @@ async function diagnose(owner, declaredIdentity) {
   return { attribution, ...await probeProcessOwner2(owner.pid, owner.process), owner };
 }
 var MAX_RECLAIM_DEPTH = 16;
+var STALE_GUARD_GRACE_MS = 5000;
+var STAGED_NAME = /^\.lock-[0-9a-f-]{36}\.tmp$/;
+async function stagedSibling(path, ino, dev) {
+  const directory = dirname(path);
+  for (const name of await readdir(directory)) {
+    if (!STAGED_NAME.test(name))
+      continue;
+    const candidate = join(directory, name);
+    const info = await lstat(candidate).catch(() => {
+      return;
+    });
+    if (info?.isFile() && info.ino === ino && info.dev === dev)
+      return candidate;
+  }
+  return;
+}
 async function readLockFile(path, onFailure, signal) {
   try {
-    const record = await readLockRecord(path, undefined, signal);
+    let stagedName;
+    let record;
+    try {
+      record = await readLockRecord(path, { signal });
+    } catch (cause) {
+      if (!(cause instanceof LockRecordError) || cause.code !== "LOCK_UNSAFE_RECORD")
+        throw cause;
+      const info = await lstat(path);
+      stagedName = info.nlink === 2 ? await stagedSibling(path, info.ino, info.dev) : undefined;
+      if (stagedName === undefined)
+        throw cause;
+      record = await readLockRecord(path, { signal, singleLink: false });
+    }
     return {
       ...readOwner(record.text),
       ino: record.info.ino,
       dev: record.info.dev,
-      mtimeMs: record.info.mtimeMs
+      mtimeMs: record.info.mtimeMs,
+      ...stagedName !== undefined && { stagedName }
     };
   } catch (cause) {
     if (!isCode(cause, "ENOENT"))
@@ -119,10 +142,23 @@ async function readLockFile(path, onFailure, signal) {
     return;
   }
 }
-async function unlinkIfSame(path, ino, dev) {
+async function sweepStagedLocks(directory, machine, signal) {
+  for (const name of await readdir(directory).catch(() => [])) {
+    if (!STAGED_NAME.test(name))
+      continue;
+    const candidate = join(directory, name);
+    const state = await readLockFile(candidate, undefined, signal);
+    if (!state?.owner)
+      continue;
+    if ((await diagnose(state.owner, machine)).liveness !== "gone")
+      continue;
+    await unlinkIfSame(candidate, state.ino, state.dev, state.stagedName === undefined ? 1 : 2);
+  }
+}
+async function unlinkIfSame(path, ino, dev, links = 1) {
   try {
     const current = await lstat(path);
-    if (current.ino !== ino || current.dev !== dev || !current.isFile() || current.nlink !== 1)
+    if (current.ino !== ino || current.dev !== dev || !current.isFile() || current.nlink !== links)
       return;
     await unlink(path);
   } catch (error) {
@@ -133,7 +169,6 @@ async function unlinkIfSame(path, ino, dev) {
 async function createOwned(path, options, reclaimed) {
   const identity = await machineIdentity(options.machineIdentity);
   const instance = await readProcessInstance(process.pid);
-  const handle = await open2(path, "wx", options.mode);
   const owner = {
     pid: process.pid,
     process: instance,
@@ -141,29 +176,41 @@ async function createOwned(path, options, reclaimed) {
     acquiredAt: new Date().toISOString(),
     ...identity !== null && { machine: identity }
   };
+  const ownedRecord = `${JSON.stringify(owner)}
+`;
+  const staged = join(dirname(path), `.lock-${randomUUID()}.tmp`);
+  const handle = await open(staged, "wx", options.mode);
   let ino;
   let dev;
+  let published = false;
   try {
     const info = await handle.stat();
     ino = info.ino;
     dev = info.dev;
     await handle.chmod(options.mode);
-    await handle.writeFile(`${JSON.stringify(owner)}
-`, "utf8");
+    await handle.writeFile(ownedRecord, "utf8");
+    try {
+      await publishAtomicFile(staged, path, { replace: false, durability: "file" });
+      published = true;
+    } catch (error) {
+      published = error instanceof AtomicFilePublicationError2;
+      throw error;
+    }
   } catch (error) {
     await handle.close().catch(() => {
       return;
     });
-    if (ino !== undefined && dev !== undefined)
-      await unlinkIfSame(path, ino, dev).catch(() => {
+    if (published && ino !== undefined && dev !== undefined)
+      await unlinkIfSame(path, ino, dev, 2).catch(() => {
         return;
       });
+    await unlink(staged).catch(() => {
+      return;
+    });
     throw error;
   }
   const ownedInode = ino;
   const ownedDevice = dev;
-  const ownedRecord = `${JSON.stringify(owner)}
-`;
   let released = false;
   return {
     path,
@@ -206,7 +253,7 @@ async function reclaimUnderGuard(path, options, depth) {
   try {
     acquired = await attemptExclusiveLock(guardPath, {
       ...options,
-      ownerlessGraceMs: options.ownerlessGraceMs === undefined ? 5000 : options.ownerlessGraceMs
+      ownerlessGraceMs: options.ownerlessGraceMs === undefined ? STALE_GUARD_GRACE_MS : options.ownerlessGraceMs
     }, depth + 1);
   } catch (cause) {
     if (!isCode(cause, "ENAMETOOLONG"))
@@ -229,8 +276,14 @@ async function reclaimUnderGuard(path, options, depth) {
         return { refused: true };
       if (!reclaimable(state, diagnosis, options.ownerlessGraceMs))
         return { refused: true, cause: diagnosis.cause };
+      if (state.stagedName !== undefined)
+        await unlink(state.stagedName).catch((error) => {
+          if (!isCode(error, "ENOENT"))
+            throw error;
+        });
       await unlinkIfSame(path, state.ino, state.dev);
     }
+    await sweepStagedLocks(dirname(path), options.machineIdentity, options.signal);
     return await createOwned(path, options, state !== undefined).catch((error) => {
       if (isCode(error, "EEXIST"))
         return { refused: true, cause: error };

package/dist/index-eemvahkc.js

@@ -0,0 +1,21 @@
+// src/internal/timers.ts
+var MAX_TIMER_MS = 2147483647;
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const abort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
+
+export { MAX_TIMER_MS, sleep };

package/dist/index-ef8gdaq0.js

@@ -0,0 +1,105 @@
+import {
+  stagingPath
+} from "./index-cq59agna.js";
+import {
+  closeAfter,
+  closeAfterSync,
+  publishAtomicFile,
+  publishAtomicFileSync
+} from "./index-b56nnscm.js";
+
+// src/internal/atomic-file.ts
+import { closeSync, fchmodSync, fsyncSync, openSync, unlinkSync, writeSync } from "node:fs";
+import { open, unlink } from "node:fs/promises";
+var DEFAULT_MODE = 384;
+function bytesOf(data) {
+  return typeof data === "string" ? new TextEncoder().encode(data) : data;
+}
+async function writeAllBytes(file, bytes) {
+  for (let offset = 0;offset < bytes.byteLength; ) {
+    const { bytesWritten } = await file.write(bytes, offset, bytes.byteLength - offset);
+    if (bytesWritten === 0)
+      throw new Error("zero-byte atomic-file write");
+    offset += bytesWritten;
+  }
+}
+async function writeFileAtomic2(target, data, options = {}) {
+  return writeAtomicFileData(target, data, options);
+}
+function isMissing(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+async function writeAtomicFileStaged(target, stage, options, io = { open, unlink, publish: publishAtomicFile }) {
+  const mode = options.mode ?? DEFAULT_MODE;
+  const staged = stagingPath(target);
+  const file = await io.open(staged, "wx", mode);
+  try {
+    const value = await closeAfter(file, async () => {
+      const filled = await stage.fill(file);
+      await file.chmod(mode);
+      if (options.durability !== "none")
+        await file.sync();
+      return filled;
+    });
+    await io.publish(staged, target, {
+      replace: options.replace ?? true,
+      durability: options.durability ?? "file"
+    });
+    return value;
+  } catch (error) {
+    await io.unlink(staged).catch((cleanup) => {
+      if (!isMissing(cleanup))
+        stage.onCleanupError?.(cleanup);
+    });
+    throw error;
+  }
+}
+async function writeAtomicFileData(target, data, options, io) {
+  await writeAtomicFileStaged(target, { fill: (file) => writeAllBytes(file, bytesOf(data)) }, options, io);
+}
+var nativeSync = {
+  open(path, flags, mode) {
+    const descriptor = openSync(path, flags, mode);
+    return {
+      write: (bytes, offset, length) => writeSync(descriptor, bytes, offset, length),
+      chmod: (bits) => fchmodSync(descriptor, bits),
+      sync: () => fsyncSync(descriptor),
+      close: () => closeSync(descriptor)
+    };
+  },
+  unlink: unlinkSync,
+  publish: publishAtomicFileSync
+};
+function writeAtomicFileDataSync(target, data, options, io = nativeSync) {
+  const mode = options.mode ?? DEFAULT_MODE;
+  const bytes = bytesOf(data);
+  const staged = stagingPath(target);
+  const file = io.open(staged, "wx", mode);
+  try {
+    closeAfterSync(() => file.close(), () => {
+      for (let offset = 0;offset < bytes.byteLength; ) {
+        const written = file.write(bytes, offset, bytes.byteLength - offset);
+        if (written === 0)
+          throw new Error("zero-byte atomic-file write");
+        offset += written;
+      }
+      file.chmod(mode);
+      if (options.durability !== "none")
+        file.sync();
+    });
+    io.publish(staged, target, {
+      replace: options.replace ?? true,
+      durability: options.durability ?? "file"
+    });
+  } catch (error) {
+    try {
+      io.unlink(staged);
+    } catch {}
+    throw error;
+  }
+}
+function writeFileAtomicSync2(target, data, options = {}) {
+  writeAtomicFileDataSync(target, data, options);
+}
+
+export { writeAllBytes, writeFileAtomic2, writeAtomicFileStaged, writeAtomicFileData, writeFileAtomicSync2 };

package/dist/{index-fa4wg312.js → index-f199nfq5.js}

@@ -1,16 +1,16 @@
 import {
   AppError2
-} from "./index-x928baz2.js";
+} from "./index-j9gxbztg.js";
 import {
   toolErrorFromResult
-} from "./index-2vnh05w4.js";
+} from "./index-2k91mewf.js";
 import {
   assertUniqueToolName
-} from "./index-77nxk6ay.js";
+} from "./index-r393tnfp.js";
 import {
   collectTools2,
   createToolRunner
-} from "./index-2hyavjjj.js";
+} from "./index-wbhdzxar.js";
 
 // src/tools/invoker.ts
 function createToolInvoker2(services, config) {
@@ -30,8 +30,12 @@ function createToolInvoker2(services, config) {
     const tool = tools.get(name);
     if (tool)
       return tool;
-    throw new AppError2("NOT_FOUND", `Unknown tool: ${name}`, 404, {
-      available: names
+    throw new AppError2("NOT_FOUND", {
+      message: `Unknown tool: ${name}`,
+      status: 404,
+      details: {
+        available: names
+      }
     });
   };
   const run = (name, args, options = {}) => {

package/dist/{index-ck71tbcf.js → index-fsw1ybf3.js}

@@ -1,6 +1,9 @@
 import {
   resolveRouteParamsSchema
 } from "./index-m38ej7e5.js";
+import {
+  assertPositiveSafeInteger
+} from "./index-0s4xebbg.js";
 import {
   isUnsafeKey
 } from "./index-zsarb5xp.js";
@@ -71,11 +74,6 @@ function assertToolView(prefix, key, ep) {
 }
 
 // src/contract/define-validation.ts
-function assertPositiveLimit(where, name, value) {
-  if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
-    throw new Error(`${where} ${name} must be a positive safe integer, received ${value}`);
-  }
-}
 function assertMultipartEndpoint(prefix, key, ep) {
   const where = `Contract "${prefix}": multipart endpoint "${key}"`;
   if (ep.method !== "POST" && ep.method !== "PUT" && ep.method !== "PATCH") {
@@ -85,16 +83,16 @@ function assertMultipartEndpoint(prefix, key, ep) {
   if (!multipart || typeof multipart !== "object") {
     throw new Error(`${where} must declare a multipart descriptor`);
   }
-  assertPositiveLimit(where, "maxRequestBytes", multipart.maxRequestBytes);
-  assertPositiveLimit(where, "maxFieldBytes", multipart.maxFieldBytes);
+  assertPositiveSafeInteger(`${where} maxRequestBytes`, multipart.maxRequestBytes, Error);
+  assertPositiveSafeInteger(`${where} maxFieldBytes`, multipart.maxFieldBytes, Error);
   const entries = Object.entries(multipart.files);
   if (entries.length === 0)
     throw new Error(`${where} must declare at least one file field`);
   for (const [field, policy] of entries) {
     if (!field || isUnsafeKey(field))
       throw new Error(`${where} has an invalid file field name`);
-    assertPositiveLimit(`${where} field "${field}"`, "maxBytes", policy.maxBytes);
-    assertPositiveLimit(`${where} field "${field}"`, "maxFiles", policy.maxFiles);
+    assertPositiveSafeInteger(`${where} field "${field}" maxBytes`, policy.maxBytes, Error);
+    assertPositiveSafeInteger(`${where} field "${field}" maxFiles`, policy.maxFiles, Error);
     if (policy.multiple !== true && policy.maxFiles !== undefined) {
       throw new Error(`${where} field "${field}" may set maxFiles only with multiple: true`);
     }
@@ -142,9 +140,9 @@ function assertStreamingResponseEndpoint(prefix, key, ep) {
   if (runtimeFinalLine === "require-newline" && runtimeFormat === "sse") {
     throw new Error(`${where} finalLine applies only to ndjson`);
   }
-  assertPositiveLimit(where, "maxFrameBytes", ep.stream.maxFrameBytes);
-  assertPositiveLimit(where, "lifetimeMs", ep.stream.lifetimeMs);
-  assertPositiveLimit(where, "heartbeatMs", ep.stream.heartbeatMs);
+  assertPositiveSafeInteger(`${where} maxFrameBytes`, ep.stream.maxFrameBytes, Error);
+  assertPositiveSafeInteger(`${where} lifetimeMs`, ep.stream.lifetimeMs, Error);
+  assertPositiveSafeInteger(`${where} heartbeatMs`, ep.stream.heartbeatMs, Error);
   if (ep.stream.idleTimeoutSeconds !== undefined && (!Number.isSafeInteger(ep.stream.idleTimeoutSeconds) || ep.stream.idleTimeoutSeconds < 0)) {
     throw new Error(`${where} idleTimeoutSeconds must be a non-negative safe integer`);
   }
@@ -267,9 +265,7 @@ function defineContract2(meta, endpoints) {
     if (ep.desc.trim() === "") {
       throw new Error(`Contract "${meta.prefix}": endpoint "${key}" has an empty desc`);
     }
-    if (ep.maxJsonBodyBytes !== undefined && (!Number.isSafeInteger(ep.maxJsonBodyBytes) || ep.maxJsonBodyBytes <= 0)) {
-      throw new Error(`Contract "${meta.prefix}": endpoint "${key}" maxJsonBodyBytes must be a positive safe integer, received ${ep.maxJsonBodyBytes}`);
-    }
+    assertPositiveSafeInteger(`Contract "${meta.prefix}": endpoint "${key}" maxJsonBodyBytes`, ep.maxJsonBodyBytes, Error);
     if (ep.multipart)
       assertMultipartEndpoint(meta.prefix, key, ep);
     if (ep.rawResponse)