@cosmicdrift/kumiko-dev-server 0.391.0 → 0.392.0

package/bin/kumiko-dev.ts

@@ -1,19 +1,18 @@
 #!/usr/bin/env bun
-// kumiko-dev — Wrapper-Skript für sample dev-scripts. Spawnt den
-// übergebenen Server-Entry und respawnt automatisch.
+// kumiko-dev: wrapper script for sample dev scripts. Spawns the given
+// server entry and respawns it automatically.
 //
-// Restart-Policy:
-//   - exit 75 (EX_TEMPFAIL, vom dev-server beim Schema-Change ausgelöst,
-//     weil Bun's Module-Cache einen Process-Restart erzwingt): sofortiger
-//     respawn ohne Crash-Loop-Anrechnung — das ist erwartetes Verhalten.
-//   - jeder andere non-zero exit: respawn mit kurzem Backoff, aber
-//     Crash-Loop-Schutz via createCrashTracker. Verhindert Endlos-Loop
-//     bei syntaktisch totem bin/main.ts und gibt dem User trotzdem
-//     "Live-Edit"-Feeling: ein Code-Fehler in einem Feature killt nicht
-//     die ganze bun-dev-Session.
-//   - Signal-killed (SIGINT/SIGTERM): wir folgen dem Caller, exit 0.
+// Restart policy:
+//   - exit 75 (EX_TEMPFAIL, raised by the dev-server on a schema change
+//     because Bun's module cache forces a process restart): respawn
+//     immediately without counting towards the crash loop. This is expected.
+//   - any other non-zero exit: respawn with a short backoff, guarded by
+//     createCrashTracker. Prevents an endless loop on a syntactically broken
+//     bin/main.ts while keeping the "live edit" feel: a code error in one
+//     feature does not kill the whole bun dev session.
+//   - killed by a signal (SIGINT/SIGTERM): follow the caller, exit 0.
 //
-// Nutzung: `kumiko-dev src/app/server.ts` in package.json:
+// Usage: `kumiko-dev src/app/server.ts` in package.json:
 //
 //   "scripts": { "dev": "kumiko-dev src/app/server.ts" }
 
@@ -37,13 +36,13 @@ if (entry === undefined || entry === "") {
   process.exit(2);
 }
 
-// Restliche Args (z.B. --port 4175) reichen wir an den Server durch.
+// Pass the remaining args (e.g. --port 4175) through to the server.
 const passthroughArgs = process.argv.slice(3);
 
-// Bun's eigener Pfad steht in process.argv[0] — den nutzen wir, damit
-// `bun --env-file=...` Flags vom Caller nicht verloren gehen. Wir
-// reichen NICHT alle Bun-Flags durch (kompliziert mit shell-Escaping);
-// dev-scripts in samples setzen Env-Vars direkt im Aufruf wenn nötig.
+// Bun's own path is in process.argv[0] — we use it so
+// `bun --env-file=...` flags from the caller aren't lost. We
+// do NOT pass through all Bun flags (complicated with shell escaping);
+// dev-scripts in samples set env vars directly in the invocation when needed.
 const bunPath = process.argv[0] ?? "bun";
 
 const crashTracker = createCrashTracker({
@@ -61,7 +60,7 @@ const spawnServer = (): void => {
 
   child.on("exit", (code, signal) => {
     if (signal !== null) {
-      // Signal-killed (z.B. SIGINT): Caller wollte raus → wir auch.
+      // Signal-killed (e.g. SIGINT): the caller wanted out → so do we.
       process.exit(0);
       return;
     }
@@ -74,8 +73,8 @@ const spawnServer = (): void => {
       process.exit(0);
       return;
     }
-    // Non-zero exit ohne Schema-Change: Code-Fehler oder transienter
-    // Crash. Respawn mit Backoff + Crash-Loop-Schutz.
+    // Non-zero exit without a schema change: code error or transient
+    // crash. Respawn with backoff + crash-loop protection.
     const now = Date.now();
     const allowed = crashTracker.noteCrash(now);
     if (!allowed) {

package/dist/build-server-bundle.js

@@ -40,6 +40,10 @@
 //                       worker threads, dynamic require). Added to
 //                       dist-server/package.json#dependencies.
 //
+//   OPTIONAL_RUNTIME_EXTERNALS — external in every build, but listed in
+//                       dist-server/package.json#dependencies only when an
+//                       emitted file imports them or the app declares them.
+//
 //   BUILD_ONLY_EXTERNALS — referenced only transitively in the framework,
 //                          never by app code. Tree-shaking removes them from
 //                          the bundle; the external marker only disables
@@ -54,13 +58,6 @@ const hasBun = typeof Bun !== "undefined";
 // ioredis), and dynamic require (postgres, temporal-polyfill) — anything that
 // breaks under Bun bundling. (drizzle-kit/drizzle-orm are excluded: the
 // migration path now uses the framework's runMigrationsFromDir, not drizzle-kit.)
-// meilisearch is deliberately here, not in BUILD_ONLY_EXTERNALS below — apps
-// that import createMeilisearchAdapter (kumiko-framework/search/meilisearch)
-// reference the package at runtime (no native binding, plain HTTP client,
-// but a real runtime import). A production crash in money-horse,
-// "Cannot find package 'meilisearch'", occurred because it used to be in
-// BUILD_ONLY_EXTERNALS instead. Its version comes from the framework's
-// peerDependencies range.
 const RUNTIME_EXTERNALS = [
     "@node-rs/argon2",
     "sharp",
@@ -70,8 +67,12 @@ const RUNTIME_EXTERNALS = [
     "temporal-polyfill",
     "pino",
     "pino-pretty",
-    "meilisearch",
 ];
+// An optional framework peer: apps that import createMeilisearchAdapter reference
+// it at runtime, so it must stay external (as BUILD_ONLY_EXTERNALS it crashed
+// money-horse with "Cannot find package 'meilisearch'"), but apps without search
+// should not install it.
+const OPTIONAL_RUNTIME_EXTERNALS = ["meilisearch"];
 // Packages that appear only in the build stack (transitive framework imports),
 // but are not referenced by app code. Without the external marker,
 // bun build fails on dynamic imports. Tree-shaking removes them from the
@@ -136,6 +137,7 @@ export async function buildServerBundle(options = {}) {
     const extraEntryPaths = resolveExtraEntries(cwd, options.extraEntries ?? []);
     const externals = [
         ...RUNTIME_EXTERNALS,
+        ...OPTIONAL_RUNTIME_EXTERNALS,
         ...BUILD_ONLY_EXTERNALS,
         ...(options.extraRuntimeExternals ?? []),
         ...(options.extraBuildOnlyExternals ?? []),
@@ -169,7 +171,9 @@ export async function buildServerBundle(options = {}) {
     // split entry points and sometimes reports ~0 for the entry stub.
     const entries = [];
     const chunks = [];
+    const emittedCode = [];
     for (const out of result.outputs) {
+        emittedCode.push(await out.text());
         const base = out.path.split("/").pop() ?? out.path;
         if (out.kind === "entry-point") {
             const desired = ENTRY_RENAMES[base] ?? base;
@@ -184,8 +188,11 @@ export async function buildServerBundle(options = {}) {
     }
     entries.sort((a, b) => a.file.localeCompare(b.file));
     const totalBytes = [...entries, ...chunks].reduce((sum, e) => sum + e.sizeBytes, 0);
+    const declaredAppDependencies = readDeclaredAppDependencies(cwd);
+    const neededOptionalExternals = OPTIONAL_RUNTIME_EXTERNALS.filter((pkg) => declaredAppDependencies.has(pkg) || emittedCode.some((code) => importsBarePackage(code, pkg)));
     const runtimeDeps = await resolveRuntimeDepsVersions(cwd, repoRoot, [
         ...RUNTIME_EXTERNALS,
+        ...neededOptionalExternals,
         ...(options.extraRuntimeExternals ?? []),
     ]);
     const runtimePkg = {
@@ -272,7 +279,23 @@ export function readExtraRuntimeExternals(cwd) {
         return [];
     return list.filter((x) => typeof x === "string" && x.trim().length > 0);
 }
-// Resolve versions for RUNTIME_EXTERNALS: first from installed
+// Static, dynamic and CommonJS imports of an external survive bundling as a bare specifier
+// (require becomes __require(...)).
+function importsBarePackage(code, pkg) {
+    const escaped = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:\\bfrom\\s*|\\bimport\\s*\\(?\\s*|\\w*[rR]equire\\w*\\s*\\(\\s*)["'\`]${escaped}["'\`]`).test(code);
+}
+function readDeclaredAppDependencies(cwd) {
+    const appPkg = join(cwd, "package.json");
+    if (!existsSync(appPkg))
+        return new Set();
+    const parsed = parseJsonSafe(readFileSync(appPkg, "utf-8"), {});
+    return new Set([
+        ...Object.keys(parsed.dependencies ?? {}),
+        ...Object.keys(parsed.optionalDependencies ?? {}),
+    ]);
+}
+// Resolve versions for the runtime externals: first from installed
 // node_modules/@cosmicdrift/*-packages (relative to cwd, which works for
 // any consumer app), then additionally from packages/framework + bundled-
 // features (the framework's own workspace checkout). Fall back to "*"

package/dist/scaffold-deploy.d.ts

@@ -28,9 +28,9 @@ export type ScaffoldDeployDetected = {
     /** ES-Operations seed-migrations (`seeds/`). Required for apps that
      *  use the es-ops feature. */
     readonly hasSeeds: boolean;
-    /** Private @cosmicdriftgamestudio/* GH-Packages → Dockerfile needs to
-     *  pass NPM_AUTH_TOKEN as build-arg + re-export it as $GITHUB_TOKEN inside
-     *  the build-stage (bunfig.toml/.npmrc read $GITHUB_TOKEN). */
+    /** Private @cosmicdriftgamestudio/* GH-Packages → the build-stage install
+     *  mounts the BuildKit secret npm_auth_token as $GITHUB_TOKEN
+     *  (bunfig.toml/.npmrc read $GITHUB_TOKEN). */
     readonly hasPrivateGhPackages: boolean;
     /** A `workspaces` root, or a `file:`/`workspace:`/`link:` dependency spec
      *  — bun needs the whole build context on disk to resolve the lockfile,

package/dist/scaffold-deploy.js

@@ -17,6 +17,7 @@ import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
 import { isKebabSegment } from "./kebab.js";
 const REGISTRY_CONFIG_FILES = ["bunfig.toml", ".npmrc"];
+const NPM_AUTH_SECRET_MOUNT = "--mount=type=secret,id=npm_auth_token,env=GITHUB_TOKEN";
 const TEMPLATE_FILES = [
     { template: "Dockerfile.template", output: "Dockerfile" },
     {
@@ -49,7 +50,7 @@ export function renderDeployFiles(options) {
     const sourceDir = options.sourceDir ?? destinationRoot;
     const detected = detectOptionalSurfaces(sourceDir, options.appName, options.ensuredRegistryConfigFiles ?? []);
     if (detected.hasPrivateGhPackages && detected.registryConfigFiles.length === 0) {
-        // The Dockerfile only forwards the auth build-arg; without a registry
+        // The Dockerfile only mounts the auth secret; without a registry
         // config scope entry bun resolves @cosmicdriftgamestudio/* against npmjs
         // and the image build fails late with a 404.
         throw new Error(`renderDeployFiles: private @cosmicdriftgamestudio/* deps need a bunfig.toml or .npmrc in ${sourceDir} with a scope entry for the private registry`);
@@ -60,6 +61,7 @@ export function renderDeployFiles(options) {
         port: String(port),
         githubOrg,
         installManifests,
+        npmAuthSecretMount: detected.hasPrivateGhPackages ? `${NPM_AUTH_SECRET_MOUNT} ` : "",
         dbUser: detected.dbUser,
         dbName: detected.dbName,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.391.0",
+  "version": "0.392.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -77,15 +77,15 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.391.0",
-    "@cosmicdrift/kumiko-feature-ast": "0.391.0",
-    "@cosmicdrift/kumiko-framework": "0.391.0",
-    "@cosmicdrift/kumiko-renderer": "0.391.0",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.391.0",
-    "@cosmicdrift/kumiko-guards": "0.391.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.391.0",
-    "@cosmicdrift/kumiko-testing": "0.391.0",
-    "@cosmicdrift/kumiko-types": "0.391.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.392.0",
+    "@cosmicdrift/kumiko-feature-ast": "0.392.0",
+    "@cosmicdrift/kumiko-framework": "0.392.0",
+    "@cosmicdrift/kumiko-renderer": "0.392.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.392.0",
+    "@cosmicdrift/kumiko-guards": "0.392.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.392.0",
+    "@cosmicdrift/kumiko-testing": "0.392.0",
+    "@cosmicdrift/kumiko-types": "0.392.0",
     "ts-morph": "^28.0.0",
     "zod": "^4.6.7"
   },

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.392.0",
+    "type": "breaking",
+    "title": "The managed Dockerfile reads the registry token from a BuildKit secret",
+    "migration": "Image builds pass the token as a BuildKit secret instead of a build-arg: docker build --secret id=npm_auth_token,env=NPM_AUTH_TOKEN, or secrets: npm_auth_token=... in docker/build-push-action. The infra _docker-build-push workflow already sends both. Run kumiko-upgrade --apply to rewrite deploy/Dockerfile; a Dockerfile with a kumiko-managed: local override changes by hand: drop ARG NPM_AUTH_TOKEN and ENV GITHUB_TOKEN and start the build-stage install with RUN --mount=type=secret,id=npm_auth_token,env=GITHUB_TOKEN bun install."
+  },
+  {
+    "version": "0.392.0",
+    "type": "improvement",
+    "title": "meilisearch lands in dist-server dependencies only when the bundle imports it or the app declares it",
+    "detail": "The package stays external in every server build, but apps without search no longer get it as a production dependency in dist-server/package.json. An app that imports createMeilisearchAdapter, or lists meilisearch in dependencies or optionalDependencies, keeps it with the framework's peer range."
+  },
   {
     "version": "0.390.0",
     "type": "fix",

package/templates/deploy/Dockerfile.template

@@ -12,13 +12,6 @@
 # Build context: repository root (the full source tree is only used in the build stage).
 
 ARG BUN_VERSION=1.4.4
-{{#hasPrivateGhPackages}}
-# Registry auth for @cosmicdriftgamestudio: CI passes the token as
-# NPM_AUTH_TOKEN via --build-arg. Multi-stage ARG scoping needs the
-# re-declaration inside the stage that uses it; this top-level ARG only
-# makes it settable via `docker build`.
-ARG NPM_AUTH_TOKEN=
-{{/hasPrivateGhPackages}}
 # Build identity — passed in by the CI workflow via --build-arg. Defaults
 # for local container builds.
 ARG BUILD_VERSION=dev
@@ -28,9 +21,10 @@ ARG BUILD_TIME=unknown
 FROM oven/bun:${BUN_VERSION}-alpine AS build
 WORKDIR /app
 {{#hasPrivateGhPackages}}
-# bunfig.toml/.npmrc resolve the @cosmicdriftgamestudio scope via $GITHUB_TOKEN.
-ARG NPM_AUTH_TOKEN
-ENV GITHUB_TOKEN=${NPM_AUTH_TOKEN}
+# Registry auth for @cosmicdriftgamestudio: CI passes the token as the BuildKit
+# secret npm_auth_token. The install RUN mounts it as $GITHUB_TOKEN, which
+# bunfig.toml/.npmrc read, so it never lands in a layer, the image history or
+# the registry build cache.
 {{/hasPrivateGhPackages}}
 
 {{#installFromFullTree}}
@@ -38,14 +32,14 @@ ENV GITHUB_TOKEN=${NPM_AUTH_TOKEN}
 # disk for bun to resolve the lockfile — a partial COPY makes bun treat it
 # as empty and rewrite it.
 COPY . .
-RUN bun install --frozen-lockfile
+RUN {{npmAuthSecretMount}}bun install --frozen-lockfile
 RUN bun run build
 {{/installFromFullTree}}
 {{#installFromManifests}}
 # Manifests first for Docker layer cache — bun install only invalidates on
 # dependency change, not on every source edit.
 COPY {{installManifests}} ./
-RUN bun install --frozen-lockfile
+RUN {{npmAuthSecretMount}}bun install --frozen-lockfile
 COPY . .
 RUN bun run build
 {{/installFromManifests}}