alepha 0.15.0 → 0.15.2

package/src/system/providers/MemoryShellProvider.ts

@@ -0,0 +1,164 @@
+import type { ShellProvider, ShellRunOptions } from "./ShellProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface MemoryShellCall {
+  command: string;
+  options: ShellRunOptions;
+}
+
+export interface MemoryShellProviderOptions {
+  /**
+   * Simulated outputs for specific commands.
+   * Key is the command string, value is the stdout to return.
+   */
+  outputs?: Record<string, string>;
+
+  /**
+   * Commands that should throw an error.
+   * Key is the command string, value is the error message.
+   */
+  errors?: Record<string, string>;
+
+  /**
+   * Commands that are considered "installed" in the system PATH.
+   */
+  installedCommands?: string[];
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * In-memory implementation of ShellProvider for testing.
+ *
+ * Records all commands that would be executed without actually running them.
+ * Can be configured to return specific outputs or throw errors for testing.
+ *
+ * @example
+ * ```typescript
+ * // In tests, substitute the real ShellProvider with MemoryShellProvider
+ * const alepha = Alepha.create().with({
+ *   provide: ShellProvider,
+ *   use: MemoryShellProvider,
+ * });
+ *
+ * // Configure mock behavior
+ * const shell = alepha.inject(MemoryShellProvider);
+ * shell.configure({
+ *   outputs: { "echo hello": "hello\n" },
+ *   errors: { "failing-cmd": "Command failed" },
+ * });
+ *
+ * // Or use the fluent API
+ * shell.outputs.set("another-cmd", "output");
+ * shell.errors.set("another-error", "Error message");
+ *
+ * // Run code that uses ShellProvider
+ * const service = alepha.inject(MyService);
+ * await service.doSomething();
+ *
+ * // Verify commands were called
+ * expect(shell.calls).toHaveLength(2);
+ * expect(shell.calls[0].command).toBe("yarn install");
+ * ```
+ */
+export class MemoryShellProvider implements ShellProvider {
+  /**
+   * All recorded shell calls.
+   */
+  public calls: MemoryShellCall[] = [];
+
+  /**
+   * Simulated outputs for specific commands.
+   */
+  public outputs = new Map<string, string>();
+
+  /**
+   * Commands that should throw an error.
+   */
+  public errors = new Map<string, string>();
+
+  /**
+   * Commands considered installed in the system PATH.
+   */
+  public installedCommands = new Set<string>();
+
+  /**
+   * Configure the mock with predefined outputs, errors, and installed commands.
+   */
+  public configure(options: MemoryShellProviderOptions): this {
+    if (options.outputs) {
+      for (const [cmd, output] of Object.entries(options.outputs)) {
+        this.outputs.set(cmd, output);
+      }
+    }
+    if (options.errors) {
+      for (const [cmd, error] of Object.entries(options.errors)) {
+        this.errors.set(cmd, error);
+      }
+    }
+    if (options.installedCommands) {
+      for (const cmd of options.installedCommands) {
+        this.installedCommands.add(cmd);
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Record command and return simulated output.
+   */
+  public async run(
+    command: string,
+    options: ShellRunOptions = {},
+  ): Promise<string> {
+    this.calls.push({ command, options });
+
+    // Check for configured error
+    const errorMsg = this.errors.get(command);
+    if (errorMsg) {
+      throw new Error(errorMsg);
+    }
+
+    // Return configured output or empty string
+    return this.outputs.get(command) ?? "";
+  }
+
+  /**
+   * Check if a specific command was called.
+   */
+  public wasCalled(command: string): boolean {
+    return this.calls.some((call) => call.command === command);
+  }
+
+  /**
+   * Check if a command matching a pattern was called.
+   */
+  public wasCalledMatching(pattern: RegExp): boolean {
+    return this.calls.some((call) => pattern.test(call.command));
+  }
+
+  /**
+   * Get all calls matching a pattern.
+   */
+  public getCallsMatching(pattern: RegExp): MemoryShellCall[] {
+    return this.calls.filter((call) => pattern.test(call.command));
+  }
+
+  /**
+   * Check if a command is installed.
+   */
+  public async isInstalled(command: string): Promise<boolean> {
+    return this.installedCommands.has(command);
+  }
+
+  /**
+   * Reset all recorded state.
+   */
+  public reset(): void {
+    this.calls = [];
+    this.outputs.clear();
+    this.errors.clear();
+    this.installedCommands.clear();
+  }
+}

package/src/{file → system}/providers/NodeFileSystemProvider.spec.ts

@@ -1,14 +1,14 @@
 import { Readable } from "node:stream";
 import { Alepha } from "alepha";
 import { beforeEach, describe, it } from "vitest";
-import { AlephaFile } from "../index.ts";
+import { AlephaSystem } from "../index.ts";
 import { NodeFileSystemProvider } from "../providers/NodeFileSystemProvider.ts";
 
 describe("NodeFileSystem", () => {
   let fs: NodeFileSystemProvider;
 
   beforeEach(() => {
-    const alepha = Alepha.create().with(AlephaFile);
+    const alepha = Alepha.create().with(AlephaSystem);
     fs = alepha.inject(NodeFileSystemProvider);
   });
 

package/src/{file → system}/providers/NodeFileSystemProvider.ts

@@ -20,6 +20,7 @@ import {
   AlephaError,
   type FileLike,
   isFileLike,
+  Json,
   type StreamLike,
 } from "alepha";
 import { FileDetector } from "../services/FileDetector.ts";
@@ -58,6 +59,7 @@ import type {
  */
 export class NodeFileSystemProvider implements FileSystemProvider {
   protected detector = $inject(FileDetector);
+  protected json = $inject(Json);
 
   public join(...paths: string[]): string {
     return join(...paths);
@@ -418,6 +420,40 @@ export class NodeFileSystemProvider implements FileSystemProvider {
     await fsWriteFile(path, data);
   }
 
+  /**
+   * Reads the content of a file as a string.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a string
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   * const content = await fs.readTextFile("/tmp/file.txt");
+   * ```
+   */
+  async readTextFile(path: string): Promise<string> {
+    const buffer = await this.readFile(path);
+    return buffer.toString("utf-8");
+  }
+
+  /**
+   * Reads the content of a file as JSON.
+   *
+   * @param path - The file path to read
+   * @returns The parsed JSON content
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   * const config = await fs.readJsonFile<{ name: string }>("/tmp/config.json");
+   * ```
+   */
+  async readJsonFile<T = unknown>(path: string): Promise<T> {
+    const text = await this.readTextFile(path);
+    return this.json.parse(text) as T;
+  }
+
   /**
    * Creates a FileLike object from a Web File.
    *

package/src/system/providers/NodeShellProvider.ts

@@ -0,0 +1,184 @@
+import { exec, spawn } from "node:child_process";
+import { $inject, AlephaError } from "alepha";
+import { $logger } from "alepha/logger";
+import { FileSystemProvider } from "./FileSystemProvider.ts";
+import type { ShellProvider, ShellRunOptions } from "./ShellProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Node.js implementation of ShellProvider.
+ *
+ * Executes shell commands using Node.js child_process module.
+ * Supports binary resolution from node_modules/.bin for local packages.
+ */
+export class NodeShellProvider implements ShellProvider {
+  protected readonly log = $logger();
+  protected readonly fs = $inject(FileSystemProvider);
+
+  /**
+   * Run a shell command or binary.
+   */
+  public async run(
+    command: string,
+    options: ShellRunOptions = {},
+  ): Promise<string> {
+    const { resolve = false, capture = false, root, env } = options;
+    const cwd = root ?? process.cwd();
+
+    this.log.debug(`Shell: ${command}`, { cwd, resolve, capture });
+
+    let executable: string;
+    let args: string[];
+
+    if (resolve) {
+      const [bin, ...rest] = command.split(" ");
+      executable = await this.resolveExecutable(bin, cwd);
+      args = rest;
+    } else {
+      [executable, ...args] = command.split(" ");
+    }
+
+    if (capture) {
+      return this.execCapture(command, { cwd, env });
+    }
+
+    return this.execInherit(executable, args, { cwd, env });
+  }
+
+  /**
+   * Execute command with inherited stdio (streams to terminal).
+   */
+  protected async execInherit(
+    executable: string,
+    args: string[],
+    options: { cwd: string; env?: Record<string, string> },
+  ): Promise<string> {
+    const proc = spawn(executable, args, {
+      stdio: "inherit",
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        ...options.env,
+      },
+    });
+
+    return new Promise<string>((resolve, reject) => {
+      proc.on("exit", (code) => {
+        if (code === 0 || code === null) {
+          resolve("");
+        } else {
+          reject(new AlephaError(`Command exited with code ${code}`));
+        }
+      });
+      proc.on("error", reject);
+    });
+  }
+
+  /**
+   * Execute command and capture stdout.
+   */
+  protected execCapture(
+    command: string,
+    options: { cwd: string; env?: Record<string, string> },
+  ): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      exec(
+        command,
+        {
+          cwd: options.cwd,
+          env: {
+            ...process.env,
+            LOG_FORMAT: "pretty",
+            ...options.env,
+          },
+        },
+        (err, stdout) => {
+          if (err) {
+            (err as any).stdout = stdout;
+            reject(err);
+          } else {
+            resolve(stdout);
+          }
+        },
+      );
+    });
+  }
+
+  /**
+   * Resolve executable path from node_modules/.bin.
+   *
+   * Search order:
+   * 1. Local: node_modules/.bin/
+   * 2. Pnpm nested: node_modules/alepha/node_modules/.bin/
+   * 3. Monorepo: Walk up to 3 parent directories
+   */
+  protected async resolveExecutable(
+    name: string,
+    root: string,
+  ): Promise<string> {
+    const suffix = process.platform === "win32" ? ".cmd" : "";
+
+    // 1. Local node_modules
+    let execPath = await this.findExecutable(
+      root,
+      `node_modules/.bin/${name}${suffix}`,
+    );
+
+    // 2. Pnpm nested (alepha's own node_modules)
+    if (!execPath) {
+      execPath = await this.findExecutable(
+        root,
+        `node_modules/alepha/node_modules/.bin/${name}${suffix}`,
+      );
+    }
+
+    // 3. Monorepo: check parent directories (up to 3 levels)
+    if (!execPath) {
+      let parentDir = this.fs.join(root, "..");
+      for (let i = 0; i < 3; i++) {
+        execPath = await this.findExecutable(
+          parentDir,
+          `node_modules/.bin/${name}${suffix}`,
+        );
+        if (execPath) break;
+        parentDir = this.fs.join(parentDir, "..");
+      }
+    }
+
+    if (!execPath) {
+      throw new AlephaError(
+        `Could not find executable for '${name}'. Make sure the package is installed.`,
+      );
+    }
+
+    return execPath;
+  }
+
+  /**
+   * Check if executable exists at path.
+   */
+  protected async findExecutable(
+    root: string,
+    relativePath: string,
+  ): Promise<string | undefined> {
+    const fullPath = this.fs.join(root, relativePath);
+    if (await this.fs.exists(fullPath)) {
+      return fullPath;
+    }
+    return undefined;
+  }
+
+  /**
+   * Check if a command is installed and available in the system PATH.
+   */
+  public isInstalled(command: string): Promise<boolean> {
+    return new Promise((resolve) => {
+      const check =
+        process.platform === "win32"
+          ? `where ${command}`
+          : `command -v ${command}`;
+      exec(check, (error) => resolve(!error));
+    });
+  }
+}

package/src/system/providers/ShellProvider.ts

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface ShellRunOptions {
+  /**
+   * Working directory for the command.
+   */
+  root?: string;
+
+  /**
+   * Additional environment variables.
+   */
+  env?: Record<string, string>;
+
+  /**
+   * Resolve the executable from node_modules/.bin.
+   * Supports local project, pnpm nested, and monorepo structures.
+   * @default false
+   */
+  resolve?: boolean;
+
+  /**
+   * Capture stdout instead of inheriting stdio.
+   * When true, returns stdout as string.
+   * When false, streams output to terminal.
+   * @default false
+   */
+  capture?: boolean;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Abstract provider for executing shell commands and binaries.
+ *
+ * Implementations:
+ * - `NodeShellProvider` - Real shell execution using Node.js child_process
+ * - `MemoryShellProvider` - In-memory mock for testing
+ *
+ * @example
+ * ```typescript
+ * class MyService {
+ *   protected readonly shell = $inject(ShellProvider);
+ *
+ *   async build() {
+ *     // Run shell command directly
+ *     await this.shell.run("yarn install");
+ *
+ *     // Run local binary with resolution
+ *     await this.shell.run("vite build", { resolve: true });
+ *
+ *     // Capture output
+ *     const output = await this.shell.run("echo hello", { capture: true });
+ *   }
+ * }
+ * ```
+ */
+export abstract class ShellProvider {
+  /**
+   * Run a shell command or binary.
+   *
+   * @param command - The command to run
+   * @param options - Execution options
+   * @returns stdout if capture is true, empty string otherwise
+   */
+  abstract run(command: string, options?: ShellRunOptions): Promise<string>;
+
+  /**
+   * Check if a command is installed and available in the system PATH.
+   *
+   * @param command - The command name to check
+   * @returns true if the command is available
+   */
+  abstract isInstalled(command: string): Promise<boolean>;
+}

package/src/{file → system}/services/FileDetector.spec.ts

@@ -1,7 +1,7 @@
 import { Readable } from "node:stream";
 import { Alepha } from "alepha";
 import { beforeEach, describe, expect, it } from "vitest";
-import { AlephaFile } from "../index.ts";
+import { AlephaSystem } from "../index.ts";
 import { FileDetector } from "../services/FileDetector.ts";
 
 /**
@@ -26,7 +26,7 @@ describe("FileDetector", () => {
   let detector: FileDetector;
 
   beforeEach(() => {
-    const alepha = Alepha.create().with(AlephaFile);
+    const alepha = Alepha.create().with(AlephaSystem);
     detector = alepha.inject(FileDetector);
   });
 

package/src/thread/index.ts

@@ -22,9 +22,18 @@ Alepha.prototype.isWorkerThread = function (this: Alepha): boolean {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Simple interface for managing worker threads in Alepha.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | experimental |
+ *
+ * Multi-threading support.
+ *
+ * **Features:**
+ * - Worker thread definitions
+ * - Worker thread management
+ * - Message passing
+ * - Worker pools
  *
- * @see {@link $thread}
  * @module alepha.thread
  */
 export const AlephaThread = $module({

package/src/topic/core/index.ts

@@ -15,12 +15,19 @@ export * from "./providers/TopicProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Generic interface for pub/sub messaging.
- * Gives you the ability to create topics and subscribers.
- * This module provides only a memory implementation of the topic provider.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
+ *
+ * Publish/subscribe messaging for event-driven architectures.
+ *
+ * **Features:**
+ * - Pub/sub topics with type-safe messages
+ * - Topic subscription handlers
+ * - Multiple subscriber support
+ * - Message filtering and routing
+ * - Providers: Memory (dev), Redis (production)
  *
- * @see {@link $topic}
- * @see {@link $subscriber}
  * @module alepha.topic
  */
 export const AlephaTopic = $module({

package/src/vite/index.ts

@@ -1,15 +1,16 @@
 import type { Alepha } from "alepha";
 
 // Helpers (for advanced use)
-export * from "./helpers/boot.ts";
 export * from "./helpers/createBufferedLogger.ts";
+export * from "./helpers/importVite.ts";
+export * from "./helpers/importViteReact.ts";
 // Plugins (public API)
-export * from "./plugins/viteAlephaDev.ts";
 export * from "./plugins/viteAlephaSsrPreload.ts";
 export * from "./plugins/viteCompress.ts";
 // Tasks (for CLI integration)
 export * from "./tasks/index.ts";
 
 declare global {
+  var __alepha: Alepha;
   var __cli_alepha: Alepha;
 }

package/src/vite/tasks/buildClient.ts

@@ -36,11 +36,6 @@ export interface BuildClientOptions {
     hostname: string;
   };
 
-  /**
-   * Override Vite config options.
-   */
-  config?: UserConfig;
-
   /**
    * If true, generate build stats report.
    */
@@ -61,7 +56,7 @@ export interface BuildClientOptions {
  * including code splitting, minification, and optional compression.
  */
 export async function buildClient(opts: BuildClientOptions): Promise<void> {
-  const { build: viteBuild, mergeConfig } = await importVite();
+  const { build: viteBuild } = await importVite();
   const plugins: any[] = [];
 
   const viteReact = await importViteReact();
@@ -103,7 +98,6 @@ export async function buildClient(opts: BuildClientOptions): Promise<void> {
       outDir: opts.dist,
       // Generate manifest for SSR module preloading
       manifest: true,
-      ssrManifest: true,
       rollupOptions: {
         output: {
           entryFileNames: "entry.[hash].js",
@@ -118,7 +112,7 @@ export async function buildClient(opts: BuildClientOptions): Promise<void> {
   };
 
   try {
-    await viteBuild(mergeConfig(viteBuildClientConfig, opts.config ?? {}));
+    await viteBuild(viteBuildClientConfig);
   } catch (error) {
     // Flush buffered logs on failure so user can see what happened
     logger?.flush();