alepha 0.22.0 → 0.24.0

package/src/cli/core/tasks/BuildPrerenderTask.ts

@@ -4,11 +4,18 @@ import { FileSystemProvider } from "alepha/system";
 import { BuildTask, type BuildTaskContext } from "./BuildTask.ts";
 
 /**
- * Pre-render static pages defined in the Alepha application.
+ * Pre-render static pages and routes defined in the Alepha application.
  *
- * Queries all page primitives with `static: true` and generates
- * static HTML files for each page. Supports pages with parameterized
- * routes via `static.entries` configuration.
+ * Two passes, both writing into `dist/public`:
+ * - **pages** — every `$page` with `static: true` is rendered to an HTML file
+ *   (supports parameterized routes via `static.entries`).
+ * - **routes** — every `static` route primitive (a `$route({ static: true })`
+ *   or a `$sitemap`) is invoked in-process and its body written verbatim to
+ *   `{path}` (e.g. `sitemap.xml`, `robots.txt`).
+ *
+ * Both passes read the primitive registry and call a method on the already
+ * created primitive instances — no provider is re-injected, so this works in
+ * the build's configured-but-not-started container.
  */
 export class BuildPrerenderTask extends BuildTask {
   protected readonly fs = $inject(FileSystemProvider);
@@ -22,7 +29,8 @@ export class BuildPrerenderTask extends BuildTask {
     }
 
     const pages = this.getStaticPages(ctx);
-    if (pages.length === 0) {
+    const routes = this.getStaticRoutePrimitives(ctx);
+    if (pages.length === 0 && routes.length === 0) {
       return;
     }
 
@@ -31,13 +39,18 @@ export class BuildPrerenderTask extends BuildTask {
     const dist = this.fs.join(ctx.root, distDir, publicDir);
 
     await ctx.run({
-      name: "pre-render pages",
+      name: "pre-render",
       handler: async () => {
         // TODO: running configure here is a temporary workaround
         if (!ctx.alepha.isConfigured()) {
           await ctx.alepha.events.emit("configure", ctx.alepha);
         }
-        await this.prerenderFromAlepha(pages, dist);
+        if (pages.length > 0) {
+          await this.prerenderFromAlepha(pages, dist);
+        }
+        if (routes.length > 0) {
+          await this.prerenderRoutes(routes, dist);
+        }
       },
     });
   }
@@ -50,6 +63,18 @@ export class BuildPrerenderTask extends BuildTask {
     });
   }
 
+  /**
+   * Static route primitives to snapshot: `$route({ static: true })` and every
+   * `$sitemap`. Both expose an async `prerender(): { path, body }`.
+   */
+  protected getStaticRoutePrimitives(ctx: BuildTaskContext): any[] {
+    const routes = (ctx.alepha.primitives("route") as any[]).filter(
+      (route) => route.options?.static === true,
+    );
+    const sitemaps = ctx.alepha.primitives("sitemap") as any[];
+    return [...routes, ...sitemaps];
+  }
+
   protected async prerenderFromAlepha(
     pages: any[],
     dist: string,
@@ -77,6 +102,18 @@ export class BuildPrerenderTask extends BuildTask {
     return count;
   }
 
+  protected async prerenderRoutes(
+    primitives: any[],
+    dist: string,
+  ): Promise<void> {
+    for (const primitive of primitives) {
+      const { path, body } = await primitive.prerender();
+      const filepath = this.fs.join(dist, path);
+      await this.fs.mkdir(dirname(filepath));
+      await this.fs.writeFile(filepath, body);
+    }
+  }
+
   protected async renderFile(
     page: any,
     options: any,

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

@@ -1,9 +1,9 @@
 export const apiHelloResponseSchemaTs = () => {
-  return `import { type Static, t } from "alepha";
+  return `import { type Static, z } from "alepha";
 
-export const helloResponseSchema = t.object({
-  appName: t.text(),
-  serverTime: t.datetime(),
+export const helloResponseSchema = z.object({
+  appName: z.text(),
+  serverTime: z.datetime(),
 });
 
 export type HelloResponse = Static<typeof helloResponseSchema>;

package/src/cli/devtools/atoms/devtoolsOptions.ts

@@ -1,4 +1,4 @@
-import { $atom, type Static, t } from "alepha";
+import { $atom, type Static, z } from "alepha";
 
 /**
  * Devtools configuration atom.
@@ -8,16 +8,16 @@ import { $atom, type Static, t } from "alepha";
 export const devtoolsOptions = $atom({
   name: "alepha.cli.devtools.options",
   description: "Devtools plugin configuration",
-  schema: t.optional(
-    t.object({
+  schema: z
+    .object({
       /**
        * Hide the floating devtools button in the browser.
        *
        * The devtools UI is still accessible at `/__devtools/`.
        */
-      hideButton: t.optional(t.boolean({ default: false })),
-    }),
-  ),
+      hideButton: z.boolean().default(false).optional(),
+    })
+    .optional(),
 });
 
 /**

package/src/cli/i18n/__tests__/I18nCheckService.spec.ts

@@ -109,6 +109,54 @@ ${body}
     expect(result.unused).toEqual(["home.title"]);
   });
 
+  it("extracts keys from lazily-imported per-language files", async () => {
+    await env.fs.mkdir(`${ROOT}/src/web/i18n`, { recursive: true });
+    // Marker file declares `$dictionary` but the keys live in split,
+    // markerless per-language files referenced via `lazy: () => import(...)`.
+    // A sibling `$page` lazy import must NOT be mistaken for a key file.
+    await env.fs.writeFile(
+      `${ROOT}/src/web/Router.ts`,
+      `import { $dictionary } from "alepha/react/i18n";
+export class Router {
+  fr = $dictionary({ lazy: () => import("./i18n/fr.ts"), lang: "fr" });
+  en = $dictionary({ lazy: () => import("./i18n/en.ts"), lang: "en" });
+  page = $page({ lazy: () => import("./Home.tsx") });
+}
+`,
+    );
+    await env.fs.writeFile(
+      `${ROOT}/src/web/i18n/fr.ts`,
+      `export default { "home.title": "Accueil", "home.unused": "Rien" };`,
+    );
+    await env.fs.writeFile(
+      `${ROOT}/src/web/i18n/en.ts`,
+      `export default { "home.title": "Home", "home.unused": "Nothing" };`,
+    );
+    // The only reference — `home.unused` is dead in both languages. The
+    // `"home.title": "…"` lines in the sibling language file must not count
+    // as references (key files are excluded from the usage corpus).
+    await env.fs.writeFile(
+      `${ROOT}/src/web/Home.tsx`,
+      `export const Home = () => tr("home.title");`,
+    );
+
+    const result = await env.service.check({
+      root: ROOT,
+      scan: ["src"],
+      dynamicPrefixes: [],
+      exclude: [],
+    });
+
+    expect(result.totalKeys).toBe(2);
+    expect(result.unused).toEqual(["home.unused"]);
+    // The resolved language file is treated as a dictionary; the sibling
+    // `$page` lazy import is not (it contributed no keys and stays in the
+    // usage corpus). `en.ts` is also a dictionary file but adds no *new*
+    // keys, so only the first contributor is listed.
+    expect(result.dictionaryFiles).toContain(`${ROOT}/src/web/i18n/fr.ts`);
+    expect(result.dictionaryFiles).not.toContain(`${ROOT}/src/web/Home.tsx`);
+  });
+
   it("returns totalKeys=0 when no dictionary is found", async () => {
     await env.fs.mkdir(`${ROOT}/src`, { recursive: true });
     await env.fs.writeFile(

package/src/cli/i18n/atoms/i18nOptions.ts

@@ -1,4 +1,4 @@
-import { $atom, type Static, t } from "alepha";
+import { $atom, type Static, z } from "alepha";
 
 /**
  * i18n CLI configuration atom.
@@ -9,15 +9,15 @@ import { $atom, type Static, t } from "alepha";
 export const i18nOptions = $atom({
   name: "alepha.cli.i18n.options",
   description: "i18n unused-key check configuration",
-  schema: t.optional(
-    t.object({
+  schema: z
+    .object({
       /**
        * Directories (relative to the project root) to scan both for
        * `$dictionary(...)` declarations and for translation key usage.
        *
        * @default ["src"]
        */
-      scan: t.optional(t.array(t.text())),
+      scan: z.array(z.text()).optional(),
 
       /**
        * Key prefixes that are constructed at runtime (e.g. via template
@@ -30,7 +30,7 @@ export const i18nOptions = $atom({
        *
        * @default []
        */
-      dynamicPrefixes: t.optional(t.array(t.text())),
+      dynamicPrefixes: z.array(z.text()).optional(),
 
       /**
        * Additional path substrings (matched against the full file
@@ -40,9 +40,9 @@ export const i18nOptions = $atom({
        *
        * @default []
        */
-      exclude: t.optional(t.array(t.text())),
-    }),
-  ),
+      exclude: z.array(z.text()).optional(),
+    })
+    .optional(),
 });
 
 /**

package/src/cli/i18n/services/I18nCheckService.ts

@@ -35,6 +35,22 @@ const KEY_DECLARATION_RE = /"([\w-]+(?:\.[\w-]+)+)"\s*:/g;
  */
 const DICTIONARY_MARKER = "$dictionary";
 
+/**
+ * Captures the module specifier of a lazily-imported dictionary, i.e. the
+ * `"./fr.ts"` in `$dictionary({ lazy: () => import("./fr.ts") })`. Apps
+ * commonly split each language into its own file so a session only ships the
+ * active locale — those key files carry no `$dictionary` marker, so without
+ * this the keys would be invisible to the check.
+ *
+ * `[^{}]*?` keeps the match inside the `$dictionary` call's own object literal
+ * (it stops at the first brace), so unrelated lazy imports in the same file —
+ * e.g. a sibling `$page({ lazy: () => import("./Page.tsx") })` or a
+ * `$dictionary` whose `lazy` returns an inline `({ default: {…} })` object —
+ * are never mistaken for dictionary key files.
+ */
+const DICTIONARY_LAZY_IMPORT_RE =
+  /\$dictionary\s*\(\s*\{[^{}]*?import\s*\(\s*["']([^"']+)["']/g;
+
 export interface I18nCheckOptions {
   root: string;
   scan: string[];
@@ -62,11 +78,11 @@ export class I18nCheckService {
    * Find unused translation keys.
    *
    * Discovery is fully static: we walk `scan` dirs, identify files
-   * that import `$dictionary` (matched via the literal substring),
-   * extract every `"a.b.c": ...` property key declared in them, then
-   * grep the remaining source files for a quoted-literal occurrence
-   * of each key. Anything matching a `dynamicPrefixes` entry is
-   * exempted.
+   * that import `$dictionary` (matched via the literal substring) plus
+   * any per-language files they lazily `import(...)`, extract every
+   * `"a.b.c": ...` property key declared across them, then grep the
+   * remaining source files for a quoted-literal occurrence of each key.
+   * Anything matching a `dynamicPrefixes` entry is exempted.
    */
   async check(options: I18nCheckOptions): Promise<I18nCheckResult> {
     const { root, scan, dynamicPrefixes, exclude } = options;
@@ -91,14 +107,31 @@ export class I18nCheckService {
       }
     }
 
-    const dictionaryFiles: string[] = [];
-    const allKeys = new Set<string>();
     const fileContents = new Map<string, string>();
-
     for (const file of allFiles) {
-      const text = (await this.fs.readFile(file)).toString("utf8");
-      fileContents.set(file, text);
+      fileContents.set(file, (await this.fs.readFile(file)).toString("utf8"));
+    }
+
+    // A file is a dictionary if it declares `$dictionary` OR it is the target
+    // of a `$dictionary({ lazy: () => import("…") })` (the split per-language
+    // key files, which carry no marker of their own). Resolving the lazy
+    // targets first lets their keys be extracted below and keeps them out of
+    // the usage corpus (their `"key": "value"` lines aren't references).
+    const dictionarySet = new Set<string>();
+    for (const [file, text] of fileContents) {
       if (!text.includes(DICTIONARY_MARKER)) continue;
+      dictionarySet.add(file);
+      for (const m of text.matchAll(DICTIONARY_LAZY_IMPORT_RE)) {
+        const target = this.resolveImport(file, m[1], fileContents);
+        if (target) dictionarySet.add(target);
+      }
+    }
+
+    const dictionaryFiles: string[] = [];
+    const allKeys = new Set<string>();
+    for (const file of dictionarySet) {
+      const text = fileContents.get(file);
+      if (!text) continue;
       const before = allKeys.size;
       for (const m of text.matchAll(KEY_DECLARATION_RE)) {
         allKeys.add(m[1]);
@@ -108,7 +141,6 @@ export class I18nCheckService {
 
     // Concatenate every non-dictionary file into one corpus so each
     // key is tested with a single regex run rather than O(files × keys).
-    const dictionarySet = new Set(dictionaryFiles);
     const corpusParts: string[] = [];
     let scannedFiles = 0;
     for (const [file, text] of fileContents) {
@@ -141,4 +173,26 @@ export class I18nCheckService {
       unused: unused.sort(),
     };
   }
+
+  /**
+   * Resolve a relative `import("…")` specifier from `fromFile` to an absolute
+   * path that was actually scanned. Returns `undefined` for bare/package
+   * specifiers or targets outside the scan set. Extensionless specifiers are
+   * probed against each supported source extension.
+   */
+  protected resolveImport(
+    fromFile: string,
+    spec: string,
+    files: Map<string, string>,
+  ): string | undefined {
+    if (!spec.startsWith(".")) return undefined;
+    // `join(file, "..", spec)` drops the filename then applies the relative
+    // specifier — i.e. resolves against `fromFile`'s directory.
+    const base = this.fs.join(fromFile, "..", spec);
+    if (files.has(base)) return base;
+    for (const ext of SCAN_EXTS) {
+      if (files.has(base + ext)) return base + ext;
+    }
+    return undefined;
+  }
 }

package/src/cli/platform/commands/SecretsCommand.ts

@@ -1,4 +1,4 @@
-import { $inject, $state, AlephaError, t } from "alepha";
+import { $inject, $state, AlephaError, z } from "alepha";
 import {
   GitHubSecretStore,
   NamingService,
@@ -20,13 +20,13 @@ export class SecretsCommand {
   protected readonly filter = $inject(SecretFilterService);
   protected readonly color = $inject(ConsoleColorProvider);
 
-  protected readonly envFlags = t.object({
-    env: t.optional(
-      t.text({
+  protected readonly envFlags = z.object({
+    env: z
+      .text({
         aliases: ["e"],
         description: "Target environment",
-      }),
-    ),
+      })
+      .optional(),
   });
 
   // -----------------------------------------------------------------------
@@ -38,19 +38,19 @@ export class SecretsCommand {
     aliases: ["ls"],
     description:
       "List secret names stored in the remote store for an environment (values are never returned). Use --format=gha to emit a ready-to-paste GitHub Actions env: block.",
-    flags: t.object({
-      env: t.optional(
-        t.text({
+    flags: z.object({
+      env: z
+        .text({
           aliases: ["e"],
           description: "Target environment",
-        }),
-      ),
-      format: t.optional(
-        t.text({
+        })
+        .optional(),
+      format: z
+        .text({
           aliases: ["f"],
           description: "Output format: table (default), gha",
-        }),
-      ),
+        })
+        .optional(),
     }),
     handler: async ({ flags, root, run }) => {
       const config = await this.inspector.resolveConfig(root);
@@ -182,18 +182,17 @@ export class SecretsCommand {
     name: "apply",
     description:
       "Push secrets from local .env.<env> to the remote store (one upsert per key). Use --dry-run to preview. Existing remote keys not present locally are left untouched — this command never deletes.",
-    flags: t.object({
-      env: t.optional(
-        t.text({
+    flags: z.object({
+      env: z
+        .text({
           aliases: ["e"],
           description: "Target environment",
-        }),
-      ),
-      "dry-run": t.optional(
-        t.boolean({
-          description: "Preview changes without pushing",
-        }),
-      ),
+        })
+        .optional(),
+      "dry-run": z
+        .boolean()
+        .describe("Preview changes without pushing")
+        .optional(),
     }),
     handler: async ({ flags, root, run }) => {
       const config = await this.inspector.resolveConfig(root);

package/src/cli/platform/commands/platform.ts

@@ -1,4 +1,4 @@
-import { $inject, $state, AlephaError, t } from "alepha";
+import { $inject, $state, AlephaError, z } from "alepha";
 import { type AppEntry, AppEntryProvider, ViteBuildProvider } from "alepha/cli";
 import {
   CloudflareAdapter,
@@ -32,30 +32,25 @@ export class PlatformCommand {
   /**
    * Common flags for env targeting.
    */
-  protected readonly envFlags = t.object({
-    env: t.optional(
-      t.text({
+  protected readonly envFlags = z.object({
+    env: z
+      .text({
         aliases: ["e"],
         description: "Target environment",
-      }),
-    ),
-    tenant: t.optional(
-      t.text({
+      })
+      .optional(),
+    tenant: z
+      .text({
         description:
           "Tenant slug (apps with tenancy: optional | required). Names resources <tenant>-<project>-<env> and serves <tenant>.<domain>.",
-      }),
-    ),
-    verbose: t.optional(
-      t.boolean({
-        aliases: ["v"],
-        description: "Verbose output",
-      }),
-    ),
-    json: t.optional(
-      t.boolean({
-        description: "Output as JSON",
-      }),
-    ),
+      })
+      .optional(),
+    verbose: z
+      .boolean()
+      .meta({ aliases: ["v"] })
+      .describe("Verbose output")
+      .optional(),
+    json: z.boolean().describe("Output as JSON").optional(),
   });
 
   // -----------------------------------------------------------------------
@@ -215,14 +210,14 @@ export class PlatformCommand {
     name: "up",
     mode: "production",
     description: "Build, migrate, and deploy",
-    flags: t.object({
+    flags: z.object({
       ...this.envFlags.properties,
-      prebuilt: t.optional(
-        t.boolean({
-          description:
-            "Pre-built mode. Skips the Vite bundle steps; only regenerates the target deploy config (wrangler.jsonc) so it reflects current bindings and per-tenant overrides. Use when `dist/` is already produced upstream (e.g. inside Alepha Rocket).",
-        }),
-      ),
+      prebuilt: z
+        .boolean()
+        .describe(
+          "Pre-built mode. Skips the Vite bundle steps; only regenerates the target deploy config (wrangler.jsonc) so it reflects current bindings and per-tenant overrides. Use when `dist/` is already produced upstream (e.g. inside Alepha Rocket).",
+        )
+        .optional(),
     }),
     handler: async ({ flags, root, run }) => {
       process.env.NODE_ENV = "production";
@@ -275,15 +270,15 @@ export class PlatformCommand {
   protected readonly down = $command({
     name: "down",
     description: "Tear down an environment",
-    flags: t.object({
+    flags: z.object({
       ...this.envFlags.properties,
-      yes: t.optional(
-        t.boolean({
-          aliases: ["y"],
-          description:
-            "Skip the interactive confirmation. Required for non-interactive callers (CI, Alepha Rocket). The caller is responsible for not invoking this accidentally — there's no second chance.",
-        }),
-      ),
+      yes: z
+        .boolean()
+        .meta({ aliases: ["y"] })
+        .describe(
+          "Skip the interactive confirmation. Required for non-interactive callers (CI, Alepha Rocket). The caller is responsible for not invoking this accidentally — there's no second chance.",
+        )
+        .optional(),
     }),
     handler: async ({ flags, root, run, ask }) => {
       if (!flags.env) {
@@ -635,19 +630,18 @@ export class PlatformCommand {
     name: "export",
     description:
       "Export the deployed database to a local snapshot (remote → local dev DB).",
-    flags: t.object({
+    flags: z.object({
       ...this.envFlags.properties,
-      output: t.optional(
-        t.text({
+      output: z
+        .text({
           description:
             "Destination SQLite file. Defaults to the dev DB path (node_modules/.alepha/sqlite.db).",
-        }),
-      ),
-      keepSql: t.optional(
-        t.boolean({
-          description: "Keep the intermediate .sql dump file.",
-        }),
-      ),
+        })
+        .optional(),
+      keepSql: z
+        .boolean()
+        .describe("Keep the intermediate .sql dump file.")
+        .optional(),
     }),
     handler: async ({ flags, root, run }) => {
       const config = await this.inspector.resolveConfig(root);

package/src/cli/platform/index.ts

@@ -64,7 +64,7 @@ export const platform = (options: PlatformOptions) => {
   // places. Honors an explicit env override and any non-production-only
   // setup (we don't override prod-set values).
   if (!process.env.PUBLIC_URL) {
-    const productionDomain = options.environments?.production?.domain;
+    const productionDomain = options?.environments?.production?.domain;
     if (productionDomain) {
       process.env.PUBLIC_URL = `https://${productionDomain}`;
     }

package/src/cli/platform-lib/__tests__/CloudflareAdapter.spec.ts

@@ -935,8 +935,6 @@ describe("CloudflareAdapter", () => {
       const run: any = async (cmd: any) => {
         if (typeof cmd === "string") commands.push(cmd);
       };
-      run.pause = () => {};
-      run.resume = () => {};
       run.end = () => {};
 
       await adapter.exportDb(ctx, run, {
@@ -977,8 +975,6 @@ function createMockRun(): any {
       await task.handler();
     }
   };
-  run.pause = () => {};
-  run.resume = () => {};
   run.end = () => {};
   return run;
 }

package/src/cli/platform-lib/__tests__/PlatformInspector.spec.ts

@@ -5,7 +5,7 @@ import { platformOptions } from "../atoms/platformOptions.ts";
 import { PlatformInspector } from "../services/PlatformInspector.ts";
 
 describe("PlatformInspector", () => {
-  const createTestEnv = (config: Record<string, any> = {}) => {
+  const createTestEnv = (config?: Record<string, any>) => {
     const alepha = Alepha.create().with({
       provide: FileSystemProvider,
       use: MemoryFileSystemProvider,
@@ -14,7 +14,14 @@ describe("PlatformInspector", () => {
     const fs = alepha.inject(MemoryFileSystemProvider);
     const inspector = alepha.inject(PlatformInspector);
 
-    alepha.set(platformOptions, config as any);
+    // Only write the atom when the test actually provides a config —
+    // `platformOptions.schema` requires `environments`, so an empty object
+    // is not a valid "configured" state. Leaving the atom unset is how a
+    // real "no platform config" run looks (falls through to the
+    // dist/manifest.json fallback in PlatformInspector.resolveConfig).
+    if (config) {
+      alepha.set(platformOptions, config as any);
+    }
 
     return { alepha, fs, inspector };
   };
@@ -22,7 +29,7 @@ describe("PlatformInspector", () => {
   test("throws when platform is not configured in CI", async ({ expect }) => {
     process.env.CI = "1";
     try {
-      const { inspector } = createTestEnv({});
+      const { inspector } = createTestEnv();
       await expect(inspector.resolveConfig("/project")).rejects.toThrowError(
         AlephaError,
       );

package/src/cli/platform-lib/__tests__/VercelAdapter.spec.ts

@@ -479,8 +479,6 @@ function createMockRun(): any {
       await task.handler();
     }
   };
-  run.pause = () => {};
-  run.resume = () => {};
   run.end = () => {};
   return run;
 }