@cosmicdrift/kumiko-dev-server 0.75.0 → 0.77.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.75.0",
+  "version": "0.77.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.75.0",
-    "@cosmicdrift/kumiko-framework": "0.75.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.77.0",
+    "@cosmicdrift/kumiko-framework": "0.77.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

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

@@ -15,7 +15,7 @@ describe("scaffoldApp", () => {
     rmSync(tmp, { recursive: true, force: true });
   });
 
-  test("scaffolds 6 files into <cwd>/<name>", () => {
+  test("scaffolds the expected files into <cwd>/<name>", () => {
     const dest = join(tmp, "my-shop");
     const result = scaffoldApp({ name: "my-shop", destination: dest });
 
@@ -26,6 +26,7 @@ describe("scaffoldApp", () => {
       "tsconfig.json",
       "src/run-config.ts",
       "bin/main.ts",
+      "bin/dev.ts",
       ".env.example",
       "README.md",
     ]);
@@ -48,6 +49,53 @@ describe("scaffoldApp", () => {
     expect(pkg.dependencies["@cosmicdrift/kumiko-dev-server"]).toBe("^0.13.0");
     expect(pkg.dependencies["@cosmicdrift/kumiko-framework"]).toBe("^0.13.0");
     expect(pkg.scripts["boot"]).toContain("KUMIKO_DRY_RUN_ENV=boot");
+    expect(pkg.scripts["dev"]).toBe("bun --watch bin/dev.ts");
+  });
+
+  test("bin/dev.ts contains runDevApp + welcomeBanner + admin login", () => {
+    const dest = join(tmp, "my-shop");
+    scaffoldApp({ name: "my-shop", destination: dest });
+
+    const dev = readFileSync(join(dest, "bin/dev.ts"), "utf-8");
+    expect(dev).toContain("runDevApp");
+    expect(dev).toContain("welcomeBanner: true");
+    expect(dev).toContain("admin@my-shop.local");
+    expect(dev).toContain(`password: "changeme"`);
+  });
+
+  test(".env.example carries KUMIKO_DEV_DB_NAME default so reboots are persistent", () => {
+    const dest = join(tmp, "my-shop");
+    scaffoldApp({ name: "my-shop", destination: dest });
+
+    const env = readFileSync(join(dest, ".env.example"), "utf-8");
+    expect(env).toContain("KUMIKO_DEV_DB_NAME=my_shop_dev");
+  });
+
+  test("README lists the mounted features dynamically", () => {
+    const dest = join(tmp, "my-shop");
+    scaffoldApp({
+      name: "my-shop",
+      destination: dest,
+      features: [
+        {
+          name: "tenant",
+          importPath: "@cosmicdrift/kumiko-bundled-features/tenant",
+          exportName: "createTenantFeature",
+          callExpression: "createTenantFeature()",
+        },
+        {
+          name: "delivery",
+          importPath: "@cosmicdrift/kumiko-bundled-features/delivery",
+          exportName: "createDeliveryFeature",
+          callExpression: "createDeliveryFeature()",
+        },
+      ],
+    });
+
+    const readme = readFileSync(join(dest, "README.md"), "utf-8");
+    expect(readme).toContain("## Mounted features");
+    expect(readme).toContain("- `tenant`");
+    expect(readme).toContain("- `delivery`");
   });
 
   test("bin/main.ts contains runProdApp + auth.admin stub", () => {

package/src/__tests__/scaffold-dev-cycle.integration.test.ts

@@ -0,0 +1,109 @@
+// Phase-2 Validator (Plan-Doc create-kumiko-app.md, Risk #1): pinnt dass
+// setupTestStack auf persistent DB einen Reboot mit erweitertem Feature-Set
+// überlebt — eine neue r.entity ohne Migration-CLI muss die Tabelle anlegen,
+// und ein bereits existierendes Entity darf nicht crashen (duplicate CREATE).
+//
+// Das ist der Pfad den `bun dev` mit KUMIKO_DEV_DB_NAME triggert: der
+// Dev-User editiert src/features/notes.ts, `bun --watch` rebootet den Process,
+// runDevApp ruft createKumikoServer → setupTestStack mit denselben DB-Name
+// auf, und das neue Notes-Entity muss als Tabelle erscheinen ohne dass der
+// User `kumiko schema apply` aufgerufen hat. Bricht der Filter in
+// push-entity-projection-tables (test-stack.ts:200-209), lügt der Dev-Flow.
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { asRawClient, createDbConnection, tableExists } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  pushEntityProjectionTables,
+  setupTestStack,
+  type TestStack,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+
+const baseEntity = createEntity({
+  fields: { title: createTextField({ required: true }) },
+  table: "phase2_base_thing",
+});
+
+const noteEntity = createEntity({
+  fields: { title: createTextField({ required: true }) },
+  table: "phase2_note",
+});
+
+const baseFeature: FeatureDefinition = defineFeature("phase2-base", (r) => {
+  r.entity("base-thing", baseEntity);
+});
+
+const notesFeature: FeatureDefinition = defineFeature("phase2-notes", (r) => {
+  r.entity("note", noteEntity);
+});
+
+const dbName = `kumiko_phase2_${generateId().slice(-8)}`;
+
+afterAll(async () => {
+  const base = process.env["TEST_DATABASE_URL"];
+  if (!base) return;
+  const adminUrl = base.replace(/\/[^/]+$/, "/postgres");
+  const admin = createDbConnection(adminUrl, { maxConnections: 1 });
+  try {
+    await asRawClient(admin.db).unsafe(`DROP DATABASE IF EXISTS "${dbName}"`);
+  } finally {
+    await admin.close();
+  }
+});
+
+describe("scaffold dev cycle (Phase 2 Validator)", () => {
+  test("persistent reboot with added entity creates only the new table", async () => {
+    const base = process.env["TEST_DATABASE_URL"];
+    if (!base) throw new Error("TEST_DATABASE_URL required");
+
+    // Boot 1: only base feature, persistent DB.
+    const stack1: TestStack = await setupTestStack({
+      features: [baseFeature],
+      dbName,
+      persistentDb: true,
+    });
+    try {
+      await pushEntityProjectionTables(stack1, stack1.registry);
+      expect(await tableExists(stack1.db, "public.phase2_base_thing")).toBe(true);
+      expect(await tableExists(stack1.db, "public.phase2_note")).toBe(false);
+    } finally {
+      await stack1.cleanup();
+    }
+
+    // Boot 2: base + notes — simulates the Dev-User edit + bun --watch reboot.
+    // pushEntityProjectionTables MUSS phase2_base_thing skippen (existiert)
+    // und phase2_note neu anlegen — sonst crash auf duplicate CREATE TABLE
+    // oder die Notes-Tabelle fehlt.
+    const stack2: TestStack = await setupTestStack({
+      features: [baseFeature, notesFeature],
+      dbName,
+      persistentDb: true,
+    });
+    try {
+      await pushEntityProjectionTables(stack2, stack2.registry);
+      expect(await tableExists(stack2.db, "public.phase2_base_thing")).toBe(true);
+      expect(await tableExists(stack2.db, "public.phase2_note")).toBe(true);
+    } finally {
+      await stack2.cleanup();
+    }
+
+    // Boot 3 with same feature-set must remain idempotent (no double-CREATE).
+    const stack3: TestStack = await setupTestStack({
+      features: [baseFeature, notesFeature],
+      dbName,
+      persistentDb: true,
+    });
+    try {
+      await pushEntityProjectionTables(stack3, stack3.registry);
+      expect(await tableExists(stack3.db, "public.phase2_note")).toBe(true);
+    } finally {
+      await stack3.cleanup();
+    }
+  });
+});

package/src/__tests__/walkthrough.integration.test.ts

@@ -4,7 +4,7 @@
 // docs without an actual `bunx … && bun install && bun run boot` CI run.
 //
 // What this test pins:
-//   - scaffoldApp produces the 6 files the walkthrough lists
+//   - scaffoldApp produces the files the walkthrough lists
 //   - scaffoldAppFeature scaffolds + auto-mounts (the diff-block shown)
 //   - composeFeatures(includeBundled:true) yields the exact feature-count
 //     the walkthrough advertises in "Expected output"
@@ -32,13 +32,14 @@ describe("walkthrough — DX-3.1 snapshot", () => {
     rmSync(tmp, { recursive: true, force: true });
   });
 
-  test("Step 1 (kumiko new app) — produces walkthrough's 6 files", () => {
+  test("Step 1 (kumiko new app) — produces walkthrough's scaffold files", () => {
     const result = scaffoldApp({ name: "my-notes", destination: appRoot });
     expect(result.files).toEqual([
       "package.json",
       "tsconfig.json",
       "src/run-config.ts",
       "bin/main.ts",
+      "bin/dev.ts",
       ".env.example",
       "README.md",
     ]);

package/src/scaffold-app.ts

@@ -80,10 +80,13 @@ export function scaffoldApp(options: ScaffoldAppOptions): ScaffoldAppResult {
   write(join(destination, "bin", "main.ts"), renderMain(options.name));
   files.push("bin/main.ts");
 
-  write(join(destination, ".env.example"), renderEnvExample());
+  write(join(destination, "bin", "dev.ts"), renderDev(options.name));
+  files.push("bin/dev.ts");
+
+  write(join(destination, ".env.example"), renderEnvExample(options.name));
   files.push(".env.example");
 
-  write(join(destination, "README.md"), renderReadme(options.name));
+  write(join(destination, "README.md"), renderReadme(options.name, options.features));
   files.push("README.md");
 
   return { destination, files, appName: options.name };
@@ -102,6 +105,7 @@ function renderPackageJson(name: string, version: string): string {
       private: true,
       type: "module",
       scripts: {
+        dev: "bun --watch bin/dev.ts",
         boot: "KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts",
         check: "tsc --noEmit",
       },
@@ -313,7 +317,81 @@ function renderMain(appName: string): string {
   return sf.getFullText();
 }
 
-function renderEnvExample(): string {
+function renderDev(appName: string): string {
+  const tenantId = deriveTenantId(appName);
+  const project = newTsProject();
+  const sf = project.createSourceFile("dev.ts", "");
+
+  sf.addImportDeclaration({
+    moduleSpecifier: "@cosmicdrift/kumiko-dev-server",
+    namedImports: ["runDevApp"],
+  });
+  sf.addImportDeclaration({
+    moduleSpecifier: "@cosmicdrift/kumiko-framework/engine",
+    isTypeOnly: true,
+    namedImports: ["TenantId"],
+  });
+  sf.addImportDeclaration({
+    moduleSpecifier: "../src/run-config",
+    namedImports: ["APP_FEATURES"],
+  });
+
+  sf.addVariableStatement({
+    declarationKind: VariableDeclarationKind.Const,
+    declarations: [
+      {
+        name: "DEFAULT_TENANT_ID",
+        initializer: `"${tenantId}" as TenantId`,
+      },
+    ],
+  });
+
+  sf.addStatements((writer) => {
+    writer
+      .write("await runDevApp(")
+      .inlineBlock(() => {
+        writer.writeLine("features: APP_FEATURES,");
+        writer.writeLine("welcomeBanner: true,");
+        writer.write("auth: ").inlineBlock(() => {
+          writer.write("admin: ").inlineBlock(() => {
+            writer.writeLine(`email: "admin@${appName}.local",`);
+            writer.writeLine(`password: "changeme",`);
+            writer.writeLine(`displayName: "Admin",`);
+            writer.write("memberships: [");
+            writer.indent(() => {
+              writer.inlineBlock(() => {
+                writer.writeLine("tenantId: DEFAULT_TENANT_ID,");
+                writer.writeLine(`tenantKey: "${appName}",`);
+                writer.writeLine(`tenantName: "${appName}",`);
+                writer.writeLine(`roles: ["TenantAdmin"],`);
+              });
+              writer.write(",");
+            });
+            writer.write("],");
+          });
+        });
+      })
+      .write(");");
+  });
+
+  sf.insertText(
+    0,
+    [
+      "// Dev-bootstrap. `bun --watch bin/dev.ts` (siehe package.json scripts.dev)",
+      "// startet einen full-featured Dev-Server mit Auto-Reload bei Code-Änderungen.",
+      "// setupTestStack legt fehlende Entity-Tabellen automatisch an — neues",
+      "// r.entity(...) in einem Feature führt beim nächsten Reboot zu CREATE TABLE,",
+      "// kein manuelles `kumiko schema apply` nötig (das gilt nur für Prod).",
+      "// Persistent-DB via KUMIKO_DEV_DB_NAME (.env) damit Admin + Daten Reboots überleben.",
+      "",
+      "",
+    ].join("\n"),
+  );
+
+  return sf.getFullText();
+}
+
+function renderEnvExample(appName: string): string {
   return `# Required env-vars für boot-mode + dev. Production: über Pulumi/k8s-Secrets.
 DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/app
 REDIS_URL=redis://127.0.0.1:6379
@@ -324,37 +402,62 @@ JWT_SECRET=change-me-min-32-chars-change-me-min-32
 # KUMIKO_SECRETS_MASTER_KEY_V1: base64-encoded 32 bytes (AES-256 KEK).
 # Generate with: openssl rand -base64 32
 KUMIKO_SECRETS_MASTER_KEY_V1=
+
+# Dev-only: persistente DB für \`bun dev\`. Ohne diesen Var startet jeder Reboot
+# eine frische kumiko_test_<random>-DB → Admin-Login + Daten weg bei jedem Edit.
+# Mit Var bleibt die DB zwischen Reboots erhalten (Schema-Pushes sind idempotent).
+KUMIKO_DEV_DB_NAME=${appName.replace(/-/g, "_")}_dev
 `;
 }
 
-function renderReadme(appName: string): string {
+function renderReadme(
+  appName: string,
+  features: ReadonlyArray<ScaffoldFeatureEntry> | undefined,
+): string {
+  const featureList =
+    features && features.length > 0
+      ? features.map((f) => `- \`${f.name}\``).join("\n")
+      : "- `secrets` (foundation)\n- `sessions` (foundation)";
   return `# ${appName}
 
-Scaffolded by \`kumiko new app\`. Boots out-of-the-box with secrets + sessions
-mounted (foundation set). Add features with \`bunx @cosmicdrift/kumiko-cli add feature <name>\`.
+Scaffolded by \`bun create kumiko-app\`. Boots out-of-the-box with the picked
+feature stack mounted. Add features by editing \`src/run-config.ts\` or via
+\`bunx @cosmicdrift/kumiko-cli add feature <name>\`.
+
+## Mounted features
+
+${featureList}
 
-## First boot
+Edit \`src/run-config.ts\` to add or remove.
+
+## First run
 
 \`\`\`sh
 bun install
 cp .env.example .env
-# edit .env — set JWT_SECRET + KUMIKO_SECRETS_MASTER_KEY_V1
-bun run boot
+# edit .env — set JWT_SECRET + KUMIKO_SECRETS_MASTER_KEY_V1, point DATABASE_URL/REDIS_URL at a real PG+Redis
+docker compose up -d   # if you don't have PG+Redis running already
+bun dev
 \`\`\`
 
-Expected: \`[runProdApp] boot validation OK (… features, … registry entries)\` + exit 0.
+The dev-server prints a welcome banner with the URL + admin login when ready.
+Edits to \`src/features/**\` trigger a process restart (\`bun --watch\`); new
+\`r.entity(...)\` calls auto-create tables on reboot — no manual migration.
 
-## Adding features
+## Boot-only smoke (no DB needed)
 
 \`\`\`sh
-bunx @cosmicdrift/kumiko-cli add feature my-domain
-# → editiert src/run-config.ts automatisch + scaffolded src/features/my-domain/
+bun run boot
 \`\`\`
 
+Runs \`KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts\` — validates feature composition
++ env schema, exits 0 without touching DB/Redis. Useful in CI.
+
 ## Architecture
 
 - \`src/run-config.ts\` — single source of truth: which features your app mounts.
-- \`bin/main.ts\` — production-bootstrap. Reads env, mounts features, starts server.
+- \`bin/dev.ts\` — dev-server entry (\`bun dev\`).
+- \`bin/main.ts\` — production-bootstrap (\`bun run boot\` smoke + production deploy).
 
 For full docs see https://docs.kumiko.rocks.
 `;