argsbarg 6.1.2 → 6.1.3

package/index.d.ts

@@ -1,9 +1,5 @@
 // Generated by dts-bundle-generator v9.5.1
 
-/** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
-export declare function resolveAppConfigPath(program: CliProgram): string;
-/** Human-readable config path for error messages (`~/…` when under home). */
-export declare function displayAppConfigPath(program: CliProgram): string;
 export type ResolvedConfig = Record<string, unknown>;
 declare class EmptyAppConfigSnapshot {
 	private readonly program;
@@ -52,19 +48,25 @@ export type CliLeafInputs = Record<string, boolean | number | string | string[]
 export declare class CliContext {
 	readonly appName: string;
 	readonly commandPath: string[];
-	readonly args: string[];
+	args: string[];
 	readonly program: CliProgram;
-	readonly opts: Record<string, string>;
+	opts: Record<string, string>;
 	readonly invocation: CliInvocation;
 	readonly appConfig: AnyAppConfigSnapshot;
 	/** Original flat tool arguments for API/MCP invocations (when provided). */
 	readonly toolArgs?: Record<string, unknown>;
+	/** Path parameter values from `:param` router descent. */
+	readonly pathParams: Record<string, string>;
 	/** Pipable Json option values read from stdin before the handler (CLI only). */
 	readonly preloadedJson: Record<string, unknown>;
+	/** Per-invocation bag; `beforeInvoke` may write. */
+	readonly locals: CliLocals;
+	/** Shared server state for HTTP/MCP invocations. */
+	runtime?: ServerRuntime;
 	private response?;
 	private leafInputsCache?;
 	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
-	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot, toolArgs?: Record<string, unknown>, preloadedJson?: Record<string, unknown>);
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot, toolArgs?: Record<string, unknown>, preloadedJson?: Record<string, unknown>, pathParams?: Record<string, string>, locals?: CliLocals, runtime?: ServerRuntime);
 	/**
 	 * Sets the machine-readable response for API/MCP invocations, or writes to stdout in CLI mode.
 	 * May only be called once per invocation.
@@ -107,14 +109,6 @@ export declare class CliContext {
 	 * {@link inputs} cast to a schemagen or app-defined input type (consumer-asserted; not inferred from `inputSchema`).
 	 */
 	inputsAs<T = CliLeafInputs>(): T;
-	/**
-	 * @deprecated Use {@link inputs} or {@link inputsAs}.
-	 */
-	readLeafInputs(): CliLeafInputs;
-	/**
-	 * @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs.
-	 */
-	readLeafInputsAsync(): Promise<CliLeafInputs>;
 	private _leafNode;
 	private _posMap;
 	private _positionalMap;
@@ -122,7 +116,7 @@ export declare class CliContext {
 /**
  * How a leaf handler was dispatched.
  */
-export type CliInvocation = "cli" | "mcp" | "api";
+export type CliInvocation = "cli" | "mcp" | "http";
 /**
  * Option kinds: presence (boolean flag), string (free-form text), number (strict double), enum (fixed choices), or json (parsed JSON object/array).
  */
@@ -170,14 +164,52 @@ export declare enum CliFallbackMode {
 	 */
 	UnknownOnly = "unknownOnly"
 }
+/**
+ * Per-surface CLI exposure (help, completions, cli-schema).
+ */
+export interface CliCliExposureConfig {
+	/** When `false`, not callable via CLI (cascades to descendants). Default: true. */
+	enabled?: boolean;
+	/** Callable; omit from help, completions, and schema export. */
+	hidden?: boolean;
+	completions?: {
+		enabled?: boolean;
+		hidden?: boolean;
+	};
+	schema?: {
+		enabled?: boolean;
+		hidden?: boolean;
+	};
+}
+/** HTTP method for REST leaves. */
+export type CliHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Per-node HTTP exposure and response defaults (routers: segment/enabled/hidden; leaves: full set).
+ */
+export interface CliHttpExposureConfig {
+	/** When `false`, omit from HTTP route table. Default: exposed. */
+	enabled?: boolean;
+	/** Callable; omit from OpenAPI / route discovery. */
+	hidden?: boolean;
+	/** Override inferred HTTP verb. */
+	method?: CliHttpMethod;
+	/** URL path segment override (≠ `key`). */
+	segment?: string;
+	/** Default success HTTP status when handler omits `ctx.respond({ status })`. */
+	successStatus?: number;
+	/** Default success Content-Type (OpenAPI + response headers). */
+	successContentType?: string;
+	/** Default Content-Disposition for binary/downloads. */
+	contentDisposition?: string;
+}
 /**
  * A named flag or value option (`--long`, `-short`), listed on command `options`.
  */
 export interface CliOption {
 	/** Option name (e.g., "name", "verbose"). */
 	name: string;
-	/** When `true`, omit from help, schema, completions, and MCP tool inputSchema (still parseable). */
-	hidden?: boolean;
+	/** Per-surface CLI exposure for this option. */
+	cli?: Pick<CliCliExposureConfig, "hidden">;
 	/** Description shown in help. */
 	description: string;
 	/** Option kind: presence flag, string value, or number value. */
@@ -227,7 +259,7 @@ export interface CliPositional {
 	 */
 	argMax?: number;
 }
-/** Optional metadata for `mcp bundle` MCP Bundle output (program root `mcpServer.bundle` only). */
+/** @experimental MCP bundle output options (program root `mcpServer.bundle` only). */
 export interface CliMcpBundleConfig {
 	author?: {
 		name: string;
@@ -242,10 +274,15 @@ export interface CliMcpBundleConfig {
 /**
  * Enables `myapp mcp` and MCP stdio server metadata (program root only).
  * Must include `enabled: true`; omit `mcpServer` entirely to disable MCP.
+ * @experimental
  */
 export interface CliMcpServerConfig {
 	/** When `true`, enables the `mcp` built-in and MCP stdio server. */
 	enabled: boolean;
+	/** MCP error response defaults. */
+	errors?: CliMcpServerErrorsConfig;
+	/** Observe-only hooks for JSON-RPC messages. */
+	hooks?: CliMcpWireHooks;
 	/** When `true`, `mcp bundle` writes `dist/<key>.mcpb` for Claude Desktop. Default false. */
 	mcpd?: boolean;
 	/** When `true`, `mcp bundle` also writes `dist/claude-plugin/<name>.zip`. Default false. */
@@ -266,26 +303,70 @@ export interface CliMcpServerConfig {
 	/** Optional MCP Bundle (`.mcpb`) metadata for `mcp bundle`. */
 	bundle?: CliMcpBundleConfig;
 }
+/** JSON Schema for structured error responses (OpenAPI + HTTP/MCP error bodies). */
+export type CliJsonSchema = Record<string, unknown>;
+/** Wire-level HTTP hooks (observe-only; all requests including health and 404s). */
+export interface CliHttpWireHooks {
+	onRequest?: (ctx: CliHttpWireContext) => void | Promise<void>;
+	onResponse?: (ctx: CliHttpWireContext & {
+		status: number;
+		durationMs: number;
+	}) => void | Promise<void>;
+	onError?: (ctx: CliHttpWireContext & {
+		failureKind: InvokeFailureKind;
+		error: unknown;
+	}) => void | Promise<void>;
+}
+/** Per-request HTTP wire context for {@link CliHttpWireHooks}. */
+export interface CliHttpWireContext {
+	request: Request;
+	requestId: string;
+	clientIp: string;
+	path: string;
+	method: string;
+}
+/** Wire-level MCP hooks on JSON-RPC messages (observe-only). */
+export interface CliMcpWireHooks {
+	onRequest?: (ctx: CliMcpWireContext) => void | Promise<void>;
+	onResponse?: (ctx: CliMcpWireContext & {
+		durationMs: number;
+	}) => void | Promise<void>;
+	onError?: (ctx: CliMcpWireContext & {
+		failureKind: InvokeFailureKind;
+		error: unknown;
+	}) => void | Promise<void>;
+}
+/** Per-message MCP wire context for {@link CliMcpWireHooks}. */
+export interface CliMcpWireContext {
+	rpcMethod: string;
+	requestId: string;
+	toolName?: string;
+}
 /**
- * Enables `myapp api` and the HTTP tool server (program root only).
- * Must include `enabled: true`; omit `apiServer` entirely to disable HTTP.
+ * Enables `myapp http` and the HTTP tool server (program root only).
+ * Must include `enabled: true`; omit `httpServer` entirely to disable HTTP.
  */
-export interface CliApiServerConfig {
-	/** When `true`, enables the `api` built-in and HTTP tool server. */
+export interface CliHttpServerConfig {
+	/** When `true`, enables the `http` built-in and HTTP tool server. */
 	enabled: boolean;
 	/** Listen host (default: `127.0.0.1`). */
 	host?: string;
 	/** Listen port (default: `3000`). */
 	port?: number;
+	/** Honor `X-Forwarded-For` for client IP in hooks and logs. */
+	trustProxy?: boolean;
+	/** HTTP error response defaults. */
+	errors?: {
+		errorSchema?: CliJsonSchema;
+		obscureUnexpected?: boolean;
+	};
+	/** Observe-only hooks for all HTTP requests. */
+	hooks?: CliHttpWireHooks;
 }
-/**
- * Declarative HTTP response hints for a leaf (used by OpenAPI and default headers).
- */
-export interface CliApiResponseConfig {
-	/** Default success Content-Type (default: `application/json`). */
-	contentType?: string;
-	/** Optional Content-Disposition (e.g. `attachment; filename="invoice.pdf"`). */
-	contentDisposition?: string;
+/** MCP server error defaults. */
+export interface CliMcpServerErrorsConfig {
+	errorSchema?: CliJsonSchema;
+	obscureUnexpected?: boolean;
 }
 /** Body types accepted by {@link CliContext.respond}. */
 export type CliRespondBody = string | Uint8Array | Record<string, unknown> | unknown[];
@@ -319,15 +400,13 @@ export interface CliMcpResource {
 export interface CliMcpToolConfig {
 	/** When `false`, omit from `tools/list` (default: exposed). */
 	enabled?: boolean;
+	/** Callable; omit from `tools/list` and MCP tool schemas. */
+	hidden?: boolean;
 	/**
 	 * Override the generated MCP tool description.
 	 * Default: auto-generated from command path and description.
 	 */
 	description?: string;
-	/**
-	 * @deprecated Set `outputSchema` on the leaf command instead.
-	 */
-	outputSchema?: Record<string, unknown>;
 }
 /** Context passed to {@link CliAppConfigEntry.resolve} for one config key. */
 export interface CliAppConfigResolveContext {
@@ -392,6 +471,7 @@ export interface CliCompletionConfig {
 	/** When `false`, hide/disable `completion` (default: enabled). */
 	enabled?: boolean;
 }
+/** @experimental */
 export interface CliConfigureConfig {
 	/** When `false`, hide/disable `configure` (default: enabled). */
 	enabled?: boolean;
@@ -459,21 +539,16 @@ export interface CliDocsTopic {
 	description?: string;
 }
 /**
- * Enables `myapp docs` and bundled markdown topics (program root only).
- * Must include `enabled: true`; omit `docs` entirely to disable.
+ * Opt-out and optional topics for the `docs` built-in (program root only).
+ * Docs is enabled by default; set `enabled: false` to disable.
  */
 export interface CliDocsConfig {
-	/** When `true`, enables the `docs` built-in command group. */
-	enabled: boolean;
+	/** When `false`, hide/disable `docs` (default: enabled). */
+	enabled?: boolean;
 	/** Router description for `myapp docs` (default: "Print bundled CLI documentation."). */
 	description?: string;
-	/**
-	 * Subcommand for bare `myapp docs` (maps to router `fallbackCommand`).
-	 * When omitted, uses the first key in `topics` (insertion order).
-	 */
-	defaultTopic?: string;
-	/** Topic key → bundled markdown. Reserved keys: `mcp`, `all` (supplied by the built-in). */
-	topics: Record<string, CliDocsTopic>;
+	/** Optional consumer markdown topics. Reserved keys: `mcp`, `all` (supplied by the built-in). */
+	topics?: Record<string, CliDocsTopic>;
 }
 /**
  * Base properties shared by all nodes in the user command tree.
@@ -481,8 +556,10 @@ export interface CliDocsConfig {
 export interface CliNodeBase {
 	/** Program or command key (e.g., "myapp", "stat", "owner"). */
 	key: string;
-	/** When `true`, omit from help listings, schema, completions, and MCP tools (still invocable). */
-	hidden?: boolean;
+	/** Per-surface CLI exposure. */
+	cli?: CliCliExposureConfig;
+	/** Per-surface HTTP exposure and response defaults. */
+	http?: CliHttpExposureConfig;
 	/** Short description shown in help. */
 	description: string;
 	/** Additional notes shown in help (`{argsbarg:program}` → program key). */
@@ -507,13 +584,11 @@ export type CliLeaf = CliNodeBase & {
 	positionals?: CliPositional[];
 	/**
 	 * JSON Schema for structured stdout (e.g. with `--json` or MCP when the handler emits JSON).
-	 * Exported in `docs cli-schema`, `docs api`, and MCP `tools/list`; not validated at runtime yet.
+	 * Exported in `docs cli-schema`, `docs cli`, and MCP `tools/list`; not validated at runtime yet.
 	 */
 	outputSchema?: Record<string, unknown>;
 	/** JSON Schema for MCP/HTTP tool arguments (flat object). */
 	inputSchema?: Record<string, unknown>;
-	/** Declarative HTTP response metadata (Content-Type, Content-Disposition). */
-	apiResponse?: CliApiResponseConfig;
 	/** Per-tool MCP exposure and metadata. */
 	mcpTool?: CliMcpToolConfig;
 };
@@ -532,6 +607,122 @@ export type CliRouter = CliNodeBase & {
  * A node in the user-defined command tree (router or leaf).
  */
 export type CliNode = CliLeaf | CliRouter;
+/** Classified failure kind for invoke error pipeline and HTTP/MCP status mapping. */
+export type InvokeFailureKind = "validation" | "help" | "unexpected" | "not_ready" | "missing_config" | "unknown_route";
+/**
+ * Per-invocation context attached in hooks (e.g. DB handles, auth principals).
+ * Augment in app code: `declare module "argsbarg" { interface CliLocals { db: AppDb } }`.
+ */
+export interface CliLocals {
+	/** Correlation id seeded before hooks run (HTTP/MCP wire id or generated UUID). */
+	requestId?: string;
+}
+/**
+ * Cross-request server state (HTTP/MCP runtime bag).
+ * Augment in app code: `declare module "argsbarg" { interface ServerState { db: AppDb } }`.
+ */
+export interface ServerState {
+	/** Set when app config soft-validation fails at server start. */
+	configFileError?: string;
+	/** Short-TTL cache for readiness probe results. */
+	readinessCache?: {
+		at: number;
+		result: {
+			ok: boolean;
+			checks: Record<string, {
+				ok: boolean;
+				error?: string;
+				missing?: string[];
+			}>;
+		};
+	};
+	/** Last readiness probe result. */
+	readiness?: {
+		ok: boolean;
+		checks: Record<string, {
+			ok: boolean;
+			error?: string;
+			missing?: string[];
+		}>;
+	};
+}
+/** Cross-request mutable state created at HTTP/MCP server start. */
+export interface ServerRuntime {
+	/** Mutable global bag (DB pool, degraded flags, readiness cache, etc.). */
+	state: ServerState;
+	program: CliProgram;
+	surface: "http" | "mcp";
+}
+/** Context for program-level invoke hooks (CLI, HTTP, MCP user commands). */
+export interface InvokeHookContext {
+	invocation: CliInvocation;
+	path: string[];
+	pathParams: Record<string, string>;
+	opts: Record<string, string>;
+	/** Per-invocation bag; `beforeInvoke` may write. Framework seeds `requestId` before hooks run. */
+	locals: CliLocals;
+	runtime?: ServerRuntime;
+	appConfig: AnyAppConfigSnapshot;
+	http?: {
+		request: Request;
+		clientIp: string;
+		requestId: string;
+	};
+	mcp?: {
+		rpcMethod: string;
+		toolName?: string;
+		requestId: string;
+	};
+}
+/** Error hook context after failure classification. */
+export interface ErrorHookContext extends InvokeHookContext {
+	failureKind: InvokeFailureKind;
+	error: unknown;
+	/** Default client-facing error before `formatError` override. */
+	clientError: ClientErrorOverride;
+}
+/** Client-facing error payload; `formatError` may return a partial override. */
+export interface ClientErrorOverride {
+	message: string;
+	exitCode?: number;
+}
+/** Minimal invoke result passed to `afterInvoke` (see {@link Cli.invoke}). */
+export interface CliInvokeHookResult {
+	kind: "ok" | "help" | "error";
+	exitCode: number;
+	failureKind?: InvokeFailureKind;
+	errorMsg?: string;
+}
+/** Program-level invoke and error hooks (skipped for builtins). */
+export interface CliProgramHooks {
+	/** May mutate `locals`, `opts`, `args`; may throw. Skipped for builtins. */
+	beforeInvoke?: (ctx: InvokeHookContext) => void | Promise<void>;
+	afterInvoke?: (ctx: InvokeHookContext & {
+		result: CliInvokeHookResult;
+	}) => void | Promise<void>;
+	/** Mutate client-facing error payload only. Runs before `onError`. */
+	formatError?: (ctx: ErrorHookContext) => ClientErrorOverride | undefined | Promise<ClientErrorOverride | undefined>;
+	/** Observe only — runs after `formatError`; may enrich `locals`. Never mutates client response. */
+	onError?: (ctx: ErrorHookContext) => void | Promise<void>;
+}
+/** Context for optional `program.readiness` (HTTP/MCP health only). */
+export interface ReadinessContext {
+	program: CliProgram;
+	surface: "http" | "mcp";
+	appConfig: AnyAppConfigSnapshot;
+	runtime: ServerRuntime;
+}
+/** Framework logging defaults (ECS json or human text on stderr). */
+export interface CliLogConfig {
+	/** `json` = ECS lines; `text` = human stderr lines. Default: `json`. */
+	format?: "json" | "text";
+	/** Tee stderr + append; relative paths resolve under the app config dir. */
+	file?: string;
+	/** Emit HTTP/MCP access logs. Default: true. */
+	access?: boolean;
+	/** Emit error events after the hook pipeline. Default: true. */
+	errors?: boolean;
+}
 /**
  * Program root passed to {@link Cli}.
  * May be a leaf or router, plus optional program-level MCP and install config.
@@ -543,14 +734,20 @@ export type CliProgram = CliNode & {
 	appConfig?: CliAppConfig;
 	/** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
 	mcpServer?: CliMcpServerConfig;
-	/** When set with `enabled: true`, enables the `api` built-in HTTP server. */
-	apiServer?: CliApiServerConfig;
+	/** When set with `enabled: true`, enables the `http` built-in HTTP server. */
+	httpServer?: CliHttpServerConfig;
 	/** Opt-out and defaults for `configure`. */
 	configure?: CliConfigureConfig;
 	/** Opt-out for shell completion generation (`completion bash|zsh|fish`). */
 	completion?: CliCompletionConfig;
-	/** When set with `enabled: true`, enables the `docs` built-in command group. */
+	/** Opt-out and optional topics for the `docs` built-in (default: enabled). */
 	docs?: CliDocsConfig;
+	/** Invoke and error hooks for user commands on CLI, HTTP, and MCP. */
+	hooks?: CliProgramHooks;
+	/** Optional readiness probe for HTTP/MCP `GET /health/ready` only. */
+	readiness?: (ctx: ReadinessContext) => boolean | Promise<boolean>;
+	/** Framework logging (stderr + optional file). */
+	log?: CliLogConfig;
 };
 /** True when the leaf accepts a pure JSON body (no CLI flags). */
 export declare function isJsonLeaf(leaf: CliLeaf): boolean;
@@ -566,68 +763,10 @@ export declare class CliSchemaValidationError extends Error {
 	/** Creates a schema validation error with a human-readable rule violation. */
 	constructor(message: string);
 }
-/** Generates an OpenAPI 3.1 document for the program's exposed tools. */
-export declare function generateOpenApi(program: CliProgram): Record<string, unknown>;
-/** Pretty-printed OpenAPI JSON (same document as `GET /openapi.json`). */
-export declare function openApiJson(program: CliProgram): string;
-/** Platform builtins derived from program config and runtime. */
-export interface CliCapabilities {
-	api: boolean;
-	completion: boolean;
-	mcp: boolean;
-	configure: boolean;
-	docs: boolean;
-	configCommands: boolean;
-}
-/** JSON-safe command node (no handlers). */
-export interface CliSchemaExport {
-	key: string;
-	description: string;
-	notes?: string;
-	/** JSON Schema for structured stdout when set on the leaf. */
-	outputSchema?: Record<string, unknown>;
-	options?: CliOption[];
-	fallbackCommand?: string;
-	fallbackMode?: CliFallbackMode;
-	commands?: CliSchemaExport[];
-	positionals?: CliPositional[];
-}
-/** Outcome of a non-exiting CLI invocation. */
-export type CliInvokeKind = "ok" | "help" | "error";
-/** Result of Cli.invoke: captured output and exit metadata without process.exit. */
-export interface CliInvokeResult {
-	kind: CliInvokeKind;
-	exitCode: number;
-	stdout: string;
-	stderr: string;
-	errorMsg?: string;
-	/** Headless response payload when invocation is `api` or `mcp` and the handler succeeded. */
-	response?: CliRespondOptions;
-}
-/** Argsbarg runtime for a validated, frozen {@link CliProgram}. */
-export declare class Cli {
-	readonly program: CliProgram;
-	readonly caps: CliCapabilities;
-	private readonly parseRootMerged;
-	private readonly presentationRoot;
-	private _appConfig?;
-	constructor(program: CliProgram);
-	get appConfig(): AnyAppConfigSnapshot;
-	exportCommandSchema(): CliSchemaExport;
-	exportAppConfigSchema(): Record<string, unknown> | undefined;
-	run(argv?: string[]): Promise<never>;
-	invoke(argv: string[], opts?: {
-		invocation?: CliInvocation;
-		toolArgs?: Record<string, unknown>;
-	}): Promise<CliInvokeResult>;
-	serveMcp(): Promise<never>;
-	serveApi(): Promise<never>;
-	private ensureValidatedLeafInputs;
-	private exitLeafInputError;
-	private prepareDispatch;
-	private buildAppConfigSnapshot;
-}
-export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
+/** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
+export declare function resolveAppConfigPath(program: CliProgram): string;
+/** Human-readable config path for error messages (`~/…` when under home). */
+export declare function displayAppConfigPath(program: CliProgram): string;
 /** Parses a duration string (e.g. 20m, 1h, 30s) into milliseconds. */
 export declare function parseDurationMs(durationStr: string): number;
 /** Splits a comma-separated string into trimmed non-empty tokens. */
@@ -636,6 +775,17 @@ export declare function parseCommaList(s: string): string[];
 export declare function parseDate(s: string): string;
 /** Returns normalized ISO 8601 UTC after validation. */
 export declare function parseDateTime(s: string): string;
+/** Thrown when leaf input resolution or validation fails. */
+export declare class LeafInputError extends Error {
+	constructor(message: string);
+}
+/** Resolves a Json option from argv, preloaded stdin, or toolArgs (flag wins). */
+export declare function readJsonOptionValue(ctx: CliContext, name: string): unknown | undefined;
+/**
+ * Reads piped stdin for a pipable Json option when the flag is omitted (CLI only).
+ * Call from {@link Cli.run} before constructing the handler context.
+ */
+export declare function preloadPipableJson(program: CliProgram, commandPath: string[], opts: Record<string, string>, invocation: CliInvocation, args?: string[]): Promise<Record<string, unknown>>;
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
 /** True when `--json` was passed or the handler was invoked headlessly over MCP/HTTP. */
@@ -671,26 +821,10 @@ dryRun?: boolean,
 interactive?: boolean): void;
 /** Prefixes a success message when running in dry-run mode. */
 export declare function formatDryRunMessage(message: string, dryRun: boolean): string;
-/** Thrown when leaf input resolution or validation fails. */
-export declare class LeafInputError extends Error {
-	constructor(message: string);
-}
-/** Resolves a Json option from argv, preloaded stdin, or toolArgs (flag wins). */
-export declare function readJsonOptionValue(ctx: CliContext, name: string): unknown | undefined;
-/**
- * Reads piped stdin for a pipable Json option when the flag is omitted (CLI only).
- * Call from {@link Cli.run} before constructing the handler context.
- */
-export declare function preloadPipableJson(program: CliProgram, commandPath: string[], opts: Record<string, string>, invocation: CliInvocation, args?: string[]): Promise<Record<string, unknown>>;
-/**
- * Loads coerced leaf inputs and validates against `leaf.inputSchema` when set.
- * Used by {@link CliContext.inputs}; prefer `ctx.inputs` or `ctx.inputsAs()` in handlers.
- */
-export declare function loadLeafInputs(ctx: CliContext): CliLeafInputs;
-/** @deprecated Use {@link CliContext.inputs} or {@link loadLeafInputs} via `ctx.inputs`. */
-export declare function readLeafInputs(ctx: CliContext): CliLeafInputs;
-/** @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs. */
-export declare function readLeafInputsAsync(ctx: CliContext): Promise<CliLeafInputs>;
+/** Generates an OpenAPI 3.1 document for the program's HTTP routes. */
+export declare function generateOpenApi(program: CliProgram): Record<string, unknown>;
+/** Pretty-printed OpenAPI JSON (same document as `GET /openapi.json`). */
+export declare function openApiJson(program: CliProgram): string;
 /** Resolved paths for `mcp bundle`. */
 export interface McpBundlePaths {
 	binaryPath: string;
@@ -711,6 +845,167 @@ export interface PackMcpBundleOpts {
  * Requires the compiled binary to exist.
  */
 export declare function packMcpBundle(program: CliProgram, opts?: PackMcpBundleOpts): string;
+/** JSON-safe command node (no handlers). */
+export interface CliSchemaExport {
+	key: string;
+	description: string;
+	notes?: string;
+	/** JSON Schema for structured stdout when set on the leaf. */
+	outputSchema?: Record<string, unknown>;
+	/** Default success Content-Type when `outputSchema` is omitted but `http.successContentType` is set. */
+	outputContentType?: string;
+	options?: CliOption[];
+	fallbackCommand?: string;
+	fallbackMode?: CliFallbackMode;
+	commands?: CliSchemaExport[];
+	positionals?: CliPositional[];
+}
+/** JSON-safe command tree export (handlers omitted). */
+export interface CliSchemaRootExport extends CliSchemaExport {
+	/** Program-level error JSON Schema when configured on `httpServer.errors` or `mcpServer.errors`. */
+	errorSchema?: Record<string, unknown>;
+}
+/** Severity label for ECS `log.level`. */
+export type EcsLogLevel = "debug" | "info" | "warn" | "error";
+/** Input for one ECS log event. */
+export interface EcsLogEvent {
+	level: EcsLogLevel;
+	message: string;
+	action?: string;
+	labels?: Record<string, string | number | boolean>;
+	error?: unknown;
+	fields?: Record<string, unknown>;
+}
+/** Resolved logging options for a server or invoke session. */
+export interface ResolvedLogConfig {
+	format: "json" | "text";
+	file?: string;
+	access: boolean;
+	errors: boolean;
+	dev: boolean;
+}
+/** Options for {@link LogEmitter}. */
+export interface LogEmitterOpts {
+	program: CliProgram;
+	resolved: ResolvedLogConfig;
+}
+declare class LogEmitter {
+	private readonly service;
+	private readonly resolved;
+	constructor(opts: LogEmitterOpts);
+	get config(): ResolvedLogConfig;
+	/** Emits one log event to stderr (and optional file). */
+	emit(event: EcsLogEvent): void;
+	/** Human startup line or ECS/json event for lifecycle milestones. */
+	emitLifecycle(message: string, action: string, labels?: Record<string, string | number | boolean>): void;
+	/** Access log for one HTTP request or MCP RPC. */
+	emitAccess(fields: {
+		method: string;
+		path: string;
+		status: number;
+		durationMs: number;
+		requestId?: string;
+		clientIp?: string;
+	}): void;
+	/** Error log after the hook pipeline (real stack always included). */
+	emitInvokeError(failureKind: string, error: unknown, clientMessage: string, labels?: Record<string, string | number | boolean>): void;
+	private formatLine;
+	private formatTextLine;
+	private appendFile;
+}
+/** Overrides from `myapp http` / `serveHttp()` flags and embedders. */
+export interface ServeOverrides {
+	host?: string;
+	port?: number;
+	trustProxy?: boolean;
+	obscureErrors?: boolean;
+	logFormat?: "json" | "text";
+	logFile?: string;
+	noAccessLog?: boolean;
+	dev?: boolean;
+}
+/** Resolved HTTP listen and error options after merging schema + overrides. */
+export interface ResolvedHttpServeConfig {
+	hostname: string;
+	port: number;
+	trustProxy: boolean;
+	obscureUnexpected: boolean;
+	log: ResolvedLogConfig;
+}
+/** Resolved MCP serve options after merging schema + overrides. */
+export interface ResolvedMcpServeConfig {
+	obscureUnexpected: boolean;
+	log: ResolvedLogConfig;
+}
+/** Shared server state for one HTTP or MCP serve session. */
+export interface ServerHandleContext {
+	runtime: ServerRuntime;
+	emitter: LogEmitter;
+	http?: ResolvedHttpServeConfig;
+	mcp?: ResolvedMcpServeConfig;
+	httpHooks?: CliHttpWireHooks;
+	mcpHooks?: CliMcpWireHooks;
+}
+/** Platform builtins derived from program config and runtime. */
+export interface CliCapabilities {
+	http: boolean;
+	completion: boolean;
+	mcp: boolean;
+	configure: boolean;
+	docs: boolean;
+	configCommands: boolean;
+}
+/** Outcome of a non-exiting CLI invocation. */
+export type CliInvokeKind = "ok" | "help" | "error";
+/** Result of Cli.invoke: captured output and exit metadata without process.exit. */
+export interface CliInvokeResult {
+	kind: CliInvokeKind;
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+	errorMsg?: string;
+	/** Classified failure for HTTP/MCP status mapping. */
+	failureKind?: InvokeFailureKind;
+	/** Headless response payload when invocation is `api` or `mcp` and the handler succeeded. */
+	response?: CliRespondOptions;
+}
+/** Argsbarg runtime for a validated, frozen {@link CliProgram}. */
+export declare class Cli {
+	readonly program: CliProgram;
+	readonly caps: CliCapabilities;
+	private readonly parseRootMerged;
+	private readonly presentationRoot;
+	private _appConfig?;
+	/** Active HTTP/MCP server handle (set during serve). */
+	server?: ServerHandleContext;
+	constructor(program: CliProgram);
+	get appConfig(): AnyAppConfigSnapshot;
+	exportCommandSchema(): CliSchemaRootExport;
+	exportAppConfigSchema(): Record<string, unknown> | undefined;
+	run(argv?: string[]): Promise<never>;
+	invoke(argv: string[], opts?: {
+		invocation?: CliInvocation;
+		toolArgs?: Record<string, unknown>;
+		requestId?: string;
+		http?: {
+			request: Request;
+			clientIp: string;
+			requestId: string;
+		};
+		mcp?: {
+			rpcMethod: string;
+			toolName?: string;
+			requestId: string;
+		};
+	}): Promise<CliInvokeResult>;
+	serveMcp(overrides?: ServeOverrides): Promise<never>;
+	serveHttp(overrides?: ServeOverrides): Promise<never>;
+	private ensureValidatedLeafInputs;
+	private exitLeafInputError;
+	private prepareDispatch;
+	private buildAppConfigSnapshot;
+}
+export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
 /** True when stdin is a TTY. */
 export declare const isInteractiveTty: boolean;