@jalsoedesign/filezilla-cli 1.0.0

package/dist/index.js

@@ -0,0 +1,119 @@
+import { getDefaultSiteManager, getSiteManager } from '@jalsoedesign/filezilla-core';
+import { listCommand } from './commands/list.js';
+import { getCommand } from './commands/get.js';
+import { runCheckCommand } from './commands/check.js';
+export { checkConnection } from './commands/check.js';
+import * as process from 'process';
+function showHelp() {
+    console.log(`
+Usage: filezilla-js <command> [options] [args]
+
+Commands:
+  list                      List all servers
+  get <path> [property]    Get a server or a specific property value
+  check <path>              Check a connection without remote mutations (check --help)
+
+Options:
+  --file <path>             Specify the sitemanager.xml file path
+  --json                    Output in JSON format
+  --table                   Output in table format
+  --search <term>           Search for a server by name or path
+  --recurse                 Return results in a nested structure (requires --json)
+  --full                    Return full server properties when using list command
+  --show-password           Show the actual password in output (otherwise hidden)
+  --color                   Force color output (on by default on Windows TTY)
+  --no-color                Disable color output
+  --help, -h                Show this help message
+
+Examples:
+  filezilla-js list
+  filezilla-js list --json
+  filezilla-js list --table
+  filezilla-js get "My Server"
+  filezilla-js get "My Server" host
+  filezilla-js get "My Server" --json
+`);
+}
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = {};
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--json') {
+            options.json = true;
+        }
+        else if (arg === '--table') {
+            options.table = true;
+        }
+        else if (arg === '--full') {
+            options.full = true;
+        }
+        else if (arg === '--recurse') {
+            options.recurse = true;
+        }
+        else if (arg === '--show-password') {
+            options.showPassword = true;
+        }
+        else if (arg === '--file' && i + 1 < args.length) {
+            options.file = args[++i];
+        }
+        else if (arg === '--search' && i + 1 < args.length) {
+            options.search = args[++i];
+        }
+        else if (arg === '--help' || arg === '-h') {
+            options.help = true;
+        }
+        else if (arg.startsWith('--')) {
+            // ignore unknown flags
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { options, positional };
+}
+export async function run() {
+    if (process.argv[2] === 'check') {
+        await runCheckCommand(process.argv.slice(3));
+        return;
+    }
+    const { options, positional } = parseArgs();
+    if (options.help || positional.length === 0) {
+        showHelp();
+        return;
+    }
+    const command = positional[0];
+    const commandArgs = positional.slice(1);
+    const commands = {
+        list: listCommand,
+        get: getCommand,
+    };
+    const handler = commands[command];
+    if (!handler) {
+        console.error(`Error: Unknown command "${command}"`);
+        showHelp();
+        process.exit(1);
+    }
+    try {
+        const siteManager = options.file ?
+            getSiteManager(options.file) :
+            getDefaultSiteManager();
+        const context = {
+            siteManager,
+            args: commandArgs,
+            options,
+        };
+        await handler(context);
+    }
+    catch (e) {
+        if (options.json) {
+            console.error(JSON.stringify({ error: e.message }));
+        }
+        else {
+            console.error(`Error: ${e.message}`);
+        }
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+import { SiteManager } from '@jalsoedesign/filezilla-core';
+export interface CommandContext {
+    siteManager: SiteManager;
+    args: string[];
+    options: {
+        json?: boolean;
+        table?: boolean;
+        file?: string;
+        help?: boolean;
+        search?: string;
+        recurse?: boolean;
+        full?: boolean;
+        showPassword?: boolean;
+    };
+}
+export type CommandHandler = (ctx: CommandContext) => Promise<void> | void;
+export declare function formatOutput(data: string | number | boolean | any[] | Record<string, any>, options: CommandContext['options'], tableData?: {
+    columns: string[];
+    rows: (string | number | boolean | undefined)[][];
+}): void;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,8BAA8B,CAAC;AAGzD,MAAM,WAAW,cAAc;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE;QACL,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,YAAY,CAAC,EAAE,OAAO,CAAC;KAC1B,CAAC;CACL;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE3E,wBAAgB,YAAY,CACxB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7D,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,EAClC,SAAS,CAAC,EAAE;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,EAAE,EAAE,CAAA;CAAC,QAuDrF"}

package/dist/types.js

@@ -0,0 +1,48 @@
+import chalk from 'chalk';
+export function formatOutput(data, options, tableData) {
+    if (options.json) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    else if (options.table && tableData) {
+        const colWidths = tableData.columns.map((col, i) => Math.max(col.length, ...tableData.rows.map(row => String(row[i] ?? '').length)));
+        const borderChars = {
+            top: { start: '┌', mid: '┬', end: '┐' },
+            middle: { start: '├', mid: '┼', end: '┤' },
+            bottom: { start: '└', mid: '┴', end: '┘' },
+            side: { start: '│', mid: '│', end: '│' },
+        };
+        const colored = Object.fromEntries(Object.entries(borderChars).map(([type, chars]) => [
+            type,
+            Object.fromEntries(Object.entries(chars).map(([k, v]) => [k, chalk.cyan(v)])),
+        ]));
+        const buildBorder = (widths, type) => {
+            const c = colored[type];
+            return c.start + widths.map(w => chalk.cyan('─'.repeat(w + 2))).join(c.mid) + c.end;
+        };
+        const side = colored.side.mid;
+        const buildRow = (cells, widths) => side + ' ' + cells.map((cell, i) => String(cell ?? '').padEnd(widths[i])).join(' ' + side + ' ') + ' ' + side;
+        console.log(buildBorder(colWidths, 'top'));
+        console.log(side + ' ' + tableData.columns.map((col, i) => chalk.bold.white(col.padEnd(colWidths[i]))).join(' ' + side + ' ') + ' ' + side);
+        console.log(buildBorder(colWidths, 'middle'));
+        tableData.rows.forEach(row => console.log(buildRow(row, colWidths)));
+        console.log(buildBorder(colWidths, 'bottom'));
+    }
+    else {
+        if (typeof data === 'string' || typeof data === 'number' || typeof data === 'boolean') {
+            console.log(data);
+        }
+        else if (Array.isArray(data)) {
+            data.forEach(item => console.log(chalk.green('• ') + item));
+        }
+        else {
+            Object.entries(data).forEach(([key, value]) => {
+                let displayValue = String(value);
+                if (key === 'password' && !options.showPassword && value) {
+                    displayValue = chalk.gray('(hidden)');
+                }
+                console.log(`${chalk.yellow(key.padEnd(26))}: ${displayValue}`);
+            });
+        }
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/examples/transfer-recipes.ts

@@ -0,0 +1,184 @@
+import {createReadStream} from 'node:fs';
+import {open, stat, unlink} from 'node:fs/promises';
+import {Transform} from 'node:stream';
+import {pipeline} from 'node:stream/promises';
+import type {Server} from '@jalsoedesign/filezilla-core';
+import {SftpConnectorFactory, type SftpConnector} from '@jalsoedesign/filezilla-connector-sftp';
+import {
+    checkAbort,
+    IntegrityError,
+    NotSupportedError,
+    publishFile,
+    ResourceLimitError,
+    toReadable,
+    type ConnectorOperationOptions,
+    type PublicationResult,
+    type TransferConnector,
+} from '@jalsoedesign/filezilla-connector-abstract';
+
+export interface RecipeConnector extends TransferConnector {
+    connect(options?: ConnectorOperationOptions): Promise<void>;
+    disconnect(): Promise<void>;
+}
+
+/** The caller supplies an independently verified public fingerprint and owns saved credentials. */
+export function createPinnedSftp(server: Server, fingerprint: string): SftpConnector {
+    if (!/^SHA256:[A-Za-z0-9+/]{43}$/.test(fingerprint)) {
+        throw new TypeError('Provide a canonical, independently verified SHA256 host-key fingerprint.');
+    }
+
+    return SftpConnectorFactory.fromServer(server, {
+        requireTrustPolicy: true,
+        hasTrustPolicy: challenge => challenge.fingerprint === fingerprint,
+        acceptTrustPolicy: () => false,
+        autoReconnect: false,
+        maxTransientRetries: 0,
+    });
+}
+
+/** The callback must await complete stream consumption before returning. */
+export async function withConnectedSite<T>(
+    createConnector: () => RecipeConnector,
+    options: ConnectorOperationOptions,
+    operation: (connector: RecipeConnector) => Promise<T>,
+): Promise<T> {
+    checkAbort(options.abortSignal);
+
+    const connector = createConnector();
+    let operationFailed = false;
+    let operationError: unknown;
+    let value: T | undefined;
+
+    try {
+        await connector.connect(options);
+
+        value = await operation(connector);
+    } catch (error) {
+        operationFailed = true;
+        operationError = error;
+    }
+
+    try {
+        await connector.disconnect();
+    } catch (cleanupError) {
+        if (operationFailed) {
+            throw new AggregateError([operationError, cleanupError],
+                'The operation and connection cleanup both failed.', {cause: cleanupError});
+        }
+
+        throw cleanupError;
+    }
+
+    if (operationFailed) {
+        throw operationError;
+    }
+
+    return value as T;
+}
+
+export interface DownloadRecipeOptions extends ConnectorOperationOptions {
+    maxBytes?: number;
+}
+
+/** Creates a new local file exclusively. Failure removes only the file this invocation created. */
+export async function downloadToNewFile(
+    createConnector: () => RecipeConnector,
+    remotePath: string,
+    localPath: string,
+    options: DownloadRecipeOptions = {},
+): Promise<{bytesWritten: number}> {
+    const maxBytes = options.maxBytes ?? 1073741824;
+
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+        throw new RangeError('maxBytes must be a non-negative safe integer.');
+    }
+
+    let owned = false;
+
+    try {
+        return await withConnectedSite(createConnector, options, async connector => {
+            const metadata = await connector.stat(remotePath, options);
+
+            if (metadata.type !== 'file') {
+                throw new NotSupportedError('This recipe downloads regular files only.');
+            }
+
+            if (metadata.size !== undefined && metadata.size > maxBytes) {
+                throw new ResourceLimitError('The download exceeds maxBytes.');
+            }
+
+            const file = await open(localPath, 'wx', 0o600);
+            let bytesWritten = 0;
+
+            owned = true;
+
+            try {
+                const source = toReadable(await connector.read(remotePath, options));
+                const counter = new Transform({
+                    transform(chunk: Buffer, _encoding, callback) {
+                        bytesWritten += chunk.length;
+                        callback(bytesWritten > maxBytes ? new ResourceLimitError('The download exceeds maxBytes.') :
+                            null, chunk);
+                    },
+                });
+
+                await pipeline(source, counter, file.createWriteStream({autoClose: true}), {
+                    signal: options.abortSignal,
+                });
+                checkAbort(options.abortSignal);
+
+                if (metadata.size !== undefined && metadata.size !== bytesWritten) {
+                    throw new IntegrityError('The remote file changed length or the download ended early.');
+                }
+            } finally {
+                await file.close();
+            }
+
+            return {bytesWritten};
+        });
+    } catch (error) {
+        if (owned) {
+            try {
+                await unlink(localPath);
+            } catch (cleanupError) {
+                throw new AggregateError([error, cleanupError],
+                    'The download and local-file cleanup both failed.', {cause: cleanupError});
+            }
+        }
+
+        throw error;
+    }
+}
+
+export interface PublishRecipeOptions extends ConnectorOperationOptions {
+    /** Explicit integrity value supplied by the application, never guessed by the recipe. */
+    expectedSha256?: string;
+    /** Fail unless the selected connector/server can honor this rename guarantee. */
+    requireAtomicRename?: boolean;
+}
+
+/** Publishes to a new remote name with overwrite:'fail'; deployment replacement policy stays with the application. */
+export async function publishNewFile(
+    createConnector: () => RecipeConnector,
+    localPath: string,
+    remotePath: string,
+    options: PublishRecipeOptions = {},
+): Promise<PublicationResult> {
+    checkAbort(options.abortSignal);
+
+    const metadata = await stat(localPath);
+
+    if (!metadata.isFile()) {
+        throw new NotSupportedError('This recipe publishes regular files only.');
+    }
+
+    return withConnectedSite(createConnector, options, connector => publishFile(connector, remotePath,
+        () => createReadStream(localPath), {
+            ...options,
+            overwrite: 'fail',
+            totalBytes: metadata.size,
+            ...(options.expectedSha256 === undefined ? {} : {
+                verify: {algorithm: 'sha256', expectedDigest: options.expectedSha256, maxBytes: metadata.size},
+            }),
+        }));
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "@jalsoedesign/filezilla-cli",
+    "version": "1.0.0",
+    "type": "module",
+    "description": "Command-line interface for querying FileZilla sitemanager.xml files",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "bin": {
+        "filezilla-js": "dist/cli.js"
+    },
+    "scripts": {
+        "build": "node ../../scripts/build-package.mjs",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "dev": "tsc --watch",
+        "lint": "eslint src tests --no-error-on-unmatched-pattern --max-warnings 0",
+        "prepack": "npm run build"
+    },
+    "dependencies": {
+        "@jalsoedesign/filezilla-core": "^1.0.0",
+        "chalk": "6.0.0",
+        "@jalsoedesign/filezilla-connector-abstract": "^1.0.0",
+        "@jalsoedesign/filezilla-connector-ftp": "^1.0.0",
+        "@jalsoedesign/filezilla-connector-sftp": "^1.0.0"
+    },
+    "devDependencies": {
+        "vitest": "5.0.0",
+        "typescript": "6.0.3",
+        "tsx": "4.23.13"
+    },
+    "license": "MIT",
+    "engines": {
+        "node": ">=22.22.2"
+    },
+    "files": [
+        "dist",
+        "LICENSE",
+        "examples"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json",
+        "./dist/*": "./dist/*"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/h2ooooooo/filezilla-js.git",
+        "directory": "packages/cli"
+    },
+    "homepage": "https://h2ooooooo.github.io/filezilla-js/",
+    "bugs": {
+        "url": "https://github.com/h2ooooooo/filezilla-js/issues"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}