@design-edito/tools 0.4.4 → 0.4.6

package/node/process/spawner/index.js

@@ -1,83 +1,107 @@
-import {
-  styles
-} from "../../../chunks/chunk-JZ6GM444.js";
-import "../../../chunks/chunk-H4PP6AHP.js";
-import {
-  makeFailure,
-  makeSuccess
-} from "../../../chunks/chunk-LUAYN7VJ.js";
-import {
-  unknownToString
-} from "../../../chunks/chunk-PUQUSA6S.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/process/spawner/index.ts
-import {
-  spawn,
-  spawnSync
-} from "node:child_process";
-import ansiRegex from "ansi-regex";
-import chalk from "chalk";
-async function spawner(label, command, args, options) {
-  return await new Promise((resolve, reject) => {
-    if (label !== null) console.log("\n" + styles.info(label) + "\n");
-    const printableArgs = options?.argsPrintFormat !== void 0 ? options.argsPrintFormat(args) : args;
-    console.log(styles.light(`> ${command} ${printableArgs.join(" ")}
-`));
-    const prcss = spawn(command, args, { stdio: "pipe", ...options });
-    let stdout = "";
-    let stderr = "";
-    let err = null;
-    prcss.stdout?.on("data", (data) => {
-      const strData = unknownToString(data);
-      stdout += strData;
-      console.log(styles.light(strData.replace(ansiRegex(), "").trim()));
+import { spawn, spawnSync } from 'node:child_process';
+import ansiRegex from 'ansi-regex';
+import chalk from 'chalk';
+import * as Outcome from '../../../agnostic/misc/outcome/index.js';
+import { styles } from '../../../agnostic/misc/logs/styles/index.js';
+import { unknownToString } from '../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Spawns a child process asynchronously and logs its execution and output.
+ *
+ * Stdout and stderr are streamed, logged in real time, and collected.
+ * The result is returned as an `Outcome.Either`, representing success or failure.
+ *
+ * @param label - Optional label printed before execution to visually group logs.
+ * @param command - The command to execute.
+ * @param args - Arguments passed to the command.
+ * @param options - Optional spawn configuration and utility-specific options:
+ *   - `argsPrintFormat`: Function to format arguments for logging.
+ *   - `throwOnError`: If `true`, rejects on non-zero exit code instead of resolving a failure.
+ * @returns A promise resolving to an `Outcome.Either`:
+ *   - success: `{ stdout, stderr, err }` when the command exits with code `0`
+ *   - failure: `{ stdout, stderr, err }` when the command exits with a non-zero code
+ */
+export async function spawner(label, command, args, options) {
+    return await new Promise((resolve, reject) => {
+        if (label !== null)
+            console.log('\n' + styles.info(label) + '\n');
+        const printableArgs = options?.argsPrintFormat !== undefined
+            ? options.argsPrintFormat(args)
+            : args;
+        console.log(styles.light(`> ${command} ${printableArgs.join(' ')}\n`));
+        const prcss = spawn(command, args, { stdio: 'pipe', ...options });
+        let stdout = '';
+        let stderr = '';
+        let err = null;
+        prcss.stdout?.on('data', data => {
+            const strData = unknownToString(data);
+            stdout += strData;
+            console.log(styles.light(strData.replace(ansiRegex(), '').trim()));
+        });
+        prcss.stderr?.on('data', data => {
+            const strData = unknownToString(data);
+            stderr += strData;
+            console.log(styles.warning(strData.replace(ansiRegex(), '').trim()));
+        });
+        prcss.on('error', e => {
+            err = e;
+            console.log(styles.error(unknownToString(err).replace(ansiRegex(), '').trim()));
+        });
+        prcss.on('close', code => {
+            if (code !== 0 && options?.throwOnError === true)
+                reject(new Error(stderr + '\n' + stdout));
+            else if (code !== 0)
+                return resolve(Outcome.makeFailure({ stdout, stderr, err }));
+            else
+                return resolve(Outcome.makeSuccess({ stdout, stderr, err }));
+        });
     });
-    prcss.stderr?.on("data", (data) => {
-      const strData = unknownToString(data);
-      stderr += strData;
-      console.log(styles.warning(strData.replace(ansiRegex(), "").trim()));
-    });
-    prcss.on("error", (e) => {
-      err = e;
-      console.log(styles.error(unknownToString(err).replace(ansiRegex(), "").trim()));
-    });
-    prcss.on("close", (code) => {
-      if (code !== 0 && options?.throwOnError === true) reject(new Error(stderr + "\n" + stdout));
-      else if (code !== 0) return resolve(makeFailure({ stdout, stderr, err }));
-      else return resolve(makeSuccess({ stdout, stderr, err }));
-    });
-  });
 }
-function spawnerSync(label, command, args, options) {
-  if (label !== null) console.log("\n" + styles.info(label) + "\n");
-  const printableArgs = options?.argsPrintFormat !== void 0 ? options.argsPrintFormat(args) : args;
-  console.log(styles.light(`> ${command} ${printableArgs.join(" ")}
-`));
-  const result = spawnSync(command, args, { stdio: "pipe", encoding: "utf8", ...options });
-  const stderr = result.stderr?.toString().trim();
-  const stdout = result.stdout?.toString().trim();
-  const err = result.error;
-  if (err !== void 0) {
-    console.log(styles.light(chalk.italic("err:\n")));
-    console.log(styles.error(unknownToString(err).replace(ansiRegex(), "")));
-    console.log("");
-  }
-  if (stderr !== "") {
-    console.log(styles.light(chalk.italic("stderr:\n")));
-    console.log(styles.warning(stderr.replace(ansiRegex(), "")));
-    console.log("");
-  }
-  if (stdout !== "") {
-    console.log(styles.light(chalk.italic("stdout:\n")));
-    console.log(styles.light(stdout.replace(ansiRegex(), "")));
-    console.log("");
-  }
-  if (result.status !== 0 && options?.throwOnError === true) throw new Error(stderr + "\n" + stdout);
-  else if (result.status !== 0) return makeFailure({ stdout, stderr, err });
-  return makeSuccess({ stdout, stderr, err });
+/**
+ * Spawns a child process synchronously and logs its execution and output.
+ *
+ * Stdout, stderr, and execution errors are logged after the process completes.
+ * The result is returned as an `Outcome.Either`, representing success or failure.
+ *
+ * @param label - Optional label printed before execution to visually group logs.
+ * @param command - The command to execute.
+ * @param args - Arguments passed to the command.
+ * @param options - Optional spawn configuration and utility-specific options:
+ *   - `argsPrintFormat`: Function to format arguments for logging.
+ *   - `throwOnError`: If `true`, throws on non-zero exit code instead of returning a failure.
+ * @returns An `Outcome.Either`:
+ *   - success: `{ stdout, stderr, err }` when the command exits with code `0`
+ *   - failure: `{ stdout, stderr, err }` when the command exits with a non-zero code
+ * @throws Error if `throwOnError` is `true` and the process exits with a non-zero status
+ */
+export function spawnerSync(label, command, args, options) {
+    if (label !== null)
+        console.log('\n' + styles.info(label) + '\n');
+    const printableArgs = options?.argsPrintFormat !== undefined
+        ? options.argsPrintFormat(args)
+        : args;
+    console.log(styles.light(`> ${command} ${printableArgs.join(' ')}\n`));
+    const result = spawnSync(command, args, { stdio: 'pipe', encoding: 'utf8', ...options });
+    const stderr = result.stderr?.toString().trim();
+    const stdout = result.stdout?.toString().trim();
+    const err = result.error;
+    if (err !== undefined) {
+        console.log(styles.light(chalk.italic('err:\n')));
+        console.log(styles.error(unknownToString(err).replace(ansiRegex(), '')));
+        console.log('');
+    }
+    if (stderr !== '') {
+        console.log(styles.light(chalk.italic('stderr:\n')));
+        console.log(styles.warning(stderr.replace(ansiRegex(), '')));
+        console.log('');
+    }
+    if (stdout !== '') {
+        console.log(styles.light(chalk.italic('stdout:\n')));
+        console.log(styles.light(stdout.replace(ansiRegex(), '')));
+        console.log('');
+    }
+    if (result.status !== 0 && options?.throwOnError === true)
+        throw new Error(stderr + '\n' + stdout);
+    else if (result.status !== 0)
+        return Outcome.makeFailure({ stdout, stderr, err });
+    return Outcome.makeSuccess({ stdout, stderr, err });
 }
-export {
-  spawner,
-  spawnerSync
-};

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

@@ -1,9 +1,55 @@
-import {
-  copyDir
-} from "../../../../chunks/chunk-4Q5TKOIG.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 SFTP server, streaming data to minimize memory usage.
+ *
+ * @param {Client} sftp - The SFTP 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>>}
+ * - On success: `Outcome.makeSuccess(true)` indicating the copy was successful.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message if the copy fails.
+ */
+export async function copyDir(sftp, sourceDir, targetDir, options) {
+    const { overwrite = false, ensureDir = true, ...transferOptions } = options ?? {};
+    async function recurse(dir) {
+        const list = await sftp.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.type === 'd') {
+                if (ensureDir)
+                    await sftp.mkdir(dst, true);
+                await recurse(src);
+            }
+            else if (entry.type === '-') {
+                if (!overwrite) {
+                    const exists = await sftp.exists(dst);
+                    if (exists !== false)
+                        throw new Error(`File already exists at ${dst}.`);
+                }
+                if (ensureDir) {
+                    const dirPath = dst.substring(0, dst.lastIndexOf('/'));
+                    await sftp.mkdir(dirPath, true);
+                }
+                const pass = new PassThrough();
+                const upload = sftp.put(pass, dst, transferOptions);
+                await sftp.get(src, pass, transferOptions);
+                await upload;
+            }
+        }
+    }
+    try {
+        if (ensureDir)
+            await sftp.mkdir(targetDir, true);
+        await recurse(sourceDir);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

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

@@ -1,9 +1,23 @@
-import {
-  list
-} from "../../../../chunks/chunk-2IGP6V77.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 SFTP server.
+ *
+ * This function returns only the immediate files (not recursive) under the specified directory.
+ *
+ * @param {Client} sftp - The ssh2-sftp-client instance used to interact with the SFTP 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(sftp, directoryPath) {
+    try {
+        const list = await sftp.list(directoryPath);
+        const files = list
+            .filter(entry => entry.type === '-')
+            .map(entry => (directoryPath.endsWith('/') ? directoryPath + entry.name : directoryPath + '/' + entry.name));
+        return Outcome.makeSuccess(files);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

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

@@ -1,9 +1,38 @@
-import {
-  moveDir
-} from "../../../../chunks/chunk-TAXFCVFE.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 SFTP server using `rename`, which moves
+ * the entire tree in one operation when supported by the server.
+ *
+ * If `ensureDir` is true (default), the parent directory of `targetDir` is
+ * created if it does not exist.
+ *
+ * @param {Client} sftp - The SFTP 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.
+ * @param {boolean} [options.overwrite=false] - If false and `targetDir` exists, abort.
+ * @param {boolean} [options.ensureDir=true] - Whether to create the parent directory of `targetDir`.
+ * @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(sftp, sourceDir, targetDir, options) {
+    const { overwrite = false, ensureDir = true } = options ?? {};
+    try {
+        if (ensureDir) {
+            const parentDir = targetDir.substring(0, targetDir.lastIndexOf('/'));
+            await sftp.mkdir(parentDir, true);
+        }
+        if (!overwrite) {
+            const exists = await sftp.exists(targetDir);
+            if (exists !== false)
+                return Outcome.makeFailure(`Target ${targetDir} already exists.`);
+        }
+        await sftp.rename(sourceDir, targetDir);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

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

@@ -1,9 +1,42 @@
-import {
-  removeDir
-} from "../../../../chunks/chunk-B6653QJD.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 SFTP server.
+ *
+ * @param {Client}  sftp           - The SFTP 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 the
+ *   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(sftp, directoryPath, options) {
+    const { ignoreMissing = true } = options ?? {};
+    async function recurse(dir) {
+        const list = await sftp.list(dir);
+        for (const entry of list) {
+            const full = dir.endsWith('/') ? dir + entry.name : `${dir}/${entry.name}`;
+            if (entry.type === 'd') {
+                await recurse(full);
+            }
+            else if (entry.type === '-') {
+                await sftp.delete(full);
+            }
+        }
+        await sftp.rmdir(dir);
+    }
+    try {
+        await recurse(directoryPath);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        // ssh2-sftp-client uses code 2 / ENOENT for “No such file or directory”
+        if (ignoreMissing && (err.code === 2 || err.code === 'ENOENT')) {
+            return Outcome.makeSuccess(true);
+        }
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

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

@@ -1,9 +1,40 @@
-import {
-  copy
-} from "../../../../chunks/chunk-R66GH2MQ.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 SFTP server using streams
+ * (avoids loading the entire file into memory).
+ *
+ * @param {Client}  sftp       - The ssh2‑sftp‑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(sftp, sourcePath, targetPath, options) {
+    const { overwrite = false, ensureDir = true, ...transferOptions } = options ?? {};
+    try {
+        // Abort if destination exists and overwrite is disabled
+        if (!overwrite) {
+            const exists = await sftp.exists(targetPath);
+            if (exists !== false)
+                return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+        }
+        // Create missing target directories if requested
+        if (ensureDir) {
+            const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+            await sftp.mkdir(dirPath, true);
+        }
+        // Stream copy: download → PassThrough → upload
+        const pass = new PassThrough();
+        const uploadPromise = sftp.put(pass, targetPath, transferOptions);
+        await sftp.get(sourcePath, pass, transferOptions);
+        await uploadPromise;
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

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

@@ -1,9 +1,27 @@
-import {
-  download
-} from "../../../../chunks/chunk-AG4VERYN.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  download
-};
+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 SFTP server.
+ *
+ * This function downloads a file from the given SFTP 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} sftp - The ssh2-sftp-client instance used to interact with the SFTP server.
+ * @param {string} sourcePath - The path of the file to be downloaded from the SFTP server.
+ * @param {DownloadOptions} [options] - Optional settings for configuring the download process.
+ * @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(sftp, sourcePath, options) {
+    try {
+        const stream = sftp.createReadStream(sourcePath, options);
+        stream.on('error', (err) => { throw err; });
+        return Outcome.makeSuccess(stream);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}

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

@@ -1,9 +1,30 @@
-import {
-  exists
-} from "../../../../chunks/chunk-JB27MAKY.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  exists
-};
+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 SFTP server.
+ *
+ * `sftp.exists(path)` resolves to:
+ *   • `'d'` – the path exists and is a **directory**
+ *   • `'-'` – the path exists and is a **regular file**
+ *   • `'l'` – the path exists and is a **symlink**
+ *   • `false` – the path does **not** exist
+ *
+ * For the purpose of this util we treat a regular file (`'-'`) **or** a
+ * symlink (`'l'`) as a “file”. A directory (`'d'`) returns `false`.
+ *
+ * @param {Client} sftp        - The ssh2‑sftp‑client instance.
+ * @param {string} sourcePath  - The path to check.
+ * @returns {Promise<Outcome.Either<boolean, string>>}
+ * - Success: `Outcome.makeSuccess(true | false)` indicating file existence.
+ * - Failure: `Outcome.makeFailure(errStr)` if an error occurs.
+ */
+export async function exists(sftp, sourcePath) {
+    try {
+        const res = await sftp.exists(sourcePath); // 'd' | '-' | 'l' | false
+        const isFile = res === '-' || res === 'l';
+        return Outcome.makeSuccess(isFile);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/sftp/file/index.d.ts

@@ -1,7 +1,7 @@
 export * as copy from './copy/index.js'
-export * as download from './download/index.js'
 export * as exists from './exists/index.js'
-export * as move from './move/index.js'
+export * as download from './download/index.js'
 export * as remove from './remove/index.js'
 export * as stat from './stat/index.js'
 export * as upload from './upload/index.js'
+export * as move from './move/index.js'

package/node/sftp/file/index.js

@@ -1,7 +1,7 @@
 export * as copy from './copy/index.js'
-export * as download from './download/index.js'
 export * as exists from './exists/index.js'
-export * as move from './move/index.js'
+export * as download from './download/index.js'
 export * as remove from './remove/index.js'
 export * as stat from './stat/index.js'
 export * as upload from './upload/index.js'
+export * as move from './move/index.js'

package/node/sftp/file/move/index.js

@@ -1,9 +1,42 @@
-import {
-  move
-} from "../../../../chunks/chunk-EYYNCLVR.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  move
-};
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+/**
+ * Moves (renames) a file on an SFTP server.
+ *
+ * The function uses `rename`, which atomically moves the file from
+ * `sourcePath` to `targetPath`.  It supports two safety features:
+ *
+ * 1. **ensureDir** – If enabled, the parent directory of `targetPath`
+ *    is created with `mkdir -p` semantics before the rename.
+ * 2. **overwrite** – If disabled (default) the function first checks whether
+ *    something already exists at `targetPath`; if so, it aborts.
+ *
+ * @param {Client} sftp          - The ssh2‑sftp‑client instance.
+ * @param {string} sourcePath    - The full path of the source file.
+ * @param {string} targetPath    - The full destination path.
+ * @param {MoveOptions} [options] - Optional move configuration.
+ * @param {boolean} [options.ensureDir=true]  - Whether to create missing parent directories.
+ * @param {boolean} [options.overwrite=false] - Whether to overwrite an existing destination.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success:  `Outcome.makeSuccess(true)`.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function move(sftp, sourcePath, targetPath, options) {
+    const { ensureDir = true, overwrite = false } = options ?? {};
+    try {
+        if (ensureDir) {
+            const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+            await sftp.mkdir(dirPath, true); // mkdir -p
+        }
+        if (!overwrite) {
+            const exists = await sftp.exists(targetPath) !== false;
+            if (exists)
+                return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+        }
+        await sftp.rename(sourcePath, targetPath);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/sftp/file/remove/index.js

@@ -1,9 +1,33 @@
-import {
-  remove
-} from "../../../../chunks/chunk-SYH5LYQC.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  remove
-};
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+/**
+ * Deletes a file from a specified SFTP server.
+ *
+ * This function removes the file located at the given path on the SFTP server.
+ * The deletion process can be customized using optional delete options.
+ * If the `ignoreMissing` option is true, it does not treat a missing file as an error.
+ *
+ * @param {SftpClient} sftp - The ssh2-sftp-client instance used to interact with the SFTP server.
+ * @param {string} targetPath - The path of the file to delete on the SFTP server.
+ * @param {RemoveOptions} [options] - Optional settings for configuring the deletion process.
+ * @returns {Promise<Outcome.Either<true, string>>} A promise that resolves to an Outcome.Either.
+ * - On success: Outcome.makeSuccess(true) indicating the deletion was successful.
+ * - On failure: Outcome.makeFailure(errStr) with an error message if the deletion fails.
+ */
+export async function remove(sftp, targetPath, options) {
+    const { ignoreMissing = true } = options ?? {};
+    try {
+        const exists = await sftp.exists(targetPath) !== false;
+        if (!exists) {
+            if (ignoreMissing)
+                return Outcome.makeSuccess(true);
+            return Outcome.makeFailure(`File not found at ${targetPath}.`);
+        }
+        await sftp.delete(targetPath);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}