@akanjs/devkit 3.0.2 → 3.1.0-rc.1

package/incrementalBuilder/buildBatchProtocol.ts

@@ -3,8 +3,9 @@ import type { BaseBuildArtifact, CssPayload, HmrTrace, PagesBundlePayload } from
 
 export type OptimizedFonts = Awaited<ReturnType<FontOptimizer["optimize"]>>;
 
-// `base` is the boot build: it always runs alone, before the builder can serve anything.
-export type BuildBatchNeed = "base" | "pages" | "css" | "csr" | "ssr";
+// `base` is the boot build: it always runs alone, before the builder can serve anything. `shell` is the single-file
+// CSR build an MCP Apps view needs under the dev CSR registry, made on request and reported to no tab.
+export type BuildBatchNeed = "base" | "pages" | "css" | "csr" | "ssr" | "shell";
 
 // JSON only: the worker is spawned per batch and receives this in its argv.
 export interface BuildBatchRequest {

package/incrementalBuilder/incrementalBuilder.proc.test.ts

@@ -82,6 +82,102 @@ process.send({ type: "build-batch-result", data: { generation, errors: {}, artif
     expect(log).toContain(reason);
   }, 30_000);
 
+  test("builds a view's shell once on request, answers with its failure, and reports it to no tab", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    // A stand-in batch: boots, and fails a shell batch by naming the needs it was handed.
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation, needs } = JSON.parse(process.argv[2]);
+const errors = needs.includes("base") ? {} : { shell: "handed " + needs.join(",") };
+process.send({ type: "build-batch-result", data: { generation, errors, artifact: {}, optimizedFonts: { css: "", files: [] } } });
+`,
+    );
+    await writeText(path.join(appDir, "page/_index.tsx"), "export default () => null;\n");
+    const messages: BuilderMessage[] = [];
+    const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        AKAN_WORKSPACE_ROOT: root,
+        AKAN_PUBLIC_APP_NAME: "demo",
+        AKAN_PUBLIC_REPO_NAME: "repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+        AKAN_PUBLIC_ENV: "local",
+        AKAN_WATCH: "0",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    try {
+      await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
+      proc.send({ type: "build-csr", id: 7, reason: "mcp app view", shell: true } satisfies BuilderMessage);
+      await until(proc, "build-csr-res", () => messages.some((message) => message.type === "build-csr-res"));
+    } finally {
+      proc.kill();
+      await proc.exited;
+    }
+    expect(messages.find((message) => message.type === "build-csr-res")).toEqual({
+      type: "build-csr-res",
+      id: 7,
+      ok: false,
+      error: "handed shell",
+    });
+    expect(messages.some((message) => message.type === "build-status")).toBe(false);
+  }, 30_000);
+
+  test("answers a second shell request in the same generation without building again", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    const ledger = path.join(root, "batches.log");
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation, needs } = JSON.parse(process.argv[2]);
+require("node:fs").appendFileSync(${JSON.stringify(ledger)}, needs.join(",") + "\\n");
+process.send({ type: "build-batch-result", data: { generation, errors: {}, artifact: {}, optimizedFonts: { css: "", files: [] } } });
+`,
+    );
+    await writeText(path.join(appDir, "page/_index.tsx"), "export default () => null;\n");
+    const messages: BuilderMessage[] = [];
+    const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        AKAN_WORKSPACE_ROOT: root,
+        AKAN_PUBLIC_APP_NAME: "demo",
+        AKAN_PUBLIC_REPO_NAME: "repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+        AKAN_PUBLIC_ENV: "local",
+        AKAN_WATCH: "0",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    const answers = () => messages.filter((message) => message.type === "build-csr-res");
+    try {
+      await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
+      proc.send({ type: "build-csr", id: 7, reason: "mcp app view", shell: true } satisfies BuilderMessage);
+      await until(proc, "the first build-csr-res", () => answers().length === 1);
+      proc.send({ type: "build-csr", id: 8, reason: "mcp app view", shell: true } satisfies BuilderMessage);
+      await until(proc, "the second build-csr-res", () => answers().length === 2);
+    } finally {
+      proc.kill();
+      await proc.exited;
+    }
+    expect(answers()).toEqual([
+      { type: "build-csr-res", id: 7, ok: true },
+      { type: "build-csr-res", id: 8, ok: true },
+    ]);
+    const batches = (await Bun.file(ledger).text()).trim().split("\n");
+    expect(batches.filter((needs) => needs === "shell")).toHaveLength(1);
+  }, 30_000);
+
   test("a killed boot build is tried again after the crash window, before boot-armed; a route build's check waits likewise", async () => {
     // Inside the checkout so the route's client bundle resolves the framework from its source.
     const { root } = track(await createTempApp("demo", path.join(import.meta.dir, "..", "local")));

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -63,6 +63,7 @@ class IncrementalBuilder {
   #autoImportSync: AutoImportSync;
   #watcher: HmrWatcher | null = null;
   #generation = 0;
+  #shellGeneration: number | null = null;
   #discoveredThrough = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #csrBundler: CsrDevBundler;
@@ -798,7 +799,7 @@ class IncrementalBuilder {
       if (crashedNeeds.includes("ssr")) this.#ssrPatcher?.releaseHandedOver();
       // `base` is not a `BuildPhase` and never comes through here: `#buildBootDeps` throws into the degraded boot.
       for (const need of crashedNeeds)
-        if (need !== "base")
+        if (need !== "base" && need !== "shell")
           this.#sendBuildStatus(need, {
             generation,
             ok: false,
@@ -874,6 +875,10 @@ class IncrementalBuilder {
 
   // On demand: dev serves CSR only via the opt-in `/__csr` and `?csr=true` routes; once built, it rebuilds every save.
   async handleBuildCsr(msg: BuilderCsrReq): Promise<void> {
+    if (msg.shell) {
+      await this.#buildShell(msg);
+      return;
+    }
     //? Armed now, not when the build lands: a save handled meanwhile then patches CSR behind #csrGate instead of skipping.
     this.#beginCsrArm();
     this.#csrActive = true;
@@ -903,6 +908,30 @@ class IncrementalBuilder {
     await armed;
   }
 
+  // Asked on every view read and rebuilt only when a save moved the generation, instead of armed per save: a restarted
+  // builder has no last build to trust, and so rebuilds once on the next read.
+  async #buildShell(msg: BuilderCsrReq): Promise<void> {
+    await this.#workQueue.enqueue("build-shell", async (): Promise<void> => {
+      const generation = this.#generation;
+      let error: string | undefined;
+      if (this.#shellGeneration !== generation)
+        try {
+          const result = await this.#batchRunner.run(
+            await this.#batchRequest({ generation, needs: ["shell"], changedFiles: [] }),
+          );
+          error = result.errors.shell;
+          if (!error) this.#shellGeneration = generation;
+        } catch (err) {
+          error = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
+        }
+      await BuilderChannel.send(
+        error
+          ? { type: "build-csr-res", id: msg.id, ok: false, error }
+          : { type: "build-csr-res", id: msg.id, ok: true },
+      );
+    });
+  }
+
   //? Settled by the last of the arming builds in flight, not by each: two requests that both fail would otherwise leave
   //? CSR on (the second saw the first's optimistic flag as where it started), and the first to finish would let saves
   //? patch CSR first while the second still builds.

package/lint/__fixtures__/no-import-external-library-in-test/bad.tsx

@@ -0,0 +1,6 @@
+import dayjs from "dayjs"; // @flag
+import { z } from "zod"; // @flag
+import fs from "node:fs"; // @ok
+import { Database } from "bun:sqlite"; // @ok
+import { describe } from "bun:test"; // @ok
+import { cnst } from "../cnst"; // @ok

package/lint/__fixtures__/no-import-external-library-in-test/good.tsx

@@ -0,0 +1,6 @@
+import { mkdtemp } from "node:fs/promises"; // @ok
+import { createServer } from "node:net"; // @ok
+import { tmpdir } from "node:os"; // @ok
+import { Database } from "bun:sqlite"; // @ok
+import { describe, expect, test } from "bun:test"; // @ok
+import { fetch } from "../sig"; // @ok

package/lint/no-import-external-library-in-test.grit

@@ -0,0 +1,24 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// A module test still reaches vendors through a lib, but it may use the runtime's own primitives — a temp dir, a
+// socket, sqlite — that a module file leaves to srvkit/.
+JsModuleSource() as $source where {
+  $source <: within JsImport(),
+  not $source <: or {
+    r"\"\..*",
+    r"\"akanjs.*",
+    r"\"@akanjs.*",
+    r"\"@playwright.*",
+    r"\"@apps/.*",
+    r"\"@libs/.*",
+    r"\"@pkgs/.*",
+    r"\"bun:.*",
+    r"\"node:.*",
+    r"\"react.*"
+  },
+  register_diagnostic(
+    span = $source,
+    message = "External libraries should not be imported in a module test. Only internal packages and the runtime's node: and bun: modules are permitted."
+  )
+}

package/mobile/desktopServerStage.test.ts

@@ -46,6 +46,12 @@ describe("DesktopServerStage", () => {
     });
     expect(env.PORT).toBeUndefined();
     expect(env.AKAN_LOG_TO_FILE).toBeUndefined();
+    expect(env.AKAN_MODULES).toBeUndefined();
+    expect(DesktopServerStage.env(appConfig(), "main", { modules: ["@edge", "edgeAgent"] }).AKAN_MODULES).toBe(
+      "@edge,edgeAgent",
+    );
+    const withEnv = DesktopServerStage.env(appConfig(), "main", { env: { CLOUD_ORIGIN: "https://cloud.example" } });
+    expect(withEnv).toMatchObject({ CLOUD_ORIGIN: "https://cloud.example", AKAN_PUBLIC_OPERATION_MODE: "edge" });
   });
 
   test("installs what the image does, minus the RSC renderer and the other modes' drivers", () => {

package/mobile/desktopServerStage.ts

@@ -10,6 +10,16 @@ export interface DesktopServerBundle {
   dir: string;
   entry: string;
   env: Record<string, string>;
+  restart?: "forever" | number;
+  watchdog?: { intervalMs: number; failures: number };
+}
+
+/** How the targets that carry one build's server have it run (`desktop.server`, normalized). */
+export interface DesktopServerRun {
+  modules?: string[];
+  env?: Record<string, string>;
+  restart?: "forever" | number;
+  watchdog?: { intervalMs: number; failures: number };
 }
 
 //* A desktop app's carried server is the backend `akan build` wrote into dist, installed on its own as the image's
@@ -44,11 +54,16 @@ export class DesktopServerStage {
       );
   }
 
-  static env(config: AkanAppConfig, environment: NativeEnv): Record<string, string> {
+  static env(
+    config: AkanAppConfig,
+    environment: NativeEnv,
+    { modules = [], env = {} }: Pick<DesktopServerRun, "modules" | "env"> = {},
+  ): 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,
+      ...env,
       //? 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",
@@ -59,6 +74,7 @@ export class DesktopServerStage {
       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",
+      ...(modules.length ? { AKAN_MODULES: modules.join(",") } : {}),
     };
   }
 
@@ -162,7 +178,7 @@ export class DesktopServerStage {
   }
 
   //? Copies the build beside what `install` put in the stage, so it runs after both.
-  async prepare(environment: NativeEnv): Promise<DesktopServerBundle> {
+  async prepare(environment: NativeEnv, run: DesktopServerRun = {}): Promise<DesktopServerBundle> {
     const config = await this.app.getConfig();
     const dist = this.app.dist.cwdPath;
     await mkdir(this.dir, { recursive: true });
@@ -173,6 +189,12 @@ export class DesktopServerStage {
     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) };
+    return {
+      dir: this.dir,
+      entry: "main.js",
+      env: DesktopServerStage.env(config, environment, run),
+      ...(run.restart !== undefined ? { restart: run.restart } : {}),
+      ...(run.watchdog ? { watchdog: run.watchdog } : {}),
+    };
   }
 }

package/mobile/index.ts

@@ -7,4 +7,5 @@ export * from "./nativeConfig";
 export * from "./nativePluginFolders";
 export * from "./nativeWebDir";
 export * from "./placeholderAppId";
+export * from "./updateUploader";
 export * from "./usageDescriptions";

package/mobile/nativeApp.test.ts

@@ -58,6 +58,7 @@ describe("NativeApp", () => {
         ({
           config: {},
           api: {
+            requestedDistribution: () => ({ notice: null, unused: [] }),
             build: async ({ env }: { env?: Record<string, string> }) => {
               seen = env;
               return { artifacts: [], warnings: [] };
@@ -231,3 +232,36 @@ describe("NativeApp", () => {
     );
   });
 });
+
+describe("a pack read back from its folder", () => {
+  test("takes the folder as the pack's place, and refuses what is not a takeable pack", async () => {
+    const root = await makeTempRoot();
+    const pack = {
+      schema: 1,
+      app: "lu",
+      target: "default",
+      platform: "android",
+      env: "main",
+      channel: "main",
+      appId: "com.lu",
+      appVersion: "1.0.0",
+      nativeApi: "0123456789abcdef",
+      webHash: "f".repeat(64),
+      files: 1,
+      size: 13,
+      out: "/elsewhere/updates/android",
+    };
+    const moved = path.join(root, "moved");
+    await writeText(path.join(moved, "pack.json"), JSON.stringify(pack));
+    expect(await NativeApp.readPack(moved)).toEqual({ ...pack, out: moved } as never);
+
+    await expect(NativeApp.readPack(path.join(root, "empty"))).rejects.toThrow("holds no pack.json");
+    const later = path.join(root, "later");
+    await writeText(path.join(later, "pack.json"), JSON.stringify({ ...pack, schema: 2 }));
+    await expect(NativeApp.readPack(later)).rejects.toThrow("schema 2");
+    const refused = path.join(root, "refused");
+    const compat = { against: "store/bundle.json", compatible: false, problems: ["deepLinks differ"] };
+    await writeText(path.join(refused, "pack.json"), JSON.stringify({ ...pack, compat }));
+    expect((await NativeApp.readPack(refused)).compat).toEqual(compat);
+  });
+});

package/mobile/nativeApp.ts

@@ -1,3 +1,4 @@
+import { rm } from "node:fs/promises";
 import path from "node:path";
 import type { AkanNativeConfig } from "@akanjs/native/config";
 import type { NativeEnv } from "akanjs";
@@ -17,6 +18,7 @@ import { NativeAppLine, type NativeAppLineRead } from "./nativeAppLine";
 import { NativeConfig } from "./nativeConfig";
 import { NativePluginFolders } from "./nativePluginFolders";
 import { NativeWebDir } from "./nativeWebDir";
+import { ServerBundleSecrets } from "./serverBundleSecrets";
 
 type TaskOptions = Parameters<NativeBuildApiModule["build"]>[0];
 type DeviceSelector = NonNullable<Parameters<NativeBuildApiModule["run"]>[0]["device"]>;
@@ -42,6 +44,10 @@ export interface NativeBuildOptions {
   installer?: boolean;
   /** The CPU the desktop app runs on, of the same OS; a macOS app is arm64 only. Default this computer's. */
   arch?: DesktopArch;
+  /** Sign with the identity AKAN_NATIVE_MACOS_* / AKAN_NATIVE_WINDOWS_* names; the env alone signs nothing. */
+  sign?: boolean;
+  /** macOS: upload the signed app to Apple's notary service. */
+  notarize?: boolean;
 }
 
 export interface NativeDevOptions extends NativeRunOptions {
@@ -50,6 +56,25 @@ export interface NativeDevOptions extends NativeRunOptions {
   lang: string;
 }
 
+/** `<out>/pack.json`: what a signer needs of a pack, read instead of the log. */
+export interface NativeUpdatePack {
+  schema: 1;
+  app: string;
+  target: string;
+  platform: MobilePlatform;
+  env: NativeEnv;
+  channel: string;
+  appId: string;
+  appVersion: string;
+  nativeApi: string;
+  /** bundle.json `web.hash`: the web files as served, the part of a bundle id that names its content. */
+  webHash: string;
+  files: number;
+  size: number;
+  out: string;
+  compat?: { against: string; compatible: boolean; problems: string[] };
+}
+
 /** One native 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 {
@@ -194,32 +219,19 @@ export class NativeApp {
 
   async build(
     platform: NativePlatform,
-    { profile = "release", server, installer = false, arch }: NativeBuildOptions = {},
+    { profile = "release", server, installer = false, arch, sign = false, notarize = false }: NativeBuildOptions = {},
   ) {
     NativeApp.#assertServerPlatform(platform, server);
     NativeApp.assertInstaller(platform, installer);
     await this.assembleWeb(platform);
     const { api, config } = await this.prepare(platform, server, arch);
+    const distribution = await this.#distribution(api, platform, profile, { sign, notarize }, server);
     return await api.build({
       ...this.#task(platform, config, { env: await this.#runtimeEnv(server) }),
       profile,
       ...(arch ? { arch } : {}),
-      ...(platform === "windows"
-        ? {
-            windows: {
-              ...(installer ? { installer } : {}),
-              ...(profile === "release" ? NativeApp.#windowsSigning(api) : {}),
-            },
-          }
-        : {}),
-      ...(platform === "macos"
-        ? {
-            macos: {
-              ...(profile === "release" ? api.macosDistributionFromEnv(process.env) : {}),
-              ...(installer ? { dmg: true } : {}),
-            },
-          }
-        : {}),
+      ...(platform === "windows" ? { windows: { ...(installer ? { installer } : {}), ...distribution.windows } } : {}),
+      ...(platform === "macos" ? { macos: { ...distribution.macos, ...(installer ? { dmg: true } : {}) } } : {}),
       ...(platform === "linux" && installer ? { linux: { appImage: true } } : {}),
     });
   }
@@ -306,30 +318,64 @@ export class NativeApp {
   /** A signed release installed apps take through the updates plugin, from a release build of this bundle. */
   async publishUpdate(
     platform: NativePlatform,
-    { channel, server }: { channel?: string; server?: DesktopServerBundle } = {},
+    {
+      channel,
+      server,
+      arch,
+      sign = false,
+      notarize = false,
+    }: { channel?: string; server?: DesktopServerBundle; arch?: DesktopArch; sign?: boolean; notarize?: boolean } = {},
   ) {
     NativeApp.#assertServerPlatform(platform, server);
     this.#assertUpdates();
     await this.assembleWeb(platform);
-    const { api, config } = await this.prepare(platform, server);
+    const { api, config } = await this.prepare(platform, server, arch);
+    //? The updater keeps the installed app's signature, so a release is signed as the downloaded app was.
+    const distribution = await this.#distribution(api, platform, "release", { sign, notarize }, server);
     return await api.publishUpdate({
       ...this.#task(platform, config, { env: await this.#runtimeEnv(server) }),
       platform,
       out: this.updatesDir,
       ...(channel ? { channel } : {}),
-      //? The updater keeps the installed app's signature, so a release is signed as the downloaded app was.
-      ...(platform === "macos" ? { macos: api.macosDistributionFromEnv(process.env) } : {}),
-      ...(platform === "windows" ? { windows: NativeApp.#windowsSigning(api) } : {}),
+      ...(arch ? { arch } : {}),
+      ...(distribution.macos ? { macos: distribution.macos } : {}),
+      ...(distribution.windows ? { windows: distribution.windows } : {}),
     });
   }
 
+  //* Only what the command asked for is signed or uploaded; a signed app's server is searched for the workspace's
+  //* secret values first, and the one line naming the identity and the service comes right before the build.
+  async #distribution(
+    api: NativeBuildApiModule,
+    platform: NativePlatform,
+    profile: "debug" | "release",
+    request: { sign: boolean; notarize: boolean },
+    server: DesktopServerBundle | undefined,
+  ) {
+    const distribution = api.requestedDistribution(platform, profile, request);
+    if (!distribution.notice) {
+      if (distribution.unused.length && (platform === "macos" || platform === "windows"))
+        this.app.logger.info(`${distribution.unused.join(", ")} set: this build is not signed without --sign.`);
+      return distribution;
+    }
+    if (server) {
+      const unread = await new ServerBundleSecrets(this.app.workspace.workspaceRoot, this.app.cwdPath).assertClean(
+        server.dir,
+      );
+      if (unread.length)
+        this.app.logger.warn(`Not searched for secrets, as they could not be evaluated: ${unread.join(", ")}.`);
+    }
+    this.app.logger.warn(distribution.notice);
+    return distribution;
+  }
+
   /**
    * What publishing refuses once the release is built: no updates settings, an invalid config, no signing key or
    * another app's, and a desktop release whose server presence is not its channel's previous release's.
    */
   async assertPublishable(
     platform: NativePlatform,
-    { channel, server = false }: { channel?: string; server?: boolean } = {},
+    { channel, server = false, arch }: { channel?: string; server?: boolean; arch?: DesktopArch } = {},
   ) {
     this.#assertUpdates();
     const [api, { config }] = await Promise.all([
@@ -345,6 +391,7 @@ export class NativeApp {
         out: this.updatesDir,
         server,
         ...(channel ? { channel } : {}),
+        ...(arch ? { arch } : {}),
       });
     } catch (error) {
       throw new Error(
@@ -384,7 +431,7 @@ export class NativeApp {
     });
   }
 
-  /** An unsigned OTA update of this target's web bundle for `platform`, and the channel its binary follows. */
+  /** An unsigned OTA update of this target's web bundle for `platform`, and the record `pack.json` keeps of it. */
   async packUpdate(platform: MobilePlatform, { out }: { out?: string } = {}) {
     await this.assembleWeb(platform);
     const { api, config } = await this.prepare(platform);
@@ -392,12 +439,42 @@ export class NativeApp {
       throw new Error(
         `Native target '${this.target.name}' takes no updates: add native.updates: { url, publicKey } to akan.config.ts first.`,
       );
-    const packed = await api.packUpdate({
-      ...this.#task(platform, config),
+    const dir = path.resolve(out ?? path.join(this.updatesDir, platform));
+    //? A pack that fails must not leave the previous pack's record behind for whoever reads the exit code.
+    await Promise.all(["pack.json", "compat.json"].map((name) => rm(path.join(dir, name), { force: true })));
+    const packed = await api.packUpdate({ ...this.#task(platform, config), platform, out: dir });
+    const channel = config.updates.channel ?? "production";
+    const bundle = (await Bun.file(path.join(packed.out, "bundle.json")).json()) as { web: { hash: string } };
+    const pack: NativeUpdatePack = {
+      schema: 1,
+      app: this.app.name,
+      target: this.target.name,
       platform,
-      out: out ?? path.join(this.updatesDir, platform),
-    });
-    return { ...packed, channel: config.updates.channel ?? "production" };
+      env: this.env ?? "main",
+      channel,
+      appId: packed.manifest.app,
+      appVersion: packed.manifest.version,
+      nativeApi: packed.manifest.nativeApi ?? "",
+      webHash: bundle.web.hash,
+      files: packed.manifest.files.length,
+      size: packed.manifest.files.reduce((sum, file) => sum + file.size, 0),
+      out: packed.out,
+    };
+    return { ...packed, channel, pack };
+  }
+
+  static async writePack(pack: NativeUpdatePack) {
+    await Bun.write(path.join(pack.out, "pack.json"), `${JSON.stringify(pack, null, 2)}\n`);
+  }
+
+  /** A pack `packUpdate` wrote, read back from its folder wherever it was moved. */
+  static async readPack(dir: string): Promise<NativeUpdatePack> {
+    const file = Bun.file(path.join(dir, "pack.json"));
+    if (!(await file.exists()))
+      throw new Error(`${dir} holds no pack.json: give the folder \`akan pack-update\` wrote.`);
+    const pack = (await file.json()) as NativeUpdatePack;
+    if (pack.schema !== 1) throw new Error(`${dir}/pack.json is schema ${pack.schema}, and this akan reads schema 1.`);
+    return { ...pack, out: path.resolve(dir) };
   }
 
   static async compareBundles(appDir: string, shipped: string, bundle: string) {
@@ -437,11 +514,6 @@ export class NativeApp {
     return `/${home.join("/")}?${params}`;
   }
 
-  static #windowsSigning(api: NativeBuildApiModule) {
-    const signing = api.windowsSigningFromEnv(process.env);
-    return signing ? { signing } : {};
-  }
-
   //* `installer` is the file a person downloads: a setup program on Windows, a disk image on macOS, an AppImage on Linux.
   static assertInstaller(platform: NativePlatform, installer: boolean) {
     if (installer && (platform === "ios" || platform === "android"))