create-adk-agent 0.0.1 → 0.0.5

package/README.md

@@ -1,31 +1,57 @@
-# @adk-ts-new/create-adk-agent
+# create-adk-agent
 
-> Nx generator for scaffolding ADK (Agent Development Kit) TypeScript projects with multiple templates, multi-model support, and modern tooling.
+> **The fastest way to start building with Google's Agent Development Kit (ADK)**
 
-## 🚀 Quick Start
+Scaffold production-ready ADK TypeScript projects in seconds with best practices, multiple templates, and zero configuration.
+
+**What is ADK?** The [Agent Development Kit](https://google.github.io/adk-docs/) is Google's framework for building AI agents. This tool makes it easy to get started.
 
-### Using npx (Recommended)
+## 🚀 Quick Start
 
 ```bash
-npx @adk-ts-new/create-adk-agent my-agent
+npx create-adk-agent my-agent
 ```
 
-### Using Nx workspace
+Or use it non-interactively:
 
 ```bash
-nx g @adk-ts-new/create-adk-agent:init my-agent
+npx create-adk-agent my-agent --template=basic --modelProvider=gemini --model=gemini-2.0-flash
 ```
 
-## ✨ Features
+That's it! You'll get a fully configured ADK project with:
+
+- ✅ TypeScript configured for ADK (ES2022, NodeNext)
+- ✅ Environment setup with API key validation
+- ✅ Working agent examples from official docs
+- ✅ Hot reload development with tsx
+- ✅ Testing setup with Jest
+- ✅ All the tooling (ESLint, Prettier, etc.)
+
+## 💡 Why Use This?
+
+Instead of manually setting up TypeScript, configuring ESM, managing API keys, and copying examples from docs, `create-adk-agent` does it all for you in one command.
+
+**Perfect for:**
 
-- 🤖 **Multiple Agent Templates** - Choose from 5 different agent templates from official ADK docs
-- 🔌 **Multi-Model Support** - Works with Gemini, OpenAI, and Anthropic models
-- ⚡ **tsx Development** - Instant TypeScript execution with hot reload (no build step)
-- 🔐 **Security First** - Built-in `.env` management with clear security warnings
-- 🧪 **Testing Ready** - Pre-configured Jest testing setup
-- 📦 **Modern Stack** - TypeScript, ESLint, Prettier, Zod validation
+- 🎓 Learning ADK quickly with working examples
+- 🚀 Starting new ADK projects without boilerplate hassle
+- 📦 Getting ADK best practices out of the box
+- 🔄 Experimenting with different agent patterns
 
-## 📋 Agent Templates
+## ✨ What You Get
+
+## ✨ What You Get
+
+- 🤖 **5 Agent Templates** - Pre-built examples from [official ADK docs](https://google.github.io/adk-docs/) (basic, multi-tool, team, streaming, workflow)
+- 🔌 **Multi-Model Ready** - Pre-configured for Gemini, OpenAI, and Anthropic
+- ⚡ **Hot Reload** - Instant TypeScript execution with tsx (no build step needed)
+- 🔐 **Security Built-in** - Proper `.env` handling with validation and git-ignore
+- 🧪 **Testing Included** - Jest configured and ready to go
+- 📦 **Best Practices** - TypeScript, ESLint, Prettier, Zod validation
+
+## 📚 Agent Templates
+
+All templates are based on [official ADK documentation examples](https://google.github.io/adk-docs/):
 
 ### Basic Agent
 
@@ -49,28 +75,31 @@ Sequential workflow patterns with validation, transformation, and saving steps.
 
 ## 🎯 Usage
 
-### Interactive Mode
+### Simple (Interactive)
+
+Just run the command and answer a few questions:
 
 ```bash
-npx @adk-ts-new/create-adk-agent my-agent
+npx create-adk-agent my-agent
 ```
 
-You'll be prompted for:
+You'll choose:
 
-- Agent templates to include
-- Model provider (Gemini/OpenAI/Anthropic)
-- Whether to install dependencies
+- Which agent templates to include
+- Your preferred model provider (Gemini, OpenAI, or Anthropic)
+- Whether to install dependencies now
 - Whether to initialize git
 
-### Non-Interactive Mode
+### Advanced (Non-Interactive)
+
+Skip prompts by providing options:
 
 ```bash
-npx @adk-ts-new/create-adk-agent my-agent \
+npx create-adk-agent my-agent \
   --templates=basic,multi-tool \
   --modelProvider=gemini \
   --model=gemini-3.0-flash \
   --description="My custom agent" \
-  --directory=apps \
   --installDependencies \
   --no-interactive
 ```
@@ -114,7 +143,30 @@ npx @adk-ts-new/create-adk-agent my-agent \
 
 **Note:** You can change to any model after project generation. The list above is for initial setup convenience.
 
-## 📦 Generated Project Structure
+## 🎬 Getting Started Workflow
+
+```bash
+# 1. Create your project (takes ~10 seconds)
+npx create-adk-agent my-agent
+
+# 2. Navigate to project
+cd my-agent
+
+# 3. Add your API key
+cp .env.example .env
+# Edit .env and add your API key (get it from links in the file)
+
+# 4. Start coding! (hot reload enabled)
+npm run dev
+
+# 5. Or use ADK DevTools
+npm run adk:web    # Beautiful web UI
+npm run adk:run    # CLI runner
+```
+
+**That's it!** You're now building with ADK. No complex setup, no configuration headaches.
+
+## 🔗 Learn More About ADK
 
 ```
 my-agent/

package/bin/create-adk-agent.js

@@ -0,0 +1,364 @@
+#!/usr/bin/env node
+
+// @ts-check
+import { blue, cyan, green, red, reset, yellow } from 'kolorist';
+import minimist from 'minimist';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import prompts from 'prompts';
+
+const argv = minimist(process.argv.slice(2), { string: ['_'] });
+const cwd = process.cwd();
+
+// Template configurations
+const TEMPLATES = [
+  {
+    name: 'basic',
+    display: 'Basic Agent',
+    description: 'Single agent with one tool (time example)',
+    color: green,
+  },
+  {
+    name: 'multi-tool',
+    display: 'Multi-Tool Agent',
+    description: 'Agent with multiple tools (recommended)',
+    color: blue,
+  },
+  {
+    name: 'streaming',
+    display: 'Streaming Agent',
+    description: 'Agent with Live API streaming support',
+    color: cyan,
+  },
+  {
+    name: 'team',
+    display: 'Multi-Agent Team',
+    description: 'Multiple agents working together',
+    color: yellow,
+  },
+  {
+    name: 'workflow',
+    display: 'Workflow Agent',
+    description: 'Sequential and parallel execution patterns',
+    color: yellow,
+  },
+];
+
+// Model provider configurations
+const MODEL_PROVIDERS = {
+  gemini: {
+    name: 'Google Gemini',
+    models: [
+      'gemini-2.0-flash',
+      'gemini-2.0-flash-thinking-exp-01-21',
+      'gemini-1.5-pro',
+    ],
+    apiKeyVar: 'GEMINI_API_KEY',
+    importStatement: "import { LlmAgent, FunctionTool } from '@google/adk';",
+    modelConfig: (model) => `'${model}'`,
+  },
+  openai: {
+    name: 'OpenAI',
+    models: ['openai/gpt-4o', 'openai/gpt-4o-mini', 'openai/gpt-4-turbo'],
+    apiKeyVar: 'OPENAI_API_KEY',
+    importStatement:
+      "import { LlmAgent, FunctionTool, LiteLlm } from '@google/adk';",
+    modelConfig: (model) => `new LiteLlm({ model: '${model}' })`,
+  },
+  anthropic: {
+    name: 'Anthropic (Claude)',
+    models: [
+      'anthropic/claude-3-5-sonnet',
+      'anthropic/claude-3-opus',
+      'anthropic/claude-3-haiku',
+    ],
+    apiKeyVar: 'ANTHROPIC_API_KEY',
+    importStatement:
+      "import { LlmAgent, FunctionTool, LiteLlm } from '@google/adk';",
+    modelConfig: (model) => `new LiteLlm({ model: '${model}' })`,
+  },
+};
+
+const renameFiles = {
+  _gitignore: '.gitignore',
+};
+
+function formatTargetDir(targetDir) {
+  return targetDir?.trim().replace(/\/+$/g, '');
+}
+
+function isValidPackageName(projectName) {
+  return /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(
+    projectName,
+  );
+}
+
+function toValidPackageName(projectName) {
+  return projectName
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/^[._]/, '')
+    .replace(/[^a-z0-9-~]+/g, '-');
+}
+
+function copy(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    copyDir(src, dest);
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function copyDir(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const file of fs.readdirSync(srcDir)) {
+    const srcFile = path.resolve(srcDir, file);
+    const destFile = path.resolve(destDir, file);
+    copy(srcFile, destFile);
+  }
+}
+
+function isEmpty(pathToCheck) {
+  const files = fs.readdirSync(pathToCheck);
+  return files.length === 0 || (files.length === 1 && files[0] === '.git');
+}
+
+function emptyDir(dir) {
+  if (!fs.existsSync(dir)) {
+    return;
+  }
+  for (const file of fs.readdirSync(dir)) {
+    fs.rmSync(path.resolve(dir, file), { recursive: true, force: true });
+  }
+}
+
+function replacePlaceholders(root, files, config) {
+  for (const file of Array.isArray(files) ? files : [files]) {
+    const filePath = path.join(root, file);
+    if (!fs.existsSync(filePath)) continue;
+
+    const fileContent = fs.readFileSync(filePath, 'utf-8');
+    const newFileContent = Object.keys(config).reduce(
+      (content, placeholder) =>
+        content.replace(new RegExp(placeholder, 'g'), config[placeholder]),
+      fileContent,
+    );
+    fs.writeFileSync(filePath, newFileContent);
+  }
+}
+
+async function init() {
+  let targetDir = formatTargetDir(argv._[0]);
+  let template = argv.template || argv.t;
+  let modelProvider = argv.modelProvider || argv.mp;
+  let model = argv.model || argv.m;
+  let description = argv.description || argv.d;
+
+  const defaultTargetDir = 'my-adk-agent';
+  const getProjectName = () =>
+    targetDir === '.' ? path.basename(path.resolve()) : targetDir;
+
+  let result = {};
+
+  try {
+    result = await prompts(
+      [
+        {
+          type: targetDir ? null : 'text',
+          name: 'projectName',
+          message: reset('Project name:'),
+          initial: defaultTargetDir,
+          onState: (state) => {
+            targetDir = formatTargetDir(state.value) || defaultTargetDir;
+          },
+        },
+        {
+          type: () =>
+            !fs.existsSync(targetDir) || isEmpty(targetDir) ? null : 'confirm',
+          name: 'overwrite',
+          message: () =>
+            (targetDir === '.'
+              ? 'Current directory'
+              : `Target directory "${targetDir}"`) +
+            ` is not empty. Remove existing files and continue?`,
+        },
+        {
+          type: (_, { overwrite } = {}) => {
+            if (overwrite === false) {
+              throw new Error(red('✖') + ' Operation cancelled');
+            }
+            return null;
+          },
+          name: 'overwriteChecker',
+        },
+        {
+          type: () => (isValidPackageName(getProjectName()) ? null : 'text'),
+          name: 'packageName',
+          message: reset('Package name:'),
+          initial: () => toValidPackageName(getProjectName()),
+          validate: (dir) =>
+            isValidPackageName(dir) || 'Invalid package.json name',
+        },
+        {
+          type: description ? null : 'text',
+          name: 'description',
+          message: reset('Project description:'),
+          initial: 'My ADK Agent',
+        },
+        {
+          type: template ? null : 'select',
+          name: 'template',
+          message: reset('Select a template:'),
+          choices: TEMPLATES.map((t) => ({
+            title: `${t.color(t.display)} - ${t.description}`,
+            value: t.name,
+          })),
+        },
+        {
+          type: modelProvider ? null : 'select',
+          name: 'modelProvider',
+          message: reset('Select LLM provider:'),
+          choices: Object.entries(MODEL_PROVIDERS).map(([key, value]) => ({
+            title: value.name,
+            value: key,
+          })),
+        },
+        {
+          type: (prev, values) => {
+            const provider = modelProvider || values.modelProvider;
+            return model || !provider ? null : 'select';
+          },
+          name: 'model',
+          message: reset('Select model:'),
+          choices: (prev, values) => {
+            const provider = modelProvider || values.modelProvider;
+            return MODEL_PROVIDERS[provider].models.map((m) => ({
+              title: m,
+              value: m,
+            }));
+          },
+        },
+      ],
+      {
+        onCancel: () => {
+          throw new Error(red('✖') + ' Operation cancelled');
+        },
+      },
+    );
+  } catch (cancelled) {
+    console.log(cancelled.message);
+    return;
+  }
+
+  // Extract values from prompts
+  const {
+    overwrite,
+    packageName,
+    description: promptDescription,
+    template: promptTemplate,
+    modelProvider: promptModelProvider,
+    model: promptModel,
+  } = result;
+
+  // Use CLI args or prompt values
+  template = template || promptTemplate || 'basic';
+  modelProvider = modelProvider || promptModelProvider || 'gemini';
+  model = model || promptModel || MODEL_PROVIDERS[modelProvider].models[0];
+  description = description || promptDescription || 'My ADK Agent';
+
+  const root = path.join(cwd, targetDir);
+
+  if (overwrite) {
+    emptyDir(root);
+  } else if (!fs.existsSync(root)) {
+    fs.mkdirSync(root, { recursive: true });
+  }
+
+  console.log(`\n${green('✓')} Scaffolding project in ${root}...\n`);
+
+  const templateDir = path.resolve(
+    fileURLToPath(import.meta.url),
+    '..',
+    '..',
+    'templates',
+    template,
+  );
+
+  if (!fs.existsSync(templateDir)) {
+    console.error(red(`✖ Error: Template "${template}" not found!`));
+    process.exit(1);
+  }
+
+  const write = (file, content) => {
+    const targetPath = renameFiles[file]
+      ? path.join(root, renameFiles[file])
+      : path.join(root, file);
+
+    if (content) {
+      fs.writeFileSync(targetPath, content);
+    } else {
+      copy(path.join(templateDir, file), targetPath);
+    }
+  };
+
+  // Copy all template files
+  const files = fs.readdirSync(templateDir);
+  for (const file of files.filter((f) => f !== 'package.json')) {
+    write(file);
+  }
+
+  // Handle package.json separately
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(templateDir, 'package.json'), 'utf-8'),
+  );
+  pkg.name = packageName || getProjectName();
+  pkg.description = description;
+
+  write('package.json', JSON.stringify(pkg, null, 2));
+
+  // Replace placeholders
+  const providerConfig = MODEL_PROVIDERS[modelProvider];
+  const modelConfig = providerConfig.modelConfig(model);
+
+  replacePlaceholders(root, 'README.md', {
+    __PROJECT_NAME__: pkg.name,
+    __DESCRIPTION__: description,
+  });
+
+  replacePlaceholders(root, 'src/index.ts', {
+    __MODEL_CONFIG__: modelConfig,
+  });
+
+  // Update imports if needed (for LiteLLM)
+  if (modelProvider !== 'gemini') {
+    replacePlaceholders(root, 'src/index.ts', {
+      "import { LlmAgent, FunctionTool } from '@google/adk';":
+        providerConfig.importStatement,
+    });
+  }
+
+  console.log(`${green('✓')} Project created successfully!\n`);
+  console.log(`${cyan('Next steps:')}\n`);
+
+  if (root !== cwd) {
+    console.log(`  cd ${path.relative(cwd, root)}`);
+  }
+
+  console.log(`  npm install`);
+  console.log(`  cp .env.example .env`);
+  console.log(`  ${yellow('# Edit .env and add your API key')}`);
+  console.log(`  npm run dev\n`);
+
+  console.log(`${cyan('Configuration:')}`);
+  console.log(`  Template: ${green(template)}`);
+  console.log(`  Provider: ${green(providerConfig.name)}`);
+  console.log(`  Model: ${green(model)}`);
+  console.log(`  API Key: ${yellow(providerConfig.apiKeyVar)}\n`);
+}
+
+init().catch((e) => {
+  console.error(e);
+});

package/dist/generators/init/files/.env.example.template

@@ -0,0 +1,16 @@
+# Google Gemini API Key
+# Get your key from: https://aistudio.google.com/apikey
+GEMINI_API_KEY=your_google_api_key_here
+
+# OR use Vertex AI (for Google Cloud)
+# GOOGLE_GENAI_USE_VERTEXAI=true
+# GOOGLE_CLOUD_PROJECT=your-project-id
+# GOOGLE_CLOUD_LOCATION=us-central1
+
+# OpenAI API Key (if using OpenAI models)
+# Get your key from: https://platform.openai.com/api-keys
+# OPENAI_API_KEY=your_openai_api_key_here
+
+# Anthropic API Key (if using Claude models)
+# Get your key from: https://console.anthropic.com/settings/keys
+# ANTHROPIC_API_KEY=your_anthropic_api_key_here

package/dist/generators/init/files/.eslintrc.json.template

@@ -0,0 +1,20 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "plugins": ["@typescript-eslint"],
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
+    "@typescript-eslint/no-explicit-any": "warn"
+  }
+}

package/dist/generators/init/files/.gitignore.template

@@ -0,0 +1,27 @@
+# Environment files - NEVER commit these!
+.env
+.env.local
+.env*.local
+
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test coverage
+coverage/
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

package/dist/generators/init/files/.prettierrc.template

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2
+}