@akanjs/devkit 3.0.0-alpha.11 → 3.0.0-alpha.110

package/dependencyScanner.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { TypeScriptDependencyScanner } from "./dependencyScanner";
+import type { PackageJson } from "./types";
+
+const tempRoots: string[] = [];
+
+const makeTempRoot = async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-depscan-"));
+  tempRoots.push(root);
+  return root;
+};
+
+const write = async (root: string, relPath: string, content: string) => {
+  const filePath = path.join(root, relPath);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+  return filePath;
+};
+
+const scannerFor = async (root: string, dependencies: Record<string, string> = {}) =>
+  new TypeScriptDependencyScanner(path.join(root, "pkgs/@akanjs/devkit"), {
+    workspaceRoot: root,
+    tsconfig: { compilerOptions: { target: "esnext" } },
+    rootPackageJson: { dependencies } as unknown as PackageJson,
+  });
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("TypeScriptDependencyScanner — getPackageBuildDependencies", () => {
+  test("collects imports from ordinary source files", async () => {
+    const root = await makeTempRoot();
+    await write(root, "pkgs/@akanjs/devkit/linter.ts", `import chalk from "chalk";\nexport const x = chalk;\n`);
+    const scanner = await scannerFor(root, { chalk: "^5.0.0" });
+
+    const { npmDeps, missingDeps } = await scanner.getPackageBuildDependencies("@akanjs/devkit");
+
+    expect(npmDeps).toEqual(["chalk"]);
+    expect(missingDeps).toEqual([]);
+  });
+
+  test("reports an import that root package.json does not version", async () => {
+    const root = await makeTempRoot();
+    await write(root, "pkgs/@akanjs/devkit/linter.ts", `import clsx from "clsx";\nexport const x = clsx;\n`);
+    const scanner = await scannerFor(root);
+
+    expect((await scanner.getPackageBuildDependencies("@akanjs/devkit")).missingDeps).toEqual(["clsx"]);
+  });
+
+  test("skips __fixtures__, whose imports are lint violations rather than dependencies", async () => {
+    const root = await makeTempRoot();
+    await write(
+      root,
+      "pkgs/@akanjs/devkit/lint/__fixtures__/no-import-external-library/bad.tsx",
+      `import clsx from "clsx";\nimport { cnst } from "@libs/shared/client";\nexport const x = [clsx, cnst];\n`,
+    );
+    const scanner = await scannerFor(root);
+
+    const { npmDeps, npmDevDeps, missingDeps } = await scanner.getPackageBuildDependencies("@akanjs/devkit");
+
+    expect(missingDeps).toEqual([]);
+    expect(npmDeps).toEqual([]);
+    expect(npmDevDeps).toEqual([]);
+  });
+
+  test("skips a nested __fixtures__ directory at any depth", async () => {
+    const root = await makeTempRoot();
+    await write(root, "pkgs/@akanjs/devkit/__fixtures__/bad.ts", `import a from "pkg-a";\nexport const x = a;\n`);
+    await write(root, "pkgs/@akanjs/devkit/a/b/__fixtures__/c/bad.ts", `import b from "pkg-b";\nexport const x = b;\n`);
+    const scanner = await scannerFor(root);
+
+    expect((await scanner.getPackageBuildDependencies("@akanjs/devkit")).missingDeps).toEqual([]);
+  });
+
+  test("keeps a directory whose name merely contains the fixtures marker", async () => {
+    const root = await makeTempRoot();
+    await write(
+      root,
+      "pkgs/@akanjs/devkit/__fixtures__helper/keep.ts",
+      `import a from "pkg-a";\nexport const x = a;\n`,
+    );
+    const scanner = await scannerFor(root);
+
+    expect((await scanner.getPackageBuildDependencies("@akanjs/devkit")).missingDeps).toEqual(["pkg-a"]);
+  });
+
+  test("skips test files but still reports their non-test siblings", async () => {
+    const root = await makeTempRoot();
+    await write(root, "pkgs/@akanjs/devkit/linter.test.ts", `import a from "pkg-a";\nexport const x = a;\n`);
+    await write(root, "pkgs/@akanjs/devkit/linter.ts", `import b from "pkg-b";\nexport const x = b;\n`);
+    const scanner = await scannerFor(root);
+
+    expect((await scanner.getPackageBuildDependencies("@akanjs/devkit")).missingDeps).toEqual(["pkg-b"]);
+  });
+});

package/dependencyScanner.ts

@@ -7,6 +7,11 @@ import { FileSys } from "./fileSys";
 import type { PackageJson, TsConfigJson } from "./types";
 
 const testFileRegex = /\.(?:test|spec)\.[cm]?[tj]sx?$/;
+// `__fixtures__` holds deliberately invalid sample sources for the lint-rule suites; tsconfig `exclude` and
+// biome's `!` override already skip them, and their imports are violations rather than real dependencies.
+const skipDirs = ["node_modules", "dist", "build", ".git", ".next", "public", "ios", "android", "__fixtures__"];
+const isSkippedPath = (filePath: string) =>
+  skipDirs.some((dir) => filePath.includes(`/${dir}/`) || filePath.startsWith(`${dir}/`));
 const builtinModuleSet = new Set([...builtinModules, ...builtinModules.map((mod) => `node:${mod}`)]);
 const stripShebang = (source: string) => source.replace(/^#!.*(?:\r?\n|$)/, "");
 
@@ -17,10 +22,10 @@ export class TypeScriptDependencyScanner {
   #visitedFiles = new Set<string>();
   readonly #tsTranspiler = new Bun.Transpiler({ loader: "ts" });
   readonly #tsxTranspiler = new Bun.Transpiler({ loader: "tsx" });
-  private readonly directory: string;
-  private readonly rootPackageJson: PackageJson;
-  private readonly ig: ReturnType<typeof ignore>;
-  private readonly workspaceRoot: string;
+  readonly #directory: string;
+  readonly #rootPackageJson: PackageJson;
+  readonly #ig: ReturnType<typeof ignore>;
+  readonly #workspaceRoot: string;
 
   constructor(
     directory: string,
@@ -30,10 +35,10 @@ export class TypeScriptDependencyScanner {
       gitignorePatterns = [],
     }: { workspaceRoot: string; tsconfig: TsConfigJson; rootPackageJson: PackageJson; gitignorePatterns?: string[] },
   ) {
-    this.directory = directory;
-    this.rootPackageJson = rootPackageJson;
-    this.ig = ignore().add(gitignorePatterns);
-    this.workspaceRoot = workspaceRoot;
+    this.#directory = directory;
+    this.#rootPackageJson = rootPackageJson;
+    this.#ig = ignore().add(gitignorePatterns);
+    this.#workspaceRoot = workspaceRoot;
   }
 
   async getMonorepoDependencies(
@@ -41,7 +46,7 @@ export class TypeScriptDependencyScanner {
     { pkgs = [], libs = [] }: { pkgs?: string[]; libs?: string[] } = {},
   ): Promise<{ pkgDeps: string[]; libDeps: string[]; npmDeps: string[]; npmDevDeps: string[] }> {
     const npmSet = new Set(
-      Object.keys({ ...this.rootPackageJson.dependencies, ...this.rootPackageJson.devDependencies }),
+      Object.keys({ ...this.#rootPackageJson.dependencies, ...this.#rootPackageJson.devDependencies }),
     );
     const pkgPathSet = new Set(pkgs);
     const libPathSet = new Set(libs.map((lib) => `@libs/${lib}`));
@@ -68,11 +73,11 @@ export class TypeScriptDependencyScanner {
   ): Promise<{ npmDeps: string[]; npmDevDeps: string[]; missingDeps: string[] }> {
     const runtimeDeps = new Set<string>();
     const devDeps = new Set<string>();
-    const sourceFiles = await this.#findTypeScriptFiles(this.directory, {
+    const sourceFiles = await this.#findTypeScriptFiles(this.#directory, {
       excludeBuildFiles: true,
       excludeTestFiles: true,
     });
-    const cssFiles = await this.#findCssFiles(this.directory);
+    const cssFiles = await this.#findCssFiles(this.#directory);
 
     for (const filePath of sourceFiles) {
       const fileContent = await FileSys.readText(filePath);
@@ -86,7 +91,7 @@ export class TypeScriptDependencyScanner {
       this.#addNormalizedImports(runtimeDeps, this.#extractCssPluginImports(fileContent), projectName);
     }
 
-    const buildFilePath = path.join(this.directory, "build.ts");
+    const buildFilePath = path.join(this.#directory, "build.ts");
     if (await FileSys.fileExists(buildFilePath)) {
       const fileContent = await FileSys.readText(buildFilePath);
       const { imports, typeImports } = this.#extractImports(fileContent, buildFilePath);
@@ -95,7 +100,7 @@ export class TypeScriptDependencyScanner {
 
     for (const dep of runtimeDeps) devDeps.delete(dep);
 
-    const rootDeps = { ...this.rootPackageJson.dependencies, ...this.rootPackageJson.devDependencies };
+    const rootDeps = { ...this.#rootPackageJson.dependencies, ...this.#rootPackageJson.devDependencies };
     const missingDeps: string[] = [];
     for (const dep of [...runtimeDeps, ...devDeps]) {
       if (rootDeps[dep] || (await this.#hasWorkspacePackage(dep))) continue;
@@ -109,7 +114,7 @@ export class TypeScriptDependencyScanner {
   }
 
   async #hasWorkspacePackage(dep: string) {
-    const packageJsonPath = path.join(this.workspaceRoot, "pkgs", dep, "package.json");
+    const packageJsonPath = path.join(this.#workspaceRoot, "pkgs", dep, "package.json");
     if (!(await Bun.file(packageJsonPath).exists())) return false;
     try {
       const packageJson = await FileSys.readJson<PackageJson>(packageJsonPath);
@@ -156,9 +161,9 @@ export class TypeScriptDependencyScanner {
     this.#fileTypeDependencies.clear();
     this.#visitedFiles.clear();
 
-    const files = await this.#findTypeScriptFiles(this.directory);
+    const files = await this.#findTypeScriptFiles(this.#directory);
 
-    for (const file of files) await this.#analyzeFile(file, this.directory);
+    for (const file of files) await this.#analyzeFile(file, this.#directory);
 
     return this.#fileDependencies;
   }
@@ -171,17 +176,16 @@ export class TypeScriptDependencyScanner {
     }: { excludeBuildFiles?: boolean; excludeTestFiles?: boolean } = {},
   ): Promise<string[]> {
     const files: string[] = [];
-    const skipDirs = ["node_modules", "dist", "build", ".git", ".next", "public", "ios", "android"];
 
     const glob = new Bun.Glob("**/*.{ts,tsx}");
     for await (const filePath of glob.scan({ cwd: directory, onlyFiles: true })) {
-      if (skipDirs.some((dir) => filePath.includes(`/${dir}/`) || filePath.startsWith(`${dir}/`))) continue;
+      if (isSkippedPath(filePath)) continue;
       if (excludeBuildFiles && filePath === "build.ts") continue;
       if (excludeTestFiles && testFileRegex.test(filePath)) continue;
 
       const fullPath = path.join(directory, filePath);
-      const relativePath = path.relative(this.workspaceRoot, fullPath);
-      if (this.ig.ignores(relativePath)) continue;
+      const relativePath = path.relative(this.#workspaceRoot, fullPath);
+      if (this.#ig.ignores(relativePath)) continue;
 
       files.push(fullPath);
     }
@@ -190,14 +194,13 @@ export class TypeScriptDependencyScanner {
 
   async #findCssFiles(directory: string): Promise<string[]> {
     const files: string[] = [];
-    const skipDirs = ["node_modules", "dist", "build", ".git", ".next", "public", "ios", "android"];
     const glob = new Bun.Glob("**/*.css");
     for await (const filePath of glob.scan({ cwd: directory, onlyFiles: true })) {
-      if (skipDirs.some((dir) => filePath.includes(`/${dir}/`) || filePath.startsWith(`${dir}/`))) continue;
+      if (isSkippedPath(filePath)) continue;
 
       const fullPath = path.join(directory, filePath);
-      const relativePath = path.relative(this.workspaceRoot, fullPath);
-      if (this.ig.ignores(relativePath)) continue;
+      const relativePath = path.relative(this.#workspaceRoot, fullPath);
+      if (this.#ig.ignores(relativePath)) continue;
 
       files.push(fullPath);
     }

package/devkitUtils.test.ts

@@ -6,8 +6,6 @@ import { ApplicationBuildReporter } from "./applicationBuildReporter";
 import { resolveSignalTestPreloadPath } from "./applicationTestPreload";
 import { TypeScriptDependencyScanner } from "./dependencyScanner";
 import { AppExecutor, WorkspaceExecutor } from "./executors";
-import { extractDependencies } from "./extractDeps";
-import { getModelFileData } from "./getModelFileData";
 import type { PackageJson, TsConfigJson } from "./types";
 
 const tempRoots: string[] = [];
@@ -27,65 +25,6 @@ afterEach(async () => {
   await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
 });
 
-describe("extractDependencies", () => {
-  const packageJson: PackageJson = {
-    name: "fixture",
-    version: "1.0.0",
-    description: "fixture",
-    dependencies: {
-      react: "19.0.0",
-      "@scope/pkg": "1.0.0",
-      lodash: "4.0.0",
-    },
-    devDependencies: {
-      typescript: "6.0.0",
-      vite: "5.0.0",
-    },
-  };
-
-  test("extracts runtime package versions from imports and requires", () => {
-    const deps = extractDependencies(
-      [
-        {
-          path: "index.ts",
-          text: [
-            'import React from "react";',
-            'import { value } from "@scope/pkg/subpath";',
-            'import type { Type } from "typescript";',
-            'const lodash = require("lodash/fp");',
-            'const fs = require("node:fs");',
-            'const path = require("path");',
-            "",
-          ].join("\n"),
-        },
-        { path: "style.css", text: '@import "vite";' },
-      ],
-      packageJson,
-      ["vite"],
-    );
-
-    expect(deps).toEqual({
-      "@scope/pkg": "1.0.0",
-      lodash: "4.0.0",
-      react: "19.0.0",
-      typescript: "6.0.0",
-      vite: "5.0.0",
-    });
-  });
-
-  test("reports missing dependency sections and missing versions", () => {
-    expect(() =>
-      extractDependencies([{ path: "index.ts", text: 'import React from "react";' }], {
-        name: "broken",
-        version: "1.0.0",
-        description: "broken",
-      }),
-    ).toThrow("No dependencies found");
-
-    expect(() => extractDependencies([], packageJson, ["missing"])).toThrow("No version found for missing");
-  });
-});
-
 describe("resolveSignalTestPreloadPath", () => {
   test("resolves the preload file from an installed akanjs package", async () => {
     const root = await makeTempRoot();
@@ -252,49 +191,6 @@ describe("scan convention", () => {
   });
 });
 
-describe("getModelFileData", () => {
-  test("reads model files and derives imported local, scalar, and lib models", async () => {
-    const root = await makeTempRoot();
-    const cwd = process.cwd();
-    process.chdir(root);
-    try {
-      await write(
-        path.join(root, "apps/demo/lib/post/post.constant.ts"),
-        [
-          'import { cnst as shared } from "@libs/shared";',
-          'import { User } from "../user/user.constant";',
-          'import { Money } from "../_money/money.constant";',
-          "export const Post = {};",
-          "",
-        ].join("\n"),
-      );
-      await write(
-        path.join(root, "apps/demo/lib/post/Post.Unit.tsx"),
-        "export default function Unit() { return null; }\n",
-      );
-      await write(
-        path.join(root, "apps/demo/lib/post/Post.View.tsx"),
-        "export default function View() { return null; }\n",
-      );
-
-      const data = await getModelFileData("apps/demo", "post");
-      expect(data).toMatchObject({
-        moduleType: "app",
-        moduleName: "demo",
-        modelName: "post",
-        importModelNames: ["user"],
-        hasImportScalar: true,
-        importLibNames: ["shared"],
-      });
-      expect(data.constantFileStr).toContain("export const Post");
-      expect(data.unitFileStr).toContain("Unit");
-      expect(data.viewFileStr).toContain("View");
-    } finally {
-      process.chdir(cwd);
-    }
-  });
-});
-
 describe("ApplicationBuildReporter", () => {
   test("formats duration, phase lines, and nested errors", () => {
     expect(ApplicationBuildReporter.formatDuration(999)).toBe("999ms");

package/executors.test.ts

@@ -31,7 +31,6 @@ const rootPackageJson = (extra: Partial<PackageJson> = {}): PackageJson => ({
     react: "19.0.0",
     "react-dom": "19.0.0",
     "react-server-dom-webpack": "19.0.0",
-    sharp: "1.0.0",
     lodash: "4.0.0",
   },
   devDependencies: {
@@ -128,6 +127,49 @@ describe("Executor filesystem helpers", () => {
     expect(await readFile(path.join(root, "local/docker-compose.yaml"), "utf8")).toBe("custom");
   });
 
+  test("hands every scaffolded TypeScript file to the formatter, and nothing else", async () => {
+    // A template emits identifiers it cannot sort — `import { fetch, Task, usePage }` is right for a model
+    // named Task and wrong for Zoo — and unsorted imports fail `biome check`. So the scaffold is formatted
+    // on the way out, or it is red for most model names whatever the template says.
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+    const formatted: string[] = [];
+    exec.getLinter = () =>
+      ({
+        fixFiles: async (filePaths: string[]) => {
+          formatted.push(...filePaths);
+          return { fixed: [] };
+        },
+      }) as unknown as ReturnType<Executor["getLinter"]>;
+
+    await exec.applyTemplate({
+      basePath: "apps/demo/page/task",
+      template: "crudSinglePage",
+      dict: { model: "task", appName: "demo" },
+    });
+
+    expect(formatted).toEqual([path.join(root, "apps/demo/page/task/_index.tsx")]);
+  });
+
+  test("a formatter that cannot run does not fail the scaffold", async () => {
+    // `create-akan-workspace` scaffolds before `bun install`, so there is no local Biome binary and often
+    // no config above the target. An unformatted file is a lint fix; a failed scaffold is not.
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+    exec.getLinter = () => {
+      throw new Error("biome.json not found");
+    };
+
+    const created = await exec.applyTemplate({
+      basePath: "apps/demo/page/task",
+      template: "crudSinglePage",
+      dict: { model: "task", appName: "demo" },
+    });
+
+    expect(created).toHaveLength(1);
+    expect(await readFile(path.join(root, "apps/demo/page/task/_index.tsx"), "utf8")).toContain("Task.Zone.Card");
+  });
+
   test("applies hidden files and directories from CLI templates", async () => {
     const root = await makeTempRoot();
     const exec = new Executor("fixture", root);
@@ -204,6 +246,7 @@ describe("Workspace and app executor environment contracts", () => {
       serveDomain: "example.com",
       env: "local",
       portOffset: 10,
+      workspaceId: undefined,
     });
 
     delete process.env.AKAN_PUBLIC_REPO_NAME;
@@ -234,6 +277,7 @@ describe("Workspace and app executor environment contracts", () => {
       serveDomain: "file.example.com",
       env: "develop",
       portOffset: 7,
+      workspaceId: undefined,
     });
   });
 
@@ -271,6 +315,11 @@ describe("Workspace and app executor environment contracts", () => {
     const prepared = await app.prepareCommand("build");
     expect(prepared.env.AKAN_COMMAND_TYPE).toBe("build");
     expect(prepared.env.AKAN_PUBLIC_BASE_PATHS).toBe("admin");
+    // Bundling reads `process.env` through getPublicEnv and `define`s every AKAN_PUBLIC_* into a literal, so a
+    // dev port published here would be baked into the artifact and outrank the PORT the container is run with.
+    expect(process.env.AKAN_PUBLIC_APP_NAME).toBe("demo");
+    expect(process.env.AKAN_PUBLIC_CLIENT_PORT).toBeUndefined();
+    expect(process.env.AKAN_PUBLIC_SERVER_PORT).toBeUndefined();
     expect((await stat(path.join(root, "dist/apps/demo/private"))).isDirectory()).toBe(true);
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
@@ -546,9 +595,7 @@ describe("Workspace and app executor environment contracts", () => {
         "_index.tsx": `export const pageConfig = { devOnly: process.env.NODE_ENV !== "production" };\n${PAGE_SOURCE}`,
       });
 
-      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(
-        "pageConfig.devOnly must be a literal true or false",
-      );
+      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow("devOnly must be a literal true or false");
     });
 
     test("reads devOnly through a satisfies annotation", async () => {
@@ -622,6 +669,64 @@ describe("Workspace and app executor environment contracts", () => {
     });
   });
 
+  describe("root layout source validation during page key discovery", () => {
+    const makeRouteValidationApp = async (appName: string, config: string, files: Record<string, string>) => {
+      const root = await makeTempRoot();
+      process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+      process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+      process.env.AKAN_PUBLIC_ENV = "local";
+      await writeJson(path.join(root, "package.json"), rootPackageJson());
+      await mkdir(path.join(root, "apps", appName), { recursive: true });
+      await writeFile(path.join(root, `apps/${appName}/akan.config.ts`), config);
+      for (const [file, source] of Object.entries(files)) {
+        const filePath = path.join(root, `apps/${appName}/page`, file);
+        await mkdir(path.dirname(filePath), { recursive: true });
+        await writeFile(filePath, source);
+      }
+      const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+      return AppExecutor.from(workspace, appName);
+    };
+    const wsConnectLayout = [
+      "export const wsConnect = false;",
+      "export default function Layout({ children }) { return children; }",
+      "",
+    ].join("\n");
+
+    test("accepts wsConnect on a configured base-path root layout", async () => {
+      process.env.AKAN_PUBLIC_BASE_PATHS = "web,admin";
+      const app = await makeRouteValidationApp(
+        "base-path-root-ws",
+        [
+          "export default {",
+          '  routes: [{ basePath: "web", domains: {} }, { basePath: "admin", domains: {} }],',
+          "};",
+          "",
+        ].join("\n"),
+        { "admin/_layout.tsx": wsConnectLayout },
+      );
+
+      await expect(app.getPageKeys({ refresh: true })).resolves.toEqual(["./admin/_layout.tsx"]);
+    });
+
+    test("rejects wsConnect on a nested layout", async () => {
+      const app = await makeRouteValidationApp(
+        "nested-layout-ws",
+        'export default { routes: [{ basePath: "admin", domains: {} }] };\n',
+        { "admin/users/_layout.tsx": wsConnectLayout },
+      );
+
+      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(/unsupported export "wsConnect"/);
+    });
+
+    test("accepts wsConnect on a grouped root layout", async () => {
+      const app = await makeRouteValidationApp("grouped-root-ws", "export default {};\n", {
+        "(docs)/_layout.tsx": wsConnectLayout,
+      });
+
+      await expect(app.getPageKeys({ refresh: true })).resolves.toEqual(["./(docs)/_layout.tsx"]);
+    });
+  });
+
   test("accepts metadata route exports during page key discovery", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
@@ -760,6 +865,29 @@ describe("Workspace and app executor environment contracts", () => {
     expect(offsetMinimalStart.env.AKAN_PUBLIC_CLIENT_PORT).toBe("8286");
     expect(offsetMinimalStart.env.AKAN_PUBLIC_SERVER_PORT).toBe("8286");
   });
+
+  test("pins the start command to development so an ambient NODE_ENV cannot pick the production router", async () => {
+    const root = await makeTempRoot();
+    process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    await writeJson(path.join(root, "package.json"), rootPackageJson());
+    await mkdir(path.join(root, "apps/ambient"), { recursive: true });
+    await writeFile(path.join(root, "apps/ambient/akan.config.ts"), "export default {};\n");
+
+    const originalNodeEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "production";
+    try {
+      const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+      const started = await AppExecutor.from(workspace, "ambient").prepareCommand("start");
+      expect(started.env.NODE_ENV).toBe("development");
+      // The builder runs in this process and bakes NODE_ENV into the dev bundles it emits.
+      expect(process.env.NODE_ENV).toBe("development");
+    } finally {
+      if (originalNodeEnv === undefined) delete process.env.NODE_ENV;
+      else process.env.NODE_ENV = originalNodeEnv;
+    }
+  });
 });
 
 describe("PkgExecutor package generation", () => {
@@ -773,7 +901,7 @@ describe("PkgExecutor package generation", () => {
       exports: { "./extra": { import: "./extra.ts" } },
       peerDependencies: { react: "19.0.0" },
       peerDependenciesMeta: { react: { optional: true } },
-      optionalDependencies: { sharp: "1.0.0" },
+      optionalDependencies: { "@sample/native": "1.0.0" },
     });
 
     const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
@@ -783,12 +911,12 @@ describe("PkgExecutor package generation", () => {
     expect(distPackageJson).toMatchObject({
       name: "@sample/tool",
       type: "module",
-      engines: { bun: ">=1.3.13" },
+      engines: { bun: ">=1.4.0" },
       dependencies: { lodash: "4.0.0" },
       devDependencies: { typescript: "6.0.0" },
       peerDependencies: { react: "19.0.0" },
       peerDependenciesMeta: { react: { optional: true } },
-      optionalDependencies: { sharp: "1.0.0" },
+      optionalDependencies: { "@sample/native": "1.0.0" },
     });
     expect(distPackageJson.exports?.["."]).toEqual({
       import: "./index.ts",