@akanjs/devkit 3.0.2 → 3.1.0-rc.1

package/applicationBuildRunner.ts

@@ -1,4 +1,3 @@
-import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
 import type { BunPlugin } from "bun";
 import type {
@@ -16,10 +15,14 @@ import {
 } from "./frontendBuild";
 import { Spinner } from "./spinner";
 import { createServerEnvPlugin } from "./transforms/serverEnvPlugin";
+import { ServerEnvProfile } from "./transforms/serverEnvProfile";
+import { ProjectTypecheck } from "./typecheck/projectTypecheck";
 
 export interface TypecheckOptions {
   clean?: boolean;
   incremental?: boolean;
+  /** The app's own tests and specs too (`akan typecheck`); a build leaves them out. */
+  tests?: boolean;
 }
 
 export type BuildPhaseId = "prepare" | "typecheck" | "backend" | "ssr" | "csr" | "assets" | "compress" | "metadata";
@@ -32,6 +35,8 @@ export interface ApplicationBuildRunnerOptions {
   reporter?: BuildProgressReporter;
   /** The backend env the build is for, when it is not the workspace's own (a mobile or desktop build's `--env`). */
   environment?: string;
+  /** Bundles `env/env.server.<environment>.<profile>.ts`, which may hold no secret, in place of the environment's file. */
+  profile?: string;
 }
 export interface BuildOptions {
   spinner?: boolean;
@@ -67,34 +72,41 @@ const SSR_RENDER_EXTERNALS = [
 // is a no-op as of Bun 1.4.2.
 export const AKAN_BACKEND_MINIFY = { whitespace: true, syntax: true, identifiers: false } as const;
 
-export const AKAN_OPTIONAL_BACKEND_EXTERNALS = [
-  "@libsql/client",
-  "bullmq",
-  "ioredis",
-  "postgres",
-  "protobufjs",
-] as const;
+export const AKAN_OPTIONAL_BACKEND_EXTERNALS = ["bullmq", "ioredis", "postgres", "protobufjs"] as const;
 
 export class ApplicationBuildRunner {
   #app: App;
   #fast: boolean;
   #reporter?: BuildProgressReporter;
   #environment?: string;
+  #profile?: string;
   #spinner?: boolean;
   #startedAt = Date.now();
   #phases: BuildPhaseResult[] = [];
 
-  constructor(app: App, { fast = false, reporter, environment }: ApplicationBuildRunnerOptions = {}) {
+  constructor(app: App, { fast = false, reporter, environment, profile }: ApplicationBuildRunnerOptions = {}) {
     this.#app = app;
     this.#fast = fast;
     this.#reporter = reporter;
     this.#environment = environment;
+    this.#profile = profile;
+  }
+
+  get #envDir() {
+    return path.join(this.#app.cwdPath, "env");
   }
 
   async build({ spinner = false }: BuildOptions = {}): Promise<BuildResult> {
     // serial build is needed because of Bun.build is unstable for parallel build
     this.#spinner = spinner;
-    const { web, assets } = await this.#app.getConfig();
+    const { web, assets, baseDevEnv } = await this.#app.getConfig();
+    //? Before any phase: a profile that would ship a secret stops the build, not the image after it.
+    if (this.#profile)
+      await ServerEnvProfile.assertShippable({
+        envDir: this.#envDir,
+        environment: this.#environment ?? baseDevEnv.env,
+        profile: this.#profile,
+      });
     await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"));
     if (!this.#fast) await this.#runPhase("typecheck", "Typechecking", () => this.typecheck());
     await this.#runPhase(
@@ -148,11 +160,31 @@ export class ApplicationBuildRunner {
   }
 
   async typecheck(options: TypecheckOptions = {}) {
-    const { clean = false, incremental = true } = options;
     await this.#app.getPageKeys({ refresh: true });
-    const { typecheckDir, tsconfigPath } = await this.#writeTypecheckTsconfig(incremental);
-    if (clean) await rm(path.join(typecheckDir, "tsconfig.tsbuildinfo"), { force: true });
-    await this.#checkProjectInChildProcess(tsconfigPath);
+    const typecheck = new ProjectTypecheck(
+      this.#app.cwdPath,
+      this.#app.workspace.workspaceRoot,
+      this.#app.getCommandEnv(),
+    );
+    //* TypeScript's `include` globs do not cross a symlink, so synced lib pages need their real path.
+    const libPageIncludes = (await this.#app.getPageRoots())
+      .filter((root) => root.keyPrefix)
+      .flatMap((root) => {
+        const rel = path.relative(typecheck.typecheckDir, root.realDir).split(path.sep).join("/");
+        return [`${rel}/**/*.ts`, `${rel}/**/*.tsx`];
+      });
+    await typecheck.run(
+      [
+        "../../main.ts",
+        "../../server.ts",
+        "../../client.ts",
+        "../../page/**/*.ts",
+        "../../page/**/*.tsx",
+        ...libPageIncludes,
+        "../../../../pkgs/akanjs/*/types/**/*.d.ts",
+      ],
+      options,
+    );
   }
 
   async #runPhase<T>(
@@ -209,6 +241,28 @@ export class ApplicationBuildRunner {
     return `${sha.stdout.toString().trim()}${suffix}`;
   }
 
+  #serverEnv: BunPlugin | null = null;
+  #warnedLibEnvs = new Set<string>();
+  //? One plugin for every server-side bundle of the build: the backend, the RSC worker and the SSR route bundle.
+  #serverEnvPlugin(baseEnv: string, branches: Iterable<string>): BunPlugin {
+    this.#serverEnv ??= createServerEnvPlugin({
+      envDir: this.#envDir,
+      //? The root .env wins over the shell in baseDevEnv, so a `--env` build names its own; a desktop app runs it.
+      environment: this.#environment ?? baseEnv,
+      environments: ["local", "testing", ...branches],
+      profile: this.#profile,
+      onLibEnv: (file, { profileFile, stripped }) => {
+        if (profileFile || !stripped.length || this.#warnedLibEnvs.has(file)) return;
+        this.#warnedLibEnvs.add(file);
+        const lib = path.relative(this.#app.workspace.workspaceRoot, file);
+        this.#app.logger.warn(
+          `${lib}: the "${this.#profile}" build leaves out ${stripped.join(", ")}. Give the lib ${path.basename(ServerEnvProfile.profileFileOf(file, this.#profile ?? ""))} to say what this profile runs with.`,
+        );
+      },
+    });
+    return this.#serverEnv;
+  }
+
   async #buildBackend() {
     const { externalLibs, web, baseDevEnv, branches } = await this.#app.getConfig();
     const backendEntryPoints = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
@@ -223,12 +277,7 @@ export class ApplicationBuildRunner {
       // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
       define: { "process.env.NODE_ENV": JSON.stringify("production") },
     } satisfies Omit<Bun.BuildConfig, "entrypoints">;
-    const serverEnvPlugin = createServerEnvPlugin({
-      envDir: path.join(this.#app.cwdPath, "env"),
-      //? The root .env wins over the shell in baseDevEnv, so a `--env` build names its own; a desktop app runs it.
-      environment: this.#environment ?? baseDevEnv.env,
-      environments: ["local", "testing", ...branches],
-    });
+    const serverEnvPlugin = this.#serverEnvPlugin(baseDevEnv.env, branches);
     const backendConfig = {
       ...sharedConfig,
       plugins: [this.#createExternalSpecifiersPlugin(externalLibs), serverEnvPlugin],
@@ -306,74 +355,14 @@ void run().catch((error) => {
       this.#app.log(`[cli] no route files under ${this.#app.cwdPath}/page — skipping SSR build`);
       return null;
     }
-    const base = await new SsrBaseArtifactBuilder(this.#app, "build").build();
+    const { baseDevEnv, branches } = await this.#app.getConfig();
+    const base = await new SsrBaseArtifactBuilder(this.#app, "build", {
+      serverEnv: this.#serverEnvPlugin(baseDevEnv.env, branches),
+    }).build();
     const allRoutes = await new AllRoutesBuilder(this.#app, base.artifact, "build").build();
     return { base, allRoutes };
   }
 
-  async #writeTypecheckTsconfig(incremental: boolean) {
-    const typecheckDir = path.join(this.#app.cwdPath, ".akan", "typecheck");
-    await mkdir(typecheckDir, { recursive: true });
-    //* TypeScript's `include` globs do not cross a symlink, so synced lib pages need their real path.
-    const libPageIncludes = (await this.#app.getPageRoots())
-      .filter((root) => root.keyPrefix)
-      .flatMap((root) => {
-        const rel = path.relative(typecheckDir, root.realDir).split(path.sep).join("/");
-        return [`${rel}/**/*.ts`, `${rel}/**/*.tsx`];
-      });
-    const tsconfig = {
-      extends: "../../tsconfig.json",
-      compilerOptions: {
-        noEmit: true,
-        incremental,
-        tsBuildInfoFile: "./tsconfig.tsbuildinfo",
-      },
-      include: [
-        "../../main.ts",
-        "../../server.ts",
-        "../../client.ts",
-        "../../page/**/*.ts",
-        "../../page/**/*.tsx",
-        ...libPageIncludes,
-        "../../../../pkgs/akanjs/*/types/**/*.d.ts",
-      ],
-      references: [],
-    };
-    const tsconfigPath = path.join(typecheckDir, "tsconfig.json");
-    await Bun.write(tsconfigPath, `${JSON.stringify(tsconfig, null, 2)}\n`);
-    return { typecheckDir, tsconfigPath };
-  }
-
-  async #checkProjectInChildProcess(tsconfigPath: string) {
-    const entry = await this.#resolveTypecheckWorkerEntry();
-    const proc = Bun.spawn([process.execPath, entry], {
-      cwd: this.#app.workspace.workspaceRoot,
-      env: this.#app.getCommandEnv({
-        AKAN_COMMAND_TYPE: "typecheck",
-        AKAN_TYPECHECK_TSCONFIG: tsconfigPath,
-      }),
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const [stdout, stderr, exitCode] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-      proc.exited,
-    ]);
-    if (exitCode !== 0) throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
-  }
-
-  async #resolveTypecheckWorkerEntry() {
-    const candidates = [
-      path.join(this.#app.workspace.workspaceRoot, "pkgs/@akanjs/devkit/typecheck/typecheck.proc.ts"),
-      path.join(this.#app.workspace.workspaceRoot, "node_modules/@akanjs/devkit/typecheck/typecheck.proc.ts"),
-      path.join(import.meta.dir, "typecheck.proc.js"),
-      path.join(import.meta.dir, "typecheck.proc.ts"),
-    ];
-    for (const candidate of candidates) if (await Bun.file(candidate).exists()) return candidate;
-    throw new Error(`[cli] typecheck worker entry not found; looked in: ${candidates.join(", ")}`);
-  }
-
   async #buildOrThrow(label: string, config: Bun.BuildConfig): Promise<Bun.BuildOutput> {
     const result = await Bun.build(config);
     if (!result.success) throw new AggregateError(result.logs, `[${label}] Bun.build failed`);

package/artifact/implicitRootLayout.test.ts

@@ -39,8 +39,9 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("const inheritedLayout = resolveRouteModule(inheritedModule as never");
     expect(generatedSource).not.toContain("<System.Provider");
     expect(generatedSource).toContain("export async function generateHead(props: PageProps)");
-    expect(generatedSource).toContain("if (userLayout.generateHead) return userLayout.generateHead(props);");
-    expect(generatedSource).toContain("return inheritedLayout.head;");
+    // The ancestor root is a level of the route tree, which merges its head; this boundary returns only its own.
+    expect(generatedSource).toContain("[userLayout].map((layout)");
+    expect(generatedSource).toContain("return RouteHead.mergeNodes(heads);");
     expect(generatedSource).not.toContain("generateMetadata");
     expect(generatedSource).toContain("export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;");
     expect(generatedSource).toContain("export const Error = userLayout.Error ?? inheritedLayout.Error;");
@@ -71,6 +72,9 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("<System.Provider");
     expect(generatedSource).toContain("export const theme = userLayout.theme ?? inheritedLayout.theme;");
     expect(generatedSource).toContain("theme={theme}");
+    expect(generatedSource).toContain("export const viewport = userLayout.viewport ?? inheritedLayout.viewport;");
+    expect(generatedSource).toContain("viewport={viewport}");
+    expect(generatedSource).toContain("[inheritedLayout, userLayout].map((layout)");
     expect(generatedSource).toContain('import { allDictionary } from "../dict/useDict.ts";');
     expect(generatedSource).toContain(
       'allDictionary={process.env.AKAN_PUBLIC_RENDER_ENV === "ssr" ? allDictionary : undefined}',

package/artifact/implicitRootLayout.ts

@@ -189,11 +189,13 @@ async function writeGeneratedRootLayoutFile(opts: {
     : "";
   const layoutChild = isAsyncUserLayout ? "{layout}" : userLayoutElement;
   const layoutReturn = isAsyncUserLayout ? "layout" : userLayoutElement;
+  //? Under an ancestor root boundary the route tree merges that root's head itself; merging it here would repeat it.
+  const headLayouts = opts.includeSystemProvider ? "[inheritedLayout, userLayout]" : "[userLayout]";
   const layoutExports = `export async function generateHead(props: PageProps) {
-  if (userLayout.generateHead) return userLayout.generateHead(props);
-  if (userLayout.head !== undefined) return userLayout.head;
-  if (inheritedLayout.generateHead) return inheritedLayout.generateHead(props);
-  return inheritedLayout.head;
+  const heads = await Promise.all(
+    ${headLayouts}.map((layout) => (layout.generateHead ? layout.generateHead(props) : layout.head)),
+  );
+  return RouteHead.mergeNodes(heads);
 }
 
 export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
@@ -204,7 +206,7 @@ ${layoutSignature}({ children, params, searchParams }: LayoutProps) {
 ${layoutBinding}  return `;
   const source = opts.includeSystemProvider
     ? `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
-import { loadFonts, resolveRouteModule } from "akanjs/client";
+import { loadFonts, resolveRouteModule, RouteHead } from "akanjs/client";
 import type { ReactNode } from "react";
 import { System } from "akanjs/ui";
 import { env } from "@apps/${opts.appName}/env/env.client";
@@ -216,15 +218,18 @@ if (defaultFonts.length > 1) throw new Error("[route-convention] only one defaul
 const defaultFont = defaultFonts[0];
 const defaultFontClassName = defaultFont ? (defaultFont.className ?? \`font-\${defaultFont.name}\`) : undefined;
 export const theme = userLayout.theme ?? inheritedLayout.theme;
+export const viewport = userLayout.viewport ?? inheritedLayout.viewport;
+export const manifest = userLayout.manifest ?? inheritedLayout.manifest;
 
 ${layoutExports}(
     <System.Provider
       of={GeneratedLayout as never}
       appName=${JSON.stringify(opts.appName)}
       ${prefix ? `prefix=${JSON.stringify(prefix)}\n      ` : ""}params={params}
-      manifest={userLayout.manifest ?? inheritedLayout.manifest}
+      manifest={manifest}
       env={env}
       theme={theme}
+      viewport={viewport}
       fonts={loadFonts(userFonts)}
       className={defaultFontClassName}
       layoutStyle={userLayout.layoutStyle ?? inheritedLayout.layoutStyle}
@@ -238,7 +243,7 @@ ${layoutExports}(
 }
 `
     : `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
-import { resolveRouteModule } from "akanjs/client";
+import { resolveRouteModule, RouteHead } from "akanjs/client";
 import type { ReactNode } from "react";
 ${inheritedImport}${userImport}
 ${layoutExports}${layoutReturn};

package/biome.base.json

@@ -301,8 +301,6 @@
         "{apps,libs}/**/*.document.ts",
         "{apps,libs}/**/*.service.ts",
         "{apps,libs}/**/*.signal.ts",
-        "{apps,libs}/**/*.signal.test.ts",
-        "{apps,libs}/**/*.service.test.ts",
         "{apps,libs}/**/*.store.ts",
         "{apps,libs}/**/*.Template.tsx",
         "{apps,libs}/**/*.Unit.tsx",
@@ -315,6 +313,13 @@
         "./node_modules/@akanjs/devkit/lint/no-deep-internal-import.grit"
       ]
     },
+    {
+      "includes": ["{apps,libs}/**/*.signal.test.ts", "{apps,libs}/**/*.service.test.ts"],
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-import-external-library-in-test.grit",
+        "./node_modules/@akanjs/devkit/lint/no-deep-internal-import.grit"
+      ]
+    },
     {
       "includes": [
         "apps/**/*.tsx",

package/cloud/cloudApi.ts

@@ -63,6 +63,45 @@ export interface TunnelGrant {
   expiresAt: string | null;
 }
 
+/** `scope` is `"*"` for every branch or the one branch it overrides. No call ever returns a value. */
+export interface PipelineSecretSummary {
+  name: string;
+  scope: string;
+  updatedAt: string;
+}
+
+export interface PipelineSecretListing extends PipelineSecretSummary {
+  updatedBy: string;
+}
+
+/** What akasys answers for an uploaded pack or a registered binary; a pack's release also says how it was taken. */
+export interface CloudRecord {
+  id: string;
+  status?: string;
+  problems?: string[];
+  [key: string]: unknown;
+}
+
+export interface UpdateUploadRequest {
+  appName: string;
+  target: string;
+  platform: "ios" | "android";
+  channel: string;
+  notes: string | null;
+  size: number;
+  sha256: string;
+}
+
+export interface UpdateUploadTicket {
+  uploadId: string;
+  /** A presigned PUT: whoever holds it writes the staging object, so it is never logged or put in an argv. */
+  uploadUrl: string;
+  expiresAt: string;
+  contentType: string;
+}
+
+export type AppBinaryDistribution = "appStore" | "testFlight" | "playStore" | "playTesting" | "direct";
+
 export interface TunnelSummary {
   code: string;
   hostname: string;
@@ -74,6 +113,11 @@ export interface TunnelSummary {
 }
 
 export class CloudApi {
+  /** The HTTP status an error from this client carries, or null for one without (a dropped connection, a timeout). */
+  static statusOf(error: unknown) {
+    const status = Number(/(?:^|: )(\d{3}) /.exec(error instanceof Error ? error.message : String(error))?.[1]);
+    return Number.isNaN(status) ? null : status;
+  }
   readonly #api: HttpClient;
   #accessToken: AccessToken | null = null;
   #workspace: Workspace;
@@ -113,6 +157,49 @@ export class CloudApi {
     formData.append("file", file);
     return await this.#api.post<boolean>(`/uploadEnv/${devProjectId}`, formData);
   }
+  async uploadSecret(devProjectId: string, secret: { scope: string; name: string; value: string }) {
+    return await this.#api.post<PipelineSecretSummary>(`/uploadSecret/${encodeURIComponent(devProjectId)}`, secret);
+  }
+  async listSecrets(devProjectId: string) {
+    return await this.#api.get<PipelineSecretListing[]>(`/listSecrets/${encodeURIComponent(devProjectId)}`);
+  }
+  async removeSecret(devProjectId: string, secret: { scope: string; name: string }) {
+    return await this.#api.post<boolean>(`/removeSecret/${encodeURIComponent(devProjectId)}`, secret);
+  }
+  async requestUpdateUpload(devProjectId: string, upload: UpdateUploadRequest) {
+    return await this.#api.post<UpdateUploadTicket>(`/requestUpdateUpload/${encodeURIComponent(devProjectId)}`, upload);
+  }
+  // The endpoint declares ten minutes; Cloudflare cuts at 100 s anyway, which is what UpdatePackUpload's retry is for.
+  async commitUpdateUpload(devProjectId: string, uploadId: string) {
+    return await this.#api.post<CloudRecord>(
+      `/commitUpdateUpload/${encodeURIComponent(devProjectId)}`,
+      { uploadId },
+      { signal: AbortSignal.timeout(11 * 60_000) },
+    );
+  }
+  async registerAppBinary(
+    devProjectId: string,
+    binary: {
+      appName: string;
+      target: string;
+      distribution: AppBinaryDistribution;
+      bundle: Blob;
+      /** The pack staged with UpdatePackUpload.stage; the multipart `pack` is for a server older than staging. */
+      packUploadId?: string;
+      pack?: Blob;
+      channel?: string;
+    },
+  ) {
+    const formData = new FormData();
+    for (const key of ["appName", "target", "distribution"] as const) formData.append(key, binary[key]);
+    if (binary.channel) formData.append("channel", binary.channel);
+    formData.append("bundle", binary.bundle, "bundle.json");
+    if (binary.packUploadId) formData.append("packUploadId", binary.packUploadId);
+    if (binary.pack) formData.append("pack", binary.pack, "pack.tgz");
+    return await this.#api.post<CloudRecord>(`/registerAppBinary/${encodeURIComponent(devProjectId)}`, formData, {
+      signal: AbortSignal.timeout(11 * 60_000),
+    });
+  }
   async downloadEnv(devProjectId: string): Promise<unknown> {
     const localPath = `${this.#workspace.workspaceRoot}/local/env.tar`;
     await this.#api.getFile(`/downloadEnv/${devProjectId}`, localPath);

package/cloud/globalConfig.ts

@@ -53,6 +53,10 @@ export class GlobalConfig {
       await GlobalConfig.#setAkanGlobalConfig(mutate(await GlobalConfig.#getAkanGlobalConfig()));
     });
   }
+  static async hostFor(workspace: { getConfig(): Promise<{ cloudHost: string | null }> }, host?: string | null) {
+    if (host) return host;
+    return (await workspace.getConfig()).cloudHost ?? GlobalConfig.akanCloudHost;
+  }
   static async getHostConfig(host = GlobalConfig.akanCloudHost): Promise<HostConfig> {
     const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
     return GlobalConfig.toHostConfig(akanConfig.cloudHost[host] ?? getDefaultHostConfig(host));

package/cloud/index.ts

@@ -1,3 +1,4 @@
 export * from "./cloudApi";
 export * from "./constants";
 export * from "./globalConfig";
+export * from "./updatePackUpload";