@lazycatcloud/lzc-cli 2.0.0-pre.0 → 2.0.0-pre.2

package/lib/app/project_runtime.js

@@ -7,12 +7,52 @@ import { isUserApp } from '../utils.js';
 import { resolveBuildRemoteFromFile, DEFAULT_BUILD_CONFIG_FILE } from '../build_remote.js';
 
 export const DEFAULT_DEPLOY_BUILD_CONFIG_FILE = 'lzc-build.dev.yml';
-export const DEFAULT_RELEASE_BUILD_CONFIG_FILE = 'lzc-build.release.yml';
+export const DEFAULT_RELEASE_BUILD_CONFIG_FILE = DEFAULT_BUILD_CONFIG_FILE;
 
 function isFile(pathname) {
 	return fs.existsSync(pathname) && fs.statSync(pathname).isFile();
 }
 
+function normalizeProjectTargetSelection(selection = '') {
+	if (typeof selection === 'string') {
+		return {
+			config: String(selection ?? '').trim(),
+			dev: false,
+			release: false,
+		};
+	}
+	if (!selection || typeof selection !== 'object') {
+		return {
+			config: '',
+			dev: false,
+			release: false,
+		};
+	}
+	return {
+		config: String(selection.config ?? '').trim(),
+		dev: !!selection.dev,
+		release: !!selection.release,
+	};
+}
+
+export function addProjectTargetOptions(args) {
+	args.option('c', {
+		alias: 'config',
+		describe: 'Build config file name',
+		type: 'string',
+	});
+	args.option('dev', {
+		describe: `Use ${DEFAULT_DEPLOY_BUILD_CONFIG_FILE}`,
+		type: 'boolean',
+		default: false,
+	});
+	args.option('release', {
+		describe: `Use ${DEFAULT_RELEASE_BUILD_CONFIG_FILE}`,
+		type: 'boolean',
+		default: false,
+	});
+}
+
 export function resolveBuildConfigPath(startDir = process.cwd(), buildConfigFile = DEFAULT_BUILD_CONFIG_FILE) {
 	const configName = String(buildConfigFile ?? DEFAULT_BUILD_CONFIG_FILE).trim() || DEFAULT_BUILD_CONFIG_FILE;
 	if (path.isAbsolute(configName)) {
@@ -43,16 +83,62 @@ export function resolveBuildConfigPath(startDir = process.cwd(), buildConfigFile
 	return '';
 }
 
-export function resolveProjectDeployConfigPath(startDir = process.cwd(), buildConfigFile = '') {
-	return resolvePreferredBuildConfigPath(startDir, buildConfigFile, DEFAULT_DEPLOY_BUILD_CONFIG_FILE);
+function resolveExplicitBuildConfigPath(startDir, selection) {
+	const normalized = normalizeProjectTargetSelection(selection);
+	if (normalized.dev && normalized.release) {
+		throw new Error('Cannot use --dev and --release together.');
+	}
+	if (normalized.config && (normalized.dev || normalized.release)) {
+		throw new Error('Cannot combine --config with --dev or --release.');
+	}
+	if (normalized.config) {
+		const explicitPath = resolveBuildConfigPath(startDir, normalized.config);
+		if (!explicitPath) {
+			throw new Error(`Build config file not found: ${normalized.config}`);
+		}
+		return explicitPath;
+	}
+	if (normalized.dev) {
+		const devPath = resolveBuildConfigPath(startDir, DEFAULT_DEPLOY_BUILD_CONFIG_FILE);
+		if (!devPath) {
+			throw new Error(`Build config file not found: ${DEFAULT_DEPLOY_BUILD_CONFIG_FILE}`);
+		}
+		return devPath;
+	}
+	if (normalized.release) {
+		const releasePath = resolveBuildConfigPath(startDir, DEFAULT_RELEASE_BUILD_CONFIG_FILE);
+		if (!releasePath) {
+			throw new Error(`Build config file not found: ${DEFAULT_RELEASE_BUILD_CONFIG_FILE}`);
+		}
+		return releasePath;
+	}
+	return '';
 }
 
-export function resolveProjectReleaseConfigPath(startDir = process.cwd(), buildConfigFile = '') {
-	return resolvePreferredBuildConfigPath(startDir, buildConfigFile, DEFAULT_RELEASE_BUILD_CONFIG_FILE);
+export function resolveProjectDeployConfigPath(startDir = process.cwd(), selection = '') {
+	const explicitPath = resolveExplicitBuildConfigPath(startDir, selection);
+	if (explicitPath) {
+		return explicitPath;
+	}
+
+	const preferredConfigPath = resolveBuildConfigPath(startDir, DEFAULT_DEPLOY_BUILD_CONFIG_FILE);
+	if (preferredConfigPath) {
+		return preferredConfigPath;
+	}
+
+	const defaultConfigPath = resolveBuildConfigPath(startDir, DEFAULT_RELEASE_BUILD_CONFIG_FILE);
+	if (!defaultConfigPath) {
+		throw new Error(`Build config file not found: ${DEFAULT_DEPLOY_BUILD_CONFIG_FILE} or ${DEFAULT_RELEASE_BUILD_CONFIG_FILE}`);
+	}
+	return defaultConfigPath;
 }
 
-function resolvePreferredBuildConfigPath(startDir, buildConfigFile, preferredConfigFile) {
-	const explicitConfig = String(buildConfigFile ?? '').trim();
+export function resolveProjectReleaseConfigPath(startDir = process.cwd(), selection = '') {
+	const normalized = normalizeProjectTargetSelection(selection);
+	if (normalized.dev) {
+		throw new Error('Release command does not support --dev. Use --release or omit the flag.');
+	}
+	const explicitConfig = normalized.config;
 	if (explicitConfig) {
 		const explicitPath = resolveBuildConfigPath(startDir, explicitConfig);
 		if (!explicitPath) {
@@ -61,23 +147,32 @@ function resolvePreferredBuildConfigPath(startDir, buildConfigFile, preferredCon
 		return explicitPath;
 	}
 
-	const preferredConfigPath = resolveBuildConfigPath(startDir, preferredConfigFile);
-	if (preferredConfigPath) {
-		return preferredConfigPath;
-	}
-
-	const defaultConfigPath = resolveBuildConfigPath(startDir, DEFAULT_BUILD_CONFIG_FILE);
+	const defaultConfigPath = resolveBuildConfigPath(startDir, DEFAULT_RELEASE_BUILD_CONFIG_FILE);
 	if (!defaultConfigPath) {
-		throw new Error(`Build config file not found: ${preferredConfigFile} or ${DEFAULT_BUILD_CONFIG_FILE}`);
+		throw new Error(`Build config file not found: ${DEFAULT_RELEASE_BUILD_CONFIG_FILE}`);
 	}
 	return defaultConfigPath;
 }
 
-export async function resolveProjectRuntime(startDir = process.cwd(), buildConfigFile = DEFAULT_BUILD_CONFIG_FILE) {
-	const configPath = resolveBuildConfigPath(startDir, buildConfigFile);
-	if (!configPath) {
-		throw new Error(`Build config file not found: ${buildConfigFile}`);
+export function resolveProjectCommandConfigPath(startDir = process.cwd(), selection = '') {
+	const explicitPath = resolveExplicitBuildConfigPath(startDir, selection);
+	if (explicitPath) {
+		return explicitPath;
+	}
+
+	const devPath = resolveBuildConfigPath(startDir, DEFAULT_DEPLOY_BUILD_CONFIG_FILE);
+	if (devPath) {
+		return devPath;
+	}
+	const releasePath = resolveBuildConfigPath(startDir, DEFAULT_RELEASE_BUILD_CONFIG_FILE);
+	if (releasePath) {
+		return releasePath;
 	}
+	throw new Error(`Build config file not found: ${DEFAULT_DEPLOY_BUILD_CONFIG_FILE} or ${DEFAULT_RELEASE_BUILD_CONFIG_FILE}`);
+}
+
+export async function resolveProjectRuntime(startDir = process.cwd(), selection = '') {
+	const configPath = resolveProjectCommandConfigPath(startDir, selection);
 
 	const projectCwd = path.dirname(configPath);
 	const configName = path.basename(configPath);

package/lib/app/project_start.js

@@ -1,7 +1,6 @@
 import logger from 'loglevel';
-import { DEFAULT_BUILD_CONFIG_FILE } from '../build_remote.js';
 import { LpkBuild } from './lpk_build.js';
-import { resolveProjectRuntime, getProjectDeployInfo, getProjectComposePs } from './project_runtime.js';
+import { addProjectTargetOptions, resolveProjectRuntime, getProjectDeployInfo, getProjectComposePs } from './project_runtime.js';
 
 function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
@@ -32,7 +31,7 @@ async function waitProjectNotRunning(runtime, timeoutMs = 30000) {
 }
 
 async function deployCurrentVersion(runtime) {
-	const lpkBuild = await new LpkBuild(runtime.projectCwd, runtime.configName).init();
+	const lpkBuild = await new LpkBuild(runtime.projectCwd, runtime.configName, { forceV2: true }).init();
 	lpkBuild.onBeforeBuildPackage(async (options) => {
 		delete options['devshell'];
 		return options;
@@ -47,20 +46,16 @@ export function projectStartCommand() {
 		command: 'start',
 		desc: 'Start project app',
 		builder: (args) => {
-			args.option('c', {
-				alias: 'config',
-				describe: 'Build config file name',
-				type: 'string',
-				default: DEFAULT_BUILD_CONFIG_FILE,
-			});
+			addProjectTargetOptions(args);
 			args.option('restart', {
 				describe: 'Force restart app instance',
 				type: 'boolean',
 				default: false,
 			});
 		},
-		handler: async ({ config, restart }) => {
-			const runtime = await resolveProjectRuntime(process.cwd(), config);
+		handler: async ({ config, dev, release, restart }) => {
+			const runtime = await resolveProjectRuntime(process.cwd(), { config, dev, release, command: 'lzc-cli project start' });
+			logger.info(`Build config: ${runtime.configPath}`);
 			let deploy = await getProjectDeployInfo(runtime);
 
 			if (!deploy.currentVersionDeployed) {

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);
+			});
+		},
+	};
+}