@typecad/framework-zephyr 1.0.0-alpha.16 → 1.0.0-alpha.18

package/dist/strategy.js

@@ -25,6 +25,22 @@ import { syncBoardCatalog, ensureFreshBoardCatalog, } from './sdk/board-catalog-
 import { setActiveChip, NO_BOARD_CHIP } from './chips/index.js';
 import { resolveChipFromBoard } from './chips/resolve.js';
 import { emitGpioDevDispatcher } from './chips/controllers.js';
+/**
+ * Visit the program's transpile-resolved HAL ops with the same `visit` the IR
+ * walk uses. A HAL call inlined into another HAL call's template literal
+ * (`USB0.writeLine(\`n: ${gps.available()}\`)`) is lowered to C++ text while
+ * the IR is built — it never becomes a hal-op/hal-expr IR node, so the walk
+ * alone cannot see it. Such ops ride on ProgramIR.resolvedHalOps; wrapped as
+ * `{ operation: op }` they match the hal-op node shape every collector below
+ * tests for. Without this fold, shims keyed on these scans (UART RX rings,
+ * sensor device handles, per-controller bus state, ADC channels/overrides,
+ * dt specs) go undeclared while the baked text still references them — the
+ * `'__tc_dt_led0' was not declared` failure class.
+ */
+function visitResolvedHalOps(program, visit) {
+    for (const op of program?.resolvedHalOps ?? [])
+        visit({ operation: op });
+}
 /**
  * Deep-walk the program IR and collect the HAL pin numbers the program
  * actually touches for a peripheral family ('adc' | 'pwm') — the same walk
@@ -64,6 +80,7 @@ function collectUsedPins(program, kind, chip) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return pins;
 }
 /**
@@ -99,6 +116,7 @@ function collectAdcOverrideDevices(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return devices;
 }
 /**
@@ -136,6 +154,7 @@ function collectPwmOverrideSpecs(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return specs;
 }
 /**
@@ -185,6 +204,7 @@ function collectUsedBusIndices(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return indices;
 }
 /**
@@ -228,6 +248,7 @@ export function collectSensors(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return sensors;
 }
 /**
@@ -266,6 +287,7 @@ export function collectSpiTargets(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return targets;
 }
 /**
@@ -305,6 +327,7 @@ export function collectUartRings(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return rings;
 }
 /**
@@ -339,6 +362,7 @@ export function collectThreads(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return threads;
 }
 import { lowerHalOp } from './lowering/index.js';
@@ -385,13 +409,15 @@ import { httpInitLines } from './lowering/http.js';
 import { mqttInitLines } from './lowering/mqtt.js';
 import { preferencesInitLines } from './lowering/preferences.js';
 import { randomInitLines } from './lowering/random.js';
-import { generateZephyrInitCode, generateZephyrBreakpointCode, generateZephyrLogpointCode } from './debug-codegen.js';
 import { generateStaticAsyncRuntime } from '@typecad/cuttlefish/api/shared';
 import { resolveZephyrDisplayOp, newDisplayState } from './display/index.js';
 import { buildDisplayRuntime } from './display/gfx.js';
 import { ZEPHYR_DISPLAY_PROFILES, BUILT_IN_PROFILES } from './display/profiles.js';
 import { zephyrDisplayAdapterGenerator } from './display/ui-adapter.js';
 import { zephyrTouchAdapter } from './display/touch-adapter.js';
+/** debugMode() memo — the boardgen facts lookup is not free and the method is
+ *  called several times per build (transpile gate + artifact writers). */
+const debugModeMemo = new Map();
 export class ZephyrStrategy {
     constructor() {
         this.id = 'zephyr';
@@ -437,22 +463,7 @@ export class ZephyrStrategy {
         setActiveChip(fromBoard ?? NO_BOARD_CHIP);
         return fromBoard ?? NO_BOARD_CHIP;
     }
-    /**
-     * Resolve the debug mode for the active target from the platform context.
-     * Mirrors resolveChip's target extraction so shimLines/forcedIncludes can
-     * gate the printf halt shim + console UART include to printf builds only
-     * (gdb builds use VS Code native breakpoints + #line markers, so the
-     * __tc_debug_wait_for_continue shim and its <zephyr/drivers/uart.h> include
-     * are dead code there).
-     */
-    resolveDebugMode(ctx) {
-        const fd = ctx?.frameworkData;
-        const target = fd?.target ??
-            fd?.buildTarget;
-        return this.debugMode(target);
-    }
     forcedIncludes(_program, ctx) {
-        const isPrintf = this.resolveDebugMode(ctx) === 'printf';
         // <zephyr/kernel.h> for k_msleep / k_uptime_get_32 / k_busy_wait / printk.
         // <zephyr/drivers/gpio.h> for the gpio_pin_*_dt / gpio_dt_spec API.
         // <cstdint> because DIRECT_CPP_TYPE_MAP passes int32_t/uint8_t through
@@ -473,7 +484,7 @@ export class ZephyrStrategy {
         // passes int32_t/uint8_t through verbatim.
         const inc = ['<zephyr/kernel.h>', '<zephyr/drivers/gpio.h>', '<cstdint>'];
         // <cstdio> backs the printf family only: __tc_print/__tc_println (emitted
-        // solely when @typecad/expect's preprocessor injected them — tracked via
+        // solely when the test-runner preprocessor injected them — tracked via
         // usedPolyfillHelpers), raw printf/snprintf in user code (usesCstdio), and
         // the fs/preferences/uart shims (their lowerings snprintf into buffers).
         // A program touching none of those needs no <cstdio>.
@@ -491,12 +502,6 @@ export class ZephyrStrategy {
             inc.push('<zephyr/drivers/spi.h>');
         if (uses('usesUart'))
             inc.push('<zephyr/drivers/uart.h>');
-        // uart.h is also needed by the printf-mode debug halt shim
-        // (__tc_debug_wait_for_continue polls the console UART) even when the
-        // program itself does not use the UART HAL. In gdb mode the shim is not
-        // emitted, so skip the include there to avoid pulling in an unused header.
-        if (isPrintf && !inc.includes('<zephyr/drivers/uart.h>'))
-            inc.push('<zephyr/drivers/uart.h>');
         // USB CDC serial: the class instance is a UART device (uart.h); the
         // device context macros + usbd_* API live in the next-stack header.
         if (uses('usesUsb')) {
@@ -550,10 +555,11 @@ export class ZephyrStrategy {
         // HTTP/S client: Zephyr's http_client_req runs over a pre-connected socket,
         // so the shim pulls in the BSD socket + POSIX DNS surfaces alongside the
         // http client/parser headers. TLS sec tags need tls_credentials; <cstring>
-        // /<cstdlib> back the shim's memcpy/strlen/new-nothrow usage (the core
-        // shim only includes <cstdio>/<cstdint>).
+        // /<cstdlib>/<new> back the shim's memcpy/strlen/new-nothrow usage (the
+        // core shim only includes <cstdio>/<cstdint> — std::nothrow is not
+        // guaranteed to arrive transitively).
         if (uses('usesHttp'))
-            inc.push('<zephyr/net/socket.h>', '<zephyr/net/http/client.h>', '<zephyr/net/http/parser.h>', '<zephyr/net/tls_credentials.h>', '<zephyr/posix/sys/socket.h>', '<cstring>', '<cstdlib>');
+            inc.push('<zephyr/net/socket.h>', '<zephyr/net/http/client.h>', '<zephyr/net/http/parser.h>', '<zephyr/net/tls_credentials.h>', '<zephyr/posix/sys/socket.h>', '<cstring>', '<cstdlib>', '<new>');
         // MQTT client: <zephyr/net/mqtt.h> for mqtt_connect/publish/subscribe, plus
         // <zephyr/net/socket.h> for the zsock_* poll/getaddrinfo API the shim's poll
         // thread uses, and <zephyr/net/tls_credentials.h> for the mqtts:// path
@@ -608,6 +614,10 @@ export class ZephyrStrategy {
                 return;
             }
             for (const v of Object.values(node)) {
+                if (typeof v === 'string' && v.includes(TOKEN)) {
+                    found = true;
+                    return;
+                }
                 if (Array.isArray(v)) {
                     for (const item of v)
                         visit(item);
@@ -620,9 +630,17 @@ export class ZephyrStrategy {
         return found;
     }
     /** Pins referenced by gpio.* hal-ops in the program IR. lowerGpio routes a
-     *  pin to its devicetree spec by pin NUMBER, so the structured hal-op pins
-     *  are the authoritative signal for which __tc_dt_* specs are needed —
-     *  regardless of when the final call text is rendered. */
+     * pin to its devicetree spec by pin NUMBER, so the structured hal-op pins
+     * are the authoritative signal for which __tc_dt_* specs are needed —
+     * regardless of when the final call text is rendered.
+     *
+     * A gpio op interpolated into another HAL call's template literal
+     * (`USB0.writeLine(\`led: ${led.get()}\`)`) never becomes an IR node —
+     * resolveHALExprToText lowers it to C++ text while building the IR and bakes
+     * it into an __EMIT__ snprintf prelude, so the walk cannot see its pin. The
+     * spec NAME it references is still in that text; collectRawMatches finds it
+     * there, or the spec goes undeclared and the build fails on `__tc_dt_led0
+     * was not declared in this scope`. */
     collectGpioPinUsage(program) {
         const pins = new Set();
         if (!program)
@@ -646,13 +664,18 @@ export class ZephyrStrategy {
             }
         };
         visit(program);
+        visitResolvedHalOps(program, visit);
         return pins;
     }
     /** Run `re` (global) against every raw string in the IR — raw expression
-     *  values plus raw hal-op codes — returning capture group 1 of each match
-     *  (the full match when the regex has no group). This is how references the
-     *  text scanners must see but that never appear as IR call nodes (e.g. a
-     *  rawCpp() escape hatch naming `__tc_dt_sw0` directly) are discovered. */
+     * values plus raw hal-op codes — returning capture group 1 of each match
+     * (the full match when the regex has no group). This is how references the
+     * text scanners must see but that never appear as IR call nodes are
+     * discovered: a rawCpp() escape hatch naming `__tc_dt_sw0` directly, and —
+     * the reason every string LEAF is scanned, not just raw nodes — the
+     * pre-lowered C++ text of a HAL call inlined into another HAL call's
+     * template literal, which the IR builder bakes into plain `string` payloads
+     * (__EMIT__ snprintf preludes, op data fields) rather than raw nodes. */
     collectRawMatches(program, re) {
         const found = new Set();
         if (!program)
@@ -664,14 +687,10 @@ export class ZephyrStrategy {
         const visit = (node) => {
             if (!node || typeof node !== 'object')
                 return;
-            if (node.kind === 'raw' && typeof node.value === 'string')
-                scan(node.value);
-            if (node.operation && typeof node.operation === 'object'
-                && node.operation.operation === 'raw' && typeof node.operation.code === 'string') {
-                scan(node.operation.code);
-            }
             for (const v of Object.values(node)) {
-                if (Array.isArray(v)) {
+                if (typeof v === 'string')
+                    scan(v);
+                else if (Array.isArray(v)) {
                     for (const item of v)
                         visit(item);
                 }
@@ -700,7 +719,6 @@ export class ZephyrStrategy {
     }
     shimLines(program, ctx) {
         const chip = this.resolveChip(ctx, program);
-        const isPrintf = this.resolveDebugMode(ctx) === 'printf';
         const a = ctx?.analysis;
         const uses = (f) => (a ? !!a[f] : true);
         const helpers = a?.usedPolyfillHelpers;
@@ -764,7 +782,7 @@ export class ZephyrStrategy {
         if (entryHasUI()) {
             guardBody.push('#ifndef PROGMEM', '#define PROGMEM', '#endif');
         }
-        // Test-runner console helpers: @typecad/expect's Zephyr shim calls these
+        // Test-runner console helpers: the test-runner's Zephyr shim calls these
         // for protocol output. Overloaded for string (const char*) and numeric
         // (double) so the same call site works for markers and test values.
         // The fs lowering bakes __tc_println into its error paths too, so the
@@ -953,13 +971,15 @@ export class ZephyrStrategy {
             lines.push('// cuttlefish runtime shim. Wrapped in a single include guard so the', '// block is safe to emit into multiple headers and .cpp files within', '// one translation unit (a .cpp may #include several headers that each', '// carry the shim). The guard ensures the definitions are seen exactly', '// once per TU.', '#ifndef CUTTLEFISH_SHIM_DEFINED', '#define CUTTLEFISH_SHIM_DEFINED', ...guardBody, '#endif // CUTTLEFISH_SHIM_DEFINED');
         }
         // Devicetree specs — one per board-defined GPIO pin, but ONLY for pins the
-        // program actually addresses (lowerGpio routes by pin number, and the
-        // structured gpio.* hal-op pins are visible here) plus aliases named
-        // verbatim in raw code (rawCpp escape hatches). Emitted OUTSIDE the single
-        // CUTTLEFISH_SHIM_DEFINED guard with a per-symbol guard: per-file pin sets
-        // differ, and in a multi-header TU the first header's TU-wide guard would
-        // otherwise hide the second header's specs. Without a program (capability
-        // query), emit them all.
+        // program actually addresses (lowerGpio routes by pin number; the
+        // structured gpio.* hal-op pins plus the spec names appearing in any IR
+        // string — including the pre-lowered text of a HAL call inlined into
+        // another HAL call's template literal — are visible here) and aliases
+        // named verbatim in raw code (rawCpp escape hatches). Emitted OUTSIDE the
+        // single CUTTLEFISH_SHIM_DEFINED guard with a per-symbol guard: per-file
+        // pin sets differ, and in a multi-header TU the first header's TU-wide
+        // guard would otherwise hide the second header's specs. Without a program
+        // (capability query), emit them all.
         const usedPins = this.collectGpioPinUsage(program);
         const dtTextRefs = this.collectRawMatches(program, /__tc_dt_([A-Za-z0-9_]+)/g);
         for (const spec of chip.gpio.dtSpecs) {
@@ -968,32 +988,6 @@ export class ZephyrStrategy {
             const guard = `__TC_DT_${spec.dtSpec.replace(/[^A-Za-z0-9_]/g, '_').toUpperCase()}_SPEC`;
             lines.push(`#ifndef ${guard}`, `#define ${guard}`, `static const struct gpio_dt_spec __tc_dt_${spec.dtSpec} = GPIO_DT_SPEC_GET(DT_ALIAS(${spec.dtSpec}), gpios);`, `#endif // ${guard}`);
         }
-        // --- Debug-mode halt + per-breakpoint disable registry ---
-        //
-        // Printf mode only. In gdb mode the cuttlefish debug preprocessor is
-        // skipped (core emits #line markers + VS Code native breakpoints instead),
-        // so __tc_debug_wait_for_continue is never called — skip the shim and its
-        // <zephyr/drivers/uart.h> dependency entirely (forcedIncludes mirrors this).
-        //
-        // The cuttlefish debug preprocessor injects __tc_debug_wait_for_continue(id)
-        // calls at each breakpoint; without these definitions the emitted code
-        // would not link.
-        //
-        // Zephyr's minimal libc has no getchar()/EOF, so the halt polls the console
-        // UART directly via uart_poll_in on the system console device, yielding to
-        // the scheduler with k_msleep between polls so an unattended breakpoint
-        // does not starve the system. ENTER (or any non-'s' byte) = continue;
-        // 's'/'S' = skip this breakpoint for the rest of the run (records the id).
-        if (isPrintf) {
-            lines.push('#ifndef __TC_BP_DISABLED_DEFINED', '#define __TC_BP_DISABLED_DEFINED', 'static bool __tc_bp_disabled[256] = {0};', 'static inline bool __tc_bp_is_disabled(int id) { return id >= 0 && id < 256 && __tc_bp_disabled[id]; }', 
-            // Console input: poll the UART console device. DEVICE_DT_GET(DT_CHOSEN(zephyr_console))
-            // resolves to the board's console (UART0 USB-CDC on the XIAO nRF52840).
-            // Not every board DTS declares a zephyr,console chosen (STM32MP1 M-side,
-            // display/carrier boards): there is nothing to print a prompt on and
-            // nothing to read a key from, so breakpoints auto-continue instead of
-            // hanging an unattended run.
-            '#if DT_HAS_CHOSEN(zephyr_console)', 'static inline char __tc_debug_wait_for_continue(int id) {', '    const struct device* __con = DEVICE_DT_GET(DT_CHOSEN(zephyr_console));', '    unsigned char __c = 0;', "    while (uart_poll_in(__con, &__c) != 0) {", '        k_msleep(10);', '    }', "    // Drain the rest of the typed line so the next breakpoint waits fresh.", "    unsigned char __peek = 0;", "    while (uart_poll_in(__con, &__peek) == 0 && __peek != '\\n') { (void)0; }", "    if ((__c == 's') || (__c == 'S')) { if (id >= 0 && id < 256) __tc_bp_disabled[id] = true; }", '    return static_cast<char>(__c);', '}', '#else', 'static inline char __tc_debug_wait_for_continue(int id) { (void)id; return static_cast<char>(0); }', '#endif // DT_HAS_CHOSEN(zephyr_console)', '#endif // __TC_BP_DISABLED_DEFINED', '');
-        }
         // --- Zephyr entrypoint ---------------------------------------------------
         // No bridge here: the synthesizer emits main() itself (it keys off
         // entrypointFunctionName()="main" and requiresLoopFunction()=false), with
@@ -1556,10 +1550,13 @@ export class ZephyrStrategy {
     // ── Interrupt safety ─────────────────────────────────────────────────────
     // Zephyr ISRs run above thread context: anything that sleeps (k_msleep),
     // pends, or takes a driver lock is illegal there (asserted by the kernel in
-    // debug builds; corrupts scheduler state otherwise). The names below are the
-    // IR-level callees cuttlefish's interrupt-analysis pass matches (the same
-    // keys ArduinoStrategy uses; timing.delay/delay_microseconds hal-ops are
-    // mapped back to the bare names by the analyzer itself).
+    // debug builds; corrupts scheduler state otherwise). The keys below are
+    // matched by cuttlefish's interrupt-analysis pass in two shapes: bare/qualified
+    // callee names (call statements) and resolved hal-op payloads — the analyzer
+    // maps timing.delay/delay_microseconds/sleep/busy_wait_us ops back to the
+    // bare timing keys, and matches the op payload's port/bus field (UART0,
+    // I2C0, SPI0, …) against these keys directly. The same keys ArduinoStrategy
+    // uses.
     isrUnsafeOperations() {
         return new Map([
             ['delay', {
@@ -1698,14 +1695,14 @@ export class ZephyrStrategy {
         catch (err) {
             // A malformed facts/as-built file is the USER's error — surface it
             // verbatim instead of the generic "cannot generate" below.
-            if (err instanceof Error && (err.message.includes('cuttlefish.facts.json') || err.message.includes('as-built.json')))
+            if (err instanceof Error && (err.message.includes('typecad-hal.facts.json') || err.message.includes('as-built.json')))
                 throw err;
             return undefined;
         }
     }
     /**
      * Regenerate the board catalog overlay from the user's own Zephyr tree —
-     * `cuttlefish board sync`. After a `west update`, this is how new/changed/
+     * `typecad-hal board sync`. After a `west update`, this is how new/changed/
      * removed boards reach projects without a cuttlefish release. See
      * src/sdk/board-catalog-sync.ts.
      */
@@ -1714,7 +1711,7 @@ export class ZephyrStrategy {
     }
     /**
      * Refresh the overlay only when it is stale (provenance no longer matches
-     * the tree) — the pre-step `cuttlefish board regen` runs so a regen after
+     * the tree) — the pre-step `typecad-hal board regen` runs so a regen after
      * `west update` picks up the tree's boards automatically. Tree walk only
      * happens when there is actual refreshing to do.
      */
@@ -1899,23 +1896,23 @@ export class ZephyrStrategy {
                 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; }
+                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: [],
@@ -1931,27 +1928,27 @@ int __tc_indexOf(const char* s, const char* needle) { const char* p = strstr(s,
                 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
+                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: [],
@@ -2085,43 +2082,43 @@ struct __tc_StaticArray {
         };
     }
     // ── Debug ─────────────────────────────────────────────────────────────────
-    // Zephyr's minimal C++ config has no <iostream>, so the GenericStrategy
-    // std::cout fallback the debug preprocessor uses by default would NOT
-    // compile. Override the debug surface to route through printk (always
-    // available, no CONFIG_CONSOLE dependency) and the __tc_debug_wait_for_continue
-    // halt emitted in shimLines. See src/debug-codegen.ts.
-    //
-    // Target-selective: targets with a debug probe get native GDB source-level
-    // debugging (core emits #line markers + skips printf instrumentation); the
-    // rest fall back to the printk instrumentation path. The ESP32-S3 has a
-    // built-in USB-JTAG (single-cable GDB via OpenOCD) so it selects 'gdb'.
-    // The XIAO nRF52840 needs its J-Link wired up; its GDB path is a follow-on,
-    // so it stays on printf for now.
+    // Source-level debugging is the GDB flow only (the west-owned gdb server
+    // serves F5 via cortex-debug's external-server mode — see
+    // toolchain/debug-config.ts). The printf/Serial breakpoint instrumentation
+    // pipeline was removed from the product.
     debugMode(target) {
-        // `target` is the Zephyr board id (optionally with a /qualifier suffix,
-        // e.g. 'esp32s3_devkitc/esp32s3/procpu'). Match on the bare board id.
-        const boardId = (target ?? '').split('/')[0];
-        if (boardId === 'esp32s3_devkitc' || boardId.startsWith('esp32s3')) {
-            return 'gdb';
+        // `target` is the Zephyr board id (optionally with a /qualifier suffix).
+        // gdb capability is a FACT of the board: its probe-method table carries a
+        // debug-capable entry (bootloaders mark debug:false; SWD/JTAG probes and
+        // built-in USB-JTAG carry debug:true) — the same table west's runner
+        // selection uses. Boards without a table (or unresolvable targets, e.g.
+        // generated custom boards) report 'none', and --debug fails with an
+        // explicit diagnostic (transpile.ts) rather than building silently.
+        const t = (target ?? '').trim();
+        if (!t)
+            return 'none';
+        const memo = debugModeMemo.get(t);
+        if (memo)
+            return memo;
+        let mode = 'none';
+        try {
+            const g = generateBoard(t);
+            const constants = JSON.parse(g.boardJson).constants;
+            for (let i = 0;; i++) {
+                const id = constants[`zephyr.probeMethods.${i}.id`];
+                if (typeof id !== 'string')
+                    break;
+                if (constants[`zephyr.probeMethods.${i}.debug`] !== false) {
+                    mode = 'gdb';
+                    break;
+                }
+            }
         }
-        // The STM32 Black Pill ships a verified ST-Link probe method in its board
-        // package (openocd runner over SWD, with the reset_config quirk for the
-        // unwired SRST line), so F5 attaches natively out of the box.
-        if (boardId.startsWith('blackpill_')) {
-            return 'gdb';
+        catch {
+            // Board not resolvable from facts — 'none' (never crash codegen over
+            // the debug-capability gate).
         }
-        // The plain ESP32 (esp32_devkitc) intentionally stays on 'printf': unlike
-        // the S3 it has NO built-in USB-JTAG, so gdb needs an external ESP-PROG
-        // probe + a different OpenOCD cfg/toolchain dir (deferred). Falls through.
-        return 'printf';
-    }
-    generateDebugInitCode() {
-        return generateZephyrInitCode();
-    }
-    generateDebugBreakpointCode(params) {
-        return generateZephyrBreakpointCode(params.fileName, params.lineNum, params.originalLine, params.variables, params.normalizedCondition, params.breakpointId);
-    }
-    generateDebugLogpointCode(params) {
-        return generateZephyrLogpointCode(params.fileName, params.lineNum, params.parts, params.variables);
+        debugModeMemo.set(t, mode);
+        return mode;
     }
 }

package/dist/tmp-probe.d.ts

@@ -0,0 +1,2 @@
+import type { ToolchainOptions } from '@typecad/cuttlefish/api/shared';
+export declare function probe(opts: ToolchainOptions): void;

package/dist/tmp-probe.js

@@ -0,0 +1,9 @@
+import { spawn } from 'node:child_process';
+export function probe(opts) {
+    void opts;
+    const child = spawn('west', ['build'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        ...(process.platform !== 'win32' ? { detached: true } : {}),
+    });
+    child.on('exit', (code) => { void code; });
+}