@typecad/cuttlefish 1.0.0-alpha.3 → 1.0.0-alpha.7

package/dist/ui-hook.d.ts

@@ -58,7 +58,23 @@ export interface TranspilerUIHook {
     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;
+    /**
+     * Emits ONLY the CuttlefishGFX class definition (the shared GFX base for
+     * native display paths). Called separately from emitRuntimeHeader so the
+     * class can be emitted BEFORE display adapter declarations that
+     * instantiate CuttlefishGFX by value. Returns "" when active is false
+     * (Arduino path).
+     */
+    emitCuttlefishGfx(active: boolean): string;
+    /**
+     * Options controlling runtime-header emission.
+     *   - nativeDisplayActive: when true, emit the shared CuttlefishGFX class
+     *     (used by native display adapters on AVR/ESP32). Arduino paths pass
+     *     false (default) and use Adafruit_GFX directly.
+     */
+    emitRuntimeHeader(opts?: {
+        nativeDisplayActive?: boolean;
+    }): string;
     splitUiFile(src: string): UiFileParts;
     generateProjectUITypeDeclarations(projectRoot: string): {
         written: string[];

package/dist/utils/cli.js

@@ -17,6 +17,8 @@ export function printHelp() {
     console.log(`  cuttlefish board add <spec.jsonc> [--force]   Generate board + MCU packages from a chip spec`);
     console.log(`  cuttlefish gen-decls <input.cpp|--all <directory>>`);
     console.log(`  cuttlefish map-error <mapFile> [options]`);
+    console.log(`  cuttlefish doctor                              Check that arduino-cli is installed and the board's core is present`);
+    console.log(`  cuttlefish licenses [--all] [--strict]          Scan this project's Arduino libraries for SPDX licenses (--all: every installed library)`);
     console.log();
     console.log(chalk.gray(`Transpilation is always performed first. Use --compile, --upload, and`));
     console.log(chalk.gray(`--monitor to chain operations after transpilation.`));
@@ -337,6 +339,48 @@ export function parseCommandLine(argv) {
             port: port ? String(port) : undefined,
         };
     }
+    // doctor subcommand — verify arduino-cli + board core presence
+    if (firstArg === "doctor") {
+        return {
+            command: "doctor",
+            // The remaining pipeline fields are unused by doctor; fill with safe
+            // defaults, the same way the preview branch does.
+            inputFile: undefined,
+            emitMode: "split",
+            target: "generic",
+            outDir: undefined,
+            emitMaps: true,
+            noTranspile: false,
+            compile: false,
+            upload: false,
+            monitor: false,
+            watch: false,
+            baud: 9600,
+            platformContext: {},
+        };
+    }
+    // licenses subcommand — scan installed Arduino libraries for SPDX licenses
+    if (firstArg === "licenses") {
+        return {
+            command: "licenses",
+            strict: argv.includes("--strict"),
+            all: argv.includes("--all"),
+            // The remaining pipeline fields are unused by licenses; fill with safe
+            // defaults, the same way the doctor branch does.
+            inputFile: undefined,
+            emitMode: "split",
+            target: "generic",
+            outDir: undefined,
+            emitMaps: true,
+            noTranspile: false,
+            compile: false,
+            upload: false,
+            monitor: false,
+            watch: false,
+            baud: 9600,
+            platformContext: {},
+        };
+    }
     // Named subcommands
     if (firstArg === "gen-libdefs" || firstArg === "gen-decls" || firstArg === "map-error") {
         const command = firstArg;
@@ -387,12 +431,16 @@ export function parseCommandLine(argv) {
         // gen-decls - generate .d.ts from C++ files
         if (command === "gen-decls") {
             const allFlag = argv.includes("--all");
+            const componentsFlag = argv.includes("--components");
+            if (allFlag && componentsFlag) {
+                throw new Error("gen-decls: --components and --all are mutually exclusive. Use one or the other.");
+            }
             // The positional path may sit at argv[3] or argv[4] depending on whether
             // --all precedes or follows it. Scan argv starting after the subcommand
             // name (argv[2]) for the first token that is not a flag and not a known
             // flag's value. This mirrors the default-pipeline approach of "first
             // non-flag token wins".
-            const booleanFlags = new Set(["--all"]);
+            const booleanFlags = new Set(["--all", "--components"]);
             const valueFlags = new Set([
                 "--emit", "--target", "--outDir", "--out-dir", "--emit-maps", "--build-target",
             ]);
@@ -413,6 +461,28 @@ export function parseCommandLine(argv) {
                 inputPath = tok;
                 break;
             }
+            // --components mode: scan managed_components/ + components/ declared in
+            // cuttlefish.config.ts. Falls back to cwd when no path is given.
+            if (componentsFlag) {
+                const componentsDir = inputPath || process.cwd();
+                return {
+                    command: "gen-decls",
+                    inputFile: undefined,
+                    emitMode,
+                    target,
+                    outDir: outDir ? path.resolve(process.cwd(), outDir) : undefined,
+                    emitMaps,
+                    noTranspile: false,
+                    compile: false,
+                    upload: false,
+                    monitor: false,
+                    watch: false,
+                    baud: 9600,
+                    platformContext,
+                    scanDir: undefined,
+                    componentsDir: path.resolve(process.cwd(), componentsDir),
+                };
+            }
             if (!inputPath && !allFlag) {
                 throw new Error("Missing input C++ file path. Use: gen-decls <file.cpp> or gen-decls --all <directory>");
             }

package/dist/utils/fs.d.ts

@@ -2,3 +2,16 @@ export declare function ensureDir(dirPath: string): void;
 export declare function readText(filePath: string): string;
 export declare function writeText(filePath: string, content: string): void;
 export declare function listFiles(dirPath: string, extension: string): string[];
+/**
+ * Recursive variant of {@link listFiles}. Walks `dirPath` depth-first and
+ * returns every file (in every subdirectory) whose name ends with `extension`.
+ *
+ * Used by {@link loadLibraryDefinitions} so libdefs under nested cache dirs
+ * like `.cuttlefish/component-decls/<component>/` are discovered. Purely
+ * additive vs. the non-recursive `listFiles` — single-level layouts keep
+ * working, nested layouts now also work.
+ *
+ * Returns absolute paths. Unreadable directories are silently skipped
+ * (matches `listFiles`'s not-exist behavior for non-existent roots).
+ */
+export declare function listFilesRecursive(dirPath: string, extension: string): string[];

package/dist/utils/fs.js

@@ -10,6 +10,15 @@ export function readText(filePath) {
 }
 export function writeText(filePath, content) {
     ensureDir(path.dirname(filePath));
+    // Skip writing when content is identical — preserves mtime so downstream
+    // build tools (idf.py/ninja, arduino-cli, make) can skip recompilation.
+    try {
+        if (fs.readFileSync(filePath, "utf8") === content)
+            return;
+    }
+    catch {
+        // File doesn't exist yet — fall through to write.
+    }
     fs.writeFileSync(filePath, content, "utf8");
 }
 export function listFiles(dirPath, extension) {
@@ -21,3 +30,44 @@ export function listFiles(dirPath, extension) {
         .filter((name) => name.toLowerCase().endsWith(extension.toLowerCase()))
         .map((name) => path.join(dirPath, name));
 }
+/**
+ * Recursive variant of {@link listFiles}. Walks `dirPath` depth-first and
+ * returns every file (in every subdirectory) whose name ends with `extension`.
+ *
+ * Used by {@link loadLibraryDefinitions} so libdefs under nested cache dirs
+ * like `.cuttlefish/component-decls/<component>/` are discovered. Purely
+ * additive vs. the non-recursive `listFiles` — single-level layouts keep
+ * working, nested layouts now also work.
+ *
+ * Returns absolute paths. Unreadable directories are silently skipped
+ * (matches `listFiles`'s not-exist behavior for non-existent roots).
+ */
+export function listFilesRecursive(dirPath, extension) {
+    if (!fs.existsSync(dirPath)) {
+        return [];
+    }
+    const ext = extension.toLowerCase();
+    const out = [];
+    const stack = [dirPath];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            // Permission error / race / etc. Skip this subtree.
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(cur, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile() && entry.name.toLowerCase().endsWith(ext)) {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/cuttlefish",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.7",
   "description": "TypeScript to C++ transpiler — native, Arduino, and bare-metal targets",
   "type": "module",
   "main": "./dist/transpile.js",
@@ -49,6 +49,10 @@
       "types": "./dist/emit/route-hal-op.d.ts",
       "default": "./dist/emit/route-hal-op.js"
     },
+    "./lib/component-decls": {
+      "types": "./dist/libdef/component-decls.d.ts",
+      "default": "./dist/libdef/component-decls.js"
+    },
     "./ir/transformers/ui-lowering": {
       "types": "./dist/ir/transformers/ui-lowering.d.ts",
       "default": "./dist/ir/transformers/ui-lowering.js"
@@ -80,10 +84,11 @@
   "dependencies": {
     "chalk": "^4.1.2",
     "typescript": "^5.7.3",
-    "zod": "^3.24.0"
+    "zod": "^3.24.0",
+    "@typecad/arduino-cli": "1.0.0-alpha.7"
   },
   "peerDependencies": {
-    "@typecad/ui": "1.0.0-alpha.3"
+    "@typecad/ui": "1.0.0-alpha.7"
   },
   "peerDependenciesMeta": {
     "@typecad/ui": {
@@ -91,7 +96,7 @@
     }
   },
   "optionalDependencies": {
-    "@typecad/framework-native": "1.0.0-alpha.3"
+    "@typecad/framework-native": "1.0.0-alpha.7"
   },
   "devDependencies": {
     "@types/node": "^22.10.7"

package/dist/ir/heap-array-validation.d.ts

@@ -1,24 +0,0 @@
-import type { Diagnostic } from '../types.js';
-import type { BoardConstants } from './board-resolver.js';
-import type { StatementIR } from '../api/index.js';
-import type { PlatformStrategy } from '../api/shared/index.js';
-/**
- * @deprecated Heap allocation is now validated at emit time by the platform
- * strategy's `profileDiagnostics` (see framework-arduino `collectHeapAllocationDiagnostics`).
- * This build-time stub returns no diagnostics. Kept to preserve the
- * `validation-orchestrator.ts` import; remove that call site when convenient.
- */
-export declare function validateHeapArrayUsage(_program: {
-    topLevelStatements: StatementIR[];
-    functions: Array<{
-        statements: StatementIR[];
-    }>;
-    classes: Array<{
-        methods: Array<{
-            statements: StatementIR[];
-        }>;
-        constructor?: {
-            statements: StatementIR[];
-        };
-    }>;
-}, _boardConstants: BoardConstants | undefined, _strategy?: PlatformStrategy): Diagnostic[];

package/dist/ir/heap-array-validation.js

@@ -1,29 +0,0 @@
-// ---------------------------------------------------------------------------
-// Heap Allocation Validator (retired — moved to the emit-time profile gate)
-//
-// Heap allocation via `new` on no-heap architectures (AVR, etc.) is now
-// rejected by the Arduino strategy's `profileDiagnostics`
-// (`framework-arduino/src/strategy.ts` `collectHeapAllocationDiagnostics`).
-//
-// WHY THE MOVE: this build-time validator keyed off `boardConstants.architecture`,
-// which is only populated when an MCU/board `import` is present. Programs with
-// no such import silently bypassed it — so demo #33's `new Accumulator()`
-// passed while a HAL-importing demo's `new Blinker()` failed, for the same
-// source pattern. The profile-time gate derives `arch` from the FQBN
-// (`frameworkData.buildTarget`), so it fires regardless of import structure
-// (demo #34 Finding A). It also keys off the `newClassName` marker a user-class
-// `new` tags its raw IR node with (set in `expression-to-ir.ts`), making
-// detection structural rather than textual.
-//
-// The export is kept (returns `[]`) so `validation-orchestrator.ts`'s import
-// stays valid; the real work happens at emit time.
-// ---------------------------------------------------------------------------
-/**
- * @deprecated Heap allocation is now validated at emit time by the platform
- * strategy's `profileDiagnostics` (see framework-arduino `collectHeapAllocationDiagnostics`).
- * This build-time stub returns no diagnostics. Kept to preserve the
- * `validation-orchestrator.ts` import; remove that call site when convenient.
- */
-export function validateHeapArrayUsage(_program, _boardConstants, _strategy) {
-    return [];
-}