@typecad/expect 0.1.0-alpha.2 → 1.0.0-alpha.11

package/README.md

@@ -62,7 +62,7 @@ Hardware test runner for [TypeCAD](../../README.md). Write vitest-style assertio
 npm install --save-dev @typecad/expect @typecad/cuttlefish
 ```
 
-`@typecad/expect` ships the `cuttlefish-test` CLI. It pairs with [`@typecad/cuttlefish`](https://github.com/justind000/typecode/tree/main/packages/cuttlefish), which transpiles your TypeScript test files to C++ for upload to hardware.
+`@typecad/expect` ships the `cuttlefish-test` CLI. It pairs with [`@typecad/cuttlefish`](https://cuttlefish.typecad.net), which transpiles your TypeScript test files to C++ for upload to hardware.
 
 **Prerequisites:**
 
@@ -152,13 +152,13 @@ All numeric matchers return the parent `Suite`, so you can continue the chain wi
 
 ```bash
 # Run a specific file
-npx cuttlefish-test examples/my-sensor.test.ts
+npx --package=@typecad/expect cuttlefish-test examples/my-sensor.test.ts
 
 # Run all test files matched by config include patterns
-npx cuttlefish-test
+npx --package=@typecad/expect cuttlefish-test
 
 # Override the port at run-time
-npx cuttlefish-test --port /dev/ttyACM0 examples/my-sensor.test.ts
+npx --package=@typecad/expect cuttlefish-test --port /dev/ttyACM0 examples/my-sensor.test.ts
 ```
 
 Or via the npm script defined in the root `package.json`:
@@ -253,10 +253,10 @@ Example flow:
 
 ```bash
 # 1. Compile and upload the serial-output showcase
-npx cuttlefish src/23-transpiler-showcase.ts --compile --upload --port COM4
+npx @typecad/cuttlefish src/23-transpiler-showcase.ts --compile --upload --port COM4
 
 # 2. Run the on-hardware expect test against the connected Uno
-npx cuttlefish-test examples/24-uno-validation.test.ts --port COM4
+npx --package=@typecad/expect cuttlefish-test examples/24-uno-validation.test.ts --port COM4
 ```
 
 This hybrid workflow is the recommended way to confirm that simple variables, arithmetic, arrays, enums, functions, GPIO, and analog input are behaving correctly on real Uno hardware.

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,17 +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 Arduino sketch using arduino-cli.
+ * Compile the sketch/project via the configured toolchain (arduino-cli or west).
  */
-export declare function compileSketch(sketchDir: string, buildTarget: 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.
  */
-export declare function uploadSketch(sketchDir: string, buildTarget: string, port: 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

@@ -7,18 +7,32 @@
 import path from 'node:path';
 import fs from 'node:fs';
 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 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];
+    if (failure.fixCommand)
+        lines.push(`  Fix: ${failure.fixCommand}`);
+    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
+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 buildDir = path.join(projectRoot, '.build', 'expect', baseName);
     try {
+        // Fresh dir for every transpile.
         fs.rmSync(buildDir, { recursive: true, force: true });
         fs.mkdirSync(buildDir, { recursive: true });
     }
@@ -32,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']
@@ -54,29 +77,45 @@ 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 Arduino sketch using arduino-cli.
+ * Compile the sketch/project via the configured toolchain (arduino-cli or west).
  */
-export function compileSketch(sketchDir, buildTarget) {
+export function compileSketch(sketchDir, buildTarget, framework, toolchainType = 'arduino-cli', zephyrConfig) {
+    if (toolchainType === 'west') {
+        return compileWestProject(sketchDir, buildTarget, zephyrConfig);
+    }
+    return compileArduinoSketch(sketchDir, buildTarget);
+}
+/** Compile via arduino-cli. */
+function compileArduinoSketch(sketchDir, buildTarget) {
+    // Hard gate: verify arduino-cli + core before spawning.
+    {
+        const gate = checkArduinoEnv(buildTarget);
+        if (!gate.ok) {
+            const message = formatEnvFailure(gate);
+            return { success: false, sketchDir, sketchPath: '', output: message, error: message };
+        }
+    }
     const result = spawnSync('arduino-cli', ['compile', '--fqbn', buildTarget, sketchDir], { encoding: 'utf8', timeout: 120000 });
     const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
     return {
@@ -88,9 +127,24 @@ export function compileSketch(sketchDir, buildTarget) {
     };
 }
 /**
- * Upload the compiled sketch to the board.
+ * Upload the compiled sketch/project to the board via the configured toolchain.
  */
-export function uploadSketch(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);
+}
+/** 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 {
@@ -100,6 +154,84 @@ export function uploadSketch(sketchDir, buildTarget, port) {
     };
 }
 // ---------------------------------------------------------------------------
+// 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 {
+        // 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: projectRoot,
+            sketchPath: sourcePath,
+            output: result.output,
+            error: result.success ? undefined : `west build failed:\n${result.output}`,
+        };
+    }
+    catch (e) {
+        return { success: false, sketchDir, sketchPath: '', output: '', error: `Failed to compile via west: ${e.message}` };
+    }
+}
+/**
+ * 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 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.success ? undefined : `west flash failed:\n${result.output}`,
+        };
+    }
+    catch (e) {
+        return { success: false, output: '', error: `Failed to flash via west: ${e.message}` };
+    }
+}
+// ---------------------------------------------------------------------------
 // Internal
 // ---------------------------------------------------------------------------
 function resolveCuttlefishCmd(projectRoot) {
@@ -126,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 = [
@@ -138,39 +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'));
+    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)) {
-        if (entry.endsWith('.ino')) {
+        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')) {
+        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;
         }
@@ -191,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.
@@ -208,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}',`);
@@ -224,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.`);
@@ -55,7 +59,14 @@ export function loadConfig(projectRoot, overrides = {}) {
         buildTarget: test.buildTarget ?? raw.frameworkData?.buildTarget ?? 'arduino:avr:uno',
         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,
     };
 }
 // ---------------------------------------------------------------------------
@@ -102,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 = {};
@@ -117,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

@@ -1,6 +1,31 @@
+/**
+ * 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).
+ */
+export interface OutputShim {
+    /** The init call emitted in the preamble, e.g. "Serial.begin(115200)". */
+    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)". */
+    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().
+ */
+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). */
+    shim?: OutputShim;
 }
 /**
  * Preprocess a test file's TypeScript source.
@@ -17,10 +42,11 @@ export declare class PreprocessorContext {
     private varCounter;
     private fnCounter;
     private preambleEmitted;
-    private readonly baudRate;
     readonly isAvr: boolean;
-    constructor(isAvr: boolean);
-    /** Wrap a string literal in F() on AVR to keep it in flash. */
+    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;
     /** Emit a line of TypeScript output. */
     emit(line: string): void;

package/dist/host/preprocessor.js

@@ -24,6 +24,24 @@
 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().
+ */
+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.
  *
@@ -35,7 +53,7 @@ import { emitSegments } from './protocol-emitter.js';
  */
 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);
+    const ctx = new PreprocessorContext(options?.isAvr ?? false, options?.shim);
     for (const stmt of sf.statements) {
         if (ts.isImportDeclaration(stmt)) {
             const moduleSpecifier = stmt.moduleSpecifier.text;
@@ -56,15 +74,16 @@ export function preprocess(source, fileName = 'test.ts', options) {
 // PreprocessorContext — shared state threaded through sub-modules
 // ---------------------------------------------------------------------------
 export class PreprocessorContext {
-    constructor(isAvr) {
+    constructor(isAvr, shim = serialShim) {
         this.lines = [];
         this.varCounter = 0;
         this.fnCounter = 0;
         this.preambleEmitted = false;
-        this.baudRate = 115200;
         this.isAvr = isAvr;
+        this.shim = shim;
     }
-    /** Wrap a string literal in F() on AVR to keep it in flash. */
+    /** 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}"`;
     }
@@ -84,8 +103,8 @@ export class PreprocessorContext {
     }
     emitPreamble() {
         this.preambleEmitted = true;
-        this.lines.push(`Serial.begin(${this.baudRate});`);
-        this.lines.push(`Serial.println(${this.flash('[TC:SUITE_START]')});`);
+        this.lines.push(`${this.shim.begin};`);
+        this.lines.push(`${this.shim.println(this.flash('[TC:SUITE_START]'))};`);
     }
     build() {
         return this.lines.join('\n') + '\n';
@@ -97,8 +116,8 @@ export class PreprocessorContext {
 function processExpressionStatement(stmt, sf, ctx) {
     const expr = stmt.expression;
     if (isDoneCall(expr)) {
-        ctx.emit(`Serial.println(${ctx.flash('[TC:SUITE_END]')});`);
-        ctx.emit(`while (true) { delay(1000); }`);
+        ctx.emit(`${ctx.shim.println(ctx.flash('[TC:SUITE_END]'))};`);
+        ctx.emit(`while (true) { ${ctx.shim.delay}; }`);
         return;
     }
     if (isDescribeChain(expr)) {

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(`Serial.println(${ctx.flash(`[TC:DESCRIBE:${escapeProtocol(seg.name ?? '')}]`)});`);
+                ctx.emit(`${ctx.shim.println(ctx.flash(`[TC:DESCRIBE:${escapeProtocol(seg.name ?? '')}]`))};`);
                 break;
             case 'it':
-                ctx.emit(`Serial.println(${ctx.flash(`[TC:IT:${escapeProtocol(seg.name ?? '')}]`)});`);
+                ctx.emit(`${ctx.shim.println(ctx.flash(`[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(`Serial.print(${ctx.flash(`[TC:EXPECT:${matcher}:`)});`);
-        ctx.emit(`Serial.print("${escapeProtocol(rawExpected)}");`);
-        ctx.emit(`Serial.print(${ctx.flash(':')});`);
-        ctx.emit(`Serial.print(${actualVar});`);
-        ctx.emit(`Serial.println(${ctx.flash(']')});`);
+        ctx.emit(`${ctx.shim.print(ctx.flash(`[TC:EXPECT:${matcher}:`))};`);
+        ctx.emit(`${ctx.shim.print(`"${escapeProtocol(rawExpected)}"`)};`);
+        ctx.emit(`${ctx.shim.print(ctx.flash(':'))};`);
+        ctx.emit(`${ctx.shim.print(actualVar)};`);
+        ctx.emit(`${ctx.shim.println(ctx.flash(']'))};`);
         return;
     }
     const expectedPart = matcherArgs.join(',');
-    ctx.emit(`Serial.print(${ctx.flash(`[TC:EXPECT:${matcher}:${expectedPart}:`)});`);
-    ctx.emit(`Serial.print(${actualVar});`);
-    ctx.emit(`Serial.println(${ctx.flash(']')});`);
+    ctx.emit(`${ctx.shim.print(ctx.flash(`[TC:EXPECT:${matcher}:${expectedPart}:`))};`);
+    ctx.emit(`${ctx.shim.print(actualVar)};`);
+    ctx.emit(`${ctx.shim.println(ctx.flash(']'))};`);
 }
 // ---------------------------------------------------------------------------
 // Expression classification helpers

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 } 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,6 +90,7 @@ async function processTestFile(filePath, config) {
     try {
         preprocessed = preprocess(source, path.basename(filePath), {
             isAvr: config.target === 'avr' || config.target === 'megaavr',
+            shim: config.toolchainType === 'west' ? zephyrShim : serialShim,
         });
     }
     catch (e) {
@@ -91,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 with arduino-cli
+    // Step 3: Compile via the configured toolchain (arduino-cli or west)
     console.log(`  ${DIM}compiling...${RESET}`);
-    const compileResult = compileSketch(transpileResult.sketchDir, config.buildTarget);
+    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
+    // --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);
+    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.
@@ -116,6 +118,18 @@ export interface ResolvedConfig {
     buildTarget: string;
     board: string;
     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": "0.1.0-alpha.2",
+  "version": "1.0.0-alpha.11",
   "description": "Hardware test framework for TypeCAD — vitest-style assertions over serial",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,10 +39,11 @@
   },
   "dependencies": {
     "typescript": "^5.7.3",
-    "serialport": "^12.0.0"
+    "serialport": "^12.0.0",
+    "@typecad/arduino-cli": "1.0.0-alpha.11"
   },
   "devDependencies": {
-    "@typecad/cuttlefish": "0.1.0-alpha.2",
+    "@typecad/cuttlefish": "1.0.0-alpha.11",
     "@types/node": "^22.10.7"
   },
   "license": "MIT",