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

package/dist/create/{init-templates.js → templates.js}

@@ -1,20 +1,22 @@
 import { LINT_RULES } from '../ir/feature-registry.js';
+import { isBuiltinFramework } from './framework-catalog.js';
 export function generateProjectPackageJson(options) {
-    const { projectName, frameworkPackage, boardPackage } = options;
+    const { projectName, frameworkPackage } = 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.
+    // transitively (framework + board packages depend on it),
+    // but native targets have no board package, so HAL must be an explicit
+    // direct dependency here.
     const deps = {
         "@typecad/cuttlefish": "^1.0.0-alpha.3",
         "@typecad/hal": "^1.0.0-alpha.3",
-        [frameworkPackage]: "^1.0.0-alpha.3",
     };
-    if (boardPackage) {
-        deps[boardPackage] = "^1.0.0-alpha.3";
+    // Built-in frameworks (native) ship inside @typecad/cuttlefish — no
+    // separate dependency entry.
+    if (!isBuiltinFramework(frameworkPackage)) {
+        deps[frameworkPackage] = "^1.0.0-alpha.3";
     }
     const depsJson = Object.entries(deps)
         .map(([k, v]) => `    "${k}": "${v}"`)
@@ -28,19 +30,13 @@ export function generateProjectPackageJson(options) {
         '    "@typescript-eslint/parser": "^8.61.0"',
         '    "@typescript-eslint/eslint-plugin": "^8.61.0"',
     ];
-    // 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`.
+    // Developer-utility script shared by every target (native + embedded).
+    // Requires no 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.
     const devScripts = [
         '"dev": "cuttlefish build --watch"',
-        '"gen-decls": "cuttlefish gen-decls"',
-        '"gen-libdefs": "cuttlefish gen-libdefs"',
     ];
     if (options.isNative) {
         const devDepsJson = baseDevDeps.join(',\n');
@@ -100,10 +96,15 @@ ${devDepsJson}
 `;
 }
 export function generateProjectTsconfig(options) {
-    const paths = options.boardPackage
+    // The @typecad/board virtual import resolves for board AND MCU-only targets
+    // (the transpile writes .cuttlefish/board.ts re-exporting either). The
+    // @typecad/test-pins module is board data — MCU-only targets have none.
+    const hasBoard = !!options.board || !!options.soc;
+    const paths = (hasBoard || options.soc)
         ? `,
     "paths": {
-      "@typecad/board": ["./.cuttlefish/board.ts"]
+      "@typecad/board": ["./.cuttlefish/board.ts"]${hasBoard ? `,
+      "@typecad/test-pins": ["./.cuttlefish/test-pins.ts"]` : ''}
     }`
         : '';
     return `{
@@ -156,26 +157,59 @@ const config = {
 export default config;
 `;
     }
+    // The build target rides `board:` for board projects; only board-less
+    // projects (bare silicon / contract, whose target is a generated custom
+    // board) need the explicit frameworkData entry.
     const buildTarget = options.buildTarget;
-    const resolvedToolchain = options.toolchainType
-        ?? 'arduino-cli';
     let frameworkDataBlock = '';
-    if (buildTarget) {
-        frameworkDataBlock = `\n  // Framework data\n  frameworkData: {\n    buildTarget: '${buildTarget}',\n  },`;
+    if (buildTarget && buildTarget !== options.board) {
+        frameworkDataBlock = `\n  // Framework data — the generated custom board's name (no upstream board).\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`
+    const socLine = options.soc
+        ? `
+  // Zephyr SoC — bare silicon; the board module is generated from the
+  // curated soc descriptor (contract projects narrow it further).
+  soc: '${options.soc}',
+`
         : '';
-    const boardLine = options.boardPackage
-        ? `\n  // Board package — provides pin definitions and board constants\n  board: '${options.boardPackage}',`
+    const boardLine = options.board
+        ? `
+  // Zephyr board target — the project-local board module is generated
+  // from the framework's board data pack on first build.
+  board: '${options.board}',`
         : '';
     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  },` : '';
+    const portValue = options.port ?? portHint;
+    // zephyr.* section — probe (boards with a probe-method table) and/or
+    // customBoard (MCU-only targets: generate an out-of-tree board for the
+    // chip, named after frameworkData.buildTarget).
+    const zephyrFields = [];
+    if (options.zephyrCustomBoard) {
+        zephyrFields.push(`    // Generate an out-of-tree Zephyr board for this MCU under
+    // boards/typecad/ (no board package exists for this hardware). The
+    // board's name comes from frameworkData.buildTarget above.
+    customBoard: true,`);
+    }
+    if (options.probeMethod) {
+        const probeIds = (options.probeMethods ?? []).map((m) => m.id).join(', ');
+        zephyrFields.push(`    // How this board attaches a probe (picked at create time;
+    // the board also supports: ${probeIds || 'see the framework docs'}). Serves
+    // flashing AND debugging.
+    probe: '${options.probeMethod}',`);
+    }
+    const zephyrProbeBlock = zephyrFields.length > 0
+        ? `
+
+  // Zephyr-specific configuration.
+  zephyr: {
+${zephyrFields.join('\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  },`;
+    // provided by @typecad/expect). Defaults: baudRate 115200, timeout 30000,
+    // include tests/**/*.test.ts.
+    const testBaud = options.baudRate && options.baudRate !== 115200 ? `\n    baudRate: ${options.baudRate},` : '';
+    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: '${portValue}',${testBaud}\n  },`;
     return `// ---------------------------------------------------------------------------
 // cuttlefish.config.ts — Project configuration
 //
@@ -187,30 +221,23 @@ import type { CuttlefishConfig } from '@typecad/cuttlefish/api';
 const config: CuttlefishConfig = {
   // Entry point — the main TypeScript file to transpile
   entry: './src/main.ts',
-
-  // Target architecture
-  target: '${options.architecture}',${mcuLine}${boardLine}
-
+${socLine}${boardLine}
   // Framework package — controls code generation strategy
   framework: '${options.frameworkPackage}',${frameworkDataBlock}
 
-  // Output / build options
+  // Transpiled output (the Zephyr app lands in src/out)
   output: {
-    framework: '${options.framework}',
     outDir: './out',
-  },
-
-  // Toolchain configuration
-  toolchain: {
-    type: '${resolvedToolchain}',
-  },${baudLine}${testLine}
+  },${zephyrProbeBlock}${testLine}
 };
 
 export default config;
 `;
 }
 export function generateProjectEnvDts(options) {
-    if (!options.boardPackage) {
+    // The @typecad/board virtual module resolves for board AND MCU-only targets
+    // — the transpile's first build rewrites this placeholder either way.
+    if (!options.board && !options.soc) {
         return `// ---------------------------------------------------------------------------
 // cuttlefish-env.d.ts — Global type declarations
 //
@@ -248,34 +275,9 @@ declare global {
   type float = number;
   type double = number;
 
-  // console — declared here (not pulled from lib.dom) so this project does not
-  // need "dom" in tsconfig lib just to type console.log. Avoiding lib.dom also
-  // keeps DOM global type names (Node, Element, Event, ...) out of scope, so a
-  // user class named e.g. Node is not shadowed by the DOM global. The
-  // transpiler regenerates this file on build and may merge extra members
-  // (readLine/readCharacter) onto the Console interface.
-  interface Console {
-    log(...args: unknown[]): void;
-    info(...args: unknown[]): void;
-    debug(...args: unknown[]): void;
-    warn(...args: unknown[]): void;
-    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 {};
@@ -321,34 +323,9 @@ declare global {
   type float = number;
   type double = number;
 
-  // console — declared here (not pulled from lib.dom) so this project does not
-  // need "dom" in tsconfig lib just to type console.log. Avoiding lib.dom also
-  // keeps DOM global type names (Node, Element, Event, ...) out of scope, so a
-  // user class named e.g. Node is not shadowed by the DOM global. The
-  // transpiler regenerates this file on build and may merge extra members
-  // (readLine/readCharacter) onto the Console interface.
-  interface Console {
-    log(...args: unknown[]): void;
-    info(...args: unknown[]): void;
-    debug(...args: unknown[]): void;
-    warn(...args: unknown[]): void;
-    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' {
@@ -361,12 +338,13 @@ declare module '@typecad/board' {
 export {};
 `;
 }
-export function generateStarterSketch(options) {
+export function generateStarterProgram(options) {
     if (options.isNative) {
         return `// ---------------------------------------------------------------------------
 // Hello World — Native desktop application
 //
-// Compiles to a native executable via g++/clang++.
+// Compiles to a native executable via g++/clang++. There is no console.* here
+// — results are observable through the debugger or your own channels.
 // ---------------------------------------------------------------------------
 
 function fibonacci(n: number): number {
@@ -374,24 +352,58 @@ function fibonacci(n: number): number {
   return fibonacci(n - 1) + fibonacci(n - 2);
 }
 
-console.log("Hello from Cuttlefish!");
-console.log("Fibonacci(10) =", fibonacci(10));
+const fib10 = fibonacci(10);
 `;
     }
-    return `// ---------------------------------------------------------------------------
+    // MCU-only target: bare silicon has no board-level LED alias — blink a
+    // port pin from the MCU datasheet instead.
+    if (!options.board && options.starterPin) {
+        return `// ---------------------------------------------------------------------------
 // Blink — The classic "Hello World" of embedded
 //
-// Toggles the onboard LED every second using the recommended GPIO pattern.
+// MCU-only target (no board package): ${options.targetDisplayName}. Pins are
+// addressed by their datasheet port names — see the MCU package for the full
+// pinout and each pin's capabilities.
 // ---------------------------------------------------------------------------
 
-import { LED, delay } from '@typecad/board';
+import { GPIO, Time } from '@typecad/hal';
+import { ${options.starterPin} } from '@typecad/board';
 
-const led = LED.asOutput(false);
+const led = new GPIO(${options.starterPin}, GPIO.OUTPUT);
 
 while (true) {
   led.toggle();
-  delay(1000);
+  Time.sleep(1000);
 }
+`;
+    }
+    return `// ---------------------------------------------------------------------------
+// Starter — The skeleton every program grows from
+//
+// ${options.hasLed === false
+        ? `This board's devicetree declares no LED — wire up your board's I/O below.`
+        : `Toggles the onboard LED every second using the recommended GPIO pattern.`}
+// ---------------------------------------------------------------------------
+
+${options.hasLed === false
+        ? `import { Time } from '@typecad/hal';
+
+// This board exports no LED alias — add a peripheral here (GPIO on a header
+// pin, UART0/USB0 for serial output, ...) and drive it in the loop.
+while (true) {
+  Time.sleep(1000);
+}
+`
+        : `import { GPIO, Time } from '@typecad/hal';
+import { LED } from '@typecad/board';
+
+const led = new GPIO(LED, GPIO.OUTPUT);
+
+while (true) {
+  led.toggle();
+  Time.sleep(1000);
+}
+`}
 `;
 }
 export function generateStarterTest(_options) {
@@ -451,7 +463,7 @@ export function generateStarterSim(options) {
 // 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.
+// @typecad/simulator package). No board, serial port, or west build required.
 // The simulator mirrors the pins/peripherals of your ${options.targetDisplayName}
 // (${boardType}); you inject fake inputs and assert on the outputs in Node.
 //
@@ -536,14 +548,6 @@ describe("Button + LED (simulator)", () => {
 });
 `;
 }
-export function generateBoardForwardingFile(boardPackage) {
-    return `// ---------------------------------------------------------------------------
-// .cuttlefish/board.ts — Dynamically generated forwarding board package
-// ---------------------------------------------------------------------------
-
-export * from '${boardPackage}';
-`;
-}
 export function generateGitignore(_options) {
     return `node_modules/
 out/
@@ -557,11 +561,26 @@ dist/
 .cuttlefish/eslint-transpiler-rules.mjs
 `;
 }
+export function generateEditorconfig(_options) {
+    return `# Auto-generated by 'cuttlefish create'. Edit to customise your build.
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{ts,js,mjs,cjs,json,css,ui,md,yml}]
+indent_style = space
+indent_size = 2
+`;
+}
 export function generateEslintConfig(_options) {
     // `no-restricted-syntax` selectors are generated from LINT_RULES
     // (packages/cuttlefish/src/ir/feature-registry.ts), the single source of
-    // truth shared with build-time prescan diagnostics. See SUPPORT_MATRIX for
-    // the per-pattern ❌/🚫 rationale. Do not hand-edit the array below.
+    // truth shared with build-time prescan diagnostics. Do not hand-edit the
+    // array below.
     const transpilerRulesJson = JSON.stringify(LINT_RULES.map(({ selector, message }) => ({ selector, message })), null, 2).replace(/\n/g, "\n  ");
     return `import tsparser from "@typescript-eslint/parser";
 import tseslint from "@typescript-eslint/eslint-plugin";

package/dist/create/wizard.d.ts

@@ -0,0 +1,19 @@
+import type { CreateProjectOptions } from "./templates.js";
+/**
+ * Attached serial ports for the wizard's port question — dependency-free
+ * (the wizard runs before any project deps exist, and cuttlefish itself
+ * carries no native serialport binding). Windows asks the .NET SerialPort
+ * class via PowerShell; macOS/Linux scan /dev for USB CDC/bridge nodes.
+ * Returns [] when enumeration fails — the question then falls back to a
+ * free-text prompt with the platform hint as default.
+ */
+export declare function detectSerialPorts(): string[];
+export declare function runCreateWizard(partialOptions?: {
+    probe?: string;
+    port?: string;
+    projectName?: string;
+    board?: string;
+    framework?: string;
+    baud?: number;
+    noStarter?: boolean;
+}): Promise<CreateProjectOptions | null>;