@gjsify/fs 0.1.15 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/fs",
-  "version": "0.1.15",
+  "version": "0.3.0",
   "description": "Node.js fs module for Gjs",
   "module": "lib/esm/index.js",
   "types": "lib/types/index.d.ts",
@@ -25,7 +25,7 @@
     "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
     "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
     "test": "yarn build:gjsify && yarn build:test && yarn test:node && yarn test:gjs",
-    "test:gjs": "gjs -m test.gjs.mjs",
+    "test:gjs": "gjsify run test.gjs.mjs",
     "test:node": "node test.node.mjs"
   },
   "keywords": [
@@ -34,18 +34,18 @@
     "fs"
   ],
   "devDependencies": {
-    "@gjsify/cli": "^0.1.15",
-    "@gjsify/unit": "^0.1.15",
+    "@gjsify/cli": "^0.3.0",
+    "@gjsify/unit": "^0.3.0",
     "@types/node": "^25.6.0",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@girs/gio-2.0": "^2.88.0-4.0.0-rc.3",
-    "@girs/glib-2.0": "^2.88.0-4.0.0-rc.3",
-    "@gjsify/buffer": "^0.1.15",
-    "@gjsify/events": "^0.1.15",
-    "@gjsify/stream": "^0.1.15",
-    "@gjsify/url": "^0.1.15",
-    "@gjsify/utils": "^0.1.15"
+    "@girs/gio-2.0": "^2.88.0-4.0.0-rc.9",
+    "@girs/glib-2.0": "^2.88.0-4.0.0-rc.9",
+    "@gjsify/buffer": "^0.3.0",
+    "@gjsify/events": "^0.3.0",
+    "@gjsify/stream": "^0.3.0",
+    "@gjsify/url": "^0.3.0",
+    "@gjsify/utils": "^0.3.0"
   }
 }

package/src/callback.ts

@@ -10,6 +10,7 @@ import { Buffer } from 'node:buffer';
 import { Stats, BigIntStats, STAT_ATTRIBUTES } from './stats.js';
 import { createNodeError } from './errors.js';
 import { realpathSync, readdirSync, renameSync, copyFileSync, accessSync, appendFileSync, readlinkSync, truncateSync, chmodSync, chownSync, mkdirSync, rmdirSync, readFileSync, writeFileSync } from './sync.js';
+import { normalizePath } from './utils.js';
 // encoding helpers available if needed in future
 
 import type { OpenFlags } from './types/index.js';
@@ -23,13 +24,14 @@ function parseOptsCb(optionsOrCallback: unknown, maybeCallback?: Function): { op
 }
 
 function statImpl(path: PathLike, flags: Gio.FileQueryInfoFlags, syscall: string, options: Record<string, unknown>, callback: Function): void {
-  const file = Gio.File.new_for_path(path.toString());
+  const pathStr = normalizePath(path);
+  const file = Gio.File.new_for_path(pathStr);
   file.query_info_async(STAT_ATTRIBUTES, flags, GLib.PRIORITY_DEFAULT, null, (_s: Gio.File, res: Gio.AsyncResult) => {
     try {
       const info = file.query_info_finish(res);
-      callback(null, options?.bigint ? new BigIntStats(info, path) : new Stats(info, path));
+      callback(null, options?.bigint ? new BigIntStats(info, pathStr) : new Stats(info, pathStr));
     } catch (err: unknown) {
-      callback(createNodeError(err, syscall, path));
+      callback(createNodeError(err, syscall, pathStr));
     }
   });
 }
@@ -89,13 +91,15 @@ export function symlink(target: PathLike, path: PathLike, typeOrCallback: string
   if (typeof callback !== 'function') {
     throw new TypeError('Callback must be a function. Received ' + typeof callback);
   }
-  const file = Gio.File.new_for_path(path.toString());
-  file.make_symbolic_link_async(target.toString(), GLib.PRIORITY_DEFAULT, null, (_s: Gio.File, res: Gio.AsyncResult) => {
+  const pathStr = normalizePath(path);
+  const targetStr = normalizePath(target);
+  const file = Gio.File.new_for_path(pathStr);
+  file.make_symbolic_link_async(targetStr, GLib.PRIORITY_DEFAULT, null, (_s: Gio.File, res: Gio.AsyncResult) => {
     try {
       file.make_symbolic_link_finish(res);
       callback(null);
     } catch (err: unknown) {
-      callback(createNodeError(err, 'symlink', target, path));
+      callback(createNodeError(err, 'symlink', targetStr, pathStr));
     }
   });
 }
@@ -159,7 +163,7 @@ export function open(path: PathLike, ...args: (OpenMode | Mode | OpenCallback |
             break;
     }
 
-    openP(path, flags as OpenFlags | undefined, mode)
+    openP(path, flags as OpenFlags | number | undefined, mode)
     .then((fileHandle) => {
         callback(null, fileHandle.fd);
     })
@@ -616,10 +620,11 @@ export function readFile(path: PathLike, options: { encoding?: string; flag?: st
 export function readFile(path: PathLike, optsOrCb: { encoding?: string; flag?: string } | string | ((err: NodeJS.ErrnoException | null, data: Buffer) => void), maybeCb?: (err: NodeJS.ErrnoException | null, data: string | Buffer | null) => void): void {
   const callback = typeof optsOrCb === 'function' ? optsOrCb : maybeCb!;
   const options = typeof optsOrCb === 'function' ? undefined : optsOrCb;
+  const pathStr = normalizePath(path);
   Promise.resolve().then(() => {
     try {
       const readOpts = typeof options === 'string' ? { encoding: options as string | null, flag: 'r' } : { encoding: (options?.encoding ?? null) as string | null, flag: options?.flag ?? 'r' };
-      callback(null, readFileSync(path.toString(), readOpts) as unknown as Buffer);
+      callback(null, readFileSync(pathStr, readOpts) as unknown as Buffer);
     } catch (err: unknown) {
       callback(err as NodeJS.ErrnoException, null as unknown as Buffer);
     }
@@ -632,9 +637,10 @@ export function writeFile(path: PathLike, data: string | Uint8Array, callback: N
 export function writeFile(path: PathLike, data: string | Uint8Array, options: { encoding?: string; mode?: number; flag?: string } | string, callback: NoParamCallback): void;
 export function writeFile(path: PathLike, data: string | Uint8Array, optsOrCb: { encoding?: string; mode?: number; flag?: string } | string | NoParamCallback, maybeCb?: NoParamCallback): void {
   const callback = typeof optsOrCb === 'function' ? optsOrCb : maybeCb!;
+  const pathStr = normalizePath(path);
   Promise.resolve().then(() => {
     try {
-      writeFileSync(path.toString(), data);
+      writeFileSync(pathStr, data);
       callback(null);
     } catch (err: unknown) {
       callback(err as NodeJS.ErrnoException);
@@ -645,13 +651,15 @@ export function writeFile(path: PathLike, data: string | Uint8Array, optsOrCb: {
 // --- link (callback) ---
 
 export function link(existingPath: PathLike, newPath: PathLike, callback: NoParamCallback): void {
+  const existingStr = normalizePath(existingPath);
+  const newStr = normalizePath(newPath);
   Promise.resolve().then(() => {
     try {
-      const result = GLib.spawn_command_line_sync(`ln ${existingPath.toString()} ${newPath.toString()}`);
+      const result = GLib.spawn_command_line_sync(`ln ${existingStr} ${newStr}`);
       if (!result[0]) {
-        throw Object.assign(new Error(`EPERM: operation not permitted, link '${existingPath}' -> '${newPath}'`), {
+        throw Object.assign(new Error(`EPERM: operation not permitted, link '${existingStr}' -> '${newStr}'`), {
           code: 'EPERM', errno: -1, syscall: 'link',
-          path: existingPath.toString(), dest: newPath.toString()
+          path: existingStr, dest: newStr
         });
       }
       callback(null);
@@ -664,9 +672,10 @@ export function link(existingPath: PathLike, newPath: PathLike, callback: NoPara
 // --- unlink (callback) ---
 
 export function unlink(path: PathLike, callback: NoParamCallback): void {
+  const pathStr = normalizePath(path);
   Promise.resolve().then(() => {
     try {
-      GLib.unlink(path.toString());
+      GLib.unlink(pathStr);
       callback(null);
     } catch (err: unknown) {
       callback(err as NodeJS.ErrnoException);

package/src/cp.spec.ts

@@ -0,0 +1,181 @@
+// Ported from refs/bun/test/js/node/fs/cp.test.ts and
+// refs/node-test/parallel/test-fs-cp-sync-*.mjs
+// Original: MIT, Oven & contributors / Node.js contributors.
+// Rewritten for @gjsify/unit — behavior preserved, assertion dialect adapted.
+
+import { describe, it, expect } from '@gjsify/unit';
+import { cpSync, promises, existsSync, mkdirSync, writeFileSync, readFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+function makeTmp(): string {
+  return mkdtempSync(join(tmpdir(), 'gjsify-cp-'));
+}
+
+export default async () => {
+  await describe('fs.cpSync', async () => {
+    await it('copies a single file', async () => {
+      const tmp = makeTmp();
+      writeFileSync(join(tmp, 'a.txt'), 'hello');
+
+      cpSync(join(tmp, 'a.txt'), join(tmp, 'b.txt'));
+
+      expect(readFileSync(join(tmp, 'b.txt'), 'utf8')).toBe('hello');
+      rmSync(tmp, { recursive: true, force: true });
+    });
+
+    await it('throws EISDIR when src is directory and recursive is false', async () => {
+      const tmp = makeTmp();
+      mkdirSync(join(tmp, 'src'));
+
+      let threw = false;
+      try {
+        cpSync(join(tmp, 'src'), join(tmp, 'dest'));
+      } catch (e: any) {
+        threw = true;
+        expect(e.code).toBe('ERR_FS_EISDIR');
+      }
+      expect(threw).toBe(true);
+      rmSync(tmp, { recursive: true, force: true });
+    });
+
+    await it('recursively copies a directory tree', async () => {
+      const tmp = makeTmp();
+      mkdirSync(join(tmp, 'src', 'sub'), { recursive: true });
+      writeFileSync(join(tmp, 'src', 'a.txt'), 'a');
+      writeFileSync(join(tmp, 'src', 'sub', 'b.txt'), 'b');
+
+      cpSync(join(tmp, 'src'), join(tmp, 'dst'), { recursive: true });
+
+      expect(readFileSync(join(tmp, 'dst', 'a.txt'), 'utf8')).toBe('a');
+      expect(readFileSync(join(tmp, 'dst', 'sub', 'b.txt'), 'utf8')).toBe('b');
+      rmSync(tmp, { recursive: true, force: true });
+    });
+
+    await it('overwrites existing file by default (force=true)', async () => {
+      const tmp = makeTmp();
+      writeFileSync(join(tmp, 'src.txt'), 'new');
+      writeFileSync(join(tmp, 'dst.txt'), 'old');
+
+      cpSync(join(tmp, 'src.txt'), join(tmp, 'dst.txt'));
+
+      expect(readFileSync(join(tmp, 'dst.txt'), 'utf8')).toBe('new');
+      rmSync(tmp, { recursive: true, force: true });
+    });
+
+    await it('does not overwrite when force=false', async () => {
+      const tmp = makeTmp();
+      writeFileSync(join(tmp, 'src.txt'), 'new');
+      writeFileSync(join(tmp, 'dst.txt'), 'old');
+
+      cpSync(join(tmp, 'src.txt'), join(tmp, 'dst.txt'), { force: false });
+
+      expect(readFileSync(join(tmp, 'dst.txt'), 'utf8')).toBe('old');
+      rmSync(tmp, { recursive: true, force: true });
+    });
+
+    await it('throws EEXIST when force=false and errorOnExist=true', async () => {
+      const tmp = makeTmp();
+      writeFileSync(join(tmp, 'src.txt'), 'new');
+      writeFileSync(join(tmp, 'dst.txt'), 'old');
+
+      let threw = false;
+      try {
+        cpSync(join(tmp, 'src.txt'), join(tmp, 'dst.txt'), { force: false, errorOnExist: true });
+      } catch (e: any) {
+        threw = true;
+        expect(e.code).toBe('ERR_FS_CP_EEXIST');
+      }
+      expect(threw).toBe(true);
+      rmSync(tmp, { recursive: true, force: true });
+    });
+
+    await it('applies filter function — skips excluded entries', async () => {
+      const tmp = makeTmp();
+      mkdirSync(join(tmp, 'src'));
+      writeFileSync(join(tmp, 'src', 'keep.txt'), 'keep');
+      writeFileSync(join(tmp, 'src', 'skip.log'), 'skip');
+
+      cpSync(join(tmp, 'src'), join(tmp, 'dst'), {
+        recursive: true,
+        filter: (_src, _dst) => !_src.endsWith('.log'),
+      });
+
+      expect(existsSync(join(tmp, 'dst', 'keep.txt'))).toBe(true);
+      expect(existsSync(join(tmp, 'dst', 'skip.log'))).toBe(false);
+      rmSync(tmp, { recursive: true, force: true });
+    });
+
+    await it('throws ENOENT when src does not exist', async () => {
+      const tmp = makeTmp();
+
+      let threw = false;
+      try {
+        cpSync(join(tmp, 'nonexistent.txt'), join(tmp, 'dst.txt'));
+      } catch (e: any) {
+        threw = true;
+        expect(e.code).toBe('ENOENT');
+      }
+      expect(threw).toBe(true);
+      rmSync(tmp, { recursive: true, force: true });
+    });
+  });
+
+  await describe('fs.promises.cp', async () => {
+    await it('copies a single file', async () => {
+      const tmp = makeTmp();
+      writeFileSync(join(tmp, 'a.txt'), 'hello');
+
+      await promises.cp(join(tmp, 'a.txt'), join(tmp, 'b.txt'));
+
+      expect(readFileSync(join(tmp, 'b.txt'), 'utf8')).toBe('hello');
+      rmSync(tmp, { recursive: true, force: true });
+    });
+
+    await it('throws EISDIR when src is directory and recursive is false', async () => {
+      const tmp = makeTmp();
+      mkdirSync(join(tmp, 'src'));
+
+      let threw = false;
+      try {
+        await promises.cp(join(tmp, 'src'), join(tmp, 'dest'));
+      } catch (e: any) {
+        threw = true;
+        expect(e.code).toBe('ERR_FS_EISDIR');
+      }
+      expect(threw).toBe(true);
+      rmSync(tmp, { recursive: true, force: true });
+    });
+
+    await it('recursively copies a directory tree', async () => {
+      const tmp = makeTmp();
+      mkdirSync(join(tmp, 'src', 'sub'), { recursive: true });
+      writeFileSync(join(tmp, 'src', 'a.txt'), 'a');
+      writeFileSync(join(tmp, 'src', 'sub', 'b.txt'), 'b');
+
+      await promises.cp(join(tmp, 'src'), join(tmp, 'dst'), { recursive: true });
+
+      expect(readFileSync(join(tmp, 'dst', 'a.txt'), 'utf8')).toBe('a');
+      expect(readFileSync(join(tmp, 'dst', 'sub', 'b.txt'), 'utf8')).toBe('b');
+      rmSync(tmp, { recursive: true, force: true });
+    });
+
+    await it('applies async filter function', async () => {
+      const tmp = makeTmp();
+      mkdirSync(join(tmp, 'src'));
+      writeFileSync(join(tmp, 'src', 'keep.ts'), 'ts');
+      writeFileSync(join(tmp, 'src', 'skip.js'), 'js');
+
+      await promises.cp(join(tmp, 'src'), join(tmp, 'dst'), {
+        recursive: true,
+        filter: async (_src, _dst) => {
+          return !_src.endsWith('.js');
+        },
+      });
+
+      expect(existsSync(join(tmp, 'dst', 'keep.ts'))).toBe(true);
+      expect(existsSync(join(tmp, 'dst', 'skip.js'))).toBe(false);
+      rmSync(tmp, { recursive: true, force: true });
+    });
+  });
+};

package/src/cp.ts

@@ -0,0 +1,328 @@
+// fs.cp / fs.cpSync / fs.promises.cp — recursive copy
+// Reference: Node.js lib/internal/fs/cpSync.js
+// Reimplemented for GJS using Gio.File synchronous operations
+
+import Gio from '@girs/gio-2.0';
+import { join } from 'node:path';
+import { normalizePath } from './utils.js';
+import { createNodeError } from './errors.js';
+
+import type { PathLike } from 'node:fs';
+
+export interface CpSyncOptions {
+  dereference?: boolean;
+  errorOnExist?: boolean;
+  filter?: (src: string, dest: string) => boolean;
+  force?: boolean;
+  mode?: number;
+  preserveTimestamps?: boolean;
+  recursive?: boolean;
+  verbatimSymlinks?: boolean;
+}
+
+export interface CpOptions extends Omit<CpSyncOptions, 'filter'> {
+  filter?: (src: string, dest: string) => boolean | Promise<boolean>;
+}
+
+function makeEEXIST(destStr: string): NodeJS.ErrnoException {
+  const e: NodeJS.ErrnoException = new Error(`ERR_FS_CP_EEXIST: file already exists, copyfile '${destStr}'`);
+  e.code = 'ERR_FS_CP_EEXIST';
+  e.syscall = 'copyfile';
+  e.path = destStr;
+  return e;
+}
+
+function makeEISDIR(srcStr: string): NodeJS.ErrnoException {
+  const e: NodeJS.ErrnoException = new Error(`ERR_FS_EISDIR: illegal operation on a directory, copyfile '${srcStr}'`);
+  e.code = 'ERR_FS_EISDIR';
+  e.syscall = 'copyfile';
+  e.path = srcStr;
+  return e;
+}
+
+function makeENOTDIR(srcStr: string, destStr: string): NodeJS.ErrnoException {
+  const e: NodeJS.ErrnoException = new Error(`ENOTDIR: not a directory, copyfile '${srcStr}' -> '${destStr}'`);
+  e.code = 'ENOTDIR';
+  e.syscall = 'copyfile';
+  e.path = srcStr;
+  (e as any).dest = destStr;
+  return e;
+}
+
+function makeSYMLINKLOOP(srcStr: string, destStr: string): NodeJS.ErrnoException {
+  const e: NodeJS.ErrnoException = new Error(`ELOOP: too many levels of symbolic links, copyfile '${srcStr}' -> '${destStr}'`);
+  e.code = 'ELOOP';
+  e.syscall = 'copyfile';
+  e.path = srcStr;
+  (e as any).dest = destStr;
+  return e;
+}
+
+function queryCopyFlags(opts: CpSyncOptions | CpOptions): Gio.FileCopyFlags {
+  const force = opts.force ?? true;
+  let flags = Gio.FileCopyFlags.NONE;
+  if (force) flags |= Gio.FileCopyFlags.OVERWRITE;
+  if (opts.preserveTimestamps) flags |= Gio.FileCopyFlags.TARGET_DEFAULT_MODIFIED_TIME;
+  if (!opts.dereference) flags |= Gio.FileCopyFlags.NOFOLLOW_SYMLINKS;
+  return flags;
+}
+
+function copyOneSyncFile(srcFile: Gio.File, destFile: Gio.File, srcStr: string, destStr: string, opts: CpSyncOptions | CpOptions): void {
+  const force = opts.force ?? true;
+
+  // Check dest is not a directory
+  try {
+    const destInfo = destFile.query_info('standard::type', Gio.FileQueryInfoFlags.NONE, null);
+    if (destInfo.get_file_type() === Gio.FileType.DIRECTORY) {
+      throw makeENOTDIR(srcStr, destStr);
+    }
+    if (!force) {
+      if (opts.errorOnExist) throw makeEEXIST(destStr);
+      return; // silent skip when force=false and no errorOnExist
+    }
+  } catch (e: any) {
+    if (typeof e.code === 'string') throw e; // re-throw Node-style errors (string codes)
+    // Gio errors have numeric codes (e.g. NOT_FOUND=1) — dest doesn't exist, fine
+  }
+
+  const flags = queryCopyFlags(opts);
+  try {
+    srcFile.copy(destFile, flags, null, null);
+  } catch (err: unknown) {
+    throw createNodeError(err, 'copyfile', srcStr, destStr);
+  }
+}
+
+function cpOneDirSync(srcFile: Gio.File, destFile: Gio.File, srcStr: string, destStr: string, opts: CpSyncOptions | CpOptions): void {
+  // Detect src ⊂ dest cycle (if dest path starts with srcStr + separator)
+  const sep = srcStr.endsWith('/') ? '' : '/';
+  if (destStr.startsWith(srcStr + sep) && destStr !== srcStr) {
+    throw makeSYMLINKLOOP(srcStr, destStr);
+  }
+
+  // Create dest directory if it doesn't exist
+  if (!destFile.query_exists(null)) {
+    try {
+      destFile.make_directory_with_parents(null);
+    } catch (err: unknown) {
+      throw createNodeError(err, 'mkdir', destStr);
+    }
+  } else {
+    // dest exists — must be a directory
+    try {
+      const destInfo = destFile.query_info('standard::type', Gio.FileQueryInfoFlags.NONE, null);
+      if (destInfo.get_file_type() !== Gio.FileType.DIRECTORY) {
+        throw makeENOTDIR(destStr, srcStr);
+      }
+    } catch (e: any) {
+      if (typeof e.code === 'string') throw e;
+    }
+  }
+
+  // Enumerate children
+  let enumerator: Gio.FileEnumerator;
+  try {
+    enumerator = srcFile.enumerate_children(
+      'standard::name,standard::type,standard::is-symlink',
+      opts.dereference ? Gio.FileQueryInfoFlags.NONE : Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS,
+      null,
+    );
+  } catch (err: unknown) {
+    throw createNodeError(err, 'scandir', srcStr);
+  }
+
+  let childInfo = enumerator.next_file(null);
+  while (childInfo !== null) {
+    const name = childInfo.get_name();
+    const childSrc = join(srcStr, name);
+    const childDest = join(destStr, name);
+
+    const filter = (opts as CpSyncOptions).filter;
+    if (filter && !filter(childSrc, childDest)) {
+      childInfo = enumerator.next_file(null);
+      continue;
+    }
+
+    cpSyncInternal(childSrc, childDest, opts);
+    childInfo = enumerator.next_file(null);
+  }
+}
+
+function cpSyncInternal(srcStr: string, destStr: string, opts: CpSyncOptions | CpOptions): void {
+  const srcFile = Gio.File.new_for_path(srcStr);
+  const destFile = Gio.File.new_for_path(destStr);
+
+  let info: Gio.FileInfo;
+  try {
+    info = srcFile.query_info(
+      'standard::type,standard::is-symlink',
+      opts.dereference ? Gio.FileQueryInfoFlags.NONE : Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS,
+      null,
+    );
+  } catch (err: unknown) {
+    throw createNodeError(err, 'stat', srcStr);
+  }
+
+  const type = info.get_file_type();
+
+  if (type === Gio.FileType.DIRECTORY) {
+    if (!opts.recursive) throw makeEISDIR(srcStr);
+    cpOneDirSync(srcFile, destFile, srcStr, destStr, opts);
+  } else {
+    copyOneSyncFile(srcFile, destFile, srcStr, destStr, opts);
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+export function cpSync(src: PathLike, dest: PathLike, options?: CpSyncOptions): void {
+  const srcStr = normalizePath(src);
+  const destStr = normalizePath(dest);
+  const opts: CpSyncOptions = options ?? {};
+
+  const srcFile = Gio.File.new_for_path(srcStr);
+
+  // Apply top-level filter before doing anything
+  const filter = opts.filter;
+  if (filter && !filter(srcStr, destStr)) return;
+
+  // Check src is a directory without recursive option
+  try {
+    const info = srcFile.query_info(
+      'standard::type',
+      opts.dereference ? Gio.FileQueryInfoFlags.NONE : Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS,
+      null,
+    );
+    if (info.get_file_type() === Gio.FileType.DIRECTORY && !opts.recursive) {
+      throw makeEISDIR(srcStr);
+    }
+  } catch (e: any) {
+    if (typeof e.code === 'string') throw e;
+    throw createNodeError(e, 'stat', srcStr);
+  }
+
+  cpSyncInternal(srcStr, destStr, opts);
+}
+
+export function cp(
+  src: PathLike,
+  dest: PathLike,
+  options: CpOptions | ((err: NodeJS.ErrnoException | null) => void),
+  callback?: (err: NodeJS.ErrnoException | null) => void,
+): void {
+  let opts: CpOptions;
+  let cb: (err: NodeJS.ErrnoException | null) => void;
+
+  if (typeof options === 'function') {
+    cb = options;
+    opts = {};
+  } else {
+    cb = callback!;
+    opts = options;
+  }
+
+  const asyncFilter = opts.filter;
+  if (asyncFilter) {
+    // Wrap async filter through a sync-compatible adapter by running
+    // a mini async pipeline: resolve filter for each entry, then cpSync.
+    // For simplicity, resolve the top-level filter and then run cpSync
+    // with a synchronous shim. Full async recursive filtering uses the
+    // promise variant.
+    Promise.resolve(asyncFilter(normalizePath(src), normalizePath(dest))).then((include) => {
+      if (!include) { cb(null); return; }
+      try {
+        // For directories, we must run asynchronously through promises.cp
+        cpPromises(src, dest, opts).then(() => cb(null)).catch(cb);
+      } catch (e: any) {
+        cb(e);
+      }
+    }).catch(cb);
+    return;
+  }
+
+  // No async filter — use synchronous implementation on next tick
+  Promise.resolve().then(() => {
+    try {
+      cpSync(src, dest, opts as CpSyncOptions);
+      cb(null);
+    } catch (e: any) {
+      cb(e);
+    }
+  });
+}
+
+// ─── promises.cp ─────────────────────────────────────────────────────────────
+
+async function cpPromisesDir(srcStr: string, destStr: string, opts: CpOptions): Promise<void> {
+  const sep = srcStr.endsWith('/') ? '' : '/';
+  if (destStr.startsWith(srcStr + sep) && destStr !== srcStr) {
+    throw makeSYMLINKLOOP(srcStr, destStr);
+  }
+
+  const destFile = Gio.File.new_for_path(destStr);
+  if (!destFile.query_exists(null)) {
+    try {
+      destFile.make_directory_with_parents(null);
+    } catch (err: unknown) {
+      throw createNodeError(err, 'mkdir', destStr);
+    }
+  }
+
+  const srcFile = Gio.File.new_for_path(srcStr);
+  let enumerator: Gio.FileEnumerator;
+  try {
+    enumerator = srcFile.enumerate_children(
+      'standard::name,standard::type',
+      opts.dereference ? Gio.FileQueryInfoFlags.NONE : Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS,
+      null,
+    );
+  } catch (err: unknown) {
+    throw createNodeError(err, 'scandir', srcStr);
+  }
+
+  let childInfo = enumerator.next_file(null);
+  while (childInfo !== null) {
+    const name = childInfo.get_name();
+    const childSrc = join(srcStr, name);
+    const childDest = join(destStr, name);
+
+    const filter = opts.filter;
+    if (filter) {
+      const include = await Promise.resolve(filter(childSrc, childDest));
+      if (!include) {
+        childInfo = enumerator.next_file(null);
+        continue;
+      }
+    }
+
+    await cpPromises(childSrc, childDest, opts);
+    childInfo = enumerator.next_file(null);
+  }
+}
+
+async function cpPromises(src: PathLike, dest: PathLike, opts: CpOptions = {}): Promise<void> {
+  const srcStr = normalizePath(src);
+  const destStr = normalizePath(dest);
+
+  const srcFile = Gio.File.new_for_path(srcStr);
+  let info: Gio.FileInfo;
+  try {
+    info = srcFile.query_info(
+      'standard::type',
+      opts.dereference ? Gio.FileQueryInfoFlags.NONE : Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS,
+      null,
+    );
+  } catch (err: unknown) {
+    throw createNodeError(err, 'stat', srcStr);
+  }
+
+  if (info.get_file_type() === Gio.FileType.DIRECTORY) {
+    if (!opts.recursive) throw makeEISDIR(srcStr);
+    await cpPromisesDir(srcStr, destStr, opts);
+  } else {
+    const destFile = Gio.File.new_for_path(destStr);
+    copyOneSyncFile(srcFile, destFile, srcStr, destStr, opts);
+  }
+}
+
+export { cpPromises as cpAsync };