@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/cli/deploy-readiness.ts

@@ -0,0 +1,481 @@
+import { findAgentCapsuleRoot, loadAgentCapsule } from "../runtime/config";
+import { loadDeployReadinessContext, type DeployReadinessContext } from "../runtime/deploy-readiness";
+import { loadCapsuleEnv } from "../runtime/env";
+import { isAgentKitError } from "../runtime/errors";
+import { MANAGED_COMPOSIO_API_KEY_SECRET, MANAGED_COMPOSIO_ENTITLEMENT } from "../runtime/integrations/composio";
+import {
+  cloudApiRequest,
+  formatCloudAuthSource,
+  readCloudAuthForApiUrl,
+  type CloudCapabilitiesResponse,
+  type CloudLimitsResponse,
+  type CloudManagedComposioResponse,
+  type CloudMeResponse,
+  type CloudProjectResolveResponse,
+  type CloudSecretsResponse,
+} from "./cloud-client";
+
+type DeployReadinessStatus = "pass" | "fail" | "warn" | "info";
+
+type DeployReadinessCheck = {
+  status: DeployReadinessStatus;
+  title: string;
+  message: string;
+  action?: string;
+};
+
+type DeployReadinessReport = {
+  ok: boolean;
+  apiUrl: string;
+  context: DeployReadinessContext;
+  checks: DeployReadinessCheck[];
+};
+
+export async function checkDeployReadiness(options: {
+  apiUrl: string;
+  requireLogin: boolean;
+}): Promise<DeployReadinessReport> {
+  const context = await loadDeployReadinessContext(process.cwd(), process.env);
+  const auth = options.requireLogin ? await readCloudAuthForApiUrl(options.apiUrl) : null;
+  const checks: DeployReadinessCheck[] = [];
+  let cloudAuthUsable = false;
+
+  if (context.runtime !== "edge") {
+    checks.push({
+      status: "fail",
+      title: "Target runtime",
+      message: 'Cloudflare deploy requires runtime: "edge" in agentkit.config.ts.',
+      action: "set runtime: \"edge\" before deploying to AgentKit Cloud",
+    });
+  } else {
+    checks.push({
+      status: "pass",
+      title: "Target runtime",
+      message: "Capsule is configured for edge deploy.",
+    });
+  }
+
+  const nodeMajor = majorNodeVersion(process.versions.node);
+  if (nodeMajor !== null && nodeMajor < 24) {
+    checks.push({
+      status: "warn",
+      title: "Node version",
+      message: `@andreprado/agentkit requires Node >=24; current Node is ${process.versions.node}.`,
+      action: "use Node 24+ before running direct node imports or production container commands",
+    });
+  } else {
+    checks.push({
+      status: "pass",
+      title: "Node version",
+      message: `Node ${process.versions.node} satisfies @andreprado/agentkit engines.node >=24.`,
+    });
+  }
+
+  if (!auth?.token) {
+    checks.push({
+      status: options.requireLogin ? "fail" : "warn",
+      title: "Login",
+      message: options.requireLogin
+        ? "No AgentKit Cloud token was found for hosted production deploy."
+        : "No AgentKit Cloud token was found; deploy will request anonymous mode.",
+      action: "agentkit login --token <token>",
+    });
+  } else {
+    try {
+      const me = (await cloudApiRequest(options.apiUrl, "/v1/me", { method: "GET" })) as CloudMeResponse;
+      const email = me.account?.email;
+      checks.push({
+        status: "pass",
+        title: "Login",
+        message: email ? `Authenticated as ${email}.` : "AgentKit Cloud token is accepted.",
+      });
+      cloudAuthUsable = true;
+    } catch (error) {
+      checks.push({
+        status: "fail",
+        title: "Login",
+        message: `AgentKit Cloud rejected the token from ${formatCloudAuthSource(auth)}. ${formatReadinessError(error)}`,
+        action: "agentkit login --token <token>",
+      });
+    }
+  }
+
+  if (cloudAuthUsable) {
+    try {
+      context.projectId = await resolveCloudProjectId(options.apiUrl, context.projectName);
+    } catch (error) {
+      checks.push({
+        status: "fail",
+        title: "Project identity",
+        message: `Could not resolve the account-scoped AgentKit Cloud project. ${formatReadinessError(error)}`,
+      });
+      cloudAuthUsable = false;
+    }
+  }
+
+  if (cloudAuthUsable) {
+    try {
+      const payload = (await cloudApiRequest(options.apiUrl, "/v1/me/capabilities", {
+        method: "GET",
+      })) as CloudCapabilitiesResponse;
+      const capabilities = payload.capabilities ?? [];
+      const hasCloudflareAlpha = capabilities.some(
+        (capability) => capability.name === "cloudflare_deploy_alpha" && capability.status === "active",
+      );
+      const hasManagedComposio = capabilities.some(
+        (capability) => capability.name === MANAGED_COMPOSIO_ENTITLEMENT && capability.status === "active",
+      );
+
+      checks.push({
+        status: hasCloudflareAlpha ? "pass" : "fail",
+        title: "Deploy entitlement",
+        message: hasCloudflareAlpha
+          ? "cloudflare_deploy_alpha is active."
+          : "This account is missing the cloudflare_deploy_alpha entitlement.",
+        ...(hasCloudflareAlpha ? {} : { action: "log in with an invited AgentKit Cloud alpha token" }),
+      });
+
+      if (context.integrations.managedComposio.enabled) {
+        checks.push({
+          status: hasManagedComposio ? "pass" : "fail",
+          title: "Managed Composio entitlement",
+          message: hasManagedComposio
+            ? `${MANAGED_COMPOSIO_ENTITLEMENT} is active.`
+            : `This capsule uses AgentKit-managed Composio, but this account is missing ${MANAGED_COMPOSIO_ENTITLEMENT}.`,
+          ...(hasManagedComposio ? {} : { action: "upgrade the AgentKit Cloud account or ask an operator to grant managed_composio" }),
+        });
+      }
+    } catch (error) {
+      checks.push({
+        status: "fail",
+        title: "Deploy entitlement",
+        message: `Could not verify AgentKit Cloud capabilities. ${formatReadinessError(error)}`,
+      });
+    }
+
+    try {
+      const payload = (await cloudApiRequest(options.apiUrl, "/v1/me/limits", {
+        method: "GET",
+      })) as CloudLimitsResponse;
+      const account = payload.online_agents?.account;
+      const global = payload.online_agents?.global;
+      const accountLimit = normalizeOptionalNumber(account?.limit);
+      const accountUsed = normalizeOptionalNumber(account?.used);
+      const globalLimit = normalizeOptionalNumber(global?.limit);
+      const globalUsed = normalizeOptionalNumber(global?.used);
+
+      if (accountLimit !== undefined && accountUsed !== undefined && accountUsed >= accountLimit) {
+        checks.push({
+          status: "fail",
+          title: "Online agent capacity",
+          message: `This account is already using ${accountUsed}/${accountLimit} online AgentKit deploys.`,
+          action: "agentkit deploy pause",
+        });
+      } else if (globalLimit !== undefined && globalUsed !== undefined && globalUsed >= globalLimit) {
+        checks.push({
+          status: "fail",
+          title: "Online agent capacity",
+          message: `AgentKit Cloud is already using ${globalUsed}/${globalLimit} global online deploy slots.`,
+          action: "agentkit deploy status",
+        });
+      } else if (accountLimit !== undefined && accountUsed !== undefined) {
+        checks.push({
+          status: "pass",
+          title: "Online agent capacity",
+          message: `Account has capacity: ${accountUsed}/${accountLimit} online deploys are in use.`,
+        });
+      } else if (globalLimit !== undefined && globalUsed !== undefined) {
+        checks.push({
+          status: "pass",
+          title: "Online agent capacity",
+          message: `Global capacity is available: ${globalUsed}/${globalLimit} online deploys are in use.`,
+        });
+      } else {
+        checks.push({
+          status: "info",
+          title: "Online agent capacity",
+          message: "No online deploy limit is configured for this account.",
+        });
+      }
+    } catch (error) {
+      checks.push({
+        status: "warn",
+        title: "Online agent capacity",
+        message: `Could not verify online deploy capacity. ${formatReadinessError(error)}`,
+      });
+    }
+
+    if (context.integrations.managedComposio.enabled) {
+      try {
+        const payload = (await cloudApiRequest(
+          options.apiUrl,
+          `/v1/me/managed-composio?toolkits=${encodeURIComponent(context.integrations.managedComposio.toolkits.join(","))}`,
+          {
+            method: "GET",
+          },
+        )) as CloudManagedComposioResponse;
+        const managed = payload.managed_composio;
+        const missingToolkits = (managed?.toolkits ?? []).filter((toolkit) => toolkit.auth_config !== "set");
+
+        if (managed?.api_key !== "set") {
+          checks.push({
+            status: "fail",
+            title: "Managed Composio API key",
+            message: `AgentKit Cloud is missing AGENTKIT_SECRET_${MANAGED_COMPOSIO_API_KEY_SECRET}.`,
+            action: "ask the AgentKit Cloud operator to configure managed Composio",
+          });
+        } else {
+          checks.push({
+            status: "pass",
+            title: "Managed Composio API key",
+            message: "AgentKit Cloud has the managed COMPOSIO_API_KEY.",
+          });
+        }
+
+        if (missingToolkits.length > 0) {
+          checks.push({
+            status: "fail",
+            title: "Managed Composio auth configs",
+            message: `Missing ${missingToolkits
+              .map((toolkit) => `${toolkit.auth_config_env ?? "auth config"} for ${toolkit.toolkit ?? "unknown"}`)
+              .join(", ")}.`,
+            action: "ask the AgentKit Cloud operator to configure the Composio auth config registry or fallback env",
+          });
+        } else {
+          const toolkitSources = (managed?.toolkits ?? []).map((toolkit) =>
+            `${toolkit.toolkit ?? "unknown"}${toolkit.auth_config_source ? ` via ${toolkit.auth_config_source}` : ""}`,
+          );
+          checks.push({
+            status: "pass",
+            title: "Managed Composio auth configs",
+            message: `Auth configs are available for ${toolkitSources.join(", ")}.`,
+          });
+        }
+      } catch (error) {
+        checks.push({
+          status: "warn",
+          title: "Managed Composio auth configs",
+          message: `Could not verify managed Composio auth configs. ${formatReadinessError(error)}`,
+        });
+      }
+    }
+  }
+
+  if (context.agentKitManagedSecrets.length > 0) {
+    checks.push({
+      status: "info",
+      title: "AgentKit-managed secrets",
+      message: `${context.agentKitManagedSecrets.join(", ")} ${
+        context.agentKitManagedSecrets.length === 1 ? "is" : "are"
+      } provisioned by AgentKit Cloud during deploy.`,
+    });
+  }
+
+  if (context.integrations.managedComposio.enabled) {
+    if (!options.requireLogin) {
+      checks.push({
+        status: "fail",
+        title: "Managed Composio access",
+        message: "AgentKit-managed Composio is paid hosted infrastructure and cannot be used by anonymous deploys.",
+        action: "run agentkit deploy without --anonymous after logging in with a paid AgentKit Cloud account",
+      });
+    } else {
+      checks.push({
+        status: "info",
+        title: "Managed Composio",
+        message: `Configured for ${context.integrations.managedComposio.toolkits.join(", ")} with ${
+          context.integrations.managedComposio.toolCount
+        } allowed action${context.integrations.managedComposio.toolCount === 1 ? "" : "s"}. AgentKit Cloud injects COMPOSIO_API_KEY.`,
+      });
+    }
+  }
+
+  if (context.accessMode === "private") {
+    checks.push({
+      status: "info",
+      title: "Private access",
+      message: "AGENTKIT_PRIVATE_TOKEN is required at runtime; AgentKit Cloud generates it and saves it in .agentkit/deploy.json.",
+    });
+  }
+
+  if (context.knowledge.enabled) {
+    if (context.knowledge.databaseDriver !== "turso") {
+      checks.push({
+        status: "fail",
+        title: "Knowledge storage",
+        message: "Hosted Knowledge requires a Turso database so indexed chunks are available to the Cloudflare runtime.",
+        action: 'set storage.database.driver: "turso" in agentkit.config.ts before deploying Knowledge',
+      });
+    } else {
+      checks.push({
+        status: "pass",
+        title: "Knowledge storage",
+        message: `Knowledge is configured with ${context.knowledge.sourceCount} source${
+          context.knowledge.sourceCount === 1 ? "" : "s"
+        } and Turso storage.`,
+      });
+    }
+  }
+
+  if (context.userManagedSecrets.length === 0) {
+    checks.push({
+      status: "pass",
+      title: "Hosted secrets",
+      message: "No user-managed hosted secrets are required by this capsule.",
+    });
+  } else if (!cloudAuthUsable) {
+    checks.push({
+      status: options.requireLogin ? "fail" : "warn",
+      title: "Hosted secrets",
+      message: `Could not check hosted secrets without a valid AgentKit Cloud login. Required: ${context.userManagedSecrets.join(", ")}.`,
+      action: "agentkit secret list",
+    });
+  } else {
+    try {
+      const payload = (await cloudApiRequest(
+        options.apiUrl,
+        `/v1/projects/${encodeURIComponent(context.projectId)}/secrets`,
+        { method: "GET" },
+      )) as CloudSecretsResponse;
+      const hostedSecretNames = new Set((payload.secrets ?? []).map((secret) => secret.name).filter(isString));
+      const missing = context.userManagedSecrets.filter((name) => !hostedSecretNames.has(name));
+
+      if (missing.length === 0) {
+        checks.push({
+          status: "pass",
+          title: "Hosted secrets",
+          message: "All user-managed hosted secrets are set.",
+        });
+      } else {
+        for (const secret of missing) {
+          const localSource = context.localSecrets[secret];
+          checks.push({
+            status: "fail",
+            title: `Hosted secret ${secret}`,
+            message: localSource
+              ? `${secret} is present locally but has not been set in AgentKit Cloud.`
+              : `${secret} is required but missing from AgentKit Cloud.`,
+            action: secretSetCommand(secret, localSource),
+          });
+        }
+      }
+    } catch (error) {
+      checks.push({
+        status: "fail",
+        title: "Hosted secrets",
+        message: `Could not list hosted secrets for project ${context.projectId}. ${formatReadinessError(error)}`,
+        action: "agentkit secret list",
+      });
+    }
+  }
+
+  return {
+    ok: checks.every((check) => check.status !== "fail"),
+    apiUrl: options.apiUrl,
+    context,
+    checks,
+  };
+}
+
+export function printDeployReadinessReport(report: DeployReadinessReport): void {
+  console.log("AgentKit deploy readiness");
+  console.log(`Project: ${report.context.projectName}`);
+  console.log(`Project ID: ${report.context.projectId}`);
+  console.log(`Target: ${report.context.target}`);
+  console.log(`API: ${report.apiUrl}`);
+  console.log("");
+
+  for (const check of report.checks) {
+    console.log(`[${check.status}] ${check.title}: ${check.message}`);
+
+    if (check.action) {
+      console.log(`  Run: ${check.action}`);
+    }
+  }
+}
+
+export async function syncHostedSecretsFromLocal(options: { apiUrl: string; projectId: string }): Promise<void> {
+  const context = await loadDeployReadinessContext(process.cwd(), process.env);
+  const localEnv = await loadCapsuleEnv(context.root, {});
+  let synced = 0;
+  let skipped = 0;
+
+  for (const secret of context.userManagedSecrets) {
+    const value = localEnv[secret];
+
+    if (value === undefined) {
+      skipped += 1;
+      console.log(`${secret}\tskipped_missing_local`);
+      continue;
+    }
+
+    await cloudApiRequest(options.apiUrl, `/v1/projects/${encodeURIComponent(options.projectId)}/secrets/${encodeURIComponent(secret)}`, {
+      method: "PUT",
+      body: JSON.stringify({ value }),
+    });
+    synced += 1;
+    console.log(`${secret}\tsynced`);
+  }
+
+  if (context.userManagedSecrets.length === 0) {
+    console.log("No user-managed hosted secrets are declared by this capsule.");
+    return;
+  }
+
+  console.log("");
+  console.log(`${synced} synced, ${skipped} skipped`);
+}
+
+export function formatReadinessError(error: unknown): string {
+  if (isAgentKitError(error)) {
+    return `${error.code}: ${error.message}`;
+  }
+
+  return error instanceof Error ? error.message : String(error);
+}
+
+export async function resolveProjectIdForSecretCommand(cwd: string, apiUrl: string): Promise<string> {
+  const root = await findAgentCapsuleRoot(cwd);
+  const capsule = await loadAgentCapsule(root);
+  return resolveCloudProjectId(apiUrl, capsule.config.name);
+}
+
+async function resolveCloudProjectId(apiUrl: string, projectName: string): Promise<string> {
+  const payload = (await cloudApiRequest(apiUrl, "/v1/projects/resolve", {
+    method: "POST",
+    body: JSON.stringify({ project_name: projectName }),
+  })) as CloudProjectResolveResponse;
+  const projectId = payload.project?.id;
+
+  if (!projectId) {
+    throw new Error("AgentKit Cloud did not return a project id.");
+  }
+
+  return projectId;
+}
+
+function secretSetCommand(secret: string, source: DeployReadinessContext["localSecrets"][string] | undefined): string {
+  if (source?.dotenv) {
+    return `npm run agentkit -- secret set ${secret} --from-local-env`;
+  }
+
+  if (source?.environment) {
+    return `npm run agentkit -- secret set ${secret} --from-env`;
+  }
+
+  return `npm run agentkit -- secret set ${secret} --stdin`;
+}
+
+function normalizeOptionalNumber(value: number | null | undefined): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function majorNodeVersion(version: string): number | null {
+  const [major] = version.split(".");
+  const parsed = Number(major);
+  return Number.isInteger(parsed) ? parsed : null;
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}

package/src/cli/flags.ts

@@ -0,0 +1,162 @@
+import { listTargetsWithCapability } from "../runtime/core/targets";
+import { loadCapsuleEnv } from "../runtime/env";
+import { AgentKitError } from "../runtime/errors";
+import { defaultAgentKitCloudApiUrl } from "./constants";
+
+export function parsePort(value: string | boolean | undefined, usage = "agentkit dev --port <number>"): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value !== "string") {
+    throw new Error(`Missing port. Usage: ${usage}`);
+  }
+
+  const port = Number(value);
+
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`Invalid port. Usage: ${usage}`);
+  }
+
+  return port;
+}
+
+export function parseTargetFlag(value: string | boolean | undefined, capability: "build" | "deploy"): string {
+  if (value === undefined) {
+    return "cloudflare";
+  }
+
+  if (typeof value !== "string") {
+    throw new Error(
+      `Missing target. Usage: agentkit ${capability} --target ${listTargetsWithCapability(capability).join("|")}`,
+    );
+  }
+
+  return value;
+}
+
+export function parseCloudApiUrl(value: string | boolean | undefined): string {
+  if (value === undefined) {
+    return process.env.AGENTKIT_CLOUD_API_URL ?? defaultAgentKitCloudApiUrl;
+  }
+
+  if (typeof value !== "string") {
+    throw new Error("Missing API URL. Usage: agentkit deploy --api <url>");
+  }
+
+  return value;
+}
+
+export function parseRequiredStringFlag(value: string | boolean | undefined, name: string, usage: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Missing ${name}. Usage: ${usage}`);
+  }
+
+  return value.trim();
+}
+
+export function parseOptionalStringFlag(value: string | boolean | undefined, name: string, usage: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Missing ${name}. Usage: ${usage}`);
+  }
+
+  return value.trim();
+}
+
+export async function resolveSecretInputValue(options: {
+  name: string | undefined;
+  valueParts: string[];
+  stdinFlag: string | boolean | undefined;
+  fromEnvFlag: string | boolean | undefined;
+  fromLocalEnvFlag: string | boolean | undefined;
+  localEnvRoot?: string;
+  usage: string;
+  inlineSensitiveHelp?: string;
+}): Promise<string> {
+  const { name, valueParts, stdinFlag, fromEnvFlag, fromLocalEnvFlag, localEnvRoot, usage, inlineSensitiveHelp } = options;
+
+  if (!name) {
+    throw new Error(`Missing name. Usage: ${usage}`);
+  }
+
+  const hasInlineValue = valueParts.length > 0;
+  const hasStdin = stdinFlag !== undefined;
+  const hasFromEnv = fromEnvFlag !== undefined;
+  const hasFromLocalEnv = fromLocalEnvFlag !== undefined;
+  const inputModes = [hasInlineValue, hasStdin, hasFromEnv, hasFromLocalEnv].filter(Boolean).length;
+
+  if (inputModes !== 1) {
+    throw new Error(`Provide exactly one value source. Usage: ${usage}`);
+  }
+
+  let value: string;
+
+  if (hasInlineValue) {
+    value = valueParts.join(" ");
+    if (looksLikeSecretName(name)) {
+      console.error(
+        `Warning: ${name} looks sensitive. ${inlineSensitiveHelp ?? "Prefer --stdin or --from-env so the value does not enter shell history."}`,
+      );
+    }
+  } else if (hasStdin) {
+    if (stdinFlag !== true) {
+      throw new Error(`--stdin does not take a value. Usage: ${usage}`);
+    }
+
+    value = stripOneTrailingNewline(await readStdinText());
+  } else if (hasFromEnv) {
+    const envName = fromEnvFlag === true ? name : parseRequiredStringFlag(fromEnvFlag, "env name", usage);
+    const envValue = process.env[envName];
+
+    if (envValue === undefined) {
+      throw new AgentKitError("secret_not_found", `Environment variable ${envName} is not set.`);
+    }
+
+    value = envValue;
+  } else {
+    if (fromLocalEnvFlag !== true) {
+      throw new Error(`--from-local-env does not take a value. Usage: ${usage}`);
+    }
+
+    if (!localEnvRoot) {
+      throw new Error(`--from-local-env is not available for this command. Usage: ${usage}`);
+    }
+
+    const localEnv = await loadCapsuleEnv(localEnvRoot, {});
+    const localValue = localEnv[name];
+
+    if (localValue === undefined) {
+      throw new AgentKitError("secret_not_found", `Local .env does not contain ${name}.`);
+    }
+
+    value = localValue;
+  }
+
+  if (value.length === 0) {
+    throw new Error(`Secret value cannot be empty. Usage: ${usage}`);
+  }
+
+  return value;
+}
+
+function looksLikeSecretName(name: string): boolean {
+  return /(?:SECRET|TOKEN|KEY|PASSWORD|CREDENTIAL|PRIVATE)/i.test(name);
+}
+
+async function readStdinText(): Promise<string> {
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function stripOneTrailingNewline(value: string): string {
+  return value.replace(/\r?\n$/, "");
+}