@north-light/api 0.3.579 → 0.3.587

package/dist/core/keybindings/resolve.js

@@ -0,0 +1,348 @@
+import { isDeepStrictEqual } from 'node:util';
+import { BINDING_CATALOG, BINDING_IDS, SAFETY_REQUIREMENTS } from './catalog.js';
+import { normalizeTmuxPassthrough, 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');
+        }
+    }
+    if (definition?.inputKind === 'tmux-global-action') {
+        if (normalized.length !== 1)
+            throw new GestureSyntaxError('a global menu shortcut must be one stroke');
+        const modifiers = normalized[0].split('+').slice(0, -1);
+        if (!modifiers.includes('ctrl') && !modifiers.includes('alt')) {
+            throw new GestureSyntaxError('a global menu shortcut must include Ctrl or Alt');
+        }
+    }
+    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);
+}
+/** Resolve keybindings and tmux passthrough from one immutable user-config snapshot. */
+export function resolveUserKeybindingSettings() {
+    const raw = readRawScopeConfig('user');
+    return Object.freeze({
+        bindings: resolveKeybindings(raw?.keybindings),
+        tmuxPassthrough: Object.freeze(normalizeTmuxPassthrough(raw?.tmux_passthrough)),
+    });
+}
+export function resolveUserKeybindings() {
+    return resolveUserKeybindingSettings().bindings;
+}
+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/layout-migrate/index.d.ts

@@ -0,0 +1,38 @@
+import { OldToNewPathMap } from './paths.js';
+export { OldToNewPathMap, oldToNewPathMap } from './paths.js';
+export interface LayoutMigration {
+    map: OldToNewPathMap;
+    moved: number;
+    /** Exactly the filesystem operations that changed a source path. */
+    changes: string[];
+    /** One line per leftover the migration resolved itself (a dry run lists what it would do). */
+    resolutions: string[];
+    /** Old stored path prefix → new path, rewritten as text in migrated markdown bodies. */
+    bodyPaths: Array<[string, string]>;
+    /** Credential sources that did not exist; legitimate when the old volume never held one. */
+    absentCredentials: string[];
+    dryRun: boolean;
+}
+export declare function isJunkFile(name: string): boolean;
+/** Where a leftover the new layout has no place for is kept: `runtime/set-aside/<kind>/<name>`, never overwriting. */
+export declare function setAsidePath(migration: LayoutMigration, kind: string, name: string): string;
+/** Move a leftover aside (a rename; never a copy). */
+export declare function setAside(from: string, kind: string, migration: LayoutMigration, name?: string): string;
+/**
+ * What to do with a destination that already exists before a move. A file is
+ * renamed atomically, so a file present at both paths was never written by
+ * this migration: an identical copy drops the source, an empty file is
+ * removed, and anything else is kept aside under `runtime/set-aside/replaced/`.
+ */
+export type Claim = {
+    action: 'merge' | 'drop-source' | 'remove-destination' | 'set-aside-destination';
+    line?: string;
+};
+export declare function claim(from: string, to: string, migration: LayoutMigration, wholeDirectory?: boolean): Claim;
+/** Rename within the volume; merge an existing directory on interrupted runs, never overwrite a file. */
+export declare function movePath(from: string, to: string, migration: LayoutMigration, wholeDirectory?: boolean): void;
+/** Dry-run lines for a move: the claims the real run would make, without touching anything. */
+export declare function previewMove(from: string, to: string, migration: LayoutMigration, wholeDirectory?: boolean): void;
+export declare function sameFile(from: string, to: string): boolean;
+export declare function daemonAnswers(socketPath: string): Promise<boolean>;
+export declare function migrateLayout(dryRun: boolean): Promise<LayoutMigration | null>;