@cosmicdrift/kumiko-dev-server 0.12.2 → 0.14.0

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/build-server-bundle.ts

@@ -82,7 +82,25 @@ const RUNTIME_EXTERNALS = [
 // Markierung scheitert bun build an dynamic-imports (z.B. drizzle-kit →
 // @libsql/client). Tree-Shake wirft sie eh aus dem Bundle — der Marker
 // schaltet nur das resolution-during-build ab. NICHT in runtime-deps.
-const BUILD_ONLY_EXTERNALS = ["meilisearch", "pino", "pino-pretty", "@aws-sdk/*"] as const;
+//
+// drizzle-kit's dialect-resolver macht dynamic-imports zu allen DB-driver-
+// packages (planetscale/libsql/sqlite/neon/vercel/mysql2). Wir nutzen nur
+// postgres → diese werden never-loaded zur Runtime, aber der Bundler will
+// sie resolven. Aufgedeckt durch C1 Empfehlung 4 (bundle-smoke).
+const BUILD_ONLY_EXTERNALS = [
+  "meilisearch",
+  "pino",
+  "pino-pretty",
+  "@aws-sdk/*",
+  "@planetscale/database",
+  "@libsql/client",
+  "better-sqlite3",
+  "@neondatabase/serverless",
+  "@vercel/postgres",
+  "mysql2",
+  // ink (kumiko-tui) hat react-devtools-core als dev-only transitive import.
+  "react-devtools-core",
+] as const;
 
 export type BuildServerBundleOptions = {
   /** App-Root. Default: process.cwd(). */

package/src/index.ts

@@ -54,6 +54,13 @@ export type {
   SignupSetup,
 } from "./run-prod-app";
 export { runProdApp } from "./run-prod-app";
+export type { ScaffoldAppOptions, ScaffoldAppResult } from "./scaffold-app";
+export { scaffoldApp } from "./scaffold-app";
+export type {
+  ScaffoldAppFeatureOptions,
+  ScaffoldAppFeatureResult,
+} from "./scaffold-app-feature";
+export { runConfigPathForApp, scaffoldAppFeature } from "./scaffold-app-feature";
 export type {
   ScaffoldDeployOptions,
   ScaffoldDeployResult,

package/src/run-prod-app.ts

@@ -126,23 +126,28 @@ function readEnv(name: string): string | undefined {
   return value === undefined || value === "" ? undefined : value;
 }
 
-// Parse `KUMIKO_DRY_RUN_ENV=…` into a DryRunMode. Truthy "1" aliases
-// "human" — the most common deploy-Q quick-look. Unknown values are
-// warned-and-ignored: a typo like `=humans` would otherwise look like
-// a confused boot 30 seconds later when the schema fails.
-function parseDryRunMode(raw: string | undefined): DryRunMode | null {
+// `boot` is the C1 smoke-test path — validators run, no DB/Redis connect,
+// exit after registry-build. Render-modes (human|json|pulumi|k8s|1)
+// inspect the env-schema and exit before any feature wiring.
+type RunMode = DryRunMode | "boot";
+
+function parseRunMode(raw: string | undefined): RunMode | null {
   if (!raw) return null;
   const v = raw.toLowerCase();
   if (v === "1" || v === "true" || v === "human") return "human";
-  if (v === "json" || v === "pulumi" || v === "k8s") return v;
+  if (v === "json" || v === "pulumi" || v === "k8s" || v === "boot") return v;
   // biome-ignore lint/suspicious/noConsole: boot-time warn for typo discovery
   console.warn(
     `[runProdApp] KUMIKO_DRY_RUN_ENV="${raw}" unrecognized ` +
-      `(expected 1|human|json|pulumi|k8s); continuing with normal boot.`,
+      `(expected 1|human|json|pulumi|k8s|boot); continuing with normal boot.`,
   );
   return null;
 }
 
+function isRenderMode(mode: RunMode | null): mode is DryRunMode {
+  return mode !== null && mode !== "boot";
+}
+
 function defaultBootErrorReporter(err: KumikoBootError): never {
   // biome-ignore lint/suspicious/noConsole: boot-time error, no logger configured yet
   console.error(err.format());
@@ -485,13 +490,13 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   //    at parse-time before the polyfill loads. Plain strings + .regex /
   //    .min / .email / .url cover every env-var shape we've actually
   //    needed in 9.1's audit (37 references, 25 distinct vars).
+  const envSource = options.envSource ?? process.env;
+  const runMode = parseRunMode(envSource["KUMIKO_DRY_RUN_ENV"]);
   if (options.envSchema) {
-    const envSource = options.envSource ?? process.env;
-    const dryRunMode = parseDryRunMode(envSource["KUMIKO_DRY_RUN_ENV"]);
-    if (dryRunMode !== null) {
+    if (isRenderMode(runMode)) {
       // biome-ignore lint/suspicious/noConsole: dry-run output IS the deliverable
       console.log(
-        renderDryRun(options.envSchema, dryRunMode, {
+        renderDryRun(options.envSchema, runMode, {
           ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
           sources: options.envSchema.sources,
         }),
@@ -504,6 +509,9 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
       }
       return makeDryRunHandle();
     }
+    // boot-mode AND normal-boot both run env-validation. boot-mode wants
+    // a real env-check (all required vars present + schema-valid) before
+    // it asserts feature-wiring works.
     try {
       parseEnv(options.envSchema.schema, envSource, {
         sources: options.envSchema.sources,
@@ -554,6 +562,22 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   validateBoot(features);
   const registry = createRegistry(features);
 
+  // C1 boot-mode exit: validators ran, registry built, no DB/Redis
+  // operations executed yet (postgres.js + ioredis are lazy). Tear down
+  // the lazy clients so Bun doesn't keep them open, then exit / return.
+  if (runMode === "boot") {
+    // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
+    console.log(
+      `[runProdApp] boot validation OK (${features.length} features, ${registry.features.size} registry entries)`,
+    );
+    await closeDb();
+    redis.disconnect();
+    if (options.envSource === undefined) {
+      process.exit(0);
+    }
+    return makeDryRunHandle();
+  }
+
   // Sprint-8a Tier-Composition auto-wire: scan features for a
   // tenantTierResolver-extension. If found AND user didn't supply own
   // effectiveFeatures, build the resolver here (db + registry are

package/src/scaffold-app-feature.ts

@@ -0,0 +1,154 @@
+// scaffoldAppFeature — DX-2. Scaffolds a fresh feature inside an
+// existing Kumiko-app workspace + auto-mounts it in src/run-config.ts.
+//
+// Sister to `scaffoldFeature` (which targets samples/recipes/ for the
+// framework workspace). This one targets `src/features/<name>/` of an
+// already-scaffolded app (output of `kumiko new app`).
+//
+// Auto-mount via ts-morph: opens src/run-config.ts, finds
+// `export const APP_FEATURES = [...]`, prepends import + appends entry.
+// User's promise "defineFeature → nichts woanders eintragen" is met
+// for the run-config side. Drizzle FEATURE_IMPORT_REGISTRY is NOT
+// touched here — DX-4 auto-discovery resolves that.
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Project, SyntaxKind } from "ts-morph";
+
+export type ScaffoldAppFeatureOptions = {
+  /** kebab-case feature name (e.g. "product-catalog"). */
+  readonly name: string;
+  /** App workspace root. Defaults to cwd. */
+  readonly appRoot?: string;
+};
+
+export type ScaffoldAppFeatureResult = {
+  readonly featureName: string;
+  readonly featureDir: string;
+  readonly files: readonly string[];
+  /** Whether src/run-config.ts was auto-mounted. False if run-config
+   *  is missing — caller gets the scaffolded files but must hand-mount. */
+  readonly autoMounted: boolean;
+};
+
+const KEBAB_RE = /^[a-z][a-z0-9-]*$/;
+
+export function scaffoldAppFeature(options: ScaffoldAppFeatureOptions): ScaffoldAppFeatureResult {
+  if (!KEBAB_RE.test(options.name)) {
+    throw new Error(
+      `scaffoldAppFeature: name must be kebab-case (a-z, 0-9, -); got "${options.name}"`,
+    );
+  }
+  const appRoot = resolve(options.appRoot ?? process.cwd());
+  const featureDir = join(appRoot, "src", "features", options.name);
+  if (existsSync(featureDir)) {
+    throw new Error(`scaffoldAppFeature: ${featureDir} already exists — refusing to overwrite`);
+  }
+  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`);
+
+  const indexFile = join(featureDir, "index.ts");
+  writeFileSync(indexFile, renderIndex(options.name));
+  files.push(`src/features/${options.name}/index.ts`);
+
+  const runConfigPath = join(appRoot, "src", "run-config.ts");
+  const autoMounted = existsSync(runConfigPath)
+    ? mountInRunConfig(runConfigPath, options.name)
+    : false;
+
+  return {
+    featureName: options.name,
+    featureDir,
+    files,
+    autoMounted,
+  };
+}
+
+function renderFeature(name: string): string {
+  const camel = kebabToCamel(name);
+  return `// ${name} feature — scaffolded by \`kumiko add feature\`. Edit freely.
+//
+// Doc-Pointer: https://docs.kumiko.so/en/patterns/ for the \`r.*\` API
+// (r.entity, r.writeHandler, r.queryHandler, hooks, …).
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+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 },
+    },
+  });
+});
+`;
+}
+
+function renderIndex(name: string): string {
+  const camel = kebabToCamel(name);
+  return `export { ${camel}Feature } from "./feature";\n`;
+}
+
+function kebabToCamel(name: string): string {
+  return name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+}
+
+// ts-morph: open run-config, prepend import, append APP_FEATURES entry.
+// Returns true on success, throws on shape-mismatch (caller swallows the
+// scaffolded files but warns).
+function mountInRunConfig(runConfigPath: string, name: string): boolean {
+  const camel = kebabToCamel(name);
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+  const sf = project.addSourceFileAtPath(runConfigPath);
+
+  // Already mounted? short-circuit (idempotent re-runs).
+  const existingImport = sf.getImportDeclaration(`./features/${name}`);
+  if (existingImport) return true;
+
+  // 1. Prepend import after the last existing import.
+  const imports = sf.getImportDeclarations();
+  const insertIndex = imports.length > 0 ? imports[imports.length - 1]!.getChildIndex() + 1 : 0;
+  sf.insertImportDeclaration(insertIndex, {
+    moduleSpecifier: `./features/${name}`,
+    namedImports: [`${camel}Feature`],
+  });
+
+  // 2. Find `export const APP_FEATURES = [...]` and append the new entry.
+  const appFeaturesDecl = sf.getVariableDeclaration("APP_FEATURES");
+  if (!appFeaturesDecl) {
+    throw new Error(
+      `mountInRunConfig: ${runConfigPath} has no 'APP_FEATURES' declaration — ` +
+        `cannot auto-mount. Hand-edit: add '${camel}Feature' to APP_FEATURES.`,
+    );
+  }
+  const initializer =
+    appFeaturesDecl.getInitializerIfKind(SyntaxKind.AsExpression) ??
+    appFeaturesDecl.getInitializer();
+  if (!initializer) {
+    throw new Error(`mountInRunConfig: APP_FEATURES has no initializer — cannot auto-mount.`);
+  }
+  // Strip `as const` wrapper if present.
+  const arr =
+    initializer.getKind() === SyntaxKind.AsExpression
+      ? initializer.getFirstChildByKind(SyntaxKind.ArrayLiteralExpression)
+      : initializer.asKind(SyntaxKind.ArrayLiteralExpression);
+  if (!arr) {
+    throw new Error(`mountInRunConfig: APP_FEATURES is not an array literal — cannot auto-mount.`);
+  }
+  arr.addElement(`${camel}Feature`);
+
+  sf.saveSync();
+  return true;
+}
+
+// Re-export so consumers can hint at the file (e.g. for kumiko-cli output).
+export function runConfigPathForApp(appRoot: string): string {
+  return join(appRoot, "src", "run-config.ts");
+}