Refactoring 7

.gitignore

@@ -8,6 +8,7 @@ Thumbs.db
 *~
 *.log
 npm-debug.log*
+.zshrc.local
 yarn-debug.log*
 yarn-error.log*
 

.husky/pre-push

@@ -2,12 +2,12 @@
 
 echo "🔍 Starte Qualitäts-Checks vor dem Push..."
 
-# 1. Schnelle Tests ausführen
+# 1. Schnelle Tests mit Coverage ausführen
 # Hinweis: Falls Tests zu lange dauern, können Sie diese Hook mit:
 #   git push --no-verify
 # umgehen (nicht empfohlen!)
-echo "⏳ Starte npm run test:fast..."
-npm run test:fast
+echo "⏳ Starte npm run test:fast (mit Coverage)..."
+LOG_LEVEL=warn npx vitest run --coverage --exclude tests/server/load-suite.test.ts --exclude tests/integration/serial-flow.test.ts
 if [ $? -ne 0 ]; then
   echo "❌ Fehler: Die schnellen Tests sind fehlgeschlagen!"
   echo "💡 Tipp: Um den Hook zu überspringen, verwende: git push --no-verify"

.sonarlint/connectedMode.json

@@ -0,0 +1,4 @@
+{
+  "sonarQubeUri": "http://localhost:9000",
+  "projectKey": "unowebsim"
+}

.sonarlintignore

@@ -0,0 +1,12 @@
+# Ignore shell configuration files containing environment secrets
+.zshrc*
+.bashrc*
+.bash_profile*
+.profile*
+
+# Ignore editor config
+.vscode/
+.idea/
+
+# Ignore node_modules
+node_modules/

.vscode/launch.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.2.0",
+  "configurations": [],
+  "compounds": [],
+  "inputs": [],
+  "env": {
+    "SONARQUBE_URL": "http://localhost:9000",
+    "SONAR_URL": "http://localhost:9000",
+    "SONAR_TOKEN": "squ_85eeef7888f45f1801a6c36fa7b94e1b7287f951",
+    "SONARQUBE_TOKEN": "squ_85eeef7888f45f1801a6c36fa7b94e1b7287f951"
+  }
+}

README.md

@@ -70,6 +70,84 @@ npm run dev:full
 
 This will start both the backend server and the frontend development server.
 
+## Usage
+
+UnoSim can be run in several modes depending on your use case.
+
+### Development Mode
+
+```bash
+npm run dev:full
+```
+
+Starts the backend (Express + WebSocket) and the Vite dev server with hot-reload.
+The backend runs via `tsx` (TypeScript execution) and the client is served by Vite on a separate port with HMR.
+Compilation uses `arduino-cli` directly on the host — Docker is **not** required.
+
+| Component | Details |
+|-----------|---------|
+| Backend | `tsx server/index.ts` on port 3000 |
+| Client | Vite HMR dev server (proxied) |
+| Compiler | Direct `arduino-cli` calls on host |
+| Worker Pool | Disabled (`PooledCompiler.usePool = false` outside production) |
+
+### Production Mode
+
+```bash
+npm run build
+npm run start
+```
+
+Builds the full stack (client + server + worker) into `dist/` and runs the production server.
+The Vite-built client is served as static files from `dist/public/`.
+
+| Component | Details |
+|-----------|---------|
+| Backend | `node dist/index.js` on port 3000 |
+| Client | Static files from `dist/public/` |
+| Compiler | Worker Pool with 4 parallel threads |
+| Docker | Optional — enables sandboxed compilation if Docker Desktop is running |
+
+> **Note:** Docker warnings at startup (`Cannot connect to the Docker daemon`) are non-blocking.
+> The app falls back to direct `arduino-cli` compilation when Docker is unavailable.
+
+### Docker Mode
+
+```bash
+docker build -t unowebsim:latest .
+docker run --rm -p 3000:3000 -e NODE_ENV=production unowebsim:latest
+```
+
+Or with docker-compose:
+
+```bash
+docker-compose up --build
+```
+
+Runs the full application inside a container with `arduino-cli` pre-installed.
+Available at `http://localhost:3000`.
+
+### Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev:full` | Start backend + client in development mode |
+| `npm run dev` | Start backend only (no client) |
+| `npm run dev:client` | Start Vite client only |
+| `npm run build` | Build client, server, and worker for production |
+| `npm run start` | Run the production build |
+| `npm run check` | TypeScript type-check (`tsc --noEmit`) |
+| `npm run test:fast` | Run unit tests (excludes load tests) |
+| `npm test` | Run all tests |
+| `./run-tests.sh` | Full pipeline: lint, unit tests, Docker build, integration tests, E2E |
+
+### Architecture Overview
+
+- **Sandbox Runner Pool** — Manages a pool of sandbox processes that execute compiled Arduino binaries. Each simulation runs in an isolated child process with stdout/stderr capture for serial output and pin state reporting.
+- **Compilation Worker Pool** — In production mode, 4 Node.js Worker Threads handle compilations in parallel via the `PooledCompiler`. Each worker runs `arduino-cli` and caches build artifacts (hex files, core objects) for faster recompilation.
+- **WebSocket Layer** — Real-time communication between client and server for serial output, pin state batches, and simulation control (start/stop/pause/resume).
+- **SonarQube Integration** — Quality gate checks are built into the pre-push hook and the test pipeline (`./run-tests.sh`). Coverage reports are generated automatically.
+
 ## Notes for running tests (optional)
 
 The repository contains a **robust, fast test pipeline**:
@@ -131,27 +209,3 @@ The backend utilizes an Adapter Pattern for compilation:
 - Worker Isolation: Each compilation task runs in a separate thread, reducing API latency by ~30% under concurrent load.
 
 - Graceful Shutdown: Intelligent SIGTERM handling ensures all worker threads and file handles are closed properly.
-
-## Docker
-
-This repository includes a Dockerfile that builds the project using Node.js v25.2.1.
-
-- Build the image:
-
-```bash
-docker build -t unowebsim:latest .
-```
-
-- Run the container (exposes port 3000):
-
-```bash
-docker run --rm -p 3000:3000 -e NODE_ENV=production unowebsim:latest
-```
-
-- Alternatively use docker-compose:
-
-```bash
-docker-compose up --build
-```
-
-The server will be available at http://localhost:3000

client/src/components/features/code-editor.tsx

@@ -582,10 +582,11 @@ export function CodeEditor({
         // Move cursor to end of pasted text
         const lines = text.split("\n");
         const endLineNumber = selection.startLineNumber + lines.length - 1;
+        const lastLineText = lines.at(-1) ?? "";
         const endColumn =
           lines.length === 1
             ? selection.startColumn + text.length
-            : lines.at(-1)!.length + 1;
+            : lastLineText.length + 1;
 
         editor.setPosition({
           lineNumber: endLineNumber,

client/src/components/features/parser-output.tsx

@@ -410,7 +410,7 @@ export function ParserOutput({
                               size="sm"
                               onClick={() => {
                                 onInsertSuggestion?.(
-                                  message.suggestion!,
+                                  message.suggestion ?? "",
                                   message.line,
                                 );
                               }}

client/src/components/features/serial-monitor.tsx

@@ -71,6 +71,30 @@ function processAnsiCodes(text: string): string {
   return processed;
 }
 
+/**
+ * Strips leading backspace characters from text and removes corresponding
+ * characters from the last incomplete line.
+ */
+function consumeLeadingBackspaces(
+  lines: Array<{ text: string; incomplete: boolean }>,
+  text: string,
+): string {
+  let idx = 0;
+  while (idx < text.length && text[idx] === "\b") {
+    idx++;
+  }
+  if (idx === 0) return text;
+
+  const lastLine = lines.at(-1);
+  if (!lastLine?.incomplete) return text;
+
+  lastLine.text = lastLine.text.slice(
+    0,
+    Math.max(0, lastLine.text.length - idx),
+  );
+  return text.slice(idx);
+}
+
 // Exported for unit testing and reuse inside the hook
 export function applyBackspaceAcrossLines(
   lines: Array<{ text: string; incomplete: boolean }>,
@@ -79,36 +103,20 @@ export function applyBackspaceAcrossLines(
 ): string | null {
   // Handle backspaces at the start of text
   if (text.includes("\b")) {
-    // Count leading backspaces to remove from previous line
-    let backspaceCount = 0;
-    let idx = 0;
-    while (idx < text.length && text[idx] === "\b") {
-      backspaceCount++;
-      idx++;
-    }
-
-    if (
-      backspaceCount > 0 &&
-      lines.length > 0 &&
-      lines.at(-1)!.incomplete
-    ) {
-      const lastLine = lines.at(-1)!;
-      lastLine.text = lastLine.text.slice(
-        0,
-        Math.max(0, lastLine.text.length - backspaceCount),
-      );
-      text = text.slice(backspaceCount);
-    }
+    text = consumeLeadingBackspaces(lines, text);
   }
 
   // If there's still text to process and we have an incomplete line, append to it
-  if (text && lines.length > 0 && lines.at(-1)!.incomplete) {
-    const cleanText = processAnsiCodes(text);
-    if (cleanText) {
-      lines.at(-1)!.text += cleanText;
-      lines.at(-1)!.incomplete = !isComplete;
+  if (text) {
+    const lastLine = lines.at(-1);
+    if (lastLine?.incomplete) {
+      const cleanText = processAnsiCodes(text);
+      if (cleanText) {
+        lastLine.text += cleanText;
+        lastLine.incomplete = !isComplete;
+      }
+      return null; // already handled
     }
-    return null; // already handled
   }
 
   // No text left after backspace processing, or no incomplete line to append to
@@ -140,17 +148,49 @@ function processCarriageReturnLine(
   const parts = text.split("\r");
   const cleanParts = parts.map((p) => processAnsiCodes(p));
   if (cleanParts.length <= 1) return false;
-  const finalText = cleanParts.at(-1)!;
-  if (lines.length > 0 && !lines.at(-1)!.incomplete) {
-    lines.push({ text: finalText, incomplete: !lineComplete });
-  } else if (lines.length > 0) {
+  const finalText = cleanParts.at(-1) ?? "";
+  const lastLine = lines.at(-1);
+  if (lastLine?.incomplete) {
     lines[lines.length - 1] = { text: finalText, incomplete: !lineComplete };
   } else {
     lines.push({ text: finalText, incomplete: !lineComplete });
   }
   return true;
 }
 
+function processLineWithControls(
+  lines: ProcessedLine[],
+  text: string,
+  controls: ReturnType<typeof hasControlChars>,
+  shouldClear: boolean,
+  lineComplete: boolean,
+): { text: string; shouldClear: boolean; handled: boolean } {
+  let newShouldClear = shouldClear;
+  let newText = text;
+
+  if (controls.hasClearScreen) {
+    newShouldClear = true;
+    lines.length = 0;
+  }
+
+  if (controls.hasCursorHome && newShouldClear) {
+    lines.length = 0;
+    newShouldClear = false;
+  }
+
+  const backspaceResult = applyBackspaceAcrossLines(lines, newText, lineComplete);
+  if (backspaceResult === null) {
+    return { text: "", shouldClear: newShouldClear, handled: true };
+  }
+
+  newText = backspaceResult;
+  if (controls.hasCarriageReturn && processCarriageReturnLine(lines, newText, lineComplete)) {
+    return { text: "", shouldClear: newShouldClear, handled: true };
+  }
+
+  return { text: newText, shouldClear: newShouldClear, handled: false };
+}
+
 export function SerialMonitor({
   output,
   isConnected: _isConnected,
@@ -204,39 +244,21 @@ export function SerialMonitor({
       let text = line.text;
       const controls = hasControlChars(text);
 
-      if (controls.hasClearScreen) {
-        shouldClear = true;
-        lines.length = 0;
-      }
-
-      if (controls.hasCursorHome) {
-        if (shouldClear) {
-          lines.length = 0;
-          shouldClear = false;
-        }
-      }
-
-      // Handle backspace across line boundaries: apply to last incomplete line
-      const backspaceResult = applyBackspaceAcrossLines(
+      const { text: processedText, shouldClear: newShouldClear, handled } = processLineWithControls(
         lines,
         text,
+        controls,
+        shouldClear,
         line.complete ?? true,
       );
-      if (backspaceResult === null) {
-        return; // handled fully
-      }
-      text = backspaceResult;
+      shouldClear = newShouldClear;
 
-      if (controls.hasCarriageReturn) {
-        if (processCarriageReturnLine(lines, text, line.complete ?? true)) {
-          return;
+      if (!handled && processedText) {
+        const cleanText = processAnsiCodes(processedText);
+        if (cleanText) {
+          lines.push({ text: cleanText, incomplete: !line.complete });
         }
       }
-
-      const cleanText = processAnsiCodes(text);
-      if (cleanText) {
-        lines.push({ text: cleanText, incomplete: !line.complete });
-      }
     });
 
     return lines;

client/src/hooks/use-compile-and-run.ts

@@ -214,7 +214,7 @@ export function useCompileAndRun(params: CompileAndRunParams): UseCompileAndRunR
     },
     onError: (err: unknown) => {
       const backendDown = params.isBackendUnreachableError(err);
-      const message = err instanceof Error ? err.message : String(err);
+      const message = err instanceof Error ? err.message : JSON.stringify(err, null, 2);
       params.toast({
         title: backendDown ? "Backend unreachable" : "Upload failed",
         description: backendDown
@@ -498,7 +498,7 @@ export function useCompileAndRun(params: CompileAndRunParams): UseCompileAndRunR
       } catch { }
     },
     onError: (error: unknown) => {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = error instanceof Error ? error.message : JSON.stringify(error, null, 2);
       params.toast({
         title: "Start Failed",
         description: message || "Could not start simulation",

client/src/hooks/useSimulatorFileSystem.ts

@@ -73,8 +73,8 @@ export function useSimulatorFileSystem({
       setTabs(newTabs);
 
       if (activeTabId === tabId) {
-        if (newTabs.length > 0) {
-          const newActiveTab = newTabs.at(-1)!;
+        const newActiveTab = newTabs.at(-1);
+        if (newActiveTab) {
           setActiveTabId(newActiveTab.id);
           setCode(newActiveTab.content);
         } else {