/**
 * Materialize pulled context items to a local directory, mirroring the
 * write-to-disk pattern in `rules/pull-bundle.ts`. Used by the `pull_context` /
 * `pull_inbox` MCP tools when the agent passes a `writeToDir` -- it lets a coding
 * agent drop scoped context straight into its working tree.
 */
import { mkdir, writeFile } from 'node:fs/promises';
type WritableItem = {
    id: string;
    name: string;
    content: string | null;
};
/**
 * Reduce server-supplied text to a single safe path segment, or '' when nothing
 * usable survives.
 *
 * The one definition every on-disk name derives from — item filenames here, and
 * the bundle directory in `context/pull.ts`. Both take their name from a value
 * the dashboard returns, so a weakened rule in either place is a traversal, and
 * two copies of it is exactly how one of them ends up weakened.
 */
export declare function sanitizePathSegment(value: string): string;
/**
 * Turn an item's display name into a safe single-segment `.md` filename,
 * falling back to the item id when the name reduces to nothing.
 */
export declare function safeItemFileName(name: string, id: string): string;
export type WriteItemsDeps = {
    mkdirFn?: typeof mkdir;
    writeFileFn?: typeof writeFile;
    /**
     * Where the machine cache lives, so a `writeToDir` leaves a record of what it
     * put on disk. Injected by tests; defaults to `~/.auden/state/machine-cache.json`.
     */
    machineCachePath?: string;
};
/**
 * Write each item's `content` to `dir` as `<safe-name>.md`, creating the
 * directory if needed. Items with `null` content (e.g. assets, whose bytes live
 * in object storage) are skipped. Filename collisions are disambiguated by
 * appending the item id. Returns the absolute-ish paths written, in order.
 *
 * **Every file written is recorded** in the machine cache, keyed by its absolute
 * path and carrying the item's id and the hash of the bytes actually written
 * (`state/machine-cache.ts`). Before this, a `writeToDir` recorded nothing at
 * all: no placement, no baseline, nothing that could later say where an item had
 * been put or whether the user had since edited it. That is what made this path
 * the one way to get canonical context onto disk with no trace, and the record
 * is half the fix — the other half is the scope guard the caller applies
 * (`mcp/write-scope.ts`).
 *
 * The record is machine-local by construction, and deliberately not a committed
 * placement: `writeToDir` is a one-shot transfer to a directory the caller
 * named, not a subscription, so writing a placement record would claim the repo
 * had subscribed to something it had not.
 *
 * A file that would land on an auto-discovered guide file at the destination
 * root — `AGENTS.md` and friends — is skipped and reported. The directory guard
 * cannot catch these: `writeToDir: "."` is legal, and the filename is derived
 * from a server-supplied item name only at this point.
 */
export declare function writeItemsToDir(items: readonly WritableItem[], dir: string, deps?: WriteItemsDeps): Promise<{
    written: string[];
    skipped: string[];
}>;
export {};
//# sourceMappingURL=write-items.d.ts.map