@gesslar/toolkit 3.28.0 → 3.30.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.28.0",
+  "version": "3.30.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -61,7 +61,7 @@
   "devDependencies": {
     "@gesslar/uglier": "^1.2.0",
     "eslint": "^9.39.2",
-    "happy-dom": "^20.3.7",
+    "happy-dom": "^20.4.0",
     "typescript": "^5.9.3"
   },
   "scripts": {

package/src/node/lib/DirectoryObject.js

@@ -5,6 +5,7 @@
  */
 
 import {glob, mkdir, opendir, readdir, rmdir} from "node:fs/promises"
+import {relative} from "node:path"
 import path from "node:path"
 import {URL} from "node:url"
 
@@ -540,75 +541,100 @@ export default class DirectoryObject extends FS {
   /**
    * Creates a new DirectoryObject by extending this directory's path.
    *
+   * Paths are always resolved relative to THIS directory. Any attempt to
+   * escape via `..` or absolute paths is constrained - the `..` segments
+   * are stripped and the remaining path is resolved relative to this directory.
+   *
+   * On Windows, cross-drive absolute paths (e.g., `D:\foo` when base is `C:\`)
+   * are also constrained - the drive root is stripped and the path is resolved
+   * relative to this directory.
+   *
    * Uses overlapping path segment detection to intelligently combine paths.
-   * Preserves the temporary flag from the current directory.
    *
    * @param {string} newPath - The path to append to this directory's path.
    * @returns {DirectoryObject} A new DirectoryObject with the extended path.
    * @example
    * const dir = new DirectoryObject("/projects/git/toolkit")
-   * const subDir = dir.addDirectory("src/lib")
+   * const subDir = dir.getDirectory("src/lib")
    * console.log(subDir.path) // "/projects/git/toolkit/src/lib"
+   *
+   * @example
+   * // Path traversal is constrained to this directory
+   * const dir = new DirectoryObject("/projects/git/toolkit")
+   * const escaped = dir.getDirectory("../../../foo/bar")
+   * console.log(escaped.path) // "/projects/git/toolkit/foo/bar"
    */
   getDirectory(newPath) {
     Valid.type(newPath, "String", {allowEmpty: false})
 
-    // Reject absolute paths
-    if(path.isAbsolute(newPath)) {
-      throw Sass.new(`Absolute paths not allowed: ${newPath}`)
-    }
-
-    // Reject parent directory traversal
-    if(newPath.includes("..")) {
-      throw Sass.new(`Path traversal not allowed: ${newPath} contains '..'`)
-    }
-
+    // New direction: every path is relative to THIS path. Absolute?
+    //  ../../../..? up to this path and then down again if required.
     const thisPath = this.path
     const merged = FS.mergeOverlappingPaths(thisPath, newPath)
     const resolved = FS.resolvePath(thisPath, merged)
+    let local = relative(thisPath, resolved)
 
-    // Final safety check
-    if(!FS.pathContains(thisPath, resolved)) {
-      throw Sass.new(`Path resolves outside directory: ${newPath}`)
-    }
+    // On Windows, cross-drive paths return absolute - strip the root
+    if(path.isAbsolute(local))
+      local = local.slice(path.parse(local).root.length)
+
+    const parts = local.split(this.sep)
+
+    while(parts[0] === "..")
+      parts.shift()
+
+    const newLocal = parts.join(this.sep)
 
-    return new this.constructor(resolved)
+    return new this.constructor(FS.resolvePath(this.path, newLocal))
   }
 
   /**
    * Creates a new FileObject by extending this directory's path.
    *
+   * Paths are always resolved relative to THIS directory. Any attempt to
+   * escape via `..` or absolute paths is constrained - the `..` segments
+   * are stripped and the remaining path is resolved relative to this directory.
+   *
+   * On Windows, cross-drive absolute paths (e.g., `D:\foo` when base is `C:\`)
+   * are also constrained - the drive root is stripped and the path is resolved
+   * relative to this directory.
+   *
    * Uses overlapping path segment detection to intelligently combine paths.
    *
    * @param {string} filename - The filename to append to this directory's path.
    * @returns {FileObject} A new FileObject with the extended path.
    * @example
    * const dir = new DirectoryObject("/projects/git/toolkit")
-   * const file = dir.addFile("package.json")
+   * const file = dir.getFile("package.json")
    * console.log(file.path) // "/projects/git/toolkit/package.json"
+   *
+   * @example
+   * // Path traversal is constrained to this directory
+   * const dir = new DirectoryObject("/projects/git/toolkit")
+   * const escaped = dir.getFile("../../../foo/bar.js")
+   * console.log(escaped.path) // "/projects/git/toolkit/foo/bar.js"
    */
   getFile(filename) {
     Valid.type(filename, "String", {allowEmpty: false})
 
-    // Reject absolute paths
-    if(path.isAbsolute(filename)) {
-      throw Sass.new(`Absolute paths not allowed: ${filename}`)
-    }
-
-    // Reject parent directory traversal
-    if(filename.includes("..")) {
-      throw Sass.new(`Path traversal not allowed: ${filename} contains '..'`)
-    }
-
+    // Every path is relative to THIS path. Absolute or .. paths
+    // are constrained to this directory.
     const thisPath = this.path
     const merged = FS.mergeOverlappingPaths(thisPath, filename)
     const resolved = FS.resolvePath(thisPath, merged)
+    let local = relative(thisPath, resolved)
 
-    // Final safety check
-    if(!FS.pathContains(thisPath, resolved)) {
-      throw Sass.new(`Path resolves outside directory: ${filename}`)
-    }
+    // On Windows, cross-drive paths return absolute - strip the root
+    if(path.isAbsolute(local))
+      local = local.slice(path.parse(local).root.length)
+
+    const parts = local.split(this.sep)
+
+    while(parts[0] === "..")
+      parts.shift()
+
+    const newLocal = parts.join(this.sep)
 
-    return new FileObject(resolved)
+    return new FileObject(newLocal, this)
   }
 }

package/src/node/lib/FileSystem.js

@@ -251,11 +251,11 @@ export default class FileSystem {
    * @param {string} [sep=path.sep] - The path separator to use (defaults to system separator)
    * @returns {string|null} The relative path, empty string if paths are identical, or null if no overlap found
    * @example
-   * FS.toRelativePath("/projects/toolkit", "/projects/toolkit/src") // "src"
-   * FS.toRelativePath("/home/user", "/home/user") // ""
-   * FS.toRelativePath("/projects/app", "/other/path") // null
+   * FS.toLocalRelativePath("/projects/toolkit", "/projects/toolkit/src") // "src"
+   * FS.toLocalRelativePath("/home/user", "/home/user") // ""
+   * FS.toLocalRelativePath("/projects/app", "/other/path") // null
    */
-  static toRelativePath(from, to, sep=path.sep) {
+  static toLocalRelativePath(from, to, sep=path.sep) {
     // If they're the same, just return ""
     if(from === to)
       return ""
@@ -276,20 +276,46 @@ export default class FileSystem {
   }
 
   /**
-   * Find the common root path between two paths by identifying overlapping segments.
-   * Returns the portion of 'from' that matches up to the overlap point in 'to'.
+   * Computes the relative path from one path to another using Node's path.relative.
+   *
+   * Unlike toLocalRelativePath which uses overlap detection, this method uses
+   * standard relative path calculation and may return paths with ".." segments.
+   *
+   * @static
+   * @param {string} from - The base path to calculate relative from
+   * @param {string} to - The target path to make relative
+   * @returns {string} The relative path, or empty string if paths are identical
+   * @example
+   * FS.toRelativePath("/home/user", "/home/user/docs") // "docs"
+   * FS.toRelativePath("/home/user", "/home/user") // ""
+   * FS.toRelativePath("/home/user", "/home/other") // "../other"
+   */
+  static toRelativePath(from, to) {
+    // If they're the same, just return ""
+    if(from === to)
+      return ""
+
+    return path.relative(from, to)
+  }
+
+  /**
+   * Find where a path's final segment appears in another path, returning the
+   * portion of 'from' up to that overlap point.
+   *
+   * Looks for the last segment of `from` within `to`. If found, returns `from`
+   * sliced to the index where that segment appears in `to`.
    *
    * @static
-   * @param {string} from - The first path to compare
-   * @param {string} to - The second path to find common root with
+   * @param {string} from - The source path whose final segment to search for
+   * @param {string} to - The target path to search within
    * @param {string} [sep=path.sep] - The path separator to use (defaults to system separator)
-   * @returns {string|null} The common root path, the original path if identical, or null if no overlap found
+   * @returns {string|null} The sliced portion of from, the original path if identical, or null if no overlap
    * @throws {Sass} If from is not a non-empty string
    * @throws {Sass} If to is not a non-empty string
    * @example
-   * FS.getCommonRootPath("/projects/toolkit/src", "/projects/toolkit/tests") // "/projects/toolkit"
+   * FS.getCommonRootPath("/projects/toolkit", "/projects/toolkit/src") // "/projects/toolkit"
    * FS.getCommonRootPath("/home/user", "/home/user") // "/home/user"
-   * FS.getCommonRootPath("/projects/app", "/other/path") // null
+   * FS.getCommonRootPath("/projects/app", "/other/path") // null (no overlap)
    */
   static getCommonRootPath(from, to, sep=path.sep) {
     Valid.type(from, "String", {allowEmpty: false})

package/src/node/lib/Term.js

@@ -3,9 +3,29 @@ import process from "node:process"
 import {Writable} from "node:stream"
 import supportsColor from "supports-color"
 import {stripVTControlCharacters} from "node:util"
+import c from "@gesslar/colours"
 
 import Sass from "./Sass.js"
 
+c.alias.set("success", "{F035}")
+c.alias.set("info", "{F033}")
+c.alias.set("warn", "{F208}")
+c.alias.set("error", "{F032}")
+c.alias.set("modified", "{F147}")
+
+/**
+ * Terminal output utilities with ANSI colour support.
+ *
+ * Provides console logging wrappers, cursor control, and formatted message
+ * output with colour styling via `@gesslar/colours`.
+ *
+ * Predefined colour aliases:
+ * - `success` - green (F035)
+ * - `info` - blue (F033)
+ * - `warn` - orange (F208)
+ * - `error` - red (F032)
+ * - `modified` - purple (F147)
+ */
 export default class Term {
   static #cache = new Map()
 
@@ -217,17 +237,17 @@ export default class Term {
   }
 
   /**
-   * Constructs a formatted status line.
+   * Constructs a formatted status line with optional colour styling.
    *
    * Input forms:
    *  - string: printed as-is
    *  - array: each element is either:
    *    - a plain string (emitted unchanged), or
-   *    - a tuple: [level, text] where `level` maps to an ansiColors alias
-   *        (e.g. success, info, warn, error, modified).
-   *    - a tuple: [level, text, [openBracket,closeBracket]] where `level` maps to an ansiColors alias
-   *        (e.g. success, info, warn, error, modified). These are rendered as
-   *        colourised bracketed segments: [TEXT].
+   *    - a tuple: [colourCode, text] where `colourCode` is a colour alias
+   *        (e.g. success, info, warn, error, modified) or any valid
+   *        `@gesslar/colours` format string.
+   *    - a tuple: [colourCode, text, [openBracket, closeBracket]] for custom
+   *        brackets around the colourised text.
    *
    * The function performs a shallow validation: tuple elements must both be
    * strings; otherwise a TypeError is thrown. Nested arrays beyond depth 1 are
@@ -236,8 +256,8 @@ export default class Term {
    * Recursion: array input is normalised into a single string then re-dispatched
    * through `status` to leverage the string branch (keeps logic DRY).
    *
-   * @param {string | Array<string | [string, string] | [string, string, string]>} argList - Message spec.
-   * @returns {void}
+   * @param {string | Array<string | [string, string] | [string, string, [string, string]]>} argList - Message spec.
+   * @returns {string} The formatted message string.
    */
   static terminalMessage(argList) {
     if(typeof argList === "string")
@@ -269,34 +289,33 @@ export default class Term {
 
   /**
    * Construct a single coloured bracketed segment from a tuple specifying
-   * the style level and the text. The first element ("level") maps to an
-   * `ansiColors` alias (e.g. success, info, warn, error, modified) and is
-   * used both for the inner text colour and to locate its matching
-   * "-bracket" alias for the surrounding square brackets. The second
-   * element is the raw text to display.
+   * the colour code and text. The first element is a colour code that can be
+   * a predefined alias (success, info, warn, error, modified) or any valid
+   * `@gesslar/colours` format string. The brackets are coloured while the
+   * inner text remains uncoloured.
    *
-   * Input validation: every element of `parts` must be a string; otherwise
-   * an `Sass` error is thrown. (Additional elements beyond the first two are
-   * ignored – the method destructures only the first pair.)
+   * Input validation: colourCode and text must both be strings; otherwise
+   * a `Sass` error is thrown.
    *
    * Example:
-   *  terminalBracket(["success", "COMPILED"]) → "[COMPILED]" with coloured
-   *  brackets + inner text (assuming colour support is available in the
-   *  terminal).
+   *  terminalBracket(["success", "COMPILED"]) → "[COMPILED]" with green
+   *  brackets (assuming colour support is available in the terminal).
+   *
+   *  terminalBracket(["info", "STATUS", ["<", ">"]]) → "<STATUS>" with blue
+   *  angle brackets.
    *
    * This method does not append trailing spaces; callers are responsible for
    * joining multiple segments with appropriate separators.
    *
-   * @param {Array<string>} parts - Tuple: [level, text]. Additional entries ignored.
+   * @param {[string, string, [string, string]?]} parts - Tuple: [colourCode, text, brackets?].
    * @returns {string} Colourised bracketed segment (e.g. "[TEXT]").
-   * @throws {Sass} If any element of `parts` is not a string.
+   * @throws {Sass} If colourCode or text is not a string.
    */
-  static terminalBracket([level, text, brackets=["[","]"]]) {
-    if(!(typeof level === "string" && typeof text === "string"))
+  static terminalBracket([colourCode="", text, brackets=["[","]"]]) {
+    if(!(typeof colourCode === "string" && typeof text === "string"))
       throw Sass.new("Each element must be a string.")
 
-    // Simplified version without color support - just return bracketed text
-    return `${brackets[0]}${text}${brackets[1]}`
+    return this.#preformat(c`{${colourCode}}${brackets[0]}{/}${text}{${colourCode}}${brackets[1]}{/}`)
   }
 
   /**

package/types/node/lib/DirectoryObject.d.ts

@@ -266,28 +266,55 @@ export default class DirectoryObject extends FS {
     /**
      * Creates a new DirectoryObject by extending this directory's path.
      *
+     * Paths are always resolved relative to THIS directory. Any attempt to
+     * escape via `..` or absolute paths is constrained - the `..` segments
+     * are stripped and the remaining path is resolved relative to this directory.
+     *
+     * On Windows, cross-drive absolute paths (e.g., `D:\foo` when base is `C:\`)
+     * are also constrained - the drive root is stripped and the path is resolved
+     * relative to this directory.
+     *
      * Uses overlapping path segment detection to intelligently combine paths.
-     * Preserves the temporary flag from the current directory.
      *
      * @param {string} newPath - The path to append to this directory's path.
      * @returns {DirectoryObject} A new DirectoryObject with the extended path.
      * @example
      * const dir = new DirectoryObject("/projects/git/toolkit")
-     * const subDir = dir.addDirectory("src/lib")
+     * const subDir = dir.getDirectory("src/lib")
      * console.log(subDir.path) // "/projects/git/toolkit/src/lib"
+     *
+     * @example
+     * // Path traversal is constrained to this directory
+     * const dir = new DirectoryObject("/projects/git/toolkit")
+     * const escaped = dir.getDirectory("../../../foo/bar")
+     * console.log(escaped.path) // "/projects/git/toolkit/foo/bar"
      */
     getDirectory(newPath: string): DirectoryObject;
     /**
      * Creates a new FileObject by extending this directory's path.
      *
+     * Paths are always resolved relative to THIS directory. Any attempt to
+     * escape via `..` or absolute paths is constrained - the `..` segments
+     * are stripped and the remaining path is resolved relative to this directory.
+     *
+     * On Windows, cross-drive absolute paths (e.g., `D:\foo` when base is `C:\`)
+     * are also constrained - the drive root is stripped and the path is resolved
+     * relative to this directory.
+     *
      * Uses overlapping path segment detection to intelligently combine paths.
      *
      * @param {string} filename - The filename to append to this directory's path.
      * @returns {FileObject} A new FileObject with the extended path.
      * @example
      * const dir = new DirectoryObject("/projects/git/toolkit")
-     * const file = dir.addFile("package.json")
+     * const file = dir.getFile("package.json")
      * console.log(file.path) // "/projects/git/toolkit/package.json"
+     *
+     * @example
+     * // Path traversal is constrained to this directory
+     * const dir = new DirectoryObject("/projects/git/toolkit")
+     * const escaped = dir.getFile("../../../foo/bar.js")
+     * console.log(escaped.path) // "/projects/git/toolkit/foo/bar.js"
      */
     getFile(filename: string): FileObject;
     #private;

package/types/node/lib/DirectoryObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAuDE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA7CD;;;;OAIG;IACH,uBAFW,MAAM,OAAC,EA4BjB;IAyBD;;;;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;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAsBhC;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAmBD;;;;;;;;;;;;;;;;;OAiBG;IACH,WAZW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CA8CpF;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAZW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAiD/F;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAuBzB;IAyBD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,eAAe,CAc3B;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAED;;;;;;;;;;;;OAYG;IACH,sBAPW,MAAM,GACJ,eAAe,CA6B3B;IAED;;;;;;;;;;;OAWG;IACH,kBAPW,MAAM,GACJ,UAAU,CA6BtB;;CACF;;UAnlBa,MAAY;QAAC,KAAK,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC;eACnD,MAAY,aAAa;;;;;;iBAMzB,OAAO;;;;eACP,MAAM,GAAC,IAAI;;;;YACX,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;YACX,eAAe,GAAC,SAAS;;;;gBACzB,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;SACX,MAAM,GAAC,IAAI;;;;cACX,MAAM,GAAC,IAAI;;;;WACX,KAAK,CAAC,MAAM,CAAC,GAAC,IAAI;;;;SAClB,GAAG,GAAC,IAAI;;eAvBP,iBAAiB;uBADT,iBAAiB"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/DirectoryObject.js"],"names":[],"mappings":"AAiBA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAuDE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA7CD;;;;OAIG;IACH,uBAFW,MAAM,OAAC,EA4BjB;IAyBD;;;;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;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAsBhC;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAmBD;;;;;;;;;;;;;;;;;OAiBG;IACH,WAZW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CA8CpF;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAZW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAiD/F;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAuBzB;IAyBD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,eAAe,CAc3B;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,sBAbW,MAAM,GACJ,eAAe,CAkC3B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAbW,MAAM,GACJ,UAAU,CAkCtB;;CACF;;UA5mBa,MAAY;QAAC,KAAK,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC;eACnD,MAAY,aAAa;;;;;;iBAMzB,OAAO;;;;eACP,MAAM,GAAC,IAAI;;;;YACX,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;YACX,eAAe,GAAC,SAAS;;;;gBACzB,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;SACX,MAAM,GAAC,IAAI;;;;cACX,MAAM,GAAC,IAAI;;;;WACX,KAAK,CAAC,MAAM,CAAC,GAAC,IAAI;;;;SAClB,GAAG,GAAC,IAAI;;eAvBP,iBAAiB;uBADT,iBAAiB"}

package/types/node/lib/FileSystem.d.ts

@@ -101,26 +101,45 @@ export default class FileSystem {
      * @param {string} [sep=path.sep] - The path separator to use (defaults to system separator)
      * @returns {string|null} The relative path, empty string if paths are identical, or null if no overlap found
      * @example
-     * FS.toRelativePath("/projects/toolkit", "/projects/toolkit/src") // "src"
+     * FS.toLocalRelativePath("/projects/toolkit", "/projects/toolkit/src") // "src"
+     * FS.toLocalRelativePath("/home/user", "/home/user") // ""
+     * FS.toLocalRelativePath("/projects/app", "/other/path") // null
+     */
+    static toLocalRelativePath(from: string, to: string, sep?: string): string | null;
+    /**
+     * Computes the relative path from one path to another using Node's path.relative.
+     *
+     * Unlike toLocalRelativePath which uses overlap detection, this method uses
+     * standard relative path calculation and may return paths with ".." segments.
+     *
+     * @static
+     * @param {string} from - The base path to calculate relative from
+     * @param {string} to - The target path to make relative
+     * @returns {string} The relative path, or empty string if paths are identical
+     * @example
+     * FS.toRelativePath("/home/user", "/home/user/docs") // "docs"
      * FS.toRelativePath("/home/user", "/home/user") // ""
-     * FS.toRelativePath("/projects/app", "/other/path") // null
+     * FS.toRelativePath("/home/user", "/home/other") // "../other"
      */
-    static toRelativePath(from: string, to: string, sep?: string): string | null;
+    static toRelativePath(from: string, to: string): string;
     /**
-     * Find the common root path between two paths by identifying overlapping segments.
-     * Returns the portion of 'from' that matches up to the overlap point in 'to'.
+     * Find where a path's final segment appears in another path, returning the
+     * portion of 'from' up to that overlap point.
+     *
+     * Looks for the last segment of `from` within `to`. If found, returns `from`
+     * sliced to the index where that segment appears in `to`.
      *
      * @static
-     * @param {string} from - The first path to compare
-     * @param {string} to - The second path to find common root with
+     * @param {string} from - The source path whose final segment to search for
+     * @param {string} to - The target path to search within
      * @param {string} [sep=path.sep] - The path separator to use (defaults to system separator)
-     * @returns {string|null} The common root path, the original path if identical, or null if no overlap found
+     * @returns {string|null} The sliced portion of from, the original path if identical, or null if no overlap
      * @throws {Sass} If from is not a non-empty string
      * @throws {Sass} If to is not a non-empty string
      * @example
-     * FS.getCommonRootPath("/projects/toolkit/src", "/projects/toolkit/tests") // "/projects/toolkit"
+     * FS.getCommonRootPath("/projects/toolkit", "/projects/toolkit/src") // "/projects/toolkit"
      * FS.getCommonRootPath("/home/user", "/home/user") // "/home/user"
-     * FS.getCommonRootPath("/projects/app", "/other/path") // null
+     * FS.getCommonRootPath("/projects/app", "/other/path") // null (no overlap)
      */
     static getCommonRootPath(from: string, to: string, sep?: string): string | null;
     /**

package/types/node/lib/FileSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileSystem.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileSystem.js"],"names":[],"mappings":"AA2BA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAsBtB;;;;;;OAMG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;OAQG;IACH,0BALW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;;;;;OAUG;IACH,gCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;;;;OAUG;IACH,oCAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;OASG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA0BlB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAmClB;IAED;;;;;;;;;;;;OAYG;IACH,+BATW,MAAM,aACN,MAAM,GACJ,OAAO,CAcnB;IAED;;;;;;;;;;;;;;OAcG;IACH,4BATW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAwBvB;IAED;;;;;;;;;;;;;;;OAeG;IACH,+BAXW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CA+BvB;IAED;;;;;;;OAOG;IAEH;;;;;;;OAOG;IACH,2BAJW,MAAM;;;;cAXH,MAAM;;;;aACN,MAAM;;;;aACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM;MAenB;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAzTD;;;;;;;;;OASG;IACH,kCAJW,UAAU,GAAC,eAAe,GACxB,MAAM,CAWlB;CAwSF;yBA3Ua,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}
+{"version":3,"file":"FileSystem.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileSystem.js"],"names":[],"mappings":"AA2BA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAsBtB;;;;;;OAMG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;OAQG;IACH,0BALW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;;;;;OAUG;IACH,gCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;;;;OAUG;IACH,oCAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;OASG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA0BlB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAmClB;IAED;;;;;;;;;;;;OAYG;IACH,+BATW,MAAM,aACN,MAAM,GACJ,OAAO,CAcnB;IAED;;;;;;;;;;;;;;OAcG;IACH,iCATW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAwBvB;IAED;;;;;;;;;;;;;;OAcG;IACH,4BARW,MAAM,MACN,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,+BAXW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CA+BvB;IAED;;;;;;;OAOG;IAEH;;;;;;;OAOG;IACH,2BAJW,MAAM;;;;cAXH,MAAM;;;;aACN,MAAM;;;;aACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM;MAenB;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAnVD;;;;;;;;;OASG;IACH,kCAJW,UAAU,GAAC,eAAe,GACxB,MAAM,CAWlB;CAkUF;yBArWa,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}

package/types/node/lib/Term.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Terminal output utilities with ANSI colour support.
+ *
+ * Provides console logging wrappers, cursor control, and formatted message
+ * output with colour styling via `@gesslar/colours`.
+ *
+ * Predefined colour aliases:
+ * - `success` - green (F035)
+ * - `info` - blue (F033)
+ * - `warn` - orange (F208)
+ * - `error` - red (F032)
+ * - `modified` - purple (F147)
+ */
 export default class Term {
     static "__#private@#cache": Map<any, any>;
     static "__#private@#preformat"(text: any): any;
@@ -107,17 +120,17 @@ export default class Term {
         silent: boolean;
     }): void;
     /**
-     * Constructs a formatted status line.
+     * Constructs a formatted status line with optional colour styling.
      *
      * Input forms:
      *  - string: printed as-is
      *  - array: each element is either:
      *    - a plain string (emitted unchanged), or
-     *    - a tuple: [level, text] where `level` maps to an ansiColors alias
-     *        (e.g. success, info, warn, error, modified).
-     *    - a tuple: [level, text, [openBracket,closeBracket]] where `level` maps to an ansiColors alias
-     *        (e.g. success, info, warn, error, modified). These are rendered as
-     *        colourised bracketed segments: [TEXT].
+     *    - a tuple: [colourCode, text] where `colourCode` is a colour alias
+     *        (e.g. success, info, warn, error, modified) or any valid
+     *        `@gesslar/colours` format string.
+     *    - a tuple: [colourCode, text, [openBracket, closeBracket]] for custom
+     *        brackets around the colourised text.
      *
      * The function performs a shallow validation: tuple elements must both be
      * strings; otherwise a TypeError is thrown. Nested arrays beyond depth 1 are
@@ -126,35 +139,35 @@ export default class Term {
      * Recursion: array input is normalised into a single string then re-dispatched
      * through `status` to leverage the string branch (keeps logic DRY).
      *
-     * @param {string | Array<string | [string, string] | [string, string, string]>} argList - Message spec.
-     * @returns {void}
+     * @param {string | Array<string | [string, string] | [string, string, [string, string]]>} argList - Message spec.
+     * @returns {string} The formatted message string.
      */
-    static terminalMessage(argList: string | Array<string | [string, string] | [string, string, string]>): void;
+    static terminalMessage(argList: string | Array<string | [string, string] | [string, string, [string, string]]>): string;
     /**
      * Construct a single coloured bracketed segment from a tuple specifying
-     * the style level and the text. The first element ("level") maps to an
-     * `ansiColors` alias (e.g. success, info, warn, error, modified) and is
-     * used both for the inner text colour and to locate its matching
-     * "-bracket" alias for the surrounding square brackets. The second
-     * element is the raw text to display.
+     * the colour code and text. The first element is a colour code that can be
+     * a predefined alias (success, info, warn, error, modified) or any valid
+     * `@gesslar/colours` format string. The brackets are coloured while the
+     * inner text remains uncoloured.
      *
-     * Input validation: every element of `parts` must be a string; otherwise
-     * an `Sass` error is thrown. (Additional elements beyond the first two are
-     * ignored – the method destructures only the first pair.)
+     * Input validation: colourCode and text must both be strings; otherwise
+     * a `Sass` error is thrown.
      *
      * Example:
-     *  terminalBracket(["success", "COMPILED"]) → "[COMPILED]" with coloured
-     *  brackets + inner text (assuming colour support is available in the
-     *  terminal).
+     *  terminalBracket(["success", "COMPILED"]) → "[COMPILED]" with green
+     *  brackets (assuming colour support is available in the terminal).
+     *
+     *  terminalBracket(["info", "STATUS", ["<", ">"]]) → "<STATUS>" with blue
+     *  angle brackets.
      *
      * This method does not append trailing spaces; callers are responsible for
      * joining multiple segments with appropriate separators.
      *
-     * @param {Array<string>} parts - Tuple: [level, text]. Additional entries ignored.
+     * @param {[string, string, [string, string]?]} parts - Tuple: [colourCode, text, brackets?].
      * @returns {string} Colourised bracketed segment (e.g. "[TEXT]").
-     * @throws {Sass} If any element of `parts` is not a string.
+     * @throws {Sass} If colourCode or text is not a string.
      */
-    static terminalBracket([level, text, brackets]: Array<string>): string;
+    static terminalBracket([colourCode, text, brackets]: [string, string, [string, string]?]): string;
     /**
      * ANSI escape sequence to move cursor to start of line.
      *

package/types/node/lib/Term.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Term.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Term.js"],"names":[],"mappings":"AAQA;IACE,0CAAyB;IAEzB,+CAIC;IAED;;;;OAIG;IACH,sBAFU,MAAM,GAAG,SAAS,CAI3B;IAED;;;;OAIG;IACH,mBAFU,MAAM,GAAG,SAAS,CAI3B;IAED;;;;OAIG;IACH,kBAFU;QAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAIhE;IAED;;;;OAIG;IACH,4BAFU,OAAO,CAMhB;IAED;;;;OAIG;IACH,uBAFU,OAAO,CAMhB;IAED;;;;OAIG;IACH,oBAFc,OAAO,EAAA,QAIpB;IAED;;;;OAIG;IACH,qBAFc,OAAO,EAAA,QAIpB;IAED;;;;OAIG;IACH,qBAFc,OAAO,EAAA,QAIpB;IAED;;;;OAIG;IACH,sBAFc,OAAO,EAAA,QAIpB;IAED;;;;OAIG;IACH,sBAFc,OAAO,EAAA,QAIpB;IAED;;;;OAIG;IACH,sBAFc,OAAO,EAAA,QAIpB;IAED;;OAEG;IACH,wBAEC;IAED;;;;;;;;OAQG;IACH,0BANW,MAAM,QAAQ,YAEtB;QAAgC,UAAU,GAAlC,KAAK,CAAC,MAAM,CAAC;QACK,UAAU,GAA5B,OAAO;QACW,aAAa,GAA/B,OAAO;KACjB,QA2DA;IAED;;;;;;;;;;;;;;OAcG;IACH,oBALW,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,eAEjD;QAAyB,MAAM,EAAvB,OAAO;KACf,GAAU,IAAI,CAOhB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gCAHW,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,GAClE,IAAI,CA4BhB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,gDAJW,KAAK,CAAC,MAAM,CAAC,GACX,MAAM,CASlB;IAED;;;;OAIG;IACH,oBAFU,MAAM,CAIf;IAED;;;;OAIG;IACH,oBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,kBAFU,MAAM,CAIf;IAED;;;;OAIG;IACH,kBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,iBAFU,MAAM,CAIf;IAED;;;;;OAKG;IACH,mBAHW,MAAM,GACJ,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,qBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,qBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,yBAFU,OAAO,CAOhB;IAED;;;;OAIG;IACH,yBAFU,OAAO,CAOhB;IAED;;;;OAIG;IACH,sBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,sBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,oBAFa,OAAO,IAAI,CAMvB;IAED;;;;;OAKG;IACH,uBAHW,MAAM,GACJ,OAAO,IAAI,CAOvB;IAED;;;;;OAKG;IACH,qBAHW,MAAM,GACJ,OAAO,IAAI,CAMvB;IAED;;;;;;OAMG;IACH,yBAHW,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACvB,OAAO,CAAC,MAAM,CAAC,CAyD3B;IAED;;;;OAIG;IACH,4BAFa,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAqCrC;IAED;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAMzB;IAID,0CAAuE;CAYxE"}
+{"version":3,"file":"Term.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Term.js"],"names":[],"mappings":"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"}