@andreprado/agentkit 0.1.0-alpha.3 → 0.1.0-alpha.5

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$/, "");
+}

package/src/cli/help.ts

@@ -0,0 +1,158 @@
+export function renderHelp(): string {
+  return `AgentKit
+
+Create, run, inspect, and deploy Agent Capsules.
+
+Quick start:
+  agentkit new support-agent --template support
+  cd support-agent
+  npm run dev
+  npm run chat -- --message "hello"
+
+Usage:
+  agentkit <command> [options]
+
+Start:
+  agentkit new <name> [--template blank|support|dentista] [--no-install]
+  agentkit dev
+  agentkit open
+  agentkit chat-ui --deploy
+  agentkit chat --message <text> [--conversation-id <id>]
+  agentkit inspect
+
+Build:
+  agentkit tool <name> [--input <path-or-json>]
+  agentkit db migrate
+  agentkit eval run
+  agentkit conversations list
+
+Deploy:
+  agentkit login --token <token>
+  agentkit deploy doctor
+  agentkit secret set <NAME> --stdin
+  agentkit secret sync --from-local
+  agentkit deploy --smoke "hello"
+  agentkit deploy status
+
+More:
+  agentkit channels ...
+  agentkit access token ...
+  agentkit env ...
+  agentkit docs full
+  agentkit help commands
+`;
+}
+
+export function renderCommandReference(): string {
+  return `AgentKit Command Reference
+
+Usage:
+  agentkit new <name> [--template blank|support|dentista] [--no-install]
+  agentkit dev [--port <number>]
+  agentkit open
+  agentkit chat-ui --deploy [--port <number>] [--token-file <path>]
+  agentkit chat --message <text> [--conversation-id <id>]
+  agentkit tool <name> [--input <path-or-json>]
+  agentkit db migrate
+  agentkit db reset --yes
+  agentkit db shell
+  agentkit db seed [--file <path>]
+  agentkit eval run
+  agentkit conversations list
+  agentkit conversations show <conversation-id>
+  agentkit channels list
+  agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
+  agentkit channels setup <name> [--apply] [--api <url>]
+  agentkit channels status <name> [--api <url>]
+  agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
+  agentkit channels deliveries list <name> [--api <url>]
+  agentkit channels deliveries show <delivery-id> [--api <url>]
+  agentkit inspect
+  agentkit build [--target cloudflare|container]
+  agentkit login --token <token> [--api <url>]
+  agentkit logout
+  agentkit deploy [--target cloudflare|vps] [--host <host>] [--api <url>] [--dry-run] [--anonymous] [--local-wrangler] [--smoke <message>]
+  agentkit deploy doctor [--api <url>] [--anonymous]
+  agentkit deploy smoke [--message <text>] [--api <url>]
+  agentkit deploy status [--api <url>]
+  agentkit deploy pause [--api <url>]
+  agentkit deploy resume [--api <url>]
+  agentkit secret set <NAME> <VALUE> [--api <url>]
+  agentkit secret set <NAME> --stdin [--api <url>]
+  agentkit secret set <NAME> --from-env [ENV_NAME] [--api <url>]
+  agentkit secret set <NAME> --from-local-env [--api <url>]
+  agentkit secret sync --from-local [--api <url>]
+  agentkit secret list [--api <url>]
+  agentkit secret unset <NAME> [--api <url>]
+  agentkit access token create <name> [--api <url>] [--out <path>]
+  agentkit access token list [--api <url>]
+  agentkit access token revoke <token-id> [--api <url>]
+  agentkit env set <NAME> <VALUE>
+  agentkit env set <NAME> --stdin
+  agentkit env set <NAME> --from-env [ENV_NAME]
+  agentkit env list
+  agentkit env unset <NAME>
+  agentkit docs path
+  agentkit docs llms
+  agentkit docs full
+  agentkit handoff codex [goal]
+  agentkit help commands
+  agentkit --help
+
+Commands:
+  new             Create a new Agent Capsule
+  dev             Run the Agent Capsule locally
+  open            Open the local Agent Capsule UI if it is already running
+  chat-ui         Run a local chat UI, optionally pointed at a hosted deploy
+  chat            Send one message to the local Agent Capsule
+  tool            Run one registered tool directly
+  db              Manage the local SQLite database
+  eval            Run local eval files
+  conversations   List and inspect stored local conversations
+  channels        Manage hosted channel resources
+  inspect         Print machine-readable Agent Capsule state
+  build           Build a hosted deploy artifact
+  login           Store an AgentKit Cloud alpha token outside the capsule
+  logout          Remove the stored AgentKit Cloud alpha token
+  deploy          Build and send a hosted artifact to AgentKit Cloud
+  secret          Manage hosted AgentKit Cloud secrets without readback
+  access          Manage hosted deploy access tokens
+  env             Manage local .env values without opening code
+  docs            Print AgentKit docs locations
+  handoff         Print a ready-to-paste prompt for another coding agent
+  help            Print focused help or the full command reference
+
+Examples:
+  agentkit new support-agent --template support
+  cd support-agent
+  agentkit dev
+  agentkit open
+  agentkit tool lookup_order --input '{"orderId":"A100"}'
+  agentkit eval run
+
+  agentkit new clara-dentista --template dentista
+`;
+}
+
+export function renderCommandHelp(command: string): string {
+  const usage: Record<string, string> = {
+    new: "agentkit new <name> [--template blank|support|dentista] [--no-install]",
+    dev: "agentkit dev [--port <number>]",
+    open: "agentkit open",
+    "chat-ui": "agentkit chat-ui --deploy [--port <number>] [--token-file <path>]",
+    chat: 'agentkit chat --message "hello" [--conversation-id <id>]',
+    tool: "agentkit tool <name> [--input <path-or-json>]",
+    deploy:
+      'agentkit deploy [--smoke "hello"] | agentkit deploy smoke [--message "hello"] | agentkit deploy doctor | status | pause | resume',
+    secret:
+      "agentkit secret set <NAME> --stdin | --from-env [ENV_NAME] | --from-local-env | agentkit secret sync --from-local | list | unset <NAME>",
+    access: "agentkit access token create <name> [--out <path>] | list | revoke <token-id>",
+    env: "agentkit env set <NAME> --stdin | --from-env [ENV_NAME] | list | unset <NAME>",
+    docs: "agentkit docs path | llms | full",
+    handoff: "agentkit handoff codex [goal] | agentkit handoff claude [goal]",
+  };
+
+  return `Usage: ${usage[command] ?? "agentkit <command> [options]"}
+
+Run \`agentkit help commands\` for the full command reference.`;
+}