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

package/dist/cli/local-connection.js

@@ -0,0 +1,151 @@
+/**
+ * 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 const LOCAL_CONNECTION_SECRETS_ENV = "APIFUSE__LOCAL_CONNECTION__SECRETS";
+/** Stable local connection id, mirroring the CLIs' other `local-*` scopes. */
+export const LOCAL_CONNECTION_ID = "local-connection";
+/** Auth modes whose providers read a credential the gateway supplies. */
+export function providerRequiresConnection(provider) {
+    const mode = provider.auth?.mode;
+    return mode !== undefined && mode !== "none";
+}
+/**
+ * Parses repeated `--credential key=value` arguments.
+ *
+ * Splits on the first `=` only: a base64 or URL-shaped secret routinely
+ * contains more.
+ */
+export function parseCredentialOverrides(values) {
+    const secrets = {};
+    for (const [index, value] of values.entries()) {
+        // The offending argument is never echoed. `--credential =secret` and
+        // `--credential secret` are both malformed *and* carry the credential, so
+        // quoting the input to be helpful would print it to stderr — before any
+        // redaction context exists, so no caller could scrub it.
+        const separator = value.indexOf("=");
+        if (separator <= 0) {
+            return {
+                ok: false,
+                reason: `--credential #${index + 1} is not of the form key=value; its value is not echoed here because it may be the credential.`,
+            };
+        }
+        const key = value.slice(0, separator).trim();
+        if (key.length === 0) {
+            return {
+                ok: false,
+                reason: `--credential #${index + 1} has an empty key; its value is not echoed here because it may be the credential.`,
+            };
+        }
+        secrets[key] = value.slice(separator + 1);
+    }
+    return { ok: true, secrets };
+}
+/** Reads {@link LOCAL_CONNECTION_SECRETS_ENV} into a secrets map. */
+export function parseEnvironmentSecrets(raw) {
+    if (raw === undefined || raw.trim().length === 0) {
+        return { ok: true, secrets: {} };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `${LOCAL_CONNECTION_SECRETS_ENV} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            reason: `${LOCAL_CONNECTION_SECRETS_ENV} must be a JSON object of credential key to string value.`,
+        };
+    }
+    const secrets = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value !== "string") {
+            return {
+                ok: false,
+                reason: `${LOCAL_CONNECTION_SECRETS_ENV}.${key} must be a string (received ${typeof value}); the value is not echoed here.`,
+            };
+        }
+        secrets[key] = value;
+    }
+    return { ok: true, secrets };
+}
+/**
+ * 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 function resolveLocalConnection(provider, options = {}) {
+    const fromEnv = parseEnvironmentSecrets((options.env ?? process.env)[LOCAL_CONNECTION_SECRETS_ENV]);
+    if (!fromEnv.ok)
+        return fromEnv;
+    const fromArgs = parseCredentialOverrides(options.overrides ?? []);
+    if (!fromArgs.ok)
+        return fromArgs;
+    const secrets = { ...fromEnv.secrets, ...fromArgs.secrets };
+    const mode = provider.auth?.mode;
+    if (!providerRequiresConnection(provider)) {
+        if (Object.keys(secrets).length > 0) {
+            return {
+                ok: false,
+                reason: `Provider "${provider.id}" declares auth.mode ${JSON.stringify(mode ?? "none")}, which takes no credential. Remove the supplied credential values.`,
+            };
+        }
+        return { ok: true, connection: undefined };
+    }
+    if (Object.keys(secrets).length === 0) {
+        return {
+            ok: false,
+            reason: missingLocalConnectionMessage(provider.id, mode ?? "none"),
+        };
+    }
+    return {
+        ok: true,
+        connection: {
+            id: LOCAL_CONNECTION_ID,
+            // `mode` is narrowed by providerRequiresConnection above.
+            mode: mode ?? "none",
+            secrets,
+            metadata: {},
+            externalRef: "",
+        },
+    };
+}
+/** The message a caller prints when a needed credential is not configured. */
+export function missingLocalConnectionMessage(providerId, mode) {
+    const platformManaged = mode === "platform-managed";
+    return [
+        `Provider "${providerId}" declares auth.mode "${mode}", so the gateway injects a credential on every invocation and this command has none.`,
+        platformManaged
+            ? "The value is the platform-owned key an operator holds; it is not a provider secret and is not derivable from the checkout."
+            : "Supply the same credential the gateway would resolve for a connection.",
+        "Supply it with one of:",
+        "  --credential <key>=<value>   (repeatable)",
+        `  ${LOCAL_CONNECTION_SECRETS_ENV}='{"<key>":"<value>"}'`,
+        "The keys are the ones the provider passes to ctx.credential.get(...).",
+        "Pass --no-credential to run without one anyway (the provider will fail the way it does in production when the credential is unavailable).",
+    ].join("\n");
+}

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

@@ -0,0 +1,132 @@
+import type { ProviderDeploymentOverrides } from "../types.js";
+import { type ResolvedDeploymentIntent } from "./deployment-intent.js";
+export declare const TYPESCRIPT_REQUIRED_MESSAGE = "apifuse migrate-deployment requires typescript; install it in the workspace running the CLI (bun add -d typescript)";
+/**
+ * Deployment-intent migration: retire a provider repository's standalone
+ * `deploy.ts`.
+ *
+ * End state: deployment intent lives only in the `deployment` key of the
+ * `defineProvider({...})` declaration, and only the fields that differ from
+ * the runtime profile are written. Everything else goes: the `deploy.ts`
+ * file, a `deployment` extra on a `{ ...provider, deployment }` default
+ * export, and an `import deployment from "./deploy"`. The `/deploy.ts`
+ * CODEOWNERS lock is kept by default: the platform still honors a committed
+ * legacy file until its fallback is retired, so re-adding one must keep
+ * needing operator review. `dropCodeownersLock` removes it once that
+ * fallback is gone.
+ *
+ * The transform never regenerates values from the profile — it moves the
+ * values the file actually declares (hand-edited "mirrors" exist in the
+ * fleet) and proves equivalence: the key it writes must resolve to exactly
+ * what the legacy file resolved to, or it refuses. Like the other codemods
+ * it is conservative: anything it cannot fully account for is reported as
+ * `refused` with a reason rather than partially migrated.
+ */
+/** How the `defineProvider()` declaration literal was located. */
+export type DeploymentDeclarationShape = 
+/** `defineProvider({ ... })` — the literal is the argument (spreads inside are fine). */
+"literal-argument"
+/** `const declaration = { ... }; defineProvider(declaration)` — top-level const literal. */
+ | "variable-literal-argument";
+export interface DeploymentIntentMigrationInput {
+    /** Current `index.ts` text. */
+    readonly indexSource: string;
+    /** Current `deploy.ts` text, or undefined when the repository has none. */
+    readonly deploySource?: string;
+    /** Current `.github/CODEOWNERS` text, or undefined when absent. */
+    readonly codeownersSource?: string;
+    /**
+     * Remove the `/deploy.ts` CODEOWNERS lock (and the scaffold's TEMPORARY
+     * comment above it). Off by default — see the module comment.
+     */
+    readonly dropCodeownersLock?: boolean;
+    readonly indexFileName?: string;
+}
+export type DeploymentIntentMigration = {
+    readonly status: "migrated";
+    readonly shape: DeploymentDeclarationShape;
+    readonly indexSource: string;
+    readonly indexChanged: boolean;
+    readonly codeownersSource?: string;
+    readonly codeownersChanged: boolean;
+    /** True when `deploy.ts` existed and must be deleted. */
+    readonly removeDeployFile: boolean;
+    /** Resolved view the legacy `deploy.ts` declared, when it existed. */
+    readonly legacy?: ResolvedDeploymentIntent;
+    /** The minimal key now authored in the declaration (empty = profile defaults). */
+    readonly intent: ProviderDeploymentOverrides;
+    /** What the key resolves to; equals `legacy` when a legacy file existed. */
+    readonly resolved: ResolvedDeploymentIntent;
+    readonly notes: readonly string[];
+} | {
+    readonly status: "unchanged";
+    readonly notes: readonly string[];
+} | {
+    readonly status: "refused";
+    readonly reason: string;
+};
+/**
+ * Emitted above the key only when it carries `runtime`: the deployment
+ * runtime axis sits next to the execution `runtime` property and must not
+ * be read as the same axis.
+ */
+export declare const DEPLOYMENT_RUNTIME_AXIS_COMMENT = "// Deployment runtime axis (shared | dedicated | browser); not the execution runtime above.";
+export declare function migrateDeploymentIntent(input: DeploymentIntentMigrationInput): DeploymentIntentMigration;
+/**
+ * Statically read the `deployment` key authored inside the declaration
+ * literal of `indexSource` (undefined when absent). Used to prove round
+ * trips: the value the transform wrote must resolve to the legacy view.
+ */
+export declare function readDeclaredDeploymentIntent(indexSource: string, fileName?: string): {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Line (1-based) of a `deployment` property attached to a spread default
+ * export (`export default { ...provider, deployment }`), or undefined when
+ * the module has no such legacy surface. Used by `apifuse check`: the loaded
+ * module cannot tell that extra apart from a declaration-level key, so the
+ * source shape is inspected instead.
+ */
+export declare function findSpreadExportDeploymentProperty(indexSource: string, fileName?: string): {
+    readonly line: number;
+} | undefined;
+/** Parse a legacy `deploy.ts` module text into the resolved deployment view. */
+export declare function readLegacyDeployFile(deploySource: string): {
+    readonly ok: true;
+    readonly value: ResolvedDeploymentIntent;
+    readonly raw: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Repository sources (other than index.ts and deploy.ts themselves) that
+ * import the deploy module — `import x from "../deploy"`, re-exports, dynamic
+ * `import("./deploy")`, `require("./deploy")`. Deleting deploy.ts while one
+ * exists breaks that consumer, so the command refuses until it is removed.
+ * `files` carry paths relative to or absolute under `providerRoot`.
+ */
+export declare function findDeployModuleConsumers(providerRoot: string, files: readonly {
+    readonly path: string;
+    readonly text: string;
+}[]): string[];
+/**
+ * Remove the `/deploy.ts` CODEOWNERS line and, when it is preceded by the
+ * exact platform-scaffold comment block, that block too. Any other content
+ * is preserved byte for byte.
+ */
+export declare function stripCodeownersDeployLock(text: string): {
+    readonly text: string;
+    readonly changed: boolean;
+};
+/**
+ * Format the key's object literal starting at column `indent.length +
+ * "deployment: ".length`: inline when it fits the line width, otherwise
+ * expanded one property per line (recursively), trailing commas included —
+ * the same decisions a formatter would keep.
+ */
+export declare function formatIntentLiteral(intent: ProviderDeploymentOverrides, indent: string, unit: string): string;