ssh-client-wrapper 2.11.0 → 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/coverage_report.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/download-artifact@v3
+      - uses: actions/download-artifact@v4
         with:
           name: code-coverage-report
       - uses: paambaati/codeclimate-action@v5.0.0

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 }}
@@ -21,7 +18,6 @@ jobs:
       TEST_USER: testuser
       TEST_PW: passw0rd
       TEST_PORT: 10022
-      DEBUG: 'ssh*'
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -35,7 +31,9 @@ jobs:
       - run: npm ci
       - run: npm run test
       - run: npm run coverage
-      - uses: actions/upload-artifact@v3
+        if: matrix.node-version == '20.x'
+      - uses: actions/upload-artifact@v4
+        if: matrix.node-version == '20.x'
         with:
           name: code-coverage-report
           path: coverage-report.lcov

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

@@ -0,0 +1,181 @@
+import js from "@eslint/js";
+import globals from "globals";
+import stylistic from "@stylistic/eslint-plugin";
+import jsdoc from "eslint-plugin-jsdoc";
+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
+    }],
+  "@stylistic/comma-dangle": [
+    "error",
+    "never"
+  ],
+  "@stylistic/spaced-comment": [
+    "error",
+    "never"
+  ],
+  "@stylistic/lines-around-comment": [
+    "error",
+    {
+      beforeBlockComment: true,
+      afterBlockComment: false,
+      beforeLineComment: false,
+      afterLineComment: false,
+      allowBlockStart: true
+    }
+  ],
+  "@stylistic/lines-between-class-members": [
+    "error",
+    "always",
+    {
+      exceptAfterSingleLine: true
+    }
+  ],
+  "@stylistic/newline-per-chained-call": [
+    "error",
+    {
+      ignoreChainWithDepth: 2
+    }
+  ],
+  "@stylistic/padded-blocks": [
+    "error",
+    "never"
+  ],
+  "@stylistic/brace-style": [
+    "error",
+    "1tbs",
+    {
+      allowSingleLine: true
+    }
+  ],
+  "@stylistic/padding-line-between-statements": [
+    "error",
+    {
+      blankLine: "any",
+      prev: [
+        "const",
+        "let",
+        "var"
+      ],
+      next: "*"
+    },
+    {
+      blankLine: "always",
+      prev: "*",
+      next: [
+        "class",
+        "do",
+        "for",
+        "function",
+        "switch",
+        "try",
+        "while"
+      ]
+    },
+    {
+      blankLine: "any",
+      prev: [
+        "const",
+        "let",
+        "var",
+        "for",
+        "while",
+        "do",
+        "block-like",
+        "multiline-block-like"
+      ],
+      next: [
+        "block-like",
+        "do",
+        "for",
+        "multiline-block-like",
+        "switch",
+        "try",
+        "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,
+  {
+    plugins: {
+      "@stylistic": stylistic
+    }
+  },
+  // Lib configuration
+  {
+    files: ["lib/**/*.js"],
+    plugins: {
+      jsdoc
+    },
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        ...globals.es2021,
+        ...globals.node
+      }
+    },
+    rules: {
+      ...styleRules,
+      ...jsdocRules
+    }
+  },
+  // Test configuration
+  {
+    files: ["test/**/*.js"],
+    plugins: {
+      "chai-friendly": eslintPluginChaiFriendly,
+      "chai-expect": eslintPluginChaiExpect
+    },
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        ...globals.es2021,
+        ...globals.node,
+        ...globals.mocha
+      }
+    },
+    rules: {
+      ...styleRules,
+      "no-unused-expressions": "off",
+      "chai-friendly/no-unused-expressions": "error"
+    }
+  }
+];

package/lib/fork.js

@@ -1,18 +1,19 @@
-"use strict";
-const debug = require("debug")("sshClientWrapper:debug:fork");
-const debugVerbose = require("debug")("sshClientWrapper:verbose:fork");
-const debugSendPty = require("debug")("sshClientWrapperInsecure:fork_sendpty");
-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) {
-  return new Promise((resolve, reject) => {
+export function sshLoginCallback(output, ptyProcess, pw, ph, logger = debugSendPty) {
+  return new Promise((resolve, reject)=>{
     if (reRemoteHostIdentificationHasChanged.test(output)) {
       debug("REMOTE HOST IDENTIFICATION HAS CHANGED");
       const rt = /known_hosts:(\d+)/.exec(output);
@@ -38,10 +39,10 @@ function sshLoginCallback (output, ptyProcess, pw, ph, logger = debugSendPty) {
       if (typeof pw === "function") {
         debug("call password callback function");
         pw()
-          .then((v) => {
+          .then((v)=>{
             sendPty(ptyProcess, `${v}\n`, logger, 30);
           })
-          .catch((e) => {
+          .catch((e)=>{
             reject(e);
           });
         resolve();
@@ -56,10 +57,10 @@ function sshLoginCallback (output, ptyProcess, pw, ph, logger = debugSendPty) {
       if (typeof ph === "function") {
         debug("call passphrase callback function");
         ph()
-          .then((v) => {
+          .then((v)=>{
             sendPty(ptyProcess, `${v}\n`, logger, 45);
           })
-          .catch((e) => {
+          .catch((e)=>{
             reject(e);
           });
       }
@@ -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,13 +82,13 @@ function createMasterPty (hostInfo) {
   hostInfo.masterPty = ptyProcess;
 }
 
-async function fork (hostInfo, cmd, args, timeout, outputCallback, retryableExitCodes = []) {
-  return new Promise((resolve, reject) => {
+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);
     let ac = null;
     if (timeout > 0) {
-      ac = watchDogTimer(timeout, cmd, () => {
+      ac = watchDogTimer(timeout, cmd, ()=>{
         ptyProcess.kill();
         const err = new Error(`watchdog timer expired ${timeout}`);
         err.code = "TIMEEXPIRE";
@@ -97,7 +98,7 @@ async function fork (hostInfo, cmd, args, timeout, outputCallback, retryableExit
     ptyProcess.onData(buff2String.bind(null, debugVerbose));
 
     if (hostInfo !== null) {
-      ptyProcess.onData(async (data) => {
+      ptyProcess.onData((data)=>{
         const output = data.toString();
         sshLoginCallback(output, ptyProcess, hostInfo.password, hostInfo.passphrase)
           .catch(reject);
@@ -108,13 +109,25 @@ async function fork (hostInfo, cmd, args, timeout, outputCallback, retryableExit
           err.retryable = true;
           reject(err);
         }
+
+        if (Array.isArray(expects) && expects.length > 0) {
+          const { reExpect, send, numKeep } = expects.shift();
+          if (reExpect.test(output)) {
+            sendPty(ptyProcess, `${send}\n`, debugSendPty, "userDefinedHandler").catch(reject);
+            if (numKeep > 0) {
+              expects.unshift({ reExpect, send, numKeep: numKeep - 1 });
+            }
+          } else {
+            expects.unshift({ reExpect, send, numKeep });
+          }
+        }
       });
     }
 
     if (typeof outputCallback === "function") {
       ptyProcess.onData(buff2String.bind(null, outputCallback));
     }
-    ptyProcess.onExit(({ exitCode, signal }) => {
+    ptyProcess.onExit(({ exitCode, signal })=>{
       debug("onExit", exitCode, signal);
 
       if (ac !== null) {
@@ -138,8 +151,3 @@ async function fork (hostInfo, cmd, args, timeout, outputCallback, retryableExit
     });
   });
 }
-module.exports = {
-  fork,
-  createMasterPty,
-  sshLoginCallback
-};