Separate to multiple packages wokwi-client-js and wokwi-cli

.github/workflows/release.yml

@@ -27,10 +27,10 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y binfmt-support qemu-user-static
       - name: 'Build'
-        run: pnpm run package
+        run: pnpm run build && pnpm --filter wokwi-cli run package
       - name: Upload Release
         uses: ncipollo/release-action@v1
         with:
-          artifacts: 'dist/bin/wokwi-cli-*,dist/bin/version.json'
+          artifacts: 'packages/wokwi-cli/dist/bin/wokwi-cli-*,packages/wokwi-cli/dist/bin/version.json'
           token: ${{ secrets.GITHUB_TOKEN }}
           generateReleaseNotes: true

.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: Tests
 
 on:
   push:
-    branches: [main]
   pull_request:
     branches: [main]
+  workflow_dispatch:
 
 jobs:
   test:
@@ -20,5 +20,17 @@ jobs:
           cache: 'pnpm'
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
-      - name: Run tests
-        run: pnpm test
+      - name: Build packages
+        run: pnpm run build
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps
+      - name: Format check
+        run: pnpm run format:check
+      - name: Run vitest tests
+        run: pnpm run test:vitest
+      - name: Run Playwright embed tests
+        run: pnpm run test:embed:playwright
+      - name: Run CLI integration tests
+        run: pnpm run test:cli:integration
+        env:
+          WOKWI_CLI_TOKEN: ${{ secrets.WOKWI_CLI_TOKEN }}

.gitignore

@@ -4,3 +4,7 @@ wokwi.toml
 *.bin
 diagram.json
 screenshot.png
+playwright-report/
+test-results/
+test-project/
+wokwi-part-tests/

.prettierignore

@@ -0,0 +1,27 @@
+# Ignore node_modules
+node_modules/
+
+# Ignore build outputs
+dist/
+build/
+
+# Ignore logs
+*.log
+
+# Ignore package-lock.json if present
+package-lock.json
+
+# Ignore Arduino-specific files
+*.hex
+*.elf
+*.bin
+
+# Ignore OS-specific files
+.DS_Store
+Thumbs.db
+
+# repo specific ignores
+playwright-report/
+test-results/
+test-project/
+wokwi-part-tests/

DEVELOPMENT.md

@@ -0,0 +1,113 @@
+# Development
+
+This document describes how to set up a development environment for the Wokwi CLI and the Wokwi JS client.
+
+## Getting started
+
+Prerequisites:
+- Node.js (https://nodejs.org/) (version 20 or higher)
+- Git
+- PNPM (https://pnpm.io)
+
+We use PNPM workspaces to manage multiple packages in this repository. Install PNPM globally following the official instructions: https://pnpm.io/installation.
+
+## Setting up the repository
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/wokwi/wokwi-cli
+cd wokwi-cli
+pnpm install
+```
+
+We use Playwright for end-to-end testing. Install the required browsers with:
+
+```bash
+pnpm exec playwright install
+```
+
+## Packages
+
+The repository contains two main packages:
+- `wokwi-cli`: The command-line interface for Wokwi.
+- `wokwi-js`: The JavaScript client library used to interact with Wokwi from a browser iframe.
+
+When you run `pnpm` commands from the repository root, the monorepo configuration determines which packages the command runs in. For example, `pnpm build` runs the build across packages, while `pnpm lint` runs `eslint .` for the whole repository.
+
+If you want to build a single package, use the `--filter` flag. For example, to build only the `wokwi-cli` package:
+
+```bash
+pnpm --filter wokwi-cli build
+```
+
+Or change into the package directory and run the command there:
+
+```bash
+cd packages/wokwi-cli
+pnpm build
+```
+
+## Running the CLI in development mode
+
+Build the packages first:
+
+```bash
+pnpm build
+```
+
+Then run the CLI from the `wokwi-cli` package directory:
+
+```bash
+cd packages/wokwi-cli
+pnpm cli [arguments]
+
+# Example: show the help screen
+pnpm cli -h
+```
+
+Example output:
+
+```bash
+Wokwi CLI v0-development (f33d9d579b0a)
+
+  USAGE
+
+      $ wokwi-cli [options] [path/to/project]
+
+  OPTIONS
+      --help, -h                  Shows this help message and exit
+...
+```
+
+## Running tests locally
+
+Before running tests, make sure you have built the packages and installed Playwright browsers:
+
+```bash
+pnpm build
+pnpm exec playwright install
+```
+
+We have several types of tests:
+- Unit tests (Vitest)
+- End-to-end tests (Playwright)
+- Integration tests that run the CLI against real Wokwi projects
+
+To run all tests:
+
+```bash
+pnpm test
+```
+
+To run tests separately, inspect the `scripts` section in the root `package.json`.
+
+## Automatic tests (CI)
+
+The repository uses GitHub Actions to run tests on every push and pull request. The workflow files live in `.github/workflows/` and contain steps to set up the environment, install dependencies, build packages, and run tests.
+
+If you fork the repository, you must enable GitHub Actions for your fork and add the `WOKWI_CLI_TOKEN` secret.
+
+Set the `WOKWI_CLI_TOKEN` secret in your fork under `Settings` > `Secrets and variables` > `Actions` > `New repository secret`.
+
+Instructions for obtaining the `WOKWI_CLI_TOKEN` are in the `README.md` (see the Usage section).

README.md

@@ -74,20 +74,7 @@ To configure your AI agent to use the MCP server, add the following to your agen
 
 ## Development
 
-Clone the repository, install the npm depenedencies, and then run the CLI:
-
-```bash
-git clone https://github.com/wokwi/wokwi-cli
-cd wokwi-cli
-npm install
-npm start
-```
-
-To pass command line arguments to the cli, use `npm start -- [arguments]`. For example, to see the help screen, run:
-
-```
-npm start -- -h
-```
+All information about developing the Wokwi CLI can be found in [DEVELOPMENT.md](DEVELOPMENT.md).
 
 ## License
 

eslint.config.ts

@@ -1,6 +1,5 @@
 import { defineConfig } from 'eslint/config';
 import eslint from '@eslint/js';
-import eslintConfigPrettier from 'eslint-config-prettier';
 import tseslint from 'typescript-eslint';
 
 export default defineConfig(
@@ -18,6 +17,8 @@ export default defineConfig(
       '**/.git/**',
       '**/coverage/**',
       '**/*.min.js',
+      '**/playwright-report/**',
+      '**/test-results/**',
     ],
   },
 
@@ -64,7 +65,4 @@ export default defineConfig(
       'no-undef': 'off',
     },
   },
-
-  // Prettier config (must be last to override conflicting rules)
-  eslintConfigPrettier,
 );

package.json

@@ -9,7 +9,14 @@
     "clean": "pnpm -r run clean",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "test": "npm run lint && vitest --run",
+    "format": "prettier --write packages scripts test",
+    "format:check": "prettier --check packages scripts test",
+    "test": "pnpm run test:vitest && pnpm run test:embed:playwright && pnpm run test:cli:integration",
+    "test:vitest": "pnpm run lint && vitest --run",
+    "test:embed:playwright": "playwright test test/wokwi-embed",
+    "test:embed:playwright:ui": "playwright test test/wokwi-embed --ui",
+    "test:cli:integration": "pnpm exec tsx scripts/test-cli-integration.ts",
+    "package": "pnpm --filter wokwi-cli run package",
     "cli": "tsx packages/wokwi-cli/src/main.ts",
     "prepare": "husky install"
   },
@@ -19,26 +26,15 @@
     "type": "git",
     "url": "https://github.com/wokwi/wokwi-cli"
   },
-  "dependencies": {
-    "@clack/prompts": "^0.7.0",
-    "@iarna/toml": "2.2.5",
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "arg": "^5.0.2",
-    "chalk": "^5.3.0",
-    "chalk-template": "^1.1.0",
-    "pngjs": "^7.0.0",
-    "ws": "^8.13.0",
-    "yaml": "^2.3.1"
-  },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
+    "@playwright/test": "^1.48.0",
     "esbuild": "^0.25.2",
     "eslint": "^9.39.1",
-    "eslint-config-prettier": "^10.1.8",
     "husky": "^8.0.0",
     "jiti": "^2.6.1",
     "lint-staged": "^15.4.3",
-    "prettier": "^3.5.0",
+    "prettier": "^3.6.2",
     "rimraf": "^5.0.0",
     "tsx": "^4.19.2",
     "typescript": "^5.9.3",
@@ -47,8 +43,8 @@
   },
   "lint-staged": {
     "*.{js,ts}": [
-      "prettier --write",
-      "eslint"
+      "pnpm run format:check",
+      "pnpm run lint"
     ]
   }
 }

packages/wokwi-cli/package.json

@@ -5,10 +5,15 @@
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "build": "node tools/build.js",
-    "package": "npm run build && pkg --public -o dist/bin/wokwi-cli -t node20-linuxstatic-arm64,node20-linuxstatic-x64,node20-macos-arm64,node20-macos-x64,node20-win-x64 dist/cli.cjs",
+    "prebuild": "pnpm run clean",
+    "build": "tsc && pnpm run bundle",
+    "bundle": "node tools/bundle.js",
+    "package": "pnpm run build && pkg --public -o dist/bin/wokwi-cli -t node20-linuxstatic-arm64,node20-linuxstatic-x64,node20-macos-arm64,node20-macos-x64,node20-win-x64 dist/cli.cjs",
+    "clean": "rimraf dist",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
     "cli": "tsx src/main.ts",
-    "test": "npm run lint && vitest --run",
+    "test": "pnpm run lint && vitest --run",
     "test:watch": "vitest --watch"
   },
   "keywords": [
@@ -41,6 +46,7 @@
     "chalk": "^5.3.0",
     "chalk-template": "^1.1.0",
     "pngjs": "^7.0.0",
+    "wokwi-client-js": "workspace:*",
     "ws": "^8.13.0",
     "yaml": "^2.3.1"
   },

packages/wokwi-cli/src/TestScenario.ts

@@ -1,5 +1,5 @@
 import chalkTemplate from 'chalk-template';
-import type { APIClient } from './APIClient.js';
+import type { APIClient } from 'wokwi-client-js';
 
 export interface IScenarioCommand {
   /** Validates the input to the command. Throws an exception of the input is not valid */

packages/wokwi-cli/src/constants.ts

@@ -0,0 +1 @@
+export const DEFAULT_SERVER = process.env.WOKWI_CLI_SERVER ?? 'wss://wokwi.com/api/ws/beta';