akanjs 2.0.5 → 2.0.7

package/cli/library/library.runner.ts

@@ -1,5 +1,5 @@
 import { type Lib, LibExecutor, runner, type Workspace } from "akanjs/devkit";
-import { compareVersions } from "compare-versions";
+import { compareSemver } from "../semver";
 
 export class LibraryRunner extends runner("library") {
   async createLibrary(libName: string, workspace: Workspace) {
@@ -44,7 +44,7 @@ export class LibraryRunner extends runner("library") {
       Object.keys({ ...libDependencies, ...rootDependencies }).map((dep) => {
         const libVersion = libDependencies[dep] ?? "0.0.0";
         const rootVersion = rootDependencies[dep] ?? "0.0.0";
-        const newerVersion = compareVersions(rootVersion, libVersion) > 0 ? rootVersion : libVersion;
+        const newerVersion = compareSemver(rootVersion, libVersion) > 0 ? rootVersion : libVersion;
         return [dep, newerVersion];
       }),
     );

package/cli/module/module.runner.ts

@@ -1,6 +1,6 @@
 import { capitalize } from "akanjs/common";
 import { type Module, runner, type Workspace } from "akanjs/devkit";
-import pluralize from "pluralize";
+import { pluralizeName } from "../pluralizeName";
 
 export class ModuleRunner extends runner("module") {
   async createModule(
@@ -30,7 +30,7 @@ export class ModuleRunner extends runner("module") {
   }
 
   async createModuleTemplate(module: Module) {
-    const names = pluralize(module.name);
+    const names = pluralizeName(module.name);
     await module.applyTemplate({
       basePath: `.`,
       template: "module",

package/cli/npmRegistry.ts

@@ -0,0 +1,13 @@
+interface NpmPackageMetadata {
+  "dist-tags"?: Record<string, string>;
+}
+
+export async function getLatestPackageVersion(packageName: string, tag = "latest"): Promise<string> {
+  const url = `https://registry.npmjs.org/${encodeURIComponent(packageName).replace(/^%40/, "@")}`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Failed to fetch ${packageName} metadata from npm registry`);
+  const metadata = (await res.json()) as NpmPackageMetadata;
+  const version = metadata["dist-tags"]?.[tag];
+  if (!version) throw new Error(`No npm dist-tag "${tag}" found for ${packageName}`);
+  return version;
+}

package/cli/openBrowser.ts

@@ -0,0 +1,15 @@
+import { spawn } from "node:child_process";
+
+export function openBrowser(url: string): Promise<void> {
+  const command =
+    process.platform === "darwin"
+      ? ["open", url]
+      : process.platform === "win32"
+        ? ["cmd", "/c", "start", "", url]
+        : ["xdg-open", url];
+  const child = spawn(command[0], command.slice(1), { detached: true, stdio: "ignore" });
+  child.on("error", () => {
+  });
+  child.unref();
+  return Promise.resolve();
+}

package/cli/pluralizeName.ts

@@ -0,0 +1,5 @@
+export function pluralizeName(name: string): string {
+  if (/[^aeiou]y$/i.test(name)) return `${name.slice(0, -1)}ies`;
+  if (/(s|x|z|ch|sh)$/i.test(name)) return `${name}es`;
+  return `${name}s`;
+}

package/cli/scalar/scalar.prompt.ts

@@ -1,6 +1,6 @@
 import { input } from "@inquirer/prompts";
 import { type FileContent, Prompter, type Sys } from "akanjs/devkit";
-import pluralize from "pluralize";
+import { pluralizeName } from "../pluralizeName";
 
 export class ScalarPrompt extends Prompter {
   constructor(
@@ -20,7 +20,7 @@ export class ScalarPrompt extends Prompter {
     await this.sys.applyTemplate({
       basePath: "./lib/__scalar",
       template: "__scalar",
-      dict: { model: this.name, models: pluralize(this.name), sysName: this.sys.name },
+      dict: { model: this.name, models: pluralizeName(this.name), sysName: this.sys.name },
     });
     const boilerplate = await this.sys.readFile(`lib/__scalar/${this.name}/${this.name}.constant.ts`);
     return await this.#requestConstant({

package/cli/scalar/scalar.runner.ts

@@ -1,5 +1,5 @@
 import { AiSession, runner, type Sys } from "akanjs/devkit";
-import pluralize from "pluralize";
+import { pluralizeName } from "../pluralizeName";
 
 import { ScalarPrompt } from "./scalar.prompt";
 
@@ -8,7 +8,7 @@ export class ScalarRunner extends runner("scalar") {
     await sys.applyTemplate({
       basePath: "./lib/__scalar",
       template: "__scalar",
-      dict: { model: scalarName, models: pluralize(scalarName), sysName: sys.name },
+      dict: { model: scalarName, models: pluralizeName(scalarName), sysName: sys.name },
       overwrite: false,
     });
   }

package/cli/semver.ts

@@ -0,0 +1,18 @@
+function parseVersion(version: string): number[] {
+  return version
+    .replace(/^[^\d]*/, "")
+    .split(/[.-]/)
+    .map((part) => Number.parseInt(part, 10))
+    .map((part) => (Number.isFinite(part) ? part : 0));
+}
+
+export function compareSemver(a: string, b: string): number {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}

package/cli/templates/lib/sig.ts

@@ -50,8 +50,8 @@ ${[...scanInfo.service.entries()]
   )
   .join("\n")}
 
-${databaseModules.map((module) => `export const ${module} = SignalRegistry.registerDatabase(${module}Sig.${capitalize(module)}Internal, ${module}Sig.${capitalize(module)}Endpoint, ${module}Sig.${capitalize(module)}Slice, ${capitalize(module)});`).join("\n")}
-${serviceModules.map((module) => `export const ${module} = SignalRegistry.registerService(${module}Sig.${capitalize(module)}Internal, ${module}Sig.${capitalize(module)}Endpoint, ${capitalize(module)});`).join("\n")}
+${databaseModules.map((module) => `export const ${module} = SignalRegistry.registerDatabase("${module}" as const, ${module}Sig.${capitalize(module)}Internal, ${module}Sig.${capitalize(module)}Endpoint, ${module}Sig.${capitalize(module)}Slice, ${capitalize(module)});`).join("\n")}
+${serviceModules.map((module) => `export const ${module} = SignalRegistry.registerService("${module}" as const, ${module}Sig.${capitalize(module)}Internal, ${module}Sig.${capitalize(module)}Endpoint, ${capitalize(module)});`).join("\n")}
 
 export const fetch = FetchClient.from(${[...(libs.length === 0 ? ["base"] : libs), ...databaseModules, ...serviceModules].join(", ")});
 

package/cli/workspace/workspace.runner.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
-import { FileSys, type Exec, type PackageJson, runner, type Workspace, WorkspaceExecutor } from "akanjs/devkit";
-import latestVersion from "latest-version";
+import { type Exec, FileSys, type PackageJson, runner, type Workspace, WorkspaceExecutor } from "akanjs/devkit";
+import { getLatestPackageVersion } from "../npmRegistry";
 
 export class WorkspaceRunner extends runner("workspace") {
   async createWorkspace(
@@ -13,7 +13,7 @@ export class WorkspaceRunner extends runner("workspace") {
 
     const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot, repoName });
     const templateSpinner = workspace.spinning(`Creating workspace template files in ${dirname}/${repoName}...`);
-    const latestTypesBunVersion = await latestVersion("@types/bun");
+    const latestTypesBunVersion = await getLatestPackageVersion("@types/bun");
     await workspace.applyTemplate({
       basePath: ".",
       template: "workspaceRoot",

package/client/cookie.ts

@@ -1,12 +1,16 @@
 import { getEnv } from "akanjs/base";
-import { Logger } from "akanjs/common";
+import { decodeJwtPayload, Logger } from "akanjs/common";
 import type { Account } from "akanjs/fetch";
 import { requestStorage } from "akanjs/fetch";
-import Cookies from "js-cookie";
-import { jwtDecode } from "jwt-decode";
 import { storage } from "./storage";
 import { fetch } from "./useClient";
 
+interface CookieOptions {
+  path?: string;
+  sameSite?: "strict" | "lax" | "none";
+  secure?: boolean;
+}
+
 function parseCookieHeader(cookieHeader: string): Map<string, { name: string; value: string }> {
   const entries = cookieHeader
     .split(";")
@@ -30,22 +34,13 @@ export const cookies = (): Map<string, { name: string; value: string }> => {
     if (!req) return new Map();
     return parseCookieHeader(req.headers.get("cookie") ?? "");
   }
-  const cookie = Cookies.get();
-  return new Map(
-    Object.entries(cookie).map(([key, value]) => [
-      key,
-      {
-        name: key,
-        value: typeof value === "string" && value.startsWith("j:") ? (JSON.parse(value.slice(2)) as string) : value,
-      },
-    ]),
-  );
+  return parseCookieHeader(document.cookie);
 };
 
 export const setCookie = (
   key: string,
   value: string,
-  options: Cookies.CookieAttributes = { path: "/", sameSite: "none", secure: true },
+  options: CookieOptions = { path: "/", sameSite: "none", secure: true },
 ) => {
   if (getEnv().side === "server") return;
   else
@@ -88,7 +83,7 @@ export const getAccount = <AddData = unknown>(): Account<AddData> => {
   const jwt = getCookie("jwt") ?? getHeader("jwt");
   const defaultAccount = { appName: getEnv().appName, environment: getEnv().environment } as Account<AddData>;
   if (!jwt) return defaultAccount;
-  const account: Account<AddData> = jwtDecode<Account<AddData>>(jwt);
+  const account = decodeJwtPayload<Account<AddData>>(jwt);
   if (account.appName !== getEnv().appName || account.environment !== getEnv().environment) return defaultAccount;
   return account;
 };

package/common/index.ts

@@ -11,6 +11,7 @@ export { isEmail } from "./isEmail";
 export { isPhoneNumber } from "./isPhoneNumber";
 export { isQueryEqual } from "./isQueryEqual";
 export { isValidDate } from "./isValidDate";
+export { decodeJwtPayload } from "./jwtDecode";
 export { Logger, type LoggerSink, type LoggerSinkEntry, type LogLevel } from "./Logger";
 export {
   type AkanI18nConfig,

package/common/jwtDecode.ts

@@ -0,0 +1,17 @@
+function decodeBase64Url(input: string): string {
+  const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+  if (typeof atob === "function") return atob(padded);
+  return Buffer.from(padded, "base64").toString("binary");
+}
+
+/** Decodes a JWT payload without validating its signature. */
+export function decodeJwtPayload<T = unknown>(jwt: string): T {
+  const [, payload] = jwt.split(".");
+  if (!payload) throw new Error("Invalid JWT payload");
+  const binary = decodeBase64Url(payload);
+  const json = decodeURIComponent(
+    [...binary].map((char) => `%${char.charCodeAt(0).toString(16).padStart(2, "0")}`).join(""),
+  );
+  return JSON.parse(json) as T;
+}

package/constant/serialize.ts

@@ -53,7 +53,7 @@ const serializeInput = <Input = unknown>(
     return Object.fromEntries(
       Object.entries(modelRef[FIELD_META]).map(([key, field]) => [
         key,
-        field.isClass && !field.isScalar
+        serializeType === "input" && field.isClass && !field.isScalar
           ? serialize(ID, field.arrDepth, getRelationId((value as Record<string, unknown>)?.[key]), serializeType, {
               nullable: field.nullable,
               key,

package/devkit/akanApp/akanApp.host.ts

@@ -9,6 +9,8 @@ import { IncrementalBuilderHost } from "../incrementalBuilder";
 const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route"]);
 const BACKEND_RESTART_DEBOUNCE_MS = 120;
 const BACKEND_GRACEFUL_TIMEOUT_MS = 3000;
+const BACKEND_RECOVERY_BASE_DELAY_MS = 1_000;
+const BACKEND_RECOVERY_MAX_DELAY_MS = 30_000;
 const BUILDER_READY_TIMEOUT_MS = 15000;
 const BUILDER_START_MAX_ATTEMPTS = 3;
 const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
@@ -132,6 +134,8 @@ export class AkanAppHost {
   #backendReady = false;
   #plannedBackendStops = new WeakSet<Bun.Subprocess<"ignore", "inherit", "inherit">>();
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
+  #backendRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
+  #backendRecoveryAttempts = 0;
   #restartFiles = new Set<string>();
   #latestPagesUpdated: Extract<BuilderMessage, { type: "pages-updated" }> | null = null;
   #latestCssUpdated: Extract<BuilderMessage, { type: "css-updated" }> | null = null;
@@ -162,6 +166,10 @@ export class AkanAppHost {
       clearTimeout(this.#restartTimer);
       this.#restartTimer = null;
     }
+    if (this.#backendRecoveryTimer) {
+      clearTimeout(this.#backendRecoveryTimer);
+      this.#backendRecoveryTimer = null;
+    }
     await this.#stopBackend();
     this.#stopBuilder();
     return this;
@@ -185,6 +193,7 @@ export class AkanAppHost {
         if (!msg || typeof msg !== "object") return;
         if (msg.type === "backend-ready") {
           this.#backendReady = true;
+          this.#backendRecoveryAttempts = 0;
           this.logger.verbose(`backend ready pid=${msg.pid}`);
           this.#replayBuilderState();
           return;
@@ -199,7 +208,7 @@ export class AkanAppHost {
           this.#plannedBackendStops.delete(backend);
           return;
         }
-        this.#stopBuilder();
+        this.#scheduleBackendRecovery("backend-exit");
       },
     });
     this.#backend = backend;
@@ -245,6 +254,10 @@ export class AkanAppHost {
   }
   #scheduleBackendRestart(files: string[]) {
     for (const file of files) this.#restartFiles.add(file);
+    if (this.#backendRecoveryTimer) {
+      clearTimeout(this.#backendRecoveryTimer);
+      this.#backendRecoveryTimer = null;
+    }
     if (this.#restartTimer) clearTimeout(this.#restartTimer);
     this.#restartTimer = setTimeout(() => {
       this.#restartTimer = null;
@@ -255,9 +268,26 @@ export class AkanAppHost {
   }
   async #restartBackend(files: string[]) {
     this.logger.verbose(`[backend-reload] restarting backend for ${files.length} file(s)`);
+    this.#backendRecoveryAttempts = 0;
     await Promise.all([this.#stopBackend(), this.#backendGraph.refresh()]);
     this.#startBackend();
   }
+  #scheduleBackendRecovery(reason: string) {
+    if (this.#backendRecoveryTimer || this.#backend) return;
+    const attempt = this.#backendRecoveryAttempts;
+    const delay = Math.min(BACKEND_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BACKEND_RECOVERY_MAX_DELAY_MS);
+    this.#backendRecoveryAttempts = attempt + 1;
+    this.logger.warn(
+      `[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecoveryAttempts})`,
+    );
+    this.#backendRecoveryTimer = setTimeout(() => {
+      this.#backendRecoveryTimer = null;
+      if (this.#backend) return;
+      void this.#backendGraph.refresh().finally(() => {
+        if (!this.#backend) this.#startBackend();
+      });
+    }, delay);
+  }
   #enqueueBuilderMessage(message: BuilderMessage) {
     this.#builderMessageQueue = this.#builderMessageQueue
       .then(() => this.#handleBuilderMessage(message))
@@ -319,7 +349,6 @@ export class AkanAppHost {
     return new Promise<void>((resolve, reject) => {
       if (!this.#builder) throw new Error("Builder Not Found");
       let settled = false;
-      let ready = false;
       const settle = (fn: () => void) => {
         if (settled) return;
         settled = true;
@@ -331,22 +360,30 @@ export class AkanAppHost {
       }, BUILDER_READY_TIMEOUT_MS);
       this.#builder.start({
         onExit: () => {
-          if (settled && ready) {
-            void this.#stopBackend();
-            return;
-          }
           settle(() => reject(new Error(`[cli] builder exited before emitting builder-ready (attempt ${attempt})`)));
         },
         onReady: () => {
-          ready = true;
           settle(resolve);
         },
+        onRestartReady: () => {
+          this.logger.verbose("[builder-recovery] builder ready after restart; replaying latest state");
+          this.#replayBuilderState();
+        },
       });
     });
   }
   #sendToBuilder(message: BuilderMessage) {
-    if (this.#builder) this.#builder.send(message);
-    else this.logger.warn("akanAppHost is not running");
+    if (this.#builder?.send(message)) return;
+    if (message.type === "build-route") {
+      this.#sendToBackend({
+        type: "build-route-res",
+        id: message.id,
+        ok: false,
+        error: `builder is ${this.#builder?.status ?? "stopped"}; reload after the builder is ready`,
+      });
+      return;
+    }
+    this.logger.warn("akanAppHost builder is not running");
   }
   #stopBuilder() {
     if (!this.#builder) return;

package/devkit/akanConfig/akanConfig.ts

@@ -269,7 +269,8 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     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];
+    if (AKAN_RUNTIME_PACKAGES.has(lib))
+      return akanPackageJson.dependencies?.[lib] ?? akanPackageJson.peerDependencies?.[lib];
   }
   getProductionPackageJson(data: Partial<PackageJson> = {}): PackageJson {
     return {

package/devkit/capacitor.base.config.ts

@@ -16,12 +16,25 @@ const getLocalIP = () => {
 
 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) throw new Error(`Akan mobile target '${targetName}' was not found.`);
+    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);
@@ -31,7 +44,8 @@ const resolveTarget = (appInfo: AppScanResult, targetName = process.env.AKAN_MOB
 
 const localCsrUrl = (ip: string, target: AkanMobileTargetConfig) => {
   const basePath = normalizeBasePath(target.basePath);
-  return `http://${ip}:8282/${basePath ? `${basePath}` : ""}?csr=true`;
+  const port = process.env.AKAN_PUBLIC_CLIENT_PORT ?? process.env.PORT ?? "8282";
+  return `http://${ip}:${port}/${basePath ? `${basePath}` : ""}?csr=true`;
 };
 
 export const withBase = (
@@ -44,9 +58,10 @@ export const withBase = (
   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: "www",
+    webDir: "dist",
     server:
       process.env.APP_OPERATION_MODE !== "release"
         ? {
@@ -62,7 +77,6 @@ export const withBase = (
       CapacitorCookies: { enabled: true },
       ...target.plugins,
     },
-    ...target,
     android: {
       ...target.android,
     },