@cleocode/paths 2026.9.20 → 2026.9.21

package/dist/exec-path.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Cross-platform PATH composition and executable lookup.
+ *
+ * `PATH` is `:`-delimited on POSIX and `;`-delimited on Windows, where the
+ * variable is also commonly spelled `Path` and a bare command name resolves
+ * through `PATHEXT` (`git` → `git.exe`, `cleo` → `cleo.cmd`). Building PATH as
+ * `${dir}:${PATH}` on Windows fuses the new directory with the first real
+ * entry, and splitting on `:` cuts every `C:\…` drive-letter entry in half, so
+ * each helper here takes the platform explicitly (defaulting to the running
+ * one) and joins with that platform's path module. Tests inject `win32` on
+ * any host.
+ *
+ * Lookups are in-process filesystem probes — no `which`/`where` child — so
+ * they behave identically on every OS and cost no process spawn.
+ *
+ * @task T12605
+ */
+/** Platform-injection options shared by the PATH helpers. */
+export interface ExecPathOptions {
+    /** Platform whose PATH rules apply. @defaultValue `process.platform` */
+    platform?: NodeJS.Platform;
+    /** Environment holding `PATH`/`Path` and `PATHEXT`. @defaultValue `process.env` */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Predicate deciding whether a candidate file is runnable.
+     * @defaultValue a regular file that is executable (POSIX) or exists (win32)
+     */
+    isExecutable?: (candidate: string) => boolean;
+}
+/**
+ * Return the PATH list delimiter for a platform (`;` on win32, `:` elsewhere).
+ *
+ * @param platform - Target platform. @defaultValue `process.platform`
+ * @returns The delimiter character.
+ */
+export declare function pathDelimiterFor(platform?: NodeJS.Platform): string;
+/**
+ * Return the environment key that holds the executable search path.
+ *
+ * Windows environment names are case-insensitive and the system spelling is
+ * `Path`; writing a second `PATH` key beside it leaves the child with two
+ * conflicting values. The existing key is reused whatever its case.
+ *
+ * @param env - Environment to inspect.
+ * @param platform - Target platform. @defaultValue `process.platform`
+ * @returns `PATH`, or the existing case-variant on win32.
+ */
+export declare function pathEnvKey(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+/**
+ * Split a PATH value into its non-empty directory entries.
+ *
+ * @param value - Raw PATH value (may be undefined).
+ * @param platform - Target platform. @defaultValue `process.platform`
+ * @returns Directory entries in search order.
+ * @example
+ * ```ts
+ * splitPathEnv('C:\\Windows;C:\\Git\\cmd', 'win32'); // ['C:\\Windows', 'C:\\Git\\cmd']
+ * ```
+ */
+export declare function splitPathEnv(value: string | undefined, platform?: NodeJS.Platform): string[];
+/**
+ * Prepend a directory to a PATH value using the platform's delimiter.
+ *
+ * @param dir - Directory to search first.
+ * @param currentPath - Existing PATH value (may be empty or undefined).
+ * @param platform - Target platform. @defaultValue `process.platform`
+ * @returns The composed PATH value; `dir` alone when `currentPath` is empty.
+ * @example
+ * ```ts
+ * prependPathEntry('C:\\shim', 'C:\\Windows', 'win32'); // 'C:\\shim;C:\\Windows'
+ * ```
+ */
+export declare function prependPathEntry(dir: string, currentPath: string | undefined, platform?: NodeJS.Platform): string;
+/**
+ * List the file names a bare command can resolve to on a platform.
+ *
+ * On win32 each `PATHEXT` extension is tried, and the bare name only when it
+ * already carries one of those extensions. Elsewhere the name is used as-is.
+ *
+ * @param name - Command name, e.g. `git`.
+ * @param opts - Platform and environment overrides.
+ * @returns Candidate file names in resolution order.
+ */
+export declare function executableNames(name: string, opts?: ExecPathOptions): string[];
+/**
+ * Resolve a command to the absolute path the OS would run, or `null`.
+ *
+ * Honours the platform's PATH delimiter, the win32 `Path` spelling, and
+ * `PATHEXT`. A name containing a path separator is checked directly rather
+ * than searched for.
+ *
+ * @param name - Command name or path.
+ * @param opts - Platform, environment and executability overrides.
+ * @returns Absolute path of the first match, or `null`.
+ * @example
+ * ```ts
+ * findOnPath('git'); // '/usr/bin/git' on Linux, 'C:\\Program Files\\Git\\cmd\\git.exe' on Windows
+ * ```
+ */
+export declare function findOnPath(name: string, opts?: ExecPathOptions): string | null;
+/** A shell command line resolved to an argv the platform can spawn. */
+export interface ShellInvocation {
+    /** Shell executable. */
+    file: string;
+    /** Arguments that make the shell run the command line once. */
+    args: string[];
+    /** Pass to `child_process` so cmd.exe receives the quoted line untouched. */
+    windowsVerbatimArguments: boolean;
+}
+/**
+ * Resolve how to run a shell command line on a platform.
+ *
+ * `/bin/sh -c` on POSIX; on win32 `%ComSpec%` (cmd.exe) with `/d /s /c` and
+ * the line quoted verbatim — the same resolution Node applies for
+ * `shell: true`, made explicit so every caller that runs user-authored
+ * command strings (worktree hooks, release build commands) shares one
+ * resolver and tests can pin the platform.
+ *
+ * @param command - Command line to run.
+ * @param opts - Platform and environment overrides.
+ * @returns The executable, its argv and the verbatim-arguments flag.
+ * @example
+ * ```ts
+ * const sh = shellInvocation('pnpm build');
+ * execFile(sh.file, sh.args, { windowsVerbatimArguments: sh.windowsVerbatimArguments });
+ * ```
+ */
+export declare function shellInvocation(command: string, opts?: ExecPathOptions): ShellInvocation;
+/**
+ * Quote one argument for a `.cmd`/`.bat` target launched through cmd.exe.
+ *
+ * Two layers, as cmd parses the line and the batch file's program parses its
+ * argv: MSVCRT quoting (backslashes before a quote doubled, the quote
+ * escaped, the whole argument wrapped in quotes), then every cmd
+ * metacharacter caret-escaped TWICE — cmd re-parses the line when it
+ * dispatches a batch file, consuming one caret layer each pass. Because every
+ * quote is escaped, cmd never sees a quoted region in which operators such as
+ * `&` or `|` would be live. `%VAR%` expands before carets are processed, but
+ * `%NAME^%` names a variable (`NAME^`) that is never defined, and an undefined
+ * reference is left verbatim on a `cmd /c` line. This is the scheme `cross-spawn` uses against the BatBadBut class
+ * (CVE-2024-27980).
+ *
+ * @param arg - Literal argument.
+ * @returns The escaped token.
+ * @throws When `arg` holds CR or LF: cmd.exe ends the command at a line
+ *   break and no escape can carry one into a batch file.
+ * @example
+ * ```ts
+ * quoteCmdArg('a b'); // '^^^"a^^^ b^^^"'
+ * ```
+ */
+export declare function quoteCmdArg(arg: string): string;
+/** An executable plus argv, resolved for `child_process.spawn` on a platform. */
+export interface SpawnInvocation {
+    /** File to spawn. */
+    file: string;
+    /** Arguments to pass. */
+    args: string[];
+    /** Pass through to `spawn` — `true` only for the cmd.exe batch form. */
+    windowsVerbatimArguments: boolean;
+}
+/**
+ * Resolve how to spawn `command args` without a shell on any platform.
+ *
+ * POSIX: returned unchanged. win32: the command is resolved to the absolute
+ * path {@link findOnPath} finds, because Node's own lookup tries only `.exe`
+ * and `.com`. A `.cmd`/`.bat` target (every npm-installed CLI) cannot be
+ * spawned directly — Node refuses since CVE-2024-27980 — so it is launched
+ * through `%ComSpec% /d /s /c` with every token escaped by {@link quoteCmdArg}.
+ *
+ * @param command - Command name or path.
+ * @param args - Literal arguments.
+ * @param opts - Platform and environment overrides.
+ * @returns The spawnable invocation.
+ * @throws When a batch-file argument contains a line break (see {@link quoteCmdArg}).
+ * @example
+ * ```ts
+ * const inv = resolveSpawnInvocation('codex', ['--full-auto', promptFile]);
+ * spawn(inv.file, inv.args, { windowsVerbatimArguments: inv.windowsVerbatimArguments });
+ * ```
+ */
+export declare function resolveSpawnInvocation(command: string, args: readonly string[], opts?: ExecPathOptions): SpawnInvocation;
+//# sourceMappingURL=exec-path.d.ts.map

package/dist/exec-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-path.d.ts","sourceRoot":"","sources":["../src/exec-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;CAC/C;AAKD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,MAAM,CAErF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,CAGR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,EAAE,CAEV;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,CAER;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,MAAM,EAAE,CAWlF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,MAAM,GAAG,IAAI,CAgBlF;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,6EAA6E;IAC7E,wBAAwB,EAAE,OAAO,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,eAAe,CAS5F;AAKD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK/C;AA2BD,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,wBAAwB,EAAE,OAAO,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,GAAE,eAAoB,GACzB,eAAe,CAYjB"}

package/dist/exec-path.js

@@ -0,0 +1,266 @@
+/**
+ * Cross-platform PATH composition and executable lookup.
+ *
+ * `PATH` is `:`-delimited on POSIX and `;`-delimited on Windows, where the
+ * variable is also commonly spelled `Path` and a bare command name resolves
+ * through `PATHEXT` (`git` → `git.exe`, `cleo` → `cleo.cmd`). Building PATH as
+ * `${dir}:${PATH}` on Windows fuses the new directory with the first real
+ * entry, and splitting on `:` cuts every `C:\…` drive-letter entry in half, so
+ * each helper here takes the platform explicitly (defaulting to the running
+ * one) and joins with that platform's path module. Tests inject `win32` on
+ * any host.
+ *
+ * Lookups are in-process filesystem probes — no `which`/`where` child — so
+ * they behave identically on every OS and cost no process spawn.
+ *
+ * @task T12605
+ */
+import { accessSync, constants, statSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
+/** `PATHEXT` used on Windows when the variable is unset. */
+const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+/**
+ * Return the PATH list delimiter for a platform (`;` on win32, `:` elsewhere).
+ *
+ * @param platform - Target platform. @defaultValue `process.platform`
+ * @returns The delimiter character.
+ */
+export function pathDelimiterFor(platform = process.platform) {
+    return platform === 'win32' ? win32.delimiter : posix.delimiter;
+}
+/**
+ * Return the environment key that holds the executable search path.
+ *
+ * Windows environment names are case-insensitive and the system spelling is
+ * `Path`; writing a second `PATH` key beside it leaves the child with two
+ * conflicting values. The existing key is reused whatever its case.
+ *
+ * @param env - Environment to inspect.
+ * @param platform - Target platform. @defaultValue `process.platform`
+ * @returns `PATH`, or the existing case-variant on win32.
+ */
+export function pathEnvKey(env = process.env, platform = process.platform) {
+    if (platform !== 'win32')
+        return 'PATH';
+    return Object.keys(env).find((key) => key.toUpperCase() === 'PATH') ?? 'PATH';
+}
+/**
+ * Split a PATH value into its non-empty directory entries.
+ *
+ * @param value - Raw PATH value (may be undefined).
+ * @param platform - Target platform. @defaultValue `process.platform`
+ * @returns Directory entries in search order.
+ * @example
+ * ```ts
+ * splitPathEnv('C:\\Windows;C:\\Git\\cmd', 'win32'); // ['C:\\Windows', 'C:\\Git\\cmd']
+ * ```
+ */
+export function splitPathEnv(value, platform = process.platform) {
+    return (value ?? '').split(pathDelimiterFor(platform)).filter(Boolean);
+}
+/**
+ * Prepend a directory to a PATH value using the platform's delimiter.
+ *
+ * @param dir - Directory to search first.
+ * @param currentPath - Existing PATH value (may be empty or undefined).
+ * @param platform - Target platform. @defaultValue `process.platform`
+ * @returns The composed PATH value; `dir` alone when `currentPath` is empty.
+ * @example
+ * ```ts
+ * prependPathEntry('C:\\shim', 'C:\\Windows', 'win32'); // 'C:\\shim;C:\\Windows'
+ * ```
+ */
+export function prependPathEntry(dir, currentPath, platform = process.platform) {
+    return currentPath ? `${dir}${pathDelimiterFor(platform)}${currentPath}` : dir;
+}
+/**
+ * List the file names a bare command can resolve to on a platform.
+ *
+ * On win32 each `PATHEXT` extension is tried, and the bare name only when it
+ * already carries one of those extensions. Elsewhere the name is used as-is.
+ *
+ * @param name - Command name, e.g. `git`.
+ * @param opts - Platform and environment overrides.
+ * @returns Candidate file names in resolution order.
+ */
+export function executableNames(name, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    if (platform !== 'win32')
+        return [name];
+    const env = opts.env ?? process.env;
+    const exts = (env[pathExtKey(env)] || DEFAULT_PATHEXT)
+        .split(';')
+        .map((ext) => ext.trim().toLowerCase())
+        .filter(Boolean);
+    const lower = name.toLowerCase();
+    if (exts.some((ext) => lower.endsWith(ext)))
+        return [name];
+    return exts.map((ext) => `${name}${ext}`);
+}
+/**
+ * Resolve a command to the absolute path the OS would run, or `null`.
+ *
+ * Honours the platform's PATH delimiter, the win32 `Path` spelling, and
+ * `PATHEXT`. A name containing a path separator is checked directly rather
+ * than searched for.
+ *
+ * @param name - Command name or path.
+ * @param opts - Platform, environment and executability overrides.
+ * @returns Absolute path of the first match, or `null`.
+ * @example
+ * ```ts
+ * findOnPath('git'); // '/usr/bin/git' on Linux, 'C:\\Program Files\\Git\\cmd\\git.exe' on Windows
+ * ```
+ */
+export function findOnPath(name, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
+    const pathApi = platform === 'win32' ? win32 : posix;
+    const isExecutable = opts.isExecutable ?? ((p) => defaultIsExecutable(p, platform));
+    const names = executableNames(name, { platform, env });
+    const hasSeparator = platform === 'win32' ? /[\\/]/.test(name) : name.includes('/');
+    const dirs = hasSeparator ? [''] : splitPathEnv(env[pathEnvKey(env, platform)], platform);
+    for (const dir of dirs) {
+        for (const candidateName of names) {
+            const candidate = dir ? pathApi.join(dir, candidateName) : candidateName;
+            if (isExecutable(candidate))
+                return pathApi.resolve(candidate);
+        }
+    }
+    return null;
+}
+/**
+ * Resolve how to run a shell command line on a platform.
+ *
+ * `/bin/sh -c` on POSIX; on win32 `%ComSpec%` (cmd.exe) with `/d /s /c` and
+ * the line quoted verbatim — the same resolution Node applies for
+ * `shell: true`, made explicit so every caller that runs user-authored
+ * command strings (worktree hooks, release build commands) shares one
+ * resolver and tests can pin the platform.
+ *
+ * @param command - Command line to run.
+ * @param opts - Platform and environment overrides.
+ * @returns The executable, its argv and the verbatim-arguments flag.
+ * @example
+ * ```ts
+ * const sh = shellInvocation('pnpm build');
+ * execFile(sh.file, sh.args, { windowsVerbatimArguments: sh.windowsVerbatimArguments });
+ * ```
+ */
+export function shellInvocation(command, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    if (platform !== 'win32') {
+        return { file: '/bin/sh', args: ['-c', command], windowsVerbatimArguments: false };
+    }
+    const env = opts.env ?? process.env;
+    const comSpecKey = Object.keys(env).find((key) => key.toUpperCase() === 'COMSPEC');
+    const file = (comSpecKey && env[comSpecKey]) || 'cmd.exe';
+    return { file, args: ['/d', '/s', '/c', `"${command}"`], windowsVerbatimArguments: true };
+}
+/** cmd.exe metacharacters; each is caret-escaped so cmd treats it literally. */
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+/**
+ * Quote one argument for a `.cmd`/`.bat` target launched through cmd.exe.
+ *
+ * Two layers, as cmd parses the line and the batch file's program parses its
+ * argv: MSVCRT quoting (backslashes before a quote doubled, the quote
+ * escaped, the whole argument wrapped in quotes), then every cmd
+ * metacharacter caret-escaped TWICE — cmd re-parses the line when it
+ * dispatches a batch file, consuming one caret layer each pass. Because every
+ * quote is escaped, cmd never sees a quoted region in which operators such as
+ * `&` or `|` would be live. `%VAR%` expands before carets are processed, but
+ * `%NAME^%` names a variable (`NAME^`) that is never defined, and an undefined
+ * reference is left verbatim on a `cmd /c` line. This is the scheme `cross-spawn` uses against the BatBadBut class
+ * (CVE-2024-27980).
+ *
+ * @param arg - Literal argument.
+ * @returns The escaped token.
+ * @throws When `arg` holds CR or LF: cmd.exe ends the command at a line
+ *   break and no escape can carry one into a batch file.
+ * @example
+ * ```ts
+ * quoteCmdArg('a b'); // '^^^"a^^^ b^^^"'
+ * ```
+ */
+export function quoteCmdArg(arg) {
+    if (/[\r\n]/.test(arg))
+        throw new Error('E_UNSAFE_BATCH_ARG: a .cmd/.bat argument cannot contain a line break');
+    const msvcrt = `"${escapeMsvcrt(arg)}"`;
+    return msvcrt.replace(CMD_META, '^$1').replace(CMD_META, '^$1');
+}
+/**
+ * MSVCRT-escape an argument's body in ONE linear pass: a run of backslashes
+ * is doubled when it precedes a quote (the quote itself is then escaped) or
+ * the end of the argument, and kept as-is otherwise. The regex form
+ * `/(\\*)"/g` is quadratic on long backslash runs — the ReDoS class of
+ * cross-spawn's CVE-2024-21538 — and this input is untrusted prompt text.
+ */
+function escapeMsvcrt(arg) {
+    let out = '';
+    let slashes = 0;
+    for (const ch of arg) {
+        if (ch === '\\') {
+            slashes++;
+            continue;
+        }
+        if (ch === '"') {
+            out += `${'\\'.repeat(slashes * 2)}\\"`;
+        }
+        else {
+            out += `${'\\'.repeat(slashes)}${ch}`;
+        }
+        slashes = 0;
+    }
+    return out + '\\'.repeat(slashes * 2);
+}
+/**
+ * Resolve how to spawn `command args` without a shell on any platform.
+ *
+ * POSIX: returned unchanged. win32: the command is resolved to the absolute
+ * path {@link findOnPath} finds, because Node's own lookup tries only `.exe`
+ * and `.com`. A `.cmd`/`.bat` target (every npm-installed CLI) cannot be
+ * spawned directly — Node refuses since CVE-2024-27980 — so it is launched
+ * through `%ComSpec% /d /s /c` with every token escaped by {@link quoteCmdArg}.
+ *
+ * @param command - Command name or path.
+ * @param args - Literal arguments.
+ * @param opts - Platform and environment overrides.
+ * @returns The spawnable invocation.
+ * @throws When a batch-file argument contains a line break (see {@link quoteCmdArg}).
+ * @example
+ * ```ts
+ * const inv = resolveSpawnInvocation('codex', ['--full-auto', promptFile]);
+ * spawn(inv.file, inv.args, { windowsVerbatimArguments: inv.windowsVerbatimArguments });
+ * ```
+ */
+export function resolveSpawnInvocation(command, args, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    if (platform !== 'win32') {
+        return { file: command, args: [...args], windowsVerbatimArguments: false };
+    }
+    const resolved = findOnPath(command, opts) ?? command;
+    if (!/\.(cmd|bat)$/i.test(resolved)) {
+        return { file: resolved, args: [...args], windowsVerbatimArguments: false };
+    }
+    const line = [resolved.replace(CMD_META, '^$1'), ...args.map(quoteCmdArg)].join(' ');
+    const shell = shellInvocation(line, opts);
+    return { file: shell.file, args: shell.args, windowsVerbatimArguments: true };
+}
+/** Environment key for `PATHEXT`, matched case-insensitively. */
+function pathExtKey(env) {
+    return Object.keys(env).find((key) => key.toUpperCase() === 'PATHEXT') ?? 'PATHEXT';
+}
+/** A regular file that the current user may execute (existence alone on win32). */
+function defaultIsExecutable(candidate, platform) {
+    try {
+        if (!statSync(candidate).isFile())
+            return false;
+        if (platform !== 'win32')
+            accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=exec-path.js.map

package/dist/exec-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-path.js","sourceRoot":"","sources":["../src/exec-path.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -14,7 +14,11 @@
  * - Worktree primitives: {@link computeProjectHash},
  *   {@link resolveWorktreeRootForHash}, {@link resolveTaskWorktreePath},
  *   {@link getCleoWorktreesRoot}, {@link resolveWorktreeIndexPath}
+ * - {@link getCleoStateDir} — CLEO state dir (XDG state on Linux, `<cleoHome>/state` elsewhere)
+ * - {@link expandTildePath} — `~` expansion via `os.homedir()`
  * - {@link isAbsolutePath} — cross-platform abs-path check
+ * - Executable search: {@link findOnPath}, {@link prependPathEntry},
+ *   {@link splitPathEnv} (PATH delimiter + PATHEXT aware, T12605)
  * - Portable identity: {@link readPortableProjectId} (tracked `.cleo/project-id`, T12325)
  *
  * @packageDocumentation
@@ -22,9 +26,10 @@
  * @task T11008
  */
 export { isAbsolutePath } from './abs-path.js';
-export { _resetCleoPlatformPathsCache, canonicalizePath, computeCanonicalProjectId, getCanonicalTemplatesTildePath, getCleoHome, getCleoPlatformPaths, getCleoSystemInfo, getCleoTemplatesTildePath, legacyProjectId, type ResolvedProject, resolveCanonicalCleoDir, resolveLegacyCleoDir, resolveProjectByCwd, } from './cleo-paths.js';
+export { _resetCleoPlatformPathsCache, canonicalizePath, computeCanonicalProjectId, computePathFingerprintId, type DeclaredProjectIdentity, getCanonicalTemplatesTildePath, getCleoHome, getCleoPlatformPaths, getCleoStateDir, getCleoSystemInfo, getCleoTemplatesTildePath, legacyAliasClaimants, legacyProjectId, type RecordedProjectPath, type ResolvedProject, readDeclaredProjectIdentity, resolveCanonicalCleoDir, resolveLegacyCleoDir, resolveProjectByCwd, resolveStableDeviceIdPath, } from './cleo-paths.js';
+export { type ExecPathOptions, executableNames, findOnPath, pathDelimiterFor, pathEnvKey, prependPathEntry, quoteCmdArg, resolveSpawnInvocation, type ShellInvocation, type SpawnInvocation, shellInvocation, splitPathEnv, } from './exec-path.js';
 export { type EnforceOptions, enforceNodeVersion, evaluateNodeVersion, FALLBACK_MIN_NODE, getRequiredNodeVersion, type NodeManager, type NodeVersionVerdict, parseSemver, type Semver, type UpgradeHint, } from './node-version-gate.js';
-export { createPlatformPathsResolver, type PlatformPaths, type PlatformPathsResolver, type SystemInfo, } from './platform-paths.js';
+export { createPlatformPathsResolver, expandTildePath, type PlatformPaths, type PlatformPathsResolver, type SystemInfo, } from './platform-paths.js';
 export { formatPortableProjectId, isValidPortableProjectId, PORTABLE_PROJECT_ID_FILE, type PortableProjectIdRead, parsePortableProjectId, portableProjectIdPath, readPortableProjectId, } from './portable-project-id.js';
-export { computeProjectHash, getCleoWorktreesRoot, resolveTaskWorktreePath, resolveWorktreeIndexPath, resolveWorktreeRootForHash, } from './worktree-paths.js';
+export { computeProjectHash, getCleoWorktreesRoot, resolveTaskWorktreePath, resolveWorktreeIndexPath, resolveWorktreeRootForHash, resolveWorktreeTaskLockPath, } from './worktree-paths.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,yBAAyB,EACzB,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,eAAe,EACf,KAAK,eAAe,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,cAAc,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,WAAW,EACX,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,2BAA2B,EAC3B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,yBAAyB,EACzB,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EACf,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,eAAe,EACpB,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,eAAe,EACf,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,cAAc,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,WAAW,EACX,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -14,7 +14,11 @@
  * - Worktree primitives: {@link computeProjectHash},
  *   {@link resolveWorktreeRootForHash}, {@link resolveTaskWorktreePath},
  *   {@link getCleoWorktreesRoot}, {@link resolveWorktreeIndexPath}
+ * - {@link getCleoStateDir} — CLEO state dir (XDG state on Linux, `<cleoHome>/state` elsewhere)
+ * - {@link expandTildePath} — `~` expansion via `os.homedir()`
  * - {@link isAbsolutePath} — cross-platform abs-path check
+ * - Executable search: {@link findOnPath}, {@link prependPathEntry},
+ *   {@link splitPathEnv} (PATH delimiter + PATHEXT aware, T12605)
  * - Portable identity: {@link readPortableProjectId} (tracked `.cleo/project-id`, T12325)
  *
  * @packageDocumentation
@@ -22,9 +26,10 @@
  * @task T11008
  */
 export { isAbsolutePath } from './abs-path.js';
-export { _resetCleoPlatformPathsCache, canonicalizePath, computeCanonicalProjectId, getCanonicalTemplatesTildePath, getCleoHome, getCleoPlatformPaths, getCleoSystemInfo, getCleoTemplatesTildePath, legacyProjectId, resolveCanonicalCleoDir, resolveLegacyCleoDir, resolveProjectByCwd, } from './cleo-paths.js';
+export { _resetCleoPlatformPathsCache, canonicalizePath, computeCanonicalProjectId, computePathFingerprintId, getCanonicalTemplatesTildePath, getCleoHome, getCleoPlatformPaths, getCleoStateDir, getCleoSystemInfo, getCleoTemplatesTildePath, legacyAliasClaimants, legacyProjectId, readDeclaredProjectIdentity, resolveCanonicalCleoDir, resolveLegacyCleoDir, resolveProjectByCwd, resolveStableDeviceIdPath, } from './cleo-paths.js';
+export { executableNames, findOnPath, pathDelimiterFor, pathEnvKey, prependPathEntry, quoteCmdArg, resolveSpawnInvocation, shellInvocation, splitPathEnv, } from './exec-path.js';
 export { enforceNodeVersion, evaluateNodeVersion, FALLBACK_MIN_NODE, getRequiredNodeVersion, parseSemver, } from './node-version-gate.js';
-export { createPlatformPathsResolver, } from './platform-paths.js';
+export { createPlatformPathsResolver, expandTildePath, } from './platform-paths.js';
 export { formatPortableProjectId, isValidPortableProjectId, PORTABLE_PROJECT_ID_FILE, parsePortableProjectId, portableProjectIdPath, readPortableProjectId, } from './portable-project-id.js';
-export { computeProjectHash, getCleoWorktreesRoot, resolveTaskWorktreePath, resolveWorktreeIndexPath, resolveWorktreeRootForHash, } from './worktree-paths.js';
+export { computeProjectHash, getCleoWorktreesRoot, resolveTaskWorktreePath, resolveWorktreeIndexPath, resolveWorktreeRootForHash, resolveWorktreeTaskLockPath, } from './worktree-paths.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,yBAAyB,EACzB,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,eAAe,EAEf,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EAGtB,WAAW,GAGZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,2BAA2B,GAI5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EAExB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,yBAAyB,EACzB,wBAAwB,EAExB,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EAGf,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,sBAAsB,EAGtB,eAAe,EACf,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EAGtB,WAAW,GAGZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,2BAA2B,EAC3B,eAAe,GAIhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EAExB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC"}

package/dist/platform-paths.d.ts

@@ -89,6 +89,27 @@ export interface PlatformPathsResolver {
      */
     resetCache(): void;
 }
+/**
+ * Expand a leading `~` in a user-supplied path to the user's home directory.
+ *
+ * Uses `os.homedir()`, which reads `USERPROFILE` on Windows — unlike
+ * `process.env.HOME`, which is unset there and turns `~/x` into the relative
+ * path `x`. Accepts `~`, `~/x`, and on Windows `~\x`. Any other input,
+ * including `~user/x`, is returned unchanged.
+ *
+ * @param path - Path that may start with `~`.
+ * @param home - Home directory to expand into. Defaults to `os.homedir()`.
+ * @returns The expanded path, or `path` unchanged when it has no leading `~`.
+ *
+ * @example
+ * ```typescript
+ * expandTildePath('~/.pi/x.cant'); // "/home/me/.pi/x.cant" on Linux
+ * ```
+ *
+ * @public
+ * @task T12608
+ */
+export declare function expandTildePath(path: string, home?: string): string;
 /**
  * Create a platform-paths resolver bound to a specific app name and home env var.
  *

package/dist/platform-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform-paths.d.ts","sourceRoot":"","sources":["../src/platform-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,KAAK,EAAE,aAAa,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,gBAAgB,IAAI,aAAa,CAAC;IAElC;;;;;OAKG;IACH,aAAa,IAAI,UAAU,CAAC;IAE5B;;;;;OAKG;IACH,UAAU,IAAI,IAAI,CAAC;CACpB;AAqBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,qBAAqB,CAyCvB"}
+{"version":3,"file":"platform-paths.d.ts","sourceRoot":"","sources":["../src/platform-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,KAAK,EAAE,aAAa,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,gBAAgB,IAAI,aAAa,CAAC;IAElC;;;;;OAKG;IACH,aAAa,IAAI,UAAU,CAAC;IAE5B;;;;;OAKG;IACH,UAAU,IAAI,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAK9E;AAqBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,qBAAqB,CAyCvB"}

package/dist/platform-paths.js

@@ -18,6 +18,32 @@
 import { arch, homedir, hostname, platform, release } from 'node:os';
 import { isAbsolute, join } from 'node:path';
 import envPaths from 'env-paths';
+/**
+ * Expand a leading `~` in a user-supplied path to the user's home directory.
+ *
+ * Uses `os.homedir()`, which reads `USERPROFILE` on Windows — unlike
+ * `process.env.HOME`, which is unset there and turns `~/x` into the relative
+ * path `x`. Accepts `~`, `~/x`, and on Windows `~\x`. Any other input,
+ * including `~user/x`, is returned unchanged.
+ *
+ * @param path - Path that may start with `~`.
+ * @param home - Home directory to expand into. Defaults to `os.homedir()`.
+ * @returns The expanded path, or `path` unchanged when it has no leading `~`.
+ *
+ * @example
+ * ```typescript
+ * expandTildePath('~/.pi/x.cant'); // "/home/me/.pi/x.cant" on Linux
+ * ```
+ *
+ * @public
+ * @task T12608
+ */
+export function expandTildePath(path, home = homedir()) {
+    if (path === '~')
+        return home;
+    const separatorAfterTilde = path.startsWith('~/') || (process.platform === 'win32' && path.startsWith('~\\'));
+    return separatorAfterTilde ? join(home, path.slice(2)) : path;
+}
 /**
  * Normalize a home-override env var value to an absolute path.
  *
@@ -33,10 +59,9 @@ function resolveHomeOverride(value) {
     const trimmed = value.trim();
     if (trimmed.length === 0)
         return undefined;
-    if (trimmed === '~')
-        return homedir();
-    if (trimmed.startsWith('~/'))
-        return join(homedir(), trimmed.slice(2));
+    const expanded = expandTildePath(trimmed);
+    if (expanded !== trimmed)
+        return expanded;
     if (isAbsolute(trimmed))
         return trimmed;
     return join(homedir(), trimmed);

package/dist/platform-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform-paths.js","sourceRoot":"","sources":["../src/platform-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,QAAQ,MAAM,WAAW,CAAC;AAiFjC;;;;;;;;GAQG;AACH,SAAS,mBAAmB,CAAC,KAAyB;IACpD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,OAAO,EAAE,CAAC;IACtC,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,IAAI,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACxC,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAe,EACf,UAAkB,EAClB,YAAqB;IAErB,IAAI,aAAa,GAAsB,IAAI,CAAC;IAE5C,SAAS,iBAAiB;QACxB,MAAM,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAC7C,MAAM,YAAY,GAAG,mBAAmB,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;QAClE,gEAAgE;QAChE,yEAAyE;QACzE,yEAAyE;QACzE,yEAAyE;QACzE,0BAA0B;QAC1B,MAAM,cAAc,GAAG,YAAY;YACjC,CAAC,CAAC,mBAAmB,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAChD,CAAC,CAAC,SAAS,CAAC;QACd,OAAO;YACL,IAAI,EAAE,YAAY,IAAI,EAAE,CAAC,IAAI;YAC7B,MAAM,EAAE,cAAc,IAAI,EAAE,CAAC,MAAM;YACnC,KAAK,EAAE,EAAE,CAAC,KAAK;YACf,GAAG,EAAE,EAAE,CAAC,GAAG;YACX,IAAI,EAAE,EAAE,CAAC,IAAI;SACd,CAAC;IACJ,CAAC;IAED,OAAO;QACL,gBAAgB,EAAE,iBAAiB;QACnC,aAAa;YACX,IAAI,aAAa;gBAAE,OAAO,aAAa,CAAC;YACxC,aAAa,GAAG;gBACd,QAAQ,EAAE,QAAQ,EAAE;gBACpB,IAAI,EAAE,IAAI,EAAE;gBACZ,OAAO,EAAE,OAAO,EAAE;gBAClB,QAAQ,EAAE,QAAQ,EAAE;gBACpB,WAAW,EAAE,OAAO,CAAC,OAAO;gBAC5B,KAAK,EAAE,iBAAiB,EAAE;aAC3B,CAAC;YACF,OAAO,aAAa,CAAC;QACvB,CAAC;QACD,UAAU;YACR,aAAa,GAAG,IAAI,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"platform-paths.js","sourceRoot":"","sources":["../src/platform-paths.ts"],"names":[],"mappings":"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"}