create-chaaskit 0.1.0

package/dist/templates/docs/scheduled-prompts.md

@@ -0,0 +1,279 @@
+# Scheduled Prompts (Automations)
+
+Scheduled Prompts allow you to run AI prompts automatically on a schedule. Results are stored in dedicated threads and can trigger notifications via Slack and email.
+
+## Overview
+
+- **Schedule prompts** to run at specific times (daily, weekly, custom cron)
+- **Store results** in dedicated threads for history and context
+- **Get notified** via Slack or email when prompts complete
+- **Team or personal** - create automations for yourself or your team
+
+## Configuration
+
+Enable scheduled prompts in your `config/app.config.ts`:
+
+```typescript
+export const config: AppConfig = {
+  // ... other config
+
+  scheduledPrompts: {
+    enabled: true,
+    featureName: 'Automations',  // Display name in UI (default: "Scheduled Prompts")
+    allowUserPrompts: true,       // Allow personal automations
+    allowTeamPrompts: true,       // Allow team automations
+    defaultTimezone: 'UTC',
+
+    // Plan-based limits
+    planLimits: [
+      { plan: 'free', maxUserPrompts: 1, maxTeamPrompts: 0 },
+      { plan: 'pro', maxUserPrompts: 5, maxTeamPrompts: 10 },
+      { plan: 'enterprise', maxUserPrompts: 20, maxTeamPrompts: 50 },
+    ],
+    defaultMaxUserPrompts: 0,  // Plans not listed get no access
+    defaultMaxTeamPrompts: 0,
+  },
+};
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable the scheduled prompts feature |
+| `featureName` | string | `"Scheduled Prompts"` | Display name in sidebar and UI |
+| `allowUserPrompts` | boolean | `true` | Allow personal automations |
+| `allowTeamPrompts` | boolean | `true` | Allow team automations |
+| `defaultTimezone` | string | `"UTC"` | Default timezone for new prompts |
+| `planLimits` | array | `[]` | Limits per subscription plan |
+| `defaultMaxUserPrompts` | number | `0` | Fallback limit for unlisted plans |
+| `defaultMaxTeamPrompts` | number | `0` | Fallback limit for unlisted plans |
+
+## Email Notifications
+
+To enable email notifications, configure the email service:
+
+```typescript
+export const config: AppConfig = {
+  // ... other config
+
+  email: {
+    enabled: true,
+    fromAddress: 'noreply@yourapp.com',
+    fromName: 'Your App',
+    providerConfig: {
+      type: 'ses',
+      region: 'us-east-1',
+    },
+  },
+};
+```
+
+### AWS SES Setup
+
+1. Install the AWS SDK:
+   ```bash
+   pnpm add @aws-sdk/client-ses
+   ```
+
+2. Set AWS credentials in your environment:
+   ```bash
+   AWS_ACCESS_KEY_ID=your-access-key
+   AWS_SECRET_ACCESS_KEY=your-secret-key
+   ```
+
+3. Verify your sender email address in the [AWS SES Console](https://console.aws.amazon.com/ses/)
+
+4. If in sandbox mode, also verify recipient email addresses
+
+## Queue Requirement
+
+Scheduled prompts require the [Job Queue](./queue.md) to be enabled:
+
+```typescript
+export const config: AppConfig = {
+  queue: {
+    enabled: true,
+    providerConfig: {
+      type: 'memory',  // or 'sqs' for production
+    },
+  },
+};
+```
+
+The scheduler polls for due recurring jobs and enqueues them for execution.
+
+## Usage
+
+The Automations page shows prompts based on your sidebar selection:
+- **Personal**: Shows your personal automations and usage (e.g., "2 of 5 used")
+- **Team**: Shows the selected team's automations and usage against the team plan
+
+### Creating a Scheduled Prompt
+
+1. Navigate to **Automations** in the sidebar
+2. Click **New Automation** (disabled if plan limit reached)
+3. Fill in the form:
+   - **Name**: A descriptive name (e.g., "Daily Summary")
+   - **Prompt**: The prompt text to run
+   - **Agent**: Which AI agent to use
+   - **Schedule**: When to run (presets or custom cron)
+   - **Timezone**: Your local timezone
+   - **Notifications**: Enable Slack and/or email
+
+### Schedule Presets
+
+| Preset | Cron Expression |
+|--------|-----------------|
+| Every morning (9 AM) | `0 9 * * *` |
+| Every evening (6 PM) | `0 18 * * *` |
+| Weekdays at 9 AM | `0 9 * * 1-5` |
+| Every Monday | `0 9 * * 1` |
+| First of month | `0 9 1 * *` |
+| Every hour | `0 * * * *` |
+
+You can also enter custom cron expressions for more complex schedules.
+
+### Viewing Results
+
+Each scheduled prompt has a dedicated thread where all runs are stored:
+- The prompt is sent as a user message
+- The AI response is saved as an assistant message
+- Previous context is maintained across runs
+
+Click the thread link in the automation list to view the full history.
+
+### Manual Execution
+
+You can trigger a scheduled prompt immediately:
+1. Click the **Run Now** button on any automation
+2. The prompt executes with the current context
+3. Results appear in the thread and trigger notifications
+
+## API Endpoints
+
+### List Scheduled Prompts
+
+```http
+GET /api/scheduled-prompts?personal=true    # Personal prompts only
+GET /api/scheduled-prompts?teamId=team_xxx  # Team prompts only
+```
+
+Response includes usage limits:
+
+```json
+{
+  "prompts": [...],
+  "limits": {
+    "context": "personal",  // or "team"
+    "current": 2,           // Number currently configured
+    "max": 5                // Maximum allowed by plan
+  }
+}
+```
+
+### Create Scheduled Prompt
+
+```http
+POST /api/scheduled-prompts
+Content-Type: application/json
+
+{
+  "name": "Daily Summary",
+  "prompt": "Summarize the key developments from today.",
+  "agentId": "default",
+  "schedule": "0 18 * * *",
+  "timezone": "America/New_York",
+  "notifySlack": true,
+  "notifyEmail": true,
+  "emailRecipients": ["user@example.com"],
+  "teamId": "team_xxx"  // Optional, for team prompts
+}
+```
+
+### Update Scheduled Prompt
+
+```http
+PUT /api/scheduled-prompts/:id
+Content-Type: application/json
+
+{
+  "name": "Updated Name",
+  "enabled": false
+}
+```
+
+### Delete Scheduled Prompt
+
+```http
+DELETE /api/scheduled-prompts/:id
+```
+
+### Manual Run
+
+```http
+POST /api/scheduled-prompts/:id/run
+```
+
+## Slack Notifications
+
+If your team has [Slack integration](./slack.md) configured, scheduled prompts can post results to your notification channel.
+
+The notification includes:
+- Prompt name and completion time
+- Truncated result (first 500 characters)
+- Link to view the full thread
+
+## Database Schema
+
+The feature adds a `ScheduledPrompt` model:
+
+```prisma
+model ScheduledPrompt {
+  id              String    @id @default(cuid())
+  name            String
+  prompt          String    @db.Text
+  agentId         String?
+  schedule        String
+  timezone        String    @default("UTC")
+  enabled         Boolean   @default(true)
+  notifySlack     Boolean   @default(true)
+  notifyEmail     Boolean   @default(false)
+  emailRecipients String?   @db.Text
+  threadId        String?
+  userId          String?
+  teamId          String?
+  lastRunAt       DateTime?
+  lastRunStatus   String?
+  lastError       String?
+  runCount        Int       @default(0)
+  createdAt       DateTime  @default(now())
+  updatedAt       DateTime  @updatedAt
+}
+```
+
+## Troubleshooting
+
+### Prompt not running
+
+1. Check that the queue is enabled and processing jobs
+2. Verify the prompt is enabled (not toggled off)
+3. Check the `lastError` field for execution errors
+4. Review server logs for job handler errors
+
+### Email not sending
+
+1. Verify email is enabled in config
+2. Check AWS credentials are set correctly
+3. Confirm sender address is verified in SES
+4. In SES sandbox mode, recipient must also be verified
+
+### Slack notification not appearing
+
+1. Confirm team has active Slack integration
+2. Check notification channel is configured
+3. Verify the bot has permission to post to the channel
+
+### Plan limit reached
+
+Users see an error when creating more prompts than their plan allows. Upgrade to a higher plan or delete unused automations.

package/dist/templates/docs/settings.md

@@ -0,0 +1,415 @@
+# User Settings
+
+The ChaasKit Template includes a flexible user settings system that allows users to customize their experience and provide context to the AI.
+
+## Configuration
+
+Define available settings in `config/app.config.ts`:
+
+```typescript
+userSettings: {
+  fields: [
+    {
+      key: 'name',
+      label: 'Your Name',
+      type: 'text',
+      placeholder: 'Enter your name',
+    },
+    {
+      key: 'role',
+      label: 'Your Role',
+      type: 'select',
+      options: ['Developer', 'Designer', 'Manager', 'Other'],
+    },
+    {
+      key: 'context',
+      label: 'Additional Context',
+      type: 'textarea',
+      placeholder: 'Any context the AI should know about you...',
+    },
+  ],
+}
+```
+
+## Field Types
+
+### Text Field
+
+Simple single-line text input.
+
+```typescript
+{
+  key: 'company',
+  label: 'Company',
+  type: 'text',
+  placeholder: 'Your company name',
+}
+```
+
+### Select Field
+
+Dropdown selection from predefined options.
+
+```typescript
+{
+  key: 'experience',
+  label: 'Experience Level',
+  type: 'select',
+  options: ['Beginner', 'Intermediate', 'Expert'],
+}
+```
+
+### Textarea Field
+
+Multi-line text input for longer content.
+
+```typescript
+{
+  key: 'bio',
+  label: 'About You',
+  type: 'textarea',
+  placeholder: 'Tell us about yourself...',
+}
+```
+
+## How Settings Work
+
+### Storage
+
+User settings are stored in the `settings` JSON field on the User model:
+
+```prisma
+model User {
+  // ...
+  settings Json @default("{}")
+}
+```
+
+### API
+
+**Get Settings:**
+```http
+GET /api/user/settings
+Authorization: Bearer <token>
+```
+
+**Update Settings:**
+```http
+PUT /api/user/settings
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "name": "John",
+  "role": "Developer",
+  "context": "I work with React and Node.js"
+}
+```
+
+### AI Context
+
+Settings are automatically included in the AI's system prompt:
+
+```typescript
+// agent.ts
+if (options?.userContext) {
+  const contextStr = Object.entries(options.userContext)
+    .filter(([, v]) => v != null && v !== '')
+    .map(([k, v]) => `${k}: ${v}`)
+    .join('\n');
+
+  if (contextStr) {
+    systemPrompt += `\n\nUser context:\n${contextStr}`;
+  }
+}
+```
+
+This allows the AI to personalize responses based on user preferences.
+
+## Frontend Integration
+
+### Settings Page
+
+The settings are displayed in a form on the settings page:
+
+```tsx
+import { useAuth } from '../contexts/AuthContext';
+import { useConfig } from '../contexts/ConfigContext';
+
+function SettingsPage() {
+  const { user } = useAuth();
+  const config = useConfig();
+
+  return (
+    <form>
+      {config.userSettings.fields.map((field) => (
+        <FormField key={field.key} field={field} />
+      ))}
+    </form>
+  );
+}
+```
+
+### FormField Component
+
+Renders appropriate input based on field type:
+
+```tsx
+function FormField({ field }) {
+  switch (field.type) {
+    case 'text':
+      return <input type="text" {...props} />;
+    case 'select':
+      return (
+        <select {...props}>
+          {field.options.map((opt) => (
+            <option key={opt} value={opt}>{opt}</option>
+          ))}
+        </select>
+      );
+    case 'textarea':
+      return <textarea {...props} />;
+  }
+}
+```
+
+## MCP Credentials
+
+Users can manage credentials for MCP servers that require authentication directly in the Settings modal.
+
+### Credential Types
+
+**API Key**: For servers with `authMode: 'user-apikey'`
+- Text input to enter/update the API key
+- Key is encrypted and stored securely
+
+**OAuth**: For servers with `authMode: 'user-oauth'`
+- "Connect" button initiates OAuth flow
+- Tokens are encrypted and stored
+- "Disconnect" button to revoke access
+
+### Settings Modal Section
+
+The MCP Credentials section appears automatically when servers with user authentication are configured:
+
+```tsx
+// In SettingsModal
+{mcpServers.length > 0 && (
+  <MCPCredentialsSection servers={mcpServers} />
+)}
+```
+
+### API Endpoints
+
+**Get Credential Status:**
+```http
+GET /api/mcp/credentials
+Authorization: Bearer <token>
+```
+
+**Set API Key:**
+```http
+POST /api/mcp/credentials/:serverId/apikey
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "apiKey": "sk-..."
+}
+```
+
+**Start OAuth:**
+```http
+GET /api/mcp/oauth/:serverId/authorize
+Authorization: Bearer <token>
+```
+
+**Remove Credentials:**
+```http
+DELETE /api/mcp/credentials/:serverId
+Authorization: Bearer <token>
+```
+
+## Usage Metrics
+
+The Settings modal displays usage metrics showing the user's message consumption:
+
+### Display
+
+- Progress bar showing messages used vs. limit
+- Numerical display: "X / Y messages used"
+- For unlimited plans: "X messages used (unlimited)"
+
+### API Endpoint
+
+```http
+GET /api/user/usage
+Authorization: Bearer <token>
+```
+
+Response:
+```json
+{
+  "messagesUsed": 15,
+  "messagesLimit": 100,
+  "unlimited": false
+}
+```
+
+## Theme Preference
+
+The user's theme preference is stored separately:
+
+```prisma
+model User {
+  themePreference String?  // 'light' | 'dark' | null (system)
+}
+```
+
+### API
+
+**Get Theme:**
+```http
+GET /api/user/theme
+```
+
+**Update Theme:**
+```http
+PUT /api/user/theme
+Content-Type: application/json
+
+{
+  "theme": "dark"
+}
+```
+
+### Frontend
+
+Use the ThemeContext:
+
+```tsx
+import { useTheme } from '../contexts/ThemeContext';
+
+function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+      Toggle Theme
+    </button>
+  );
+}
+```
+
+## Use Cases
+
+### Developer Context
+
+```typescript
+userSettings: {
+  fields: [
+    {
+      key: 'primaryLanguage',
+      label: 'Primary Language',
+      type: 'select',
+      options: ['JavaScript', 'Python', 'Go', 'Rust', 'Other'],
+    },
+    {
+      key: 'framework',
+      label: 'Preferred Framework',
+      type: 'text',
+      placeholder: 'React, Vue, Django, etc.',
+    },
+    {
+      key: 'codeStyle',
+      label: 'Code Style Preferences',
+      type: 'textarea',
+      placeholder: 'Describe your coding style preferences...',
+    },
+  ],
+}
+```
+
+### Customer Support
+
+```typescript
+userSettings: {
+  fields: [
+    {
+      key: 'accountId',
+      label: 'Account ID',
+      type: 'text',
+    },
+    {
+      key: 'department',
+      label: 'Department',
+      type: 'select',
+      options: ['Sales', 'Engineering', 'Support', 'Finance'],
+    },
+  ],
+}
+```
+
+### Creative Writing
+
+```typescript
+userSettings: {
+  fields: [
+    {
+      key: 'writingStyle',
+      label: 'Preferred Writing Style',
+      type: 'select',
+      options: ['Formal', 'Casual', 'Technical', 'Creative'],
+    },
+    {
+      key: 'targetAudience',
+      label: 'Target Audience',
+      type: 'text',
+      placeholder: 'Who are you writing for?',
+    },
+  ],
+}
+```
+
+## Extending Settings
+
+### Custom Field Types
+
+Add new field types by extending the configuration:
+
+```typescript
+// types/config.ts
+export interface UserSettingsField {
+  key: string;
+  label: string;
+  type: 'text' | 'select' | 'textarea' | 'number' | 'boolean';
+  // ...
+}
+```
+
+### Validation
+
+Add validation using Zod:
+
+```typescript
+// validation/user.ts
+export const settingsSchema = z.object({
+  name: z.string().optional(),
+  role: z.enum(['Developer', 'Designer', 'Manager', 'Other']).optional(),
+  context: z.string().max(1000).optional(),
+});
+```
+
+### Computed Settings
+
+Process settings before sending to AI:
+
+```typescript
+function processUserContext(settings) {
+  return {
+    ...settings,
+    // Add computed fields
+    fullContext: `${settings.name} is a ${settings.role}. ${settings.context}`,
+  };
+}
+```