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

package/dist/create/init-templates.js

@@ -1,12 +1,20 @@
 import { LINT_RULES } from '../ir/feature-registry.js';
 export function generateProjectPackageJson(options) {
     const { projectName, frameworkPackage, boardPackage } = options;
+    // @typecad/hal is needed by every build, not just embedded ones: the
+    // transpiler unconditionally warms the HAL source modules (loadHALModules in
+    // transpile.ts), and resolveHALSourceDir() throws "Could not resolve
+    // @typecad/hal/src/" if the package is absent. Embedded targets pull it in
+    // transitively (@typecad/framework-arduino + board packages depend on it),
+    // but native targets have no board package and @typecad/framework-native does
+    // not declare it, so HAL must be an explicit direct dependency here.
     const deps = {
-        "@typecad/cuttlefish": "^0.1.0-alpha.1",
-        [frameworkPackage]: "^0.1.0-alpha.1",
+        "@typecad/cuttlefish": "^1.0.0-alpha.3",
+        "@typecad/hal": "^1.0.0-alpha.3",
+        [frameworkPackage]: "^1.0.0-alpha.3",
     };
     if (boardPackage) {
-        deps[boardPackage] = "^0.1.0-alpha.1";
+        deps[boardPackage] = "^1.0.0-alpha.3";
     }
     const depsJson = Object.entries(deps)
         .map(([k, v]) => `    "${k}": "${v}"`)
@@ -15,12 +23,27 @@ export function generateProjectPackageJson(options) {
     // eslint-transpiler-rules plugin (which is plain JS, no dep). Without these
     // devDependencies `npm run lint` fails to resolve the parser/plugin in a
     // freshly created project. Versions mirror the repo demo's package.json.
-    const devDepsJson = [
+    const baseDevDeps = [
         '    "eslint": "^10.4.1"',
         '    "@typescript-eslint/parser": "^8.61.0"',
         '    "@typescript-eslint/eslint-plugin": "^8.61.0"',
-    ].join(',\n');
+    ];
+    // Developer-utility scripts shared by every target (native + embedded).
+    // None require hardware or extra dependencies:
+    //   dev        — auto-retranspile on save (transpile-only; append --compile
+    //                to also compile on each change). The fast "does it
+    //                typecheck" feedback loop.
+    //   gen-decls  — generate TypeScript .d.ts from C++ headers. File-argument:
+    //                `npm run gen-decls -- lib/foo.h` or `-- --all lib/`.
+    //   gen-libdefs — generate library-definition stubs from a TS file's imports.
+    //                File-argument: `npm run gen-libdefs -- src/main.ts`.
+    const devScripts = [
+        '"dev": "cuttlefish build --watch"',
+        '"gen-decls": "cuttlefish gen-decls"',
+        '"gen-libdefs": "cuttlefish gen-libdefs"',
+    ];
     if (options.isNative) {
+        const devDepsJson = baseDevDeps.join(',\n');
         return `{
   "name": "${projectName}",
   "version": "1.0.0",
@@ -28,7 +51,8 @@ export function generateProjectPackageJson(options) {
   "scripts": {
     "build": "cuttlefish build",
     "compile": "cuttlefish build --compile",
-    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/"
+    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/",
+    ${devScripts.join(',\n    ')}
   },
   "dependencies": {
 ${depsJson}
@@ -39,6 +63,19 @@ ${devDepsJson}
 }
 `;
     }
+    // Embedded projects get two host-side testing tiers:
+    //  - @typecad/expect: hardware tests run on the board via cuttlefish-test
+    //    (`npm run test:hw`), scoped to tests/**/*.test.ts.
+    //  - @typecad/simulator + vitest: simulate the board in Node (`npm run
+    //    simulate`), scoped to sim/**/*.test.ts so vitest never collides with the
+    //    @typecad/expect no-op stubs under tests/.
+    // Versions mirror the workspace's published releases / root devDeps.
+    const devDepsJson = [
+        ...baseDevDeps,
+        '    "@typecad/expect": "^1.0.0-alpha.3"',
+        '    "@typecad/simulator": "^1.0.0-alpha.3"',
+        '    "vitest": "^4.0.18"',
+    ].join(',\n');
     return `{
   "name": "${projectName}",
   "version": "1.0.0",
@@ -48,7 +85,10 @@ ${devDepsJson}
     "compile": "cuttlefish build --compile",
     "upload": "cuttlefish build --compile --upload",
     "monitor": "cuttlefish build --compile --upload --monitor",
-    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/"
+    "test:hw": "npm exec -- cuttlefish-test",
+    "simulate": "vitest run sim/",
+    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/",
+    ${devScripts.join(',\n    ')}
   },
   "dependencies": {
 ${depsJson}
@@ -85,9 +125,10 @@ export function generateProjectTsconfig(options) {
     "noEmit": true,
     "resolveJsonModule": true,
     "allowArbitraryExtensions": true,
+    "allowImportingTsExtensions": true,
     "rootDirs": ["src", "types"]${paths}
   },
-  "include": ["src/**/*.ts", "types/**/*.ts", "cuttlefish.config.ts"${options.boardPackage ? ', ".cuttlefish/cuttlefish-env.d.ts"' : ''}]
+  "include": ["src/**/*.ts", "types/**/*.ts", "cuttlefish.config.ts", ".cuttlefish/cuttlefish-env.d.ts"${options.isNative ? '' : ', "sim/**/*.ts"'}]
 }
 `;
 }
@@ -117,8 +158,12 @@ export default config;
 `;
     }
     const buildTarget = options.buildTarget;
-    const resolvedToolchain = options.toolchainType ?? 'arduino-cli';
-    const buildTargetLine = buildTarget ? `\n  // Framework data\n  frameworkData: {\n    buildTarget: '${buildTarget}',\n  },` : '';
+    const resolvedToolchain = options.toolchainType
+        ?? 'arduino-cli';
+    let frameworkDataBlock = '';
+    if (buildTarget) {
+        frameworkDataBlock = `\n  // Framework data\n  frameworkData: {\n    buildTarget: '${buildTarget}',\n  },`;
+    }
     const mcuLine = options.mcu
         ? `\n  // MCU package — provides silicon-level pin definitions\n  mcu: '${options.mcu.startsWith('@') ? options.mcu : `@typecad/mcu-${options.mcu}`}',\n`
         : '';
@@ -127,6 +172,11 @@ export default config;
         : '';
     const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
     const baudLine = options.baudRate ? `\n\n  // Console polyfill configuration\n  console: {\n    baudRate: ${options.baudRate},\n    // Serial port for upload/monitor. Override with --port on the CLI.\n    port: '${portHint}',\n  },` : '';
+    // Hardware test runner configuration — used by \`npm run test:hw\` (cuttlefish-test,
+    // provided by @typecad/expect). It transpiles each tests/**/*.test.ts file,
+    // flashes it to the board, and evaluates the assertions over serial.
+    const resolvedBaud = options.baudRate ?? 115200;
+    const testLine = `\n\n  // Hardware test runner (@typecad/expect / \`npm run test:hw\`)\n  test: {\n    // Serial port for the test board. Override with --port on the CLI or the\n    // CUTTLEFISH_PORT env var (e.g. CUTTLEFISH_PORT=/dev/ttyUSB0 npm run test:hw).\n    port: '${portHint}',\n    baudRate: ${resolvedBaud},\n    timeout: 30000,\n    include: ['tests/**/*.test.ts'],\n  },`;
     return `// ---------------------------------------------------------------------------
 // cuttlefish.config.ts — Project configuration
 //
@@ -143,7 +193,7 @@ const config: CuttlefishConfig = {
   target: '${options.architecture}',${mcuLine}${boardLine}
 
   // Framework package — controls code generation strategy
-  framework: '${options.frameworkPackage}',${buildTargetLine}
+  framework: '${options.frameworkPackage}',${frameworkDataBlock}
 
   // Output / build options
   output: {
@@ -155,7 +205,7 @@ const config: CuttlefishConfig = {
   // Toolchain configuration
   toolchain: {
     type: '${resolvedToolchain}',
-  },${baudLine}
+  },${baudLine}${testLine}
 };
 
 export default config;
@@ -173,6 +223,22 @@ declare global {
   type Owned<T = unknown> = T;
   type Shared<T = unknown> = T;
   type Mutable<T = unknown> = T;
+  // SafeVariable: SEU-resistant storage. The transpiler lowers SafeVariable<number>
+  // to a C++ template with inverted-redundancy storage. Declared as an interface
+  // (not a type alias) so the TS type checker recognizes method calls.
+  // Arithmetic T only (integral or floating-point); string is rejected by a
+  // static_assert in the emitted C++ template.
+  interface SafeVariable<T = number> { set(value: T): void; get(): T; valid(): boolean; hasFault(): boolean; }
+  // SafeInt: chainable bounds-checked signed-integer arithmetic. The transpiler
+  // lowers SafeInt<number> to SafeInt<int32_t> (a C++ template with sticky-fault
+  // overflow detection). Signed integer T only — unsigned/bool/float/string are
+  // rejected by a static_assert in the emitted C++ template.
+  interface SafeInt<T = number> {
+    add(delta: T): SafeInt<T>; sub(delta: T): SafeInt<T>;
+    mul(factor: T): SafeInt<T>; divide(d: T): SafeInt<T>; mod(d: T): SafeInt<T>;
+    negate(): SafeInt<T>; absValue(): SafeInt<T>;
+    get(): T; hasFault(): boolean; valid(): boolean; reset(newValue: T): void;
+  }
 
   type uint8_t = number;
   type int8_t = number;
@@ -198,6 +264,20 @@ declare global {
     error(...args: unknown[]): void;
   }
   const console: Console;
+
+  // Convenience helper for volatile variables in TypeCAD programs.
+  // The transpiler detects calls to volatile() and emits the C++ volatile qualifier.
+  declare function volatile<T>(value: T): T;
+
+  // JS-style timers (declared here so a project does not need "dom" in tsconfig
+  // lib to type setInterval/setTimeout). The transpiler rewrites these to
+  // __tc_setInterval/__tc_setTimeout and emits the timer_methods polyfill when
+  // used. Note: Timing.setInterval/setTimeout (from @typecad/hal) is the
+  // preferred single entry point and is typed via the @typecad/board import.
+  declare function setInterval(handler: () => void, timeout?: number): number;
+  declare function setTimeout(handler: () => void, timeout?: number): number;
+  declare function clearInterval(id: number): void;
+  declare function clearTimeout(id: number): void;
 }
 
 export {};
@@ -216,6 +296,22 @@ declare global {
   type Owned<T = unknown> = T;
   type Shared<T = unknown> = T;
   type Mutable<T = unknown> = T;
+  // SafeVariable: SEU-resistant storage. The transpiler lowers SafeVariable<number>
+  // to a C++ template with inverted-redundancy storage. Declared as an interface
+  // (not a type alias) so the TS type checker recognizes method calls.
+  // Arithmetic T only (integral or floating-point); string is rejected by a
+  // static_assert in the emitted C++ template.
+  interface SafeVariable<T = number> { set(value: T): void; get(): T; valid(): boolean; hasFault(): boolean; }
+  // SafeInt: chainable bounds-checked signed-integer arithmetic. The transpiler
+  // lowers SafeInt<number> to SafeInt<int32_t> (a C++ template with sticky-fault
+  // overflow detection). Signed integer T only — unsigned/bool/float/string are
+  // rejected by a static_assert in the emitted C++ template.
+  interface SafeInt<T = number> {
+    add(delta: T): SafeInt<T>; sub(delta: T): SafeInt<T>;
+    mul(factor: T): SafeInt<T>; divide(d: T): SafeInt<T>; mod(d: T): SafeInt<T>;
+    negate(): SafeInt<T>; absValue(): SafeInt<T>;
+    get(): T; hasFault(): boolean; valid(): boolean; reset(newValue: T): void;
+  }
 
   type uint8_t = number;
   type int8_t = number;
@@ -241,6 +337,20 @@ declare global {
     error(...args: unknown[]): void;
   }
   const console: Console;
+
+  // Convenience helper for volatile variables in TypeCAD programs.
+  // The transpiler detects calls to volatile() and emits the C++ volatile qualifier.
+  declare function volatile<T>(value: T): T;
+
+  // JS-style timers (declared here so a project does not need "dom" in tsconfig
+  // lib to type setInterval/setTimeout). The transpiler rewrites these to
+  // __tc_setInterval/__tc_setTimeout and emits the timer_methods polyfill when
+  // used. Note: Timing.setInterval/setTimeout (from @typecad/hal) is the
+  // preferred single entry point and is typed via the @typecad/board import.
+  declare function setInterval(handler: () => void, timeout?: number): number;
+  declare function setTimeout(handler: () => void, timeout?: number): number;
+  declare function clearInterval(id: number): void;
+  declare function clearTimeout(id: number): void;
 }
 
 declare module '@typecad/board' {
@@ -286,6 +396,148 @@ while (true) {
 }
 `;
 }
+export function generateStarterTest(_options) {
+    return `// ---------------------------------------------------------------------------
+// Hardware test — Basics
+//
+// Runs on the board via \`npm run test:hw\` (cuttlefish-test). Each test file is
+// transpiled, flashed to the board, and its assertions are evaluated on the host
+// over serial. Change the serial port in cuttlefish.config.ts (the \`test.port\`
+// field) or override it with the CUTTLEFISH_PORT env var.
+//
+// API: describe(...).it(...).expect(value).<matcher>() chains. Import pin
+// objects from '@typecad/board' to assert on real hardware I/O. Every file ends
+// with done().
+// ---------------------------------------------------------------------------
+
+import { describe, done } from '@typecad/expect';
+
+describe("Basics")
+  .it("adds two numbers")
+  .expect(
+    (() => {
+      const a = 1;
+      let b = 2;
+      return a + b;
+    })
+  ).toBe(3)
+  .it("multiplies two numbers")
+  .expect(
+    (() => {
+      let a = 3;
+      let b = 4;
+      return a * b;
+    })
+  ).toBe(12)
+  .it("reads an array element")
+  .expect(
+    (() => {
+      const data = new Uint8Array([0xAA, 0x10, 0x20]);
+      return data[1];
+    })
+  ).toBe(0x10)
+  .it("clamps a value to a range")
+  .expect(
+    (() => {
+      const value = 2000;
+      return Math.max(0, Math.min(1023, value));
+    })
+  ).toBe(1023);
+
+done();
+`;
+}
+export function generateStarterSim(options) {
+    const boardType = options.targetId;
+    return `// ---------------------------------------------------------------------------
+// Hardware simulation — Button + LED
+//
+// Runs entirely on your computer with \`npm run simulate\` (vitest + the
+// @typecad/simulator package). No board, serial port, or arduino-cli required.
+// The simulator mirrors the pins/peripherals of your ${options.targetDisplayName}
+// (${boardType}); you inject fake inputs and assert on the outputs in Node.
+//
+// This is the fast tier — iterate on logic here, then confirm on real hardware
+// with \`npm run test:hw\` (which flashes tests/ to the board).
+// ---------------------------------------------------------------------------
+
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  createSimBoard,
+  type SimBoard,
+  type SimDigitalPin,
+} from "@typecad/simulator";
+
+// ===========================================================================
+// FIRMWARE LOGIC
+// ---------------------------------------------------------------------------
+// Factor your firmware into a function that takes the simulated pins as
+// arguments. In a real project this same logic runs on the board against real
+// pins — here it runs against the sim board so you can test it without hardware.
+// ===========================================================================
+
+/**
+ * Reads a button and reflects its state on an LED.
+ *
+ * To use your own logic: replace the body of this function with whatever your
+ * firmware does (read a sensor, drive a motor, print to serial, ...). As long
+ * as it only touches pins you pass in, the simulator can exercise it.
+ */
+function reflectButtonOnLed(button: SimDigitalPin, led: SimDigitalPin): void {
+  // The button pin is pulled HIGH (1) at rest and reads LOW (0) when pressed.
+  if (button.isLow()) {
+    led.high();
+  } else {
+    led.low();
+  }
+}
+
+// ===========================================================================
+// TEST BENCH
+// ---------------------------------------------------------------------------
+// \`createSimBoard\` builds an in-memory version of your board. The pin numbers
+// below match the physical pinout. Add the pins/peripherals your firmware uses:
+// board.digital(n), board.analog(n), board.pwm(n), board.serial(n),
+// board.i2c(n), board.spi(n), board.interrupt(n).
+// ===========================================================================
+
+function setupSim(): { board: SimBoard; button: SimDigitalPin; led: SimDigitalPin } {
+  // boardType mirrors the target chosen with \`cuttlefish create\`.
+  const board = createSimBoard({ boardType: "${boardType}" });
+
+  const button = board.digital(2).asInputPullUp();  // button on pin 2 (INPUT_PULLUP)
+  const led = board.digital(13).asOutput(false);    // LED on pin 13
+
+  return { board, button, led };
+}
+
+describe("Button + LED (simulator)", () => {
+  beforeEach(() => {
+    // A fresh board per test keeps state isolated. For a long-running sim you
+    // can call board.reset() between cycles instead.
+  });
+
+  it("keeps the LED off while the button is released", () => {
+    const { button, led } = setupSim();
+
+    // Button at rest: INPUT_PULLUP reads HIGH.
+    reflectButtonOnLed(button, led);
+
+    expect(led.getBitValue()).toBe(0);
+  });
+
+  it("turns the LED on while the button is pressed", () => {
+    const { button, led } = setupSim();
+
+    // Simulate a press: drive the button pin LOW.
+    button.injectValue(0);
+    reflectButtonOnLed(button, led);
+
+    expect(led.getBitValue()).toBe(1);
+  });
+});
+`;
+}
 export function generateBoardForwardingFile(boardPackage) {
     return `// ---------------------------------------------------------------------------
 // .cuttlefish/board.ts — Dynamically generated forwarding board package
@@ -328,11 +580,13 @@ export default [
     files: ["src/**/*.ts"],
     languageOptions: {
       parser: tsparser,
-      parserOptions: {
-        // Type-aware parsing so @typescript-eslint/no-explicit-any resolves
-        // imported bindings to their real types instead of defaulting to any.
-        project: "./tsconfig.json",
-      },
+      // NOTE: do NOT set parserOptions.project here. None of the rules below
+      // (no-restricted-syntax, the cuttlefish/* AST rules, no-explicit-any,
+      // no-eval, ...) consume type information, so enabling type-aware linting
+      // only forces ESLint to build a full TS type-program per file — ~3.4s of
+      // pure overhead on small projects with zero change to what is detected.
+      // If a future rule needs types, scope project to that rule only via
+      // parserOptions on a dedicated config block, not globally.
     },
     plugins: {
       "@typescript-eslint": tseslint,

package/dist/create/init-wizard.js

@@ -2,6 +2,7 @@ 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.";
@@ -84,34 +85,43 @@ export async function runInitWizard(partialOptions) {
             targetId = await promptSelect(rl, "Target", targetOptions);
         }
         const target = KNOWN_TARGETS.find((t) => t.id === targetId);
-        // 3. Framework (only for embedded targets)
+        // 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;
-        if (!target.isNative) {
-            const frameworkOptions = [
-                { label: "Arduino (digitalWrite, Wire, SPI)", value: 'arduino', pkg: '@typecad/framework-arduino' },
-            ];
-            if (target.architecture === 'avr') {
-                frameworkOptions.push({ label: "Bare-metal AVR (PORTB, etc.)", value: 'avr', pkg: '@typecad/framework-avr' });
-            }
-            if (partialOptions?.framework) {
-                const match = frameworkOptions.find(f => f.value === partialOptions.framework);
-                framework = match?.value ?? partialOptions.framework;
-                frameworkPackage = match?.pkg ?? `@typecad/framework-${partialOptions.framework}`;
-                console.log(`${chalk.cyan("?")} Framework: ${chalk.white(framework)}`);
-            }
-            else if (frameworkOptions.length === 1) {
-                framework = frameworkOptions[0].value;
-                frameworkPackage = frameworkOptions[0].pkg;
-                console.log(`${chalk.cyan("?")} Framework: ${chalk.white(frameworkOptions[0].label)}`);
-            }
-            else {
-                const selected = await promptSelect(rl, "Framework", frameworkOptions.map(f => ({ label: f.label, value: f.value })));
-                const match = frameworkOptions.find(f => f.value === selected);
-                framework = match.value;
-                frameworkPackage = match.pkg;
+        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) {
@@ -148,12 +158,16 @@ export async function runInitWizard(partialOptions) {
             isNative: target.isNative,
             architecture: target.architecture,
             boardPackage: target.boardPackage,
-            frameworkPackage,
-            framework,
-            buildTarget: target.buildTarget,
+            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) {

package/dist/create/install-deps.d.ts

@@ -0,0 +1,32 @@
+import { type PackageManager } from "./framework-catalog.js";
+export interface ProjectInstallResult {
+    pm: PackageManager;
+}
+interface InstallCommand {
+    bin: PackageManager;
+    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 __setProjectInstallRunnerForTest(runner: InstallRunner | undefined): void;
+/**
+ * Run `<pm> install` in `projectDir`. Throws on launch failure or non-zero exit
+ * so the create command can catch it and fall back to instructing the user to
+ * run the install manually (the scaffold itself already succeeded).
+ */
+export declare function installProjectDependencies(opts: {
+    projectDir: string;
+    /** Where to detect the user's preferred package manager. Defaults to cwd. */
+    cwd?: string;
+}): ProjectInstallResult;
+export {};

package/dist/create/install-deps.js

@@ -0,0 +1,46 @@
+// Installs all dependencies in a freshly scaffolded project directory, as the
+// final step of `cuttlefish create` so the new project is ready to build with
+// no separate `npm install` step. The package manager is detected from the
+// INVOKING directory (process.cwd()) — a pnpm/yarn user gets their tool of
+// choice even though the new project has no lockfile yet.
+import { spawnSync } from "node:child_process";
+import { detectPackageManager } from "./framework-catalog.js";
+let testRunner;
+/**
+ * FOR TESTS ONLY. Replaces the real spawn-based installer with `runner`.
+ * Pass `undefined` to restore the real executor.
+ */
+export function __setProjectInstallRunnerForTest(runner) {
+    testRunner = runner;
+}
+function runRealInstall(cmd) {
+    // stdio: "inherit" streams the package manager's own output to the terminal
+    // (install progress, deprecation warnings, etc.).
+    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 };
+}
+/**
+ * Run `<pm> install` in `projectDir`. Throws on launch failure or non-zero exit
+ * so the create command can catch it and fall back to instructing the user to
+ * run the install manually (the scaffold itself already succeeded).
+ */
+export function installProjectDependencies(opts) {
+    const pm = detectPackageManager(opts.cwd ?? process.cwd());
+    const cmd = { bin: pm, args: ["install"], cwd: opts.projectDir };
+    const run = testRunner ?? runRealInstall;
+    const result = run(cmd);
+    if (result.launchError) {
+        throw new Error(`Failed to run '${pm}': ${result.launchError}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`'${pm} install' exited with code ${result.status}.`);
+    }
+    return { pm };
+}