ssh-client-wrapper 2.12.4 → 2.13.0

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release and Publish
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    uses: ./.github/workflows/run_test.yml
+
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - name: Semantic Release
+        uses: cycjimmy/semantic-release-action@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/run_test.yml

@@ -1,11 +1,8 @@
 name: run UT
 on:
-  push:
-    tags-ignore:
-      - 'v*'
+  pull_request:
     branches:
-      - '*'
-      - '!main'
+      - main
   workflow_call:
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

package/.husky/_pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.husky/pre-commit

@@ -1,4 +1 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
 npx lint-staged

package/.releaserc.json

@@ -0,0 +1,16 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    ["@semantic-release/npm", {
+      "npmPublish": true
+    }],
+    ["@semantic-release/git", {
+      "assets": ["package.json", "package-lock.json", "CHANGELOG.md"],
+      "message": "chore(release): ${nextRelease.version} [skip ci]\\n\\n${nextRelease.notes}"
+    }],
+    "@semantic-release/github"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# [2.13.0](https://github.com/so5/ssh-client-wrapper/compare/v2.12.4...v2.13.0) (2025-08-20)
+
+
+### Bug Fixes
+
+* upgrade debug from 4.4.0 to 4.4.1 ([35f966a](https://github.com/so5/ssh-client-wrapper/commit/35f966a7212d6bb9677964688bb94ae06f869ada))
+
+
+### Features
+
+* Improve DX and automate releases ([805f2ea](https://github.com/so5/ssh-client-wrapper/commit/805f2ea7756f6ad61238a4a21d86575a17e748d9))
+* Rewrite in ESM ([c5a95c1](https://github.com/so5/ssh-client-wrapper/commit/c5a95c18401e7b373249d3707609f2a9576f7400))
+* Rewrite in ESM ([71ed6f5](https://github.com/so5/ssh-client-wrapper/commit/71ed6f56af43cac1471cbf4a4ed3016f7e55ab4d))

package/README.md

@@ -4,3 +4,102 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/8f3c0ea00e755ae31081/maintainability)](https://codeclimate.com/github/so5/ssh-client-wrapper/maintainability)
 # ssh-client-wrapper
 open ssh client wrapper library for nodejs
+
+## Installation
+```bash
+npm install ssh-client-wrapper
+```
+
+## Usage
+Here is a simple example of how to use `ssh-client-wrapper` to execute a command on a remote server.
+
+```javascript
+import SshClientWrapper from 'ssh-client-wrapper';
+
+const hostInfo = {
+  host: 'remote.server.com',
+  port: 22,
+  user: 'username',
+  password: 'password'
+};
+
+const ssh = new SshClientWrapper(hostInfo);
+
+async function run() {
+  try {
+    await ssh.canConnect();
+    console.log('Connection successful!');
+
+    const { output, rt } = await ssh.execAndGetOutput('ls -l /home');
+    if (rt === 0) {
+      console.log('Directory listing:');
+      output.forEach(line => console.log(line));
+    } else {
+      console.error('Error executing command');
+    }
+  } catch (err) {
+    console.error('Connection or command failed:', err);
+  } finally {
+    ssh.disconnect();
+  }
+}
+
+run();
+```
+
+## API Guide
+
+### `new SshClientWrapper(hostInfo)`
+Creates a new SSH client instance.
+
+*   `hostInfo` (Object): Connection details for the remote host.
+    *   `host` (string): The hostname or IP address of the server.
+    *   `user` (string): The username for authentication.
+    *   `port` (number, optional): The port number. Defaults to 22.
+    *   `password` (string | Function, optional): The password for authentication, or a function that returns the password.
+    *   `keyFile` (string, optional): The path to the private key file for key-based authentication.
+    *   `passphrase` (string | Function, optional): The passphrase for the private key, or a function that returns it.
+    *   `noStrictHostKeyChecking` (boolean, optional): If `true`, bypasses strict host key checking.
+    *   And more... see `lib/index.js` for all available options.
+
+### `.exec(cmd, [timeout], [outputCallback], [rcfile], [prependCmd])`
+Executes a command on the remote host.
+
+*   Returns: `Promise<number>` - The return code of the command.
+
+### `.execAndGetOutput(cmd, [timeout], [rcfile], [prependCmd])`
+Executes a command and returns its standard output.
+
+*   Returns: `Promise<{output: string[], rt: number}>` - An object containing the output as an array of strings and the return code.
+
+### `.ls(target, [lsOpt], [timeout])`
+Executes the `ls` command on the remote host.
+
+*   Returns: `Promise<string[]>` - The output of the `ls` command as an array of strings.
+
+### `.expect(cmd, expects, [timeout])`
+Executes a command and interacts with it, similar to the `expect` tool.
+
+*   Returns: `Promise<number>` - The return code of the command.
+
+### `.send(src, dst, [opt], [timeout])`
+Uploads files or directories to the remote host using `rsync`.
+
+*   `src` (string[]): An array of local paths to send.
+*   `dst` (string): The remote destination path.
+*   Returns: `Promise<void>`
+
+### `.recv(src, dst, [opt], [timeout])`
+Downloads files or directories from the remote host using `rsync`.
+
+*   `src` (string[]): An array of remote paths to receive.
+*   `dst` (string): The local destination path.
+*   Returns: `Promise<void>`
+
+### `.canConnect([timeout])`
+Checks if a connection to the remote host can be established.
+
+*   Returns: `Promise<boolean>` - Resolves with `true` on success.
+
+### `.disconnect()`
+Closes the master SSH connection to the remote host.

package/eslint.config.mjs

@@ -1,39 +1,25 @@
-"use strict";
 import js from "@eslint/js";
 import globals from "globals";
 import stylistic from "@stylistic/eslint-plugin";
 import jsdoc from "eslint-plugin-jsdoc";
-import node from "eslint-plugin-node";
-import chaiFriendly from "eslint-plugin-chai-friendly";
-
-const jsdocRules = {
-  "jsdoc/require-jsdoc": ["warn", { enableFixer: false }],
-  "jsdoc/require-param": ["warn", { enableFixer: false }],
-  "jsdoc/require-param-description": "warn",
-  "jsdoc/require-param-name": "warn",
-  "jsdoc/require-param-type": "warn",
-  "jsdoc/require-hyphen-before-param-description": [
-    "warn",
-    "always",
-  ],
-  "jsdoc/require-returns": "warn",
-  "jsdoc/require-returns-check": "error",
-};
+import eslintPluginChaiFriendly from "eslint-plugin-chai-friendly";
+import eslintPluginChaiExpect from "eslint-plugin-chai-expect";
 
 const styleRules = {
+  "arrow-body-style": ["error", "always"],
   "@stylistic/arrow-spacing": [
     "error",
     {
       after: false,
-      before: false,
+      before: false
     }],
   "@stylistic/comma-dangle": [
     "error",
-    "never",
+    "never"
   ],
   "@stylistic/spaced-comment": [
     "error",
-    "never",
+    "never"
   ],
   "@stylistic/lines-around-comment": [
     "error",
@@ -42,32 +28,32 @@ const styleRules = {
       afterBlockComment: false,
       beforeLineComment: false,
       afterLineComment: false,
-      allowBlockStart: true,
-    },
+      allowBlockStart: true
+    }
   ],
   "@stylistic/lines-between-class-members": [
     "error",
     "always",
     {
-      exceptAfterSingleLine: true,
-    },
+      exceptAfterSingleLine: true
+    }
   ],
   "@stylistic/newline-per-chained-call": [
     "error",
     {
-      ignoreChainWithDepth: 2,
-    },
+      ignoreChainWithDepth: 2
+    }
   ],
   "@stylistic/padded-blocks": [
     "error",
-    "never",
+    "never"
   ],
   "@stylistic/brace-style": [
     "error",
     "1tbs",
     {
-      allowSingleLine: true,
-    },
+      allowSingleLine: true
+    }
   ],
   "@stylistic/padding-line-between-statements": [
     "error",
@@ -76,9 +62,9 @@ const styleRules = {
       prev: [
         "const",
         "let",
-        "var",
+        "var"
       ],
-      next: "*",
+      next: "*"
     },
     {
       blankLine: "always",
@@ -90,8 +76,8 @@ const styleRules = {
         "function",
         "switch",
         "try",
-        "while",
-      ],
+        "while"
+      ]
     },
     {
       blankLine: "any",
@@ -103,7 +89,7 @@ const styleRules = {
         "while",
         "do",
         "block-like",
-        "multiline-block-like",
+        "multiline-block-like"
       ],
       next: [
         "block-like",
@@ -112,95 +98,84 @@ const styleRules = {
         "multiline-block-like",
         "switch",
         "try",
-        "while",
-      ],
-    },
+        "while"
+      ]
+    }
   ],
+  "@stylistic/quotes": [
+    "error",
+    "double"
+  ],
+  "@stylistic/semi": [
+    "error",
+    "always"
+  ]
+};
+
+const jsdocRules = {
+  "jsdoc/require-jsdoc": ["warn", { enableFixer: false }],
+  "jsdoc/require-param": ["warn", { enableFixer: false }],
+  "jsdoc/require-param-description": "warn",
+  "jsdoc/require-param-name": "warn",
+  "jsdoc/require-param-type": "warn",
+  "jsdoc/require-hyphen-before-param-description": [
+    "warn",
+    "always"
+  ],
+  "jsdoc/require-returns": "warn",
+  "jsdoc/require-returns-check": "error"
 };
 
 export default [
+  // Global configuration
+  {
+    ignores: ["coverage-report.lcov", "node_modules/"]
+  },
   js.configs.recommended,
-  jsdoc.configs["flat/recommended"],
-  stylistic.configs["disable-legacy"],
-  stylistic.configs.customize({
-    indent: 2,
-    quotes: "double",
-    semi: true,
-    arrowParens: true,
-  }),
   {
-    ignores: ["node_modules/"],
+    plugins: {
+      "@stylistic": stylistic
+    }
   },
+  // Lib configuration
   {
-    files: ["test/**/*.js"],
+    files: ["lib/**/*.js"],
     plugins: {
-      chaiFriendly,
+      jsdoc
     },
     languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
       globals: {
-        ...globals.nodeBuiltin,
-        ...globals.node,
-        it: "readonly",
-        describe: "readonly",
-        before: "readonly",
-        after: "readonly",
-        beforeEach: "readonly",
-        afterEach: "readonly",
-      },
+        ...globals.es2021,
+        ...globals.node
+      }
     },
+    rules: {
+      ...styleRules,
+      ...jsdocRules
+    }
   },
+  // Test configuration
   {
-    files: ["**/*.js"],
+    files: ["test/**/*.js"],
     plugins: {
-      node,
-      "@stylistic": stylistic,
-      jsdoc,
+      "chai-friendly": eslintPluginChaiFriendly,
+      "chai-expect": eslintPluginChaiExpect
     },
     languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
       globals: {
-        ...globals.nodeBuiltin,
+        ...globals.es2021,
         ...globals.node,
-      },
-      sourceType: "commonjs",
+        ...globals.mocha
+      }
     },
     rules: {
       ...styleRules,
-      ...jsdocRules,
-      "node/exports-style": [
-        "error",
-        "module.exports",
-      ],
-      "no-nested-ternary": "off",
-      "no-param-reassign": "warn",
-      "camelcase": [
-        "error",
-        {
-          properties: "never",
-        },
-      ],
-      "eqeqeq": [
-        "error",
-        "always",
-        {
-          null: "ignore",
-        },
-      ],
-      "func-style": [
-        "error",
-        "declaration",
-        {
-          allowArrowFunctions: true,
-        },
-      ],
-      "no-use-before-define": [
-        "error",
-        {
-          functions: false,
-        },
-      ],
-      "no-warning-comments": "warn",
-      "require-unicode-regexp": "off",
-
-    },
-  },
+      "no-unused-expressions": "off",
+      "chai-friendly/no-unused-expressions": "error"
+    }
+  }
 ];

package/lib/fork.js

@@ -1,17 +1,18 @@
-"use strict";
-const debug = require("debug")("sshClientWrapper:debug:fork");
-const debugVerbose = require("debug")("sshClientWrapper:verbose:fork");
-const debugSendPty = require("debug")("sshClientWrapper:insecure:fork");
-const { spawn } = require("node-pty");
+import Debug from "debug";
+import { spawn } from "node-pty-prebuilt-multiarch";
 
-const { rePwPrompt, rePhPrompt, reNewHostPrompt, reRemoteHostIdentificationHasChanged, buff2String, sendPty, watchDogTimer } = require("./util.js");
+import { rePwPrompt, rePhPrompt, reNewHostPrompt, reRemoteHostIdentificationHasChanged, buff2String, sendPty, watchDogTimer } from "./util.js";
+
+const debug = Debug("sshClientWrapper:debug:fork");
+const debugVerbose = Debug("sshClientWrapper:verbose:fork");
+const debugSendPty = Debug("sshClientWrapper:insecure:fork");
 
 const nodePtyOpt = {
   shell: process.platform === "win32" ? process.env.ComSpec : process.env.SHELL,
   windowsHide: true
 };
 
-function sshLoginCallback(output, ptyProcess, pw, ph, logger = debugSendPty) {
+export function sshLoginCallback(output, ptyProcess, pw, ph, logger = debugSendPty) {
   return new Promise((resolve, reject)=>{
     if (reRemoteHostIdentificationHasChanged.test(output)) {
       debug("REMOTE HOST IDENTIFICATION HAS CHANGED");
@@ -70,7 +71,7 @@ function sshLoginCallback(output, ptyProcess, pw, ph, logger = debugSendPty) {
 /**
  * create pty for master ssh session and store to hostInfo.masterPty
  */
-function createMasterPty(hostInfo) {
+export function createMasterPty(hostInfo) {
   debug("fork pty for master connection");
 
   if (hostInfo.masterPty) {
@@ -81,7 +82,7 @@ function createMasterPty(hostInfo) {
   hostInfo.masterPty = ptyProcess;
 }
 
-async function fork(hostInfo, cmd, args, timeout, outputCallback, retryableExitCodes = [], expects = []) {
+export async function fork(hostInfo, cmd, args, timeout, outputCallback, retryableExitCodes = [], expects = []) {
   return new Promise((resolve, reject)=>{
     debug(`cmd=${cmd}: args=${args}`);
     const ptyProcess = spawn(cmd, args, nodePtyOpt);
@@ -150,8 +151,3 @@ async function fork(hostInfo, cmd, args, timeout, outputCallback, retryableExitC
     });
   });
 }
-module.exports = {
-  fork,
-  createMasterPty,
-  sshLoginCallback
-};

package/lib/index.js

@@ -1,11 +1,12 @@
-"use strict";
-const fs = require("fs");
-const path = require("path");
-const debug = require("debug")("sshClientWrapper:debug:interface");
-const debugVerbose = require("debug")("sshClientWrapper:verbose:interface");
-const { sshExec, canConnect, disconnect, expect } = require("./sshExec.js");
-const { send, recv } = require("./rsyncExec.js");
-const { isArrayOfString, sanityCheck } = require("./util.js");
+import fs from "fs";
+import path from "path";
+import Debug from "debug";
+import * as sshExecModule from "./sshExec.js";
+import * as rsyncExecModule from "./rsyncExec.js";
+import { isArrayOfString, sanityCheck } from "./util.js";
+
+const debug = Debug("sshClientWrapper:debug:interface");
+const debugVerbose = Debug("sshClientWrapper:verbose:interface");
 
 /**
  * Integer means integer number but it is defined as Object for now
@@ -25,10 +26,10 @@ const { isArrayOfString, sanityCheck } = require("./util.js");
  * @param {string | Function} hostInfo.passphrase - passphrase or function which return passphrase of private key
  * @param {string} hostInfo.keyFile - private key filename
  * @param {boolean} hostInfo.noStrictHostKeyChecking - bypass host key checking if true
- * @param {Integer} hostInfo.ControlPersist=180 - how long keep master connection after last client connection has been closed (sec).
- * @param {Integer} hostInfo.ConnectTimeout=60 - timeout used when connectiong to ths SSH server
- * @param {Integer} hostInfo.maxRetry=3 - max number of retry
- * @param {Integer} hostInfo.retryDuration=1000 - duration time (msec) between each retry
+ * @param {Integer} hostInfo.ControlPersist - how long keep master connection after last client connection has been closed (sec).
+ * @param {Integer} hostInfo.ConnectTimeout - timeout used when connectiong to ths SSH server
+ * @param {Integer} hostInfo.maxRetry - max number of retry
+ * @param {Integer} hostInfo.retryDuration - duration time (msec) between each retry
  * @param {string} hostInfo.rcfile - rcfile path which will be sourced before executing actual command
  * @param {string} hostInfo.prependCmd - command string which will be executed before executing actual command
  * @param {string[]} hostInfo.sshOpt - additional options for ssh
@@ -44,13 +45,14 @@ const logAndReject = (message)=>{
  * @class
  */
 class SshClientWrapper {
-  constructor(hostInfo) {
+  constructor(hostInfo, deps = { ...sshExecModule, ...rsyncExecModule }) {
     debug("constructor called for", hostInfo.host);
     debugVerbose("hostInfo=", hostInfo);
     this.hostInfo = { ...hostInfo };
     sanityCheck(this.hostInfo);
     this.hostInfo.masterPty = null;
     this.hostInfo.rsyncVersion = null;
+    this.deps = deps;
 
     if (process.env.HOME) {
       try {
@@ -80,7 +82,7 @@ class SshClientWrapper {
     if (typeof cmd !== "string" || cmd === "") {
       return logAndReject("cmd must be string");
     }
-    return sshExec(this.hostInfo, cmd, timeout, outputCallback, rcfile, prependCmd);
+    return this.deps.sshExec(this.hostInfo, cmd, timeout, outputCallback, rcfile, prependCmd);
   }
 
   /**
@@ -99,7 +101,7 @@ class SshClientWrapper {
     };
     let rt = null;
     try {
-      rt = await sshExec(this.hostInfo, cmd, timeout, cb, rcfile, prependCmd);
+      rt = await this.deps.sshExec(this.hostInfo, cmd, timeout, cb, rcfile, prependCmd);
     } catch (e) {
     //non-zero retrun should be allowed
       if (typeof e.rt === "undefined" || e.rt < 0) {
@@ -138,7 +140,7 @@ class SshClientWrapper {
    */
   async expect(cmd, expects, timeout = 180) {
     debug("expect called", expects);
-    return expect(this.hostInfo, cmd, expects, timeout);
+    return this.deps.expect(this.hostInfo, cmd, expects, timeout);
   }
 
   /**
@@ -169,7 +171,7 @@ class SshClientWrapper {
     if (typeof opt !== "undefined" && !isArrayOfString(opt)) {
       return logAndReject("opt must be array of string");
     }
-    return send(this.hostInfo, src, dst, opt, timeout);
+    return this.deps.send(this.hostInfo, src, dst, opt, timeout);
   }
 
   /**
@@ -200,7 +202,7 @@ class SshClientWrapper {
     if (typeof opt !== "undefined" && !isArrayOfString(opt)) {
       return logAndReject("opt must be array of string");
     }
-    return recv(this.hostInfo, src, dst, opt, timeout);
+    return this.deps.recv(this.hostInfo, src, dst, opt, timeout);
   }
 
   /**
@@ -215,7 +217,7 @@ class SshClientWrapper {
     if (!Number.isInteger(timeout) || timeout <= 0) {
       return logAndReject("timeout must be positive integer");
     }
-    return canConnect(this.hostInfo, timeout);
+    return this.deps.canConnect(this.hostInfo, timeout);
   }
 
   /**
@@ -223,8 +225,8 @@ class SshClientWrapper {
    */
   async disconnect() {
     debug(`disconnect from ${this.hostInfo.host} called`);
-    disconnect(this.hostInfo);
+    this.deps.disconnect(this.hostInfo);
   }
 }
 
-module.exports = SshClientWrapper;
+export default SshClientWrapper;