@typecad/cuttlefish 1.0.0-alpha.8 → 1.0.0-alpha.9

package/dist/cli.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import { parseCommandLine, printHelp } from "./utils/cli.js";
 import { scaffoldProject, printInitNextSteps, KNOWN_TARGETS } from "./create/index.js";
 import { runInitWizard } from "./create/index.js";
+import { handleInstall } from "./install/index.js";
 import { generateLibraryDefinitions, transpileFile } from "./transpile.js";
 import { generateDecl, generateDeclsForDirectory, generateComponentDeclsForProject } from "./libdef/cpp-to-decl.js";
 import { mapCppLocationToTs, readSourceMap, resolveMapPath } from "./mapping/source-map.js";
@@ -151,6 +152,10 @@ async function main() {
             await handleBoardAdd(options);
             return;
         }
+        if (options.command === "install") {
+            await handleInstall(options);
+            return;
+        }
         if (options.command === "preview") {
             await runPreviewServer({
                 configPath: options.configPath,

package/dist/create/init-wizard.js

@@ -119,7 +119,7 @@ export async function runInitWizard(partialOptions) {
                 // rather than produce a broken scaffold with an empty framework field
                 // (which would generate invalid package.json + cuttlefish.config.ts).
                 throw new Error("No @typecad/framework-* packages found in this project. " +
-                    "Install one before scaffolding, e.g.: npm i @typecad/framework-arduino");
+                    "Run 'cuttlefish install' to add one (e.g. 'cuttlefish install arduino').");
             }
             else if (frameworkOptions.length === 1) {
                 framework = frameworkOptions[0].value;

package/dist/install/framework-catalog.d.ts

@@ -0,0 +1,53 @@
+/** A framework family that ships as an installable @typecad/framework-* package. */
+export interface FrameworkCatalogEntry {
+    /** Short id, e.g. "arduino". Matches the suffix of @typecad/framework-<id>. */
+    id: string;
+    /** Full npm package name, e.g. "@typecad/framework-arduino". */
+    packageName: string;
+    /** Human-readable label shown in the install prompt. */
+    label: string;
+    /**
+     * Whether a real package exists on the registry. Used to filter the prompt:
+     * "esp-idf" is a known family with no published package yet, so it must not
+     * be offered for install (it would fail at the package-manager step).
+     */
+    installable: boolean;
+}
+/**
+ * The installable frameworks. Kept aligned with the packages/ directory:
+ * framework-arduino, framework-native, framework-zephyr all ship real packages.
+ * esp-idf is intentionally absent (no published package in this repo).
+ */
+export declare const FRAMEWORK_CATALOG: readonly FrameworkCatalogEntry[];
+/** Structural shape we need from a board/target. Keeps this module decoupled
+ *  from the create/ module's KnownTarget (and trivially testable with literals). */
+export interface BoardLike {
+    isNative?: boolean;
+    architecture?: string;
+}
+/** Look up a catalog entry by framework id (e.g. "arduino"). */
+export declare function frameworkCatalogEntry(id: string): FrameworkCatalogEntry | undefined;
+/**
+ * The framework ids compatible with a board. Native boards map to ["native"];
+ * embedded boards map via ARCHITECTURE_FRAMEWORKS (falling back to arduino for
+ * unknown architectures). Order is preserved as the catalog order so the most
+ * common framework is offered first in the prompt.
+ */
+export declare function frameworksForTarget(target: BoardLike): FrameworkCatalogEntry[];
+export type PackageManager = "npm" | "pnpm" | "yarn";
+/**
+ * Detect the package manager for a directory. Priority:
+ *   1. package.json#packageManager field (the strongest signal, Corepack-style)
+ *   2. lockfile presence (pnpm-lock.yaml / yarn.lock → otherwise npm)
+ *   3. default "npm"
+ * Never throws — unreadable/missing files fall through to the next signal.
+ */
+export declare function detectPackageManager(cwd: string): PackageManager;
+/**
+ * Build the package-manager invocation that installs `packageName` into the
+ * current project (project-local, never global — per the install command spec).
+ */
+export declare function buildInstallCommand(pm: PackageManager, packageName: string): {
+    bin: string;
+    args: string[];
+};

package/dist/install/framework-catalog.js

@@ -0,0 +1,107 @@
+// Framework catalog + board→framework compatibility for `cuttlefish install`.
+//
+// A "framework" is a `@typecad/framework-<id>` npm package. This module is the
+// single source of truth for which frameworks exist as installable packages and
+// which are compatible with a given board architecture. It is deliberately
+// free of side effects (no fs/process beyond lockfile/package.json reads in
+// detectPackageManager) so it unit-tests cleanly.
+import path from "node:path";
+import fs from "node:fs";
+/**
+ * The installable frameworks. Kept aligned with the packages/ directory:
+ * framework-arduino, framework-native, framework-zephyr all ship real packages.
+ * esp-idf is intentionally absent (no published package in this repo).
+ */
+export const FRAMEWORK_CATALOG = [
+    { id: "arduino", packageName: "@typecad/framework-arduino", label: "Arduino (digitalWrite, Wire, SPI)", installable: true },
+    { id: "zephyr", packageName: "@typecad/framework-zephyr", label: "Zephyr RTOS", installable: true },
+    { id: "native", packageName: "@typecad/framework-native", label: "Native (Windows/Linux executable)", installable: true },
+];
+/**
+ * Architecture → compatible framework ids. Derived from each framework
+ * package's framework.manifest.ts `profile.targets`:
+ *   - arduino: avr, esp32 family, rp2040/rp2350, samd, stm32
+ *   - zephyr:  nrf52 (xiao_ble), esp32, esp32s3
+ *   - native:  desktop only
+ * Unknown embedded architectures fall back to [arduino] (the broadest core).
+ */
+const ARCHITECTURE_FRAMEWORKS = {
+    avr: ["arduino"],
+    esp32: ["arduino", "zephyr"],
+    esp32s2: ["arduino"],
+    esp32s3: ["arduino", "zephyr"],
+    esp32c3: ["arduino"],
+    esp32c6: ["arduino"],
+    rp2040: ["arduino"],
+    rp2350: ["arduino"],
+    samd: ["arduino"],
+    stm32: ["arduino"],
+    nrf52: ["zephyr"],
+};
+const FALLBACK_FRAMEWORKS = ["arduino"];
+/** Look up a catalog entry by framework id (e.g. "arduino"). */
+export function frameworkCatalogEntry(id) {
+    return FRAMEWORK_CATALOG.find((f) => f.id === id);
+}
+/**
+ * The framework ids compatible with a board. Native boards map to ["native"];
+ * embedded boards map via ARCHITECTURE_FRAMEWORKS (falling back to arduino for
+ * unknown architectures). Order is preserved as the catalog order so the most
+ * common framework is offered first in the prompt.
+ */
+export function frameworksForTarget(target) {
+    let ids;
+    if (target.isNative) {
+        ids = ["native"];
+    }
+    else {
+        ids = ARCHITECTURE_FRAMEWORKS[target.architecture ?? ""] ?? FALLBACK_FRAMEWORKS;
+    }
+    // Re-map ids → catalog entries in catalog order (stable ordering), dropping
+    // any id that has no catalog entry (defensive — keeps the prompt clean).
+    return FRAMEWORK_CATALOG.filter((entry) => ids.includes(entry.id));
+}
+/**
+ * Detect the package manager for a directory. Priority:
+ *   1. package.json#packageManager field (the strongest signal, Corepack-style)
+ *   2. lockfile presence (pnpm-lock.yaml / yarn.lock → otherwise npm)
+ *   3. default "npm"
+ * Never throws — unreadable/missing files fall through to the next signal.
+ */
+export function detectPackageManager(cwd) {
+    try {
+        const pkgPath = path.join(cwd, "package.json");
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        const pm = typeof pkg.packageManager === "string" ? pkg.packageManager : "";
+        if (pm.startsWith("pnpm"))
+            return "pnpm";
+        if (pm.startsWith("yarn"))
+            return "yarn";
+        if (pm.startsWith("npm"))
+            return "npm";
+    }
+    catch {
+        // no package.json or unparseable JSON — fall through to lockfile detection
+    }
+    if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (fs.existsSync(path.join(cwd, "yarn.lock")))
+        return "yarn";
+    // package-lock.json implies npm; absence also defaults to npm.
+    return "npm";
+}
+/**
+ * Build the package-manager invocation that installs `packageName` into the
+ * current project (project-local, never global — per the install command spec).
+ */
+export function buildInstallCommand(pm, packageName) {
+    switch (pm) {
+        case "pnpm":
+            return { bin: "pnpm", args: ["add", packageName] };
+        case "yarn":
+            return { bin: "yarn", args: ["add", packageName] };
+        case "npm":
+        default:
+            return { bin: "npm", args: ["install", packageName] };
+    }
+}

package/dist/install/handle-install.d.ts

@@ -0,0 +1,35 @@
+import type { InstallCommandOptions } from "../types.js";
+import { type FrameworkCatalogEntry, type PackageManager } from "./framework-catalog.js";
+interface InstallCommand {
+    bin: string;
+    args: string[];
+    cwd: string;
+}
+interface InstallRunResult {
+    /** Exit status; null when the process could not be launched (ENOENT, etc.). */
+    status: number | null;
+    /** Populated only when the binary could not be launched. */
+    launchError?: string;
+}
+type InstallRunner = (cmd: InstallCommand) => InstallRunResult;
+/**
+ * FOR TESTS ONLY. Replaces the real spawn-based installer with `runner`.
+ * Pass `undefined` to restore the real executor.
+ */
+export declare function __setInstallRunnerForTest(runner: InstallRunner | undefined): void;
+export interface InstallResult {
+    pm: PackageManager;
+    bin: string;
+    args: string[];
+}
+/**
+ * Resolve the package manager and run the install for `entry`'s package. In
+ * dry-run mode the command is printed but not executed. Throws on launch
+ * failure or non-zero exit so the CLI surfaces a clear error.
+ */
+export declare function installFrameworkPackage(entry: FrameworkCatalogEntry, opts: {
+    cwd: string;
+    dryRun?: boolean;
+}): InstallResult;
+export declare function handleInstall(options: InstallCommandOptions): Promise<void>;
+export {};

package/dist/install/handle-install.js

@@ -0,0 +1,177 @@
+// `cuttlefish install` — installs a chosen @typecad/framework-* package into the
+// current project. The flow asks which board to target first, then narrows the
+// framework choices to those compatible with that board (see framework-catalog).
+// A framework id may be passed directly (`cuttlefish install arduino`) to skip
+// the prompts entirely, which also makes the command usable in CI.
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { spawnSync } from "node:child_process";
+import chalk from "chalk";
+import { KNOWN_TARGETS } from "../create/index.js";
+import { FRAMEWORK_CATALOG, frameworkCatalogEntry, frameworksForTarget, detectPackageManager, buildInstallCommand, } from "./framework-catalog.js";
+// ── prompts (mirror the create wizard's style for a consistent UX) ──────────
+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}`);
+    }
+    while (true) {
+        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}.`);
+    }
+}
+async function selectBoardInteractively(rl) {
+    const options = KNOWN_TARGETS.map((t) => ({
+        label: t.isNative
+            ? `${t.displayName} (Windows/Linux executable)`
+            : `${t.displayName} (${t.architecture.toUpperCase()})`,
+        value: t.id,
+    }));
+    const selectedId = await promptSelect(rl, "Target board", options);
+    return KNOWN_TARGETS.find((t) => t.id === selectedId);
+}
+/**
+ * Pick a framework for `target`. When only one framework is compatible with the
+ * board it is auto-selected (mirrors the create wizard's single-option path) so
+ * the user isn't asked a question with one answer.
+ */
+async function selectFrameworkInteractively(rl, target, compatible) {
+    if (compatible.length === 1) {
+        const only = compatible[0];
+        console.log(`${chalk.cyan("?")} Framework: ${chalk.white(only.label)} ${chalk.dim(`(only option for ${target.id})`)}`);
+        return only;
+    }
+    const selectedId = await promptSelect(rl, "Framework", compatible.map((f) => ({ label: f.label, value: f.id })));
+    return compatible.find((f) => f.id === selectedId);
+}
+let testRunner;
+/**
+ * FOR TESTS ONLY. Replaces the real spawn-based installer with `runner`.
+ * Pass `undefined` to restore the real executor.
+ */
+export function __setInstallRunnerForTest(runner) {
+    testRunner = runner;
+}
+function runRealInstall(cmd) {
+    // stdio: "inherit" streams the package manager's own output to the terminal
+    // (install progress, deprecation warnings, etc.). On failure the user has
+    // already seen the details above, so we only need to report the exit code.
+    const result = spawnSync(cmd.bin, cmd.args, {
+        cwd: cmd.cwd,
+        stdio: "inherit",
+    });
+    if (result.error) {
+        const errno = result.error.code;
+        return {
+            status: null,
+            launchError: errno === "ENOENT" ? `'${cmd.bin}' not found on PATH` : String(result.error),
+        };
+    }
+    return { status: result.status };
+}
+/**
+ * Resolve the package manager and run the install for `entry`'s package. In
+ * dry-run mode the command is printed but not executed. Throws on launch
+ * failure or non-zero exit so the CLI surfaces a clear error.
+ */
+export function installFrameworkPackage(entry, opts) {
+    const pm = detectPackageManager(opts.cwd);
+    const { bin, args } = buildInstallCommand(pm, entry.packageName);
+    if (opts.dryRun) {
+        console.log(`${chalk.cyan("$")} ${bin} ${args.join(" ")}`);
+        return { pm, bin, args };
+    }
+    const cmd = { bin, args, cwd: opts.cwd };
+    const run = testRunner ?? runRealInstall;
+    const result = run(cmd);
+    if (result.launchError) {
+        throw new Error(`Failed to run '${bin}': ${result.launchError}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`'${bin} ${args.join(" ")}' exited with code ${result.status}. See the package manager output above for details.`);
+    }
+    return { pm, bin, args };
+}
+// ── command entry point ─────────────────────────────────────────────────────
+export async function handleInstall(options) {
+    const cwd = process.cwd();
+    // 1. Resolve which framework to install.
+    let entry;
+    if (options.framework) {
+        const resolved = frameworkCatalogEntry(options.framework);
+        if (!resolved) {
+            const available = FRAMEWORK_CATALOG.filter((f) => f.installable).map((f) => f.id).join(", ");
+            throw new Error(`Unknown framework '${options.framework}'. Available: ${available}`);
+        }
+        if (!resolved.installable) {
+            throw new Error(`Framework '${options.framework}' has no published package yet and cannot be installed.`);
+        }
+        entry = resolved;
+        console.log(`${chalk.cyan("?")} Framework: ${chalk.white(entry.label)}`);
+    }
+    else {
+        // Resolve the target board. --board skips the board prompt; otherwise the
+        // board is chosen interactively (which requires a TTY — handled below).
+        let target;
+        if (options.board) {
+            const found = KNOWN_TARGETS.find((t) => t.id === options.board);
+            if (!found) {
+                const available = KNOWN_TARGETS.map((t) => t.id).join(", ");
+                throw new Error(`Unknown board '${options.board}'. Available: ${available}`);
+            }
+            target = found;
+            console.log(`${chalk.cyan("?")} Board: ${chalk.white(target.displayName)} (${chalk.dim(target.id)})`);
+        }
+        // Narrow to the frameworks compatible with that board.
+        let compatible;
+        if (target) {
+            compatible = frameworksForTarget(target).filter((f) => f.installable);
+            if (compatible.length === 0) {
+                throw new Error(`No installable frameworks are compatible with board '${target.id}'.`);
+            }
+        }
+        if (compatible && compatible.length === 1) {
+            // Only one framework fits this board — auto-select it (no prompt, so this
+            // path also works under CI / non-interactive stdin).
+            entry = compatible[0];
+            console.log(`${chalk.cyan("?")} Framework: ${chalk.white(entry.label)} ${chalk.dim(`(only option for ${target.id})`)}`);
+        }
+        else {
+            // Need to prompt — for the board (if --board wasn't given) and/or for the
+            // framework (when 2+ are compatible). Refuse to hang on a readline that
+            // can't be answered (e.g. piped stdin under CI).
+            if (!process.stdin.isTTY) {
+                throw new Error("No framework specified and stdin is not interactive. " +
+                    "Pass a framework id (e.g. 'cuttlefish install arduino'), " +
+                    "or a board with a single compatible framework (e.g. '--board arduino-uno').");
+            }
+            const rl = readline.createInterface({ input, output });
+            try {
+                if (!target) {
+                    target = await selectBoardInteractively(rl);
+                    compatible = frameworksForTarget(target).filter((f) => f.installable);
+                    if (compatible.length === 0) {
+                        throw new Error(`No installable frameworks are compatible with board '${target.id}'.`);
+                    }
+                }
+                entry = await selectFrameworkInteractively(rl, target, compatible);
+            }
+            finally {
+                rl.close();
+            }
+        }
+    }
+    // 2. Install it.
+    console.log(`\n${chalk.cyan("⤳")} Installing ${chalk.white(entry.packageName)} into ${chalk.dim(cwd)}…`);
+    const result = installFrameworkPackage(entry, { cwd, dryRun: options.dryRun });
+    if (options.dryRun) {
+        console.log(chalk.dim("(dry-run — nothing was installed)"));
+        return;
+    }
+    console.log(`\n${chalk.green("✓")} Installed ${chalk.white(entry.packageName)} via ${result.pm}.`);
+    console.log(chalk.dim(`Next: run 'cuttlefish create' and pick ${entry.id}, or set framework: "${entry.packageName}" in cuttlefish.config.ts.`));
+}

package/dist/install/index.d.ts

@@ -0,0 +1,4 @@
+export { handleInstall, installFrameworkPackage, __setInstallRunnerForTest } from "./handle-install.js";
+export type { InstallResult } from "./handle-install.js";
+export { FRAMEWORK_CATALOG, frameworkCatalogEntry, frameworksForTarget, detectPackageManager, buildInstallCommand, } from "./framework-catalog.js";
+export type { FrameworkCatalogEntry, BoardLike, PackageManager, } from "./framework-catalog.js";

package/dist/install/index.js

@@ -0,0 +1,3 @@
+// `cuttlefish install` command — install a @typecad/framework-* package.
+export { handleInstall, installFrameworkPackage, __setInstallRunnerForTest } from "./handle-install.js";
+export { FRAMEWORK_CATALOG, frameworkCatalogEntry, frameworksForTarget, detectPackageManager, buildInstallCommand, } from "./framework-catalog.js";

package/dist/types.d.ts

@@ -231,4 +231,13 @@ export interface BoardAddCommandOptions {
     specPath: string;
     force?: boolean;
 }
+export interface InstallCommandOptions {
+    command: "install";
+    /** Framework id to install directly (e.g. "arduino"), skipping the prompts. */
+    framework?: string;
+    /** Board/target id to narrow framework choices (e.g. "esp32-devkit"). */
+    board?: string;
+    /** Resolve and print the package-manager command without running it. */
+    dryRun?: boolean;
+}
 export {};

package/dist/utils/cli.d.ts

@@ -1,3 +1,3 @@
-import { CommandLineOptions, CreateCommandOptions, BoardAddCommandOptions } from "../types.js";
+import { CommandLineOptions, CreateCommandOptions, BoardAddCommandOptions, InstallCommandOptions } 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 | InstallCommandOptions | "help";

package/dist/utils/cli.js

@@ -11,6 +11,7 @@ export function printHelp() {
     console.log();
     console.log(`  cuttlefish <input.ts> [options]`);
     console.log(`  cuttlefish create [name] [options]`);
+    console.log(`  cuttlefish install [framework] [--board id]  Install a @typecad/framework-* package (asks board, then narrows frameworks)`);
     console.log(`  cuttlefish build [options]`);
     console.log(`  cuttlefish preview [--config <path>] [--port <port>]`);
     console.log(`  cuttlefish gen-libdefs <input.ts>`);
@@ -357,6 +358,22 @@ export function parseCommandLine(argv) {
             outDir: outDir ? path.resolve(process.cwd(), outDir) : undefined,
         };
     }
+    // install subcommand — install a @typecad/framework-* package. A framework id
+    // may be passed positionally (`cuttlefish install arduino`) or via --framework;
+    // --board narrows the interactive framework prompt to that board's options.
+    if (firstArg === "install") {
+        const secondArg = argv[3];
+        const positionalFramework = secondArg && !secondArg.startsWith("-") ? secondArg : undefined;
+        const framework = positionalFramework ?? readFirstFlagValue(argv, ["--framework", "-f"]);
+        const board = readFirstFlagValue(argv, ["--board", "-b"]);
+        const dryRun = argv.includes("--dry-run");
+        return {
+            command: "install",
+            framework,
+            board,
+            dryRun,
+        };
+    }
     if (firstArg === "create-board") {
         throw new Error(`The 'create-board' command has been removed. Board scaffolding is now in @typecad/create.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/cuttlefish",
-  "version": "1.0.0-alpha.8",
+  "version": "1.0.0-alpha.9",
   "description": "TypeScript to C++ transpiler — native, Arduino, and bare-metal targets",
   "type": "module",
   "main": "./dist/transpile.js",
@@ -99,8 +99,8 @@
     "zod": "^3.24.0"
   },
   "peerDependencies": {
-    "@typecad/ui": "1.0.0-alpha.8",
-    "@typecad/safety": "1.0.0-alpha.8"
+    "@typecad/ui": "1.0.0-alpha.9",
+    "@typecad/safety": "1.0.0-alpha.9"
   },
   "peerDependenciesMeta": {
     "@typecad/ui": {
@@ -111,7 +111,7 @@
     }
   },
   "optionalDependencies": {
-    "@typecad/framework-native": "1.0.0-alpha.8"
+    "@typecad/framework-native": "1.0.0-alpha.9"
   },
   "devDependencies": {
     "@types/node": "^22.10.7"