@silo-code/sdk 0.20.0 → 0.22.0

package/src/file-service.ts

@@ -24,6 +24,16 @@ export interface FileMeta {
   modifiedMs: number;
 }
 
+/**
+ * The normalized kind of a filesystem change, as delivered in
+ * {@link FileChangeEvent.kind}. Backend-specific event kinds that don't map to
+ * one of the three meaningful values are surfaced as `"other"`.
+ *
+ * @category Core Types
+ * @public
+ */
+export type FileChangeKind = "create" | "modify" | "remove" | "other";
+
 /**
  * A filesystem change event delivered to a {@link FileService.watch} listener,
  * for changes under that watch's path.
@@ -34,8 +44,12 @@ export interface FileMeta {
 export interface FileChangeEvent {
   /** The paths that changed in this event. */
   paths: string[];
-  /** The backend's change kind (e.g. `"create"`, `"modify"`, `"remove"`). */
-  kind: string;
+  /**
+   * Normalized change kind. The host maps the backend's vocabulary to this
+   * closed union; backend-specific kinds that don't match arrive as `"other"`.
+   * Always compare against the union values — never against raw backend strings.
+   */
+  kind: FileChangeKind;
 }
 
 /**
@@ -68,15 +82,46 @@ export interface FileService {
   readBytes(path: string): Promise<ArrayBuffer>;
   /** List a directory's immediate entries. */
   readDir(path: string): Promise<FileMeta[]>;
-  /** Resolve true if a file or directory exists at `path`. */
+  /**
+   * Resolve true if a file or directory exists at `path`. Prefer
+   * {@link FileService.stat} when you also need the entry's metadata — `stat`
+   * returning non-`null` subsumes this check in one call.
+   */
   pathExists(path: string): Promise<boolean>;
+  /**
+   * Metadata for a single path, following symlinks, or `null` if nothing
+   * exists there. Resolving `null` (rather than rejecting) for an absent path
+   * is deliberate — it makes `stat` a one-call replacement for
+   * {@link FileService.pathExists} that also returns size / mtime / type.
+   * Rejects only on a real I/O error (e.g. a permission failure).
+   */
+  stat(path: string): Promise<FileMeta | null>;
   /** Write UTF-8 text to a file, creating or overwriting it. */
   writeText(path: string, content: string): Promise<void>;
+  /**
+   * Write raw bytes to a file, creating or overwriting it (and creating any
+   * missing parent directories). The byte-oriented counterpart to
+   * {@link FileService.writeText} / {@link FileService.readBytes} — use it for
+   * binary assets (images, archives) where `writeText` would corrupt the data.
+   */
+  writeBytes(path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
   /** Create a directory (and any missing parents). */
   createDir(path: string): Promise<void>;
+  /**
+   * Copy a file or directory from `src` to `dest`, recursively for
+   * directories, creating any missing parent directories. Requires read access
+   * to `src` and write access to `dest` (both are workspace-scoped). Overwrites
+   * existing files at the destination.
+   */
+  copy(src: string, dest: string): Promise<void>;
   /** Rename / move a file or directory. */
   rename(oldPath: string, newPath: string): Promise<void>;
-  /** Delete a file or directory. */
+  /**
+   * **Permanently** delete a file or directory (directories are removed
+   * recursively). This does **not** move the entry to the OS trash/recycle
+   * bin — the delete is irreversible, so confirm destructive removals with the
+   * user first. Rejects if the path does not exist.
+   */
   delete(path: string): Promise<void>;
   /** Reveal a path in the OS file manager (Finder / Explorer). */
   reveal(path: string): Promise<void>;

package/src/index.ts

@@ -1,10 +1,16 @@
 /**
- * The public Silo extension API surface — the single curated entry point an
- * extension author imports from. This is the seed of the future `@silo-code/sdk`
- * package: it re-exports **only** the blessed, permanently supported types.
- * Anything not re-exported here is host-internal and may change without notice.
+ * The `@silo-code/sdk` public surface — the single curated entry point an
+ * extension author imports from. Re-exports **only** the blessed, permanently
+ * supported types and runtime helpers. Anything not re-exported here is
+ * host-internal and may change without notice.
  *
- * It is also the entry point the API-reference generator (TypeDoc) reads, so
+ * **What's here:** the types-first extension contract (see `types.ts`) plus a
+ * small set of blessed runtime helpers (`Tooltip`, `useFocusGroup`,
+ * `useServiceState`, `DND_MIME`, `PathDeniedError`, `NetworkError`). The SDK
+ * peer-depends on React 19; changes to the runtime helpers can be breaking
+ * even when the types are unchanged.
+ *
+ * This is also the entry point the API-reference generator (TypeDoc) reads, so
  * the published reference is exactly this surface — no more, no less.
  *
  * @packageDocumentation
@@ -66,6 +72,9 @@ export type {
   DiffContent,
   DiffContentRequest,
   DiffContentProvider,
+  ActiveEditorInfo,
+  EditorsState,
+  EditorSaveEvent,
 } from "./editor-service";
 export type {
   LayoutService,
@@ -94,7 +103,12 @@ export type {
   TerminalTabDecorationProvider,
   OscEvent,
 } from "./terminal-service";
-export type { FileService, FileMeta, FileChangeEvent } from "./file-service";
+export type {
+  FileService,
+  FileMeta,
+  FileChangeKind,
+  FileChangeEvent,
+} from "./file-service";
 // Cross-file content search exposed on the ExtensionContext as `ctx.search`.
 export type {
   SearchService,
@@ -157,10 +171,12 @@ export type {
 } from "./ui-service";
 
 // Server-side HTTP client — bypasses CORS, readable response headers.
+export { NetworkError } from "./network-service";
 export type {
   NetworkService,
   NetworkRequestOptions,
   NetworkResponse,
+  NetworkBytesResponse,
 } from "./network-service";
 
 // Static host-platform metadata: OS, CPU arch, and Silo version.
@@ -174,6 +190,15 @@ export type { LogService, LogLevel } from "./output-service";
 // Context keys referenced by `when` predicates on menu items / keybindings.
 export type { ContextKeys } from "./context-keys";
 
+// Typed event primitive: a subscribable Event<T> that returns a Disposable.
+// The matching host-side emitter is internal to the extension-host package.
+export type { Event } from "./event";
+
+// Pure path utilities — cross-platform replacement for `node:path` (banned in
+// extensions). All outputs use forward-slash separators. Both "/" and "\" are
+// accepted as input. Exported as a namespaced `path` object.
+export { path } from "./path";
+
 // Tooltip — the same styled hover popup the host uses in the status bar.
 // Extensions use this instead of native `title` attributes to match host chrome.
 export { Tooltip } from "./Tooltip";

package/src/layout-service.ts

@@ -60,21 +60,23 @@ export interface LayoutService {
    * web-viewer tab). No-op when the center dock has no active workspace.
    *
    * @param kindId - The {@link DockPanelKind.id} to instantiate.
-   * @param params - Arbitrary params forwarded to the panel's
-   *   `IDockviewPanelProps`. Serialized into `ws.dockLayout` so URL/state
-   *   survives workspace close/reopen.
+   * @param params - Arbitrary params forwarded to the panel component.
+   *   Serialized into `ws.dockLayout` so state survives workspace
+   *   close/reopen.
+   * @param options - `singleton: true` opens at most one instance at a time:
+   *   if a panel with `kindId` already exists, it is focused instead of
+   *   creating a new one. The panel's id equals `kindId` (not UUID-based) when
+   *   singleton is set.
    */
-  openPanel(kindId: string, params?: Record<string, unknown>): void;
+  openPanel(
+    kindId: string,
+    params?: Record<string, unknown>,
+    options?: { singleton?: boolean },
+  ): void;
   /**
-   * Open a **singleton** dock panel — a panel that should only ever have one
-   * instance at a time. If a panel with `kindId` already exists, focuses it;
-   * otherwise creates it. The panel's id equals `kindId` (not UUID-based, so
-   * at most one can exist). Use for utility panels like Output that don't
-   * benefit from multiple instances.
-   *
-   * @param kindId - The {@link DockPanelKind.id} to open or focus.
-   * @param params - Forwarded to the panel when creating; ignored when
-   *   focusing an existing instance.
+   * Open a **singleton** dock panel.
+   * @deprecated Use `openPanel(kindId, params, { singleton: true })` instead.
+   *   This method will be removed in a future release.
    */
   openSingletonPanel(kindId: string, params?: Record<string, unknown>): void;
 }

package/src/network-service.ts

@@ -1,3 +1,35 @@
+/**
+ * Thrown by {@link NetworkService.fetch} and {@link NetworkService.fetchHeaders}
+ * when a request fails (network error, DNS failure, TLS error, timeout, etc.).
+ *
+ * ```ts
+ * try {
+ *   const res = await ctx.net.fetch("https://api.example.com/data");
+ * } catch (err) {
+ *   if (err instanceof NetworkError) {
+ *     console.error(`Request to ${err.url} failed: ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @category Core Types
+ * @public
+ */
+export class NetworkError extends Error {
+  /** The URL that was requested when the error occurred. */
+  readonly url: string;
+
+  constructor(url: string, message: string) {
+    super(message);
+    this.name = "NetworkError";
+    this.url = url;
+    // Restore the prototype chain so `instanceof` works across the down-leveled
+    // class output the SDK ships (and across the host↔extension boundary, where
+    // there's a single shared SDK instance).
+    Object.setPrototypeOf(this, NetworkError.prototype);
+  }
+}
+
 /**
  * Options for {@link NetworkService.fetch} and {@link NetworkService.fetchHeaders}.
  *
@@ -12,8 +44,12 @@ export interface NetworkRequestOptions {
   method?: "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH";
   /** Request headers to send. */
   headers?: Record<string, string>;
-  /** Request body (string). Only meaningful for methods that carry a body. */
-  body?: string;
+  /**
+   * Request body. A string is sent as-is; an `ArrayBuffer` / `Uint8Array` is
+   * sent as raw bytes (e.g. uploading a file). Only meaningful for methods that
+   * carry a body.
+   */
+  body?: string | ArrayBuffer | Uint8Array;
   /** Follow HTTP redirects. Defaults to `true`. */
   followRedirects?: boolean;
   /** Request timeout in milliseconds. Omit for the platform default (~30 s). */
@@ -40,6 +76,24 @@ export interface NetworkResponse {
   finalUrl: string;
 }
 
+/**
+ * Response from {@link NetworkService.fetchBytes} — identical to
+ * {@link NetworkResponse} but with the body delivered as raw bytes.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface NetworkBytesResponse {
+  /** HTTP status code. */
+  status: number;
+  /** Response headers, lowercased (multi-value joined with `", "`). */
+  headers: Record<string, string>;
+  /** Response body as raw bytes. */
+  body: ArrayBuffer;
+  /** Final URL after redirects. */
+  finalUrl: string;
+}
+
 /**
  * Server-side HTTP client exposed as {@link ExtensionContext.net}. Requests
  * run in the Rust backend via `reqwest`, so they bypass the browser's CORS
@@ -62,7 +116,7 @@ export interface NetworkService {
    *
    * @param url - The URL to fetch.
    * @param options - Method, headers, body, redirect and timeout controls.
-   * @throws A string error message if the request fails (network error, DNS
+   * @throws {@link NetworkError} if the request fails (network error, DNS
    *   failure, TLS error, etc.).
    *
    * @example
@@ -72,6 +126,33 @@ export interface NetworkService {
    */
   fetch(url: string, options?: NetworkRequestOptions): Promise<NetworkResponse>;
 
+  /**
+   * Like {@link NetworkService.fetch}, but resolves the response body as raw
+   * bytes ({@link NetworkBytesResponse}) instead of decoding it as UTF-8 text —
+   * for downloading images, archives, or any binary payload.
+   *
+   * @param url - The URL to fetch.
+   * @param options - Method, headers, body, redirect and timeout controls. The
+   *   body may itself be binary (`ArrayBuffer` / `Uint8Array`).
+   * @throws {@link NetworkError} if the request fails.
+   *
+   * @remarks
+   * The body rides Tauri's binary IPC channel (no base64), but the whole
+   * response is still buffered in memory on both sides — suitable for typical
+   * asset downloads (up to a few tens of MB), not for streaming multi-hundred-MB
+   * files.
+   *
+   * @example
+   * ```ts
+   * const { body } = await ctx.net.fetchBytes("https://example.com/logo.png");
+   * await ctx.files.writeBytes("logo.png", body);
+   * ```
+   */
+  fetchBytes(
+    url: string,
+    options?: NetworkRequestOptions,
+  ): Promise<NetworkBytesResponse>;
+
   /**
    * Send a `HEAD` request and return only the response headers — no body is
    * downloaded. More efficient than {@link NetworkService.fetch} when you only
@@ -83,7 +164,7 @@ export interface NetworkService {
    * @param url - The URL to probe.
    * @param options - Redirect and timeout controls (`method` and `body` are
    *   ignored — this is always a HEAD request).
-   * @throws A string error message if the request fails.
+   * @throws {@link NetworkError} if the request fails.
    *
    * @example
    * ```ts

package/src/path.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { path } from "./path";
+
+describe("path.normalize", () => {
+  it("collapses dot segments", () =>
+    expect(path.normalize("a/./b")).toBe("a/b"));
+  it("resolves dot-dot segments", () =>
+    expect(path.normalize("a/b/../c")).toBe("a/c"));
+  it("converts backslash to forward-slash", () =>
+    expect(path.normalize("a\\b")).toBe("a/b"));
+  it("collapses duplicate slashes", () =>
+    expect(path.normalize("a//b")).toBe("a/b"));
+  it("preserves POSIX absolute", () =>
+    expect(path.normalize("/a/b")).toBe("/a/b"));
+  it("handles Windows drive", () =>
+    expect(path.normalize("C:\\a\\b")).toBe("C:/a/b"));
+  it("handles Windows drive with forward-slash", () =>
+    expect(path.normalize("C:/a/b")).toBe("C:/a/b"));
+  it("stays at root when dot-dot exceeds root", () =>
+    expect(path.normalize("/a/../..")).toBe("/"));
+  it("returns dot for empty-ish relative path", () =>
+    expect(path.normalize("a/..")).toBe("."));
+  it("UNC path is preserved", () =>
+    expect(path.normalize("\\\\server\\share\\foo")).toBe(
+      "//server/share/foo",
+    ));
+});
+
+describe("path.join", () => {
+  it("joins two segments", () => expect(path.join("a", "b")).toBe("a/b"));
+  it("joins many segments", () =>
+    expect(path.join("a", "b", "c")).toBe("a/b/c"));
+  it("resolves dot-dot across join", () =>
+    expect(path.join("a/b", "../c")).toBe("a/c"));
+  it("preserves leading slash from first segment", () =>
+    expect(path.join("/a", "b")).toBe("/a/b"));
+  it("converts backslash", () => expect(path.join("a\\b", "c")).toBe("a/b/c"));
+  it("returns dot for no arguments", () => expect(path.join()).toBe("."));
+  it("ignores empty string segments", () =>
+    expect(path.join("a", "", "b")).toBe("a/b"));
+  it("handles Windows drive", () =>
+    expect(path.join("C:\\a", "b")).toBe("C:/a/b"));
+  it('join("/", rel) produces "/rel" not "//rel" (UNC)', () =>
+    expect(path.join("/", "linked.md")).toBe("/linked.md"));
+  it("join of POSIX root with nested rel stays absolute", () =>
+    expect(path.join("/", "a/b/../c")).toBe("/a/c"));
+});
+
+describe("path.dirname", () => {
+  it("returns parent dir", () => expect(path.dirname("/a/b/c")).toBe("/a/b"));
+  it("returns slash for top-level file", () =>
+    expect(path.dirname("/a")).toBe("/"));
+  it("returns dot for bare filename", () =>
+    expect(path.dirname("a")).toBe("."));
+  it("handles Windows drive", () =>
+    expect(path.dirname("C:\\a\\b")).toBe("C:/a"));
+  it("returns drive root for top-level", () =>
+    expect(path.dirname("C:\\a")).toBe("C:/"));
+  it("resolves trailing slash before computing", () =>
+    expect(path.dirname("/a/b/")).toBe("/a"));
+  it("handles UNC path", () =>
+    expect(path.dirname("//server/share/foo")).toBe("//server/share"));
+  it("returns dot for relative bare name", () =>
+    expect(path.dirname("file.ts")).toBe("."));
+  it("returns relative parent", () => expect(path.dirname("a/b")).toBe("a"));
+});
+
+describe("path.basename", () => {
+  it("returns last segment", () =>
+    expect(path.basename("/a/b/file.ts")).toBe("file.ts"));
+  it("strips provided extension", () =>
+    expect(path.basename("file.ts", ".ts")).toBe("file"));
+  it("does not strip if extension doesn't match", () =>
+    expect(path.basename("file.ts", ".js")).toBe("file.ts"));
+  it("handles trailing slash", () => expect(path.basename("/a/b/")).toBe("b"));
+  it("handles Windows path", () =>
+    expect(path.basename("C:\\a\\b.txt")).toBe("b.txt"));
+  it("returns empty string for root", () =>
+    expect(path.basename("/")).toBe(""));
+  it("returns bare name", () =>
+    expect(path.basename("file.ts")).toBe("file.ts"));
+});
+
+describe("path.extname", () => {
+  it("returns extension with dot", () =>
+    expect(path.extname("file.ts")).toBe(".ts"));
+  it("returns last extension only", () =>
+    expect(path.extname("file.test.ts")).toBe(".ts"));
+  it("returns empty for no extension", () =>
+    expect(path.extname("file")).toBe(""));
+  it("returns empty for dotfile (dot at position 0)", () =>
+    expect(path.extname(".gitignore")).toBe(""));
+  it("returns dot for trailing dot", () =>
+    expect(path.extname("file.")).toBe("."));
+  it("handles full path", () =>
+    expect(path.extname("/a/b/file.md")).toBe(".md"));
+});
+
+describe("path.isAbsolute", () => {
+  it("true for POSIX absolute", () =>
+    expect(path.isAbsolute("/foo")).toBe(true));
+  it("true for Windows drive with backslash", () =>
+    expect(path.isAbsolute("C:\\foo")).toBe(true));
+  it("true for Windows drive with forward-slash", () =>
+    expect(path.isAbsolute("C:/foo")).toBe(true));
+  it("true for UNC backslash", () =>
+    expect(path.isAbsolute("\\\\server\\share")).toBe(true));
+  it("true for UNC forward-slash", () =>
+    expect(path.isAbsolute("//server/share")).toBe(true));
+  it("false for relative path", () =>
+    expect(path.isAbsolute("foo/bar")).toBe(false));
+  it("false for drive-relative (no slash)", () =>
+    expect(path.isAbsolute("C:foo")).toBe(false));
+  it("false for bare filename", () =>
+    expect(path.isAbsolute("file.ts")).toBe(false));
+});
+
+describe("path.relative", () => {
+  it("computes sibling relative path", () =>
+    expect(path.relative("/a/b", "/a/c")).toBe("../c"));
+  it("returns dot for same path", () =>
+    expect(path.relative("/a/b", "/a/b")).toBe("."));
+  it("returns descendant path", () =>
+    expect(path.relative("/a", "/a/b/c")).toBe("b/c"));
+  it("returns parent path", () =>
+    expect(path.relative("/a/b/c", "/a")).toBe("../.."));
+  it("handles root to subpath", () =>
+    expect(path.relative("/", "/a/b")).toBe("a/b"));
+  it("returns normalized `to` for different Windows drives", () =>
+    expect(path.relative("C:/a", "D:/b")).toBe("D:/b"));
+  it("same drive computes relative", () =>
+    expect(path.relative("C:/a/b", "C:/a/c")).toBe("../c"));
+  it("handles backslash inputs", () =>
+    expect(path.relative("C:\\a\\b", "C:\\a\\c")).toBe("../c"));
+});

package/src/path.ts

@@ -0,0 +1,188 @@
+// Pure path utilities for extensions. A cross-platform replacement for
+// `node:path`, which extensions are banned from importing (platform ban).
+// All outputs use forward-slash separators — the form FileService accepts on
+// every platform. Both "/" and "\" are accepted as inputs.
+
+/** Normalize all separators to forward-slash. */
+function normSep(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+/** Extract a Windows drive-letter prefix ("C:") from a forward-slash path, or null. */
+function parseDrive(p: string): string | null {
+  const m = /^([A-Za-z]):/.exec(p);
+  return m ? m[1].toUpperCase() + ":" : null;
+}
+
+/**
+ * Normalize segments of a forward-slash path: collapse duplicate slashes,
+ * resolve "." and ".." segments. Preserves leading "/" (POSIX absolute),
+ * "C:/" (Windows drive-letter), and "//" (UNC paths).
+ */
+function normSegments(s: string): string {
+  const drive = parseDrive(s);
+  const afterDrive = drive ? s.slice(2) : s;
+  const isUnc = afterDrive.startsWith("//");
+  const isAbs = isUnc || afterDrive.startsWith("/");
+
+  const stack: string[] = [];
+  for (const seg of afterDrive.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (stack.length > 0 && stack[stack.length - 1] !== "..") {
+        stack.pop();
+      } else if (!isAbs) {
+        stack.push("..");
+      }
+    } else {
+      stack.push(seg);
+    }
+  }
+
+  let result = stack.join("/");
+  if (isUnc) result = "//" + result;
+  else if (isAbs) result = "/" + result;
+  if (drive) result = drive + result;
+  if (!result) return isAbs ? (drive ? drive + "/" : "/") : ".";
+  return result;
+}
+
+/**
+ * Path utilities for extensions — a cross-platform replacement for
+ * `node:path`, which extensions are banned from importing. All output paths
+ * use forward-slash separators (the form {@link FileService} accepts on every
+ * platform). Both `/` and `\` are accepted as input separators.
+ *
+ * @example
+ * ```ts
+ * import { path } from "@silo-code/sdk";
+ *
+ * const dir  = path.dirname(filePath);            // "/home/user/docs"
+ * const full = path.join(dir, "images/fig.png");  // "/home/user/docs/images/fig.png"
+ * const rel  = path.relative(dir, full);           // "images/fig.png"
+ * const ext  = path.extname(full);                 // ".png"
+ * ```
+ *
+ * @category Core Types
+ * @public
+ */
+export const path: {
+  /**
+   * Join path segments and normalize the result. Empty segments are ignored;
+   * `\` separators in any segment are treated as `/`.
+   */
+  join(...parts: string[]): string;
+  /**
+   * Return the directory portion of a path — everything up to (not including)
+   * the last `/`. Returns `"."` for a bare filename with no directory component.
+   */
+  dirname(p: string): string;
+  /**
+   * Return the final component of a path. If `ext` is supplied and the
+   * basename ends with that string, it is stripped from the result.
+   */
+  basename(p: string, ext?: string): string;
+  /**
+   * Return the extension of a path — the portion from the last `.` of the
+   * basename, including the dot. Returns `""` for paths with no extension and
+   * for dotfiles with no secondary extension (e.g. `".gitignore"` → `""`).
+   */
+  extname(p: string): string;
+  /**
+   * Compute the relative path from `from` to `to`. Both should be absolute
+   * paths on the same drive. When they are on different Windows drive letters,
+   * `to` (normalized) is returned unchanged — no relative path exists between
+   * drives.
+   */
+  relative(from: string, to: string): string;
+  /**
+   * Return `true` if `p` is an absolute path: starts with `/` (POSIX), has a
+   * drive letter followed by a slash (`C:/`, `C:\`), or is a UNC path
+   * (`\\server\share` / `//server/share`). Note: `C:foo` (drive-relative,
+   * no slash) is NOT absolute.
+   */
+  isAbsolute(p: string): boolean;
+  /**
+   * Normalize a path: convert `\` to `/`, collapse duplicate slashes, and
+   * resolve `.` and `..` segments.
+   */
+  normalize(p: string): string;
+} = {
+  normalize(p) {
+    return normSegments(normSep(p));
+  },
+
+  join(...parts) {
+    const nonEmpty = parts.filter((p) => p.length > 0);
+    if (nonEmpty.length === 0) return ".";
+    // Concatenate without adding "/" when adjacent parts already supply the
+    // boundary, so join("/", "rel") → "/rel" rather than "//rel" (UNC).
+    const raw = nonEmpty.map(normSep).reduce((a, b) => {
+      if (a.endsWith("/") || b.startsWith("/")) return a + b;
+      return a + "/" + b;
+    });
+    return normSegments(raw);
+  },
+
+  dirname(p) {
+    const n = normSegments(normSep(p));
+    const drive = parseDrive(n);
+    const rest = drive ? n.slice(2) : n;
+    const i = rest.lastIndexOf("/");
+    if (i < 0) return drive ? drive + "." : ".";
+    if (i === 0) return drive ? drive + "/" : "/";
+    return drive ? drive + rest.slice(0, i) : rest.slice(0, i);
+  },
+
+  basename(p, ext) {
+    const n = normSep(p);
+    const segs = n.split("/");
+    let name = segs[segs.length - 1] ?? "";
+    // Trailing slash: "foo/" → last segment is "" → fall back to prior segment
+    if (name === "" && segs.length > 1) name = segs[segs.length - 2] ?? "";
+    if (ext !== undefined && name.endsWith(ext)) {
+      name = name.slice(0, name.length - ext.length);
+    }
+    return name;
+  },
+
+  extname(p) {
+    const base = path.basename(normSep(p));
+    const i = base.lastIndexOf(".");
+    // i === 0 means a dotfile like ".gitignore" — no extension
+    if (i <= 0) return "";
+    return base.slice(i);
+  },
+
+  isAbsolute(p) {
+    const n = normSep(p);
+    if (n.startsWith("//")) return true; // UNC (\\server\share or //server/share)
+    if (/^[A-Za-z]:\//.test(n)) return true; // Windows drive with slash (C:/ or C:\)
+    return n.startsWith("/"); // POSIX
+  },
+
+  relative(from, to) {
+    const nFrom = normSegments(normSep(from));
+    const nTo = normSegments(normSep(to));
+    const driveFrom = parseDrive(nFrom);
+    const driveTo = parseDrive(nTo);
+    // Can't express a relative path across different drives
+    if (driveFrom !== driveTo) return nTo;
+    const segsFrom = (driveFrom ? nFrom.slice(2) : nFrom)
+      .split("/")
+      .filter(Boolean);
+    const segsTo = (driveTo ? nTo.slice(2) : nTo).split("/").filter(Boolean);
+    let common = 0;
+    while (
+      common < segsFrom.length &&
+      common < segsTo.length &&
+      segsFrom[common] === segsTo[common]
+    ) {
+      common++;
+    }
+    const ups = segsFrom.length - common;
+    const downs = segsTo.slice(common);
+    const parts = [...Array<string>(ups).fill(".."), ...downs];
+    return parts.join("/") || ".";
+  },
+};