alepha 0.21.2 → 0.22.0

package/src/cli/{platform → platform-lib}/adapters/PlatformAdapter.ts

@@ -1,8 +1,25 @@
+import { AlephaError } from "alepha";
 import type { AppEntry } from "alepha/cli";
 import type { RunnerMethod } from "alepha/command";
 import type { EnvironmentConfig } from "../atoms/platformOptions.ts";
 import type { NamingContext } from "../services/NamingService.ts";
 
+/**
+ * Options for {@link PlatformAdapter.exportDb}.
+ */
+export interface ExportDbOptions {
+  /**
+   * Destination file for the local snapshot. Adapter-specific default —
+   * Cloudflare/D1 writes the dev SQLite at
+   * `node_modules/.alepha/sqlite.db`.
+   */
+  output?: string;
+  /**
+   * Keep the intermediate `.sql` dump instead of deleting it after import.
+   */
+  keepSql?: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // Context types
 // ---------------------------------------------------------------------------
@@ -15,32 +32,14 @@ export interface DetectedResources {
   hasCron: boolean;
 }
 
-export interface AppDefinition {
-  /**
-   * Slugified app name (from package.json).
-   */
-  name: string;
-
-  /**
-   * Relative path from root (e.g., "apps/api").
-   * Empty string for standalone apps.
-   */
-  path: string;
-
-  /**
-   * Resolved entry points for this app.
-   */
-  entry: AppEntry;
-
-  /**
-   * Cloud resources detected by introspecting the app.
-   */
-  resources: DetectedResources;
-}
-
+/**
+ * One workspace = one app. Used to be a per-app definition in a
+ * monorepo-aware orchestrator; flattened into `PlatformContext` after
+ * the `apps:` field was removed from platform options.
+ */
 export interface PlatformContext {
   /**
-   * Slugified project name (from root package.json or config).
+   * Slugified project name (from package.json or platform config).
    */
   project: string;
 
@@ -55,20 +54,35 @@ export interface PlatformContext {
   envConfig: EnvironmentConfig;
 
   /**
-   * All apps in the project.
+   * Workspace root path.
    */
-  apps: AppDefinition[];
+  root: string;
 
   /**
-   * Monorepo/project root path.
+   * Resolved entry points for the workspace. Stub (`{ root, server: "" }`)
+   * in pre-built / manifest mode since no source booting happens.
    */
-  root: string;
+  entry: AppEntry;
+
+  /**
+   * Cloud resources the workspace uses — discovered at build time, read
+   * from `dist/manifest.json` at deploy time.
+   */
+  resources: DetectedResources;
 
   /**
-   * Resource name generator bound to this project+env.
+   * Resource name generator bound to this project+env(+tenant).
    */
   naming: NamingContext;
 
+  /**
+   * Active tenant slug for this deploy (apps with `tenancy: optional |
+   * required`), or `undefined` for a base / non-tenanted deploy. Shapes
+   * the served host (`<tenant>.<domain>`); resource names already fold it
+   * in via {@link naming}.
+   */
+  tenant?: string;
+
   /**
    * Pre-built mode. When true, the adapter's `build()` should skip the
    * Vite bundle steps and only regenerate the deploy config
@@ -78,12 +92,11 @@ export interface PlatformContext {
   prebuilt?: boolean;
 }
 
-export interface AppContext extends PlatformContext {
-  /**
-   * The specific app being operated on.
-   */
-  app: AppDefinition;
-}
+/**
+ * @deprecated Same as `PlatformContext` since the `apps:` collapse —
+ * kept as a type alias so existing adapter signatures still compile.
+ */
+export type AppContext = PlatformContext;
 
 // ---------------------------------------------------------------------------
 // State types (returned by inspect)
@@ -158,6 +171,20 @@ export abstract class PlatformAdapter {
    */
   async migrate(_ctx: PlatformContext, _run: RunnerMethod): Promise<void> {}
 
+  /**
+   * Export the deployed database to a local file — the remote → local dev
+   * snapshot workflow. Adapter/dialect specific; the default refuses.
+   */
+  async exportDb(
+    _ctx: PlatformContext,
+    _run: RunnerMethod,
+    _options: ExportDbOptions = {},
+  ): Promise<void> {
+    throw new AlephaError(
+      `Database export is not supported by the '${this.constructor.name}' adapter.`,
+    );
+  }
+
   /**
    * Push runtime secrets to the deployed worker(s).
    *

package/src/cli/{platform → platform-lib}/adapters/VercelAdapter.ts

@@ -95,9 +95,7 @@ export class VercelAdapter extends PlatformAdapter {
   // -------------------------------------------------------------------------
 
   async build(ctx: AppContext, run: RunnerMethod): Promise<void> {
-    const appDir = ctx.app.path
-      ? this.fs.join(ctx.root, ctx.app.path)
-      : ctx.root;
+    const appDir = ctx.root;
 
     await run({
       name: "alepha build -t vercel",
@@ -117,16 +115,14 @@ export class VercelAdapter extends PlatformAdapter {
     ctx: AppContext,
     run: RunnerMethod,
   ): Promise<string | undefined> {
-    const distDir = ctx.app.path
-      ? this.fs.join(ctx.root, ctx.app.path, "dist")
-      : this.fs.join(ctx.root, "dist");
+    const distDir = this.fs.join(ctx.root, "dist");
 
     const projectName = ctx.naming.worker();
 
     let url: string | undefined;
 
     await run({
-      name: `deploy ${ctx.app.name}`,
+      name: `deploy ${ctx.project}`,
       handler: async () => {
         // Ensure project exists and has framework: null for prebuilt deploys
         let project = await this.api.getProject(projectName);
@@ -199,7 +195,7 @@ export class VercelAdapter extends PlatformAdapter {
       return;
     }
 
-    for (const app of ctx.apps) {
+    {
       const projectName = ctx.naming.worker();
 
       await run({
@@ -231,7 +227,7 @@ export class VercelAdapter extends PlatformAdapter {
     const tasks: Array<{ name: string; handler: () => Promise<void> }> = [];
 
     // Projects/deployments (mapped to "workers" in PlatformState)
-    for (const app of ctx.apps) {
+    {
       const projectName = ctx.naming.worker();
 
       tasks.push({
@@ -303,7 +299,7 @@ export class VercelAdapter extends PlatformAdapter {
   // -------------------------------------------------------------------------
 
   async teardown(ctx: PlatformContext, run: RunnerMethod): Promise<void> {
-    for (const app of ctx.apps) {
+    {
       const projectName = ctx.naming.worker();
 
       await run({

package/src/cli/{platform → platform-lib}/atoms/platformOptions.ts

@@ -23,16 +23,49 @@ export const platformOptions = $atom({
        */
       default: t.optional(t.text()),
 
+      /**
+       * Multi-tenancy mode — controls whether `--tenant <slug>` is
+       * accepted/required and how it shapes resource names + the domain.
+       *
+       * - `none` (default): single instance. `--tenant` is rejected.
+       * - `required`: every deploy needs `--tenant`; resources are named
+       *   `<tenant>-<project>-<env>` and the host becomes
+       *   `<tenant>.<domain>`. Omitting it errors.
+       * - `optional`: a base instance (no `--tenant`) plus per-tenant
+       *   instances coexist.
+       *
+       * @default "none"
+       */
+      tenancy: t.optional(t.enum(["none", "optional", "required"])),
+
       /**
        * Secret store configuration for syncing .env secrets
        * to external providers (e.g. GitHub Actions environments).
        */
       secrets: t.optional(
         t.object({
+          /**
+           * Explicit override of the worker secret-key allowlist.
+           *
+           * By default the deploy `secrets` step uses the build manifest's
+           * `env` list (every key the app declares via `$env`, captured at
+           * build time) as the allowlist, resolving each value from
+           * `.env.<env>[.local]` first, then `process.env`. This lets CI
+           * deliver secrets via the job environment (no `.env` file on the
+           * runner) while only ever pushing declared keys — ambient runner
+           * vars (PATH, GITHUB_*, …) can never leak.
+           *
+           * Set `keys` to override that auto-detected list (e.g. to narrow it,
+           * or to add a key read via `process.env` rather than `$env`). When
+           * neither this nor a manifest is present, the `.env.<env>` file is
+           * itself the allowlist (legacy fallback).
+           */
+          keys: t.optional(t.array(t.text())),
+
           /**
            * Secret store backend.
            */
-          store: t.enum(["github"]),
+          store: t.optional(t.enum(["github"])),
 
           /**
            * Pattern for resolving environment names in the store.

package/src/cli/platform-lib/index.ts

@@ -0,0 +1,67 @@
+import { $module } from "alepha";
+import { CloudflareAdapter } from "./adapters/CloudflareAdapter.ts";
+import { VercelAdapter } from "./adapters/VercelAdapter.ts";
+import { GitHubSecretStore } from "./providers/GitHubSecretStore.ts";
+import { MemorySecretStore } from "./providers/MemorySecretStore.ts";
+import { PlatformCacheProvider } from "./providers/PlatformCacheProvider.ts";
+import { CloudflareApi } from "./services/CloudflareApi.ts";
+import { NamingService } from "./services/NamingService.ts";
+import { PlatformInspector } from "./services/PlatformInspector.ts";
+import { PlatformOrchestrator } from "./services/PlatformOrchestrator.ts";
+import { SecretFilterService } from "./services/SecretFilterService.ts";
+import { VercelApi } from "./services/VercelApi.ts";
+import { VercelCli } from "./services/VercelCli.ts";
+import { WranglerApi } from "./services/WranglerApi.ts";
+
+/**
+ * Framework-agnostic platform deploy services.
+ *
+ * Exports `PlatformOrchestrator` + adapters + secret stores + the
+ * `platformOptions` atom — everything needed to drive a deploy
+ * programmatically. **No `$command` instances** and **no
+ * `AppEntryProvider` / `ViteBuildProvider` dependency** — so consumers
+ * importing this subpath don't pull in the CLI argv-parser or Vite.
+ *
+ * Used by Alepha Rocket (and other non-CLI deploy orchestrators) to
+ * call `orchestrator.up({ ... })` directly. For CLI usage
+ * (`alepha platform up`), import `AlephaCliPlatformPlugin` from
+ * `alepha/cli/platform` — that one adds the command layer on top.
+ */
+export const AlephaPlatformLibPlugin = $module({
+  name: "alepha.cli.platform-lib",
+  services: [
+    CloudflareAdapter,
+    CloudflareApi,
+    VercelAdapter,
+    VercelApi,
+    VercelCli,
+    WranglerApi,
+    PlatformCacheProvider,
+    GitHubSecretStore,
+    MemorySecretStore,
+    NamingService,
+    SecretFilterService,
+    PlatformInspector,
+    PlatformOrchestrator,
+  ],
+});
+
+export * from "./adapters/CloudflareAdapter.ts";
+export * from "./adapters/PlatformAdapter.ts";
+export * from "./adapters/VercelAdapter.ts";
+export * from "./atoms/platformOptions.ts";
+export * from "./providers/GitHubSecretStore.ts";
+export * from "./providers/MemorySecretStore.ts";
+export * from "./providers/PlatformCacheProvider.ts";
+export * from "./providers/SecretStoreProvider.ts";
+export * from "./schemas/cloudflare.ts";
+export * from "./schemas/platform.ts";
+export * from "./schemas/vercel.ts";
+export * from "./services/CloudflareApi.ts";
+export * from "./services/NamingService.ts";
+export * from "./services/PlatformInspector.ts";
+export * from "./services/PlatformOrchestrator.ts";
+export * from "./services/SecretFilterService.ts";
+export * from "./services/VercelApi.ts";
+export * from "./services/VercelCli.ts";
+export * from "./services/WranglerApi.ts";

package/src/cli/platform-lib/services/NamingService.ts

@@ -0,0 +1,136 @@
+import { AlephaError } from "alepha";
+
+/**
+ * Multi-tenancy mode for an app's deployments.
+ *
+ * - `none` (default): single-instance app. Passing `--tenant` is an
+ *   error — guards a non-tenanted app (e.g. the SaaS console) from
+ *   accidentally getting a tenant prefix.
+ * - `required`: every deploy targets a tenant. Omitting `--tenant` is an
+ *   error — kills the "forgot the flag → deployed to the apex" footgun.
+ * - `optional`: both work — a base instance (no `--tenant`) and per-tenant
+ *   instances coexist (distinct names + hosts).
+ */
+export type Tenancy = "none" | "optional" | "required";
+
+/**
+ * Validate a `--tenant` value against the app's declared `tenancy` and
+ * return the effective tenant (or `undefined` for a base/non-tenanted
+ * deploy). Throws on any matrix violation so a misconfigured deploy fails
+ * fast instead of landing on the wrong resource names / host.
+ */
+export function resolveTenant(
+  tenancy: Tenancy | undefined,
+  tenant: string | undefined,
+): string | undefined {
+  const mode = tenancy ?? "none";
+
+  if (tenant !== undefined && !/^[a-z0-9][a-z0-9-]*$/.test(tenant)) {
+    throw new AlephaError(
+      `Invalid --tenant "${tenant}": must be a slug (lowercase alphanumeric + dashes, e.g. "b14").`,
+    );
+  }
+
+  if (mode === "none") {
+    if (tenant !== undefined) {
+      throw new AlephaError(
+        `This app is not tenanted (tenancy: "none") but --tenant "${tenant}" was given. ` +
+          `Set tenancy: "optional" | "required" in platform() to deploy per-tenant.`,
+      );
+    }
+    return undefined;
+  }
+
+  if (mode === "required" && tenant === undefined) {
+    throw new AlephaError(
+      `This app requires a tenant (tenancy: "required"). Pass --tenant <slug>.`,
+    );
+  }
+
+  // required+value or optional(+/- value) — value may be undefined for the
+  // optional base instance.
+  return tenant;
+}
+
+/**
+ * Resolve the host a deploy is served on.
+ *
+ * - `override` (V2 custom domains, e.g. `reservation.club-b14.fr`) wins
+ *   outright when supplied — not wired to a flag today, but the single
+ *   seam a future `--domain` / Rocket `config.hostname` plugs into.
+ * - else a tenant becomes the leftmost DNS label: `b14` + `alepha.club`
+ *   → `b14.alepha.club`.
+ * - else the base domain is used as-is.
+ */
+export function tenantDomain(
+  base: string | undefined,
+  tenant: string | undefined,
+  override?: string,
+): string | undefined {
+  if (override) return override;
+  if (!base) return base;
+  return tenant ? `${tenant}.${base}` : base;
+}
+
+/**
+ * Generates deterministic resource names for cloud deployments.
+ *
+ * Pattern: `<tenant>-<project>-<env>` (tenant segment omitted when the
+ * deploy isn't tenanted).
+ *
+ * All segments are slugified (lowercase, alphanumeric + dashes, max 63
+ * chars). One app per workspace — see `alepha platform`.
+ */
+export class NamingService {
+  public forContext(
+    project: string,
+    env: string,
+    tenant?: string,
+  ): NamingContext {
+    const prefix = [tenant, project, env]
+      .filter((segment): segment is string => !!segment)
+      .map((segment) => this.slugify(segment))
+      .join("-");
+    return new NamingContext(prefix);
+  }
+
+  public slugify(name: string): string {
+    return name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 63);
+  }
+}
+
+export class NamingContext {
+  protected readonly prefix: string;
+
+  constructor(prefix: string) {
+    this.prefix = prefix;
+  }
+
+  public worker(): string {
+    return this.prefix;
+  }
+
+  public d1(): string {
+    return this.prefix;
+  }
+
+  public hyperdrive(): string {
+    return this.prefix;
+  }
+
+  public r2(): string {
+    return this.prefix;
+  }
+
+  public kv(): string {
+    return this.prefix;
+  }
+
+  public queue(): string {
+    return this.prefix;
+  }
+}

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

@@ -6,11 +6,13 @@ import {
   type EnvironmentConfig,
   platformOptions,
 } from "../atoms/platformOptions.ts";
-import { NamingService } from "./NamingService.ts";
+import { NamingService, type Tenancy } from "./NamingService.ts";
 
 export interface ResolvedPlatformConfig {
   project: string;
   defaultEnv: string;
+  /** App tenancy mode (undefined ⇒ "none"). */
+  tenancy?: Tenancy;
   environments: Record<string, EnvironmentConfig>;
 }
 
@@ -35,10 +37,42 @@ export class PlatformInspector {
 
   /**
    * Resolve and validate the full platform configuration.
+   *
+   * Source priority:
+   *   1. `platformOptions` atom (set by `alepha.config.ts` during the
+   *      configure hook) — local dev / from-source deploys.
+   *   2. `dist/manifest.json` (written by `alepha build`) — pre-built
+   *      deploys via Alepha Rocket or any `--prebuilt` consumer that
+   *      ships only the build artifact without `alepha.config.ts`.
    */
   public async resolveConfig(root: string): Promise<ResolvedPlatformConfig> {
-    if (!this.options) {
-      this.log.warn(` alepha.config.ts not found or missing platform config.
+    if (this.options) {
+      const opts = this.options;
+      const project = await this.resolveProjectName(root, opts.name);
+      return {
+        project: this.naming.slugify(project),
+        defaultEnv: opts.default ?? "production",
+        tenancy: opts.tenancy,
+        environments: opts.environments as Record<string, EnvironmentConfig>,
+      };
+    }
+
+    // Fallback: read dist/manifest.json. Lets prebuilt artifacts deploy
+    // without shipping alepha.config.ts in the tarball.
+    const manifest = await this.readManifest(root);
+    if (manifest) {
+      return {
+        project: this.naming.slugify(manifest.project),
+        defaultEnv: manifest.defaultEnv ?? "production",
+        tenancy: manifest.tenancy,
+        environments: manifest.environments as Record<
+          string,
+          EnvironmentConfig
+        >,
+      };
+    }
+
+    this.log.warn(` alepha.config.ts not found or missing platform config.
 
 Please add a "platform" section to alepha.config.ts:
 
@@ -50,17 +84,30 @@ export default defineConfig({
   },
 });
         `);
-      throw new AlephaError("Missing platform configuration.");
-    }
-
-    const opts = this.options;
-    const project = await this.resolveProjectName(root, opts.name);
+    throw new AlephaError("Missing platform configuration.");
+  }
 
-    return {
-      project: this.naming.slugify(project),
-      defaultEnv: opts.default ?? "production",
-      environments: opts.environments as Record<string, EnvironmentConfig>,
-    };
+  /**
+   * Read `dist/manifest.json` if present. Returns null on any error so
+   * callers fall back to the strict alepha.config.ts path.
+   */
+  protected async readManifest(root: string): Promise<{
+    project: string;
+    defaultEnv?: string;
+    tenancy?: Tenancy;
+    environments?: Record<string, unknown>;
+  } | null> {
+    try {
+      const fs = await import("node:fs/promises");
+      const path = await import("node:path");
+      const raw = await fs.readFile(
+        path.join(root, "dist", "manifest.json"),
+        "utf-8",
+      );
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
   }
 
   /**