@cosmicdrift/kumiko-dev-server 1.0.0 → 2.0.0

package/src/scaffold-app.ts

@@ -19,9 +19,17 @@ import {
   writeSnapshotJson,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";
 import { IndentationText, Project, VariableDeclarationKind } from "ts-morph";
-import { composeFeatures } from "./compose-features";
 import { isKebabSegment } from "./kebab";
+import {
+  createDemoTasksFeature,
+  renderDemoSeedFile,
+  renderDemoTasksFeatureFile,
+  renderDemoTasksI18n,
+  renderDemoTasksIndex,
+  renderDemoTasksWebIndex,
+} from "./scaffold-demo-tasks";
 import { scaffoldDeploy } from "./scaffold-deploy";
 
 // Single bundled-feature entry the scaffolder mounts into run-config.ts.
@@ -34,6 +42,8 @@ export type ScaffoldFeatureEntry = {
   readonly importPath: string;
   readonly exportName: string;
   readonly callExpression: string;
+  /** Runtime args for factory-style exports that need config the codegen text can't parse back out (e.g. `{ scopes: {} }`). Omit for zero-arg factories and object-style exports. */
+  readonly callArgs?: readonly unknown[];
 };
 
 export type ScaffoldAppOptions = {
@@ -95,6 +105,21 @@ export async function scaffoldApp(options: ScaffoldAppOptions): Promise<Scaffold
   write(join(destination, "src", "run-config.ts"), renderRunConfig(options.features));
   files.push("src/run-config.ts");
 
+  mkdirSync(join(destination, "src", "features", "tasks", "web"), { recursive: true });
+  write(join(destination, "src", "features", "tasks", "feature.ts"), renderDemoTasksFeatureFile());
+  files.push("src/features/tasks/feature.ts");
+  write(join(destination, "src", "features", "tasks", "i18n.ts"), renderDemoTasksI18n());
+  files.push("src/features/tasks/i18n.ts");
+  write(join(destination, "src", "features", "tasks", "index.ts"), renderDemoTasksIndex());
+  files.push("src/features/tasks/index.ts");
+  write(
+    join(destination, "src", "features", "tasks", "web", "index.ts"),
+    renderDemoTasksWebIndex(),
+  );
+  files.push("src/features/tasks/web/index.ts");
+  write(join(destination, "src", "seed.ts"), renderDemoSeedFile());
+  files.push("src/seed.ts");
+
   write(join(destination, "kumiko", "schema.ts"), renderKumikoSchema());
   files.push("kumiko/schema.ts");
 
@@ -107,7 +132,7 @@ export async function scaffoldApp(options: ScaffoldAppOptions): Promise<Scaffold
   write(join(destination, "bin", "kumiko.ts"), renderBinKumiko());
   files.push("bin/kumiko.ts");
 
-  write(join(destination, "src", "client.tsx"), renderClient());
+  write(join(destination, "src", "client.tsx"), renderClient(options.name));
   files.push("src/client.tsx");
 
   write(join(destination, "src", "styles.css"), renderStylesCss());
@@ -163,6 +188,7 @@ function renderPackageJson(name: string, version: string): string {
         "@cosmicdrift/kumiko-dev-server": version,
         "@cosmicdrift/kumiko-framework": version,
         "@cosmicdrift/kumiko-renderer-web": version,
+        "@cosmicdrift/kumiko-server-runtime": version,
         react: "^19.2.6",
         "react-dom": "^19.2.6",
         zod: "^4.4.3",
@@ -170,6 +196,8 @@ function renderPackageJson(name: string, version: string): string {
       devDependencies: {
         "@biomejs/biome": "^2.4.15",
         "@tailwindcss/cli": "^4.3.0",
+        "@types/react": "^19.2.0",
+        "@types/react-dom": "^19.2.0",
         "bun-types": "^1.3.14",
         tailwindcss: "^4.3.0",
         typescript: "^6.0.3",
@@ -345,15 +373,19 @@ function renderRunConfig(features?: ReadonlyArray<ScaffoldFeatureEntry>): string
   for (const [importPath, namedImports] of grouped) {
     sf.addImportDeclaration({ moduleSpecifier: importPath, namedImports });
   }
+  sf.addImportDeclaration({
+    moduleSpecifier: "./features/tasks",
+    namedImports: ["tasksFeature"],
+  });
 
-  const callList = effective.map((f) => f.callExpression).join(", ");
+  const callExprs = [...effective.map((f) => f.callExpression), "tasksFeature"];
   sf.addVariableStatement({
     declarationKind: VariableDeclarationKind.Const,
     isExported: true,
     declarations: [
       {
         name: "APP_FEATURES",
-        initializer: `[${callList}] as const`,
+        initializer: `[${callExprs.join(", ")}] as const`,
       },
     ],
   });
@@ -367,14 +399,14 @@ function renderRunConfig(features?: ReadonlyArray<ScaffoldFeatureEntry>): string
   sf.insertText(
     0,
     [
-      "// Single source of truth für die Feature-Komposition deiner App.",
-      "// config/user/tenant/auth-email-password werden via",
-      "// composeFeatures(includeBundled:true) automatisch ergänzt wenn",
-      "// runProdApp mit `auth: {…}` aufgerufen wird (siehe bin/main.ts).",
+      "// Single source of truth for your app's feature composition.",
+      "// config/user/tenant/auth-email-password are added automatically",
+      "// via composeFeatures(includeBundled:true) when runProdApp is called",
+      "// with `auth: {…}` (see bin/main.ts).",
       "//",
-      "// Neue features hinzufügen:",
-      "//   - bunx @cosmicdrift/kumiko-cli add feature <name>  (DX-2, automatisch)",
-      "//   - oder: hand-edit + import unten ergänzen",
+      "// Add new features:",
+      "//   - bunx @cosmicdrift/kumiko-cli add feature <name>  (DX-2, automatic)",
+      "//   - or: hand-edit + add the import below",
       "",
       "",
     ].join("\n"),
@@ -390,7 +422,11 @@ function renderMain(appName: string): string {
 
   sf.addImportDeclaration({
     moduleSpecifier: "@cosmicdrift/kumiko-dev-server",
-    namedImports: ["composeFeatures", "frameworkCoreEnvSchema", "runProdApp"],
+    namedImports: ["frameworkCoreEnvSchema"],
+  });
+  sf.addImportDeclaration({
+    moduleSpecifier: "@cosmicdrift/kumiko-server-runtime",
+    namedImports: ["composeFeatures", "runProdApp"],
   });
   sf.addImportDeclaration({
     moduleSpecifier: "@cosmicdrift/kumiko-framework/engine",
@@ -475,9 +511,9 @@ function renderMain(appName: string): string {
     [
       "// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after",
       "// composeFeatures + validateBoot + createRegistry without DB/Redis-connect",
-      "// (siehe @cosmicdrift/kumiko-dev-server runProdApp). Echter Dev-Boot",
-      "// passiert via `bunx kumiko dev` (in-repo dev-tool) mit Docker-stack — DX-1.0 deckt nur",
-      "// den boot-mode-Pfad ab; `kumiko dev` kommt in einer späteren DX-Phase.",
+      "// (see @cosmicdrift/kumiko-server-runtime runProdApp). The real dev boot",
+      "// runs via `bunx kumiko dev` (in-repo dev-tool) with a Docker stack — DX-1.0",
+      "// only covers the boot-mode path; `kumiko dev` lands in a later DX phase.",
       "",
       "",
     ].join("\n"),
@@ -504,6 +540,10 @@ function renderDev(appName: string): string {
     moduleSpecifier: "../src/run-config",
     namedImports: ["APP_FEATURES"],
   });
+  sf.addImportDeclaration({
+    moduleSpecifier: "../src/seed",
+    namedImports: ["seedDemoTasks"],
+  });
 
   sf.addVariableStatement({
     declarationKind: VariableDeclarationKind.Const,
@@ -522,6 +562,7 @@ function renderDev(appName: string): string {
         writer.writeLine("features: APP_FEATURES,");
         writer.writeLine("welcomeBanner: true,");
         writer.writeLine(`clientEntry: "./src/client.tsx",`);
+        writer.writeLine("seeds: [seedDemoTasks],");
         writer.write("auth: ").inlineBlock(() => {
           writer.write("admin: ").inlineBlock(() => {
             writer.writeLine(`email: "admin@${appName}.local",`);
@@ -547,12 +588,12 @@ function renderDev(appName: string): string {
   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.",
+      "// Dev bootstrap. `bun --watch bin/dev.ts` (see package.json scripts.dev)",
+      "// starts a full-featured dev server with auto-reload on code changes.",
+      "// setupTestStack creates missing entity tables automatically — a new",
+      "// r.entity(...) in a feature becomes a CREATE TABLE on the next reboot,",
+      "// no manual `kumiko schema apply` needed (that's prod-only).",
+      "// Persistent DB via KUMIKO_DEV_DB_NAME (.env) so admin + data survive reboots.",
       "",
       "",
     ].join("\n"),
@@ -561,27 +602,39 @@ function renderDev(appName: string): string {
   return sf.getFullText();
 }
 
-function renderClient(): string {
+function renderClient(appName: string): string {
   return [
-    "// Browser-Entry. runDevApp's clientEntry-Option bundlet diese Datei zu",
-    "// /client.js und das Default-HTML lädt sie. createKumikoApp liest das",
-    "// Schema aus dem window-globalen (das injectSchema im dev-server setzt)",
-    "// und mountet die Routen.",
+    "// Browser entry. runDevApp's clientEntry option bundles this file to",
+    "// /client.js and the default HTML loads it. createKumikoApp reads the",
+    "// schema from the window global (injectSchema in the dev-server sets it)",
+    "// and mounts the routes.",
     "//",
-    "// DefaultAppShell liefert die Sidebar + Topbar — ohne `shell` rendert",
-    "// createKumikoApp das aktive Screen ohne Layout-Wrapper (= nach Login",
-    "// nur ein nackter Banner statt der App). emailPasswordClient() bringt",
-    "// Login-Screen + Session-Provider — ohne ihn bliebe /login leer.",
+    "// AppShell wraps DefaultAppShell to supply `brand` — createKumikoApp's",
+    "// shell option only injects schema + children. Without `shell` the",
+    "// active screen renders with no layout wrapper (a bare banner after",
+    "// login instead of the app). emailPasswordClient() brings the login",
+    "// screen + session provider — without it /login stays empty.",
     "//",
-    "// Neue Client-Plugins (z.B. notificationsClient()) hier in clientFeatures",
-    "// hinzu — symmetrisch zu APP_FEATURES auf der Server-Seite.",
+    "// Add new client plugins (e.g. notificationsClient()) to clientFeatures",
+    "// here — symmetric to APP_FEATURES on the server side.",
     "",
     'import { emailPasswordClient } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";',
-    'import { createKumikoApp, DefaultAppShell } from "@cosmicdrift/kumiko-renderer-web";',
+    'import { tasksClient } from "./features/tasks/web";',
+    'import { type AppSchema, createKumikoApp, DefaultAppShell } from "@cosmicdrift/kumiko-renderer-web";',
+    'import type { ReactNode } from "react";',
+    "",
+    "function AppShell({ children, schema }: { children: ReactNode; schema: AppSchema }): ReactNode {",
+    "  return (",
+    // html-ok: appName is kebab-validated (a-z/0-9/-); this is generated .tsx source, not runtime HTML.
+    `    <DefaultAppShell brand={<span className="font-semibold tracking-tight">${appName}</span>} schema={schema}>`,
+    "      {children}",
+    "    </DefaultAppShell>",
+    "  );",
+    "}",
     "",
     "createKumikoApp({",
-    "  shell: DefaultAppShell,",
-    "  clientFeatures: [emailPasswordClient()],",
+    "  shell: AppShell,",
+    "  clientFeatures: [emailPasswordClient(), tasksClient],",
     "});",
     "",
   ].join("\n");
@@ -589,10 +642,10 @@ function renderClient(): string {
 
 function renderEnvExample(appName: string): string {
   const devDb = `${appName.replace(/-/g, "_")}_dev`;
-  return `# bun dev (runDevApp → setupTestStack) braucht TEST_DATABASE_URL.
-# Production (bun bin/main.ts → runProdApp) braucht DATABASE_URL.
-# Beide zeigen im Default auf denselben lokalen Postgres — runDevApp legt
-# darunter eine eigene "<KUMIKO_DEV_DB_NAME>"-Datenbank an.
+  return `# bun dev (runDevApp → setupTestStack) needs TEST_DATABASE_URL.
+# Production (bun bin/main.ts → runProdApp) needs DATABASE_URL.
+# Both default to the same local Postgres — runDevApp creates its own
+# "<KUMIKO_DEV_DB_NAME>" database underneath.
 TEST_DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/postgres
 DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/app
 REDIS_URL=redis://127.0.0.1:6379
@@ -604,26 +657,27 @@ JWT_SECRET=change-me-min-32-chars-change-me-min-32
 # 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).
+# Dev-only: persistent DB for \`bun dev\`. Without this var every reboot starts
+# a fresh kumiko_test_<random> DB → admin login + data gone on every edit.
+# With it the DB persists across reboots (schema pushes are idempotent).
 KUMIKO_DEV_DB_NAME=${devDb}
 `;
 }
 
-// Local Postgres + Redis for `bun dev`. Ports + credentials match the *_URL
-// defaults in renderEnvExample, so `docker compose up -d` (referenced by the
-// README) just works with the generated .env. Named pg volume so dev data
-// survives `docker compose down` (pairs with KUMIKO_DEV_DB_NAME persistence).
-// Ports bind to 127.0.0.1 only: the dev DB (postgres/postgres) and auth-less
-// Redis must not be reachable from the LAN on a machine without a firewall.
+// Ports + credentials match the *_URL defaults in renderEnvExample, so
+// `docker compose up -d` just works with the generated .env. Named pg volume
+// so dev data survives `docker compose down` (pairs with KUMIKO_DEV_DB_NAME
+// persistence) — the loopback-binding rationale is in the generated file's
+// own comment (657/1), no need to duplicate it here.
 function renderDockerCompose(): string {
   return `# Local Postgres + Redis for \`bun dev\`. Matches the *_URL defaults in .env.example.
 # Start: docker compose up -d   ·   Stop: docker compose down   ·   Reset: docker compose down -v
 # Ports bind to 127.0.0.1 only — weak dev credentials must not be exposed on the LAN.
 services:
   postgres:
-    image: postgres:18
+    # Pinned to the project's own compose-file tag (663/1) — Alpine variant
+    # (~90MB vs ~400MB) and a reproducible patch version, bump on PG18 minors.
+    image: postgres:18.3-alpine
     environment:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
@@ -646,33 +700,36 @@ function renderReadme(
 ): string {
   const featureList =
     features && features.length > 0
-      ? features.map((f) => `- \`${f.name}\``).join("\n")
-      : "- `secrets` (foundation)\n- `sessions` (foundation)";
+      ? [...features.map((f) => `- \`${f.name}\``), "- `tasks` (demo — list + edit screens)"].join(
+          "\n",
+        )
+      : "- `secrets` (foundation)\n- `sessions` (foundation)\n- `tasks` (demo — list + edit screens)";
   return `# ${appName}
 
-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>\`.
+Scaffolded by \`kumiko new app\`. Includes a demo **tasks** feature with list +
+edit screens, sidebar nav, and seeded rows — \`bun dev\` shows a working admin UI
+after login. Add more features via \`bunx @cosmicdrift/kumiko-cli add feature <name>\`.
 
 ## Mounted features
 
 ${featureList}
 
-Edit \`src/run-config.ts\` to add or remove.
+Edit \`src/run-config.ts\` to add bundled features. The demo lives in
+\`src/features/tasks/\`.
 
-## First run
+## First run (browser)
 
 \`\`\`sh
 bun install
 cp .env.example .env
-# 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
+# set JWT_SECRET + KUMIKO_SECRETS_MASTER_KEY_V1 in .env
+docker compose up -d   # local Postgres + Redis (skip if you already have them)
 bun dev
 \`\`\`
 
-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.
+The welcome banner prints the URL (default \`http://localhost:4173\`) and admin
+login. Sign in as \`admin@${appName}.local\` / \`changeme\`, then open **Tasks**
+in the sidebar — demo rows are pre-seeded.
 
 ## Boot-only smoke (no DB needed)
 
@@ -705,10 +762,12 @@ deploys. Build context = app repo root; migrations ship in \`kumiko/migrations/\
 ## Architecture
 
 - \`src/run-config.ts\` — single source of truth: which features your app mounts (\`APP_FEATURES\`, \`HAS_AUTH\`).
+- \`src/features/tasks/\` — demo feature (entity + handlers + screens + nav).
+- \`src/seed.ts\` — dev seed for demo tasks (\`bun dev\` only).
 - \`kumiko/schema.ts\` — same feature set → \`ENTITY_METAS\` for \`kumiko schema\`.
 - \`bin/dev.ts\` — dev-server entry (\`bun dev\`).
 - \`bin/main.ts\` — production-bootstrap (\`bun run start\`).
-- \`bin/kumiko.ts\` — schema-CLI bundled into \`dist-server/kumiko.js\`.
+- \`bin/kumiko.ts\` — schema + consumer-ops CLI bundled into \`dist-server/kumiko.js\`.
 - \`docker-compose.yml\` — local Postgres + Redis for \`bun dev\`.
 
 For full docs see https://docs.kumiko.rocks.
@@ -731,7 +790,7 @@ function renderKumikoSchema(): string {
     "// Computes table-metas from the SAME composeFeatures(APP_FEATURES) the",
     "// runtime sees (runProdApp/runDevApp) — migration and runtime cannot drift.",
     "",
-    'import { composeFeatures } from "@cosmicdrift/kumiko-dev-server/compose-features";',
+    'import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";',
     'import { collectTableMetas, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";',
     'import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";',
     'import { APP_FEATURES, HAS_AUTH } from "../src/run-config";',
@@ -749,25 +808,32 @@ function renderBinKumiko(): string {
   return [
     "#!/usr/bin/env bun",
     "",
-    "// Standalone kumiko schema-CLI for the production bundle. The deploy",
-    "// migrate-step runs `bun /app/kumiko.js schema apply`; kumiko-build bundles",
-    "// this file to dist-server/kumiko.js.",
+    "// Standalone kumiko CLI for the production bundle. The deploy migrate-step",
+    "// runs `bun /app/kumiko.js schema apply`; ops runs `bun /app/kumiko.js",
+    "// consumer status|restart <name>` to recover a dead event consumer without",
+    "// ad-hoc SQL. kumiko-build bundles this file to dist-server/kumiko.js.",
     "",
-    'import { composeFeatures } from "@cosmicdrift/kumiko-dev-server/compose-features";',
+    'import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";',
+    'import { runConsumerCli } from "@cosmicdrift/kumiko-framework/consumer-cli";',
     'import { runSchemaCli } from "@cosmicdrift/kumiko-framework/schema-cli";',
     'import { APP_FEATURES, HAS_AUTH } from "../src/run-config";',
     "",
     "const [, , cmd, ...rest] = Bun.argv;",
-    'if (cmd !== "schema") {',
-    "  // biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
-    '  console.error("\\n  Unbekannt: kumiko " + (cmd ?? "") + " — nur \'kumiko schema <sub>\' im Standalone-Bundle.\\n");',
-    "  process.exit(1);",
+    "// biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
+    "const out = { log: (l: string) => console.log(l), err: (l: string) => console.error(l) };",
+    "",
+    'if (cmd === "schema") {',
+    "  const features = composeFeatures([...APP_FEATURES], { includeBundled: HAS_AUTH });",
+    "  process.exit(await runSchemaCli(rest, process.env.INIT_CWD ?? process.cwd(), out, { features }));",
+    "}",
+    "",
+    'if (cmd === "consumer") {',
+    "  process.exit(await runConsumerCli(rest, out));",
     "}",
     "",
-    "const features = composeFeatures([...APP_FEATURES], { includeBundled: HAS_AUTH });",
     "// biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
-    "const out = { log: (l: string) => console.log(l), err: (l: string) => console.error(l) };",
-    "process.exit(await runSchemaCli(rest, process.env.INIT_CWD ?? process.cwd(), out, { features }));",
+    'console.error("\\n  Unknown: kumiko " + (cmd ?? "") + " — only \'kumiko schema <sub>\' or \'kumiko consumer <sub>\' in the standalone bundle.\\n");',
+    "process.exit(1);",
     "",
   ].join("\n");
 }
@@ -786,15 +852,21 @@ async function instantiateScaffoldFeatures(
         `scaffoldApp: ${entry.importPath} missing export ${entry.exportName} for ${entry.callExpression}`,
       );
     }
-    if (entry.callExpression.endsWith("()")) {
-      if (typeof exp !== "function") {
-        throw new Error(`scaffoldApp: ${entry.exportName} is not callable (${entry.importPath})`);
-      }
-      instances.push((exp as () => FeatureDefinition)());
+    const looksCallable = entry.callExpression.endsWith(")");
+    if (looksCallable !== (typeof exp === "function")) {
+      throw new Error(
+        `scaffoldApp: ${entry.importPath} export ${entry.exportName} is ${
+          typeof exp === "function" ? "" : "not "
+        }callable but callExpression "${entry.callExpression}" says otherwise`,
+      );
+    }
+    if (typeof exp === "function") {
+      instances.push((exp as (...args: unknown[]) => FeatureDefinition)(...(entry.callArgs ?? [])));
     } else {
       instances.push(exp as FeatureDefinition);
     }
   }
+  instances.push(createDemoTasksFeature());
   return instances;
 }