@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/placement.js

@@ -1,19 +1,3 @@
-/**
- * Placement — one model for "where does the body run?"
- *
- * The CLI grew several doors that all mean execution target:
- *   run --device / --lease / --box / --cloud
- *   routines --placement / --run-on / hostStrategy
- *   monitors --run-on (body) vs --device (owner — NOT placement)
- *   teams --device (teammate pin)
- *   cloud run --provider host
- *
- * This module is the shared vocabulary. Old flags remain; --where is a
- * thin alias on `agents run` that expands into them. Docs and help teach
- * the matrix; stores stay separate (device registry, lease boxes, cloud).
- *
- * Owner (who may fire / evaluate) is NOT placement — see monitors.
- */
 export class PlacementError extends Error {
     constructor(message) {
         super(message);
@@ -21,17 +5,6 @@ export class PlacementError extends Error {
     }
 }
 const KINDS = new Set(['local', 'device', 'fleet', 'cloud', 'lease', 'host']);
-/**
- * Parse a `--where` / placement spec string.
- *
- * Accepted forms:
- *   local
- *   device[:name] | host[:name]   (bare name → device:<name>)
- *   device:auto | auto | host:auto
- *   fleet
- *   cloud
- *   lease[:backend]
- */
 export function parseWhereSpec(raw, source = '--where') {
     const spec = raw.trim();
     if (!spec) {
@@ -50,9 +23,7 @@ export function parseWhereSpec(raw, source = '--where') {
         return { kind: 'lease', source };
     const colon = spec.indexOf(':');
     if (colon === -1) {
-        // Bare token that is not a reserved kind → device target.
         if (KINDS.has(lower)) {
-            // "device" / "host" alone means device with no pin (invalid for run).
             throw new PlacementError(`${source} ${spec}: name a target (device:<name>, device:auto) or use local|lease|cloud|fleet`);
         }
         return { kind: 'device', target: spec, source };
@@ -76,7 +47,6 @@ export function parseWhereSpec(raw, source = '--where') {
     }
     throw new PlacementError(`${source} ${spec}: unknown kind '${head}' (use local | device:<name> | auto | lease[:backend] | cloud | fleet)`);
 }
-/** First non-empty host-family flag value (host / device / on / computer). */
 export function hostFamilyTarget(flags) {
     for (const v of [flags.host, flags.device, flags.on, flags.computer]) {
         if (v)
@@ -84,10 +54,6 @@ export function hostFamilyTarget(flags) {
     }
     return undefined;
 }
-/**
- * Resolve placement from run flags. `--where` wins only when no other
- * placement flag is set; mixing is a PlacementError.
- */
 export function placementFromRunFlags(flags) {
     const where = flags.where?.trim();
     const hostT = hostFamilyTarget(flags);
@@ -128,13 +94,6 @@ export function placementFromRunFlags(flags) {
         return { kind: 'device', target: hostT, source: '--device' };
     return { kind: 'local', source: 'default' };
 }
-/**
- * Expand a resolved placement into the concrete run option fields the
- * existing dispatch paths already understand. Pure — does not mutate input.
- *
- * `fleet` is not valid for a bare `agents run` (it is a routines placement);
- * it throws so callers fail loud.
- */
 export function expandPlacementToRunFlags(placement) {
     switch (placement.kind) {
         case 'local':
@@ -143,23 +102,18 @@ export function expandPlacementToRunFlags(placement) {
             if (!placement.target) {
                 throw new PlacementError(`${placement.source}: device placement needs a target (name or auto)`);
             }
-            // Canonical host flag; --device is an alias of the same path.
             return { host: placement.target };
         case 'lease':
-            // --box reuses a warm slug; --where lease[:backend] / --lease provisions.
             if (placement.source === '--box')
                 return { box: placement.target };
             return placement.target ? { lease: placement.target } : { lease: true };
         case 'cloud':
-            // Vendor cloud placement — `--where cloud[:provider]` expands to the
-            // --cloud flag (+ --provider refinement) the run action dispatches on.
             return placement.target ? { cloud: true, provider: placement.target } : { cloud: true };
         case 'fleet':
             throw new PlacementError(`fleet placement is for routines (agents routines add … --placement fleet), not agents run. ` +
                 `Use --where device:auto for an affinity pick, or --where device:<name>.`);
     }
 }
-/** Map routines hostStrategy (+ optional host) onto the shared Placement. */
 export function placementFromHostStrategy(strategy, host) {
     switch (strategy) {
         case 'local':
@@ -172,7 +126,6 @@ export function placementFromHostStrategy(strategy, host) {
             return { kind: 'cloud', source: 'hostStrategy:cloud' };
     }
 }
-/** One-line human form for logs / help. */
 export function formatPlacement(p) {
     if (p.kind === 'local')
         return 'local';

package/dist/lib/platform/exec.d.ts

@@ -1,82 +1,9 @@
-/** PATH-search command for the platform: `where` on Windows, else `which`. */
 export declare function whichCommand(platform?: NodeJS.Platform): string;
-/**
- * Does spawning `binary` require `shell: true` on this platform?
- *
- * On Windows a `.cmd`/`.bat` wrapper (npm.cmd, bun.cmd, the agent shims) cannot
- * be exec'd directly — `spawn`/`execFile` look for a literal executable and miss
- * the PATHEXT/cmd-interpreter step, surfacing as `ENOENT`/`EINVAL`. A bare
- * command name (not an absolute path) needs the same PATHEXT resolution. Both
- * cases require the shell. Always false off Windows, where direct exec is right.
- */
 export declare function needsWindowsShell(binary: string, platform?: NodeJS.Platform): boolean;
-/**
- * Resolve an executable name to its absolute path via the OS PATH search, or
- * `null` if not found. On Windows `where` can return several lines (one per
- * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
- * shell would actually run, matching `which` semantics on POSIX. stderr is
- * dropped: a miss is an expected outcome here, and `where.exe` announces every
- * miss on stderr ("INFO: Could not find files..."), which would otherwise leak
- * into the caller's terminal once per probe.
- */
 export declare function findExecutable(name: string, platform?: NodeJS.Platform): string | null;
-/**
- * Absolute path of the POSIX shell for `sh -c <command string>` composition.
- * `/bin/sh` on POSIX; on Windows there is no /bin/sh, so resolve Git's
- * `sh.exe`/`bash.exe` from PATH (present wherever Git for Windows is — dev
- * boxes and the GitHub windows runners alike). Falls back to the bare name so
- * a missing shell surfaces as a clear spawn ENOENT on `sh` rather than a
- * misleading one on `/bin/sh`.
- */
 export declare function posixShellPath(platform?: NodeJS.Platform): string;
-/**
- * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
- * `spawn(..., { shell: true })` on win32 (the `.cmd` agent shims, `agents secrets
- * exec`, ...). cmd.exe does NO quoting of its own, so an unquoted arg with a space
- * is split into several args, and a cmd metacharacter (`&|<>()^`) would be
- * interpreted by the shell. We wrap any arg with whitespace, a quote, or a
- * metacharacter in double quotes and escape embedded quotes / trailing
- * backslashes per the CommandLineToArgvW rules, so the *child's* argv parse
- * reconstructs the original argument.
- *
- * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
- * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
- * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
- * the callers here run a command whose `%`/`!`-bearing tokens are the caller's
- * own (an agent prompt against the caller's shell, a bundle the caller owns), so
- * caller-controlled `%`/`!` is not a privilege boundary. If that ever changes
- * (composing an untrusted command line), route through a shell that disables
- * expansion rather than relying on this quoter. An empty arg becomes `""`.
- */
 export declare function quoteWin32ExecArg(arg: string): string;
-/**
- * Compose a DEP0190-safe Windows shell command line from a command and its args.
- *
- * Node's `spawn(cmd, args, { shell: true })` on win32 concatenates `cmd` and
- * every element of `args` into a single cmd.exe line WITHOUT escaping — that is
- * both Node's DEP0190 deprecation (a future hard error) and a real injection
- * surface, since user-controlled text (an agent prompt, a secrets-exec command)
- * flows through `args`. Passing the fully-composed line as the SOLE `command`
- * with an EMPTY args array sidesteps both: we quote every token with
- * `quoteWin32ExecArg` so the child's CommandLineToArgvW parse reconstructs the
- * exact original argv, and Node has no args array left to concatenate.
- *
- * Callers spawn the result as `spawn(line, [], { shell: true })`. A simple arg
- * (no whitespace/quote/metachar) is passed through untouched, so the composed
- * line is byte-identical to the old unquoted join for the common case.
- */
 export declare function composeWin32CommandLine(command: string, args: string[]): string;
-/**
- * DEP0190-safe execFile/spawn spec when the binary may need `shell: true` on Windows.
- *
- * When `needsWindowsShell(bin)` is true, compose ONE fully-quoted command line via
- * `composeWin32CommandLine` and return an EMPTY args array so Node never concatenates
- * user-controlled argv (MCP command/args, prompts, …) into the cmd.exe line unescaped.
- * Off that path the original bin+args are returned unchanged.
- *
- * Call as: `const s = execFileShellSpec(bin, args); execFile(s.command, s.args, { shell: s.shell })`.
- * Pure; optional `platform` override keeps the win32 branch unit-testable on any host.
- */
 export declare function execFileShellSpec(bin: string, args: string[], platform?: NodeJS.Platform): {
     command: string;
     args: string[];

package/dist/lib/platform/exec.js

@@ -1,37 +1,13 @@
-/**
- * Executable resolution, platform-aware.
- */
 import { execFileSync } from 'child_process';
 import * as path from 'path';
-/** PATH-search command for the platform: `where` on Windows, else `which`. */
 export function whichCommand(platform = process.platform) {
     return platform === 'win32' ? 'where' : 'which';
 }
-/**
- * Does spawning `binary` require `shell: true` on this platform?
- *
- * On Windows a `.cmd`/`.bat` wrapper (npm.cmd, bun.cmd, the agent shims) cannot
- * be exec'd directly — `spawn`/`execFile` look for a literal executable and miss
- * the PATHEXT/cmd-interpreter step, surfacing as `ENOENT`/`EINVAL`. A bare
- * command name (not an absolute path) needs the same PATHEXT resolution. Both
- * cases require the shell. Always false off Windows, where direct exec is right.
- */
 export function needsWindowsShell(binary, platform = process.platform) {
     if (platform !== 'win32')
         return false;
-    // path.win32.isAbsolute, not path.isAbsolute: the latter uses the HOST's rules,
-    // so a Windows path would read as relative when this runs on a Linux CI host.
     return !path.win32.isAbsolute(binary) || /\.(cmd|bat)$/i.test(binary);
 }
-/**
- * Resolve an executable name to its absolute path via the OS PATH search, or
- * `null` if not found. On Windows `where` can return several lines (one per
- * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
- * shell would actually run, matching `which` semantics on POSIX. stderr is
- * dropped: a miss is an expected outcome here, and `where.exe` announces every
- * miss on stderr ("INFO: Could not find files..."), which would otherwise leak
- * into the caller's terminal once per probe.
- */
 export function findExecutable(name, platform = process.platform) {
     try {
         const out = execFileSync(whichCommand(platform), [name], {
@@ -45,38 +21,11 @@ export function findExecutable(name, platform = process.platform) {
         return null;
     }
 }
-/**
- * Absolute path of the POSIX shell for `sh -c <command string>` composition.
- * `/bin/sh` on POSIX; on Windows there is no /bin/sh, so resolve Git's
- * `sh.exe`/`bash.exe` from PATH (present wherever Git for Windows is — dev
- * boxes and the GitHub windows runners alike). Falls back to the bare name so
- * a missing shell surfaces as a clear spawn ENOENT on `sh` rather than a
- * misleading one on `/bin/sh`.
- */
 export function posixShellPath(platform = process.platform) {
     if (platform !== 'win32')
         return '/bin/sh';
     return findExecutable('sh', platform) ?? findExecutable('bash', platform) ?? 'sh';
 }
-/**
- * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
- * `spawn(..., { shell: true })` on win32 (the `.cmd` agent shims, `agents secrets
- * exec`, ...). cmd.exe does NO quoting of its own, so an unquoted arg with a space
- * is split into several args, and a cmd metacharacter (`&|<>()^`) would be
- * interpreted by the shell. We wrap any arg with whitespace, a quote, or a
- * metacharacter in double quotes and escape embedded quotes / trailing
- * backslashes per the CommandLineToArgvW rules, so the *child's* argv parse
- * reconstructs the original argument.
- *
- * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
- * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
- * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
- * the callers here run a command whose `%`/`!`-bearing tokens are the caller's
- * own (an agent prompt against the caller's shell, a bundle the caller owns), so
- * caller-controlled `%`/`!` is not a privilege boundary. If that ever changes
- * (composing an untrusted command line), route through a shell that disables
- * expansion rather than relying on this quoter. An empty arg becomes `""`.
- */
 export function quoteWin32ExecArg(arg) {
     if (arg.length > 0 && !/[\s"&|<>()^]/.test(arg))
         return arg;
@@ -88,7 +37,6 @@ export function quoteWin32ExecArg(arg) {
             continue;
         }
         if (ch === '"') {
-            // Double the run of backslashes, then escape this quote.
             result += '\\'.repeat(backslashes * 2 + 1) + '"';
             backslashes = 0;
             continue;
@@ -96,40 +44,12 @@ export function quoteWin32ExecArg(arg) {
         result += '\\'.repeat(backslashes) + ch;
         backslashes = 0;
     }
-    // Trailing backslashes precede the closing quote → must be doubled.
     result += '\\'.repeat(backslashes * 2) + '"';
     return result;
 }
-/**
- * Compose a DEP0190-safe Windows shell command line from a command and its args.
- *
- * Node's `spawn(cmd, args, { shell: true })` on win32 concatenates `cmd` and
- * every element of `args` into a single cmd.exe line WITHOUT escaping — that is
- * both Node's DEP0190 deprecation (a future hard error) and a real injection
- * surface, since user-controlled text (an agent prompt, a secrets-exec command)
- * flows through `args`. Passing the fully-composed line as the SOLE `command`
- * with an EMPTY args array sidesteps both: we quote every token with
- * `quoteWin32ExecArg` so the child's CommandLineToArgvW parse reconstructs the
- * exact original argv, and Node has no args array left to concatenate.
- *
- * Callers spawn the result as `spawn(line, [], { shell: true })`. A simple arg
- * (no whitespace/quote/metachar) is passed through untouched, so the composed
- * line is byte-identical to the old unquoted join for the common case.
- */
 export function composeWin32CommandLine(command, args) {
     return [command, ...args].map(quoteWin32ExecArg).join(' ');
 }
-/**
- * DEP0190-safe execFile/spawn spec when the binary may need `shell: true` on Windows.
- *
- * When `needsWindowsShell(bin)` is true, compose ONE fully-quoted command line via
- * `composeWin32CommandLine` and return an EMPTY args array so Node never concatenates
- * user-controlled argv (MCP command/args, prompts, …) into the cmd.exe line unescaped.
- * Off that path the original bin+args are returned unchanged.
- *
- * Call as: `const s = execFileShellSpec(bin, args); execFile(s.command, s.args, { shell: s.shell })`.
- * Pure; optional `platform` override keeps the win32 branch unit-testable on any host.
- */
 export function execFileShellSpec(bin, args, platform = process.platform) {
     if (!needsWindowsShell(bin, platform)) {
         return { command: bin, args, shell: false };

package/dist/lib/platform/index.d.ts

@@ -1,17 +1,3 @@
-/**
- * Platform abstraction — the ONE place OS-divergent behavior is decided.
- *
- * Consumers express intent (`looksLikePath`, `findExecutable`, `isAlive`) instead
- * of scattering `process.platform === 'win32'` checks. Each helper that has an
- * observable branch accepts an explicit `platform` argument (defaulting to
- * `process.platform`), so all three OSes are unit-testable on any host.
- *
- * Modules grow per concern as features land:
- *   paths   — path classification + normalization
- *   exec    — executable resolution
- *   process — process liveness / control
- * (ipc + shell follow when their consumers migrate off inline branches.)
- */
 export declare const IS_WINDOWS: boolean;
 export declare const IS_MACOS: boolean;
 export declare const IS_LINUX: boolean;

package/dist/lib/platform/index.js

@@ -1,17 +1,3 @@
-/**
- * Platform abstraction — the ONE place OS-divergent behavior is decided.
- *
- * Consumers express intent (`looksLikePath`, `findExecutable`, `isAlive`) instead
- * of scattering `process.platform === 'win32'` checks. Each helper that has an
- * observable branch accepts an explicit `platform` argument (defaulting to
- * `process.platform`), so all three OSes are unit-testable on any host.
- *
- * Modules grow per concern as features land:
- *   paths   — path classification + normalization
- *   exec    — executable resolution
- *   process — process liveness / control
- * (ipc + shell follow when their consumers migrate off inline branches.)
- */
 export const IS_WINDOWS = process.platform === 'win32';
 export const IS_MACOS = process.platform === 'darwin';
 export const IS_LINUX = process.platform === 'linux';

package/dist/lib/platform/ipc.d.ts

@@ -1,11 +1 @@
-/**
- * Resolve the address a local daemon listens on / clients connect to.
- *
- * POSIX: the AF_UNIX socket file path itself.
- * Windows: a named pipe (`\\.\pipe\agents-<hash>`). Filesystem socket files
- * aren't supported there, and named pipes are NOT filesystem objects — derive a
- * stable name from a hash of the socket path so client and server agree without
- * touching disk, and never probe the result with fs.existsSync (it always reports
- * false). Both forms are accepted by net.createServer / net.createConnection.
- */
 export declare function ipcEndpoint(socketPath: string, platform?: NodeJS.Platform): string;

package/dist/lib/platform/ipc.js

@@ -1,17 +1,4 @@
-/**
- * Local-daemon IPC endpoint, platform-aware.
- */
 import * as crypto from 'crypto';
-/**
- * Resolve the address a local daemon listens on / clients connect to.
- *
- * POSIX: the AF_UNIX socket file path itself.
- * Windows: a named pipe (`\\.\pipe\agents-<hash>`). Filesystem socket files
- * aren't supported there, and named pipes are NOT filesystem objects — derive a
- * stable name from a hash of the socket path so client and server agree without
- * touching disk, and never probe the result with fs.existsSync (it always reports
- * false). Both forms are accepted by net.createServer / net.createConnection.
- */
 export function ipcEndpoint(socketPath, platform = process.platform) {
     if (platform === 'win32') {
         const hash = crypto.createHash('sha1').update(socketPath).digest('hex').slice(0, 16);

package/dist/lib/platform/links.d.ts

@@ -1,15 +1 @@
-/**
- * Create a link at `dst` pointing to `src`, portable across platforms.
- *
- * - **Directory** target: junction on Windows (no Developer Mode needed), plain
- *   symlink on POSIX.
- * - **File** target: symlink, falling back to `copyFileSync` when Windows
- *   refuses the symlink (`EPERM`/`ENOSYS` — no Developer Mode). The copy is a
- *   point-in-time snapshot, not a live link; acceptable for the immutable
- *   targets we link (binaries, config files).
- *
- * `dst` must not already exist. Callers that replace atomically should link to a
- * temp name and `rename` over the destination, exactly as before — the copy
- * fallback is non-atomic, so the temp+rename stays the caller's responsibility.
- */
 export declare function createLink(src: string, dst: string): void;

package/dist/lib/platform/links.js

@@ -1,32 +1,7 @@
-/**
- * Filesystem linking, platform-aware.
- *
- * POSIX symlinks have no portable equivalent on Windows: directory symlinks and
- * file symlinks both require either Administrator or Developer Mode, while
- * *junctions* (directories only) need no elevation. `createLink` picks the form
- * that works without privilege — junction for directories — and falls back to a
- * copy for file links when the OS refuses the symlink.
- */
 import * as fs from 'fs';
-/**
- * Create a link at `dst` pointing to `src`, portable across platforms.
- *
- * - **Directory** target: junction on Windows (no Developer Mode needed), plain
- *   symlink on POSIX.
- * - **File** target: symlink, falling back to `copyFileSync` when Windows
- *   refuses the symlink (`EPERM`/`ENOSYS` — no Developer Mode). The copy is a
- *   point-in-time snapshot, not a live link; acceptable for the immutable
- *   targets we link (binaries, config files).
- *
- * `dst` must not already exist. Callers that replace atomically should link to a
- * temp name and `rename` over the destination, exactly as before — the copy
- * fallback is non-atomic, so the temp+rename stays the caller's responsibility.
- */
 export function createLink(src, dst) {
     const win = process.platform === 'win32';
     const isDir = fs.statSync(src).isDirectory();
-    // Type is ignored on POSIX; on Windows, junction (dir) avoids the elevation a
-    // dir symlink would need, and 'file' is the explicit file-symlink form.
     const type = win ? (isDir ? 'junction' : 'file') : undefined;
     try {
         fs.symlinkSync(src, dst, type);

package/dist/lib/platform/paths.d.ts

@@ -1,55 +1,7 @@
-/**
- * Does this positional argument look like a filesystem path (vs a search term)?
- *
- * POSIX markers (`.`, `./`, `../`, `/`, `~`) are recognized on every platform —
- * identical to the long-standing behavior. Windows-only shapes (drive-letter
- * `C:\…`, UNC `\\…`, backslash-relative `.\` / `..\`) are recognized ONLY on
- * win32, so a literal `C:\repo` typed on macOS/Linux still resolves as a search
- * term — i.e. no behavior change off Windows.
- */
 export declare function looksLikePath(query: string, platform?: NodeJS.Platform): boolean;
-/**
- * Normalize a path for comparison/prefix-matching: backslashes folded to forward
- * slashes and lowercased on Windows (its filesystem is case-insensitive). On
- * POSIX the input is returned unchanged, so callers behave exactly as before.
- */
 export declare function toComparablePath(p: string, platform?: NodeJS.Platform): string;
-/**
- * Canonical home directory. Use this instead of `process.env.HOME`, which is
- * unset on Windows (where the home is `USERPROFILE`); `os.homedir()` resolves
- * correctly on all three platforms.
- */
 export declare function homeDir(): string;
-/**
- * Is this a Windows absolute path — a drive-letter root (`C:\`, `C:/`) or a UNC
- * share (`\\server\share`)? Used by local-source parsing to recognize a native
- * Windows path that the POSIX `/`, `./`, `../` prefixes miss. Caller decides
- * whether to apply it (typically gated on win32).
- */
 export declare function isWindowsAbsolutePath(p: string): boolean;
-/**
- * Fold backslashes to forward slashes. Use when a path is going into a string
- * that must read the same on every OS — a doc-comparable display path, a regex
- * subject, a forward-slash-keyed lookup. Pure string transform; on POSIX input
- * (no backslashes) it returns the value unchanged.
- */
 export declare function toPosix(p: string): string;
-/**
- * Fold forward slashes to the platform's native separator. The inverse of
- * {@link toPosix}: use when a path from a source that emits POSIX separators on
- * every OS — notably `git`, whose `rev-parse` prints `C:/Users/...` on Windows —
- * must become a native filesystem path so it compares equal to one built with
- * `path.*`. On POSIX (`path.sep === '/'`) it returns the value unchanged.
- */
 export declare function toNativePath(p: string, sep?: string): string;
-/**
- * Derive a filesystem-safe key/slug from an absolute path. Drops the Windows
- * drive colon (`:` is illegal in NTFS filenames / is the ADS separator) and
- * folds path separators and spaces to `_`. For a POSIX path this produces the
- * exact historical slug (`/a/b c` -> `_a_b_c`), so existing on-disk keys are
- * unchanged; on Windows `C:\a\b` -> `C_a_b` instead of an unusable name.
- *
- * Shell mirror (keep byte-identical in any bash shim that recomputes this key):
- *   printf '%s' "$P" | tr -d ':' | tr '\\/ ' '_'
- */
 export declare function toPortableKey(p: string): string;

package/dist/lib/platform/paths.js

@@ -1,19 +1,6 @@
-/**
- * Path classification + normalization, platform-aware.
- */
 import * as os from 'os';
 import * as path from 'path';
-/** Windows drive-letter absolute path: `C:\` or `C:/`. */
 const WIN_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
-/**
- * Does this positional argument look like a filesystem path (vs a search term)?
- *
- * POSIX markers (`.`, `./`, `../`, `/`, `~`) are recognized on every platform —
- * identical to the long-standing behavior. Windows-only shapes (drive-letter
- * `C:\…`, UNC `\\…`, backslash-relative `.\` / `..\`) are recognized ONLY on
- * win32, so a literal `C:\repo` typed on macOS/Linux still resolves as a search
- * term — i.e. no behavior change off Windows.
- */
 export function looksLikePath(query, platform = process.platform) {
     if (query === '.' ||
         query.startsWith('./') ||
@@ -30,62 +17,23 @@ export function looksLikePath(query, platform = process.platform) {
     }
     return false;
 }
-/**
- * Normalize a path for comparison/prefix-matching: backslashes folded to forward
- * slashes and lowercased on Windows (its filesystem is case-insensitive). On
- * POSIX the input is returned unchanged, so callers behave exactly as before.
- */
 export function toComparablePath(p, platform = process.platform) {
     if (platform === 'win32')
         return p.replace(/\\/g, '/').toLowerCase();
     return p;
 }
-/**
- * Canonical home directory. Use this instead of `process.env.HOME`, which is
- * unset on Windows (where the home is `USERPROFILE`); `os.homedir()` resolves
- * correctly on all three platforms.
- */
 export function homeDir() {
     return os.homedir();
 }
-/**
- * Is this a Windows absolute path — a drive-letter root (`C:\`, `C:/`) or a UNC
- * share (`\\server\share`)? Used by local-source parsing to recognize a native
- * Windows path that the POSIX `/`, `./`, `../` prefixes miss. Caller decides
- * whether to apply it (typically gated on win32).
- */
 export function isWindowsAbsolutePath(p) {
     return WIN_DRIVE_RE.test(p) || p.startsWith('\\\\');
 }
-/**
- * Fold backslashes to forward slashes. Use when a path is going into a string
- * that must read the same on every OS — a doc-comparable display path, a regex
- * subject, a forward-slash-keyed lookup. Pure string transform; on POSIX input
- * (no backslashes) it returns the value unchanged.
- */
 export function toPosix(p) {
     return p.replace(/\\/g, '/');
 }
-/**
- * Fold forward slashes to the platform's native separator. The inverse of
- * {@link toPosix}: use when a path from a source that emits POSIX separators on
- * every OS — notably `git`, whose `rev-parse` prints `C:/Users/...` on Windows —
- * must become a native filesystem path so it compares equal to one built with
- * `path.*`. On POSIX (`path.sep === '/'`) it returns the value unchanged.
- */
 export function toNativePath(p, sep = path.sep) {
     return sep === '/' ? p : p.replace(/\//g, sep);
 }
-/**
- * Derive a filesystem-safe key/slug from an absolute path. Drops the Windows
- * drive colon (`:` is illegal in NTFS filenames / is the ADS separator) and
- * folds path separators and spaces to `_`. For a POSIX path this produces the
- * exact historical slug (`/a/b c` -> `_a_b_c`), so existing on-disk keys are
- * unchanged; on Windows `C:\a\b` -> `C_a_b` instead of an unusable name.
- *
- * Shell mirror (keep byte-identical in any bash shim that recomputes this key):
- *   printf '%s' "$P" | tr -d ':' | tr '\\/ ' '_'
- */
 export function toPortableKey(p) {
     return p.replace(/^([a-zA-Z]):/, '$1').replace(/[\\/ ]/g, '_');
 }

package/dist/lib/platform/posixpath.d.ts

@@ -1,29 +1,11 @@
-/** The XDG user-bin dir, `~/.local/bin`. */
 export declare function localBinDir(home?: string): string;
 interface SymlinkResult {
-    /** A usable symlink to `target` exists at the path after this call. */
     ok: boolean;
-    /** True only when this call created the symlink (false = already correct, or left untouched). */
     created: boolean;
-    /** Why an existing entry was left untouched (set only when ok is false). */
     skippedReason?: string;
     path: string;
 }
-/**
- * Ensure `<dir>/<name>` is a symlink to `target`, NEVER clobbering a
- * pre-existing real file or a symlink that already points elsewhere — most
- * importantly a developer's `scripts/install.sh` dev build at
- * `~/.local/bin/agents`. Only an absent path, or a symlink already pointing at
- * `target`, is created/treated as ok. Idempotent.
- */
 export declare function ensureLocalBinSymlink(name: string, target: string, dir?: string): SymlinkResult;
-/**
- * Does a fresh `bash -lc` resolve `cmd` on its PATH? This is the real question
- * for the consumers we heal. Best-effort: any probe failure returns false so
- * the caller heals rather than wrongly assuming success. `command -v` is a
- * POSIX builtin.
- */
 export declare function loginShellResolves(cmd: string): boolean;
-/** Is `dir` on a fresh `bash -lc` PATH? Best-effort; a probe failure returns false. */
 export declare function dirOnLoginPath(dir: string): boolean;
 export {};