bailian-cli-runtime 1.6.0 → 1.7.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Command, Command as Command$1, Config, GlobalFlags, OptionDef, OptionDef as OptionDef$1, OutputFormat, ResolvedCredential } from "bailian-cli-core";
+import { AnyCommand, ApiKeyCredential, AuthStore, Client, Command, ConfigStore, FlagDef, FlagsDef, Identity, OutputFormat, ParsedFlags, ResolutionSources, Settings, UsageError } from "bailian-cli-core";
 
 //#region src/create-cli.d.ts
 /** Per-product identity injected by each CLI entrypoint (bl / rag / …). */
@@ -7,38 +7,63 @@ interface CliOptions {
   binName: string;
   /** Product version for `--version` output, telemetry and update checks. */
   version: string;
-  /** Telemetry client name (e.g. "bailian-cli", "rag-cli"). Defaults to `binName`. */
-  clientName?: string;
+  /** User-Agent / telemetry client name (e.g. "bailian-cli", "rag-cli")。必填,无默认。 */
+  clientName: string;
   /** npm package name for self-update (e.g. "bailian-cli", "bailian-cli-rag"). */
   npmPackage: string;
+  /** Root-help suggestions shown after credentials are configured. */
+  quickStartTasks?: readonly string[];
 }
 interface Cli {
   run(argv?: string[]): Promise<void>;
 }
 /**
- * Build a CLI from an injected command set. The runtime is agnostic to *which*
- * commands exist — each product (bailian-cli, rag-cli, …) passes its own map and
- * identity. No module-level singleton: the registry is scoped to this instance.
+ * Build a CLI from an injected command set — each product (bl / rag / …) passes
+ * its own commands + identity. `run` resolves argv into a {@link Resolution},
+ * then dispatches it.
  */
-declare function createCli(commands: Record<string, Command$1>, opts: CliOptions): Cli;
+declare function createCli(commands: Record<string, AnyCommand>, opts: CliOptions): Cli;
 //#endregion
 //#region src/registry.d.ts
+/**
+ * What a command path resolves to in the registry. The single judgement that
+ * feeds `resolve()` — no scattered `isGroupPath` + throwing `resolve`.
+ *  - leaf:    landed *exactly* on an executable command (no leftover tokens).
+ *  - group:   landed on a command group with no executable of its own (incl. root []).
+ *  - unknown: the path doesn't exist, or a valid command had unexpected trailing
+ *             tokens (no positionals); `error` carries the message + hint.
+ */
+type LocateResult = {
+  kind: "leaf";
+  command: AnyCommand;
+  matched: string[];
+} | {
+  kind: "group";
+  matched: string[];
+} | {
+  kind: "unknown";
+  error: UsageError;
+};
 declare class CommandRegistry {
   private root;
   /** Binary name shown in usage/help/error strings (e.g. "bl", "rag"). */
   private readonly cliName;
-  constructor(commands: Record<string, Command$1>, cliName: string);
+  private readonly authRequirements;
+  constructor(commands: Record<string, AnyCommand>, cliName: string);
   private register;
-  getAllCommands(): Command$1[];
+  getAllCommands(): AnyCommand[];
   /** First registered command path, for the "Getting Help" example (e.g. "knowledge retrieve"). */
   private helpExample;
-  isGroupPath(commandPath: string[]): boolean;
-  resolve(commandPath: string[]): {
-    command: Command$1;
-    extra: string[];
-  };
+  /**
+   * Resolve a command path to a leaf / group / unknown outcome. Pure: walks the
+   * trie taking the longest registered prefix as the command. There are no
+   * positionals, so a valid command followed by leftover tokens is `unknown`
+   * (unexpected argument). Never throws — unknown paths return a carried UsageError.
+   */
+  locate(commandPath: string[]): LocateResult;
   private buildResourceLines;
-  private buildGlobalFlagLines;
+  private buildFlagLines;
+  private buildAuthFlagSection;
   private bold;
   private accent;
   private dim;
@@ -49,21 +74,89 @@ declare class CommandRegistry {
   private printChildren;
 }
 //#endregion
+//#region src/resolve.d.ts
+/**
+ * What an invocation resolves to — "what to do" expressed as data, not control
+ * flow. A single pure function (`resolve`) produces one of these; `createCli`'s
+ * dispatch switches on it. No scattered `argv.includes(...)` + `process.exit`.
+ *  - version: print the version and stop.
+ *  - help:    print help for `path` (root [] / a group / an explicit --help). Terminal.
+ *  - run:     execute `command`; `rest` is the flag region for parseFlags.
+ *  - usageError: the path doesn't exist (or has unexpected args); render and stop.
+ */
+type Resolution = {
+  kind: "version";
+} | {
+  kind: "help";
+  path: string[];
+} | {
+  kind: "run";
+  path: string[];
+  command: AnyCommand;
+  rest: string[];
+} | {
+  kind: "usageError";
+  error: UsageError;
+};
+/**
+ * Classify argv into a {@link Resolution}. Pure over (argv, registry): one
+ * `parsePath` scan for the command path + flag region, one `registry.locate`
+ * for the routing decision. Never throws. Trivially unit-testable.
+ */
+declare function resolve(argv: string[], registry: CommandRegistry): Resolution;
+//#endregion
+//#region src/middleware.d.ts
+/**
+ * What each middleware stage gets for the invocation in flight: the matched
+ * `command` with its `path`/`settings`/`flags`, and the `client` (populated by
+ * {@link authStage}). A stage reads these and may augment them before `next()`.
+ */
+interface RunContext {
+  /** 静态产品身份(binName/version/npmPackage/clientName)。 */
+  readonly identity: Identity;
+  /** The matched command path, e.g. ["speech","recognize"]. */
+  readonly path: string[];
+  readonly command: AnyCommand;
+  /** 只含本命令声明的 flag(分流后);全局 flag 在 sources/settings。 */
+  flags: ParsedFlags<FlagsDef>;
+  /** 解析后的有效配置面(命令的新读取面;双轨迁移期与 config 并存)。 */
+  settings: Settings;
+  /** 解析源:provider/访问器用;业务命令不可见(窄视图类型不含此字段)。 */
+  sources: ResolutionSources;
+  /** 惰性访问器,lint 限定 commands/config/** 使用。 */
+  configStore(): ConfigStore;
+  /** 惰性访问器,lint 限定 commands/auth/** 使用。 */
+  authStore(): AuthStore;
+  /** Network surface with the credential baked in — set by {@link authStage}. */
+  client: Client;
+}
+/** Koa-style onion middleware: do work, call `next()`, do work after it returns. */
+type Middleware = (ctx: RunContext, next: () => Promise<void>) => Promise<void>;
+/** Fold a middleware list into a single runnable function. */
+declare function compose(stack: Middleware[]): (ctx: RunContext) => Promise<void>;
+//#endregion
 //#region src/args.d.ts
+interface ParsePathResult {
+  /** Command path: the leading run of bare tokens, e.g. ["speech", "recognize"]. */
+  path: string[];
+  /** Everything from the first flag onward — handed to parseFlags later. */
+  rest: string[];
+  hasHelpFlag: boolean;
+  hasVersionFlag: boolean;
+}
 /**
- * Quick scan: collect positional (non-dash) args to determine the command path.
- * Skips global flags and their values so that e.g. `--output json text chat`
- * correctly produces ['text', 'chat'] instead of ['json', 'text', 'chat'].
+ * First pass — routing only. The command path is the leading run of bare
+ * (non-`-`) tokens; the first flag ends it ("command path first, then flags",
+ * oclif-style). There are no positionals, so nothing bare can legitimately
+ * follow a flag — and no flags precede the path, so this needs no schema.
  */
-declare function scanCommandPath(argv: string[], globalOptions?: OptionDef$1[]): string[];
+declare function parsePath(argv: string[]): ParsePathResult;
 /**
- * Full flag parse. Types are derived entirely from the provided OptionDef schema:
- *   - boolean: no <value> placeholder in flag string (or type: 'boolean')
- *   - number:  type: 'number'
- *   - array:   type: 'array'  (repeatable via multiple --flag occurrences)
- *   - default: string
+ * Second pass — parse the flag region into typed values, driven entirely by the
+ * keyed FlagsDef (key = camelCase flag name). Pure: returns typed flags or
+ * throws UsageError — never prints/exits. The error boundary decides rendering.
  */
-declare function parseFlags(argv: string[], options: OptionDef$1[]): GlobalFlags;
+declare function parseFlags<F extends FlagsDef>(rest: string[], defs: F): ParsedFlags<F>;
 //#endregion
 //#region src/proxy.d.ts
 declare function setupProxyFromEnv(): void;
@@ -94,13 +187,8 @@ declare const VOICE_TTS_PAGE = "https://help.aliyun.com/zh/model-studio/cosyvoic
 //#region src/output/output.d.ts
 /**
  * Emit the primary result of a command.
- *
- * Design principle:
- *   stdout  → structured data only (JSON when piped, text when TTY)
- *   stderr  → human info (progress, logs, tips) — handled elsewhere
- *
- * This ensures `bl cmd ... | jq .` always receives clean JSON,
- * while interactive users see human-readable text.
+ *   stdout → result (text by default; JSON with --output json)
+ *   stderr → human info (progress, logs, tips) — handled elsewhere
  */
 declare function emitResult(data: unknown, format: OutputFormat): void;
 /**
@@ -123,50 +211,6 @@ declare function formatTable(headers: string[], rows: string[][], {
   gap?: number;
 }): string[];
 //#endregion
-//#region src/output/prompt.d.ts
-/**
- * Build a command-usage string for the running command: `<binName> <path> <args>`.
- * Both the product binary name and the command path come from the runtime, so
- * callers never hardcode "bl" or their own path — the same code renders as
- * `bl knowledge retrieve …` under bl and `rag retrieve …` under rag.
- */
-declare function cmdUsage(config: Config, args?: string): string;
-/**
- * Prompt the user for a text value.
- * Only call this when isInteractive() is true; otherwise the function returns
- * undefined immediately so the caller can fail fast.
- */
-declare function promptText(options: {
-  message: string;
-  defaultValue?: string;
-}): Promise<string | undefined>;
-/**
- * Like promptText but confirms with y/N before proceeding.
- */
-declare function promptConfirm(options: {
-  message: string;
-  initialValue?: boolean;
-}): Promise<boolean | undefined>;
-/**
- * Prompt the user to select one value from a list.
- * Only call this when isInteractive() is true; otherwise the function returns
- * undefined immediately so the caller can fail fast.
- */
-declare function promptSelect(options: {
-  message: string;
-  choices: Array<{
-    value: string;
-    label: string;
-    hint?: string;
-  }>;
-  defaultValue?: string;
-}): Promise<string | undefined>;
-/**
- * Fail fast with a user-friendly error when a required option is missing
- * in non-interactive (agent / CI) mode.
- */
-declare function failIfMissing(flagName: string, context: string): never;
-//#endregion
 //#region src/output/progress.d.ts
 interface Spinner {
   start(): void;
@@ -182,17 +226,41 @@ declare function createProgressBar(total: number, label?: string): ProgressBar;
 //#endregion
 //#region src/output/banner.d.ts
 declare function printWelcomeBanner(cliName: string): void;
-declare function printQuickStart(): void;
+declare function printQuickStart(tasks: readonly string[]): void;
 //#endregion
 //#region src/output/status-bar.d.ts
-declare function maybeShowStatusBar(config: Config, token: string, resolved?: ResolvedCredential): void;
+declare function maybeShowStatusBar(settings: Settings, token: string, resolved: ApiKeyCredential): void;
 //#endregion
 //#region src/output/cjk-width.d.ts
 declare function displayWidth(text: string): number;
 declare function padEnd(text: string, targetWidth: number): string;
 //#endregion
+//#region src/output/color.d.ts
+type TextStyle = (text: string) => string;
+interface AnsiStyles {
+  bold: TextStyle;
+  dim: TextStyle;
+  green: TextStyle;
+  yellow: TextStyle;
+  red: TextStyle;
+  cyan: TextStyle;
+  blue: TextStyle;
+  magenta: TextStyle;
+  white: TextStyle;
+  accent: TextStyle;
+  logo: TextStyle;
+  purple: TextStyle;
+  brandBlue: TextStyle;
+  keyPink: TextStyle;
+  reset: string;
+}
+declare function isTerminal(out: NodeJS.WriteStream): boolean;
+declare function supportsColor(out: NodeJS.WriteStream): boolean;
+declare function ansi(out: NodeJS.WriteStream): AnsiStyles;
+//#endregion
 //#region src/utils/polling.d.ts
 interface PollOptions {
+  /** Absolute task URL (Client passes absolute URLs through as-is). */
   url: string;
   intervalSec: number;
   timeoutSec: number;
@@ -201,7 +269,7 @@ interface PollOptions {
   getStatus?: (data: unknown) => string;
   getErrorMessage?: (data: unknown) => string | undefined;
 }
-declare function poll<T>(config: Config, opts: PollOptions): Promise<T>;
+declare function poll<T>(client: Client, settings: Settings, opts: PollOptions): Promise<T>;
 //#endregion
 //#region src/utils/download.d.ts
 declare function downloadFile(url: string, destPath: string, opts?: {
@@ -212,19 +280,21 @@ declare function downloadFile(url: string, destPath: string, opts?: {
 declare function formatBytes(bytes: number): string;
 //#endregion
 //#region src/utils/concurrent.d.ts
-/** Resolve concurrency from flags (defaults to 1). */
-declare function getConcurrency(flags: GlobalFlags): number;
+/** Resolve concurrency from parsed command flags(`--concurrent`,defaults to 1). */
+declare function getConcurrency(flags: {
+  concurrent?: number;
+}): number;
 /**
  * Run an async task N times concurrently.
  * Returns all resolved results in order.
  * If any single task fails, the error propagates (Promise.all semantics).
  *
- * @param n       Number of concurrent executions
- * @param config  CLI config (for logging)
- * @param task    Async factory to execute
- * @param label   Optional label for status output (e.g. "requests", "tasks")
+ * @param n        Number of concurrent executions
+ * @param settings  Resolved settings (for logging)
+ * @param task     Async factory to execute
+ * @param label    Optional label for status output (e.g. "requests", "tasks")
  */
-declare function runConcurrent<T>(n: number, config: Config, task: (index: number) => Promise<T>, label?: string): Promise<T[]>;
+declare function runConcurrent<T>(n: number, settings: Settings, task: (index: number) => Promise<T>, label?: string): Promise<T[]>;
 /**
  * Parallel download helper — downloads multiple URLs concurrently.
  *
@@ -247,16 +317,6 @@ declare function downloadParallel(items: Array<{
 declare function resolveImageSize(input: string, useSync: boolean): string;
 declare function resolveImageSize(input: string | undefined, useSync: boolean): string | undefined;
 //#endregion
-//#region src/utils/ensure-key.d.ts
-declare function ensureApiKey(config: Config): Promise<void>;
-//#endregion
-//#region src/utils/command-help.d.ts
-declare function setExecutingCommandPath(path: string[]): void;
-declare function getExecutingCommandPath(): string[];
-declare function registerCommandHelpPrinter(fn: (commandPath: string[], out: NodeJS.WriteStream) => void): void;
-/** Print help for the command currently being executed (must call `setExecutingCommandPath` first). */
-declare function printCurrentCommandHelp(out?: NodeJS.WriteStream): void;
-//#endregion
 //#region src/utils/update-checker.d.ts
 declare const NPM_REGISTRY = "https://registry.npmjs.org";
 /** Default npm package; products override per-call via the `npmPackage` argument. */
@@ -547,7 +607,7 @@ interface StepContext {
   timeoutSeconds?: number;
   blRequestTimeoutSeconds?: number;
   emitEvent?: (event: Record<string, unknown>) => void | Promise<void>;
-  blConfig?: unknown;
+  blEnv?: unknown;
 }
 //#endregion
 //#region src/pipeline/dispatcher.d.ts
@@ -576,4 +636,4 @@ declare function collectPipelineHints(pipeline: PipelineDefinition, dispatcher?:
 declare function executePipeline(pipeline: PipelineDefinition, runtimeInput?: Record<string, unknown>, options?: ExecutePipelineOptions): Promise<PipelineExecutionReport>;
 declare function streamPipelineEvents(pipeline: PipelineDefinition, runtimeInput?: Record<string, unknown>, options?: Pick<ExecutePipelineOptions, "concurrency" | "basePath" | "dryRun" | "signal" | "timeoutSeconds" | "blRequestTimeoutSeconds" | "stepDispatcher">): AsyncGenerator<PipelineLifecycleEvent>;
 //#endregion
-export { API_KEY_PAGE, BAILIAN_CONSOLE, BAILIAN_CONSOLE_ROOT, BOOL_FLAG_PROMPT_EXTEND_API_DEFAULT, BOOL_FLAG_PROMPT_EXTEND_CLI_TRUE, BOOL_FLAG_PROMPT_EXTEND_IMAGE_GENERATE, BOOL_FLAG_WATERMARK, CLI_VERSION, type Cli, type CliOptions, type Command, CommandRegistry, NPM_PACKAGE, NPM_REGISTRY, type OptionDef, type PipelineDefinition, type PipelineLifecycleEvent, VOICE_TTS_PAGE, checkForUpdate, cmdUsage, collectPipelineHints, collectPipelineIssues, createCli, createProgressBar, createSpinner, displayWidth, downloadFile, downloadParallel, emitBare, emitResult, ensureApiKey, executePipeline, failIfMissing, fetchLatestVersion, formatBytes, formatTable, getConcurrency, getExecutingCommandPath, getPendingUpdateNotification, handleError, initPipelineSteps, maybeShowStatusBar, padEnd, parseFlags, poll, printCurrentCommandHelp, printQuickStart, printWelcomeBanner, promptConfirm, promptSelect, promptText, registerCommandHelpPrinter, resolveImageSize, runConcurrent, scanCommandPath, setExecutingCommandPath, setupProxyFromEnv, streamPipelineEvents };
+export { API_KEY_PAGE, type AnsiStyles, BAILIAN_CONSOLE, BAILIAN_CONSOLE_ROOT, BOOL_FLAG_PROMPT_EXTEND_API_DEFAULT, BOOL_FLAG_PROMPT_EXTEND_CLI_TRUE, BOOL_FLAG_PROMPT_EXTEND_IMAGE_GENERATE, BOOL_FLAG_WATERMARK, CLI_VERSION, type Cli, type CliOptions, type Command, CommandRegistry, type FlagDef, type LocateResult, type Middleware, NPM_PACKAGE, NPM_REGISTRY, type ParsePathResult, type PipelineDefinition, type PipelineLifecycleEvent, type Resolution, type RunContext, type TextStyle, VOICE_TTS_PAGE, ansi, checkForUpdate, collectPipelineHints, collectPipelineIssues, compose, createCli, createProgressBar, createSpinner, displayWidth, downloadFile, downloadParallel, emitBare, emitResult, executePipeline, fetchLatestVersion, formatBytes, formatTable, getConcurrency, getPendingUpdateNotification, handleError, initPipelineSteps, isTerminal, maybeShowStatusBar, padEnd, parseFlags, parsePath, poll, printQuickStart, printWelcomeBanner, resolve, resolveImageSize, runConcurrent, setupProxyFromEnv, streamPipelineEvents, supportsColor };