alepha 0.19.3 → 0.19.5

package/src/cli/platform/hooks/PlatformHook.ts

@@ -0,0 +1,51 @@
+import type { RunnerMethod } from "alepha/command";
+import type { PlatformContext } from "../adapters/PlatformAdapter.ts";
+
+/**
+ * Context passed to platform hooks.
+ *
+ * Extends PlatformContext with the fully-qualified base URL of the
+ * deployed app (derived from `envConfig.domain` or the adapter's deploy
+ * URL) and the active RunnerMethod.
+ */
+export interface PlatformHookContext extends PlatformContext {
+  /**
+   * Fully-qualified base URL of the deployed app, e.g. "https://foo.com".
+   */
+  baseUrl: string;
+  run: RunnerMethod;
+}
+
+/**
+ * Third-party provisioning hook for `alepha platform up` / `down`.
+ *
+ * Plugins can extend this to register resources in external services
+ * (Stripe webhooks, Sentry projects, Resend domains, etc.) tied to a
+ * deployment. Hooks are discovered via `alepha.services(PlatformHook)`,
+ * so adding a plugin to `services: [...]` in `alepha.config.ts` is all
+ * it takes to wire one in.
+ *
+ * Lifecycle:
+ * - `register` runs after `deploy` and before `adapter.secrets()` so
+ *   any secret a hook writes to `.env.<env>` is picked up in the same
+ *   `up` cycle.
+ * - `unregister` runs on `down` before `adapter.teardown()`.
+ *
+ * Implementations MUST be idempotent: `register` is called on every `up`.
+ */
+export abstract class PlatformHook {
+  /**
+   * Stable identifier. Used for log output.
+   */
+  abstract readonly name: string;
+
+  /**
+   * Create or update external resources. Must tolerate pre-existing state.
+   */
+  abstract register(ctx: PlatformHookContext): Promise<void>;
+
+  /**
+   * Remove external resources. Must tolerate missing state.
+   */
+  abstract unregister(ctx: PlatformHookContext): Promise<void>;
+}

package/src/cli/platform/index.ts

@@ -101,6 +101,7 @@ export * from "./adapters/VercelAdapter.ts";
 export * from "./atoms/platformOptions.ts";
 export * from "./commands/platform.ts";
 export * from "./commands/SecretsCommand.ts";
+export * from "./hooks/PlatformHook.ts";
 export * from "./providers/GitHubSecretStore.ts";
 export * from "./providers/MemorySecretStore.ts";
 export * from "./providers/PlatformCacheProvider.ts";

package/src/cli/platform/services/CloudflareApi.ts

@@ -67,6 +67,19 @@ export class CloudflareApi {
 
   protected token?: string;
   protected accountId?: string;
+  protected jurisdiction?: "eu" | "fedramp";
+
+  /**
+   * Set the Cloudflare data jurisdiction for R2 and D1 resources.
+   *
+   * R2 buckets and D1 databases created under a jurisdiction live in a
+   * separate namespace — every R2 API call (list/create/delete) must include
+   * the `cf-r2-jurisdiction` header, and D1 create must include the field
+   * in the request body. Omit / pass `undefined` for the default (global).
+   */
+  public setJurisdiction(jurisdiction?: "eu" | "fedramp"): void {
+    this.jurisdiction = jurisdiction;
+  }
 
   // -------------------------------------------------------------------------
   // Auth
@@ -127,7 +140,11 @@ export class CloudflareApi {
       `/accounts/${accountId}/d1/database`,
       {
         method: "POST",
-        body: { name, primary_location_hint: location },
+        body: {
+          name,
+          primary_location_hint: location,
+          ...(this.jurisdiction ? { jurisdiction: this.jurisdiction } : {}),
+        },
         bodySchema: createD1BodySchema,
         schema: cloudflareD1Schema,
       },
@@ -392,6 +409,10 @@ export class CloudflareApi {
       Authorization: `Bearer ${token}`,
     };
 
+    if (this.jurisdiction && /\/r2\//.test(path)) {
+      headers["cf-r2-jurisdiction"] = this.jurisdiction;
+    }
+
     const init: RequestInit = { method, headers };
 
     if (body) {

package/src/cli/platform/services/PlatformOrchestrator.ts

@@ -1,4 +1,4 @@
-import { $inject, AlephaError } from "alepha";
+import { $inject, Alepha, AlephaError } from "alepha";
 import type { RunnerMethod } from "alepha/command";
 import { $logger, ConsoleColorProvider } from "alepha/logger";
 import { CloudflareAdapter } from "../adapters/CloudflareAdapter.ts";
@@ -9,6 +9,10 @@ import type {
   PlatformState,
 } from "../adapters/PlatformAdapter.ts";
 import { VercelAdapter } from "../adapters/VercelAdapter.ts";
+import {
+  PlatformHook,
+  type PlatformHookContext,
+} from "../hooks/PlatformHook.ts";
 import { type NamingContext, NamingService } from "./NamingService.ts";
 import {
   PlatformInspector,
@@ -28,6 +32,7 @@ export class PlatformOrchestrator {
   protected readonly naming = $inject(NamingService);
   protected readonly cloudflareAdapter = $inject(CloudflareAdapter);
   protected readonly vercelAdapter = $inject(VercelAdapter);
+  protected readonly alepha = $inject(Alepha);
 
   // -------------------------------------------------------------------------
   // Adapter resolution
@@ -104,7 +109,12 @@ export class PlatformOrchestrator {
       }
     }
 
-    // 7. Secrets (push .env.{env} secrets to deployed workers)
+    // 7. Platform hooks (register external resources: Stripe webhooks, etc.)
+    //    Run before secrets() so any secret a hook writes to .env.<env>
+    //    gets pushed to the deployed worker in the same up cycle.
+    await this.runHooks("register", ctx, urls, run);
+
+    // 8. Secrets (push .env.{env} secrets to deployed workers)
     await adapter.secrets(ctx, run);
 
     run.end();
@@ -166,6 +176,9 @@ export class PlatformOrchestrator {
     // Auth
     await adapter.authenticate(ctx, run);
 
+    // Platform hooks (tear down external resources first, while creds still valid)
+    await this.runHooks("unregister", ctx, [], run);
+
     // Teardown
     await adapter.teardown(ctx, run);
     run.end();
@@ -173,6 +186,58 @@ export class PlatformOrchestrator {
     return true;
   }
 
+  // -------------------------------------------------------------------------
+  // Platform hooks
+  // -------------------------------------------------------------------------
+
+  /**
+   * Run all registered PlatformHook instances.
+   *
+   * Discovered dynamically via `alepha.services(PlatformHook)`: any plugin
+   * that registers a PlatformHook subclass in its `$module.services`
+   * participates automatically, without the core knowing about it.
+   */
+  protected async runHooks(
+    phase: "register" | "unregister",
+    ctx: PlatformContext,
+    deployUrls: string[],
+    run: RunnerMethod,
+  ): Promise<void> {
+    const hooks = this.alepha.services(PlatformHook);
+    if (hooks.length === 0) return;
+
+    const baseUrl = ctx.envConfig.domain
+      ? `https://${ctx.envConfig.domain}`
+      : deployUrls[0];
+
+    if (!baseUrl) {
+      this.log.debug("Skipping platform hooks: no base URL available");
+      return;
+    }
+
+    const hookCtx: PlatformHookContext = { ...ctx, baseUrl, run };
+
+    for (const hook of hooks) {
+      this.log.info(`Platform hook: ${hook.name} (${phase})`);
+      try {
+        if (phase === "register") {
+          await hook.register(hookCtx);
+        } else {
+          await hook.unregister(hookCtx);
+        }
+      } catch (err) {
+        // unregister must never block teardown
+        if (phase === "unregister") {
+          this.log.warn(
+            `Platform hook ${hook.name} failed to unregister: ${(err as Error).message}`,
+          );
+        } else {
+          throw err;
+        }
+      }
+    }
+  }
+
   // -------------------------------------------------------------------------
   // plan
   // -------------------------------------------------------------------------