@typecad/framework-arduino 0.1.0-alpha.1

package/src/arduino-compile.ts

@@ -0,0 +1,359 @@
+// ---------------------------------------------------------------------------
+// Arduino sketch compilation, upload, and monitoring
+//
+// Provides functions to flatten generated modules into an Arduino sketch,
+// compile using arduino-cli, upload to a board, and monitor serial output.
+// ---------------------------------------------------------------------------
+
+import path from "node:path";
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import type { CompileError, CompileResult, UploadResult } from "@typecad/cuttlefish/api/shared";
+import { parseCompileErrors, collectCppFiles } from "@typecad/cuttlefish/api/shared";
+
+export type ArduinoCompileResult = CompileResult;
+export type ArduinoUploadResult = UploadResult;
+
+const ARDUINO_ERROR = /^(.*?):(\d+):\d+:\s*(error|warning|note):\s*(.*)$/i;
+
+/**
+ * Parse compile errors with Arduino format support.
+ */
+function parseArduinoCompileErrors(output: string, sketchDir?: string): CompileError[] {
+  const errors: CompileError[] = [];
+
+  for (const rawLine of output.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    let match = line.match(ARDUINO_ERROR);
+
+    if (!match) {
+      continue;
+    }
+
+    const severityRaw = match[3].toLowerCase();
+    const severity: "error" | "warning" | "note" =
+      severityRaw.includes("error") ? "error" : severityRaw === "warning" ? "warning" : "note";
+
+    let filePath = match[1];
+
+    if (sketchDir) {
+      if (!path.isAbsolute(filePath)) {
+        const resolved = path.resolve(sketchDir, filePath);
+        if (fs.existsSync(resolved)) {
+          filePath = resolved;
+        }
+      }
+      if (filePath.includes(path.basename(sketchDir))) {
+        filePath = path.resolve(sketchDir, path.basename(sketchDir) + ".ino");
+      }
+    }
+
+    errors.push({
+      filePath: path.resolve(filePath),
+      line: parseInt(match[2], 10),
+      column: 1,
+      severity,
+      message: match[4],
+    });
+  }
+
+  return errors;
+}
+
+/**
+ * Parse memory usage from arduino-cli output.
+ */
+export function parseArduinoMemoryUsage(output: string): { flashUsed?: number, flashTotal?: number, ramUsed?: number, ramTotal?: number } {
+  const result: { flashUsed?: number, flashTotal?: number, ramUsed?: number, ramTotal?: number } = {};
+  
+  // Sketch uses 444 bytes (1%) of program storage space. Maximum is 32256 bytes.
+  const flashMatch = output.match(/Sketch uses (\d+) bytes.*Maximum is (\d+) bytes/i);
+  if (flashMatch) {
+    result.flashUsed = parseInt(flashMatch[1], 10);
+    result.flashTotal = parseInt(flashMatch[2], 10);
+  }
+  
+  // Global variables use 9 bytes (0%) of dynamic memory, leaving 2039 bytes for local variables. Maximum is 2048 bytes.
+  const ramMatch = output.match(/Global variables use (\d+) bytes.*Maximum is (\d+) bytes/i);
+  if (ramMatch) {
+    result.ramUsed = parseInt(ramMatch[1], 10);
+    result.ramTotal = parseInt(ramMatch[2], 10);
+  }
+  
+  return result;
+}
+
+/**
+ * Extract architecture from FQBN string.
+ * FQBN format: vendor:arch:board[:config]
+ */
+export function toArchitectureFromFqbn(buildTarget?: string): string | undefined {
+  if (!buildTarget) return undefined;
+  return buildTarget.split(":")[1];
+}
+
+export function flattenGeneratedModulesIntoSketch(sketchDir: string, sketchPath: string): void {
+  const normalizedSketchPath = path.resolve(sketchPath);
+  const cppFiles = collectCppFiles(sketchDir).filter((filePath) => path.resolve(filePath) !== normalizedSketchPath);
+  if (cppFiles.length === 0) {
+    return;
+  }
+
+  // Collect header file names that correspond to the merged .cpp files
+  // These includes should be stripped from the entry sketch since the code is merged inline
+  const mergedHeaderNames = new Set<string>();
+  // Also track header file paths for inlining
+  const headerFiles = new Map<string, string>(); // baseName -> headerPath
+  for (const cppPath of cppFiles) {
+    const baseName = path.basename(cppPath, path.extname(cppPath));
+    const headerName = `${baseName}.h`;
+    mergedHeaderNames.add(headerName);
+
+    // Check if corresponding .h file exists
+    const headerPath = path.join(path.dirname(cppPath), headerName);
+    if (fs.existsSync(headerPath) && fs.statSync(headerPath).isFile()) {
+      headerFiles.set(baseName, headerPath);
+    }
+  }
+
+  // Also collect standalone .h files in the output directory that have no .cpp.
+  // These come from modules that only contain `declare function` (no bodies = no .cpp output).
+  for (const entry of fs.readdirSync(sketchDir)) {
+    if (!entry.endsWith(".h")) continue;
+    if (mergedHeaderNames.has(entry)) continue;
+    // Skip the sketch's own header and non-generated files
+    if (entry === path.basename(normalizedSketchPath, ".ino") + ".h") continue;
+    mergedHeaderNames.add(entry);
+    const headerPath = path.join(sketchDir, entry);
+    if (fs.statSync(headerPath).isFile()) {
+      headerFiles.set(path.basename(entry, ".h"), headerPath);
+    }
+  }
+
+  const originalSketch = fs.readFileSync(normalizedSketchPath, "utf8");
+  const sanitizedSketch = originalSketch
+    .replace(/^\s*#include\s+<Arduino\.h>\s*$/gm, "")
+    .replace(/^\s*#include\s+"Arduino\.h"\s*$/gm, "")
+    // Strip includes for headers corresponding to merged .cpp modules
+    .replace(/^\s*#include\s+"([^"]+)"\s*$/gm, (line, includePath: string) => {
+      const headerName = path.basename(includePath);
+      if (mergedHeaderNames.has(headerName)) {
+        return ""; // Remove the include since the module is merged inline
+      }
+      return line;
+    });
+  // Collect module contents - native C++ modules are NOT wrapped in namespaces
+  // since they're already valid C++ code
+  const moduleContents: string[] = [];
+  
+  for (const cppPath of cppFiles) {
+    const baseName = path.basename(cppPath, path.extname(cppPath));
+    const relativePath = path.relative(sketchDir, cppPath).replace(/\\/g, "/");
+    
+    // First, inline the corresponding .h file if it exists
+    const headerPath = headerFiles.get(baseName);
+    if (headerPath) {
+      const headerRelativePath = path.relative(sketchDir, headerPath).replace(/\\/g, "/");
+      const headerContent = fs.readFileSync(headerPath, "utf8");
+      const sanitizedHeader = headerContent
+        .replace(/^\s*#include\s+<Arduino\.h>\s*$/gm, "")
+        .replace(/^\s*#include\s+"Arduino\.h"\s*$/gm, "")
+        .replace(/^\s*#include\s+"([^"]+)"\s*$/gm, (line, includePath: string) => {
+          const headerName = path.basename(includePath);
+          if (mergedHeaderNames.has(headerName)) {
+            return ""; // Remove the include since the module is merged inline
+          }
+          return line;
+        });
+
+      moduleContents.push(`\n// ---- merged from ${headerRelativePath} ----\n${sanitizedHeader}\n`);
+    }
+    
+    const content = fs.readFileSync(cppPath, "utf8");
+    const rewritten = content.replace(/^\s*#include\s+"([^"]+)"\s*$/gm, (_line, includePath: string) => {
+      const headerName = path.basename(includePath);
+      // Strip includes for headers that we've already inlined
+      if (mergedHeaderNames.has(headerName)) {
+        return "";
+      }
+      
+      const resolved = path.resolve(path.dirname(cppPath), includePath);
+      if (!resolved.startsWith(path.resolve(sketchDir))) {
+        return `#include "${includePath}"`;
+      }
+      let relativeToSketch = path.relative(sketchDir, resolved).replace(/\\/g, "/");
+      relativeToSketch = relativeToSketch.replace(/(^|\/)([^\/]+)\/\2(?=\/|$)/g, "$1$2");
+      if (!relativeToSketch.startsWith(".")) {
+        relativeToSketch = `./${relativeToSketch}`;
+      }
+      return `#include "${relativeToSketch}"`;
+    });
+    const sanitized = rewritten
+      .replace(/^\s*#include\s+<Arduino\.h>\s*$/gm, "")
+      .replace(/^\s*#include\s+"Arduino\.h"\s*$/gm, "");
+    
+    // Skip modules whose body is empty after tree-shaking
+    const stripped = sanitized
+      .replace(/^\s*#include\s+.*$/gm, "")
+      .replace(/^\s*\/\/.*$/gm, "")
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .trim();
+    if (stripped.length === 0) {
+      continue;
+    }
+    
+    moduleContents.push(`\n// ---- merged from ${relativePath} ----\n${sanitized}\n`);
+  }
+
+  const mergedSketch = `${moduleContents.join("")}// ---- entry sketch ----\n${sanitizedSketch}\n`;
+  fs.writeFileSync(normalizedSketchPath, mergedSketch, "utf8");
+
+  // Clean up merged .cpp and .h files
+  for (const cppPath of cppFiles) {
+    fs.rmSync(cppPath, { force: true });
+  }
+  for (const headerPath of headerFiles.values()) {
+    fs.rmSync(headerPath, { force: true });
+  }
+}
+
+export function compileArduinoSketch(
+  sketchFilePath: string,
+  buildTarget: string,
+  options?: { extraFlags?: string[]; defines?: Record<string, string> },
+): ArduinoCompileResult {
+  const resolvedSketchFilePath = path.resolve(sketchFilePath);
+  let sketchDir = path.dirname(resolvedSketchFilePath);
+  let sketchDirName = path.basename(sketchDir);
+  let requiredSketchPath = path.join(sketchDir, `${sketchDirName}.ino`);
+
+  if (sketchDirName.startsWith(".")) {
+    const stagingDir = path.join(path.dirname(sketchDir), "ts2cpp_sketch");
+    try {
+      fs.rmSync(stagingDir, { recursive: true, force: true });
+      fs.mkdirSync(stagingDir, { recursive: true });
+      fs.cpSync(sketchDir, stagingDir, { recursive: true });
+      sketchDir = stagingDir;
+      sketchDirName = path.basename(sketchDir);
+      requiredSketchPath = path.join(sketchDir, `${sketchDirName}.ino`);
+    } catch {
+      // Best-effort staging; fall back to original directory behavior.
+    }
+  }
+
+  if (path.extname(resolvedSketchFilePath).toLowerCase() === ".ino" && resolvedSketchFilePath !== requiredSketchPath) {
+    try {
+      const sourceText = fs.readFileSync(resolvedSketchFilePath, "utf8");
+      if (!fs.existsSync(requiredSketchPath) || fs.readFileSync(requiredSketchPath, "utf8") !== sourceText) {
+        fs.writeFileSync(requiredSketchPath, sourceText, "utf8");
+      }
+
+      // Arduino sketches must have a single primary .ino matching the folder name.
+      // Remove other .ino files in the sketch root to avoid duplicate setup()/loop().
+      for (const child of fs.readdirSync(sketchDir)) {
+        if (!child.toLowerCase().endsWith(".ino")) {
+          continue;
+        }
+        const candidate = path.join(sketchDir, child);
+        if (path.resolve(candidate) !== path.resolve(requiredSketchPath)) {
+          fs.rmSync(candidate, { force: true });
+        }
+      }
+    } catch {
+      // Best-effort sketch alias generation. If this fails, arduino-cli output will report details.
+    }
+  }
+
+  try {
+    if (fs.existsSync(requiredSketchPath)) {
+      flattenGeneratedModulesIntoSketch(sketchDir, requiredSketchPath);
+    }
+  } catch {
+    // Best-effort flattening for generated modules.
+  }
+
+  // Build the arduino-cli argument list. User defines/extraFlags (from
+  // output.defines and output.extraFlags in cuttlefish.config.ts) are injected
+  // via a build_opt.h file in the sketch dir, which arduino-cli reads through
+  // the platform recipe's @"{build.opt.path}" token and feeds to the compiler
+  // WITHOUT touching any platform property.
+  //
+  // Why not --build-property? Both candidate properties are load-bearing on
+  // modern cores and `--build-property` REPLACES rather than appends:
+  //   - compiler.cpp.extra_flags carries -MMD/-c (dependency tracking); replacing
+  //     it desyncs the sketch from the precompiled core, producing dozens of
+  //     "undefined reference" errors to core symbols (pinMode, Serial, main, ...).
+  //   - build.extra_flags on the ESP32 core is a composed value that pulls in
+  //     the USB/CDC/boot-mode defines (ARDUINO_USB_CDC_ON_BOOT, ARDUINO_USB_MODE,
+  //     ...); replacing it silently breaks USB-serial sketches.
+  // build_opt.h avoids both: the platform recipe appends it verbatim, so every
+  // board/core property stays intact and the user defines are applied cleanly.
+  const compileArgs: string[] = ["compile", "--fqbn", buildTarget];
+  const userFlagParts: string[] = [];
+  if (options?.defines) {
+    for (const [name, value] of Object.entries(options.defines)) {
+      userFlagParts.push(value !== "" ? `-D${name}=${value}` : `-D${name}`);
+    }
+  }
+  if (options?.extraFlags) {
+    userFlagParts.push(...options.extraFlags);
+  }
+  if (userFlagParts.length > 0) {
+    const buildOptPath = path.join(sketchDir, "build_opt.h");
+    try {
+      // Preserve any user-authored build_opt.h content; append our defines
+      // rather than overwriting so we don't drop flags the sketch relies on.
+      const existing = fs.existsSync(buildOptPath)
+        ? fs.readFileSync(buildOptPath, "utf8")
+        : "";
+      const generated = `${userFlagParts.join("\n")}\n`;
+      const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+      fs.writeFileSync(buildOptPath, existing + sep + generated, "utf8");
+    } catch {
+      // Best-effort: if we can't write build_opt.h, fall back to no defines
+      // rather than failing the whole compile. The compile will still run;
+      // the user's defines just won't be applied.
+    }
+  }
+  compileArgs.push(sketchDir);
+
+  const cmd = spawnSync("arduino-cli", compileArgs, {
+    encoding: "utf8",
+    timeout: 120000,
+  });
+
+  const output = `${cmd.stdout ?? ""}\n${cmd.stderr ?? ""}`.trim();
+  const gccErrors = parseCompileErrors(output, sketchDir);
+  const arduinoErrors = parseArduinoCompileErrors(output, sketchDir);
+  const errors = gccErrors.length > 0 ? gccErrors : arduinoErrors;
+
+  return {
+    success: cmd.status === 0,
+    output,
+    errors,
+    memoryUsage: cmd.status === 0 ? parseArduinoMemoryUsage(output) : undefined,
+  };
+}
+
+export function uploadArduinoSketch(sketchDir: string, buildTarget: string, port: string): ArduinoUploadResult {
+  const cmd = spawnSync("arduino-cli", ["upload", "--fqbn", buildTarget, "--port", port, sketchDir], {
+    encoding: "utf8",
+    timeout: 60000,
+  });
+
+  const output = `${cmd.stdout ?? ""}\n${cmd.stderr ?? ""}`.trim();
+
+  return {
+    success: cmd.status === 0,
+    output,
+  };
+}
+
+export function monitorArduinoSketch(port: string, baud: number): void {
+  spawnSync("arduino-cli", ["monitor", "--port", port, "--config", `baudrate=${baud}`], {
+    stdio: "inherit",
+    timeout: 0,
+  });
+}

package/src/arduino-libs.ts

@@ -0,0 +1,33 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — Arduino Library Utilities
+//
+// Thin re-export barrel. Implementation is split across:
+//   - lib-discovery.ts    — finding installed libraries via arduino-cli
+//   - cpp-parser.ts       — parsing C++ headers into an IR
+//   - lib-declaration.ts  — generating .d.ts declarations + docs
+// ---------------------------------------------------------------------------
+
+export type { ArduinoLibrary } from './lib-discovery.js';
+export {
+  getInstalledLibraries,
+  findArduinoLibrary,
+  findLibraryHeader,
+  isArduinoLibraryImport,
+  clearLibraryCache,
+} from './lib-discovery.js';
+
+export type { CppParseResult } from './cpp-parser.js';
+export {
+  mapCppTypeToTs,
+  parseParameters,
+  parseCppClass,
+} from './cpp-parser.js';
+
+export type { GeneratedArduinoLib } from './lib-declaration.js';
+export {
+  tryGenerateArduinoLibDecl,
+  getArduinoLibraryHeaderName,
+  getArduinoLibraryClassNames,
+  generateUsageDocumentation,
+} from './lib-declaration.js';
+

package/src/cli-metadata.ts

@@ -0,0 +1,250 @@
+// ---------------------------------------------------------------------------
+// Arduino CLI metadata loader
+//
+// Loads board metadata from arduino-cli when available.
+// Uses disk caching to avoid repeated slow arduino-cli calls.
+// ---------------------------------------------------------------------------
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { Diagnostic } from "@typecad/cuttlefish/api/shared";
+import type { ArduinoPlatformContext } from "./strategy.js";
+
+// ---------------------------------------------------------------------------
+// Disk cache for arduino-cli metadata
+// ---------------------------------------------------------------------------
+
+const CACHE_DIR = path.join(os.homedir(), ".TypeCAD", "cache");
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+interface CachedMetadata {
+  fqbn: string;
+  metadata: {
+    architecture?: string;
+    pins: Record<string, number>;
+    builtinFunctions: string[];  // Serialized as array
+    builtinGlobals: string[];    // Serialized as array
+  };
+  timestamp: number;
+}
+
+function getCachePath(fqbn: string): string {
+  const safeFqbn = fqbn.replace(/[:/\\]/g, "_");
+  return path.join(CACHE_DIR, `arduino-cli-${safeFqbn}.json`);
+}
+
+function loadCachedMetadata(fqbn: string): ArduinoCliMetadata | null {
+  try {
+    const cachePath = getCachePath(fqbn);
+    if (!fs.existsSync(cachePath)) return null;
+
+    const cached: CachedMetadata = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+
+    // Check TTL
+    if (Date.now() - cached.timestamp > CACHE_TTL_MS) {
+      return null; // Expired
+    }
+
+    // Convert arrays back to Sets
+    return {
+      architecture: cached.metadata.architecture,
+      pins: cached.metadata.pins,
+      builtinFunctions: new Set(cached.metadata.builtinFunctions),
+      builtinGlobals: new Set(cached.metadata.builtinGlobals),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function saveCachedMetadata(fqbn: string, metadata: ArduinoCliMetadata): void {
+  try {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+    const cached: CachedMetadata = {
+      fqbn,
+      metadata: {
+        architecture: metadata.architecture,
+        pins: metadata.pins,
+        builtinFunctions: [...metadata.builtinFunctions],  // Convert Set to array
+        builtinGlobals: [...metadata.builtinGlobals],      // Convert Set to array
+      },
+      timestamp: Date.now(),
+    };
+    fs.writeFileSync(getCachePath(fqbn), JSON.stringify(cached));
+  } catch {
+    // Ignore cache write errors
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Arduino CLI probing
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract architecture from FQBN string.
+ * FQBN format: vendor:arch:board[:menu=options]
+ * e.g., "arduino:avr:uno" -> "avr"
+ */
+function toArchitectureFromFqbn(fqbn?: string): string | undefined {
+  if (!fqbn) return undefined;
+  const parts = fqbn.split(":");
+  return parts.length >= 2 ? parts[1] : undefined;
+}
+
+export interface ArduinoCliMetadata {
+  architecture?: string;
+  pins: Record<string, number>;
+  builtinFunctions: Set<string>;
+  builtinGlobals: Set<string>;
+}
+
+function parsePinMap(value: unknown): Record<string, number> {
+  const pins: Record<string, number> = {};
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (!item || typeof item !== "object") {
+        continue;
+      }
+      const candidate = item as Record<string, unknown>;
+      const name = typeof candidate.name === "string" ? candidate.name : undefined;
+      const numeric =
+        typeof candidate.value === "number"
+          ? candidate.value
+          : typeof candidate.value === "string" && !Number.isNaN(Number(candidate.value))
+            ? Number(candidate.value)
+            : undefined;
+      if (name && numeric !== undefined) {
+        pins[name] = numeric;
+      }
+    }
+    return pins;
+  }
+
+  if (value && typeof value === "object") {
+    for (const [name, raw] of Object.entries(value as Record<string, unknown>)) {
+      if (typeof raw === "number") {
+        pins[name] = raw;
+      } else if (typeof raw === "string" && !Number.isNaN(Number(raw))) {
+        pins[name] = Number(raw);
+      }
+    }
+  }
+
+  return pins;
+}
+
+function parseStringSet(value: unknown): Set<string> {
+  if (!Array.isArray(value)) {
+    return new Set<string>();
+  }
+
+  return new Set(
+    value
+      .filter((item): item is string => typeof item === "string")
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0),
+  );
+}
+
+function normalizeMetadata(raw: unknown, context?: ArduinoPlatformContext): ArduinoCliMetadata {
+  const object = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+
+  // board details --format json puts architecture under platform.architecture
+  const platform = object.platform && typeof object.platform === "object" ? (object.platform as Record<string, unknown>) : {};
+  const architecture =
+    (typeof platform.architecture === "string" ? platform.architecture.toLowerCase() : undefined) ??
+    (typeof object.architecture === "string" ? object.architecture.toLowerCase() : undefined) ??
+    (typeof object.arch === "string" ? object.arch.toLowerCase() : undefined) ??
+    toArchitectureFromFqbn(context?.buildTarget);
+
+  const pins = {
+    ...parsePinMap(object.pins),
+    ...parsePinMap(object.pinMappings),
+  };
+
+  const builtinFunctions = new Set<string>([
+    ...parseStringSet(object.builtinFunctions),
+    ...parseStringSet(object.functions),
+  ]);
+
+  const builtinGlobals = new Set<string>([
+    ...parseStringSet(object.builtinGlobals),
+    ...parseStringSet(object.globals),
+  ]);
+
+  return {
+    architecture,
+    pins,
+    builtinFunctions,
+    builtinGlobals,
+  };
+}
+
+function tryArduinoCliProbe(ctx?: ArduinoPlatformContext): { raw?: unknown; diagnostic?: Diagnostic } {
+  if (!ctx || !ctx.buildTarget) {
+    return {};
+  }
+
+  const cmd = spawnSync("arduino-cli", ["board", "details", "--show-properties", "--format", "json", "--fqbn", ctx.buildTarget], {
+    encoding: "utf8",
+    timeout: 10000,
+  });
+
+  if (cmd.error || cmd.status !== 0) {
+    return {
+      diagnostic: {
+        severity: "warning",
+        code: "TS2CPP_ARDUINO_CLI_PROBE_FAILED",
+        message: `Failed to parse arduino-cli properties for ${ctx.buildTarget}`,
+      },
+    };
+  }
+
+  try {
+    return { raw: JSON.parse(cmd.stdout) as unknown };
+  } catch {
+    return {
+      diagnostic: {
+        severity: "warning",
+        code: "TS2CPP_ARDUINO_CLI_PARSE_FAILED",
+        message: "arduino-cli output could not be parsed as JSON; using static profile fallbacks.",
+      },
+    };
+  }
+}
+
+export function loadArduinoCliMetadata(ctx?: ArduinoPlatformContext): {
+  metadata?: ArduinoCliMetadata;
+  diagnostics: Diagnostic[];
+} {
+  const diagnostics: Diagnostic[] = [];
+  const fqbn = ctx?.buildTarget;
+
+  if (!fqbn) {
+    return { diagnostics };
+  }
+
+  // Try disk cache first
+  const cached = loadCachedMetadata(fqbn);
+  if (cached) {
+    return { metadata: cached, diagnostics };
+  }
+
+  // Cache miss - probe arduino-cli
+  const probe = tryArduinoCliProbe(ctx);
+  if (probe.diagnostic) {
+    diagnostics.push(probe.diagnostic);
+  }
+
+  if (probe.raw) {
+    const metadata = normalizeMetadata(probe.raw, ctx);
+    // Save to disk cache for future sessions
+    saveCachedMetadata(fqbn, metadata);
+    return { metadata, diagnostics };
+  }
+
+  return { diagnostics };
+}