@akanjs/devkit 3.0.0-beta.20 → 3.0.0-beta.21

package/lint/no-document-cookie.grit

@@ -0,0 +1,29 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// A native shell serves the page from app://localhost on iOS, macOS and Linux, a custom scheme WebKit keeps no
+// cookie jar for: `document.cookie` reads "" and a write is dropped without an error, so the value exists in the
+// browser and silently vanishes in the app. akanjs/client's cookie helpers keep an app:// page's cookies in a
+// storage-backed jar, which is the only spelling that works in every shell.
+//
+// Pinned to the member nodes: a bare snippet also matches JSX text that spells the same words (a docs page), and a
+// write is its own node (JsStaticMemberAssignment) that the expression form does not match.
+or {
+  JsStaticMemberExpression() as $access where {
+    $access <: or { `document.cookie`, `window.document.cookie`, `globalThis.document.cookie`, `self.document.cookie` },
+    register_diagnostic(
+      span = $access,
+      message = "`document.cookie` is always empty on a native app page (app://localhost keeps no cookies), so this value vanishes in the app. Use `getCookie` / `setCookie` / `removeCookie` from `akanjs/client`.",
+      severity = "error"
+    )
+  },
+  JsStaticMemberAssignment(object = $object, member = $member) as $access where {
+    $member <: `cookie`,
+    $object <: or { `document`, `window.document`, `globalThis.document`, `self.document` },
+    register_diagnostic(
+      span = $access,
+      message = "`document.cookie` is always empty on a native app page (app://localhost keeps no cookies), so this value vanishes in the app. Use `getCookie` / `setCookie` / `removeCookie` from `akanjs/client`.",
+      severity = "error"
+    )
+  }
+}

package/lint/no-web-only-api-outside-webkit.grit

@@ -0,0 +1,44 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Browser APIs a native shell's WebView lacks: Android's WebView has no Web Share, an app:// page on iOS has no
+// service worker, no WebView has the Notification API, and iOS has no vibration. They stay legal on the web, so the
+// rule does not ban them — it keeps them in `webkit/`, the layer whose hooks branch on the platform (and is
+// excluded from this rule's scope in biome.base.json), and names the native side where one exists.
+//
+// Pinned to member access, so JSX text naming an API does not match; `Notification` only through its static entry
+// points, because the name is also the libs/shared model (`Notification.View`, `cnst.Notification`).
+or {
+  JsStaticMemberExpression() as $access where {
+    $access <: or { `navigator.share`, `navigator.canShare` },
+    register_diagnostic(
+      span = $access,
+      message = "Android's WebView has no Web Share, so this does nothing in the app. Move it into a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client/native`; the runtime's `share` plugin is the app side.",
+      severity = "warn"
+    )
+  },
+  JsStaticMemberExpression() as $access where {
+    $access <: or { `navigator.serviceWorker`, `Notification.requestPermission`, `Notification.permission` },
+    register_diagnostic(
+      span = $access,
+      message = "A native app page has no service worker or Notification API. Keep this in a `webkit/` hook behind `isNativeApp()`; native push is `push` from `akanjs/client/native`, and `usePushNotification` in libs/util wraps both.",
+      severity = "warn"
+    )
+  },
+  JsStaticMemberExpression() as $access where {
+    $access <: `navigator.geolocation`,
+    register_diagnostic(
+      span = $access,
+      message = "`navigator.geolocation` skips the app's location plugin and its permission flow. Use `useGeoLocation` from `akanjs/webkit`.",
+      severity = "warn"
+    )
+  },
+  JsStaticMemberExpression() as $access where {
+    $access <: `navigator.vibrate`,
+    register_diagnostic(
+      span = $access,
+      message = "iOS has no `navigator.vibrate`. Use `haptics` from `akanjs/client/native` in a `webkit/` hook.",
+      severity = "warn"
+    )
+  }
+}

package/lint/no-web-storage.grit

@@ -0,0 +1,30 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Web Storage works inside the native shells, so this is not about a crash: akanjs/client's `storage` is where the
+// backend is chosen per platform (the shell's Preferences — UserDefaults, SharedPreferences, a JSON file on the
+// desktop — in an app, localStorage on the web), `secretStorage` keeps credentials in the Keychain/Keystore and
+// clears them on a reinstall, and both answer nothing on the server where a bare `localStorage` read during SSR
+// throws.
+//
+// Only the global is matched — a reference, or a member of window/globalThis/self — pinned to those node kinds: a
+// bare snippet matches the name in any position, a field, an object key or JSX text included.
+or {
+  JsIdentifierExpression() as $access where {
+    $access <: or { `localStorage`, `sessionStorage` },
+    register_diagnostic(
+      span = $access,
+      message = "Web Storage bypasses the store akanjs picks per platform (the shell's Preferences in an app) and throws during SSR. Use `storage` from `akanjs/client`, or `secretStorage` for tokens and credentials; a value that may be lost with the tab belongs in component state or the store.",
+      severity = "error"
+    )
+  },
+  JsStaticMemberExpression(object = $root, member = $name) as $access where {
+    $root <: or { `window`, `globalThis`, `self` },
+    $name <: or { `localStorage`, `sessionStorage` },
+    register_diagnostic(
+      span = $access,
+      message = "Web Storage bypasses the store akanjs picks per platform (the shell's Preferences in an app) and throws during SSR. Use `storage` from `akanjs/client`, or `secretStorage` for tokens and credentials; a value that may be lost with the tab belongs in component state or the store.",
+      severity = "error"
+    )
+  }
+}

package/mobile/index.ts

@@ -1 +1,7 @@
 export * from "./mobileTarget";
+export * from "./nativeApi";
+export * from "./nativeApp";
+export * from "./nativeConfig";
+export * from "./nativeWebDir";
+export * from "./placeholderAppId";
+export * from "./usageDescriptions";

package/mobile/mobileTarget.ts

@@ -2,6 +2,8 @@ import type { AkanMobileTargetConfig, MobileEnv } 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 {

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,85 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import type { AkanPlugin } from "akanjs";
+import type { AkanMobileTargetConfig } from "../akanConfig";
+import type { App } from "../commandDecorators";
+import { NativeApp } from "./nativeApp";
+import { NativeConfig } from "./nativeConfig";
+
+const target = (config: Partial<AkanMobileTargetConfig> = {}) => ({
+  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[] = []) =>
+  ({
+    cwdPath: appDir,
+    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/mobile/admin/web"));
+    expect(admin.outDir("ios")).toBe(path.join(appDir, ".akan/mobile/admin/native/ios"));
+    expect(admin.outDir("android")).toBe(path.join(appDir, ".akan/mobile/admin/native/android"));
+  });
+
+  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")).toBe(
+      "/en/explore?csr=true&akanMobileTarget=default&akanMobileIndexPath=%2Fexplore",
+    );
+    expect(new NativeApp(fakeApp(), target({ name: "admin", basePath: "/admin/" })).startPath("ko")).toBe(
+      "/ko/admin?csr=true&akanMobileTarget=admin&akanMobileBasePath=admin",
+    );
+  });
+
+  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();
+
+    expect(warnings).toEqual([]);
+    expect(config.plugins).toEqual([...NativeConfig.basePlugins, "push"]);
+    expect(config.web.dir).toBe(path.join(appDir, ".akan/mobile/default/web"));
+  });
+
+  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",
+    );
+  });
+});

package/mobile/nativeApp.ts

@@ -0,0 +1,210 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { AkanNativeConfig } from "@akanjs/native/config";
+import type { App } from "../commandDecorators";
+import {
+  type DesktopPlatform,
+  type MobilePlatform,
+  type NativePlatform,
+  type ResolvedMobileTarget,
+  targetHtmlFilename,
+} from "./mobileTarget";
+import { NativeApi, type NativeBuildApiModule } from "./nativeApi";
+import { NativeConfig } from "./nativeConfig";
+import { NativeWebDir } from "./nativeWebDir";
+
+type TaskOptions = Parameters<NativeBuildApiModule["build"]>[0];
+type DeviceSelector = NonNullable<Parameters<NativeBuildApiModule["run"]>[0]["device"]>;
+type ReleaseOptions = Parameters<NativeBuildApiModule["release"]>[0];
+type AndroidSigning = Extract<ReleaseOptions, { platform: "android" }>["signing"];
+
+export interface NativeRunOptions {
+  device?: DeviceSelector;
+  /** Narrows the iPhone signing to one Apple team. */
+  teamId?: string;
+}
+
+export interface NativeDevOptions extends NativeRunOptions {
+  /** The akan dev server the gateway proxies. */
+  upstream: string;
+  lang: string;
+}
+
+/** One mobile target of an app on the native runtime (a phone, or this computer as a desktop app): where it builds,
+ * what it ships, and the calls into the API. */
+export class NativeApp {
+  readonly targetRoot: string;
+  readonly web: NativeWebDir;
+
+  constructor(
+    readonly app: App,
+    readonly target: ResolvedMobileTarget,
+  ) {
+    this.targetRoot = path.join(app.cwdPath, ".akan", "mobile", target.name);
+    this.web = new NativeWebDir(path.join(this.targetRoot, "web"));
+  }
+
+  outDir(platform: NativePlatform) {
+    return path.join(this.targetRoot, "native", platform);
+  }
+
+  /** The web root, from the production build the mobile commands run first. */
+  async assembleWeb() {
+    const dist = this.app.dist.cwdPath;
+    return await this.web.assemble(this.target.config, {
+      html: path.join(dist, "csr", targetHtmlFilename(this.target.config)),
+      publicDir: path.join(dist, "public"),
+      fontsDir: path.join(dist, ".akan", "artifact", "fonts"),
+    });
+  }
+
+  async config() {
+    const [appConfig, plugins] = await Promise.all([this.app.getConfig(), this.app.collectPlugins()]);
+    return NativeConfig.build({
+      appPath: this.app.cwdPath,
+      target: this.target.config,
+      webDir: this.web.dir,
+      contributions: plugins.flatMap((plugin) => (plugin.native ? [plugin.native] : [])),
+      locales: appConfig.i18n.locales,
+    });
+  }
+
+  /** The API and the config it is about to build, refused here when the runtime would refuse it later. */
+  async prepare() {
+    const [api, { config, warnings }] = await Promise.all([NativeApi.load(this.app.cwdPath), this.config()]);
+    for (const warning of warnings) this.app.logger.warn(warning);
+    const problems = api.validateConfig(config, { appDir: this.app.cwdPath });
+    if (problems.length)
+      throw new Error(
+        `Mobile target '${this.target.name}' makes an invalid native config:\n- ${problems.join("\n- ")}`,
+      );
+    return { api, config };
+  }
+
+  //? The app's own output: its console (mirrored by a dev build), the simulator log stream or logcat.
+  #appLine = (line: string) => {
+    this.app.logger.info(`[${this.target.name}] ${line}`);
+  };
+
+  //* `AKAN_PUBLIC_*` is already inlined into the CSR bundle, so the runtime reads no .env file of its own.
+  #task(platform: NativePlatform, config: AkanNativeConfig): TaskOptions {
+    return {
+      appDir: this.app.cwdPath,
+      config,
+      platform,
+      outDir: this.outDir(platform),
+      envFiles: false,
+      skipWebBuild: true,
+      log: (event) => {
+        if (event.level === "error") this.app.logger.error(event.message);
+        else if (event.level === "warn") this.app.logger.warn(event.message);
+        else if (event.level === "tool") this.app.logger.verbose(event.message);
+        else this.app.logger.info(event.message);
+      },
+    };
+  }
+
+  async build(platform: NativePlatform, { profile = "release" }: { profile?: "debug" | "release" } = {}) {
+    await this.assembleWeb();
+    const { api, config } = await this.prepare();
+    return await api.build({ ...this.#task(platform, config), profile });
+  }
+
+  async run(
+    platform: NativePlatform,
+    { device, teamId, profile = "debug" }: NativeRunOptions & { profile?: "debug" | "release" } = {},
+  ) {
+    await this.assembleWeb();
+    const { api, config } = await this.prepare();
+    return await api.run({
+      ...this.#task(platform, config),
+      profile,
+      onLine: this.#appLine,
+      ...(device ? { device } : {}),
+      ...(teamId ? { ios: { signing: { teamId } } } : {}),
+    });
+  }
+
+  //* The gateway serves the page and its HMR socket on the app origin; API calls go to the dev server itself (baseEnv),
+  //* which an Android device reaches through the reversed port.
+  async dev(platform: NativePlatform, { upstream, lang, device, teamId }: NativeDevOptions) {
+    await mkdir(this.web.dir, { recursive: true });
+    const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(), this.app.getConfig()]);
+    return await api.dev({
+      ...this.#task(platform, config),
+      upstream,
+      hmrPath: "/_akan/hmr",
+      //? A dev page calls its own origin (akanjs baseEnv), so the gateway relays the socket it opens for the API too.
+      wsPaths: [`${routes.prefix}${routes.websocketPrefix}`],
+      onLine: this.#appLine,
+      startPath: this.startPath(lang),
+      ...(device ? { device } : {}),
+      ...(teamId ? { ios: { signing: { teamId } } } : {}),
+    });
+  }
+
+  async releaseIos({ teamId, adHoc = false }: { teamId?: string; adHoc?: boolean } = {}) {
+    await this.assembleWeb();
+    const { api, config } = await this.prepare();
+    return await api.release({
+      ...this.#task("ios", config),
+      platform: "ios",
+      signing: { ...(teamId ? { teamId } : {}), ...(adHoc ? { distribution: "ad-hoc" as const } : {}) },
+    });
+  }
+
+  async releaseAndroid({ formats = ["aab"] }: { formats?: ("aab" | "apk")[] } = {}) {
+    const signing = NativeApp.androidSigning();
+    await this.assembleWeb();
+    const { api, config } = await this.prepare();
+    return await api.release({ ...this.#task("android", config), platform: "android", signing, formats });
+  }
+
+  //* The names the Gradle build read, so a CI that already holds these secrets keeps working.
+  static androidSigning(env: Record<string, string | undefined> = process.env): AndroidSigning {
+    const keystore = env.MYAPP_RELEASE_STORE_FILE;
+    const storePassword = env.MYAPP_RELEASE_STORE_PASSWORD;
+    const alias = env.MYAPP_RELEASE_KEY_ALIAS;
+    const keyPassword = env.MYAPP_RELEASE_KEY_PASSWORD;
+    if (!keystore || !storePassword || !alias) {
+      const missing = Object.entries({
+        MYAPP_RELEASE_STORE_FILE: keystore,
+        MYAPP_RELEASE_STORE_PASSWORD: storePassword,
+        MYAPP_RELEASE_KEY_ALIAS: alias,
+      }).flatMap(([key, value]) => (value ? [] : [key]));
+      throw new Error(
+        `An Android release is signed with the upload key; set ${missing.join(", ")} in the environment.`,
+      );
+    }
+    return { keystore, storePassword, alias, ...(keyPassword ? { keyPassword } : {}) };
+  }
+
+  /** The first page of a dev build, the target's home as a release bundle opens it; the dev server answers the CSR
+   * shell only for `?csr=true`. */
+  startPath(lang: string) {
+    const basePath = this.target.config.basePath?.replace(/^\/+|\/+$/g, "");
+    const params = new URLSearchParams({ csr: "true", akanMobileTarget: this.target.name });
+    if (basePath) params.set("akanMobileBasePath", basePath);
+    if (this.target.config.indexPath) params.set("akanMobileIndexPath", this.target.config.indexPath);
+    const home = [lang, basePath, this.target.config.indexPath]
+      .flatMap((part) => (part ?? "").split("/"))
+      .filter((segment) => segment.length > 0);
+    return `/${home.join("/")}?${params}`;
+  }
+
+  //* A desktop app builds only on its own OS, so the platform is this computer's.
+  static desktopPlatform(host: NodeJS.Platform = process.platform): DesktopPlatform {
+    if (host === "darwin") return "macos";
+    if (host === "win32") return "windows";
+    if (host === "linux") return "linux";
+    throw new Error(`A desktop app builds on macOS, Windows or Linux, not on ${host}.`);
+  }
+
+  static async devices(appDir: string, platform: MobilePlatform) {
+    return await (await NativeApi.load(appDir)).devices({ platform });
+  }
+
+  static async doctor(appDir: string, platforms: NativePlatform[]) {
+    return await (await NativeApi.load(appDir)).doctor({ platforms });
+  }
+}