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

package/dist/config-loader.d.ts

@@ -5,21 +5,24 @@
  */
 export interface ResolvedCuttlefishConfig {
     target?: string;
-    /** MCU package specifier (e.g. '@typecad/mcu-atmega328p'). */
-    mcu?: string;
-    /** Board package specifier (e.g. '@typecad/board-arduino-uno'). (Deprecated) */
+    /** Zephyr board target — the qualified `west build -b` argument (e.g.
+     *  'esp32s3_devkitc/esp32s3/procpu'). The project-local board module is
+     *  generated from the framework's board data pack on first build. */
     board?: string;
+    /** Zephyr SoC name for contract-based projects (custom PCBs, no board
+     *  target) — e.g. 'stm32f411xe'. Selects the curated soc descriptor. */
+    soc?: string;
     /** Path to a TypeCAD contract file (*.contract.json). */
     contract?: string;
-    /** Build target identifier (e.g. FQBN for Arduino CLI). */
+    /** Build target identifier (the framework's board id, e.g. 'blackpill_f411ce/stm32f411xe'). */
     buildTarget?: string;
-    /** Output framework (e.g. 'arduino'). */
+    /** Output framework (e.g. 'zephyr'). */
     outputFramework?: string;
     /** Output directory. */
     outputOutDir?: string;
     /**
      * Framework package for code generation strategy.
-     * Can be '@typecad/framework-arduino', '@typecad/framework-zephyr',
+     * Can be '@typecad/framework-zephyr', '@typecad/framework-native',
      * '@typecad/framework-native', or a custom path.
      */
     framework?: string;
@@ -29,11 +32,6 @@ export interface ResolvedCuttlefishConfig {
     entry?: string;
     /** Path to the config file that was loaded. */
     configPath: string;
-    /** Console polyfill configuration. */
-    console?: {
-        baudRate?: number;
-        port?: string;
-    };
     /** Extra compiler flags from `output.extraFlags`. */
     outputExtraFlags?: string[];
     /** Additional defines from `output.defines`. */
@@ -69,15 +67,12 @@ export type ConfigDropWarning = (message: string) => void;
  */
 export declare function parseConfigFile(configPath: string): ResolvedCuttlefishConfig | undefined;
 /**
- * Generates (or updates) a `cuttlefish-env.d.ts` file next to the config file.
- *
- * The file declares an ambient `@typecad/board` module that simply re-exports
- * everything from the concrete board package.  This lets the TypeScript
- * language server resolve `import { ... } from '@typecad/board'` in user files.
- *
- * The file is regenerated on every transpiler run so it stays in sync when
- * the board changes in `cuttlefish.config.ts`.
+ * Force-regenerate the project-local board module — the `cuttlefish board
+ * regen` path. Board-target configs only: contract projects write their
+ * board module through the contract reader, and native projects have none.
+ * Returns the .cuttlefish directory the module was written to.
  */
+export declare function regenBoardModule(config: ResolvedCuttlefishConfig): string;
 export declare function generateVirtualTypeDeclaration(config: ResolvedCuttlefishConfig, platformDeclarations?: string[]): void;
 /**
  * High-level entry point: find and load `cuttlefish.config.ts` starting from

package/dist/config-loader.js

@@ -9,13 +9,17 @@
 import path from "node:path";
 import fs from "node:fs";
 import ts from "typescript";
+import { createRequire } from "node:module";
+import { loadBoardCatalogOverlay, ensureFreshBoardCatalog, boardRecordFingerprint, factsFingerprint, findBoardInCatalog, } from "./board-catalog/index.js";
+import { fileURLToPath } from "node:url";
+import { readTestPinsFile, buildTestPinsModuleContent } from "./transpile/test-pins.js";
 import { safeValidateConfig } from "./config-schema.js";
 /** The filename we search for when walking up directories. */
 const CONFIG_FILENAME = "cuttlefish.config.ts";
 /** Top-level keys recognized by CuttlefishConfigSchema — used to warn about
  *  misspelled keys that the AST extraction would otherwise drop silently. */
 const KNOWN_TOP_LEVEL_KEYS = new Set([
-    "entry", "target", "mcu", "board", "contract", "framework", "psram",
+    "entry", "target", "board", "soc", "contract", "framework", "psram",
     "output", "frameworkData", "include", "exclude", "test", "toolchain",
     "console", "native", "zephyr", "display",
 ]);
@@ -390,19 +394,33 @@ export function parseConfigFile(configPath) {
     const target = flat.get("target");
     if (typeof target === "string")
         resolved.target = target;
-    const mcu = flat.get("mcu");
-    if (typeof mcu === "string")
-        resolved.mcu = mcu;
+    const soc = flat.get("soc");
+    if (typeof soc === "string")
+        resolved.soc = soc;
     const board = flat.get("board");
     if (typeof board === "string")
         resolved.board = board;
     const contract = flat.get("contract");
     if (typeof contract === "string")
         resolved.contract = contract;
-    // We do not extract fqbn here anymore, it should be in frameworkData
-    const buildTarget = flat.get("frameworkData.buildTarget");
-    if (typeof buildTarget === "string")
-        resolved.buildTarget = buildTarget;
+    // The build target (what `west build -b` receives) has a single source of
+    // truth: `board:` for board-target projects. `frameworkData.buildTarget`
+    // is honored only for board-less projects (bare silicon / contract, whose
+    // build target is a generated custom board). When both are present they
+    // must agree — a disagreement is the split-brain trap (board module for
+    // one board, firmware for another), so board wins with a warning.
+    const buildTargetFlat = flat.get("frameworkData.buildTarget");
+    if (typeof board === "string") {
+        if (typeof buildTargetFlat === "string" && buildTargetFlat !== board) {
+            warn(`config sets both board: '${board}' and frameworkData.buildTarget: '${buildTargetFlat}' — ` +
+                `they disagree. 'board' is the source of truth; building for '${board}'. ` +
+                `Remove the stale frameworkData.buildTarget entry.`);
+        }
+        resolved.buildTarget = board;
+    }
+    else if (typeof buildTargetFlat === "string") {
+        resolved.buildTarget = buildTargetFlat;
+    }
     const framework = flat.get("framework");
     if (typeof framework === "string")
         resolved.framework = framework;
@@ -424,18 +442,20 @@ export function parseConfigFile(configPath) {
         warn("'output.optimize' has no effect and is deprecated — remove it. " +
             "Control optimization via the framework (e.g. zephyr.kconfig CONFIG_SIZE_OPTIMIZATIONS / CONFIG_SPEED_OPTIMIZATIONS).");
     }
+    // The `console` section is removed: the console.* carry-over (console.log
+    // lowering to a platform print, plus this section routing/parameterizing it)
+    // is gone. Programs write to a serial console explicitly — USB0.writeLine
+    // or UART0.writeLine from the board module. Warn-and-drop so existing
+    // configs keep building while telling the user to delete the key.
+    for (const key of flat.keys()) {
+        if (key === "console" || key.startsWith("console.")) {
+            warn(`'${key}' is removed — the console.* carry-over is gone. ` +
+                "Write to a serial console explicitly (USB0.writeLine(...) / UART0.writeLine(...)) and delete the console section.");
+        }
+    }
     const outputOutDir = flat.get("output.outDir");
     if (typeof outputOutDir === "string")
         resolved.outputOutDir = outputOutDir;
-    // Parse console configuration
-    const consoleBaudRate = flat.get("console.baudRate");
-    const consolePort = flat.get("console.port");
-    if (typeof consoleBaudRate === "number" || typeof consolePort === "string") {
-        resolved.console = {
-            ...(typeof consoleBaudRate === "number" ? { baudRate: consoleBaudRate } : {}),
-            ...(typeof consolePort === "string" ? { port: consolePort } : {}),
-        };
-    }
     // Extract structured fields that the flat walker cannot handle.
     const outputExtraFlags = extractStringArray(configObject, ["output", "extraFlags"], warn);
     if (outputExtraFlags)
@@ -450,12 +470,18 @@ export function parseConfigFile(configPath) {
     // Parse zephyr-specific config section.
     const zephyrKconfig = extractStringRecord(configObject, ["zephyr", "kconfig"], warn);
     const zephyrCmakeArgs = extractStringArray(configObject, ["zephyr", "cmakeArgs"], warn);
+    const zephyrRunnerArgs = extractStringArray(configObject, ["zephyr", "runnerArgs"], warn);
     const zephyrRunner = flat.get("zephyr.runner");
-    if (zephyrKconfig || zephyrCmakeArgs || typeof zephyrRunner === "string") {
+    const zephyrProbe = flat.get("zephyr.probe");
+    const zephyrCustomBoard = flat.get("zephyr.customBoard");
+    if (zephyrKconfig || zephyrCmakeArgs || zephyrRunnerArgs || typeof zephyrRunner === "string" || typeof zephyrProbe === "string" || typeof zephyrCustomBoard === "boolean") {
         resolved.zephyrConfig = {
             ...(zephyrKconfig ? { kconfig: zephyrKconfig } : {}),
             ...(zephyrCmakeArgs ? { cmakeArgs: zephyrCmakeArgs } : {}),
+            ...(zephyrRunnerArgs ? { runnerArgs: zephyrRunnerArgs } : {}),
+            ...(typeof zephyrProbe === "string" ? { probe: zephyrProbe } : {}),
             ...(typeof zephyrRunner === "string" ? { runner: zephyrRunner } : {}),
+            ...(zephyrCustomBoard === true ? { customBoard: true } : {}),
         };
     }
     // Parse display profile config (nested object with profile name, wiring, touch)
@@ -470,8 +496,8 @@ export function parseConfigFile(configPath) {
     const structuredForValidation = {};
     if (resolved.target)
         structuredForValidation.target = resolved.target;
-    if (resolved.mcu)
-        structuredForValidation.mcu = resolved.mcu;
+    if (resolved.soc)
+        structuredForValidation.soc = resolved.soc;
     if (resolved.board)
         structuredForValidation.board = resolved.board;
     if (resolved.contract)
@@ -492,8 +518,6 @@ export function parseConfigFile(configPath) {
             ...(resolved.outputDefines ? { defines: resolved.outputDefines } : {}),
         };
     }
-    if (resolved.console)
-        structuredForValidation.console = resolved.console;
     if (resolved.zephyrConfig)
         structuredForValidation.zephyr = resolved.zephyrConfig;
     if (resolved.frameworkConfig)
@@ -526,9 +550,162 @@ export function parseConfigFile(configPath) {
  * The file is regenerated on every transpiler run so it stays in sync when
  * the board changes in `cuttlefish.config.ts`.
  */
+/** Refresh a stale catalog overlay before the board-module check — fs-only
+ *  discovery, re-walks the tree only when the provenance moved. Errors are
+ *  swallowed deliberately: an offline or tree-less machine keeps whatever
+ *  catalog it already has; generation surfaces the real problem. */
+function refreshBoardCatalogQuietly() {
+    try {
+        ensureFreshBoardCatalog();
+    }
+    catch {
+        // non-fatal by design
+    }
+}
+/**
+ * Ensure the generated board module (.cuttlefish/board.ts + board.json)
+ * is current for a board-target config. Regen-first: any input change —
+ * the config's board, the catalog overlay, the Zephyr tree, the generator
+ * revision — recreates the module, so the emitted module is
+ * project-pinned and diffable, not rebuilt on every compile. One exception:
+ * when the module on disk is for a DIFFERENT board than config.board (the
+ * user switched boards), it regenerates automatically — a stale module is
+ * the split-brain trap, not something to pin.
+ */
+function ensureGeneratedBoard(config, cuttlefishDir) {
+    const boardTsPath = path.join(cuttlefishDir, "board.ts");
+    const boardJsonPath = path.join(cuttlefishDir, "board.json");
+    // Regen-first: the board module is a derived artifact, recreated whenever
+    // ANY input moves — the config's board target, the catalog overlay, the
+    // Zephyr tree the overlay was generated from, or the extraction revision.
+    // The check is cheap (fs-only provenance + a fingerprint compare); a
+    // stale overlay re-walks the tree once, then this regenerates.
+    refreshBoardCatalogQuietly();
+    if (fs.existsSync(boardTsPath) && fs.existsSync(boardJsonPath)) {
+        try {
+            const existing = JSON.parse(fs.readFileSync(boardJsonPath, "utf8"));
+            const sameBoard = existing.identifier
+                && existing.identifier.toLowerCase() === config.board.toLowerCase();
+            const overlay = loadBoardCatalogOverlay();
+            const entry = overlay && sameBoard ? findBoardInCatalog(overlay.data, config.board) : undefined;
+            const sameSource = entry && overlay
+                ? existing.source?.fingerprint
+                    === boardRecordFingerprint(entry, overlay)
+                        + factsFingerprint(readUserFactsJson(config) ?? "")
+                        + factsFingerprint(readAsBuiltJson(config) ?? "")
+                : true; // no overlay to verify against — keep the existing module
+            if (sameBoard && sameSource)
+                return;
+        }
+        catch {
+            // Unreadable manifest — regenerate below rather than build on a
+            // module of unknown provenance.
+        }
+    }
+    // Missing files, a board mismatch, or a source change — (re)generate.
+    const target = config.board;
+    if (!config.framework) {
+        throw new Error(`Cannot generate the board module for '${target}' — no framework configured.`);
+    }
+    // The framework owns board generation; reach its strategy through the
+    // configured package (exported as ZephyrStrategy / default). The package
+    // is ESM ("type": "module"), so resolve it from the built dist through
+    // createRequire against the project's node_modules resolution.
+    const generated = loadFrameworkBoardModule(config, configDirOf(config), readUserFactsJson(config), readAsBuiltJson(config));
+    if (!generated) {
+        throw new Error(`Framework '${config.framework}' cannot generate a board module for '${target}'. ` +
+            `Check the target against the framework's board catalog.`);
+    }
+    // User-facts notes (shadowed harvest routes) surface once per regen —
+    // the fingerprint keeps regens rare.
+    for (const w of generated.warnings ?? [])
+        console.warn(`cuttlefish: ${w}`);
+    fs.writeFileSync(boardTsPath, generated.boardTs, "utf-8");
+    fs.writeFileSync(boardJsonPath, generated.boardJson, "utf-8");
+}
+/**
+ * Force-regenerate the project-local board module — the `cuttlefish board
+ * regen` path. Board-target configs only: contract projects write their
+ * board module through the contract reader, and native projects have none.
+ * Returns the .cuttlefish directory the module was written to.
+ */
+export function regenBoardModule(config) {
+    if (!config.board || config.contract) {
+        throw new Error("'cuttlefish board regen' applies to board-target projects. " +
+            "Set 'board:' in cuttlefish.config.ts (contract projects regenerate on build).");
+    }
+    const cuttlefishDir = path.join(path.dirname(config.configPath), ".cuttlefish");
+    if (!fs.existsSync(cuttlefishDir)) {
+        fs.mkdirSync(cuttlefishDir, { recursive: true });
+    }
+    fs.rmSync(path.join(cuttlefishDir, "board.ts"), { force: true });
+    fs.rmSync(path.join(cuttlefishDir, "board.json"), { force: true });
+    ensureGeneratedBoard(config, cuttlefishDir);
+    return cuttlefishDir;
+}
+/** The project's last-build snapshot (.cuttlefish/as-built.json, written by
+ *  the framework toolchain after each successful west build). Absent →
+ *  undefined; malformed content is handled downstream (soft ignore). */
+function readAsBuiltJson(config) {
+    const p = path.join(path.dirname(config.configPath), ".cuttlefish", "as-built.json");
+    if (!fs.existsSync(p))
+        return undefined;
+    try {
+        return fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return undefined; // best-effort enrichment — never blocks generation
+    }
+}
+/** The project's raw cuttlefish.facts.json text, when one exists beside the
+ *  config. Absent file → undefined; present-but-unreadable surfaces. */
+function readUserFactsJson(config) {
+    const factsPath = path.join(path.dirname(config.configPath), "cuttlefish.facts.json");
+    if (!fs.existsSync(factsPath))
+        return undefined;
+    try {
+        return fs.readFileSync(factsPath, "utf8");
+    }
+    catch (err) {
+        throw new Error(`cuttlefish.facts.json exists but cannot be read: ${err.message}`);
+    }
+}
+/** Resolve the configured framework package's board generator. The framework
+ *  packages are ESM, so this imports their built entry from the resolving
+ *  project's node_modules (createRequire against the project dir).
+ *  @param configDir  the project directory (where node_modules resolution starts) */
+function configDirOf(config) {
+    return path.dirname(config.configPath);
+}
+function loadFrameworkBoardModule(config, configDir, factsJson, asBuiltJson) {
+    const target = config.board;
+    const spec = config.framework;
+    const tryResolve = (anchor) => {
+        try {
+            const projectRequire = createRequire(anchor);
+            const mod = projectRequire(projectRequire.resolve(spec));
+            const Ctor = mod.ZephyrStrategy ?? mod.default;
+            const strategy = typeof Ctor === "function" ? new Ctor() : undefined;
+            const opts = {};
+            if (factsJson !== undefined)
+                opts.factsJson = factsJson;
+            if (asBuiltJson !== undefined)
+                opts.asBuiltJson = asBuiltJson;
+            return strategy?.generateBoardModule?.(target, Object.keys(opts).length > 0 ? opts : undefined) ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // Resolve from the project's package.json when it has one; projects without
+    // one (bare configs, tests) fall back to cuttlefish's own resolution — the
+    // framework is a peer of the tool in every real layout.
+    return (tryResolve(path.join(configDir, "package.json")) ??
+        tryResolve(path.join(path.dirname(fileURLToPath(import.meta.url)), "package.json")));
+}
 export function generateVirtualTypeDeclaration(config, platformDeclarations) {
-    if (!config.mcu && !config.board) {
-        // For native targets with no board/mcu, still generate declarations
+    if (!config.board && !config.soc) {
+        // For native targets with no board, still generate declarations
         if (!platformDeclarations || platformDeclarations.length === 0)
             return;
     }
@@ -541,22 +718,23 @@ export function generateVirtualTypeDeclaration(config, platformDeclarations) {
     }
     // Determine what @typecad/board exports
     let boardExport = "";
-    if (config.contract) {
-        // Contract-based: export from generated board (same dir — .cuttlefish/)
+    if (config.contract || config.board) {
+        // Board-target or contract project: the project-local generated board
+        // module (.cuttlefish/board.ts) — produced by boardgen (board target)
+        // or the contract reader (soc + contract), never a package.
         boardExport = "export * from './board.js';";
     }
-    else if (config.board) {
-        // Explicit board package (legacy)
-        boardExport = `export * from '${config.board}';`;
-    }
-    else if (config.mcu) {
-        // MCU-only: export all from MCU
-        boardExport = `export * from '${config.mcu}';`;
-    }
     else {
-        // Native target with no board/mcu: empty export
+        // Native target with no board: empty export
         boardExport = "";
     }
+    // Board-target projects: ensure the generated board module exists. The
+    // framework owns the generation (the Zephyr framework joins its board
+    // data pack with its curated soc descriptors) — reach it through the
+    // configured framework package's strategy hook.
+    if (config.board && !config.contract) {
+        ensureGeneratedBoard(config, cuttlefishDir);
+    }
     const content = [
         "// ---------------------------------------------------------------------------",
         "// cuttlefish-env.d.ts — Virtual module declaration for '@typecad/board'",
@@ -564,7 +742,7 @@ export function generateVirtualTypeDeclaration(config, platformDeclarations) {
         "// Auto-generated by the cuttlefish transpiler. Do not edit manually.",
         "// To change the board, update cuttlefish.config.ts and re-run the transpiler.",
         "//",
-        `// Board: ${config.board ?? config.mcu ?? "native"}`,
+        `// Board: ${config.board ?? config.soc ?? "native"}`,
         "// ---------------------------------------------------------------------------",
         "",
         "declare global {",
@@ -600,30 +778,10 @@ export function generateVirtualTypeDeclaration(config, platformDeclarations) {
         "  type float = number;",
         "  type double = number;",
         "",
-        "  // console — declared here (not pulled from lib.dom) so a project does not",
-        "  // need \"dom\" in tsconfig lib just to type console.log. Avoiding lib.dom",
-        "  // also keeps DOM global type names (Node, Element, Event, Document, ...)",
-        "  // out of scope, so a user class named e.g. `Node` is not shadowed by the",
-        "  // DOM global of the same name. Platforms may declaration-merge extra",
-        "  // members onto this interface via ambientTypeDeclarations().",
-        "  interface Console {",
-        "    log(...args: unknown[]): void;",
-        "    info(...args: unknown[]): void;",
-        "    debug(...args: unknown[]): void;",
-        "    warn(...args: unknown[]): void;",
-        "    error(...args: unknown[]): void;",
-        "  }",
-        "  const console: Console;",
-        "",
         "  // Convenience helper for volatile variables in TypeCAD programs.",
         "  // The transpiler detects calls to volatile() and emits the C++ volatile qualifier.",
         "  declare function volatile<T>(value: T): T;",
         "",
-        "  // JS-style timers",
-        "  declare function setInterval(handler: () => void, timeout?: number): number;",
-        "  declare function setTimeout(handler: () => void, timeout?: number): number;",
-        "  declare function clearInterval(id: number): void;",
-        "  declare function clearTimeout(id: number): void;",
         ...(platformDeclarations ?? []),
         "}",
         "",
@@ -638,28 +796,34 @@ export function generateVirtualTypeDeclaration(config, platformDeclarations) {
         "",
     ].join("\n");
     fs.writeFileSync(outPath, content, "utf-8");
-    // Also write a `.cuttlefish/board.ts` re-export. The scaffolded tsconfig.json
-    // path mapping points the virtual specifier ("@typecad/board") at this file so
-    // the TypeScript language server and the transpiler's type-check resolve
-    // `import { ... } from '@typecad/board'` to the configured board — which
-    // re-exports the HAL plus board-specific pins. Without this, the ambient
-    // `declare module` in cuttlefish-env.d.ts is treated as module augmentation
-    // (because that file has `export {}`), which can't define a new module.
-    //
-    // For contract-based configs, the narrowed board.ts is generated by the
-    // contract reader (`contract/board-generator.ts`, invoked from cli.ts before
-    // this function runs), so don't overwrite it with the generic re-export here.
-    if (!config.contract && (config.board || config.mcu)) {
-        const reExportSource = config.board ?? config.mcu;
-        const boardTsPath = path.join(cuttlefishDir, "board.ts");
-        const boardTsContent = [
-            `// Auto-generated by the cuttlefish transpiler. Do not edit manually.`,
-            `// Re-exports the configured board/MCU package so the tsconfig path`,
-            `// mapping for the virtual "@typecad/board" specifier resolves correctly.`,
-            `export * from '${reExportSource}';`,
-            ``,
-        ].join("\n");
-        fs.writeFileSync(boardTsPath, boardTsContent, "utf-8");
+    // The .cuttlefish/board.ts module itself is written by ensureGeneratedBoard
+    // (board-target configs, above) or the contract reader (invoked from cli.ts
+    // before this function runs) — never a package re-export here. The
+    // scaffolded tsconfig path mapping points the virtual specifier
+    // ("@typecad/board") at that file, and the ambient declare module in
+    // cuttlefish-env.d.ts mirrors it for the language server.
+    // A project-local test-pins.json (board packages are gone — projects that
+    // want role pins carry them) gets a sibling .cuttlefish/test-pins.ts
+    // re-export, so the language server resolves the '@typecad/test-pins'
+    // virtual specifier to the same role consts the transpiler generates.
+    if (config.board) {
+        const projectTestPins = path.join(configDir, "test-pins.json");
+        const testPinsData = fs.existsSync(projectTestPins)
+            ? readTestPinsFile(configDir)
+            : undefined;
+        const testPinsContent = testPinsData
+            ? buildTestPinsModuleContent(config.board, testPinsData)
+            : undefined;
+        if (testPinsContent) {
+            const testPinsTsPath = path.join(cuttlefishDir, "test-pins.ts");
+            const existing = fs.existsSync(testPinsTsPath)
+                ? fs.readFileSync(testPinsTsPath, "utf8")
+                : undefined;
+            const withHeader = testPinsContent.replace(/^\/\/ Generated from/, "// Auto-generated by the cuttlefish transpiler. Do not edit manually.\n// Generated from");
+            if (existing !== withHeader) {
+                fs.writeFileSync(testPinsTsPath, withHeader, "utf-8");
+            }
+        }
     }
 }
 /**