alepha 0.21.0 → 0.21.2

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

@@ -9,10 +9,6 @@ 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,
@@ -56,11 +52,22 @@ export class PlatformOrchestrator {
   public async up(options: {
     root: string;
     env: string;
-    app?: string;
     apps: AppDefinition[];
     run: RunnerMethod;
-  }): Promise<void> {
-    const { root, env, app: appFilter, apps, run } = options;
+    /**
+     * Pre-built mode — the artifact's `dist/` is already produced.
+     *
+     * Still runs auth → provision → build → migrate → deploy → secrets,
+     * but the `build` step shells out to `alepha build --prebuilt` which
+     * only regenerates the target-specific deploy config (e.g.
+     * `wrangler.jsonc`) and skips the Vite client + server builds.
+     * Used by external orchestrators (Rocket) that ship a pre-built
+     * `dist/` and just need the wrangler config refreshed for
+     * per-tenant overrides on every deploy.
+     */
+    prebuilt?: boolean;
+  }): Promise<{ urls: string[]; domain?: string }> {
+    const { root, env, apps, run, prebuilt } = options;
     const envConfig = await this.inspector.resolveEnvironment(root, env);
     const config = await this.inspector.resolveConfig(root);
     const adapter = this.resolveAdapter(envConfig.adapter);
@@ -73,63 +80,58 @@ export class PlatformOrchestrator {
       apps,
       root,
       naming: namingCtx,
+      prebuilt,
     };
 
     // 1. Auth
     await adapter.authenticate(ctx, run);
 
-    // 2. Filter apps
-    const targetApps = appFilter
-      ? apps.filter((a) => a.name === appFilter)
-      : apps;
-
-    if (targetApps.length === 0 && appFilter) {
-      throw new AlephaError(
-        `App "${appFilter}" not found. Available: ${apps.map((a) => a.name).join(", ")}`,
-      );
-    }
-
-    // 3. Provision (before build so resource IDs are available for wrangler config)
+    // 2. Provision (before build so resource IDs are available for wrangler config)
     await adapter.provision(ctx, run);
 
-    // 4. Build
-    for (const a of targetApps) {
+    // 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);
     }
 
-    // 5. Migrate
+    // 4. Migrate
     await adapter.migrate(ctx, run);
 
-    // 6. Deploy
+    // 5. Deploy
     const urls: string[] = [];
-    for (const a of targetApps) {
+    for (const a of apps) {
       const url = await adapter.deploy({ ...ctx, app: a }, run);
       if (url) {
         urls.push(url);
       }
     }
 
-    // 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)
+    // 6. Secrets (push .env.{env} secrets to deployed workers)
     await adapter.secrets(ctx, run);
 
     run.end();
 
-    const c = this.color;
+    return { urls, domain: envConfig.domain };
+  }
 
-    if (envConfig.domain) {
+  /**
+   * Pretty-print the `up()` result to stdout. Matches the formatting the
+   * orchestrator used to emit inline; split out so callers that want
+   * JSON output can skip this branch.
+   */
+  public printUpSummary(result: { urls: string[]; domain?: string }): void {
+    const c = this.color;
+    if (result.domain) {
       this.log.info("");
-      const display = envConfig.domain.includes("*")
-        ? `https://${envConfig.domain} (wildcard route)`
-        : `https://${envConfig.domain}`;
+      const display = result.domain.includes("*")
+        ? `https://${result.domain} (wildcard route)`
+        : `https://${result.domain}`;
       this.log.info(`  ${c.set("GREEN", "\u2192")} ${c.set("CYAN", display)}`);
       this.log.info("");
     } else {
-      for (const url of urls) {
+      for (const url of result.urls) {
         this.log.info("");
         this.log.info(`  ${c.set("GREEN", "\u2192")} ${c.set("CYAN", url)}`);
         this.log.info("");
@@ -144,12 +146,11 @@ export class PlatformOrchestrator {
   public async down(options: {
     root: string;
     env: string;
-    app?: string;
     apps: AppDefinition[];
     run: RunnerMethod;
     confirm: (prompt: string) => Promise<string>;
   }): Promise<boolean> {
-    const { root, env, app: appFilter, apps, run, confirm } = options;
+    const { root, env, apps, run, confirm } = options;
     const envConfig = await this.inspector.resolveEnvironment(root, env);
     const config = await this.inspector.resolveConfig(root);
     const adapter = this.resolveAdapter(envConfig.adapter);
@@ -159,7 +160,7 @@ export class PlatformOrchestrator {
       project: config.project,
       env,
       envConfig,
-      apps: appFilter ? apps.filter((a) => a.name === appFilter) : apps,
+      apps,
       root,
       naming: namingCtx,
     };
@@ -177,9 +178,6 @@ 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();
@@ -187,62 +185,6 @@ 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;
-
-    // Wildcard domains aren't a concrete URL — fall back to the worker URL so
-    // hooks (Stripe webhooks, etc.) receive a usable endpoint.
-    const hasUsableDomain =
-      ctx.envConfig.domain && !ctx.envConfig.domain.includes("*");
-    const baseUrl = hasUsableDomain
-      ? `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.debug(`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.debug(
-            `Platform hook ${hook.name} failed to unregister: ${(err as Error).message}`,
-          );
-        } else {
-          throw err;
-        }
-      }
-    }
-  }
-
   // -------------------------------------------------------------------------
   // plan
   // -------------------------------------------------------------------------

package/src/containers/core/__tests__/$container.spec.ts

@@ -0,0 +1,83 @@
+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 { $container } from "../primitives/$container.ts";
+import { ContainerProvider } from "../providers/ContainerProvider.ts";
+import { NodeContainerProvider } from "../providers/NodeContainerProvider.ts";
+
+describe("$container", () => {
+  it("routes proxy calls through the active provider", async ({ expect }) => {
+    class RocketController {
+      createJob = $action({
+        schema: {
+          body: t.object({ op: t.text() }),
+          response: t.object({ jobId: t.text(), status: t.text() }),
+        },
+        handler: async ({ body }) => ({
+          jobId: `job-${body.op}`,
+          status: "queued",
+        }),
+      });
+    }
+
+    class DeployService {
+      rocket = $container<RocketController>({
+        image: "alepha/rocket:latest",
+      });
+    }
+
+    // In test mode AlephaContainers 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(RocketController)
+      .with(DeployService);
+
+    await alepha.start();
+
+    const service = alepha.inject(DeployService);
+    const result = await alepha.context.run(() =>
+      (service.rocket as any).createJob({ body: { op: "up" } }),
+    );
+    expect(result).toStrictEqual({ jobId: "job-up", status: "queued" });
+  });
+
+  it("exposes the underlying primitive via instanceof + name", ({ expect }) => {
+    class App {
+      rocket = $container({
+        image: "alepha/rocket:latest",
+        name: "rocket",
+      });
+    }
+
+    const alepha = Alepha.create({ env: {} }).with(AlephaContainers).with(App);
+
+    // Force App instantiation so the primitive registers.
+    const app = alepha.inject(App);
+    expect((app.rocket as any).name).toBe("rocket");
+    expect((app.rocket as any).options.image).toBe("alepha/rocket:latest");
+    expect(alepha.primitives($container).length).toBe(1);
+  });
+
+  it("throws when a Node container has no URL", async ({ expect }) => {
+    class App {
+      rocket = $container({ image: "alepha/rocket:latest" });
+    }
+
+    const alepha = Alepha.create({ env: {} })
+      .with({ provide: ContainerProvider, use: NodeContainerProvider })
+      .with(AlephaContainers)
+      .with(App);
+    await alepha.start();
+
+    const app = alepha.inject(App);
+    await expect(
+      alepha.context.run(() => (app.rocket as any).deploy({ body: {} })),
+    ).rejects.toThrow(/no 'url' configured/i);
+  });
+});

package/src/containers/core/index.ts

@@ -0,0 +1,50 @@
+import { $module } from "alepha";
+import { $container } from "./primitives/$container.ts";
+import { ContainerProvider } from "./providers/ContainerProvider.ts";
+import { MockContainerProvider } from "./providers/MockContainerProvider.ts";
+import { NodeContainerProvider } from "./providers/NodeContainerProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./interfaces/ContainerOptions.ts";
+export * from "./primitives/$container.ts";
+export * from "./providers/ContainerProvider.ts";
+export * from "./providers/MockContainerProvider.ts";
+export * from "./providers/NodeContainerProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Type-safe RPC clients for ephemeral containerized Alepha apps.
+ *
+ * **Features:**
+ * - `$container<T>()` directive returns a typed Proxy onto a remote
+ *   Alepha controller's `$action` endpoints — the wire format is the
+ *   same `POST /api/<method>` shape served by every Alepha server.
+ * - 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).
+ * - Build-time integration: `BuildCloudflareTask.enhanceContainers`
+ *   emits the matching wrangler bindings and Durable Object class
+ *   declarations.
+ *
+ * The Node binding is the "temporary, not perfect" path documented in
+ * the spec — apps need to provide an explicit `url` per primitive
+ * until a `target=docker` adapter ships.
+ *
+ * @module alepha.containers
+ */
+export const AlephaContainers = $module({
+  name: "alepha.containers",
+  primitives: [$container],
+  services: [ContainerProvider],
+  variants: [MockContainerProvider, NodeContainerProvider],
+  register: (alepha) => {
+    alepha.with({
+      optional: true,
+      provide: ContainerProvider,
+      use: alepha.isTest() ? MockContainerProvider : NodeContainerProvider,
+    });
+  },
+});

package/src/containers/core/index.workerd.ts

@@ -0,0 +1,37 @@
+import { $module } from "alepha";
+import { $container } from "./primitives/$container.ts";
+import { CloudflareContainerProvider } from "./providers/CloudflareContainerProvider.ts";
+import { ContainerProvider } from "./providers/ContainerProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./interfaces/ContainerOptions.ts";
+export * from "./primitives/$container.ts";
+export * from "./providers/CloudflareContainerProvider.ts";
+export * from "./providers/ContainerProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Type-safe RPC clients for ephemeral containerized Alepha apps,
+ * Cloudflare workerd build.
+ *
+ * Auto-binds `CloudflareContainerProvider` so `$container()` calls
+ * route through `env.<NAME>.getContainer(...).fetch()`. Pair with
+ * `BuildCloudflareTask.enhanceContainers` (in `alepha/cli/core`) which
+ * emits the wrangler.jsonc bindings and DO class declarations.
+ *
+ * @module alepha.containers
+ */
+export const AlephaContainers = $module({
+  name: "alepha.containers",
+  primitives: [$container],
+  services: [ContainerProvider, CloudflareContainerProvider],
+  register: (alepha) => {
+    alepha.with({
+      optional: true,
+      provide: ContainerProvider,
+      use: CloudflareContainerProvider,
+    });
+  },
+});

package/src/containers/core/interfaces/ContainerOptions.ts

@@ -0,0 +1,69 @@
+import type { DurationLike } from "alepha/datetime";
+
+/**
+ * Options for the `$container` primitive.
+ *
+ * Describes a remote Alepha app running in an ephemeral container. The
+ * primitive returns a typed Proxy that calls the container's `$action`
+ * endpoints through whatever transport the active provider chooses
+ * (Cloudflare Containers binding on `target=cloudflare`, plain HTTP on
+ * Node when `url` is set).
+ */
+export interface ContainerPrimitiveOptions {
+  /**
+   * Logical container name. Defaults to the property key.
+   *
+   * Cloudflare provider uppercases this to look up the binding
+   * (`env.<NAME>`), so prefer lowercase here.
+   */
+  name?: string;
+
+  /**
+   * Docker image the container runs. Required.
+   *
+   * The build task uses this verbatim in `wrangler.jsonc`'s
+   * `containers[].image` entry.
+   */
+  image: string;
+
+  /**
+   * Explicit URL the Node provider should call. When set, `$container`
+   * routes through `LinkProvider` exactly like `$remote({ url })`.
+   *
+   * On `target=cloudflare`, this is ignored — the Containers binding is
+   * used instead.
+   */
+  url?: string | (() => string);
+
+  /**
+   * Port the container app listens on. Defaults to 3000 (Alepha
+   * convention — NOT Cloudflare's 8080). Used in build-time codegen.
+   */
+  port?: number;
+
+  /**
+   * Idle window before the platform stops the container instance.
+   *
+   * @default "15m"
+   */
+  sleepAfter?: DurationLike;
+
+  /**
+   * Environment variables injected into the container at runtime.
+   */
+  envVars?: Record<string, string>;
+
+  /**
+   * Cloudflare-specific instance class. Ignored on other targets.
+   *
+   * @default "dev"
+   */
+  instanceType?: "dev" | "basic" | "standard";
+
+  /**
+   * Maximum concurrent container instances.
+   *
+   * @default 5
+   */
+  maxInstances?: number;
+}

package/src/containers/core/primitives/$container.ts

@@ -0,0 +1,100 @@
+import { $inject, AlephaError, createPrimitive, KIND, Primitive } from "alepha";
+import type { ContainerPrimitiveOptions } from "../interfaces/ContainerOptions.ts";
+import { ContainerProvider } from "../providers/ContainerProvider.ts";
+
+/**
+ * `$container` — typed RPC client to a containerized Alepha app.
+ *
+ * Returns a typed Proxy whose method calls map 1:1 to the target
+ * controller's `$action` endpoints. The wire format mirrors what a
+ * normal Alepha server exposes (`POST /api/<method>` with a JSON body),
+ * so the container is literally a tiny Alepha worker.
+ *
+ * Transport is owned by the active {@link ContainerProvider}:
+ * - `target=cloudflare` → `CloudflareContainerProvider` routes through
+ *   the Containers binding (`env.<NAME>.getContainer(...).fetch()`).
+ * - Node (with `url` set) → `NodeContainerProvider` uses plain
+ *   `fetch()` against the configured URL.
+ *
+ * Build-time, `BuildCloudflareTask.enhanceContainers` walks
+ * `alepha.primitives($container)` to emit the matching `wrangler.jsonc`
+ * entries and Durable Object class declarations into
+ * `main.cloudflare.js`.
+ *
+ * @example
+ * ```ts
+ * import { $container } from "alepha/containers";
+ * import type { RocketController } from "@alepha/rocket";
+ *
+ * class DeployService {
+ *   rocket = $container<RocketController>({
+ *     image: "alepha/rocket:latest",
+ *     port: 3000,
+ *     sleepAfter: "15m",
+ *   });
+ *
+ *   async deploy() {
+ *     return this.rocket.createJob({ body: { op: "up" } });
+ *   }
+ * }
+ * ```
+ */
+export const $container = <T extends object = any>(
+  options: ContainerPrimitiveOptions,
+): ContainerProxy<T> => {
+  if (!options.image) {
+    throw new AlephaError("$container requires an 'image' option");
+  }
+  const instance = createPrimitive(ContainerPrimitive, options);
+  return instance.proxy() as ContainerProxy<T>;
+};
+
+/**
+ * Typed proxy returned by `$container<T>()`. Each `$action` member of
+ * `T` becomes a callable returning the action's response body.
+ *
+ * The runtime shape is a `Proxy(primitive)` — own-property reads hit the
+ * underlying `ContainerPrimitive` (so `alepha.primitives($container)`
+ * still finds it via the `instanceof Primitive` check inside
+ * `Alepha.new()`), and anything else is treated as an action name and
+ * routed through the active `ContainerProvider`.
+ */
+export type ContainerProxy<T extends object> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? (...args: A) => Promise<Awaited<R>>
+    : (config?: {
+        body?: unknown;
+        query?: unknown;
+        params?: unknown;
+      }) => Promise<any>;
+};
+
+export class ContainerPrimitive extends Primitive<ContainerPrimitiveOptions> {
+  protected readonly provider = $inject(ContainerProvider);
+
+  public get name(): string {
+    return this.options.name ?? this.config.propertyKey;
+  }
+
+  /**
+   * Build the typed Proxy. The target is the primitive itself so
+   * `instanceof Primitive` keeps working (required by Alepha's
+   * primitive registration in `Alepha.new`). Property reads that match
+   * an own/inherited member return that member; anything else is
+   * treated as an action name and routed through the provider.
+   */
+  public proxy<T extends object = any>(): ContainerProxy<T> {
+    const primitive = this;
+    return new Proxy(primitive as any, {
+      get(target: any, prop: string | symbol, receiver: any) {
+        if (typeof prop === "symbol" || prop in target) {
+          return Reflect.get(target, prop, receiver);
+        }
+        return (config: any = {}) =>
+          primitive.provider.invoke(primitive, prop as string, config);
+      },
+    }) as ContainerProxy<T>;
+  }
+}
+
+$container[KIND] = ContainerPrimitive;

package/src/containers/core/providers/CloudflareContainerProvider.ts

@@ -0,0 +1,72 @@
+import { $inject, Alepha, AlephaError } from "alepha";
+import type { ContainerPrimitive } from "../primitives/$container.ts";
+import {
+  type ContainerInvokeConfig,
+  ContainerProvider,
+} from "./ContainerProvider.ts";
+
+/**
+ * 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.
+ *
+ * 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);
+
+  public override async invoke(
+    container: ContainerPrimitive,
+    action: string,
+    config: ContainerInvokeConfig,
+  ): Promise<unknown> {
+    const env = this.alepha.store.get("cloudflare.env") as
+      | Record<string, unknown>
+      | undefined;
+    if (!env) {
+      throw new AlephaError(
+        `CloudflareContainerProvider could not resolve 'cloudflare.env' from the store — is the app running on workerd?`,
+      );
+    }
+
+    const binding = env[container.name.toUpperCase()] as
+      | {
+          getContainer?: (id: string) => {
+            fetch(req: Request): Promise<Response>;
+          };
+        }
+      | undefined;
+
+    if (!binding?.getContainer) {
+      throw new AlephaError(
+        `Cloudflare Containers binding '${container.name.toUpperCase()}' not found on env — check wrangler.jsonc.`,
+      );
+    }
+
+    const instance = binding.getContainer("shared");
+    const { path, init } = this.buildRequest(action, config);
+    const request = new Request(`http://container${path}`, init);
+    const response = await instance.fetch(request);
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new AlephaError(
+        `Container '${container.name}' action '${action}' failed: ${response.status} ${response.statusText}${
+          text ? ` — ${text}` : ""
+        }`,
+      );
+    }
+
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      return await response.json();
+    }
+    return await response.text();
+  }
+}