@akanjs/devkit 3.1.0-rc.0 → 3.1.0-rc.10

package/cloud/cloudHttpError.ts

@@ -0,0 +1,54 @@
+import { isRecord } from "akanjs/common";
+
+//? The body is kept whole for reading the server's answer; only the message is cut, as it lands in a terminal.
+export class CloudHttpError extends Error {
+  static readonly #errKey = /^[\w$-]+\.error\.[\w$-]+$/;
+
+  override readonly name = "CloudHttpError";
+
+  constructor(
+    readonly status: number,
+    readonly statusText: string,
+    readonly url: string,
+    readonly body: string,
+    readonly headers: Headers = new Headers(),
+  ) {
+    super(`${status} ${statusText} from ${url}: ${body.slice(0, 200)}`);
+  }
+
+  static async of(response: Response, url: string) {
+    return new CloudHttpError(response.status, response.statusText, url, await response.text(), response.headers);
+  }
+
+  static statusOf(error: unknown) {
+    return error instanceof CloudHttpError ? error.status : null;
+  }
+
+  /** The `error` of a JSON refusal: an Err key from the server itself, or whatever a proxy put there. */
+  get error(): string | null {
+    try {
+      const parsed: unknown = JSON.parse(this.body);
+      return isRecord(parsed) && typeof parsed.error === "string" ? parsed.error : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** `error` when it is an Err key (`release.error.uploadCommitInProgress`), which only the server's own answer names. */
+  get errKey(): string | null {
+    const { error } = this;
+    return error && CloudHttpError.#errKey.test(error) ? error : null;
+  }
+
+  get retryAfterMs(): number | null {
+    return CloudHttpError.retryAfterMs(this.headers.get("retry-after"));
+  }
+
+  /** Retry-After in milliseconds from now: whole seconds, or an HTTP date. */
+  static retryAfterMs(header: string | null): number | null {
+    const value = header?.trim() ?? "";
+    if (!value) return null;
+    const ms = /^\d+$/.test(value) ? Number(value) * 1000 : Date.parse(value) - Date.now();
+    return Number.isFinite(ms) ? Math.max(0, ms) : null;
+  }
+}

package/cloud/cloudUpdates.ts

@@ -0,0 +1,138 @@
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { NativeEnv } from "../akanConfig";
+import type { App } from "../commandDecorators";
+import { ExitCodeError } from "../commandDecorators/exitCodeError";
+import { type MobilePlatform, resolveMobileTargets } from "../mobile/mobileTarget";
+import { NativeApp } from "../mobile/nativeApp";
+import { NativePublicEnv } from "../mobile/nativePublicEnv";
+import { type NativeUpdatePack, UpdatePackFolder } from "../mobile/updatePackFolder";
+import { type AppBinaryDistribution, CloudApi } from "./cloudApi";
+import { UpdatePackUpload } from "./updatePackUpload";
+
+//* A phone app's over-the-air updates through an Akan Cloud project, which keeps the signing key: a pack uploaded for
+//* it to sign and publish, and the store build a pack of the same commit is embedded in.
+export class CloudUpdates {
+  constructor(
+    readonly cloudApi: CloudApi,
+    readonly devProjectId: string,
+  ) {}
+
+  /** The bundle.json the target's last `akan release-<platform>` wrote. */
+  static async storeBundlePath(app: App, target: string | undefined, platform: MobilePlatform) {
+    const [mobileTarget] = await resolveMobileTargets(app, target);
+    if (!mobileTarget) throw new Error(`Native target '${target}' was not found.`);
+    return path.join(new NativeApp(app, mobileTarget).outDir(platform), UpdatePackFolder.bundleFile);
+  }
+
+  /** A pack `akan pack-update` wrote, refused unless it is this app's and agrees with every flag given beside it. */
+  static async readPack(
+    app: App,
+    dir: string,
+    {
+      platform,
+      target,
+      env,
+      allowLocalRelease,
+    }: { platform: MobilePlatform | null; target: string | null; env: NativeEnv | null; allowLocalRelease: boolean },
+  ) {
+    const pack = await UpdatePackFolder.read(dir);
+    const what = `The pack in ${pack.out} is ${pack.app} ${pack.target} ${pack.platform} --env ${pack.env}`;
+    if (pack.app !== app.name) throw new Error(`${what}, not ${app.name}'s.`);
+    if (platform && platform !== pack.platform) throw new Error(`${what}, not ${platform}.`);
+    if (env && env !== pack.env) throw new Error(`${what}, not --env ${env}.`);
+    if (target) {
+      const targets = (await resolveMobileTargets(app, target)).map(({ name }) => name);
+      if (targets.length !== 1 || targets[0] !== pack.target)
+        throw new Error(`${what}, not --target ${target} (${targets.join(", ")}).`);
+    }
+    if (pack.env === "local" && !allowLocalRelease)
+      throw new Error(
+        `${what}, and a local pack is blocked. Pass --allow-local-release only for explicit local release testing.`,
+      );
+    return pack;
+  }
+
+  async push(pack: NativeUpdatePack, { channel, notes }: { channel: string | null; notes: string | null }) {
+    const target = channel ?? pack.channel;
+    return await UpdatePackFolder.withArchive(pack, async (archive) => {
+      const release = await new UpdatePackUpload(this.cloudApi, this.devProjectId)
+        .send(archive, { appName: pack.app, target: pack.target, platform: pack.platform, channel: target, notes })
+        .catch((error: unknown) => {
+          throw CloudApi.refusal(error, "a pack is uploaded by a project member signed in with `akan login`");
+        });
+      const label = `${pack.app} ${pack.target} ${pack.platform} on channel ${target}: release ${release.id}`;
+      if (release.status === "rejected")
+        throw new ExitCodeError(
+          `The project rejected ${label}:\n${(release.problems ?? []).map((problem) => `  - ${problem}`).join("\n")}`,
+          2,
+        );
+      if (release.status === "published")
+        Logger.rawLog(`Published ${label} (${pack.files} files, native API ${pack.nativeApi}).`);
+      else
+        Logger.rawLog(
+          `Staged ${label} (${pack.files} files, native API ${pack.nativeApi}). Publish it from the project's release screen.`,
+        );
+      return release;
+    });
+  }
+
+  //? The store build first, then a pack of the same commit: a server that registers the binary checks the pack runs in it.
+  async registerBinary(
+    app: App,
+    pack: NativeUpdatePack,
+    { distribution, env }: { distribution: AppBinaryDistribution; env: NativeEnv },
+  ) {
+    const { cloudApi, devProjectId } = this;
+    const bundlePath = await CloudUpdates.storeBundlePath(app, pack.target, pack.platform);
+    const bundleFile = Bun.file(bundlePath);
+    const rebuild = `akan release-${pack.platform} ${app.name} --target ${pack.target} --env ${env}`;
+    if (!(await bundleFile.exists())) throw new Error(`No store build at ${bundlePath}: run \`${rebuild}\` first.`);
+    const bundle = await UpdatePackFolder.readBundle(bundlePath);
+    if (!bundle.updates)
+      throw new Error(`The store build at ${bundlePath} takes no updates: give the target native.updates.`);
+    const packBundle = path.join(pack.out, UpdatePackFolder.bundleFile);
+    const envProblem = await NativePublicEnv.problemAgainst(bundlePath, packBundle);
+    if (envProblem) throw new ExitCodeError(`The pack in ${pack.out} cannot run in the store build: ${envProblem}.`, 2);
+    //? Every native build of the target rewrites this file, so a debug or another env's build replaces the release's.
+    if (bundle.web.hash !== pack.webHash)
+      throw new Error(
+        `The store build at ${bundlePath} is not this commit's --env ${env} build: its web bundle differs from the pack's. Run \`${rebuild}\`, then register that build.`,
+      );
+    const compat = await NativeApp.compareBundles(app.cwdPath, bundlePath, packBundle);
+    const verdict = UpdatePackFolder.storeBuildVerdict(
+      { out: pack.out, compat: { against: bundlePath, ...compat } },
+      `Run \`${rebuild}\`, then register that build.`,
+    );
+    if (verdict) throw verdict;
+    if (bundle.updates.channel !== pack.channel)
+      throw new Error(
+        `The store build at ${bundlePath} reads updates channel ${bundle.updates.channel}, and this commit's --env ${env} pack is for ${pack.channel}. Run \`${rebuild}\`, then register that build.`,
+      );
+    const { channel } = pack;
+    const upload = new UpdatePackUpload(cloudApi, devProjectId);
+    return await UpdatePackFolder.withArchive(pack, async (archive) => {
+      const binary = await upload
+        .stage(archive, { appName: pack.app, target: pack.target, platform: pack.platform, channel, notes: null })
+        .then((packUploadId) =>
+          upload.settle(() =>
+            cloudApi.registerAppBinary(devProjectId, {
+              appName: pack.app,
+              target: pack.target,
+              distribution,
+              bundle: bundleFile,
+              packUploadId,
+              channel,
+            }),
+          ),
+        )
+        .catch((error: unknown) => {
+          throw CloudApi.refusal(error, "a binary is registered by a project member signed in with `akan login`");
+        });
+      Logger.rawLog(
+        `Registered ${pack.app} ${pack.target} ${pack.platform} (${distribution}): binary ${binary.id}, native API ${pack.nativeApi}.`,
+      );
+      return binary;
+    });
+  }
+}

package/cloud/configLock.ts

@@ -36,7 +36,8 @@ export class ConfigLock {
 
   static async #take(lockPath: string) {
     const handle = await open(lockPath, "wx", 0o600).catch((error: NodeJS.ErrnoException) => {
-      if (error.code === "EEXIST") return null;
+      // Windows answers EPERM, not EEXIST, while a released lock file is still pending delete behind an open handle.
+      if (error.code === "EEXIST" || (process.platform === "win32" && error.code === "EPERM")) return null;
       throw error;
     });
     if (!handle) return false;

package/cloud/globalConfig.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { GlobalConfig } from "./globalConfig";
+
+const workspace = (cloudHost: string | null) => ({ getConfig: async () => ({ cloudHost }) });
+
+describe("GlobalConfig", () => {
+  test("hostFor spells --host the way the workspace's cloud.host is spelled, so one login serves both", async () => {
+    for (const given of ["https://cloud.example.com/", "https://Cloud.Example.com:443", "https://cloud.example.com//"])
+      expect(await GlobalConfig.hostFor(workspace(null), given)).toBe("https://cloud.example.com");
+    expect(await GlobalConfig.hostFor(workspace("https://cloud.example.com"), "https://cloud.example.com/")).toBe(
+      await GlobalConfig.hostFor(workspace("https://cloud.example.com"), null),
+    );
+    expect(await GlobalConfig.hostFor(workspace(null), "https://example.com/cloud/")).toBe("https://example.com/cloud");
+    expect(await GlobalConfig.hostFor(workspace(null), "http://localhost:8283/")).toBe("http://localhost:8283");
+    expect(await GlobalConfig.hostFor(workspace(null))).toBe(GlobalConfig.akanCloudHost);
+  });
+});

package/cloud/globalConfig.ts

@@ -1,4 +1,5 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
+import { trimTrailingSlashes } from "akanjs/common";
 import dayjs from "dayjs";
 import { FileSys } from "../fileSys";
 import { ConfigLock } from "./configLock";
@@ -54,8 +55,14 @@ export class GlobalConfig {
     });
   }
   static async hostFor(workspace: { getConfig(): Promise<{ cloudHost: string | null }> }, host?: string | null) {
-    if (host) return host;
-    return (await workspace.getConfig()).cloudHost ?? GlobalConfig.akanCloudHost;
+    return GlobalConfig.#normalizeHost(host || ((await workspace.getConfig()).cloudHost ?? GlobalConfig.akanCloudHost));
+  }
+  //? A login is stored under the host string, so `--host` and the workspace's `cloud.host` must spell one cloud alike.
+  static #normalizeHost(host: string) {
+    const url = URL.canParse(host) ? new URL(host) : null;
+    return url && (url.protocol === "https:" || url.protocol === "http:")
+      ? `${url.origin}${trimTrailingSlashes(url.pathname)}`
+      : trimTrailingSlashes(host);
   }
   static async getHostConfig(host = GlobalConfig.akanCloudHost): Promise<HostConfig> {
     const akanConfig = await GlobalConfig.#getAkanGlobalConfig();

package/cloud/index.ts

@@ -1,4 +1,7 @@
 export * from "./cloudApi";
+export * from "./cloudHttpError";
+export * from "./cloudUpdates";
 export * from "./constants";
 export * from "./globalConfig";
+export * from "./pipelineSecrets";
 export * from "./updatePackUpload";

package/cloud/pipelineSecrets.ts

@@ -0,0 +1,114 @@
+import { capitalize, Logger, PipelineNames } from "akanjs/common";
+import { CloudApi, type PipelineSecretListing } from "./cloudApi";
+
+//* The named secrets an Akan Cloud project hands its pipeline: written and removed by name, listed without values.
+export class PipelineSecrets {
+  static readonly #secretBytes = 64 * 1024;
+  //? The branches Akan Cloud deploys (its BranchType): a secret scoped to any other is refused by the server.
+  static readonly #secretBranches = ["debug", "develop", "main"];
+  static readonly #secretsUnavailable = "The server is not configured for pipeline secrets yet";
+
+  constructor(
+    readonly cloudApi: CloudApi,
+    readonly devProjectId: string,
+  ) {}
+
+  //* Never an argument: a value on the command line lands in shell history and in any `ps` listing.
+  static async readValue(name: string, file: string | null) {
+    const raw = file
+      ? await Bun.file(file).text()
+      : process.stdin.isTTY
+        ? await (await import("@inquirer/prompts")).password({
+            message: `Value of ${name} (hidden; it can never be read back)`,
+            mask: "*",
+          })
+        : await PipelineSecrets.#readStdin(name);
+    const value = raw.replace(/\r?\n$/, "");
+    if (!value) throw new Error(`The value of ${name} is empty.`);
+    const bytes = new TextEncoder().encode(value).length;
+    if (bytes > PipelineSecrets.#secretBytes)
+      throw new Error(`The value of ${name} is ${bytes} bytes, over ${PipelineSecrets.#secretBytes}.`);
+    return value;
+  }
+
+  static async #readStdin(name: string) {
+    process.stderr.write(`Reading the value of ${name} from stdin until it closes (or pass --file <path>).\n`);
+    return await Bun.stdin.text();
+  }
+
+  async upload({ name, branch, value }: { name: string; branch: string | null; value: string }) {
+    PipelineSecrets.assertName(name);
+    PipelineSecrets.assertBranch(branch);
+    const saved = await this.cloudApi
+      .uploadSecret(this.devProjectId, { scope: branch ?? "*", name, value })
+      .catch((error: unknown) => {
+        throw CloudApi.refusal(error, "a secret is written by a project member signed in with `akan login`", {
+          unavailable: PipelineSecrets.#secretsUnavailable,
+        });
+      });
+    Logger.rawLog(
+      `Saved ${saved.name} for ${saved.scope === "*" ? "every branch" : `branch ${saved.scope}`}. Builds that start from now on use it.`,
+    );
+  }
+
+  async list(branch: string | null) {
+    PipelineSecrets.assertBranch(branch);
+    const listed = await this.cloudApi.listSecrets(this.devProjectId).catch((error: unknown) => {
+      throw CloudApi.refusal(error, "the secrets are listed for a project member", {
+        unavailable: PipelineSecrets.#secretsUnavailable,
+      });
+    });
+    const secrets = listed.filter((secret) => !branch || secret.scope === "*" || secret.scope === branch);
+    Logger.rawLog(PipelineSecrets.format(secrets));
+  }
+
+  async remove({ name, branch }: { name: string; branch: string | null }) {
+    PipelineSecrets.assertName(name);
+    PipelineSecrets.assertBranch(branch);
+    const removed = await this.cloudApi
+      .removeSecret(this.devProjectId, { scope: branch ?? "*", name })
+      .catch((error: unknown) => {
+        throw CloudApi.refusal(error, "a secret is removed by a project member signed in with `akan login`", {
+          unavailable: PipelineSecrets.#secretsUnavailable,
+        });
+      });
+    Logger.rawLog(
+      removed
+        ? `Removed ${name} for ${branch ? `branch ${branch}` : "every branch"}.`
+        : `No ${name} for ${branch ? `branch ${branch}` : "every branch"} to remove.`,
+    );
+  }
+
+  static format(secrets: PipelineSecretListing[]) {
+    if (!secrets.length) return "No pipeline secrets.";
+    const rows = [...secrets]
+      .sort((a, b) => a.name.localeCompare(b.name) || a.scope.localeCompare(b.scope))
+      .map((secret) =>
+        [secret.name, secret.scope === "*" ? "every branch" : secret.scope, secret.updatedAt, secret.updatedBy].map(
+          (cell) => String(cell ?? "-"),
+        ),
+      );
+    const header = ["NAME", "SCOPE", "UPDATED", "BY"];
+    const widths = header.map((title, column) =>
+      Math.max(title.length, ...rows.map((row) => row[column]?.length ?? 0)),
+    );
+    return [header, ...rows]
+      .map((row) =>
+        row
+          .map((cell, column) => cell.padEnd(widths[column] ?? 0))
+          .join("  ")
+          .trimEnd(),
+      )
+      .join("\n");
+  }
+
+  static assertName(name: string) {
+    const problem = PipelineNames.secretNameError(name);
+    if (problem) throw new Error(`${capitalize(problem)}.`);
+  }
+
+  static assertBranch(branch: string | null) {
+    if (branch !== null && !PipelineSecrets.#secretBranches.includes(branch))
+      throw new Error(`--branch ${branch} is not a deployed branch: ${PipelineSecrets.#secretBranches.join(", ")}.`);
+  }
+}