@typecad/expect 1.0.0-alpha.7 → 1.0.0-alpha.8

package/dist/host/cli.js

@@ -27,6 +27,9 @@ function parseArgs(argv) {
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         switch (arg) {
+            case '--config':
+                result.config = args[++i];
+                break;
             case '--port':
             case '-p':
                 result.port = args[++i];
@@ -75,6 +78,12 @@ function parseArgs(argv) {
             case '-v':
                 result.verbose = true;
                 break;
+            case '--dry-run':
+                result.dryRun = true;
+                break;
+            case '--bail':
+                result.bail = true;
+                break;
             case '--help':
             case '-h':
                 result.help = true;
@@ -169,12 +178,18 @@ async function main() {
     // Load config
     let config;
     try {
-        config = loadConfig(projectRoot, overrides);
+        const configPath = args.config
+            ? (path.isAbsolute(args.config) ? args.config : path.resolve(projectRoot, args.config))
+            : undefined;
+        config = loadConfig(projectRoot, overrides, configPath);
     }
     catch (e) {
         console.error(`\x1b[31m${e.message}\x1b[0m`);
         process.exit(2);
     }
+    // CLI mode flags (not config-file settings).
+    config.dryRun = args.dryRun;
+    config.bail = args.bail;
     // Run tests
     const exitCode = await run(config);
     process.exit(exitCode);

package/dist/host/compiler.d.ts

@@ -11,24 +11,17 @@ export interface UploadResult {
     error?: string;
 }
 /**
- * Transpile preprocessed TypeScript source to a C++ Arduino sketch.
- *
- * Writes the preprocessed source to a temp file, invokes the cuttlefish
- * transpiler, and returns the path to the generated .ino file.
+ * Transpile preprocessed TypeScript source to a C++ Arduino sketch (or Zephyr
+ * project). Writes the preprocessed source to a temp file, invokes the cuttlefish
+ * transpiler, and returns the path to the generated .ino (Arduino) or .cpp
+ * (Zephyr) entry file.
  */
-export declare function transpileTestFile(preprocessedSource: string, originalFilePath: string, projectRoot: string, buildTarget: string): CompileResult;
+export declare function transpileTestFile(preprocessedSource: string, originalFilePath: string, projectRoot: string, buildTarget: string, toolchainType?: 'arduino-cli' | 'west', configPath?: string): CompileResult;
 /**
- * Compile the sketch. Detects the toolchain from the framework:
- * - framework-esp32 → idf.py build (via framework-esp32's compileEspIdf)
- * - everything else → arduino-cli compile
+ * Compile the sketch/project via the configured toolchain (arduino-cli or west).
  */
-export declare function compileSketch(sketchDir: string, buildTarget: string, framework?: string): CompileResult;
+export declare function compileSketch(sketchDir: string, buildTarget: string, framework?: string, toolchainType?: 'arduino-cli' | 'west', zephyrConfig?: Record<string, unknown>): CompileResult;
 /**
- * Upload the compiled sketch to the board.
+ * Upload the compiled sketch/project to the board via the configured toolchain.
  */
-/**
- * Upload firmware. Detects the toolchain from the framework:
- * - framework-esp32 → idf.py flash
- * - everything else → arduino-cli upload
- */
-export declare function uploadSketch(sketchDir: string, buildTarget: string, port: string, framework?: string): UploadResult;
+export declare function uploadSketch(sketchDir: string, buildTarget: string, port: string, framework?: string, toolchainType?: 'arduino-cli' | 'west', zephyrConfig?: Record<string, unknown>): UploadResult;

package/dist/host/compiler.js

@@ -10,9 +10,9 @@ import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { parseConfigAST } from './config.js';
 import { checkArduinoEnv } from '@typecad/arduino-cli';
-// createRequire lets us synchronously require CommonJS modules from this ESM
-// file. Used to load framework-esp32's compiled dist at runtime.
-const require_ = createRequire(import.meta.url);
+// createRequire lets us use require() in an ESM module for the optional
+// framework-zephyr dynamic import (avoids a hard dependency for Arduino users).
+const require = createRequire(import.meta.url);
 /** Format a check failure into the `error` field used by CompileResult/UploadResult. */
 function formatEnvFailure(failure) {
     const lines = [...failure.messages];
@@ -21,41 +21,20 @@ function formatEnvFailure(failure) {
     return lines.join('\n');
 }
 /**
- * Transpile preprocessed TypeScript source to a C++ Arduino sketch.
- *
- * Writes the preprocessed source to a temp file, invokes the cuttlefish
- * transpiler, and returns the path to the generated .ino file.
+ * Transpile preprocessed TypeScript source to a C++ Arduino sketch (or Zephyr
+ * project). Writes the preprocessed source to a temp file, invokes the cuttlefish
+ * transpiler, and returns the path to the generated .ino (Arduino) or .cpp
+ * (Zephyr) entry file.
  */
-export function transpileTestFile(preprocessedSource, originalFilePath, projectRoot, buildTarget) {
-    // Create a build directory for this test file.
-    // For idf.py targets, use a SHARED build directory across all test files —
-    // only main/main.cc changes between files, so idf.py can do incremental
-    // builds (ninja detects only the changed .cc and relinks). This turns the
-    // 2nd+ file from a ~130s full rebuild into a ~10-15s incremental build.
-    // For arduino-cli targets, use per-file directories (no incremental benefit).
+export function transpileTestFile(preprocessedSource, originalFilePath, projectRoot, buildTarget, toolchainType = 'arduino-cli', configPath) {
+    // Create a build directory for this test file. Per-file directories are
+    // used — arduino-cli compile has no incremental benefit from a shared dir.
     const baseName = path.basename(originalFilePath, '.test.ts').replace(/[^a-zA-Z0-9_]/g, '_');
-    const isEsp32 = buildTarget === 'esp32' || buildTarget === 'esp32s3' || buildTarget === 'esp32c3' || buildTarget === 'esp32c6';
-    const buildDir = isEsp32
-        ? path.join(projectRoot, '.build', 'expect', 'esp32_shared')
-        : path.join(projectRoot, '.build', 'expect', baseName);
+    const buildDir = path.join(projectRoot, '.build', 'expect', baseName);
     try {
-        if (isEsp32 && fs.existsSync(buildDir)) {
-            // Shared ESP32 build dir: preserve it. The transpiler will overwrite
-            // the .ts source and regenerate main.cc; ninja does an incremental build.
-            // Only remove the old .ts file so the transpiler doesn't pick up stale ones.
-            const oldTsFiles = fs.readdirSync(buildDir).filter(f => f.endsWith('.ts'));
-            for (const f of oldTsFiles) {
-                try {
-                    fs.unlinkSync(path.join(buildDir, f));
-                }
-                catch { }
-            }
-        }
-        else {
-            // Fresh dir (first run, or arduino-cli target).
-            fs.rmSync(buildDir, { recursive: true, force: true });
-            fs.mkdirSync(buildDir, { recursive: true });
-        }
+        // Fresh dir for every transpile.
+        fs.rmSync(buildDir, { recursive: true, force: true });
+        fs.mkdirSync(buildDir, { recursive: true });
     }
     catch {
         return { success: false, sketchDir: buildDir, sketchPath: '', output: '', error: `Failed to create build dir: ${buildDir}` };
@@ -67,9 +46,18 @@ export function transpileTestFile(preprocessedSource, originalFilePath, projectR
     // Invoke the cuttlefish transpiler
     // We call it as a CLI command rather than importing to avoid coupling
     const cuttlefishCmd = resolveCuttlefishCmd(projectRoot);
-    const useBuildMode = hasRelativeImports(rewrittenSource);
+    // Use build mode (run `cuttlefish build` from a build dir that holds its own
+    // generated cuttlefish.config.ts) when the test source has relative imports
+    // OR when an explicit configPath was passed. The latter matters because
+    // direct-file mode discovers cuttlefish.config.ts from cwd (projectRoot),
+    // which is the DEFAULT config — so a project with several target-specific
+    // configs (e.g. tests/hardware/cuttlefish.config.ts vs ble-demo.config.ts)
+    // would always transpile against the default. Build mode writes a config
+    // derived from the chosen configPath into the build dir, so the right
+    // board/MCU/target is used.
+    const useBuildMode = hasRelativeImports(rewrittenSource) || !!configPath;
     if (useBuildMode) {
-        writeBuildConfig(buildDir, projectRoot, path.basename(tsPath), buildTarget);
+        writeBuildConfig(buildDir, projectRoot, path.basename(tsPath), buildTarget, configPath);
     }
     const result = spawnSync(process.execPath, useBuildMode
         ? [cuttlefishCmd, 'build', '--skip-type-check', '--force']
@@ -89,46 +77,36 @@ export function transpileTestFile(preprocessedSource, originalFilePath, projectR
             error: `Transpilation failed:\n${transpileOutput}`,
         };
     }
-    // Find the generated .ino file
-    const outDir = findOutputDir(buildDir, baseName, projectRoot);
-    const inoPath = findInoFile(outDir);
-    if (!inoPath) {
+    // Find the generated entry file (.ino for Arduino, .cpp for Zephyr)
+    const outDir = findOutputDir(buildDir, baseName, projectRoot, toolchainType);
+    const entryPath = findEntryFile(outDir, toolchainType);
+    if (!entryPath) {
+        const ext = toolchainType === 'west' ? '.cpp' : '.ino';
         return {
             success: false,
             sketchDir: outDir,
             sketchPath: '',
             output: transpileOutput,
-            error: `No .ino file found in ${outDir} after transpilation`,
+            error: `No ${ext} file found in ${outDir} after transpilation`,
         };
     }
     return {
         success: true,
-        sketchDir: path.dirname(inoPath),
-        sketchPath: inoPath,
+        sketchDir: path.dirname(entryPath),
+        sketchPath: entryPath,
         output: transpileOutput,
     };
 }
 /**
- * Compile the sketch. Detects the toolchain from the framework:
- * - framework-esp32 → idf.py build (via framework-esp32's compileEspIdf)
- * - everything else → arduino-cli compile
+ * Compile the sketch/project via the configured toolchain (arduino-cli or west).
  */
-export function compileSketch(sketchDir, buildTarget, framework) {
-    if (framework?.includes('framework-esp32')) {
-        return compileEspIdfSketch(sketchDir, buildTarget);
+export function compileSketch(sketchDir, buildTarget, framework, toolchainType = 'arduino-cli', zephyrConfig) {
+    if (toolchainType === 'west') {
+        return compileWestProject(sketchDir, buildTarget, zephyrConfig);
     }
     return compileArduinoSketch(sketchDir, buildTarget);
 }
-/** Resolve the framework-esp32 dist/toolchain directory from node_modules.
- *  Uses the main export entry point (dist/index.js) to find the dist dir,
- *  avoiding the package's exports field restriction on subpaths. */
-function resolveFrameworkEsp32Dist() {
-    const indexPath = require_.resolve('@typecad/framework-esp32');
-    // indexPath = .../packages/framework-esp32/dist/index.js
-    // toolchain dir = .../packages/framework-esp32/dist/toolchain
-    return path.join(path.dirname(indexPath), 'toolchain');
-}
-/** Compile via arduino-cli (framework-arduino / framework-avr). */
+/** Compile via arduino-cli. */
 function compileArduinoSketch(sketchDir, buildTarget) {
     // Hard gate: verify arduino-cli + core before spawning.
     {
@@ -149,85 +127,109 @@ function compileArduinoSketch(sketchDir, buildTarget) {
     };
 }
 /**
- * Upload the compiled sketch to the board.
+ * Upload the compiled sketch/project to the board via the configured toolchain.
  */
-/**
- * Upload firmware. Detects the toolchain from the framework:
- * - framework-esp32 → idf.py flash
- * - everything else → arduino-cli upload
- */
-export function uploadSketch(sketchDir, buildTarget, port, framework) {
-    if (framework?.includes('framework-esp32')) {
-        return uploadEspIdfSketch(sketchDir, buildTarget, port);
+export function uploadSketch(sketchDir, buildTarget, port, framework, toolchainType = 'arduino-cli', zephyrConfig) {
+    if (toolchainType === 'west') {
+        return uploadWestProject(sketchDir, buildTarget, port, zephyrConfig);
     }
     return uploadArduinoSketch(sketchDir, buildTarget, port);
 }
-/** Compile via idf.py build (framework-esp32). */
-function compileEspIdfSketch(sketchDir, buildTarget) {
+/** Upload via arduino-cli. */
+function uploadArduinoSketch(sketchDir, buildTarget, port) {
+    // Hard gate: verify arduino-cli + core before spawning.
+    {
+        const gate = checkArduinoEnv(buildTarget);
+        if (!gate.ok) {
+            const message = formatEnvFailure(gate);
+            return { success: false, output: message, error: message };
+        }
+    }
+    const result = spawnSync('arduino-cli', ['upload', '--fqbn', buildTarget, '--port', port, sketchDir], { encoding: 'utf8', timeout: 60000 });
+    const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+    return {
+        success: result.status === 0,
+        output,
+        error: result.status !== 0 ? `Upload failed:\n${output}` : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Zephyr (west) toolchain
+// ---------------------------------------------------------------------------
+/**
+ * Compile a Zephyr project via `west build`. The Zephyr Toolchain (from
+ * @typecad/framework-zephyr) handles west discovery, ZEPHYR_BASE, scaffolding,
+ * and the board target. We call it via dynamic import to avoid a hard
+ * dependency on framework-zephyr (the Arduino path doesn't need it).
+ */
+function compileWestProject(sketchDir, buildTarget, zephyrConfig) {
+    // sketchDir for Zephyr is the project root containing src/, app/, build/.
+    // The transpiler emits src/src.cpp; the west project root is the parent of src/.
+    const srcDir = path.join(sketchDir, 'src');
+    const projectRoot = fs.existsSync(srcDir) ? sketchDir : path.dirname(sketchDir);
+    const sourcePath = fs.existsSync(path.join(srcDir, 'src.cpp'))
+        ? path.join(srcDir, 'src.cpp')
+        : path.join(sketchDir, 'src.cpp');
+    const outputDir = fs.existsSync(srcDir) ? srcDir : sketchDir;
     try {
-        const projectDir = path.basename(sketchDir) === 'main' ? path.dirname(sketchDir) : sketchDir;
-        const distDir = resolveFrameworkEsp32Dist();
-        const { compileEspIdf } = require_(path.join(distDir, 'compile.js'));
-        const result = compileEspIdf({
-            sourcePath: projectDir,
-            target: buildTarget || 'esp32',
+        // Dynamic import — framework-zephyr is an optional dependency (only present
+        // for Zephyr projects). The Toolchain object has compile()/upload().
+        const mod = require('@typecad/framework-zephyr');
+        const Toolchain = mod.Toolchain;
+        if (!Toolchain || typeof Toolchain.compile !== 'function') {
+            return { success: false, sketchDir, sketchPath: '', output: '', error: '@typecad/framework-zephyr did not export a usable Toolchain.compile().' };
+        }
+        const result = Toolchain.compile({
+            outputDir,
+            sourcePath,
+            buildTarget,
+            zephyrConfig,
         });
         return {
             success: result.success,
-            sketchDir: projectDir,
-            sketchPath: '',
+            sketchDir: projectRoot,
+            sketchPath: sourcePath,
             output: result.output,
-            error: result.errorMessage,
+            error: result.success ? undefined : `west build failed:\n${result.output}`,
         };
     }
     catch (e) {
-        return {
-            success: false,
-            sketchDir,
-            sketchPath: '',
-            output: '',
-            error: `idf.py compile failed: ${e instanceof Error ? e.message : String(e)}`,
-        };
+        return { success: false, sketchDir, sketchPath: '', output: '', error: `Failed to compile via west: ${e.message}` };
     }
 }
-/** Upload via idf.py flash (framework-esp32). */
-function uploadEspIdfSketch(sketchDir, buildTarget, port) {
+/**
+ * Upload (flash) a Zephyr project via `west flash`. For ESP32 boards, west
+ * uses the esptool runner; for nRF boards, nrfjprog. The port is forwarded.
+ */
+function uploadWestProject(sketchDir, buildTarget, port, zephyrConfig) {
+    const srcDir = path.join(sketchDir, 'src');
+    const projectRoot = fs.existsSync(srcDir) ? sketchDir : path.dirname(sketchDir);
+    const sourcePath = fs.existsSync(path.join(srcDir, 'src.cpp'))
+        ? path.join(srcDir, 'src.cpp')
+        : path.join(sketchDir, 'src.cpp');
+    const outputDir = fs.existsSync(srcDir) ? srcDir : sketchDir;
     try {
-        const projectDir = path.basename(sketchDir) === 'main' ? path.dirname(sketchDir) : sketchDir;
-        const distDir = resolveFrameworkEsp32Dist();
-        const { uploadEspIdf } = require_(path.join(distDir, 'upload.js'));
-        const result = uploadEspIdf(projectDir, port);
+        const mod = require('@typecad/framework-zephyr');
+        const Toolchain = mod.Toolchain;
+        if (!Toolchain || typeof Toolchain.upload !== 'function') {
+            return { success: false, output: '', error: '@typecad/framework-zephyr did not export a usable Toolchain.upload().' };
+        }
+        const result = Toolchain.upload({
+            outputDir,
+            sourcePath,
+            buildTarget,
+            port,
+            zephyrConfig,
+        });
         return {
             success: result.success,
             output: result.output,
-            error: result.errorMessage,
+            error: result.success ? undefined : `west flash failed:\n${result.output}`,
         };
     }
     catch (e) {
-        return {
-            success: false,
-            output: '',
-            error: `idf.py flash failed: ${e instanceof Error ? e.message : String(e)}`,
-        };
-    }
-}
-/** Upload via arduino-cli (framework-arduino / framework-avr). */
-function uploadArduinoSketch(sketchDir, buildTarget, port) {
-    // Hard gate: verify arduino-cli + core before spawning.
-    {
-        const gate = checkArduinoEnv(buildTarget);
-        if (!gate.ok) {
-            const message = formatEnvFailure(gate);
-            return { success: false, output: message, error: message };
-        }
+        return { success: false, output: '', error: `Failed to flash via west: ${e.message}` };
     }
-    const result = spawnSync('arduino-cli', ['upload', '--fqbn', buildTarget, '--port', port, sketchDir], { encoding: 'utf8', timeout: 60000 });
-    const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
-    return {
-        success: result.status === 0,
-        output,
-        error: result.status !== 0 ? `Upload failed:\n${output}` : undefined,
-    };
 }
 // ---------------------------------------------------------------------------
 // Internal
@@ -256,7 +258,7 @@ function resolveCuttlefishCmd(projectRoot) {
     // Fallback: assume it's on PATH
     return 'cuttlefish';
 }
-function findOutputDir(buildDir, baseName, projectRoot) {
+function findOutputDir(buildDir, baseName, projectRoot, toolchainType = 'arduino-cli') {
     // The cuttlefish transpiler writes output next to the source by default,
     // or to the configured outDir.  Check common locations.
     const candidates = [
@@ -268,40 +270,59 @@ function findOutputDir(buildDir, baseName, projectRoot) {
         path.join(projectRoot, '.build', 'expect', baseName, baseName),
     ];
     for (const c of candidates) {
-        if (fs.existsSync(c) && hasInoFile(c))
+        if (fs.existsSync(c) && hasEntryFile(c, toolchainType))
             return c;
     }
-    // Last resort: walk the buildDir tree recursively to find any .ino
-    const found = findInoFileRecursive(buildDir);
+    // Last resort: walk the buildDir tree recursively to find any entry file
+    const found = findEntryFileRecursive(buildDir, toolchainType);
     if (found)
         return path.dirname(found);
     return buildDir;
 }
-function hasInoFile(dir) {
+/** Check for a .ino (Arduino) or .cpp (Zephyr) entry file in a directory. */
+function hasEntryFile(dir, toolchainType = 'arduino-cli') {
     if (!fs.existsSync(dir))
         return false;
-    return fs.readdirSync(dir).some(f => f.endsWith('.ino') || f.endsWith('.cc'));
+    return fs.readdirSync(dir).some(f => isEntryFileName(f, toolchainType));
+}
+/** True if the filename is a valid entry file for the toolchain. */
+function isEntryFileName(name, toolchainType) {
+    if (toolchainType === 'west') {
+        return name.endsWith('.cpp') || name.endsWith('.cc');
+    }
+    return name.endsWith('.ino') || name.endsWith('.cc');
 }
-function findInoFile(dir) {
+/** Find the entry file (.ino for Arduino, .cpp for Zephyr) in a directory. */
+function findEntryFile(dir, toolchainType = 'arduino-cli') {
     if (!fs.existsSync(dir))
         return undefined;
     for (const entry of fs.readdirSync(dir)) {
-        // Accept .ino (Arduino) and .cc (ESP-IDF main.cc) as entry files.
-        if (entry.endsWith('.ino') || entry.endsWith('.cc')) {
+        if (isEntryFileName(entry, toolchainType)) {
             return path.join(dir, entry);
         }
     }
+    // For Zephyr, the entry may be in a src/ subdirectory
+    if (toolchainType === 'west') {
+        const srcDir = path.join(dir, 'src');
+        if (fs.existsSync(srcDir)) {
+            for (const entry of fs.readdirSync(srcDir)) {
+                if (isEntryFileName(entry, toolchainType)) {
+                    return path.join(srcDir, entry);
+                }
+            }
+        }
+    }
     return undefined;
 }
-function findInoFileRecursive(dir) {
+function findEntryFileRecursive(dir, toolchainType = 'arduino-cli') {
     if (!fs.existsSync(dir))
         return undefined;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-        if (entry.name.endsWith('.ino') || entry.name.endsWith('.cc')) {
+        if (isEntryFileName(entry.name, toolchainType)) {
             return path.join(dir, entry.name);
         }
         if (entry.isDirectory()) {
-            const result = findInoFileRecursive(path.join(dir, entry.name));
+            const result = findEntryFileRecursive(path.join(dir, entry.name), toolchainType);
             if (result)
                 return result;
         }
@@ -322,8 +343,14 @@ function rewriteRelativeImports(source, originalFilePath, buildDir) {
         return `from ${quote}${relativePath}${quote}`;
     });
 }
-function writeBuildConfig(buildDir, projectRoot, entryFileName, buildTarget) {
-    const baseConfigPath = path.join(projectRoot, 'cuttlefish.config.ts');
+function writeBuildConfig(buildDir, projectRoot, entryFileName, buildTarget, configPath) {
+    // Resolve the source config: an explicit --config path wins; otherwise fall
+    // back to cuttlefish.config.ts in the project root. The transpile runs from
+    // buildDir, so we inline the scalar fields the cuttlefish transpiler needs
+    // (target/board/mcu/framework/buildTarget/toolchain/zephyr) into a generated
+    // cuttlefish.config.ts there — the config loader can't evaluate spreads or
+    // relative imports, and discovery from buildDir would find no config.
+    const baseConfigPath = configPath ?? path.join(projectRoot, 'cuttlefish.config.ts');
     const buildConfigPath = path.join(buildDir, 'cuttlefish.config.ts');
     if (fs.existsSync(baseConfigPath)) {
         // Parse base config via AST to extract scalar values, then inline them.
@@ -339,10 +366,14 @@ function writeBuildConfig(buildDir, projectRoot, entryFileName, buildTarget) {
             lines.push(`  target: '${baseValues.target}',`);
         if (baseValues.board)
             lines.push(`  board: '${baseValues.board}',`);
+        if (baseValues.mcu)
+            lines.push(`  mcu: '${baseValues.mcu}',`);
         if (baseValues.framework)
             lines.push(`  framework: '${baseValues.framework}',`);
         if (baseValues.frameworkData?.buildTarget)
             lines.push(`  frameworkData: { buildTarget: '${baseValues.frameworkData.buildTarget}' },`);
+        if (baseValues.toolchain?.type)
+            lines.push(`  toolchain: { type: '${baseValues.toolchain.type}' },`);
         lines.push('  output: {');
         if (baseValues.output?.framework)
             lines.push(`    framework: '${baseValues.output?.framework}',`);
@@ -355,6 +386,16 @@ function writeBuildConfig(buildDir, projectRoot, entryFileName, buildTarget) {
             lines.push(`    baudRate: ${baseValues.console?.baudRate},`);
             lines.push('  },');
         }
+        // Pass the zephyr section (kconfig, runner) through verbatim — the Zephyr
+        // toolchain reads runner from it (e.g. zephyr.runner: 'uf2'). Serialize the
+        // parsed object as a minimal object literal (string values only; sufficient
+        // for the scalar fields the toolchain reads).
+        if (baseValues.zephyr && Object.keys(baseValues.zephyr).length > 0) {
+            const parts = Object.entries(baseValues.zephyr)
+                .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+                .join(', ');
+            lines.push(`  zephyr: { ${parts} },`);
+        }
         lines.push('};');
         lines.push('');
         lines.push('export default config;');

package/dist/host/config.d.ts

@@ -8,14 +8,19 @@ import type { ResolvedConfig, TestConfig } from './types.js';
  * @param projectRoot  Absolute path to the project root.
  * @param overrides    CLI flag overrides for test config.
  */
-export declare function loadConfig(projectRoot: string, overrides?: Partial<TestConfig>): ResolvedConfig;
+export declare function loadConfig(projectRoot: string, overrides?: Partial<TestConfig>, explicitConfigPath?: string): ResolvedConfig;
 export interface RawConfig {
     target?: string;
     board?: string;
+    mcu?: string;
     frameworkData?: {
         buildTarget?: string;
     };
     framework?: string;
+    toolchain?: {
+        type?: string;
+    };
+    zephyr?: Record<string, unknown>;
     test?: Partial<TestConfig>;
     output?: {
         framework?: string;

package/dist/host/config.js

@@ -29,8 +29,12 @@ const DEFAULT_TEST_CONFIG = {
  * @param projectRoot  Absolute path to the project root.
  * @param overrides    CLI flag overrides for test config.
  */
-export function loadConfig(projectRoot, overrides = {}) {
-    const configPath = findConfigFile(projectRoot);
+export function loadConfig(projectRoot, overrides = {}, explicitConfigPath) {
+    // An explicit --config path wins; otherwise discover cuttlefish.config.ts in
+    // the project root. The explicit path lets a project hold several configs
+    // (e.g. one per target board) and select one at run time instead of keeping
+    // a single cuttlefish.config.ts as the only entry.
+    const configPath = explicitConfigPath ?? findConfigFile(projectRoot);
     if (!configPath) {
         throw new Error(`No cuttlefish.config.ts found in ${projectRoot}. ` +
             `Create one or specify --port and --board on the command line.`);
@@ -56,7 +60,13 @@ export function loadConfig(projectRoot, overrides = {}) {
         board: test.board ?? raw.board ?? '@typecad/board-arduino-uno',
         target: raw.target ?? 'avr',
         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
+        // extract board/MCU for the transpile, so it must point at the same file
+        // loadConfig parsed (not always the default cuttlefish.config.ts).
+        configPath,
     };
 }
 // ---------------------------------------------------------------------------
@@ -103,6 +113,10 @@ function extractConfigProperties(obj, out) {
                 if (ts.isStringLiteral(prop.initializer))
                     out.board = prop.initializer.text;
                 break;
+            case 'mcu':
+                if (ts.isStringLiteral(prop.initializer))
+                    out.mcu = prop.initializer.text;
+                break;
             case 'frameworkData':
                 if (ts.isObjectLiteralExpression(prop.initializer)) {
                     out.frameworkData = {};
@@ -118,6 +132,41 @@ function extractConfigProperties(obj, out) {
                 if (ts.isStringLiteral(prop.initializer))
                     out.framework = prop.initializer.text;
                 break;
+            case 'toolchain':
+                if (ts.isObjectLiteralExpression(prop.initializer)) {
+                    out.toolchain = {};
+                    for (const tProp of prop.initializer.properties) {
+                        if (ts.isPropertyAssignment(tProp) && tProp.name.getText() === 'type' && ts.isStringLiteral(tProp.initializer)) {
+                            out.toolchain.type = tProp.initializer.text;
+                        }
+                    }
+                }
+                break;
+            case 'zephyr':
+                // Parse the zephyr section (kconfig, runner, cmakeArgs) as a generic
+                // object so it can be passed through to the Zephyr toolchain.
+                if (ts.isObjectLiteralExpression(prop.initializer)) {
+                    out.zephyr = {};
+                    for (const zProp of prop.initializer.properties) {
+                        if (ts.isPropertyAssignment(zProp)) {
+                            const key = zProp.name.getText();
+                            if (ts.isObjectLiteralExpression(zProp.initializer)) {
+                                // kconfig: { 'CONFIG_X': 'y' }
+                                const sub = {};
+                                for (const subProp of zProp.initializer.properties) {
+                                    if (ts.isPropertyAssignment(subProp) && ts.isStringLiteral(subProp.initializer)) {
+                                        sub[subProp.name.getText().replace(/['"]/g, '')] = subProp.initializer.text;
+                                    }
+                                }
+                                out.zephyr[key] = sub;
+                            }
+                            else if (ts.isStringLiteral(zProp.initializer)) {
+                                out.zephyr[key] = zProp.initializer.text;
+                            }
+                        }
+                    }
+                }
+                break;
             case 'test':
                 if (ts.isObjectLiteralExpression(prop.initializer)) {
                     out.test = extractTestConfig(prop.initializer);

package/dist/host/preprocessor.d.ts

@@ -15,15 +15,12 @@ export interface OutputShim {
 }
 /** Default shim: Arduino HardwareSerial. */
 export declare const serialShim: OutputShim;
-/** AVR native UART shim: routes through framework-avr's _uart_* helpers. */
-export declare const avrUartShim: OutputShim;
-/** ESP-IDF shim: emits console.debug (print, no newline) and console.log
- *  (println, with newline) calls. The transpiler's transformConsoleCall lowers
- *  these to printf for framework-esp32. Using different console methods lets
- *  the lowering distinguish "partial line" (print/debug) from "end of line"
- *  (println/log) — critical for the [TC:EXPECT:...] protocol format which
- *  spans multiple print calls on a single line. */
-export declare const espIdfShim: 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().
+ */
+export declare const zephyrShim: OutputShim;
 export interface PreprocessorOptions {
     /** Wrap string literals in Arduino F() macro to save SRAM on AVR. */
     isAvr?: boolean;
@@ -49,8 +46,7 @@ export declare class PreprocessorContext {
     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()).
-     *  The avrUartShim runs without the core, so F() is undefined — plain strings. */
+     *  Only applies when using the serialShim (Arduino core provides F()). */
     flash(s: string): string;
     /** Emit a line of TypeScript output. */
     emit(line: string): void;

package/dist/host/preprocessor.js

@@ -31,24 +31,16 @@ export const serialShim = {
     println: (e) => `Serial.println(${e})`,
     delay: 'delay(1000)',
 };
-/** AVR native UART shim: routes through framework-avr's _uart_* helpers. */
-export const avrUartShim = {
-    begin: '_uart_init(115200)',
-    print: (e) => `_uart_print_expr(${e})`,
-    println: (e) => `_uart_println_expr(${e})`,
-    delay: '_native_delay_ms(1000)',
-};
-/** ESP-IDF shim: emits console.debug (print, no newline) and console.log
- *  (println, with newline) calls. The transpiler's transformConsoleCall lowers
- *  these to printf for framework-esp32. Using different console methods lets
- *  the lowering distinguish "partial line" (print/debug) from "end of line"
- *  (println/log) — critical for the [TC:EXPECT:...] protocol format which
- *  spans multiple print calls on a single line. */
-export const espIdfShim = {
-    begin: '',
-    print: (e) => `console.debug(${e})`,
-    println: (e) => `console.log(${e})`,
-    delay: 'Timing.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().
+ */
+export const zephyrShim = {
+    begin: '', // Zephyr console auto-initializes via DT; no explicit begin needed
+    print: (e) => `__tc_print(${e})`,
+    println: (e) => `__tc_println(${e})`,
+    delay: 'k_msleep(1000)',
 };
 /**
  * Preprocess a test file's TypeScript source.
@@ -91,11 +83,8 @@ export class PreprocessorContext {
         this.shim = shim;
     }
     /** Wrap a string literal in F() on AVR to keep it in flash.
-     *  Only applies when using the serialShim (Arduino core provides F()).
-     *  The avrUartShim runs without the core, so F() is undefined — plain strings. */
+     *  Only applies when using the serialShim (Arduino core provides F()). */
     flash(s) {
-        if (this.shim === avrUartShim)
-            return `"${s}"`;
         return this.isAvr ? `F("${s}")` : `"${s}"`;
     }
     /** Emit a line of TypeScript output. */

package/dist/host/reporter.js

@@ -82,6 +82,11 @@ function reportFile(file, verbose) {
         console.log();
         return;
     }
+    if (file.compiled) {
+        console.log(` ${PASS_ICON} ${BOLD}${file.filePath}${RESET} ${GREEN}(compiled, dry-run)${RESET}`);
+        console.log();
+        return;
+    }
     for (const desc of file.describes) {
         reportDescribe(desc, verbose);
     }

package/dist/host/runner.js

@@ -7,7 +7,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { findTestFiles } from './finder.js';
-import { preprocess, serialShim, avrUartShim, espIdfShim } from './preprocessor.js';
+import { preprocess, serialShim, zephyrShim } from './preprocessor.js';
 import { transpileTestFile, compileSketch, uploadSketch } from './compiler.js';
 import { readSerialOutput } from './serial.js';
 import { parseProtocolLines } from './parser.js';
@@ -43,6 +43,12 @@ export async function run(config) {
         const result = await processTestFile(filePath, config);
         fileResults.push(result);
         reportFileResult(result, { verbose: config.test.verbose });
+        // --bail: stop after the first file that fails to compile/upload or has a
+        // failing test (skipped/compiled files don't count as failures).
+        if (config.bail && (result.error || (result.describes.length > 0 && !result.passed))) {
+            console.log(`${YELLOW}--bail: stopping after first failure${RESET}`);
+            break;
+        }
     }
     // 3. Aggregate results
     const runResult = aggregateResults(fileResults, Date.now() - startTime);
@@ -73,8 +79,8 @@ async function processTestFile(filePath, config) {
     }
     // Validate port only for files that will actually compile/upload. This lets
     // target-incompatible files be skipped without requiring hardware to be
-    // connected.
-    if (!config.test.port) {
+    // connected, and lets --dry-run run without any port (it stops after compile).
+    if (!config.test.port && !config.dryRun) {
         return errorResult(filePath, 'No serial port specified. Use --port <port> or set test.port in cuttlefish.config.ts', startTime);
     }
     console.log(`${CYAN}●${RESET} ${relativePath}`);
@@ -84,9 +90,7 @@ async function processTestFile(filePath, config) {
     try {
         preprocessed = preprocess(source, path.basename(filePath), {
             isAvr: config.target === 'avr' || config.target === 'megaavr',
-            shim: config.framework === '@typecad/framework-avr' ? avrUartShim
-                : config.framework?.includes('framework-esp32') ? espIdfShim
-                    : serialShim,
+            shim: config.toolchainType === 'west' ? zephyrShim : serialShim,
         });
     }
     catch (e) {
@@ -94,19 +98,26 @@ async function processTestFile(filePath, config) {
     }
     // Step 2: Transpile to C++
     console.log(`  ${DIM}transpiling...${RESET}`);
-    const transpileResult = transpileTestFile(preprocessed, filePath, config.projectRoot, config.buildTarget);
+    const transpileResult = transpileTestFile(preprocessed, filePath, config.projectRoot, config.buildTarget, config.toolchainType, config.configPath);
     if (!transpileResult.success) {
         return errorResult(filePath, transpileResult.error ?? 'Transpilation failed', startTime);
     }
-    // Step 3: Compile (arduino-cli or idf.py depending on framework)
+    // Step 3: Compile via the configured toolchain (arduino-cli or west)
     console.log(`  ${DIM}compiling...${RESET}`);
-    const compileResult = compileSketch(transpileResult.sketchDir, config.buildTarget, config.framework);
+    const compileResult = compileSketch(transpileResult.sketchDir, config.buildTarget, config.framework, config.toolchainType, config.zephyrConfig);
     if (!compileResult.success) {
         return errorResult(filePath, compileResult.error ?? 'Compilation failed', startTime);
     }
-    // Step 4: Upload (arduino-cli or idf.py depending on framework)
+    // --dry-run: stop after a successful compile. Skips upload + serial read so
+    // the pipeline can be verified without hardware attached.
+    if (config.dryRun) {
+        const durationMs = Date.now() - startTime;
+        console.log(`  ${DIM}compiled (dry-run, skipping upload and tests)${RESET}`);
+        return { filePath: relativePath, describes: [], passed: true, durationMs, debugOutput: [], compiled: true };
+    }
+    // Step 4: Upload via the configured toolchain
     console.log(`  ${DIM}uploading to ${config.test.port}...${RESET}`);
-    const uploadResult = uploadSketch(transpileResult.sketchDir, config.buildTarget, config.test.port, config.framework);
+    const uploadResult = uploadSketch(transpileResult.sketchDir, config.buildTarget, config.test.port, config.framework, config.toolchainType, config.zephyrConfig);
     if (!uploadResult.success) {
         return errorResult(filePath, uploadResult.error ?? 'Upload failed', startTime);
     }

package/dist/host/types.d.ts

@@ -67,6 +67,8 @@ export interface FileResult {
     skipReason?: string;
     /** If the file didn't compile or upload. */
     error?: string;
+    /** True under --dry-run: the file compiled but was not uploaded/run. */
+    compiled?: boolean;
 }
 /**
  * Result of the entire test run.
@@ -118,6 +120,16 @@ export interface ResolvedConfig {
     target: string;
     /** Framework package name, e.g. "@typecad/framework-avr". */
     framework?: string;
+    /** Toolchain type from config: 'arduino-cli' (default) or 'west' (Zephyr). */
+    toolchainType: 'arduino-cli' | 'west';
+    /** Zephyr-specific config (kconfig, etc.) from cuttlefish.config.ts. */
+    zephyrConfig?: Record<string, unknown>;
     /** Absolute path to project root. */
     projectRoot: string;
+    /** Absolute path to the cuttlefish config file these values were read from. */
+    configPath: string;
+    /** --dry-run: compile every file but skip upload and test execution. */
+    dryRun?: boolean;
+    /** --bail: stop after the first failing test file. */
+    bail?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/expect",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.8",
   "description": "Hardware test framework for TypeCAD — vitest-style assertions over serial",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,10 +40,10 @@
   "dependencies": {
     "typescript": "^5.7.3",
     "serialport": "^12.0.0",
-    "@typecad/arduino-cli": "1.0.0-alpha.7"
+    "@typecad/arduino-cli": "1.0.0-alpha.8"
   },
   "devDependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.7",
+    "@typecad/cuttlefish": "1.0.0-alpha.8",
     "@types/node": "^22.10.7"
   },
   "license": "MIT",