@cronicorn/mcp-server 1.5.9 → 1.6.1

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

package/dist/docs/developers/workspace-structure.md

@@ -0,0 +1,179 @@
+---
+id: developer-workspace-structure
+title: Workspace Structure
+description: Overview of monorepo workspaces (apps and packages)
+tags:
+  - developer
+  - architecture
+sidebar_position: 3
+mcp:
+  uri: file:///docs/developers/workspace-structure.md
+  mimeType: text/markdown
+  priority: 0.7
+---
+
+# Workspace Structure
+
+Cronicorn is organized as a pnpm monorepo with 8 apps and 13 packages. This guide helps you quickly locate code for specific features.
+
+## Apps (8)
+
+Deployable applications and services.
+
+### `@cronicorn/api`
+HTTP API server using Hono framework with OpenAPI/Swagger support and Better Auth authentication.
+- **Tech**: Hono, Zod, Better Auth, Drizzle ORM
+- **Port**: Configurable via env
+- **Location**: `apps/api/`
+
+### `@cronicorn/web`
+Frontend web application built with React and TanStack Router.
+- **Tech**: React 19, TanStack Router, Vite, Tailwind CSS 4
+- **Dev**: Vite dev server with HMR
+- **Location**: `apps/web/`
+
+### `@cronicorn/scheduler-app`
+Background worker that claims and executes scheduled job endpoints.
+- **Tech**: Pino logging, Drizzle ORM, HTTP dispatcher
+- **Purpose**: Main scheduling loop execution
+- **Location**: `apps/scheduler/`
+
+### `@cronicorn/ai-planner-app`
+AI-powered worker that optimizes scheduling decisions using OpenAI.
+- **Tech**: Vercel AI SDK, OpenAI provider
+- **Purpose**: Adaptive scheduling intelligence
+- **Location**: `apps/ai-planner/`
+
+### `@cronicorn/docs`
+Docusaurus-based documentation website.
+- **Tech**: Docusaurus 3.9.2
+- **Purpose**: Public and developer documentation
+- **Location**: `apps/docs/`
+
+### `@cronicorn/mcp-server`
+Model Context Protocol server enabling AI agents to manage cron jobs.
+- **Tech**: MCP SDK
+- **Published**: Yes (public npm package)
+- **Binary**: `cronicorn-mcp`
+- **Location**: `apps/mcp-server/`
+
+### `@cronicorn/migrator`
+Database migration runner using Drizzle Kit.
+- **Purpose**: Run migrations on startup or manually
+- **Location**: `apps/migrator/`
+
+### `@cronicorn/test-ai`
+Test harness for AI integration experiments.
+- **Purpose**: Development/testing only
+- **Location**: `apps/test-ai/`
+
+---
+
+## Packages (13)
+
+Shared libraries and adapters used by apps.
+
+### Adapters (7)
+
+Implement domain ports using external libraries/services.
+
+#### `@cronicorn/adapter-ai`
+AI SDK integration with mock support (MSW).
+- **Location**: `packages/adapter-ai/`
+
+#### `@cronicorn/adapter-cron`
+Cron expression parsing using cron-parser.
+- **Location**: `packages/adapter-cron/`
+
+#### `@cronicorn/adapter-drizzle`
+PostgreSQL database adapter with Drizzle ORM schema and repositories.
+- **Location**: `packages/adapter-drizzle/`
+
+#### `@cronicorn/adapter-http`
+HTTP request dispatcher for endpoint execution.
+- **Location**: `packages/adapter-http/`
+
+#### `@cronicorn/adapter-pino`
+Structured logging with Pino.
+- **Location**: `packages/adapter-pino/`
+
+#### `@cronicorn/adapter-stripe`
+Stripe payment integration for subscriptions.
+- **Location**: `packages/adapter-stripe/`
+
+#### `@cronicorn/adapter-system-clock`
+System clock implementation for production (vs fake clock for tests).
+- **Location**: `packages/adapter-system-clock/`
+
+### Core Domain (3)
+
+#### `@cronicorn/domain`
+Pure domain logic: ports, entities, policies, governor, scheduler (no external dependencies except Zod).
+- **Location**: `packages/domain/`
+- **Key**: All business rules live here
+
+#### `@cronicorn/services`
+Business logic layer: job management, scheduling services.
+- **Location**: `packages/services/`
+
+#### `@cronicorn/api-contracts`
+OpenAPI contracts and Zod schemas for HTTP API routes (shared between API and Web).
+- **Location**: `packages/api-contracts/`
+
+### Workers (2)
+
+#### `@cronicorn/worker-scheduler`
+Core scheduling worker logic with simulation support.
+- **Script**: `pnpm sim` runs deterministic scenarios
+- **Location**: `packages/worker-scheduler/`
+
+#### `@cronicorn/worker-ai-planner`
+AI planner worker logic (orchestrates AI hints and nudges).
+- **Location**: `packages/worker-ai-planner/`
+
+### UI (1)
+
+#### `@cronicorn/ui-library`
+Shared React component library using shadcn/ui with Radix UI primitives.
+- **Tech**: Tailwind CSS 4, Radix UI, React Hook Form, Recharts
+- **Location**: `packages/ui-library/`
+
+### Content (1)
+
+#### `@cronicorn/content`
+Centralized content: brand assets, pricing, FAQs, SEO metadata, business copy.
+- **Exports**: Multiple subpaths (brand, pricing, docs, seo, etc.)
+- **Location**: `packages/content/`
+
+---
+
+## Other folders
+
+#### `/docs`
+Central docs folder that is used by the docs app and mcp-server
+
+
+## Key Architecture Notes
+
+- **Monorepo**: pnpm workspaces with TypeScript project references
+- **Build**: Packages build with `tsc`, apps use `tsx` (dev) or `tsc` (prod)
+- **Env**: Single `.env` file at root, loaded via `dotenv-cli`
+- **Testing**: Vitest with transaction-per-test pattern
+- **Ports & Adapters**: Clean separation between domain and infrastructure
+
+## Finding Code
+
+| Looking for... | Check... |
+|----------------|----------|
+| API routes | `apps/api/src/routes/` |
+| Database schema | `packages/adapter-drizzle/src/schema/` |
+| Scheduling logic | `packages/domain/src/scheduler.ts` |
+| UI components | `packages/ui-library/src/components/` |
+| AI prompts | `packages/worker-ai-planner/src/` |
+| HTTP dispatcher | `packages/adapter-http/` |
+| Business logic | `packages/services/` |
+
+## Next Steps
+
+- **[System Architecture](../technical/system-architecture.md)** - How components interact at runtime
+- **[Quick Start](./quick-start.md)** - Set up your dev environment