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

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

@@ -40,7 +40,7 @@ export interface ZephyrEnvCheck {
     compatRange: string | undefined;
     /** Result of the compat-range check against the detected version. */
     compatStatus: CompatStatus;
-    /** Raw board target from cuttlefish.config.ts, if configured. */
+    /** Raw board target from typecad-hal.config.ts, if configured. */
     buildTarget: string | undefined;
     /** buildTarget normalized for the installed Zephyr version (may equal it). */
     resolvedBoardTarget: string | undefined;
@@ -61,8 +61,6 @@ export type ZephyrEnvFailure = {
     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

package/dist/toolchain/env-check.js

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// Zephyr environment check — the shared detection behind `cuttlefish doctor`.
+// Zephyr environment check — the shared detection behind `typecad-hal doctor`.
 //
 // Zephyr environment check: gather the impure
 // environment facts once (west presence + version, Zephyr version, board
@@ -21,16 +21,11 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { discoverWest, resetWestDiscoveryCache } from './west-discover.js';
+import { discoverWest } from './west-discover.js';
 import { westSpawn } from './west-spawn.js';
 import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget, } from './compat.js';
 // ---- west probe (impure; isolated + cached + overridable) ------------------
 let cachedProbe;
-/** Clear the west-probe cache (for tests). Also resets discovery cache. */
-export function resetWestProbeCacheForTest() {
-    cachedProbe = undefined;
-    resetWestDiscoveryCache();
-}
 /**
  * Gather west facts: discover a usable install, then run `west --version`
  * through it to capture the version. Memoized for the process lifetime (west

package/dist/toolchain/index.d.ts

@@ -28,7 +28,7 @@ export interface ScannedSpiTarget {
 export declare function scanSpiTargets(src: string): ScannedSpiTarget[];
 export declare function scanSensorParts(src: string): ScannedSensorPart[];
 /**
- * Derive the Zephyr project root from the cuttlefish-emitted source path.
+ * Derive the Zephyr project root from the typecad-hal-emitted source path.
  *
  * Cuttlefish emits `src/main.cpp` under the output dir. The CLI passes
  * `sourcePath` = full path to `main.cpp` and `outputDir` = its parent (`src/`).
@@ -43,7 +43,7 @@ export declare function projectRootFromOptions(o: ToolchainOptions): string;
  * runner for its hardware (xiao_ble → nrfutil, esp32* → esptool), and `west
  * flash` resolves it automatically. The framework only intervenes where the
  * board default needs an argument it can't infer:
- *   - An explicit `zephyr.runner` (from cuttlefish.config.ts) always wins.
+ *   - An explicit `zephyr.runner` (from typecad-hal.config.ts) always wins.
  *   - ESP32 boards forward the port via `--esp-device` (esptool reads the
  *     device from it); board.cmake still picks the runner.
  *   - Every other board trusts the board.cmake default. Previously this forced
@@ -78,7 +78,55 @@ export type ProbeResolution = {
     ok: false;
     error: string;
 };
+/**
+ * The board a cached build dir was configured for (CMakeCache.txt's
+ * BOARD:STRING — the exact value passed to `west build -b`), or undefined
+ * when no cache exists. compile() compares it against the requested board
+ * and nukes the dir on mismatch: `west build`'s --pristine=auto covers
+ * cmake/config churn, NOT a board switch — west aborts with "refusing to
+ * proceed without --force", and cuttlefish doesn't forward that flag.
+ */
+export declare function cachedBuildBoard(buildDir: string): string | undefined;
 export declare function resolveProbeMethod(zc: Record<string, unknown> | undefined, chip: ZephyrChipDescriptor, purpose?: 'flash' | 'debug'): ProbeResolution;
+/**
+ * Run an openocd session against the board's probe config — the shared
+ * engine for the pre-flash quiesce and the post-flash SYSRESETREQ (see the
+ * call sites in upload()). The config is the probe method's verbatim
+ * debugCfg from the board catalog (the same lines `west debug` uses);
+ * `commands` are appended after `-f <cfg> -c init`. Returns a flash note on
+ * success, undefined when skipped or failed (best-effort by design).
+ */
+/**
+ * Resolve the openocd binary (plus script search dirs) for the probe session.
+ *
+ * Resolution order mirrors how west's own openocd runner finds the binary, so
+ * the session and `west flash` drive the SAME openocd:
+ *   1. $OPENOCD — the variable Zephyr's CMake reads into the build cache.
+ *   2. A Zephyr-SDK-hosted install ($ZEPHYR_SDK_INSTALL_DIR, else the
+ *      discovered west install's SDK). Layout differs by SDK generation —
+ *      hosttools/openocd/share/openocd/scripts vs hosttools/openocd/scripts —
+ *      so both script dirs are collected.
+ *   3. PATH — Linux distro / conda / micromamba installs (a micromamba-env
+ *      openocd is the common Linux setup; the SDK layout check alone made the
+ *      deterministic probe session unreachable there, silently dropping every
+ *      Linux flash to the racy `west flash` fallback).
+ *
+ * A non-SDK binary resolves with no explicit -s dirs: it finds its own
+ * interface/target scripts via its compiled-in search path. Returns undefined
+ * when no openocd can be found (the caller then uses the west fallback).
+ *
+ * Exported (pure) so the resolution contract is unit-testable without
+ * spawning openocd.
+ */
+export interface SessionOpenOcd {
+    readonly exe: string;
+    readonly searchDirs: readonly string[];
+}
+export declare function resolveSessionOpenOcd(env?: {
+    OPENOCD?: string | undefined;
+    ZEPHYR_SDK_INSTALL_DIR?: string | undefined;
+    PATH?: string | undefined;
+}, sdkInstallDir?: string): SessionOpenOcd | undefined;
 /**
  * Whether a flash runner carries the upload over a serial port. Runner-gated,
  * never board-name-gated: esptool and bossac are the only runners
@@ -111,6 +159,16 @@ export declare function buildFlashArgs(buildDir: string, userRunner: string | un
  * Exported (pure) so the classification is unit-testable without spawning west.
  */
 export declare function classifyUploadResult(runner: string | undefined, status: number | null, output: string): boolean;
+/**
+ * Whether a `west flash` (openocd) output carries one of the known
+ * target-ignored-SWD signatures — the DAP connect failing ("init mode
+ * failed (unable to connect to the target)", i.e. the DPIDR read never
+ * succeeded) or a reset/halt never landing ("timed out while waiting for
+ * target halted" / "TARGET: <name> - Not halted"). Both mean the board (or
+ * probe) needs a power-cycle or the SWD-free DFU path, not a retry of the
+ * same command. Centralized so the upload hint stays testable.
+ */
+export declare function isTargetSwdFailure(output: string): boolean;
 /**
  * Cleanse the `west flash` output shown to the user.
  *
@@ -148,4 +206,9 @@ export declare const Toolchain: {
     upload(o: ToolchainOptions): UploadResult;
     monitor(o: ToolchainOptions): void;
     debug(o: ToolchainOptions): void;
+    debugServer(o: ToolchainOptions, action: "start" | "stop"): void;
 };
+/** How long `--monitor` waits for the port to (re)appear after a flash reset. */
+export declare const MONITOR_PORT_WAIT_MS = 8000;
+/** argv for the pyserial port wait — exported for the toolchain unit tests. */
+export declare function serialPortWaitArgs(port: string, timeoutMs: number): string[];