alepha 0.21.2 → 0.22.0

package/src/cli/core/tasks/BuildCloudflareTask.ts

@@ -1,22 +1,105 @@
 import { basename } from "node:path";
 import { $inject } from "alepha";
 import { KV_DEFAULT_BINDING } from "alepha/cache";
-import { $container, type ContainerPrimitive } from "alepha/containers";
-import { EmailProvider } from "alepha/email";
-import {
-  CloudflareEmailProvider,
-  SEND_EMAIL_DEFAULT_BINDING,
-} from "alepha/email/cloudflare";
+import type { ContainerPrimitive } from "alepha/container";
+import { SEND_EMAIL_DEFAULT_BINDING } from "alepha/email/cloudflare";
 import { QUEUE_DEFAULT_BINDING } from "alepha/queue";
 import type { CronProvider, WorkerdCronProvider } from "alepha/scheduler";
 import { FileSystemProvider } from "alepha/system";
 import { ViteUtils } from "../services/ViteUtils.ts";
 import { BuildTask, type BuildTaskContext } from "./BuildTask.ts";
 
+// Looked up by class name string (not by class identity) because
+// BuildCloudflareTask runs in the CLI's Alepha context while ctx.alepha
+// is the workspace's separate context. Two module graphs = two distinct
+// `CloudflareEmailProvider` class objects, so the imported reference
+// here wouldn't match the one the workspace registered.
+const CLOUDFLARE_EMAIL_PROVIDER_NAME = "CloudflareEmailProvider";
+
 interface WranglerConfig {
   [key: string]: any;
 }
 
+/**
+ * Build-time snapshot describing what the workspace needs at deploy
+ * time. Written to `dist/manifest.json` alongside `wrangler.jsonc`.
+ *
+ * Lets `alepha platform up --prebuilt` skip the Vite-based
+ * introspection step on the deploy side — and lets Alepha Rocket skip
+ * the workspace's runtime `npm install` because no app source is
+ * booted at deploy time. The manifest captures the bits of primitive
+ * data that the deploy steps (provision, secrets, hooks) need to
+ * know.
+ */
+export interface BuildManifest {
+  version: 1;
+  project: string;
+  /**
+   * Default environment when `--env` is omitted at deploy time.
+   * Captured from `platformOptions.default` (defaults to `"production"`).
+   */
+  defaultEnv: string;
+  /**
+   * Multi-tenancy mode (`none` | `optional` | `required`). Captured from
+   * `platformOptions.tenancy` so the prebuilt deploy side (Rocket) can
+   * validate `--tenant` without re-evaluating `alepha.config.ts`.
+   */
+  tenancy?: "none" | "optional" | "required";
+  /**
+   * Resolved `platform({ environments: ... })` map. Captured at build
+   * time from the workspace's `alepha.config.ts` so the deploy side
+   * doesn't need to re-evaluate the config. Each value is the same
+   * `EnvironmentConfig` shape consumed by the orchestrator (adapter,
+   * domain, zone, jurisdiction, accountId).
+   */
+  environments: Record<
+    string,
+    {
+      adapter: "cloudflare" | "vercel";
+      domain?: string;
+      zone?: string;
+      jurisdiction?: "eu" | "fedramp";
+      accountId?: string;
+    }
+  >;
+  resources: {
+    hasDatabase: boolean;
+    hasBucket: boolean;
+    hasKV: boolean;
+    hasQueue: boolean;
+    hasCron: boolean;
+  };
+  /**
+   * All distinct cron expressions registered by `$scheduler`
+   * primitives. Empty when `hasCron` is false.
+   */
+  crons: string[];
+  /**
+   * `$container()` descriptors — image, port, lifecycle settings.
+   * Used both to populate Cloudflare Containers bindings in
+   * wrangler.jsonc and (in future) to know which images Rocket should
+   * pull on the deploy side.
+   */
+  containers: Array<{
+    name: string;
+    className: string;
+    image: string;
+    port: number;
+    sleepAfter: string;
+    instanceType: string;
+    maxInstances: number;
+  }>;
+  /**
+   * Every env var the app declares via `$env`, captured from
+   * `alepha.dump().env` at build time. The deploy `secrets` step uses this
+   * as the worker-secret allowlist (minus build/binding vars) so CI can
+   * deliver secrets straight from `process.env` without a `.env` file —
+   * `platform.secrets.keys` overrides it when set. Empty when introspection
+   * was unavailable (older artifacts / prebuilt mode).
+   */
+  env: string[];
+}
+
 /**
  * Generate Cloudflare Workers deployment configuration.
  *
@@ -52,7 +135,15 @@ export class BuildCloudflareTask extends BuildTask {
     distDir: string,
   ): Promise<void> {
     const root = ctx.root;
-    const name = basename(root);
+    // Slugify the dir basename — wrangler rejects names that aren't
+    // `^[a-z0-9-]+$` (no uppercase, dots, underscores, spaces, etc.).
+    // Without this, running `alepha build -t cloudflare` in a dir like
+    // `My App` or `club-0.0.2` produces an unusable `wrangler.jsonc`.
+    const name = basename(root)
+      .toLowerCase()
+      .replace(/[^a-z0-9-]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 63);
     const hasAssets = await this.fs.exists(
       this.fs.join(root, distDir, "public"),
     );
@@ -98,9 +189,128 @@ export class BuildCloudflareTask extends BuildTask {
       JSON.stringify(wrangler, null, 2),
     );
 
+    // Only write a fresh manifest when we discovered it from a booted
+    // Alepha instance. In manifest mode (ctx.manifest != null) we're
+    // re-emitting the same data we just read — skip to avoid a redundant
+    // write and to keep the original manifest as the canonical record.
+    if (!ctx.manifest) {
+      await this.writeManifest(ctx, root, distDir, name, containers);
+    }
     await this.writeWorkerEntryPoint(root, distDir, containers);
   }
 
+  /**
+   * Write `dist/manifest.json` — a build-time snapshot of everything
+   * downstream tooling needs to know about the app without re-booting
+   * it. Used by `alepha platform up --prebuilt` (and Alepha Rocket) so
+   * the deploy path can skip the Vite-based introspection step and the
+   * workspace's runtime npm install.
+   */
+  protected async writeManifest(
+    ctx: BuildTaskContext,
+    root: string,
+    distDir: string,
+    name: string,
+    containers: ContainerDescriptor[],
+  ): Promise<void> {
+    // Discover the same primitive shapes the enhance* methods read.
+    // Errors are silently swallowed — an absent primitive class just
+    // means the app doesn't use that resource.
+    let hasDatabase = false;
+    let hasBucket = false;
+    let hasKV = false;
+    let hasQueue = false;
+    let crons: string[] = [];
+
+    try {
+      const repo = ctx.alepha.inject("RepositoryProvider") as {
+        getRepositories?: () => unknown[];
+      };
+      hasDatabase = (repo.getRepositories?.() ?? []).length > 0;
+    } catch {}
+
+    try {
+      hasBucket = ctx.alepha.primitives("$bucket").length > 0;
+    } catch {}
+
+    try {
+      // Only count $cache primitives without an explicit `provider`
+      // option — those fall back to KV on workerd. Explicit memory /
+      // Redis / Postgres providers opt out of KV provisioning.
+      hasKV =
+        ctx.alepha
+          .primitives("cache")
+          .filter(
+            (p) =>
+              (p as { options?: { provider?: unknown } }).options?.provider ==
+              null,
+          ).length > 0;
+    } catch {}
+
+    try {
+      hasQueue = ctx.alepha.primitives("$queue").length > 0;
+    } catch {}
+
+    try {
+      const cronProvider = ctx.alepha.inject("CronProvider") as {
+        getCronJobs?: () => Array<{ expression: string }>;
+      };
+      crons = [
+        ...new Set(
+          (cronProvider.getCronJobs?.() ?? []).map((c) => c.expression),
+        ),
+      ];
+    } catch {}
+
+    // platformOptions come from the CLI's Alepha instance (where
+    // alepha.config.ts ran during the configure hook). BuildCommand
+    // reads them up there and threads them via ctx — ctx.alepha here
+    // is the WORKSPACE's Vite-booted Alepha, which never saw the
+    // platform options.
+    const defaultEnv = ctx.platformOptions?.default ?? "production";
+    const environments = (ctx.platformOptions?.environments ??
+      {}) as BuildManifest["environments"];
+
+    // Every declared `$env` key. dump() force-instantiates the graph (no
+    // start/ready hooks), so this is the full env surface — used by the
+    // deploy `secrets` step as the worker-secret allowlist.
+    let env: string[] = [];
+    try {
+      env = Object.keys(ctx.alepha.dump().env).sort();
+    } catch {}
+
+    const manifest: BuildManifest = {
+      version: 1,
+      project: name,
+      defaultEnv,
+      tenancy: ctx.platformOptions?.tenancy,
+      environments,
+      resources: {
+        hasDatabase,
+        hasBucket,
+        hasKV,
+        hasQueue,
+        hasCron: crons.length > 0,
+      },
+      crons,
+      containers: containers.map((c) => ({
+        name: c.name,
+        className: c.className,
+        image: c.image,
+        port: c.port,
+        sleepAfter: c.sleepAfter,
+        instanceType: c.instanceType,
+        maxInstances: c.maxInstances,
+      })),
+      env,
+    };
+
+    await this.fs.writeFile(
+      this.fs.join(root, distDir, "manifest.json"),
+      JSON.stringify(manifest, null, 2),
+    );
+  }
+
   protected enhanceDomain(wrangler: WranglerConfig): void {
     const domain = process.env.CLOUDFLARE_DOMAIN;
     if (!domain) {
@@ -132,23 +342,29 @@ export class BuildCloudflareTask extends BuildTask {
   }
 
   protected enhanceCron(ctx: BuildTaskContext, wrangler: WranglerConfig): void {
-    if (ctx.alepha.primitives("scheduler").length === 0) {
+    const cronExpressions = ctx.manifest
+      ? ctx.manifest.crons
+      : this.discoverCrons(ctx);
+    if (cronExpressions.length === 0) {
       return;
     }
+    wrangler.triggers ??= {};
+    wrangler.triggers.crons = cronExpressions;
+  }
 
+  protected discoverCrons(ctx: BuildTaskContext): string[] {
+    if (ctx.alepha.primitives("scheduler").length === 0) {
+      return [];
+    }
     let cronProvider: CronProvider | undefined;
     try {
       cronProvider = ctx.alepha.inject("CronProvider") as WorkerdCronProvider;
     } catch {}
-
     const crons = cronProvider?.getCronJobs();
     if (!crons || crons.length === 0) {
-      return;
+      return [];
     }
-
-    const cronExpressions = [...new Set(crons.map((c) => c.expression))];
-    wrangler.triggers ??= {};
-    wrangler.triggers.crons = cronExpressions;
+    return [...new Set(crons.map((c) => c.expression))];
   }
 
   protected enhanceDatabase(wrangler: WranglerConfig): void {
@@ -256,14 +472,16 @@ export class BuildCloudflareTask extends BuildTask {
     ctx: BuildTaskContext,
     wrangler: WranglerConfig,
   ): void {
-    let provider: EmailProvider | undefined;
-    try {
-      provider = ctx.alepha.inject(EmailProvider);
-    } catch {
+    // Manifest mode doesn't capture email provider details yet. Apps
+    // using CloudflareEmailProvider would need a manifest field added.
+    // For now, skip — non-email apps and apps using non-CF providers
+    // are unaffected. TODO: add `emailProvider` to BuildManifest.
+    if (ctx.manifest || !ctx.alepha) {
       return;
     }
-
-    if (!(provider instanceof CloudflareEmailProvider)) {
+    try {
+      ctx.alepha.inject(CLOUDFLARE_EMAIL_PROVIDER_NAME);
+    } catch {
       return;
     }
 
@@ -276,11 +494,17 @@ export class BuildCloudflareTask extends BuildTask {
       return;
     }
 
+    // NOTE: do NOT set `destination_address` here. On a Cloudflare
+    // `send_email` binding, `destination_address` is a *recipient* allow-list
+    // lock (the worker may then only send TO that one address) — it is not the
+    // sender. Setting it to `EMAIL_FROM` (the sender) broke all outbound mail:
+    // a bare address locked delivery to that single recipient ("email to … not
+    // allowed"), and a display-name form like `Lore <noreply@…>` is a malformed
+    // destination value that Cloudflare rejects with "internal error". The
+    // sender goes in the message `from` field (see CloudflareEmailProvider.send);
+    // leaving the binding unrestricted lets the worker send to any verified
+    // destination.
     const entry: Record<string, unknown> = { name: SEND_EMAIL_DEFAULT_BINDING };
-    const destination = process.env.EMAIL_FROM;
-    if (destination) {
-      entry.destination_address = destination;
-    }
 
     wrangler.send_email.push(entry);
   }
@@ -295,18 +519,19 @@ export class BuildCloudflareTask extends BuildTask {
    * `writeWorkerEntryPoint` can emit `export class <NAME> extends
    * Container` declarations referencing them.
    */
-  protected enhanceContainers(
-    ctx: BuildTaskContext,
-    wrangler: WranglerConfig,
-  ): ContainerDescriptor[] {
+  protected discoverContainers(ctx: BuildTaskContext): ContainerDescriptor[] {
+    // String key, not the `$container` factory. The build task runs in
+    // the CLI's Node realm, while the workspace's entry module is
+    // loaded by Vite — two separate module copies of
+    // `alepha/container`. Looking up by `$container[KIND]` (a class
+    // reference) would dereference the CLI's ContainerPrimitive class,
+    // which never matches the workspace's. The string form iterates
+    // the registry by class name and survives the dual-realm — same
+    // pattern used for `$bucket`, `$queue`, `scheduler` below.
     const primitives = ctx.alepha.primitives(
-      $container,
+      "container",
     ) as ContainerPrimitive[];
-    if (primitives.length === 0) {
-      return [];
-    }
-
-    const descriptors: ContainerDescriptor[] = primitives.map((p) => ({
+    return primitives.map((p) => ({
       name: p.name.toUpperCase(),
       className: p.name
         .split(/[^a-zA-Z0-9]/)
@@ -317,10 +542,67 @@ export class BuildCloudflareTask extends BuildTask {
       port: p.options.port ?? 3000,
       sleepAfter:
         typeof p.options.sleepAfter === "string" ? p.options.sleepAfter : "15m",
-      instanceType: p.options.instanceType ?? "dev",
+      // `lite` is the post-GA name for what `$container` historically
+      // called `dev`. Default to `lite` here and rewrite any
+      // explicit `dev` to it on the way out — wrangler warns
+      // otherwise.
+      instanceType:
+        p.options.instanceType === "dev"
+          ? "lite"
+          : (p.options.instanceType ?? "lite"),
       maxInstances: p.options.maxInstances ?? 5,
       envVars: p.options.envVars,
     }));
+  }
+
+  /**
+   * Expand a short image ref (e.g. `alepha-rocket:0.1.0`) into the
+   * fully-qualified `registry.cloudflare.com/<account>/<image>:<tag>`
+   * URL that wrangler validates at deploy time.
+   *
+   * Cloudflare Containers only pulls from `registry.cloudflare.com`;
+   * wrangler accepts either a Dockerfile path or a fully-qualified
+   * registry URL in the `image` field — not a bare DockerHub-style
+   * name. We let `$container({ image })` callers write the short
+   * form (it matches what `wrangler containers push <local>` accepts
+   * + matches the local docker tag) and rewrite to the CF registry
+   * URL here.
+   *
+   * Pass-through cases:
+   *   - already a full URL: starts with `registry.cloudflare.com/`
+   *     or contains a scheme/`://`
+   *   - looks like a Dockerfile path: starts with `./` or `/`
+   */
+  protected resolveContainerImage(image: string): string {
+    if (
+      image.startsWith("./") ||
+      image.startsWith("/") ||
+      image.startsWith("registry.cloudflare.com/") ||
+      image.includes("://")
+    ) {
+      return image;
+    }
+    const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+    if (!accountId) {
+      // No account id — leave the short form and let wrangler error
+      // out with a clearer message. This branch fires only in dry
+      // builds where the env isn't wired (e.g. `alepha build` without
+      // `alepha platform up` around it).
+      return image;
+    }
+    return `registry.cloudflare.com/${accountId}/${image}`;
+  }
+
+  protected enhanceContainers(
+    ctx: BuildTaskContext,
+    wrangler: WranglerConfig,
+  ): ContainerDescriptor[] {
+    const descriptors: ContainerDescriptor[] = ctx.manifest
+      ? (ctx.manifest.containers as ContainerDescriptor[])
+      : this.discoverContainers(ctx);
+    if (descriptors.length === 0) {
+      return [];
+    }
 
     wrangler.containers = wrangler.containers || [];
     wrangler.durable_objects = wrangler.durable_objects || {};
@@ -331,7 +613,7 @@ export class BuildCloudflareTask extends BuildTask {
     for (const d of descriptors) {
       wrangler.containers.push({
         class_name: d.className,
-        image: d.image,
+        image: this.resolveContainerImage(d.image),
         instance_type: d.instanceType,
         max_instances: d.maxInstances,
       });
@@ -357,20 +639,24 @@ export class BuildCloudflareTask extends BuildTask {
     distDir: string,
     containers: ContainerDescriptor[] = [],
   ): Promise<void> {
+    // Extend `globalThis.__alepha_CloudflareContainer` instead of
+    // importing `@cloudflare/containers` directly. The entry is
+    // written AFTER Vite, so any bare specifier in here survives to
+    // workerd (which has `no_bundle: true`) and 10021's out. The
+    // global is set by a side-effect in `alepha/container`'s
+    // workerd entry, which Vite has already inlined into
+    // `./index.js`. ESM evaluates top-level imports before the
+    // module body, so by the time the `extends` expression below is
+    // evaluated, the global is set.
     const containerDeclarations = containers
       .map((c) => {
         const envVars = c.envVars
           ? `  envVars = ${JSON.stringify(c.envVars)};\n`
           : "";
-        return `export class ${c.className} extends Container {\n  defaultPort = ${c.port};\n  sleepAfter = "${c.sleepAfter}";\n${envVars}}`;
+        return `export class ${c.className} extends globalThis.__alepha_CloudflareContainer {\n  defaultPort = ${c.port};\n  sleepAfter = "${c.sleepAfter}";\n${envVars}}`;
       })
       .join("\n\n");
 
-    const containerImport =
-      containers.length > 0
-        ? `import { Container } from "@cloudflare/containers";\n\n${containerDeclarations}\n\n`
-        : "";
-
     const workerCode = `
 import "./index.js";
 
@@ -385,11 +671,19 @@ const setWaitUntil = (executionCtx) => {
   }
 };
 
+// Bind the per-invocation Worker \`env\`: keep the full binding (D1, R2, KV, …)
+// in the store for providers, and lift its string values (secrets/vars like
+// PUBLIC_URL) into \`alepha.env\` so \`$env\` resolves them at runtime.
+const bindEnv = (env) => {
+  __alepha.set("cloudflare.env", env);
+  __alepha.loadEnv(env);
+};
+
 export default {
   fetch: async (request, env, executionCtx) => {
     const ctx = { req: request, res: undefined };
 
-    __alepha.set("cloudflare.env", env);
+    bindEnv(env);
     setWaitUntil(executionCtx);
 
     try {
@@ -405,7 +699,7 @@ export default {
   },
 
   scheduled: async (event, env, executionCtx) => {
-    __alepha.set("cloudflare.env", env);
+    bindEnv(env);
     setWaitUntil(executionCtx);
 
     try {
@@ -422,7 +716,7 @@ export default {
   },
 
   queue: async (batch, env, executionCtx) => {
-    __alepha.set("cloudflare.env", env);
+    bindEnv(env);
     setWaitUntil(executionCtx);
 
     try {
@@ -444,9 +738,12 @@ export default {
 };
 `.trim();
 
+    const containerBlock =
+      containers.length > 0 ? `${containerDeclarations}\n\n` : "";
+
     await this.fs.writeFile(
       this.fs.join(root, distDir, "main.cloudflare.js"),
-      `${this.warningComment}\n${containerImport}${workerCode}`.trim(),
+      `${this.warningComment}\n${containerBlock}${workerCode}`.trim(),
     );
   }
 }
@@ -457,7 +754,16 @@ interface ContainerDescriptor {
   image: string;
   port: number;
   sleepAfter: string;
-  instanceType: "dev" | "basic" | "standard";
+  /**
+   * Cloudflare Containers instance class.
+   *
+   * `dev` is the wrangler-pre-GA name; the platform accepts it but
+   * emits a deprecation warning telling you to use `lite`. We
+   * silently translate at write time (see `discoverContainers`
+   * default + `enhanceContainers` write) so older
+   * `$container({ instanceType: "dev" })` declarations keep working.
+   */
+  instanceType: "dev" | "lite" | "basic" | "standard";
   maxInstances: number;
   envVars?: Record<string, string>;
 }

package/src/cli/core/tasks/BuildDockerTask.ts

@@ -73,10 +73,12 @@ export class BuildDockerTask extends BuildTask {
       name: "generate deploy config (docker)",
       handler: async () => {
         const migrationsCopied = await this.copyMigrations(ctx.root, distDir);
+        const hasDeps = await this.hasRuntimeDeps(ctx.root, distDir);
         await this.writeDockerfile(ctx.root, distDir, {
           compile,
           standard: { image: dockerFrom, command: dockerCommand },
           hasMigrations: migrationsCopied,
+          hasDeps,
           install: ctx.options.docker?.install ?? [],
         });
       },
@@ -211,6 +213,28 @@ export class BuildDockerTask extends BuildTask {
     return false;
   }
 
+  /**
+   * Whether the produced `dist/package.json` declares any runtime
+   * dependencies. Alepha apps normally bundle everything into the
+   * server entry via Vite, leaving `dependencies: {}` — in which case
+   * the generated Dockerfile's `RUN npm install` is wasted work
+   * (and emits deprecation noise). Skip the line when empty.
+   */
+  protected async hasRuntimeDeps(
+    root: string,
+    distDir: string,
+  ): Promise<boolean> {
+    try {
+      const pkg = await this.fs.readJsonFile<{
+        dependencies?: Record<string, string>;
+      }>(this.fs.join(root, distDir, "package.json"));
+      return Object.keys(pkg.dependencies ?? {}).length > 0;
+    } catch {
+      // No package.json in dist/ → nothing to install.
+      return false;
+    }
+  }
+
   protected async writeDockerfile(
     root: string,
     distDir: string,
@@ -218,6 +242,7 @@ export class BuildDockerTask extends BuildTask {
       compile: ResolvedCompile | null;
       standard: { image: string; command: string };
       hasMigrations: boolean;
+      hasDeps: boolean;
       install: string[];
     },
   ): Promise<void> {
@@ -244,12 +269,18 @@ ENTRYPOINT ["/app/app"]
 `;
     } else {
       const { image, command } = opts.standard;
+      // Skip `RUN <pm> install` when `dist/package.json` declares no
+      // runtime deps — Alepha apps normally bundle everything via Vite,
+      // making the install a no-op that just emits deprecation noise.
+      const baseInstallLine = opts.hasDeps
+        ? `RUN ${command === "bun" ? "bun" : "npm"} install\n`
+        : "";
       // Install requested packages locally (no --global). They land in
       // `/app/node_modules/`, alongside the app's own deps. Use
       // `--no-save` so we don't mutate the bundled package.json. Node
       // module resolution walks up into `/app/node_modules/` when the
       // workspace lives under `/app/workspace/<deploy-id>/`.
-      const installLine = opts.install.length
+      const extraInstallLine = opts.install.length
         ? `RUN npm install --no-save --no-fund --no-audit ${opts.install.join(" ")}\n`
         : "";
       dockerfile = `${header}FROM ${image}
@@ -257,8 +288,7 @@ WORKDIR /app
 
 COPY . .
 
-RUN ${command === "bun" ? "bun" : "npm"} install
-${installLine}
+${baseInstallLine}${extraInstallLine}
 ENV SERVER_HOST=0.0.0.0
 
 CMD ["${command}", "index.js"]

package/src/cli/core/tasks/BuildTask.ts

@@ -2,6 +2,7 @@ import type { Alepha } from "alepha";
 import type { RunnerMethod } from "alepha/command";
 import type { BuildOptions } from "../atoms/buildOptions.ts";
 import type { AppEntry } from "../providers/AppEntryProvider.ts";
+import type { BuildManifest } from "./BuildCloudflareTask.ts";
 
 export interface BuildTaskContext {
   /**
@@ -43,6 +44,39 @@ export interface BuildTaskContext {
    * Raw CLI flags passed through from the command.
    * Tasks can read flags relevant to their domain.
    */
+  /**
+   * Build-time snapshot of primitive data, read from
+   * `dist/manifest.json`. Populated only in `--prebuilt` mode when a
+   * previous build's manifest is present — lets BuildCloudflareTask
+   * regenerate `wrangler.jsonc` without re-booting the workspace.
+   * `null` when introspection (`ctx.alepha`) is the source of truth.
+   */
+  manifest: BuildManifest | null;
+
+  /**
+   * Resolved `platform({ default, environments, ... })` options from
+   * the workspace's `alepha.config.ts`. Populated by `BuildCommand`
+   * from the CLI's Alepha instance (where alepha.config.ts ran) —
+   * BuildCloudflareTask uses these to write the corresponding fields
+   * into `dist/manifest.json` so the deploy side doesn't need to
+   * re-load `alepha.config.ts`. `null` when no platform options were
+   * declared.
+   */
+  platformOptions: {
+    default?: string;
+    tenancy?: "none" | "optional" | "required";
+    environments?: Record<
+      string,
+      {
+        adapter: "cloudflare" | "vercel";
+        domain?: string;
+        zone?: string;
+        jurisdiction?: "eu" | "fedramp";
+        accountId?: string;
+      }
+    >;
+  } | null;
+
   flags?: {
     image?: boolean | string;
     /**