@akanjs/devkit 3.0.0-beta.9 → 3.0.1

package/mobile/desktopServerStage.ts

@@ -0,0 +1,178 @@
+import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { AkanAppConfig, NativeEnv } from "../akanConfig";
+import type { App } from "../commandDecorators";
+import type { PackageJson } from "../types";
+import { DesktopBin } from "./desktopBin";
+
+/** What a desktop build hands the native runtime as `desktop.server`. */
+export interface DesktopServerBundle {
+  dir: string;
+  entry: string;
+  env: Record<string, string>;
+}
+
+//* A desktop app's carried server is the backend `akan build` wrote into dist, installed on its own as the image's
+//* `bun install --production` does. It is staged outside dist: installing there would put host packages into the
+//* image's `COPY . .`.
+export class DesktopServerStage {
+  //? An API-only server starts neither the RSC worker nor the akan console and serves no CSR, public/ or SSR artifact,
+  //? and `install` wrote its own package.json. The rest of dist is the server's: its chunks, a `.node`, a `.wasm`.
+  static readonly uncarried = new Set([
+    "Dockerfile",
+    "package.json",
+    "rscWorker.js",
+    "console.js",
+    "console-runtime.js",
+    "csr",
+    "public",
+    ".akan",
+  ]);
+  //? Only the RSC worker loads it, and its peer webpack makes 35 of the 43 MB an install would add.
+  static readonly rscRenderer = "react-server-dom-webpack";
+
+  readonly dir: string;
+
+  constructor(readonly app: App) {
+    this.dir = path.join(app.cwdPath, ".akan", "desktop", "server");
+  }
+
+  static assertCarriable(config: AkanAppConfig) {
+    if (!config.database.modes.includes("single"))
+      throw new Error(
+        `desktop.server in native puts the server in the app, where only database mode single runs (no Redis or Postgres); apps/${config.app.name}/akan.config.ts declares ${config.database.modes.join(", ")}.`,
+      );
+  }
+
+  static env(config: AkanAppConfig, environment: NativeEnv): Record<string, string> {
+    //? The launcher picks the port, and the log file stays on: a user's computer has no log collector.
+    const { PORT: _port, AKAN_LOG_TO_FILE: _fileLog, ...image } = config.getProductionEnv(environment);
+    return {
+      ...image,
+      //? Neither the developer's machine (local, which derives a forgeable JWT secret) nor a deployment (cloud).
+      AKAN_PUBLIC_OPERATION_MODE: "edge",
+      AKAN_DATABASE_MODE: "single",
+      AKAN_DATABASE_MODES: "single",
+      //? API only: the shell serves the CSR bundle, and an RSC worker would need a bun on the user's PATH.
+      AKAN_SSR: "false",
+      AKAN_CSR: "false",
+      AKAN_MCP: "false",
+      //? Ahead of the launcher's 1.5 s grace before it signals, which sits inside the shell's 2 s quit budget.
+      AKAN_SHUTDOWN_TIMEOUT_MS: "1000",
+    };
+  }
+
+  //? The image's steps install into a Linux image the desktop app never runs in, so its server has none of it.
+  static imageStepsNotice(
+    config: Pick<AkanAppConfig, "app" | "docker">,
+    carried: string[],
+  ): { level: "warn" | "info"; message: string } | null {
+    const steps =
+      typeof config.docker === "string" ? null : config.docker.preRuns.length + config.docker.postRuns.length;
+    if (steps === 0) return null;
+    const image =
+      steps === null
+        ? `apps/${config.app.name}/akan.config.ts writes its own Dockerfile`
+        : `The image runs ${steps} docker step${steps === 1 ? "" : "s"} from the app and its libs`;
+    return carried.length
+      ? {
+          level: "info",
+          message: `${image}; the desktop app's server runs none of them and carries only bin: ${carried.join(", ")}.`,
+        }
+      : {
+          level: "warn",
+          message: `${image}, and a desktop app's server runs none of them: declare in bin the executables its code spawns, or those calls fail on the user's computer.`,
+        };
+  }
+
+  //? `omit` (the target's `desktop.server.omit`) wins over externalLibs: the image keeps those packages, the app does not.
+  static packageJson(config: AkanAppConfig, built: PackageJson, omit: string[] = []): PackageJson {
+    const otherDrivers = new Set(
+      config.database.modes
+        .filter((mode) => mode !== "single")
+        .flatMap((mode) => config.getDatabaseModeRuntimePackages(mode)),
+    );
+    const dependencies = Object.entries(built.dependencies ?? {}).filter(
+      ([name]) =>
+        !omit.includes(name) &&
+        (config.externalLibs.includes(name) || (name !== DesktopServerStage.rscRenderer && !otherDrivers.has(name))),
+    );
+    return { ...built, dependencies: Object.fromEntries(dependencies) };
+  }
+
+  /** The packages in `nodeModules` that depend on `name`: what still pulls an omitted package in. */
+  static async dependentsOf(nodeModules: string, name: string): Promise<string[]> {
+    const dependents = new Set<string>();
+    for await (const manifest of new Bun.Glob("**/package.json").scan({ cwd: nodeModules, onlyFiles: true })) {
+      const json = (await Bun.file(path.join(nodeModules, manifest))
+        .json()
+        .catch(() => null)) as PackageJson | null;
+      if (!json?.name || json.name === name) continue;
+      const declared = { ...json.dependencies, ...json.optionalDependencies, ...json.peerDependencies };
+      if (name in declared) dependents.add(json.name);
+    }
+    return [...dependents].sort();
+  }
+
+  //? `--cpu` installs another CPU's optional packages: an addon's prebuilt binary for the app's CPU, not this computer's.
+  static installArgs(arch?: "arm64" | "x64"): string[] {
+    return ["install", "--production", "--prefer-offline", ...(arch && arch !== process.arch ? [`--cpu=${arch}`] : [])];
+  }
+
+  //* The packages come from the config alone, so they install before `akan build` runs: a machine that cannot install
+  //* them stops at once instead of after the whole build.
+  async install(arch?: "arm64" | "x64", omit: string[] = []) {
+    const config = await this.app.getConfig();
+    DesktopServerStage.assertCarriable(config);
+    await rm(this.dir, { recursive: true, force: true });
+    await mkdir(this.dir, { recursive: true });
+    const built = config.getProductionPackageJson();
+    for (const name of omit.filter((name) => !(name in (built.dependencies ?? {}))))
+      this.app.logger.warn(`desktop.server.omit names ${name}, which the server does not depend on directly.`);
+    await writeFile(
+      path.join(this.dir, "package.json"),
+      JSON.stringify(DesktopServerStage.packageJson(config, built, omit), null, 2),
+    );
+    try {
+      await this.app.spawn(process.execPath, DesktopServerStage.installArgs(arch), { cwd: this.dir });
+    } catch (error) {
+      throw new Error(
+        `The desktop app's server could not install its packages in ${this.dir}: it needs the npm registry, or a Bun cache that already holds every one of them.\n${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+    //? Launcher links only: a link out of the app bundle breaks its signature, and the server runs none of them.
+    await rm(path.join(this.dir, "node_modules", ".bin"), { recursive: true, force: true });
+    await this.#assertOmitted(omit);
+  }
+
+  //? Leaving a package out of package.json keeps out only what nothing else needs; another dependency still installs it.
+  async #assertOmitted(omit: string[]) {
+    const nodeModules = path.join(this.dir, "node_modules");
+    const kept: string[] = [];
+    for (const name of omit) {
+      if (!(await Bun.file(path.join(nodeModules, name, "package.json")).exists())) continue;
+      const dependents = await DesktopServerStage.dependentsOf(nodeModules, name);
+      kept.push(`${name} (needed by ${dependents.join(", ") || "a package that names it"})`);
+    }
+    if (kept.length)
+      throw new Error(
+        `desktop.server.omit leaves out packages another dependency still installs: ${kept.join("; ")}. Omit those too, or keep the package.`,
+      );
+  }
+
+  //? Copies the build beside what `install` put in the stage, so it runs after both.
+  async prepare(environment: NativeEnv): Promise<DesktopServerBundle> {
+    const config = await this.app.getConfig();
+    const dist = this.app.dist.cwdPath;
+    await mkdir(this.dir, { recursive: true });
+    for (const name of await readdir(dist))
+      if (!DesktopServerStage.uncarried.has(name))
+        await cp(path.join(dist, name), path.join(this.dir, name), { recursive: true });
+    const scanInfo = this.app.getScanInfo({ allowEmpty: true }) ?? (await this.app.scan({ write: false }));
+    const carried = [...DesktopBin.select(config, scanInfo.getLibs()).keys()];
+    const notice = DesktopServerStage.imageStepsNotice(config, carried);
+    if (notice) this.app.logger[notice.level](notice.message);
+    return { dir: this.dir, entry: "main.js", env: DesktopServerStage.env(config, environment) };
+  }
+}

package/mobile/index.ts

@@ -1 +1,10 @@
+export * from "./desktopBin";
+export * from "./desktopServerStage";
 export * from "./mobileTarget";
+export * from "./nativeApi";
+export * from "./nativeApp";
+export * from "./nativeConfig";
+export * from "./nativePluginFolders";
+export * from "./nativeWebDir";
+export * from "./placeholderAppId";
+export * from "./usageDescriptions";

package/mobile/mobileTarget.test.ts

@@ -1,7 +1,14 @@
 import { describe, expect, test } from "bun:test";
-import type { AkanMobileTargetConfig } from "../akanConfig";
+import type { AkanNativeTarget } from "../akanConfig";
 import type { App } from "../commandDecorators";
-import { getMobileTargetChoices, resolveMobilePath, resolveMobileTargets, targetHtmlFilename } from "./mobileTarget";
+import {
+  appIdsOf,
+  getMobileTargetChoices,
+  resolveAppId,
+  resolveMobilePath,
+  resolveMobileTargets,
+  targetHtmlFilename,
+} from "./mobileTarget";
 
 const target = {
   name: "akanjs",
@@ -10,25 +17,36 @@ const target = {
   appId: "com.akanjs.app",
   version: "1.0.0",
   buildNum: 1,
-} as AkanMobileTargetConfig;
+} as AkanNativeTarget;
 
-describe("mobile target helpers", () => {
+describe("native target helpers", () => {
   test("maps deep links into target base paths without duplicating prefixes", () => {
     expect(resolveMobilePath(target, "/order/123")).toBe("/akanjs/order/123");
     expect(resolveMobilePath(target, "/akanjs/order/123")).toBe("/akanjs/order/123");
     expect(resolveMobilePath({ ...target, basePath: undefined }, "/order/123")).toBe("/order/123");
   });
 
+  test("an app id per platform falls back to default, and a platform with neither is refused", () => {
+    const appId = { default: "com.yeollege", ios: "com.puffinplanet.yeollege" };
+    expect(resolveAppId(appId, "ios")).toBe("com.puffinplanet.yeollege");
+    expect(resolveAppId(appId, "android")).toBe("com.yeollege");
+    expect(resolveAppId("com.one.app", "macos")).toBe("com.one.app");
+    expect(() => resolveAppId({ ios: "com.puffinplanet.yeollege" }, "android")).toThrow(
+      "native.appId names no id for android",
+    );
+    expect(appIdsOf(appId)).toEqual(["com.yeollege", "com.puffinplanet.yeollege"]);
+  });
+
   test("selects the self-contained html file for a target", () => {
     expect(targetHtmlFilename(target)).toBe("akanjs.html");
     expect(targetHtmlFilename({ ...target, basePath: undefined })).toBe("index.html");
   });
 
-  test("uses the configured mobile target as the only choice when one target is configured", async () => {
+  test("uses the configured native target as the only choice when one target is configured", async () => {
     const app = {
       getConfig: async () => ({
         basePaths: new Set(["akanjs", "soft", "office"]),
-        mobile: { targets: { akanjs: target } },
+        native: { targets: { akanjs: target } },
       }),
     } as unknown as App;
 
@@ -36,11 +54,42 @@ describe("mobile target helpers", () => {
     await expect(resolveMobileTargets(app, undefined)).resolves.toEqual([{ name: "akanjs", config: target }]);
   });
 
-  test("resolves a route base path onto the default mobile target config", async () => {
+  test("a target naming no basePath is a template in an app with basePaths, never a page of its own", async () => {
+    const template = { ...target, name: "default", basePath: undefined };
+    const appWith = (basePaths: string[]) =>
+      ({
+        name: "angelo",
+        getConfig: async () => ({ basePaths: new Set(basePaths), native: { targets: { default: template } } }),
+      }) as unknown as App;
+
+    const two = appWith(["soft", "office"]);
+    await expect(getMobileTargetChoices(two)).resolves.toEqual(["soft", "office"]);
+    await expect(resolveMobileTargets(two, undefined)).rejects.toThrow(
+      "Multiple native targets found for angelo. Pass --target <soft|office|all>.",
+    );
+    await expect(resolveMobileTargets(two, "office")).resolves.toEqual([
+      { name: "office", config: { ...template, name: "office", basePath: "office" } },
+    ]);
+    await expect(resolveMobileTargets(two, "all")).resolves.toEqual([
+      { name: "soft", config: { ...template, name: "soft", basePath: "soft" } },
+      { name: "office", config: { ...template, name: "office", basePath: "office" } },
+    ]);
+
+    const one = appWith(["soft"]);
+    const soft = [{ name: "soft", config: { ...template, name: "soft", basePath: "soft" } }];
+    await expect(resolveMobileTargets(one, undefined)).resolves.toEqual(soft);
+    await expect(resolveMobileTargets(one, "all")).resolves.toEqual(soft);
+
+    await expect(resolveMobileTargets(appWith([]), undefined)).resolves.toEqual([
+      { name: "default", config: template },
+    ]);
+  });
+
+  test("resolves a route base path onto the default native target config", async () => {
     const app = {
       getConfig: async () => ({
         basePaths: new Set(["akanjs", "soft", "office"]),
-        mobile: { targets: { akanjs: target } },
+        native: { targets: { akanjs: target } },
       }),
     } as unknown as App;
 

package/mobile/mobileTarget.ts

@@ -1,45 +1,52 @@
-import type { AkanMobileTargetConfig, MobileEnv } from "../akanConfig";
+import type { AkanNativeAppId } from "akanjs";
+import type { AkanAppConfig, AkanNativeTarget, NativeEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 
 export type MobilePlatform = "ios" | "android";
+export type DesktopPlatform = "macos" | "windows" | "linux";
+export type NativePlatform = MobilePlatform | DesktopPlatform;
 export type MobileTargetSelection = string | "all" | undefined;
 
 export interface ResolvedMobileTarget {
   name: string;
-  config: AkanMobileTargetConfig;
+  config: AkanNativeTarget;
 }
 
-export const MOBILE_ENVS = ["local", "debug", "develop", "main"] as const satisfies readonly MobileEnv[];
+export const MOBILE_ENVS = ["local", "debug", "develop", "main"] as const satisfies readonly NativeEnv[];
+
+const trimSlashes = (value: string) => value.replace(/^\/+|\/+$/g, "");
 
 export const getMobileTargets = async (app: App): Promise<ResolvedMobileTarget[]> => {
   const config = await app.getConfig();
-  return Object.entries(config.mobile.targets).map(([name, target]) => ({ name, config: target }));
+  return Object.entries(config.native.targets).map(([name, target]) => ({ name, config: target }));
 };
 
+//* An app with basePaths builds a CSR page per basePath and none at its root, so a target naming no basePath opens
+//* nothing on its own there; it is the template each basePath's target is made from.
+const isTemplateOnly = ({ basePaths, native }: Pick<AkanAppConfig, "basePaths" | "native">) =>
+  basePaths.size > 0 && Object.values(native.targets).every((target) => !target.basePath);
+
 export const getMobileTargetChoices = async (app: App): Promise<string[]> => {
   const config = await app.getConfig();
-  const targetNames = Object.keys(config.mobile.targets);
-  if (targetNames.length > 0) return targetNames;
-  const basePaths = [...config.basePaths];
-  return basePaths;
+  const targetNames = Object.keys(config.native.targets);
+  if (targetNames.length > 0 && !isTemplateOnly(config)) return targetNames;
+  return [...config.basePaths];
 };
 
 const resolveMobileTargetByBasePath = (
   targets: ResolvedMobileTarget[],
   basePath: string,
 ): ResolvedMobileTarget | undefined => {
-  const normalizedBasePath = basePath.replace(/^\/+|\/+$/g, "");
-  const byBasePath = targets.find((target) => target.config.basePath?.replace(/^\/+|\/+$/g, "") === normalizedBasePath);
+  const normalizedBasePath = trimSlashes(basePath);
+  const byBasePath = targets.find(
+    ({ config }) => config.basePath !== undefined && trimSlashes(config.basePath) === normalizedBasePath,
+  );
   if (byBasePath) return byBasePath;
   const [template] = targets;
   if (!template) return undefined;
   return {
     name: normalizedBasePath,
-    config: {
-      ...template.config,
-      name: normalizedBasePath,
-      basePath: normalizedBasePath,
-    },
+    config: { ...template.config, name: normalizedBasePath, basePath: normalizedBasePath },
   };
 };
 
@@ -49,17 +56,17 @@ export const resolveMobileTargets = async (
 ): Promise<ResolvedMobileTarget[]> => {
   const config = await app.getConfig();
   const targets = await getMobileTargets(app);
-  if (targets.length === 0) throw new Error(`No mobile targets configured for ${app.name}`);
-  if (!selection && targets.length === 1) return targets;
+  if (targets.length === 0) throw new Error(`No native targets configured for ${app.name}`);
+  if (!selection && targets.length === 1 && !isTemplateOnly(config)) return targets;
   if (!selection) {
     const choices = await getMobileTargetChoices(app);
     if (choices.length === 1) return resolveMobileTargets(app, choices[0]);
-    throw new Error(`Multiple mobile targets found for ${app.name}. Pass --target <${choices.join("|")}|all>.`);
+    throw new Error(`Multiple native targets found for ${app.name}. Pass --target <${choices.join("|")}|all>.`);
   }
   if (selection === "all") {
-    if (Object.keys(config.mobile.targets).length > 1) return targets;
+    if (Object.keys(config.native.targets).length > 1) return targets;
     const basePaths = [...config.basePaths];
-    if (basePaths.length > 1) {
+    if (basePaths.length > 1 || isTemplateOnly(config)) {
       return basePaths.flatMap((basePath) => {
         const resolved = resolveMobileTargetByBasePath(targets, basePath);
         return resolved ? [resolved] : [];
@@ -70,18 +77,30 @@ export const resolveMobileTargets = async (
   const target = targets.find((candidate) => candidate.name === selection);
   if (target) return [target];
   const basePathTarget = resolveMobileTargetByBasePath(targets, selection);
-  if (basePathTarget && config.basePaths.has(selection.replace(/^\/+|\/+$/g, ""))) return [basePathTarget];
+  if (basePathTarget && config.basePaths.has(trimSlashes(selection))) return [basePathTarget];
   const choices = await getMobileTargetChoices(app);
-  throw new Error(`Mobile target '${selection}' was not found. Available: ${choices.join(", ")}`);
+  throw new Error(`Native target '${selection}' was not found. Available: ${choices.join(", ")}`);
+};
+
+export const resolveAppId = (appId: AkanNativeAppId, platform: NativePlatform): string => {
+  if (typeof appId === "string") return appId;
+  const id = appId[platform] ?? appId.default;
+  if (!id) throw new Error(`native.appId names no id for ${platform}; give it ${platform} or default.`);
+  return id;
 };
 
-export const resolveMobilePath = (target: AkanMobileTargetConfig, pathname: string) => {
-  const basePath = target.basePath?.replace(/^\/+|\/+$/g, "");
+export const appIdsOf = (appId: AkanNativeAppId): string[] =>
+  typeof appId === "string" ? [appId] : Object.values(appId).filter((id): id is string => !!id);
+
+export const resolveMobilePath = (target: AkanNativeTarget, pathname: string) => {
+  const basePath = trimSlashes(target.basePath ?? "");
   const normalizedPath = `/${pathname.replace(/^\/+/, "")}`;
   if (!basePath) return normalizedPath;
   if (normalizedPath === `/${basePath}` || normalizedPath.startsWith(`/${basePath}/`)) return normalizedPath;
   return `/${basePath}${normalizedPath === "/" ? "" : normalizedPath}`;
 };
 
-export const targetHtmlFilename = (target: AkanMobileTargetConfig) =>
-  target.basePath?.replace(/^\/+|\/+$/g, "") ? `${target.basePath.replace(/^\/+|\/+$/g, "")}.html` : "index.html";
+export const targetHtmlFilename = (target: AkanNativeTarget) => {
+  const basePath = trimSlashes(target.basePath ?? "");
+  return basePath ? `${basePath}.html` : "index.html";
+};

package/mobile/nativeApi.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs } from "../testHelpers";
+import { NativeApi } from "./nativeApi";
+
+const makeTempRoot = tempDirs("akan-native-api-");
+const repoApp = path.resolve(import.meta.dir, "../../../../apps/minimal");
+
+describe("NativeApi", () => {
+  test("inside this repo, loads the workspace package and checks its major", async () => {
+    expect(NativeApi.entryOf(repoApp)).toBe(path.resolve(import.meta.dir, "../../native/packages/cli/src/api.ts"));
+    const api = await NativeApi.load(repoApp);
+    expect(api.API_VERSION.split(".")[0]).toBe(String(NativeApi.supportedMajor));
+  });
+
+  test("elsewhere, looks for the copy akanjs vendors, and says so when it is missing", async () => {
+    const root = await realpath(await makeTempRoot());
+    await mkdir(path.join(root, "node_modules/akanjs"), { recursive: true });
+    await writeFile(
+      path.join(root, "node_modules/akanjs/package.json"),
+      JSON.stringify({ name: "akanjs", exports: { "./package.json": "./package.json" } }),
+    );
+
+    expect(NativeApi.entryOf(root)).toBe(
+      path.join(root, "node_modules/akanjs/vendor/@akanjs/native/packages/cli/src/api.ts"),
+    );
+    await expect(NativeApi.load(root)).rejects.toThrow("The installed akanjs has no native build");
+  });
+});

package/mobile/nativeApi.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+import type * as NativeBuildApi from "@akanjs/native/api";
+
+export type NativeBuildApiModule = typeof NativeBuildApi;
+
+export class NativeApi {
+  //* The build API versions itself; a major this devkit was not written against is refused before anything builds.
+  static readonly supportedMajor = 0;
+
+  /** The API of the akanjs the app installed: the workspace package inside this repo, akanjs's vendored copy elsewhere. */
+  static entryOf(appDir: string): string {
+    const workspaceEntry = NativeApi.#resolve("@akanjs/native/api", appDir);
+    if (workspaceEntry) return workspaceEntry;
+    const akanjsPackage = NativeApi.#resolve("akanjs/package.json", appDir);
+    if (!akanjsPackage) throw new Error(`akanjs is not installed for ${appDir}; the native build ships inside it.`);
+    return path.join(path.dirname(akanjsPackage), "vendor", "@akanjs", "native", "packages", "cli", "src", "api.ts");
+  }
+
+  static async load(appDir: string): Promise<NativeBuildApiModule> {
+    const entry = NativeApi.entryOf(appDir);
+    if (!(await Bun.file(entry).exists()))
+      throw new Error(`The installed akanjs has no native build at ${entry}; update akanjs.`);
+    const api = (await import(entry)) as NativeBuildApiModule;
+    const major = Number(api.API_VERSION.split(".")[0]);
+    if (major !== NativeApi.supportedMajor)
+      throw new Error(
+        `The native build API is ${api.API_VERSION}, and this akan CLI speaks ${NativeApi.supportedMajor}.x; install matching versions of akanjs and @akanjs/cli.`,
+      );
+    return api;
+  }
+
+  static #resolve(specifier: string, from: string) {
+    try {
+      return Bun.resolveSync(specifier, from);
+    } catch {
+      // Not installed where the app can reach it, which the caller answers with the next place to look.
+      return null;
+    }
+  }
+}