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

package/dist/libdef/cpp-to-decl.js

@@ -8,7 +8,6 @@ import fs from "node:fs";
 import path from "node:path";
 import { parseHeader } from "./header-parser.js";
 import { buildClassIndex, BaseClassResolver } from "./base-class-resolver.js";
-import { writeText } from "../utils/fs.js";
 /**
  * Maps C++ types to TypeScript types
  */
@@ -583,74 +582,3 @@ function generateDeclWithResolver(filePath, resolver) {
     }
     return outPath;
 }
-// ─── ESP-IDF component dispatch ───────────────────────────────────────────
-//
-// Picks the C or C++ emitter per header based on whether it declares classes.
-// ESP-IDF components are mostly C (free functions + typedefs); Arduino-style
-// libraries are C++ classes. Spec:
-// docs/superpowers/specs/2026-07-19-framework-esp32-components-design.md
-import { generateCDecl } from "./c-to-decl.js";
-import { discoverComponentHeaders } from "./component-discovery.js";
-/** Heuristic: does this header declare any C++ classes? */
-function hasClasses(headerPath) {
-    try {
-        const content = fs.readFileSync(headerPath, "utf8");
-        return parseHeader(content).length > 0;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Generate .d.ts declarations for every declared component's headers,
- * picking the C or C++ emitter per header based on whether it declares classes.
- *
- * Returns the list of created/updated .d.ts paths (headers that produced no
- * declarations are skipped).
- */
-export function generateComponentDeclsForProject(projectDir, roots) {
-    const headers = discoverComponentHeaders(projectDir, roots);
-    const created = [];
-    for (const discovered of headers) {
-        // Output path: <outputDir>/<basename>.d.ts. For managed/local this is
-        // alongside the header; for builtins it's the project-local cache dir.
-        const baseName = path.basename(discovered.path).replace(/\.h$/i, '');
-        const outputPath = path.join(discovered.outputDir, baseName + '.d.ts');
-        const out = hasClasses(discovered.path)
-            ? generateDecl(discovered.path, outputPath)
-            : generateCDecl(discovered.path, outputPath);
-        if (out) {
-            created.push(out);
-            // Write a sibling .libdef.json so the import → #include resolver picks
-            // up the real (case-preserving) header name. Without this, the resolver
-            // falls back to toPascalCase(moduleKey) + ".h" — fine for Arduino libs
-            // (Adafruit_GFX → Adafruit_GFX.h, resolved separately) but wrong for
-            // ESP-IDF component headers (esp_wifi → <EspWifi.h>, not <esp_wifi.h>).
-            // The libdef declares the actual header basename ("esp_wifi.h"), which
-            // is the ground truth — the generator just read the file.
-            writeComponentLibdef(discovered.path, outputPath);
-        }
-    }
-    return created;
-}
-/**
- * Write `<d.ts-basename>.libdef.json` next to a generated component `.d.ts`,
- * pointing the import → #include resolver at the actual source header.
- *
- * The libdef `module` field is the lowercased basename (matches what
- * `toModuleKey()` produces from an import specifier), and `include` is the
- * case-preserving `<basename>.h` — quote-wrapped because component headers
- * are project-local (resolved via the include path), not system angle-bracket
- * includes. Matches the local-header convention in `resolveLocalModuleHeader`.
- */
-function writeComponentLibdef(sourceHeaderPath, dtsOutputPath) {
-    const headerBaseName = path.basename(sourceHeaderPath); // e.g. "esp_wifi.h"
-    const dtsBaseName = path.basename(dtsOutputPath, '.d.ts'); // e.g. "esp_wifi"
-    const libdefPath = path.join(path.dirname(dtsOutputPath), `${dtsBaseName}.libdef.json`);
-    const libdef = {
-        module: dtsBaseName.toLowerCase(),
-        include: `"${headerBaseName}"`,
-        source: sourceHeaderPath,
-    };
-    writeText(libdefPath, JSON.stringify(libdef, null, 2) + '\n');
-}

package/dist/libdef/registry.d.ts

@@ -6,5 +6,4 @@ interface ResolvedImport {
 }
 export declare function loadLibraryDefinitions(definitionsDir: string): Map<string, LibraryDefinition>;
 export declare function resolveImport(importNode: ImportIR, definitions: Map<string, LibraryDefinition>, target: TargetProfile, platformContext?: PlatformContext, importerFilePath?: string): ResolvedImport;
-export declare function generateLibdefStubs(inputFile: string, imports: ImportIR[], outDir: string): string[];
 export {};

package/dist/libdef/registry.js

@@ -22,8 +22,7 @@ function getLibraryResolver() {
 export function loadLibraryDefinitions(definitionsDir) {
     const registry = new Map();
     // Recursive scan: libdefs may live at the entry dir (single-level convention)
-    // or nested under cache trees like `.cuttlefish/component-decls/<component>/`
-    // (per-component overrides generated alongside .d.ts stubs).
+    // or nested in project subdirectories (per-module overrides).
     const files = listFilesRecursive(definitionsDir, ".libdef.json");
     for (const filePath of files) {
         let def;
@@ -121,25 +120,3 @@ export function resolveImport(importNode, definitions, target, platformContext,
         },
     };
 }
-export function generateLibdefStubs(inputFile, imports, outDir) {
-    const created = [];
-    if (!fs.existsSync(outDir)) {
-        fs.mkdirSync(outDir, { recursive: true });
-    }
-    for (const item of imports) {
-        const moduleKey = toModuleKey(item.moduleSpecifier);
-        const libdefPath = path.join(outDir, `${moduleKey}.libdef.json`);
-        if (!fs.existsSync(libdefPath)) {
-            const include = `<${toPascalCase(moduleKey)}.h>`;
-            const libdefContent = {
-                module: moduleKey,
-                include,
-                symbols: Object.fromEntries(item.namedImports.map((symbol) => [symbol, symbol])),
-                source: inputFile,
-            };
-            fs.writeFileSync(libdefPath, JSON.stringify(libdefContent, null, 2) + "\n", "utf8");
-            created.push(libdefPath);
-        }
-    }
-    return created;
-}

package/dist/library/catalog.d.ts

@@ -0,0 +1,35 @@
+/** The one keyword every cuttlefish library package must carry. */
+export declare const LIBRARY_MARKER_KEYWORD = "cuttlefish-library";
+/** Prefix for category keywords (`cuttlefish-<id>`). */
+export declare const CATEGORY_KEYWORD_PREFIX = "cuttlefish-";
+export interface LibraryCategory {
+    /** Stable id used in --category flags, keywords, and docs. */
+    id: string;
+    /** Human label for prompts and tables. */
+    label: string;
+    /** One-line scope description. */
+    description: string;
+    /** Example parts the category covers (prompt/README guidance). */
+    examples: string;
+}
+/**
+ * The category taxonomy. Shared by search (query building + result shaping),
+ * init (scaffold choices + keywords), validate (keyword consistency), and the
+ * website's Library Packages page (rendered from the same list).
+ */
+export declare const LIBRARY_CATEGORIES: readonly LibraryCategory[];
+/** Look up a category by id (case-insensitive). */
+export declare function libraryCategory(id: string): LibraryCategory | undefined;
+/** The npm keyword for a category (`cuttlefish-<id>`). */
+export declare function categoryKeyword(id: string): string;
+/**
+ * Derive the category of an npm search result from its keywords. A package may
+ * carry several category keywords; the first match in taxonomy order wins so
+ * results are stable.
+ */
+export declare function categoryFromKeywords(keywords: readonly string[] | undefined): string | null;
+/**
+ * The keywords a library package should carry: the marker plus its category
+ * keyword. Used by `library init` and checked by `library validate`.
+ */
+export declare function requiredLibraryKeywords(categoryId: string): string[];

package/dist/library/catalog.js

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// Cuttlefish library catalog — the category taxonomy and npm keyword
+// conventions behind `cuttlefish library search/init/validate`.
+//
+// The catalog has no registry service: npm keywords ARE the catalog. Every
+// library package carries the marker keyword LIBRARY_MARKER_KEYWORD plus one
+// category keyword (e.g. 'cuttlefish-led'). npm's search endpoint ANDs
+// `keywords:` terms, so queries compose:
+//
+//   keywords:cuttlefish-library                     → every library
+//   keywords:cuttlefish-library keywords:cuttlefish-led → the led category
+//   keywords:cuttlefish-library ws2812              → free-text within libraries
+// ---------------------------------------------------------------------------
+/** The one keyword every cuttlefish library package must carry. */
+export const LIBRARY_MARKER_KEYWORD = "cuttlefish-library";
+/** Prefix for category keywords (`cuttlefish-<id>`). */
+export const CATEGORY_KEYWORD_PREFIX = "cuttlefish-";
+/**
+ * The category taxonomy. Shared by search (query building + result shaping),
+ * init (scaffold choices + keywords), validate (keyword consistency), and the
+ * website's Library Packages page (rendered from the same list).
+ */
+export const LIBRARY_CATEGORIES = [
+    { id: "led", label: "LEDs", description: "LEDs, addressable strips, LED drivers", examples: "WS2812-class pixels, LED drivers, bar graphs" },
+    { id: "display", label: "Displays", description: "Panels and panel drivers", examples: "TFT, OLED, e-ink" },
+    { id: "sensor", label: "Sensors", description: "Measurement parts", examples: "environmental, motion, IMU, light, distance" },
+    { id: "actuator", label: "Actuators", description: "Things that move or switch", examples: "motors, servos, steppers, relays" },
+    { id: "comms", label: "Communications", description: "Radios and networking beyond built-in WiFi/BLE", examples: "LoRa, GSM, satellite, CAN add-ons" },
+    { id: "storage", label: "Storage", description: "Persistent storage parts", examples: "SD cards, flash chips, FRAM" },
+    { id: "audio", label: "Audio", description: "Sound input and output", examples: "microphones, amplifiers, codecs" },
+    { id: "power", label: "Power", description: "Power management and monitoring", examples: "PMICs, battery gauges, chargers" },
+    { id: "input", label: "Input", description: "Add-on human input", examples: "keypads, rotary encoders, add-on touch" },
+    { id: "io", label: "I/O Expanders", description: "Extra I/O and simple drivers", examples: "port expanders, matrix drivers, 7-segment" },
+    { id: "timing", label: "Timing", description: "Clocks and time sources", examples: "RTCs, precision clocks, GPS time" },
+    { id: "utility", label: "Utility", description: "Pure-code helpers with no hardware of their own", examples: "formats, algorithms, protocol codecs" },
+];
+/** Look up a category by id (case-insensitive). */
+export function libraryCategory(id) {
+    const lower = id.toLowerCase();
+    return LIBRARY_CATEGORIES.find((c) => c.id === lower);
+}
+/** The npm keyword for a category (`cuttlefish-<id>`). */
+export function categoryKeyword(id) {
+    return `${CATEGORY_KEYWORD_PREFIX}${id.toLowerCase()}`;
+}
+/**
+ * Derive the category of an npm search result from its keywords. A package may
+ * carry several category keywords; the first match in taxonomy order wins so
+ * results are stable.
+ */
+export function categoryFromKeywords(keywords) {
+    if (!keywords || keywords.length === 0)
+        return null;
+    const set = new Set(keywords.map((k) => k.toLowerCase()));
+    for (const category of LIBRARY_CATEGORIES) {
+        if (set.has(categoryKeyword(category.id)))
+            return category.id;
+    }
+    return null;
+}
+/**
+ * The keywords a library package should carry: the marker plus its category
+ * keyword. Used by `library init` and checked by `library validate`.
+ */
+export function requiredLibraryKeywords(categoryId) {
+    return [LIBRARY_MARKER_KEYWORD, categoryKeyword(categoryId)];
+}

package/dist/library/cli.d.ts

@@ -0,0 +1,2 @@
+import type { LibraryCommandOptions } from "../types.js";
+export declare function runLibraryCommand(options: LibraryCommandOptions): Promise<void>;

package/dist/library/cli.js

@@ -0,0 +1,168 @@
+// ---------------------------------------------------------------------------
+// `cuttlefish library <subcommand>` — CLI glue for the library manager.
+// Subcommands: search, install, init, validate. The catalog modules own the
+// logic; this module owns argument interpretation and presentation.
+// ---------------------------------------------------------------------------
+import chalk from "chalk";
+import path from "node:path";
+import { LIBRARY_CATEGORIES, libraryCategory } from "./catalog.js";
+import { searchLibraryPackages } from "./registry-search.js";
+import { findProjectPackageJson, installedDependencyVersion, npmInstall } from "./install.js";
+import { runLibraryInit } from "./init.js";
+import { validateLibraryPackage, printValidationReport } from "./validate.js";
+function requireCategory(category, command) {
+    if (category === undefined)
+        return undefined;
+    if (!libraryCategory(category)) {
+        throw new Error(`Unknown category '${category}' for 'library ${command}'. Known categories: ` +
+            LIBRARY_CATEGORIES.map((c) => c.id).join(", ") +
+            ".");
+    }
+    return category.toLowerCase();
+}
+function stripVersionPrefix(v) {
+    return v.replace(/^[^0-9]*/, "");
+}
+async function runSearch(options) {
+    const category = requireCategory(options.category, "search");
+    const text = options.positionals.join(" ");
+    let results;
+    try {
+        results = await searchLibraryPackages(text || undefined, category);
+    }
+    catch (e) {
+        throw new Error(`Failed to search npm: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (options.json) {
+        const pkgPath = findProjectPackageJson();
+        console.log(JSON.stringify(results.map((r) => ({
+            name: r.name,
+            version: r.version,
+            description: r.description,
+            category: r.category,
+            npmUrl: r.npmUrl,
+            installed: pkgPath ? installedDependencyVersion(pkgPath, r.name) !== undefined : false,
+        })), null, 2));
+        return;
+    }
+    const header = category
+        ? `cuttlefish libraries — category: ${libraryCategory(category).label}`
+        : "cuttlefish libraries";
+    console.log(chalk.green("+") + " " + chalk.white.bold(header) + chalk.gray(`  (npm keyword: cuttlefish-library${category ? ` + cuttlefish-${category}` : ""})`));
+    console.log();
+    if (results.length === 0) {
+        console.log(chalk.yellow("No matching library packages on npm yet."));
+        console.log(`  Scaffold the first one: ${chalk.cyan("cuttlefish library init")}`);
+        return;
+    }
+    const pkgPath = findProjectPackageJson();
+    for (const r of results) {
+        const cat = r.category ? libraryCategory(r.category) : undefined;
+        const installedSpec = pkgPath ? installedDependencyVersion(pkgPath, r.name) : undefined;
+        const state = installedSpec
+            ? stripVersionPrefix(installedSpec) === r.version
+                ? chalk.gray(" (installed)")
+                : chalk.yellow(` (installed v${stripVersionPrefix(installedSpec)}, latest v${r.version})`)
+            : "";
+        console.log(`  ${chalk.white.bold(r.name)} ${chalk.dim(`v${r.version}`)}${state}`);
+        if (cat) {
+            console.log(`    ${chalk.cyan(`[${cat.label}]`)} ${r.description ?? ""}`);
+        }
+        else {
+            console.log(`    ${r.description ?? ""}`);
+        }
+    }
+    console.log();
+    console.log(chalk.gray(`  Install with: cuttlefish library install <name>`));
+}
+function runInstall(options) {
+    const names = options.positionals;
+    if (names.length === 0) {
+        throw new Error("Usage: cuttlefish library install <package...>");
+    }
+    const pkgPath = findProjectPackageJson();
+    if (!pkgPath) {
+        throw new Error("No package.json found in this directory or any parent — run inside a cuttlefish project.");
+    }
+    const pkgDir = path.dirname(pkgPath);
+    if (options.json) {
+        const before = Object.fromEntries(names.map((n) => [n, installedDependencyVersion(pkgPath, n) ?? null]));
+        try {
+            npmInstall(names, pkgDir);
+        }
+        catch (e) {
+            const err = e;
+            const detail = err.stderr?.toString().trim() || (e instanceof Error ? e.message : String(e));
+            throw new Error(`Failed to install packages: ${detail}`);
+        }
+        console.log(JSON.stringify({ installed: names, projectRoot: pkgDir, previous: before }, null, 2));
+        return;
+    }
+    console.log(chalk.green("+") + ` Installing ${names.join(", ")}...`);
+    try {
+        npmInstall(names, pkgDir);
+    }
+    catch (e) {
+        const err = e;
+        const detail = err.stderr?.toString().trim() || (e instanceof Error ? e.message : String(e));
+        throw new Error(`Failed to install packages: ${detail}`);
+    }
+    for (const name of names) {
+        console.log(chalk.green("+") + ` ${name}`);
+        console.log(chalk.gray(`  https://www.npmjs.com/package/${name}`));
+    }
+    console.log(chalk.green("✔") + " Done");
+}
+async function runInit(options) {
+    if (options.category !== undefined) {
+        requireCategory(options.category, "init");
+    }
+    await runLibraryInit({
+        name: options.positionals[0],
+        framework: options.framework,
+        category: options.category,
+        targets: options.targets,
+        dir: options.dir,
+        yes: options.yes,
+    });
+}
+function runValidate(options) {
+    const dir = options.positionals[0] ?? process.cwd();
+    const report = validateLibraryPackage(dir);
+    if (options.json) {
+        console.log(JSON.stringify({
+            valid: report.valid,
+            dir: report.dir,
+            errors: report.errors,
+            warnings: report.warnings,
+            autosarFindings: report.autosarFindings,
+        }, null, 2));
+    }
+    else {
+        console.log(chalk.white.bold(`cuttlefish library validate`) + chalk.gray(`  ${report.dir}`));
+        console.log();
+        const code = printValidationReport(report);
+        if (code !== 0) {
+            process.exitCode = code;
+        }
+    }
+    if (!report.valid && options.json) {
+        process.exitCode = 1;
+    }
+}
+export async function runLibraryCommand(options) {
+    switch (options.subcommand) {
+        case "search":
+            await runSearch(options);
+            return;
+        case "install":
+            runInstall(options);
+            return;
+        case "init":
+            await runInit(options);
+            return;
+        case "validate":
+            runValidate(options);
+            return;
+    }
+}

package/dist/library/init.d.ts

@@ -0,0 +1,25 @@
+export interface LibraryInitOptions {
+    /** Full package name (e.g. '@acme/esp32-led-ring' or 'my-lib'). */
+    name?: string;
+    /** Framework id from FRAMEWORK_CATALOG ('zephyr', 'native', ...). */
+    framework?: string;
+    /** Category id from LIBRARY_CATEGORIES. */
+    category?: string;
+    /** Comma-separated board-target prefixes (e.g. 'esp32s3_devkitc'). */
+    targets?: string;
+    /** Directory to scaffold into (default: ./<package basename>). */
+    dir?: string;
+    /** Skip prompts; take defaults for anything not provided by flags. */
+    yes?: boolean;
+}
+export interface LibraryInitResult {
+    packageDir: string;
+    packageName: string;
+    /** The library id (slug of the package basename). */
+    id: string;
+}
+/** Slug of a package basename: lowercase, runs of non-alphanumerics → '-'. */
+export declare function libraryIdFromPackageName(packageName: string): string;
+/** '__tc_my_lib' for id 'my-lib' — a valid C++ identifier prefix. */
+export declare function tokenBaseFromId(id: string): string;
+export declare function runLibraryInit(options: LibraryInitOptions): Promise<LibraryInitResult>;