@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/harness-auth-capabilities.d.ts

@@ -1,17 +1,3 @@
-/**
- * Per-harness auth capability table (PHNX-3940).
- *
- * One row per `ALL_AGENT_IDS` entry. Governs `accounts add` / connect login
- * argv, identity strength, the durable worker credential (if any), and the
- * config-dir env that pins a slot. Completeness is pinned by the test against
- * `ALL_AGENT_IDS` — a new harness without a row is a type error and a failing
- * test, never a silent skip.
- *
- * Values are taken from evidence-harness-auth.md (2026-09-06) and the adapters
- * under `lib/harness/adapters/`. `LOGIN_INVOCATIONS` is the connect-era subset
- * (claude, codex) derived from this table so existing connect callers keep
- * working until T4 folds connect into `accounts add`.
- */
 import type { AgentId } from './types.js';
 type HarnessIdentityKind = 'strong' | 'email' | 'opaque';
 /**
@@ -24,24 +10,15 @@ type HarnessIdentityKind = 'strong' | 'email' | 'opaque';
 type HarnessWorkerKind = 'setup-token' | 'none' | `api-key:${string}` | `per-device${'' | `:${string}`}`;
 type HarnessWorker = HarnessWorkerKind | HarnessWorkerKind[];
 interface HarnessAuthCapability {
-    /** argv after the harness binary to start native login, or null when there is no finite login command. */
     login: string[] | null;
-    /** argv to probe login status, or null when the CLI has no status command. */
     status: string[] | null;
     identity: HarnessIdentityKind;
     worker: HarnessWorker;
-    /** Config-dir env that pins a slot, or null when isolation is HOME-swap only. */
     slotEnv: string | null;
 }
 export declare const HARNESS_AUTH: Record<AgentId, HarnessAuthCapability>;
 export declare function harnessAuth(agent: AgentId): HarnessAuthCapability;
-/** Worker kinds as a flat list (codex's dual path is two entries). */
 export declare function harnessWorkerKinds(agent: AgentId): HarnessWorkerKind[];
-/**
- * True when this harness has no portable worker credential and must log in
- * per box. `worker: 'none'` (kimi, antigravity, …) and a sole `per-device…`
- * kind both count; a dual path like Codex (API key OR device-auth) does not.
- */
 export declare function harnessWorkerIsPerDevice(agent: AgentId): boolean;
 /**
  * Native-login invocation per harness. Only harnesses with a REAL, finite login
@@ -52,11 +29,8 @@ export declare function harnessWorkerIsPerDevice(agent: AgentId): boolean;
  * Args are the `HARNESS_AUTH.login` values for the same ids.
  */
 export interface LoginInvocation {
-    /** argv passed to the installed binary to start the native login. */
     args: string[];
-    /** Flag that pre-fills the login email (appended as `[emailFlag, email]`), when supported. */
     emailFlag?: string;
-    /** One-line hint shown before the login flow takes over. */
     hint?: string;
 }
 export declare const LOGIN_INVOCATIONS: Partial<Record<AgentId, LoginInvocation>>;

package/dist/lib/harness-auth-capabilities.js

@@ -1,19 +1,9 @@
 export const HARNESS_AUTH = {
     claude: { login: ['auth', 'login'], status: ['auth', 'status'], identity: 'strong', worker: 'setup-token', slotEnv: 'CLAUDE_CONFIG_DIR' },
     codex: { login: ['login'], status: ['login', 'status'], identity: 'strong', worker: ['api-key:OPENAI_API_KEY', 'per-device:device-auth'], slotEnv: 'CODEX_HOME' },
-    // `--device-auth` pins the device-code flow: bare `grok login` defaults to
-    // `--oauth`, the loopback browser flow, which opens whatever browser profile
-    // the OS defaults to. The device-code screen prints the URL + code instead,
-    // so the human finishes it in the browser profile they choose — which is
-    // what makes it usable over an SSH shell on a worker.
     grok: { login: ['login', '--device-auth'], status: null, identity: 'strong', worker: ['api-key:XAI_API_KEY', 'per-device:device-auth'], slotEnv: 'GROK_HOME' },
-    // auth.json has no email claim; identity is the sorted provider-id join
-    // (`resolveOpenCodeAccountId`). NATIVE_ACCOUNT_CAPABILITIES.opencode.inspection
-    // is already 'opaque'.
     opencode: { login: ['auth', 'login'], status: ['auth', 'list'], identity: 'opaque', worker: 'api-key:provider', slotEnv: 'XDG_DATA_HOME' },
     cursor: { login: ['login'], status: ['status'], identity: 'strong', worker: 'api-key:CURSOR_API_KEY', slotEnv: null },
-    // No finite login argv — launch bare `kimi`, then `/login` in the TUI
-    // (`loginHint('kimi') === 'kimi'`).
     kimi: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: 'KIMI_CODE_HOME' },
     antigravity: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
     droid: { login: null, status: null, identity: 'opaque', worker: 'api-key:FACTORY_API_KEY', slotEnv: null },
@@ -22,8 +12,6 @@ export const HARNESS_AUTH = {
     amp: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
     goose: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
     hermes: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
-    // Auth lives under $XDG_CONFIG_HOME/muse (adapter pins XDG_CONFIG_HOME +
-    // XDG_DATA_HOME). slotEnv names the config pin; T5 must not HOME-swap.
     muse: { login: null, status: null, identity: 'email', worker: 'none', slotEnv: 'XDG_CONFIG_HOME' },
     warp: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
 };
@@ -33,16 +21,10 @@ export function harnessAuth(agent) {
         throw new Error(`No harness-auth capability for '${agent}'.`);
     return cap;
 }
-/** Worker kinds as a flat list (codex's dual path is two entries). */
 export function harnessWorkerKinds(agent) {
     const worker = harnessAuth(agent).worker;
     return Array.isArray(worker) ? worker : [worker];
 }
-/**
- * True when this harness has no portable worker credential and must log in
- * per box. `worker: 'none'` (kimi, antigravity, …) and a sole `per-device…`
- * kind both count; a dual path like Codex (API key OR device-auth) does not.
- */
 export function harnessWorkerIsPerDevice(agent) {
     return harnessWorkerKinds(agent).every((kind) => kind === 'none' || kind.startsWith('per-device'));
 }

package/dist/lib/harness-connection-test.d.ts

@@ -15,44 +15,17 @@
  * classifier is a pure function over the child's exit code + combined output, so
  * it is unit-tested against real stderr samples with no spawn.
  */
-/** Why a connection test failed, when it did. `undefined` reason ⇒ it passed. */
 export type ConnectionTestReason = 'auth' | 'endpoint' | 'model' | 'unknown';
-/** Outcome of a harness connection test. */
 export interface ConnectionTestResult {
     ok: boolean;
-    /** Machine-readable failure class; absent on success. */
     reason?: ConnectionTestReason;
-    /** One-line human summary (the classified cause, or a success note). */
     message?: string;
 }
-/** The prompt the smoke test sends — cheap, deterministic, one token of output. */
 export declare const CONNECTION_TEST_PROMPT = "say alive in one word";
-/**
- * Classify a finished `agents run` smoke test from its exit code and combined
- * stdout+stderr. Pure — no spawn — so the mapping (pass / auth / endpoint /
- * model / unknown) is unit-tested against real provider error strings.
- *
- * Exit 0 is a pass. Otherwise the output is matched against provider-error
- * shapes in priority order: an auth rejection (401 / invalid key) is the most
- * specific, then a model-not-served error, then a transport/DNS failure; a
- * failure that matches none is `unknown` (the run failed but not in a way we can
- * name — surfaced verbatim, never swallowed).
- */
 export declare function classifyConnectionOutput(exitCode: number | null, output: string): ConnectionTestResult;
-/** Options for {@link runHarnessConnectionTest}. */
 interface ConnectionTestOptions {
-    /** Agent-side timeout passed to `agents run --timeout`. Default `60s`. */
     timeout?: string;
-    /** Hard wall-clock cap (ms) on the child, above the agent timeout. Default 90s. */
     killAfterMs?: number;
 }
-/**
- * Run the real connection test against an already-saved harness. Spawns the CLI
- * itself (`getCliLaunch`, the one self-invocation primitive) with the same argv a
- * user would type, and classifies the result. Never throws on a failed run — a
- * failure is returned as a classified {@link ConnectionTestResult}; only a spawn
- * that never produced an exit (killed by the wall-clock cap) reads as `endpoint`
- * (the request hung).
- */
 export declare function runHarnessConnectionTest(name: string, opts?: ConnectionTestOptions): Promise<ConnectionTestResult>;
 export {};

package/dist/lib/harness-connection-test.js

@@ -1,3 +1,5 @@
+// Exercise saved profiles through real agents run, never mocks; classify auth → model → endpoint → unknown and return failed runs.
+// A wall-clock kill is an endpoint failure.
 /**
  * Pre-save connection test for a custom harness (PHNX-2221).
  *
@@ -17,19 +19,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import { getCliLaunch } from './cli-entry.js';
-/** The prompt the smoke test sends — cheap, deterministic, one token of output. */
 export const CONNECTION_TEST_PROMPT = 'say alive in one word';
-/**
- * Classify a finished `agents run` smoke test from its exit code and combined
- * stdout+stderr. Pure — no spawn — so the mapping (pass / auth / endpoint /
- * model / unknown) is unit-tested against real provider error strings.
- *
- * Exit 0 is a pass. Otherwise the output is matched against provider-error
- * shapes in priority order: an auth rejection (401 / invalid key) is the most
- * specific, then a model-not-served error, then a transport/DNS failure; a
- * failure that matches none is `unknown` (the run failed but not in a way we can
- * name — surfaced verbatim, never swallowed).
- */
 export function classifyConnectionOutput(exitCode, output) {
     if (exitCode === 0)
         return { ok: true, message: 'Connection test passed.' };
@@ -47,14 +37,6 @@ export function classifyConnectionOutput(exitCode, output) {
     }
     return { ok: false, reason: 'unknown', message: `Run failed (exit ${exitCode ?? 'null'}).${detail}` };
 }
-/**
- * Run the real connection test against an already-saved harness. Spawns the CLI
- * itself (`getCliLaunch`, the one self-invocation primitive) with the same argv a
- * user would type, and classifies the result. Never throws on a failed run — a
- * failure is returned as a classified {@link ConnectionTestResult}; only a spawn
- * that never produced an exit (killed by the wall-clock cap) reads as `endpoint`
- * (the request hung).
- */
 export async function runHarnessConnectionTest(name, opts = {}) {
     const { command, args } = getCliLaunch([
         'run',

package/dist/lib/heal.d.ts

@@ -1,43 +1,13 @@
-/**
- * Resource heal engine — close the gap between what DotAgents repos DEFINE and
- * what is actually present/valid in each installed agent home.
- *
- * Powers two callers:
- *   - `agents sync` — the one fixer, via the post-reconcile repair pass
- *     (`lib/reconcile-and-repair.ts`, run at the tail of every sync). Mode
- *     'full': fills missing, overwrites drifted content, and refreshes stale
- *     plugins even when the baseline is unknown (the user asked to sync).
- *   - the routines daemon's periodic safety check — Mode 'safe': fixes only the
- *     unambiguous gaps (missing resources, Claude-invalid plugin manifests, and
- *     provably-unmodified stale plugins). Drift and risky refreshes are reported,
- *     never clobbered.
- *
- * Built on the LIVE-home diff (`diffVersionResources`) — NOT the staleness
- * manifest. `isStale()` only compares the last-synced manifest against the
- * sources, so home-side rot (a deleted, corrupted, or Claude-rejected file in a
- * version home whose source never changed) is invisible to it and to the sync
- * fast-guard. The diff reads the actual home, so heal catches exactly that class
- * of drift — the kind that silently broke the `code` plugin on a non-default
- * Claude version.
- *
- * Heal FILLS and FIXES; it never deletes. Orphan/extra removal stays the job of
- * `agents prune cleanup`, so a heal pass can never lose work.
- */
 import type { AgentId } from './types.js';
 import { type DoctorKind, type DiffStatus } from './doctor-diff.js';
 export interface HealedResource {
     kind: DoctorKind;
     name: string;
-    /** Why it was healed: 'missing' (filled) or 'diff' (overwritten / re-pushed). */
     was: DiffStatus;
 }
 export interface SkippedResource {
     kind: DoctorKind;
     name: string;
-    /** 'drift': hand-edited content left untouched in 'safe' mode.
-     *  'unreconcilable': heal wrote it but the diff still flags it — a source/home
-     *  asymmetry the writer can't satisfy (e.g. a hook sidecar the installer omits),
-     *  surfaced honestly instead of "fixed" on every pass. */
     reason: 'drift' | 'unreconcilable';
 }
 export interface VersionHealResult {
@@ -48,7 +18,6 @@ export interface VersionHealResult {
 }
 export interface ManifestRepairResult {
     plugin: string;
-    /** Bare-name fields stripped from the source plugin.json (e.g. ["skills"]). */
     droppedFields: string[];
 }
 export interface PluginRefreshResult {
@@ -60,7 +29,6 @@ export interface PluginRefreshSkip {
     plugin: string;
     from: string;
     upstream: string;
-    /** 'modified': central diverged from baseline. 'no-baseline': pre-tracking install. */
     reason: 'modified' | 'no-baseline';
 }
 export interface HealResult {
@@ -70,25 +38,12 @@ export interface HealResult {
     skippedPlugins: PluginRefreshSkip[];
 }
 interface HealOptions {
-    /** 'full' (agents sync): fix drift + refresh unknown-baseline plugins.
-     *  'safe' (daemon): missing + invalid-manifest + unmodified refresh only. */
     mode: 'full' | 'safe';
-    /** Resolution cwd. Defaults to the home dir so no project layer is ever
-     *  resolved — heal targets the GLOBAL install, never a project. Tests override. */
     cwd?: string;
-    /** Scope to one agent; omit to heal every installed agent. */
     agent?: AgentId;
-    /** Scope to specific versions of `agent`; omit for all installed versions. */
     versions?: string[];
-    /** Compute the plan without writing anything. */
     dryRun?: boolean;
 }
-/** True when a heal pass made (or would make) any change at all. */
 export declare function healChangedAnything(r: HealResult): boolean;
-/**
- * Run a heal pass. Repairs the central plugin layer once (manifest + stale
- * refresh), then reconciles every targeted (agent, version) home against its
- * live diff. Returns a full account of what changed (or would, under dryRun).
- */
 export declare function heal(opts: HealOptions): Promise<HealResult>;
 export {};

package/dist/lib/heal.js

@@ -1,28 +1,3 @@
-/**
- * Resource heal engine — close the gap between what DotAgents repos DEFINE and
- * what is actually present/valid in each installed agent home.
- *
- * Powers two callers:
- *   - `agents sync` — the one fixer, via the post-reconcile repair pass
- *     (`lib/reconcile-and-repair.ts`, run at the tail of every sync). Mode
- *     'full': fills missing, overwrites drifted content, and refreshes stale
- *     plugins even when the baseline is unknown (the user asked to sync).
- *   - the routines daemon's periodic safety check — Mode 'safe': fixes only the
- *     unambiguous gaps (missing resources, Claude-invalid plugin manifests, and
- *     provably-unmodified stale plugins). Drift and risky refreshes are reported,
- *     never clobbered.
- *
- * Built on the LIVE-home diff (`diffVersionResources`) — NOT the staleness
- * manifest. `isStale()` only compares the last-synced manifest against the
- * sources, so home-side rot (a deleted, corrupted, or Claude-rejected file in a
- * version home whose source never changed) is invisible to it and to the sync
- * fast-guard. The diff reads the actual home, so heal catches exactly that class
- * of drift — the kind that silently broke the `code` plugin on a non-default
- * Claude version.
- *
- * Heal FILLS and FIXES; it never deletes. Orphan/extra removal stays the job of
- * `agents prune cleanup`, so a heal pass can never lose work.
- */
 import { ALL_AGENT_IDS } from './agents.js';
 import { syncResourcesToVersion, listInstalledVersions, isVersionIsolated, getVersionHomePath, getActuallySyncedResources, compareVersions, } from './installations/versions.js';
 import { diffVersionResources, } from './doctor-diff.js';
@@ -31,10 +6,6 @@ import { repairPluginManifestFile } from './plugins/plugin-marketplace.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-// ─── diff → selection mapping ────────────────────────────────────────────────
-// Which ResourceSelection key each healable diff kind writes through. `rules`
-// re-syncs via the whole-memory channel (not name-scoped); `promptcuts` is not
-// version-synced at all, so it is never healed here.
 const KIND_TO_SELECTION = {
     commands: 'commands',
     skills: 'skills',
@@ -48,18 +19,11 @@ const KIND_TO_SELECTION = {
 function totalHealed(r) {
     return r.versions.reduce((n, v) => n + v.healed.length, 0);
 }
-/** True when a heal pass made (or would make) any change at all. */
 export function healChangedAnything(r) {
     return (totalHealed(r) > 0 ||
         r.repairedManifests.length > 0 ||
         r.refreshedPlugins.length > 0);
 }
-// ─── central plugin layer (version-independent, runs once per heal) ──────────
-/**
- * Strip Claude-invalid bare-name `skills`/`commands` fields from every central
- * plugin's SOURCE plugin.json. Unambiguously safe (Claude auto-discovers both
- * from their directories) and the precondition for those plugins loading at all.
- */
 function repairCentralPluginManifests(dryRun = false) {
     const out = [];
     for (const p of discoverPlugins()) {
@@ -70,12 +34,6 @@ function repairCentralPluginManifests(dryRun = false) {
     }
     return out;
 }
-/**
- * Fast-forward central plugins whose local `.source` upstream now ships a newer
- * version. `allowModified` (full mode) re-pulls regardless of baseline; safe
- * mode refreshes only when the central copy is provably an untouched mirror of
- * its last pull (baseline version === current version) and reports the rest.
- */
 async function refreshStaleCentralPlugins(opts) {
     const refreshed = [];
     const skipped = [];
@@ -83,16 +41,15 @@ async function refreshStaleCentralPlugins(opts) {
         const info = readPluginSourceInfo(p.root);
         if (!info)
             continue;
-        const upstream = getUpstreamManifestVersion(info); // null for git sources
+        const upstream = getUpstreamManifestVersion(info);
         if (!upstream)
             continue;
         const central = p.manifest.version;
         if (compareVersions(upstream, central) <= 0)
-            continue; // central already current
+            continue;
         const baselineKnown = info.version !== undefined;
         const modified = baselineKnown && info.version !== central;
         if (!opts.allowModified) {
-            // Safe mode never overwrites a copy it can't prove is pristine.
             if (modified) {
                 skipped.push({ plugin: p.name, from: central, upstream, reason: 'modified' });
                 continue;
@@ -112,19 +69,14 @@ async function refreshStaleCentralPlugins(opts) {
     }
     return { refreshed, skipped };
 }
-// ─── per-version heal ────────────────────────────────────────────────────────
 function healVersion(agent, version, opts) {
     const result = { agent, version, healed: [], skipped: [] };
     const home = getVersionHomePath(agent, version);
     if (!fs.existsSync(home))
         return result;
-    // Always resolve against non-project layers: the global version home is never
-    // reconciled against per-cwd project resources (they layer in at launch).
     const diffOpts = { cwd: opts.cwd, excludeProject: true };
     const report = diffVersionResources(agent, version, diffOpts);
     const selection = {};
-    // Resources we attempt to write, tracked so the post-write re-diff can tell
-    // "actually fixed" from "writer couldn't satisfy the diff" (no false claims).
     const attempted = [];
     for (const rows of Object.values(report.kinds)) {
         for (const row of rows) {
@@ -133,17 +85,9 @@ function healVersion(agent, version, opts) {
             if (!isMissing && !isDrift)
                 continue;
             if (isDrift && !opts.includeDrift) {
-                // Ambiguous content drift — could be a deliberate hand-edit. Report it
-                // (the daemon notifies); never silently overwrite in safe mode.
                 result.skipped.push({ kind: row.kind, name: row.name, reason: 'drift' });
                 continue;
             }
-            // Rules (the composed instruction file) and knowledge memory (~/.agents/
-            // memory/ facts) are both repaired by a sync of this version: rules via the
-            // preset re-composition `selection.memory` drives, knowledge facts via the
-            // unconditional `syncMemoryToVersionHome` fan-out every sync runs. Setting
-            // the rules selection guarantees a sync executes, so a memory-fact drift is
-            // reconciled the same pass (PHNX-3504).
             if (row.kind === 'rules' || row.kind === 'memory') {
                 selection.memory = 'all';
                 attempted.push({ kind: row.kind, name: row.name, was: row.status });
@@ -156,11 +100,6 @@ function healVersion(agent, version, opts) {
             attempted.push({ kind: row.kind, name: row.name, was: row.status });
         }
     }
-    // Plugins are presence-only in the diff, so a stale/invalid-but-present plugin
-    // mirror never shows as 'diff' — yet its central source just changed (repaired
-    // or refreshed). Re-push those into this version's marketplace mirror, but only
-    // where the plugin is already installed (don't force-install into a version
-    // that opted out). These are verified by the central change, not the re-diff.
     const pluginHealed = [];
     if (opts.changedPlugins.size > 0) {
         const synced = new Set(getActuallySyncedResources(agent, version, diffOpts).plugins);
@@ -176,17 +115,11 @@ function healVersion(agent, version, opts) {
     if (!hasWork)
         return result;
     if (opts.dryRun) {
-        // No write — report the intended fixes as-is.
         result.healed.push(...attempted, ...pluginHealed);
         return result;
     }
-    // Explicit selection => bypasses the manifest fast-guard and writes exactly
-    // these names (additive; no orphan-sweep), so nothing outside the gap moves.
     syncResourcesToVersion(agent, version, selection, { cwd: opts.cwd });
     result.healed.push(...pluginHealed);
-    // Verify: re-diff and only claim resources that actually flipped to ok. Ones
-    // still flagged are reported as 'unreconcilable' so repeated runs converge in
-    // messaging instead of "fixing" the same item forever.
     const post = diffVersionResources(agent, version, diffOpts);
     const stillBad = new Set();
     for (const rows of Object.values(post.kinds)) {
@@ -205,12 +138,6 @@ function healVersion(agent, version, opts) {
     }
     return result;
 }
-// ─── public entrypoint ────────────────────────────────────────────────────────
-/**
- * Run a heal pass. Repairs the central plugin layer once (manifest + stale
- * refresh), then reconciles every targeted (agent, version) home against its
- * live diff. Returns a full account of what changed (or would, under dryRun).
- */
 export async function heal(opts) {
     const cwd = opts.cwd ?? os.homedir();
     const full = opts.mode === 'full';
@@ -223,13 +150,6 @@ export async function heal(opts) {
         ...repairedManifests.map((r) => r.plugin),
         ...refreshed.map((r) => r.plugin),
     ]);
-    // Isolated copies are excluded from every SWEEP. `agents add --isolated`
-    // promises "no settings carry-over, no resource sync", and this engine runs
-    // unattended from the daemon (~30s after start, then every ~6h) — a sweep that
-    // walked into an isolated home would quietly refill it with shared commands,
-    // skills, hooks, MCP config and permissions. Explicitly NAMED versions
-    // (`agents sync <agent>@<version>`) are honoured as-is: naming the
-    // version is the operator's consent.
     const sweep = (a) => listInstalledVersions(a).filter((v) => !isVersionIsolated(a, v));
     const targets = opts.agent
         ? [{ agent: opts.agent, versions: opts.versions ?? sweep(opts.agent) }]

package/dist/lib/help.d.ts

@@ -1,48 +1,16 @@
-/**
- * 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. */
 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;
-/**
- * Front-door command groups shown on `agents --help`. Derived from measured
- * reach: tier 1 = setup/run/sessions/view, tier 2 = teams/browser/secrets/
- * devices/accounts/add. The remaining groups stay discoverable through the
- * pointer rendered below these groups.
- */
 export declare const FRONT_DOOR_COMMAND_GROUPS: readonly CommandGroup[];
-/** Mark the root program so its help only renders front-door groups + a pointer. */
 export declare function setCompactRootHelp(program: Command): void;
-/** Examples + Notes blocks attached to a command via setHelpSections. */
 interface HelpSections {
     examples?: string;
     notes?: string;
 }
-/**
- * Attach an Examples block (rendered between the description and Arguments)
- * and/or a Notes block (rendered at the very end, after Options) to a command.
- *
- * Bodies are normalized: the shared leading indent is stripped, then every line
- * is re-indented by two spaces. Callers can pass natural multiline template
- * literals without babysitting whitespace.
- */
 export declare function setHelpSections(cmd: Command, sections: HelpSections): void;
-/** Read the workflow-first sections attached to a command for generated references. */
 export declare function getHelpSections(cmd: Command): Readonly<HelpSections>;
-/** Apply standardized help formatting to the root command and all subcommands. */
 export declare function applyGlobalHelpConventions(root: Command): void;
 export {};

package/dist/lib/help.js

@@ -1,18 +1,7 @@
 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);
 }
-/**
- * Front-door command groups shown on `agents --help`. Derived from measured
- * reach: tier 1 = setup/run/sessions/view, tier 2 = teams/browser/secrets/
- * devices/accounts/add. The remaining groups stay discoverable through the
- * pointer rendered below these groups.
- */
 export const FRONT_DOOR_COMMAND_GROUPS = [
     {
         title: 'Quick start',
@@ -24,27 +13,16 @@ export const FRONT_DOOR_COMMAND_GROUPS = [
     },
 ];
 const compactRootHelp = new WeakMap();
-/** Mark the root program so its help only renders front-door groups + a pointer. */
 export function setCompactRootHelp(program) {
     compactRootHelp.set(program, true);
 }
 const helpSectionRegistry = new WeakMap();
-/**
- * Attach an Examples block (rendered between the description and Arguments)
- * and/or a Notes block (rendered at the very end, after Options) to a command.
- *
- * Bodies are normalized: the shared leading indent is stripped, then every line
- * is re-indented by two spaces. Callers can pass natural multiline template
- * literals without babysitting whitespace.
- */
 export function setHelpSections(cmd, sections) {
     helpSectionRegistry.set(cmd, sections);
 }
-/** Read the workflow-first sections attached to a command for generated references. */
 export function getHelpSections(cmd) {
     return helpSectionRegistry.get(cmd) ?? {};
 }
-/** Strip a uniform leading indent from a block and trim surrounding blank lines. */
 function dedent(body) {
     const lines = body.replace(/^\n+/, '').replace(/\s+$/, '').split('\n');
     let minIndent = Infinity;
@@ -59,24 +37,17 @@ function dedent(body) {
         return lines.join('\n');
     return lines.map((line) => (line.length >= minIndent ? line.slice(minIndent) : line)).join('\n');
 }
-/** Re-indent a dedented block by two spaces so it sits under a section heading. */
 function indentBlock(body) {
     return body
         .split('\n')
         .map((line) => (line.length === 0 ? '' : `  ${line}`))
         .join('\n');
 }
-/** 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;
     const itemIndentWidth = 2;
     const itemSeparatorWidth = 2;
-    // commander v15 dropped `Help.wrap(str, width, indent)` in favor of
-    // `boxWrap(str, width)` plus a built-in `formatItem(term, termWidth,
-    // description, helper)` that handles the term-pad + continuation-indent
-    // math we used to do by hand. Delegate to it so callers get the same
-    // continuation-line alignment under the description column.
     function formatItem(term, description) {
         if (description) {
             return helper.formatItem(term, termWidth, description, helper);
@@ -84,13 +55,8 @@ function formatHelpCommandsFirst(cmd, helper) {
         return ' '.repeat(itemIndentWidth) + term;
     }
     function formatList(textArray) {
-        // formatItem already prefixes each item with its 2-space indent, so just
-        // join. Single-line items (no description) are indented above.
         return textArray.join('\n');
     }
-    // Drop arguments flagged as hidden (deprecation / compat slots) from both
-    // the Usage line and the Arguments section. Commander v12's Argument lacks
-    // hideHelp(), so we read a custom `hidden` field that callers set directly.
     const isHidden = (a) => a.hidden === true;
     const registeredArgs = cmd.registeredArguments ?? [];
     const parentNames = [];
@@ -104,8 +70,6 @@ function formatHelpCommandsFirst(cmd, helper) {
         return a.required ? `<${n}>` : `[${n}]`;
     })
         .join(' ');
-    // commander always exposes -h/--help, so every command effectively has options.
-    // Order matches commander's default: name [options] <args> [command].
     const argsToken = visibleArgTokens ? ` ${visibleArgTokens}` : '';
     const commandToken = cmd.commands.length > 0 ? ' [command]' : '';
     const usageLine = `${parentPrefix}${cmd.name()} [options]${argsToken}${commandToken}`;
@@ -129,9 +93,6 @@ function formatHelpCommandsFirst(cmd, helper) {
     }
     const visibleCommands = helper.visibleCommands(cmd);
     const subcommandTermNoAlias = (sub) => {
-        // Mirror commander's default subcommandTerm but drop the |alias suffix and
-        // skip arguments marked as hidden (Argument#hideHelp()), so deprecation /
-        // compatibility slots don't pollute the usage line.
         const argList = sub.registeredArguments ?? [];
         const args = argList
             .filter((a) => !a.hidden)
@@ -190,7 +151,6 @@ 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')
@@ -202,7 +162,6 @@ function applyHelpConventionsRecursive(cmd) {
         applyHelpConventionsRecursive(subcommand);
     }
 }
-/** Apply standardized help formatting to the root command and all subcommands. */
 export function applyGlobalHelpConventions(root) {
     applyHelpConventionsRecursive(root);
 }