@typecad/cuttlefish 1.0.0-alpha.13 → 1.0.0-alpha.15

package/README.md

@@ -1,79 +1,82 @@
-# `@typecad/cuttlefish`
-
-TypeScript → C++ transpiler for embedded firmware. Targets native (desktop),
-Arduino, and bare-metal MCU builds from a single TypeScript codebase.
-
-`cuttlefish` is the command-line tool at the center of the [TypeCAD](https://cuttlefish.typecad.net)
-toolchain: it loads `cuttlefish.config.ts`, transpiles TypeScript firmware to
-C++, and can chain compile, upload, and serial-monitor steps.
-
-## Quick start
-
-From a project root containing `cuttlefish.config.ts`:
-
-```bash
-npx @typecad/cuttlefish build
-npx @typecad/cuttlefish build --compile --upload --port COM4
-npx @typecad/cuttlefish build --compile --upload --monitor --port COM4 --baud 115200
-```
-
-Scaffold a starter project with the built-in wizard:
-
-```bash
-npx @typecad/cuttlefish create --board arduino:avr:uno --framework arduino
-```
-
-## Commands
-
-| Command | Description |
-| --- | --- |
-| `cuttlefish build` | Transpile the entry file (default). Accepts `--compile`, `--upload`, `--monitor`, `--port`, `--baud`. |
-| `cuttlefish create` | Generate a starter project and `cuttlefish.config.ts`. |
-| `cuttlefish board-add` | Add a new board package via the board-codegen scaffolder. |
-| `cuttlefish preview` | Launch the browser preview server for a UI project. |
-| `cuttlefish map-error <mapFile>` | Map a C++ compiler error back to its TypeScript source location. |
-| `cuttlefish gen-decls` | Generate type declaration stubs. |
-| `cuttlefish gen-libdefs <input.ts>` | Generate library definition stubs for third-party imports. |
-
-### Flags (for `build`)
-
-- `--compile` — transpile, then compile via the active framework's toolchain (`arduino-cli` for Arduino, `g++` for native).
-- `--upload` — flash firmware to the board (implies `--compile`).
-- `--monitor` — open a serial monitor after upload.
-- `--port <port>` — serial port for upload/monitor (e.g. `COM4`, `/dev/ttyUSB0`).
-- `--baud <rate>` — serial monitor baud rate.
-
-## Configuration
-
-The CLI reads `cuttlefish.config.ts` from the current working directory and
-treats it as the source of truth. When no config file is present, command-line
-flags such as `--fqbn` and `--board` supply board and build settings.
-
-```ts
-import type { CuttlefishConfig } from '@typecad/cuttlefish/api';
-
-const config: CuttlefishConfig = {
-  entry: './src/main.ts',
-  target: 'esp32',
-  mcu: '@typecad/mcu-esp32',
-  board: '@typecad/board-esp32-devkit',
-  framework: '@typecad/framework-arduino',
-};
-
-export default config;
-```
-
-## Ecosystem
-
-`@typecad/cuttlefish` is the transpiler core. It pairs with sibling packages:
-
-- [`@typecad/hal`](https://cuttlefish.typecad.net) — hardware abstraction (GPIO, I2C, SPI, UART) as regular TypeScript.
-- [`@typecad/ui`](https://cuttlefish.typecad.net) — HTML/CSS-driven graphics for microcontroller displays.
-- [`@typecad/expect`](https://cuttlefish.typecad.net) — hardware test framework (vitest-style assertions over serial).
-- [`@typecad/framework-arduino`](https://cuttlefish.typecad.net) — Arduino framework code-gen strategy.
-- [`@typecad/framework-native`](https://cuttlefish.typecad.net) — native desktop C++ code-gen strategy.
-- `@typecad/mcu-*` and `@typecad/board-*` — silicon- and board-level pin/peripheral definitions.
-
-## License
-
-MIT
+# `@typecad/cuttlefish`
+
+TypeScript → C++ transpiler for embedded firmware. Targets native (desktop)
+and Zephyr-supported embedded boards from a single TypeScript codebase.
+
+`cuttlefish` is the command-line tool at the center of the [TypeCAD](https://cuttlefish.typecad.net)
+toolchain: it loads `cuttlefish.config.ts`, transpiles TypeScript firmware to
+C++, and can chain compile, upload, and serial-monitor steps.
+
+## Quick start
+
+From a project root containing `cuttlefish.config.ts`:
+
+```bash
+npx @typecad/cuttlefish build
+npx @typecad/cuttlefish build --compile --upload --port COM4
+npx @typecad/cuttlefish build --compile --upload --monitor --port COM4 --baud 115200
+```
+
+Scaffold a starter project with the built-in wizard:
+
+```bash
+npx @typecad/cuttlefish create --board esp32s3
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `cuttlefish build` | Transpile the entry file (default). Accepts `--compile`, `--upload`, `--monitor`, `--port`, `--baud`. |
+| `cuttlefish create` | Generate a starter project and `cuttlefish.config.ts`. |
+| `cuttlefish preview` | Launch the browser preview server for a UI project. |
+| `cuttlefish gen-decls <file.h\|file.cpp\|--all <dir>>` | Generate `.d.ts` declaration stubs from C++ headers. |
+| `cuttlefish doctor` | Check the active framework's environment (e.g. toolchain + board support). |
+| `cuttlefish licenses [--all] [--strict]` | Scan this project's libraries for SPDX licenses. |
+| `cuttlefish board sync [zephyr-base]` | Rebuild the local board catalog from your Zephyr tree's board DTS files. The catalog is machine-local — there is no compiled-in board database; builds create and refresh it automatically, this command forces a rebuild. |
+| `cuttlefish board regen` | Regenerate the project-local board module (`.cuttlefish/board.ts` + `board.json`). Builds also regenerate it automatically whenever any input changes (config board, catalog, or Zephyr tree). |
+| `cuttlefish library <search\|install\|init\|validate>` | The cuttlefish library package manager (npm keywords are the catalog). |
+
+### Flags (for `build`)
+
+- `--compile` — transpile, then compile via the active framework's toolchain (`west` for Zephyr, `g++` for native).
+- `--upload` — flash firmware to the board (requires `--compile`).
+- `--monitor` — open a serial monitor after upload.
+- `--port <port>` — serial port for upload/monitor (e.g. `COM4`, `/dev/ttyUSB0`).
+- `--baud <rate>` — serial monitor baud rate.
+
+## Configuration
+
+The CLI reads `cuttlefish.config.ts` from the current working directory and
+treats it as the source of truth. When no config file is present, command-line
+flags such as `--board` and `--build-target` supply board and build settings.
+
+```ts
+import type { CuttlefishConfig } from '@typecad/cuttlefish/api';
+
+const config: CuttlefishConfig = {
+  entry: './src/main.ts',
+  board: 'xiao_ble/nrf52840',
+  framework: '@typecad/framework-zephyr',
+};
+
+export default config;
+```
+
+## Ecosystem
+
+`@typecad/cuttlefish` is the transpiler core. It pairs with sibling packages:
+
+- [`@typecad/hal`](https://cuttlefish.typecad.net) — hardware abstraction (GPIO, I2C, SPI, UART) as regular TypeScript.
+- [`@typecad/ui`](https://cuttlefish.typecad.net) — HTML/CSS-driven graphics for microcontroller displays.
+- [`@typecad/expect`](https://cuttlefish.typecad.net) — hardware test framework (vitest-style assertions over serial).
+- [`@typecad/framework-zephyr`](https://cuttlefish.typecad.net) — Zephyr RTOS framework (build, flashing, and the bundled Zephyr toolchain installer).
+
+Built in, no separate package: the **native** desktop target (`framework:
+'@typecad/framework-native'` resolves inside cuttlefish) and the **safety**
+engine (verified GPIO reads, ISO 26262 analysis — author via
+`@typecad/cuttlefish/safety`).
+
+## License
+
+MIT

package/assets/editor-extensions/typecad-debug/README.md

@@ -0,0 +1,141 @@
+# TypeCAD Debug
+
+A Visual Studio Code extension that bridges VSCode's breakpoint gutter to the
+TypeCAD `Serial.print` debug pipeline. Set breakpoints in your `.ts` source;
+this extension syncs them to `.cuttlefish/breakpoints.json`, which the
+`@typecad/cuttlefish` transpiler reads (when run with `--debug`) to inject
+`Serial.println` instrumentation that reports variable values and lets you
+step through execution.
+
+This is the producer half of a two-part system. The consumer half lives in
+[`@typecad/cuttlefish`](../../packages/cuttlefish/src/debug/) and is the
+authoritative source for the on-disk schema and matching behavior described
+below.
+
+## Install
+
+This package is `private: true` and is **not** published to the npm registry
+or the VS Code Marketplace. Build the VSIX locally:
+
+```sh
+cd packages/vscode-typecad-debug
+npm install
+npm run compile
+npm run package        # produces vscode-typecad-debug-0.2.0.vsix
+code --install-extension vscode-typecad-debug-0.2.0.vsix
+```
+
+## Usage
+
+1. Open the Command Palette (`Ctrl/Cmd+Shift+P`).
+2. Run **TypeCAD: Debug with Breakpoints** — or set red-dot breakpoints in the
+   gutter and run `cuttlefish build --debug` in a terminal.
+3. Breakpoints (including conditional breakpoints and logpoints) are written
+   to `.cuttlefish/breakpoints.json` on every breakpoint change and on every
+   `.ts` save.
+4. Upload the instrumented firmware and open a serial monitor (`--monitor`).
+   At each breakpoint the firmware prints the location, the original source
+   line, and the variables in scope, then halts. Two keys are available:
+   - **ENTER** — continue (the breakpoint will halt here again the next time
+     execution reaches it).
+   - **`s`** — skip this breakpoint for the rest of the run: it won't halt
+     here again until the device reboots. Other breakpoints are unaffected.
+
+### Commands
+
+| Command | Title |
+|---|---|
+| `typecad-debug.toggleBreakpoint` | TypeCAD: Toggle Breakpoint (bound to `F9` in `.ts` files) |
+| `typecad-debug.clearAllBreakpoints` | TypeCAD: Clear All Breakpoints |
+| `typecad-debug.debugWithBreakpoints` | TypeCAD: Debug with Breakpoints |
+| `typecad-debug.syncBreakpoints` | TypeCAD: Sync Breakpoints from VS Code |
+| `typecad-debug.generateDeclaration` | TypeCAD: Generate Declaration from C++ |
+
+### Enabling instrumentation
+
+Breakpoints are only injected when cuttlefish is run with `--debug`:
+
+```sh
+cuttlefish build --debug                                    # uses cuttlefish.config.ts entry
+cuttlefish src/index.ts --debug --compile --upload --port COM4
+```
+
+See `cuttlefish --help` for the full `--debug` description.
+
+## `.cuttlefish/breakpoints.json` schema
+
+The file lives at the project root (or any ancestor of the entry file's
+directory). Each entry uses **the basename** of the source file as `file`
+(this is the only path form that matches reliably on both Windows and POSIX
+under cuttlefish's basename-matching loader):
+
+```jsonc
+{
+  "breakpoints": [
+    { "file": "index.ts", "line": 12 },
+    { "file": "index.ts", "line": 27, "condition": "counter > 5" },
+    { "file": "sensor.ts", "line": 8, "logMessage": "reading = {value}" }
+  ]
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `file` | string | yes | Source file **basename** (e.g. `index.ts`). |
+| `line` | number | yes | 1-indexed line number. `0` is dropped. |
+| `condition` | string | no | Conditional expression; `===`/`!==` are auto-normalized to `==`/`!=` for C++. |
+| `logMessage` | string | no | Logpoint with `{variable}` interpolation. When present, the breakpoint logs instead of halting. |
+
+Two source files sharing the same basename in one project will share
+breakpoints — acceptable for typical single-program projects.
+
+## Native debugging on ESP32-S3
+
+For ESP32-S3, this extension's printf instrumentation is superseded by a
+native GDB path. `cuttlefish build --debug` on `esp32s3` emits `#line`
+directives in the generated C++ and writes `.vscode/launch.json` +
+`tasks.json` (at the cuttlefish project root, where VS Code reads them) plus
+`.cuttlefish/openocd.cfg` next to the build output. Press **F5** in VS Code
+and the generated config attaches GDB to the chip's built-in USB-Serial-JTAG
+— one USB cable, no external probe.
+
+For Zephyr projects (`@typecad/framework-zephyr` on an esp32s3 board),
+`cuttlefish create` writes the same starter artifacts at project creation —
+`.vscode/launch.json` + `tasks.json` + `src/out/.cuttlefish/openocd.cfg` —
+so F5 works on a fresh project before any build: the preLaunch task runs
+`cuttlefish build --compile --upload --debug`, which builds, flashes, and
+re-merges the launch entry with the build-cache-resolved gdbPath. (The
+starter gdbPath is probed from `$ZEPHYR_SDK_INSTALL_DIR`, the
+zephyr-installer micromamba layout, or `~/zephyr-sdk-*`.)
+
+`launch.json` ships a single **`cortex-debug`** configuration (`servertype:
+"openocd"`, or `"jlink"` when the board's probe method is a JLink runner).
+The cortex-debug extension starts OpenOCD itself as a child process, passing
+the generated `.cuttlefish/openocd.cfg`; the `preLaunchTask` is just
+`build + flash` — no competing OpenOCD process. Install the cortex-debug
+extension (ESP32 targets also need OpenOCD — the framework probes the
+openocd-esp32 install layout or the Zephyr SDK's own openocd), and set the
+serial port through the `CUTTLEFISH_PORT` env var or pass
+`--port`.
+
+The printf instrumentation documented below remains the path for targets
+that don't ship a native GDB path yet.
+
+## Limitations
+
+- This is a printf-based instrumentation shim, not a DAP debug
+  adapter. There is no native step/step-in/step-out — each breakpoint halts
+  until ENTER (continue) or `s` (skip this breakpoint for the run) is received
+  over serial. **On ESP32-S3, use the native GDB path above instead** — it
+  provides full stepping, call stacks, and TS-named variable inspection.
+- The scope analyzer captures module-scope identifiers plus locals and
+  parameters in the enclosing function. Member access and arbitrary
+  expressions are not resolved; `{ value }` in a logpoint emits the literal
+  `"{value}"` if `value` is not in scope.
+- Baud rate is fixed by the framework's console shim regardless of the CLI
+  `--baud` value.
+- **Target-specific output:** under @typecad/framework-zephyr the injected
+  code routes through the board console (`printk`/shell backend) and blocks on
+  a getchar-equivalent with the idle thread feeding — so a debug build must
+  have a serial monitor attached (e.g. `cuttlefish build --monitor`), or it
+  will hang at the first breakpoint until power is cycled.

package/assets/editor-extensions/typecad-debug/out/extension.js

@@ -0,0 +1,347 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// vscode-typecad-debug — VSCode Extension
+//
+// Tracks breakpoints in TypeScript files and syncs them to
+// .cuttlefish/breakpoints.json for the TypeCAD debug preprocessor.
+// Also auto-generates .d.ts declaration files from C++ sources.
+//
+// The breakpoint file is read by @typecad/cuttlefish when invoked with
+// `--debug`. The preprocessor injects Serial.println instrumentation at the
+// recorded line numbers; run `cuttlefish build --debug` (or `cuttlefish
+// index.ts --debug`) to enable it.
+//
+// IMPORTANT: the `file` field in each breakpoint entry is written as the
+// basename only (e.g. "index.ts"). The cuttlefish loader matches breakpoints
+// by exact → basename → suffix, and basename matching is the only strategy
+// that works identically on Windows (backslash) and POSIX (forward slash)
+// without slash normalization. The trade-off is that two files with the same
+// basename in one project share breakpoints — acceptable for typical
+// single-sketch Arduino projects.
+// ---------------------------------------------------------------------------
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activate = activate;
+exports.deactivate = deactivate;
+const vscode = __importStar(require("vscode"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Relative to the workspace root. */
+const BREAKPOINTS_DIR = '.cuttlefish';
+const BREAKPOINTS_FILE = 'breakpoints.json';
+// ---------------------------------------------------------------------------
+// Extension Activation
+// ---------------------------------------------------------------------------
+function activate(context) {
+    console.log('TypeCAD Debug extension activated');
+    const breakpointTracker = new BreakpointTracker();
+    const toggleCmd = vscode.commands.registerCommand('typecad-debug.toggleBreakpoint', () => breakpointTracker.toggleBreakpoint());
+    const clearAllCmd = vscode.commands.registerCommand('typecad-debug.clearAllBreakpoints', () => breakpointTracker.clearAllBreakpoints());
+    const debugCmd = vscode.commands.registerCommand('typecad-debug.debugWithBreakpoints', () => breakpointTracker.debugWithBreakpoints());
+    const syncCmd = vscode.commands.registerCommand('typecad-debug.syncBreakpoints', () => breakpointTracker.syncFromVSCode());
+    // Auto-sync breakpoints when saving TypeScript files.
+    const saveListener = vscode.workspace.onDidSaveTextDocument((doc) => {
+        if (doc.fileName.endsWith('.ts') && !doc.fileName.includes('node_modules')) {
+            breakpointTracker.syncFromVSCode();
+        }
+    });
+    const declGenerator = new DeclarationGenerator();
+    const genDeclCmd = vscode.commands.registerCommand('typecad-debug.generateDeclaration', () => declGenerator.generateForCurrentFile());
+    // Auto-generate a .d.ts when a C++ file is saved and the sidecar is missing.
+    const cppSaveListener = vscode.workspace.onDidSaveTextDocument((doc) => {
+        if (doc.fileName.endsWith('.cpp') && !doc.fileName.includes('node_modules')) {
+            declGenerator.checkAndGenerate(doc.fileName);
+        }
+    });
+    context.subscriptions.push(toggleCmd, clearAllCmd, debugCmd, syncCmd, saveListener, breakpointTracker, genDeclCmd, cppSaveListener, declGenerator);
+}
+function deactivate() { }
+// ---------------------------------------------------------------------------
+// Breakpoint Tracker
+// ---------------------------------------------------------------------------
+class BreakpointTracker {
+    constructor() {
+        /** file fsPath → line → Breakpoint. Keys are full fsPaths for dedup. */
+        this.breakpoints = new Map();
+        this._onDidChange = new vscode.EventEmitter();
+        this.onDidChange = this._onDidChange.event;
+        this.loadFromFile();
+        // VSCode breakpoint gutter changes (red dots, conditions, logpoints).
+        vscode.debug.onDidChangeBreakpoints(() => {
+            console.log('TypeCAD: Breakpoint change detected');
+            this.syncFromVSCode();
+        });
+        // Re-sync when switching editor so a stale in-memory map doesn't survive.
+        vscode.window.onDidChangeActiveTextEditor((editor) => {
+            if (editor) {
+                this.syncFromVSCode();
+            }
+        });
+    }
+    /**
+     * Toggle a breakpoint at the current cursor position.
+     */
+    toggleBreakpoint() {
+        const editor = vscode.window.activeTextEditor;
+        if (!editor)
+            return;
+        const filePath = editor.document.uri.fsPath;
+        const fileName = path.basename(filePath);
+        const line = editor.selection.active.line + 1; // 1-indexed
+        if (!this.breakpoints.has(fileName)) {
+            this.breakpoints.set(fileName, new Map());
+        }
+        const fileBreakpoints = this.breakpoints.get(fileName);
+        if (fileBreakpoints.has(line)) {
+            fileBreakpoints.delete(line);
+            vscode.window.showInformationMessage(`TypeCAD: Breakpoint removed at line ${line}`);
+        }
+        else {
+            fileBreakpoints.set(line, { file: fileName, line });
+            vscode.window.showInformationMessage(`TypeCAD: Breakpoint added at line ${line}`);
+        }
+        this.saveToFile();
+        this._onDidChange.fire();
+    }
+    /**
+     * Clear all breakpoints.
+     */
+    clearAllBreakpoints() {
+        this.breakpoints.clear();
+        this.saveToFile();
+        vscode.window.showInformationMessage('TypeCAD: All breakpoints cleared');
+        this._onDidChange.fire();
+    }
+    /**
+     * Save breakpoints, then run `cuttlefish build --debug` in a terminal.
+     */
+    async debugWithBreakpoints() {
+        const editor = vscode.window.activeTextEditor;
+        if (!editor) {
+            vscode.window.showErrorMessage('TypeCAD: No active editor');
+            return;
+        }
+        this.saveToFile();
+        const terminal = vscode.window.createTerminal('TypeCAD Debug');
+        terminal.show();
+        terminal.sendText('npx cuttlefish build --debug');
+    }
+    /**
+     * Sync breakpoints from VSCode's built-in breakpoint system.
+     * Captures conditional breakpoints and logpoints.
+     * REPLACES all breakpoints with the current VS Code state.
+     */
+    syncFromVSCode() {
+        const vscodeBreakpoints = vscode.debug.breakpoints;
+        console.log(`TypeCAD: Syncing ${vscodeBreakpoints.length} breakpoints from VS Code`);
+        this.breakpoints.clear();
+        let count = 0;
+        for (const bp of vscodeBreakpoints) {
+            if (bp instanceof vscode.SourceBreakpoint) {
+                // Key the in-memory map by basename so saveToFile and the toggle path
+                // agree on a single canonical key. The loader matches by basename.
+                const filePath = bp.location.uri.fsPath;
+                const fileName = path.basename(filePath);
+                const line = bp.location.range.start.line + 1; // 1-indexed
+                if (!this.breakpoints.has(fileName)) {
+                    this.breakpoints.set(fileName, new Map());
+                }
+                this.breakpoints.get(fileName).set(line, {
+                    file: fileName,
+                    line,
+                    condition: bp.condition,
+                    logMessage: bp.logMessage, // LogMessageBreakpoint has this property
+                });
+                count++;
+            }
+        }
+        this.saveToFile();
+        vscode.window.setStatusBarMessage(`TypeCAD: Synced ${count} breakpoints`, 3000);
+        console.log(`TypeCAD: Synced ${count} breakpoints to file`);
+    }
+    /**
+     * Load breakpoints from .cuttlefish/breakpoints.json
+     */
+    loadFromFile() {
+        const workspaceFolders = vscode.workspace.workspaceFolders;
+        if (!workspaceFolders || workspaceFolders.length === 0)
+            return;
+        const filePath = path.join(workspaceFolders[0].uri.fsPath, BREAKPOINTS_DIR, BREAKPOINTS_FILE);
+        if (!fs.existsSync(filePath))
+            return;
+        try {
+            const content = fs.readFileSync(filePath, 'utf8');
+            const map = JSON.parse(content);
+            for (const bp of map.breakpoints ?? []) {
+                if (!this.breakpoints.has(bp.file)) {
+                    this.breakpoints.set(bp.file, new Map());
+                }
+                this.breakpoints.get(bp.file).set(bp.line, bp);
+            }
+        }
+        catch (err) {
+            console.error('TypeCAD: Failed to load breakpoints:', err);
+        }
+    }
+    /**
+     * Save breakpoints to .cuttlefish/breakpoints.json atomically.
+     * Writes to a temp file then renames, so a watching transpiler never reads
+     * a half-written file.
+     */
+    saveToFile() {
+        const workspaceFolders = vscode.workspace.workspaceFolders;
+        if (!workspaceFolders || workspaceFolders.length === 0) {
+            console.log('TypeCAD: No workspace folder, skipping save');
+            return;
+        }
+        const dirPath = path.join(workspaceFolders[0].uri.fsPath, BREAKPOINTS_DIR);
+        const filePath = path.join(dirPath, BREAKPOINTS_FILE);
+        const tmpPath = `${filePath}.tmp`;
+        try {
+            if (!fs.existsSync(dirPath)) {
+                fs.mkdirSync(dirPath, { recursive: true });
+            }
+        }
+        catch (mkdirErr) {
+            console.error('TypeCAD: Failed to create directory:', mkdirErr);
+            vscode.window.showErrorMessage(`TypeCAD: Failed to create ${BREAKPOINTS_DIR} directory: ${mkdirErr}`);
+            return;
+        }
+        const map = { breakpoints: [] };
+        for (const [, fileBreakpoints] of this.breakpoints) {
+            for (const [, bp] of fileBreakpoints) {
+                map.breakpoints.push(bp);
+            }
+        }
+        // Stable order for clean diffs and reproducible output.
+        map.breakpoints.sort((a, b) => {
+            if (a.file !== b.file)
+                return a.file.localeCompare(b.file);
+            return a.line - b.line;
+        });
+        try {
+            fs.writeFileSync(tmpPath, JSON.stringify(map, null, 2));
+            fs.renameSync(tmpPath, filePath);
+            console.log(`TypeCAD: Saved ${map.breakpoints.length} breakpoints to ${filePath}`);
+        }
+        catch (err) {
+            // Best effort: clean up the temp file on failure.
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch { }
+            console.error('TypeCAD: Failed to save breakpoints:', err);
+            vscode.window.showErrorMessage(`TypeCAD: Failed to save breakpoints: ${err}`);
+        }
+    }
+    dispose() {
+        this._onDidChange.dispose();
+    }
+}
+// ---------------------------------------------------------------------------
+// Declaration Generator
+// ---------------------------------------------------------------------------
+class DeclarationGenerator {
+    /**
+     * Generate a .d.ts sidecar for a C++ file if one is not already present.
+     */
+    async checkAndGenerate(cppPath) {
+        const declPath = cppPath.replace(/\.cpp$/i, '.d.ts');
+        if (fs.existsSync(declPath)) {
+            return; // Already exists — never clobber.
+        }
+        const result = await this.generateDeclaration(cppPath, declPath);
+        if (result) {
+            vscode.window.showInformationMessage(`TypeCAD: Generated ${path.basename(declPath)} from ${path.basename(cppPath)}. Review and adjust types if needed.`);
+        }
+    }
+    /**
+     * Generate a declaration for the currently active C++ file.
+     */
+    async generateForCurrentFile() {
+        const editor = vscode.window.activeTextEditor;
+        if (!editor) {
+            vscode.window.showErrorMessage('TypeCAD: No active editor');
+            return;
+        }
+        const filePath = editor.document.uri.fsPath;
+        if (!filePath.endsWith('.cpp')) {
+            vscode.window.showErrorMessage('TypeCAD: Active file must be a .cpp file');
+            return;
+        }
+        const declPath = filePath.replace(/\.cpp$/i, '.d.ts');
+        const result = await this.generateDeclaration(filePath, declPath);
+        if (result) {
+            vscode.window.showInformationMessage(`TypeCAD: Generated ${path.basename(declPath)}`);
+            const doc = await vscode.workspace.openTextDocument(result);
+            await vscode.window.showTextDocument(doc);
+        }
+        else {
+            vscode.window.showWarningMessage('TypeCAD: No classes or constants found in C++ file');
+        }
+    }
+    /**
+     * Generate a .d.ts file from a C++ file via the cuttlefish CLI.
+     * Uses the monorepo source directly when developing inside this repo,
+     * falls back to `npx cuttlefish` for installed users.
+     */
+    async generateDeclaration(cppPath, declPath) {
+        return new Promise((resolve) => {
+            const workspaceFolders = vscode.workspace.workspaceFolders;
+            // Local-CLI fallback for development inside the typecode monorepo.
+            const localCliPath = workspaceFolders
+                ? path.join(workspaceFolders[0].uri.fsPath, 'packages/cuttlefish/src/cli.ts')
+                : null;
+            const cmd = localCliPath && fs.existsSync(localCliPath)
+                ? `npx tsx "${localCliPath}" gen-decls "${cppPath}"`
+                : `npx cuttlefish gen-decls "${cppPath}"`;
+            (0, node_child_process_1.exec)(cmd, { cwd: workspaceFolders?.[0]?.uri.fsPath }, (error) => {
+                if (error) {
+                    console.error('TypeCAD: Failed to generate declaration:', error);
+                    vscode.window.showErrorMessage(`TypeCAD: Failed to generate declaration: ${error.message}`);
+                    resolve(null);
+                    return;
+                }
+                resolve(fs.existsSync(declPath) ? declPath : null);
+            });
+        });
+    }
+    dispose() { }
+}
+//# sourceMappingURL=extension.js.map