outcome-cli 1.0.0

package/src/config/README.md

@@ -0,0 +1,128 @@
+# Configuration Module
+
+This module provides type-safe environment configuration with validation.
+
+## Overview
+
+The configuration system:
+- Validates all required environment variables on startup
+- Fails fast in production if required API keys are missing
+- Allows missing keys in development for easier local setup
+- Provides type-safe access to configuration values
+
+## Required API Keys (Production)
+
+The following API keys **must** be set for production deployment:
+
+| Key | Description | Get it at |
+|-----|-------------|-----------|
+| `ANTHROPIC_API_KEY` | Anthropic Claude API | https://console.anthropic.com/ |
+| `OPENAI_API_KEY` | OpenAI API | https://platform.openai.com/api-keys |
+| `GOOGLE_API_KEY` | Google Gemini API | https://makersuite.google.com/app/apikey |
+| `TREMENDOUS_API_KEY` | Tremendous (fiat payouts) | https://www.tremendous.com |
+| `CIRCLE_API_KEY` | Circle USDC (crypto payouts) | https://console.circle.com |
+| `CIRCLE_ENTITY_SECRET` | Circle entity secret | Run `npx @circle-fin/usdckit register-entity-secret` |
+| `CIRCLE_TREASURY_ADDRESS` | Treasury wallet address | Run `npx tsx scripts/setup-circle-treasury.ts create` |
+| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL | https://supabase.com/dashboard |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase anon key | https://supabase.com/dashboard |
+| `SUPABASE_SERVICE_ROLE_KEY` | Supabase service role key | https://supabase.com/dashboard |
+
+## Usage
+
+```typescript
+import { getEnvConfig, requireApiKey, hasApiKey, printEnvStatus } from './config';
+
+// Get full config
+const config = getEnvConfig();
+
+// Check if a key is configured
+if (hasApiKey('ANTHROPIC_API_KEY')) {
+  // Use Anthropic
+}
+
+// Get a required key (throws if missing)
+const apiKey = requireApiKey('OPENAI_API_KEY');
+
+// Print status for debugging
+printEnvStatus();
+```
+
+## Local Development
+
+1. Copy `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Fill in the API keys you need for development
+
+3. Missing keys are allowed in development mode
+
+## Cloudflare Workers Deployment
+
+For Cloudflare Workers, use `wrangler secret` to set secrets:
+
+```bash
+# Set secrets for default environment
+wrangler secret put ANTHROPIC_API_KEY
+wrangler secret put OPENAI_API_KEY
+wrangler secret put GOOGLE_API_KEY
+wrangler secret put TREMENDOUS_API_KEY
+wrangler secret put CIRCLE_API_KEY
+wrangler secret put CIRCLE_ENTITY_SECRET
+wrangler secret put SUPABASE_SERVICE_ROLE_KEY
+
+# Set secrets for staging
+wrangler secret put ANTHROPIC_API_KEY --env staging
+# ... repeat for all secrets
+
+# Set secrets for production
+wrangler secret put ANTHROPIC_API_KEY --env production
+# ... repeat for all secrets
+
+# List secrets
+wrangler secret list
+wrangler secret list --env production
+
+# Delete a secret
+wrangler secret delete SECRET_NAME
+```
+
+## Environment Modes
+
+| Mode | Behavior |
+|------|----------|
+| `development` | Missing keys allowed, uses sandbox/testnet |
+| `staging` | Missing keys allowed, uses sandbox/testnet |
+| `production` | All required keys must be set, uses production APIs |
+
+## Payout Provider Modes
+
+Control sandbox/production mode for payout providers:
+
+```bash
+# Sandbox mode (default in development)
+TREMENDOUS_SANDBOX=true
+CIRCLE_TESTNET=true
+
+# Production mode
+TREMENDOUS_SANDBOX=false
+CIRCLE_TESTNET=false
+```
+
+## Validation
+
+The system validates environment variables on startup:
+
+- **Production**: Fails with clear error message listing missing keys
+- **Development**: Logs warnings but continues
+
+Example error in production:
+```
+Environment validation failed in production mode.
+Missing required API keys:
+  - ANTHROPIC_API_KEY
+  - TREMENDOUS_API_KEY
+
+Set these environment variables or use Cloudflare Workers secrets.
+```

package/src/config/env.ts

@@ -0,0 +1,262 @@
+/**
+ * Environment Configuration Module
+ *
+ * Validates and provides type-safe access to environment variables.
+ * Fails fast with clear error messages when required variables are missing.
+ *
+ * Requirements: 9.1, 9.3, 9.4
+ */
+
+import { z } from 'zod';
+
+/**
+ * Schema for required environment variables in production
+ */
+const productionRequiredSchema = z.object({
+  // AI Model Providers
+  ANTHROPIC_API_KEY: z.string().min(1, 'ANTHROPIC_API_KEY is required'),
+  OPENAI_API_KEY: z.string().min(1, 'OPENAI_API_KEY is required'),
+  GOOGLE_API_KEY: z.string().min(1, 'GOOGLE_API_KEY is required'),
+
+  // Payout Providers
+  TREMENDOUS_API_KEY: z.string().min(1, 'TREMENDOUS_API_KEY is required'),
+  CIRCLE_API_KEY: z.string().min(1, 'CIRCLE_API_KEY is required'),
+  CIRCLE_ENTITY_SECRET: z.string().min(1, 'CIRCLE_ENTITY_SECRET is required'),
+
+  // Authentication (Supabase)
+  NEXT_PUBLIC_SUPABASE_URL: z.string().min(1, 'NEXT_PUBLIC_SUPABASE_URL is required'),
+  NEXT_PUBLIC_SUPABASE_ANON_KEY: z.string().min(1, 'NEXT_PUBLIC_SUPABASE_ANON_KEY is required'),
+  SUPABASE_SERVICE_ROLE_KEY: z.string().min(1, 'SUPABASE_SERVICE_ROLE_KEY is required'),
+});
+
+/**
+ * Schema for optional environment variables
+ */
+const optionalSchema = z.object({
+  // Environment mode
+  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
+  ENVIRONMENT: z.enum(['development', 'staging', 'production']).default('development'),
+
+  // Payout provider modes
+  TREMENDOUS_SANDBOX: z.string().transform(v => v === 'true').default('true'),
+  CIRCLE_TESTNET: z.string().transform(v => v === 'true').default('true'),
+
+  // Email (SendGrid)
+  SENDGRID_API_KEY: z.string().optional(),
+  SENDGRID_FROM_EMAIL: z.string().email().optional(),
+  SENDGRID_FROM_NAME: z.string().optional(),
+
+  // Notion Integration
+  NOTION_API_KEY: z.string().optional(),
+  NOTION_BRIEFINGS_DB: z.string().optional(),
+  NOTION_ACTIVITY_DB: z.string().optional(),
+  NOTION_SPONSORS_DB: z.string().optional(),
+  NOTION_TOURNAMENTS_DB: z.string().optional(),
+  NOTION_FEEDBACK_DB: z.string().optional(),
+  NOTION_CONTENT_DB: z.string().optional(),
+
+  // Google Integration
+  GOOGLE_SERVICE_ACCOUNT_PATH: z.string().optional(),
+  GOOGLE_METRICS_SHEET: z.string().optional(),
+  GOOGLE_SPONSORS_SHEET: z.string().optional(),
+  GOOGLE_TOURNAMENTS_SHEET: z.string().optional(),
+  GOOGLE_USERS_SHEET: z.string().optional(),
+  GOOGLE_CONTENT_SHEET: z.string().optional(),
+
+  // Slack Integration
+  SLACK_BOT_TOKEN: z.string().optional(),
+  SLACK_ALERTS_CHANNEL: z.string().optional(),
+  SLACK_BRIEFINGS_CHANNEL: z.string().optional(),
+  SLACK_TOURNAMENTS_CHANNEL: z.string().optional(),
+  SLACK_SPONSORS_CHANNEL: z.string().optional(),
+  SLACK_SUPPORT_CHANNEL: z.string().optional(),
+  SLACK_MARKETING_CHANNEL: z.string().optional(),
+
+  // Discord Bot
+  DISCORD_BOT_TOKEN: z.string().optional(),
+  DISCORD_GUILD_ID: z.string().optional(),
+
+  // Local Models (Ollama)
+  OLLAMA_BASE_URL: z.string().url().default('http://localhost:11434'),
+
+  // Infrastructure
+  MAX_AGENTS_PER_LEAGUE: z.string().transform(Number).default('10'),
+  GLOBAL_SPEND_CEILING: z.string().transform(Number).default('100000'),
+});
+
+/**
+ * Development schema - all required fields are optional
+ */
+const developmentSchema = z.object({
+  ANTHROPIC_API_KEY: z.string().optional(),
+  OPENAI_API_KEY: z.string().optional(),
+  GOOGLE_API_KEY: z.string().optional(),
+  TREMENDOUS_API_KEY: z.string().optional(),
+  CIRCLE_API_KEY: z.string().optional(),
+  CIRCLE_ENTITY_SECRET: z.string().optional(),
+  NEXT_PUBLIC_SUPABASE_URL: z.string().optional(),
+  NEXT_PUBLIC_SUPABASE_ANON_KEY: z.string().optional(),
+  SUPABASE_SERVICE_ROLE_KEY: z.string().optional(),
+}).merge(optionalSchema);
+
+/**
+ * Full environment schema combining required and optional
+ */
+const fullSchema = productionRequiredSchema.merge(optionalSchema);
+
+export type EnvConfig = z.infer<typeof fullSchema>;
+export type DevEnvConfig = z.infer<typeof developmentSchema>;
+
+/**
+ * Validation error with details about missing keys
+ */
+export class EnvValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly missingKeys: string[],
+    public readonly details: z.ZodError
+  ) {
+    super(message);
+    this.name = 'EnvValidationError';
+  }
+}
+
+
+/**
+ * Determines if we're in production mode
+ */
+function isProduction(): boolean {
+  const env = process.env.NODE_ENV || process.env.ENVIRONMENT || 'development';
+  return env === 'production';
+}
+
+/**
+ * Validates environment variables based on current mode.
+ * In production, all required API keys must be set.
+ * In development/staging, missing keys are allowed.
+ *
+ * @throws EnvValidationError if validation fails in production
+ */
+export function validateEnv(): EnvConfig | DevEnvConfig {
+  const isProd = isProduction();
+
+  if (isProd) {
+    const result = fullSchema.safeParse(process.env);
+
+    if (!result.success) {
+      const missingKeys = result.error.issues
+        .filter(issue => issue.code === 'invalid_type' || issue.code === 'too_small')
+        .map(issue => issue.path.join('.'));
+
+      const errorMessage = [
+        'Environment validation failed in production mode.',
+        'Missing required API keys:',
+        ...missingKeys.map(key => `  - ${key}`),
+        '',
+        'Set these environment variables or use Cloudflare Workers secrets.',
+      ].join('\n');
+
+      throw new EnvValidationError(errorMessage, missingKeys, result.error);
+    }
+
+    return result.data;
+  }
+
+  // Development mode - use relaxed schema
+  const result = developmentSchema.safeParse(process.env);
+
+  if (!result.success) {
+    // Log warnings but don't fail in development
+    console.warn('[env] Some environment variables are invalid:', result.error.format());
+  }
+
+  return result.data ?? ({} as DevEnvConfig);
+}
+
+/**
+ * Gets a validated environment configuration.
+ * Caches the result after first validation.
+ */
+let cachedConfig: EnvConfig | DevEnvConfig | null = null;
+
+export function getEnvConfig(): EnvConfig | DevEnvConfig {
+  if (!cachedConfig) {
+    cachedConfig = validateEnv();
+  }
+  return cachedConfig;
+}
+
+/**
+ * Checks if a specific API key is configured
+ */
+export function hasApiKey(key: keyof EnvConfig): boolean {
+  const config = getEnvConfig();
+  const value = config[key as keyof typeof config];
+  return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * Gets an API key, throwing if not configured
+ */
+export function requireApiKey(key: keyof EnvConfig): string {
+  const config = getEnvConfig();
+  const value = config[key as keyof typeof config];
+
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Required API key not configured: ${key}`);
+  }
+
+  return value;
+}
+
+/**
+ * Checks if running in sandbox/testnet mode for payout providers
+ */
+export function isPayoutSandbox(): boolean {
+  const config = getEnvConfig();
+  return config.TREMENDOUS_SANDBOX === true || config.CIRCLE_TESTNET === true;
+}
+
+/**
+ * Gets the current environment mode
+ */
+export function getEnvironment(): 'development' | 'staging' | 'production' {
+  const config = getEnvConfig();
+  return config.ENVIRONMENT || config.NODE_ENV || 'development';
+}
+
+/**
+ * Lists all required API keys for production
+ */
+export const REQUIRED_API_KEYS = [
+  'ANTHROPIC_API_KEY',
+  'OPENAI_API_KEY',
+  'GOOGLE_API_KEY',
+  'TREMENDOUS_API_KEY',
+  'CIRCLE_API_KEY',
+  'CIRCLE_ENTITY_SECRET',
+  'NEXT_PUBLIC_SUPABASE_URL',
+  'NEXT_PUBLIC_SUPABASE_ANON_KEY',
+  'SUPABASE_SERVICE_ROLE_KEY',
+] as const;
+
+/**
+ * Prints environment status (for debugging)
+ */
+export function printEnvStatus(): void {
+  // Ensure config is loaded
+  getEnvConfig();
+  const env = getEnvironment();
+
+  console.log(`\n[env] Environment: ${env}`);
+  console.log('[env] API Key Status:');
+
+  for (const key of REQUIRED_API_KEYS) {
+    const keyConfigured = hasApiKey(key);
+    const status = keyConfigured ? '✓' : '✗';
+    console.log(`  ${status} ${key}`);
+  }
+
+  console.log(`[env] Payout Mode: ${isPayoutSandbox() ? 'Sandbox/Testnet' : 'Production'}`);
+  console.log('');
+}

package/src/config/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Configuration Module
+ *
+ * Exports environment configuration utilities.
+ */
+
+export {
+  validateEnv,
+  getEnvConfig,
+  hasApiKey,
+  requireApiKey,
+  isPayoutSandbox,
+  getEnvironment,
+  printEnvStatus,
+  REQUIRED_API_KEYS,
+  EnvValidationError,
+  type EnvConfig,
+  type DevEnvConfig,
+} from './env.js';