@cronicorn/mcp-server 1.5.8 → 1.6.0

package/dist/docs/developers/README.md

@@ -0,0 +1,29 @@
+---
+id: developers-overview
+title: Developer Overview
+description: Documentation for developers contributing to Cronicorn
+tags:
+  - developer
+sidebar_position: 0
+mcp:
+  uri: file:///docs/developers/overview.md
+---
+
+# Developer Documentation
+
+Documentation for developers contributing to Cronicorn's codebase or building AI agents that interact with Cronicorn.
+
+## Getting Started
+
+- **[Quick Start](./quick-start.md)** - Set up your development environment in 4 steps
+- **[Authentication](./authentication.md)** - Configure admin user or GitHub OAuth
+- **[Workspace Structure](./workspace-structure.md)** - Monorepo organization (apps and packages)
+- **[Quality Checks](./quality-checks.md)** - Required checks before committing and merging
+
+## Architecture & Design
+
+- **[System Architecture](../technical/system-architecture.md)** - Core concepts and design patterns
+
+## Contributing
+
+For contributors working on Cronicorn's codebase, additional technical guidelines are available in the repository's `.github/instructions/` directory.

package/dist/docs/developers/authentication.md

@@ -0,0 +1,177 @@
+---
+id: developer-authentication
+title: Authentication Configuration
+description: Configure authentication methods for your Cronicorn deployment
+tags:
+  - developer
+  - configuration
+sidebar_position: 2
+mcp:
+  uri: file:///docs/developers/authentication.md
+  mimeType: text/markdown
+  priority: 0.8
+---
+
+# Authentication Configuration
+
+Cronicorn supports two authentication methods. At least one must be enabled.
+
+## Quick Reference
+
+```bash
+# Admin User (local dev, CI/CD)
+ADMIN_USER_EMAIL=admin@example.com
+ADMIN_USER_PASSWORD=your-secure-password-min-8-chars
+
+# GitHub OAuth (production)
+GITHUB_CLIENT_ID=your_github_client_id
+GITHUB_CLIENT_SECRET=your_github_client_secret
+```
+
+**Choose based on your use case:**
+- **Local Dev**: Admin user only (no OAuth setup needed)
+- **Production**: GitHub OAuth (for multiple users)
+- **Hybrid**: Both (admins use email, users use GitHub)
+
+## Admin User Setup
+
+Perfect for development and self-hosting.
+
+**1. Edit `.env`:**
+```bash
+ADMIN_USER_EMAIL=admin@example.com
+ADMIN_USER_PASSWORD=your-secure-password
+ADMIN_USER_NAME=Admin  # Optional
+```
+
+**2. Restart the app** - admin user auto-created on startup
+
+**3. Login** at `http://localhost:5173/login` with your email/password
+
+**Benefits**: ✅ No OAuth app needed, ✅ Works offline, ✅ Perfect for CI/CD
+
+## GitHub OAuth Setup
+
+Best for production with multiple users.
+
+**1. [Create GitHub OAuth app](https://github.com/settings/developers)**
+
+**2. Set callback URL:**
+```
+${BETTER_AUTH_URL}/api/auth/callback/github
+```
+Example: `http://localhost:3333/api/auth/callback/github`
+
+**3. Add to `.env`:**
+```bash
+GITHUB_CLIENT_ID=your_client_id
+GITHUB_CLIENT_SECRET=your_client_secret
+```
+
+**4. Login** - click "Sign in with GitHub" button
+
+## Validation Rules
+
+**At least one method required.** App validates on startup:
+
+| Configuration | Status |
+|---------------|--------|
+| Admin user only | ✅ Works |
+| GitHub OAuth only | ✅ Works |
+| Both enabled | ✅ Works |
+| Neither enabled | ❌ Fails |
+
+## Required Environment Variables
+
+### Base Config (Always Required)
+
+```bash
+DATABASE_URL=postgresql://user:password@localhost:6666/db
+BETTER_AUTH_SECRET=$(openssl rand -base64 32)
+BETTER_AUTH_URL=http://localhost:3333
+WEB_URL=http://localhost:5173
+```
+
+### Admin User (Optional*)
+
+| Variable | Description |
+|----------|-------------|
+| `ADMIN_USER_EMAIL` | Valid email address |
+| `ADMIN_USER_PASSWORD` | Minimum 8 characters |
+| `ADMIN_USER_NAME` | Display name (optional) |
+
+*Required if GitHub OAuth not configured
+
+### GitHub OAuth (Optional*)
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_CLIENT_ID` | From GitHub OAuth app |
+| `GITHUB_CLIENT_SECRET` | From GitHub OAuth app |
+
+*Required if admin user not configured
+
+## Common Issues
+
+### Admin user not created
+
+1. Check both `ADMIN_USER_EMAIL` and `ADMIN_USER_PASSWORD` are in `.env`
+2. Restart the application
+3. Check logs for "Admin user created successfully"
+
+### Login returns 404
+
+1. Restart API server after changing `.env`
+2. Verify: `curl http://localhost:3333/api/auth/config`
+
+### Wrong credentials
+
+1. Check email/password match `.env` exactly (case-sensitive)
+2. Password must be at least 8 characters
+3. Remove any extra whitespace
+
+## Production Configuration
+
+**Admin for emergency access:**
+```bash
+ADMIN_USER_EMAIL=admin@yourdomain.com
+ADMIN_USER_PASSWORD=${SECRET_FROM_VAULT}
+```
+
+**GitHub for regular users:**
+```bash
+GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
+GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
+BETTER_AUTH_URL=https://api.yourdomain.com
+WEB_URL=https://yourdomain.com
+```
+
+**Security**: Use secrets manager, not plain `.env` files
+
+## Programmatic Access
+
+### Bearer Tokens (CLI/AI Agents)
+
+```bash
+# 1. Initiate device flow
+curl -X POST http://localhost:3333/api/auth/device/code
+
+# 2. User authorizes in browser
+
+# 3. Poll for token
+curl -X POST http://localhost:3333/api/auth/device/token \
+  -d "device_code=DEVICE_CODE"
+
+# 4. Use in API requests
+curl -H "Authorization: Bearer TOKEN" \
+  http://localhost:3333/api/jobs
+```
+
+### API Keys
+
+Generate in web UI at `/settings/api-keys`:
+
+```bash
+curl -H "X-API-Key: your-api-key" \
+  http://localhost:3333/api/jobs
+```

package/dist/docs/developers/environment-configuration.md

@@ -0,0 +1,197 @@
+---
+id: environment-configuration
+title: Environment Configuration
+description: Understanding Cronicorn's zero-config approach and environment variables
+tags:
+  - developer
+  - configuration
+  - setup
+sidebar_position: 2
+---
+
+# Environment Configuration
+
+## Zero-Config Local Development
+
+Cronicorn is designed for **zero-configuration local development**. All environment variables have sensible defaults, so you can run the entire stack without creating a `.env` file.
+
+```bash
+# That's it - no .env file needed!
+pnpm install
+pnpm db
+pnpm db:migrate
+pnpm dev
+```
+
+Login at http://localhost:5173 with:
+- Email: `admin@example.com`
+- Password: `devpassword`
+
+## How It Works
+
+### Centralized Defaults
+
+All default values are maintained in a single package: `@cronicorn/config-defaults`
+
+This ensures:
+- **Consistency** - Same defaults across all apps (API, scheduler, ai-planner, web)
+- **Maintainability** - One place to update defaults
+- **Type safety** - TypeScript constants prevent typos
+- **Security** - Production validation prevents using dev defaults
+
+### Development Defaults
+
+| Category | Variable | Default Value |
+|----------|----------|---------------|
+| **Ports** | API_PORT | 3333 |
+| | WEB_PORT | 5173 |
+| | DB_PORT | 6666 |
+| **Database** | DATABASE_URL | postgresql://user:password@localhost:6666/db |
+| **Auth** | ADMIN_USER_EMAIL | admin@example.com |
+| | ADMIN_USER_PASSWORD | devpassword |
+| | BETTER_AUTH_SECRET | dev-secret-DO-NOT-USE-IN-PRODUCTION-min32chars |
+| **URLs** | BETTER_AUTH_URL | http://localhost:3333 |
+| | WEB_URL | http://localhost:5173 |
+| | API_URL | http://localhost:3333 |
+| **Stripe** | STRIPE_SECRET_KEY | sk_test_dummy_key_for_local_dev_only |
+| | STRIPE_WEBHOOK_SECRET | whsec_test_dummy_secret_for_local_dev |
+
+⚠️ **Security Warning**: These are insecure defaults for local development only. Production deployments MUST override these values.
+
+## Customizing Configuration
+
+
+### Full Configuration (.env.example)
+
+For production or advanced setup:
+
+```bash
+# Copy the full example
+cp .env.example .env
+
+# Edit with your production values
+vim .env
+```
+
+See all available variables with descriptions in `.env.example`.
+
+## Production Deployment
+
+### Required Changes
+
+Production deployments MUST set these variables:
+
+```bash
+# 1. Secure auth secret (generate with: openssl rand -base64 32)
+BETTER_AUTH_SECRET=your-secure-random-secret-min-32-chars
+
+# 2. Choose authentication method:
+# Option A: Admin User
+ADMIN_USER_EMAIL=admin@yourcompany.com
+ADMIN_USER_PASSWORD=strong-unique-password
+
+# Option B: GitHub OAuth
+GITHUB_CLIENT_ID=your_github_client_id
+GITHUB_CLIENT_SECRET=your_github_client_secret
+
+# 3. Real Stripe keys (if using payments)
+STRIPE_SECRET_KEY=sk_live_your_production_key
+STRIPE_WEBHOOK_SECRET=whsec_your_production_webhook_secret
+STRIPE_PRICE_PRO=price_live_pro_monthly
+STRIPE_PRICE_ENTERPRISE=price_live_enterprise_monthly
+
+# 4. Production URLs
+BASE_URL=https://your-production-domain.com
+WEB_URL=https://your-production-domain.com
+API_URL=https://api.your-production-domain.com
+BETTER_AUTH_URL=https://api.your-production-domain.com
+```
+
+### Production Validation
+
+The application automatically validates that dev defaults are not used in production:
+
+```typescript
+// Automatically runs on startup in production
+if (NODE_ENV === "production") {
+  // Checks BETTER_AUTH_SECRET, ADMIN_USER_PASSWORD, STRIPE_SECRET_KEY
+  // Exits with error if using dev defaults
+}
+```
+
+## Configuration Architecture
+
+### Per-App Config Files
+
+Each app has its own configuration file that imports shared defaults:
+
+```
+apps/
+  api/src/lib/config.ts          # API server config
+  scheduler/src/index.ts          # Scheduler worker config  
+  ai-planner/src/index.ts         # AI planner config
+  web/src/config.ts               # Web app config
+```
+
+### Shared Defaults Package
+
+```
+packages/
+  config-defaults/
+    src/index.ts                  # Single source of truth
+    README.md                     # Usage documentation
+```
+
+## Best Practices
+
+### Local Development
+- ✅ Use defaults (empty .env or .env.minimal)
+- ✅ Override only what you need to test
+- ✅ Keep .env out of git (already in .gitignore)
+
+### Production
+- ✅ Set all required variables explicitly
+- ✅ Use secure secrets (never dev defaults)
+- ✅ Validate with `NODE_ENV=production` locally first
+- ✅ Use environment-specific .env files (.env.production, .env.staging)
+
+### Team Development
+- ✅ Document custom local overrides in team wiki (not in .env)
+- ✅ Keep .env.example up to date
+- ✅ Use the same default ports to avoid conflicts
+- ✅ Update shared defaults in config-defaults package only
+
+## Troubleshooting
+
+### "Cannot find module @cronicorn/config-defaults"
+
+Run `pnpm build:packages` to build the shared config package:
+
+```bash
+pnpm build:packages
+```
+
+### "Environment variable validation failed"
+
+Check the error message for which variable is invalid:
+
+```bash
+# See current environment
+pnpm exec dotenv -e .env -- env | grep -E "(DATABASE_URL|STRIPE|ADMIN|GITHUB)"
+```
+
+### "Auth not working in production"
+
+Ensure you've overridden the dev defaults:
+
+```bash
+# Never use these in production:
+ADMIN_USER_PASSWORD=devpassword  # ❌
+BETTER_AUTH_SECRET=dev-secret-DO-NOT-USE-IN-PRODUCTION-min32chars  # ❌
+```
+
+## Related
+
+- **[Quick Start](./quick-start.md)** - Get started with development
+- **[Quality Checks](./quality-checks.md)** - Testing and validation
+- **[Workspace Structure](./workspace-structure.md)** - Project organization

package/dist/docs/developers/quality-checks.md

@@ -0,0 +1,68 @@
+---
+id: developer-quality-checks
+title: Quality Checks
+description: Required quality checks before committing and merging code
+tags:
+  - developer
+  - quality
+  - testing
+sidebar_position: 4
+mcp:
+  uri: file:///docs/developers/quality-checks.md
+  mimeType: text/markdown
+  priority: 0.75
+---
+
+# Quality Checks
+
+## Before Commit
+
+```bash
+pnpm test              # Unit & integration tests (excludes e2e)
+pnpm lint              # Check for errors
+pnpm build:packages    # Ensure types compile
+```
+
+## Before Merge
+
+```bash
+pnpm test              # Full test suite (excludes e2e)
+pnpm lint:fix          # Fix and verify (zero warnings)
+pnpm build             # Full build
+pnpm test:e2e          # E2E tests (separate command)
+```
+
+## What to Test
+
+| Change | Test Type |
+|--------|-----------|
+| Domain logic | Unit tests (mocked ports) |
+| Repositories | Integration tests (transaction-per-test) |
+| API routes | API + integration tests |
+| Bug fixes | Regression test |
+
+**Coverage**: 80%+ for managers/services
+
+## Common Fixes
+
+**Tests fail**: `pnpm db` (ensure database running)  
+**Module errors**: `pnpm build:packages`  
+**Lint errors**: `pnpm lint:fix` (auto-fix most issues)
+
+## Checklist
+
+**Before Commit**
+- [ ] Tests pass for changed packages
+- [ ] No lint errors
+- [ ] Packages build
+
+**Before Merge**
+- [ ] Full test suite passes
+- [ ] Full build succeeds  
+- [ ] Zero lint warnings
+- [ ] E2E tests pass (if applicable)
+- [ ] ADR created (if architectural decision)
+
+## Related
+
+- **[Quick Start](./quick-start.md)** - Dev environment setup

package/dist/docs/developers/quick-start.md

@@ -0,0 +1,84 @@
+---
+id: developer-quick-start
+title: Developer Quick Start
+description: Set up your Cronicorn development environment in 4 steps
+tags:
+  - developer
+  - essential
+sidebar_position: 1
+mcp:
+  uri: file:///docs/developers/quick-start.md
+  mimeType: text/markdown
+  priority: 0.9
+---
+
+# Developer Quick Start
+
+Get Cronicorn running locally in 4 steps.
+
+## Prerequisites
+
+- Node.js 24+ and pnpm 10+
+- Docker (for PostgreSQL)
+
+## Setup
+
+```bash
+# 1. Clone and install
+git clone https://github.com/weskerllc/cronicorn.git
+cd cronicorn
+pnpm install  # Auto-builds packages
+
+# 2. Configure authentication (optional - use defaults)
+cp .env.example .env
+# Edit .env and uncomment ADMIN_USER_EMAIL and ADMIN_USER_PASSWORD
+# Or leave as-is to use GitHub OAuth (requires setup)
+
+# 3. Start database
+pnpm db
+
+# 4. Run migrations
+pnpm db:migrate
+
+# 5. Start development
+pnpm dev
+```
+
+**Login**: Open http://localhost:5173
+
+- **Admin User**: Use email/password from your `.env` file
+- **GitHub OAuth**: Click "Sign in with GitHub" (if configured)
+
+> 💡 **Tip**: For local dev, uncomment the admin user credentials in `.env` for instant login without OAuth setup.
+
+> ⚠️ You'll see a warning about `OPENAI_API_KEY` - this is normal. AI features are optional.
+
+## Common Commands
+
+| Command | Description |
+|---------|-------------|
+| `pnpm dev` | Start all services |
+| `pnpm dev:api` | API server only |
+| `pnpm dev:web` | Web app only |
+| `pnpm db` | Start PostgreSQL |
+| `pnpm db:migrate` | Run migrations |
+| `pnpm db:reset` | Reset db |
+| `pnpm db:generate` | Generate migrations when you make schema changes |
+| `pnpm studio` | Database Browser |
+| `pnpm build` | Production build |
+
+## Troubleshooting
+
+**Can't login?**  
+→ Check `.env` has either admin user credentials uncommented OR GitHub OAuth configured
+
+**Module errors?**  
+→ `pnpm build:packages`
+
+**Database errors?**  
+→ Ensure Docker is running, then `pnpm db`
+
+## Next Steps
+
+-  [Authentication](./authentication.md) - Configure authentication methods
+-  [Architecture](../technical/system-architecture.md) - System design