create-adk-agent 0.0.2 → 0.0.9

package/README.md

@@ -1,241 +1,69 @@
 # create-adk-agent
 
-> **The fastest way to start building with Google's Agent Development Kit (ADK)**
+> Scaffold production-ready [Google ADK](https://google.github.io/adk-docs/) TypeScript projects in seconds
 
-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.
-
-## 🚀 Quick Start
+## Quick Start
 
 ```bash
 npx create-adk-agent my-agent
 ```
 
-That's it! You'll get a fully configured ADK project with:
-- ✅ TypeScript configured for ADK
-- ✅ 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:**
-- 🎓 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
-
-## ✨ 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
-
-Simple agent with time tool - perfect for learning ADK basics.
-
-### Multi-Tool Agent (Default)
-
-Agent with multiple tools (time, weather, calculator) demonstrating tool composition.
-
-### Team Agent
+Creates a TypeScript project pre-configured for building AI agents with Google's Agent Development Kit.
 
-Multi-agent system with coordination, delegation, and sub-agents (greeting + farewell).
+## What You Get
 
-### Streaming Agent
-
-Demonstrates real-time streaming responses using ADK Live API.
-
-### Workflow Agent
-
-Sequential workflow patterns with validation, transformation, and saving steps.
-
-## 🎯 Usage
+- ✅ Working agent examples from [ADK docs](https://google.github.io/adk-docs/get-started/typescript/)
+- ✅ TypeScript configured (ES2022, NodeNext, ESM)
+- ✅ Hot reload with tsx (instant execution)
+- ✅ Multi-model support (Gemini, OpenAI, Anthropic)
+- ✅ Environment setup with API key validation
+- ✅ Testing with Jest, linting with ESLint
 
-### Simple (Interactive)
+## Usage
 
-Just run the command and answer a few questions:
+**Interactive:**
 
 ```bash
 npx create-adk-agent my-agent
 ```
 
-You'll choose:
-- Which agent templates to include
-- Your preferred model provider (Gemini, OpenAI, or Anthropic)
-- Whether to install dependencies now
-- Whether to initialize git
-
-### Advanced (Non-Interactive)
-
-Skip prompts by providing options:
+**Non-interactive:**
 
 ```bash
 npx create-adk-agent my-agent \
-  --templates=basic,multi-tool \
+  --template=basic \
   --modelProvider=gemini \
-  --model=gemini-3.0-flash \
-  --description="My custom agent" \
-  --installDependencies \
-  --no-interactive
+  --model=gemini-2.5-flash
 ```
 
-### Options
-
-| Option                  | Type                              | Description                | Default                |
-| ----------------------- | --------------------------------- | -------------------------- | ---------------------- |
-| `name`                  | string                            | Project name (required)    | -                      |
-| `--templates`           | string[]                          | Agent templates to include | `['multi-tool']`       |
-| `--modelProvider`       | gemini\|openai\|anthropic\|custom | LLM provider               | `gemini`               |
-| `--model`               | string                            | Specific model to use      | Provider's first model |
-| `--description`         | string                            | Project description        | `My ADK Agent`         |
-| `--directory`           | string                            | Target directory           | Same as name           |
-| `--installDependencies` | boolean                           | Run npm install            | Prompt                 |
-| `--initGit`             | boolean                           | Initialize git repo        | Prompt                 |
-| `--no-interactive`      | boolean                           | Skip prompts               | `false`                |
-
-## 🤖 Supported Models
-
-### Google Gemini (Direct)
-
-- gemini-3.0-flash
-- gemini-3.0-pro
-- gemini-2.5-flash
-- gemini-2.5-pro
-
-### OpenAI (via LiteLLM)
-
-- gpt-5
-- gpt-5-mini
-- gpt-4o
-- gpt-4o-mini
-
-### Anthropic (via LiteLLM)
-
-- claude-4.5-sonnet
-- claude-4-sonnet
-- claude-4-opus
-- claude-3-5-sonnet
-
-**Note:** You can change to any model after project generation. The list above is for initial setup convenience.
-
-## 🎬 Getting Started Workflow
+## After Generation
 
 ```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
+# Add your API key
 cp .env.example .env
-# Edit .env and add your API key (get it from links in the file)
+# Edit .env with your API key
 
-# 4. Start coding! (hot reload enabled)
+# Start development
 npm run dev
 
-# 5. Or use ADK DevTools
-npm run adk:web    # Beautiful web UI
+# Use ADK DevTools
+npm run adk:web    # Interactive 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/
-├── src/
-│   ├── agents/
-│   │   ├── basic/          # Basic agent (if selected)
-│   │   ├── multi-tool/     # Multi-tool agent (if selected)
-│   │   ├── team/           # Team agents (if selected)
-│   │   ├── streaming/      # Streaming agent (if selected)
-│   │   └── workflow/       # Workflow agent (if selected)
-│   └── index.ts            # Entry point with env validation
-├── tests/
-│   └── agents.test.ts      # Jest tests
-├── .env.example            # Environment template (commit this)
-├── .env                    # Your API keys (DO NOT COMMIT)
-├── .gitignore              # Includes .env patterns
-├── package.json            # With tsx, ADK, and dev tools
-├── tsconfig.json           # Configured for ESM + NodeNext
-└── README.md               # Project-specific documentation
-```
-
-## 🔐 Security
+## Templates
 
-**⚠️ Generated projects include:**
-
-- `.env` in `.gitignore` by default
-- API key validation on startup
-- Clear warnings about committing secrets
-- `.env.example` template for sharing
-
-## 🛠️ Development Workflow
-
-After generating your project:
-
-```bash
-cd my-agent
-
-# 1. Set up your API key
-cp .env.example .env
-# Edit .env and add your API key
+- **basic** - Single agent with one tool ([docs example](https://google.github.io/adk-docs/get-started/typescript/#define-the-agent-code))
+- **multi-tool** - Agent with multiple tools (default)
 
-# 2. Install dependencies (if not done during generation)
-npm install
+## Learn More
 
-# 3. Start development with hot reload
-npm run dev
-
-# 4. Run tests
-npm test
-
-# 5. Use ADK DevTools
-npm run adk:web    # Web UI
-npm run adk:run    # CLI runner
-```
-
-## 📚 Documentation
-
-- [ADK Documentation](https://google.github.io/adk-docs/)
-- [TypeScript Quick Start](https://google.github.io/adk-docs/get-started/typescript/)
-- [Agent Tutorial](https://google.github.io/adk-docs/tutorial/agent/)
-
-## 🤝 Contributing
-
-Contributions welcome! This is an Nx workspace project.
-
-### Development
-
-```bash
-# Build the generator
-nx build create-adk-agent
-
-# Test locally
-nx g @adk-ts-new/create-adk-agent:init test-project
-
-# Run tests
-nx test create-adk-agent
-```
+- **[ADK Documentation](https://google.github.io/adk-docs/)** - Official ADK guide
+- **[TypeScript Quickstart](https://google.github.io/adk-docs/get-started/typescript/)** - Getting started
+- **[Building Agents](https://google.github.io/adk-docs/tutorials/)** - Agent tutorials
 
-## 📄 License
+## License
 
-MIT © Maina Wycliffe
+MIT

package/bin/create-adk-agent.js

@@ -1,38 +1,364 @@
 #!/usr/bin/env node
 
-import { execSync } from 'child_process';
-import { fileURLToPath } from 'url';
-import { dirname, resolve } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Get the arguments passed to the script (excluding node and script path)
-const args = process.argv.slice(2);
-
-// Check if a project name was provided
-if (args.length === 0) {
-  console.error('❌ Error: Please provide a project name');
-  console.error('Usage: npx create-adk-agent <project-name> [options]');
-  console.error('');
-  console.error('Example:');
-  console.error('  npx create-adk-agent my-agent');
-  console.error('  npx create-adk-agent my-agent --templates=basic,multi-tool --no-interactive');
-  process.exit(1);
-}
-
-// Build the nx command
-const generatorPath = resolve(__dirname, '..');
-const command = `npx --yes nx g ${generatorPath}:init ${args.join(' ')}`;
-
-console.log('🚀 Creating your ADK agent project...');
-console.log('');
-
-try {
-  // Execute the nx generator command
-  execSync(command, { stdio: 'inherit', cwd: process.cwd() });
-} catch (error) {
-  console.error('');
-  console.error('❌ Failed to create project');
-  process.exit(1);
+// @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