@typecad/cuttlefish 0.1.0-alpha.1

package/dist/platform/async-runtime.d.ts

@@ -0,0 +1,8 @@
+import type { ProgramIR } from "../api/index.js";
+import type { PlatformContext } from "./../types.js";
+import type { RuntimePolyfillIR } from "../api/shared/index.js";
+/**
+ * Build a RuntimePolyfillIR for the async Promise runtime, if the program
+ * has async functions and the target architecture has stdlib support.
+ */
+export declare function buildAsyncRuntimePolyfill(program: ProgramIR, ctx: PlatformContext | undefined, target: string, queueCapacity?: number): RuntimePolyfillIR | null;

package/dist/platform/async-runtime.js

@@ -0,0 +1,26 @@
+import { getStdLibSupport, generatePromiseRuntime } from "../api/shared/index.js";
+/**
+ * Build a RuntimePolyfillIR for the async Promise runtime, if the program
+ * has async functions and the target architecture has stdlib support.
+ */
+export function buildAsyncRuntimePolyfill(program, ctx, target, queueCapacity) {
+    const hasAsync = program.functions.some(fn => fn.isAsync);
+    if (!hasAsync)
+        return null;
+    const architecture = ctx?.architecture;
+    const stdlib = getStdLibSupport(architecture);
+    if (!stdlib.hasVector || !stdlib.hasString)
+        return null;
+    return {
+        kind: "polyfill",
+        id: "async_runtime",
+        domain: "standard",
+        requiredIncludes: ["<functional>", "<vector>", "<utility>", "<string>"],
+        forwardDeclarations: [],
+        helperStructs: [generatePromiseRuntime(queueCapacity ?? 256)],
+        helperFunctions: [],
+        shimMacros: [],
+        dependencies: [],
+        hasPromiseRuntime: true,
+    };
+}

package/dist/platform/generic-strategy.d.ts

@@ -0,0 +1,101 @@
+import type { PlatformStrategy, AsyncRuntimeConfig } from "../api/shared/index.js";
+import type { ExpressionIR, ProgramIR } from "../api/index.js";
+import type { BoardConstants } from "../api/shared/index.js";
+import type { Diagnostic, PlatformContext } from "../types.js";
+import type { RuntimePolyfillIR, StdLibSupport } from "../api/shared/index.js";
+import type { GraphicsCapacity, DisplayHALOp } from "../api/shared/index.js";
+export declare class GenericStrategy implements PlatformStrategy {
+    readonly id = "generic";
+    private _largeEnumNames;
+    forcedIncludes(_program: ProgramIR, _ctx?: PlatformContext): string[];
+    symbolAliases(_program: ProgramIR, _ctx?: PlatformContext): Record<string, string>;
+    shimLines(_program: ProgramIR, _ctx?: PlatformContext): string[];
+    profileDiagnostics(_program: ProgramIR, _ctx?: PlatformContext): Diagnostic[];
+    sourceExtension(_isEntryFile: boolean, _isNpmPackage: boolean): string;
+    entrypointFunctionName(): string;
+    requiresLoopFunction(): boolean;
+    overrideBaseName(originalBaseName: string, _outDirBaseName: string, _isEntryFile: boolean, _isNpmPackage: boolean): string;
+    effectiveEmitMode(requestedMode: string, _isNpmPackage: boolean): string;
+    normalizeCppType(typeName: string): string;
+    defaultNumericType(): string;
+    mapReturnType(_functionName: string, returnType: string): string;
+    isStringLikeType(cppType: string): boolean;
+    isPointerType(cppType: string): boolean;
+    mapFunctionName(originalName: string): string;
+    normalizeRawExpression(value: string): string;
+    nullValue(): string;
+    wrapStringConcat(_leftRendered: string, _rightRendered: string, _leftIsString: boolean): string | undefined;
+    wrapStringObject(expr: string): string;
+    useSnprintfForStrings(): boolean;
+    renameEnumMember(_enumName: string, memberName: string): string;
+    setLargeEnumNames(names: ReadonlySet<string>): void;
+    enumCastType(enumName: string): string | undefined;
+    renderBoardDefinitionAccess(_chain: string[], _boardConstants?: BoardConstants): string | undefined;
+    renderThrow(valueExpr: string): string;
+    isConsoleCall(callee: string): boolean;
+    transformConsoleCall(method: string, renderedArgs: string, forHeader: boolean): string;
+    transformConsoleExpression(method: string, _renderedArgs: string): string | undefined;
+    objectFieldInitializer(_fieldValue: ExpressionIR, _renderExpr: (e: ExpressionIR) => string): string | undefined;
+    overrideClassFieldType(_fieldName: string, _normalizedType: string): string;
+    reservedNames(): ReadonlySet<string>;
+    passthroughMacroNames(): ReadonlySet<string>;
+    apiReservedEnumNames(): ReadonlySet<string>;
+    apiReservedEnumGuard(): string;
+    needsIostream(): boolean;
+    needsStdString(): boolean;
+    needsStdVector(): boolean;
+    needsStdExcept(): boolean;
+    needsStdFunction(): boolean;
+    mathHeader(): string;
+    cstringHeader(): string;
+    needsVectorOverload(): boolean;
+    needsLargeEnumUnderlying(): boolean;
+    renameStructField(fieldName: string): string;
+    structFieldInitializer(_fieldValue: ExpressionIR, _compiletimeVarNames: Set<string>, _renderExpr: (e: ExpressionIR) => string): string | undefined;
+    getAsyncRuntimeConfig(): AsyncRuntimeConfig;
+    generateNativePolyfills(program: ProgramIR, ctx?: PlatformContext): RuntimePolyfillIR[];
+    asyncLoopInjection(_taskVarNames: string[], config: AsyncRuntimeConfig): string[];
+    asyncLoopInjection(_taskVarNames: string[], hasPromiseRuntime: boolean): string[];
+    asyncDriverFunctionName(): string;
+    shouldSkipTypeAlias(_cppType: string): boolean;
+    emitDiagnostics(_emitMode: string): Diagnostic[];
+    currentTimeMillis(): string;
+    asyncQueueCapacity(): number;
+    outputSubdirectory(_baseName: string): string;
+    generateHeaderFile(): boolean;
+    enumApiGuard(_enumName: string): {
+        open: string;
+        close: string;
+    } | undefined;
+    getStdLibSupport(_architecture?: string): StdLibSupport;
+    generateDebugInitCode(): string[];
+    generateDebugBreakpointCode(params: {
+        fileName: string;
+        lineNum: number;
+        originalLine: string;
+        variables: Array<{
+            name: string;
+            isFunction?: boolean;
+        }>;
+        normalizedCondition?: string;
+    }): string[];
+    generateDebugLogpointCode(params: {
+        fileName: string;
+        lineNum: number;
+        parts: Array<{
+            type: 'text' | 'variable';
+            value: string;
+        }>;
+        variables: Array<{
+            name: string;
+            isFunction?: boolean;
+        }>;
+    }): string[];
+    resolveDisplayOp(_op: DisplayHALOp): {
+        code?: string;
+        expression?: string;
+    } | undefined;
+    supportedDisplayDrivers(): ReadonlySet<string>;
+    colorFormat(): "rgb565" | "rgb666" | "rgb888" | "mono";
+    graphicsCapacity(): GraphicsCapacity;
+}

package/dist/platform/generic-strategy.js

@@ -0,0 +1,289 @@
+// ---------------------------------------------------------------------------
+// GenericStrategy — standard C++ target (std::cout, main(), <cmath> …)
+// ---------------------------------------------------------------------------
+import { escapeCppStringLiteral } from "../utils/strings.js";
+import { DEFAULT_STDLIB_SUPPORT } from "../api/shared/index.js";
+import { parsedIsPointer } from "../api/shared/cpp-type-ir.js";
+import { buildAsyncRuntimePolyfill } from "./async-runtime.js";
+export class GenericStrategy {
+    constructor() {
+        this.id = "generic";
+        this._largeEnumNames = new Set();
+    }
+    // ── Profile ─────────────────────────────────────────────────────────────
+    forcedIncludes(_program, _ctx) {
+        return [];
+    }
+    symbolAliases(_program, _ctx) {
+        return {};
+    }
+    shimLines(_program, _ctx) {
+        return [];
+    }
+    profileDiagnostics(_program, _ctx) {
+        return [];
+    }
+    // ── File shape ──────────────────────────────────────────────────────────
+    sourceExtension(_isEntryFile, _isNpmPackage) {
+        return "cpp";
+    }
+    entrypointFunctionName() {
+        return "main";
+    }
+    requiresLoopFunction() {
+        return false;
+    }
+    overrideBaseName(originalBaseName, _outDirBaseName, _isEntryFile, _isNpmPackage) {
+        return originalBaseName;
+    }
+    effectiveEmitMode(requestedMode, _isNpmPackage) {
+        return requestedMode;
+    }
+    // ── Type normalisation ──────────────────────────────────────────────────
+    normalizeCppType(typeName) {
+        if (typeName === "auto")
+            return "int";
+        return typeName;
+    }
+    defaultNumericType() { return "int"; }
+    mapReturnType(_functionName, returnType) {
+        return this.normalizeCppType(returnType);
+    }
+    isStringLikeType(cppType) {
+        // Note: this is the platform-policy definition of "string-like" — kept as
+        // an exact set (std::string, const char*, char*) because platform overrides
+        // (Arduino's `String`, etc.) extend it with platform-specific types. The
+        // broader structural `parsedIsStringLike` is used at consumer sites that
+        // don't depend on platform policy.
+        return cppType === "std::string" || cppType === "const char*" || cppType === "char*";
+    }
+    isPointerType(cppType) {
+        return parsedIsPointer(cppType);
+    }
+    mapFunctionName(originalName) {
+        if (originalName === "__cuttlefish_entrypoint__")
+            return "main";
+        return originalName;
+    }
+    // ── Expression rendering ────────────────────────────────────────────────
+    normalizeRawExpression(value) {
+        return value;
+    }
+    nullValue() {
+        return "";
+    }
+    wrapStringConcat(_leftRendered, _rightRendered, _leftIsString) {
+        return undefined;
+    }
+    wrapStringObject(expr) {
+        return `std::to_string(${expr})`;
+    }
+    useSnprintfForStrings() {
+        // Native uses snprintf for string concatenation so that non-arithmetic
+        // values (enums, class instances) never hit std::to_string() and floats
+        // get JS-compatible formatting. This unifies native with the Arduino/AVR
+        // snprintf path; see inferFormatSpecifier for per-type format specifiers.
+        return true;
+    }
+    renameEnumMember(_enumName, memberName) {
+        return memberName;
+    }
+    setLargeEnumNames(names) {
+        this._largeEnumNames = names;
+    }
+    enumCastType(enumName) {
+        return undefined;
+    }
+    renderBoardDefinitionAccess(_chain, _boardConstants) {
+        return undefined;
+    }
+    // ── Statement rendering ─────────────────────────────────────────────────
+    renderThrow(valueExpr) {
+        return `throw ${valueExpr};`;
+    }
+    isConsoleCall(callee) {
+        return callee.startsWith("console.");
+    }
+    transformConsoleCall(method, renderedArgs, forHeader) {
+        const semi = forHeader ? "" : ";";
+        switch (method) {
+            case "log":
+            case "info":
+            case "debug":
+                return `std::cout << ${renderedArgs} << std::endl${semi}`;
+            case "error":
+                return `std::cerr << "[ERROR] " << ${renderedArgs} << std::endl${semi}`;
+            case "warn":
+                return `std::cerr << "[WARN] " << ${renderedArgs} << std::endl${semi}`;
+            case "readLine":
+            case "readCharacter":
+                return this.transformConsoleExpression(method, renderedArgs) + semi;
+            default:
+                return `std::cout << ${renderedArgs} << std::endl${semi}`;
+        }
+    }
+    transformConsoleExpression(method, _renderedArgs) {
+        switch (method) {
+            case 'readLine':
+                return '([]() -> std::string { std::string s; std::getline(std::cin, s); return s; })()';
+            case 'readCharacter':
+                return '([&]() -> char { std::cout << "> " << std::flush; return std::cin.get(); })()';
+            default:
+                return undefined;
+        }
+    }
+    objectFieldInitializer(_fieldValue, _renderExpr) {
+        return undefined;
+    }
+    overrideClassFieldType(_fieldName, _normalizedType) {
+        return _normalizedType;
+    }
+    // ── Name guards ─────────────────────────────────────────────────────────
+    reservedNames() {
+        return new Set();
+    }
+    passthroughMacroNames() {
+        return new Set();
+    }
+    apiReservedEnumNames() {
+        return new Set();
+    }
+    apiReservedEnumGuard() {
+        return "";
+    }
+    // ── Includes ────────────────────────────────────────────────────────────
+    needsIostream() { return true; }
+    needsStdString() { return true; }
+    needsStdVector() { return true; }
+    needsStdExcept() { return true; }
+    needsStdFunction() { return true; }
+    mathHeader() { return "<cmath>"; }
+    cstringHeader() { return "<cstring>"; }
+    needsVectorOverload() { return true; }
+    // ── Enum underlying type ────────────────────────────────────────────────
+    needsLargeEnumUnderlying() { return false; }
+    // ── Struct field handling ───────────────────────────────────────────────
+    renameStructField(fieldName) { return fieldName; }
+    structFieldInitializer(_fieldValue, _compiletimeVarNames, _renderExpr) {
+        return undefined;
+    }
+    // ── Async ───────────────────────────────────────────────────────────────
+    getAsyncRuntimeConfig() {
+        return {
+            queueCapacity: this.asyncQueueCapacity(),
+            scheduler: "microtask",
+            waitForPinEdge: "stub",
+            hasPromiseRuntime: true,
+            hasTimers: false,
+            requiredIncludes: ["<functional>", "<vector>", "<utility>", "<string>"],
+        };
+    }
+    generateNativePolyfills(program, ctx) {
+        const helpers = [];
+        const asyncRuntime = buildAsyncRuntimePolyfill(program, ctx, "generic", this.asyncQueueCapacity());
+        if (asyncRuntime)
+            helpers.push(asyncRuntime);
+        return helpers;
+    }
+    asyncLoopInjection(_taskVarNames, configOrBool) {
+        let hasPromiseRuntime;
+        if (typeof configOrBool === 'boolean') {
+            hasPromiseRuntime = configOrBool;
+        }
+        else {
+            hasPromiseRuntime = configOrBool.hasPromiseRuntime;
+        }
+        const lines = [];
+        if (hasPromiseRuntime)
+            lines.push("  cuttlefish_pump_microtasks();");
+        return lines;
+    }
+    asyncDriverFunctionName() { return "main"; }
+    // ── Type aliases ────────────────────────────────────────────────────────
+    shouldSkipTypeAlias(_cppType) { return false; }
+    // ── Diagnostics ─────────────────────────────────────────────────────────
+    emitDiagnostics(_emitMode) { return []; }
+    currentTimeMillis() {
+        return 'std::chrono::duration_cast<std::chrono::milliseconds>(std::chrono::steady_clock::now().time_since_epoch()).count()';
+    }
+    // ── Build configuration ─────────────────────────────────────────────────
+    asyncQueueCapacity() { return 256; }
+    outputSubdirectory(_baseName) { return ".build"; }
+    generateHeaderFile() { return true; }
+    enumApiGuard(_enumName) { return undefined; }
+    getStdLibSupport(_architecture) { return DEFAULT_STDLIB_SUPPORT; }
+    // ── Debug code generation ─────────────────────────────────────────────────
+    generateDebugInitCode() {
+        return [
+            '// === DEBUG: Initialize ===',
+            'std::cout << "TypeCAD Debug Mode Active" << std::endl;',
+            '// === END DEBUG INIT ===',
+            '',
+        ];
+    }
+    generateDebugBreakpointCode(params) {
+        const lines = [];
+        lines.push(`  // === BREAKPOINT: ${params.fileName}:${params.lineNum} ===`);
+        if (params.normalizedCondition) {
+            lines.push(`  if (${params.normalizedCondition}) {`);
+        }
+        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "━━━━━━━━━━━━━━━━━━━━━━━━━━━━" << std::endl;`);
+        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "BREAKPOINT: ${params.fileName}:${params.lineNum}" << std::endl;`);
+        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  ${params.originalLine.replace(/"/g, '\\"')}" << std::endl;`);
+        if (params.variables.length > 0) {
+            lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  Variables:" << std::endl;`);
+            for (const v of params.variables) {
+                if (v.isFunction) {
+                    lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  ${v.name} = [function]" << std::endl;`);
+                }
+                else {
+                    lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  ${v.name} = " << ${v.name} << std::endl;`);
+                }
+            }
+        }
+        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "━━━━━━━━━━━━━━━━━━━━━━━━━━━━" << std::endl;`);
+        if (params.normalizedCondition) {
+            lines.push(`  }`);
+        }
+        lines.push(`  // === END BREAKPOINT ===`);
+        return lines;
+    }
+    generateDebugLogpointCode(params) {
+        const lines = [];
+        lines.push(`  // === LOGPOINT: ${params.fileName}:${params.lineNum} ===`);
+        const parts = [`"[LOG ${params.fileName}:${params.lineNum}] "`];
+        for (const part of params.parts) {
+            if (part.type === 'text') {
+                parts.push(`"${escapeCppStringLiteral(part.value)}"`);
+            }
+            else {
+                const varExists = params.variables.some(v => v.name === part.value && !v.isFunction);
+                parts.push(varExists ? part.value : `"${escapeCppStringLiteral(part.value)}"`);
+            }
+        }
+        lines.push(`  std::cout << ${parts.join(' << ')} << std::endl;`);
+        lines.push(`  // === END LOGPOINT ===`);
+        return lines;
+    }
+    // ── Graphics (fallback) ────────────────────────────────────────────────
+    resolveDisplayOp(_op) {
+        // Generic target has no display hardware. Returning undefined lets the
+        // emitter fall back; if a UI is mounted against the generic target the
+        // mount-time validation should have already errored.
+        return undefined;
+    }
+    supportedDisplayDrivers() {
+        return new Set();
+    }
+    colorFormat() {
+        return "rgb565";
+    }
+    graphicsCapacity() {
+        return {
+            maxNodes: 256,
+            maxBindings: 64,
+            maxActiveTransitions: 32,
+            nodeStorage: "flash",
+        };
+    }
+}

package/dist/platform/index.d.ts

@@ -0,0 +1,4 @@
+export type { PlatformStrategy } from '../api/shared/index.js';
+export { GenericStrategy } from './generic-strategy.js';
+export { resolveStrategy, registerPlatformStrategy } from './registry.js';
+export type { RuntimePolyfillIR } from '../api/shared/index.js';

package/dist/platform/index.js

@@ -0,0 +1,9 @@
+// ---------------------------------------------------------------------------
+// Platform strategy exports
+//
+// Re-exports platform strategies for use within the CLI and by consumers.
+// Framework-specific strategies (e.g. ArduinoStrategy) are provided by their
+// respective framework packages, which register via registerPlatformStrategy().
+// ---------------------------------------------------------------------------
+export { GenericStrategy } from './generic-strategy.js';
+export { resolveStrategy, registerPlatformStrategy } from './registry.js';

package/dist/platform/registry.d.ts

@@ -0,0 +1,21 @@
+import type { PlatformStrategy } from "../api/shared/index.js";
+/**
+ * Register a custom platform strategy.  Framework packages call this from
+ * their entry point to override the default strategy for a target.
+ *
+ * @example
+ * // In @typecad/framework-arduino
+ * import { registerPlatformStrategy } from "@typecad/cuttlefish/platform/registry";
+ * registerPlatformStrategy(new ArduinoStrategy());
+ */
+export declare function registerPlatformStrategy(strategy: PlatformStrategy): void;
+/**
+ * Resolve a PlatformStrategy for the given target profile.
+ * Falls back to the "generic" strategy if no match is found.
+ */
+export declare function resolveStrategy(target: string): PlatformStrategy;
+/**
+ * Clear profile caches on all registered strategies.
+ * Should be called between transpilations to ensure fresh profile resolution.
+ */
+export declare function clearAllProfileCaches(): void;

package/dist/platform/registry.js

@@ -0,0 +1,42 @@
+// ---------------------------------------------------------------------------
+// Platform strategy registry
+//
+// Maps target profile strings to PlatformStrategy implementations.
+// Framework packages call `registerPlatformStrategy()` to plug in custom
+// strategies at import time.
+// ---------------------------------------------------------------------------
+import { GenericStrategy } from "./generic-strategy.js";
+const _genericStrategy = new GenericStrategy();
+const _registry = new Map([
+    ["generic", _genericStrategy],
+]);
+/**
+ * Register a custom platform strategy.  Framework packages call this from
+ * their entry point to override the default strategy for a target.
+ *
+ * @example
+ * // In @typecad/framework-arduino
+ * import { registerPlatformStrategy } from "@typecad/cuttlefish/platform/registry";
+ * registerPlatformStrategy(new ArduinoStrategy());
+ */
+export function registerPlatformStrategy(strategy) {
+    _registry.set(strategy.id, strategy);
+}
+/**
+ * Resolve a PlatformStrategy for the given target profile.
+ * Falls back to the "generic" strategy if no match is found.
+ */
+export function resolveStrategy(target) {
+    return _registry.get(target) ?? _registry.get("generic");
+}
+/**
+ * Clear profile caches on all registered strategies.
+ * Should be called between transpilations to ensure fresh profile resolution.
+ */
+export function clearAllProfileCaches() {
+    for (const strategy of _registry.values()) {
+        if (typeof strategy.clearProfileCache === "function") {
+            strategy.clearProfileCache();
+        }
+    }
+}

package/dist/platform/toolchain.d.ts

@@ -0,0 +1,4 @@
+import type { ToolchainOptions, CompileResult, UploadResult } from "../api/shared/index.js";
+export declare function compileSource(options: ToolchainOptions): CompileResult;
+export declare function uploadFirmware(options: ToolchainOptions): UploadResult;
+export declare function monitorDevice(options: ToolchainOptions): void;

package/dist/platform/toolchain.js

@@ -0,0 +1,43 @@
+// ---------------------------------------------------------------------------
+// Generic toolchain delegation
+//
+// Provides framework-agnostic compile/upload/monitor functions that delegate
+// to whatever toolchain the active framework provides.
+// ---------------------------------------------------------------------------
+import { getLoadedFramework, hasLoadedFramework } from "../framework-registry.js";
+import { loadFrameworkPackage } from "../framework-package.js";
+function getToolchain(fromDir, frameworkPackage) {
+    if (hasLoadedFramework()) {
+        const { toolchain } = getLoadedFramework();
+        if (toolchain)
+            return toolchain;
+    }
+    if (frameworkPackage) {
+        loadFrameworkPackage(frameworkPackage, fromDir);
+        if (hasLoadedFramework()) {
+            const { toolchain } = getLoadedFramework();
+            if (toolchain)
+                return toolchain;
+        }
+    }
+    throw new Error("No framework toolchain available. Specify a framework package in your TypeCAD config " +
+        "or ensure a framework with compile/upload support is installed.");
+}
+export function compileSource(options) {
+    const toolchain = getToolchain(options.outputDir);
+    return toolchain.compile(options);
+}
+export function uploadFirmware(options) {
+    const toolchain = getToolchain(options.outputDir);
+    if (!toolchain.upload) {
+        throw new Error("The active framework does not support upload.");
+    }
+    return toolchain.upload(options);
+}
+export function monitorDevice(options) {
+    const toolchain = getToolchain(options.outputDir);
+    if (!toolchain.monitor) {
+        throw new Error("The active framework does not support device monitoring.");
+    }
+    toolchain.monitor(options);
+}

package/dist/preview/client.d.ts

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