Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/** Cross-cutting filesystem, time, formatting, and hashing helpers. */
import { access, appendFile, chmod, copyFile, mkdir, open, readFile, readdir, stat, writeFile, rename, unlink, rm } from 'fs/promises';
import { createReadStream, createWriteStream, existsSync, statSync, watch as watchFileSystem } from 'fs';
import { createHash, randomUUID } from 'crypto';
import { basename, dirname, extname, join } from 'path';
import { promisify } from 'util';
import { execFile } from './childProcess.js';
import { isVitestRunner } from './runtimeEnv.js';
// The #6176 data-root guard is loaded ONLY under an actual Vitest worker —
// `isVitestRunner()`, narrower than `isTestRunner()`, because `scripts/
// smoke-boot.js` sets NODE_ENV=test on the real server boot to select the
// file-backend escape hatch, and that boot's writes into the real data/ tree
// are correct, not a leak (see `isVitestRunner()`'s doc comment). `fileCore` is
// reached by essentially every server suite, so a static import of the guard
// (and its `dataRoot`/`pathContainment` closure) landed on every one of them and
// pushed `importScoping.test.js`'s tree-wide budget over its ceiling. Deferring
// it — the shape server/AGENTS.md prescribes — also means production never
// loads the guard at all, rather than loading it to no-op.
// The module promise is memoized, so the dynamic import resolves once per worker.
let guardModule = null;
const loadGuard = () => (guardModule ??= import('./testDataIsolation.js'));
export const execFileAsync = promisify(execFile);
const IS_WIN = process.platform === 'win32';
// Call-time platform probe. `IS_WIN` above is a module-load snapshot (fine for
// the path-shape helper at the bottom of this file); the Windows retry paths
// below read the platform on every call so a POSIX host never carries a stale
// decision and so the retry behavior is exercisable in tests.
const isWindows = () => process.platform === 'win32';
// Windows-only retry knobs (#4095). A destination lock from a concurrent reader
// or an AV scan clears in milliseconds, so a handful of short retries is enough
// to avoid both a failed write and the reader's
// phantom "nothing here yet".
const WIN_RETRY_ATTEMPTS = 5;
const WIN_RETRY_DELAY_MS = 10;
// rename(2) failures that mean "the destination is momentarily locked", not
// "this rename can never work".
const WIN_RENAME_LOCK_CODES = ['EPERM', 'EACCES', 'EEXIST', 'EBUSY'];
// copyfile(2) has no EEXIST case (the destination is overwritten); a held
// source or destination surfaces as one of these.
const WIN_COPY_LOCK_CODES = ['EPERM', 'EACCES', 'EBUSY'];
const FILE_WATCH_FALLBACK_POLL_MS = 5000;
// Directories whose fsync already failed once this process, so a filesystem
// that rejects directory fsync (EINVAL on some network mounts) warns once
// instead of on every write.
const unsyncableDirs = new Set();
/**
* fsync a directory so a just-completed rename inside it survives a crash.
* Best-effort once the rename is visible: the bytes are already in place, so a
* filesystem that cannot sync its directory degrades to the pre-#12025
* guarantee with one warning rather than failing a write that succeeded.
* Windows cannot open a directory for fsync, so it is skipped there.
*/
async function syncDirectory(dir) {
if (isWindows()) return;
try {
const handle = await open(dir, 'r');
try { await handle.sync(); } finally { await handle.close(); }
} catch (err) {
if (!err?.code) throw err;
if (unsyncableDirs.has(dir)) return;
unsyncableDirs.add(dir);
console.warn(`⚠️ Directory fsync unavailable for ${dir} (${err.code}); renames there are not crash-durable`);
}
}
/** Normalize Node statfs block counts into byte totals and compatibility aliases. */
export function parseFilesystemStats(stats) {
if (!stats) return null;
const total = Number(stats.blocks) * Number(stats.bsize);
const available = Number(stats.bavail) * Number(stats.bsize);
if (!Number.isFinite(total) || total <= 0 || !Number.isFinite(available) || available < 0) return null;
const free = Math.min(total, available);
const used = total - free;
return {
total,
used,
free,
usagePercent: Math.round((used / total) * 100),
totalBytes: total,
usedBytes: used,
freeBytes: free,
};
}
/**
* Watch for a file to appear without repeatedly stat'ing its parent directory.
*
* `shouldDetect` is a run-specific acceptance gate for callers watching a
* compatibility name. It is evaluated only after the target exists, so a
* rejected stale/ambiguous file remains watchable and can be accepted if a
* later write makes it valid.
*/
export function watchForFile(
filePath,
onDetected,
{
settleMs = 50,
pollMs = FILE_WATCH_FALLBACK_POLL_MS,
shouldDetect = () => true,
} = {},
) {
const targetName = basename(filePath);
const targetDir = dirname(filePath);
let closed = false;
let detected = false;
let settleTimer = null;
let pollTimer = null;
let watcher = null;
let onWatcherClosed = null;
const notify = () => {
Promise.resolve().then(onDetected).catch((err) => {
console.error(`❌ File watcher callback failed: ${err.message}`);
});
};
const watcherClosed = () => {
watcher = null;
const callback = onWatcherClosed;
onWatcherClosed = null;
callback?.();
};
const close = (onClosed) => {
if (closed) return;
closed = true;
if (settleTimer) clearTimeout(settleTimer);
if (pollTimer) clearInterval(pollTimer);
onWatcherClosed = onClosed;
if (watcher) watcher.close();
else watcherClosed();
};
const detect = (settle = true) => {
if (closed || detected || !existsSync(filePath) || !shouldDetect(filePath)) return;
detected = true;
if (!settle) {
close(notify);
return;
}
settleTimer = setTimeout(() => {
settleTimer = null;
if (closed) return;
close(notify);
}, settleMs);
};
const watchFailed = (err) => {
// Native errors can close the handle without emitting `close`. Drop it so
// fallback detection never waits for an event that can no longer arrive.
const failedWatcher = watcher;
watcher = null;
failedWatcher?.close();
watcherClosed();
console.warn(`⚠️ File watcher unavailable (${err.code || 'UNKNOWN'}); using fallback polling`);
};
try {
watcher = watchFileSystem(targetDir, (_eventType, changedName) => {
if (changedName == null || changedName.toString() === targetName) detect();
});
watcher.once('close', watcherClosed);
watcher.on('error', watchFailed);
} catch (err) {
watchFailed(err);
}
// fs.watch is low-latency but best-effort: native backends can miss a file
// creation or atomic rename. Keep a deliberately relaxed fallback so a
// missed event cannot strand an agent indefinitely.
pollTimer = setInterval(() => detect(), pollMs);
detect(false);
return close;
}
// Cache __dirname calculation for services importing this module
/**
* Ensure a directory exists, creating it recursively if needed.
* Uses mkdir with recursive: true which is idempotent and avoids TOCTOU races.
*
* @param {string} dir - Directory path to ensure exists
* @returns {Promise<void>}
*
* @example
* await ensureDir(PATHS.data);
* await ensureDir('/custom/path/to/dir');
*/
export async function ensureDir(dir) {
// #6176 — refuse a NEW dir in the real data/ tree under the runner. Only the
// CREATE path: `mkdir -p` on an existing directory mutates nothing.
if (isVitestRunner()) (await loadGuard()).assertNotNewRealDataDir(dir);
// mkdir with recursive: true is idempotent - it succeeds if dir exists.
// BUT on Windows it can intermittently throw UNKNOWN/EPERM/EEXIST even when
// the directory already exists or is created concurrently — antivirus locks,
// OneDrive sync, and network/mapped drives all surface spurious failures that
// the POSIX-modeled `recursive: true` no-op contract doesn't anticipate.
// Swallow the error when the path is in fact a directory afterward.
await mkdir(dir, { recursive: true }).catch((err) => {
if (err?.code === 'EEXIST') return; // already exists — the intended state
const s = statSync(dir, { throwIfNoEntry: false });
if (s && s.isDirectory()) {
console.log(`⚠️ ensureDir swallowed spurious ${err?.code || 'error'} — dir exists: ${dir}`);
return;
}
throw err;
});
}
/**
* Async existence check — the non-blocking replacement for `existsSync` on
* request/hot paths. Resolves true iff `path` is accessible, false otherwise.
* Never throws (a missing path, permission error, etc. all resolve false), so
* it drops in wherever `existsSync` guarded a request handler.
*
* @param {string} path - File or directory path to test.
* @returns {Promise<boolean>}
*
* @example
* if (!(await pathExists(filepath))) throw new ServerError('Not found', { status: 404 });
*/
export async function pathExists(path) {
return access(path).then(() => true, () => false);
}
/**
* Ensure multiple directories exist.
*
* @param {string[]} dirs - Array of directory paths to ensure exist
* @returns {Promise<void>}
*
* @example
* await ensureDirs([PATHS.data, PATHS.cos, PATHS.memory]);
*/
export async function ensureDirs(dirs) {
for (const dir of dirs) {
await ensureDir(dir);
}
}
/**
* Atomically write data to a file via temp-file + rename.
* Guarantees readers never see a partial write. Accepts a string or any JSON-
* serializable value (objects are stringified with 2-space indentation).
*
* Symlink semantics (design decision, issue #1893): when `filePath` is a
* symlink, the temp+rename REPLACES the link with a regular file — it does NOT
* follow the link to update the backing file. This is the standard atomic-write
* contract (git, dpkg, rsync, `os.replace` all replace the link); following the
* link would reintroduce the non-atomic in-place truncate this helper exists to
* eliminate. PortOS ships no symlinked data files, so this is a documented
* property rather than a supported use case — do not pass a symlink you expect
* to be followed. Callers that genuinely need follow-the-link semantics must
* resolve `realpath(filePath)` themselves before calling.
*
* Crash durability (#12025): the temp file is fsynced before the rename and
* the parent directory after it, so a power loss or OS crash cannot make the
* rename durable while the bytes are not — the zero-length or stale store that
* strict readers (settings, auth sessions, the media-jobs persist latch) treat
* as permanent corruption. The rename alone only protects concurrent readers.
* Windows gets the file sync only; see `syncDirectory`.
*
* @param {string} filePath - Destination file path
* @param {string|object} data - String or JSON-serializable value
* @param {{ onStage?: (stage: 'write'|'replace'|'dirSync') => void }} [options] -
* `onStage` is called as each durable stage begins, for slow-write diagnostics.
* @returns {Promise<void>}
*
* @example
* await atomicWrite(FILE, { version: 1, items: [] });
* await atomicWrite(LOG_FILE, 'raw string content');
*/
export async function atomicWrite(filePath, data, { onStage } = {}) {
// #6176 — the filesystem analogue of db.js's row-write backstop. Refuses
// before any bytes are produced, so a leaking suite cannot even leave a temp
// file behind in the real tree.
if (isVitestRunner()) (await loadGuard()).assertNotRealDataWrite(filePath, 'atomicWrite');
// Buffer must pass through unchanged — JSON.stringify on a Buffer produces
// `{"type":"Buffer","data":[...]}` which corrupts binary writes (PNG, etc.).
const payload = typeof data === 'string' || Buffer.isBuffer(data) ? data : JSON.stringify(data, null, 2);
onStage?.('write');
await ensureDir(dirname(filePath));
// Preserve the destination's existing permission bits. A plain
// writeFile(existing) truncated the inode in place and kept its mode, but
// atomicWrite creates a fresh temp inode and renames it over the target —
// which would silently widen a hand-restricted file (e.g. a `chmod 600`
// OAuth tokens.json) to the umask default (typically 0644) on every rewrite.
// Read the destination's mode FIRST and create the temp file with it from
// the start, so the secret bytes are never written to a world-readable temp
// (a crash between write and chmod would otherwise leave a readable copy, and
// a local user could race-read it during the window). A trailing chmod pins
// the exact mode in case the umask tightened the create below it. New files
// (stat fails with ENOENT) keep the umask default, exactly as before.
const existingMode = await stat(filePath).then((s) => s.mode & 0o777, (err) => {
// An unreadable mode is not an absent file: defaulting here could replace
// an owner-only store with a more permissive inode.
if (err.code === 'ENOENT') return null;
throw err;
});
const tmp = `${filePath}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
const renameWithWindowsRetries = async (from, to, {
attempts = WIN_RETRY_ATTEMPTS,
delayMs = WIN_RETRY_DELAY_MS,
} = {}) => {
let err = await rename(from, to).then(() => null, (e) => e);
let retries = 0;
if (isWindows()) {
for (let attempt = 1; err && attempt < attempts && WIN_RENAME_LOCK_CODES.includes(err.code); attempt += 1) {
await sleep(delayMs);
retries += 1;
err = await rename(from, to).then(() => null, (e) => e);
if (!err) console.log(`⚠️ atomicWrite rename succeeded after ${retries} retry(s): ${basename(filePath)}`);
}
}
return { err, retries };
};
// Node's fs.rename uses MoveFileExW with MOVEFILE_REPLACE_EXISTING on Windows (atomic
// overwrite), but still fails with EPERM/EACCES/EBUSY if the destination is locked (AV scan,
// concurrent reader). Retry the atomic rename a bounded number of times; if the lock
// persists, FAIL the write (#9556). The previous fallback moved the destination to a `.bak`
// sibling and installed the temp file — if that install also failed, the only canonical
// copy was left orphaned at the backup path while readers saw a trustworthy "absent" store.
// Rejecting leaves the original bytes untouched at filePath.
const replace = async () => {
const { err } = await renameWithWindowsRetries(tmp, filePath);
if (!err) return;
if (isWindows() && WIN_RENAME_LOCK_CODES.includes(err.code)) {
err.message = `${err.message} — ${basename(filePath)} stayed locked after ${WIN_RETRY_ATTEMPTS} attempts; the existing file was left untouched, so retry the write once the lock (AV scan, open handle) clears`;
}
throw err;
};
try {
// writeFile can create a partial temp file before rejecting (e.g. ENOSPC).
// Own cleanup from that first write, and publish only once its mode is set.
// `flush` fsyncs the temp file's bytes before the handle closes, so the
// rename below never publishes an inode the disk has not yet received.
await writeFile(tmp, payload, { ...(existingMode !== null ? { mode: existingMode } : {}), flush: true });
if (existingMode !== null) await chmod(tmp, existingMode);
onStage?.('replace');
await replace();
} catch (err) {
await unlink(tmp).catch(() => {});
throw err;
}
onStage?.('dirSync');
await syncDirectory(dirname(filePath));
}
/**
* `writeFile`, `appendFile` and `copyFile` with the #6176 data-root guard.
*
* `atomicWrite` is the primitive almost every writer should use, and it is
* guarded. These exist for the writers that genuinely cannot: an append (which
* replaces nothing), an exclusive `{ flag: 'wx' }` create (where the flag IS
* the mechanism), a byte-for-byte copy, and a destination whose name is already
* clamped to NAME_MAX (atomicWrite's `.<pid>.<ts>.<uuid>.tmp` suffix would push
* the temp file past it).
*
* Exported as wrappers rather than left as an `assertNotRealDataWrite` call at
* each site, so the NEXT raw writer inherits the guard instead of having to
* remember the import.
*/
/** Guarded `fs/promises.writeFile`. Same signature. */
export async function writeFileGuarded(filePath, data, options) {
if (isVitestRunner()) (await loadGuard()).assertNotRealDataWrite(filePath, 'writeFile');
return writeFile(filePath, data, options);
}
/** Guarded `fs/promises.appendFile`. Same signature. */
export async function appendFileGuarded(filePath, data, options) {
if (isVitestRunner()) (await loadGuard()).assertNotRealDataWrite(filePath, 'appendFile');
return appendFile(filePath, data, options);
}
/**
* Guarded `fs/promises.copyFile` — the DESTINATION is what gets written. On
* Windows a transient lock (AV scan, indexer) on either file is retried a
* bounded number of times; a persistent lock rethrows the original error.
*/
export async function copyFileGuarded(src, dest, mode, {
attempts = WIN_RETRY_ATTEMPTS,
delayMs = WIN_RETRY_DELAY_MS,
} = {}) {
if (isVitestRunner()) (await loadGuard()).assertNotRealDataWrite(dest, 'copyFile');
for (let attempt = 1; ; attempt += 1) {
try {
return await copyFile(src, dest, mode);
} catch (err) {
if (!isWindows() || attempt >= attempts || !WIN_COPY_LOCK_CODES.includes(err.code)) throw err;
await sleep(delayMs);
}
}
}
/** Guarded `fs/promises.rename` — the DESTINATION is what gets replaced. */
export async function renameGuarded(from, to) {
if (isVitestRunner()) (await loadGuard()).assertNotRealDataWrite(to, 'rename');
return rename(from, to);
}
/** Guarded `fs/promises.rm`. Same signature. */
export async function rmGuarded(target, options) {
if (isVitestRunner()) (await loadGuard()).assertNotRealDataWrite(target, 'rm');
return rm(target, options);
}
/** Guarded `fs/promises.unlink`. Same signature. */
export async function unlinkGuarded(target) {
if (isVitestRunner()) (await loadGuard()).assertNotRealDataWrite(target, 'unlink');
return unlink(target);
}
/** Guarded `fs.createWriteStream`. Returns a Promise resolving to the WriteStream. */
export async function createWriteStreamGuarded(filePath, options) {
if (isVitestRunner()) (await loadGuard()).assertNotRealDataWrite(filePath, 'createWriteStream');
return createWriteStream(filePath, options);
}
export const MINUTE = 60 * 1000;
export const HOUR = 60 * MINUTE;
export const DAY = 24 * HOUR;
/**
* Promise-based delay. Canonical replacement for the per-module
* `const delay = (ms) => new Promise(...)` one-liners.
*
* @param {number} ms - Milliseconds to wait
* @returns {Promise<void>}
*/
export function sleep(ms) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
/**
* Format a date as YYYY-MM-DD string.
*
* @param {Date} [date=new Date()] - Date to format
* @returns {string} ISO date string (e.g., "2026-03-05")
*/
export function getDateString(date = new Date()) {
return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
}
/**
* UUID v4 regex pattern for validating account/entity IDs.
*/
export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
/**
* Truncate an id to a fixed prefix for human-readable log lines. Null-safe
* so callers can pass a possibly-missing field directly (`shortId(run?.id)`)
* without an outer truthiness check.
*
* @param {*} id - id-like value; coerced to string
* @param {number} [n=8] - prefix length
* @returns {string} prefix of length `n`, or `''` when `id` is null/undefined
*/
export function shortId(id, n = 8) {
if (id == null) return '';
return String(id).slice(0, n);
}
/**
* Safely parse a date value to epoch milliseconds.
* Returns 0 for invalid/missing dates instead of NaN.
*
* @param {string|Date|number} d - Date value to parse
* @returns {number} Epoch milliseconds, or 0 if invalid
*/
export function safeDate(d) {
const t = new Date(d).getTime();
return Number.isNaN(t) ? 0 : t;
}
/**
* Generic search filter — returns items where any of the specified fields
* contain the search string (case-insensitive).
*
* @param {Array<Object>} items - Items to filter
* @param {string} search - Search query
* @param {Array<string>} fields - Dot-notation field paths to search (e.g., 'from.name')
* @returns {Array<Object>} Filtered items
*/
export function filterBySearch(items, search, fields) {
if (!search) return items;
const q = search.toLowerCase();
return items.filter(item =>
fields.some(field => {
const val = field.includes('.') ? field.split('.').reduce((o, k) => o?.[k], item) : item[field];
return val?.toLowerCase?.().includes(q);
})
);
}
/**
* Format a duration in milliseconds to a human-readable string.
* Outputs the most appropriate unit (minutes, hours, days) based on size.
*
* @param {number} ms - Duration in milliseconds
* @returns {string} Formatted duration (e.g., "5m", "2h 30m", "3d 5h")
*
* @example
* formatDuration(30000) // "0m"
* formatDuration(300000) // "5m"
* formatDuration(7200000) // "2h 0m"
* formatDuration(90000000) // "1d 1h"
*/
export function formatDuration(ms) {
if (!ms) return '0m';
const mins = Math.floor(ms / 60000);
const hours = Math.floor(mins / 60);
const days = Math.floor(hours / 24);
if (days > 0) {
const remainingHours = hours % 24;
return `${days}d ${remainingHours}h`;
}
if (hours > 0) {
const remainingMins = mins % 60;
return `${hours}h ${remainingMins}m`;
}
return `${mins}m`;
}
export function formatBytes(bytes) {
if (!bytes) return '0 B';
const units = ['B', 'KB', 'MB', 'GB', 'TB'];
const i = Math.floor(Math.log(bytes) / Math.log(1024));
return (bytes / Math.pow(1024, i)).toFixed(i > 1 ? 1 : 0) + ' ' + units[i];
}
// =============================================================================
// FILENAME / MIME HELPERS (shared by uploads, attachments, screenshots routes)
// =============================================================================
/**
* List a directory, keep entries whose extension matches `extensions`, stat
* each, and project the survivors through `mapEntry(name, fullPath, stat)`.
* Three sibling helpers (listLoras / listGallery / listMusicLibrary) used to
* spell this loop out by hand — collapsed onto one primitive so the dir-
* missing fallback, extension filter, and stat-failure handling all stay in
* sync.
*
* - `extensions`: array of lowercased extensions including the leading dot
* (`['.png']`, `['.mp3', '.wav', ...]`). Matched against `extname(name)`
* case-insensitively so `FOO.PNG` and `foo.png` both pass.
* - `mapEntry`: async/sync `(name, fullPath, stat) => entry|null`. Return
* `null` to drop the entry. Final array preserves readdir order minus drops.
* - `requireRegularFile` (default `true`): when true, entries whose stat
* reports `!isFile()` are dropped before `mapEntry` runs (skips directories
* with matching extensions). Pass `false` to match the gallery's legacy
* behavior (only drops on stat failure).
*
* Missing directory → `[]` (no surprise 500 on a fresh install). Stat errors
* on individual entries → drop that entry (matches the prior per-site
* `.catch(() => null)` pattern).
*/
export async function listDirectoryByExtension(dir, { extensions, mapEntry, requireRegularFile = true } = {}) {
if (!Array.isArray(extensions) || extensions.length === 0) {
throw new Error('listDirectoryByExtension: extensions allowlist is required');
}
if (typeof mapEntry !== 'function') {
throw new Error('listDirectoryByExtension: mapEntry must be a function');
}
const allowed = new Set(extensions.map((e) => String(e).toLowerCase()));
const names = await readdir(dir).catch((err) => {
if (err?.code === 'ENOENT') return [];
throw err;
});
const filtered = names.filter((name) => allowed.has((extname(name) || '').toLowerCase()));
const entries = await Promise.all(filtered.map(async (name) => {
const fullPath = join(dir, name);
const s = await stat(fullPath).catch(() => null);
if (!s) return null;
if (requireRegularFile && !s.isFile()) return null;
return mapEntry(name, fullPath, s);
}));
return entries.filter((v) => v != null);
}
// Size in bytes of every file under `path`. Shells out to `du -sk` (or
// PowerShell on Windows) — orders of magnitude faster than walking with
// node's recursive readdir on large trees (hundreds of GB / 200k+ files).
// Returns 0 + logs on failure (missing tool, permission denied, timeout) so
// the Media Models endpoint stays responsive even on unusual systems instead
// of throwing and 500ing the whole route. Counted/reporting callers can pass
// `{ strict: true }` to reject instead, preserving failed-vs-legitimately-empty.
export async function dirSize(path, { strict = false } = {}) {
if (strict) {
const present = await stat(path).then(
() => true,
(err) => {
if (err?.code === 'ENOENT') return false;
throw err;
},
);
if (!present) return 0;
} else if (!existsSync(path)) {
return 0;
}
if (IS_WIN) {
// Pass the path via an env var so a literal apostrophe in the path can't
// close the PowerShell string and inject commands.
const result = await execFileAsync('powershell', [
'-NoProfile', '-Command',
'(Get-ChildItem -Recurse -File $Env:DIRSIZE_TARGET | Measure-Object -Property Length -Sum).Sum',
], { encoding: 'utf8', timeout: 60_000, env: { ...process.env, DIRSIZE_TARGET: path } }).catch((err) => ({ error: err }));
if (result.error) {
if (strict) throw result.error;
console.log(`⚠️ dirSize(${path}) failed: ${result.error.message}`);
return 0;
}
const bytes = parseInt(result.stdout.trim(), 10);
if (!Number.isFinite(bytes) || bytes < 0) {
if (strict) throw new Error(`Could not parse directory size for ${path}`);
return 0;
}
return bytes;
}
const result = await execFileAsync('du', ['-sk', path], { encoding: 'utf8', timeout: 60_000 }).catch((err) => ({ error: err }));
if (result.error) {
if (strict) throw result.error;
console.log(`⚠️ dirSize(${path}) failed: ${result.error.message}`);
return 0;
}
const kb = parseInt(result.stdout.split('\t')[0], 10);
if (!Number.isFinite(kb) || kb < 0) {
if (strict) throw new Error(`Could not parse directory size for ${path}`);
return 0;
}
return kb * 1024;
}
/** SHA-256 a string or Buffer as hex — `sha256File`'s in-memory twin. */
export const sha256Text = (value) => createHash('sha256').update(value).digest('hex');
/**
* SHA-256 a file as hex. One-shot read under 512 KB; streams above so multi-GB
* videos don't blow heap. Threshold matches `server/services/backup.js`'s
* snapshot manifest generator.
*/
const SHA256_STREAM_THRESHOLD = 512 * 1024;
export async function sha256File(path) {
const info = await stat(path);
if (info.size < SHA256_STREAM_THRESHOLD) {
const buf = await readFile(path);
return createHash('sha256').update(buf).digest('hex');
}
return new Promise((resolve, reject) => {
const hasher = createHash('sha256');
const stream = createReadStream(path);
stream.on('error', reject);
stream.pipe(hasher);
hasher.on('finish', () => resolve(hasher.digest('hex')));
hasher.on('error', reject);
});
}