@akanjs/devkit 3.0.2 → 3.1.0-rc.1

package/mobile/nativeConfig.test.ts

@@ -67,6 +67,30 @@ describe("NativeConfig.build", () => {
     expect(build(undefined)).toBeUndefined();
   });
 
+  test("paints the window before its page with backgroundColor, and names the Windows publisher", () => {
+    const build = (target: Partial<AkanNativeTarget>) =>
+      NativeConfig.build({
+        appPath: "/repo/apps/minimal",
+        target: { ...minimalTarget, ...target },
+        webDir: "/repo/dist/native/minimal/default/web",
+        contributions: [],
+        locales: ["en"],
+        platform: "windows",
+      }).config;
+
+    expect(build({ backgroundColor: "#000000" }).shell).toEqual({ backgroundColor: "#000000" });
+    expect(build({ backgroundColor: { light: "#fafafa", dark: "#111111" } }).shell).toEqual({
+      backgroundColor: "#fafafa",
+      backgroundColorDark: "#111111",
+    });
+    expect(build({}).shell).toBeUndefined();
+    expect(build({ backgroundColor: "#000000", devtools: true }).shell).toEqual({
+      backgroundColor: "#000000",
+      devtools: true,
+    });
+    expect(build({ desktop: { publisher: "Leading Flight" } }).desktop?.publisher).toBe("Leading Flight");
+  });
+
   test("turns the minimal app's push target into the runtime's config, single-instance carrying its link scheme", () => {
     const { config, warnings } = NativeConfig.build({
       appPath: "/repo/apps/minimal",
@@ -208,10 +232,38 @@ describe("NativeConfig.build", () => {
       readyTimeout: 15_000,
     });
     expect(build({ url, publicKey: updatesKey }).updates).toEqual({ url, publicKey: updatesKey });
+    const spare = Buffer.alloc(32, 8).toString("base64");
+    expect(build({ url, publicKeys: [updatesKey, spare] }, "main").updates).toEqual({
+      url,
+      publicKeys: [updatesKey, spare],
+      channel: "main",
+    });
+    const report = { url: "https://cloud.example.com/api/ota/report/abcdefghijklmnop" };
+    expect(build({ url, publicKey: updatesKey, report }, "main").updates).toEqual({
+      url,
+      publicKey: updatesKey,
+      channel: "main",
+      report,
+    });
     expect(build({ url, publicKey: updatesKey }, "main").plugins).toContain("updates");
     expect(build(undefined, "main").plugins).not.toContain("updates");
   });
 
+  test("devtools opens the web inspector of a release build only when a target asks for it", () => {
+    const build = (devtools?: boolean) =>
+      NativeConfig.build({
+        appPath: "/repo/apps/portal",
+        target: { ...adminTarget, ...(devtools === undefined ? {} : { devtools }) },
+        webDir: "/web",
+        contributions: [],
+        locales: ["en"],
+        platform: "android",
+      }).config.shell;
+    expect(build(true)).toEqual({ devtools: true });
+    expect(build(false)).toBeUndefined();
+    expect(build()).toBeUndefined();
+  });
+
   test("push, privacy and the icon and splash objects reach the runtime, paths from the app folder", () => {
     const { config } = NativeConfig.build({
       appPath: "/repo/apps/portal",
@@ -342,7 +394,12 @@ describe("NativeConfig.build", () => {
         permissions: [],
         deepLinks: undefined,
         android: { autoplay: true },
-        desktop: { recovery: "reload", window: { fullscreen: true, skipTaskbar: true }, screenCapture: "auto" },
+        desktop: {
+          recovery: "reload",
+          window: { fullscreen: true, skipTaskbar: true },
+          screenCapture: "auto",
+          webview2: "standalone",
+        },
       },
       webDir: path.join(root, "web"),
       contributions: [],
@@ -355,6 +412,7 @@ describe("NativeConfig.build", () => {
       recovery: "reload",
       window: { fullscreen: true, skipTaskbar: true },
       screenCapture: "auto",
+      webview2: "standalone",
       bin: root,
     });
     expect(config.android).toEqual({ debugAppIdSuffix: ".debug", autoplay: true });

package/mobile/nativeConfig.ts

@@ -175,11 +175,19 @@ export class NativeConfig {
     const desktop = NativeConfig.#compact<NonNullable<AkanNativeConfig["desktop"]>>({
       recovery: target.desktop?.recovery,
       screenCapture: target.desktop?.screenCapture,
+      webview2: target.desktop?.webview2,
+      publisher: target.desktop?.publisher,
       window: NativeConfig.#compact({ ...target.desktop?.window }),
       server: desktopServer,
       bin: desktopBin,
       dmg: NativeConfig.#dmg(target.desktop?.dmg, abs),
     });
+    const background = target.backgroundColor;
+    const shell = NativeConfig.#compact<NonNullable<AkanNativeConfig["shell"]>>({
+      backgroundColor: typeof background === "string" ? background : background?.light,
+      backgroundColorDark: typeof background === "string" ? undefined : background?.dark,
+      devtools: target.devtools ? true : undefined,
+    });
     const config: AkanNativeConfig = {
       app: {
         id: resolveAppId(target.appId, platform),
@@ -223,6 +231,7 @@ export class NativeConfig {
       ...(desktop ? { desktop } : {}),
       ...(target.icon ? { icon: NativeConfig.#icon(target.icon, abs) } : {}),
       ...(target.splash ? { splash: NativeConfig.#splash(target.splash, abs) } : {}),
+      ...(shell ? { shell } : {}),
     };
     return { config, warnings };
   }
@@ -252,10 +261,11 @@ export class NativeConfig {
     };
   }
 
-  //? akanConfig refuses a target whose merged updates lack url or publicKey; the type still has them optional.
+  //? akanConfig refuses a target whose merged updates lack url or a key; the type still has them optional.
   static #updates(target: AkanNativeTarget, env?: NativeEnv): NonNullable<AkanNativeConfig["updates"]> | undefined {
-    const { url, publicKey, channel = env, ...rest } = target.updates ?? {};
-    return url && publicKey ? { ...rest, url, publicKey, ...(channel ? { channel } : {}) } : undefined;
+    const { url, publicKey, publicKeys, channel = env, ...rest } = target.updates ?? {};
+    const keys = publicKeys ? { publicKeys: [...publicKeys] } : publicKey ? { publicKey } : null;
+    return url && keys ? { ...rest, url, ...keys, ...(channel ? { channel } : {}) } : undefined;
   }
 
   /** Letters, digits, `.`, `_` and `-` only; the folder name of an akan app already is one almost always. */

package/mobile/serverBundleSecrets.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { ServerBundleSecrets } from "./serverBundleSecrets";
+
+const makeTempRoot = tempDirs("akan-devkit-server-bundle-secrets-");
+
+const workspace = async () => {
+  const root = await makeTempRoot();
+  await write(
+    path.join(root, "libs/util/env/env.server.testing.ts"),
+    `export const env = { hostname: "lib-host", security: { jwtSecret: "lib-jwt-0123456789" }, iapVerify: { apple: "0f9e8d7c6b5a49382716abcdef012345", google: { type: "service_account", private_key: "-----BEGIN PRIVATE KEY-----\\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7\\n-----END PRIVATE KEY-----\\n" } } };\n`,
+  );
+  await write(path.join(root, "libs/util/env/env.server.type.ts"), "export type Env = object;\n");
+  await write(
+    path.join(root, "apps/demo/env/env.server.main.ts"),
+    'export const env = { mailer: { auth: { user: "ops", pass: "main-mail-pass" } } };\n',
+  );
+  const bundle = path.join(root, "bundle");
+  return { root, appDir: path.join(root, "apps/demo"), bundle };
+};
+
+describe("ServerBundleSecrets", () => {
+  test("passes a bundle that holds none of the workspace's secret values, constants of a credential block aside", async () => {
+    const { root, appDir, bundle } = await workspace();
+    await write(path.join(bundle, "server.js"), 'const t = "service_account"; const host = "lib-host";\n');
+    await write(path.join(bundle, "node_modules/leaky/index.js"), 'const k = "lib-jwt-0123456789";\n');
+    expect(await new ServerBundleSecrets(root, appDir).assertClean(bundle)).toEqual([]);
+  });
+
+  test("refuses one that does, naming the file, the env file and the key path and never the value", async () => {
+    const { root, appDir, bundle } = await workspace();
+    await write(
+      path.join(bundle, "chunk-a.js"),
+      'const e = { pass: "main-mail-pass", apple: "0f9e8d7c6b5a49382716abcdef012345" };\n',
+    );
+    await write(
+      path.join(bundle, "chunk-b.js"),
+      'const pem = "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7";\n',
+    );
+    const error = await new ServerBundleSecrets(root, appDir).assertClean(bundle).catch((e: Error) => e);
+    expect(error).toBeInstanceOf(Error);
+    const message = (error as Error).message;
+    expect(message).toContain("chunk-a.js holds apps/demo/env/env.server.main.ts mailer.auth.pass");
+    expect(message).toContain("chunk-a.js holds libs/util/env/env.server.testing.ts iapVerify.apple");
+    expect(message).toContain("chunk-b.js holds libs/util/env/env.server.testing.ts iapVerify.google.private_key");
+    for (const secret of ["main-mail-pass", "0f9e8d7c", "MIIEvQ"]) expect(message).not.toContain(secret);
+  });
+
+  test("names an env file it could not evaluate instead of passing it silently", async () => {
+    const { root, appDir, bundle } = await workspace();
+    await write(
+      path.join(appDir, "env/env.server.develop.ts"),
+      'import { gone } from "./missing";\nexport const env = gone;\n',
+    );
+    await write(path.join(bundle, "server.js"), "\n");
+    expect(await new ServerBundleSecrets(root, appDir).assertClean(bundle)).toEqual([
+      "apps/demo/env/env.server.develop.ts",
+    ]);
+  });
+});

package/mobile/serverBundleSecrets.ts

@@ -0,0 +1,85 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { ServerEnvProfile } from "../transforms/serverEnvProfile";
+
+interface SecretValue {
+  file: string;
+  path: string;
+  value: string;
+}
+
+//* A signed app leaves the building, and a notarized one goes to Apple first: before either, every secret value the
+//* workspace's server env files hold is looked for in the server the app carries, whatever put it there.
+export class ServerBundleSecrets {
+  static readonly #largestFile = 64 * 1024 * 1024;
+
+  constructor(
+    readonly workspaceRoot: string,
+    readonly appDir: string,
+  ) {}
+
+  /** The app's `env/env.server.<name>.ts` and every lib's, but the type and example files. */
+  async envFiles(): Promise<string[]> {
+    const libsDir = path.join(this.workspaceRoot, "libs");
+    const libs = await readdir(libsDir).catch(() => [] as string[]);
+    const dirs = [path.join(this.appDir, "env"), ...libs.map((lib) => path.join(libsDir, lib, "env"))];
+    const files = await Promise.all(
+      dirs.map(async (dir) =>
+        (await readdir(dir).catch(() => [] as string[]))
+          .filter((name) => /^env\.server\.[A-Za-z0-9.-]+\.ts$/.test(name) && !/\.(type|example)\.ts$/.test(name))
+          .map((name) => path.join(dir, name)),
+      ),
+    );
+    return files.flat();
+  }
+
+  /** Refuses, naming files and key paths and never a value, when the bundle holds one; returns the env files it could not read. */
+  async assertClean(bundleDir: string): Promise<string[]> {
+    const unread: string[] = [];
+    const secrets: SecretValue[] = [];
+    for (const file of await this.envFiles()) {
+      try {
+        const value = await ServerEnvProfile.evaluate(file, path.dirname(path.dirname(file)));
+        secrets.push(...ServerEnvProfile.secretValues(value).map((secret) => ({ file, ...secret })));
+      } catch {
+        unread.push(ServerBundleSecrets.#relative(this.workspaceRoot, file));
+      }
+    }
+    const found: string[] = [];
+    for (const bundled of await ServerBundleSecrets.#files(bundleDir)) {
+      const text = await readFile(bundled, "latin1");
+      for (const secret of secrets)
+        if (ServerBundleSecrets.#needles(secret.value).some((needle) => text.includes(needle)))
+          found.push(
+            `${ServerBundleSecrets.#relative(bundleDir, bundled)} holds ${ServerBundleSecrets.#relative(this.workspaceRoot, secret.file)} ${secret.path}`,
+          );
+    }
+    if (found.length)
+      throw new Error(
+        `The server this app carries holds secret values from the workspace's env files, so it is not signed or sent anywhere:\n  ${[...new Set(found)].join("\n  ")}\nBuild its server with a profile (native.desktop.server.profile), whose bundle carries no secret.`,
+      );
+    return unread;
+  }
+
+  //? A multi-line key sits in a bundle as a JS string, escaped; one long line of it is enough to recognise.
+  static #needles(value: string): string[] {
+    const escaped = JSON.stringify(value).slice(1, -1);
+    const line = value.split(/\r?\n/).find((part) => part.length >= 32);
+    return [...new Set([value, escaped, ...(line ? [line] : [])])];
+  }
+
+  static #relative(from: string, to: string) {
+    return path.relative(from, to).split(path.sep).join("/");
+  }
+
+  static async #files(dir: string): Promise<string[]> {
+    const files: string[] = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== "node_modules") files.push(...(await ServerBundleSecrets.#files(file)));
+      } else if (entry.isFile() && (await stat(file)).size <= ServerBundleSecrets.#largestFile) files.push(file);
+    }
+    return files;
+  }
+}

package/mobile/updateUploader.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { type UpdateBucket, UpdateUploader } from "./updateUploader";
+
+const fakeBucket = (held: string[] = []) => {
+  const writes: { key: string; type?: string }[] = [];
+  const bucket: UpdateBucket = {
+    exists: async (key) => held.includes(key),
+    write: async (key, _data, options) => {
+      writes.push({ key, ...(options?.type ? { type: options.type } : {}) });
+      return 0;
+    },
+  };
+  return { bucket, writes };
+};
+
+describe("UpdateUploader", () => {
+  test("reads s3://bucket/prefix and refuses anything else", () => {
+    expect(UpdateUploader.parseTarget("s3://releases/dcms/kiosk/")).toEqual({
+      bucket: "releases",
+      prefix: "dcms/kiosk",
+    });
+    expect(UpdateUploader.parseTarget("s3://releases")).toEqual({ bucket: "releases", prefix: "" });
+    expect(() => UpdateUploader.parseTarget("https://releases.example/dcms")).toThrow("s3://<bucket>/<prefix>");
+  });
+
+  test("uploads what the bucket lacks first, then each signature before its manifest", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "akan-update-upload-"));
+    try {
+      await mkdir(path.join(dir, "windows-x64", "files"), { recursive: true });
+      for (const file of ["windows-x64/files/2000-aa.tar.gz", "windows-x64/files/1000-bb.tar.gz"])
+        await writeFile(path.join(dir, file), "tar");
+      for (const file of ["windows-x64/main.json", "windows-x64/main.json.sig", "windows-x64/main.json.tmp"])
+        await writeFile(path.join(dir, file), "{}");
+      const { bucket, writes } = fakeBucket(["dcms/windows-x64/files/1000-bb.tar.gz"]);
+
+      expect(await new UpdateUploader(bucket, "dcms").upload(dir)).toEqual({ uploaded: 3, skipped: 1 });
+      expect(writes).toEqual([
+        { key: "dcms/windows-x64/files/2000-aa.tar.gz" },
+        { key: "dcms/windows-x64/main.json.sig", type: "text/plain" },
+        { key: "dcms/windows-x64/main.json", type: "application/json" },
+      ]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/mobile/updateUploader.ts

@@ -0,0 +1,71 @@
+import path from "node:path";
+
+/** What the uploader needs of an S3 client; Bun.S3Client is one. */
+export interface UpdateBucket {
+  exists(key: string): Promise<boolean>;
+  write(key: string, data: Blob, options?: { type?: string }): Promise<number>;
+}
+
+export interface UpdateUploadResult {
+  uploaded: number;
+  skipped: number;
+}
+
+//* A manifest names files that must already be there, so they go first and the manifests last, each signature before
+//* its manifest as `publish-update` writes them. A release file never changes once published (its name carries its
+//* hash), so one the bucket holds is skipped; a manifest is always written.
+export class UpdateUploader {
+  static readonly #manifest = /\.json(?:\.sig)?$/;
+
+  /** `s3://bucket/prefix`: the credentials and endpoint come from S3_* (or AWS_*) in the environment. */
+  static parseTarget(target: string): { bucket: string; prefix: string } {
+    const match = /^s3:\/\/([^/]+)\/?(.*)$/.exec(target.trim());
+    if (!match?.[1]) throw new Error(`--upload takes s3://<bucket>/<prefix>, not ${JSON.stringify(target)}.`);
+    return { bucket: match[1], prefix: (match[2] ?? "").replace(/\/+$/, "") };
+  }
+
+  static order(files: string[]): { releases: string[]; manifests: string[] } {
+    const manifests = files.filter((file) => UpdateUploader.#manifest.test(file));
+    return {
+      releases: files.filter((file) => !UpdateUploader.#manifest.test(file)).sort((a, b) => a.localeCompare(b)),
+      manifests: manifests.sort(
+        (a, b) => Number(a.endsWith(".json")) - Number(b.endsWith(".json")) || a.localeCompare(b),
+      ),
+    };
+  }
+
+  constructor(
+    readonly bucket: UpdateBucket,
+    readonly prefix: string,
+  ) {}
+
+  static forTarget(target: string): UpdateUploader {
+    const { bucket, prefix } = UpdateUploader.parseTarget(target);
+    return new UpdateUploader(new Bun.S3Client({ bucket }), prefix);
+  }
+
+  async upload(dir: string): Promise<UpdateUploadResult> {
+    const files: string[] = [];
+    for await (const file of new Bun.Glob("**/*").scan({ cwd: dir, onlyFiles: true })) {
+      if (!file.endsWith(".tmp")) files.push(file.split(path.sep).join("/"));
+    }
+    const { releases, manifests } = UpdateUploader.order(files);
+    const keyOf = (file: string) => (this.prefix ? `${this.prefix}/${file}` : file);
+    let uploaded = 0;
+    let skipped = 0;
+    for (const file of releases) {
+      if (await this.bucket.exists(keyOf(file))) {
+        skipped++;
+        continue;
+      }
+      await this.bucket.write(keyOf(file), Bun.file(path.join(dir, file)));
+      uploaded++;
+    }
+    for (const file of manifests) {
+      const type = file.endsWith(".json") ? "application/json" : "text/plain";
+      await this.bucket.write(keyOf(file), Bun.file(path.join(dir, file)), { type });
+      uploaded++;
+    }
+    return { uploaded, skipped };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.2",
+  "version": "3.1.0-rc.1",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -33,6 +33,7 @@
     "./frontendBuild": "./frontendBuild/index.ts",
     "./incrementalBuilder": "./incrementalBuilder/index.ts",
     "./mobile": "./mobile/index.ts",
+    "./pipeline": "./pipeline/index.ts",
     "./transforms": "./transforms/index.ts",
     "./workflow": "./workflow/index.ts",
     "./*.ts": "./*.ts",
@@ -47,7 +48,7 @@
     "@earendil-works/pi-tui": "0.86.1",
     "@inquirer/prompts": "^8.4.3",
     "@tailwindcss/node": "^4.3.0",
-    "akanjs": "3.0.2",
+    "akanjs": "3.1.0-rc.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",