alepha 0.15.0 → 0.15.2

package/dist/system/index.d.ts

@@ -0,0 +1,1158 @@
+import * as alepha0 from "alepha";
+import { FileLike, Json, StreamLike } from "alepha";
+import { Readable } from "node:stream";
+import * as alepha_logger0 from "alepha/logger";
+
+//#region ../../src/system/errors/FileError.d.ts
+declare class FileError extends Error {
+  constructor(message: string, cause?: Error);
+}
+//#endregion
+//#region ../../src/system/providers/FileSystemProvider.d.ts
+/**
+ * Options for creating a file from a URL
+ */
+interface CreateFileFromUrlOptions {
+  /**
+   * The URL to load the file from (file://, http://, or https://)
+   */
+  url: string;
+  /**
+   * The MIME type of the file (optional, will be detected from filename if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (optional, will be extracted from URL if not provided)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a path (URL with file:// scheme)
+ */
+interface CreateFileFromPathOptions {
+  /**
+   * The path to the file on the local filesystem
+   */
+  path: string;
+  /**
+   * The MIME type of the file (optional, will be detected from filename if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (optional, will be extracted from URL if not provided)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a Buffer
+ */
+interface CreateFileFromBufferOptions {
+  /**
+   * The Buffer containing the file data
+   */
+  buffer: Buffer;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a stream
+ */
+interface CreateFileFromStreamOptions {
+  /**
+   * The readable stream containing the file data
+   */
+  stream: StreamLike;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+  /**
+   * The size of the file in bytes (optional)
+   */
+  size?: number;
+}
+/**
+ * Options for creating a file from text content
+ */
+interface CreateFileFromTextOptions {
+  /**
+   * The text content to create the file from
+   */
+  text: string;
+  /**
+   * The MIME type of the file (default: text/plain)
+   */
+  type?: string;
+  /**
+   * The name of the file (default: "file.txt")
+   */
+  name?: string;
+}
+interface CreateFileFromResponseOptions {
+  /**
+   * The Response object containing the file data
+   */
+  response: Response;
+  /**
+   * Override the name (optional, uses filename from Content-Disposition header if not provided)
+   */
+  name?: string;
+  /**
+   * Override the MIME type (optional, uses file.type if not provided)
+   */
+  type?: string;
+}
+/**
+ * Options for creating a file from a Web File object
+ */
+interface CreateFileFromWebFileOptions {
+  /**
+   * The Web File object
+   */
+  file: File;
+  /**
+   * Override the MIME type (optional, uses file.type if not provided)
+   */
+  type?: string;
+  /**
+   * Override the name (optional, uses file.name if not provided)
+   */
+  name?: string;
+  /**
+   * Override the size (optional, uses file.size if not provided)
+   */
+  size?: number;
+}
+/**
+ * Options for creating a file from an ArrayBuffer
+ */
+interface CreateFileFromArrayBufferOptions {
+  /**
+   * The ArrayBuffer containing the file data
+   */
+  arrayBuffer: ArrayBuffer;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+}
+/**
+ * Union type for all createFile options
+ */
+type CreateFileOptions = CreateFileFromUrlOptions | CreateFileFromPathOptions | CreateFileFromBufferOptions | CreateFileFromStreamOptions | CreateFileFromTextOptions | CreateFileFromWebFileOptions | CreateFileFromResponseOptions | CreateFileFromArrayBufferOptions;
+/**
+ * Options for rm (remove) operation
+ */
+interface RmOptions {
+  /**
+   * If true, removes directories and their contents recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, no error will be thrown if the path does not exist
+   */
+  force?: boolean;
+}
+/**
+ * Options for cp (copy) operation
+ */
+interface CpOptions {
+  /**
+   * If true, copy directories recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, overwrite existing destination
+   */
+  force?: boolean;
+}
+/**
+ * Options for mkdir operation
+ */
+interface MkdirOptions {
+  /**
+   * If true, creates parent directories as needed
+   */
+  recursive?: boolean;
+  /**
+   * File mode (permission and sticky bits)
+   */
+  mode?: number;
+}
+/**
+ * Options for ls (list) operation
+ */
+interface LsOptions {
+  /**
+   * If true, list contents of directories recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, include hidden files (starting with .)
+   */
+  hidden?: boolean;
+}
+/**
+ * FileSystem interface providing utilities for working with files.
+ */
+declare abstract class FileSystemProvider {
+  /**
+   * Joins multiple path segments into a single path.
+   *
+   * @param paths - The path segments to join
+   * @returns The joined path
+   */
+  abstract join(...paths: string[]): string;
+  /**
+   * Creates a FileLike object from various sources.
+   *
+   * @param options - Options for creating the file
+   * @returns A FileLike object
+   */
+  abstract createFile(options: CreateFileOptions): FileLike;
+  /**
+   * Removes a file or directory.
+   *
+   * @param path - The path to remove
+   * @param options - Remove options
+   */
+  abstract rm(path: string, options?: RmOptions): Promise<void>;
+  /**
+   * Copies a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   * @param options - Copy options
+   */
+  abstract cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+  /**
+   * Moves/renames a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   */
+  abstract mv(src: string, dest: string): Promise<void>;
+  /**
+   * Creates a directory.
+   *
+   * @param path - The directory path to create
+   * @param options - Mkdir options
+   */
+  abstract mkdir(path: string, options?: MkdirOptions): Promise<void>;
+  /**
+   * Lists files in a directory.
+   *
+   * @param path - The directory path to list
+   * @param options - List options
+   * @returns Array of filenames
+   */
+  abstract ls(path: string, options?: LsOptions): Promise<string[]>;
+  /**
+   * Checks if a file or directory exists.
+   *
+   * @param path - The path to check
+   * @returns True if the path exists, false otherwise
+   */
+  abstract exists(path: string): Promise<boolean>;
+  /**
+   * Reads the content of a file.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a Buffer
+   */
+  abstract readFile(path: string): Promise<Buffer>;
+  /**
+   * Writes data to a file.
+   *
+   * @param path - The file path to write to
+   * @param data - The data to write (Buffer or string)
+   */
+  abstract writeFile(path: string, data: Uint8Array | Buffer | string | FileLike): Promise<void>;
+  /**
+   * Reads the content of a file as a string.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a string
+   */
+  abstract readTextFile(path: string): Promise<string>;
+  /**
+   * Reads the content of a file as JSON.
+   *
+   * @param path - The file path to read
+   * @returns The parsed JSON content
+   */
+  abstract readJsonFile<T = unknown>(path: string): Promise<T>;
+}
+//#endregion
+//#region ../../src/system/providers/MemoryFileSystemProvider.d.ts
+interface MemoryFileSystemProviderOptions {
+  /**
+   * Error to throw on mkdir operations (for testing error handling)
+   */
+  mkdirError?: Error | null;
+  /**
+   * Error to throw on writeFile operations (for testing error handling)
+   */
+  writeFileError?: Error | null;
+  /**
+   * Error to throw on readFile operations (for testing error handling)
+   */
+  readFileError?: Error | null;
+}
+/**
+ * In-memory implementation of FileSystemProvider for testing.
+ *
+ * This provider stores all files and directories in memory, making it ideal for
+ * unit tests that need to verify file operations without touching the real file system.
+ *
+ * @example
+ * ```typescript
+ * // In tests, substitute the real FileSystemProvider with MemoryFileSystemProvider
+ * const alepha = Alepha.create().with({
+ *   provide: FileSystemProvider,
+ *   use: MemoryFileSystemProvider,
+ * });
+ *
+ * // Run code that uses FileSystemProvider
+ * const service = alepha.inject(MyService);
+ * await service.saveFile("test.txt", "Hello World");
+ *
+ * // Verify the file was written
+ * const memoryFs = alepha.inject(MemoryFileSystemProvider);
+ * expect(memoryFs.files.get("test.txt")?.toString()).toBe("Hello World");
+ * ```
+ */
+declare class MemoryFileSystemProvider implements FileSystemProvider {
+  protected json: Json;
+  /**
+   * In-memory storage for files (path -> content)
+   */
+  files: Map<string, Buffer<ArrayBufferLike>>;
+  /**
+   * In-memory storage for directories
+   */
+  directories: Set<string>;
+  /**
+   * Track mkdir calls for test assertions
+   */
+  mkdirCalls: Array<{
+    path: string;
+    options?: MkdirOptions;
+  }>;
+  /**
+   * Track writeFile calls for test assertions
+   */
+  writeFileCalls: Array<{
+    path: string;
+    data: string;
+  }>;
+  /**
+   * Track readFile calls for test assertions
+   */
+  readFileCalls: Array<string>;
+  /**
+   * Track rm calls for test assertions
+   */
+  rmCalls: Array<{
+    path: string;
+    options?: RmOptions;
+  }>;
+  /**
+   * Track join calls for test assertions
+   */
+  joinCalls: Array<string[]>;
+  /**
+   * Error to throw on mkdir (for testing error handling)
+   */
+  mkdirError: Error | null;
+  /**
+   * Error to throw on writeFile (for testing error handling)
+   */
+  writeFileError: Error | null;
+  /**
+   * Error to throw on readFile (for testing error handling)
+   */
+  readFileError: Error | null;
+  constructor(options?: MemoryFileSystemProviderOptions);
+  /**
+   * Join path segments using forward slashes.
+   * Uses Node's path.join for proper normalization (handles .. and .)
+   */
+  join(...paths: string[]): string;
+  /**
+   * Create a FileLike object from various sources.
+   */
+  createFile(options: CreateFileOptions): FileLike;
+  /**
+   * Remove a file or directory from memory.
+   */
+  rm(path: string, options?: RmOptions): Promise<void>;
+  /**
+   * Copy a file or directory in memory.
+   */
+  cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+  /**
+   * Move/rename a file or directory in memory.
+   */
+  mv(src: string, dest: string): Promise<void>;
+  /**
+   * Create a directory in memory.
+   */
+  mkdir(path: string, options?: MkdirOptions): Promise<void>;
+  /**
+   * List files in a directory.
+   */
+  ls(path: string, options?: LsOptions): Promise<string[]>;
+  /**
+   * Check if a file or directory exists in memory.
+   */
+  exists(path: string): Promise<boolean>;
+  /**
+   * Read a file from memory.
+   */
+  readFile(path: string): Promise<Buffer>;
+  /**
+   * Read a file from memory as text.
+   */
+  readTextFile(path: string): Promise<string>;
+  /**
+   * Read a file from memory as JSON.
+   */
+  readJsonFile<T = unknown>(path: string): Promise<T>;
+  /**
+   * Write a file to memory.
+   */
+  writeFile(path: string, data: Uint8Array | Buffer | string | FileLike): Promise<void>;
+  /**
+   * Reset all in-memory state (useful between tests).
+   */
+  reset(): void;
+  /**
+   * Check if a file was written during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(fs.wasWritten("/project/tsconfig.json")).toBe(true);
+   * ```
+   */
+  wasWritten(path: string): boolean;
+  /**
+   * Check if a file was written with content matching a pattern.
+   *
+   * @example
+   * ```typescript
+   * expect(fs.wasWrittenMatching("/project/tsconfig.json", /extends/)).toBe(true);
+   * ```
+   */
+  wasWrittenMatching(path: string, pattern: RegExp): boolean;
+  /**
+   * Check if a file was read during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(fs.wasRead("/project/package.json")).toBe(true);
+   * ```
+   */
+  wasRead(path: string): boolean;
+  /**
+   * Check if a file was deleted during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(fs.wasDeleted("/project/old-file.txt")).toBe(true);
+   * ```
+   */
+  wasDeleted(path: string): boolean;
+  /**
+   * Get the content of a file as a string (convenience method for testing).
+   */
+  getFileContent(path: string): string | undefined;
+}
+//#endregion
+//#region ../../src/system/providers/ShellProvider.d.ts
+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 });
+ *   }
+ * }
+ * ```
+ */
+declare 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>;
+}
+//#endregion
+//#region ../../src/system/providers/MemoryShellProvider.d.ts
+interface MemoryShellCall {
+  command: string;
+  options: ShellRunOptions;
+}
+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");
+ * ```
+ */
+declare class MemoryShellProvider implements ShellProvider {
+  /**
+   * All recorded shell calls.
+   */
+  calls: MemoryShellCall[];
+  /**
+   * Simulated outputs for specific commands.
+   */
+  outputs: Map<string, string>;
+  /**
+   * Commands that should throw an error.
+   */
+  errors: Map<string, string>;
+  /**
+   * Commands considered installed in the system PATH.
+   */
+  installedCommands: Set<string>;
+  /**
+   * Configure the mock with predefined outputs, errors, and installed commands.
+   */
+  configure(options: MemoryShellProviderOptions): this;
+  /**
+   * Record command and return simulated output.
+   */
+  run(command: string, options?: ShellRunOptions): Promise<string>;
+  /**
+   * Check if a specific command was called.
+   */
+  wasCalled(command: string): boolean;
+  /**
+   * Check if a command matching a pattern was called.
+   */
+  wasCalledMatching(pattern: RegExp): boolean;
+  /**
+   * Get all calls matching a pattern.
+   */
+  getCallsMatching(pattern: RegExp): MemoryShellCall[];
+  /**
+   * Check if a command is installed.
+   */
+  isInstalled(command: string): Promise<boolean>;
+  /**
+   * Reset all recorded state.
+   */
+  reset(): void;
+}
+//#endregion
+//#region ../../src/system/services/FileDetector.d.ts
+interface FileTypeResult {
+  /**
+   * The detected MIME type
+   */
+  mimeType: string;
+  /**
+   * The detected file extension
+   */
+  extension: string;
+  /**
+   * Whether the file type was verified by magic bytes
+   */
+  verified: boolean;
+  /**
+   * The stream (potentially wrapped to allow re-reading)
+   */
+  stream: Readable;
+}
+/**
+ * Service for detecting file types and getting content types.
+ *
+ * @example
+ * ```typescript
+ * const detector = alepha.inject(FileDetector);
+ *
+ * // Get content type from filename
+ * const mimeType = detector.getContentType("image.png"); // "image/png"
+ *
+ * // Detect file type by magic bytes
+ * const stream = createReadStream('image.png');
+ * const result = await detector.detectFileType(stream, 'image.png');
+ * console.log(result.mimeType); // 'image/png'
+ * console.log(result.verified); // true if magic bytes match
+ * ```
+ */
+declare class FileDetector {
+  /**
+   * Magic byte signatures for common file formats.
+   * Each signature is represented as an array of bytes or null (wildcard).
+   */
+  protected static readonly MAGIC_BYTES: Record<string, {
+    signature: (number | null)[];
+    mimeType: string;
+  }[]>;
+  /**
+   * All possible format signatures for checking against actual file content
+   */
+  protected static readonly ALL_SIGNATURES: {
+    signature: (number | null)[];
+    mimeType: string;
+    ext: string;
+  }[];
+  /**
+   * MIME type map for file extensions.
+   *
+   * Can be used to get the content type of file based on its extension.
+   * Feel free to add more mime types in your project!
+   */
+  static readonly mimeMap: Record<string, string>;
+  /**
+   * Reverse MIME type map for looking up extensions from MIME types.
+   * Prefers shorter, more common extensions when multiple exist.
+   */
+  protected static readonly reverseMimeMap: Record<string, string>;
+  /**
+   * Returns the file extension for a given MIME type.
+   *
+   * @param mimeType - The MIME type to look up
+   * @returns The file extension (without dot), or "bin" if not found
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const ext = detector.getExtensionFromMimeType("image/png"); // "png"
+   * const ext2 = detector.getExtensionFromMimeType("application/octet-stream"); // "bin"
+   * ```
+   */
+  getExtensionFromMimeType(mimeType: string): string;
+  /**
+   * Returns the content type of file based on its filename.
+   *
+   * @param filename - The filename to check
+   * @returns The MIME type
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const mimeType = detector.getContentType("image.png"); // "image/png"
+   * ```
+   */
+  getContentType(filename: string): string;
+  /**
+   * Detects the file type by checking magic bytes against the stream content.
+   *
+   * @param stream - The readable stream to check
+   * @param filename - The filename (used to get the extension)
+   * @returns File type information including MIME type, extension, and verification status
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const stream = createReadStream('image.png');
+   * const result = await detector.detectFileType(stream, 'image.png');
+   * console.log(result.mimeType); // 'image/png'
+   * console.log(result.verified); // true if magic bytes match
+   * ```
+   */
+  detectFileType(stream: Readable, filename: string): Promise<FileTypeResult>;
+  /**
+   * Reads all bytes from a stream and returns the first N bytes along with a new stream containing all data.
+   * This approach reads the entire stream upfront to avoid complex async handling issues.
+   *
+   * @protected
+   */
+  protected peekBytes(stream: Readable, numBytes: number): Promise<{
+    buffer: Buffer;
+    stream: Readable;
+  }>;
+  /**
+   * Checks if a buffer matches a magic byte signature.
+   *
+   * @protected
+   */
+  protected matchesSignature(buffer: Buffer, signature: (number | null)[]): boolean;
+}
+//#endregion
+//#region ../../src/system/providers/NodeFileSystemProvider.d.ts
+/**
+ * Node.js implementation of FileSystem interface.
+ *
+ * @example
+ * ```typescript
+ * const fs = alepha.inject(NodeFileSystemProvider);
+ *
+ * // Create from URL
+ * const file1 = fs.createFile({ url: "file:///path/to/file.png" });
+ *
+ * // Create from Buffer
+ * const file2 = fs.createFile({ buffer: Buffer.from("hello"), name: "hello.txt" });
+ *
+ * // Create from text
+ * const file3 = fs.createFile({ text: "Hello, world!", name: "greeting.txt" });
+ *
+ * // File operations
+ * await fs.mkdir("/tmp/mydir", { recursive: true });
+ * await fs.cp("/src/file.txt", "/dest/file.txt");
+ * await fs.mv("/old/path.txt", "/new/path.txt");
+ * const files = await fs.ls("/tmp");
+ * await fs.rm("/tmp/file.txt");
+ * ```
+ */
+declare class NodeFileSystemProvider implements FileSystemProvider {
+  protected detector: FileDetector;
+  protected json: Json;
+  join(...paths: string[]): string;
+  /**
+   * Creates a FileLike object from various sources.
+   *
+   * @param options - Options for creating the file
+   * @returns A FileLike object
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   *
+   * // From URL
+   * const file1 = fs.createFile({ url: "https://example.com/image.png" });
+   *
+   * // From Buffer
+   * const file2 = fs.createFile({
+   *   buffer: Buffer.from("hello"),
+   *   name: "hello.txt",
+   *   type: "text/plain"
+   * });
+   *
+   * // From text
+   * const file3 = fs.createFile({ text: "Hello!", name: "greeting.txt" });
+   *
+   * // From stream with detection
+   * const stream = createReadStream("/path/to/file.png");
+   * const file4 = fs.createFile({ stream, name: "image.png" });
+   * ```
+   */
+  createFile(options: CreateFileOptions): FileLike;
+  /**
+   * Removes a file or directory.
+   *
+   * @param path - The path to remove
+   * @param options - Remove options
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   *
+   * // Remove a file
+   * await fs.rm("/tmp/file.txt");
+   *
+   * // Remove a directory recursively
+   * await fs.rm("/tmp/mydir", { recursive: true });
+   *
+   * // Remove with force (no error if doesn't exist)
+   * await fs.rm("/tmp/maybe-exists.txt", { force: true });
+   * ```
+   */
+  rm(path: string, options?: RmOptions): Promise<void>;
+  /**
+   * Copies a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   * @param options - Copy options
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   *
+   * // Copy a file
+   * await fs.cp("/src/file.txt", "/dest/file.txt");
+   *
+   * // Copy a directory recursively
+   * await fs.cp("/src/dir", "/dest/dir", { recursive: true });
+   *
+   * // Copy with force (overwrite existing)
+   * await fs.cp("/src/file.txt", "/dest/file.txt", { force: true });
+   * ```
+   */
+  cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+  /**
+   * Moves/renames a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   *
+   * // Move/rename a file
+   * await fs.mv("/old/path.txt", "/new/path.txt");
+   *
+   * // Move a directory
+   * await fs.mv("/old/dir", "/new/dir");
+   * ```
+   */
+  mv(src: string, dest: string): Promise<void>;
+  /**
+   * Creates a directory.
+   *
+   * @param path - The directory path to create
+   * @param options - Mkdir options
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   *
+   * // Create a directory
+   * await fs.mkdir("/tmp/mydir");
+   *
+   * // Create nested directories
+   * await fs.mkdir("/tmp/path/to/dir", { recursive: true });
+   *
+   * // Create with specific permissions
+   * await fs.mkdir("/tmp/mydir", { mode: 0o755 });
+   * ```
+   */
+  mkdir(path: string, options?: MkdirOptions): Promise<void>;
+  /**
+   * Lists files in a directory.
+   *
+   * @param path - The directory path to list
+   * @param options - List options
+   * @returns Array of filenames
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   *
+   * // List files in a directory
+   * const files = await fs.ls("/tmp");
+   * console.log(files); // ["file1.txt", "file2.txt", "subdir"]
+   *
+   * // List with hidden files
+   * const allFiles = await fs.ls("/tmp", { hidden: true });
+   *
+   * // List recursively
+   * const allFilesRecursive = await fs.ls("/tmp", { recursive: true });
+   * ```
+   */
+  ls(path: string, options?: LsOptions): Promise<string[]>;
+  /**
+   * Checks if a file or directory exists.
+   *
+   * @param path - The path to check
+   * @returns True if the path exists, false otherwise
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   *
+   * if (await fs.exists("/tmp/file.txt")) {
+   *   console.log("File exists");
+   * }
+   * ```
+   */
+  exists(path: string): Promise<boolean>;
+  /**
+   * Reads the content of a file.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a Buffer
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   *
+   * const buffer = await fs.readFile("/tmp/file.txt");
+   * console.log(buffer.toString("utf-8"));
+   * ```
+   */
+  readFile(path: string): Promise<Buffer>;
+  /**
+   * Writes data to a file.
+   *
+   * @param path - The file path to write to
+   * @param data - The data to write (Buffer or string)
+   *
+   * @example
+   * ```typescript
+   * const fs = alepha.inject(NodeFileSystemProvider);
+   *
+   * // Write string
+   * await fs.writeFile("/tmp/file.txt", "Hello, world!");
+   *
+   * // Write Buffer
+   * await fs.writeFile("/tmp/file.bin", Buffer.from([0x01, 0x02, 0x03]));
+   * ```
+   */
+  writeFile(path: string, data: Uint8Array | Buffer | string | FileLike): Promise<void>;
+  /**
+   * 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");
+   * ```
+   */
+  readTextFile(path: string): Promise<string>;
+  /**
+   * 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");
+   * ```
+   */
+  readJsonFile<T = unknown>(path: string): Promise<T>;
+  /**
+   * Creates a FileLike object from a Web File.
+   *
+   * @protected
+   */
+  protected createFileFromWebFile(source: File, options?: {
+    type?: string;
+    name?: string;
+    size?: number;
+  }): FileLike;
+  /**
+   * Creates a FileLike object from a Buffer.
+   *
+   * @protected
+   */
+  protected createFileFromBuffer(source: Buffer, options?: {
+    type?: string;
+    name?: string;
+  }): FileLike;
+  /**
+   * Creates a FileLike object from a stream.
+   *
+   * @protected
+   */
+  protected createFileFromStream(source: StreamLike, options?: {
+    type?: string;
+    name?: string;
+    size?: number;
+  }): FileLike & {
+    _buffer: null | Buffer;
+  };
+  /**
+   * Creates a FileLike object from a URL.
+   *
+   * @protected
+   */
+  protected createFileFromUrl(url: string, options?: {
+    type?: string;
+    name?: string;
+  }): FileLike;
+  /**
+   * Gets a streaming response from a URL.
+   *
+   * @protected
+   */
+  protected getStreamingResponse(url: string): Readable;
+  /**
+   * Loads data from a URL.
+   *
+   * @protected
+   */
+  protected loadFromUrl(url: string): Promise<Buffer>;
+  /**
+   * Creates a stream from a URL.
+   *
+   * @protected
+   */
+  protected createStreamFromUrl(url: string): Readable;
+  /**
+   * Converts a stream-like object to a Buffer.
+   *
+   * @protected
+   */
+  protected streamToBuffer(streamLike: StreamLike): Promise<Buffer>;
+  /**
+   * Converts a Node.js Buffer to an ArrayBuffer.
+   *
+   * @protected
+   */
+  protected bufferToArrayBuffer(buffer: Buffer): ArrayBuffer;
+}
+//#endregion
+//#region ../../src/system/providers/NodeShellProvider.d.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.
+ */
+declare class NodeShellProvider implements ShellProvider {
+  protected readonly log: alepha_logger0.Logger;
+  protected readonly fs: FileSystemProvider;
+  /**
+   * Run a shell command or binary.
+   */
+  run(command: string, options?: ShellRunOptions): Promise<string>;
+  /**
+   * Execute command with inherited stdio (streams to terminal).
+   */
+  protected execInherit(executable: string, args: string[], options: {
+    cwd: string;
+    env?: Record<string, string>;
+  }): Promise<string>;
+  /**
+   * Execute command and capture stdout.
+   */
+  protected execCapture(command: string, options: {
+    cwd: string;
+    env?: Record<string, string>;
+  }): Promise<string>;
+  /**
+   * 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 resolveExecutable(name: string, root: string): Promise<string>;
+  /**
+   * Check if executable exists at path.
+   */
+  protected findExecutable(root: string, relativePath: string): Promise<string | undefined>;
+  /**
+   * Check if a command is installed and available in the system PATH.
+   */
+  isInstalled(command: string): Promise<boolean>;
+}
+//#endregion
+//#region ../../src/system/index.d.ts
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | tooling | standard | stable |
+ *
+ * System-level abstractions for portable code across runtimes.
+ *
+ * **Features:**
+ * - File system operations (read, write, exists, etc.)
+ * - Shell command execution
+ * - File type detection and MIME utilities
+ * - Memory implementations for testing
+ *
+ * @module alepha.system
+ */
+declare const AlephaSystem: alepha0.Service<alepha0.Module>;
+//#endregion
+export { AlephaSystem, CpOptions, CreateFileFromArrayBufferOptions, CreateFileFromBufferOptions, CreateFileFromPathOptions, CreateFileFromResponseOptions, CreateFileFromStreamOptions, CreateFileFromTextOptions, CreateFileFromUrlOptions, CreateFileFromWebFileOptions, CreateFileOptions, FileDetector, FileError, FileSystemProvider, FileTypeResult, LsOptions, MemoryFileSystemProvider, MemoryFileSystemProviderOptions, MemoryShellCall, MemoryShellProvider, MemoryShellProviderOptions, MkdirOptions, NodeFileSystemProvider, NodeShellProvider, RmOptions, ShellProvider, ShellRunOptions };
+//# sourceMappingURL=index.d.ts.map