@typecad/framework-zephyr 1.0.0-alpha.10 → 1.0.0-alpha.9

package/dist/framework.manifest.d.ts

@@ -1,40 +1,40 @@
 declare const _default: {
+    hal: {
+        [x: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        };
+        raw?: unknown;
+    } & {
+        [k: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        };
+    };
+    packageName: string;
     schemaVersion: 1;
     frameworkId: string;
-    packageName: string;
     canonical: boolean;
     displayName: string;
     description: string;
     implementationMode: "from-scratch" | "extends-canonical" | "extends-other";
     entrypoint: {
+        sourceExtension: "cpp" | "ino" | "cc" | "h";
         entrypointFunctionName: string;
         requiresLoopFunction: boolean;
-        sourceExtension: "ino" | "cc" | "cpp" | "h";
         generateHeaderFile: boolean;
         overrideBaseName?: string | undefined;
         outputSubdirectory?: string | undefined;
         customBridgeShim?: string | undefined;
     };
     profile: {
-        targets: string[];
         forcedIncludes: string[];
         symbolAliases: Record<string, string>;
-    };
-    hal: {
-        [x: string]: {
-            supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
-            partialCoverage: boolean;
-            unsupportedReason?: string | undefined;
-        };
-        raw?: unknown;
-    } & {
-        [k: string]: {
-            supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
-            partialCoverage: boolean;
-            unsupportedReason?: string | undefined;
-        };
+        targets: string[];
     };
     polyfills: {
         emitted: {
@@ -58,12 +58,12 @@ declare const _default: {
         reexportedFrom?: string | undefined;
     };
     typeEmission: {
-        normalizeCppType: boolean;
-        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        needsIostream: boolean;
         needsStdString: boolean;
         needsStdVector: boolean;
-        needsIostream: boolean;
         needsStdFunction: boolean;
+        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        normalizeCppType: boolean;
         stdlibSupport: {
             hasVector: boolean;
             hasString: boolean;
@@ -79,6 +79,12 @@ declare const _default: {
         hardwareTestGroups: string[];
         halResolutionTests: string[];
     };
+    doctor?: {
+        available: boolean;
+    } | undefined;
+    licenses?: {
+        available: boolean;
+    } | undefined;
     basedOn?: string | undefined;
     inheritsStrategyId?: string | undefined;
     libraryResolution?: {
@@ -88,14 +94,5 @@ declare const _default: {
         tryGenerateLibDecl: boolean;
         reexportedFrom?: string | undefined;
     } | undefined;
-    doctor?: {
-        available: boolean;
-    } | undefined;
-    licenses?: {
-        available: boolean;
-    } | undefined;
-    compat?: {
-        zephyr?: string | undefined;
-    } | undefined;
 };
 export default _default;

package/dist/framework.manifest.js

@@ -522,15 +522,4 @@ export default defineFrameworkManifest({
             'uart', 'wdt', 'worker',
         ],
     },
-    // Declared compatibility range for the installed Zephyr RTOS. The framework's
-    // build-time version check (toolchain/compat.ts) reads this and fails fast
-    // with a clear message when the user's Zephyr is outside the range, instead
-    // of letting west/CMake surface a cryptic board-target error (the class of
-    // breakage behind the HWMv2 qualifier requirement in Zephyr 4.3+).
-    compat: {
-        zephyr: '>=4.3 <5.0',
-    },
-    // `cuttlefish doctor` prints the detected Zephyr version + compat result and
-    // previews how the configured board target resolves for that version.
-    doctor: { available: true },
 });

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 export { ZephyrStrategy as FrameworkStrategy } from './strategy.js';
 export { ZephyrStrategy } from './strategy.js';
 export { Toolchain } from './toolchain/index.js';
-export { runDoctor as doctor } from './doctor.js';
 export { chipForTarget, setActiveChip, getActiveChip, XIAO_BLE, } from './chips/index.js';
 export type { ZephyrChipDescriptor, ZephyrGpioDtSpec, } from './chips/types.js';

package/dist/index.js

@@ -8,10 +8,5 @@
 export { ZephyrStrategy as FrameworkStrategy } from './strategy.js';
 export { ZephyrStrategy } from './strategy.js';
 export { Toolchain } from './toolchain/index.js';
-// `cuttlefish doctor` — verify the installed Zephyr is reachable + inside the
-// declared compat range, and preview board-target normalization. Re-exported
-// under the dispatcher-facing alias `doctor` so the loader picks it up as
-// mod.doctor (see framework-package.ts).
-export { runDoctor as doctor } from './doctor.js';
 // Chip descriptor registry (for downstream tooling / additional boards).
 export { chipForTarget, setActiveChip, getActiveChip, XIAO_BLE, } from './chips/index.js';

package/dist/toolchain/index.js

@@ -28,7 +28,6 @@ import { writeDebugConfig, resolveDebugLocations } from './debug-config.js';
 import { ZephyrStrategy } from '../strategy.js';
 import { generateOverlay } from '../dt-config/overlay.js';
 import { chipForTarget } from '../chips/index.js';
-import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './compat.js';
 import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from '../display/profiles.js';
 /** Default board target — the framework's MVP canonical board. */
 const DEFAULT_BOARD = 'xiao_ble';
@@ -198,23 +197,7 @@ export const Toolchain = {
     },
     compile(o) {
         const projectRoot = projectRootFromOptions(o);
-        const rawBoard = targetFromOptions(o);
-        // Fail fast on an incompatible Zephyr (clear message vs. a cryptic west/
-        // CMake board error), then normalize the board target for the installed
-        // version — Zephyr 4.3+ rejects bare multi-core board names, so a stale
-        // config (esp32s3_devkitc) is rewritten to the qualified form
-        // (esp32s3_devkitc/esp32s3/procpu). See toolchain/compat.ts.
-        const zephyrVersion = detectZephyrVersion();
-        const compat = checkZephyrCompat(zephyrVersion);
-        if (compat.status === 'out-of-range') {
-            throw new Error(`Zephyr ${zephyrVersion} is outside the supported range (${compat.range}) for @typecad/framework-zephyr. ` +
-                `Set ZEPHYR_BASE to a compatible Zephyr checkout, or install one via '@typecad/zephyr-installer'.`);
-        }
-        if (compat.status === 'undetectable') {
-            console.warn(`! Could not detect the installed Zephyr version (is ZEPHYR_BASE set?). ` +
-                `Skipping compat check; declared range is ${compat.range}.`);
-        }
-        const board = resolveBoardTarget(rawBoard, zephyrVersion);
+        const board = targetFromOptions(o);
         const debugMode = new ZephyrStrategy().debugMode(board);
         const isGdbDebug = o.debug === true && debugMode === 'gdb';
         const zc = o.zephyrConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/framework-zephyr",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.9",
   "description": "TypeCAD framework package for the Zephyr RTOS — west/CMake build, devicetree-driven GPIO",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,11 +38,11 @@
     "test:hw:mqtt": "cd ../../tests/hardware && npm exec -- cuttlefish-test mqtt-client.test.ts"
   },
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.10"
+    "@typecad/cuttlefish": "1.0.0-alpha.9"
   },
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.10",
-    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.10",
+    "@typecad/expect": "1.0.0-alpha.9",
+    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.9",
     "typescript": "^5.7.3"
   },
   "license": "MIT",

package/src/framework.manifest.ts

@@ -542,17 +542,4 @@ export default defineFrameworkManifest({
       'uart', 'wdt', 'worker',
     ],
   },
-
-  // Declared compatibility range for the installed Zephyr RTOS. The framework's
-  // build-time version check (toolchain/compat.ts) reads this and fails fast
-  // with a clear message when the user's Zephyr is outside the range, instead
-  // of letting west/CMake surface a cryptic board-target error (the class of
-  // breakage behind the HWMv2 qualifier requirement in Zephyr 4.3+).
-  compat: {
-    zephyr: '>=4.3 <5.0',
-  },
-
-  // `cuttlefish doctor` prints the detected Zephyr version + compat result and
-  // previews how the configured board target resolves for that version.
-  doctor: { available: true },
 });

package/src/index.ts

@@ -10,12 +10,6 @@ export { ZephyrStrategy as FrameworkStrategy } from './strategy.js';
 export { ZephyrStrategy } from './strategy.js';
 export { Toolchain } from './toolchain/index.js';
 
-// `cuttlefish doctor` — verify the installed Zephyr is reachable + inside the
-// declared compat range, and preview board-target normalization. Re-exported
-// under the dispatcher-facing alias `doctor` so the loader picks it up as
-// mod.doctor (see framework-package.ts).
-export { runDoctor as doctor } from './doctor.js';
-
 // Chip descriptor registry (for downstream tooling / additional boards).
 export {
   chipForTarget,

package/src/toolchain/index.ts

@@ -30,7 +30,6 @@ import { writeDebugConfig, resolveDebugLocations } from './debug-config.js';
 import { ZephyrStrategy } from '../strategy.js';
 import { generateOverlay, type DisplayWiring, type TouchWiring } from '../dt-config/overlay.js';
 import { chipForTarget } from '../chips/index.js';
-import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './compat.js';
 import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from '../display/profiles.js';
 
 /** Default board target — the framework's MVP canonical board. */
@@ -220,29 +219,7 @@ export const Toolchain = {
 
   compile(o: ToolchainOptions): CompileResult {
     const projectRoot = projectRootFromOptions(o);
-    const rawBoard = targetFromOptions(o);
-
-    // Fail fast on an incompatible Zephyr (clear message vs. a cryptic west/
-    // CMake board error), then normalize the board target for the installed
-    // version — Zephyr 4.3+ rejects bare multi-core board names, so a stale
-    // config (esp32s3_devkitc) is rewritten to the qualified form
-    // (esp32s3_devkitc/esp32s3/procpu). See toolchain/compat.ts.
-    const zephyrVersion = detectZephyrVersion();
-    const compat = checkZephyrCompat(zephyrVersion);
-    if (compat.status === 'out-of-range') {
-      throw new Error(
-        `Zephyr ${zephyrVersion} is outside the supported range (${compat.range}) for @typecad/framework-zephyr. ` +
-        `Set ZEPHYR_BASE to a compatible Zephyr checkout, or install one via '@typecad/zephyr-installer'.`,
-      );
-    }
-    if (compat.status === 'undetectable') {
-      console.warn(
-        `! Could not detect the installed Zephyr version (is ZEPHYR_BASE set?). ` +
-        `Skipping compat check; declared range is ${compat.range}.`,
-      );
-    }
-    const board = resolveBoardTarget(rawBoard, zephyrVersion);
-
+    const board = targetFromOptions(o);
     const debugMode = new ZephyrStrategy().debugMode(board);
     const isGdbDebug = o.debug === true && debugMode === 'gdb';
     const zc = o.zephyrConfig as Record<string, unknown> | undefined;

package/dist/doctor.d.ts

@@ -1,6 +0,0 @@
-/**
- * Verify the installed Zephyr is reachable + inside the supported range, and
- * preview board-target normalization for the configured target. Sets
- * process.exitCode = 1 on an out-of-range Zephyr.
- */
-export declare function runDoctor(): void;

package/dist/doctor.js

@@ -1,48 +0,0 @@
-// ---------------------------------------------------------------------------
-// @typecad/framework-zephyr — Zephyr environment doctor
-//
-// `cuttlefish doctor` (Zephyr framework) — verify the installed Zephyr RTOS is
-// reachable and inside the framework's declared compat range, and preview how
-// the configured board target resolves for that version. Exits 0 if the
-// environment is OK, non-zero otherwise. Mirrors framework-arduino's doctor
-// shape (dispatched via the framework's `doctor` export).
-// ---------------------------------------------------------------------------
-import * as ui from '@typecad/cuttlefish/utils/ui';
-import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
-import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './toolchain/compat.js';
-/**
- * Verify the installed Zephyr is reachable + inside the supported range, and
- * preview board-target normalization for the configured target. Sets
- * process.exitCode = 1 on an out-of-range Zephyr.
- */
-export function runDoctor() {
-    ui.printHeader();
-    ui.printStep('Checking Zephyr environment...');
-    const base = process.env.ZEPHYR_BASE;
-    const version = detectZephyrVersion();
-    const result = checkZephyrCompat(version);
-    ui.printInfo(`ZEPHYR_BASE ..... ${base ?? '(not set)'}`);
-    ui.printInfo(`Zephyr version .. ${version ?? 'unknown (could not read ZEPHYR_BASE/VERSION)'}`);
-    ui.printInfo(`Supported range . ${result.range ?? '(none declared)'}`);
-    if (result.status === 'out-of-range') {
-        ui.printError(`Zephyr ${version} is OUTSIDE the supported range (${result.range}).`);
-        ui.printInfo("Set ZEPHYR_BASE to a compatible Zephyr checkout, or install one via '@typecad/zephyr-installer'.");
-        process.exitCode = 1;
-        return;
-    }
-    if (result.status === 'undetectable') {
-        ui.printWarning('Could not detect the Zephyr version (is ZEPHYR_BASE set?) — compat check skipped.');
-    }
-    else {
-        ui.printInfo('Zephyr compat ... OK');
-    }
-    // Preview how the configured board target resolves for this Zephyr version
-    // (e.g. a stale bare id would be qualified at build time). The loader extracts
-    // frameworkData.buildTarget to a top-level field.
-    const config = loadCuttlefishConfig(process.cwd());
-    const buildTarget = config?.buildTarget;
-    if (buildTarget) {
-        const resolved = resolveBoardTarget(buildTarget, version);
-        ui.printInfo(`Board target .... ${buildTarget}${resolved === buildTarget ? '' : ` → ${resolved}`}`);
-    }
-}

package/dist/toolchain/compat.d.ts

@@ -1,38 +0,0 @@
-/** Parse "4.3.99" / "v4.3" / "4.3.99-rc1" → [4, 3, 99]. Undefined if unparseable. */
-export declare function parseVersion(v: string | undefined): [number, number, number] | undefined;
-/** Compare two version strings: -1 if a<b, 0 if equal, 1 if a>b. */
-export declare function compareVersion(a: string, b: string): number;
-/**
- * Evaluate a simple range of space-separated comparators against a version.
- * Supported operators: >= <= > < =. Each comparator glues the operator to its
- * version (">=4.3", "<5.0"); spaces between comparators are AND.
- *   satisfiesRange("4.3.99", ">=4.3 <5.0") === true
- */
-export declare function satisfiesRange(version: string, range: string): boolean;
-/**
- * Detect the installed Zephyr version from ZEPHYR_BASE/VERSION. Returns
- * undefined when ZEPHYR_BASE is unset or VERSION can't be read/parsed. Handles
- * the CMake-style file (VERSION_MAJOR = 4 / VERSION_MINOR = 3 / PATCHLEVEL = 99)
- * and a bare "4.3.99".
- */
-export declare function detectZephyrVersion(): string | undefined;
-export type CompatStatus = 'ok' | 'undetectable' | 'out-of-range';
-export interface CompatResult {
-    version: string | undefined;
-    /** Declared supported range (manifest.compat.zephyr), if any. */
-    range: string | undefined;
-    status: CompatStatus;
-}
-/**
- * Compare the detected Zephyr version against the declared compat range. Pure:
- * returns a status; the caller decides whether to throw/warn. 'ok' covers both
- * "in range" and "no range declared".
- */
-export declare function checkZephyrCompat(version: string | undefined): CompatResult;
-/**
- * Normalize a board target for the installed Zephyr version. Rewrites a stale
- * bare id (esp32s3_devkitc) to the qualified form on Zephyr >=4.3; idempotent
- * if the target is already qualified. Older Zephyr, single-core boards
- * (xiao_ble), and unknown boards pass through unchanged.
- */
-export declare function resolveBoardTarget(boardTarget: string, version: string | undefined): string;

package/dist/toolchain/compat.js

@@ -1,133 +0,0 @@
-// Zephyr version compatibility + board-target normalization.
-//
-// Two mechanisms absorb Zephyr version churn:
-//  1. checkZephyrCompat() — compare the installed Zephyr version against the
-//     declared range (manifest.compat.zephyr) so an incompatible Zephyr fails
-//     fast with a clear message instead of a cryptic west/CMake board error.
-//  2. resolveBoardTarget() — normalize the board target for the installed
-//     Zephyr version. Zephyr 4.3+ rejects bare multi-core board names
-//     (esp32s3_devkitc) and requires a qualified target
-//     (esp32s3_devkitc/esp32s3/procpu). This rewrites stale configs at build
-//     time so users don't have to regenerate them after a Zephyr upgrade.
-//
-// This module is intentionally pure (no chalk/ui/console) so it unit-tests
-// cleanly; the doctor and the toolchain decide how to present results.
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import manifest from '../framework.manifest.js';
-// ── minimal semver ──────────────────────────────────────────────────────────
-/** Parse "4.3.99" / "v4.3" / "4.3.99-rc1" → [4, 3, 99]. Undefined if unparseable. */
-export function parseVersion(v) {
-    if (!v)
-        return undefined;
-    const m = v.replace(/^v/i, '').match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
-    if (!m)
-        return undefined;
-    return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)];
-}
-/** Compare two version strings: -1 if a<b, 0 if equal, 1 if a>b. */
-export function compareVersion(a, b) {
-    const pa = parseVersion(a) ?? [0, 0, 0];
-    const pb = parseVersion(b) ?? [0, 0, 0];
-    for (let i = 0; i < 3; i++) {
-        if (pa[i] < pb[i])
-            return -1;
-        if (pa[i] > pb[i])
-            return 1;
-    }
-    return 0;
-}
-/**
- * Evaluate a simple range of space-separated comparators against a version.
- * Supported operators: >= <= > < =. Each comparator glues the operator to its
- * version (">=4.3", "<5.0"); spaces between comparators are AND.
- *   satisfiesRange("4.3.99", ">=4.3 <5.0") === true
- */
-export function satisfiesRange(version, range) {
-    return range
-        .trim()
-        .split(/\s+/)
-        .every((clause) => {
-        const m = clause.replace(/\s+/g, '').match(/^(>=|<=|>|<|=)(.+)$/);
-        if (!m)
-            return true; // ignore anything that isn't a comparator
-        const cmp = compareVersion(version, m[2]);
-        switch (m[1]) {
-            case '>=': return cmp >= 0;
-            case '<=': return cmp <= 0;
-            case '>': return cmp > 0;
-            case '<': return cmp < 0;
-            case '=': return cmp === 0;
-            default: return true;
-        }
-    });
-}
-// ── Zephyr version detection ────────────────────────────────────────────────
-/**
- * Detect the installed Zephyr version from ZEPHYR_BASE/VERSION. Returns
- * undefined when ZEPHYR_BASE is unset or VERSION can't be read/parsed. Handles
- * the CMake-style file (VERSION_MAJOR = 4 / VERSION_MINOR = 3 / PATCHLEVEL = 99)
- * and a bare "4.3.99".
- */
-export function detectZephyrVersion() {
-    const base = process.env.ZEPHYR_BASE;
-    if (!base)
-        return undefined;
-    let content;
-    try {
-        content = readFileSync(join(base, 'VERSION'), 'utf-8');
-    }
-    catch {
-        return undefined;
-    }
-    const field = (key) => {
-        const m = content.match(new RegExp(`^\\s*${key}\\s*=\\s*(\\d+)`, 'm'));
-        return m ? m[1] : undefined;
-    };
-    const major = field('VERSION_MAJOR');
-    if (major !== undefined) {
-        return `${major}.${field('VERSION_MINOR') ?? 0}.${field('PATCHLEVEL') ?? 0}`;
-    }
-    const m = content.match(/(\d+\.\d+(?:\.\d+)?)/);
-    return m ? m[1] : undefined;
-}
-/**
- * Compare the detected Zephyr version against the declared compat range. Pure:
- * returns a status; the caller decides whether to throw/warn. 'ok' covers both
- * "in range" and "no range declared".
- */
-export function checkZephyrCompat(version) {
-    const range = manifest.compat?.zephyr;
-    if (!range)
-        return { version, range, status: 'ok' };
-    if (version === undefined)
-        return { version, range, status: 'undetectable' };
-    return { version, range, status: satisfiesRange(version, range) ? 'ok' : 'out-of-range' };
-}
-// ── board-target normalization ──────────────────────────────────────────────
-/**
- * For Zephyr >=4.3, multi-core ESP32 boards require a qualified board target
- * (board/<soc>/<core>) — the bare id is rejected with "Board qualifiers … not
- * found". Map each known multi-core board id to its procpu (main app core)
- * qualified form. procpu is the core that runs application firmware; appcpu is
- * the secondary core (selected explicitly only when offloading to it).
- */
-const QUALIFIED_TARGETS_GE_4_3 = {
-    esp32_devkitc: 'esp32_devkitc/esp32/procpu',
-    esp32s3_devkitc: 'esp32s3_devkitc/esp32s3/procpu',
-};
-/**
- * Normalize a board target for the installed Zephyr version. Rewrites a stale
- * bare id (esp32s3_devkitc) to the qualified form on Zephyr >=4.3; idempotent
- * if the target is already qualified. Older Zephyr, single-core boards
- * (xiao_ble), and unknown boards pass through unchanged.
- */
-export function resolveBoardTarget(boardTarget, version) {
-    const boardId = boardTarget.split('/')[0];
-    if (version !== undefined && satisfiesRange(version, '>=4.3')) {
-        const qualified = QUALIFIED_TARGETS_GE_4_3[boardId];
-        if (qualified)
-            return qualified;
-    }
-    return boardTarget;
-}

package/src/doctor.ts

@@ -1,56 +0,0 @@
-// ---------------------------------------------------------------------------
-// @typecad/framework-zephyr — Zephyr environment doctor
-//
-// `cuttlefish doctor` (Zephyr framework) — verify the installed Zephyr RTOS is
-// reachable and inside the framework's declared compat range, and preview how
-// the configured board target resolves for that version. Exits 0 if the
-// environment is OK, non-zero otherwise. Mirrors framework-arduino's doctor
-// shape (dispatched via the framework's `doctor` export).
-// ---------------------------------------------------------------------------
-
-import * as ui from '@typecad/cuttlefish/utils/ui';
-import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
-import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './toolchain/compat.js';
-
-/**
- * Verify the installed Zephyr is reachable + inside the supported range, and
- * preview board-target normalization for the configured target. Sets
- * process.exitCode = 1 on an out-of-range Zephyr.
- */
-export function runDoctor(): void {
-  ui.printHeader();
-  ui.printStep('Checking Zephyr environment...');
-
-  const base = process.env.ZEPHYR_BASE;
-  const version = detectZephyrVersion();
-  const result = checkZephyrCompat(version);
-
-  ui.printInfo(`ZEPHYR_BASE ..... ${base ?? '(not set)'}`);
-  ui.printInfo(`Zephyr version .. ${version ?? 'unknown (could not read ZEPHYR_BASE/VERSION)'}`);
-  ui.printInfo(`Supported range . ${result.range ?? '(none declared)'}`);
-
-  if (result.status === 'out-of-range') {
-    ui.printError(`Zephyr ${version} is OUTSIDE the supported range (${result.range}).`);
-    ui.printInfo(
-      "Set ZEPHYR_BASE to a compatible Zephyr checkout, or install one via '@typecad/zephyr-installer'.",
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  if (result.status === 'undetectable') {
-    ui.printWarning('Could not detect the Zephyr version (is ZEPHYR_BASE set?) — compat check skipped.');
-  } else {
-    ui.printInfo('Zephyr compat ... OK');
-  }
-
-  // Preview how the configured board target resolves for this Zephyr version
-  // (e.g. a stale bare id would be qualified at build time). The loader extracts
-  // frameworkData.buildTarget to a top-level field.
-  const config = loadCuttlefishConfig(process.cwd());
-  const buildTarget = config?.buildTarget;
-  if (buildTarget) {
-    const resolved = resolveBoardTarget(buildTarget, version);
-    ui.printInfo(`Board target .... ${buildTarget}${resolved === buildTarget ? '' : ` → ${resolved}`}`);
-  }
-}

package/src/toolchain/compat.ts

@@ -1,145 +0,0 @@
-// Zephyr version compatibility + board-target normalization.
-//
-// Two mechanisms absorb Zephyr version churn:
-//  1. checkZephyrCompat() — compare the installed Zephyr version against the
-//     declared range (manifest.compat.zephyr) so an incompatible Zephyr fails
-//     fast with a clear message instead of a cryptic west/CMake board error.
-//  2. resolveBoardTarget() — normalize the board target for the installed
-//     Zephyr version. Zephyr 4.3+ rejects bare multi-core board names
-//     (esp32s3_devkitc) and requires a qualified target
-//     (esp32s3_devkitc/esp32s3/procpu). This rewrites stale configs at build
-//     time so users don't have to regenerate them after a Zephyr upgrade.
-//
-// This module is intentionally pure (no chalk/ui/console) so it unit-tests
-// cleanly; the doctor and the toolchain decide how to present results.
-
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import manifest from '../framework.manifest.js';
-
-// ── minimal semver ──────────────────────────────────────────────────────────
-
-/** Parse "4.3.99" / "v4.3" / "4.3.99-rc1" → [4, 3, 99]. Undefined if unparseable. */
-export function parseVersion(v: string | undefined): [number, number, number] | undefined {
-  if (!v) return undefined;
-  const m = v.replace(/^v/i, '').match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
-  if (!m) return undefined;
-  return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)];
-}
-
-/** Compare two version strings: -1 if a<b, 0 if equal, 1 if a>b. */
-export function compareVersion(a: string, b: string): number {
-  const pa = parseVersion(a) ?? [0, 0, 0];
-  const pb = parseVersion(b) ?? [0, 0, 0];
-  for (let i = 0; i < 3; i++) {
-    if (pa[i]! < pb[i]!) return -1;
-    if (pa[i]! > pb[i]!) return 1;
-  }
-  return 0;
-}
-
-/**
- * Evaluate a simple range of space-separated comparators against a version.
- * Supported operators: >= <= > < =. Each comparator glues the operator to its
- * version (">=4.3", "<5.0"); spaces between comparators are AND.
- *   satisfiesRange("4.3.99", ">=4.3 <5.0") === true
- */
-export function satisfiesRange(version: string, range: string): boolean {
-  return range
-    .trim()
-    .split(/\s+/)
-    .every((clause) => {
-      const m = clause.replace(/\s+/g, '').match(/^(>=|<=|>|<|=)(.+)$/);
-      if (!m) return true; // ignore anything that isn't a comparator
-      const cmp = compareVersion(version, m[2]!);
-      switch (m[1]) {
-        case '>=': return cmp >= 0;
-        case '<=': return cmp <= 0;
-        case '>': return cmp > 0;
-        case '<': return cmp < 0;
-        case '=': return cmp === 0;
-        default: return true;
-      }
-    });
-}
-
-// ── Zephyr version detection ────────────────────────────────────────────────
-
-/**
- * Detect the installed Zephyr version from ZEPHYR_BASE/VERSION. Returns
- * undefined when ZEPHYR_BASE is unset or VERSION can't be read/parsed. Handles
- * the CMake-style file (VERSION_MAJOR = 4 / VERSION_MINOR = 3 / PATCHLEVEL = 99)
- * and a bare "4.3.99".
- */
-export function detectZephyrVersion(): string | undefined {
-  const base = process.env.ZEPHYR_BASE;
-  if (!base) return undefined;
-  let content: string;
-  try {
-    content = readFileSync(join(base, 'VERSION'), 'utf-8');
-  } catch {
-    return undefined;
-  }
-  const field = (key: string): string | undefined => {
-    const m = content.match(new RegExp(`^\\s*${key}\\s*=\\s*(\\d+)`, 'm'));
-    return m ? m[1] : undefined;
-  };
-  const major = field('VERSION_MAJOR');
-  if (major !== undefined) {
-    return `${major}.${field('VERSION_MINOR') ?? 0}.${field('PATCHLEVEL') ?? 0}`;
-  }
-  const m = content.match(/(\d+\.\d+(?:\.\d+)?)/);
-  return m ? m[1] : undefined;
-}
-
-// ── compat check ────────────────────────────────────────────────────────────
-
-export type CompatStatus = 'ok' | 'undetectable' | 'out-of-range';
-
-export interface CompatResult {
-  version: string | undefined;
-  /** Declared supported range (manifest.compat.zephyr), if any. */
-  range: string | undefined;
-  status: CompatStatus;
-}
-
-/**
- * Compare the detected Zephyr version against the declared compat range. Pure:
- * returns a status; the caller decides whether to throw/warn. 'ok' covers both
- * "in range" and "no range declared".
- */
-export function checkZephyrCompat(version: string | undefined): CompatResult {
-  const range = manifest.compat?.zephyr;
-  if (!range) return { version, range, status: 'ok' };
-  if (version === undefined) return { version, range, status: 'undetectable' };
-  return { version, range, status: satisfiesRange(version, range) ? 'ok' : 'out-of-range' };
-}
-
-// ── board-target normalization ──────────────────────────────────────────────
-
-/**
- * For Zephyr >=4.3, multi-core ESP32 boards require a qualified board target
- * (board/<soc>/<core>) — the bare id is rejected with "Board qualifiers … not
- * found". Map each known multi-core board id to its procpu (main app core)
- * qualified form. procpu is the core that runs application firmware; appcpu is
- * the secondary core (selected explicitly only when offloading to it).
- */
-const QUALIFIED_TARGETS_GE_4_3: Record<string, string> = {
-  esp32_devkitc: 'esp32_devkitc/esp32/procpu',
-  esp32s3_devkitc: 'esp32s3_devkitc/esp32s3/procpu',
-};
-
-/**
- * Normalize a board target for the installed Zephyr version. Rewrites a stale
- * bare id (esp32s3_devkitc) to the qualified form on Zephyr >=4.3; idempotent
- * if the target is already qualified. Older Zephyr, single-core boards
- * (xiao_ble), and unknown boards pass through unchanged.
- */
-export function resolveBoardTarget(boardTarget: string, version: string | undefined): string {
-  const boardId = boardTarget.split('/')[0]!;
-  if (version !== undefined && satisfiesRange(version, '>=4.3')) {
-    const qualified = QUALIFIED_TARGETS_GE_4_3[boardId];
-    if (qualified) return qualified;
-  }
-  return boardTarget;
-}