@happyvertical/smrt-app-cli 0.51.32 → 0.51.34

package/dist/index.d.ts

@@ -1,585 +1,98 @@
-import { Server } from '@modelcontextprotocol/server';
-import { Writable } from 'node:stream';
-
-declare type ApiHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-
-export declare interface AppCli {
-    run(argv: string[]): Promise<void>;
-    /**
-     * Wire up the stdio MCP bridge and connect to stdin/stdout. The CLI
-     * advertises itself to local MCP clients as `serverInfo.name` /
-     * `.version`. Both fields default from `options.name` (so a brand-
-     * new app gets `{ name: '<name>-mcp', version: '0.0.0' }`) — pass an
-     * explicit object to override.
-     */
-    startMcpBridge(serverInfo?: {
-        name?: string;
-        version?: string;
-    }): Promise<void>;
-}
-
-export declare interface AppCliCommand {
-    name: string;
-    description: string;
-    /**
-     * When true, the CLI ensures resources are fetched and available via
-     * `ctx.getResources()` before `run()` is called. Default `false`.
-     */
-    needsResources?: boolean;
-    run(args: string[], ctx: AppCliContext): Promise<void>;
-}
-
-export declare interface AppCliContext {
-    config: CliConfig;
-    serverUrl: string;
-    token?: string;
-    /** Lazy resource-list fetch. Cached for the duration of the CLI invocation. */
-    getResources(): Promise<ResourceListResponse>;
-    /** Issue a JSON request via the shared client. */
-    requestJson<T = unknown>(path: string, init?: RequestInit, options?: RequestJsonOptions): Promise<T>;
-    /** Issue a raw fetch (for streaming / content-type-aware responses). */
-    request(path: string, init?: RequestInit): Promise<Response>;
-    stdout: NodeJS.WriteStream;
-    stderr: NodeJS.WriteStream;
-}
-
-export declare interface AppCliExecutableConfig {
-    cliOptions: Pick<CreateAppCliOptions, 'name' | 'envPrefix' | 'configDir' | 'defaultServerUrl' | 'requireSecureServerUrl'>;
-    argv: string[];
-    mcp?: {
-        name: string;
-        version: string;
-    };
-    stdioMcp: boolean;
-}
-
-/** Error compatibility wrapper returned by the legacy throwing helper. */
-export declare class AppCliRequestError extends Error {
-    readonly status: number;
-    readonly metadata: AppCliResultMetadata;
-    constructor(status: number, metadata: AppCliResultMetadata);
-}
-
-/** Structured metadata preserved for CLI JSON and MCP bridge consumers. */
-export declare type AppCliResultMetadata = AppResultMetadata;
-
-declare interface AppResultContract {
-    schema: typeof SMRT_APP_RESULT_SCHEMA;
-    version: typeof SMRT_APP_RESULT_VERSION;
-    mcpMetadataKey: typeof SMRT_MCP_RESULT_METADATA_KEY;
-    metadataFields: readonly [
-    'code',
-    'message',
-    'details',
-    'retryable',
-    'correlationId',
-    'idempotencyKey',
-    'expectedVersion'
-    ];
-}
-
-/** Machine-readable metadata shared by HTTP CLI and MCP bridge results. */
-declare interface AppResultMetadata {
-    code: string;
-    message?: string;
-    details?: JsonValue;
-    retryable?: boolean;
-    correlationId?: string;
-    idempotencyKey?: DeclaredActionField;
-    expectedVersion?: DeclaredActionField;
-}
-
-/** Enforce the executable-safe server URL policy without echoing URL values. */
-export declare function assertSecureServerUrl(value: string): void;
-
-export declare function buildFlagParser(schema: Record<string, unknown> | undefined, options?: ParserOptions): BuildParserResult;
-
-export declare interface BuildParserResult {
-    /** Parses argv tail (everything after `<cli> <slug> <cmd> [id]`). */
-    parse(argv: string[], httpMethod: string): ParsedArgs;
-    /** Status of the underlying schema. */
-    status: SchemaSupportStatus;
-}
-
-/**
- * Build only the URL — exposed for tests.
- */
-export declare function buildUrl(context: CliConfigContext, resource: CliResource, command: CommandDefinition, parsed: ParsedArgs, id?: string): Promise<string>;
-
-/**
- * Classify a JSONSchema. The CLI uses this to decide between rich flag
- * parsing and the positional JSON escape hatch.
- */
-export declare function classifySchema(schema: Record<string, unknown> | undefined): SchemaSupportStatus;
-
-/** Remove the token from the config file (e.g. on logout). */
-export declare function clearStoredToken(context: CliConfigContext): Promise<void>;
-
-/** Shape stored on disk in the app's CLI config file. */
-export declare interface CliConfig {
-    /** Issuer selected for the currently configured server. */
-    credentialIssuer?: string;
-    serverUrl?: string;
-    /** Legacy single-token field. Read only when its stored server still matches. */
-    token?: string;
-    /** Bearer credentials keyed by their exact issuer identifier. */
-    tokensByIssuer?: Record<string, string>;
-}
-
-/**
- * Configuration for the env-var/config-file resolution chain.
- *
- * Env vars derived from `envPrefix`:
- *
- *  - `${PREFIX}_SERVER_URL`
- *  - `${PREFIX}_TOKEN`
- *  - `${PREFIX}_CLI_CONFIG` (overrides config file path)
- */
-export declare interface CliConfigContext {
-    /**
-     * Uppercase prefix for env vars and the app's namespaced config dir.
-     * Example: `WILLGRIFFIN` → reads `WILLGRIFFIN_SERVER_URL`, defaults the
-     * config file to `~/.config/willgriffin/config.json` unless `appSlug`
-     * overrides the directory name.
-     */
-    envPrefix: string;
-    /** Directory name under `~/.config`. Defaults to lowercased `envPrefix`. */
-    appSlug?: string;
-    /** Fallback server URL if neither env nor config sets one. */
-    defaultServerUrl?: string;
-    /**
-     * Require HTTPS for every resolved or request-level server URL, while still
-     * permitting loopback HTTP for local development.
-     */
-    requireSecureServerUrl?: boolean;
-}
-
-export declare type CliResource = CliResource_2;
-
-declare interface CliResource_2 {
-    /** Kebab-case identifier; the first positional argument after the CLI name. */
-    slug: string;
-    className: string;
-    qualifiedName?: string;
-    packageName?: string;
-    label: string;
-    /** Collection segment, no leading slash, no `/api` prefix. */
-    apiPath: string;
-    commands: CommandDefinition_2[];
-}
-
-export declare type CommandDefinition = CommandDefinition_2;
-
-declare interface CommandDefinition_2 {
-    /** Method name in source casing — source of truth for HTTP routing. */
-    methodName: string;
-    /** Kebab-case identifier used by the CLI argv parser. */
-    commandName: string;
-    kind: CommandKind_2;
-    scope: CommandScope_2;
-    httpMethod: ApiHttpMethod;
-    /** URL path segments after `/<apiPath>[/<id>]/`. May be empty. */
-    pathSegments: string[];
-    description?: string;
-    /** JSONSchema describing the command's argv-flag surface. */
-    parameters?: Record<string, unknown>;
-    /** Retry and optimistic-concurrency fields declared by the action schema. */
-    requirements?: CommandRequirements;
-}
-
-export declare type CommandKind = CommandKind_2;
-
-declare type CommandKind_2 = 'crud' | 'custom';
-
-/** Retry and concurrency declarations projected from a command schema. */
-declare interface CommandRequirements {
-    idempotencyKey?: DeclaredActionField;
-    expectedVersion?: DeclaredActionField;
-}
-
-export declare type CommandScope = CommandScope_2;
-
-declare type CommandScope_2 = 'item' | 'collection';
-
-export declare function createAppCli(options: CreateAppCliOptions): AppCli;
-
-export declare interface CreateAppCliOptions {
-    /** Display + branding name, e.g. `willgriffin`. Also drives `envPrefix`. */
-    name: string;
-    /** Override the env-var prefix. Default: `name.toUpperCase()`. */
-    envPrefix?: string;
-    /** Override the config dir slug. Default: `name.toLowerCase()`. */
-    configDir?: string;
-    /** Baked-in default server URL when neither env nor config sets one. */
-    defaultServerUrl?: string;
-    /** Enforce HTTPS or loopback HTTP for every effective server URL. */
-    requireSecureServerUrl?: boolean;
-    /**
-     * App-specific commands. Dispatched BEFORE built-ins (`auth`,
-     * `resources`, `mcp`) and before the resource-slug dispatcher, so an
-     * `extraCommands` entry takes precedence over anything with the same
-     * top-level argv.
-     *
-     * - **Built-in shadowing** (`extraCommands: [{ name: 'mcp' }]`): the CLI
-     *   prints a one-line stderr warning on first invocation. The extra
-     *   command still wins, but the warning makes the override visible.
-     *
-     * - **Resource-slug shadowing** (`extraCommands: [{ name: 'praecos' }]`
-     *   when a server-side class also resolves to slug `praecos`): the
-     *   extra command silently wins. There's no warning because checking
-     *   would require a discovery round-trip on every invocation. Authors
-     *   are responsible for namespacing their extra commands (e.g. prefix
-     *   with the app name) to avoid accidental shadowing as the server's
-     *   class registry grows. (#1311 review C-2.)
-     */
-    extraCommands?: AppCliCommand[];
-}
-
-/** Build and validate the document hosted at an HTTPS URL used as client_id. */
-export declare function createMcpClientIdMetadataDocument(options: McpClientRegistrationOptions): McpClientIdMetadataDocument;
-
-/**
- * Wire up the stdio server. Use `runMcpStdioBridge` for a one-call entry
- * point in `bin/` scripts; this lower-level form is exposed for tests.
- */
-export declare function createMcpStdioBridge(options: McpStdioBridgeOptions): {
-    server: Server;
-    connect: () => Promise<void>;
-};
-
-/** A declared input field which controls retry or optimistic-concurrency use. */
-declare interface DeclaredActionField {
-    /** JSON Schema property name supplied by the action. */
-    field: string;
-    /** Whether the action marks the field required. */
-    required: boolean;
-}
-
-declare interface DiscoveryArtifactIntegrity {
-    algorithm: 'sha256';
-    /** `sha256:<lowercase-hex>` over canonical unsigned artifact JSON. */
-    digest: string;
-}
-
-/** Versioned payload a consumer can validate and pin. */
-declare interface DiscoveryConformanceArtifact {
-    schema: typeof SMRT_DISCOVERY_CONFORMANCE_SCHEMA;
-    version: typeof SMRT_DISCOVERY_CONFORMANCE_VERSION;
-    discovery: DiscoveryPayload;
-    resultContract: AppResultContract;
-    integrity: DiscoveryArtifactIntegrity;
-}
-
-/** The pre-artifact wire payload, kept for the existing `/_resources` fields. */
-declare type DiscoveryPayload = Omit<ResourceListResponseBody, 'artifact'>;
-
-/**
- * Fetch the discovery payload.
- *
- * Translates a 401 into a friendlier error so the CLI can prompt the
- * user to log in rather than dumping a raw HTTP error.
- */
-export declare function fetchResourceList(context: CliConfigContext, options?: FetchResourceListOptions): Promise<ResourceListResponse>;
-
-declare interface FetchResourceListOptions {
-    /** Endpoint path on the server. Default `/api/_resources`. */
-    path?: string;
-    /** Custom fetch (tests). */
-    fetch?: typeof fetch;
-    /** When true, the request fails if no token is available. */
-    requireAuth?: boolean;
-    /**
-     * Pre-loaded config to avoid re-reading from disk. Set by
-     * `buildAppContext`, which has already loaded it. (#1311 review P2.)
-     */
-    loadedConfig?: CliConfig;
-}
-
-/**
- * Find a command on a resource by its CLI-facing name. Returns
- * `undefined` if not found.
- */
-export declare function findCommand(resource: CliResource, commandName: string): CommandDefinition | undefined;
-
-/**
- * Find a resource by slug in the discovery payload. Returns `undefined`
- * if the slug isn't present.
- */
-export declare function findResourceBySlug(response: ResourceListResponse, slug: string): CliResource | undefined;
-
-/** Resolve the server URL: env var → config file → `defaultServerUrl`. */
-export declare function getServerUrl(context: CliConfigContext, config?: CliConfig): Promise<string>;
-
-/** Resolve a bearer token only when it is bound to the exact target server. */
-export declare function getStoredToken(context: CliConfigContext, config?: CliConfig, serverUrl?: string): Promise<string | undefined>;
-
-/**
- * Build the URL the CLI should hit for this command, plus the fetch init
- * (headers, body) it should pass. Returns enough so callers can stream
- * the response — they decide how to render it (see `output.ts`).
- */
-export declare function invokeCommand(options: InvokeOptions): Promise<Response>;
-
-declare interface InvokeOptions {
-    context: CliConfigContext;
-    resource: CliResource;
-    command: CommandDefinition;
-    parsed: ParsedArgs;
-    /** Positional `<id>` argument — only meaningful for item-scope commands. */
-    id?: string;
-    /** Custom fetch (tests). */
-    fetch?: typeof fetch;
-}
-
-/** JSON-safe value used by structured details and parameter schemas. */
-declare type JsonValue = null | boolean | number | string | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-
-/** Read the CLI config file. Missing file → empty config. */
-export declare function loadCliConfig(context: CliConfigContext): Promise<CliConfig>;
-
-export declare interface McpClientIdMetadataDocument {
-    application_type: OAuthApplicationType;
-    client_id: string;
-    client_name: string;
-    grant_types: ['authorization_code'];
-    redirect_uris: string[];
-    response_types: ['code'];
-    token_endpoint_auth_method: 'none';
-}
-
-export declare type McpClientRegistration = {
-    clientId: string;
-    kind: 'client_id_metadata_document';
-    metadataDocument: McpClientIdMetadataDocument;
-} | {
-    endpoint: string;
-    kind: 'dynamic_client_registration';
-    request: Omit<McpClientIdMetadataDocument, 'client_id'>;
-};
-
-export declare interface McpClientRegistrationOptions {
-    applicationType: OAuthApplicationType;
-    /** HTTPS metadata-document URL. Required only when CIMD is advertised. */
-    clientId?: string;
-    clientName: string;
-    redirectUris: string[];
-}
-
-export declare interface McpRegisteredClient {
-    clientId: string;
-    kind: McpClientRegistration['kind'];
-    metadataDocument?: McpClientIdMetadataDocument;
-    registrationResponse?: Record<string, unknown>;
-}
-
-/**
- * Configuration for the bridge.
- *
- * Combines the {@link CliConfigContext} (env var + config file resolution)
- * with the local MCP server identity the bridge advertises to clients.
- */
-export declare interface McpStdioBridgeOptions extends CliConfigContext {
-    /** MCP server identity advertised to local clients. */
-    serverInfo: {
-        name: string;
-        version: string;
-    };
-    /** Override the tools endpoint path. Defaults to `/api/mcp/tools`. */
-    toolsPath?: string;
-    /** Override the call endpoint path. Defaults to `/api/mcp/call`. */
-    callPath?: string;
-    /**
-     * Override fetch implementation (used by tests so we never hit the network).
-     */
-    fetch?: typeof fetch;
-}
-
-/** MCP OAuth client-registration helpers for remote HTTP deployments. */
-export declare type OAuthApplicationType = 'native' | 'web';
-
-export declare interface OAuthAuthorizationServerMetadata {
-    client_id_metadata_document_supported?: boolean;
-    registration_endpoint?: string;
-}
-
-declare interface OutputOptions {
-    stdout?: NodeJS.WriteStream | Writable;
-    stderr?: NodeJS.WriteStream | Writable;
-    /**
-     * Override the TTY detection (tests). Defaults to `stdout.isTTY`.
-     */
-    stdoutIsTty?: boolean;
-}
-
-/** Parse and validate the generic executable's non-secret configuration. */
-export declare function parseAppCliExecutableConfig(argv: string[], env?: NodeJS.ProcessEnv): AppCliExecutableConfig;
-
-export declare interface ParsedArgs {
-    /** Body to send (JSON serialised, for POST/PUT/PATCH). May be empty. */
-    body: Record<string, unknown>;
-    /** Query string parameters (for GET). May be empty. */
-    query: Record<string, string | string[]>;
-    /** True when the user passed a positional `'<json>'` payload — body is that. */
-    fromPositional: boolean;
-}
-
-declare interface ParserOptions {
-    /** Force-treat schema as unsupported (caller already detected unsupportedness). */
-    positionalOnly?: boolean;
-}
-
-/** Redact conventional credential fields before emitting transport metadata. */
-export declare function redactTransportValue(value: unknown): unknown;
-
-/**
- * Complete client registration against discovered authorization-server
- * metadata. A Client ID Metadata Document needs no registration request: the
- * authorization server retrieves it from the HTTPS client_id. The legacy DCR
- * fallback is executed as an RFC 7591 JSON POST.
- */
-export declare function registerMcpClient(authorizationServer: OAuthAuthorizationServerMetadata, options: McpClientRegistrationOptions, fetchImpl?: typeof fetch): Promise<McpRegisteredClient>;
-
-/**
- * Render the response. Returns the desired exit code.
- */
-export declare function renderResponse(response: Response, options?: OutputOptions): Promise<RenderResult>;
-
-export declare interface RenderResult {
-    exitCode: number;
-}
-
-/**
- * JSON request helper that injects the stored bearer token. Returns the
- * parsed JSON body on success; throws an `Error` with the server's `error`
- * field (or `HTTP <status>`) on failure.
- */
-export declare function requestJson<T = unknown>(context: CliConfigContext, path: string, init?: RequestInit, options?: RequestJsonOptions): Promise<T>;
-
-declare interface RequestJsonFailure {
-    ok: false;
-    status: number;
-    error: AppCliResultMetadata;
-}
-
-/** Options for `requestJson`. */
-export declare interface RequestJsonOptions {
-    /**
-     * When false, skip sending the Authorization header even if a token is
-     * present. Defaults to true.
-     */
-    auth?: boolean;
-    /**
-     * When true, throw if no token is available and `auth` is not false.
-     * Defaults to false.
-     */
-    requireAuth?: boolean;
-    /** Override the server URL for this request. */
-    serverUrl?: string;
-    /** Override the fetch implementation (tests). */
-    fetch?: typeof fetch;
-    /**
-     * Cap on response body size in bytes. The CLI buffers the full body
-     * before JSON-parsing, so without this cap a misbehaving or malicious
-     * server could OOM the CLI process with a multi-GB payload (auth and
-     * discovery both use this code path). Defaults to 10MB — large enough
-     * for any sensible discovery response, small enough that overflow is
-     * a clear signal something's wrong. Pass `Infinity` to disable.
-     * (#1311 review A4.)
-     */
-    maxResponseBytes?: number;
-    /**
-     * Pre-loaded config to avoid re-reading from disk. Set by callers that
-     * already have it (e.g. `buildAppContext`); leave undefined for the
-     * default behavior of loading per-call. (#1311 review P2.)
-     */
-    loadedConfig?: CliConfig;
-}
-
-/** Generic result/error envelope for a JSON request. */
-export declare type RequestJsonResult<T> = RequestJsonSuccess<T> | RequestJsonFailure;
-
-/**
- * Issue a JSON request without flattening a failure to an Error message.
- *
- * Metadata is deliberately copied only from conventional result/error fields
- * and response headers. Every value crossing this boundary is redacted before
- * a CLI or MCP client can observe it.
- */
-export declare function requestJsonResult<T = unknown>(context: CliConfigContext, path: string, init?: RequestInit, options?: RequestJsonOptions): Promise<RequestJsonResult<T>>;
-
-declare interface RequestJsonSuccess<T> {
-    ok: true;
-    result: T;
-    metadata: AppCliResultMetadata;
-}
-
-/**
- * Select registration in MCP priority order: Client ID Metadata Documents
- * first, then RFC 7591 DCR as a compatibility fallback.
- */
-export declare function resolveMcpClientRegistration(authorizationServer: OAuthAuthorizationServerMetadata, options: McpClientRegistrationOptions): McpClientRegistration;
-
-export declare type ResourceListResponse = ResourceListResponseBody;
-
-declare interface ResourceListResponseBody {
-    user: {
-        authenticated: boolean;
-        id?: string;
-    };
-    warnings: string[];
-    resources: CliResource_2[];
-    /** Versioned deterministic artifact for consumers that integrity-pin discovery. */
-    artifact?: DiscoveryConformanceArtifact;
-}
-
-/** Create the canonical app CLI and execute its forwarded command or bridge. */
-export declare function runAppCliExecutable(options?: RunAppCliExecutableOptions): Promise<void>;
-
-export declare interface RunAppCliExecutableOptions {
-    argv?: string[];
-    env?: NodeJS.ProcessEnv;
-    createCli?: (options: CreateAppCliOptions) => AppCli;
-}
-
-/**
- * One-call entry point — start the factory-owned stdio bridge. The returned
- * promise resolves once the stdio listener is installed.
- */
-export declare function runMcpStdioBridge(options: McpStdioBridgeOptions): Promise<void>;
-
-/** Persist a login with the bearer token keyed by its exact issuer. */
-export declare function saveAuth(context: CliConfigContext, serverUrl: string, token: string, issuer?: string): Promise<void>;
-
-/**
- * Write the CLI config to disk with 0600 permissions (the token is a bearer
- * credential — anyone who can read the file can impersonate the user).
- */
-export declare function saveCliConfig(context: CliConfigContext, config: CliConfig): Promise<void>;
-
-export declare type SchemaSupportStatus = {
-    kind: 'ok';
-} | {
-    kind: 'unsupported';
-    reason: string;
-} | {
-    kind: 'missing';
-};
-
-/** Versioned selector for structured application results and errors. */
-declare const SMRT_APP_RESULT_SCHEMA = "https://smrt.dev/schemas/app-result/v1";
-
-/** Version of the structured application result contract. */
-declare const SMRT_APP_RESULT_VERSION: 1;
-
-/** Immutable selector for this discovery artifact family. */
-declare const SMRT_DISCOVERY_CONFORMANCE_SCHEMA = "https://smrt.dev/schemas/discovery-conformance/v1";
-
-/** Version of the discovery artifact payload. */
-declare const SMRT_DISCOVERY_CONFORMANCE_VERSION: 1;
-
-/** MCP result `_meta` member carrying the app-result metadata. */
-export declare const SMRT_MCP_RESULT_METADATA_KEY = "io.happyvertical/smrt";
-
-export { }
+/**
+ * `@happyvertical/smrt-app-cli` — reusable CLI factory for SMRT apps.
+ *
+ * @example
+ * ```ts
+ * #!/usr/bin/env node
+ * import { createAppCli } from '@happyvertical/smrt-app-cli';
+ *
+ * const cli = createAppCli({
+ *   name: 'willgriffin',
+ *   defaultServerUrl: 'https://willgriffin.dev',
+ * });
+ * await cli.run(process.argv.slice(2));
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { type CliConfig, type RequestJsonOptions } from './config.js';
+export { AppCliRequestError, type AppCliResultMetadata, assertSecureServerUrl, type CliConfig, type CliConfigContext, clearStoredToken, getServerUrl, getStoredToken, loadCliConfig, type RequestJsonOptions, type RequestJsonResult, redactTransportValue, requestJson, requestJsonResult, saveAuth, saveCliConfig, } from './config.js';
+import { type ResourceListResponse } from './discovery.js';
+export { type CliResource, type CommandDefinition, type CommandKind, type CommandScope, fetchResourceList, findCommand, findResourceBySlug, type ResourceListResponse, } from './discovery.js';
+export { buildUrl, invokeCommand } from './invoke.js';
+export { createMcpClientIdMetadataDocument, type McpClientIdMetadataDocument, type McpClientRegistration, type McpClientRegistrationOptions, type McpRegisteredClient, type OAuthApplicationType, type OAuthAuthorizationServerMetadata, registerMcpClient, resolveMcpClientRegistration, } from './mcp-oauth.js';
+export { type RenderResult, renderResponse } from './output.js';
+export { type BuildParserResult, buildFlagParser, classifySchema, type ParsedArgs, type SchemaSupportStatus, } from './parser.js';
+export { SMRT_MCP_RESULT_METADATA_KEY } from '@happyvertical/smrt-users/app-contract';
+export { createMcpStdioBridge, type McpStdioBridgeOptions, runMcpStdioBridge, } from './bridge.js';
+export { type AppCliExecutableConfig, parseAppCliExecutableConfig, type RunAppCliExecutableOptions, runAppCliExecutable, } from './executable.js';
+export interface AppCliCommand {
+    name: string;
+    description: string;
+    /**
+     * When true, the CLI ensures resources are fetched and available via
+     * `ctx.getResources()` before `run()` is called. Default `false`.
+     */
+    needsResources?: boolean;
+    run(args: string[], ctx: AppCliContext): Promise<void>;
+}
+export interface AppCliContext {
+    config: CliConfig;
+    serverUrl: string;
+    token?: string;
+    /** Lazy resource-list fetch. Cached for the duration of the CLI invocation. */
+    getResources(): Promise<ResourceListResponse>;
+    /** Issue a JSON request via the shared client. */
+    requestJson<T = unknown>(path: string, init?: RequestInit, options?: RequestJsonOptions): Promise<T>;
+    /** Issue a raw fetch (for streaming / content-type-aware responses). */
+    request(path: string, init?: RequestInit): Promise<Response>;
+    stdout: NodeJS.WriteStream;
+    stderr: NodeJS.WriteStream;
+}
+export interface CreateAppCliOptions {
+    /** Display + branding name, e.g. `willgriffin`. Also drives `envPrefix`. */
+    name: string;
+    /** Override the env-var prefix. Default: `name.toUpperCase()`. */
+    envPrefix?: string;
+    /** Override the config dir slug. Default: `name.toLowerCase()`. */
+    configDir?: string;
+    /** Baked-in default server URL when neither env nor config sets one. */
+    defaultServerUrl?: string;
+    /** Enforce HTTPS or loopback HTTP for every effective server URL. */
+    requireSecureServerUrl?: boolean;
+    /**
+     * App-specific commands. Dispatched BEFORE built-ins (`auth`,
+     * `resources`, `mcp`) and before the resource-slug dispatcher, so an
+     * `extraCommands` entry takes precedence over anything with the same
+     * top-level argv.
+     *
+     * - **Built-in shadowing** (`extraCommands: [{ name: 'mcp' }]`): the CLI
+     *   prints a one-line stderr warning on first invocation. The extra
+     *   command still wins, but the warning makes the override visible.
+     *
+     * - **Resource-slug shadowing** (`extraCommands: [{ name: 'praecos' }]`
+     *   when a server-side class also resolves to slug `praecos`): the
+     *   extra command silently wins. There's no warning because checking
+     *   would require a discovery round-trip on every invocation. Authors
+     *   are responsible for namespacing their extra commands (e.g. prefix
+     *   with the app name) to avoid accidental shadowing as the server's
+     *   class registry grows. (#1311 review C-2.)
+     */
+    extraCommands?: AppCliCommand[];
+}
+export interface AppCli {
+    run(argv: string[]): Promise<void>;
+    /**
+     * Wire up the stdio MCP bridge and connect to stdin/stdout. The CLI
+     * advertises itself to local MCP clients as `serverInfo.name` /
+     * `.version`. Both fields default from `options.name` (so a brand-
+     * new app gets `{ name: '<name>-mcp', version: '0.0.0' }`) — pass an
+     * explicit object to override.
+     */
+    startMcpBridge(serverInfo?: {
+        name?: string;
+        version?: string;
+    }): Promise<void>;
+}
+export declare function createAppCli(options: CreateAppCliOptions): AppCli;
+//# sourceMappingURL=index.d.ts.map