@kvell007/embed-labs-cli 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/local-toolchain.js

@@ -1,27 +1,369 @@
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
-import { constants } from "node:fs";
-import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { arch, platform } from "node:os";
+import { constants, createWriteStream } from "node:fs";
+import { access, cp, mkdir, mkdtemp, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { arch, homedir, platform, tmpdir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
+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 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.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: "" }
+    ]
+};
+const BUILT_IN_MANIFESTS = {
+    "embedlabs.tools.vendor.rockchip": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.tools.vendor.rockchip",
+        version: "1.0.0",
+        kind: "tools",
+        hosts: ["darwin-arm64", "linux-x86_64"],
+        provides: ["rockchip.mkimage", "rockchip.dumpimage", "rockchip.resource_tool", "rockchip.rkdeveloptool"]
+    },
+    "embedlabs.tools.common.llvm": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.tools.common.llvm",
+        version: "22.1.3",
+        kind: "tools",
+        hosts: ["darwin-arm64", "linux-x86_64"],
+        provides: ["llvm.clang", "llvm.clangxx", "llvm.ld_lld", "llvm.ar", "llvm.objcopy", "llvm.readelf"]
+    },
+    "embedlabs.tools.common.e2fsprogs": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.tools.common.e2fsprogs",
+        version: "1.0.0",
+        kind: "tools",
+        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",
+        version: "1.0.0",
+        kind: "family",
+        family: "rk356x",
+        requires: [
+            { id: "embedlabs.tools.vendor.rockchip", version: "^1.0.0" },
+            { id: "embedlabs.tools.common.llvm", version: "22.x" },
+            { id: "embedlabs.tools.common.e2fsprogs", version: "^1.0.0" }
+        ]
+    },
+    "embedlabs.board.taishanpi.1m-rk3566": {
+        schema: "embedlabs.package.v1",
+        id: "embedlabs.board.taishanpi.1m-rk3566",
+        version: "1.0.31",
+        kind: "board",
+        family: "rk356x",
+        board: "TaishanPi",
+        variant: "1M-RK3566",
+        requires: [
+            { 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.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"]
+    }
+};
+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",
+    "README.md",
+    "meta",
+    "scripts",
+    "support",
+    "third_party"
+];
+const LOCAL_TOOLCHAIN_INSTALL_MODES = ["minimal", "compile", "qt", "full", "images"];
 export function defaultLocalReleaseRoot() {
-    return DEFAULT_RELEASE_ROOT;
+    return process.env.EMBEDLABS_LOCAL_RELEASE_ROOT?.trim()
+        || process.env.EMBEDLABS_RELEASE_ROOT?.trim()
+        || DEFAULT_RELEASE_ROOT;
 }
-export async function validateLocalToolchain(releaseRoot = DEFAULT_RELEASE_ROOT) {
-    const resolvedRoot = resolve(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 latestLocalToolchain(options = {}) {
+    const boardId = options.boardId ?? DEFAULT_BOARD_ID;
+    const channelName = options.channel ?? DEFAULT_CHANNEL;
+    const { channel, manifests, metadataRoot } = await loadLocalToolchainMetadata(options.metadataRoot, channelName);
+    const boardPackageId = boardPackageIdFor(boardId);
+    const board = manifests.get(boardPackageId);
+    if (!board) {
+        throw new Error(`No local toolchain board package found for ${boardId}.`);
+    }
+    const packages = resolvePackageRefs(boardPackageId, channel, manifests);
+    let download;
+    let downloadError;
+    try {
+        download = await resolveLocalToolchainDownloadPlan({
+            boardId,
+            channel: channelName,
+            host: hostId(),
+            toolchain: "llvm"
+        });
+    }
+    catch (error) {
+        downloadError = error instanceof Error ? error.message : String(error);
+    }
+    return {
+        board_id: boardId,
+        channel: channel.channel,
+        host: hostId(),
+        version: download?.version ?? board.version,
+        metadata_root: metadataRoot,
+        packages,
+        download,
+        download_error: downloadError
+    };
+}
+export async function currentLocalToolchain(installRoot, boardId = DEFAULT_BOARD_ID) {
+    const root = resolveInstallRoot(installRoot);
+    const registryPath = localToolchainRegistryPath(root);
+    try {
+        const registry = JSON.parse(await readFile(registryPath, "utf8"));
+        const releaseRoot = typeof registry.release_root === "string" ? registry.release_root : undefined;
+        return {
+            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,
+            channel: typeof registry.channel === "string" ? registry.channel : undefined,
+            packages: Array.isArray(registry.packages) ? registry.packages : undefined
+        };
+    }
+    catch {
+        return {
+            installed: false,
+            board_id: boardId,
+            registry_path: registryPath,
+            install_root: root
+        };
+    }
+}
+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 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 installed = current.installed && normalizeBoardId(current.board_id) === normalizeBoardId(boardId)
+            ? {
+                version: current.version,
+                channel: current.channel,
+                mode: current.mode,
+                release_root: current.release_root
+            }
+            : undefined;
+        const updateAvailable = !!installed?.version && installed.version !== latestVersion;
+        const status = !hostSupport.supported
+            ? "unsupported_host"
+            : updateAvailable
+                ? "update_available"
+                : installed
+                    ? "installed"
+                    : "available";
+        const mode = download?.default_mode ?? "qt";
+        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: hostSupport.supported,
+            unsupported_packages: hostSupport.unsupportedPackages,
+            install_modes: [...LOCAL_TOOLCHAIN_INSTALL_MODES],
+            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({ status, downloadError, unsupportedPackages: hostSupport.unsupportedPackages })
+        });
+    }
+    return {
+        host,
+        channel: channel.channel,
+        metadata_root: metadataRoot,
+        install_root: installRoot,
+        registry_path: registryPath,
+        environments
+    };
+}
+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, mode: installMode });
+        if (!validation.ok) {
+            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
+            };
+        }
+    }
+    const tempDir = await mkdtemp(join(tmpdir(), "embedlabs-local-toolchain-install-"));
+    try {
+        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);
+            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,
+                verbatimSymlinks: true
+            });
+            installedPaths.push(relativePath);
+        }
+        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(", ")}`);
+        }
+        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: sourceRoot.source,
+            installed_paths: installedPaths,
+            packages: latest.packages,
+            validation
+        };
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+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 = requiredLocalToolchainChecks(mode);
     const checked_paths = [];
     for (const [label, relativePath] of required) {
         const absolutePath = resolve(resolvedRoot, relativePath);
@@ -34,23 +376,85 @@ export async function validateLocalToolchain(releaseRoot = DEFAULT_RELEASE_ROOT)
     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()
         },
-        board_id: "taishanpi-1m-rk3566",
+        board_id: DEFAULT_BOARD_ID,
         release_root: resolvedRoot,
         checked_paths,
         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 = resolve(options.releaseRoot ?? DEFAULT_RELEASE_ROOT);
+    const releaseRoot = await resolveLocalReleaseRoot(options.releaseRoot);
     const sourcePath = resolve(options.sourcePath);
     const outputPath = resolve(options.outputPath);
     await access(sourcePath, constants.R_OK);
@@ -77,7 +481,7 @@ export async function compileTaishanPiSingleFile(options) {
 }
 export async function buildTaishanPiQtSmoke(options) {
     assertAuthenticated(options.auth);
-    const releaseRoot = resolve(options.releaseRoot ?? DEFAULT_RELEASE_ROOT);
+    const releaseRoot = await resolveLocalReleaseRoot(options.releaseRoot);
     const sourceDir = resolve(options.sourceDir ?? DEFAULT_QT_SMOKE_SOURCE);
     const buildDir = resolve(options.buildDir);
     const targetName = options.targetName ?? "qt_llvm_smoke";
@@ -104,7 +508,7 @@ export async function buildTaishanPiQtSmoke(options) {
     }
     const artifactPath = join(buildDir, targetName);
     return await localCompileResult({
-        boardId: "taishanpi-1m-rk3566",
+        boardId: DEFAULT_BOARD_ID,
         operation: "local.build.qt_smoke",
         releaseRoot,
         accountId: options.accountId,
@@ -115,6 +519,560 @@ export async function buildTaishanPiQtSmoke(options) {
         commands: [configure, build]
     });
 }
+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) {
+        return {
+            channel: BUILT_IN_CHANNEL,
+            manifests: new Map(Object.entries(BUILT_IN_MANIFESTS)),
+            metadataRoot: undefined
+        };
+    }
+    const root = resolve(candidateRoot);
+    const channelPath = join(root, "channels", channelName, "index.json");
+    const channel = JSON.parse(await readFile(channelPath, "utf8"));
+    if (channel.schema !== "embedlabs.channel.v1") {
+        throw new Error(`Unexpected local toolchain channel schema ${channel.schema}.`);
+    }
+    const manifests = new Map();
+    for (const entry of channel.packages) {
+        const manifestPath = entry.manifest
+            ? resolve(dirname(channelPath), entry.manifest)
+            : join(root, "manifests", entry.id, entry.version, "manifest.json");
+        const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+        if (manifest.schema !== "embedlabs.package.v1") {
+            throw new Error(`Unexpected local toolchain manifest schema for ${entry.id}: ${manifest.schema}.`);
+        }
+        if (manifest.id !== entry.id || manifest.version !== entry.version) {
+            throw new Error(`Local toolchain manifest mismatch for ${entry.id}@${entry.version}.`);
+        }
+        manifests.set(manifest.id, manifest);
+    }
+    return { channel, manifests, metadataRoot: root };
+}
+async function resolveLocalToolchainDownloadPlan(input) {
+    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 entry = (channel.packages ?? []).find((item) => {
+        return item.board_id === input.boardId
+            && item.host === input.host
+            && item.toolchain === input.toolchain
+            && (item.kind === undefined || item.kind === "toolchain-archive" || item.kind === "board-support-archive");
+    });
+    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}.`);
+    }
+    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))
+        && (!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 && components.length === 0) {
+        return undefined;
+    }
+    return {
+        channel_url: channelUrl,
+        manifest_url: manifestUrl,
+        package_id: manifest.id,
+        version: manifest.version,
+        board_id: input.boardId,
+        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 [];
+    }
+    seen.add(packageId);
+    const manifest = manifests.get(packageId);
+    if (!manifest) {
+        throw new Error(`Local toolchain package ${packageId} is not present in the channel.`);
+    }
+    const refs = [];
+    for (const requirement of manifest.requires ?? []) {
+        refs.push(...resolvePackageRefs(requirement.id, channel, manifests, seen));
+    }
+    const channelEntry = channel.packages.find((item) => item.id === packageId);
+    refs.push({
+        id: packageId,
+        version: manifest.version,
+        manifest: channelEntry?.manifest
+    });
+    return refs;
+}
+function boardPackageIdFor(boardId) {
+    if (boardId === DEFAULT_BOARD_ID || boardId === "taishanpi" || boardId === "taishanpi-1m-rk3566") {
+        return "embedlabs.board.taishanpi.1m-rk3566";
+    }
+    if (boardId.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 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 (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 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";
+    }
+    if (platform() === "linux" && arch() === "x64") {
+        return "linux-x86_64";
+    }
+    return `${platform()}-${arch()}`;
+}
+function resolveInstallRoot(installRoot) {
+    return resolve(installRoot
+        || process.env.EMBEDLABS_HOME?.trim()
+        || join(homedir(), ".embedlabs"));
+}
+function localToolchainRegistryPath(installRoot) {
+    return join(installRoot, "registry", "local-toolchains.json");
+}
+async function writeCurrentRegistry(installRoot, latest, releaseRoot, mode, source) {
+    const registryPath = localToolchainRegistryPath(installRoot);
+    await mkdir(dirname(registryPath), { recursive: true });
+    await writeFile(registryPath, `${JSON.stringify({
+        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()
+    }, null, 2)}\n`, "utf8");
+}
+async function resolveLocalReleaseRoot(releaseRoot) {
+    if (releaseRoot?.trim()) {
+        return resolve(releaseRoot);
+    }
+    const envRoot = process.env.EMBEDLABS_LOCAL_RELEASE_ROOT?.trim() || process.env.EMBEDLABS_RELEASE_ROOT?.trim();
+    if (envRoot) {
+        return resolve(envRoot);
+    }
+    const current = await currentLocalToolchain(undefined, DEFAULT_BOARD_ID);
+    if (current.release_root) {
+        return resolve(current.release_root);
+    }
+    return resolve(DEFAULT_RELEASE_ROOT);
+}
+async function sourceReleaseRootForInstall(options, latest, installRoot, tempDir) {
+    if (options.sourceReleaseRoot) {
+        return {
+            path: resolve(options.sourceReleaseRoot),
+            source: { kind: "directory", value: resolve(options.sourceReleaseRoot) }
+        };
+    }
+    if (options.sourceUrl) {
+        const downloadedPath = await downloadToolchainArchive(options.sourceUrl, installRoot);
+        const extractRoot = join(tempDir, "extract");
+        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: 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 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 });
+    const parsed = new URL(sourceUrl);
+    const filename = basename(parsed.pathname) || `local-toolchain-${Date.now()}.tar.gz`;
+    const outputPath = join(downloadsDir, filename);
+    if (parsed.protocol === "file:") {
+        await cp(fileURLToPath(parsed), outputPath, { force: true });
+        return outputPath;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        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);
+    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();
+    if (resumeFrom > 0) {
+        headers.set("range", `bytes=${resumeFrom}-`);
+    }
+    let response = await fetch(sourceUrl, { headers });
+    if (resumeFrom > 0 && response.status !== 206) {
+        await rm(partialPath, { force: true });
+        resumeFrom = 0;
+        response = await fetch(sourceUrl);
+    }
+    if (!response.ok) {
+        throw new Error(`Local toolchain download failed with HTTP ${response.status}: ${sourceUrl}`);
+    }
+    if (!response.body) {
+        throw new Error(`Local toolchain download returned an empty response body: ${sourceUrl}`);
+    }
+    const writeStream = createWriteStream(partialPath, { flags: resumeFrom > 0 ? "a" : "w" });
+    await pipeline(Readable.fromWeb(response.body), writeStream);
+    const downloadedSize = await fileSize(partialPath);
+    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) {
+    try {
+        const response = await fetch(sourceUrl, { method: "HEAD" });
+        if (!response.ok) {
+            return undefined;
+        }
+        const length = response.headers.get("content-length");
+        if (!length) {
+            return undefined;
+        }
+        const parsed = Number.parseInt(length, 10);
+        return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function fileSize(filePath) {
+    try {
+        return (await stat(filePath)).size;
+    }
+    catch {
+        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;
+    }
+    const entries = await readdir(extractRoot);
+    for (const entry of entries) {
+        const candidate = join(extractRoot, entry);
+        try {
+            const info = await stat(candidate);
+            if (info.isDirectory() && await pathExists(join(candidate, "toolchain"))) {
+                return candidate;
+            }
+        }
+        catch {
+            // Ignore entries that disappear during extraction cleanup.
+        }
+    }
+    throw new Error("Downloaded local toolchain archive did not contain a release root with toolchain/.");
+}
 function compilerForSource(releaseRoot, sourcePath) {
     const extension = extname(sourcePath).toLowerCase();
     const binDir = join(releaseRoot, "toolchain", "llvm-cross", "bin");