@happyvertical/smrt-app-cli 0.40.52 → 0.40.53

package/README.md

@@ -46,6 +46,41 @@ Resources and their commands are discovered from the app's `/_resources`
 surface. JSON Schema becomes CLI flags, while unsupported schema shapes are
 reported instead of silently guessed.
 
+## Discovery conformance artifact
+
+`createResourceListHandler()` includes an `artifact` beside the compatible
+`user`, `warnings`, and `resources` response fields. The artifact has a stable
+schema selector, version, canonical ordering, and a `sha256:<hex>` digest. The
+CLI validates it before using its embedded discovery payload.
+
+For a released downstream app, install the exact published
+`@happyvertical/smrt-users` version and pin a captured artifact like this:
+
+```ts
+import {
+  validateDiscoveryConformanceArtifact,
+} from '@happyvertical/smrt-users/app-contract';
+
+const response = await fetch('https://app.example/api/_resources');
+const body = await response.json();
+const artifact = validateDiscoveryConformanceArtifact(body.artifact);
+
+console.log(artifact.schema, artifact.version, artifact.integrity.digest);
+// Store all three selectors and the canonical JSON in your packaged-runtime test.
+```
+
+The result contract embedded in the artifact names the common `code`,
+`message`, `details`, `retryable`, `correlationId`, `idempotencyKey`, and
+`expectedVersion` metadata. `mcp tools` and `mcp call` print this as a JSON
+success/error envelope. HTTP failures may use either a conventional top-level
+metadata object or `{ error: metadata }`; both normalize to that same shape.
+Generated action failures use the latter form with
+`{ error: { ok: false, code, message, status, ... } }`; the CLI reports the
+HTTP status beside that normalized metadata.
+The stdio bridge carries it in MCP `_meta` under
+`io.happyvertical/smrt`. It deliberately does not synthesize MCP
+`structuredContent`.
+
 ## Add an app-specific command
 
 ```ts

package/dist/bin/smrt-mcp-bridge.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { l as runMcpStdioBridge } from "../config-DvxwoFks.js";
+import { p as runMcpStdioBridge } from "../config-CDhknIOW.js";
 //#region src/bin/smrt-mcp-bridge.ts
 /**
 * `smrt-mcp-bridge` — generic stdio MCP bridge.

package/dist/bridge-BgtGXmYP.js

@@ -0,0 +1,2 @@
+import { p as runMcpStdioBridge } from "./config-CDhknIOW.js";
+export { runMcpStdioBridge };

package/dist/config-CDhknIOW.js

@@ -0,0 +1,422 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { SMRT_MCP_RESULT_METADATA_KEY } from "@happyvertical/smrt-users/app-contract";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+//#region src/bridge.ts
+/**
+* Stdio MCP bridge — pipes a remote SMRT app's HTTP MCP surface
+* (`/api/mcp/tools` + `/api/mcp/call`) to a local stdio MCP server so that
+* editors and AI clients can connect to it.
+*
+* Apps wire this up by providing their own bin script:
+*
+* ```ts
+* #!/usr/bin/env node
+* import { runMcpStdioBridge } from '@happyvertical/smrt-app-cli';
+* await runMcpStdioBridge({
+*   envPrefix: 'WILLGRIFFIN',
+*   serverInfo: { name: 'willgriffin-mcp', version: '0.1.0' },
+* });
+* ```
+*
+* The package also ships a `smrt-mcp-bridge` bin (see `bin/smrt-mcp-bridge`)
+* that reads `--env-prefix=…` from argv for ad-hoc use without writing a
+* package-specific entry point.
+*
+* @packageDocumentation
+*/
+/**
+* Wire up the stdio server. Use `runMcpStdioBridge` for a one-call entry
+* point in `bin/` scripts; this lower-level form is exposed for tests.
+*/
+function createMcpStdioBridge(options) {
+	const toolsPath = options.toolsPath ?? "/api/mcp/tools";
+	const callPath = options.callPath ?? "/api/mcp/call";
+	const server = new Server(options.serverInfo, { capabilities: { tools: {} } });
+	server.setRequestHandler(ListToolsRequestSchema, async (_request) => {
+		const outcome = await requestJsonResult(options, toolsPath, { method: "GET" }, { fetch: options.fetch });
+		if (!outcome.ok) throw toMcpTransportError(outcome.error);
+		return withMcpMetadata(outcome.result, outcome.metadata);
+	});
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const { name, arguments: args = {} } = request.params;
+		return formatMcpCallResult(await requestJsonResult(options, callPath, {
+			body: JSON.stringify({
+				arguments: args,
+				name
+			}),
+			method: "POST"
+		}, { fetch: options.fetch }));
+	});
+	return {
+		server,
+		connect: () => server.connect(new StdioServerTransport())
+	};
+}
+/**
+* Preserve the HTTP result/error envelope in protocol-permitted MCP metadata.
+* This deliberately does not create `structuredContent`; #2149 owns declared
+* output schema semantics for generated tools.
+*/
+function formatMcpCallResult(outcome) {
+	if (!outcome.ok) {
+		const error = sanitizeMetadata(outcome.error);
+		return withMcpMetadata({
+			content: [{
+				text: error.message ?? error.code,
+				type: "text"
+			}],
+			isError: true
+		}, error);
+	}
+	const metadata = isMcpErrorResult(outcome.result) ? {
+		...outcome.metadata,
+		code: outcome.metadata.code === "ok" ? "mcp_tool_error" : outcome.metadata.code,
+		message: outcome.metadata.message ?? resultText(outcome.result)
+	} : outcome.metadata;
+	return withMcpMetadata(isMcpErrorResult(outcome.result) ? redactMcpErrorContent(outcome.result) : outcome.result, metadata);
+}
+function withMcpMetadata(result, metadata) {
+	const existing = isRecord$1(result._meta) ? result._meta : {};
+	return {
+		...result,
+		_meta: {
+			...existing,
+			[SMRT_MCP_RESULT_METADATA_KEY]: sanitizeMetadata(metadata)
+		}
+	};
+}
+function sanitizeMetadata(metadata) {
+	return {
+		...metadata,
+		...metadata.message ? { message: String(redactTransportValue(metadata.message)) } : {},
+		...metadata.details !== void 0 ? { details: redactTransportValue(metadata.details) } : {},
+		...metadata.correlationId ? { correlationId: String(redactTransportValue(metadata.correlationId)) } : {}
+	};
+}
+/** Convert an HTTP transport failure into an MCP JSON-RPC error safely. */
+function toMcpTransportError(metadata) {
+	const sanitized = sanitizeMetadata(metadata);
+	return new McpError(ErrorCode.InternalError, sanitized.message ?? sanitized.code, { [SMRT_MCP_RESULT_METADATA_KEY]: sanitized });
+}
+function isMcpErrorResult(result) {
+	return result.isError === true;
+}
+function resultText(result) {
+	const content = result.content;
+	if (!Array.isArray(content)) return void 0;
+	return content.find((entry) => isRecord$1(entry) && typeof entry.text === "string")?.text;
+}
+function redactMcpErrorContent(result) {
+	const content = result.content;
+	if (!Array.isArray(content)) return result;
+	return {
+		...result,
+		content: content.map((entry) => isRecord$1(entry) && typeof entry.text === "string" ? {
+			...entry,
+			text: String(redactTransportValue(entry.text))
+		} : entry)
+	};
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* One-call entry point — instantiate the bridge and connect stdio. Returns
+* a `Promise<void>` that resolves once the transport disconnects.
+*/
+async function runMcpStdioBridge(options) {
+	const { connect } = createMcpStdioBridge(options);
+	await connect();
+}
+//#endregion
+//#region src/config.ts
+/**
+* Shared CLI helpers for SMRT apps: a small config file format, env var
+* resolution with a configurable prefix, and a minimal JSON HTTP client
+* that knows how to bear the stored CLI token.
+*
+* The same helpers back the stdio bridge (`smrt-mcp-bridge`) and any
+* app-specific `data`-style commands that talk to the app's HTTP API.
+*
+* @packageDocumentation
+*/
+var DEFAULT_LOCAL_SERVER = "http://localhost:5173";
+function configFilePath(context) {
+	const override = process.env[`${context.envPrefix}_CLI_CONFIG`];
+	if (override) return override;
+	const slug = context.appSlug ?? context.envPrefix.toLowerCase();
+	return join(homedir(), ".config", slug, "config.json");
+}
+/** Read the CLI config file. Missing file → empty config. */
+async function loadCliConfig(context) {
+	try {
+		const raw = await readFile(configFilePath(context), "utf8");
+		if (!raw.trim()) return {};
+		return JSON.parse(raw);
+	} catch (error) {
+		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return {};
+		throw error;
+	}
+}
+/**
+* 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).
+*/
+async function saveCliConfig(context, config) {
+	const path = configFilePath(context);
+	const dir = dirname(path);
+	await mkdir(dir, {
+		recursive: true,
+		mode: 448
+	});
+	await chmod(dir, 448).catch(() => void 0);
+	const tmp = `${path}.${randomBytes(6).toString("hex")}.tmp`;
+	try {
+		await writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 384 });
+		await chmod(tmp, 384);
+		await rename(tmp, path);
+	} catch (err) {
+		await unlink(tmp).catch(() => void 0);
+		throw err;
+	}
+}
+/** Resolve the server URL: env var → config file → `defaultServerUrl`. */
+async function getServerUrl(context, config) {
+	const resolved = config ?? await loadCliConfig(context);
+	return (process.env[`${context.envPrefix}_SERVER_URL`] ?? resolved.serverUrl ?? context.defaultServerUrl ?? DEFAULT_LOCAL_SERVER).replace(/\/+$/u, "");
+}
+/** Resolve a bearer token only when it is bound to the exact target server. */
+async function getStoredToken(context, config, serverUrl) {
+	const resolved = config ?? await loadCliConfig(context);
+	const targetServer = (serverUrl ?? await getServerUrl(context, resolved)).replace(/\/+$/u, "");
+	const environmentToken = process.env[`${context.envPrefix}_TOKEN`];
+	const environmentServer = process.env[`${context.envPrefix}_SERVER_URL`]?.replace(/\/+$/u, "");
+	if (environmentToken) return environmentServer === targetServer ? environmentToken : void 0;
+	const configuredServer = resolved.serverUrl?.replace(/\/+$/u, "");
+	if (!configuredServer || configuredServer !== targetServer) return void 0;
+	if (resolved.credentialIssuer) return resolved.tokensByIssuer?.[resolved.credentialIssuer];
+	return resolved.token;
+}
+/** Remove the token from the config file (e.g. on logout). */
+async function clearStoredToken(context) {
+	const config = await loadCliConfig(context);
+	if (config.credentialIssuer && config.tokensByIssuer) {
+		delete config.tokensByIssuer[config.credentialIssuer];
+		if (Object.keys(config.tokensByIssuer).length === 0) delete config.tokensByIssuer;
+	}
+	delete config.credentialIssuer;
+	delete config.token;
+	await saveCliConfig(context, config);
+}
+/** Persist a login with the bearer token keyed by its exact issuer. */
+async function saveAuth(context, serverUrl, token, issuer = serverUrl) {
+	const config = await loadCliConfig(context);
+	const normalizedServerUrl = serverUrl.replace(/\/+$/u, "");
+	if (!issuer.trim()) throw new Error("Credential issuer must not be empty.");
+	const exactIssuer = issuer;
+	await saveCliConfig(context, {
+		...config,
+		credentialIssuer: exactIssuer,
+		serverUrl: normalizedServerUrl,
+		token: void 0,
+		tokensByIssuer: { [exactIssuer]: token }
+	});
+}
+var DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+/** Error compatibility wrapper returned by the legacy throwing helper. */
+var AppCliRequestError = class extends Error {
+	status;
+	metadata;
+	constructor(status, metadata) {
+		super(metadata.message ?? `HTTP ${status}`);
+		this.name = "AppCliRequestError";
+		this.status = status;
+		this.metadata = metadata;
+	}
+};
+/**
+* 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.
+*/
+async function requestJson(context, path, init = {}, options = {}) {
+	const outcome = await requestJsonResult(context, path, init, options);
+	if (!outcome.ok) throw new AppCliRequestError(outcome.status, outcome.error);
+	return outcome.result;
+}
+/**
+* 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.
+*/
+async function requestJsonResult(context, path, init = {}, options = {}) {
+	const config = options.loadedConfig ?? await loadCliConfig(context);
+	const serverUrl = (options.serverUrl ?? await getServerUrl(context, config)).replace(/\/+$/u, "");
+	const token = await getStoredToken(context, config, serverUrl);
+	const headers = new Headers(init.headers);
+	if (options.requireAuth && options.auth !== false && !token) return failure(401, {
+		code: "not_authenticated",
+		message: `Not authenticated. Run \`${context.envPrefix.toLowerCase()} auth login\` first.`,
+		retryable: false
+	});
+	if (!headers.has("content-type") && init.body) headers.set("content-type", "application/json");
+	if (options.auth !== false && token) headers.set("authorization", `Bearer ${token}`);
+	const fetchImpl = options.fetch ?? fetch;
+	let response;
+	try {
+		response = await fetchImpl(`${serverUrl}${path}`, {
+			...init,
+			headers
+		});
+	} catch (error) {
+		return failure(0, {
+			code: "network_error",
+			message: redactMessage(error instanceof Error ? error.message : String(error)),
+			retryable: true
+		});
+	}
+	const contentType = response.headers.get("content-type") ?? "";
+	const maxBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+	let text;
+	try {
+		text = await readBodyWithCap(response, maxBytes);
+	} catch (error) {
+		if (!(error instanceof ResponseTooLargeError)) return failure(0, {
+			code: "network_error",
+			message: redactMessage(error instanceof Error ? error.message : String(error)),
+			retryable: true
+		});
+		return failure(response.status, {
+			code: "response_too_large",
+			message: redactMessage(error instanceof Error ? error.message : String(error)),
+			retryable: response.status >= 500
+		});
+	}
+	let parsed = text;
+	if (contentType.includes("application/json") && text) try {
+		parsed = JSON.parse(text);
+	} catch {
+		return failure(response.status, {
+			code: "invalid_json_response",
+			message: "Server returned invalid JSON.",
+			retryable: response.status >= 500
+		});
+	}
+	if (!response.ok) return failure(response.status, metadataFromResponse(parsed, response.headers, `http_${response.status}`, response.status >= 500 || response.status === 408 || response.status === 429, `HTTP ${response.status}: ${response.statusText}`));
+	return {
+		ok: true,
+		result: parsed,
+		metadata: metadataFromResponse(parsed, response.headers, "ok", false)
+	};
+}
+/** Redact conventional credential fields before emitting transport metadata. */
+function redactTransportValue(value) {
+	if (typeof value === "string") return redactMessage(value);
+	if (Array.isArray(value)) return value.map(redactTransportValue);
+	if (!isRecord(value)) return value;
+	const redacted = {};
+	for (const [key, nested] of Object.entries(value)) redacted[key] = isSensitiveKey(key) ? "[REDACTED]" : redactTransportValue(nested);
+	return redacted;
+}
+function failure(status, error) {
+	return {
+		ok: false,
+		status,
+		error
+	};
+}
+function metadataFromResponse(payload, headers, fallbackCode, fallbackRetryable, fallbackMessage) {
+	const record = isRecord(payload) ? payload : void 0;
+	const error = record && isRecord(record.error) ? record.error : void 0;
+	const meta = firstRecord(error, record && isRecord(record.metadata) ? record.metadata : void 0, record && isRecord(record.meta) ? record.meta : void 0, getMcpMetadata(record), record);
+	const message = firstString(meta?.message, error?.message, typeof record?.error === "string" ? record.error : void 0, fallbackMessage);
+	const details = meta?.details ?? error?.details;
+	const correlationId = firstString(meta?.correlationId, error?.correlationId, headers.get("x-correlation-id") ?? void 0, headers.get("x-request-id") ?? void 0);
+	const idempotencyKey = declaredActionField(meta?.idempotencyKey ?? meta?.idempotency);
+	const expectedVersion = declaredActionField(meta?.expectedVersion);
+	return {
+		code: firstString(meta?.code, error?.code) ?? fallbackCode,
+		...message ? { message: redactMessage(message) } : {},
+		...details !== void 0 ? { details: redactTransportValue(details) } : {},
+		retryable: typeof meta?.retryable === "boolean" ? meta.retryable : typeof error?.retryable === "boolean" ? error.retryable : fallbackRetryable,
+		...correlationId ? { correlationId: redactMessage(correlationId) } : {},
+		...idempotencyKey ? { idempotencyKey } : {},
+		...expectedVersion ? { expectedVersion } : {}
+	};
+}
+function getMcpMetadata(record) {
+	if (!record || !isRecord(record._meta)) return void 0;
+	const meta = record._meta[SMRT_MCP_RESULT_METADATA_KEY];
+	return isRecord(meta) ? meta : void 0;
+}
+function declaredActionField(value) {
+	if (!isRecord(value) || typeof value.field !== "string") return void 0;
+	return {
+		field: value.field,
+		required: value.required === true
+	};
+}
+function firstRecord(...values) {
+	return values.find((value) => value !== void 0);
+}
+function firstString(...values) {
+	return values.find((value) => typeof value === "string" && value !== "");
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSensitiveKey(key) {
+	return /(?:authorization|token|secret|password|cookie|credential|api[-_]?key)/iu.test(key);
+}
+function redactMessage(message) {
+	return message.replace(/bearer\s+[a-z0-9._~+/=-]+/giu, "Bearer [REDACTED]").replace(/((?:token|secret|password|api[-_]?key|authorization)=)[^&\s,]+/giu, "$1[REDACTED]");
+}
+var ResponseTooLargeError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ResponseTooLargeError";
+	}
+};
+/**
+* Read the response body into a UTF-8 string, capping at `maxBytes`. On
+* overflow, throw with a clear message — better than OOM-ing the CLI
+* when a server returns a multi-GB body. Streams chunk-by-chunk so the
+* check fires before the whole body is buffered. (#1311 review A4.)
+*/
+async function readBodyWithCap(response, maxBytes) {
+	if (!response.body) return "";
+	const cl = Number(response.headers.get("content-length") ?? "");
+	if (Number.isFinite(cl) && cl > maxBytes) {
+		try {
+			await response.body.cancel();
+		} catch {}
+		throw new ResponseTooLargeError(`Response too large: ${cl} bytes exceeds ${maxBytes}-byte cap`);
+	}
+	const reader = response.body.getReader();
+	const chunks = [];
+	let size = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (!value) continue;
+			size += value.byteLength;
+			if (size > maxBytes) throw new ResponseTooLargeError(`Response too large: exceeded ${maxBytes}-byte cap mid-stream`);
+			chunks.push(value);
+		}
+	} finally {
+		try {
+			reader.releaseLock();
+		} catch {}
+	}
+	return new TextDecoder().decode(Buffer.concat(chunks.map((c) => Buffer.from(c))));
+}
+//#endregion
+export { loadCliConfig as a, requestJsonResult as c, createMcpStdioBridge as d, formatMcpCallResult as f, getStoredToken as i, saveAuth as l, toMcpTransportError as m, clearStoredToken as n, redactTransportValue as o, runMcpStdioBridge as p, getServerUrl as r, requestJson as s, AppCliRequestError as t, saveCliConfig as u };

package/dist/index.d.ts

@@ -43,6 +43,42 @@ export declare interface AppCliContext {
     stderr: NodeJS.WriteStream;
 }
 
+/** 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;
+}
+
 export declare function buildFlagParser(schema: Record<string, unknown> | undefined, options?: ParserOptions): BuildParserResult;
 
 export declare interface BuildParserResult {
@@ -129,12 +165,20 @@ declare interface CommandDefinition_2 {
     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';
@@ -183,6 +227,32 @@ export declare function createMcpStdioBridge(options: McpStdioBridgeOptions): {
     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.
  *
@@ -241,6 +311,11 @@ declare interface InvokeOptions {
     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>;
 
@@ -332,6 +407,9 @@ declare interface ParserOptions {
     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
@@ -356,6 +434,12 @@ export declare interface RenderResult {
  */
 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 {
     /**
@@ -390,6 +474,24 @@ export declare interface RequestJsonOptions {
     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.
@@ -405,6 +507,8 @@ declare interface ResourceListResponseBody {
     };
     warnings: string[];
     resources: CliResource_2[];
+    /** Versioned deterministic artifact for consumers that integrity-pin discovery. */
+    artifact?: DiscoveryConformanceArtifact;
 }
 
 /**
@@ -431,4 +535,19 @@ export declare type SchemaSupportStatus = {
     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 { }

package/dist/index.js

@@ -1,7 +1,24 @@
-import { a as requestJson, c as createMcpStdioBridge, i as loadCliConfig, l as runMcpStdioBridge, n as getServerUrl, o as saveAuth, r as getStoredToken, s as saveCliConfig, t as clearStoredToken } from "./config-DvxwoFks.js";
+import { a as loadCliConfig, c as requestJsonResult, d as createMcpStdioBridge, i as getStoredToken, l as saveAuth, n as clearStoredToken, o as redactTransportValue, p as runMcpStdioBridge, r as getServerUrl, s as requestJson, t as AppCliRequestError, u as saveCliConfig } from "./config-CDhknIOW.js";
+import { SMRT_MCP_RESULT_METADATA_KEY, validateDiscoveryConformanceArtifact } from "@happyvertical/smrt-users/app-contract";
 import { spawn, spawnSync } from "node:child_process";
 //#region src/discovery.ts
 /**
+* Fetches the resource list from `GET /api/_resources` and re-exports the
+* wire types so consumers can build typed extensions on top of the discovery
+* output.
+*
+* Types are imported type-only from `@happyvertical/smrt-users/sveltekit`
+* — the single source of truth for the wire contract. The CLI does not
+* depend on smrt-users at runtime (the peer dep is `optional` in the
+* package.json) so importing types is free of bundle cost.
+*
+* Importing type-only means a new field added to `CommandDefinition` /
+* `CliResource` on the handler side automatically propagates to the CLI's
+* typecheck — no manual mirror-update required. (#1311 review D-1.)
+*
+* @packageDocumentation
+*/
+/**
 * Fetch the discovery payload.
 *
 * Translates a 401 into a friendlier error so the CLI can prompt the
@@ -9,11 +26,17 @@ import { spawn, spawnSync } from "node:child_process";
 */
 async function fetchResourceList(context, options = {}) {
 	try {
-		return await requestJson(context, options.path ?? "/api/_resources", { method: "GET" }, {
+		const response = await requestJson(context, options.path ?? "/api/_resources", { method: "GET" }, {
 			fetch: options.fetch,
 			requireAuth: options.requireAuth,
 			loadedConfig: options.loadedConfig
 		});
+		if (!response.artifact) return response;
+		const artifact = validateDiscoveryConformanceArtifact(response.artifact);
+		return {
+			...artifact.discovery,
+			artifact
+		};
 	} catch (error) {
 		if (error instanceof Error && /401|unauthor/i.test(error.message)) throw new Error(`Not authenticated to ${context.envPrefix.toLowerCase()}. Run \`${context.envPrefix.toLowerCase()} auth login\` first.`);
 		throw error;
@@ -758,11 +781,13 @@ function openVerificationUrl(url) {
 //#region src/commands/mcp.ts
 async function runMcpCommand(options, args) {
 	const stdout = options.stdout ?? process.stdout;
+	const stderr = options.stderr ?? process.stderr;
 	const sub = args[0];
 	if (sub === "tools") {
-		const result = await requestJson(options.context, "/api/mcp/tools", { method: "GET" }, { fetch: options.fetch });
+		const result = await requestJsonResult(options.context, "/api/mcp/tools", { method: "GET" }, { fetch: options.fetch });
 		stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-		return;
+		if (!result.ok) stderr.write(`${result.error.message ?? result.error.code}\n`);
+		return result.ok;
 	}
 	if (sub === "call") {
 		const name = args[1];
@@ -774,7 +799,7 @@ async function runMcpCommand(options, args) {
 		} catch (error) {
 			throw new Error(`Could not parse mcp call payload: ${error.message}`);
 		}
-		const result = await requestJson(options.context, "/api/mcp/call", {
+		const result = await requestJsonResult(options.context, "/api/mcp/call", {
 			body: JSON.stringify({
 				arguments: parsed,
 				name
@@ -782,7 +807,8 @@ async function runMcpCommand(options, args) {
 			method: "POST"
 		}, { fetch: options.fetch });
 		stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-		return;
+		if (!result.ok) stderr.write(`${result.error.message ?? result.error.code}\n`);
+		return result.ok;
 	}
 	throw new Error("Usage: mcp tools | mcp call <tool> [<json>]");
 }
@@ -847,7 +873,7 @@ function createAppCli(options) {
 	return {
 		run: (argv) => runCli(context, options, extraByName, argv),
 		startMcpBridge: async (serverInfo) => {
-			const { runMcpStdioBridge } = await import("./bridge-D0LJc3mN.js");
+			const { runMcpStdioBridge } = await import("./bridge-BgtGXmYP.js");
 			await runMcpStdioBridge({
 				...context,
 				serverInfo: {
@@ -899,10 +925,14 @@ async function dispatchCli(context, options, extras, argv, stdout, stderr) {
 		if (sub === "logout") return runAuthLogout(opts);
 		throw new Error("Usage: auth login [--server <url>] [--no-open] | status | logout");
 	}
-	if (command === "mcp") return runMcpCommand({
-		context,
-		stdout
-	}, rest);
+	if (command === "mcp") {
+		if (!await runMcpCommand({
+			context,
+			stdout,
+			stderr
+		}, rest)) process.exitCode = 1;
+		return;
+	}
 	if (command === "resources") return runResourcesCommand({
 		context,
 		stdout,
@@ -1000,4 +1030,4 @@ function similar(a, b) {
 	return true;
 }
 //#endregion
-export { buildFlagParser, buildUrl, classifySchema, clearStoredToken, createAppCli, createMcpClientIdMetadataDocument, createMcpStdioBridge, fetchResourceList, findCommand, findResourceBySlug, getServerUrl, getStoredToken, invokeCommand, loadCliConfig, registerMcpClient, renderResponse, requestJson, resolveMcpClientRegistration, runMcpStdioBridge, saveAuth, saveCliConfig };
+export { AppCliRequestError, SMRT_MCP_RESULT_METADATA_KEY, buildFlagParser, buildUrl, classifySchema, clearStoredToken, createAppCli, createMcpClientIdMetadataDocument, createMcpStdioBridge, fetchResourceList, findCommand, findResourceBySlug, getServerUrl, getStoredToken, invokeCommand, loadCliConfig, redactTransportValue, registerMcpClient, renderResponse, requestJson, requestJsonResult, resolveMcpClientRegistration, runMcpStdioBridge, saveAuth, saveCliConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-app-cli",
-  "version": "0.40.52",
+  "version": "0.40.53",
   "description": "Reusable CLI factory for SMRT apps — branded `<name> <resource> <command>` CLI + stdio MCP bridge with decorator-driven resource discovery",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
-    "@happyvertical/smrt-users": "0.40.52"
+    "@happyvertical/smrt-users": "0.40.53"
   },
   "devDependencies": {
     "@types/node": "24.13.2",
@@ -29,7 +29,7 @@
     "vite": "8.1.4",
     "vite-plugin-dts": "4.5.4",
     "vitest": "4.1.10",
-    "@happyvertical/smrt-core": "0.40.52"
+    "@happyvertical/smrt-core": "0.40.53"
   },
   "engines": {
     "node": ">=24.18.0"

package/dist/bridge-D0LJc3mN.js

@@ -1,2 +0,0 @@
-import { l as runMcpStdioBridge } from "./config-DvxwoFks.js";
-export { runMcpStdioBridge };

package/dist/config-DvxwoFks.js

@@ -1,231 +0,0 @@
-import { randomBytes } from "node:crypto";
-import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-//#region src/bridge.ts
-/**
-* Stdio MCP bridge — pipes a remote SMRT app's HTTP MCP surface
-* (`/api/mcp/tools` + `/api/mcp/call`) to a local stdio MCP server so that
-* editors and AI clients can connect to it.
-*
-* Apps wire this up by providing their own bin script:
-*
-* ```ts
-* #!/usr/bin/env node
-* import { runMcpStdioBridge } from '@happyvertical/smrt-app-cli';
-* await runMcpStdioBridge({
-*   envPrefix: 'WILLGRIFFIN',
-*   serverInfo: { name: 'willgriffin-mcp', version: '0.1.0' },
-* });
-* ```
-*
-* The package also ships a `smrt-mcp-bridge` bin (see `bin/smrt-mcp-bridge`)
-* that reads `--env-prefix=…` from argv for ad-hoc use without writing a
-* package-specific entry point.
-*
-* @packageDocumentation
-*/
-/**
-* Wire up the stdio server. Use `runMcpStdioBridge` for a one-call entry
-* point in `bin/` scripts; this lower-level form is exposed for tests.
-*/
-function createMcpStdioBridge(options) {
-	const toolsPath = options.toolsPath ?? "/api/mcp/tools";
-	const callPath = options.callPath ?? "/api/mcp/call";
-	const server = new Server(options.serverInfo, { capabilities: { tools: {} } });
-	server.setRequestHandler(ListToolsRequestSchema, async (_request) => {
-		return requestJson(options, toolsPath, { method: "GET" }, { fetch: options.fetch });
-	});
-	server.setRequestHandler(CallToolRequestSchema, async (request) => {
-		const { name, arguments: args = {} } = request.params;
-		try {
-			return await requestJson(options, callPath, {
-				body: JSON.stringify({
-					arguments: args,
-					name
-				}),
-				method: "POST"
-			}, { fetch: options.fetch });
-		} catch (error) {
-			return {
-				content: [{
-					text: error instanceof Error ? error.message : "MCP tool call failed.",
-					type: "text"
-				}],
-				isError: true
-			};
-		}
-	});
-	return {
-		server,
-		connect: () => server.connect(new StdioServerTransport())
-	};
-}
-/**
-* One-call entry point — instantiate the bridge and connect stdio. Returns
-* a `Promise<void>` that resolves once the transport disconnects.
-*/
-async function runMcpStdioBridge(options) {
-	const { connect } = createMcpStdioBridge(options);
-	await connect();
-}
-//#endregion
-//#region src/config.ts
-/**
-* Shared CLI helpers for SMRT apps: a small config file format, env var
-* resolution with a configurable prefix, and a minimal JSON HTTP client
-* that knows how to bear the stored CLI token.
-*
-* The same helpers back the stdio bridge (`smrt-mcp-bridge`) and any
-* app-specific `data`-style commands that talk to the app's HTTP API.
-*
-* @packageDocumentation
-*/
-var DEFAULT_LOCAL_SERVER = "http://localhost:5173";
-function configFilePath(context) {
-	const override = process.env[`${context.envPrefix}_CLI_CONFIG`];
-	if (override) return override;
-	const slug = context.appSlug ?? context.envPrefix.toLowerCase();
-	return join(homedir(), ".config", slug, "config.json");
-}
-/** Read the CLI config file. Missing file → empty config. */
-async function loadCliConfig(context) {
-	try {
-		const raw = await readFile(configFilePath(context), "utf8");
-		if (!raw.trim()) return {};
-		return JSON.parse(raw);
-	} catch (error) {
-		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return {};
-		throw error;
-	}
-}
-/**
-* 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).
-*/
-async function saveCliConfig(context, config) {
-	const path = configFilePath(context);
-	const dir = dirname(path);
-	await mkdir(dir, {
-		recursive: true,
-		mode: 448
-	});
-	await chmod(dir, 448).catch(() => void 0);
-	const tmp = `${path}.${randomBytes(6).toString("hex")}.tmp`;
-	try {
-		await writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 384 });
-		await chmod(tmp, 384);
-		await rename(tmp, path);
-	} catch (err) {
-		await unlink(tmp).catch(() => void 0);
-		throw err;
-	}
-}
-/** Resolve the server URL: env var → config file → `defaultServerUrl`. */
-async function getServerUrl(context, config) {
-	const resolved = config ?? await loadCliConfig(context);
-	return (process.env[`${context.envPrefix}_SERVER_URL`] ?? resolved.serverUrl ?? context.defaultServerUrl ?? DEFAULT_LOCAL_SERVER).replace(/\/+$/u, "");
-}
-/** Resolve a bearer token only when it is bound to the exact target server. */
-async function getStoredToken(context, config, serverUrl) {
-	const resolved = config ?? await loadCliConfig(context);
-	const targetServer = (serverUrl ?? await getServerUrl(context, resolved)).replace(/\/+$/u, "");
-	const environmentToken = process.env[`${context.envPrefix}_TOKEN`];
-	const environmentServer = process.env[`${context.envPrefix}_SERVER_URL`]?.replace(/\/+$/u, "");
-	if (environmentToken) return environmentServer === targetServer ? environmentToken : void 0;
-	const configuredServer = resolved.serverUrl?.replace(/\/+$/u, "");
-	if (!configuredServer || configuredServer !== targetServer) return void 0;
-	if (resolved.credentialIssuer) return resolved.tokensByIssuer?.[resolved.credentialIssuer];
-	return resolved.token;
-}
-/** Remove the token from the config file (e.g. on logout). */
-async function clearStoredToken(context) {
-	const config = await loadCliConfig(context);
-	if (config.credentialIssuer && config.tokensByIssuer) {
-		delete config.tokensByIssuer[config.credentialIssuer];
-		if (Object.keys(config.tokensByIssuer).length === 0) delete config.tokensByIssuer;
-	}
-	delete config.credentialIssuer;
-	delete config.token;
-	await saveCliConfig(context, config);
-}
-/** Persist a login with the bearer token keyed by its exact issuer. */
-async function saveAuth(context, serverUrl, token, issuer = serverUrl) {
-	const config = await loadCliConfig(context);
-	const normalizedServerUrl = serverUrl.replace(/\/+$/u, "");
-	if (!issuer.trim()) throw new Error("Credential issuer must not be empty.");
-	const exactIssuer = issuer;
-	await saveCliConfig(context, {
-		...config,
-		credentialIssuer: exactIssuer,
-		serverUrl: normalizedServerUrl,
-		token: void 0,
-		tokensByIssuer: { [exactIssuer]: token }
-	});
-}
-var DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
-/**
-* 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.
-*/
-async function requestJson(context, path, init = {}, options = {}) {
-	const config = options.loadedConfig ?? await loadCliConfig(context);
-	const serverUrl = (options.serverUrl ?? await getServerUrl(context, config)).replace(/\/+$/u, "");
-	const token = await getStoredToken(context, config, serverUrl);
-	const headers = new Headers(init.headers);
-	if (options.requireAuth && options.auth !== false && !token) throw new Error(`Not authenticated. Run \`${context.envPrefix.toLowerCase()} auth login\` first.`);
-	if (!headers.has("content-type") && init.body) headers.set("content-type", "application/json");
-	if (options.auth !== false && token) headers.set("authorization", `Bearer ${token}`);
-	const response = await (options.fetch ?? fetch)(`${serverUrl}${path}`, {
-		...init,
-		headers
-	});
-	const contentType = response.headers.get("content-type") ?? "";
-	const text = await readBodyWithCap(response, options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES);
-	const parsed = contentType.includes("application/json") && text ? JSON.parse(text) : text;
-	if (!response.ok) {
-		const message = parsed && typeof parsed === "object" && "error" in parsed ? String(parsed.error) : `HTTP ${response.status}: ${response.statusText}`;
-		throw Object.assign(new Error(message), { status: response.status });
-	}
-	return parsed;
-}
-/**
-* Read the response body into a UTF-8 string, capping at `maxBytes`. On
-* overflow, throw with a clear message — better than OOM-ing the CLI
-* when a server returns a multi-GB body. Streams chunk-by-chunk so the
-* check fires before the whole body is buffered. (#1311 review A4.)
-*/
-async function readBodyWithCap(response, maxBytes) {
-	if (!response.body) return "";
-	const cl = Number(response.headers.get("content-length") ?? "");
-	if (Number.isFinite(cl) && cl > maxBytes) {
-		try {
-			await response.body.cancel();
-		} catch {}
-		throw new Error(`Response too large: ${cl} bytes exceeds ${maxBytes}-byte cap`);
-	}
-	const reader = response.body.getReader();
-	const chunks = [];
-	let size = 0;
-	try {
-		while (true) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			if (!value) continue;
-			size += value.byteLength;
-			if (size > maxBytes) throw new Error(`Response too large: exceeded ${maxBytes}-byte cap mid-stream`);
-			chunks.push(value);
-		}
-	} finally {
-		try {
-			reader.releaseLock();
-		} catch {}
-	}
-	return new TextDecoder().decode(Buffer.concat(chunks.map((c) => Buffer.from(c))));
-}
-//#endregion
-export { requestJson as a, createMcpStdioBridge as c, loadCliConfig as i, runMcpStdioBridge as l, getServerUrl as n, saveAuth as o, getStoredToken as r, saveCliConfig as s, clearStoredToken as t };