@mintmcp/hosted-cli 0.0.16 → 0.0.18

package/src/index.ts

@@ -6,7 +6,6 @@ import type { inferRouterInputs, inferRouterOutputs } from "@trpc/server";
 import archiver from "archiver";
 import * as fs from "fs";
 import { readFileSync } from "fs";
-import keytar from "keytar";
 import * as path from "path";
 import { dirname, join } from "path";
 import superjson from "superjson";
@@ -14,10 +13,40 @@ import { fileURLToPath } from "url";
 import z, { ZodSchema } from "zod";
 import {
   type AppRouter,
+  type GatewayId,
   HostedIdSchema,
   type HostedTransport,
   UserConfigUpdateSchema,
 } from "./api.js";
+import {
+  type Auth,
+  clearAllAuth,
+  clearSelectedAuth,
+  type Env,
+  EnvSchema,
+  formatAuthSummary,
+  getAuth,
+  getCurrentAuthAccount,
+  getSelectedAuth,
+  getTokenClaims,
+  listAuthRecords,
+  requestAndStoreAuth,
+  type StoredAuthAccount,
+  sameStoredAuthAccount,
+  useAuth,
+} from "./auth.js";
+import {
+  assertImageSupportsPlatform,
+  buildImage,
+  defaultBuildPlatform,
+  defaultLocalTestImageRef,
+  ensureDockerAvailable,
+  ensureDockerBuildxAvailable,
+  ensureImageAvailableLocally,
+  loginToRegistry,
+  pushImage,
+  smokeTestImage,
+} from "./containerBuilder.js";
 import {
   buildPartialUpdate,
   type DeployOptions,
@@ -35,10 +64,8 @@ const version = packageJson.version;
 export type CliClientAppRouterInputs = inferRouterInputs<AppRouter>;
 export type CliClientAppRouterOutputs = inferRouterOutputs<AppRouter>;
 
-const EnvSchema = z.enum(["staging", "production"]);
-type Env = z.infer<typeof EnvSchema>;
-
 const TransportSchema = z.enum(["http", "stdio"]);
+const parseTransport = argParser(TransportSchema);
 
 const TRPC_API_URL: Record<Env, string> = {
   staging: "http://localhost:3000/api.trpc",
@@ -50,147 +77,68 @@ const WEB_CLIENT_URL: Record<Env, string> = {
   production: "https://app.mintmcp.com",
 };
 
-const CLIENT_IDS: Record<Env, string> = {
-  staging: "client_01K0WB8ABW72JSBZ62V98AZMPS",
-  production: "client_01K0WB8AHKS2J39SFKAPTHTR90",
-};
-
 // Where to look for the hosted config, relative to "--base".
 const HOSTED_CONFIG_PATHS: Record<Env, string> = {
   staging: ".mintmcp/hosted-staging.json",
   production: ".mintmcp/hosted.json",
 };
 
-const HostedConfigSchema = z.object({
+const HostedConfigBaseSchema = z.object({
   hostedId: HostedIdSchema,
 
-  // Directory containing data to send to hosted server, relative to "--base".
-  mntDataDir: z.string(),
+  // Organization that owns this hosted server. Older config files may omit it.
+  organizationId: z.string().optional(),
 });
-type HostedConfig = z.infer<typeof HostedConfigSchema>;
-
-const AuthSchema = z.object({
-  accessToken: z.string(),
-  email: z.string(),
-  organizationId: z.string(),
-});
-
-type Auth = z.infer<typeof AuthSchema>;
-
-async function requestAuth(env: Env): Promise<Auth> {
-  const clientId = CLIENT_IDS[env];
-
-  const deviceCodeResponse = await fetch(
-    "https://api.workos.com/user_management/authorize/device",
-    {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/x-www-form-urlencoded",
-      },
-      body: new URLSearchParams({
-        client_id: clientId,
-      }),
-    },
-  );
-
-  if (!deviceCodeResponse.ok) {
-    throw new Error(
-      `Failed to get device code: ${await deviceCodeResponse.text()}`,
-    );
-  }
 
-  const deviceData = (await deviceCodeResponse.json()) as any;
-  const {
-    device_code: deviceCode,
-    verification_uri_complete: verificationUriComplete,
-    interval = 5,
-  } = deviceData;
+const HostedConfigSchema = z.union([
+  HostedConfigBaseSchema.extend({
+    mode: z.literal("container"),
+    image: z.string().optional(),
+    transport: TransportSchema.optional(),
 
-  console.log(`To authenticate, visit ${verificationUriComplete}`);
-
-  // Poll for access token.
-  const maxAttempts = 60;
-  for (let attempts = 0; attempts < maxAttempts; attempts += 1) {
-    await new Promise<void>((resolve) => {
-      setTimeout(resolve, interval * 1000);
-    });
-
-    const tokenResponse = await fetch(
-      "https://api.workos.com/user_management/authenticate",
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/x-www-form-urlencoded",
-        },
-        body: new URLSearchParams({
-          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
-          device_code: deviceCode,
-          client_id: clientId,
-        }),
-      },
-    );
-
-    if (!tokenResponse.ok) {
-      continue;
-    }
-
-    const tokenData = (await tokenResponse.json()) as any;
+    // Directory containing data to send to hosted server, relative to "--base".
+    mntDataDir: z.string().optional(),
+  }),
+  HostedConfigBaseSchema.extend({
+    // Directory containing data to send to hosted server, relative to "--base".
+    mntDataDir: z.string(),
+  }),
+]);
+type HostedConfig = z.infer<typeof HostedConfigSchema>;
+type DeployResult = {
+  config: HostedConfig;
+  gatewayId?: GatewayId;
+};
 
-    if (tokenData.error) {
-      if (tokenData.error === "authorization_pending") {
-        continue;
-      } else if (tokenData.error === "slow_down") {
-        // Increase interval as requested
-        await new Promise<void>((resolve) => {
-          setTimeout(resolve, 5000);
-        });
-        continue;
-      } else {
-        throw new Error(`Authentication failed: ${tokenData.error}`);
-      }
-    }
+type RegistryPushSession =
+  CliClientAppRouterOutputs["mcpHost"]["createRegistryPushSession"];
 
-    if (tokenData.access_token) {
-      if (!tokenData.user?.email) {
-        throw new Error("Authentication response missing user email");
-      }
-      if (!tokenData.organization_id) {
-        throw new Error("Authentication response missing organization ID");
-      }
-      return {
-        accessToken: tokenData.access_token,
-        email: tokenData.user.email,
-        organizationId: tokenData.organization_id,
-      };
-    }
-  }
+function storedTransport(config: HostedConfig): Transport | undefined {
+  return "mode" in config ? config.transport : undefined;
+}
 
-  throw new Error("Authentication timeout");
+function canUseDirectImageStartup(params: {
+  transport: Transport | undefined;
+  mntDataDir: string | undefined;
+}): boolean {
+  return params.transport === "http" && params.mntDataDir == undefined;
 }
 
-async function getAuth(env: Env): Promise<Auth> {
-  const keychainServiceName = "mintmcp-credentials";
-  const stored = await keytar.getPassword(keychainServiceName, env);
-  if (stored) {
-    try {
-      const parsedData = JSON.parse(stored);
-      const validatedAuth = AuthSchema.parse(parsedData);
-      return validatedAuth;
-    } catch (error) {
-      console.warn("Invalid stored credentials, re-authenticating:", error);
-      // If validation fails, delete the invalid stored credentials and re-authenticate
-      await keytar.deletePassword(keychainServiceName, env);
-    }
-  }
-  const auth = await requestAuth(env);
-  await keytar.setPassword(keychainServiceName, env, JSON.stringify(auth));
-  return auth;
+function isTRPCUnauthorized(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "data" in error &&
+    typeof (error as any).data === "object" &&
+    (error as any).data?.code === "UNAUTHORIZED"
+  );
 }
 
-async function makeAuthenticatedClient(env: Env) {
-  const auth = await getAuth(env);
+async function makeAuthenticatedClient(
+  env: Env,
+  options?: { forceRefresh?: boolean },
+) {
+  const auth = await getAuth(env, options);
 
-  // TODO: Get the organization name because that is more human readable.
   console.log(`Authenticated as ${auth.email} in ${auth.organizationId}.`);
 
   return createTRPCClient<AppRouter>({
@@ -206,6 +154,29 @@ async function makeAuthenticatedClient(env: Env) {
   });
 }
 
+type AuthenticatedClient = Awaited<ReturnType<typeof makeAuthenticatedClient>>;
+
+async function withAuthRetry<T>(
+  env: Env,
+  fn: (client: AuthenticatedClient) => Promise<T>,
+): Promise<T> {
+  const client = await makeAuthenticatedClient(env);
+  try {
+    return await fn(client);
+  } catch (error) {
+    if (isTRPCUnauthorized(error)) {
+      console.warn(
+        "Session expired or invalid. Refreshing credentials and retrying...",
+      );
+      const newClient = await makeAuthenticatedClient(env, {
+        forceRefresh: true,
+      });
+      return await fn(newClient);
+    }
+    throw error;
+  }
+}
+
 function argParser<T>(schema: ZodSchema<T>) {
   return (value: string): T => {
     const result = schema.safeParse(value);
@@ -281,7 +252,7 @@ async function uploadData(
   return { secretDataZipGcsPath: upload.secretDataZipGcsPath };
 }
 
-const DEPLOY_OPTIONS_NEW_SERVER_DEFAULTS = {
+const DEPLOY_OPTIONS_LEGACY_DEFAULTS = {
   transport: "stdio",
   // Skip install/build if already done (e.g., by startup probe or previous session).
   startupCommand:
@@ -289,32 +260,53 @@ const DEPLOY_OPTIONS_NEW_SERVER_DEFAULTS = {
   mntDataDir: ".",
 } as const;
 
+const DEPLOY_OPTIONS_CONTAINER_DEFAULTS = {
+  transport: "http",
+} as const;
+
 async function createNew(
   client: Awaited<ReturnType<typeof makeAuthenticatedClient>>,
   base: string,
+  organizationId: string,
   options: DeployOptions,
-): Promise<HostedConfig> {
-  const {
-    name,
-    transport,
-    startupCommand,
-    mntDataDir = ".",
-  } = {
-    ...DEPLOY_OPTIONS_NEW_SERVER_DEFAULTS,
+): Promise<DeployResult> {
+  const defaults = options.image
+    ? DEPLOY_OPTIONS_CONTAINER_DEFAULTS
+    : DEPLOY_OPTIONS_LEGACY_DEFAULTS;
+  const { name, image, transport, startupCommand, mntDataDir } = {
+    ...defaults,
     ...options,
   };
   if (name == undefined) {
     throw new Error("--name is a required option when creating a new server");
   }
+  if (
+    image != undefined &&
+    startupCommand == undefined &&
+    !canUseDirectImageStartup({ transport, mntDataDir })
+  ) {
+    throw new Error(
+      "--startup-command is required unless using --transport http without --mnt-data-dir",
+    );
+  }
+  if (image == undefined && startupCommand == undefined) {
+    throw new Error(
+      "Expected --startup-command to be defined after applying defaults",
+    );
+  }
 
-  const upload = await uploadData(client, path.join(base, mntDataDir));
+  const upload =
+    mntDataDir != undefined || image == undefined
+      ? await uploadData(client, path.join(base, mntDataDir ?? "."))
+      : undefined;
 
   const config = UserConfigUpdateSchema.parse({
     userGivenName: name,
-    command: startupCommand,
+    ...(image != undefined ? { image } : {}),
+    ...(startupCommand != undefined ? { command: startupCommand } : {}),
     transport: toHostedTransport(transport),
     replaceEnv: [],
-    secretDataZipGcsPath: upload.secretDataZipGcsPath,
+    ...(upload ? { secretDataZipGcsPath: upload.secretDataZipGcsPath } : {}),
   } satisfies z.input<typeof UserConfigUpdateSchema>);
 
   const createdServer = await client.mcpHost.createServer.mutate({
@@ -322,8 +314,15 @@ async function createNew(
   });
 
   return {
-    hostedId: createdServer.hostedId,
-    mntDataDir,
+    config: HostedConfigSchema.parse({
+      hostedId: createdServer.hostedId,
+      ...(image != undefined
+        ? { mode: "container" as const, image, transport }
+        : {}),
+      ...(mntDataDir != undefined ? { mntDataDir } : {}),
+      organizationId,
+    }),
+    gatewayId: createdServer.gatewayId,
   };
 }
 
@@ -331,21 +330,284 @@ async function updateExisting(
   client: Awaited<ReturnType<typeof makeAuthenticatedClient>>,
   base: string,
   config: HostedConfig,
+  organizationId: string,
   options: DeployOptions,
-): Promise<HostedConfig> {
-  const newConfig = { ...config };
-  if (options.mntDataDir != undefined) {
-    newConfig.mntDataDir = options.mntDataDir;
+): Promise<DeployResult> {
+  if (
+    config.organizationId != undefined &&
+    config.organizationId !== organizationId
+  ) {
+    throw new Error(
+      `Hosted config belongs to organization ${config.organizationId}, but the selected credentials are for ${organizationId}. Switch organizations with "hosted auth use --organization-id ${config.organizationId}" before deploying.`,
+    );
   }
-  const upload = await uploadData(
-    client,
-    path.join(base, newConfig.mntDataDir),
-  );
-  await client.mcpHost.partialUpdateServer.mutate({
+  const nextTransport = options.transport ?? storedTransport(config);
+  const clearCommand =
+    options.image != undefined &&
+    options.startupCommand == undefined &&
+    options.mntDataDir == undefined &&
+    nextTransport === "http";
+  if (
+    options.image != undefined &&
+    options.startupCommand == undefined &&
+    !clearCommand
+  ) {
+    if (options.mntDataDir != undefined) {
+      throw new Error(
+        "--startup-command is required when using --mnt-data-dir with --image",
+      );
+    }
+    if (nextTransport == undefined) {
+      throw new Error(
+        "--startup-command is required unless the resulting transport is known to be http. Pass --transport http to switch to direct image startup.",
+      );
+    }
+    throw new Error(
+      "--startup-command is required unless using --transport http without --mnt-data-dir",
+    );
+  }
+  const newConfig = HostedConfigSchema.parse({
+    ...config,
+    ...(options.mntDataDir != undefined
+      ? { mntDataDir: options.mntDataDir }
+      : {}),
+    ...(options.image != undefined
+      ? {
+          mode: "container" as const,
+          image: options.image,
+          ...(nextTransport != undefined ? { transport: nextTransport } : {}),
+        }
+      : {}),
+    ...("mode" in config && nextTransport != undefined
+      ? { transport: nextTransport }
+      : {}),
+    organizationId,
+  });
+  const upload =
+    (options.image == undefined || options.mntDataDir != undefined) &&
+    newConfig.mntDataDir != undefined
+      ? await uploadData(client, path.join(base, newConfig.mntDataDir))
+      : undefined;
+  const updatedServer = await client.mcpHost.partialUpdateServer.mutate({
     hostedId: config.hostedId,
-    update: buildPartialUpdate(options, upload.secretDataZipGcsPath),
+    update: buildPartialUpdate(options, upload?.secretDataZipGcsPath, {
+      clearCommand,
+    }),
+  });
+  return {
+    config: newConfig,
+    ...(updatedServer.gatewayId != undefined
+      ? { gatewayId: updatedServer.gatewayId }
+      : {}),
+  };
+}
+
+function connectorSettingsUrl(env: Env, gatewayId: GatewayId): string {
+  const url = new URL("/vmcps", WEB_CLIENT_URL[env]);
+  url.searchParams.set("id", gatewayId);
+  url.searchParams.set("serverTab", "connector-settings");
+  return url.toString();
+}
+
+function logDeployResult(
+  env: Env,
+  action: "Created" | "Updated",
+  result: DeployResult,
+): void {
+  if (result.gatewayId == undefined) {
+    console.log(`${action}.`);
+    return;
+  }
+  console.log(`${action} ${connectorSettingsUrl(env, result.gatewayId)}`);
+}
+
+function updateConfigAfterManagedPush(
+  config: HostedConfig,
+  organizationId: string,
+  managedImageRef: string,
+): HostedConfig {
+  return HostedConfigSchema.parse({
+    ...config,
+    mode: "container" as const,
+    image: managedImageRef,
+    organizationId,
+    ...("mode" in config && config.transport != undefined
+      ? { transport: config.transport }
+      : {}),
+  });
+}
+
+function managedRegistryImageRef(session: RegistryPushSession): string {
+  return `${session.registryHost}/${session.repository}:${session.imageTag}`;
+}
+
+async function buildAndPushManagedImage(params: {
+  client: AuthenticatedClient;
+  organizationId: string;
+  config: HostedConfig;
+  dockerfile: string;
+  context: string;
+  buildArg: string[];
+  target?: string;
+  platform: string;
+}): Promise<DeployResult> {
+  if (
+    params.config.organizationId != undefined &&
+    params.config.organizationId !== params.organizationId
+  ) {
+    throw new Error(
+      `Hosted config belongs to organization ${params.config.organizationId}, but the selected credentials are for ${params.organizationId}. Switch organizations with "hosted auth use --organization-id ${params.config.organizationId}" before building and pushing.`,
+    );
+  }
+
+  const session = await params.client.mcpHost.createRegistryPushSession.mutate({
+    hostedId: params.config.hostedId,
+  });
+
+  const deployImageRef = managedRegistryImageRef(session);
+  const buildResult = buildImage({
+    dockerfile: params.dockerfile,
+    context: params.context,
+    buildArgs: params.buildArg,
+    ...(params.target != undefined ? { target: params.target } : {}),
+    platform: params.platform,
+    imageRef: deployImageRef,
+  });
+
+  loginToRegistry(session.registryHost, session.username, session.password);
+  pushImage(buildResult.imageRef);
+
+  const finalized = await params.client.mcpHost.finalizeRegistryPush.mutate({
+    hostedId: params.config.hostedId,
+    finalizeToken: session.finalizeToken,
+  });
+
+  return {
+    config: updateConfigAfterManagedPush(
+      params.config,
+      params.organizationId,
+      deployImageRef,
+    ),
+    ...(finalized.gatewayId != undefined
+      ? { gatewayId: finalized.gatewayId }
+      : {}),
+  };
+}
+
+function buildManagedImageCreateConfig(params: {
+  name?: string;
+  transport?: Transport;
+  startupCommand?: string;
+}) {
+  const transport = params.transport ?? "http";
+  if (params.name == undefined) {
+    throw new Error(
+      "--name is a required option when building and pushing a new managed image connector",
+    );
+  }
+  if (
+    params.startupCommand == undefined &&
+    !canUseDirectImageStartup({ transport, mntDataDir: undefined })
+  ) {
+    throw new Error(
+      "--startup-command is required unless using --transport http",
+    );
+  }
+  return UserConfigUpdateSchema.omit({ image: true }).parse({
+    userGivenName: params.name,
+    ...(params.startupCommand != undefined
+      ? { command: params.startupCommand }
+      : {}),
+    transport: toHostedTransport(transport),
+    replaceEnv: [],
+  });
+}
+
+async function buildAndPushManagedImageForCreate(params: {
+  client: AuthenticatedClient;
+  organizationId: string;
+  name?: string;
+  transport?: Transport;
+  startupCommand?: string;
+  dockerfile: string;
+  context: string;
+  buildArg: string[];
+  target?: string;
+  platform: string;
+}): Promise<DeployResult> {
+  const config = buildManagedImageCreateConfig({
+    ...(params.name != undefined ? { name: params.name } : {}),
+    ...(params.transport != undefined ? { transport: params.transport } : {}),
+    ...(params.startupCommand != undefined
+      ? { startupCommand: params.startupCommand }
+      : {}),
+  });
+
+  const session =
+    await params.client.mcpHost.createRegistryPushSessionForCreate.mutate({});
+  const deployImageRef = managedRegistryImageRef(session);
+  const buildResult = buildImage({
+    dockerfile: params.dockerfile,
+    context: params.context,
+    buildArgs: params.buildArg,
+    ...(params.target != undefined ? { target: params.target } : {}),
+    platform: params.platform,
+    imageRef: deployImageRef,
+  });
+
+  loginToRegistry(session.registryHost, session.username, session.password);
+  pushImage(buildResult.imageRef);
+
+  const finalized =
+    await params.client.mcpHost.finalizeRegistryPushCreate.mutate({
+      finalizeToken: session.finalizeToken,
+      config,
+    });
+
+  return {
+    config: HostedConfigSchema.parse({
+      hostedId: finalized.hostedId,
+      organizationId: params.organizationId,
+      mode: "container" as const,
+      image: deployImageRef,
+      ...(params.transport != undefined
+        ? { transport: params.transport }
+        : { transport: "http" as const }),
+    }),
+    gatewayId: finalized.gatewayId,
+  };
+}
+
+async function deployWithOptions(
+  env: Env,
+  base: string,
+  options: DeployOptions,
+): Promise<void> {
+  const auth = await getAuth(env);
+
+  await withAuthRetry(env, async (client) => {
+    const configPath = path.join(base, HOSTED_CONFIG_PATHS[env]);
+
+    let result: DeployResult;
+    if (fs.existsSync(configPath)) {
+      console.log("Updating existing server...");
+      const configData = fs.readFileSync(configPath, "utf8");
+      result = await updateExisting(
+        client,
+        base,
+        HostedConfigSchema.parse(JSON.parse(configData)),
+        auth.organizationId,
+        options,
+      );
+      logDeployResult(env, "Updated", result);
+    } else {
+      console.log("Creating new server...");
+      result = await createNew(client, base, auth.organizationId, options);
+      logDeployResult(env, "Created", result);
+    }
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(result.config, null, 2));
   });
-  return newConfig;
 }
 
 const program = new Command()
@@ -361,11 +623,109 @@ const program = new Command()
   .option("-b, --base <base>", "base directory for config and data.", ".");
 
 function makeDefaultMessage(
-  optionName: keyof typeof DEPLOY_OPTIONS_NEW_SERVER_DEFAULTS,
+  optionName: keyof typeof DEPLOY_OPTIONS_LEGACY_DEFAULTS,
 ): string {
-  return `Defaults to '${DEPLOY_OPTIONS_NEW_SERVER_DEFAULTS[optionName]}' for new servers.`;
+  return `For new zip-based servers, defaults to '${DEPLOY_OPTIONS_LEGACY_DEFAULTS[optionName]}'.`;
+}
+
+function collect(value: string, previous: string[]): string[] {
+  return previous.concat([value]);
 }
 
+function parsePositiveInt(value: string): number {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new InvalidArgumentError("Expected a positive integer.");
+  }
+  return parsed;
+}
+
+function shouldBuildTestImage(options: {
+  build?: boolean;
+  image?: string;
+  dockerfile?: string;
+  context?: string;
+  buildArg?: string[];
+  target?: string;
+}): boolean {
+  if (options.build) {
+    return true;
+  }
+  if (options.image == undefined) {
+    return true;
+  }
+  if (options.dockerfile !== undefined && options.dockerfile !== "Dockerfile") {
+    return true;
+  }
+  if (options.context !== undefined && options.context !== ".") {
+    return true;
+  }
+  if ((options.buildArg?.length ?? 0) > 0) {
+    return true;
+  }
+  return options.target != undefined;
+}
+
+const authCommand = program
+  .command("auth")
+  .description("Manage cached hosted-cli authentication credentials.");
+
+authCommand
+  .command("login")
+  .description(
+    "Authenticate and cache credentials for the current environment.",
+  )
+  .action(async () => {
+    const { env } = program.opts();
+    const auth = await requestAndStoreAuth(env);
+    console.log(`Cached ${formatAuthSummary(auth)}.`);
+  });
+
+authCommand
+  .command("list")
+  .description("List cached credentials for the current environment.")
+  .action(async () => {
+    const { env } = program.opts();
+    const currentAccount = await getCurrentAuthAccount(env);
+    const records = await listAuthRecords(env);
+    if (records.length === 0) {
+      console.log(`No cached credentials found for ${env}.`);
+      return;
+    }
+    for (const record of records) {
+      const marker =
+        currentAccount && sameStoredAuthAccount(record.account, currentAccount)
+          ? "*"
+          : " ";
+      console.log(`${marker} ${formatAuthSummary(record.auth)}`);
+    }
+  });
+
+authCommand
+  .command("use")
+  .description("Select which cached credentials the CLI should use.")
+  .option("--user-id <id>", "WorkOS user ID to select.")
+  .option("--email <email>", "Email address to select.")
+  .option("--organization-id <id>", "Organization ID to select.")
+  .action(
+    async (options: {
+      userId?: string;
+      email?: string;
+      organizationId?: string;
+    }) => {
+      const { env } = program.opts();
+      if (!options.userId && !options.email && !options.organizationId) {
+        throw new Error(
+          'Specify at least one filter, for example "hosted auth use --organization-id <id>".',
+        );
+      }
+      const result = await useAuth(env, options);
+      const message =
+        result.mode === "switched" ? "Cached and selected" : "Selected";
+      console.log(`${message} ${formatAuthSummary(result.auth)}.`);
+    },
+  );
+
 program
   .command("deploy")
   .description("Create or update a hosted server.")
@@ -373,14 +733,18 @@ program
     "-n, --name <name>",
     "Name of the hosted server. Required for new servers.",
   )
+  .option(
+    "--image <ref>",
+    "Container image reference (e.g., ghcr.io/org/repo:tag). Skips zip upload when --mnt-data-dir is not also supplied.",
+  )
   .option(
     "-t, --transport <transport>",
-    `Transport (stdio or http). ${makeDefaultMessage("transport")}`,
+    `Transport (stdio or http). Defaults to 'http' for image-based creates. ${makeDefaultMessage("transport")}`,
     argParser(TransportSchema),
   )
   .option(
     "--startup-command <command>",
-    `Command that runs on hosted container to start the server (runs in bash). ${makeDefaultMessage("startupCommand")}`,
+    `Command that runs on hosted container to start the server (runs in bash). Required for stdio and zip-backed image deploys. ${makeDefaultMessage("startupCommand")}`,
   )
   .option(
     "--mnt-data-dir <directory>",
@@ -388,32 +752,283 @@ program
   )
   .action(async (options) => {
     const { env, base } = program.opts();
-    const client = await makeAuthenticatedClient(env);
+    await deployWithOptions(env, base, options);
+  });
+
+program
+  .command("test-image")
+  .description(
+    "Run a local MCP smoke test against a container image. Builds the current Dockerfile by default; with --image, tests that existing image directly.",
+  )
+  .option(
+    "--image <ref>",
+    "Existing image reference to test directly, or the output tag to build when --build or other build options are supplied.",
+  )
+  .option(
+    "--build",
+    "Force a local build before testing, even when --image is supplied.",
+  )
+  .option("--dockerfile <path>", "Path to Dockerfile", "Dockerfile")
+  .option("--context <dir>", "Docker build context directory", ".")
+  .option(
+    "--build-arg <arg>",
+    "Build arguments (KEY=VALUE), repeatable",
+    collect,
+    [],
+  )
+  .option("--target <target>", "Multi-stage build target")
+  .option(
+    "--probe-path <path>",
+    "HTTP path to probe with MCP initialize",
+    "/mcp",
+  )
+  .option(
+    "--probe-timeout-ms <ms>",
+    "How long to wait for the local MCP probe to succeed",
+    parsePositiveInt,
+    30_000,
+  )
+  .option(
+    "--env <entry>",
+    "Container runtime env vars for the local smoke test (KEY=VALUE), repeatable",
+    collect,
+    [],
+  )
+  .option(
+    "--env-file <path>",
+    "Path to a Docker env file for the local smoke test",
+  )
+  .action(async (options) => {
+    ensureDockerAvailable();
+    ensureDockerBuildxAvailable();
+
+    const shouldBuild = shouldBuildTestImage(options);
+    const imageRef = options.image ?? defaultLocalTestImageRef();
+
+    if (shouldBuild) {
+      buildImage({
+        dockerfile: options.dockerfile,
+        context: options.context,
+        buildArgs: options.buildArg,
+        ...(options.target != undefined ? { target: options.target } : {}),
+        imageRef,
+      });
+    } else {
+      ensureImageAvailableLocally(imageRef);
+    }
+
+    await smokeTestImage({
+      imageRef,
+      probePath: options.probePath,
+      probeTimeoutMs: options.probeTimeoutMs,
+      env: options.env,
+      ...(options.envFile != undefined ? { envFile: options.envFile } : {}),
+    });
+  });
+
+program
+  .command("build-and-push")
+  .description(
+    "Build a Docker image, push it through the managed registry, and finalize the hosted connector image update or creation.",
+  )
+  .option("--dockerfile <path>", "Path to Dockerfile", "Dockerfile")
+  .option("--context <dir>", "Docker build context directory", ".")
+  .option(
+    "--build-arg <arg>",
+    "Build arguments (KEY=VALUE), repeatable",
+    collect,
+    [],
+  )
+  .option("--target <target>", "Multi-stage build target")
+  .option(
+    "--platform <platform>",
+    `Target platform to build for before push. Defaults to '${defaultBuildPlatform()}'.`,
+    defaultBuildPlatform(),
+  )
+  .option(
+    "--name <name>",
+    "Connector name when creating a new hosted connector",
+  )
+  .option(
+    "--transport <transport>",
+    "Transport to configure when creating a new managed connector",
+    parseTransport,
+  )
+  .option(
+    "--startup-command <command>",
+    "Startup command to configure when creating a new managed connector",
+  )
+  .action(async (options) => {
+    const { env, base } = program.opts();
+
+    ensureDockerAvailable();
+    ensureDockerBuildxAvailable();
+
+    if (options.platform !== defaultBuildPlatform()) {
+      console.warn(
+        `Building for ${options.platform}. Hosted deployments typically target ${defaultBuildPlatform()}; choose a different platform only when you know the runtime is compatible.`,
+      );
+    }
 
     const configPath = path.join(base, HOSTED_CONFIG_PATHS[env]);
+    const auth = await getAuth(env);
+    const hasExistingConfig = fs.existsSync(configPath);
 
-    let newOrUpdatedConfig: HostedConfig;
-    if (fs.existsSync(configPath)) {
-      console.log("Updating existing server...");
-      const configData = fs.readFileSync(configPath, "utf8");
-      newOrUpdatedConfig = await updateExisting(
+    const result = await withAuthRetry(env, async (client) => {
+      if (hasExistingConfig) {
+        const config = HostedConfigSchema.parse(
+          JSON.parse(fs.readFileSync(configPath, "utf8")),
+        );
+        return await buildAndPushManagedImage({
+          client,
+          organizationId: auth.organizationId,
+          config,
+          dockerfile: options.dockerfile,
+          context: options.context,
+          buildArg: options.buildArg,
+          ...(options.target != undefined ? { target: options.target } : {}),
+          platform: options.platform,
+        });
+      }
+
+      return await buildAndPushManagedImageForCreate({
         client,
-        base,
-        HostedConfigSchema.parse(JSON.parse(configData)),
-        options,
-      );
-      console.log(
-        `Updated ${WEB_CLIENT_URL[env]}/hosted/${newOrUpdatedConfig.hostedId}`,
+        organizationId: auth.organizationId,
+        ...(options.name != undefined ? { name: options.name } : {}),
+        ...(options.transport != undefined
+          ? { transport: options.transport }
+          : {}),
+        ...(options.startupCommand != undefined
+          ? { startupCommand: options.startupCommand }
+          : {}),
+        dockerfile: options.dockerfile,
+        context: options.context,
+        buildArg: options.buildArg,
+        ...(options.target != undefined ? { target: options.target } : {}),
+        platform: options.platform,
+      });
+    });
+
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(result.config, null, 2));
+    logDeployResult(env, hasExistingConfig ? "Updated" : "Created", result);
+  });
+
+program
+  .command("build-and-deploy")
+  .description(
+    "Build a Docker image for hosted deployment, push it, verify the target platform, and deploy it.",
+  )
+  .requiredOption(
+    "--image <ref>",
+    "Image reference to build, push, and deploy (e.g., ghcr.io/org/repo:tag).",
+  )
+  .option("--dockerfile <path>", "Path to Dockerfile", "Dockerfile")
+  .option("--context <dir>", "Docker build context directory", ".")
+  .option(
+    "--build-arg <arg>",
+    "Build arguments (KEY=VALUE), repeatable",
+    collect,
+    [],
+  )
+  .option("--target <target>", "Multi-stage build target")
+  .option(
+    "--platform <platform>",
+    `Target platform to build for before deploy. Defaults to '${defaultBuildPlatform()}'.`,
+    defaultBuildPlatform(),
+  )
+  .option(
+    "-n, --name <name>",
+    "Name of the hosted server. Required for new servers.",
+  )
+  .option(
+    "-t, --transport <transport>",
+    `Transport (stdio or http). Defaults to 'http' for image-based creates. ${makeDefaultMessage("transport")}`,
+    argParser(TransportSchema),
+  )
+  .option(
+    "--startup-command <command>",
+    `Command that runs on hosted container to start the server (runs in bash). Required for stdio and zip-backed image deploys. ${makeDefaultMessage("startupCommand")}`,
+  )
+  .option(
+    "--mnt-data-dir <directory>",
+    `Directory to copy to /mnt on the server. ${makeDefaultMessage("mntDataDir")}`,
+  )
+  .action(async (options) => {
+    const { env, base } = program.opts();
+
+    ensureDockerAvailable();
+    ensureDockerBuildxAvailable();
+
+    if (options.platform !== defaultBuildPlatform()) {
+      console.warn(
+        `Building for ${options.platform}. Hosted deployments typically target ${defaultBuildPlatform()}; choose a different platform only when you know the runtime is compatible.`,
       );
+    }
+
+    const buildResult = buildImage({
+      dockerfile: options.dockerfile,
+      context: options.context,
+      buildArgs: options.buildArg,
+      ...(options.target != undefined ? { target: options.target } : {}),
+      platform: options.platform,
+      imageRef: options.image,
+    });
+
+    pushImage(buildResult.imageRef);
+    assertImageSupportsPlatform(buildResult.imageRef, options.platform);
+
+    await deployWithOptions(env, base, {
+      image: buildResult.imageRef,
+      ...(options.name != undefined ? { name: options.name } : {}),
+      ...(options.transport != undefined
+        ? { transport: options.transport }
+        : {}),
+      ...(options.startupCommand != undefined
+        ? { startupCommand: options.startupCommand }
+        : {}),
+      ...(options.mntDataDir != undefined
+        ? { mntDataDir: options.mntDataDir }
+        : {}),
+    });
+  });
+
+program
+  .command("logout")
+  .description(
+    "Clear stored credentials and sign out of the WorkOS browser session.",
+  )
+  .option("--all", "Clear all cached credentials for the current environment.")
+  .action(async (options: { all?: boolean }) => {
+    const { env } = program.opts();
+
+    let logoutUrl: string | undefined;
+
+    const selectedAuth = await getSelectedAuth(env);
+    if (selectedAuth) {
+      const { sid } = getTokenClaims(selectedAuth.accessToken);
+      if (sid) {
+        logoutUrl = `https://api.workos.com/user_management/sessions/logout?session_id=${sid}`;
+      }
+    }
+
+    if (options.all) {
+      await clearAllAuth(env);
+      console.log(`All cached credentials cleared for ${env}.`);
     } else {
-      console.log("Creating new server...");
-      newOrUpdatedConfig = await createNew(client, base, options);
-      console.log(
-        `Created ${WEB_CLIENT_URL[env]}/hosted/${newOrUpdatedConfig.hostedId}`,
-      );
+      const clearedAuth = await clearSelectedAuth(env);
+      if (clearedAuth) {
+        console.log(
+          `Cleared cached credentials for ${formatAuthSummary(clearedAuth)}.`,
+        );
+      } else {
+        console.log(`No cached credentials found for ${env}.`);
+      }
+    }
+    if (logoutUrl) {
+      console.log("To fully sign out of the WorkOS browser session, visit:");
+      console.log(logoutUrl);
     }
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, JSON.stringify(newOrUpdatedConfig, null, 2));
   });
 
 program.parse();