@typecad/cuttlefish 1.0.0-alpha.3 → 1.0.0-alpha.7

package/dist/cli.js

@@ -5,7 +5,8 @@ import { parseCommandLine, printHelp } from "./utils/cli.js";
 import { scaffoldProject, printInitNextSteps, KNOWN_TARGETS } from "./create/index.js";
 import { runInitWizard } from "./create/index.js";
 import { generateLibraryDefinitions, transpileFile } from "./transpile.js";
-import { generateDecl, generateDeclsForDirectory } from "./libdef/cpp-to-decl.js";
+import { generateDecl, generateDeclsForDirectory, generateComponentDeclsForProject } from "./libdef/cpp-to-decl.js";
+import { discoverIdfRootForGenDecls } from "./libdef/idf-discovery.js";
 import { mapCppLocationToTs, readSourceMap, resolveMapPath } from "./mapping/source-map.js";
 import { compileSource, uploadFirmware, monitorDevice } from "./platform/toolchain.js";
 import { resolveStrategy } from "./platform/registry.js";
@@ -19,6 +20,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");
 }
@@ -47,8 +50,14 @@ async function handleCreate(options) {
                 ? '@typecad/framework-avr'
                 : framework === 'arduino'
                     ? '@typecad/framework-arduino'
-                    : `@typecad/framework-${framework}`;
+                    : framework === 'esp32'
+                        ? '@typecad/framework-esp32'
+                        : `@typecad/framework-${framework}`;
         const projectName = options.projectName || 'my-project';
+        const isEspIdf = frameworkPackage === '@typecad/framework-esp32' || framework === 'esp32';
+        const idfTarget = target.frameworkData?.target
+            ?? target.architecture
+            ?? 'esp32';
         const result = scaffoldProject({
             projectName,
             targetId: target.id,
@@ -58,10 +67,18 @@ async function handleCreate(options) {
             boardPackage: target.boardPackage,
             frameworkPackage,
             framework,
-            buildTarget: target.buildTarget,
+            buildTarget: isEspIdf ? idfTarget : target.buildTarget,
             mcu: target.mcu,
             baudRate: target.isNative ? undefined : (options.baud ?? 9600),
             includeSketch: !options.noSketch,
+            ...(isEspIdf
+                ? {
+                    toolchainType: 'idf',
+                    frameworkData: target.frameworkData ?? { target: idfTarget, buildTarget: idfTarget },
+                }
+                : target.frameworkData
+                    ? { frameworkData: target.frameworkData }
+                    : {}),
         }, options.outDir);
         console.log(`\n${chalk.green("✓")} Created project files:`);
         for (const file of result.createdFiles) {
@@ -107,6 +124,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 +227,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());
@@ -184,6 +265,47 @@ async function main() {
         // it intentionally has no inputFile (it scans scanDir instead), so the
         // generic "Missing input file path" check would otherwise block it.
         if (options.command === "gen-decls") {
+            // Check for --components flag (ESP-IDF components: managed + local).
+            // Runs before scanDir/single-file branches; components mode has no
+            // inputFile by design (it scans managed_components/ + components/).
+            const componentsDir = options.componentsDir;
+            if (componentsDir) {
+                ui.printHeader();
+                ui.printStep(`Generating component declarations for ${componentsDir}...`);
+                const config = loadCuttlefishConfig(componentsDir);
+                const frameworkConfig = (config?.frameworkConfig ?? {});
+                const componentsNode = frameworkConfig?.components ?? {};
+                const managedSpecs = Object.keys(componentsNode.managed ?? {});
+                // idf.py stores managed deps as <namespace>__<name> (slashes → __).
+                const managedNames = managedSpecs.map((spec) => spec.replace("/", "__"));
+                const localPaths = (componentsNode.local ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(componentsDir, p));
+                const builtinNames = componentsNode.builtin ?? [];
+                // Built-in components resolve against an ESP-IDF install. The CLI
+                // uses minimal discovery (env var + well-known paths). If no install
+                // is found, builtins are skipped with a notice — the framework-esp32
+                // compile path performs richer discovery and is the primary entry
+                // point for builtin gen-decls.
+                const idfRoot = discoverIdfRootForGenDecls();
+                if (builtinNames.length > 0 && !idfRoot) {
+                    ui.printInfo('components.builtin declared but no ESP-IDF install was found; skipping builtin headers. ' +
+                        'Run via `cuttlefish build --compile` (which performs full IDF discovery) or set $IDF_PATH.');
+                }
+                const created = generateComponentDeclsForProject(componentsDir, {
+                    managed: managedNames,
+                    local: localPaths,
+                    builtin: idfRoot ? builtinNames : [],
+                    idfRoot,
+                });
+                if (created.length === 0) {
+                    ui.printInfo("No component declaration files created.");
+                }
+                else {
+                    ui.printSuccess(`Created ${created.length} declaration file(s):`);
+                    for (const f of created)
+                        ui.printFileCreated(f);
+                }
+                return;
+            }
             // Check for --all flag (scan directory)
             const scanDir = options.scanDir;
             if (scanDir) {
@@ -255,6 +377,47 @@ async function main() {
         // ── Load cuttlefish.config.ts (config wins over CLI flags) ──────────
         const inputDir = path.dirname(path.resolve(options.inputFile));
         const config = loadCuttlefishConfig(inputDir);
+        // ── Pre-transpile: generate component .d.ts stubs ───────────────────
+        // The transpile type-check needs the .d.ts imports in main.ts to resolve.
+        // For ESP-IDF builtin/managed/local components, those .d.ts files are
+        // generated by gen-decls — so we must run it BEFORE type-checking, not
+        // only as part of --compile. The cache is written under the transpile
+        // output dir (the same path --compile uses), so user imports resolve
+        // identically in both flows.
+        if (config?.frameworkConfig) {
+            const fc = config.frameworkConfig;
+            const componentsNode = fc?.components ?? {};
+            const managedSpecs = Object.keys(componentsNode.managed ?? {});
+            const localPaths = (componentsNode.local ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(inputDir, p));
+            const builtinNames = componentsNode.builtin ?? [];
+            if (managedSpecs.length > 0 || localPaths.length > 0 || builtinNames.length > 0) {
+                // Resolve the transpile output dir — the cache lives under it so the
+                // framework's compile path and this pre-transpile pass agree on location.
+                // output.outDir in config is relative to the project root (inputDir);
+                // if absent, the transpile output goes alongside the entry file.
+                const outBase = config.outputOutDir
+                    ? path.resolve(inputDir, config.outputOutDir)
+                    : inputDir;
+                // For builtins we need IDF_PATH. Use cuttlefish's minimal discovery
+                // (env var + well-known paths) — full discovery is done by
+                // framework-esp32 at --compile time. If no install is found,
+                // builtins are skipped; --compile will regenerate them.
+                const idfRoot = discoverIdfRootForGenDecls();
+                try {
+                    generateComponentDeclsForProject(outBase, {
+                        managed: managedSpecs.map((s) => s.replace('/', '__')),
+                        local: localPaths,
+                        builtin: idfRoot ? builtinNames : [],
+                        idfRoot,
+                    });
+                }
+                catch {
+                    // Non-fatal: if gen-decls fails (e.g. component not yet fetched),
+                    // the type-checker will surface the missing-import errors with
+                    // clearer context than crashing here.
+                }
+            }
+        }
         // Load the UI engine (if @typecad/ui is installed) before any UI work.
         await loadUIEngine();
         let effectivePlatformContext = options.platformContext;
@@ -277,9 +440,17 @@ async function main() {
             }
             let configBuildTarget = config.buildTarget;
             if (configBuildTarget) {
+                // Reconstruct frameworkData from buildTarget, preserving other fields
+                // (psram, components, etc.) from the resolved frameworkConfig so the
+                // transpile-time diagnostics (e.g. scroll-canvas-memory PSRAM budget)
+                // and the toolchain both see the full frameworkData, not just buildTarget.
+                const fcPsram = config.frameworkConfig?.psram;
                 effectivePlatformContext = {
                     architecture: configBuildTarget.split(":")?.[1]?.toLowerCase(),
-                    frameworkData: { buildTarget: configBuildTarget },
+                    frameworkData: {
+                        buildTarget: configBuildTarget,
+                        ...(fcPsram ? { psram: fcPsram } : {}),
+                    },
                 };
             }
             if (config.outputOutDir && !options.outDir) {

package/dist/config-loader.js

@@ -9,6 +9,12 @@
 import path from "node:path";
 import fs from "node:fs";
 import ts from "typescript";
+/** True for the framework-esp32 package or any path that resolves to it.
+ *  Used to decide whether to route frameworkData → frameworkConfig so the
+ *  ESP-IDF toolchain can read components, target, etc. */
+function isEspIdfFramework(framework) {
+    return framework === "@typecad/framework-esp32" || framework.endsWith("framework-esp32");
+}
 import { safeValidateConfig } from "./config-schema.js";
 /** The filename we search for when walking up directories. */
 const CONFIG_FILENAME = "cuttlefish.config.ts";
@@ -323,8 +329,21 @@ export function parseConfigFile(configPath) {
     if (outputDefines)
         resolved.outputDefines = outputDefines;
     const nativeSection = extractFrameworkSection(configObject, "native");
-    if (nativeSection)
+    if (nativeSection) {
         resolved.frameworkConfig = nativeSection;
+    }
+    else if (resolved.framework && isEspIdfFramework(resolved.framework)) {
+        // ESP-IDF: route frameworkData through frameworkConfig so the toolchain
+        // can read components, target, and other framework-specific fields.
+        // extractFrameworkSection walks the AST and preserves nested shapes
+        // (components.managed, components.local, etc.).
+        const frameworkData = configObject
+            ? extractFrameworkSection(configObject, "frameworkData")
+            : undefined;
+        if (frameworkData) {
+            resolved.frameworkConfig = frameworkData;
+        }
+    }
     // Parse display profile config (nested object with profile name, wiring, touch)
     const displaySection = extractFrameworkSection(configObject, "display");
     if (displaySection)

package/dist/config-schema.d.ts

@@ -41,16 +41,16 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         buildTarget: z.ZodOptional<z.ZodString>;
         board: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;
     }, {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;
@@ -83,6 +83,12 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     frameworkData?: Record<string, unknown> | undefined;
     target?: string | undefined;
+    board?: string | undefined;
+    exclude?: string[] | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
     framework?: string | undefined;
     native?: Record<string, unknown> | undefined;
     output?: {
@@ -92,20 +98,14 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
     mcu?: string | undefined;
     include?: string[] | undefined;
     entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
     contract?: string | undefined;
-    exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;
@@ -117,6 +117,12 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     frameworkData?: Record<string, unknown> | undefined;
     target?: string | undefined;
+    board?: string | undefined;
+    exclude?: string[] | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
     framework?: string | undefined;
     native?: Record<string, unknown> | undefined;
     output?: {
@@ -126,20 +132,14 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
     mcu?: string | undefined;
     include?: string[] | undefined;
     entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
     contract?: string | undefined;
-    exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;
@@ -151,6 +151,12 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     frameworkData?: Record<string, unknown> | undefined;
     target?: string | undefined;
+    board?: string | undefined;
+    exclude?: string[] | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
     framework?: string | undefined;
     native?: Record<string, unknown> | undefined;
     output?: {
@@ -160,20 +166,14 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
     mcu?: string | undefined;
     include?: string[] | undefined;
     entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
     contract?: string | undefined;
-    exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;
@@ -185,6 +185,12 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     frameworkData?: Record<string, unknown> | undefined;
     target?: string | undefined;
+    board?: string | undefined;
+    exclude?: string[] | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
     framework?: string | undefined;
     native?: Record<string, unknown> | undefined;
     output?: {
@@ -194,20 +200,14 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
     mcu?: string | undefined;
     include?: string[] | undefined;
     entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
     contract?: string | undefined;
-    exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;

package/dist/create/board-spec.d.ts

@@ -40,6 +40,7 @@ export declare const BoardSpecSchema: z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         gpio: number;
         capabilities: "FULL_GPIO" | "FULL_GPIO_ANALOG" | "FULL_GPIO_TOUCH" | "FULL_GPIO_ANALOG_TOUCH" | "FULL_GPIO_DAC" | "INPUT_ONLY";
+        notes?: string | undefined;
         functions?: {
             type: "i2c" | "spi" | "uart" | "adc" | "dac" | "pwm" | "touch" | "usb";
             instance: number;
@@ -48,11 +49,11 @@ export declare const BoardSpecSchema: z.ZodObject<{
         alt?: string[] | undefined;
         warnings?: string[] | undefined;
         unsafe?: boolean | undefined;
-        notes?: string | undefined;
         onboardLed?: boolean | undefined;
     }, {
         gpio: number;
         capabilities: "FULL_GPIO" | "FULL_GPIO_ANALOG" | "FULL_GPIO_TOUCH" | "FULL_GPIO_ANALOG_TOUCH" | "FULL_GPIO_DAC" | "INPUT_ONLY";
+        notes?: string | undefined;
         functions?: {
             type: "i2c" | "spi" | "uart" | "adc" | "dac" | "pwm" | "touch" | "usb";
             instance: number;
@@ -61,7 +62,6 @@ export declare const BoardSpecSchema: z.ZodObject<{
         alt?: string[] | undefined;
         warnings?: string[] | undefined;
         unsafe?: boolean | undefined;
-        notes?: string | undefined;
         onboardLed?: boolean | undefined;
     }>, "many">;
     unsafe: z.ZodArray<z.ZodString, "many">;
@@ -436,6 +436,7 @@ export declare const BoardSpecSchema: z.ZodObject<{
     pins: {
         gpio: number;
         capabilities: "FULL_GPIO" | "FULL_GPIO_ANALOG" | "FULL_GPIO_TOUCH" | "FULL_GPIO_ANALOG_TOUCH" | "FULL_GPIO_DAC" | "INPUT_ONLY";
+        notes?: string | undefined;
         functions?: {
             type: "i2c" | "spi" | "uart" | "adc" | "dac" | "pwm" | "touch" | "usb";
             instance: number;
@@ -444,7 +445,6 @@ export declare const BoardSpecSchema: z.ZodObject<{
         alt?: string[] | undefined;
         warnings?: string[] | undefined;
         unsafe?: boolean | undefined;
-        notes?: string | undefined;
         onboardLed?: boolean | undefined;
     }[];
     analog: string[];
@@ -568,6 +568,7 @@ export declare const BoardSpecSchema: z.ZodObject<{
     pins: {
         gpio: number;
         capabilities: "FULL_GPIO" | "FULL_GPIO_ANALOG" | "FULL_GPIO_TOUCH" | "FULL_GPIO_ANALOG_TOUCH" | "FULL_GPIO_DAC" | "INPUT_ONLY";
+        notes?: string | undefined;
         functions?: {
             type: "i2c" | "spi" | "uart" | "adc" | "dac" | "pwm" | "touch" | "usb";
             instance: number;
@@ -576,7 +577,6 @@ export declare const BoardSpecSchema: z.ZodObject<{
         alt?: string[] | undefined;
         warnings?: string[] | undefined;
         unsafe?: boolean | undefined;
-        notes?: string | undefined;
         onboardLed?: boolean | undefined;
     }[];
     analog: string[];

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.d.ts

@@ -10,6 +10,9 @@ export interface KnownTarget {
     framework: string;
     buildTarget?: string;
     mcu?: string;
+    /** Framework-specific config (becomes frameworkData in cuttlefish.config.ts).
+     *  Used by framework-esp32 to carry `target: 'esp32'|'esp32s3'|'esp32c3'|'esp32c6'`. */
+    frameworkData?: Record<string, unknown>;
 }
 export declare function registerKnownTarget(target: KnownTarget): void;
 export declare const KNOWN_TARGETS: ReadonlyArray<KnownTarget>;

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 = [
     {
@@ -33,6 +33,18 @@ const _knownTargets = [
         buildTarget: 'esp32:esp32:esp32',
         mcu: 'esp32',
     },
+    {
+        id: 'esp32-devkit-idf',
+        displayName: 'ESP32 DevKit (native ESP-IDF)',
+        isNative: false,
+        architecture: 'esp32',
+        boardPackage: '@typecad/board-esp32-devkit',
+        frameworkPackage: '@typecad/framework-esp32',
+        framework: 'esp32',
+        buildTarget: 'esp32:esp32:esp32',
+        mcu: 'esp32',
+        frameworkData: { target: 'esp32' },
+    },
     {
         id: 'esp32s3',
         displayName: 'ESP32-S3',
@@ -44,6 +56,18 @@ const _knownTargets = [
         buildTarget: 'esp32:esp32:esp32s3',
         mcu: 'esp32s3',
     },
+    {
+        id: 'esp32s3-idf',
+        displayName: 'ESP32-S3 (native ESP-IDF)',
+        isNative: false,
+        architecture: 'esp32s3',
+        boardPackage: '@typecad/board-esp32s3',
+        frameworkPackage: '@typecad/framework-esp32',
+        framework: 'esp32',
+        buildTarget: 'esp32:esp32:esp32s3',
+        mcu: 'esp32s3',
+        frameworkData: { target: 'esp32s3' },
+    },
     {
         id: 'esp32c3',
         displayName: 'ESP32-C3',
@@ -55,6 +79,18 @@ const _knownTargets = [
         buildTarget: 'esp32:esp32:esp32c3',
         mcu: 'esp32c3',
     },
+    {
+        id: 'esp32c3-idf',
+        displayName: 'ESP32-C3 (native ESP-IDF)',
+        isNative: false,
+        architecture: 'esp32c3',
+        boardPackage: '@typecad/board-esp32c3',
+        frameworkPackage: '@typecad/framework-esp32',
+        framework: 'esp32',
+        buildTarget: 'esp32:esp32:esp32c3',
+        mcu: 'esp32c3',
+        frameworkData: { target: 'esp32c3' },
+    },
     {
         id: 'esp32c6',
         displayName: 'ESP32-C6',
@@ -66,6 +102,18 @@ const _knownTargets = [
         buildTarget: 'esp32:esp32:esp32c6',
         mcu: 'esp32c6',
     },
+    {
+        id: 'esp32c6-idf',
+        displayName: 'ESP32-C6 (native ESP-IDF)',
+        isNative: false,
+        architecture: 'esp32c6',
+        boardPackage: '@typecad/board-esp32c6',
+        frameworkPackage: '@typecad/framework-esp32',
+        framework: 'esp32',
+        buildTarget: 'esp32:esp32:esp32c6',
+        mcu: 'esp32c6',
+        frameworkData: { target: 'esp32c6' },
+    },
     {
         id: 'rp2040',
         displayName: 'RP2040 (Pico)',
@@ -150,6 +198,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) {
@@ -164,9 +230,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.`));
     }
 }