@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/cli/kernel.js

@@ -1,59 +1,22 @@
-/**
- * CLI kernel — commands as data. A {@link CommandSpec} carries everything the CLI surface needs
- * (summary, args/flags, examples, narrative notes, a lazy `run`), and {@link buildProgram} renders
- * the set through commander. Commander is called ONLY from this module; the notation specs are
- * written in — docopt-style argument brackets (`<required>`/`[optional]`), the flag DSL
- * (`--auth-path <file>`, `--no-x` negation), and the derived option keys ({@link optionKey}) — is a
- * contract this module owns and validates at build time. Replacing the parser means re-implementing
- * that notation here (one module), not editing the specs.
- *
- * Follows clig.dev: per-command help in four spellings (`-h`/`--help`/`help <cmd>`/bare-with-missing-args),
- * examples in help, "did you mean" suggestions (never auto-run), and one exit-code policy — 0 success,
- * 1 runtime failure (owned by the command bodies), 2 usage error (anything the parser itself rejects).
- */
+/** CLI kernel — commands as data. */
 import { Argument, Command, Help, InvalidArgumentError, Option } from "commander";
 import { errorPrefix } from "./fail.js";
-/**
- * The option key a flag string yields on the parsed-flags record — THE naming rule specs rely on:
- * camelCase of the long name (`--auth-path` → `authPath`); a `--no-x` flag negates and stores under
- * `x` (absent ⇒ `x !== false`). Owned and enforced here so `conflicts` references and run-body reads
- * answer to one authority, not to an implicit parser behavior. Throws on a flag without a long form
- * (clig: every flag has a full-length spelling).
- */
-export function optionKey(flags) {
-    const long = flags
-        .split(/[\s,|]+/)
-        .filter((part) => part.startsWith("--"))
-        .at(-1);
-    if (!long)
-        throw new Error(`flag "${flags}" has no long form (clig: have full-length flags)`);
-    let name = long.replace(/^--/, "").replace(/[=<[].*$/, "");
-    if (name.startsWith("no-"))
-        name = name.slice(3);
-    return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-}
-// Help styling (clig: formatting with intention): section headings are BOLD, nothing in help is
-// colored — the only color in the whole CLI is the red error prefix. The style is always embedded;
-// commander strips every SGR code from the assembled help whenever the target stream has no colors
-// (non-TTY pipe, NO_COLOR, TERM=dumb).
+// Help styling (clig: formatting with intention): section headings are BOLD, nothing in help is colored — the only
+// color in the whole CLI is the red error prefix.
 const title = (s) => `\x1b[1m${s}\x1b[0m`; // bold — section headings
 /** The spec behind each registered command — how the Help renderer reaches Examples/notes. */
 const specOf = new WeakMap();
-/** Build the commander program for `specs`. The CLI entry parses with it; tests inject the IO seams. */
 export function buildProgram(specs, options = {}) {
     const exit = options.exit ?? ((code) => process.exit(code));
     const program = new Command("fastagent");
     program.description("Serve a file-defined agent — persona.md, skills/, tools/, channels/ — as a live service.");
-    // The exit-code policy: commander throws only for parse-level events — help/version displays carry
-    // exitCode 0 (→ 0), everything else it rejects is a usage error (→ 2). Runtime failures never pass
-    // through here; command bodies exit 1 themselves.
+    // The exit-code policy: commander throws only for parse-level events — help/version displays carry exitCode 0 (→
+    // 0), everything else it rejects is a usage error (→ 2).
     program.exitOverride((err) => exit(err.exitCode === 0 ? 0 : 2));
     program.configureHelp({
         ...(options.helpWidth !== undefined ? { helpWidth: options.helpWidth } : {}),
         styleTitle: title,
-        // ONE renderer for the whole page: commander's standard sections, then our Examples/notes —
-        // rendered with the SAME helper (helpWidth, styleTitle), so custom sections wrap and style
-        // exactly like native ones on any terminal.
+        // ONE renderer for the whole page: commander's standard sections, then our Examples/notes.
         formatHelp: (cmd, helper) => Help.prototype.formatHelp.call(helper, cmd, helper) + extraSections(cmd, helper),
     });
     program.configureOutput({
@@ -62,8 +25,7 @@ export function buildProgram(specs, options = {}) {
         ...(options.colors !== undefined
             ? { getOutHasColors: () => options.colors, getErrHasColors: () => options.colors }
             : {}),
-        // Every parse-level error carries the ONE unified prefix: bold-red `Error:` (plain when stderr
-        // has no colors). Command bodies get the same prefix through failStartup/failUsage.
+        // Every parse-level error carries the ONE unified prefix: bold-red `Error:` (plain when stderr has no colors).
         outputError: (str, write) => write(str.startsWith("error:") ? `${errorPrefix(options.colors)}${str.slice("error:".length)}` : str),
     });
     program.showSuggestionAfterError(); // "did you mean models?" — suggest only, never run it (clig on DWIM)
@@ -79,17 +41,6 @@ export function buildProgram(specs, options = {}) {
     return program;
 }
 function register(parent, spec) {
-    // Validate the spec's option references BEFORE handing anything to commander: every flag must
-    // have a long form (optionKey throws), and conflicts must name keys that exist on THIS command —
-    // commander matches conflicts by name at parse time, so a typo would otherwise silently never fire.
-    const keys = new Set((spec.flags ?? []).map((f) => optionKey(f.flags)));
-    for (const f of spec.flags ?? []) {
-        for (const target of f.conflicts ?? []) {
-            if (!keys.has(target)) {
-                throw new Error(`command "${spec.name}": "${f.flags}" conflicts with unknown option key "${target}"`);
-            }
-        }
-    }
     const cmd = parent.command(spec.name);
     specOf.set(cmd, spec);
     cmd.summary(spec.summary);
@@ -100,9 +51,7 @@ function register(parent, spec) {
             arg.default(a.default);
         if (a.choices)
             arg.choices(a.choices);
-        // A required argument means a non-empty VALUE, not just a present token: `invoke ""` must be a
-        // usage error, not an empty turn (the old dispatch's falsy guards, kept at the parse boundary).
-        // choices args validate membership already ("" is never a member).
+        // A required argument means a non-empty VALUE, not just a present token.
         if (a.name.startsWith("<") && !a.choices) {
             arg.argParser((value) => {
                 if (value.trim() === "")
@@ -112,12 +61,8 @@ function register(parent, spec) {
         }
         cmd.addArgument(arg);
     }
-    for (const f of spec.flags ?? []) {
-        const opt = new Option(f.flags, f.description);
-        if (f.conflicts)
-            opt.conflicts(f.conflicts);
-        cmd.addOption(opt);
-    }
+    for (const f of spec.flags ?? [])
+        cmd.addOption(new Option(f.flags, f.description));
     for (const sub of spec.subcommands ?? [])
         register(cmd, sub);
     const run = spec.run;
@@ -129,11 +74,7 @@ function register(parent, spec) {
         });
     }
 }
-/**
- * The Examples/notes sections a spec appends after commander's standard ones. Examples are
- * preformatted (column-aligned `$ cmd   # note` lines); notes are logical prose the renderer
- * reflows to `helper.helpWidth` — the exact width the sections above were wrapped to.
- */
+/** The Examples/notes sections a spec appends after commander's standard ones. */
 function extraSections(cmd, helper) {
     const spec = specOf.get(cmd);
     if (!spec || ((spec.examples?.length ?? 0) === 0 && !spec.notes))
@@ -142,8 +83,8 @@ function extraSections(cmd, helper) {
     const lines = [];
     if (spec.examples && spec.examples.length > 0) {
         lines.push(helper.styleTitle("Examples:"));
-        // Inline, column-aligned notes (`$ cmd   # note`) — a note on its own line reads as a stray
-        // fragment when neighboring examples have none.
+        // Inline, column-aligned notes (`$ cmd # note`) — a note on its own line reads as a stray fragment when
+        // neighboring examples have none.
         const w = Math.max(...spec.examples.map((e) => e.cmd.length));
         for (const e of spec.examples) {
             lines.push(e.note ? `  $ ${e.cmd.padEnd(w)}   # ${e.note}` : `  $ ${e.cmd}`);
@@ -156,11 +97,7 @@ function extraSections(cmd, helper) {
     }
     return `\n${lines.join("\n")}`;
 }
-/**
- * Reflow notes to the help width: plain lines are prose (joined and wrapped via the helper's own
- * `boxWrap`); indented lines are preformatted (aligned tables like start's precedence chains) and
- * pass through verbatim; blank lines separate paragraphs.
- */
+/** Reflow notes to the help width: plain lines are prose (joined and wrapped via the helper's own `boxWrap`). */
 function reflow(text, width, helper) {
     const out = [];
     let prose = [];

package/dist/cli/models-view.d.ts

@@ -5,16 +5,8 @@ export interface ModelPickerOption {
     label: string;
     hint: string;
 }
-/**
- * The first-run picker menu: the FULL model catalog, each spec annotated with its provider's auth
- * status — ready first (usable now, with the credential source so "which account pays" is visible at
- * the decision point), then the rest with their remedy. Order within each group preserves `specs`
- * (sorted by the caller). A broken provider (expired/corrupt credential) is annotated, not dropped —
- * fail visibly.
- */
+/** The first-run picker menu: the FULL model catalog, each spec annotated with its provider's auth status. */
 export declare function buildModelPickerOptions(specs: string[], statuses: Map<string, ProviderAuthStatus>): ModelPickerOption[];
-/** The output of `fastagent models [search]`: the spec `lines` to print to stdout (a case-insensitive
- *  substring filter; no search → all), and an stderr `error` diagnostic when a search matches nothing. */
 export declare function formatModelsCommand(specs: string[], search?: string): {
     lines: string[];
     error?: string;

package/dist/cli/models-view.js

@@ -1,24 +1,15 @@
 /**
- * CLI presenter for the model-facing commands: `fastagent models [search]` output and the first-run
- * picker's option list. Output DECISIONS live here, out of the engine config layer (config.ts owns
- * model resolution / listModels), so this process-boundary behavior is unit-testable without
- * spawning the CLI.
+ * CLI presenter for the model-facing commands: `fastagent models [search]` output and the first-run picker's option
+ * list.
  */
 import { providerOf } from "../engines/pi/config.js";
-/** The remedy hint for a non-ready provider, by what picking it actually does: an OAuth flow →
- *  "login required"; an interactive key prompt → "API key required"; no flow at all → the env var. */
+/** The remedy hint for a non-ready provider, by what picking it actually does. */
 function remedy(login) {
     if (login === "oauth")
         return "login required";
     return login === "api_key" ? "API key required" : "API key required — set the provider's env var";
 }
-/**
- * The first-run picker menu: the FULL model catalog, each spec annotated with its provider's auth
- * status — ready first (usable now, with the credential source so "which account pays" is visible at
- * the decision point), then the rest with their remedy. Order within each group preserves `specs`
- * (sorted by the caller). A broken provider (expired/corrupt credential) is annotated, not dropped —
- * fail visibly.
- */
+/** The first-run picker menu: the FULL model catalog, each spec annotated with its provider's auth status. */
 export function buildModelPickerOptions(specs, statuses) {
     const ready = [];
     const rest = [];
@@ -28,8 +19,8 @@ export function buildModelPickerOptions(specs, statuses) {
             ready.push({ value: spec, label: spec, hint: status.source ? `ready — ${status.source}` : "ready" });
         }
         else if (status?.state === "broken") {
-            // A broken stored credential OWNS the provider (env is consulted only when nothing is stored),
-            // so with no login flow the remedy is fixing the store — not the env var (which can't win here).
+            // A broken stored credential OWNS the provider (env is consulted only when nothing is stored), so with no login
+            // flow the remedy is fixing the store.
             rest.push({
                 value: spec,
                 label: spec,
@@ -42,15 +33,13 @@ export function buildModelPickerOptions(specs, statuses) {
             rest.push({ value: spec, label: spec, hint: remedy(status.login) });
         }
         else {
-            // Unreachable when `specs` and `statuses` come from the same Models (every listed provider is
-            // probed); if a caller ever mixes sources, promise nothing — neutral wording, no login claim.
+            // Unreachable when `specs` and `statuses` come from the same Models (every listed provider is probed); if a
+            // caller ever mixes sources, promise nothing.
             rest.push({ value: spec, label: spec, hint: "auth required" });
         }
     }
     return [...ready, ...rest];
 }
-/** The output of `fastagent models [search]`: the spec `lines` to print to stdout (a case-insensitive
- *  substring filter; no search → all), and an stderr `error` diagnostic when a search matches nothing. */
 export function formatModelsCommand(specs, search) {
     if (!search)
         return { lines: specs };
@@ -58,9 +47,9 @@ export function formatModelsCommand(specs, search) {
     const matches = specs.filter((spec) => spec.toLowerCase().includes(q));
     if (matches.length === 0)
         return { lines: matches, error: `no model matches "${search}"` };
-    // Rank a PROVIDER-name match (query in the part before "/") above an incidental model-id match, so
-    // `models anthropic` leads with anthropic/* rather than burying it under amazon-bedrock/anthropic.*
-    // and google-vertex/…-anthropic-… (which only match in the model id). Order within each group is kept.
+    // Rank a PROVIDER-name match (query in the part before "/") above an incidental model-id match, so `models
+    // anthropic` leads with anthropic/* rather than burying it under amazon-bedrock/anthropic.* and
+    // google-vertex/…-anthropic-… (which only match in the model id).
     const providerMatch = (spec) => providerOf(spec).toLowerCase().includes(q);
     return { lines: [...matches.filter(providerMatch), ...matches.filter((s) => !providerMatch(s))] };
 }

package/dist/cli/program.d.ts

@@ -1,11 +1,10 @@
 import { type CommandSpec, type ProgramOptions } from "./kernel.ts";
-/** Registration order = help order — the ORIGINAL usage wall's order, kept verbatim (this is a
- *  commander refactor of the same CLI, not a redesign). Exported for the kernel conformance tests. */
-export declare const specs: readonly CommandSpec[];
 /**
- * The production program assembly (specs + the top-level examples/docs). Tests build through THIS —
- * with their IO/width/color seams as overrides — so they exercise the real shape, not a lookalike.
+ * Registration order = help order — the ORIGINAL usage wall's order, kept verbatim (this is a commander refactor of
+ * the same CLI, not a redesign).
  */
+export declare const specs: readonly CommandSpec[];
+/** The production program assembly (specs + the top-level examples/docs). */
 export declare function buildCliProgram(overrides?: ProgramOptions): import("commander").Command;
-/** Parse and run one CLI invocation (`argv` = process.argv). Usage errors exit 2 via the kernel policy. */
+/** Parse and run one CLI invocation (`argv` = process.argv). */
 export declare function runCli(argv: readonly string[]): Promise<void>;