create-chaaskit 0.1.0

package/dist/templates/docs/slack.md

@@ -0,0 +1,318 @@
+# Slack Integration
+
+Connect your team's Slack workspace to chat with your AI assistant directly from Slack. Team members can @mention the bot in any channel to get instant AI responses.
+
+## Features
+
+- **AI Chat via @mentions**: Mention your bot in any channel to get AI responses
+- **Thread Continuity**: Follow-up messages in a Slack thread maintain conversation context
+- **Team Notifications**: Get notified in Slack when threads are shared, messages are liked, or new members join
+- **Per-Team Configuration**: Each team can connect their own Slack workspace
+
+## Prerequisites
+
+Before enabling Slack integration, you need:
+
+1. **Teams feature enabled** - Slack integration requires the teams feature
+2. **A Slack App** - Create one at https://api.slack.com/apps
+
+## Creating a Slack App
+
+### 1. Create the App
+
+1. Go to https://api.slack.com/apps
+2. Click "Create New App" → "From scratch"
+3. Name your app and select your workspace
+4. Note the **Client ID**, **Client Secret**, and **Signing Secret** from "Basic Information"
+
+### 2. Configure Bot Token Scopes
+
+Go to "OAuth & Permissions" and add these Bot Token Scopes:
+
+| Scope | Purpose |
+|-------|---------|
+| `app_mentions:read` | Receive @mention events |
+| `channels:history` | Read channel messages for thread context |
+| `groups:history` | Read private channel messages |
+| `im:history` | Read direct messages |
+| `chat:write` | Send messages as the bot |
+| `reactions:write` | Add reactions (processing indicators) |
+| `users:read` | Look up user information |
+
+### 3. Enable Event Subscriptions
+
+1. Go to "Event Subscriptions"
+2. Turn on "Enable Events"
+3. Set the Request URL to: `{API_URL}/api/slack/events` (e.g., `https://api.your-app.com/api/slack/events`)
+4. Subscribe to these bot events:
+   - `app_mention` - When someone @mentions your bot
+   - `message.channels` - Messages in public channels (optional, for DM support)
+   - `message.groups` - Messages in private channels (optional)
+   - `message.im` - Direct messages to the bot (optional)
+
+### 4. Set OAuth Redirect URL
+
+1. Go to "OAuth & Permissions"
+2. Add a Redirect URL: `{API_URL}/api/slack/callback` (e.g., `https://api.your-app.com/api/slack/callback`)
+
+### Sample App Manifest
+
+You can use this manifest as a starting point when creating your Slack app. Go to "App Manifest" in your app settings and paste this JSON (update the URLs to match your deployment):
+
+```json
+{
+  "display_information": {
+    "name": "My AI Assistant",
+    "description": "Chat with AI directly in Slack",
+    "background_color": "#6366f1"
+  },
+  "features": {
+    "app_home": {
+      "messages_tab_enabled": true,
+      "messages_tab_read_only_enabled": false
+    },
+    "bot_user": {
+      "display_name": "AI Assistant",
+      "always_online": true
+    }
+  },
+  "oauth_config": {
+    "redirect_urls": [
+      "https://api.your-app.com/api/slack/callback"
+    ],
+    "scopes": {
+      "bot": [
+        "app_mentions:read",
+        "channels:history",
+        "groups:history",
+        "im:history",
+        "chat:write",
+        "reactions:write",
+        "users:read"
+      ]
+    }
+  },
+  "settings": {
+    "event_subscriptions": {
+      "request_url": "https://api.your-app.com/api/slack/events",
+      "bot_events": [
+        "app_mention",
+        "message.channels",
+        "message.groups",
+        "message.im"
+      ]
+    },
+    "org_deploy_enabled": false,
+    "socket_mode_enabled": false,
+    "token_rotation_enabled": false
+  }
+}
+```
+
+**Note**: Replace `api.your-app.com` with your actual API domain (the value of `API_URL`). Both the `request_url` and `redirect_urls` must be publicly accessible.
+
+## Configuration
+
+### Environment Variables
+
+Add these to your `.env` file:
+
+```bash
+SLACK_CLIENT_ID=your-client-id
+SLACK_CLIENT_SECRET=your-client-secret
+SLACK_SIGNING_SECRET=your-signing-secret
+SLACK_INTERNAL_SECRET=any-random-secret-for-internal-calls
+```
+
+Generate the internal secret with:
+```bash
+openssl rand -hex 32
+```
+
+### App Configuration
+
+Enable Slack in your `config/app.config.ts`:
+
+```typescript
+import type { AppConfig } from '@chaaskit/shared';
+
+export const config: AppConfig = {
+  // ... other config
+
+  teams: {
+    enabled: true,  // Required for Slack
+  },
+
+  slack: {
+    enabled: true,
+    clientIdEnvVar: 'SLACK_CLIENT_ID',
+    clientSecretEnvVar: 'SLACK_CLIENT_SECRET',
+    signingSecretEnvVar: 'SLACK_SIGNING_SECRET',
+    internalSecretEnvVar: 'SLACK_INTERNAL_SECRET',
+
+    // Optional: Restrict to specific plans
+    allowedPlans: ['pro', 'enterprise'],
+
+    // AI chat settings
+    aiChat: {
+      enabled: true,
+      threadContinuity: true,  // Maintain context across Slack thread replies
+    },
+
+    // Team notifications
+    notifications: {
+      events: [
+        { event: 'thread_shared', enabled: true },
+        { event: 'message_liked', enabled: true },
+        { event: 'team_member_joined', enabled: true },
+      ],
+    },
+  },
+};
+```
+
+## Connecting a Team
+
+Once configured, team admins can connect Slack from the Team Settings page:
+
+1. Go to Team Settings
+2. Find the "Slack Integration" section
+3. Click "Add to Slack"
+4. Authorize the app in your Slack workspace
+5. You'll be redirected back with a success message
+
+## Using the Bot
+
+### Basic Usage
+
+Mention the bot in any channel:
+
+```
+@YourBot What's the weather like today?
+```
+
+The bot will:
+1. Add an 👀 reaction to show it's processing
+2. Generate a response using your AI agent
+3. Reply in a thread
+4. Replace the 👀 with ✅ when complete
+
+**Note:** The bot only responds to messages that @mention it. Regular channel messages without an @mention are ignored.
+
+### Thread Continuity
+
+Once you've @mentioned the bot, you can continue the conversation in the thread **without** needing to @mention it again:
+
+```
+User: @YourBot Explain quantum computing
+Bot: Quantum computing uses quantum bits (qubits)...
+
+User: Can you give me an example?
+Bot: Sure! A classic example is Shor's algorithm...
+```
+
+The bot automatically responds to all messages in threads where it has been mentioned, maintaining context from the conversation.
+
+### Response Formatting
+
+The bot formats responses using Slack's mrkdwn syntax, so you'll see proper formatting for bold text, code blocks, lists, and links.
+
+### Context from Your App
+
+The bot uses the same AI agent and team context as your web app. If you've configured team context in Team Settings, it will be included in Slack conversations.
+
+## Notifications
+
+When enabled, your team's Slack channel will receive notifications for:
+
+| Event | Notification |
+|-------|--------------|
+| Thread Shared | When a team member shares a conversation |
+| Message Liked | When someone gives positive feedback on an AI response |
+| Member Joined | When a new member joins the team |
+
+### Configuring Notification Channel
+
+1. Go to Team Settings → Slack Integration
+2. Enter the notification channel (e.g., `#general`)
+3. Click "Save Settings"
+
+## Architecture
+
+### Event Flow
+
+```
+1. User @mentions bot in Slack
+2. Slack sends event to /api/slack/events
+3. Server verifies signature, stores event, responds 200 OK (within 3s)
+4. Server triggers /api/slack/internal/process asynchronously
+5. Event processor:
+   - Fetches Slack thread history for context
+   - Finds/creates internal thread for continuity
+   - Calls AI agent with conversation
+   - Posts response back to Slack
+```
+
+### Data Storage
+
+| Model | Purpose |
+|-------|---------|
+| `SlackIntegration` | Stores team's Slack connection (workspace ID, encrypted tokens, settings) |
+| `SlackMessageEvent` | Tracks incoming events for deduplication and retry |
+
+Tokens are encrypted at rest using AES-256-GCM.
+
+### Retry Logic
+
+Failed events are automatically retried:
+- Events stuck in "pending" or "processing" for >3 minutes are retried
+- Maximum 3 retry attempts per event
+- Use `POST /api/slack/internal/retry` to trigger retry (requires internal secret)
+
+## API Endpoints
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/api/slack/install/:teamId` | GET | User (Admin) | Start OAuth flow |
+| `/api/slack/callback` | GET | None | OAuth callback |
+| `/api/slack/:teamId/status` | GET | User (Viewer+) | Get integration status |
+| `/api/slack/:teamId/settings` | PATCH | User (Admin) | Update settings |
+| `/api/slack/:teamId` | DELETE | User (Admin) | Disconnect Slack |
+| `/api/slack/events` | POST | Slack Signature | Receive Slack events |
+| `/api/slack/internal/process` | POST | Internal Secret | Process an event |
+| `/api/slack/internal/retry` | POST | Internal Secret | Retry stale events |
+
+## Troubleshooting
+
+### Bot doesn't respond
+
+1. Check that your Slack app has the required scopes
+2. Verify Event Subscriptions URL is correct and verified
+3. Check server logs for errors
+4. Ensure the team has Slack connected (check Team Settings)
+
+### "Invalid signature" errors
+
+- Verify `SLACK_SIGNING_SECRET` matches your Slack app's signing secret
+- Ensure raw request body is being used for signature verification
+
+### Events timing out
+
+Slack requires a response within 3 seconds. The integration handles this by:
+1. Quickly acknowledging the event
+2. Processing asynchronously via internal endpoint
+
+If you see timeout errors, check that `/api/slack/internal/process` is accessible from your server.
+
+### Thread context not working
+
+- Ensure `threadContinuity` is enabled in config
+- The bot needs `channels:history` (or equivalent) scope to read thread history
+- Private channels require `groups:history`
+
+## Security Considerations
+
+- **Token Encryption**: Slack tokens are encrypted at rest using your `SESSION_SECRET`
+- **Signature Verification**: All incoming Slack requests are verified using HMAC-SHA256
+- **Internal Endpoints**: Protected by a separate secret to prevent external access
+- **Scope Minimization**: Only request the Slack scopes you need

package/dist/templates/docs/styling.md

@@ -0,0 +1,288 @@
+# Styling Guide
+
+This guide documents the styling conventions used throughout the application to maintain visual consistency. Follow these patterns when building new pages and components.
+
+## Design Principles
+
+1. **Soft, not harsh**: Avoid hard borders and stark contrasts. Use subtle background colors for separation instead of explicit borders.
+2. **Consistent spacing**: Use the same padding and margin patterns across similar components.
+3. **Visual hierarchy**: Use typography and subtle color differences, not heavy borders, to establish hierarchy.
+
+## Color Variables
+
+Use CSS variables for all colors. Never hardcode color values.
+
+### Primary Colors
+
+| Variable | Usage |
+|----------|-------|
+| `--color-primary` | Primary actions, active states, links |
+| `--color-primary-hover` | Hover state for primary elements |
+| `--color-secondary` | Secondary accent color |
+
+### Background Colors
+
+| Variable | Usage |
+|----------|-------|
+| `--color-background` | Main page background |
+| `--color-background-secondary` | Cards, sections, elevated surfaces |
+| `--color-sidebar` | Sidebar background |
+
+### Text Colors
+
+| Variable | Usage |
+|----------|-------|
+| `--color-text-primary` | Main text, headings |
+| `--color-text-secondary` | Body text, descriptions |
+| `--color-text-muted` | Helper text, timestamps, placeholders |
+
+### Input Colors
+
+| Variable | Usage |
+|----------|-------|
+| `--color-input-background` | Input field backgrounds |
+| `--color-input-border` | Input field borders (subtle) |
+
+### Status Colors
+
+| Variable | Usage |
+|----------|-------|
+| `--color-success` | Success messages, positive states |
+| `--color-warning` | Warning messages, caution states |
+| `--color-error` | Error messages, destructive actions |
+
+## Section Styling
+
+### Cards and Sections
+
+**DO**: Use background colors for visual separation
+
+```tsx
+// Good - Soft, borderless card
+<div className="rounded-lg bg-[var(--color-background-secondary)] p-6">
+  <h2 className="text-lg font-semibold text-[var(--color-text-primary)] mb-4">
+    Section Title
+  </h2>
+  {/* content */}
+</div>
+```
+
+**DON'T**: Use explicit borders for main sections
+
+```tsx
+// Bad - Harsh border
+<div className="rounded-lg border border-[var(--color-border)] bg-[var(--color-background-secondary)] p-6">
+```
+
+### List Items with Dividers
+
+When items need visual separation, use the background color as a subtle divider:
+
+```tsx
+// Good - Subtle dividers using background color
+<div className="divide-y divide-[var(--color-background)]">
+  {items.map(item => (
+    <div key={item.id} className="px-4 py-3">
+      {/* item content */}
+    </div>
+  ))}
+</div>
+```
+
+### Table-like Lists
+
+Use grid layouts with background-based headers instead of traditional bordered tables:
+
+```tsx
+// Header
+<div className="px-4 py-3 bg-[var(--color-background)]">
+  <div className="grid grid-cols-12 gap-4 text-sm font-medium text-[var(--color-text-muted)]">
+    <div className="col-span-3">Name</div>
+    <div className="col-span-2">Status</div>
+    {/* ... */}
+  </div>
+</div>
+
+// Body
+<div className="divide-y divide-[var(--color-background)]">
+  {items.map(item => (
+    <div key={item.id} className="px-4 py-3 hover:bg-[var(--color-background)]/50">
+      <div className="grid grid-cols-12 gap-4 items-center">
+        {/* item content */}
+      </div>
+    </div>
+  ))}
+</div>
+```
+
+## Button Styling
+
+### Primary Buttons
+
+```tsx
+<button className="rounded-lg bg-[var(--color-primary)] px-4 py-2 font-medium text-white hover:bg-[var(--color-primary-hover)]">
+  Save
+</button>
+```
+
+### Secondary Buttons (Soft)
+
+```tsx
+// Good - Background-based, no border
+<button className="rounded-lg bg-[var(--color-background-secondary)] px-4 py-2 text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)]/80">
+  Cancel
+</button>
+```
+
+```tsx
+// Avoid - Bordered button
+<button className="rounded-lg border border-[var(--color-border)] px-4 py-2">
+```
+
+### Text/Link Buttons
+
+```tsx
+<button className="text-sm text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)]">
+  Back to chat
+</button>
+```
+
+### Destructive Buttons
+
+```tsx
+<button className="rounded-lg bg-[var(--color-error)] px-4 py-2 font-medium text-white hover:bg-[var(--color-error)]/90">
+  Delete
+</button>
+```
+
+## Form Inputs
+
+Inputs should have subtle borders using the input-specific variables:
+
+```tsx
+<input
+  type="text"
+  className="w-full rounded-lg border border-[var(--color-input-border)] bg-[var(--color-input-background)] px-4 py-2 text-[var(--color-text-primary)] placeholder-[var(--color-text-muted)] focus:border-[var(--color-primary)] focus:outline-none"
+/>
+```
+
+For selects in compact contexts (like inline dropdowns):
+
+```tsx
+<select className="rounded border border-[var(--color-input-border)] bg-[var(--color-input-background)] px-2 py-1 text-sm text-[var(--color-text-primary)]">
+```
+
+## Pills and Badges
+
+Use background colors with no borders:
+
+```tsx
+// Status badge
+<span className="rounded-full bg-[var(--color-primary)]/10 px-2 py-0.5 text-xs font-medium text-[var(--color-primary)]">
+  Active
+</span>
+
+// Clickable pill
+<Link className="inline-flex items-center rounded-full bg-[var(--color-background)] px-2 py-0.5 text-xs text-[var(--color-text-secondary)] hover:bg-[var(--color-primary)]/10 hover:text-[var(--color-primary)]">
+  Team Name
+</Link>
+```
+
+## Avatar Placeholders
+
+When showing initials instead of an image, use the primary color:
+
+```tsx
+<div className="w-8 h-8 rounded-full bg-primary flex items-center justify-center text-white text-sm font-medium">
+  {name[0].toUpperCase()}
+</div>
+```
+
+Note: Use Tailwind's `bg-primary` class rather than `bg-[var(--color-primary)]` for avatars, as it's more reliable in some contexts.
+
+## Page Layout
+
+### Standard Admin/Settings Page
+
+```tsx
+<div className="min-h-screen bg-[var(--color-background)] p-8">
+  <div className="mx-auto max-w-6xl">
+    {/* Header */}
+    <div className="flex items-center justify-between mb-8">
+      <h1 className="text-2xl font-bold text-[var(--color-text-primary)]">
+        Page Title
+      </h1>
+      <div className="flex gap-4">
+        {/* Navigation buttons */}
+      </div>
+    </div>
+
+    {/* Error/Success messages */}
+    {error && (
+      <div className="mb-6 rounded-lg bg-[var(--color-error)]/10 p-4 text-sm text-[var(--color-error)]">
+        {error}
+      </div>
+    )}
+
+    {/* Content sections */}
+    <div className="rounded-lg bg-[var(--color-background-secondary)] p-6 mb-6">
+      {/* Section content */}
+    </div>
+  </div>
+</div>
+```
+
+## Hover States
+
+Use subtle background changes for hover states:
+
+```tsx
+// List item hover
+className="hover:bg-[var(--color-background)]/50"
+
+// Card hover (when clickable)
+className="hover:bg-[var(--color-background-secondary)]/80"
+```
+
+## Spacing Constants
+
+| Use Case | Padding | Margin |
+|----------|---------|--------|
+| Page padding | `p-8` | - |
+| Card/Section padding | `p-6` | `mb-6` or `mb-8` |
+| List item padding | `px-4 py-3` | - |
+| Compact item padding | `px-2 py-1` | - |
+| Button padding | `px-4 py-2` | - |
+| Badge padding | `px-2 py-0.5` | - |
+
+## Reference Components
+
+When building new UI, refer to these existing components for styling patterns:
+
+| Component | Location | Good For |
+|-----------|----------|----------|
+| Settings Modal | `components/SettingsModal.tsx` | Modal dialogs, form layouts |
+| Team Settings | `pages/TeamSettingsPage.tsx` | Full-page settings, member lists |
+| Admin Dashboard | `pages/AdminDashboardPage.tsx` | Stats cards, charts, data display |
+| Admin Users | `pages/AdminUsersPage.tsx` | Data tables, search, pagination |
+| Sidebar | `components/Sidebar.tsx` | Navigation, lists, collapsible sections |
+
+## Anti-Patterns to Avoid
+
+1. **Explicit borders on cards**: Use `bg-background-secondary` instead of `border border-[var(--color-border)]`
+
+2. **Dark/harsh dividers**: Use `divide-[var(--color-background)]` instead of `divide-[var(--color-border)]`
+
+3. **Bordered buttons**: Use background colors for secondary buttons
+
+4. **CSS variable syntax for avatars**: Use Tailwind classes like `bg-primary` for avatar backgrounds
+
+5. **Inconsistent spacing**: Follow the spacing constants above
+
+6. **Hardcoded colors**: Always use CSS variables
+
+## Tailwind vs CSS Variables
+
+- **Use Tailwind classes** (`bg-primary`, `text-text-primary`) when available and working correctly
+- **Use CSS variables** (`bg-[var(--color-primary)]`) when Tailwind classes don't resolve properly or for complex color manipulation
+- **For avatars specifically**, prefer Tailwind classes as they're more reliable

package/dist/templates/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_NAME}}</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>