trzsz2 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 trzsz2 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.cn.md

@@ -0,0 +1,64 @@
+# trzsz2
+
+[中文](README.cn.md) | [English](README.md)
+
+> trzsz.js 的衍生项目，提供纯协议实现，支持 Node.js 和浏览器环境。
+
+## 声明
+
+**本项目基于 [Lonny Wong](https://github.com/lonnywong) 开发的 [trzsz-js](https://github.com/trzsz/trzsz.js)。**
+
+trzsz 协议的所有原始实现功劳归 Lonny Wong 所有。这是一个衍生作品：
+
+- 移除了原始代码库中的文件系统 (`fs`) 和浏览器特定依赖
+- 专注于提供适合 Node.js 环境的纯协议实现
+- 通过浏览器构建版本保持浏览器兼容性
+
+## 从源码构建
+
+```bash
+# 克隆仓库
+git clone https://github.com/zxdong262/trzsz2.git
+cd trzsz2
+
+# 安装依赖
+npm install
+
+# 构建所有格式
+npm run build
+
+# 构建特定格式
+npm run build:esm    # 仅 ESM
+npm run build:cjs    # 仅 CommonJS
+npm run build:cjs-full  # 打包的 CommonJS
+npm run build:browser  # 浏览器包
+```
+
+## 测试
+
+```bash
+# 运行单元测试
+npm test
+
+# 运行集成测试（需要 Docker）
+npm run test:upload
+npm run test:download
+
+# 监视模式
+npm run test:watch
+```
+
+## 待办事项
+
+- [ ] 浏览器使用文档和示例
+- [ ] 浏览器环境测试和演示
+- [ ] WebRTC 数据通道集成示例
+
+## 相关项目
+
+- [trzsz-js](https://github.com/trzsz/trzsz.js) - Lonny Wong 开发的原始 trzsz 实现，包含文件系统支持
+- [trzsz](https://github.com/trzsz/trzsz) - trzsz 主项目
+
+## 许可证
+
+MIT

package/README.md

@@ -0,0 +1,70 @@
+# trzsz2
+
+[中文](README.cn.md) | [English](README.md)
+
+> trzsz.js's derivative project providing a pure protocol implementation for Node.js and browser environments.
+
+## Notice
+
+**This project is based on [trzsz-js](https://github.com/trzsz/trzsz.js) by [Lonny Wong](https://github.com/lonnywong).**
+
+All credits for the original trzsz protocol implementation go to Lonny Wong. This is a derived work that:
+
+- Removes file system (`fs`) and browser-specific dependencies from the original codebase
+- Focuses on providing a pure protocol implementation suitable for Node.js environments
+- Maintains compatibility with browser usage through the browser build
+
+## Installation
+
+```bash
+npm install trzsz2
+```
+
+## Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/zxdong262/trzsz2.git
+cd trzsz2
+
+# Install dependencies
+npm install
+
+# Build all formats
+npm run build
+
+# Build specific format
+npm run build:esm    # ESM only
+npm run build:cjs    # CommonJS only
+npm run build:cjs-full  # Bundled CommonJS
+npm run build:browser  # Browser bundle
+```
+
+## Testing
+
+```bash
+# Run unit tests
+npm test
+
+# Run integration tests (requires Docker)
+npm run test:upload
+npm run test:download
+
+# Watch mode
+npm run test:watch
+```
+
+## TODO
+
+- [ ] Browser usage documentation and examples
+- [ ] Browser environment testing and demos
+- [ ] WebRTC data channel integration example
+
+## Related Projects
+
+- [trzsz-js](https://github.com/trzsz/trzsz.js) - Original trzsz implementation with file system support by Lonny Wong
+- [trzsz](https://github.com/trzsz/trzsz) - The main trzsz project
+
+## License
+
+MIT

package/dist/browser/buffer.d.ts

@@ -0,0 +1,76 @@
+/**
+ * trzsz2: https://github.com/zxdong262/trzsz2
+ * Copyright(c) 2024 Lonny Wong
+ * @license MIT
+ *
+ * Pure protocol implementation without fs/browser dependencies.
+ */
+/**
+ * TrzszBuffer class for handling buffer operations.
+ */
+export declare class TrzszBuffer {
+    private bufArray;
+    private resolve;
+    private reject;
+    private bufHead;
+    private bufTail;
+    private nextIdx;
+    private nextBuf;
+    private arrBuf;
+    /**
+     * Add a buffer to the queue.
+     * @param buf - The buffer to add.
+     */
+    addBuffer(buf: string | ArrayBuffer | Uint8Array | Blob): void;
+    /**
+     * Stop the buffer and reject any pending operations.
+     */
+    stopBuffer(): void;
+    /**
+     * Drain all buffers.
+     */
+    drainBuffer(): void;
+    /**
+     * Convert a buffer to Uint8Array.
+     * @param buf - The buffer to convert.
+     * @return The resulting Uint8Array.
+     */
+    private toUint8Array;
+    /**
+     * Get the next buffer.
+     * @return The next buffer.
+     */
+    private nextBuffer;
+    /**
+     * Grow the buffer.
+     * @param dst - The destination buffer.
+     * @param idx - The current index.
+     * @param min - The minimum size needed.
+     * @return The grown buffer.
+     */
+    private growBuffer;
+    /**
+     * Append a buffer to another.
+     * @param dst - The destination buffer.
+     * @param idx - The current index.
+     * @param src - The source buffer.
+     * @return The resulting buffer.
+     */
+    private appendBuffer;
+    /**
+     * Read a line from the buffer.
+     * @return The line.
+     */
+    readLine(): Promise<string>;
+    /**
+     * Read binary data from the buffer.
+     * @param len - The length to read.
+     * @return The binary data.
+     */
+    readBinary(len: number): Promise<Uint8Array>;
+    /**
+     * Read a line on Windows (handles VT100 escape sequences).
+     * @return The line.
+     */
+    readLineOnWindows(): Promise<string>;
+}

package/dist/browser/comm.d.ts

@@ -0,0 +1,162 @@
+/**
+ * trzsz2: https://github.com/zxdong262/trzsz2
+ * Copyright(c) 2024 Lonny Wong
+ * @license MIT
+ *
+ * Pure protocol implementation without fs/browser dependencies.
+ */
+/**
+ * trzsz version
+ */
+export declare const trzszVersion = "2.0.0";
+/**
+ * Convert a string to Uint8Array.
+ * @param {string} str - The input string.
+ * @return {Uint8Array} The resulting Uint8Array.
+ */
+export declare function strToUint8(str: string): Uint8Array;
+/**
+ * Convert a Uint8Array to string.
+ * @param {Uint8Array} buf - The input buffer.
+ * @param {string} encoding - The encoding to use.
+ * @return {Promise<string>} The resulting string.
+ */
+export declare function uint8ToStr(buf: Uint8Array, encoding?: string): Promise<string>;
+/**
+ * Convert a string to ArrayBuffer.
+ * @param {string} str - The input string.
+ * @return {ArrayBuffer} The resulting ArrayBuffer.
+ */
+export declare function strToArrBuf(str: string): ArrayBuffer;
+/**
+ * Encode a buffer (compress and base64).
+ * @param {string | Uint8Array} buf - The input buffer.
+ * @return {string} The encoded string.
+ */
+export declare function encodeBuffer(buf: string | Uint8Array): string;
+/**
+ * Decode a buffer (base64 and decompress).
+ * @param {string} buf - The encoded string.
+ * @return {Uint8Array} The decoded buffer.
+ */
+export declare function decodeBuffer(buf: string): Uint8Array;
+/**
+ * Custom error class for trzsz operations.
+ */
+export declare class TrzszError extends Error {
+    private readonly type;
+    private readonly trace;
+    constructor(message: string, type?: string | null, trace?: boolean);
+    /**
+     * Check if the error should include traceback.
+     * @return {boolean} True if traceback should be included.
+     */
+    isTraceBack(): boolean;
+    /**
+     * Check if the error is a remote exit.
+     * @return {boolean} True if remote exit.
+     */
+    isRemoteExit(): boolean;
+    /**
+     * Check if the error is a remote failure.
+     * @return {boolean} True if remote failure.
+     */
+    isRemoteFail(): boolean;
+    /**
+     * Check if the error indicates stop and delete.
+     * @return {boolean} True if stop and delete.
+     */
+    isStopAndDelete(): boolean;
+    /**
+     * Get the error message.
+     * @param {Error} err - The error object.
+     * @return {string} The error message.
+     */
+    static getErrorMessage(err: Error): string;
+}
+/**
+ * Interface for trzsz file operations.
+ */
+export interface TrzszFile {
+    closeFile: () => void;
+}
+/**
+ * Interface for trzsz file reader.
+ */
+export interface TrzszFileReader extends TrzszFile {
+    getPathId: () => number;
+    getRelPath: () => string[];
+    isDir: () => boolean;
+    getSize: () => number;
+    readFile: (buf: ArrayBuffer) => Promise<Uint8Array>;
+}
+/**
+ * Interface for trzsz file writer.
+ */
+export interface TrzszFileWriter extends TrzszFile {
+    getFileName: () => string;
+    getLocalName: () => string;
+    isDir: () => boolean;
+    writeFile: (buf: Uint8Array) => Promise<void>;
+    deleteFile: () => Promise<string>;
+}
+/**
+ * Type for opening save file.
+ */
+export type OpenSaveFile = (saveParam: any, fileName: string, directory: boolean, overwrite: boolean) => Promise<TrzszFileWriter>;
+/**
+ * Interface for progress callback.
+ */
+export interface ProgressCallback {
+    onNum: (num: number) => void;
+    onName: (name: string) => void;
+    onSize: (size: number) => void;
+    onStep: (step: number) => void;
+    onDone: () => void;
+}
+/**
+ * Check for duplicate file names.
+ * @param {TrzszFileReader[]} files - The files to check.
+ */
+export declare function checkDuplicateNames(files: TrzszFileReader[]): void;
+/**
+ * Check if an array contains only elements of a specific type.
+ * @param {any} arr - The array to check.
+ * @param {string} type - The type to check for.
+ * @return {boolean} True if all elements are of the specified type.
+ */
+export declare function isArrayOfType(arr: any, type: string): boolean;
+/**
+ * Check if a character is a VT100 end character.
+ * @param {number} c - The character code.
+ * @return {boolean} True if it's a VT100 end character.
+ */
+export declare function isVT100End(c: number): boolean;
+/**
+ * Strip VT100 escape sequences from server output.
+ * @param {string | ArrayBuffer | Uint8Array | Blob} output - The server output.
+ * @return {string | ArrayBuffer | Uint8Array | Blob} The stripped output.
+ */
+export declare function stripServerOutput(output: string | ArrayBuffer | Uint8Array | Blob): string | ArrayBuffer | Uint8Array | Blob;
+/**
+ * Tmux mode constants.
+ */
+export declare const TmuxMode: {
+    readonly NoTmux: 0;
+    readonly TmuxNormalMode: 1;
+    readonly TmuxControlMode: 2;
+};
+export type TmuxModeType = (typeof TmuxMode)[keyof typeof TmuxMode];
+/**
+ * Format saved files message.
+ * @param {string[]} fileNames - The file names.
+ * @param {string} destPath - The destination path.
+ * @return {string} The formatted message.
+ */
+export declare function formatSavedFiles(fileNames: string[], destPath: string): string;
+/**
+ * Strip tmux status line from buffer.
+ * @param {string} buf - The input buffer.
+ * @return {string} The stripped buffer.
+ */
+export declare function stripTmuxStatusLine(buf: string): string;

package/dist/browser/escape.d.ts

@@ -0,0 +1,33 @@
+/**
+ * trzsz2: https://github.com/zxdong262/trzsz2
+ * Copyright(c) 2024 Lonny Wong
+ * @license MIT
+ *
+ * Pure protocol implementation without fs/browser dependencies.
+ */
+/**
+ * Get escape characters for trzsz protocol.
+ * @param escapeAll - Whether to escape all special characters.
+ * @return Array of escape character pairs.
+ */
+export declare function getEscapeChars(escapeAll: boolean): string[][];
+/**
+ * Convert escape characters to codes.
+ * @param escapeChars - Array of escape character pairs.
+ * @return Array of escape code triplets.
+ */
+export declare function escapeCharsToCodes(escapeChars: string[][]): number[][];
+/**
+ * Escape data using escape codes.
+ * @param data - The data to escape.
+ * @param escapeCodes - Array of escape code triplets.
+ * @return The escaped data.
+ */
+export declare function escapeData(data: Uint8Array, escapeCodes: number[][]): Uint8Array;
+/**
+ * Unescape data using escape codes.
+ * @param data - The data to unescape.
+ * @param escapeCodes - Array of escape code triplets.
+ * @return The unescaped data.
+ */
+export declare function unescapeData(data: Uint8Array, escapeCodes: number[][]): Uint8Array;

package/dist/browser/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * trzsz2: https://github.com/zxdong262/trzsz2
+ * Copyright(c) 2024 Lonny Wong
+ * @license MIT
+ *
+ * Pure protocol implementation without fs/browser dependencies.
+ */
+export { trzszVersion } from './comm';
+export type { TrzszFile, TrzszFileReader, TrzszFileWriter, OpenSaveFile, ProgressCallback, TmuxModeType } from './comm';
+export type { TrzszOptions } from './options';
+export { TrzszError } from './comm';
+export { TrzszBuffer } from './buffer';
+export { TrzszTransfer } from './transfer';
+export { TextProgressBar } from './progress';
+export { strToUint8, uint8ToStr, strToArrBuf, encodeBuffer, decodeBuffer, checkDuplicateNames, isArrayOfType, isVT100End, stripServerOutput, formatSavedFiles, stripTmuxStatusLine, TmuxMode } from './comm';
+export { getEscapeChars, escapeCharsToCodes, escapeData, unescapeData } from './escape';
+export { getEllipsisString } from './progress';

package/dist/browser/options.d.ts

@@ -0,0 +1,57 @@
+/**
+ * trzsz2: https://github.com/zxdong262/trzsz2
+ * Copyright(c) 2024 Lonny Wong
+ * @license MIT
+ *
+ * Pure protocol implementation without fs/browser dependencies.
+ */
+/**
+ * The trzsz options interface.
+ */
+export interface TrzszOptions {
+    /**
+     * Write the server output to the terminal.
+     * @param output - The server output.
+     */
+    writeToTerminal?: (output: string | ArrayBuffer | Uint8Array | Blob) => void;
+    /**
+     * Send the terminal input (aka: user input) to the server.
+     * @param input - The terminal input (aka: user input).
+     */
+    sendToServer?: (input: string | Uint8Array) => void;
+    /**
+     * Choose some files to be sent to the server.
+     * No need for webshell or which running in a browser.
+     * @param directory - choose directories and files, or just files.
+     * @return The file paths array to be sent.
+     *         undefined means the user has cancelled.
+     */
+    chooseSendFiles?: (directory?: boolean) => Promise<string[] | undefined>;
+    /**
+     * Choose a directory to save the received files.
+     * No need for webshell or which running in a browser.
+     * @return The directory to save the received files.
+     *         undefined means the user has cancelled.
+     */
+    chooseSaveDirectory?: () => Promise<string | undefined>;
+    /**
+     * @deprecated A user event may be required to open the save dialog in browsers.
+     * No need for nodejs environment ( e.g.: electron preload.js )
+     * @param fileName - The file name going to download.
+     * @return open the save dialog or cancel the download.
+     */
+    requireUserPermission?: (fileName: string) => Promise<boolean>;
+    /**
+     * The columns of terminal.
+     */
+    terminalColumns?: number;
+    /**
+     * Is there a windows shell? Such as `cmd` and `PowerShell`.
+     */
+    isWindowsShell?: boolean;
+    /**
+     * The timeout in milliseconds for initializing drag and drop files to upload.
+     * Default is 3000.
+     */
+    dragInitTimeout?: number | undefined | null;
+}

package/dist/browser/progress.d.ts

@@ -0,0 +1,100 @@
+import { ProgressCallback } from './comm';
+/**
+ * Get ellipsis string if the string is too long.
+ * @param str - The input string.
+ * @param max - The maximum length.
+ * @return The ellipsis string and its length.
+ */
+export declare function getEllipsisString(str: string, max: number): {
+    sub: string;
+    len: number;
+};
+/**
+ * TextProgressBar class for displaying file transfer progress.
+ */
+export declare class TextProgressBar implements ProgressCallback {
+    private readonly writer;
+    private lastUpdateTime;
+    private columns;
+    private fileCount;
+    private fileIdx;
+    private fileName;
+    private fileSize;
+    private fileStep;
+    private startTime;
+    private tmuxPaneColumns;
+    private firstWrite;
+    private speedCnt;
+    private speedIdx;
+    private timeArray;
+    private stepArray;
+    /**
+     * Create a TextProgressBar.
+     * @param writer - The output writer function.
+     * @param columns - The terminal columns.
+     * @param tmuxPaneColumns - The tmux pane columns (optional).
+     */
+    constructor(writer: (output: string) => void, columns: number, tmuxPaneColumns?: number | undefined);
+    /**
+     * Set the terminal columns.
+     * @param columns - The terminal columns.
+     */
+    setTerminalColumns(columns: number): void;
+    /**
+     * Called when the number of files is known.
+     * @param num - The number of files.
+     */
+    onNum(num: number): void;
+    /**
+     * Called when a file name is known.
+     * @param name - The file name.
+     */
+    onName(name: string): void;
+    /**
+     * Called when the file size is known.
+     * @param size - The file size.
+     */
+    onSize(size: number): void;
+    /**
+     * Called when a step is completed.
+     * @param step - The step number.
+     */
+    onStep(step: number): void;
+    /**
+     * Hide the cursor.
+     */
+    hideCursor(): void;
+    /**
+     * Show the cursor.
+     */
+    showCursor(): void;
+    /**
+     * Show the progress.
+     */
+    private showProgress;
+    /**
+     * Get the current transfer speed.
+     * @param now - The current time.
+     * @return The speed in bytes per second.
+     */
+    private getSpeed;
+    /**
+     * Get the progress text.
+     * @param percentage - The percentage string.
+     * @param total - The total string.
+     * @param speed - The speed string.
+     * @param eta - The ETA string.
+     * @return The progress text.
+     */
+    private getProgressText;
+    /**
+     * Get the progress bar string.
+     * @param len - The length of the bar.
+     * @return The progress bar string.
+     */
+    private getProgressBar;
+    /**
+     * Called when the transfer is done.
+     */
+    onDone(): void;
+}