@cosmicdrift/kumiko-dev-server 0.72.0 → 0.73.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "description": "Development server bootstrap for Kumiko apps. Bundles the client, mints dev-JWTs, injects the resolved AppSchema, and seeds an admin. Not for production.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -50,8 +50,8 @@
     "kumiko-schema-check": "./bin/kumiko-schema-check.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.72.0",
-    "@cosmicdrift/kumiko-framework": "0.72.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.73.0",
+    "@cosmicdrift/kumiko-framework": "0.73.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/welcome-banner.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { renderWelcomeBanner } from "../welcome-banner";
+
+describe("renderWelcomeBanner", () => {
+  test("includes URL + admin login + features dir + docs link", () => {
+    const banner = renderWelcomeBanner({
+      url: "http://localhost:3000",
+      admin: { email: "admin@demo.test", password: "changeme" },
+    });
+    expect(banner).toContain("http://localhost:3000");
+    expect(banner).toContain("admin@demo.test");
+    expect(banner).toContain("changeme");
+    expect(banner).toContain("src/features/");
+    expect(banner).toContain("docs.kumiko.rocks");
+  });
+
+  test("box rows are aligned (all the same printable width)", () => {
+    const banner = renderWelcomeBanner({
+      url: "http://localhost:3000",
+      admin: { email: "a@b.c", password: "x" },
+    });
+    const rows = banner.split("\n");
+    const widths = rows.map((r) => [...r].length);
+    expect(new Set(widths).size).toBe(1);
+  });
+
+  test("admin is optional (no-auth dev runs still get a banner)", () => {
+    const banner = renderWelcomeBanner({ url: "http://localhost:3000" });
+    expect(banner).toContain("http://localhost:3000");
+    expect(banner).not.toContain("Login als");
+  });
+
+  test("featuresDir + docsUrl overridable", () => {
+    const banner = renderWelcomeBanner({
+      url: "http://localhost:3000",
+      featuresDir: "app/modules/",
+      docsUrl: "https://internal.example.com/dev",
+    });
+    expect(banner).toContain("app/modules/");
+    expect(banner).toContain("internal.example.com/dev");
+  });
+});

package/src/index.ts

@@ -69,3 +69,4 @@ export type {
 export { scaffoldDeploy } from "./scaffold-deploy";
 export type { ScaffoldFeatureOptions, ScaffoldFeatureResult } from "./scaffold-feature";
 export { scaffoldFeature } from "./scaffold-feature";
+export { renderWelcomeBanner, type WelcomeBannerInput } from "./welcome-banner";

package/src/run-dev-app.ts

@@ -51,6 +51,7 @@ import {
   createKumikoServer,
   type KumikoServerHandle,
 } from "./create-kumiko-server";
+import { renderWelcomeBanner } from "./welcome-banner";
 
 // Re-export der shared Auth-Setup-Types damit Apps nur einen Import-Pfad
 // brauchen. PasswordResetSetup / EmailVerificationSetup leben in
@@ -177,6 +178,13 @@ export type RunDevAppOptions = {
    *  in einem seed-fn, weil die runtime stack.db braucht und die seed-
    *  Funktionen nach setupTestStack laufen. */
   readonly effectiveFeatures?: CreateKumikoServerOptions["effectiveFeatures"];
+  /** Print a first-run banner after the server starts (URL, admin login,
+   *  hot-reload hint, docs link). Default: off — apps that already log
+   *  their own startup shouldn't get double-printed. The scaffold template
+   *  (create-kumiko-app) flips this on so the first `bun dev` ends on
+   *  something the user can click. Pass an object to override the
+   *  features-dir hint or the docs URL. */
+  readonly welcomeBanner?: boolean | { readonly featuresDir?: string; readonly docsUrl?: string };
 };
 
 export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServerHandle> {
@@ -304,7 +312,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
         }
       : {};
 
-  return createKumikoServer({
+  const handle = await createKumikoServer({
     features,
     ...(options.clientEntry !== undefined && { clientEntry: options.clientEntry }),
     ...(options.clientEntries !== undefined && { clientEntries: options.clientEntries }),
@@ -407,6 +415,26 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
       }
     },
   });
+
+  if (options.welcomeBanner) {
+    const overrides = typeof options.welcomeBanner === "object" ? options.welcomeBanner : {};
+    const port = handle.server?.port ?? options.port ?? 3000;
+    const banner = renderWelcomeBanner({
+      url: `http://localhost:${port}`,
+      ...(options.auth?.admin && {
+        admin: {
+          email: options.auth.admin.email,
+          password: options.auth.admin.password,
+        },
+      }),
+      ...(overrides.featuresDir !== undefined && { featuresDir: overrides.featuresDir }),
+      ...(overrides.docsUrl !== undefined && { docsUrl: overrides.docsUrl }),
+    });
+    // biome-ignore lint/suspicious/noConsole: boot-time UX print, opt-in via welcomeBanner.
+    console.log(`\n${banner}\n`);
+  }
+
+  return handle;
 }
 
 // Exported for the wiring-contract test (config-resolver-default.integration):

package/src/welcome-banner.ts

@@ -0,0 +1,46 @@
+// First-run welcome banner for `runDevApp({ welcomeBanner: true })`.
+// Opt-in only — `bun dev` should not normalize this for apps that
+// already log their own startup. Scaffolded apps (create-kumiko-app)
+// flip it on so the first `bun dev` doesn't end on "Server läuft" with
+// the user wondering where to click.
+
+export type WelcomeBannerInput = {
+  /** Resolved listen-URL (`http://localhost:3000`). */
+  readonly url: string;
+  /** Login the seeded admin uses (from runDevApp options.auth.admin). */
+  readonly admin?: { readonly email: string; readonly password: string };
+  /** Hot-reload hint shown in the "add a feature" line. Defaults to
+   *  `src/features/`. */
+  readonly featuresDir?: string;
+  /** Custom docs URL — defaults to the public docs site. */
+  readonly docsUrl?: string;
+};
+
+export function renderWelcomeBanner(input: WelcomeBannerInput): string {
+  const featuresDir = input.featuresDir ?? "src/features/";
+  const docsUrl = input.docsUrl ?? "https://docs.kumiko.rocks/quickstart";
+
+  const lines: string[] = [];
+  lines.push(`✓ kumiko-app läuft`);
+  lines.push(`→ Browser:        ${input.url}`);
+  if (input.admin) {
+    lines.push(`→ Login als:      ${input.admin.email} / ${input.admin.password}`);
+  }
+  lines.push(`→ Feature add:    edit ${featuresDir}`);
+  lines.push(`→ Docs:           ${docsUrl}`);
+
+  const innerWidth = Math.max(...lines.map((l) => stringWidth(l)));
+  const border = "─".repeat(innerWidth + 2);
+  const top = `┌${border}┐`;
+  const bottom = `└${border}┘`;
+  const padded = lines.map((l) => `│ ${l}${" ".repeat(innerWidth - stringWidth(l))} │`);
+  return [top, ...padded, bottom].join("\n");
+}
+
+// Plain monospace-cell width — counts each codepoint as one cell. Good
+// enough for ASCII + the small set of arrows/checkmarks used above; if a
+// real wide-char ever lands in the banner the row alignment will drift,
+// caught visually by the snapshot test.
+function stringWidth(s: string): number {
+  return [...s].length;
+}