@cosmicdrift/kumiko-dev-server 0.336.1 → 0.338.0

package/dist/create-kumiko-server.d.ts

@@ -48,7 +48,12 @@ export type DevHostDispatchResult = {
     readonly to: string;
     readonly status?: 301 | 302;
 } | {
+    /** Plain 404 by default. `file` serves a static page with status 404
+     *  (like `static-html`), `entryName` serves that bundle's shell with 404;
+     *  `file` wins when both are set. */
     readonly kind: "not-found";
+    readonly entryName?: string;
+    readonly file?: string;
 };
 /** Picks an entry by inspecting the incoming request. Wird von
  *  Multi-Entry-Apps gesetzt; im Single-Entry-Mode irrelevant. */
@@ -185,6 +190,9 @@ export type KumikoServerHandle = {
     readonly stack: TestStack;
     /** Stops the server and tears down the stack (DB + redis). */
     readonly stop: () => Promise<void>;
+    /** BullMQ queue-name prefix of this boot: per-boot in ephemeral mode, so
+     *  its `bull:<prefix>-*` keys belong to this server alone on a shared Redis. */
+    readonly jobQueueNamePrefix: string;
 };
 export declare const STYLESHEET_WATCH_ENV = "KUMIKO_DEV_STYLESHEET_WATCH";
 export declare const PROD_BUNDLES_ENV = "KUMIKO_DEV_PROD_BUNDLES";

package/dist/create-kumiko-server.js

@@ -15,7 +15,7 @@
 // The companion prod entry will land at `@cosmicdrift/kumiko-framework/server`
 // with a different options shape (clientDist, auth config, db url).
 import { spawn } from "node:child_process";
-import { existsSync, mkdtempSync, statSync } from "node:fs";
+import { existsSync, mkdtempSync, realpathSync, statSync } from "node:fs";
 import { readFile, realpath, watch } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve, sep } from "node:path";
@@ -228,13 +228,14 @@ async function servePublicFile(pathname, publicDir) {
     if (filePath === undefined)
         return undefined;
     try {
-        const bytes = await readFile(filePath);
         // Lexical containment (above) only catches "..", not a symlink inside
         // publicDir that points outside it on disk — realpath resolves the
-        // actual target and the same containment check runs against it.
+        // actual target and the same containment check runs against it. Read
+        // from the resolved path so the checked target is the one read.
         const real = await realpath(filePath);
         if (real !== publicDir && !real.startsWith(publicDir + sep))
             return undefined;
+        const bytes = await readFile(real);
         return { bytes, mime: publicFileMimeType(filePath) };
     }
     catch (err) {
@@ -722,7 +723,7 @@ export async function createKumikoServer(options) {
     // resolvePageHead goes through the same headless resolveAndInjectPageHead
     // that runProdApp uses, so dev and e2e exercise the one timeout and
     // fallback path instead of a second copy of it (#3026).
-    const htmlResponse = async (entryName, req, socketAddress) => {
+    const htmlResponse = async (entryName, req, socketAddress, status = 200) => {
         const template = htmlTemplates.get(entryName) ?? defaultTemplate;
         const headers = new Headers();
         headers.set("Content-Type", "text/html; charset=utf-8");
@@ -744,7 +745,23 @@ export async function createKumikoServer(options) {
                 systemQuery: buildDevSystemQuery(req, socketAddress),
             });
         }
-        return new Response(html, { headers });
+        return new Response(html, { status, headers });
+    };
+    // Raw file serve, no bundle injection — mirrors prod's `{ kind: "html", file }`.
+    const staticHtmlResponse = async (file, status) => {
+        let content;
+        try {
+            content = await readFile(file, "utf-8");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            return new Response(`hostDispatch: file not found: ${file}`, { status: 500 });
+        }
+        return new Response(content, {
+            status,
+            headers: { "Content-Type": "text/html; charset=utf-8" },
+        });
     };
     // --- Fetch handler (runtime-neutral) ---
     // Bundle-Pfad-Lookup: für jede Entry serven wir
@@ -756,7 +773,12 @@ export async function createKumikoServer(options) {
         bundleByAssetPath.set(assetPathFor(e.name), e.name);
     // App-root convention (same as expandWatchPatterns/resolveStylesheet above):
     // process.cwd() is the app workspace, so public/ is its static asset dir.
-    const publicDir = resolve(process.cwd(), "public");
+    // Symlink-resolved once: servePublicFile compares realpath()s against it, so
+    // a symlinked public/ would otherwise 404 every file.
+    const lexicalPublicDir = resolve(process.cwd(), "public");
+    const publicDir = existsSync(lexicalPublicDir)
+        ? realpathSync(lexicalPublicDir)
+        : lexicalPublicDir;
     // The app's cwd first, this package's own location as fallback (the cwd may
     // not have renderer-web installed, e.g. a fixture dir).
     const rendererWebFontsDir = resolveRendererWebFontsDir([process.cwd(), import.meta.dir]);
@@ -892,15 +914,15 @@ export async function createKumikoServer(options) {
                     });
                 }
                 if (dispatch.kind === "not-found") {
+                    if (dispatch.file !== undefined)
+                        return staticHtmlResponse(dispatch.file, 404);
+                    if (dispatch.entryName !== undefined) {
+                        return htmlResponse(dispatch.entryName, req, socketAddress, 404);
+                    }
                     return new Response("Not Found", { status: 404 });
                 }
                 if (dispatch.kind === "static-html") {
-                    // Raw file serve, no bundle injection — mirrors prod's
-                    // `{ kind: "html", file: ... }` static-html branch.
-                    const file = await readFile(dispatch.file, "utf-8");
-                    return new Response(file, {
-                        headers: { "Content-Type": "text/html; charset=utf-8" },
-                    });
+                    return staticHtmlResponse(dispatch.file, 200);
                 }
                 return htmlResponse(dispatch.entryName, req, socketAddress);
             }
@@ -984,6 +1006,29 @@ export async function createKumikoServer(options) {
             }, watcherAbort.signal);
         }
     }
+    // The per-boot prefix is never reused, so its BullMQ keys (queues,
+    // repeatables, delayed jobs) would pile up in the shared Redis forever.
+    // A prefix-less duplicate: SCAN returns full key names, which the stack
+    // client's keyPrefix would otherwise prepend a second time.
+    // Takes the connection as a parameter: it must be opened before
+    // stack.cleanup() closes the stack client, yet used only after it, because
+    // closing the stack's enqueuer queues re-writes their `meta` keys.
+    const deleteEphemeralJobQueues = async (raw) => {
+        try {
+            const keys = [];
+            for await (const batch of raw.scanStream({
+                match: `bull:${jobQueueNamePrefix}-*`,
+                count: 500,
+            })) {
+                keys.push(...batch);
+            }
+            if (keys.length > 0)
+                await raw.del(...keys);
+        }
+        finally {
+            raw.disconnect();
+        }
+    };
     const stop = async () => {
         // Watcher zuerst stoppen damit kein onChange während des Teardowns
         // mehr feuert (sonst können tmpdir-rmSync ein process.exit(75)
@@ -998,7 +1043,10 @@ export async function createKumikoServer(options) {
             await stack.eventDispatcher.stop();
         }
         await devJobRunners.stop();
+        const rawRedis = persistentDb ? undefined : stack.redis.redis.duplicate({ keyPrefix: "" });
         await stack.cleanup();
+        if (rawRedis)
+            await deleteEphemeralJobQueues(rawRedis);
     };
     // --- graceful shutdown ---
     // Signal handlers fire on Ctrl-C / kill. Without them, repeated dev
@@ -1041,5 +1089,5 @@ export async function createKumikoServer(options) {
                 ? ` (hot reload on ${entries.length === 1 ? "client entry" : `${entries.length} entries`})`
                 : ""));
     }
-    return { fetch: handleFetch, server, stack, stop };
+    return { fetch: handleFetch, server, stack, stop, jobQueueNamePrefix };
 }

package/dist/init-deploy-cli.js

@@ -84,7 +84,8 @@ export async function runInitDeployCli({ argv, cwd, out, }) {
         out.err("");
         return 2;
     }
-    const appName = getStringFlag(args, "app") ?? defaultAppName(cwd);
+    const outDir = getStringFlag(args, "out") ?? cwd;
+    const appName = getStringFlag(args, "app") ?? defaultAppName(outDir);
     if (!appName) {
         out.err("");
         out.err('  --app <name> is required (no package.json "name" found to default from).');
@@ -96,7 +97,7 @@ export async function runInitDeployCli({ argv, cwd, out, }) {
         appName,
         port: getNumberFlag(args, "port"),
         githubOrg: getStringFlag(args, "github-org"),
-        destination: getStringFlag(args, "out") ?? cwd,
+        destination: outDir,
     };
     try {
         return check ? reportDrift(target, out) : reportScaffold(target, force, out);

package/dist/setup-test-stack-from-features.js

@@ -6,6 +6,18 @@ import { setupTestStack, } from "@cosmicdrift/kumiko-framework/stack";
 import { jobRunLoggerCallbacks } from "@cosmicdrift/kumiko-server-runtime/boot/job-run-logger";
 import { composeFeatures, } from "@cosmicdrift/kumiko-server-runtime/compose-features";
 import { addConfigAccessorFactory } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
+function isConfigResolver(value) {
+    return (typeof value === "object" && value !== null && "get" in value && typeof value.get === "function");
+}
+function resolveBaseConfigResolver(fromBase) {
+    const supplied = fromBase["configResolver"];
+    if (supplied === undefined)
+        return undefined;
+    if (!isConfigResolver(supplied)) {
+        throw new Error("extraContext.configResolver must be a ConfigResolver (an object with get()), e.g. from createConfigResolver() — got a different value; pass the instance, not a factory.");
+    }
+    return supplied;
+}
 export function mergeExtraContext(base, presets) {
     if (presets.length === 0)
         return base;
@@ -14,7 +26,7 @@ export function mergeExtraContext(base, presets) {
         const merged = { ...fromBase };
         if (presets.includes("config")) {
             // Same precedence as mergeConfigResolverDefault (run-dev-app.ts) — a base-supplied resolver wins, factory always derives from it (fw#3313).
-            const configResolver = fromBase["configResolver"] ?? createConfigResolver();
+            const configResolver = resolveBaseConfigResolver(fromBase) ?? createConfigResolver();
             Object.assign(merged, addConfigAccessorFactory({ configResolver }, deps.registry));
         }
         if (presets.includes("template-resolver")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.336.1",
+  "version": "0.338.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -64,11 +64,11 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.336.1",
-    "@cosmicdrift/kumiko-framework": "0.336.1",
-    "@cosmicdrift/kumiko-headless": "0.336.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.336.1",
-    "@cosmicdrift/kumiko-server-runtime": "0.336.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.338.0",
+    "@cosmicdrift/kumiko-framework": "0.338.0",
+    "@cosmicdrift/kumiko-headless": "0.338.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.338.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.338.0",
     "bun-types": "^1.3.13",
     "ts-morph": "^28.0.0",
     "zod": "^4.4.3"

package/src/changes.json

@@ -1,4 +1,36 @@
 [
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "Scaffolded migrate step percent-encodes DB_PASSWORD",
+    "detail": "dev-server: the scaffolded `deploy/migrate-step.sh` percent-encodes `DB_PASSWORD` in `DATABASE_URL`, so passwords with `@`, `:`, `/`, `#`, `%` or non-ASCII characters no longer break the URL. Re-run `kumiko init-deploy` to pick it up; apps with a hand-written `urlencode` should take the new version, which also encodes bytes >= 0x80 correctly."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "dev hostDispatch not-found can serve a custom 404 page",
+    "detail": "`DevHostDispatchResult` `{ kind: \"not-found\" }` accepts `file` (served like `static-html`) or `entryName` (that entry's shell), both with status 404. A missing file answers 500 with `hostDispatch: file not found`. Without fields the plain \"Not Found\" 404 stays.",
+    "migration": "No code change needed."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "New package @cosmicdrift/kumiko-samples with the corpus sources",
+    "detail": "New package with the sample recipes, sample apps and bundled-features sources\n`@cosmicdrift/kumiko-samples` ships the sample recipes, sample apps and bundled-features sources in the repository layout. Tools such as the few-shot corpus build can run against a pinned version of it and get the same entry ids and source paths as in the monorepo."
+  },
+  {
+    "version": "0.337.1",
+    "type": "improvement",
+    "title": "createKumikoServer handle exposes the boot's jobQueueNamePrefix",
+    "detail": "dev-server: `createKumikoServer()` returns the boot's `jobQueueNamePrefix` on its handle, so callers sharing a Redis can address exactly that boot's `bull:<prefix>-*` keys.",
+    "migration": "No action needed: purely additive handle field."
+  },
+  {
+    "version": "0.337.0",
+    "type": "fix",
+    "title": "public/ served via realpath incl. symlinked public/, ephemeral dev queues cleaned on stop, init-deploy --out app name, compose-style migrate-step network name, config preset validates configResolver; guards report correct isolation lines and time out kumiko-upgrade",
+    "detail": "The dev server serves `public/` files from the symlink-resolved path (realpath check before the read) and works when `public/` itself is a symlink. Ephemeral dev boots delete their per-boot BullMQ keys from the shared Redis on `stop()`. `kumiko-init-deploy --out <dir>` defaults the app name from that directory's `package.json`. The generated `migrate-step.sh` with `stackNetwork: \"directory\"` derives the network name like Docker Compose (lowercased, sanitised, `COMPOSE_PROJECT_NAME` wins). `setupTestStackFromFeatures` with the `config` preset throws a clear error when `extraContext.configResolver` is not a resolver. The runtime-isolation guard reports each regression at its own import line, and the upgrade-state guard no longer hangs on a stuck `kumiko-upgrade` (stdin ignored, timeout)."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/templates/deploy/Dockerfile.template

@@ -2,14 +2,14 @@
 #
 # Production-Image for {{appName}}.
 #
-# Server-Bundle variant — the runtime image doesn't know about the
-# monorepo any more, only:
+# Server-Bundle variant — the runtime image doesn't carry the source tree
+# or its node_modules any more, only:
 #
 #   dist/                  ← Client build (kumiko-build)
 #   dist-server/           ← Server bundle (bun build) + minimal package.json
 #   kumiko/migrations/     ← Checked-in SQL migrations applied by `kumiko schema apply`
 #
-# Build context: repository root (monorepo is used in the build stage).
+# Build context: repository root (the full source tree is only used in the build stage).
 
 ARG BUN_VERSION=1.4.0
 {{#hasPrivateGhPackages}}

package/templates/deploy/migrate-step.sh.template

@@ -33,9 +33,11 @@ if [ -z "$STACK_NETWORK" ]; then
 fi
 {{/stackNetworkDiscover}}
 {{#stackNetworkDirectory}}
-STACK_NETWORK="$(basename "$PWD")_stack"
+# Compose lowercases the project name and drops characters outside [a-z0-9_-].
+COMPOSE_PROJECT="${COMPOSE_PROJECT_NAME:-$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z0-9_-')}"
+STACK_NETWORK="${COMPOSE_PROJECT}_stack"
 if ! docker network inspect "$STACK_NETWORK" >/dev/null 2>&1; then
-  echo "Stack network '$STACK_NETWORK' not found — compose project not running?" >&2
+  echo "Stack network '$STACK_NETWORK' not found (derived from COMPOSE_PROJECT_NAME or the directory name '$(basename "$PWD")') — compose project not running?" >&2
   exit 1
 fi
 {{/stackNetworkDirectory}}
@@ -47,6 +49,21 @@ set -a
 . ./.env
 set +a
 
+# Percent-encode so '@', ':', '/', '#', '%' in the password cannot change how
+# the URL is parsed. LC_ALL=C makes the loop walk bytes, not characters;
+# bash sign-extends bytes >= 0x80 in "'$c", hence the & 255.
+urlencode() {
+  local LC_ALL=C s="$1" out="" c i byte
+  for ((i = 0; i < ${#s}; i++)); do
+    c="${s:i:1}"
+    case "$c" in
+      [A-Za-z0-9._~-]) out+="$c" ;;
+      *) printf -v byte '%d' "'$c"; printf -v c '%%%02X' $((byte & 255)); out+="$c" ;;
+    esac
+  done
+  printf '%s' "$out"
+}
+
 # DATABASE_URL assumes: db user = appName, db name = appName, host "db"
 # (compose-service-name), port 5432. Adjust to your stack if different.
 {{#customDbUser}}
@@ -58,7 +75,7 @@ set +a
 # NAME (`-e DATABASE_URL`, no value) so the expanded password never appears
 # in `docker run`'s argv — otherwise it would be visible in `ps auxe` for
 # the duration of the migrate run.
-export DATABASE_URL="postgresql://{{dbUser}}:${DB_PASSWORD}@db:5432/{{appName}}"
+export DATABASE_URL="postgresql://{{dbUser}}:$(urlencode "$DB_PASSWORD")@db:5432/{{appName}}"
 docker run --rm \
   --network "$STACK_NETWORK" \
   -e DATABASE_URL \