@lazycatcloud/lzc-cli 1.3.17 → 2.0.0-pre.1

package/lib/app/project_sync.js

@@ -0,0 +1,499 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import chokidar from 'chokidar';
+import debounce from 'lodash.debounce';
+import ignore from 'ignore';
+import spawn from 'cross-spawn';
+import logger from 'loglevel';
+import { checkRsync, contextDirname, isDebugMode, isWindows, resolveDomain } from '../utils.js';
+import { addProjectTargetOptions, resolveProjectRuntime, getProjectDeployInfo } from './project_runtime.js';
+
+export const DEFAULT_PROJECT_SYNC_TARGET = '/lzcapp/cache/project-mirror';
+const PROJECT_SYNC_CACHE_ROOT = '/lzcapp/cache';
+const RSYNC_PASSWORD = 'fakefakefake';
+const RSYNC_PORT = '874';
+const LZCDEVIGNORE_FILE = '.lzcdevignore';
+const GITIGNORE_FILE = '.gitignore';
+const DEFAULT_LZCDEVIGNORE_RULES = [
+	'.git',
+	'.git/**',
+	'node_modules',
+	'node_modules/**',
+	'.venv',
+	'.venv/**',
+	'dist',
+	'dist/**',
+	'build',
+	'build/**',
+	'__pycache__',
+	'__pycache__/**',
+	'.idea',
+	'.idea/**',
+	'.vscode',
+	'.vscode/**',
+	'.DS_Store',
+	'.lzc-cli-*',
+	'.lzc-cli-*/**',
+	'*.lpk',
+	'*.lpk.tar',
+];
+
+function normalizePosixPath(value) {
+	return String(value ?? '')
+		.replace(/\\/g, '/')
+		.replace(/^\.\//, '')
+		.replace(/^\/+/, '')
+		.trim();
+}
+
+function loadIgnoreFile(rootDir, filename) {
+	const filePath = path.join(rootDir, filename);
+	if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+		return [];
+	}
+	return fs
+		.readFileSync(filePath, 'utf8')
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter((line) => line && !line.startsWith('#'));
+}
+
+function createIgnoreMatcher(rootDir) {
+	const ig = ignore();
+	ig.add(loadIgnoreFile(rootDir, LZCDEVIGNORE_FILE));
+	return ig;
+}
+
+function createWatchIgnored(rootDir) {
+	const ig = createIgnoreMatcher(rootDir);
+	return (candidatePath) => {
+		const relPath = normalizePosixPath(path.relative(rootDir, candidatePath));
+		if (!relPath || relPath.startsWith('..')) {
+			return false;
+		}
+		return ig.ignores(relPath);
+	};
+}
+
+function ensureLzcdevignore(rootDir) {
+	const filePath = path.join(rootDir, LZCDEVIGNORE_FILE);
+	if (fs.existsSync(filePath)) {
+		return false;
+	}
+	const mergedRules = [];
+	const seen = new Set();
+	for (const rule of [...DEFAULT_LZCDEVIGNORE_RULES, ...loadIgnoreFile(rootDir, GITIGNORE_FILE)]) {
+		const normalized = String(rule ?? '').trim();
+		if (!normalized || seen.has(normalized)) {
+			continue;
+		}
+		seen.add(normalized);
+		mergedRules.push(normalized);
+	}
+	const body = `${mergedRules.join('\n')}\n`;
+	fs.writeFileSync(filePath, body);
+	logger.warn(`Created ${LZCDEVIGNORE_FILE} from built-in defaults${fs.existsSync(path.join(rootDir, GITIGNORE_FILE)) ? ` and ${GITIGNORE_FILE}` : ''}: ${filePath}`);
+	logger.warn(`Review ${LZCDEVIGNORE_FILE} and adjust sync rules there if needed.`);
+	return true;
+}
+
+function resolveSyncCacheSubpath(targetDir) {
+	const normalized = String(targetDir || DEFAULT_PROJECT_SYNC_TARGET)
+		.replace(/\\/g, '/')
+		.replace(/\/+$/, '')
+		.trim();
+	if (!normalized) {
+		throw new Error('project sync target is empty');
+	}
+	if (normalized === PROJECT_SYNC_CACHE_ROOT) {
+		return '';
+	}
+	if (!normalized.startsWith(`${PROJECT_SYNC_CACHE_ROOT}/`)) {
+		throw new Error(`project sync target must stay under ${PROJECT_SYNC_CACHE_ROOT}`);
+	}
+	return normalizePosixPath(path.posix.relative(PROJECT_SYNC_CACHE_ROOT, normalized));
+}
+
+function resolveRsyncCommand() {
+	if (isWindows) {
+		return path.join(contextDirname(import.meta.url), '..', '..', 'template', '_lpk', 'win-rsync', 'rsync.exe');
+	}
+	return 'rsync';
+}
+
+function formatRsyncHost(host) {
+	return String(host).includes(':') ? `[${host}]` : String(host);
+}
+
+async function resolveRsyncHost(runtime) {
+	if (runtime.bridge.isBuildRemoteMode()) {
+		return runtime.bridge.buildRemote.sshHost;
+	}
+	return resolveDomain(runtime.bridge.domain);
+}
+
+async function resolveRsyncUID(runtime) {
+	return runtime.bridge.resolveCurrentUID();
+}
+
+function buildRsyncModulePath(runtime, uid, targetDir) {
+	let modulePath = runtime.pkgId;
+	if (runtime.userApp) {
+		modulePath += `/${uid}`;
+	}
+	const syncSubpath = resolveSyncCacheSubpath(targetDir);
+	if (syncSubpath) {
+		modulePath += `/${syncSubpath}`;
+	}
+	return modulePath;
+}
+
+export function buildRsyncArgs(runtime, uid, host, rootDir, targetDir, sourceDir, deleteMode, dryRun) {
+	const args = ['--recursive', '--links', '--times', '--perms', '--omit-dir-times', '--human-readable', '--itemize-changes', '--compress'];
+	if (isDebugMode()) {
+		args.push('-P');
+	}
+	if (deleteMode) {
+		args.push('--delete');
+	}
+	if (dryRun) {
+		args.push('--dry-run');
+	}
+	const ignoreFile = path.join(rootDir, LZCDEVIGNORE_FILE);
+	if (fs.existsSync(ignoreFile)) {
+		args.push(`--exclude-from=${ignoreFile}`);
+		if (deleteMode) {
+			args.push('--delete-excluded');
+		}
+	}
+	if (sourceDir) {
+		args.push('--relative');
+	}
+	const modulePath = buildRsyncModulePath(runtime, uid, targetDir);
+	const dest = `rsync://${uid}@${formatRsyncHost(host)}:${RSYNC_PORT}/lzcapp_cache/${modulePath}/`;
+	const sourceArg = sourceDir ? `./${sourceDir}/` : './';
+	args.push(sourceArg, dest);
+	return args;
+}
+
+function formatRsyncLine(line, dryRun) {
+	const text = String(line ?? '').trim();
+	if (!text) {
+		return '';
+	}
+	if (text === 'sending incremental file list') {
+		return '';
+	}
+	if (text.startsWith('sent ') || text.startsWith('total size is ')) {
+		return '';
+	}
+	if (text.startsWith('*deleting ')) {
+		const target = text.slice('*deleting '.length).trim();
+		return `${dryRun ? 'Would delete' : 'Delete'} ${target}`;
+	}
+
+	const match = text.match(/^(\S+)\s+(.+)$/);
+	if (!match) {
+		return text;
+	}
+	const [, flags, target] = match;
+	const pathText = target.trim();
+	const actionPrefix = dryRun ? 'Would ' : '';
+	if (flags.startsWith('cd')) {
+		return `${actionPrefix}create directory ${pathText}`;
+	}
+	if (flags.startsWith('<') || flags.startsWith('>') || flags.startsWith('c')) {
+		return `${actionPrefix}upload ${pathText}`;
+	}
+	if (flags.startsWith('.')) {
+		return `${actionPrefix}update ${pathText}`;
+	}
+	return `${actionPrefix}sync ${pathText}`;
+}
+
+function runRsyncProcess(command, args, cwd, dryRun) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd,
+			env: { ...process.env, RSYNC_PASSWORD },
+			shell: false,
+			stdio: ['ignore', 'pipe', 'inherit'],
+		});
+		let stdoutBuffer = '';
+		let hasChanges = false;
+		const flushLines = (force = false) => {
+			const lines = stdoutBuffer.split(/\r?\n/);
+			if (!force) {
+				stdoutBuffer = lines.pop() ?? '';
+			} else {
+				stdoutBuffer = '';
+			}
+			for (const line of lines) {
+				const formatted = formatRsyncLine(line, dryRun);
+				if (!formatted) {
+					continue;
+				}
+				hasChanges = true;
+				logger.info(formatted);
+			}
+		};
+		child.stdout?.on('data', (chunk) => {
+			stdoutBuffer += String(chunk ?? '');
+			flushLines(false);
+		});
+		child.on('error', (error) => reject(error));
+		child.on('close', (code) => {
+			flushLines(true);
+			if (code === 0) {
+				resolve(hasChanges);
+				return;
+			}
+			reject(new Error(`rsync exited with code ${code}`));
+		});
+	});
+}
+
+async function ensureProjectDeployed(runtime) {
+	const deploy = await getProjectDeployInfo(runtime);
+	if (!deploy.deployed) {
+		throw new Error('Project app is not deployed. Run "lzc-cli project deploy" first.');
+	}
+}
+
+function dirCovers(ancestor, target) {
+	if (ancestor === '') {
+		return true;
+	}
+	return target === ancestor || target.startsWith(`${ancestor}/`);
+}
+
+function compressDirs(dirs) {
+	const normalized = [...new Set(dirs.map((item) => normalizePosixPath(item)).filter((item) => item || item === ''))].sort((a, b) => {
+		if (a.length !== b.length) {
+			return a.length - b.length;
+		}
+		return a.localeCompare(b);
+	});
+	const result = [];
+	for (const dir of normalized) {
+		if (result.some((item) => dirCovers(item, dir))) {
+			continue;
+		}
+		result.push(dir);
+	}
+	return result;
+}
+
+function parentDirOf(relPath) {
+	const dir = path.posix.dirname(relPath);
+	return dir === '.' ? '' : normalizePosixPath(dir);
+}
+
+function collectWatchChange(state, eventName, relPath, deleteEnabled) {
+	if (!relPath) {
+		return;
+	}
+	if (relPath === LZCDEVIGNORE_FILE) {
+		state.fullSyncRequested = true;
+		state.reloadWatcherRequested = true;
+		return;
+	}
+	const parentDir = parentDirOf(relPath);
+	if ((eventName === 'unlink' || eventName === 'unlinkDir') && deleteEnabled) {
+		state.deleteDirs.add(parentDir);
+		return;
+	}
+	if (eventName === 'add' || eventName === 'change' || eventName === 'addDir') {
+		state.syncDirs.add(parentDir);
+	}
+}
+
+async function runSyncPath(runtime, rootDir, options, sourceDir, deleteMode) {
+	const [uid, host] = await Promise.all([resolveRsyncUID(runtime), resolveRsyncHost(runtime)]);
+	const rsyncCmd = resolveRsyncCommand();
+	const rsyncArgs = buildRsyncArgs(runtime, uid, host, rootDir, options.target, sourceDir, deleteMode, options.dryRun);
+	logger.debug('project sync rsync:', rsyncCmd, rsyncArgs.join(' '));
+	return runRsyncProcess(rsyncCmd, rsyncArgs, rootDir, options.dryRun);
+}
+
+async function runInitialSync(runtime, rootDir, options) {
+	await ensureProjectDeployed(runtime);
+	const hasChanges = await runSyncPath(runtime, rootDir, options, '', options.delete);
+	if (!hasChanges) {
+		logger.info('project sync: no changes');
+	}
+}
+
+async function runDirtySync(runtime, rootDir, options, state) {
+	await ensureProjectDeployed(runtime);
+	if (state.fullSyncRequested) {
+		state.fullSyncRequested = false;
+		const hasChanges = await runSyncPath(runtime, rootDir, options, '', options.delete);
+		if (!hasChanges) {
+			logger.info('project sync: no changes');
+		}
+		return;
+	}
+	const pendingDeleteDirs = options.delete ? compressDirs([...state.deleteDirs]) : [];
+	const pendingSyncDirs = compressDirs([...state.syncDirs]).filter((item) => !pendingDeleteDirs.some((dir) => dirCovers(dir, item)));
+	state.deleteDirs.clear();
+	state.syncDirs.clear();
+	let hasChanges = false;
+	for (const dir of pendingDeleteDirs) {
+		hasChanges = (await runSyncPath(runtime, rootDir, options, dir, true)) || hasChanges;
+	}
+	for (const dir of pendingSyncDirs) {
+		hasChanges = (await runSyncPath(runtime, rootDir, options, dir, false)) || hasChanges;
+	}
+	if (!hasChanges && pendingDeleteDirs.length === 0 && pendingSyncDirs.length === 0) {
+		logger.info('project sync: no changes');
+	}
+}
+
+function createWatchState() {
+	return {
+		syncDirs: new Set(),
+		deleteDirs: new Set(),
+		fullSyncRequested: false,
+		reloadWatcherRequested: false,
+	};
+}
+
+function hasPendingChanges(state) {
+	return state.fullSyncRequested || state.syncDirs.size > 0 || state.deleteDirs.size > 0;
+}
+
+function waitWatcherReady(watcher) {
+	return new Promise((resolve, reject) => {
+		watcher.once('ready', resolve);
+		watcher.once('error', reject);
+	});
+}
+
+function attachWatchHandlers(watcher, rootDir, options, state, trigger) {
+	watcher.on('all', (eventName, filePath) => {
+		const relPath = normalizePosixPath(path.relative(rootDir, filePath));
+		if (!relPath || relPath.startsWith('..')) {
+			return;
+		}
+		collectWatchChange(state, eventName, relPath, options.delete);
+		trigger();
+	});
+}
+
+export function projectSyncCommand() {
+	return {
+		command: 'sync',
+		desc: 'Mirror local project files into project app cache',
+		builder: (args) => {
+			addProjectTargetOptions(args);
+			args.option('watch', {
+				describe: 'Watch local files and keep mirroring changes',
+				type: 'boolean',
+				default: false,
+			});
+			args.option('delete', {
+				describe: 'Mirror target directory by deleting files removed locally',
+				type: 'boolean',
+				default: true,
+			});
+			args.option('target', {
+				describe: 'Target directory inside app cache',
+				type: 'string',
+				default: DEFAULT_PROJECT_SYNC_TARGET,
+			});
+			args.option('dry-run', {
+				describe: 'Show sync plan without changing remote files',
+				type: 'boolean',
+				default: false,
+			});
+		},
+		handler: async ({ config, dev, release, watch, delete: shouldDelete, target, dryRun }) => {
+			await checkRsync();
+			const runtime = await resolveProjectRuntime(process.cwd(), { config, dev, release, command: 'lzc-cli project sync' });
+			logger.info(`Build config: ${runtime.configPath}`);
+			const rootDir = runtime.projectCwd;
+			const options = {
+				target: String(target || DEFAULT_PROJECT_SYNC_TARGET),
+				delete: !!shouldDelete,
+				dryRun: !!dryRun,
+			};
+			const state = createWatchState();
+
+			ensureLzcdevignore(rootDir);
+			resolveSyncCacheSubpath(options.target);
+			logger.info(`Sync root: ${rootDir}`);
+			logger.info(`Sync target: ${options.target}`);
+
+			if (!watch) {
+				await runInitialSync(runtime, rootDir, options);
+				return;
+			}
+
+			let watcher = null;
+			let running = false;
+			let pending = false;
+			const triggerSync = async () => {
+				if (running) {
+					pending = true;
+					return;
+				}
+				running = true;
+				try {
+					await runDirtySync(runtime, rootDir, options, state);
+					if (state.reloadWatcherRequested) {
+						state.reloadWatcherRequested = false;
+						await watcher.close();
+						watcher = createWatcher();
+						await waitWatcherReady(watcher);
+						logger.info('project sync watch reloaded after .lzcdevignore change.');
+					}
+				} catch (error) {
+					logger.error(`project sync failed: ${error.message}`);
+				} finally {
+					running = false;
+					if (pending) {
+						pending = false;
+						await triggerSync();
+					}
+				}
+			};
+
+			const debouncedTrigger = debounce(() => {
+				void triggerSync();
+			}, 300);
+
+			const createWatcher = () => {
+				const instance = chokidar.watch(rootDir, {
+					ignoreInitial: true,
+					ignored: createWatchIgnored(rootDir),
+					awaitWriteFinish: {
+						stabilityThreshold: 150,
+						pollInterval: 50,
+					},
+				});
+				attachWatchHandlers(instance, rootDir, options, state, debouncedTrigger);
+				return instance;
+			};
+
+			watcher = createWatcher();
+			await waitWatcherReady(watcher);
+			await runInitialSync(runtime, rootDir, options);
+			if (hasPendingChanges(state)) {
+				await runDirtySync(runtime, rootDir, options, state);
+			}
+			logger.info('project sync watch started. Press Ctrl+C to stop.');
+			await new Promise((resolve) => {
+				const shutdown = async () => {
+					debouncedTrigger.cancel();
+					if (watcher) {
+						await watcher.close();
+					}
+					resolve();
+				};
+				process.once('SIGINT', shutdown);
+				process.once('SIGTERM', shutdown);
+			});
+		},
+	};
+}

package/lib/appstore/apkshell.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Blob } from 'node:buffer';
+import logger from 'loglevel';
+import fetch, { FormData } from 'node-fetch';
+import { t } from '../i18n/index.js';
+import { appStoreServerUrl } from './env.js';
+
+// axios@1.7.7 依赖的 form-data 使用了 util.isArray 导致 node 会输出弃用警告 (所以将逻辑迁移避免依赖)
+export async function triggerApk(id, name, iconPath) {
+	if (!id) {
+		logger.error(t('lzc_cli.lib.appstore.apkshell.trigger_apk_empty_appid', 'Appid 为必填项!'));
+		return;
+	}
+
+	const appName = name || t('lzc_cli.lib.appstore.apkshell.trigger_apk_default_app_name', '懒猫应用');
+	const form = new FormData();
+	form.append('app_id', id);
+	form.append('app_name', appName);
+
+	if (iconPath && fs.existsSync(iconPath)) {
+		const iconBuffer = fs.readFileSync(iconPath);
+		form.append('app_icon', new Blob([iconBuffer]), path.basename(iconPath));
+	}
+
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), 5000);
+
+	try {
+		const resp = await fetch(`${appStoreServerUrl}/api/trigger_latest_for_app`, {
+			method: 'POST',
+			body: form,
+			signal: controller.signal,
+		});
+
+		logger.debug('triggerApk resp:', resp);
+		if (resp.status == 304) {
+			logger.debug(t('lzc_cli.lib.appstore.apkshell.trigger_apk_build_tips', `APK构建任务已创建成功,如需使用安卓端,请耐心等待1分钟左右`));
+		} else if (resp.status <= 201) {
+			logger.info(t('lzc_cli.lib.appstore.apkshell.trigger_apk_build_ok_tips', `APK构建任务已创建成功,如需使用安卓端,请耐心等待1分钟左右`));
+		} else if (resp.status >= 400) {
+			logger.debug(t('lzc_cli.lib.appstore.apkshell.trigger_apk_build_failed', '请求按钮应用出错:'), await resp.text());
+			throw t('lzc_cli.lib.appstore.apkshell.trigger_apk_build_failed_tips', `请求生成应用出错! 使用 --apk=n 停止生成APK`);
+		}
+	} catch (error) {
+		logger.debug(error);
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/lib/box/index.js

@@ -1,7 +1,42 @@
 import logger from 'loglevel';
 import shellapi from '../shellapi.js';
-import { findSshPublicKey, selectSshPublicKey } from '../utils.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { findSshPublicKey, selectSshPublicKey, isMacOs, isWindows } from '../utils.js';
 import { t } from '../i18n/index.js';
+import { addSSHBox, listSSHBoxes, getDefaultSSHBox, setDefaultSSHBox, clearDefaultSSHBox, removeSSHBox } from './ssh_remote.js';
+
+function getShellAPIConfigDir() {
+	const home = os.homedir();
+	let suffix = '/.config/hportal-client';
+	if (isMacOs) {
+		suffix = '/Library/Application Support/hportal-client';
+	} else if (isWindows) {
+		suffix = '\\AppData\\Roaming\\hportal-client';
+	}
+	return path.join(home, suffix);
+}
+
+function canUseShellApi() {
+	const configDir = getShellAPIConfigDir();
+	const addrFile = path.resolve(configDir, 'shellapi_addr');
+	const credFile = path.resolve(configDir, 'shellapi_cred');
+	return fs.existsSync(addrFile) && fs.existsSync(credFile);
+}
+
+async function fetchShellBoxes() {
+	if (!canUseShellApi()) {
+		return [];
+	}
+	try {
+		await shellapi.init();
+		return await shellapi.boxList();
+	} catch (error) {
+		logger.debug('query shell boxes failed', error);
+		return [];
+	}
+}
 
 export function boxCommand(box) {
 	let subCommands = [
@@ -9,14 +44,39 @@ export function boxCommand(box) {
 			command: 'switch <boxname>',
 			desc: t('lzc_cli.lib.box.index.switch_cmd_desc', '设置默认的盒子'),
 			handler: async ({ boxname }) => {
+				const target = String(boxname ?? '').trim();
+				if (!target) {
+					throw new Error('boxname is required');
+				}
+
+				const sshBoxes = listSSHBoxes();
+				if (sshBoxes.some((item) => item.box_name === target)) {
+					setDefaultSSHBox(target);
+					logger.info(`Default box switched: ${target}`);
+					return;
+				}
+
+				if (!canUseShellApi()) {
+					throw new Error(`Box "${target}" not found in SSH boxes and shellapi is unavailable`);
+				}
 				await shellapi.init();
-				await shellapi.setDefaultBox(boxname);
+				await shellapi.setDefaultBox(target);
+				clearDefaultSSHBox();
+				logger.info(`Default box switched: ${target}`);
 			},
 		},
 		{
 			command: 'default',
 			desc: t('lzc_cli.lib.box.index.default_cmd_desc', '输出当前默认的盒子名'),
 			handler: async () => {
+				const sshDefault = getDefaultSSHBox();
+				if (sshDefault) {
+					console.log(sshDefault.box_name);
+					return;
+				}
+				if (!canUseShellApi()) {
+					throw new Error('Default box not found. Run "lzc-cli box add-by-ssh <loginUser> <address>" first.');
+				}
 				await shellapi.init();
 				console.log(shellapi.boxname);
 			},
@@ -32,8 +92,17 @@ export function boxCommand(box) {
 				});
 			},
 			handler: async ({ verbose }) => {
-				await shellapi.init();
-				const boxes = await shellapi.boxList();
+				const shellBoxes = await fetchShellBoxes();
+				const sshBoxes = listSSHBoxes();
+				const sshDefault = sshBoxes.find((item) => item.is_default_box);
+				const boxes = [
+					...shellBoxes.map((item) => ({
+						...item,
+						is_default_box: sshDefault ? false : item.is_default_box,
+						box_type: 'hclient',
+					})),
+					...sshBoxes,
+				];
 				if (boxes.length === 0) {
 					console.log(t('lzc_cli.lib.box.index.list_cmd_box_not_exist_tips', '没有找到任何盒子，赶紧添加一个吧！'));
 					return;
@@ -45,6 +114,7 @@ export function boxCommand(box) {
 
 				const list = boxes.map((b) => {
 					const info = {};
+					info[`${t('lzc_cli.lib.box.index.list_cmd_table_box_type', 'Type')}`] = b.box_type ?? 'hclient';
 					info[`${t('lzc_cli.lib.box.index.list_cmd_table_box_name', '名称')}`] = b.box_name;
 					info[`${t('lzc_cli.lib.box.index.list_cmd_table_status', '状态')}`] = b.status;
 					info[`${t('lzc_cli.lib.box.index.list_cmd_table_login_user', '登录用户')}`] = b.login_user;
@@ -59,6 +129,9 @@ export function boxCommand(box) {
 			command: 'add-public-key',
 			desc: t('lzc_cli.lib.box.index.add_public_key_cmd_desc', '添加public-key到开发者工具中'),
 			handler: async () => {
+				if (!canUseShellApi()) {
+					throw new Error('add-public-key requires shellapi connection');
+				}
 				await shellapi.init();
 				const keys = await findSshPublicKey();
 				const sshInfo = await selectSshPublicKey(keys);
@@ -75,6 +148,30 @@ export function boxCommand(box) {
 				);
 			},
 		},
+		{
+			command: 'add-by-ssh <loginUser> <address>',
+			desc: t('lzc_cli.lib.box.index.add_by_ssh_cmd_desc', '通过 ssh 配置远端直连目标'),
+			handler: async ({ loginUser, address }) => {
+				const remote = addSSHBox(loginUser, address);
+				logger.info(`SSH box added: ${remote.box_name} (${remote.ssh_target})`);
+			},
+		},
+		{
+			command: 'del <boxname>',
+			aliases: ['delete', 'rm', 'remove'],
+			desc: 'Delete ssh box config by name',
+			handler: async ({ boxname }) => {
+				const target = String(boxname ?? '').trim();
+				if (!target) {
+					throw new Error('boxname is required');
+				}
+				const removed = removeSSHBox(target);
+				if (!removed) {
+					throw new Error(`SSH box not found: ${target}`);
+				}
+				logger.info(`SSH box deleted: ${target}`);
+			},
+		},
 	];
 	box.command({
 		command: 'box',