@akanjs/devkit 3.0.0-beta.9 → 3.0.0

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;
+    }
+  }
+}

package/mobile/nativeApp.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import type { AkanPlugin } from "akanjs";
+import type { AkanNativeTarget } from "../akanConfig";
+import type { App } from "../commandDecorators";
+import { tempDirs, writeText } from "../testHelpers";
+import { NativeApp } from "./nativeApp";
+import { NativeConfig } from "./nativeConfig";
+
+const makeTempRoot = tempDirs("akan-native-app-");
+
+const target = (config: Partial<AkanNativeTarget> = {}) => ({
+  name: config.name ?? "default",
+  config: {
+    name: config.name ?? "default",
+    appName: "Portal",
+    appId: "com.portal.app",
+    version: "1.0.0",
+    buildNum: 1,
+    ...config,
+  },
+});
+
+const appDir = "/repo/apps/portal";
+
+const fakeApp = (plugins: AkanPlugin[] = []) =>
+  ({
+    name: "portal",
+    cwdPath: appDir,
+    workspace: { workspaceRoot: "/repo" },
+    getScanInfo: () => ({ getLibs: () => [] }),
+    dist: { cwdPath: "/repo/dist/apps/portal" },
+    getConfig: async () => ({ i18n: { locales: ["en", "ko"] }, api: { prefix: "/api", websocketPrefix: "/ws" } }),
+    collectPlugins: async () => plugins,
+    logger: { warn: () => undefined },
+  }) as unknown as App;
+
+describe("NativeApp", () => {
+  test("keeps each target's web root and each platform's output apart", () => {
+    const admin = new NativeApp(fakeApp(), target({ name: "admin", basePath: "admin" }));
+
+    expect(admin.web.dir).toBe(path.join(appDir, ".akan/native/admin/web"));
+    expect(admin.outDir("ios")).toBe(path.join(appDir, ".akan/native/admin/build/ios"));
+    expect(admin.outDir("android")).toBe(path.join(appDir, ".akan/native/admin/build/android"));
+    expect(admin.devOutDir("macos")).toBe(path.join(appDir, ".akan/native/admin/dev/macos"));
+  });
+
+  test("a dev build bundles no page a release build left, and builds apart from the release it would empty", async () => {
+    const app = {
+      ...fakeApp(),
+      cwdPath: await makeTempRoot(),
+      logger: { info: () => undefined, debug: () => undefined, warn: () => undefined },
+    } as unknown as App;
+    const nativeApp = new NativeApp(app, target());
+    await writeText(path.join(nativeApp.web.dir, "index.html"), "<html>the last release</html>");
+    const seen: { outDir?: string; leftover: boolean }[] = [];
+    nativeApp.prepare = async () =>
+      ({
+        config: {},
+        api: {
+          dev: async ({ outDir }: { outDir?: string }) => {
+            seen.push({ outDir, leftover: await Bun.file(path.join(nativeApp.web.dir, "index.html")).exists() });
+            return { gateway: "http://127.0.0.1:9", exited: Promise.resolve(0), stop: async () => undefined };
+          },
+        },
+      }) as never;
+
+    await nativeApp.dev("windows", { upstream: "http://localhost:8282", lang: "en" });
+
+    expect(seen).toEqual([{ outDir: nativeApp.devOutDir("windows"), leftover: false }]);
+    expect(path.relative(nativeApp.outDir("windows"), nativeApp.devOutDir("windows"))).toStartWith("..");
+  });
+
+  test("a dev boot that came up says so in one line: platform, device, dev server, time", () => {
+    const app = { ...fakeApp(), name: "portal" } as unknown as App;
+    const startedAt = performance.now() - 12_400;
+    expect(new NativeApp(app, target()).readyLine("macos", { upstream: "http://localhost:8283", startedAt })).toMatch(
+      /^portal desktop ready · http:\/\/localhost:8283 · 12\.\ds$/,
+    );
+    expect(
+      new NativeApp(app, target({ name: "admin" })).readyLine("ios", {
+        upstream: "http://localhost:8283",
+        device: { name: "iPhone 16" },
+        startedAt,
+      }),
+    ).toMatch(/^portal\/admin ios ready · iPhone 16 · http:\/\/localhost:8283 · 12\.\ds$/);
+  });
+
+  test("an installer is what a person downloads, on the desktops that have one", () => {
+    expect(() => NativeApp.assertInstaller("windows", true)).not.toThrow();
+    expect(() => NativeApp.assertInstaller("macos", true)).not.toThrow();
+    expect(() => NativeApp.assertInstaller("linux", true)).not.toThrow();
+    expect(() => NativeApp.assertInstaller("ios", true)).toThrow(/not for ios/);
+  });
+
+  test("opens a dev build on its target's home, the CSR shell under the locale", () => {
+    expect(new NativeApp(fakeApp(), target({ indexPath: "/explore" })).startPath("en", "ios")).toBe(
+      "/en/explore?csr=true&akanMobileTarget=default&akanMobileIndexPath=%2Fexplore",
+    );
+    expect(new NativeApp(fakeApp(), target({ name: "admin", basePath: "/admin/" })).startPath("ko", "android")).toBe(
+      "/ko/admin?csr=true&akanMobileTarget=admin&akanMobileBasePath=admin",
+    );
+  });
+
+  test("a platform section's indexPath wins on that platform, and the others keep the target's", () => {
+    const app = new NativeApp(fakeApp(), target({ indexPath: "/mobile", desktop: { indexPath: "/", server: true } }));
+
+    expect(app.indexPath("ios")).toBe("/mobile");
+    expect(app.indexPath("android")).toBe("/mobile");
+    expect(app.indexPath("macos")).toBe("/");
+    expect(app.indexPath("windows")).toBe("/");
+    expect(app.startPath("en", "macos")).toBe("/en?csr=true&akanMobileTarget=default&akanMobileIndexPath=%2F");
+    expect(app.startPath("en", "ios")).toBe(
+      "/en/mobile?csr=true&akanMobileTarget=default&akanMobileIndexPath=%2Fmobile",
+    );
+  });
+
+  test("assembles each platform's web root with that platform's indexPath", async () => {
+    const root = await makeTempRoot();
+    await writeText(path.join(root, "dist/csr/index.html"), "<html><head></head><body></body></html>");
+    const app = { ...fakeApp(), cwdPath: root, dist: { cwdPath: path.join(root, "dist") } } as unknown as App;
+    const nativeApp = new NativeApp(app, target({ indexPath: "/mobile", desktop: { indexPath: "/console" } }));
+    const injected = async () => await Bun.file(path.join(nativeApp.web.dir, "index.html")).text();
+
+    await nativeApp.assembleWeb("linux");
+    expect(await injected()).toContain('"indexPath":"/console"');
+    await nativeApp.assembleWeb("android");
+    expect(await injected()).toContain('"indexPath":"/mobile"');
+  });
+
+  test("builds its config from the app's locales and the plugins' native contributions", async () => {
+    const push: AkanPlugin = { name: "push-notification", native: { permission: "push", plugins: ["push"] } };
+    const app = new NativeApp(
+      fakeApp([push, { name: "other" }]),
+      target({ basePath: undefined, permissions: ["push"] }),
+    );
+
+    const { config, warnings } = await app.config({ platform: "android" });
+
+    expect(warnings).toEqual([]);
+    expect(config.plugins).toEqual([...NativeConfig.basePlugins, "push"]);
+    expect(config.web.dir).toBe(path.join(appDir, ".akan/native/default/web"));
+  });
+
+  test("a config nothing is built from (the update key's) stages no desktop bin", async () => {
+    const { config } = await new NativeApp(fakeApp(), target({ basePath: undefined })).config({
+      platform: "macos",
+      stageBin: false,
+    });
+    expect(config.desktop?.bin).toBeUndefined();
+  });
+
+  test("follows the updates channel of the backend env it is built for", async () => {
+    const updates = { url: "https://releases.example.com/portal", publicKey: `${"a".repeat(43)}=` };
+    const built = async (env?: "debug" | "main") =>
+      (await new NativeApp(fakeApp(), target({ basePath: undefined, updates }), env).config({ platform: "android" }))
+        .config.updates;
+
+    expect(await built("main")).toEqual({ ...updates, channel: "main" });
+    expect(await built("debug")).toEqual({ ...updates, channel: "debug" });
+  });
+
+  test("a desktop app is this computer's platform", () => {
+    expect(["darwin", "win32", "linux"].map((host) => NativeApp.desktopPlatform(host as NodeJS.Platform))).toEqual([
+      "macos",
+      "windows",
+      "linux",
+    ]);
+    expect(() => NativeApp.desktopPlatform("freebsd")).toThrow("A desktop app builds on macOS, Windows or Linux");
+  });
+
+  test("signs an Android release with the upload key the environment names, and says which part is missing", () => {
+    expect(
+      NativeApp.androidSigning({
+        MYAPP_RELEASE_STORE_FILE: "keys/upload.jks",
+        MYAPP_RELEASE_STORE_PASSWORD: "store",
+        MYAPP_RELEASE_KEY_ALIAS: "upload",
+      }),
+    ).toEqual({ keystore: "keys/upload.jks", storePassword: "store", alias: "upload" });
+    expect(() => NativeApp.androidSigning({ MYAPP_RELEASE_STORE_FILE: "keys/upload.jks" })).toThrow(
+      "set MYAPP_RELEASE_STORE_PASSWORD, MYAPP_RELEASE_KEY_ALIAS in the environment",
+    );
+  });
+});