@akanjs/devkit 2.1.0-rc.9 → 2.1.1-rc.0

package/akanConfig/akanConfig.test.ts

@@ -25,8 +25,8 @@ const packageJson: PackageJson = {
 
 const app = { name: "portal" } as never;
 const baseDevEnv = {
-  repoName: "akansoft",
-  serveDomain: "akamir.com",
+  repoName: "akanjs",
+  serveDomain: "akanjs.com",
   env: "debug" as const,
   portOffset: 0,
   workspaceRoot: "/workspace",
@@ -37,9 +37,9 @@ describe("AkanAppConfig", () => {
     const config = new AkanAppConfig(app, ["shared"], packageJson, {}, baseDevEnv);
 
     expect([...config.domains].sort()).toEqual([
-      "portal-debug.akamir.com",
-      "portal-develop.akamir.com",
-      "portal-main.akamir.com",
+      "portal-debug.akanjs.com",
+      "portal-develop.akanjs.com",
+      "portal-main.akanjs.com",
     ]);
     expect(config.basePaths.size).toBe(0);
     expect(config.i18n.defaultLocale).toBe("en");
@@ -95,10 +95,10 @@ describe("AkanAppConfig", () => {
     expect([...config.domains].sort()).toEqual(["qa.root.local", "root.local"]);
     expect([...config.basePaths]).toEqual(["admin"]);
     expect([...(config.subRoutes.get("admin") ?? [])].sort()).toEqual([
-      "admin-debug.akamir.com",
-      "admin-develop.akamir.com",
-      "admin-main.akamir.com",
-      "admin-qa.akamir.com",
+      "admin-debug.akanjs.com",
+      "admin-develop.akanjs.com",
+      "admin-main.akanjs.com",
+      "admin-qa.akanjs.com",
       "admin.local",
       "admin.main.local",
     ]);
@@ -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/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,10 +47,21 @@ 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;
 
+export const AKAN_OPTIONAL_BACKEND_EXTERNALS = [
+  "@libsql/client",
+  "bullmq",
+  "croner",
+  "ioredis",
+  "postgres",
+  "protobufjs",
+] as const;
+
 export class ApplicationBuildRunner {
   #app: App;
   #fast: boolean;
@@ -161,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}`);
@@ -183,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,

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/artifact/implicitRootLayout.test.ts

@@ -0,0 +1,75 @@
+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 { resolveSsrPageEntries } from "./implicitRootLayout";
+
+const tempRoots: string[] = [];
+
+const makeTempRoot = async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-implicit-root-layout-"));
+  tempRoots.push(root);
+  return root;
+};
+
+const write = async (filePath: string, content: string) => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+};
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("resolveSsrPageEntries", () => {
+  test("inherits root layout static exports for grouped root boundaries", async () => {
+    const appRoot = await makeTempRoot();
+    const pageRoot = path.join(appRoot, "page");
+    const rootLayoutPath = path.join(pageRoot, "_layout.tsx");
+    const groupedLayoutPath = path.join(pageRoot, "(home)", "_layout.tsx");
+
+    await write(path.join(appRoot, "env", "env.client.ts"), "export const env = {};\n");
+    await write(rootLayoutPath, 'export const theme = "dark";\nexport const fonts = [{ name: "pretendard" }];\n');
+    await write(groupedLayoutPath, "export default function Layout({ children }) { return children; }\n");
+
+    const entries = await resolveSsrPageEntries({
+      appCwdPath: appRoot,
+      appName: "demo",
+      pageKeys: ["./_layout.tsx", "./(home)/_layout.tsx", "./(home)/_index.tsx"],
+    });
+
+    const groupedRoot = entries.find((entry) => entry.key === "./(home)/__root_layout.tsx");
+    expect(groupedRoot).toBeDefined();
+    expect(groupedRoot?.seedAbsPaths).toContain(rootLayoutPath);
+    expect(groupedRoot?.seedAbsPaths).toContain(groupedLayoutPath);
+
+    const generatedSource = await Bun.file(groupedRoot?.moduleAbsPath ?? "").text();
+    expect(generatedSource).toContain('import * as inheritedLayout from "../../../page/_layout.tsx";');
+    expect(generatedSource).not.toContain("<System.Provider");
+    expect(generatedSource).toContain(
+      "<UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>",
+    );
+  });
+
+  test("keeps system provider for grouped root boundaries without an ancestor root", async () => {
+    const appRoot = await makeTempRoot();
+    const pageRoot = path.join(appRoot, "page");
+    const groupedLayoutPath = path.join(pageRoot, "(home)", "_layout.tsx");
+
+    await write(path.join(appRoot, "env", "env.client.ts"), "export const env = {};\n");
+    await write(groupedLayoutPath, 'export const theme = "dark";\n');
+
+    const entries = await resolveSsrPageEntries({
+      appCwdPath: appRoot,
+      appName: "demo",
+      pageKeys: ["./(home)/_layout.tsx", "./(home)/_index.tsx"],
+    });
+
+    const groupedRoot = entries.find((entry) => entry.key === "./(home)/__root_layout.tsx");
+    expect(groupedRoot).toBeDefined();
+
+    const generatedSource = await Bun.file(groupedRoot?.moduleAbsPath ?? "").text();
+    expect(generatedSource).toContain("<System.Provider");
+    expect(generatedSource).toContain("theme={userLayout.theme ?? inheritedLayout.theme}");
+  });
+});

package/artifact/implicitRootLayout.ts

@@ -68,6 +68,23 @@ function findRootBoundaries(pageKeys: string[], appCwdPath: string, basePaths: I
   return [...boundaries.values()].sort((a, b) => a.segments.join("/").localeCompare(b.segments.join("/")));
 }
 
+function hasAncestorRootBoundary(boundary: RootBoundary, boundaries: RootBoundary[]): boolean {
+  return boundaries.some(
+    (candidate) =>
+      candidate !== boundary &&
+      candidate.segments.length < boundary.segments.length &&
+      candidate.segments.every((segment, index) => boundary.segments[index] === segment),
+  );
+}
+
+function findExplicitRootLayoutAbsPath(pageKeys: string[], appCwdPath: string): string | null {
+  const rootLayoutKey = pageKeys.find((key) => {
+    const segments = getRootBoundarySegments(key);
+    return segments !== null && segments.length === 0;
+  });
+  return rootLayoutKey ? path.resolve(appCwdPath, "page", rootLayoutKey.replace(/^\.\//, "")) : null;
+}
+
 function routePrefixForSegments(segments: string[]): string | null {
   const visible = segments.filter((segment) => !/^\(.+\)$/.test(segment));
   return visible[0] ?? null;
@@ -86,7 +103,9 @@ async function writeGeneratedRootLayoutFile(opts: {
   appCwdPath: string;
   appName: string;
   boundary: RootBoundary;
+  rootSourceAbsPath: string | null;
   includeStInit: boolean;
+  includeSystemProvider: boolean;
 }): Promise<string> {
   await assertEnvClientConvention(opts.appCwdPath, opts.appName);
   const absPath = implicitRootLayoutAbsPath(opts.appCwdPath, opts.boundary.segments);
@@ -95,14 +114,29 @@ async function writeGeneratedRootLayoutFile(opts: {
     ? path.relative(path.dirname(absPath), opts.boundary.sourceAbsPath).split(path.sep).join("/")
     : null;
   const sourceSpecifier = sourceRel ? (sourceRel.startsWith(".") ? sourceRel : `./${sourceRel}`) : null;
+  const inheritedSourceAbsPath =
+    opts.rootSourceAbsPath && opts.rootSourceAbsPath !== opts.boundary.sourceAbsPath ? opts.rootSourceAbsPath : null;
+  const inheritedSourceRel = inheritedSourceAbsPath
+    ? path.relative(path.dirname(absPath), inheritedSourceAbsPath).split(path.sep).join("/")
+    : null;
+  const inheritedSourceSpecifier = inheritedSourceRel
+    ? inheritedSourceRel.startsWith(".")
+      ? inheritedSourceRel
+      : `./${inheritedSourceRel}`
+    : null;
   const clientImport = opts.includeStInit
     ? `import { st } from "@apps/${opts.appName}/client";\nvoid st;\n`
     : `import "@apps/${opts.appName}/client";\n`;
+  const inheritedImport = inheritedSourceSpecifier
+    ? `import * as inheritedLayout from ${JSON.stringify(inheritedSourceSpecifier)};\n`
+    : "const inheritedLayout = {};\n";
   const prefix = routePrefixForSegments(opts.boundary.segments);
   const userImport = sourceSpecifier
     ? `import UserLayout, * as userLayout from ${JSON.stringify(sourceSpecifier)};\n`
     : "const UserLayout = ({ children }) => children;\nconst userLayout = {};\n";
-  const source = `import type { LayoutProps, PageProps } from "akanjs/client";\nimport { loadFonts } from "akanjs/client";\nimport { System } from "akanjs/ui";\nimport { env } from "@apps/${opts.appName}/env/env.client";\n${clientImport}${userImport}\nconst userFonts = userLayout.fonts ?? [];\nconst defaultFonts = userFonts.filter((font) => font.default);\nif (defaultFonts.length > 1) throw new Error("[route-convention] only one default font is allowed per root layout");\nconst defaultFont = defaultFonts[0];\nconst defaultFontClassName = defaultFont ? (defaultFont.className ?? \`font-\${defaultFont.name}\`) : undefined;\n\nexport async function generateHead(props: PageProps) {\n  if (userLayout.generateHead) return userLayout.generateHead(props);\n  return userLayout.head;\n}\n\nexport default function GeneratedLayout({ children, params, searchParams }: LayoutProps) {\n  return (\n    <System.Provider\n      of={GeneratedLayout as never}\n      appName=${JSON.stringify(opts.appName)}\n      ${prefix ? `prefix=${JSON.stringify(prefix)}\n      ` : ""}params={params}\n      manifest={userLayout.manifest}\n      env={env}\n      theme={userLayout.theme}\n      fonts={loadFonts(userFonts)}\n      className={defaultFontClassName}\n      gaTrackingId={userLayout.gaTrackingId}\n      layoutStyle={userLayout.layoutStyle}\n      reconnect={userLayout.reconnect ?? false}\n    >\n      <UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>\n    </System.Provider>\n  );\n}\n`;
+  const source = opts.includeSystemProvider
+    ? `import type { LayoutProps, PageProps } from "akanjs/client";\nimport { loadFonts } from "akanjs/client";\nimport { System } from "akanjs/ui";\nimport { env } from "@apps/${opts.appName}/env/env.client";\n${clientImport}${inheritedImport}${userImport}\nconst userFonts = userLayout.fonts ?? inheritedLayout.fonts ?? [];\nconst defaultFonts = userFonts.filter((font) => font.default);\nif (defaultFonts.length > 1) throw new Error("[route-convention] only one default font is allowed per root layout");\nconst defaultFont = defaultFonts[0];\nconst defaultFontClassName = defaultFont ? (defaultFont.className ?? \`font-\${defaultFont.name}\`) : undefined;\n\nexport async function generateHead(props: PageProps) {\n  if (userLayout.generateHead) return userLayout.generateHead(props);\n  if (userLayout.head !== undefined) return userLayout.head;\n  if (inheritedLayout.generateHead) return inheritedLayout.generateHead(props);\n  return inheritedLayout.head;\n}\n\nexport default function GeneratedLayout({ children, params, searchParams }: LayoutProps) {\n  return (\n    <System.Provider\n      of={GeneratedLayout as never}\n      appName=${JSON.stringify(opts.appName)}\n      ${prefix ? `prefix=${JSON.stringify(prefix)}\n      ` : ""}params={params}\n      manifest={userLayout.manifest ?? inheritedLayout.manifest}\n      env={env}\n      theme={userLayout.theme ?? inheritedLayout.theme}\n      fonts={loadFonts(userFonts)}\n      className={defaultFontClassName}\n      gaTrackingId={userLayout.gaTrackingId ?? inheritedLayout.gaTrackingId}\n      layoutStyle={userLayout.layoutStyle ?? inheritedLayout.layoutStyle}\n      reconnect={userLayout.reconnect ?? inheritedLayout.reconnect ?? false}\n    >\n      <UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>\n    </System.Provider>\n  );\n}\n`
+    : `import type { LayoutProps, PageProps } from "akanjs/client";\n${inheritedImport}${userImport}\nexport async function generateHead(props: PageProps) {\n  if (userLayout.generateHead) return userLayout.generateHead(props);\n  if (userLayout.head !== undefined) return userLayout.head;\n  if (inheritedLayout.generateHead) return inheritedLayout.generateHead(props);\n  return inheritedLayout.head;\n}\n\nexport default function GeneratedLayout({ children, params, searchParams }: LayoutProps) {\n  return <UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>;\n}\n`;
   await Bun.write(absPath, source);
   return absPath;
 }
@@ -120,6 +154,8 @@ export async function resolveSsrPageEntries(opts: {
   const absPageDir = path.resolve(opts.appCwdPath, "page");
   const hasSt = await appHasStModule(opts.appCwdPath);
   const basePaths = opts.basePaths ?? [];
+  const rootSourceAbsPath = findExplicitRootLayoutAbsPath(opts.pageKeys, opts.appCwdPath);
+  const rootBoundaries = findRootBoundaries(opts.pageKeys, opts.appCwdPath, basePaths);
   const rootLayoutKeys = new Set(
     opts.pageKeys.filter((key) => {
       const segments = getRootBoundarySegments(key);
@@ -133,15 +169,17 @@ export async function resolveSsrPageEntries(opts: {
       moduleAbsPath: path.resolve(absPageDir, key),
     }));
   const generated = await Promise.all(
-    findRootBoundaries(opts.pageKeys, opts.appCwdPath, basePaths).map(async (boundary) => ({
+    rootBoundaries.map(async (boundary) => ({
       key: implicitRootLayoutKey(boundary.segments),
       moduleAbsPath: await writeGeneratedRootLayoutFile({
         appCwdPath: opts.appCwdPath,
         appName: opts.appName,
         boundary,
+        rootSourceAbsPath,
         includeStInit: hasSt && boundary.segments.length === 0,
+        includeSystemProvider: !hasAncestorRootBoundary(boundary, rootBoundaries),
       }),
-      seedAbsPaths: boundary.sourceAbsPath ? [boundary.sourceAbsPath] : [],
+      seedAbsPaths: [...new Set([boundary.sourceAbsPath, rootSourceAbsPath].filter((absPath) => absPath !== null))],
     })),
   );
   const entries = [...base, ...generated];

package/artifact/routeSeedIndex.test.ts

@@ -46,7 +46,7 @@ describe("computeRouteSeedIndex", () => {
   });
 
   test("serializes seed paths relative to the artifact directory", () => {
-    const artifactDir = "/repo/dist/apps/angelo/.akan/artifact";
+    const artifactDir = "/repo/dist/apps/akan/.akan/artifact";
     const serialized = serializeRouteSeedIndexForArtifact(
       {
         entries: [
@@ -54,36 +54,36 @@ describe("computeRouteSeedIndex", () => {
             routeId: "/profile",
             pattern: "/profile",
             seeds: [
-              "/repo/dist/apps/angelo/.akan/generated/implicit-root-layout.tsx",
-              "/repo/apps/angelo/page/profile.tsx",
+              "/repo/dist/apps/akan/.akan/generated/implicit-root-layout.tsx",
+              "/repo/apps/akan/page/profile.tsx",
             ],
           },
         ],
-        globalLayoutFiles: ["/repo/dist/apps/angelo/.akan/generated/implicit-root-layout.tsx"],
+        globalLayoutFiles: ["/repo/dist/apps/akan/.akan/generated/implicit-root-layout.tsx"],
       },
       artifactDir,
     );
 
     expect(serialized.entries[0]?.seeds).toEqual([
       "../generated/implicit-root-layout.tsx",
-      "../../../../../apps/angelo/page/profile.tsx",
+      "../../../../../apps/akan/page/profile.tsx",
     ]);
     expect(serialized.globalLayoutFiles).toEqual(["../generated/implicit-root-layout.tsx"]);
     expect(JSON.stringify(serialized)).not.toContain("/repo/");
   });
 
   test("omits source seed metadata for production artifacts", () => {
-    const artifactDir = "/repo/dist/apps/angelo/.akan/artifact";
+    const artifactDir = "/repo/dist/apps/akan/.akan/artifact";
     const serialized = serializeRouteSeedIndexForArtifact(
       {
         entries: [
           {
             routeId: "/:lang/profile",
             pattern: "/:lang/profile",
-            seeds: ["/repo/apps/angelo/page/profile.tsx"],
+            seeds: ["/repo/apps/akan/page/profile.tsx"],
           },
         ],
-        globalLayoutFiles: ["/repo/apps/angelo/.akan/generated/implicit-root-layout.tsx"],
+        globalLayoutFiles: ["/repo/apps/akan/.akan/generated/implicit-root-layout.tsx"],
       },
       artifactDir,
       { production: true },

package/cloud/cloudApi.ts

@@ -0,0 +1,101 @@
+interface AccessToken {
+  jwt: string;
+  refreshToken: string;
+  expiresAt: Date;
+}
+
+class HttpClient {
+  readonly baseUrl: string;
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl;
+  }
+  async get<T>(
+    url: string,
+    { headers }: { headers?: Record<string, string> } = {},
+  ): Promise<T> {
+    const response = await fetch(`${this.baseUrl}${url}`, {
+      headers: { "Content-Type": "application/json", ...headers },
+    });
+    return response.json();
+  }
+  async post<T>(
+    url: string,
+    data: unknown,
+    { headers }: { headers?: Record<string, string> } = {},
+  ): Promise<T> {
+    const isFormData = data instanceof FormData;
+    const response = await fetch(`${this.baseUrl}${url}`, {
+      method: "POST",
+      body: isFormData ? data : JSON.stringify(data),
+      headers: isFormData
+        ? headers
+        : { "Content-Type": "application/json", ...headers },
+    });
+    return response.json();
+  }
+}
+
+export class CloudApi {
+  readonly api: HttpClient;
+  #accessToken: AccessToken | null = null;
+  constructor(
+    host: string,
+    { accessToken }: { accessToken?: AccessToken } = {},
+  ) {
+    this.api = new HttpClient(`${host}/api`);
+    this.#accessToken = accessToken ?? null;
+  }
+
+  async uploadEnv(
+    devProjectId: string,
+    fileStream: ReadableStream,
+  ): Promise<boolean> {
+    const formData = new FormData();
+    formData.append("devProjectId", devProjectId);
+    formData.append("fileStream", await new Response(fileStream).blob());
+    const response = await this.api.post<{ success: boolean }>(
+      `/uploadEnv/${devProjectId}`,
+      formData,
+    );
+    return response.success;
+  }
+  async downloadEnv(devProjectId: string): Promise<boolean> {
+    const response = await this.api.get<{ success: boolean }>(
+      `/downloadEnv/${devProjectId}`,
+    );
+    return response.success;
+  }
+  async getRemoteAuthToken(remoteId: string): Promise<AccessToken> {
+    if (this.#needRefreshToken()) return await this.refreshAuthToken();
+    else if (this.#accessToken) return this.#accessToken;
+    const accessToken = await this.api.get<AccessToken>(
+      `/getRemoteAuthToken/${remoteId}`,
+    );
+    this.#accessToken = {
+      jwt: accessToken.jwt,
+      refreshToken: accessToken.refreshToken,
+      expiresAt: new Date(accessToken.expiresAt),
+    };
+    return accessToken;
+  }
+  async refreshAuthToken(): Promise<AccessToken> {
+    const response = await this.api.post<AccessToken>(
+      `/refreshRemoteAuthToken`,
+      {
+        refreshToken: this.#accessToken?.refreshToken,
+      },
+    );
+    this.#accessToken = {
+      jwt: response.jwt,
+      refreshToken: response.refreshToken,
+      expiresAt: new Date(response.expiresAt),
+    };
+    return response;
+  }
+  #needRefreshToken(): boolean {
+    return !!(
+      this.#accessToken?.expiresAt &&
+      this.#accessToken.expiresAt.getTime() < Date.now() - 1000 * 60 * 60
+    );
+  }
+}

package/cloud/index.ts

@@ -0,0 +1 @@
+export * from "./cloudApi";

package/constants.ts

@@ -3,8 +3,12 @@ import type { SupportedLlmModel } from "./aiEditor";
 export const basePath = `${Bun.env.HOME ?? Bun.env.USERPROFILE}/.akan`;
 export const configPath = `${basePath}/config.json`;
 export const akanCloudHost =
-  process.env.AKAN_PUBLIC_OPERATION_MODE === "local" ? "http://localhost" : "https://cloud.akanjs.com";
-export const akanCloudUrl = `${akanCloudHost}${process.env.AKAN_PUBLIC_OPERATION_MODE === "local" ? ":8282" : ""}/메ㅑ`;
+  process.env.AKAN_PUBLIC_OPERATION_MODE === "local"
+    ? "http://localhost"
+    : "https://cloud.akanjs.com";
+export const akanCloudUrl = `${akanCloudHost}${
+  process.env.AKAN_PUBLIC_OPERATION_MODE === "local" ? ":8282" : ""
+}/api`;
 
 export interface HostConfig {
   auth?: {
@@ -22,4 +26,7 @@ export interface AkanGlobalConfig {
     apiKey: string;
   } | null;
 }
-export const defaultAkanGlobalConfig: AkanGlobalConfig = { cloudHost: {}, llm: null };
+export const defaultAkanGlobalConfig: AkanGlobalConfig = {
+  cloudHost: {},
+  llm: null,
+};

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.ts

@@ -239,8 +239,6 @@ export class Executor {
     this.logger = new Logger(name);
     this.logs = [] as string[];
     this.cwdPath = cwdPath;
-    //! TODO: 테스트 확인 필요
-    // if (!(await Bun.file(cwdPath).exists())) await mkdir(cwdPath, { recursive: true });
   }
   #stdout(data: Buffer) {
     if (Executor.verbose) Logger.raw(chalk.dim(data.toString()));

package/frontendBuild/buildRouteClient.test.ts

@@ -29,14 +29,14 @@ describe("route client store bootstrap", () => {
   test("wraps client entries with app client bootstrap before re-exporting components", () => {
     const original = "/repo/pkgs/akanjs/ui/Model/NewWrapper_Client.tsx";
     const source = RouteClientBuilder.createStoreBootstrapEntrySource({
-      appName: "angelo",
+      appName: "akan",
       originalEntry: original,
       exportNames: ["NewWrapper_Client", "default"],
     });
 
     expect(source).toBe(
       [
-        'import "@apps/angelo/client";',
+        'import "@apps/akan/client";',
         `export { NewWrapper_Client } from ${JSON.stringify(original)};`,
         `export { default } from ${JSON.stringify(original)};`,
         "",
@@ -45,12 +45,12 @@ describe("route client store bootstrap", () => {
   });
 
   test("remaps wrapper manifest keys back to original client entry paths", () => {
-    const wrapper = "/repo/apps/angelo/.akan/generated/client-entry-bootstrap/NewWrapper_Client.tsx";
+    const wrapper = "/repo/apps/akan/.akan/generated/client-entry-bootstrap/NewWrapper_Client.tsx";
     const original = "/repo/pkgs/akanjs/ui/Model/NewWrapper_Client.tsx";
     const remapped = RouteClientBuilder.resolveOriginalManifestEntry(
-      "apps/angelo/.akan/generated/client-entry-bootstrap/NewWrapper_Client.tsx#NewWrapper_Client",
+      "apps/akan/.akan/generated/client-entry-bootstrap/NewWrapper_Client.tsx#NewWrapper_Client",
       new Map([[wrapper, original]]),
-      new Map([[wrapper, "apps/angelo/.akan/generated/client-entry-bootstrap/NewWrapper_Client.tsx"]]),
+      new Map([[wrapper, "apps/akan/.akan/generated/client-entry-bootstrap/NewWrapper_Client.tsx"]]),
       "/repo",
     );
 

package/frontendBuild/frontendBuild.test.ts

@@ -10,6 +10,7 @@ import { CssImportResolver } from "./cssImportResolver";
 import { HmrChangeClassifier } from "./hmrChangeClassifier";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 import { RoutesManifestArtifactSerializer } from "./routesManifestArtifactSerializer";
+import { prepareCssAsset } from "./ssrBaseArtifactBuilder";
 
 const tempRoots: string[] = [];
 
@@ -97,6 +98,32 @@ describe("CsrArtifactBuilder", () => {
   });
 });
 
+describe("SsrBaseArtifactBuilder", () => {
+  test("minifies CSS assets only for production builds", async () => {
+    const css = [
+      ".card {",
+      "  color: red;",
+      "  padding: 1rem;",
+      "}",
+      "",
+      "@media (width >= 768px) {",
+      "  .card {",
+      "    color: blue;",
+      "  }",
+      "}",
+      "",
+    ].join("\n");
+
+    const development = await prepareCssAsset("start", "", css);
+    const production = await prepareCssAsset("build", "", css);
+
+    expect(development).toBe(css);
+    expect(production.length).toBeLessThan(css.length);
+    expect(production).toContain(".card{");
+    expect(production).not.toContain("\n  ");
+  });
+});
+
 describe("RoutesManifestArtifactSerializer", () => {
   test("serializes absolute artifact paths relative to artifact directory", () => {
     const manifest = {

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { optimize } from "@tailwindcss/node";
 import type { BaseBuildArtifact } from "akanjs/server";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "../artifact/routeSeedIndex";
@@ -16,6 +17,11 @@ export interface BuildSsrBaseArtifactResult {
   optimizedFonts: Awaited<ReturnType<FontOptimizer["optimize"]>>;
 }
 
+export function prepareCssAsset(command: "build" | "start", basePath: string, cssText: string): string {
+  if (command !== "build") return cssText;
+  return optimize(cssText, { file: `${basePath || "root"}.css`, minify: true }).code;
+}
+
 export class SsrBaseArtifactBuilder {
   #app: App;
   #command: "build" | "start";
@@ -143,13 +149,14 @@ export class SsrBaseArtifactBuilder {
 
   async #writeCssAsset(basePath: string, cssText: string) {
     const cssAssetName = basePath || "root";
-    const cssHash = Bun.hash(`${basePath}\n${cssText}`).toString(36);
+    const preparedCssText = await prepareCssAsset(this.#command, basePath, cssText);
+    const cssHash = Bun.hash(`${basePath}\n${preparedCssText}`).toString(36);
     const [cssRelPath, cssUrl] = [
       `styles/${cssAssetName}-${cssHash}.css`,
       `/_akan/styles/${cssAssetName}-${cssHash}.css`,
     ];
-    await Bun.write(path.join(this.#absArtifactDir, cssRelPath), cssText);
-    this.#app.verbose(`[base-artifact] wrote ${cssText.length} bytes of CSS for ${basePath} -> ${cssRelPath}`);
+    await Bun.write(path.join(this.#absArtifactDir, cssRelPath), preparedCssText);
+    this.#app.verbose(`[base-artifact] wrote ${preparedCssText.length} bytes of CSS for ${basePath} -> ${cssRelPath}`);
     return [basePath, { cssUrl, cssRelPath }] as const;
   }
 }

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";
@@ -34,3 +35,4 @@ export * from "./types";
 export * from "./ui";
 export * from "./uploadRelease";
 export * from "./useStdoutDimensions";
+export * from "./cloud";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.1.0-rc.9",
+  "version": "2.1.1-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -30,8 +30,9 @@
     "@langchain/core": "^1.1.47",
     "@langchain/deepseek": "^1.0.26",
     "@langchain/openai": "^1.4.6",
+    "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.1.0-rc.8",
+    "akanjs": "2.1.1-rc.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "^5.5.20",