npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

hivessh

v1.1.0

Published

HiveSsh simplifies SSH2 connections via promise-based task execution on Linux servers with built-in server utilities and powerful command execution functions

Downloads

9,965

Readme

HiveSsh

CI/CD MIT typescript npm

HiveSsh simplifies SSH2 connections via promise-based task execution on Linux servers with built-in server utilities and powerful command execution functions.

HiveSsh is a library designed to streamline SSH2 connections and task execution on Linux servers. It provides user-friendly promise-based functions for efficient server operations without the need for a client application.


Key Features

HiveSsh offers the following key features:

  • All-Distributions: SSH2 and SFTP operations for all Linux servers

  • Promisified: Promise-based functions for ease of use

  • AbstractPackageManager: Built-in abstract package manager with support for apt, dnf, and yum, with additional configurability

  • Exec: Command execution utilities for event or promise-based error handling and output parsing, filtering, and mapping

Requirements

HiveSsh requires the following server environments:

  • SSH2 server
  • SFTP support
  • Linux distribution

Getting started

npm i hivessh
import { SshHost } from "hivelib"

// connect
const myHost = await SshHost.connect({
    host: "127.0.0.1",
    //port: 22, (default 22)
    //user: "root", (default root)

    password: "123456789",
})
// or
const myHost = await SshHost.connect({
    host: "127.0.0.1",
    //port: 22, (default 22)
    //user: "root", (default root)

    privateKey: "..."
    //passphrase: "123456789"
})
// or
const myHost = await SshHost.connect({
    host: "127.0.0.1",
    //port: 22, (default 22)
    //user: "root", (default root)

    privateKeyPath:"/home/user/.ssh/id_rsa",
    //passphrase: "123456789"
})

Here are some using examples:

Promisified

Execute and assets

After connecting an SshHost, you can use the promisified execution (and other asset features) directly on the SshHost instance.

// check files in user home dir
const homeDirFiles = await myHost.exec("ls -al")
console.log("Home dir files:\n", homeDirFiles.out)

Get the hosts public ip address:

// check if curl command exists
const curlExists = await myHost.cmdExists("curl")
if(!curlExists){
  myHost.close()
  throw new Error("Curl is not installed on: " + myHost.settings.id)
}

const myIp = await myHost.exec("curl ifconfig.me")
console.log("Host public ip: " + myIp.out)
//other sources: `api.ipify.org`, `ipinfo.io/ip` or `ipecho.net/plain`

You can also execute commands on absolut path:

const etcDirFiles = await myHost.exec(
  "ls -al",
  { pwd: "/etc" }
)
console.log("Etc files: ", etcDirFiles.out)

Also a git example:

// check if git command exists
const gitExists = await myHost.cmdExists("git")
if(!gitExists){
  myHost.close()
  throw new Error("Git is not installed on: " + myHost.settings.id)
}

// get git status
const gitStatus = await myHost.exec(
  "git status",
  {
    pwd: "/home/tester/myrepo"
  }
)

console.log("Git status:\n", gitStatus.out)

Sftp

You can also use the promisified SFTP features via SshHost.sftp.

const myBinary: Buffer = await myHost.sftp.readFile("/home/tester/my-binary")

const exampleConfig: string = await myHost.sftp.readFile("/etc/example/config.yml", "utf8")

AbstractPackageManager

With the abstract package manager (apm) you can use apt, dnf, yum or a custom implemented package manager via one interface. The apm features are limited and general, but you can update your system and install, delete and list your packages.

// upgrade all packages using the abstract package manager
const apm = await myHost.getApm()
await apm.updateCache()
await apm.upgradeAll()

// install a package using the abstract package manager
await apm.install("git")

Custom package manager

For creating a custon apm you need to implement the following typescript interface: https://github.com/NobleMajo/hivessh/blob/main/src/apm/ApmInterface.ts

Register package manager

After implementing the custom package manager you need to register it global via a checker function:

import { apmChecker, AbstractPackageManager } from "./apm/apm.js"

apmChecker.push(async (host) => {
    if (await host.cmdExists("myapm")) {
        const myApm: AbstractPackageManager = { ... }

        return myApm
    }
})

This function is called when the getApm() is called and can return a package manager depending on the host.

Exec Session

Sessions are available so that the PWD (process working directory) and environment do not have to be specified for every single command. These sessions store that persistent settings across multiple executions and can even resolve relative paths.

const session = host.session("/etc/example")

session.exec("ls -al") // is executed at /etc/example
session.exec("./myApp") // is using MY_APP_ENV_VAR

Example with more options:

const session = host.session("/etc/someapp")

//if sudo is needed enable it for following processes
session.sudo = true

// set process environment variables for following processes
session.env.TZ = "Europe/Berlin"
session.env.NODE_ENV = "production"

// change directory (without checking if exists) for following processes
// shortcut for session.env.PWD = "/etc/someapp/dist"
session.cd("/etc/someapp/dist")

// execute my app with earlier defined environment
session.exec("node myApp.js")

Technologies

HiveSsh is built using the following technologies:

Contributing

Contributions to HiveSsh are welcome!
Interested users can refer to the guidelines provided in the CONTRIBUTING.md file to contribute to the project and help improve its functionality and features.

License

HiveSsh is licensed under the MIT license, providing users with flexibility and freedom to use and modify the software according to their needs.

Disclaimer

HiveSsh is provided without warranties.
Users are advised to review the accompanying license for more information on the terms of use and limitations of liability.