@north-light/crouter 0.3.154

package/dist/core/keybindings/match.js

@@ -0,0 +1,105 @@
+import { normalizeStroke } from './resolve.js';
+const KEY_LABELS = {
+    enter: 'Enter',
+    escape: 'Esc',
+    tab: 'Tab',
+    backspace: 'Backspace',
+    delete: 'Delete',
+    space: 'Space',
+    up: 'Up',
+    down: 'Down',
+    left: 'Left',
+    right: 'Right',
+    pageup: 'PageUp',
+    pagedown: 'PageDown',
+    home: 'Home',
+    end: 'End',
+};
+export function formatStroke(stroke) {
+    let key;
+    let modifiers;
+    if (stroke === '+') {
+        key = '+';
+        modifiers = [];
+    }
+    else if (stroke.endsWith('++')) {
+        key = '+';
+        modifiers = stroke.slice(0, -2).split('+');
+    }
+    else {
+        const parts = stroke.split('+');
+        key = parts.pop();
+        modifiers = parts;
+    }
+    const labels = modifiers.map((modifier) => modifier[0].toUpperCase() + modifier.slice(1));
+    // A bare printable key renders EXACTLY as it must be typed: a binding of `d`
+    // is shown as `d`, never `D`. Uppercasing it advertised a shift chord that
+    // canonicalizes to `shift+d` and therefore matches nothing — a dead key the
+    // hint itself told the user to press. Modifier chords keep the conventional
+    // uppercase label (`Ctrl+X`, `Alt+I`, `Shift+G`), where the case is cosmetic
+    // because the modifier, not the letter's case, carries the stroke.
+    labels.push(KEY_LABELS[key] ?? (key.length === 1 && modifiers.length > 0 ? key.toUpperCase() : key));
+    return labels.join('+');
+}
+export function formatGesture(gesture) {
+    return gesture.split(' > ').map(formatStroke).join(' then ');
+}
+export function formatBinding(bindingSet, id) {
+    const gestures = bindingSet.gestures(id);
+    return gestures.length === 0 ? 'Disabled' : gestures.map(formatGesture).join(' / ');
+}
+export function canonicalTerminalStroke(raw) {
+    let key = null;
+    if (raw.upArrow)
+        key = 'up';
+    else if (raw.downArrow)
+        key = 'down';
+    else if (raw.leftArrow)
+        key = 'left';
+    else if (raw.rightArrow)
+        key = 'right';
+    else if (raw.return)
+        key = 'enter';
+    else if (raw.escape)
+        key = 'escape';
+    else if (raw.shiftTab)
+        return 'shift+tab';
+    else if (raw.tab)
+        key = 'tab';
+    else if (raw.backspace)
+        key = 'backspace';
+    else if (raw.delete)
+        key = 'delete';
+    else if (raw.pageUp)
+        key = 'pageup';
+    else if (raw.pageDown)
+        key = 'pagedown';
+    else if (raw.home)
+        key = 'home';
+    else if (raw.end)
+        key = 'end';
+    else if (raw.input?.length === 1)
+        key = raw.input === ' ' ? 'space' : raw.input;
+    if (key === null)
+        return null;
+    const modifiers = [];
+    if (raw.ctrl)
+        modifiers.push('ctrl');
+    if (raw.meta)
+        modifiers.push('alt');
+    if (raw.shift)
+        modifiers.push('shift');
+    try {
+        return normalizeStroke([...modifiers, key].join('+'));
+    }
+    catch {
+        return null;
+    }
+}
+export function matchesTerminalInput(bindingSet, id, raw) {
+    const stroke = canonicalTerminalStroke(raw);
+    return stroke !== null && bindingSet.gestures(id).includes(stroke);
+}
+export function matchesPiTuiInput(bindingSet, id, input, matchesKey) {
+    return bindingSet.gestures(id).some((gesture) => !gesture.includes(' > ') && matchesKey(input, gesture));
+}

package/dist/core/keybindings/persistence.d.ts

@@ -0,0 +1,14 @@
+import type { BindingId } from './catalog.js';
+import type { SparseKeybindingOverrides } from './types.js';
+export declare class KeybindingConcurrentEditError extends Error {
+    readonly latestKeybindings: unknown;
+    constructor(latestKeybindings: unknown);
+}
+export interface PersistKeybindingsOptions {
+    readonly expectedKeybindings?: unknown;
+}
+export interface PersistedKeybindings {
+    readonly path: string;
+    readonly overrides: SparseKeybindingOverrides<BindingId>;
+}
+export declare function persistUserKeybindings(prospectiveOverrides: unknown, options?: PersistKeybindingsOptions): PersistedKeybindings;

package/dist/core/keybindings/persistence.js

@@ -0,0 +1,31 @@
+import { isDeepStrictEqual } from 'node:util';
+import { configPath, updateRawConfigAtomically } from '../config.js';
+import { normalizeSparseOverrides } from './resolve.js';
+export class KeybindingConcurrentEditError extends Error {
+    latestKeybindings;
+    constructor(latestKeybindings) {
+        super('keybindings changed on disk; reload before saving');
+        this.name = 'KeybindingConcurrentEditError';
+        this.latestKeybindings = latestKeybindings;
+    }
+}
+export function persistUserKeybindings(prospectiveOverrides, options = {}) {
+    const overrides = normalizeSparseOverrides(prospectiveOverrides);
+    const path = configPath('user');
+    if (path === null)
+        throw new Error('user config path is unavailable');
+    updateRawConfigAtomically('user', (latest) => {
+        if (Object.hasOwn(options, 'expectedKeybindings')
+            && !isDeepStrictEqual(latest['keybindings'], options.expectedKeybindings)) {
+            throw new KeybindingConcurrentEditError(latest['keybindings']);
+        }
+        const next = { ...latest };
+        delete next['canvasNav'];
+        if (Object.keys(overrides).length === 0)
+            delete next['keybindings'];
+        else
+            next['keybindings'] = overrides;
+        return next;
+    });
+    return Object.freeze({ path, overrides: Object.freeze({ ...overrides }) });
+}

package/dist/core/keybindings/resolve.d.ts

@@ -0,0 +1,22 @@
+import type { BindingId } from './catalog.js';
+import type { BindingDefinition, BindingResolution, KeybindingDiagnostic, SparseKeybindingOverrides } from './types.js';
+export declare class GestureSyntaxError extends Error {
+    constructor(message: string);
+}
+export declare function normalizeStroke(raw: string): string;
+/**
+ * Split a binding expression into its gesture list. A comma separates gestures
+ * only when it stands between two non-empty gestures; a comma with nothing on
+ * one side is the comma KEY itself, so `,` is bindable and `, , c` reads as the
+ * comma key plus `c`. This mirrors the sequence separator `>`, which is only a
+ * separator when surrounded by strokes.
+ */
+export declare function splitGestureExpression(expression: string): string[];
+export declare function normalizeGesture(raw: string, definition?: Pick<BindingDefinition, 'inputKind'>): string;
+export declare function resolveKeybindings(rawOverrides?: unknown): BindingResolution<BindingId>;
+export declare function resolveUserKeybindings(): BindingResolution<BindingId>;
+export declare function normalizeSparseOverrides(rawOverrides: unknown): SparseKeybindingOverrides<BindingId>;
+export declare class KeybindingValidationError extends Error {
+    readonly diagnostics: readonly KeybindingDiagnostic[];
+    constructor(diagnostics: readonly KeybindingDiagnostic[]);
+}

package/dist/core/keybindings/resolve.js

@@ -0,0 +1,333 @@
+import { isDeepStrictEqual } from 'node:util';
+import { BINDING_CATALOG, BINDING_IDS, SAFETY_REQUIREMENTS } from './catalog.js';
+import { readRawScopeConfig } from '../config.js';
+const MODIFIER_ORDER = ['ctrl', 'alt', 'shift'];
+const INPUT_MODIFIERS = new Set(['ctrl', 'alt', 'shift', 'meta']);
+const NAMED_KEYS = new Set([
+    'enter', 'escape', 'tab', 'backspace', 'delete', 'space', 'up', 'down',
+    'left', 'right', 'pageup', 'pagedown', 'home', 'end',
+]);
+const KEY_ALIASES = { return: 'enter', esc: 'escape' };
+export class GestureSyntaxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GestureSyntaxError';
+    }
+}
+function tmuxNotation(value) {
+    const match = value.match(/^((?:[CMS]-)+)(.+)$/i);
+    if (match === null)
+        return value;
+    const modifiers = match[1].split('-').filter(Boolean).map((token) => {
+        if (token.toUpperCase() === 'C')
+            return 'ctrl';
+        if (token.toUpperCase() === 'M')
+            return 'alt';
+        return 'shift';
+    });
+    return `${modifiers.join('+')}+${match[2]}`;
+}
+export function normalizeStroke(raw) {
+    const value = tmuxNotation(raw.trim());
+    if (value === '')
+        throw new GestureSyntaxError('a stroke cannot be empty');
+    let rawKey;
+    let modifierParts;
+    if (value === '+') {
+        rawKey = '+';
+        modifierParts = [];
+    }
+    else if (value.endsWith('++')) {
+        rawKey = '+';
+        modifierParts = value.slice(0, -2).split('+');
+    }
+    else {
+        const parts = value.split('+');
+        if (parts.some((part) => part === ''))
+            throw new GestureSyntaxError(`invalid stroke "${raw}"`);
+        rawKey = parts.pop();
+        modifierParts = parts;
+    }
+    const inputModifiers = modifierParts.map((part) => part.toLowerCase());
+    if (inputModifiers.some((modifier) => !INPUT_MODIFIERS.has(modifier))) {
+        throw new GestureSyntaxError(`unsupported modifier in "${raw}"`);
+    }
+    const modifiers = inputModifiers.map((modifier) => modifier === 'meta' ? 'alt' : modifier);
+    if (new Set(modifiers).size !== modifiers.length) {
+        throw new GestureSyntaxError(`duplicate modifier in "${raw}"`);
+    }
+    let key = KEY_ALIASES[rawKey.toLowerCase()] ?? rawKey;
+    if (key.length === 1 && key >= 'A' && key <= 'Z') {
+        key = key.toLowerCase();
+        if (!modifiers.includes('shift'))
+            modifiers.push('shift');
+    }
+    else if (key.length !== 1) {
+        key = key.toLowerCase();
+    }
+    if (!(key.length === 1 && key.charCodeAt(0) >= 32 && key.charCodeAt(0) <= 126) && !NAMED_KEYS.has(key)) {
+        throw new GestureSyntaxError(`unsupported key "${rawKey}"`);
+    }
+    const ordered = MODIFIER_ORDER.filter((modifier) => modifiers.includes(modifier));
+    return [...ordered, key].join('+');
+}
+/**
+ * Split a binding expression into its gesture list. A comma separates gestures
+ * only when it stands between two non-empty gestures; a comma with nothing on
+ * one side is the comma KEY itself, so `,` is bindable and `, , c` reads as the
+ * comma key plus `c`. This mirrors the sequence separator `>`, which is only a
+ * separator when surrounded by strokes.
+ */
+export function splitGestureExpression(expression) {
+    const gestures = [];
+    let current = '';
+    for (let index = 0; index < expression.length; index += 1) {
+        const char = expression[index];
+        if (char !== ',') {
+            current += char;
+            continue;
+        }
+        const isSeparator = current.trim() !== '' && expression.slice(index + 1).trim() !== '';
+        if (isSeparator) {
+            gestures.push(current);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    gestures.push(current);
+    return gestures;
+}
+export function normalizeGesture(raw, definition) {
+    const parts = raw.trim().split(/\s+>\s+/);
+    if (parts.length > 2)
+        throw new GestureSyntaxError('a gesture may contain at most two strokes');
+    const normalized = parts.map(normalizeStroke);
+    if (normalized.length === 2 && definition?.inputKind !== 'tmux-sequence') {
+        throw new GestureSyntaxError('two-stroke sequences are supported only by tmux sequence actions');
+    }
+    if (definition?.inputKind === 'tmux-sequence' && normalized.length !== 2) {
+        throw new GestureSyntaxError('this action requires a two-stroke tmux sequence');
+    }
+    if (definition?.inputKind === 'tmux-menu-selector') {
+        if (normalized.length !== 1)
+            throw new GestureSyntaxError('a menu selector must be one stroke');
+        const stroke = normalized[0];
+        const pieces = stroke.split('+');
+        const key = pieces.at(-1);
+        const modifiers = pieces.slice(0, -1);
+        if ((key.length !== 1 && key !== 'space') || modifiers.some((modifier) => modifier !== 'shift')) {
+            throw new GestureSyntaxError('a menu selector must be one printable character');
+        }
+    }
+    return normalized.join(' > ');
+}
+function normalizeList(raw, definition) {
+    if (!Array.isArray(raw))
+        throw new GestureSyntaxError('the override must be an array of gesture strings');
+    const normalized = [];
+    for (const item of raw) {
+        if (typeof item !== 'string')
+            throw new GestureSyntaxError('every override entry must be a gesture string');
+        const gesture = normalizeGesture(item, definition);
+        if (!normalized.includes(gesture))
+            normalized.push(gesture);
+    }
+    return Object.freeze(normalized);
+}
+function contextsOverlap(a, b) {
+    return a.contexts.some((context) => b.contexts.includes(context));
+}
+function isTmuxRoot(definition) {
+    return definition.contexts.includes('tmux.root');
+}
+function isInPane(definition) {
+    return !isTmuxRoot(definition)
+        && definition.inputKind !== 'tmux-menu-selector'
+        && definition.inputKind !== 'tmux-sequence';
+}
+function firstStroke(gesture) {
+    return gesture.split(' > ')[0];
+}
+function gesturesConflict(leftDefinition, leftGesture, rightDefinition, rightGesture) {
+    const leftSequence = leftGesture.includes(' > ');
+    const rightSequence = rightGesture.includes(' > ');
+    if (contextsOverlap(leftDefinition, rightDefinition)) {
+        if (leftSequence && rightSequence)
+            return leftGesture === rightGesture;
+        if (leftSequence || rightSequence)
+            return firstStroke(leftGesture) === firstStroke(rightGesture);
+        return leftGesture === rightGesture;
+    }
+    const leftRoot = isTmuxRoot(leftDefinition);
+    const rightRoot = isTmuxRoot(rightDefinition);
+    if (!leftRoot && !rightRoot)
+        return false;
+    if (leftRoot && rightRoot && leftSequence && rightSequence)
+        return leftGesture === rightGesture;
+    if (leftRoot && rightRoot)
+        return firstStroke(leftGesture) === firstStroke(rightGesture);
+    if (leftRoot && isInPane(rightDefinition))
+        return firstStroke(leftGesture) === rightGesture;
+    if (rightRoot && isInPane(leftDefinition))
+        return leftGesture === firstStroke(rightGesture);
+    return false;
+}
+function defaultGestures(definition) {
+    return Object.freeze(definition.defaults.map((gesture) => normalizeGesture(gesture, definition)));
+}
+class FrozenBindingMap {
+    #map;
+    constructor(entries) { this.#map = new Map(entries); }
+    get size() { return this.#map.size; }
+    get(key) { return this.#map.get(key); }
+    has(key) { return this.#map.has(key); }
+    entries() { return this.#map.entries(); }
+    keys() { return this.#map.keys(); }
+    values() { return this.#map.values(); }
+    forEach(callbackfn, thisArg) {
+        for (const [key, value] of this.#map)
+            callbackfn.call(thisArg, value, key, this);
+    }
+    [Symbol.iterator]() { return this.#map[Symbol.iterator](); }
+}
+function diagnostic(code, message, offendingValue, bindingId, relatedBindingIds) {
+    return Object.freeze({ severity: 'error', code, message, offendingValue, ...(bindingId ? { bindingId } : {}), ...(relatedBindingIds ? { relatedBindingIds: Object.freeze([...relatedBindingIds]) } : {}) });
+}
+function collisionPairs(records) {
+    const out = [];
+    for (let leftIndex = 0; leftIndex < records.length; leftIndex += 1) {
+        const left = records[leftIndex];
+        for (let rightIndex = leftIndex + 1; rightIndex < records.length; rightIndex += 1) {
+            const right = records[rightIndex];
+            for (const leftGesture of left.gestures) {
+                const conflict = right.gestures.find((rightGesture) => gesturesConflict(left.definition, leftGesture, right.definition, rightGesture));
+                if (conflict !== undefined) {
+                    out.push([left, right, leftGesture.includes(' > ') ? leftGesture : conflict]);
+                    break;
+                }
+            }
+        }
+    }
+    return out;
+}
+function requirementSatisfied(records, context, capability) {
+    return records.some((record) => record.definition.safety === capability
+        && record.gestures.length > 0
+        && record.definition.contexts.includes(context));
+}
+function rejectCollidingUserOverrides(records, diagnostics) {
+    while (true) {
+        const rejected = new Set();
+        for (const [left, right, gesture] of collisionPairs(records)) {
+            if (left.source === 'user')
+                rejected.add(left);
+            if (right.source === 'user')
+                rejected.add(right);
+            if (left.source === 'default' && right.source === 'default') {
+                throw new Error(`keybinding catalog default collision: ${left.definition.id} / ${right.definition.id} (${gesture})`);
+            }
+            diagnostics.push(diagnostic('collision', `${left.definition.id} and ${right.definition.id} both claim ${gesture} in overlapping contexts`, gesture, left.source === 'user' ? left.definition.id : right.definition.id, [left.definition.id, right.definition.id]));
+        }
+        if (rejected.size === 0)
+            return;
+        for (const record of rejected) {
+            record.gestures = defaultGestures(record.definition);
+            record.source = 'default';
+        }
+    }
+}
+export function resolveKeybindings(rawOverrides = undefined) {
+    const diagnostics = [];
+    let overrides = {};
+    if (rawOverrides !== undefined) {
+        if (rawOverrides === null || typeof rawOverrides !== 'object' || Array.isArray(rawOverrides)) {
+            diagnostics.push(diagnostic('invalid-keybindings', 'keybindings must be an object keyed by catalog binding ID', rawOverrides));
+        }
+        else {
+            overrides = rawOverrides;
+        }
+    }
+    for (const [id, value] of Object.entries(overrides)) {
+        if (!BINDING_IDS.has(id)) {
+            diagnostics.push(diagnostic('unknown-binding', `unknown keybinding ID: ${id}`, value, id));
+        }
+    }
+    const records = BINDING_CATALOG.map((definition) => {
+        const defaults = defaultGestures(definition);
+        if (!Object.hasOwn(overrides, definition.id))
+            return { definition, gestures: defaults, source: 'default' };
+        const rawOverride = overrides[definition.id];
+        try {
+            return { definition, gestures: normalizeList(rawOverride, definition), source: 'user', rawOverride };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            diagnostics.push(diagnostic('invalid-override', `${definition.id}: ${message}`, rawOverride, definition.id));
+            return { definition, gestures: defaults, source: 'default' };
+        }
+    });
+    rejectCollidingUserOverrides(records, diagnostics);
+    for (const requirement of SAFETY_REQUIREMENTS) {
+        if (requirementSatisfied(records, requirement.context, requirement.capability))
+            continue;
+        const offenders = records.filter((record) => record.source === 'user'
+            && record.definition.safety === requirement.capability
+            && record.definition.contexts.includes(requirement.context));
+        diagnostics.push(diagnostic('unreachable', `${requirement.context} must retain an enabled ${requirement.capability} binding`, offenders.map((record) => record.rawOverride), offenders[0]?.definition.id, offenders.map((record) => record.definition.id)));
+        for (const offender of offenders) {
+            offender.gestures = defaultGestures(offender.definition);
+            offender.source = 'default';
+        }
+    }
+    rejectCollidingUserOverrides(records, diagnostics);
+    const entries = records.map((record) => {
+        const effective = Object.freeze({
+            definition: record.definition,
+            gestures: record.gestures,
+            source: record.source,
+        });
+        return [record.definition.id, effective];
+    });
+    const bindings = new FrozenBindingMap(entries);
+    const result = {
+        bindings,
+        diagnostics: Object.freeze(diagnostics),
+        get(id) {
+            const found = bindings.get(id);
+            if (found === undefined)
+                throw new Error(`unknown crouter keybinding ID: ${id}`);
+            return found;
+        },
+        gestures(id) { return this.get(id).gestures; },
+    };
+    return Object.freeze(result);
+}
+export function resolveUserKeybindings() {
+    const raw = readRawScopeConfig('user');
+    return resolveKeybindings(raw?.keybindings);
+}
+export function normalizeSparseOverrides(rawOverrides) {
+    const resolved = resolveKeybindings(rawOverrides);
+    if (resolved.diagnostics.length > 0) {
+        throw new KeybindingValidationError(resolved.diagnostics);
+    }
+    const sparse = {};
+    for (const definition of BINDING_CATALOG) {
+        const effective = resolved.get(definition.id);
+        const defaults = defaultGestures(definition);
+        if (effective.source === 'user' && !isDeepStrictEqual(effective.gestures, defaults)) {
+            sparse[definition.id] = [...effective.gestures];
+        }
+    }
+    return sparse;
+}
+export class KeybindingValidationError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        super(diagnostics[0]?.message ?? 'invalid keybindings');
+        this.name = 'KeybindingValidationError';
+        this.diagnostics = diagnostics;
+    }
+}

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

@@ -0,0 +1,37 @@
+export type BindingInputKind = 'terminal' | 'tmux-sequence' | 'tmux-menu-selector' | 'host-global';
+export type BindingSafetyCapability = 'dismiss-modal' | 'leave-screen' | 'save-keybindings';
+export interface BindingDefinition<Id extends string = string> {
+    readonly id: Id;
+    readonly group: string;
+    readonly name: string;
+    readonly description: string;
+    readonly defaults: readonly string[];
+    readonly inputKind: BindingInputKind;
+    readonly contexts: readonly string[];
+    readonly safety?: BindingSafetyCapability;
+}
+export interface EffectiveBinding<Id extends string = string> {
+    readonly definition: BindingDefinition<Id>;
+    readonly gestures: readonly string[];
+    readonly source: 'default' | 'user';
+}
+export type KeybindingDiagnosticCode = 'invalid-keybindings' | 'unknown-binding' | 'invalid-override' | 'collision' | 'unreachable';
+export interface KeybindingDiagnostic {
+    readonly severity: 'error';
+    readonly code: KeybindingDiagnosticCode;
+    readonly bindingId?: string;
+    readonly relatedBindingIds?: readonly string[];
+    readonly offendingValue: unknown;
+    readonly message: string;
+}
+export interface SafetyRequirement {
+    readonly context: string;
+    readonly capability: BindingSafetyCapability;
+}
+export interface BindingResolution<Id extends string = string> {
+    readonly bindings: ReadonlyMap<Id, EffectiveBinding<Id>>;
+    readonly diagnostics: readonly KeybindingDiagnostic[];
+    get(id: Id): EffectiveBinding<Id>;
+    gestures(id: Id): readonly string[];
+}
+export type SparseKeybindingOverrides<Id extends string = string> = Partial<Record<Id, string[]>>;

package/dist/core/keybindings/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/locked-file.d.ts

@@ -0,0 +1,24 @@
+export type LockResult<T> = {
+    result: T;
+    next?: string;
+};
+/** Throws if this lock was compromised (stolen/expired) since acquisition. Callers that write
+ *  from INSIDE the critical section must call it immediately before that write, because the
+ *  post-`fn` check cannot un-write a file the callback already replaced. */
+export type LockHeldGuard = () => void;
+export interface LockedFileBackend {
+    withLockAsync<T>(fn: (current: string | undefined, assertLockHeld: LockHeldGuard) => Promise<LockResult<T>>): Promise<T>;
+    /** The current whole-file contents, or undefined when the file does not exist yet.
+     *  Lock-free: every writer replaces the file by atomic rename. */
+    readUnlocked(): string | undefined;
+}
+/** A 0600 JSON file guarded by a cross-process `proper-lockfile` lock on its own path. */
+export declare class LockedJsonFile implements LockedFileBackend {
+    private readonly path;
+    constructor(path: string);
+    readUnlocked(): string | undefined;
+    private ensureFile;
+    /** Acquire the lock without blocking the event loop, keeping every read-modify-write
+     *  callback on the same asynchronous path. */
+    withLockAsync<T>(fn: (current: string | undefined, assertLockHeld: LockHeldGuard) => Promise<LockResult<T>>): Promise<T>;
+}

package/dist/core/locked-file.js

@@ -0,0 +1,91 @@
+// locked-file.ts — crouter's cross-process locked read/modify/write primitive for the
+// small JSON state files the runtime co-owns with pi: pi's own `auth.json` (api keys and
+// non-managed OAuth credentials) and crouter's per-provider subscription pool files, which
+// hold every managed account's own credential.
+//
+// The lock is `proper-lockfile` on the target path, so a crouter process and a pi process
+// contending for `auth.json` still exclude each other: same library, same lock path, and
+// same `realpath: false` option. Every callback runs asynchronously and returns
+// `{ result, next }`; `next === undefined` means "no write". Every write lands by atomic
+// tmp+rename (pool callers do their own, inside the callback), so a whole snapshot is the
+// only thing on disk and READS need no lock at all -- `readUnlocked` serves them. That
+// matters: pi asks its CredentialStore for every registered provider (~75) whenever it
+// builds a model runtime, and routing those through the lock made each boot serialize
+// behind seconds of lock acquisition backoff.
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import lockfile from 'proper-lockfile';
+const WRITE_OPTIONS = { encoding: 'utf-8', mode: 0o600 };
+// proper-lockfile decides a held lock is abandoned when its lockdir mtime is older than
+// the acquirer's `stale`, and refreshes the mtime on the holder's `update` timer. The holder
+// refreshes well inside the staleness threshold so long-running callbacks remain protected.
+const LOCK_STALE_MS = 30_000;
+const LOCK_UPDATE_MS = 5_000;
+/** A 0600 JSON file guarded by a cross-process `proper-lockfile` lock on its own path. */
+export class LockedJsonFile {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    readUnlocked() {
+        return existsSync(this.path) ? readFileSync(this.path, 'utf-8') : undefined;
+    }
+    ensureFile() {
+        const dir = dirname(this.path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (!existsSync(this.path)) {
+            writeFileSync(this.path, '{}', WRITE_OPTIONS);
+            chmodSync(this.path, 0o600);
+        }
+    }
+    /** Acquire the lock without blocking the event loop, keeping every read-modify-write
+     *  callback on the same asynchronous path. */
+    async withLockAsync(fn) {
+        this.ensureFile();
+        let release;
+        let compromised;
+        const throwIfCompromised = () => {
+            if (compromised)
+                throw compromised;
+        };
+        try {
+            release = await lockfile.lock(this.path, {
+                // A different realpath setting would derive a DIFFERENT lock path for a symlinked
+                // auth.json and silently stop excluding other writers.
+                realpath: false,
+                retries: { retries: 10, factor: 2, minTimeout: 100, maxTimeout: 10_000, randomize: true },
+                stale: LOCK_STALE_MS,
+                // Refresh the lockdir mtime well inside `stale` so long-running callbacks remain protected.
+                update: LOCK_UPDATE_MS,
+                onCompromised: (err) => {
+                    compromised = err;
+                },
+            });
+            throwIfCompromised();
+            const current = existsSync(this.path) ? readFileSync(this.path, 'utf-8') : undefined;
+            const { result, next } = await fn(current, throwIfCompromised);
+            throwIfCompromised();
+            if (next !== undefined) {
+                // Atomic replace, so a concurrent lock-free reader can never observe a half-written
+                // file (the reason `readUnlocked` is safe).
+                const tmp = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+                writeFileSync(tmp, next, WRITE_OPTIONS);
+                chmodSync(tmp, 0o600);
+                renameSync(tmp, this.path);
+            }
+            throwIfCompromised();
+            return result;
+        }
+        finally {
+            if (release) {
+                try {
+                    await release();
+                }
+                catch {
+                    // A compromised lock's release throws; the compromise itself already surfaced.
+                }
+            }
+        }
+    }
+}

package/dist/core/log.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_ROTATING_RECORD_BYTES = 65536;
+/** Synchronously appends one complete NDJSON record, retaining active + .1 + .2. */
+export declare function appendRotatingRecord(path: string, recordWithoutLf: string): boolean;