@karmaniverous/get-dotenv 6.0.0 → 6.1.0

package/dist/plugins-aws.mjs

@@ -151,6 +151,10 @@ function defaultsDeep(...layers) {
 /**
  * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
  * Future-proofs for ordering/sorting changes (currently insertion order).
+ *
+ * @param filename - Destination dotenv file path.
+ * @param data - Env-like map of values to write (values may be `undefined`).
+ * @returns A `Promise\<void\>` which resolves when the file has been written.
  */
 async function writeDotenvFile(filename, data) {
     // Serialize: key=value with quotes only for multiline values.
@@ -386,14 +390,20 @@ const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Numbe
     }
 };
 /**
- * Load a module default export from a JS/TS file with robust fallbacks:
- * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
- *   1) try direct import (if a TS loader is active),
- *   2) esbuild bundle to a temp ESM file,
- *   3) typescript.transpileModule fallback for simple modules.
+ * Load a module default export from a JS/TS file with robust fallbacks.
+ *
+ * Behavior by extension:
+ *
+ * - `.js`/`.mjs`/`.cjs`: direct dynamic import.
+ * - `.ts`/`.mts`/`.cts`/`.tsx`:
+ *   - try direct dynamic import (when a TS loader is active),
+ *   - else compile via `esbuild` to a cached `.mjs` file and import,
+ *   - else fallback to `typescript.transpileModule` for simple modules.
  *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
+ * @typeParam T - Type of the expected default export.
+ * @param absPath - Absolute path to the source file.
+ * @param cacheDirName - Cache subfolder under `.tsbuild/`.
+ * @returns A `Promise\<T | undefined\>` resolving to the default export (if any).
  */
 const loadModuleDefault = async (absPath, cacheDirName) => {
     const ext = path.extname(absPath).toLowerCase();
@@ -465,6 +475,10 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
 /**
  * Omit keys whose runtime value is undefined from a shallow object.
  * Returns a Partial with non-undefined value types preserved.
+ *
+ * @typeParam T - Input object shape.
+ * @param obj - Object to filter.
+ * @returns A shallow copy of `obj` without keys whose value is `undefined`.
  */
 function omitUndefined(obj) {
     const out = {};
@@ -476,6 +490,10 @@ function omitUndefined(obj) {
 }
 /**
  * Specialized helper for env-like maps: drop undefined and return string-only.
+ *
+ * @typeParam V - Value type for present entries (must extend `string`).
+ * @param obj - Env-like record containing `string | undefined` values.
+ * @returns A new record containing only the keys with defined values.
  */
 function omitUndefinedRecord(obj) {
     const out = {};
@@ -690,6 +708,11 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
  * Apply a dynamic map to the target progressively.
  * - Functions receive (target, env) and may return string | undefined.
  * - Literals are assigned directly (including undefined).
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param map - Dynamic map to apply (functions and/or literal values).
+ * @param env - Selected environment name (if any) passed through to dynamic functions.
+ * @returns Nothing.
  */
 function applyDynamicMap(target, map, env) {
     if (!map)
@@ -709,6 +732,12 @@ function applyDynamicMap(target, map, env) {
  * Error behavior:
  * - On failure to load/compile/evaluate the module, throws a unified message:
  *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param absPath - Absolute path to the dynamic module file.
+ * @param env - Selected environment name (if any).
+ * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
+ * @returns A `Promise\<void\>` which resolves after the module (if present) has been applied.
  */
 async function loadAndApplyDynamic(target, absPath, env, cacheDirName) {
     if (!(await fs.exists(absPath)))
@@ -1799,6 +1828,10 @@ function renderOptionGroups(cmd) {
 /**
  * Compose root/parent help output by inserting grouped sections between
  * Options and Commands, ensuring a trailing blank line.
+ *
+ * @param base - Base help text produced by Commander.
+ * @param cmd - Command instance whose grouped options should be rendered.
+ * @returns The modified help text with grouped blocks inserted.
  */
 function buildHelpInformation(base, cmd) {
     const groups = renderOptionGroups(cmd);
@@ -2395,7 +2428,10 @@ const buildSpawnEnv = (base, overlay) => {
  * Apply resolved AWS context to `process.env` and `ctx.plugins`.
  * Centralizes logic shared between the plugin action and `afterResolve` hook.
  *
+ * @param out - Resolved AWS context to apply.
+ * @param ctx - Host context to publish non-sensitive metadata into.
  * @param setProcessEnv - Whether to write credentials/region to `process.env` (default true).
+ * @returns Nothing.
  */
 function applyAwsContext(out, ctx, setProcessEnv = true) {
     const { profile, region, credentials } = out;
@@ -2431,6 +2467,9 @@ const unquote = (s) => s.length >= 2 &&
     : s;
 /**
  * Parse AWS credentials from JSON output (AWS CLI v2 export-credentials).
+ *
+ * @param txt - Raw stdout text from the AWS CLI.
+ * @returns Parsed credentials, or `undefined` when the input is not recognized.
  */
 const parseExportCredentialsJson = (txt) => {
     try {
@@ -2454,6 +2493,9 @@ const parseExportCredentialsJson = (txt) => {
 /**
  * Parse AWS credentials from environment-export output (shell-agnostic).
  * Supports POSIX `export KEY=VAL` and PowerShell `$Env:KEY=VAL`.
+ *
+ * @param txt - Raw stdout text from the AWS CLI.
+ * @returns Parsed credentials, or `undefined` when the input is not recognized.
  */
 const parseExportCredentialsEnv = (txt) => {
     const lines = txt.split(/\r?\n/);
@@ -2539,6 +2581,7 @@ const exportCredentials = async (profile, timeoutMs = DEFAULT_TIMEOUT_MS) => {
  * Applies strategy (cli-export vs none) and handling for SSO login-on-demand.
  *
  * @param options - Context options including current dotenv and plugin config.
+ * @returns A `Promise\<AwsContext\>` containing any resolved profile, region, and credentials.
  */
 const resolveAwsContext = async ({ dotenv, cfg, }) => {
     const profileKey = cfg.profileKey ?? 'AWS_LOCAL_PROFILE';

package/dist/plugins-batch.mjs

@@ -152,6 +152,10 @@ function defaultsDeep(...layers) {
 /**
  * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
  * Future-proofs for ordering/sorting changes (currently insertion order).
+ *
+ * @param filename - Destination dotenv file path.
+ * @param data - Env-like map of values to write (values may be `undefined`).
+ * @returns A `Promise\<void\>` which resolves when the file has been written.
  */
 async function writeDotenvFile(filename, data) {
     // Serialize: key=value with quotes only for multiline values.
@@ -387,14 +391,20 @@ const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Numbe
     }
 };
 /**
- * Load a module default export from a JS/TS file with robust fallbacks:
- * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
- *   1) try direct import (if a TS loader is active),
- *   2) esbuild bundle to a temp ESM file,
- *   3) typescript.transpileModule fallback for simple modules.
+ * Load a module default export from a JS/TS file with robust fallbacks.
+ *
+ * Behavior by extension:
+ *
+ * - `.js`/`.mjs`/`.cjs`: direct dynamic import.
+ * - `.ts`/`.mts`/`.cts`/`.tsx`:
+ *   - try direct dynamic import (when a TS loader is active),
+ *   - else compile via `esbuild` to a cached `.mjs` file and import,
+ *   - else fallback to `typescript.transpileModule` for simple modules.
  *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
+ * @typeParam T - Type of the expected default export.
+ * @param absPath - Absolute path to the source file.
+ * @param cacheDirName - Cache subfolder under `.tsbuild/`.
+ * @returns A `Promise\<T | undefined\>` resolving to the default export (if any).
  */
 const loadModuleDefault = async (absPath, cacheDirName) => {
     const ext = path.extname(absPath).toLowerCase();
@@ -466,6 +476,10 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
 /**
  * Omit keys whose runtime value is undefined from a shallow object.
  * Returns a Partial with non-undefined value types preserved.
+ *
+ * @typeParam T - Input object shape.
+ * @param obj - Object to filter.
+ * @returns A shallow copy of `obj` without keys whose value is `undefined`.
  */
 function omitUndefined(obj) {
     const out = {};
@@ -477,6 +491,10 @@ function omitUndefined(obj) {
 }
 /**
  * Specialized helper for env-like maps: drop undefined and return string-only.
+ *
+ * @typeParam V - Value type for present entries (must extend `string`).
+ * @param obj - Env-like record containing `string | undefined` values.
+ * @returns A new record containing only the keys with defined values.
  */
 function omitUndefinedRecord(obj) {
     const out = {};
@@ -691,6 +709,11 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
  * Apply a dynamic map to the target progressively.
  * - Functions receive (target, env) and may return string | undefined.
  * - Literals are assigned directly (including undefined).
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param map - Dynamic map to apply (functions and/or literal values).
+ * @param env - Selected environment name (if any) passed through to dynamic functions.
+ * @returns Nothing.
  */
 function applyDynamicMap(target, map, env) {
     if (!map)
@@ -710,6 +733,12 @@ function applyDynamicMap(target, map, env) {
  * Error behavior:
  * - On failure to load/compile/evaluate the module, throws a unified message:
  *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param absPath - Absolute path to the dynamic module file.
+ * @param env - Selected environment name (if any).
+ * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
+ * @returns A `Promise\<void\>` which resolves after the module (if present) has been applied.
  */
 async function loadAndApplyDynamic(target, absPath, env, cacheDirName) {
     if (!(await fs.exists(absPath)))
@@ -1781,6 +1810,10 @@ function renderOptionGroups(cmd) {
 /**
  * Compose root/parent help output by inserting grouped sections between
  * Options and Commands, ensuring a trailing blank line.
+ *
+ * @param base - Base help text produced by Commander.
+ * @param cmd - Command instance whose grouped options should be rendered.
+ * @returns The modified help text with grouped blocks inserted.
  */
 function buildHelpInformation(base, cmd) {
     const groups = renderOptionGroups(cmd);
@@ -2276,6 +2309,10 @@ class GetDotenvCli extends Command {
 /**
  * Compose a child-process env overlay from dotenv and the merged CLI options bag.
  * Returns a shallow object including getDotenvCliOptions when serializable.
+ *
+ * @param merged - Resolved CLI options bag (or a JSON-serializable subset).
+ * @param dotenv - Composed dotenv variables for the current invocation.
+ * @returns A string-only env overlay suitable for child process spawning.
  */
 function composeNestedEnv(merged, dotenv) {
     const out = {};
@@ -2298,6 +2335,7 @@ function composeNestedEnv(merged, dotenv) {
  * Strip one layer of symmetric outer quotes (single or double) from a string.
  *
  * @param s - Input string.
+ * @returns `s` without one symmetric outer quote pair (when present).
  */
 const stripOne = (s) => {
     if (s.length < 2)
@@ -2310,6 +2348,9 @@ const stripOne = (s) => {
 /**
  * Preserve argv array for Node -e/--eval payloads under shell-off and
  * peel one symmetric outer quote layer from the code argument.
+ *
+ * @param args - Argument vector intended for direct execution (shell-off).
+ * @returns Either the original `args` or a modified copy with a normalized eval payload.
  */
 function maybePreserveNodeEvalArgv(args) {
     if (args.length >= 3) {

package/dist/plugins-cmd.mjs

@@ -151,6 +151,10 @@ function defaultsDeep(...layers) {
 /**
  * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
  * Future-proofs for ordering/sorting changes (currently insertion order).
+ *
+ * @param filename - Destination dotenv file path.
+ * @param data - Env-like map of values to write (values may be `undefined`).
+ * @returns A `Promise\<void\>` which resolves when the file has been written.
  */
 async function writeDotenvFile(filename, data) {
     // Serialize: key=value with quotes only for multiline values.
@@ -386,14 +390,20 @@ const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Numbe
     }
 };
 /**
- * Load a module default export from a JS/TS file with robust fallbacks:
- * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
- *   1) try direct import (if a TS loader is active),
- *   2) esbuild bundle to a temp ESM file,
- *   3) typescript.transpileModule fallback for simple modules.
+ * Load a module default export from a JS/TS file with robust fallbacks.
+ *
+ * Behavior by extension:
+ *
+ * - `.js`/`.mjs`/`.cjs`: direct dynamic import.
+ * - `.ts`/`.mts`/`.cts`/`.tsx`:
+ *   - try direct dynamic import (when a TS loader is active),
+ *   - else compile via `esbuild` to a cached `.mjs` file and import,
+ *   - else fallback to `typescript.transpileModule` for simple modules.
  *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
+ * @typeParam T - Type of the expected default export.
+ * @param absPath - Absolute path to the source file.
+ * @param cacheDirName - Cache subfolder under `.tsbuild/`.
+ * @returns A `Promise\<T | undefined\>` resolving to the default export (if any).
  */
 const loadModuleDefault = async (absPath, cacheDirName) => {
     const ext = path.extname(absPath).toLowerCase();
@@ -465,6 +475,10 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
 /**
  * Omit keys whose runtime value is undefined from a shallow object.
  * Returns a Partial with non-undefined value types preserved.
+ *
+ * @typeParam T - Input object shape.
+ * @param obj - Object to filter.
+ * @returns A shallow copy of `obj` without keys whose value is `undefined`.
  */
 function omitUndefined(obj) {
     const out = {};
@@ -476,6 +490,10 @@ function omitUndefined(obj) {
 }
 /**
  * Specialized helper for env-like maps: drop undefined and return string-only.
+ *
+ * @typeParam V - Value type for present entries (must extend `string`).
+ * @param obj - Env-like record containing `string | undefined` values.
+ * @returns A new record containing only the keys with defined values.
  */
 function omitUndefinedRecord(obj) {
     const out = {};
@@ -696,6 +714,11 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
  * Apply a dynamic map to the target progressively.
  * - Functions receive (target, env) and may return string | undefined.
  * - Literals are assigned directly (including undefined).
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param map - Dynamic map to apply (functions and/or literal values).
+ * @param env - Selected environment name (if any) passed through to dynamic functions.
+ * @returns Nothing.
  */
 function applyDynamicMap(target, map, env) {
     if (!map)
@@ -715,6 +738,12 @@ function applyDynamicMap(target, map, env) {
  * Error behavior:
  * - On failure to load/compile/evaluate the module, throws a unified message:
  *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param absPath - Absolute path to the dynamic module file.
+ * @param env - Selected environment name (if any).
+ * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
+ * @returns A `Promise\<void\>` which resolves after the module (if present) has been applied.
  */
 async function loadAndApplyDynamic(target, absPath, env, cacheDirName) {
     if (!(await fs.exists(absPath)))
@@ -1863,6 +1892,10 @@ function renderOptionGroups(cmd) {
 /**
  * Compose root/parent help output by inserting grouped sections between
  * Options and Commands, ensuring a trailing blank line.
+ *
+ * @param base - Base help text produced by Commander.
+ * @param cmd - Command instance whose grouped options should be rendered.
+ * @returns The modified help text with grouped blocks inserted.
  */
 function buildHelpInformation(base, cmd) {
     const groups = renderOptionGroups(cmd);
@@ -2364,6 +2397,10 @@ const baseGetDotenvCliOptions = baseRootOptionDefaults;
 /**
  * Compose a child-process env overlay from dotenv and the merged CLI options bag.
  * Returns a shallow object including getDotenvCliOptions when serializable.
+ *
+ * @param merged - Resolved CLI options bag (or a JSON-serializable subset).
+ * @param dotenv - Composed dotenv variables for the current invocation.
+ * @returns A string-only env overlay suitable for child process spawning.
  */
 function composeNestedEnv(merged, dotenv) {
     const out = {};
@@ -2386,6 +2423,7 @@ function composeNestedEnv(merged, dotenv) {
  * Strip one layer of symmetric outer quotes (single or double) from a string.
  *
  * @param s - Input string.
+ * @returns `s` without one symmetric outer quote pair (when present).
  */
 const stripOne = (s) => {
     if (s.length < 2)
@@ -2398,6 +2436,9 @@ const stripOne = (s) => {
 /**
  * Preserve argv array for Node -e/--eval payloads under shell-off and
  * peel one symmetric outer quote layer from the code argument.
+ *
+ * @param args - Argument vector intended for direct execution (shell-off).
+ * @returns Either the original `args` or a modified copy with a normalized eval payload.
  */
 function maybePreserveNodeEvalArgv(args) {
     if (args.length >= 3) {

package/dist/plugins-init.mjs

@@ -153,6 +153,10 @@ function defaultsDeep(...layers) {
 /**
  * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
  * Future-proofs for ordering/sorting changes (currently insertion order).
+ *
+ * @param filename - Destination dotenv file path.
+ * @param data - Env-like map of values to write (values may be `undefined`).
+ * @returns A `Promise\<void\>` which resolves when the file has been written.
  */
 async function writeDotenvFile(filename, data) {
     // Serialize: key=value with quotes only for multiline values.
@@ -388,14 +392,20 @@ const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Numbe
     }
 };
 /**
- * Load a module default export from a JS/TS file with robust fallbacks:
- * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
- *   1) try direct import (if a TS loader is active),
- *   2) esbuild bundle to a temp ESM file,
- *   3) typescript.transpileModule fallback for simple modules.
+ * Load a module default export from a JS/TS file with robust fallbacks.
+ *
+ * Behavior by extension:
+ *
+ * - `.js`/`.mjs`/`.cjs`: direct dynamic import.
+ * - `.ts`/`.mts`/`.cts`/`.tsx`:
+ *   - try direct dynamic import (when a TS loader is active),
+ *   - else compile via `esbuild` to a cached `.mjs` file and import,
+ *   - else fallback to `typescript.transpileModule` for simple modules.
  *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
+ * @typeParam T - Type of the expected default export.
+ * @param absPath - Absolute path to the source file.
+ * @param cacheDirName - Cache subfolder under `.tsbuild/`.
+ * @returns A `Promise\<T | undefined\>` resolving to the default export (if any).
  */
 const loadModuleDefault = async (absPath, cacheDirName) => {
     const ext = path.extname(absPath).toLowerCase();
@@ -467,6 +477,10 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
 /**
  * Omit keys whose runtime value is undefined from a shallow object.
  * Returns a Partial with non-undefined value types preserved.
+ *
+ * @typeParam T - Input object shape.
+ * @param obj - Object to filter.
+ * @returns A shallow copy of `obj` without keys whose value is `undefined`.
  */
 function omitUndefined(obj) {
     const out = {};
@@ -478,6 +492,10 @@ function omitUndefined(obj) {
 }
 /**
  * Specialized helper for env-like maps: drop undefined and return string-only.
+ *
+ * @typeParam V - Value type for present entries (must extend `string`).
+ * @param obj - Env-like record containing `string | undefined` values.
+ * @returns A new record containing only the keys with defined values.
  */
 function omitUndefinedRecord(obj) {
     const out = {};
@@ -637,6 +655,11 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
  * Apply a dynamic map to the target progressively.
  * - Functions receive (target, env) and may return string | undefined.
  * - Literals are assigned directly (including undefined).
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param map - Dynamic map to apply (functions and/or literal values).
+ * @param env - Selected environment name (if any) passed through to dynamic functions.
+ * @returns Nothing.
  */
 function applyDynamicMap(target, map, env) {
     if (!map)
@@ -656,6 +679,12 @@ function applyDynamicMap(target, map, env) {
  * Error behavior:
  * - On failure to load/compile/evaluate the module, throws a unified message:
  *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param absPath - Absolute path to the dynamic module file.
+ * @param env - Selected environment name (if any).
+ * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
+ * @returns A `Promise\<void\>` which resolves after the module (if present) has been applied.
  */
 async function loadAndApplyDynamic(target, absPath, env, cacheDirName) {
     if (!(await fs.exists(absPath)))
@@ -1601,6 +1630,10 @@ function renderOptionGroups(cmd) {
 /**
  * Compose root/parent help output by inserting grouped sections between
  * Options and Commands, ensuring a trailing blank line.
+ *
+ * @param base - Base help text produced by Commander.
+ * @param cmd - Command instance whose grouped options should be rendered.
+ * @returns The modified help text with grouped blocks inserted.
  */
 function buildHelpInformation(base, cmd) {
     const groups = renderOptionGroups(cmd);
@@ -2120,14 +2153,21 @@ const readMergedOptions = (cmd) => {
 };
 
 /**
- * Ensure a directory exists.
+ * Ensure a directory exists (parents included).
+ *
+ * @param p - Directory path to create.
+ * @returns A `Promise\<string\>` resolving to the provided `p` value.
  */
 const ensureDir = async (p) => {
     await fs.ensureDir(p);
     return p;
 };
 /**
- * Write text content to a file, ensuring the parent directory exists.
+ * Write UTF-8 text content to a file, ensuring the parent directory exists.
+ *
+ * @param dest - Destination file path.
+ * @param data - File contents to write.
+ * @returns A `Promise\<void\>` which resolves when the file is written.
  */
 const writeFile = async (dest, data) => {
     await ensureDir(path.dirname(dest));
@@ -2139,6 +2179,7 @@ const writeFile = async (dest, data) => {
  * @param src - Source file path.
  * @param dest - Destination file path.
  * @param substitutions - Map of token literals to replacement strings.
+ * @returns A `Promise\<void\>` which resolves when the file has been copied.
  */
 const copyTextFile = async (src, dest, substitutions) => {
     const contents = await fs.readFile(src, 'utf-8');
@@ -2150,6 +2191,10 @@ const copyTextFile = async (src, dest, substitutions) => {
 /**
  * Ensure a set of lines exist (exact match) in a file. Creates the file
  * when missing. Returns whether it was created or changed.
+ *
+ * @param filePath - Target file path to create/update.
+ * @param lines - Lines which must be present (exact string match).
+ * @returns A `Promise\<object\>` describing whether the file was created and/or changed.
  */
 const ensureLines = async (filePath, lines) => {
     const exists = await fs.pathExists(filePath);
@@ -2177,11 +2222,23 @@ const ensureLines = async (filePath, lines) => {
     return { created: false, changed: false };
 };
 
-// Templates root used by the scaffolder
+/**
+ * Absolute path to the shipped templates directory.
+ *
+ * Used by the init scaffolder to locate files under `templates/` at runtime.
+ *
+ * @remarks
+ * This path is resolved relative to the current working directory. It assumes
+ * the `templates/` folder is present alongside the installed package (or in the
+ * repository when running from source).
+ */
 const TEMPLATES_ROOT = path.resolve('templates');
 
 /**
  * Plan the copy operations for configuration files.
+ *
+ * @param options - Planning options for config scaffolding.
+ * @returns An array of copy operations to perform.
  */
 const planConfigCopies = ({ format, withLocal, destRoot, }) => {
     const copies = [];
@@ -2225,6 +2282,9 @@ const planConfigCopies = ({ format, withLocal, destRoot, }) => {
 };
 /**
  * Plan the copy operations for the CLI skeleton.
+ *
+ * @param options - Planning options for CLI scaffolding.
+ * @returns An array of copy operations to perform.
  */
 const planCliCopies = ({ cliName, destRoot, }) => {
     const subs = { __CLI_NAME__: cliName };
@@ -2246,6 +2306,8 @@ const planCliCopies = ({ cliName, destRoot, }) => {
 /**
  * Determine whether the current environment should be treated as non-interactive.
  * CI heuristics include: CI, GITHUB_ACTIONS, BUILDKITE, TEAMCITY_VERSION, TF_BUILD.
+ *
+ * @returns `true` when running in a CI-like environment or when stdin/stdout are not TTYs.
  */
 const isNonInteractive = () => {
     const ciLike = process.env.CI ||
@@ -2258,6 +2320,11 @@ const isNonInteractive = () => {
 /**
  * Prompt the user for a file collision decision.
  * Returns a single-character code representing overwrite/example/skip (or 'all' variants).
+ *
+ * @param filePath - Path of the colliding file (for display).
+ * @param logger - Logger used for user-facing messages.
+ * @param rl - Readline interface used to capture user input.
+ * @returns A single-character decision code.
  */
 const promptDecision = async (filePath, logger, rl) => {
     logger.log(`File exists: ${filePath}\nChoose: [o]verwrite, [e]xample, [s]kip, [O]verwrite All, [E]xample All, [S]kip All`);