@typecad/cuttlefish 0.1.0-alpha.1

package/dist/types.d.ts

@@ -0,0 +1,217 @@
+import type { TargetProfile as CoreTargetProfile, PlatformContext as CorePlatformContext, SourceSpan as CoreSourceSpan, Diagnostic as CoreDiagnostic } from "./api/shared/index.js";
+export type EmitMode = "cpp" | "split";
+export type TargetProfile = CoreTargetProfile;
+export type PlatformContext = CorePlatformContext;
+export type SourceSpan = CoreSourceSpan;
+export interface SourceMapEntry {
+    generatedStartLine: number;
+    generatedStartColumn: number;
+    generatedEndLine: number;
+    generatedEndColumn: number;
+    tsSpan: SourceSpan;
+    nodeKind: string;
+    symbolName?: string;
+}
+export interface GeneratedSourceMap {
+    version: 1;
+    generatedFilePath: string;
+    sourceFilePath: string;
+    entries: SourceMapEntry[];
+}
+export interface MappedDiagnostic {
+    cppFilePath: string;
+    cppLine: number;
+    cppColumn: number;
+    message?: string;
+    mappedTsSpan?: SourceSpan;
+    nodeKind?: string;
+    symbolName?: string;
+}
+export type Diagnostic = CoreDiagnostic;
+export interface TreeShakingOptions {
+    /** Enable tree-shaking (default: true) */
+    enabled?: boolean;
+    /** Keep enums even if not referenced (default: false) */
+    keepUnusedEnums?: boolean;
+    /** Keep classes even if not instantiated (default: false) */
+    keepUnusedClasses?: boolean;
+    /** Keep type aliases even if not used (default: false) */
+    keepUnusedTypeAliases?: boolean;
+    /** Keep top-level variables even if not referenced (default: false) */
+    keepUnusedVariables?: boolean;
+    /** Generate diagnostics for removed code (default: true) */
+    reportUnused?: boolean;
+    /** Additional symbols to treat as entry points */
+    entryPoints?: string[];
+}
+export interface TranspileOptions {
+    inputFile: string;
+    outDir?: string;
+    emitMode: EmitMode;
+    target: TargetProfile;
+    emitMaps: boolean;
+    platformContext?: PlatformContext;
+    /** 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'`).
+     */
+    boardPackage?: 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.
+     * When not specified, the GenericStrategy (standard C++) is used.
+     */
+    frameworkPackage?: string;
+    /** Enable debug mode - inject breakpoint instrumentation */
+    debug?: boolean;
+    /** Skip TypeScript type-checking before transpilation (default: false) */
+    skipTypeCheck?: boolean;
+    /**
+     * Skip ESLint checks before transpilation (default: false).
+     * When false, ESLint errors in the user's `src/` abort the build, matching
+     * the type-check behavior. Mirrors `skipTypeCheck`.
+     */
+    skipLint?: boolean;
+    /**
+     * The user's project root — the directory containing `cuttlefish.config.ts`.
+     * The ESLint gate looks for `.cuttlefish/eslint.config.mjs` (or a root-level
+     * `eslint.config.mjs`) here, not under `src/`. When omitted, the entry file's
+     * directory is used as a fallback (suitable for ad-hoc API/test callers that
+     * pass a bare input file outside a configured project).
+     */
+    projectRoot?: string;
+    /**
+     * Force retranspilation of all files, ignoring incremental cache.
+     * Currently a no-op: incremental builds are disabled and every build already
+     * transpiles the full graph. Retained on the API for forward compatibility.
+     * (default: false)
+     */
+    force?: boolean;
+    /** Generate diagnostics.md and diagnostics.json reports (default: false) */
+    diagnostics?: boolean;
+    /** Display profile config from cuttlefish.config.ts */
+    display?: import("./api/shared/display-profile.js").DisplayConfig;
+}
+export interface LibraryDefinitionCondition {
+    target?: TargetProfile;
+    architecture?: string;
+    core?: string;
+    fqbnIncludes?: string;
+}
+interface LibraryDefinitionVariant {
+    when: LibraryDefinitionCondition;
+    include: string;
+    symbols?: Record<string, string>;
+}
+export interface LibraryDefinition {
+    module: string;
+    include: string;
+    symbols?: Record<string, string>;
+    variants?: LibraryDefinitionVariant[];
+}
+export interface CommandLineOptions {
+    command: "default" | "build" | "gen-libdefs" | "gen-decls" | "map-error" | "preview";
+    inputFile?: string;
+    emitMode: EmitMode;
+    target: TargetProfile;
+    outDir?: string;
+    emitMaps: boolean;
+    /** Skip transpilation (use existing generated files) */
+    noTranspile: boolean;
+    /** Compile using the framework toolchain after transpilation */
+    compile: boolean;
+    /** Upload using the framework toolchain after compilation (requires compile) */
+    upload: boolean;
+    /** Open serial monitor after upload */
+    monitor: boolean;
+    /** Serial port for upload and monitor (e.g. COM4 or /dev/ttyACM0) */
+    port?: string;
+    /** Baud rate for monitor (default: 9600) */
+    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;
+    /**
+     * Framework package for code generation strategy.
+     * Can be '@typecad/framework-arduino', '@typecad/framework-avr', or a custom path.
+     */
+    frameworkPackage?: string;
+    /** Enable debug mode - inject breakpoint instrumentation */
+    debug?: boolean;
+    /** Skip TypeScript type-checking before transpilation */
+    skipTypeCheck?: boolean;
+    /** Force retranspilation of all files, ignoring cache. Currently a no-op: incremental builds are disabled. */
+    force?: boolean;
+    /** Watch for file changes and retranspile automatically */
+    watch: boolean;
+    /** Run hardware tests via @typecad/expect */
+    expect?: boolean;
+    /** Optional test file path filter for --expect */
+    expectFile?: string;
+    /** Generate diagnostics.md and diagnostics.json reports */
+    diagnostics?: boolean;
+    /** Config file for preview command */
+    configPath?: string;
+    /** Project root (dir of cuttlefish.config.ts); passed to transpileFile for the ESLint gate. */
+    projectRoot?: string;
+}
+export interface GenerateLibdefOptions {
+    inputFile: string;
+    outDir: string;
+}
+export interface GeneratedOutputs {
+    headerPath?: string;
+    sourcePath: string;
+    headerMapPath?: string;
+    sourceMapPath?: string;
+    diagnostics: Diagnostic[];
+    asyncTaskNames?: string[];
+    usesTimers?: boolean;
+}
+interface CompileErrorEntry {
+    filePath: string;
+    line: number;
+    column: number;
+    severity: "error" | "warning" | "note";
+    message: string;
+}
+export interface CompileResultType {
+    success: boolean;
+    output: string;
+    errors: CompileErrorEntry[];
+}
+export interface UploadResultType {
+    success: boolean;
+    output: string;
+}
+export interface CreateCommandOptions {
+    command: "create";
+    projectName?: string;
+    /** @deprecated Use target */
+    board?: string;
+    target?: string;
+    framework?: string;
+    baud?: number;
+    noSketch?: boolean;
+    outDir?: string;
+}
+export interface BoardAddCommandOptions {
+    command: "board-add";
+    specPath: string;
+    force?: boolean;
+}
+export {};

package/dist/types.js

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

package/dist/ui/ui-bridge.d.ts

@@ -0,0 +1,4 @@
+/** Dynamically load @typecad/ui/engine and register the hook.
+ *  Called by transpile.ts at the start of each transpile run.
+ *  Safe to call when @typecad/ui is absent (hook stays null). */
+export declare function loadUIEngine(): Promise<void>;

package/dist/ui/ui-bridge.js

@@ -0,0 +1,34 @@
+// ---------------------------------------------------------------------------
+// UI bridge — loads the UI engine from @typecad/ui and registers it.
+//
+// transpile.ts calls loadUIEngine() at the start of transpileFile(). If
+// @typecad/ui is not installed, the import fails gracefully and the hook
+// stays null — cuttlefish works as a pure TypeScript→C++ transpiler.
+// ---------------------------------------------------------------------------
+import { setUIHook } from "../ui-hook.js";
+let loaded = false;
+/** Dynamically load @typecad/ui/engine and register the hook.
+ *  Called by transpile.ts at the start of each transpile run.
+ *  Safe to call when @typecad/ui is absent (hook stays null). */
+export async function loadUIEngine() {
+    if (loaded)
+        return;
+    loaded = true;
+    try {
+        // Dynamic import — @typecad/ui is optional. The module specifier is
+        // routed through a variable (rather than a string literal) so tsc types
+        // the result as `any` and never resolves @typecad/ui's declaration
+        // files while type-checking this file. A literal specifier here would
+        // make tsc load ui's dist/engine-index.d.ts, which imports back
+        // `@typecad/cuttlefish/ui-hook` — a self-referencing package path that
+        // resolves into this package's own dist/ output and causes TS5055
+        // ("would overwrite input file") on every rebuild where dist/ exists.
+        const uiEnginePath = "@typecad/ui/engine";
+        const engine = await import(uiEnginePath);
+        const hook = engine.registerTranspilerUI();
+        setUIHook(hook);
+    }
+    catch {
+        // @typecad/ui is not installed — cuttlefish works without UI support.
+    }
+}

package/dist/ui-hook.d.ts

@@ -0,0 +1,84 @@
+import type { Diagnostic } from "./api/shared/index.js";
+export interface LoweredUI {
+    fontTables: string;
+    nodeTable: string;
+    transitionTable: string;
+    typeDecl: string;
+    keyboardLoaders: string;
+    keyboardDispatch: string;
+    screenCount: number;
+    imageTables: string;
+    keyframeTables: string;
+    scrollMemoryDiagnostics: Diagnostic[];
+    diagnostics: Diagnostic[];
+}
+export interface UIModule {
+    htmlPath: string;
+    typeDeclPath: string;
+    typeDeclSourceRoot: string;
+    typeDeclRoot: string;
+    styled: unknown;
+    allStyledScreens: unknown[];
+    keyboards: unknown[];
+    rules: unknown[];
+    fontFaces: unknown[];
+    fontAssets: unknown[];
+    rawKeyframes: unknown[];
+    diagnostics: Diagnostic[];
+    mountDiagnostics: Diagnostic[];
+}
+export interface LowerOptions {
+    colorFormat: "rgb565" | "rgb666" | "rgb888" | "mono";
+    storage: "progmem" | "flash";
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+export interface UiFileParts {
+    script: string;
+    style: string;
+    html: string;
+}
+/** The capabilities cuttlefish core needs from the UI engine. */
+export interface TranspilerUIHook {
+    resetUIRegistry(): void;
+    loadUIModule(htmlPath: string): UIModule | undefined;
+    loadUIModuleFromText(htmlPath: string, htmlText: string, cssText: string, cssPathForFonts?: string): UIModule;
+    getUIModule(htmlPath: string): UIModule | undefined;
+    hasUIModule(htmlPath: string): boolean;
+    allUIModules(): UIModule[];
+    allLoweredUIModules(): Array<{
+        htmlPath: string;
+        lowered: LoweredUI;
+    }>;
+    markEntryHasUI(): void;
+    entryHasUI(): boolean;
+    clearEntryHasUI(): void;
+    lowerOnMount(htmlPath: string, opts: LowerOptions): LoweredUI;
+    resolveColor(input: string, format: "rgb565" | "rgb666" | "rgb888" | "mono"): number;
+    resolveColorInternal(input: string, format: "rgb565" | "rgb666" | "rgb888" | "mono"): number;
+    emitRuntimeHeader(): string;
+    splitUiFile(src: string): UiFileParts;
+    generateProjectUITypeDeclarations(projectRoot: string): {
+        written: string[];
+        errors: Array<{
+            filePath: string;
+            error: Error;
+        }>;
+    };
+    analyzeScrollMemory(styled: unknown, budget: number): Diagnostic[];
+}
+/** Set the UI hook. Called by transpile.ts after dynamically loading
+ *  @typecad/ui/engine. Passing null clears it (end of transpile run). */
+export declare function setUIHook(hook: TranspilerUIHook | null): void;
+/** Get the current UI hook, or null if @typecad/ui is not loaded. */
+export declare function getUIHook(): TranspilerUIHook | null;
+/** Returns true if the UI hook is registered (i.e. @typecad/ui is loaded). */
+export declare function hasUIHook(): boolean;
+/** Get the UI hook, throwing if it's not set. Use in code paths that are
+ *  only reached when UI is active (e.g. inside `if (entryHasUI())` blocks). */
+export declare function requireUIHook(): TranspilerUIHook;
+/** Returns true if the entry point has UI mounted. Safe to call when the
+ *  hook is not set (returns false — no UI without the engine). */
+export declare function entryHasUI(): boolean;

package/dist/ui-hook.js

@@ -0,0 +1,45 @@
+// ---------------------------------------------------------------------------
+// TranspilerUIHook — the contract between cuttlefish core and the (optional)
+// @typecad/ui package's transpiler engine.
+//
+// Cuttlefish core never statically imports from @typecad/ui. Instead, when UI
+// usage is detected in user code, transpile.ts dynamically imports
+// @typecad/ui/engine and calls its registerTranspilerUI() function, which
+// returns an object implementing this interface. Core code then calls through
+// getUIHook() instead of importing ui/ modules directly.
+//
+// When @typecad/ui is not installed, the hook stays null and UI processing is
+// skipped — cuttlefish works as a pure TypeScript→C++ transpiler.
+// ---------------------------------------------------------------------------
+// ── Module-level hook state ────────────────────────────────────────────────
+let uiHook = null;
+/** Set the UI hook. Called by transpile.ts after dynamically loading
+ *  @typecad/ui/engine. Passing null clears it (end of transpile run). */
+export function setUIHook(hook) {
+    uiHook = hook;
+}
+/** Get the current UI hook, or null if @typecad/ui is not loaded. */
+export function getUIHook() {
+    return uiHook;
+}
+/** Returns true if the UI hook is registered (i.e. @typecad/ui is loaded). */
+export function hasUIHook() {
+    return uiHook !== null;
+}
+/** Get the UI hook, throwing if it's not set. Use in code paths that are
+ *  only reached when UI is active (e.g. inside `if (entryHasUI())` blocks). */
+export function requireUIHook() {
+    if (!uiHook) {
+        throw new Error("UI hook is not registered. This code path requires @typecad/ui to be " +
+            "installed and loaded. This should not happen — the hook is set at the " +
+            "start of transpileFile() when UI is detected.");
+    }
+    return uiHook;
+}
+// ── Convenience accessors for the most common queries ──────────────────────
+// These wrap the null-check so call sites stay clean.
+/** Returns true if the entry point has UI mounted. Safe to call when the
+ *  hook is not set (returns false — no UI without the engine). */
+export function entryHasUI() {
+    return uiHook !== null && uiHook.entryHasUI();
+}

package/dist/utils/cli.d.ts

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