@sema-agent/core/dist/engine/execution-env/symlink-chain.d.ts

Stateless, task-oriented AI agent core

import { type FileError, type Result, type SymlinkChain } from "../harness/types.js";
/**
 * Anchor a RELATIVE symlink target at its link's own directory, UNFOLDED, with exactly one separator between the two.
 * A root directory (`/`, `C:\`, `\\host\share\`) already ends in its own separator, and a second one mints a spelling
 * (`//private/tmp`) that no guarded row matches; `path.resolve`/`join` would fix the separator and fold `..`, which
 * this walk may not do. `separator` is the one the caller's `dirname` writes (a pure function of its inputs); a
 * backslash terminates only where it IS a separator — on a POSIX tree `/a/b\` is an ordinary name.
 */
export declare function anchorAtLinkDir(linkDir: string, target: string, separator: string): string;
/** The walk's bound (the reference CLI's own); the terminal canonicalizer refuses at 16, so this only bounds what is REPORTED. */
export declare const SYMLINK_CHAIN_MAX_HOPS = 64;
/** The one-hop primitive (`FileSystem.readLink`'s signature): the target a symlink NAMES, not followed. The walk reads `invalid` / `not_found` / `not_directory` as the end of the chain. */
export type SymlinkHopReader = (path: string) => Promise<Result<string, FileError>>;
/**
 * THE leaf symlink chain walk ({@link import("../harness/types.js").FileSystem.canonicalChain}'s answer) over the
 * smallest primitive: `readLink` on `start` (resolved, absolute), then on each target, until a hop is not a link, is
 * absent, repeats, or the bound is reached. A relative target is anchored at its link's directory and never folded
 * (`..` is the filesystem's to resolve in the next lookup: a lexical fold reads `bridge/../next` as `next` and misses
 * every link behind `bridge`). The addressed spelling seeds the cycle table, so it is never a hop of its own chain;
 * on win32 a share-shaped hop is kept and ends the walk unprobed. Any other failure is `err`, never a shortened chain.
 * `NodeExecutionEnv.canonicalChain` is this function over its own read; a non-`node:fs` host supplies its own.
 */
export declare function walkSymlinkChain(start: string, readLink: SymlinkHopReader): Promise<Result<SymlinkChain, FileError>>;