@gesslar/toolkit 2.8.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "A collection of utilities for Node.js and browser environments.",
   "main": "./src/index.js",
   "type": "module",

package/src/lib/CappedDirectoryObject.js

@@ -13,6 +13,7 @@ import path from "node:path"
 import {Data, Valid} from "../browser/index.js"
 import DirectoryObject from "./DirectoryObject.js"
 import FileObject from "./FileObject.js"
+import FS from "./FS.js"
 import Sass from "./Sass.js"
 
 /**
@@ -30,88 +31,80 @@ export default class CappedDirectoryObject extends DirectoryObject {
   /**
    * Constructs a CappedDirectoryObject instance.
    *
-   * This is an abstract base class - use subclasses like TempDirectoryObject
-   * that define specific caps.
+   * Without a parent, the path becomes both the directory location and the cap
+   * (virtual root). With a parent, the path is resolved relative to the parent's
+   * cap using virtual path semantics (absolute paths treated as cap-relative).
    *
-   * @param {string?} name - Base name for the directory (if empty/null, uses cap root)
-   * @param {string} cap - The root path that constrains this directory tree
+   * @param {string} dirPath - Directory path (becomes cap if no parent, else relative to parent's cap)
    * @param {CappedDirectoryObject?} [parent] - Optional parent capped directory
    * @param {boolean} [temporary=false] - Whether this is a temporary directory
-   * @throws {Sass} If name is absolute
-   * @throws {Sass} If name is empty (when parent is provided)
-   * @throws {Sass} If name contains path separators
-   * @throws {Sass} If parent is not a capped directory
-   * @throws {Sass} If parent's lineage does not trace back to the cap
+   * @throws {Sass} If path is empty
+   * @throws {Sass} If parent is provided but not a CappedDirectoryObject
    * @throws {Sass} If the resulting path would escape the cap
+   * @example
+   * // Create new capped directory
+   * const cache = new CappedDirectoryObject("/home/user/.cache")
+   * // path: /home/user/.cache, cap: /home/user/.cache
+   *
+   * @example
+   * // Create subdirectory with parent
+   * const data = new CappedDirectoryObject("data", cache)
+   * // path: /home/user/.cache/data, cap: /home/user/.cache
+   *
+   * @example
+   * // Virtual absolute path with parent
+   * const config = new CappedDirectoryObject("/etc/config", cache)
+   * // path: /home/user/.cache/etc/config, cap: /home/user/.cache
    */
-  constructor(name, cap, parent=null, temporary=false) {
-    Valid.type(cap, "String")
+  constructor(dirPath, parent=null, temporary=false) {
+    Valid.type(dirPath, "String")
+    Valid.assert(dirPath.length > 0, "Path must not be empty.")
 
     // Validate parent using instanceof since TypeSpec doesn't understand inheritance
     if(parent !== null && !(parent instanceof CappedDirectoryObject)) {
       throw Sass.new(`Parent must be null or a CappedDirectoryObject instance, got ${Data.typeOf(parent)}`)
     }
 
-    let dirPath
+    let cap
+    let resolvedPath
 
-    // Special case: empty name with no parent means use cap root
-    if(!name && !parent) {
-      dirPath = cap
+    if(!parent) {
+      // No parent: dirPath becomes both the directory and the cap
+      cap = path.resolve(dirPath)
+      resolvedPath = cap
     } else {
-      Valid.type(name, "String")
+      // With parent: inherit cap and resolve dirPath relative to it
+      cap = parent.#cap
 
-      // Security: Validate name before any processing
-      Valid.assert(
-        !path.isAbsolute(name),
-        "Capped directory name must not be an absolute path.",
-      )
-      Valid.assert(
-        name.length > 0,
-        "Capped directory name must not be empty.",
-      )
-      Valid.assert(
-        !name.includes("/") && !name.includes("\\") && !name.includes(path.sep),
-        "Capped directory name must not contain path separators.",
-      )
+      // Use real path for filesystem operations
+      const parentPath = parent.realPath || parent.path
+      const capResolved = path.resolve(cap)
 
-      if(parent) {
-        // Ensure parent is capped
-        Valid.assert(parent.capped, "Parent must be a capped DirectoryObject.")
-
-        // Ensure parent has same cap
-        Valid.assert(
-          parent.cap === cap,
-          "Parent must have the same cap as this directory.",
-        )
-
-        const parentPath = parent.path
-
-        // Validate parent's lineage traces back to the cap
-        let found = false
-        if(parent.trail) {
-          for(const p of parent.walkUp) {
-            if(p.path === cap) {
-              found = true
-              break
-            }
-          }
-        }
-
-        Valid.assert(
-          found,
-          `The lineage of this directory must trace back to the cap '${cap}'.`,
-        )
-
-        dirPath = path.join(parentPath, name)
+      let targetPath
+
+      // If absolute, treat as virtual path relative to cap (strip leading /)
+      if(path.isAbsolute(dirPath)) {
+        const relative = dirPath.replace(/^[/\\]+/, "")
+        targetPath = relative ? path.join(capResolved, relative) : capResolved
+      } else {
+        // Relative path - resolve from parent directory
+        targetPath = FS.resolvePath(parentPath, dirPath)
+      }
+
+      // Resolve to absolute path (handles .. and .)
+      const resolved = path.resolve(targetPath)
+
+      // Clamp to cap boundary - cannot escape above cap
+      if(!resolved.startsWith(capResolved)) {
+        // Path tried to escape - clamp to cap root
+        resolvedPath = capResolved
       } else {
-        // No parent - this is a root-level capped directory
-        dirPath = path.join(cap, name)
+        resolvedPath = resolved
       }
     }
 
     // Call parent constructor with the path
-    // Pass through the temporary flag (subclasses control this)
-    super(dirPath, temporary)
+    super(resolvedPath, temporary)
 
     // Store the cap AFTER calling super()
     this.#cap = cap
@@ -128,13 +121,13 @@ export default class CappedDirectoryObject extends DirectoryObject {
    */
   #validateCapPath() {
     const cap = this.#cap
-    const resolved = path.resolve(this.path)
+    const resolved = path.resolve(this.#realPath)
     const capResolved = path.resolve(cap)
 
     // Check if the resolved path starts with the cap directory
     if(!resolved.startsWith(capResolved)) {
       throw Sass.new(
-        `Path '${this.path}' is not within the cap directory '${cap}'`
+        `Path '${this.#realPath}' is not within the cap directory '${cap}'`
       )
     }
   }
@@ -157,6 +150,73 @@ export default class CappedDirectoryObject extends DirectoryObject {
     return true
   }
 
+  /**
+   * Returns the real filesystem path (for internal and subclass use).
+   *
+   * @protected
+   * @returns {string} The actual filesystem path
+   */
+  get realPath() {
+    return super.path
+  }
+
+  /**
+   * Private alias for realPath (for use in private methods).
+   *
+   * @private
+   * @returns {string} The actual filesystem path
+   */
+  get #realPath() {
+    return this.realPath
+  }
+
+  /**
+   * Returns the virtual path relative to the cap.
+   * This is the default path representation in the capped environment.
+   * Use `.real.path` to access the actual filesystem path.
+   *
+   * @returns {string} Path relative to cap, or "/" if at cap root
+   * @example
+   * const temp = new TempDirectoryObject("myapp")
+   * const subdir = temp.getDirectory("data/cache")
+   * console.log(subdir.path)       // "/data/cache" (virtual, relative to cap)
+   * console.log(subdir.real.path)  // "/tmp/myapp-ABC123/data/cache" (actual filesystem)
+   */
+  get path() {
+    const capResolved = path.resolve(this.#cap)
+    const relative = path.relative(capResolved, this.#realPath)
+
+    // If at cap root or empty, return "/"
+    if(!relative || relative === ".") {
+      return "/"
+    }
+
+    // Return with leading slash to indicate it's cap-relative
+    return "/" + relative.split(path.sep).join("/")
+  }
+
+  /**
+   * Returns a plain DirectoryObject representing the actual filesystem location.
+   * This provides an "escape hatch" from the capped environment to interact
+   * with the real filesystem when needed.
+   *
+   * @returns {DirectoryObject} Uncapped directory object at the real filesystem path
+   * @example
+   * const temp = new TempDirectoryObject("myapp")
+   * const subdir = temp.getDirectory("data")
+   *
+   * // Work within the capped environment (virtual paths)
+   * console.log(subdir.path)        // "/data" (virtual)
+   * subdir.getFile("config.json")   // Stays within cap
+   *
+   * // Break out to real filesystem when needed
+   * console.log(subdir.real.path)   // "/tmp/myapp-ABC123/data" (real)
+   * subdir.real.parent              // Can traverse outside the cap
+   */
+  get real() {
+    return new DirectoryObject(this.#realPath)
+  }
+
   /**
    * Returns the parent directory of this capped directory.
    * Returns null only if this directory is at the cap (the "root" of the capped tree).
@@ -175,12 +235,17 @@ export default class CappedDirectoryObject extends DirectoryObject {
     const capResolved = path.resolve(this.#cap)
 
     // If we're at the cap, return null (cap is the "root")
-    if(this.path === capResolved) {
+    if(this.#realPath === capResolved) {
       return null
     }
 
-    // Otherwise return the parent (plain DirectoryObject, not capped)
-    return super.parent
+    // Otherwise return the parent using real path (plain DirectoryObject, not capped)
+    const parentPath = path.dirname(this.#realPath)
+    const isRoot = parentPath === this.#realPath
+
+    return isRoot
+      ? null
+      : new DirectoryObject(parentPath, this.temporary)
   }
 
   /**
@@ -201,19 +266,27 @@ export default class CappedDirectoryObject extends DirectoryObject {
   *#walkUpCapped() {
     const capResolved = path.resolve(this.#cap)
 
-    // Use super.walkUp but stop when we would go beyond the cap
-    for(const dir of super.walkUp) {
+    // Build trail from real path
+    const trail = this.#realPath.split(path.sep).filter(Boolean)
+    const curr = [...trail]
+
+    while(curr.length > 0) {
+      const joined = path.sep + curr.join(path.sep)
+
       // Don't yield anything beyond the cap
-      if(!dir.path.startsWith(capResolved)) {
+      if(!joined.startsWith(capResolved)) {
         break
       }
 
-      yield dir
+      // Yield plain DirectoryObject with real path
+      yield new DirectoryObject(joined, this.temporary)
 
       // Stop after yielding the cap
-      if(dir.path === capResolved) {
+      if(joined === capResolved) {
         break
       }
+
+      curr.pop()
     }
   }
 
@@ -229,69 +302,269 @@ export default class CappedDirectoryObject extends DirectoryObject {
   /**
    * Creates a new CappedDirectoryObject by extending this directory's path.
    *
-   * Validates that the resulting path remains within the cap directory tree.
+   * All paths are coerced to remain within the cap directory tree:
+   * - Absolute paths (e.g., "/foo") are treated as relative to the cap
+   * - Parent traversal ("..") is allowed but clamped at the cap boundary
+   * - The cap acts as the virtual root directory
    *
-   * @param {string} newPath - The path segment to append
-   * @returns {CappedDirectoryObject} A new CappedDirectoryObject with the extended path
-   * @throws {Sass} If the path would escape the cap directory
-   * @throws {Sass} If the path is absolute
-   * @throws {Sass} If the path contains traversal (..)
+   * @param {string} newPath - The path to resolve (can be absolute or contain ..)
+   * @returns {CappedDirectoryObject} A new CappedDirectoryObject with the coerced path
    * @example
    * const capped = new TempDirectoryObject("myapp")
    * const subDir = capped.getDirectory("data")
    * console.log(subDir.path) // "/tmp/myapp-ABC123/data"
+   *
+   * @example
+   * // Absolute paths are relative to cap
+   * const abs = capped.getDirectory("/foo/bar")
+   * console.log(abs.path) // "/tmp/myapp-ABC123/foo/bar"
+   *
+   * @example
+   * // Excessive .. traversal clamps to cap
+   * const up = capped.getDirectory("../../../etc/passwd")
+   * console.log(up.path) // "/tmp/myapp-ABC123" (clamped to cap)
    */
   getDirectory(newPath) {
     Valid.type(newPath, "String")
 
-    // Prevent absolute paths
+    // Fast path: if it's a simple name (no separators, not absolute, no ..)
+    // use the subclass constructor directly to preserve type
+    const isSimpleName = !path.isAbsolute(newPath) &&
+                         !newPath.includes("/") &&
+                         !newPath.includes("\\") &&
+                         !newPath.includes("..")
+
+    if(isSimpleName) {
+      // Both CappedDirectoryObject and subclasses use same signature now
+      return new this.constructor(newPath, this, this.temporary)
+    }
+
+    // Complex path - handle coercion
+    const capResolved = path.resolve(this.#cap)
+    let targetPath
+
+    // If absolute, treat as relative to cap (virtual root)
     if(path.isAbsolute(newPath)) {
-      throw Sass.new("Absolute paths are not allowed in capped directories")
+      // Strip leading slashes to make relative
+      const relative = newPath.replace(/^[/\\]+/, "")
+
+      // Join with cap (unless empty, which means cap root)
+      targetPath = relative ? path.join(capResolved, relative) : capResolved
+    } else {
+      // Relative path - resolve from current directory
+      targetPath = FS.resolvePath(this.#realPath, newPath)
     }
 
-    // Prevent path traversal attacks
-    const normalized = path.normalize(newPath)
-    if(normalized.includes("..")) {
-      throw Sass.new("Path traversal (..) is not allowed in capped directories")
+    // Resolve to absolute path (handles .. and .)
+    const resolved = path.resolve(targetPath)
+
+    // Coerce: if path escaped cap, clamp to cap boundary
+    const coerced = resolved.startsWith(capResolved)
+      ? resolved
+      : capResolved
+
+    // Compute path relative to cap for reconstruction
+    const relativeToCap = path.relative(capResolved, coerced)
+
+    // If we're at the cap root, return cap root directory
+    if(!relativeToCap || relativeToCap === ".") {
+      return this.#createCappedAtRoot()
     }
 
-    // Use the constructor of the current class (supports subclassing)
-    // Pass this as parent so the child inherits the same cap
-    return new this.constructor(newPath, this)
+    // Build directory by traversing segments from cap
+    return this.#buildDirectoryFromRelativePath(relativeToCap)
+  }
+
+  /**
+   * Creates a CappedDirectoryObject at the cap root.
+   * Can be overridden by subclasses that have different root semantics.
+   *
+   * @private
+   * @returns {CappedDirectoryObject} Directory object at cap root
+   */
+  #createCappedAtRoot() {
+    // Create a base CappedDirectoryObject at the cap path
+    // This works for direct usage of CappedDirectoryObject
+    // Subclasses may need to override if they have special semantics
+    return new CappedDirectoryObject(this.#cap, null, this.temporary)
+  }
+
+  /**
+   * Builds a directory by traversing path segments from cap.
+   *
+   * @private
+   * @param {string} relativePath - Path relative to cap
+   * @returns {CappedDirectoryObject} The directory at the final path
+   */
+  #buildDirectoryFromRelativePath(relativePath) {
+    const segments = relativePath.split(path.sep).filter(Boolean)
+
+    // Start at cap root
+    let current = this.#createCappedAtRoot()
+
+    // Traverse each segment, creating CappedDirectoryObject instances
+    // (not subclass instances, to avoid constructor signature issues)
+    for(const segment of segments) {
+      current = new CappedDirectoryObject(segment, current, this.temporary)
+    }
+
+    return current
   }
 
   /**
    * Creates a new FileObject by extending this directory's path.
    *
-   * Validates that the resulting path remains within the cap directory tree.
+   * All paths are coerced to remain within the cap directory tree:
+   * - Absolute paths (e.g., "/config.json") are treated as relative to the cap
+   * - Parent traversal ("..") is allowed but clamped at the cap boundary
+   * - The cap acts as the virtual root directory
    *
-   * @param {string} filename - The filename to append
-   * @returns {FileObject} A new FileObject with the extended path
-   * @throws {Sass} If the path would escape the cap directory
-   * @throws {Sass} If the path is absolute
-   * @throws {Sass} If the path contains traversal (..)
+   * @param {string} filename - The filename to resolve (can be absolute or contain ..)
+   * @returns {FileObject} A new FileObject with the coerced path
    * @example
    * const capped = new TempDirectoryObject("myapp")
    * const file = capped.getFile("config.json")
    * console.log(file.path) // "/tmp/myapp-ABC123/config.json"
+   *
+   * @example
+   * // Absolute paths are relative to cap
+   * const abs = capped.getFile("/data/config.json")
+   * console.log(abs.path) // "/tmp/myapp-ABC123/data/config.json"
+   *
+   * @example
+   * // Excessive .. traversal clamps to cap
+   * const up = capped.getFile("../../../etc/passwd")
+   * console.log(up.path) // "/tmp/myapp-ABC123/passwd" (clamped to cap)
    */
   getFile(filename) {
     Valid.type(filename, "String")
 
-    // Prevent absolute paths
+    // Fast path: if it's a simple filename (no separators, not absolute, no ..)
+    // use this as the parent directly
+    const isSimpleName = !path.isAbsolute(filename) &&
+                         !filename.includes("/") &&
+                         !filename.includes("\\") &&
+                         !filename.includes("..")
+
+    if(isSimpleName) {
+      // Simple filename - create directly with this as parent
+      return new FileObject(filename, this)
+    }
+
+    // Complex path - handle coercion
+    const capResolved = path.resolve(this.#cap)
+    let targetPath
+
+    // If absolute, treat as relative to cap (virtual root)
     if(path.isAbsolute(filename)) {
-      throw Sass.new("Absolute paths are not allowed in capped directories")
+      // Strip leading slashes to make relative
+      const relative = filename.replace(/^[/\\]+/, "")
+
+      // Join with cap
+      targetPath = path.join(capResolved, relative)
+    } else {
+      // Relative path - resolve from current directory
+      targetPath = FS.resolvePath(this.#realPath, filename)
     }
 
-    // Prevent path traversal attacks
-    const normalized = path.normalize(filename)
-    if(normalized.includes("..")) {
-      throw Sass.new("Path traversal (..) is not allowed in capped directories")
+    // Resolve to absolute path (handles .. and .)
+    const resolved = path.resolve(targetPath)
+
+    // Coerce: if path escaped cap, clamp to cap boundary
+    const coerced = resolved.startsWith(capResolved)
+      ? resolved
+      : capResolved
+
+    // Extract directory and filename parts
+    let fileDir = path.dirname(coerced)
+    let fileBasename = path.basename(coerced)
+
+    // Special case: if coerced is exactly the cap (file tried to escape),
+    // the file should be placed at the cap root with just the filename
+    if(coerced === capResolved) {
+      // Extract just the filename from the original path
+      fileBasename = path.basename(resolved)
+      fileDir = capResolved
     }
 
-    // Pass the filename and this directory as parent
-    // This ensures the FileObject maintains the correct parent reference
-    return new FileObject(filename, this)
+    // Get or create the parent directory
+    const relativeToCap = path.relative(capResolved, fileDir)
+    const parentDir = !relativeToCap || relativeToCap === "."
+      ? this.#createCappedAtRoot()
+      : this.#buildDirectoryFromRelativePath(relativeToCap)
+
+    // Create FileObject with parent directory
+    return new FileObject(fileBasename, parentDir)
+  }
+
+  /**
+   * Override exists to use real filesystem path.
+   *
+   * @returns {Promise<boolean>} Whether the directory exists
+   */
+  get exists() {
+    return this.real.exists
+  }
+
+  /**
+   * Override read to use real filesystem path and return capped objects.
+   *
+   * @param {string} [pat=""] - Optional glob pattern
+   * @returns {Promise<{files: Array<FileObject>, directories: Array}>} Directory contents
+   */
+  async read(pat="") {
+    const {files, directories} = await this.real.read(pat)
+
+    // Convert plain DirectoryObjects to CappedDirectoryObjects with same cap
+    const cappedDirectories = directories.map(dir => {
+      const name = dir.name
+
+      return new this.constructor(name, this)
+    })
+
+    return {files, directories: cappedDirectories}
+  }
+
+  /**
+   * Override assureExists to use real filesystem path.
+   *
+   * @param {object} [options] - Options for mkdir
+   * @returns {Promise<void>}
+   */
+  async assureExists(options = {}) {
+    return await this.real.assureExists(options)
+  }
+
+  /**
+   * Override delete to use real filesystem path.
+   *
+   * @returns {Promise<void>}
+   */
+  async delete() {
+    return await this.real.delete()
+  }
+
+  /**
+   * Override remove to preserve temporary flag check.
+   *
+   * @returns {Promise<void>}
+   */
+  async remove() {
+    if(!this.temporary)
+      throw Sass.new("This is not a temporary directory.")
+
+    const {files, directories} = await this.read()
+
+    // Remove subdirectories recursively
+    for(const dir of directories)
+      await dir.remove()
+
+    // Remove files
+    for(const file of files)
+      await file.delete()
+
+    // Delete the now-empty directory
+    await this.delete()
   }
 
   /**
@@ -300,6 +573,6 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * @returns {string} string representation of the CappedDirectoryObject
    */
   toString() {
-    return `[CappedDirectoryObject: ${this.path}]`
+    return `[CappedDirectoryObject: ${this.path} (real: ${this.#realPath})]`
   }
 }

package/src/lib/FileObject.js

@@ -96,6 +96,7 @@ export default class FileObject extends FS {
         case "String":
           return new DirectoryObject(parent)
         case "DirectoryObject":
+        case "CappedDirectoryObject":
         case "TempDirectoryObject":
           return parent
         default:
@@ -103,7 +104,9 @@ export default class FileObject extends FS {
       }
     })()
 
-    const final = FS.resolvePath(parentObject.path ?? ".", fixedFile)
+    // Use real path if parent is capped, otherwise use path
+    const parentPath = parentObject.realPath || parentObject.path
+    const final = FS.resolvePath(parentPath ?? ".", fixedFile)
 
     const resolved = final
     const url = new URL(FS.pathToUri(resolved))
@@ -113,7 +116,9 @@ export default class FileObject extends FS {
 
     // If the file is directly in the provided parent directory, reuse that object
     // Otherwise, create a DirectoryObject for the actual parent directory
-    const actualParent = parentObject && actualParentPath === parentObject.path
+    // Use real path for comparison if parent is capped
+    const parentRealPath = parentObject.realPath || parentObject.path
+    const actualParent = parentObject && actualParentPath === parentRealPath
       ? parentObject
       : new DirectoryObject(actualParentPath)
 
@@ -184,12 +189,28 @@ export default class FileObject extends FS {
   }
 
   /**
-   * Return the fully resolved absolute path to the file on disk.
+   * Returns the file path. If the parent is a capped directory, returns the
+   * virtual path relative to the cap. Otherwise returns the real filesystem path.
+   * Use `.real.path` to always get the actual filesystem path.
    *
-   * @returns {string} The fully resolved absolute file path
+   * @returns {string} The file path (virtual if parent is capped, real otherwise)
    */
   get path() {
-    return this.#meta.path
+    const realPath = this.#meta.path
+    const parent = this.#meta.parent
+
+    // If parent is capped, return virtual path
+    if(parent?.capped) {
+      const cap = parent.cap
+      const capResolved = path.resolve(cap)
+      const relative = path.relative(capResolved, realPath)
+
+      // Return with leading slash to indicate it's cap-relative
+      return "/" + relative.split(path.sep).join("/")
+    }
+
+    // Otherwise return real path
+    return realPath
   }
 
   /**
@@ -264,6 +285,26 @@ export default class FileObject extends FS {
     return this.#meta.parent
   }
 
+  /**
+   * Returns a plain FileObject representing the actual filesystem location.
+   * This provides an "escape hatch" when working with capped directories,
+   * allowing direct filesystem access when needed.
+   *
+   * @returns {FileObject} Uncapped file object at the real filesystem path
+   * @example
+   * const temp = new TempDirectoryObject("myapp")
+   * const file = temp.getFile("/config/app.json")
+   *
+   * // file.path shows virtual path
+   * console.log(file.path)       // "/config/app.json"
+   * // file.real.path shows actual filesystem path
+   * console.log(file.real.path)  // "/tmp/myapp-ABC123/config/app.json"
+   * file.real.parent.parent      // Can traverse outside the cap
+   */
+  get real() {
+    return new FileObject(this.#meta.path)
+  }
+
   /**
    * Check if a file can be read. Returns true if the file can be read, false
    *
@@ -271,7 +312,7 @@ export default class FileObject extends FS {
    */
   async canRead() {
     try {
-      await fs.access(this.path, fs.constants.R_OK)
+      await fs.access(this.#meta.path, fs.constants.R_OK)
 
       return true
     } catch(_) {
@@ -286,7 +327,7 @@ export default class FileObject extends FS {
    */
   async canWrite() {
     try {
-      await fs.access(this.path, fs.constants.W_OK)
+      await fs.access(this.#meta.path, fs.constants.W_OK)
 
       return true
     } catch(_) {
@@ -301,7 +342,7 @@ export default class FileObject extends FS {
    */
   async #fileExists() {
     try {
-      await fs.access(this.path, fs.constants.F_OK)
+      await fs.access(this.#meta.path, fs.constants.F_OK)
 
       return true
     } catch(_) {
@@ -316,7 +357,7 @@ export default class FileObject extends FS {
    */
   async size() {
     try {
-      const stat = await fs.stat(this.path)
+      const stat = await fs.stat(this.#meta.path)
 
       return stat.size
     } catch(_) {
@@ -332,7 +373,7 @@ export default class FileObject extends FS {
    */
   async modified() {
     try {
-      const stat = await fs.stat(this.path)
+      const stat = await fs.stat(this.#meta.path)
 
       return stat.mtime
     } catch(_) {

package/src/lib/TempDirectoryObject.js

@@ -6,6 +6,7 @@
 
 import fs from "node:fs"
 import os from "node:os"
+import path from "node:path"
 
 import CappedDirectoryObject from "./CappedDirectoryObject.js"
 import Sass from "./Sass.js"
@@ -57,22 +58,63 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
    * await parent.remove() // Removes both parent and child
    */
   constructor(name, parent=null) {
-    let finalName = name
+    let dirPath
+    let cappedParent = parent
 
-    // Only generate unique suffix if we have a name and no parent
-    if(name && !parent) {
-      const prefix = name.endsWith("-") ? name : `${name}-`
-      const uniqueSuffix =
-        Math.random()
-          .toString(36)
-          .substring(2, 8)
-          .toUpperCase()
-      finalName = `${prefix}${uniqueSuffix}`
+    if(!parent) {
+      // No parent: need to create a capped parent at tmpdir first
+      cappedParent = new CappedDirectoryObject(os.tmpdir(), null, true)
+
+      if(name) {
+        // Check if name is a simple name (no separators, not absolute)
+        const isSimpleName = !path.isAbsolute(name) &&
+                             !name.includes("/") &&
+                             !name.includes("\\") &&
+                             !name.includes(path.sep)
+
+        if(isSimpleName) {
+          // Simple name: add unique suffix
+          const prefix = name.endsWith("-") ? name : `${name}-`
+          const uniqueSuffix =
+            Math.random()
+              .toString(36)
+              .substring(2, 8)
+              .toUpperCase()
+          dirPath = `${prefix}${uniqueSuffix}`
+        } else {
+          // Complex path: use as-is, let CappedDirectoryObject handle coercion
+          dirPath = name
+        }
+      } else {
+        // No name: use tmpdir itself (no parent)
+        dirPath = os.tmpdir()
+        cappedParent = null
+      }
+    } else {
+      // With parent: validate it's a proper temp directory parent
+      if(!(parent instanceof CappedDirectoryObject)) {
+        throw Sass.new(
+          "Parent must be a CappedDirectoryObject or TempDirectoryObject."
+        )
+      }
+
+      // SECURITY: Ensure parent's cap is tmpdir (prevent escape to other caps)
+      const tmpdir = os.tmpdir()
+      if(parent.cap !== tmpdir) {
+        throw Sass.new(
+          `Parent must be capped to OS temp directory (${tmpdir}), ` +
+          `got cap: ${parent.cap}`
+        )
+      }
+
+      dirPath = name || ""
+      if(!dirPath) {
+        throw Sass.new("Name must not be empty when parent is provided.")
+      }
     }
 
-    // Call parent constructor with the cap set to OS temp directory
-    // Mark as temporary=true so remove() works
-    super(finalName, os.tmpdir(), parent, true)
+    // Call parent constructor with new signature
+    super(dirPath, cappedParent, true)
 
     // Temp-specific behavior: create directory immediately
     this.#createDirectory()
@@ -86,12 +128,13 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
    */
   #createDirectory() {
     try {
-      fs.mkdirSync(this.path)
+      // Use recursive: true to create parent directories as needed
+      fs.mkdirSync(this.realPath, {recursive: true})
     } catch(e) {
       // EEXIST is fine - directory already exists
       if(e.code !== "EEXIST") {
         throw Sass.new(
-          `Unable to create temporary directory '${this.path}': ${e.message}`
+          `Unable to create temporary directory '${this.realPath}': ${e.message}`
         )
       }
     }

package/src/types/lib/CappedDirectoryObject.d.ts

@@ -11,21 +11,32 @@ export default class CappedDirectoryObject extends DirectoryObject {
     /**
      * Constructs a CappedDirectoryObject instance.
      *
-     * This is an abstract base class - use subclasses like TempDirectoryObject
-     * that define specific caps.
+     * Without a parent, the path becomes both the directory location and the cap
+     * (virtual root). With a parent, the path is resolved relative to the parent's
+     * cap using virtual path semantics (absolute paths treated as cap-relative).
      *
-     * @param {string?} name - Base name for the directory (if empty/null, uses cap root)
-     * @param {string} cap - The root path that constrains this directory tree
+     * @param {string} dirPath - Directory path (becomes cap if no parent, else relative to parent's cap)
      * @param {CappedDirectoryObject?} [parent] - Optional parent capped directory
      * @param {boolean} [temporary=false] - Whether this is a temporary directory
-     * @throws {Sass} If name is absolute
-     * @throws {Sass} If name is empty (when parent is provided)
-     * @throws {Sass} If name contains path separators
-     * @throws {Sass} If parent is not a capped directory
-     * @throws {Sass} If parent's lineage does not trace back to the cap
+     * @throws {Sass} If path is empty
+     * @throws {Sass} If parent is provided but not a CappedDirectoryObject
      * @throws {Sass} If the resulting path would escape the cap
+     * @example
+     * // Create new capped directory
+     * const cache = new CappedDirectoryObject("/home/user/.cache")
+     * // path: /home/user/.cache, cap: /home/user/.cache
+     *
+     * @example
+     * // Create subdirectory with parent
+     * const data = new CappedDirectoryObject("data", cache)
+     * // path: /home/user/.cache/data, cap: /home/user/.cache
+     *
+     * @example
+     * // Virtual absolute path with parent
+     * const config = new CappedDirectoryObject("/etc/config", cache)
+     * // path: /home/user/.cache/etc/config, cap: /home/user/.cache
      */
-    constructor(name: string | null, cap: string, parent?: CappedDirectoryObject | null, temporary?: boolean);
+    constructor(dirPath: string, parent?: CappedDirectoryObject | null, temporary?: boolean);
     /**
      * Returns the cap path for this directory.
      *
@@ -38,6 +49,32 @@ export default class CappedDirectoryObject extends DirectoryObject {
      * @returns {boolean} Always true for CappedDirectoryObject instances
      */
     get capped(): boolean;
+    /**
+     * Returns the real filesystem path (for internal and subclass use).
+     *
+     * @protected
+     * @returns {string} The actual filesystem path
+     */
+    protected get realPath(): string;
+    /**
+     * Returns a plain DirectoryObject representing the actual filesystem location.
+     * This provides an "escape hatch" from the capped environment to interact
+     * with the real filesystem when needed.
+     *
+     * @returns {DirectoryObject} Uncapped directory object at the real filesystem path
+     * @example
+     * const temp = new TempDirectoryObject("myapp")
+     * const subdir = temp.getDirectory("data")
+     *
+     * // Work within the capped environment (virtual paths)
+     * console.log(subdir.path)        // "/data" (virtual)
+     * subdir.getFile("config.json")   // Stays within cap
+     *
+     * // Break out to real filesystem when needed
+     * console.log(subdir.real.path)   // "/tmp/myapp-ABC123/data" (real)
+     * subdir.real.parent              // Can traverse outside the cap
+     */
+    get real(): DirectoryObject;
     /**
      * Returns a generator that walks up to the cap.
      *
@@ -47,20 +84,41 @@ export default class CappedDirectoryObject extends DirectoryObject {
     /**
      * Creates a new CappedDirectoryObject by extending this directory's path.
      *
-     * Validates that the resulting path remains within the cap directory tree.
+     * All paths are coerced to remain within the cap directory tree:
+     * - Absolute paths (e.g., "/foo") are treated as relative to the cap
+     * - Parent traversal ("..") is allowed but clamped at the cap boundary
+     * - The cap acts as the virtual root directory
      *
-     * @param {string} newPath - The path segment to append
-     * @returns {CappedDirectoryObject} A new CappedDirectoryObject with the extended path
-     * @throws {Sass} If the path would escape the cap directory
-     * @throws {Sass} If the path is absolute
-     * @throws {Sass} If the path contains traversal (..)
+     * @param {string} newPath - The path to resolve (can be absolute or contain ..)
+     * @returns {CappedDirectoryObject} A new CappedDirectoryObject with the coerced path
      * @example
      * const capped = new TempDirectoryObject("myapp")
      * const subDir = capped.getDirectory("data")
      * console.log(subDir.path) // "/tmp/myapp-ABC123/data"
+     *
+     * @example
+     * // Absolute paths are relative to cap
+     * const abs = capped.getDirectory("/foo/bar")
+     * console.log(abs.path) // "/tmp/myapp-ABC123/foo/bar"
+     *
+     * @example
+     * // Excessive .. traversal clamps to cap
+     * const up = capped.getDirectory("../../../etc/passwd")
+     * console.log(up.path) // "/tmp/myapp-ABC123" (clamped to cap)
      */
     getDirectory(newPath: string): CappedDirectoryObject;
+    /**
+     * Override read to use real filesystem path and return capped objects.
+     *
+     * @param {string} [pat=""] - Optional glob pattern
+     * @returns {Promise<{files: Array<FileObject>, directories: Array}>} Directory contents
+     */
+    read(pat?: string): Promise<{
+        files: Array<FileObject>;
+        directories: any[];
+    }>;
     #private;
 }
 import DirectoryObject from "./DirectoryObject.js";
+import FileObject from "./FileObject.js";
 //# sourceMappingURL=CappedDirectoryObject.d.ts.map

package/src/types/lib/CappedDirectoryObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CappedDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/CappedDirectoryObject.js"],"names":[],"mappings":"AAiBA;;;;;;;;GAQG;AACH;IAGE;;;;;;;;;;;;;;;;OAgBG;IACH,kBAXW,MAAM,OAAC,OACP,MAAM,WACN,qBAAqB,OAAC,cACtB,OAAO,EAkFjB;IAqBD;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IA8DD;;;;OAIG;IACH,cAFa,SAAS,CAAC,eAAe,CAAC,CAItC;IAED;;;;;;;;;;;;;;OAcG;IACH,sBAVW,MAAM,GACJ,qBAAqB,CA0BjC;;CA4CF;4BAnS2B,sBAAsB"}
+{"version":3,"file":"CappedDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/CappedDirectoryObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH;IAGE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,qBArBW,MAAM,WACN,qBAAqB,OAAC,cACtB,OAAO,EA0EjB;IAqBD;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,0BAFa,MAAM,CAIlB;IAqCD;;;;;;;;;;;;;;;;;OAiBG;IACH,YAba,eAAe,CAe3B;IA2ED;;;;OAIG;IACH,cAFa,SAAS,CAAC,eAAe,CAAC,CAItC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,sBAjBW,MAAM,GACJ,qBAAqB,CAiEjC;IAqID;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,QAAO;KAAC,CAAC,CAanE;;CAoDF;4BApjB2B,sBAAsB;uBAC3B,iBAAiB"}

package/src/types/lib/FileObject.d.ts

@@ -50,9 +50,11 @@ export default class FileObject extends FS {
      */
     get supplied(): string;
     /**
-     * Return the fully resolved absolute path to the file on disk.
+     * Returns the file path. If the parent is a capped directory, returns the
+     * virtual path relative to the cap. Otherwise returns the real filesystem path.
+     * Use `.real.path` to always get the actual filesystem path.
      *
-     * @returns {string} The fully resolved absolute file path
+     * @returns {string} The file path (virtual if parent is capped, real otherwise)
      */
     get path(): string;
     /**
@@ -107,6 +109,23 @@ export default class FileObject extends FS {
      * @returns {DirectoryObject} The parent directory object
      */
     get parent(): DirectoryObject;
+    /**
+     * Returns a plain FileObject representing the actual filesystem location.
+     * This provides an "escape hatch" when working with capped directories,
+     * allowing direct filesystem access when needed.
+     *
+     * @returns {FileObject} Uncapped file object at the real filesystem path
+     * @example
+     * const temp = new TempDirectoryObject("myapp")
+     * const file = temp.getFile("/config/app.json")
+     *
+     * // file.path shows virtual path
+     * console.log(file.path)       // "/config/app.json"
+     * // file.real.path shows actual filesystem path
+     * console.log(file.real.path)  // "/tmp/myapp-ABC123/config/app.json"
+     * file.real.parent.parent      // Can traverse outside the cap
+     */
+    get real(): FileObject;
     /**
      * Check if a file can be read. Returns true if the file can be read, false
      *

package/src/types/lib/FileObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../lib/FileObject.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;GAcG;AAEH;uBA8He,MAAM;IA7HnB;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA2BF;;;;;OAKG;IACH,sBAHW,MAAM,GAAG,UAAU,WACnB,eAAe,GAAC,MAAM,GAAC,IAAI,EAkDrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAclB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IACD;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAsBD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAkB3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAezB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAkC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAiBzB;;CACF;eA7gBc,SAAS;4BADI,sBAAsB;kBARhC,OAAO;iBAIR,MAAM"}
+{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../lib/FileObject.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;GAcG;AAEH;uBAmIe,MAAM;IAlInB;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA2BF;;;;;OAKG;IACH,sBAHW,MAAM,GAAG,UAAU,WACnB,eAAe,GAAC,MAAM,GAAC,IAAI,EAuDrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAclB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,YAFa,MAAM,CAkBlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IACD;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;;;;;;;;;;;;OAeG;IACH,YAXa,UAAU,CAatB;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAsBD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAkB3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAezB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAkC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAiBzB;;CACF;eAtjBc,SAAS;4BADI,sBAAsB;kBARhC,OAAO;iBAIR,MAAM"}

package/src/types/lib/TempDirectoryObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TempDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/TempDirectoryObject.js"],"names":[],"mappings":"AAYA;;;;;;;;;GASG;AACH;IAEE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAxBW,MAAM,OAAC,WACP,mBAAmB,OAAC,EA2C9B;IAqBD;;;;;;;;;;;;;;OAcG;IACH,sBAVW,MAAM,GACJ,mBAAmB,CAY/B;IAED;;;;;;;;;;;;;;OAcG;IACH,kBAVW,MAAM,GACJ,UAAU,CAYtB;;CAUF;kCA1IiC,4BAA4B"}
+{"version":3,"file":"TempDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/TempDirectoryObject.js"],"names":[],"mappings":"AAaA;;;;;;;;;GASG;AACH;IAEE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAxBW,MAAM,OAAC,WACP,mBAAmB,OAAC,EAoF9B;IAsBD;;;;;;;;;;;;;;OAcG;IACH,sBAVW,MAAM,GACJ,mBAAmB,CAY/B;IAED;;;;;;;;;;;;;;OAcG;IACH,kBAVW,MAAM,GACJ,UAAU,CAYtB;;CAUF;kCApLiC,4BAA4B"}