alepha 0.21.2 → 0.22.0

package/src/cli/{platform → platform-lib}/services/PlatformOrchestrator.ts

@@ -1,15 +1,21 @@
 import { $inject, Alepha, AlephaError } from "alepha";
+import type { AppEntry } from "alepha/cli";
 import type { RunnerMethod } from "alepha/command";
 import { $logger, ConsoleColorProvider } from "alepha/logger";
 import { CloudflareAdapter } from "../adapters/CloudflareAdapter.ts";
 import type {
-  AppDefinition,
+  DetectedResources,
   PlatformAdapter,
   PlatformContext,
   PlatformState,
 } from "../adapters/PlatformAdapter.ts";
 import { VercelAdapter } from "../adapters/VercelAdapter.ts";
-import { type NamingContext, NamingService } from "./NamingService.ts";
+import {
+  type NamingContext,
+  NamingService,
+  resolveTenant,
+  tenantDomain,
+} from "./NamingService.ts";
 import {
   PlatformInspector,
   type ResolvedPlatformConfig,
@@ -52,7 +58,8 @@ export class PlatformOrchestrator {
   public async up(options: {
     root: string;
     env: string;
-    apps: AppDefinition[];
+    entry: AppEntry;
+    resources: DetectedResources;
     run: RunnerMethod;
     /**
      * Pre-built mode — the artifact's `dist/` is already produced.
@@ -66,54 +73,43 @@ export class PlatformOrchestrator {
      * per-tenant overrides on every deploy.
      */
     prebuilt?: boolean;
+    /** Tenant slug (apps with tenancy optional|required). */
+    tenant?: string;
   }): Promise<{ urls: string[]; domain?: string }> {
-    const { root, env, apps, run, prebuilt } = options;
+    const { root, env, entry, resources, run, prebuilt } = options;
     const envConfig = await this.inspector.resolveEnvironment(root, env);
     const config = await this.inspector.resolveConfig(root);
     const adapter = this.resolveAdapter(envConfig.adapter);
-    const namingCtx = this.naming.forContext(config.project, env);
+    const tenant = resolveTenant(config.tenancy, options.tenant);
+    const namingCtx = this.naming.forContext(config.project, env, tenant);
 
     const ctx: PlatformContext = {
       project: config.project,
       env,
       envConfig,
-      apps,
       root,
+      entry,
+      resources,
       naming: namingCtx,
+      tenant,
       prebuilt,
     };
 
-    // 1. Auth
     await adapter.authenticate(ctx, run);
-
-    // 2. Provision (before build so resource IDs are available for wrangler config)
     await adapter.provision(ctx, run);
-
-    // 3. Build
-    //    Always runs — the adapter checks `ctx.prebuilt` to decide whether
-    //    to do a full bundle build or just regenerate deploy config.
-    for (const a of apps) {
-      await adapter.build({ ...ctx, app: a }, run);
-    }
-
-    // 4. Migrate
+    // `build` always runs — adapter checks `ctx.prebuilt` to decide
+    // whether to do a full bundle build or only regenerate deploy config.
+    await adapter.build(ctx, run);
     await adapter.migrate(ctx, run);
-
-    // 5. Deploy
-    const urls: string[] = [];
-    for (const a of apps) {
-      const url = await adapter.deploy({ ...ctx, app: a }, run);
-      if (url) {
-        urls.push(url);
-      }
-    }
-
-    // 6. Secrets (push .env.{env} secrets to deployed workers)
+    const url = await adapter.deploy(ctx, run);
     await adapter.secrets(ctx, run);
 
     run.end();
 
-    return { urls, domain: envConfig.domain };
+    return {
+      urls: url ? [url] : [],
+      domain: tenantDomain(envConfig.domain, tenant),
+    };
   }
 
   /**
@@ -146,23 +142,29 @@ export class PlatformOrchestrator {
   public async down(options: {
     root: string;
     env: string;
-    apps: AppDefinition[];
+    entry: AppEntry;
+    resources: DetectedResources;
     run: RunnerMethod;
     confirm: (prompt: string) => Promise<string>;
+    /** Tenant slug (apps with tenancy optional|required). */
+    tenant?: string;
   }): Promise<boolean> {
-    const { root, env, apps, run, confirm } = options;
+    const { root, env, entry, resources, run, confirm } = options;
     const envConfig = await this.inspector.resolveEnvironment(root, env);
     const config = await this.inspector.resolveConfig(root);
     const adapter = this.resolveAdapter(envConfig.adapter);
-    const namingCtx = this.naming.forContext(config.project, env);
+    const tenant = resolveTenant(config.tenancy, options.tenant);
+    const namingCtx = this.naming.forContext(config.project, env, tenant);
 
     const ctx: PlatformContext = {
       project: config.project,
       env,
       envConfig,
-      apps,
       root,
+      entry,
+      resources,
       naming: namingCtx,
+      tenant,
     };
 
     // Confirm (skip for tmp envs)
@@ -192,16 +194,19 @@ export class PlatformOrchestrator {
   public async plan(options: {
     root: string;
     env: string;
-    apps: AppDefinition[];
+    resources: DetectedResources;
+    /** Tenant slug (apps with tenancy optional|required). */
+    tenant?: string;
   }): Promise<{
     config: ResolvedPlatformConfig;
     naming: NamingContext;
-    apps: AppDefinition[];
+    resources: DetectedResources;
   }> {
-    const { root, env, apps } = options;
+    const { root, env, resources } = options;
     const config = await this.inspector.resolveConfig(root);
-    const namingCtx = this.naming.forContext(config.project, env);
-    return { config, naming: namingCtx, apps };
+    const tenant = resolveTenant(config.tenancy, options.tenant);
+    const namingCtx = this.naming.forContext(config.project, env, tenant);
+    return { config, naming: namingCtx, resources };
   }
 
   // -------------------------------------------------------------------------
@@ -211,22 +216,28 @@ export class PlatformOrchestrator {
   public async status(options: {
     root: string;
     env: string;
-    apps: AppDefinition[];
+    entry: AppEntry;
+    resources: DetectedResources;
     run: RunnerMethod;
+    /** Tenant slug (apps with tenancy optional|required). */
+    tenant?: string;
   }): Promise<{ config: ResolvedPlatformConfig; state: PlatformState }> {
-    const { root, env, apps, run } = options;
+    const { root, env, entry, resources, run } = options;
     const envConfig = await this.inspector.resolveEnvironment(root, env);
     const config = await this.inspector.resolveConfig(root);
     const adapter = this.resolveAdapter(envConfig.adapter);
-    const namingCtx = this.naming.forContext(config.project, env);
+    const tenant = resolveTenant(config.tenancy, options.tenant);
+    const namingCtx = this.naming.forContext(config.project, env, tenant);
 
     const ctx: PlatformContext = {
       project: config.project,
       env,
       envConfig,
-      apps,
       root,
+      entry,
+      resources,
       naming: namingCtx,
+      tenant,
     };
 
     await adapter.authenticate(ctx, run);

package/src/cli/{platform → platform-lib}/services/WranglerApi.ts

@@ -98,10 +98,11 @@ export class WranglerApi {
   public async deploy(
     workerName: string,
     configPath: string,
+    root?: string,
   ): Promise<string | undefined> {
     const output = await this.runShell(
       `wrangler deploy --name=${workerName} --no-bundle --config=${configPath}`,
-      { resolve: true, capture: true },
+      { resolve: true, capture: true, root },
     );
 
     const match = output.match(/https:\/\/[^\s]*\.workers\.dev/);
@@ -118,10 +119,11 @@ export class WranglerApi {
   public async d1MigrationsApply(
     dbName: string,
     configPath: string,
+    root?: string,
   ): Promise<void> {
     await this.runShell(
       `wrangler d1 migrations apply ${dbName} --remote --config=${configPath}`,
-      { resolve: true, env: { CI: "1" } },
+      { resolve: true, env: { CI: "1" }, root },
     );
   }
 }

package/src/command/__tests__/Runner.spec.ts

@@ -37,6 +37,26 @@ describe("Runner", () => {
     vi.clearAllMocks();
   });
 
+  test("useDynamicLogger: state overrides disable the stylish UI even with LOG_FORMAT=raw", () => {
+    // env says "raw" (stylish), but a runtime state override (what the CLI
+    // `--verbose` flag sets) must win. Asserting the *false* direction is
+    // deterministic across CI/non-CI (the dynamic-on path is gated on isCI).
+    const alepha = Alepha.create({
+      env: { LOG_LEVEL: "info", LOG_FORMAT: "raw" },
+    }).with({
+      provide: LogDestinationProvider,
+      use: MemoryDestinationProvider,
+    });
+    const r = alepha.inject(Runner);
+
+    alepha.store.set("alepha.logger.format", "pretty");
+    expect(r.useDynamicLogger).toBe(false);
+
+    alepha.store.set("alepha.logger.format", undefined);
+    alepha.store.set("alepha.logger.level", "debug");
+    expect(r.useDynamicLogger).toBe(false);
+  });
+
   test("should execute a single shell command via run.sh", async () => {
     await runner.run(`echo "hello"`);
 

package/src/command/helpers/EnvUtils.ts

@@ -52,11 +52,27 @@ export class EnvUtils {
               const trimmedKey = key.trim();
               if (trimmedKey && !trimmedKey.startsWith("#")) {
                 let value = rest.join("=").trim();
-                // Strip matching surrounding quotes (single or double)
+                const last = value.length - 1;
                 if (
                   value.length >= 2 &&
-                  ((value[0] === '"' && value[value.length - 1] === '"') ||
-                    (value[0] === "'" && value[value.length - 1] === "'"))
+                  value[0] === '"' &&
+                  value[last] === '"'
+                ) {
+                  // Double-quoted: JSON-decode so escapes round-trip with a
+                  // `JSON.stringify`-based writer (e.g. Rocket's
+                  // `.env.<env>.local` overrides, which write JSON values like
+                  // CLUB_CONFIG_JSON). Falls back to a naive strip when the
+                  // body isn't valid JSON (e.g. a Windows path with `\`), so
+                  // simple `KEY="value"` still behaves as before.
+                  try {
+                    value = JSON.parse(value);
+                  } catch {
+                    value = value.slice(1, -1);
+                  }
+                } else if (
+                  value.length >= 2 &&
+                  value[0] === "'" &&
+                  value[last] === "'"
                 ) {
                   value = value.slice(1, -1);
                 }

package/src/command/helpers/Runner.ts

@@ -78,12 +78,22 @@ export class Runner {
       return false;
     }
 
-    const logLevel = String(this.alepha.env.LOG_LEVEL || "").toLowerCase();
+    // Runtime state overrides the env defaults (e.g. the CLI `--verbose`
+    // flag sets level=debug + format=pretty), so a flag can flip the
+    // stylish task UI off without restarting with LOG_* env vars.
+    const logLevel = String(
+      this.alepha.store.get("alepha.logger.level") ??
+        this.alepha.env.LOG_LEVEL ??
+        "",
+    ).toLowerCase();
     if (logLevel === "debug" || logLevel === "trace") {
       return false;
     }
 
-    return this.alepha.env.LOG_FORMAT === "raw";
+    const format =
+      this.alepha.store.get("alepha.logger.format") ??
+      this.alepha.env.LOG_FORMAT;
+    return format === "raw";
   }
 
   /**

package/src/command/providers/CliProvider.ts

@@ -145,6 +145,13 @@ export class CliProvider {
       description: "Show this help message",
       schema: t.boolean(),
     },
+    verbose: {
+      // No `-v` alias — it collides with `--version` on the root command.
+      aliases: ["verbose"],
+      description:
+        "Verbose output: debug logs in plain pretty format (turns off the dynamic CLI UI).",
+      schema: t.boolean(),
+    },
   };
 
   // ─────────────────────────────────────────────────────────────────────────────
@@ -175,6 +182,14 @@ export class CliProvider {
         { strict: false }, // Don't throw for command-specific flags
       );
 
+      // `--verbose` → flip the logger to debug + plain pretty output via
+      // state (read live by Logger + Runner). Set before the command runs
+      // so its output and task UI honor it.
+      if (globalFlags.verbose) {
+        this.alepha.store.set("alepha.logger.level", "debug");
+        this.alepha.store.set("alepha.logger.format", "pretty");
+      }
+
       if (globalFlags.help) {
         this.printHelp(command);
         return;
@@ -552,10 +567,28 @@ export class CliProvider {
       });
     }
 
+    // Tolerate global flags (--help, --verbose) so strict command parsing
+    // doesn't reject them — they're consumed by the onReady global pass,
+    // not by the command. Skip any whose alias the command already claims
+    // (e.g. a command with its own `verbose` flag handles it directly).
+    const claimed = new Set(flagDefs.flatMap((d) => d.aliases));
+    for (const [key, value] of Object.entries(this.getAllGlobalFlags())) {
+      if (value.aliases.some((a: string) => claimed.has(a))) continue;
+      flagDefs.push({
+        key: `__global_${key}__`,
+        aliases: value.aliases,
+        description: undefined,
+        schema: value.schema,
+      });
+    }
+
     const parsed = this.parseFlags(argv, flagDefs);
 
-    // Remove the mode flag from parsed result (it's handled separately)
+    // Remove the mode + global flags from parsed result (handled separately)
     parsed.__mode__ = undefined;
+    for (const key of Object.keys(parsed)) {
+      if (key.startsWith("__global_")) delete parsed[key];
+    }
 
     // apply manually defaults for optional properties that have defaults
     for (const [key, value] of Object.entries(schema.properties)) {

package/src/{containers → container}/core/__tests__/$container.spec.ts

@@ -2,7 +2,7 @@ import { Alepha, t } from "alepha";
 import { $action, AlephaServer } from "alepha/server";
 import { AlephaServerLinks } from "alepha/server/links";
 import { describe, it } from "vitest";
-import { AlephaContainers } from "../index.ts";
+import { AlephaContainer } from "../index.ts";
 import { $container } from "../primitives/$container.ts";
 import { ContainerProvider } from "../providers/ContainerProvider.ts";
 import { NodeContainerProvider } from "../providers/NodeContainerProvider.ts";
@@ -28,13 +28,13 @@ describe("$container", () => {
       });
     }
 
-    // In test mode AlephaContainers binds the Mock provider by default,
+    // In test mode AlephaContainer binds the Mock provider by default,
     // which routes the proxy's `.createJob(...)` call back through
     // LinkProvider — so RocketController must live on the same Alepha.
     const alepha = Alepha.create({ env: { LOG_LEVEL: "warn" } })
       .with(AlephaServer)
       .with(AlephaServerLinks)
-      .with(AlephaContainers)
+      .with(AlephaContainer)
       .with(RocketController)
       .with(DeployService);
 
@@ -55,7 +55,7 @@ describe("$container", () => {
       });
     }
 
-    const alepha = Alepha.create({ env: {} }).with(AlephaContainers).with(App);
+    const alepha = Alepha.create({ env: {} }).with(AlephaContainer).with(App);
 
     // Force App instantiation so the primitive registers.
     const app = alepha.inject(App);
@@ -71,7 +71,7 @@ describe("$container", () => {
 
     const alepha = Alepha.create({ env: {} })
       .with({ provide: ContainerProvider, use: NodeContainerProvider })
-      .with(AlephaContainers)
+      .with(AlephaContainer)
       .with(App);
     await alepha.start();
 

package/src/{containers → container}/core/index.ts

@@ -24,7 +24,7 @@ export * from "./providers/NodeContainerProvider.ts";
  * - Pluggable transport: Node (plain `fetch` against a configured URL),
  *   Mock (in-process call via `LinkProvider.follow` for tests),
  *   Cloudflare workerd (`getContainer().fetch()` through the Containers
- *   binding — see `alepha/containers` workerd entry).
+ *   binding — see `alepha/container` workerd entry).
  * - Build-time integration: `BuildCloudflareTask.enhanceContainers`
  *   emits the matching wrangler bindings and Durable Object class
  *   declarations.
@@ -33,10 +33,10 @@ export * from "./providers/NodeContainerProvider.ts";
  * the spec — apps need to provide an explicit `url` per primitive
  * until a `target=docker` adapter ships.
  *
- * @module alepha.containers
+ * @module alepha.container
  */
-export const AlephaContainers = $module({
-  name: "alepha.containers",
+export const AlephaContainer = $module({
+  name: "alepha.container",
   primitives: [$container],
   services: [ContainerProvider],
   variants: [MockContainerProvider, NodeContainerProvider],

package/src/{containers → container}/core/index.workerd.ts

@@ -1,8 +1,24 @@
+import { Container } from "@cloudflare/containers";
 import { $module } from "alepha";
 import { $container } from "./primitives/$container.ts";
 import { CloudflareContainerProvider } from "./providers/CloudflareContainerProvider.ts";
 import { ContainerProvider } from "./providers/ContainerProvider.ts";
 
+// Stash the Cloudflare Containers `Container` base class on globalThis
+// so `BuildCloudflareTask`'s post-Vite-emitted entry
+// (`dist/main.cloudflare.js`) can declare
+// `class <T> extends globalThis.__alepha_CloudflareContainer` without
+// introducing a bare `@cloudflare/containers` specifier.
+//
+// The entry is written AFTER Vite — anything Vite hasn't seen
+// survives as an unresolved import all the way to workerd (where the
+// upload is `no_bundle: true`). This side-effect runs whenever an app
+// imports anything from `alepha/container` (Vite picks this file via
+// the `workerd` export condition), so by the time the entry's
+// `import "./index.js"` finishes, the global is set and the
+// `extends` expression resolves.
+(globalThis as any).__alepha_CloudflareContainer = Container;
+
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./interfaces/ContainerOptions.ts";
@@ -21,10 +37,10 @@ export * from "./providers/ContainerProvider.ts";
  * `BuildCloudflareTask.enhanceContainers` (in `alepha/cli/core`) which
  * emits the wrangler.jsonc bindings and DO class declarations.
  *
- * @module alepha.containers
+ * @module alepha.container
  */
-export const AlephaContainers = $module({
-  name: "alepha.containers",
+export const AlephaContainer = $module({
+  name: "alepha.container",
   primitives: [$container],
   services: [ContainerProvider, CloudflareContainerProvider],
   register: (alepha) => {

package/src/{containers → container}/core/primitives/$container.ts

@@ -23,7 +23,7 @@ import { ContainerProvider } from "../providers/ContainerProvider.ts";
  *
  * @example
  * ```ts
- * import { $container } from "alepha/containers";
+ * import { $container } from "alepha/container";
  * import type { RocketController } from "@alepha/rocket";
  *
  * class DeployService {

package/src/{containers → container}/core/providers/CloudflareContainerProvider.ts

@@ -1,3 +1,4 @@
+import { getContainer } from "@cloudflare/containers";
 import { $inject, Alepha, AlephaError } from "alepha";
 import type { ContainerPrimitive } from "../primitives/$container.ts";
 import {
@@ -8,15 +9,18 @@ import {
 /**
  * Cloudflare Workers (workerd) container provider.
  *
- * Routes proxy calls through the Cloudflare Containers binding bound on
- * `env.<NAME>`, using a single shared instance per container
- * (`getContainer(env.NAME, "shared")`). The binding is generated by
- * `BuildCloudflareTask.enhanceContainers` from the `$container`
- * primitives discovered in the app.
+ * Routes proxy calls through the Cloudflare Containers binding bound
+ * on `env.<NAME>`, using a single shared instance per container.
+ * `getContainer` from `@cloudflare/containers` is a free function (not
+ * a method on the binding) — it takes the DO namespace and an id and
+ * returns a stub with a `.fetch()` method targeting the running
+ * container instance.
  *
- * The runtime `env` object is pulled from the Alepha store key
- * `cloudflare.env` — the worker entry point publishes it there on every
- * fetch (`__alepha.set("cloudflare.env", env)`).
+ * The binding is generated by `BuildCloudflareTask.enhanceContainers`
+ * from the `$container` primitives discovered in the app. The runtime
+ * `env` object is pulled from the Alepha store key `cloudflare.env`
+ * — the worker entry point publishes it there on every fetch
+ * (`__alepha.set("cloudflare.env", env)`).
  */
 export class CloudflareContainerProvider extends ContainerProvider {
   protected readonly alepha = $inject(Alepha);
@@ -35,21 +39,15 @@ export class CloudflareContainerProvider extends ContainerProvider {
       );
     }
 
-    const binding = env[container.name.toUpperCase()] as
-      | {
-          getContainer?: (id: string) => {
-            fetch(req: Request): Promise<Response>;
-          };
-        }
-      | undefined;
-
-    if (!binding?.getContainer) {
+    const bindingName = container.name.toUpperCase();
+    const binding = env[bindingName];
+    if (!binding) {
       throw new AlephaError(
-        `Cloudflare Containers binding '${container.name.toUpperCase()}' not found on env — check wrangler.jsonc.`,
+        `Cloudflare Containers binding '${bindingName}' not found on env — check wrangler.jsonc.`,
       );
     }
 
-    const instance = binding.getContainer("shared");
+    const instance = getContainer(binding as never, "shared");
     const { path, init } = this.buildRequest(action, config);
     const request = new Request(`http://container${path}`, init);
     const response = await instance.fetch(request);

package/src/{containers → container}/core/providers/ContainerProvider.ts

@@ -33,7 +33,7 @@ export abstract class ContainerProvider {
     void config;
     throw new AlephaError(
       `No ContainerProvider configured for container '${container.name}' (action '${action}'). ` +
-        `Set up alepha/containers via AlephaContainers and either supply 'url' (Node) or build for target=cloudflare.`,
+        `Set up alepha/container via AlephaContainer and either supply 'url' (Node) or build for target=cloudflare.`,
     );
   }
 
@@ -54,11 +54,25 @@ export abstract class ContainerProvider {
       }
     }
 
+    // Match the route Alepha generates server-side when no explicit
+    // `path:` is set on `$action`: `/${name}` with one `/:<key>`
+    // segment appended per param. Params that match a `:key`
+    // placeholder are substituted in place; any remaining params are
+    // appended in declaration order so `params: {id:"abc"}` against a
+    // proxy action `getDeploy` yields `/api/getDeploy/abc`.
     let path = `/api/${action}`;
     if (config.params) {
+      const tail: string[] = [];
       for (const [k, v] of Object.entries(config.params)) {
-        path = path.replace(`:${k}`, encodeURIComponent(String(v)));
+        const placeholder = `:${k}`;
+        const encoded = encodeURIComponent(String(v));
+        if (path.includes(placeholder)) {
+          path = path.replace(placeholder, encoded);
+        } else {
+          tail.push(encoded);
+        }
       }
+      if (tail.length) path += `/${tail.join("/")}`;
     }
 
     const search = params.toString();

package/src/{containers → container}/core/providers/MockContainerProvider.ts

@@ -17,7 +17,7 @@ import {
  * @example
  * ```ts
  * const alepha = Alepha.create()
- *   .with(AlephaContainers)
+ *   .with(AlephaContainer)
  *   .with(RocketController)
  *   .with(MyApp)
  *   .with({ provide: ContainerProvider, use: MockContainerProvider });

package/src/core/Alepha.ts

@@ -971,6 +971,33 @@ export class Alepha {
 
   // -------------------------------------------------------------------------------------------------------------------
 
+  /**
+   * Merge additional environment variables into the env store at runtime.
+   *
+   * Serverless entrypoints (Cloudflare Workers) receive their secrets and
+   * vars on the runtime `env` binding rather than `process.env`, so they are
+   * absent from `alepha.env` — which is frozen at `create()` from
+   * `process.env`. Call this from the entrypoint to lift the binding's string
+   * values into `alepha.env`, so `$env` and `alepha.env.*` resolve them (e.g.
+   * `PUBLIC_URL`).
+   *
+   * Only string values are lifted; non-string bindings (D1, R2, KV, queues,
+   * …) are skipped. Existing env values win, so explicit configuration is
+   * never clobbered. The env cache is cleared so subsequent `$env` reads see
+   * the merged values.
+   */
+  public loadEnv(env: Record<string, unknown>): this {
+    const incoming: Record<string, string> = {};
+    for (const [key, value] of Object.entries(env)) {
+      if (typeof value === "string") {
+        incoming[key] = value;
+      }
+    }
+    this.store.set("env", { ...incoming, ...this.env });
+    this.cacheEnv.clear();
+    return this;
+  }
+
   /**
    * Applies environment variables to the provided schema and state object.
    *
@@ -1087,6 +1114,16 @@ export class Alepha {
   }
 
   public dump(): AlephaDump {
+    // Force-instantiate the graph FIRST. `$env` is lazy — a key only lands in
+    // `cacheEnv` once its owning service is constructed. `graph()` injects
+    // every registered substitution (without emitting start/ready hooks), so
+    // calling it before reading `cacheEnv` ensures `env` reflects the whole
+    // app, not just whatever happened to be instantiated already. Reading
+    // `cacheEnv` first (the old order) under-reported env on a not-yet-started
+    // app and was internally inconsistent: dump() instantiated providers for
+    // `providers` but never saw their env.
+    const providers = this.graph();
+
     const env: Record<string, AlephaDumpEnvVariable> = {};
     for (const [schema] of this.cacheEnv.entries()) {
       const ref = schema as any;
@@ -1103,7 +1140,7 @@ export class Alepha {
 
     return {
       env,
-      providers: this.graph(),
+      providers,
     };
   }
 
@@ -1271,6 +1308,17 @@ export interface Env {
    * The secret key used for signing JWTs, encrypting cookies, and other security features.
    */
   APP_SECRET?: string;
+
+  /**
+   * Public-facing base URL of the deployed app (e.g. "https://lore.alepha.dev").
+   *
+   * Used to render absolute links — emails, OAuth callbacks, sitemap. On the
+   * Cloudflare platform it is auto-derived from the configured production
+   * domain and pushed as a Worker secret by `alepha platform up`; otherwise
+   * set it explicitly in `.env.<env>`. Unset → empty, and absolute-link
+   * builders fall back to relative URLs.
+   */
+  PUBLIC_URL?: string;
 }
 
 // ---------------------------------------------------------------------------------------------------------------------