@socketsecurity/lib 6.0.8 → 6.0.9

package/dist/external-tools/skillspector/types.d.ts

@@ -3,7 +3,7 @@
  *   third-party-skill scanner (sibling to AgentShield); pinned to a git SHA
  *   because upstream has no PyPI release or GH tags as of 2026-06-01.
  */
-export type SkillSpectorSource = 'vfs' | 'pipx' | 'path' | 'dlx';
+export type SkillSpectorSource = 'vfs' | 'pipx' | 'path' | 'uv' | 'dlx';
 /**
  * A resolved SkillSpector installation.
  */
@@ -18,6 +18,8 @@ export interface ResolvedSkillSpector {
      * - 'vfs' — extracted from the SEA binary's VFS
      * - 'pipx' — `which skillspector` returned a pipx-installed venv binary
      * - 'path' — `which skillspector` returned a non-pipx binary on PATH
+     * - 'uv' — `uv sync --locked` against a uv project's .venv (the most
+     *   locked-down tier; every transitive version pinned in uv.lock)
      * - 'dlx' — created a venv under ~/.socket/_dlx/skillspector/<sha>/
      */
     readonly source: SkillSpectorSource;

package/dist/external-tools/uv/asset-names.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Upstream uv release asset-name mapping per `platform-arch`. uv
+ *   publishes per-platform archives under
+ *   https://github.com/astral-sh/uv/releases/download/<X.Y.Z>/. The release tag
+ *   is the bare semver (no `v` prefix), unlike most upstream projects. Each
+ *   archive wraps the binary one directory deep (`uv-<triple>/uv[.exe]`), so
+ *   callers should pass `strip: 1` to the extractor — or, equivalently, look up
+ *   the binary inside the archive's stem directory.
+ */
+export interface UvAssetEntry {
+    /**
+     * Full asset filename (no version interpolation — uv asset names are
+     * version-free).
+     */
+    readonly asset: string;
+}
+export declare const UV_ASSET_MAP: Readonly<Record<string, UvAssetEntry>>;
+export declare function getUvAssetEntry(platformArch: string): UvAssetEntry | undefined;
+export interface UvDownloadOptions {
+    /**
+     * Uv release version, e.g. `'0.10.11'` (no `v` prefix — astral-sh/uv tags
+     * releases as bare semver).
+     */
+    version: string;
+    /**
+     * Fleet platform-arch token — looked up in `UV_ASSET_MAP`.
+     */
+    platformArch: string;
+}
+/**
+ * Build the GitHub release-asset download URL for an upstream uv binary.
+ * Returns `undefined` when no entry exists for the requested platform-arch.
+ *
+ * Reference: https://github.com/astral-sh/uv/releases.
+ */
+export declare function getUvDownloadUrl(options: UvDownloadOptions): string | undefined;

package/dist/external-tools/uv/asset-names.js

@@ -0,0 +1,73 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_object = require('../../primordials/object.js');
+
+//#region src/external-tools/uv/asset-names.ts
+/**
+* @file Upstream uv release asset-name mapping per `platform-arch`. uv
+*   publishes per-platform archives under
+*   https://github.com/astral-sh/uv/releases/download/<X.Y.Z>/. The release tag
+*   is the bare semver (no `v` prefix), unlike most upstream projects. Each
+*   archive wraps the binary one directory deep (`uv-<triple>/uv[.exe]`), so
+*   callers should pass `strip: 1` to the extractor — or, equivalently, look up
+*   the binary inside the archive's stem directory.
+*/
+const UV_ASSET_MAP = require_primordials_object.ObjectFreeze({
+	__proto__: null,
+	"darwin-arm64": require_primordials_object.ObjectFreeze({
+		__proto__: null,
+		asset: "uv-aarch64-apple-darwin.tar.gz"
+	}),
+	"darwin-x64": require_primordials_object.ObjectFreeze({
+		__proto__: null,
+		asset: "uv-x86_64-apple-darwin.tar.gz"
+	}),
+	"linux-arm64": require_primordials_object.ObjectFreeze({
+		__proto__: null,
+		asset: "uv-aarch64-unknown-linux-gnu.tar.gz"
+	}),
+	"linux-arm64-musl": require_primordials_object.ObjectFreeze({
+		__proto__: null,
+		asset: "uv-aarch64-unknown-linux-musl.tar.gz"
+	}),
+	"linux-x64": require_primordials_object.ObjectFreeze({
+		__proto__: null,
+		asset: "uv-x86_64-unknown-linux-gnu.tar.gz"
+	}),
+	"linux-x64-musl": require_primordials_object.ObjectFreeze({
+		__proto__: null,
+		asset: "uv-x86_64-unknown-linux-musl.tar.gz"
+	}),
+	"win-arm64": require_primordials_object.ObjectFreeze({
+		__proto__: null,
+		asset: "uv-aarch64-pc-windows-msvc.zip"
+	}),
+	"win-x64": require_primordials_object.ObjectFreeze({
+		__proto__: null,
+		asset: "uv-x86_64-pc-windows-msvc.zip"
+	})
+});
+function getUvAssetEntry(platformArch) {
+	return UV_ASSET_MAP[platformArch];
+}
+/**
+* Build the GitHub release-asset download URL for an upstream uv binary.
+* Returns `undefined` when no entry exists for the requested platform-arch.
+*
+* Reference: https://github.com/astral-sh/uv/releases.
+*/
+function getUvDownloadUrl(options) {
+	const { platformArch, version } = {
+		__proto__: null,
+		...options
+	};
+	const entry = UV_ASSET_MAP[platformArch];
+	if (!entry) return;
+	return `https://github.com/astral-sh/uv/releases/download/${version}/` + entry.asset;
+}
+
+//#endregion
+exports.UV_ASSET_MAP = UV_ASSET_MAP;
+exports.getUvAssetEntry = getUvAssetEntry;
+exports.getUvDownloadUrl = getUvDownloadUrl;

package/dist/external-tools/uv/from-download.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file `uvFromDownload()` — fetches upstream uv and returns a `ResolvedUv`
+ *   pointing at the extracted binary. uv tarballs wrap the binary in a
+ *   `<asset-stem>/` directory; the extractor strips that level so the binary
+ *   sits at the cache-dir root.
+ */
+import type { BinaryDownloader } from '../from-download';
+import type { HashSpec } from '../../integrity';
+import type { ResolvedUv } from './types';
+export interface UvFromDownloadOptions {
+    version: string;
+    platformArch: string;
+    integrity?: HashSpec | undefined;
+    cacheDir?: string | undefined;
+    downloader?: BinaryDownloader | undefined;
+}
+export declare function uvFromDownload(options: UvFromDownloadOptions): Promise<ResolvedUv | undefined>;

package/dist/external-tools/uv/from-download.js

@@ -0,0 +1,50 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../../_virtual/_rolldown/runtime.js');
+const require_paths_socket = require('../../paths/socket.js');
+const require_external_tools_from_download = require('../from-download.js');
+const require_external_tools_uv_asset_names = require('./asset-names.js');
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path);
+
+//#region src/external-tools/uv/from-download.ts
+/**
+* @file `uvFromDownload()` — fetches upstream uv and returns a `ResolvedUv`
+*   pointing at the extracted binary. uv tarballs wrap the binary in a
+*   `<asset-stem>/` directory; the extractor strips that level so the binary
+*   sits at the cache-dir root.
+*/
+async function uvFromDownload(options) {
+	const { cacheDir, downloader, integrity, platformArch, version } = {
+		__proto__: null,
+		...options
+	};
+	const url = require_external_tools_uv_asset_names.getUvDownloadUrl({
+		version,
+		platformArch
+	});
+	const entry = require_external_tools_uv_asset_names.getUvAssetEntry(platformArch);
+	if (!url || !entry) return;
+	const archiveExt = entry.asset.endsWith(".zip") ? ".zip" : ".tar.gz";
+	const extractedDir = cacheDir ?? node_path.default.join(require_paths_socket.getSocketDlxDir(), "uv", version, platformArch);
+	const archive = await require_external_tools_from_download.downloadAndExtractTool({
+		url,
+		name: `uv-${version}-${platformArch}${archiveExt}`,
+		integrity,
+		extractedDir,
+		extractOptions: { strip: 1 },
+		downloader
+	});
+	const binary = node_process.default.platform === "win32" ? "uv.exe" : "uv";
+	return {
+		path: node_path.default.join(extractedDir, binary),
+		source: "download",
+		integrity: archive.integrity
+	};
+}
+
+//#endregion
+exports.uvFromDownload = uvFromDownload;

package/dist/external-tools/uv/from-path.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @file `uvFromPath()` — looks for `uv` on the system PATH.
+ */
+import type { ResolvedUv } from './types';
+export declare function uvFromPath(): Promise<ResolvedUv | undefined>;

package/dist/external-tools/uv/from-path.js

@@ -0,0 +1,22 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_bin_which = require('../../bin/which.js');
+
+//#region src/external-tools/uv/from-path.ts
+/**
+* @file `uvFromPath()` — looks for `uv` on the system PATH.
+*/
+async function uvFromPath() {
+	const onPath = await require_bin_which.which("uv", { nothrow: true });
+	/* c8 ignore start - reached only when uv is NOT on PATH. */
+	if (typeof onPath !== "string") return;
+	/* c8 ignore stop */
+	return {
+		path: onPath,
+		source: "path"
+	};
+}
+
+//#endregion
+exports.uvFromPath = uvFromPath;

package/dist/external-tools/uv/from-vfs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file `uvFromVfs()` — extracts the uv binary from the smol binary's VFS.
+ *   Returns `undefined` when the binary doesn't have uv bundled.
+ */
+import type { ResolvedUv } from './types';
+export declare const UV_VFS_KEY = "uv";
+export declare function uvFromVfs(): Promise<ResolvedUv | undefined>;

package/dist/external-tools/uv/from-vfs.js

@@ -0,0 +1,26 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_smol_vfs = require('../../smol/vfs.js');
+
+//#region src/external-tools/uv/from-vfs.ts
+/**
+* @file `uvFromVfs()` — extracts the uv binary from the smol binary's VFS.
+*   Returns `undefined` when the binary doesn't have uv bundled.
+*/
+const UV_VFS_KEY = "uv";
+async function uvFromVfs() {
+	const vfs = require_smol_vfs.getSmolVfs();
+	if (!vfs) return;
+	/* c8 ignore start - smol Node binary only. */
+	if (!vfs.has("uv")) return;
+	return {
+		path: await vfs.extract("uv"),
+		source: "vfs"
+	};
+	/* c8 ignore stop */
+}
+
+//#endregion
+exports.UV_VFS_KEY = UV_VFS_KEY;
+exports.uvFromVfs = uvFromVfs;

package/dist/external-tools/uv/resolve.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file `resolveUv()` — uv resolution entry point. Tries each source in order:
+ *
+ *   1. VFS — smol binary's embedded uv (if packed)
+ *   2. PATH — `uv` on the system PATH
+ *   3. download — upstream GitHub release archive (only when `downloadIfMissing`
+ *      is passed) Returns `undefined` if all of the enabled sources miss.
+ *      Memoized per option-shape.
+ */
+import type { BinaryDownloader } from '../from-download';
+import type { HashSpec } from '../../integrity';
+import type { ResolvedUv } from './types';
+export interface ResolveUvOptions {
+    downloadIfMissing?: {
+        version: string;
+        platformArch: string;
+        integrity?: HashSpec | undefined;
+        cacheDir?: string | undefined;
+        downloader?: BinaryDownloader | undefined;
+    } | undefined;
+}
+export declare function cacheKey(options: ResolveUvOptions | undefined): string;
+export declare function doResolveUv(options?: ResolveUvOptions | undefined): Promise<ResolvedUv | undefined>;
+export declare function resetUvResolution(): void;
+export declare function resolveUv(options?: ResolveUvOptions | undefined): Promise<ResolvedUv | undefined>;

package/dist/external-tools/uv/resolve.js

@@ -0,0 +1,61 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_map_set = require('../../primordials/map-set.js');
+const require_external_tools_uv_from_download = require('./from-download.js');
+const require_external_tools_uv_from_path = require('./from-path.js');
+const require_external_tools_uv_from_vfs = require('./from-vfs.js');
+
+//#region src/external-tools/uv/resolve.ts
+/**
+* @file `resolveUv()` — uv resolution entry point. Tries each source in order:
+*
+*   1. VFS — smol binary's embedded uv (if packed)
+*   2. PATH — `uv` on the system PATH
+*   3. download — upstream GitHub release archive (only when `downloadIfMissing`
+*      is passed) Returns `undefined` if all of the enabled sources miss.
+*      Memoized per option-shape.
+*/
+const resolutionCache = new require_primordials_map_set.MapCtor();
+function cacheKey(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	if (!opts?.downloadIfMissing) return "local-only";
+	const { cacheDir, integrity, platformArch, version } = opts.downloadIfMissing;
+	return `dl:${version}:${platformArch}:${typeof integrity === "string" ? integrity : integrity ? `${integrity.type}:${integrity.value}` : ""}:${cacheDir ?? ""}`;
+}
+async function doResolveUv(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const fromVfs = await require_external_tools_uv_from_vfs.uvFromVfs();
+	/* c8 ignore start - smol Node binary only. */
+	if (fromVfs) return fromVfs;
+	/* c8 ignore stop */
+	const fromPath = await require_external_tools_uv_from_path.uvFromPath();
+	if (fromPath) return fromPath;
+	if (opts?.downloadIfMissing) return require_external_tools_uv_from_download.uvFromDownload(opts.downloadIfMissing);
+}
+/* c8 ignore start - test-only escape hatch. */
+function resetUvResolution() {
+	resolutionCache.clear();
+}
+/* c8 ignore stop */
+function resolveUv(options) {
+	const key = cacheKey(options);
+	let cached = resolutionCache.get(key);
+	if (!cached) {
+		cached = doResolveUv(options);
+		resolutionCache.set(key, cached);
+	}
+	return cached;
+}
+
+//#endregion
+exports.cacheKey = cacheKey;
+exports.doResolveUv = doResolveUv;
+exports.resetUvResolution = resetUvResolution;
+exports.resolveUv = resolveUv;

package/dist/external-tools/uv/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Shared types for uv resolution. uv is Astral's Python package manager
+ *   used by socket-basics for Python project bootstrap. Ships per-platform
+ *   archives that wrap the `uv` binary one level deep.
+ */
+import type { ResolvedToolIntegrity } from '../from-download';
+export type UvSource = 'download' | 'path' | 'vfs';
+/**
+ * A resolved uv installation.
+ */
+export interface ResolvedUv {
+    /**
+     * Absolute path to the `uv` executable.
+     */
+    readonly path: string;
+    /**
+     * Which resolver tier found this.
+     */
+    readonly source: UvSource;
+    /**
+     * See {@link ResolvedToolIntegrity}.
+     */
+    readonly integrity?: ResolvedToolIntegrity | undefined;
+}

package/dist/external-tools/uv/types.js

@@ -0,0 +1,2 @@
+"use strict";
+/* Socket Lib - Built with rolldown */

package/dist/fleet/repo-config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @file Fleet-convention config reader: a per-repo override (`.config/repo`)
+ *   layered over the cascaded fleet default (`.config/fleet`). A thin wrapper
+ *   over the generic `config/layers` reader that returns the named `{ fleet,
+ *   repo }` shape fleet callers use, plus the `{ fleet, repo }` array-merge
+ *   convenience. The generic, fleet-agnostic primitives (`readConfigLayers`,
+ *   `mergeConfigArray`) live in `config/layers`. Lives in the published lib
+ *   because it is the only import root the `.git-hooks/_shared` and
+ *   `.claude/hooks/_shared` trees (which do not cross-import) plus `.config/*`
+ *   can all reach.
+ */
+export declare const FLEET_LAYER_DIRS: readonly string[];
+export interface RepoConfigTiers<T> {
+    fleet: T | undefined;
+    repo: T | undefined;
+}
+export interface ResolveRepoConfigOptions {
+    repoRoot?: string | undefined;
+    cwd?: string | undefined;
+}
+/**
+ * Concatenate one array-valued key across the fleet + repo tiers. Fleet entries
+ * first, then repo entries. Convenience over `mergeConfigArray` for the `{
+ * fleet, repo }` shape.
+ *
+ * @param tiers - The `{ fleet, repo }` from `resolveRepoConfig`.
+ * @param key - The array-valued property to concatenate.
+ *
+ * @returns Fleet entries followed by repo entries; `[]` when neither is an
+ *   array.
+ */
+export declare function mergeRepoConfigArray<T extends Record<string, unknown>, K extends keyof T>(tiers: RepoConfigTiers<T>, key: K): Array<T[K] extends Array<infer E> ? E : never>;
+/**
+ * Fleet-convention reader: a repo override (`.config/repo`) layered over the
+ * cascaded fleet default (`.config/fleet`). A thin wrapper over
+ * `readConfigLayers` that returns the named `{ fleet, repo }` shape callers
+ * already use; either tier is `undefined` when absent or unparseable.
+ *
+ * @example
+ *   ;```typescript
+ *   const { fleet, repo } = resolveRepoConfig<VitestTiers>('vitest')
+ *   const nonIsolated = [
+ *     ...(fleet?.nonIsolated ?? []),
+ *     ...(repo?.nonIsolated ?? []),
+ *   ]
+ *   ```
+ *
+ * @param name - Base name of the config file (no directory, no `.json`).
+ * @param options - `repoRoot` / `cwd` for path resolution.
+ *
+ * @returns `{ fleet, repo }` parsed tiers; either may be `undefined`.
+ */
+export declare function resolveRepoConfig<T = unknown>(name: string, options?: ResolveRepoConfigOptions | undefined): RepoConfigTiers<T>;

package/dist/fleet/repo-config.js

@@ -0,0 +1,79 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_config_layers = require('../config/layers.js');
+
+//#region src/fleet/repo-config.ts
+/**
+* @file Fleet-convention config reader: a per-repo override (`.config/repo`)
+*   layered over the cascaded fleet default (`.config/fleet`). A thin wrapper
+*   over the generic `config/layers` reader that returns the named `{ fleet,
+*   repo }` shape fleet callers use, plus the `{ fleet, repo }` array-merge
+*   convenience. The generic, fleet-agnostic primitives (`readConfigLayers`,
+*   `mergeConfigArray`) live in `config/layers`. Lives in the published lib
+*   because it is the only import root the `.git-hooks/_shared` and
+*   `.claude/hooks/_shared` trees (which do not cross-import) plus `.config/*`
+*   can all reach.
+*/
+const FLEET_LAYER_DIRS = [".config/fleet", ".config/repo"];
+/**
+* Concatenate one array-valued key across the fleet + repo tiers. Fleet entries
+* first, then repo entries. Convenience over `mergeConfigArray` for the `{
+* fleet, repo }` shape.
+*
+* @param tiers - The `{ fleet, repo }` from `resolveRepoConfig`.
+* @param key - The array-valued property to concatenate.
+*
+* @returns Fleet entries followed by repo entries; `[]` when neither is an
+*   array.
+*/
+function mergeRepoConfigArray(tiers, key) {
+	return require_config_layers.mergeConfigArray([tiers.fleet, tiers.repo], key);
+}
+/**
+* Fleet-convention reader: a repo override (`.config/repo`) layered over the
+* cascaded fleet default (`.config/fleet`). A thin wrapper over
+* `readConfigLayers` that returns the named `{ fleet, repo }` shape callers
+* already use; either tier is `undefined` when absent or unparseable.
+*
+* @example
+*   ;```typescript
+*   const { fleet, repo } = resolveRepoConfig<VitestTiers>('vitest')
+*   const nonIsolated = [
+*     ...(fleet?.nonIsolated ?? []),
+*     ...(repo?.nonIsolated ?? []),
+*   ]
+*   ```
+*
+* @param name - Base name of the config file (no directory, no `.json`).
+* @param options - `repoRoot` / `cwd` for path resolution.
+*
+* @returns `{ fleet, repo }` parsed tiers; either may be `undefined`.
+*/
+function resolveRepoConfig(name, options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const base = {
+		cwd: opts.cwd,
+		rootDir: opts.repoRoot
+	};
+	const [fleet] = require_config_layers.readConfigLayers(name, {
+		...base,
+		dirs: [FLEET_LAYER_DIRS[0]]
+	});
+	const [repo] = require_config_layers.readConfigLayers(name, {
+		...base,
+		dirs: [FLEET_LAYER_DIRS[1]]
+	});
+	return {
+		fleet,
+		repo
+	};
+}
+
+//#endregion
+exports.FLEET_LAYER_DIRS = FLEET_LAYER_DIRS;
+exports.mergeRepoConfigArray = mergeRepoConfigArray;
+exports.resolveRepoConfig = resolveRepoConfig;

package/dist/fs/allowed-dirs-cache.js

@@ -1,8 +1,6 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_paths_rewire = require('../paths/rewire.js');
-const require_fs__internal = require('./_internal.js');
 
 //#region src/fs/allowed-dirs-cache.ts
 /**
@@ -36,7 +34,7 @@ const require_fs__internal = require('./_internal.js');
 * @internal Used for test rewiring
 */
 function invalidatePathCache() {
-	require_fs__internal.clearAllowedDirectories();
+	clearAllowedDirectories();
 }
 /**
 * Register `invalidatePathCache` with the rewire module after the current
@@ -55,8 +53,8 @@ function invalidatePathCache() {
 */
 function registerInvalidationCallback(attempt = 0) {
 	try {
-		if (typeof require_paths_rewire.registerCacheInvalidation === "function") {
-			require_paths_rewire.registerCacheInvalidation(invalidatePathCache);
+		if (typeof registerCacheInvalidation === "function") {
+			registerCacheInvalidation(invalidatePathCache);
 			return;
 		}
 	} catch {}

package/dist/fs/copy.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @file Recursive copy for a file or directory tree, with three destination
+ *   modes (see {@link CopyMode}). Plain `fs.cp` (even with `force`) overwrites
+ *   files present in the source but never deletes destination files absent from
+ *   it, so copying onto an existing target leaves stale leftovers behind. The
+ *   `'pave'` mode makes the destination an exact copy of the source by staging
+ *   a fresh tree in a sibling temp directory and swapping it in with a single
+ *   rename — atomic, with no stale survivors.
+ */
+import type { PathLike } from 'node:fs';
+/**
+ * Named values for {@link CopyMode}. A frozen object rather than a TypeScript
+ * `enum` so the declaration is erasable (enums emit runtime helper code).
+ */
+export declare const CopyMode: Readonly<{
+    readonly Fill: 'fill';
+    readonly Overlay: 'overlay';
+    readonly Pave: 'pave';
+}>;
+/**
+ * How {@link copy} treats an existing destination.
+ *
+ * - `'overlay'` (default) — overwrite files present in the source but leave any
+ *   pre-existing destination-only files in place (a recursive `fs.cp`).
+ * - `'pave'` — replace the destination so it becomes an exact copy of the source;
+ *   destination entries absent from the source do not survive. The swap is
+ *   atomic (a sibling temp directory is renamed into place), so a partial tree
+ *   is never observable.
+ * - `'fill'` — copy only what the destination lacks: existing files stay
+ *   untouched (no-clobber), missing ones are added. Never throws on an existing
+ *   file.
+ *
+ * Maps to `cp` (overlay), `rsync --delete` / robocopy `/MIR` (pave), and
+ * `cp -n` (fill).
+ */
+export type CopyMode = (typeof CopyMode)[keyof typeof CopyMode];
+/**
+ * Options for {@link copy}.
+ */
+export interface CopyOptions {
+    /**
+     * Dereference symlinks — copy what each points to rather than the link
+     * itself.
+     *
+     * @default false
+     */
+    dereference?: boolean | undefined;
+    /**
+     * Predicate deciding which entries to copy. Return `false` to skip an entry
+     * (and, for a directory, everything beneath it). Receives resolved source
+     * and destination paths, matching `node:fs` `cp`'s `filter`.
+     */
+    filter?: ((source: string, destination: string) => boolean) | undefined;
+    /**
+     * How to treat an existing destination. See {@link CopyMode}.
+     *
+     * @default 'overlay'
+     */
+    mode?: CopyMode | undefined;
+    /**
+     * Abort signal to cancel the operation.
+     */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Recursively copy a file or directory tree from `from` to `to`.
+ *
+ * Works for both files and directories. The `mode` option chooses how an
+ * existing destination is treated — overlay (default), pave, or fill; see
+ * {@link CopyMode}.
+ *
+ * @example
+ *   ;```ts
+ *   // Overlay (default) — overwrite collisions, keep files already in dest:
+ *   await copy('./src', './dest')
+ *
+ *   // Pave — dest ends up identical to src, no stale survivors:
+ *   await copy('./vendor/upstream', './deps/upstream', { mode: CopyMode.Pave })
+ *
+ *   // Fill — add only what's missing, never overwrite an existing file:
+ *   await copy('./defaults', './config', { mode: CopyMode.Fill })
+ *   ```
+ *
+ * @param from - Source file or directory to copy.
+ * @param to - Destination path.
+ * @param options - Copy options (mode, filter, dereference, abort signal).
+ */
+export declare function copy(from: PathLike, to: PathLike, options?: CopyOptions | undefined): Promise<void>;