@cosmicdrift/kumiko-dev-server 0.72.0 → 0.74.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.72.0",
+  "version": "0.74.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.74.0",
+    "@cosmicdrift/kumiko-framework": "0.74.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/scaffold-app.test.ts

@@ -119,6 +119,43 @@ describe("scaffoldApp", () => {
     expect(() => scaffoldApp({ name: "existing", destination: dest })).toThrow(/already exists/);
   });
 
+  test("features-param: custom selection lands in run-config.ts imports + APP_FEATURES", () => {
+    const dest = join(tmp, "custom-features");
+    scaffoldApp({
+      name: "custom-features",
+      destination: dest,
+      features: [
+        {
+          name: "tenant",
+          importPath: "@cosmicdrift/kumiko-bundled-features/tenant",
+          exportName: "createTenantFeature",
+          callExpression: "createTenantFeature()",
+        },
+        {
+          name: "billing-foundation",
+          importPath: "@cosmicdrift/kumiko-bundled-features/billing-foundation",
+          exportName: "billingFoundationFeature",
+          callExpression: "billingFoundationFeature",
+        },
+      ],
+    });
+    const cfg = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
+    expect(cfg).toContain('from "@cosmicdrift/kumiko-bundled-features/tenant"');
+    expect(cfg).toContain('from "@cosmicdrift/kumiko-bundled-features/billing-foundation"');
+    expect(cfg).toContain("createTenantFeature()");
+    expect(cfg).toContain("billingFoundationFeature");
+    expect(cfg).not.toContain("createSecretsFeature");
+    expect(cfg).not.toContain("createSessionsFeature");
+  });
+
+  test("features-param: empty array falls back to foundation (backwards-compat)", () => {
+    const dest = join(tmp, "empty-features");
+    scaffoldApp({ name: "empty-features", destination: dest, features: [] });
+    const cfg = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
+    expect(cfg).toContain("createSecretsFeature()");
+    expect(cfg).toContain("createSessionsFeature()");
+  });
+
   test("deterministic tenantId for same name (reproducible boots)", () => {
     const a = join(tmp, "a");
     const b = join(tmp, "b");

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

@@ -54,7 +54,11 @@ export type {
   SignupSetup,
 } from "./run-prod-app";
 export { runProdApp } from "./run-prod-app";
-export type { ScaffoldAppOptions, ScaffoldAppResult } from "./scaffold-app";
+export type {
+  ScaffoldAppOptions,
+  ScaffoldAppResult,
+  ScaffoldFeatureEntry,
+} from "./scaffold-app";
 export { scaffoldApp } from "./scaffold-app";
 export type {
   ScaffoldAppFeatureOptions,
@@ -69,3 +73,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/scaffold-app.ts

@@ -16,6 +16,18 @@ import { join, resolve } from "node:path";
 import { IndentationText, Project, VariableDeclarationKind } from "ts-morph";
 import { isKebabSegment } from "./kebab";
 
+// Single bundled-feature entry the scaffolder mounts into run-config.ts.
+// importPath is the from-spec ("@cosmicdrift/kumiko-bundled-features/files"),
+// exportName the named import, callExpression the form that lands in the
+// APP_FEATURES array literal — typically `${exportName}()` for factory-style
+// features and just `${exportName}` for object-style ones (e.g. billingFoundationFeature).
+export type ScaffoldFeatureEntry = {
+  readonly name: string;
+  readonly importPath: string;
+  readonly exportName: string;
+  readonly callExpression: string;
+};
+
 export type ScaffoldAppOptions = {
   /** kebab-case app name (e.g. "my-shop"). Becomes package-name + folder. */
   readonly name: string;
@@ -28,6 +40,10 @@ export type ScaffoldAppOptions = {
   readonly cwd?: string;
   /** npm-version-pin for @cosmicdrift/* deps. Default "*" for latest. */
   readonly frameworkVersion?: string;
+  /** Bundled-features to mount in run-config.ts. Default: secrets + sessions
+   *  (the historical foundation). create-kumiko-app passes the picker output
+   *  here so the generated APP_FEATURES reflects the user's selection. */
+  readonly features?: ReadonlyArray<ScaffoldFeatureEntry>;
 };
 
 export type ScaffoldAppResult = {
@@ -58,7 +74,7 @@ export function scaffoldApp(options: ScaffoldAppOptions): ScaffoldAppResult {
   write(join(destination, "tsconfig.json"), renderTsconfig());
   files.push("tsconfig.json");
 
-  write(join(destination, "src", "run-config.ts"), renderRunConfig());
+  write(join(destination, "src", "run-config.ts"), renderRunConfig(options.features));
   files.push("src/run-config.ts");
 
   write(join(destination, "bin", "main.ts"), renderMain(options.name));
@@ -133,26 +149,44 @@ function newTsProject(): Project {
   });
 }
 
-function renderRunConfig(): string {
+const FOUNDATION_FEATURES: ReadonlyArray<ScaffoldFeatureEntry> = [
+  {
+    name: "secrets",
+    importPath: "@cosmicdrift/kumiko-bundled-features/secrets",
+    exportName: "createSecretsFeature",
+    callExpression: "createSecretsFeature()",
+  },
+  {
+    name: "sessions",
+    importPath: "@cosmicdrift/kumiko-bundled-features/sessions",
+    exportName: "createSessionsFeature",
+    callExpression: "createSessionsFeature()",
+  },
+];
+
+function renderRunConfig(features?: ReadonlyArray<ScaffoldFeatureEntry>): string {
   const project = newTsProject();
   const sf = project.createSourceFile("run-config.ts", "");
 
-  sf.addImportDeclaration({
-    moduleSpecifier: "@cosmicdrift/kumiko-bundled-features/secrets",
-    namedImports: ["createSecretsFeature"],
-  });
-  sf.addImportDeclaration({
-    moduleSpecifier: "@cosmicdrift/kumiko-bundled-features/sessions",
-    namedImports: ["createSessionsFeature"],
-  });
+  const effective = features && features.length > 0 ? features : FOUNDATION_FEATURES;
+  const grouped = new Map<string, string[]>();
+  for (const entry of effective) {
+    const existing = grouped.get(entry.importPath) ?? [];
+    if (!existing.includes(entry.exportName)) existing.push(entry.exportName);
+    grouped.set(entry.importPath, existing);
+  }
+  for (const [importPath, namedImports] of grouped) {
+    sf.addImportDeclaration({ moduleSpecifier: importPath, namedImports });
+  }
 
+  const callList = effective.map((f) => f.callExpression).join(", ");
   sf.addVariableStatement({
     declarationKind: VariableDeclarationKind.Const,
     isExported: true,
     declarations: [
       {
         name: "APP_FEATURES",
-        initializer: "[createSecretsFeature(), createSessionsFeature()] as const",
+        initializer: `[${callList}] as const`,
       },
     ],
   });
@@ -161,9 +195,9 @@ function renderRunConfig(): string {
     0,
     [
       "// Single source of truth für die Feature-Komposition deiner App.",
-      "// Bundled-Foundation: secrets + sessions. config/user/tenant/auth-email-password",
-      "// werden via composeFeatures(includeBundled:true) automatisch ergänzt",
-      "// wenn runProdApp mit `auth: {…}` aufgerufen wird (siehe bin/main.ts).",
+      "// config/user/tenant/auth-email-password werden via",
+      "// composeFeatures(includeBundled:true) automatisch ergänzt wenn",
+      "// runProdApp mit `auth: {…}` aufgerufen wird (siehe bin/main.ts).",
       "//",
       "// Neue features hinzufügen:",
       "//   - bunx @cosmicdrift/kumiko-cli add feature <name>  (DX-2, automatisch)",

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;
+}