feat: wokwi-cli init wizard

Author: urish

README.md

@@ -36,6 +36,20 @@ cd esp-idf-hello-world
 wokwi-cli .
 ```
 
+## Configuration Wizard
+
+To generate a `wokwi.toml` and a default `diagram.json` files for your project, run:
+
+```bash
+wokwi-cli init
+```
+
+This will ask you a few questions and will create the necessary files in the current directory. If you want to create the files in a different directory, pass the directory name as an argument:
+
+```bash
+wokwi-cli init my-project
+```
+
 ## Development
 
 Clone the repository, install the npm depenedencies, and then run the CLI:

package-lock.json

@@ -36,6 +36,7 @@
     "url": "https://github.com/wokwi/wokwi-cli"
   },
   "dependencies": {
+    "@clack/prompts": "^0.7.0",
     "@iarna/toml": "2.2.5",
     "arg": "^5.0.2",
     "chalk": "^5.3.0",
@@ -46,6 +47,7 @@
   "devDependencies": {
     "@types/ws": "^8.5.4",
     "@typescript-eslint/eslint-plugin": "^5.59.1",
+    "@yao-pkg/pkg": "^5.11.5",
     "esbuild": "^0.18.17",
     "eslint": "^8.39.0",
     "eslint-config-prettier": "^8.8.0",
@@ -55,7 +57,6 @@
     "eslint-plugin-promise": "^6.1.1",
     "husky": "^8.0.0",
     "lint-staged": "^13.2.2",
-    "@yao-pkg/pkg": "^5.11.5",
     "prettier": "^3.0.3",
     "rimraf": "^5.0.0",
     "tsx": "^4.6.1",

package.json

@@ -10,6 +10,7 @@ import { ExpectEngine } from './ExpectEngine.js';
 import { TestScenario } from './TestScenario.js';
 import { parseConfig } from './config.js';
 import { cliHelp } from './help.js';
+import { initProjectWizard } from './project/initProjectWizard.js';
 import { loadChips } from './loadChips.js';
 import { readVersion } from './readVersion.js';
 import { DelayCommand } from './scenario/DelayCommand.js';
@@ -84,6 +85,11 @@ async function main() {
     process.exit(0);
   }
 
+  if (args._[0] === 'init') {
+    await initProjectWizard(args._[1] ?? '.', { diagramFile });
+    process.exit(0);
+  }
+
   const token = process.env.WOKWI_CLI_TOKEN;
   if (token == null || token.length === 0) {
     console.error(

src/main.ts

@@ -0,0 +1,24 @@
+export const boards = [
+  // ESP32 DevKits
+  { title: 'ESP32 DevKit', board: 'board-esp32-devkit-c-v4', family: 'esp32' },
+  { title: 'ESP32-C3 DevKit', board: 'board-esp32-c3-devkitm-1', family: 'esp32' },
+  { title: 'ESP32-C6 DevKit', board: 'board-esp32-c6-devkitc-1', family: 'esp32' },
+  { title: 'ESP32-H2 DevKit', board: 'board-esp32-h2-devkitm-1', family: 'esp32' },
+  { title: 'ESP32-P4 (Preview)', board: 'board-esp32-p4-preview', family: 'esp32' },
+  { title: 'ESP32-S2 DevKit', board: 'board-esp32-s2-devkitm-1', family: 'esp32' },
+  { title: 'ESP32-S3 DevKit', board: 'board-esp32-s3-devkitc-1', family: 'esp32' },
+
+  // ESP32-based boards
+  { title: 'ESP32-C3 Rust DevKit', board: 'board-esp32-c3-rust-1', family: 'esp32' },
+  { title: 'ESP32-S3-BOX', board: 'board-esp32-s3-box', family: 'esp32' },
+  { title: 'ESP32-S3-BOX-3', board: 'board-esp32-s3-box-3', family: 'esp32' },
+  { title: 'M5Stack CoreS3', board: 'board-m5stack-core-s3', family: 'esp32' },
+
+  // RP2040-based boards
+  { title: 'Raspberry Pi Pico', board: 'wokwi-pi-pico', family: 'rp2' },
+  { title: 'Raspberry Pi Pico W', board: 'board-pi-pico-w', family: 'rp2' },
+
+  // STM32 boards
+  { title: 'STM32 Nucleo-64 C031C6', board: 'board-st-nucleo-c031c6', family: 'stm32' },
+  { title: 'STM32 Nucleo-64 L031K6', board: 'board-st-nucleo-l031k6', family: 'stm32' },
+];

src/project/boards.ts

@@ -0,0 +1,12 @@
+export function createDiagram(board: string) {
+  return {
+    version: 1,
+    author: 'Uri Shaked',
+    editor: 'wokwi',
+    parts: [{ type: board, id: 'esp' }],
+    connections: [
+      ['esp:TX', '$serialMonitor:RX', ''],
+      ['esp:RX', '$serialMonitor:TX', ''],
+    ],
+  };
+}

src/project/createDiagram.ts

@@ -0,0 +1,45 @@
+import { join } from 'path';
+import { readFileOrNull } from '../utils/files.js';
+import { type ProjectType } from './projectType.js';
+
+export interface FindFirmwarePathResult {
+  firmware?: string;
+  elf?: string;
+}
+
+export async function findFirmwarePath(
+  rootDir: string,
+  projectType: ProjectType | null,
+): Promise<FindFirmwarePathResult> {
+  const cmakeLists = await readFileOrNull(join(rootDir, 'CMakeLists.txt'));
+
+  switch (projectType) {
+    case 'esp-idf': {
+      const projectName = cmakeLists?.toString('utf-8').match(/\Wproject\(([^\s)]+)\)/i)?.[1];
+      return {
+        firmware: 'build/flasher_args.json',
+        elf: projectName && `build/${projectName}.elf`,
+      };
+    }
+
+    case 'pico-sdk': {
+      const projectName = cmakeLists?.toString('utf-8').match(/\Wadd_executable\(([^\s)]+)/i)?.[1];
+      return {
+        firmware: projectName && `build/${projectName}.uf2`,
+        elf: projectName && `build/${projectName}.elf`,
+      };
+    }
+
+    case 'platformio': {
+      const platformIni = await readFileOrNull(join(rootDir, 'platformio.ini'));
+      const firstEnv = platformIni?.toString('utf-8').match(/\[env:([^\s\]]+)\]/)?.[1];
+      return {
+        firmware: firstEnv && `.pio/build/${firstEnv}/firmware.bin`,
+        elf: firstEnv && `.pio/build/${firstEnv}/firmware.elf`,
+      };
+    }
+
+    default:
+      return {};
+  }
+}

src/project/findFirmwarePath.ts

@@ -0,0 +1,114 @@
+import { cancel, confirm, intro, isCancel, log, note, outro, select, text } from '@clack/prompts';
+import chalkTemplate from 'chalk-template';
+import { existsSync, writeFileSync } from 'fs';
+import path from 'path';
+import { boards } from './boards.js';
+import { createDiagram } from './createDiagram.js';
+import { findFirmwarePath } from './findFirmwarePath.js';
+import { detectProjectType } from './projectType.js';
+
+export async function initProjectWizard(rootDir: string, opts: { diagramFile?: string }) {
+  const configPath = path.join(rootDir, 'wokwi.toml');
+  const diagramFilePath = path.resolve(rootDir, opts.diagramFile ?? 'diagram.json');
+
+  intro(`Wokwi CLI - Project Initialization Wizard`);
+
+  note(`This wizard will help you configure your project for Wokwi.`, 'Welcome');
+
+  const existingFiles = [];
+  if (existsSync(configPath)) {
+    existingFiles.push('wokwi.toml');
+  }
+  if (existsSync(diagramFilePath)) {
+    existingFiles.push('diagram.json');
+  }
+
+  if (existingFiles.length > 0) {
+    const shouldContinue = await confirm({
+      message: `${existingFiles.join(
+        ' and ',
+      )} already exist in the project directory. This operation will overwrite them. Continue?`,
+      initialValue: false,
+    });
+    if (!shouldContinue || isCancel(shouldContinue)) {
+      cancel('Operation cancelled.');
+      process.exit(0);
+    }
+  }
+
+  const projectType = await detectProjectType(rootDir);
+  if (projectType != null) {
+    log.info(chalkTemplate`Detected project type: {greenBright ${projectType}}`);
+  }
+
+  const filteredBoards =
+    projectType === 'esp-idf'
+      ? boards.filter((board) => board.family === 'esp32')
+      : projectType === 'pico-sdk'
+      ? boards.filter((board) => board.family === 'rp2')
+      : boards;
+
+  const boardType = await select({
+    message: 'Select the board to simulate:',
+    options: filteredBoards.map((board) => ({ value: board.board, label: board.title })),
+    maxItems: 12,
+  });
+  if (isCancel(boardType)) {
+    cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  const defaultFirmwarePath = await findFirmwarePath(rootDir, projectType);
+  const firmwarePath = await text({
+    message: 'Enter the path to the firmware file (e.g. firmware.bin):',
+    initialValue: defaultFirmwarePath.firmware,
+    validate: (value) => {
+      if (!value) {
+        return 'Please enter a valid path';
+      }
+      return undefined;
+    },
+  });
+  if (isCancel(firmwarePath)) {
+    cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  let elfPath = firmwarePath;
+  if (!elfPath.endsWith('.elf')) {
+    const elfPathResponse = await text({
+      message: 'Enter the path to the ELF file (e.g. firmware.elf):',
+      initialValue: defaultFirmwarePath.elf,
+      validate: (value) => {
+        if (!value) {
+          return 'Please enter a valid path';
+        }
+        return undefined;
+      },
+    });
+    if (isCancel(elfPathResponse)) {
+      cancel('Operation cancelled.');
+      process.exit(0);
+    }
+
+    elfPath = elfPathResponse;
+  }
+
+  log.info(`Writing wokwi.toml...`);
+  writeFileSync(
+    configPath,
+    `# Wokwi Configuration File
+# Reference: https://docs.wokwi.com/vscode/project-config
+
+[wokwi]
+version = 1
+firmware = '${firmwarePath}'
+elf = '${elfPath}'
+`,
+  );
+
+  log.info(`Writing diagram.json...`);
+  writeFileSync(diagramFilePath, JSON.stringify(createDiagram(boardType as string), null, 2));
+
+  outro(`You're all set!`);
+}

src/project/initProjectWizard.ts

@@ -0,0 +1,42 @@
+import { join } from 'path';
+import { fileExists, readFileOrNull } from '../utils/files.js';
+
+export type ProjectType =
+  | 'none'
+  | 'rust'
+  | 'zephyr'
+  | 'platformio'
+  | 'esp-idf'
+  | 'pico-sdk'
+  | 'arduino';
+
+export async function detectProjectType(root: string): Promise<ProjectType | null> {
+  if (await fileExists(join(root, 'Cargo.toml'))) {
+    return 'rust';
+  }
+
+  if (await fileExists(join(root, 'west.yml'))) {
+    return 'zephyr';
+  }
+
+  if (await fileExists(join(root, 'platformio.ini'))) {
+    return 'platformio';
+  }
+
+  const cmakeLists = await readFileOrNull(join(root, 'CMakeLists.txt'));
+  if (cmakeLists) {
+    const cmakeListStr = Buffer.from(cmakeLists).toString();
+    if (cmakeListStr.includes('$ENV{IDF_PATH}')) {
+      return 'esp-idf';
+    }
+    if (cmakeListStr.includes('pico_sdk_init')) {
+      return 'pico-sdk';
+    }
+  }
+
+  if (await fileExists(join(root, '.vscode/arduino.json'))) {
+    return 'arduino';
+  }
+
+  return null;
+}

src/project/projectType.ts

@@ -0,0 +1,18 @@
+import { access, readFile } from 'fs/promises';
+
+export async function fileExists(path: string) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readFileOrNull(path: string) {
+  try {
+    return await readFile(path);
+  } catch {
+    return null;
+  }
+}