@typecad/cuttlefish 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/transpile.js

@@ -20,19 +20,22 @@ const CUTTLEFISH_VERSION = (() => {
     }
 })();
 import { buildProgramIR } from "./ir/build-ir.js";
+import { resetTranspileResolvedHalOps } from "./ir/build-ir-state.js";
 import { classDeclarationToIR } from "./ir/declaration-builders.js";
 import { clickHandlers } from "./ir/transformers/ui-call-resolver.js";
 import { requireUIHook, hasUIHook } from "./ui-hook.js";
 import { loadUIEngine } from "./ui/ui-bridge.js";
 import { hasSafetyHook, requireSafetyHook } from "./safety-hook.js";
 import { loadSafetyEngine } from "./safety/safety-bridge.js";
+import { isSafetyImportSpecifier } from "./safety/specifiers.js";
 import { setDisplayProfile, resetDisplayProfile, getDisplayProfile } from "./stores/display-profile-store.js";
 import { setThemeCss, resetThemeCss, setThemeClass } from "./stores/theme-store.js";
 import { emitCpp, registerAllEnumNames } from "./emit/cpp-emitter.js";
-import { readText, writeText, resetWrittenFiles, wasWrittenThisRun } from "./utils/fs.js";
+import { writeText, resetWrittenFiles, wasWrittenThisRun } from "./utils/fs.js";
 import { debug as logDebug, info } from "./utils/logger.js";
 import { printDebugStrategy } from "./utils/ui.js";
-import { loadLibraryDefinitions, generateLibdefStubs } from "./libdef/registry.js";
+import { loadLibraryDefinitions } from "./libdef/registry.js";
+import { resetCuttlefishLibraries, validateCuttlefishLibraries, cuttlefishLibraryLibdefs, libraryDefinitionKey, writeCuttlefishLibraryArtifacts, } from "./library-packages.js";
 import { buildCallGraph } from "./ir/call-graph.js";
 import { clearCaches, } from "./cache.js";
 import { detectEntryPoints, detectExportedEntryPoints } from "./ir/entry-points.js";
@@ -69,7 +72,7 @@ function loadExpectPreprocessor() {
 function cleanOutput(_entryDir, outDir) {
     // The out dir is NOT wiped: writeText skips writing when content is
     // identical, so keeping it lets downstream build tools (idf.py/ninja,
-    // arduino-cli) reuse their build caches. Stale generated SOURCES are handled
+    // west) reuse their build caches. Stale generated SOURCES are handled
     // precisely instead — after emission, sweepStaleGeneratedSources() removes
     // compiled-source files in the out dir that this run did not write (e.g. a
     // main.cpp left behind by the old emit naming next to the current src.cpp;
@@ -79,7 +82,7 @@ function cleanOutput(_entryDir, outDir) {
     void outDir;
     resetWrittenFiles();
 }
-const GENERATED_SOURCE_EXTENSIONS = [".cpp", ".cc", ".c", ".h", ".ino"];
+const GENERATED_SOURCE_EXTENSIONS = [".cpp", ".cc", ".c", ".h"];
 /**
  * Remove stale generated source files from the out dir: compiled-source files
  * that THIS transpile run did not write. Sweeps only the source layouts the
@@ -121,13 +124,13 @@ function sweepStaleGeneratedSources(outDir) {
  * Returns list of generated files.
  */
 /**
- * True iff the program imports `@typecad/safety` anywhere. The safety
- * transform pass uses this as its fast no-op guard — when no file imports
- * safety, the pass returns the program unchanged.
+ * True iff the program imports the safety authoring surface anywhere. The
+ * safety transform pass uses this as its fast no-op guard — when no file
+ * imports safety, the pass returns the program unchanged.
  */
 function entryImportsSafety(program) {
     for (const imp of program.imports) {
-        if (imp.moduleSpecifier === "@typecad/safety")
+        if (isSafetyImportSpecifier(imp.moduleSpecifier))
             return true;
     }
     return false;
@@ -258,7 +261,7 @@ function throwIfFatalDiagnostics(entries) {
  * doesn't export a FrameworkStrategy, allowing emitCpp to fall back to
  * target-based resolution via the platform registry.
  */
-function loadPlatformStrategy(frameworkPackage, _boardPackage, fromDir, debug) {
+function loadPlatformStrategy(frameworkPackage, _boardTarget, fromDir, debug) {
     if (!frameworkPackage) {
         if (debug) {
             logDebug(`No framework package configured, will use target-based resolution`, true);
@@ -311,12 +314,12 @@ export async function transpileFile(options) {
     const entryFile = path.resolve(options.inputFile);
     const entryDir = path.dirname(entryFile);
     const sourceDir = entryDir;
-    const sketchBaseName = path.basename(entryFile).replace(/\.[^.]+$/, "");
+    const entryBaseName = path.basename(entryFile).replace(/\.[^.]+$/, "");
     const outBaseDir = options.outDir ?? sourceDir;
     profiler.endTimer("setup:caches");
     profiler.startTimer("setup:load-strategy");
     // Load platform strategy from framework or board package, or use target-based resolution
-    const boardStrategy = loadPlatformStrategy(options.frameworkPackage, options.boardPackage, entryDir, options.debug);
+    const boardStrategy = loadPlatformStrategy(options.frameworkPackage, options.boardTarget, entryDir, options.debug);
     profiler.endTimer("setup:load-strategy");
     // Use the framework-loaded strategy for output path computation if available,
     // otherwise fall back to target-based resolution.  This ensures a single
@@ -330,7 +333,7 @@ export async function transpileFile(options) {
     if (configDisplay) {
         const { resolveDisplayProfile } = await import("./api/shared/display-profile.js");
         // Build the named-profile registry. Prefer the strategy's hook (per-framework
-        // canonical profiles — Arduino returns its BUILT_IN_PROFILES, Zephyr returns
+        // canonical profiles — the framework returns its BUILT_IN_PROFILES
         // its DT-binding profiles). Fall back to the legacy dynamic import of the
         // framework's displays/ili9341-spi module when the strategy provides none.
         // The registry maps a config `profile` name (e.g. "st7796-zephyr") to its
@@ -360,7 +363,7 @@ export async function transpileFile(options) {
             setThemeClass(configDisplay.themeClass);
         }
     }
-    const outDir = path.join(outBaseDir, strategy.outputSubdirectory(sketchBaseName));
+    const outDir = path.join(outBaseDir, strategy.outputSubdirectory(entryBaseName));
     // Start fresh: clean the output directory. (Incremental builds are disabled —
     // see incremental-cache.ts — so we always transpile the full graph.)
     cleanOutput(entryDir, outDir);
@@ -377,15 +380,21 @@ export async function transpileFile(options) {
             return {};
         }
     })();
-    const graphResult = await collectTranspileGraph(entryFile, options.boardPackage, imageDecodeMax);
+    resetCuttlefishLibraries();
+    const graphResult = await collectTranspileGraph(entryFile, options.boardTarget, imageDecodeMax);
     profiler.endTimer("graph:collect");
+    // Cuttlefish library packages registered during the graph walk — validate
+    // them against the loaded framework (and build target, when known) before
+    // any codegen. A framework/target mismatch is a hard error here, far
+    // clearer than the native compiler's take on a missing header or node.
+    validateCuttlefishLibraries(strategy.id, options.platformContext?.frameworkData?.buildTarget);
     const transpileFiles = graphResult.files;
     // ── Type-check all files before transpiling ────────────────────────────────
     // Skip type-checking if explicitly disabled
     let typeCheckProgram;
     if (options.skipTypeCheck !== true && transpileFiles.length > 0) {
         profiler.startTimer("typecheck:full");
-        let typeCheckResult = typeCheckFiles(transpileFiles, options.boardPackage, entryFile);
+        let typeCheckResult = typeCheckFiles(transpileFiles, options.boardTarget, entryFile);
         // If type-checking failed, try to auto-generate missing .d.ts files from C++ sources
         if (!typeCheckResult.success) {
             profiler.startTimer("typecheck:autogen-decls");
@@ -394,7 +403,7 @@ export async function transpileFile(options) {
             // If we generated any declaration files, retry type-checking
             if (generatedDecls.length > 0) {
                 profiler.startTimer("typecheck:retry");
-                typeCheckResult = typeCheckFiles(transpileFiles, options.boardPackage, entryFile);
+                typeCheckResult = typeCheckFiles(transpileFiles, options.boardTarget, entryFile);
                 profiler.endTimer("typecheck:retry");
             }
         }
@@ -451,6 +460,15 @@ export async function transpileFile(options) {
     }
     const npmPackages = graphResult.npmPackages;
     const definitions = loadLibraryDefinitions(sourceDir);
+    // Cuttlefish library packages: the import resolves to the library's shim
+    // include (e.g. '"__tc_rgbled.h"') instead of a transpiled module header.
+    // Project-local .libdef.json files keep precedence.
+    for (const libdef of cuttlefishLibraryLibdefs()) {
+        const key = libraryDefinitionKey(libdef.module);
+        if (!definitions.has(key)) {
+            definitions.set(key, libdef);
+        }
+    }
     let entryOutputs;
     const diagnostics = [];
     const allRemovedSymbols = [];
@@ -576,7 +594,9 @@ export async function transpileFile(options) {
         // Printf instrumentation runs only in printf debug mode. In gdb mode
         // (e.g. ESP32-S3), --debug emits #line markers at the emit stage and
         // uses VS Code native breakpoints; the printf preprocessor is skipped
-        // so the source reaches IR/emit unmodified.
+        // so the source reaches IR/emit unmodified. The preprocessor instruments
+        // with the SAME strategy that emits below — its debug dialect must match
+        // the runtime the generated code links against.
         const buildTarget = options.platformContext?.frameworkData?.buildTarget;
         const debugMode = strategy.debugMode?.(buildTarget) ?? 'printf';
         if (options.debug && breakpoints && debugMode === 'printf') {
@@ -584,11 +604,12 @@ export async function transpileFile(options) {
                 fileName: filePath,
                 breakpoints,
                 source: sourceText,
+                strategy,
             });
             sourceText = instrumented;
         }
         profiler.startTimer(`ir:build-ir:${fileBasename}`);
-        const programIR = buildProgramIR(filePath, sourceText, options.boardPackage, prebuiltClassMap);
+        const programIR = buildProgramIR(filePath, sourceText, options.boardTarget, prebuiltClassMap);
         profiler.endTimer(`ir:build-ir:${fileBasename}`);
         const npmPackage = npmPackages.get(filePath);
         profiler.endTimer(`ir:build:${fileBasename}`);
@@ -605,6 +626,11 @@ export async function transpileFile(options) {
     profiler.startTimer("ir:load-hal");
     loadHALModules(true);
     profiler.endTimer("ir:load-hal");
+    // Fresh run, fresh resolved-op set: the lowering seams record every HAL op
+    // they resolve (some never become IR nodes); analyzeProgram merges them into
+    // the peripheral usage flags at emit. Without this reset, a watch-mode
+    // rebuild in the same process would carry the previous program's ops over.
+    resetTranspileResolvedHalOps();
     const rawIRArray = await Promise.all(filesToProcess.map(buildRawIR));
     profiler.captureMemorySnapshot("ir:post-build");
     profiler.endTimer("ir:build-all");
@@ -645,7 +671,7 @@ export async function transpileFile(options) {
     for (const { filePath, programIR } of rawIRArray) {
         for (const imp of programIR.imports) {
             // Resolve the import to find which file it comes from
-            const resolved = resolveImport(filePath, imp.moduleSpecifier, options.boardPackage);
+            const resolved = resolveImport(filePath, imp.moduleSpecifier, options.boardTarget);
             if (!resolved)
                 continue;
             const targetFile = resolved.sourcePath;
@@ -872,10 +898,11 @@ export async function transpileFile(options) {
     profiler.startTimer("post:native-modules");
     const nativeModuleOutputs = [];
     for (const [moduleSpecifier, nativeModule] of graphResult.nativeModules) {
-        // Skip copying — Arduino's library system provides both .h and .cpp.
-        // Copying either causes conflicts: the .cpp merges into the .ino (duplicate
-        // definitions), and the .h shadows the library's own header (link failures).
-        // The gen-decls .d.ts files are sufficient for TypeScript type-checking.
+        // Skip copying — framework libraries provide both .h and .cpp.
+        // Copying either causes conflicts: the .cpp merges into the entry source
+        // (duplicate definitions), and the .h shadows the library's own header
+        // (link failures). The gen-decls .d.ts files are sufficient for TS
+        // type-checking.
         info(`Native module (library-managed): ${moduleSpecifier}`);
     }
     profiler.endTimer("post:native-modules");
@@ -913,7 +940,7 @@ export async function transpileFile(options) {
                 asyncTaskNames: entryOutputs.asyncTaskNames ?? [],
                 usesTimers: entryOutputs.usesTimers ?? false,
                 target: options.target,
-                boardPackage: options.boardPackage,
+                boardTarget: options.boardTarget,
                 frameworkPackage: options.frameworkPackage,
                 outDir,
                 outputFile: entryOutputs.sourcePath,
@@ -935,14 +962,48 @@ export async function transpileFile(options) {
             });
         }
     }
+    // ── Persist the resolved board constants next to the emitted source ─────
+    // Framework toolchains re-read this at compile time to rebuild their chip
+    // descriptors (framework-zephyr's resolveChipFromBoard). Board packages
+    // carry chip data — controller splits, ADC channel maps, PWM specs — that
+    // lives only in the board package, so without this file the toolchain's
+    // registry fallback silently resolves board-derived targets (rpi_pico,
+    // esp32c3/c6, blackpill) to the XIAO default descriptor.
+    try {
+        // Read from the built program IRs — the IR build context (and its
+        // current-board-constants slot) is already closed at this point. Any
+        // file's IR may carry the constants (the board import is traversed while
+        // building whichever file imports it first), so scan for a populated one.
+        let boardConstants;
+        for (const pb of preBuilt.values()) {
+            const bc = pb.programIR.boardConstants;
+            if (bc && bc.size > 0) {
+                boardConstants = bc;
+                break;
+            }
+        }
+        if (boardConstants && boardConstants.size > 0) {
+            fs.writeFileSync(path.join(outDir, "board-constants.json"), JSON.stringify(Object.fromEntries(boardConstants), null, 2));
+        }
+    }
+    catch {
+        // Best-effort persistence; the toolchain falls back to its registry.
+    }
+    // ── Cuttlefish library packages: shims + libraries.json sidecar ─────────
+    // Shims are written next to the emitted sources (the framework scaffold's
+    // CMake/program regen compiles them); the sidecar records the used
+    // libraries' build contributions (Kconfig lines, overlay fragments) for
+    // the framework toolchain — the board-constants.json convention.
+    try {
+        const emittedSrcDir = entryOutputs ? path.dirname(entryOutputs.sourcePath) : outDir;
+        writeCuttlefishLibraryArtifacts(outDir, emittedSrcDir);
+    }
+    catch {
+        // Best-effort; a missing shim surfaces at native compile time.
+    }
     return {
         ...entryOutputs,
         diagnostics,
         diagnosticsReportPath,
     };
 }
-export function generateLibraryDefinitions(options) {
-    const sourceText = readText(options.inputFile);
-    const programIR = buildProgramIR(options.inputFile, sourceText);
-    return generateLibdefStubs(options.inputFile, programIR.imports, options.outDir);
-}

package/dist/types.d.ts

@@ -55,15 +55,15 @@ export interface TranspileOptions {
     /** Tree-shaking options for dead code elimination */
     treeShaking?: TreeShakingOptions;
     /**
-     * Board package specifier resolved from `cuttlefish.config.ts`.
-     * When present, `@typecad/board` imports are rewritten to this package
-     * (e.g. `'@typecad/board-arduino-uno'`).
+     * Zephyr board target resolved from `cuttlefish.config.ts` (e.g.
+     * `'esp32s3_devkitc/esp32s3/procpu'`). When a generated board module is
+     * absent, `@typecad/board` imports resolve through it.
      */
-    boardPackage?: string;
+    boardTarget?: string;
     /**
      * Framework package for code generation strategy.
-     * Can be any framework package path, e.g. '@typecad/framework-arduino',
-     * '@typecad/framework-avr', or a custom local path.
+     * Can be any framework package path, e.g. '@typecad/framework-zephyr',
+     * '@typecad/framework-native', or a custom local path.
      * When not specified, the GenericStrategy (standard C++) is used.
      */
     frameworkPackage?: string;
@@ -121,7 +121,7 @@ export interface LibraryDefinition {
     variants?: LibraryDefinitionVariant[];
 }
 export interface CommandLineOptions {
-    command: "default" | "build" | "gen-libdefs" | "gen-decls" | "map-error" | "preview" | "doctor" | "licenses";
+    command: "default" | "build" | "gen-decls" | "preview" | "doctor" | "licenses";
     /** For `licenses`: treat unknown/missing licenses as failures (exit 1). */
     strict?: boolean;
     /** For `licenses`: scan all installed libraries (default: this project's only). */
@@ -141,26 +141,23 @@ export interface CommandLineOptions {
     monitor: boolean;
     /** Serial port for upload and monitor (e.g. COM4 or /dev/ttyACM0) */
     port?: string;
+    /** One-off probe-method override (a board probeMethods id) for --upload
+     *  and --debug. Wins over zephyr.probe in cuttlefish.config.ts; Zephyr-only. */
+    probe?: string;
     /** Baud rate for monitor. Undefined when --baud is absent so the consumer
-     *  can fall back to config.console.baudRate (the framework monitor default
-     *  applies only when neither is set). */
+     *  can fall through to the framework monitor default. */
     baud?: number;
     platformContext?: PlatformContext;
-    mapFile?: string;
-    cppFile?: string;
-    cppLine?: number;
-    cppColumn?: number;
-    message?: string;
     /** Tree-shaking options */
     treeShaking?: TreeShakingOptions;
     /**
      * Board package specifier resolved from `cuttlefish.config.ts`.
      * When present, `@typecad/board` imports are rewritten to this package.
      */
-    boardPackage?: string;
+    boardTarget?: string;
     /**
      * Framework package for code generation strategy.
-     * Can be '@typecad/framework-arduino', '@typecad/framework-avr', or a custom path.
+     * Can be '@typecad/framework-zephyr', '@typecad/framework-native', or a custom path.
      */
     frameworkPackage?: string;
     /** Enable debug mode - inject breakpoint instrumentation */
@@ -188,11 +185,6 @@ export interface CommandLineOptions {
     /** Project root (dir of cuttlefish.config.ts); passed to transpileFile for the ESLint gate. */
     projectRoot?: string;
 }
-export interface GenerateLibdefOptions {
-    inputFile: string;
-    outDir: string;
-}
-/** `cuttlefish add <preset>` — scaffold a copy-and-own asset into the project. */
 export interface GeneratedOutputs {
     headerPath?: string;
     sourcePath: string;
@@ -228,14 +220,41 @@ export interface CreateCommandOptions {
     target?: string;
     framework?: string;
     baud?: number;
-    noSketch?: boolean;
+    noStarter?: boolean;
     outDir?: string;
     /** Skip the automatic `npm install` in the scaffolded project. */
     noInstall?: boolean;
+    /** Probe method id (board probeMethods table) — skips the wizard question
+     * and writes zephyr.probe into the scaffolded config. Zephyr-only. */
+    probe?: string;
+    /** Serial port the board is attached to (COMx / /dev/tty*) — skips the
+     * wizard question and seeds test.port in the config. */
+    port?: string;
 }
-export interface BoardAddCommandOptions {
-    command: "board-add";
-    specPath: string;
-    force?: boolean;
+/** Parsed `cuttlefish board <subcommand>` options. */
+export interface BoardCommandOptions {
+    command: "board";
+    subcommand: "regen" | "sync";
+    /** sync: optional explicit Zephyr checkout path to walk. */
+    zephyrBase?: string;
+}
+/** Parsed `cuttlefish library <subcommand>` options. */
+export interface LibraryCommandOptions {
+    command: "library";
+    subcommand: "search" | "install" | "init" | "validate";
+    /** Non-flag tokens after the subcommand: search text, install names, init name, validate path. */
+    positionals: string[];
+    /** search: taxonomy category id. */
+    category?: string;
+    /** init: framework id from the framework catalog. */
+    framework?: string;
+    /** init: comma-separated board-target prefixes. */
+    targets?: string;
+    /** init: scaffold directory (default ./<library-id>). */
+    dir?: string;
+    /** init: skip prompts, take defaults. */
+    yes?: boolean;
+    /** Machine-readable output for search/validate. */
+    json?: boolean;
 }
 export {};

package/dist/ui-hook.d.ts

@@ -62,7 +62,7 @@ export interface TranspilerUIHook {
      * native display paths). Called separately from emitRuntimeHeader so the
      * class can be emitted BEFORE display adapter declarations that
      * instantiate CuttlefishGFX by value. Returns "" when active is false
-     * (Arduino path).
+     * (console path).
      */
     emitCuttlefishGfx(active: boolean): string;
     /**

package/dist/utils/cli.d.ts

@@ -1,3 +1,3 @@
-import { CommandLineOptions, CreateCommandOptions, BoardAddCommandOptions } from "../types.js";
+import { CommandLineOptions, CreateCommandOptions, LibraryCommandOptions, BoardCommandOptions } from "../types.js";
 export declare function printHelp(): void;
-export declare function parseCommandLine(argv: string[]): CommandLineOptions | CreateCommandOptions | BoardAddCommandOptions | "help";
+export declare function parseCommandLine(argv: string[]): CommandLineOptions | CreateCommandOptions | LibraryCommandOptions | BoardCommandOptions | "help";