@kvell007/embed-labs-cli 0.1.0-alpha.5 → 0.1.0-alpha.51

package/dist/local-toolchain.js

@@ -8,19 +8,27 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
 const DEFAULT_RELEASE_ROOT = "/Volumes/LLVM-TSPI/tspi-rk3566-llvm-release-minimal";
-const DEFAULT_QT_SMOKE_SOURCE = "/Users/kvell/kk-project/DBT-Agent-Project/llvm-build-tspi/qt-smoke";
-const DEFAULT_METADATA_ROOT = "/Users/kvell/kk-project/DBT-Agent-Project/llvm-build-tspi/embedlabs-release";
 const DEFAULT_BOARD_ID = "taishanpi-1m-rk3566";
+const PICO2W_RP2350_BOARD_ID = "pico2w-rp2350-monitor";
+const COLOREASYPICO2_RP2350_BOARD_ID = "coloreasypico2-rp2350-monitor";
 const DEFAULT_CHANNEL = "stable";
+const DEFAULT_DOWNLOAD_BASE_URL = "https://download.embedboard.com";
+const DOWNLOAD_REQUEST_TIMEOUT_MS = 12_000;
 const BUILT_IN_CHANNEL = {
     schema: "embedlabs.channel.v1",
     channel: DEFAULT_CHANNEL,
     packages: [
         { id: "embedlabs.tools.vendor.rockchip", version: "1.0.0", manifest: "" },
         { id: "embedlabs.tools.common.llvm", version: "22.1.3", manifest: "" },
+        { id: "embedlabs.tools.common.arm-none-eabi", version: "15.2.rel1", manifest: "" },
         { id: "embedlabs.tools.common.e2fsprogs", version: "1.0.0", manifest: "" },
+        { id: "embedlabs.tools.runtime.qtquick-live-preview", version: "1.0.33", manifest: "" },
+        { id: "embedlabs.tools.runtime.rp2350-monitor", version: "1.0.33", manifest: "" },
         { id: "embedlabs.family.rk356x", version: "1.0.0", manifest: "" },
-        { id: "embedlabs.board.taishanpi.1m-rk3566", version: "1.0.31", manifest: "" }
+        { id: "embedlabs.family.rp2350", version: "1.0.0", manifest: "" },
+        { id: "embedlabs.board.taishanpi.1m-rk3566", version: "1.0.33", manifest: "" },
+        { id: "embedlabs.board.pico2w.rp2350-monitor", version: "1.0.33", manifest: "" },
+        { id: "embedlabs.board.coloreasypico2.rp2350-monitor", version: "1.0.33", manifest: "" }
     ]
 };
 const BUILT_IN_MANIFESTS = {
@@ -40,6 +48,14 @@ const BUILT_IN_MANIFESTS = {
         hosts: ["darwin-arm64", "linux-x86_64"],
         provides: ["llvm.clang", "llvm.clangxx", "llvm.ld_lld", "llvm.ar", "llvm.objcopy", "llvm.readelf"]
     },
+    "embedlabs.tools.common.arm-none-eabi": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.tools.common.arm-none-eabi",
+        version: "15.2.rel1",
+        kind: "tools",
+        hosts: ["darwin-arm64"],
+        provides: ["arm-none-eabi.gcc", "arm-none-eabi.g++", "arm-none-eabi.objcopy", "picotool"]
+    },
     "embedlabs.tools.common.e2fsprogs": {
         schema: "embedlabs.package.v1",
         id: "embedlabs.tools.common.e2fsprogs",
@@ -48,6 +64,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.33",
+        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.33",
+        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",
@@ -60,10 +92,21 @@ const BUILT_IN_MANIFESTS = {
             { id: "embedlabs.tools.common.e2fsprogs", version: "^1.0.0" }
         ]
     },
+    "embedlabs.family.rp2350": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.family.rp2350",
+        version: "1.0.0",
+        kind: "family",
+        family: "rp2350",
+        requires: [
+            { id: "embedlabs.tools.common.arm-none-eabi", version: "15.x", roles: ["compile", "uf2"] },
+            { id: "embedlabs.tools.runtime.rp2350-monitor", version: "^1.0.33", roles: ["hardware-control", "logic-analyzer", "debug-probe"] }
+        ]
+    },
     "embedlabs.board.taishanpi.1m-rk3566": {
         schema: "embedlabs.package.v1",
         id: "embedlabs.board.taishanpi.1m-rk3566",
-        version: "1.0.31",
+        version: "1.0.33",
         kind: "board",
         family: "rk356x",
         board: "TaishanPi",
@@ -72,20 +115,67 @@ 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.33", roles: ["qtquick-preview"] }
         ],
         build_modes: ["local-llvm"]
+    },
+    "embedlabs.board.pico2w.rp2350-monitor": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.board.pico2w.rp2350-monitor",
+        version: "1.0.33",
+        kind: "board",
+        display_name: "Pico 2 W",
+        family: "rp2350",
+        board: "Pico 2 W",
+        board_id: PICO2W_RP2350_BOARD_ID,
+        requires: [
+            { id: "embedlabs.family.rp2350", version: "^1.0.0" },
+            { id: "embedlabs.tools.common.arm-none-eabi", version: "15.x", roles: ["compile", "uf2", "picotool"] },
+            { id: "embedlabs.tools.runtime.rp2350-monitor", version: "^1.0.33", roles: ["hardware-control", "logic-analyzer", "debug-probe"] }
+        ],
+        build_modes: ["local-pico-sdk", "optional-rp2350-monitor"]
+    },
+    "embedlabs.board.coloreasypico2.rp2350-monitor": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.board.coloreasypico2.rp2350-monitor",
+        version: "1.0.33",
+        kind: "board",
+        display_name: "ColorEasyPICO2",
+        family: "rp2350",
+        board: "ColorEasyPICO2",
+        board_id: COLOREASYPICO2_RP2350_BOARD_ID,
+        requires: [
+            { id: "embedlabs.family.rp2350", version: "^1.0.0" },
+            { id: "embedlabs.tools.common.arm-none-eabi", version: "15.x", roles: ["compile", "uf2", "picotool"] },
+            { id: "embedlabs.tools.runtime.rp2350-monitor", version: "^1.0.33", roles: ["hardware-control", "logic-analyzer", "debug-probe"] }
+        ],
+        build_modes: ["local-pico-sdk", "optional-rp2350-monitor"]
     }
 };
 const INSTALL_COPY_PATHS = [
     "toolchain/llvm-cross",
-    "toolchain/host/aarch64-buildroot-linux-gnu/sysroot",
+    "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",
+    "rp2350-sdk",
+    "rp2350-initial-firmware",
+    "rp2350-examples",
     "images/current",
     "userdata/rootfs",
-    "boot-workspace/kernel-tree"
+    "boot-workspace",
+    "README.md",
+    "meta",
+    "scripts",
+    "support",
+    "third_party"
 ];
+const LOCAL_TOOLCHAIN_INSTALL_MODES = ["minimal", "runtime", "compile", "qt", "firmware", "full", "images"];
 export function defaultLocalReleaseRoot() {
     return process.env.EMBEDLABS_LOCAL_RELEASE_ROOT?.trim()
         || process.env.EMBEDLABS_RELEASE_ROOT?.trim()
@@ -100,14 +190,30 @@ export async function latestLocalToolchain(options = {}) {
     if (!board) {
         throw new Error(`No local toolchain board package found for ${boardId}.`);
     }
+    const canonicalBoardId = boardIdForPackageManifest(board);
     const packages = resolvePackageRefs(boardPackageId, channel, manifests);
+    let download;
+    let downloadError;
+    try {
+        download = await resolveLocalToolchainDownloadPlan({
+            boardId: canonicalBoardId,
+            channel: channelName,
+            host: hostId(),
+            toolchain: "llvm"
+        });
+    }
+    catch (error) {
+        downloadError = error instanceof Error ? error.message : String(error);
+    }
     return {
-        board_id: boardId,
+        board_id: canonicalBoardId,
         channel: channel.channel,
         host: hostId(),
-        version: board.version,
+        version: download?.version ?? board.version,
         metadata_root: metadataRoot,
-        packages
+        packages,
+        download,
+        download_error: downloadError
     };
 }
 export async function currentLocalToolchain(installRoot, boardId = DEFAULT_BOARD_ID) {
@@ -115,11 +221,36 @@ export async function currentLocalToolchain(installRoot, boardId = DEFAULT_BOARD
     const registryPath = localToolchainRegistryPath(root);
     try {
         const registry = JSON.parse(await readFile(registryPath, "utf8"));
+        const environments = registry.environments;
+        const boardInstall = environments?.[normalizeBoardId(boardId)];
+        if (boardInstall?.release_root) {
+            return {
+                installed: true,
+                board_id: typeof boardInstall.board_id === "string" ? boardInstall.board_id : boardId,
+                version: typeof boardInstall.version === "string" ? boardInstall.version : undefined,
+                mode: typeof boardInstall.mode === "string" ? boardInstall.mode : undefined,
+                release_root: boardInstall.release_root,
+                registry_path: registryPath,
+                install_root: root,
+                channel: typeof boardInstall.channel === "string" ? boardInstall.channel : undefined,
+                packages: Array.isArray(boardInstall.packages) ? boardInstall.packages : undefined
+            };
+        }
         const releaseRoot = typeof registry.release_root === "string" ? registry.release_root : undefined;
+        const registryBoardId = typeof registry.board_id === "string" ? registry.board_id : boardId;
+        if (releaseRoot && normalizeBoardId(registryBoardId) !== normalizeBoardId(boardId)) {
+            return {
+                installed: false,
+                board_id: boardId,
+                registry_path: registryPath,
+                install_root: root
+            };
+        }
         return {
             installed: !!releaseRoot,
-            board_id: typeof registry.board_id === "string" ? registry.board_id : boardId,
+            board_id: registryBoardId,
             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,
@@ -136,48 +267,228 @@ export async function currentLocalToolchain(installRoot, boardId = DEFAULT_BOARD
         };
     }
 }
+async function discoverInstalledLocalToolchains(installRoot, current) {
+    const installed = new Map();
+    if (current.installed && current.release_root) {
+        installed.set(normalizeBoardId(current.board_id), {
+            board_id: current.board_id,
+            version: current.version,
+            channel: current.channel,
+            mode: current.mode,
+            release_root: current.release_root
+        });
+    }
+    const toolchainsRoot = join(installRoot, "toolchains");
+    let boardEntries;
+    try {
+        boardEntries = await readdir(toolchainsRoot, { withFileTypes: true });
+    }
+    catch {
+        return installed;
+    }
+    for (const boardEntry of boardEntries) {
+        if (!boardEntry.isDirectory()) {
+            continue;
+        }
+        const boardId = normalizeBoardId(boardEntry.name);
+        if (installed.has(boardId)) {
+            continue;
+        }
+        const boardRoot = join(toolchainsRoot, boardEntry.name);
+        let versionEntries;
+        try {
+            versionEntries = await readdir(boardRoot, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        const versions = versionEntries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort(compareVersionLike)
+            .reverse();
+        const version = versions[0];
+        if (!version) {
+            continue;
+        }
+        installed.set(boardId, {
+            board_id: boardId,
+            version,
+            release_root: join(boardRoot, version)
+        });
+    }
+    return installed;
+}
+export async function listLocalToolchainEnvironments(options = {}) {
+    const channelName = options.channel ?? DEFAULT_CHANNEL;
+    const host = hostId();
+    const installRoot = resolveInstallRoot(options.installRoot);
+    const registryPath = localToolchainRegistryPath(installRoot);
+    const { channel, manifests, metadataRoot } = await loadLocalToolchainMetadata(options.metadataRoot, channelName);
+    const current = await currentLocalToolchain(installRoot);
+    const installedByBoard = await discoverInstalledLocalToolchains(installRoot, current);
+    const boardManifests = [...manifests.values()]
+        .filter((manifest) => manifest.kind === "board")
+        .filter((manifest) => {
+        if (!options.boardId) {
+            return true;
+        }
+        const normalizedFilter = normalizeBoardId(options.boardId);
+        return boardIdForPackageManifest(manifest) === normalizedFilter
+            || manifest.id === options.boardId
+            || manifest.id === packageIdForBoardFilter(options.boardId);
+    })
+        .sort((left, right) => boardIdForPackageManifest(left).localeCompare(boardIdForPackageManifest(right)));
+    const environments = [];
+    for (const board of boardManifests) {
+        const boardId = boardIdForPackageManifest(board);
+        const packages = resolvePackageRefs(board.id, channel, manifests);
+        const hostSupport = packageHostSupport(packages, manifests, host);
+        let download;
+        let downloadError;
+        try {
+            download = await resolveLocalToolchainDownloadPlan({
+                boardId,
+                channel: channelName,
+                host,
+                toolchain: "llvm"
+            });
+        }
+        catch (error) {
+            downloadError = error instanceof Error ? error.message : String(error);
+        }
+        const latestVersion = download?.version ?? board.version;
+        const currentForBoard = await currentLocalToolchain(installRoot, boardId);
+        const installedCandidate = currentForBoard.installed
+            ? currentForBoard
+            : installedByBoard.get(normalizeBoardId(boardId));
+        const installed = installedCandidate
+            ? {
+                version: installedCandidate.version,
+                channel: installedCandidate.channel,
+                mode: installedCandidate.mode,
+                release_root: installedCandidate.release_root
+            }
+            : undefined;
+        const updateAvailable = !!installed?.version && installed.version !== latestVersion;
+        const effectiveHostSupport = download || installed
+            ? { supported: true, unsupportedPackages: [] }
+            : hostSupport;
+        const status = !effectiveHostSupport.supported
+            ? "unsupported_host"
+            : updateAvailable
+                ? "update_available"
+                : installed
+                    ? "installed"
+                    : "available";
+        const mode = download?.default_mode ?? "qt";
+        const installModes = download
+            ? localToolchainInstallModesForDownload(download)
+            : installed?.mode
+                ? [installed.mode]
+                : localToolchainInstallModesForDownload(download);
+        environments.push({
+            board_id: boardId,
+            package_id: board.id,
+            display_name: board.display_name || [board.board, board.variant].filter(Boolean).join(" ") || boardId,
+            family: board.family,
+            variant: board.variant,
+            channel: channel.channel,
+            host,
+            status,
+            supported_host: effectiveHostSupport.supported,
+            unsupported_packages: effectiveHostSupport.unsupportedPackages,
+            install_modes: installModes,
+            installed,
+            latest: {
+                version: latestVersion,
+                default_mode: download?.default_mode,
+                source_url: download?.source_url,
+                manifest_url: download?.manifest_url,
+                component_count: download?.components?.length,
+                download_error: downloadError
+            },
+            packages,
+            components: download?.components?.map(localToolchainEnvironmentComponent),
+            install_command: `embedlabs local toolchain install --board ${boardId} --mode ${mode}`,
+            update_command: `embedlabs local toolchain install --board ${boardId} --mode ${mode} --force`,
+            notes: environmentNotes({ boardId, status, downloadError, unsupportedPackages: effectiveHostSupport.unsupportedPackages })
+        });
+    }
+    const filteredEnvironments = options.installedOnly
+        ? environments.filter((environment) => !!environment.installed)
+        : environments;
+    return {
+        host,
+        channel: channel.channel,
+        metadata_source: metadataRoot ? "local_override" : "built_in",
+        metadata_root: metadataRoot,
+        install_root: installRoot,
+        registry_path: registryPath,
+        environments: filteredEnvironments
+    };
+}
 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);
+        await rewriteLocalToolchainPortablePaths(releaseRoot, latest.board_id);
+        const validation = await validateLocalToolchain({ releaseRoot, mode: installMode, boardId: latest.board_id });
         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, installRoot, tempDir);
-        await rm(releaseRoot, { recursive: true, force: true });
+        const sourceRoot = await sourceReleaseRootForInstall(options, latest, installRoot, tempDir);
+        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) {
-            const sourcePath = resolve(sourceRoot.path, relativePath);
+        for (const relativePath of installCopyPathsForBoard(latest.board_id)) {
+            const sourcePath = await resolveInstallSourcePathForBoard(sourceRoot.path, relativePath, latest.board_id);
             if (!await pathExists(sourcePath)) {
                 continue;
             }
             const targetPath = resolve(releaseRoot, relativePath);
             await mkdir(dirname(targetPath), { recursive: true });
-            await cp(sourcePath, targetPath, { recursive: true, force: true, preserveTimestamps: true });
+            await cp(sourcePath, targetPath, {
+                recursive: true,
+                force: true,
+                preserveTimestamps: true,
+                verbatimSymlinks: true
+            });
             installedPaths.push(relativePath);
         }
-        await writeCurrentRegistry(installRoot, latest, releaseRoot);
-        const validation = await validateLocalToolchain(releaseRoot);
+        await rewriteLocalToolchainPortablePaths(releaseRoot, latest.board_id);
+        await writeCurrentRegistry(installRoot, latest, releaseRoot, installMode, sourceRoot.source);
+        const validation = await validateLocalToolchain({ releaseRoot, mode: installMode, boardId: latest.board_id });
         if (!validation.ok) {
             throw new Error(`Installed local toolchain is incomplete: ${validation.missing_paths.join(", ")}`);
         }
@@ -186,6 +497,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),
@@ -199,19 +511,75 @@ export async function installLocalToolchain(options = {}) {
         await rm(tempDir, { recursive: true, force: true });
     }
 }
-export async function validateLocalToolchain(releaseRoot) {
-    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"],
-        ["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 resource_tool", "tools/mac/resource_tool"]
-    ];
+export async function uninstallLocalToolchain(options = {}) {
+    if (!options.boardId?.trim()) {
+        throw new Error("board_id is required for local toolchain uninstall.");
+    }
+    const boardId = normalizeBoardId(options.boardId);
+    const installRoot = resolveInstallRoot(options.installRoot);
+    const registryPath = localToolchainRegistryPath(installRoot);
+    const boardRoot = resolve(installRoot, "toolchains", boardId);
+    const removedPaths = [];
+    if (await pathExists(boardRoot)) {
+        await rm(boardRoot, { recursive: true, force: true });
+        removedPaths.push(boardRoot);
+    }
+    let removedRegistryEntry = false;
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(registryPath, "utf8"));
+    }
+    catch {
+        existing = {};
+    }
+    const environments = isRecord(existing.environments)
+        ? { ...existing.environments }
+        : {};
+    if (Object.prototype.hasOwnProperty.call(environments, boardId)) {
+        delete environments[boardId];
+        removedRegistryEntry = true;
+    }
+    const topLevelBoard = normalizeBoardId(String(existing.board_id ?? DEFAULT_BOARD_ID));
+    const topLevelPointsToBoard = topLevelBoard === boardId && typeof existing.release_root === "string";
+    const cleaned = { ...existing, environments, updated_at: new Date().toISOString() };
+    if (topLevelPointsToBoard) {
+        for (const key of [
+            "installed",
+            "board_id",
+            "version",
+            "channel",
+            "host",
+            "mode",
+            "release_root",
+            "packages",
+            "source",
+            "installed_components"
+        ]) {
+            delete cleaned[key];
+        }
+        removedRegistryEntry = true;
+    }
+    if (removedRegistryEntry || Object.keys(environments).length > 0 || Object.keys(existing).length > 0) {
+        await mkdir(dirname(registryPath), { recursive: true });
+        await writeFile(registryPath, `${JSON.stringify(cleaned, null, 2)}\n`, "utf8");
+    }
+    return {
+        board_id: boardId,
+        install_root: installRoot,
+        registry_path: registryPath,
+        removed: removedPaths.length > 0 || removedRegistryEntry,
+        removed_paths: removedPaths,
+        removed_registry_entry: removedRegistryEntry,
+        remaining_installed_boards: Object.keys(environments).sort(),
+        observed_at: new Date().toISOString()
+    };
+}
+export async function validateLocalToolchain(input) {
+    const releaseRoot = typeof input === "string" ? input : input?.releaseRoot;
+    const mode = normalizeLocalToolchainInstallMode(typeof input === "string" ? undefined : input?.mode);
+    const boardId = normalizeBoardId(typeof input === "string" ? DEFAULT_BOARD_ID : input?.boardId ?? DEFAULT_BOARD_ID);
+    const resolvedRoot = await resolveLocalReleaseRoot(releaseRoot, boardId);
+    const required = requiredLocalToolchainChecks(mode, boardId);
     const checked_paths = [];
     for (const [label, relativePath] of required) {
         const absolutePath = resolve(resolvedRoot, relativePath);
@@ -222,22 +590,309 @@ export async function validateLocalToolchain(releaseRoot) {
         });
     }
     const missing_paths = checked_paths.filter((item) => !item.exists).map((item) => item.path);
+    const path_leaks = await localToolchainPathLeaks(resolvedRoot, boardId);
+    const missing_groups = localToolchainMissingGroups(checked_paths, path_leaks);
+    const repair_command = missing_paths.length > 0 || path_leaks.length > 0
+        ? `embedlabs local toolchain install --board ${boardId} --mode ${mode}`
+        : undefined;
     return {
-        ok: missing_paths.length === 0,
+        ok: missing_paths.length === 0 && path_leaks.length === 0,
+        mode,
         host: {
             platform: platform(),
             arch: arch()
         },
-        board_id: DEFAULT_BOARD_ID,
+        board_id: boardId,
         release_root: resolvedRoot,
         checked_paths,
         missing_paths,
+        path_leaks,
+        missing_groups,
+        repair_command,
+        summary_for_user: localToolchainValidationSummary({
+            boardId,
+            mode,
+            ok: missing_paths.length === 0,
+            missingGroups: missing_groups,
+            repairCommand: repair_command
+        }),
         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 ${boardId} local support layout for install mode ${mode}.`
         ]
     };
 }
+function localToolchainMissingGroups(checkedPaths, pathLeaks = []) {
+    const groups = new Set();
+    if (pathLeaks.length > 0) {
+        groups.add("portable-paths/安装包可移植路径");
+    }
+    for (const check of checkedPaths) {
+        if (check.exists) {
+            continue;
+        }
+        const text = `${check.label} ${check.path}`.toLowerCase();
+        if (text.includes("qt host") || text.includes("qtquick") || text.includes("qt cmake") || text.includes("qt target")) {
+            groups.add("qt/Qt host、target 或实时预览组件");
+            continue;
+        }
+        if (text.includes("compiler") || text.includes("readelf") || text.includes("sysroot") || text.includes("include directory") || text.includes("clang wrapper") || text.includes("gcc libraries")) {
+            groups.add("compile/交叉编译器与 sysroot");
+            continue;
+        }
+        if (text.includes("boot") || text.includes("dtb") || text.includes("resource image") || text.includes("metadata") || text.includes("/meta")) {
+            groups.add("board-resources/启动资源、DTB 与元数据");
+            continue;
+        }
+        if (text.includes("image") || text.includes("rootfs") || text.includes("parameter")) {
+            groups.add("images/基础镜像资源");
+            continue;
+        }
+        if (text.includes("rp2350") || text.includes("pico")) {
+            groups.add("rp2350/RP2350 SDK、固件或监控运行时");
+            continue;
+        }
+        groups.add("runtime/运行时文件");
+    }
+    return [...groups];
+}
+async function rewriteLocalToolchainPortablePaths(releaseRoot, boardId) {
+    if (normalizeBoardId(boardId) !== DEFAULT_BOARD_ID) {
+        return;
+    }
+    const replacements = taishanPiPortablePathReplacements(releaseRoot);
+    const files = await taishanPiPortableTextFiles(releaseRoot);
+    for (const file of files) {
+        let content;
+        try {
+            content = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const rewritten = rewritePortablePathContent(content, replacements);
+        if (rewritten !== content) {
+            await writeFile(file, rewritten, "utf8");
+        }
+    }
+}
+async function localToolchainPathLeaks(releaseRoot, boardId) {
+    if (normalizeBoardId(boardId) !== DEFAULT_BOARD_ID || !await pathExists(releaseRoot)) {
+        return [];
+    }
+    const forbidden = taishanPiForbiddenPortablePathFragments();
+    const files = await taishanPiPortableTextFiles(releaseRoot);
+    const leaks = [];
+    for (const file of files) {
+        let content;
+        try {
+            content = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const fragment of forbidden) {
+            if (content.includes(fragment)) {
+                leaks.push({
+                    label: "portable path check",
+                    path: file,
+                    forbidden: fragment
+                });
+                break;
+            }
+        }
+    }
+    return leaks;
+}
+async function taishanPiPortableTextFiles(releaseRoot) {
+    const candidates = [
+        "toolchain/qt6-rk3566-llvm-toolchain.cmake",
+        "qt-target/qt6-rk3566-llvm-6.8.3/bin/target_qt.conf",
+        "qt-target/qt6-rk3566-llvm-6.8.3/lib/cmake/Qt6/Qt6Dependencies.cmake",
+        "qt-target/qt6-rk3566-llvm-6.8.3/lib/cmake/Qt6/qt.toolchain.cmake",
+        "qt-target/qt6-rk3566-llvm-6.8.3/lib/cmake/Qt6BuildInternals/QtBuildInternalsExtra.cmake",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/qdevice.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/qmodule.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/modules/qt_lib_core_private.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/modules/qt_lib_gui_private.pri",
+        "qt-target/qt6-rk3566-llvm-6.8.3/mkspecs/modules/qt_ext_openxr_loader.pri",
+        "qt-host/qt6-host-macos-6.8.3/lib/cmake/Qt6BuildInternals/QtBuildInternalsExtra.cmake",
+        "qt-host/qt6-host-macos-6.8.3/mkspecs/modules/qt_ext_openxr_loader.pri"
+    ];
+    const files = [];
+    for (const candidate of candidates) {
+        const file = join(releaseRoot, candidate);
+        if (await pathExists(file)) {
+            files.push(file);
+        }
+    }
+    return files;
+}
+function taishanPiPortablePathReplacements(releaseRoot) {
+    const normalizedRoot = resolve(releaseRoot);
+    // Legacy development paths are recognized only so older staged packages can
+    // be rewritten into a portable installed layout during validation/repair.
+    return [
+        ["@EMBEDLABS_RELEASE_ROOT@", normalizedRoot],
+        ["/Users/kvell/kk-project/DBT-Agent-Project/llvm-build-tspi/scripts/qt6-rk3566-llvm-toolchain.cmake", join(normalizedRoot, "toolchain", "qt6-rk3566-llvm-toolchain.cmake")],
+        ["/Users/kvell/kk-project/DBT-Agent-Project/llvm-build-tspi/.llvm-cross", join(normalizedRoot, "toolchain", "llvm-cross")],
+        ["/Volumes/LLVM-TSPI/tspi-rk3566-llvm-release-minimal", normalizedRoot],
+        ["/Volumes/LLVM-TSPI/sdk-tools/buildroot/output/rockchip_rk3566/host", join(normalizedRoot, "toolchain", "host")],
+        ["/Volumes/LLVM-TSPI/qt6-host-macos-6.8.3", join(normalizedRoot, "qt-host", "qt6-host-macos-6.8.3")],
+        ["/Volumes/LLVM-TSPI/qt6-rk3566-llvm-6.8.3", join(normalizedRoot, "qt-target", "qt6-rk3566-llvm-6.8.3")],
+        ["/Volumes/LLVM-TSPI/qt-build-host-macos-6.8.3", join(normalizedRoot, "qt-host", "qt6-host-macos-6.8.3", ".build-info", "qt-build-host-macos-6.8.3")],
+        ["/Volumes/LLVM-TSPI/qt-build-rk3566-llvm-6.8.3", join(normalizedRoot, "qt-target", "qt6-rk3566-llvm-6.8.3", ".build-info", "qt-build-rk3566-llvm-6.8.3")],
+        ["/Volumes/LLVM-TSPI/qt-everywhere-src-6.8.3", join(normalizedRoot, "meta", "source", "qt-everywhere-src-6.8.3")],
+        ["/Users/kvell/kk-project/DBT-Agent-Project/llvm-build-tspi", join(normalizedRoot, "meta", "source", "llvm-build-tspi")]
+    ];
+}
+function taishanPiForbiddenPortablePathFragments() {
+    return [
+        "/Volumes/LLVM-TSPI",
+        "/Users/kvell/kk-project/DBT-Agent-Project"
+    ];
+}
+function rewritePortablePathContent(content, replacements) {
+    let rewritten = content;
+    for (const [from, to] of replacements) {
+        rewritten = rewritten.split(from).join(to);
+    }
+    return rewritten;
+}
+function localToolchainValidationSummary(input) {
+    const boardName = input.boardId === DEFAULT_BOARD_ID
+        ? "泰山派 1M-RK3566"
+        : input.boardId;
+    if (input.ok) {
+        if (input.boardId === DEFAULT_BOARD_ID && input.mode === "qt") {
+            return `${boardName} Qt 本地开发环境完整，可以继续 QtQuick 原型、一键交叉编译和真机部署。`;
+        }
+        return `${boardName} 本地开发环境完整，可以继续使用 ${input.mode} 模式。`;
+    }
+    const groups = input.missingGroups.length > 0 ? input.missingGroups.join("、") : "部分文件";
+    if (input.boardId === DEFAULT_BOARD_ID && input.mode === "qt") {
+        return `${boardName} Qt 本地开发环境不完整，缺少 ${groups}。这会影响一键交叉编译、实时预览或真机部署；请先执行 ${input.repairCommand} 补装缺失组件。`;
+    }
+    return `${boardName} 本地开发环境不完整，缺少 ${groups}；请先执行 ${input.repairCommand} 补装缺失组件。`;
+}
+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, boardId) {
+    if (isRp2350MonitorBoardId(boardId)) {
+        return requiredRp2350MonitorChecks(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"],
+        ["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];
+}
+function requiredRp2350MonitorChecks(mode) {
+    const armToolchainDir = rp2350ArmToolchainDirName();
+    const executableSuffix = platform() === "win32" ? ".exe" : "";
+    const monitorLauncher = platform() === "win32"
+        ? "toolkit-runtime/rp2350-monitor/ui/bin/embed-labs-logic-analyzer.cmd"
+        : "toolkit-runtime/rp2350-monitor/ui/bin/embed-labs-logic-analyzer";
+    const base = [
+        ["release root", "."],
+    ];
+    const runtime = [
+        ["RP2350 Monitor UI", "toolkit-runtime/rp2350-monitor/ui/index.html"],
+        ["RP2350 Monitor bridge", "toolkit-runtime/rp2350-monitor/ui/bridge/rpmon_bridge.py"],
+        ["RP2350 Monitor CLI", "toolkit-runtime/rp2350-monitor/tools/rpmon_cli.py"],
+        ["RP2350 picotool", `toolkit-runtime/rp2350-monitor/tools/picotool${executableSuffix}`],
+        ["RP2350 Monitor logic analyzer", monitorLauncher],
+        ["RP2350 Monitor AI operation contract", "toolkit-runtime/rp2350-monitor/ui/docs/ai-operation-contract.md"],
+        ["package metadata", "meta"]
+    ];
+    const firmware = [
+        ["RP2350 Monitor UF2", "toolkit-runtime/rp2350-monitor/firmware/rp2350_monitor.uf2"],
+        ["RP2350 Monitor firmware source", "toolkit-runtime/rp2350-monitor/firmware/src/main.cpp"]
+    ];
+    const initialFirmware = [
+        ["Pico 2 W initialization UF2", "rp2350-initial-firmware/pico2w/initial.uf2"],
+        ["ColorEasyPICO2 initialization UF2", "rp2350-initial-firmware/coloreasypico2/initial.uf2"]
+    ];
+    const compile = [
+        ["Pico SDK", "rp2350-sdk/pico-sdk/pico_sdk_init.cmake"],
+        ["Pico SDK CMakeLists", "rp2350-sdk/pico-sdk/CMakeLists.txt"],
+        ["ARM bare-metal C compiler", `rp2350-sdk/toolchains/${armToolchainDir}/bin/arm-none-eabi-gcc${executableSuffix}`],
+        ["ARM bare-metal C++ compiler", `rp2350-sdk/toolchains/${armToolchainDir}/bin/arm-none-eabi-g++${executableSuffix}`],
+        ["picotool", `rp2350-sdk/picotool/install/picotool/picotool${executableSuffix}`]
+    ];
+    if (mode === "compile") {
+        return [...base, ...compile, ...initialFirmware];
+    }
+    if (mode === "firmware") {
+        return [...base, ...runtime, ...firmware, ...initialFirmware];
+    }
+    if (mode === "full") {
+        return [...base, ...runtime, ...firmware, ...initialFirmware, ...compile];
+    }
+    return [...base, ...runtime];
+}
+function rp2350ArmToolchainDirName() {
+    if (platform() === "win32") {
+        return "arm-gnu-toolchain-15.2.rel1-mingw-w64-x86_64-arm-none-eabi";
+    }
+    if (platform() === "linux" && arch() === "x64") {
+        return "arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi";
+    }
+    if (platform() === "linux" && arch() === "arm64") {
+        return "arm-gnu-toolchain-15.2.rel1-aarch64-arm-none-eabi";
+    }
+    return "arm-gnu-toolchain-15.2.rel1-darwin-arm64-arm-none-eabi";
+}
 export async function compileTaishanPiSingleFile(options) {
     assertAuthenticated(options.auth);
     const releaseRoot = await resolveLocalReleaseRoot(options.releaseRoot);
@@ -268,7 +923,7 @@ export async function compileTaishanPiSingleFile(options) {
 export async function buildTaishanPiQtSmoke(options) {
     assertAuthenticated(options.auth);
     const releaseRoot = await resolveLocalReleaseRoot(options.releaseRoot);
-    const sourceDir = resolve(options.sourceDir ?? DEFAULT_QT_SMOKE_SOURCE);
+    const sourceDir = resolve(options.sourceDir ?? join(releaseRoot, "examples", "qt-smoke"));
     const buildDir = resolve(options.buildDir);
     const targetName = options.targetName ?? "qt_llvm_smoke";
     const qtCmake = join(releaseRoot, "qt-target", "qt6-rk3566-llvm-6.8.3", "bin", "qt-cmake");
@@ -307,15 +962,14 @@ export async function buildTaishanPiQtSmoke(options) {
 }
 async function loadLocalToolchainMetadata(metadataRoot, channelName) {
     const explicitRoot = metadataRoot || process.env.EMBEDLABS_METADATA_ROOT?.trim();
-    const candidateRoot = explicitRoot || (await pathExists(DEFAULT_METADATA_ROOT) ? DEFAULT_METADATA_ROOT : undefined);
-    if (!candidateRoot) {
+    if (!explicitRoot) {
         return {
             channel: BUILT_IN_CHANNEL,
             manifests: new Map(Object.entries(BUILT_IN_MANIFESTS)),
             metadataRoot: undefined
         };
     }
-    const root = resolve(candidateRoot);
+    const root = resolve(explicitRoot);
     const channelPath = join(root, "channels", channelName, "index.json");
     const channel = JSON.parse(await readFile(channelPath, "utf8"));
     if (channel.schema !== "embedlabs.channel.v1") {
@@ -337,6 +991,149 @@ async function loadLocalToolchainMetadata(metadataRoot, channelName) {
     }
     return { channel, manifests, metadataRoot: root };
 }
+async function resolveLocalToolchainDownloadPlan(input) {
+    const requestedBoardId = normalizeBoardId(input.boardId);
+    const compatibleBoardIds = compatibleDownloadBoardIds(requestedBoardId);
+    const channelUrl = downloadChannelUrl(input.channel);
+    const channel = await fetchJson(channelUrl);
+    if (channel.schema !== "embedlabs.download-channel.v1") {
+        throw new Error(`Unexpected download channel schema ${channel.schema}.`);
+    }
+    const entries = channel.packages ?? [];
+    let entry;
+    for (const boardId of compatibleBoardIds) {
+        entry = entries.find((item) => {
+            return normalizeBoardId(item.board_id ?? "") === boardId
+                && item.host === input.host
+                && item.toolchain === input.toolchain
+                && (item.kind === undefined || item.kind === "toolchain-archive" || item.kind === "board-support-archive");
+        });
+        if (entry) {
+            break;
+        }
+    }
+    if (!entry?.manifest) {
+        return undefined;
+    }
+    const manifestUrl = new URL(entry.manifest, channelUrl).toString();
+    const manifest = await fetchJson(manifestUrl);
+    if (manifest.id !== entry.id || manifest.version !== entry.version) {
+        throw new Error(`Download manifest mismatch for ${entry.id}@${entry.version}.`);
+    }
+    const manifestBoardId = normalizeBoardId(manifest.board_id ?? "");
+    if (!compatibleBoardIds.includes(manifestBoardId) || manifest.host !== input.host || manifest.toolchain !== input.toolchain) {
+        throw new Error(`Download manifest does not match requested ${requestedBoardId}/${input.host}/${input.toolchain}.`);
+    }
+    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 = downloadComponentsForBoard(requestedBoardId, (manifest.components ?? []).map((component) => normalizeDownloadComponent(component, manifest, manifestUrl)));
+    const first = mirrors[0];
+    if (!first && components.length === 0) {
+        return undefined;
+    }
+    return {
+        channel_url: channelUrl,
+        manifest_url: manifestUrl,
+        package_id: manifest.id,
+        version: manifest.version,
+        board_id: requestedBoardId,
+        host: input.host,
+        toolchain: input.toolchain,
+        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
+    };
+}
+function orderDownloadMirrors(mirrors, preferredOrder) {
+    const preference = preferredOrder?.length
+        ? preferredOrder
+        : ["github_release", "embedlabs_cdn", "cloudfront", "embedlabs_server"];
+    return [...mirrors].sort((left, right) => mirrorRank(left.kind, preference) - mirrorRank(right.kind, preference));
+}
+function mirrorRank(kind, preferredOrder) {
+    const index = preferredOrder.indexOf(kind);
+    return index >= 0 ? index : preferredOrder.length + 1;
+}
+async function fetchJson(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_REQUEST_TIMEOUT_MS) });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status} while loading ${url}`);
+    }
+    return await response.json();
+}
+function downloadChannelUrl(channelName) {
+    const explicit = process.env.EMBED_DOWNLOAD_CHANNEL_URL?.trim()
+        || process.env.EMBEDLABS_DOWNLOAD_CHANNEL_URL?.trim();
+    if (explicit) {
+        return explicit;
+    }
+    return `${downloadBaseUrl()}/downloads/metadata/channels/${encodeURIComponent(channelName)}/index.json`;
+}
+function downloadBaseUrl() {
+    return trimTrailingSlash(process.env.EMBED_DOWNLOAD_BASE_URL?.trim()
+        || process.env.EMBEDLABS_DOWNLOAD_BASE_URL?.trim()
+        || DEFAULT_DOWNLOAD_BASE_URL);
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
 function resolvePackageRefs(packageId, channel, manifests, seen = new Set()) {
     if (seen.has(packageId)) {
         return [];
@@ -359,14 +1156,153 @@ function resolvePackageRefs(packageId, channel, manifests, seen = new Set()) {
     return refs;
 }
 function boardPackageIdFor(boardId) {
-    if (boardId === DEFAULT_BOARD_ID || boardId === "taishanpi" || boardId === "taishanpi-1m-rk3566") {
+    const normalized = normalizeBoardId(boardId);
+    if (normalized === DEFAULT_BOARD_ID || normalized === "taishanpi" || normalized === "taishanpi-1m-rk3566") {
         return "embedlabs.board.taishanpi.1m-rk3566";
     }
-    if (boardId.startsWith("embedlabs.board.")) {
+    if (normalized === COLOREASYPICO2_RP2350_BOARD_ID
+        || normalized === "coloreasypico2"
+        || normalized === "color-easy-pico2"
+        || normalized === "color-easy-pico-2"
+        || normalized === "color-easy-pico-2-rp2350-monitor"
+        || normalized === "ce-pico2") {
+        return "embedlabs.board.coloreasypico2.rp2350-monitor";
+    }
+    if (normalized === PICO2W_RP2350_BOARD_ID
+        || normalized === "pico2w"
+        || normalized === "pico-2-w"
+        || normalized === "pico2"
+        || normalized === "rp2350"
+        || normalized === "rp2350-monitor") {
+        return "embedlabs.board.pico2w.rp2350-monitor";
+    }
+    if (normalized.startsWith("embedlabs.board.")) {
         return boardId;
     }
     throw new Error(`Unsupported local toolchain board ${boardId}.`);
 }
+function packageIdForBoardFilter(boardId) {
+    try {
+        return boardPackageIdFor(boardId);
+    }
+    catch {
+        return undefined;
+    }
+}
+function boardIdForPackageManifest(manifest) {
+    const explicit = manifest.board_id;
+    if (explicit?.trim()) {
+        return normalizeBoardId(explicit);
+    }
+    if (manifest.id === "embedlabs.board.taishanpi.1m-rk3566") {
+        return DEFAULT_BOARD_ID;
+    }
+    if (manifest.id.startsWith("embedlabs.board.")) {
+        return normalizeBoardId(manifest.id.slice("embedlabs.board.".length).replaceAll(".", "-"));
+    }
+    return normalizeBoardId([manifest.board, manifest.variant].filter(Boolean).join("-") || manifest.id);
+}
+function normalizeBoardId(boardId) {
+    return boardId.trim().toLowerCase().replaceAll("_", "-");
+}
+function isRp2350MonitorBoardId(boardId) {
+    const normalized = normalizeBoardId(boardId);
+    return normalized === PICO2W_RP2350_BOARD_ID
+        || normalized === COLOREASYPICO2_RP2350_BOARD_ID
+        || normalized === "pico2w"
+        || normalized === "pico-2-w"
+        || normalized === "pico2"
+        || normalized === "rp2350"
+        || normalized === "rp2350-monitor"
+        || normalized === "coloreasypico2"
+        || normalized === "color-easy-pico2"
+        || normalized === "color-easy-pico-2"
+        || normalized === "ce-pico2";
+}
+function compatibleDownloadBoardIds(boardId) {
+    const normalized = normalizeBoardId(boardId);
+    if (normalized === COLOREASYPICO2_RP2350_BOARD_ID) {
+        return [COLOREASYPICO2_RP2350_BOARD_ID, PICO2W_RP2350_BOARD_ID];
+    }
+    return [normalized];
+}
+function downloadComponentsForBoard(boardId, components) {
+    const normalized = normalizeBoardId(boardId);
+    if (normalized === DEFAULT_BOARD_ID) {
+        return components.filter((component) => !isRp2350MonitorComponent(component));
+    }
+    return components;
+}
+function isRp2350MonitorComponent(component) {
+    const text = `${component.id} ${component.role ?? ""} ${component.archive.file}`.toLowerCase();
+    return text.includes("rp2350-monitor") || text.includes("pico2w-rp2350-monitor");
+}
+function compareVersionLike(left, right) {
+    return left.localeCompare(right, undefined, { numeric: true, sensitivity: "base" });
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function packageHostSupport(packages, manifests, host) {
+    const unsupportedPackages = [];
+    for (const item of packages) {
+        const manifest = manifests.get(item.id);
+        if (manifest?.hosts?.length && !manifest.hosts.includes(host)) {
+            unsupportedPackages.push(`${item.id}@${manifest.version}`);
+        }
+    }
+    return {
+        supported: unsupportedPackages.length === 0,
+        unsupportedPackages
+    };
+}
+function environmentNotes(input) {
+    const notes = [];
+    if (normalizeBoardId(input.boardId) === COLOREASYPICO2_RP2350_BOARD_ID) {
+        notes.push("ColorEasyPICO2 uses the same RP2350/Pico SDK, ARM bare-metal toolchain, picotool, and optional RP2350 Monitor image package as Pico 2 W; Wi-Fi operations are not declared for this no-Wi-Fi board.");
+    }
+    if (isRp2350MonitorBoardId(input.boardId)) {
+        notes.push("RP2350 Monitor is an optional hardware-control firmware image; the board environment itself is the Pico 2 W or ColorEasyPICO2 C/C++ SDK environment.");
+    }
+    if (input.status === "available") {
+        notes.push("Environment is available but not installed on this computer.");
+    }
+    if (input.status === "update_available") {
+        notes.push("A newer package is available; run the update command to refresh only the selected environment.");
+    }
+    if (input.status === "unsupported_host") {
+        notes.push(`This host is missing platform support for: ${input.unsupportedPackages.join(", ")}`);
+    }
+    if (input.downloadError) {
+        notes.push(`Download manifest could not be resolved yet: ${input.downloadError}`);
+    }
+    return notes;
+}
+function localToolchainInstallModesForDownload(download) {
+    if (!download?.components?.length) {
+        return [...LOCAL_TOOLCHAIN_INSTALL_MODES];
+    }
+    const modes = new Set();
+    for (const component of download.components) {
+        for (const mode of component.install_modes ?? []) {
+            modes.add(mode);
+        }
+    }
+    return modes.size > 0
+        ? [...modes].filter((mode) => LOCAL_TOOLCHAIN_INSTALL_MODES.includes(mode))
+        : [...LOCAL_TOOLCHAIN_INSTALL_MODES];
+}
+function localToolchainEnvironmentComponent(component) {
+    return {
+        id: component.id,
+        version: component.version,
+        role: component.role,
+        install_modes: component.install_modes,
+        file: component.archive.file,
+        size_bytes: component.archive.size_bytes,
+        source_url: component.source_url
+    };
+}
 function hostId() {
     if (platform() === "darwin" && arch() === "arm64") {
         return "darwin-arm64";
@@ -384,21 +1320,44 @@ 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({
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(registryPath, "utf8"));
+    }
+    catch {
+        existing = {};
+    }
+    const entry = {
         installed: true,
         board_id: latest.board_id,
         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()
+    };
+    const environments = isRecord(existing.environments)
+        ? { ...existing.environments }
+        : {};
+    environments[normalizeBoardId(latest.board_id)] = entry;
+    const preserveTopLevel = latest.board_id !== DEFAULT_BOARD_ID
+        && typeof existing.release_root === "string"
+        && normalizeBoardId(String(existing.board_id ?? DEFAULT_BOARD_ID)) === DEFAULT_BOARD_ID;
+    const topLevel = preserveTopLevel ? existing : entry;
+    await writeFile(registryPath, `${JSON.stringify({
+        ...topLevel,
+        environments,
         updated_at: new Date().toISOString()
     }, null, 2)}\n`, "utf8");
 }
-async function resolveLocalReleaseRoot(releaseRoot) {
+async function resolveLocalReleaseRoot(releaseRoot, boardId = DEFAULT_BOARD_ID) {
     if (releaseRoot?.trim()) {
         return resolve(releaseRoot);
     }
@@ -406,13 +1365,13 @@ async function resolveLocalReleaseRoot(releaseRoot) {
     if (envRoot) {
         return resolve(envRoot);
     }
-    const current = await currentLocalToolchain(undefined, DEFAULT_BOARD_ID);
+    const current = await currentLocalToolchain(undefined, boardId);
     if (current.release_root) {
         return resolve(current.release_root);
     }
     return resolve(DEFAULT_RELEASE_ROOT);
 }
-async function sourceReleaseRootForInstall(options, installRoot, tempDir) {
+async function sourceReleaseRootForInstall(options, latest, installRoot, tempDir) {
     if (options.sourceReleaseRoot) {
         return {
             path: resolve(options.sourceReleaseRoot),
@@ -432,15 +1391,180 @@ async function sourceReleaseRootForInstall(options, 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, {
+                    sha256: mirror.sha256 ?? latest.download.archive.sha256,
+                    size_bytes: mirror.size_bytes ?? latest.download.archive.size_bytes
+                });
+                await rm(extractRoot, { recursive: true, force: true });
+                await mkdir(extractRoot, { recursive: true });
+                const extracted = await runCommand(["tar", "-xzf", downloadedPath, "-C", extractRoot], tempDir);
+                if (extracted.exit_code !== 0) {
+                    throw new Error(`Could not extract local toolchain archive: ${extracted.stderr_tail.join("\n")}`);
+                }
+                return {
+                    path: await findReleaseRoot(extractRoot),
+                    source: {
+                        kind: "url",
+                        value: mirror.url,
+                        downloaded_path: downloadedPath,
+                        mirror_kind: mirror.kind,
+                        sha256: mirror.sha256 ?? latest.download.archive.sha256,
+                        size_bytes: mirror.size_bytes ?? latest.download.archive.size_bytes
+                    }
+                };
+            }
+            catch (error) {
+                failures.push(`${mirror.kind}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (failures.length > 0 && !await pathExists(DEFAULT_RELEASE_ROOT)) {
+            throw new Error(`Could not install local toolchain from download mirrors: ${failures.join("; ")}`);
+        }
+    }
     if (await pathExists(DEFAULT_RELEASE_ROOT)) {
         return {
             path: resolve(DEFAULT_RELEASE_ROOT),
             source: { kind: "directory", value: resolve(DEFAULT_RELEASE_ROOT) }
         };
     }
-    throw new Error("Local toolchain install needs --source-url <tar.gz> or --source-release-root <path> until the public download service is configured.");
+    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);
+    });
+}
+function installCopyPathsForBoard(boardId) {
+    if (normalizeBoardId(boardId) === DEFAULT_BOARD_ID) {
+        return INSTALL_COPY_PATHS.filter((relativePath) => {
+            const normalized = relativePath.toLowerCase();
+            return normalized !== "toolkit-runtime/rp2350-monitor"
+                && normalized !== "toolkit-runtime/rp2350-monitor/";
+        });
+    }
+    return INSTALL_COPY_PATHS;
+}
+async function resolveInstallSourcePathForBoard(sourceRoot, relativePath, boardId) {
+    const direct = resolve(sourceRoot, relativePath);
+    if (await pathExists(direct)) {
+        return direct;
+    }
+    if (!isRp2350MonitorBoardId(boardId)) {
+        return direct;
+    }
+    const legacyRp2350Root = await findLegacyRp2350Root(sourceRoot);
+    if (!legacyRp2350Root) {
+        return direct;
+    }
+    if (relativePath === "rp2350-sdk") {
+        return legacyRp2350Root;
+    }
+    if (relativePath === "rp2350-initial-firmware") {
+        return resolve(legacyRp2350Root, "initial_firmware");
+    }
+    if (relativePath === "rp2350-examples") {
+        return resolve(legacyRp2350Root, "validation");
+    }
+    return direct;
+}
+async function findLegacyRp2350Root(sourceRoot) {
+    const direct = resolve(sourceRoot, "RP2350");
+    if (await pathExists(resolve(direct, "pico-sdk", "pico_sdk_init.cmake"))) {
+        return direct;
+    }
+    let entries;
+    try {
+        entries = await readdir(sourceRoot, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const candidate = resolve(sourceRoot, entry.name, "RP2350");
+        if (await pathExists(resolve(candidate, "pico-sdk", "pico_sdk_init.cmake"))) {
+            return candidate;
+        }
+    }
+    return undefined;
 }
-async function downloadToolchainArchive(sourceUrl, installRoot) {
+async function downloadToolchainArchive(sourceUrl, installRoot, expected) {
     const downloadsDir = join(installRoot, "cache", "downloads");
     await mkdir(downloadsDir, { recursive: true });
     const parsed = new URL(sourceUrl);
@@ -454,10 +1578,21 @@ async function downloadToolchainArchive(sourceUrl, installRoot) {
         throw new Error(`Unsupported local toolchain download URL protocol: ${parsed.protocol}`);
     }
     const partialPath = `${outputPath}.part`;
+    const expectedSize = expected?.size_bytes;
     const existingComplete = await fileSize(outputPath);
     const remoteSize = await remoteContentLength(sourceUrl);
-    if (existingComplete > 0 && remoteSize !== undefined && existingComplete === remoteSize) {
-        return outputPath;
+    const targetSize = expectedSize ?? remoteSize;
+    if (existingComplete > 0 && targetSize !== undefined && existingComplete === targetSize) {
+        if (expected?.sha256) {
+            const actual = await sha256(outputPath);
+            if (actual === expected.sha256) {
+                return outputPath;
+            }
+            await rm(outputPath, { force: true });
+        }
+        else {
+            return outputPath;
+        }
     }
     let resumeFrom = await fileSize(partialPath);
     const headers = new Headers();
@@ -479,10 +1614,17 @@ async function downloadToolchainArchive(sourceUrl, installRoot) {
     const writeStream = createWriteStream(partialPath, { flags: resumeFrom > 0 ? "a" : "w" });
     await pipeline(Readable.fromWeb(response.body), writeStream);
     const downloadedSize = await fileSize(partialPath);
-    if (remoteSize !== undefined && downloadedSize !== remoteSize) {
-        throw new Error(`Local toolchain download incomplete: expected ${remoteSize} bytes, got ${downloadedSize} bytes.`);
+    if (targetSize !== undefined && downloadedSize !== targetSize) {
+        throw new Error(`Local toolchain download incomplete: expected ${targetSize} bytes, got ${downloadedSize} bytes.`);
     }
     await rename(partialPath, outputPath);
+    if (expected?.sha256) {
+        const actual = await sha256(outputPath);
+        if (actual !== expected.sha256) {
+            await rm(outputPath, { force: true });
+            throw new Error(`Local toolchain download SHA256 mismatch: expected ${expected.sha256}, got ${actual}.`);
+        }
+    }
     return outputPath;
 }
 async function remoteContentLength(sourceUrl) {
@@ -510,6 +1652,9 @@ async function fileSize(filePath) {
         return 0;
     }
 }
+function safeFileToken(value) {
+    return value.replace(/[^a-zA-Z0-9_.-]+/g, "_") || "mirror";
+}
 async function findReleaseRoot(extractRoot) {
     if (await pathExists(join(extractRoot, "toolchain"))) {
         return extractRoot;