@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/exec.d.ts

@@ -1,10 +1,16 @@
 import type { AgentId } from './types.js';
+/** Agent execution modes controlling tool access and autonomy level. */
 export type ExecMode = 'plan' | 'edit' | 'full';
+/** Reasoning effort levels passed to agents that support them. 'auto' defers to the agent's default. */
 export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
+/** Options for spawning an agent process. Omitting `prompt` launches the CLI interactively. */
 export interface ExecOptions {
     agent: AgentId;
     version?: string;
-    prompt: string;
+    /** Omit to launch the CLI interactively -- no prompt, no --print, stdio fully inherited. */
+    prompt?: string;
+    /** Force interactive mode even when a prompt is provided. */
+    interactive?: boolean;
     mode: ExecMode;
     effort: ExecEffort;
     cwd?: string;
@@ -17,8 +23,15 @@ export interface ExecOptions {
     verbose?: boolean;
     env?: Record<string, string>;
 }
+/** Parse an array of KEY=VALUE strings into an env record. Returns undefined for empty input. */
 export declare function parseExecEnv(entries: string[]): Record<string, string> | undefined;
+/**
+ * Build the process environment for an agent invocation.
+ * Pins CLAUDE_CONFIG_DIR for Claude and CODEX_HOME for Codex; strips the
+ * other agent's env var so it doesn't leak into unrelated invocations.
+ */
 export declare function buildExecEnv(options: ExecOptions): NodeJS.ProcessEnv;
+/** Describes how to translate ExecOptions into CLI arguments for a specific agent. */
 export interface AgentCommandTemplate {
     base: string[];
     promptFlag: 'positional' | string;
@@ -32,26 +45,34 @@ export interface AgentCommandTemplate {
     printFlags?: string[];
     verboseFlag?: string;
 }
+/** CLI command templates for every supported agent. */
 export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
+/** Assemble the full CLI argument array for an agent invocation. */
 export declare function buildExecCommand(options: ExecOptions): string[];
+/** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */
 export declare function execAgent(options: ExecOptions): Promise<number>;
 /**
  * Patterns that indicate a rate/usage limit. Matching is intentionally broad
- * because providers phrase these differently — Anthropic uses "5-hour limit"
+ * because providers phrase these differently -- Anthropic uses "5-hour limit"
  * and "rate limit", OpenAI surfaces 429s, Google says "quota exceeded".
  * False positives here just trigger a fallback attempt; false negatives leave
  * the original error unhandled, which is worse.
  */
 export declare const RATE_LIMIT_PATTERNS: RegExp[];
+/** Return true if the text contains any known rate-limit or overload indicator. */
 export declare function detectRateLimit(text: string): boolean;
+/** An agent (with optional pinned version) in a fallback chain. */
 export interface FallbackEntry {
     agent: AgentId;
     /** Optional pinned version (e.g. '0.116.0'). When set, takes precedence over the active default. */
     version?: string;
 }
+/** ExecOptions extended with a fallback chain for rate-limit cascading. */
 export interface FallbackOptions extends ExecOptions {
     /** Ordered list of agents to try if the primary (options.agent) hits a rate limit. */
     fallback: FallbackEntry[];
+    /** Fallback requires a prompt -- chain handoff doesn't apply to interactive sessions. */
+    prompt: string;
 }
 /**
  * Build the prompt handed to the fallback agent when the primary was stopped
@@ -60,7 +81,7 @@ export interface FallbackOptions extends ExecOptions {
  * When the prior agent was Claude we pin its session ID via `--session-id` so
  * `prevSessionId` is always defined; for other primaries we pass undefined and
  * get a simpler retry-with-context prompt. Claude understands `/continue <id>`
- * via its shipped skill — other agents fall through to an explicit instruction
+ * via its shipped skill -- other agents fall through to an explicit instruction
  * that points at the version-agnostic `agents sessions <id>` reader.
  */
 export declare function buildFallbackPrompt(prevAgent: AgentId, prevSessionId: string | undefined, nextAgent: AgentId, originalPrompt: string): string;
@@ -69,7 +90,7 @@ export declare function buildFallbackPrompt(prevAgent: AgentId, prevSessionId: s
  *
  * The primary agent gets the original prompt. Subsequent agents get a
  * `/continue <id>`-style handoff (see buildFallbackPrompt) when we can pin a
- * session ID — which today means Claude as primary (supports `--session-id`).
+ * session ID -- which today means Claude as primary (supports `--session-id`).
  * For other primaries, fallbacks run with the original prompt plus a
  * retry-with-context note, since we can't deterministically resolve their
  * auto-generated session IDs.
@@ -79,4 +100,3 @@ export declare function buildFallbackPrompt(prevAgent: AgentId, prevSessionId: s
  * instead of an opaque "all agents failed" message.
  */
 export declare function runWithFallback(options: FallbackOptions): Promise<number>;
-//# sourceMappingURL=exec.d.ts.map

package/dist/lib/exec.js

@@ -1,10 +1,18 @@
+/**
+ * Agent execution -- command building, process spawning, and rate-limit fallback.
+ *
+ * Translates high-level ExecOptions into CLI invocations for each supported agent,
+ * manages environment isolation per agent, and chains fallback agents on rate limits.
+ */
 import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import * as path from 'path';
 import { parseTimeout } from './routines.js';
 import { getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
+/** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Parse a single KEY=VALUE string into a tuple, validating the key name. */
 function parseExecEnvEntry(entry) {
     const separatorIndex = entry.indexOf('=');
     if (separatorIndex <= 0) {
@@ -17,34 +25,58 @@ function parseExecEnvEntry(entry) {
     }
     return [key, value];
 }
+/** Parse an array of KEY=VALUE strings into an env record. Returns undefined for empty input. */
 export function parseExecEnv(entries) {
     if (entries.length === 0) {
         return undefined;
     }
     return Object.fromEntries(entries.map(parseExecEnvEntry));
 }
+/**
+ * Build the process environment for an agent invocation.
+ * Pins CLAUDE_CONFIG_DIR for Claude and CODEX_HOME for Codex; strips the
+ * other agent's env var so it doesn't leak into unrelated invocations.
+ */
 export function buildExecEnv(options) {
     const result = { ...process.env };
-    // CLAUDE_CONFIG_DIR is Claude-specific. When the caller is running inside
-    // a Claude-managed shell, process.env already carries it; spreading into a
-    // non-Claude agent's env would leak a config pointer that the target CLI
-    // doesn't understand. Strip it unless we're actually invoking Claude, and
-    // when we are, pin it to the resolved version's home.
+    // Config-dir env vars are agent-specific. When the caller is running inside
+    // an agent-managed shell, process.env already carries one; spreading into a
+    // different agent's env would leak a config pointer the target CLI doesn't
+    // understand. Strip foreign vars and pin the right one to the versioned home.
     if (options.agent === 'claude') {
         const cwd = options.cwd || process.cwd();
-        const version = options.version || resolveVersion('claude', cwd);
-        if (version && isVersionInstalled('claude', version)) {
+        const resolvedVersion = options.version ?? resolveVersion('claude', cwd);
+        // Use an explicitly pinned version unconditionally; for auto-resolved versions
+        // only inject the path when the version is actually installed on disk.
+        const version = options.version
+            ? resolvedVersion
+            : (resolvedVersion && isVersionInstalled('claude', resolvedVersion) ? resolvedVersion : null);
+        if (version) {
             result.CLAUDE_CONFIG_DIR = path.join(getVersionHomePath('claude', version), '.claude');
         }
+        delete result.CODEX_HOME;
+    }
+    else if (options.agent === 'codex') {
+        const cwd = options.cwd || process.cwd();
+        const resolvedVersion = options.version ?? resolveVersion('codex', cwd);
+        const version = options.version
+            ? resolvedVersion
+            : (resolvedVersion && isVersionInstalled('codex', resolvedVersion) ? resolvedVersion : null);
+        if (version) {
+            result.CODEX_HOME = path.join(getVersionHomePath('codex', version), '.codex');
+        }
+        delete result.CLAUDE_CONFIG_DIR;
     }
     else {
         delete result.CLAUDE_CONFIG_DIR;
+        delete result.CODEX_HOME;
     }
     return {
         ...result,
         ...options.env,
     };
 }
+/** CLI command templates for every supported agent. */
 export const AGENT_COMMANDS = {
     claude: {
         base: ['claude'],
@@ -164,9 +196,11 @@ export const AGENT_COMMANDS = {
         modelFlag: '--model',
     },
 };
+/** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
     const cmd = [...template.base];
+    const interactive = options.interactive === true || options.prompt === undefined;
     // Use versioned alias if a specific version was requested (e.g., claude@2.1.98)
     if (options.version && cmd.length > 0) {
         cmd[0] = `${cmd[0]}@${options.version}`;
@@ -189,8 +223,10 @@ export function buildExecCommand(options) {
     // Add mode flags
     const modeFlags = template.modeFlags[options.mode];
     cmd.push(...modeFlags);
-    // Add print/headless flags
-    if (options.headless && template.printFlags) {
+    // Add print/headless flags only when a prompt is provided. Without a prompt
+    // the caller wants an interactive REPL -- passing --print would immediately
+    // wait on stdin and never render the TUI.
+    if (!interactive && options.headless && template.printFlags) {
         cmd.push(...template.printFlags);
     }
     // Add session ID (Claude only)
@@ -222,12 +258,16 @@ export function buildExecCommand(options) {
             cmd.push(template.verboseFlag);
         }
     }
-    // Add prompt
-    if (template.promptFlag === 'positional') {
-        cmd.push(options.prompt);
-    }
-    else {
-        cmd.push(template.promptFlag, options.prompt);
+    // Add prompt when provided. In pure interactive mode (no prompt) we skip this
+    // so the CLI launches its TUI. When --interactive is passed alongside a prompt
+    // we still forward the prompt so the agent receives it as the first message.
+    if (options.prompt !== undefined) {
+        if (template.promptFlag === 'positional') {
+            cmd.push(options.prompt);
+        }
+        else {
+            cmd.push(template.promptFlag, options.prompt);
+        }
     }
     // Claude-specific: add dirs
     if (options.agent === 'claude' && options.addDirs) {
@@ -237,6 +277,7 @@ export function buildExecCommand(options) {
     }
     return cmd;
 }
+/** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */
 export async function execAgent(options) {
     const { exitCode } = await spawnAgent(options);
     return exitCode;
@@ -245,7 +286,7 @@ export async function execAgent(options) {
  * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
  *
  * Stderr is always piped so the caller can inspect it (e.g., for rate-limit
- * detection) while also forwarding every chunk to process.stderr in real time —
+ * detection) while also forwarding every chunk to process.stderr in real time --
  * the user sees the same output they would with stdio: 'inherit'. Stdout keeps
  * the original behavior: 'pipe' when downstream output is piped (so `agents
  * run ... | ...` composes cleanly), otherwise 'inherit' so TTY output is
@@ -256,23 +297,27 @@ async function spawnAgent(options) {
     const [executable, ...args] = cmd;
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
     const piped = !process.stdout.isTTY;
+    const interactive = options.interactive === true || options.prompt === undefined;
     return new Promise((resolve, reject) => {
+        // Interactive mode inherits all stdio so the CLI owns the TTY (TUI
+        // rendering, raw-mode keystrokes, colored output). Headless mode pipes
+        // stderr so we can scan for rate limits and feed fallback. stdout stays
+        // inherited for TTY, piped when the caller pipes us downstream.
+        const stdio = interactive
+            ? ['inherit', 'inherit', 'inherit']
+            : ['inherit', piped ? 'pipe' : 'inherit', 'pipe'];
         const child = spawn(executable, args, {
             cwd: options.cwd || process.cwd(),
-            stdio: [
-                'inherit',
-                piped ? 'pipe' : 'inherit',
-                'pipe',
-            ],
+            stdio,
             env: buildExecEnv(options),
             shell: false,
         });
-        if (piped && child.stdout) {
+        if (!interactive && piped && child.stdout) {
             child.stdout.pipe(process.stdout);
         }
         let stderrBuffer = '';
         const STDERR_BUFFER_CAP = 64 * 1024;
-        if (child.stderr) {
+        if (!interactive && child.stderr) {
             child.stderr.on('data', (chunk) => {
                 process.stderr.write(chunk);
                 if (stderrBuffer.length < STDERR_BUFFER_CAP) {
@@ -304,7 +349,7 @@ async function spawnAgent(options) {
 }
 /**
  * Patterns that indicate a rate/usage limit. Matching is intentionally broad
- * because providers phrase these differently — Anthropic uses "5-hour limit"
+ * because providers phrase these differently -- Anthropic uses "5-hour limit"
  * and "rate limit", OpenAI surfaces 429s, Google says "quota exceeded".
  * False positives here just trigger a fallback attempt; false negatives leave
  * the original error unhandled, which is worse.
@@ -319,6 +364,7 @@ export const RATE_LIMIT_PATTERNS = [
     /api[\s_-]?overloaded/i,
     /\boverloaded\b/i,
 ];
+/** Return true if the text contains any known rate-limit or overload indicator. */
 export function detectRateLimit(text) {
     return RATE_LIMIT_PATTERNS.some(pattern => pattern.test(text));
 }
@@ -329,7 +375,7 @@ export function detectRateLimit(text) {
  * When the prior agent was Claude we pin its session ID via `--session-id` so
  * `prevSessionId` is always defined; for other primaries we pass undefined and
  * get a simpler retry-with-context prompt. Claude understands `/continue <id>`
- * via its shipped skill — other agents fall through to an explicit instruction
+ * via its shipped skill -- other agents fall through to an explicit instruction
  * that points at the version-agnostic `agents sessions <id>` reader.
  */
 export function buildFallbackPrompt(prevAgent, prevSessionId, nextAgent, originalPrompt) {
@@ -350,7 +396,7 @@ export function buildFallbackPrompt(prevAgent, prevSessionId, nextAgent, origina
  *
  * The primary agent gets the original prompt. Subsequent agents get a
  * `/continue <id>`-style handoff (see buildFallbackPrompt) when we can pin a
- * session ID — which today means Claude as primary (supports `--session-id`).
+ * session ID -- which today means Claude as primary (supports `--session-id`).
  * For other primaries, fallbacks run with the original prompt plus a
  * retry-with-context note, since we can't deterministically resolve their
  * auto-generated session IDs.
@@ -411,4 +457,3 @@ export async function runWithFallback(options) {
     }
     return 1;
 }
-//# sourceMappingURL=exec.js.map

package/dist/lib/fs-walk.d.ts

@@ -0,0 +1,2 @@
+/** Walk a directory recursively for files with a given extension. */
+export declare function walkForFiles(dir: string, ext: string, limit: number): string[];

package/dist/lib/fs-walk.js

@@ -0,0 +1,40 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/** Walk a directory recursively for files with a given extension. */
+export function walkForFiles(dir, ext, limit) {
+    const results = [];
+    function walk(d, depth) {
+        if (depth > 5)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(d, entry);
+            const stat = safeStatSync(full);
+            if (!stat)
+                continue;
+            if (stat.isDirectory()) {
+                walk(full, depth + 1);
+            }
+            else if (entry.endsWith(ext)) {
+                results.push({ path: full, mtime: stat.mtimeMs });
+            }
+        }
+    }
+    walk(dir, 0);
+    results.sort((a, b) => b.mtime - a.mtime);
+    return results.slice(0, limit).map(r => r.path);
+}
+function safeStatSync(p) {
+    try {
+        return fs.statSync(p);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/fuzzy.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Fuzzy string matching for user-provided identifiers.
+ * Auto-corrects typos like "cladue" -> "claude" based on Levenshtein distance.
+ */
+/** Levenshtein edit distance between two strings. */
+export declare function levenshtein(a: string, b: string): number;
+export interface FuzzyOptions {
+    /** Absolute max edit distance allowed. */
+    maxDistance?: number;
+    /** Max ratio of distance to input length. If set, effective threshold = min(maxDistance, floor(len * maxRatio)). */
+    maxRatio?: number;
+}
+/**
+ * Fuzzy match an input string against a list of candidates.
+ * Returns the single best match within tolerance, or null if no match or ambiguous.
+ */
+export declare function fuzzyMatch<T extends string>(input: string, candidates: readonly T[], options?: FuzzyOptions): T | null;
+/**
+ * Preset configurations for different identifier types.
+ * Based on pairwise distance analysis of candidate pools.
+ */
+export declare const FUZZY_PRESETS: {
+    /** Agents: min pairwise dist=3 (opencode/openclaw), safe tolerance=2 */
+    readonly agents: {
+        readonly maxDistance: 2;
+    };
+    /** Modes: plan/edit/full all at dist=4, lenient */
+    readonly modes: {
+        readonly maxDistance: 2;
+    };
+    /** Efforts: high/xhigh at dist=1, must be strict */
+    readonly efforts: {
+        readonly maxDistance: 1;
+    };
+    /** Strategies: pinned/available/rotate all far apart */
+    readonly strategies: {
+        readonly maxDistance: 2;
+    };
+    /** Beta features: drive/factory at dist=7, lenient */
+    readonly beta: {
+        readonly maxDistance: 2;
+    };
+    /** Dynamic/user-defined: profiles, commands, hooks, etc. */
+    readonly dynamic: {
+        readonly maxDistance: 2;
+        readonly maxRatio: 0.3;
+    };
+    /** Skills: often longer names, slightly more lenient */
+    readonly skills: {
+        readonly maxDistance: 3;
+        readonly maxRatio: 0.3;
+    };
+};

package/dist/lib/fuzzy.js

@@ -0,0 +1,72 @@
+/**
+ * Fuzzy string matching for user-provided identifiers.
+ * Auto-corrects typos like "cladue" -> "claude" based on Levenshtein distance.
+ */
+/** Levenshtein edit distance between two strings. */
+export function levenshtein(a, b) {
+    const m = a.length, n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+/**
+ * Fuzzy match an input string against a list of candidates.
+ * Returns the single best match within tolerance, or null if no match or ambiguous.
+ */
+export function fuzzyMatch(input, candidates, options = {}) {
+    const { maxDistance = 2, maxRatio } = options;
+    const lower = input.toLowerCase();
+    // Reject inputs that are too short - they're too ambiguous
+    if (lower.length < 3)
+        return null;
+    // Compute effective threshold
+    const threshold = maxRatio
+        ? Math.min(maxDistance, Math.floor(lower.length * maxRatio))
+        : maxDistance;
+    // Find all candidates within threshold (excluding exact matches)
+    const matches = [];
+    for (const candidate of candidates) {
+        const dist = levenshtein(lower, candidate.toLowerCase());
+        if (dist > 0 && dist <= threshold) {
+            matches.push({ candidate, dist });
+        }
+    }
+    if (matches.length === 0)
+        return null;
+    // Sort by distance
+    matches.sort((a, b) => a.dist - b.dist);
+    // Only return if exactly one candidate at the minimum distance (no ambiguity)
+    const minDist = matches[0].dist;
+    const atMinDist = matches.filter(m => m.dist === minDist);
+    return atMinDist.length === 1 ? atMinDist[0].candidate : null;
+}
+/**
+ * Preset configurations for different identifier types.
+ * Based on pairwise distance analysis of candidate pools.
+ */
+export const FUZZY_PRESETS = {
+    /** Agents: min pairwise dist=3 (opencode/openclaw), safe tolerance=2 */
+    agents: { maxDistance: 2 },
+    /** Modes: plan/edit/full all at dist=4, lenient */
+    modes: { maxDistance: 2 },
+    /** Efforts: high/xhigh at dist=1, must be strict */
+    efforts: { maxDistance: 1 },
+    /** Strategies: pinned/available/rotate all far apart */
+    strategies: { maxDistance: 2 },
+    /** Beta features: drive/factory at dist=7, lenient */
+    beta: { maxDistance: 2 },
+    /** Dynamic/user-defined: profiles, commands, hooks, etc. */
+    dynamic: { maxDistance: 2, maxRatio: 0.3 },
+    /** Skills: often longer names, slightly more lenient */
+    skills: { maxDistance: 3, maxRatio: 0.3 },
+};

package/dist/lib/gemini-settings.d.ts

@@ -0,0 +1,4 @@
+export declare function readGeminiSettings(settingsPath: string): Record<string, unknown>;
+export declare function writeGeminiSettings(settingsPath: string, settings: Record<string, unknown>): void;
+export declare function updateGeminiSettings(settingsPath: string, mutate: (settings: Record<string, unknown>) => void): Record<string, unknown>;
+export declare function setGeminiAutoUpdateDisabled(settings: Record<string, unknown>): void;

package/dist/lib/gemini-settings.js

@@ -0,0 +1,33 @@
+import * as fs from 'fs';
+import * as path from 'path';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function readGeminiSettings(settingsPath) {
+    if (!fs.existsSync(settingsPath)) {
+        return {};
+    }
+    const raw = fs.readFileSync(settingsPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed)) {
+        throw new Error(`Gemini settings must be a JSON object: ${settingsPath}`);
+    }
+    return parsed;
+}
+export function writeGeminiSettings(settingsPath, settings) {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+export function updateGeminiSettings(settingsPath, mutate) {
+    const settings = readGeminiSettings(settingsPath);
+    mutate(settings);
+    writeGeminiSettings(settingsPath, settings);
+    return settings;
+}
+export function setGeminiAutoUpdateDisabled(settings) {
+    const general = isRecord(settings.general) ? settings.general : {};
+    settings.general = {
+        ...general,
+        enableAutoUpdate: false,
+    };
+}

package/dist/lib/git.d.ts

@@ -1,3 +1,4 @@
+/** Parsed representation of a git source string (GitHub, generic URL, or local path). */
 export interface GitSource {
     type: 'github' | 'url' | 'local';
     url: string;
@@ -21,20 +22,24 @@ export interface GitSource {
  *   ./relative/path                  -> local path
  */
 export declare function parseSource(source: string): GitSource;
+/** Clone a remote repo or pull updates if it already exists locally. */
 export declare function cloneOrPull(source: GitSource, targetDir: string): Promise<{
     isNew: boolean;
     commit: string;
 }>;
+/** Clone a repository from a source string, returning the local path and commit hash. */
 export declare function cloneRepo(source: string): Promise<{
     localPath: string;
     commit: string;
     isNew: boolean;
 }>;
+/** Clone a package from a source string into the packages directory. */
 export declare function clonePackage(source: string): Promise<{
     localPath: string;
     commit: string;
     isNew: boolean;
 }>;
+/** Get the short commit hash (8 chars) of the latest commit in a repo. */
 export declare function getRepoCommit(repoPath: string): Promise<string>;
 /**
  * Get the current GitHub username using gh CLI.
@@ -91,7 +96,7 @@ export declare function isSystemRepoOrigin(dir: string): Promise<boolean>;
 export declare function hasLocalChanges(dir: string): Promise<boolean>;
 /**
  * Pull changes in an existing repo.
- * Refuses to pull if the working tree is dirty — user must commit or discard changes first.
+ * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
  */
 export declare function pullRepo(dir: string): Promise<{
     success: boolean;
@@ -103,12 +108,18 @@ export declare function pullRepo(dir: string): Promise<{
  * Returns files categorized by their status relative to HEAD.
  */
 export interface GitSyncStatus {
+    /** Tracked and unchanged files. */
     synced: string[];
+    /** Modified but not staged files. */
     modified: string[];
+    /** Untracked files. */
     new: string[];
+    /** Staged for commit. */
     staged: string[];
+    /** Deleted files. */
     deleted: string[];
 }
+/** Compute the sync status of a git repo, optionally scoped to a subdirectory. */
 export declare function getGitSyncStatus(dir: string, subdir?: string): Promise<GitSyncStatus | null>;
 /**
  * Get list of files tracked by git in a directory.
@@ -143,4 +154,3 @@ export declare function tryAutoPull(dir: string): Promise<{
     pulled: boolean;
     error?: string;
 }>;
-//# sourceMappingURL=git.d.ts.map

package/dist/lib/git.js

@@ -1,3 +1,10 @@
+/**
+ * Git operations for the agents-cli system repo and package repositories.
+ *
+ * Handles cloning, pulling, syncing, and inspecting git repos used by
+ * the agents version management and plugin/package system. Includes
+ * source parsing for GitHub shorthand, SSH, HTTPS, and local paths.
+ */
 import simpleGit from 'simple-git';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -8,7 +15,7 @@ import { DEFAULT_SYSTEM_REPO, LEGACY_SYSTEM_REPO, systemRepoSlug } from './types
  *
  * Why: `git config core.hooksPath` is a known sandbox-escape vector and is
  * blocked by some sandboxed environments (e.g. Claude Code). Symlinks inside
- * `.git/hooks/` sidestep that restriction entirely — Git runs them the same way.
+ * `.git/hooks/` sidestep that restriction entirely -- Git runs them the same way.
  */
 function installGithooksSymlinks(repoDir) {
     const githooksDir = path.join(repoDir, '.githooks');
@@ -149,6 +156,7 @@ export function parseSource(source) {
     }
     throw new Error(`Invalid source: ${source}. Supported formats: gh:owner/repo, owner/repo, github.com/owner/repo, https://github.com/owner/repo, or local path`);
 }
+/** Clone a remote repo or pull updates if it already exists locally. */
 export async function cloneOrPull(source, targetDir) {
     const git = simpleGit();
     if (source.type === 'local') {
@@ -174,6 +182,7 @@ export async function cloneOrPull(source, targetDir) {
     const log = await repoGit.log({ maxCount: 1 });
     return { isNew: true, commit: log.latest?.hash.slice(0, 8) || 'unknown' };
 }
+/** Clone a repository from a source string, returning the local path and commit hash. */
 export async function cloneRepo(source) {
     const parsed = parseSource(source);
     if (parsed.type === 'local') {
@@ -191,6 +200,7 @@ export async function cloneRepo(source) {
         isNew: result.isNew,
     };
 }
+/** Clone a package from a source string into the packages directory. */
 export async function clonePackage(source) {
     const parsed = parseSource(source);
     if (parsed.type === 'local') {
@@ -208,6 +218,7 @@ export async function clonePackage(source) {
         isNew: result.isNew,
     };
 }
+/** Get the short commit hash (8 chars) of the latest commit in a repo. */
 export async function getRepoCommit(repoPath) {
     try {
         const git = simpleGit(repoPath);
@@ -270,10 +281,10 @@ export async function setRemoteUrl(repoPath, url) {
  */
 export async function checkGitHubRepoExists(owner, repo) {
     try {
-        const { exec } = await import('child_process');
+        const { execFile } = await import('child_process');
         const { promisify } = await import('util');
-        const execAsync = promisify(exec);
-        await execAsync(`gh repo view ${owner}/${repo} --json name`);
+        const execFileAsync = promisify(execFile);
+        await execFileAsync('gh', ['repo', 'view', `${owner}/${repo}`, '--json', 'name']);
         return true;
     }
     catch {
@@ -414,7 +425,7 @@ export async function hasLocalChanges(dir) {
 }
 /**
  * Pull changes in an existing repo.
- * Refuses to pull if the working tree is dirty — user must commit or discard changes first.
+ * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
  */
 export async function pullRepo(dir) {
     try {
@@ -440,6 +451,7 @@ export async function pullRepo(dir) {
         return { success: false, commit: '', error: err.message };
     }
 }
+/** Compute the sync status of a git repo, optionally scoped to a subdirectory. */
 export async function getGitSyncStatus(dir, subdir) {
     if (!isGitRepo(dir)) {
         return null;
@@ -632,4 +644,3 @@ export async function tryAutoPull(dir) {
         return { pulled: false, error: err.message };
     }
 }
-//# sourceMappingURL=git.js.map