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

package/dist/board-catalog/index.d.ts

@@ -0,0 +1,11 @@
+export type { BoardDataEntry } from './types.js';
+export { readBoardDts } from './dts-reader.js';
+export { harvestPinconfig } from './pinconfig.js';
+export type { PinconfigFacts, PinconfigAdcRoute, PinconfigDacRoute, PinconfigPwmRoute } from './pinconfig.js';
+export type { DtsBoardFacts, DtsGpioRef, DtsGpioNode, DtsConnector, DtsPwmLed, } from './dts-reader.js';
+export { walkBoardCatalog, boardYmlSocIndex, boardYmlTargets, boardProbeMethods, socBusLabelsFromTree, zephyrVersionOf, gitHeadOf, } from './walker.js';
+export type { BoardYmlSocIndex, BoardYmlTarget, BoardCatalogProvenance, BoardCatalogWalkResult, VariantPin, } from './walker.js';
+export { GENERATOR_REV, isZephyrBase, locateZephyrBaseCheap, micromambaZephyrBase, overlayPathFor, readBoardCatalogOverlayFile, loadBoardCatalogOverlay, resetBoardCatalogOverlayCache, isOverlayStale, ensureFreshBoardCatalog, syncBoardCatalog, diffBoardCatalogs, findBoardInCatalog, boardRecordFingerprint, factsFingerprint, activeBoardCatalog, resetActiveBoardCatalog, } from './store.js';
+export type { BoardCatalogOverlay, BoardCatalogSyncReport, BoardCatalogSnapshot, BoardCatalogEnsureResult, } from './store.js';
+export { PINNED_ZEPHYR_MANIFEST_REV, PINNED_ZEPHYR_SDK_VERSION, ZEPHYR_INSTALL_CMD, sdkFingerprint, findToolchainSdk, checkZephyrSdk, assertZephyrSdkForCreate, formatZephyrSdkFound, } from './sdk.js';
+export type { SdkCheck, SdkDiscoverySource } from './sdk.js';

package/dist/board-catalog/index.js

@@ -0,0 +1,12 @@
+// ---------------------------------------------------------------------------
+// board-catalog/index.ts — public surface of the board catalog tooling.
+//
+// The catalog is generated from the user's own Zephyr tree (walker over the
+// tolerant devicetree reader) and lives as a machine-local overlay. There
+// is no compiled-in board database.
+// ---------------------------------------------------------------------------
+export { readBoardDts } from './dts-reader.js';
+export { harvestPinconfig } from './pinconfig.js';
+export { walkBoardCatalog, boardYmlSocIndex, boardYmlTargets, boardProbeMethods, socBusLabelsFromTree, zephyrVersionOf, gitHeadOf, } from './walker.js';
+export { GENERATOR_REV, isZephyrBase, locateZephyrBaseCheap, micromambaZephyrBase, overlayPathFor, readBoardCatalogOverlayFile, loadBoardCatalogOverlay, resetBoardCatalogOverlayCache, isOverlayStale, ensureFreshBoardCatalog, syncBoardCatalog, diffBoardCatalogs, findBoardInCatalog, boardRecordFingerprint, factsFingerprint, activeBoardCatalog, resetActiveBoardCatalog, } from './store.js';
+export { PINNED_ZEPHYR_MANIFEST_REV, PINNED_ZEPHYR_SDK_VERSION, ZEPHYR_INSTALL_CMD, sdkFingerprint, findToolchainSdk, checkZephyrSdk, assertZephyrSdkForCreate, formatZephyrSdkFound, } from './sdk.js';

package/dist/board-catalog/pinconfig.d.ts

@@ -0,0 +1,48 @@
+/** A normalized ADC route from a pinconfig table (raw harvest form). */
+export interface PinconfigAdcRoute {
+    /** ADC controller nodelabel the route maps to ('adc0', 'adc1', 'adc'). */
+    readonly source: string;
+    /** Input channel number. */
+    readonly channel: number;
+    /** GPIO port letter ('A', …) or digit ('0' for a flat gpio0 controller). */
+    readonly port: string;
+    readonly bit: number;
+    /** Pinmux token when the family's ADC needs a pad mux. Absent for families
+     *  whose analog inputs need none (Atmel SAM, Bouffalolab). */
+    readonly pinctrl?: string;
+}
+export interface PinconfigFacts {
+    readonly adc: PinconfigAdcRoute[];
+    /** DAC output routes (Atmel SAM — no pinmux group; the driver selects the
+     *  output pad). */
+    readonly dac?: PinconfigDacRoute[];
+    /** PWM output routes (Atmel SAM tc/tcc waveform outputs — the WO pinmux
+     *  macro is synthesized from the position+peripheral+signal triple). */
+    readonly pwm?: PinconfigPwmRoute[];
+    /** The pinconfig file that satisfied the board (provenance). */
+    readonly file?: string;
+}
+/** A normalized DAC output route from a pinconfig table (raw harvest form). */
+export interface PinconfigDacRoute {
+    readonly source: string;
+    readonly channel: number;
+    readonly port: string;
+    readonly bit: number;
+}
+/** A normalized PWM output route from a pinconfig table. `pinctrl` is the
+ *  synthesized SAM pinmux macro token (`PA17E_TCC2_WO1`), which the board's
+ *  pinctrl include chain defines via SAM_PINMUX. */
+export interface PinconfigPwmRoute {
+    readonly source: string;
+    readonly channel: number;
+    readonly port: string;
+    readonly bit: number;
+    readonly pinctrl: string;
+}
+/**
+ * Harvest ADC routes from the vendor pinconfigs for the board's SoC. The
+ * source is chosen by the soc segment — a data convention (like the
+ * letter-port families), never a board name. Undefined for SoCs without a
+ * pinconfig source.
+ */
+export declare function harvestPinconfig(identifier: string, westRoot: string): PinconfigFacts | undefined;

package/dist/board-catalog/pinconfig.js

@@ -0,0 +1,263 @@
+// ---------------------------------------------------------------------------
+// board-catalog/pinconfig.ts — parse the vendor `pinconfigs/*.yml` datasheet
+// pin tables into normalized silicon routes.
+//
+// Atmel (SAM/SAM0) and Bouffalolab publish datasheet-complete pin-mux tables
+// as YAML under their HAL module's `pinconfigs/` directory — the SAME files
+// the vendors' own pinctrl generators consume. Each declares, per pin and per
+// bonded package ("pincode"), the full list of alternate functions (ADC input
+// channel, DAC output channel, timer/PWM channel, and the raw signal
+// vocabulary). That is the authoritative "every pin + every function" source
+// — no macro-name regexes, no generated-header churn.
+//
+// GigaDevice is deliberately NOT here: its board soc segment is the SERIES
+// (gd32f450), not the part, so the package key this parser needs is absent
+// from the soc name — the package-specific generated header (read by the
+// dts-reader's dialect table) is the authoritative source for GD32.
+//
+// This module unifies the two grammars (they share a `series`/`pincode`/
+// `pins` skeleton) and returns ADC routes in the raw harvest form the rest of
+// the catalog already uses (source/channel/port/bit). DAC/PWM routes are
+// deliberately NOT lowered yet — their overlay pinmux synthesis is per-family
+// and still pending (tracked by the walker's coverage ledger, not shipped as
+// false capability flags).
+// ----------------------------------------------------------------------------
+import fs from 'node:fs';
+import path from 'node:path';
+/** List the *.yml files in a pinconfigs dir (undefined when absent). */
+function listYml(dir) {
+    try {
+        return fs.readdirSync(dir).filter((f) => f.endsWith('.yml'));
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── Atmel SAM / SAM0 ────────────────────────────────────────────────────────
+// `periph:` is a list of `[position, peripheral, signal]` triples per pin.
+// Analog inputs are `[b, adc0, ain15]` — no pad mux token (the SAM ADC driver
+// samples by channel; the pad is analog by function selection).
+// ----------------------------------------------------------------------------
+function harvestAtmel(soc, westRoot) {
+    const dir = path.join(westRoot, 'modules', 'hal', 'atmel', 'pinconfigs');
+    const files = listYml(dir);
+    if (!files)
+        return undefined;
+    const socLower = soc.toLowerCase();
+    for (const f of files) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, f), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const seriesMatch = text.match(/^series:\s*\[([^\]]*)\]/m);
+        if (!seriesMatch)
+            continue;
+        const series = seriesMatch[1].split(',').map((s) => s.trim()).filter(Boolean);
+        // Series tokens encode the soc prefix either directly ('d51') or as a
+        // placeholder with a trailing 'X' ('4eX', '3XX', '4lsX' — the OLD SAM
+        // parts). A placeholder matches the bare prefix and its package letter is
+        // the LAST character of the soc name (sam4e16e → 'e'), unlike the modern
+        // parts whose package follows the series directly (samd51j19a → 'j').
+        const prefixes = [];
+        for (const s of series) {
+            const lower = s.toLowerCase();
+            if (lower.includes('-')) {
+                prefixes.push({ prefix: lower, placeholder: false });
+                prefixes.push({ prefix: lower.split('-')[0], placeholder: false });
+                continue;
+            }
+            if (lower.endsWith('x')) {
+                const stripped = lower.replace(/x+$/, '');
+                if (stripped)
+                    prefixes.push({ prefix: stripped, placeholder: true });
+                prefixes.push({ prefix: lower, placeholder: true });
+            }
+            else {
+                prefixes.push({ prefix: lower, placeholder: false });
+            }
+        }
+        const matched = prefixes.find((p) => socLower.startsWith('sam' + p.prefix));
+        if (!matched)
+            continue;
+        const pincode = matched.placeholder
+            ? socLower.slice(-1)
+            : socLower.slice(('sam' + matched.prefix).length).charAt(0);
+        if (!/^[a-z]$/.test(pincode))
+            break;
+        const routes = [];
+        const dacRoutes = [];
+        const pwmRoutes = [];
+        let pin;
+        for (const line of text.split('\n')) {
+            // Atmel pin names are p<port><bits> (pa02, pa0 — the PIO prefix; the
+            // old SAM parts use single-digit pads).
+            const pinM = line.match(/^  p([a-z])(\d+):/);
+            if (pinM) {
+                pin = { name: pinM[1] + pinM[2], codes: new Set() };
+                continue;
+            }
+            if (!pin)
+                continue;
+            const codesM = line.match(/^ {4}pincodes:\s*\[([^\]]*)\]/);
+            if (codesM) {
+                for (const c of codesM[1].split(',').map((s) => s.trim()).filter(Boolean))
+                    pin.codes.add(c);
+                continue;
+            }
+            const perM = line.match(/^ {6}- \[([a-z]),\s*(\w+),\s*(\w+)(?:,\s*\[[^\]]*\])?\]/);
+            // 'adc' (d2x/3x single controller), 'adc0'/'adc1' (d5x). The signal is
+            // `ain<N>` on the SAM0/SAMD parts and `ad<N>` on the older SAM parts.
+            // `adc_dac` (reference outputs) and the AFEC/ADCIFE front-ends
+            // (`afec0`/`adcife`) are NOT input routes on the standard adc driver.
+            if (perM && pin.codes.has(pincode) && /^adc\d*$/.test(perM[2])) {
+                const ain = perM[3].match(/^ain(\d+)$/) ?? perM[3].match(/^ad(\d+)$/);
+                if (ain) {
+                    routes.push({
+                        source: perM[2],
+                        channel: Number(ain[1]),
+                        port: pin.name[0].toUpperCase(),
+                        bit: Number(pin.name.slice(1)),
+                    });
+                }
+            }
+            // DAC output: `[b, dac, vout<N>]` (and the digitless `vout` on the
+            // single-channel parts). The YAML peripheral is `dac` but the DT
+            // nodelabel is `dac0` (samd2x/samd5x/… declare dac0: dac@…), so the
+            // source is normalized to dac0 to survive the analogDevices cross-check.
+            // No pinmux group — the sam0-dac driver selects the output pad.
+            if (perM && pin.codes.has(pincode) && perM[2] === 'dac') {
+                const vout = perM[3].match(/^vout(\d+)$/) ?? (perM[3] === 'vout' ? [null, '0'] : null);
+                if (vout) {
+                    dacRoutes.push({
+                        source: 'dac0',
+                        channel: Number(vout[1] ?? 0),
+                        port: pin.name[0].toUpperCase(),
+                        bit: Number(pin.name.slice(1)),
+                    });
+                }
+            }
+            // PWM waveform output: `[e, tcc2, wo1]` — the position letter +
+            // peripheral + signal synthesize the SAM pinmux macro token the board's
+            // pinctrl chain defines (`P<port><bit><pos>_<PERIPH>_<SIG>` →
+            // `PA17E_TCC2_WO1`). The source is the DT nodelabel verbatim (`tcc2`).
+            if (perM && pin.codes.has(pincode) && /^(tcc|tc)\d+$/.test(perM[2])) {
+                const wo = perM[3].match(/^wo(\d+)$/);
+                if (wo) {
+                    const port = pin.name[0].toUpperCase();
+                    // The macro token uses the NUMERIC pad (no leading zero — pa02 →
+                    // PA2E_TCC2_WO1, pa17 → PA17E_TCC2_WO1).
+                    const bit = Number(pin.name.slice(1));
+                    pwmRoutes.push({
+                        source: perM[2],
+                        channel: Number(wo[1]),
+                        port,
+                        bit,
+                        pinctrl: `P${port}${bit}${perM[1].toUpperCase()}_${perM[2].toUpperCase()}_${perM[3].toUpperCase()}`,
+                    });
+                }
+            }
+        }
+        if (routes.length > 0 || dacRoutes.length > 0 || pwmRoutes.length > 0) {
+            routes.sort((a, b) => a.source.localeCompare(b.source, undefined, { numeric: true }) || a.channel - b.channel);
+            dacRoutes.sort((a, b) => a.channel - b.channel);
+            pwmRoutes.sort((a, b) => a.source.localeCompare(b.source, undefined, { numeric: true }) || a.channel - b.channel);
+            return {
+                adc: routes,
+                ...(dacRoutes.length > 0 ? { dac: dacRoutes } : {}),
+                ...(pwmRoutes.length > 0 ? { pwm: pwmRoutes } : {}),
+                file: f,
+            };
+        }
+        break;
+    }
+    return undefined;
+}
+// ── Bouffalolab ─────────────────────────────────────────────────────────────
+// Pins are global pads (`gpio0`…), `analog:` lists `[adc, [ch<N>]]` and the
+// family/series fields name the SoC variants (`family: bl60x`, `series:
+// [602, 604]` → bl602/bl604). Analog pads need no pinmux group (silicon-
+// selected, like the ESP32 SARADC). Indentation varies between files (bl60x
+// indents pins 2 spaces, bl61x/bl70x 4) — matched tolerant of depth.
+// ----------------------------------------------------------------------------
+function harvestBflb(soc, westRoot) {
+    const dir = path.join(westRoot, 'modules', 'hal', 'bouffalolab', 'pinconfigs');
+    const files = listYml(dir);
+    if (!files)
+        return undefined;
+    const socLower = soc.toLowerCase();
+    for (const f of files) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, f), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const series = [...text.matchAll(/^series:\s*\[([^\]]*)\]/gm)]
+            .flatMap((m) => m[1].split(',').map((s) => s.trim()).filter(Boolean));
+        if (series.length === 0)
+            continue;
+        // The soc name starts with `bl` + a series entry (bl602c00q2i → bl602,
+        // bl704l10q2i → bl704l, …) — the tail is package/flash detail.
+        const suffix = series.find((s) => socLower.startsWith(('bl' + s).toLowerCase()));
+        if (!suffix)
+            continue;
+        const routes = [];
+        let pin;
+        let inAnalog = false;
+        for (const rawLine of text.split('\n')) {
+            const line = rawLine.replace(/\r$/, '');
+            const pinM = line.match(/^\s+gpio(\d+):/);
+            if (pinM) {
+                pin = { bit: Number(pinM[1]), bonded: true };
+                inAnalog = false;
+                continue;
+            }
+            if (!pin)
+                continue;
+            // A new key at pin depth ends the analog block.
+            if (inAnalog && /^\s+\w[\w-]*:/.test(line)) {
+                inAnalog = false;
+            }
+            if (inAnalog) {
+                const adc = line.match(/^\s*-\s*\[adc,\s*\[ch(\d+)\]\]/);
+                if (adc && pin.bonded) {
+                    routes.push({ source: 'adc0', channel: Number(adc[1]), port: '0', bit: pin.bit });
+                }
+                continue;
+            }
+            const seriesM = line.match(/^\s+series:\s*\[([^\]]*)\]/);
+            if (seriesM) {
+                pin.bonded = seriesM[1].split(',').some((s) => s.trim() === suffix);
+                continue;
+            }
+            if (/^\s+analog:/.test(line))
+                inAnalog = true;
+        }
+        if (routes.length > 0) {
+            routes.sort((a, b) => a.channel - b.channel);
+            return { adc: routes, file: f };
+        }
+    }
+    return undefined;
+}
+/**
+ * Harvest ADC routes from the vendor pinconfigs for the board's SoC. The
+ * source is chosen by the soc segment — a data convention (like the
+ * letter-port families), never a board name. Undefined for SoCs without a
+ * pinconfig source.
+ */
+export function harvestPinconfig(identifier, westRoot) {
+    const soc = identifier.split('/')[1];
+    if (!soc)
+        return undefined;
+    const s = soc.toLowerCase();
+    if (s.startsWith('sam'))
+        return harvestAtmel(soc, westRoot);
+    if (s.startsWith('bl'))
+        return harvestBflb(soc, westRoot);
+    return undefined;
+}

package/dist/board-catalog/sdk.d.ts

@@ -0,0 +1,82 @@
+/** The Zephyr manifest revision the workspace pins (installer versions.env). */
+export declare const PINNED_ZEPHYR_MANIFEST_REV = "v4.4.2";
+/** The Zephyr SDK (toolchain bundle) version the workspace pins. */
+export declare const PINNED_ZEPHYR_SDK_VERSION = "1.0.1";
+/** The canonical install command (the installer's own usage strings). */
+export declare const ZEPHYR_INSTALL_CMD = "npx --package @typecad/framework-zephyr zephyr-installer";
+/** Env that disables the create-time SDK gate (tests / expert override). */
+export declare const SDK_CHECK_ENV = "CUTTLEFISH_SDK_CHECK";
+/**
+ * Fingerprint of an installed Zephyr tree: version + git HEAD, hashed. This
+ * is the identity the board catalog's provenance already records per-walk;
+ * expose it for humans (`board sync`, `doctor`) and any consumer that wants
+ * to detect "the SDK moved" without comparing fields.
+ */
+export declare function sdkFingerprint(tree: string): string | undefined;
+/** Where the tree was found — printed by create so the user knows which
+ *  SDK they are building against (and why, when two machines differ). */
+export type SdkDiscoverySource = 'ZEPHYR_BASE' | 'well-known workspace' | 'installer env' | 'explicit';
+/** Everything the create-time gate (and doctor) needs to know about the SDK:
+ *  the Zephyr tree (source of truth for boards) and the toolchain SDK dir
+ *  (the compiler bundle the installer lays down beside it). */
+export type SdkCheck = {
+    status: 'ok';
+    tree: string;
+    version: string;
+    pinnedVersion: string;
+    fingerprint: string;
+    discoveredVia: SdkDiscoverySource;
+    toolchainDir?: string;
+    toolchainVersion?: string;
+} | {
+    status: 'missing';
+    pinnedVersion: string;
+} | {
+    status: 'version-mismatch';
+    tree: string;
+    version: string;
+    pinnedVersion: string;
+    fingerprint: string;
+    discoveredVia: SdkDiscoverySource;
+    toolchainDir?: string;
+    toolchainVersion?: string;
+} | {
+    status: 'toolchain-mismatch';
+    tree: string;
+    version: string;
+    pinnedVersion: string;
+    fingerprint: string;
+    discoveredVia: SdkDiscoverySource;
+    toolchainDir: string;
+    toolchainVersion: string;
+    pinnedToolchainVersion: string;
+};
+/**
+ * Locate the toolchain SDK dir (the compiler bundle the installer lays
+ * down — distinct from the Zephyr tree): $ZEPHYR_SDK_INSTALL_DIR, the
+ * installer env-vars file, or a `zephyr-sdk-*` sibling of the tree.
+ * Verifies the dir carries an sdk_version file and returns the pair.
+ */
+export declare function findToolchainSdk(tree: string): {
+    toolchainDir: string;
+    toolchainVersion: string;
+} | undefined;
+/**
+ * Check the installed Zephyr SDK against the workspace pin. `tree` is
+ * optional injection for tests; without it, discovery runs (fs-only,
+ * ZEPHYR_BASE authoritative when set). Pure — no throwing, callers decide.
+ */
+export declare function checkZephyrSdk(tree?: string): SdkCheck;
+/**
+ * The create-time gate: throw with actionable guidance unless a matching SDK
+ * is installed. Suppressed by CUTTLEFISH_SDK_CHECK=off (tests / experts who
+ * track their own tree against the looser build-time compat range).
+ */
+export declare function assertZephyrSdkForCreate(): Extract<SdkCheck, {
+    status: 'ok';
+}> | undefined;
+/** Multi-line summary of a successful check — the CLI's indented
+ *  key/value list style (match the `board sync` block's format). */
+export declare function formatZephyrSdkFound(check: Extract<SdkCheck, {
+    status: 'ok';
+}>): string[];

package/dist/board-catalog/sdk.js

@@ -0,0 +1,180 @@
+// ---------------------------------------------------------------------------
+// board-catalog/sdk.ts — the installed Zephyr SDK is the source of truth.
+//
+// `cuttlefish create` gates on this: no SDK, no project. The check is
+// fs-only (the same discovery the catalog store uses) and compares the
+// installed tree against the workspace pin so a project is always created
+// against the SDK the frameworks were validated with.
+//
+// The pin mirrors framework-zephyr's installer/versions.env
+// (ZEPHYR_MANIFEST_REV) — the installer's canonical source. A drift-guard
+// test keeps the two in lockstep; change them together.
+// ----------------------------------------------------------------------------
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { locateZephyrBaseCheap, isZephyrBase, micromambaZephyrBase } from './store.js';
+import { zephyrVersionOf, gitHeadOf } from './walker.js';
+/** The Zephyr manifest revision the workspace pins (installer versions.env). */
+export const PINNED_ZEPHYR_MANIFEST_REV = 'v4.4.2';
+/** The Zephyr SDK (toolchain bundle) version the workspace pins. */
+export const PINNED_ZEPHYR_SDK_VERSION = '1.0.1';
+/** The canonical install command (the installer's own usage strings). */
+export const ZEPHYR_INSTALL_CMD = 'npx --package @typecad/framework-zephyr zephyr-installer';
+/** Env that disables the create-time SDK gate (tests / expert override). */
+export const SDK_CHECK_ENV = 'CUTTLEFISH_SDK_CHECK';
+/** 'v4.4.2' → '4.4.2' (the tree's VERSION file form). */
+function revToVersion(rev) {
+    return rev.replace(/^v/, '');
+}
+/**
+ * Fingerprint of an installed Zephyr tree: version + git HEAD, hashed. This
+ * is the identity the board catalog's provenance already records per-walk;
+ * expose it for humans (`board sync`, `doctor`) and any consumer that wants
+ * to detect "the SDK moved" without comparing fields.
+ */
+export function sdkFingerprint(tree) {
+    if (!isZephyrBase(tree))
+        return undefined;
+    const version = zephyrVersionOf(tree);
+    const head = gitHeadOf(tree) ?? 'no-git';
+    if (!version)
+        return undefined;
+    return createHash('sha1').update(`${version}\0${head}`).digest('hex').slice(0, 16);
+}
+/**
+ * Locate the toolchain SDK dir (the compiler bundle the installer lays
+ * down — distinct from the Zephyr tree): $ZEPHYR_SDK_INSTALL_DIR, the
+ * installer env-vars file, or a `zephyr-sdk-*` sibling of the tree.
+ * Verifies the dir carries an sdk_version file and returns the pair.
+ */
+export function findToolchainSdk(tree) {
+    const candidates = [];
+    if (process.env.ZEPHYR_SDK_INSTALL_DIR)
+        candidates.push(process.env.ZEPHYR_SDK_INSTALL_DIR);
+    const root = process.env.MAMBA_ROOT_PREFIX || path.join(os.homedir(), 'micromamba');
+    const envDir = path.join(root, 'envs', process.env.TYPECAD_ZEPHYR_ENV || 'zephyr');
+    const envVars = process.platform === 'win32'
+        ? [path.join(envDir, 'etc', 'conda', 'env-vars.ps1'), path.join(envDir, 'etc', 'conda', 'env-vars.bat')]
+        : [path.join(envDir, 'etc', 'conda', 'env-vars.sh')];
+    for (const f of envVars) {
+        if (!fs.existsSync(f))
+            continue;
+        try {
+            const m = fs.readFileSync(f, 'utf8').match(/TYPECAD_ZEPHYR_SDK_INSTALL_DIR\s*=\s*"([^"]+)"/);
+            if (m)
+                candidates.push(m[1]);
+        }
+        catch {
+            // unreadable — keep going
+        }
+    }
+    const workspace = path.dirname(path.resolve(tree));
+    for (const entry of fs.existsSync(workspace) ? fs.readdirSync(workspace) : []) {
+        if (/^zephyr-sdk-/.test(entry))
+            candidates.push(path.join(workspace, entry));
+    }
+    for (const dir of candidates) {
+        const versionFile = path.join(dir, 'sdk_version');
+        try {
+            const version = fs.readFileSync(versionFile, 'utf8').trim();
+            if (version)
+                return { toolchainDir: path.resolve(dir), toolchainVersion: version };
+        }
+        catch {
+            // not an SDK dir — try the next candidate
+        }
+    }
+    return undefined;
+}
+/** How the tree at `base` was discovered (for the create printout). */
+function discoverySource(base) {
+    if (process.env.ZEPHYR_BASE && path.resolve(process.env.ZEPHYR_BASE) === base)
+        return 'ZEPHYR_BASE';
+    const installer = micromambaZephyrBase();
+    if (installer && path.resolve(installer) === base)
+        return 'installer env';
+    return 'well-known workspace';
+}
+/**
+ * Check the installed Zephyr SDK against the workspace pin. `tree` is
+ * optional injection for tests; without it, discovery runs (fs-only,
+ * ZEPHYR_BASE authoritative when set). Pure — no throwing, callers decide.
+ */
+export function checkZephyrSdk(tree) {
+    const pinnedVersion = revToVersion(PINNED_ZEPHYR_MANIFEST_REV);
+    let discoveredVia = 'explicit';
+    let base;
+    if (tree !== undefined) {
+        base = isZephyrBase(tree) ? path.resolve(tree) : undefined;
+    }
+    else {
+        base = locateZephyrBaseCheap();
+        if (base)
+            discoveredVia = discoverySource(base);
+    }
+    if (!base)
+        return { status: 'missing', pinnedVersion };
+    const version = zephyrVersionOf(base);
+    const fingerprint = sdkFingerprint(base);
+    if (!version || !fingerprint)
+        return { status: 'missing', pinnedVersion };
+    const toolchain = findToolchainSdk(base);
+    if (version !== pinnedVersion) {
+        return {
+            status: 'version-mismatch', tree: base, version, pinnedVersion, fingerprint,
+            discoveredVia, ...(toolchain ?? {}),
+        };
+    }
+    // The toolchain bundle is the SDK proper — the installer pins it in
+    // lockstep with the manifest revision, so a mismatch means a partial
+    // upgrade (tree re-pinned, toolchains not re-fetched, or vice versa).
+    if (toolchain && toolchain.toolchainVersion !== PINNED_ZEPHYR_SDK_VERSION) {
+        return {
+            status: 'toolchain-mismatch', tree: base, version, pinnedVersion, fingerprint,
+            discoveredVia,
+            toolchainDir: toolchain.toolchainDir,
+            toolchainVersion: toolchain.toolchainVersion,
+            pinnedToolchainVersion: PINNED_ZEPHYR_SDK_VERSION,
+        };
+    }
+    return {
+        status: 'ok', tree: base, version, pinnedVersion, fingerprint,
+        discoveredVia, ...(toolchain ?? {}),
+    };
+}
+/**
+ * The create-time gate: throw with actionable guidance unless a matching SDK
+ * is installed. Suppressed by CUTTLEFISH_SDK_CHECK=off (tests / experts who
+ * track their own tree against the looser build-time compat range).
+ */
+export function assertZephyrSdkForCreate() {
+    if (process.env[SDK_CHECK_ENV] === 'off')
+        return undefined;
+    const check = checkZephyrSdk();
+    if (check.status === 'ok')
+        return check;
+    if (check.status === 'missing') {
+        throw new Error(`No Zephyr SDK found on this machine — a project is only useful with one.\n` +
+            `Install the pinned SDK (Zephyr ${check.pinnedVersion}, toolchain SDK ${PINNED_ZEPHYR_SDK_VERSION}):\n` +
+            `  ${ZEPHYR_INSTALL_CMD}\n` +
+            `Then re-run 'cuttlefish create'. (Set ZEPHYR_BASE if your tree lives elsewhere.)`);
+    }
+    throw new Error(`The installed Zephyr SDK (${check.version} at ${check.tree}) does not match the\n` +
+        `workspace pin (${check.pinnedVersion}). Re-pin your tree to the validated revision:\n` +
+        `  ${ZEPHYR_INSTALL_CMD}            # interactive — re-checks out the pinned revision\n` +
+        `or track your own tree by setting CUTTLEFISH_SDK_CHECK=off (the build-time\n` +
+        `compat check still applies).`);
+}
+/** Multi-line summary of a successful check — the CLI's indented
+ *  key/value list style (match the `board sync` block's format). */
+export function formatZephyrSdkFound(check) {
+    const lines = [
+        `  zephyr:       ${check.version} @ ${check.tree}`,
+    ];
+    lines.push(check.toolchainDir
+        ? `  toolchain:    SDK ${check.toolchainVersion ?? ''} @ ${check.toolchainDir}`
+        : `  toolchain:    not found (west builds still work; some runners may not)`);
+    return lines;
+}