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

package/dist/transpile.js

@@ -33,6 +33,7 @@ import { readText, writeText, resetWrittenFiles, wasWrittenThisRun } from "./uti
 import { debug as logDebug, info } from "./utils/logger.js";
 import { printDebugStrategy } from "./utils/ui.js";
 import { loadLibraryDefinitions, generateLibdefStubs } from "./libdef/registry.js";
+import { resetCuttlefishLibraries, validateCuttlefishLibraries, cuttlefishLibraryLibdefs, libraryDefinitionKey, writeCuttlefishLibraryArtifacts, } from "./library-packages.js";
 import { buildCallGraph } from "./ir/call-graph.js";
 import { clearCaches, } from "./cache.js";
 import { detectEntryPoints, detectExportedEntryPoints } from "./ir/entry-points.js";
@@ -377,8 +378,14 @@ export async function transpileFile(options) {
             return {};
         }
     })();
+    resetCuttlefishLibraries();
     const graphResult = await collectTranspileGraph(entryFile, options.boardPackage, imageDecodeMax);
     profiler.endTimer("graph:collect");
+    // Cuttlefish library packages registered during the graph walk — validate
+    // them against the loaded framework (and build target, when known) before
+    // any codegen. A framework/target mismatch is a hard error here, far
+    // clearer than the native compiler's take on a missing header or node.
+    validateCuttlefishLibraries(strategy.id, options.platformContext?.frameworkData?.buildTarget);
     const transpileFiles = graphResult.files;
     // ── Type-check all files before transpiling ────────────────────────────────
     // Skip type-checking if explicitly disabled
@@ -451,6 +458,15 @@ export async function transpileFile(options) {
     }
     const npmPackages = graphResult.npmPackages;
     const definitions = loadLibraryDefinitions(sourceDir);
+    // Cuttlefish library packages: the import resolves to the library's shim
+    // include (e.g. '"__tc_rgbled.h"') instead of a transpiled module header.
+    // Project-local .libdef.json files keep precedence.
+    for (const libdef of cuttlefishLibraryLibdefs()) {
+        const key = libraryDefinitionKey(libdef.module);
+        if (!definitions.has(key)) {
+            definitions.set(key, libdef);
+        }
+    }
     let entryOutputs;
     const diagnostics = [];
     const allRemovedSymbols = [];
@@ -935,6 +951,45 @@ export async function transpileFile(options) {
             });
         }
     }
+    // ── Persist the resolved board constants next to the emitted source ─────
+    // Framework toolchains re-read this at compile time to rebuild their chip
+    // descriptors (framework-zephyr's resolveChipFromBoard). Board packages
+    // carry chip data — controller splits, ADC channel maps, PWM specs — that
+    // lives only in the board package, so without this file the toolchain's
+    // registry fallback silently resolves board-derived targets (rpi_pico,
+    // esp32c3/c6, blackpill) to the XIAO default descriptor.
+    try {
+        // Read from the built program IRs — the IR build context (and its
+        // current-board-constants slot) is already closed at this point. Any
+        // file's IR may carry the constants (the board import is traversed while
+        // building whichever file imports it first), so scan for a populated one.
+        let boardConstants;
+        for (const pb of preBuilt.values()) {
+            const bc = pb.programIR.boardConstants;
+            if (bc && bc.size > 0) {
+                boardConstants = bc;
+                break;
+            }
+        }
+        if (boardConstants && boardConstants.size > 0) {
+            fs.writeFileSync(path.join(outDir, "board-constants.json"), JSON.stringify(Object.fromEntries(boardConstants), null, 2));
+        }
+    }
+    catch {
+        // Best-effort persistence; the toolchain falls back to its registry.
+    }
+    // ── Cuttlefish library packages: shims + libraries.json sidecar ─────────
+    // Shims are written next to the emitted sources (the framework scaffold's
+    // CMake/sketch regen compiles them); the sidecar records the used
+    // libraries' build contributions (Kconfig lines, overlay fragments) for
+    // the framework toolchain — the board-constants.json convention.
+    try {
+        const emittedSrcDir = entryOutputs ? path.dirname(entryOutputs.sourcePath) : outDir;
+        writeCuttlefishLibraryArtifacts(outDir, emittedSrcDir);
+    }
+    catch {
+        // Best-effort; a missing shim surfaces at native compile time.
+    }
     return {
         ...entryOutputs,
         diagnostics,

package/dist/types.d.ts

@@ -238,4 +238,23 @@ export interface BoardAddCommandOptions {
     specPath: string;
     force?: boolean;
 }
+/** Parsed `cuttlefish library <subcommand>` options. */
+export interface LibraryCommandOptions {
+    command: "library";
+    subcommand: "search" | "install" | "init" | "validate";
+    /** Non-flag tokens after the subcommand: search text, install names, init name, validate path. */
+    positionals: string[];
+    /** search: taxonomy category id. */
+    category?: string;
+    /** init: framework id from the framework catalog. */
+    framework?: string;
+    /** init: comma-separated board-target prefixes. */
+    targets?: string;
+    /** init: scaffold directory (default ./<library-id>). */
+    dir?: string;
+    /** init: skip prompts, take defaults. */
+    yes?: boolean;
+    /** Machine-readable output for search/validate. */
+    json?: boolean;
+}
 export {};

package/dist/utils/cli.d.ts

@@ -1,3 +1,3 @@
-import { CommandLineOptions, CreateCommandOptions, BoardAddCommandOptions } from "../types.js";
+import { CommandLineOptions, CreateCommandOptions, BoardAddCommandOptions, LibraryCommandOptions } from "../types.js";
 export declare function printHelp(): void;
-export declare function parseCommandLine(argv: string[]): CommandLineOptions | CreateCommandOptions | BoardAddCommandOptions | "help";
+export declare function parseCommandLine(argv: string[]): CommandLineOptions | CreateCommandOptions | BoardAddCommandOptions | LibraryCommandOptions | "help";

package/dist/utils/cli.js

@@ -20,6 +20,15 @@ export function printHelp() {
     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();
+    console.log(chalk.cyan(`LIBRARY PACKAGES`) + chalk.gray(` (npm keywords are the catalog)`));
+    console.log();
+    console.log(`  cuttlefish library search [text] [--category <id>] [--json]`);
+    console.log(`                          Browse cuttlefish library packages on npm, optionally by category`);
+    console.log(`  cuttlefish library install <pkg...>             Install library packages into this project`);
+    console.log(`  cuttlefish library init [name] [--framework <id>] [--category <id>] [--targets <list>]`);
+    console.log(`                          Scaffold a new library package (interactive; --yes takes defaults)`);
+    console.log(`  cuttlefish library validate [path] [--json]     Validate a library package (manifest, shims, keywords, AUTOSAR strict)`);
+    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.`));
     console.log();
@@ -371,9 +380,6 @@ export function parseCommandLine(argv) {
     if (firstArg === "create-board") {
         throw new Error(`The 'create-board' command has been removed. Board scaffolding is now in @typecad/create.`);
     }
-    if (firstArg === "init") {
-        throw new Error(`Use 'cuttlefish create' instead of 'cuttlefish init'.`);
-    }
     // build subcommand — entry point comes from cuttlefish.config.ts
     if (firstArg === "build") {
         return parsePipelineCommand(argv, "build");
@@ -441,6 +447,65 @@ export function parseCommandLine(argv) {
             platformContext: {},
         };
     }
+    // library subcommand — the cuttlefish library package manager
+    // (search/install/init/validate; npm keywords are the catalog).
+    if (firstArg === "library") {
+        const sub = argv[3];
+        const known = new Set(["search", "install", "init", "validate"]);
+        if (!sub || !known.has(sub)) {
+            throw new Error("Usage: cuttlefish library <search|install|init|validate> [args]. " +
+                "Try 'cuttlefish library search' to browse, or 'cuttlefish library init <name>'.");
+        }
+        const subcommand = sub;
+        // Value flags accept both forms (--category led and --category=led); the
+        // generic readFlag helper only handles the space-separated form, which
+        // would silently drop an equals-form filter.
+        const valueFlags = new Set(["--category", "--framework", "--targets", "--dir"]);
+        const flagValues = new Map();
+        const positionals = [];
+        let jsonFlag = false;
+        let yesFlag = false;
+        for (let i = 4; i < argv.length; i++) {
+            const tok = argv[i];
+            if (tok.startsWith("--") && tok.includes("=")) {
+                const eq = tok.indexOf("=");
+                flagValues.set(tok.slice(0, eq), tok.slice(eq + 1));
+                continue;
+            }
+            if (valueFlags.has(tok)) {
+                if (i + 1 < argv.length) {
+                    flagValues.set(tok, argv[++i]);
+                }
+                continue;
+            }
+            if (tok === "--json") {
+                jsonFlag = true;
+                continue;
+            }
+            if (tok === "--yes" || tok === "-y") {
+                yesFlag = true;
+                continue;
+            }
+            if (tok.startsWith("-"))
+                continue;
+            positionals.push(tok);
+        }
+        const category = flagValues.get("--category");
+        if (category !== undefined && subcommand !== "search" && subcommand !== "init") {
+            throw new Error("--category applies to 'library search' and 'library init' only.");
+        }
+        return {
+            command: "library",
+            subcommand,
+            positionals,
+            category,
+            framework: flagValues.get("--framework"),
+            targets: flagValues.get("--targets"),
+            dir: flagValues.get("--dir"),
+            yes: yesFlag,
+            json: jsonFlag,
+        };
+    }
     // Named subcommands
     if (firstArg === "gen-libdefs" || firstArg === "gen-decls" || firstArg === "map-error") {
         const command = firstArg;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/cuttlefish",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.14",
   "description": "TypeScript to C++ transpiler — native, Arduino, and bare-metal targets",
   "type": "module",
   "main": "./dist/transpile.js",
@@ -37,6 +37,14 @@
       "types": "./dist/ir/build-ir-state.d.ts",
       "default": "./dist/ir/build-ir-state.js"
     },
+    "./library-packages": {
+      "types": "./dist/library-packages.d.ts",
+      "default": "./dist/library-packages.js"
+    },
+    "./compliance": {
+      "types": "./dist/emit/compliance/index.d.ts",
+      "default": "./dist/emit/compliance/index.js"
+    },
     "./config-loader": {
       "types": "./dist/config-loader.d.ts",
       "default": "./dist/config-loader.js"
@@ -95,13 +103,13 @@
     "start": "node dist/cli.js"
   },
   "dependencies": {
-    "chalk": "^4.1.2",
+    "chalk": "^6.0.0",
     "typescript": "^5.7.3",
-    "zod": "^3.24.0"
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@typecad/ui": "1.0.0-alpha.13",
-    "@typecad/safety": "1.0.0-alpha.13"
+    "@typecad/ui": "1.0.0-alpha.14",
+    "@typecad/safety": "1.0.0-alpha.14"
   },
   "peerDependenciesMeta": {
     "@typecad/ui": {
@@ -112,8 +120,8 @@
     }
   },
   "optionalDependencies": {
-    "@typecad/expect": "1.0.0-alpha.13",
-    "@typecad/framework-native": "1.0.0-alpha.13"
+    "@typecad/expect": "1.0.0-alpha.14",
+    "@typecad/framework-native": "1.0.0-alpha.14"
   },
   "devDependencies": {
     "@types/node": "^22.10.7"
@@ -142,7 +150,7 @@
     "typescript"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.11.0"
   },
   "author": "typecad0",
   "sideEffects": false

package/dist/create/init-templates.d.ts

@@ -1,28 +0,0 @@
-import type { ArchitectureIdentifier } from '../api/index.js';
-export interface InitProjectOptions {
-    projectName: string;
-    targetId: string;
-    targetDisplayName: string;
-    isNative: boolean;
-    architecture?: ArchitectureIdentifier;
-    boardPackage?: string;
-    frameworkPackage: string;
-    framework: string;
-    buildTarget?: string;
-    mcu?: string;
-    baudRate?: number;
-    includeSketch: boolean;
-    toolchainType?: string;
-    /** Extra frameworkData fields (e.g. `{ target: 'esp32s3' }` for framework-esp32). */
-    frameworkData?: Record<string, unknown>;
-}
-export declare function generateProjectPackageJson(options: InitProjectOptions): string;
-export declare function generateProjectTsconfig(options: InitProjectOptions): string;
-export declare function generateProjectConfig(options: InitProjectOptions): string;
-export declare function generateProjectEnvDts(options: InitProjectOptions): string;
-export declare function generateStarterSketch(options: InitProjectOptions): string;
-export declare function generateStarterTest(_options: InitProjectOptions): string;
-export declare function generateStarterSim(options: InitProjectOptions): string;
-export declare function generateBoardForwardingFile(boardPackage: string): string;
-export declare function generateGitignore(_options: InitProjectOptions): string;
-export declare function generateEslintConfig(_options: InitProjectOptions): string;

package/dist/create/init-wizard.d.ts

@@ -1,8 +0,0 @@
-import type { InitProjectOptions } from "./init-templates.js";
-export declare function runInitWizard(partialOptions?: {
-    projectName?: string;
-    board?: string;
-    framework?: string;
-    baud?: number;
-    noSketch?: boolean;
-}): Promise<InitProjectOptions | null>;