alepha 0.20.1 → 0.20.2

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

@@ -22,9 +22,9 @@ import {
   cloudflareKVSchema,
   cloudflareQueueConsumerSchema,
   cloudflareQueueSchema,
-  cloudflareR2ListSchema,
+  cloudflareR2Schema,
   cloudflareSecretSchema,
-  cloudflareVersionListSchema,
+  cloudflareVersionSchema,
   cloudflareWorkerSchema,
   createD1BodySchema,
   createHyperdriveBodySchema,
@@ -81,6 +81,16 @@ export class CloudflareApi {
     this.jurisdiction = jurisdiction;
   }
 
+  /**
+   * Override the Cloudflare account ID (from platform config).
+   *
+   * When unset, `resolveAccountId` falls back to `CLOUDFLARE_ACCOUNT_ID` env
+   * var or the token's single account.
+   */
+  public setAccountId(accountId?: string): void {
+    this.accountId = accountId;
+  }
+
   // -------------------------------------------------------------------------
   // Auth
   // -------------------------------------------------------------------------
@@ -107,6 +117,12 @@ export class CloudflareApi {
       return this.accountId;
     }
 
+    const fromEnv = process.env.CLOUDFLARE_ACCOUNT_ID;
+    if (fromEnv) {
+      this.accountId = fromEnv;
+      return this.accountId;
+    }
+
     const res = await this.fetch<CloudflareAccount[]>("/accounts", {
       schema: t.array(cloudflareAccountSchema),
     });
@@ -115,6 +131,15 @@ export class CloudflareApi {
       throw new AlephaError("No Cloudflare accounts found for this token.");
     }
 
+    if (res.length > 1) {
+      const list = res.map((a) => `  - ${a.id}  ${a.name}`).join("\n");
+      throw new AlephaError(
+        `Cloudflare token has access to ${res.length} accounts; set ` +
+          `\`CLOUDFLARE_ACCOUNT_ID\` or the \`accountId\` field in your ` +
+          `platform config to pick one:\n${list}`,
+      );
+    }
+
     this.accountId = res[0].id;
     return this.accountId;
   }
@@ -125,9 +150,9 @@ export class CloudflareApi {
 
   public async listD1(): Promise<CloudflareD1[]> {
     const accountId = await this.resolveAccountId();
-    return await this.fetch<CloudflareD1[]>(
+    return await this.paginate<CloudflareD1>(
       `/accounts/${accountId}/d1/database`,
-      { schema: t.array(cloudflareD1Schema) },
+      cloudflareD1Schema,
     );
   }
 
@@ -136,15 +161,19 @@ export class CloudflareApi {
     location = "weur", // TODO: move to config (or auto-resolve based on account info, or ask ?)
   ): Promise<CloudflareD1> {
     const accountId = await this.resolveAccountId();
+    // When jurisdiction is set, `primary_location_hint` is silently ignored
+    // by the API, so omit it to avoid confusion.
+    const body: Record<string, unknown> = { name };
+    if (this.jurisdiction) {
+      body.jurisdiction = this.jurisdiction;
+    } else {
+      body.primary_location_hint = location;
+    }
     return await this.fetch<CloudflareD1>(
       `/accounts/${accountId}/d1/database`,
       {
         method: "POST",
-        body: {
-          name,
-          primary_location_hint: location,
-          ...(this.jurisdiction ? { jurisdiction: this.jurisdiction } : {}),
-        },
+        body,
         bodySchema: createD1BodySchema,
         schema: cloudflareD1Schema,
       },
@@ -164,9 +193,10 @@ export class CloudflareApi {
 
   public async listKV(): Promise<CloudflareKV[]> {
     const accountId = await this.resolveAccountId();
-    return await this.fetch<CloudflareKV[]>(
+    return await this.paginate<CloudflareKV>(
       `/accounts/${accountId}/storage/kv/namespaces`,
-      { schema: t.array(cloudflareKVSchema) },
+      cloudflareKVSchema,
+      100, // KV list caps at 100 per page
     );
   }
 
@@ -197,11 +227,11 @@ export class CloudflareApi {
 
   public async listR2(): Promise<CloudflareR2[]> {
     const accountId = await this.resolveAccountId();
-    const res = await this.fetch<{ buckets: CloudflareR2[] }>(
+    return await this.paginateCursor<CloudflareR2>(
       `/accounts/${accountId}/r2/buckets`,
-      { schema: cloudflareR2ListSchema },
+      "buckets",
+      cloudflareR2Schema,
     );
-    return res.buckets;
   }
 
   public async createR2(name: string): Promise<void> {
@@ -226,9 +256,9 @@ export class CloudflareApi {
 
   public async listQueues(): Promise<CloudflareQueue[]> {
     const accountId = await this.resolveAccountId();
-    return await this.fetch<CloudflareQueue[]>(
+    return await this.paginate<CloudflareQueue>(
       `/accounts/${accountId}/queues`,
-      { schema: t.array(cloudflareQueueSchema) },
+      cloudflareQueueSchema,
     );
   }
 
@@ -253,9 +283,9 @@ export class CloudflareApi {
     queueId: string,
   ): Promise<CloudflareQueueConsumer[]> {
     const accountId = await this.resolveAccountId();
-    return await this.fetch<CloudflareQueueConsumer[]>(
+    return await this.paginate<CloudflareQueueConsumer>(
       `/accounts/${accountId}/queues/${queueId}/consumers`,
-      { schema: t.array(cloudflareQueueConsumerSchema) },
+      cloudflareQueueConsumerSchema,
     );
   }
 
@@ -264,8 +294,13 @@ export class CloudflareApi {
     consumerService: string,
   ): Promise<void> {
     const accountId = await this.resolveAccountId();
+    const consumers = await this.listQueueConsumers(queueId);
+    const consumer = consumers.find((c) => c.service === consumerService);
+    if (!consumer) {
+      return;
+    }
     await this.fetch(
-      `/accounts/${accountId}/queues/${queueId}/consumers/${consumerService}`,
+      `/accounts/${accountId}/queues/${queueId}/consumers/${consumer.consumer_id}`,
       { method: "DELETE" },
     );
   }
@@ -276,9 +311,9 @@ export class CloudflareApi {
 
   public async listHyperdrive(): Promise<CloudflareHyperdrive[]> {
     const accountId = await this.resolveAccountId();
-    return await this.fetch<CloudflareHyperdrive[]>(
+    return await this.paginate<CloudflareHyperdrive>(
       `/accounts/${accountId}/hyperdrive/configs`,
-      { schema: t.array(cloudflareHyperdriveSchema) },
+      cloudflareHyperdriveSchema,
     );
   }
 
@@ -338,20 +373,22 @@ export class CloudflareApi {
     scriptName: string,
   ): Promise<CloudflareDeployment[]> {
     const accountId = await this.resolveAccountId();
+    // Deployments list is wrapped in `{ deployments }` and returns newest
+    // first; for picking the active deployment we only need the top page.
     const res = await this.fetch<{ deployments: CloudflareDeployment[] }>(
       `/accounts/${accountId}/workers/scripts/${scriptName}/deployments`,
-      { schema: cloudflareDeploymentListSchema },
+      { schema: cloudflareDeploymentListSchema, query: { per_page: "100" } },
     );
     return res.deployments;
   }
 
   public async listVersions(scriptName: string): Promise<CloudflareVersion[]> {
     const accountId = await this.resolveAccountId();
-    const res = await this.fetch<{ items: CloudflareVersion[] }>(
+    return await this.paginateCursor<CloudflareVersion>(
       `/accounts/${accountId}/workers/scripts/${scriptName}/versions`,
-      { schema: cloudflareVersionListSchema },
+      "items",
+      cloudflareVersionSchema,
     );
-    return res.items;
   }
 
   // -------------------------------------------------------------------------
@@ -428,6 +465,13 @@ export class CloudflareApi {
       success: boolean;
       result: T;
       errors: CloudflareApiError[];
+      result_info?: {
+        page: number;
+        per_page: number;
+        total_pages?: number;
+        count?: number;
+        total_count?: number;
+      };
     };
 
     if (!json.success) {
@@ -444,6 +488,101 @@ export class CloudflareApi {
     return json.result;
   }
 
+  /**
+   * Paginate a page-based list endpoint (`result_info.total_pages`).
+   *
+   * Cloudflare defaults to `per_page=20`; we push it to 1000 (max on most
+   * list endpoints) and loop if more pages exist. Each page is validated
+   * against the item schema.
+   */
+  protected async paginate<T>(
+    path: string,
+    itemSchema: TSchema,
+    perPage = 1000,
+  ): Promise<T[]> {
+    const results: T[] = [];
+    let page = 1;
+
+    while (true) {
+      const token = await this.resolveToken();
+      const url = `${CloudflareApi.BASE}${path}?per_page=${perPage}&page=${page}`;
+
+      const headers: Record<string, string> = {
+        Authorization: `Bearer ${token}`,
+      };
+      if (this.jurisdiction && /\/r2\//.test(path)) {
+        headers["cf-r2-jurisdiction"] = this.jurisdiction;
+      }
+
+      const response = await globalThis.fetch(url, { method: "GET", headers });
+      const json = (await response.json()) as {
+        success: boolean;
+        result: T[];
+        errors: CloudflareApiError[];
+        result_info?: { page: number; total_pages?: number };
+      };
+
+      if (!json.success) {
+        const messages = json.errors.map((e) => e.message).join(", ");
+        throw new AlephaError(
+          `Cloudflare API error (GET ${path}): ${messages}`,
+        );
+      }
+
+      const validated = this.alepha.codec.validate(
+        t.array(itemSchema),
+        json.result,
+      ) as T[];
+      results.push(...validated);
+
+      const totalPages = json.result_info?.total_pages;
+      if (!totalPages || page >= totalPages || validated.length === 0) {
+        break;
+      }
+      page++;
+    }
+
+    return results;
+  }
+
+  /**
+   * Paginate a cursor-based list endpoint where `result` is an object
+   * containing both the items array and a `cursor` field (R2 buckets,
+   * Workers versions). Returns the flattened item array.
+   */
+  protected async paginateCursor<T>(
+    path: string,
+    itemsKey: string,
+    itemSchema: TSchema,
+    perPage = 1000,
+  ): Promise<T[]> {
+    const results: T[] = [];
+    let cursor: string | undefined;
+
+    while (true) {
+      const query: Record<string, string> = { per_page: String(perPage) };
+      if (cursor) {
+        query.cursor = cursor;
+      }
+
+      const res = await this.fetch<Record<string, unknown>>(path, { query });
+      const items = (res[itemsKey] as unknown[]) ?? [];
+      const validated = this.alepha.codec.validate(
+        t.array(itemSchema),
+        items,
+      ) as T[];
+      results.push(...validated);
+
+      const nextCursor = res.cursor as string | undefined;
+      if (!nextCursor || validated.length === 0) {
+        break;
+      }
+      cursor = nextCursor;
+    }
+
+    return results;
+  }
+
   // -------------------------------------------------------------------------
   // Helpers
   // -------------------------------------------------------------------------

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

@@ -124,21 +124,4 @@ export class WranglerApi {
       { resolve: true, env: { CI: "1" } },
     );
   }
-
-  // -------------------------------------------------------------------------
-  // Secrets
-  // -------------------------------------------------------------------------
-
-  /**
-   * Push secrets in bulk to a worker.
-   */
-  public async secretBulk(
-    secretsPath: string,
-    workerName: string,
-  ): Promise<void> {
-    await this.runShell(
-      `wrangler secret bulk ${secretsPath} --name=${workerName}`,
-      { resolve: true },
-    );
-  }
 }

package/src/core/Alepha.ts

@@ -826,6 +826,15 @@ export class Alepha {
     return this;
   }
 
+  /**
+   * Alias for {@link Alepha#with}.
+   */
+  public register<T extends object>(
+    serviceEntry: ServiceEntry<T> | { default: ServiceEntry<T> },
+  ): this {
+    return this.with(serviceEntry);
+  }
+
   /**
    * Get an instance of the specified service from the container.
    *

package/src/react/form/index.ts

@@ -9,6 +9,8 @@ export * from "./hooks/useForm.ts";
 export * from "./hooks/useFormState.ts";
 export * from "./hooks/useFormValues.ts";
 export * from "./services/FormModel.ts";
+export * from "./services/parseField.ts";
+export * from "./services/prettyName.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/react/form/services/parseField.ts

@@ -0,0 +1,163 @@
+import { type TSchema, TypeBoxError } from "alepha";
+import type { BaseInputField } from "./FormModel.ts";
+import { prettyName } from "./prettyName.ts";
+
+/**
+ * Semantic icon hint derived from schema metadata. UI layers map this
+ * to their own icon set — this module is headless and ships no JSX.
+ */
+export type IconHint =
+  | "email"
+  | "password"
+  | "phone"
+  | "url"
+  | "number"
+  | "calendar"
+  | "clock"
+  | "list"
+  | "text"
+  | "user"
+  | "file"
+  | "switch";
+
+export interface FieldConstraints {
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  pattern?: string;
+}
+
+export interface FieldMeta {
+  id?: string;
+  label: string;
+  description?: string;
+  error?: string;
+  required: boolean;
+  type?: string;
+  format?: string;
+  isEnum: boolean;
+  isArray: boolean;
+  isObject: boolean;
+  isArrayOfObjects: boolean;
+  enum?: readonly unknown[];
+  iconHint?: IconHint;
+  constraints: FieldConstraints;
+  testId?: string;
+  schema: TSchema;
+}
+
+export interface ParseFieldOptions {
+  label?: string;
+  description?: string;
+  error?: Error;
+}
+
+/**
+ * Derives a {@link FieldMeta} from an `InputField` (from `useForm`) plus
+ * optional overrides. Pure — no React, no JSX, no UI library coupling.
+ *
+ * UI components consume this metadata to render labels, descriptions,
+ * error messages, icons, and validation constraints.
+ */
+export const parseField = (
+  input: BaseInputField,
+  options: ParseFieldOptions = {},
+): FieldMeta => {
+  const schema = input.schema as TSchema & {
+    type?: string;
+    format?: string;
+    title?: string;
+    description?: string;
+    enum?: readonly unknown[];
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    properties?: unknown;
+    items?: { properties?: unknown };
+  };
+
+  const label =
+    options.label ??
+    (typeof schema.title === "string" ? schema.title : undefined) ??
+    prettyName(input.path);
+
+  const description =
+    options.description ??
+    (typeof schema.description === "string" ? schema.description : undefined);
+
+  const error =
+    options.error instanceof TypeBoxError
+      ? (options.error as TypeBoxError).value?.message
+      : undefined;
+
+  const type = schema.type;
+  const format = typeof schema.format === "string" ? schema.format : undefined;
+  const isEnum = Array.isArray(schema.enum);
+  const isArray = type === "array";
+  const isObject = type === "object" && Boolean(schema.properties);
+  const isArrayOfObjects =
+    isArray && Boolean(schema.items && (schema.items as any).properties);
+
+  const name = input.props.name;
+  const iconHint = inferIconHint({ type, format, name, isEnum, isArray });
+
+  const constraints: FieldConstraints = {};
+  if (typeof schema.minLength === "number")
+    constraints.minLength = schema.minLength;
+  if (typeof schema.maxLength === "number")
+    constraints.maxLength = schema.maxLength;
+  if (typeof schema.minimum === "number") constraints.minimum = schema.minimum;
+  if (typeof schema.maximum === "number") constraints.maximum = schema.maximum;
+  if (typeof schema.pattern === "string") constraints.pattern = schema.pattern;
+
+  return {
+    id: input.props.id,
+    label,
+    description,
+    error,
+    required: input.required,
+    type,
+    format,
+    isEnum,
+    isArray,
+    isObject,
+    isArrayOfObjects,
+    enum: schema.enum,
+    iconHint,
+    constraints,
+    testId: (input.props as Record<string, unknown>)["data-testid"] as
+      | string
+      | undefined,
+    schema: input.schema,
+  };
+};
+
+const inferIconHint = (params: {
+  type?: string;
+  format?: string;
+  name?: string;
+  isEnum: boolean;
+  isArray: boolean;
+}): IconHint | undefined => {
+  const { type, format, name, isEnum, isArray } = params;
+
+  if (format === "email") return "email";
+  if (format === "url" || format === "uri") return "url";
+  if (format === "tel" || format === "phone") return "phone";
+  if (format === "date" || format === "date-time") return "calendar";
+  if (format === "time") return "clock";
+
+  if (name?.toLowerCase().includes("password")) return "password";
+  if (name?.toLowerCase().includes("email")) return "email";
+  if (name?.toLowerCase().includes("phone")) return "phone";
+
+  if (type === "boolean") return "switch";
+  if (type === "number" || type === "integer") return "number";
+  if (isEnum || isArray) return "list";
+  if (type === "string") return "text";
+
+  return undefined;
+};

package/src/react/form/services/prettyName.ts

@@ -0,0 +1,19 @@
+/**
+ * Converts a path or identifier string into a pretty display name.
+ * For paths like "/contacts/0/name", extracts just the field name "Name".
+ * Handles camelCase and snake_case conversion to Title Case.
+ *
+ * @example
+ * prettyName("/userName") // "User Name"
+ * prettyName("/contacts/0/email") // "Email"
+ * prettyName("/address/streetName") // "Street Name"
+ * prettyName("first_name") // "First Name"
+ */
+export const prettyName = (name: string): string => {
+  const segments = name.split("/").filter((s) => s && !/^\d+$/.test(s));
+  const fieldName = segments[segments.length - 1] || name.replaceAll("/", "");
+  return fieldName
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+};

package/src/react/head/providers/BrowserHeadProvider.ts

@@ -154,10 +154,12 @@ export class BrowserHeadProvider {
       | string
       | (Record<string, string | boolean | undefined> & { content?: string }),
   ): void {
-    const el = document.createElement("script");
-
-    // Handle plain string as inline script
+    // Plain string → inline script. Dedupe by exact content match against
+    // any existing inline script (handles SSR-emitted globals that would
+    // otherwise be re-appended on hydration).
     if (typeof script === "string") {
+      if (this.findInlineScriptByContent(document, script)) return;
+      const el = document.createElement("script");
       el.textContent = script;
       document.head.appendChild(el);
       return;
@@ -165,14 +167,18 @@ export class BrowserHeadProvider {
 
     const { content, ...attrs } = script;
 
-    // For scripts with src, check if already exists
+    // src-based scripts: dedupe by src attribute (existing behaviour).
     if (attrs.src) {
-      const existing = document.querySelector(`script[src="${attrs.src}"]`);
-      if (existing) {
-        return;
-      }
+      if (document.querySelector(`script[src="${attrs.src}"]`)) return;
+    } else if (typeof attrs.id === "string") {
+      // id-based dedupe — single source of truth per id.
+      if (document.querySelector(`script#${CSS.escape(attrs.id)}`)) return;
+    } else if (content) {
+      // Inline scripts with `content` and no src/id: fall back to content match.
+      if (this.findInlineScriptByContent(document, content)) return;
     }
 
+    const el = document.createElement("script");
     for (const [key, value] of Object.entries(attrs)) {
       if (value === true) {
         el.setAttribute(key, "");
@@ -180,14 +186,29 @@ export class BrowserHeadProvider {
         el.setAttribute(key, String(value));
       }
     }
-
     if (content) {
       el.textContent = content;
     }
-
     document.head.appendChild(el);
   }
 
+  /**
+   * Find an existing inline `<script>` tag (no `src`) with matching textContent.
+   * Used to make `renderScriptTag` idempotent across hydration + navigation,
+   * so SSR-emitted global scripts aren't re-appended client-side.
+   */
+  protected findInlineScriptByContent(
+    document: Document,
+    content: string,
+  ): Element | null {
+    for (const existing of document.head.querySelectorAll(
+      "script:not([src])",
+    )) {
+      if (existing.textContent === content) return existing;
+    }
+    return null;
+  }
+
   protected renderMetaTag(document: Document, meta: HeadMeta): void {
     const { content } = meta;
 

package/src/react/router/primitives/$page.ts

@@ -50,16 +50,6 @@ import { ReactPageService } from "../services/ReactPageService.ts";
  * - Hierarchical error handling (child → parent)
  * - HTTP status code handling (404, 401, etc.)
  *
- * **Page Animations**
- * - CSS-based enter/exit animations
- * - Dynamic animations based on page state
- * - Custom timing and easing functions
- *
- * **Lifecycle Management**
- * - Server response hooks for headers and status codes
- * - Page leave handlers for cleanup (browser only)
- * - Permission-based access control
- *
  * @example Simple page with data fetching
  * ```typescript
  * const userProfile = $page({
@@ -202,13 +192,46 @@ export interface PagePrimitiveOptions<
   lazy?: () => Promise<{ default: FC<TProps & TPropsParent> }>;
 
   /**
-   * Attach child pages to create nested routes.
-   * This will make the page a parent route.
+   * Attach child pages to create nested routes, adopting them as children of
+   * this page.
+   *
+   * Use this when you want a parent to own children it cannot modify — most
+   * notably pages that come from an injected router in another package, whose
+   * `$page` definitions are frozen and cannot declare `parent` themselves.
+   *
+   * ```ts
+   * layout = $page({
+   *   path: "/app",
+   *   children: () => [
+   *     this.productRouter.catalogPage,  // from $inject(ProductRouter)
+   *     this.productRouter.checkoutPage,
+   *   ],
+   * });
+   * ```
+   *
+   * Use a thunk (`() => [...]`) when the children are defined later in the
+   * same class.
+   *
+   * **Declare each edge from one side only.** If a child already sets
+   * `parent: thisPage`, do NOT also add it to `children` — the link is
+   * already established, and declaring it on both sides creates a TypeScript
+   * circular dependency between the two class fields (each references the
+   * other before it is initialised).
    */
   children?: Array<PagePrimitive> | (() => Array<PagePrimitive>);
 
   /**
    * Define a parent page for nested routing.
+   *
+   * Use this when you own the child page and can edit its definition — it is
+   * the simplest way to nest routes and reads top-down. For pages you do NOT
+   * own (e.g. pages exposed by an injected router from another package), let
+   * the parent adopt them via its `children` option instead.
+   *
+   * **Declare each edge from one side only.** If you set `parent` here, do
+   * NOT also add this page to the parent's `children` array — the link is
+   * already established, and declaring it on both sides creates a TypeScript
+   * circular dependency between the two class fields.
    */
   parent?: PagePrimitive<PageConfigSchema, TPropsParent, any>;