create-atsdc-stack 1.0.1 → 1.1.0

package/CLAUDE.md

@@ -0,0 +1,215 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+The ATSDC Stack is a full-stack web application framework built with Astro, TypeScript, SCSS, Drizzle ORM, and Clerk. It's designed as both a production-ready template and a CLI tool for scaffolding new projects.
+
+This is a monorepo with two main parts:
+- **Root**: CLI tool for scaffolding new projects (`create-atsdc-stack`)
+- **app/**: The actual Astro application template
+
+## Development Commands
+
+Run these commands from the **root directory** (they delegate to the app workspace):
+
+```bash
+# Development
+npm run dev              # Start dev server at http://localhost:4321
+
+# Build & Preview
+npm run build            # Type-check and build for production
+npm run preview          # Preview production build locally
+
+# Database Operations
+npm run db:push          # Push schema changes to database (no migrations)
+npm run db:generate      # Generate migration files from schema
+npm run db:migrate       # Apply pending migrations
+npm run db:studio        # Open Drizzle Studio GUI for database
+```
+
+## Architecture Overview
+
+### Database Layer (Drizzle ORM)
+
+**Key files:**
+- `app/src/db/schema.ts` - Table definitions using Drizzle ORM
+- `app/src/db/validations.ts` - Zod schemas for runtime validation
+- `app/src/db/initialize.ts` - Database client initialization and utilities
+- `app/drizzle.config.ts` - Drizzle Kit configuration
+
+**Important patterns:**
+- Uses **NanoID** (21 chars) for all primary keys, not UUIDs or auto-increment
+- All IDs are `varchar(21)` with `.$defaultFn(() => nanoid())`
+- TypeScript types are inferred: `typeof posts.$inferSelect` and `typeof posts.$inferInsert`
+- Zod validation schemas mirror database schemas but add runtime validation
+- Use `@vercel/postgres` for connection pooling, wrapped by Drizzle
+
+### API Routes
+
+**Location:** `app/src/pages/api/`
+
+**Pattern:** Each file exports HTTP methods as named exports:
+```typescript
+export const GET: APIRoute = async ({ request, url }) => { ... }
+export const POST: APIRoute = async ({ request }) => { ... }
+export const PUT: APIRoute = async ({ request }) => { ... }
+export const DELETE: APIRoute = async ({ request, url }) => { ... }
+```
+
+**Key conventions:**
+1. Always validate inputs with Zod schemas from `validations.ts`
+2. Return JSON responses with proper status codes (200, 201, 400, 404, 500)
+3. Handle `ZodError` separately from generic errors
+4. Use Drizzle query builder, not raw SQL
+5. For query params, use `url.searchParams.get()` and validate with Zod
+
+**Example:** See `app/src/pages/api/posts.ts` for complete CRUD implementation
+
+### AI Integration (Vercel AI SDK v5+)
+
+**Location:** `app/src/pages/api/chat.ts`
+
+**Key pattern:** Uses AI Gateway - no provider-specific packages needed!
+```typescript
+import { streamText } from 'ai';
+
+const result = streamText({
+  model: 'openai/gpt-4o',  // or 'anthropic/claude-3-5-sonnet-20241022'
+  messages: validatedData.messages,
+  apiKey: process.env.OPENAI_API_KEY,  // Pass the appropriate API key
+});
+
+return result.toDataStreamResponse();
+```
+
+**Supported formats:** `openai/`, `anthropic/`, `google/`, etc.
+
+### SCSS Architecture
+
+**Critical rules:**
+1. **NO inline `<style>` tags** in `.astro` files (except truly standalone components)
+2. **NO utility classes** - use semantic class names (`.btn`, `.card`, not `.px-4`)
+3. All styles in external `.scss` files under `app/src/styles/`
+4. Component styles: `app/src/styles/components/`
+5. Page styles: `app/src/styles/pages/`
+6. Global variables auto-imported via Vite config: `@use "@/styles/variables/globals.scss" as *;`
+
+**Import pattern in .astro files:**
+```astro
+---
+import '@/styles/components/button.scss';
+import '@/styles/pages/example.scss';
+---
+```
+
+**Styling modifiers (in order of preference):**
+1. Data attributes: `<button class="btn" data-variant="primary" data-size="lg">`
+2. Class chaining: `<button class="btn primary lg">`
+
+**SCSS organization:**
+- `variables/globals.scss` - Colors, spacing, typography
+- `variables/mixins.scss` - Reusable mixins like `@include flex-center`
+- `reset.scss` - CSS reset
+- `global.scss` - Global base styles
+
+### TypeScript Path Aliases
+
+Configured in `app/tsconfig.json`:
+```json
+{
+  "@/*": ["src/*"],
+  "@db/*": ["src/db/*"],
+  "@styles/*": ["src/styles/*"],
+  "@components/*": ["src/components/*"]
+}
+```
+
+**Usage:**
+```typescript
+import { db } from '@/db/initialize';
+import { posts } from '@/db/schema';
+import '@/styles/components/card.scss';
+```
+
+### Authentication (Clerk)
+
+- Pre-configured in `app/astro.config.mjs`
+- Middleware: Create `app/src/middleware.ts` with `clerkMiddleware()` to protect routes
+- User IDs stored as `authorId` in database (varchar 255)
+- React components available via `@clerk/clerk-react`
+
+### Progressive Web App (PWA)
+
+- Configured via `vite-plugin-pwa` in `astro.config.mjs`
+- Auto-updates enabled (`registerType: 'autoUpdate'`)
+- Manifest and service worker auto-generated
+- Assets should be in `app/public/` (pwa-192x192.png, pwa-512x512.png)
+
+## Environment Variables
+
+**Required:**
+- `DATABASE_URL` - PostgreSQL connection string
+- `PUBLIC_CLERK_PUBLISHABLE_KEY` - Clerk publishable key
+- `CLERK_SECRET_KEY` - Clerk secret key
+- `OPENAI_API_KEY` - OpenAI API key (for AI features)
+
+**Setup:** Copy `.env.example` to `.env` and fill in values
+
+## Key Design Decisions
+
+1. **NanoID over UUID/auto-increment:** URL-safe, shorter, equally collision-resistant
+2. **Vercel Postgres over node-postgres:** Better connection pooling for serverless
+3. **Drizzle over Prisma:** Closer to SQL, better TypeScript inference, lighter weight
+4. **Zod validation separate from schema:** Allows different validation rules for create/update operations
+5. **SCSS over Tailwind:** Enforces semantic naming, better for large teams and maintainability
+6. **Astro server mode:** Enables API routes and dynamic rendering with Vercel adapter
+
+## Common Patterns
+
+### Creating a new database table
+
+1. Define schema in `app/src/db/schema.ts` using NanoID for primary key
+2. Create Zod schemas in `app/src/db/validations.ts` for create/update operations
+3. Export TypeScript types: `export type MyModel = typeof myTable.$inferSelect`
+4. Push to database: `npm run db:push` (dev) or `npm run db:generate && npm run db:migrate` (prod)
+
+### Creating a new API route
+
+1. Create file in `app/src/pages/api/[name].ts`
+2. Export named HTTP method handlers: `GET`, `POST`, `PUT`, `DELETE`
+3. Validate inputs with Zod schemas
+4. Use Drizzle ORM for database operations
+5. Return JSON responses with proper error handling
+
+### Adding new styles
+
+1. Create `.scss` file in appropriate location (`components/` or `pages/`)
+2. Import in `.astro` component: `import '@/styles/components/mycomponent.scss'`
+3. Use semantic class names with data attributes for modifiers
+4. Access global variables/mixins automatically (via Vite config)
+
+## Testing Database Connection
+
+```typescript
+import { getDatabaseHealth } from '@/db/initialize';
+
+const health = await getDatabaseHealth();
+// Returns: { connected: boolean, tablesExist: boolean, timestamp: Date }
+```
+
+## Deployment
+
+Configured for **Vercel** deployment with:
+- Adapter: `@astrojs/vercel` (serverless mode)
+- Build command: `npm run build`
+- Output directory: `app/dist/`
+- Environment variables must be set in Vercel project settings
+
+## Workspace Structure
+
+This is an npm workspace:
+- Root `package.json` contains CLI tooling and workspace configuration
+- `app/package.json` contains the Astro application dependencies
+- Commands run from root are proxied to the app workspace via `--workspace=app`

package/bin/cli.js

@@ -6,11 +6,13 @@
  */
 
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
-import * as readline from 'node:readline/promises';
+import promptSyncModule from 'prompt-sync';
+
+const prompt = promptSyncModule();
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -46,23 +48,14 @@ function logWarning(message) {
     console.warn(`${colors.yellow}⚠${colors.reset} ${message}`);
 }
 
-async function promptUser(question) {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-
-    try {
-        const answer = await rl.question(`${colors.cyan}${question}${colors.reset} `);
-        return answer.trim();
-    } finally {
-        rl.close();
-    }
+function promptUser(question) {
+    const answer = prompt(`${colors.cyan}${question}${colors.reset} `);
+    return answer ? answer.trim() : '';
 }
 
-async function promptYesNo(question, defaultValue = false) {
+function promptYesNo(question, defaultValue = false) {
     const defaultText = defaultValue ? 'Y/n' : 'y/N';
-    const answer = await promptUser(`${question} (${defaultText}):`);
+    const answer = promptUser(`${question} (${defaultText}):`);
 
     if (!answer) {
         return defaultValue;
@@ -592,23 +585,34 @@ async function setupDatabase(projectDir) {
 }
 
 async function createProject(projectName, options = {}) {
-    const targetDir = join(process.cwd(), projectName);
+    // If no project name provided, use current directory
+    const isCurrentDir = !projectName || projectName === '.';
+    const targetDir = isCurrentDir ? process.cwd() : join(process.cwd(), projectName);
+    const displayName = isCurrentDir ? 'current directory' : projectName;
 
     try {
-        // Step 1: Check if directory exists
-        logStep(1, 'Checking project directory...');
-        if (existsSync(targetDir)) {
-            logError(`Directory "${projectName}" already exists!`);
-            process.exit(1);
+        // Step 1: Check if directory exists (skip for current directory)
+        if (!isCurrentDir) {
+            logStep(1, 'Checking project directory...');
+            if (existsSync(targetDir)) {
+                logError(`Directory "${projectName}" already exists!`);
+                process.exit(1);
+            }
+            logSuccess('Directory available');
         }
 
-        // Step 2: Create project directory
-        logStep(2, `Creating project directory: ${projectName}`);
-        await mkdir(targetDir, { recursive: true });
-        logSuccess('Directory created');
+        // Step 2: Create project directory (skip for current directory)
+        if (!isCurrentDir) {
+            logStep(isCurrentDir ? 1 : 2, `Creating project directory: ${projectName}`);
+            await mkdir(targetDir, { recursive: true });
+            logSuccess('Directory created');
+        } else {
+            logStep(1, 'Using current directory for project setup');
+        }
 
         // Step 3: Copy template files
-        logStep(3, 'Copying template files...');
+        const stepOffset = isCurrentDir ? 1 : 2;
+        logStep(stepOffset + 1, 'Copying template files...');
 
         const appDir = join(templateDir, 'app');
 
@@ -651,10 +655,12 @@ async function createProject(projectName, options = {}) {
         logSuccess('Template files copied');
 
         // Step 4: Update package.json with project name, adapter, and integrations
-        logStep(4, 'Updating package.json...');
+        logStep(stepOffset + 2, 'Updating package.json...');
         const packageJsonPath = join(targetDir, 'package.json');
         const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf-8'));
-        packageJson.name = projectName;
+        // Use current directory name if no project name provided
+        const finalProjectName = isCurrentDir ? basename(targetDir) : projectName;
+        packageJson.name = finalProjectName;
 
         // Initialize dependencies if not present
         if (!packageJson.dependencies) {
@@ -716,7 +722,7 @@ async function createProject(projectName, options = {}) {
         logSuccess('package.json updated');
 
         // Step 5: Create .env from .env.example
-        logStep(5, 'Creating environment file...');
+        logStep(stepOffset + 3, 'Creating environment file...');
         const envExamplePath = join(targetDir, '.env.example');
         const envPath = join(targetDir, '.env');
         if (existsSync(envExamplePath)) {
@@ -728,7 +734,7 @@ async function createProject(projectName, options = {}) {
 
         // Step 6: Install dependencies if requested
         if (options.install) {
-            logStep(6, 'Installing dependencies...');
+            logStep(stepOffset + 4, 'Installing dependencies...');
             try {
                 execSync('npm install', {
                     cwd: targetDir,
@@ -752,7 +758,9 @@ async function createProject(projectName, options = {}) {
 
         console.log('\nNext steps:');
         let step = 1;
-        console.log(`  ${step++}. ${colors.cyan}cd ${projectName}${colors.reset}`);
+        if (!isCurrentDir) {
+            console.log(`  ${step++}. ${colors.cyan}cd ${projectName}${colors.reset}`);
+        }
 
         if (!options.install) {
             console.log(`  ${step++}. ${colors.cyan}npm install${colors.reset}`);
@@ -856,10 +864,11 @@ ${colors.bright}${colors.green}DESCRIPTION${colors.reset}
 ${colors.bright}${colors.green}ARGUMENTS${colors.reset}
     ${colors.cyan}project-name${colors.reset}
             The name of your new project directory. If omitted, you will be
-            prompted to enter it interactively.
+            prompted to enter it interactively. Press Enter without typing
+            a name (or use ".") to scaffold in the current directory.
 
             ${colors.yellow}Validation:${colors.reset} Only letters, numbers, hyphens, and underscores
-            ${colors.yellow}Example:${colors.reset} my-app, my_blog, myapp123
+            ${colors.yellow}Example:${colors.reset} my-app, my_blog, myapp123, . (current directory)
 
 ${colors.bright}${colors.green}OPTIONS${colors.reset}
     ${colors.cyan}--install, -i${colors.reset}
@@ -911,6 +920,9 @@ ${colors.bright}${colors.green}EXAMPLES${colors.reset}
     ${colors.yellow}# Fully interactive - prompts for everything${colors.reset}
     npx create-atsdc-stack
 
+    ${colors.yellow}# Scaffold in current directory${colors.reset}
+    npx create-atsdc-stack .
+
     ${colors.yellow}# Provide name, get prompted for install/setup options${colors.reset}
     npx create-atsdc-stack my-awesome-app
 
@@ -1062,17 +1074,18 @@ if (needsInteractive && !projectName) {
 
 // Prompt for project name if not provided
 if (!projectName) {
-    projectName = await promptUser('What would you like to name your project?');
+    projectName = await promptUser('What would you like to name your project? (Press Enter to use current directory)');
 
+    // If empty, use current directory
     if (!projectName) {
-        logError('Project name is required');
-        process.exit(1);
-    }
-
-    // Validate project name (basic validation)
-    if (!/^[a-z0-9-_]+$/i.test(projectName)) {
-        logError('Project name can only contain letters, numbers, hyphens, and underscores');
-        process.exit(1);
+        projectName = '.';
+        logSuccess('Using current directory for project setup');
+    } else {
+        // Validate project name (basic validation) - only if not using current dir
+        if (projectName !== '.' && !/^[a-z0-9-_]+$/i.test(projectName)) {
+            logError('Project name can only contain letters, numbers, hyphens, and underscores');
+            process.exit(1);
+        }
     }
     console.log();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-atsdc-stack",
-    "version": "1.0.1",
+    "version": "1.1.0",
     "description": "ATSDC Stack - Astro, TypeScript, SCSS, Drizzle, Clerk CLI utility",
     "type": "module",
     "bin": {