create-xani-agentic-app 1.0.0

package/README.md

@@ -0,0 +1,237 @@
+# create-xani-agentic-app
+
+Scaffold a new agentic AI application with Next.js, Better Auth, and AI SDK.
+
+## Usage
+
+Create a new project in the current directory:
+
+```bash
+npx create-xani-agentic-app@latest .
+```
+
+Create a new project in a subdirectory:
+
+```bash
+npx create-xani-agentic-app@latest my-app
+```
+
+### Non-Interactive Mode (for CI/CD and coding agents)
+
+All prompts can be bypassed with CLI flags, enabling fully automated project scaffolding:
+
+```bash
+# Full non-interactive setup
+npx create-xani-agentic-app@latest my-app -y -p pnpm
+
+# Skip install and git init for faster scaffolding
+npx create-xani-agentic-app@latest my-app -y -p npm --skip-install --skip-git
+```
+
+#### Available Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--yes` | `-y` | Auto-confirm non-empty directory prompt |
+| `--package-manager <manager>` | `-p` | Package manager to use: `pnpm`, `npm`, or `yarn` |
+| `--skip-install` | | Skip dependency installation |
+| `--skip-git` | | Skip git repository initialization |
+
+## What's Included
+
+This starter kit includes:
+
+- **Next.js 16** with App Router and Turbopack
+- **Better Auth** for authentication (email/password, OAuth)
+- **AI SDK** by Vercel for AI chat functionality
+- **Drizzle ORM** with PostgreSQL database
+- **Tailwind CSS** with shadcn/ui components
+- **TypeScript** for type safety
+- **Dark mode** support with next-themes
+
+## Next Steps
+
+After creating your project:
+
+1. **Update environment variables**: Edit `.env` with your API keys and database credentials
+2. **Start the database**: `docker compose up -d`
+3. **Run migrations**: `pnpm run db:migrate` (or `npm`/`yarn`)
+4. **Start dev server**: `pnpm run dev`
+
+Visit `http://localhost:3000` to see your app!
+
+## Publishing to npm
+
+To publish this package to npm:
+
+1. **Update package.json**: Set your author, repository URL, and version in `create-xani-agentic-app/package.json`
+2. **Test locally** (optional): Test the package before publishing:
+   ```bash
+   cd create-xani-agentic-app
+   npm link
+   cd /path/to/test/directory
+   create-xani-agentic-app my-test-app
+   ```
+3. **Publish**: The sync happens automatically!
+   ```bash
+   cd create-xani-agentic-app
+   npm publish
+   ```
+   The `prepublishOnly` hook will automatically sync the template from the main project before publishing.
+
+## Maintainer Guide: Updating & Publishing
+
+This section is for maintainers who need to update the npm package after making changes to the main project.
+
+### Complete Publishing Workflow
+
+Follow these steps **every time** you make changes to the main project and want to publish them:
+
+#### Step 1: Make Changes to Main Project
+
+Edit any files in the main project (outside of `create-xani-agentic-app/` folder):
+- `src/` components and pages
+- `docker-compose.yml`
+- `package.json`
+- Configuration files
+- etc.
+
+#### Step 2: Navigate to create-xani-agentic-app Directory
+
+```bash
+cd create-xani-agentic-app
+```
+
+#### Step 3: Sync Template from Main Project
+
+This copies all your changes from the main project into the template folder:
+
+```bash
+npm run sync
+```
+
+**What this does:**
+- Deletes everything in `create-xani-agentic-app/template/`
+- Copies ALL files from your main project into `template/`
+- Excludes: `node_modules`, `.next`, `.git`, lock files, `.env`, and the `create-xani-agentic-app` folder itself
+- Cleans up the template's `package.json` (removes `private` field and `sync-template` script)
+
+#### Step 4: Bump the Version
+
+Update the version number in `create-xani-agentic-app/package.json`:
+
+**Option A - Using npm version command (recommended):**
+```bash
+npm version patch   # 1.1.3 → 1.1.4 (bug fixes)
+# or
+npm version minor   # 1.1.3 → 1.2.0 (new features)
+# or
+npm version major   # 1.1.3 → 2.0.0 (breaking changes)
+```
+
+**Option B - Manual:**
+Edit `create-xani-agentic-app/package.json` and change the version number.
+
+#### Step 5: Verify Everything Looks Good (Optional)
+
+Quick check to make sure your changes are in the package:
+
+```bash
+npm pack --dry-run | grep "template/"
+```
+
+This shows all files that will be published. Look for your changed files.
+
+#### Step 6: Publish to npm
+
+```bash
+npm publish
+```
+
+**What happens:**
+- The `prepublishOnly` hook automatically runs `npm run sync` again (safety check)
+- Your package gets published to npm with the new version
+
+#### Step 7: Test It
+
+In a different directory, test that it works:
+
+```bash
+cd /path/to/test-directory
+npx create-xani-agentic-app@latest test-project
+# or use the specific version
+npx create-xani-agentic-app@1.1.4 test-project
+```
+
+### Quick Reference Commands
+
+```bash
+# Complete workflow in 4 commands:
+cd create-xani-agentic-app
+npm run sync
+npm version patch
+npm publish
+```
+
+### Common Scenarios
+
+**Scenario 1: You edited `docker-compose.yml` in the main project**
+```bash
+cd create-xani-agentic-app
+npm run sync                    # Copies docker-compose.yml to template/
+npm version patch               # Bumps to next version
+npm publish                     # Publishes to npm
+```
+
+**Scenario 2: You added a new component in `src/components/`**
+```bash
+cd create-xani-agentic-app
+npm run sync                    # Copies new component to template/
+npm version patch               # Bumps version
+npm publish                     # Publishes
+```
+
+**Scenario 3: You updated multiple files**
+```bash
+cd create-xani-agentic-app
+npm run sync                    # Copies ALL changes to template/
+npm version patch               # Bumps version
+npm publish                     # Publishes
+```
+
+### What Gets Excluded from the Template
+
+The sync script excludes these patterns (see `scripts/sync-templates.js`):
+- `node_modules`
+- `.next`
+- `.git`
+- `pnpm-lock.yaml`
+- `package-lock.json`
+- `yarn.lock`
+- `tsconfig.tsbuildinfo`
+- `.env`
+- `create-xani-agentic-app` (the folder itself)
+
+### Troubleshooting
+
+**Issue: npmjs.com shows old version after publishing**
+- The npm website can take 5-10 minutes to update due to CDN caching
+- Verify actual registry: `npm view create-xani-agentic-app version`
+- The package is available to users immediately via `npx` even if the website hasn't updated
+
+**Issue: Users getting old version with `npx`**
+- Users may have cached versions. Tell them to:
+  ```bash
+  npx clear-npx-cache
+  npx create-xani-agentic-app@latest my-project
+  # or use specific version
+  npx create-xani-agentic-app@1.1.4 my-project
+  ```
+
+**Issue: Forgot to run sync before publishing**
+- No problem! The `prepublishOnly` hook runs it automatically
+- But it's good practice to run manually first to verify changes
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import prompts from 'prompts';
+import ora from 'ora';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const TEMPLATE_DIR = path.join(__dirname, 'template');
+
+async function main() {
+  console.log(chalk.bold.cyan('\n🤖 Create Xani Agentic App\n'));
+
+  program
+    .name('create-xani-agentic-app')
+    .description('Scaffold a new agentic AI application')
+    .argument('[project-directory]', 'Project directory name (use "." for current directory)')
+    .option('-y, --yes', 'Auto-confirm non-empty directory prompt')
+    .option('-p, --package-manager <manager>', 'Package manager to use: pnpm | npm | yarn')
+    .option('--skip-install', 'Skip dependency installation')
+    .option('--skip-git', 'Skip git repository initialization')
+    .parse(process.argv);
+
+  const args = program.args;
+  const opts = program.opts();
+  let projectDir = args[0] || '.';
+
+  // Validate --package-manager value if provided
+  const validPackageManagers = ['pnpm', 'npm', 'yarn'];
+  if (opts.packageManager && !validPackageManagers.includes(opts.packageManager)) {
+    console.log(chalk.red(`Invalid package manager: "${opts.packageManager}"`));
+    console.log(chalk.yellow(`Valid options: ${validPackageManagers.join(', ')}`));
+    process.exit(1);
+  }
+
+  // Resolve the target directory
+  const targetDir = path.resolve(process.cwd(), projectDir);
+  const projectName = projectDir === '.' ? path.basename(targetDir) : projectDir;
+
+  // Check if directory exists and is not empty
+  if (fs.existsSync(targetDir)) {
+    const files = fs.readdirSync(targetDir);
+    if (files.length > 0 && projectDir !== '.') {
+      if (opts.yes) {
+        console.log(chalk.yellow(`Directory "${projectDir}" is not empty. Proceeding (--yes).`));
+      } else {
+        const { proceed } = await prompts({
+          type: 'confirm',
+          name: 'proceed',
+          message: `Directory "${projectDir}" is not empty. Continue anyway?`,
+          initial: false
+        });
+
+        if (!proceed) {
+          console.log(chalk.yellow('Cancelled.'));
+          process.exit(0);
+        }
+      }
+    }
+  }
+
+  // Determine package manager
+  let packageManager;
+  if (opts.packageManager) {
+    packageManager = opts.packageManager;
+  } else {
+    const response = await prompts({
+      type: 'select',
+      name: 'packageManager',
+      message: 'Which package manager do you want to use?',
+      choices: [
+        { title: 'pnpm (recommended)', value: 'pnpm' },
+        { title: 'npm', value: 'npm' },
+        { title: 'yarn', value: 'yarn' }
+      ],
+      initial: 0
+    });
+    packageManager = response.packageManager;
+
+    if (!packageManager) {
+      console.log(chalk.yellow('Cancelled.'));
+      process.exit(0);
+    }
+  }
+
+  console.log();
+  const spinner = ora('Creating project...').start();
+
+  try {
+    // Create target directory if it doesn't exist
+    fs.ensureDirSync(targetDir);
+
+    // Copy template files
+    spinner.text = 'Copying template files...';
+    await fs.copy(TEMPLATE_DIR, targetDir, {
+      overwrite: false,
+      errorOnExist: false,
+      filter: (src) => {
+        // Skip node_modules, .next, and other build artifacts
+        const relativePath = path.relative(TEMPLATE_DIR, src);
+        return !relativePath.includes('node_modules') &&
+               !relativePath.includes('.next') &&
+               !relativePath.includes('.git') &&
+               !relativePath.includes('pnpm-lock.yaml') &&
+               !relativePath.includes('package-lock.json') &&
+               !relativePath.includes('yarn.lock') &&
+               !relativePath.includes('tsconfig.tsbuildinfo');
+      }
+    });
+
+    // Copy .env.example to .env if it doesn't exist
+    const envExamplePath = path.join(targetDir, 'env.example');
+    const envPath = path.join(targetDir, '.env');
+
+    if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) {
+      spinner.text = 'Setting up environment file...';
+      await fs.copy(envExamplePath, envPath);
+    }
+
+    // Rename _gitignore to .gitignore (npm excludes .gitignore by default)
+    const gitignoreTemplatePath = path.join(targetDir, '_gitignore');
+    const gitignorePath = path.join(targetDir, '.gitignore');
+
+    if (fs.existsSync(gitignoreTemplatePath)) {
+      spinner.text = 'Setting up .gitignore file...';
+      await fs.move(gitignoreTemplatePath, gitignorePath, { overwrite: true });
+    }
+
+    // Update package.json name if not current directory
+    if (projectDir !== '.') {
+      const packageJsonPath = path.join(targetDir, 'package.json');
+      if (fs.existsSync(packageJsonPath)) {
+        const packageJson = await fs.readJson(packageJsonPath);
+        packageJson.name = projectName;
+        await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
+      }
+    }
+
+    spinner.succeed(chalk.green('Project created successfully!'));
+
+    // Install dependencies
+    if (opts.skipInstall) {
+      console.log(chalk.yellow('\nSkipping dependency installation (--skip-install).'));
+    } else {
+      console.log();
+      const installSpinner = ora(`Installing dependencies with ${packageManager}...`).start();
+
+      try {
+        const installCmd = packageManager === 'yarn' ? 'yarn install' : `${packageManager} install`;
+        execSync(installCmd, {
+          cwd: targetDir,
+          stdio: 'pipe'
+        });
+        installSpinner.succeed(chalk.green('Dependencies installed!'));
+      } catch (error) {
+        installSpinner.fail(chalk.red('Failed to install dependencies'));
+        console.log(chalk.yellow(`\nPlease run "${packageManager} install" manually.\n`));
+      }
+    }
+
+    // Initialize Git repository
+    if (opts.skipGit) {
+      console.log(chalk.yellow('\nSkipping git initialization (--skip-git).'));
+    } else {
+      console.log();
+      const gitSpinner = ora('Initializing Git repository...').start();
+
+      try {
+        // Check if git is available
+        execSync('git --version', { stdio: 'pipe' });
+
+        // Initialize git repo if not already initialized
+        if (!fs.existsSync(path.join(targetDir, '.git'))) {
+          execSync('git init', { cwd: targetDir, stdio: 'pipe' });
+          execSync('git add .', { cwd: targetDir, stdio: 'pipe' });
+          execSync('git commit -m "Initial commit from create-xani-agentic-app"', {
+            cwd: targetDir,
+            stdio: 'pipe'
+          });
+          gitSpinner.succeed(chalk.green('Git repository initialized!'));
+        } else {
+          gitSpinner.info(chalk.blue('Git repository already exists'));
+        }
+      } catch (error) {
+        gitSpinner.warn(chalk.yellow('Git not found - skipping repository initialization'));
+      }
+    }
+
+    // Display next steps
+    console.log();
+    console.log(chalk.bold.green('✨ Your agentic app is ready!\n'));
+    console.log(chalk.bold('Next steps:\n'));
+
+    if (projectDir !== '.') {
+      console.log(chalk.cyan(`  cd ${projectDir}`));
+    }
+
+    console.log(chalk.cyan('  1. Update the .env file with your API keys and database credentials'));
+    console.log(chalk.cyan(`  2. Start the database: docker compose up -d`));
+    console.log(chalk.cyan(`  3. Run database migrations: ${packageManager} run db:migrate`));
+    console.log(chalk.cyan(`  4. Start the development server: ${packageManager} run dev`));
+
+    console.log();
+    console.log(chalk.gray('For more information, check out the README.md file.\n'));
+
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to create project'));
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "create-xani-agentic-app",
+  "version": "1.0.0",
+  "description": "Scaffold a new agentic AI application with Next.js, Better Auth, and AI SDK",
+  "type": "module",
+  "bin": {
+    "create-xani-agentic-app": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "scripts": {
+    "sync": "node scripts/sync-templates.js",
+    "prepublishOnly": "npm run sync",
+    "publish:token": "node scripts/publish-with-token.js"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "nextjs",
+    "better-auth",
+    "starter-kit",
+    "boilerplate",
+    "scaffold",
+    "create-app"
+  ],
+  "author": "AlexandreXavier",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AlexandreXavier/xani-agentic-starter-kit.git",
+    "directory": "create-xani-agentic-app"
+  },
+  "homepage": "https://github.com/AlexandreXavier/xani-agentic-starter-kit#readme",
+  "bugs": {
+    "url": "https://github.com/AlexandreXavier/xani-agentic-starter-kit/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0",
+    "ora": "^8.1.1",
+    "prompts": "^2.4.2"
+  }
+}

package/template/.agents/skills/ai-sdk/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: ai-sdk
+description: 'Answer questions about the AI SDK and help build AI-powered features. Use when developers: (1) Ask about AI SDK functions like generateText, streamText, ToolLoopAgent, embed, or tools, (2) Want to build AI agents, chatbots, RAG systems, or text generation features, (3) Have questions about AI providers (OpenAI, Anthropic, Google, etc.), streaming, tool calling, structured output, or embeddings, (4) Use React hooks like useChat or useCompletion. Triggers on: "AI SDK", "Vercel AI SDK", "generateText", "streamText", "add AI to my app", "build an agent", "tool calling", "structured output", "useChat".'
+---
+
+## Prerequisites
+
+Before searching docs, check if `node_modules/ai/docs/` exists. If not, install **only** the `ai` package using the project's package manager (e.g., `pnpm add ai`).
+
+Do not install other packages at this stage. Provider packages (e.g., `@ai-sdk/openai`) and client packages (e.g., `@ai-sdk/react`) should be installed later when needed based on user requirements.
+
+## Critical: Do Not Trust Internal Knowledge
+
+Everything you know about the AI SDK is outdated or wrong. Your training data contains obsolete APIs, deprecated patterns, and incorrect usage.
+
+**When working with the AI SDK:**
+
+1. Ensure `ai` package is installed (see Prerequisites)
+2. Search `node_modules/ai/docs/` and `node_modules/ai/src/` for current APIs
+3. If not found locally, search ai-sdk.dev documentation (instructions below)
+4. Never rely on memory - always verify against source code or docs
+5. **`useChat` has changed significantly** - check [Common Errors](references/common-errors.md) before writing client code
+6. When deciding which model and provider to use (e.g. OpenAI, Anthropic, Gemini), use the Vercel AI Gateway provider unless the user specifies otherwise. See [AI Gateway Reference](references/ai-gateway.md) for usage details.
+7. **Always fetch current model IDs** - Never use model IDs from memory. Before writing code that uses a model, run `curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '[.data[] | select(.id | startswith("provider/")) | .id] | reverse | .[]'` (replacing `provider` with the relevant provider like `anthropic`, `openai`, or `google`) to get the full list with newest models first. Use the model with the highest version number (e.g., `claude-sonnet-4-5` over `claude-sonnet-4` over `claude-3-5-sonnet`).
+8. Run typecheck after changes to ensure code is correct
+9. **Be minimal** - Only specify options that differ from defaults. When unsure of defaults, check docs or source rather than guessing or over-specifying.
+
+If you cannot find documentation to support your answer, state that explicitly.
+
+## Finding Documentation
+
+### ai@6.0.34+
+
+Search bundled docs and source in `node_modules/ai/`:
+
+- **Docs**: `grep "query" node_modules/ai/docs/`
+- **Source**: `grep "query" node_modules/ai/src/`
+
+Provider packages include docs at `node_modules/@ai-sdk/<provider>/docs/`.
+
+### Earlier versions
+
+1. Search: `https://ai-sdk.dev/api/search-docs?q=your_query`
+2. Fetch `.md` URLs from results (e.g., `https://ai-sdk.dev/docs/agents/building-agents.md`)
+
+## When Typecheck Fails
+
+**Before searching source code**, grep [Common Errors](references/common-errors.md) for the failing property or function name. Many type errors are caused by deprecated APIs documented there.
+
+If not found in common-errors.md:
+
+1. Search `node_modules/ai/src/` and `node_modules/ai/docs/`
+2. Search ai-sdk.dev (for earlier versions or if not found locally)
+
+## Building and Consuming Agents
+
+### Creating Agents
+
+Always use the `ToolLoopAgent` pattern. Search `node_modules/ai/docs/` for current agent creation APIs.
+
+**File conventions**: See [type-safe-agents.md](references/type-safe-agents.md) for where to save agents and tools.
+
+**Type Safety**: When consuming agents with `useChat`, always use `InferAgentUIMessage<typeof agent>` for type-safe tool results. See [reference](references/type-safe-agents.md).
+
+### Consuming Agents (Framework-Specific)
+
+Before implementing agent consumption:
+
+1. Check `package.json` to detect the project's framework/stack
+2. Search documentation for the framework's quickstart guide
+3. Follow the framework-specific patterns for streaming, API routes, and client integration
+
+## References
+
+- [Common Errors](references/common-errors.md) - Renamed parameters reference (parameters → inputSchema, etc.)
+- [AI Gateway](references/ai-gateway.md) - Gateway setup and usage
+- [Type-Safe Agents with useChat](references/type-safe-agents.md) - End-to-end type safety with InferAgentUIMessage
+- [DevTools](references/devtools.md) - Set up local debugging and observability (development only)

package/template/.agents/skills/ai-sdk/references/ai-gateway.md

@@ -0,0 +1,66 @@
+---
+title: Vercel AI Gateway
+description: Reference for using Vercel AI Gateway with the AI SDK.
+---
+
+# Vercel AI Gateway
+
+The Vercel AI Gateway is the fastest way to get started with the AI SDK. It provides access to models from OpenAI, Anthropic, Google, and other providers through a single API.
+
+## Authentication
+
+Authenticate with OIDC (for Vercel deployments) or an [AI Gateway API key](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway%2Fapi-keys&title=AI+Gateway+API+Keys):
+
+```env filename=".env.local"
+AI_GATEWAY_API_KEY=your_api_key_here
+```
+
+## Usage
+
+The AI Gateway is the default global provider, so you can access models using a simple string:
+
+```ts
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: 'anthropic/claude-sonnet-4.5',
+  prompt: 'What is love?',
+});
+```
+
+You can also explicitly import and use the gateway provider:
+
+```ts
+// Option 1: Import from 'ai' package (included by default)
+import { gateway } from 'ai';
+model: gateway('anthropic/claude-sonnet-4.5');
+
+// Option 2: Install and import from '@ai-sdk/gateway' package
+import { gateway } from '@ai-sdk/gateway';
+model: gateway('anthropic/claude-sonnet-4.5');
+```
+
+## Find Available Models
+
+**Important**: Always fetch the current model list before writing code. Never use model IDs from memory - they may be outdated.
+
+List all available models through the gateway API:
+
+```bash
+curl https://ai-gateway.vercel.sh/v1/models
+```
+
+Filter by provider using `jq`. **Do not truncate with `head`** - always fetch the full list to find the latest models:
+
+```bash
+# Anthropic models
+curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '[.data[] | select(.id | startswith("anthropic/")) | .id] | reverse | .[]'
+
+# OpenAI models
+curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '[.data[] | select(.id | startswith("openai/")) | .id] | reverse | .[]'
+
+# Google models
+curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '[.data[] | select(.id | startswith("google/")) | .id] | reverse | .[]'
+```
+
+When multiple versions of a model exist, use the one with the highest version number (e.g., prefer `anthropic/claude-sonnet-4.6` over `anthropic/claude-sonnet-4.5` over `claude-sonnet-4`).