@typecad/cuttlefish 0.1.0-alpha.2 → 1.0.0-alpha.6

package/README.md

@@ -3,7 +3,7 @@
 TypeScript → C++ transpiler for embedded firmware. Targets native (desktop),
 Arduino, and bare-metal MCU builds from a single TypeScript codebase.
 
-`cuttlefish` is the command-line tool at the center of the [TypeCAD](https://github.com/justind000/typecode)
+`cuttlefish` is the command-line tool at the center of the [TypeCAD](https://cuttlefish.typecad.net)
 toolchain: it loads `cuttlefish.config.ts`, transpiles TypeScript firmware to
 C++, and can chain compile, upload, and serial-monitor steps.
 
@@ -12,15 +12,15 @@ C++, and can chain compile, upload, and serial-monitor steps.
 From a project root containing `cuttlefish.config.ts`:
 
 ```bash
-npx cuttlefish build
-npx cuttlefish build --compile --upload --port COM4
-npx cuttlefish build --compile --upload --monitor --port COM4 --baud 115200
+npx @typecad/cuttlefish build
+npx @typecad/cuttlefish build --compile --upload --port COM4
+npx @typecad/cuttlefish build --compile --upload --monitor --port COM4 --baud 115200
 ```
 
 Scaffold a starter project with the built-in wizard:
 
 ```bash
-npx cuttlefish create --board arduino:avr:uno --framework arduino
+npx @typecad/cuttlefish create --board arduino:avr:uno --framework arduino
 ```
 
 ## Commands
@@ -67,11 +67,11 @@ export default config;
 
 `@typecad/cuttlefish` is the transpiler core. It pairs with sibling packages:
 
-- [`@typecad/hal`](https://github.com/justind000/typecode/tree/main/packages/hal) — hardware abstraction (GPIO, I2C, SPI, UART) as regular TypeScript.
-- [`@typecad/ui`](https://github.com/justind000/typecode/tree/main/packages/ui) — HTML/CSS-driven graphics for microcontroller displays.
-- [`@typecad/expect`](https://github.com/justind000/typecode/tree/main/packages/expect) — hardware test framework (vitest-style assertions over serial).
-- [`@typecad/framework-arduino`](https://github.com/justind000/typecode/tree/main/packages/framework-arduino) — Arduino framework code-gen strategy.
-- [`@typecad/framework-native`](https://github.com/justind000/typecode/tree/main/packages/framework-native) — native desktop C++ code-gen strategy.
+- [`@typecad/hal`](https://cuttlefish.typecad.net) — hardware abstraction (GPIO, I2C, SPI, UART) as regular TypeScript.
+- [`@typecad/ui`](https://cuttlefish.typecad.net) — HTML/CSS-driven graphics for microcontroller displays.
+- [`@typecad/expect`](https://cuttlefish.typecad.net) — hardware test framework (vitest-style assertions over serial).
+- [`@typecad/framework-arduino`](https://cuttlefish.typecad.net) — Arduino framework code-gen strategy.
+- [`@typecad/framework-native`](https://cuttlefish.typecad.net) — native desktop C++ code-gen strategy.
 - `@typecad/mcu-*` and `@typecad/board-*` — silicon- and board-level pin/peripheral definitions.
 
 ## License

package/dist/api/board-types.d.ts

@@ -1 +1 @@
-export type ArchitectureIdentifier = 'avr' | 'esp32' | 'esp32s2' | 'esp32s3' | 'esp32c3' | 'esp32c6' | 'rp2040' | 'samd' | 'stm32' | 'nrf52' | (string & {});
+export type ArchitectureIdentifier = 'avr' | 'esp32' | 'esp32s2' | 'esp32s3' | 'esp32c3' | 'esp32c6' | 'rp2040' | 'rp2350' | 'samd' | 'stm32' | 'nrf52' | (string & {});

package/dist/api/shared/hal-op-ir.d.ts

@@ -267,6 +267,15 @@ export interface SpiCsHighOp {
     port?: string;
     pin: number;
 }
+export interface SpiReadBufferOp {
+    operation: "spi.read_buffer";
+    bus: string;
+    /** Number of bytes — numeric or runtime expression string */
+    count: number | string;
+    /** Buffer variable name, "__HAL_READ_BUF__" placeholder (rewritten to the
+     *  caller's variable by the variable-init transformer), or "__DISCARD__" */
+    buffer: string;
+}
 export interface UartBeginOp {
     operation: "uart.begin";
     port: string;
@@ -385,7 +394,7 @@ export interface RawCppOp {
  * operations. Each node carries a semantic `operation` tag and typed
  * arguments. Framework strategies translate these into concrete C++.
  */
-export type HALOpIR = GpioWriteOp | GpioReadOp | GpioToggleOp | GpioSetModeOp | PwmWriteOp | PwmGetFrequencyOp | PwmGetResolutionOp | AdcReadOp | AdcGetResolutionOp | AdcSetReferenceOp | AdcGetReferenceOp | AdcReadVoltageOp | DacWriteOp | InterruptAttachOp | InterruptDetachOp | TonePlayOp | ToneStopOp | TimingDelayOp | TimingDelayMicrosecondsOp | TimingMillisOp | TimingMicrosOp | TimingFreeHeapOp | TimingSetIntervalOp | TimingSetTimeoutOp | TimingClearIntervalOp | TimingClearTimeoutOp | PowerDeepSleepOp | PowerLightSleepOp | PowerSetCpuFrequencyOp | I2cBeginOp | I2cEndOp | I2cSetClockOp | I2cBeginTransmissionOp | I2cWriteOp | I2cWriteBytesOp | I2cWriteBufferOp | I2cReadBufferOp | I2cEndTransmissionOp | I2cRequestFromOp | I2cAvailableOp | I2cReadOp | I2cRecoverOp | SpiBeginOp | SpiEndOp | SpiTransferOp | SpibeginTransactionOp | SpiEndTransactionOp | SpiSetModeOp | SpiSetBitOrderOp | SpiCsLowOp | SpiCsHighOp | UartBeginOp | UartEndOp | UartPrintOp | UartPrintlnOp | UartPrintfOp | UartWriteOp | UartReadOp | UartPeekOp | UartAvailableOp | UartFlushOp | PulseInOp | PulseInLongOp | ShiftOutOp | ShiftInOp | BoardResolveOp | WdtEnableOp | WdtResetOp | WdtDisableOp | SnprintfEmitOp | RawCppOp | DisplayHALOp;
+export type HALOpIR = GpioWriteOp | GpioReadOp | GpioToggleOp | GpioSetModeOp | PwmWriteOp | PwmGetFrequencyOp | PwmGetResolutionOp | AdcReadOp | AdcGetResolutionOp | AdcSetReferenceOp | AdcGetReferenceOp | AdcReadVoltageOp | DacWriteOp | InterruptAttachOp | InterruptDetachOp | TonePlayOp | ToneStopOp | TimingDelayOp | TimingDelayMicrosecondsOp | TimingMillisOp | TimingMicrosOp | TimingFreeHeapOp | TimingSetIntervalOp | TimingSetTimeoutOp | TimingClearIntervalOp | TimingClearTimeoutOp | PowerDeepSleepOp | PowerLightSleepOp | PowerSetCpuFrequencyOp | I2cBeginOp | I2cEndOp | I2cSetClockOp | I2cBeginTransmissionOp | I2cWriteOp | I2cWriteBytesOp | I2cWriteBufferOp | I2cReadBufferOp | I2cEndTransmissionOp | I2cRequestFromOp | I2cAvailableOp | I2cReadOp | I2cRecoverOp | SpiBeginOp | SpiEndOp | SpiTransferOp | SpibeginTransactionOp | SpiEndTransactionOp | SpiSetModeOp | SpiSetBitOrderOp | SpiCsLowOp | SpiCsHighOp | SpiReadBufferOp | UartBeginOp | UartEndOp | UartPrintOp | UartPrintlnOp | UartPrintfOp | UartWriteOp | UartReadOp | UartPeekOp | UartAvailableOp | UartFlushOp | PulseInOp | PulseInLongOp | ShiftOutOp | ShiftInOp | BoardResolveOp | WdtEnableOp | WdtResetOp | WdtDisableOp | SnprintfEmitOp | RawCppOp | DisplayHALOp;
 /**
  * Helper type: extracts the operation string from a HALOpIR variant.
  * Useful for type-safe switch statements in framework strategies.

package/dist/api/shared/platform-strategy.d.ts

@@ -8,6 +8,12 @@ import type { PlatformGraphicsStrategy } from './graphics-strategy.js';
 export interface PlatformProfileStrategy {
     /** System #include headers forced at the top of every emitted file. */
     forcedIncludes(program: ProgramIR, ctx?: PlatformContext): string[];
+    /**
+     * Filter the HAL-discovered required includes (from __includes metadata).
+     * Frameworks that provide native peripheral drivers can strip stale Arduino
+     * library includes here. Defaults to returning the includes unchanged.
+     */
+    filterRequiredIncludes?(includes: string[]): string[];
     /** Symbol aliases (TypeScript name → C++ name). */
     symbolAliases(program: ProgramIR, ctx?: PlatformContext): Record<string, string>;
     /** Extra shim lines emitted after includes (e.g. #define fallbacks). */

package/dist/api/shared/types.d.ts

@@ -26,6 +26,14 @@ export interface Diagnostic {
     column?: number;
     code?: string;
     source?: string;
+    /**
+     * Path (or basename) of the source file the diagnostic refers to. When set,
+     * it is rendered in the diagnostic header so the location is not just
+     * `(line,col)` but `path/to/file.ts (line,col)`. Emitters should prefer the
+     * real file path from the originating node's sourceSpan, falling back to a
+     * basename when the full path is unavailable.
+     */
+    filePath?: string;
     /** Text of the source line for display context. */
     sourceLine?: string;
 }

package/dist/cli-utils.d.ts

@@ -13,6 +13,7 @@ export declare function printDiagnostics(diagnostics: Array<Diagnostic | {
     line?: number;
     column?: number;
     code?: string;
+    filePath?: string;
     sourceLine?: string;
 }>): void;
 /**

package/dist/cli-utils.js

@@ -50,6 +50,7 @@ export function printDiagnostics(diagnostics) {
     for (const diagnostic of diagnostics) {
         const position = diagnostic.line && diagnostic.column ? chalk.gray(`(${diagnostic.line},${diagnostic.column})`) : "";
         const code = diagnostic.code ? chalk.gray(` [${diagnostic.code}]`) : "";
+        const file = 'filePath' in diagnostic && diagnostic.filePath ? chalk.cyan(diagnostic.filePath) : "";
         let severityLabel;
         let hintColor;
         if (diagnostic.severity === "error") {
@@ -65,7 +66,8 @@ export function printDiagnostics(diagnostics) {
             hintColor = chalk.cyan;
         }
         const location = position ? ` ${position}` : "";
-        const header = `${severityLabel}${code}${location}: ${chalk.white(diagnostic.message)}`;
+        const filePrefix = file ? `${file} ` : "";
+        const header = `${filePrefix}${severityLabel}${code}${location}: ${chalk.white(diagnostic.message)}`;
         if (diagnostic.severity === "error") {
             console.error(header);
         }

package/dist/cli.js

@@ -19,6 +19,8 @@ import { runExpectTests, assertTypeScriptInput, printDiagnostics, printMappedCom
 import { runPreviewServer } from "./preview/server.js";
 import * as ui from "./utils/ui.js";
 import chalk from "chalk";
+import { checkArduinoEnv } from "@typecad/arduino-cli";
+import { runLicensesPresenter } from "./licenses.js";
 function hasFatalDiagnostics(result) {
     return result.diagnostics.some((diagnostic) => diagnostic.severity === "error");
 }
@@ -107,6 +109,62 @@ async function handleBoardAdd(options) {
     }
     console.log(generateFrameworkChecklist(spec));
 }
+/**
+ * `cuttlefish doctor` — verify arduino-cli is installed and the board's core
+ * (derived from the FQBN in cuttlefish.config.ts) is present. Exits 0 if the
+ * environment is OK, non-zero otherwise. Reuses checkArduinoEnv so the
+ * detection logic is shared with the build/test gates.
+ */
+function runDoctor() {
+    ui.printHeader();
+    ui.printStep("Checking arduino-cli environment...");
+    const config = loadCuttlefishConfig(process.cwd());
+    const fqbn = config?.buildTarget;
+    const result = checkArduinoEnv(fqbn);
+    const check = result.check;
+    // arduino-cli presence line
+    if (check.arduinoCliInstalled) {
+        ui.printInfo(`arduino-cli .... ${check.arduinoCliVersion ?? "unknown"}  ✓`);
+    }
+    else if (!result.ok && result.reason === "arduino-cli-not-found") {
+        ui.printError(`arduino-cli .... NOT FOUND on PATH`);
+    }
+    else {
+        ui.printError(`arduino-cli .... found but unresponsive`);
+    }
+    // core presence line (only meaningful if we have an FQBN)
+    if (fqbn) {
+        if (check.requiredCore) {
+            const status = check.requiredCoreInstalled ? "installed ✓" : "NOT installed ✗";
+            const line = `${check.requiredCore} ....... ${status}`;
+            if (check.requiredCoreInstalled) {
+                ui.printInfo(line);
+            }
+            else {
+                ui.printError(line);
+                ui.printInfo(`  → run: arduino-cli core install ${check.requiredCore}`);
+            }
+        }
+    }
+    else {
+        ui.printInfo("(no buildTarget in cuttlefish.config.ts — skipping core check)");
+    }
+    // Exit code
+    if (result.ok) {
+        ui.printSuccess("Environment OK");
+        return; // exitCode stays unset => 0
+    }
+    if (!result.ok) {
+        for (const line of result.messages)
+            ui.printInfo(line);
+        process.exitCode = 1;
+    }
+}
+/**
+ * `cuttlefish licenses` dispatch — the presenter lives in licenses.ts so it is
+ * unit-testable without importing this binary entry module (cli.ts has a
+ * shebang and runs main() at import time). See runLicensesPresenter.
+ */
 async function main() {
     try {
         const options = parseCommandLine(process.argv);
@@ -154,6 +212,14 @@ async function main() {
             }
             return;
         }
+        if (options.command === "doctor") {
+            runDoctor();
+            return;
+        }
+        if (options.command === "licenses") {
+            runLicensesPresenter(options.strict ?? false, options.all ?? false);
+            return;
+        }
         // ── Handle build command — entry point comes from config ──────────
         if (options.command === "build") {
             const buildConfig = loadCuttlefishConfig(process.cwd());
@@ -361,6 +427,9 @@ async function main() {
                 });
                 printDiagnostics(result.diagnostics);
                 ui.printTasks(result.asyncTaskNames ?? [], result.usesTimers ?? false);
+                if (result.diagnosticsReportPath) {
+                    ui.printInfo(`Diagnostics report: ${result.diagnosticsReportPath}`);
+                }
                 if (result.diagnostics.length === 0) {
                     ui.printSuccess();
                     initialBuildOk = true;
@@ -451,6 +520,9 @@ async function main() {
                         });
                         printDiagnostics(rebuildResult.diagnostics);
                         ui.printTasks(rebuildResult.asyncTaskNames ?? [], rebuildResult.usesTimers ?? false);
+                        if (rebuildResult.diagnosticsReportPath) {
+                            ui.printInfo(`Diagnostics report: ${rebuildResult.diagnosticsReportPath}`);
+                        }
                         if (rebuildResult.diagnostics.length > 0) {
                             // Errors shown via printDiagnostics — skip compile/upload
                         }
@@ -535,6 +607,9 @@ async function main() {
             });
             printDiagnostics(result.diagnostics);
             ui.printTasks(result.asyncTaskNames ?? [], result.usesTimers ?? false);
+            if (result.diagnosticsReportPath) {
+                ui.printInfo(`Diagnostics report: ${result.diagnosticsReportPath}`);
+            }
         }
         if (hasFatalDiagnostics(result)) {
             ui.printError("Transpilation failed. Fix the transpiler diagnostics above before compiling.");

package/dist/create/index.d.ts

@@ -1,6 +1,6 @@
 export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printInitNextSteps } from './init-scaffold.js';
 export type { KnownTarget, KnownBoard, ScaffoldProjectResult } from './init-scaffold.js';
-export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateEslintConfig, } from './init-templates.js';
+export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, } from './init-templates.js';
 export type { InitProjectOptions } from './init-templates.js';
 export { runInitWizard } from './init-wizard.js';
 export { scaffoldBoardPackages } from './board-codegen.js';

package/dist/create/index.js

@@ -1,5 +1,5 @@
 export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printInitNextSteps } from './init-scaffold.js';
-export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateEslintConfig, } from './init-templates.js';
+export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, } from './init-templates.js';
 export { runInitWizard } from './init-wizard.js';
 // Board codegen tool (`cuttlefish board add`)
 export { scaffoldBoardPackages } from './board-codegen.js';

package/dist/create/init-scaffold.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import fs from "node:fs";
 import chalk from "chalk";
-import { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateBoardForwardingFile, generateEslintConfig, } from "./init-templates.js";
+import { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateBoardForwardingFile, generateEslintConfig, } from "./init-templates.js";
 import { generateEslintRules } from "./eslint-rules-template.js";
 const _knownTargets = [
     {
@@ -66,6 +66,28 @@ const _knownTargets = [
         buildTarget: 'esp32:esp32:esp32c6',
         mcu: 'esp32c6',
     },
+    {
+        id: 'rp2040',
+        displayName: 'RP2040 (Pico)',
+        isNative: false,
+        architecture: 'rp2040',
+        boardPackage: '@typecad/board-rp2040',
+        frameworkPackage: '@typecad/framework-arduino',
+        framework: 'arduino',
+        buildTarget: 'rp2040:rp2040:rpipico',
+        mcu: 'rp2040',
+    },
+    {
+        id: 'rp2350',
+        displayName: 'RP2350 (Pico 2)',
+        isNative: false,
+        architecture: 'rp2350',
+        boardPackage: '@typecad/board-rp2350',
+        frameworkPackage: '@typecad/framework-arduino',
+        framework: 'arduino',
+        buildTarget: 'rp2040:rp2040:rpipico2',
+        mcu: 'rp2350',
+    },
 ];
 export function registerKnownTarget(target) {
     const existing = _knownTargets.findIndex(t => t.id === target.id);
@@ -128,6 +150,24 @@ export function scaffoldProject(options, outDir) {
         fs.writeFileSync(sketchPath, generateStarterSketch(options), 'utf-8');
         createdFiles.push(sketchPath);
     }
+    // Embedded projects get a starter hardware test (@typecad/expect / cuttlefish-test).
+    // Native projects have no serial/board path, so they get no test setup.
+    if (!options.isNative) {
+        const testsDir = path.join(resolvedOutDir, 'tests');
+        fs.mkdirSync(testsDir, { recursive: true });
+        const testPath = path.join(testsDir, '01-basics.test.ts');
+        fs.writeFileSync(testPath, generateStarterTest(options), 'utf-8');
+        createdFiles.push(testPath);
+        // Host-side simulation (@typecad/simulator + vitest). sim/ is kept separate
+        // from tests/ so `vitest run sim/` never loads the @typecad/expect no-op
+        // stubs, and `cuttlefish-test` (which globs tests/) never tries to flash a
+        // simulator file as firmware.
+        const simDir = path.join(resolvedOutDir, 'sim');
+        fs.mkdirSync(simDir, { recursive: true });
+        const simPath = path.join(simDir, 'main.test.ts');
+        fs.writeFileSync(simPath, generateStarterSim(options), 'utf-8');
+        createdFiles.push(simPath);
+    }
     return { createdFiles, outDir: resolvedOutDir, options };
 }
 export function printInitNextSteps(options, outDir) {
@@ -142,9 +182,15 @@ export function printInitNextSteps(options, outDir) {
     if (!options.isNative) {
         const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
         console.log();
+        console.log(chalk.bold.white("To simulate without hardware:"));
+        console.log(`  ${chalk.cyan("npm run simulate")}`);
+        console.log();
         console.log(chalk.bold.white("To upload to your board:"));
         console.log(`  ${chalk.cyan("npm run upload")}`);
         console.log();
-        console.log(chalk.dim(`Edit ${chalk.white("package.json")} to change the serial port from ${chalk.white(portHint)} to your port.`));
+        console.log(chalk.bold.white("To run hardware tests:"));
+        console.log(`  ${chalk.cyan("npm run test:hw")}`);
+        console.log();
+        console.log(chalk.dim(`Edit ${chalk.white("cuttlefish.config.ts")} to change the serial port from ${chalk.white(portHint)} to your port.`));
     }
 }

package/dist/create/init-templates.d.ts

@@ -19,6 +19,8 @@ export declare function generateProjectTsconfig(options: InitProjectOptions): st
 export declare function generateProjectConfig(options: InitProjectOptions): string;
 export declare function generateProjectEnvDts(options: InitProjectOptions): string;
 export declare function generateStarterSketch(options: InitProjectOptions): string;
+export declare function generateStarterTest(_options: InitProjectOptions): string;
+export declare function generateStarterSim(options: InitProjectOptions): string;
 export declare function generateBoardForwardingFile(boardPackage: string): string;
 export declare function generateGitignore(_options: InitProjectOptions): string;
 export declare function generateEslintConfig(_options: InitProjectOptions): string;

package/dist/create/init-templates.js

@@ -2,11 +2,11 @@ import { LINT_RULES } from '../ir/feature-registry.js';
 export function generateProjectPackageJson(options) {
     const { projectName, frameworkPackage, boardPackage } = options;
     const deps = {
-        "@typecad/cuttlefish": "^0.1.0-alpha.1",
-        [frameworkPackage]: "^0.1.0-alpha.1",
+        "@typecad/cuttlefish": "^1.0.0-alpha.3",
+        [frameworkPackage]: "^1.0.0-alpha.3",
     };
     if (boardPackage) {
-        deps[boardPackage] = "^0.1.0-alpha.1";
+        deps[boardPackage] = "^1.0.0-alpha.3";
     }
     const depsJson = Object.entries(deps)
         .map(([k, v]) => `    "${k}": "${v}"`)
@@ -15,12 +15,27 @@ export function generateProjectPackageJson(options) {
     // eslint-transpiler-rules plugin (which is plain JS, no dep). Without these
     // devDependencies `npm run lint` fails to resolve the parser/plugin in a
     // freshly created project. Versions mirror the repo demo's package.json.
-    const devDepsJson = [
+    const baseDevDeps = [
         '    "eslint": "^10.4.1"',
         '    "@typescript-eslint/parser": "^8.61.0"',
         '    "@typescript-eslint/eslint-plugin": "^8.61.0"',
-    ].join(',\n');
+    ];
+    // Developer-utility scripts shared by every target (native + embedded).
+    // None require hardware or extra dependencies:
+    //   dev        — auto-retranspile on save (transpile-only; append --compile
+    //                to also compile on each change). The fast "does it
+    //                typecheck" feedback loop.
+    //   gen-decls  — generate TypeScript .d.ts from C++ headers. File-argument:
+    //                `npm run gen-decls -- lib/foo.h` or `-- --all lib/`.
+    //   gen-libdefs — generate library-definition stubs from a TS file's imports.
+    //                File-argument: `npm run gen-libdefs -- src/main.ts`.
+    const devScripts = [
+        '"dev": "cuttlefish build --watch"',
+        '"gen-decls": "cuttlefish gen-decls"',
+        '"gen-libdefs": "cuttlefish gen-libdefs"',
+    ];
     if (options.isNative) {
+        const devDepsJson = baseDevDeps.join(',\n');
         return `{
   "name": "${projectName}",
   "version": "1.0.0",
@@ -28,7 +43,8 @@ export function generateProjectPackageJson(options) {
   "scripts": {
     "build": "cuttlefish build",
     "compile": "cuttlefish build --compile",
-    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/"
+    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/",
+    ${devScripts.join(',\n    ')}
   },
   "dependencies": {
 ${depsJson}
@@ -39,6 +55,19 @@ ${devDepsJson}
 }
 `;
     }
+    // Embedded projects get two host-side testing tiers:
+    //  - @typecad/expect: hardware tests run on the board via cuttlefish-test
+    //    (`npm run test:hw`), scoped to tests/**/*.test.ts.
+    //  - @typecad/simulator + vitest: simulate the board in Node (`npm run
+    //    simulate`), scoped to sim/**/*.test.ts so vitest never collides with the
+    //    @typecad/expect no-op stubs under tests/.
+    // Versions mirror the workspace's published releases / root devDeps.
+    const devDepsJson = [
+        ...baseDevDeps,
+        '    "@typecad/expect": "^1.0.0-alpha.3"',
+        '    "@typecad/simulator": "^1.0.0-alpha.3"',
+        '    "vitest": "^4.0.18"',
+    ].join(',\n');
     return `{
   "name": "${projectName}",
   "version": "1.0.0",
@@ -48,7 +77,10 @@ ${devDepsJson}
     "compile": "cuttlefish build --compile",
     "upload": "cuttlefish build --compile --upload",
     "monitor": "cuttlefish build --compile --upload --monitor",
-    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/"
+    "test:hw": "npm exec -- cuttlefish-test",
+    "simulate": "vitest run sim/",
+    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/",
+    ${devScripts.join(',\n    ')}
   },
   "dependencies": {
 ${depsJson}
@@ -85,9 +117,10 @@ export function generateProjectTsconfig(options) {
     "noEmit": true,
     "resolveJsonModule": true,
     "allowArbitraryExtensions": true,
+    "allowImportingTsExtensions": true,
     "rootDirs": ["src", "types"]${paths}
   },
-  "include": ["src/**/*.ts", "types/**/*.ts", "cuttlefish.config.ts"${options.boardPackage ? ', ".cuttlefish/cuttlefish-env.d.ts"' : ''}]
+  "include": ["src/**/*.ts", "types/**/*.ts", "cuttlefish.config.ts"${options.boardPackage ? ', ".cuttlefish/cuttlefish-env.d.ts"' : ''}${options.isNative ? '' : ', "sim/**/*.ts"'}]
 }
 `;
 }
@@ -127,6 +160,11 @@ export default config;
         : '';
     const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
     const baudLine = options.baudRate ? `\n\n  // Console polyfill configuration\n  console: {\n    baudRate: ${options.baudRate},\n    // Serial port for upload/monitor. Override with --port on the CLI.\n    port: '${portHint}',\n  },` : '';
+    // Hardware test runner configuration — used by \`npm run test:hw\` (cuttlefish-test,
+    // provided by @typecad/expect). It transpiles each tests/**/*.test.ts file,
+    // flashes it to the board, and evaluates the assertions over serial.
+    const resolvedBaud = options.baudRate ?? 115200;
+    const testLine = `\n\n  // Hardware test runner (@typecad/expect / \`npm run test:hw\`)\n  test: {\n    // Serial port for the test board. Override with --port on the CLI or the\n    // CUTTLEFISH_PORT env var (e.g. CUTTLEFISH_PORT=/dev/ttyUSB0 npm run test:hw).\n    port: '${portHint}',\n    baudRate: ${resolvedBaud},\n    timeout: 30000,\n    include: ['tests/**/*.test.ts'],\n  },`;
     return `// ---------------------------------------------------------------------------
 // cuttlefish.config.ts — Project configuration
 //
@@ -155,7 +193,7 @@ const config: CuttlefishConfig = {
   // Toolchain configuration
   toolchain: {
     type: '${resolvedToolchain}',
-  },${baudLine}
+  },${baudLine}${testLine}
 };
 
 export default config;
@@ -286,6 +324,148 @@ while (true) {
 }
 `;
 }
+export function generateStarterTest(_options) {
+    return `// ---------------------------------------------------------------------------
+// Hardware test — Basics
+//
+// Runs on the board via \`npm run test:hw\` (cuttlefish-test). Each test file is
+// transpiled, flashed to the board, and its assertions are evaluated on the host
+// over serial. Change the serial port in cuttlefish.config.ts (the \`test.port\`
+// field) or override it with the CUTTLEFISH_PORT env var.
+//
+// API: describe(...).it(...).expect(value).<matcher>() chains. Import pin
+// objects from '@typecad/board' to assert on real hardware I/O. Every file ends
+// with done().
+// ---------------------------------------------------------------------------
+
+import { describe, done } from '@typecad/expect';
+
+describe("Basics")
+  .it("adds two numbers")
+  .expect(
+    (() => {
+      const a = 1;
+      let b = 2;
+      return a + b;
+    })
+  ).toBe(3)
+  .it("multiplies two numbers")
+  .expect(
+    (() => {
+      let a = 3;
+      let b = 4;
+      return a * b;
+    })
+  ).toBe(12)
+  .it("reads an array element")
+  .expect(
+    (() => {
+      const data = new Uint8Array([0xAA, 0x10, 0x20]);
+      return data[1];
+    })
+  ).toBe(0x10)
+  .it("clamps a value to a range")
+  .expect(
+    (() => {
+      const value = 2000;
+      return Math.max(0, Math.min(1023, value));
+    })
+  ).toBe(1023);
+
+done();
+`;
+}
+export function generateStarterSim(options) {
+    const boardType = options.targetId;
+    return `// ---------------------------------------------------------------------------
+// Hardware simulation — Button + LED
+//
+// Runs entirely on your computer with \`npm run simulate\` (vitest + the
+// @typecad/simulator package). No board, serial port, or arduino-cli required.
+// The simulator mirrors the pins/peripherals of your ${options.targetDisplayName}
+// (${boardType}); you inject fake inputs and assert on the outputs in Node.
+//
+// This is the fast tier — iterate on logic here, then confirm on real hardware
+// with \`npm run test:hw\` (which flashes tests/ to the board).
+// ---------------------------------------------------------------------------
+
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  createSimBoard,
+  type SimBoard,
+  type SimDigitalPin,
+} from "@typecad/simulator";
+
+// ===========================================================================
+// FIRMWARE LOGIC
+// ---------------------------------------------------------------------------
+// Factor your firmware into a function that takes the simulated pins as
+// arguments. In a real project this same logic runs on the board against real
+// pins — here it runs against the sim board so you can test it without hardware.
+// ===========================================================================
+
+/**
+ * Reads a button and reflects its state on an LED.
+ *
+ * To use your own logic: replace the body of this function with whatever your
+ * firmware does (read a sensor, drive a motor, print to serial, ...). As long
+ * as it only touches pins you pass in, the simulator can exercise it.
+ */
+function reflectButtonOnLed(button: SimDigitalPin, led: SimDigitalPin): void {
+  // The button pin is pulled HIGH (1) at rest and reads LOW (0) when pressed.
+  if (button.isLow()) {
+    led.high();
+  } else {
+    led.low();
+  }
+}
+
+// ===========================================================================
+// TEST BENCH
+// ---------------------------------------------------------------------------
+// \`createSimBoard\` builds an in-memory version of your board. The pin numbers
+// below match the physical pinout. Add the pins/peripherals your firmware uses:
+// board.digital(n), board.analog(n), board.pwm(n), board.serial(n),
+// board.i2c(n), board.spi(n), board.interrupt(n).
+// ===========================================================================
+
+function setupSim(): { board: SimBoard; button: SimDigitalPin; led: SimDigitalPin } {
+  // boardType mirrors the target chosen with \`cuttlefish create\`.
+  const board = createSimBoard({ boardType: "${boardType}" });
+
+  const button = board.digital(2).asInputPullUp();  // button on pin 2 (INPUT_PULLUP)
+  const led = board.digital(13).asOutput(false);    // LED on pin 13
+
+  return { board, button, led };
+}
+
+describe("Button + LED (simulator)", () => {
+  beforeEach(() => {
+    // A fresh board per test keeps state isolated. For a long-running sim you
+    // can call board.reset() between cycles instead.
+  });
+
+  it("keeps the LED off while the button is released", () => {
+    const { button, led } = setupSim();
+
+    // Button at rest: INPUT_PULLUP reads HIGH.
+    reflectButtonOnLed(button, led);
+
+    expect(led.getBitValue()).toBe(0);
+  });
+
+  it("turns the LED on while the button is pressed", () => {
+    const { button, led } = setupSim();
+
+    // Simulate a press: drive the button pin LOW.
+    button.injectValue(0);
+    reflectButtonOnLed(button, led);
+
+    expect(led.getBitValue()).toBe(1);
+  });
+});
+`;
+}
 export function generateBoardForwardingFile(boardPackage) {
     return `// ---------------------------------------------------------------------------
 // .cuttlefish/board.ts — Dynamically generated forwarding board package