alepha 0.20.2 → 0.20.4

package/src/cli/core/templates/mainCss.ts

@@ -11,6 +11,7 @@ export const mainCss = (opts: { tailwind?: boolean } = {}) => {
  *
  * Options:
  * - Tailwind CSS: Use \`alepha init --tailwind\` to add Tailwind CSS
+ * - shadcn/ui: Use \`alepha init --shadcn\` to add shadcn/ui setup
  * - Raw CSS: Write your own styles below
  */
 

package/src/cli/core/templates/saasAdminLayoutTsx.ts

@@ -0,0 +1,77 @@
+/**
+ * SaaS admin layout — full AppShell on /admin with a sidebar, breadcrumbs,
+ * a Sonner toaster, and a confirm provider. The page list grows with
+ * whatever `admin-*` registry components the user adds.
+ *
+ * All UI primitives come from `src/components/*` where `shadcn add` drops
+ * them; alepha app code lives in `src/web/*` and references them via the
+ * `@/components/*` alias.
+ */
+export const saasAdminLayoutTsx = () =>
+  `import { AppShell } from "@/components/app-shell";
+import { Toaster } from "@/components/ui/sonner";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { DialogProvider } from "@/components/use-dialog";
+import { NestedView, useRouterState } from "alepha/react/router";
+import { ShieldCheck, Users } from "lucide-react";
+
+const NAV = [
+  {
+    label: "Identity",
+    items: [
+      { href: "/admin/users", label: "Users", icon: Users },
+      { href: "/admin/sessions", label: "Sessions", icon: ShieldCheck },
+    ],
+  },
+] as const;
+
+const findCrumbs = (pathname: string): { label: string; href?: string }[] => {
+  for (const group of NAV) {
+    const match = group.items.find((it) => it.href === pathname);
+    if (match) return [{ label: group.label }, { label: match.label }];
+  }
+  return [];
+};
+
+const AdminLayout = () => {
+  const state = useRouterState();
+  const crumbs = findCrumbs(state.url.pathname);
+
+  return (
+    <TooltipProvider>
+      <DialogProvider>
+        <AppShell
+          brand={
+            <a
+              href="/admin"
+              className="flex items-center gap-2 px-2 py-2 font-semibold group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0"
+            >
+              <span className="bg-primary text-primary-foreground flex size-7 shrink-0 items-center justify-center rounded">
+                α
+              </span>
+              <span className="truncate group-data-[collapsible=icon]:hidden">
+                Admin
+              </span>
+            </a>
+          }
+          nav={NAV.map((group) => ({
+            label: group.label,
+            items: group.items.map((it) => ({
+              href: it.href,
+              label: it.label,
+              icon: it.icon,
+              active: it.href === state.url.pathname,
+            })),
+          }))}
+          breadcrumbs={crumbs.length ? crumbs : undefined}
+        >
+          <NestedView />
+        </AppShell>
+        <Toaster />
+      </DialogProvider>
+    </TooltipProvider>
+  );
+};
+
+export default AdminLayout;
+`;

package/src/cli/core/templates/saasAdminPagesTsx.ts

@@ -0,0 +1,26 @@
+/**
+ * Admin pages — each is a thin wrapper around the matching `admin-*`
+ * registry component (placed at `src/components/admin/*`). The starter
+ * ships with Users + Sessions; add more by `shadcn add @alepha/admin-…`
+ * and a matching `$page(...)` in AppRouter.
+ */
+
+export const saasAdminUsersTsx = () =>
+  `import { AdminUsers } from "@/components/admin/admin-users";
+
+const AdminUsersPage = () => {
+  return <AdminUsers />;
+};
+
+export default AdminUsersPage;
+`;
+
+export const saasAdminSessionsTsx = () =>
+  `import { AdminSessions } from "@/components/admin/admin-sessions";
+
+const AdminSessionsPage = () => {
+  return <AdminSessions />;
+};
+
+export default AdminSessionsPage;
+`;

package/src/cli/core/templates/saasAuthLayoutTsx.ts

@@ -0,0 +1,20 @@
+/**
+ * SaaS auth layout — wraps every /auth/* page with a centered card.
+ * Routes (login, register, reset-password, verify-email) are mounted as
+ * children so they share this shell.
+ */
+export const saasAuthLayoutTsx = () =>
+  `import { NestedView } from "alepha/react/router";
+
+const AuthLayout = () => {
+  return (
+    <div className="bg-background flex min-h-screen items-center justify-center p-4">
+      <div className="w-full max-w-md">
+        <NestedView />
+      </div>
+    </div>
+  );
+};
+
+export default AuthLayout;
+`;

package/src/cli/core/templates/saasAuthPagesTsx.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-page wrapper around the registry components. The registry component
+ * receives the realm config from the page loader; the page itself stays a
+ * thin shell so apps can layer their branding around it.
+ *
+ * Registry components land at `src/components/auth/*` (shadcn defaults).
+ */
+
+export const saasAuthLoginTsx = () =>
+  `import { AuthLogin } from "@/components/auth/auth-login";
+import type { RealmConfig } from "alepha/api/users";
+
+export interface AuthLoginPageProps {
+  realmConfig: RealmConfig;
+}
+
+const AuthLoginPage = (props: AuthLoginPageProps) => {
+  return <AuthLogin realmConfig={props.realmConfig} />;
+};
+
+export default AuthLoginPage;
+`;
+
+export const saasAuthRegisterTsx = () =>
+  `import { AuthRegister } from "@/components/auth/auth-register";
+import type { RealmConfig } from "alepha/api/users";
+
+export interface AuthRegisterPageProps {
+  realmConfig: RealmConfig;
+}
+
+const AuthRegisterPage = (props: AuthRegisterPageProps) => {
+  return <AuthRegister realmConfig={props.realmConfig} />;
+};
+
+export default AuthRegisterPage;
+`;
+
+export const saasAuthResetPasswordTsx = () =>
+  `import { AuthResetPassword } from "@/components/auth/auth-reset-password";
+import type { RealmConfig } from "alepha/api/users";
+
+export interface AuthResetPasswordPageProps {
+  realmConfig: RealmConfig;
+}
+
+const AuthResetPasswordPage = (props: AuthResetPasswordPageProps) => {
+  return <AuthResetPassword realmConfig={props.realmConfig} />;
+};
+
+export default AuthResetPasswordPage;
+`;
+
+export const saasAuthVerifyEmailTsx = () =>
+  `import { AuthVerifyEmail } from "@/components/auth/auth-verify-email";
+
+const AuthVerifyEmailPage = () => {
+  return <AuthVerifyEmail />;
+};
+
+export default AuthVerifyEmailPage;
+`;

package/src/cli/core/templates/saasRealmProviderTs.ts

@@ -0,0 +1,46 @@
+export interface SaasRealmProviderOptions {
+  /**
+   * Email seeded as the default admin. Detected from `git config user.email`
+   * at init time; falls through to `admin@example.com` if git isn't configured.
+   */
+  adminEmail?: string;
+}
+
+/**
+ * Realm provider scaffolded by `alepha init --saas`.
+ *
+ * Minimal hello-world setup: credentials login with email, one admin seeded
+ * with the developer's git email at scaffold time, and an `admin:ui`
+ * permission used by the AppRouter to gate `/admin/*`. The default `admin`
+ * role grants `*` (so it inherits `admin:ui`); the default `user` role
+ * excludes `admin:*` (so non-admins get a 403 before the shell renders).
+ *
+ * Add `$env`, more permissions, or stricter settings as the project grows.
+ */
+export const saasRealmProviderTs = (options: SaasRealmProviderOptions = {}) => {
+  const adminEmail = options.adminEmail ?? "admin@example.com";
+  return `import { $realm } from "alepha/api/users";
+import { $permission } from "alepha/security";
+
+export class RealmProvider {
+  /**
+   * Permission required to open the admin UI. Wired into AppRouter.adminLayout
+   * via \`$secure({ permissions: ["admin:ui"] })\`.
+   */
+  adminUi = $permission({
+    group: "admin",
+    name: "ui",
+    description: "Access to the admin UI shell",
+  });
+
+  realm = $realm({
+    settings: {
+      adminEmails: [${JSON.stringify(adminEmail)}],
+    },
+    identities: {
+      credentials: true,
+    },
+  });
+}
+`;
+};

package/src/cli/core/templates/webAppRouterTs.ts

@@ -1,4 +1,16 @@
-export const webAppRouterTs = (options: { api?: boolean }) => {
+export interface WebAppRouterOptions {
+  api?: boolean;
+  saas?: boolean;
+}
+
+export const webAppRouterTs = (options: WebAppRouterOptions) => {
+  if (options.saas) {
+    return saasAppRouterTs();
+  }
+  return basicAppRouterTs(options);
+};
+
+const basicAppRouterTs = (options: WebAppRouterOptions) => {
   const imports: string[] = ['import { $page } from "alepha/react/router";'];
   const classMembers: string[] = [];
 
@@ -27,3 +39,94 @@ export class AppRouter {
 ${classMembers.join("\n\n")}
 }`;
 };
+
+/**
+ * SaaS router wires three trees onto the app:
+ *   /            → Home
+ *   /auth/*      → AuthLayout + login / register / reset / verify
+ *   /admin/*     → AdminLayout + users / sessions / api-keys / parameters / audits
+ *
+ * Each auth page resolves the realm config from its loader, so the registry
+ * components render with everything they need on first paint.
+ */
+const saasAppRouterTs =
+  () => `import type { RealmController } from "alepha/api/users";
+import { $page, NotFound } from "alepha/react/router";
+import { $secure } from "alepha/security";
+import { $client } from "alepha/server/links";
+import type { HelloController } from "../api/controllers/HelloController.ts";
+
+export class AppRouter {
+  protected readonly api = $client<HelloController>();
+  protected readonly realmApi = $client<RealmController>();
+
+  home = $page({
+    path: "/",
+    lazy: () => import("./components/Home.tsx"),
+    loader: () => this.api.hello(),
+  });
+
+  // ── /auth — login, register, reset, verify ─────────────────────────────
+  authLayout = $page({
+    path: "/auth",
+    lazy: () => import("./components/auth/AuthLayout.tsx"),
+  });
+
+  login = $page({
+    parent: this.authLayout,
+    path: "/login",
+    name: "login",
+    head: { title: "Sign in" },
+    lazy: () => import("./components/auth/Login.tsx"),
+    loader: async () => ({ realmConfig: await this.realmApi.getRealmConfig() }),
+  });
+
+  register = $page({
+    parent: this.authLayout,
+    path: "/register",
+    name: "register",
+    head: { title: "Sign up" },
+    lazy: () => import("./components/auth/Register.tsx"),
+    loader: async () => ({ realmConfig: await this.realmApi.getRealmConfig() }),
+  });
+
+  resetPassword = $page({
+    parent: this.authLayout,
+    path: "/reset-password",
+    head: { title: "Reset password" },
+    lazy: () => import("./components/auth/ResetPassword.tsx"),
+    loader: async () => ({ realmConfig: await this.realmApi.getRealmConfig() }),
+  });
+
+  verifyEmail = $page({
+    parent: this.authLayout,
+    path: "/verify-email",
+    head: { title: "Verify email" },
+    lazy: () => import("./components/auth/VerifyEmail.tsx"),
+  });
+
+  // ── /admin — gated by 'admin:ui' permission, declared in RealmProvider.
+  // Children inherit the gate via the parent chain.
+  adminLayout = $page({
+    path: "/admin",
+    use: [$secure({ permissions: ["admin:ui"] })],
+    lazy: () => import("./components/admin/AdminLayout.tsx"),
+  });
+
+  adminUsers = $page({
+    parent: this.adminLayout,
+    path: "/users",
+    head: { title: "Users" },
+    lazy: () => import("./components/admin/Users.tsx"),
+  });
+
+  adminSessions = $page({
+    parent: this.adminLayout,
+    path: "/sessions",
+    head: { title: "Sessions" },
+    lazy: () => import("./components/admin/Sessions.tsx"),
+  });
+
+  notFound = $page({ path: "/*", component: NotFound });
+}
+`;

package/src/cli/core/templates/webIndexTs.ts

@@ -1,9 +1,31 @@
 export interface WebIndexTsOptions {
   appName?: string;
+  /**
+   * SaaS bundle: auth pages need `useAuth()` (ReactAuth) which lives in the
+   * `alepha.react.auth` module. Importing it here registers ReactAuth in the
+   * container so the auth-* registry components can inject it.
+   */
+  saas?: boolean;
 }
 
 export const webIndexTs = (options: WebIndexTsOptions = {}) => {
-  const { appName = "app" } = options;
+  const { appName = "app", saas = false } = options;
+
+  if (saas) {
+    return `
+import { $module } from "alepha";
+import { AlephaReactAuth } from "alepha/react/auth";
+import { AlephaReactI18n } from "alepha/react/i18n";
+import { AppRouter } from "./AppRouter.ts";
+
+export const WebModule = $module({
+  name: "${appName}.web",
+  services: [AppRouter],
+  imports: [AlephaReactAuth, AlephaReactI18n],
+});
+`.trim();
+  }
+
   return `
 import { $module } from "alepha";
 import { AppRouter } from "./AppRouter.ts";

package/src/cli/devtools/index.ts

@@ -1,9 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
-import { $module, AlephaError } from "alepha";
+import { $context, $module, AlephaError } from "alepha";
 import { ViteDevServerProvider } from "alepha/cli";
-import { cliConfigPlugins } from "alepha/cli/config";
 import {
   type DevtoolsOptions,
   devtoolsOptions,
@@ -11,14 +10,6 @@ import {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-declare module "alepha/cli/config" {
-  interface AlephaCliConfig {
-    devtools?: DevtoolsOptions;
-  }
-}
-
-// ---------------------------------------------------------------------------------------------------------------------
-
 const DEVTOOLS_OVERLAY_SCRIPT = `
 (function () {
   if (window.__alepha_devtools_injected) return;
@@ -29,23 +20,19 @@ const DEVTOOLS_OVERLAY_SCRIPT = `
   // Button
   const btn = document.createElement("button");
   btn.id = "alepha-devtools-btn";
-  btn.innerHTML = \`<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z"/><path d="m14.7 6.3-5.4 5.4a2.1 2.1 0 1 0 3 3l5.4-5.4a2.1 2.1 0 1 0-3-3z"/><path d="m8 16 1.5-1.5"/></svg>\`;
+  btn.innerHTML = \`<svg width="28" height="28" viewBox="0 0 300 300" xmlns="http://www.w3.org/2000/svg"><defs><linearGradient id="adb" x1="142.3" x2="159.6" y1="123.3" y2="176.7" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#33a72c"/><stop offset="1" stop-color="#2d8d40"/></linearGradient><linearGradient id="adc" x1="61.6" x2="100.7" y1="218.5" y2="174" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#298e35"/><stop offset="1" stop-color="#327952"/></linearGradient><linearGradient id="add" x1="262.7" x2="242.2" y1="178.4" y2="220.1" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#32a62d"/><stop offset="1" stop-color="#2d8d40"/></linearGradient><linearGradient id="ade" x1="81.2" x2="69.1" y1="126.7" y2="92.3" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#299a2c"/><stop offset="1" stop-color="#51be40"/></linearGradient><clipPath id="ada"><path fill="none" d="M0 0h300v241H0z"/></clipPath></defs><g fill="none" stroke-miterlimit="10" clip-path="url(#ada)"><path fill="url(#adb)" d="M54 174a182 182 0 0 1 106-51c19-2 37-6 54-15l16-11 3-4 1 1 1 4 1 6v9c0 6-2 12-5 18l-1 4-7 8c-5 7-12 14-19 19l-4 2-11 7v1l-1-1-3 2a120 120 0 0 1-30 8l-8 1-20-1c-21-3-44-10-64 0-5 2-9 4-12 8l-9 9h1l14-9c7-4 15-6 23-7h7l25 3 3 1-2 5-3 5c-4 7-10 14-15 18l-4 3c-12 8-25 12-39 13h-5l-5 1h-8l-7-1H15c0-3 4-7 5-9l7-11 5-8c6-10 14-19 22-28z"/><path fill="#1d524a" d="M178 141c9-1 17-4 24-8l8-4-6 4c-9 7-20 11-32 13l-39 5h-5l-15 3 16 13 18 15-20-1c-21-3-44-10-64 0-5 2-9 4-12 8l-9 9h1l14-9c7-4 15-6 23-7h7l25 3 3 1-2 5-3 5c-4 7-10 14-15 18l-4 3c-12 8-25 12-39 13h-5l-5 1h-8l-7-1H15c0-3 4-7 5-9l7-11 5-8c6-10 14-19 22-28l4-2 23-14 11-5c21-7 43-9 65-9l21-3z"/><path fill="url(#adc)" d="M57 189c7-4 15-6 23-7h7l25 3 3 1-2 5-3 5c-4 7-10 14-15 18l-4 3c-12 8-25 12-39 13h-5l-4-9-2-5 5-2 9-4 10-5 10-4c5-2 10-3 14-6l3-1h-1a1136 1136 0 0 0-43 14c1-6 6-14 9-19 1 0 0 0 0 0z"/><path fill="#2d6f4d" d="m41 216 5-2 9-4 5 3c9 4 18 6 27 4h4c-12 8-25 12-39 13h-5l-4-9-2-5zm16-27s1 0 0 0c-3 5-8 13-9 19l-15 8c0-3 1-9 3-11l3-3 4-4 14-9z"/><path fill="#49b63b" d="M42 198h1l-4 4 3-4z"/><path fill="#2d6f4d" d="m113 154 15-3 11 2 18 8c11 6 23 8 35 5l8-2-11 7v1l-1-1-3 2a120 120 0 0 1-30 8l-8 1-18-15-16-13z"/><path fill="#49b63b" d="M81 158c2-4 11-7 15-8 18-6 36-7 55-8l12-1h15l-21 3c-22 0-44 2-65 9l-11 5z"/><path fill="#2d913b" d="m110 52 2-5 9-14c7-8 19-14 29-18l10-3 12-6 1-1 1 1 1 5v6l6 12 5 10 12 26 2 5 4 10 7 17 4 8c-9 5-20 9-30 12l-16 3-7-14-6-14-5-10-1-3-4 7-13 27-6 11-6 2-24 9 2-4c11-16 14-36 11-56l-3 1-9 5 1-3 9-21 2-5z"/><path fill="#2d6f4d" d="m175 17 6 12 5 10 12 26 2 5 4 10 7 17 4 8c-9 5-20 9-30 12l-16 3-7-14-6-14-5-10-1-3c0-2 5-8 6-10l1-2c9-13 17-28 18-45v-5z"/><path fill="#1d524a" d="m175 17 6 12 5 10 12 26 2 5-3-1-13-8-7 4 3 7-4 1-2-3-5-12-5 7a136 136 0 0 1-10 15l-3 2-1-3c0-2 5-8 6-10l1-2c9-13 17-28 18-45v-5z"/><path fill="#2d6f4d" d="m186 39 12 26 2 5-3-1-13-8-7 4-6-12 8-7 7-7z"/><path fill="#2d913b" d="m177 65 7-4 13 8 3 1 4 10-3 7-7 14-2 8-1-4-6-19a99 99 0 0 0-8-21zm-3 5 2 3 12 32h-1l-8 5c-4 1-9 0-13-2l-1-1c-1-8 2-15 4-22 1-5 2-10 5-15z"/><path fill="#1d524a" d="m110 52 2-5 9-14c7-8 19-14 29-18l10-3 12-6 1-1 1 1c-3 1-3 2-4 4l-11 14-5 5v1c-11 11-22 24-31 37l-5 6-6 11h1l6 12c3 7 8 13 14 17l-6 11-6 2-24 9 2-4c11-16 14-36 11-56l-3 1-9 5 1-3 9-21 2-5z"/><path fill="#49b63b" d="m110 52 2-5 9-14c7-8 19-14 29-18l10-3 12-6 1-1 1 1c-3 1-3 2-4 4l-11 14-5 5-8 7-13 11-5 6c-5-2-10-5-15-3l-3 2z"/><path fill="#2d913b" d="m110 52 3-2c5-2 10 1 15 3l-12 13-6 9-3 1-9 5 1-3 9-21 2-5z"/><path fill="#2d6f4d" d="M121 92c10-5 19-9 28-17l7-6c-1 2-6 8-6 10l-4 7-13 27c-6-4-11-10-14-17l-6-12 4-5 4 13z"/><path fill="#49b63b" d="m154 30-1 11c0 4-3 9-6 12-6 9-19 10-25 19-1 0-3 2-4 1l5-6c9-13 20-26 31-37z"/><path fill="url(#add)" d="m230 135 3 6 11 17 2 5 4 5 3 6 9 14 19 36 4 5c-2 2-19 2-22 2l-5-1h-2c-12 0-25-4-35-10l-4-3c-10-8-15-16-21-27l-7-18v-1l11-7 4-2c7-5 14-12 19-19l7-8z"/><path fill="#1d524a" d="m230 135 3 6 11 17 2 5 4 5 3 6h-1c-10-8-20-9-32-4l23 23 13 12 1 2-20-14-13-12-4-3-5-6c-2 0-2 3-2 5l-1 10c-1 8-2 11 1 19l2 6 2 5c-10-8-15-16-21-27l-7-18v-1l11-7 4-2c7-5 14-12 19-19l7-8z"/><path fill="#2d6f4d" d="m233 141 11 17 2 5 4 5 3 6h-1c-10-8-20-9-32-4l-7-9 15-15 5-5zm-16 76-2-5-2-6c-3-8-2-11-1-19l1-10c0-2 0-5 2-5l5 6 4 3h-1c0 4 8 22 11 26 6 10 15 18 25 22 2 0 3 0 4 2l-5-1h-2c-12 0-25-4-35-10l-4-3z"/><path fill="#2d913b" d="M110 75c3 20 0 40-11 56l-2 4a145 145 0 0 0-43 31l-5 4-11 15v-7l-1-10a143 143 0 0 1 5-29l9-20c13-18 32-29 52-37l4-3 3-4z"/><path fill="url(#ade)" d="m42 139 9-20c13-18 32-29 52-37l4-3-3 7c-4 5-8 11-13 15l-3 3c-6 6-13 12-18 19l-8 11-20 5z"/><path fill="#1d524a" d="M91 101c0 2-4 6-6 8-5 5-10 11-14 18l-9 13-4 9 5 1c4 0 16-9 19-7-10 7-20 14-28 23l-5 4-11 15v-7l-1-10a143 143 0 0 1 5-29l20-5 8-11c5-7 12-13 18-19l3-3z"/><path fill="#2d6f4d" d="m62 134-9 16-3 7-2 4c-3 3-8 5-10 8l-1-1a143 143 0 0 1 5-29l20-5zm0 6 11-5 7-4c5-1 14-2 19 0l-2 4-15 8c-3-2-15 7-19 7l-5-1 4-9z"/></g></svg>\`;
   Object.assign(btn.style, {
-    position: "fixed", bottom: "16px", right: "16px", zIndex: "99998",
+    position: "fixed", bottom: "16px", left: "16px", zIndex: "99998",
     width: "40px", height: "40px", borderRadius: "50%",
-    background: "#1a1a2e", color: "#a0a0c0", border: "1px solid #2a2a4a",
+    background: "#fff", border: "1px solid #2a2a4a",
     cursor: "pointer", display: "flex", alignItems: "center", justifyContent: "center",
     boxShadow: "0 2px 8px rgba(0,0,0,0.3)", transition: "all 0.2s",
     padding: "0", fontSize: "0",
   });
   btn.addEventListener("mouseenter", () => {
-    btn.style.background = "#2a2a4e";
-    btn.style.color = "#c0c0e0";
     btn.style.transform = "scale(1.1)";
   });
   btn.addEventListener("mouseleave", () => {
-    btn.style.background = "#1a1a2e";
-    btn.style.color = "#a0a0c0";
     btn.style.transform = "scale(1)";
   });
 
@@ -110,10 +97,10 @@ const DEVTOOLS_OVERLAY_SCRIPT = `
  *
  * Usage in `alepha.config.ts`:
  * ```ts
- * import { AlephaCliDevtoolsPlugin } from "alepha/devtools/plugin";
+ * import { devtools } from "alepha/cli/devtools";
  *
  * export default defineConfig({
- *   services: [AlephaCliDevtoolsPlugin],
+ *   plugins: [devtools()],
  * });
  * ```
  *
@@ -201,13 +188,12 @@ export const AlephaCliDevtoolsPlugin = $module({
   },
 });
 
-// ---------------------------------------------------------------------------------------------------------------------
-
-cliConfigPlugins.push((config, alepha) => {
-  if (config.devtools) {
-    alepha.set(devtoolsOptions, config.devtools);
-  }
-});
+export const devtools = (options: DevtoolsOptions = {}) => {
+  return () => {
+    const { alepha } = $context();
+    alepha.with(AlephaCliDevtoolsPlugin).set(devtoolsOptions, options);
+  };
+};
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/cli/platform/__tests__/SecretsCommand.spec.ts

@@ -252,8 +252,10 @@ describe("SecretsCommand", () => {
 
       const output = writes.join("");
       expect(output).toContain("env:");
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: GitHub Actions `${{ ... }}` syntax in plain string
       expect(output).toContain("API_KEY: ${{ secrets.API_KEY }}");
       expect(output).toContain(
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: GitHub Actions `${{ ... }}` syntax in plain string
         "GITHUB_CLIENT_ID: ${{ secrets.APP_GITHUB_CLIENT_ID }}",
       );
     });

package/src/cli/platform/index.ts

@@ -1,6 +1,5 @@
-import { $module } from "alepha";
+import { $context, $module } from "alepha";
 import { AlephaCli } from "alepha/cli";
-import { cliConfigPlugins } from "alepha/cli/config";
 import { CloudflareAdapter } from "./adapters/CloudflareAdapter.ts";
 import { VercelAdapter } from "./adapters/VercelAdapter.ts";
 import {
@@ -23,14 +22,6 @@ import { WranglerApi } from "./services/WranglerApi.ts";
 
 // ---------------------------------------------------------------------------
 
-declare module "alepha/cli/config" {
-  interface AlephaCliConfig {
-    platform?: PlatformOptions;
-  }
-}
-
-// ---------------------------------------------------------------------------
-
 /**
  * CLI plugin for multi-cloud deployment orchestration.
  *
@@ -51,15 +42,16 @@ declare module "alepha/cli/config" {
  * Configuration in `alepha.config.ts`:
  *
  * ```typescript
- * import { AlephaCliPlatformPlugin } from "alepha/cli/platform";
+ * import { platform } from "alepha/cli/platform";
  *
  * export default defineConfig({
- *   services: [AlephaCliPlatformPlugin],
- *   platform: {
- *     environments: {
- *       production: { adapter: "cloudflare", domain: "myapp.com" },
- *     },
- *   },
+ *   plugins: [
+ *     platform({
+ *       environments: {
+ *         production: { adapter: "cloudflare", domain: "myapp.com" },
+ *       },
+ *     }),
+ *   ],
  * });
  * ```
  */
@@ -85,13 +77,12 @@ export const AlephaCliPlatformPlugin = $module({
   ],
 });
 
-// ---------------------------------------------------------------------------
-
-cliConfigPlugins.push((config, alepha) => {
-  if (config.platform) {
-    alepha.set(platformOptions, config.platform);
-  }
-});
+export const platform = (options: PlatformOptions) => {
+  return () => {
+    const { alepha } = $context();
+    alepha.with(AlephaCliPlatformPlugin).set(platformOptions, options);
+  };
+};
 
 // ---------------------------------------------------------------------------
 

package/src/cli/vendor/atoms/vendorOptions.ts

@@ -28,7 +28,7 @@ export const vendorOptions = $atom({
       /**
        * Package directory names under `packages/` to sync.
        *
-       * @example ["alepha", "@alepha/bucket-s3"]
+       * @example ["alepha", "@alepha/payments-stripe"]
        */
       packages: t.array(t.text()),
     }),

package/src/cli/vendor/index.ts

@@ -1,19 +1,10 @@
-import { $module } from "alepha";
-import { cliConfigPlugins } from "alepha/cli/config";
+import { $context, $module } from "alepha";
 import { type VendorOptions, vendorOptions } from "./atoms/vendorOptions.ts";
 import { VendorCommand } from "./commands/VendorCommand.ts";
 import { VendorService } from "./services/VendorService.ts";
 
 // ---------------------------------------------------------------------------
 
-declare module "alepha/cli/config" {
-  interface AlephaCliConfig {
-    vendor?: VendorOptions;
-  }
-}
-
-// ---------------------------------------------------------------------------
-
 /**
  * CLI plugin for vendoring Alepha packages into external projects.
  *
@@ -28,14 +19,15 @@ declare module "alepha/cli/config" {
  * Configuration in `alepha.config.ts`:
  *
  * ```typescript
- * import { AlephaCliVendorPlugin } from "alepha/cli/vendor";
+ * import { vendor } from "alepha/cli/vendor";
  *
  * export default defineConfig({
- *   services: [AlephaCliVendorPlugin],
- *   vendor: {
- *     branch: "main",
- *     packages: ["alepha", "@alepha/bucket-s3"],
- *   },
+ *   plugins: [
+ *     vendor({
+ *       branch: "main",
+ *       packages: ["alepha", "@alepha/payments-stripe"],
+ *     }),
+ *   ],
  * });
  * ```
  */
@@ -45,13 +37,12 @@ export const AlephaCliVendorPlugin = $module({
   services: [VendorCommand, VendorService],
 });
 
-// ---------------------------------------------------------------------------
-
-cliConfigPlugins.push((config, alepha) => {
-  if (config.vendor) {
-    alepha.set(vendorOptions, config.vendor);
-  }
-});
+export const vendor = (options: VendorOptions) => {
+  return () => {
+    const { alepha } = $context();
+    alepha.with(AlephaCliVendorPlugin).set(vendorOptions, options);
+  };
+};
 
 // ---------------------------------------------------------------------------
 

package/src/command/providers/CliProvider.ts

@@ -555,7 +555,7 @@ export class CliProvider {
     const parsed = this.parseFlags(argv, flagDefs);
 
     // Remove the mode flag from parsed result (it's handled separately)
-    delete parsed.__mode__;
+    parsed.__mode__ = undefined;
 
     // apply manually defaults for optional properties that have defaults
     for (const [key, value] of Object.entries(schema.properties)) {