@crouter/api 0.3.386 → 0.3.388

package/dist/core/events/types.d.ts

@@ -0,0 +1,68 @@
+export type EventLevel = 'error' | 'warn' | 'info' | 'debug';
+export type EventComponent = 'daemon' | 'broker' | 'control-plane' | 'front' | 'sentinel';
+export type EventOutcome = 'succeeded' | 'failed' | 'skipped';
+export type RetryDisposition = 'auto' | 'manual' | 'fatal';
+export type OperationId = string & {
+    readonly __operationId: unique symbol;
+};
+export declare const errorClassCodes: readonly ["rate_limit", "overloaded", "connection", "auth", "protocol", "context_overflow", "wedged", "model_not_found", "unknown"];
+export type ErrorClassCode = (typeof errorClassCodes)[number];
+export interface ErrorClass {
+    class: ErrorClassCode;
+    status?: number;
+    provider?: string;
+    retry_disposition?: RetryDisposition;
+}
+export interface EventError {
+    type: string;
+    message: string;
+    stack?: string;
+    cause?: string;
+}
+export type EventField = null | boolean | number | string | readonly EventField[] | {
+    readonly [key: string]: EventField;
+};
+export interface EventEnvelope {
+    v: 1;
+    ts: string;
+    level: EventLevel;
+    event: string;
+    component: EventComponent;
+    operation_id: OperationId;
+    node_id?: string;
+    stream_id?: string;
+    duration_ms?: number;
+    outcome?: EventOutcome;
+    attempt?: number;
+    error_class?: ErrorClass;
+    error?: EventError;
+    fields?: Readonly<Record<string, EventField>>;
+    record_truncated?: true;
+    original_bytes?: number;
+    dropped_fields_count?: number;
+}
+export interface BuildEnvelopeInput {
+    ts?: string;
+    level: EventLevel;
+    event: string;
+    component: EventComponent;
+    operation_id?: string;
+    node_id?: string;
+    stream_id?: string;
+    duration_ms?: number;
+    outcome?: EventOutcome;
+    attempt?: number;
+    error_class?: ErrorClass;
+    error?: unknown;
+    fields?: Readonly<Record<string, unknown>>;
+}
+export interface ErrorClassHints {
+    status?: number;
+    provider?: string;
+    retry_disposition?: RetryDisposition;
+}
+export interface OperationIdContext {
+    current(): OperationId | undefined;
+    run<T>(operationId: string, callback: () => T): T;
+    fresh<T>(callback: (operationId: OperationId) => T): T;
+}

package/dist/core/events/types.js

@@ -0,0 +1,11 @@
+export const errorClassCodes = [
+    'rate_limit',
+    'overloaded',
+    'connection',
+    'auth',
+    'protocol',
+    'context_overflow',
+    'wedged',
+    'model_not_found',
+    'unknown',
+];

package/dist/core/exclusive-lock.d.ts

@@ -0,0 +1,34 @@
+/** The pid currently holding this lock, read straight off the marker name (the
+ *  token opens with the owner's pid). Null when the lock is free, unowned, or
+ *  names a token we cannot parse. Lets a caller tell "my child is doing the
+ *  work" apart from "my child is queued behind someone else's work" without
+ *  any new bookkeeping. */
+export declare function exclusiveLockOwnerPid(path: string): number | null;
+/**
+ * Block until `path` is no longer held by a LIVE other process, or the wait
+ * runs out. Unlike `withExclusiveDirectoryLock*` this never CLAIMS the lock —
+ * it is for a reader that only needs the holder's transition to be over before
+ * it looks at the directory the holder is rewriting.
+ *
+ * Returns immediately when the lock is free, when its marker names this very
+ * process (a caller waiting on its own lock would otherwise deadlock), or when
+ * the named owner is gone — a dead holder's transition is already over, however
+ * it ended.
+ */
+export declare function awaitExclusiveLockRelease(path: string, timeoutMs: number): void;
+export interface ExclusiveLockOptions {
+    /** Grace before a lock that names no owner at all is cleared. */
+    staleMs?: number;
+    timeoutMs?: number;
+    /** The error thrown when the wait runs out, so callers keep their own remediation. */
+    timeoutError?: () => Error;
+}
+/**
+ * Run a short filesystem transition under a token-checked, crash-reclaimable
+ * directory lock. A holder that dies releases immediately — the next contender
+ * sees a dead pid in the marker name — while a live holder is never stolen from,
+ * however long its operation runs.
+ */
+export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: ExclusiveLockOptions): T;
+/** Run an awaited operation under the same token-checked directory lock. */
+export declare function withExclusiveDirectoryLockAsync<T>(path: string, operation: () => Promise<T>, options?: ExclusiveLockOptions): Promise<T>;

package/dist/core/exclusive-lock.js

@@ -0,0 +1,197 @@
+import { existsSync, mkdirSync, readdirSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+const MARKER_PREFIX = 'owner.';
+// Contention backoff. The first polls stay tight so an uncontended hand-off is
+// still effectively immediate; the interval then doubles to a ceiling so a lock
+// held across a long operation (a corpus migration, say) cannot turn a crowd of
+// waiters into a filesystem hot loop — N waiters at a fixed 10ms is N*100
+// tryAcquire() syscall bursts per second on one directory.
+const POLL_MS = 10;
+const POLL_MAX_MS = 250;
+const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_TIMEOUT_MS = 5_000;
+function nextPollMs(current) { return Math.min(current * 2, POLL_MAX_MS); }
+function pause(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+function pauseAsync(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
+function markerPath(path, token) { return `${path}/${MARKER_PREFIX}${token}`; }
+function observedMarkerToken(path) {
+    try {
+        return readdirSync(path).find((entry) => entry.startsWith(MARKER_PREFIX))?.slice(MARKER_PREFIX.length) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The token opens with the owner's pid, so liveness reads off the name. */
+function ownerIsAlive(token) {
+    const pid = Number(token.split('.', 1)[0]);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function isEmptyDirectory(path) {
+    try {
+        return readdirSync(path).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function ageMs(path) {
+    try {
+        return Date.now() - statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+// Reclamation is bound to the exact instance it observed: it unlinks ONLY that
+// token's marker, then removes the now-empty directory with an empty-guarded
+// rmdir. A successor holds a different random token — a different marker name —
+// so a lagging reclaimer that saw the old dead lock can never strip a live
+// successor: its unlink targets a name that no longer exists.
+function reclaimIfOwnerGone(path, staleMs) {
+    const token = observedMarkerToken(path);
+    if (token !== null) {
+        if (ownerIsAlive(token))
+            return;
+        try {
+            unlinkSync(markerPath(path, token));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    else {
+        // Nothing names an owner. A live holder always has its marker, so this is a
+        // crash between mkdir and the marker write, or a lock left in some older
+        // shape; age is the only evidence, and an empty-guarded rmdir still cannot
+        // take a successor that has since claimed the name.
+        if (ageMs(path) <= staleMs)
+            return;
+        if (!isEmptyDirectory(path)) {
+            rmSync(path, { recursive: true, force: true });
+            return;
+        }
+    }
+    try {
+        rmdirSync(path);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ENOTEMPTY' && code !== 'EEXIST')
+            throw error;
+    }
+}
+/** The pid currently holding this lock, read straight off the marker name (the
+ *  token opens with the owner's pid). Null when the lock is free, unowned, or
+ *  names a token we cannot parse. Lets a caller tell "my child is doing the
+ *  work" apart from "my child is queued behind someone else's work" without
+ *  any new bookkeeping. */
+export function exclusiveLockOwnerPid(path) {
+    const token = observedMarkerToken(path);
+    if (token === null)
+        return null;
+    const pid = Number(token.split('.', 1)[0]);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+/**
+ * Block until `path` is no longer held by a LIVE other process, or the wait
+ * runs out. Unlike `withExclusiveDirectoryLock*` this never CLAIMS the lock —
+ * it is for a reader that only needs the holder's transition to be over before
+ * it looks at the directory the holder is rewriting.
+ *
+ * Returns immediately when the lock is free, when its marker names this very
+ * process (a caller waiting on its own lock would otherwise deadlock), or when
+ * the named owner is gone — a dead holder's transition is already over, however
+ * it ended.
+ */
+export function awaitExclusiveLockRelease(path, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let pollMs = POLL_MS;
+    for (;;) {
+        const token = observedMarkerToken(path);
+        if (token === null)
+            return;
+        if (Number(token.split('.', 1)[0]) === process.pid)
+            return;
+        if (!ownerIsAlive(token))
+            return;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return;
+        pause(Math.min(pollMs, remaining));
+        pollMs = nextPollMs(pollMs);
+    }
+}
+function tryAcquire(path, staleMs) {
+    const token = `${process.pid}.${randomUUID()}`;
+    try {
+        mkdirSync(path, { mode: 0o700 });
+        writeFileSync(markerPath(path, token), '', { flag: 'wx', mode: 0o600 });
+        return { path, token };
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        reclaimIfOwnerGone(path, staleMs);
+        return null;
+    }
+}
+/**
+ * Run a short filesystem transition under a token-checked, crash-reclaimable
+ * directory lock. A holder that dies releases immediately — the next contender
+ * sees a dead pid in the marker name — while a live holder is never stolen from,
+ * however long its operation runs.
+ */
+export function withExclusiveDirectoryLock(path, operation, options = {}) {
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let pollMs = POLL_MS;
+    let lock = tryAcquire(path, staleMs);
+    while (lock === null) {
+        if (Date.now() >= deadline) {
+            throw options.timeoutError?.() ?? new Error(`timed out waiting for the exclusive lock: ${path}`);
+        }
+        pause(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+        pollMs = nextPollMs(pollMs);
+        lock = tryAcquire(path, staleMs);
+    }
+    try {
+        return operation();
+    }
+    finally {
+        if (existsSync(markerPath(lock.path, lock.token)))
+            rmSync(lock.path, { recursive: true, force: true });
+    }
+}
+/** Run an awaited operation under the same token-checked directory lock. */
+export async function withExclusiveDirectoryLockAsync(path, operation, options = {}) {
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let pollMs = POLL_MS;
+    let lock = tryAcquire(path, staleMs);
+    while (lock === null) {
+        if (Date.now() >= deadline) {
+            throw options.timeoutError?.() ?? new Error(`timed out waiting for the exclusive lock: ${path}`);
+        }
+        await pauseAsync(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+        pollMs = nextPollMs(pollMs);
+        lock = tryAcquire(path, staleMs);
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        if (existsSync(markerPath(lock.path, lock.token)))
+            rmSync(lock.path, { recursive: true, force: true });
+    }
+}

package/dist/core/fs-utils.d.ts

@@ -0,0 +1,44 @@
+/** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved. */
+export declare function realpathOrSelf(p: string): string;
+/** Expand a leading `~` against `homeDir` (pi's own convention). Other forms
+ *  — absolute, relative, `~user` — pass through as pi leaves them. */
+export declare function expandTilde(p: string, homeDir?: string): string;
+/** Collapse the home prefix to `~` so a path reads short. The inverse of
+ *  `expandTilde`, and the ONE collapse every surface prints paths through. */
+export declare function tildify(p: string, homeDir?: string): string;
+export declare function ensureDir(dir: string): void;
+export declare function writeJson(path: string, data: unknown): void;
+export interface AtomicWriteOptions {
+    /** Force this mode regardless of any existing file's mode. Omitted: preserve the existing file's mode, or default a new file to `0o600`. */
+    mode?: number;
+    /** Require the parent to exist, rather than recreate a removed project root. */
+    createParent?: boolean;
+}
+export declare function atomicWriteJson(path: string, data: unknown, opts?: AtomicWriteOptions): void;
+/** Force a file's written bytes to stable storage. */
+export declare function syncFile(path: string): void;
+/** Force a directory's entry changes to stable storage. */
+export declare function syncDirectory(path: string): void;
+/** Replace one file's contents in a single rename, so a concurrent reader — the
+ *  tmux inbox watcher, or crtrd serving a ticket read — sees either the old
+ *  bytes or the new ones and never a truncated file mid-write. */
+export declare function atomicWriteText(path: string, content: string | Uint8Array, opts?: AtomicWriteOptions): void;
+export declare function readJson<T = unknown>(path: string): T;
+export declare function readJsonIfExists<T = unknown>(path: string): T | null;
+/** Missing or corrupt reads as absent, so a crash artifact never throws. */
+export declare function readJsonOrNull<T = unknown>(path: string): T | null;
+export declare function readTextIfExists(path: string): string | null;
+export declare function readText(path: string): string;
+export declare function writeText(path: string, content: string): void;
+export declare function isDir(path: string): boolean;
+export declare function isSymlink(path: string): boolean;
+export declare function pathExists(path: string): boolean;
+export declare function listDirs(path: string): string[];
+export declare function listEntries(path: string): string[];
+export declare function removePath(path: string): void;
+export declare function linkOrCopy(target: string, linkPath: string, opts?: {
+    noSymlink?: boolean;
+}): 'symlink' | 'copy';
+export declare function readSymlinkTarget(path: string): string | null;
+export declare function walkFiles(root: string, predicate?: (name: string) => boolean, skipDir?: (name: string) => boolean): string[];
+export declare function nowIso(): string;

package/dist/core/fs-utils.js

@@ -0,0 +1,208 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, realpathSync, closeSync, fsyncSync, openSync, } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { homedir, platform } from 'node:os';
+/** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved. */
+export function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Expand a leading `~` against `homeDir` (pi's own convention). Other forms
+ *  — absolute, relative, `~user` — pass through as pi leaves them. */
+export function expandTilde(p, homeDir = homedir()) {
+    if (p === '~')
+        return homeDir;
+    if (p.startsWith('~/') || (platform() === 'win32' && p.startsWith('~\\')))
+        return join(homeDir, p.slice(2));
+    return p;
+}
+/** Collapse the home prefix to `~` so a path reads short. The inverse of
+ *  `expandTilde`, and the ONE collapse every surface prints paths through. */
+export function tildify(p, homeDir = homedir()) {
+    if (p === homeDir)
+        return '~';
+    if (p.startsWith(homeDir + sep))
+        return '~' + p.slice(homeDir.length);
+    return p;
+}
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true });
+}
+export function writeJson(path, data) {
+    ensureDir(dirname(path));
+    writeFileSync(path, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+export function atomicWriteJson(path, data, opts) {
+    atomicWriteText(path, JSON.stringify(data, null, 2) + '\n', opts);
+}
+/** Force a file's written bytes to stable storage. */
+export function syncFile(path) {
+    const fd = openSync(path, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Force a directory's entry changes to stable storage. */
+export function syncDirectory(path) {
+    const fd = openSync(path, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Replace one file's contents in a single rename, so a concurrent reader — the
+ *  tmux inbox watcher, or crtrd serving a ticket read — sees either the old
+ *  bytes or the new ones and never a truncated file mid-write. */
+export function atomicWriteText(path, content, opts) {
+    if (opts?.createParent !== false)
+        ensureDir(dirname(path));
+    const temp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+    const mode = opts?.mode ?? (existsSync(path) ? statSync(path).mode & 0o777 : 0o600);
+    try {
+        writeFileSync(temp, content, { mode });
+        chmodSync(temp, mode);
+        renameSync(temp, path);
+    }
+    finally {
+        if (existsSync(temp))
+            rmSync(temp, { force: true });
+    }
+}
+export function readJson(path) {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+export function readJsonIfExists(path) {
+    try {
+        return readJson(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/** Missing or corrupt reads as absent, so a crash artifact never throws. */
+export function readJsonOrNull(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function readTextIfExists(path) {
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, 'utf8');
+}
+export function readText(path) {
+    return readFileSync(path, 'utf8');
+}
+export function writeText(path, content) {
+    ensureDir(dirname(path));
+    writeFileSync(path, content, 'utf8');
+}
+export function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+export function pathExists(path) {
+    return existsSync(path);
+}
+export function listDirs(path) {
+    if (!existsSync(path))
+        return [];
+    return readdirSync(path, { withFileTypes: true })
+        .filter((d) => d.isDirectory() || d.isSymbolicLink())
+        .map((d) => d.name);
+}
+export function listEntries(path) {
+    if (!existsSync(path))
+        return [];
+    return readdirSync(path);
+}
+export function removePath(path) {
+    if (!existsSync(path) && !isSymlink(path))
+        return;
+    rmSync(path, { recursive: true, force: true });
+}
+export function linkOrCopy(target, linkPath, opts = {}) {
+    ensureDir(dirname(linkPath));
+    removePath(linkPath);
+    const isWindows = platform() === 'win32';
+    if (!opts.noSymlink && !isWindows) {
+        // The kernel resolves a relative link against the link's *physical*
+        // directory, so both ends must be realpaths: computing `..` hops from a
+        // lexical path whose ancestor is itself a symlink (macOS /tmp →
+        // /private/tmp) walks up the wrong chain and silently creates a dangling
+        // link, since symlinkSync never checks the target.
+        const rel = relative(realpathOrSelf(dirname(linkPath)), realpathOrSelf(target));
+        try {
+            symlinkSync(rel, linkPath, isDir(target) ? 'dir' : 'file');
+            return 'symlink';
+        }
+        catch {
+            cpSync(target, linkPath, { recursive: true });
+            return 'copy';
+        }
+    }
+    cpSync(target, linkPath, { recursive: true });
+    return 'copy';
+}
+export function readSymlinkTarget(path) {
+    try {
+        return readlinkSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+export function walkFiles(root, predicate = () => true, skipDir = () => false) {
+    const out = [];
+    if (!existsSync(root))
+        return out;
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!skipDir(e.name))
+                    stack.push(full);
+            }
+            else if (e.isFile() && predicate(e.name))
+                out.push(full);
+        }
+    }
+    return out;
+}
+export function nowIso() {
+    return new Date().toISOString();
+}