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

package/lib/docker/index.js

@@ -2,8 +2,9 @@ import path from 'node:path';
 import logger from 'loglevel';
 import { DebugBridge } from '../debug_bridge.js';
 import shellApi from '../shellapi.js';
-import { isFileExist, isUserApp, loadFromYaml } from '../utils.js';
+import { isFileExist, loadFromYaml } from '../utils.js';
 import { t } from '../i18n/index.js';
+import { resolveBuildRemoteFromFile } from '../build_remote.js';
 
 function dockerMiddleware(argv, yargs) {
 	if (argv.$0 == 'lzc-docker' || argv.$0 == 'lzc-docker-compose') {
@@ -53,8 +54,11 @@ export function singleLzcDockerCommand(commandName = 'docker') {
 		builder: builder,
 		handler: async (args) => {
 			logger.debug('args: ', args);
-			await shellApi.init();
-			const bridge = new DebugBridge();
+			const buildRemote = resolveBuildRemoteFromFile(process.cwd());
+			if (!buildRemote) {
+				await shellApi.init();
+			}
+			const bridge = new DebugBridge(process.cwd(), buildRemote);
 			await bridge.init();
 			logger.debug('docker', args.dockerArgs);
 			await bridge.lzcDocker(args.dockerArgs);
@@ -69,7 +73,10 @@ export function singleLzcDockerComposeCommand(commandName = 'docker-compose') {
 		builder: builder,
 		handler: async (args) => {
 			logger.debug('args: ', args);
-			await shellApi.init();
+			const buildRemote = resolveBuildRemoteFromFile(process.cwd());
+			if (!buildRemote) {
+				await shellApi.init();
+			}
 			let manifest = null;
 			try {
 				for (let name of ['lzc-manifest.yml', 'manifest.yml']) {
@@ -83,13 +90,20 @@ export function singleLzcDockerComposeCommand(commandName = 'docker-compose') {
 				logger.debug('load manifest: ', e);
 			}
 			const pkgId = manifest ? manifest['package'] : '';
-			const userApp = manifest ? isUserApp(manifest) : false;
 
-			const bridge = new DebugBridge();
+			const bridge = new DebugBridge(process.cwd(), buildRemote);
 			await bridge.init();
 			const options = args.dockerArgs;
-			if (pkgId != '' && !options.some((o) => o == '--project-directory')) {
-				options.unshift('--project-directory', `/lzcapp/run/lzc-docker/compose/${pkgId}${userApp ? '/' + shellapi.uid : ''}`);
+			if (
+				pkgId != '' &&
+				!options.some((o) => o == '--project-directory') &&
+				!options.some((o) => o == '-p') &&
+				!options.some((o) => o == '--project-name') &&
+				!options.some((o) => o == '-f') &&
+				!options.some((o) => o == '--file')
+			) {
+				const projectName = pkgId.replaceAll('.', '');
+				options.unshift('-p', projectName);
 			}
 			logger.debug('docker-compose', options.join(' '));
 			await bridge.lzcDockerCompose(options);
@@ -98,6 +112,12 @@ export function singleLzcDockerComposeCommand(commandName = 'docker-compose') {
 }
 
 export function lzcDockerCommand(program) {
-	program.command(singleLzcDockerCommand());
-	program.command(singleLzcDockerComposeCommand());
+	program.command({
+		...singleLzcDockerCommand(),
+		desc: false,
+	});
+	program.command({
+		...singleLzcDockerComposeCommand(),
+		desc: false,
+	});
 }

package/lib/i18n/index.js

@@ -15,6 +15,7 @@ const __dirname = dirname(__filename)
 
 i18next.use(backend).init({
   debug: false,
+  showSupportNotice: false,
   initAsync: false,
   fallbackLng: "zh",
   ns: ["translation"],

package/lib/i18n/locales/en/translation.json

@@ -55,14 +55,26 @@
 				"lpk_create": {
 					"ask_lpk_info_message": "Please enter the app ID, for example app-demo1",
 					"ask_lpk_info_validate_fail": "A combination of lowercase letters or numbers or - is allowed, but does not start with a number, and cannot start or end with -, nor can there be consecutive dashes --",
-					"choose_template_message": "Select project build template",
+						"choose_template_message": "Select project build template",
+						"template_option_hello_vue": "hello-vue (Vue starter)",
+						"template_option_todolist_java": "todolist-java (Java Todo demo)",
+						"template_option_todolist_python": "todolist-python (Python Todo demo)",
+						"template_option_todolist_golang": "todolist-golang (Golang Todo demo)",
+						"template_option_gui_vnc": "gui-vnc (GUI VNC embed demo)",
+						"template_option_todolist_serverless": "todolist-serverless (Serverless Todo demo)",
 					"exec_init_project_name_exist_tips": "! The same directory has been detected and the old directory has been automatically renamed to {{renamedFileName}}",
 					"exec_init_project_success_tips": "✨ Initialize Lazycat Cloud application",
 					"exec_init_project_tips": "✨ Initialize project {{name}}"
 				},
 				"lpk_create_generator": {
-					"app_create_success_tip": "✨ Lazycat Microservice application has been created successfully!\n✨ After completing the following steps, you can enter container development\n   cd {{name}}\n   lzc-cli project devshell",
-					"template_config_vue3_green": "⚙️ After entering the application container, execute the following command:\n   npm install\n   npm rundev\n🚀 Launch the application:\n   Enter the LCMD client launcher page and click the application icon to test the application.",
+						"app_create_success_tip": "✨ Lazycat Microservice application has been created successfully!\n✨ Finish the first deployment first and verify access from mobile/PC\n   cd {{name}}\n   npm install\n   lzc-cli project deploy\n   lzc-cli project info",
+						"app_create_success_tip_common": "✨ Lazycat Microservice application has been created successfully!\n✨ Finish the first deployment first and verify access from mobile/PC\n   cd {{name}}{{installBlock}}\n   lzc-cli project deploy\n   lzc-cli project info",
+						"template_config_python_green": "🛠 Flask app starts in container runtime:\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec /bin/sh",
+						"template_config_springboot_green": "🛠 Spring Boot app starts inside image build/runtime:\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec /bin/sh",
+						"template_config_golang_green": "🛠 Golang app starts in container runtime:\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec /bin/sh",
+						"template_config_gui_vnc_green": "🛠 GUI VNC app (embedded image template):\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec -s desktop /bin/sh",
+						"template_config_vue_minidb_green": "🛠 This template includes @lazycatcloud/minidb:\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec /bin/sh",
+					"template_config_vue3_green": "🛠 After editing source code, redeploy to verify changes:\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec /bin/sh",
 					"write_file_tree_create_file": "Create file {{filePath}}"
 				},
 				"lpk_devshell": {
@@ -87,7 +99,7 @@
 					"install_from_file_done_tips": "👉 Please visit https://{{subdomain}}.{{boxname}}.heiyu.space in your browser",
 					"install_from_file_fail_tips": "Installation failed: {{error}}",
 					"install_from_file_gen_apk_error": "Failed to generate APK:",
-					"install_from_file_gen_apk_error_tips": "Failed to generate APK, use lzc-cli project devshell --apk n to ignore the error",
+					"install_from_file_gen_apk_error_tips": "Failed to generate APK, you can run lzc-cli app install --apk n to ignore this error",
 					"install_from_file_gen_apk_tips": "Whether to generate APK:",
 					"install_from_file_login_tips": "👉 And log in using your Microservice username and password",
 					"install_from_file_lpk_path_fail": "install must specify a pkg path",
@@ -249,4 +261,4 @@
 			}
 		}
 	}
-}
+}

package/lib/i18n/locales/zh/translation.json

@@ -55,14 +55,26 @@
 				"lpk_create": {
 					"ask_lpk_info_message": "请输入应用ID，例如 app-demo1",
 					"ask_lpk_info_validate_fail": "允许小写字母或数字或-的组合，但不以数字开头，且不能以 - 开头或结束，也不能有连续的短横线 --",
-					"choose_template_message": "选择项目构建模板",
+						"choose_template_message": "选择项目构建模板",
+						"template_option_hello_vue": "hello-vue (Vue基础模板)",
+						"template_option_todolist_java": "todolist-java (Java Todo示例)",
+						"template_option_todolist_python": "todolist-python (Python Todo示例)",
+						"template_option_todolist_golang": "todolist-golang (Golang Todo示例)",
+						"template_option_gui_vnc": "gui-vnc (GUI VNC Embed示例)",
+						"template_option_todolist_serverless": "todolist-serverless (Serverless Todo示例)",
 					"exec_init_project_name_exist_tips": "! 检测到相同目录,已自动将旧目录重命名为 {{ renamedFileName }}",
 					"exec_init_project_success_tips": "✨ 初始化懒猫云应用",
 					"exec_init_project_tips": "✨ 初始化项目 {{ name }}"
 				},
 				"lpk_create_generator": {
-					"app_create_success_tip": "\n✨ 懒猫微服应用已创建成功 !\n✨ 进行下面步骤后即可进入容器开发\n   cd {{ name }}\n   lzc-cli project devshell\n   ",
-					"template_config_vue3_green": "\n⚙️  进入应用容器后执行下面命令:\n   npm install\n   npm run dev\n🚀 启动应用:\n   进入微服客户端启动器页面点击应用图标来测试应用\n   ",
+						"app_create_success_tip": "\n✨ 懒猫微服应用已创建成功 !\n✨ 先完成第一次部署，确认手机/PC都可以访问\n   cd {{ name }}\n   npm install\n   lzc-cli project deploy\n   lzc-cli project info\n   ",
+						"app_create_success_tip_common": "\n✨ 懒猫微服应用已创建成功 !\n✨ 先完成第一次部署，确认手机/PC都可以访问\n   cd {{ name }}{{ installBlock }}\n   lzc-cli project deploy\n   lzc-cli project info\n   ",
+						"template_config_python_green": "\n🛠 Flask app starts in container runtime:\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec /bin/sh\n   ",
+						"template_config_springboot_green": "\n🛠 Spring Boot app starts inside image build/runtime:\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec /bin/sh\n   ",
+						"template_config_golang_green": "\n🛠 Golang app starts in container runtime:\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec /bin/sh\n   ",
+						"template_config_gui_vnc_green": "\n🛠 GUI VNC app (embedded image template):\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec -s desktop /bin/sh\n   ",
+						"template_config_vue_minidb_green": "\n🛠 This template includes @lazycatcloud/minidb:\n   lzc-cli project deploy\n🔎 For troubleshooting:\n   lzc-cli project log -f\n   lzc-cli project exec /bin/sh\n   ",
+					"template_config_vue3_green": "\n🛠 修改源码后，重新执行部署即可查看效果:\n   lzc-cli project deploy\n🔎 如果要排查问题:\n   lzc-cli project log -f\n   lzc-cli project exec /bin/sh\n   ",
 					"write_file_tree_create_file": "创建文件 {{ filePath }}"
 				},
 				"lpk_devshell": {
@@ -87,7 +99,7 @@
 					"install_from_file_done_tips": "👉 请在浏览器中访问 https://{{ subdomain }}.{{ boxname }}.heiyu.space",
 					"install_from_file_fail_tips": "安装失败: {{ error }}",
 					"install_from_file_gen_apk_error": "生成 APK 失败: ",
-					"install_from_file_gen_apk_error_tips": "生成 APK 失败，使用 lzc-cli project devshell --apk n 忽略该错误",
+					"install_from_file_gen_apk_error_tips": "生成 APK 失败，可使用 lzc-cli app install --apk n 忽略该错误",
 					"install_from_file_gen_apk_tips": "是否生成APK:",
 					"install_from_file_login_tips": "👉 并使用微服的用户名和密码登录",
 					"install_from_file_lpk_path_fail": "install 必须指定一个 pkg 路径",

package/lib/lpk/core.js

@@ -0,0 +1,487 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import archiver from 'archiver';
+import AdmZip from 'adm-zip';
+import * as tar from 'tar';
+import yaml from 'js-yaml';
+import logger from 'loglevel';
+import shellApi from '../shellapi.js';
+import { DebugBridge } from '../debug_bridge.js';
+import { resolveBuildRemoteFromFile } from '../build_remote.js';
+
+function toPosixPath(filePath) {
+	return filePath.split(path.sep).join('/');
+}
+
+export function formatBytes(bytes) {
+	const value = Number(bytes ?? 0);
+	if (!Number.isFinite(value) || value <= 0) {
+		return '0 B';
+	}
+	const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+	let size = value;
+	let unitIndex = 0;
+	while (size >= 1024 && unitIndex < units.length - 1) {
+		size /= 1024;
+		unitIndex += 1;
+	}
+	const digits = unitIndex === 0 ? 0 : 2;
+	return `${size.toFixed(digits)} ${units[unitIndex]}`;
+}
+
+function normalizeDigest(raw) {
+	const value = String(raw ?? '').trim().toLowerCase();
+	if (!value.startsWith('sha256:')) {
+		return '';
+	}
+	const hexPart = value.slice('sha256:'.length);
+	if (!/^[0-9a-f]{64}$/.test(hexPart)) {
+		return '';
+	}
+	return `sha256:${hexPart}`;
+}
+
+function digestToBlobPath(blobsDir, digest) {
+	const normalized = normalizeDigest(digest);
+	if (!normalized) {
+		throw new Error(`Invalid digest: ${digest}`);
+	}
+	return path.join(blobsDir, normalized.slice('sha256:'.length));
+}
+
+function detectPackageFormat(pkgPath) {
+	const ext = path.basename(pkgPath).toLowerCase();
+	if (ext.endsWith('.lpk.tar') || ext.endsWith('.tar')) {
+		return 'tar';
+	}
+	const fd = fs.openSync(pkgPath, 'r');
+	try {
+		const header = Buffer.alloc(4);
+		fs.readSync(fd, header, 0, 4, 0);
+		if (header[0] === 0x50 && header[1] === 0x4b) {
+			return 'zip';
+		}
+	} finally {
+		fs.closeSync(fd);
+	}
+	return 'tar';
+}
+
+async function extractPackage(pkgPath, format, destDir) {
+	if (format === 'zip') {
+		const zip = new AdmZip(pkgPath);
+		zip.extractAllTo(destDir, true);
+		return;
+	}
+	await tar.x({
+		file: pkgPath,
+		cwd: destDir,
+	});
+}
+
+async function packAsZip(srcDir, outPath) {
+	return new Promise((resolve, reject) => {
+		const output = fs.createWriteStream(outPath);
+		const archive = archiver('zip');
+		archive.on('error', reject);
+		output.on('error', reject);
+		output.on('close', resolve);
+		archive.pipe(output);
+		archive.directory(srcDir, false);
+		archive.finalize();
+	});
+}
+
+async function packAsTar(srcDir, outPath) {
+	const entries = fs.readdirSync(srcDir).sort();
+	await tar.c(
+		{
+			cwd: srcDir,
+			file: outPath,
+			portable: true,
+		},
+		entries,
+	);
+}
+
+async function packPackage(srcDir, format, outPath) {
+	if (format === 'zip') {
+		return packAsZip(srcDir, outPath);
+	}
+	return packAsTar(srcDir, outPath);
+}
+
+function walkFilesRecursive(dir, baseDir = dir) {
+	const result = [];
+	if (!fs.existsSync(dir)) {
+		return result;
+	}
+	for (const entry of fs.readdirSync(dir)) {
+		const absPath = path.join(dir, entry);
+		const stat = fs.statSync(absPath);
+		if (stat.isDirectory()) {
+			result.push(...walkFilesRecursive(absPath, baseDir));
+			continue;
+		}
+		if (stat.isFile()) {
+			result.push(toPosixPath(path.relative(baseDir, absPath)));
+		}
+	}
+	return result;
+}
+
+async function sha256File(filePath) {
+	return new Promise((resolve, reject) => {
+		const hash = crypto.createHash('sha256');
+		let size = 0;
+		const stream = fs.createReadStream(filePath);
+		stream.on('data', (chunk) => {
+			size += chunk.length;
+			hash.update(chunk);
+		});
+		stream.on('error', reject);
+		stream.on('end', () => {
+			resolve({
+				digest: hash.digest('hex'),
+				size,
+			});
+		});
+	});
+}
+
+function readYamlFile(filePath) {
+	if (!fs.existsSync(filePath)) {
+		return {};
+	}
+	return yaml.load(fs.readFileSync(filePath, 'utf-8')) ?? {};
+}
+
+function isSignedPackage(workDir) {
+	const releaseLock = path.join(workDir, 'META', 'release.lock');
+	const sigDir = path.join(workDir, 'META', 'signatures');
+	if (fs.existsSync(releaseLock)) {
+		return true;
+	}
+	if (!fs.existsSync(sigDir) || !fs.statSync(sigDir).isDirectory()) {
+		return false;
+	}
+	return fs.readdirSync(sigDir).some((name) => name.endsWith('.sig'));
+}
+
+function buildAliasInfo(lock, blobsDir) {
+	const lockImages = lock?.images ?? {};
+	const aliases = Object.keys(lockImages).sort();
+
+	const allEmbeddedDigests = new Set();
+	const aliasDetails = [];
+	for (const alias of aliases) {
+		const imageInfo = lockImages[alias] ?? {};
+		const layers = Array.isArray(imageInfo.layers) ? imageInfo.layers : [];
+
+		let embedLayerCount = 0;
+		let upstreamLayerCount = 0;
+		let embedSize = 0;
+		let missingEmbedLayerCount = 0;
+		const uniqueEmbedDigests = new Set();
+
+		for (const layer of layers) {
+			const digest = normalizeDigest(layer?.digest ?? '');
+			if (!digest) {
+				continue;
+			}
+			const source = String(layer?.source ?? '').trim().toLowerCase();
+			if (source === 'embed') {
+				embedLayerCount += 1;
+				uniqueEmbedDigests.add(digest);
+				allEmbeddedDigests.add(digest);
+				const blobPath = digestToBlobPath(blobsDir, digest);
+				if (fs.existsSync(blobPath)) {
+					embedSize += fs.statSync(blobPath).size;
+				} else {
+					missingEmbedLayerCount += 1;
+				}
+			} else {
+				upstreamLayerCount += 1;
+			}
+		}
+
+		aliasDetails.push({
+			alias,
+			imageID: String(imageInfo.image_id ?? ''),
+			upstream: String(imageInfo.upstream ?? ''),
+			embedLayerCount,
+			upstreamLayerCount,
+			embedSize,
+			uniqueEmbedLayerCount: uniqueEmbedDigests.size,
+			missingEmbedLayerCount,
+		});
+	}
+
+	let totalEmbeddedSize = 0;
+	let totalMissingEmbeddedLayerCount = 0;
+	for (const digest of allEmbeddedDigests) {
+		const blobPath = digestToBlobPath(blobsDir, digest);
+		if (fs.existsSync(blobPath)) {
+			totalEmbeddedSize += fs.statSync(blobPath).size;
+		} else {
+			totalMissingEmbeddedLayerCount += 1;
+		}
+	}
+
+	return {
+		aliases,
+		aliasDetails,
+		totalEmbeddedLayerCount: allEmbeddedDigests.size,
+		totalEmbeddedSize,
+		totalMissingEmbeddedLayerCount,
+	};
+}
+
+export async function inspectLpkPackage(pkgPath) {
+	const resolvedPkgPath = path.resolve(pkgPath);
+	if (!fs.existsSync(resolvedPkgPath)) {
+		throw new Error(`Package not found: ${resolvedPkgPath}`);
+	}
+
+	const format = detectPackageFormat(resolvedPkgPath);
+	const pkgStat = fs.statSync(resolvedPkgPath);
+	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lzc-cli-lpk-info-'));
+	const workDir = path.join(tempDir, 'work');
+	fs.mkdirSync(workDir, { recursive: true });
+	try {
+		await extractPackage(resolvedPkgPath, format, workDir);
+
+		const manifest = readYamlFile(path.join(workDir, 'manifest.yml'));
+		const imagesDir = path.join(workDir, 'images');
+		const imagesLockPath = path.join(workDir, 'images.lock');
+		const hasImagesDir = fs.existsSync(imagesDir) && fs.statSync(imagesDir).isDirectory();
+		const hasImagesLock = fs.existsSync(imagesLockPath);
+		const lpkVersion = hasImagesDir ? 'v2' : 'v1';
+
+		let imageInfo = {
+			aliases: [],
+			aliasDetails: [],
+			totalEmbeddedLayerCount: 0,
+			totalEmbeddedSize: 0,
+			totalMissingEmbeddedLayerCount: 0,
+		};
+		if (hasImagesLock) {
+			const lock = readYamlFile(imagesLockPath);
+			const blobsDir = path.join(imagesDir, 'blobs', 'sha256');
+			imageInfo = buildAliasInfo(lock, blobsDir);
+		}
+
+		return {
+			path: resolvedPkgPath,
+			size: pkgStat.size,
+			format,
+			lpkVersion,
+			signed: isSignedPackage(workDir),
+			packageID: String(manifest?.package ?? ''),
+			appVersion: String(manifest?.version ?? ''),
+			hasImagesDir,
+			hasImagesLock,
+			imageInfo,
+		};
+	} finally {
+		fs.rmSync(tempDir, { recursive: true, force: true });
+	}
+}
+
+async function ensureBridge(baseDir) {
+	const buildRemote = resolveBuildRemoteFromFile(baseDir);
+	if (!buildRemote) {
+		await shellApi.init();
+	}
+	const bridge = new DebugBridge(baseDir, buildRemote);
+	await bridge.init();
+	return bridge;
+}
+
+async function fillMissingDigestsFromUpstream(bridge, upstreamImage, digestSet, blobsDir, tempRoot) {
+	if (!upstreamImage) {
+		throw new Error('Upstream image is required for filling missing blobs');
+	}
+	const pending = new Set([...digestSet].filter((digest) => !fs.existsSync(digestToBlobPath(blobsDir, digest))));
+	if (pending.size === 0) {
+		return { addedCount: 0, addedBytes: 0 };
+	}
+
+	await bridge.lzcDockerPull(upstreamImage);
+	const archivePath = path.join(tempRoot, `upstream-${Date.now()}-${Math.random().toString(16).slice(2)}.tar`);
+	await bridge.lzcDockerSave([upstreamImage], archivePath);
+
+	let addedCount = 0;
+	let addedBytes = 0;
+	const extractDir = fs.mkdtempSync(path.join(tempRoot, 'upstream-extract-'));
+	try {
+		await tar.x({
+			file: archivePath,
+			cwd: extractDir,
+		});
+
+		for (const digest of [...pending]) {
+			const hex = digest.slice('sha256:'.length);
+			const blobSourcePath = path.join(extractDir, 'blobs', 'sha256', hex);
+			if (!fs.existsSync(blobSourcePath)) {
+				continue;
+			}
+			const blobTargetPath = path.join(blobsDir, hex);
+			fs.mkdirSync(path.dirname(blobTargetPath), { recursive: true });
+			if (!fs.existsSync(blobTargetPath)) {
+				fs.copyFileSync(blobSourcePath, blobTargetPath);
+				addedCount += 1;
+				addedBytes += fs.statSync(blobTargetPath).size;
+			}
+			pending.delete(digest);
+		}
+
+		if (pending.size > 0) {
+			const files = walkFilesRecursive(extractDir).filter((relPath) => relPath.endsWith('.tar')).sort();
+			for (const relPath of files) {
+				if (pending.size === 0) {
+					break;
+				}
+				const absPath = path.join(extractDir, relPath);
+				const { digest } = await sha256File(absPath);
+				const fullDigest = `sha256:${digest}`;
+				if (!pending.has(fullDigest)) {
+					continue;
+				}
+				const blobTargetPath = path.join(blobsDir, digest);
+				fs.mkdirSync(path.dirname(blobTargetPath), { recursive: true });
+				if (!fs.existsSync(blobTargetPath)) {
+					fs.copyFileSync(absPath, blobTargetPath);
+					addedCount += 1;
+					addedBytes += fs.statSync(blobTargetPath).size;
+				}
+				pending.delete(fullDigest);
+			}
+		}
+
+		if (pending.size > 0) {
+			throw new Error(`Missing upstream layer blobs after sync: ${[...pending].sort().join(', ')}`);
+		}
+	} finally {
+		fs.rmSync(archivePath, { force: true });
+		fs.rmSync(extractDir, { recursive: true, force: true });
+	}
+
+	return { addedCount, addedBytes };
+}
+
+export async function embedLpkPackage(pkgPath, options = {}) {
+	const resolvedPkgPath = path.resolve(pkgPath);
+	if (!fs.existsSync(resolvedPkgPath)) {
+		throw new Error(`Package not found: ${resolvedPkgPath}`);
+	}
+
+	const format = detectPackageFormat(resolvedPkgPath);
+	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lzc-cli-lpk-embed-'));
+	const workDir = path.join(tempDir, 'work');
+	const outTemp = path.join(tempDir, format === 'zip' ? 'embedded.lpk' : 'embedded.lpk.tar');
+	fs.mkdirSync(workDir, { recursive: true });
+
+	try {
+		await extractPackage(resolvedPkgPath, format, workDir);
+		const imagesDir = path.join(workDir, 'images');
+		const imagesLockPath = path.join(workDir, 'images.lock');
+		if (!fs.existsSync(imagesDir) || !fs.statSync(imagesDir).isDirectory() || !fs.existsSync(imagesLockPath)) {
+			throw new Error('This package does not contain images.lock/images directory, only lpk v2 is supported');
+		}
+
+		const lock = readYamlFile(imagesLockPath);
+		const lockImages = lock?.images;
+		if (!lockImages || typeof lockImages !== 'object') {
+			throw new Error('Invalid images.lock: images field is missing');
+		}
+		const allAliases = Object.keys(lockImages).sort();
+		if (allAliases.length === 0) {
+			throw new Error('Invalid images.lock: images is empty');
+		}
+
+		const inputAliases = Array.isArray(options.images)
+			? options.images
+					.map((item) => String(item ?? '').trim())
+					.filter((item) => item !== '')
+			: [];
+		const targetAliases = inputAliases.length > 0 ? [...new Set(inputAliases)] : allAliases;
+		for (const alias of targetAliases) {
+			if (!Object.prototype.hasOwnProperty.call(lockImages, alias)) {
+				throw new Error(`Image alias not found in images.lock: ${alias}`);
+			}
+		}
+
+		const blobsDir = path.join(imagesDir, 'blobs', 'sha256');
+		fs.mkdirSync(blobsDir, { recursive: true });
+
+		const missingByUpstream = new Map();
+		let changedLayerCount = 0;
+		for (const alias of targetAliases) {
+			const image = lockImages[alias];
+			const upstream = String(image?.upstream ?? '').trim();
+			const layers = Array.isArray(image?.layers) ? image.layers : [];
+
+			let hasUpstreamLayer = false;
+			for (const layer of layers) {
+				const digest = normalizeDigest(layer?.digest ?? '');
+				if (!digest) {
+					continue;
+				}
+				const source = String(layer?.source ?? '').trim().toLowerCase();
+				if (source === 'embed') {
+					continue;
+				}
+				hasUpstreamLayer = true;
+				changedLayerCount += 1;
+				layer.source = 'embed';
+
+				const blobPath = digestToBlobPath(blobsDir, digest);
+				if (!fs.existsSync(blobPath)) {
+					if (!upstream) {
+						throw new Error(`Alias "${alias}" layer ${digest} requires upstream blob, but upstream is empty`);
+					}
+					if (!missingByUpstream.has(upstream)) {
+						missingByUpstream.set(upstream, new Set());
+					}
+					missingByUpstream.get(upstream).add(digest);
+				}
+			}
+
+			if (hasUpstreamLayer) {
+				image.upstream = '';
+			}
+		}
+
+		let addedBlobCount = 0;
+		let addedBlobBytes = 0;
+		if (missingByUpstream.size > 0) {
+			const bridge = await ensureBridge(process.cwd());
+			for (const [upstream, digestSet] of missingByUpstream.entries()) {
+				logger.info(`Sync upstream blobs from: ${upstream}`);
+				const result = await fillMissingDigestsFromUpstream(bridge, upstream, digestSet, blobsDir, tempDir);
+				addedBlobCount += result.addedCount;
+				addedBlobBytes += result.addedBytes;
+			}
+		}
+
+		fs.writeFileSync(imagesLockPath, yaml.dump(lock, { lineWidth: -1 }));
+		await packPackage(workDir, format, outTemp);
+
+		const finalPath = options.output ? path.resolve(options.output) : resolvedPkgPath;
+		fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+		fs.copyFileSync(outTemp, finalPath);
+
+		return {
+			outputPath: finalPath,
+			targetAliases,
+			changedLayerCount,
+			addedBlobCount,
+			addedBlobBytes,
+		};
+	} finally {
+		fs.rmSync(tempDir, { recursive: true, force: true });
+	}
+}