@struktoai/mirage-core/dist/workspace/dispatcher/reader.d.ts

A Unified Virtual Filesystem For AI Agents

import { type FileStat, Limit, PathSpec, type Visibility } from '../../types.ts';
import type { MountView, NamespaceLinks } from '../../view/types.ts';
import type { MountRow } from '../types.ts';
/**
 * Whether a session sees a path: it is not hidden, and no link on it leads
 * where the session cannot see.
 *
 * The rule the dispatcher refuses a call by, and the one every answer a
 * `NamespaceReader` gives is filtered by. Mirrors Python's `sees`.
 */
export declare function sees(vis: Visibility | null, links: NamespaceLinks | null, virtual: string): boolean;
/**
 * What one session sees of the namespace: its links and its mounts.
 *
 * The namespace the dispatcher answers from owns the link table and the mount
 * table and hands this out (`Namespace.readers`); it is the one way anything
 * above the dispatcher reads them. Every answer is filtered by the rule the
 * dispatcher refuses a call by (`sees`): a hidden link, or one that leads
 * where the session cannot see, has no row, no listing entry and no target,
 * and a hidden mount is a boundary a walk stops at but is never named. It is a
 * link table itself (`NamespaceLinks`), the namespace's as the session sees
 * it, so whatever takes a link table above the dispatcher is handed this one.
 * Live, so a link made or removed mid-command is seen by the next question,
 * and synchronous, so a walk asks per entry at no dispatch cost. Mirrors
 * Python's `NamespaceReader`.
 */
export declare class NamespaceReader implements NamespaceLinks {
    private readonly links;
    private readonly allRows;
    private readonly sessionId;
    private readonly visibility;
    /**
     * @param links the namespace's link table, null where the files stand
     *   outside a workspace.
     * @param allRows every registered mount.
     * @param sessionId the session the answers are for, which decides the
     *   mounts it is told of at all.
     * @param visibility the visibility of that session, asked when a question is.
     */
    constructor(links: NamespaceLinks | null, allRows: () => readonly MountRow[], sessionId: string | null, visibility: () => Visibility | null);
    /** Whether a link table stands behind the answers. */
    get linked(): boolean;
    /** Whether the session sees `path` (`sees`). */
    visible(path: string | PathSpec): boolean;
    /**
     * Whether the session could hide anything at or under `path`, so a reader
     * of a store of its own (a repository's history, say) has to ask `visible`
     * of what it finds there.
     */
    hidesUnder(path: string | PathSpec): boolean;
    /**
     * Every registered mount, hides and sessions aside, longest prefix first:
     * what a facade's record asks of the mount table.
     */
    rows(): MountRow[];
    /** The registered mount owning `path` by longest prefix. */
    owner(path: string): MountRow | null;
    /**
     * The mounts the session is told of at all, hides aside. A session's own
     * documents mount is one only it is told of.
     */
    served(): MountRow[];
    /**
     * The mounts whose root the session sees. A hidden mount is left out of
     * every list here, as it is left out of a listing, so no list names it.
     */
    shown(): MountRow[];
    /**
     * The prefix of the mount serving `path`, without a trailing slash; null
     * for a path the session cannot see.
     */
    mountOf(path: string | PathSpec): string | null;
    /** Whether `path` is the root of a mount the session sees. */
    isMount(path: string | PathSpec): boolean;
    /**
     * The mount roots strictly under `path`, sorted, without a trailing slash;
     * a hidden one reported by the nearest folder above it the session sees.
     */
    submounts(path: string | PathSpec): string[];
    /** Whether a link the session sees stands at `path`. */
    isLink(path: string): boolean;
    /**
     * The link standing at a path, its own row; null where none stands or the
     * session cannot see it.
     */
    linkStatAt(path: string): FileStat | null;
    /**
     * Every link the session sees, to its stored target. A session that hides
     * nothing sees the whole table, which is asked of no link.
     */
    symlinkTargets(): ReadonlyMap<string, string>;
    /** The links at any depth under a directory the session sees, each with its own row. */
    linkStatsBelow(directory: string): [string, FileStat][];
    /**
     * The names of the links directly under a directory that the session sees,
     * which a listing's link marks need.
     */
    linkNamesUnder(directory: string): Set<string>;
    /**
     * A link's stored target, as typed; null where no link stands or the
     * session cannot see it.
     */
    readlink(path: string): string | null;
    /**
     * Where a path the session sees leads, every link followed; one it cannot
     * see, a link on it leading through a hide included, is left as typed, for
     * the dispatcher to refuse. Throws CycleError where a link loop stands in
     * the walk.
     */
    follow(path: string): string;
    /**
     * A path with every link above its final name followed, the walk a call
     * that acts on the name itself is given; a path the session cannot see is
     * left as typed.
     * Throws CycleError where a link loop stands in the walk.
     */
    followParent(path: string): string;
    /**
     * The names a directory holds only as namespace structure: the mounts
     * below it and its links, by their first segment under it.
     */
    owed(directory: string): string[];
    /**
     * Where the mount boundaries are, as the session sees them.
     *
     * Every mount below a path, hidden or not, is a boundary a backend's own
     * walk stops at: a mount the session cannot see still shadows the parent
     * backend's keys under its prefix. Only the visible ones are ever named. A
     * walk through the dispatcher (`crossing`) descends into each mount itself,
     * so it has no boundary to stop at: no mount below a path, and no mount
     * root; and it takes no mount's shortcut, so no mount answers a function
     * for it or narrows its search. A walk's `walkLimit` on each mount is
     * `command`'s (walkBound), resolved through the session's `profile`, the
     * mount's and the workspace's command limits and the running command's
     * declared one; without a command, the one every command shares. Both
     * default to the running command's and its session's.
     */
    mounts(crossing: boolean, command?: string | null, profile?: Readonly<Record<string, Limit>>): MountView;
}
//# sourceMappingURL=reader.d.ts.map