create-ortha-app 0.4.0

package/templates/default/apps/admin/vite.config.mts

@@ -0,0 +1,67 @@
+import { resolve } from 'node:path';
+import { defineConfig, loadEnv } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig(({ mode }) => {
+    // This config lives inside the app it builds, so `root` is its own
+    // directory rather than wherever the command was typed — the CLI runs
+    // `vite --config apps/admin/vite.config.mts` from the project root.
+    const root = import.meta.dirname;
+    // The empty prefix is what makes unprefixed keys visible. Nothing here is
+    // inlined into the client bundle — only `import.meta.env` and `define` are.
+    // `.env` lives at the project root, two levels up from this config.
+    const env = {
+        ...loadEnv(mode, resolve(root, '../..'), ''),
+        ...process.env
+    };
+    const adminPort = Number(env['ADMIN_PORT']) || 4200;
+    const apiPort = Number(env['PORT']) || 3000;
+
+    return {
+        root,
+        server: {
+            port: adminPort,
+            // Fail on a taken port rather than drifting to the next free one:
+            // a silently-shifted port either 404s or lands on another app.
+            strictPort: true,
+            // Proxy the API under the admin's own origin, so the session
+            // cookie (httpOnly, SameSite=lax) is first-party in development —
+            // the same single origin `ortha start` gives you in production via
+            // `staticDir`, and the reason neither needs CORS.
+            //
+            // The key is a REGEX ending in a slash, not the bare `/api`
+            // prefix: a plain string key prefix-matches, so `/api` would also
+            // swallow sibling SPA routes whose path merely starts with those
+            // characters (`/api-tokens`) and forward them to the API, which
+            // 404s them on a hard refresh.
+            proxy: {
+                '^/api/': {
+                    target: `http://localhost:${apiPort}`,
+                    changeOrigin: true
+                }
+            }
+        },
+        plugins: [tailwindcss(), react()],
+        build: {
+            // What `staticDir` serves in production — the shared `dist/` at
+            // the project root, not one inside this app.
+            outDir: resolve(root, '../../dist/admin'),
+            emptyOutDir: true
+        },
+        // Unit tests for the **admin** half. Declared here rather than in a
+        // `vitest.config.ts` of its own so the tests resolve modules exactly
+        // the way the app does — same plugins, same aliases, no second config
+        // to keep in step. The server half runs under Jest (`jest.config.js`),
+        // which is what emits the decorator metadata NestJS DI needs.
+        test: {
+            name: 'admin',
+            environment: 'jsdom',
+            globals: true,
+            include: ['src/**/*.{test,spec}.{ts,tsx}'],
+            coverage: {
+                reportsDirectory: resolve(root, '../../test-output/vitest')
+            }
+        }
+    };
+});

package/templates/default/apps/admin-e2e/playwright.config.ts

@@ -0,0 +1,51 @@
+import { resolve } from 'node:path';
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * The project root — two levels up from this app.
+ *
+ * `__dirname`, not `import.meta.dirname`: the app is `"type": "commonjs"` and
+ * Playwright loads a `.ts` config as CommonJS, where `import.meta` is a syntax
+ * error rather than an undefined value — so the failure is the config refusing
+ * to parse, with nothing in it about modules.
+ */
+const projectRoot = resolve(__dirname, '../..');
+
+/**
+ * Admin end-to-end tests — the UI in a browser, against a **mocked** API.
+ *
+ * `webServer` runs the Vite dev server only. Specs intercept `/api` at the
+ * network layer (`src/support/seed.ts`), so a run needs no backend, no
+ * database and no migration: it is fast, hermetic, and when it fails it is the
+ * UI that is wrong. API behaviour is covered by `e2e/server`, where a failure
+ * names the endpoint instead of blaming a page.
+ */
+const adminPort = Number(process.env['ADMIN_PORT']) || 4200;
+
+export default defineConfig({
+    testDir: './src',
+    fullyParallel: true,
+    // A `.only` left in a file passes locally and silently stops running every
+    // other test in CI.
+    forbidOnly: !!process.env['CI'],
+    retries: process.env['CI'] ? 2 : 0,
+    reporter: process.env['CI'] ? 'github' : 'list',
+    use: {
+        baseURL: process.env['BASE_URL'] || `http://localhost:${adminPort}`,
+        // Retained on every failure rather than on a retry: outside CI there
+        // are no retries, so `on-first-retry` collects a trace exactly never —
+        // and a local run is the only post-mortem anyone gets.
+        trace: 'retain-on-failure'
+    },
+    projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+    webServer: {
+        command: `npx vite --config apps/admin/vite.config.mts --port ${adminPort} --strictPort`,
+        // Playwright resolves `cwd` against this config's directory, and the
+        // dev server has to start from the project root or it resolves neither
+        // `node_modules` nor the admin config path above.
+        cwd: projectRoot,
+        url: `http://localhost:${adminPort}`,
+        reuseExistingServer: !process.env['CI'],
+        timeout: 120_000
+    }
+});

package/templates/default/apps/admin-e2e/src/auth.spec.ts

@@ -0,0 +1,55 @@
+import { expect, test } from '@playwright/test';
+import { seedApi, SIGNED_IN_USER } from './support/seed';
+
+/**
+ * The admin, driven in a browser against a mocked API.
+ *
+ * These assert what only a browser can see — that a route renders, that the
+ * gate holds, that the shell mounts. Anything about *what the API returns*
+ * belongs in `e2e/server`.
+ */
+test.describe('the admin shell', () => {
+    test('sends a signed-out visitor to sign in', async ({ page }) => {
+        await seedApi(page);
+
+        await page.goto('/');
+
+        await expect(
+            page.getByRole('textbox', { name: /email/i })
+        ).toBeVisible();
+    });
+
+    test('keeps a signed-out visitor off a private route', async ({ page }) => {
+        await seedApi(page);
+
+        // The gate is the shell's layout composing identity's `RequireAuth`.
+        // If a second plugin ever contributes a layout ahead of the shell's,
+        // this is the test that notices — the page renders, ungated.
+        await page.goto('/workspaces');
+
+        await expect(
+            page.getByRole('textbox', { name: /email/i })
+        ).toBeVisible();
+    });
+
+    test('renders the app shell for a signed-in user', async ({ page }) => {
+        await seedApi(page, { me: SIGNED_IN_USER, workspaces: [] });
+
+        await page.goto('/workspaces');
+
+        // The `<main>` landmark comes from the shell's layout — its presence is
+        // what says the chrome mounted rather than a bare route.
+        await expect(page.getByRole('main')).toBeVisible();
+    });
+
+    test('serves a deep route on a hard refresh', async ({ page }) => {
+        await seedApi(page, { me: SIGNED_IN_USER, workspaces: [] });
+
+        // A client-side route reached by URL rather than by clicking. In
+        // production this is the SPA fallback's job; in dev it is Vite's.
+        // Either way a 404 here means the app is unreachable on refresh.
+        const response = await page.goto('/workspaces/settings');
+
+        expect(response?.status()).toBeLessThan(400);
+    });
+});

package/templates/default/apps/admin-e2e/src/support/seed.ts

@@ -0,0 +1,62 @@
+import type { Page, Route } from '@playwright/test';
+
+/** The API responses a run should answer with. */
+export interface Seed {
+    /** The signed-in user, or `null` for a signed-out session. */
+    me?: unknown;
+    /** Workspaces the sidebar lists. */
+    workspaces?: unknown[];
+    /** Anything else, keyed by path suffix — `'content/article'`. */
+    routes?: Record<string, unknown>;
+}
+
+/**
+ * Mocks `/api` at the network layer.
+ *
+ * The admin e2e suite drives the **UI**, not the stack: it runs against the
+ * Vite dev server with no backend and no database, so a run is fast, hermetic,
+ * and says something specific when it fails. Testing the API through a browser
+ * would be slower and would blame the UI for server bugs — those belong in
+ * `e2e/server`, where a failure names the endpoint.
+ *
+ * Anything not seeded gets a 404, deliberately: a silent empty `200` makes a
+ * page render its empty state and pass, which is exactly the false green this
+ * exists to avoid.
+ */
+export async function seedApi(page: Page, seed: Seed = {}): Promise<void> {
+    const json = (route: Route, body: unknown, status = 200) =>
+        route.fulfill({
+            status,
+            contentType: 'application/json',
+            body: JSON.stringify(body)
+        });
+
+    await page.route('**/api/**', async (route) => {
+        const path = new URL(route.request().url()).pathname.replace(
+            /^\/api\/?/,
+            ''
+        );
+
+        if (path === 'auth/me') {
+            return seed.me
+                ? json(route, seed.me)
+                : json(route, { message: 'Unauthorized' }, 401);
+        }
+        if (path === 'workspaces') {
+            return json(route, { items: seed.workspaces ?? [], total: 0 });
+        }
+
+        const custom = seed.routes?.[path];
+        if (custom !== undefined) return json(route, custom);
+
+        return json(route, { message: `Unmocked: ${path}` }, 404);
+    });
+}
+
+/** A signed-in session, for tests that start past the login screen. */
+export const SIGNED_IN_USER = {
+    id: '00000000-0000-0000-0000-000000000001',
+    email: 'e2e@example.com',
+    name: 'E2E User',
+    permissions: []
+};

package/templates/default/apps/admin-e2e/tsconfig.json

@@ -0,0 +1,23 @@
+{
+    "compilerOptions": {
+        "target": "es2022",
+        "lib": [
+            "es2023",
+            "dom"
+        ],
+        "module": "esnext",
+        "moduleResolution": "bundler",
+        "types": [
+            "node"
+        ],
+        "strict": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "noEmit": true
+    },
+    "include": [
+        "src/**/*.ts",
+        "playwright.config.ts"
+    ]
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Unit tests for the **server** half.
+ *
+ * Jest with `@swc/jest`, not Vitest, and that is not a style choice: the server
+ * is a NestJS app, its DI reads `emitDecoratorMetadata`, and Vitest's esbuild
+ * transform does not emit it — providers resolve as `undefined` with no error
+ * that names the cause. swc emits it, in the same legacy-decorator mode
+ * `tsconfig.server.json` compiles with.
+ *
+ * The admin half runs under Vitest instead (see `apps/admin/vite.config.mts`), because it
+ * is a Vite app and sharing its config is the only way the two agree on how
+ * modules resolve. Two runners, one per half, each matching its own toolchain.
+ */
+module.exports = {
+    displayName: 'server',
+    testEnvironment: 'node',
+    rootDir: '../..',
+    testMatch: ['<rootDir>/apps/server/**/*.spec.ts'],
+    setupFiles: ['<rootDir>/apps/server/jest.setup.js'],
+    transform: {
+        '^.+\\.[tj]s$': [
+            '@swc/jest',
+            {
+                jsc: {
+                    target: 'es2022',
+                    parser: { syntax: 'typescript', decorators: true },
+                    transform: {
+                        legacyDecorator: true,
+                        decoratorMetadata: true
+                    }
+                },
+                module: { type: 'commonjs' }
+            }
+        ]
+    },
+    moduleFileExtensions: ['ts', 'js', 'json'],
+    coverageDirectory: 'test-output/jest'
+};

package/templates/default/apps/server/jest.setup.js

@@ -0,0 +1,20 @@
+/**
+ * Environment for the server unit tests.
+ *
+ * They build the plugin list, which imports `ortha.config.ts` — and that file
+ * deliberately refuses to load without `DATABASE_URL`, because a blank
+ * connection string reaches `pg` as "use the libpq defaults" and migrations
+ * then run against whatever database the local environment happens to name.
+ *
+ * Nothing here connects to anything: the plugin list is a pure function of the
+ * config. So load a real `.env` when there is one, and fall back to
+ * placeholders — which is what lets `npm test` run in CI with no `.env` at all.
+ */
+const { existsSync } = require('node:fs');
+
+if (existsSync('.env') && typeof process.loadEnvFile === 'function') {
+    process.loadEnvFile('.env');
+}
+
+process.env.DATABASE_URL ||=
+    'postgresql://ortha:ortha@localhost:5432/placeholder';