xypriss 9.0.13 → 9.1.1

package/docs/features/filesystem-api.md

@@ -0,0 +1,242 @@
+# XyPriss FileSystem API Documentation
+
+## Overview
+
+The XyPriss FileSystem API is a robust, root-aware utility designed to simplify file system operations within XyPriss applications. Integrated directly into the global `__sys__` instance, it provides a comprehensive set of methods for path manipulation, file I/O, directory management, and advanced file system utilities.
+
+All methods are prefixed with the `$` symbol to maintain consistency with the XyPriss system naming conventions and are automatically delegated from the `__sys__` global via a dynamic proxy.
+
+## Core Concept: Root-Awareness
+
+The primary advantage of the XyPriss FileSystem API is its root-aware nature. Most operations that accept a path will automatically resolve it relative to the project's root directory (`__sys__.__root__`). This ensures that file operations remain scoped within the project and simplifies path management across different environments.
+
+---
+
+## API Reference
+
+### Path Operations
+
+These methods provide cross-platform path manipulation utilities, leveraging the underlying `node:path` module but with enhanced root-aware behavior where applicable.
+
+| Method                   | Description                                                                       |
+| :----------------------- | :-------------------------------------------------------------------------------- |
+| `$resolve(...paths)`     | Resolves path segments into an absolute path relative to the project root.        |
+| `$join(...paths)`        | Joins path segments using platform-specific separators and normalizes the result. |
+| `$dirname(path)`         | Returns the directory portion of a path.                                          |
+| `$basename(path, [ext])` | Returns the last portion of a path (filename or last directory).                  |
+| `$extname(path)`         | Returns the file extension, including the leading dot.                            |
+| `$relative(from, to)`    | Computes the relative path from one location to another.                          |
+| `$normalize(path)`       | Resolves '.' and '..' segments and eliminates redundant separators.               |
+| `$parse(path)`           | Breaks down a path into root, dir, base, ext, and name components.                |
+| `$format(pathObject)`    | Reconstructs a path string from a parsed path object.                             |
+
+### Existence & Type Checks
+
+Utilities for verifying the presence and nature of file system entries.
+
+| Method             | Description                                                 |
+| :----------------- | :---------------------------------------------------------- |
+| `$exists(path)`    | Synchronously checks if a file or directory exists.         |
+| `$isDir(path)`     | Verifies if the specified path points to a directory.       |
+| `$isFile(path)`    | Verifies if the specified path points to a regular file.    |
+| `$isSymlink(path)` | Identifies if the specified path is a symbolic link.        |
+| `$isEmpty(path)`   | Checks if a directory is empty or if a file has zero bytes. |
+| `$link(src, dest)` | Creates a symbolic link.                                    |
+
+### File Reading
+
+Methods for retrieving data from files with support for various formats and safety checks.
+
+| Method                         | Description                                              |
+| :----------------------------- | :------------------------------------------------------- |
+| `$readFile(path, [options])`   | Reads the entire contents of a file (defaults to UTF-8). |
+| `$readJson(path)`              | Reads and parses a JSON file into a JavaScript object.   |
+| `$readJsonSafe(path, default)` | Safely reads JSON, returning a default value on failure. |
+| `$readLines(path)`             | Reads a file and returns an array of its lines.          |
+| `$readNonEmptyLines(path)`     | Reads a file and returns only non-empty, trimmed lines.  |
+
+### File Writing
+
+Methods for creating and modifying file content, with automatic directory creation.
+
+| Method                           | Description                                                          |
+| :------------------------------- | :------------------------------------------------------------------- |
+| `$writeFile(path, data, [opts])` | Writes data to a file, creating parent directories if necessary.     |
+| `$writeJson(path, data, [opts])` | Serializes an object to JSON and writes it with 2-space indentation. |
+| `$append(path, data, [opts])`    | Appends data to the end of a file.                                   |
+| `$appendLine(path, line)`        | Appends a single line with an automatic newline character.           |
+| `$touch(path)`                   | Creates an empty file or updates the timestamps of an existing one.  |
+| `$writeIfNotExists(path, data)`  | Writes data only if the file does not already exist.                 |
+
+### Directory Operations
+
+Comprehensive tools for managing directory structures and listings.
+
+| Method                         | Description                                                        |
+| :----------------------------- | :----------------------------------------------------------------- |
+| `$mkdir(path, [recursive])`    | Creates a directory (recursive by default).                        |
+| `$ensureDir(path)`             | Guarantees a directory exists without throwing if it already does. |
+| `$ls(path)`                    | Lists the names of items within a directory.                       |
+| `$lsFullPath(path)`            | Lists items in a directory with their full absolute paths.         |
+| `$lsFiles(path)`               | Lists only the regular files in a directory.                       |
+| `$lsDirs(path)`                | Lists only the subdirectories in a directory.                      |
+| `$lsRecursive(path, [filter])` | Recursively lists all files in a directory tree.                   |
+| `$findByExt(path, ext)`        | Recursively finds files matching a specific extension.             |
+| `$findByPattern(path, regex)`  | Recursively finds files matching a regular expression.             |
+| `$findModifiedSince(dir, h)`   | Finds files modified within the last N hours.                      |
+
+### Copy & Move Operations
+
+| Method                          | Description                                                      |
+| :------------------------------ | :--------------------------------------------------------------- |
+| `$copy(src, dest, [overwrite])` | Copies a file or directory recursively.                          |
+| `$duplicate(path, newName)`     | Creates a copy of an item in the same directory with a new name. |
+| `$move(src, dest)`              | Moves or renames a file or directory.                            |
+| `$rename(path, newName)`        | Renames an item within its current directory.                    |
+| `$batchRename(path, pat, rep)`  | Performs mass rename using regex. Returns count or preview.      |
+
+### Delete Operations
+
+| Method                 | Description                                                             |
+| :--------------------- | :---------------------------------------------------------------------- |
+| `$rm(path, [options])` | Removes a file or directory recursively.                                |
+| `$rmIfExists(path)`    | Removes an item only if it exists, preventing errors.                   |
+| `$emptyDir(path)`      | Deletes all contents of a directory but preserves the directory itself. |
+
+### File Statistics & Metadata
+
+| Method              | Description                                                  |
+| :------------------ | :----------------------------------------------------------- |
+| `$stats(path)`      | Retrieves detailed metadata (size, timestamps, permissions). |
+| `$size(path)`       | Returns the size of a file in bytes.                         |
+| `$sizeHuman(path)`  | Returns a human-readable size string (e.g., "1.5 MB").       |
+| `$sizeDir(path)`    | Calculates the total size of a directory recursively.        |
+| `$createdAt(path)`  | Returns the creation date of the entry.                      |
+| `$modifiedAt(path)` | Returns the last modification date.                          |
+| `$accessedAt(path)` | Returns the last access date.                                |
+
+### Comparison & Search
+
+| Method                      | Description                                                          |
+| :-------------------------- | :------------------------------------------------------------------- |
+| `$isSameContent(p1, p2)`    | Compares two files byte-for-byte for equality.                       |
+| `$isNewer(p1, p2)`          | Checks if the first file was modified more recently than the second. |
+| `$isOlder(p1, p2)`          | Checks if the first file is older than the second.                   |
+| `$searchInFiles(dir, text)` | Performs high-performance Grep search inside files.                  |
+| `$grep(dir, pattern)`       | Native implementation of regex-based content search.                 |
+
+### Advanced Utilities
+
+| Method                     | Description                                                           |
+| :------------------------- | :-------------------------------------------------------------------- |
+| `$uniqueFilename(path)`    | Generates a non-conflicting filename (e.g., "file (1).txt").          |
+| `$mkdtemp([prefix])`       | Creates a unique temporary directory.                                 |
+| `$readForClipboard(path)`  | Reads file content with normalized Unix-style line endings.           |
+| `$watch(path, options)`    | Monitors for real-time changes using high-performance Go engine.    |
+| `$watchContent(p, opts)`   | Deep-monitoring that detects content differences (Diff) in real-time. |
+| `$stream(path, [opts])`    | Streams large files in chunks without loading them into memory.       |
+| `$batchProcess(dir, proc)` | Applies a transformation function to all files in a directory tree.   |
+| `$backup(path, [suffix])`  | Creates a backup copy of a file or directory.                         |
+| `$restore(path, [suffix])` | Restores an item from its backup copy.                                |
+
+---
+
+## Archiving & Compression (High Performance)
+
+XyPriss provides a native bridge to optimized compression engines. These methods are significantly faster than Node.js native `zlib` for large datasets and handle directory structures via TAR.
+
+| Method                   | Description                                            |
+| :----------------------- | :----------------------------------------------------- |
+| `$compress(src, dest)`   | Compresses a single file using Gzip.                   |
+| `$decompress(src, dest)` | Decompresses a Gzip (`.gz`) file.                      |
+| `$tar(dir, output)`      | Bundles a directory into a TAR archive (uncompressed). |
+| `$untar(archive, dest)`  | Extracts a TAR archive to a directory.                 |
+
+> **Pro-Tip**: To compress a directory, use `$tar` followed by `$compress`. To decompress, use `$decompress` followed by `$untar`.
+
+### Multi-Step Compression Example
+
+```typescript
+const projectSrc = "src";
+const archive = "project.tar";
+const compressed = "project.tar.gz";
+
+// 1. Bundle
+__sys__.$tar(projectSrc, archive);
+
+// 2. Compress
+__sys__.$compress(archive, compressed);
+
+console.log("Dossier compressé avec succès !");
+```
+
+---
+
+## Usage Examples
+
+### Initializing and Accessing
+
+The FileSystem API is accessible via the global `__sys__` instance.
+
+```typescript
+import { XyPrissSys } from "./src/sys";
+
+// Accessing the global instance
+const sys = __sys__;
+
+// Resolving a path relative to project root
+const configPath = __sys__.$resolve("config", "server.json");
+```
+
+### Reading and Writing Configuration
+
+```typescript
+const settingsPath = "settings.json";
+
+// Read safely with a default value
+const settings = __sys__.$readJsonSafe(settingsPath, { theme: "dark" });
+
+// Update and write back
+settings.theme = "light";
+__sys__.$writeJson(settingsPath, settings);
+```
+
+### Directory Management
+
+```typescript
+const logsDir = "logs/app";
+
+// Ensure directory exists
+__sys__.$ensureDir(logsDir);
+
+// List all log files
+const logFiles = __sys__.$lsFiles(logsDir);
+
+// Find specific logs recursively
+const errorLogs = __sys__.$findByPattern("logs", /error-.*\.log$/);
+```
+
+### Backup and Restore
+
+```typescript
+const database = "data/main.db";
+
+// Create a backup before a risky operation
+__sys__.$backup(database);
+
+try {
+    // Perform operations...
+} catch (error) {
+    // Restore if something fails
+    __sys__.$restore(database);
+}
+```
+
+## Error Handling
+
+Most methods throw standard Node.js errors (e.g., `ENOENT` if a file is missing). It is recommended to use `$exists()` or `$readJsonSafe()` when dealing with optional files to avoid unnecessary try-catch blocks.
+
+## Performance Considerations
+
+The majority of these methods are synchronous to provide a straightforward, procedural API suitable for configuration and initialization tasks. For high-throughput I/O operations in a production request-response cycle, consider the performance implications of synchronous calls.
+

package/docs/features/xfpm.md

@@ -0,0 +1,157 @@
+# XFPM: XyPriss Fast Package Manager 🕶️
+
+XFPM is the high-performance package manager and CLI tool for the XyPriss ecosystem, written in Rust. It serves as the official successor to the previous Go-based CLI, offering ultra-fast dependency resolution, a unique "Matrix-style" terminal interface, and deep integration with XyPriss projects.
+
+## Key Features
+
+- **Blazing Fast**: Engineered in Rust for maximum performance.
+- **Matrix-Style UI**: Technical, professional, and consistent terminal feedback with hexadecimal pulses and zero emojis.
+- **Strict Isolation**: Implementation of a virtual store for dependency isolation (similar to pnpm).
+- **Neural Graph Resolution**: Advanced dependency resolution engine that maps your project's neural graph.
+- **Global & Local Support**: Manage packages globally or locally with ease.
+- **Legacy Compatibility**: Full support for existing npm/package.json ecosystems.
+
+## OS & Architecture Support
+
+XFPM is designed for universal high-performance execution.
+
+| OS          | Architecture            | Status           |
+| ----------- | ----------------------- | ---------------- |
+| **Linux**   | x86_64 (AMD64)          | ✅ Supported     |
+| **Linux**   | aarch64 (ARM64)         | ✅ Supported     |
+| **Windows** | x86_64 (AMD64)          | ✅ Supported     |
+| **Windows** | aarch64 (ARM64)         | ✅ Supported     |
+| **macOS**   | x86_64 (Intel)          | 🛠️ Source-only\* |
+| **macOS**   | aarch64 (Apple Silicon) | 🛠️ Source-only\* |
+
+> \* **Note**: macOS binaries are currently provided via source builds or dedicated Apple-hosted CI. Direct cross-compilation for Darwin targets from Linux is ongoing.
+
+> **Future Guarantee**: Nehonix™ is committed to expanding support for emerging architectures, including RISC-V and specialized edge computing platforms.
+
+## Installation
+
+XFPM is now distributed via the official unified installer. For complete platform-specific instructions, please refer to the [**Installation Guide**](./INSTALLATION.md).
+
+### Unix/macOS
+
+```bash
+curl -sL https://xypriss.nehonix.com/install.js | node
+```
+
+### Windows
+
+```bash
+Invoke-RestMethod -Uri "https://xypriss.nehonix.com/install.js" -UseBasicParsing | node
+
+# or
+irm https://xypriss.nehonix.com/install.js | node
+```
+
+### Uninstallation
+
+To remove the engine:
+
+```bash
+curl -sL https://xypriss.nehonix.com/install.js | node - uninstall
+```
+
+_Note: The installer automatically handles architecture detection and system PATH configuration._
+
+<!--
+## Command Reference
+
+> **Note:** `xyp` and `xfpm` are aliases for the same tool. You can use them interchangeably in all commands. -->
+
+### `init` - Initialize Project
+
+Creates a new XyPriss project with interactive or flag-based configuration.
+
+```bash
+xyp init [options]
+```
+
+**Options:**
+
+- `-n, --name <string>`: Project name
+- `--desc <string>`: Project description
+- `--lang <string>`: Language (ts/js)
+- `--port <number>`: Default server port
+- `--author <string>`: Author name
+- `--alias <string>`: Application alias
+
+### `install` - Manage Dependencies
+
+Installs packages or synchronizes the current project.
+**Aliases:** `i`, `add`
+
+```bash
+# Install everything from package.json
+xfpm i
+
+# Add packages
+xfpm add <package...> [flags]
+```
+
+**Flags:**
+
+- `-D, --dev`: Save to `devDependencies`
+- `-O, --optional`: Save to `optionalDependencies`
+- `-P, --peer`: Save to `peerDependencies`
+- `-E, --exact`: Install exact version (no `^`)
+- `-g, --global`: Install globally
+    <!-- - `--npm`: Force npm mode compatibility -->
+- `--retries <number>`: Network retry attempts (default: 3)
+
+### `run` - Execute Scripts
+
+Runs a project script or a file using the optimized runtime.
+**Aliases:** `r`, `test`, `build`
+
+```bash
+# Intelligent Default (runs 'dev' script)
+xfpm run
+
+# Run specific script
+xfpm run build
+xfpm build        # Shorthand alias
+
+# Run a file directly
+xfpm run scripts/seed.ts
+```
+
+### `exec` - Binary Execution
+
+Execute a command from `node_modules/.bin` (similar to `npx` or `bun x`).
+**Alias:** `--`
+
+```bash
+# Syntax
+xfpm exec <command> [args...]
+
+# Shorthand usage
+xfpm -- prisma generate
+xfpm -- tsc --noEmit
+```
+
+### `start` - Development Server
+
+Starts the project in development mode (alias for `xyp run dev`).
+**Alias:** `dev`
+
+```bash
+xfpm dev
+```
+
+### `uninstall` - Remove Packages
+
+Removes dependencies from the project.
+**Aliases:** `un`, `rm`, `remove`
+
+```bash
+xfpm rm <package...> [flags]
+```
+
+**Flags:**
+
+- `-g, --global`: Uninstall globally
+