@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/files/fence.js

@@ -0,0 +1,350 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { cancelledError, FileError, throwIfAborted, toFileError } from './errors.js';
+import { assertScopeAllows, inside } from './scope.js';
+export { FileError, toFileError, cancelledError, throwIfAborted } from './errors.js';
+/*
+ * The one file fence: validate -> pin the parent directory -> touch only a leaf -> O_NOFOLLOW -> atomic commit.
+ *
+ * Invariant: the process cwd is shared by everything running in the process, so ONLY code inside `pinned()` may use a
+ * relative path, and it may only use the leaf names its `Pin` hands out. Everything else (find, media encoding, git,
+ * spawned children) uses absolute paths and explicit child cwds. `pinned()` sections are mutually exclusive through an
+ * async mutex; nothing outside them waits for it.
+ */
+// ---------------------------------------------------------------------------------------------------------------------
+// pinned(): async mutex + chdir + post-chdir realpath check + finally restore
+class AsyncMutex {
+    tail = Promise.resolve();
+    holders = 0;
+    /** When the current holder acquired the lock (the files host's hung-IO watchdog reads it). */
+    heldSince = null;
+    get busy() { return this.holders > 0; }
+    /** FIFO. A waiter whose signal aborts leaves the queue without ever holding the lock (and without blocking it). */
+    async acquire(signal) {
+        throwIfAborted(signal);
+        const previous = this.tail;
+        let open;
+        const mine = new Promise(resolve => { open = resolve; });
+        this.tail = previous.then(() => mine);
+        if (signal) {
+            let onAbort;
+            const aborted = new Promise((_resolve, reject) => {
+                onAbort = () => reject(cancelledError());
+                signal.addEventListener('abort', onAbort, { once: true });
+            });
+            try {
+                await Promise.race([previous, aborted]);
+            }
+            catch (error) {
+                void previous.then(open);
+                throw error;
+            }
+            finally {
+                signal.removeEventListener('abort', onAbort);
+            }
+        }
+        else
+            await previous;
+        this.holders++;
+        this.heldSince = Date.now();
+        let released = false;
+        return () => { if (released)
+            return; released = true; this.holders--; this.heldSince = null; open(); };
+    }
+}
+const cwdLock = new AsyncMutex();
+/** Marks the async context of a running section, so a nested `pinned()` fails instead of waiting for itself forever. */
+const section = new AsyncLocalStorage();
+/** True while some `pinned()` section holds the cwd (diagnostics and tests). */
+export function cwdPinned() { return cwdLock.busy; }
+/** How long the current `pinned()` section has held the cwd, or 0 when none does (hung-IO watchdog). */
+export function pinnedForMs(now = Date.now()) { return cwdLock.heldSince === null ? 0 : Math.max(0, now - cwdLock.heldSince); }
+/** configured-roots / read-only: the pinned directory must be exactly the validated (canonical) parent. */
+export const exactParent = (pinnedReal, parent) => {
+    if (pinnedReal !== parent)
+        throw new FileError('invalid_path', 'File parent escaped allowed roots');
+};
+/** request-root: the pinned directory must still be the canonical root or below it (today's file worker check). */
+export function withinRoot(canonicalRoot) {
+    return pinnedReal => {
+        const rel = path.relative(canonicalRoot, pinnedReal);
+        if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+            throw new FileError('invalid_path', 'File parent escaped the configured workspace');
+        }
+    };
+}
+export async function pinned(parent, action, options = {}) {
+    // The lock is not re-entrant. (A continuation that outlives its section sees `active: false` and may pin normally.)
+    if (section.getStore()?.active)
+        throw new FileError('io_error', 'Nested pinned() section');
+    const release = await cwdLock.acquire(options.signal);
+    let active = false;
+    const leaf = (target) => {
+        if (!active)
+            throw new FileError('io_error', 'File directory is not pinned');
+        if (target === parent)
+            return '.';
+        if (path.dirname(target) !== parent)
+            throw new FileError('invalid_path', 'File path escaped pinned directory');
+        return path.basename(target);
+    };
+    const pin = {
+        parent,
+        leaf,
+        async regularHandle(target, flags = constants.O_RDONLY) {
+            const handle = await fs.open(leaf(target), flags | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                if (!(await handle.stat()).isFile())
+                    throw new FileError('not_regular_file', 'Not a regular file');
+                return handle;
+            }
+            catch (error) {
+                await handle.close();
+                throw error;
+            }
+        },
+    };
+    let previous;
+    const marker = { active: true };
+    try {
+        throwIfAborted(options.signal);
+        previous = process.cwd();
+        process.chdir(parent);
+        (options.verify ?? exactParent)(await fs.realpath('.'), parent);
+        active = true;
+        return await section.run(marker, () => action(pin));
+    }
+    finally {
+        active = false;
+        marker.active = false;
+        try {
+            if (previous !== undefined)
+                process.chdir(previous);
+        }
+        finally {
+            release();
+        }
+    }
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// request-root: relative slash paths below a server-given root (was filePaths.ts)
+/** Validate portable slash components before touching the filesystem. */
+export function validateRelativePath(relative) {
+    if (!relative || relative.includes('\\') || relative.includes(':') || relative.includes('\0') || path.isAbsolute(relative)) {
+        throw new FileError('invalid_path', 'Path must be relative to the selected workspace');
+    }
+    const components = relative.split('/');
+    if (components.some(component => !component || component === '.' || component === '..')) {
+        throw new FileError('invalid_path', 'Path contains an unsafe component');
+    }
+    return components;
+}
+/** A request root must be absolute: a relative one would resolve against whatever directory a section has pinned. */
+export function assertAbsoluteRoot(root) {
+    if (typeof root !== 'string' || !path.isAbsolute(root) || root.includes('\0')) {
+        throw new FileError('invalid_path', 'Workspace root must be an absolute path');
+    }
+}
+export async function canonicalRoot(root) {
+    assertAbsoluteRoot(root);
+    try {
+        return await fs.realpath(root);
+    }
+    catch (error) {
+        throw toFileError(error);
+    }
+}
+/** The configured root may itself be a symlink; none of its descendants may be. */
+export async function resolveRelativeFile(root, relative, allowMissingLeaf) {
+    const components = validateRelativePath(relative);
+    let cursor = await canonicalRoot(root);
+    for (let index = 0; index < components.length; index++) {
+        cursor = path.join(cursor, components[index]);
+        let stat;
+        try {
+            stat = await fs.lstat(cursor);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' && allowMissingLeaf && index === components.length - 1)
+                return cursor;
+            throw toFileError(error);
+        }
+        if (stat.isSymbolicLink())
+            throw new FileError('invalid_path', 'Symbolic links are not allowed');
+        if (index === components.length - 1) {
+            if (!stat.isFile())
+                throw new FileError('not_regular_file', 'Target is not a regular file');
+        }
+        else if (!stat.isDirectory()) {
+            throw new FileError('not_regular_file', 'Parent is not a directory');
+        }
+    }
+    return cursor;
+}
+/** Resolve only a leaf relative to an already pinned process cwd; never turn it back into an absolute pathname. */
+export async function resolvePinnedLeaf(_root, relative, allowMissingLeaf) {
+    const components = validateRelativePath(relative);
+    if (components.length !== 1)
+        throw new FileError('invalid_path', 'Pinned file operation requires one path component');
+    try {
+        const entry = await fs.lstat(relative);
+        if (entry.isSymbolicLink())
+            throw new FileError('invalid_path', 'Symbolic links are not allowed');
+        if (!entry.isFile())
+            throw new FileError('not_regular_file', 'Target is not a regular file');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || !allowMissingLeaf)
+            throw toFileError(error);
+    }
+    return relative;
+}
+/** Every component of a directory listing target must exist, be a directory, and not be a symlink; '' is the root. */
+export async function resolveRelativeDir(root, relative) {
+    const components = relative === '' ? [] : validateRelativePath(relative);
+    let cursor = await canonicalRoot(root);
+    for (const component of components) {
+        cursor = path.join(cursor, component);
+        let entry;
+        try {
+            entry = await fs.lstat(cursor);
+        }
+        catch (error) {
+            throw toFileError(error);
+        }
+        if (entry.isSymbolicLink())
+            throw new FileError('invalid_path', 'Symbolic links are not allowed');
+        if (!entry.isDirectory())
+            throw new FileError('not_regular_file', 'Target is not a directory');
+    }
+    return cursor;
+}
+/** Pinned variant: '' lists the pinned cwd itself, otherwise exactly one component. */
+export async function resolvePinnedDir(_root, relative) {
+    const components = relative === '' ? [] : validateRelativePath(relative);
+    if (components.length > 1)
+        throw new FileError('invalid_path', 'Pinned directory operation requires at most one path component');
+    const target = relative === '' ? '.' : path.join('.', relative);
+    let entry;
+    try {
+        entry = await fs.lstat(target);
+    }
+    catch (error) {
+        throw toFileError(error);
+    }
+    if (entry.isSymbolicLink())
+        throw new FileError('invalid_path', 'Symbolic links are not allowed');
+    if (!entry.isDirectory())
+        throw new FileError('not_regular_file', 'Target is not a directory');
+    return target;
+}
+/**
+ * Locate the deepest existing ancestor for a directory creation. Without parents the anchor must be the
+ * target's own parent (only the leaf may be missing); with parents any prefix may be missing. Existing
+ * components must be directories and never symlinks; an existing leaf counts as "already created".
+ */
+export async function resolveRelativeDirCreate(root, relative, parents) {
+    const components = validateRelativePath(relative);
+    let cursor = await canonicalRoot(root);
+    let anchorIndex = 0;
+    for (; anchorIndex < components.length; anchorIndex++) {
+        const candidate = path.join(cursor, components[anchorIndex]);
+        let entry;
+        try {
+            entry = await fs.lstat(candidate);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw toFileError(error);
+            break;
+        }
+        if (entry.isSymbolicLink())
+            throw new FileError('invalid_path', 'Symbolic links are not allowed');
+        if (!entry.isDirectory())
+            throw new FileError('not_found', 'Path is not a directory');
+        cursor = candidate;
+    }
+    const missing = components.slice(anchorIndex);
+    if (!parents && missing.length > 1) {
+        throw new FileError('not_found', 'Parent directory not found');
+    }
+    return { anchor: cursor, missing };
+}
+/** Pinned variant: create the missing components below the pinned cwd, one leaf at a time. */
+export async function resolvePinnedDirCreate(_root, relative, _parents) {
+    const components = relative === '' ? [] : validateRelativePath(relative);
+    return { anchor: '.', missing: components };
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// configured-roots / read-only: absolute paths (was StructuredFiles.resolve)
+/**
+ * Canonical roots and no descendant symlinks. Read-only previews may follow an existing alias, then pin and check its
+ * canonical parent; writable operations keep their allowed-root and no-symlink fence. Errors that come straight from
+ * the filesystem (ENOENT, EACCES, ...) are rethrown as they are: their messages are what `files.*` callers see today.
+ */
+export async function resolveAbsolute(scope, raw, missingLeaf = false, mutation = false, followLeaf = true) {
+    if (scope.kind !== 'configured-roots' && scope.kind !== 'read-only' && scope.kind !== 'filesystem') {
+        throw new FileError('invalid_argument', 'Absolute paths are not accepted in this scope');
+    }
+    const readOnly = scope.kind === 'read-only';
+    if (!path.isAbsolute(raw) || raw.includes('\0') || raw.includes('\\') || raw.split(path.sep).includes('..') || raw.length > 4096) {
+        throw new FileError('invalid_path', 'Invalid file path');
+    }
+    if (readOnly && (mutation || missingLeaf))
+        throw new FileError('permission_denied', 'Read-only file access cannot modify files');
+    if (scope.kind === 'filesystem') {
+        let target;
+        try {
+            if (followLeaf)
+                target = await fs.realpath(raw);
+            else {
+                target = path.join(await fs.realpath(path.dirname(raw)), path.basename(raw));
+                if ((await fs.lstat(target)).isSymbolicLink())
+                    throw new FileError('invalid_path', 'Cannot mutate a symbolic link');
+            }
+        }
+        catch (error) {
+            if (!missingLeaf || error.code !== 'ENOENT')
+                throw error;
+            target = path.join(await fs.realpath(path.dirname(raw)), path.basename(raw));
+        }
+        if (mutation && target === path.parse(target).root)
+            throw new FileError('permission_denied', 'Cannot modify filesystem root');
+        return target;
+    }
+    const target = readOnly ? await fs.realpath(raw) : path.resolve(raw);
+    const root = readOnly ? path.parse(target).root : scope.roots.filter(root => inside(target, root)).sort((a, b) => b.length - a.length)[0];
+    if (!root)
+        throw new FileError('invalid_path', 'Path outside allowed roots');
+    if (mutation && !readOnly && scope.roots.includes(target))
+        throw new FileError('permission_denied', 'Cannot modify file root');
+    // Detect root replacement as well as symlink components below it.
+    if (await fs.realpath(root) !== root)
+        throw new FileError('conflict', 'File root changed');
+    let cursor = root;
+    const parts = path.relative(root, target).split(path.sep).filter(Boolean);
+    for (let i = 0; i < parts.length; i++) {
+        cursor = path.join(cursor, parts[i]);
+        let stat;
+        try {
+            stat = await fs.lstat(cursor);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' && missingLeaf && i === parts.length - 1)
+                return target;
+            throw error;
+        }
+        if (stat.isSymbolicLink())
+            throw new FileError('invalid_path', 'Symbolic links are not allowed');
+        if (i < parts.length - 1 && !stat.isDirectory())
+            throw new FileError('not_regular_file', 'Parent is not a directory');
+    }
+    return target;
+}
+/** The descriptor stays valid after the pin ends; media children inherit it and never re-open the path. */
+export async function openMediaSource(scope, raw) {
+    assertScopeAllows(scope, 'media');
+    const target = await resolveAbsolute(scope, raw, false, false);
+    return pinned(path.dirname(target), pin => pin.regularHandle(target));
+}

package/dist/workstation/files/find/fileIndex.js

@@ -0,0 +1,153 @@
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+export const MAX_ENTRIES = 200_000;
+const WALK_BUDGET_MS = 1_500;
+const GIT_TIMEOUT_MS = 3_000;
+// Short: agents write files through terminals the keeper never sees.
+const CACHE_TTL_MS = 10_000;
+const CACHE_SCOPES = 4;
+const SKIPPED_DIRECTORIES = new Set(['.git', '.hg', '.svn', 'node_modules']);
+function fromEntries(entries, truncated, source) {
+    const paths = [];
+    const directories = new Set();
+    for (const entry of entries) {
+        if (entry.directory)
+            directories.add(paths.length);
+        paths.push(entry.relative);
+    }
+    return { paths, directories, truncated, source };
+}
+/** Files git tracks or would track under [scope], plus every directory on the way to them. */
+export async function gitIndex(scope, skip = () => false) {
+    const output = await new Promise(resolve => {
+        execFile('git', [
+            // A repository's own config must not run a command: fsmonitor is the one ls-files would call.
+            '-c', 'core.fsmonitor=false', '-c', 'core.quotePath=false',
+            'ls-files', '-z', '--cached', '--others', '--exclude-standard',
+        ], { cwd: scope, timeout: GIT_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } }, (error, stdout) => resolve(error ? null : stdout));
+    });
+    if (output === null)
+        return null;
+    const seen = new Set();
+    const entries = [];
+    let truncated = false;
+    for (const file of output.split('\0')) {
+        if (!file || seen.has(file))
+            continue;
+        // Same hiding rule as the walk and files.list (upload staging directories, …), per segment.
+        if (file.split('/').some(segment => segment && skip(segment)))
+            continue;
+        if (entries.length >= MAX_ENTRIES) {
+            truncated = true;
+            break;
+        }
+        let slash = file.indexOf('/');
+        while (slash > 0) {
+            const directory = file.slice(0, slash);
+            if (!seen.has(directory)) {
+                seen.add(directory);
+                entries.push({ relative: directory, directory: true });
+            }
+            slash = file.indexOf('/', slash + 1);
+        }
+        // An untracked nested repository is listed once, as `name/`: a directory, not a file.
+        if (file.endsWith('/'))
+            continue;
+        seen.add(file);
+        entries.push({ relative: file, directory: false });
+    }
+    return entries.length ? fromEntries(entries, truncated, 'git') : null;
+}
+/**
+ * Breadth-first under [scope]; symbolic links, special files and [skip]-named entries are left out.
+ * Directories on another device are listed but never entered: a mounted volume or network share
+ * (`/Volumes/*`, autofs, NFS) can be enormous or hang an `opendir` that no time budget interrupts,
+ * which would stall that search indefinitely.
+ */
+export async function walkIndex(scope, skip = () => false, budgetMs = WALK_BUDGET_MS) {
+    const deadline = Date.now() + budgetMs;
+    const entries = [];
+    const queue = [''];
+    let truncated = false;
+    let visited = 0;
+    let device;
+    try {
+        device = (await fs.stat(scope)).dev;
+    }
+    catch {
+        return fromEntries([], false, 'walk');
+    }
+    outer: for (let head = 0; head < queue.length; head++) {
+        const relative = queue[head];
+        if (Date.now() > deadline) {
+            truncated = true;
+            break;
+        }
+        let listing;
+        try {
+            listing = await fs.opendir(relative ? path.join(scope, relative) : scope);
+        }
+        catch {
+            continue;
+        }
+        try {
+            for await (const entry of listing) {
+                if (entries.length >= MAX_ENTRIES || (++visited % 256 === 0 && Date.now() > deadline)) {
+                    truncated = true;
+                    break outer;
+                }
+                if (entry.isSymbolicLink() || skip(entry.name))
+                    continue;
+                const child = relative ? `${relative}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    entries.push({ relative: child, directory: true });
+                    if (SKIPPED_DIRECTORIES.has(entry.name))
+                        continue;
+                    try {
+                        if ((await fs.lstat(path.join(scope, child))).dev === device)
+                            queue.push(child);
+                    }
+                    catch { /* Gone: nothing to enter. */ }
+                }
+                else if (entry.isFile())
+                    entries.push({ relative: child, directory: false });
+            }
+        }
+        catch { /* A directory that vanished or denied mid-read keeps what it already gave. */ }
+        finally {
+            await listing.close().catch(() => { });
+        }
+    }
+    return fromEntries(entries, truncated, 'walk');
+}
+export class FileIndexCache {
+    skip;
+    now;
+    avoidGit;
+    scopes = new Map();
+    constructor(skip = () => false, now = Date.now, 
+    /** Scopes where git's answer is not the file tree (a dotfiles repo at home ignores `*`). */
+    avoidGit = () => false) {
+        this.skip = skip;
+        this.now = now;
+        this.avoidGit = avoidGit;
+    }
+    // Bumped by every invalidate(): a build that overlapped one may hold a pre-mutation list, so it is not cached.
+    generation = 0;
+    async get(scope) {
+        const cached = this.scopes.get(scope);
+        if (cached && this.now() - cached.at < CACHE_TTL_MS)
+            return cached.index;
+        const generation = this.generation;
+        const index = (this.avoidGit(scope) ? null : await gitIndex(scope, this.skip)) ?? (await walkIndex(scope, this.skip));
+        if (generation !== this.generation)
+            return index;
+        this.scopes.delete(scope);
+        this.scopes.set(scope, { index, at: this.now() });
+        while (this.scopes.size > CACHE_SCOPES)
+            this.scopes.delete(this.scopes.keys().next().value);
+        return index;
+    }
+    invalidate() { this.generation++; this.scopes.clear(); }
+}

package/dist/workstation/files/find/fuzzy.js

@@ -0,0 +1,155 @@
+/**
+ * Quick-open style fuzzy matching over relative paths (fzf v1 shape, no dependency).
+ *
+ * A query is whitespace-separated terms; every term must match as a subsequence. Lowercase terms
+ * match case-insensitively, a term with an uppercase letter matches case-sensitively (smart case).
+ * A term without `/` is tried against the basename first: `ctrl` should rank `SessionFilesController.kt`
+ * above `controllers/readme.md`. A term with `/` always matches the whole path.
+ *
+ * Scoring per matched char, bonuses for word starts (after `/`, `_`, `-`, `.`, space, or a camelCase
+ * hump) and for runs; gaps cost. Ties go to the shorter path, then to the path itself.
+ */
+const SCORE_MATCH = 16;
+const GAP_START = -3;
+const GAP_EXTENSION = -1;
+const BONUS_SLASH = 9;
+const BONUS_BOUNDARY = 8;
+const BONUS_CAMEL = 7;
+const BONUS_CONSECUTIVE = -(GAP_START + GAP_EXTENSION);
+const BONUS_FIRST_CHAR_MULTIPLIER = 2;
+const BONUS_BASENAME = 24;
+const BONUS_BASENAME_PREFIX = 16;
+const BONUS_BASENAME_EXACT = 48;
+function isUpper(c) { return c >= 'A' && c <= 'Z'; }
+function isLower(c) { return c >= 'a' && c <= 'z'; }
+function isDigit(c) { return c >= '0' && c <= '9'; }
+function bonusAt(text, i, start) {
+    if (i === start)
+        return BONUS_SLASH;
+    const prev = text[i - 1];
+    const cur = text[i];
+    if (prev === '/')
+        return BONUS_SLASH;
+    if (prev === '_' || prev === '-' || prev === '.' || prev === ' ')
+        return BONUS_BOUNDARY;
+    if (isLower(prev) && isUpper(cur))
+        return BONUS_CAMEL;
+    if (!isDigit(prev) && isDigit(cur))
+        return BONUS_CAMEL;
+    return 0;
+}
+/** Greedy left-to-right from [from] (where `term[0]` sits), scored; null when the term runs out of text. */
+function scoreFrom(text, subject, term, from, start) {
+    const positions = [];
+    let score = 0;
+    let inGap = false;
+    let run = 0;
+    let runBonus = 0;
+    let t = 0;
+    for (let i = from; i < subject.length && t < term.length; i++) {
+        if (subject[i] === term[t]) {
+            let bonus = bonusAt(text, i, start);
+            if (run > 0)
+                bonus = Math.max(bonus, runBonus, BONUS_CONSECUTIVE);
+            else
+                runBonus = bonus;
+            score += SCORE_MATCH + (t === 0 ? bonus * BONUS_FIRST_CHAR_MULTIPLIER : bonus);
+            positions.push(i);
+            t++;
+            run++;
+            inGap = false;
+        }
+        else if (t > 0) {
+            score += inGap ? GAP_EXTENSION : GAP_START;
+            inGap = true;
+            run = 0;
+        }
+    }
+    return t === term.length ? { score, positions } : null;
+}
+const WORD_START_CANDIDATES = 8;
+/**
+ * One term against `text[start..]`. fzf v1: the forward pass finds the leftmost end, the backward
+ * pass the latest start for it, and that tight window is scored. Pure v1 misses `sfc` →
+ * **S**ession**F**iles**C**ontroller (it settles on the last `s` of "Session"), so the first few
+ * word starts holding `term[0]` before that window are scored greedily too, and the best one wins.
+ */
+export function matchTerm(text, term, start = 0) {
+    if (!term.length)
+        return { score: 0, positions: [] };
+    const caseSensitive = term !== term.toLowerCase();
+    const subject = caseSensitive ? text : text.toLowerCase();
+    let t = 0;
+    let end = -1;
+    for (let i = start; i < subject.length; i++) {
+        if (subject[i] === term[t] && ++t === term.length) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0)
+        return null;
+    let first = end;
+    t = term.length - 1;
+    for (let i = end; i >= start; i--) {
+        if (subject[i] === term[t]) {
+            first = i;
+            if (--t < 0)
+                break;
+        }
+    }
+    let best = scoreFrom(text, subject, term, first, start);
+    let tried = 0;
+    for (let i = start; i < first && tried < WORD_START_CANDIDATES; i++) {
+        if (subject[i] !== term[0] || bonusAt(text, i, start) === 0)
+            continue;
+        tried++;
+        const candidate = scoreFrom(text, subject, term, i, start);
+        if (candidate && candidate.score > best.score)
+            best = candidate;
+    }
+    return best;
+}
+/** All terms of [query] against one relative path, or null when any term misses. */
+export function matchPath(relative, terms) {
+    const base = relative.lastIndexOf('/') + 1;
+    const basename = relative.slice(base).toLowerCase();
+    let score = 0;
+    const positions = new Set();
+    for (const term of terms) {
+        let match = null;
+        let bonus = 0;
+        if (!term.includes('/')) {
+            match = matchTerm(relative, term, base);
+            if (match) {
+                const lower = term.toLowerCase();
+                bonus = basename === lower ? BONUS_BASENAME_EXACT : basename.startsWith(lower) ? BONUS_BASENAME_PREFIX : BONUS_BASENAME;
+            }
+        }
+        match ??= matchTerm(relative, term);
+        if (!match)
+            return null;
+        score += match.score + bonus;
+        for (const position of match.positions)
+            positions.add(position);
+    }
+    return { score, positions: [...positions].sort((a, b) => a - b) };
+}
+export function queryTerms(query) {
+    return query.trim().split(/\s+/).filter(Boolean);
+}
+/** Every matching index of [paths], best first: score, then shorter path, then the path itself. */
+export function rankPaths(paths, query) {
+    const terms = queryTerms(query);
+    if (!terms.length)
+        return [];
+    const ranked = [];
+    for (let index = 0; index < paths.length; index++) {
+        const match = matchPath(paths[index], terms);
+        if (match)
+            ranked.push({ index, score: match.score, positions: match.positions });
+    }
+    ranked.sort((a, b) => b.score - a.score || paths[a.index].length - paths[b.index].length
+        || (paths[a.index] < paths[b.index] ? -1 : paths[a.index] > paths[b.index] ? 1 : 0));
+    return ranked;
+}