alepha 0.20.3 → 0.20.4

package/src/bucket/providers/CloudflareR2Provider.ts

@@ -1,3 +1,4 @@
+import type { R2Bucket } from "@cloudflare/workers-types";
 import {
   $env,
   $hook,
@@ -14,142 +15,6 @@ import type { FileStorageProvider } from "./FileStorageProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-/**
- * R2Bucket interface matching Cloudflare's R2 API.
- */
-export interface R2Bucket {
-  put(
-    key: string,
-    value:
-      | ReadableStream
-      | ArrayBuffer
-      | ArrayBufferView
-      | string
-      | Blob
-      | null,
-    options?: R2PutOptions,
-  ): Promise<R2Object | null>;
-  get(key: string, options?: R2GetOptions): Promise<R2ObjectBody | null>;
-  head(key: string): Promise<R2Object | null>;
-  delete(keys: string | string[]): Promise<void>;
-  list(options?: R2ListOptions): Promise<R2Objects>;
-  createMultipartUpload(
-    key: string,
-    options?: R2MultipartOptions,
-  ): Promise<R2MultipartUpload>;
-}
-
-export interface R2Object {
-  key: string;
-  version: string;
-  size: number;
-  etag: string;
-  httpEtag: string;
-  checksums: R2Checksums;
-  uploaded: Date;
-  httpMetadata?: R2HTTPMetadata;
-  customMetadata?: Record<string, string>;
-  range?: R2Range;
-  storageClass: string;
-}
-
-export interface R2ObjectBody extends R2Object {
-  body: ReadableStream;
-  bodyUsed: boolean;
-  arrayBuffer(): Promise<ArrayBuffer>;
-  text(): Promise<string>;
-  json<T>(): Promise<T>;
-  blob(): Promise<Blob>;
-}
-
-export interface R2PutOptions {
-  onlyIf?: R2Conditional;
-  httpMetadata?: R2HTTPMetadata;
-  customMetadata?: Record<string, string>;
-  md5?: ArrayBuffer | string;
-  sha1?: ArrayBuffer | string;
-  sha256?: ArrayBuffer | string;
-  sha384?: ArrayBuffer | string;
-  sha512?: ArrayBuffer | string;
-  storageClass?: string;
-}
-
-export interface R2GetOptions {
-  onlyIf?: R2Conditional;
-  range?: R2Range;
-}
-
-export interface R2ListOptions {
-  limit?: number;
-  prefix?: string;
-  cursor?: string;
-  delimiter?: string;
-  startAfter?: string;
-  include?: ("httpMetadata" | "customMetadata")[];
-}
-
-export interface R2Objects {
-  objects: R2Object[];
-  truncated: boolean;
-  cursor?: string;
-  delimitedPrefixes: string[];
-}
-
-export interface R2Checksums {
-  md5?: ArrayBuffer;
-  sha1?: ArrayBuffer;
-  sha256?: ArrayBuffer;
-  sha384?: ArrayBuffer;
-  sha512?: ArrayBuffer;
-}
-
-export interface R2HTTPMetadata {
-  contentType?: string;
-  contentLanguage?: string;
-  contentDisposition?: string;
-  contentEncoding?: string;
-  cacheControl?: string;
-  cacheExpiry?: Date;
-}
-
-export interface R2Conditional {
-  etagMatches?: string;
-  etagDoesNotMatch?: string;
-  uploadedBefore?: Date;
-  uploadedAfter?: Date;
-  secondsGranularity?: boolean;
-}
-
-export interface R2Range {
-  offset?: number;
-  length?: number;
-  suffix?: number;
-}
-
-export interface R2MultipartOptions {
-  httpMetadata?: R2HTTPMetadata;
-  customMetadata?: Record<string, string>;
-  storageClass?: string;
-}
-
-export interface R2MultipartUpload {
-  key: string;
-  uploadId: string;
-  uploadPart(
-    partNumber: number,
-    value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob,
-  ): Promise<R2UploadedPart>;
-  abort(): Promise<void>;
-  complete(uploadedParts: R2UploadedPart[]): Promise<R2Object>;
-}
-
-export interface R2UploadedPart {
-  partNumber: number;
-  etag: string;
-}
-
-// ---------------------------------------------------------------------------------------------------------------------
-
 /**
  * Cloudflare R2 storage provider.
  *
@@ -311,7 +176,7 @@ export class CloudflareR2Provider implements FileStorageProvider {
       type: contentType,
       size: object.size,
       lastModified: object.uploaded.getTime(),
-      stream: () => object.body,
+      stream: () => object.body as unknown as ReadableStream,
       arrayBuffer: () => object.arrayBuffer(),
       text: () => object.text(),
     };

package/src/bucket/providers/NodeS3BucketProvider.ts

@@ -0,0 +1,218 @@
+import { Buffer } from "node:buffer";
+import {
+  $env,
+  $hook,
+  $inject,
+  Alepha,
+  AlephaError,
+  type FileLike,
+  type Static,
+  t,
+} from "alepha";
+import { $logger } from "alepha/logger";
+import { FileDetector, FileSystemProvider } from "alepha/system";
+import { S3mini } from "s3mini";
+import { FileNotFoundError } from "../errors/FileNotFoundError.ts";
+import { $bucket } from "../primitives/$bucket.ts";
+import type { FileStorageProvider } from "./FileStorageProvider.ts";
+
+const envSchema = t.object({
+  /**
+   * S3 endpoint URL. The bucket name is appended (path-style) per request.
+   *
+   * Examples:
+   * - AWS S3: `https://s3.us-east-1.amazonaws.com`
+   * - Cloudflare R2: `https://<account-id>.r2.cloudflarestorage.com`
+   * - MinIO: `http://localhost:9000`
+   * - DigitalOcean Spaces: `https://<region>.digitaloceanspaces.com`
+   */
+  S3_ENDPOINT: t.string(),
+
+  /**
+   * AWS region or "auto" for R2.
+   *
+   * @default "auto"
+   */
+  S3_REGION: t.optional(t.string()),
+
+  /**
+   * Access key ID for S3 authentication.
+   */
+  S3_ACCESS_KEY_ID: t.string(),
+
+  /**
+   * Secret access key for S3 authentication.
+   */
+  S3_SECRET_ACCESS_KEY: t.string(),
+});
+
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof envSchema>> {}
+}
+
+/**
+ * S3-compatible file storage provider for Node.js.
+ *
+ * Backed by `s3mini` (zero-dep, ~20 KB). Works with AWS S3, Cloudflare R2,
+ * MinIO, DigitalOcean Spaces, Backblaze B2, and any other S3-compatible service.
+ *
+ * Uses path-style addressing (`<endpoint>/<bucket>`).
+ */
+export class NodeS3BucketProvider implements FileStorageProvider {
+  protected readonly log = $logger();
+  protected readonly env = $env(envSchema);
+  protected readonly alepha = $inject(Alepha);
+  protected readonly fileSystem = $inject(FileSystemProvider);
+  protected readonly fileDetector = $inject(FileDetector);
+  protected readonly clients: Map<string, S3mini> = new Map();
+
+  /**
+   * Convert bucket name to S3-compatible format.
+   * S3 bucket names must be lowercase, 3-63 characters, no underscores.
+   */
+  public convertName(name: string): string {
+    return name.replaceAll("/", "-").replaceAll("_", "-").toLowerCase();
+  }
+
+  protected getClient(bucketName: string): S3mini {
+    const name = this.convertName(bucketName);
+    let client = this.clients.get(name);
+    if (!client) {
+      const endpoint = this.env.S3_ENDPOINT.replace(/\/+$/, "");
+      client = new S3mini({
+        accessKeyId: this.env.S3_ACCESS_KEY_ID,
+        secretAccessKey: this.env.S3_SECRET_ACCESS_KEY,
+        region: this.env.S3_REGION || "auto",
+        endpoint: `${endpoint}/${name}`,
+      });
+      this.clients.set(name, client);
+    }
+    return client;
+  }
+
+  protected readonly onStart = $hook({
+    on: "start",
+    handler: async () => {
+      for (const bucket of this.alepha.primitives($bucket)) {
+        if (bucket.provider !== this) {
+          continue;
+        }
+
+        const name = this.convertName(bucket.name);
+        const client = this.getClient(bucket.name);
+
+        this.log.debug(`Preparing S3 bucket '${name}'...`);
+
+        const exists = await client.bucketExists();
+        if (!exists) {
+          this.log.debug(`Creating S3 bucket '${name}'...`);
+          const created = await client.createBucket();
+          if (!created) {
+            throw new AlephaError(`Failed to create S3 bucket '${name}'`);
+          }
+        }
+
+        this.log.info(`S3 bucket '${bucket.name}' OK`);
+      }
+    },
+  });
+
+  protected createId(mimeType: string): string {
+    const ext = this.fileDetector.getExtensionFromMimeType(mimeType);
+    return `${crypto.randomUUID()}.${ext}`;
+  }
+
+  public async upload(
+    bucketName: string,
+    file: FileLike,
+    fileId?: string,
+  ): Promise<string> {
+    fileId ??= this.createId(file.type);
+
+    this.log.trace(
+      `Uploading file '${file.name}' to bucket '${bucketName}' with id '${fileId}'...`,
+    );
+
+    const client = this.getClient(bucketName);
+
+    try {
+      const buffer = new Uint8Array(await file.arrayBuffer());
+      await client.putObject(
+        fileId,
+        buffer,
+        file.type || "application/octet-stream",
+        undefined,
+        { "x-amz-meta-name": encodeURIComponent(file.name) },
+        file.size,
+      );
+
+      this.log.trace(`File uploaded successfully: ${fileId}`);
+      return fileId;
+    } catch (error) {
+      this.log.error(`Failed to upload file: ${error}`);
+      if (error instanceof Error) {
+        throw new AlephaError(`Upload failed: ${error.message}`, {
+          cause: error,
+        });
+      }
+      throw error;
+    }
+  }
+
+  public async download(bucketName: string, fileId: string): Promise<FileLike> {
+    this.log.trace(
+      `Downloading file '${fileId}' from bucket '${bucketName}'...`,
+    );
+
+    const client = this.getClient(bucketName);
+    const response = await client.getObjectResponse(fileId);
+
+    if (!response) {
+      throw new FileNotFoundError(
+        `File '${fileId}' not found in bucket '${bucketName}'`,
+      );
+    }
+
+    const buffer = Buffer.from(await response.arrayBuffer());
+
+    const mimeType =
+      response.headers.get("content-type") ||
+      this.fileDetector.getContentType(fileId);
+
+    const metaName = response.headers.get("x-amz-meta-name");
+    const name = metaName ? decodeURIComponent(metaName) : fileId;
+
+    return this.fileSystem.createFile({
+      buffer,
+      name,
+      type: mimeType,
+      size: buffer.length,
+    });
+  }
+
+  public async exists(bucketName: string, fileId: string): Promise<boolean> {
+    this.log.trace(
+      `Checking existence of file '${fileId}' in bucket '${bucketName}'...`,
+    );
+
+    const client = this.getClient(bucketName);
+    const result = await client.objectExists(fileId);
+    return result === true;
+  }
+
+  public async delete(bucketName: string, fileId: string): Promise<void> {
+    this.log.trace(`Deleting file '${fileId}' from bucket '${bucketName}'...`);
+
+    const client = this.getClient(bucketName);
+
+    try {
+      await client.deleteObject(fileId);
+    } catch (error) {
+      this.log.error(`Failed to delete file: ${error}`);
+      if (error instanceof Error) {
+        throw new FileNotFoundError("Error deleting file", { cause: error });
+      }
+      throw error;
+    }
+  }
+}

package/src/cache/core/index.ts

@@ -12,6 +12,35 @@ export * from "./providers/MemoryCacheProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+declare module "alepha" {
+  interface Hooks {
+    /**
+     * Fires when a cache lookup finds a value.
+     */
+    "cache:hit": {
+      container: string;
+      key: string;
+    };
+    /**
+     * Fires when a cache lookup does not find a value.
+     */
+    "cache:miss": {
+      container: string;
+      key: string;
+    };
+    /**
+     * Fires when a value is written to the cache.
+     */
+    "cache:set": {
+      container: string;
+      key: string;
+      ttlMs?: number;
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
 /**
  * Type-safe caching with TTL support.
  *

package/src/cache/core/primitives/$cache.ts

@@ -239,6 +239,12 @@ export class CachePrimitive<
       ttl: px > 0 ? px : undefined,
       compress: this.options.compress,
     });
+
+    await this.alepha.events.emit("cache:set", {
+      container: this.container,
+      key,
+      ttlMs: px > 0 ? px : undefined,
+    });
   }
 
   public async get(key: string): Promise<TReturn | undefined> {
@@ -250,7 +256,14 @@ export class CachePrimitive<
       return undefined;
     }
 
-    return this.provider.getTyped<TReturn>(this.container, key);
+    const value = await this.provider.getTyped<TReturn>(this.container, key);
+
+    await this.alepha.events.emit(
+      value === undefined ? "cache:miss" : "cache:hit",
+      { container: this.container, key },
+    );
+
+    return value;
   }
 
   protected $provider(): CacheProvider {

package/src/cli/config/defineConfig.ts

@@ -1,4 +1,4 @@
-import type { Alepha } from "alepha";
+import type { Alepha, Service } from "alepha";
 import {
   type AppEntryOptions,
   appEntryOptions,
@@ -10,15 +10,6 @@ import {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export type AlephaCliConfigPlugin = (
-  config: AlephaCliConfig,
-  alepha: Alepha,
-) => void;
-
-export const cliConfigPlugins: AlephaCliConfigPlugin[] = [];
-
-// ---------------------------------------------------------------------------------------------------------------------
-
 export interface AlephaCliConfig {
   /**
    * Override entry paths.
@@ -28,7 +19,12 @@ export interface AlephaCliConfig {
   /**
    * Register more services to the Alepha CLI (enhancements, commands, etc.).
    */
-  services?: Array<any>;
+  services?: Array<Service>;
+
+  /**
+   * @alias services Register more services to the Alepha CLI (enhancements, commands, etc.).
+   */
+  plugins?: Array<Service>;
 
   /**
    * Configure Alepha build command.
@@ -58,6 +54,12 @@ export const defineConfig = (config: AlephaCliConfig) => {
       }
     }
 
+    if (config.plugins) {
+      for (const it of config.plugins) {
+        alepha.with(it);
+      }
+    }
+
     if (config.env) {
       for (const [key, value] of Object.entries(config.env)) {
         process.env[key] = String(value);
@@ -76,10 +78,6 @@ export const defineConfig = (config: AlephaCliConfig) => {
       alepha.set(appEntryOptions, config.entry);
     }
 
-    for (const plugin of cliConfigPlugins) {
-      plugin(config, alepha);
-    }
-
     return {};
   };
 };

package/src/cli/core/__tests__/init.spec.ts

@@ -98,25 +98,24 @@ describe("alepha init", () => {
   // ─────────────────────────────────────────────────────────────────────────────
 
   describe("AI agent files", () => {
-    it("should create CLAUDE.md when claude CLI is installed", async () => {
-      const { fs, shell, cli, cmd, json } = createTestEnv();
+    it("should create both AGENTS.md and CLAUDE.md", async () => {
+      const { fs, cli, cmd, json } = createTestEnv();
       await setupProject(fs, json);
-      shell.installedCommands.add("claude");
 
       await cli.run(cmd.init, { root: "/project" });
 
+      expect(fs.wasWritten("/project/AGENTS.md")).toBe(true);
       expect(fs.wasWritten("/project/CLAUDE.md")).toBe(true);
-      expect(fs.wasWritten("/project/AGENTS.md")).toBe(false);
     });
 
-    it("should create AGENTS.md when claude CLI is not installed", async () => {
+    it("should write CLAUDE.md as a stub importing AGENTS.md", async () => {
       const { fs, cli, cmd, json } = createTestEnv();
       await setupProject(fs, json);
 
       await cli.run(cmd.init, { root: "/project" });
 
-      expect(fs.wasWritten("/project/AGENTS.md")).toBe(true);
-      expect(fs.wasWritten("/project/CLAUDE.md")).toBe(false);
+      const claude = await fs.readTextFile("/project/CLAUDE.md");
+      expect(claude.trim()).toBe("@AGENTS.md");
     });
 
     it("should include Alepha instructions in agent file", async () => {

package/src/cli/core/services/ProjectScaffolder.ts

@@ -3,7 +3,7 @@ import { $inject, AlephaError } from "alepha";
 import type { RunnerMethod } from "alepha/command";
 import { $logger, ConsoleColorProvider } from "alepha/logger";
 import { FileSystemProvider, ShellProvider } from "alepha/system";
-import { type AgentMdOptions, agentMd } from "../templates/agentMd.ts";
+import { agentMd } from "../templates/agentMd.ts";
 import { alephaConfigTs } from "../templates/alephaConfigTs.ts";
 import { apiHelloControllerTs } from "../templates/apiHelloControllerTs.ts";
 import { apiHelloResponseSchemaTs } from "../templates/apiHelloResponseSchemaTs.ts";
@@ -94,7 +94,7 @@ export class ProjectScaffolder {
       tsconfigJson?: boolean | "local";
       biomeJson?: boolean;
       editorconfig?: boolean;
-      agentMd?: false | AgentMdOptions;
+      agentMd?: boolean;
     },
   ): Promise<void> {
     const tasks: Promise<void>[] = [];
@@ -126,7 +126,7 @@ export class ProjectScaffolder {
       tasks.push(this.ensureEditorConfig(root, { force, checkWorkspace }));
     }
     if (opts.agentMd) {
-      tasks.push(this.ensureAgentMd(root, { ...opts.agentMd, force }));
+      tasks.push(this.ensureAgentMd(root, { force }));
     }
 
     await Promise.all(tasks);
@@ -214,12 +214,19 @@ export class ProjectScaffolder {
     return true;
   }
 
+  /**
+   * Ensure AGENTS.md (cross-tool standard, canonical source) exists, with a
+   * CLAUDE.md stub that imports it via Claude Code's `@` syntax. Single
+   * source of truth, cross-platform, no symlink needed.
+   */
   public async ensureAgentMd(
     root: string,
-    options: AgentMdOptions & { force?: boolean },
+    options: { force?: boolean } = {},
   ): Promise<void> {
-    const filename = options.type === "claude" ? "CLAUDE.md" : "AGENTS.md";
-    await this.ensureFile(root, filename, agentMd(options), options.force);
+    await Promise.all([
+      this.ensureFile(root, "AGENTS.md", agentMd(), options.force),
+      this.ensureFile(root, "CLAUDE.md", "@AGENTS.md\n", options.force),
+    ]);
   }
 
   /**
@@ -602,12 +609,9 @@ export class ProjectScaffolder {
     // Detect workspace context (are we inside packages/ or apps/ of a monorepo?)
     const workspace = await this.pm.getWorkspaceContext(root);
 
-    // Detect agent type: claude CLI → CLAUDE.md, else → AGENTS.md
-    let agentType: "claude" | "agents" | false = false;
-    if (!workspace.isPackage) {
-      const hasClaudeCli = await this.utils.isInstalledAsync("claude");
-      agentType = hasClaudeCli ? "claude" : "agents";
-    }
+    // Always emit both AGENTS.md and CLAUDE.md at project roots (skip for
+    // monorepo sub-packages where agent files live at workspace root).
+    const writeAgentMd = !workspace.isPackage;
 
     const isExpo = await this.pm.hasExpo(root);
 
@@ -626,7 +630,7 @@ export class ProjectScaffolder {
           tsconfigJson: f.shadcn ? "local" : !workspace.config.tsconfigJson,
           biomeJson: true,
           editorconfig: !workspace.config.editorconfig,
-          agentMd: agentType ? { type: agentType } : false,
+          agentMd: writeAgentMd,
         });
 
         // Create alepha.config.ts with documented options
@@ -729,7 +733,7 @@ export class ProjectScaffolder {
     // pulls its peer primitives + dependencies (sonner, etc.).
     if (flags.saas) {
       // Pull the public SaaS bundle in one shot — it aggregates control,
-      // auto-form, alepha-table, use-confirm, app-shell, every auth-*, and
+      // auto-form, alepha-table, use-dialog, app-shell, every auth-*, and
       // every admin-* block. Definition lives at
       // https://alepha.dev/r/saas.json (see @alepha/ui-registry).
       // `--yes --overwrite` is the only combo that works non-interactively

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

@@ -73,6 +73,11 @@ export class BuildCloudflareTask extends BuildTask {
       };
     }
 
+    wrangler.observability ??= {
+      enabled: true,
+      head_sampling_rate: 1,
+    };
+
     this.enhanceDomain(wrangler);
     this.enhanceCron(ctx, wrangler);
     this.enhanceDatabase(wrangler);

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

@@ -1,13 +1,5 @@
-export type AgentMdType = "claude" | "agents";
-
-export interface AgentMdOptions {
-  type: AgentMdType;
-}
-
-export const agentMd = (options: AgentMdOptions): string => {
-  const header = options.type === "claude" ? `# CLAUDE.md` : `# AGENTS.md`;
-
-  return `${header}
+export const agentMd = (): string => {
+  return `# AGENTS.md
 
 This is an **Alepha** project.
 

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

@@ -11,7 +11,7 @@ export const saasAdminLayoutTsx = () =>
   `import { AppShell } from "@/components/app-shell";
 import { Toaster } from "@/components/ui/sonner";
 import { TooltipProvider } from "@/components/ui/tooltip";
-import { ConfirmProvider } from "@/components/use-confirm";
+import { DialogProvider } from "@/components/use-dialog";
 import { NestedView, useRouterState } from "alepha/react/router";
 import { ShieldCheck, Users } from "lucide-react";
 
@@ -39,7 +39,7 @@ const AdminLayout = () => {
 
   return (
     <TooltipProvider>
-      <ConfirmProvider>
+      <DialogProvider>
         <AppShell
           brand={
             <a
@@ -68,7 +68,7 @@ const AdminLayout = () => {
           <NestedView />
         </AppShell>
         <Toaster />
-      </ConfirmProvider>
+      </DialogProvider>
     </TooltipProvider>
   );
 };