@design-edito/tools 0.4.4 → 0.4.6

package/node/files/subpaths/index.js

@@ -1,122 +1,165 @@
-import {
-  matchesSome
-} from "../../../chunks/chunk-R3AWQXMY.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/files/subpaths/index.ts
-import { promises as fs } from "node:fs";
-import path from "node:path";
-var defaultListContext = {
-  depth: 0,
-  lstats: null,
-  rootPath: null
+/* eslint-disable @typescript-eslint/no-throw-literal */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { matchesSome as stringMatchesSome } from '../../../agnostic/strings/matches/index.js';
+export const defaultListContext = {
+    depth: 0,
+    lstats: null,
+    rootPath: null
 };
-var fillListContext = (input) => {
-  return {
-    ...defaultListContext,
-    ...input
-  };
+/**
+ * Fills missing properties in a list context with default values.
+ *
+ * @param {ListContext} input - The partial list context to fill.
+ * @returns {Required<ListContext>} A complete list context with all properties set.
+ */
+export const fillListContext = (input) => {
+    return {
+        ...defaultListContext,
+        ...input
+    };
 };
-var defaultListOptions = {
-  directories: true,
-  files: true,
-  symlinks: true,
-  hidden: true,
-  followSimlinks: false,
-  dedupeSimlinksContents: false,
-  maxDepth: Infinity,
-  returnRelative: false,
-  exclude: null,
-  include: null,
-  filter: () => true
+export const defaultListOptions = {
+    directories: true,
+    files: true,
+    symlinks: true,
+    hidden: true,
+    followSimlinks: false,
+    dedupeSimlinksContents: false,
+    maxDepth: Infinity,
+    returnRelative: false,
+    exclude: null,
+    include: null,
+    filter: () => true
 };
-var fillOptions = (input) => {
-  return {
-    ...defaultListOptions,
-    ...input
-  };
+/**
+ * Fills missing properties in list options with default values.
+ *
+ * @param {ListOptions} input - The partial list options to fill.
+ * @returns {Required<ListOptions>} A complete list options object with all properties set.
+ */
+export const fillOptions = (input) => {
+    return {
+        ...defaultListOptions,
+        ...input
+    };
 };
-async function list(...args) {
-  const [inputPath, _options] = args;
-  const options = fillOptions(_options ?? {});
-  const subpaths = await listAbsoluteSubpaths(...args);
-  return options.returnRelative ? subpaths.map((subpath) => path.relative(inputPath, subpath)) : subpaths;
+/**
+ * Lists all subpaths under a given directory path.
+ *
+ * The function recursively traverses the directory tree and returns all matching
+ * files, directories, and symlinks based on the provided options.
+ *
+ * @param inputPath - The root directory path to list subpaths from.
+ * @param [options] - Optional configuration for filtering and behavior. See `ListOptions` for details.
+ * @returns Array of subpaths (absolute or relative based on `returnRelative` option).
+ */
+export async function list(...args) {
+    const [inputPath, _options] = args;
+    const options = fillOptions(_options ?? {});
+    const subpaths = await listAbsoluteSubpaths(...args);
+    return options.returnRelative
+        ? subpaths.map(subpath => path.relative(inputPath, subpath))
+        : subpaths;
 }
-async function listAbsoluteSubpaths(inputPath, _options = {}, __private_context = {}) {
-  const options = fillOptions(_options);
-  const _private_context = fillListContext(__private_context);
-  if (_private_context.rootPath === null) {
-    _private_context.rootPath = inputPath;
-  }
-  const subpaths = [];
-  if (_private_context.depth > options.maxDepth) return subpaths;
-  try {
-    const pathStat = _private_context.lstats ?? await fs.lstat(inputPath);
-    if (!pathStat.isDirectory()) return subpaths;
-  } catch (err) {
-    return subpaths;
-  }
-  const childrenRelPaths = await fs.readdir(inputPath);
-  await Promise.all(childrenRelPaths.map(async (childRelPath) => {
-    const childAbsPath = path.join(inputPath, childRelPath);
-    const childRelFromRootPath = path.relative(_private_context.rootPath ?? inputPath, childAbsPath);
-    const childLstats = await fs.lstat(childAbsPath);
+/**
+ * Internal function that lists absolute subpaths recursively.
+ *
+ * @param {string} inputPath              - The directory path to list.
+ * @param {ListOptions} [_options]        - Optional configuration.
+ * @param {ListContext} [__private_context] - Internal recursion context.
+ * @returns {Promise<string[]>} Array of absolute subpaths.
+ */
+async function listAbsoluteSubpaths(inputPath, _options = {}, 
+// eslint-disable-next-line @typescript-eslint/naming-convention
+__private_context = {}) {
+    const options = fillOptions(_options);
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    const _private_context = fillListContext(__private_context);
+    if (_private_context.rootPath === null) {
+        _private_context.rootPath = inputPath;
+    }
+    const subpaths = [];
+    if (_private_context.depth > options.maxDepth)
+        return subpaths;
     try {
-      const isDirectory = childLstats.isDirectory();
-      const isSymlink = childLstats.isSymbolicLink();
-      const isFile = !isDirectory && !isSymlink;
-      const isHidden = path.basename(childAbsPath).startsWith(".");
-      const type = isDirectory ? "directory" : isSymlink ? "symlink" : "file";
-      if (isDirectory && !options.directories) throw true;
-      if (isSymlink && !options.symlinks) throw false;
-      if (isFile && !options.files) throw false;
-      if (isHidden && !options.hidden) throw false;
-      const realPath = isSymlink ? await fs.realpath(childAbsPath) : childAbsPath;
-      const childPathForFilters = options.returnRelative ? childRelFromRootPath : childAbsPath;
-      const isInExclude = matchesSome(childPathForFilters, options.exclude ?? []);
-      const isInInclude = matchesSome(childPathForFilters, options.include ?? []);
-      if (isInExclude && !isInInclude) throw false;
-      const isInFilter = await options.filter(childPathForFilters, { type, hidden: isHidden, realPath });
-      if (!isInFilter) throw true;
-      if (isSymlink) {
-        if (!options.followSimlinks) subpaths.push(childAbsPath);
-        else {
-          const childSubpaths = await listAbsoluteSubpaths(realPath, options, {
-            ..._private_context,
-            depth: _private_context.depth + 1
-          });
-          subpaths.push(realPath, ...childSubpaths);
+        const pathStat = _private_context.lstats ?? await fs.lstat(inputPath);
+        if (!pathStat.isDirectory())
+            return subpaths;
+    }
+    catch (err) {
+        return subpaths;
+    }
+    const childrenRelPaths = await fs.readdir(inputPath);
+    await Promise.all(childrenRelPaths.map(async (childRelPath) => {
+        const childAbsPath = path.join(inputPath, childRelPath);
+        const childRelFromRootPath = path.relative(_private_context.rootPath ?? inputPath, childAbsPath);
+        const childLstats = await fs.lstat(childAbsPath);
+        try {
+            const isDirectory = childLstats.isDirectory();
+            const isSymlink = childLstats.isSymbolicLink();
+            const isFile = !isDirectory && !isSymlink;
+            const isHidden = path.basename(childAbsPath).startsWith('.');
+            const type = isDirectory ? 'directory' : (isSymlink ? 'symlink' : 'file');
+            if (isDirectory && !options.directories)
+                throw true;
+            if (isSymlink && !options.symlinks)
+                throw false;
+            if (isFile && !options.files)
+                throw false;
+            if (isHidden && !options.hidden)
+                throw false;
+            const realPath = isSymlink
+                ? await fs.realpath(childAbsPath)
+                : childAbsPath;
+            const childPathForFilters = options.returnRelative ? childRelFromRootPath : childAbsPath;
+            const isInExclude = stringMatchesSome(childPathForFilters, options.exclude ?? []);
+            const isInInclude = stringMatchesSome(childPathForFilters, options.include ?? []);
+            if (isInExclude && !isInInclude)
+                throw false;
+            const isInFilter = await options.filter(childPathForFilters, { type, hidden: isHidden, realPath });
+            if (!isInFilter)
+                throw true;
+            if (isSymlink) {
+                if (!options.followSimlinks)
+                    subpaths.push(childAbsPath);
+                else {
+                    const childSubpaths = await listAbsoluteSubpaths(realPath, options, {
+                        ..._private_context,
+                        depth: _private_context.depth + 1
+                    });
+                    subpaths.push(realPath, ...childSubpaths);
+                }
+            }
+            else {
+                if (isDirectory) {
+                    const childSubpaths = await listAbsoluteSubpaths(childAbsPath, options, {
+                        ..._private_context,
+                        depth: _private_context.depth + 1,
+                        lstats: childLstats
+                    });
+                    subpaths.push(childAbsPath, ...childSubpaths);
+                }
+                else {
+                    subpaths.push(childAbsPath);
+                }
+            }
         }
-      } else {
-        if (isDirectory) {
-          const childSubpaths = await listAbsoluteSubpaths(childAbsPath, options, {
-            ..._private_context,
-            depth: _private_context.depth + 1,
-            lstats: childLstats
-          });
-          subpaths.push(childAbsPath, ...childSubpaths);
-        } else {
-          subpaths.push(childAbsPath);
+        catch (err) {
+            if (typeof err !== 'boolean')
+                throw new Error('This try/catch block should only throw booleans');
+            const shouldDiveDeeper = err;
+            if (!shouldDiveDeeper)
+                return [];
+            const childSubpaths = await listAbsoluteSubpaths(childAbsPath, options, {
+                ..._private_context,
+                depth: _private_context.depth + 1,
+                lstats: childLstats
+            });
+            subpaths.push(...childSubpaths);
         }
-      }
-    } catch (err) {
-      if (typeof err !== "boolean") throw new Error("This try/catch block should only throw booleans");
-      const shouldDiveDeeper = err;
-      if (!shouldDiveDeeper) return [];
-      const childSubpaths = await listAbsoluteSubpaths(childAbsPath, options, {
-        ..._private_context,
-        depth: _private_context.depth + 1,
-        lstats: childLstats
-      });
-      subpaths.push(...childSubpaths);
-    }
-  }));
-  return options.dedupeSimlinksContents ? Array.from(new Set(subpaths)) : subpaths;
+    }));
+    return options.dedupeSimlinksContents
+        ? Array.from(new Set(subpaths))
+        : subpaths;
 }
-export {
-  defaultListContext,
-  defaultListOptions,
-  fillListContext,
-  fillOptions,
-  list
-};

package/node/ftps/directory/copy-dir/index.js

@@ -1,9 +1,58 @@
-import {
-  copyDir
-} from "../../../../chunks/chunk-4LTN4SCD.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  copyDir
-};
+import { PassThrough } from 'node:stream';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Recursively copies every file under `sourceDir` to the same relative path
+ * beneath `targetDir` on an FTP server, streaming data to avoid buffering.
+ *
+ * @param {Client}  ftpClient  - The FTP client instance.
+ * @param {string}  sourceDir  - The source directory path to copy from.
+ * @param {string}  targetDir  - The target directory path to copy to.
+ * @param {CopyDirOptions} [options] - Optional parameters for the operation.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - Success: `Outcome.makeSuccess(true)` if the copy succeeds.
+ * - Failure: `Outcome.makeFailure(errStr)` if an error occurs.
+ */
+export async function copyDir(ftpClient, sourceDir, targetDir, options) {
+    const { overwrite = false, ensureDir = true } = options ?? {};
+    async function recurse(dir) {
+        const list = await ftpClient.list(dir);
+        for (const entry of list) {
+            const src = dir.endsWith('/') ? dir + entry.name : dir + '/' + entry.name;
+            const rel = src.substring(sourceDir.length + (sourceDir.endsWith('/') ? 0 : 1));
+            const dst = targetDir.endsWith('/') ? targetDir + rel : `${targetDir}/${rel}`;
+            if (entry.isDirectory) {
+                if (ensureDir)
+                    await ftpClient.ensureDir(dst);
+                await recurse(src);
+            }
+            else if (entry.isFile) {
+                if (!overwrite) {
+                    try {
+                        await ftpClient.size(dst);
+                        throw new Error(`File already exists at ${dst}.`);
+                    }
+                    catch { /* 550 “not found” – safe to proceed */ }
+                }
+                // Make sure parent directory exists if ensureDir is enabled
+                if (ensureDir) {
+                    const dirPath = dst.substring(0, dst.lastIndexOf('/'));
+                    await ftpClient.ensureDir(dirPath);
+                }
+                const pass = new PassThrough();
+                const upload = ftpClient.uploadFrom(pass, dst);
+                await ftpClient.downloadTo(pass, src);
+                await upload;
+            }
+        }
+    }
+    try {
+        if (ensureDir)
+            await ftpClient.ensureDir(targetDir);
+        await recurse(sourceDir);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/ftps/directory/index.d.ts

@@ -1,4 +1,4 @@
-export * as list from './list/index.js'
 export * as copyDir from './copy-dir/index.js'
+export * as list from './list/index.js'
 export * as moveDir from './move-dir/index.js'
 export * as removeDir from './remove-dir/index.js'

package/node/ftps/directory/index.js

@@ -1,4 +1,4 @@
-export * as list from './list/index.js'
 export * as copyDir from './copy-dir/index.js'
+export * as list from './list/index.js'
 export * as moveDir from './move-dir/index.js'
 export * as removeDir from './remove-dir/index.js'

package/node/ftps/directory/list/index.js

@@ -1,9 +1,25 @@
-import {
-  list
-} from "../../../../chunks/chunk-E7BBN5JC.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  list
-};
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Lists all direct children files under a given directory on an FTP server.
+ *
+ * This function returns only the immediate files (not recursive) under the specified directory.
+ *
+ * @param {Client} ftpClient - The basic-ftp client instance used to interact with the FTP server.
+ * @param {string} directoryPath - The directory path to list files under.
+ * @returns {Promise<Outcome.Either<string[], string>>} Returns either a success with an array of file paths, or a failure with an error message.
+ */
+export async function list(ftpClient, directoryPath) {
+    try {
+        const list = await ftpClient.list(directoryPath);
+        const files = list
+            .filter(entry => entry.isFile)
+            .map(entry => (directoryPath.endsWith('/')
+            ? `${directoryPath}${entry.name}`
+            : `${directoryPath}/${entry.name}`));
+        return Outcome.makeSuccess(files);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/ftps/directory/move-dir/index.js

@@ -1,9 +1,41 @@
-import {
-  moveDir
-} from "../../../../chunks/chunk-BCX4HPD7.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  moveDir
-};
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Renames (moves) a directory on an FTP server.
+ * Most FTP servers allow `RNFR /path/old` + `RNTO /path/new` to move a tree
+ * atomically. Falling back to manual copy/delete would be expensive, so this
+ * util simply performs `rename`.
+ *
+ * If `ensureDir` is true (default), the parent directory of `targetDir` is
+ * created if it does not exist.
+ *
+ * @param {Client} ftpClient - The FTP client instance.
+ * @param {string} sourceDir - The source directory path to move from.
+ * @param {string} targetDir - The target directory path to move to.
+ * @param {MoveDirOptions} [options] - Optional parameters for the operation.
+ * @returns {Promise<Outcome.Either<true, string>>} A promise that resolves to an `Outcome.Either`:
+ * - On success: `Outcome.makeSuccess(true)` indicating the move was successful.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message if the move fails.
+ */
+export async function moveDir(ftpClient, sourceDir, targetDir, options) {
+    const { overwrite = false, ensureDir = true } = options ?? {};
+    try {
+        if (ensureDir) {
+            // ensure parent directory of targetDir exists
+            const parentDir = targetDir.substring(0, targetDir.lastIndexOf('/'));
+            await ftpClient.ensureDir(parentDir);
+        }
+        if (!overwrite) {
+            try {
+                await ftpClient.size(targetDir); // will throw 550 for dirs or missing
+                return Outcome.makeFailure(`Target ${targetDir} already exists.`);
+            }
+            catch { /* not found – ok */ }
+        }
+        await ftpClient.rename(sourceDir, targetDir);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/ftps/directory/remove-dir/index.js

@@ -1,9 +1,42 @@
-import {
-  removeDir
-} from "../../../../chunks/chunk-FSNNEPY5.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  removeDir
-};
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Recursively deletes a directory (and all contents) on an FTP server.
+ *
+ * @param {Client} ftpClient            - The FTP client instance.
+ * @param {string} directoryPath        - The path of the directory to delete.
+ * @param {RemoveDirOptions} [options]  - Optional configuration.
+ * @param {boolean} [options.ignoreMissing=true] - Whether to ignore a missing directory.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success: `Outcome.makeSuccess(true)` – deletion succeeded, or directory
+ *   was absent and `ignoreMissing` is true.
+ * - On failure: `Outcome.makeFailure(errStr)` if deletion fails, or directory
+ *   absent and `ignoreMissing` is false.
+ */
+export async function removeDir(ftpClient, directoryPath, options) {
+    const { ignoreMissing = true } = options ?? {};
+    async function recurse(dir) {
+        const list = await ftpClient.list(dir);
+        for (const entry of list) {
+            const full = dir.endsWith('/') ? dir + entry.name : `${dir}/${entry.name}`;
+            if (entry.isDirectory) {
+                await recurse(full);
+            }
+            else if (entry.isFile) {
+                await ftpClient.remove(full);
+            }
+        }
+        await ftpClient.removeDir(dir);
+    }
+    try {
+        await recurse(directoryPath);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        // 550 (“No such file or directory”) when the path is missing
+        if (ignoreMissing && err.code === 550) {
+            return Outcome.makeSuccess(true);
+        }
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/ftps/file/copy/index.js

@@ -1,9 +1,45 @@
-import {
-  copy
-} from "../../../../chunks/chunk-ZAP3ELDE.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  copy
-};
+import { PassThrough } from 'node:stream';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Copies a file from one path to another on the same FTP server, streaming the
+ * data instead of buffering it in memory.
+ *
+ * @param {Client}  ftpClient  - The basic‑ftp client instance.
+ * @param {string}  sourcePath - The path of the source file.
+ * @param {string}  targetPath - The destination path.
+ * @param {CopyOptions} [options] - Optional copy configuration.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success:  `Outcome.makeSuccess(true)`.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function copy(ftpClient, sourcePath, targetPath, options) {
+    const { overwrite = false, ensureDir = true } = options ?? {};
+    try {
+        // Abort if destination exists and overwrite is disabled
+        if (!overwrite) {
+            try {
+                await ftpClient.size(targetPath);
+                return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+            }
+            catch { /* 550 = not found – safe to proceed */ }
+        }
+        // Create missing target directories if requested
+        if (ensureDir) {
+            const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+            await ftpClient.ensureDir(dirPath);
+        }
+        // Stream copy: download → PassThrough → upload
+        const pass = new PassThrough();
+        // Start the upload first so the server reads from `pass` as data arrives
+        const uploadPromise = ftpClient.uploadFrom(pass, targetPath);
+        // Pump data from source into `pass`
+        await ftpClient.downloadTo(pass, sourcePath);
+        // Wait until the upload completes
+        await uploadPromise;
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/ftps/file/download/index.js

@@ -1,9 +1,30 @@
-import {
-  download
-} from "../../../../chunks/chunk-XQUMWHCH.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  download
-};
+import { PassThrough } from 'node:stream';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+/**
+ * Downloads a file from a specified FTP server.
+ *
+ * This function downloads a file from the given FTP server at the specified source path,
+ * returning the file content as a Readable stream. The download process can be customized
+ * using optional download options.
+ *
+ * @param {Client} ftpClient - The basic-ftp client instance used to interact with the FTP server.
+ * @param {string} sourcePath - The path of the file to be downloaded from the FTP server.
+ * @param {DownloadOptions} [options] - Optional settings for configuring the download process.
+ * @param {number} [options.startAt] - The byte offset at which to start downloading the file.
+ * @returns {Promise<Outcome.Either<Readable, string>>} A promise that resolves to an Outcome.Either.
+ * - On success: Outcome.makeSuccess(stream) containing the downloaded file's content as a Readable stream.
+ * - On failure: Outcome.makeFailure(errStr) with an error message if the download fails.
+ */
+export async function download(ftpClient, sourcePath, options) {
+    const { startAt } = options ?? {};
+    const stream = new PassThrough();
+    try {
+        await ftpClient.downloadTo(stream, sourcePath, startAt);
+        return Outcome.makeSuccess(stream);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}

package/node/ftps/file/exists/index.js

@@ -1,9 +1,39 @@
-import {
-  exists
-} from "../../../../chunks/chunk-2FNCUXAX.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  exists
-};
+import { FileType } from 'basic-ftp';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+/**
+ * Checks if a *file* (not a directory) exists on a specified FTP server.
+ *
+ * `ftpClient.list(parentDir)` returns an array of `FileInfo` objects:
+ *   • `type === FileType.File`          → regular file
+ *   • `type === FileType.Directory`     → directory
+ *   • `type === FileType.SymbolicLink`  → symlink
+ *
+ * The function reports **true** only for `FileType.File` or
+ * `FileType.SymbolicLink`, mirroring the SFTP behaviour where `'-'` and `'l'`
+ * are considered files.
+ *
+ * @param {Client} ftpClient  - The basic‑ftp client instance.
+ * @param {string} sourcePath - The full path to check on the FTP server.
+ * @returns {Promise<Outcome.Either<boolean, string>>}
+ * - Success: `Outcome.makeSuccess(true | false)` – true only if a file exists.
+ * - Failure: `Outcome.makeFailure(errStr)` if an error occurs.
+ */
+export async function exists(ftpClient, sourcePath) {
+    try {
+        // Split path into parent dir and base name
+        const lastSlash = sourcePath.lastIndexOf('/');
+        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+        const parentDir = lastSlash === -1 ? '.' : sourcePath.slice(0, lastSlash) || '/';
+        const baseName = lastSlash === -1 ? sourcePath : sourcePath.slice(lastSlash + 1);
+        const list = await ftpClient.list(parentDir);
+        const entry = list.find(e => e.name === baseName);
+        const isFile = entry !== undefined
+            ? (entry.type === FileType.File || entry.type === FileType.SymbolicLink)
+            : false;
+        return Outcome.makeSuccess(isFile);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}