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

package/lib/app/lpk_build_images.js

@@ -0,0 +1,728 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import logger from 'loglevel';
+import * as tar from 'tar';
+import yaml from 'js-yaml';
+import { DebugBridge } from '../debug_bridge.js';
+import shellApi from '../shellapi.js';
+import { collectContextFromDockerFile } from './lpk_devshell_docker.js';
+import { isFileExist } from '../utils.js';
+import { resolveBuildRemoteFromOptions } from '../build_remote.js';
+
+const EMBED_PREFIX = 'embed:';
+const EMBED_TYPO_PREFIXES = ['emebd:'];
+const SHA256_PREFIX = 'sha256:';
+const DEFAULT_UPSTREAM_MATCH = 'registry.lazycat.cloud';
+const IMAGE_BUILD_CACHE_VERSION = 3;
+const IMAGE_PACKAGE_CACHE_VERSION = 1;
+
+function isPlainObject(value) {
+	return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function sanitizeTagPart(value, fallback) {
+	const normalized = String(value ?? '').trim().toLowerCase();
+	if (!normalized) {
+		return fallback;
+	}
+	return normalized.replace(/[^a-z0-9._-]/g, '-');
+}
+
+function normalizeSha256Digest(digest, fieldName) {
+	const value = String(digest ?? '').trim();
+	if (!value.startsWith(SHA256_PREFIX)) {
+		throw new Error(`${fieldName} is not a sha256 digest: ${value}`);
+	}
+	const hex = value.slice(SHA256_PREFIX.length);
+	if (!/^[0-9a-f]{64}$/i.test(hex)) {
+		throw new Error(`${fieldName} has invalid sha256 hex: ${value}`);
+	}
+	return `${SHA256_PREFIX}${hex.toLowerCase()}`;
+}
+
+function normalizeDigestList(value, fieldName) {
+	if (!Array.isArray(value)) {
+		throw new Error(`${fieldName} must be a digest array`);
+	}
+	return value.map((item, index) => normalizeSha256Digest(item, `${fieldName}[${index}]`));
+}
+
+function normalizeImageBuildEntries(rawConfig, cwd, manifest) {
+	if (!isPlainObject(rawConfig)) {
+		throw new Error('images config must be an object');
+	}
+
+	const packageName = sanitizeTagPart(manifest?.package, 'local-app');
+	const version = sanitizeTagPart(manifest?.version, 'latest');
+	const entries = [];
+
+	for (const [alias, configValue] of Object.entries(rawConfig)) {
+		if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(alias)) {
+			throw new Error(`Invalid image alias "${alias}", only [a-zA-Z0-9._-] is allowed`);
+		}
+
+		let config = configValue;
+		if (typeof configValue === 'string') {
+			config = { dockerfile: configValue };
+		}
+		if (!isPlainObject(config)) {
+			throw new Error(`images.${alias} must be an object`);
+		}
+		if (Object.prototype.hasOwnProperty.call(config, 'upstream_match')) {
+			throw new Error(`images.${alias}.upstream_match is invalid, use images.${alias}.upstream-match`);
+		}
+		if (Object.prototype.hasOwnProperty.call(config, 'dockerfile_content')) {
+			throw new Error(`images.${alias}.dockerfile_content is invalid, use images.${alias}.dockerfile-content`);
+		}
+
+		const dockerfileValue = String(config.dockerfile ?? '').trim();
+		const hasDockerfileContentField = Object.prototype.hasOwnProperty.call(config, 'dockerfile-content');
+		const dockerfileContentValue = hasDockerfileContentField ? String(config['dockerfile-content'] ?? '') : '';
+		const dockerfileContent = dockerfileContentValue.trim() === '' ? '' : dockerfileContentValue;
+		if (!dockerfileValue && !dockerfileContent) {
+			throw new Error(`images.${alias}.dockerfile or images.${alias}.dockerfile-content is required`);
+		}
+		if (dockerfileValue && dockerfileContent) {
+			throw new Error(`images.${alias}.dockerfile and images.${alias}.dockerfile-content cannot be used together`);
+		}
+
+		const contextValue = String(config.context ?? '').trim();
+		let dockerfilePath = '';
+		let contextDir = '';
+		let dockerfileInlineContent = '';
+		if (dockerfileValue) {
+			dockerfilePath = path.isAbsolute(dockerfileValue) ? dockerfileValue : path.resolve(cwd, dockerfileValue);
+			if (!isFileExist(dockerfilePath)) {
+				throw new Error(`dockerfile does not exist for alias "${alias}": ${dockerfilePath}`);
+			}
+			contextDir = contextValue ? (path.isAbsolute(contextValue) ? contextValue : path.resolve(cwd, contextValue)) : path.dirname(dockerfilePath);
+		} else {
+			dockerfileInlineContent = dockerfileContent;
+			contextDir = contextValue ? (path.isAbsolute(contextValue) ? contextValue : path.resolve(cwd, contextValue)) : path.resolve(cwd);
+		}
+
+		if (!fs.existsSync(contextDir) || !fs.statSync(contextDir).isDirectory()) {
+			throw new Error(`context directory is invalid for alias "${alias}": ${contextDir}`);
+		}
+
+		if (dockerfilePath) {
+			const relativeDockerfile = path.relative(contextDir, dockerfilePath);
+			if (!relativeDockerfile || relativeDockerfile.startsWith('..') || path.isAbsolute(relativeDockerfile)) {
+				throw new Error(`dockerfile for alias "${alias}" must be inside context`);
+			}
+		}
+
+		const upstreamMatchValue = config['upstream-match'];
+		let upstreamMatch = DEFAULT_UPSTREAM_MATCH;
+		if (upstreamMatchValue !== undefined && upstreamMatchValue !== null) {
+			upstreamMatch = String(upstreamMatchValue).trim();
+			if (!upstreamMatch) {
+				throw new Error(`images.${alias}.upstream-match must not be empty`);
+			}
+		}
+
+		entries.push({
+			alias,
+			contextDir,
+			dockerfilePath,
+			dockerfileInlineContent,
+			imageLabel: `${packageName}-image-${sanitizeTagPart(alias, 'image')}:${version}`,
+			upstreamMatch,
+		});
+	}
+
+	return entries;
+}
+
+function startsWithDigestList(layers, prefix) {
+	if (prefix.length > layers.length) {
+		return false;
+	}
+	for (let index = 0; index < prefix.length; index += 1) {
+		if (layers[index] !== prefix[index]) {
+			return false;
+		}
+	}
+	return true;
+}
+
+function formatDurationMs(ms) {
+	return `${Number(ms || 0).toFixed(0)}ms`;
+}
+
+function parseEmbeddedAliasFromRef(rawValue) {
+	const trimmed = String(rawValue ?? '').trim();
+	if (!trimmed.startsWith(EMBED_PREFIX)) {
+		return '';
+	}
+	const rest = trimmed.slice(EMBED_PREFIX.length).trim();
+	if (!rest) {
+		throw new Error(`Invalid image reference "${trimmed}", alias is required after "${EMBED_PREFIX}"`);
+	}
+	const at = rest.indexOf('@');
+	const alias = (at >= 0 ? rest.slice(0, at) : rest).trim();
+	if (!alias) {
+		throw new Error(`Invalid image reference "${trimmed}", alias is required after "${EMBED_PREFIX}"`);
+	}
+	if (at >= 0) {
+		const digest = rest.slice(at + 1).trim();
+		if (!digest) {
+			throw new Error(`Invalid image reference "${trimmed}", digest is required after "@"`);
+		}
+	}
+	return alias;
+}
+
+function collectManifestEmbedAliases(manifest) {
+	const aliases = new Set();
+	const walk = (value) => {
+		if (typeof value === 'string') {
+			const trimmed = value.trim();
+			const lowered = trimmed.toLowerCase();
+			for (const typoPrefix of EMBED_TYPO_PREFIXES) {
+				if (lowered.startsWith(typoPrefix)) {
+					throw new Error(`Invalid image reference prefix "${trimmed}", please use "${EMBED_PREFIX}<alias>"`);
+				}
+			}
+			const alias = parseEmbeddedAliasFromRef(trimmed);
+			if (alias) {
+				aliases.add(alias);
+			}
+			return;
+		}
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				walk(item);
+			}
+			return;
+		}
+		if (isPlainObject(value)) {
+			for (const item of Object.values(value)) {
+				walk(item);
+			}
+		}
+	};
+	walk(manifest);
+	return [...aliases];
+}
+
+function extractRepoFromRepoDigest(repoDigest) {
+	const value = String(repoDigest ?? '').trim();
+	const index = value.indexOf('@sha256:');
+	if (index < 0) {
+		return '';
+	}
+	return value.slice(0, index);
+}
+
+function imageBuildCacheFilePath(cwd) {
+	const pathID = crypto.createHash('sha256').update(path.resolve(cwd)).digest('hex');
+	return path.join(os.tmpdir(), 'lzc-cli-image-build', pathID, 'cache.json');
+}
+
+function loadImageBuildCache(cwd) {
+	const cachePath = imageBuildCacheFilePath(cwd);
+	if (!isFileExist(cachePath)) {
+		return {
+			cachePath,
+			records: {},
+		};
+	}
+	try {
+		const raw = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+		if (raw?.version !== IMAGE_BUILD_CACHE_VERSION || !isPlainObject(raw?.records)) {
+			return {
+				cachePath,
+				records: {},
+			};
+		}
+		return {
+			cachePath,
+			records: raw.records,
+		};
+	} catch (error) {
+		logger.debug(`ignore broken image build cache: ${error.message}`);
+		return {
+			cachePath,
+			records: {},
+		};
+	}
+}
+
+function saveImageBuildCache(cachePath, records) {
+	const cacheDir = path.dirname(cachePath);
+	fs.mkdirSync(cacheDir, { recursive: true });
+	fs.writeFileSync(
+		cachePath,
+		JSON.stringify(
+			{
+				version: IMAGE_BUILD_CACHE_VERSION,
+				records,
+			},
+			null,
+			2,
+		),
+	);
+}
+
+function imagePackageCacheRootDir(cwd) {
+	const pathID = crypto.createHash('sha256').update(path.resolve(cwd)).digest('hex');
+	return path.join(os.tmpdir(), 'lzc-cli-image-build', pathID, 'package-cache');
+}
+
+function normalizeMetaForPackageCache(metaList) {
+	return [...metaList]
+		.map((meta) => ({
+			alias: String(meta?.alias ?? ''),
+			imageID: String(meta?.imageID ?? ''),
+			upstream: String(meta?.upstream ?? ''),
+			embeddedDiffIDs: [...(meta?.embeddedDiffIDs ?? [])].map((item) => String(item ?? '')),
+		}))
+		.sort((a, b) => a.alias.localeCompare(b.alias));
+}
+
+function computePackageCacheKey(metaList) {
+	const normalized = normalizeMetaForPackageCache(metaList);
+	return crypto
+		.createHash('sha256')
+		.update(
+			JSON.stringify({
+				version: IMAGE_PACKAGE_CACHE_VERSION,
+				images: normalized,
+			}),
+		)
+		.digest('hex');
+}
+
+function tryLoadPackageCache(cwd, cacheKey, targetTempDir) {
+	if (!cacheKey) {
+		return null;
+	}
+	const cacheRoot = imagePackageCacheRootDir(cwd);
+	const cacheDir = path.join(cacheRoot, cacheKey);
+	const cachedImagesDir = path.join(cacheDir, 'images');
+	const cachedLockPath = path.join(cacheDir, 'images.lock');
+	const cachedMetaPath = path.join(cacheDir, 'meta.json');
+
+	if (!isFileExist(cachedLockPath) || !isFileExist(cachedMetaPath) || !fs.existsSync(cachedImagesDir) || !fs.statSync(cachedImagesDir).isDirectory()) {
+		return null;
+	}
+
+	try {
+		const meta = JSON.parse(fs.readFileSync(cachedMetaPath, 'utf-8'));
+		const targetImagesDir = path.join(targetTempDir, 'images');
+		fs.mkdirSync(targetImagesDir, { recursive: true });
+		fs.cpSync(cachedImagesDir, targetImagesDir, { recursive: true });
+		fs.copyFileSync(cachedLockPath, path.join(targetTempDir, 'images.lock'));
+		return {
+			embeddedLayerBytes: Number(meta?.embeddedLayerBytes ?? 0),
+			embeddedLayerCount: Number(meta?.embeddedLayerCount ?? 0),
+		};
+	} catch (error) {
+		logger.debug(`ignore broken package cache: ${error.message}`);
+		return null;
+	}
+}
+
+function savePackageCache(cwd, cacheKey, sourceTempDir, convertResult) {
+	if (!cacheKey) {
+		return;
+	}
+	const cacheRoot = imagePackageCacheRootDir(cwd);
+	const cacheDir = path.join(cacheRoot, cacheKey);
+	const cacheDirTmp = `${cacheDir}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+	try {
+		fs.mkdirSync(cacheDirTmp, { recursive: true });
+		fs.cpSync(path.join(sourceTempDir, 'images'), path.join(cacheDirTmp, 'images'), { recursive: true });
+		fs.copyFileSync(path.join(sourceTempDir, 'images.lock'), path.join(cacheDirTmp, 'images.lock'));
+		fs.writeFileSync(
+			path.join(cacheDirTmp, 'meta.json'),
+			JSON.stringify(
+				{
+					version: IMAGE_PACKAGE_CACHE_VERSION,
+					embeddedLayerBytes: Number(convertResult?.embeddedLayerBytes ?? 0),
+					embeddedLayerCount: Number(convertResult?.embeddedLayerCount ?? 0),
+				},
+				null,
+				2,
+			),
+		);
+		fs.mkdirSync(cacheRoot, { recursive: true });
+		fs.rmSync(cacheDir, { recursive: true, force: true });
+		fs.renameSync(cacheDirTmp, cacheDir);
+	} catch (error) {
+		logger.debug(`skip save package cache: ${error.message}`);
+		fs.rmSync(cacheDirTmp, { recursive: true, force: true });
+	}
+}
+
+function compactLockLayers(rawLayers) {
+	if (!Array.isArray(rawLayers)) {
+		return [];
+	}
+	const layers = [];
+	for (const item of rawLayers) {
+		const digest = String(item?.digest ?? '').trim();
+		if (!digest) {
+			continue;
+		}
+		const source = String(item?.source ?? '').trim().toLowerCase();
+		layers.push({
+			digest,
+			source,
+		});
+	}
+	return layers;
+}
+
+function compactLockImages(rawImages) {
+	if (!isPlainObject(rawImages)) {
+		return {};
+	}
+	const compacted = {};
+	for (const [alias, imageInfo] of Object.entries(rawImages)) {
+		if (!isPlainObject(imageInfo)) {
+			continue;
+		}
+			const imageID = String(imageInfo.image_id ?? '').trim();
+		const upstream = String(imageInfo.upstream ?? '').trim();
+		const layers = compactLockLayers(imageInfo.layers);
+		compacted[alias] = {
+			image_id: imageID,
+			upstream,
+			layers,
+		};
+	}
+	return compacted;
+}
+
+function rewriteImagesLock(tempDir, fallbackLockImages = {}) {
+	const lockPath = path.join(tempDir, 'images.lock');
+	let sourceImages = {};
+	if (isFileExist(lockPath)) {
+		try {
+			const existingLock = yaml.load(fs.readFileSync(lockPath, 'utf-8'));
+			sourceImages = existingLock?.images;
+		} catch (error) {
+			logger.debug(`ignore broken images.lock before compact: ${error.message}`);
+		}
+	}
+	if (!isPlainObject(sourceImages) || Object.keys(sourceImages).length === 0) {
+		sourceImages = fallbackLockImages;
+	}
+	const lock = {
+		version: 1,
+		images: compactLockImages(sourceImages),
+	};
+	fs.writeFileSync(lockPath, yaml.dump(lock, { lineWidth: -1 }));
+	return lock.images;
+}
+
+function ensureDockerfileForEntry(entry) {
+	if (!entry?.dockerfileInlineContent) {
+		return {
+			dockerfilePath: entry.dockerfilePath,
+			cleanup: () => {},
+		};
+	}
+
+	const dockerfilePath = path.join(entry.contextDir, 'Dockerfile');
+	const backupPath = `${dockerfilePath}.lzc-inline-backup-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+	const hasOriginalDockerfile = fs.existsSync(dockerfilePath);
+	if (hasOriginalDockerfile) {
+		fs.copyFileSync(dockerfilePath, backupPath);
+	}
+	fs.writeFileSync(dockerfilePath, entry.dockerfileInlineContent);
+	return {
+		dockerfilePath,
+		cleanup: () => {
+			if (hasOriginalDockerfile && fs.existsSync(backupPath)) {
+				fs.copyFileSync(backupPath, dockerfilePath);
+				fs.rmSync(backupPath, { force: true });
+				return;
+			}
+			fs.rmSync(dockerfilePath, { force: true });
+		},
+	};
+}
+
+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,
+			});
+		});
+	});
+}
+
+export async function buildConfiguredImagesToTempDir(rawConfig, manifest, cwd, tempDir, options = {}) {
+	const imageEntries = normalizeImageBuildEntries(rawConfig, cwd, manifest);
+	if (imageEntries.length === 0) {
+		return {
+			imageCount: 0,
+		};
+	}
+
+	const manifestAliases = collectManifestEmbedAliases(manifest);
+	for (const alias of manifestAliases) {
+		const exists = imageEntries.some((item) => item.alias === alias);
+		if (!exists) {
+			throw new Error(`Found alias "${alias}" in manifest but it is missing in lzc-build.yml images`);
+		}
+	}
+
+	const buildRemote = resolveBuildRemoteFromOptions(options, 'lzc-build.yml');
+	if (!buildRemote) {
+		await shellApi.init();
+	}
+	const bridge = new DebugBridge(cwd, buildRemote);
+	await bridge.init();
+
+	const imageMetaByRef = new Map();
+	const imageRefs = [];
+	const buildCache = loadImageBuildCache(cwd);
+	const buildCacheRecords = { ...buildCache.records };
+
+	for (const entry of imageEntries) {
+		const profileStartAt = Date.now();
+		let contextCollectMs = 0;
+		let buildStageMs = 0;
+		let resolveStageMs = 0;
+		let buildMode = 'build-pack';
+
+		const dockerfileDesc = entry.dockerfilePath || '(inline dockerfile-content)';
+		logger.info(`Build image for alias "${entry.alias}" from ${dockerfileDesc}`);
+		const contextStartAt = Date.now();
+		const dockerfileSource = ensureDockerfileForEntry(entry);
+		let contextTar = '';
+		try {
+			contextTar = await collectContextFromDockerFile(entry.contextDir, dockerfileSource.dockerfilePath);
+		} finally {
+			dockerfileSource.cleanup();
+		}
+		contextCollectMs = Date.now() - contextStartAt;
+		const contextHash = await sha256File(contextTar);
+		const contextDigest = `${SHA256_PREFIX}${contextHash.digest}`;
+
+		const cacheRecord = buildCache.records?.[entry.alias];
+		let builtImageRef = '';
+		let reusedFromCache = false;
+		let imageID = '';
+		let builtDiffIDs = [];
+		let upstream = '';
+		let upstreamDiffIDs = [];
+		let archiveKey = '';
+
+		if (
+			cacheRecord &&
+			cacheRecord.image_label === entry.imageLabel &&
+			cacheRecord.context_digest === contextDigest &&
+			cacheRecord.upstream_match === entry.upstreamMatch &&
+			cacheRecord.build_mode === 'pack' &&
+			Array.isArray(cacheRecord.built_diff_ids) &&
+			typeof cacheRecord.image_id === 'string' &&
+			cacheRecord.image_id.trim() !== ''
+		) {
+			try {
+				imageID = normalizeSha256Digest(cacheRecord.image_id, `cached image id of alias ${entry.alias}`);
+				builtDiffIDs = normalizeDigestList(cacheRecord.built_diff_ids, `cached built diff ids of alias ${entry.alias}`);
+				if (builtDiffIDs.length === 0) {
+					throw new Error('built diff ids is empty');
+				}
+				upstream = cacheRecord.upstream ? String(cacheRecord.upstream).trim() : '';
+				if (upstream && !upstream.includes('@sha256:')) {
+					throw new Error(`invalid cached upstream: ${upstream}`);
+				}
+				upstreamDiffIDs = Array.isArray(cacheRecord.upstream_diff_ids)
+					? normalizeDigestList(cacheRecord.upstream_diff_ids, `cached upstream diff ids of alias ${entry.alias}`)
+					: [];
+				archiveKey = String(cacheRecord.archive_key ?? '').trim();
+				builtImageRef = typeof cacheRecord.image_ref === 'string' && cacheRecord.image_ref.trim() !== '' ? cacheRecord.image_ref : `debug.bridge/${entry.imageLabel}`;
+				reusedFromCache = true;
+				buildMode = 'build-pack-cache';
+				logger.info(`Reuse cached build-pack metadata for alias "${entry.alias}"`);
+			} catch (error) {
+				logger.info(`Cached build-pack metadata is invalid for alias "${entry.alias}", rebuild image`);
+			}
+		}
+
+		const buildStartAt = Date.now();
+		if (!reusedFromCache) {
+			const buildPackResult = await bridge.buildImageForPack(entry.imageLabel, contextTar);
+			builtImageRef = String(buildPackResult?.tag ?? '').trim() || `debug.bridge/${entry.imageLabel}`;
+			buildMode = 'build-pack';
+			archiveKey = String(buildPackResult?.archiveKey ?? '').trim();
+			imageID = normalizeSha256Digest(buildPackResult?.imageID, `build-pack image id of alias ${entry.alias}`);
+			builtDiffIDs = normalizeDigestList(buildPackResult?.diffIDs ?? [], `build-pack diff ids of alias ${entry.alias}`);
+			if (builtDiffIDs.length === 0) {
+				throw new Error(`No rootfs layer found in build-pack output for alias "${entry.alias}"`);
+			}
+			const baseRepoDigest = String(buildPackResult?.baseRepoDigest ?? '').trim();
+			if (baseRepoDigest) {
+				if (!baseRepoDigest.includes('@sha256:')) {
+					throw new Error(`Invalid baseRepoDigest from build-pack of alias "${entry.alias}": ${baseRepoDigest}`);
+				}
+				const baseRepo = extractRepoFromRepoDigest(baseRepoDigest);
+				if (!entry.upstreamMatch || baseRepo.startsWith(entry.upstreamMatch)) {
+					upstream = baseRepoDigest;
+					if (Array.isArray(buildPackResult?.baseDiffIDs) && buildPackResult.baseDiffIDs.length > 0) {
+						upstreamDiffIDs = normalizeDigestList(buildPackResult.baseDiffIDs, `build-pack base diff ids of alias ${entry.alias}`);
+					}
+					if (upstreamDiffIDs.length > 0 && !startsWithDigestList(builtDiffIDs, upstreamDiffIDs)) {
+						logger.warn(`Ignore invalid upstream layer prefix for alias "${entry.alias}" from build-pack metadata`);
+						upstream = '';
+						upstreamDiffIDs = [];
+					}
+				}
+			}
+		} else {
+			fs.rmSync(contextTar, { force: true });
+		}
+		buildStageMs = Date.now() - buildStartAt;
+		imageRefs.push(builtImageRef);
+
+		const resolveStartAt = Date.now();
+		if (!imageID || builtDiffIDs.length === 0) {
+			throw new Error(`No rootfs layer metadata found in build-pack output for alias "${entry.alias}"`);
+		}
+		resolveStageMs = Date.now() - resolveStartAt;
+
+		if (upstreamDiffIDs.length > 0 && !startsWithDigestList(builtDiffIDs, upstreamDiffIDs)) {
+			throw new Error(`Failed to derive mixed layers for alias "${entry.alias}", built layers do not start with upstream layers`);
+		}
+
+		const embeddedDiffIDs = upstreamDiffIDs.length === 0 ? builtDiffIDs : builtDiffIDs.slice(upstreamDiffIDs.length);
+		if (embeddedDiffIDs.length === 0 && !upstream) {
+			throw new Error(`Alias "${entry.alias}" has no embed layers and no upstream image`);
+		}
+
+		imageMetaByRef.set(builtImageRef, {
+			alias: entry.alias,
+			imageID,
+			upstream: upstream || '',
+			embeddedDiffIDs,
+			archiveKey: archiveKey || '',
+		});
+		buildCacheRecords[entry.alias] = {
+			image_label: entry.imageLabel,
+			context_digest: contextDigest,
+			upstream_match: entry.upstreamMatch,
+			image_ref: builtImageRef,
+			image_id: imageID,
+			build_mode: 'pack',
+			built_diff_ids: builtDiffIDs,
+			upstream: upstream || '',
+			upstream_diff_ids: upstreamDiffIDs,
+			archive_key: archiveKey || '',
+		};
+
+		logger.info(`Image alias "${entry.alias}" is ready: ${builtImageRef}`);
+		logger.info(
+			`[profile] alias=${entry.alias} mode=${buildMode} context=${formatDurationMs(contextCollectMs)} build=${formatDurationMs(
+				buildStageMs,
+			)} resolve=${formatDurationMs(resolveStageMs)} total=${formatDurationMs(Date.now() - profileStartAt)}`,
+		);
+	}
+	saveImageBuildCache(buildCache.cachePath, buildCacheRecords);
+
+	const packageCacheKey = computePackageCacheKey([...imageMetaByRef.values()]);
+	const cachedPackage = tryLoadPackageCache(cwd, packageCacheKey, tempDir);
+	let convertResult = null;
+	if (cachedPackage) {
+		logger.info('Reuse cached OCI image package');
+		convertResult = {
+			lockImages: Object.fromEntries(
+				[...imageMetaByRef.values()].map((meta) => [
+					meta.alias,
+					{
+						image_id: meta.imageID,
+						upstream: meta.upstream ?? '',
+					},
+				]),
+			),
+			embeddedLayerBytes: cachedPackage.embeddedLayerBytes,
+			embeddedLayerCount: cachedPackage.embeddedLayerCount,
+		};
+	}
+
+	if (!convertResult) {
+		const packBridgeStartAt = Date.now();
+		const packedArchivePath = path.join(tempDir, 'images.packed.tar');
+		const packSpecs = imageRefs.map((ref) => {
+			const meta = imageMetaByRef.get(ref);
+			if (!meta) {
+				throw new Error(`Missing image meta for ref: ${ref}`);
+			}
+			return {
+				ref,
+				alias: meta.alias,
+				imageID: meta.imageID,
+				upstream: meta.upstream ?? '',
+				embeddedDiffIDs: meta.embeddedDiffIDs,
+				archiveKey: meta.archiveKey || undefined,
+			};
+		});
+		logger.info('Pack built images to OCI layout in debug bridge');
+		await bridge.packImages(packSpecs, packedArchivePath);
+		const packBridgeMs = Date.now() - packBridgeStartAt;
+		const extractStartAt = Date.now();
+		await tar.x({
+			file: packedArchivePath,
+			cwd: tempDir,
+		});
+		const extractMs = Date.now() - extractStartAt;
+		fs.rmSync(packedArchivePath, { force: true });
+		const parseStartAt = Date.now();
+		const packedResultPath = path.join(tempDir, 'pack-result.json');
+		if (!isFileExist(packedResultPath)) {
+			throw new Error('pack-result.json not found after pack-images');
+		}
+		const packedResult = JSON.parse(fs.readFileSync(packedResultPath, 'utf-8'));
+		fs.rmSync(packedResultPath, { force: true });
+		if (!isPlainObject(packedResult?.lockImages)) {
+			throw new Error('Invalid pack-result.json: lockImages is missing');
+		}
+		convertResult = {
+			lockImages: packedResult.lockImages,
+			embeddedLayerBytes: Number(packedResult?.embeddedLayerBytes ?? 0),
+			embeddedLayerCount: Number(packedResult?.embeddedLayerCount ?? 0),
+		};
+		const parseMs = Date.now() - parseStartAt;
+			logger.info(
+				`[profile] pack-images bridge=${formatDurationMs(packBridgeMs)} extract=${formatDurationMs(extractMs)} parse=${formatDurationMs(parseMs)} total=${formatDurationMs(
+					packBridgeMs + extractMs + parseMs,
+				)}`,
+			);
+		}
+		convertResult.lockImages = rewriteImagesLock(tempDir, convertResult.lockImages);
+		if (!cachedPackage) {
+			savePackageCache(cwd, packageCacheKey, tempDir, convertResult);
+		}
+
+		const upstreamByAlias = {};
+		const resolvedImageByAlias = {};
+	for (const meta of imageMetaByRef.values()) {
+		upstreamByAlias[meta.alias] = meta.upstream || '';
+		resolvedImageByAlias[meta.alias] = meta.imageID;
+	}
+
+	return {
+		imageCount: Object.keys(convertResult.lockImages).length,
+		upstreamByAlias,
+		resolvedImageByAlias,
+		embeddedLayerBytes: convertResult.embeddedLayerBytes,
+		embeddedLayerCount: convertResult.embeddedLayerCount,
+	};
+}