// Generated by dts-bundle-generator v9.5.1

export type ResolvedConfig = Record<string, unknown>;
declare class EmptyAppConfigSnapshot {
	private readonly program;
	private fileData;
	constructor(program: CliProgram, fileData?: Record<string, unknown>);
	get(_key: string): undefined;
	require(key: string): never;
	set(_key: string, _value: unknown): void;
	read(): ResolvedConfig;
	readUnsafe(): Record<string, unknown>;
	getUnsafe(key: string): unknown;
	setUnsafe(key: string, value: unknown): void;
	/** Resolved absolute path to the app JSON config file (OS default from `program.key`). */
	get path(): string;
	/** Resolved absolute directory containing the config file. */
	get dir(): string;
}
declare class AppConfigSnapshot {
	private readonly program;
	private snapshot;
	private fileData;
	constructor(program: CliProgram, fileData: Record<string, unknown>, resolved: ResolvedConfig);
	get(key: string): unknown;
	require(key: string): unknown;
	set(key: string, value: unknown): void;
	read(): ResolvedConfig;
	readUnsafe(): Record<string, unknown>;
	getUnsafe(key: string): unknown;
	setUnsafe(key: string, value: unknown): void;
	/** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
	get path(): string;
	/** Resolved absolute directory containing the config file. */
	get dir(): string;
	/** Replace snapshot after external bootstrap (internal). */
	refresh(fileData: Record<string, unknown>, resolved: ResolvedConfig): void;
	private persistFileData;
	private assertEntryKey;
	private assertUnsafeKey;
}
export type AnyAppConfigSnapshot = AppConfigSnapshot | EmptyAppConfigSnapshot;
/** Coerced leaf inputs keyed by option and positional names. */
export type CliLeafInputs = Record<string, boolean | number | string | string[] | unknown | undefined>;
/**
 * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
 */
export declare class CliContext {
	readonly appName: string;
	readonly commandPath: string[];
	args: string[];
	readonly program: CliProgram;
	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>, 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.
	 */
	respond(opts: CliRespondOptions): void;
	/** Returns the respond payload set by {@link respond}, if any. */
	getResponse(): CliRespondOptions | undefined;
	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
	hasFlag(name: string): boolean;
	/** Returns the string value for a string-valued option, if present. */
	stringOpt(name: string): string | undefined;
	/** Parses a stored string as a number; returns null if missing or not a strict double string. */
	numberOpt(name: string): number | null;
	/**
	 * Generic typed accessor: parses a stored string using the provided parse function.
	 * This is the TypeScript-native advantage over the Swift version.
	 */
	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
	/** Duration option in milliseconds (post-parse validated). */
	durationOpt(name: string): number | undefined;
	/** Comma-list option as a string array (post-parse validated). */
	commaListOpt(name: string): string[] | undefined;
	/** Date option as canonical YYYY-MM-DD (post-parse validated). */
	dateOpt(name: string): string | undefined;
	/** Date-time option as normalized ISO 8601 UTC (post-parse validated). */
	dateTimeOpt(name: string): string | undefined;
	/**
	 * Parsed Json option: `--name '<json>'`, preloaded piped stdin (when `pipable`), or MCP/API toolArgs.
	 * Flag wins over stdin and toolArgs.
	 */
	jsonOpt(name: string): unknown | undefined;
	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
	positional(name: string): string | string[] | undefined;
	/**
	 * Coerced option and positional values for the current leaf.
	 * When `leaf.inputSchema` is set, argsbarg validates before the handler runs; this returns the cached result.
	 */
	get inputs(): CliLeafInputs;
	/**
	 * {@link inputs} cast to a schemagen or app-defined input type (consumer-asserted; not inferred from `inputSchema`).
	 */
	inputsAs<T = CliLeafInputs>(): T;
	private _leafNode;
	private _posMap;
	private _positionalMap;
}
/** ECS version string written to every JSON log line. */
export declare const ECS_VERSION = "8.11.0";
/** Severity label for ECS `log.level`. */
export type EcsLogLevel = "debug" | "info" | "warn" | "error";
/** Fields merged into every ECS log line. */
export interface EcsServiceFields {
	name: string;
	version: string;
}
/** Context for {@link CliLogConfig.enrich} and {@link CliLogConfig.serialize}. */
export interface LogEnrichContext {
	level: EcsLogLevel;
	message: string;
	action?: string;
	requestId?: string;
	traceId?: string;
	spanId?: string;
	labels?: Record<string, string | number | boolean>;
	error?: unknown;
	service: EcsServiceFields;
	http?: {
		method: string;
		path: string;
		status: number;
		durationMs: number;
		clientIp?: string;
	};
}
/** 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>;
	requestId?: string;
	traceId?: string;
	spanId?: string;
	/** Populated on HTTP/MCP access log events for {@link CliLogConfig.enrich}. */
	http?: LogEnrichContext["http"];
}
/** Options for {@link formatEcsLine}. */
export interface FormatEcsLineOpts {
	service: EcsServiceFields;
	event: EcsLogEvent;
	/** Additive fields merged after the ECS baseline (cannot override protected keys). */
	enrich?: (ctx: LogEnrichContext) => Record<string, unknown>;
}
/** Formats one ECS Logging–compatible JSON log line (newline omitted). */
export declare function formatEcsLine(opts: FormatEcsLineOpts): string;
/** @deprecated Pass {@link FormatEcsLineOpts} instead. */
export declare function formatEcsLine(service: EcsServiceFields, event: EcsLogEvent): string;
/**
 * How a leaf handler was dispatched.
 */
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).
 */
export declare enum CliOptionKind {
	/** Boolean flag: no value token (may be implicit `"1"` when set). */
	Presence = "presence",
	/** Free-form string value. */
	String = "string",
	/** Strict floating-point value (parsed at validation time). */
	Number = "number",
	/** Fixed set of allowed string values. Requires non-empty `choices` on the option. */
	Enum = "enum",
	/** JSON object or array (parsed from `--name '<json>'`, piped stdin when `pipable`, or MCP/API tool body). */
	Json = "json"
}
/**
 * Named validation/coercion for string options (`format` on `CliOption`).
 * Positionals do not use `format`; varargs use space-separated CLI tokens and JSON arrays over MCP.
 */
export declare enum CliValueFormat {
	/** Duration text such as `30s`, `20m`, `1h`, `2d` (default unit minutes when omitted). */
	Duration = "duration",
	/** Comma-separated list on a single option value (`--services a,b`). */
	CommaList = "comma-list",
	/** Calendar date `YYYY-MM-DD`. */
	Date = "date",
	/** RFC 3339 instant with `Z` or numeric offset. */
	DateTime = "date-time"
}
/**
 * When `fallbackCommand` is used for missing or unknown subcommand tokens at a routing node.
 */
export declare enum CliFallbackMode {
	/**
	 * If argv has no next subcommand, route to `fallbackCommand`; if the token is unknown, error.
	 */
	MissingOnly = "missingOnly",
	/**
	 * If argv has no next subcommand or the token is not a known child, route to `fallbackCommand`.
	 */
	MissingOrUnknown = "missingOrUnknown",
	/**
	 * If the next token is present but not a known child, route to `fallbackCommand`.
	 * When the subcommand token is missing (exhausted argv), do not use fallback (implicit scoped help).
	 */
	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;
	/** 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. */
	kind: CliOptionKind;
	/** Short option character (e.g., 'n' for -n). */
	shortName?: string;
	/** Whether this option must be provided. Cannot be used with Presence kind. */
	required?: boolean;
	/**
	 * Allowed values. Required when kind === Enum; ignored otherwise.
	 * Must be a non-empty array of distinct non-empty strings.
	 */
	choices?: string[];
	/**
	 * Named string validation for `kind: String` options. Mutually exclusive with `pattern`.
	 * Not supported on positionals.
	 */
	format?: CliValueFormat;
	/** Default value applied in post-parse when the option is omitted. */
	default?: string;
	/** Regex pattern for string options. Mutually exclusive with `format`. */
	pattern?: string;
	/**
	 * When `true` on a `Json` option, CLI may omit `--name` and supply JSON via stdin instead.
	 * If `--name` is set, the flag value wins and stdin is not read.
	 */
	pipable?: boolean;
}
/**
 * An ordered positional argument slot, listed on leaf `positionals`.
 */
export interface CliPositional {
	/** Positional name (used in help and error messages). */
	name: string;
	/** Description shown in help. */
	description: string;
	/** Value kind for each consumed token. */
	kind: CliOptionKind;
	/**
	 * Minimum number of values required (default 1).
	 * Use `0` for an optional slot when paired with `argMax: 1`, or a varargs tail with `argMax: 0`.
	 */
	argMin?: number;
	/**
	 * Maximum number of values (`1` = a single required or optional word; default 1). Use `0` for an
	 * unbounded varargs tail (must be the last slot in the command’s `positionals` list).
	 */
	argMax?: number;
}
/** @experimental MCP bundle output options (program root `mcpServer.bundle` only). */
export interface CliMcpBundleConfig {
	author?: {
		name: string;
		email?: string;
		url?: string;
	};
	/** Human-readable display name for plugin manifests. */
	displayName?: string;
	/** Homepage URL for plugin manifests. */
	homepage?: string;
	/** Repo-relative path to a PNG icon copied into the bundle. */
	icon?: string;
	/** Software license identifier (e.g. "MIT", "Apache-2.0"). */
	license?: string;
	/** Manifest `long_description` (defaults to program description). */
	longDescription?: string;
	/** Repository URL for plugin manifests. */
	repository?: string;
	/** Custom relative path to repository skills directory (defaults to `skills/<dirName>`). */
	skillsDir?: string;
}
/**
 * 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. */
	claudePlugin?: boolean;
	/** When `true`, `mcp bundle` also writes `dist/cursor-plugin/<name>.zip`. Default false. */
	cursorPlugin?: boolean;
	/** Resource URI for schema export (default: `<sanitized root key>://schema`). */
	schemaResourceUri?: string;
	/**
	 * Capture the user's login shell environment at MCP server start and merge it
	 * into process.env. Solves missing PATH, nvm/rbenv shims, Homebrew binaries,
	 * and shell exports that MCP hosts (e.g. Cursor) don't inherit.
	 */
	shellEnv?: boolean | string;
	/**
	 * Custom MCP resources exposed alongside the built-in schema resource.
	 * URIs must be unique and must not equal schemaResourceUri.
	 */
	resources?: CliMcpResource[];
	/** 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;
	/** W3C trace id when `traceparent` is present on the request. */
	traceId?: string;
	/** Span id for this server hop when `traceparent` is present. */
	spanId?: 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 http` and the HTTP tool server (program root only).
 * Must include `enabled: true`; omit `httpServer` entirely to disable HTTP.
 */
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;
	/**
	 * URL prefix for user command routes (default: `""` — routes at server root, e.g. `/workspaces`).
	 * Set to `"/api"` for `/api/workspaces`-style paths.
	 */
	pathPrefix?: string;
	/** 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;
}
/** 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[];
/** Options for {@link CliContext.respond} and headless invoke results. */
export interface CliRespondOptions {
	body: CliRespondBody;
	/** Default: `application/json` for objects/arrays, `text/plain` for strings; binary requires explicit type. */
	contentType?: string;
	/** HTTP status (default: 200). */
	status?: number;
	headers?: Record<string, string>;
}
/**
 * A custom MCP resource exposed under resources/list and resources/read.
 */
export interface CliMcpResource {
	/** Resource URI (must be unique; must not equal schemaResourceUri). */
	uri: string;
	/** Short display name for resources/list. */
	name: string;
	/** Optional human description for resources/list. */
	description?: string;
	/** MIME type (default: "text/plain"). */
	mimeType?: string;
	/** Called at resources/read time; must return the resource body. */
	load: () => string;
}
/**
 * Leaf-only. Controls how this command appears as an MCP tool.
 */
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;
}
/** Context passed to {@link CliAppConfigEntry.resolve} for one config key. */
export interface CliAppConfigResolveContext {
	/** Schema key being resolved. */
	key: string;
	/** Entry metadata for this key. */
	entry: CliAppConfigEntry;
	/** Program root (read-only). */
	program: CliProgram;
	/** Raw value from the config file, if any. */
	fileValue: unknown;
	/** Non-empty host env string when `entry.env` is set; otherwise `undefined`. */
	envValue: string | undefined;
}
/**
 * Optional fallback resolver for one config key (e.g. `gh auth token` when `GH_TOKEN` is unset).
 * Return `undefined` to continue resolution (env, then default).
 */
export type CliAppConfigResolveFn = (ctx: CliAppConfigResolveContext) => unknown;
/**
 * Metadata overlay for one key in {@link CliAppConfig.entries}.
 * Types and validation come from {@link CliAppConfig.jsonSchema} when set; otherwise all values are strings.
 */
export interface CliAppConfigEntry {
	/** Help text for prompts, MCP manifests, and generated docs. */
	description: string;
	/** Short label in host UIs and CLI prompts. Default: the config key. */
	title?: string;
	/** Default when `jsonSchema` is omitted (all-string mode). */
	default?: string;
	/** When `false`, optional for bootstrap and MCP enforcement. Default: `true`. */
	required?: boolean;
	/**
	 * Mask stdin during prompts and redact on `configure get`.
	 * Default: `/key|token|secret|password/i.test(name)`.
	 */
	sensitive?: boolean;
	/** When set: non-empty `process.env[env]` overrides file; value exported after resolve. */
	env?: string;
	/**
	 * Optional fallback after file when env is empty.
	 * Return `undefined` to fall back to `env` (if set) and schema defaults.
	 */
	resolve?: CliAppConfigResolveFn;
}
/**
 * App configuration block on the program root ({@link CliProgram.appConfig}).
 */
export interface CliAppConfig {
	/** Built-in `configure get` / `configure set`. Default: enabled when `appConfig` is set. */
	commands?: boolean | {
		enabled?: boolean;
		mcpSet?: boolean;
	};
	/** Block JSON Schema (draft-07). When omitted, synthesize all-string schema from `entries`. */
	jsonSchema?: Record<string, unknown>;
	/** Per-key metadata; keys must match `jsonSchema.properties` when `jsonSchema` is set. */
	entries: Record<string, CliAppConfigEntry>;
}
/** Opt-out for the `completion` built-in (default: enabled). */
export interface CliCompletionConfig {
	/** When `false`, hide/disable `completion` (default: enabled). */
	enabled?: boolean;
}
/**
 * @deprecated Skill generation was removed; skills are authored directly in repositories under `skills/<app>/SKILL.md`.
 */
export interface CliSkillConfig {
	/** @deprecated Skill generation was removed; this property has no effect. */
	enabled?: boolean;
}
/** Context for {@link CliConfigureConfig} lifecycle hooks. */
export interface ConfigureHookContext {
	program: CliProgram;
	dry: boolean;
	paths: {
		agentsSkillDir: string;
		agentsMcpPath: string;
		mcpName: string;
		skillDirName: string;
	};
}
/** @experimental */
export interface CliConfigureConfig {
	/** When `false`, hide/disable `configure` (default: enabled). */
	enabled?: boolean;
	/** Per-artifact gates for configure install. See {@link resolveEffectiveInstallTargets}. */
	targets?: CliConfigureTargets;
	/** Runs after framework artifacts are installed (`configure install`). */
	afterInstall?: (ctx: ConfigureHookContext) => void | Promise<void>;
	/** Runs before framework artifacts are removed (`configure uninstall`). */
	beforeUninstall?: (ctx: ConfigureHookContext) => void | Promise<void>;
}
/** Boolean or structured gate for one install artifact. */
export type InstallTargetSpec = boolean | {
	/** When false, artifact is never installed (even with scoped CLI flags). Default true. */
	enabled?: boolean;
	/** When true, included in `configure install`. Default varies by key. */
	includedInAll?: boolean;
};
export interface ResolvedInstallTarget {
	enabled: boolean;
	includedInAll: boolean;
}
/** Per-artifact gates for configure. See {@link resolveEffectiveInstallTargets}. */
export interface CliConfigureTargets {
	/** App binary status only (Homebrew PATH); no self-install. */
	app?: InstallTargetSpec;
	/** App config: interactive wizard step in `configure`. Default not in refresh. */
	configure?: InstallTargetSpec;
}
/**
 * One bundled documentation topic for the `docs` built-in (program root only).
 */
export interface CliDocsTopic {
	/** Bundled markdown (use compile-time text imports in the consumer). */
	text: string;
	/** Leaf help text for `myapp docs <key> -h`. Auto-generated from key when omitted. */
	description?: string;
}
/**
 * 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 `false`, hide/disable `docs` (default: enabled). */
	enabled?: boolean;
	/** Router description for `myapp docs` (default: "Print bundled CLI documentation."). */
	description?: string;
	/** 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.
 */
export interface CliNodeBase {
	/** Program or command key (e.g., "myapp", "stat", "owner"). */
	key: string;
	/** 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). */
	notes?: string;
	/** Global or command-level flags/options. */
	options?: CliOption[];
}
/** Leaf input mode: `document` (or legacy `json`) = structured JSON or YAML document body (no CLI flags). */
export type CliLeafKind = "document" | "json";
/**
 * A leaf command node with a handler and optional positionals.
 */
export type CliLeaf = CliNodeBase & {
	/**
	 * When `"document"` (or legacy `"json"`), the leaf accepts a single JSON or YAML document
	 * (CLI positional or piped stdin; MCP/HTTP tool args = body). Requires `inputSchema`;
	 * forbids `options` and `positionals`.
	 */
	kind?: CliLeafKind;
	/** Handler function for leaf commands. */
	handler: CliHandler;
	/** Positional argument definitions. */
	positionals?: CliPositional[];
	/**
	 * JSON Schema for structured stdout (e.g. with `--json` or MCP when the handler emits JSON).
	 * 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>;
	/** Per-tool MCP exposure and metadata. */
	mcpTool?: CliMcpToolConfig;
};
/**
 * A routing command node with nested subcommands.
 */
export type CliRouter = CliNodeBase & {
	/** Nested subcommands. */
	commands: CliNode[];
	/** Default subcommand when argv omits a command or uses an unknown token at this routing node. */
	fallbackCommand?: string;
	/** How fallbackCommand is applied at this routing node. */
	fallbackMode?: CliFallbackMode;
};
/**
 * 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;
		traceId?: string;
		spanId?: 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 Logging json or human text on stderr). */
export interface CliLogConfig {
	/** `json` = ECS Logging 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;
	/**
	 * Add non-standard fields to each JSON log line after the ECS baseline.
	 * Cannot override `@timestamp`, `log.level`, `message`, `ecs.version`, or service fields.
	 */
	enrich?: (ctx: LogEnrichContext) => Record<string, unknown>;
	/**
	 * Full control over JSON log line serialization. When set, bypasses the built-in ECS formatter.
	 * The consumer owns the entire line (including newline omission).
	 */
	serialize?: (ctx: LogEnrichContext) => string;
}
/**
 * Program root passed to {@link Cli}.
 * May be a leaf or router, plus optional program-level MCP and install config.
 */
export type CliProgram = CliNode & {
	/** Schema-driven app config file, bootstrap, and MCP metadata. */
	appConfig?: CliAppConfig;
	/** Opt-out for shell completion generation (`completion bash|zsh|fish`). */
	completion?: CliCompletionConfig;
	/** Opt-out and defaults for `configure`. */
	configure?: CliConfigureConfig;
	/** 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;
	/** When set with `enabled: true`, enables the `http` built-in HTTP server. */
	httpServer?: CliHttpServerConfig;
	/** Framework logging (stderr + optional file). */
	log?: CliLogConfig;
	/** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
	mcpServer?: CliMcpServerConfig;
	/** Optional readiness probe for HTTP/MCP `GET /health/readiness` only. */
	readiness?: (ctx: ReadinessContext) => boolean | Promise<boolean>;
	/** @deprecated Skill generation was removed; skills are authored directly in repositories under `skills/<app>/SKILL.md`. */
	skill?: CliSkillConfig;
	/** Program version (printed by the `version` built-in and MCP serverInfo). */
	version: string;
};
/** True when the leaf accepts a structured JSON or YAML document body (no CLI flags). */
export declare function isDocumentLeaf(
/** Leaf command node to inspect. */
leaf: CliLeaf): boolean;
/** True when the leaf accepts a structured document body (backward-compatible alias for `isDocumentLeaf`). */
export declare function isJsonLeaf(
/** Leaf command node to inspect. */
leaf: CliLeaf): boolean;
/**
 * Handler closure type for leaf commands.
 * Supports sync and async handlers; non-undefined return values become implicit JSON responses for headless invocations.
 */
export type CliHandler = (ctx: CliContext) => unknown | Promise<unknown>;
/**
 * Error thrown when the static CLI tree violates ArgsBarg rules.
 */
export declare class CliSchemaValidationError extends Error {
	/** Creates a schema validation error with a human-readable rule violation. */
	constructor(message: string);
}
/** 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. */
export declare function parseCommaList(s: string): string[];
/** Returns canonical YYYY-MM-DD after validation. */
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);
}
/** Parses a JSON or YAML string from a command argument or document body. */
export declare function parseDocumentText(
/** Raw text containing a JSON or YAML document. */
raw: string, 
/** Field or argument label for error reporting. */
label: string): unknown;
/** 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>>;
/**
 * Filters leaf-local options to only those exposed over wire protocols (MCP, OpenAPI, CLI schema export).
 * Omits hidden options and framework-handled presence flags (`--json`, `--yes`, `--verbose`).
 */
export declare function leafWireOptions(
/** Leaf command node to extract wire options from. */
leaf: CliLeaf): CliOption[];
/**
 * Builds the canonical input JSON Schema for a leaf command.
 * Returns `leaf.inputSchema` when explicitly defined (e.g. on document leaves or schemagen leaves);
 * otherwise synthesizes a flat object schema from leaf-local wire options and positionals.
 */
export declare function buildLeafInputSchema(
/** Leaf command node to build the input schema for. */
leaf: CliLeaf): 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. */
export declare function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean;
/**
 * Headless when MCP, `--json`, `--dry-run`, or stdin is not a TTY.
 * Use for commands that should auto-emit JSON in pipelines.
 */
export declare function shouldRunHeadless(ctx: HeadlessContext, hasJsonFlag: boolean, hasDryRunFlag?: boolean, interactive?: boolean): boolean;
/**
 * Like {@link shouldRunHeadless}, but only auto-headless in non-TTY when positionals are present.
 * Avoids turning empty invocations into JSON errors.
 */
export declare function shouldRunHeadlessWithPositionals(ctx: HeadlessContext, hasJsonFlag: boolean, positionals: string[], hasDryRunFlag?: boolean, interactive?: boolean): boolean;
/**
 * Headless when MCP, `--dry-run` with required args, or non-TTY with `--yes` and required args.
 * Use for mutating commands that require explicit `--yes` in scripts.
 */
export declare function shouldRunHeadlessWithYes(ctx: HeadlessContext, opts: {
	yes: boolean;
	hasRequiredArgs: boolean;
	dryRun?: boolean;
}, interactive?: boolean): boolean;
/** Exits when non-interactive mode is used without `--yes`. */
export declare function requireYesInNonTty(
/** True when `--yes` was passed on the command line. */
yes: boolean, 
/** Command-specific guidance appended to the error message. */
hint: string, 
/** When true, skip the check (dry-run preview). */
dryRun?: boolean, 
/** Injectable TTY probe for tests. */
interactive?: boolean): void;
/** Prefixes a success message when running in dry-run mode. */
export declare function formatDryRunMessage(message: string, dryRun: boolean): string;
/** 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;
	outPath: string;
	binaryName: string;
}
/** Default `dist/<key>` binary and `dist/<key>.mcpb` output under cwd. */
export declare function defaultMcpBundlePaths(program: CliProgram, cwd?: string): McpBundlePaths;
/** Generates MCPB `manifest.json` object from program schema and MCP tools. */
export declare function generateMcpManifest(program: CliProgram, binaryName: string): Record<string, unknown>;
export interface PackMcpBundleOpts {
	cwd?: string;
	binaryPath?: string;
	outPath?: string;
}
/**
 * Stages manifest + binary (+ optional icon) and writes a `.mcpb` ZIP.
 * Requires the compiled binary to exist.
 */
export declare function packMcpBundle(program: CliProgram, opts?: PackMcpBundleOpts): string;
/**
 * Resolves the user home directory without depending on `$HOME`.
 * This is helpful for when homebrew post-install hooks run with a temporary `$HOME`.
 */
export declare function userHome(): string;
/** JSON-safe command node (no handlers). */
export interface CliSchemaExport {
	key: string;
	description: string;
	notes?: string;
	/** JSON Schema for input arguments (options, positionals, or document body) when on a leaf. */
	inputSchema?: Record<string, unknown>;
	/** 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>;
}
/** Resolved logging options for a server or invoke session. */
export interface ResolvedLogConfig {
	format: "json" | "text";
	file?: string;
	access: boolean;
	errors: boolean;
	dev: boolean;
	enrich?: CliLogConfig["enrich"];
	serialize?: CliLogConfig["serialize"];
}
/** 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;
		traceId?: string;
		spanId?: string;
	}): void;
	/** Error log after the hook pipeline (real stack always included). */
	emitInvokeError(failureKind: string, error: unknown, clientMessage: string, meta?: {
		labels?: Record<string, string | number | boolean>;
		requestId?: string;
		traceId?: string;
		spanId?: string;
	}): void;
	private formatLine;
	private buildEnrichContext;
	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;
			traceId?: string;
			spanId?: 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;

export {};