@cosmicdrift/kumiko-dev-server 0.386.0 → 0.388.0

package/dist/run-dev-app.d.ts

@@ -1,12 +1,12 @@
-import { type SeedAdminOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import type { SeedAdminOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
 import type { PostAuthLandingResolver } from "@cosmicdrift/kumiko-framework/api";
-import { type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import { type FeatureDefinition, type Registry, type ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
-import { type ComposedEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import type { ComposedEnvSchema } from "@cosmicdrift/kumiko-framework/env";
 import type { ErrorDocsConfig } from "@cosmicdrift/kumiko-framework/errors";
 import type { EnvelopeCipher, MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import type { PageHeadResolver } from "@cosmicdrift/kumiko-renderer/headless/apex";
-import { type BillingBootOption, type DemoModeOption, type FileStorageBootOption, type KmsMode, type MailBootOption, type ProdSeedsConfig } from "@cosmicdrift/kumiko-server-runtime";
+import type { BillingBootOption, DemoModeOption, FileStorageBootOption, KmsMode, MailBootOption, ProdSeedsConfig } from "@cosmicdrift/kumiko-server-runtime";
 import type { TestStack } from "@cosmicdrift/kumiko-testing/stack";
 import { type CreateKumikoServerOptions, type KumikoServerHandle } from "./create-kumiko-server.ts";
 export type { AccountLockoutSetup, AccountUnlockSetup, AuthMailOptions, EmailVerificationSetup, InviteSetup, PasswordResetSetup, SignupSetup, } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
@@ -19,16 +19,16 @@ export type RunDevAppAuthOptions = {
     /** Optional override of the login error → HTTP status map. Default
      *  maps invalidCredentials → 401, noMembership → 403. */
     readonly loginErrorStatusMap?: Readonly<Record<string, number>>;
-    /** Auth-Mail-Convenience — symmetrisch zu RunProdAppAuthOptions.mail.
-     *  Verdrahtet alle 4 Mail-Flows aus env-SMTP + Standard-Templates;
-     *  hmacSecret = `JWT_SECRET`-env (Dev-Fallback wenn ungesetzt). Ohne
-     *  `SMTP_HOST`-env bleiben die Flows unverdrahtet (Null-Transport-Guard).
-     *  Explizite Flow-Setups gewinnen über den mail-Default. */
+    /** Auth-mail convenience, symmetric with RunProdAppAuthOptions.mail.
+     *  Wires all four mail flows from env-based SMTP settings and the default
+     *  templates; hmacSecret is the `JWT_SECRET` environment value, with a dev
+     *  fallback when unset. Without `SMTP_HOST`, the flows remain unwired
+     *  (the null-transport guard). Explicit flow setups override the mail default. */
     readonly mail?: AuthMailOptions;
-    /** Password-reset flow. Wenn gesetzt werden /api/auth/request-password-
-     *  reset + /api/auth/reset-password als Public-Routes gemounted UND
-     *  der request/confirm-Handler im auth-email-password-Feature wird
-     *  registriert. Symmetrisch zu RunProdAppAuthOptions.passwordReset. */
+    /** Password-reset flow. When set, mounts /api/auth/request-password-
+     *  reset and /api/auth/reset-password as public routes and registers the
+     *  request/confirm handlers in the auth-email-password feature. Symmetric
+     *  with RunProdAppAuthOptions.passwordReset. */
     readonly passwordReset?: PasswordResetSetup;
     /** Email-verification flow. Symmetric to passwordReset. */
     readonly emailVerification?: EmailVerificationSetup;
@@ -36,11 +36,11 @@ export type RunDevAppAuthOptions = {
     readonly signup?: SignupSetup;
     /** Tenant-invite flow (magic link). Symmetric. */
     readonly invite?: InviteSetup;
-    /** Account-unlock flow (#1266). Symmetric to RunProdAppAuthOptions. */
+    /** Account-unlock flow. Symmetric to RunProdAppAuthOptions. */
     readonly accountUnlock?: AccountUnlockSetup;
     /** Brute-force guard on the login handler (maxFailedAttempts,
      *  lockoutDurationMinutes). Mounts no routes. Symmetric to
-     *  RunProdAppAuthOptions.accountLockout (kumiko-framework#1627). */
+     *  RunProdAppAuthOptions.accountLockout. */
     readonly accountLockout?: AccountLockoutSetup;
     /** Domain attribute for both auth cookies (see
      *  AuthRoutesConfig.cookieDomain). Symmetric to RunProdAppAuthOptions. */
@@ -55,7 +55,7 @@ export type RunDevAppAuthOptions = {
     /** Opt out of the Origin guard. Symmetric to RunProdAppAuthOptions. */
     readonly unsafeSkipOriginCheck?: boolean;
     /** Number of trusted reverse-proxy hops for client-IP derivation (see
-     *  AuthRoutesConfig.trustedProxyHops, kumiko-framework#1539). Symmetric to
+     *  AuthRoutesConfig.trustedProxyHops). Symmetric to
      *  RunProdAppAuthOptions — dev usually runs unproxied, so this is normally
      *  left unset (default 0). */
     readonly trustedProxyHops?: number;
@@ -72,9 +72,9 @@ export type RunDevAppSeedsConfig = Omit<ProdSeedsConfig, "run"> & {
     readonly run?: readonly SeedFn[];
 };
 export type RunDevAppOptions = {
-    /** App-spezifische Features. Im auth-mode werden config/user/tenant/
-     *  auth-email-password automatisch dazu gemischt — KEIN doppeltes
-     *  manuelles Hinzufügen nötig. */
+    /** App-specific features. In auth mode, config/user/tenant/
+     *  auth-email-password are mixed in automatically, so they must not be
+     *  added manually as well. */
     readonly features: readonly FeatureDefinition[];
     /** Opt-in boot-validator warnings — see ValidateBootOptions. */
     readonly validateBootOptions?: ValidateBootOptions;
@@ -94,38 +94,39 @@ export type RunDevAppOptions = {
      *  through `runDevApp` show the same resolved head prod does. See
      *  `CreateKumikoServerOptions.resolvePageHead` for the full contract. */
     readonly resolvePageHead?: PageHeadResolver;
-    /** CSS-Entry. Default: package-export `@cosmicdrift/kumiko-renderer/web/styles.css`
-     *  wenn ein client-Entry gesetzt ist. `false` deaktiviert die CSS-Pipeline. */
+    /** CSS entry. Defaults to the package export
+     *  `@cosmicdrift/kumiko-renderer/web/styles.css` when a client entry is set.
+     *  `false` disables the CSS pipeline. */
     readonly stylesheet?: string | false;
     /** Tailwind `--watch` process on/off, see `CreateKumikoServerOptions.stylesheetWatch`. */
     readonly stylesheetWatch?: boolean;
-    /** Eigenes HTML-Template; sonst minimal-Default (#root + client.js).
-     *  Im Multi-Entry-Mode ist es das Fallback-Template, wenn ein einzelner
-     *  Entry kein eigenes htmlPath setzt. */
+    /** Custom HTML template; otherwise uses a minimal default (#root + client.js).
+     *  In multi-entry mode, this is the fallback template when an entry does not
+     *  define its own htmlPath. */
     readonly htmlPath?: string;
-    /** Listen-Port. Default 4173 (oder $PORT). */
+    /** Listening port. Defaults to 4173, or `$PORT` when set. */
     readonly port?: number;
-    /** Extra-Verzeichnisse für den File-Watcher (Trigger Hot-Reload). */
+    /** Additional directories for the file watcher to trigger hot reload. */
     readonly watchDirs?: readonly string[];
-    /** SIGINT/SIGTERM-Handler installieren (Default true; in Tests auf
-     *  false damit repeated boots keine Listener akkumulieren). */
+    /** Installs SIGINT/SIGTERM handlers. Defaults to true; tests can disable
+     *  them so repeated boots do not accumulate listeners. */
     readonly installSignalHandlers?: boolean;
     /** Auth mode: standard features mixed in, auth routes wired, seedAdminGuarded
      *  runs in onAfterSetup. Without `auth` the server stays in auto-mint JWT mode. */
     readonly auth?: RunDevAppAuthOptions;
-    /** Eigene Seed-Funktionen, laufen nach dem Admin (wenn auth) in
-     *  Array-Reihenfolge. */
+    /** App-defined seed functions, run after the admin seed when auth is active,
+     *  in array order. */
     readonly seeds?: readonly SeedFn[] | RunDevAppSeedsConfig;
-    /** Extra-AppContext-Keys. `templateResolver` (immer) + `secrets` (wenn das
-     *  secrets-Feature gemountet ist) + `configResolver` (auth-mode) werden
-     *  automatisch ergänzt — App-Werte gewinnen. Symmetrisch zu runProdApp. */
+    /** Additional AppContext keys. `templateResolver` is always added; `secrets`
+     *  is added when the secrets feature is mounted; and `configResolver` is
+     *  added in auth mode. App values take precedence. Symmetric with runProdApp. */
     /** Boot default locale (BCP-47) for ctx.locale when the request carries
      *  no locale signal. Merged into AppContext before extraContext (app wins). */
     readonly defaultLocale?: string;
     readonly extraContext?: CreateKumikoServerOptions["extraContext"];
-    /** MasterKeyProvider für die auto-verdrahtete `ctx.secrets`. Default:
-     *  `createEnvMasterKeyProvider`. Override für KMS-Backends. Nur relevant
-     *  wenn das secrets-Feature gemountet ist. Symmetrisch zu runProdApp. */
+    /** MasterKeyProvider for the automatically wired `ctx.secrets`. Defaults to
+     *  `createEnvMasterKeyProvider`; override it for KMS backends. Only relevant
+     *  when the secrets feature is mounted. Symmetric with runProdApp. */
     readonly masterKey?: MasterKeyProvider;
     /** Subject KMS for PII-annotated fields, the dev counterpart of runProdApp({ kms }).
      *  Unset: an ephemeral DB gets an InMemoryKmsAdapter plus a throwaway blind-index key;
@@ -133,32 +134,33 @@ export type RunDevAppOptions = {
      *  createPgKmsAdapter against that DB there (in-memory DEKs vanish on restart).
      *  `false`: explicit plaintext, with the boot warning. */
     readonly kms?: KmsAdapter | false;
-    /** 32-Byte-Key (base64) für Blind-Index-HMACs — Pflicht sobald `kms`
-     *  gesetzt ist und lookupable-Felder gemountet sind (sonst Boot-Abbruch,
-     *  symmetrisch zu runProdApp). */
+    /** 32-byte base64 key for blind-index HMACs. Required when `kms` is set and
+     *  lookupable fields are mounted; otherwise boot aborts. Symmetric with
+     *  runProdApp. */
     readonly blindIndexKey?: string;
-    /** Env-Quelle für die ENV→config-app-override-Brücke (Keys mit `env:`
-     *  bekommen ihren env-Wert als app-override-Default — symmetrisch zu
-     *  runProdApp). Default `process.env`. Injizierbar als Test-Seam, damit
-     *  Tests eigene env-Werte reichen statt `process.env` global zu mutieren. */
+    /** Environment source for the ENV-to-config app-override bridge. Keys with
+     *  `env:` receive their environment value as the app-override default,
+     *  symmetric with runProdApp.
+     *  Defaults to `process.env`; injectable as a test seam so tests can provide
+     *  custom environment values without mutating the global `process.env`. */
     readonly envSource?: Record<string, string | undefined>;
-    /** Anonymous-Access für Public-Endpoints — Requests ohne JWT laufen
-     *  als Pseudo-User mit Rolle `anonymous` durch, wenn der Handler die
-     *  Rolle in `access.roles` führt. */
+    /** Anonymous access for public endpoints. Requests without a JWT proceed as
+     *  a pseudo-user with the `anonymous` role when the handler includes that
+     *  role in `access.roles`. */
     readonly anonymousAccess?: CreateKumikoServerOptions["anonymousAccess"];
     /** File-Storage-Provider — aktiviert die Upload-Routes (/api/files) +
      *  `ctx.files`. Demos: `{ storageProvider: createInMemoryFileProvider() }`. */
     readonly files?: CreateKumikoServerOptions["files"];
-    /** App-eigene HTTP-Routes (z.B. /feed.xml, /sitemap.xml) — wird ans
-     *  Hono-app gehängt, läuft VOR dem static-asset-Pfad. Symmetrisch zur
-     *  gleichnamigen Option in runProdApp. */
+    /** App-defined HTTP routes, such as /feed.xml and /sitemap.xml. They are
+     *  attached to the Hono app before the static-asset path. Symmetric with the
+     *  same-named option in runProdApp. */
     readonly extraRoutes?: CreateKumikoServerOptions["extraRoutes"];
     /** Framework-managed unsubscribe links and routes, same contract as
      *  `RunProdAppOptions.unsubscribe`; the link base URL comes from `auth.mail.baseUrl`
      *  or `APP_BASE_URL` (dev has no `auth.publicOrigin`). */
     readonly unsubscribe?: UnsubscribeOption;
     /** Hook for app-wired co-running components — symmetric to
-     *  runProdApp.wire (kumiko-framework#3050). */
+     *  runProdApp.wire. */
     readonly wire?: CreateKumikoServerOptions["wire"];
     /** Same as `RunProdAppOptions["mail"]`: mounts `channel-email` and wires the auth mail flows. */
     readonly mail?: MailBootOption;