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

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', 'arduino', ...). */
+    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>;

package/dist/library/init.js

@@ -0,0 +1,397 @@
+// ---------------------------------------------------------------------------
+// `cuttlefish library init` — scaffold a new cuttlefish library package.
+//
+// Generates everything a library author needs to reach a valid, publishable
+// package: the typed API skeleton, the cuttlefish.library.json manifest,
+// AUTOSAR C++14-compliant shim stubs, (for Zephyr) an overlay fragment, a
+// README, and a starter compliance test. The scaffold is deliberately tiny —
+// it must pass `cuttlefish library validate` the moment it lands.
+//
+// Prompts follow the create-wizard's readline pattern (no prompt dependency);
+// flags override prompts, and --yes takes defaults for anything unanswered.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import chalk from "chalk";
+import { LIBRARY_CATEGORIES, libraryCategory, requiredLibraryKeywords } from "./catalog.js";
+import { FRAMEWORK_CATALOG } from "../create/framework-catalog.js";
+// ── Naming derivations ──────────────────────────────────────────────────────
+/** Slug of a package basename: lowercase, runs of non-alphanumerics → '-'. */
+export function libraryIdFromPackageName(packageName) {
+    const base = packageName.includes("/") ? packageName.split("/").pop() : packageName;
+    const slug = base.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    if (slug.length === 0) {
+        throw new Error(`Cannot derive a library id from '${packageName}'.`);
+    }
+    return slug;
+}
+/** '__tc_my_lib' for id 'my-lib' — a valid C++ identifier prefix. */
+export function tokenBaseFromId(id) {
+    return id.replace(/-/g, "_");
+}
+function pascalCase(id) {
+    return id.split("-").filter(Boolean).map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
+}
+function camelCase(id) {
+    const pascal = pascalCase(id);
+    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+function isValidNpmName(name) {
+    // Conservative check: optional @scope/ + url-safe segments.
+    return /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i.test(name);
+}
+async function promptText(rl, prompt, defaultValue, validate) {
+    for (;;) {
+        const suffix = defaultValue ? ` (${defaultValue})` : "";
+        const answer = await rl.question(`${chalk.cyan("?")} ${prompt}${suffix}: `);
+        const value = (answer.trim() || (defaultValue ?? "")).trim();
+        if (validate) {
+            const error = validate(value);
+            if (error) {
+                console.log(`  ${chalk.red("✗")} ${error}`);
+                continue;
+            }
+        }
+        return value;
+    }
+}
+async function promptSelect(rl, prompt, options) {
+    console.log(`${chalk.cyan("?")} ${prompt}:`);
+    for (let i = 0; i < options.length; i++) {
+        console.log(`  ${chalk.dim(`${i + 1})`)} ${options[i].label}`);
+    }
+    for (;;) {
+        const answer = await rl.question(`  Enter number (1-${options.length}): `);
+        const idx = parseInt(answer.trim(), 10) - 1;
+        if (idx >= 0 && idx < options.length) {
+            return options[idx].value;
+        }
+        console.log(`  ${chalk.red("✗")} Please enter a number between 1 and ${options.length}.`);
+    }
+}
+function renderPackageJson(m) {
+    return JSON.stringify({
+        name: m.packageName,
+        version: "1.0.0",
+        description: `${m.category.label} library for cuttlefish (${m.framework} framework)`,
+        type: "module",
+        main: "./dist/index.js",
+        types: "./dist/index.d.ts",
+        files: ["dist", "src", "shims", "cuttlefish.library.json"],
+        scripts: {
+            build: "tsc",
+            prepublishOnly: "npm run build",
+        },
+        license: "MIT",
+        keywords: [
+            "cuttlefish",
+            ...requiredLibraryKeywords(m.category.id),
+            m.framework,
+            ...m.id.split("-"),
+        ],
+        engines: { node: ">=18" },
+        sideEffects: false,
+        exports: {
+            ".": { types: "./dist/index.d.ts", default: "./dist/index.js" },
+            "./package.json": "./package.json",
+        },
+        devDependencies: {
+            "@typecad/cuttlefish": "*",
+            vitest: "^4.0.0",
+        },
+    }, null, 2) + "\n";
+}
+function renderTsconfig() {
+    return JSON.stringify({
+        compilerOptions: {
+            composite: true,
+            target: "ES2021",
+            module: "Node16",
+            moduleResolution: "Node16",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            forceConsistentCasingInFileNames: true,
+            declaration: true,
+            declarationMap: false,
+            sourceMap: false,
+            rootDir: "src",
+            outDir: "dist",
+        },
+        include: ["src/**/*.ts"],
+    }, null, 2) + "\n";
+}
+function renderApi(m) {
+    return `// ---------------------------------------------------------------------------
+// ${m.packageName} — cuttlefish library package (${m.category.label.toLowerCase()}).
+//
+// This file is the typed API contract: it is never executed. The cuttlefish
+// transpiler lowers the import to the shim header (shims/__tc_${m.tokenBase}.h),
+// and calls on the exported instance render verbatim into the generated C++.
+// Two rules keep that contract intact:
+//
+//   1. Method names are load-bearing. The C++ class in the shim must define
+//      exactly these names — 'rgbLed'-style call sites appear in the C++ as-is.
+//   2. Export a singleton instance, not a constructor. A bare 'new' in user
+//      code renders as a C++ heap allocation, which the AUTOSAR C++14 rules
+//      the shims follow forbid.
+// ---------------------------------------------------------------------------
+
+/**
+ * ${m.category.description} (${m.category.examples}).
+ */
+export class ${m.className} {
+  /**
+   * Prepare the hardware. Call once from setup(). The stub in the shim is a
+   * no-op — replace it with your initialization code.
+   */
+  begin(): this {
+    return this;
+  }
+
+  // Add your API here. Every method needs a matching member on the C++ class.
+}
+
+/** The instance to use — a preconstructed singleton (see rule 2 above). */
+export const ${m.instanceName}: ${m.className} = new ${m.className}();
+`;
+}
+function renderManifest(m) {
+    const manifest = {
+        id: m.id,
+        module: m.packageName,
+        framework: m.framework,
+        include: `"__tc_${m.tokenBase}.h"`,
+        gateToken: `__tc_${m.tokenBase}`,
+        shims: [
+            { path: `shims/__tc_${m.tokenBase}.h`, outName: `__tc_${m.tokenBase}.h` },
+            { path: `shims/__tc_${m.tokenBase}.cpp`, outName: `__tc_${m.tokenBase}.cpp` },
+        ],
+    };
+    if (m.targets.length > 0) {
+        manifest.targets = m.targets;
+    }
+    if (m.isZephyr) {
+        manifest.kconfig = ["# TODO: the CONFIG_ lines your library needs, e.g. CONFIG_LED_STRIP=y"];
+        manifest.overlay = `shims/${m.id}.overlay`;
+    }
+    return JSON.stringify(manifest, null, 2) + "\n";
+}
+function renderShimHeader(m) {
+    return `// ---------------------------------------------------------------------------
+// __tc_${m.tokenBase}.h — ${m.packageName} shim.
+//
+// The implementation behind the TypeScript API in src/index.ts. Calls on the
+// exported instance render verbatim, so the class name, the instance name,
+// and the method names must match src/index.ts exactly.
+//
+// AUTOSAR C++14 by construction: fixed-width integers, static_cast only (no
+// C-style casts), no heap, 'final' on the leaf class. The generated
+// application's compliance check runs over these bytes.
+// ---------------------------------------------------------------------------
+
+#ifndef TC_${m.tokenBase.toUpperCase()}_H_
+#define TC_${m.tokenBase.toUpperCase()}_H_
+
+#include <cstdint>
+${m.isZephyr ? "#include <zephyr/kernel.h>\n" : ""}class ${m.className} final
+{
+public:
+  ${m.className}& begin();
+
+private:
+  bool initialized_ = false;
+};
+
+extern ${m.className} ${m.instanceName};
+
+#endif  // TC_${m.tokenBase.toUpperCase()}_H_
+`;
+}
+function renderShimSource(m) {
+    return `// ---------------------------------------------------------------------------
+// __tc_${m.tokenBase}.cpp — ${m.packageName} shim implementation.
+// See __tc_${m.tokenBase}.h for the contract. AUTOSAR C++14 compliant.
+// ---------------------------------------------------------------------------
+
+#include "__tc_${m.tokenBase}.h"
+
+${m.className}& ${m.className}::begin()
+{
+  initialized_ = true;
+  return *this;
+}
+
+${m.className} ${m.instanceName};
+`;
+}
+function renderOverlay(m) {
+    return `/*
+ * ${m.id} — devicetree overlay fragment (${m.category.label.toLowerCase()}).
+ *
+ * Appended to the generated boards/<board>.overlay when this library's import
+ * is used. Describe the hardware here: controllers, pins, binding properties.
+ * When upstream Zephyr ships a sample overlay for your part, adapt it and
+ * credit it in a comment.
+ */
+
+/ {
+\t/* aliases { your-alias = &your_node; }; */
+};
+`;
+}
+function renderReadme(m) {
+    return `# ${m.packageName}
+
+A cuttlefish library package — ${m.category.label.toLowerCase()} (${m.category.description}),
+for the **${m.framework}** framework${m.targets.length > 0 ? ` (targets: ${m.targets.join(", ")})` : ""}.
+
+## Use it
+
+\`\`\`ts
+import { ${m.instanceName} } from '${m.packageName}';
+
+${m.instanceName}.begin();
+\`\`\`
+
+## Carry the hardware facts
+
+This library owns the facts so projects don't have to. Document, in this
+README, everything a user would otherwise hunt through datasheets for:
+
+- which board revisions and targets are supported (and which pins they use),
+- which peripherals the library borrows (say so — a user may want them),
+- wiring requirements (I2C address straps, level shifting, pull-ups).
+
+## Authoring checklist
+
+- Method names in src/index.ts match the C++ shim names exactly; calls render verbatim.
+- Export a singleton instance, not a constructor.
+- Shims pass \`cuttlefish library validate\` (AUTOSAR C++14, strict).
+- \`cuttlefish.library.json\` declares framework${m.isZephyr ? ", kconfig, overlay" : ""} and the shim files.
+- package.json keywords include the marker (\`cuttlefish-library\`) and category (\`cuttlefish-${m.category.id}\`) keywords.
+
+Validate with \`cuttlefish library validate .\` from this directory.
+`;
+}
+function renderStarterTest(m) {
+    return `import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ComplianceContext, runSelfCheck } from "@typecad/cuttlefish/compliance";
+
+// The shipped shim bytes must pass --autosar=strict, exactly like framework
+// shims — the generated application's compliance check runs over them.
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+describe("${m.packageName} shims under --autosar=strict", () => {
+  it("__tc_${m.tokenBase}.h/.cpp produce no unrecorded AUTOSAR violations", () => {
+    const header = readFileSync(join(here, "..", "shims", "__tc_${m.tokenBase}.h"), "utf8").split("\\n");
+    const source = readFileSync(join(here, "..", "shims", "__tc_${m.tokenBase}.cpp"), "utf8").split("\\n");
+    const ctx = new ComplianceContext("strict");
+    const findings = runSelfCheck(ctx, source, header);
+    expect(findings).toEqual([]);
+  });
+});
+`;
+}
+// ── Scaffolding ─────────────────────────────────────────────────────────────
+function writeIfChanged(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+}
+export async function runLibraryInit(options) {
+    const interactive = options.yes !== true;
+    let packageName = options.name;
+    let framework = options.framework;
+    let categoryId = options.category;
+    let targetsRaw = options.targets;
+    const missing = packageName === undefined || framework === undefined || categoryId === undefined;
+    if (interactive && missing) {
+        const rl = readline.createInterface({ input, output });
+        try {
+            if (packageName === undefined) {
+                packageName = await promptText(rl, "Package name (npm name, e.g. @acme/my-lib)", "my-lib", (v) => isValidNpmName(v) ? null : "Not a valid npm package name.");
+            }
+            if (framework === undefined) {
+                framework = await promptSelect(rl, "Framework", FRAMEWORK_CATALOG.map((f) => ({ label: f.label, value: f.id })));
+            }
+            if (categoryId === undefined) {
+                categoryId = await promptSelect(rl, "Category", LIBRARY_CATEGORIES.map((c) => ({ label: `${c.label} — ${c.description}`, value: c.id })));
+            }
+            if (targetsRaw === undefined) {
+                targetsRaw = await promptText(rl, "Board targets (comma-separated build-target prefixes, empty for any)", "");
+            }
+        }
+        finally {
+            rl.close();
+        }
+    }
+    packageName = (packageName ?? "my-lib").trim();
+    framework = (framework ?? "zephyr").trim();
+    categoryId = (categoryId ?? "utility").trim();
+    if (!isValidNpmName(packageName)) {
+        throw new Error(`'${packageName}' is not a valid npm package name.`);
+    }
+    const frameworkEntry = FRAMEWORK_CATALOG.find((f) => f.id === framework);
+    if (!frameworkEntry) {
+        throw new Error(`Unknown framework '${framework}'. Known: ${FRAMEWORK_CATALOG.map((f) => f.id).join(", ")}.`);
+    }
+    const category = libraryCategory(categoryId);
+    if (!category) {
+        throw new Error(`Unknown category '${categoryId}'. Known: ${LIBRARY_CATEGORIES.map((c) => c.id).join(", ")}.`);
+    }
+    const id = libraryIdFromPackageName(packageName);
+    const targets = (targetsRaw ?? "")
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    const model = {
+        packageName,
+        id,
+        className: pascalCase(id),
+        instanceName: camelCase(id),
+        tokenBase: tokenBaseFromId(id),
+        framework,
+        category,
+        targets,
+        isZephyr: framework === "zephyr",
+    };
+    const packageDir = path.resolve(options.dir ?? path.join(process.cwd(), id));
+    if (fs.existsSync(packageDir) && fs.readdirSync(packageDir).length > 0) {
+        throw new Error(`Directory ${packageDir} exists and is not empty.`);
+    }
+    writeIfChanged(path.join(packageDir, "package.json"), renderPackageJson(model));
+    writeIfChanged(path.join(packageDir, "tsconfig.json"), renderTsconfig());
+    writeIfChanged(path.join(packageDir, ".gitignore"), "node_modules/\ndist/\n");
+    writeIfChanged(path.join(packageDir, "src", "index.ts"), renderApi(model));
+    writeIfChanged(path.join(packageDir, "cuttlefish.library.json"), renderManifest(model));
+    writeIfChanged(path.join(packageDir, "shims", `__tc_${model.tokenBase}.h`), renderShimHeader(model));
+    writeIfChanged(path.join(packageDir, "shims", `__tc_${model.tokenBase}.cpp`), renderShimSource(model));
+    if (model.isZephyr) {
+        writeIfChanged(path.join(packageDir, "shims", `${id}.overlay`), renderOverlay(model));
+    }
+    writeIfChanged(path.join(packageDir, "README.md"), renderReadme(model));
+    writeIfChanged(path.join(packageDir, "tests", "library.test.ts"), renderStarterTest(model));
+    console.log(chalk.green("+") + ` Scaffolded ${chalk.white.bold(packageName)} in ${packageDir}`);
+    console.log();
+    console.log(`  Framework:  ${frameworkEntry.label}`);
+    console.log(`  Category:   ${category.label} (keyword: cuttlefish-${category.id})`);
+    console.log(`  Library id: ${id} (shim __tc_${model.tokenBase}.h, gate token __tc_${model.tokenBase})`);
+    console.log();
+    console.log("  Next steps:");
+    console.log(`    1. Replace the stubs in shims/ with your implementation.`);
+    console.log(`    2. Fill in cuttlefish.library.json${model.isZephyr ? " (kconfig + overlay)" : ""} as you go.`);
+    console.log(`    3. Validate: npx cuttlefish library validate ${packageDir}`);
+    console.log(`    4. Use it in a project: npm install <path-or-published-name>, then`);
+    console.log(`       import { ${model.instanceName} } from '${packageName}';`);
+    if (model.isZephyr) {
+        console.log();
+        console.log(chalk.dim("  Note: for Zephyr, document the peripherals your overlay borrows in the README."));
+    }
+    return { packageDir, packageName, id };
+}

package/dist/library/install.d.ts

@@ -0,0 +1,9 @@
+/** Walk up from `fromDir` to the nearest package.json. */
+export declare function findProjectPackageJson(fromDir?: string): string | null;
+/** Installed version spec for a dependency name, or undefined. */
+export declare function installedDependencyVersion(packageJsonPath: string, name: string): string | undefined;
+/**
+ * Install npm packages into the project owning `cwd`. Returns the directory
+ * the install ran in. Throws with npm's stderr on failure.
+ */
+export declare function npmInstall(packageNames: string[], cwd: string): void;