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

package/dist/utils/cli.js

@@ -13,12 +13,11 @@ export function printHelp() {
     console.log(`  cuttlefish create [name] [options]`);
     console.log(`  cuttlefish build [options]`);
     console.log(`  cuttlefish preview [--config <path>] [--port <port>]`);
-    console.log(`  cuttlefish gen-libdefs <input.ts>`);
-    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 board sync [zephyr-base]            Rebuild the board catalog from your Zephyr tree (after west update)`);
+    console.log(`  cuttlefish board regen                          Regenerate the project-local board module (.cuttlefish/board.ts + board.json)`);
     console.log(`  cuttlefish doctor                              Check the active framework's environment (e.g. toolchain + board core)`);
-    console.log(`  cuttlefish licenses [--all] [--strict]          Scan this project's Arduino libraries for SPDX licenses (--all: every installed library)`);
+    console.log(`  cuttlefish licenses [--all] [--strict]          Scan this project's libraries for SPDX licenses (--all: every installed library)`);
     console.log();
     console.log(chalk.cyan(`LIBRARY PACKAGES`) + chalk.gray(` (npm keywords are the catalog)`));
     console.log();
@@ -81,7 +80,7 @@ export function printHelp() {
     console.log();
     console.log(`  --build-target <id>     Framework-specific build target identifier.`);
     console.log(`                          Required by most frameworks for --compile and --upload.`);
-    console.log(`                          Example: arduino:avr:uno, esp32:esp32:esp32dev, cmake:Debug`);
+    console.log(`                          Example: blackpill_f411ce/stm32f411xe, esp32s3_devkitc/esp32s3/procpu`);
     console.log();
     console.log(`  --port <port>           Serial port of the connected board.`);
     console.log(`                          Required for --upload and --monitor.`);
@@ -91,7 +90,7 @@ export function printHelp() {
     console.log();
     console.log(`  --framework <pkg>       Framework package for code generation strategy.`);
     console.log(`                          Overrides cuttlefish.config.ts framework setting.`);
-    console.log(`                          Example: @typecad/framework-arduino, @typecad/framework-native`);
+    console.log(`                          Example: @typecad/framework-zephyr, @typecad/framework-native`);
     console.log();
     console.log(chalk.cyan(`BUILD COMMAND`));
     console.log();
@@ -138,17 +137,23 @@ export function printHelp() {
     console.log(chalk.cyan(`PROJECT CREATION`));
     console.log();
     console.log(`  create [name]           Create a new TypeCAD project`);
-    console.log(`                          Interactive wizard if no --target flag.`);
+    console.log(`                          Interactive wizard (also with --board on a terminal;`);
+    console.log(`                          piped/CI runs are non-interactive).`);
     console.log();
-    console.log(`  --target, -t <id>       Target platform (native, arduino-uno, esp32-devkit)`);
+    console.log(`  --target, -t <id>       Target platform (native, or any catalog board)`);
     console.log();
     console.log(`  --board, -b <id>        Alias for --target`);
     console.log();
-    console.log(`  --framework, -f <pkg>   Framework (arduino, avr, native)`);
+    console.log(`  --framework, -f <pkg>   Framework (zephyr, native)`);
     console.log();
-    console.log(`  --baud <rate>           Serial baud rate (default: 9600)`);
+    console.log(`  --probe, --flash <id>   Probe/flash method (stlink, dfu, jlink, ...) —`);
+    console.log(`                          what uploads AND debugs the board`);
     console.log();
-    console.log(`  --no-sketch             Skip generating starter sketch`);
+    console.log(`  --port, -p <port>       Serial port the board is on (COM10, /dev/ttyACM0)`);
+    console.log();
+    console.log(`  --baud <rate>           Serial baud rate (default: 115200 on Zephyr, 9600 otherwise)`);
+    console.log();
+    console.log(`  --no-starter            Skip generating the starter program`);
     console.log();
     console.log(`  --outDir, -o <path>     Output directory (default: ./<name>)`);
     console.log();
@@ -160,8 +165,10 @@ export function printHelp() {
     console.log(chalk.gray(`  # Native desktop project`));
     console.log(`  cuttlefish create my-app --target native`);
     console.log();
-    console.log(chalk.gray(`  # Arduino Uno project`));
-    console.log(`  cuttlefish create my-project --target arduino-uno`);
+    console.log(chalk.gray(`  # Zephyr board project`));
+    console.log(`  cuttlefish create my-project --target blackpill-f411ce`);
+    console.log();
+    console.log(chalk.gray(`  # Custom STM32F411 hardware — generated Zephyr board`));
     console.log();
     console.log(chalk.gray(`  # Build using config entry point`));
     console.log(`  cuttlefish build --compile --upload --port COM4`);
@@ -172,29 +179,23 @@ export function printHelp() {
     console.log(chalk.gray(`  # Transpile to generic C++`));
     console.log(`  cuttlefish src/main.ts`);
     console.log();
-    console.log(chalk.gray(`  # Transpile using Arduino framework`));
-    console.log(`  cuttlefish sketch.ts --framework @typecad/framework-arduino --outDir ./build`);
+    console.log(chalk.gray(`  # Transpile using the Zephyr framework`));
+    console.log(`  cuttlefish main.ts --framework @typecad/framework-zephyr --outDir ./build`);
     console.log();
-    console.log(chalk.gray(`  # Transpile and compile for Arduino Uno`));
-    console.log(`  cuttlefish sketch.ts --framework @typecad/framework-arduino --compile --build-target arduino:avr:uno`);
+    console.log(chalk.gray(`  # Transpile and compile for the Black Pill`));
+    console.log(`  cuttlefish main.ts --framework @typecad/framework-zephyr --compile --build-target blackpill_f411ce/stm32f411xe`);
     console.log();
     console.log(chalk.gray(`  # Transpile, compile, and upload`));
-    console.log(`  cuttlefish sketch.ts --framework @typecad/framework-arduino --compile --upload --build-target arduino:avr:uno --port COM4`);
+    console.log(`  cuttlefish main.ts --framework @typecad/framework-zephyr --compile --upload --build-target blackpill_f411ce/stm32f411xe --port COM4`);
     console.log();
     console.log(chalk.gray(`  # Full chain: transpile → compile → upload → monitor`));
-    console.log(`  cuttlefish sketch.ts --framework @typecad/framework-arduino --compile --upload --monitor --build-target arduino:avr:uno --port COM4 --baud 115200`);
+    console.log(`  cuttlefish main.ts --framework @typecad/framework-zephyr --compile --upload --monitor --build-target blackpill_f411ce/stm32f411xe --port COM4 --baud 115200`);
     console.log();
     console.log(chalk.gray(`  # Watch mode: auto-retranspile on changes`));
-    console.log(`  cuttlefish sketch.ts --watch`);
-    console.log();
-    console.log(chalk.gray(`  # Watch and auto-compile for Arduino`));
-    console.log(`  cuttlefish sketch.ts --framework @typecad/framework-arduino --watch --compile --build-target arduino:avr:uno`);
-    console.log();
-    console.log(chalk.gray(`  # Generate library definitions from imports`));
-    console.log(`  cuttlefish gen-libdefs src/sensor.ts`);
+    console.log(`  cuttlefish main.ts --watch`);
     console.log();
-    console.log(chalk.gray(`  # Map a C++ error to TypeScript source`));
-    console.log(`  cuttlefish map-error .build/sketch.cpp.map --line 42 --column 5 --message "undefined reference"`);
+    console.log(chalk.gray(`  # Watch and auto-compile`));
+    console.log(`  cuttlefish main.ts --framework @typecad/framework-zephyr --watch --compile --build-target blackpill_f411ce/stm32f411xe`);
     console.log();
 }
 function readFlag(argv, flag) {
@@ -240,10 +241,11 @@ function parsePipelineCommand(argv, command, inputFile) {
     const emitMapsFlag = readFirstFlagValue(argv, ["--emit-maps"]);
     const buildTarget = readFirstFlagValue(argv, ["--build-target"]);
     const port = readFirstFlagValue(argv, ["--port"]);
-    // Default to undefined (NOT 9600) so the build/upload/monitor flow's
-    // `options.baud ?? config.console.baudRate` falls through to the configured
-    // baud. Hardcoding 9600 here shadowed config.console.baudRate whenever --baud
-    // was absent (the monitor then opened the port at 9600, ignoring the config).
+    const probeFlag = readFirstFlagValue(argv, ["--probe", "--flash"]);
+    // Default to undefined (NOT a hardcoded baud) so the build/upload/monitor
+    // flow falls through to the framework's monitor default when --baud is
+    // absent. Hardcoding 9600 here forced the monitor to open the port at 9600
+    // and ignore --baud given elsewhere.
     const baud = readNumberFlag(argv, ["--baud"]);
     const frameworkFlag = readFirstFlagValue(argv, ["--framework"]);
     const compile = readBooleanFlag(argv, ["--compile"]);
@@ -307,8 +309,8 @@ function parsePipelineCommand(argv, command, inputFile) {
         throw new Error("--upload requires --compile.");
     }
     // Note: port validation is deferred to the build path, which checks the
-    // effective port (CLI --port flag OR config.console.port). This allows
-    // setting the port in cuttlefish.config.ts instead of on every command.
+    // effective port (CLI --port flag OR the CUTTLEFISH_PORT env var). This
+    // allows setting the port in the environment instead of on every command.
     if (watch && monitor) {
         throw new Error("--watch and --monitor cannot be used together (monitor blocks the process).");
     }
@@ -334,6 +336,7 @@ function parsePipelineCommand(argv, command, inputFile) {
         monitor,
         watch,
         port,
+        probe: probeFlag,
         baud,
         platformContext,
         treeShaking,
@@ -363,23 +366,24 @@ export function parseCommandLine(argv) {
         const framework = readFirstFlagValue(argv, ["--framework", "-f"]);
         const baudRaw = readFirstFlagValue(argv, ["--baud"]);
         const outDir = readFirstFlagValue(argv, ["--outDir", "--out-dir", "-o"]);
-        const noSketch = argv.includes("--no-sketch");
+        const noStarter = argv.includes("--no-starter");
         const noInstall = argv.includes("--no-install");
+        const probeFlag = readFirstFlagValue(argv, ["--probe", "--flash"]);
+        const portFlag = readFirstFlagValue(argv, ["--port", "-p"]);
         const baud = baudRaw && !Number.isNaN(Number(baudRaw)) ? Number(baudRaw) : undefined;
         return {
             command: "create",
+            probe: probeFlag,
             projectName,
             target,
             baud,
             framework,
-            noSketch,
+            noStarter,
             noInstall,
+            port: portFlag,
             outDir: outDir ? path.resolve(process.cwd(), outDir) : undefined,
         };
     }
-    if (firstArg === "create-board") {
-        throw new Error(`The 'create-board' command has been removed. Board scaffolding is now in @typecad/create.`);
-    }
     // build subcommand — entry point comes from cuttlefish.config.ts
     if (firstArg === "build") {
         return parsePipelineCommand(argv, "build");
@@ -447,6 +451,24 @@ export function parseCommandLine(argv) {
             platformContext: {},
         };
     }
+    // board subcommand — project-local board module management
+    // (sync: rebuild the board catalog overlay from the user's Zephyr tree —
+    // the refresh path after `west update`; regen: re-emit
+    // .cuttlefish/board.ts + board.json from the active catalog).
+    if (firstArg === "board") {
+        const sub = argv[3];
+        if (sub === "sync") {
+            // Optional positional: an explicit Zephyr checkout to sync from.
+            const positional = argv.slice(4).find((a) => !a.startsWith("-"));
+            return { command: "board", subcommand: "sync", zephyrBase: positional };
+        }
+        if (sub !== "regen") {
+            throw new Error("Usage: cuttlefish board <sync|regen> — 'sync' rebuilds the board catalog from your " +
+                "Zephyr tree, 'regen' regenerates .cuttlefish/board.ts + board.json for the config's " +
+                "board target.");
+        }
+        return { command: "board", subcommand: "regen" };
+    }
     // library subcommand — the cuttlefish library package manager
     // (search/install/init/validate; npm keywords are the catalog).
     if (firstArg === "library") {
@@ -506,9 +528,8 @@ export function parseCommandLine(argv) {
             json: jsonFlag,
         };
     }
-    // Named subcommands
-    if (firstArg === "gen-libdefs" || firstArg === "gen-decls" || firstArg === "map-error") {
-        const command = firstArg;
+    // gen-decls subcommand — generate .d.ts from C++ files
+    if (firstArg === "gen-decls") {
         const emitFlag = readFirstFlagValue(argv, ["--emit"]);
         const targetFlag = readFirstFlagValue(argv, ["--target"]);
         const outDir = readFirstFlagValue(argv, ["--outDir", "--out-dir"]);
@@ -521,124 +542,40 @@ export function parseCommandLine(argv) {
             architecture: buildTarget?.split(":")?.[1]?.toLowerCase(),
             frameworkData: { buildTarget },
         };
-        if (command === "map-error") {
-            const mapFile = argv[3];
-            if (!mapFile) {
-                throw new Error("Missing source map path for map-error.");
-            }
-            const cppLineRaw = readFirstFlagValue(argv, ["--line", "--cpp-line"]);
-            if (!cppLineRaw || Number.isNaN(Number(cppLineRaw))) {
-                throw new Error("map-error requires --line <number>.");
-            }
-            const cppColumnRaw = readFirstFlagValue(argv, ["--column", "--cpp-column"]);
-            const cppFile = readFirstFlagValue(argv, ["--cpp-file"]);
-            const message = readFirstFlagValue(argv, ["--message"]);
-            return {
-                command,
-                emitMode,
-                target,
-                outDir: outDir ? path.resolve(process.cwd(), outDir) : undefined,
-                emitMaps,
-                noTranspile: false,
-                compile: false,
-                upload: false,
-                monitor: false,
-                watch: false,
-                baud: 9600,
-                platformContext,
-                mapFile: path.resolve(process.cwd(), mapFile),
-                cppFile: cppFile ? path.resolve(process.cwd(), cppFile) : undefined,
-                cppLine: Number(cppLineRaw),
-                cppColumn: cppColumnRaw ? Number(cppColumnRaw) : 1,
-                message,
-            };
-        }
-        // 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", "--components"]);
-            const valueFlags = new Set([
-                "--emit", "--target", "--outDir", "--out-dir", "--emit-maps", "--build-target",
-            ]);
-            let inputPath;
-            for (let i = 3; i < argv.length; i++) {
-                const tok = argv[i];
-                if (valueFlags.has(tok)) {
-                    // Value-consuming flag: skip its value (if any) so it isn't mistaken
-                    // for the positional path.
-                    if (i + 1 < argv.length) {
-                        i++;
-                    }
-                    continue;
-                }
-                if (tok.startsWith("-")) {
-                    continue; // boolean flag (e.g. --all) or unknown flag — ignore
+        const allFlag = argv.includes("--all");
+        // 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 valueFlags = new Set([
+            "--emit", "--target", "--outDir", "--out-dir", "--emit-maps", "--build-target",
+        ]);
+        let inputPath;
+        for (let i = 3; i < argv.length; i++) {
+            const tok = argv[i];
+            if (valueFlags.has(tok)) {
+                // Value-consuming flag: skip its value (if any) so it isn't mistaken
+                // for the positional path.
+                if (i + 1 < argv.length) {
+                    i++;
                 }
-                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),
-                };
+                continue;
             }
-            if (!inputPath && !allFlag) {
-                throw new Error("Missing input C++ file path. Use: gen-decls <file.cpp> or gen-decls --all <directory>");
+            if (tok.startsWith("-")) {
+                continue; // boolean flag (e.g. --all) or unknown flag — ignore
             }
-            const scanDir = allFlag ? (inputPath || process.cwd()) : undefined;
-            const inputFile = allFlag ? undefined : inputPath;
-            return {
-                command: "gen-decls",
-                inputFile: inputFile ? path.resolve(process.cwd(), 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,
-                // Custom fields for gen-decls
-                scanDir: scanDir ? path.resolve(process.cwd(), scanDir) : undefined,
-            };
+            inputPath = tok;
+            break;
         }
-        // gen-libdefs
-        const inputFile = argv[3];
-        if (!inputFile) {
-            throw new Error("Missing input TypeScript file path.");
+        if (!inputPath && !allFlag) {
+            throw new Error("Missing input C++ file path. Use: gen-decls <file.cpp> or gen-decls --all <directory>");
         }
+        const scanDir = allFlag ? (inputPath || process.cwd()) : undefined;
+        const inputFile = allFlag ? undefined : inputPath;
         return {
-            command,
-            inputFile: path.resolve(process.cwd(), inputFile),
+            command: "gen-decls",
+            inputFile: inputFile ? path.resolve(process.cwd(), inputFile) : undefined,
             emitMode,
             target,
             outDir: outDir ? path.resolve(process.cwd(), outDir) : undefined,
@@ -650,6 +587,7 @@ export function parseCommandLine(argv) {
             watch: false,
             baud: 9600,
             platformContext,
+            scanDir: scanDir ? path.resolve(process.cwd(), scanDir) : undefined,
         };
     }
     // Default: firstArg is the input file (unless it's a flag like --expect)

package/dist/utils/fs.d.ts

@@ -8,10 +8,9 @@ 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.
+ * Used by {@link loadLibraryDefinitions} so libdefs in project subdirectories
+ * 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).

package/dist/utils/fs.js

@@ -25,7 +25,7 @@ export function writeText(filePath, content) {
     ensureDir(path.dirname(filePath));
     const resolved = path.resolve(filePath);
     // Skip writing when content is identical — preserves mtime so downstream
-    // build tools (idf.py/ninja, arduino-cli, make) can skip recompilation.
+    // build tools (west/ninja, make) can skip recompilation.
     // The file still counts as "written this run" (it is current output).
     writtenFiles.add(resolved);
     try {
@@ -50,10 +50,9 @@ export function listFiles(dirPath, extension) {
  * 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.
+ * Used by {@link loadLibraryDefinitions} so libdefs in project subdirectories
+ * 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).

package/dist/utils/strings.d.ts

@@ -32,4 +32,3 @@ export declare function escapeCppStringLiteral(value: string): string;
  *  format argument to snprintf(...) — NOT for snprintf *arguments* or for
  *  standalone C++ string literals, where a bare `%` is harmless. */
 export declare function escapeSnprintfFormatFragment(value: string): string;
-export declare function normalizeKebabName(name: string): string;

package/dist/utils/strings.js

@@ -132,11 +132,3 @@ export function escapeCppStringLiteral(value) {
 export function escapeSnprintfFormatFragment(value) {
     return escapeCppStringLiteral(value).replace(/%/g, "%%");
 }
-export function normalizeKebabName(name) {
-    return name
-        .toLowerCase()
-        .replace(/[\s_]+/g, '-')
-        .replace(/[^a-z0-9-]/g, '')
-        .replace(/-+/g, '-')
-        .replace(/^-|-$/g, '');
-}

package/dist/utils/ui.d.ts

@@ -1,3 +1,5 @@
+declare const VERSION: string;
+export { VERSION };
 /**
  * Print the Cuttlefish branded header
  */
@@ -33,9 +35,10 @@ export declare function printCompiling(target: string): void;
  */
 export declare function printDebugStrategy(framework: string): void;
 /**
- * Print uploading step
+ * Print uploading step. Probe/USB flashing carries no serial port — the
+ * destination is omitted rather than printed as "undefined".
  */
-export declare function printUploading(port: string): void;
+export declare function printUploading(port?: string): void;
 /**
  * Print monitoring step
  */

package/dist/utils/ui.js

@@ -1,5 +1,13 @@
 import chalk from "chalk";
-const VERSION = "0.1.0";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// Real package version (dist/utils/ui.js → ../../package.json). Previously
+// hardcoded "0.1.0", which drifted from the published version and misled
+// bug reports into blaming a stale global install.
+const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+const VERSION = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version ?? "unknown";
+export { VERSION };
 // Icons
 const ICON_CUTTLEFISH = "⤳";
 const ICON_COMPILE = "⇉";
@@ -77,10 +85,12 @@ export function printDebugStrategy(framework) {
     console.log(chalk.cyan(`${ICON_COMPILE} Preparing to debug using `) + chalk.white(framework));
 }
 /**
- * Print uploading step
+ * Print uploading step. Probe/USB flashing carries no serial port — the
+ * destination is omitted rather than printed as "undefined".
  */
 export function printUploading(port) {
-    console.log(chalk.cyan(`${ICON_UPLOAD} Uploading to `) + chalk.white(port));
+    const destination = port ? chalk.cyan(" to ") + chalk.white(port) : "";
+    console.log(chalk.cyan(`${ICON_UPLOAD} Uploading`) + destination);
 }
 /**
  * Print monitoring step