@struktoai/mirage-core/dist/utils/key_prefix.d.ts

A Unified Virtual Filesystem For AI Agents

import { PathSpec } from '../types.ts';
/**
 * Normalize a key prefix, the one rule every object-key backend applies on
 * both hosts: strip leading slashes and ensure one trailing slash. A prefix
 * that is empty once its leading slashes are gone ('', '/') is no prefix at
 * all, so a root-spelled prefix never puts a slash in front of every key.
 * Mirrors Python `normalize` (`utils/key_prefix.py`).
 */
export declare function normalize(raw: string | undefined): string;
/** Prepend a normalized prefix to a virtual path. */
export declare function apply(prefix: string, path: string): string;
/** Same as apply() but guarantees a trailing slash for LIST-style ops. */
export declare function applyDir(prefix: string, path: string): string;
/** Strip a normalized prefix from a backend-returned key. */
export declare function strip(prefix: string, key: string): string;
/**
 * Remove a mount prefix from a virtual path at a path boundary.
 *
 * A sibling that only shares the prefix as a string (`/database` vs a
 * `/data` prefix) is left untouched.
 *
 * Example:
 *   stripMount('/data/sub/x.txt', '/data')  -> '/sub/x.txt'
 *   stripMount('/database/x.txt', '/data')  -> '/database/x.txt'
 *   stripMount('/data', '/data')            -> '/'
 *   stripMount('/x.txt', '')                -> '/x.txt'
 *
 * A glob word's quote marks (`glob_walk.markGlobs`) read as the characters
 * they stand for, one for one: a quoted prefix still names its mount
 * (`'/team+'/*`), and the rest keeps its marks.
 */
export declare function stripMount(virtual: string, prefix: string): string;
/**
 * Whether `candidate` is `root` itself or sits below it.
 *
 * A boundary-aware prefix test, so a sibling that merely shares the string
 * (`/data/xy` against `/data/x`) is not counted. Both sides are compared
 * without a trailing slash, because a backend may have keyed a directory
 * either way. Mirrors Python `under_path` (`utils/key_prefix.py`).
 *
 * Example:
 *   underPath('/data/x/y', '/data/x')  -> true
 *   underPath('/data/x', '/data/x/')   -> true
 *   underPath('/data/xy', '/data/x')   -> false
 */
export declare function underPath(candidate: string, root: string): boolean;
/**
 * Backend key for a virtual path under a mount prefix.
 *
 * Example:
 *   mountKey('/data/sub/x.txt', '/data')  -> 'sub/x.txt'
 *   mountKey('/data', '/data')            -> ''
 *   mountKey('/x.txt', '')                -> 'x.txt'
 */
export declare function mountKey(virtual: string, prefix: string): string;
/**
 * Backend key for a child virtual path, derived from its parent.
 *
 * A child shares the parent's mount prefix, so its key is the child
 * virtual path with the same prefix removed. The prefix length is
 * recovered from the parent's `virtual`/`vfsPath` pair, so no mount
 * context is needed.
 *
 * Example:
 *   rekey('/data/sub', 'sub', '/data/sub/x.txt')  -> 'sub/x.txt'
 *   rekey('/data', '', '/data/x.txt')             -> 'x.txt'
 */
export declare function rekey(parentVirtual: string, parentVfsPath: string, child: string): string;
/**
 * Recover a mount prefix from a virtual path and its backend key.
 *
 * The inverse of stamping: given a path's virtual form and the key the
 * mount stamped, return the mount prefix that was stripped off.
 *
 * Example:
 *   mountPrefixOf('/data/sub', 'sub')  -> '/data'
 *   mountPrefixOf('/data', '')         -> '/data'
 *   mountPrefixOf('/x.txt', 'x.txt')   -> ''
 */
export declare function mountPrefixOf(virtual: string, vfsPath: string): string;
/**
 * The path below the mount prefix, spelled as the virtual path is: `/` for
 * the mount root, else the slash-led remainder with any trailing slash kept.
 * Mirrors Python's `raw_path_of`.
 */
export declare function rawPathOf(path: PathSpec): string;
export declare function mountedPath(root: PathSpec, mountPath: string): PathSpec;
/** The path a backend key under `keyPrefix` names, addressed like `root`. Mirrors Python `key_path`. */
export declare function keyPath(root: PathSpec, keyPrefix: string, key: string): PathSpec;
export declare function respelled(path: PathSpec, rawPath: string): PathSpec;
/** The path of `name` inside the directory `spec`, on its mount. Mirrors Python's `child_spec`. */
export declare function childSpec(spec: PathSpec, name: string): PathSpec;
//# sourceMappingURL=key_prefix.d.ts.map