fullnative 0.2.1 → 1.0.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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).
 
+## [1.0.0] - 2026-10-05
+
+First stable release. The public API is now frozen: from here on, breaking changes require a major version.
+
+### Breaking changes
+
+- **`File.moveTo`, `File.moveInto`, `File.rename`, `Folder.moveTo`, `Folder.moveInto`, `Folder.rename` no longer mutate the instance.** They move/rename the file or folder on disk and return a **new** instance (`Promise<File>` / `Promise<Folder>`) pointing at the new path; the original instance keeps its old path. This unifies their semantics with `copyTo`/`copyInto`, which already returned new instances, and removes the aliasing bugs caused by silent `this.path` mutation. (`File.moveTo`/`rename` returned `this`; `Folder.moveTo`/`rename` returned `this`.)
+- **`Result.lines` now returns all lines** of stdout as `stdout.split(/\r?\n/)`, **including empty lines** — an output ending with a newline produces a final empty line. The previous behavior (empty lines filtered out) is still available in the new `Result.nonEmptyLines` getter.
+- **`ShellConfig.shell` was removed.** It was dead configuration: the actual shell is chosen internally by the library (`/bin/sh` on Unix, `cmd.exe` on Windows). Remove the field from your `Shell` options — there is no replacement.
+
+### Added
+
+- `File.absolute` getter: absolute path resolved against `process.cwd()` (parity with `Folder.absolute`).
+- `Result.nonEmptyLines` getter: stdout split into lines with empty lines filtered out (the pre-1.0 `lines` behavior).
+- `Command.withAbort(signal)`: immutable builder method that associates an `AbortSignal` with the command. On abort the process is killed with `SIGTERM`, `LiveProcess` ends with `stopped === true`, and `wait()` resolves with a normal `Result` (never rejects with `AbortError`). The signal is deliberately not passed to the native `spawn()`, which would emit an `error` event with `AbortError`.
+- `env.load()` options: accepts `string | { path?: string; override?: boolean }` (`LoadOptions`, default `".env"`). With `override: true` the file's variables overwrite existing `process.env` entries; by default the real environment always wins (unchanged semantics). The string signature `load("./file.env")` keeps working.
+- `env.load()` now returns `Promise<Record<string, string>>` with the variables actually applied by the call: in normal mode only the keys that weren't already in `process.env`, with `override: true` every resolved variable.
+- New `utils` module: `sleep(ms)` (promise-based pause), `timeout(promise, ms, message?)` (deadline for any promise, rejects with the new `TimeoutError` class — `name === "TimeoutError"`, default message includes the ms), and `tempDir({ prefix?, keep? })` returning a `TempDir` instance (`extends Folder`, with `dispose()`); created with `fs.mkdtemp` under `os.tmpdir()` (default prefix `"fullnative-"`), auto-removed at process exit via a single global `exit` hook unless `keep: true`. Types `LoadOptions` and `TempDirOptions` are exported.
+
+### Fixed
+
+- `Folder.delete(recursive)` uses `fs.rm(path, { recursive, force: true })` instead of the deprecated `fs.rmdir` (`DEP0147`, deprecated since Node 22 and slated for removal). Return semantics unchanged: `true` if it existed and was deleted.
+- `Folder.tree()` rendering: subdirectories were painted twice, indentation was duplicated after each level, and non-last-child directories were forced to the `└──` connector. Now every entry is rendered exactly once, with correct `├──`/`└──` connectors and child prefixes `│   ` (not-last) / `    ` (last).
+- `Shell.cd(target)` resolves relative paths against the session's current cwd (`path.resolve`) and adopts absolute paths as-is. Before, the literal string was stored, producing a silently invalid `cwd` that exploded later on the first command.
+- `Shell.pipe()` hardened: validates that `stdout`/`stdin` exist at every hop (clear `TypeError` when missing) and attaches safe error listeners to piped streams so stream errors (`EPIPE`, e.g. when an intermediate command dies) resolve as a failed `Result` instead of crashing the host process with unhandled errors.
+
+### Documented
+
+- The `$` tagged template generates POSIX-style quoting (`sh`/`bash`), which is **not** safe for `cmd.exe` on Windows. Windows-safe quoting is a future feature.
+
 ## [0.1.0] - 2026-08-14
 
 ### Added

package/MIGRATION.md

@@ -0,0 +1,161 @@
+# Migration guide: 0.x → 1.0
+
+`fullnative` 1.0 is the first stable release; the public API is frozen from here on. This guide covers the three changes that can actually break your code when upgrading from 0.x, plus the additions that come along for free.
+
+```bash
+npm install fullnative@1.0.0
+# or
+pnpm add fullnative@1.0.0
+```
+
+---
+
+## 1. `moveTo()` / `moveInto()` / `rename()` no longer mutate — they return a new instance
+
+**What changed:** `File.moveTo`, `File.moveInto`, `File.rename`, `Folder.moveTo`, `Folder.moveInto` and `Folder.rename` physically move/rename the file or folder on disk (same as before), but they no longer mutate the instance or return `this`. They return a **new** instance (`Promise<File>` / `Promise<Folder>`) pointing at the new path, while the original instance keeps its old path.
+
+This matches `copyTo()` / `copyInto()`, which already returned a new instance.
+
+**Why:** silently mutating `this.path` made any alias of the same object desynchronize — a `File` passed to a helper could change its path without the caller knowing. Returning a new instance removes that entire class of bugs.
+
+### Before (0.x)
+
+```ts
+const f = new File("./data.txt");
+
+// Code that relied on mutation:
+await f.moveTo("./archive/data.txt");
+console.log(f.path);          // "./archive/data.txt" — mutated!
+await f.rename("data.old");   // also mutated f
+// `f` was the single handle to the moved file
+```
+
+### After (1.0)
+
+```ts
+const f = new File("./data.txt");
+
+const moved = await f.moveTo("./archive/data.txt");
+console.log(f.path);      // "./data.txt" — unchanged
+console.log(moved.path);  // "./archive/data.txt"
+
+const renamed = await moved.rename("data.old");
+// renamed points at "./archive/data.old"; `moved` still points at "./archive/data.txt"
+
+// Use the returned instance for everything that follows:
+const contents = await moved.read();
+```
+
+### How to migrate
+
+- **If you used the return value as `this` for chaining** (`await f.moveTo(x).rename(y)` — no; chained awaits):
+  
+  ```ts
+  // 0.x
+  await file.moveTo("./a");
+  await file.rename("b");   // renamed because `file` had mutated
+
+  // 1.0 — carry the returned instance forward
+  const moved = await file.moveTo("./a");
+  const renamed = await moved.rename("b");
+  ```
+
+- **If you relied on the original instance changing:** replace your old variable with the returned one, or reassign it explicitly:
+
+  ```ts
+  // Keep the same variable name if you want old code to keep working:
+  file = await file.moveTo("./archive/data.txt");
+  ```
+
+The same applies to `Folder`:
+
+```ts
+const project = new Folder("./my-app");
+const moved = await project.moveTo("./archive/my-app");
+await moved.createFile("marker.txt", "ok");  // writes into the moved dir
+```
+
+---
+
+## 2. `Result.lines` now includes empty lines — use `nonEmptyLines` for the old behavior
+
+**What changed:** `Result.lines` is now the plain `String.split(/\r?\n/)` of stdout, **including empty lines**. An output that ends with `\n` — which is the common case — now produces a final empty line in the array.
+
+The old behavior (empty lines filtered out) is still there: use the new **`Result.nonEmptyLines`** getter.
+
+**Why:** a method named `lines` that behaves like `split` should behave like `split`. Silent filtering corrupted cases where empty lines are data (CSVs, logs, blocks separated by blank lines).
+
+### Before (0.x)
+
+```ts
+const result = await proc.run("printf", "a\n\nb\n");
+result.lines;   // ["a", "b"] — empty lines silently filtered
+```
+
+### After (1.0)
+
+```ts
+const result = await proc.run("printf", "a\n\nb\n");
+result.lines;           // ["a", "", "b", ""] — plain split, including the trailing empty line
+result.nonEmptyLines;   // ["a", "b"] — the old filtered behavior
+```
+
+### How to migrate
+
+Search your code for `\.lines` on command results and decide, case by case:
+
+- You were counting on filtered empty lines → switch to `result.nonEmptyLines` (drop-in, same array shape).
+- You want raw lines (e.g. to preserve blank separators or reconstruct the exact output) → keep `result.lines`.
+
+If you never filtered them yourself and just consumed the array, `nonEmptyLines` is almost always what you were implicitly assuming.
+
+---
+
+## 3. Remove `ShellConfig.shell` — it was never used
+
+**What changed:** the `shell` field was removed from the `Shell` constructor options. It was dead configuration: `fullnative` chooses the actual shell internally (`/bin/sh` on Unix, `cmd.exe` on Windows), and no option can change that.
+
+### Before (0.x)
+
+```ts
+// Compiled with a warning at best — the field was never respected
+const sh = new Shell({ cwd: "/my/project", shell: "/bin/bash" });
+```
+
+### After (1.0)
+
+```ts
+// Just remove the field
+const sh = new Shell({ cwd: "/my/project" });
+```
+
+### How to migrate
+
+Delete the property. There is no replacement: if TypeScript was enforcing it, the build itself will point you to every occurrence. Type-checking will catch this one mechanically — `cwd` and `env` remain valid options.
+
+---
+
+## Non-breaking additions in the same release
+
+Everything below is additive — no action needed:
+
+- **`File.absolute`** — absolute path resolved against `process.cwd()` (parity with `Folder.absolute`).
+- **`Result.nonEmptyLines`** — covered above; new getter, no conflicts.
+- **`Command.withAbort(signal)`** — associate an `AbortSignal` with a command; on abort the process is killed with `SIGTERM`, the `LiveProcess` ends with `stopped === true`, and `wait()` resolves with a normal `Result`. The signal is deliberately not passed to the native `spawn()` to avoid a native `AbortError` rejection.
+- **`load()` options and return value** — accepts `string | { path?: string; override?: boolean }` and now returns a `Promise<Record<string, string>>` with the variables actually applied. The string signature `load("./file.env")` and the default semantics (the real environment always wins) are unchanged, so existing calls keep working. Use `override: true` when you want the file to overwrite the environment.
+- **New `utils` module** — `sleep(ms)`, `timeout(promise, ms, message?)` with `TimeoutError`, and `tempDir({ prefix?, keep? })` returning a `TempDir` (extends `Folder`, with `dispose()` and auto-cleanup at process exit unless `keep: true`).
+
+### Behavioral fixes you may notice (no migration needed)
+
+- `Folder.delete(recursive)` now uses `fs.rm` under the hood (the deprecated `fs.rmdir` is gone) — return semantics unchanged.
+- `Folder.tree()` output changed: correct `├──`/`└──` connectors, no duplicated entries or indentation. If you parse tree output, re-verify your parsing.
+- `Shell.cd()` resolves relative targets against the session cwd instead of storing the literal string.
+- `Shell.pipe()` no longer crashes the host process on stream errors (`EPIPE`); a broken pipeline resolves as a failed `Result`.
+
+---
+
+## Questions
+
+- **Do I have to change anything for `load()`?** No — the string signature still works and the default merge semantics did not change. The return value is new information you can start using (or ignore).
+- **Can I keep mutating-style code by reassigning?** Yes: `file = await file.moveTo(dest)` restores the old feel at the cost of one extra assignment. We recommend holding both instances when you need the history.
+- **Is `$` safe on Windows?** The quoting is POSIX-style, which is not safe for `cmd.exe`. Windows-safe quoting is on the roadmap; until then, avoid `$` in Windows scripts.

package/README.md

@@ -1,6 +1,8 @@
-# fullnative
+![logo](/logo.png)
 
-TypeScript toolchain for Node.js — files, folders, processes, shell sessions, and environment variables with a clean, object-oriented API for stateful resources and functional utilities for the rest.
+# Full Native
+
+TypeScript toolchain for Node.js — files, folders, processes, shell sessions, environment variables, and promise utilities with a clean, object-oriented API for stateful resources and functional utilities for the rest.
 
 [![npm](https://img.shields.io/npm/v/fullnative.svg)](https://www.npmjs.com/package/fullnative)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -11,7 +13,8 @@ Node's built-in modules are powerful but verbose. `fullnative` wraps them in sim
 
 - **Zero dependencies** — uses only Node.js built-ins (`fs`, `child_process`, `crypto`, `util.parseEnv`)
 - **Fully typed** — ships with `.d.ts` declarations for every module
-- **Object-oriented for stateful resources** (`File`, `Folder`, `Process`, `Shell` are classes you instantiate and chain), **functional utilities for the rest** (`env` module is plain functions)
+- **Object-oriented for stateful resources** (`File`, `Folder`, `Process`, `Shell` are classes you instantiate and chain), **functional utilities for the rest** (`env` and `utils` modules are plain functions)
+- **Immutable movement semantics** — `moveTo()`, `moveInto()` and `rename()` return a **new** instance pointing at the new path, like `copyTo()`; the original instance never mutates (`File`, `Folder`)
 - **Node.js >= 20.12** — takes advantage of native `util.parseEnv` for `.env` parsing
 - **ESM only** — ships as `"type": "module"` with `import`/`export`. No CJS support.
 
@@ -25,13 +28,15 @@ pnpm add fullnative
 yarn add fullnative
 ```
 
+> **Upgrading from 0.x?** 1.0 is the first stable release and ships intentional breaking changes (immutable `moveTo()`/`rename()`, `Result.lines` split semantics, removed `ShellConfig.shell`). See [MIGRATION.md](./MIGRATION.md) for a step-by-step guide.
+
 ## Quick start
 
 ```ts
-import { File, Folder, Process, Shell, load } from "fullnative";
+import { File, Folder, Process, Shell, load, sleep, tempDir } from "fullnative";
 
 // Load .env variables with ${VAR} interpolation
-await load();
+const applied = await load();   // record of the variables actually applied
 
 // Work with files
 const config = new File("./config.json");
@@ -41,6 +46,11 @@ await config.writeJson({ port: 3000 });
 const proc = new Process();
 const result = await proc.run("git", "log", "--oneline");
 console.log(result.stdout);
+
+// Promise utilities: auto-cleaned temp dir + readable pause
+const tmp = await tempDir();
+await tmp.file("scratch.txt").write("working...");
+await sleep(500);
 ```
 
 ---
@@ -57,7 +67,9 @@ console.log(result.stdout);
 - [Shell](#shell)
 - [Job](#job)
 - [env](#env)
+- [utils](#utils)
 - [API Reference](#api-reference)
+- [Migration guide](./MIGRATION.md)
 - [Requirements](#requirements)
 - [Roadmap](#roadmap)
 
@@ -97,10 +109,13 @@ const hash = await file.hash("sha256");
 const same = await file.equals(new File("./other.txt"));
 const matches = await file.contentEquals("exact content");
 
-// Copy returns a NEW File; move/rename mutate this.path and return this
-const backup = await file.copyTo("./backup/data.txt");  // new File
-await file.moveTo("./archive/data.txt");                 // same instance, path updated
-await file.rename("renamed.txt");                        // same instance, path updated
+// Copy & move return a NEW instance; the original never mutates
+const copy = await file.copyTo("./backup/data.txt");   // new File at "./backup/data.txt"
+const moved = await file.moveTo("./archive/data.txt");  // new File at "./archive/data.txt"
+const renamed = await file.rename("renamed.txt");       // new File at "./archive/renamed.txt"
+const tucked = await file.moveInto("./archive");        // new File at "./archive/data.txt" (keeps name)
+
+// file.path is still "./data.txt" — only the returned instances point elsewhere
 
 // Streams
 const readable = file.readStream();   // Readable stream
@@ -111,6 +126,7 @@ const size = await file.size();           // bytes
 const empty = await file.isEmpty();       // true if 0 bytes
 const exists = await file.exists();
 const stat = await file.stat();            // fs.Stats
+const abs = file.absolute;                 // absolute path resolved against process.cwd()
 
 // Delete
 await file.delete();  // returns true if existed
@@ -118,8 +134,8 @@ await file.delete();  // returns true if existed
 
 **Key behaviors:**
 - `write()`, `append()`, `prepend()` create parent directories automatically.
-- `copyTo()` / `copyInto()` return a **new** `File` instance.
-- `moveTo()` / `moveInto()` / `rename()` mutate `this.path` and return `this` for chaining.
+- `copyTo()`, `copyInto()`, `moveTo()`, `moveInto()` and `rename()` return a **new** `File` instance; the original instance keeps its old path.
+- `absolute` resolves the instance path against `process.cwd()`.
 
 ---
 
@@ -136,7 +152,7 @@ const project = new Folder("./my-app");
 await project.ensure();                  // create if missing
 await project.create();                  // mkdir -p
 await project.clear();                    // empty contents
-await project.delete(true);               // recursive delete
+await project.delete(true);               // recursive delete (fs.rm with force)
 
 // Navigation (returns references, doesn't check existence)
 const entry: File = project.file("index.ts");
@@ -172,19 +188,22 @@ const matched = await project.matchFiles(/\.test\.ts$/); // File[]
 const newFile = await project.createFile("note.txt", "hello");
 const newDir = await project.createDir("utils");
 
-// Copy & move (same semantics as File)
-const copy = await project.copyTo("./backup/my-app");  // new Folder
-await project.moveTo("./archive/my-app");               // same instance
-await project.rename("renamed-app");                    // same instance
+// Copy & move return a NEW instance; the original never mutates
+const copy = await project.copyTo("./backup/my-app");   // new Folder at "./backup/my-app"
+const moved = await project.moveTo("./archive/my-app");  // new Folder at "./archive/my-app"
+const renamed = await project.rename("renamed-app");     // new Folder at "./renamed-app"
+const tucked = await project.moveInto("./archive");      // new Folder at "./archive/my-app" (keeps name)
+
+// project.path is still "./my-app" — only the returned instances point elsewhere
 
 // Tree visualization
 const tree = await project.tree();
 console.log(tree);
-// └── my-app/
-//     ├── index.ts
-//     ├── src/
-//     │   └── utils.ts
-//     └── package.json
+// my-app/
+// ├── index.ts
+// ├── src/
+// │   └── utils.ts
+// └── package.json
 ```
 
 ---
@@ -203,7 +222,8 @@ const result = await proc.run("git", "log", "--oneline");
 console.log(result.stdout);      // captured output
 console.log(result.ok);           // true if exitCode === 0
 console.log(result.exitCode);     // 0
-console.log(result.lines);        // stdout split into lines (empty lines filtered)
+console.log(result.lines);        // stdout split into lines (includes empty lines)
+console.log(result.nonEmptyLines); // stdout split into lines (empty lines filtered)
 console.log(result.durationMs);   // execution time in ms
 
 // Get stdout only (trimmed)
@@ -232,6 +252,7 @@ const cmd = proc
   .in("/my/project")                        // set cwd
   .withEnv({ CI: "true" })                  // merge env vars
   .withTimeout(30000)                       // kill after 30s
+  .withAbort(controller.signal)              // kill with SIGTERM when the signal aborts
   .withInput("stdin data\n")                 // pipe to stdin
   .throwOnError();                           // reject on non-zero exit
 
@@ -240,6 +261,11 @@ const out = await cmd.output();              // stdout.trim()
 const handle = cmd.spawn();                  // returns LiveProcess
 ```
 
+`withAbort(signal)` associates an `AbortSignal` with the command — the same primitive used by `fetch`, `fs` and timers, so it integrates with any framework that already uses `AbortController`. Notes:
+
+- The signal is **not** passed to the native `spawn()`. On abort, the process is killed with `SIGTERM`, the `LiveProcess` ends with `stopped === true`, and `wait()` resolves with a normal `Result` — it never rejects with an `AbortError`.
+- `withTimeout(ms)` kills the process with `SIGTERM` after the deadline, exactly like before.
+
 ### LiveProcess (interactive handle)
 
 A running process you can interact with in real time.
@@ -285,7 +311,8 @@ result.exitCode;     // 0
 result.ok;           // true
 result.failed;       // false
 result.output;       // stdout + stderr, trimmed
-result.lines;        // ["{\"ok\":true}"]
+result.lines;        // ['{"ok":true}', ''] — plain split, includes the empty trailing line
+result.nonEmptyLines; // ['{"ok":true}'] — empty lines filtered out
 result.durationMs;   // 12
 result.json();       // { ok: true } — parses stdout as JSON
 result.json<{ ok: boolean }>();  // typed
@@ -294,6 +321,8 @@ result.json<{ ok: boolean }>();  // typed
 result.throwIfFailed();  // throws ProcessError if exitCode !== 0, returns this if ok
 ```
 
+`lines` is a plain `String.split(/\r?\n/)` of stdout, so it includes empty lines — an output that ends with a newline produces a final empty line. For the old filtered behavior, use `nonEmptyLines`.
+
 ---
 
 ## ProcessError
@@ -331,6 +360,8 @@ The `kind` field distinguishes between:
 
 A shell session with state (cwd, env, aliases, history) that delegates to `Process` internally.
 
+The config object accepts only `cwd` and `env` — the shell binary itself is chosen internally (`/bin/sh` on Unix, `cmd.exe` on Windows), so there is nothing to configure.
+
 ```ts
 import { Shell } from "fullnative";
 
@@ -341,7 +372,8 @@ const result = await sh.run("npm install && npm run build");
 console.log(result.ok);
 
 // Change directory
-sh.cd("./src");
+sh.cd("./src");            // relative paths resolve against the session cwd
+sh.cd("/other/project");   // absolute paths are adopted as-is
 console.log(sh.cwd);  // "/my/project/src"
 
 // Environment variables
@@ -363,6 +395,8 @@ sh.clearHistory();
 
 Interpolates values with automatic shell quoting. Strings with special characters are escaped; arrays expand to separate arguments.
 
+> **Windows limitation:** the quoting style is POSIX (`sh`/`bash`), so the generated scripts are **not** safe for `cmd.exe` on Windows, where escaping rules differ.
+
 ```ts
 const branch = "main";
 const files = ["a.ts", "b.ts"];
@@ -382,6 +416,8 @@ const result = await sh.pipe("cat log.txt", "grep ERROR", "wc -l");
 console.log(result.stdout.trim());  // error count
 ```
 
+Fails visibly, never crashes the host: every hop validates that the needed `stdout`/`stdin` streams exist (clear `TypeError` if missing), and stream errors like `EPIPE` are absorbed by safe listeners — a broken pipeline resolves as a failed `Result` instead of crashing the process.
+
 #### `chain()` — Sequential execution (stop on error)
 
 ```ts
@@ -476,9 +512,15 @@ Load `.env` files with `${VAR}` interpolation using Node's native `util.parseEnv
 import { load, get, requireEnv } from "fullnative";
 
 // Load .env (default path: ".env")
-await load();
+const applied = await load();
+// applied: Record<string, string> — variables actually applied by this call
+
+// Load a specific file
 await load("./.env.production");
 
+// Options object: path + override
+await load({ path: "./.env.production", override: true });
+
 // Get a variable
 const port = get("PORT");              // string | undefined
 const host = get("HOST", "localhost");  // string (fallback)
@@ -486,31 +528,85 @@ const key = requireEnv("API_KEY");      // string — throws if missing
 ```
 
 **Behavior:**
+- Accepts `string | { path?: string; override?: boolean }` (`LoadOptions`). With no argument, loads `".env"`.
+- Returns `Promise<Record<string, string>>` with the variables **actually applied**: in normal mode only the keys that weren't already in `process.env`; with `override: true`, every resolved variable.
 - Parses with `util.parseEnv` (handles quotes, comments, multiline values).
 - Interpolates `${VAR}` references across multiple passes (resolves chains like `A=${B}`, `B=${C}`, `C=value`).
 - Circular references (`A=${B}`, `B=${A}`) are cut off after 5 passes — no infinite loops.
-- Variables already set in `process.env` are **never overwritten** — the real environment always wins.
+- Default merge semantics unchanged: variables already set in `process.env` are **never overwritten** — the real environment always wins. Use `override: true` to let the file win.
 - `requireEnv("KEY")` throws `Error` with the key name if the variable is missing.
 - **`load()` rejects if the file doesn't exist** — wrap in try/catch if you want optional loading. There is no silent mode.
 
 ---
 
+## utils
+
+Functional utilities for the patterns that show up in every serious automation: pausing, deadlines, and disposable temp directories.
+
+```ts
+import { sleep, timeout, TimeoutError, tempDir, TempDir } from "fullnative";
+
+// sleep(ms) — readable pause, always resolves (even with ms <= 0)
+await sleep(200);   // wait 200ms before continuing
+
+// timeout(promise, ms, message?) — deadline for ANY promise
+const data = await timeout(fetchJSON("/api/data"), 5000);
+// rejects with TimeoutError if fetchJSON takes longer than 5s
+
+try {
+  await timeout(slowTask(), 1_000);
+} catch (err) {
+  if (err instanceof TimeoutError) {
+    // distinguish deadlines from real failures — decide: retry or abort
+  }
+}
+// Default message: "Operation timed out after {ms}ms"; custom message supported
+
+// tempDir() — disposable temp directory (fs.mkdtemp under os.tmpdir())
+const tmp = await tempDir();                    // TempDir (extends Folder), prefix "fullnative-"
+const mine = await tempDir({ prefix: "myapp-" });
+
+await tmp.file("scratch.txt").write("hello");   // full Folder API inherited
+console.log(tmp.path);                          // unique absolute path
+
+await tmp.dispose();  // removes it now (fs.rm recursive + force), idempotent
+// Without dispose(): if keep !== true, the directory is auto-removed
+// via a single process "exit" hook — one listener total for all temp dirs
+
+// keep: true — no auto-cleanup; removal is your responsibility
+const persistent = await tempDir({ keep: true });
+```
+
+**Behavior:**
+- `sleep(ms)` resolves to `void`; it never rejects.
+- `timeout()` cleans up its timer (`clearTimeout` via `finally`) when the underlying promise wins the race, and never produces unhandled rejections from late rejections of the wrapped promise.
+- `TempDir` extends `Folder`, so it inherits the entire directory API (`list`, `createFile`, `walk`, ...).
+- `dispose()` is idempotent: it removes the directory and takes the path out of the auto-cleanup registry, so there is no double delete attempt at exit.
+- Auto-cleanup uses **one** global `process.once("exit")` hook registered once per process — never one listener per temp directory.
+
+---
+
 ## API Reference
 
 | Class / Function | Description |
 |---|---|
-| `File` | File operations: read, write, JSON, hash, streams, copy, move, rename, replace, permissions, truncate, touch |
+| `File` | File operations: read, write, JSON, hash, streams, copy, move, rename, replace, permissions, truncate, touch, absolute |
 | `Folder` | Directory operations: list, walk, walkIter, walkFilesIter, tree, find, matchFiles, watch, copy, move, rename |
 | `Process` | Execute native commands: run, output, shell, spawn, spawnScript, exists, which |
-| `Command` | Immutable builder: withArgs, in, withEnv, withTimeout, withInput, throwOnError |
+| `Command` | Immutable builder: withArgs, in, withEnv, withTimeout, withAbort, withInput, throwOnError |
 | `LiveProcess` | Running process: stdin/stdout/stderr, kill, forceKill, wait, onOutput, elapsed, stopped |
-| `Result` | Finished command: stdout, stderr, output, lines, json, ok, failed, throwIfFailed |
+| `Result` | Finished command: stdout, stderr, output, lines, nonEmptyLines, json, ok, failed, throwIfFailed |
 | `ProcessError` | Structured error: command, args, kind, exitCode, signal, stderr, cause |
 | `Shell` | Shell session: run, $, pipe, chain, ifOk, ifFail, bg, cd, set/unset, alias, history, killAll |
 | `Job` | Background process: name, autoRestart, restartCount, onRestart, kill, wait, result |
-| `load` | Load `.env` file with `${VAR}` interpolation — rejects if file missing |
+| `load` | Load `.env` file with `${VAR}` interpolation — accepts `string` or `LoadOptions`, returns the variables applied, rejects if file missing |
 | `get` | Get env var with optional fallback |
 | `requireEnv` | Get env var or throw if missing |
+| `sleep` | Promise-based pause for `ms` milliseconds |
+| `timeout` | Race any promise against a deadline — rejects with `TimeoutError` |
+| `TimeoutError` | Error thrown when a `timeout()` deadline expires |
+| `tempDir` | Create a unique temp directory (`TempDir`) with optional auto-cleanup at process exit |
+| `TempDir` | Temp directory class extending `Folder`, with `dispose()` |
 
 ## Requirements
 
@@ -522,7 +618,7 @@ const key = requireEnv("API_KEY");      // string — throws if missing
 
 ```bash
 pnpm install
-pnpm test          # run 150 tests
+pnpm test          # run 172 tests
 pnpm run typecheck # type check
 pnpm run build     # compile to dist/
 ```
@@ -531,12 +627,10 @@ pnpm run build     # compile to dist/
 
 Planned for future releases:
 
-- **`sleep(ms)`** — promise-based delay
 - **`waitFor(fn, opts)`** — poll until a condition is met
 - **`retry(fn, opts)`** — retry with backoff strategies
-- **`timeout(promise, ms)`** — race a promise against a timer
 - **`onShutdown(fn)`** — register graceful shutdown handlers (SIGINT/SIGTERM)
-- **`tempDir()`** — create and auto-cleanup a temporary directory
+- **Windows-safe quoting for `$`** — cmd.exe-specific escaping (POSIX quoting documented above)
 - **Dual CJS/ESM support** — if there's demand from legacy projects
 
 ## License

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

@@ -1,16 +1,48 @@
+/**
+ * Opciones de `load`.
+ *
+ * Se acepta directamente un `string` (equivalente a `{ path }`) para
+ * mantener la firma previa. Sin argumento, se usa la ruta default.
+ */
+export interface LoadOptions {
+    /**
+     * Ruta al archivo `.env` a cargar (default `".env"`, relativa al cwd del
+     * proceso).
+     */
+    path?: string;
+    /**
+     * Si es `true`, las variables del archivo **sobrescriben** las que ya
+     * existan en `process.env`. Default `false`: el entorno real siempre gana
+     * y las variables preexistentes no se tocan (merge con `??=`).
+     */
+    override?: boolean;
+}
 /**
  * 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.
+ * `process.env`.
+ *
+ * Semántica de merge (breaking en 1.0):
+ * - **Default**: las variables ya seteadas en el entorno real **no se
+ *   tocan** (merge con `??=`); el entorno real siempre tiene prioridad sobre
+ *   el archivo.
+ * - **`override: true`**: las variables del archivo **sobrescriben** las que
+ *   ya existan en `process.env`.
+ *
+ * Acepta la firma string (`load("./ruta.env")`, equivalente a
+ * `{ path: "./ruta.env" }`) o un objeto `LoadOptions`. Sin argumento, usa la
+ * ruta default `".env"`.
  *
  * 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
+ * @param options Ruta al archivo `.env` (default `".env"`) u objeto de
+ *   opciones `LoadOptions`
+ * @returns Un registro con las variables **efectivamente aplicadas** a
+ *   `process.env` por esta llamada: en modo normal, solo las que no existían
+ *   previamente; en modo `override: true`, todas las resueltas
  * @throws {Error} Si el archivo no existe (ENOENT) u otro error de lectura
  */
-export declare function load(envPath?: string): Promise<void>;
+export declare function load(options?: string | LoadOptions): Promise<Record<string, string>>;
 /**
  * Devuelve el valor de una env var, o `undefined` si no existe.
  * @param key Nombre de la variable

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

@@ -1 +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;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9C"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/core/env/env.ts"],"names":[],"mappings":"AA4FA;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,IAAI,CACxB,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAuBjC;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;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9C"}