create-chaaskit 0.1.0

package/dist/templates/docs/index.md

@@ -0,0 +1,139 @@
+# {{PROJECT_NAME}} Documentation
+
+Welcome to your ChaasKit application. This documentation covers how to configure, extend, and deploy your app.
+
+## Quick Start
+
+```bash
+# Configure environment
+cp .env.example .env
+# Edit .env with your DATABASE_URL and API keys
+
+# Setup database
+pnpm db:push
+
+# Start development
+pnpm dev
+```
+
+Your app will be available at:
+- **Frontend**: http://localhost:5173
+- **Backend**: http://localhost:3000
+
+## Documentation
+
+### Getting Started
+| Guide | Description |
+|-------|-------------|
+| [Installation](./installation.md) | Initial setup and requirements |
+| [Configuration](./configuration.md) | App settings, theming, AI providers |
+| [Development](./development.md) | Development workflow and tips |
+| [Deployment](./deployment.md) | Production deployment guide |
+
+### Features
+| Guide | Description |
+|-------|-------------|
+| [Authentication](./authentication.md) | Email/password, OAuth, Magic Links |
+| [Custom Pages](./custom-pages.md) | Adding marketing pages, landing pages |
+| [Documents](./documents.md) | Mentionable documents with @mentions |
+| [API Keys](./api-keys.md) | Programmatic API access |
+| [MCP Integration](./mcp.md) | Connect AI to external tools |
+| [Native Tools](./native-tools.md) | Built-in tools and creating custom ones |
+
+### Advanced
+| Guide | Description |
+|-------|-------------|
+| [Extensions](./extensions.md) | Custom agents, pages, payment plans |
+| [Queue System](./queue.md) | Background jobs and async processing |
+| [Scheduled Prompts](./scheduled-prompts.md) | Automated recurring AI tasks |
+| [Slack Integration](./slack.md) | Connect your app to Slack |
+| [Admin Dashboard](./admin.md) | Site-wide administration |
+| [Settings](./settings.md) | User preferences and settings |
+| [Styling](./styling.md) | UI conventions and theming |
+
+## Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── config/
+│   └── app.config.ts      # Your app configuration
+├── docs/                   # This documentation
+├── extensions/
+│   ├── agents/            # Custom AI agents
+│   ├── payment-plans/     # Custom pricing plans
+│   └── pages/             # Custom frontend pages
+├── prisma/
+│   └── schema.prisma      # Database schema
+├── public/
+│   └── logo.svg           # Your logo
+├── src/
+│   └── main.tsx           # Frontend entry point
+├── .env                   # Environment variables (create from .env.example)
+├── index.html
+├── package.json
+└── vite.config.ts
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `config/app.config.ts` | Main configuration (UI, themes, auth, AI, payments) |
+| `.env` | Environment variables and secrets |
+| `prisma/schema.prisma` | Database schema |
+| `public/logo.svg` | Application logo |
+| `extensions/` | Your custom code |
+
+## Commands
+
+```bash
+pnpm dev          # Start development servers
+pnpm build        # Build for production
+pnpm start        # Run production server
+pnpm db:push      # Push schema changes (development)
+pnpm db:migrate   # Run migrations (production)
+pnpm db:studio    # Open Prisma Studio GUI
+pnpm db:generate  # Regenerate Prisma client
+pnpm typecheck    # Run TypeScript checks
+```
+
+## Environment Variables
+
+Required in `.env`:
+
+```bash
+# Database
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+
+# Auth secrets (min 32 chars - generate with: openssl rand -base64 32)
+SESSION_SECRET=your-session-secret
+JWT_SECRET=your-jwt-secret
+
+# AI Provider (at least one required)
+ANTHROPIC_API_KEY=sk-ant-...
+# or
+OPENAI_API_KEY=sk-...
+
+# URLs
+APP_URL=http://localhost:5173
+API_URL=http://localhost:3000
+```
+
+Optional:
+```bash
+# Payments
+STRIPE_SECRET_KEY=sk_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+# OAuth
+GOOGLE_CLIENT_ID=...
+GOOGLE_CLIENT_SECRET=...
+GITHUB_CLIENT_ID=...
+GITHUB_CLIENT_SECRET=...
+```
+
+## Getting Help
+
+- Check the documentation in this `docs/` folder
+- Review `config/app.config.ts` for available options
+- See the [ChaasKit Template repository](https://github.com/your-org/chaaskit) for updates

package/dist/templates/docs/installation.md

@@ -0,0 +1,286 @@
+# Installation
+
+ChaasKit uses React Router v7 framework mode to provide a full-stack application with server-side rendering and a rich client experience.
+
+## Prerequisites
+
+- **Node.js** 18 or higher
+- **pnpm** 8 or higher (recommended) or npm/yarn
+- **PostgreSQL** 14 or higher
+
+## Create a New Project
+
+```bash
+# Create a new ChaasKit project
+npx chaaskit create my-app
+
+# Navigate to your project
+cd my-app
+```
+
+Or with options:
+```bash
+npx chaaskit create my-app --skip-install --use-npm
+```
+
+## Configure Environment
+
+Copy the example environment file and configure it:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your settings:
+
+```bash
+# Database (required)
+DATABASE_URL="postgresql://user:password@localhost:5432/my_app"
+
+# Auth secrets (required - generate with: openssl rand -base64 32)
+SESSION_SECRET=your-session-secret-min-32-chars
+JWT_SECRET=your-jwt-secret-min-32-chars
+
+# AI Provider (at least one required)
+OPENAI_API_KEY=sk-...
+# or
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Application URLs (optional in development)
+APP_URL=http://localhost:5173
+API_URL=http://localhost:3000
+```
+
+## Setup Database
+
+Push the schema to your database:
+
+```bash
+pnpm db:push
+```
+
+This creates all the required tables. For production, use migrations instead:
+
+```bash
+pnpm db:migrate
+```
+
+## Start Development
+
+```bash
+pnpm dev
+```
+
+This starts:
+- The React Router dev server with HMR at `http://localhost:5173`
+- The Express API server at `http://localhost:3000`
+
+Visit `http://localhost:5173` to see your app!
+
+## Project Structure
+
+```
+my-app/
+├── app/
+│   ├── routes/                    # React Router v7 routes
+│   │   ├── _index.tsx             # Landing page (/)
+│   │   ├── login.tsx              # Login page (/login)
+│   │   ├── register.tsx           # Register page (/register)
+│   │   ├── chat._index.tsx        # Main chat (/chat)
+│   │   ├── chat.thread.$threadId.tsx  # Thread view (/chat/thread/:id)
+│   │   ├── chat.documents.tsx     # Documents page (/chat/documents)
+│   │   └── ...                    # Other routes
+│   ├── components/                # Client wrapper components
+│   │   ├── ChatClient.tsx         # Chat page client wrapper
+│   │   ├── ClientOnly.tsx         # SSR boundary component
+│   │   └── ...
+│   ├── root.tsx                   # HTML shell, theme, providers
+│   ├── routes.ts                  # Route configuration
+│   ├── entry.client.tsx           # Client-side entry
+│   └── entry.server.tsx           # Server-side entry
+├── config/
+│   └── app.config.ts              # Application configuration
+├── extensions/
+│   ├── agents/                    # Custom AI agents
+│   ├── payment-plans/             # Custom pricing plans
+│   └── pages/                     # Custom frontend pages
+├── prisma/
+│   └── schema/
+│       ├── base.prisma            # ChaasKit models (synced from package)
+│       └── custom.prisma          # Your custom models
+├── public/
+│   ├── logo.svg                   # Your logo
+│   └── favicon.svg                # Favicon
+├── .env                           # Environment variables
+├── server.js                      # Production server
+├── vite.config.ts                 # Vite configuration
+├── react-router.config.ts         # React Router configuration
+└── package.json
+```
+
+## Configure Your App
+
+Edit `config/app.config.ts` to customize your application:
+
+```typescript
+import type { AppConfig } from '@chaaskit/shared';
+
+export const config: AppConfig = {
+  app: {
+    name: 'My Chat App',
+    description: 'AI-powered chat application',
+    url: 'http://localhost:5173',
+    basePath: '/chat',  // Chat app routes live under /chat
+  },
+
+  agent: {
+    type: 'built-in',
+    provider: 'openai',  // or 'anthropic'
+    model: 'gpt-4o-mini',
+    systemPrompt: 'You are a helpful AI assistant.',
+  },
+
+  // Enable features
+  teams: { enabled: true },
+  projects: {
+    enabled: true,
+    colors: ['#6366f1', '#8b5cf6', '#ec4899', /* ... */],
+  },
+  documents: {
+    enabled: true,
+    storage: { provider: 'database' },
+  },
+
+  // ... see Configuration docs for all options
+};
+```
+
+See [Configuration](./configuration.md) for all available options.
+
+## Updating ChaasKit
+
+When new versions of ChaasKit are released:
+
+```bash
+# 1. Update the packages
+pnpm update @chaaskit/server @chaaskit/client @chaaskit/db @chaaskit/shared
+
+# 2. Sync the database schema
+# This updates base.prisma with new models while preserving your custom.prisma
+pnpm db:sync
+
+# 3. Regenerate Prisma client
+pnpm db:generate
+
+# 4. Apply any schema changes to your database
+pnpm db:push
+```
+
+The `db:sync` command is safe to run - it only updates `prisma/schema/base.prisma` (the ChaasKit models) and never touches your custom models in `prisma/schema/custom.prisma`.
+
+## Database Options
+
+### Local PostgreSQL
+
+```bash
+# Create a database
+createdb my_app
+
+# Connection string
+DATABASE_URL="postgresql://localhost:5432/my_app"
+```
+
+### Supabase
+
+1. Create a project at [supabase.com](https://supabase.com)
+2. Go to Settings > Database
+3. Use the "Transaction pooler" connection string for Prisma
+
+### Neon
+
+1. Create a project at [neon.tech](https://neon.tech)
+2. Copy the connection string
+3. Enable connection pooling for production
+
+## AI Provider Setup
+
+### Anthropic
+
+1. Get an API key from [console.anthropic.com](https://console.anthropic.com)
+2. Set `ANTHROPIC_API_KEY` in `.env`
+3. Configure in `config/app.config.ts`:
+   ```typescript
+   agent: {
+     type: 'built-in',
+     provider: 'anthropic',
+     model: 'claude-sonnet-4-20250514',
+   }
+   ```
+
+### OpenAI
+
+1. Get an API key from [platform.openai.com](https://platform.openai.com)
+2. Set `OPENAI_API_KEY` in `.env`
+3. Configure in `config/app.config.ts`:
+   ```typescript
+   agent: {
+     type: 'built-in',
+     provider: 'openai',
+     model: 'gpt-4o-mini',
+   }
+   ```
+
+## Verification
+
+After setup, verify everything works:
+
+1. Open `http://localhost:5173`
+2. You should see the landing page
+3. Click "Get Started" or navigate to `/login`
+4. Register a new account
+5. Send a test message in the chat
+6. Check the terminal for any errors
+
+## Troubleshooting
+
+### Database connection issues
+
+- Ensure PostgreSQL is running
+- Check the connection string format
+- Verify the database exists: `createdb my_app`
+
+### "Module not found" errors
+
+```bash
+# Clean install
+rm -rf node_modules
+pnpm install
+```
+
+### Config not loading
+
+The server looks for config in this order:
+1. Programmatic config (via `setConfig()`)
+2. `CHAASKIT_CONFIG_PATH` environment variable
+3. `./config/app.config.ts` (relative to cwd)
+4. `./config/app.config.js`
+5. Default built-in config
+
+### Type errors
+
+```bash
+# Regenerate Prisma client
+pnpm db:generate
+pnpm typecheck
+```
+
+### Theme/hydration warnings
+
+If you see hydration warnings about `data-theme`, ensure your `app/root.tsx` uses the cookie-based theme sync pattern (this is set up by default in new projects).
+
+## Next Steps
+
+- [Configuration](./configuration.md) - Customize the application
+- [Extensions](./extensions.md) - Add custom functionality
+- [Development](./development.md) - Learn the development workflow
+- [Deployment](./deployment.md) - Deploy to production