@akanjs/devkit 2.1.0-rc.1 → 2.1.0-rc.11

package/akanConfig/akanConfig.test.ts

@@ -132,6 +132,7 @@ describe("AkanAppConfig", () => {
         react: "19.0.0",
         "react-dom": "19.0.0",
         "react-server-dom-webpack": "19.0.0",
+        croner: akanPackageJson.peerDependencies?.croner,
         sharp: "1.0.0",
         "@external/runtime": "2.0.0",
       },
@@ -168,10 +169,45 @@ describe("AkanAppConfig", () => {
       react: runtimeDependencies.react,
       "react-dom": runtimeDependencies["react-dom"],
       "react-server-dom-webpack": runtimeDependencies["react-server-dom-webpack"],
+      croner: runtimeDependencies.croner,
       sharp: runtimeDependencies.sharp,
     });
   });
 
+  test("adds backend runtime packages by database mode", () => {
+    const runtimeDependencies = { ...akanPackageJson.dependencies, ...akanPackageJson.peerDependencies };
+    const singleConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "single" }, baseDevEnv);
+    const multipleConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "multiple" }, baseDevEnv);
+    const clusterConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "cluster" }, baseDevEnv);
+
+    expect(singleConfig.getProductionPackageJson().dependencies).toMatchObject({
+      croner: runtimeDependencies.croner,
+    });
+    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("ioredis");
+    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("bullmq");
+    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("@libsql/client");
+    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("postgres");
+    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("protobufjs");
+
+    expect(multipleConfig.getProductionPackageJson().dependencies).toMatchObject({
+      "@libsql/client": runtimeDependencies["@libsql/client"],
+      bullmq: runtimeDependencies.bullmq,
+      croner: runtimeDependencies.croner,
+      ioredis: runtimeDependencies.ioredis,
+      protobufjs: runtimeDependencies.protobufjs,
+    });
+    expect(multipleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("postgres");
+
+    expect(clusterConfig.getProductionPackageJson().dependencies).toMatchObject({
+      bullmq: runtimeDependencies.bullmq,
+      croner: runtimeDependencies.croner,
+      ioredis: runtimeDependencies.ioredis,
+      postgres: runtimeDependencies.postgres,
+      protobufjs: runtimeDependencies.protobufjs,
+    });
+    expect(clusterConfig.getProductionPackageJson().dependencies).not.toHaveProperty("@libsql/client");
+  });
+
   test("normalizes multiple mobile targets and validates base paths", () => {
     const config = new AkanAppConfig(
       app,

package/akanConfig/akanConfig.ts

@@ -50,7 +50,18 @@ const DEFAULT_OPTIMIZE_IMPORTS = [
 const WORKSPACE_BARREL_FACETS = ["ui", "webkit", "common", "client", "server"] as const;
 const SSR_RUNTIME_PACKAGES = ["react", "react-dom", "react-server-dom-webpack"] as const;
 const NATIVE_RUNTIME_PACKAGES = ["sharp"] as const;
-const AKAN_RUNTIME_PACKAGES = new Set<string>([...SSR_RUNTIME_PACKAGES, ...NATIVE_RUNTIME_PACKAGES]);
+const DEFAULT_BACKEND_RUNTIME_PACKAGES = ["croner"] as const;
+const DATABASE_MODE_RUNTIME_PACKAGES = {
+  single: [],
+  multiple: ["@libsql/client", "bullmq", "ioredis", "protobufjs"],
+  cluster: ["bullmq", "ioredis", "postgres", "protobufjs"],
+} satisfies Record<DatabaseMode, readonly string[]>;
+const AKAN_RUNTIME_PACKAGES = new Set<string>([
+  ...SSR_RUNTIME_PACKAGES,
+  ...NATIVE_RUNTIME_PACKAGES,
+  ...DEFAULT_BACKEND_RUNTIME_PACKAGES,
+  ...Object.values(DATABASE_MODE_RUNTIME_PACKAGES).flat(),
+]);
 const DEFAULT_AKAN_IMAGE_CONFIG: AkanImageConfig = {
   deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
   imageSizes: [32, 48, 64, 96, 128, 256, 384],
@@ -272,6 +283,15 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     if (AKAN_RUNTIME_PACKAGES.has(lib))
       return akanPackageJson.dependencies?.[lib] ?? akanPackageJson.peerDependencies?.[lib];
   }
+  #getProductionRuntimePackages() {
+    return [
+      ...this.externalLibs,
+      ...SSR_RUNTIME_PACKAGES,
+      ...NATIVE_RUNTIME_PACKAGES,
+      ...DEFAULT_BACKEND_RUNTIME_PACKAGES,
+      ...DATABASE_MODE_RUNTIME_PACKAGES[this.defaultDatabaseMode],
+    ];
+  }
   getProductionPackageJson(data: Partial<PackageJson> = {}): PackageJson {
     return {
       name: this.app.name,
@@ -279,7 +299,7 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
       version: "1.0.0",
       main: "./main.js",
       dependencies: Object.fromEntries(
-        [...new Set([...this.externalLibs, ...SSR_RUNTIME_PACKAGES, ...NATIVE_RUNTIME_PACKAGES])].map((lib) => {
+        [...new Set(this.#getProductionRuntimePackages())].map((lib) => {
           const version = this.#resolveProductionDependencyVersion(lib);
           if (!version) throw new Error(`Dependency ${lib} not found in package.json`);
           return [lib, version];

package/akanConfig/types.ts

@@ -1,4 +1,3 @@
-export { archs } from "akanjs";
 export type {
   AkanConfigFile,
   AkanMobileConfig,
@@ -21,3 +20,4 @@ export type {
   ScanResult,
   WorkspaceScanResult,
 } from "akanjs";
+export { archs } from "akanjs";

package/applicationBuildRunner.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from "bun:test";
+import { AKAN_OPTIONAL_BACKEND_EXTERNALS } from "./applicationBuildRunner";
+
+describe("ApplicationBuildRunner", () => {
+  test("externalizes Akan optional backend dependencies", () => {
+    expect(AKAN_OPTIONAL_BACKEND_EXTERNALS).toEqual(
+      expect.arrayContaining(["@libsql/client", "bullmq", "croner", "ioredis", "postgres", "protobufjs"]),
+    );
+  });
+});

package/applicationBuildRunner.ts

@@ -47,26 +47,20 @@ const SSR_RENDER_EXTERNALS = [
   "react/jsx-dev-runtime",
   "react-dom",
   "react-dom/server.browser",
+  "react-server-dom-webpack",
+  "react-server-dom-webpack/server.node",
   "react-server-dom-webpack/client.node",
   "react-server-dom-webpack/client.browser",
 ] as const;
 
-const TYPECHECK_WORKER_CODE = `
-import { TypeChecker } from "@akanjs/devkit";
-
-try {
-  const configPath = process.env.AKAN_TYPECHECK_TSCONFIG;
-  if (!configPath) throw new Error("AKAN_TYPECHECK_TSCONFIG is required");
-  const result = TypeChecker.checkProject(configPath);
-  if (result.errors.length > 0) {
-    console.error(result.message);
-    process.exit(1);
-  }
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-}
-`;
+export const AKAN_OPTIONAL_BACKEND_EXTERNALS = [
+  "@libsql/client",
+  "bullmq",
+  "croner",
+  "ioredis",
+  "postgres",
+  "protobufjs",
+] as const;
 
 export class ApplicationBuildRunner {
   #app: App;
@@ -178,7 +172,9 @@ export class ApplicationBuildRunner {
 
   async #buildBackend() {
     const akanConfig = await this.#app.getConfig();
-    const backendExternals = [...new Set([...akanConfig.externalLibs, ...SSR_RENDER_EXTERNALS])];
+    const backendExternals = [
+      ...new Set([...akanConfig.externalLibs, ...SSR_RENDER_EXTERNALS, ...AKAN_OPTIONAL_BACKEND_EXTERNALS]),
+    ];
     const backendEntryPoints = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
     for (const entrypoint of backendEntryPoints) {
       if (!(await Bun.file(entrypoint).exists())) throw new Error(`Backend entrypoint not found: ${entrypoint}`);
@@ -200,8 +196,7 @@ export class ApplicationBuildRunner {
       conditions: ["react-server"],
       // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
       define: { "process.env.NODE_ENV": JSON.stringify("production") },
-      plugins:
-        akanConfig.externalLibs.length > 0 ? [this.#createExternalSpecifiersPlugin(akanConfig.externalLibs)] : [],
+      plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
     });
     return {
       entrypoints: backendEntryPoints.length + 1,
@@ -258,7 +253,8 @@ export class ApplicationBuildRunner {
   }
 
   async #checkProjectInChildProcess(tsconfigPath: string) {
-    const proc = Bun.spawn([process.execPath, "--eval", TYPECHECK_WORKER_CODE], {
+    const entry = await this.#resolveTypecheckWorkerEntry();
+    const proc = Bun.spawn([process.execPath, entry], {
       cwd: this.#app.workspace.workspaceRoot,
       env: this.#app.getCommandEnv({
         AKAN_COMMAND_TYPE: "typecheck",
@@ -275,6 +271,17 @@ export class ApplicationBuildRunner {
     if (exitCode !== 0) throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
   }
 
+  async #resolveTypecheckWorkerEntry() {
+    const candidates = [
+      path.join(this.#app.workspace.workspaceRoot, "pkgs/@akanjs/devkit/typecheck/typecheck.proc.ts"),
+      path.join(this.#app.workspace.workspaceRoot, "node_modules/@akanjs/devkit/typecheck/typecheck.proc.ts"),
+      path.join(import.meta.dir, "typecheck.proc.js"),
+      path.join(import.meta.dir, "typecheck.proc.ts"),
+    ];
+    for (const candidate of candidates) if (await Bun.file(candidate).exists()) return candidate;
+    throw new Error(`[cli] typecheck worker entry not found; looked in: ${candidates.join(", ")}`);
+  }
+
   async #buildOrThrow(label: string, config: Bun.BuildConfig): Promise<Bun.BuildOutput> {
     const result = await Bun.build(config);
     if (!result.success) throw new AggregateError(result.logs, `[${label}] Bun.build failed`);

package/applicationTestPreload.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+
+export const SIGNAL_TEST_PRELOAD_PATH = "test/signalTest.preload.ts";
+
+export interface SignalTestPreloadTarget {
+  cwdPath: string;
+}
+
+export async function resolveSignalTestPreloadPath(target: SignalTestPreloadTarget) {
+  const candidates: string[] = [];
+  const addResolvedPackageCandidate = (basePath: string) => {
+    try {
+      candidates.push(
+        path.join(path.dirname(Bun.resolveSync("akanjs/package.json", basePath)), SIGNAL_TEST_PRELOAD_PATH),
+      );
+    } catch {
+      // Source workspaces and published installs can resolve Akan packages from different roots.
+    }
+  };
+
+  addResolvedPackageCandidate(target.cwdPath);
+  addResolvedPackageCandidate(process.cwd());
+  addResolvedPackageCandidate(path.dirname(Bun.main));
+  addResolvedPackageCandidate(import.meta.dir);
+
+  candidates.push(
+    path.join(target.cwdPath, "../../node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH),
+    path.join(target.cwdPath, "../../pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH),
+    path.join(process.cwd(), "node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH),
+    path.join(process.cwd(), "pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH),
+    path.join(path.dirname(Bun.main), "../../akanjs", SIGNAL_TEST_PRELOAD_PATH),
+    path.resolve(import.meta.dir, "../../akanjs", SIGNAL_TEST_PRELOAD_PATH),
+  );
+
+  for (const candidate of [...new Set(candidates)]) {
+    if (await Bun.file(candidate).exists()) return candidate;
+  }
+
+  throw new Error(`Failed to locate ${SIGNAL_TEST_PRELOAD_PATH} from ${target.cwdPath}`);
+}

package/capacitorApp.ts

@@ -217,7 +217,7 @@ export class CapacitorApp {
       .split(path.sep)
       .join("/");
     const content = `import type { AppScanResult } from "akanjs";
-import { withBase } from "@akanjs/devkit/capacitor.base.config";
+import { withBase } from "akanjs/capacitor.base.config";
 import appInfo from "${appInfoPath.startsWith(".") ? appInfoPath : `./${appInfoPath}`}";
 
 export default withBase(

package/commandDecorators/command.ts

@@ -1,5 +1,5 @@
-import { confirm, input, select } from "@inquirer/prompts";
 import path from "node:path";
+import { confirm, input, select } from "@inquirer/prompts";
 import { Logger } from "akanjs/common";
 import chalk from "chalk";
 import { type Command, program } from "commander";
@@ -19,6 +19,32 @@ import { formatCommandHelp, formatHelp } from "./helpFormatter";
 import { type CommandCls, getTargetMetas } from "./targetMeta";
 
 const camelToKebabCase = (str: string) => str.replace(/([A-Z])/g, "-$1").toLowerCase();
+const loggedCliErrorObjects = new WeakSet<object>();
+const loggedCliErrorMessages = new Set<string>();
+
+const formatCliError = (error: unknown): string => {
+  if (error instanceof Error) return error.message || error.name;
+  if (typeof error === "string") return error.trim() || "Unknown error";
+  if (error === null || error === undefined) return "Unknown error";
+  try {
+    const json = JSON.stringify(error);
+    if (json) return json;
+  } catch {
+    return String(error);
+  }
+  return String(error) || "Unknown error";
+};
+
+const printCliError = (error: unknown) => {
+  if (typeof error === "object" && error !== null) {
+    if (loggedCliErrorObjects.has(error)) return;
+    loggedCliErrorObjects.add(error);
+  }
+  const message = formatCliError(error);
+  if (loggedCliErrorMessages.has(message)) return;
+  loggedCliErrorMessages.add(message);
+  Logger.rawLog(`\n${chalk.red(message)}`);
+};
 
 const handleOption = (programCommand: Command, argMeta: ArgMeta) => {
   const {
@@ -219,6 +245,7 @@ const getInternalArgumentValue = async (
 
 export const runCommands = async (...commands: CommandCls[]) => {
   process.on("unhandledRejection", (error) => {
+    printCliError(error);
     process.exit(1);
   });
   const __dirname = getDirname(import.meta.url);
@@ -339,8 +366,7 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
             await targetMeta.handler.call(cmd, ...commandArgs);
             Logger.rawLog();
           } catch (e) {
-            const errMsg = e instanceof Error ? e.message : typeof e === "string" ? e : JSON.stringify(e);
-            Logger.rawLog(`\n${chalk.red(errMsg)}`);
+            printCliError(e);
             throw e;
           }
         });

package/devkitUtils.test.ts

@@ -3,6 +3,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { ApplicationBuildReporter } from "./applicationBuildReporter";
+import { resolveSignalTestPreloadPath } from "./applicationTestPreload";
 import { TypeScriptDependencyScanner } from "./dependencyScanner";
 import { extractDependencies } from "./extractDeps";
 import { getModelFileData } from "./getModelFileData";
@@ -84,6 +85,26 @@ describe("extractDependencies", () => {
   });
 });
 
+describe("resolveSignalTestPreloadPath", () => {
+  test("resolves the preload file from an installed akanjs package", async () => {
+    const root = await makeTempRoot();
+    const libDir = path.join(root, "libs/shared");
+    await write(
+      path.join(root, "node_modules/akanjs/package.json"),
+      JSON.stringify({
+        name: "akanjs",
+        version: "0.0.0",
+        exports: { "./package.json": "./package.json" },
+      }),
+    );
+    await write(path.join(root, "node_modules/akanjs/test/signalTest.preload.ts"), "export {};\n");
+
+    await expect(resolveSignalTestPreloadPath({ cwdPath: libDir })).resolves.toContain(
+      "node_modules/akanjs/test/signalTest.preload.ts",
+    );
+  });
+});
+
 describe("TypeScriptDependencyScanner", () => {
   test("separates monorepo package, lib, runtime, and type-only dependencies", async () => {
     const root = await makeTempRoot();

package/executors.test.ts

@@ -3,7 +3,7 @@ import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises"
 import os from "node:os";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
-import { AppExecutor, Executor, PkgExecutor, WorkspaceExecutor } from "./executors";
+import { AppExecutor, CommandExecutionError, Executor, PkgExecutor, WorkspaceExecutor } from "./executors";
 import { AppInfo } from "./scanInfo";
 import type { PackageJson } from "./types";
 
@@ -48,6 +48,41 @@ afterEach(async () => {
 });
 
 describe("Executor filesystem helpers", () => {
+  test("reports command failures with command context and captured output", async () => {
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+
+    let error: unknown;
+    try {
+      await exec.spawn(process.execPath, ["--eval", "console.error('spawn failed'); process.exit(7)"]);
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(CommandExecutionError);
+    expect((error as CommandExecutionError).message).toContain(`Command failed: ${process.execPath}`);
+    expect((error as CommandExecutionError).message).toContain(`cwd: ${root}`);
+    expect((error as CommandExecutionError).message).toContain("exit code: 7");
+    expect((error as CommandExecutionError).message).toContain("spawn failed");
+  });
+
+  test("reports inherited stdio command failures with a fallback message", async () => {
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+
+    let error: unknown;
+    try {
+      await exec.spawn(process.execPath, ["--eval", "process.exit(3)"], { stdio: "inherit" });
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(CommandExecutionError);
+    expect((error as CommandExecutionError).message).toContain(`Command failed: ${process.execPath}`);
+    expect((error as CommandExecutionError).message).toContain(`cwd: ${root}`);
+    expect((error as CommandExecutionError).message).toContain("exit code: 3");
+  });
+
   test("resolves paths and reads/writes files relative to cwd", async () => {
     const root = await makeTempRoot();
     const exec = new Executor("fixture", root);

package/executors.ts

@@ -64,6 +64,58 @@ const staticTemplateFileExtensions = new Set([
   ".xml",
 ]);
 
+const formatCommandArg = (value: string) => (/^[\w@%+=:,./-]+$/.test(value) ? value : JSON.stringify(value));
+
+const formatCommandForDisplay = (command: string, args: string[] = []) =>
+  [command, ...args].map(formatCommandArg).join(" ");
+
+export interface CommandExecutionErrorOptions {
+  command: string;
+  args?: string[];
+  cwd: string;
+  code: number | null;
+  signal: string | null;
+  stdout?: string;
+  stderr?: string;
+  cause?: unknown;
+}
+
+export class CommandExecutionError extends Error {
+  command: string;
+  args: string[];
+  cwd: string;
+  code: number | null;
+  signal: string | null;
+  stdout: string;
+  stderr: string;
+
+  constructor({
+    command,
+    args = [],
+    cwd,
+    code,
+    signal,
+    stdout = "",
+    stderr = "",
+    cause,
+  }: CommandExecutionErrorOptions) {
+    const displayCommand = formatCommandForDisplay(command, args);
+    const status = signal ? `signal: ${signal}` : `exit code: ${code ?? "unknown"}`;
+    const output = (stderr || stdout).trim();
+    super([`Command failed: ${displayCommand}`, `cwd: ${cwd}`, status, output ? `\n${output}` : ""].join("\n"), {
+      cause,
+    });
+    this.name = "CommandExecutionError";
+    this.command = command;
+    this.args = args;
+    this.cwd = cwd;
+    this.code = code;
+    this.signal = signal;
+    this.stdout = stdout;
+    this.stderr = stderr;
+  }
+}
+
 export const execEmoji = {
   workspace: "🏠",
   app: "🚀",
@@ -197,22 +249,31 @@ export class Executor {
     Logger.raw(chalk.red(data.toString()));
   }
   exec(command: string, options: ExecOptions = {}) {
+    const cwd = options.cwd?.toString() ?? this.cwdPath;
     const proc = exec(command, { cwd: this.cwdPath, ...options });
+    let stdout = "";
+    let stderr = "";
     proc.stdout?.on("data", (data: Buffer) => {
+      stdout += data.toString();
       this.#stdout(data);
     });
     proc.stderr?.on("data", (data: Buffer) => {
+      stderr += data.toString();
       this.#stdout(data); // 정상로그도 stderr로 나옴
     });
     return new Promise((resolve, reject) => {
+      proc.on("error", (error) => {
+        reject(new CommandExecutionError({ command, cwd, code: null, signal: null, stdout, stderr, cause: error }));
+      });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal) reject({ code, signal });
+        if (!!code || signal) reject(new CommandExecutionError({ command, cwd, code, signal, stdout, stderr }));
         else resolve({ code, signal });
       });
     });
   }
 
   spawn(command: string, args: string[] = [], options: SpawnOptions = {}): Promise<string> {
+    const cwd = options.cwd?.toString() ?? this.cwdPath;
     const proc = spawn(command, args, {
       cwd: this.cwdPath,
       // stdio: "inherit",
@@ -232,8 +293,14 @@ export class Executor {
       this.#stdout(data); // 정상로그도 stderr로 나옴
     });
     return new Promise((resolve, reject) => {
+      proc.on("error", (error) => {
+        reject(
+          new CommandExecutionError({ command, args, cwd, code: null, signal: null, stdout, stderr, cause: error }),
+        );
+      });
       proc.on("close", (code, signal) => {
-        if (code !== 0 || signal) reject(stderr || stdout);
+        if (code !== 0 || signal)
+          reject(new CommandExecutionError({ command, args, cwd, code, signal, stdout, stderr }));
         else resolve(stdout);
       });
     });
@@ -247,20 +314,40 @@ export class Executor {
     return proc;
   }
   fork(modulePath: string, args: string[] = [], options: ForkOptions = {}) {
+    const cwd = options.cwd?.toString() ?? this.cwdPath;
     const proc = fork(modulePath, args, {
       cwd: this.cwdPath,
       // stdio: ["ignore", "inherit", "inherit", "ipc"],
       ...options,
     });
+    let stdout = "";
+    let stderr = "";
     proc.stdout?.on("data", (data: Buffer) => {
+      stdout += data.toString();
       this.#stdout(data);
     });
     proc.stderr?.on("data", (data: Buffer) => {
+      stderr += data.toString();
       this.#stderr(data);
     });
     return new Promise((resolve, reject) => {
+      proc.on("error", (error) => {
+        reject(
+          new CommandExecutionError({
+            command: modulePath,
+            args,
+            cwd,
+            code: null,
+            signal: null,
+            stdout,
+            stderr,
+            cause: error,
+          }),
+        );
+      });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal) reject({ code, signal });
+        if (!!code || signal)
+          reject(new CommandExecutionError({ command: modulePath, args, cwd, code, signal, stdout, stderr }));
         else resolve({ code, signal });
       });
     });

package/frontendBuild/buildRouteClient.test.ts

@@ -72,14 +72,12 @@ describe("route client store bootstrap", () => {
     expect(CLIENT_BUNDLE_NAMING.asset.includes("[name]")).toBe(false);
   });
 
-  test("resolves SSR client runtime aliases from the server renderer package", () => {
+  test("keeps start SSR client React imports bare and rewrites resolved fetch imports", () => {
     const aliases = RouteClientBuilder.resolveSsrClientRuntimeAliases();
 
-    expect(Object.keys(aliases)).toEqual(
+    expect(Object.keys(aliases)).not.toEqual(
       expect.arrayContaining(["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime"]),
     );
-    expect(aliases.react).toBe(Bun.resolveSync("react", RouteClientBuilder.resolveAkanServerEntry()));
-    expect(aliases.react).not.toBe("react");
     expect(aliases[Bun.resolveSync("akanjs/fetch", RouteClientBuilder.resolveAkanServerEntry())]).toBe("akanjs/fetch");
   });
 

package/frontendBuild/cssImportResolver.ts

@@ -24,9 +24,9 @@ export class CssImportResolver {
 
   async resolve(id: string, fromBase: string): Promise<string | null> {
     for (const resolve of [
+      () => this.#resolveWithTsconfig(id),
       () => this.#resolveWithBun(id, fromBase),
       () => this.#resolveWithRequire(id, fromBase),
-      () => this.#resolveWithTsconfig(id),
       () => this.#resolvePackageStyle(id, fromBase),
     ]) {
       const resolved = await resolve();
@@ -36,21 +36,27 @@ export class CssImportResolver {
   }
 
   #resolveWithBun(id: string, fromBase: string): string | null {
-    try {
-      const resolved = Bun.resolveSync(id, fromBase);
-      return CssImportResolver.isCssFile(resolved) ? resolved : null;
-    } catch {
-      return null;
+    for (const base of this.#resolutionBases(fromBase)) {
+      try {
+        const resolved = Bun.resolveSync(id, base);
+        if (CssImportResolver.isCssFile(resolved)) return resolved;
+      } catch {
+        // Try the next known package resolution root.
+      }
     }
+    return null;
   }
 
   #resolveWithRequire(id: string, fromBase: string): string | null {
-    try {
-      const resolved = require.resolve(id, { paths: [fromBase] });
-      return CssImportResolver.isCssFile(resolved) ? resolved : null;
-    } catch {
-      return null;
+    for (const base of this.#resolutionBases(fromBase)) {
+      try {
+        const resolved = require.resolve(id, { paths: [base] });
+        if (CssImportResolver.isCssFile(resolved)) return resolved;
+      } catch {
+        // Try the next known package resolution root.
+      }
     }
+    return null;
   }
 
   async #resolveWithTsconfig(id: string): Promise<string | null> {
@@ -77,8 +83,25 @@ export class CssImportResolver {
   async #resolvePackageStyle(id: string, fromBase: string): Promise<string | null> {
     const pkgName = CssImportResolver.getPackageName(id);
     if (!pkgName) return null;
+    for (const base of this.#resolutionBases(fromBase)) {
+      try {
+        const pkgPath = require.resolve(`${pkgName}/package.json`, { paths: [base] });
+        const resolved = await this.#resolvePackageStyleFromPackageJson(id, pkgName, pkgPath);
+        if (resolved) return resolved;
+      } catch {
+        // Try the next known package resolution root.
+      }
+    }
+    for (const pkgPath of this.#packageJsonCandidates(pkgName)) {
+      const resolved = await this.#resolvePackageStyleFromPackageJson(id, pkgName, pkgPath);
+      if (resolved) return resolved;
+    }
+    return null;
+  }
+
+  async #resolvePackageStyleFromPackageJson(id: string, pkgName: string, pkgPath: string): Promise<string | null> {
     try {
-      const pkgPath = require.resolve(`${pkgName}/package.json`, { paths: [fromBase] });
+      if (!(await Bun.file(pkgPath).exists())) return null;
       const pkgDir = path.dirname(pkgPath);
       const pkg = await Bun.file(pkgPath).json();
       const subpath = id === pkgName ? "." : `.${id.slice(pkgName.length)}`;
@@ -96,6 +119,19 @@ export class CssImportResolver {
     }
   }
 
+  #resolutionBases(fromBase: string): string[] {
+    return [fromBase, this.#workspaceRoot, path.dirname(Bun.main), path.resolve(path.dirname(Bun.main), "../..")];
+  }
+
+  #packageJsonCandidates(pkgName: string): string[] {
+    return [
+      path.join(this.#workspaceRoot, "pkgs", pkgName, "package.json"),
+      path.join(this.#workspaceRoot, "node_modules", pkgName, "package.json"),
+      path.join(path.dirname(Bun.main), "node_modules", pkgName, "package.json"),
+      path.join(path.dirname(Bun.main), "../../", pkgName, "package.json"),
+    ];
+  }
+
   async #firstExisting(basePath: string): Promise<string | null> {
     for (const suffix of CSS_IMPORT_EXTS) {
       const candidate = `${basePath}${suffix}`;

package/frontendBuild/routeClientBuilder.ts

@@ -224,11 +224,7 @@ export class RouteClientBuilder {
 
   static resolveSsrClientRuntimeAliases(): Record<string, string> {
     const serverEntry = RouteClientBuilder.resolveAkanServerEntry();
-    const aliases = Object.fromEntries(
-      SSR_CLIENT_ALIAS_EXTERNALS.map((specifier) => [specifier, Bun.resolveSync(specifier, serverEntry)]),
-    ) as Record<string, string>;
-    aliases[Bun.resolveSync("akanjs/fetch", serverEntry)] = "akanjs/fetch";
-    return aliases;
+    return { [Bun.resolveSync("akanjs/fetch", serverEntry)]: "akanjs/fetch" };
   }
 
   static resolveSsrClientExternalOptions(command: "build" | "start"): {

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -92,15 +92,31 @@ export class SsrBaseArtifactBuilder {
     return { rscClientUrl, vendorMap };
   }
   async #resolveAkanServerPath() {
-    const candidates = [
+    const candidates: string[] = [];
+    try {
+      candidates.push(path.dirname(Bun.resolveSync("akanjs/server", this.#app.workspace.workspaceRoot)));
+    } catch {
+      // Source workspaces and bundled CLI execution have different resolution roots; try explicit candidates below.
+    }
+    candidates.push(
       path.join(this.#app.workspace.workspaceRoot, "pkgs/akanjs/server"),
+      path.join(this.#app.workspace.workspaceRoot, "node_modules/akanjs/server"),
+    );
+    try {
+      candidates.push(path.dirname(Bun.resolveSync("akanjs/server", path.dirname(Bun.main))));
+    } catch {
+      // Published CLI installs may hoist dependencies differently; explicit Bun.main candidates cover that.
+    }
+    candidates.push(
+      path.join(path.dirname(Bun.main), "node_modules/akanjs/server"),
+      path.join(path.dirname(Bun.main), "../../akanjs/server"),
       path.resolve(import.meta.dir, "../../server"),
       path.resolve(import.meta.dir, "../server"),
-    ];
+    );
     for (const candidate of candidates) {
       if (await Bun.file(path.join(candidate, "rscClient.tsx")).exists()) return candidate;
     }
-    return candidates[0];
+    throw new Error(`[base-artifact] failed to locate akanjs/server; looked in: ${candidates.join(", ")}`);
   }
 
   async #buildStyleAssets(): Promise<{

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -143,6 +143,7 @@ export class IncrementalBuilderHost {
         app.workspace.workspaceRoot,
         "node_modules/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts",
       ),
+      path.join(import.meta.dir, "incrementalBuilder.proc.js"),
       path.join(import.meta.dir, "incrementalBuilder.proc.ts"),
     ];
     for (const c of candidates)

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -1,5 +1,4 @@
 import path from "node:path";
-import { Logger } from "akanjs/common";
 import {
   type App,
   AppExecutor,
@@ -16,6 +15,7 @@ import {
   WatchRootResolver,
   WorkspaceExecutor,
 } from "@akanjs/devkit";
+import { Logger } from "akanjs/common";
 import type {
   BaseBuildArtifact,
   BuilderEvent,

package/index.ts

@@ -4,6 +4,7 @@ export * from "./akanConfig";
 export * from "./applicationBuildReporter";
 export * from "./applicationBuildRunner";
 export * from "./applicationReleasePackager";
+export * from "./applicationTestPreload";
 export * from "./artifact";
 export * from "./auth";
 export * from "./builder";

package/lint/no-import-external-library.grit

@@ -6,6 +6,7 @@ JsModuleSource() as $source where {
   not $source <: or {
     r"\"\..*",
     r"\"akanjs.*",
+    r"\"@akanjs.*",
     r"\"@playwright.*",
     r"\"@radix-ui.*",
     r"\"@apps/.*",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.1.0-rc.1",
+  "version": "2.1.0-rc.11",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -23,11 +23,6 @@
       "default": "./index.ts"
     },
     "./package.json": "./package.json",
-    "./capacitor.base.config": {
-      "import": "./capacitor.base.config.ts",
-      "types": "./capacitor.base.config.ts",
-      "default": "./capacitor.base.config.ts"
-    },
     "./*": "./*"
   },
   "dependencies": {
@@ -36,9 +31,10 @@
     "@langchain/deepseek": "^1.0.26",
     "@langchain/openai": "^1.4.6",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.1.0-rc.0",
+    "akanjs": "2.1.0-rc.10",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
+    "daisyui": "^5.5.20",
     "fontaine": "^0.8.0",
     "fonteditor-core": "^2.6.3",
     "ignore": "^7.0.5",
@@ -47,6 +43,7 @@
     "ora": "^9.4.0",
     "ssh2": "^1.17.0",
     "subset-font": "^2.5.0",
+    "tailwind-scrollbar": "^4.0.2",
     "tailwindcss": "^4.3.0",
     "typescript": "^6.0.3"
   },

package/src/capacitorApp.ts

@@ -1,9 +1,9 @@
+import { type AppExecutor, FileSys } from "@akanjs/devkit";
 import type { CapacitorConfig } from "@capacitor/cli";
 import { MobileProject } from "@trapezedev/project";
 import type { AndroidProject } from "@trapezedev/project/dist/android/project";
 import type { IosProject } from "@trapezedev/project/dist/ios/project";
 import { capitalize } from "akanjs/common";
-import { type AppExecutor, FileSys } from "@akanjs/devkit";
 
 import { FileEditor } from "./fileEditor";
 

package/typecheck/typecheck.proc.ts

@@ -0,0 +1,14 @@
+import { TypeChecker } from "../typeChecker";
+
+try {
+  const configPath = process.env.AKAN_TYPECHECK_TSCONFIG;
+  if (!configPath) throw new Error("AKAN_TYPECHECK_TSCONFIG is required");
+  const result = TypeChecker.checkProject(configPath);
+  if (result.errors.length > 0) {
+    console.error(result.message);
+    process.exit(1);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/capacitor.base.config.ts

@@ -1,88 +0,0 @@
-import os from "node:os";
-import type { CapacitorConfig } from "@capacitor/cli";
-import type { AkanMobileTargetConfig, AppScanResult } from "akanjs";
-
-const getLocalIP = () => {
-  const interfaces = os.networkInterfaces();
-  for (const interfaceName in interfaces) {
-    const iface = interfaces[interfaceName];
-    if (!iface) continue;
-    for (const alias of iface) {
-      if (alias.family === "IPv4" && !alias.internal) return alias.address;
-    }
-  }
-  return "127.0.0.1"; // fallback to localhost if no suitable IP found
-};
-
-const normalizeBasePath = (basePath: string | undefined) => basePath?.replace(/^\/+|\/+$/g, "");
-
-const routeBasePaths = (appInfo: AppScanResult) =>
-  new Set(
-    appInfo.routes
-      .map((route) => route.replace(/^\.\//, "").split("/")[0])
-      .filter((segment): segment is string => !!segment && !segment.startsWith("_") && !segment.startsWith("(")),
-  );
-
-const resolveTarget = (appInfo: AppScanResult, targetName = process.env.AKAN_MOBILE_TARGET) => {
-  const targets = appInfo.akanConfig.mobile.targets;
-  if (!targets || Object.keys(targets).length === 0) throw new Error("Akan mobile target metadata is missing.");
-  if (targetName) {
-    const target = targets[targetName];
-    if (!target) {
-      const basePath = normalizeBasePath(targetName);
-      const [template] = Object.values(targets);
-      if (basePath && template && routeBasePaths(appInfo).has(basePath))
-        return { ...template, name: basePath, basePath };
-      throw new Error(`Akan mobile target '${targetName}' was not found.`);
-    }
-    return target;
-  }
-  const entries = Object.entries(targets);
-  if (entries.length !== 1) throw new Error("AKAN_MOBILE_TARGET is required when multiple mobile targets exist.");
-  return entries[0]?.[1] as AkanMobileTargetConfig;
-};
-
-const localCsrUrl = (ip: string, target: AkanMobileTargetConfig) => {
-  const basePath = normalizeBasePath(target.basePath);
-  const port = process.env.AKAN_PUBLIC_CLIENT_PORT ?? process.env.PORT ?? "8282";
-  return `http://${ip}:${port}/${basePath ? `${basePath}` : ""}?csr=true`;
-};
-
-export const withBase = (
-  configImp: (config: CapacitorConfig, target: AkanMobileTargetConfig) => CapacitorConfig = (config) => config,
-  appData?: AppScanResult,
-  targetName?: string,
-) => {
-  const ip = getLocalIP();
-  const appInfo = appData;
-  if (!appInfo) throw new Error("withBase requires apps/<app>/akan.app.json metadata.");
-  const target = resolveTarget(appInfo, targetName);
-  const baseConfig: CapacitorConfig = {
-    ...target,
-    appId: target.appId,
-    appName: target.appName,
-    webDir: "dist",
-    server:
-      process.env.APP_OPERATION_MODE !== "release"
-        ? {
-            androidScheme: "http",
-            url: localCsrUrl(ip, target),
-            cleartext: true,
-            allowNavigation: [ip, "localhost"],
-          }
-        : {
-            allowNavigation: ["*"],
-          },
-    plugins: {
-      CapacitorCookies: { enabled: true },
-      ...target.plugins,
-    },
-    android: {
-      ...target.android,
-    },
-    ios: {
-      ...target.ios,
-    },
-  };
-  return configImp(baseConfig, target);
-};