@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/cli/deployment-intent.d.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import type { ProviderDeploymentOverrides } from "../types.js";
+/**
+ * Deployment-intent helpers shared by `apifuse check` and
+ * `apifuse migrate-deployment`.
+ *
+ * Deployment intent has exactly one authored home: the optional `deployment`
+ * key on `defineProvider()`. The APIFuse registry builder is the only reader;
+ * it resolves omitted fields from a runtime profile and rejects anything it
+ * cannot resolve. This module mirrors that profile table so the CLI can
+ * (a) subtract profile defaults when hoisting a legacy `deploy.ts` into the
+ * key and (b) warn when a declared key restates a default. The registry
+ * stays canonical — keep the constants below identical to
+ * `resolveProviderDeploymentConfig` in `@apifuse/provider-registry`.
+ */
+export type DeploymentRuntime = "shared" | "dedicated" | "browser";
+export type DeploymentLanguage = "typescript" | "python";
+export interface DeploymentResources {
+    cpu: string;
+    memory: string;
+}
+export interface DeploymentHpa {
+    enabled: boolean;
+    minReplicas?: number;
+    maxReplicas?: number;
+    targetCPUUtilizationPercentage?: number;
+}
+/** Fully resolved deployment view: what the platform materializes for a provider. */
+export interface ResolvedDeploymentIntent {
+    runtime: DeploymentRuntime;
+    language: DeploymentLanguage;
+    replicas: number;
+    hpa: DeploymentHpa;
+    resources: DeploymentResources;
+    cache?: {
+        redis?: {
+            enabled: boolean;
+            url?: string;
+        };
+    };
+    network?: {
+        additionalTcpPorts: number[];
+    };
+    buildContext: string;
+}
+/**
+ * Runtime-profile defaults. `dedicated` carries no resource profile and
+ * therefore always needs explicit `resources`.
+ */
+export declare const DEPLOYMENT_PROFILE_DEFAULTS: Readonly<{
+    runtime: DeploymentRuntime;
+    language: DeploymentLanguage;
+    replicas: 1;
+    hpa: Readonly<DeploymentHpa>;
+    buildContext: ".";
+    resources: Readonly<Record<DeploymentRuntime, Readonly<DeploymentResources> | undefined>>;
+}>;
+/**
+ * The standalone `deploy.ts` contract (legacy). Mirrors the registry's
+ * `ProviderDeploymentConfigSchema`, including its own defaults — note that a
+ * legacy file without `hpa` resolved to `{ enabled: false }`, not the
+ * profile HPA, so the two default tables are deliberately different.
+ */
+export declare const legacyDeploymentConfigSchema: z.ZodObject<{
+    runtime: z.ZodEnum<{
+        browser: "browser";
+        shared: "shared";
+        dedicated: "dedicated";
+    }>;
+    language: z.ZodEnum<{
+        typescript: "typescript";
+        python: "python";
+    }>;
+    replicas: z.ZodDefault<z.ZodNumber>;
+    hpa: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        minReplicas: z.ZodOptional<z.ZodNumber>;
+        maxReplicas: z.ZodOptional<z.ZodNumber>;
+        targetCPUUtilizationPercentage: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    resources: z.ZodObject<{
+        cpu: z.ZodString;
+        memory: z.ZodString;
+    }, z.core.$strict>;
+    cache: z.ZodOptional<z.ZodObject<{
+        redis: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    network: z.ZodOptional<z.ZodObject<{
+        additionalTcpPorts: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strict>>;
+    buildContext: z.ZodOptional<z.ZodString & z.ZodType<".", string, z.core.$ZodTypeInternals<".", string>>>;
+}, z.core.$strict>;
+/** The authored `deployment` key: every field optional (registry `ProviderDeploymentOverridesSchema`). */
+export declare const deploymentOverridesSchema: z.ZodObject<{
+    runtime: z.ZodOptional<z.ZodEnum<{
+        browser: "browser";
+        shared: "shared";
+        dedicated: "dedicated";
+    }>>;
+    language: z.ZodOptional<z.ZodEnum<{
+        typescript: "typescript";
+        python: "python";
+    }>>;
+    replicas: z.ZodOptional<z.ZodNumber>;
+    hpa: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        minReplicas: z.ZodOptional<z.ZodNumber>;
+        maxReplicas: z.ZodOptional<z.ZodNumber>;
+        targetCPUUtilizationPercentage: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    resources: z.ZodOptional<z.ZodObject<{
+        cpu: z.ZodString;
+        memory: z.ZodString;
+    }, z.core.$strict>>;
+    cache: z.ZodOptional<z.ZodObject<{
+        redis: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    network: z.ZodOptional<z.ZodObject<{
+        additionalTcpPorts: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strict>>;
+    buildContext: z.ZodOptional<z.ZodString & z.ZodType<".", string, z.core.$ZodTypeInternals<".", string>>>;
+}, z.core.$strict>;
+export type DeploymentParse<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Parse a legacy `deploy.ts` default export into the resolved view. */
+export declare function normalizeLegacyDeployment(value: unknown): DeploymentParse<ResolvedDeploymentIntent>;
+/** Parse an authored `deployment` key against the strict overrides contract. */
+export declare function parseDeploymentIntent(value: unknown): DeploymentParse<ProviderDeploymentOverrides>;
+/**
+ * Resolve an authored key against the runtime profiles, per field;
+ * `resources` and `hpa` resolve as whole objects (never deep-merged).
+ * Throws when the intent cannot resolve (dedicated runtime without
+ * resources, non-default buildContext) — the registry rejects the same.
+ */
+export declare function resolveDeploymentIntent(intent?: ProviderDeploymentOverrides): ResolvedDeploymentIntent;
+/**
+ * Two resolved views describe the same deployment when they are deep-equal
+ * after dropping empty shells (`network: { additionalTcpPorts: [] }`,
+ * `cache: {}`) that carry no intent — the manifests they render are
+ * byte-identical.
+ */
+export declare function deploymentIntentsEquivalent(left: ResolvedDeploymentIntent, right: ResolvedDeploymentIntent): boolean;
+export declare function canonicalResolvedDeployment(resolved: ResolvedDeploymentIntent): ResolvedDeploymentIntent;
+/**
+ * The smallest `deployment` key that resolves to `resolved`: profile
+ * defaults are omitted, `hpa`/`resources` are kept whole when they differ
+ * (the resolver never deep-merges them), and empty shells are dropped.
+ * Callers prove the result with
+ * `deploymentIntentsEquivalent(resolveDeploymentIntent(key), resolved)`.
+ */
+export declare function subtractDeploymentDefaults(resolved: ResolvedDeploymentIntent): ProviderDeploymentOverrides;
+/** Authored order for emitted keys: the registry contract's field order. */
+export declare const DEPLOYMENT_INTENT_FIELD_ORDER: readonly (keyof ProviderDeploymentOverrides)[];
+export interface RedundantDeploymentField {
+    /** Dotted path under `deployment`, e.g. `hpa` or `network.additionalTcpPorts`. */
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Fields of an authored `deployment` key that restate what the runtime
+ * profile already resolves (ADR-0009 "derived values are not re-stated").
+ * Accepts an unvalidated value because `apifuse check` inspects the loaded
+ * definition, whose key the SDK passes through verbatim.
+ */
+export declare function redundantDeploymentDefaults(intent: unknown): RedundantDeploymentField[];
+/** Structural equality for JSON-shaped values, key order insensitive. */
+export declare function deepEqual(left: unknown, right: unknown): boolean;

package/dist/cli/deployment-intent.js

@@ -0,0 +1,277 @@
+import { z } from "zod";
+/**
+ * Runtime-profile defaults. `dedicated` carries no resource profile and
+ * therefore always needs explicit `resources`.
+ */
+export const DEPLOYMENT_PROFILE_DEFAULTS = Object.freeze({
+    runtime: "shared",
+    language: "typescript",
+    replicas: 1,
+    hpa: Object.freeze({
+        enabled: true,
+        minReplicas: 1,
+        maxReplicas: 1,
+        targetCPUUtilizationPercentage: 70,
+    }),
+    buildContext: ".",
+    resources: Object.freeze({
+        shared: Object.freeze({ cpu: "25m", memory: "128Mi" }),
+        browser: Object.freeze({ cpu: "200m", memory: "256Mi" }),
+        dedicated: undefined,
+    }),
+});
+const BUILD_CONTEXT_CONSTRAINT = 'only "." is accepted; external provider images always build from the materialized checkout root';
+const hpaSchema = z
+    .object({
+    enabled: z.boolean(),
+    minReplicas: z.number().int().positive().optional(),
+    maxReplicas: z.number().int().positive().optional(),
+    targetCPUUtilizationPercentage: z.number().int().positive().optional(),
+})
+    .strict();
+const resourcesSchema = z.object({ cpu: z.string().min(1), memory: z.string().min(1) }).strict();
+const cacheSchema = z
+    .object({
+    redis: z
+        .object({ enabled: z.boolean(), url: z.string().min(1).optional() })
+        .strict()
+        .optional(),
+})
+    .strict();
+const networkSchema = z
+    .object({
+    additionalTcpPorts: z.array(z.number().int().min(1).max(65535)).default([]),
+})
+    .strict();
+const buildContextSchema = z
+    .string()
+    .min(1)
+    .refine((value) => value === ".", { message: BUILD_CONTEXT_CONSTRAINT });
+/**
+ * The standalone `deploy.ts` contract (legacy). Mirrors the registry's
+ * `ProviderDeploymentConfigSchema`, including its own defaults — note that a
+ * legacy file without `hpa` resolved to `{ enabled: false }`, not the
+ * profile HPA, so the two default tables are deliberately different.
+ */
+export const legacyDeploymentConfigSchema = z
+    .object({
+    runtime: z.enum(["shared", "dedicated", "browser"]),
+    language: z.enum(["typescript", "python"]),
+    replicas: z.number().int().positive().default(1),
+    hpa: hpaSchema.default({ enabled: false }),
+    resources: resourcesSchema,
+    cache: cacheSchema.optional(),
+    network: networkSchema.optional(),
+    buildContext: buildContextSchema.optional(),
+})
+    .strict();
+/** The authored `deployment` key: every field optional (registry `ProviderDeploymentOverridesSchema`). */
+export const deploymentOverridesSchema = z
+    .object({
+    runtime: z.enum(["shared", "dedicated", "browser"]).optional(),
+    language: z.enum(["typescript", "python"]).optional(),
+    replicas: z.number().int().positive().optional(),
+    hpa: hpaSchema.optional(),
+    resources: resourcesSchema.optional(),
+    cache: cacheSchema.optional(),
+    network: networkSchema.optional(),
+    buildContext: buildContextSchema.optional(),
+})
+    .strict();
+function formatZodIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.map(String).join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}
+/** Parse a legacy `deploy.ts` default export into the resolved view. */
+export function normalizeLegacyDeployment(value) {
+    const parsed = legacyDeploymentConfigSchema.safeParse(value);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            reason: `deploy.ts is not a valid deployment config: ${formatZodIssues(parsed.error)}`,
+        };
+    }
+    const legacy = parsed.data;
+    return {
+        ok: true,
+        value: {
+            runtime: legacy.runtime,
+            language: legacy.language,
+            replicas: legacy.replicas,
+            hpa: legacy.hpa,
+            resources: legacy.resources,
+            ...(legacy.cache ? { cache: legacy.cache } : {}),
+            ...(legacy.network ? { network: legacy.network } : {}),
+            buildContext: legacy.buildContext ?? DEPLOYMENT_PROFILE_DEFAULTS.buildContext,
+        },
+    };
+}
+/** Parse an authored `deployment` key against the strict overrides contract. */
+export function parseDeploymentIntent(value) {
+    const parsed = deploymentOverridesSchema.safeParse(value);
+    if (!parsed.success) {
+        return { ok: false, reason: `deployment key is invalid: ${formatZodIssues(parsed.error)}` };
+    }
+    return { ok: true, value: parsed.data };
+}
+/**
+ * Resolve an authored key against the runtime profiles, per field;
+ * `resources` and `hpa` resolve as whole objects (never deep-merged).
+ * Throws when the intent cannot resolve (dedicated runtime without
+ * resources, non-default buildContext) — the registry rejects the same.
+ */
+export function resolveDeploymentIntent(intent = {}) {
+    const runtime = intent.runtime ?? DEPLOYMENT_PROFILE_DEFAULTS.runtime;
+    const resources = intent.resources ?? DEPLOYMENT_PROFILE_DEFAULTS.resources[runtime];
+    if (!resources) {
+        throw new Error(`resources: runtime "${runtime}" has no profile default; declare explicit resources { cpu, memory }`);
+    }
+    if (intent.buildContext !== undefined &&
+        intent.buildContext !== DEPLOYMENT_PROFILE_DEFAULTS.buildContext) {
+        throw new Error(`buildContext: ${BUILD_CONTEXT_CONSTRAINT}`);
+    }
+    return {
+        runtime,
+        language: intent.language ?? DEPLOYMENT_PROFILE_DEFAULTS.language,
+        replicas: intent.replicas ?? DEPLOYMENT_PROFILE_DEFAULTS.replicas,
+        hpa: intent.hpa ? { ...intent.hpa } : { ...DEPLOYMENT_PROFILE_DEFAULTS.hpa },
+        resources: { ...resources },
+        ...(intent.cache ? { cache: cloneJson(intent.cache) } : {}),
+        ...(intent.network
+            ? { network: { additionalTcpPorts: [...(intent.network.additionalTcpPorts ?? [])] } }
+            : {}),
+        buildContext: intent.buildContext ?? DEPLOYMENT_PROFILE_DEFAULTS.buildContext,
+    };
+}
+/**
+ * Two resolved views describe the same deployment when they are deep-equal
+ * after dropping empty shells (`network: { additionalTcpPorts: [] }`,
+ * `cache: {}`) that carry no intent — the manifests they render are
+ * byte-identical.
+ */
+export function deploymentIntentsEquivalent(left, right) {
+    return deepEqual(canonicalResolvedDeployment(left), canonicalResolvedDeployment(right));
+}
+export function canonicalResolvedDeployment(resolved) {
+    const { cache, network, ...rest } = resolved;
+    const canonical = { ...rest };
+    if (cache?.redis !== undefined)
+        canonical.cache = { redis: { ...cache.redis } };
+    if (network !== undefined && network.additionalTcpPorts.length > 0) {
+        canonical.network = { additionalTcpPorts: [...network.additionalTcpPorts] };
+    }
+    return canonical;
+}
+/**
+ * The smallest `deployment` key that resolves to `resolved`: profile
+ * defaults are omitted, `hpa`/`resources` are kept whole when they differ
+ * (the resolver never deep-merges them), and empty shells are dropped.
+ * Callers prove the result with
+ * `deploymentIntentsEquivalent(resolveDeploymentIntent(key), resolved)`.
+ */
+export function subtractDeploymentDefaults(resolved) {
+    const intent = {};
+    if (resolved.runtime !== DEPLOYMENT_PROFILE_DEFAULTS.runtime)
+        intent.runtime = resolved.runtime;
+    if (resolved.language !== DEPLOYMENT_PROFILE_DEFAULTS.language)
+        intent.language = resolved.language;
+    if (resolved.replicas !== DEPLOYMENT_PROFILE_DEFAULTS.replicas)
+        intent.replicas = resolved.replicas;
+    if (!deepEqual(resolved.hpa, DEPLOYMENT_PROFILE_DEFAULTS.hpa))
+        intent.hpa = { ...resolved.hpa };
+    const profileResources = DEPLOYMENT_PROFILE_DEFAULTS.resources[resolved.runtime];
+    if (profileResources === undefined || !deepEqual(resolved.resources, profileResources)) {
+        intent.resources = { ...resolved.resources };
+    }
+    if (resolved.cache?.redis !== undefined)
+        intent.cache = { redis: { ...resolved.cache.redis } };
+    if (resolved.network !== undefined && resolved.network.additionalTcpPorts.length > 0) {
+        intent.network = { additionalTcpPorts: [...resolved.network.additionalTcpPorts] };
+    }
+    // buildContext: "." is the only accepted value, so it is never authored.
+    return intent;
+}
+/** Authored order for emitted keys: the registry contract's field order. */
+export const DEPLOYMENT_INTENT_FIELD_ORDER = [
+    "runtime",
+    "language",
+    "replicas",
+    "hpa",
+    "resources",
+    "cache",
+    "network",
+    "buildContext",
+];
+/**
+ * Fields of an authored `deployment` key that restate what the runtime
+ * profile already resolves (ADR-0009 "derived values are not re-stated").
+ * Accepts an unvalidated value because `apifuse check` inspects the loaded
+ * definition, whose key the SDK passes through verbatim.
+ */
+export function redundantDeploymentDefaults(intent) {
+    if (!isRecord(intent))
+        return [];
+    const redundant = [];
+    const flag = (path, detail) => {
+        redundant.push({ path, message: `deployment.${path} ${detail}; omit it` });
+    };
+    if (intent.runtime === DEPLOYMENT_PROFILE_DEFAULTS.runtime) {
+        flag("runtime", `restates the profile default ("${DEPLOYMENT_PROFILE_DEFAULTS.runtime}")`);
+    }
+    if (intent.language === DEPLOYMENT_PROFILE_DEFAULTS.language) {
+        flag("language", `restates the profile default ("${DEPLOYMENT_PROFILE_DEFAULTS.language}")`);
+    }
+    if (intent.replicas === DEPLOYMENT_PROFILE_DEFAULTS.replicas) {
+        flag("replicas", `restates the profile default (${DEPLOYMENT_PROFILE_DEFAULTS.replicas})`);
+    }
+    if (deepEqual(intent.hpa, DEPLOYMENT_PROFILE_DEFAULTS.hpa)) {
+        flag("hpa", "restates the profile default (enabled, 1-1 replicas, 70% CPU target)");
+    }
+    const runtime = typeof intent.runtime === "string" && intent.runtime in DEPLOYMENT_PROFILE_DEFAULTS.resources
+        ? intent.runtime
+        : DEPLOYMENT_PROFILE_DEFAULTS.runtime;
+    const profileResources = DEPLOYMENT_PROFILE_DEFAULTS.resources[runtime];
+    if (profileResources !== undefined && deepEqual(intent.resources, profileResources)) {
+        flag("resources", `restates the "${runtime}" profile default (${profileResources.cpu}/${profileResources.memory})`);
+    }
+    if (intent.buildContext === DEPLOYMENT_PROFILE_DEFAULTS.buildContext) {
+        flag("buildContext", 'restates the only accepted value (".")');
+    }
+    if (isRecord(intent.network)) {
+        const ports = intent.network.additionalTcpPorts;
+        if (ports === undefined || (Array.isArray(ports) && ports.length === 0)) {
+            flag("network", "declares no additional TCP ports (empty shell)");
+        }
+    }
+    if (isRecord(intent.cache) && intent.cache.redis === undefined) {
+        flag("cache", "declares no redis intent (empty shell)");
+    }
+    return redundant;
+}
+/** Structural equality for JSON-shaped values, key order insensitive. */
+export function deepEqual(left, right) {
+    if (left === right)
+        return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length)
+            return false;
+        return left.every((item, index) => deepEqual(item, right[index]));
+    }
+    if (!isRecord(left) || !isRecord(right))
+        return false;
+    const leftKeys = Object.keys(left).filter((key) => left[key] !== undefined);
+    const rightKeys = Object.keys(right).filter((key) => right[key] !== undefined);
+    if (leftKeys.length !== rightKeys.length)
+        return false;
+    return leftKeys.every((key) => Object.hasOwn(right, key) && deepEqual(left[key], right[key]));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/cli/local-connection.d.ts

@@ -0,0 +1,111 @@
+import type { AuthMode, ProviderDefinition } from "../types.js";
+/**
+ * The connection the local CLIs stand in for the gateway with.
+ *
+ * At invocation time the gateway resolves the credential a provider needs and
+ * attaches it to the request envelope as
+ * `connection: { id, mode, secrets, metadata }`; `serve` then builds
+ * `ctx.credential` from `connection.secrets` and nothing else. For
+ * `auth.mode: "platform-managed"` the secrets are the platform-owned key the
+ * caller never sees — which is why a probe reaches one only by going back
+ * through the gateway (`ctx.gateway.execute(...)` in a health case's
+ * `prepareInput`), and why nothing that runs outside the gateway had any way
+ * to supply it.
+ *
+ * `apifuse record` hard-coded `credential: { mode: "none" }`, so
+ * `ctx.credential.get(...)` returned `undefined` for every platform-managed
+ * provider and the run died on that provider's own `MISSING_SECRET`. The same
+ * hole made `submit-check --smoke` POST an envelope with no `connection` at
+ * all. A large share of the fleet was unrecordable and unsmokeable, and it
+ * read as "no live upstream success" rather than as a missing capability.
+ *
+ * This module is the local resolver for that connection. It does not invent a
+ * second credential path: it produces the exact shape the gateway injects, so
+ * the provider code under test takes the production branch.
+ */
+export interface LocalConnection {
+    readonly id: string;
+    readonly mode: AuthMode;
+    readonly secrets: Record<string, string>;
+    readonly metadata: Record<string, never>;
+    /**
+     * Empty, exactly as the gateway leaves it when it injects a platform
+     * credential. `OperationConnectionSchema` requires the field, so omitting
+     * it would make every smoke envelope fail request validation before the
+     * provider ran.
+     */
+    readonly externalRef: string;
+}
+/**
+ * JSON object of `connection.secrets`, keyed exactly as the provider reads
+ * them through `ctx.credential.get(...)`.
+ *
+ * A single JSON value rather than one variable per key on purpose:
+ * platform-managed providers must not declare `credential.keys` (the SDK lint
+ * rejects it), so the key names are known only to the provider's own source.
+ * There is no derivation from an env name that would be right for every
+ * provider, and guessing one would be a second, lossy contract next to the
+ * gateway's.
+ */
+export declare const LOCAL_CONNECTION_SECRETS_ENV = "APIFUSE__LOCAL_CONNECTION__SECRETS";
+/** Stable local connection id, mirroring the CLIs' other `local-*` scopes. */
+export declare const LOCAL_CONNECTION_ID = "local-connection";
+/** Auth modes whose providers read a credential the gateway supplies. */
+export declare function providerRequiresConnection(provider: {
+    readonly auth?: {
+        readonly mode?: AuthMode;
+    } | undefined;
+}): boolean;
+export type CredentialOverrideParse = {
+    readonly ok: true;
+    readonly secrets: Record<string, string>;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Parses repeated `--credential key=value` arguments.
+ *
+ * Splits on the first `=` only: a base64 or URL-shaped secret routinely
+ * contains more.
+ */
+export declare function parseCredentialOverrides(values: readonly string[]): CredentialOverrideParse;
+/** Reads {@link LOCAL_CONNECTION_SECRETS_ENV} into a secrets map. */
+export declare function parseEnvironmentSecrets(raw: string | undefined): CredentialOverrideParse;
+export interface ResolveLocalConnectionOptions {
+    /** Repeated `--credential key=value` arguments, in order. */
+    readonly overrides?: readonly string[];
+    /** Environment to read {@link LOCAL_CONNECTION_SECRETS_ENV} from. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export type LocalConnectionResolution = {
+    readonly ok: true;
+    readonly connection: LocalConnection | undefined;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Resolves the connection to attach for one local invocation.
+ *
+ * Three outcomes, and the middle one is the point of the change:
+ *
+ * - the provider needs no credential (`auth.mode` absent or `"none"`) →
+ *   no connection, exactly as before;
+ * - the provider needs one and none is configured → `ok: false` with a
+ *   message naming both ways to supply it. The caller surfaces that instead
+ *   of letting the provider fail deep inside a handler on a `MISSING_SECRET`
+ *   that reads like an upstream problem;
+ * - the provider needs one and it is configured → the gateway's envelope
+ *   shape.
+ *
+ * CLI overrides win over the environment so a one-off run does not need the
+ * shell variable unset.
+ */
+export declare function resolveLocalConnection(provider: Pick<ProviderDefinition, "id"> & {
+    auth?: {
+        mode?: AuthMode;
+    };
+}, options?: ResolveLocalConnectionOptions): LocalConnectionResolution;
+/** The message a caller prints when a needed credential is not configured. */
+export declare function missingLocalConnectionMessage(providerId: string, mode: AuthMode): string;