@typecad/cuttlefish 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/cli.js

@@ -2,18 +2,20 @@
 import path from "node:path";
 import fs from "node:fs";
 import { parseCommandLine, printHelp } from "./utils/cli.js";
-import { scaffoldProject, printInitNextSteps, KNOWN_TARGETS, frameworksForTarget, frameworkCatalogEntry, FRAMEWORK_CATALOG, frameworkTargetProfile } from "./create/index.js";
+import { runLibraryCommand } from "./library/cli.js";
+import { scaffoldProject, printCreateNextSteps, KNOWN_TARGETS, frameworksForTarget, frameworkCatalogEntry, FRAMEWORK_CATALOG, frameworkTargetProfile, probeMethodsForBoard } from "./create/index.js";
+import { findPackBoard, packBoardAsTarget } from "./create/pack-targets.js";
+import { activeBoardCatalog, assertZephyrSdkForCreate, formatZephyrSdkFound, ensureFreshBoardCatalog, resetBoardCatalogOverlayCache, sdkFingerprint, PINNED_ZEPHYR_MANIFEST_REV } from "./board-catalog/index.js";
 import { generateFrameworkDebugArtifacts } from "./create/debug-artifacts.js";
-import { runInitWizard } from "./create/index.js";
+import { runCreateWizard } from "./create/index.js";
 import { installProjectDependencies } from "./create/install-deps.js";
-import { generateLibraryDefinitions, transpileFile } from "./transpile.js";
-import { generateDecl, generateDeclsForDirectory, generateComponentDeclsForProject } from "./libdef/cpp-to-decl.js";
-import { mapCppLocationToTs, readSourceMap, resolveMapPath } from "./mapping/source-map.js";
+import { transpileFile } from "./transpile.js";
+import { generateDecl, generateDeclsForDirectory } from "./libdef/cpp-to-decl.js";
 import { compileSource, uploadFirmware, monitorDevice } from "./platform/toolchain.js";
 import { resolveStrategy } from "./platform/registry.js";
 import { loadFrameworkPackage } from "./framework-package.js";
 import { getLoadedFramework, hasLoadedFramework } from "./framework-registry.js";
-import { loadCuttlefishConfig, generateVirtualTypeDeclaration } from "./config-loader.js";
+import { loadCuttlefishConfig, generateVirtualTypeDeclaration, regenBoardModule } from "./config-loader.js";
 import { generateContractBoard } from "./contract/index.js";
 import { requireUIHook, hasUIHook } from "./ui-hook.js";
 import { loadUIEngine } from "./ui/ui-bridge.js";
@@ -35,38 +37,67 @@ function displayConfigForTranspile(config) {
     }
     return display;
 }
-/**
- * Apply the PSRAM config to the Arduino build: append the `PSRAM={opi|quad}`
- * menu option to the FQBN (so the Arduino core's psramFound()/ps_malloc work
- * at runtime — they're gated on the board menu option, not just the define)
- * and add `-DBOARD_HAS_PSRAM` to the defines (so the framework's PSRAM canvas
- * allocator is compiled in). No-op when psram is unset or the target isn't an
- * Arduino FQBN (the PSRAM= option is Arduino-core-specific).
- */
-function applyPsramToArduinoBuild(buildTarget, defines, psram) {
-    if (!psram || !buildTarget || !buildTarget.includes(':')) {
-        return { buildTarget, defines: defines ?? {} };
-    }
-    // Arduino FQBN config options follow the board:option as `key=value` pairs.
-    // Append PSRAM= if not already present (don't clobber an explicit override).
-    const psramOpt = `PSRAM=${psram}`;
-    const adjustedTarget = buildTarget.includes('PSRAM=') ? buildTarget : `${buildTarget}:${psramOpt}`;
-    const adjustedDefines = { ...(defines ?? {}) };
-    if (!('BOARD_HAS_PSRAM' in adjustedDefines))
-        adjustedDefines.BOARD_HAS_PSRAM = '';
-    return { buildTarget: adjustedTarget, defines: adjustedDefines };
-}
 async function handleCreate(options) {
     const targetId = options.target ?? options.board;
     const hasTarget = !!targetId;
-    if (hasTarget) {
-        const target = KNOWN_TARGETS.find(t => t.id === targetId);
+    // SDK gate: the installed Zephyr SDK is the source of truth — boards, pin
+    // data, everything derives from it. No SDK (or a wrong-version one) means
+    // the project cannot work; fail with the fix instead of scaffolding junk.
+    // Native-desktop projects are the one exception (no Zephyr involved).
+    const wantsNative = options.framework === "native" || (!options.framework && targetId === "native");
+    if (!wantsNative) {
+        // The gate doubles as the lookup — its ok-return carries everything the
+        // printout needs (no second discovery pass).
+        const sdk = assertZephyrSdkForCreate();
+        if (sdk) {
+            console.log(chalk.gray('  Zephyr SDK:'));
+            for (const line of formatZephyrSdkFound(sdk))
+                console.log(chalk.gray(line));
+        }
+        // Build/refresh the board registry from the installed SDK now — the
+        // wizard's board list and --board resolution below read it.
+        ensureFreshBoardCatalog();
+        resetBoardCatalogOverlayCache();
+    }
+    // Preseeded targets run non-interactively ONLY when stdin is not a TTY
+    // (scripts/CI pipe nothing and expect zero prompts). A human typing
+    // `cuttlefish create x --board <target>` still gets the wizard — it
+    // prints the preseeded answers and asks only what was not specified
+    // (probe method, serial port, baud, starter).
+    const interactive = process.stdin.isTTY === true;
+    if (hasTarget && !interactive) {
+        // Target resolution: --target/--board names the native target or any
+        // board from the catalog (a qualified target like
+        // 'nucleo_f411re/stm32f411xe', or a bare board id).
+        let target = KNOWN_TARGETS.find(t => t.id === targetId)
+            ?? (() => {
+                const pack = findPackBoard(targetId);
+                return pack ? packBoardAsTarget(pack) : undefined;
+            })();
         if (!target) {
-            const available = KNOWN_TARGETS.map(t => `  - ${t.id} (${t.displayName})`).join("\n");
-            throw new Error(`Unknown target '${targetId}'. Available targets:\n${available}`);
-        }
-        // Resolve the framework. --framework wins; otherwise narrow via the catalog
-        // for the chosen board and auto-pick when exactly one is compatible.
+            // No catalog on this machine (or a typo). A QUALIFIED target passes
+            // through raw: the first build syncs the catalog from the Zephyr tree
+            // and validates it there, where the real error is actionable.
+            if (targetId.includes("/")) {
+                target = packBoardAsTarget({
+                    identifier: targetId,
+                    name: targetId,
+                    soc: targetId.split("/")[1] ?? "",
+                });
+            }
+            else {
+                const known = KNOWN_TARGETS.map(t => `  - ${t.id} (${t.displayName})`);
+                throw new Error(`Unknown target '${targetId}'. Built-in targets:\n${known.join("\n")}\n` +
+                    `Or pass any board from the catalog (e.g. --board nucleo_f411re/stm32f411xe) —\n` +
+                    `the catalog comes from your Zephyr tree; run \`cuttlefish board sync\` (or the\n` +
+                    `installer) to generate it.`);
+            }
+        }
+        const compatibleFrameworks = frameworksForTarget(target)
+            .filter(f => f.installable);
+        // Resolve the framework. --framework wins (validated against the board's
+        // compatible set); otherwise narrow via the catalog for the chosen board
+        // and auto-pick when exactly one is compatible.
         let frameworkId;
         let frameworkPackage;
         if (options.framework) {
@@ -75,39 +106,62 @@ async function handleCreate(options) {
                 const available = FRAMEWORK_CATALOG.filter(f => f.installable).map(f => f.id).join(", ");
                 throw new Error(`Unknown framework '${options.framework}'. Available: ${available}`);
             }
+            if (!compatibleFrameworks.some(f => f.id === requested.id)) {
+                const list = compatibleFrameworks.map(f => f.id).join(", ");
+                throw new Error(`Framework '${requested.id}' is not compatible with target '${target.id}' (${target.displayName}). ` +
+                    `Compatible frameworks: ${list}`);
+            }
             frameworkId = requested.id;
             frameworkPackage = requested.packageName;
         }
         else {
-            const compatible = frameworksForTarget(target).filter(f => f.installable);
-            if (compatible.length === 1) {
-                frameworkId = compatible[0].id;
-                frameworkPackage = compatible[0].packageName;
+            if (compatibleFrameworks.length === 1) {
+                frameworkId = compatibleFrameworks[0].id;
+                frameworkPackage = compatibleFrameworks[0].packageName;
             }
             else {
-                const list = compatible.map(f => f.id).join(", ");
+                const list = compatibleFrameworks.map(f => f.id).join(", ");
                 throw new Error(`Target '${target.id}' is compatible with multiple frameworks (${list}). ` +
                     `Pass --framework <id> to choose one.`);
             }
         }
+        // Probe methods (Zephyr boards whose packages ship a table). An explicit
+        // --probe id is validated against the catalog so a typo fails at create
+        // time, not at the first upload.
+        const probeMethods = frameworkId === 'zephyr' ? probeMethodsForBoard(target.id) : [];
+        if (options.probe && probeMethods.length > 0 && !probeMethods.some(m => m.id === options.probe)) {
+            const list = probeMethods.map(m => `${m.id} (${m.description})`).join('; ');
+            throw new Error(`Unknown probe method '${options.probe}' for ${target.displayName}. Supported: ${list}.`);
+        }
         const projectName = options.projectName || 'my-project';
-        // Framework-specific build target + toolchain (Zephyr board id + 'west' vs
-        // the Arduino FQBN + 'arduino-cli').
+        // Framework-specific build target + toolchain (Zephyr board id + 'west').
         const profile = frameworkTargetProfile(target, frameworkId);
+        const buildTarget = profile.buildTarget ?? target.buildTarget;
         const result = scaffoldProject({
+            probeMethod: options.probe,
+            probeMethods,
             projectName,
             targetId: target.id,
             targetDisplayName: target.displayName,
             isNative: target.isNative,
             architecture: target.architecture,
-            boardPackage: target.boardPackage,
+            board: target.board,
+            // Pack fact: does the board's devicetree declare an LED? Drives the
+            // starter between LED-blink and console-heartbeat (384 of 1,248 pack
+            // boards ship no gpio-leds node).
+            ...(target.board ? { hasLed: Boolean(activeBoardCatalog()[target.board]?.led) } : {}),
             frameworkPackage,
             framework: frameworkId,
-            buildTarget: profile.buildTarget ?? target.buildTarget,
+            buildTarget,
             ...(profile.toolchainType ? { toolchainType: profile.toolchainType } : {}),
-            mcu: target.mcu,
-            baudRate: target.isNative ? undefined : (options.baud ?? 9600),
-            includeSketch: !options.noSketch,
+            // soc rides the config only for bare-silicon/contract projects — a
+            // board target's soc derives from the identifier at boardgen time.
+            ...(target.board ? {} : { soc: target.soc }),
+            // Zephyr consoles default 115200; the 9600 default is the Arduino-class
+            // convention.
+            baudRate: target.isNative ? undefined : (options.baud ?? (frameworkId === 'zephyr' ? 115200 : 9600)),
+            includeStarter: !options.noStarter,
+            ...(options.port ? { port: options.port } : {}),
             ...(target.frameworkData
                 ? { frameworkData: target.frameworkData }
                 : {}),
@@ -115,12 +169,14 @@ async function handleCreate(options) {
         finalizeCreate(result, options);
     }
     else {
-        const wizardResult = await runInitWizard({
+        const wizardResult = await runCreateWizard({
             projectName: options.projectName,
-            board: options.board,
+            board: options.board ?? options.target,
             framework: options.framework,
             baud: options.baud,
-            noSketch: options.noSketch,
+            noStarter: options.noStarter,
+            probe: options.probe,
+            port: options.port,
         });
         if (!wizardResult) {
             console.log(chalk.yellow("Project setup cancelled."));
@@ -170,23 +226,7 @@ function finalizeCreate(result, options) {
     if (debugArtifacts.length > 0) {
         console.log(`\n${chalk.green("✓")} Debug profile: ${debugArtifacts.map((f) => chalk.white(f)).join(", ")}`);
     }
-    printInitNextSteps(result.options, result.outDir, { installed, debugProfile: debugArtifacts.length > 0 });
-}
-async function handleBoardAdd(options) {
-    const { scaffoldBoardPackages, parseBoardSpec, generateFrameworkChecklist } = await import("./create/index.js");
-    if (!fs.existsSync(options.specPath)) {
-        throw new Error(`Spec file not found: ${options.specPath}`);
-    }
-    console.log(`Reading spec: ${options.specPath}`);
-    const specText = fs.readFileSync(options.specPath, "utf8");
-    const spec = parseBoardSpec(specText);
-    console.log(`Generating board packages for ${spec.architecture} (${spec.boardName})...`);
-    const result = scaffoldBoardPackages(spec, { force: options.force });
-    console.log(`\nCreated ${result.createdFiles.length} files:`);
-    for (const f of result.createdFiles) {
-        console.log(`  ${path.relative(process.cwd(), f)}`);
-    }
-    console.log(generateFrameworkChecklist(spec));
+    printCreateNextSteps(result.options, result.outDir, { installed, debugProfile: debugArtifacts.length > 0 });
 }
 async function main() {
     try {
@@ -199,8 +239,8 @@ async function main() {
             await handleCreate(options);
             return;
         }
-        if (options.command === "board-add") {
-            await handleBoardAdd(options);
+        if (options.command === "library") {
+            await runLibraryCommand(options);
             return;
         }
         if (options.command === "preview") {
@@ -210,31 +250,6 @@ async function main() {
             });
             return;
         }
-        if (options.command === "map-error") {
-            if (!options.mapFile || !options.cppLine || !options.cppColumn) {
-                throw new Error("map-error requires map file and C++ line/column options.");
-            }
-            const mapPath = resolveMapPath(options.mapFile);
-            const sourceMap = readSourceMap(mapPath);
-            const mapped = mapCppLocationToTs(sourceMap, options.cppLine, options.cppColumn, options.message, options.cppFile);
-            if (!mapped.mappedTsSpan) {
-                console.log("No TypeScript mapping found for the provided C++ location.");
-            }
-            else {
-                console.log([
-                    `Mapped TS location: ${mapped.mappedTsSpan.filePath}`,
-                    `(${mapped.mappedTsSpan.startLine},${mapped.mappedTsSpan.startColumn})`,
-                    `node=${mapped.nodeKind ?? "unknown"}`,
-                    mapped.symbolName ? `symbol=${mapped.symbolName}` : undefined,
-                ]
-                    .filter(Boolean)
-                    .join(" "));
-            }
-            if (mapped.message) {
-                console.log(`Compiler message: ${mapped.message}`);
-            }
-            return;
-        }
         if (options.command === "doctor" || options.command === "licenses") {
             // These commands run standalone (often before a build), so the framework
             // isn't loaded yet. Load it from the config's framework field so the
@@ -267,6 +282,74 @@ async function main() {
             fw.licenses(options.strict ?? false, options.all ?? false);
             return;
         }
+        // ── Handle board catalog sync / board module regen ────────────────────
+        if (options.command === "board") {
+            const config = loadCuttlefishConfig(process.cwd());
+            if (!config) {
+                throw new Error("No cuttlefish.config.ts found in current directory.\n" +
+                    "Run 'cuttlefish create' to create one.");
+            }
+            // The framework owns the board catalog + module generation; load it
+            // the same way the doctor command does.
+            if (!hasLoadedFramework() && config.framework) {
+                try {
+                    loadFrameworkPackage(config.framework, process.cwd());
+                }
+                catch {
+                    // Framework package not resolvable — the hook error below names
+                    // the problem better than a loader crash would.
+                }
+            }
+            const strategy = hasLoadedFramework()
+                ? getLoadedFramework().strategy
+                : undefined;
+            if (options.subcommand === "sync") {
+                if (typeof strategy?.syncBoardCatalog !== "function") {
+                    throw new Error(`Framework '${config.framework ?? "(none)"}' provides no board catalog sync — ` +
+                        `'cuttlefish board sync' applies to Zephyr-framework projects.`);
+                }
+                const report = strategy.syncBoardCatalog(options.zephyrBase);
+                const version = report.provenance.version || "unknown version";
+                const head = report.provenance.gitHead ? ` @ ${report.provenance.gitHead.slice(0, 12)}` : "";
+                const fp = sdkFingerprint(report.zephyrBase);
+                ui.printSuccess(`Board catalog synced from Zephyr ${version}${head}`);
+                console.log(chalk.gray(`  tree:     ${report.zephyrBase}`));
+                if (fp)
+                    console.log(chalk.gray(`  fingerprint: ${fp} (pin ${PINNED_ZEPHYR_MANIFEST_REV})`));
+                console.log(chalk.gray(`  catalog:  ${report.overlayPath}`));
+                console.log(`  ${report.stats.variants} board variants (${report.stats.withFacts} with pin facts` +
+                    `${report.stats.failures > 0 ? `, ${report.stats.failures} reader failures` : ""}` +
+                    `${report.stats.droppedYamls > 0 ? `, ${report.stats.droppedYamls} yamls with no resolvable .dts` : ""})`);
+                const { added, changed, removed } = report;
+                const list = (ids, verb) => ids.length === 0
+                    ? chalk.gray(`  0 ${verb}`)
+                    : `  ${ids.length} ${verb}: ${ids.slice(0, 8).join(", ")}${ids.length > 8 ? ", …" : ""}`;
+                console.log(chalk.gray("  vs the previous catalog (what changed in your tree):"));
+                console.log(list(added, "added"));
+                console.log(list(changed, "changed"));
+                console.log(list(removed, "removed"));
+                // Refresh the project's own board module so the sync lands in this
+                // project immediately (not just on the next first-build).
+                if (config.board && !config.contract) {
+                    const dir = regenBoardModule(config);
+                    ui.printSuccess(`Regenerated the board module for '${config.board}' in ${path.join(dir, "board.ts")}`);
+                }
+                return;
+            }
+            // regen: refresh a stale catalog overlay first, so a regen after
+            // `west update` picks up the tree's boards automatically. Best-effort
+            // — a missing tree or a failed walk must not block regenerating from
+            // whatever catalog is already present.
+            try {
+                strategy?.ensureFreshBoardCatalog?.();
+            }
+            catch {
+                // Non-fatal by design (see above).
+            }
+            const dir = regenBoardModule(config);
+            ui.printSuccess(`Regenerated the board module for '${config.board}' in ${path.join(dir, "board.ts")}`);
+            return;
+        }
         // ── Handle build command — entry point comes from config ──────────
         if (options.command === "build") {
             const buildConfig = loadCuttlefishConfig(process.cwd());
@@ -276,7 +359,7 @@ async function main() {
             }
             if (!buildConfig.entry) {
                 throw new Error("cuttlefish.config.ts has no 'entry' field.\n" +
-                    "Add: entry: './src/sketch.ts'");
+                    "Add: entry: './src/main.ts'");
             }
             const entryFile = path.resolve(path.dirname(buildConfig.configPath), buildConfig.entry);
             if (!fs.existsSync(entryFile)) {
@@ -297,37 +380,6 @@ async function main() {
         // it intentionally has no inputFile (it scans scanDir instead), so the
         // generic "Missing input file path" check would otherwise block it.
         if (options.command === "gen-decls") {
-            // Check for --components flag (ESP-IDF components: managed + local).
-            // Runs before scanDir/single-file branches; components mode has no
-            // inputFile by design (it scans managed_components/ + components/).
-            const componentsDir = options.componentsDir;
-            if (componentsDir) {
-                ui.printHeader();
-                ui.printStep(`Generating component declarations for ${componentsDir}...`);
-                const config = loadCuttlefishConfig(componentsDir);
-                const frameworkConfig = (config?.frameworkConfig ?? {});
-                const componentsNode = frameworkConfig?.components ?? {};
-                const managedSpecs = Object.keys(componentsNode.managed ?? {});
-                // idf.py stores managed deps as <namespace>__<name> (slashes → __).
-                const managedNames = managedSpecs.map((spec) => spec.replace("/", "__"));
-                const localPaths = (componentsNode.local ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(componentsDir, p));
-                const builtinNames = componentsNode.builtin ?? [];
-                const created = generateComponentDeclsForProject(componentsDir, {
-                    managed: managedNames,
-                    local: localPaths,
-                    builtin: [],
-                    idfRoot: undefined,
-                });
-                if (created.length === 0) {
-                    ui.printInfo("No component declaration files created.");
-                }
-                else {
-                    ui.printSuccess(`Created ${created.length} declaration file(s):`);
-                    for (const f of created)
-                        ui.printFileCreated(f);
-                }
-                return;
-            }
             // Check for --all flag (scan directory)
             const scanDir = options.scanDir;
             if (scanDir) {
@@ -368,9 +420,9 @@ async function main() {
             if (options.expect) {
                 const config = loadCuttlefishConfig(process.cwd());
                 const exitCode = runExpectTests({
-                    port: options.port ?? config?.console?.port,
+                    port: options.port,
                     buildTarget: config?.buildTarget,
-                    baud: config?.console?.baudRate ?? options.baud,
+                    baud: options.baud,
                     expectFile: options.expectFile,
                 });
                 process.exitCode = exitCode;
@@ -379,23 +431,6 @@ async function main() {
             throw new Error("Missing input file path.");
         }
         assertTypeScriptInput(options.inputFile);
-        if (options.command === "gen-libdefs") {
-            const outDir = path.dirname(options.inputFile);
-            const created = generateLibraryDefinitions({
-                inputFile: options.inputFile,
-                outDir,
-            });
-            if (created.length === 0) {
-                console.log("No new library definition files created.");
-            }
-            else {
-                console.log("Created library definition files:");
-                for (const filePath of created) {
-                    console.log(`- ${filePath}`);
-                }
-            }
-            return;
-        }
         // ── Load cuttlefish.config.ts (config wins over CLI flags) ──────────
         const inputDir = path.dirname(path.resolve(options.inputFile));
         const config = loadCuttlefishConfig(inputDir);
@@ -408,42 +443,6 @@ async function main() {
         if (config?.contract) {
             await generateContractBoard(config);
         }
-        // ── Pre-transpile: generate component .d.ts stubs ───────────────────
-        // The transpile type-check needs the .d.ts imports in main.ts to resolve.
-        // For ESP-IDF builtin/managed/local components, those .d.ts files are
-        // generated by gen-decls — so we must run it BEFORE type-checking, not
-        // only as part of --compile. The cache is written under the transpile
-        // output dir (the same path --compile uses), so user imports resolve
-        // identically in both flows.
-        if (config?.frameworkConfig) {
-            const fc = config.frameworkConfig;
-            const componentsNode = fc?.components ?? {};
-            const managedSpecs = Object.keys(componentsNode.managed ?? {});
-            const localPaths = (componentsNode.local ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(inputDir, p));
-            const builtinNames = componentsNode.builtin ?? [];
-            if (managedSpecs.length > 0 || localPaths.length > 0 || builtinNames.length > 0) {
-                // Resolve the transpile output dir — the cache lives under it so the
-                // framework's compile path and this pre-transpile pass agree on location.
-                // output.outDir in config is relative to the project root (inputDir);
-                // if absent, the transpile output goes alongside the entry file.
-                const outBase = config.outputOutDir
-                    ? path.resolve(inputDir, config.outputOutDir)
-                    : inputDir;
-                try {
-                    generateComponentDeclsForProject(outBase, {
-                        managed: managedSpecs.map((s) => s.replace('/', '__')),
-                        local: localPaths,
-                        builtin: [],
-                        idfRoot: undefined,
-                    });
-                }
-                catch {
-                    // Non-fatal: if gen-decls fails (e.g. component not yet fetched),
-                    // the type-checker will surface the missing-import errors with
-                    // clearer context than crashing here.
-                }
-            }
-        }
         // Load the UI engine (if @typecad/ui is installed) before any UI work.
         await loadUIEngine();
         // Load the safety engine (if @typecad/safety is installed) before any
@@ -452,9 +451,8 @@ async function main() {
         let effectivePlatformContext = options.platformContext;
         let effectiveTarget = options.target;
         let effectiveOutDir = options.outDir;
-        let effectiveBoardPackage = options.boardPackage;
+        let effectiveBoardTarget = options.boardTarget;
         let effectiveFrameworkPackage = options.frameworkPackage;
-        let effectiveMcuPackage;
         let effectivePort = options.port;
         // CUTTLEFISH_PORT env var sits between the CLI flag and the config file
         // (flag > env > config), so cross-platform uploads don't need a
@@ -463,15 +461,8 @@ async function main() {
             effectivePort = process.env.CUTTLEFISH_PORT;
         }
         if (config) {
-            if (config.mcu) {
-                effectiveMcuPackage = config.mcu;
-            }
-            // Config port is the default; CLI --port flag overrides it.
-            if (!effectivePort && config.console?.port) {
-                effectivePort = config.console.port;
-            }
-            if (config.board || config.mcu) {
-                effectiveBoardPackage = config.board || config.mcu;
+            if (config.board) {
+                effectiveBoardTarget = config.board;
             }
             let configBuildTarget = config.buildTarget;
             if (configBuildTarget) {
@@ -482,7 +473,7 @@ async function main() {
                     frameworkData: {
                         buildTarget: configBuildTarget,
                         // Thread the PSRAM type through to the framework so it can emit the
-                        // PSRAM-enabling Kconfig (Zephyr) / define + FQBN option (Arduino).
+                        // PSRAM-enabling Kconfig + BOARD_HAS_PSRAM compile definition.
                         ...(config.psram ? { psram: config.psram } : {}),
                     },
                 };
@@ -493,24 +484,6 @@ async function main() {
             if (config.framework) {
                 effectiveFrameworkPackage = config.framework;
             }
-            if (config.target) {
-                if (effectiveFrameworkPackage) {
-                    try {
-                        loadFrameworkPackage(effectiveFrameworkPackage, inputDir);
-                        if (hasLoadedFramework()) {
-                            effectiveTarget = getLoadedFramework().strategy.id;
-                        }
-                    }
-                    catch {
-                        // Framework not loadable — keep the CLI-provided target
-                    }
-                }
-            }
-            // Pass console baud rate to platform context
-            if (config.console?.baudRate) {
-                effectivePlatformContext = effectivePlatformContext || {};
-                effectivePlatformContext.console = { baudRate: config.console.baudRate };
-            }
             // Keep cuttlefish-env.d.ts in sync so the TS language server can resolve
             // '@typecad/board' imports in editor without a linter error.
             // Platform-specific declarations come from the strategy if available.
@@ -536,8 +509,7 @@ async function main() {
         ui.printHeader();
         ui.printBuildInfo({
             framework: effectiveFrameworkPackage,
-            mcu: effectiveMcuPackage,
-            board: effectiveBoardPackage,
+            board: effectiveBoardTarget,
             buildTarget: effectivePlatformContext?.frameworkData?.buildTarget,
         });
         // ── Watch mode ────────────────────────────────────────────────────────
@@ -555,7 +527,7 @@ async function main() {
                     emitMaps: options.emitMaps,
                     platformContext: effectivePlatformContext,
                     treeShaking: options.treeShaking,
-                    boardPackage: effectiveBoardPackage,
+                    boardTarget: effectiveBoardTarget,
                     frameworkPackage: effectiveFrameworkPackage,
                     debug: options.debug,
                     force: options.force,
@@ -577,28 +549,29 @@ async function main() {
                     // Initial compile + upload if flags are set
                     if (options.compile) {
                         const baseBuildTarget = effectivePlatformContext?.frameworkData?.buildTarget ?? options.platformContext?.frameworkData?.buildTarget;
-                        const { buildTarget, defines: psramDefines } = applyPsramToArduinoBuild(baseBuildTarget, config?.outputDefines, config?.psram);
                         const watchOpts = {
                             outputDir: path.dirname(result.sourcePath),
                             sourcePath: result.sourcePath,
-                            buildTarget,
+                            buildTarget: baseBuildTarget,
                             port: effectivePort,
-                            baud: options.baud ?? config?.console?.baudRate,
+                            baud: options.baud,
                             extraFlags: config?.outputExtraFlags,
-                            defines: psramDefines,
+                            defines: config?.outputDefines ?? {},
                             psram: config?.psram,
                             frameworkConfig: config?.frameworkConfig,
                             zephyrConfig: config?.zephyrConfig,
                             display: displayConfigForTranspile(config),
                             debug: options.debug,
                         };
-                        ui.printCompiling(buildTarget ?? "native");
+                        ui.printCompiling(baseBuildTarget ?? "native");
                         const compileResult = compileSource(watchOpts);
                         printMappedCompileErrors(compileResult, result.sourceMapPath, result.sourcePath, path.dirname(result.sourcePath));
                         if (compileResult.success) {
                             if (compileResult.memoryUsage)
                                 ui.printMemoryUsage(compileResult.memoryUsage);
-                            if (options.upload && effectivePort) {
+                            if (options.upload) {
+                                // No port gate here — probe/USB flashing needs none, and the
+                                // framework reports a friendly failure when the runner does.
                                 ui.printUploading(effectivePort);
                                 const uploadResult = uploadFirmware(watchOpts);
                                 if (uploadResult.output)
@@ -633,7 +606,7 @@ async function main() {
                     process.stdout.write("\x1Bc");
                     const timestamp = new Date().toLocaleTimeString();
                     const relativePath = path.relative(process.cwd(), changedFile);
-                    console.log(chalk.cyan(`⤳ Cuttlefish`) + chalk.gray(` v0.1.0`));
+                    console.log(chalk.cyan(`⤳ Cuttlefish`) + chalk.gray(` v${ui.VERSION}`));
                     console.log();
                     ui.printInfo(`[${timestamp}] Change detected: ${relativePath}`);
                     console.log();
@@ -654,7 +627,7 @@ async function main() {
                             emitMaps: options.emitMaps,
                             platformContext: effectivePlatformContext,
                             treeShaking: options.treeShaking,
-                            boardPackage: effectiveBoardPackage,
+                            boardTarget: effectiveBoardTarget,
                             frameworkPackage: effectiveFrameworkPackage,
                             debug: options.debug,
                             force: true, // Always force in watch mode to bypass stale cache
@@ -677,28 +650,30 @@ async function main() {
                             ui.printSuccess();
                             if (options.compile) {
                                 const baseBuildTarget = effectivePlatformContext?.frameworkData?.buildTarget ?? options.platformContext?.frameworkData?.buildTarget;
-                                const { buildTarget, defines: psramDefines } = applyPsramToArduinoBuild(baseBuildTarget, config?.outputDefines, config?.psram);
                                 const rebuildOpts = {
                                     outputDir: path.dirname(rebuildResult.sourcePath),
                                     sourcePath: rebuildResult.sourcePath,
-                                    buildTarget,
+                                    buildTarget: baseBuildTarget,
                                     port: effectivePort,
-                                    baud: options.baud ?? config?.console?.baudRate,
+                                    baud: options.baud,
                                     extraFlags: config?.outputExtraFlags,
-                                    defines: psramDefines,
+                                    defines: config?.outputDefines ?? {},
                                     psram: config?.psram,
                                     frameworkConfig: config?.frameworkConfig,
                                     zephyrConfig: config?.zephyrConfig,
                                     display: displayConfigForTranspile(config),
                                     debug: options.debug,
                                 };
-                                ui.printCompiling(buildTarget ?? "native");
+                                ui.printCompiling(baseBuildTarget ?? "native");
                                 const compileResult = compileSource(rebuildOpts);
                                 printMappedCompileErrors(compileResult, rebuildResult.sourceMapPath, rebuildResult.sourcePath, path.dirname(rebuildResult.sourcePath));
                                 if (compileResult.success) {
                                     if (compileResult.memoryUsage)
                                         ui.printMemoryUsage(compileResult.memoryUsage);
-                                    if (options.upload && effectivePort) {
+                                    if (options.upload) {
+                                        // No port gate here — probe/USB flashing needs none, and
+                                        // the framework reports a friendly failure when the
+                                        // runner does.
                                         ui.printUploading(effectivePort);
                                         const uploadResult = uploadFirmware(rebuildOpts);
                                         if (uploadResult.output)
@@ -747,7 +722,7 @@ async function main() {
                 emitMaps: options.emitMaps,
                 platformContext: effectivePlatformContext,
                 treeShaking: options.treeShaking,
-                boardPackage: effectiveBoardPackage,
+                boardTarget: effectiveBoardTarget,
                 frameworkPackage: effectiveFrameworkPackage,
                 debug: options.debug,
                 force: options.force,
@@ -775,7 +750,7 @@ async function main() {
                 const exitCode = runExpectTests({
                     port: effectivePort,
                     buildTarget: effectivePlatformContext?.frameworkData?.buildTarget ?? options.platformContext?.frameworkData?.buildTarget,
-                    baud: config?.console?.baudRate ?? options.baud,
+                    baud: options.baud,
                     expectFile: options.expectFile,
                 });
                 process.exitCode = exitCode;
@@ -784,22 +759,24 @@ async function main() {
         }
         // --compile (delegates to the active framework's toolchain)
         const baseBuildTarget = effectivePlatformContext?.frameworkData?.buildTarget ?? options.platformContext?.frameworkData?.buildTarget;
-        const { buildTarget, defines: psramDefines } = applyPsramToArduinoBuild(baseBuildTarget, config?.outputDefines, config?.psram);
         const toolchainOpts = {
             outputDir: path.dirname(result.sourcePath),
             sourcePath: result.sourcePath,
-            buildTarget,
+            buildTarget: baseBuildTarget,
             port: effectivePort,
-            baud: options.baud ?? config?.console?.baudRate,
+            baud: options.baud,
             extraFlags: config?.outputExtraFlags,
-            defines: psramDefines,
+            defines: config?.outputDefines ?? {},
             psram: config?.psram,
             frameworkConfig: config?.frameworkConfig,
-            zephyrConfig: config?.zephyrConfig,
+            // --probe <method> overrides zephyr.probe from the config for this run.
+            zephyrConfig: options.probe
+                ? { ...(config?.zephyrConfig ?? {}), probe: options.probe }
+                : config?.zephyrConfig,
             display: displayConfigForTranspile(config),
             debug: options.debug,
         };
-        ui.printCompiling(buildTarget ?? "native");
+        ui.printCompiling(baseBuildTarget ?? "native");
         let compileResult;
         try {
             compileResult = compileSource(toolchainOpts);
@@ -829,10 +806,11 @@ async function main() {
             ui.printSuccess();
             return;
         }
-        // --upload (requires a port from --port flag or config.console.port)
-        if (!effectivePort) {
-            throw new Error("--upload requires a port. Set --port <port> on the command line or console.port in cuttlefish.config.ts.");
-        }
+        // --upload. Whether a port is required is the active framework's call —
+        // probe-based flashing (openocd/jlink) and USB bootloaders (dfu-util,
+        // uf2) need no serial port, so a missing --port only surfaces as the
+        // framework's own upload failure for serial-port runners (esptool,
+        // bossac).
         const port = effectivePort;
         ui.printUploading(port);
         const uploadResult = uploadFirmware(toolchainOpts);
@@ -848,9 +826,14 @@ async function main() {
             return;
         }
         if (options.monitor) {
-            // --monitor (blocks until Ctrl+C). Show the resolved baud (config ?? --baud)
-            // in the banner — toolchainOpts.baud is built the same way, so what the
-            // user sees is what the framework monitor opens the port at.
+            // --monitor (blocks until Ctrl+C). Unlike flashing, monitoring always
+            // needs a serial port — there is no probe/USB flavor of it.
+            if (!port) {
+                throw new Error("--monitor requires a port. Set --port <port> on the command line (or the CUTTLEFISH_PORT env var).");
+            }
+            // Show the resolved --baud in the banner — toolchainOpts.baud is built
+            // the same way, so what the user sees is what the framework monitor
+            // opens the port at.
             ui.printMonitoring(port, toolchainOpts.baud ?? 115200);
             monitorDevice(toolchainOpts);
             return;
@@ -860,8 +843,8 @@ async function main() {
             ui.printSuccess();
             const exitCode = runExpectTests({
                 port: effectivePort,
-                buildTarget,
-                baud: config?.console?.baudRate ?? options.baud,
+                buildTarget: baseBuildTarget,
+                baud: options.baud,
                 expectFile: options.expectFile,
             });
             process.exitCode = exitCode;