create-atsdc-stack 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node -e:*)",
+      "Bash(git mv:*)",
+      "Bash(git add:*)"
+    ]
+  }
+}

package/CONTRIBUTING.md

@@ -0,0 +1,342 @@
+# Contributing to ATSDC Stack
+
+Thank you for your interest in contributing to the ATSDC Stack! This document provides guidelines and instructions for contributing.
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.
+
+## How to Contribute
+
+### Reporting Bugs
+
+If you find a bug, please create an issue with:
+
+1. A clear, descriptive title
+2. Steps to reproduce the issue
+3. Expected behavior
+4. Actual behavior
+5. Your environment (OS, Node version, etc.)
+6. Screenshots (if applicable)
+
+### Suggesting Enhancements
+
+We welcome feature requests! Please create an issue with:
+
+1. A clear, descriptive title
+2. Detailed description of the proposed feature
+3. Use cases and benefits
+4. Possible implementation approach (optional)
+
+### Pull Requests
+
+1. **Fork the repository**
+
+   ```bash
+   git clone https://github.com/yourusername/atsdc-stack.git
+   cd atsdc-stack
+   ```
+
+2. **Create a feature branch**
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+3. **Make your changes**
+   - Follow the existing code style
+   - Write clear, concise commit messages
+   - Add tests if applicable
+   - Update documentation as needed
+
+4. **Test your changes**
+
+   ```bash
+   npm run build
+   npm run preview
+   ```
+
+5. **Commit your changes**
+
+   ```bash
+   git add .
+   git commit -m "feat: add amazing new feature"
+   ```
+
+6. **Push to your fork**
+
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. **Create a Pull Request**
+   - Use a clear, descriptive title
+   - Reference any related issues
+   - Describe your changes in detail
+   - Include screenshots for UI changes
+
+## Development Guidelines
+
+### Code Style
+
+#### TypeScript
+
+- Use TypeScript for all new code
+- Prefer interfaces over types for object shapes
+- Use strict mode
+- Avoid `any` - use `unknown` if necessary
+
+```typescript
+// Good
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+// Avoid
+type User = {
+  id: any;
+  name: any;
+};
+```
+
+#### SCSS Architecture
+
+**Critical Rule**: Never use inline `<style>` tags in `.astro` files unless the component is completely self-standing and not part of the main layout.
+
+```astro
+<!-- GOOD: External styles with data attributes (preferred) -->
+---
+import '@/styles/components/button.scss';
+---
+<button class="btn" data-variant="primary" data-size="lg">Click Me</button>
+```
+
+```astro
+<!-- GOOD: External styles with class chaining (alternative) -->
+---
+import '@/styles/components/button.scss';
+---
+<button class="btn primary lg">Click Me</button>
+```
+
+```astro
+<!-- BAD: Inline styles (avoid this) -->
+<button class="btn">Click Me</button>
+<style>
+  .btn { /* styles */ }
+</style>
+```
+
+**SCSS File Organization:**
+
+- **Variables**: `src/styles/variables/globals.scss`
+- **Mixins**: `src/styles/variables/mixins.scss`
+- **Global styles**: `src/styles/global.scss`
+- **Component styles**: `src/styles/components/[component-name].scss`
+- **Page styles**: `src/styles/pages/[page-name].scss`
+
+**Naming Conventions & Modifier Strategy:**
+
+- Use **data attributes** for modifiers by default (preferred for state and variants)
+- Use **class chaining** when data attributes aren't appropriate
+- Use kebab-case for file names
+- Prefix component-specific classes with component name
+- Use BEM for elements only (not modifiers)
+
+```scss
+// Component: Button
+.btn {
+  @include button-base;
+
+  // Preferred: Data attribute modifiers
+  &[data-variant='primary'] { /* state/variant */ }
+  &[data-size='lg'] { /* size modifier */ }
+  &[data-state='loading'] { /* dynamic state */ }
+
+  // Alternative: Class chaining
+  &.primary { /* variant */ }
+  &.lg { /* size modifier */ }
+  &.loading { /* dynamic state */ }
+
+  // BEM for elements (still valid)
+  &__icon { /* element */ }
+}
+```
+
+**When to use data attributes vs. class chaining:**
+
+- **Data attributes (preferred):**
+  - Dynamic states (loading, active, disabled)
+  - Variants (primary, secondary, success, danger)
+  - Configuration (size, padding, alignment)
+  - Semantic modifiers that describe state
+
+- **Class chaining (when appropriate):**
+  - CSS-only solutions without JavaScript
+  - When data attributes feel verbose
+  - Simple utility classes
+  - When working with third-party libraries
+
+#### Database Schema
+
+- Use NanoID for primary keys
+- Always define Zod schemas for validation
+- Include timestamps (createdAt, updatedAt)
+- Use descriptive column names
+
+```typescript
+// Good
+export const posts = pgTable('posts', {
+  id: varchar('id', { length: 21 })
+    .primaryKey()
+    .$defaultFn(() => nanoid()),
+  title: varchar('title', { length: 255 }).notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+});
+
+// Corresponding Zod schema
+export const createPostSchema = z.object({
+  title: z.string().min(1).max(255),
+});
+```
+
+#### API Routes
+
+- Always validate input with Zod
+- Use proper HTTP status codes
+- Return consistent response formats
+- Handle errors gracefully
+
+```typescript
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const body = await request.json();
+    const validated = schema.parse(body);
+
+    // ... process request
+
+    return new Response(
+      JSON.stringify({ data: result }),
+      { status: 200 }
+    );
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return new Response(
+        JSON.stringify({ error: 'Validation error', details: error.errors }),
+        { status: 400 }
+      );
+    }
+    // ... handle other errors
+  }
+};
+```
+
+### Commit Message Guidelines
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+type(scope): subject
+
+body
+
+footer
+```
+
+**Types:**
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+**Examples:**
+
+```text
+feat(auth): add OAuth integration with Google
+fix(db): resolve connection pool timeout issue
+docs(readme): update installation instructions
+style(scss): reorganize component styles
+refactor(api): simplify error handling
+```
+
+### Testing
+
+- Test your changes locally before submitting
+- Ensure the build passes: `npm run build`
+- Check TypeScript types: `npx astro check`
+- Test database migrations if applicable
+
+### Documentation
+
+- Update README.md if you change functionality
+- Add JSDoc comments to functions and components
+- Update INSTALLATION.md for setup changes
+- Include inline comments for complex logic
+
+## Project Structure Conventions
+
+```text
+src/
+├── components/        # Reusable Astro components
+│   └── ComponentName.astro
+├── db/               # Database layer
+│   ├── client.ts     # Database client
+│   ├── schema.ts     # Drizzle schemas
+│   └── validations.ts # Zod schemas
+├── layouts/          # Layout components
+│   └── Layout.astro
+├── pages/            # Routes and pages
+│   ├── api/          # API routes
+│   │   └── endpoint.ts
+│   └── index.astro
+└── styles/           # SCSS files
+    ├── components/   # Component styles
+    ├── pages/        # Page styles
+    ├── variables/
+    │   ├── globals.scss
+    │   └── mixins.scss
+    └── global.scss
+```
+
+## Adding New Dependencies
+
+When adding a new dependency:
+
+1. Justify the need - avoid dependency bloat
+2. Check license compatibility (MIT preferred)
+3. Verify it's actively maintained
+4. Consider bundle size impact
+5. Update package.json and documentation
+
+## Release Process
+
+Maintainers will handle releases:
+
+1. Update version in package.json
+2. Update CHANGELOG.md
+3. Create a git tag
+4. Publish to npm
+
+## Questions?
+
+If you have questions:
+
+1. Check existing issues and discussions
+2. Review the documentation
+3. Create a new issue with the `question` label
+
+## Recognition
+
+Contributors will be recognized in:
+
+- README.md contributors section
+- Release notes
+- Project documentation
+
+Thank you for contributing to ATSDC Stack!

package/INSTALLATION.md

@@ -0,0 +1,359 @@
+# Installation Guide
+
+This guide provides detailed shell commands for initializing a new Astro project with the ATSDC Stack.
+
+## Quick Start
+
+### Option 1: Using the CLI (Recommended)
+
+```bash
+npx create-atsdc-stack my-app
+cd my-app
+npm install
+```
+
+### Option 2: Manual Setup from Scratch
+
+If you want to build the stack manually from scratch, follow these steps:
+
+## Step 1: Initialize Astro Project
+
+```bash
+# Create a new directory
+mkdir my-atsdc-app
+cd my-atsdc-app
+
+# Initialize npm project
+npm init -y
+
+# Install Astro and core dependencies
+npm install astro@latest
+```
+
+## Step 2: Install All Stack Dependencies
+
+### Core Framework & Language
+
+```bash
+npm install astro@latest typescript@latest
+```
+
+### Astro Integrations
+
+```bash
+npm install @astrojs/react@latest @astrojs/vercel@latest @astrojs/check@latest
+```
+
+### Authentication (Clerk)
+
+```bash
+npm install @clerk/astro@latest @clerk/clerk-react@latest
+```
+
+### Database (Drizzle ORM + PostgreSQL)
+
+```bash
+npm install drizzle-orm@latest postgres@latest @vercel/postgres@latest
+npm install -D drizzle-kit@latest
+```
+
+### Validation (Zod)
+
+```bash
+npm install zod@latest
+```
+
+### Styling (SCSS)
+
+```bash
+npm install -D sass@latest
+```
+
+### AI Integration (Vercel AI SDK)
+
+```bash
+npm install ai@latest @ai-sdk/openai@latest
+```
+
+### Unique IDs (NanoID)
+
+```bash
+npm install nanoid@latest
+```
+
+### PWA Support
+
+```bash
+npm install -D vite-plugin-pwa@latest @vite-pwa/assets-generator@latest
+```
+
+### React Dependencies (for Clerk components)
+
+```bash
+npm install react@latest react-dom@latest
+npm install -D @types/react@latest @types/react-dom@latest
+```
+
+### TypeScript Types
+
+```bash
+npm install -D @types/node@latest
+```
+
+## Step 3: All-in-One Installation Command
+
+Alternatively, install all dependencies at once:
+
+```bash
+npm install \
+  astro@latest \
+  @astrojs/react@latest \
+  @astrojs/vercel@latest \
+  @astrojs/check@latest \
+  @clerk/astro@latest \
+  @clerk/clerk-react@latest \
+  @vercel/postgres@latest \
+  ai@latest \
+  @ai-sdk/openai@latest \
+  drizzle-orm@latest \
+  nanoid@latest \
+  postgres@latest \
+  react@latest \
+  react-dom@latest \
+  typescript@latest \
+  zod@latest
+
+npm install -D \
+  @types/node@latest \
+  @types/react@latest \
+  @types/react-dom@latest \
+  @vite-pwa/assets-generator@latest \
+  drizzle-kit@latest \
+  sass@latest \
+  vite-plugin-pwa@latest
+```
+
+## Step 4: Project Structure Setup
+
+Create the necessary directories:
+
+```bash
+mkdir -p src/{components,db,layouts,pages/api,styles/components,styles/pages} public bin
+```
+
+## Step 5: Configuration Files
+
+### Create `package.json` scripts
+
+Add these to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro check && astro build",
+    "preview": "astro preview",
+    "astro": "astro",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio"
+  }
+}
+```
+
+### Create `tsconfig.json`
+
+```bash
+cat > tsconfig.json << 'EOF'
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "jsxImportSource": "react",
+    "strict": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}
+EOF
+```
+
+### Create `astro.config.mjs`
+
+```bash
+cat > astro.config.mjs << 'EOF'
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import vercel from '@astrojs/vercel/serverless';
+import clerk from '@clerk/astro';
+import { VitePWA } from 'vite-plugin-pwa';
+
+export default defineConfig({
+  output: 'server',
+  adapter: vercel(),
+  integrations: [react(), clerk()],
+  vite: {
+    plugins: [VitePWA({ registerType: 'autoUpdate' })],
+  },
+});
+EOF
+```
+
+### Create `.env.example`
+
+```bash
+cat > .env.example << 'EOF'
+DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
+PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
+CLERK_SECRET_KEY="sk_test_..."
+OPENAI_API_KEY="sk-..."
+EOF
+```
+
+### Create `.gitignore`
+
+```bash
+cat > .gitignore << 'EOF'
+node_modules/
+dist/
+.astro/
+.env
+.env.local
+.DS_Store
+.vscode/
+*.log
+drizzle/
+EOF
+```
+
+## Step 6: Environment Setup
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Edit .env with your actual credentials
+nano .env  # or use your preferred editor
+```
+
+## Step 7: Database Setup
+
+```bash
+# Push your schema to the database
+npm run db:push
+
+# Or generate migrations
+npm run db:generate
+npm run db:migrate
+```
+
+## Step 8: Start Development
+
+```bash
+npm run dev
+```
+
+Your application will be available at `http://localhost:4321`
+
+## Verification
+
+Verify your installation:
+
+```bash
+# Check Node version (should be 18+)
+node --version
+
+# Check npm version
+npm --version
+
+# Verify Astro is working
+npm run astro -- --version
+
+# Check TypeScript
+npx tsc --version
+```
+
+## Troubleshooting
+
+### Port Already in Use
+
+```bash
+# Kill process on port 4321
+lsof -ti:4321 | xargs kill -9
+
+# Or specify a different port
+npm run dev -- --port 3000
+```
+
+### Database Connection Issues
+
+```bash
+# Test PostgreSQL connection
+psql $DATABASE_URL
+
+# Check if database exists
+psql -l
+```
+
+### Clear Cache and Reinstall
+
+```bash
+# Remove node_modules and lockfile
+rm -rf node_modules package-lock.json
+
+# Clear npm cache
+npm cache clean --force
+
+# Reinstall
+npm install
+```
+
+## Next Steps
+
+1. Review the [README.md](./README.md) for architecture details
+2. Explore the example code in `src/pages/api/`
+3. Customize your database schema in `src/db/schema.ts`
+4. Set up your Clerk authentication
+5. Deploy to Vercel
+
+## Production Deployment
+
+### Vercel
+
+```bash
+# Install Vercel CLI
+npm i -g vercel
+
+# Login
+vercel login
+
+# Deploy
+vercel
+
+# Deploy to production
+vercel --prod
+```
+
+### Set Environment Variables on Vercel
+
+```bash
+vercel env add DATABASE_URL
+vercel env add CLERK_SECRET_KEY
+vercel env add OPENAI_API_KEY
+```
+
+## Support
+
+If you encounter issues:
+
+1. Check the [GitHub Issues](https://github.com/yourusername/atsdc-stack/issues)
+2. Review the official documentation for each technology
+3. Ask in the community Discord/Slack
+
+Happy coding!