@stonyx/utils 0.2.3-alpha.24 → 0.2.3-alpha.26

package/README.md

@@ -75,10 +75,12 @@ Creates a file at the given path.
 
 #### `updateFile(filePath, data, options={})`
 
-Updates a file atomically by writing to a temporary file first.
+Updates a file atomically by writing to a sibling swap file first, then renaming it over the target. Throws if the file does not exist.
 
 * `options.json` — boolean, serialize as JSON.
 
+**Concurrency: last writer wins.** Concurrent `updateFile` calls on the same path are safe — each uses a swap file unique to its process and call, so neither caller can throw `ENOENT` or persist the other's bytes — but they are not serialized. The surviving value is whichever caller renames last.
+
 #### `copyFile(sourcePath, targetPath, options={})`
 
 Copies a file from source to target.
@@ -245,6 +247,8 @@ Prompts the user with `(y/N)` and resolves to `true` only if the answer is `"y"`
 * `options.input` — Readable stream (default: `process.stdin`).
 * `options.output` — Writable stream (default: `process.stdout`).
 
+**TTY required:** Rejects with an error if `process.stdin` is not a TTY and no custom `input` stream is provided. For headless/container deployments, use `autoMigrate` config or provide a custom input stream.
+
 #### `prompt(question, options={})`
 
 Prompts the user with a question and resolves to the trimmed input string.
@@ -252,6 +256,8 @@ Prompts the user with a question and resolves to the trimmed input string.
 * `options.input` — Readable stream (default: `process.stdin`).
 * `options.output` — Writable stream (default: `process.stdout`).
 
+**TTY required:** Rejects with an error if `process.stdin` is not a TTY and no custom `input` stream is provided.
+
 ```js
 import { confirm, prompt } from '@stonyx/utils/prompt';
 

package/dist/file.d.ts

@@ -23,6 +23,39 @@ interface FileImportMeta {
     path: string;
 }
 export declare function createFile(filePath: string, data: string | Record<string, unknown>, options?: FileOptions): Promise<void>;
+/**
+ * Atomically replace the contents of an existing file.
+ *
+ * Writes to a swap file that is a **sibling** of the target — so `rename` stays
+ * on one filesystem and therefore stays atomic — then renames it over the
+ * target. The swap name carries `process.pid` and a short random token rather
+ * than a timestamp: a whole-second token collided between concurrent callers,
+ * which made one caller throw `ENOENT` and the other silently persist bytes it
+ * had not written (abofs/stonyx-utils#44).
+ *
+ * Concurrency contract: **last writer wins**. Unique swap names remove the
+ * `ENOENT` and the byte-level clobber, but overlapping calls on one path still
+ * race on which value lands last. `updateFile` does not serialize, and callers
+ * needing a serialization guarantee must supply their own — an in-process queue
+ * would not provide one across processes anyway.
+ *
+ * The target's mode is read before the write and reapplied to the swap file, so
+ * the rename does not widen a deliberately restrictive file (a `0600` database
+ * would otherwise become `0666 & ~umask`). Other inode-bound metadata — ACLs,
+ * extended attributes, hard links, ownership — is *not* carried across; the
+ * target gets a new inode by construction.
+ *
+ * `rename` is atomic against concurrent *readers*, not against power loss:
+ * there is no `fsync`, so this is namespace atomicity, not crash durability.
+ * If the target is a symlink it is replaced by a regular file — the link's
+ * destination is never written through.
+ *
+ * Swap files are cleaned up on every failure path this function controls, but
+ * a process killed between the write and the rename leaves a permanently
+ * distinct `<path>.temp-<pid>-<token>` sibling that nothing reclaims. No
+ * sweeper ships with this module; `*.temp-*` siblings of a target are safe for
+ * a consumer to delete.
+ */
 export declare function updateFile(filePath: string, data: string | Record<string, unknown>, options?: FileOptions): Promise<void>;
 interface CopyFileOptions {
     overwrite?: boolean;

package/dist/file.js

@@ -1,9 +1,9 @@
-import { getTimestamp } from './date.js';
 import { kebabCaseToCamelCase } from './string.js';
 import { objToJson } from './object.js';
 import fs from 'fs';
 import { promises as fsp } from 'fs';
 import path from 'path';
+import { randomUUID } from 'crypto';
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }
@@ -17,12 +17,72 @@ export async function createFile(filePath, data, options = {}) {
         throw error instanceof Error ? error : new Error(String(error));
     }
 }
+/**
+ * Atomically replace the contents of an existing file.
+ *
+ * Writes to a swap file that is a **sibling** of the target — so `rename` stays
+ * on one filesystem and therefore stays atomic — then renames it over the
+ * target. The swap name carries `process.pid` and a short random token rather
+ * than a timestamp: a whole-second token collided between concurrent callers,
+ * which made one caller throw `ENOENT` and the other silently persist bytes it
+ * had not written (abofs/stonyx-utils#44).
+ *
+ * Concurrency contract: **last writer wins**. Unique swap names remove the
+ * `ENOENT` and the byte-level clobber, but overlapping calls on one path still
+ * race on which value lands last. `updateFile` does not serialize, and callers
+ * needing a serialization guarantee must supply their own — an in-process queue
+ * would not provide one across processes anyway.
+ *
+ * The target's mode is read before the write and reapplied to the swap file, so
+ * the rename does not widen a deliberately restrictive file (a `0600` database
+ * would otherwise become `0666 & ~umask`). Other inode-bound metadata — ACLs,
+ * extended attributes, hard links, ownership — is *not* carried across; the
+ * target gets a new inode by construction.
+ *
+ * `rename` is atomic against concurrent *readers*, not against power loss:
+ * there is no `fsync`, so this is namespace atomicity, not crash durability.
+ * If the target is a symlink it is replaced by a regular file — the link's
+ * destination is never written through.
+ *
+ * Swap files are cleaned up on every failure path this function controls, but
+ * a process killed between the write and the rename leaves a permanently
+ * distinct `<path>.temp-<pid>-<token>` sibling that nothing reclaims. No
+ * sweeper ships with this module; `*.temp-*` siblings of a target are safe for
+ * a consumer to delete.
+ */
 export async function updateFile(filePath, data, options = {}) {
     try {
+        filePath = path.resolve(filePath);
         await fsp.access(filePath);
-        const swapFile = `${filePath}.temp-${getTimestamp()}`;
-        await fsp.writeFile(swapFile, options.json ? objToJson(data) : String(data), 'utf8');
-        await fsp.rename(swapFile, filePath);
+        // The swap file becomes the target's inode, so it has to carry the target's
+        // permission bits or a routine save silently widens them.
+        const { mode } = await fsp.stat(filePath);
+        const targetMode = mode & 0o7777;
+        // pid + random token, never a timestamp: the swap name is a uniqueness
+        // token, and whole seconds cannot discriminate between concurrent callers.
+        // Truncated to 8 hex chars deliberately — a full 36-char UUID pushed the
+        // name overhead to 48 characters and made ~210-character basenames fail
+        // ENAMETOOLONG on a 255-byte NAME_MAX. `wx` below makes any residual
+        // collision loud, so the shortened token costs no safety.
+        const swapFile = `${filePath}.temp-${process.pid}-${randomUUID().slice(0, 8)}`;
+        try {
+            // `wx` turns any residual name collision into a loud EEXIST rather than a
+            // silent overwrite of another caller's swap bytes. `mode` here is masked
+            // by the umask, so it only narrows — the chmod below sets the exact bits.
+            await fsp.writeFile(swapFile, options.json ? objToJson(data) : String(data), { encoding: 'utf8', flag: 'wx', mode: targetMode });
+            await fsp.chmod(swapFile, targetMode);
+            await fsp.rename(swapFile, filePath);
+        }
+        catch (swapError) {
+            // Leave no orphan behind, and never let the cleanup mask the real error.
+            // EEXIST is the one code that must NOT be cleaned up: it means this call
+            // did not create the path, so the file belongs to another writer and
+            // unlinking it would reintroduce #44.
+            if (!(isNodeError(swapError) && swapError.code === 'EEXIST')) {
+                await fsp.unlink(swapFile).catch(() => { });
+            }
+            throw swapError;
+        }
     }
     catch (error) {
         throw error instanceof Error ? error : new Error(String(error));

package/dist/prompt.js

@@ -1,5 +1,9 @@
 import { createInterface } from 'readline';
 export function confirm(question, { input, output } = {}) {
+    if (!input && !process.stdin.isTTY) {
+        return Promise.reject(new Error('Interactive confirm() requires a TTY on stdin. ' +
+            'For headless/container deployments, use the autoMigrate config option instead.'));
+    }
     const rl = createInterface({
         input: input ?? process.stdin,
         output: output ?? process.stdout,
@@ -12,6 +16,10 @@ export function confirm(question, { input, output } = {}) {
     });
 }
 export function prompt(question, { input, output } = {}) {
+    if (!input && !process.stdin.isTTY) {
+        return Promise.reject(new Error('Interactive prompt() requires a TTY on stdin. ' +
+            'For headless/container deployments, configure non-interactive alternatives instead.'));
+    }
     const rl = createInterface({
         input: input ?? process.stdin,
         output: output ?? process.stdout,

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.3-alpha.24",
+  "version": "0.2.3-alpha.26",
   "description": "Utils module for Stonyx Framework",
   "repository": {
     "type": "git",