alepha 0.23.0 → 0.24.0

package/src/cli/core/commands/test.ts

@@ -1,4 +1,4 @@
-import { $inject, t } from "alepha";
+import { $inject, z } from "alepha";
 import { $command } from "alepha/command";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
 import { ProjectScaffolder } from "../services/ProjectScaffolder.ts";
@@ -11,28 +11,25 @@ export class TestCommand {
     name: "test",
     description:
       "Run tests using Vitest. Pass a filter to run only matching specs, e.g. `alepha test user` or `alepha test test/auth.spec.ts`",
-    args: t.optional(
-      t.text({
+    args: z
+      .text({
         title: "filter",
         description: "Only run spec files whose path matches this string",
-      }),
-    ),
-    flags: t.object({
-      config: t.optional(
-        t.string({
-          description: "Path to Vitest config file",
-          alias: "c",
-        }),
-      ),
+      })
+      .optional(),
+    flags: z.object({
+      config: z
+        .string()
+        .meta({ alias: "c" })
+        .describe("Path to Vitest config file")
+        .optional(),
     }),
-    env: t.object({
-      VITEST_ARGS: t.optional(
-        t.string({
-          default: "",
-          description:
-            "Additional arguments to pass to Vitest. E.g., --coverage",
-        }),
-      ),
+    env: z.object({
+      VITEST_ARGS: z
+        .string()
+        .describe("Additional arguments to pass to Vitest. E.g., --coverage")
+        .default("")
+        .optional(),
     }),
     handler: async ({ run, root, flags, env, args }) => {
       await this.scaffolder.ensureConfig(root, {

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

@@ -1,9 +1,8 @@
 import { basename } from "node:path";
 import { $inject } from "alepha";
 import { KV_DEFAULT_BINDING } from "alepha/cache";
-import type { ContainerPrimitive } from "alepha/container";
 import { SEND_EMAIL_DEFAULT_BINDING } from "alepha/email/cloudflare";
-import { QUEUE_DEFAULT_BINDING } from "alepha/queue";
+import { QUEUE_DEFAULT_BINDING, QUEUE_DEFAULT_MAX_RETRIES } from "alepha/queue";
 import type { CronProvider, WorkerdCronProvider } from "alepha/scheduler";
 import { FileSystemProvider } from "alepha/system";
 import { ViteUtils } from "../services/ViteUtils.ts";
@@ -16,6 +15,16 @@ import { BuildTask, type BuildTaskContext } from "./BuildTask.ts";
 // here wouldn't match the one the workspace registered.
 const CLOUDFLARE_EMAIL_PROVIDER_NAME = "CloudflareEmailProvider";
 
+/**
+ * Best-effort Cloudflare zone (registrable domain) for a wildcard Worker route:
+ * strip the leading `*.` and any subdomain labels, keep the last two — e.g.
+ * `*.club.alepha.dev` → `alepha.dev`, `*.alepha.club` → `alepha.club`. Correct
+ * for single-label TLDs (the common case); a multi-label public suffix
+ * (`.co.uk`) or a CF subdomain zone needs an explicit `CLOUDFLARE_ZONE`.
+ */
+const deriveZone = (domain: string): string =>
+  domain.replace(/^\*\./, "").split(".").slice(-2).join(".");
+
 interface WranglerConfig {
   [key: string]: any;
 }
@@ -82,21 +91,6 @@ export interface BuildManifest {
    * app doesn't use Cloudflare email.
    */
   email?: { binding: 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
@@ -184,13 +178,13 @@ export class BuildCloudflareTask extends BuildTask {
     };
 
     this.enhanceDomain(wrangler);
+    this.enhanceServices(wrangler);
     this.enhanceCron(ctx, wrangler);
     this.enhanceDatabase(wrangler);
     this.enhanceR2(wrangler);
     this.enhanceKV(wrangler);
     this.enhanceQueue(wrangler);
     this.enhanceEmail(ctx, wrangler);
-    const containers = this.enhanceContainers(ctx, wrangler);
 
     await this.fs.writeFile(
       this.fs.join(root, distDir, "wrangler.jsonc"),
@@ -202,9 +196,9 @@ export class BuildCloudflareTask extends BuildTask {
     // 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.writeManifest(ctx, root, distDir, name);
     }
-    await this.writeWorkerEntryPoint(root, distDir, containers);
+    await this.writeWorkerEntryPoint(root, distDir);
   }
 
   /**
@@ -219,7 +213,6 @@ export class BuildCloudflareTask extends BuildTask {
     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
@@ -309,15 +302,6 @@ export class BuildCloudflareTask extends BuildTask {
         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,
-      })),
       email,
       env,
     };
@@ -328,6 +312,21 @@ export class BuildCloudflareTask extends BuildTask {
     );
   }
 
+  /** Worker-to-worker service bindings, from CLOUDFLARE_SERVICES (JSON). */
+  protected enhanceServices(wrangler: WranglerConfig): void {
+    const raw = process.env.CLOUDFLARE_SERVICES;
+    if (!raw) {
+      return;
+    }
+    const services = JSON.parse(raw) as Array<{
+      binding: string;
+      service: string;
+    }>;
+    if (services.length > 0) {
+      (wrangler as { services?: unknown }).services = services;
+    }
+  }
+
   protected enhanceDomain(wrangler: WranglerConfig): void {
     const domain = process.env.CLOUDFLARE_DOMAIN;
     if (!domain) {
@@ -335,12 +334,13 @@ export class BuildCloudflareTask extends BuildTask {
     }
 
     if (domain.includes("*")) {
-      const zone = process.env.CLOUDFLARE_ZONE;
-      if (!zone) {
-        throw new Error(
-          `Wildcard domain "${domain}" requires CLOUDFLARE_ZONE to be set (the parent zone name, e.g. "alepha.dev").`,
-        );
-      }
+      // A wildcard is a Worker *Route* (not a Custom Domain), and the CF API
+      // keys routes by zone. Default the zone to the registrable domain — the
+      // last two labels of the wildcard host (`*.club.alepha.dev` → `alepha.dev`,
+      // `*.alepha.club` → `alepha.club`). Set CLOUDFLARE_ZONE explicitly only to
+      // override (a subdomain zone, or a multi-label public suffix like `.co.uk`
+      // where "last two labels" is wrong).
+      const zone = process.env.CLOUDFLARE_ZONE || deriveZone(domain);
       wrangler.routes = [
         {
           pattern: domain.endsWith("/*") ? domain : `${domain}/*`,
@@ -350,6 +350,22 @@ export class BuildCloudflareTask extends BuildTask {
       return;
     }
 
+    // An explicit CLOUDFLARE_ZONE forces a zone *Route* for a non-wildcard
+    // host too. Needed when the host is ALSO covered by another Worker's
+    // wildcard route on the same zone: Cloudflare evaluates Routes before
+    // Custom Domains, but among routes the most specific pattern wins — so
+    // `app.club.alepha.dev/*` beats the pooled `*.club.alepha.dev/*`, while a
+    // Custom Domain on that host would lose to the wildcard route entirely.
+    if (process.env.CLOUDFLARE_ZONE) {
+      wrangler.routes = [
+        {
+          pattern: `${domain}/*`,
+          zone_name: process.env.CLOUDFLARE_ZONE,
+        },
+      ];
+      return;
+    }
+
     wrangler.routes = [
       {
         pattern: domain,
@@ -403,13 +419,15 @@ export class BuildCloudflareTask extends BuildTask {
 
     const [dbName, id] = url.replace("d1://", "").replace("d1:", "").split(":");
     const binding = BuildCloudflareTask.D1_BINDING;
-    const jurisdiction = process.env.CLOUDFLARE_JURISDICTION;
+    // No `jurisdiction` here: unlike r2_buckets, the wrangler D1 binding schema
+    // has no jurisdiction field (it warns on the unexpected key). D1 data
+    // residency is fixed when the database is created — see CloudflareApi —
+    // and the binding just references it by `database_id`.
     wrangler.d1_databases = wrangler.d1_databases || [];
     wrangler.d1_databases.push({
       binding,
       database_name: dbName,
       database_id: id,
-      ...(jurisdiction ? { jurisdiction } : {}),
     });
     wrangler.vars ??= {};
     wrangler.vars.DATABASE_URL = `d1://${binding}`;
@@ -479,9 +497,22 @@ export class BuildCloudflareTask extends BuildTask {
       binding: QUEUE_DEFAULT_BINDING,
       queue: queueName,
     });
+
+    // The worker's queue handler calls `msg.retry()` on any throw. Cloudflare
+    // only gives a failing message somewhere to land if the consumer declares a
+    // `dead_letter_queue` — otherwise it burns `max_retries` and DISCARDS the
+    // message, with no record and no signal. CF creates the DLQ on demand, so a
+    // derived default is safe.
+    const maxRetries = Number(process.env.CLOUDFLARE_QUEUE_MAX_RETRIES);
+
     wrangler.queues.consumers = wrangler.queues.consumers || [];
     wrangler.queues.consumers.push({
       queue: queueName,
+      dead_letter_queue:
+        process.env.CLOUDFLARE_QUEUE_DLQ_NAME || `${queueName}-dlq`,
+      max_retries: Number.isSafeInteger(maxRetries)
+        ? maxRetries
+        : QUEUE_DEFAULT_MAX_RETRIES,
     });
   }
 
@@ -529,166 +560,28 @@ export class BuildCloudflareTask extends BuildTask {
     wrangler.send_email.push({ name: binding });
   }
 
-  /**
-   * Discover `$container` primitives and emit the matching Cloudflare
-   * Containers bindings, Durable Object bindings, and migrations into
-   * `wrangler.jsonc`. The DO class declarations are added later, when
-   * the worker entry point is written.
-   *
-   * Returns the list of container descriptors so
-   * `writeWorkerEntryPoint` can emit `export class <NAME> extends
-   * Container` declarations referencing them.
-   */
-  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",
-    ) as ContainerPrimitive[];
-    return primitives.map((p) => ({
-      name: p.name.toUpperCase(),
-      className: p.name
-        .split(/[^a-zA-Z0-9]/)
-        .filter(Boolean)
-        .map((s) => s[0]!.toUpperCase() + s.slice(1))
-        .join(""),
-      image: p.options.image,
-      port: p.options.port ?? 3000,
-      sleepAfter:
-        typeof p.options.sleepAfter === "string" ? p.options.sleepAfter : "15m",
-      // `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 || {};
-    wrangler.durable_objects.bindings = wrangler.durable_objects.bindings || [];
-    wrangler.migrations = wrangler.migrations || [];
-
-    const newSqliteClasses: string[] = [];
-    for (const d of descriptors) {
-      wrangler.containers.push({
-        class_name: d.className,
-        image: this.resolveContainerImage(d.image),
-        instance_type: d.instanceType,
-        max_instances: d.maxInstances,
-      });
-      wrangler.durable_objects.bindings.push({
-        name: d.name,
-        class_name: d.className,
-      });
-      newSqliteClasses.push(d.className);
-    }
-
-    if (newSqliteClasses.length > 0) {
-      wrangler.migrations.push({
-        tag: "containers-v1",
-        new_sqlite_classes: newSqliteClasses,
-      });
-    }
-
-    return descriptors;
-  }
-
   protected async writeWorkerEntryPoint(
     root: string,
     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 globalThis.__alepha_CloudflareContainer {\n  defaultPort = ${c.port};\n  sleepAfter = "${c.sleepAfter}";\n${envVars}}`;
-      })
-      .join("\n\n");
-
     const workerCode = `
 import "./index.js";
 
-// Stash the per-invocation \`executionCtx.waitUntil\` in the Alepha store
-// so background work (notably $job direct dispatch) can keep the isolate
-// alive past the response.
-const setWaitUntil = (executionCtx) => {
-  if (executionCtx && typeof executionCtx.waitUntil === "function") {
-    __alepha.set("cloudflare.waitUntil", (p) => executionCtx.waitUntil(p));
-  } else {
-    __alepha.set("cloudflare.waitUntil", undefined);
-  }
+// Run an invocation inside an Alepha fork carrying THIS invocation's
+// \`executionCtx.waitUntil\`, so background work (notably $job direct dispatch)
+// can keep the isolate alive past the response.
+//
+// It must be the async context, never the shared store: one isolate serves
+// concurrent invocations, so a store slot would let request B overwrite
+// request A's handle — A's background work would then call B's already-returned
+// context ("waitUntil after response") and be silently dropped.
+const withExecutionContext = (executionCtx, fn) => {
+  const waitUntil =
+    executionCtx && typeof executionCtx.waitUntil === "function"
+      ? (p) => executionCtx.waitUntil(p)
+      : undefined;
+
+  return __alepha.context.run(fn, { "cloudflare.waitUntil": waitUntil });
 };
 
 // Bind the per-invocation Worker \`env\`: keep the full binding (D1, R2, KV, …)
@@ -704,7 +597,6 @@ export default {
     const ctx = { req: request, res: undefined };
 
     bindEnv(env);
-    setWaitUntil(executionCtx);
 
     try {
       await __alepha.start();
@@ -713,14 +605,15 @@ export default {
       return new Response("Internal Server Error", { status: 500 });
     }
 
-    await __alepha.events.emit("web:request", ctx);
+    await withExecutionContext(executionCtx, () =>
+      __alepha.events.emit("web:request", ctx),
+    );
 
     return ctx.res;
   },
 
   scheduled: async (event, env, executionCtx) => {
     bindEnv(env);
-    setWaitUntil(executionCtx);
 
     try {
       await __alepha.start();
@@ -729,15 +622,16 @@ export default {
       throw err;
     }
 
-    await __alepha.events.emit("cloudflare:scheduled", {
-      cron: event.cron,
-      scheduledTime: event.scheduledTime,
-    });
+    await withExecutionContext(executionCtx, () =>
+      __alepha.events.emit("cloudflare:scheduled", {
+        cron: event.cron,
+        scheduledTime: event.scheduledTime,
+      }),
+    );
   },
 
   queue: async (batch, env, executionCtx) => {
     bindEnv(env);
-    setWaitUntil(executionCtx);
 
     try {
       await __alepha.start();
@@ -746,44 +640,23 @@ export default {
       throw err;
     }
 
-    for (const msg of batch.messages) {
-      try {
-        await __alepha.events.emit("cloudflare:queue", msg.body);
-        msg.ack();
-      } catch (e) {
-        msg.retry();
+    await withExecutionContext(executionCtx, async () => {
+      for (const msg of batch.messages) {
+        try {
+          await __alepha.events.emit("cloudflare:queue", msg.body);
+          msg.ack();
+        } catch (e) {
+          msg.retry();
+        }
       }
-    }
+    });
   },
 };
 `.trim();
 
-    const containerBlock =
-      containers.length > 0 ? `${containerDeclarations}\n\n` : "";
-
     await this.fs.writeFile(
       this.fs.join(root, distDir, "main.cloudflare.js"),
-      `${this.warningComment}\n${containerBlock}${workerCode}`.trim(),
+      `${this.warningComment}\n${workerCode}`.trim(),
     );
   }
 }
-
-interface ContainerDescriptor {
-  name: string;
-  className: string;
-  image: string;
-  port: number;
-  sleepAfter: string;
-  /**
-   * 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/templates/apiHelloResponseSchemaTs.ts

@@ -1,9 +1,9 @@
 export const apiHelloResponseSchemaTs = () => {
-  return `import { type Static, t } from "alepha";
+  return `import { type Static, z } from "alepha";
 
-export const helloResponseSchema = t.object({
-  appName: t.text(),
-  serverTime: t.datetime(),
+export const helloResponseSchema = z.object({
+  appName: z.text(),
+  serverTime: z.datetime(),
 });
 
 export type HelloResponse = Static<typeof helloResponseSchema>;

package/src/cli/devtools/atoms/devtoolsOptions.ts

@@ -1,4 +1,4 @@
-import { $atom, type Static, t } from "alepha";
+import { $atom, type Static, z } from "alepha";
 
 /**
  * Devtools configuration atom.
@@ -8,16 +8,16 @@ import { $atom, type Static, t } from "alepha";
 export const devtoolsOptions = $atom({
   name: "alepha.cli.devtools.options",
   description: "Devtools plugin configuration",
-  schema: t.optional(
-    t.object({
+  schema: z
+    .object({
       /**
        * Hide the floating devtools button in the browser.
        *
        * The devtools UI is still accessible at `/__devtools/`.
        */
-      hideButton: t.optional(t.boolean({ default: false })),
-    }),
-  ),
+      hideButton: z.boolean().default(false).optional(),
+    })
+    .optional(),
 });
 
 /**

package/src/cli/i18n/atoms/i18nOptions.ts

@@ -1,4 +1,4 @@
-import { $atom, type Static, t } from "alepha";
+import { $atom, type Static, z } from "alepha";
 
 /**
  * i18n CLI configuration atom.
@@ -9,15 +9,15 @@ import { $atom, type Static, t } from "alepha";
 export const i18nOptions = $atom({
   name: "alepha.cli.i18n.options",
   description: "i18n unused-key check configuration",
-  schema: t.optional(
-    t.object({
+  schema: z
+    .object({
       /**
        * Directories (relative to the project root) to scan both for
        * `$dictionary(...)` declarations and for translation key usage.
        *
        * @default ["src"]
        */
-      scan: t.optional(t.array(t.text())),
+      scan: z.array(z.text()).optional(),
 
       /**
        * Key prefixes that are constructed at runtime (e.g. via template
@@ -30,7 +30,7 @@ export const i18nOptions = $atom({
        *
        * @default []
        */
-      dynamicPrefixes: t.optional(t.array(t.text())),
+      dynamicPrefixes: z.array(z.text()).optional(),
 
       /**
        * Additional path substrings (matched against the full file
@@ -40,9 +40,9 @@ export const i18nOptions = $atom({
        *
        * @default []
        */
-      exclude: t.optional(t.array(t.text())),
-    }),
-  ),
+      exclude: z.array(z.text()).optional(),
+    })
+    .optional(),
 });
 
 /**