create-ortha-app 0.4.0

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

@@ -0,0 +1,229 @@
+import type { ServerPlugin } from '@orthacms/bootstrap-server';
+import { ActivityPlugin } from '@orthacms/activity-server';
+import { ContentPlugin } from '@orthacms/content-server';
+import { DatabasePlugin } from '@orthacms/database';
+import { I18nServerPlugin } from '@orthacms/i18n-server';
+import { IdentityPlugin } from '@orthacms/identity-server';
+// ortha:if sso-oidc
+import type { SsoRegistration } from '@orthacms/identity-domain';
+import { createOidcProvider } from '@orthacms/identity-provider-oidc';
+// ortha:end
+import { MediaServerPlugin } from '@orthacms/media-server';
+// ortha:if media-local
+import { createLocalStorageProvider } from '@orthacms/media-provider-local';
+// ortha:end
+// ortha:if media-s3
+import { createS3StorageProvider } from '@orthacms/media-provider-s3';
+// ortha:end
+// ortha:if media-azure
+import { createAzureStorageProvider } from '@orthacms/media-provider-azure';
+// ortha:end
+// ortha:if media-gcs
+import { createGcsStorageProvider } from '@orthacms/media-provider-gcs';
+// ortha:end
+// ortha:if media-vercel-blob
+import { createVercelBlobStorageProvider } from '@orthacms/media-provider-vercel-blob';
+// ortha:end
+import { UsersPlugin } from '@orthacms/users-server';
+// ortha:if graphql
+import { ContentGraphqlPlugin } from '@orthacms/content-graphql';
+// ortha:end
+// ortha:if mcp
+import { McpPlugin } from '@orthacms/mcp-server';
+// ortha:end
+import {
+    CopilotPlugin,
+    type ProviderRegistration
+} from '@orthacms/copilot-server';
+import { createFakeProvider } from '@orthacms/copilot-provider-fake';
+// ortha:if copilot-anthropic
+import { createAnthropicProvider } from '@orthacms/copilot-provider-anthropic';
+// ortha:end
+// ortha:if copilot-openai
+import { createOpenAiProvider } from '@orthacms/copilot-provider-openai';
+// ortha:end
+import { WorkspacesPlugin } from '@orthacms/workspaces-server';
+import type { OrthaConfig } from '../ortha.config';
+
+/**
+ * The model backends this deployment can actually reach, in preference order.
+ *
+ * **Only what is configured is registered.** `ortha.config.ts` omits a provider
+ * whose connection settings are absent, and an unconfigured backend is skipped
+ * here too: the first entry serves a run that names no provider, so a keyless
+ * one at the top of the list would be the house default and would fail on the
+ * first message.
+ *
+ * `fake` is last and unconditional. It is a shipped adapter, not test
+ * scaffolding — it needs no key and no network, so it is what makes the chat
+ * work offline, and being last it is the default only when it is the only one.
+ */
+// ortha:if sso-oidc
+/**
+ * The identity providers this app can actually reach.
+ *
+ * **Only what is configured is registered.** `ortha.config.ts` omits a provider
+ * whose issuer or client id is missing, and an unconfigured one is skipped here
+ * too — it would appear on the sign-in page as a button that can only fail.
+ *
+ * Running two directories at once is another entry. The name is what
+ * `/api/auth/sso/<name>/start` and every `sso_identities` row refer to the
+ * provider by, so renaming a registration orphans its links. Register the
+ * callback URL `<publicBaseUrl>/api/auth/sso/<name>/callback` with the
+ * provider; `ssoCallbackUrl` from `@orthacms/identity-server` builds the exact
+ * string, which matters because most providers match it byte for byte.
+ */
+export function ssoProviders(config: OrthaConfig): SsoRegistration[] {
+    const oidc = config.plugins.identity.ssoProviders?.oidc;
+    if (!oidc) {
+        return [];
+    }
+    const { name, ...settings } = oidc;
+    return [{ name, provider: createOidcProvider(settings) }];
+}
+// ortha:end
+
+export function copilotProviders(config: OrthaConfig): ProviderRegistration[] {
+    const providers: ProviderRegistration[] = [];
+    // ortha:if copilot-anthropic
+    if (config.plugins.copilot.providers.claude) {
+        providers.push({
+            name: 'claude',
+            provider: createAnthropicProvider(
+                config.plugins.copilot.providers.claude
+            )
+        });
+    }
+    // ortha:end
+    // ortha:if copilot-openai
+    if (config.plugins.copilot.providers.openai) {
+        providers.push({
+            name: 'openai',
+            provider: createOpenAiProvider(
+                config.plugins.copilot.providers.openai
+            )
+        });
+    }
+    // ortha:end
+    providers.push({ name: 'fake', provider: createFakeProvider() });
+
+    return providers;
+}
+
+/**
+ * This app's composition — the whole of what its API is.
+ *
+ * **The order is migration order.** Migrations are applied by walking this
+ * array, with no transaction spanning plugins, so a plugin whose tables
+ * reference another's must come after it. `WorkspacesPlugin` follows
+ * `IdentityPlugin` because its `memberships` table FK-references identity's
+ * `users`: put it first and a *fresh* `ortha migrate` fails with
+ * `relation "users" does not exist`, while an already-migrated database
+ * migrates perfectly happily — so the mistake ships and bites the next clean
+ * install. Add new plugins at the end unless you have a reason not to.
+ *
+ * Order does **not** decide dependency injection: every plugin module is
+ * global and every `onPluginInit` runs before the Nest app is created, so no
+ * provider can be constructed before the database connection is open.
+ *
+ * To add a plugin, install it and add a line. To remove one, delete its line —
+ * plugins that extend each other do so through optional ports, so removing one
+ * degrades the feature rather than failing boot.
+ */
+export function buildPlugins(config: OrthaConfig): ServerPlugin[] {
+    // No content types yet — see the note below. Held in a variable because
+    // the GraphQL adapter takes the plugin itself, not just its types.
+    const content = ContentPlugin({ types: [] });
+
+    return [
+        // First: the only plugin that opens a resource in `onPluginInit`.
+        DatabasePlugin({ connectionString: config.database.url }),
+        // ortha:if sso-oidc
+        // Identity, plus the identity providers this app offers. The second
+        // argument is where constructed adapters go: `ortha.config.ts` holds
+        // the typed view of the environment, and an adapter instance is not an
+        // environment value.
+        IdentityPlugin(config.plugins.identity, {
+            sso: { providers: ssoProviders(config) }
+        }),
+        // ortha:end
+        // ortha:ifnot sso-oidc
+        IdentityPlugin(config.plugins.identity),
+        // ortha:end
+        WorkspacesPlugin(),
+        ActivityPlugin(),
+        UsersPlugin(),
+        // No content types yet. Define some in `src/server/content/`, pass them
+        // here as `types`, then add a `drizzle.config.ts` pointing at them and
+        // a `migrations` descriptor so `ortha generate` / `ortha migrate` can
+        // manage their tables:
+        //
+        //   ContentPlugin({
+        //       types: contentTypes,
+        //       migrations: {
+        //           dir: () => join(process.cwd(), 'migrations'),
+        //           table: '__drizzle_migrations_content'
+        //       }
+        //   })
+        //
+        // Until then the plugin serves its generic routes with an empty
+        // registry, and owns no tables of its own.
+        content,
+        // ortha:if graphql
+        // The same public content API over GraphQL, on /api/v1/graphql. It owns
+        // no schema and adds no credential — it reuses content's bearer guards
+        // and read services, so a token minted before it existed works against
+        // it unchanged. Taking `content` by value lets it fail boot on two
+        // content types that would collide as GraphQL names, rather than on the
+        // first request from a workspace granted both.
+        ContentGraphqlPlugin({
+            content,
+            playground: config.docs.enabled === true
+        }),
+        // ortha:end
+        // Fills the Content Library's locale extensions, so it reads after it.
+        I18nServerPlugin(config.plugins.i18n),
+        // This line is the single place that selects storage — one constructed
+        // provider, writing every upload to local disk. A deployment runs
+        // exactly one; swapping backend is swapping this expression (and the
+        // type of `media.storage` with it).
+        MediaServerPlugin({
+            // ortha:if media-local
+            provider: createLocalStorageProvider(config.plugins.media.storage),
+            // ortha:end
+            // ortha:if media-s3
+            provider: createS3StorageProvider(config.plugins.media.storage),
+            // ortha:end
+            // ortha:if media-azure
+            provider: createAzureStorageProvider(config.plugins.media.storage),
+            // ortha:end
+            // ortha:if media-gcs
+            provider: createGcsStorageProvider(config.plugins.media.storage),
+            // ortha:end
+            // ortha:if media-vercel-blob
+            provider: createVercelBlobStorageProvider(
+                config.plugins.media.storage
+            ),
+            // ortha:end
+            config: config.plugins.media
+        }),
+        // Registered after workspaces (runs are workspace-scoped) and identity
+        // (runs execute as the calling user, gated on `copilot:use`). The
+        // composition root is the single place that selects a backend: the
+        // plugin never learns which adapters exist, it takes a list of named,
+        // already-constructed providers, and **the order is the setting** —
+        // there is no `defaultProvider`, the first entry serves a run that
+        // names none.
+        CopilotPlugin({
+            providers: copilotProviders(config),
+            config: config.plugins.copilot
+        }),
+        // ortha:if mcp
+        // The Model Context Protocol front door, registered LAST because it
+        // serves whatever the plugins above contributed. Off unless
+        // MCP_ENABLED=true: it hands an external agent the same content CRUD a
+        // full-scope token has.
+        McpPlugin({ config: config.plugins.mcp })
+        // ortha:end
+    ];
+}

package/templates/default/apps/server/tsconfig.json

@@ -0,0 +1,31 @@
+{
+    "compilerOptions": {
+        "target": "es2022",
+        "lib": [
+            "es2023"
+        ],
+        "module": "commonjs",
+        "moduleResolution": "node",
+        "outDir": "../../dist/server",
+        "rootDir": ".",
+        "types": [
+            "node"
+        ],
+        "strict": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "sourceMap": true,
+        "declaration": false,
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true,
+        "tsBuildInfoFile": "../../dist/server/tsconfig.tsbuildinfo"
+    },
+    "include": [
+        "**/*.ts"
+    ],
+    "exclude": [
+        "**/*.spec.ts"
+    ]
+}

package/templates/default/apps/server-e2e/jest.config.js

@@ -0,0 +1,47 @@
+/**
+ * Server end-to-end tests — the real app, a real database.
+ *
+ * Separate from `jest.config.js` on purpose: these need a database, take
+ * seconds rather than milliseconds, and must run **serially**. `npm test`
+ * stays fast and infrastructure-free; `npm run e2e:server` is the slow one you
+ * run before pushing.
+ */
+module.exports = {
+    displayName: 'server-e2e',
+    testEnvironment: 'node',
+    rootDir: '../..',
+    testMatch: ['<rootDir>/apps/server-e2e/src/**/*.spec.ts'],
+    globalSetup: '<rootDir>/apps/server-e2e/src/global-setup.ts',
+    setupFiles: ['<rootDir>/apps/server-e2e/src/jest.setup.ts'],
+    // One worker. The suite truncates shared tables, so parallel workers
+    // delete each other's fixtures — and the failure surfaces as whichever
+    // assertion happened to read a row mid-truncate, never as the race it is.
+    maxWorkers: 1,
+    // Booting the app migrates nothing but does open a pool and run the
+    // bootstrap seeders; the default 5s is not enough on a cold database.
+    testTimeout: 30_000,
+    transform: {
+        '^.+\\.[tj]s$': [
+            '@swc/jest',
+            {
+                jsc: {
+                    target: 'es2022',
+                    parser: { syntax: 'typescript', decorators: true },
+                    transform: {
+                        legacyDecorator: true,
+                        decoratorMetadata: true
+                    }
+                },
+                module: { type: 'commonjs' }
+            }
+        ]
+    },
+    // Jest runs CommonJS, and `createServer` pulls in the Scalar API-reference
+    // renderer, which is published as ESM only — so `node_modules` cannot be
+    // ignored wholesale or the import fails with `Unexpected token 'export'`
+    // pointing at a file nobody in this app wrote. Letting swc transform that
+    // one scope is cheaper than stubbing the module and pretending the docs
+    // route does not exist.
+    transformIgnorePatterns: ['/node_modules/(?!@scalar/)'],
+    moduleFileExtensions: ['ts', 'js', 'json']
+};

package/templates/default/apps/server-e2e/src/api.spec.ts

@@ -0,0 +1,107 @@
+import request from 'supertest';
+import { resolveTestDatabaseUrl, resetDatabase } from './support/db';
+import {
+    ALLOWED_ORIGIN,
+    closeTestApp,
+    createTestApp,
+    type TestApp
+} from './support/test-app';
+
+/**
+ * The API, driven through the real bootstrap.
+ *
+ * These are the checks that only mean something once every plugin is wired
+ * together — guards actually mounted, the auth flow actually issuing a cookie.
+ * Anything provable from a single function belongs in a unit test, where it
+ * runs in milliseconds and needs no database.
+ */
+describe('the API', () => {
+    let harness: TestApp;
+
+    beforeAll(async () => {
+        harness = await createTestApp();
+    });
+
+    afterAll(async () => {
+        await closeTestApp(harness);
+    });
+
+    describe('authentication', () => {
+        it('refuses an unauthenticated read', async () => {
+            await request(harness.server).get('/api/workspaces').expect(401);
+        });
+
+        it('signs in the root admin provisioned at boot', async () => {
+            const response = await request(harness.server)
+                .post('/api/auth/login')
+                .set('Origin', ALLOWED_ORIGIN)
+                .send({
+                    email: process.env['ORTHA_ROOT_ADMIN_EMAIL'],
+                    password: process.env['ORTHA_ROOT_ADMIN_PASSWORD']
+                })
+                .expect(201);
+
+            expect(response.headers['set-cookie']).toBeDefined();
+        });
+
+        it('accepts that session on a protected route', async () => {
+            const agent = request.agent(harness.server);
+
+            await agent
+                .post('/api/auth/login')
+                .set('Origin', ALLOWED_ORIGIN)
+                .send({
+                    email: process.env['ORTHA_ROOT_ADMIN_EMAIL'],
+                    password: process.env['ORTHA_ROOT_ADMIN_PASSWORD']
+                })
+                .expect(201);
+
+            await agent.get('/api/workspaces').expect(200);
+        });
+
+        it('rejects a wrong password without saying which half was wrong', async () => {
+            // Distinguishing "no such user" from "wrong password" turns the
+            // login form into an account enumerator.
+            const response = await request(harness.server)
+                .post('/api/auth/login')
+                .set('Origin', ALLOWED_ORIGIN)
+                .send({
+                    email: process.env['ORTHA_ROOT_ADMIN_EMAIL'],
+                    password: 'not-the-password'
+                })
+                .expect(401);
+
+            expect(JSON.stringify(response.body)).not.toMatch(/password|email/i);
+        });
+    });
+
+    describe('routing', () => {
+        it('answers an unknown path with a JSON 404', async () => {
+            const response = await request(harness.server)
+                .get('/api/not-a-real-endpoint')
+                .expect(404);
+
+            expect(response.body).toMatchObject({ statusCode: 404 });
+        });
+    });
+});
+
+/**
+ * The reset helper, proven on the database this suite actually uses.
+ *
+ * Every suite that seeds rows depends on this leaving the schema intact — a
+ * `TRUNCATE` that took the migration history with it would look like a
+ * migration bug in whichever suite ran next.
+ */
+describe('resetDatabase()', () => {
+    it('empties the tables without touching the migration history', async () => {
+        const url = resolveTestDatabaseUrl();
+
+        await expect(resetDatabase(url)).resolves.toBeUndefined();
+
+        // The app still boots, which it could not do against a dropped schema.
+        const harness = await createTestApp();
+        await request(harness.server).get('/api/workspaces').expect(401);
+        await closeTestApp(harness);
+    });
+});

package/templates/default/apps/server-e2e/src/global-setup.ts

@@ -0,0 +1,41 @@
+import {
+    assertDisposable,
+    ensureDatabase,
+    loadDotEnv,
+    resolveTestDatabaseUrl
+} from './support/db';
+
+/**
+ * Creates and migrates the e2e database once for the whole run.
+ *
+ * Migrations go through `applyPluginMigrations` — the same function
+ * `ortha migrate` calls — so the schema under test is the real shipped schema,
+ * applied in the same plugin order. A hand-rolled setup would drift from what
+ * the app does the first time a plugin is added.
+ *
+ * The app's config and plugin list are pulled in with **dynamic** imports, and
+ * that is load-bearing rather than stylistic: `ortha.config.ts` reads
+ * `process.env` at import time and throws without `DATABASE_URL`. A static
+ * import is hoisted above every statement here, so it would run before `.env`
+ * is loaded and before the URL is pointed at the test database — and the whole
+ * suite would fail on a variable that is sitting in a file two lines away.
+ */
+export default async function globalSetup(): Promise<void> {
+    loadDotEnv();
+
+    const url = resolveTestDatabaseUrl();
+    assertDisposable(url);
+    await ensureDatabase(url);
+
+    // Only now is it safe to let the config load.
+    process.env['DATABASE_URL'] = url;
+
+    const [{ applyPluginMigrations }, { default: config }, { buildPlugins }] =
+        await Promise.all([
+            import('@orthacms/cli'),
+            import('../../server/ortha.config'),
+            import('../../server/src/plugins')
+        ]);
+
+    await applyPluginMigrations(buildPlugins(config), url);
+}

package/templates/default/apps/server-e2e/src/jest.setup.ts

@@ -0,0 +1,28 @@
+import { Logger } from '@nestjs/common';
+import { loadDotEnv, resolveTestDatabaseUrl } from './support/db';
+
+/**
+ * Points this worker at the e2e database **before any module loads**.
+ *
+ * `ortha.config.ts` reads `process.env` at import time, so this has to be a
+ * `setupFiles` entry — those run before the module registry is touched, unlike
+ * `setupFilesAfterEnv`. Jest loads no `.env` of its own in a worker either,
+ * hence `loadDotEnv` first.
+ *
+ * Nothing is handed over from `global-setup`: the URL is derived by the same
+ * pure function in both places, so there is no channel to get out of step.
+ */
+loadDotEnv();
+
+process.env['DATABASE_URL'] = resolveTestDatabaseUrl();
+
+// A root admin is provisioned on boot when these are set, which is what gives
+// the suite a real account to sign in with.
+process.env['ORTHA_ROOT_ADMIN_EMAIL'] ||= 'e2e@example.com';
+process.env['ORTHA_ROOT_ADMIN_PASSWORD'] ||= 'e2e-password-not-a-secret';
+
+// `createServer` builds its own Nest app and takes no logger option, so this
+// is the only way to keep a full boot banner — every mapped route, every
+// seeder — out of the output for each suite that boots one. A failing
+// assertion is then the first thing on screen instead of the last.
+Logger.overrideLogger(false);

package/templates/default/apps/server-e2e/src/support/db.ts

@@ -0,0 +1,143 @@
+import { existsSync } from 'node:fs';
+import { Pool } from 'pg';
+
+/**
+ * Loads `.env` into `process.env`.
+ *
+ * Jest loads nothing — not in the main process where `globalSetup` runs, and
+ * not in the workers. `ortha.config.ts` reads `process.env` at import time and
+ * refuses to load without `DATABASE_URL`, so every entry point into this suite
+ * has to call this **before** anything reaches the config.
+ *
+ * Values already exported in the shell win, which is what lets CI set the
+ * database without a file.
+ */
+export function loadDotEnv(): void {
+    if (existsSync('.env') && typeof process.loadEnvFile === 'function') {
+        process.loadEnvFile('.env');
+    }
+}
+
+/**
+ * The database the server e2e suite runs against.
+ *
+ * **Never your development database.** This suite truncates every table
+ * between tests, and `DATABASE_URL` is routinely set in a `.env` pointing at
+ * the database you are actually working in. So the URL is derived into a
+ * separate `<name>_e2e`, and `E2E_DATABASE_URL` overrides it — an opt-in name
+ * that cannot be triggered by accident.
+ */
+const SUFFIX = '_e2e';
+
+export function resolveTestDatabaseUrl(): string {
+    const explicit = process.env['E2E_DATABASE_URL']?.trim();
+    if (explicit) return explicit;
+
+    const base = process.env['DATABASE_URL']?.trim();
+    if (!base) {
+        throw new Error(
+            'Neither E2E_DATABASE_URL nor DATABASE_URL is set — the e2e suite ' +
+                'needs to know which database to create and truncate.'
+        );
+    }
+
+    const url = new URL(base);
+    const database = url.pathname.replace(/^\//, '');
+
+    // **Idempotent.** `global-setup` runs in Jest's main process and points
+    // `DATABASE_URL` at the test database; workers fork from it and inherit
+    // that value, so a naive append derives `app_e2e_e2e` in the worker and
+    // every test then fails against a database nobody created.
+    if (database.endsWith(SUFFIX)) return base;
+
+    url.pathname = `/${database}${SUFFIX}`;
+
+    return url.toString();
+}
+
+/**
+ * Refuses to run against the database `DATABASE_URL` names.
+ *
+ * The derivation above makes a collision unlikely, but `E2E_DATABASE_URL` can
+ * be set to anything — and the first thing this suite does to whatever it is
+ * handed is delete every row. Check before the first `TRUNCATE`, not after.
+ */
+export function assertDisposable(testUrl: string): void {
+    const development = process.env['DATABASE_URL']?.trim();
+
+    if (development && new URL(testUrl).href === new URL(development).href) {
+        throw new Error(
+            'E2E_DATABASE_URL points at the same database as DATABASE_URL. ' +
+                'This suite truncates every table — point it somewhere disposable.'
+        );
+    }
+}
+
+/** Opens a pool against the `postgres` maintenance database on the same host. */
+function maintenancePool(testUrl: string): Pool {
+    const url = new URL(testUrl);
+    const database = url.pathname.replace(/^\//, '');
+    url.pathname = '/postgres';
+
+    return Object.assign(new Pool({ connectionString: url.toString() }), {
+        targetDatabase: database
+    });
+}
+
+/**
+ * Creates the test database if it is not there yet.
+ *
+ * `CREATE DATABASE` cannot run inside a transaction and has no `IF NOT
+ * EXISTS`, so this asks first. Losing the race with another runner is fine —
+ * `42P04` means someone else created it, which is the outcome we wanted.
+ */
+export async function ensureDatabase(testUrl: string): Promise<void> {
+    const pool = maintenancePool(testUrl);
+    const database = (pool as Pool & { targetDatabase: string })
+        .targetDatabase;
+
+    try {
+        const { rowCount } = await pool.query(
+            'SELECT 1 FROM pg_database WHERE datname = $1',
+            [database]
+        );
+        if (rowCount === 0) {
+            // The name comes from our own derivation, not from user input, and
+            // CREATE DATABASE takes no parameters.
+            await pool.query(`CREATE DATABASE "${database}"`);
+        }
+    } catch (error) {
+        if ((error as { code?: string }).code !== '42P04') throw error;
+    } finally {
+        await pool.end();
+    }
+}
+
+/**
+ * Empties every table, leaving the schema and the migration history alone.
+ *
+ * One `TRUNCATE … CASCADE` rather than a delete per table: it ignores foreign
+ * keys, so the suite never has to know which order its own content types
+ * depend on each other in. `RESTART IDENTITY` keeps sequences from drifting
+ * across a run, so an id asserted in one test means the same thing in the next.
+ */
+export async function resetDatabase(testUrl: string): Promise<void> {
+    const pool = new Pool({ connectionString: testUrl });
+
+    try {
+        const { rows } = await pool.query<{ tables: string[] }>(`
+            SELECT array_agg(format('%I.%I', schemaname, tablename)) AS tables
+            FROM pg_tables
+            WHERE schemaname = 'public'
+              AND tablename NOT LIKE '\\_\\_drizzle%'
+        `);
+        const tables = rows[0]?.tables;
+        if (!tables?.length) return;
+
+        await pool.query(
+            `TRUNCATE ${tables.join(', ')} RESTART IDENTITY CASCADE`
+        );
+    } finally {
+        await pool.end();
+    }
+}