create-ortha-app 0.4.3 → 0.5.0

package/dist/lib/run.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USAGE = void 0;
+exports.lockedOf = lockedOf;
+exports.resolveAnswers = resolveAnswers;
+exports.main = main;
+const tslib_1 = require("tslib");
+/**
+ * The scaffolder itself: read the flags, ask what a terminal can be asked,
+ * write the app.
+ *
+ * Separate from `src/cli.ts`, which is the `bin` and does nothing but call
+ * `main()` and turn a thrown error into an exit code. The split is what makes
+ * this testable: importing a module that scaffolds on import would scaffold
+ * during a test run, so the refusals and the defaults below could only be
+ * checked by spawning a process.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const promises_1 = require("node:readline/promises");
+const features_1 = require("./features");
+const template_1 = require("./template");
+const ui = tslib_1.__importStar(require("./ui"));
+const validate_1 = require("./validate");
+exports.USAGE = `create-ortha-app — scaffold an Ortha CMS app
+
+Usage: npx create-ortha-app <directory> [options]
+
+Options:
+  --yes            Accept every default, asking nothing
+  --media <id>     Storage adapter (default: media-local)
+  --copilot <ids>  Comma-separated copilot providers, or "none"
+  --sso <ids>      Comma-separated identity providers (sso-oidc, sso-github,
+                   sso-saml), or "none"
+  --protocols <ids> Comma-separated protocols beyond REST (graphql, mcp), or "none"
+  --no-install     Skip installing dependencies
+  --no-git         Skip initialising a git repository
+  -h, --help       Show this message
+`;
+/** Whether a bare `--flag` is present. */
+function flag(argv, name) {
+    return argv.includes(`--${name}`);
+}
+/** Reads `--name=value` or `--name value` from argv. */
+function option(argv, name) {
+    const inline = argv.find((arg) => arg.startsWith(`--${name}=`));
+    if (inline)
+        return inline.slice(`--${name}=`.length);
+    const index = argv.indexOf(`--${name}`);
+    const next = index === -1 ? undefined : argv[index + 1];
+    return next && !next.startsWith('-') ? next : undefined;
+}
+/** Splits a comma-separated flag value; `none` means an empty selection. */
+function idList(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw.trim() === 'none')
+        return [];
+    return raw
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+}
+/**
+ * The ids a `--media` / `--copilot` / `--sso` / `--protocols` flag named, checked
+ * against the group it belongs to.
+ *
+ * An id nobody recognises has to stop the run. The flags take *feature ids*
+ * (`media-s3`), not the label or the bare adapter name, and `--media s3` is the
+ * natural guess — it used to select nothing, and "nothing" is a real answer for
+ * three of the four groups, so it scaffolded an app quietly missing whatever was
+ * asked for. For storage that app cannot even compile: no adapter means no
+ * `storage` setting and no `mediaStorage()` for the config to call. Naming the
+ * valid ids here costs a typo nothing and turns a broken app into one line of
+ * output.
+ *
+ * `required` marks a single-choice group that must end up with something —
+ * storage, where "no adapter" is not a configuration an app can run.
+ */
+function selected(argv, name, group, required = false) {
+    const chosen = idList(option(argv, name)) ?? defaultsOf(group);
+    const known = new Set(group.map((feature) => feature.id));
+    const unknown = chosen.filter((id) => !known.has(id));
+    if (unknown.length > 0) {
+        throw new Error(`--${name}: no such option ${unknown.map((id) => `"${id}"`).join(', ')}. ` +
+            `Expected ${[...known].join(', ')}${required ? '' : ', or none'}.`);
+    }
+    if (required && chosen.length === 0) {
+        throw new Error(`--${name}: an app needs one of ${[...known].join(', ')} — ` +
+            'there is no configuration for "no adapter at all".');
+    }
+    return chosen;
+}
+/**
+ * This package's own version, which every `@orthacms/*` dependency in the
+ * generated app is pinned to.
+ *
+ * The scaffolder is released in lockstep with the packages it scaffolds, so its
+ * version *is* the matching set — which is the whole mechanism keeping a
+ * generated app internally consistent. Reading it from the manifest rather than
+ * resolving `latest` from the registry also means `npx create-ortha-app@0.3.0`
+ * generates a 0.3.0 app, not whatever shipped since.
+ */
+function ownVersion() {
+    const manifest = (0, node_path_1.join)(__dirname, '../../package.json');
+    return JSON.parse((0, node_fs_1.readFileSync)(manifest, 'utf8'))
+        .version;
+}
+/** Runs a command in `cwd`, returning whether it succeeded. */
+function runCommand(command, args, cwd) {
+    return ((0, node_child_process_1.spawnSync)(command, args, {
+        cwd,
+        stdio: 'inherit',
+        shell: process.platform === 'win32'
+    }).status === 0);
+}
+/** Turns a feature into a picker row. */
+function toChoice(feature) {
+    return {
+        value: feature.id,
+        label: feature.label,
+        hint: feature.hint,
+        selected: feature.enabledByDefault,
+        disabled: !feature.available,
+        locked: feature.locked
+    };
+}
+/**
+ * The ids a feature group falls back to when nothing is picked.
+ *
+ * A locked feature is in every answer, including `--protocols none`: REST is
+ * not something the flag can switch off.
+ */
+function defaultsOf(features) {
+    return features
+        .filter((feature) => (feature.enabledByDefault || feature.locked) &&
+        feature.available)
+        .map((feature) => feature.id);
+}
+/** The ids that are on regardless of what was asked or passed. */
+function lockedOf(features) {
+    return features
+        .filter((feature) => feature.locked && feature.available)
+        .map((feature) => feature.id);
+}
+/** Asks a free-text question, re-asking until it validates. */
+async function askText(label, fallback, validate) {
+    const rl = (0, promises_1.createInterface)({
+        input: process.stdin,
+        output: process.stdout
+    });
+    try {
+        for (;;) {
+            const raw = await rl.question(`${ui.cyan('◆')} ${ui.bold(label)} ${ui.dim(`(${fallback})`)} `);
+            const answer = raw.trim() || fallback;
+            const problem = validate?.(answer);
+            if (!problem)
+                return answer;
+            ui.error(problem);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Resolves the answers, asking only when there is a terminal to ask in.
+ *
+ * Non-interactive is not an error case to warn about — it is CI, a piped
+ * install, and `--yes`. A scaffolder that blocks on a prompt nobody can answer
+ * hangs a pipeline until it times out, which is a far worse failure than
+ * defaulting, so the flags and the defaults cover every question.
+ */
+async function resolveAnswers(argv, defaultName) {
+    const asked = !flag(argv, 'yes') && ui.interactive();
+    const defaultDatabaseUrl = `postgresql://ortha:ortha@localhost:5432/${defaultName.replace(/[^a-z0-9_]/gi, '_')}`;
+    // Storage is `required`: it is a single choice, and an app with no adapter
+    // has no `storage` setting for `plugins.ts` to hand its factory.
+    const media = selected(argv, 'media', features_1.MEDIA_PROVIDERS, true);
+    const copilot = selected(argv, 'copilot', features_1.COPILOT_PROVIDERS);
+    const sso = selected(argv, 'sso', features_1.SSO_PROVIDERS);
+    const protocols = [
+        ...lockedOf(features_1.PROTOCOLS),
+        ...selected(argv, 'protocols', features_1.PROTOCOLS)
+    ];
+    if (!asked) {
+        return {
+            appName: defaultName,
+            databaseUrl: defaultDatabaseUrl,
+            adminEmail: 'admin@example.com',
+            selection: {
+                enabled: new Set([...media, ...copilot, ...sso, ...protocols])
+            }
+        };
+    }
+    ui.section('Project');
+    const appName = await askText('App name', defaultName, validate_1.validateAppName);
+    const databaseUrl = await askText('Database URL', defaultDatabaseUrl, validate_1.validateDatabaseUrl);
+    const adminEmail = await askText('Admin email', 'admin@example.com');
+    ui.section('Features');
+    ui.note('Everything else is installed for you. These are the choices.');
+    console.log('');
+    // Only ask when there is more than one answer available. S3 is not
+    // published, so today this is a question with a single possible reply, and
+    // asking it would be noise pretending to be a choice.
+    const selectable = features_1.MEDIA_PROVIDERS.filter((provider) => provider.available);
+    const chosenMedia = selectable.length > 1
+        ? [
+            (await ui.select('Where should uploads be stored?', features_1.MEDIA_PROVIDERS.map(toChoice))) ?? media[0]
+        ]
+        : media;
+    const chosenCopilot = (await ui.multiselect('AI copilot — which model backends?', features_1.COPILOT_PROVIDERS.map(toChoice))) ?? copilot;
+    const chosenSso = (await ui.multiselect('Single sign-on — which identity providers?', features_1.SSO_PROVIDERS.map(toChoice))) ?? sso;
+    const chosenProtocols = (await ui.multiselect('Which protocols should the content API speak?', features_1.PROTOCOLS.map(toChoice))) ?? protocols;
+    return {
+        appName,
+        databaseUrl,
+        adminEmail,
+        selection: {
+            enabled: new Set([
+                ...chosenMedia.filter(Boolean),
+                ...chosenCopilot,
+                ...chosenSso,
+                ...chosenProtocols
+            ])
+        }
+    };
+}
+/** Human-readable summary of what was chosen. */
+function describeSelection(selection) {
+    const labelsFor = (features) => {
+        const chosen = features
+            .filter((feature) => selection.enabled.has(feature.id))
+            .map((feature) => feature.label);
+        return chosen.length > 0 ? chosen.join(', ') : ui.dim('none');
+    };
+    const providers = features_1.COPILOT_PROVIDERS.filter((provider) => selection.enabled.has(provider.id));
+    return [
+        ['Storage', labelsFor(features_1.MEDIA_PROVIDERS)],
+        ['Protocols', labelsFor(features_1.PROTOCOLS)],
+        [
+            'Copilot',
+            providers.length > 0
+                ? providers.map((p) => p.label).join(', ')
+                : ui.dim('no backend')
+        ],
+        ['Sign-in', labelsFor(features_1.SSO_PROVIDERS)],
+        ['Ortha packages', String((0, features_1.resolvePackages)(selection).length + 1)]
+    ];
+}
+async function main(argv = process.argv.slice(2)) {
+    if (flag(argv, 'help') || argv.includes('-h')) {
+        console.log(exports.USAGE);
+        return;
+    }
+    const positional = argv.filter((arg) => !arg.startsWith('-'));
+    const target = (0, node_path_1.resolve)(positional[0] ?? '.');
+    ui.banner('Ortha CMS', `Creating an app in ${target}`);
+    if ((0, template_1.isNonEmptyDirectory)(target)) {
+        throw new Error(`${target} already exists and is not empty. Pick a new directory, ` +
+            `or empty that one first.`);
+    }
+    const answers = await resolveAnswers(argv, (0, node_path_1.basename)(target));
+    // Generated rather than prompted: a password typed at a prompt is echoed to
+    // the terminal and lands in shell history. This one is written only to the
+    // git-ignored .env, and printed once below.
+    const adminPassword = (0, node_crypto_1.randomBytes)(12).toString('base64url');
+    ui.summary('Your app', [
+        ['Name', answers.appName],
+        ['Database', (0, validate_1.databaseNameFrom)(answers.databaseUrl)],
+        ...describeSelection(answers.selection)
+    ]);
+    (0, node_fs_1.mkdirSync)(target, { recursive: true });
+    (0, template_1.renderTemplate)((0, node_path_1.join)(__dirname, '../../templates/default'), target, {
+        appName: answers.appName,
+        appTitle: answers.appName,
+        databaseUrl: answers.databaseUrl,
+        databaseName: (0, validate_1.databaseNameFrom)(answers.databaseUrl),
+        adminEmail: answers.adminEmail,
+        adminPassword,
+        orthaVersion: ownVersion(),
+        selection: answers.selection
+    });
+    console.log('');
+    ui.success('Files written');
+    if (!flag(argv, 'no-git') && !(0, node_fs_1.existsSync)((0, node_path_1.join)(target, '.git'))) {
+        if (runCommand('git', ['init', '--quiet'], target)) {
+            ui.success('Git repository initialised');
+        }
+    }
+    let installed = true;
+    if (!flag(argv, 'no-install')) {
+        console.log('');
+        ui.note('Installing dependencies…');
+        installed = runCommand('npm', ['install', '--no-audit', '--no-fund'], target);
+        if (installed)
+            ui.success('Dependencies installed');
+    }
+    if (!installed) {
+        ui.error('Dependency installation failed — fix the error above, then run ' +
+            '`npm install` in the new directory.');
+        process.exitCode = 1;
+    }
+    ui.summary('Your admin account', [
+        ['Email', answers.adminEmail],
+        ['Password', ui.bold(adminPassword)],
+        ['', ui.dim('Also written to .env')]
+    ]);
+    ui.nextSteps([
+        `cd ${(0, node_path_1.basename)(target)}`,
+        ...(flag(argv, 'no-install') ? ['npm install'] : []),
+        'docker compose up -d',
+        'npm run migrate',
+        `npm run dev        ${ui.dim('→ http://localhost:4200')}`
+    ]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-ortha-app",
-    "version": "0.4.3",
+    "version": "0.5.0",
     "description": "Create an Ortha CMS app: npx create-ortha-app my-cms",
     "license": "MIT",
     "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/create-ortha-app",

package/templates/default/README.md.tmpl

@@ -22,7 +22,7 @@ provisioned on boot, idempotently — clear those two variables once you have it
 | `npm run build` | Compiles the server and builds the admin bundle |
 | `npm start` | Runs the built server — API **and** admin, one process, one origin |
 | `npm run migrate` | Applies every plugin's pending migrations |
-| `npm run generate -- --name=<name>` | Generates a migration for your own content tables |
+| `npm run generate -- --name=<name>` | Generates a migration for your own content tables — needs a `drizzle.config.ts` first, see below |
 | `npm run studio` | Opens Drizzle Studio on this app's database |
 | `npm test` | Unit tests — both halves |
 | `npm run e2e` | Both end-to-end suites |
@@ -109,7 +109,7 @@ source lands in the same place here.
 | --- | --- |
 | `apps/server/src/plugins.ts` | Which plugins the API runs, and **in what order** |
 | `apps/admin/src/plugins.ts` | Which plugins the admin UI runs |
-| `apps/server/ortha.config.ts` | Every setting, typed — the only reader of `process.env` |
+| `apps/server/ortha.config.ts` | Every setting, typed — with `apps/server/config/`, the only reader of the environment |
 | `apps/admin/src/styles.css` | The theme tokens: this app's whole visual identity |
 
 Upgrading is a version bump. Keep the `@orthacms/*` versions **in step with each
@@ -121,9 +121,9 @@ and UI that silently stops talking to itself.
 
 A server plugin is a `ServerPlugin` from `@orthacms/bootstrap-server` — a name,
 a NestJS module, and optionally its own migrations — added to the array in
-`src/server/plugins.ts`. `@InjectDatabase()` from `@orthacms/database` gives it
+`apps/server/src/plugins.ts`. `@InjectDatabase()` from `@orthacms/database` gives it
 the shared connection. An admin plugin is an `AdminPlugin` from
-`@orthacms/bootstrap-admin`, added to `src/admin/plugins.ts`.
+`@orthacms/bootstrap-admin`, added to `apps/admin/src/plugins.ts`.
 
 `@orthacms/utils-server` and `@orthacms/utils-admin` hold the shared toolkit
 (filter parsing, `apiClient`, slots, table URL state), and
@@ -154,7 +154,7 @@ It is not the switch that keeps your content in-house, though. A backend is
 registered only when its settings are present (below), so an app with no key
 reaches no third party either way.
 
-Backends are registered in `src/server/plugins.ts`, and **the order is the
+Backends are registered in `apps/server/src/plugins.ts`, and **the order is the
 setting** — there is no `defaultProvider`. The first registered backend serves a
 run that names none, and it is what the admin's model picker opens on. A backend
 is only registered when its connection settings are present, so an unconfigured
@@ -189,8 +189,27 @@ This app starts with none. To add some:
 1. Write them under `apps/server/src/content/` and export a `contentTypes` array.
 2. Pass them to `ContentPlugin({ types: contentTypes, migrations: … })` in
    `apps/server/src/plugins.ts` — the comment there has the exact shape.
-3. Add `apps/server/drizzle.config.ts` pointing `schema` at your
-   `src/content/index.ts` and `out` at `../../migrations`.
+3. Add `apps/server/drizzle.config.ts`:
+
+    ```ts
+    import { defineConfig } from 'drizzle-kit';
+
+    export default defineConfig({
+        dialect: 'postgresql',
+        schema: 'apps/server/src/content/index.ts',
+        out: 'migrations'
+    });
+    ```
+
+    Both paths are relative to **this app's root**, not to the config file.
+    drizzle-kit resolves `schema` and `out` from the working directory, and
+    `ortha generate` runs it from the root — so `out: 'migrations'` is the
+    same `migrations/` the plugin's descriptor in step 2 points at, and a
+    `../../` in front of it would write two levels above your project.
+
+    No `dbCredentials`: generating a migration only diffs the schema against
+    the last snapshot and never connects, so there is no secret to put here.
+
 4. `npm run generate -- --name=add_content_types && npm run migrate`
 
 ## Deploying

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

@@ -31,11 +31,14 @@ const EXPECTED_PLUGINS = [
     'i18n',
     'wysiwyg',
     'media',
+    'transfer',
     'alarms',
     'copilot',
+    'segments',
     'users',
     'activity',
-    'api-tokens'
+    'api-tokens',
+    'webhooks'
 ];
 
 describe('buildPlugins()', () => {

package/templates/default/apps/admin/src/plugins.ts

@@ -1,6 +1,7 @@
 import type { AdminPlugin } from '@orthacms/bootstrap-admin';
 import { ActivityPlugin } from '@orthacms/activity-admin';
 import { ApiTokensPlugin } from '@orthacms/api-tokens-admin';
+import { WebhooksPlugin } from '@orthacms/webhooks-admin';
 import { ContentPlugin } from '@orthacms/content-admin';
 import { I18nPlugin } from '@orthacms/i18n-admin';
 import { IdentityPlugin } from '@orthacms/identity-admin';
@@ -12,9 +13,12 @@ import { WorkspacesPlugin } from '@orthacms/workspaces-admin';
 import { WysiwygPlugin } from '@orthacms/wysiwyg-admin';
 import { CopilotPlugin } from '@orthacms/copilot-admin';
 import { AlarmsPlugin } from '@orthacms/alarms-admin';
+import { transferAdminPlugin } from '@orthacms/transfer-admin';
+import { SegmentsPlugin } from '@orthacms/segments-admin';
 
 /**
- * The admin's composition, mirroring `src/server/plugins.ts` on the UI side.
+ * The admin's composition, mirroring `apps/server/src/plugins.ts` on the UI
+ * side.
  *
  * **Two positions matter; the rest is legibility.**
  *
@@ -47,6 +51,10 @@ export function buildPlugins(): AdminPlugin[] {
         I18nPlugin(),
         WysiwygPlugin(),
         MediaPlugin(),
+        // Export/import. Another Content Library slot filler — the entry menu,
+        // the records selection bar and the collection toolbar — so it reads
+        // after ContentPlugin() for the same reason I18nPlugin() does.
+        transferAdminPlugin(),
         // Another Content Library slot filler — the entry rail's checks block,
         // an optional records column, and "Save as rule" in the toolbar.
         AlarmsPlugin(),
@@ -54,8 +62,15 @@ export function buildPlugins(): AdminPlugin[] {
         // the workspace-interior features: the panel mounts into the workspace
         // shell's sidebar footer.
         CopilotPlugin(),
+        // Reader entitlements — who may *read* published content. It fills the
+        // Content Library's entry-header and entry-tab slots, so like the other
+        // library fillers it reads after ContentPlugin(); its own audience
+        // directory is independent of that order. Inert until an audience
+        // exists.
+        SegmentsPlugin(),
         UsersPlugin(),
         ActivityPlugin(),
-        ApiTokensPlugin()
+        ApiTokensPlugin(),
+        WebhooksPlugin()
     ];
 }

package/templates/default/apps/server/config/copilot-openai.ts

@@ -14,7 +14,7 @@ export function openAiProvider(): OpenAiProviderConfig | undefined {
     }
     return {
         baseUrl,
-        apiKey: process.env['COPILOT_OPENAI_API_KEY'] ?? '',
+        apiKey: readEnv('COPILOT_OPENAI_API_KEY') ?? '',
         models: readList('COPILOT_OPENAI_MODELS', 'llama3.1')
     };
 }

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

@@ -3,6 +3,12 @@ import type { IdentityPluginConfig } from '@orthacms/identity-server';
 // ortha:if sso-oidc
 import type { OidcProviderConfig } from '@orthacms/identity-provider-oidc';
 // ortha:end
+// ortha:if sso-github
+import type { GithubProviderConfig } from '@orthacms/identity-provider-github';
+// ortha:end
+// ortha:if sso-saml
+import type { SamlProviderConfig } from '@orthacms/identity-provider-saml';
+// ortha:end
 import {
     defined,
     isProduction,
@@ -14,6 +20,12 @@ import {
 // ortha:if sso-oidc
 import { oidcProvider } from './sso-oidc';
 // ortha:end
+// ortha:if sso-github
+import { githubProvider } from './sso-github';
+// ortha:end
+// ortha:if sso-saml
+import { samlProvider } from './sso-saml';
+// ortha:end
 
 /**
  * Identity settings, plus the identity providers this app can reach.
@@ -36,6 +48,14 @@ export interface AppIdentityConfig extends IdentityPluginConfig {
         /** A generic OpenID Connect provider. Present when both env vars are set. */
         oidc?: OidcProviderConfig & { name: string };
         // ortha:end
+        // ortha:if sso-github
+        /** GitHub or GitHub Enterprise Server. Present when both env vars are set. */
+        github?: GithubProviderConfig & { name: string };
+        // ortha:end
+        // ortha:if sso-saml
+        /** A SAML 2.0 identity provider. Present when all three env vars are set. */
+        saml?: SamlProviderConfig & { name: string };
+        // ortha:end
     };
 }
 
@@ -67,15 +87,28 @@ export function identityConfig(): AppIdentityConfig {
             limit: readPositiveInt('LOGIN_RATE_LIMIT', 10)
         },
         sso: ssoConfig(),
-        // ortha:if sso-oidc
-        ssoProviders: defined({ oidc: oidcProvider() }),
+        // ortha:if sso
+        ssoProviders: defined({
+            // ortha:if sso-oidc
+            oidc: oidcProvider(),
+            // ortha:end
+            // ortha:if sso-github
+            github: githubProvider(),
+            // ortha:end
+            // ortha:if sso-saml
+            saml: samlProvider()
+            // ortha:end
+        }),
         // ortha:end
         // With an email set, an admin is provisioned on boot — idempotent and
         // non-destructive. This is how you get your first login.
+        // Read through `readEnv`, so all three are trimmed and a whitespace-only
+        // value is nothing rather than a value — a password of three spaces
+        // would otherwise be provisioned as the administrator's, silently.
         rootAdmin: {
-            email: process.env['ORTHA_ROOT_ADMIN_EMAIL'] ?? '',
-            password: process.env['ORTHA_ROOT_ADMIN_PASSWORD'] ?? '',
-            name: process.env['ORTHA_ROOT_ADMIN_NAME'] ?? ''
+            email: readEnv('ORTHA_ROOT_ADMIN_EMAIL') ?? '',
+            password: readEnv('ORTHA_ROOT_ADMIN_PASSWORD') ?? '',
+            name: readEnv('ORTHA_ROOT_ADMIN_NAME') ?? ''
         }
     };
 }

package/templates/default/apps/server/config/media-storage.ts

@@ -8,13 +8,14 @@
  */
 // ortha:if media-local
 import type { LocalStorageConfig } from '@orthacms/media-provider-local';
+import { readEnv } from '@orthacms/utils-server';
 
 /** Local-filesystem blobs. */
 export function mediaStorage(): LocalStorageConfig {
     return {
         // 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'
+        rootDir: readEnv('MEDIA_LOCAL_ROOT') ?? './.storage/media'
     };
 }
 // ortha:end
@@ -67,7 +68,7 @@ export function mediaStorage(): S3StorageConfig {
     return defined({
         bucket: requireEnv('MEDIA_S3_BUCKET'),
         // `auto` is what R2 expects; AWS needs its real region.
-        region: process.env['MEDIA_S3_REGION'] ?? 'auto',
+        region: readEnv('MEDIA_S3_REGION') ?? 'auto',
         // Omit for AWS S3 itself; set it for R2, MinIO, Spaces, B2…
         endpoint: readEnv('MEDIA_S3_ENDPOINT'),
         forcePathStyle: readFlag('MEDIA_S3_FORCE_PATH_STYLE', false),

package/templates/default/apps/server/config/sso-github.ts

@@ -0,0 +1,42 @@
+// ortha:if sso-github
+import type { GithubProviderConfig } from '@orthacms/identity-provider-github';
+import { defined, readEnv, readList } from '@orthacms/utils-server';
+
+/**
+ * The GitHub provider, or nothing.
+ *
+ * Present only when both values are set. The secret is not optional the way an
+ * OIDC one can be: GitHub's code exchange has no PKCE, so the secret is the
+ * only thing proving the code is being redeemed by this application — and the
+ * adapter refuses at construction rather than at the first sign-in, because
+ * every SSO failure looks the same to whoever clicked the button.
+ */
+export function githubProvider():
+    | (GithubProviderConfig & { name: string })
+    | undefined {
+    const clientId = readEnv('SSO_GITHUB_CLIENT_ID');
+    const clientSecret = readEnv('SSO_GITHUB_CLIENT_SECRET');
+    if (!clientId || !clientSecret) {
+        return undefined;
+    }
+    // `.env` ships this key blank, and `readList` answers a blank with `[]` —
+    // which is a value, not an absence, so passing it straight through would
+    // request *no* scopes and leave the profile read with nothing to read.
+    const scopes = readList('SSO_GITHUB_SCOPES', '');
+    return defined({
+        name: readEnv('SSO_GITHUB_NAME') ?? 'github',
+        clientId,
+        clientSecret,
+        label: readEnv('SSO_GITHUB_LABEL'),
+        // Defaults to `read:user user:email` — a profile and the verified
+        // addresses on it. GitHub's scopes are coarse, so anything wider hands
+        // the CMS access it has no use for.
+        scopes: scopes.length > 0 ? scopes : undefined,
+        // Only for GitHub Enterprise Server; github.com needs none.
+        enterpriseBaseUrl: readEnv('SSO_GITHUB_ENTERPRISE_BASE_URL'),
+        // Cosmetic, like Google's `hd`: it shapes the account chooser. Who
+        // actually gets in is this CMS's own decision, not GitHub's.
+        organization: readEnv('SSO_GITHUB_ORGANIZATION')
+    });
+}
+// ortha:end

package/templates/default/apps/server/config/sso-oidc.ts

@@ -16,7 +16,7 @@ export function oidcProvider(): (OidcProviderConfig & { name: string }) | undefi
         return undefined;
     }
     return defined({
-        name: process.env['SSO_OIDC_NAME'] ?? 'oidc',
+        name: readEnv('SSO_OIDC_NAME') ?? 'oidc',
         issuer,
         clientId,
         clientSecret: readEnv('SSO_OIDC_CLIENT_SECRET'),

package/templates/default/apps/server/config/sso-saml.ts

@@ -0,0 +1,46 @@
+// ortha:if sso-saml
+import type { SamlProviderConfig } from '@orthacms/identity-provider-saml';
+import { defined, readEnv, readFlag } from '@orthacms/utils-server';
+
+/**
+ * The SAML provider, or nothing.
+ *
+ * All three of the entry point, the certificate and this app's entity id are
+ * required, and there is nothing to fall back to: SAML has no discovery
+ * document and no key endpoint, so the certificate an operator copies out of
+ * their IdP is the whole of the trust relationship.
+ */
+export function samlProvider():
+    | (SamlProviderConfig & { name: string })
+    | undefined {
+    const entryPoint = readEnv('SSO_SAML_ENTRY_POINT');
+    const idpCert = readEnv('SSO_SAML_IDP_CERT');
+    const issuer = readEnv('SSO_SAML_ISSUER');
+    if (!entryPoint || !idpCert || !issuer) {
+        return undefined;
+    }
+    return defined({
+        name: readEnv('SSO_SAML_NAME') ?? 'saml',
+        entryPoint,
+        // A PEM body on one line, `\n` escapes and all: an environment
+        // variable cannot hold real newlines, so they are put back here rather
+        // than left for the XML parser to fail on.
+        idpCert: idpCert.replace(/\\n/g, '\n'),
+        issuer,
+        label: readEnv('SSO_SAML_LABEL'),
+        // Worth setting whenever the IdP's NameID format is `emailAddress`: an
+        // address is not a stable identifier, and a profile whose subject is
+        // one is refused.
+        subjectAttribute: readEnv('SSO_SAML_SUBJECT_ATTRIBUTE'),
+        emailAttribute: readEnv('SSO_SAML_EMAIL_ATTRIBUTE'),
+        nameAttribute: readEnv('SSO_SAML_NAME_ATTRIBUTE'),
+        groupsAttribute: readEnv('SSO_SAML_GROUPS_ATTRIBUTE'),
+        // Defaults to false, and stays an assertion rather than a reading:
+        // **SAML carries no verification claim at all**, so there is nothing
+        // an adapter could inspect and be honest about. Setting it says this
+        // directory is authoritative for the addresses it reports — which is
+        // the only gate on a first sign-in claiming an existing account.
+        emailVerified: readFlag('SSO_SAML_EMAIL_VERIFIED', false)
+    });
+}
+// ortha:end