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

package/dist/contract/index.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedCuttlefishConfig } from '../config-loader.js';
 export type { HwContract, ContractPin, ContractComponent, AvailablePeripherals, } from './contract-parser.js';
-export { parseContractFile, matchConnectedPins, selectPeripherals } from './contract-parser.js';
+export { parseContractFile, matchConnectedPins, selectPeripherals, contractPinNames, contractPads } from './contract-parser.js';
 export { generateBoardFile, CUTTLEFISH_DIR } from './board-generator.js';
 export type { GenerateBoardOptions } from './board-generator.js';
 /**

package/dist/contract/index.js

@@ -7,9 +7,12 @@
 // module is what writes that file.
 // ---------------------------------------------------------------------------
 import path from 'node:path';
-import { parseContractFile, matchConnectedPins, selectPeripherals } from './contract-parser.js';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { locateZephyrBaseCheap } from '../board-catalog/index.js';
+import { parseContractFile, contractPinNames, contractPads } from './contract-parser.js';
 import { generateBoardFile } from './board-generator.js';
-export { parseContractFile, matchConnectedPins, selectPeripherals } from './contract-parser.js';
+export { parseContractFile, matchConnectedPins, selectPeripherals, contractPinNames, contractPads } from './contract-parser.js';
 export { generateBoardFile, CUTTLEFISH_DIR } from './board-generator.js';
 /**
  * Orchestrates contract-based board generation for a resolved config:
@@ -31,9 +34,9 @@ export async function generateContractBoard(config) {
     if (!config.contract) {
         throw new Error('generateContractBoard called without config.contract');
     }
-    if (!config.mcu) {
-        throw new Error(`A 'contract' config requires an 'mcu' package to narrow against. ` +
-            `Add e.g. mcu: '@typecad/mcu-atmega328p' to cuttlefish.config.ts.`);
+    if (!config.soc && !config.buildTarget) {
+        throw new Error(`A 'contract' config requires a 'soc' (Zephyr SoC name) to narrow against. ` +
+            `Add e.g. soc: 'stm32f411xe' to cuttlefish.config.ts.`);
     }
     const projectDir = path.dirname(config.configPath);
     const contractPath = path.isAbsolute(config.contract)
@@ -41,27 +44,73 @@ export async function generateContractBoard(config) {
         : path.resolve(projectDir, config.contract);
     // (1) Parse the contract.
     const contract = parseContractFile(contractPath);
-    // (2) Load the MCU manifest. The MCU package is a peer at runtime — import
-    // it dynamically so cuttlefish doesn't hard-depend on any single MCU.
-    let manifest;
+    // (2) SDK-as-truth: the SoC's bus controller labels come from the
+    // INSTALLED Zephyr tree's soc dtsi (located via the same fs-only
+    // discovery the catalog uses), and the wired pads come from the contract
+    // itself. The framework runs them through the same board-module builder
+    // every catalog board uses.
+    const soc = config.soc ?? path.basename(config.buildTarget ?? '').split('/')[0];
+    if (!soc) {
+        throw new Error("Contract-based projects need a `soc:` (Zephyr SoC name, e.g. 'stm32f411xe') " +
+            "in cuttlefish.config.ts to select the silicon the contract narrows.");
+    }
+    if (!config.framework) {
+        throw new Error("Contract-based projects need a `framework:` package to generate the board data.");
+    }
+    // ESM-safe: the framework packages are "type": "module" — resolve through
+    // createRequire anchored at the project's package.json.
+    let strategy;
     try {
-        const mod = (await import(config.mcu));
-        if (!mod.TypeCADManifest) {
-            throw new Error(`'${config.mcu}' does not export a TypeCADManifest.`);
-        }
-        manifest = mod.TypeCADManifest;
+        const projectRequire = createRequire(path.join(projectDir, 'package.json'));
+        const mod = projectRequire(projectRequire.resolve(config.framework));
+        const Ctor = mod.ZephyrStrategy ?? mod.default;
+        strategy = typeof Ctor === 'function' ? new Ctor() : undefined;
+    }
+    catch {
+        strategy = undefined;
     }
-    catch (err) {
-        throw new Error(`Could not load TypeCADManifest from MCU package '${config.mcu}' for contract-based ` +
-            `board generation: ${err.message}`);
+    if (!strategy?.generateContractBoardModule) {
+        throw new Error(`Framework '${config.framework}' provides no contract board generation. ` +
+            `Zephyr contract projects require '@typecad/framework-zephyr' (which derives the ` +
+            `soc's bus controllers from the installed Zephyr tree).`);
     }
-    // (3) Match + select.
-    const connectedPins = matchConnectedPins(contract, manifest.pinNames);
-    const peripherals = selectPeripherals(contract, manifest.peripheralNames);
-    // (4) Emit the narrowed board.
+    const zephyrBase = locateZephyrBaseCheap();
+    if (!zephyrBase) {
+        throw new Error(`No Zephyr tree found for the contract build. The SoC's bus controllers are derived ` +
+            `from the installed Zephyr tree — install one via '@typecad/framework-zephyr' ` +
+            `(zephyr-installer) or set ZEPHYR_BASE.`);
+    }
+    const generated = strategy.generateContractBoardModule({
+        soc,
+        zephyrBase,
+        // The contract's own canonical pad names (boardName when typecad.net
+        // carried a mapping, else the KiCAD pin-name segment that matches the
+        // soc's datasheet form).
+        pinNames: contractPads(contract).map((p) => p.mcuName),
+        padAliases: contractPads(contract)
+            .filter((p) => p.alias)
+            .map((p) => ({ exportName: p.alias, padName: p.mcuName })),
+        peripherals: contract.availablePeripherals,
+    });
+    // (3) The narrowed pad set: the contract's own canonical names — the
+    // board module the framework generated exposes the soc's datasheet sweep
+    // for the wired controllers; board.ts narrows the user surface to the
+    // pads the PCB actually wired (an unwired pin is a compile error).
+    const connectedPins = contractPinNames(contract);
+    const peripherals = [
+        contract.availablePeripherals.i2c ? 'I2C0' : '',
+        contract.availablePeripherals.spi ? 'SPI0' : '',
+        contract.availablePeripherals.uart ? 'UART0' : '',
+    ].filter(Boolean);
+    // (4) Emit the soc's full board.json — the transpiler's pin map and chip
+    // resolution read it (same artifact a board-target project carries).
+    const cuttlefishDir = path.join(projectDir, '.cuttlefish');
+    fs.mkdirSync(cuttlefishDir, { recursive: true });
+    fs.writeFileSync(path.join(cuttlefishDir, 'board.json'), generated.boardJson, 'utf-8');
+    // (5) Emit the narrowed board.
     return generateBoardFile({
         projectDir,
-        mcuPackage: config.mcu,
+        soc,
         connectedPins,
         peripherals,
     });

package/dist/create/active-board-catalog.d.ts

@@ -0,0 +1,9 @@
+import type { BoardDataEntry } from './board-catalog.generated.js';
+/**
+ * The active board catalog: the local overlay when one is discoverable
+ * (env var, $ZEPHYR_BASE, well-known workspace layouts, installer env),
+ * else the compiled-in generated pack. Memoized per process.
+ */
+export declare function activeBoardCatalog(): Record<string, BoardDataEntry>;
+/** Test hook — drop the memo so env/discovery changes take effect. */
+export declare function resetActiveBoardCatalog(): void;

package/dist/create/active-board-catalog.js

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// active-board-catalog.ts — the board catalog the create flow resolves
+// against: the local overlay when one exists, else the compiled-in pack.
+//
+// `cuttlefish create` runs BEFORE the framework package is installed, so it
+// cannot ask the framework for its catalog. It reads the same overlay file
+// `cuttlefish board sync` writes — <workspace>/.cuttlefish/board-catalog.json
+// beside the Zephyr checkout — with fs-only discovery (no spawns; the wizard
+// stays snappy). The schema/path contract lives in framework-zephyr's
+// src/sdk/board-catalog-sync.ts; keep this reader in sync with it.
+//
+// The overlay REPLACES the compiled-in pack (not a merge): it describes the
+// exact tree west builds against, including boards the shipped pack no
+// longer carries.
+// ----------------------------------------------------------------------------
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { BOARD_DATA } from './board-catalog.generated.js';
+/** Explicit overlay file ('' / 'off' disables) — same var as the framework's loader. */
+const OVERLAY_ENV = 'CUTTLEFISH_BOARD_CATALOG';
+const OVERLAY_SCHEMA = 1;
+/** True when dir looks like a Zephyr checkout (mirrors west-discover's check). */
+function isZephyrBase(dir) {
+    return (fs.existsSync(path.join(dir, 'CMakeLists.txt')) &&
+        fs.existsSync(path.join(dir, 'include', 'zephyr', 'kernel.h')));
+}
+/** Installer-written ZEPHYR_BASE from the micromamba env-vars file (fs-only). */
+function micromambaZephyrBase() {
+    const root = process.env.MAMBA_ROOT_PREFIX || path.join(homedir(), 'micromamba');
+    const envDir = path.join(root, 'envs', process.env.TYPECAD_ZEPHYR_ENV || 'zephyr');
+    const candidates = process.platform === 'win32'
+        ? [path.join(envDir, 'etc', 'conda', 'env-vars.ps1'), path.join(envDir, 'etc', 'conda', 'env-vars.bat')]
+        : [path.join(envDir, 'etc', 'conda', 'env-vars.sh')];
+    for (const f of candidates) {
+        if (!fs.existsSync(f))
+            continue;
+        try {
+            const m = fs.readFileSync(f, 'utf8').match(/TYPECAD_ZEPHYR_BASE\s*=\s*"([^"]+)"/);
+            if (m && isZephyrBase(m[1]))
+                return m[1];
+        }
+        catch {
+            // unreadable — try the next candidate
+        }
+    }
+    return undefined;
+}
+let cached;
+/**
+ * The active board catalog: the local overlay when one is discoverable
+ * (env var, $ZEPHYR_BASE, well-known workspace layouts, installer env),
+ * else the compiled-in generated pack. Memoized per process.
+ */
+export function activeBoardCatalog() {
+    if (cached)
+        return cached;
+    cached = { ...BOARD_DATA };
+    const read = (file) => {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (parsed.schema === OVERLAY_SCHEMA && parsed.boards)
+                cached = parsed.boards;
+        }
+        catch {
+            // unreadable/malformed overlay — keep the compiled-in pack
+        }
+    };
+    const explicit = process.env[OVERLAY_ENV];
+    if (explicit !== undefined) {
+        if (explicit !== '' && explicit.toLowerCase() !== 'off')
+            read(explicit);
+        return cached;
+    }
+    const home = homedir();
+    const trees = [
+        process.env.ZEPHYR_BASE,
+        path.join(home, 'zephyrproject', 'zephyr'),
+        path.join(home, 'zephyr', 'zephyr'),
+        ...(process.platform === 'win32' ? ['C:\\zephyrproject\\zephyr', 'C:\\zephyr\\zephyr'] : ['/opt/zephyrproject/zephyr', '/opt/zephyr/zephyr']),
+        micromambaZephyrBase(),
+    ];
+    for (const t of trees) {
+        if (t && isZephyrBase(t)) {
+            read(path.join(path.dirname(path.resolve(t)), '.cuttlefish', 'board-catalog.json'));
+            break;
+        }
+    }
+    return cached;
+}
+/** Test hook — drop the memo so env/discovery changes take effect. */
+export function resetActiveBoardCatalog() {
+    cached = undefined;
+}

package/dist/create/board-catalog.generated.d.ts

@@ -0,0 +1,96 @@
+export interface BoardDataEntry {
+    /** Qualified west build target (the variant yaml identifier). */
+    readonly identifier: string;
+    /** Human board name. */
+    readonly name: string;
+    /** Vendor directory name. */
+    readonly vendor: string;
+    /** The variant DTS file this was extracted from. */
+    readonly dts: string;
+    /** Console controller nodelabel (the chosen zephyr,console). */
+    readonly console?: string;
+    /** Addressable user LED (worldsemi,ws2812-*): the pad driving the pixel.
+     *  A plain-GPIO LED — no led0 devicetree spec (the pixel is not a
+     *  gpio-leds node). Present only when the board has no gpio-leds LED. */
+    readonly stripLed?: {
+        readonly controller: string;
+        readonly pin: number;
+    };
+    /** PWM-driven LEDs (pwm-leds children) in board order. The alias is the
+     *  devicetree alias ('pwm-led0') — the DT_ALIAS-addressable form the PWM
+     *  lowering needs; non-aliased channels are carried for reference. */
+    readonly pwmLeds?: readonly {
+        readonly alias?: string;
+        readonly controller: string;
+        readonly channel: number;
+        readonly periodNs?: number;
+        readonly flags?: readonly string[];
+    }[];
+    /** The board's USB device wiring: 'enabled' (DTS turns the device
+     *  controller on), 'disabled' (explicitly off — suppress the USB0
+     *  export), undefined (silent; the app overlay may still compose CDC). */
+    readonly usbDevice?: 'enabled' | 'disabled';
+    /** The USB device controller nodelabel backing usbDevice. */
+    readonly usbController?: string;
+    /** Watchdog node label (the devicetree watchdog0 alias). */
+    readonly wdtNodeLabel?: string;
+    /** Bus controller nodelabels the board DTS wires up (&i2c0/&spi2/&usart1
+     *  overrides). Board-level facts only — a bus enabled solely in the SoC
+     *  dtsi is invisible here. */
+    readonly buses?: {
+        readonly i2c: readonly string[];
+        readonly spi: readonly string[];
+        readonly uart: readonly string[];
+    };
+    /** Probe/flash methods from the board's board.cmake (west runners, in the
+     *  board's include order — first = west's default runner). */
+    readonly probeMethods?: readonly {
+        readonly id: string;
+        readonly description: string;
+        readonly runner: string;
+        readonly args?: readonly string[];
+        readonly debug?: boolean;
+        readonly debugInterface?: 'swd' | 'jtag';
+        readonly debugDevice?: string;
+        /** The board's support/openocd.cfg, verbatim lines in file order. */
+        readonly debugCfg?: readonly string[];
+    }[];
+    /** The canonical aliased LED (led0). */
+    readonly led?: {
+        readonly dtSpec: string;
+        readonly controller: string;
+        readonly pin: number;
+        readonly flags: readonly string[];
+    };
+    /** The canonical aliased button (sw0). */
+    readonly button?: {
+        readonly dtSpec: string;
+        readonly controller: string;
+        readonly pin: number;
+        readonly flags: readonly string[];
+    };
+    /** Additional aliased LEDs/buttons beyond the canonical ones. */
+    readonly extraLeds?: readonly {
+        readonly dtSpec: string;
+        readonly controller: string;
+        readonly pin: number;
+        readonly flags: readonly string[];
+    }[];
+    readonly extraButtons?: readonly {
+        readonly dtSpec: string;
+        readonly controller: string;
+        readonly pin: number;
+        readonly flags: readonly string[];
+    }[];
+    /** Connector gpio-maps (arduino headers, XIAO edge connector, ...). */
+    readonly connectors?: readonly {
+        readonly nodelabel: string;
+        readonly compatible?: string;
+        readonly pins: Readonly<Record<string, {
+            readonly controller: string;
+            readonly pin: number;
+            readonly flags: readonly string[];
+        }>>;
+    }[];
+}
+export declare const BOARD_DATA: Readonly<Record<string, BoardDataEntry>>;