package-management 0.0.16 → 0.2.0

package/dist/index.d.mts

@@ -1,15 +1,26 @@
-import { Split } from 'string-ts';
 import * as async_cache_fn from 'async-cache-fn';
 import { AsyncCacheFn as AsyncCacheFn$1 } from 'async-cache-fn';
+import { WriteFileOptions } from 'node:fs';
 import { Options } from 'execa';
-import { InstallPackageOptions as InstallPackageOptions$1 } from '@antfu/install-pkg';
 import { ResolveOptions } from 'mlly';
 import * as parse_gitignore from 'parse-gitignore';
-import * as WST from 'workspace-tools';
 import { ModificationOptions } from 'jsonc-parser';
+import { parseJSONC, stringifyJSONC, parseJSON5, stringifyJSON5, parseYAML, stringifyYAML, parseTOML, stringifyTOML } from 'confbox';
 import { StorageValue, TransactionOptions, Snapshot, Storage } from 'unstorage';
 import { FSStorageOptions } from 'unstorage/drivers/fs-lite';
 
+/**
+ * Returns true if string input type is a literal
+ */
+type IsStringLiteral<T extends string> = [T] extends [string] ? [string] extends [T] ? false : Uppercase<T> extends Uppercase<Lowercase<T>> ? Lowercase<T> extends Lowercase<Uppercase<T>> ? true : false : false : false;
+
+/**
+ * Splits a string into an array of substrings.
+ * T: The string to split.
+ * delimiter: The delimiter.
+ */
+type Split<T extends string, delimiter extends string = ''> = IsStringLiteral<T | delimiter> extends true ? T extends `${infer first}${delimiter}${infer rest}` ? [first, ...Split<rest, delimiter>] : T extends '' ? [] : [T] : string[];
+
 type Equals<A1 extends any, A2 extends any> = (<A>() => A extends A2 ? 1 : 0) extends <A>() => A extends A1 ? 1 : 0 ? 1 : 0;
 type Cast<A1 extends any, A2 extends any> = A1 extends A2 ? A1 : A2;
 type __<T> = {
@@ -21,6 +32,7 @@ type Prettify<T> = {
 type ValueOf<T> = T[keyof T];
 type EnumToLiteral<T extends string | number> = T extends string ? `${T}` : `${T}` extends `${infer N extends number}` ? N : never;
 type IsUnknown<t> = unknown extends t ? [t] extends [{}] ? false : true : false;
+type IsNever<T> = [T] extends [never] ? true : false;
 type AnyFunction = (...args: any[]) => any;
 type StringLiteral<T extends string> = T | (string & {});
 type Awaitable<T> = T | Promise<T>;
@@ -74,11 +86,55 @@ interface PathOptions {
 type AsyncCacheFn<TReturn = unknown, TOption extends object | undefined = undefined, C extends "required" | "optional" = "optional"> = AsyncCacheFn$1<TReturn, C extends "optional" ? [TOption | undefined] | [] : [TOption]>;
 type CheckResult<$data, $error = Error, $data_key extends string = "data", $error_key extends string = "error"> = Prettify<RequireExactlyOne<SingleProp<$data_key, $data> & SingleProp<$error_key, $error>>>;
 
-interface StackFrameOptions {
-    rootFunctionName?: string;
+interface CallerLocationOptions {
+    /**
+     * The calling module's own URL — pass `import.meta.url`.
+     *
+     * This is the reliable answer and skips stack inspection entirely. A module
+     * can always name itself; nothing can ask the runtime who called it, which is
+     * why the fallback below has to exist at all.
+     */
+    from?: string | URL;
+    /**
+     * Name of the public entry point whose caller is wanted, used only when
+     * `from` is absent.
+     */
+    boundaryFunctionName?: string;
+    /**
+     * Module URLs to treat as this library's own when walking the stack.
+     *
+     * In a published bundle every internal frame shares one script, so this is
+     * redundant there; unbundled, each internal module is its own script and has
+     * to say so.
+     */
+    internalScripts?: string[];
+}
+
+/**
+ * The calling file's absolute path.
+ *
+ * Pass `from: import.meta.url` wherever the caller can — that is exact in every
+ * runtime, while the stack fallback is Node-only.
+ */
+declare const _filename: (options?: CallerLocationOptions) => string | undefined;
+/** The directory of the calling file. */
+declare const _dirname: (options?: CallerLocationOptions) => string | undefined;
+
+declare function createFile(filePath: string, data: string, options?: WriteFileOptions): void;
+
+interface ReadFileOptions {
+    /** @default "utf-8" */
+    encoding?: BufferEncoding;
 }
-declare const _filename: (options?: StackFrameOptions) => string | undefined;
-declare const _dirname: (options?: StackFrameOptions) => string | undefined;
+declare function readFile(filePath: string, options?: ReadFileOptions): string;
+/**
+ * `undefined` is a real answer: a config a tool has never written yet is
+ * absent rather than empty, and callers seeding one say so themselves
+ * instead of catching a throw to find out.
+ */
+declare function readFileSafely(filePath: string, options?: ReadFileOptions): string | undefined;
+
+declare function isWritable(filename: string): boolean;
 
 interface PackageManagerConfig<ID extends string = string> {
     id: ID;
@@ -86,6 +142,14 @@ interface PackageManagerConfig<ID extends string = string> {
     name: string;
     meta: {
         lockfile: string | string[];
+        /**
+         * Distinguishes package managers that share both a command and a lockfile
+         * name, where the lockfile alone cannot identify which one a project uses —
+         * Yarn Classic and Yarn Berry being the case this exists for.
+         *
+         * Omit when the lockfile is already unambiguous.
+         */
+        matchesVersion?: (version: string) => boolean;
     };
     runner: string;
     args: {
@@ -138,9 +202,12 @@ interface ImportPackageData<T = any> extends ImportModuleData<T> {
      */
     dev?: boolean;
     /**
-     * Additional installation options
+     * When enabled, a package already declared as a dependency is not installed
+     * again, so a satisfied import map costs no package manager invocations.
+     *
+     * @default true
      */
-    installOptions?: Omit<InstallPackageOptions$1, "dev">;
+    checkExists?: boolean;
 }
 type ImportOption<T = any> = Module | ImportCallback<T> | ImportModuleData<T> | ImportPackageData<T>;
 type Module<T = any> = Promise<T>;
@@ -259,6 +326,11 @@ interface PackageManager<ID extends string = PackageManagerId> {
         cwd?: string;
     }>;
     globalVersion: AsyncCacheFn<string | undefined, PackageManagerScriptOptions>;
+    /**
+     * Whether the installed version is the one this config describes. Always
+     * true for managers whose lockfile already identifies them unambiguously.
+     */
+    matchesVersion: AsyncCacheFn<boolean, PackageManagerScriptOptions>;
     definePackage: DefinePackageFn;
     defineImportMap: <T extends ImportMap>(importMap: T, options?: {
         /**
@@ -270,6 +342,9 @@ interface PackageManager<ID extends string = PackageManagerId> {
     uninstallPackage: (packageNames: string | string[], options?: UninstallPackageOptions) => Promise<void>;
     installPackage: (packageNames: string | string[], options?: PackageManagerScriptOptions<"install">) => Promise<void>;
 }
+declare function definePackageManager<ID extends string>(config: PackageManagerConfig<ID>, options?: {
+    cwd?: string;
+}): PackageManager<ID>;
 
 interface DetectPackageManagerOptions<$id extends string = PackageManagerId> {
     /**
@@ -312,20 +387,24 @@ declare function mapPackageManagers<$result, $id extends string = PackageManager
 declare function filterPackageManagers<$id extends string = PackageManagerId>(packageManagers: PackageManagers<$id>, filterFn: (packageManager: PackageManager<$id>) => Awaitable<boolean>, options?: DetectPackageManagerOptions<$id>): Promise<PackageManager<$id>[]>;
 
 type PackageManagerId = (typeof packageManagerConfigs)[number]["id"];
-declare const packageManagerConfigs: (PackageManagerConfig<"pnpm"> | PackageManagerConfig<"yarn"> | PackageManagerConfig<"bun"> | PackageManagerConfig<"npm">)[];
+declare const packageManagerConfigs: (PackageManagerConfig<"pnpm"> | PackageManagerConfig<"yarn"> | PackageManagerConfig<"yarn-berry"> | PackageManagerConfig<"bun"> | PackageManagerConfig<"npm">)[];
 declare function definePackageManagerClient(options: DetectPackageManagerOptions): {
-    configs: PackageManager<"pnpm" | "yarn" | "bun" | "npm">[];
-    findPackageManager: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-    findPackageManagerSafely: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm"> | undefined, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-    detectPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-    detectLockfilePackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-    detectGlobalPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-    globalVersions: async_cache_fn.AsyncCacheFn<Record<"pnpm" | "yarn" | "bun" | "npm", string | undefined>, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-    filterPackageManagers: (filterFn: (packageManager: PackageManager) => Awaitable<boolean>, options?: DetectPackageManagerOptions) => Promise<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[]>;
+    configs: PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[];
+    findPackageManager: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+    findPackageManagerSafely: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+    detectPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+    detectLockfilePackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+    detectGlobalPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+    globalVersions: async_cache_fn.AsyncCacheFn<Record<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm", string | undefined>, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+    filterPackageManagers: (filterFn: (packageManager: PackageManager) => Awaitable<boolean>, options?: DetectPackageManagerOptions) => Promise<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[]>;
     mapPackageManagers: <$result>(mapFn: (packageManager: PackageManager) => Awaitable<$result>, options?: DetectPackageManagerOptions) => Promise<Awaited<$result>[]>;
 };
 
-declare function isPackageDependency(packageName: string | string[]): boolean;
+/**
+ * Whether every named package is declared in the nearest package.json,
+ * searching up from `cwd`.
+ */
+declare function isPackageDependency(packageName: string | string[], options?: PathOptions): boolean;
 
 interface AliasDefinition {
     resolve: ResolvePathAliasFn;
@@ -341,9 +420,20 @@ type AliasMap<TAliases extends AliasDefinitionMap = AliasDefinitionMap> = {
 } & {
     [K in keyof TAliases as `${Extract<K, string>}/${NonNullable<TAliases[K]["subpaths"]>[number]["to"]}`]: TAliases[K]["resolve"];
 };
-type ResolvePathAliasFn = (opts?: {
+interface PathAliasResolveOptions {
     cwd?: string;
-}) => string;
+    /**
+     * The calling module's own URL — `import.meta.url`. Only the caller-relative
+     * aliases read it, and only they need it.
+     */
+    from?: string | URL;
+}
+/**
+ * `undefined` is a real answer: an alias can name a location that does not
+ * exist in this context, and callers assert on it rather than receiving a
+ * path assembled from nothing.
+ */
+type ResolvePathAliasFn = (opts?: PathAliasResolveOptions) => string | undefined;
 type StringKeyOf<T> = Extract<keyof T, string>;
 declare function definePathAliases<const T extends AliasDefinitionMap>(aliasDefinitions: T): {
     aliasDefinitions: T;
@@ -355,6 +445,14 @@ interface GetPathOptions<TAlias extends string, TValidate extends boolean = fals
     to: PathTo<TAlias>;
     startingFrom?: PathTo<TAlias>;
     cwd?: string;
+    /**
+     * The calling module's own URL — `import.meta.url`.
+     *
+     * Required in any runtime without `node:util`'s call sites, and worth
+     * passing regardless: a module naming itself is exact, whereas inferring the
+     * caller from the stack is a best effort.
+     */
+    from?: string | URL;
     checkExistence?: TValidate;
     glob?: TGlob;
 }
@@ -415,9 +513,7 @@ type PickPathAlias<K extends PathAlias> = K;
 type PredefinedPathAliases = typeof predefinedPathAliases;
 declare const predefinedPathAliases: {
     readonly "<workspace_folder>": {
-        readonly resolve: (opts: {
-            cwd?: string;
-        } | undefined) => string;
+        readonly resolve: (opts: PathAliasResolveOptions | undefined) => string;
         readonly subpaths: [{
             readonly to: "node_modules";
         }, {
@@ -425,9 +521,7 @@ declare const predefinedPathAliases: {
         }];
     };
     readonly "<workspace_folder?>": {
-        readonly resolve: (opts: {
-            cwd?: string;
-        } | undefined) => string;
+        readonly resolve: (opts: PathAliasResolveOptions | undefined) => string;
         readonly subpaths: [{
             readonly to: "node_modules";
         }, {
@@ -435,9 +529,7 @@ declare const predefinedPathAliases: {
         }];
     };
     readonly "<package_folder>": {
-        readonly resolve: (opts: {
-            cwd?: string;
-        } | undefined) => string;
+        readonly resolve: (opts: PathAliasResolveOptions | undefined) => string | undefined;
         readonly subpaths: [{
             readonly to: "node_modules";
         }, {
@@ -447,9 +539,7 @@ declare const predefinedPathAliases: {
         }];
     };
     readonly "<gitroot_folder>": {
-        readonly resolve: (opts: {
-            cwd?: string;
-        } | undefined) => string;
+        readonly resolve: (opts: PathAliasResolveOptions | undefined) => string;
         readonly subpaths: [{
             readonly to: "node_modules";
         }, {
@@ -471,11 +561,11 @@ declare const predefinedPathAliases: {
         readonly subpaths: any[];
     };
     readonly "<current_file>": {
-        readonly resolve: () => string;
+        readonly resolve: (opts: PathAliasResolveOptions | undefined) => string | undefined;
         readonly subpaths: any[];
     };
     readonly "<current_folder>": {
-        readonly resolve: () => string;
+        readonly resolve: (opts: PathAliasResolveOptions | undefined) => string | undefined;
         readonly subpaths: any[];
     };
 };
@@ -679,11 +769,11 @@ declare const project: (...args: ProjectParams) => {
     packageJsonPath: string | undefined;
     packageName: string | undefined;
     projectDir: string | undefined;
-    findPackageManager: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-    detectPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-    detectGlobalPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-    detectLockfilePackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-    globalVersions: async_cache_fn.AsyncCacheFn<Record<"pnpm" | "yarn" | "bun" | "npm", string | undefined>, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
+    findPackageManager: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+    detectPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+    detectGlobalPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+    detectLockfilePackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+    globalVersions: async_cache_fn.AsyncCacheFn<Record<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm", string | undefined>, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
     mapPackageManagers: <$result>(mapFn: (packageManager: PackageManager) => Awaitable<$result>, options?: DetectPackageManagerOptions) => Promise<Awaited<$result>[]>;
     tsconfig: {
         readonly paths: string[];
@@ -692,8 +782,8 @@ declare const project: (...args: ProjectParams) => {
         readonly data: parse_gitignore.ParsedGitignoreObject;
         readonly patterns: string[];
     };
-    filterPackageManagers: (filterFn: (packageManager: PackageManager) => Awaitable<boolean>, options?: DetectPackageManagerOptions) => Promise<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[]>;
-    getPackageJson: () => PackageJson;
+    filterPackageManagers: (filterFn: (packageManager: PackageManager) => Awaitable<boolean>, options?: DetectPackageManagerOptions) => Promise<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[]>;
+    getPackageJson: () => PackageJson | undefined;
     findDependencyInPackageJson: (options: string | FindDependencyInPackageJsonOptions) => {
         firstMatch: PackageDependencyItem | undefined;
         matches: PackageDependencyItem[];
@@ -719,7 +809,7 @@ declare function getGitRootFolder<$ThrowIfNotFound extends boolean = true>(optio
  */
 declare function getPackageFolder(options?: {
     cwd?: string;
-}): string;
+}): string | undefined;
 
 interface GetWorkspaceFolderOptions<$Validate extends boolean = true> extends PathOptions {
     /** @default true */
@@ -741,7 +831,7 @@ interface GetPackageInfoListOptions {
     cwd?: string;
     includeRoot?: boolean;
 }
-declare function getWorkspacePackageInfoList(options?: GetPackageInfoListOptions): (PackageInfo | WST.WorkspacePackageInfo)[];
+declare function getWorkspacePackageInfoList(options?: GetPackageInfoListOptions): PackageInfo[];
 
 declare function getWorkspacePackageNames(options?: GetPackageInfoListOptions): string[];
 
@@ -755,11 +845,11 @@ declare const workspace: {
         packageJsonPath: string | undefined;
         packageName: string | undefined;
         projectDir: string | undefined;
-        findPackageManager: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-        detectPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-        detectGlobalPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-        detectLockfilePackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
-        globalVersions: async_cache_fn.AsyncCacheFn<Record<"pnpm" | "yarn" | "bun" | "npm", string | undefined>, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "bun" | "npm"> | undefined]>;
+        findPackageManager: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+        detectPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+        detectGlobalPackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+        detectLockfilePackageManagers: async_cache_fn.AsyncCacheFn<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[], [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
+        globalVersions: async_cache_fn.AsyncCacheFn<Record<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm", string | undefined>, [options?: DetectPackageManagerOptions<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm"> | undefined]>;
         mapPackageManagers: <$result>(mapFn: (packageManager: PackageManager) => Awaitable<$result>, options?: DetectPackageManagerOptions) => Promise<Awaited<$result>[]>;
         tsconfig: {
             readonly paths: string[];
@@ -768,8 +858,8 @@ declare const workspace: {
             readonly data: parse_gitignore.ParsedGitignoreObject;
             readonly patterns: string[];
         };
-        filterPackageManagers: (filterFn: (packageManager: PackageManager) => Awaitable<boolean>, options?: DetectPackageManagerOptions) => Promise<PackageManager<"pnpm" | "yarn" | "bun" | "npm">[]>;
-        getPackageJson: () => PackageJson;
+        filterPackageManagers: (filterFn: (packageManager: PackageManager) => Awaitable<boolean>, options?: DetectPackageManagerOptions) => Promise<PackageManager<"pnpm" | "yarn" | "yarn-berry" | "bun" | "npm">[]>;
+        getPackageJson: () => PackageJson | undefined;
         findDependencyInPackageJson: (options: string | FindDependencyInPackageJsonOptions) => {
             firstMatch: PackageDependencyItem | undefined;
             matches: PackageDependencyItem[];
@@ -818,21 +908,104 @@ type ModifyJSONFileResult<$auto_commit extends boolean = true> = $auto_commit ex
 }>;
 declare function modifyJSONFile<$auto_commit extends boolean = true>(filepath: string, edits: JSONEdits, options?: MoodifyJSONFileOptions<$auto_commit>): ModifyJSONFileResult<$auto_commit>;
 
-declare const storage: Storage<StorageValue>;
-declare const tempFileSystem: {
-    definition: {
-        readonly base: string;
+/**
+ * The configuration languages a project actually ships: `package.json` and
+ * `tsconfig.json`, `.prettierrc.json5`, CI and Compose YAML, and the TOML
+ * that Cargo, Codex, and Ruff read.
+ */
+type ConfigFormat = "json" | "jsonc" | "json5" | "yaml" | "toml";
+type ConfigSourceInputType = keyof ConfigSourceInput;
+interface ConfigSourceData<$config extends object = object> {
+    text: string;
+    data: $config;
+}
+type ConfigSourceInput<data extends object = object> = Prettify<RequireExactlyOne<{
+    data?: data;
+    filepath?: string;
+    text?: string;
+}> & {
+    /**
+     * Inferred from a `filepath`'s extension. Required for `text` and `data`,
+     * which carry no extension to read it from.
+     */
+    format?: ConfigFormat;
+}>;
+
+/**
+ * One edit vocabulary across every language. A dot path addresses nesting,
+ * an array spells segments out literally, and both are what `modifyJSON`
+ * already accepts — so an edit written for `package.json` reads the same
+ * written for `config.toml`.
+ */
+type ConfigEdits = JSONEdits;
+type ConfigEditData = JSONEditData;
+type ConfigEditOptions = JSONEditOptions;
+interface ModifyConfigOptions<$config extends object = object> {
+    config: ConfigSourceInput<$config>;
+    edits: ConfigEdits;
+    defaultEditOptions?: ConfigEditOptions;
+}
+declare function modifyConfig({ config, edits, defaultEditOptions, }: ModifyConfigOptions): CheckResult<ConfigSourceData>;
+interface ModifyConfigFileOptions<$auto_commit extends boolean = boolean> {
+    autoCommit?: $auto_commit;
+    defaultEditOptions?: ConfigEditOptions;
+    /** Overrides the format the file's extension implies. */
+    format?: ConfigFormat;
+}
+type ModifyConfigFileResult<$auto_commit extends boolean = true> = $auto_commit extends true ? CheckResult<ConfigSourceData> : CheckResult<{
+    config: ConfigSourceData;
+    commit: () => void;
+}>;
+declare function modifyConfigFile<$auto_commit extends boolean = true>(filepath: string, edits: ConfigEdits, options?: ModifyConfigFileOptions<$auto_commit>): ModifyConfigFileResult<$auto_commit>;
+
+declare const configLanguages: {
+    readonly json: {
+        readonly parse: typeof parseJSONC;
+        readonly stringify: typeof stringifyJSONC;
+        readonly surgical: true;
+    };
+    readonly jsonc: {
+        readonly parse: typeof parseJSONC;
+        readonly stringify: typeof stringifyJSONC;
+        readonly surgical: true;
+    };
+    readonly json5: {
+        readonly parse: typeof parseJSON5;
+        readonly stringify: typeof stringifyJSON5;
+        readonly surgical: false;
+    };
+    readonly yaml: {
+        readonly parse: typeof parseYAML;
+        readonly stringify: typeof stringifyYAML;
+        readonly surgical: false;
+    };
+    readonly toml: {
+        readonly parse: typeof parseTOML;
+        readonly stringify: typeof stringifyTOML;
+        readonly surgical: false;
     };
-    initialize: () => Promise<FileSystemStorage<unknown, string & {}>>;
 };
+declare function isConfigFormat(value: string): value is ConfigFormat;
+/**
+ * `undefined` is a real answer: a path can name an extension this module has
+ * no language for, and callers say what to do about it rather than receiving
+ * a format picked at random.
+ */
+declare function getConfigFormat(filepath: string): ConfigFormat | undefined;
+
+type InferConfig<$source extends ConfigSourceInput> = $source extends ConfigSourceInput<infer $config> ? $config : object;
+type ResolvedConfigSourceData<$as extends "data" | "text" = never, $config extends object = object> = IsNever<$as> extends false ? $as extends string ? ConfigSourceData<$config>[$as] : ConfigSourceData<$config> : ConfigSourceData<$config>;
+declare function resolveConfigSource<$source extends ConfigSourceInput, $as extends "data" | "text" = never>(source: $source, as?: $as): ResolvedConfigSourceData<$as, InferConfig<$source>>;
+
+declare const storage: Storage<StorageValue>;
+declare const tempFileSystem: FileSystemStorage<FileSystemEntriesDefinition<string>, FileSystemPathCompletion<FileSystemEntriesDefinition<string>>>;
 type FileSystemEntriesDefinition<$filepath extends string = string> = {
-    [K in $filepath]: StorageValue | (<$file_data extends StorageValue>() => {
-        file: $file_data;
-        options?: TransactionOptions;
-        serialize?: (file_data: $file_data) => string;
-        deserialize?: (file_content: string) => $file_data;
-    });
+    [K in $filepath]: StorageValue | (() => FileSystemEntryDefinition);
 };
+interface FileSystemEntryDefinition<$file_data extends StorageValue = StorageValue> {
+    file: $file_data;
+    options?: TransactionOptions;
+}
 interface FileSystemEntry<$key extends string = string> {
     key: $key;
     value: string;
@@ -858,15 +1031,21 @@ $path_completion extends FileSystemPathCompletion<$fs_def> = FileSystemPathCompl
     getFile: (filepath: $path_completion) => Promise<{
         key: string;
         filepath: string;
-        data: any;
-        read: () => Promise<any>;
+        data: StorageValue;
+        read: () => Promise<string | undefined>;
     }>;
-    readFile: (filepath: $path_completion) => Promise<string>;
-    getFilePath: <$filepath extends $path_completion>(key: $filepath) => Promise<string>;
+    /** Resolves to `undefined` when the file does not exist. */
+    readFile: (filepath: $path_completion) => Promise<string | undefined>;
+    /** The location a key maps to on disk, whether or not anything is there. */
+    getFilePath: (key: $path_completion) => string;
+    /** `base` is a storage key prefix, not a filesystem path. */
     restoreFs(snapshot: Snapshot, base?: string): Promise<void>;
+    /** `base` is a storage key prefix, not a filesystem path. */
     snapshotFs: (base?: string) => Promise<Snapshot<string>>;
+    /** Replaces the entries this storage owns, leaving other files in place. */
     initializeFs: (newInitial?: FileSystemEntriesDefinition) => Promise<void>;
-    removeAllFiles(base?: string, opts?: TransactionOptions): Promise<void>;
+    removeAllFiles(): Promise<void>;
+    /** Removes the base directory and everything under it. */
     deleteFileSystem(): Promise<void>;
     defineFileSystemEntries: typeof defineFileSystemEntries;
     storage: Storage;
@@ -878,10 +1057,7 @@ interface FileSystemEntriesData<T extends FileSystemEntriesDefinition | undefine
 declare function defineFileSystemEntries<const $fs_def extends FileSystemEntriesDefinition>(definition: $fs_def): FileSystemEntriesData<$fs_def>;
 type ExtractFsEntriesDef<$fs_def> = Cast<$fs_def, FileSystemEntriesDefinition>;
 declare function defineFileSystemStorage<const $fs_storage_def extends DefineFileSystemOptions = DefineFileSystemOptions, // prettier-ignore
-$fs_def extends $fs_storage_def['initial'] = $fs_storage_def['initial']>(options: $fs_storage_def): $fs_storage_def["initial"] extends undefined ? FileSystemStorage : {
-    definition: $fs_storage_def;
-    initialize: () => Promise<FileSystemStorage<$fs_def>>;
-};
+$fs_def extends $fs_storage_def['initial'] = $fs_storage_def['initial']>(options: $fs_storage_def): FileSystemStorage<ExtractFsEntriesDef<$fs_def>>;
 
-export { _dirname, _filename, defineFileSystemEntries, defineFileSystemStorage, definePackage, definePackageManagerClient, definePathAliases, dependencyTypeMap, detectGlobalPackageManagers, detectLockfilePackageManagers, detectPackageManagers, filterPackageManagers, findDependencyInPackageJson, findPackageManager, findPackageManagerSafely, findResolvedModulePath, getAliasMap, getFolderByPackageName, getGitRootFolder, getGlobalVersions, getPackageFolder, getPath, getWorkspaceFolder, importMap, importer, isDependencyInPackageJson, isPackageDependency, isPackageModuleFound, mapPackageManagers, modifyJSON, modifyJSONFile, packageManagerConfigs, predefinedPathAliases, project, resolveModule, resolveModulePath, resolvePackageModulePath, storage, tempFileSystem, workspace };
-export type { AliasDefinition, AliasDefinitionMap, AliasMap, AnyFunction, AsyncCacheFn, Awaitable, Cast, CheckResult, DefinePackageFn, DetectPackageManagerOptions, Entry, EntryOf, EnumToLiteral, Equals, ExtractImportOptionModule, FileSystemEntriesDefinition, FindDependencyInPackageJsonOptions, FromEntries, GetGitRootFolderOptions, GetPathOptions, GetWorkspaceFolderOptions, ImportCallback, ImportList, ImportMap, ImportMapFn, ImportMapOptions, ImportModuleData, ImportModuleFn, ImportOption, ImportOptionData, ImportPackageData, ImporterOptions, InstallPackageOptions, InstallerFn, IsExactBoolean, IsUnion, IsUnknown, JSONEditData, JSONEditMap, JSONEditOptions, JSONEdits, KeyOf, KnownPackageJson, MergeObject, ModifyJSONCDataOptions, Module, MoodifyJSONFileOptions, NoInfer, OmitByValue, OmitIndexSignature, OmitNever, PackageDependencyItem, PackageDependencyType, PackageInfo, PackageInfoList, PackageInfoMap, PackageJson, PackageJsonPerson, PackageManagerCommandName, PackageManagerCommandSpec, PackageManagerCommands, PackageManagerConfig, PackageManagerId, PackageManagerScriptOptions, PackageName, PathAlias, PathOptions, PathTo, PickByValue, PickKeyOf, PickPathAlias, PredefinedPathAliases, Prettify, ProjectParams, RequireExactlyOne, ResolveModulePathOptions, ResolvedImportList, ResolvedImportListPromise, ResolvedImportMap, ResolvedImportMapPromise, ResolvedImportOption, ResolvedPromise, Select, SelectionMap, SingleProp, StringLiteral, UninstallPackageOptions, ValueAtPath, ValueKeyOf, ValueKeyOfDeep, ValueOf, __ };
+export { _dirname, _filename, configLanguages, createFile, defineFileSystemEntries, defineFileSystemStorage, definePackage, definePackageManager, definePackageManagerClient, definePathAliases, dependencyTypeMap, detectGlobalPackageManagers, detectLockfilePackageManagers, detectPackageManagers, filterPackageManagers, findDependencyInPackageJson, findPackageManager, findPackageManagerSafely, findResolvedModulePath, getAliasMap, getConfigFormat, getFolderByPackageName, getGitRootFolder, getGlobalVersions, getPackageFolder, getPath, getWorkspaceFolder, importMap, importer, isConfigFormat, isDependencyInPackageJson, isPackageDependency, isPackageModuleFound, isWritable, mapPackageManagers, modifyConfig, modifyConfigFile, modifyJSON, modifyJSONFile, packageManagerConfigs, predefinedPathAliases, project, readFile, readFileSafely, resolveConfigSource, resolveModule, resolveModulePath, resolvePackageModulePath, storage, tempFileSystem, workspace };
+export type { AliasDefinition, AliasDefinitionMap, AliasMap, AnyFunction, AsyncCacheFn, Awaitable, CallerLocationOptions, Cast, CheckResult, ConfigEditData, ConfigEditOptions, ConfigEdits, ConfigFormat, ConfigSourceData, ConfigSourceInput, ConfigSourceInputType, DefinePackageFn, DetectPackageManagerOptions, Entry, EntryOf, EnumToLiteral, Equals, ExtractImportOptionModule, FileSystemEntriesDefinition, FindDependencyInPackageJsonOptions, FromEntries, GetGitRootFolderOptions, GetPathOptions, GetWorkspaceFolderOptions, ImportCallback, ImportList, ImportMap, ImportMapFn, ImportMapOptions, ImportModuleData, ImportModuleFn, ImportOption, ImportOptionData, ImportPackageData, ImporterOptions, InstallPackageOptions, InstallerFn, IsExactBoolean, IsNever, IsUnion, IsUnknown, JSONEditData, JSONEditMap, JSONEditOptions, JSONEdits, KeyOf, KnownPackageJson, MergeObject, ModifyConfigFileOptions, ModifyConfigOptions, ModifyJSONCDataOptions, Module, MoodifyJSONFileOptions, NoInfer, OmitByValue, OmitIndexSignature, OmitNever, PackageDependencyItem, PackageDependencyType, PackageInfo, PackageInfoList, PackageInfoMap, PackageJson, PackageJsonPerson, PackageManager, PackageManagerCommandName, PackageManagerCommandSpec, PackageManagerCommands, PackageManagerConfig, PackageManagerId, PackageManagerScriptOptions, PackageManagers, PackageName, PathAlias, PathAliasResolveOptions, PathOptions, PathTo, PickByValue, PickKeyOf, PickPathAlias, PredefinedPathAliases, Prettify, ProjectParams, ReadFileOptions, RequireExactlyOne, ResolveModulePathOptions, ResolvedImportList, ResolvedImportListPromise, ResolvedImportMap, ResolvedImportMapPromise, ResolvedImportOption, ResolvedPromise, Select, SelectionMap, SingleProp, StringLiteral, UninstallPackageOptions, ValueAtPath, ValueKeyOf, ValueKeyOfDeep, ValueOf, __ };