fullnative 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-14
+
+### Added
+
+- `File` class: read, write, JSON, hash, streams, copy, move, rename, replace, replaceMany, permissions, truncate, touch.
+- `Folder` class: list, walk, walkIter, walkFilesIter, tree, find, matchFiles, watch, copy, move, rename, create, delete, clear.
+- `Process` facade: run, output, shell, spawn, spawnWith, spawnScript, exists, which.
+- `Command` builder: withArgs, in, withEnv, withTimeout, withInput, throwOnError, run, output, spawn.
+- `LiveProcess` handle: stdin/stdout/stderr, kill, forceKill, wait, onOutput, onStdout, onStderr, onExit, elapsed, stopped.
+- `Result` class: stdout, stderr, output, lines, json, ok, failed, exitCode, signal, throwIfFailed.
+- `ProcessError` class: structured error with command, args, kind, exitCode, signal, stderr, cause.
+- `Shell` session: run, $ tagged template, pipe, chain, ifOk, ifFail, bg, jobs registry, killAll, cd, set/unset, alias/unalias, history.
+- `Job` class: name, autoRestart, restartCount, onRestart, kill, wait, result, full LiveProcess forwarding.
+- `env` module: load (with `${VAR}` interpolation via `util.parseEnv`), get, require.
+- 150 tests covering all modules.
+- JSDoc in Spanish across all public APIs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeltri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# fullnative
+
+TypeScript toolchain for Node.js scripting — files, folders, processes, and shell sessions with a clean, object-oriented API.
+
+## Why
+
+Node's built-in modules are powerful but verbose. `fullnative` wraps them in simple objects that are pleasant to use in scripts, CLIs, and build tools — no callbacks, no boilerplate, just objects.
+
+## Install
+
+```bash
+pnpm add fullnative
+```
+
+## Quick start
+
+```ts
+import { File, Folder, Process, Shell } from "fullnative";
+```
+
+### File
+
+```ts
+const config = new File("./config.json");
+
+await config.writeJson({ port: 3000 });
+const { port } = await config.readJson<{ port: number }>();
+
+await config.replace("v1.0.0", "v2.0.0");
+const hash = await config.hash("sha256");
+await config.copyTo("./backup/config.json");
+```
+
+### Folder
+
+```ts
+const project = new Folder("./my-app");
+await project.ensure();
+
+const tsFiles = await project.listByExt("ts");
+const entry = await project.find("index.ts");
+const tree = await project.tree(); // ASCII tree visualization
+await project.copyTo("./backup/my-app");
+```
+
+### Process
+
+```ts
+const proc = new Process();
+
+const result = await proc.run("git", "log", "--oneline");
+console.log(result.stdout);
+console.log(result.ok);     // true if exitCode === 0
+console.log(result.lines);  // stdout split into lines
+
+// Builder API
+const out = await proc
+  .cmd("git")
+  .withArgs("rev-parse", "--abbrev-ref", "HEAD")
+  .in("/my/repo")
+  .output();
+
+// Interactive
+const node = proc.spawn("node", "-i");
+node.sendLine("1 + 1");
+node.endInput();
+const res = await node.wait();
+
+// Check if a binary exists
+if (await proc.exists("docker")) {
+  await proc.run("docker", "compose", "up", "-d");
+}
+```
+
+### Shell
+
+```ts
+const sh = new Shell({ cwd: "/my/project" });
+
+// Run shell scripts
+await sh.run("npm install && npm run build");
+
+// Tagged template with safe quoting
+const branch = "main";
+await sh.$`git push origin ${branch}`;
+
+// Pipeline
+const errors = await sh.pipe("cat log.txt", "grep ERROR", "wc -l");
+
+// Chain (stop on error)
+const results = await sh.chain("npm run lint", "npm run build", "npm test");
+const allOk = results.every((r) => r.ok);
+
+// Conditionals
+await sh.ifOk("npm test", "npm run deploy");
+```
+
+### Background jobs
+
+```ts
+const sh = new Shell();
+
+const dev = sh.bg("npm run dev", { name: "dev" });
+dev.onOutput((chunk) => process.stdout.write(chunk));
+
+const server = sh.bg("npm run serve", {
+  name: "server",
+  autoRestart: true,
+});
+server.onRestart((job) => console.log(`Restarted (${job.restartCount})`));
+
+// Introspect
+console.log(sh.activeJobs.map((j) => j.name));
+
+// Clean up everything
+sh.killAll();
+```
+
+### Error handling
+
+```ts
+import { ProcessError } from "fullnative";
+
+try {
+  await proc.run("npm", "run", "build").then((r) => r.throwIfFailed());
+} catch (err) {
+  if (err instanceof ProcessError) {
+    console.log(err.command);   // "npm"
+    console.log(err.kind);      // "exit" | "spawn"
+    console.log(err.exitCode);  // 1
+    console.log(err.stderr);    // build error output
+  }
+}
+```
+
+## API
+
+| Class | Description |
+|---|---|
+| `File` | File operations: read, write, JSON, hash, streams, copy, move |
+| `Folder` | Directory operations: list, walk, tree, find, matchFiles, watch, copy, move |
+| `Process` | Execute native commands: run, spawn, shell, exists, which |
+| `Command` | Immutable builder: withArgs, in, withEnv, withTimeout, withInput, throwOnError |
+| `LiveProcess` | Running process: stdin/stdout/stderr, kill, wait, onOutput, elapsed, stopped |
+| `Result` | Finished command: stdout, stderr, json, lines, ok, throwIfFailed |
+| `Shell` | Shell session: run, $, pipe, chain, ifOk, ifFail, bg, jobs, killAll |
+| `Job` | Background process: name, autoRestart, onRestart, kill, wait |
+| `ProcessError` | Structured error: command, kind, exitCode, signal, stderr, cause |
+
+## Development
+
+```bash
+pnpm install
+pnpm test          # run tests
+pnpm run typecheck # type check
+pnpm run build     # compile to dist/
+```
+
+## License
+
+MIT

package/dist/core/env/env.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Carga un archivo `.env`, interpola referencias `${VAR}` y las mergea a
+ * `process.env` **sin pisar** variables que ya estén seteadas en el entorno
+ * real. El entorno real siempre tiene prioridad sobre el archivo.
+ *
+ * El parseo se realiza con `util.parseEnv` de Node.js. Los valores `undefined`
+ * resultantes del parseo se descartan antes de interpolar.
+ *
+ * @param path Ruta al archivo `.env` (default `".env"`)
+ * @returns Nada; muta `process.env` como efecto secundario
+ * @throws {Error} Si el archivo no existe (ENOENT) u otro error de lectura
+ */
+export declare function load(envPath?: string): Promise<void>;
+/**
+ * Devuelve el valor de una env var, o `undefined` si no existe.
+ * @param key Nombre de la variable
+ * @returns El valor o `undefined`
+ */
+export declare function get(key: string): string | undefined;
+/**
+ * Devuelve el valor de una env var, o `fallback` si no existe.
+ * @param key Nombre de la variable
+ * @param fallback Valor a retornar si la variable no existe
+ * @returns El valor o el fallback
+ */
+export declare function get(key: string, fallback: string): string;
+/**
+ * Devuelve el valor de una env var, o lanza `Error` si no existe.
+ * @param key Nombre de la variable
+ * @returns El valor
+ * @throws {Error} Si la variable no existe, con un mensaje que incluye el nombre de la key
+ */
+export declare function require(key: string): string;
+//# sourceMappingURL=env.d.ts.map

package/dist/core/env/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/core/env/env.ts"],"names":[],"mappings":"AA4FA;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CAAC,OAAO,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAY1D;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAErD;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;AAgB3D;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM3C"}

package/dist/core/env/env.js

@@ -0,0 +1,134 @@
+import { parseEnv } from "node:util";
+import { readFile } from "node:fs/promises";
+/**
+ * Expresión regular global que captura referencias de interpolación del tipo
+ * `${VAR}`. El identificador capturado debe comenzar con una letra o `_` y
+ * contener solo caracteres alfanuméricos o `_`.
+ */
+const REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/**
+ * Resuelve referencias `${VAR}` dentro de los valores de un objeto de variables.
+ *
+ * - Busca el valor en el propio objeto primero, luego en `process.env`.
+ * - Si no se encuentra en ninguno, reemplaza por string vacío.
+ * - Repite pases hasta que no haya cambios entre un pase y el siguiente
+ *   (soporta referencias encadenadas: A depende de B, B depende de C).
+ * - **Límite duro de `maxPasses` (default 5)**: corta referencias circulares
+ *   (`A=${B}`, `B=${A}`) sin colgar el proceso. Al llegar al límite, devuelve
+ *   el resultado tal como quedó — los `${...}` sin resolver sobreviven.
+ *   Es una decisión de "mejor esfuerzo".
+ *
+ * La comparación entre pases se hace con `JSON.stringify` (no con regex
+ * stateful) para evitar falsos negativos por `lastIndex`.
+ *
+ * @param vars Objeto de variables a interpolar
+ * @param maxPasses Número máximo de pases de resolución (default 5)
+ * @returns Un nuevo objeto con las referencias `${VAR}` resueltas (de forma
+ *   "mejor esfuerzo"; las no resolubles sobreviven literales)
+ */
+function interpolate(vars, maxPasses = 5) {
+    let current = vars;
+    /**
+     * Resuelve todas las referencias `${VAR}` de un valor individual.
+     *
+     * Para cada referencia, busca primero en el objeto `current` (resultado
+     * parcial del pase actual) y luego en `process.env`. Si no se encuentra en
+     * ninguno, reemplaza por string vacío.
+     *
+     * @param value Cadena que puede contener cero o más referencias `${VAR}`
+     * @returns El valor con todas las referencias resolubles reemplazadas
+     */
+    const resolveValue = (value) => value.replace(REF, (_, name) => {
+        const found = current[name] ?? process.env[name] ?? "";
+        return found;
+    });
+    /**
+     * Ejecuta un único pase de resolución sobre todo el objeto de variables,
+     * aplicando `resolveValue` a cada clave.
+     *
+     * @param obj Objeto de variables a resolver en este pase
+     * @returns Un nuevo objeto con los valores tras aplicar `resolveValue`
+     */
+    const resolvePass = (obj) => {
+        const next = {};
+        for (const key of Object.keys(obj)) {
+            next[key] = resolveValue(obj[key]);
+        }
+        return next;
+    };
+    /**
+     * Bucle recursivo que aplica `resolvePass` repetidamente hasta que no haya
+     * cambios entre pases (referencias encadenadas resueltas) o hasta alcanzar
+     * `maxPasses` (corta referencias circulares sin colgar el proceso).
+     *
+     * La comparación entre pases se hace con `JSON.stringify` (no con el estado
+     * interno de la regex) para evitar falsos negativos por `lastIndex`.
+     *
+     * @param acc Acumulador de variables resueltas hasta el pase actual
+     * @param pass Número de pase actual (comienza en 0)
+     * @returns El objeto de variables tras detenerse (por convergencia o límite)
+     */
+    const loop = (acc, pass) => {
+        if (pass >= maxPasses)
+            return acc;
+        const next = resolvePass(acc);
+        if (JSON.stringify(next) === JSON.stringify(acc))
+            return next;
+        return loop(next, pass + 1);
+    };
+    return loop(current, 0);
+}
+/**
+ * Carga un archivo `.env`, interpola referencias `${VAR}` y las mergea a
+ * `process.env` **sin pisar** variables que ya estén seteadas en el entorno
+ * real. El entorno real siempre tiene prioridad sobre el archivo.
+ *
+ * El parseo se realiza con `util.parseEnv` de Node.js. Los valores `undefined`
+ * resultantes del parseo se descartan antes de interpolar.
+ *
+ * @param path Ruta al archivo `.env` (default `".env"`)
+ * @returns Nada; muta `process.env` como efecto secundario
+ * @throws {Error} Si el archivo no existe (ENOENT) u otro error de lectura
+ */
+export async function load(envPath = ".env") {
+    const raw = await readFile(envPath, "utf8");
+    const parsed = parseEnv(raw);
+    const clean = {};
+    for (const key of Object.keys(parsed)) {
+        const value = parsed[key];
+        if (value !== undefined)
+            clean[key] = value;
+    }
+    const resolved = interpolate(clean);
+    for (const key of Object.keys(resolved)) {
+        process.env[key] ??= resolved[key];
+    }
+}
+/**
+ * Implementación de `get`. Devuelve el valor de una env var, o `fallback`
+ * (que por defecto es `undefined`) si la variable no existe en `process.env`.
+ *
+ * @param key Nombre de la variable
+ * @param fallback Valor a retornar si la variable no existe (default `undefined`)
+ * @returns El valor de la variable, el fallback, o `undefined`
+ */
+export function get(key, fallback) {
+    const value = process.env[key];
+    if (value === undefined)
+        return fallback;
+    return value;
+}
+/**
+ * Devuelve el valor de una env var, o lanza `Error` si no existe.
+ * @param key Nombre de la variable
+ * @returns El valor
+ * @throws {Error} Si la variable no existe, con un mensaje que incluye el nombre de la key
+ */
+export function require(key) {
+    const value = process.env[key];
+    if (value === undefined) {
+        throw new Error(`Missing required environment variable: ${key}`);
+    }
+    return value;
+}
+//# sourceMappingURL=env.js.map

package/dist/core/env/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/core/env/env.ts"],"names":[],"mappings":"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"}

package/dist/core/env/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Punto de entrada del módulo de variables de entorno.
+ *
+ * Reexporta la API pública para cargar, leer y exigir variables de entorno:
+ * - `load(path?)`: carga un archivo `.env` y lo mergea a `process.env`.
+ * - `get(key)` / `get(key, fallback)`: lee una variable con o sin valor por defecto.
+ * - `require(key)`: lee una variable o lanza si no existe.
+ */
+export { load, get, require } from "./env.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/env/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/env/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC"}

package/dist/core/env/index.js

@@ -0,0 +1,10 @@
+/**
+ * Punto de entrada del módulo de variables de entorno.
+ *
+ * Reexporta la API pública para cargar, leer y exigir variables de entorno:
+ * - `load(path?)`: carga un archivo `.env` y lo mergea a `process.env`.
+ * - `get(key)` / `get(key, fallback)`: lee una variable con o sin valor por defecto.
+ * - `require(key)`: lee una variable o lanza si no existe.
+ */
+export { load, get, require } from "./env.js";
+//# sourceMappingURL=index.js.map

package/dist/core/env/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/env/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC"}

package/dist/core/file/File.d.ts

@@ -0,0 +1,246 @@
+import { type Stats } from "node:fs";
+import { Readable, Writable } from "node:stream";
+/**
+ * Representa un archivo individual accesible mediante una API sencilla.
+ * Las operaciones son perezosas: leen/escriben en disco solo cuando se invocan.
+ */
+export declare class File {
+    path: string;
+    constructor(path: string);
+    /** Nombre del archivo incluyendo su extensión. */
+    get name(): string;
+    /** Nombre del archivo sin la extensión. */
+    get baseName(): string;
+    /** Extensión del archivo sin el punto inicial (ej. `txt`, `json`). */
+    get ext(): string;
+    /** Ruta absoluta del directorio que contiene al archivo. */
+    get dirname(): string;
+    /**
+     * Tipo MIME inferido a partir de la extensión del archivo.
+     * Devuelve `application/octet-stream` para extensiones desconocidas.
+     */
+    get mimeType(): string;
+    /**
+     * Verifica si el archivo existe en disco.
+     * @returns `true` si el archivo existe, `false` en caso contrario.
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Obtiene los metadatos (stat) del archivo en disco.
+     * @returns Una promesa con el objeto `Stats` de Node.js.
+     */
+    stat(): Promise<Stats>;
+    /**
+     * Obtiene el tamaño del archivo en bytes.
+     * @returns Tamaño en bytes.
+     */
+    size(): Promise<number>;
+    /**
+     * Indica si el archivo está vacío (0 bytes).
+     * @returns `true` si el tamaño es 0, `false` en caso contrario.
+     */
+    isEmpty(): Promise<boolean>;
+    /**
+     * Obtiene la fecha de creación del archivo.
+     * @returns La fecha (`birthtime`) de creación.
+     */
+    createdAt(): Promise<Date>;
+    /**
+     * Obtiene la fecha de última modificación del archivo.
+     * @returns La fecha (`mtime`) de última modificación.
+     */
+    modifiedAt(): Promise<Date>;
+    /**
+     * Obtiene la fecha de último acceso al archivo.
+     * @returns La fecha (`atime`) de último acceso.
+     */
+    accessedAt(): Promise<Date>;
+    /**
+     * Lee el contenido del archivo como texto.
+     * @param encoding Codificación a utilizar (por defecto `utf8`).
+     * @returns El contenido del archivo como cadena.
+     */
+    read(encoding?: BufferEncoding): Promise<string>;
+    /**
+     * Lee el contenido del archivo como `Buffer` binario.
+     * @returns Un `Buffer` con los bytes del archivo.
+     */
+    readBuffer(): Promise<Buffer>;
+    /**
+     * Lee y parsea el contenido del archivo como JSON.
+     * @returns El valor parseado, tipado genéricamente como `T`.
+     */
+    readJson<T = unknown>(): Promise<T>;
+    /**
+     * Lee el contenido del archivo y lo divide en líneas.
+     * @returns Un arreglo de cadenas, una por línea.
+     */
+    readLines(): Promise<string[]>;
+    /**
+     * Escribe datos en el archivo. Crea el directorio padre automáticamente
+     * si no existe (comportamiento intencional para que el caller no necesite
+     * un `mkdir -p` previo explícito). Sobrescribe el contenido existente.
+     * @param data Contenido a escribir (cadena, `Buffer` o `Uint8Array`).
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    write(data: string | Buffer | Uint8Array): Promise<void>;
+    /**
+     * Serializa `data` a JSON y lo escribe en el archivo (creando el directorio padre).
+     * @param data Valor a serializar.
+     * @param pretty Si `true` (por defecto), indenta con 2 espacios; si `false`, compacto.
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    writeJson(data: unknown, pretty?: boolean): Promise<void>;
+    /**
+     * Escribe un arreglo de líneas en el archivo, unidas por `\n`.
+     * Crea el directorio padre automáticamente.
+     * @param lines Líneas a escribir.
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    writeLines(lines: readonly string[]): Promise<void>;
+    /**
+     * Añade datos al final del archivo. Crea el directorio padre automáticamente
+     * si no existe.
+     * @param data Contenido a añadir (cadena, `Buffer` o `Uint8Array`).
+     * @returns Promesa que se resuelve cuando la operación termina.
+     */
+    append(data: string | Buffer | Uint8Array): Promise<void>;
+    /**
+     * Añade una línea al final del archivo, seguida de un salto de línea.
+     * Crea el directorio padre automáticamente.
+     * @param line Texto de la línea a añadir.
+     * @returns Promesa que se resuelve cuando la operación termina.
+     */
+    appendLine(line: string): Promise<void>;
+    /**
+     * Prependa datos al inicio del archivo, leyendo el contenido existente y
+     * reescribiendo el archivo completo. Crea el directorio padre automáticamente.
+     * @param data Contenido a prepend (cadena, `Buffer` o `Uint8Array`).
+     * @returns Promesa que se resuelve cuando la operación termina.
+     */
+    prepend(data: string | Buffer | Uint8Array): Promise<void>;
+    /**
+     * Inserta una línea en una posición específica del archivo (por índice de línea).
+     * El índice se ajusta dentro de los límites válidos.
+     * @param lineIndex Índice (base 0) donde insertar la línea.
+     * @param content Texto de la línea a insertar.
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    insertAt(lineIndex: number, content: string): Promise<void>;
+    /**
+     * Reemplaza la primera ocurrencia de `search` por `replacement` en el contenido
+     * del archivo y lo reescribe.
+     * @param search Cadena o expresión regular a buscar.
+     * @param replacement Texto de reemplazo.
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    replace(search: string | RegExp, replacement: string): Promise<void>;
+    /**
+     * Aplica múltiples reemplazos en secuencia sobre el contenido del archivo.
+     * Renombrado desde `replaceAll()` para evitar colisión con el método nativo
+     * de cadenas. Cada reemplazo se aplica al resultado del anterior, en orden.
+     * @param replacements Arreglo de pares `{ search, replacement }` aplicados en orden.
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    replaceMany(replacements: readonly {
+        search: string | RegExp;
+        replacement: string;
+    }[]): Promise<void>;
+    /**
+     * Trunca el archivo al tamaño indicado.
+     * @param size Tamaño en bytes (por defecto 0, vacía el archivo).
+     * @returns Promesa que se resuelve al completar el truncado.
+     */
+    truncate(size?: number): Promise<void>;
+    /**
+     * Actualiza la fecha de acceso/modificación al momento actual, o crea el
+     * archivo vacío si no existe.
+     * @returns Promesa que se resuelve al completar la operación.
+     */
+    touch(): Promise<void>;
+    /**
+     * Cambia los permisos del archivo.
+     * @param mode Máscode de permisos numérico (ej. `0o644`).
+     * @returns Promesa que se resuelve al completar el cambio.
+     */
+    chmod(mode: number): Promise<void>;
+    /**
+     * Establece el archivo como solo lectura (modo `0o444`).
+     * @returns Promesa que se resuelve al completar el cambio.
+     */
+    setReadOnly(): Promise<void>;
+    /**
+     * Establece el archivo como lectura/escritura (modo `0o644`).
+     * @returns Promesa que se resuelve al completar el cambio.
+     */
+    setReadWrite(): Promise<void>;
+    /**
+     * Calcula el hash criptográfico del contenido del archivo.
+     * @param algo Algoritmo de hash (por defecto `sha256`).
+     * @returns El hash en formato hexadecimal.
+     */
+    hash(algo?: string): Promise<string>;
+    /**
+     * Compara este archivo con otro por contenido (usando hash).
+     * @param other Otro `File` a comparar.
+     * @returns `true` si ambos existen y su hash coincide, `false` en caso contrario.
+     */
+    equals(other: File): Promise<boolean>;
+    /**
+     * Compara el contenido del archivo con una cadena o `Buffer` dada.
+     * @param content Contenido a comparar.
+     * @returns `true` si el contenido coincide, `false` si no existe o difiere.
+     */
+    contentEquals(content: string | Buffer): Promise<boolean>;
+    /**
+     * Crea un stream de lectura para el archivo.
+     * @returns Un `Readable` para consumir el contenido en streaming.
+     */
+    readStream(): Readable;
+    /**
+     * Crea un stream de escritura hacia el archivo.
+     * @returns Un `Writable` para escribir contenido en streaming.
+     */
+    writeStream(): Writable;
+    /**
+     * Elimina el archivo del disco.
+     * @returns `true` si el archivo existía y fue eliminado, `false` si no existía.
+     */
+    delete(): Promise<boolean>;
+    /**
+     * Copia este archivo a una ruta destino. Crea el directorio padre del destino
+     * automáticamente si no existe.
+     * @param dest Ruta absoluta del archivo destino.
+     * @returns Una **nueva** instancia de `File` apuntando al destino.
+     */
+    copyTo(dest: string): Promise<File>;
+    /**
+     * Copia este archivo dentro de un directorio, conservando su nombre.
+     * @param dir Ruta del directorio destino.
+     * @returns Una **nueva** instancia de `File` apuntando a `dir/name`.
+     */
+    copyInto(dir: string): Promise<File>;
+    /**
+     * Mueve este archivo a una ruta destino. Crea el directorio padre del destino
+     * automáticamente si no existe. **Muta `this.path`** al nuevo destino y
+     * devuelve `this` para encadenamiento.
+     * @param dest Ruta absoluta del archivo destino.
+     * @returns La misma instancia (`this`) con `path` actualizado.
+     */
+    moveTo(dest: string): Promise<this>;
+    /**
+     * Mueve este archivo dentro de un directorio, conservando su nombre.
+     * **Muta `this.path`** y devuelve `this`.
+     * @param dir Ruta del directorio destino.
+     * @returns La misma instancia (`this`) con `path` actualizado.
+     */
+    moveInto(dir: string): Promise<this>;
+    /**
+     * Renombra este archivo dentro de su mismo directorio.
+     * **Muta `this.path`** y devuelve `this`.
+     * @param newName Nuevo nombre del archivo (sin ruta).
+     * @returns La misma instancia (`this`) con `path` actualizado.
+     */
+    rename(newName: string): Promise<this>;
+}
+//# sourceMappingURL=File.d.ts.map

package/dist/core/file/File.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"File.d.ts","sourceRoot":"","sources":["../../../src/core/file/File.ts"],"names":[],"mappings":"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"}