@crouter/api 0.3.387 → 0.3.389

package/dist/core/help.d.ts

@@ -0,0 +1,309 @@
+import type { DeclaredOutputField } from '../api/command-manifest/result.js';
+export type Field = DeclaredOutputField;
+/** Positional argument. A repeatable positional consumes every remaining positional token. */
+export interface PositionalParam {
+    kind: 'positional';
+    name: string;
+    /** Display hint only; always parsed as string. `file` names a
+     *  capability-provider file argument, sent locally as the string typed. */
+    type?: 'string' | 'path' | 'file';
+    required: boolean;
+    constraint: string;
+    /** When true, every positional token is collected into an array in argv order. */
+    repeatable?: boolean;
+    /** Local-file materialization contract, valid only on a `path` param. The
+     *  CLI-side value is a path to a local file; the invoker reads that file and
+     *  sends its CONTENT as the mapped value — 'text' as UTF-8, 'base64' as the
+     *  base64 of its raw bytes. The path string itself never crosses the wire. */
+    encoding?: FileEncoding;
+    /** Ambient default: when the caller omits this param and the named client
+     *  environment variable is set and non-empty, that value is used and counts as
+     *  supplied — see FlagParam.defaultFromEnv. */
+    defaultFromEnv?: string;
+}
+/** How a local file named by a `path` param is encoded into the request. */
+export type FileEncoding = 'text' | 'base64';
+/** Additional guidance for an uncommon flag whose safe selection, value
+ *  grammar, dynamic choices, or effects do not fit in its compact leaf-schema
+ *  row. The compact row routes the agent to `crtr <leaf> --<flag> -h`; that
+ *  focused continuation renders only this parameter contract. */
+export interface FocusedFlagHelp {
+    /** Concrete cases that justify overriding the default, plus when to omit. */
+    whenToUse: string;
+    /** Complete accepted-value grammar and default/inheritance behavior. */
+    value: string;
+    /** Flag-specific persistent or lifecycle effects and coupled interactions. */
+    effects?: string[];
+    /** Bounded dynamic choices owned by this flag, rendered only in focused help. */
+    dynamicState?: () => string | null;
+}
+/** Long-form flag (`--name`). */
+export interface FlagParam {
+    kind: 'flag';
+    name: string;
+    /** 'bool' flags take no value — presence = true. 'file' names a
+     *  capability-provider file argument, sent locally as the string typed. */
+    type: 'string' | 'int' | 'bool' | 'path' | 'enum' | 'file';
+    /** Required only when type is 'enum'. */
+    choices?: string[];
+    required: boolean;
+    /** Compact discovery contract. When focusedHelp is present, state what the
+     *  flag changes and the condition that could justify it; the renderer adds
+     *  the exact focused-help road sign automatically. */
+    constraint: string;
+    /** Opt into focused `--flag -h` guidance. Use only when omission is normal
+     *  and the complete safe contract cannot fit in one compact row. */
+    focusedHelp?: FocusedFlagHelp;
+    default?: string | number | boolean;
+    /** When true, the flag may appear multiple times; values accumulate into an
+     *  array (parseArgv collects them; body-placed REST params ship as a JSON array). */
+    repeatable?: boolean;
+    /** When true, the flag is PARSED normally but never rendered in `-h`. For a
+     *  deliberately-undiscoverable confirmation gate the agent must be TOLD about
+     *  in the command's own output (not by reading the schema), never advertised. */
+    hidden?: boolean;
+    /** The value is a secret. Parse errors for the leaf then withhold every stray
+     *  argv value, since a mistyped invocation is how a secret lands in one. */
+    sensitive?: boolean;
+    /** Local-file materialization contract, valid only on a `path` flag — see
+     *  PositionalParam.encoding. */
+    encoding?: FileEncoding;
+    /** Ambient default sourced from the CALLER's environment: when the param is
+     *  not supplied on the command line and this environment variable is set and
+     *  non-empty, its value fills the param and counts as explicitly supplied (it
+     *  therefore satisfies `required` and ships like a typed value — unlike a
+     *  static `default`, which is a display/parse convenience only). This is how a
+     *  leaf picks up ambient identity a caller should not have to retype, e.g.
+     *  CRTR_NODE_ID, which every broker exports into its node's environment. */
+    defaultFromEnv?: string;
+}
+/** Raw stdin content blob (piped text, not parsed as JSON). */
+export interface StdinParam {
+    kind: 'stdin';
+    name: string;
+    required: boolean;
+    constraint: string;
+    /** Whether one positional token may supply stdin instead of a pipe. Defaults
+     * to true for existing stdin-body leaves; false requires actual stdin. */
+    allowPositional?: boolean;
+    /** Optional leaf-specific recovery when a positional stdin body collides with
+     * piped stdin. Return undefined to keep the generic collision error. */
+    positionalStdinConflict?: (input: Readonly<Record<string, unknown>>) => {
+        message: string;
+        field?: string;
+        next: string;
+    } | undefined;
+}
+/** --context-file PATH: reads and JSON-parses the file at PATH. */
+export interface ContextFileParam {
+    kind: 'context-file';
+    name: string;
+    required: boolean;
+    constraint: string;
+    /** Optional description of the expected JSON shape. */
+    shape?: string;
+}
+export type InputParam = PositionalParam | FlagParam | StdinParam | ContextFileParam;
+/** How prominently a subcommand surfaces in ancestor (parent / root) -h
+ *  listings. Set per child in the parent branch's `help.children`. Default
+ *  'normal'.
+ *   - hidden    — never listed anywhere, not even in this branch's own -h.
+ *                 You must already know it exists to invoke it.
+ *   - normal    — listed in this branch's own -h only (the default).
+ *   - common    — ALSO promoted into the parent's -h, as a bare qualified name.
+ *   - important — ALSO promoted into the parent's -h, name + shortform desc. */
+export type SubTier = 'hidden' | 'normal' | 'common' | 'important';
+/** A child's assembled parent-level listing entry — computed by defineBranch
+ *  from each child def's own self-description (`description`/`whenToUse`/`tier`).
+ *  renderBranch consumes this; it is never authored by hand and there is no
+ *  parent-side copy of a child's description (principle 16: each node owns its
+ *  representation one level up). */
+export interface ListingChild {
+    name: string;
+    /** Plugin that contributed this child to an extensible core branch. */
+    plugin?: string;
+    /** Short description for this child's <subcommand> row. */
+    description: string;
+    /** Selection rubric — plainly states when to reach for this command. Expansive
+     *  with a variety of examples for judgment-heavy commands; concise for
+     *  genuinely single-purpose ones. Rendered verbatim (no prefix). */
+    whenToUse: string;
+    /** Visibility tier in ancestor listings (see SubTier). 'hidden' children are
+     *  dropped from every listing. */
+    tier: SubTier;
+    /** Whether the child is a leaf or a branch. */
+    kind?: 'leaf' | 'branch';
+    /** How many non-hidden subcommands this child itself owns — drives the
+     *  `subcommands="N"` attribute when a branch child is listed without
+     *  expansion. Absent for leaves and childless branches. */
+    subCount?: number;
+}
+/** A subtree's self-description at the parent (root) level. Each subtree owns
+ *  the content that represents it one level up: its vocabulary line, its
+ *  selection rubric, and any bounded block it contributes to the parent's -h.
+ *  defineRoot assembles the root help from these — root never hardcodes a
+ *  subtree's representation. See cli-design "Each node owns its parent-level
+ *  representation". */
+export interface RootEntry {
+    /** One-line vocabulary desc — what this subtree is. Rendered first in the
+     *  subtree's <name> block at root. */
+    concept: string;
+    /** Operations summary (verb list). Carried for completeness; the root block
+     *  leads with concept + rubric, so this is available but not rendered. */
+    desc: string;
+    /** The selection rubric — `use when X` in the subtree's <name> block. */
+    useWhen: string;
+    /** Optional bounded block this subtree contributes to its <name> block at
+     *  root. Returns a complete self-named state element (build it with
+     *  stateBlock), e.g. `<kinds count="7">…</kinds>`. Aggregate, never an
+     *  unbounded enumeration on a cold path. Soft-fails to omission on
+     *  null/throw. */
+    dynamicState?: () => string | null;
+}
+export interface RootHelp {
+    tagline: string;
+    /** One entry per listed subtree. Each renders as its own <name> XML block at
+     *  root, carrying the subtree's concept, selection rubric, and any nested
+     *  runtime-state block. Assembled from subtrees' RootEntry by defineRoot;
+     *  root hardcodes none of it. */
+    commands: RootCommand[];
+    globals: {
+        name: string;
+        desc: string;
+    }[];
+}
+/** A single command block at root. Most fields come from the subtree's
+ *  RootEntry; `subcommands`/`otherSubcommandCount` are computed by defineRoot
+ *  from the subtree's children tiers. */
+export interface RootCommand {
+    name: string;
+    concept: string;
+    desc: string;
+    useWhen: string;
+    dynamicState?: () => string | null;
+    /** Promoted subcommands surfaced inline under this command at root, in
+     *  declaration order. `desc` is present only for 'important' tier; 'common'
+     *  tier carries the bare qualified path. */
+    subcommands?: {
+        path: string;
+        desc?: string;
+    }[];
+    /** How many of this command's other (non-hidden, not-promoted) direct
+     *  subcommands are not shown. Drives the "[+N (other) subcommands]" line. */
+    otherSubcommandCount?: number;
+}
+export interface BranchHelp {
+    name: string;
+    /** The command's own description — rendered as the `description` attribute of
+     *  its <command> card at its own -h. */
+    summary: string;
+    /** Local model prose orienting the agent to what the subtree contains and how
+     *  the children differ as a group — never a per-child restatement (each
+     *  child's purpose lives in its own listing row). */
+    model?: string;
+    /** Bounded runtime aggregate as a complete self-named state element (build
+     *  it with stateBlock), e.g. `<kinds count="7">…</kinds>`. Renderer
+     *  soft-fails to omission if this returns null or throws. */
+    dynamicState?: () => string | null;
+    /** Parent-level listing assembled by defineBranch from the actual child defs.
+     *  renderBranch reads this; never author it by hand. */
+    listing?: ListingChild[];
+    /** A rejected repository fragment is visible only on its owning extensible branch. */
+    extensionIssue?: {
+        fragment: string;
+        message: string;
+    };
+}
+/** Viewer-only hint about how a leaf's result should preview in the attach
+ *  viewer's chat — never part of `-h` output and never reaches agent-facing
+ *  stdout (see renderLeafArgv / renderResult, neither of which read this
+ *  field). Declared on the leaf that owns the behavior, so the attach viewer
+ *  asks the command tree instead of guessing from rendered text. */
+export interface PreviewMeta {
+    /** When true, the attach viewer collapses this leaf's successful result to
+     *  a one-line status by default (still expandable with Ctrl+O). For a
+     *  command whose result is a machine-readable dump meant for a browser/tool
+     *  rather than a human glance (e.g. a snapshot leaf). Never suppresses a
+     *  failed run — errors always show in full. */
+    suppressOutput?: boolean;
+}
+export interface LeafHelp {
+    name: string;
+    summary: string;
+    /** Optional long-form workflow prose rendered immediately after the summary
+     *  line, before the schema. Carried only by leaves whose correct use needs
+     *  prose beyond the schema (e.g. node new's prompt-writing guidance,
+     *  node yield's pre-yield checklist). */
+    guide?: string;
+    params?: InputParam[];
+    /** Note appended when there is no input (replaces the Input block). */
+    inputNote?: string;
+    output: Field[];
+    outputKind: 'object' | 'jsonl';
+    /** Every persistent change the command makes to the world. For read-only
+     *  leaves use exactly: ["None. Read-only."] */
+    effects: string[];
+    /** Bounded runtime aggregate as a complete self-named state element (build it
+     *  with stateBlock), e.g. `<kinds count="7">…</kinds>`. Lazily evaluated at
+     *  render time so it reflects the caller's cwd/project scope; appended after
+     *  the schema. Renderer soft-fails to omission if it returns null or throws.
+     *  Mirrors BranchHelp.dynamicState. */
+    dynamicState?: () => string | null;
+    /** Attach-viewer preview hint (see PreviewMeta). Optional; omit for the
+     *  default preview behaviour. */
+    preview?: PreviewMeta;
+}
+/** Invocation-local help view for one hook-eligible core leaf. It shares every
+ *  non-effects field with the frozen core help and owns a separately frozen
+ *  effects list that describes the effective pipeline. */
+export type EffectiveLeafHelp = Readonly<Omit<LeafHelp, 'effects'> & {
+    effects: readonly string[];
+}>;
+/** State elements a leaf reads asynchronously (e.g. from the daemon) when its
+ *  help renders: `leaf` stands in for `dynamicState`, `flags` for a named
+ *  flag's `focusedHelp.dynamicState`. */
+export interface AsyncHelpState {
+    leaf?: () => Promise<string>;
+    flags?: Readonly<Record<string, () => Promise<string>>>;
+}
+/** `help` with the async state the render shows read once: the leaf's for
+ *  ordinary help, only `focusedFlag`'s for focused help. A read that throws
+ *  renders no element, the same soft failure `evalDynamic` gives a sync one. */
+export declare function withAsyncHelpState(help: LeafHelp, state: AsyncHelpState, focusedFlag?: string): Promise<LeafHelp>;
+/** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
+ *  subtree that owns the state authors it through this, so the tag name and any
+ *  scalar metadata (e.g. a count) travel with the data and render identically
+ *  at every level the block appears. The tag name carries the label, so the
+ *  body never repeats it. Attribute values are controlled (counts, short
+ *  tokens) and not escaped. */
+export declare function stateBlock(tag: string, attrs: Record<string, string | number>, body: string): string;
+export declare function renderRoot(h: RootHelp): string;
+/** A branch with more visible children than this lists only its promoted
+ *  (`common` / `important`) children in its own -h and counts the rest. A
+ *  plugin that mounts one command per catalog entry (a provider with >1,000
+ *  services) would otherwise print every one on each `-h`. Unlisted children
+ *  still route, and their own `-h` still renders. */
+export declare const WIDE_BRANCH_LISTING_LIMIT = 40;
+/** Split a branch's non-hidden children into the ones its -h lists and the count
+ *  it leaves out. A branch at or under the limit, or one with no promoted child
+ *  to fall back on, lists everything. */
+export declare function collapseWideChildren<T extends {
+    tier?: SubTier;
+}>(visible: readonly T[]): {
+    listed: T[];
+    unlisted: number;
+};
+/** The children of a branch that its parent's (root) -h promotes inline: its
+ *  `common` / `important` ones. On a wide branch only leaves are promoted, so a
+ *  promoted service branch shows in the branch's own -h but does not widen the
+ *  root listing every agent reads. */
+export declare function rootPromotedChildren<T extends {
+    tier?: SubTier;
+    kind?: 'leaf' | 'branch';
+}>(visible: readonly T[]): T[];
+export declare function renderBranch(h: BranchHelp): string;
+/** Render one leaf's ordinary contract, or the focused continuation for one
+ *  uncommon flag selected through `--flag -h`. The caller reaches focused help
+ *  from the ordinary row, so that view contains only leaf identity and the new
+ *  parameter detail instead of repeating information already in context. */
+export declare function renderLeafArgv(h: LeafHelp | EffectiveLeafHelp, focusedFlag?: string): string;