@cosmicdrift/kumiko-dev-server 0.130.2 → 0.131.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.130.2",
+  "version": "0.131.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>",
@@ -58,8 +58,8 @@
     "kumiko-schema-check": "./bin/kumiko-schema-check.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.130.2",
-    "@cosmicdrift/kumiko-framework": "0.130.2",
+    "@cosmicdrift/kumiko-bundled-features": "0.131.0",
+    "@cosmicdrift/kumiko-framework": "0.131.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

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

@@ -4,6 +4,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
 import { scaffoldApp } from "../scaffold-app";
 import { scaffoldAppFeature } from "../scaffold-app-feature";
 
@@ -19,23 +20,60 @@ describe("scaffoldAppFeature", () => {
     rmSync(tmp, { recursive: true, force: true });
   });
 
-  test("scaffolds src/features/<name>/feature.ts + index.ts", () => {
+  test("scaffolds die volle App-Feature-Konvention", () => {
     const result = scaffoldAppFeature({ name: "product-catalog", appRoot });
     expect(result.featureName).toBe("product-catalog");
     expect(result.files).toEqual([
       "src/features/product-catalog/feature.ts",
       "src/features/product-catalog/index.ts",
+      "src/features/product-catalog/constants.ts",
+      "src/features/product-catalog/i18n.ts",
+      "src/features/product-catalog/schema/product-catalog-item.ts",
+      "src/features/product-catalog/schema/index.ts",
+      "src/features/product-catalog/web/index.ts",
+      "src/features/product-catalog/__tests__/feature.boot.test.ts",
     ]);
-    expect(existsSync(join(appRoot, "src/features/product-catalog/feature.ts"))).toBe(true);
-    expect(existsSync(join(appRoot, "src/features/product-catalog/index.ts"))).toBe(true);
+    for (const file of result.files) {
+      expect(existsSync(join(appRoot, file))).toBe(true);
+    }
   });
 
-  test("feature.ts uses kebab-name + camelCase variable", () => {
+  test("feature.ts registriert nur — Entity aus schema/, Keys aus i18n.ts", () => {
     scaffoldAppFeature({ name: "product-catalog", appRoot });
     const feature = readFileSync(join(appRoot, "src/features/product-catalog/feature.ts"), "utf-8");
-    expect(feature).toContain(`defineFeature("product-catalog"`);
+    expect(feature).toContain("defineFeature(PRODUCT_CATALOG_FEATURE");
     expect(feature).toContain("export const productCatalogFeature");
-    expect(feature).toContain('r.entity("product-catalog-item"');
+    expect(feature).toContain('r.entity("product-catalog-item", productCatalogItemEntity)');
+    expect(feature).toContain('type: "entityList"');
+    expect(feature).toContain("r.translations({ keys: productCatalogTranslationKeys })");
+    // Konvention: Entity-Felder leben in schema/, nicht inline in feature.ts.
+    expect(feature).not.toContain("fields:");
+  });
+
+  test("Starter erfüllt Boot-Constraints: sortable-Feld, defaultSort, i18n-Pflichtkeys", () => {
+    scaffoldAppFeature({ name: "product-catalog", appRoot });
+    const entity = readFileSync(
+      join(appRoot, "src/features/product-catalog/schema/product-catalog-item.ts"),
+      "utf-8",
+    );
+    expect(entity).toContain("sortable: true");
+    const feature = readFileSync(join(appRoot, "src/features/product-catalog/feature.ts"), "utf-8");
+    expect(feature).toContain('defaultSort: { field: "title", dir: "asc" }');
+    const i18n = readFileSync(join(appRoot, "src/features/product-catalog/i18n.ts"), "utf-8");
+    expect(i18n).toContain('"screen:items.title"');
+    expect(i18n).toContain('"product-catalog:entity:product-catalog-item:field:title"');
+  });
+
+  test("web/index.ts ist Client-Stub, __tests__ enthält validateBoot-Test", () => {
+    scaffoldAppFeature({ name: "product-catalog", appRoot });
+    const web = readFileSync(join(appRoot, "src/features/product-catalog/web/index.ts"), "utf-8");
+    expect(web).toContain("@runtime client");
+    expect(web).toContain("export const productCatalogClient: ClientFeatureDefinition");
+    const bootTest = readFileSync(
+      join(appRoot, "src/features/product-catalog/__tests__/feature.boot.test.ts"),
+      "utf-8",
+    );
+    expect(bootTest).toContain("validateBoot([productCatalogFeature])");
   });
 
   test("auto-mounts in src/run-config.ts (import + APP_FEATURES entry)", () => {
@@ -119,6 +157,21 @@ describe("scaffoldAppFeature", () => {
     expect(healed).toMatch(/\]\s*as const;/);
   });
 
+  test("gescaffoldetes Feature bootet wirklich (validateBoot über dynamic import)", async () => {
+    // Ins Repo scaffolden (nicht os.tmpdir): nur hier löst der dynamic
+    // import "@cosmicdrift/kumiko-framework/engine" über node_modules auf.
+    const repoTmp = mkdtempSync(join(import.meta.dir, ".tmp-scaffold-"));
+    try {
+      scaffoldAppFeature({ name: "boot-probe", appRoot: repoTmp });
+      const mod = (await import(join(repoTmp, "src/features/boot-probe/feature.ts"))) as {
+        readonly bootProbeFeature: Parameters<typeof validateBoot>[0][number];
+      };
+      expect(() => validateBoot([mod.bootProbeFeature])).not.toThrow();
+    } finally {
+      rmSync(repoTmp, { recursive: true, force: true });
+    }
+  });
+
   test("rejects non-kebab-case", () => {
     expect(() => scaffoldAppFeature({ name: "ProductCatalog", appRoot })).toThrow(/kebab-case/);
     expect(() => scaffoldAppFeature({ name: "product_catalog", appRoot })).toThrow(/kebab-case/);

package/src/scaffold-app-feature.ts

@@ -47,14 +47,27 @@ export function scaffoldAppFeature(options: ScaffoldAppFeatureOptions): Scaffold
   }
   mkdirSync(featureDir, { recursive: true });
 
-  const files: string[] = [];
-  const featureFile = join(featureDir, "feature.ts");
-  writeFileSync(featureFile, renderFeature(options.name));
-  files.push(`src/features/${options.name}/feature.ts`);
+  // Volle App-Feature-Konvention (Referenz: bundled-features/tenant):
+  // feature.ts = nur Registrierung, schema/ für Entities, i18n.ts für
+  // Server-Keys, web/ für die Client-Seite, __tests__/ mit Boot-Test.
+  // handlers/ + lib/ entstehen beim ersten echten Handler/Logik-Modul.
+  mkdirSync(join(featureDir, "schema"), { recursive: true });
+  mkdirSync(join(featureDir, "web"), { recursive: true });
+  mkdirSync(join(featureDir, "__tests__"), { recursive: true });
 
-  const indexFile = join(featureDir, "index.ts");
-  writeFileSync(indexFile, renderIndex(options.name));
-  files.push(`src/features/${options.name}/index.ts`);
+  const files: string[] = [];
+  const write = (relative: string, content: string): void => {
+    writeFileSync(join(featureDir, relative), content);
+    files.push(`src/features/${options.name}/${relative}`);
+  };
+  write("feature.ts", renderFeature(options.name));
+  write("index.ts", renderIndex(options.name));
+  write("constants.ts", renderConstants(options.name));
+  write("i18n.ts", renderI18n(options.name));
+  write(join("schema", `${options.name}-item.ts`), renderEntity(options.name));
+  write(join("schema", "index.ts"), renderSchemaIndex(options.name));
+  write(join("web", "index.ts"), renderWebIndex(options.name));
+  write(join("__tests__", "feature.boot.test.ts"), renderBootTest(options.name));
 
   const runConfigPath = join(appRoot, "src", "run-config.ts");
   let autoMounted = false;
@@ -83,18 +96,38 @@ function renderFeature(name: string): string {
   const camel = kebabToCamel(name);
   return `// ${name} feature — scaffolded by \`kumiko add feature\`. Edit freely.
 //
-// Doc-Pointer: https://docs.kumiko.rocks/en/patterns/ for the \`r.*\` API
-// (r.entity, r.writeHandler, r.queryHandler, hooks, …).
+// Konvention (Referenz: bundled-features, z.B. tenant/):
+//   feature.ts  — NUR Registrierung (r.entity / r.screen / r.queryHandler / …)
+//   schema/     — Entity-Definitionen
+//   handlers/   — eine Datei pro Handler (defineQueryHandler / defineWriteHandler)
+//   lib/        — reine Domain-Logik
+//   web/        — Client-Seite (index.ts, ein Screen pro Datei)
+//   i18n.ts     — Server-Translation-Keys
+//
+// Doc-Pointer: https://docs.kumiko.rocks/en/patterns/ for the \`r.*\` API.
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { ${constName(name)} } from "./constants";
+import { ${camel}TranslationKeys } from "./i18n";
+import { ${camel}ItemEntity } from "./schema";
+
+export const ${camel}Feature = defineFeature(${constName(name)}, (r) => {
+  r.entity("${name}-item", ${camel}ItemEntity);
 
-export const ${camel}Feature = defineFeature("${name}", (r) => {
-  // Starter: declare an entity. Drop and replace with your domain.
-  r.entity("${name}-item", {
-    fields: {
-      title: { type: "text", required: true },
-    },
+  // Deklarativer List-Screen — CRUD-Query kommt aus der Entity.
+  // Für query-getriebene Tabellen: type "projectionList"; für
+  // Kennzahlen-Grids: type "dashboard".
+  r.screen({
+    id: "items",
+    type: "entityList",
+    entity: "${name}-item",
+    columns: ["title"],
+    defaultSort: { field: "title", dir: "asc" },
   });
+
+  r.translations({ keys: ${camel}TranslationKeys });
+
+  r.nav({ id: "items", label: "screen:items.title", screen: "${name}:screen:items" });
 });
 `;
 }
@@ -104,10 +137,79 @@ function renderIndex(name: string): string {
   return `export { ${camel}Feature } from "./feature";\n`;
 }
 
+function renderConstants(name: string): string {
+  return `export const ${constName(name)} = "${name}";\n`;
+}
+
+function renderI18n(name: string): string {
+  const camel = kebabToCamel(name);
+  return `// Server-seitige Translation-Keys (r.translations). Screen-Titel und
+// Field-Labels folgen den Framework-Konventionen — der Boot-Validator
+// prüft die Abdeckung.
+
+export const ${camel}TranslationKeys = {
+  "screen:items.title": { de: "Einträge", en: "Items" },
+  "${name}:entity:${name}-item:field:title": { de: "Titel", en: "Title" },
+};
+`;
+}
+
+function renderEntity(name: string): string {
+  const camel = kebabToCamel(name);
+  return `// Entity-Definition — Felder, Annotationen, Transitions.
+// Starter: eine Text-Spalte. Ersetze sie durch deine Domain.
+
+export const ${camel}ItemEntity = {
+  fields: {
+    title: { type: "text", required: true, sortable: true },
+  },
+};
+`;
+}
+
+function renderSchemaIndex(name: string): string {
+  const camel = kebabToCamel(name);
+  return `export { ${camel}ItemEntity } from "./${name}-item";\n`;
+}
+
+function renderWebIndex(name: string): string {
+  const camel = kebabToCamel(name);
+  return `// @runtime client
+// Client-Seite des Features: translations, components (custom-Screens),
+// columnRenderers. In src/app/client.tsx bei
+// createKumikoApp({ clientFeatures: [...] }) einhängen — das passiert
+// NICHT automatisch. Screens: eine Datei pro Screen in diesem Ordner.
+
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+
+export const ${camel}Client: ClientFeatureDefinition = {
+  name: "${name}",
+};
+`;
+}
+
+function renderBootTest(name: string): string {
+  const camel = kebabToCamel(name);
+  return `import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { ${camel}Feature } from "../feature";
+
+describe("${name} feature", () => {
+  test("boots: Entity, Screens und i18n-Coverage validieren", () => {
+    expect(() => validateBoot([${camel}Feature])).not.toThrow();
+  });
+});
+`;
+}
+
 function kebabToCamel(name: string): string {
   return name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
 }
 
+function constName(name: string): string {
+  return `${name.replace(/-/g, "_").toUpperCase()}_FEATURE`;
+}
+
 // ts-morph: open run-config, prepend import, append APP_FEATURES entry.
 // Returns true on success, throws on shape-mismatch — the caller rolls back
 // the scaffolded feature dir and re-throws so a re-run isn't blocked.