import { providerEnvVars, providerNames } from "./credentials.js"; import type { CliWriter } from "./envelope.js"; import { EXIT_CODES, type CliErrorCode } from "./errors.js"; import { isCredentialOptional } from "./providers.js"; export const HELP_TOPICS = [ "output", "exit-codes", "environment", "agents", ] as const; export type HelpTopic = (typeof HELP_TOPICS)[number]; export function isHelpTopic(name: string): name is HelpTopic { return (HELP_TOPICS as readonly string[]).includes(name); } /** * The exit-code table, rendered from the single constant in `errors.ts`. * * Codes are the contract and several share a status, so the table is grouped * by number: a caller branching on `code` reads the left column, a shell * script reads the right one. */ export function exitCodeTable(): string { const byExit = new Map(); for (const [code, exit] of Object.entries(EXIT_CODES) as [ CliErrorCode, number, ][]) { const bucket = byExit.get(exit); if (bucket) bucket.push(code); else byExit.set(exit, [code]); } const rows = [...byExit.entries()].sort((a, b) => a[0] - b[0]); const width = Math.max(...rows.map(([, codes]) => codes.join(", ").length)); return [ `${"code".padEnd(width)} exit`, `${"0".padEnd(width)} 0`, ...rows.map( ([exit, codes]) => `${codes.join(", ").padEnd(width)} ${exit}` ), ].join("\n"); } /** * The providers discovery reports as configured whatever the sources * hold: every one `isCredentialOptional` names, split by whether it reads * a variable at all. Derived, so the environment topic cannot fall behind * the code (ac-98i46v). */ function alwaysConfiguredRows(): string[] { const always = providerNames().filter(isCredentialOptional).sort(); const keyless = always.filter((name) => providerEnvVars(name).length === 0); const optional = always.filter((name) => providerEnvVars(name).length > 0); return [ ` no credential ${keyless.join(", ")}`, ` optional credential ${optional.join(", ")}`, ]; } const TOPIC_TEXT: Record string> = { output: () => [ "apicity help output — what a command prints", "", "Success goes to stdout, failure to stderr, and never both for one", "invocation. Whenever stdout is not a terminal — a pipe, a file, an", "agent — or `--json` is passed, a failure is exactly one JSON document:", "", ' {"ok": false, "error": "...", "code": "...", "hint": "..."}', "", "`code` is the stable contract — see `apicity help exit-codes`. `hint`,", "when present, is one line naming what to run or set next. At a terminal", "without `--json` the same failure prints as `Error:` and `hint:` lines,", "on stderr, with the same exit status.", "", "Success follows the same rule. Piped or with `--json`, a call,", "`doctor`, `setup`, `skill install` and the discovery commands", "(`commands`, `describe`, `providers`) print one JSON document, with", "the result under `data`:", "", ' {"ok": true, "data": ..., "summary": "..."}', "", "`--quiet` prints `data` alone, compactly with `--json`. At a terminal", "without `--json`, `commands` and `providers` print an aligned table", "and `describe` a text block, meant for a human reader.", ].join("\n"), "exit-codes": () => [ "apicity help exit-codes — every status the CLI returns", "", exitCodeTable(), "", "Branch on the `code` field of the error envelope, not on the number:", "several codes share a status and the numbers may gain siblings.", ].join("\n"), environment: () => [ "apicity help environment — credentials and configuration", "", "Every provider reads its credential from the environment. Run", "`apicity providers` for the env var names and which are set; the CLI", "prints names only and never a value.", "", "A call fills the addressed provider's variables, and no other", "provider's; for each variable the first source that has one wins:", "", " 1. a value already set in the process environment", " 2. a literal in the env file: --env-file, else APICITY_ENV_FILE,", " else ~/.config/apicity/.env", " 3. an op://// reference, in the environment or", " the env file (the `op run --env-file` format); all of a call's", " references resolve in one `op inject`, with the configured token", " or op's own sign-in", " 4. the vault convention op:////password, when --op-vault", " and --op-token (APICITY_OP_VAULT, APICITY_OP_SERVICE_TOKEN) are", " both set", "", "Persist the vault and token once, and every later call uses them:", "", " apicity setup 1password --op-vault --op-token env:", "", "`env:` stores the name of the variable that holds the token, so", "the token itself never touches the file. `apicity doctor` checks it.", "", "These providers are always reported as configured, whatever the", "sources above hold:", "", ...alwaysConfiguredRows(), "", "Any other provider is reported as configured when each of its variables", "has a source above. That check never runs `op`.", "", "`apicity commands` and `apicity describe` need no credential: they read", "a generated catalog rather than calling upstream.", "", "Other variables the CLI reads:", "", " APICITY_HAR_CAPTURE all, failures or off (default off)", " APICITY_HAR_DIR capture dir (default ~/.config/apicity/har)", " --capture-har [all|failures] endpoint-only override; bare means all", " apicity har list|show|scrub inspect captures; scrub --check before sharing", " apicity har report [--provider p[,p]] [--endpoint dot.path]", " [--since iso] [--baseline dir | --no-baseline] [--json]", " Markdown even when redirected; --json emits the versioned report envelope.", " apicity har cost [--provider p[,p]] [--endpoint dot.path]", " [--model m] [--since iso] [--tolerance 0.02] [--json]", " Estimate against actual per endpoint and model, with rate corrections.", " APICITY_OUTPUT_DIR where media lands, as --output-dir", " CLAUDE_PROJECT_DIR where media lands when neither is set", " APICITY_PAYGATE_SECRET_FILE arms the pay gate, as --paygate-secret-file", " APICITY_SETUP_AGENT which agent `apicity setup agents` connects", ].join("\n"), agents: () => [ "apicity help agents — using this CLI from an agent", "", "Discovery is three steps, all of them offline:", "", " apicity providers --json which providers exist and are set", " apicity commands --provider

--json that provider's endpoints", " apicity describe

--json one endpoint in full", "", "`describe` answers the request schema, a recorded example payload and", "the call shape. Read both parameter lists: `pathParams` are positional", "arguments and `requestParams` are properties of the request object.", "Passing one where the other belongs is the single most common mistake.", "", "A dotPath carrying more than one method exits `ambiguous` (8) until you", "pass `--method`.", ].join("\n"), }; export function helpTopicText(topic: HelpTopic): string { return TOPIC_TEXT[topic](); } export function printHelpTopic(writer: CliWriter, topic: HelpTopic): void { writer.out(helpTopicText(topic)); } /** The one-line pointers usage prints under its command list. */ export function helpTopicsLine(): string { return `Help topics: ${HELP_TOPICS.join(", ")} — run "apicity help ".`; }