create-kelpie 0.5.2 → 0.7.0

package/dist/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,wEAAwE;AACxE,qBAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AA4DD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAkBtD;AAED,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,MAAM,EAAE,CAsBpE"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,wEAAwE;AACxE,qBAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AA6DD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAkBtD;AAED,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,MAAM,EAAE,CAsBpE"}

package/dist/scaffold.js

@@ -29,6 +29,7 @@ const TEMPLATE_FILES = new Map([
     ['kelpie.config.ts', 'kelpie.config.ts'],
     ['kelpie.ui.config.ts', 'kelpie.ui.config.ts'],
     ['src/server.ts', 'src/server.ts'],
+    ['src/migrate.ts', 'src/migrate.ts'],
     ['src/reseal.ts', 'src/reseal.ts'],
     ['web/index.html', 'web/index.html'],
     ['web/main.tsx', 'web/main.tsx'],

package/dist/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kelpie",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Scaffold a self-hosted Kelpie assembly. Run it with npm create kelpie.",
   "keywords": [
     "kelpie",

package/src/scaffold.ts

@@ -50,6 +50,7 @@ const TEMPLATE_FILES: ReadonlyMap<string, string> = new Map([
   ['kelpie.config.ts', 'kelpie.config.ts'],
   ['kelpie.ui.config.ts', 'kelpie.ui.config.ts'],
   ['src/server.ts', 'src/server.ts'],
+  ['src/migrate.ts', 'src/migrate.ts'],
   ['src/reseal.ts', 'src/reseal.ts'],
   ['web/index.html', 'web/index.html'],
   ['web/main.tsx', 'web/main.tsx'],

package/templates/README.md

@@ -40,10 +40,15 @@ Then open <http://localhost:__WEB_PORT__/signup> and create an account.
 Passwords need at least 12 characters. Signup names your workspace, invites your
 team, and leaves you on People with a starter handbook in place.
 
-This default configuration doesn't send email. `EMAIL_PROVIDER=log` prints
-invitation and password-reset links to the API's log instead of mailing them;
-copy them from there to follow either flow. Set `EMAIL_PROVIDER=smtp` below to
-send them for real.
+This install picks its transactional-mail sender through `EMAIL_PROVIDER` in
+`.env`. Out of the box it is `log`, which writes invitation and password-reset
+messages to the API's log instead of sending them; copy the link from there
+to follow either flow locally. Set `EMAIL_PROVIDER=smtp` and fill in the
+`SMTP_*` variables below to send them over SMTP through the built-in
+`smtp-email` core module (no install needed). Other provider modules
+(Resend, Postmark, …) register their own name; install one, add it to
+`kelpie.config.ts`'s `modules:`, and set `EMAIL_PROVIDER` to that name to
+use it instead.
 
 ## Adding a module
 
@@ -66,13 +71,13 @@ lists every problem at once.
 | `DATABASE_URL` | A `postgres://` or `postgresql://` connection string |
 | `APP_BASE_URL` | The address people reach this Kelpie on. Emailed links (verification, password reset, invitations) are built from it. In development that is the Vite dev server; a deployment sets its real origin |
 | `LOG_LEVEL` | `debug`, `info`, `warn`, or `error` |
-| `EMAIL_PROVIDER` | `log` or `smtp`. `log` writes invitations and resets to the log instead of sending them |
+| `EMAIL_PROVIDER` | Name of the transactional-mail sender to use. `log` (built in) writes to the log instead of sending; `smtp` sends over SMTP through the built-in `smtp-email` core module; other names come from third-party provider modules |
 | `EMAIL_FROM` | The address transactional mail comes from |
-| `SMTP_HOST` | Required when `EMAIL_PROVIDER=smtp`. The mail server to connect to |
-| `SMTP_PORT` | Required when `EMAIL_PROVIDER=smtp`. The mail server's port |
-| `SMTP_SECURE` | Required when `EMAIL_PROVIDER=smtp`. `true` or `false`. Whether to connect over TLS from the start (typically port 465) rather than upgrading with STARTTLS (typically port 587 or 25) |
-| `SMTP_USER` | Required when `EMAIL_PROVIDER=smtp`. The SMTP username |
-| `SMTP_PASSWORD` | Required when `EMAIL_PROVIDER=smtp`. The SMTP password |
+| `SMTP_HOST` | Read by the built-in `smtp-email` module when `EMAIL_PROVIDER=smtp`. The mail server to connect to |
+| `SMTP_PORT` | Read by the built-in `smtp-email` module when `EMAIL_PROVIDER=smtp`. The mail server's port |
+| `SMTP_SECURE` | Read by the built-in `smtp-email` module when `EMAIL_PROVIDER=smtp`. `true` or `false`. Whether to connect over TLS from the start (typically port 465) rather than upgrading with STARTTLS (typically port 587 or 25) |
+| `SMTP_USER` | Read by the built-in `smtp-email` module when `EMAIL_PROVIDER=smtp`. The SMTP username |
+| `SMTP_PASSWORD` | Read by the built-in `smtp-email` module when `EMAIL_PROVIDER=smtp`. The SMTP password |
 | `SECRET_ENCRYPTION_KEY` | 32 bytes of base64, generated for this project |
 | `SECRET_ENCRYPTION_KEY_PREVIOUS` | Optional. Set only while rotating the key above |
 | `WEBHOOK_DELIVERY_RETENTION_DAYS` | Optional, default 30 |
@@ -112,7 +117,8 @@ One process now serves the pages and the API on `PORT`. Boot fails if
 stops rather than answering every browser with a blank page.
 
 Migrations apply at boot. Running more than one instance makes that a race, so
-migrate once in a release step and start the instances with `--no-migrate`.
+migrate once with `npm run migrate` in a release step, then start the instances
+with `--no-migrate`. That command is forward-only and safe to re-run.
 
 ## Upgrading
 

package/templates/env

@@ -26,17 +26,22 @@ APP_BASE_URL=http://localhost:__WEB_PORT__
 # changing it needs the rotation procedure in README.md.
 SECRET_ENCRYPTION_KEY=__SECRET_ENCRYPTION_KEY__
 
-# `log` writes invitations and password resets to the log instead of sending
-# them. `smtp` sends for real, through the server and credentials below.
+# EMAIL_PROVIDER picks a named sender the runtime resolves. `log` is a
+# built-in that writes messages to the log instead of sending them; `smtp`
+# comes from `@kelpie/module-smtp-email`, which reads the SMTP variables
+# below. A different provider module (Resend, Postmark, …) registers its
+# own name — set EMAIL_PROVIDER to that name to use it.
 EMAIL_PROVIDER=log
 EMAIL_FROM=__EMAIL_FROM__
 
-# Required only when EMAIL_PROVIDER=smtp; ignored otherwise. SMTP_SECURE is
-# "true" for a server that expects TLS from the first byte (usually port 465),
-# "false" for one you connect to in plain text and that upgrades with STARTTLS
-# (usually port 587 or 25).
-# SMTP_HOST=smtp.example.com
-# SMTP_PORT=587
-# SMTP_SECURE=false
-# SMTP_USER=
-# SMTP_PASSWORD=
+# Read by `@kelpie/module-smtp-email` when EMAIL_PROVIDER=smtp. Ignored
+# otherwise.
+#
+# SMTP_SECURE is "true" for a server that expects TLS from the first byte
+# (usually port 465), "false" for one you connect to in plain text and that
+# upgrades with STARTTLS (usually port 587 or 25).
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=
+SMTP_PASSWORD=

package/templates/kelpie.config.ts

@@ -1,21 +1,118 @@
-import { coreModules } from '@kelpie/server'
-import type { KelpieModule } from '@kelpie/server'
+import {
+  appUrlConfigSchema,
+  coreModules,
+  defineKelpieConfig,
+  fromEnv,
+  secretEncryptionConfigSchema,
+} from '@kelpie/server'
+import { z } from 'zod'
 
 /**
- * The server module list, and the only place it is declared.
+ * Your Kelpie service's configuration, and the only place it is declared.
  *
- * Boot registers these in order, after resolving what each one requires. An
- * unknown id, an unmet dependency, or invalid module configuration stops boot
- * rather than starting a service that is missing a feature.
+ * Every leaf is either a literal, committed to git and locked in for this
+ * deployment, or `fromEnv(...)`, marking a leaf the environment fills in. Edit
+ * this file for anything that should not change per deploy, and set environment
+ * variables (in `.env`, `.env.local`, or your process manager) for anything
+ * that does (secrets, per-tier limits, per-environment URLs).
  *
- * Add a module by installing it and putting it in this array:
+ * `resolveKelpieConfig(config, process.env)` at boot walks this object,
+ * resolves markers, validates, and produces the typed `KelpieConfig` the app
+ * runs on. Nothing in the app reads `process.env` for these fields after boot.
  *
- *   import { smtpEmail } from '@kelpie/module-smtp-email'
- *
- *   export const modules: readonly KelpieModule[] = [...coreModules, smtpEmail]
- *
- * Removing one from `coreModules` is possible too, but core modules depend on
- * each other, so boot will tell you if you have taken out something another
- * module needs.
+ * Add a module by installing it and putting it in the `modules` array below.
+ * `coreModules` already includes the built-in `smtp-email` module; set
+ * `EMAIL_PROVIDER=log` to fall back to the log sender.
  */
-export const modules: readonly KelpieModule[] = [...coreModules]
+
+const runtimeMode = z.enum(['development', 'test', 'production'])
+const logLevel = z.enum(['debug', 'info', 'warn', 'error'])
+const positiveInt = z.coerce.number().int().positive()
+const nonNegativeInt = z.coerce.number().int().nonnegative()
+const port = positiveInt.max(65535)
+const postgresUrl = z.string().refine(
+  (value) => {
+    try {
+      const { protocol } = new URL(value)
+      return protocol === 'postgres:' || protocol === 'postgresql:'
+    } catch {
+      return false
+    }
+  },
+  { message: 'must be a postgres:// or postgresql:// connection string' },
+)
+
+export default defineKelpieConfig({
+  runtimeMode: fromEnv('NODE_ENV', runtimeMode),
+  port: fromEnv('PORT', port),
+  databaseUrl: fromEnv('DATABASE_URL', postgresUrl),
+
+  // Every log line writes to each entry in `destinations`. Stdout is the
+  // default. Add a destination by extending the `LoggingDestination` union in
+  // `@kelpie/server` and placing an entry here.
+  logging: {
+    level: fromEnv('LOG_LEVEL', logLevel),
+    destinations: [{ kind: 'stdout' }],
+  },
+
+  webBundleDirectory: fromEnv<string | undefined>('WEB_BUNDLE_DIR', z.string().min(1).optional(), undefined),
+  moduleConfigPath: fromEnv<string | undefined>('KELPIE_MODULE_CONFIG_PATH', z.string().min(1).optional(), undefined),
+  // A human-readable name for this install ("dev", "demo", "cloud"). Read by
+  // the browser through `GET /v1/public/config` and shown at the top of the
+  // UI on non-production runs.
+  siteName: fromEnv<string | undefined>('KELPIE_SITE_NAME', z.string().min(1).optional(), undefined),
+  trustedProxyHopCount: fromEnv('TRUSTED_PROXY_HOP_COUNT', nonNegativeInt, 0),
+
+  // The deployment's base URL. Every emailed link (invite, password reset,
+  // email verification) is built from it.
+  appBaseUrl: fromEnv('APP_BASE_URL', appUrlConfigSchema.shape.APP_BASE_URL),
+
+  // Keys that seal stored secrets. Generate one with:
+  //   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+  // To rotate, set the current key as `previousKey`, put the new key here,
+  // deploy, then run `npm run reseal`.
+  secretEncryption: {
+    key: fromEnv('SECRET_ENCRYPTION_KEY', secretEncryptionConfigSchema.shape.SECRET_ENCRYPTION_KEY),
+    previousKey: fromEnv<string | undefined>(
+      'SECRET_ENCRYPTION_KEY_PREVIOUS',
+      secretEncryptionConfigSchema.shape.SECRET_ENCRYPTION_KEY_PREVIOUS,
+      undefined,
+    ),
+  },
+
+  // `provider` picks a named sender from the runtime's registry: `'log'` is
+  // built in and writes the message to the log instead of sending it. `'smtp'`
+  // is registered by the built-in `smtp-email` core module and reads the
+  // `SMTP_*` variables at boot when it is picked. Other names come from
+  // third-party provider modules (Resend, Postmark) added to `modules` below.
+  // `from` is the address on every outgoing message.
+  email: {
+    provider: fromEnv('EMAIL_PROVIDER', z.string().min(1)),
+    from: fromEnv('EMAIL_FROM', z.string().min(1)),
+  },
+
+  rateLimit: {
+    forms: {
+      limit: fromEnv('RATE_LIMIT_FORMS_LIMIT', positiveInt, 20),
+      windowSeconds: fromEnv('RATE_LIMIT_FORMS_WINDOW_SECONDS', positiveInt, 60),
+    },
+    auth: {
+      limit: fromEnv('RATE_LIMIT_AUTH_LIMIT', positiveInt, 10),
+      windowSeconds: fromEnv('RATE_LIMIT_AUTH_WINDOW_SECONDS', positiveInt, 60),
+    },
+    loginAccount: {
+      limit: fromEnv('RATE_LIMIT_LOGIN_ACCOUNT_LIMIT', positiveInt, 10),
+      windowSeconds: fromEnv('RATE_LIMIT_LOGIN_ACCOUNT_WINDOW_SECONDS', positiveInt, 900),
+    },
+    api: {
+      limit: fromEnv('RATE_LIMIT_API_LIMIT', positiveInt, 600),
+      windowSeconds: fromEnv('RATE_LIMIT_API_WINDOW_SECONDS', positiveInt, 60),
+    },
+  },
+
+  // `coreModules` already includes the built-in `smtp-email` module, which
+  // registers a `'smtp'` provider. Set `EMAIL_PROVIDER=log` to fall back to
+  // the built-in log sender; the `smtp-email` module only reads the SMTP
+  // environment when `email.provider` picks its name.
+  modules: [...coreModules],
+})

package/templates/package.json

@@ -11,6 +11,7 @@
     "dev:api": "node --watch --env-file-if-exists=.env src/server.ts",
     "dev:web": "vite",
     "start": "node --env-file-if-exists=.env src/server.ts",
+    "migrate": "node --env-file-if-exists=.env src/migrate.ts",
     "reseal": "node --env-file-if-exists=.env src/reseal.ts",
     "build": "vite build",
     "typecheck": "tsc --project tsconfig.server.json && tsc --project tsconfig.web.json"

package/templates/src/migrate.ts

@@ -0,0 +1,59 @@
+import {
+  ConfigurationError,
+  ModuleBootError,
+  ModuleConfigFileError,
+  bootAssembly,
+  runMigrations,
+} from '@kelpie/server'
+
+import kelpieConfig from '../kelpie.config.ts'
+
+/**
+ * Applies every pending migration, then exits.
+ *
+ * This is the release step `--no-migrate` expects: run it once before starting
+ * instances that skip boot-time migration, so applying migrations is not a race
+ * between them. Registration runs first, because modules declare their
+ * migrations directory while registering and there is nothing to migrate until
+ * that pass has finished. Migrations are forward-only and safe to re-run; a
+ * second run is a no-op.
+ */
+
+function reportFatal(message: string): void {
+  process.stderr.write(`${message}\n`)
+}
+
+async function migrate(): Promise<void> {
+  const { database, contributions, logger } = await bootAssembly(kelpieConfig, process.env)
+
+  try {
+    await runMigrations(database.db, contributions.schemas, logger)
+  } finally {
+    await database.close()
+  }
+}
+
+try {
+  await migrate()
+  process.exit(0)
+} catch (error: unknown) {
+  if (error instanceof ConfigurationError) {
+    reportFatal(error.message)
+    reportFatal('Check .env against the table in README.md.')
+    process.exit(1)
+  }
+
+  if (error instanceof ModuleConfigFileError) {
+    reportFatal(error.message)
+    reportFatal('Fix the file at KELPIE_MODULE_CONFIG_PATH, or unset it to let workspaces decide for themselves.')
+    process.exit(1)
+  }
+
+  if (error instanceof ModuleBootError) {
+    reportFatal(error.message)
+    reportFatal('Fix the module list in kelpie.config.ts, or the configuration it needs.')
+    process.exit(1)
+  }
+
+  throw error
+}

package/templates/src/reseal.ts

@@ -1,101 +1,33 @@
 import {
   ConfigurationError,
-  connectDatabase,
   createLogger,
-  createSecretCipher,
-  loadConfig,
-  resealStoredSecrets,
-  secretEncryptionConfigSchema,
+  createTransportForDestination,
+  resolveKelpieConfig,
+  runReseal,
 } from '@kelpie/server'
 
+import kelpieConfig from '../kelpie.config.ts'
+
 /**
  * Re-seals stored secrets after `SECRET_ENCRYPTION_KEY` changes.
  *
- * The rotation procedure, in full:
- *
- *   1. Keep the current key. Add the new one as `SECRET_ENCRYPTION_KEY` and move
- *      the old value to `SECRET_ENCRYPTION_KEY_PREVIOUS`.
- *   2. Deploy. Deliveries keep signing: new secrets seal under the new key, and
- *      existing ones still open under the previous one.
- *   3. Run `npm run reseal`. It rewrites every row still sealed under the old key.
- *   4. Remove `SECRET_ENCRYPTION_KEY_PREVIOUS` and deploy again.
- *
- * Safe to run at any point, including with no previous key set, where it reports
- * that everything is already current and writes nothing.
- *
- * A script rather than a subcommand because the repository has no CLI surface
- * yet. When self-host packaging adds one, this becomes a subcommand of it and
- * the body moves across unchanged.
+ * The rotation procedure lives on `runReseal`'s JSDoc; this file only wires
+ * the assembly's config in and hands `ConfigurationError` a fix hint on the
+ * way out. A future `kelpie` CLI turns this into a subcommand and the body
+ * stays the same size.
  */
 
-function report(message: string): void {
-  process.stdout.write(`${message}\n`)
-}
-
 function reportFatal(message: string): void {
   process.stderr.write(`${message}\n`)
 }
 
-async function reseal(): Promise<number> {
-  const config = loadConfig(process.env)
-  const logger = createLogger(config.logLevel)
-  const database = connectDatabase(config.databaseUrl, logger)
-
-  // Validated here rather than trusted, so a mistyped key fails before the pass
-  // opens a single row instead of reporting every row unreadable.
-  const secretConfig = secretEncryptionConfigSchema.safeParse(process.env)
-
-  if (!secretConfig.success) {
-    await database.close()
-
-    throw new ConfigurationError(
-      secretConfig.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`),
-    )
-  }
-
-  const hasPrevious =
-    secretConfig.data.SECRET_ENCRYPTION_KEY_PREVIOUS !== undefined &&
-    secretConfig.data.SECRET_ENCRYPTION_KEY_PREVIOUS.trim().length > 0
-
-  if (!hasPrevious) {
-    report('SECRET_ENCRYPTION_KEY_PREVIOUS is not set. Nothing sealed under an older key can be read.')
-  }
-
-  try {
-    const outcome = await resealStoredSecrets(database.db, createSecretCipher(secretConfig.data))
-
-    for (const column of outcome.columns) {
-      report(
-        `${column.label}: ${String(column.examined)} examined, ${String(column.resealed)} re-sealed, ${String(column.unreadable.length)} unreadable`,
-      )
-
-      for (const id of column.unreadable) {
-        reportFatal(`  unreadable: ${id}`)
-      }
-    }
-
-    if (outcome.unreadable > 0) {
-      reportFatal(
-        `\n${String(outcome.unreadable)} value(s) opened under neither key. They were sealed under a key that is not configured, or the rows have been altered. Nothing here can recover them: set SECRET_ENCRYPTION_KEY_PREVIOUS to the key they were sealed with and run this again, or have those records re-created.`,
-      )
-
-      return 1
-    }
-
-    report(
-      outcome.resealed === 0
-        ? `\nNothing to do: all ${String(outcome.examined)} value(s) are already sealed under the current key.`
-        : `\nRe-sealed ${String(outcome.resealed)} of ${String(outcome.examined)} value(s). You can now remove SECRET_ENCRYPTION_KEY_PREVIOUS.`,
-    )
-
-    return 0
-  } finally {
-    await database.close()
-  }
-}
-
 try {
-  process.exit(await reseal())
+  const config = resolveKelpieConfig(kelpieConfig, process.env)
+  const logger = createLogger({
+    level: config.logging.level,
+    transports: config.logging.destinations.map(createTransportForDestination),
+  })
+  process.exit(await runReseal({ config, logger }))
 } catch (error: unknown) {
   if (error instanceof ConfigurationError) {
     reportFatal(error.message)

package/templates/src/server.ts

@@ -5,35 +5,26 @@ import {
   ModuleBootError,
   ModuleConfigFileError,
   WebBundleError,
-  connectDatabase,
+  bootAssembly,
   createApp,
-  createEmailSender,
-  createEventBus,
-  createIdFactory,
-  createLogger,
-  createTransactionScope,
-  loadConfig,
-  readModuleConfigFile,
-  registerModules,
-  resolveActorFrom,
   resolveClientIpFrom,
   runMigrations,
   serveWebBundle,
 } from '@kelpie/server'
-import type { CredentialDependencies } from '@kelpie/server'
 
-import { modules } from '../kelpie.config.ts'
+import kelpieConfig from '../kelpie.config.ts'
 
 /**
  * The entry point. It reads the environment, registers the configured modules,
  * applies migrations, wires the dependencies, and serves.
  *
- * Registration runs before migrations. Modules declare their migrations
- * directory while registering, so there is nothing to migrate until that pass
- * has finished.
+ * The config, database, and registration pass come from `bootAssembly`, shared
+ * with the standalone `migrate` command. Registration runs before migrations:
+ * modules declare their migrations directory while registering, so there is
+ * nothing to migrate until that pass has finished.
  *
- * `--no-migrate` skips the migration step, for deployments where one release
- * step migrates and many instances then start.
+ * `--no-migrate` skips the migration step, for deployments where `npm run migrate`
+ * migrates once in a release step and many instances then start.
  */
 
 function reportFatal(message: string): void {
@@ -41,28 +32,10 @@ function reportFatal(message: string): void {
 }
 
 async function start(): Promise<void> {
-  const config = loadConfig(process.env)
-  const logger = createLogger(config.logLevel)
-  const database = connectDatabase(config.databaseUrl, logger)
-  const events = createEventBus(logger)
-  const createId = createIdFactory()
-  const credentials: CredentialDependencies = { db: database.db, now: () => new Date() }
-  const moduleConfig = readModuleConfigFile(config.moduleConfigPath)
-  const contributions = await registerModules({
-    modules,
-    environment: process.env,
-    logger,
-    events,
-    moduleConfig,
-    resolveActor: (context) => resolveActorFrom(credentials, context),
-    services: {
-      db: database.db,
-      transaction: createTransactionScope({ db: database.db, bus: events, logger }),
-      email: createEmailSender(config.email, logger),
-      createId,
-      now: () => new Date(),
-    },
-  })
+  const { config, logger, database, createId, credentials, contributions } = await bootAssembly(
+    kelpieConfig,
+    process.env,
+  )
 
   if (process.argv.includes('--no-migrate')) {
     logger.info('skipping migrations', { reason: '--no-migrate' })
@@ -77,6 +50,8 @@ async function start(): Promise<void> {
     credentials,
     createId,
     rateLimit: config.rateLimit,
+    runtimeMode: config.runtimeMode,
+    siteName: config.siteName,
     // The socket address, then `X-Forwarded-For` only as far as the configured
     // number of trusted proxies allows. Resolved from the connection itself
     // rather than defaulted inside `createApp`, and trusting the header any