create-ortha-app 0.4.0

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

@@ -0,0 +1,64 @@
+import type { NestExpressApplication } from '@nestjs/platform-express';
+import { createServer } from '@orthacms/bootstrap-server';
+import { closeDatabase } from '@orthacms/database';
+import type { Server } from 'node:http';
+import config from '../../../server/ortha.config';
+import { buildPlugins } from '../../../server/src/plugins';
+
+/**
+ * An origin the login route accepts.
+ *
+ * Login is guarded against cross-site POSTs by an allow-list, so a request
+ * with no `Origin` — or the wrong one — is refused with `403` before the
+ * credentials are ever looked at. Read from the config rather than hardcoded:
+ * the list follows `ADMIN_PORT`, so a hardcoded `:4200` fails on any app whose
+ * admin runs somewhere else, and fails as a confusing `403` rather than
+ * "wrong origin".
+ */
+export const ALLOWED_ORIGIN =
+    config.plugins.identity.allowedOrigins?.[0] ?? 'http://localhost:4200';
+
+/** A booted app plus the raw server to hand to supertest. */
+export interface TestApp {
+    app: NestExpressApplication;
+    server: Server;
+}
+
+/**
+ * Boots **this app** — the real `buildPlugins`, the real config — on an
+ * ephemeral port.
+ *
+ * Deliberately `createServer` rather than a hand-assembled Nest app: a harness
+ * that mirrors the bootstrap can never fail on a bootstrap defect, and this
+ * suite exists to catch exactly the things that only appear once everything is
+ * wired together. Port `0` keeps parallel runs from colliding; supertest is
+ * handed the server object, so nothing depends on the number.
+ *
+ * `createServer` also runs the `OnApplicationBootstrap` seeders, so the system
+ * roles and the root admin from `.env.e2e` exist by the time a test runs.
+ */
+export async function createTestApp(): Promise<TestApp> {
+    const app = await createServer({
+        plugins: buildPlugins(config),
+        port: 0,
+        globalPrefix: config.globalPrefix,
+        bodyLimit: config.bodyLimit,
+        // The reference is developer tooling and adds a route surface these
+        // tests do not describe. Off, whatever the environment says.
+        docs: { ...config.docs, enabled: false }
+    });
+
+    return { app, server: app.getHttpServer() as Server };
+}
+
+/**
+ * Closes the app and the database pool.
+ *
+ * `app.close()` does not end the pool — nothing binds a shutdown hook to it —
+ * so without `closeDatabase` the Jest worker stays alive on an open handle and
+ * the run hangs after the last assertion passes.
+ */
+export async function closeTestApp(harness: TestApp): Promise<void> {
+    await harness.app.close();
+    await closeDatabase();
+}

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

@@ -0,0 +1,26 @@
+{
+    "compilerOptions": {
+        "target": "es2022",
+        "lib": [
+            "es2023"
+        ],
+        "module": "commonjs",
+        "moduleResolution": "node",
+        "types": [
+            "node",
+            "jest"
+        ],
+        "strict": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true,
+        "noEmit": true
+    },
+    "include": [
+        "src/**/*.ts",
+        "jest.config.js"
+    ]
+}

package/templates/default/docker-compose.yml

@@ -0,0 +1,21 @@
+# Postgres for local development. `docker compose up -d`, then `npm run migrate`.
+services:
+    postgres:
+        image: postgres:17-alpine
+        restart: unless-stopped
+        environment:
+            POSTGRES_USER: ortha
+            POSTGRES_PASSWORD: ortha
+            POSTGRES_DB: __DATABASE_NAME__
+        ports:
+            - '5432:5432'
+        volumes:
+            - postgres-data:/var/lib/postgresql/data
+        healthcheck:
+            test: ['CMD-SHELL', 'pg_isready -U ortha']
+            interval: 5s
+            timeout: 5s
+            retries: 10
+
+volumes:
+    postgres-data:

package/templates/default/env.tmpl

@@ -0,0 +1,140 @@
+# Port the API listens on. `ortha start` serves the admin from here too.
+PORT=3000
+# Port the Vite dev server listens on (development only).
+ADMIN_PORT=4200
+
+# PostgreSQL connection string.
+DATABASE_URL=__DATABASE_URL__
+
+# How many reverse proxies sit in front of the app (Express `trust proxy`).
+# REQUIRED behind a load balancer, ingress or CDN: left unset, Express ignores
+# X-Forwarded-For, every request reports the proxy's address, and the login
+# rate limit collapses into ONE bucket for the whole deployment. Prefer the hop
+# count (1 for a single proxy) — a client cannot forge past it.
+TRUST_PROXY=
+
+# Serve the API reference on /reference. On outside production by default.
+API_DOCS=
+
+# Largest JSON request body the API accepts. Defaults to 1mb.
+MAX_REQUEST_BODY=
+
+# --- media ---
+# ortha:if media-local
+# Where uploads are written. Point this at a persistent volume in production:
+# a container's own disk is wiped on every deploy.
+MEDIA_LOCAL_ROOT=./.storage/media
+# ortha:end
+# ortha:if media-vercel-blob
+# Vercel injects this on its own platform; set it only when running elsewhere.
+# NOTE: every blob in this store gets a permanent, public URL — anyone who
+# obtains one can fetch that asset without signing in. Do not pick this backend
+# for confidential media.
+BLOB_READ_WRITE_TOKEN=
+# ortha:end
+# ortha:if media-gcs
+# The bucket every upload lands in. Required.
+MEDIA_GCS_BUCKET=
+# Leave the rest blank on GKE or Cloud Run: the client falls back to
+# Application Default Credentials, which is the point of using this adapter
+# instead of the S3-compatible one.
+MEDIA_GCS_PROJECT_ID=
+MEDIA_GCS_KEY_FILE=
+# Sign URLs through IAM instead of a private key (Workload Identity). Needs
+# the iam.serviceAccounts.signBlob permission.
+MEDIA_GCS_SIGN_WITH_IAM=false
+# ortha:end
+# ortha:if media-azure
+# The container every upload lands in, and how to reach the account. The portal
+# hands you the connection string; Azurite prints one too. For managed identity,
+# build the container client yourself in plugins.ts — see the package docs.
+MEDIA_AZURE_CONTAINER=media
+MEDIA_AZURE_CONNECTION_STRING=
+# ortha:end
+# ortha:if media-s3
+# The bucket every upload lands in. Required.
+MEDIA_S3_BUCKET=
+# Leave the endpoint blank for AWS S3 itself. For anything else, set it:
+#   Cloudflare R2  https://<account>.r2.cloudflarestorage.com
+#   MinIO          http://localhost:9000   (also set FORCE_PATH_STYLE=true)
+MEDIA_S3_ENDPOINT=
+MEDIA_S3_REGION=auto
+MEDIA_S3_FORCE_PATH_STYLE=false
+# Leave both blank on a host with an instance role or IRSA — the SDK finds
+# those itself, and blanks here would shadow them with keys that cannot sign.
+MEDIA_S3_ACCESS_KEY_ID=
+MEDIA_S3_SECRET_ACCESS_KEY=
+# ortha:end
+MEDIA_MAX_UPLOAD_BYTES=52428800
+
+# --- first admin ---
+# With an email set, an active admin is provisioned on boot — idempotent and
+# non-destructive, so an existing account is left alone. This is how you get
+# your first login; clear it once you have one.
+ORTHA_ROOT_ADMIN_EMAIL=__ADMIN_EMAIL__
+ORTHA_ROOT_ADMIN_PASSWORD=__ADMIN_PASSWORD__
+
+# --- copilot ---
+# Global kill switch. OFF by default: enabling a hosted provider sends workspace
+# content to a third party, so an operator opts in explicitly.
+COPILOT_ENABLED=false
+# Ceiling on a single model response, in tokens.
+COPILOT_MAX_OUTPUT_TOKENS=8192
+# ortha:if copilot-anthropic
+# Native Claude. 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. The key never leaves the server.
+ANTHROPIC_API_KEY=
+# Comma-separated. The FIRST is the default; the rest are what a user can switch
+# to mid-conversation without a redeploy.
+COPILOT_ANTHROPIC_MODELS=claude-sonnet-5
+# ortha:end
+# ortha:if copilot-openai
+# An OpenAI-wire endpoint. Setting this REGISTERS the backend, and there is no
+# default: an endpoint nobody named is a backend that can only time out. A local
+# Ollama is http://localhost:11434/v1.
+COPILOT_OPENAI_BASE_URL=
+COPILOT_OPENAI_MODELS=llama3.1
+# Leave empty for a local runtime that wants no auth.
+COPILOT_OPENAI_API_KEY=
+# ortha:end
+# ortha:if mcp
+# --- mcp ---
+# Global kill switch. OFF by default: once on, any holder of a `full`-scope API
+# token can drive content CRUD from an external agent. Agents connect to
+# POST /api/v1/mcp with `Authorization: Bearer <token>`.
+MCP_ENABLED=false
+# Ceiling on one tools/call, in milliseconds. Defaults to 30000.
+MCP_CALL_TIMEOUT_MS=
+# Ceiling on one tool result, in bytes. Defaults to 4194304 (4 MB).
+MCP_MAX_RESULT_BYTES=
+# ortha:end
+
+# --- single sign-on ---
+# ortha:if sso-oidc
+# Generic OpenID Connect — Okta, Auth0, Keycloak, Google, Entra ID and the rest.
+# Both of these are what make the provider configured at all: an issuer with no
+# client id is a sign-in button that can only fail.
+#
+# The issuer must match the `iss` claim byte for byte, trailing slash included
+# (Auth0 issues with one). Register
+# <origin>/api/auth/sso/<SSO_OIDC_NAME>/callback with the provider.
+SSO_OIDC_ISSUER=
+SSO_OIDC_CLIENT_ID=
+SSO_OIDC_CLIENT_SECRET=
+# What the route and every sso_identities row call this provider. Renaming it
+# orphans the links that name it. Default: oidc
+SSO_OIDC_NAME=
+# The sign-in button's text. Defaults to the issuer's host.
+SSO_OIDC_LABEL=
+# Set to true ONLY if your provider never sends `email_verified` and you are
+# asserting that this directory owns the addresses it reports (Microsoft Entra
+# ID is the common case). That claim is the only gate on a first sign-in
+# claiming an existing account.
+SSO_OIDC_EMAIL_VERIFIED_WHEN_ABSENT=
+# ortha:end
+# The origin browsers reach the API on, when the admin is served from a
+# different one. Leave empty for the usual same-origin deployment.
+SSO_PUBLIC_BASE_URL=
+# How long one sign-in attempt stays live, in seconds. Default 600.
+SSO_REQUEST_TTL_SECONDS=

package/templates/default/package.json.tmpl

@@ -0,0 +1,51 @@
+{
+    "name": "__APP_NAME__",
+    "version": "0.1.0",
+    "private": true,
+    "type": "commonjs",
+    "scripts": {
+        "dev": "ortha dev",
+        "build": "ortha build",
+        "start": "ortha start",
+        "migrate": "ortha migrate",
+        "generate": "ortha generate",
+        "studio": "ortha studio",
+        "test": "npm run test:server && npm run test:admin",
+        "test:server": "jest --config apps/server/jest.config.js",
+        "test:admin": "vitest run --config apps/admin/vite.config.mts",
+        "e2e": "npm run e2e:server && npm run e2e:admin",
+        "typecheck": "tsc --build tsconfig.json",
+        "e2e:server": "jest --config apps/server-e2e/jest.config.js",
+        "e2e:admin": "playwright test --config apps/admin-e2e/playwright.config.ts"
+    },
+    "dependencies": {
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
+        "react-router-dom": "6.30.3",
+        "reflect-metadata": "^0.1.13",
+        "rxjs": "^7.8.0"
+    },
+    "devDependencies": {
+        "@playwright/test": "^1.36.0",
+        "@swc/core": "~1.15.5",
+        "@swc/jest": "~0.2.38",
+        "@tailwindcss/vite": "^4.3.0",
+        "@testing-library/dom": "10.4.0",
+        "@testing-library/react": "16.3.0",
+        "@types/jest": "~30.0.0",
+        "@types/node": "^20.19.9",
+        "@types/pg": "^8.11.0",
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "@types/supertest": "^6.0.0",
+        "@vitejs/plugin-react": "^6.0.0",
+        "jest": "~30.3.0",
+        "jsdom": "~22.1.0",
+        "pg": "^8.13.0",
+        "supertest": "^7.0.0",
+        "tailwindcss": "^4.3.0",
+        "typescript": "~5.9.2",
+        "vite": "^8.0.0",
+        "vitest": "~4.1.0"
+    }
+}

package/templates/default/tsconfig.json

@@ -0,0 +1,18 @@
+{
+    "files": [],
+    "include": [],
+    "references": [
+        {
+            "path": "./apps/server"
+        },
+        {
+            "path": "./apps/admin"
+        },
+        {
+            "path": "./apps/server-e2e"
+        },
+        {
+            "path": "./apps/admin-e2e"
+        }
+    ]
+}