@typecad/expect 1.0.0-alpha.14 → 1.0.0-alpha.16

package/dist/host/config.js

@@ -46,6 +46,8 @@ export function loadConfig(projectRoot, overrides = {}, explicitConfigPath) {
         include: overrides.include ?? testFromFile.include ?? DEFAULT_TEST_CONFIG.include,
         exclude: overrides.exclude ?? testFromFile.exclude,
         port: overrides.port ?? testFromFile.port ?? DEFAULT_TEST_CONFIG.port,
+        // A CLI --port override disables USB discovery outright (explicit wins).
+        usb: overrides.port ? undefined : (testFromFile.usb ?? overrides.usb),
         baudRate: overrides.baudRate ?? testFromFile.baudRate ?? DEFAULT_TEST_CONFIG.baudRate,
         timeout: overrides.timeout ?? testFromFile.timeout ?? DEFAULT_TEST_CONFIG.timeout,
         serialOpenDelay: overrides.serialOpenDelay ?? testFromFile.serialOpenDelay ?? DEFAULT_TEST_CONFIG.serialOpenDelay,
@@ -56,11 +58,13 @@ export function loadConfig(projectRoot, overrides = {}, explicitConfigPath) {
     };
     return {
         test,
-        buildTarget: test.buildTarget ?? raw.frameworkData?.buildTarget ?? 'arduino:avr:uno',
-        board: test.board ?? raw.board ?? '@typecad/board-arduino-uno',
-        target: raw.target ?? 'avr',
+        // Board: is the source of truth for west's -b target (mirrors the
+        // cuttlefish config-loader: frameworkData.buildTarget is the board-less
+        // custom-board form). An explicit test.buildTarget overrides both.
+        buildTarget: test.buildTarget ?? raw.board ?? raw.frameworkData?.buildTarget ?? '',
+        board: test.board ?? raw.board ?? 'xiao_ble/nrf52840',
+        target: raw.target ?? 'zephyr',
         framework: raw.framework,
-        toolchainType: raw.toolchain?.type === 'west' ? 'west' : 'arduino-cli',
         zephyrConfig: raw.zephyr,
         projectRoot,
         // The config file these values came from. writeBuildConfig re-reads it to
@@ -266,13 +270,6 @@ function extractConfigProperties(obj, out) {
                 }
                 break;
             }
-            case 'console': {
-                const init = unwrapExpr(prop.initializer);
-                if (ts.isObjectLiteralExpression(init)) {
-                    out.console = extractConsoleConfig(init);
-                }
-                break;
-            }
         }
     }
 }
@@ -291,6 +288,24 @@ function extractTestConfig(obj) {
                     result.port = v;
                 break;
             }
+            case 'usb': {
+                const init = unwrapExpr(prop.initializer);
+                if (ts.isObjectLiteralExpression(init)) {
+                    const sub = {};
+                    for (const subProp of init.properties) {
+                        if (!ts.isPropertyAssignment(subProp))
+                            continue;
+                        const subKey = propName(subProp);
+                        const v = stringLikeText(subProp.initializer);
+                        if (subKey !== undefined && v !== undefined)
+                            sub[subKey] = v;
+                    }
+                    if (sub.vid && sub.pid) {
+                        result.usb = { vid: sub.vid, pid: sub.pid, ...(sub.serial ? { serial: sub.serial } : {}) };
+                    }
+                }
+                break;
+            }
             case 'baudRate': {
                 const v = numericValue(prop.initializer);
                 if (v !== undefined)
@@ -369,16 +384,3 @@ function extractOutputConfig(obj) {
     }
     return result;
 }
-function extractConsoleConfig(obj) {
-    const result = {};
-    for (const prop of obj.properties) {
-        if (!ts.isPropertyAssignment(prop))
-            continue;
-        if (propName(prop) === 'baudRate') {
-            const v = numericValue(prop.initializer);
-            if (v !== undefined)
-                result.baudRate = v;
-        }
-    }
-    return result;
-}

package/dist/host/finder.d.ts

@@ -2,7 +2,7 @@
  * Find all test files matching the include glob patterns.
  *
  * Supports patterns like `tests/**\/*.test.ts`, `src/**\/*.test.ts`, or exact
- * file paths like `src/sketch.ts`.  Only files ending in `.test.ts` are
+ * file paths like `src/main.ts`.  Only files ending in `.test.ts` are
  * returned.
  *
  * @param projectRoot  Absolute path to the project root.

package/dist/host/finder.js

@@ -12,7 +12,7 @@ import fs from 'node:fs';
  * Find all test files matching the include glob patterns.
  *
  * Supports patterns like `tests/**\/*.test.ts`, `src/**\/*.test.ts`, or exact
- * file paths like `src/sketch.ts`.  Only files ending in `.test.ts` are
+ * file paths like `src/main.ts`.  Only files ending in `.test.ts` are
  * returned.
  *
  * @param projectRoot  Absolute path to the project root.

package/dist/host/port-discovery.d.ts

@@ -0,0 +1,55 @@
+/** A USB identity to match attached serial ports against. */
+export interface UsbIdentity {
+    /** Vendor ID, 4 hex digits (with or without 0x, case-insensitive). */
+    vid: string;
+    /** Product ID, 4 hex digits (with or without 0x, case-insensitive). */
+    pid: string;
+    /** Optional exact serial-number match — disambiguates identical devices. */
+    serial?: string;
+}
+/** One attached USB serial port, normalized from serialport's listing. */
+export interface UsbSerialPort {
+    path: string;
+    vid: string;
+    pid: string;
+    serialNumber?: string;
+    manufacturer?: string;
+}
+/** Normalize a hex id: strip 0x, lowercase, pad to 4 digits. */
+export declare function normalizeHexId(value: string): string;
+/** Normalize an identity's fields (returns a new object). */
+export declare function normalizeUsbIdentity(identity: UsbIdentity): UsbIdentity;
+/** Human-readable one-line form: `2FE3:0001 (serial DF7A…)` / `2FE3:0001`. */
+export declare function formatUsbIdentity(identity: UsbIdentity): string;
+/** Format the attached-port table for diagnostics (nightly logs). */
+export declare function formatPortTable(ports: UsbSerialPort[]): string;
+/**
+ * Enumerate attached USB serial ports (ports without a USB identity, such as
+ * legacy motherboard COM ports, are skipped). Uses a dynamic import so the
+ * native serialport dependency loads only when discovery runs.
+ */
+export declare function listUsbSerialPorts(): Promise<UsbSerialPort[]>;
+/**
+ * Pure matcher: which of `ports` match `identity`. VID/PID must match; when
+ * the identity carries a serial, it must match exactly (the disambiguator
+ * for several identical bridge chips).
+ */
+export declare function matchUsbPorts(ports: UsbSerialPort[], identity: UsbIdentity): UsbSerialPort[];
+export interface ResolveResult {
+    /** Resolved port path on success. */
+    port?: string;
+    /** Failure reason when no port could be resolved. */
+    error?: string;
+}
+/**
+ * Resolve the port for an identity: exactly one match, or an error naming
+ * the problem AND the full attached-port table (a nightly log should show
+ * what IS connected, not just that something is missing).
+ */
+export declare function resolveUsbPort(identity: UsbIdentity): Promise<ResolveResult>;
+/**
+ * Wait for a port matching the identity to (re-)appear — CDC consoles
+ * re-enumerate after a flash and may come back under a different COM
+ * number. Polls after an initial settle delay; returns undefined on timeout.
+ */
+export declare function waitForUsbPort(identity: UsbIdentity, settleMs: number, pollMs?: number, maxWaitMs?: number): Promise<string | undefined>;

package/dist/host/port-discovery.js

@@ -0,0 +1,122 @@
+// ---------------------------------------------------------------------------
+// @typecad/expect — USB identity port discovery
+//
+// Multi-board rigs (e.g. a nightly test box) cannot track COM/tty numbers:
+// they reshuffle on every replug and every CDC re-enumeration after a flash.
+// Boards are instead identified by their USB VID/PID (+ optional serial
+// number), declared per board in test-pins.json (`usb: { vid, pid, serial? }`)
+// or directly in the config's `test.usb`. Zephyr CDC consoles all enumerate
+// at the Zephyr-test default identity 0x2FE3:0001 (per-board PIDs are no
+// longer assigned), so vid/pid alone cannot distinguish several attached CDC
+// boards — run one CDC board at a time, or disambiguate via `serial` when the
+// descriptor provides one.
+//
+// UART-bridge boards identify by their bridge chip instead: the Uno's 16U2
+// (2341:0043, CH340 clones report 1A86:7523) and the ESP32 DevKitC's CP2102
+// (10C4:EA60). Those bridges report real unique serial numbers, so several
+// identical devkits disambiguate via `serial`.
+// ---------------------------------------------------------------------------
+/** Normalize a hex id: strip 0x, lowercase, pad to 4 digits. */
+export function normalizeHexId(value) {
+    const stripped = value.trim().toLowerCase().replace(/^0x/, '');
+    return stripped.padStart(4, '0');
+}
+/** Normalize an identity's fields (returns a new object). */
+export function normalizeUsbIdentity(identity) {
+    return {
+        vid: normalizeHexId(identity.vid),
+        pid: normalizeHexId(identity.pid),
+        ...(identity.serial ? { serial: identity.serial } : {}),
+    };
+}
+/** Human-readable one-line form: `2FE3:0001 (serial DF7A…)` / `2FE3:0001`. */
+export function formatUsbIdentity(identity) {
+    const n = normalizeUsbIdentity(identity);
+    return `${n.vid.toUpperCase()}:${n.pid.toUpperCase()}${n.serial ? ` serial ${n.serial}` : ''}`;
+}
+/** Format the attached-port table for diagnostics (nightly logs). */
+export function formatPortTable(ports) {
+    if (ports.length === 0)
+        return '  (no USB serial ports found)';
+    const rows = ports.map((p) => {
+        const id = `${p.vid.toUpperCase()}:${p.pid.toUpperCase()}`;
+        const serial = p.serialNumber ? ` serial ${p.serialNumber}` : '';
+        const mfr = p.manufacturer ? ` [${p.manufacturer}]` : '';
+        return `  ${p.path}  ${id}${serial}${mfr}`;
+    });
+    return rows.join('\n');
+}
+/**
+ * Enumerate attached USB serial ports (ports without a USB identity, such as
+ * legacy motherboard COM ports, are skipped). Uses a dynamic import so the
+ * native serialport dependency loads only when discovery runs.
+ */
+export async function listUsbSerialPorts() {
+    const { SerialPort } = await import('serialport');
+    const ports = await SerialPort.list();
+    const result = [];
+    for (const p of ports) {
+        if (!p.vendorId || !p.productId || !p.path)
+            continue;
+        result.push({
+            path: p.path,
+            vid: normalizeHexId(p.vendorId),
+            pid: normalizeHexId(p.productId),
+            ...(p.serialNumber ? { serialNumber: p.serialNumber } : {}),
+            ...(p.manufacturer ? { manufacturer: p.manufacturer } : {}),
+        });
+    }
+    return result;
+}
+/**
+ * Pure matcher: which of `ports` match `identity`. VID/PID must match; when
+ * the identity carries a serial, it must match exactly (the disambiguator
+ * for several identical bridge chips).
+ */
+export function matchUsbPorts(ports, identity) {
+    const n = normalizeUsbIdentity(identity);
+    return ports.filter((p) => p.vid === n.vid
+        && p.pid === n.pid
+        && (n.serial === undefined || p.serialNumber === n.serial));
+}
+/**
+ * Resolve the port for an identity: exactly one match, or an error naming
+ * the problem AND the full attached-port table (a nightly log should show
+ * what IS connected, not just that something is missing).
+ */
+export async function resolveUsbPort(identity) {
+    const ports = await listUsbSerialPorts();
+    const matches = matchUsbPorts(ports, identity);
+    if (matches.length === 1)
+        return { port: matches[0].path };
+    const wanted = formatUsbIdentity(identity);
+    if (matches.length === 0) {
+        return {
+            error: `No USB serial port matches ${wanted}. Attached ports:\n${formatPortTable(ports)}`,
+        };
+    }
+    return {
+        error: `Multiple ports match ${wanted} — add a serial number to disambiguate. Matches:\n${formatPortTable(matches)}\nAll attached ports:\n${formatPortTable(ports)}`,
+    };
+}
+/**
+ * Wait for a port matching the identity to (re-)appear — CDC consoles
+ * re-enumerate after a flash and may come back under a different COM
+ * number. Polls after an initial settle delay; returns undefined on timeout.
+ */
+export async function waitForUsbPort(identity, settleMs, pollMs = 500, maxWaitMs = 10_000) {
+    if (settleMs > 0)
+        await sleep(settleMs);
+    const deadline = Date.now() + Math.max(maxWaitMs - settleMs, 0);
+    for (;;) {
+        const result = await resolveUsbPort(identity);
+        if (result.port)
+            return result.port;
+        if (Date.now() >= deadline)
+            return undefined;
+        await sleep(pollMs);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/host/preprocessor.d.ts

@@ -1,40 +1,49 @@
+import type { TestPinsSubstitutions } from './test-pins.js';
 /**
  * Describes how the test protocol emits output for a given framework.
  * Each framework provides its own shim so the preprocessor doesn't hardcode
- * Serial.* (which would force the Arduino core to be linked).
+ * a specific console API.
  */
 export interface OutputShim {
-    /** The init call emitted in the preamble, e.g. "Serial.begin(115200)". */
+    /** The init call emitted in the preamble, e.g. "Serial.begin(115200)". Empty when the console self-initializes. */
     begin: string;
     /** Print without newline — receives a fully-formed argument expression. */
     print: (expr: string) => string;
     /** Print with newline — receives a fully-formed argument expression. */
     println: (expr: string) => string;
-    /** The idle-loop delay call after SUITE_END, e.g. "delay(1000)". */
+    /** The idle-loop delay call after SUITE_END, e.g. "k_msleep(1000)". */
     delay: string;
 }
-/** Default shim: Arduino HardwareSerial. */
-export declare const serialShim: OutputShim;
 /**
- * Zephyr shim: uses overloaded __tc_print/__tc_println helpers that handle
- * both string and numeric (double) output via printf. The Zephyr strategy's
- * shimLines emits these helper definitions. k_msleep replaces delay().
+ * Zephyr shim (the default): uses overloaded __tc_print/__tc_println helpers
+ * that handle both string and numeric (double) output via printf. The Zephyr
+ * strategy's shimLines emits these helper definitions. k_msleep replaces
+ * delay().
  */
 export declare const zephyrShim: OutputShim;
 export interface PreprocessorOptions {
-    /** Wrap string literals in Arduino F() macro to save SRAM on AVR. */
-    isAvr?: boolean;
-    /** Output shim — defaults to serialShim (Arduino HardwareSerial). */
+    /** Output shim — defaults to the Zephyr __tc_print helpers. */
     shim?: OutputShim;
+    /**
+     * Board test-pins substitutions (role const -> replacement text). When
+     * present, every role identifier in the source is replaced with the
+     * board's real pin symbol (or numeric fact), and a synthesized
+     * `import { <used pins> } from '@typecad/board'` is prepended. The
+     * '@typecad/test-pins' import itself is stripped — the transpiler never
+     * sees the virtual specifier.
+     */
+    testPins?: TestPinsSubstitutions;
 }
 /**
  * Preprocess a test file's TypeScript source.
  *
- * 1. Strips `import { ... } from '@typecad/expect'`
+ * 1. Strips `import { ... } from '@typecad/expect'` and
+ *    `import { ... } from '@typecad/test-pins'`
  * 2. Walks top-level expression-statements looking for `describe(...)...` chains
  * 3. Replaces `done()` with the suite-end sentinel + idle loop
  * 4. Hoists hardware expressions out of `expect()` into `const` declarations
- * 5. Wraps everything with Serial.initialize + SUITE_START preamble
+ * 5. Wraps everything with the console init + SUITE_START preamble
+ * 6. Substitutes test-pin role identifiers with the board's real pin symbols
  */
 export declare function preprocess(source: string, fileName?: string, options?: PreprocessorOptions): string;
 export declare class PreprocessorContext {
@@ -42,18 +51,28 @@ export declare class PreprocessorContext {
     private varCounter;
     private fnCounter;
     private preambleEmitted;
-    readonly isAvr: boolean;
     readonly shim: OutputShim;
-    constructor(isAvr: boolean, shim?: OutputShim);
-    /** Wrap a string literal in F() on AVR to keep it in flash.
-     *  Only applies when using the serialShim (Arduino core provides F()). */
-    flash(s: string): string;
+    /** Role const -> replacement text (board pin symbols / numeric facts). */
+    private readonly substitutions?;
+    /** Pin symbols seen in substitutions that actually replaced something. */
+    private readonly usedPins;
+    constructor(shim?: OutputShim, substitutions?: TestPinsSubstitutions);
+    /** Quote a protocol string literal for the active shim. */
+    quote(s: string): string;
     /** Emit a line of TypeScript output. */
     emit(line: string): void;
     /** Generate a unique temporary variable name. */
     nextVar(): string;
     /** Generate a unique extracted function name. */
     nextFn(): string;
+    /**
+     * Replace whole-word role identifiers with their board-specific text.
+     * Role const names are SCREAMING_SNAKE and never appear in protocol
+     * strings, so a word-boundary replace over the emitted statement text is
+     * safe. Pin symbols referenced by a used replacement are recorded so the
+     * synthesized board import covers them.
+     */
+    private substitute;
     private emitPreamble;
     build(): string;
 }

package/dist/host/preprocessor.js

@@ -10,31 +10,24 @@
 //   done();
 //
 // OUTPUT (preprocessed — fed to transpiler):
-//   Serial.begin(115200);
-//   Serial.println("[TC:SUITE_START]");
-//   Serial.println("[TC:DESCRIBE:A0 analog read]");
-//   Serial.println("[TC:IT:reads zero]");
+//   __tc_println("[TC:SUITE_START]");
+//   __tc_println("[TC:DESCRIBE:A0 analog read]");
+//   __tc_println("[TC:IT:reads zero]");
 //   const __tc_v1: number = A0.readAnalog();
-//   Serial.print("[TC:EXPECT:toBe:0:");
-//   Serial.print(__tc_v1);
-//   Serial.println("]");
-//   Serial.println("[TC:SUITE_END]");
-//   while (true) { delay(1000); }
+//   __tc_print("[TC:EXPECT:toBe:0:");
+//   __tc_print(__tc_v1);
+//   __tc_println("]");
+//   __tc_println("[TC:SUITE_END]");
+//   while (true) { k_msleep(1000); }
 // ---------------------------------------------------------------------------
 import ts from 'typescript';
 import { isDescribeChain, collectChainSegments } from './chain-collector.js';
 import { emitSegments } from './protocol-emitter.js';
-/** Default shim: Arduino HardwareSerial. */
-export const serialShim = {
-    begin: 'Serial.begin(115200)',
-    print: (e) => `Serial.print(${e})`,
-    println: (e) => `Serial.println(${e})`,
-    delay: 'delay(1000)',
-};
 /**
- * Zephyr shim: uses overloaded __tc_print/__tc_println helpers that handle
- * both string and numeric (double) output via printf. The Zephyr strategy's
- * shimLines emits these helper definitions. k_msleep replaces delay().
+ * Zephyr shim (the default): uses overloaded __tc_print/__tc_println helpers
+ * that handle both string and numeric (double) output via printf. The Zephyr
+ * strategy's shimLines emits these helper definitions. k_msleep replaces
+ * delay().
  */
 export const zephyrShim = {
     begin: '', // Zephyr console auto-initializes via DT; no explicit begin needed
@@ -45,20 +38,24 @@ export const zephyrShim = {
 /**
  * Preprocess a test file's TypeScript source.
  *
- * 1. Strips `import { ... } from '@typecad/expect'`
+ * 1. Strips `import { ... } from '@typecad/expect'` and
+ *    `import { ... } from '@typecad/test-pins'`
  * 2. Walks top-level expression-statements looking for `describe(...)...` chains
  * 3. Replaces `done()` with the suite-end sentinel + idle loop
  * 4. Hoists hardware expressions out of `expect()` into `const` declarations
- * 5. Wraps everything with Serial.initialize + SUITE_START preamble
+ * 5. Wraps everything with the console init + SUITE_START preamble
+ * 6. Substitutes test-pin role identifiers with the board's real pin symbols
  */
 export function preprocess(source, fileName = 'test.ts', options) {
     const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-    const ctx = new PreprocessorContext(options?.isAvr ?? false, options?.shim);
+    const ctx = new PreprocessorContext(options?.shim, options?.testPins);
     for (const stmt of sf.statements) {
         if (ts.isImportDeclaration(stmt)) {
             const moduleSpecifier = stmt.moduleSpecifier.text;
             if (moduleSpecifier === '@typecad/expect')
                 continue; // strip
+            if (moduleSpecifier === '@typecad/test-pins')
+                continue; // stripped; roles are substituted inline
             ctx.emit(stmt.getText(sf));
         }
         else if (ts.isExpressionStatement(stmt)) {
@@ -74,24 +71,25 @@ export function preprocess(source, fileName = 'test.ts', options) {
 // PreprocessorContext — shared state threaded through sub-modules
 // ---------------------------------------------------------------------------
 export class PreprocessorContext {
-    constructor(isAvr, shim = serialShim) {
+    constructor(shim = zephyrShim, substitutions) {
         this.lines = [];
         this.varCounter = 0;
         this.fnCounter = 0;
         this.preambleEmitted = false;
-        this.isAvr = isAvr;
+        /** Pin symbols seen in substitutions that actually replaced something. */
+        this.usedPins = new Set();
         this.shim = shim;
+        this.substitutions = substitutions;
     }
-    /** Wrap a string literal in F() on AVR to keep it in flash.
-     *  Only applies when using the serialShim (Arduino core provides F()). */
-    flash(s) {
-        return this.isAvr ? `F("${s}")` : `"${s}"`;
+    /** Quote a protocol string literal for the active shim. */
+    quote(s) {
+        return `"${s}"`;
     }
     /** Emit a line of TypeScript output. */
     emit(line) {
         if (!this.preambleEmitted)
             this.emitPreamble();
-        this.lines.push(line);
+        this.lines.push(this.substitute(line));
     }
     /** Generate a unique temporary variable name. */
     nextVar() {
@@ -101,13 +99,45 @@ export class PreprocessorContext {
     nextFn() {
         return `__tc_fn${++this.fnCounter}`;
     }
+    /**
+     * Replace whole-word role identifiers with their board-specific text.
+     * Role const names are SCREAMING_SNAKE and never appear in protocol
+     * strings, so a word-boundary replace over the emitted statement text is
+     * safe. Pin symbols referenced by a used replacement are recorded so the
+     * synthesized board import covers them.
+     */
+    substitute(line) {
+        if (!this.substitutions || this.substitutions.size === 0)
+            return line;
+        let result = line;
+        for (const [role, replacement] of this.substitutions) {
+            const pattern = new RegExp(`\\b${role}\\b`, 'g');
+            if (!pattern.test(result))
+                continue;
+            result = result.replace(pattern, replacement);
+            for (const pin of replacement.matchAll(/[A-Za-z_$][\w$]*/g)) {
+                if (!/^\d/.test(pin[0]))
+                    this.usedPins.add(pin[0]);
+            }
+        }
+        return result;
+    }
     emitPreamble() {
         this.preambleEmitted = true;
-        this.lines.push(`${this.shim.begin};`);
-        this.lines.push(`${this.shim.println(this.flash('[TC:SUITE_START]'))};`);
+        // Shims whose console self-initializes (Zephyr DT) have an empty begin.
+        if (this.shim.begin)
+            this.lines.push(`${this.shim.begin};`);
+        this.lines.push(`${this.shim.println(this.quote('[TC:SUITE_START]'))};`);
     }
     build() {
-        return this.lines.join('\n') + '\n';
+        const parts = [];
+        // Synthesized import for the substituted pins — must be a top-level
+        // statement; placed first so the (untype-checked) source reads naturally.
+        if (this.usedPins.size > 0) {
+            parts.push(`import { ${[...this.usedPins].join(', ')} } from '@typecad/board';`);
+        }
+        parts.push(...this.lines);
+        return parts.join('\n') + '\n';
     }
 }
 // ---------------------------------------------------------------------------
@@ -116,7 +146,7 @@ export class PreprocessorContext {
 function processExpressionStatement(stmt, sf, ctx) {
     const expr = stmt.expression;
     if (isDoneCall(expr)) {
-        ctx.emit(`${ctx.shim.println(ctx.flash('[TC:SUITE_END]'))};`);
+        ctx.emit(`${ctx.shim.println(ctx.quote('[TC:SUITE_END]'))};`);
         ctx.emit(`while (true) { ${ctx.shim.delay}; }`);
         return;
     }

package/dist/host/project-root.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolve the project root for a run.
+ *
+ * @param env  The environment to consult (defaults to `process.env`).
+ * @param cwd  The fallback directory (defaults to `process.cwd()`).
+ * @returns INIT_CWD when it names an existing directory, else cwd.
+ */
+export declare function resolveProjectRoot(env?: NodeJS.ProcessEnv, cwd?: string): string;

package/dist/host/project-root.js

@@ -0,0 +1,24 @@
+// ---------------------------------------------------------------------------
+// project-root.ts — resolve the project directory the test runner targets.
+//
+// `npx cuttlefish-test` (npm exec) resets the child process's cwd to the npm
+// local prefix — the NEAREST package.json ancestor of the invocation dir.
+// From a nested suite dir (e.g. packages/framework-zephyr/hal/esp32s3, which
+// has no package.json of its own) that lands on the workspace package instead
+// of the project under test, and file discovery finds nothing. npm stashes
+// the real invocation directory in INIT_CWD (also set by `npm run` to the
+// script's package dir, which is likewise the intended root) — prefer it when
+// it names an existing directory.
+// ---------------------------------------------------------------------------
+import fs from 'node:fs';
+/**
+ * Resolve the project root for a run.
+ *
+ * @param env  The environment to consult (defaults to `process.env`).
+ * @param cwd  The fallback directory (defaults to `process.cwd()`).
+ * @returns INIT_CWD when it names an existing directory, else cwd.
+ */
+export function resolveProjectRoot(env = process.env, cwd = process.cwd()) {
+    const initCwd = env.INIT_CWD;
+    return initCwd !== undefined && initCwd !== '' && fs.existsSync(initCwd) ? initCwd : cwd;
+}

package/dist/host/protocol-emitter.js

@@ -22,10 +22,10 @@ export function emitSegments(segments, ctx) {
     for (const seg of segments) {
         switch (seg.kind) {
             case 'describe':
-                ctx.emit(`${ctx.shim.println(ctx.flash(`[TC:DESCRIBE:${escapeProtocol(seg.name ?? '')}]`))};`);
+                ctx.emit(`${ctx.shim.println(ctx.quote(`[TC:DESCRIBE:${escapeProtocol(seg.name ?? '')}]`))};`);
                 break;
             case 'it':
-                ctx.emit(`${ctx.shim.println(ctx.flash(`[TC:IT:${escapeProtocol(seg.name ?? '')}]`))};`);
+                ctx.emit(`${ctx.shim.println(ctx.quote(`[TC:IT:${escapeProtocol(seg.name ?? '')}]`))};`);
                 break;
             case 'expect': {
                 if (!seg.matcher)
@@ -67,17 +67,17 @@ export function emitSegments(segments, ctx) {
 export function emitExpectProtocol(actualVar, matcher, matcherArgs, ctx, isString = false) {
     if (isString && matcher === 'toBe') {
         const rawExpected = (matcherArgs[0] ?? '').replace(/^["']|["']$/g, '');
-        ctx.emit(`${ctx.shim.print(ctx.flash(`[TC:EXPECT:${matcher}:`))};`);
+        ctx.emit(`${ctx.shim.print(ctx.quote(`[TC:EXPECT:${matcher}:`))};`);
         ctx.emit(`${ctx.shim.print(`"${escapeProtocol(rawExpected)}"`)};`);
-        ctx.emit(`${ctx.shim.print(ctx.flash(':'))};`);
+        ctx.emit(`${ctx.shim.print(ctx.quote(':'))};`);
         ctx.emit(`${ctx.shim.print(actualVar)};`);
-        ctx.emit(`${ctx.shim.println(ctx.flash(']'))};`);
+        ctx.emit(`${ctx.shim.println(ctx.quote(']'))};`);
         return;
     }
     const expectedPart = matcherArgs.join(',');
-    ctx.emit(`${ctx.shim.print(ctx.flash(`[TC:EXPECT:${matcher}:${expectedPart}:`))};`);
+    ctx.emit(`${ctx.shim.print(ctx.quote(`[TC:EXPECT:${matcher}:${expectedPart}:`))};`);
     ctx.emit(`${ctx.shim.print(actualVar)};`);
-    ctx.emit(`${ctx.shim.println(ctx.flash(']'))};`);
+    ctx.emit(`${ctx.shim.println(ctx.quote(']'))};`);
 }
 // ---------------------------------------------------------------------------
 // Expression classification helpers

package/dist/host/reporter.js

@@ -21,7 +21,7 @@
 //      Expected: 20–25
 //
 //  Tests   3 passed | 1 failed (4)
-//  Board   Arduino Uno @ COM3
+//  Board   Black Pill @ COM3
 //  Time    8.42s
 // ---------------------------------------------------------------------------
 import { describeExpected } from './evaluator.js';

package/dist/host/runner.d.ts

@@ -1,7 +1,2 @@
 import type { ResolvedConfig } from './types.js';
-/**
- * Run all test files matching the configuration.
- *
- * @returns Exit code: 0 = all passed, 1 = failures, 2 = error.
- */
 export declare function run(config: ResolvedConfig): Promise<number>;