@maiyunnet/kebab 2.0.6 → 2.0.8

package/lib/ssh/sftp.d.ts

@@ -1,7 +1,14 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-10 12:06
+ * Last: 2020-4-11 09:28:11, 2022-09-11 17:15:38, 2023-4-24 21:43:42
+ */
 import * as stream from 'stream';
 import * as ssh2 from 'ssh2';
 export declare class Connection {
+    /** --- 连接对象 --- */
     private readonly _client;
+    /** --- 当前路径，以 / 结尾 --- */
     private _path;
     constructor(sftp: ssh2.SFTPWrapper, path: string);
     getContent(path: string, options?: {
@@ -13,28 +20,127 @@ export declare class Connection {
         'start'?: number;
         'end'?: number;
     }): Promise<string | null>;
+    /**
+     * --- 写入文件内容 ---
+     * @param path 文件路径
+     * @param data 要写入的内容
+     * @param options 选项
+     */
     putContent(path: string, data: string | Buffer, options?: ssh2.WriteFileOptions): Promise<boolean>;
+    /**
+     * --- 读取链接的 target ---
+     * @param path 要读取的路径
+     */
     readLink(path: string): Promise<string | null>;
+    /**
+     * --- 把源文件创建一个 link ---
+     * @param filePath 源文件
+     * @param linkPath 连接路径
+     */
     symlink(filePath: string, linkPath: string): Promise<boolean>;
+    /**
+     * --- 删除一个文件 ---
+     * @param path 要删除的文件路径
+     */
     unlink(path: string): Promise<boolean>;
+    /** --- unlink 的删除的 promise 实现 --- */
     private _unlink;
+    /**
+     * --- 获取对象是否存在，存在则返回 stats 对象，否则返回 null ---
+     * @param path 对象路径
+     */
     stats(path: string): Promise<ssh2.Stats | null>;
+    /**
+     * --- 判断是否是目录或目录是否存在，是的话返回 stats ---
+     * @param path 判断路径
+     */
     isDir(path: string): Promise<ssh2.Stats | false>;
+    /**
+     * --- 判断是否是文件或文件是否存在，是的话返回 stats ---
+     * @param path 判断路径
+     */
     isFile(path: string): Promise<ssh2.Stats | false>;
+    /**
+     * --- 深度创建目录，如果最末目录存在，则自动创建成功 ---
+     * @param path 要创建的路径，如 /a/b/c/
+     * @param mode 权限
+     */
     mkdir(path: string, mode?: number): Promise<boolean>;
+    /**
+     * --- 删除一个空目录 ---
+     * @param path 要删除的目录路径
+     */
     rmdir(path: string): Promise<boolean>;
+    /**
+     * --- Danger 危险：危险函数，尽量不要使用 ---
+     * --- This f**king is a dangerous function, please don't use it ---
+     * --- 删除一个非空目录 ---
+     */
     rmdirDeep(path: string): Promise<boolean>;
+    /**
+     * --- 修改权限 ---
+     * @param path 要修改的路径
+     * @param mode 权限
+     */
     chmod(path: string, mode: string | number): Promise<boolean>;
+    /**
+     * --- 重命名/移动 文件文件夹 ---
+     * @param oldPath 老名
+     * @param newPath 新名
+     */
     rename(oldPath: string, newPath: string): Promise<boolean>;
+    /**
+     * --- 获取文件夹下文件列表 ---
+     * @param path 文件夹路径
+     */
     readDir(path: string): Promise<ssh2.FileEntry[]>;
+    /**
+     * --- 读取文件流 ---
+     * @param path 文件地址
+     */
     createReadStream(path: string, options?: ssh2.ReadStreamOptions): stream.Readable;
+    /**
+     * --- 读取文件写入到流，并等待写入完成 ---
+     * @param path 文件地址
+     * @param destination 要写入的流
+     * @param options 写入后是否终止写入流，默认终止
+     */
     pipe<T extends NodeJS.WritableStream>(path: string, destination: T, options?: {
         'end'?: boolean;
     }): Promise<boolean>;
+    /**
+     * --- 创建写入文件的流 ---
+     * @param path 文件地址
+     * @param options 编码或配置
+     */
     createWriteStream(path: string, options?: BufferEncoding | ssh2.WriteStreamOptions): stream.Writable;
+    /**
+     * --- 获取当前目录，末尾不带 / ---
+     * @return string
+     */
     pwd(): string;
+    /**
+     * --- 下载文件到本地 ---
+     * @param remoteFile 远程路径
+     * @param localFile 本地路径
+     * @param options 选项
+     */
     downloadFile(remoteFile: string, localFile: string, options?: ssh2.TransferOptions): Promise<boolean>;
+    /**
+     * --- 上传本地文件到远程 ---
+     * @param localFile 本地绝对路径
+     * @param remoteFile
+     * @return bool
+     */
     uploadFile(localFile: string, remoteFile: string, options?: ssh2.TransferOptions): Promise<boolean>;
+    /**
+     * --- 进入一个目录（不存在也能进入，需要自行判断） ---
+     * --- 返回进入后的路径值 ---
+     * @param dir 相对路径或绝对路径
+     */
     cd(dir: string): string;
+    /**
+     * --- 关闭当前频道 ---
+     */
     close(): void;
 }

package/lib/ssh/sftp.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Connection = void 0;
+// --- 库和定义 ---
 const core = __importStar(require("../../lib/core"));
 const text = __importStar(require("../../lib/text"));
 class Connection {
@@ -41,6 +42,11 @@ class Connection {
         this._client = sftp;
         this._path = path;
     }
+    /**
+     * --- 读取完整文件或一段 ---
+     * @param path 文件路径
+     * @param options 编码或选项
+     */
     getContent(path, options) {
         path = text.urlResolve(this._path, path);
         if (typeof options === 'string') {
@@ -102,6 +108,12 @@ class Connection {
             }
         });
     }
+    /**
+     * --- 写入文件内容 ---
+     * @param path 文件路径
+     * @param data 要写入的内容
+     * @param options 选项
+     */
     putContent(path, data, options = {}) {
         path = text.urlResolve(this._path, path);
         return new Promise((resolve) => {
@@ -115,6 +127,10 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 读取链接的 target ---
+     * @param path 要读取的路径
+     */
     readLink(path) {
         path = text.urlResolve(this._path, path);
         return new Promise((resolve) => {
@@ -128,6 +144,11 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 把源文件创建一个 link ---
+     * @param filePath 源文件
+     * @param linkPath 连接路径
+     */
     symlink(filePath, linkPath) {
         filePath = text.urlResolve(this._path, filePath);
         linkPath = text.urlResolve(this._path, linkPath);
@@ -142,6 +163,10 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 删除一个文件 ---
+     * @param path 要删除的文件路径
+     */
     async unlink(path) {
         path = text.urlResolve(this._path, path);
         for (let i = 0; i < 2; ++i) {
@@ -153,6 +178,7 @@ class Connection {
         }
         return this._unlink(path);
     }
+    /** --- unlink 的删除的 promise 实现 --- */
     _unlink(path) {
         return new Promise((resolve) => {
             this._client.unlink(path, function (err) {
@@ -165,6 +191,10 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 获取对象是否存在，存在则返回 stats 对象，否则返回 null ---
+     * @param path 对象路径
+     */
     stats(path) {
         path = text.urlResolve(this._path, path);
         return new Promise((resolve) => {
@@ -178,6 +208,10 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 判断是否是目录或目录是否存在，是的话返回 stats ---
+     * @param path 判断路径
+     */
     async isDir(path) {
         const pstats = await this.stats(path);
         if (!pstats?.isDirectory()) {
@@ -185,6 +219,10 @@ class Connection {
         }
         return pstats;
     }
+    /**
+     * --- 判断是否是文件或文件是否存在，是的话返回 stats ---
+     * @param path 判断路径
+     */
     async isFile(path) {
         const pstats = await this.stats(path);
         if (!pstats?.isFile()) {
@@ -192,6 +230,11 @@ class Connection {
         }
         return pstats;
     }
+    /**
+     * --- 深度创建目录，如果最末目录存在，则自动创建成功 ---
+     * @param path 要创建的路径，如 /a/b/c/
+     * @param mode 权限
+     */
     async mkdir(path, mode = 0o755) {
         path = text.urlResolve(this._path, path);
         if (await this.isDir(path)) {
@@ -220,6 +263,10 @@ class Connection {
         }
         return true;
     }
+    /**
+     * --- 删除一个空目录 ---
+     * @param path 要删除的目录路径
+     */
     async rmdir(path) {
         path = text.urlResolve(this._path, path);
         if (!(await this.isDir(path))) {
@@ -236,6 +283,11 @@ class Connection {
             });
         });
     }
+    /**
+     * --- Danger 危险：危险函数，尽量不要使用 ---
+     * --- This f**king is a dangerous function, please don't use it ---
+     * --- 删除一个非空目录 ---
+     */
     async rmdirDeep(path) {
         path = text.urlResolve(this._path, path);
         if (!path.endsWith('/')) {
@@ -251,6 +303,7 @@ class Connection {
                 return false;
             }
             if (stat.isDirectory()) {
+                // --- 目录 ---
                 const rtn = await this.rmdirDeep(path + item.filename);
                 if (!rtn) {
                     return false;
@@ -265,6 +318,11 @@ class Connection {
         }
         return this.rmdir(path);
     }
+    /**
+     * --- 修改权限 ---
+     * @param path 要修改的路径
+     * @param mode 权限
+     */
     chmod(path, mode) {
         path = text.urlResolve(this._path, path);
         return new Promise((resolve) => {
@@ -278,6 +336,11 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 重命名/移动 文件文件夹 ---
+     * @param oldPath 老名
+     * @param newPath 新名
+     */
     rename(oldPath, newPath) {
         oldPath = text.urlResolve(this._path, oldPath);
         newPath = text.urlResolve(this._path, newPath);
@@ -292,6 +355,10 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 获取文件夹下文件列表 ---
+     * @param path 文件夹路径
+     */
     readDir(path) {
         path = text.urlResolve(this._path, path);
         return new Promise((resolve) => {
@@ -305,10 +372,20 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 读取文件流 ---
+     * @param path 文件地址
+     */
     createReadStream(path, options) {
         path = text.urlResolve(this._path, path);
         return this._client.createReadStream(path, options);
     }
+    /**
+     * --- 读取文件写入到流，并等待写入完成 ---
+     * @param path 文件地址
+     * @param destination 要写入的流
+     * @param options 写入后是否终止写入流，默认终止
+     */
     pipe(path, destination, options = {}) {
         path = text.urlResolve(this._path, path);
         return new Promise((resolve) => {
@@ -319,6 +396,11 @@ class Connection {
             }).pipe(destination, options);
         });
     }
+    /**
+     * --- 创建写入文件的流 ---
+     * @param path 文件地址
+     * @param options 编码或配置
+     */
     createWriteStream(path, options) {
         if (typeof options === 'string') {
             options = {
@@ -330,9 +412,19 @@ class Connection {
         }
         return this._client.createWriteStream(path, options);
     }
+    /**
+     * --- 获取当前目录，末尾不带 / ---
+     * @return string
+     */
     pwd() {
         return this._path.slice(0, -1);
     }
+    /**
+     * --- 下载文件到本地 ---
+     * @param remoteFile 远程路径
+     * @param localFile 本地路径
+     * @param options 选项
+     */
     downloadFile(remoteFile, localFile, options = {}) {
         remoteFile = text.urlResolve(this._path, remoteFile);
         return new Promise((resolve) => {
@@ -346,6 +438,12 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 上传本地文件到远程 ---
+     * @param localFile 本地绝对路径
+     * @param remoteFile
+     * @return bool
+     */
     uploadFile(localFile, remoteFile, options = {}) {
         remoteFile = text.urlResolve(this._path, remoteFile);
         return new Promise((resolve) => {
@@ -359,6 +457,11 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 进入一个目录（不存在也能进入，需要自行判断） ---
+     * --- 返回进入后的路径值 ---
+     * @param dir 相对路径或绝对路径
+     */
     cd(dir) {
         this._path = text.urlResolve(this._path, dir);
         if (!this._path.endsWith('/')) {
@@ -366,6 +469,9 @@ class Connection {
         }
         return this._path;
     }
+    /**
+     * --- 关闭当前频道 ---
+     */
     close() {
         this._client.end();
     }

package/lib/ssh/shell.d.ts

@@ -1,13 +1,50 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-8 22:13
+ * Last: 2020-4-10 16:08:32, 2022-12-30 00:03:40, 2023-4-22 21:06:57
+ */
 import * as ssh2 from 'ssh2';
 export declare class Connection {
+    /** --- 连接对象 --- */
     private readonly _client;
     constructor(stream: ssh2.ClientChannel);
+    /**
+     * --- 发送指令 ---
+     * @param cmd 指令
+     * @param encoding 编码
+     */
     send(cmd: string | Buffer, encoding?: BufferEncoding): Promise<boolean>;
+    /**
+     * --- 发送带换行的内容（发送并执行） ---
+     * @param cmd 指令
+     * @param encoding 编码
+     */
     sendLine(cmd: string, encoding?: BufferEncoding): Promise<boolean>;
+    /**
+     * --- 发送 Enter 键 ---
+     */
     sendEnter(): Promise<boolean>;
+    /**
+     * --- 发送 Tab 键 ---
+     */
     sendTab(): Promise<boolean>;
+    /**
+     * --- 发送中断 ---
+     */
     sendCtrlC(): Promise<boolean>;
+    /**
+     * --- 关闭 shell ---
+     * @param cmd 命令
+     * @param encoding 编码
+     */
     close(cmd?: string | Buffer, encoding?: BufferEncoding): Promise<void>;
+    /**
+     * --- 获取返回值 ---
+     * @param tryCount 如果无知重试次数，1 次为 10 毫秒 ---
+     */
     getContent(tryCount?: number): Promise<Buffer>;
+    /**
+     * --- 获取响应读取流对象 ---
+     */
     getStream(): ssh2.ClientChannel;
 }

package/lib/ssh/shell.js

@@ -39,6 +39,11 @@ class Connection {
     constructor(stream) {
         this._client = stream;
     }
+    /**
+     * --- 发送指令 ---
+     * @param cmd 指令
+     * @param encoding 编码
+     */
     send(cmd, encoding) {
         return new Promise((resolve) => {
             const cb = (e) => {
@@ -57,18 +62,37 @@ class Connection {
             }
         });
     }
+    /**
+     * --- 发送带换行的内容（发送并执行） ---
+     * @param cmd 指令
+     * @param encoding 编码
+     */
     async sendLine(cmd, encoding) {
         return this.send(cmd + '\n', encoding);
     }
+    /**
+     * --- 发送 Enter 键 ---
+     */
     async sendEnter() {
         return this.send('\n');
     }
+    /**
+     * --- 发送 Tab 键 ---
+     */
     async sendTab() {
         return this.send('\t');
     }
+    /**
+     * --- 发送中断 ---
+     */
     async sendCtrlC() {
         return this.send('\x03');
     }
+    /**
+     * --- 关闭 shell ---
+     * @param cmd 命令
+     * @param encoding 编码
+     */
     close(cmd, encoding) {
         return new Promise((resolve) => {
             if (encoding) {
@@ -83,6 +107,10 @@ class Connection {
             }
         });
     }
+    /**
+     * --- 获取返回值 ---
+     * @param tryCount 如果无知重试次数，1 次为 10 毫秒 ---
+     */
     async getContent(tryCount = 10) {
         let nowCount = 0;
         let data = Buffer.from('');
@@ -102,6 +130,9 @@ class Connection {
         }
         return data;
     }
+    /**
+     * --- 获取响应读取流对象 ---
+     */
     getStream() {
         return this._client;
     }

package/lib/ssh.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-8 21:34:35
+ * Last: 2020-04-06 21:22:46, 2022-09-12 00:19:05, 2024-3-4 14:46:11
+ */
 import * as ssh2 from 'ssh2';
 import * as shell from './ssh/shell';
 import * as sftp from './ssh/sftp';
@@ -9,16 +14,43 @@ interface IExtOptions {
         'password': string;
     };
 }
+/** 主连接对象 */
 export declare class Connection {
+    /** --- SSH 对象 --- */
     private readonly _client;
+    /** --- 中转服务器 --- */
     private _mclient?;
     constructor();
+    /**
+     * --- 发起连接 ---
+     * @param opt 选项
+     */
     connect(opt: ssh2.ConnectConfig & IExtOptions): Promise<boolean>;
+    /**
+     * --- 断开此连接 socket ---
+     */
     disconnect(): void;
+    /**
+     * --- 执行一个命令并获取返回值，请不要在此执行无尽命令，否则获取不到返回值 ---
+     * @param command 命令内容
+     */
     exec(command: string): Promise<Buffer | false>;
+    /**
+     * --- 获取 Shell 执行对象 ---
+     */
     getShell(): Promise<shell.Connection | null>;
+    /**
+     * --- 获取 Sftp 执行对象 ---
+     */
     getSftp(): Promise<sftp.Connection | null>;
+    /**
+     * --- 直接获取原生 shell stream 对象 ---
+     */
     getStream(): Promise<ssh2.ClientChannel | null>;
 }
+/**
+ * --- 创建一个 SSH 连接 ---
+ * @param opt 选项
+ */
 export declare function get(opt: ssh2.ConnectConfig & IExtOptions): Promise<Connection | null>;
 export {};

package/lib/ssh.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-8 21:34:35
+ * Last: 2020-04-06 21:22:46, 2022-09-12 00:19:05, 2024-3-4 14:46:11
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -35,13 +40,20 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Connection = void 0;
 exports.get = get;
+// --- 第三方 ---
 const ssh2 = __importStar(require("ssh2"));
+// --- 自己 ---
 const shell = __importStar(require("./ssh/shell"));
 const sftp = __importStar(require("./ssh/sftp"));
+/** 主连接对象 */
 class Connection {
     constructor() {
         this._client = new ssh2.Client();
     }
+    /**
+     * --- 发起连接 ---
+     * @param opt 选项
+     */
     connect(opt) {
         return new Promise((resolve) => {
             if (!opt.mproxy) {
@@ -97,9 +109,16 @@ class Connection {
             }).connect(opt);
         });
     }
+    /**
+     * --- 断开此连接 socket ---
+     */
     disconnect() {
         this._client.end();
     }
+    /**
+     * --- 执行一个命令并获取返回值，请不要在此执行无尽命令，否则获取不到返回值 ---
+     * @param command 命令内容
+     */
     exec(command) {
         return new Promise((resolve) => {
             this._client.exec(command, function (err, channel) {
@@ -118,6 +137,9 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 获取 Shell 执行对象 ---
+     */
     getShell() {
         return new Promise((resolve) => {
             this._client.shell(function (err, channel) {
@@ -129,6 +151,9 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 获取 Sftp 执行对象 ---
+     */
     getSftp() {
         return new Promise((resolve) => {
             this._client.sftp((err, ssftp) => {
@@ -152,6 +177,9 @@ class Connection {
             });
         });
     }
+    /**
+     * --- 直接获取原生 shell stream 对象 ---
+     */
     getStream() {
         return new Promise((resolve) => {
             this._client.shell(function (err, stream) {
@@ -164,6 +192,10 @@ class Connection {
     }
 }
 exports.Connection = Connection;
+/**
+ * --- 创建一个 SSH 连接 ---
+ * @param opt 选项
+ */
 async function get(opt) {
     const conn = new Connection();
     const rtn = await conn.connect(opt);