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

package/dist/lowering/hwtimer.js

@@ -0,0 +1,84 @@
+// ---------------------------------------------------------------------------
+// Hardware-timer lowering — Zephyr counter API
+//
+// HAL `hwtimer.*` (instance → frequency/overflow/start/stop) maps onto Zephyr's
+// counter driver (<zephyr/drivers/counter.h>). A chip declares the counter
+// devices it exposes (e.g. nRF RTC1 — RTC0 is kernel-owned) via
+// `hwtimer.controllers[instance].nodeLabel`.
+//
+// Frequency model: a Zephyr counter has a fixed clock; the HAL
+// set_frequency(hz) is realized as a top value of counter_freq/hz with an alarm
+// callback (the on_overflow handler). start() arms both the top value and the
+// callback so the call order (setFrequency → onOverflow → start, or any
+// permutation) is handled uniformly.
+//
+// Targets without a free counter omit `hwtimer`; usage lowers to a comment and
+// profileDiagnostics flags it. The JS setInterval/setTimeout polyfill
+// (k_timer) is a separate surface and is unaffected.
+// ---------------------------------------------------------------------------
+/** Per-instance emitted symbol stems. */
+function devVar(instance) {
+    return `__tc_hw_dev_${instance}`;
+}
+function hzVar(instance) {
+    return `__tc_hw_hz_${instance}`;
+}
+function cbVar(instance) {
+    return `__tc_hw_cb_${instance}`;
+}
+/**
+ * Emit the per-instance counter device handles + frequency/callback state.
+ * Called from shimLines when the program uses hardware timers.
+ */
+export function hwtimerInitLines(chip) {
+    const controllers = chip.hwtimer?.controllers ?? [];
+    if (controllers.length === 0)
+        return [];
+    const lines = ['// CUTTLEFISH_HWTIMER_BEGIN'];
+    controllers.forEach((c, i) => {
+        lines.push(`static const struct device* ${devVar(i)} = DEVICE_DT_GET(DT_NODELABEL(${c.nodeLabel}));`, `static uint32_t ${hzVar(i)} = 1;`, `static counter_top_callback_t ${cbVar(i)} = NULL;`);
+    });
+    lines.push('// CUTTLEFISH_HWTIMER_END');
+    return lines;
+}
+/**
+ * Resolve a HAL hwtimer.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerHwtimer(op, chip) {
+    const o = op;
+    const controllers = chip.hwtimer?.controllers ?? [];
+    // No counter on this target. Comment + (in profileDiagnostics) a clear error.
+    if (controllers.length === 0) {
+        return { code: `/* hwtimer instance ${o.instance}: no counter device on ${chip.id} */` };
+    }
+    const instance = typeof o.instance === 'number' ? o.instance : parseInt(String(o.instance), 10);
+    if (isNaN(instance) || instance < 0 || instance >= controllers.length) {
+        return { code: `/* hwtimer instance ${o.instance}: out of range on ${chip.id} */` };
+    }
+    switch (op.operation) {
+        case 'hwtimer.set_frequency':
+            return { code: `${hzVar(instance)} = ${o.hz};` };
+        case 'hwtimer.on_overflow':
+            return { code: `${cbVar(instance)} = (${o.handler});` };
+        case 'hwtimer.start':
+            // Arm the top value (counter_freq / desired_hz) + the overflow callback,
+            // then start the counter. Doing both here handles any call order — the
+            // HAL typical sequence (setFrequency → onOverflow → start) and permutations.
+            return {
+                code: [
+                    `{`,
+                    `  uint32_t __f = counter_get_frequency(${devVar(instance)});`,
+                    `  uint32_t __top = __f ? (__f / ${hzVar(instance)}) : 0U;`,
+                    `  if (__top > 0U) { (void)counter_set_top_value(${devVar(instance)}, __top, ${cbVar(instance)}, NULL); }`,
+                    `  (void)counter_start(${devVar(instance)});`,
+                    `}`,
+                ].join(' '),
+            };
+        case 'hwtimer.stop':
+            return { code: `(void)counter_stop(${devVar(instance)});` };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/index.d.ts

@@ -18,7 +18,10 @@ import { lowerMqtt } from './mqtt.js';
 import { lowerPreferences } from './preferences.js';
 import { lowerBoard } from './board.js';
 import { lowerRandom } from './random.js';
-export { lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart, lowerInterrupt, lowerWdt, lowerPower, lowerTone, lowerPulseOrShift, lowerBle, lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom, };
+import { lowerDac } from './dac.js';
+import { lowerFs } from './fs.js';
+import { lowerHwtimer } from './hwtimer.js';
+export { lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart, lowerInterrupt, lowerWdt, lowerPower, lowerTone, lowerPulseOrShift, lowerBle, lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom, lowerDac, lowerFs, lowerHwtimer, };
 /**
  * Lower a HAL op to Zephyr C++. Returns undefined for unsupported categories
  * (mirrors lowerHalOp in framework-esp32/src/lowering/index.ts).

package/dist/lowering/index.js

@@ -3,8 +3,8 @@
 //
 // Routes a HALOpIR to the per-category lowering module by category prefix
 // (e.g. 'gpio.write' → lowerGpio). Returns undefined for categories the
-// framework does not lower (display/fs/mdns/ota/rmt/dac/
-// hwtimer/capacitive/temp/espnow/crypto/i2s/twai/usb/eth/pcnt/mcpwm — see
+// framework does not lower (display/mdns/ota/rmt/
+// capacitive/temp/espnow/crypto/i2s/twai/usb/eth/pcnt/mcpwm — see
 // the manifest), so the transpiler falls back and the manifest validator
 // cross-checks the unsupported categories. (board.* is registered below but is
 // a dead-letter — its values are constant-folded at IR-build time.)
@@ -36,7 +36,10 @@ import { lowerMqtt } from './mqtt.js';
 import { lowerPreferences } from './preferences.js';
 import { lowerBoard } from './board.js';
 import { lowerRandom } from './random.js';
-export { lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart, lowerInterrupt, lowerWdt, lowerPower, lowerTone, lowerPulseOrShift, lowerBle, lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom, };
+import { lowerDac } from './dac.js';
+import { lowerFs } from './fs.js';
+import { lowerHwtimer } from './hwtimer.js';
+export { lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart, lowerInterrupt, lowerWdt, lowerPower, lowerTone, lowerPulseOrShift, lowerBle, lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom, lowerDac, lowerFs, lowerHwtimer, };
 /**
  * Lower a HAL op to Zephyr C++. Returns undefined for unsupported categories
  * (mirrors lowerHalOp in framework-esp32/src/lowering/index.ts).
@@ -51,6 +54,8 @@ export function lowerHalOp(op) {
         return lowerAdc(op, chip);
     if (op.operation.startsWith('pwm.'))
         return lowerPwm(op, chip);
+    if (op.operation.startsWith('dac.'))
+        return lowerDac(op, chip);
     if (op.operation.startsWith('i2c.'))
         return lowerI2c(op, chip);
     if (op.operation.startsWith('spi.'))
@@ -61,6 +66,8 @@ export function lowerHalOp(op) {
         return lowerInterrupt(op, chip);
     if (op.operation.startsWith('wdt.'))
         return lowerWdt(op);
+    if (op.operation.startsWith('hwtimer.'))
+        return lowerHwtimer(op, chip);
     if (op.operation.startsWith('power.'))
         return lowerPower(op);
     if (op.operation.startsWith('tone.'))
@@ -80,6 +87,8 @@ export function lowerHalOp(op) {
         return lowerMqtt(op);
     if (op.operation.startsWith('preferences.'))
         return lowerPreferences(op);
+    if (op.operation.startsWith('fs.'))
+        return lowerFs(op);
     // board.resolve is constant-folded at IR-build time; lowerBoard is the
     // dead-letter reached only on an unresolvable path.
     if (op.operation.startsWith('board.'))

package/dist/strategy.js

@@ -15,7 +15,9 @@
 // repository root) and are not subject to the license of this tool source.
 // ---------------------------------------------------------------------------
 import { buildWorkerRuntimePolyfill } from '@typecad/cuttlefish/api/shared';
+import { applyStringMethodRewrites } from '@typecad/cuttlefish/api/shared';
 import { programUsesSafety } from '@typecad/cuttlefish/api';
+import { entryHasUI } from '@typecad/cuttlefish/ui-hook';
 import { chipForTarget, setActiveChip } from './chips/index.js';
 import { resolveChipFromBoard } from './chips/resolve.js';
 import { emitGpioDevDispatcher } from './chips/controllers.js';
@@ -23,6 +25,9 @@ import { lowerHalOp } from './lowering/index.js';
 import { buildZephyrWorkerBacking } from './lowering/worker-backing.js';
 import { adcInitLines } from './lowering/adc.js';
 import { pwmInitLines } from './lowering/pwm.js';
+import { dacInitLines } from './lowering/dac.js';
+import { fsInitLines } from './lowering/fs.js';
+import { hwtimerInitLines } from './lowering/hwtimer.js';
 import { i2cInitLines } from './lowering/i2c.js';
 import { spiInitLines } from './lowering/spi.js';
 import { uartInitLines } from './lowering/uart.js';
@@ -125,6 +130,16 @@ export class ZephyrStrategy {
             inc.push('<zephyr/drivers/adc.h>');
         if (uses('usesPWM'))
             inc.push('<zephyr/drivers/pwm.h>');
+        if (uses('usesDAC'))
+            inc.push('<zephyr/drivers/dac.h>');
+        // Filesystem: littlefs on the storage partition. <cstring> backs the
+        // shim's strlen; the storage/flash_map + fs/littlefs headers carry the
+        // FIXED_PARTITION_ID macro + FS_LITTLEFS_DECLARE_DEFAULT_CONFIG the shim uses.
+        if (uses('usesFS'))
+            inc.push('<zephyr/fs/fs.h>', '<zephyr/fs/littlefs.h>', '<zephyr/storage/flash_map.h>', '<cstring>');
+        // Hardware timers via the counter driver.
+        if (uses('usesHwtimer'))
+            inc.push('<zephyr/drivers/counter.h>');
         if (uses('usesWDT'))
             inc.push('<zephyr/drivers/watchdog.h>');
         if (uses('usesPower'))
@@ -290,22 +305,28 @@ export class ZephyrStrategy {
             lines.push(...adcInitLines(chip));
         if (uses('usesPWM') && chip.pwm)
             lines.push(...pwmInitLines(chip));
+        if (uses('usesDAC') && chip.dac)
+            lines.push(...dacInitLines(chip));
+        if (uses('usesHwtimer') && chip.hwtimer)
+            lines.push(...hwtimerInitLines(chip));
         if (uses('usesInterrupts'))
             lines.push(...interruptInitLines(chip));
         if (uses('usesWDT') && chip.wdt)
             lines.push(...wdtInitLines(chip));
         if (uses('usesBle'))
             lines.push(...bleInitLines());
-        // Display runtime (minimal rect/text renderer): gated on the analyzer's
-        // usesDisplay flag (set by display.* hal-ops). This is the DIRECT-call
-        // display path (user code calling screen.display.fillRect etc.). It is
-        // SUPPRESSED when the UI display adapter is active — the adapter seam
-        // (providesDisplayAdapter/resolveDisplayAdapter) emits its own display_*
-        // runtime that drives the UI rendering pipeline via CuttlefishGFX, and the
-        // two define the same symbols (display_init, __tc_display_line) so emitting
-        // both causes redefinition errors. The adapter is active for the
-        // strategy-owned drivers (ili9341-zephyr, st7796-zephyr).
-        if (uses('usesDisplay') && !this.providesDisplayAdapter()) {
+        // Display runtime (rect/text renderer): the DIRECT-call display path (user
+        // code calling screen.display.fillRect etc., no @typecad/ui). Emitted only
+        // when the program uses display.* but is NOT a UI program — the UI display
+        // adapter (emitted by cuttlefish's emitUIRuntime, solely under entryHasUI())
+        // defines the same display_init symbol, so emitting both would collide.
+        // `providesDisplayAdapter()` is a static capability (always true here) and
+        // does NOT track whether the adapter is actually emitted for THIS build, so
+        // the per-program UI signal (entryHasUI) is the correct gate. Without this,
+        // a direct display.* program has no definition for display_init/
+        // display_fill_rect/draw_rect/draw_text/flush (the gfx runtime was
+        // previously dead code).
+        if (uses('usesDisplay') && !entryHasUI()) {
             const rt = buildDisplayRuntime(this._displayState.profile);
             lines.push(...rt.stateLines);
             lines.push(rt.fontTable);
@@ -319,6 +340,8 @@ export class ZephyrStrategy {
             lines.push(...mqttInitLines());
         if (uses('usesPreferences'))
             lines.push(...preferencesInitLines());
+        if (uses('usesFS'))
+            lines.push(...fsInitLines());
         if (uses('usesRandom'))
             lines.push(...randomInitLines());
         lines.push('#endif // CUTTLEFISH_SHIM_DEFINED');
@@ -384,6 +407,8 @@ export class ZephyrStrategy {
         const outputPins = new Set();
         const adcReadPins = new Set();
         const interruptPins = new Set();
+        const dacPins = new Set();
+        const hwtimerInstances = new Set();
         let usesWifiOps = false;
         let usesHttpOps = false;
         let usesMqttOps = false;
@@ -404,6 +429,16 @@ export class ZephyrStrategy {
                     if (op.operation === 'interrupt.attach' && typeof op.pin === 'number') {
                         interruptPins.add(op.pin);
                     }
+                    if (op.operation === 'dac.write' && typeof op.pin === 'number') {
+                        dacPins.add(op.pin);
+                    }
+                    if (typeof op.operation === 'string' && op.operation.startsWith('hwtimer.')) {
+                        const inst = typeof op.instance === 'number'
+                            ? op.instance
+                            : parseInt(String(op.instance), 10);
+                        if (!isNaN(inst))
+                            hwtimerInstances.add(inst);
+                    }
                     if (typeof op.operation === 'string' && op.operation.startsWith('wifi.')) {
                         usesWifiOps = true;
                     }
@@ -464,6 +499,55 @@ export class ZephyrStrategy {
                 });
             }
         }
+        // ── DAC pin validity ────────────────────────────────────────────────────
+        // dac.write resolves a HAL pin to a channel via the chip descriptor's
+        // dac.channels map. A pin not in that map lowers to a comment (silent
+        // no-op), and a chip without a `dac` entry (nRF52840, ESP32-S3) has no DAC
+        // at all. Flag either case so the user gets a clear message instead of a
+        // pin that silently does nothing.
+        if (dacPins.size > 0) {
+            const dacChannels = new Set((chip.dac?.channels ?? []).map((c) => c.pin));
+            for (const pin of dacPins) {
+                if (!dacChannels.has(pin)) {
+                    diags.push({
+                        severity: 'error',
+                        code: 'zephyr-dac-pin-unavailable',
+                        message: `GPIO ${pin} is not a DAC channel on ${chip.id} and cannot be driven with dac.write.`,
+                        hint: dacChannels.size > 0
+                            ? `Use a DAC-capable pin. On ${chip.id}: ${[...dacChannels].sort((x, y) => x - y).join(', ')}.`
+                            : `${chip.id} has no DAC. Use an esp32_devkitc target (ESP32 DAC on GPIO25/26).`,
+                        source: program.fileName,
+                    });
+                }
+            }
+        }
+        // ── Hardware-timer instance validity ────────────────────────────────────
+        // hwtimer.* resolves the instance index to a counter device via the chip
+        // descriptor's hwtimer.controllers. A chip without that entry (or an
+        // out-of-range instance) lowers to a comment — flag it so the user knows
+        // the timer will never fire.
+        if (hwtimerInstances.size > 0) {
+            const controllerCount = chip.hwtimer?.controllers.length ?? 0;
+            for (const inst of hwtimerInstances) {
+                if (controllerCount === 0) {
+                    diags.push({
+                        severity: 'error',
+                        code: 'zephyr-hwtimer-unavailable',
+                        message: `Hardware timer instance ${inst} is used but ${chip.id} exposes no free counter device.`,
+                        hint: `${chip.id} declares no hwtimer.controllers. Use a target with a free counter (e.g. nRF RTC1).`,
+                        source: program.fileName,
+                    });
+                }
+                else if (inst < 0 || inst >= controllerCount) {
+                    diags.push({
+                        severity: 'error',
+                        code: 'zephyr-hwtimer-instance-out-of-range',
+                        message: `Hardware timer instance ${inst} is out of range on ${chip.id} (0..${controllerCount - 1}).`,
+                        source: program.fileName,
+                    });
+                }
+            }
+        }
         // ── WiFi target validity ────────────────────────────────────────────────
         // WiFi ops require a chip with a WiFi radio. The ESP32-S3 descriptor sets
         // wifi.supported; the XIAO nRF52840 omits it (no radio). Flag wifi usage on
@@ -592,6 +676,18 @@ export class ZephyrStrategy {
             v = v.replace(/\bundefined\b/g, 'CUTTLEFISH_UNDEFINED');
             v = v.replace(/\bnull\b/g, 'CUTTLEFISH_UNDEFINED');
         }
+        // String-method lowering is shared across targets (see string-method-
+        // registry). Zephyr's strings are const char*, so the __tc_* helpers this
+        // rewrites to (defined by the string_methods polyfill) take const char*.
+        // includes/startsWith lower to inline strstr/strncmp (matching framework-
+        // arduino); everything else → a __tc_* helper call.
+        v = applyStringMethodRewrites(v, {
+            wrapReceiverFor: new Set(['indexOf']),
+            special: {
+                includes: (recv, args) => `(strstr(${recv}, ${args[0]}) != NULL)`,
+                startsWith: (recv, args) => `(strncmp(${recv}, ${args[0]}, strlen(${args[0]})) == 0)`,
+            },
+        });
         return v;
     }
     nullValue() {
@@ -840,15 +936,22 @@ export class ZephyrStrategy {
         };
     }
     // ── Polyfills ───────────────────────────────────────────────────────────
-    // No native polyfills for the MVP — the shared runtime's string/array
-    // polyfills are pulled in when a program uses them. cuttlefish_halt is the
-    // one symbol the runtime header may reference; supply it as a halt loop.
+    // Zephyr is a no-STL target (hasVector/hasString = false), so array/string
+    // literals lower to __tc_StaticArray / const char* and string methods lower
+    // to __tc_* helpers — both need STL-free definitions emitted here (there is
+    // no shared-runtime fallback; the pipeline sources 100% of polyfills from
+    // generateNativePolyfills). Mirrors framework-arduino's AVR polyfills.
     nativePolyfills() {
         // cuttlefish_halt: always (the runtime header may reference it).
+        // string_methods / static_array: STL-free array + string helpers a no-STL
+        //   target needs (mutated/struct array literals + any string method).
         // timer_methods: k_timer/k_work pool for setInterval/setTimeout (gated on
         //   timerCallCount at emit time in generateNativePolyfills).
         // async_runtime: heap-free static Promise/microtask runtime (no STL needed).
-        return new Set(['cuttlefish_halt', 'wiring_compat', 'timer_methods', 'async_runtime']);
+        return new Set([
+            'cuttlefish_halt', 'wiring_compat', 'string_methods', 'static_array',
+            'timer_methods', 'async_runtime',
+        ]);
     }
     generateNativePolyfills(program, ctx) {
         const polyfills = [
@@ -897,6 +1000,75 @@ export class ZephyrStrategy {
                 ],
                 dependencies: [],
             },
+            {
+                // STL-free string-method polyfills. String methods (.toUpperCase(),
+                // .includes(), .substring(), …) lower at IR level to __tc_* helpers for
+                // every target; this supplies their definitions. Minimal-libc friendly:
+                // only <cstring> primitives (no <cctype> — case conversion is inline
+                // ASCII so the polyfill is self-contained). Mirrors framework-arduino.
+                kind: 'polyfill',
+                id: 'string_methods',
+                domain: 'embedded',
+                requiredIncludes: ['<cstring>'],
+                forwardDeclarations: [],
+                helperStructs: [],
+                helperFunctions: [`
+// TypeCAD string method polyfills (Zephyr, minimal-libc).
+#ifndef CUTTLEFISH_STR_BUF_SIZE
+#define CUTTLEFISH_STR_BUF_SIZE 64
+#endif
+bool __tc_endsWith(const char* s, const char* suffix) { int sl = strlen(s), tl = strlen(suffix); return sl >= tl && strcmp(s + sl - tl, suffix) == 0; }
+const char* __tc_toUpperCase(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; for (char* p = b; *p; p++) { if (*p >= 'a' && *p <= 'z') { *p = static_cast<char>(*p - 32); } } return b; }
+const char* __tc_toLowerCase(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; for (char* p = b; *p; p++) { if (*p >= 'A' && *p <= 'Z') { *p = static_cast<char>(*p + 32); } } return b; }
+const char* __tc_trim(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; while (*s == ' ' || *s == '\\t' || *s == '\\n' || *s == '\\r') s++; int len = strlen(s); while (len > 0 && (s[len-1] == ' ' || s[len-1] == '\\t' || s[len-1] == '\\n' || s[len-1] == '\\r')) len--; int cplen = len < CUTTLEFISH_STR_BUF_SIZE - 1 ? len : CUTTLEFISH_STR_BUF_SIZE - 1; strncpy(b, s, cplen); b[cplen] = '\\0'; return b; }
+const char* __tc_substring2(const char* s, int start, int end) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; int slen = strlen(s); if (start < 0) start = 0; if (end > slen) end = slen; if (end < start) end = start; int len = end - start; if (len >= CUTTLEFISH_STR_BUF_SIZE) len = CUTTLEFISH_STR_BUF_SIZE - 1; strncpy(b, s + start, len); b[len] = '\\0'; return b; }
+const char* __tc_substring1(const char* s, int start) { return __tc_substring2(s, start, strlen(s)); }
+const char* __tc_slice2(const char* s, int start, int end) { return __tc_substring2(s, start, end); }
+const char* __tc_slice1(const char* s, int start) { return __tc_substring2(s, start, strlen(s)); }
+const char* __tc_replace(const char* s, const char* old, const char* repl) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; const char* pos = strstr(s, old); if (!pos) { strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; return b; } int beforeLen = static_cast<int>(pos - s); int oldLen = static_cast<int>(strlen(old)); int replLen = static_cast<int>(strlen(repl)); if (beforeLen + replLen + static_cast<int>(strlen(pos + oldLen)) >= CUTTLEFISH_STR_BUF_SIZE) { strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; return b; } memcpy(b, s, beforeLen); memcpy(b + beforeLen, repl, replLen); strcpy(b + beforeLen + replLen, pos + oldLen); return b; }
+const char* __tc_charAt(const char* s, int idx) { static char buf[2][2]; static uint8_t slot = 0; slot ^= 1; buf[slot][0] = s[idx]; buf[slot][1] = '\\0'; return buf[slot]; }
+int __tc_charCodeAt(const char* s, int idx) { return static_cast<int>(static_cast<unsigned char>(s[idx])); }
+int __tc_indexOf(const char* s, const char* needle) { const char* p = strstr(s, needle); return p ? static_cast<int>(p - s) : -1; }
+`],
+                shimMacros: [],
+                dependencies: [],
+            },
+            {
+                // STL-free fixed-size array wrapper. Mutated/struct-element array
+                // literals and array methods (.push/.pop/.map/.filter) lower to
+                // __tc_StaticArray<T,N>; this supplies the template. Idempotent guard
+                // so a redefinition is a no-op. Mirrors framework-arduino.
+                kind: 'polyfill',
+                id: 'static_array',
+                domain: 'embedded',
+                requiredIncludes: [],
+                forwardDeclarations: [],
+                helperStructs: [],
+                helperFunctions: [`
+#ifndef __TC_STATIC_ARRAY_DEFINED
+#define __TC_STATIC_ARRAY_DEFINED
+template<typename T, int N>
+struct __tc_StaticArray {
+    T data[N];
+    int _size;
+    __tc_StaticArray() : _size(0) {}
+    int length() const { return _size; }
+    int size() const { return _size; }
+    void push(T val) { if (_size < N) data[_size++] = val; }
+    T pop() { return (_size > 0) ? data[--_size] : T(); }
+    int indexOf(T val) const { for (int i = 0; i < _size; i++) if (data[i] == val) return i; return -1; }
+    T& operator[](int i) { return data[i]; }
+    const T& operator[](int i) const { return data[i]; }
+    T* begin() { return &data[0]; }
+    T* end() { return &data[_size]; }
+    const T* begin() const { return &data[0]; }
+    const T* end() const { return &data[_size]; }
+};
+#endif
+`],
+                shimMacros: [],
+                dependencies: [],
+            },
         ];
         // Worker-offload runtime (Phase 1). Emitted only when the program uses
         // worker.* ops, backed by the Zephyr primitives in worker-backing.ts

package/dist/toolchain/compat.js

@@ -15,6 +15,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import manifest from '../framework.manifest.js';
+import { discoverWest } from './west-discover.js';
 // ── minimal semver ──────────────────────────────────────────────────────────
 /** Parse "4.3.99" / "v4.3" / "4.3.99-rc1" → [4, 3, 99]. Undefined if unparseable. */
 export function parseVersion(v) {
@@ -70,7 +71,15 @@ export function satisfiesRange(version, range) {
  * and a bare "4.3.99".
  */
 export function detectZephyrVersion() {
-    const base = process.env.ZEPHYR_BASE;
+    let base = process.env.ZEPHYR_BASE;
+    if (!base) {
+        // Fall back to the discovered west install's zephyrBase — covers the
+        // micromamba env from @typecad/zephyr-installer WITHOUT activation.
+        // (micromamba run sets ZEPHYR_BASE only inside the west subprocess; this
+        // makes the compat check work in the parent cuttlefish process too.)
+        const install = discoverWest();
+        base = install?.zephyrBase;
+    }
     if (!base)
         return undefined;
     let content;

package/dist/toolchain/env-check.d.ts

@@ -0,0 +1,93 @@
+import { type WestInstall } from './west-discover.js';
+import { type CompatStatus } from './compat.js';
+/**
+ * Raw west facts gathered from discovery + a `west --version` probe. Mirrors
+ * ArduinoCliProbeData: `westFound` is true when a usable west install was
+ * discovered (discovery itself probes responsiveness).
+ */
+export interface WestProbeData {
+    /** A usable west install was discovered. */
+    westFound: boolean;
+    /** west version string if the `--version` probe parsed one, e.g. "1.3.0". */
+    westVersion: string | undefined;
+    /** Which discovery strategy found west, for surfacing to the user. */
+    source: WestInstall['source'] | undefined;
+    /** Effective ZEPHYR_BASE (env var, else a base discovery surfaced). */
+    zephyrBase: string | undefined;
+}
+/**
+ * Test-injection seam for checkZephyrEnv. Mirrors Arduino's
+ * CheckArduinoEnvOptions.fakeProbe so tests never spawn a real west/python.
+ */
+export interface CheckZephyrEnvOptions {
+    /** FOR TESTS ONLY: skip the real probe and use this data directly. */
+    fakeWestProbe?: WestProbeData;
+    /** FOR TESTS ONLY: override the board-existence lookup. */
+    fakeBoardExists?: (boardId: string, zephyrBase: string | undefined) => boolean | undefined;
+}
+export interface ZephyrEnvCheck {
+    /** west (the Zephyr build tool) was discovered and responsive. */
+    westFound: boolean;
+    /** west version string if known, e.g. "1.3.0". */
+    westVersion: string | undefined;
+    /** Discovery strategy that found west, for display. */
+    westSource: WestInstall['source'] | undefined;
+    /** Effective ZEPHYR_BASE (env var, else a discovered base). */
+    zephyrBase: string | undefined;
+    /** Detected Zephyr RTOS version from $ZEPHYR_BASE/VERSION, if readable. */
+    zephyrVersion: string | undefined;
+    /** Declared supported range (manifest.compat.zephyr), if any. */
+    compatRange: string | undefined;
+    /** Result of the compat-range check against the detected version. */
+    compatStatus: CompatStatus;
+    /** Raw board target from cuttlefish.config.ts, if configured. */
+    buildTarget: string | undefined;
+    /** buildTarget normalized for the installed Zephyr version (may equal it). */
+    resolvedBoardTarget: string | undefined;
+    /** Does the resolved board exist in the checkout? undefined = undetermined. */
+    boardTargetSupported: boolean | undefined;
+}
+export type ZephyrEnvOk = {
+    ok: true;
+    check: ZephyrEnvCheck;
+};
+export type ZephyrEnvFailure = {
+    ok: false;
+    reason: 'west-not-found' | 'zephyr-out-of-range' | 'board-not-supported';
+    check: ZephyrEnvCheck;
+    /** Human-readable lines ready to print. */
+    messages: string[];
+    /** Exact remediation hint, when applicable. */
+    fixCommand: string | undefined;
+};
+export type ZephyrEnvResult = ZephyrEnvOk | ZephyrEnvFailure;
+/** Clear the west-probe cache (for tests). Also resets discovery cache. */
+export declare function resetWestProbeCacheForTest(): void;
+/**
+ * Gather west facts: discover a usable install, then run `west --version`
+ * through it to capture the version. Memoized for the process lifetime (west
+ * installs don't move). Never throws — returns westFound:false on any failure.
+ */
+export declare function probeWestEnv(): WestProbeData;
+/**
+ * Does `boardId` exist as a board directory in the Zephyr checkout? Checks the
+ * HWMv2 vendor layout used by Zephyr 4.x: $ZEPHYR_BASE/boards/<vendor>/<boardId>.
+ * Returns true/false when determinable; undefined when the base is unknown or
+ * the boards/ tree can't be read (so callers never fail on an inconclusive
+ * lookup — they just skip the board check).
+ */
+export declare function boardExistsInCheckout(boardId: string, zephyrBase: string | undefined): boolean | undefined;
+/**
+ * Verify the environment can build for `buildTarget`. Cheap and
+ * side-effect-free: discovers west, reads the Zephyr version, checks the compat
+ * range, and — when a target is configured — verifies the board exists in the
+ * checkout. Reports what (if anything) is wrong.
+ *
+ * - If `buildTarget` is undefined/empty, the board check is skipped (not a
+ *   failure), mirroring Arduino's no-FQBN path.
+ * - Never installs anything. Never mutates the user environment.
+ * - Never throws — always returns a result. Callers decide how to react.
+ *
+ * `options` is for-test only (injects fake probe data / board lookup).
+ */
+export declare function checkZephyrEnv(buildTarget?: string, options?: CheckZephyrEnvOptions): ZephyrEnvResult;