@typecad/cuttlefish 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 typecad0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# `@typecad/cuttlefish`
+
+TypeScript → C++ transpiler for embedded firmware. Targets native (desktop),
+Arduino, and bare-metal MCU builds from a single TypeScript codebase.
+
+`cuttlefish` is the command-line tool at the center of the [TypeCAD](https://github.com/justind000/typecode)
+toolchain: it loads `cuttlefish.config.ts`, transpiles TypeScript firmware to
+C++, and can chain compile, upload, and serial-monitor steps.
+
+## Quick start
+
+From a project root containing `cuttlefish.config.ts`:
+
+```bash
+npx cuttlefish build
+npx cuttlefish build --compile --upload --port COM4
+npx cuttlefish build --compile --upload --monitor --port COM4 --baud 115200
+```
+
+Scaffold a starter project with the built-in wizard:
+
+```bash
+npx cuttlefish create --board arduino:avr:uno --framework arduino
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `cuttlefish build` | Transpile the entry file (default). Accepts `--compile`, `--upload`, `--monitor`, `--port`, `--baud`. |
+| `cuttlefish create` | Generate a starter project and `cuttlefish.config.ts`. |
+| `cuttlefish board-add` | Add a new board package via the board-codegen scaffolder. |
+| `cuttlefish preview` | Launch the browser preview server for a UI project. |
+| `cuttlefish map-error <mapFile>` | Map a C++ compiler error back to its TypeScript source location. |
+| `cuttlefish gen-decls` | Generate type declaration stubs. |
+| `cuttlefish gen-libdefs <input.ts>` | Generate library definition stubs for third-party imports. |
+
+### Flags (for `build`)
+
+- `--compile` — transpile, then compile via the active framework's toolchain (`arduino-cli` for Arduino, `g++` for native).
+- `--upload` — flash firmware to the board (implies `--compile`).
+- `--monitor` — open a serial monitor after upload.
+- `--port <port>` — serial port for upload/monitor (e.g. `COM4`, `/dev/ttyUSB0`).
+- `--baud <rate>` — serial monitor baud rate.
+
+## Configuration
+
+The CLI reads `cuttlefish.config.ts` from the current working directory and
+treats it as the source of truth. When no config file is present, command-line
+flags such as `--fqbn` and `--board` supply board and build settings.
+
+```ts
+import type { CuttlefishConfig } from '@typecad/cuttlefish/api';
+
+const config: CuttlefishConfig = {
+  entry: './src/main.ts',
+  target: 'esp32',
+  mcu: '@typecad/mcu-esp32',
+  board: '@typecad/board-esp32-devkit',
+  framework: '@typecad/framework-arduino',
+};
+
+export default config;
+```
+
+## Ecosystem
+
+`@typecad/cuttlefish` is the transpiler core. It pairs with sibling packages:
+
+- [`@typecad/hal`](https://github.com/justind000/typecode/tree/main/packages/hal) — hardware abstraction (GPIO, I2C, SPI, UART) as regular TypeScript.
+- [`@typecad/ui`](https://github.com/justind000/typecode/tree/main/packages/ui) — HTML/CSS-driven graphics for microcontroller displays.
+- [`@typecad/expect`](https://github.com/justind000/typecode/tree/main/packages/expect) — hardware test framework (vitest-style assertions over serial).
+- [`@typecad/framework-arduino`](https://github.com/justind000/typecode/tree/main/packages/framework-arduino) — Arduino framework code-gen strategy.
+- [`@typecad/framework-native`](https://github.com/justind000/typecode/tree/main/packages/framework-native) — native desktop C++ code-gen strategy.
+- `@typecad/mcu-*` and `@typecad/board-*` — silicon- and board-level pin/peripheral definitions.
+
+## License
+
+MIT

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

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

package/dist/api/board-types.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// @typecad/hal — Architecture identifier type used by project configuration.
+// ---------------------------------------------------------------------------
+export {};

package/dist/api/capabilities.d.ts

@@ -0,0 +1,12 @@
+export interface PinCapabilityFlags {
+    digitalInput: boolean;
+    digitalOutput: boolean;
+    analogInput: boolean;
+    analogOutput: boolean;
+    pwm: boolean;
+    interrupt: boolean;
+    pullUp: boolean;
+    pullDown: boolean;
+    touch: boolean;
+    openDrain: boolean;
+}

package/dist/api/capabilities.js

@@ -0,0 +1 @@
+export {};

package/dist/api/config.d.ts

@@ -0,0 +1,120 @@
+import type { ArchitectureIdentifier } from './board-types.js';
+import type { DisplayConfig } from './shared/display-profile.js';
+/** Build-system / framework the transpiler should target. */
+type OutputFramework = string & {};
+/** Optimization strategy. */
+type OptimizationLevel = 'none' | 'size' | 'speed' | 'balanced';
+/**
+ * Output section — controls how generated C++ is laid out.
+ */
+interface CuttlefishOutputConfig {
+    /** Target build framework. */
+    framework: OutputFramework;
+    /** Optimization level. */
+    optimize?: OptimizationLevel;
+    /** Directory to write generated files into (relative to project root). */
+    outDir?: string;
+    /** Additional compiler defines (KEY = value). */
+    defines?: Record<string, string>;
+    /** Extra compiler flags forwarded verbatim. */
+    extraFlags?: string[];
+}
+/**
+ * Root configuration object exported from `cuttlefish.config.ts`.
+ */
+export interface CuttlefishConfig {
+    /** Entry point TypeScript file (relative to config file directory). */
+    entry?: string;
+    /** Target architecture identifier (e.g. 'avr', 'esp32', 'rp2040'). */
+    target: ArchitectureIdentifier;
+    /**
+     * MCU package providing silicon definitions.
+     * Example: '@typecad/mcu-atmega328p'
+     */
+    mcu: string;
+    /**
+     * Board package to use. (Deprecated — use mcu + contract instead)
+     */
+    board?: string;
+    /**
+     * Path to a TypeCAD contract file (*.contract.json).
+     * If provided, the transpiler will generate a narrowed board definition.
+     */
+    contract?: string;
+    /**
+     * Framework package for code generation strategy.
+     */
+    framework?: string;
+    /** Output / build options. */
+    output?: CuttlefishOutputConfig;
+    /**
+     * Framework-specific data.
+     */
+    frameworkData?: Record<string, unknown>;
+    /** Extra project-level TypeScript paths the transpiler should include. */
+    include?: string[];
+    /** Glob patterns to exclude from transpilation. */
+    exclude?: string[];
+    /**
+     * Hardware test runner configuration.
+     */
+    test?: CuttlefishTestConfig;
+    /**
+     * Toolchain configuration for compile/upload operations.
+     */
+    toolchain?: CuttlefishToolchainConfig;
+    /**
+     * Console output configuration.
+     */
+    console?: CuttlefishConsoleConfig;
+    /**
+     * Framework-specific configuration.
+     */
+    native?: Record<string, unknown>;
+    /**
+     * Display configuration — references a built-in profile by name and/or
+     * specifies display wiring (cs, dc, rst) and overrides.
+     *
+     * display: { profile: 'ili9341-spi', cs: 5, dc: 21, rst: 22 }
+     */
+    display?: DisplayConfig;
+}
+/**
+ * Toolchain configuration for compile and upload operations.
+ */
+interface CuttlefishToolchainConfig {
+    /** Toolchain type identifier. Each framework defines its own valid values. */
+    type?: string;
+    /** Framework-specific toolchain options. Each framework reads its own key. */
+    frameworkOptions?: Record<string, unknown>;
+}
+/**
+ * Console output configuration for the target framework.
+ */
+interface CuttlefishConsoleConfig {
+    /** Default baud rate for console output when auto-injected. Default: 9600 */
+    baudRate?: number;
+    /**
+     * Serial port for upload and monitor (e.g. 'COM4', '/dev/ttyACM0').
+     * Can be overridden by the --port CLI flag.
+     */
+    port?: string;
+}
+/**
+ * Configuration for the `cuttlefish-test` hardware test runner.
+ */
+interface CuttlefishTestConfig {
+    /** Glob patterns for hardware test files. */
+    include?: string[];
+    /** Serial port the board is connected to (e.g. 'COM4', '/dev/ttyACM0'). */
+    port?: string;
+    /** Serial baud rate for the test protocol. Default: 115200. */
+    baudRate?: number;
+    /** Timeout in ms to wait for test completion. Default: 30000. */
+    timeout?: number;
+    /** Framework-specific build target override. */
+    buildTarget?: string;
+    /** Board package override — defaults to the root `board` field. */
+    board?: string;
+}
+export {};

package/dist/api/config.js

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// @typecad/hal — Project configuration types
+//
+// A `cuttlefish.config.ts` file lives at the root of a user project and tells
+// the transpiler which board, architecture, and build options to use.
+// ---------------------------------------------------------------------------
+export {};

package/dist/api/index.d.ts

@@ -0,0 +1,5 @@
+export * from './shared/index.js';
+export type { ArchitectureIdentifier } from './board-types.js';
+export type { PinCapabilityFlags } from './capabilities.js';
+export type { CuttlefishConfig } from './config.js';
+export * from './schema/index.js';

package/dist/api/index.js

@@ -0,0 +1,2 @@
+export * from './shared/index.js';
+export * from './schema/index.js';

package/dist/api/schema/builder.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A branded type representing a physical pin number on the MCU package.
+ * Use `pinNumber()` to create from a raw number.
+ */
+interface PinNumber {
+    readonly __brand: unique symbol;
+    readonly value: number;
+}
+/**
+ * Create a PinNumber from a raw number.
+ * @param n The physical pin number
+ */
+export declare function pinNumber(n: number): PinNumber;
+export {};

package/dist/api/schema/builder.js

@@ -0,0 +1,15 @@
+// ---------------------------------------------------------------------------
+// Board builder utilities
+//
+// Helpers used by board definition packages.
+// ---------------------------------------------------------------------------
+/**
+ * Create a PinNumber from a raw number.
+ * @param n The physical pin number
+ */
+export function pinNumber(n) {
+    if (n < 0 || !Number.isInteger(n)) {
+        throw new Error(`Invalid pin number: ${n}. Must be a non-negative integer.`);
+    }
+    return { value: n };
+}

package/dist/api/schema/index.d.ts

@@ -0,0 +1,2 @@
+export type { BoardDefinition, MCUDefinition, PinDefinition, PeripheralFunction, PeripheralInstance, PeripheralDefinitions, ADCDefinition, DACDefinition, PWMDefinition, TimerDefinition, FeatureFlags, MemorySpec, BuildConfig, } from './types.js';
+export { pinNumber, } from './builder.js';

package/dist/api/schema/index.js

@@ -0,0 +1 @@
+export { pinNumber, } from './builder.js';

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

@@ -0,0 +1,257 @@
+import type { PinCapabilityFlags } from '../capabilities.js';
+import type { ArchitectureIdentifier } from '../board-types.js';
+export interface MemorySpec {
+    /** Flash / program memory in bytes. */
+    flash: number;
+    /** SRAM in bytes. */
+    sram: number;
+    /** EEPROM in bytes (0 if none). */
+    eeprom: number;
+    /** External RAM (PSRAM) in bytes, if available. */
+    externalRam?: number;
+    /** RTC memory in bytes, if available. */
+    rtcMemory?: number;
+}
+export interface PinDefinition {
+    /** Pin number on the physical package. */
+    number: number;
+    /** GPIO number (may differ from physical pin). */
+    gpio?: number;
+    /** Pin name — MCU-native identifier (e.g. "PB5", "GPIO21", "PC0"). */
+    name: string;
+    /** MCU port identifier for contract matching (e.g. "PB5", "GPIO21"). Auto-derived from name if absent. */
+    port?: string;
+    /** Alternate names (e.g. ["LED", "SCK"], ["SDA"]). */
+    aliases?: string[];
+    /** Pin capabilities. */
+    capabilities: PinCapabilityFlags;
+    /** Associated peripheral functions. */
+    functions?: PeripheralFunction[];
+    /** Is this pin connected to the on-board LED? */
+    onboardLed?: boolean;
+    /** Is this pin connected to the on-board button? */
+    onboardButton?: boolean;
+    /** Notes / warnings about this pin. */
+    notes?: string;
+    /** Is this pin marked as unsafe? Use with caution (e.g., boot strapping pins). */
+    unsafe?: boolean;
+    /**
+     * Peripheral functions this pin participates in, expressed as human-readable
+     * strings for IDE hover / documentation. E.g. ["I2C0 SDA", "ADC ch4"].
+     * Auto-derived from `functions` but can be overridden for clarity.
+     */
+    alternateFunctions?: string[];
+    /**
+     * Warnings about using this pin. Shown in IDE hover and transpile diagnostics.
+     * E.g. ["Conflicts with UART0 — avoid if using Serial"]
+     */
+    warnings?: string[];
+}
+export interface PeripheralFunction {
+    /** Peripheral type. */
+    type: 'i2c' | 'spi' | 'uart' | 'adc' | 'dac' | 'pwm' | 'touch' | 'usb';
+    /** Peripheral instance number. */
+    instance: number;
+    /** Function role (e.g. "sda", "scl", "mosi", "miso"). */
+    role: string;
+    /** Timer associated with this PWM function (e.g. "timer0", "timer1"). */
+    timer?: string;
+}
+export interface PinDefinitions {
+    /** Offset for analog pin numbers (e.g. A0 = 14 on Uno). */
+    analogOffset?: number;
+    /** Complete list of every pin on the board. */
+    all: PinDefinition[];
+    /** Digital pin names. */
+    digital: string[];
+    /** Analog input pin names. */
+    analog: string[];
+    /** PWM-capable pin names. */
+    pwm: string[];
+    /** Pin names marked as unsafe (for validation warnings). */
+    unsafe?: string[];
+    /** I2C bus pin assignments keyed by bus instance number. */
+    i2c: Record<number, {
+        sda: string;
+        scl: string;
+    }>;
+    /** SPI bus pin assignments keyed by bus instance number. */
+    spi: Record<number, {
+        mosi: string;
+        miso: string;
+        sck: string;
+        cs?: string;
+    }>;
+    /** UART bus pin assignments keyed by bus instance number. */
+    uart: Record<number, {
+        tx: string;
+        rx: string;
+        rts?: string;
+        cts?: string;
+    }>;
+    /** On-board LED pin name. */
+    led?: string;
+    /** On-board button pin name. */
+    button?: string;
+}
+export interface PeripheralInstance {
+    instance: number;
+    defaultPins: Record<string, string>;
+    alternatePins?: Record<string, string[]>;
+}
+export interface ADCDefinition {
+    instance: number;
+    channels: number;
+    /** Resolution in bits. */
+    resolution: number;
+    /** Default reference voltage (used when no analogReference() call precedes readVoltage()). */
+    referenceVoltage: number;
+    /** Pre-computed maximum ADC value: (1 << resolution) - 1. Used by readVoltage() and board(). */
+    maxValue: number;
+    /** Per-reference voltage map keyed by AnalogReference member name (e.g. { DEFAULT: 5.0, INTERNAL: 1.1 }). */
+    referenceVoltages?: Record<string, number>;
+}
+export interface DACDefinition {
+    instance: number;
+    /** Resolution in bits. */
+    resolution: number;
+    pins: string[];
+}
+export interface PWMDefinition {
+    channels: number;
+    /** Resolution in bits. */
+    resolution: number;
+    /** Maximum frequency in Hz. */
+    maxFrequency: number;
+}
+export interface USBDefinition {
+    type: 'device' | 'host' | 'otg';
+    vid: string;
+    pid: string;
+}
+export interface WiFiDefinition {
+    type: 'wifi' | 'wifi6';
+    supportsStation: boolean;
+    supportsAp: boolean;
+}
+export interface BluetoothDefinition {
+    type: 'classic' | 'ble' | 'dual';
+    version: string;
+}
+export interface TouchDefinition {
+    channels: number;
+    pins: string[];
+}
+export interface TimerDefinition {
+    instance: number;
+    /** Timer type classification. */
+    type: 'general' | 'high_speed' | 'rtc' | 'sys';
+    /** Register width in bits. */
+    bits: 8 | 16 | 32 | 64;
+    /** Counter frequency in Hz (if fixed). */
+    frequency?: number;
+    /** Features supported by this timer. */
+    features?: Array<'pwm' | 'capture' | 'compare' | 'interrupt' | 'dma'>;
+}
+export interface DMADefinition {
+    instance: number;
+    /** Number of independent DMA channels. */
+    channels: number;
+    /** Peripherals that can act as DMA triggers/destinations. */
+    peripherals?: string[];
+    /** Max transfer size in bytes per transaction. */
+    maxTransferSize?: number;
+}
+export interface PeripheralDefinitions {
+    /** Peripheral object name aliases (e.g. UART0 -> Serial). */
+    aliases?: Record<string, string>;
+    i2c: readonly PeripheralInstance[];
+    spi: readonly PeripheralInstance[];
+    uart: readonly PeripheralInstance[];
+    adc: readonly ADCDefinition[];
+    dac?: readonly DACDefinition[];
+    pwm: PWMDefinition;
+    usb?: USBDefinition;
+    wifi?: WiFiDefinition;
+    bluetooth?: BluetoothDefinition;
+    touch?: TouchDefinition;
+    /** Hardware timers available for application use. */
+    timers?: readonly TimerDefinition[];
+    /** DMA controllers available for high-speed transfers. */
+    dma?: readonly DMADefinition[];
+}
+export interface FeatureFlags {
+    multicore: boolean;
+    coreCount: number;
+    deepSleep: boolean;
+    watchdog: boolean;
+    externalInterrupts: boolean;
+    hardwareRng: boolean;
+    fpu: boolean;
+}
+export interface BuildConfig {
+    /** Framework-specific build identifiers (e.g., { 'my-framework': 'target:arch:board' }). */
+    frameworks?: Record<string, string>;
+    linkerScript?: string;
+    extraFlags?: string[];
+    defines?: Record<string, string>;
+}
+/**
+ * Intrinsic hardware definition for a Microcontroller (MCU).
+ * Describes the silicon capabilities that are independent of any board.
+ */
+export interface MCUDefinition {
+    /** MCU identifier (e.g. "atmega328p"). */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Target architecture. */
+    architecture: ArchitectureIdentifier;
+    /** Built-in memory specifications. */
+    memory: MemorySpec;
+    /** Intrinsic pin definitions and capabilities. */
+    pins: PinDefinitions;
+    /** Hardware peripheral instances. */
+    peripherals: PeripheralDefinitions;
+    /** Silicon-level features. */
+    features: FeatureFlags;
+    /** MCU-specific build configuration. */
+    build: BuildConfig;
+}
+/**
+ * Board definition manifest.
+ * Describes a specific PCB implementation that utilizes an MCU.
+ */
+export interface BoardDefinition {
+    /** Board identifier (e.g. "my-board"). */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Board vendor. */
+    vendor: string;
+    /** Board description. */
+    description?: string;
+    /** The MCU used on this board. */
+    mcu: MCUDefinition;
+    /** External clock speed in Hz. */
+    clockSpeed: number;
+    /**
+     * Memory specifications (extends/overrides MCU memory).
+     * Used for boards with external flash or RAM.
+     */
+    memory?: Partial<MemorySpec>;
+    /**
+     * Pin definitions (extends/overrides MCU pins).
+     * Used for board-level aliases (D0, LED), header mappings, etc.
+     */
+    pins: PinDefinitions;
+    /**
+     * Built-in peripherals (extends/overrides MCU peripherals).
+     * Used for board-level aliases (Serial, Wire, SPI).
+     */
+    peripherals: PeripheralDefinitions;
+    /** Build configuration (overrides/extends MCU build). */
+    build: BuildConfig;
+    /** Related board variants. */
+    variants?: string[];
+}

package/dist/api/schema/types.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// @typecad/cuttlefish/api/schema — Board definition manifest types
+// ---------------------------------------------------------------------------
+export {};

package/dist/api/shared/async-runtime-static.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Generate a heap-free static async runtime for C++ targets without <vector>.
+ *
+ * @param capacity Fixed number of timer/task slots. Keep small on constrained
+ *   targets (e.g. 8 on AVR). Caps the number of simultaneously pending
+ *   Async.sleep / sleepUntil / yield operations.
+ */
+export declare function generateStaticAsyncRuntime(capacity: number): string;