@cosmicdrift/kumiko-dev-server 0.413.1 → 0.414.0

package/dist/build-server-bundle.js

@@ -283,7 +283,7 @@ export function readExtraRuntimeExternals(cwd) {
 // (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);
+    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");
@@ -364,7 +364,6 @@ export function formatServerBuildResult(result, durationMs) {
     const dim = "\x1b[2m";
     const green = "\x1b[32m";
     const reset = "\x1b[0m";
-    // @wrapper-known semantic-alias
     const mb = (bytes) => (bytes / 1024 / 1024).toFixed(2);
     const lines = [];
     lines.push("");

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

@@ -1,4 +1,5 @@
 import { type PageHeadResolver, type PageHeadSystemQuery } from "@cosmicdrift/kumiko-renderer/headless/apex";
+import type { PwaShell } from "@cosmicdrift/kumiko-server-runtime/pwa";
 import type { TestStack } from "@cosmicdrift/kumiko-testing/stack";
 import type { NormalizedEntry } from "./create-kumiko-server-client-bundles.ts";
 export declare const DEFAULT_HTML = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width,initial-scale=1,interactive-widget=resizes-content\" />\n    <title>Kumiko</title>\n  </head>\n  <body>\n    <div id=\"root\"></div>\n    <script type=\"module\" src=\"/client.js\"></script>\n  </body>\n</html>\n";
@@ -16,6 +17,7 @@ export type DevHtmlDeps = {
     readonly stylesheetPath: string | undefined;
     readonly resolvePageHead: PageHeadResolver | undefined;
     readonly buildSystemQuery: DevSystemQueryBuilder;
+    readonly pwa: PwaShell | undefined;
 };
 export declare function respondWithHtmlShell(deps: DevHtmlDeps, entryName: string, req: Request, socketAddress?: string, status?: number): Promise<Response>;
 export declare function respondWithStaticHtmlFile(file: string, status: number): Promise<Response>;

package/dist/create-kumiko-server-html.js

@@ -109,6 +109,8 @@ export async function respondWithHtmlShell(deps, entryName, req, socketAddress,
     let html = injectReload(template);
     if (deps.stylesheetPath !== undefined)
         html = injectStylesheet(html);
+    if (deps.pwa !== undefined)
+        html = deps.pwa.injectHeadTags(html);
     if (deps.resolvePageHead !== undefined) {
         html = await injectDevPageHead(html, deps.resolvePageHead, req, socketAddress, deps.buildSystemQuery);
     }

package/dist/create-kumiko-server-reload.js

@@ -49,14 +49,19 @@ export function broadcastReload(hub, changedFile) {
 }
 export function openReloadStream(hub) {
     const encoder = new TextEncoder();
+    let entry;
     const stream = new ReadableStream({
         start(controller) {
-            const entry = { controller, encoder, closed: false };
+            entry = { controller, encoder, closed: false };
             hub.clients.add(entry);
             controller.enqueue(encoder.encode(": connected\n\n"));
             controller.enqueue(encoder.encode(`event: boot\ndata: ${hub.bootId}\n\n`));
         },
         cancel() {
+            if (entry !== undefined) {
+                entry.closed = true;
+                hub.clients.delete(entry);
+            }
             for (const c of hub.clients) {
                 if (c.closed)
                     hub.clients.delete(c);

package/dist/create-kumiko-server-routes.js

@@ -1,6 +1,7 @@
 /// <reference types="bun-types" preserve="true" />
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { createPwaShell } from "@cosmicdrift/kumiko-server-runtime/pwa";
 import { RENDERER_WEB_FONT_FILE_PATTERN, RENDERER_WEB_FONTS_URL_PREFIX, resolveRendererWebFontsDir, } from "@cosmicdrift/kumiko-server-runtime/renderer-web-fonts";
 import { stripNoRouteMatchHeader, tryHonoFirst, } from "@cosmicdrift/kumiko-server-runtime/try-hono-first";
 import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
@@ -77,6 +78,9 @@ async function serveStylesheet({ req, url }, deps) {
     const css = await readFile(stylesheetPath, "utf-8");
     return new Response(css, { headers: { "Content-Type": "text/css; charset=utf-8" } });
 }
+function servePwaFile({ req, url }, deps) {
+    return deps.html.pwa?.respond(req, url.pathname);
+}
 function serveReloadStream({ req, url }, deps) {
     if (url.pathname !== "/_reload" || req.method !== "GET")
         return undefined;
@@ -161,6 +165,7 @@ const DEV_ROUTES = [
     serveBundleSourceMap,
     serveRendererWebFont,
     serveStylesheet,
+    servePwaFile,
     serveReloadStream,
     serveSpaShell,
     servePublicAsset,
@@ -180,13 +185,23 @@ function createDevRouteFetch(deps) {
         return stripNoRouteMatchHeader(await deps.app.fetch(req, socketAddress));
     };
 }
+// Dev bundles keep their names across rebuilds, so the token changes per boot instead.
+function createDevPwaShell(options, bundleByAssetPath, stylesheetPath) {
+    if (options.pwa === undefined)
+        return undefined;
+    return createPwaShell(options.pwa, {
+        appShellUrls: [...bundleByAssetPath.keys(), ...(stylesheetPath ? ["/styles.css"] : [])],
+        buildToken: `dev-${Date.now()}`,
+    });
+}
 export function createDevFetchHandler(input) {
     const { options, stack } = input;
     const buildSystemQuery = createDevSystemQueryBuilder(stack.dispatcher, options.trustedProxyHops);
+    const bundleByAssetPath = indexBundlesByAssetPath(input.entries);
     const routeFetch = createDevRouteFetch({
         app: stack.app,
         clientBundles: input.clientBundles,
-        bundleByAssetPath: indexBundlesByAssetPath(input.entries),
+        bundleByAssetPath,
         publicDir: resolveDevPublicDir(),
         // 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).
@@ -200,6 +215,7 @@ export function createDevFetchHandler(input) {
             stylesheetPath: input.stylesheetPath,
             resolvePageHead: options.resolvePageHead,
             buildSystemQuery,
+            pwa: createDevPwaShell(options, bundleByAssetPath, input.stylesheetPath),
         },
     });
     return options.wrapFetch ? options.wrapFetch(routeFetch) : routeFetch;

package/dist/create-kumiko-server-stack.js

@@ -25,7 +25,11 @@ export function resolveDevDbMode(processEnv) {
         : `kumiko-dev-${crypto.randomUUID()}`;
     // Pub/Sub ignores the DB index, so the SSE channels need the same per-boot
     // isolation as the queues; an explicit env value wins so a worker can be pointed at it.
-    const sseChannelPrefix = processEnv["KUMIKO_REDIS_CHANNEL_PREFIX"]?.trim() || jobQueueNamePrefix;
+    // KUMIKO_REDIS_PREFIX (per-app ACL namespace) is next: redisNamespaceFromEnv throws when a channel
+    // prefix differs from it, so the per-boot default would stop every dev boot in such an env.
+    const sseChannelPrefix = processEnv["KUMIKO_REDIS_CHANNEL_PREFIX"]?.trim() ||
+        processEnv["KUMIKO_REDIS_PREFIX"]?.trim() ||
+        jobQueueNamePrefix;
     return { devDbName, persistentDb, jobQueueNamePrefix, sseChannelPrefix };
 }
 function buildDevStackOptions(options, dbMode, sseBroker) {

package/dist/create-kumiko-server-stylesheet.js

@@ -78,7 +78,8 @@ function runTailwindOneShotBuild(bunPath, cliPath, entryCss, outPath) {
         child.on("error", rejectPromise);
     });
 }
-// unref() so the watcher cannot outlive a crashed parent as an orphan.
+// unref() only keeps the child from holding the parent's event loop open; it does not end it,
+// so a failed boot must call the returned kill.
 function spawnTailwindWatcher(bunPath, cliPath, entryCss, outPath) {
     const watcher = spawn(bunPath, ["run", cliPath, "-i", entryCss, "-o", outPath, "--watch"], {
         stdio: "inherit",

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

@@ -19,5 +19,6 @@ export type DevFileWatcherDeps = {
     readonly reloadHub: DevReloadHub;
     readonly stop: () => Promise<void>;
 };
+export declare function probeFilesystemClockMs(probeParentDir?: string): number;
 export declare function isUnchangedSinceWatchStart(absolutePath: string, watchStartedAtMs: number): boolean;
 export declare function startDevFileWatchers(deps: DevFileWatcherDeps): void;

package/dist/create-kumiko-server-watcher.js

@@ -1,7 +1,8 @@
 /// <reference types="bun-types" preserve="true" />
-import { statSync } from "node:fs";
+import { mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { watch } from "node:fs/promises";
-import { resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { rebuildClientBundles, } from "./create-kumiko-server-client-bundles.js";
 import { broadcastReload } from "./create-kumiko-server-reload.js";
 import { logInfo } from "./dev-server-runtime.js";
@@ -112,6 +113,19 @@ function expandWatchPatterns(patterns) {
     }
     return out;
 }
+// mtimes come from the filesystem clock at its granularity, not from Date.now(); a baseline taken
+// from the same clock keeps a coarse-mtime or skewed filesystem from swallowing real edits.
+export function probeFilesystemClockMs(probeParentDir = tmpdir()) {
+    const probeDir = mkdtempSync(join(probeParentDir, "kumiko-watch-start-"));
+    try {
+        const probeFile = join(probeDir, "probe");
+        writeFileSync(probeFile, "");
+        return statSync(probeFile).mtimeMs;
+    }
+    finally {
+        rmSync(probeDir, { recursive: true, force: true });
+    }
+}
 // A deleted or renamed file is a real change, so a failing stat counts as changed.
 export function isUnchangedSinceWatchStart(absolutePath, watchStartedAtMs) {
     try {
@@ -161,9 +175,13 @@ export function startDevFileWatchers(deps) {
     for (const e of deps.entries)
         entryDirs.add(resolve(e.sourceFile, ".."));
     const entrySourceFiles = new Set(deps.entries.map((e) => resolve(e.sourceFile)));
-    const watchStartedAtMs = Date.now();
     const dirs = [...entryDirs, ...expandWatchPatterns(deps.watchDirs ?? [])];
+    // The probe sits on the watched filesystem: tmpdir() may be another mount with another clock.
+    // It is removed before the watchers start, so it raises no change event.
+    const watchStartedAtMs = probeFilesystemClockMs(dirs[0]);
     for (const dir of dirs) {
-        void watchDir(dir, (filename) => handleWatchedChange(deps, dir, filename, entrySourceFiles, watchStartedAtMs), deps.signal, deps.watchDirectory ?? watch);
+        void watchDir(dir, (filename) => {
+            void handleWatchedChange(deps, dir, filename, entrySourceFiles, watchStartedAtMs);
+        }, deps.signal, deps.watchDirectory ?? watch);
     }
 }

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

@@ -5,7 +5,9 @@ import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import type { ErrorDocsConfig } from "@cosmicdrift/kumiko-framework/errors";
 import type { PageHeadResolver, PageHeadSystemQuery } from "@cosmicdrift/kumiko-renderer/headless/apex";
 import type { SystemWireDeps } from "@cosmicdrift/kumiko-server-runtime/extra-routes-deps";
+import type { PwaOptions } from "@cosmicdrift/kumiko-server-runtime/pwa";
 import type { TestStack, TestStackOptions } from "@cosmicdrift/kumiko-testing/stack";
+import { startDevStylesheet } from "./create-kumiko-server-stylesheet.ts";
 import { type DirectoryWatchEvents } from "./create-kumiko-server-watcher.ts";
 import { type BunServer } from "./dev-server-runtime.ts";
 /** Multi-entry mode for apps that ship several separate bundles (e.g.
@@ -96,6 +98,8 @@ export type CreateKumikoServerOptions = {
     }>;
     /** @internal — replaces the native directory watcher in tests. */
     readonly _watchDirectory?: DirectoryWatchEvents;
+    /** @internal — replaces the Tailwind pipeline in tests. */
+    readonly _startStylesheet?: typeof startDevStylesheet;
     /** Absolute path to the CSS entry (typically styles.css with
      *  @import "tailwindcss"). The dev-server builds it with the Tailwind
      *  CLI and serves the result at /styles.css; `stylesheetWatch` decides
@@ -185,6 +189,8 @@ export type CreateKumikoServerOptions = {
      *  ships unchanged with status 200 — never a 500. `systemQuery` inside
      *  the resolver runs as the anonymous role, same as prod. */
     readonly resolvePageHead?: PageHeadResolver;
+    /** Installable web app, same option and same served files as `runProdApp`'s `pwa`. */
+    readonly pwa?: PwaOptions;
     /** Wraps the request handler before it reaches Bun.serve and `handle.fetch`, e.g. the demo read-only gate. */
     readonly wrapFetch?: (handler: (req: Request, socketAddress?: string) => Promise<Response>) => (req: Request, socketAddress?: string) => Promise<Response>;
 };

package/dist/create-kumiko-server.js

@@ -44,63 +44,75 @@ export async function createKumikoServer(options) {
     const entries = normalizeEntries(options);
     const buildBundle = options._buildBundle ?? buildClient;
     const clientBundles = await buildClientBundles(entries, buildBundle);
-    const stylesheet = await startDevStylesheet(options);
-    const templates = await loadHtmlTemplates(entries, options.htmlPath);
-    const dbMode = resolveDevDbMode(process.env);
-    const { stack, ownedRedisSseBroker } = await bootDevStack(options, dbMode);
-    const devJobRunners = await startDevBackgroundRunners(stack, dbMode.jobQueueNamePrefix);
-    // Built once purely to surface authoring warnings (settings-hub placement
-    // etc.) at the same point prod would; clients fetch the schema themselves
-    // from GET /api/schema, so the result is discarded.
-    buildAppSchema(stack.registry, {
-        authoringWarnings: true,
-        searchAdapterMissing: !stack.context.searchAdapter,
-    });
-    const reloadHub = createReloadHub();
-    const handleFetch = createDevFetchHandler({
-        options,
-        stack,
-        entries,
-        clientBundles,
-        templates,
-        stylesheetPath: stylesheet?.outPath,
-        reloadHub,
-    });
-    const server = startDevHttpServer(port, handleFetch, stack);
-    const watcherAbort = new AbortController();
-    const stop = createDevServerStop({
-        watcherAbort,
-        killTailwind: stylesheet?.kill,
-        server,
-        stack,
-        devJobRunners,
-        dbMode,
-        ownedRedisSseBroker,
-    });
-    startDevFileWatchers({
-        entries,
-        watchDirs: options.watchDirs,
-        watchDirectory: options._watchDirectory,
-        signal: watcherAbort.signal,
-        buildBundle,
-        clientBundles,
-        reloadHub,
-        stop,
-    });
-    if (options.installSignalHandlers ?? true)
-        installDevSignalHandlers(stop);
-    if (server !== undefined) {
-        logInfo(`[kumiko-server] listening on http://localhost:${port}` +
-            (entries.length > 0
-                ? ` (hot reload on ${entries.length === 1 ? "client entry" : `${entries.length} entries`})`
-                : ""));
+    const stylesheet = await (options._startStylesheet ?? startDevStylesheet)(options);
+    let stop;
+    try {
+        const templates = await loadHtmlTemplates(entries, options.htmlPath);
+        const dbMode = resolveDevDbMode(process.env);
+        const { stack, ownedRedisSseBroker } = await bootDevStack(options, dbMode);
+        const devJobRunners = await startDevBackgroundRunners(stack, dbMode.jobQueueNamePrefix);
+        // Built once purely to surface authoring warnings (settings-hub placement
+        // etc.) at the same point prod would; clients fetch the schema themselves
+        // from GET /api/schema, so the result is discarded.
+        buildAppSchema(stack.registry, {
+            authoringWarnings: true,
+            searchAdapterMissing: !stack.context.searchAdapter,
+        });
+        const reloadHub = createReloadHub();
+        const handleFetch = createDevFetchHandler({
+            options,
+            stack,
+            entries,
+            clientBundles,
+            templates,
+            stylesheetPath: stylesheet?.outPath,
+            reloadHub,
+        });
+        const server = startDevHttpServer(port, handleFetch, stack);
+        const watcherAbort = new AbortController();
+        stop = createDevServerStop({
+            watcherAbort,
+            killTailwind: stylesheet?.kill,
+            server,
+            stack,
+            devJobRunners,
+            dbMode,
+            ownedRedisSseBroker,
+        });
+        startDevFileWatchers({
+            entries,
+            watchDirs: options.watchDirs,
+            watchDirectory: options._watchDirectory,
+            signal: watcherAbort.signal,
+            buildBundle,
+            clientBundles,
+            reloadHub,
+            stop,
+        });
+        if (options.installSignalHandlers ?? true)
+            installDevSignalHandlers(stop);
+        if (server !== undefined) {
+            logInfo(`[kumiko-server] listening on http://localhost:${port}` +
+                (entries.length > 0
+                    ? ` (hot reload on ${entries.length === 1 ? "client entry" : `${entries.length} entries`})`
+                    : ""));
+        }
+        return {
+            fetch: handleFetch,
+            server,
+            stack,
+            stop,
+            jobQueueNamePrefix: dbMode.jobQueueNamePrefix,
+            sseChannelPrefix: dbMode.sseChannelPrefix,
+        };
+    }
+    catch (err) {
+        // Before stop() exists only the --watch child needs killing; once it exists, it tears down
+        // the server, stack, runners and watcher that a late failure would otherwise leak.
+        if (stop)
+            await stop();
+        else
+            stylesheet?.kill();
+        throw err;
     }
-    return {
-        fetch: handleFetch,
-        server,
-        stack,
-        stop,
-        jobQueueNamePrefix: dbMode.jobQueueNamePrefix,
-        sseChannelPrefix: dbMode.sseChannelPrefix,
-    };
 }

package/dist/dev-server-runtime.js

@@ -3,9 +3,7 @@
 // load without it: every Bun.* call is gated, and tests drive the fetch
 // handler directly instead of going through Bun.serve and real sockets.
 export const hasBun = typeof Bun !== "undefined";
-// @wrapper-known semantic-alias
 // biome-ignore lint/suspicious/noConsole: dev-server status logging
 export const logInfo = (msg) => console.log(msg);
-// @wrapper-known semantic-alias
 // biome-ignore lint/suspicious/noConsole: dev-server error logging
 export const logError = (...args) => console.error(...args);

package/dist/kebab.js

@@ -1,7 +1,6 @@
 // Segment-strict: rejects trailing/double hyphen so the name is a valid
 // package-name + folder (`my-shop`, not `my-` or `my--shop`).
 const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
-// @wrapper-known semantic-alias
 export function isKebabSegment(value) {
     return KEBAB_RE.test(value);
 }

package/dist/managed-files/bundled-lists-wiring.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `bundledLists` lives in kumiko.config.ts for the schema tooling and in the runner options for
+ * the running app. A runner call in bin/ that leaves it out would serve other screens than
+ * `kumiko check` validates.
+ */
+export declare function findBundledListsWiringErrors(appRoot: string): readonly string[];

package/dist/managed-files/bundled-lists-wiring.js

@@ -0,0 +1,67 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { APP_CONFIG_FILE } from "@cosmicdrift/kumiko-framework/config";
+import { Project, SyntaxKind } from "ts-morph";
+const RUNNER_NAMES = new Set(["runProdApp", "runDevApp", "runWorkerApp"]);
+const BUNDLED_LISTS = "bundledLists";
+function parseSource(fileName, source) {
+    const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+    return project.createSourceFile(fileName, source);
+}
+function declaresProperty(object, name) {
+    return object.getProperties().some((property) => {
+        if (property.isKind(SyntaxKind.ShorthandPropertyAssignment))
+            return property.getName() === name;
+        if (property.isKind(SyntaxKind.PropertyAssignment)) {
+            return property.getName().replace(/^["']|["']$/g, "") === name;
+        }
+        return false;
+    });
+}
+function hasSpread(object) {
+    return object.getProperties().some((property) => property.isKind(SyntaxKind.SpreadAssignment));
+}
+function firstObjectArgument(args) {
+    const first = args[0];
+    return first?.isKind(SyntaxKind.ObjectLiteralExpression) ? first : undefined;
+}
+function configDeclaresBundledLists(source) {
+    const call = parseSource(APP_CONFIG_FILE, source)
+        .getDescendantsOfKind(SyntaxKind.CallExpression)
+        .find((candidate) => candidate.getExpression().getText() === "defineAppConfig");
+    const config = call === undefined ? undefined : firstObjectArgument(call.getArguments());
+    return config !== undefined && declaresProperty(config, BUNDLED_LISTS);
+}
+function runnersWithoutBundledLists(fileName, source) {
+    return parseSource(fileName, source)
+        .getDescendantsOfKind(SyntaxKind.CallExpression)
+        .flatMap((call) => {
+        const runner = call.getExpression().getText();
+        if (!RUNNER_NAMES.has(runner))
+            return [];
+        const options = firstObjectArgument(call.getArguments());
+        // A spread may carry the key; the static check cannot see into it.
+        if (options === undefined || declaresProperty(options, BUNDLED_LISTS) || hasSpread(options)) {
+            return [];
+        }
+        return [runner];
+    });
+}
+/**
+ * `bundledLists` lives in kumiko.config.ts for the schema tooling and in the runner options for
+ * the running app. A runner call in bin/ that leaves it out would serve other screens than
+ * `kumiko check` validates.
+ */
+export function findBundledListsWiringErrors(appRoot) {
+    const configPath = join(appRoot, APP_CONFIG_FILE);
+    if (!existsSync(configPath) || !configDeclaresBundledLists(readFileSync(configPath, "utf-8"))) {
+        return [];
+    }
+    const binDir = join(appRoot, "bin");
+    if (!existsSync(binDir))
+        return [];
+    return readdirSync(binDir)
+        .filter((name) => name.endsWith(".ts"))
+        .sort()
+        .flatMap((name) => runnersWithoutBundledLists(name, readFileSync(join(binDir, name), "utf-8")).map((runner) => `bin/${name}: ${runner}() does not pass bundledLists although ${APP_CONFIG_FILE} sets it. Add \`bundledLists: appConfig.bundledLists\` to the runner options, otherwise the app serves other screens than \`kumiko check\` validates.`));
+}

package/dist/managed-files/registry.js

@@ -9,6 +9,7 @@ import { readStaticAppConfig, } from "@cosmicdrift/kumiko-guards/repo-manifest/a
 import { BUNFIG_FILES, renderBunfig } from "@cosmicdrift/kumiko-testing/bunfig";
 import { isKebabSegment } from "../kebab.js";
 import { readReleaseTarget, render, renderDeployFiles, } from "../scaffold-deploy.js";
+import { findBundledListsWiringErrors } from "./bundled-lists-wiring.js";
 import { addManagedMarker } from "./marker.js";
 import { findKumikoPinErrors } from "./pins.js";
 export const BIOME_PRESET = "@cosmicdrift/kumiko-framework/biome";
@@ -60,6 +61,7 @@ export function listManagedErrors(facts) {
             ".");
     }
     errors.push(...findKumikoPinErrors(readPackageJsonOrEmpty(facts.appRoot)));
+    errors.push(...findBundledListsWiringErrors(facts.appRoot));
     return errors;
 }
 function marked(path, body, style, executable = false) {

package/dist/run-dev-app-server-options.js

@@ -22,6 +22,7 @@ function pickDevServiceOptions(options) {
         ...(options.anonymousAccess !== undefined && { anonymousAccess: options.anonymousAccess }),
         ...(options.files !== undefined && { files: options.files }),
         ...(options.wire !== undefined && { wire: options.wire }),
+        ...(options.pwa !== undefined && { pwa: options.pwa }),
     };
 }
 export function buildDevServerOptions(deps) {

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

@@ -102,6 +102,8 @@ export type RunDevAppOptions = {
      *  through `runDevApp` show the same resolved head prod does. See
      *  `CreateKumikoServerOptions.resolvePageHead` for the full contract. */
     readonly resolvePageHead?: PageHeadResolver;
+    /** Installable web app, same option as `runProdApp`'s `pwa`; pass the same value to both. */
+    readonly pwa?: CreateKumikoServerOptions["pwa"];
     /** CSS entry. Defaults to the package export
      *  `@cosmicdrift/kumiko-renderer/web/styles.css` when a client entry is set.
      *  `false` disables the CSS pipeline. */

package/dist/scaffold-app.js

@@ -146,7 +146,6 @@ export async function scaffoldApp(options) {
     files.push("CLAUDE.md");
     return { destination, files, appName: options.name };
 }
-// @wrapper-known semantic-alias
 function write(path, content) {
     writeFileSync(path, content);
 }
@@ -156,7 +155,7 @@ function appScripts(testSetup) {
         build: "bun kumiko-build",
         start: "bun run bin/main.ts",
         boot: "KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts",
-        typecheck: "tsc --noEmit",
+        typecheck: "bun check --no-script",
         lint: "biome check .",
         check: "kumiko check",
         ...(testSetup?.scripts ?? { test: "bun --config=bunfig.toml test --dots" }),
@@ -171,6 +170,8 @@ function renderPackageJson(name, version, testSetup, infraRef) {
         version: "0.1.0",
         private: true,
         type: "module",
+        // `bun check` is built in from 1.4.4; older Bun resolves it to the app's `check` script.
+        engines: { bun: ">=1.4.4" },
         kumiko: { deploy: { infraRef } },
         scripts: appScripts(testSetup),
         dependencies: {
@@ -355,7 +356,8 @@ function renderMain(appName) {
     ]);
     // Subject-key KMS is optional locally (plaintext + loud warning) but required
     // under NODE_ENV=production.
-    return `// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after
+    return `// biome-ignore-all lint/style/noProcessEnv: KMS wiring and the demo admin password are read before runProdApp parses the env contract, and the scaffold has no bin/env.ts
+// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after
 // composeFeatures + validateBoot + createRegistry without DB/Redis-connect
 // (see @cosmicdrift/kumiko-server-runtime runProdApp).
 

package/dist/scaffold-blank-starter.js

@@ -45,7 +45,8 @@ export function renderBlankMain(appName) {
         { specifier: "../kumiko.config", names: [], defaultName: "appConfig" },
         { specifier: "./env-schema", names: ["envSchema"] },
     ]);
-    return `// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after
+    return `// biome-ignore-all lint/style/noProcessEnv: KMS wiring and the demo admin password are read before runProdApp parses the env contract, and the scaffold has no bin/env.ts
+// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after
 // composeFeatures + validateBoot + createRegistry without DB/Redis-connect
 // (see @cosmicdrift/kumiko-server-runtime runProdApp).
 

package/dist/scaffold-demo-tasks.js

@@ -3,6 +3,7 @@
 // functions emit the same shape into the user's repo.
 import { createBooleanField, createEntity, createNumberField, createTextField, defineEntityCreateHandler, defineEntityDeleteHandler, defineEntityDetailHandler, defineEntityListHandler, defineEntityUpdateHandler, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
 const taskEntity = createEntity({
+    description: "A to-do item with a title, status, priority and urgency flag.",
     fields: {
         title: createTextField({
             required: true,
@@ -38,6 +39,7 @@ const open = {
         },
     },
 };
+const described = (description) => ({ ...open, description });
 const TASKS_I18N = {
     "screen:task-list.title": { de: "Aufgaben", en: "Tasks" },
     "screen:task-edit.title": { de: "Aufgabe", en: "Task" },
@@ -53,11 +55,11 @@ export function createDemoTasksFeature() {
     return defineFeature("tasks", (r) => {
         r.translations({ keys: TASKS_I18N });
         r.entity({ name: "task", ...taskEntity });
-        r.writeHandler(defineEntityCreateHandler("task", taskEntity, open));
-        r.writeHandler(defineEntityUpdateHandler("task", taskEntity, open));
-        r.writeHandler(defineEntityDeleteHandler("task", taskEntity, open));
-        r.queryHandler(defineEntityListHandler("task", taskEntity, open));
-        r.queryHandler(defineEntityDetailHandler("task", taskEntity, open));
+        r.writeHandler(defineEntityCreateHandler("task", taskEntity, described("Creates a task.")));
+        r.writeHandler(defineEntityUpdateHandler("task", taskEntity, described("Updates a task.")));
+        r.writeHandler(defineEntityDeleteHandler("task", taskEntity, described("Deletes a task.")));
+        r.queryHandler(defineEntityListHandler("task", taskEntity, described("Lists all tasks.")));
+        r.queryHandler(defineEntityDetailHandler("task", taskEntity, described("Returns one task.")));
         r.screen(listScreen);
         r.screen(editScreen);
         r.nav({ id: "tasks", label: "tasks:nav.tasks", order: 10, screen: "tasks:screen:task-list" });
@@ -93,6 +95,7 @@ import type {
 import { tasksTranslationKeys } from "./i18n";
 
 const taskEntity = createEntity({
+  description: "A to-do item with a title, status, priority and urgency flag.",
   fields: {
     title: createTextField({
       required: true,
@@ -133,14 +136,16 @@ const open = {
   },
 } as const;
 
+const described = (description: string) => ({ ...open, description });
+
 export const tasksFeature = defineFeature("tasks", (r) => {
   r.translations({ keys: tasksTranslationKeys });
   r.entity({ name: "task", ...taskEntity });
-  r.writeHandler(defineEntityCreateHandler("task", taskEntity, open));
-  r.writeHandler(defineEntityUpdateHandler("task", taskEntity, open));
-  r.writeHandler(defineEntityDeleteHandler("task", taskEntity, open));
-  r.queryHandler(defineEntityListHandler("task", taskEntity, open));
-  r.queryHandler(defineEntityDetailHandler("task", taskEntity, open));
+  r.writeHandler(defineEntityCreateHandler("task", taskEntity, described("Creates a task.")));
+  r.writeHandler(defineEntityUpdateHandler("task", taskEntity, described("Updates a task.")));
+  r.writeHandler(defineEntityDeleteHandler("task", taskEntity, described("Deletes a task.")));
+  r.queryHandler(defineEntityListHandler("task", taskEntity, described("Lists all tasks.")));
+  r.queryHandler(defineEntityDetailHandler("task", taskEntity, described("Returns one task.")));
   r.screen(listScreen);
   r.screen(editScreen);
   r.nav({ id: "tasks", label: "tasks:nav.tasks", order: 10, screen: "tasks:screen:task-list" });

package/dist/scaffold-render-helpers.js

@@ -72,7 +72,6 @@ export function deriveTenantId(name) {
         state ^= ch.charCodeAt(0);
         state = Math.imul(state, 16777619) >>> 0;
     }
-    // @wrapper-known semantic-alias
     const hex = (n, len) => n.toString(16).padStart(len, "0").slice(0, len);
     const a = hex(state, 8);
     state ^= state << 13;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.413.1",
+  "version": "0.414.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.413.1",
-    "@cosmicdrift/kumiko-feature-ast": "0.413.1",
-    "@cosmicdrift/kumiko-framework": "0.413.1",
-    "@cosmicdrift/kumiko-renderer": "0.413.1",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.413.1",
-    "@cosmicdrift/kumiko-guards": "0.413.1",
-    "@cosmicdrift/kumiko-server-runtime": "0.413.1",
-    "@cosmicdrift/kumiko-testing": "0.413.1",
-    "@cosmicdrift/kumiko-types": "0.413.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.414.0",
+    "@cosmicdrift/kumiko-feature-ast": "0.414.0",
+    "@cosmicdrift/kumiko-framework": "0.414.0",
+    "@cosmicdrift/kumiko-renderer": "0.414.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.414.0",
+    "@cosmicdrift/kumiko-guards": "0.414.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.414.0",
+    "@cosmicdrift/kumiko-testing": "0.414.0",
+    "@cosmicdrift/kumiko-types": "0.414.0",
     "ts-morph": "^28.0.0",
     "zod": "^4.6.7"
   },

package/src/changes.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.414.0",
+    "type": "fix",
+    "title": "Scaffolded apps typecheck with bun check",
+    "detail": "The typecheck script of newly scaffolded apps and of the framework workspace now runs `bun check --no-script` instead of `tsc --noEmit`, which needs Bun 1.4.4 or newer. Existing apps keep their script until they change it."
+  },
+  {
+    "version": "0.414.0",
+    "type": "fix",
+    "title": "Deploy Dockerfile template no longer mentions migrate-step.sh",
+    "detail": "The comment in `deploy/Dockerfile.template` named a compose-host migrate step that the scaffold does not generate. It now only names the migrate-db initContainer of the k3s deployment."
+  },
+  {
+    "version": "0.414.0",
+    "type": "fix",
+    "title": "managed check reports a bin entry that does not pass bundledLists",
+    "detail": "When `kumiko.config.ts` sets `bundledLists`, every `runProdApp`, `runDevApp` and `runWorkerApp` call in `bin/*.ts` must pass `bundledLists` too; otherwise the managed-files check reports an error instead of the app drifting silently from its config."
+  },
+  {
+    "version": "0.414.0",
+    "type": "fix",
+    "title": "subpath imports of an optional runtime external count as an import",
+    "detail": "The server bundle only detected `import \"meilisearch\"`, so an app that imported just `meilisearch/token` and did not list `meilisearch` in its dependencies shipped a `dist-server/package.json` without it and crashed in production with `Cannot find package 'meilisearch'`. Subpath imports are detected now."
+  },
+  {
+    "version": "0.414.0",
+    "type": "fix",
+    "title": "dev server boots when KUMIKO_REDIS_PREFIX is set",
+    "detail": "The SSE channel prefix defaulted to a per-boot value that differs from `KUMIKO_REDIS_PREFIX`, which `redisNamespaceFromEnv` rejects. The prefix now falls back to `KUMIKO_REDIS_PREFIX` before the per-boot default."
+  },
   {
     "version": "0.411.0",
     "type": "improvement",

package/templates/deploy/Dockerfile.template

@@ -64,7 +64,7 @@ RUN bun install --production --frozen-lockfile
 COPY --from=build --chown=app:app /app/dist ./dist
 
 # Checked-in SQL migrations for the pre-deploy `kumiko schema apply` step
-# (migrate-db initContainer of the infra _app-deploy.yml on k3s, or migrate-step.sh on compose hosts).
+# (migrate-db initContainer of the infra _app-deploy.yml on k3s).
 # The shipped `kumiko-schema` bin reads `${INIT_CWD}/kumiko/migrations/*.sql`
 # (see ENV INIT_CWD=/app below). kumiko/schema.ts is NOT needed at runtime
 # (only generate reads it; apply is checksum-tracked SQL only).