create-ortha-app 0.4.2 → 0.5.0

package/templates/default/apps/server/ortha.config.ts

@@ -1,98 +1,64 @@
 /**
  * Typed configuration for this app.
  *
- * **The single place that reads `process.env`.** Everything downstream — the
- * host, every plugin — receives typed values, so "where does this setting come
- * from" has exactly one answer. Deploy-specific values come from the
- * environment; stable product tuning lives here as literals.
+ * **`config/` is the single place that reads the environment**, and it reads it
+ * only through the readers in `@orthacms/utils-server` — never `process.env`
+ * directly. `readEnv` is where "an empty value means the setting is absent" is
+ * decided, and `.env` ships keys with nothing on the right-hand side; a raw
+ * `process.env['X'] ?? default` skips that decision and lets a blank line win
+ * over the default. Everything
+ * downstream — the host, every plugin — receives typed values, so "where does
+ * this setting come from" has exactly one answer. Deploy-specific values come
+ * from the environment; stable product tuning lives in the builders as literals.
+ *
+ * **Shape:** one module per plugin under `config/`, each exporting a builder,
+ * and this file assembling them. So the literal at the bottom is the table of
+ * contents — what this app runs, in one screen — and a reader who wants to know
+ * how one setting is derived opens the one module that owns it. Adding a setting
+ * means editing one builder; adding a plugin means one module and one line here.
+ *
+ * *How* a value is parsed is decided in neither place: the readers come from
+ * `@orthacms/utils-server`. Each refuses a value it cannot honour instead of
+ * guessing, and the guessing is what makes a misconfigured deployment look
+ * configured. Anything conditional is a *value* — a builder returns `undefined`
+ * for a backend you did not configure, and `defined(…)` drops the keys that were
+ * never set, so no config object here needs a `...(x ? { … } : {})` spread.
+ *
+ * This file stays the entry point rather than becoming another module in the
+ * folder: `ortha start` runs the compiled `dist/server/ortha.config.js`, and
+ * `src/plugins.ts` imports the types below.
  */
 import { join } from 'node:path';
 import type {
     ApiDocsOptions,
     TrustProxySetting
 } from '@orthacms/bootstrap-server';
-import type { IdentityPluginConfig } from '@orthacms/identity-server';
-// ortha:if sso-oidc
-import type { OidcProviderConfig } from '@orthacms/identity-provider-oidc';
-// ortha:end
 import type { I18nPluginConfig } from '@orthacms/i18n-server';
-import type { MediaPluginConfig } from '@orthacms/media-server';
-// ortha:if media-local
-import type { LocalStorageConfig } from '@orthacms/media-provider-local';
-// ortha:end
-// ortha:if media-s3
-import type { S3StorageConfig } from '@orthacms/media-provider-s3';
-// ortha:end
-// ortha:if media-azure
-import type { AzureStorageConfig } from '@orthacms/media-provider-azure';
-// ortha:end
-// ortha:if media-gcs
-import type { GcsStorageConfig } from '@orthacms/media-provider-gcs';
-// ortha:end
-// ortha:if media-vercel-blob
-import type { VercelBlobStorageConfig } from '@orthacms/media-provider-vercel-blob';
-// ortha:end
-import type { CopilotPluginConfig } from '@orthacms/copilot-server';
-// ortha:if copilot-anthropic
-import type { AnthropicProviderConfig } from '@orthacms/copilot-provider-anthropic';
-// ortha:end
-// ortha:if copilot-openai
-import type { OpenAiProviderConfig } from '@orthacms/copilot-provider-openai';
-// ortha:end
 // ortha:if mcp
 import type { McpPluginConfig } from '@orthacms/mcp-server';
 // ortha:end
+import {
+    readEnv,
+    readPositiveInt,
+    readTrustProxy,
+    requireEnv
+} from '@orthacms/utils-server';
+
+import { docsConfig } from './config/docs';
+import { identityConfig, type AppIdentityConfig } from './config/identity';
+import { i18nConfig } from './config/i18n';
+import { mediaConfig, type AppMediaConfig } from './config/media';
+import { copilotConfig, type AppCopilotConfig } from './config/copilot';
+// ortha:if mcp
+import { mcpConfig } from './config/mcp';
+// ortha:end
 
 /**
- * Copilot settings plus the backends this deployment can reach.
- *
- * The provider settings live **here**, not inside `CopilotPluginConfig`: the
- * plugin is adapter-agnostic by decision, so it names no provider kind. A key
- * is present only when the deployment configured that backend, and `plugins.ts`
- * registers exactly the ones that are — "configured" is a fact this file can
- * read, where a `defaultProvider` naming one of them could be misspelled or
- * point at a backend nobody registered.
- */
-/**
- * Identity settings, plus the identity providers this app can reach.
- *
- * The provider settings live here rather than inside `IdentityPluginConfig`,
- * for the same reason the copilot's backends do: the plugin names no protocol,
- * and this file is the one place that reads the environment. The constructed
- * adapters are registered in `src/plugins.ts`.
+ * Re-exported so `import type { AppCopilotConfig } from '../ortha.config'`
+ * keeps working. `src/plugins.ts` names these, and which file they are declared
+ * in is an implementation detail of this one.
  */
-export interface AppIdentityConfig extends IdentityPluginConfig {
-    /**
-     * Identity providers, keyed by the name they are registered under. That
-     * name appears in the sign-in URL and in every `sso_identities` row, so
-     * renaming one orphans the links that name it.
-     *
-     * Optional, and absent unless this app was generated with single sign-on.
-     */
-    ssoProviders?: {
-        // ortha:if sso-oidc
-        /** A generic OpenID Connect provider. Present when both env vars are set. */
-        oidc?: OidcProviderConfig & { name: string };
-        // ortha:end
-    };
-}
-
-export interface AppCopilotConfig extends CopilotPluginConfig {
-    providers: {
-        // ortha:if copilot-anthropic
-        /** Native Claude. Present when ANTHROPIC_API_KEY is set. */
-        claude?: AnthropicProviderConfig;
-        // ortha:end
-        // ortha:if copilot-openai
-        /**
-         * An OpenAI-wire endpoint — Ollama, vLLM, LiteLLM, Azure or OpenAI.
-         * Present when COPILOT_OPENAI_BASE_URL is set: an endpoint nobody
-         * named is a backend that can only time out.
-         */
-        openai?: OpenAiProviderConfig;
-        // ortha:end
-    };
-}
+export type { AppIdentityConfig, AppMediaConfig, AppCopilotConfig };
 
 /** Root configuration for this app. */
 export interface OrthaConfig {
@@ -106,27 +72,7 @@ export interface OrthaConfig {
     plugins: {
         identity: AppIdentityConfig;
         i18n: I18nPluginConfig;
-        media: MediaPluginConfig & {
-            /**
-             * Settings for the storage backend `plugins.ts` constructs. Typed
-             * by the factory it imports — the two move together.
-             */
-            // ortha:if media-local
-            storage: LocalStorageConfig;
-            // ortha:end
-            // ortha:if media-s3
-            storage: S3StorageConfig;
-            // ortha:end
-            // ortha:if media-azure
-            storage: AzureStorageConfig;
-            // ortha:end
-            // ortha:if media-gcs
-            storage: GcsStorageConfig;
-            // ortha:end
-            // ortha:if media-vercel-blob
-            storage: VercelBlobStorageConfig;
-            // ortha:end
-        };
+        media: AppMediaConfig;
         copilot: AppCopilotConfig;
         // ortha:if mcp
         mcp: McpPluginConfig;
@@ -134,105 +80,14 @@ export interface OrthaConfig {
     };
 }
 
-/**
- * Reads a value the app cannot run without, failing at load rather than
- * several seconds into boot.
- *
- * Allowed to default to `''`, a missing `DATABASE_URL` reaches `pg` as "use
- * the libpq defaults" — so the first query fails with whatever the local
- * environment happens to produce, and nothing in the message names the
- * variable nobody set.
- */
-function requireEnv(name: string): string {
-    const raw = process.env[name]?.trim();
-    if (!raw) {
-        throw new Error(
-            `Missing required environment variable ${name}. ` +
-                'Set it in your .env before starting the app.'
-        );
-    }
-    return raw;
-}
-
-/**
- * A numeric setting: the default when unset, the value when it is a plain
- * positive integer, and an error otherwise.
- *
- * Deliberately not `Number(process.env[x]) || fallback`, which is wrong in
- * three directions and silent in all of them: `0` is falsy so it becomes the
- * default, a negative is truthy so it is accepted (a negative session TTL
- * issues every session already expired), and `1e9` parses.
- */
-function readPositiveInt(name: string, fallback: number): number {
-    const raw = process.env[name]?.trim();
-    if (!raw) return fallback;
-
-    if (!/^\d+$/.test(raw) || Number(raw) <= 0) {
-        throw new Error(
-            `Environment variable ${name} must be a positive whole number ` +
-                `(got "${raw}").`
-        );
-    }
-    return Number(raw);
-}
-
-/**
- * Express's `trust proxy` setting: a hop count (the recommended form, and the
- * only one a client cannot forge past), a boolean, or a subnet/preset string
- * passed through verbatim. Unset leaves forwarded headers ignored.
- */
-function readTrustProxy(): TrustProxySetting | undefined {
-    const raw = process.env['TRUST_PROXY']?.trim();
-    if (!raw) return undefined;
-
-    const hops = Number(raw);
-    if (Number.isInteger(hops) && hops >= 0) return hops;
-    if (raw === 'true' || raw === 'false') return raw === 'true';
-
-    return raw;
-}
-
-/**
- * True only in a deployment that said so, spelling checked.
- *
- * This one comparison gates two protections at once — whether the API
- * reference is published, and whether the session cookie carries `Secure` — so
- * a typo silently turns both off and is indistinguishable from correct
- * configuration until you read a `Set-Cookie` header.
- */
-const NODE_ENVS = ['development', 'test', 'production'] as const;
-const nodeEnv = process.env['NODE_ENV']?.trim();
-
-if (nodeEnv && !(NODE_ENVS as readonly string[]).includes(nodeEnv)) {
-    throw new Error(
-        `NODE_ENV is "${nodeEnv}", which this app does not recognise — expected ` +
-            `one of ${NODE_ENVS.join(', ')}, or nothing at all for local ` +
-            'development. Anything else reads as "not production", which ' +
-            'publishes the API reference and drops `Secure` from the session cookie.'
-    );
-}
-
-const isProduction = nodeEnv === 'production';
-
-/** A comma-separated list setting, trimmed and emptied of blanks. */
-function readList(name: string, fallback: string): string[] {
-    return (process.env[name] ?? fallback)
-        .split(',')
-        .map((item) => item.trim())
-        .filter(Boolean);
-}
-// ortha:if copilot-anthropic
-const anthropicApiKey = process.env['ANTHROPIC_API_KEY']?.trim();
-// ortha:end
-// ortha:if copilot-openai
-const openAiBaseUrl = process.env['COPILOT_OPENAI_BASE_URL']?.trim();
-// ortha:end
-
 const config: OrthaConfig = {
     port: readPositiveInt('PORT', 3000),
     globalPrefix: 'api',
+    // A hop count is the recommended form and the only one a client cannot
+    // forge past. Unset, forwarded headers are ignored entirely — right for an
+    // app exposed directly, wrong behind any proxy.
     trustProxy: readTrustProxy(),
-    bodyLimit: process.env['MAX_REQUEST_BODY'] || '1mb',
+    bodyLimit: readEnv('MAX_REQUEST_BODY') ?? '1mb',
     // The built admin bundle, served by this same process so the API and the
     // UI share one origin — which is what identity's httpOnly, SameSite=lax
     // session cookie needs. `ortha dev` uses Vite's proxy for the same effect.
@@ -241,263 +96,19 @@ const config: OrthaConfig = {
     // must mean the same thing whether it is read from `dist/` or from source.
     staticDir: join(process.cwd(), 'dist/admin'),
     database: {
-        url: requireEnv('DATABASE_URL')
-    },
-    docs: {
-        // On outside production, where the reference is a development tool.
-        // `API_DOCS=true` publishes it from a deployed instance.
-        enabled: process.env['API_DOCS']
-            ? process.env['API_DOCS'] === 'true'
-            : !isProduction,
-        title: '__APP_TITLE__ API',
-        version: '1.0.0'
+        url: requireEnv(
+            'DATABASE_URL',
+            'Set it in your .env before starting the app.'
+        )
     },
+    docs: docsConfig(),
     plugins: {
-        identity: {
-            // Origins allowed to make state-changing calls (login-CSRF
-            // defence). In development that is the Vite dev server; in
-            // production the app is same-origin, so this list is what a
-            // separately-hosted admin would need adding to.
-            allowedOrigins: (
-                process.env['ALLOWED_ORIGINS'] ??
-                `http://localhost:${readPositiveInt('ADMIN_PORT', 4200)}`
-            )
-                .split(',')
-                .map((origin) => origin.trim())
-                .filter(Boolean),
-            session: {
-                ttlSeconds: readPositiveInt(
-                    'SESSION_TTL_SECONDS',
-                    60 * 60 * 24 * 7
-                ),
-                cookieSecure: isProduction,
-                cookieSameSite: 'lax'
-            },
-            token: {
-                inviteTtlSeconds: readPositiveInt(
-                    'INVITE_TTL_SECONDS',
-                    60 * 60 * 24 * 7
-                ),
-                resetTtlSeconds: readPositiveInt('RESET_TTL_SECONDS', 60 * 60)
-            },
-            rateLimit: {
-                ttlSeconds: readPositiveInt('LOGIN_RATE_LIMIT_TTL_SECONDS', 60),
-                limit: readPositiveInt('LOGIN_RATE_LIMIT', 10)
-            },
-            // Single sign-on. The providers themselves are constructed in
-            // `src/plugins.ts`; these settings shape the handshake.
-            sso: {
-                // The origin browsers reach this API on. It builds the
-                // redirect_uri you register with each provider, and it is
-                // configured rather than read from the request's Host header,
-                // which a client controls. Leave it unset when the admin and
-                // the API share an origin — the usual case.
-                ...(process.env['SSO_PUBLIC_BASE_URL']
-                    ? { publicBaseUrl: process.env['SSO_PUBLIC_BASE_URL'] }
-                    : {}),
-                requestTtlSeconds: readPositiveInt(
-                    'SSO_REQUEST_TTL_SECONDS',
-                    600
-                )
-            },
-            // ortha:if sso-oidc
-            ssoProviders: {
-                // Present only when both are set: an issuer with no client id
-                // becomes a sign-in button that can only fail, and every SSO
-                // failure looks the same, so whoever clicks it learns nothing.
-                ...(process.env['SSO_OIDC_ISSUER'] &&
-                process.env['SSO_OIDC_CLIENT_ID']
-                    ? {
-                          oidc: {
-                              name: process.env['SSO_OIDC_NAME'] ?? 'oidc',
-                              issuer: process.env['SSO_OIDC_ISSUER'],
-                              clientId: process.env['SSO_OIDC_CLIENT_ID'],
-                              ...(process.env['SSO_OIDC_CLIENT_SECRET']
-                                  ? {
-                                        clientSecret:
-                                            process.env[
-                                                'SSO_OIDC_CLIENT_SECRET'
-                                            ]
-                                    }
-                                  : {}),
-                              ...(process.env['SSO_OIDC_LABEL']
-                                  ? { label: process.env['SSO_OIDC_LABEL'] }
-                                  : {}),
-                              // The only gate on a first sign-in claiming an
-                              // existing account. A provider that omits the
-                              // claim — Entra ID, notably — links nobody until
-                              // an operator asserts that this directory owns
-                              // the addresses it reports.
-                              emailVerifiedWhenAbsent:
-                                  process.env[
-                                      'SSO_OIDC_EMAIL_VERIFIED_WHEN_ABSENT'
-                                  ] === 'true'
-                          }
-                      }
-                    : {})
-            },
-            // ortha:end
-            // With an email set, an admin is provisioned on boot — idempotent
-            // and non-destructive. This is how you get your first login.
-            rootAdmin: {
-                email: process.env['ORTHA_ROOT_ADMIN_EMAIL'] ?? '',
-                password: process.env['ORTHA_ROOT_ADMIN_PASSWORD'] ?? '',
-                name: process.env['ORTHA_ROOT_ADMIN_NAME'] ?? ''
-            }
-        },
-        i18n: {
-            // Content locales. Stable product configuration, hence literals.
-            // The slugs are stored on entry rows, so removing one hides its
-            // rows rather than deleting them — which is what `orphanedLocales`
-            // is about below.
-            locales: [{ slug: 'en', name: 'English', isDefault: true }],
-            // Rows in a locale no longer listed above are intact and
-            // unreachable, the worst shape for a silent failure. Fail the boot
-            // and put the choice in front of whoever edited the array.
-            orphanedLocales: 'fail'
-        },
-        media: {
-            // ortha:if media-local
-            storage: {
-                // Point MEDIA_LOCAL_ROOT at a persistent volume in production:
-                // a container's own disk is wiped on every deploy.
-                rootDir: process.env['MEDIA_LOCAL_ROOT'] ?? './.storage/media'
-            },
-            // ortha:end
-            // ortha:if media-vercel-blob
-            storage: {
-                // On Vercel the SDK reads BLOB_READ_WRITE_TOKEN itself, so this
-                // is only for running the app elsewhere.
-                ...(process.env['BLOB_READ_WRITE_TOKEN']
-                    ? { token: process.env['BLOB_READ_WRITE_TOKEN'] }
-                    : {})
-            },
-            // ortha:end
-            // ortha:if media-gcs
-            storage: {
-                bucket: requireEnv('MEDIA_GCS_BUCKET'),
-                // Everything else is optional: with no key file and no inline
-                // credentials the client uses Application Default Credentials,
-                // which is what a GKE or Cloud Run deployment wants.
-                ...(process.env['MEDIA_GCS_PROJECT_ID']
-                    ? { projectId: process.env['MEDIA_GCS_PROJECT_ID'] }
-                    : {}),
-                ...(process.env['MEDIA_GCS_KEY_FILE']
-                    ? { keyFilename: process.env['MEDIA_GCS_KEY_FILE'] }
-                    : {}),
-                signWithIam: process.env['MEDIA_GCS_SIGN_WITH_IAM'] === 'true'
-            },
-            // ortha:end
-            // ortha:if media-azure
-            storage: {
-                container: requireEnv('MEDIA_AZURE_CONTAINER'),
-                connectionString: requireEnv('MEDIA_AZURE_CONNECTION_STRING')
-            },
-            // ortha:end
-            // ortha:if media-s3
-            storage: {
-                bucket: requireEnv('MEDIA_S3_BUCKET'),
-                // `auto` is what R2 expects; AWS needs its real region.
-                region: process.env['MEDIA_S3_REGION'] ?? 'auto',
-                // Omit for AWS S3 itself; set it for R2, MinIO, Spaces, B2…
-                ...(process.env['MEDIA_S3_ENDPOINT']
-                    ? { endpoint: process.env['MEDIA_S3_ENDPOINT'] }
-                    : {}),
-                forcePathStyle:
-                    process.env['MEDIA_S3_FORCE_PATH_STYLE'] === 'true',
-                // Absent means "use the SDK's own provider chain" — an instance
-                // role, IRSA, a shared config file. Passing blanks instead
-                // would shadow all of that with credentials that cannot sign.
-                ...(process.env['MEDIA_S3_ACCESS_KEY_ID'] &&
-                process.env['MEDIA_S3_SECRET_ACCESS_KEY']
-                    ? {
-                          credentials: {
-                              accessKeyId: process.env['MEDIA_S3_ACCESS_KEY_ID'],
-                              secretAccessKey:
-                                  process.env['MEDIA_S3_SECRET_ACCESS_KEY']
-                          }
-                      }
-                    : {})
-            },
-            // ortha:end
-            // Redirect an already-authorized download straight to the
-            // storage backend instead of streaming it through the app. Off
-            // unless asked for, and only possible on a backend that can sign a
-            // URL — the plugin refuses the combination at boot rather than
-            // proxying while the operator believes otherwise.
-            directServe:
-                process.env['MEDIA_DIRECT_SERVE'] === 'signed-url'
-                    ? 'signed-url'
-                    : 'off',
-            directServeTtlSeconds: readPositiveInt(
-                'MEDIA_DIRECT_SERVE_TTL_SECONDS',
-                300
-            ),
-            maxUploadBytes: readPositiveInt(
-                'MEDIA_MAX_UPLOAD_BYTES',
-                50 * 1024 * 1024
-            )
-        }
-        ,
-        copilot: {
-            // Off by default: enabling a hosted provider sends workspace
-            // content to a third party, which is an operator's decision to make
-            // explicitly.
-            enabled: process.env['COPILOT_ENABLED'] === 'true',
-            maxOutputTokens: readPositiveInt('COPILOT_MAX_OUTPUT_TOKENS', 8192),
-            providers: {
-                // ortha:if copilot-anthropic
-                // Setting the key is what REGISTERS this backend — leave it
-                // empty and there is no `claude` in the picker at all, rather
-                // than one that fails on the first message.
-                ...(anthropicApiKey
-                    ? {
-                          claude: {
-                              apiKey: anthropicApiKey,
-                              models: readList(
-                                  'COPILOT_ANTHROPIC_MODELS',
-                                  'claude-sonnet-5'
-                              )
-                          }
-                      }
-                    : {}),
-                // ortha:end
-                // ortha:if copilot-openai
-                ...(openAiBaseUrl
-                    ? {
-                          openai: {
-                              baseUrl: openAiBaseUrl,
-                              apiKey: process.env['COPILOT_OPENAI_API_KEY'] ?? '',
-                              models: readList(
-                                  'COPILOT_OPENAI_MODELS',
-                                  'llama3.1'
-                              )
-                          }
-                      }
-                    : {})
-                // ortha:end
-            }
-        }
+        identity: identityConfig(),
+        i18n: i18nConfig(),
+        media: mediaConfig(),
+        copilot: copilotConfig(),
         // ortha:if mcp
-        ,
-        mcp: {
-            // Off by default: once on, any holder of a full-scope API token can
-            // drive content CRUD from an external agent.
-            enabled: process.env['MCP_ENABLED'] === 'true',
-            // The identity MCP clients display in their connector lists.
-            name: '__APP_NAME__',
-            version: '1.0.0',
-            // A request/response transport owes its caller an answer, and the
-            // tool registry has no deadline of its own — so without this the
-            // only bound on a `tools/call` is the query underneath it, and a
-            // blocked pool turns one call into a socket held until the client
-            // gives up.
-            callTimeoutMs: readPositiveInt('MCP_CALL_TIMEOUT_MS', 30_000),
-            // Deliberately generous: the ceiling exists to stop a pathological
-            // result being serialised several times over, not to shape normal
-            // use. A result this large does not fit a model's context anyway.
-            maxResultBytes: readPositiveInt('MCP_MAX_RESULT_BYTES', 4_194_304)
-        }
+        mcp: mcpConfig()
         // ortha:end
     }
 };

package/templates/default/apps/server/src/plugins.spec.ts

@@ -29,11 +29,18 @@ const EXPECTED_PLUGINS = [
     'activity',
     'users',
     'content',
+    // A second entry from the content package: `ServerPlugin.migrations` holds
+    // one descriptor per entry, and saved list views ship their own tables.
+    'content-views',
     // ortha:if graphql
     'content-graphql',
     // ortha:end
     'i18n',
+    'alarms',
+    'webhooks',
     'media',
+    'transfer',
+    'segments',
     'copilot'
     // ortha:if mcp
     ,