@cosmicdrift/kumiko-dev-server 0.294.1 → 0.295.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.294.1",
+  "version": "0.295.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -59,10 +59,10 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.294.1",
-    "@cosmicdrift/kumiko-framework": "0.294.1",
-    "@cosmicdrift/kumiko-headless": "0.294.1",
-    "@cosmicdrift/kumiko-server-runtime": "0.294.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.295.0",
+    "@cosmicdrift/kumiko-framework": "0.295.0",
+    "@cosmicdrift/kumiko-headless": "0.295.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.295.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/framework-version.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveFrameworkVersion } from "../framework-version";
+
+const tmpRoots: string[] = [];
+
+function makeTree(): { root: string; nested: string } {
+  const root = mkdtempSync(join(tmpdir(), "framework-version-"));
+  tmpRoots.push(root);
+  const nested = join(root, "a", "b");
+  mkdirSync(nested, { recursive: true });
+  return { root, nested };
+}
+
+afterEach(() => {
+  for (const root of tmpRoots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("resolveFrameworkVersion", () => {
+  test("resolves the real dev-server version with a caret range", async () => {
+    const own: { version: string } = await Bun.file(
+      join(import.meta.dir, "../../package.json"),
+    ).json();
+    expect(resolveFrameworkVersion()).toBe(`^${own.version}`);
+  });
+
+  test("skips corrupt and foreign package.json files on the way up", () => {
+    const { root, nested } = makeTree();
+    writeFileSync(
+      join(root, "package.json"),
+      '{"name":"@cosmicdrift/kumiko-dev-server","version":"1.2.3"}',
+    );
+    writeFileSync(join(root, "a", "package.json"), '{"name":"other","version":"9.9.9"}');
+    writeFileSync(join(nested, "package.json"), "{ not json");
+    expect(resolveFrameworkVersion(nested)).toBe("^1.2.3");
+  });
+
+  test("ignores a dev-server manifest without a version", () => {
+    const { root, nested } = makeTree();
+    writeFileSync(join(root, "package.json"), '{"name":"@cosmicdrift/kumiko-dev-server"}');
+    expect(resolveFrameworkVersion(nested)).toBeUndefined();
+  });
+});

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

@@ -4,7 +4,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { scaffoldApp } from "../scaffold-app";
+import { type ScaffoldTestSetup, scaffoldApp } from "../scaffold-app";
 
 const SCAFFOLD_FILES = [
   "package.json",
@@ -32,6 +32,17 @@ const SCAFFOLD_FILES = [
   "README.md",
 ] as const;
 
+const STUB_TEST_SETUP: ScaffoldTestSetup = {
+  files: {
+    "bunfig.toml": "# stub unit bunfig\n",
+    "e2e/smoke.spec.ts": "// stub spec\n",
+    "src/__tests__/stub.test.ts": "// stub test\n",
+  },
+  scripts: { test: "stub-unit", "test:integration": "stub-integration", e2e: "stub-e2e" },
+  devDependencies: { "@cosmicdrift/kumiko-testing": "stub-version", "@playwright/test": "^1.0.0" },
+  rulesMarkdown: "## Testing\n\n- stub rule\n",
+};
+
 describe("scaffoldApp", () => {
   let tmp: string;
   beforeEach(() => {
@@ -74,6 +85,92 @@ describe("scaffoldApp", () => {
     expect(pkg.scripts["lint"]).toBe("biome check .");
   });
 
+  test("without testSetup the scaffold keeps the legacy bunfig pair and test script", async () => {
+    const dest = join(tmp, "my-shop");
+    const result = await scaffoldApp({ name: "my-shop", destination: dest });
+
+    const pkg = JSON.parse(readFileSync(join(dest, "package.json"), "utf-8")) as {
+      scripts: Record<string, string>;
+      devDependencies: Record<string, string>;
+    };
+    expect(pkg.scripts["test"]).toBe("bun --config=bunfig.ci.toml test --dots");
+    expect(Object.keys(pkg.scripts)).not.toContain("e2e");
+    expect(Object.keys(pkg.devDependencies)).not.toContain("@cosmicdrift/kumiko-testing");
+    expect(result.files).toContain("bunfig.ci.toml");
+    expect(existsSync(join(dest, "e2e"))).toBe(false);
+    expect(readFileSync(join(dest, "README.md"), "utf-8")).not.toContain("## Testing");
+  });
+
+  test("testSetup: factory gets name + version, files land (nested dirs) and are reported", async () => {
+    const dest = join(tmp, "my-shop");
+    let received: { appName: string; frameworkVersion: string } | undefined;
+    const result = await scaffoldApp({
+      name: "my-shop",
+      destination: dest,
+      frameworkVersion: "^0.13.0",
+      testSetup: (input) => {
+        received = input;
+        return STUB_TEST_SETUP;
+      },
+    });
+
+    expect(received).toEqual({ appName: "my-shop", frameworkVersion: "^0.13.0" });
+    for (const rel of Object.keys(STUB_TEST_SETUP.files)) {
+      expect(result.files).toContain(rel);
+      expect(readFileSync(join(dest, rel), "utf-8")).toBe(STUB_TEST_SETUP.files[rel] as string);
+    }
+    expect(existsSync(join(dest, "bunfig.ci.toml"))).toBe(false);
+    expect(result.files.filter((f) => f === "bunfig.toml")).toHaveLength(1);
+  });
+
+  test("testSetup: scripts replace test in place, devDependencies merge sorted, rules land in README", async () => {
+    const dest = join(tmp, "my-shop");
+    await scaffoldApp({ name: "my-shop", destination: dest, testSetup: () => STUB_TEST_SETUP });
+
+    const pkg = JSON.parse(readFileSync(join(dest, "package.json"), "utf-8")) as {
+      scripts: Record<string, string>;
+      devDependencies: Record<string, string>;
+    };
+    expect(pkg.scripts["test"]).toBe("stub-unit");
+    expect(Object.keys(pkg.scripts)).toEqual([
+      "dev",
+      "build",
+      "start",
+      "boot",
+      "typecheck",
+      "lint",
+      "test",
+      "test:integration",
+      "e2e",
+      "schema:apply",
+      "schema:generate",
+    ]);
+    expect(pkg.devDependencies["@cosmicdrift/kumiko-testing"]).toBe("stub-version");
+    const names = Object.keys(pkg.devDependencies);
+    expect(names).toEqual([...names].sort());
+    expect(names).toContain("@biomejs/biome");
+
+    const readme = readFileSync(join(dest, "README.md"), "utf-8");
+    expect(readme).toContain("## Architecture");
+    expect(readme.endsWith(STUB_TEST_SETUP.rulesMarkdown)).toBe(true);
+  });
+
+  test("tsconfig and biome cover the e2e sources", async () => {
+    const dest = join(tmp, "my-shop");
+    await scaffoldApp({ name: "my-shop", destination: dest, testSetup: () => STUB_TEST_SETUP });
+
+    const tsconfig = JSON.parse(readFileSync(join(dest, "tsconfig.json"), "utf-8")) as {
+      include: string[];
+    };
+    expect(tsconfig.include).toEqual(expect.arrayContaining(["e2e", "playwright.config.ts"]));
+    const biome = JSON.parse(readFileSync(join(dest, "biome.json"), "utf-8")) as {
+      files: { includes: string[] };
+    };
+    expect(biome.files.includes).toEqual(
+      expect.arrayContaining(["e2e/**", "playwright.config.ts"]),
+    );
+  });
+
   test("src/seed.ts bare return has a skip comment directly above it (kumiko-guard-silent-skip)", async () => {
     const dest = join(tmp, "my-shop");
     await scaffoldApp({ name: "my-shop", destination: dest });

package/src/framework-version.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+
+const DEV_SERVER_PACKAGE = "@cosmicdrift/kumiko-dev-server";
+
+interface DevServerManifest {
+  readonly name: typeof DEV_SERVER_PACKAGE;
+  readonly version: string;
+}
+
+function isDevServerManifest(value: unknown): value is DevServerManifest {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "name" in value &&
+    value.name === DEV_SERVER_PACKAGE &&
+    "version" in value &&
+    typeof value.version === "string" &&
+    value.version !== ""
+  );
+}
+
+// All @cosmicdrift packages release in lockstep (changesets fixed-group), so
+// the dev-server's own version is the framework version.
+export function resolveFrameworkVersion(startDir: string = import.meta.dir): string | undefined {
+  let dir = startDir;
+  while (true) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      // A corrupt or foreign package.json on the way up must not abort the search.
+      const manifest = parseJsonSafe<unknown>(readFileSync(candidate, "utf-8"), undefined);
+      if (isDevServerManifest(manifest)) return `^${manifest.version}`;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}

package/src/index.ts

@@ -65,6 +65,7 @@ export type {
   FewShotEntry,
 } from "./few-shot-corpus";
 export { buildFewShotCorpus, pathToId } from "./few-shot-corpus";
+export { resolveFrameworkVersion } from "./framework-version";
 export type { RunDevAppAuthOptions, RunDevAppOptions, SeedFn } from "./run-dev-app";
 export { runDevApp } from "./run-dev-app";
 export type {

package/src/scaffold-app.ts

@@ -12,7 +12,7 @@
 // Static files (package.json, tsconfig, .env, README) stay text-based.
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import {
   collectTableMetas,
   generateMigration,
@@ -46,6 +46,20 @@ export type ScaffoldFeatureEntry = {
   readonly callArgs?: readonly unknown[];
 };
 
+// Structural twin of `ScaffoldTestSetup` from @cosmicdrift/kumiko-testing/scaffold —
+// dev-server cannot import that package (it depends on dev-server), callers pass it in.
+export type ScaffoldTestSetup = {
+  readonly files: Readonly<Record<string, string>>;
+  readonly scripts: Readonly<Record<string, string>>;
+  readonly devDependencies: Readonly<Record<string, string>>;
+  readonly rulesMarkdown: string;
+};
+
+export type ScaffoldTestSetupFactory = (input: {
+  readonly appName: string;
+  readonly frameworkVersion: string;
+}) => ScaffoldTestSetup;
+
 export type ScaffoldAppOptions = {
   /** kebab-case app name (e.g. "my-shop"). Becomes package-name + folder. */
   readonly name: string;
@@ -62,6 +76,10 @@ export type ScaffoldAppOptions = {
    *  (the historical foundation). create-kumiko-app passes the picker output
    *  here so the generated APP_FEATURES reflects the user's selection. */
   readonly features?: ReadonlyArray<ScaffoldFeatureEntry>;
+  /** Test wiring (bunfigs, scripts, example tests, e2e) — `renderTestSetup` from
+   *  @cosmicdrift/kumiko-testing/scaffold. Without it the app gets the legacy
+   *  bunfig pair and no example tests. */
+  readonly testSetup?: ScaffoldTestSetupFactory;
 };
 
 export type ScaffoldAppResult = {
@@ -80,6 +98,7 @@ export async function scaffoldApp(options: ScaffoldAppOptions): Promise<Scaffold
     throw new Error(`scaffoldApp: ${destination} already exists — refusing to overwrite`);
   }
   const version = options.frameworkVersion ?? "*";
+  const testSetup = options.testSetup?.({ appName: options.name, frameworkVersion: version });
 
   mkdirSync(join(destination, "bin"), { recursive: true });
   mkdirSync(join(destination, "src"), { recursive: true });
@@ -87,7 +106,7 @@ export async function scaffoldApp(options: ScaffoldAppOptions): Promise<Scaffold
 
   const files: string[] = [];
 
-  write(join(destination, "package.json"), renderPackageJson(options.name, version));
+  write(join(destination, "package.json"), renderPackageJson(options.name, version, testSetup));
   files.push("package.json");
 
   write(join(destination, "tsconfig.json"), renderTsconfig());
@@ -96,11 +115,13 @@ export async function scaffoldApp(options: ScaffoldAppOptions): Promise<Scaffold
   write(join(destination, "biome.json"), renderBiomeJson());
   files.push("biome.json");
 
-  write(join(destination, "bunfig.toml"), renderBunfigToml());
-  files.push("bunfig.toml");
+  if (testSetup === undefined) {
+    write(join(destination, "bunfig.toml"), renderBunfigToml());
+    files.push("bunfig.toml");
 
-  write(join(destination, "bunfig.ci.toml"), renderBunfigCiToml());
-  files.push("bunfig.ci.toml");
+    write(join(destination, "bunfig.ci.toml"), renderBunfigCiToml());
+    files.push("bunfig.ci.toml");
+  }
 
   write(join(destination, "src", "run-config.ts"), renderRunConfig(options.features));
   files.push("src/run-config.ts");
@@ -154,7 +175,18 @@ export async function scaffoldApp(options: ScaffoldAppOptions): Promise<Scaffold
     }
   }
 
-  write(join(destination, "README.md"), renderReadme(options.name, options.features));
+  if (testSetup !== undefined) {
+    for (const [rel, content] of Object.entries(testSetup.files)) {
+      mkdirSync(dirname(join(destination, rel)), { recursive: true });
+      write(join(destination, rel), content);
+      files.push(rel);
+    }
+  }
+
+  write(
+    join(destination, "README.md"),
+    `${renderReadme(options.name, options.features)}${testSetup === undefined ? "" : `\n${testSetup.rulesMarkdown}`}`,
+  );
   files.push("README.md");
 
   return { destination, files, appName: options.name };
@@ -165,7 +197,11 @@ function write(path: string, content: string): void {
   writeFileSync(path, content);
 }
 
-function renderPackageJson(name: string, version: string): string {
+function renderPackageJson(
+  name: string,
+  version: string,
+  testSetup: ScaffoldTestSetup | undefined,
+): string {
   return `${JSON.stringify(
     {
       name,
@@ -179,7 +215,7 @@ function renderPackageJson(name: string, version: string): string {
         boot: "KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts",
         typecheck: "tsc --noEmit",
         lint: "biome check .",
-        test: "bun --config=bunfig.ci.toml test --dots",
+        ...(testSetup?.scripts ?? { test: "bun --config=bunfig.ci.toml test --dots" }),
         "schema:apply": "bun kumiko-schema apply",
         "schema:generate": "bun kumiko-schema generate",
       },
@@ -193,7 +229,7 @@ function renderPackageJson(name: string, version: string): string {
         "react-dom": "^19.2.6",
         zod: "^4.4.3",
       },
-      devDependencies: {
+      devDependencies: sortedByName({
         "@biomejs/biome": "^2.4.15",
         "@tailwindcss/cli": "^4.3.0",
         "@types/react": "^19.2.0",
@@ -201,13 +237,18 @@ function renderPackageJson(name: string, version: string): string {
         "bun-types": "^1.4.0",
         tailwindcss: "^4.3.0",
         typescript: "^6.0.3",
-      },
+        ...testSetup?.devDependencies,
+      }),
     },
     null,
     2,
   )}\n`;
 }
 
+function sortedByName(record: Readonly<Record<string, string>>): Record<string, string> {
+  return Object.fromEntries(Object.entries(record).sort(([a], [b]) => (a < b ? -1 : 1)));
+}
+
 function renderTsconfig(): string {
   return `${JSON.stringify(
     {
@@ -226,7 +267,7 @@ function renderTsconfig(): string {
         jsx: "react-jsx",
         noEmit: true,
       },
-      include: ["bin", "src", "kumiko"],
+      include: ["bin", "src", "kumiko", "e2e", "playwright.config.ts"],
     },
     null,
     2,
@@ -244,7 +285,15 @@ function renderBiomeJson(): string {
         defaultBranch: "main",
       },
       files: {
-        includes: ["src/**", "bin/**", "kumiko/**", "!**/dist", "!kumiko/migrations"],
+        includes: [
+          "src/**",
+          "bin/**",
+          "kumiko/**",
+          "e2e/**",
+          "playwright.config.ts",
+          "!**/dist",
+          "!kumiko/migrations",
+        ],
       },
       formatter: {
         enabled: true,