@typecad/cuttlefish 0.1.0-alpha.2 → 1.0.0-alpha.11

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

@@ -0,0 +1,64 @@
+/** 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 create 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 (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 KnownTarget type (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;
+export interface FrameworkTargetProfile {
+    /** Framework-specific build target (FQBN for Arduino, board id for Zephyr). */
+    buildTarget?: string;
+    /** Toolchain backend the framework's compile/upload expects. */
+    toolchainType?: string;
+}
+export interface TargetProfileInput {
+    id: string;
+    isNative?: boolean;
+    /** The board's Arduino FQBN, as currently stored on KnownTarget. */
+    buildTarget?: string;
+}
+/**
+ * Resolve the framework-specific buildTarget + toolchain type for a
+ * (board, framework) pair. Arduino reuses the board's FQBN; Zephyr maps to the
+ * Zephyr board id; native returns an empty profile (the native config writes
+ * neither field).
+ */
+export declare function frameworkTargetProfile(target: TargetProfileInput, frameworkId: string): FrameworkTargetProfile;
+/**
+ * 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;

package/dist/create/framework-catalog.js

@@ -0,0 +1,136 @@
+// Framework catalog + board→framework compatibility for the create wizard.
+//
+// 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);
+}
+// ── framework-specific build target + toolchain ─────────────────────────────
+// A board's buildTarget string is NOT framework-independent: Arduino uses an
+// FQBN (e.g. 'esp32:esp32:esp32s3') while Zephyr uses a board id for
+// `west build -b` (e.g. 'esp32s3_devkitc'). The scaffold must pick the right
+// one for the chosen framework, and the matching toolchain backend
+// ('arduino-cli' vs 'west'). Source for Zephyr board ids: framework-zephyr's
+// chip registry (src/chips/index.ts) + the demo configs.
+const FRAMEWORK_TOOLCHAIN = {
+    arduino: "arduino-cli",
+    zephyr: "west",
+    // native has no toolchain (the native config path writes neither field).
+};
+/**
+ * Zephyr board target for each cuttlefish board id that supports Zephyr. These
+ * are the full qualified targets passed to `west build -b <target>` (framework-
+ * zephyr's chipForTarget splits on '/' and takes the board id, so the qualified
+ * form resolves correctly there too). Zephyr 4.3+ REQUIRES the qualifier for
+ * multi-core ESP32 boards — the bare id (e.g. 'esp32s3_devkitc') is rejected
+ * with "Board qualifiers ... not found". procpu is the main application core.
+ */
+const ZEPHYR_BOARD_IDS = {
+    "esp32-devkit": "esp32_devkitc/esp32/procpu",
+    esp32s3: "esp32s3_devkitc/esp32s3/procpu",
+    // xiao_ble isn't currently a KNOWN_TARGETS entry, but keep the descriptor
+    // correct for completeness: nRF52840 (single core), base (non-sense) variant.
+    "xiao-nrf52840": "xiao_ble/nrf52840",
+};
+/**
+ * Resolve the framework-specific buildTarget + toolchain type for a
+ * (board, framework) pair. Arduino reuses the board's FQBN; Zephyr maps to the
+ * Zephyr board id; native returns an empty profile (the native config writes
+ * neither field).
+ */
+export function frameworkTargetProfile(target, frameworkId) {
+    if (target.isNative) {
+        return {};
+    }
+    const toolchainType = FRAMEWORK_TOOLCHAIN[frameworkId];
+    if (frameworkId === "zephyr") {
+        return { buildTarget: ZEPHYR_BOARD_IDS[target.id], toolchainType };
+    }
+    // Arduino (and any unlisted framework) → use the board's FQBN.
+    return { buildTarget: target.buildTarget, toolchainType };
+}
+/**
+ * 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";
+}

package/dist/create/index.d.ts

@@ -1,6 +1,10 @@
 export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printInitNextSteps } from './init-scaffold.js';
 export type { KnownTarget, KnownBoard, ScaffoldProjectResult } from './init-scaffold.js';
-export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateEslintConfig, } from './init-templates.js';
+export { FRAMEWORK_CATALOG, frameworksForTarget, frameworkCatalogEntry, detectPackageManager, frameworkTargetProfile } from './framework-catalog.js';
+export type { FrameworkCatalogEntry, BoardLike, PackageManager, FrameworkTargetProfile, TargetProfileInput } from './framework-catalog.js';
+export { installProjectDependencies, __setProjectInstallRunnerForTest } from './install-deps.js';
+export type { ProjectInstallResult } from './install-deps.js';
+export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, } from './init-templates.js';
 export type { InitProjectOptions } from './init-templates.js';
 export { runInitWizard } from './init-wizard.js';
 export { scaffoldBoardPackages } from './board-codegen.js';

package/dist/create/index.js

@@ -1,5 +1,7 @@
 export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printInitNextSteps } from './init-scaffold.js';
-export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateEslintConfig, } from './init-templates.js';
+export { FRAMEWORK_CATALOG, frameworksForTarget, frameworkCatalogEntry, detectPackageManager, frameworkTargetProfile } from './framework-catalog.js';
+export { installProjectDependencies, __setProjectInstallRunnerForTest } from './install-deps.js';
+export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, } from './init-templates.js';
 export { runInitWizard } from './init-wizard.js';
 // Board codegen tool (`cuttlefish board add`)
 export { scaffoldBoardPackages } from './board-codegen.js';

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

@@ -6,10 +6,17 @@ export interface KnownTarget {
     isNative: boolean;
     architecture?: ArchitectureIdentifier;
     boardPackage?: string;
-    frameworkPackage: string;
-    framework: string;
+    /** Framework package + id. Optional on embedded targets: the scaffold wizard
+     *  fills these in by discovering installed @typecad/framework-* packages, so
+     *  KNOWN_TARGETS board entries do not hardcode a framework. Native targets
+     *  set them directly. */
+    frameworkPackage?: string;
+    framework?: string;
     buildTarget?: string;
     mcu?: string;
+    /** Framework-specific config (becomes frameworkData in cuttlefish.config.ts).
+     *  Carries framework-specific target/options data for the selected framework. */
+    frameworkData?: Record<string, unknown>;
 }
 export declare function registerKnownTarget(target: KnownTarget): void;
 export declare const KNOWN_TARGETS: ReadonlyArray<KnownTarget>;
@@ -24,4 +31,6 @@ export interface ScaffoldProjectResult {
     options: InitProjectOptions;
 }
 export declare function scaffoldProject(options: InitProjectOptions, outDir?: string): ScaffoldProjectResult;
-export declare function printInitNextSteps(options: InitProjectOptions, outDir: string): void;
+export declare function printInitNextSteps(options: InitProjectOptions, outDir: string, opts?: {
+    installed?: boolean;
+}): void;

package/dist/create/init-scaffold.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import fs from "node:fs";
 import chalk from "chalk";
-import { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateBoardForwardingFile, generateEslintConfig, } from "./init-templates.js";
+import { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateBoardForwardingFile, generateEslintConfig, } from "./init-templates.js";
 import { generateEslintRules } from "./eslint-rules-template.js";
 const _knownTargets = [
     {
@@ -17,8 +17,6 @@ const _knownTargets = [
         isNative: false,
         architecture: 'avr',
         boardPackage: '@typecad/board-arduino-uno',
-        frameworkPackage: '@typecad/framework-arduino',
-        framework: 'arduino',
         buildTarget: 'arduino:avr:uno',
         mcu: 'atmega328p',
     },
@@ -28,8 +26,6 @@ const _knownTargets = [
         isNative: false,
         architecture: 'esp32',
         boardPackage: '@typecad/board-esp32-devkit',
-        frameworkPackage: '@typecad/framework-arduino',
-        framework: 'arduino',
         buildTarget: 'esp32:esp32:esp32',
         mcu: 'esp32',
     },
@@ -39,8 +35,6 @@ const _knownTargets = [
         isNative: false,
         architecture: 'esp32s3',
         boardPackage: '@typecad/board-esp32s3',
-        frameworkPackage: '@typecad/framework-arduino',
-        framework: 'arduino',
         buildTarget: 'esp32:esp32:esp32s3',
         mcu: 'esp32s3',
     },
@@ -50,8 +44,6 @@ const _knownTargets = [
         isNative: false,
         architecture: 'esp32c3',
         boardPackage: '@typecad/board-esp32c3',
-        frameworkPackage: '@typecad/framework-arduino',
-        framework: 'arduino',
         buildTarget: 'esp32:esp32:esp32c3',
         mcu: 'esp32c3',
     },
@@ -61,11 +53,27 @@ const _knownTargets = [
         isNative: false,
         architecture: 'esp32c6',
         boardPackage: '@typecad/board-esp32c6',
-        frameworkPackage: '@typecad/framework-arduino',
-        framework: 'arduino',
         buildTarget: 'esp32:esp32:esp32c6',
         mcu: 'esp32c6',
     },
+    {
+        id: 'rp2040',
+        displayName: 'RP2040 (Pico)',
+        isNative: false,
+        architecture: 'rp2040',
+        boardPackage: '@typecad/board-rp2040',
+        buildTarget: 'rp2040:rp2040:rpipico',
+        mcu: 'rp2040',
+    },
+    {
+        id: 'rp2350',
+        displayName: 'RP2350 (Pico 2)',
+        isNative: false,
+        architecture: 'rp2350',
+        boardPackage: '@typecad/board-rp2350',
+        buildTarget: 'rp2040:rp2040:rpipico2',
+        mcu: 'rp2350',
+    },
 ];
 export function registerKnownTarget(target) {
     const existing = _knownTargets.findIndex(t => t.id === target.id);
@@ -128,23 +136,50 @@ export function scaffoldProject(options, outDir) {
         fs.writeFileSync(sketchPath, generateStarterSketch(options), 'utf-8');
         createdFiles.push(sketchPath);
     }
+    // Embedded projects get a starter hardware test (@typecad/expect / cuttlefish-test).
+    // Native projects have no serial/board path, so they get no test setup.
+    if (!options.isNative) {
+        const testsDir = path.join(resolvedOutDir, 'tests');
+        fs.mkdirSync(testsDir, { recursive: true });
+        const testPath = path.join(testsDir, '01-basics.test.ts');
+        fs.writeFileSync(testPath, generateStarterTest(options), 'utf-8');
+        createdFiles.push(testPath);
+        // Host-side simulation (@typecad/simulator + vitest). sim/ is kept separate
+        // from tests/ so `vitest run sim/` never loads the @typecad/expect no-op
+        // stubs, and `cuttlefish-test` (which globs tests/) never tries to flash a
+        // simulator file as firmware.
+        const simDir = path.join(resolvedOutDir, 'sim');
+        fs.mkdirSync(simDir, { recursive: true });
+        const simPath = path.join(simDir, 'main.test.ts');
+        fs.writeFileSync(simPath, generateStarterSim(options), 'utf-8');
+        createdFiles.push(simPath);
+    }
     return { createdFiles, outDir: resolvedOutDir, options };
 }
-export function printInitNextSteps(options, outDir) {
+export function printInitNextSteps(options, outDir, opts = {}) {
     const relativeDir = path.relative(process.cwd(), outDir) || '.';
     console.log();
     console.log(chalk.cyan(`⤳ Cuttlefish`));
     console.log();
     console.log(chalk.bold.white("Next steps:"));
     console.log(chalk.dim(`  cd ${relativeDir}`));
-    console.log(chalk.dim(`  npm install`));
+    // When create already installed dependencies, don't tell the user to do it again.
+    if (!opts.installed) {
+        console.log(chalk.dim(`  npm install`));
+    }
     console.log(`  ${chalk.cyan("npm run compile")}`);
     if (!options.isNative) {
         const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
         console.log();
+        console.log(chalk.bold.white("To simulate without hardware:"));
+        console.log(`  ${chalk.cyan("npm run simulate")}`);
+        console.log();
         console.log(chalk.bold.white("To upload to your board:"));
         console.log(`  ${chalk.cyan("npm run upload")}`);
         console.log();
-        console.log(chalk.dim(`Edit ${chalk.white("package.json")} to change the serial port from ${chalk.white(portHint)} to your port.`));
+        console.log(chalk.bold.white("To run hardware tests:"));
+        console.log(`  ${chalk.cyan("npm run test:hw")}`);
+        console.log();
+        console.log(chalk.dim(`Edit ${chalk.white("cuttlefish.config.ts")} to change the serial port from ${chalk.white(portHint)} to your port.`));
     }
 }

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

@@ -13,12 +13,16 @@ export interface InitProjectOptions {
     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;