@keystrokehq/cli 0.0.1

package/dist/connect.handler-CYel9cy6.mjs

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+
+import { D as throwReportedCliExit, h as toErrorMessage, l as AUTH_HINT, m as isNetworkError, t as ui } from "./keystroke.mjs";
+import { i as writeJson } from "./output-DM4b7KgY.mjs";
+import { n as CredentialScopeSchema, t as ConnectionStatusSchema } from "./schema-17qMfNyI.mjs";
+import { t as openBrowser } from "./browser-qwFrUH82.mjs";
+import { t as getIntegrationCatalog } from "./integration-catalog-Bt-L3GjF.mjs";
+import { z } from "zod";
+//#region ../../packages/shared-types/src/connections/api.ts
+/**
+* API request/response types for the integration catalog and connection endpoints.
+*
+* These types are shared between the server route handlers, the Keystroke SDK, and
+* any in-repo consumer (CLI, web). They divide the surface into two clearly-scoped
+* endpoints:
+*
+*   GET /api/v1/integrations  — the static Keystroke integration catalog (what can
+*     be connected). Auth required; not org-scoped; long-cached.
+*
+*   GET /api/v1/connections   — the caller's configured connections for the current
+*     org (what has been connected). Auth + org required; no-cache.
+*
+* Each endpoint validates its query string with the exported `*QuerySchema`, and
+* the SDK types its method signatures against the same schema so that invalid
+* params cannot be sent or accepted.
+*/
+const ShopifyShopDomainSchema = z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*\.myshopify\.com$/i, "Shopify store domain must look like \"example.myshopify.com\".");
+const InitiateConnectionRequestSchema = z.object({
+	providerAppId: z.string().optional(),
+	shopDomain: ShopifyShopDomainSchema.optional(),
+	requestedScopes: z.array(z.string()).optional()
+});
+const InitiateConnectionResponseSchema = z.object({
+	authUrl: z.string(),
+	initiatedAt: z.number()
+});
+const ConnectionFailureReasonSchema = z.enum([
+	"missing_state",
+	"invalid_state",
+	"provider_denied",
+	"unknown_integration",
+	"provider_app_not_configured",
+	"token_exchange_failed",
+	"installation_metadata_invalid",
+	"validation_failed",
+	"persist_failed",
+	"unknown_error"
+]);
+const ConnectionStatusNotStartedSchema = z.object({ status: z.literal("not_started") });
+const ConnectionStatusPendingSchema = z.object({ status: z.literal("pending") });
+const ConnectionStatusConnectedSchema = z.object({ status: z.literal("connected") });
+const ConnectionStatusFailedSchema = z.object({
+	status: z.literal("failed"),
+	reason: ConnectionFailureReasonSchema,
+	/**
+	* Optional human-readable detail. Truncated by the server to
+	* {@link CONNECTION_FAILURE_DETAIL_MAX_CHARS} characters before being
+	* persisted in `credential_sets.last_callback_error_detail` and
+	* before being echoed in the callback redirect query.
+	*/
+	message: z.string().max(300).optional(),
+	/** ISO-8601 timestamp of when the failure was recorded. */
+	failedAt: z.string()
+});
+const ConnectionStatusResponseSchema = z.discriminatedUnion("status", [
+	ConnectionStatusNotStartedSchema,
+	ConnectionStatusPendingSchema,
+	ConnectionStatusConnectedSchema,
+	ConnectionStatusFailedSchema
+]);
+const ConnectionKindSchema = z.enum([
+	"oauth",
+	"manual",
+	"credentials-exchange"
+]);
+const InternalCredentialSetEntrySchema = z.object({
+	resolvedCredentialSetId: z.string(),
+	publicId: z.string(),
+	displayName: z.string(),
+	/**
+	* Internal credential-set role. Currently the only first-class role is
+	* `'provider-app-definition'`; other values are accepted for forward-compat
+	* so newer servers can introduce roles without breaking older SDKs.
+	*/
+	role: z.string()
+});
+const IntegrationCatalogEntryBaseSchema = z.object({
+	publicId: z.string(),
+	/**
+	* Public-facing aliases that resolve to this canonical `publicId`
+	* (e.g., `"github"` aliases `"github-account"`). Includes the canonical
+	* ID itself — callers can key a lookup table by every entry in this
+	* list and get the same catalog record back.
+	*/
+	aliases: z.array(z.string()),
+	name: z.string(),
+	description: z.string().optional(),
+	/**
+	* Resolved credential-set metadata for the integration's primary connection.
+	* `storedKeys` drives upload flows (what the vault stores), while
+	* `authKeys` describes the post-resolve runtime shape.
+	*/
+	credentialSet: z.object({
+		resolvedCredentialSetId: z.string(),
+		authKeys: z.array(z.string()),
+		storedKeys: z.array(z.string()),
+		optionalStoredKeys: z.array(z.string()).optional(),
+		schemaFingerprint: z.string().optional()
+	}),
+	/**
+	* Internal credential sets associated with the integration (e.g., provider
+	* app definitions). Populated only when the caller requests
+	* `includeInternal=true`; otherwise empty.
+	*/
+	internalCredentialSets: z.array(InternalCredentialSetEntrySchema)
+});
+const OAuthIntegrationCatalogEntrySchema = IntegrationCatalogEntryBaseSchema.extend({
+	connectionKind: z.literal("oauth"),
+	tokenType: z.enum(["long-lived", "refreshable"]),
+	scopes: z.array(z.string())
+});
+const ManualIntegrationCatalogEntrySchema = IntegrationCatalogEntryBaseSchema.extend({ connectionKind: z.literal("manual") });
+/**
+* Catalog entry for `credentials-exchange`-kind integrations.
+*
+* Carries the JSON-schema projection of the connection's `input` schema so
+* the CLI and web UI can render an input form without re-loading the
+* original Zod schema (which only exists in the integration bundle's
+* runtime module). `credentialSet.storedKeys` reflects the stored-schema
+* keys that get persisted after exchange.
+*
+* @see packages/workflow-core/src/credential-set/connection.ts CredentialsExchangeConnectionConfig
+*/
+const CredentialsExchangeIntegrationCatalogEntrySchema = IntegrationCatalogEntryBaseSchema.extend({
+	connectionKind: z.literal("credentials-exchange"),
+	/** JSON-schema projection of the connection's `input` schema. */
+	input: z.record(z.string(), z.unknown()),
+	/** Optional free-form copy rendered above the input form. */
+	instructions: z.string().optional()
+});
+const IntegrationCatalogEntrySchema = z.discriminatedUnion("connectionKind", [
+	OAuthIntegrationCatalogEntrySchema,
+	ManualIntegrationCatalogEntrySchema,
+	CredentialsExchangeIntegrationCatalogEntrySchema
+]);
+z.object({
+	/** Restrict results to one connection kind. */
+	connectionKind: ConnectionKindSchema.optional(),
+	/**
+	* Return only the integration whose `publicId` (or alias) matches.
+	* When no integration matches, the endpoint returns an empty array.
+	*/
+	publicId: z.string().min(1).optional(),
+	/**
+	* Case-insensitive substring match against `publicId`, `aliases`, and `name`.
+	*/
+	q: z.string().min(1).optional(),
+	/**
+	* Opt into `internalCredentialSets[]` on each entry. Defaults to `false`
+	* so the common catalog call stays lean. CLI commands that need to render
+	* credential-set display names set this to `true`.
+	*/
+	includeInternal: z.stringbool().optional().default(false)
+}).strict();
+z.object({ integrations: z.array(IntegrationCatalogEntrySchema) });
+const ConnectionEntrySchema = z.object({
+	id: z.string(),
+	/**
+	* Public-facing integration ID this connection is associated with
+	* (post alias resolution). `null` when the underlying credential set is
+	* not backed by an official Keystroke integration (e.g., user-defined
+	* custom credential sets).
+	*/
+	integrationPublicId: z.string().nullable(),
+	/**
+	* Resolved credential-set ID, e.g., `"keystroke:slack"` or a custom set's
+	* identifier. Stable across alias resolution.
+	*/
+	credentialSetId: z.string(),
+	name: z.string(),
+	scope: CredentialScopeSchema,
+	platformConnected: z.boolean(),
+	connectionStatus: ConnectionStatusSchema,
+	expiresAt: z.string().nullable(),
+	isDefault: z.boolean(),
+	createdAt: z.string()
+});
+/**
+* Coerces a `status` query-param value that may arrive as a single string,
+* a comma-separated string, or (in Hono/ky's query handling) an array of
+* strings, into a canonical `ConnectionStatus[]`. Invalid entries cause the
+* surrounding Zod parse to fail with a helpful issue.
+*
+* The field itself is made optional at the object level (see
+* `ListConnectionsQuerySchema`), so passing `undefined` / omitting the key
+* is always valid; this preprocessor only runs when a value is actually
+* present.
+*/
+const ConnectionStatusQueryParam = z.preprocess((value) => {
+	if (value === void 0 || value === null || value === "") return void 0;
+	const trimmed = (Array.isArray(value) ? value : String(value).split(",")).flatMap((entry) => String(entry).split(",")).map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+	return trimmed.length === 0 ? void 0 : trimmed;
+}, z.array(ConnectionStatusSchema));
+z.object({
+	/** Filter to connections for a specific integration's public ID (alias-resolved). */
+	integrationPublicId: z.string().min(1).optional(),
+	/**
+	* Filter by one or more connection statuses. Accepts a single value, a
+	* comma-separated string, or repeated query keys. Omit to return all statuses.
+	*/
+	status: ConnectionStatusQueryParam.optional(),
+	scope: CredentialScopeSchema.optional(),
+	projectId: z.uuid().optional()
+}).strict();
+z.object({ connections: z.array(ConnectionEntrySchema) });
+//#endregion
+//#region src/commands/connect/connect.handler.ts
+function formatIntegrationLabel(catalog, integrationId) {
+	return catalog.lookupByPublicId(integrationId)?.name ?? integrationId;
+}
+function normalizeShopifyShopDomain(shop) {
+	const trimmed = shop?.trim().toLowerCase();
+	if (!trimmed) return;
+	const normalized = trimmed.endsWith(".myshopify.com") ? trimmed : `${trimmed}.myshopify.com`;
+	return ShopifyShopDomainSchema.parse(normalized);
+}
+/**
+* Per-reason CLI hint table for `failed` status responses.
+*
+* The hints are operator-facing copy: short, actionable, free of jargon.
+* Anywhere `{label}` appears, the caller substitutes the human-readable
+* integration label (e.g. "Slack"). Values come from
+* `ConnectionFailureReasonValues` in shared-types — keep the two in
+* lock-step (the CLI test asserts every reason has a hint).
+*/
+const FAILURE_REASON_HINTS = {
+	missing_state: "The OAuth callback was missing its state token. This is almost always transient — try `keystroke connect {label}` again.",
+	invalid_state: "The OAuth state token was invalid or expired (10-minute TTL). Run `keystroke connect {label}` again to start a fresh flow.",
+	provider_denied: "The provider rejected the authorization request. Approve access at the provider, then run `keystroke connect {label}` again.",
+	unknown_integration: "Keystroke does not recognize this integration. Run `keystroke integrations list` to see what is available.",
+	provider_app_not_configured: "The Keystroke {label} OAuth app is not configured for this environment. Ask a Keystroke developer to seed the platform credentials and try again.",
+	token_exchange_failed: "The provider rejected the token exchange. Re-running `keystroke connect {label}` usually fixes a transient failure; otherwise verify the platform OAuth client credentials.",
+	installation_metadata_invalid: "The provider returned an unexpected response shape on success. Re-run `keystroke connect {label}`; if the failure repeats, file a bug with the structured server log.",
+	validation_failed: "The {label} credentials passed token exchange but failed Keystroke's post-grant validation (e.g. missing required scope). Approve the listed scopes when re-running `keystroke connect {label}`.",
+	persist_failed: "Keystroke failed to persist the {label} connection (database error). Re-run `keystroke connect {label}`; if it keeps failing, check the server logs for the structured error code.",
+	unknown_error: "Keystroke encountered an unexpected error finishing the {label} connection. Check the server logs and re-run `keystroke connect {label}`."
+};
+function formatFailureHint(reason, label) {
+	return FAILURE_REASON_HINTS[reason].replaceAll("{label}", label);
+}
+function exitWithError(ctx, message, opts) {
+	if (ctx.jsonMode) {
+		process.stdout.write(`${JSON.stringify({
+			error: message,
+			...opts?.code ? { code: opts.code } : {},
+			...opts?.hint ? { hint: opts.hint } : {}
+		}, null, 2)}\n`);
+		throwReportedCliExit(message);
+	}
+	ui.error(message);
+	if (opts?.hint) ui.hint(opts.hint);
+	throwReportedCliExit(message);
+}
+/**
+* Handle the `keystroke connect <integrationId>` command.
+*
+* Initiates a platform OAuth flow:
+* 1. Calls POST /api/v1/connections/:integrationId/initiate to get an auth URL + state token
+* 2. Opens the browser to the auth URL
+* 3. Polls GET /api/v1/connections/:integrationId/status?state=XXX until connected or timeout
+*/
+async function handleConnect(options, ctx) {
+	const integrationId = options.integrationId?.trim().toLowerCase();
+	const { baseUrl, apiKey } = ctx;
+	if (!baseUrl || !apiKey) exitWithError(ctx, "Not authenticated.", {
+		code: "AUTH_ERROR",
+		hint: AUTH_HINT
+	});
+	if (!integrationId) exitWithError(ctx, "Usage: keystroke connect <integrationId>", {
+		code: "USAGE_ERROR",
+		hint: "Example: keystroke connect github"
+	});
+	const catalog = await getIntegrationCatalog(ctx);
+	const integrationLabel = catalog.oauthPublicIds.includes(integrationId) ? formatIntegrationLabel(catalog, integrationId) : integrationId;
+	const shopDomain = integrationId === "shopify" ? normalizeShopifyShopDomain(options.shop) : void 0;
+	if (integrationId === "shopify" && !shopDomain) exitWithError(ctx, "Shopify connections require a store domain.", {
+		code: "USAGE_ERROR",
+		hint: "Example: keystroke connect shopify --shop example.myshopify.com"
+	});
+	if (!ctx.jsonMode) {
+		ui.text(`Connect ${integrationLabel}`);
+		ui.br();
+	}
+	let authUrl;
+	let initiatedAt;
+	try {
+		const requestBody = InitiateConnectionRequestSchema.parse({ ...shopDomain ? { shopDomain } : {} });
+		const hasRequestBody = Object.keys(requestBody).length > 0;
+		const response = await fetch(`${baseUrl}/api/v1/connections/${integrationId}/initiate`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+				...hasRequestBody ? { "Content-Type": "application/json" } : {}
+			},
+			...hasRequestBody ? { body: JSON.stringify(requestBody) } : {}
+		});
+		if (!response.ok) {
+			if (response.status === 404) exitWithError(ctx, `Integration "${integrationId}" is not supported for platform OAuth.`, {
+				code: "UNSUPPORTED_INTEGRATION",
+				hint: `Currently supported official OAuth integrations: ${catalog.oauthPublicIds.join(", ")}. Workspace-authored OAuth connect flows are not available yet.`
+			});
+			if (response.status === 503) exitWithError(ctx, `Platform credentials not configured for "${integrationId}".`, {
+				code: "PLATFORM_NOT_CONFIGURED",
+				hint: `Ask a Keystroke developer to configure the ${integrationLabel} account OAuth client for this environment.`
+			});
+			if (response.status === 401) exitWithError(ctx, "Not authenticated.", {
+				code: "AUTH_ERROR",
+				hint: AUTH_HINT
+			});
+			if (response.status === 403) exitWithError(ctx, `You do not have permission to connect ${integrationLabel} in the current organization.`, {
+				code: "FORBIDDEN",
+				hint: "Verify your active organization and your permissions in that organization."
+			});
+			if (response.status >= 500) exitWithError(ctx, `The Keystroke server failed while starting the ${integrationLabel} connection.`, {
+				code: "SERVER_ERROR",
+				hint: `Server returned HTTP ${response.status}. Check the server logs and try again.`
+			});
+			exitWithError(ctx, `Failed to initiate the ${integrationLabel} connection.`, {
+				code: "INITIATE_FAILED",
+				hint: `Server returned HTTP ${response.status}.`
+			});
+		}
+		const data = InitiateConnectionResponseSchema.parse(await response.json());
+		authUrl = data.authUrl;
+		initiatedAt = data.initiatedAt;
+	} catch (error) {
+		if (error instanceof Error && error.name === "CliExitError") throw error;
+		if (isNetworkError(error)) exitWithError(ctx, `Could not reach the Keystroke server to start the ${integrationLabel} connection.`, {
+			code: "NETWORK_ERROR",
+			hint: `Check that your local services are running and that the CLI is pointed at ${baseUrl}.`
+		});
+		exitWithError(ctx, `Failed to initiate the ${integrationLabel} connection.`, {
+			code: "INITIATE_FAILED",
+			hint: toErrorMessage(error)
+		});
+	}
+	if (ctx.jsonMode) {
+		writeJson({
+			status: "authorization_required",
+			integrationId,
+			authUrl,
+			initiatedAt,
+			timeoutSeconds: options.timeout
+		});
+		return;
+	}
+	if (!options.noOpen) ui.text("Opening your browser for authorization...");
+	ui.br();
+	ui.text(options.noOpen ? "Open this URL in your browser:" : "If nothing opens, visit this URL:");
+	ui.text(`  ${authUrl}`);
+	if (!options.noOpen) try {
+		await openBrowser(authUrl);
+	} catch (error) {
+		ui.warn(`Could not open the browser automatically: ${error instanceof Error ? error.message : "unknown error"}`);
+		ui.text("Open this URL manually to continue:");
+		ui.text(`  ${authUrl}`);
+	}
+	ui.br();
+	ui.text(`Waiting for approval in ${integrationLabel}...`);
+	ui.text("Return to this terminal after you approve access.");
+	ui.text("Press Ctrl+C to cancel.");
+	const timeoutMs = options.timeout * 1e3;
+	const pollIntervalMs = 2e3;
+	const startTime = Date.now();
+	let consecutivePollFailures = 0;
+	let pollingWarningShown = false;
+	while (Date.now() - startTime < timeoutMs) {
+		await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+		try {
+			const response = await fetch(`${baseUrl}/api/v1/connections/${integrationId}/status?since=${initiatedAt}`, { headers: { Authorization: `Bearer ${apiKey}` } });
+			if (!response.ok) {
+				consecutivePollFailures += 1;
+				if (response.status === 401) exitWithError(ctx, "Your CLI session is no longer authenticated.", {
+					code: "AUTH_ERROR",
+					hint: AUTH_HINT
+				});
+				if (response.status === 403) exitWithError(ctx, `You do not have permission to finish the ${integrationLabel} connection in the current organization.`, {
+					code: "FORBIDDEN",
+					hint: "Verify your active organization and your permissions in that organization."
+				});
+				if (!pollingWarningShown && consecutivePollFailures >= 3) {
+					pollingWarningShown = true;
+					ui.warn(`Still waiting for ${integrationLabel} authorization.`);
+					ui.hint(`Polling has hit temporary errors (latest HTTP ${response.status}). If you already approved access, wait a moment and try again.`);
+				}
+				continue;
+			}
+			consecutivePollFailures = 0;
+			const data = ConnectionStatusResponseSchema.parse(await response.json());
+			if (data.status === "connected") {
+				ui.br();
+				ui.success(`Connected ${integrationLabel} successfully.`);
+				ui.hint(`Your ${integrationLabel} account is now available to Keystroke workflows.`);
+				return;
+			}
+			if (data.status === "failed") {
+				ui.br();
+				const headline = data.message ? `Could not finish the ${integrationLabel} connection: ${data.message}` : `Could not finish the ${integrationLabel} connection (${data.reason}).`;
+				ui.error(headline);
+				ui.hint(formatFailureHint(data.reason, integrationLabel));
+				throwReportedCliExit(headline);
+			}
+		} catch (error) {
+			if (error instanceof Error && error.name === "CliExitError") throw error;
+			consecutivePollFailures += 1;
+			if (!pollingWarningShown && consecutivePollFailures >= 3) {
+				pollingWarningShown = true;
+				ui.warn(`Still waiting for ${integrationLabel} authorization.`);
+				ui.hint(`Polling has hit temporary errors. If you already approved access, wait a moment and try again.`);
+			}
+		}
+	}
+	ui.br();
+	ui.error(`Timed out waiting for ${integrationLabel} authorization.`);
+	ui.text("If authorization is still open in your browser, you can still finish it here:");
+	ui.text(`  ${authUrl}`);
+	throwReportedCliExit(`Timed out waiting for ${integrationLabel} authorization.`);
+}
+//#endregion
+export { handleConnect };

package/dist/constants-CPpPdSNg.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+//#region ../../packages/shared-types/src/connections/constants.ts
+/** Namespaces reserved for official Keystroke integrations. Builder rejects these in user source files. */
+const RESERVED_NAMESPACES = ["keystroke"];
+RESERVED_NAMESPACES[0];
+//#endregion
+export { RESERVED_NAMESPACES as t };

package/dist/context-T7HZuB97.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+import { n as __exportAll } from "./chunk-CH6r78ws.mjs";
+import { C as CliExitError, S as AuthenticationError, h as toErrorMessage, i as logger, l as AUTH_HINT, p as isAuthError, t as ui, u as REAUTH_HINT } from "./keystroke.mjs";
+import { l as resolveAuthOptions } from "./dist-CUK7yBM0.mjs";
+import { a as writeJsonError } from "./output-DM4b7KgY.mjs";
+import { t as getEnv } from "./env-91KwMKov.mjs";
+//#region src/lib/context.ts
+var context_exports = /* @__PURE__ */ __exportAll({
+	assertProjectConfigMatchesAuthenticatedOrg: () => assertProjectConfigMatchesAuthenticatedOrg,
+	requireAuthOptions: () => requireAuthOptions,
+	requireClient: () => requireClient,
+	resolveAuthContext: () => resolveAuthContext,
+	resolveBaseContext: () => resolveBaseContext,
+	validateApiKey: () => validateApiKey
+});
+function exitNotAuthenticated(jsonMode) {
+	if (jsonMode) writeJsonError(`Not authenticated. ${AUTH_HINT}`, {
+		code: "AUTH_ERROR",
+		hint: AUTH_HINT
+	});
+	ui.error(`Not authenticated. ${AUTH_HINT}`);
+	throw new AuthenticationError(`Not authenticated. ${AUTH_HINT}`, { reported: true });
+}
+/**
+* Resolves the base CLI context for every command.
+*
+* Org resolution priority (first non-empty value wins):
+*   1. --org flag (ID)
+*   2. KEYSTROKE_ORG_ID env
+*   3. Active org from stored credentials
+*
+* API key: resolved from the matching org entry in stored credentials (or explicit --apiKey flag).
+* Base URL: flags > stored credentials > env.
+*/
+async function resolveBaseContext(overrides = {}) {
+	const authContext = await resolveAuthContext(overrides);
+	let client = null;
+	if (authContext.apiKey && authContext.baseUrl) try {
+		const { createClient } = await import("./src-eHwu-Gfw.mjs");
+		client = createClient({
+			apiKey: authContext.apiKey,
+			baseUrl: authContext.baseUrl,
+			organizationId: authContext.organizationId,
+			onRequest: (info) => logger.debug(`-> ${info.method} ${info.url}`, {
+				headers: info.headers,
+				body: info.body
+			}),
+			onResponse: (info) => logger.debug(`<- ${info.status} ${info.method} ${info.url} (${info.durationMs}ms)`, {
+				headers: info.headers,
+				body: info.body
+			})
+		});
+	} catch {}
+	return {
+		...authContext,
+		client
+	};
+}
+async function resolveAuthContext(overrides = {}) {
+	const auth = await resolveAuthOptions({
+		apiKey: overrides.apiKey,
+		baseUrl: overrides.baseUrl
+	});
+	const env = getEnv();
+	let apiKey = auth.apiKey ?? env.KEYSTROKE_API_KEY;
+	const baseUrl = auth.baseUrl ?? env.SERVER_URL;
+	const orgRaw = overrides.org ?? env.KEYSTROKE_ORG_ID ?? auth.activeOrg?.organizationId;
+	const orgSource = overrides.org ? "flag" : env.KEYSTROKE_ORG_ID ? "env" : auth.activeOrg?.organizationId ? "credentials" : void 0;
+	let organizationId = orgRaw;
+	let matchedStoredOrg = false;
+	if (orgRaw && auth.storedCredentials) {
+		const matchedOrg = auth.storedCredentials.orgs.find((o) => o.organizationId === orgRaw);
+		matchedStoredOrg = matchedOrg !== void 0;
+		if (matchedOrg) {
+			if (!overrides.apiKey) apiKey = matchedOrg.apiKey;
+			organizationId = matchedOrg.organizationId;
+		}
+	}
+	const usingSavedApiKey = !overrides.apiKey && !env.KEYSTROKE_API_KEY && typeof auth.apiKey === "string" && auth.apiKey.length > 0;
+	if (typeof orgRaw === "string" && orgRaw.length > 0 && orgSource !== "credentials" && usingSavedApiKey && auth.storedCredentials && !matchedStoredOrg) {
+		ui.error(`Organization ID "${orgRaw}" is not available in your saved credentials.`);
+		ui.hint("Run `keystroke org switch`, re-authenticate for that organization, or pass --api-key.");
+		throw new CliExitError(`Unknown saved organization ID: ${orgRaw}`, { reported: true });
+	}
+	return {
+		apiKey,
+		baseUrl,
+		jsonMode: false,
+		organizationId,
+		orgSource,
+		storedCredentials: auth.storedCredentials,
+		credentialsPath: auth.credentialsPath
+	};
+}
+/**
+* Requires that the CLI context has a valid authenticated client.
+* Exits the process with a helpful message if credentials are missing.
+* Outputs a JSON error when `ctx.jsonMode` is true.
+*/
+function requireClient(ctx) {
+	if (!ctx.client) exitNotAuthenticated(ctx.jsonMode);
+	return ctx.client;
+}
+function requireAuthOptions(ctx) {
+	if (!ctx.apiKey || !ctx.baseUrl) exitNotAuthenticated(ctx.jsonMode);
+	return {
+		apiKey: ctx.apiKey,
+		baseUrl: ctx.baseUrl,
+		...ctx.organizationId ? { organizationId: ctx.organizationId } : {}
+	};
+}
+/**
+* Validates the API key by making a test request to the server.
+* Exits the process with a helpful message if the key is invalid, expired, or unreachable.
+*/
+async function validateApiKey(client) {
+	try {
+		return await client.public.auth.validate();
+	} catch (error) {
+		const message = toErrorMessage(error);
+		if (isAuthError(error)) ui.error(`Invalid or expired API key. ${REAUTH_HINT}`);
+		else ui.error(`Failed to verify API key: ${message}`);
+		throw new AuthenticationError(`API key validation failed: ${message}`, {
+			cause: error,
+			reported: true
+		});
+	}
+}
+async function assertProjectConfigMatchesAuthenticatedOrg(client, projectConfig) {
+	const auth = await validateApiKey(client);
+	if (auth.organizationId === projectConfig.organizationId) return;
+	ui.error(`This checkout is configured for organization ID "${projectConfig.organizationId}", but the current credentials are scoped to organization ID "${auth.organizationId}".`);
+	ui.hint("Switch organizations or update your local project config before running this command.");
+	throw new CliExitError(`Project organization mismatch: config=${projectConfig.organizationId} auth=${auth.organizationId}`, { reported: true });
+}
+//#endregion
+export { validateApiKey as a, requireClient as i, context_exports as n, requireAuthOptions as r, assertProjectConfigMatchesAuthenticatedOrg as t };

package/dist/credential-env-map-CI8yWHVy.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import * as fs from "node:fs/promises";
+import * as path$1 from "node:path";
+import { z } from "zod";
+//#region src/lib/credential-env-map.ts
+/**
+* Read optional .keystroke/credential-env-map.json from project root.
+* Maps credentialSetId → { credentialKey: envVarName } to override KEYSTROKE_<KEY> convention.
+*/
+const CredentialEnvMapSchema = z.record(z.string(), z.record(z.string(), z.string()));
+const CREDENTIAL_ENV_MAP_FILE = ".keystroke/credential-env-map.json";
+/**
+* Reads .keystroke/credential-env-map.json from project root (workflowsDir).
+* Returns null if file does not exist or is invalid.
+*/
+async function readCredentialEnvMap(projectRoot) {
+	const filePath = path$1.join(projectRoot, CREDENTIAL_ENV_MAP_FILE);
+	try {
+		const raw = await fs.readFile(filePath, "utf-8");
+		const parsed = CredentialEnvMapSchema.safeParse(JSON.parse(raw));
+		return parsed.success ? parsed.data : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { readCredentialEnvMap as t };

package/dist/credential-schema-mismatch-BKo5PjcQ.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { i as writeJson } from "./output-DM4b7KgY.mjs";
+//#region src/lib/credential-schema-mismatch.ts
+/**
+* Structured detection and rendering for `CredentialSchemaMismatchError`
+* surfaces in the CLI.
+*
+* The error is thrown by the executor's credential resolver and the server
+* upload/preflight paths when a vault row's stored schema fingerprint does
+* not match the current manifest's fingerprint. Because the error crosses
+* worker subprocess and sandbox isolates, detection uses a structural
+* `.name` check rather than `instanceof`.
+*
+* This module centralises both the detection and the human-readable /
+* JSON renderings so every CLI command surfaces the error consistently.
+*
+* @see import('@keystroke/workflow-core/errors').CredentialSchemaMismatchError
+*/
+/**
+* JSON output code used for structured CLI output. Keep this literal value
+* stable — agents and scripts match on it.
+*/
+const CREDENTIAL_SCHEMA_MISMATCH_CODE = "CREDENTIAL_SCHEMA_MISMATCH";
+/**
+* Structural check — `instanceof` is unreliable across V8 contexts (worker
+* subprocess, sandbox isolates) so we detect by `.name` plus the mandatory
+* structural fields.
+*/
+function isCredentialSchemaMismatchErrorLike(error) {
+	if (!error || typeof error !== "object") return false;
+	const candidate = error;
+	return candidate.name === "CredentialSchemaMismatchError" && typeof candidate.manifestId === "string" && typeof candidate.storedFingerprint === "string" && typeof candidate.currentFingerprint === "string" && typeof candidate.remediation === "string";
+}
+function serializeUploadedAt(value) {
+	if (value instanceof Date) return value.toISOString();
+	if (typeof value === "string" && value.length > 0) {
+		const parsed = new Date(value);
+		if (!Number.isNaN(parsed.getTime())) return parsed.toISOString();
+	}
+	return null;
+}
+function renderCredentialSchemaMismatchText(ui, error) {
+	ui.error(`Credential schema mismatch for "${error.manifestId}".`);
+	ui.text("");
+	ui.text(`  The credentials stored for "${error.manifestId}" were uploaded against a`);
+	ui.text("  different schema than the workflow currently expects.");
+	ui.text("");
+	const uploadedAt = serializeUploadedAt(error.uploadedAt) ?? "unknown";
+	ui.text(`    Uploaded at:    ${uploadedAt}`);
+	ui.text(`    Uploaded shape: ${error.storedFingerprint}`);
+	ui.text(`    Current shape:  ${error.currentFingerprint}`);
+	ui.text("");
+	ui.text("  To fix, re-upload credentials:");
+	ui.text("");
+	ui.text(`    ${error.remediation}`);
+}
+/**
+* Emit the mismatch as a structured JSON payload on stdout. Leaves process
+* flow to the caller — paired with `throwReportedCliExit` at the call site
+* so the CLI returns a non-zero exit code after the payload is written.
+*/
+function writeCredentialSchemaMismatchJson(error) {
+	writeJson({
+		ok: false,
+		code: CREDENTIAL_SCHEMA_MISMATCH_CODE,
+		error: error.message ?? `Credential schema mismatch for "${error.manifestId}"`,
+		manifestId: error.manifestId,
+		storedFingerprint: error.storedFingerprint,
+		currentFingerprint: error.currentFingerprint,
+		uploadedAt: serializeUploadedAt(error.uploadedAt),
+		remediation: error.remediation
+	});
+}
+//#endregion
+export { renderCredentialSchemaMismatchText as n, writeCredentialSchemaMismatchJson as r, isCredentialSchemaMismatchErrorLike as t };