@akanjs/devkit 2.1.1-rc.2 → 2.1.2-rc.0

package/akanConfig/akanConfig.ts

@@ -47,8 +47,18 @@ const DEFAULT_OPTIMIZE_IMPORTS = [
   "mui-core",
   "react-icons/*",
 ];
-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 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 DEFAULT_BACKEND_RUNTIME_PACKAGES = ["croner"] as const;
 const DATABASE_MODE_RUNTIME_PACKAGES = {
@@ -111,19 +121,31 @@ export class AkanAppConfig implements AppConfigResult {
     this.barrelImports = [
       ...DEFAULT_BARREL_IMPORTS,
       ...WORKSPACE_BARREL_FACETS.map((facet) => `@apps/${app.name}/${facet}`),
-      ...libs.flatMap((lib) => WORKSPACE_BARREL_FACETS.map((facet) => `@libs/${lib}/${facet}`)),
+      ...libs.flatMap((lib) =>
+        WORKSPACE_BARREL_FACETS.map((facet) => `@libs/${lib}/${facet}`),
+      ),
       ...(config?.barrelImports ?? []),
     ];
-    this.optimizeImports = [...new Set([...DEFAULT_OPTIMIZE_IMPORTS, ...(config?.optimizeImports ?? [])])];
-    this.images = mergeImageConfig(config?.images as Partial<AkanImageConfig> | undefined);
+    this.optimizeImports = [
+      ...new Set([
+        ...DEFAULT_OPTIMIZE_IMPORTS,
+        ...(config?.optimizeImports ?? []),
+      ]),
+    ];
+    this.images = mergeImageConfig(
+      config?.images as Partial<AkanImageConfig> | undefined,
+    );
     this.i18n = resolveAkanI18nConfig(config?.i18n);
     process.env.AKAN_PUBLIC_DEFAULT_LOCALE = this.i18n.defaultLocale;
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
-    this.publicEnv = (config?.publicEnv as string[] | undefined) ?? ([] as string[]);
+    this.publicEnv =
+      (config?.publicEnv as string[] | undefined) ?? ([] as string[]);
     this.mobile = this.#resolveMobileConfig(config.mobile);
     this.docker = this.#makeDockerContent(config?.docker ?? {});
   }
-  #resolveMobileConfig(mobile: DeepPartial<AkanMobileConfig> | undefined): AkanMobileConfig {
+  #resolveMobileConfig(
+    mobile: DeepPartial<AkanMobileConfig> | undefined,
+  ): AkanMobileConfig {
     const { targets: rawTargets, ...rawMobile } = mobile ?? {};
     const appName = rawMobile.appName ?? this.app.name;
     const appId = rawMobile.appId ?? `com.${this.app.name}.app`;
@@ -138,8 +160,11 @@ export class AkanAppConfig implements AppConfigResult {
     const targets = Object.fromEntries(
       targetEntries.map(([name, rawTarget]) => {
         const target = rawTarget as DeepPartial<AkanMobileTargetConfig>;
-        const fallbackBasePath = !rawTargets && this.basePaths.has(name) ? name : undefined;
-        const basePath = (target.basePath ?? fallbackBasePath)?.replace(/^\/+|\/+$/g, "") || undefined;
+        const fallbackBasePath =
+          !rawTargets && this.basePaths.has(name) ? name : undefined;
+        const basePath =
+          (target.basePath ?? fallbackBasePath)?.replace(/^\/+|\/+$/g, "") ||
+          undefined;
         if (basePath && !this.basePaths.has(basePath)) {
           throw new Error(
             `Mobile target '${name}' uses unknown basePath '${basePath}' in apps/${this.app.name}/akan.config.ts`,
@@ -180,8 +205,11 @@ export class AkanAppConfig implements AppConfigResult {
       plugins: rawMobile.plugins,
     } as AkanMobileConfig;
   }
-  #defaultMobileTargetName(rawTargets: DeepPartial<AkanMobileConfig>["targets"] | undefined) {
-    if (rawTargets && Object.keys(rawTargets).length > 0) return Object.keys(rawTargets)[0] as string;
+  #defaultMobileTargetName(
+    rawTargets: DeepPartial<AkanMobileConfig>["targets"] | undefined,
+  ) {
+    if (rawTargets && Object.keys(rawTargets).length > 0)
+      return Object.keys(rawTargets)[0] as string;
     return this.basePaths.has(this.app.name) ? this.app.name : "default";
   }
   #applyRoutes(routes: AkanRouteConfig[] = []) {
@@ -190,28 +218,38 @@ export class AkanAppConfig implements AppConfigResult {
         const basePath = route.basePath.replace(/^\/+|\/+$/g, "");
         this.basePaths.add(basePath);
         const domains = this.subRoutes.getOrInsert(basePath, new Set());
-        Object.keys(route.domains).forEach((branch) => void this.branches.add(branch));
+        Object.keys(route.domains).forEach(
+          (branch) => void this.branches.add(branch),
+        );
         Object.values(route.domains)
           .flat()
           .forEach((domain) => {
             if (domain) domains.add(domain.toLowerCase().replace(/:\d+$/, ""));
           });
       } else {
-        Object.keys(route.domains).forEach((branch) => void this.branches.add(branch));
+        Object.keys(route.domains).forEach(
+          (branch) => void this.branches.add(branch),
+        );
         Object.values(route.domains)
           .flat()
           .forEach((domain) => {
-            if (domain) this.domains.add(domain.toLowerCase().replace(/:\d+$/, ""));
+            if (domain)
+              this.domains.add(domain.toLowerCase().replace(/:\d+$/, ""));
           });
       }
     }
     const appName = this.app.name.toLowerCase();
     const serveDomain = this.baseDevEnv.serveDomain.toLowerCase();
     if (this.subRoutes.size === 0)
-      this.branches.forEach((branch) => void this.domains.add(`${appName}-${branch}.${serveDomain}`));
+      this.branches.forEach(
+        (branch) =>
+          void this.domains.add(`${appName}-${branch}.${serveDomain}`),
+      );
     else
       Array.from(this.subRoutes.entries()).forEach(([basePath, domains]) => {
-        this.branches.forEach((domain) => void domains.add(`${basePath}-${domain}.${serveDomain}`));
+        this.branches.forEach(
+          (domain) => void domains.add(`${basePath}-${domain}.${serveDomain}`),
+        );
       });
   }
   #getDockerRunScripts(runs: (string | { [key in Arch]?: string })[]) {
@@ -227,12 +265,25 @@ export class AkanAppConfig implements AppConfigResult {
           .join("\n");
     });
   }
-  #getDockerImageScript(image: string | { [key in Arch]?: string }, defaultImage: string) {
+  #getDockerImageScript(
+    image: string | { [key in Arch]?: string },
+    defaultImage: string,
+  ) {
     if (typeof image === "string") return `FROM ${image}`;
-    else return archs.map((arch) => `FROM ${image[arch] ?? defaultImage} AS ${arch}`).join("\n");
+    else
+      return archs
+        .map((arch) => `FROM ${image[arch] ?? defaultImage} AS ${arch}`)
+        .join("\n");
   }
   #makeDockerContent(docker: DeepPartial<DockerConfig>): DockerConfig {
-    if (docker.content) return { content: docker.content, image: {}, preRuns: [], postRuns: [], command: [] };
+    if (docker.content)
+      return {
+        content: docker.content,
+        image: {},
+        preRuns: [],
+        postRuns: [],
+        command: [],
+      };
     const preRunScripts = this.#getDockerRunScripts(docker.preRuns ?? []);
     const postRunScripts = this.#getDockerRunScripts(docker.postRuns ?? []);
 
@@ -264,12 +315,20 @@ ENV AKAN_PUBLIC_LOCALES=${this.i18n.locales.join(",")}
 ENV AKAN_PUBLIC_OPERATION_MODE=cloud
 
 CMD [${command.map((c) => `"${c}"`).join(",")}]`;
-    return { content, image: imageScript, preRuns: docker.preRuns ?? [], postRuns: docker.postRuns ?? [], command };
+    return {
+      content,
+      image: imageScript,
+      preRuns: docker.preRuns ?? [],
+      postRuns: docker.postRuns ?? [],
+      command,
+    };
   }
   static async from(app: App) {
     const [configImp, baseDevEnv, libs, rootPackageJson] = await Promise.all([
       import(`${app.cwdPath}/akan.config.ts`).then((mod) => mod.default),
-      WorkspaceExecutor.getBaseDevEnv(path.join(app.workspace.workspaceRoot, ".env")),
+      WorkspaceExecutor.getBaseDevEnv(
+        path.join(app.workspace.workspaceRoot, ".env"),
+      ),
       app.workspace.getLibs(),
       app.workspace.getPackageJson(),
     ]);
@@ -277,11 +336,16 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     return new AkanAppConfig(app, libs, rootPackageJson, config, baseDevEnv);
   }
   #resolveProductionDependencyVersion(lib: string) {
-    const rootVersion = this.rootPackageJson.dependencies?.[lib] ?? this.rootPackageJson.devDependencies?.[lib];
+    const rootVersion =
+      this.rootPackageJson.dependencies?.[lib] ??
+      this.rootPackageJson.devDependencies?.[lib];
     if (rootVersion) return rootVersion;
     const akanPackageJson = getAkanPackageJson();
     if (AKAN_RUNTIME_PACKAGES.has(lib))
-      return akanPackageJson.dependencies?.[lib] ?? akanPackageJson.peerDependencies?.[lib];
+      return (
+        akanPackageJson.dependencies?.[lib] ??
+        akanPackageJson.peerDependencies?.[lib]
+      );
   }
   #getProductionRuntimePackages() {
     return [
@@ -289,9 +353,30 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
       ...SSR_RUNTIME_PACKAGES,
       ...NATIVE_RUNTIME_PACKAGES,
       ...DEFAULT_BACKEND_RUNTIME_PACKAGES,
-      ...DATABASE_MODE_RUNTIME_PACKAGES[this.defaultDatabaseMode],
+      ...this.getDatabaseModeRuntimePackages(),
     ];
   }
+  getDatabaseModeRuntimePackages(
+    databaseMode: DatabaseMode = this.defaultDatabaseMode,
+  ) {
+    return [...DATABASE_MODE_RUNTIME_PACKAGES[databaseMode]];
+  }
+  getMissingDatabaseModeDependencySpecs(
+    databaseMode: DatabaseMode = this.defaultDatabaseMode,
+  ) {
+    const rootDependencies = {
+      ...this.rootPackageJson.dependencies,
+      ...this.rootPackageJson.devDependencies,
+    };
+    return this.getDatabaseModeRuntimePackages(databaseMode)
+      .filter((lib) => !rootDependencies[lib])
+      .map((lib) => {
+        const version = this.#resolveProductionDependencyVersion(lib);
+        if (!version)
+          throw new Error(`Dependency ${lib} not found in package.json`);
+        return `${lib}@${version}`;
+      });
+  }
   getProductionPackageJson(data: Partial<PackageJson> = {}): PackageJson {
     return {
       name: this.app.name,
@@ -301,7 +386,8 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
       dependencies: Object.fromEntries(
         [...new Set(this.#getProductionRuntimePackages())].map((lib) => {
           const version = this.#resolveProductionDependencyVersion(lib);
-          if (!version) throw new Error(`Dependency ${lib} not found in package.json`);
+          if (!version)
+            throw new Error(`Dependency ${lib} not found in package.json`);
           return [lib, version];
         }),
       ),
@@ -327,17 +413,26 @@ function getAkanPackageJson() {
   }
   for (const packageJsonPath of packageJsonPaths) {
     try {
-      akanPackageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8")) as PackageJson;
+      akanPackageJson = JSON.parse(
+        fs.readFileSync(packageJsonPath, "utf8"),
+      ) as PackageJson;
       return akanPackageJson;
     } catch {
       // Try the next known layout: source package first, bundled CLI package second.
     }
   }
-  akanPackageJson = { name: "akanjs", version: "0.0.0", description: "akanjs", dependencies: {} };
+  akanPackageJson = {
+    name: "akanjs",
+    version: "0.0.0",
+    description: "akanjs",
+    dependencies: {},
+  };
   return akanPackageJson;
 }
 
-function mergeImageConfig(config: Partial<AkanImageConfig> = {}): AkanImageConfig {
+function mergeImageConfig(
+  config: Partial<AkanImageConfig> = {},
+): AkanImageConfig {
   return {
     ...DEFAULT_AKAN_IMAGE_CONFIG,
     ...config,
@@ -345,8 +440,10 @@ function mergeImageConfig(config: Partial<AkanImageConfig> = {}): AkanImageConfi
     imageSizes: config.imageSizes ?? DEFAULT_AKAN_IMAGE_CONFIG.imageSizes,
     formats: config.formats ?? DEFAULT_AKAN_IMAGE_CONFIG.formats,
     qualities: config.qualities ?? DEFAULT_AKAN_IMAGE_CONFIG.qualities,
-    remotePatterns: config.remotePatterns ?? DEFAULT_AKAN_IMAGE_CONFIG.remotePatterns,
-    localPatterns: config.localPatterns ?? DEFAULT_AKAN_IMAGE_CONFIG.localPatterns,
+    remotePatterns:
+      config.remotePatterns ?? DEFAULT_AKAN_IMAGE_CONFIG.remotePatterns,
+    localPatterns:
+      config.localPatterns ?? DEFAULT_AKAN_IMAGE_CONFIG.localPatterns,
   };
 }
 
@@ -358,7 +455,9 @@ export class AkanLibConfig implements LibConfigResult {
     this.externalLibs = config?.externalLibs ?? [];
   }
   static async from(lib: Lib) {
-    const [configImp] = await Promise.all([import(`${lib.cwdPath}/akan.config.ts`).then((mod) => mod.default)]);
+    const [configImp] = await Promise.all([
+      import(`${lib.cwdPath}/akan.config.ts`).then((mod) => mod.default),
+    ]);
     const config = typeof configImp === "function" ? configImp(lib) : configImp;
     return new AkanLibConfig(lib, config);
   }

package/artifact/implicitRootLayout.test.ts

@@ -46,6 +46,8 @@ describe("resolveSsrPageEntries", () => {
     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("export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;");
+    expect(generatedSource).toContain("export const Error = userLayout.Error ?? inheritedLayout.Error;");
     expect(generatedSource).toContain(
       "<UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>",
     );

package/artifact/implicitRootLayout.ts

@@ -135,8 +135,8 @@ async function writeGeneratedRootLayoutFile(opts: {
     ? `import UserLayout, * as userLayout from ${JSON.stringify(sourceSpecifier)};\n`
     : "const UserLayout = ({ children }) => children;\nconst userLayout = {};\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`;
+    ? `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 const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;\nexport const Error = userLayout.Error ?? inheritedLayout.Error;\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 const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;\nexport const Error = userLayout.Error ?? inheritedLayout.Error;\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;
 }

package/cloud/cloudApi.ts

@@ -1,9 +1,5 @@
-import {
-  type AccessToken,
-  type AccessTokenDto,
-  akanCloudHost,
-  type HostConfig,
-} from "./constants";
+import type { Workspace } from "../commandDecorators";
+import { type AccessToken, type AccessTokenDto, akanCloudHost, type HostConfig } from "./constants";
 import { GlobalConfig } from "./globalConfig";
 
 class HttpClient {
@@ -13,10 +9,7 @@ class HttpClient {
     this.baseUrl = baseUrl;
     this.headers = headers;
   }
-  async get<T>(
-    url: string,
-    { headers }: { headers?: Record<string, string> } = {},
-  ): Promise<T> {
+  async get<T>(url: string, { headers }: { headers?: Record<string, string> } = {}): Promise<T> {
     const response = await fetch(`${this.baseUrl}${url}`, {
       headers: {
         "Content-Type": "application/json",
@@ -26,25 +19,14 @@ class HttpClient {
     });
     return response.json();
   }
-  async getFile(
-    url: string,
-    localPath: string,
-    headers?: Record<string, string>,
-  ): Promise<void> {
+  async getFile(url: string, localPath: string, headers?: Record<string, string>): Promise<void> {
     const response = await fetch(`${this.baseUrl}${url}`, {
       headers: { ...this.headers, ...headers },
     });
-    if (!response.ok)
-      throw new Error(
-        `Failed to download file: ${response.status} ${response.statusText}`,
-      );
+    if (!response.ok) throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
     await Bun.write(localPath, response);
   }
-  async post<T>(
-    url: string,
-    data: unknown,
-    { headers }: { headers?: Record<string, string> } = {},
-  ): Promise<T> {
+  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",
@@ -64,12 +46,14 @@ class HttpClient {
 export class CloudApi {
   readonly #api: HttpClient;
   #accessToken: AccessToken | null = null;
+  #workspace: Workspace;
 
-  static async fromHost(host?: string) {
+  static async fromHost(workspace: Workspace, host?: string) {
     const hostConfig = await GlobalConfig.getHostConfig(host);
-    return new CloudApi(hostConfig);
+    return new CloudApi(workspace, hostConfig);
   }
-  constructor(hostConfig: HostConfig) {
+  constructor(workspace: Workspace, hostConfig: HostConfig) {
+    this.#workspace = workspace;
     const host = akanCloudHost;
     this.#api = new HttpClient(`${host}/api`);
     this.#accessToken = hostConfig.auth?.accessToken ?? null;
@@ -83,25 +67,20 @@ export class CloudApi {
     const formData = new FormData();
     formData.append("devProjectId", devProjectId);
     formData.append("file", file);
-    const data = await this.#api.post<boolean>(
-      `/uploadEnv/${devProjectId}`,
-      formData,
-    );
+    const data = await this.#api.post<boolean>(`/uploadEnv/${devProjectId}`, formData);
     return data;
   }
-  async downloadEnv(devProjectId: string, localPath: string): Promise<void> {
+  async downloadEnv(devProjectId: string): Promise<void> {
+    const localPath = `${this.#workspace.workspaceRoot}/local/env.tar`;
     await this.#api.getFile(`/downloadEnv/${devProjectId}`, localPath);
   }
   async getRemoteAuthToken(remoteId: string): Promise<AccessToken | null> {
     try {
       if (this.#accessToken) {
-        if (GlobalConfig.needRefreshToken(this.#accessToken))
-          return await this.refreshAuthToken();
-        else return await this.refreshAuthToken();
+        if (GlobalConfig.needRefreshToken(this.#accessToken)) return await this.#refreshAuthToken();
+        else return await this.#refreshAuthToken();
       }
-      const accessToken = await this.#api.get<AccessTokenDto>(
-        `/getRemoteAuthToken/${remoteId}`,
-      );
+      const accessToken = await this.#api.get<AccessTokenDto>(`/getRemoteAuthToken/${remoteId}`);
       this.#accessToken = GlobalConfig.toAccessToken(accessToken);
       this.#api.setHeaders({
         Authorization: `Bearer ${this.#accessToken.jwt}`,
@@ -111,22 +90,20 @@ export class CloudApi {
       return null;
     }
   }
-  async refreshAuthToken(): Promise<AccessToken> {
-    const response = await this.#api.post<AccessTokenDto>(
-      `/refreshRemoteAuthToken`,
-      {
-        refreshToken: this.#accessToken?.refreshToken,
-      },
-    );
+  async #refreshAuthToken(): Promise<AccessToken> {
+    const refreshToken = this.#accessToken?.refreshToken;
+    if (!refreshToken) throw new Error("No refresh token");
+    return await this.refreshAuthToken(refreshToken);
+  }
+  async refreshAuthToken(refreshToken: string): Promise<AccessToken> {
+    const response = await this.#api.post<AccessTokenDto>(`/refreshRemoteAuthToken`, { refreshToken });
     this.#accessToken = GlobalConfig.toAccessToken(response);
     this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
     return this.#accessToken;
   }
   async getRemoteSelf(): Promise<{ id: string; nickname: string } | null> {
     try {
-      const data = await this.#api.get<{ id: string; nickname: string }>(
-        `/getRemoteSelf`,
-      );
+      const data = await this.#api.get<{ id: string; nickname: string }>(`/getRemoteSelf`);
       return data;
     } catch {
       return null;

package/executors.test.ts

@@ -251,6 +251,53 @@ describe("Workspace and app executor environment contracts", () => {
     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);
   });
+
+  test("assigns start command ports from sorted app order", 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());
+    for (const appName of ["minimal", "akan"]) {
+      await mkdir(path.join(root, `apps/${appName}`), { recursive: true });
+      await writeFile(
+        path.join(root, `apps/${appName}/akan.config.ts`),
+        [
+          "export default {",
+          `  routes: [{ basePath: "${appName}", domains: { debug: ["${appName}.local:8282"] } }],`,
+          "};",
+          "",
+        ].join("\n"),
+      );
+    }
+
+    const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+    const akan = AppExecutor.from(workspace, "akan");
+    const minimal = AppExecutor.from(workspace, "minimal");
+
+    const akanStart = await akan.prepareCommand("start");
+    expect(akanStart.env.PORT).toBe("8282");
+    expect(akanStart.env.AKAN_PUBLIC_CLIENT_PORT).toBe("8282");
+    expect(akanStart.env.AKAN_PUBLIC_SERVER_PORT).toBe("8282");
+
+    const minimalStart = await minimal.prepareCommand("start");
+    expect(minimalStart.env.PORT).toBe("8283");
+    expect(minimalStart.env.AKAN_PUBLIC_CLIENT_PORT).toBe("8283");
+    expect(minimalStart.env.AKAN_PUBLIC_SERVER_PORT).toBe("8283");
+
+    process.env.PORT_OFFSET = "3";
+
+    const offsetAkanStart = await akan.prepareCommand("start");
+    expect(offsetAkanStart.env.PORT).toBe("8285");
+    expect(offsetAkanStart.env.AKAN_PUBLIC_CLIENT_PORT).toBe("8285");
+    expect(offsetAkanStart.env.AKAN_PUBLIC_SERVER_PORT).toBe("8285");
+
+    const offsetMinimalStart = await minimal.prepareCommand("start");
+    expect(offsetMinimalStart.env.PORT).toBe("8286");
+    expect(offsetMinimalStart.env.AKAN_PUBLIC_CLIENT_PORT).toBe("8286");
+    expect(offsetMinimalStart.env.AKAN_PUBLIC_SERVER_PORT).toBe("8286");
+  });
 });
 
 describe("PkgExecutor package generation", () => {

package/executors.ts

@@ -163,8 +163,10 @@ const ROOT_LAYOUT_EXPORTS = new Set([
   "layoutStyle",
   "gaTrackingId",
   "Loading",
+  "NotFound",
+  "Error",
 ]);
-const LAYOUT_ROUTE_EXPORTS = new Set(["default", "head", "generateHead", "Loading"]);
+const LAYOUT_ROUTE_EXPORTS = new Set(["default", "head", "generateHead", "Loading", "NotFound", "Error"]);
 
 function validateRouteSourceExports(
   source: string,
@@ -739,6 +741,51 @@ export class Executor {
     const message = typeChecker.formatDiagnostics(fileDiagnostics);
     return { fileDiagnostics, fileErrors, fileWarnings, message };
   }
+  async typeCheckAsync(filePath: string) {
+    const path = this.getPath(filePath);
+    const entry = await this.#resolveTypecheckWorkerEntry();
+    const proc = Bun.spawn([process.execPath, entry], {
+      cwd: this.cwdPath,
+      env: {
+        ...process.env,
+        AKAN_TYPECHECK_CWD: this.cwdPath,
+        AKAN_TYPECHECK_FILE: path,
+      },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (exitCode !== 0) throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+
+    const result = JSON.parse(stdout) as {
+      fileDiagnosticsCount: number;
+      fileErrorsCount: number;
+      fileWarningsCount: number;
+      message: string;
+    };
+    return {
+      fileDiagnostics: Array.from({ length: result.fileDiagnosticsCount }),
+      fileErrors: Array.from({ length: result.fileErrorsCount }),
+      fileWarnings: Array.from({ length: result.fileWarningsCount }),
+      message: result.message,
+    };
+  }
+  async #resolveTypecheckWorkerEntry() {
+    const dirname = getDirname(import.meta.url);
+    const candidates = [
+      path.join(process.cwd(), "pkgs/@akanjs/devkit/typecheck/typecheck.proc.ts"),
+      path.join(process.cwd(), "node_modules/@akanjs/devkit/typecheck/typecheck.proc.ts"),
+      path.join(dirname, "typecheck/typecheck.proc.ts"),
+      path.join(dirname, "typecheck.proc.js"),
+      path.join(dirname, "typecheck.proc.ts"),
+    ];
+    for (const candidate of candidates) if (await Bun.file(candidate).exists()) return candidate;
+    throw new Error(`[devkit] typecheck worker entry not found; looked in: ${candidates.join(", ")}`);
+  }
   getLinter() {
     this.linter ??= new Linter(this.cwdPath);
     return this.linter;
@@ -811,7 +858,15 @@ export class WorkspaceExecutor extends Executor {
       | "local"
       | undefined;
     if (!env) throw new Error("AKAN_PUBLIC_ENV is not set");
-    return { ...(appName ? { appName } : {}), workspaceRoot, repoName, serveDomain, env, portOffset, workspaceId };
+    return {
+      ...(appName ? { appName } : {}),
+      workspaceRoot,
+      repoName,
+      serveDomain,
+      env,
+      portOffset,
+      workspaceId,
+    };
   }
   getWorkspaceId<AllowEmpty extends boolean = false>({
     allowEmpty,
@@ -1259,6 +1314,13 @@ export class AppExecutor extends SysExecutor {
   getEnv() {
     return WorkspaceExecutor.getBaseDevEnv().env;
   }
+  async getDevPort() {
+    const basePort = 8282;
+    const appNames = (await this.workspace.getApps()).sort((a, b) => a.localeCompare(b));
+    const appIndex = Math.max(appNames.indexOf(this.name), 0);
+    const portOffset = WorkspaceExecutor.getBaseDevEnv().portOffset;
+    return basePort + appIndex + portOffset;
+  }
   getCommandEnv(env: Record<string, string> = {}): Record<string, string> {
     const basePort = 8282;
     const portOffset = WorkspaceExecutor.getBaseDevEnv().portOffset;
@@ -1290,7 +1352,12 @@ export class AppExecutor extends SysExecutor {
         this.cp("public", `${this.dist.cwdPath}/public`),
       ]);
     } else await this.removeDir(".akan");
-    const env = this.getCommandEnv({ AKAN_COMMAND_TYPE: type, ...routeEnv });
+    const devPort = type === "start" ? (await this.getDevPort()).toString() : undefined;
+    const env = this.getCommandEnv({
+      AKAN_COMMAND_TYPE: type,
+      ...routeEnv,
+      ...(devPort ? { PORT: devPort, AKAN_PUBLIC_CLIENT_PORT: devPort, AKAN_PUBLIC_SERVER_PORT: devPort } : {}),
+    });
     return { env };
   }
   #publicEnv: Record<string, string> | null = null;

package/index.ts

@@ -9,6 +9,7 @@ export * from "./artifact";
 export * from "./builder";
 export * from "./capacitorApp";
 export * from "./cloud";
+export * from "./cloud";
 export * from "./commandDecorators";
 export * from "./createTunnel";
 export * from "./dependencyScanner";
@@ -34,4 +35,3 @@ export * from "./types";
 export * from "./ui";
 export * from "./uploadRelease";
 export * from "./useStdoutDimensions";
-export * from "./cloud";