@kvell007/embed-labs-cli 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/local-toolchain.d.ts

@@ -6,6 +6,7 @@ export interface LocalToolchainAuthContext {
 }
 export interface LocalToolchainValidationResult {
     ok: boolean;
+    mode: string;
     host: {
         platform: string;
         arch: string;
@@ -107,6 +108,7 @@ export interface LocalToolchainInstallOptions extends LocalToolchainLatestOption
     sourceReleaseRoot?: string;
     sourceUrl?: string;
     installRoot?: string;
+    mode?: string;
     force?: boolean;
 }
 export interface LocalToolchainInstallResult {
@@ -114,16 +116,18 @@ export interface LocalToolchainInstallResult {
     version: string;
     channel: string;
     host: string;
+    mode: string;
     install_root: string;
     release_root: string;
     registry_path: string;
     source: {
-        kind: "directory" | "url";
+        kind: "directory" | "url" | "components";
         value: string;
         downloaded_path?: string;
         mirror_kind?: string;
         sha256?: string;
         size_bytes?: number;
+        components?: LocalToolchainInstalledComponent[];
     };
     installed_paths: string[];
     packages: LocalToolchainPackageRef[];
@@ -133,6 +137,7 @@ export interface LocalToolchainCurrentResult {
     installed: boolean;
     board_id: string;
     version?: string;
+    mode?: string;
     release_root?: string;
     registry_path: string;
     install_root: string;
@@ -147,15 +152,17 @@ export interface LocalToolchainDownloadPlan {
     board_id: string;
     host: string;
     toolchain: string;
-    source_url: string;
-    mirror_kind: string;
-    archive: {
+    source_url?: string;
+    mirror_kind?: string;
+    archive?: {
         file: string;
         size_bytes: number;
         sha256: string;
         content_type?: string;
     };
     mirrors: LocalToolchainDownloadMirror[];
+    components?: LocalToolchainDownloadComponent[];
+    default_mode?: string;
 }
 export interface LocalToolchainDownloadMirror {
     kind: string;
@@ -164,10 +171,38 @@ export interface LocalToolchainDownloadMirror {
     sha256?: string;
     size_bytes?: number;
 }
+export interface LocalToolchainDownloadComponent {
+    id: string;
+    version: string;
+    role?: string;
+    install_modes?: string[];
+    archive: {
+        file: string;
+        size_bytes: number;
+        sha256: string;
+        content_type?: string;
+    };
+    source_url?: string;
+    mirror_kind?: string;
+    mirrors: LocalToolchainDownloadMirror[];
+}
+export interface LocalToolchainInstalledComponent {
+    id: string;
+    version: string;
+    role?: string;
+    archive_file: string;
+    mirror_kind?: string;
+    downloaded_path: string;
+    size_bytes: number;
+    sha256: string;
+}
 export declare function defaultLocalReleaseRoot(): string;
 export declare function latestLocalToolchain(options?: LocalToolchainLatestOptions): Promise<LocalToolchainLatestResult>;
 export declare function currentLocalToolchain(installRoot?: string, boardId?: string): Promise<LocalToolchainCurrentResult>;
 export declare function installLocalToolchain(options?: LocalToolchainInstallOptions): Promise<LocalToolchainInstallResult>;
-export declare function validateLocalToolchain(releaseRoot?: string): Promise<LocalToolchainValidationResult>;
+export declare function validateLocalToolchain(input?: string | {
+    releaseRoot?: string;
+    mode?: string;
+}): Promise<LocalToolchainValidationResult>;
 export declare function compileTaishanPiSingleFile(options: LocalCompileOptions): Promise<LocalCompileResult>;
 export declare function buildTaishanPiQtSmoke(options: LocalQtSmokeBuildOptions): Promise<LocalCompileResult>;

package/dist/local-toolchain.js

@@ -21,6 +21,8 @@ const BUILT_IN_CHANNEL = {
         { id: "embedlabs.tools.vendor.rockchip", version: "1.0.0", manifest: "" },
         { id: "embedlabs.tools.common.llvm", version: "22.1.3", manifest: "" },
         { id: "embedlabs.tools.common.e2fsprogs", version: "1.0.0", manifest: "" },
+        { id: "embedlabs.tools.runtime.qtquick-live-preview", version: "1.0.31", manifest: "" },
+        { id: "embedlabs.tools.runtime.rp2350-monitor", version: "1.0.31", manifest: "" },
         { id: "embedlabs.family.rk356x", version: "1.0.0", manifest: "" },
         { id: "embedlabs.board.taishanpi.1m-rk3566", version: "1.0.31", manifest: "" }
     ]
@@ -50,6 +52,22 @@ const BUILT_IN_MANIFESTS = {
         hosts: ["darwin-arm64", "linux-x86_64"],
         provides: ["ext4.mke2fs", "ext4.resize2fs", "fakeroot"]
     },
+    "embedlabs.tools.runtime.qtquick-live-preview": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.tools.runtime.qtquick-live-preview",
+        version: "1.0.31",
+        kind: "tools",
+        hosts: ["darwin-arm64", "linux-x86_64"],
+        provides: ["qtquick.live_preview", "qtquick.live_preview.inspector", "qtquick.live_preview.feedback"]
+    },
+    "embedlabs.tools.runtime.rp2350-monitor": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.tools.runtime.rp2350-monitor",
+        version: "1.0.31",
+        kind: "tools",
+        hosts: ["darwin-arm64", "linux-x86_64"],
+        provides: ["rp2350.monitor.cli", "rp2350.monitor.logic_analyzer", "rp2350.monitor.logic_decode"]
+    },
     "embedlabs.family.rk356x": {
         schema: "embedlabs.package.v1",
         id: "embedlabs.family.rk356x",
@@ -74,7 +92,9 @@ const BUILT_IN_MANIFESTS = {
             { id: "embedlabs.family.rk356x", version: "^1.0.0" },
             { id: "embedlabs.tools.vendor.rockchip", version: "^1.0.0", roles: ["flash", "resource-image"] },
             { id: "embedlabs.tools.common.llvm", version: "22.x", roles: ["compile"] },
-            { id: "embedlabs.tools.common.e2fsprogs", version: "^1.0.0", roles: ["userdata-image"] }
+            { id: "embedlabs.tools.common.e2fsprogs", version: "^1.0.0", roles: ["userdata-image"] },
+            { id: "embedlabs.tools.runtime.qtquick-live-preview", version: "^1.0.31", roles: ["qtquick-preview"] },
+            { id: "embedlabs.tools.runtime.rp2350-monitor", version: "^1.0.31", roles: ["rp2350-monitor"] }
         ],
         build_modes: ["local-llvm"]
     }
@@ -83,12 +103,23 @@ const INSTALL_COPY_PATHS = [
     "toolchain/llvm-cross",
     "toolchain/host",
     "toolchain/host-tools",
+    "toolchain/qt6-rk3566-llvm-toolchain.cmake",
     "qt-target/qt6-rk3566-llvm-6.8.3",
+    "qt-host/qt6-host-macos-6.8.3",
     "tools/mac",
+    "toolkit-runtime/qtquick-live-preview",
+    "toolkit-runtime/rp2350-monitor",
+    "toolkit-runtime/RP2350-Monitor",
     "images/current",
     "userdata/rootfs",
-    "boot-workspace/kernel-tree"
+    "boot-workspace",
+    "README.md",
+    "meta",
+    "scripts",
+    "support",
+    "third_party"
 ];
+const LOCAL_TOOLCHAIN_INSTALL_MODES = ["minimal", "compile", "qt", "full", "images"];
 export function defaultLocalReleaseRoot() {
     return process.env.EMBEDLABS_LOCAL_RELEASE_ROOT?.trim()
         || process.env.EMBEDLABS_RELEASE_ROOT?.trim()
@@ -121,7 +152,7 @@ export async function latestLocalToolchain(options = {}) {
         board_id: boardId,
         channel: channel.channel,
         host: hostId(),
-        version: board.version,
+        version: download?.version ?? board.version,
         metadata_root: metadataRoot,
         packages,
         download,
@@ -138,6 +169,7 @@ export async function currentLocalToolchain(installRoot, boardId = DEFAULT_BOARD
             installed: !!releaseRoot,
             board_id: typeof registry.board_id === "string" ? registry.board_id : boardId,
             version: typeof registry.version === "string" ? registry.version : undefined,
+            mode: typeof registry.mode === "string" ? registry.mode : undefined,
             release_root: releaseRoot,
             registry_path: registryPath,
             install_root: root,
@@ -158,30 +190,42 @@ export async function installLocalToolchain(options = {}) {
     const latest = await latestLocalToolchain(options);
     const installRoot = resolveInstallRoot(options.installRoot);
     const releaseRoot = resolve(installRoot, "toolchains", latest.board_id, latest.version);
+    const installMode = normalizeLocalToolchainInstallMode(options.mode ?? latest.download?.default_mode);
     if (await pathExists(releaseRoot) && !options.force) {
-        const validation = await validateLocalToolchain(releaseRoot);
+        const validation = await validateLocalToolchain({ releaseRoot, mode: installMode });
         if (!validation.ok) {
-            throw new Error(`Existing local toolchain is incomplete at ${releaseRoot}; rerun with --force.`);
+            if (latest.download?.components?.length) {
+                // Component installs can upgrade an existing lower-mode install by overlaying
+                // only the newly selected components instead of deleting the whole tree.
+            }
+            else {
+                throw new Error(`Existing local toolchain is incomplete at ${releaseRoot}; rerun with --force.`);
+            }
+        }
+        else {
+            await writeCurrentRegistry(installRoot, latest, releaseRoot, installMode);
+            return {
+                board_id: latest.board_id,
+                version: latest.version,
+                channel: latest.channel,
+                host: latest.host,
+                mode: installMode,
+                install_root: installRoot,
+                release_root: releaseRoot,
+                registry_path: localToolchainRegistryPath(installRoot),
+                source: { kind: "directory", value: releaseRoot },
+                installed_paths: [],
+                packages: latest.packages,
+                validation
+            };
         }
-        await writeCurrentRegistry(installRoot, latest, releaseRoot);
-        return {
-            board_id: latest.board_id,
-            version: latest.version,
-            channel: latest.channel,
-            host: latest.host,
-            install_root: installRoot,
-            release_root: releaseRoot,
-            registry_path: localToolchainRegistryPath(installRoot),
-            source: { kind: "directory", value: releaseRoot },
-            installed_paths: [],
-            packages: latest.packages,
-            validation
-        };
     }
     const tempDir = await mkdtemp(join(tmpdir(), "embedlabs-local-toolchain-install-"));
     try {
         const sourceRoot = await sourceReleaseRootForInstall(options, latest, installRoot, tempDir);
-        await rm(releaseRoot, { recursive: true, force: true });
+        if (options.force || !await pathExists(releaseRoot) || sourceRoot.source.kind !== "components") {
+            await rm(releaseRoot, { recursive: true, force: true });
+        }
         await mkdir(releaseRoot, { recursive: true });
         const installedPaths = [];
         for (const relativePath of INSTALL_COPY_PATHS) {
@@ -199,8 +243,8 @@ export async function installLocalToolchain(options = {}) {
             });
             installedPaths.push(relativePath);
         }
-        await writeCurrentRegistry(installRoot, latest, releaseRoot);
-        const validation = await validateLocalToolchain(releaseRoot);
+        await writeCurrentRegistry(installRoot, latest, releaseRoot, installMode, sourceRoot.source);
+        const validation = await validateLocalToolchain({ releaseRoot, mode: installMode });
         if (!validation.ok) {
             throw new Error(`Installed local toolchain is incomplete: ${validation.missing_paths.join(", ")}`);
         }
@@ -209,6 +253,7 @@ export async function installLocalToolchain(options = {}) {
             version: latest.version,
             channel: latest.channel,
             host: latest.host,
+            mode: installMode,
             install_root: installRoot,
             release_root: releaseRoot,
             registry_path: localToolchainRegistryPath(installRoot),
@@ -222,23 +267,11 @@ export async function installLocalToolchain(options = {}) {
         await rm(tempDir, { recursive: true, force: true });
     }
 }
-export async function validateLocalToolchain(releaseRoot) {
+export async function validateLocalToolchain(input) {
+    const releaseRoot = typeof input === "string" ? input : input?.releaseRoot;
+    const mode = normalizeLocalToolchainInstallMode(typeof input === "string" ? undefined : input?.mode);
     const resolvedRoot = await resolveLocalReleaseRoot(releaseRoot);
-    const required = [
-        ["release root", "."],
-        ["C compiler", "toolchain/llvm-cross/bin/aarch64-linux-gnu-gcc"],
-        ["C++ compiler", "toolchain/llvm-cross/bin/aarch64-linux-gnu-g++"],
-        ["readelf", "toolchain/llvm-cross/bin/aarch64-linux-gnu-readelf"],
-        ["host clang wrapper", "toolchain/host-tools/bin/clang-aarch64-linux-gnu"],
-        ["host GCC libraries", "toolchain/host/lib/gcc"],
-        ["Qt CMake", "qt-target/qt6-rk3566-llvm-6.8.3/bin/qt-cmake"],
-        ["target sysroot", "toolchain/host/aarch64-buildroot-linux-gnu/sysroot"],
-        ["Qt target libraries", "qt-target/qt6-rk3566-llvm-6.8.3/lib"],
-        ["Rockchip mkimage", "tools/mac/mkimage"],
-        ["Rockchip dumpimage", "tools/mac/dumpimage"],
-        ["Rockchip resource_tool", "tools/mac/resource_tool"],
-        ["Rockchip rkdeveloptool", "tools/mac/rkdeveloptool"]
-    ];
+    const required = requiredLocalToolchainChecks(mode);
     const checked_paths = [];
     for (const [label, relativePath] of required) {
         const absolutePath = resolve(resolvedRoot, relativePath);
@@ -251,6 +284,7 @@ export async function validateLocalToolchain(releaseRoot) {
     const missing_paths = checked_paths.filter((item) => !item.exists).map((item) => item.path);
     return {
         ok: missing_paths.length === 0,
+        mode,
         host: {
             platform: platform(),
             arch: arch()
@@ -261,10 +295,71 @@ export async function validateLocalToolchain(releaseRoot) {
         missing_paths,
         notes: [
             "Local build commands require an Embed Labs auth token so local resource use remains account attributable.",
-            "This validator checks the Mac-first TaishanPi LLVM release layout; package install/update registry work is tracked separately."
+            `This validator checks the TaishanPi LLVM local support layout for install mode ${mode}.`
         ]
     };
 }
+function normalizeLocalToolchainInstallMode(mode) {
+    const normalized = mode?.trim();
+    if (!normalized) {
+        return "qt";
+    }
+    if (LOCAL_TOOLCHAIN_INSTALL_MODES.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Unsupported local toolchain install mode ${normalized}; expected ${LOCAL_TOOLCHAIN_INSTALL_MODES.join(", ")}.`);
+}
+function requiredLocalToolchainChecks(mode) {
+    const base = [
+        ["release root", "."],
+        ["Rockchip mkimage", "tools/mac/mkimage"],
+        ["Rockchip dumpimage", "tools/mac/dumpimage"],
+        ["Rockchip resource_tool", "tools/mac/resource_tool"],
+        ["Rockchip rkdeveloptool", "tools/mac/rkdeveloptool"],
+        ["boot resource image", "boot-workspace/out/resource.img"],
+        ["boot image", "boot-workspace/out/boot.img"],
+        ["boot DTB", "boot-workspace/out/tspi-rk3566-user-v10-linux.dtb"],
+        ["RP2350 Monitor CLI", "toolkit-runtime/rp2350-monitor/tools/rpmon_cli.py"],
+        ["RP2350 Monitor logic analyzer", "toolkit-runtime/rp2350-monitor/ui/bin/embed-labs-logic-analyzer"],
+        ["package metadata", "meta"]
+    ];
+    const compile = [
+        ["C compiler", "toolchain/llvm-cross/bin/aarch64-linux-gnu-gcc"],
+        ["C++ compiler", "toolchain/llvm-cross/bin/aarch64-linux-gnu-g++"],
+        ["readelf", "toolchain/llvm-cross/bin/aarch64-linux-gnu-readelf"],
+        ["host clang wrapper", "toolchain/host-tools/bin/clang-aarch64-linux-gnu"],
+        ["host GCC libraries", "toolchain/host/lib/gcc"],
+        ["target sysroot", "toolchain/host/aarch64-buildroot-linux-gnu/sysroot"],
+        ["target include directory", "toolchain/host/aarch64-buildroot-linux-gnu/include"]
+    ];
+    const qt = [
+        ["Qt CMake", "qt-target/qt6-rk3566-llvm-6.8.3/bin/qt-cmake"],
+        ["Qt target libraries", "qt-target/qt6-rk3566-llvm-6.8.3/lib"],
+        ["Qt host tools", "qt-host/qt6-host-macos-6.8.3"],
+        ["QtQuick live preview", "toolkit-runtime/qtquick-live-preview/bin/embed-qml-live-preview"]
+    ];
+    const images = [
+        ["base boot image", "images/current/boot.img"],
+        ["base rootfs image", "images/current/rootfs.img"],
+        ["base image parameter", "images/current/parameter.txt"]
+    ];
+    const full = [
+        ["rootfs overlay", "userdata/rootfs"]
+    ];
+    if (mode === "minimal") {
+        return base;
+    }
+    if (mode === "compile") {
+        return [...base, ...compile];
+    }
+    if (mode === "qt") {
+        return [...base, ...compile, ...qt];
+    }
+    if (mode === "images") {
+        return [...base, ...images];
+    }
+    return [...base, ...compile, ...qt, ...images, ...full];
+}
 export async function compileTaishanPiSingleFile(options) {
     assertAuthenticated(options.auth);
     const releaseRoot = await resolveLocalReleaseRoot(options.releaseRoot);
@@ -374,7 +469,7 @@ async function resolveLocalToolchainDownloadPlan(input) {
         return item.board_id === input.boardId
             && item.host === input.host
             && item.toolchain === input.toolchain
-            && (item.kind === undefined || item.kind === "toolchain-archive");
+            && (item.kind === undefined || item.kind === "toolchain-archive" || item.kind === "board-support-archive");
     });
     if (!entry?.manifest) {
         return undefined;
@@ -387,20 +482,24 @@ async function resolveLocalToolchainDownloadPlan(input) {
     if (manifest.board_id !== input.boardId || manifest.host !== input.host || manifest.toolchain !== input.toolchain) {
         throw new Error(`Download manifest does not match requested ${input.boardId}/${input.host}/${input.toolchain}.`);
     }
-    if (!manifest.archive?.file || !manifest.archive.sha256 || !Number.isFinite(manifest.archive.size_bytes)) {
-        throw new Error(`Download manifest ${manifest.id}@${manifest.version} is missing archive file, size, or SHA256.`);
-    }
-    const mirrors = orderDownloadMirrors((manifest.mirrors ?? [])
-        .filter((mirror) => mirror.enabled !== false && typeof mirror.url === "string" && mirror.url.length > 0)
-        .map((mirror) => ({
-        kind: mirror.kind || "unknown",
-        enabled: mirror.enabled !== false,
-        url: mirror.url,
-        sha256: typeof mirror.sha256 === "string" ? mirror.sha256 : manifest.archive?.sha256,
-        size_bytes: Number.isFinite(mirror.size_bytes) ? mirror.size_bytes : manifest.archive?.size_bytes
-    })), manifest.download_policy?.preferred_order);
+    if ((!manifest.archive?.file || !manifest.archive.sha256 || !Number.isFinite(manifest.archive.size_bytes))
+        && (!Array.isArray(manifest.components) || manifest.components.length === 0)) {
+        throw new Error(`Download manifest ${manifest.id}@${manifest.version} is missing archive/components metadata.`);
+    }
+    const mirrors = manifest.archive
+        ? orderDownloadMirrors((manifest.mirrors ?? [])
+            .filter((mirror) => mirror.enabled !== false && typeof mirror.url === "string" && mirror.url.length > 0)
+            .map((mirror) => ({
+            kind: mirror.kind || "unknown",
+            enabled: mirror.enabled !== false,
+            url: mirror.url,
+            sha256: typeof mirror.sha256 === "string" ? mirror.sha256 : manifest.archive?.sha256,
+            size_bytes: Number.isFinite(mirror.size_bytes) ? mirror.size_bytes : manifest.archive?.size_bytes
+        })), manifest.download_policy?.preferred_order)
+        : [];
+    const components = (manifest.components ?? []).map((component) => normalizeDownloadComponent(component, manifest, manifestUrl));
     const first = mirrors[0];
-    if (!first) {
+    if (!first && components.length === 0) {
         return undefined;
     }
     return {
@@ -411,14 +510,52 @@ async function resolveLocalToolchainDownloadPlan(input) {
         board_id: input.boardId,
         host: input.host,
         toolchain: input.toolchain,
-        source_url: first.url,
-        mirror_kind: first.kind,
-        archive: {
+        source_url: first?.url,
+        mirror_kind: first?.kind,
+        archive: manifest.archive ? {
             file: manifest.archive.file,
             size_bytes: manifest.archive.size_bytes,
             sha256: manifest.archive.sha256,
             content_type: manifest.archive.content_type
+        } : undefined,
+        mirrors,
+        components: components.length > 0 ? components : undefined,
+        default_mode: manifest.download_policy?.default_mode
+    };
+}
+function normalizeDownloadComponent(component, manifest, manifestUrl) {
+    if (!component.id || !component.version) {
+        throw new Error(`Download manifest ${manifest.id}@${manifest.version} contains a component without id/version.`);
+    }
+    if (!component.archive?.file || !component.archive.sha256 || !Number.isFinite(component.archive.size_bytes)) {
+        throw new Error(`Download manifest ${manifest.id}@${manifest.version} component ${component.id} is missing archive metadata.`);
+    }
+    const mirrors = orderDownloadMirrors((component.mirrors ?? [])
+        .filter((mirror) => mirror.enabled !== false && typeof mirror.url === "string" && mirror.url.length > 0)
+        .map((mirror) => ({
+        kind: mirror.kind || "unknown",
+        enabled: mirror.enabled !== false,
+        url: new URL(mirror.url, manifestUrl).toString(),
+        sha256: typeof mirror.sha256 === "string" ? mirror.sha256 : component.archive?.sha256,
+        size_bytes: Number.isFinite(mirror.size_bytes) ? mirror.size_bytes : component.archive?.size_bytes
+    })), manifest.download_policy?.preferred_order);
+    const first = mirrors[0];
+    if (!first) {
+        throw new Error(`Download manifest ${manifest.id}@${manifest.version} component ${component.id} has no enabled mirrors.`);
+    }
+    return {
+        id: component.id,
+        version: component.version,
+        role: component.role,
+        install_modes: Array.isArray(component.install_modes) ? component.install_modes : undefined,
+        archive: {
+            file: component.archive.file,
+            size_bytes: component.archive.size_bytes,
+            sha256: component.archive.sha256,
+            content_type: component.archive.content_type
         },
+        source_url: first.url,
+        mirror_kind: first.kind,
         mirrors
     };
 }
@@ -502,7 +639,7 @@ function resolveInstallRoot(installRoot) {
 function localToolchainRegistryPath(installRoot) {
     return join(installRoot, "registry", "local-toolchains.json");
 }
-async function writeCurrentRegistry(installRoot, latest, releaseRoot) {
+async function writeCurrentRegistry(installRoot, latest, releaseRoot, mode, source) {
     const registryPath = localToolchainRegistryPath(installRoot);
     await mkdir(dirname(registryPath), { recursive: true });
     await writeFile(registryPath, `${JSON.stringify({
@@ -511,8 +648,11 @@ async function writeCurrentRegistry(installRoot, latest, releaseRoot) {
         version: latest.version,
         channel: latest.channel,
         host: latest.host,
+        mode,
         release_root: releaseRoot,
         packages: latest.packages,
+        source,
+        installed_components: source?.components,
         updated_at: new Date().toISOString()
     }, null, 2)}\n`, "utf8");
 }
@@ -550,12 +690,18 @@ async function sourceReleaseRootForInstall(options, latest, installRoot, tempDir
             source: { kind: "url", value: options.sourceUrl, downloaded_path: downloadedPath }
         };
     }
+    if (latest.download?.components?.length) {
+        return await componentSourceRootForInstall(options, latest.download, installRoot, tempDir);
+    }
     if (latest.download) {
         const failures = [];
         for (const mirror of latest.download.mirrors) {
             if (!mirror.enabled) {
                 continue;
             }
+            if (!latest.download.archive) {
+                continue;
+            }
             const extractRoot = join(tempDir, `extract-${safeFileToken(mirror.kind)}`);
             try {
                 const downloadedPath = await downloadToolchainArchive(mirror.url, installRoot, {
@@ -596,6 +742,71 @@ async function sourceReleaseRootForInstall(options, latest, installRoot, tempDir
     }
     throw new Error("Local toolchain install could not resolve a source. Pass --source-url <tar.gz>, --source-release-root <path>, or configure EMBED_DOWNLOAD_BASE_URL.");
 }
+async function componentSourceRootForInstall(options, download, installRoot, tempDir) {
+    const mode = normalizeLocalToolchainInstallMode(options.mode ?? download.default_mode);
+    const components = selectedDownloadComponents(download.components ?? [], mode);
+    if (components.length === 0) {
+        throw new Error(`No local toolchain components selected for mode ${mode}.`);
+    }
+    const extractRoot = join(tempDir, "extract-components");
+    await mkdir(extractRoot, { recursive: true });
+    const installedComponents = [];
+    const failures = [];
+    for (const component of components) {
+        let installed = false;
+        for (const mirror of component.mirrors) {
+            if (!mirror.enabled) {
+                continue;
+            }
+            try {
+                const downloadedPath = await downloadToolchainArchive(mirror.url, installRoot, {
+                    sha256: mirror.sha256 ?? component.archive.sha256,
+                    size_bytes: mirror.size_bytes ?? component.archive.size_bytes
+                });
+                const extracted = await runCommand(["tar", "-xzf", downloadedPath, "-C", extractRoot], tempDir);
+                if (extracted.exit_code !== 0) {
+                    throw new Error(`Could not extract component ${component.id}: ${extracted.stderr_tail.join("\n")}`);
+                }
+                installedComponents.push({
+                    id: component.id,
+                    version: component.version,
+                    role: component.role,
+                    archive_file: component.archive.file,
+                    mirror_kind: mirror.kind,
+                    downloaded_path: downloadedPath,
+                    size_bytes: mirror.size_bytes ?? component.archive.size_bytes,
+                    sha256: mirror.sha256 ?? component.archive.sha256
+                });
+                installed = true;
+                break;
+            }
+            catch (error) {
+                failures.push(`${component.id}@${component.version}/${mirror.kind}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (!installed) {
+            throw new Error(`Could not install component ${component.id}@${component.version}: ${failures.join("; ")}`);
+        }
+    }
+    return {
+        path: extractRoot,
+        source: {
+            kind: "components",
+            value: download.manifest_url,
+            mirror_kind: "components",
+            size_bytes: installedComponents.reduce((total, component) => total + component.size_bytes, 0),
+            components: installedComponents
+        }
+    };
+}
+function selectedDownloadComponents(components, mode) {
+    return components.filter((component) => {
+        if (!component.install_modes?.length) {
+            return true;
+        }
+        return component.install_modes.includes(mode);
+    });
+}
 async function downloadToolchainArchive(sourceUrl, installRoot, expected) {
     const downloadsDir = join(installRoot, "cache", "downloads");
     await mkdir(downloadsDir, { recursive: true });