alepha 0.15.1 → 0.15.3

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);
@@ -289,8 +291,17 @@ export class NodeFileSystemProvider implements FileSystemProvider {
    * await fs.mkdir("/tmp/mydir", { mode: 0o755 });
    * ```
    */
-  async mkdir(path: string, options?: MkdirOptions): Promise<void> {
-    await fsMkdir(path, options);
+  async mkdir(path: string, options: MkdirOptions = {}): Promise<void> {
+    const p = fsMkdir(path, {
+      recursive: options.recursive ?? true,
+      mode: options.mode,
+    });
+
+    if (options.force === false) {
+      await p;
+    } else {
+      await p.catch(() => {});
+    }
   }
 
   /**
@@ -418,6 +429,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/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();
@@ -117,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();

package/src/vite/tasks/buildServer.ts

@@ -23,7 +23,7 @@ export interface BuildServerOptions {
 
   /**
    * Optional client directory name (relative to distDir).
-   * If provided, the client template will be embedded in the server output.
+   * If provided, the SSR manifest will be embedded in the server output.
    */
   clientDir?: string;
 
@@ -61,6 +61,7 @@ export interface BuildServerResult {
    * Can be used to set in alepha store for pre-rendering.
    */
   manifest?: {
+    base?: string;
     client?: Record<string, any>;
     preload?: Record<string, string>;
   };
@@ -166,21 +167,15 @@ export async function buildServer(
 
   const entryFile = extractEntryFromBundle(opts.entry, result);
 
-  // Embed client template if client was built
-  let template = "";
-  if (opts.clientDir) {
-    const index = await readFile(
-      `${opts.distDir}/${opts.clientDir}/index.html`,
-      "utf-8",
-    );
-    template = `__alepha.set("alepha.react.server.template", \`${index.replace(/>\s*</g, "><").trim()}\`);\n`;
-  }
-
   // Embed SSR manifests if client was built
   // This bundles all manifest data into index.js for serverless deployments
   let manifest = "";
   let manifestData:
-    | { client?: Record<string, any>; preload?: Record<string, string> }
+    | {
+        base?: string;
+        client?: Record<string, any>;
+        preload?: Record<string, string>;
+      }
     | undefined;
 
   if (opts.clientDir) {
@@ -193,7 +188,18 @@ export async function buildServer(
     // Strip unused fields from client manifest to reduce bundle size
     const strippedClientManifest = stripClientManifest(clientManifest);
 
+    // Get base path from resolved config (defaults to "/" if not set)
+    // Normalize: ensure it starts with "/" and doesn't end with "/" (unless it's just "/")
+    let base = resolvedConfig.base || "/";
+    if (!base.startsWith("/")) {
+      base = `/${base}`;
+    }
+    if (base.length > 1 && base.endsWith("/")) {
+      base = base.slice(0, -1);
+    }
+
     manifestData = {
+      base: base !== "/" ? base : undefined, // Only include if not default
       client: strippedClientManifest,
       preload: preloadManifest,
     };
@@ -214,7 +220,7 @@ export async function buildServer(
 
   await writeFile(
     `${opts.distDir}/index.js`,
-    `${warning}\n${template}${manifest}import './server/${entryFile}';\n`.trim(),
+    `${warning}\n${manifest}import './server/${entryFile}';\n`.trim(),
   );
 
   return { entryFile, manifest: manifestData };