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

package/dist/create/board-spec.js

@@ -1,214 +0,0 @@
-// ---------------------------------------------------------------------------
-// board-spec.ts — Zod schema + types for the .jsonc chip spec consumed by
-// `cuttlefish board add`. The spec is a human-authored description of the
-// silicon + board; the codegen transforms it into package source files.
-// ---------------------------------------------------------------------------
-import { z } from 'zod';
-// ---------------------------------------------------------------------------
-// Comment stripper — .jsonc → JSON. Strips // line comments and /* */ blocks
-// while respecting string literals (a // inside a string is not a comment).
-// ---------------------------------------------------------------------------
-export function stripJsonc(text) {
-    let result = '';
-    let i = 0;
-    while (i < text.length) {
-        const ch = text[i];
-        const next = text[i + 1];
-        // String literal — copy verbatim until closing quote
-        if (ch === '"') {
-            result += ch;
-            i++;
-            while (i < text.length) {
-                result += text[i];
-                if (text[i] === '\\' && i + 1 < text.length) {
-                    result += text[i + 1];
-                    i += 2;
-                    continue;
-                }
-                if (text[i] === '"') {
-                    i++;
-                    break;
-                }
-                i++;
-            }
-            continue;
-        }
-        // Line comment // ... \n
-        if (ch === '/' && next === '/') {
-            while (i < text.length && text[i] !== '\n')
-                i++;
-            continue;
-        }
-        // Block comment /* ... */
-        if (ch === '/' && next === '*') {
-            i += 2;
-            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
-                i++;
-            i += 2;
-            continue;
-        }
-        result += ch;
-        i++;
-    }
-    return result;
-}
-// ---------------------------------------------------------------------------
-// Sub-schemas
-// ---------------------------------------------------------------------------
-const PinFunctionSchema = z.object({
-    type: z.enum(['i2c', 'spi', 'uart', 'adc', 'dac', 'pwm', 'touch', 'usb']),
-    instance: z.number().int(),
-    role: z.string(),
-}).strict();
-const PinSpecSchema = z.object({
-    gpio: z.number().int(),
-    capabilities: z.enum([
-        'FULL_GPIO', 'FULL_GPIO_ANALOG', 'FULL_GPIO_TOUCH',
-        'FULL_GPIO_ANALOG_TOUCH', 'FULL_GPIO_DAC', 'INPUT_ONLY',
-    ]),
-    functions: z.array(PinFunctionSchema).optional(),
-    alt: z.array(z.string()).optional(),
-    warnings: z.array(z.string()).optional(),
-    unsafe: z.boolean().optional(),
-    notes: z.string().optional(),
-    onboardLed: z.boolean().optional(),
-}).strict();
-const PeripheralInstanceSchema = z.object({
-    instance: z.number().int(),
-    defaultPins: z.record(z.string(), z.string()),
-    alternatePins: z.record(z.string(), z.array(z.string())).optional(),
-}).strict();
-const AdcSchema = z.object({
-    instance: z.number().int(),
-    channels: z.number().int(),
-    resolution: z.number().int(),
-    referenceVoltage: z.number(),
-    maxValue: z.number().int(),
-    referenceVoltages: z.record(z.string(), z.number()).optional(),
-}).strict();
-const BusPinMapSchema = z.record(z.string(), z.object({
-    sda: z.string().optional(),
-    scl: z.string().optional(),
-    mosi: z.string().optional(),
-    miso: z.string().optional(),
-    sck: z.string().optional(),
-    cs: z.string().optional(),
-    tx: z.string().optional(),
-    rx: z.string().optional(),
-}).strict());
-// ---------------------------------------------------------------------------
-// Top-level spec schema
-// ---------------------------------------------------------------------------
-export const BoardSpecSchema = z.object({
-    // Identity
-    architecture: z.string().min(1),
-    mcuId: z.string().min(1),
-    mcuName: z.string().min(1),
-    boardId: z.string().min(1),
-    boardName: z.string().min(1),
-    vendor: z.string().min(1),
-    description: z.string().optional(),
-    // Build
-    clockSpeed: z.number().int(),
-    fqbn: z.string().min(1),
-    arduinoDefine: z.string().min(1),
-    // Memory (module-level; silicon memory is derived)
-    moduleFlash: z.number().int().nullable(),
-    externalRam: z.number().int().nullable(),
-    // GPIO range
-    gpioRange: z.tuple([z.number().int(), z.number().int()]),
-    excludedGpio: z.array(z.number().int()),
-    // Pin data
-    pins: z.array(PinSpecSchema),
-    unsafe: z.array(z.string()),
-    analog: z.array(z.string()),
-    // Bus maps
-    i2c: BusPinMapSchema,
-    spi: BusPinMapSchema,
-    uart: BusPinMapSchema,
-    // Peripherals
-    peripheralInstances: z.object({
-        i2c: z.array(PeripheralInstanceSchema),
-        spi: z.array(PeripheralInstanceSchema),
-        uart: z.array(PeripheralInstanceSchema),
-    }).strict(),
-    adc: z.array(AdcSchema),
-    pwm: z.object({
-        channels: z.number().int(),
-        resolution: z.number().int(),
-        maxFrequency: z.number().int(),
-    }).strict(),
-    touch: z.object({
-        channels: z.number().int(),
-        pins: z.array(z.string()),
-    }).nullable().optional(),
-    timers: z.array(z.object({
-        instance: z.number().int(),
-        type: z.enum(['general', 'high_speed', 'rtc', 'sys']),
-        bits: z.union([z.literal(8), z.literal(16), z.literal(32), z.literal(64)]),
-        features: z.array(z.enum(['pwm', 'capture', 'compare', 'interrupt', 'dma'])).optional(),
-    }).strict()),
-    // Connectivity
-    wifi: z.object({
-        type: z.enum(['wifi', 'wifi6']),
-        supportsStation: z.boolean(),
-        supportsAp: z.boolean(),
-    }).strict(),
-    bluetooth: z.object({
-        type: z.enum(['classic', 'ble', 'dual']),
-        version: z.string(),
-    }).strict(),
-    usb: z.object({
-        type: z.enum(['device', 'host', 'otg']),
-        vid: z.string(),
-        pid: z.string(),
-    }).strict(),
-    // Features
-    features: z.object({
-        multicore: z.boolean(),
-        coreCount: z.number().int(),
-        deepSleep: z.boolean(),
-        watchdog: z.boolean(),
-        externalInterrupts: z.boolean(),
-        hardwareRng: z.boolean(),
-        fpu: z.boolean(),
-    }).strict(),
-    // Silicon memory
-    memory: z.object({
-        flash: z.number().int(),
-        sram: z.number().int(),
-        eeprom: z.number().int(),
-        externalRam: z.number().int().optional(),
-        rtcMemory: z.number().int().optional(),
-    }).strict(),
-}).strict();
-// ---------------------------------------------------------------------------
-// Parse + validate a .jsonc string
-// ---------------------------------------------------------------------------
-export function parseBoardSpec(jsoncText) {
-    const jsonText = stripJsonc(jsoncText);
-    let parsed;
-    try {
-        parsed = JSON.parse(jsonText);
-    }
-    catch (e) {
-        throw new Error(`Invalid JSON in spec file: ${e.message}`);
-    }
-    return BoardSpecSchema.parse(parsed);
-}
-export function safeParseBoardSpec(jsoncText) {
-    try {
-        const spec = parseBoardSpec(jsoncText);
-        return { success: true, spec };
-    }
-    catch (e) {
-        if (e instanceof z.ZodError) {
-            const errors = e.issues.map(issue => {
-                const path = issue.path.join('.');
-                return path ? `${path}: ${issue.message}` : issue.message;
-            });
-            return { success: false, errors };
-        }
-        return { success: false, errors: [e.message] };
-    }
-}

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>;

package/dist/create/init-wizard.js

@@ -1,182 +0,0 @@
-import * as readline from "node:readline/promises";
-import { stdin as input, stdout as output } from "node:process";
-import chalk from "chalk";
-import { KNOWN_TARGETS } from "./init-scaffold.js";
-import { frameworksForTarget, frameworkCatalogEntry, FRAMEWORK_CATALOG, frameworkTargetProfile } from "./framework-catalog.js";
-function validateProjectName(name) {
-    if (!name || name.trim().length === 0) {
-        return "Project name cannot be empty.";
-    }
-    const normalized = name.trim().toLowerCase();
-    if (!/^[a-z][a-z0-9-]*$/.test(normalized)) {
-        return "Project name must start with a letter and contain only lowercase letters, digits, and hyphens.";
-    }
-    if (normalized.length > 64) {
-        return "Project name must be 64 characters or fewer.";
-    }
-    return null;
-}
-async function promptText(rl, prompt, defaultValue, validate) {
-    while (true) {
-        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}`);
-    }
-    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 promptConfirm(rl, prompt, defaultValue) {
-    const suffix = defaultValue ? " (Y/n)" : " (y/N)";
-    const answer = await rl.question(`${chalk.cyan("?")} ${prompt}${suffix}: `);
-    const trimmed = answer.trim().toLowerCase();
-    if (trimmed === "")
-        return defaultValue;
-    return trimmed === "y" || trimmed === "yes";
-}
-export async function runInitWizard(partialOptions) {
-    const rl = readline.createInterface({ input, output });
-    try {
-        console.log();
-        console.log(chalk.cyan("⤳ Cuttlefish") + chalk.dim(" — Project Setup"));
-        console.log();
-        // 1. Project name
-        const projectName = partialOptions?.projectName
-            ?? await promptText(rl, "Project name", "my-project", validateProjectName);
-        // 2. Target selection (native first, then embedded boards)
-        const targetOptions = KNOWN_TARGETS.map((t) => ({
-            label: t.isNative
-                ? `${t.displayName} (Windows/Linux executable)`
-                : `${t.displayName} (${t.architecture.toUpperCase()})`,
-            value: t.id,
-        }));
-        let targetId;
-        if (partialOptions?.board) {
-            const found = KNOWN_TARGETS.find((t) => t.id === partialOptions.board);
-            if (found) {
-                targetId = found.id;
-                console.log(`${chalk.cyan("?")} Target: ${chalk.white(found.displayName)} (${chalk.dim(partialOptions.board)})`);
-            }
-            else {
-                console.log(`  ${chalk.yellow("!")} Target '${chalk.white(partialOptions.board)}' not found.`);
-                targetId = await promptSelect(rl, "Target", targetOptions);
-            }
-        }
-        else {
-            targetId = await promptSelect(rl, "Target", targetOptions);
-        }
-        const target = KNOWN_TARGETS.find((t) => t.id === targetId);
-        // 3. Framework. Narrow to the frameworks compatible with the selected board
-        // (see framework-catalog), then let the user pick. The chosen package is
-        // installed into the new project by `cuttlefish create`, so we offer every
-        // compatible framework regardless of what is currently installed — no
-        // require.resolve discovery (which also avoided an ESM `require` pitfall
-        // where the lookup always failed and made the wizard dead-end).
-        let framework = target.framework;
-        let frameworkPackage = target.frameworkPackage;
-        const compatible = frameworksForTarget(target).filter((f) => f.installable);
-        if (compatible.length === 0) {
-            // Defensive: every known target maps to at least one framework in the catalog.
-            throw new Error(`No installable frameworks are compatible with target '${target.id}'.`);
-        }
-        if (partialOptions?.framework) {
-            const requested = frameworkCatalogEntry(partialOptions.framework);
-            if (!requested) {
-                const available = FRAMEWORK_CATALOG.filter((f) => f.installable).map((f) => f.id).join(", ");
-                throw new Error(`Unknown framework '${partialOptions.framework}'. Available: ${available}`);
-            }
-            framework = requested.id;
-            frameworkPackage = requested.packageName;
-            console.log(`${chalk.cyan("?")} Framework: ${chalk.white(requested.label)}`);
-        }
-        else if (compatible.length === 1) {
-            framework = compatible[0].id;
-            frameworkPackage = compatible[0].packageName;
-            console.log(`${chalk.cyan("?")} Framework: ${chalk.white(compatible[0].label)}`);
-        }
-        else {
-            const selected = await promptSelect(rl, "Framework", compatible.map((f) => ({ label: f.label, value: f.id })));
-            const match = compatible.find((f) => f.id === selected);
-            framework = match.id;
-            frameworkPackage = match.packageName;
-        }
-        // Resolve the framework-specific build target + toolchain (e.g. a Zephyr
-        // board id + 'west' vs the Arduino FQBN + 'arduino-cli'). See framework-catalog.
-        const profile = frameworkTargetProfile(target, framework);
-        // 4. Baud rate (only for embedded)
-        let baudRate;
-        if (!target.isNative) {
-            if (partialOptions?.baud) {
-                baudRate = partialOptions.baud;
-                console.log(`${chalk.cyan("?")} Serial baud rate: ${chalk.white(baudRate)}`);
-            }
-            else {
-                const baudAnswer = await promptText(rl, "Serial baud rate", "9600");
-                baudRate = parseInt(baudAnswer, 10);
-                if (Number.isNaN(baudRate) || baudRate <= 0) {
-                    baudRate = 9600;
-                    console.log(`  ${chalk.dim("Using default: 9600")}`);
-                }
-            }
-        }
-        // 5. Starter sketch
-        let includeSketch;
-        if (partialOptions?.noSketch) {
-            includeSketch = false;
-            console.log(`${chalk.cyan("?")} Create starter sketch: ${chalk.dim("no")}`);
-        }
-        else if (partialOptions?.noSketch === false) {
-            includeSketch = true;
-            console.log(`${chalk.cyan("?")} Create starter sketch: ${chalk.green("yes")}`);
-        }
-        else {
-            includeSketch = await promptConfirm(rl, "Create starter sketch?", true);
-        }
-        return {
-            projectName,
-            targetId: target.id,
-            targetDisplayName: target.displayName,
-            isNative: target.isNative,
-            architecture: target.architecture,
-            boardPackage: target.boardPackage,
-            frameworkPackage: frameworkPackage ?? '',
-            framework: framework ?? '',
-            buildTarget: profile.buildTarget ?? target.buildTarget,
-            ...(profile.toolchainType ? { toolchainType: profile.toolchainType } : {}),
-            mcu: target.mcu,
-            baudRate,
-            includeSketch,
-            ...(target.frameworkData
-                ? { frameworkData: target.frameworkData }
-                : {}),
-        };
-    }
-    catch (err) {
-        if (err && typeof err === 'object' && err.code === 'ERR_USE_AFTER_CLOSE') {
-            return null;
-        }
-        throw err;
-    }
-    finally {
-        rl.close();
-    }
-}

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

@@ -1,53 +0,0 @@
-/** 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

@@ -1,107 +0,0 @@
-// 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

@@ -1,35 +0,0 @@
-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 {};