@taskforcehq/taskforce 0.3.168

package/dist/config/envSchema.js

@@ -0,0 +1,374 @@
+const SPECS = [
+    { key: 'PORT', description: 'Standalone server port.', category: 'Core', defaultValue: '8080', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_TENANT_ID', description: 'Tenant identifier.', category: 'Core', defaultValue: 'default', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_WORKSPACE_ID', description: 'Optional explicit workspace scope for MCP/server tooling.', category: 'Core', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_RUNTIME_MODE', description: 'Runtime mode (local|cloud).', category: 'Core', defaultValue: 'local', example: 'cloud', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_DB_PROVIDER', description: 'Database provider (sqlite|postgres).', category: 'Core', defaultValue: 'sqlite', example: 'postgres', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_BILLING_ENABLED', description: 'Enable Stripe billing routes and webhook processing.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_DATABASE_URL', description: 'Postgres connection string when provider=postgres.', category: 'Core', example: 'postgresql://user:pass@host:5432/db', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_ALLOW_SQLITE_IN_CLOUD', description: 'Emergency override to allow sqlite in cloud runtime.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_FORCE_SETUP', description: 'Force local setup gate for development.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_FORCE_GLOBAL_SETUP', description: 'Force global setup step for development.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_FORCE_WORKSPACE_SETUP', description: 'Force workspace setup step for development.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_GIT_BACKUP', description: 'Enable git backup persistence behavior in local tooling.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_REALTIME_SYNC', description: 'Enable realtime sync transport layer (feature-flag).', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_ENABLED', description: 'Enable auth endpoints and session checks.', category: 'Auth', defaultValue: 'true', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_REQUIRED_FOR_API', description: 'Require auth for protected API routes.', category: 'Auth', defaultValue: 'true', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_EXCLUDED_PATHS', description: 'Comma-separated API paths excluded from auth checks.', category: 'Auth', defaultValue: '/api/taskforce/health,/api/taskforce/version,/api/taskforce/auth', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_DEFAULT_ROLE', description: 'Default role for unauthenticated context (owner|admin|member|read-only).', category: 'Auth', defaultValue: 'member', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_SESSION_COOKIE', description: 'Session cookie name.', category: 'Auth', defaultValue: 'taskforce_session', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_SESSION_SECRET', description: 'Session signing secret.', category: 'Auth', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_SESSION_TTL_SECONDS', description: 'Session max age in seconds.', category: 'Auth', defaultValue: '2592000', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_SESSION_SAMESITE', description: 'SameSite policy (Lax|Strict|None).', category: 'Auth', defaultValue: 'None', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_SESSION_DOMAIN', description: 'Optional cookie domain.', category: 'Auth', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_BOOTSTRAP_ADMIN_EMAIL', description: 'Bootstrap admin email used by login fallback.', category: 'Auth', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_BOOTSTRAP_ADMIN_PASSWORD', description: 'Bootstrap admin password used by login fallback.', category: 'Auth', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_PUBLIC_BASE_URL', description: 'Public auth URL used in email links.', category: 'Auth', example: 'https://performance-app.taskforcehq.ai', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_EXPOSE_DEV_TOKENS', description: 'Expose dev auth tokens in responses.', category: 'Auth', defaultValue: 'false', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_CLOUD_PROXY_BASE_URL', description: 'Optional upstream cloud base URL for local proxying of auth/sync API calls.', category: 'Auth', example: 'https://performance-app.taskforcehq.ai', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_CF_ACCESS_CLIENT_ID', description: 'Optional Cloudflare Access service token client id for local cloud proxy.', category: 'Cloudflare', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_CF_ACCESS_CLIENT_SECRET', description: 'Optional Cloudflare Access service token client secret for local cloud proxy.', category: 'Cloudflare', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_OBJECT_STORAGE_PROVIDER', description: 'Object storage provider (local|r2).', category: 'Storage', defaultValue: 'local', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_STORAGE_PROVIDER', description: 'Legacy alias for object storage provider.', category: 'Storage', targets: ['server', 'all'] },
+    { key: 'R2_ACCOUNT_ID', description: 'Cloudflare R2 account ID.', category: 'Storage', secret: true, targets: ['server', 'all'] },
+    { key: 'R2_BUCKET', description: 'Cloudflare R2 bucket name.', category: 'Storage', targets: ['server', 'all'] },
+    { key: 'R2_ACCESS_KEY_ID', description: 'R2 access key ID.', category: 'Storage', secret: true, targets: ['server', 'all'] },
+    { key: 'R2_SECRET_ACCESS_KEY', description: 'R2 secret access key.', category: 'Storage', secret: true, targets: ['server', 'all'] },
+    { key: 'R2_ENDPOINT', description: 'Optional R2 endpoint override.', category: 'Storage', targets: ['server', 'all'] },
+    { key: 'R2_KEY_PREFIX', description: 'R2 key prefix.', category: 'Storage', defaultValue: 'taskforce', targets: ['server', 'all'] },
+    { key: 'R2_SIGNED_UPLOAD_TTL_SECONDS', description: 'Upload signed URL TTL.', category: 'Storage', defaultValue: '600', targets: ['server', 'all'] },
+    { key: 'R2_SIGNED_DOWNLOAD_TTL_SECONDS', description: 'Download signed URL TTL.', category: 'Storage', defaultValue: '300', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_VIRUS_SCAN_PROVIDER', description: 'Virus scanner provider (none|clamav).', category: 'Security', defaultValue: 'none', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_VIRUS_SCAN_FAIL_CLOSED', description: 'Fail uploads closed on scan failures.', category: 'Security', defaultValue: 'false', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_VIRUS_SCAN_TIMEOUT_MS', description: 'Virus scan timeout in ms.', category: 'Security', defaultValue: '15000', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_VIRUS_SCAN_ASYNC', description: 'Run scan asynchronously when supported.', category: 'Security', defaultValue: 'true', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_CLAMAV_HOST', description: 'ClamAV host.', category: 'Security', defaultValue: '127.0.0.1', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_CLAMAV_PORT', description: 'ClamAV port.', category: 'Security', defaultValue: '3310', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_EMAIL_PROVIDER', description: 'Email provider (console|resend|google-workspace).', category: 'Email', defaultValue: 'console', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_EMAIL_FROM', description: 'Email from address.', category: 'Email', defaultValue: 'Taskforce <no-reply@taskforcehq.ai>', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_EMAIL_REPLY_TO', description: 'Optional reply-to address.', category: 'Email', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_EMAIL_PROVIDER_API_KEY', description: 'Provider API key.', category: 'Email', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_EMAIL_RESEND_API_KEY', description: 'Legacy resend API key alias.', category: 'Email', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_EMAIL_GOOGLE_APP_PASSWORD', description: 'Google Workspace app password alias.', category: 'Email', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_ALLOWED_ORIGINS', description: 'Allowed CORS origins (comma-separated).', category: 'Security', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_API_RATE_LIMIT_ENABLED', description: 'Enable API rate limiter.', category: 'Security', defaultValue: 'true', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_API_RATE_LIMIT_MAX_REQUESTS', description: 'API rate limit max requests per window.', category: 'Security', defaultValue: '120', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_API_RATE_LIMIT_WINDOW_MS', description: 'API rate limit window size in ms.', category: 'Security', defaultValue: '60000', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_STRIPE_WEBHOOK_RATE_LIMIT_MAX_REQUESTS', description: 'Stripe webhook-specific rate limit max requests per window.', category: 'Security', defaultValue: '600', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_STRIPE_WEBHOOK_RATE_LIMIT_WINDOW_MS', description: 'Stripe webhook-specific rate limit window size in ms.', category: 'Security', defaultValue: '60000', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_MAX_PAYLOAD_BYTES', description: 'Maximum accepted API payload size in bytes.', category: 'Security', defaultValue: '1048576', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_DOCUMENT_RETENTION_DAYS', description: 'Document retention period.', category: 'Security', defaultValue: '7', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_DOCUMENT_PURGE_ENABLED', description: 'Enable document purge scheduler.', category: 'Security', defaultValue: 'true', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_DOCUMENT_PURGE_INTERVAL_MINUTES', description: 'Document purge interval in minutes.', category: 'Security', defaultValue: '15', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_STORAGE_INTEGRITY_SCHEDULE_POLL_MINUTES', description: 'Storage integrity schedule poll frequency in minutes.', category: 'Security', defaultValue: '1', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_SYNC_KEY', description: 'Optional sync encryption key.', category: 'Security', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_STRIPE_SECRET_KEY', description: 'Stripe secret API key used by server-side billing routes.', category: 'Security', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_STRIPE_WEBHOOK_SECRET', description: 'Stripe webhook signing secret used to verify incoming webhooks.', category: 'Security', secret: true, targets: ['server', 'all'] },
+    { key: 'TASKFORCE_BUILD_VERSION', description: 'Build version metadata.', category: 'Build', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_BUILD_GIT_SHA', description: 'Build git SHA metadata.', category: 'Build', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_BUILD_TIME', description: 'Build timestamp metadata.', category: 'Build', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_BUILD_DEPLOY_ID', description: 'Build deploy ID metadata.', category: 'Build', targets: ['server', 'all'] },
+    { key: 'VITE_TASKFORCE_BASE_URL', description: 'Client base URL for both API and cloud auth when specific overrides are not set.', category: 'Client', example: 'https://performance-app.taskforcehq.ai', targets: ['all'] },
+    { key: 'VITE_TASKFORCE_API_BASE_URL', description: 'Client API base URL (overrides VITE_TASKFORCE_BASE_URL when set).', category: 'Client', example: 'https://performance-app.taskforcehq.ai', targets: ['all'] },
+    { key: 'VITE_TASKFORCE_CLOUD_AUTH_BASE_URL', description: 'Client cloud auth base URL.', category: 'Client', example: 'https://performance-app.taskforcehq.ai', targets: ['all'] },
+    { key: 'VITE_TASKFORCE_WS_BASE_URL', description: 'Client websocket base URL override.', category: 'Client', example: 'wss://performance-app.taskforcehq.ai', targets: ['all'] },
+    { key: 'SYNC_SOAK_LOCAL_BASE_URL', description: 'Soak local app URL.', category: 'Soak', defaultValue: 'http://localhost:5174', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_CLOUD_BASE_URL', description: 'Soak cloud app URL.', category: 'Soak', example: 'https://performance-app.taskforcehq.ai', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_WORKSPACE_ID', description: 'Base soak workspace ID.', category: 'Soak', defaultValue: 'test-smoke', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_EMAIL', description: 'Primary soak account email fallback.', category: 'Soak', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_PASSWORD', description: 'Primary soak account password fallback.', category: 'Soak', secret: true, targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_ACCOUNTS_JSON', description: 'JSON account pool for soak login rotation.', category: 'Soak', secret: true, example: '[{"email":"test_01@taskforcehq.ai","password":"..."}]', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_ACCOUNT_WORKSPACES_JSON', description: 'Optional explicit account->workspace map.', category: 'Soak', example: '{"test_01@taskforcehq.ai":"test-smoke-test-01"}', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_PROFILE', description: 'Soak profile (smoke|stress|overnight).', category: 'Soak', defaultValue: 'smoke', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_DURATION_MIN', description: 'Soak duration in minutes.', category: 'Soak', defaultValue: '60', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_SEED', description: 'Deterministic soak seed.', category: 'Soak', example: '4242', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_ARTIFACT_DIR', description: 'Soak artifacts output directory.', category: 'Soak', defaultValue: '.taskforce/soak-artifacts', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_ENABLE_SYNC_DEBUG', description: 'Enable sync debug diagnostics during soak.', category: 'Soak', defaultValue: 'false', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_STRESS_ACTIONS', description: 'Stress action count.', category: 'Soak', defaultValue: '150', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_STRESS_CHECKPOINT_INTERVAL', description: 'Stress checkpoint interval.', category: 'Soak', defaultValue: '50', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_STRESS_SETTLE_RETRIES', description: 'Stress settle retry count.', category: 'Soak', defaultValue: '3', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_STRESS_SETTLE_WAIT_MS', description: 'Stress settle wait time in ms.', category: 'Soak', defaultValue: '500', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_STRESS_HARD_RESET_SETTLE', description: 'Enable hard reset settle path in stress.', category: 'Soak', defaultValue: 'true', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_OVERNIGHT_ACTION_INTERVAL_MS', description: 'Overnight action pacing interval in ms.', category: 'Soak', defaultValue: '60000', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_OVERNIGHT_CHECKPOINT_MIN', description: 'Overnight checkpoint interval in minutes.', category: 'Soak', defaultValue: '15', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_OVERNIGHT_MAX_ACTIONS', description: 'Overnight hard cap on action count.', category: 'Soak', defaultValue: '10000', targets: ['soak', 'all'] },
+    { key: 'SYNC_SOAK_OVERNIGHT_MIN_ACTIONS', description: 'Overnight minimum actions expected before pass.', category: 'Soak', defaultValue: '80', targets: ['soak', 'all'] },
+    { key: 'CF_ACCESS_CLIENT_ID', description: 'Cloudflare Access service token client id (soak).', category: 'Cloudflare', secret: true, targets: ['soak', 'all'] },
+    { key: 'CF_ACCESS_CLIENT_SECRET', description: 'Cloudflare Access service token client secret (soak).', category: 'Cloudflare', secret: true, targets: ['soak', 'all'] }
+];
+const SPEC_BY_KEY = new Map(SPECS.map((spec) => [spec.key, spec]));
+const MANAGED_PREFIXES = ['TASKFORCE_', 'SYNC_SOAK_', 'VITE_TASKFORCE_', 'R2_', 'CF_ACCESS_'];
+const ADDITIONAL_MANAGED_KEYS = new Set(['PORT']);
+function hasValue(env, key) {
+    return String(env[key] || '').trim().length > 0;
+}
+function parseBoolean(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (!normalized)
+        return null;
+    if (['1', 'true', 'yes', 'on'].includes(normalized))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(normalized))
+        return false;
+    return null;
+}
+function parsePositiveInt(value) {
+    if (!String(value || '').trim())
+        return null;
+    const parsed = Number.parseInt(String(value), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return null;
+    return parsed;
+}
+function isHttpUrl(value) {
+    const raw = String(value || '').trim();
+    if (!raw)
+        return false;
+    try {
+        const parsed = new URL(raw);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function isManagedKey(key) {
+    if (ADDITIONAL_MANAGED_KEYS.has(key))
+        return true;
+    return MANAGED_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+function validateCommonNumbers(env, errors) {
+    const numericKeys = [
+        'PORT',
+        'TASKFORCE_API_RATE_LIMIT_MAX_REQUESTS',
+        'TASKFORCE_API_RATE_LIMIT_WINDOW_MS',
+        'TASKFORCE_STRIPE_WEBHOOK_RATE_LIMIT_MAX_REQUESTS',
+        'TASKFORCE_STRIPE_WEBHOOK_RATE_LIMIT_WINDOW_MS',
+        'TASKFORCE_MAX_PAYLOAD_BYTES',
+        'TASKFORCE_DOCUMENT_RETENTION_DAYS',
+        'TASKFORCE_DOCUMENT_PURGE_INTERVAL_MINUTES',
+        'TASKFORCE_STORAGE_INTEGRITY_SCHEDULE_POLL_MINUTES',
+        'TASKFORCE_AUTH_SESSION_TTL_SECONDS',
+        'TASKFORCE_VIRUS_SCAN_TIMEOUT_MS',
+        'TASKFORCE_CLAMAV_PORT',
+        'R2_SIGNED_UPLOAD_TTL_SECONDS',
+        'R2_SIGNED_DOWNLOAD_TTL_SECONDS',
+        'SYNC_SOAK_DURATION_MIN',
+        'SYNC_SOAK_STRESS_ACTIONS',
+        'SYNC_SOAK_STRESS_CHECKPOINT_INTERVAL',
+        'SYNC_SOAK_STRESS_SETTLE_RETRIES',
+        'SYNC_SOAK_STRESS_SETTLE_WAIT_MS',
+        'SYNC_SOAK_OVERNIGHT_ACTION_INTERVAL_MS',
+        'SYNC_SOAK_OVERNIGHT_CHECKPOINT_MIN',
+        'SYNC_SOAK_OVERNIGHT_MAX_ACTIONS',
+        'SYNC_SOAK_OVERNIGHT_MIN_ACTIONS'
+    ];
+    for (const key of numericKeys) {
+        const raw = env[key];
+        if (!String(raw || '').trim())
+            continue;
+        if (parsePositiveInt(raw) === null) {
+            errors.push(`${key} must be a positive integer.`);
+        }
+    }
+}
+function validateServerEnv(env, errors) {
+    const providerRaw = String(env.TASKFORCE_DB_PROVIDER || 'sqlite').trim().toLowerCase();
+    const provider = providerRaw === 'postgres' ? 'postgres' : 'sqlite';
+    if (!['sqlite', 'postgres'].includes(providerRaw) && providerRaw !== '') {
+        errors.push('TASKFORCE_DB_PROVIDER must be one of: sqlite, postgres.');
+    }
+    const runtimeRaw = String(env.TASKFORCE_RUNTIME_MODE || '').trim().toLowerCase();
+    const runtimeMode = runtimeRaw === 'cloud' || runtimeRaw === 'local'
+        ? runtimeRaw
+        : (provider === 'postgres' ? 'cloud' : 'local');
+    if (runtimeRaw && !['local', 'cloud'].includes(runtimeRaw)) {
+        errors.push('TASKFORCE_RUNTIME_MODE must be one of: local, cloud.');
+    }
+    const allowSqliteInCloud = parseBoolean(env.TASKFORCE_ALLOW_SQLITE_IN_CLOUD) === true;
+    const billingEnabled = parseBoolean(env.TASKFORCE_BILLING_ENABLED) === true;
+    if (runtimeMode === 'cloud' && provider !== 'postgres' && !allowSqliteInCloud) {
+        errors.push('Cloud runtime requires TASKFORCE_DB_PROVIDER=postgres (or explicit TASKFORCE_ALLOW_SQLITE_IN_CLOUD=true override).');
+    }
+    if (billingEnabled && runtimeMode !== 'cloud') {
+        errors.push('TASKFORCE_BILLING_ENABLED requires TASKFORCE_RUNTIME_MODE=cloud.');
+    }
+    if (provider === 'postgres' && !hasValue(env, 'TASKFORCE_DATABASE_URL')) {
+        errors.push('TASKFORCE_DATABASE_URL is required when TASKFORCE_DB_PROVIDER=postgres.');
+    }
+    if (billingEnabled && !hasValue(env, 'TASKFORCE_STRIPE_SECRET_KEY')) {
+        errors.push('TASKFORCE_STRIPE_SECRET_KEY is required when TASKFORCE_BILLING_ENABLED=true.');
+    }
+    if (billingEnabled && !hasValue(env, 'TASKFORCE_STRIPE_WEBHOOK_SECRET')) {
+        errors.push('TASKFORCE_STRIPE_WEBHOOK_SECRET is required when TASKFORCE_BILLING_ENABLED=true.');
+    }
+    const authEnabled = parseBoolean(env.TASKFORCE_AUTH_ENABLED);
+    const effectiveAuthEnabled = authEnabled === null ? runtimeMode === 'cloud' : authEnabled;
+    if (effectiveAuthEnabled && !hasValue(env, 'TASKFORCE_AUTH_SESSION_SECRET')) {
+        errors.push('TASKFORCE_AUTH_SESSION_SECRET is required when auth is enabled.');
+    }
+    const sameSiteRaw = String(env.TASKFORCE_AUTH_SESSION_SAMESITE || '').trim();
+    if (sameSiteRaw && !['Lax', 'Strict', 'None', 'lax', 'strict', 'none'].includes(sameSiteRaw)) {
+        errors.push('TASKFORCE_AUTH_SESSION_SAMESITE must be one of: Lax, Strict, None.');
+    }
+    const objectProviderRaw = String(env.TASKFORCE_OBJECT_STORAGE_PROVIDER || env.TASKFORCE_STORAGE_PROVIDER || 'local').trim().toLowerCase();
+    const objectProvider = objectProviderRaw === 'r2' ? 'r2' : 'local';
+    if (objectProviderRaw && !['local', 'r2'].includes(objectProviderRaw)) {
+        errors.push('TASKFORCE_OBJECT_STORAGE_PROVIDER must be one of: local, r2.');
+    }
+    if (objectProvider === 'r2') {
+        const requiredR2 = ['R2_ACCOUNT_ID', 'R2_BUCKET', 'R2_ACCESS_KEY_ID', 'R2_SECRET_ACCESS_KEY'];
+        for (const key of requiredR2) {
+            if (!hasValue(env, key))
+                errors.push(`${key} is required when TASKFORCE_OBJECT_STORAGE_PROVIDER=r2.`);
+        }
+    }
+    const emailProviderRaw = String(env.TASKFORCE_EMAIL_PROVIDER || 'console').trim().toLowerCase();
+    if (!['console', 'resend', 'google-workspace'].includes(emailProviderRaw)) {
+        errors.push('TASKFORCE_EMAIL_PROVIDER must be one of: console, resend, google-workspace.');
+    }
+    if (emailProviderRaw === 'resend' || emailProviderRaw === 'google-workspace') {
+        const hasApiKey = hasValue(env, 'TASKFORCE_EMAIL_PROVIDER_API_KEY')
+            || (emailProviderRaw === 'resend' && hasValue(env, 'TASKFORCE_EMAIL_RESEND_API_KEY'))
+            || (emailProviderRaw === 'google-workspace' && hasValue(env, 'TASKFORCE_EMAIL_GOOGLE_APP_PASSWORD'));
+        if (!hasApiKey) {
+            if (emailProviderRaw === 'resend') {
+                errors.push('TASKFORCE_EMAIL_PROVIDER_API_KEY (or TASKFORCE_EMAIL_RESEND_API_KEY) is required when TASKFORCE_EMAIL_PROVIDER=resend.');
+            }
+            else {
+                errors.push('TASKFORCE_EMAIL_PROVIDER_API_KEY (or TASKFORCE_EMAIL_GOOGLE_APP_PASSWORD) is required when TASKFORCE_EMAIL_PROVIDER=google-workspace.');
+            }
+        }
+    }
+    const virusProviderRaw = String(env.TASKFORCE_VIRUS_SCAN_PROVIDER || 'none').trim().toLowerCase();
+    if (!['none', 'clamav'].includes(virusProviderRaw)) {
+        errors.push('TASKFORCE_VIRUS_SCAN_PROVIDER must be one of: none, clamav.');
+    }
+}
+function validateSoakEnv(env, errors) {
+    if (!hasValue(env, 'SYNC_SOAK_LOCAL_BASE_URL'))
+        errors.push('SYNC_SOAK_LOCAL_BASE_URL is required for soak tests.');
+    if (!hasValue(env, 'SYNC_SOAK_CLOUD_BASE_URL'))
+        errors.push('SYNC_SOAK_CLOUD_BASE_URL is required for soak tests.');
+    if (!hasValue(env, 'SYNC_SOAK_WORKSPACE_ID'))
+        errors.push('SYNC_SOAK_WORKSPACE_ID is required for soak tests.');
+    if (hasValue(env, 'SYNC_SOAK_LOCAL_BASE_URL') && !isHttpUrl(env.SYNC_SOAK_LOCAL_BASE_URL)) {
+        errors.push('SYNC_SOAK_LOCAL_BASE_URL must be an absolute http(s) URL.');
+    }
+    if (hasValue(env, 'SYNC_SOAK_CLOUD_BASE_URL') && !isHttpUrl(env.SYNC_SOAK_CLOUD_BASE_URL)) {
+        errors.push('SYNC_SOAK_CLOUD_BASE_URL must be an absolute http(s) URL.');
+    }
+    const hasAccountPool = hasValue(env, 'SYNC_SOAK_ACCOUNTS_JSON');
+    const hasSingleAccount = hasValue(env, 'SYNC_SOAK_EMAIL') && hasValue(env, 'SYNC_SOAK_PASSWORD');
+    if (!hasAccountPool && !hasSingleAccount) {
+        errors.push('Provide SYNC_SOAK_ACCOUNTS_JSON or both SYNC_SOAK_EMAIL and SYNC_SOAK_PASSWORD.');
+    }
+    if (hasAccountPool) {
+        try {
+            const parsed = JSON.parse(String(env.SYNC_SOAK_ACCOUNTS_JSON || ''));
+            if (!Array.isArray(parsed) || parsed.length === 0) {
+                errors.push('SYNC_SOAK_ACCOUNTS_JSON must be a non-empty JSON array.');
+            }
+            else {
+                for (const entry of parsed) {
+                    const email = String(entry?.email || '').trim();
+                    const password = String(entry?.password || '').trim();
+                    if (!email || !password) {
+                        errors.push('Each SYNC_SOAK_ACCOUNTS_JSON entry must include non-empty email and password.');
+                        break;
+                    }
+                }
+            }
+        }
+        catch {
+            errors.push('SYNC_SOAK_ACCOUNTS_JSON must be valid JSON.');
+        }
+    }
+    const profile = String(env.SYNC_SOAK_PROFILE || 'smoke').trim().toLowerCase();
+    if (!['smoke', 'stress', 'overnight'].includes(profile)) {
+        errors.push('SYNC_SOAK_PROFILE must be one of: smoke, stress, overnight.');
+    }
+    if (hasValue(env, 'SYNC_SOAK_ACCOUNT_WORKSPACES_JSON')) {
+        try {
+            const parsed = JSON.parse(String(env.SYNC_SOAK_ACCOUNT_WORKSPACES_JSON || ''));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                errors.push('SYNC_SOAK_ACCOUNT_WORKSPACES_JSON must be a JSON object map (email->workspaceId).');
+            }
+        }
+        catch {
+            errors.push('SYNC_SOAK_ACCOUNT_WORKSPACES_JSON must be valid JSON.');
+        }
+    }
+}
+export function validateEnvironment(env = process.env, options = {}) {
+    const target = options.target || 'all';
+    const strictUnknown = options.strictUnknown !== false;
+    const errors = [];
+    const warnings = [];
+    validateCommonNumbers(env, errors);
+    if (target === 'server' || target === 'all') {
+        validateServerEnv(env, errors);
+    }
+    if (target === 'soak' || target === 'all') {
+        validateSoakEnv(env, errors);
+    }
+    if (strictUnknown) {
+        const known = new Set(SPECS.map((spec) => spec.key));
+        for (const key of Object.keys(env)) {
+            if (!isManagedKey(key))
+                continue;
+            if (!known.has(key)) {
+                errors.push(`Unknown managed environment variable: ${key}`);
+            }
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        warnings
+    };
+}
+export function assertEnvironment(env = process.env, options = {}) {
+    const result = validateEnvironment(env, options);
+    if (result.ok)
+        return;
+    const details = result.errors.map((entry) => `- ${entry}`).join('\n');
+    throw new Error(`Environment validation failed:\n${details}`);
+}
+export function getEnvSpecs(target = 'all') {
+    if (target === 'all')
+        return [...SPECS];
+    return SPECS.filter((spec) => spec.targets.includes(target) || spec.targets.includes('all'));
+}
+export function renderEnvExample(target = 'all') {
+    const specs = getEnvSpecs(target);
+    const categoryOrder = ['Core', 'Auth', 'Storage', 'Security', 'Email', 'Build', 'Client', 'Soak', 'Cloudflare'];
+    const grouped = new Map();
+    for (const category of categoryOrder)
+        grouped.set(category, []);
+    for (const spec of specs) {
+        const bucket = grouped.get(spec.category);
+        if (bucket)
+            bucket.push(spec);
+    }
+    const out = [];
+    out.push('# Generated file. Edit values locally; do not store secrets in git.');
+    out.push('# Regenerate with: npm run gen:env-example');
+    out.push('');
+    for (const category of categoryOrder) {
+        const entries = grouped.get(category) || [];
+        if (entries.length === 0)
+            continue;
+        out.push(`# ${category}`);
+        for (const spec of entries) {
+            out.push(`# ${spec.description}`);
+            const value = spec.defaultValue
+                ?? spec.example
+                ?? (spec.secret ? '' : '');
+            out.push(`${spec.key}=${value}`);
+            out.push('');
+        }
+    }
+    return `${out.join('\n').trimEnd()}\n`;
+}
+export const MANAGED_ENV_KEYS = Object.freeze([...SPEC_BY_KEY.keys()]);

package/dist/config/envSchema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/envSchema.test.js

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import { renderEnvExample, validateEnvironment } from './envSchema';
+describe('config/envSchema', () => {
+    it('fails server validation when cloud runtime is configured without postgres', () => {
+        const result = validateEnvironment({
+            TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_DB_PROVIDER: 'sqlite',
+            TASKFORCE_AUTH_ENABLED: 'false'
+        }, { target: 'server', strictUnknown: false });
+        expect(result.ok).toBe(false);
+        expect(result.errors.join('\n')).toMatch(/Cloud runtime requires TASKFORCE_DB_PROVIDER=postgres/i);
+    });
+    it('fails soak validation when credentials are missing', () => {
+        const result = validateEnvironment({
+            SYNC_SOAK_LOCAL_BASE_URL: 'http://localhost:5174',
+            SYNC_SOAK_CLOUD_BASE_URL: 'https://performance-app.taskforcehq.ai',
+            SYNC_SOAK_WORKSPACE_ID: 'test-smoke'
+        }, { target: 'soak', strictUnknown: false });
+        expect(result.ok).toBe(false);
+        expect(result.errors.join('\n')).toMatch(/SYNC_SOAK_ACCOUNTS_JSON|SYNC_SOAK_EMAIL/i);
+    });
+    it('renders an env example with key sections', () => {
+        const example = renderEnvExample('all');
+        expect(example).toContain('# Core');
+        expect(example).toContain('TASKFORCE_DB_PROVIDER=');
+        expect(example).toContain('SYNC_SOAK_ACCOUNTS_JSON=');
+    });
+    it('rejects unknown email provider', () => {
+        const result = validateEnvironment({
+            TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_DB_PROVIDER: 'postgres',
+            TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
+            TASKFORCE_AUTH_ENABLED: 'false',
+            TASKFORCE_EMAIL_PROVIDER: 'ses'
+        }, { target: 'server', strictUnknown: false });
+        expect(result.ok).toBe(false);
+        expect(result.errors.join('\n')).toContain('TASKFORCE_EMAIL_PROVIDER must be one of: console, resend, google-workspace.');
+    });
+    it('requires google workspace app password when provider is google-workspace', () => {
+        const result = validateEnvironment({
+            TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_DB_PROVIDER: 'postgres',
+            TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
+            TASKFORCE_AUTH_ENABLED: 'false',
+            TASKFORCE_EMAIL_PROVIDER: 'google-workspace'
+        }, { target: 'server', strictUnknown: false });
+        expect(result.ok).toBe(false);
+        expect(result.errors.join('\n')).toContain('TASKFORCE_EMAIL_PROVIDER_API_KEY (or TASKFORCE_EMAIL_GOOGLE_APP_PASSWORD) is required when TASKFORCE_EMAIL_PROVIDER=google-workspace.');
+    });
+    it('accepts google workspace provider with google app password alias', () => {
+        const result = validateEnvironment({
+            TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_DB_PROVIDER: 'postgres',
+            TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
+            TASKFORCE_AUTH_ENABLED: 'false',
+            TASKFORCE_EMAIL_PROVIDER: 'google-workspace',
+            TASKFORCE_EMAIL_GOOGLE_APP_PASSWORD: 'app-password'
+        }, { target: 'server', strictUnknown: false });
+        expect(result.ok).toBe(true);
+    });
+    it('requires TASKFORCE_STRIPE_SECRET_KEY when billing is enabled', () => {
+        const result = validateEnvironment({
+            TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_DB_PROVIDER: 'postgres',
+            TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
+            TASKFORCE_AUTH_ENABLED: 'false',
+            TASKFORCE_BILLING_ENABLED: 'true',
+            TASKFORCE_STRIPE_WEBHOOK_SECRET: 'whsec_test'
+        }, { target: 'server', strictUnknown: false });
+        expect(result.ok).toBe(false);
+        expect(result.errors.join('\n')).toContain('TASKFORCE_STRIPE_SECRET_KEY is required when TASKFORCE_BILLING_ENABLED=true.');
+    });
+    it('requires TASKFORCE_STRIPE_WEBHOOK_SECRET when billing is enabled', () => {
+        const result = validateEnvironment({
+            TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_DB_PROVIDER: 'postgres',
+            TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
+            TASKFORCE_AUTH_ENABLED: 'false',
+            TASKFORCE_BILLING_ENABLED: 'true',
+            TASKFORCE_STRIPE_SECRET_KEY: 'sk_test_x'
+        }, { target: 'server', strictUnknown: false });
+        expect(result.ok).toBe(false);
+        expect(result.errors.join('\n')).toContain('TASKFORCE_STRIPE_WEBHOOK_SECRET is required when TASKFORCE_BILLING_ENABLED=true.');
+    });
+    it('requires cloud runtime when billing is enabled', () => {
+        const result = validateEnvironment({
+            TASKFORCE_RUNTIME_MODE: 'local',
+            TASKFORCE_DB_PROVIDER: 'sqlite',
+            TASKFORCE_AUTH_ENABLED: 'false',
+            TASKFORCE_BILLING_ENABLED: 'true',
+            TASKFORCE_STRIPE_SECRET_KEY: 'sk_test_x',
+            TASKFORCE_STRIPE_WEBHOOK_SECRET: 'whsec_test'
+        }, { target: 'server', strictUnknown: false });
+        expect(result.ok).toBe(false);
+        expect(result.errors.join('\n')).toContain('TASKFORCE_BILLING_ENABLED requires TASKFORCE_RUNTIME_MODE=cloud.');
+    });
+});

package/dist/config/surfaceBase.d.ts

@@ -0,0 +1,2 @@
+export type SurfaceId = 'app' | 'site' | 'admin';
+export declare function getSurfaceBase(surface: SurfaceId): string;

package/dist/config/surfaceBase.js

@@ -0,0 +1,8 @@
+const SURFACE_BASE = {
+    app: '/taskforce/',
+    site: '/',
+    admin: '/'
+};
+export function getSurfaceBase(surface) {
+    return SURFACE_BASE[surface];
+}

package/dist/core/BulkUpdateFieldsPreview.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/BulkUpdateFieldsPreview.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { TaskforceCore } from './Taskforce';
+function makeTempProjectRoot() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-bulk-preview-'));
+    fs.mkdirSync(root, { recursive: true });
+    return root;
+}
+describe('TaskforceCore bulk update preflight', () => {
+    it('builds deterministic apply set and skips invalid/noop updates', () => {
+        const projectRoot = makeTempProjectRoot();
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const task = core.createTask({ title: 'A', priority: 2 });
+        const preview = core.bulkUpdateFieldsPreview([
+            { title: 'missing id' },
+            { id: 'task-missing', title: 'x' },
+            { id: task.id, priority: 2 }, // no-op
+            { id: task.id, priority: 3 } // apply
+        ]);
+        expect(preview.total).toBe(4);
+        expect(preview.toApply).toHaveLength(1);
+        expect(preview.toApply[0].id).toBe(task.id);
+        expect(preview.toApply[0].changedFields).toEqual(['priority']);
+        expect(preview.skipped.map(s => s.code)).toEqual(expect.arrayContaining(['TASK_ID_REQUIRED', 'TASK_NOT_FOUND', 'DUPLICATE_SUPERSEDED']));
+        core.close();
+        fs.rmSync(projectRoot, { recursive: true, force: true });
+    });
+    it('applies only changed fields and returns skip counters', () => {
+        const projectRoot = makeTempProjectRoot();
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const task = core.createTask({ title: 'A', priority: 2 });
+        const result = core.bulkUpdateFields([
+            { id: task.id, priority: 2 }, // no-op
+            { id: task.id, priority: 3 }, // superseded
+            { id: task.id, priority: 4 } // effective
+        ]);
+        const refreshed = core.getTask(task.id);
+        expect(refreshed?.priority).toBe(4);
+        expect(result.updated).toBe(1);
+        expect(result.skippedNoop).toBe(2);
+        expect(result.deduped).toBe(2);
+        core.close();
+        fs.rmSync(projectRoot, { recursive: true, force: true });
+    });
+    it('includes priority distribution before and after', () => {
+        const projectRoot = makeTempProjectRoot();
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const a = core.createTask({ title: 'A', priority: 1 });
+        core.createTask({ title: 'B', priority: 2 });
+        const preview = core.bulkUpdateFieldsPreview([
+            { id: a.id, priority: 4 }
+        ]);
+        expect(preview.priorityBefore?.[1]).toBe(1);
+        expect(preview.priorityBefore?.[4] || 0).toBe(0);
+        expect(preview.priorityAfter?.[1] || 0).toBe(0);
+        expect(preview.priorityAfter?.[4]).toBe(1);
+        core.close();
+        fs.rmSync(projectRoot, { recursive: true, force: true });
+    });
+});

package/dist/core/CompletedAt.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/CompletedAt.test.js

@@ -0,0 +1,44 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { TaskforceCore } from './Taskforce';
+const roots = [];
+function createCore() {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-completed-at-'));
+    roots.push(projectRoot);
+    return new TaskforceCore({ projectRoot });
+}
+afterEach(() => {
+    while (roots.length > 0) {
+        const root = roots.pop();
+        if (root)
+            fs.rmSync(root, { recursive: true, force: true });
+    }
+});
+describe('TaskforceCore completedAt behavior', () => {
+    it('sets completedAt when status transitions to done', () => {
+        const core = createCore();
+        const task = core.createTask({ title: 'A', status: 'task' });
+        const updated = core.updateTask(task.id, { status: 'done' });
+        expect(updated?.completedAt).toBeTruthy();
+        core.close();
+    });
+    it('preserves completedAt when archiving a previously completed task', () => {
+        const core = createCore();
+        const task = core.createTask({ title: 'B', status: 'task' });
+        const completed = core.updateTask(task.id, { status: 'cancelled' });
+        expect(completed?.completedAt).toBeTruthy();
+        const completedAt = completed?.completedAt;
+        const archived = core.archiveTask(task.id, true, 'No longer needed');
+        expect(archived?.completedAt).toBe(completedAt);
+        core.close();
+    });
+    it('sets completedAt when archiving an active task', () => {
+        const core = createCore();
+        const task = core.createTask({ title: 'C', status: 'in-progress' });
+        const archived = core.archiveTask(task.id, false);
+        expect(archived?.completedAt).toBeTruthy();
+        core.close();
+    });
+});

package/dist/core/CreatedBy.test.d.ts

@@ -0,0 +1 @@
+export {};