@typecad/cuttlefish 0.1.0-alpha.1

package/dist/api/shared/promise-runtime.js

@@ -0,0 +1,244 @@
+// ---------------------------------------------------------------------------
+// Shared Promise runtime C++ code generator
+//
+// Generates a cooperative microtask queue + minimal Promise<T> runtime
+// for embedded C++ targets. Used by both the generic transpiler strategy
+// and the Arduino framework strategy.
+//
+// Functions named __typecad_async_* and __cuttlefish_wait_pin_edge are the
+// runtime implementations that the HAL Async module's emit() calls resolve to.
+// They are defined inside the typecad_async namespace (to see Promise<T> and
+// enqueueMicrotask), and also have unscoped global aliases so the emitted
+// C++ code can call them directly.
+// ---------------------------------------------------------------------------
+/**
+ * Generate the cooperative microtask queue + minimal Promise runtime for C++.
+ *
+ * @param queueCapacity Maximum number of pending microtasks in the queue.
+ *   Use a smaller value (e.g. 32) for memory-constrained targets like AVR,
+ *   and a larger value (e.g. 256) for targets with more RAM.
+ * @param includeWaitForPinEdge Whether to include the `waitForPinEdge` stub
+ *   (used by Arduino targets).
+ */
+export function generatePromiseRuntime(queueCapacity, includeWaitForPinEdge = false) {
+    const waitForPinEdge = includeWaitForPinEdge ? `
+  // HAL-level wait for pin edge — polling-based implementation.
+  // Detects an actual transition (idle→target), not just the current level.
+  // Uses a two-phase approach: phase 1 waits for the idle level, phase 2 waits
+  // for the target level (the edge). Each phase re-enqueues on the microtask
+  // queue so other tasks can run between polls.
+  inline Promise<void> __cuttlefish_wait_pin_edge(int pin, int mode, long timeout) {
+    return Promise<void>([pin, mode, timeout](std::function<void(const void*)> resolve, std::function<void(const std::string&)> reject) {
+      int targetState = (mode == RISING) ? HIGH : LOW;
+      int idleState = (mode == RISING) ? LOW : HIGH;
+      unsigned long start = millis();
+      // Phase 2 poller: waits for the pin to reach the target state (the edge).
+      auto pollTarget = [pin, targetState, timeout, start, resolve]() {
+        if (digitalRead(pin) == targetState) {
+          resolve(nullptr);
+        } else if (timeout >= 0 && (millis() - start >= (unsigned long)timeout)) {
+          resolve(nullptr);
+        } else {
+          enqueueMicrotask([pin, targetState, timeout, start, resolve]() {
+            if (digitalRead(pin) == targetState) {
+              resolve(nullptr);
+            } else if (timeout >= 0 && (millis() - start >= (unsigned long)timeout)) {
+              resolve(nullptr);
+            } else {
+              enqueueMicrotask([pin, targetState, timeout, start, resolve]() {});
+            }
+          });
+        }
+      };
+      // Phase 1: wait for idle state before watching for the edge.
+      enqueueMicrotask([pin, idleState, timeout, start, resolve, pollTarget]() {
+        if (digitalRead(pin) == idleState) {
+          pollTarget();
+        } else if (timeout >= 0 && (millis() - start >= (unsigned long)timeout)) {
+          resolve(nullptr);
+        } else {
+          enqueueMicrotask([pin, idleState, timeout, start, resolve, pollTarget]() {});
+        }
+      });
+    });
+  }
+` : "";
+    return `
+// Cooperative microtask queue + minimal Promise runtime
+namespace typecad_async {
+  using Microtask = std::function<void()>;
+
+  class MicrotaskQueue {
+  public:
+    static MicrotaskQueue& instance() {
+      static MicrotaskQueue queue;
+      return queue;
+    }
+
+    bool enqueue(Microtask task) {
+      if (_queue.size() >= ${queueCapacity}) {
+        return false;
+      }
+      _queue.push_back(std::move(task));
+      return true;
+    }
+
+    void pump() {
+      const size_t total = _queue.size();
+      for (size_t i = 0; i < total; ++i) {
+        Microtask task = std::move(_queue[i]);
+        task();
+      }
+      if (total > 0) {
+        _queue.erase(_queue.begin(), _queue.begin() + static_cast<long long>(total));
+      }
+    }
+
+  private:
+    std::vector<Microtask> _queue;
+  };
+
+  inline void enqueueMicrotask(Microtask task) {
+    MicrotaskQueue::instance().enqueue(std::move(task));
+  }
+
+  inline void pumpMicrotasks() {
+    MicrotaskQueue::instance().pump();
+  }
+
+  template <typename T>
+  class Promise {
+  public:
+    enum class State { Pending, Fulfilled, Rejected };
+
+    Promise() : _state(State::Pending), _value{}, _error{} {}
+
+    explicit Promise(std::function<void(std::function<void(const T&)>, std::function<void(const std::string&)>)> executor)
+      : _state(State::Pending), _value{}, _error{} {
+      executor(
+        [this](const T& value) { this->resolve(value); },
+        [this](const std::string& error) { this->reject(error); }
+      );
+    }
+
+    static Promise<T> resolveValue(const T& value) {
+      Promise<T> promise;
+      promise.resolve(value);
+      return promise;
+    }
+
+    static Promise<T> rejectValue(const std::string& error) {
+      Promise<T> promise;
+      promise.reject(error);
+      return promise;
+    }
+
+    void resolve(const T& value) {
+      if (_state != State::Pending) return;
+      _state = State::Fulfilled;
+      _value = value;
+      auto callbacks = _onFulfilled;
+      enqueueMicrotask([callbacks, value]() mutable {
+        for (auto& callback : callbacks) { callback(value); }
+      });
+    }
+
+    void reject(const std::string& error) {
+      if (_state != State::Pending) return;
+      _state = State::Rejected;
+      _error = error;
+      auto callbacks = _onRejected;
+      enqueueMicrotask([callbacks, error]() mutable {
+        for (auto& callback : callbacks) { callback(error); }
+      });
+    }
+
+    Promise<T>& then(std::function<void(const T&)> onFulfilled) {
+      if (_state == State::Fulfilled) {
+        const T value = _value;
+        enqueueMicrotask([onFulfilled, value]() mutable { onFulfilled(value); });
+      } else if (_state == State::Pending) {
+        _onFulfilled.push_back(std::move(onFulfilled));
+      }
+      return *this;
+    }
+
+    Promise<T>& catchError(std::function<void(const std::string&)> onRejected) {
+      if (_state == State::Rejected) {
+        const std::string error = _error;
+        enqueueMicrotask([onRejected, error]() mutable { onRejected(error); });
+      } else if (_state == State::Pending) {
+        _onRejected.push_back(std::move(onRejected));
+      }
+      return *this;
+    }
+
+  private:
+    State _state;
+    T _value;
+    std::string _error;
+    std::vector<std::function<void(const T&)>> _onFulfilled;
+    std::vector<std::function<void(const std::string&)>> _onRejected;
+  };
+
+  // ── HAL-level implementations (inside namespace so they see Promise<T> and enqueueMicrotask) ──
+
+  // Async.sleep() — cooperative delay using millis polling
+  inline Promise<void> __cuttlefish_async_sleep(unsigned long ms) {
+    return Promise<void>([ms](std::function<void(const void*)> resolve, std::function<void(const std::string&)> reject) {
+      unsigned long start = millis();
+      if (millis() - start >= ms) {
+        resolve(nullptr);
+      } else {
+        enqueueMicrotask([ms, start, resolve]() {
+          if (millis() - start >= ms) {
+            resolve(nullptr);
+          } else {
+            enqueueMicrotask([ms, start, resolve]() { /* will be re-checked next cycle */ });
+          }
+        });
+      }
+    });
+  }
+
+  // Async.yield() — defer to next microtask pump cycle
+  inline Promise<void> __cuttlefish_async_yield() {
+    return Promise<void>([](std::function<void(const void*)> resolve, std::function<void(const std::string&)> reject) {
+      enqueueMicrotask([resolve]() { resolve(nullptr); });
+    });
+  }
+
+  // Async.sleepUntil() — poll condition every interval ms
+  inline Promise<void> __cuttlefish_async_sleep_until(unsigned long pollIntervalMs) {
+    return Promise<void>([pollIntervalMs](std::function<void(const void*)> resolve, std::function<void(const std::string&)> reject) {
+      unsigned long start = millis();
+      enqueueMicrotask([pollIntervalMs, start, resolve]() {
+        if (millis() - start >= pollIntervalMs) {
+          resolve(nullptr);  // caller re-checks condition
+        } else {
+          enqueueMicrotask([pollIntervalMs, start, resolve]() { /* re-check next cycle */ });
+        }
+      });
+    });
+  }
+
+  // Async.currentTask() — return task description string
+  inline const char* __cuttlefish_async_current_task() {
+    return "main";
+  }
+
+${waitForPinEdge}
+} // namespace typecad_async
+
+// ── Global-scope aliases so HAL emit() calls resolve ──
+using typecad_async::__cuttlefish_async_sleep;
+using typecad_async::__cuttlefish_async_yield;
+using typecad_async::__cuttlefish_async_sleep_until;
+using typecad_async::__cuttlefish_async_current_task;
+${includeWaitForPinEdge ? `using typecad_async::__cuttlefish_wait_pin_edge;` : ``}
+
+inline void cuttlefish_pump_microtasks() {
+  typecad_async::pumpMicrotasks();
+}
+`;
+}

package/dist/api/shared/snprintf-types.d.ts

@@ -0,0 +1,29 @@
+export interface KnownVariableInfo {
+    cppType: string;
+    floatPrecision?: number;
+    /**
+     * The initializer expression for `auto`-deduced locals, retained so the
+     * snprintf specifier picker can infer the real C++ type (e.g. resolve
+     * `const name = loot.name` to `std::string` even though the decl emits as
+     * `auto`). Undefined for explicitly-typed decls and parameters.
+     */
+    initializer?: import('./ir-core.js').ExpressionIR;
+}
+export interface SnprintfArgRenderResult {
+    format: string;
+    arg: string;
+    estimatedLength: number;
+    preludeLines: string[];
+}
+export interface SnprintfRenderResult {
+    formatString: string;
+    args: string[];
+    estimatedLength: number;
+    preludeLines: string[];
+}
+export interface EmissionScopeState {
+    readonly knownVariableTypes: Map<string, KnownVariableInfo>;
+    readonly snprintfBuffers: Set<string>;
+    nextSnprintfTempId: number;
+}
+export type SnprintfExpressionRenderer = (expr: import('./ir-core.js').ExpressionIR) => string;

package/dist/api/shared/snprintf-types.js

@@ -0,0 +1,8 @@
+// ---------------------------------------------------------------------------
+// Snprintf types for emission scope state and render results
+//
+// These types describe the data structures used by the snprintf-based
+// template literal lowering system. Defined here so both CLI and framework
+// packages can reference them without a circular dependency.
+// ---------------------------------------------------------------------------
+export {};

package/dist/api/shared/string-method-registry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Argument shape for a string method, determining how the call is rewritten.
+ * - `receiverOnly`: no args, e.g. `s.toUpperCase()`
+ * - `unary`:        one arg,   e.g. `s.charAt(2)`
+ * - `binary`:       two args,  e.g. `s.substring(0, 2)`
+ * - `unaryDefault`: one-arg form that has a default (e.g. padStart),
+ *                    emitted via a `_default` helper variant
+ */
+export type StringMethodArgForm = "receiverOnly" | "unary" | "binary" | "unaryDefault";
+export interface StringMethodSpec {
+    /** The exact `__tc_*` helper name emitted for this form (e.g. `__tc_substring2`). */
+    helper: string;
+    argForm: StringMethodArgForm;
+    /**
+     * The JS method name this spec lowers. Defaults to the helper name with the
+     * `__tc_` prefix and any trailing arity suffix (`1`/`2`) stripped.
+     */
+    methodName?: string;
+}
+/**
+ * Ordered table of JS string methods → `__tc_*` lowering specs.
+ * Order matters: 2-arg (binary) forms MUST precede their 1-arg (unary)
+ * counterparts so that `substring(0, 2)` isn't partially matched by the
+ * 1-arg rule first. Each spec names the EXACT helper for its arity.
+ */
+export declare const STRING_METHODS: StringMethodSpec[];
+/**
+ * The set of JS string-method names this registry knows how to lower.
+ * Used by program analysis to detect which polyfill helpers are needed.
+ */
+export declare const STRING_METHOD_NAMES: ReadonlySet<string>;
+/**
+ * Apply all string-method rewrites to a raw C++ expression string.
+ *
+ * This is the shared lowering that both the native and Arduino strategies
+ * call from their `normalizeRawExpression()`. Each strategy may perform
+ * additional platform-specific rewrites (pin modes, HAL, etc.) before/after.
+ *
+ * The `options.receiverWrapper` lets a strategy wrap the receiver when it
+ * becomes a helper argument — e.g. Arduino wraps `indexOf` receivers in
+ * `__tc_str_ptr(...)`. Methods listed in `options.special` are replaced
+ * entirely (Arduino uses `strstr`/`strncmp` for `includes`/`startsWith`).
+ */
+export declare function applyStringMethodRewrites(value: string, options?: {
+    /** Methods whose helper the receiver should be wrapped in (e.g. indexOf → __tc_str_ptr). */
+    wrapReceiverFor?: ReadonlySet<string>;
+    /**
+     * Per-method custom rewrites that bypass the standard helper form.
+     * Keyed by JS method name → function(receiver, args[]) returning the
+     * replacement string, or undefined to fall back to the standard form.
+     */
+    special?: Record<string, (receiver: string, args: string[]) => string | undefined>;
+}): string;

package/dist/api/shared/string-method-registry.js

@@ -0,0 +1,168 @@
+// ---------------------------------------------------------------------------
+// Shared string-method lowering registry
+//
+// Single source of truth for rewriting JS string method calls
+// (`s.toUpperCase()`, `s.substring(0, 2)`, …) into the `__tc_*` C++ helper
+// calls that both the native and Arduino/AVR strategies emit.
+//
+// Both platform strategies previously maintained their own (drifting) regex
+// tables inside normalizeRawExpression(). The native table additionally had a
+// latent bug: its receiver-capture group `R` used nested capturing groups,
+// which shifted the backreferences and caused methods like substring/slice/
+// charCodeAt to emit the receiver twice and drop an argument
+// (e.g. `frame.substring(0, 2)` → `__tc_substring2(frame, frame, 0)`).
+//
+// This module centralises the lowering with a receiver pattern that captures
+// the receiver as a single group, fixing that bug for every target.
+// ---------------------------------------------------------------------------
+/**
+ * Derive the JS method name from a helper name: strip `__tc_`, then strip a
+ * trailing `_default` or arity digit (so `__tc_substring2` → `substring`,
+ * `__tc_padStart_default` → `padStart`).
+ */
+function methodNameFromHelper(helper) {
+    return helper.replace(/^__tc_/, "").replace(/_default$/, "").replace(/\d+$/, "");
+}
+/**
+ * Ordered table of JS string methods → `__tc_*` lowering specs.
+ * Order matters: 2-arg (binary) forms MUST precede their 1-arg (unary)
+ * counterparts so that `substring(0, 2)` isn't partially matched by the
+ * 1-arg rule first. Each spec names the EXACT helper for its arity.
+ */
+export const STRING_METHODS = [
+    // ── No-arg methods (receiver only) ───────────────────────────────────────
+    { helper: "__tc_toUpperCase", argForm: "receiverOnly" },
+    { helper: "__tc_toLowerCase", argForm: "receiverOnly" },
+    { helper: "__tc_trim", argForm: "receiverOnly" },
+    // ── Two-arg methods (must precede 1-arg forms) ───────────────────────────
+    { helper: "__tc_substring2", argForm: "binary" },
+    { helper: "__tc_slice2", argForm: "binary" },
+    { helper: "__tc_padStart", argForm: "binary" },
+    { helper: "__tc_padEnd", argForm: "binary" },
+    { helper: "__tc_replace", argForm: "binary" },
+    // ── One-arg methods ──────────────────────────────────────────────────────
+    { helper: "__tc_substring1", argForm: "unary" },
+    { helper: "__tc_slice1", argForm: "unary" },
+    { helper: "__tc_padStart_default", argForm: "unaryDefault" },
+    { helper: "__tc_padEnd_default", argForm: "unaryDefault" },
+    { helper: "__tc_charAt", argForm: "unary" },
+    { helper: "__tc_charCodeAt", argForm: "unary" },
+    { helper: "__tc_endsWith", argForm: "unary" },
+    { helper: "__tc_startsWith", argForm: "unary" },
+    { helper: "__tc_includes", argForm: "unary" },
+    { helper: "__tc_indexOf", argForm: "unary" },
+    { helper: "__tc_lastIndexOf", argForm: "unary" },
+    { helper: "__tc_repeat", argForm: "unary" },
+    { helper: "__tc_split", argForm: "unary" },
+    // NOTE: `__tc_join` is intentionally NOT in this table. `.join(sep)` is a
+    // std::VECTOR method (it returns a std::string built from the vector's
+    // elements), NOT a std::string method. Listing it here previously caused
+    // `parts.join(' ')` on a `mutableArrayVars` receiver (a string[] built via
+    // .push) to fall through BOTH lowering paths: `shouldLowerAsStringMethod`
+    // returns false for a known array (correct), and the vector-method table
+    // `VECTOR_VALUE_METHOD_LOWERINGS` had no `join` entry, so the call was
+    // emitted verbatim (`parts.join(" ")`) and g++ rejected it ("no member
+    // named 'join'"). `join` is now lowered in the VECTOR path
+    // (ir/transformers/array-methods.ts), and the polyfill helper is still
+    // registered via POLYFILL_HELPER_MAP['.join(']. Demo #31 Finding B.
+];
+/** JS method name → spec (for the names set). */
+const STRING_METHOD_BY_NAME = new Map();
+for (const spec of STRING_METHODS) {
+    const name = spec.methodName ?? methodNameFromHelper(spec.helper);
+    STRING_METHOD_BY_NAME.set(name, spec);
+}
+/**
+ * The set of JS string-method names this registry knows how to lower.
+ * Used by program analysis to detect which polyfill helpers are needed.
+ */
+export const STRING_METHOD_NAMES = new Set(STRING_METHOD_BY_NAME.keys());
+/**
+ * Receiver-capture pattern shared across targets. Captures the receiver as
+ * group 1 (the ONLY group before the method arguments), so backreferences for
+ * arguments always start at $2.
+ *
+ * The outer group is CAPTURING (so it is $1); the inner alternation between
+ * `std::string(...)` and identifier-chains is NON-capturing so it does not
+ * shift the group numbering. (The old native `R` pattern used a nested
+ * capturing alternation, which shifted backreferences and caused the
+ * receiver to be emitted twice — the substring/slice/charCodeAt bug.)
+ *
+ * Matches:
+ *  - `std::string(...)` constructor calls, or
+ *  - an identifier optionally followed by `.member` chains.
+ */
+const RECEIVER_PATTERN = "((?:std::string\\([^)]*\\)|(?:[A-Za-z_]\\w*(?:\\.[A-Za-z_]\\w*)*)))";
+/**
+ * Apply all string-method rewrites to a raw C++ expression string.
+ *
+ * This is the shared lowering that both the native and Arduino strategies
+ * call from their `normalizeRawExpression()`. Each strategy may perform
+ * additional platform-specific rewrites (pin modes, HAL, etc.) before/after.
+ *
+ * The `options.receiverWrapper` lets a strategy wrap the receiver when it
+ * becomes a helper argument — e.g. Arduino wraps `indexOf` receivers in
+ * `__tc_str_ptr(...)`. Methods listed in `options.special` are replaced
+ * entirely (Arduino uses `strstr`/`strncmp` for `includes`/`startsWith`).
+ */
+export function applyStringMethodRewrites(value, options = {}) {
+    const wrapReceiverFor = options.wrapReceiverFor ?? new Set();
+    const special = options.special ?? {};
+    let v = value;
+    let prev = "";
+    // Loop because one rewrite can expose another (e.g. chained calls). Bound
+    // to avoid infinite loops: each pass either changes the string or stops.
+    let guard = 0;
+    while (prev !== v && guard < 8) {
+        prev = v;
+        guard++;
+        for (const spec of STRING_METHODS) {
+            const name = spec.methodName ?? methodNameFromHelper(spec.helper);
+            v = rewriteMethod(v, name, spec, wrapReceiverFor, special);
+        }
+    }
+    return v;
+}
+/** Rewrite a single method name according to its spec. */
+function rewriteMethod(v, name, spec, wrapReceiverFor, special) {
+    const R = RECEIVER_PATTERN;
+    const wrap = (recv) => wrapReceiverFor.has(name) ? `__tc_str_ptr(${recv})` : recv;
+    if (spec.argForm === "receiverOnly") {
+        // s.name() → __tc_name(s)
+        const re = new RegExp(`${R}\\.${escapeRegex(name)}\\(\\)`, "g");
+        v = v.replace(re, (_m, receiver) => {
+            const custom = special[name]?.(receiver, []);
+            return custom ?? `${spec.helper}(${wrap(receiver)})`;
+        });
+        return v;
+    }
+    if (spec.argForm === "unary") {
+        // s.name(arg) → __tc_name(s, arg)
+        const re = new RegExp(`${R}\\.${escapeRegex(name)}\\(([^)]+)\\)`, "g");
+        v = v.replace(re, (_m, receiver, arg) => {
+            const custom = special[name]?.(receiver, [arg]);
+            return custom ?? `${spec.helper}(${wrap(receiver)}, ${arg})`;
+        });
+        return v;
+    }
+    if (spec.argForm === "binary") {
+        // s.name(a, b) → __tc_nameN(s, a, b). The helper name carries the arity
+        // suffix already (e.g. __tc_substring2, __tc_slice2).
+        const re = new RegExp(`${R}\\.${escapeRegex(name)}\\(([^,]+),\\s*([^)]+)\\)`, "g");
+        v = v.replace(re, (_m, receiver, a, b) => {
+            const custom = special[name]?.(receiver, [a, b]);
+            return custom ?? `${spec.helper}(${wrap(receiver)}, ${a}, ${b})`;
+        });
+        return v;
+    }
+    // unaryDefault: s.name(arg) → __tc_name_default(s, arg)
+    const re = new RegExp(`${R}\\.${escapeRegex(name)}\\(([^)]+)\\)`, "g");
+    v = v.replace(re, (_m, receiver, arg) => {
+        const custom = special[name]?.(receiver, [arg]);
+        return custom ?? `${spec.helper}(${wrap(receiver)}, ${arg})`;
+    });
+    return v;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/api/shared/toolchain-types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Compile error structure
+ */
+export interface CompileError {
+    filePath: string;
+    line: number;
+    column: number;
+    severity: "error" | "warning" | "note";
+    message: string;
+}
+/**
+ * Memory usage details
+ */
+export interface MemoryUsage {
+    flashUsed?: number;
+    flashTotal?: number;
+    ramUsed?: number;
+    ramTotal?: number;
+}
+/**
+ * Generic compile options bag. Each framework reads what it needs
+ * and ignores the rest. The CLI populates whichever fields are
+ * available from CLI flags and config.
+ */
+export interface ToolchainOptions {
+    outputDir: string;
+    sourcePath: string;
+    buildTarget?: string;
+    port?: string;
+    baud?: number;
+    optimize?: string;
+    extraFlags?: string[];
+    defines?: Record<string, string>;
+    /**
+     * Framework-specific config from `cuttlefish.config.ts`.
+     * Each framework casts this to its own typed interface.
+     */
+    frameworkConfig?: Record<string, unknown>;
+}
+/**
+ * Generic compile result. All frameworks return this shape.
+ */
+export interface CompileResult {
+    success: boolean;
+    output: string;
+    errors: CompileError[];
+    memoryUsage?: MemoryUsage;
+}
+/**
+ * Generic upload result. All frameworks return this shape.
+ */
+export interface UploadResult {
+    success: boolean;
+    output: string;
+}
+/**
+ * Parse compile errors from output (GCC and Clang formats)
+ */
+export declare function parseCompileErrors(output: string, sketchDir?: string): CompileError[];
+/**
+ * Collect all .cpp files in a directory (non-recursive).
+ */
+export declare function collectCppFiles(rootDir: string): string[];

package/dist/api/shared/toolchain-types.js

@@ -0,0 +1,71 @@
+// ---------------------------------------------------------------------------
+// Shared toolchain types and utilities
+//
+// Compile error types, parsing utilities, and file collection helpers
+// shared across toolchain implementations.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * GCC-style error regex
+ */
+const GCC_STYLE = /^(.*?):(\d+):(\d+):\s*(fatal error|error|warning|note):\s*(.*)$/i;
+/**
+ * Clang-style error regex
+ */
+const CLANG_ERROR = /^(.*?):(\d+):(\d+):\s*(error|warning|note):\s*(.*)$/i;
+/**
+ * Parse compile errors from output (GCC and Clang formats)
+ */
+export function parseCompileErrors(output, sketchDir) {
+    const errors = [];
+    for (const rawLine of output.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        let match = line.match(GCC_STYLE);
+        if (!match) {
+            match = line.match(CLANG_ERROR);
+        }
+        if (!match) {
+            continue;
+        }
+        const severityRaw = match[4].toLowerCase();
+        const severity = severityRaw.includes("error") ? "error" : severityRaw === "warning" ? "warning" : "note";
+        let filePath = match[1];
+        // Normalize file paths
+        if (sketchDir) {
+            if (!path.isAbsolute(filePath)) {
+                const resolved = path.resolve(sketchDir, filePath);
+                if (fs.existsSync(resolved)) {
+                    filePath = resolved;
+                }
+            }
+        }
+        errors.push({
+            filePath: path.resolve(filePath),
+            line: parseInt(match[2], 10),
+            column: parseInt(match[3], 10),
+            severity,
+            message: match[5],
+        });
+    }
+    return errors;
+}
+/**
+ * Collect all .cpp files in a directory (non-recursive).
+ */
+export function collectCppFiles(rootDir) {
+    const results = [];
+    if (!fs.existsSync(rootDir)) {
+        return results;
+    }
+    for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".cpp")) {
+            continue;
+        }
+        results.push(path.join(rootDir, entry.name));
+    }
+    results.sort((a, b) => a.localeCompare(b));
+    return results;
+}