@typecad/cuttlefish 0.1.0-alpha.1

package/dist/config-schema.d.ts

@@ -0,0 +1,233 @@
+import { z } from 'zod';
+/**
+ * Schema for the full CuttlefishConfig shape.
+ *
+ * `target` and `board` are required. Everything else is optional.
+ */
+export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
+    entry: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodString>;
+    mcu: z.ZodOptional<z.ZodString>;
+    board: z.ZodOptional<z.ZodString>;
+    contract: z.ZodOptional<z.ZodString>;
+    framework: z.ZodOptional<z.ZodString>;
+    output: z.ZodOptional<z.ZodObject<{
+        framework: z.ZodOptional<z.ZodString>;
+        optimize: z.ZodOptional<z.ZodEnum<["none", "size", "speed", "balanced"]>>;
+        outDir: z.ZodOptional<z.ZodString>;
+        defines: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        extraFlags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        framework?: string | undefined;
+        outDir?: string | undefined;
+        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
+        defines?: Record<string, string> | undefined;
+        extraFlags?: string[] | undefined;
+    }, {
+        framework?: string | undefined;
+        outDir?: string | undefined;
+        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
+        defines?: Record<string, string> | undefined;
+        extraFlags?: string[] | undefined;
+    }>>;
+    frameworkData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    include: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    test: z.ZodOptional<z.ZodObject<{
+        include: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        port: z.ZodOptional<z.ZodString>;
+        baudRate: z.ZodOptional<z.ZodNumber>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+        buildTarget: z.ZodOptional<z.ZodString>;
+        board: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        buildTarget?: string | undefined;
+        port?: string | undefined;
+        board?: string | undefined;
+        baudRate?: number | undefined;
+        include?: string[] | undefined;
+        timeout?: number | undefined;
+    }, {
+        buildTarget?: string | undefined;
+        port?: string | undefined;
+        board?: string | undefined;
+        baudRate?: number | undefined;
+        include?: string[] | undefined;
+        timeout?: number | undefined;
+    }>>;
+    toolchain: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        frameworkOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strict", z.ZodTypeAny, {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    }, {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    }>>;
+    console: z.ZodOptional<z.ZodObject<{
+        baudRate: z.ZodOptional<z.ZodNumber>;
+        port: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        port?: string | undefined;
+        baudRate?: number | undefined;
+    }, {
+        port?: string | undefined;
+        baudRate?: number | undefined;
+    }>>;
+    native: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strict", z.ZodTypeAny, {
+    console?: {
+        port?: string | undefined;
+        baudRate?: number | undefined;
+    } | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
+    target?: string | undefined;
+    framework?: string | undefined;
+    native?: Record<string, unknown> | undefined;
+    output?: {
+        framework?: string | undefined;
+        outDir?: string | undefined;
+        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
+        defines?: Record<string, string> | undefined;
+        extraFlags?: string[] | undefined;
+    } | undefined;
+    board?: string | undefined;
+    mcu?: string | undefined;
+    include?: string[] | undefined;
+    entry?: string | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
+    contract?: string | undefined;
+    exclude?: string[] | undefined;
+    test?: {
+        buildTarget?: string | undefined;
+        port?: string | undefined;
+        board?: string | undefined;
+        baudRate?: number | undefined;
+        include?: string[] | undefined;
+        timeout?: number | undefined;
+    } | undefined;
+}, {
+    console?: {
+        port?: string | undefined;
+        baudRate?: number | undefined;
+    } | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
+    target?: string | undefined;
+    framework?: string | undefined;
+    native?: Record<string, unknown> | undefined;
+    output?: {
+        framework?: string | undefined;
+        outDir?: string | undefined;
+        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
+        defines?: Record<string, string> | undefined;
+        extraFlags?: string[] | undefined;
+    } | undefined;
+    board?: string | undefined;
+    mcu?: string | undefined;
+    include?: string[] | undefined;
+    entry?: string | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
+    contract?: string | undefined;
+    exclude?: string[] | undefined;
+    test?: {
+        buildTarget?: string | undefined;
+        port?: string | undefined;
+        board?: string | undefined;
+        baudRate?: number | undefined;
+        include?: string[] | undefined;
+        timeout?: number | undefined;
+    } | undefined;
+}>, {
+    console?: {
+        port?: string | undefined;
+        baudRate?: number | undefined;
+    } | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
+    target?: string | undefined;
+    framework?: string | undefined;
+    native?: Record<string, unknown> | undefined;
+    output?: {
+        framework?: string | undefined;
+        outDir?: string | undefined;
+        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
+        defines?: Record<string, string> | undefined;
+        extraFlags?: string[] | undefined;
+    } | undefined;
+    board?: string | undefined;
+    mcu?: string | undefined;
+    include?: string[] | undefined;
+    entry?: string | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
+    contract?: string | undefined;
+    exclude?: string[] | undefined;
+    test?: {
+        buildTarget?: string | undefined;
+        port?: string | undefined;
+        board?: string | undefined;
+        baudRate?: number | undefined;
+        include?: string[] | undefined;
+        timeout?: number | undefined;
+    } | undefined;
+}, {
+    console?: {
+        port?: string | undefined;
+        baudRate?: number | undefined;
+    } | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
+    target?: string | undefined;
+    framework?: string | undefined;
+    native?: Record<string, unknown> | undefined;
+    output?: {
+        framework?: string | undefined;
+        outDir?: string | undefined;
+        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
+        defines?: Record<string, string> | undefined;
+        extraFlags?: string[] | undefined;
+    } | undefined;
+    board?: string | undefined;
+    mcu?: string | undefined;
+    include?: string[] | undefined;
+    entry?: string | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
+    contract?: string | undefined;
+    exclude?: string[] | undefined;
+    test?: {
+        buildTarget?: string | undefined;
+        port?: string | undefined;
+        board?: string | undefined;
+        baudRate?: number | undefined;
+        include?: string[] | undefined;
+        timeout?: number | undefined;
+    } | undefined;
+}>;
+/** Inferred TypeScript type from the Zod schema. */
+export type ValidatedCuttlefishConfig = z.infer<typeof CuttlefishConfigSchema>;
+/**
+ * Validate a parsed config object against the schema.
+ * Returns the validated config or throws a ZodError with detailed diagnostics.
+ */
+export declare function validateConfig(config: unknown): ValidatedCuttlefishConfig;
+/**
+ * Validate a parsed config object, returning a result instead of throwing.
+ * Useful when you want to collect diagnostics without catching exceptions.
+ */
+export declare function safeValidateConfig(config: unknown): {
+    success: true;
+    data: ValidatedCuttlefishConfig;
+} | {
+    success: false;
+    errors: string[];
+};

package/dist/config-schema.js

@@ -0,0 +1,83 @@
+// ---------------------------------------------------------------------------
+// Config Schema — Zod validation for cuttlefish.config.ts parsed values
+//
+// After the AST-based config loader extracts scalar/structured values from
+// cuttlefish.config.ts, this schema validates the shape, required fields, and
+// enum constraints before the config is used by the transpiler.
+// ---------------------------------------------------------------------------
+import { z } from 'zod';
+/** Optimization levels accepted by the output.optimize field. */
+const OptimizationLevel = z.enum(['none', 'size', 'speed', 'balanced']);
+/** Schema for the `output` section. */
+const OutputConfig = z.object({
+    framework: z.string().min(1).optional(),
+    optimize: OptimizationLevel.optional(),
+    outDir: z.string().optional(),
+    defines: z.record(z.string(), z.string()).optional(),
+    extraFlags: z.array(z.string()).optional(),
+}).strict();
+/** Schema for the `console` section. */
+const ConsoleConfig = z.object({
+    baudRate: z.number().int().positive().optional(),
+    port: z.string().optional(),
+}).strict();
+/** Schema for the `test` section. */
+const TestConfig = z.object({
+    include: z.array(z.string()).optional(),
+    port: z.string().optional(),
+    baudRate: z.number().int().positive().optional(),
+    timeout: z.number().int().positive().optional(),
+    buildTarget: z.string().optional(),
+    board: z.string().optional(),
+}).strict();
+/** Schema for the `toolchain` section. */
+const ToolchainConfig = z.object({
+    type: z.string().optional(),
+    frameworkOptions: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+/**
+ * Schema for the full CuttlefishConfig shape.
+ *
+ * `target` and `board` are required. Everything else is optional.
+ */
+export const CuttlefishConfigSchema = z.object({
+    entry: z.string().optional(),
+    target: z.string().min(1).optional(),
+    mcu: z.string().min(1).optional(),
+    board: z.string().optional(),
+    contract: z.string().optional(),
+    framework: z.string().optional(),
+    output: OutputConfig.optional(),
+    frameworkData: z.record(z.string(), z.unknown()).optional(),
+    include: z.array(z.string()).optional(),
+    exclude: z.array(z.string()).optional(),
+    test: TestConfig.optional(),
+    toolchain: ToolchainConfig.optional(),
+    console: ConsoleConfig.optional(),
+    native: z.record(z.string(), z.unknown()).optional(),
+}).strict().refine(data => !(data.board && data.contract), {
+    message: "Specifying both 'board' and 'contract' is not allowed. Choose one.",
+    path: ['board'],
+});
+/**
+ * Validate a parsed config object against the schema.
+ * Returns the validated config or throws a ZodError with detailed diagnostics.
+ */
+export function validateConfig(config) {
+    return CuttlefishConfigSchema.parse(config);
+}
+/**
+ * Validate a parsed config object, returning a result instead of throwing.
+ * Useful when you want to collect diagnostics without catching exceptions.
+ */
+export function safeValidateConfig(config) {
+    const result = CuttlefishConfigSchema.safeParse(config);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    const errors = result.error.issues.map(issue => {
+        const path = issue.path.join('.');
+        return path ? `${path}: ${issue.message}` : issue.message;
+    });
+    return { success: false, errors };
+}

package/dist/create/board-checklist.d.ts

@@ -0,0 +1,2 @@
+import type { BoardSpec } from './board-spec.js';
+export declare function generateFrameworkChecklist(spec: BoardSpec): string;

package/dist/create/board-checklist.js

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// board-checklist.ts — Generates the "manual framework steps remaining"
+// checklist printed after `cuttlefish board add`. The tool does not apply
+// these edits (they require per-chip judgement), but it tells the user exactly
+// what to do.
+// ---------------------------------------------------------------------------
+export function generateFrameworkChecklist(spec) {
+    const arch = spec.architecture;
+    const a0 = getA0Fallback(spec);
+    const fqbnPrefix = spec.fqbn.split(':').slice(0, 2).join(':') + ':';
+    const lines = [
+        '',
+        '━━━ Manual framework steps remaining ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+        '',
+        'The tool cannot safely apply these (they vary per chip). Check whether',
+        `'${arch}' is already present in each file; if not, add it:`,
+        '',
+        `1. packages/cuttlefish/src/api/board-types.ts`,
+        `   Add \`| '${arch}'\` to the ArchitectureIdentifier union.`,
+        '',
+        `2. packages/hal/src/core/board-types.ts`,
+        `   Same addition (the union is duplicated in both packages).`,
+        '',
+        `3. packages/framework-arduino/src/strategy.ts — freeHeap() (~line 234)`,
+        `   Add \`|| arch === '${arch}'\` to the ESP32-family check.`,
+        '',
+        `4. packages/framework-arduino/src/strategy.ts — isrFunctionAttribute() (~line 1004)`,
+        `   Add \`|| arch === '${arch}'\` to the same check.`,
+        '',
+        `5. packages/cuttlefish/src/ir/heap-analysis.ts (~line 74)`,
+        `   Add \`|| arch === '${arch}'\` to the architecture gate.`,
+        '',
+        `6. packages/framework-arduino/src/profile.ts — PROFILE_VARIANTS`,
+        `   Add \`{ architecture: "${arch}", forcedIncludes: ["<Arduino.h>"] }\`.`,
+        `   Also add a CAPABILITY_TABLE row (mirror esp32; fallbackPins.A0 = ${a0}).`,
+        `   Also add an FQBN_PIN_OVERRIDES entry: \`{ fqbnIncludes: "${fqbnPrefix}", pins: { A0: ${a0} } }\`.`,
+        '',
+        'Then rebuild and test:',
+        '  npm run build --workspaces',
+        '  npx vitest run tests/packages/transpiler/init-scaffold.test.ts',
+        '  npx vitest run tests/packages/framework-arduino/',
+        '',
+    ];
+    return lines.join('\n');
+}
+function getA0Fallback(spec) {
+    // A0 maps to the first ADC1 pin. The analog array lists ADC1 pins in order;
+    // A0 = the GPIO number of the first entry. Parse "GPIOn" → n.
+    const firstAnalog = spec.analog[0];
+    const match = firstAnalog.match(/GPIO(\d+)/);
+    return match ? parseInt(match[1], 10) : 0;
+}

package/dist/create/board-codegen.d.ts

@@ -0,0 +1,9 @@
+import type { BoardSpec } from './board-spec.js';
+export interface ScaffoldBoardResult {
+    createdFiles: string[];
+    checklist: string;
+}
+export declare function scaffoldBoardPackages(spec: BoardSpec, opts?: {
+    force?: boolean;
+    rootDir?: string;
+}): ScaffoldBoardResult;

package/dist/create/board-codegen.js

@@ -0,0 +1,238 @@
+// ---------------------------------------------------------------------------
+// board-codegen.ts — The orchestrator for `cuttlefish board add`.
+// Validates the spec, calls the generators, writes files, edits the
+// registry/tests/README (idempotently), and returns the file list + the
+// framework-anticipation checklist.
+//
+// Pattern: mirrors init-scaffold.ts's scaffoldProject — a writeFile closure
+// + fs.writeFileSync + tracks createdFiles.
+// ---------------------------------------------------------------------------
+import path from 'node:path';
+import fs from 'node:fs';
+import * as Gen from './board-generators.js';
+import { generateFrameworkChecklist } from './board-checklist.js';
+/**
+ * Find the monorepo root by walking up from startDir looking for a package.json
+ * with a "workspaces" array containing "packages/cuttlefish".
+ */
+function findMonorepoRoot(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 20; i++) {
+        const pj = path.join(dir, 'package.json');
+        if (fs.existsSync(pj)) {
+            try {
+                const content = JSON.parse(fs.readFileSync(pj, 'utf8'));
+                if (Array.isArray(content.workspaces) && content.workspaces.some((w) => w.includes('packages/cuttlefish'))) {
+                    return dir;
+                }
+            }
+            catch { /* keep walking */ }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`Could not find monorepo root (no package.json with workspaces including packages/cuttlefish, starting from ${startDir}). Pass --rootDir explicitly.`);
+}
+/** Idempotently insert text into a file after a marker line, if not already present. */
+function insertAfter(filePath, marker, insertion, searchForId) {
+    if (!fs.existsSync(filePath))
+        return false;
+    const content = fs.readFileSync(filePath, 'utf8');
+    if (content.includes(searchForId))
+        return false; // already present
+    const idx = content.indexOf(marker);
+    if (idx === -1)
+        return false;
+    const insertPos = content.indexOf('\n', idx) + 1;
+    const newContent = content.slice(0, insertPos) + insertion + content.slice(insertPos);
+    fs.writeFileSync(filePath, newContent, 'utf8');
+    return true;
+}
+export function scaffoldBoardPackages(spec, opts = {}) {
+    const arch = spec.architecture;
+    const rootDir = opts.rootDir ? path.resolve(opts.rootDir) : findMonorepoRoot(process.cwd());
+    const mcuDir = path.join(rootDir, 'packages', `mcu-${arch}`);
+    const boardDir = path.join(rootDir, 'packages', `board-${arch}`);
+    // Overwrite protection
+    const mcuExists = fs.existsSync(mcuDir);
+    const boardExists = fs.existsSync(boardDir);
+    if ((mcuExists || boardExists) && !opts.force) {
+        throw new Error(`Package directory already exists: ${mcuExists ? mcuDir : boardDir}\n` +
+            `Use --force to overwrite (deletes and regenerates).`);
+    }
+    if (opts.force) {
+        if (mcuExists)
+            fs.rmSync(mcuDir, { recursive: true, force: true });
+        if (boardExists)
+            fs.rmSync(boardDir, { recursive: true, force: true });
+    }
+    const createdFiles = [];
+    const writeFile = (filePath, content) => {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, content, 'utf8');
+        createdFiles.push(filePath);
+    };
+    // --- MCU package ---
+    writeFile(path.join(mcuDir, 'package.json'), Gen.genMcuPackageJson(spec));
+    writeFile(path.join(mcuDir, 'tsconfig.json'), Gen.genMcuTsconfig(spec));
+    writeFile(path.join(mcuDir, 'src', 'index.ts'), Gen.genMcuIndex(spec));
+    writeFile(path.join(mcuDir, 'src', 'pins.ts'), Gen.genMcuPins(spec));
+    writeFile(path.join(mcuDir, 'src', 'peripherals.ts'), Gen.genMcuPeripherals(spec));
+    // --- Board package ---
+    writeFile(path.join(boardDir, 'package.json'), Gen.genBoardPackageJson(spec));
+    writeFile(path.join(boardDir, 'tsconfig.json'), Gen.genBoardTsconfig(spec));
+    writeFile(path.join(boardDir, 'src', 'index.ts'), Gen.genBoardIndex(spec));
+    writeFile(path.join(boardDir, 'src', 'pins.ts'), Gen.genBoardPins(spec));
+    writeFile(path.join(boardDir, 'src', 'analog.ts'), Gen.genBoardAnalog(spec));
+    writeFile(path.join(boardDir, 'src', 'board.ts'), Gen.genBoardNamespace(spec));
+    // --- Idempotent edits to existing files (skipped if target doesn't exist) ---
+    // 1. Root package.json workspaces
+    const rootPjPath = path.join(rootDir, 'package.json');
+    if (fs.existsSync(rootPjPath)) {
+        try {
+            const rootPj = JSON.parse(fs.readFileSync(rootPjPath, 'utf8'));
+            if (Array.isArray(rootPj.workspaces) && !rootPj.workspaces.includes(`packages/mcu-${arch}`)) {
+                rootPj.workspaces.push(`packages/mcu-${arch}`, `packages/board-${arch}`);
+                fs.writeFileSync(rootPjPath, JSON.stringify(rootPj, null, 2) + '\n', 'utf8');
+            }
+        }
+        catch { /* best-effort: skip if package.json isn't valid */ }
+    }
+    // 2. init-scaffold.ts registry entry
+    const scaffoldPath = path.join(rootDir, 'packages', 'cuttlefish', 'src', 'create', 'init-scaffold.ts');
+    const registryEntry = `  {\n    id: '${spec.boardId}',\n    displayName: '${spec.boardName}',\n    isNative: false,\n    architecture: '${arch}',\n    boardPackage: '@typecad/board-${arch}',\n    frameworkPackage: '@typecad/framework-arduino',\n    framework: 'arduino',\n    buildTarget: '${spec.fqbn}',\n    mcu: '${arch}',\n  },\n`;
+    insertAfter(scaffoldPath, "  _knownTargets: KnownTarget[] = [", registryEntry, `'${spec.boardId}'`);
+    // 3. KNOWN_BOARDS test
+    const testPath = path.join(rootDir, 'tests', 'packages', 'transpiler', 'init-scaffold.test.ts');
+    const testEntry = `
+    it("contains ${spec.boardId}", () => {
+      const b = KNOWN_BOARDS.find(b => b.id === '${spec.boardId}');
+      expect(b).toBeDefined();
+      expect(b!.architecture).toBe('${arch}');
+      expect(b!.buildTarget).toBe('${spec.fqbn}');
+    });
+`;
+    // Insert before the closing of the KNOWN_BOARDS describe block
+    if (fs.existsSync(testPath)) {
+        const content = fs.readFileSync(testPath, 'utf8');
+        if (!content.includes(`'${spec.boardId}'`)) {
+            // Find the end of the KNOWN_BOARDS describe block (the `});` after the last `it`)
+            const describeStart = content.indexOf('describe("KNOWN_BOARDS"');
+            if (describeStart !== -1) {
+                // Find the closing `});` of this describe block
+                let depth = 0;
+                let endPos = -1;
+                for (let i = describeStart; i < content.length; i++) {
+                    if (content[i] === '{')
+                        depth++;
+                    if (content[i] === '}') {
+                        depth--;
+                        if (depth === 0) {
+                            endPos = i;
+                            break;
+                        }
+                    }
+                }
+                if (endPos !== -1) {
+                    // Insert before the closing `});`
+                    const insertPos = content.lastIndexOf('\n', endPos);
+                    const newContent = content.slice(0, insertPos + 1) + testEntry + content.slice(insertPos + 1);
+                    fs.writeFileSync(testPath, newContent, 'utf8');
+                }
+            }
+        }
+    }
+    // 4. Profile test file (new)
+    const profileTestDir = path.join(rootDir, 'tests', 'packages', 'framework-arduino');
+    const profileTestPath = path.join(profileTestDir, `${arch}-profile.test.ts`);
+    const archUpper = arch.toUpperCase();
+    const profileTestContent = `// ---------------------------------------------------------------------------
+// Tests for ${spec.boardName} framework-arduino support
+// (profile variant, capabilities, and IRAM_ATTR ISR attribute)
+// ---------------------------------------------------------------------------
+
+import { describe, it, expect } from "vitest";
+import { ArduinoStrategy } from "../../../packages/framework-arduino/src";
+import { resolveArduinoProfile } from "../../../packages/framework-arduino/src/profile";
+import type { ProgramIR, PlatformContext } from "@typecad/cuttlefish/api/shared";
+
+const CTX = { frameworkData: { buildTarget: "${spec.fqbn}" } } as PlatformContext;
+const EMPTY_PROGRAM = { topLevelStatements: [], functions: [] } as any as ProgramIR;
+
+describe("${spec.boardName} framework-arduino support", () => {
+  describe("profile resolution", () => {
+    it("forces <Arduino.h> include for the ${arch} FQBN", () => {
+      const result = resolveArduinoProfile(EMPTY_PROGRAM, CTX);
+      expect(result.forcedIncludes).toContain("<Arduino.h>");
+      expect(result.diagnostics.filter(d => d.code === "TypeCAD_ARDUINO_FUNC_UNKNOWN")).toEqual([]);
+    });
+
+    it("does not emit an A0 shim for the ${arch} FQBN", () => {
+      const program = {
+        topLevelStatements: [
+          { kind: "assign", target: "x", value: { kind: "identifier", value: "A0" } },
+        ],
+        functions: [],
+      } as any as ProgramIR;
+      const result = resolveArduinoProfile(program, CTX);
+      expect(result.shimLines.filter(l => l.startsWith("#define A0"))).toEqual([]);
+      expect(result.diagnostics.find(d => d.code === "TypeCAD_ARDUINO_SHIM_A0")).toBeUndefined();
+    });
+  });
+
+  describe("ArduinoStrategy isrFunctionAttribute", () => {
+    it("returns IRAM_ATTR for the ${arch} FQBN after profile resolution", () => {
+      const strategy = new ArduinoStrategy();
+      strategy.forcedIncludes(EMPTY_PROGRAM, CTX);
+      expect(strategy.isrFunctionAttribute()).toBe("IRAM_ATTR ");
+    });
+
+    it("returns empty string for AVR", () => {
+      const strategy = new ArduinoStrategy();
+      const avrCtx = { frameworkData: { buildTarget: "arduino:avr:uno" } } as PlatformContext;
+      strategy.forcedIncludes(EMPTY_PROGRAM, avrCtx);
+      expect(strategy.isrFunctionAttribute()).toBe("");
+    });
+  });
+});
+`;
+    if (!fs.existsSync(profileTestPath)) {
+        writeFile(profileTestPath, profileTestContent);
+    }
+    // 5. README board table row + available-boards list
+    const readmePath = path.join(rootDir, 'README.md');
+    if (fs.existsSync(readmePath)) {
+        let readme = fs.readFileSync(readmePath, 'utf8');
+        // Board table: insert after the last `| ESP32-` row, before the blank line
+        if (!readme.includes(`@typecad/board-${arch}`)) {
+            const tableRow = `| ${spec.boardName} | \`@typecad/board-${arch}\` | ${spec.mcuName} |\n`;
+            // Find the last board table row
+            const tableMarker = '|---|---|---|';
+            const tableIdx = readme.indexOf(tableMarker);
+            if (tableIdx !== -1) {
+                // Find the next blank line after the table
+                const blankIdx = readme.indexOf('\n\n', tableIdx);
+                if (blankIdx !== -1) {
+                    readme = readme.slice(0, blankIdx + 1) + tableRow + readme.slice(blankIdx + 1);
+                }
+            }
+            // Available-boards list: append the id before the final period
+            const listMarker = 'Available boards:';
+            const listIdx = readme.indexOf(listMarker);
+            if (listIdx !== -1) {
+                const lineEnd = readme.indexOf('\n', listIdx);
+                const line = readme.slice(listIdx, lineEnd);
+                // Insert before the trailing backtick + period
+                const updatedLine = line.replace(/(\`)\.$/, `, \`${spec.boardId}\`.`);
+                readme = readme.slice(0, listIdx) + updatedLine + readme.slice(lineEnd);
+            }
+            fs.writeFileSync(readmePath, readme, 'utf8');
+        }
+    }
+    return {
+        createdFiles,
+        checklist: generateFrameworkChecklist(spec),
+    };
+}

package/dist/create/board-generators.d.ts

@@ -0,0 +1,12 @@
+import type { BoardSpec } from './board-spec.js';
+export declare function genMcuPackageJson(spec: BoardSpec): string;
+export declare function genMcuTsconfig(_spec: BoardSpec): string;
+export declare function genMcuPins(spec: BoardSpec): string;
+export declare function genMcuPeripherals(spec: BoardSpec): string;
+export declare function genMcuIndex(spec: BoardSpec): string;
+export declare function genBoardPackageJson(spec: BoardSpec): string;
+export declare function genBoardTsconfig(spec: BoardSpec): string;
+export declare function genBoardAnalog(_spec: BoardSpec): string;
+export declare function genBoardPins(spec: BoardSpec): string;
+export declare function genBoardIndex(spec: BoardSpec): string;
+export declare function genBoardNamespace(spec: BoardSpec): string;