@cosmicdrift/kumiko-dev-server 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @cosmicdrift/kumiko-dev-server
 
+## 0.14.0
+
+### Minor Changes
+
+- b8e1d48: scaffoldApp baut `src/run-config.ts` + `bin/main.ts` jetzt via ts-morph
+  (AST) statt template-strings. Selbes Tool wie scaffoldAppFeature →
+  ein konsistenter Mechanismus für generate + later modify. Plus:
+  ts-morph als explicit dependency aufgenommen (war bisher nur via
+  hoisted root-dep verfügbar; broken bei publish).
+
+### Patch Changes
+
+- ce23d48: `walkthrough.integration.ts` — DX-3.1 walkthrough-snapshot-test. Pins
+  scaffoldApp + scaffoldAppFeature output gegen die Behauptungen in
+  docs.kumiko.so/en/walkthrough/. Catches doc-drift ohne actual
+  `bunx … && yarn install && bun run boot` CI-run.
+
+  5 Tests: file-list, auto-mount-diff, run-config text-content,
+  composeFeatures(includeBundled:true) = 7 features, bin/main auth.admin
+  stub.
+
+  - @cosmicdrift/kumiko-framework@0.14.0
+  - @cosmicdrift/kumiko-bundled-features@0.14.0
+
 ## 0.13.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.13.0",
+  "version": "0.14.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>",
@@ -49,8 +49,9 @@
     "kumiko-schema-check": "./bin/kumiko-schema-check.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.13.0",
-    "@cosmicdrift/kumiko-framework": "0.13.0"
+    "@cosmicdrift/kumiko-bundled-features": "0.14.0",
+    "@cosmicdrift/kumiko-framework": "0.14.0",
+    "ts-morph": "^28.0.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/__tests__/walkthrough.integration.ts

@@ -0,0 +1,118 @@
+// DX-3.1 — walkthrough-snapshot-test. Reproduces the 3-command path from
+// docs.kumiko.so/en/walkthrough/ in-process and asserts what the walkthrough
+// claims. Catches drift in scaffoldApp + scaffoldAppFeature against the
+// docs without an actual `bunx … && yarn install && bun run boot` CI run.
+//
+// What this test pins:
+//   - scaffoldApp produces the 6 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"
+
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { createRegistry, defineFeature, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { composeFeatures } from "../compose-features";
+import { scaffoldApp } from "../scaffold-app";
+import { scaffoldAppFeature } from "../scaffold-app-feature";
+
+describe("walkthrough — DX-3.1 snapshot", () => {
+  let tmp: string;
+  let appRoot: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "walkthrough-"));
+    appRoot = join(tmp, "my-notes");
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("Step 1 (kumiko new app) — produces walkthrough's 6 files", () => {
+    const result = scaffoldApp({ name: "my-notes", destination: appRoot });
+    expect(result.files).toEqual([
+      "package.json",
+      "tsconfig.json",
+      "src/run-config.ts",
+      "bin/main.ts",
+      ".env.example",
+      "README.md",
+    ]);
+  });
+
+  test("Step 2 (kumiko add feature) — auto-mounts + walkthrough diff matches", () => {
+    scaffoldApp({ name: "my-notes", destination: appRoot });
+    const result = scaffoldAppFeature({ name: "notes", appRoot });
+    expect(result.autoMounted).toBe(true);
+
+    const runConfig = readFileSync(join(appRoot, "src/run-config.ts"), "utf-8");
+    // Walkthrough's diff-block claims:
+    //   + import { notesFeature } from "./features/notes";
+    //   + notesFeature  (in APP_FEATURES)
+    expect(runConfig).toContain(`import { notesFeature } from "./features/notes";`);
+    expect(runConfig).toContain("notesFeature");
+    // Foundation still mounted (createSecretsFeature + createSessionsFeature).
+    expect(runConfig).toContain("createSecretsFeature()");
+    expect(runConfig).toContain("createSessionsFeature()");
+  });
+
+  test("Step 3 (boot validation) — scaffolded run-config matches walkthrough's APP_FEATURES claim", () => {
+    scaffoldApp({ name: "my-notes", destination: appRoot });
+    scaffoldAppFeature({ name: "notes", appRoot });
+
+    // Text-assert: scaffolded run-config.ts contains exactly the 3 features
+    // the walkthrough's diff-block shows (secrets + sessions + notesFeature).
+    // Dynamic-import would fail because /tmp can't resolve @cosmicdrift/*
+    // workspace symlinks — instead we reproduce the equivalent APP_FEATURES
+    // array in-process below.
+    const runConfig = readFileSync(join(appRoot, "src/run-config.ts"), "utf-8");
+    expect(runConfig).toContain("createSecretsFeature()");
+    expect(runConfig).toContain("createSessionsFeature()");
+    expect(runConfig).toContain("notesFeature");
+  });
+
+  test("Step 3 (composeFeatures) — 3 explicit + 4 auto-mounted = 7 features", () => {
+    // Reproduces the scaffolded APP_FEATURES in-process. notesFeature gets
+    // a dummy defineFeature here — the scaffold-side of "notesFeature"
+    // (file-content) is pinned in test 2; this test pins the runtime-side
+    // (composeFeatures auto-prepend behaviour the walkthrough claims).
+    const notesFeature = defineFeature("notes", () => {});
+    const APP_FEATURES = [createSecretsFeature(), createSessionsFeature(), notesFeature];
+
+    const composed = composeFeatures(APP_FEATURES, { includeBundled: true });
+    // 3 explicit + 4 auto-mounted bundled = 7 total features.
+    expect(composed.length).toBe(7);
+
+    const composedNames = composed.map((f) => f.name).sort();
+    expect(composedNames).toEqual([
+      "auth-email-password",
+      "config",
+      "notes",
+      "secrets",
+      "sessions",
+      "tenant",
+      "user",
+    ]);
+
+    // validateBoot must pass (no missing-requires, no schema-errors).
+    expect(() => validateBoot(composed)).not.toThrow();
+    // Registry must contain all 7 features.
+    const registry = createRegistry(composed);
+    expect(registry.features.size).toBe(7);
+  });
+
+  test("bin/main.ts contains the auth.admin stub the walkthrough relies on", () => {
+    scaffoldApp({ name: "my-notes", destination: appRoot });
+    const main = readFileSync(join(appRoot, "bin/main.ts"), "utf-8");
+    // composeFeatures(includeBundled:true)-trigger is `auth: { admin: { … } }`.
+    // Walkthrough explicitly says this is what auto-mounts the 4 bundled features.
+    expect(main).toContain("auth: {");
+    expect(main).toContain("admin: {");
+    expect(main).toContain("memberships:");
+    expect(main).toContain("runProdApp");
+  });
+});

package/src/scaffold-app.ts

@@ -6,16 +6,14 @@
 // stub, package.json with @cosmicdrift/* deps, tsconfig, .env.example,
 // README.
 //
-// Intentionally NOT included in DX-1.0:
-// - drizzle/ setup (DX-1.1 — needs FEATURE_IMPORT_REGISTRY decision from DX-4)
-// - deploy/Dockerfile (already covered by scaffoldDeploy — separate cmd)
-// - first feature scaffold (use scaffoldFeature after this)
-//
-// The generated app is born "boots cleanly, mounts nothing fancy". User
-// runs `kumiko add feature` (DX-2) or hand-edits src/run-config.ts to grow.
+// .ts files are built via ts-morph (same tool [[scaffoldAppFeature]] uses
+// to auto-mount features). Means a single AST representation for both
+// generate + later modify — no template-string ↔ ts-morph divergence.
+// Static files (package.json, tsconfig, .env, README) stay text-based.
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { IndentationText, Project, VariableDeclarationKind } from "ts-morph";
 
 export type ScaffoldAppOptions = {
   /** kebab-case app name (e.g. "my-shop"). Becomes package-name + folder. */
@@ -122,72 +120,143 @@ function renderTsconfig(): string {
   )}\n`;
 }
 
-function renderRunConfig(): string {
-  return `// 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).
-//
-// Neue features hinzufügen:
-//   - bunx kumiko add feature <name>  (DX-2, automatisch)
-//   - oder: hand-edit + import unten ergänzen
-
-import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
-import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+function newTsProject(): Project {
+  return new Project({
+    useInMemoryFileSystem: true,
+    compilerOptions: { target: 99, module: 99, strict: true },
+    manipulationSettings: { indentationText: IndentationText.TwoSpaces },
+  });
+}
 
-export const APP_FEATURES = [
-  createSecretsFeature(),
-  createSessionsFeature(),
-] as const;
-`;
+function renderRunConfig(): 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"],
+  });
+
+  sf.addVariableStatement({
+    declarationKind: VariableDeclarationKind.Const,
+    isExported: true,
+    declarations: [
+      {
+        name: "APP_FEATURES",
+        initializer: "[createSecretsFeature(), createSessionsFeature()] as const",
+      },
+    ],
+  });
+
+  sf.insertText(
+    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).",
+      "//",
+      "// Neue features hinzufügen:",
+      "//   - bunx @cosmicdrift/kumiko-cli add feature <name>  (DX-2, automatisch)",
+      "//   - oder: hand-edit + import unten ergänzen",
+      "",
+      "",
+    ].join("\n"),
+  );
+
+  return sf.getFullText();
 }
 
 function renderMain(appName: string): string {
-  // Deterministic tenant-UUID derived from appName for the seed-admin
-  // membership. Reproducible across boots; tenants table sees the same
-  // ID. Format: 8-4-4-4-12 hex chars, version-4 marker at position 14.
-  // We hash the name into the digits using a tiny PRNG so two apps
-  // get different IDs without bun's crypto dependency.
   const tenantId = deriveTenantId(appName);
-  return `// 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\` mit Docker-stack — DX-1.0 deckt nur
-// den boot-mode-Pfad ab; \`kumiko dev\` kommt in einer späteren DX-Phase.
-
-import { frameworkCoreEnvSchema, runProdApp } from "@cosmicdrift/kumiko-dev-server";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
-import { APP_FEATURES } from "../src/run-config";
-
-const DEFAULT_TENANT_ID = "${tenantId}" as TenantId;
-
-const envSchema = composeEnvSchema({
-  core: frameworkCoreEnvSchema,
-  features: APP_FEATURES,
-});
-
-await runProdApp({
-  features: APP_FEATURES,
-  envSchema,
-  migrations: false,
-  auth: {
-    admin: {
-      email: "admin@${appName}.local",
-      password: "change-me-on-first-deploy",
-      displayName: "Admin",
-      memberships: [
-        {
-          tenantId: DEFAULT_TENANT_ID,
-          tenantKey: "${appName}",
-          tenantName: "${appName}",
-          roles: ["TenantAdmin"],
-        },
-      ],
-    },
-  },
-});
-`;
+  const project = newTsProject();
+  const sf = project.createSourceFile("main.ts", "");
+
+  sf.addImportDeclaration({
+    moduleSpecifier: "@cosmicdrift/kumiko-dev-server",
+    namedImports: ["frameworkCoreEnvSchema", "runProdApp"],
+  });
+  sf.addImportDeclaration({
+    moduleSpecifier: "@cosmicdrift/kumiko-framework/engine",
+    isTypeOnly: true,
+    namedImports: ["TenantId"],
+  });
+  sf.addImportDeclaration({
+    moduleSpecifier: "@cosmicdrift/kumiko-framework/env",
+    namedImports: ["composeEnvSchema"],
+  });
+  sf.addImportDeclaration({
+    moduleSpecifier: "../src/run-config",
+    namedImports: ["APP_FEATURES"],
+  });
+
+  sf.addVariableStatement({
+    declarationKind: VariableDeclarationKind.Const,
+    declarations: [
+      {
+        name: "DEFAULT_TENANT_ID",
+        initializer: `"${tenantId}" as TenantId`,
+      },
+    ],
+  });
+
+  sf.addVariableStatement({
+    declarationKind: VariableDeclarationKind.Const,
+    declarations: [
+      {
+        name: "envSchema",
+        initializer: "composeEnvSchema({ core: frameworkCoreEnvSchema, features: APP_FEATURES })",
+      },
+    ],
+  });
+
+  sf.addStatements((writer) => {
+    writer
+      .write("await runProdApp(")
+      .inlineBlock(() => {
+        writer.writeLine("features: APP_FEATURES,");
+        writer.writeLine("envSchema,");
+        writer.writeLine("migrations: false,");
+        writer.write("auth: ").inlineBlock(() => {
+          writer.write("admin: ").inlineBlock(() => {
+            writer.writeLine(`email: "admin@${appName}.local",`);
+            writer.writeLine(`password: "change-me-on-first-deploy",`);
+            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,
+    [
+      "// 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 `yarn 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.",
+      "",
+      "",
+    ].join("\n"),
+  );
+
+  return sf.getFullText();
 }
 
 function renderEnvExample(): string {
@@ -208,7 +277,7 @@ function renderReadme(appName: string): string {
   return `# ${appName}
 
 Scaffolded by \`kumiko new app\`. Boots out-of-the-box with secrets + sessions
-mounted (foundation set). Add features with \`bunx kumiko add feature <name>\`.
+mounted (foundation set). Add features with \`bunx @cosmicdrift/kumiko-cli add feature <name>\`.
 
 ## First boot
 
@@ -224,7 +293,7 @@ Expected: \`[runProdApp] boot validation OK (… features, … registry entries)
 ## Adding features
 
 \`\`\`sh
-bunx kumiko add feature my-domain
+bunx @cosmicdrift/kumiko-cli add feature my-domain
 # → editiert src/run-config.ts automatisch + scaffolded src/features/my-domain/
 \`\`\`
 
@@ -241,10 +310,6 @@ For full docs see https://docs.kumiko.so.
 // version-marker at the right spot. NOT cryptographically random —
 // just a stable per-app default the user can change later.
 function deriveTenantId(name: string): string {
-  // Tiny xorshift PRNG seeded from the name's char-codes. Same name →
-  // same ID. Sufficient for "give every scaffolded app a deterministic
-  // default tenant" — production sets its own via the create-tenant
-  // flow anyway.
   let state = 2166136261;
   for (const ch of name) {
     state ^= ch.charCodeAt(0);
@@ -255,11 +320,9 @@ function deriveTenantId(name: string): string {
   state ^= state << 13;
   state >>>= 0;
   const b = hex(state, 4);
-  // version-4 marker at first char of 3rd group:
   state ^= state >>> 17;
   state >>>= 0;
   const c = `4${hex(state, 3)}`;
-  // RFC 4122 variant: 10xx (set top two bits of 4th group to 10):
   state ^= state << 5;
   state >>>= 0;
   const d4 = (0x8 | (state & 0x3)).toString(16);