alepha 0.15.1 → 0.15.3

package/dist/{file → system}/index.js

@@ -1,18 +1,20 @@
-import { $inject, $module, AlephaError, isFileLike } from "alepha";
+import { $inject, $module, AlephaError, Json, isFileLike } from "alepha";
+import { join } from "node:path";
 import { createReadStream } from "node:fs";
 import { access, copyFile, cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
 import { PassThrough, Readable } from "node:stream";
 import { fileURLToPath } from "node:url";
+import { exec, spawn } from "node:child_process";
+import { $logger } from "alepha/logger";
 
-//#region ../../src/file/providers/FileSystemProvider.ts
+//#region ../../src/system/providers/FileSystemProvider.ts
 /**
 * FileSystem interface providing utilities for working with files.
 */
 var FileSystemProvider = class {};
 
 //#endregion
-//#region ../../src/file/providers/MemoryFileSystemProvider.ts
+//#region ../../src/system/providers/MemoryFileSystemProvider.ts
 /**
 * In-memory implementation of FileSystemProvider for testing.
 *
@@ -37,6 +39,7 @@ var FileSystemProvider = class {};
 * ```
 */
 var MemoryFileSystemProvider = class {
+	json = $inject(Json);
 	/**
 	* In-memory storage for files (path -> content)
 	*/
@@ -54,6 +57,14 @@ var MemoryFileSystemProvider = class {
 	*/
 	writeFileCalls = [];
 	/**
+	* Track readFile calls for test assertions
+	*/
+	readFileCalls = [];
+	/**
+	* Track rm calls for test assertions
+	*/
+	rmCalls = [];
+	/**
 	* Track join calls for test assertions
 	*/
 	joinCalls = [];
@@ -76,15 +87,32 @@ var MemoryFileSystemProvider = class {
 	}
 	/**
 	* Join path segments using forward slashes.
+	* Uses Node's path.join for proper normalization (handles .. and .)
 	*/
 	join(...paths) {
 		this.joinCalls.push(paths);
-		return paths.filter(Boolean).join("/").replace(/\/+/g, "/");
+		return join(...paths);
 	}
 	/**
 	* Create a FileLike object from various sources.
 	*/
 	createFile(options) {
+		if ("path" in options) {
+			const filePath = options.path;
+			const buffer = this.files.get(filePath);
+			if (buffer === void 0) throw new Error(`ENOENT: no such file or directory, open '${filePath}'`);
+			return {
+				name: options.name ?? filePath.split("/").pop() ?? "file",
+				type: options.type ?? "application/octet-stream",
+				size: buffer.byteLength,
+				lastModified: Date.now(),
+				stream: () => {
+					throw new Error("Stream not implemented in MemoryFileSystemProvider");
+				},
+				arrayBuffer: async () => buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+				text: async () => buffer.toString("utf-8")
+			};
+		}
 		if ("buffer" in options) {
 			const buffer = options.buffer;
 			return {
@@ -119,6 +147,10 @@ var MemoryFileSystemProvider = class {
 	* Remove a file or directory from memory.
 	*/
 	async rm(path, options) {
+		this.rmCalls.push({
+			path,
+			options
+		});
 		if (!(this.files.has(path) || this.directories.has(path)) && !options?.force) throw new Error(`ENOENT: no such file or directory, rm '${path}'`);
 		if (this.directories.has(path)) if (options?.recursive) {
 			this.directories.delete(path);
@@ -213,12 +245,26 @@ var MemoryFileSystemProvider = class {
 	* Read a file from memory.
 	*/
 	async readFile(path) {
+		this.readFileCalls.push(path);
 		if (this.readFileError) throw this.readFileError;
 		const content = this.files.get(path);
 		if (!content) throw new Error(`ENOENT: no such file or directory, open '${path}'`);
 		return content;
 	}
 	/**
+	* Read a file from memory as text.
+	*/
+	async readTextFile(path) {
+		return (await this.readFile(path)).toString("utf-8");
+	}
+	/**
+	* Read a file from memory as JSON.
+	*/
+	async readJsonFile(path) {
+		const text = await this.readTextFile(path);
+		return this.json.parse(text);
+	}
+	/**
 	* Write a file to memory.
 	*/
 	async writeFile(path, data) {
@@ -239,12 +285,59 @@ var MemoryFileSystemProvider = class {
 		this.directories.clear();
 		this.mkdirCalls = [];
 		this.writeFileCalls = [];
+		this.readFileCalls = [];
+		this.rmCalls = [];
 		this.joinCalls = [];
 		this.mkdirError = null;
 		this.writeFileError = null;
 		this.readFileError = null;
 	}
 	/**
+	* Check if a file was written during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasWritten("/project/tsconfig.json")).toBe(true);
+	* ```
+	*/
+	wasWritten(path) {
+		return this.writeFileCalls.some((call) => call.path === path);
+	}
+	/**
+	* Check if a file was written with content matching a pattern.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasWrittenMatching("/project/tsconfig.json", /extends/)).toBe(true);
+	* ```
+	*/
+	wasWrittenMatching(path, pattern) {
+		const call = this.writeFileCalls.find((c) => c.path === path);
+		return call ? pattern.test(call.data) : false;
+	}
+	/**
+	* Check if a file was read during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasRead("/project/package.json")).toBe(true);
+	* ```
+	*/
+	wasRead(path) {
+		return this.readFileCalls.includes(path);
+	}
+	/**
+	* Check if a file was deleted during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasDeleted("/project/old-file.txt")).toBe(true);
+	* ```
+	*/
+	wasDeleted(path) {
+		return this.rmCalls.some((call) => call.path === path);
+	}
+	/**
 	* Get the content of a file as a string (convenience method for testing).
 	*/
 	getFileContent(path) {
@@ -253,7 +346,116 @@ var MemoryFileSystemProvider = class {
 };
 
 //#endregion
-//#region ../../src/file/services/FileDetector.ts
+//#region ../../src/system/providers/MemoryShellProvider.ts
+/**
+* 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");
+* ```
+*/
+var MemoryShellProvider = class {
+	/**
+	* All recorded shell calls.
+	*/
+	calls = [];
+	/**
+	* Simulated outputs for specific commands.
+	*/
+	outputs = /* @__PURE__ */ new Map();
+	/**
+	* Commands that should throw an error.
+	*/
+	errors = /* @__PURE__ */ new Map();
+	/**
+	* Commands considered installed in the system PATH.
+	*/
+	installedCommands = /* @__PURE__ */ new Set();
+	/**
+	* Configure the mock with predefined outputs, errors, and installed commands.
+	*/
+	configure(options) {
+		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.
+	*/
+	async run(command, options = {}) {
+		this.calls.push({
+			command,
+			options
+		});
+		const errorMsg = this.errors.get(command);
+		if (errorMsg) throw new Error(errorMsg);
+		return this.outputs.get(command) ?? "";
+	}
+	/**
+	* Check if a specific command was called.
+	*/
+	wasCalled(command) {
+		return this.calls.some((call) => call.command === command);
+	}
+	/**
+	* Check if a command matching a pattern was called.
+	*/
+	wasCalledMatching(pattern) {
+		return this.calls.some((call) => pattern.test(call.command));
+	}
+	/**
+	* Get all calls matching a pattern.
+	*/
+	getCallsMatching(pattern) {
+		return this.calls.filter((call) => pattern.test(call.command));
+	}
+	/**
+	* Check if a command is installed.
+	*/
+	async isInstalled(command) {
+		return this.installedCommands.has(command);
+	}
+	/**
+	* Reset all recorded state.
+	*/
+	reset() {
+		this.calls = [];
+		this.outputs.clear();
+		this.errors.clear();
+		this.installedCommands.clear();
+	}
+};
+
+//#endregion
+//#region ../../src/system/services/FileDetector.ts
 /**
 * Service for detecting file types and getting content types.
 *
@@ -956,7 +1158,7 @@ var FileDetector = class FileDetector {
 };
 
 //#endregion
-//#region ../../src/file/providers/NodeFileSystemProvider.ts
+//#region ../../src/system/providers/NodeFileSystemProvider.ts
 /**
 * Node.js implementation of FileSystem interface.
 *
@@ -983,6 +1185,7 @@ var FileDetector = class FileDetector {
 */
 var NodeFileSystemProvider = class {
 	detector = $inject(FileDetector);
+	json = $inject(Json);
 	join(...paths) {
 		return join(...paths);
 	}
@@ -1162,8 +1365,13 @@ var NodeFileSystemProvider = class {
 	* await fs.mkdir("/tmp/mydir", { mode: 0o755 });
 	* ```
 	*/
-	async mkdir(path, options) {
-		await mkdir(path, options);
+	async mkdir(path, options = {}) {
+		const p = mkdir(path, {
+			recursive: options.recursive ?? true,
+			mode: options.mode
+		});
+		if (options.force === false) await p;
+		else await p.catch(() => {});
 	}
 	/**
 	* Lists files in a directory.
@@ -1269,6 +1477,37 @@ var NodeFileSystemProvider = class {
 		await writeFile(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) {
+		return (await this.readFile(path)).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(path) {
+		const text = await this.readTextFile(path);
+		return this.json.parse(text);
+	}
+	/**
 	* Creates a FileLike object from a Web File.
 	*
 	* @protected
@@ -1421,7 +1660,154 @@ var NodeFileSystemProvider = class {
 };
 
 //#endregion
-//#region ../../src/file/errors/FileError.ts
+//#region ../../src/system/providers/NodeShellProvider.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.
+*/
+var NodeShellProvider = class {
+	log = $logger();
+	fs = $inject(FileSystemProvider);
+	/**
+	* Run a shell command or binary.
+	*/
+	async run(command, options = {}) {
+		const { resolve = false, capture = false, root, env } = options;
+		const cwd = root ?? process.cwd();
+		this.log.debug(`Shell: ${command}`, {
+			cwd,
+			resolve,
+			capture
+		});
+		let executable;
+		let args;
+		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).
+	*/
+	async execInherit(executable, args, options) {
+		const proc = spawn(executable, args, {
+			stdio: "inherit",
+			cwd: options.cwd,
+			env: {
+				...process.env,
+				...options.env
+			}
+		});
+		return new Promise((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.
+	*/
+	execCapture(command, options) {
+		return new Promise((resolve, reject) => {
+			exec(command, {
+				cwd: options.cwd,
+				env: {
+					...process.env,
+					LOG_FORMAT: "pretty",
+					...options.env
+				}
+			}, (err, stdout) => {
+				if (err) {
+					err.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
+	*/
+	async resolveExecutable(name, root) {
+		const suffix = process.platform === "win32" ? ".cmd" : "";
+		let execPath = await this.findExecutable(root, `node_modules/.bin/${name}${suffix}`);
+		if (!execPath) execPath = await this.findExecutable(root, `node_modules/alepha/node_modules/.bin/${name}${suffix}`);
+		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.
+	*/
+	async findExecutable(root, relativePath) {
+		const fullPath = this.fs.join(root, relativePath);
+		if (await this.fs.exists(fullPath)) return fullPath;
+	}
+	/**
+	* Check if a command is installed and available in the system PATH.
+	*/
+	isInstalled(command) {
+		return new Promise((resolve) => {
+			exec(process.platform === "win32" ? `where ${command}` : `command -v ${command}`, (error) => resolve(!error));
+		});
+	}
+};
+
+//#endregion
+//#region ../../src/system/providers/ShellProvider.ts
+/**
+* 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 });
+*   }
+* }
+* ```
+*/
+var ShellProvider = class {};
+
+//#endregion
+//#region ../../src/system/errors/FileError.ts
 var FileError = class extends Error {
 	constructor(message, cause) {
 		super(message);
@@ -1431,34 +1817,45 @@ var FileError = class extends Error {
 };
 
 //#endregion
-//#region ../../src/file/index.ts
+//#region ../../src/system/index.ts
 /**
-* Provides file system capabilities for Alepha applications with support for multiple file sources and operations.
+* | type | quality | stability |
+* |------|---------|-----------|
+* | tooling | standard | stable |
 *
-* The file module enables working with files from various sources (URLs, buffers, streams) and provides
-* utilities for file type detection, content type determination, and common file system operations.
+* System-level abstractions for portable code across runtimes.
 *
-* @see {@link FileDetector}
-* @see {@link FileSystemProvider}
-* @see {@link NodeFileSystemProvider}
-* @module alepha.file
+* **Features:**
+* - File system operations (read, write, exists, etc.)
+* - Shell command execution
+* - File type detection and MIME utilities
+* - Memory implementations for testing
+*
+* @module alepha.system
 */
-const AlephaFile = $module({
-	name: "alepha.file",
+const AlephaSystem = $module({
+	name: "alepha.system",
 	primitives: [],
 	services: [
 		FileDetector,
 		FileSystemProvider,
 		MemoryFileSystemProvider,
-		NodeFileSystemProvider
+		NodeFileSystemProvider,
+		ShellProvider,
+		MemoryShellProvider,
+		NodeShellProvider
 	],
 	register: (alepha) => alepha.with({
 		optional: true,
 		provide: FileSystemProvider,
 		use: NodeFileSystemProvider
+	}).with({
+		optional: true,
+		provide: ShellProvider,
+		use: alepha.isTest() ? MemoryShellProvider : NodeShellProvider
 	})
 });
 
 //#endregion
-export { AlephaFile, FileDetector, FileError, FileSystemProvider, MemoryFileSystemProvider, NodeFileSystemProvider };
+export { AlephaSystem, FileDetector, FileError, FileSystemProvider, MemoryFileSystemProvider, MemoryShellProvider, NodeFileSystemProvider, NodeShellProvider, ShellProvider };
 //# sourceMappingURL=index.js.map