@phnx-labs/agents-cli 0.1.0 → 1.14.1

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,10 +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.prompt === undefined;
+    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}`;
@@ -191,7 +224,7 @@ export function buildExecCommand(options) {
     const modeFlags = template.modeFlags[options.mode];
     cmd.push(...modeFlags);
     // Add print/headless flags only when a prompt is provided. Without a prompt
-    // the caller wants an interactive REPL — passing --print would immediately
+    // 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);
@@ -225,8 +258,10 @@ export function buildExecCommand(options) {
             cmd.push(template.verboseFlag);
         }
     }
-    // Add prompt (skipped in interactive mode so the CLI launches its TUI)
-    if (!interactive) {
+    // 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);
         }
@@ -242,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;
@@ -250,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
@@ -261,7 +297,7 @@ async function spawnAgent(options) {
     const [executable, ...args] = cmd;
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
     const piped = !process.stdout.isTTY;
-    const interactive = options.prompt === undefined;
+    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
@@ -313,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.
@@ -328,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));
 }
@@ -338,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) {
@@ -359,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.
@@ -420,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

package/dist/lib/help.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Custom help formatting for the CLI.
+ *
+ * Overrides commander's default help layout to show Commands before Options,
+ * and applies consistent conventions (short -h flag, no implicit help subcommand).
+ */
 import type { Command } from 'commander';
+/** Description of a named command group rendered as its own section in help output. */
+export interface CommandGroup {
+    /** Section heading, e.g. 'Bundle commands'. */
+    title: string;
+    /** Subcommand names (in desired display order) that belong to this group. */
+    names: readonly string[];
+}
+/**
+ * Register named groups for a parent command so its help output splits the
+ * Commands section into multiple labeled sections. Subcommands not listed in
+ * any group fall back to a plain "Commands:" section below the groups.
+ */
+export declare function registerCommandGroups(parent: Command, groups: readonly CommandGroup[]): void;
+/** Apply standardized help formatting to the root command and all subcommands. */
 export declare function applyGlobalHelpConventions(root: Command): void;
-//# sourceMappingURL=help.d.ts.map

package/dist/lib/help.js

@@ -1,3 +1,13 @@
+const commandGroupRegistry = new WeakMap();
+/**
+ * Register named groups for a parent command so its help output splits the
+ * Commands section into multiple labeled sections. Subcommands not listed in
+ * any group fall back to a plain "Commands:" section below the groups.
+ */
+export function registerCommandGroups(parent, groups) {
+    commandGroupRegistry.set(parent, groups);
+}
+/** Format help output with Commands listed before Options for better discoverability. */
 function formatHelpCommandsFirst(cmd, helper) {
     const termWidth = helper.padWidth(cmd, helper);
     const helpWidth = helper.helpWidth || 80;
@@ -24,11 +34,39 @@ function formatHelpCommandsFirst(cmd, helper) {
     if (argumentList.length > 0) {
         output = output.concat(['Arguments:', formatList(argumentList), '']);
     }
-    const commandList = helper.visibleCommands(cmd).map((subcommand) => {
-        return formatItem(helper.subcommandTerm(subcommand), helper.subcommandDescription(subcommand));
-    });
-    if (commandList.length > 0) {
-        output = output.concat(['Commands:', formatList(commandList), '']);
+    const visibleCommands = helper.visibleCommands(cmd);
+    const subcommandTermNoAlias = (sub) => {
+        // Mirror commander's default subcommandTerm but drop the |alias suffix.
+        const argList = sub.registeredArguments ?? [];
+        const args = argList
+            .map((a) => {
+            const n = a.name() + (a.variadic ? '...' : '');
+            return a.required ? `<${n}>` : `[${n}]`;
+        })
+            .join(' ');
+        return sub.name() + (sub.options.length > 0 ? ' [options]' : '') + (args ? ` ${args}` : '');
+    };
+    const renderCommand = (sub) => formatItem(subcommandTermNoAlias(sub), helper.subcommandDescription(sub));
+    const groups = commandGroupRegistry.get(cmd);
+    if (groups && groups.length > 0) {
+        const byName = new Map(visibleCommands.map((s) => [s.name(), s]));
+        const placed = new Set();
+        for (const { title, names } of groups) {
+            const subs = names
+                .map((n) => byName.get(n))
+                .filter((s) => s !== undefined);
+            if (subs.length === 0)
+                continue;
+            subs.forEach((s) => placed.add(s.name()));
+            output = output.concat([`${title}:`, formatList(subs.map(renderCommand)), '']);
+        }
+        const remaining = visibleCommands.filter((s) => !placed.has(s.name()));
+        if (remaining.length > 0) {
+            output = output.concat(['Commands:', formatList(remaining.map(renderCommand)), '']);
+        }
+    }
+    else if (visibleCommands.length > 0) {
+        output = output.concat(['Commands:', formatList(visibleCommands.map(renderCommand)), '']);
     }
     const optionList = helper.visibleOptions(cmd).map((option) => {
         return formatItem(helper.optionTerm(option), helper.optionDescription(option));
@@ -46,6 +84,7 @@ function formatHelpCommandsFirst(cmd, helper) {
     }
     return output.join('\n');
 }
+/** Recursively apply help conventions (-h flag, no help subcommand, custom formatter). */
 function applyHelpConventionsRecursive(cmd) {
     cmd
         .helpOption('-h, --help', 'Show help')
@@ -57,7 +96,7 @@ function applyHelpConventionsRecursive(cmd) {
         applyHelpConventionsRecursive(subcommand);
     }
 }
+/** Apply standardized help formatting to the root command and all subcommands. */
 export function applyGlobalHelpConventions(root) {
     applyHelpConventionsRecursive(root);
 }
-//# sourceMappingURL=help.js.map