Merge pull request 'fix: updated commands' (#12) from furqan into dev

Reviewed-on: https://gitea.maskantech.in/gitea_admin/pdf/pulls/12

command.MD

@@ -1,107 +1,190 @@
-# PDF Engine — Windows Development Commands
-
-## Windows Environment
-
-Always use:
-
-```text
-Developer PowerShell for VS 2022
-```
-
-This ensures:
-
-* MSVC compiler works
-* C++ standard library paths are loaded
-* CMake works correctly
+# PDF Engine — Developer Command Reference
 
 ---
 
-# 1. Configure Project
+## ⚠️ Windows — Activate MSVC Before Anything Else
 
-Use when:
+Run this once per terminal session before any `cmake` command:
 
-* adding new `.cpp` files
-* modifying `CMakeLists.txt`
-* changing presets
+**Option A — Open a new PowerShell with MSVC loaded**
+
+```powershell
+cmd /c '"C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat" && powershell'
+```
+
+**Option B — Load MSVC into your current PowerShell window**
+
+```powershell
+cmd /c '"C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat" && set' |
+  Where-Object { $_ -match '=' } |
+  ForEach-Object {
+    $name, $value = $_ -split '=', 2
+    [System.Environment]::SetEnvironmentVariable($name, $value, 'Process')
+  }
+$env:VCPKG_ROOT = "C:\Users\furqa\vcpkg"
+```
+
+If you skip this step, cmake will fail with:
+`CMake Error: No CMAKE_CXX_COMPILER could be found.`
+
+---
+
+## One-Time Setup (new machine only)
+
+```powershell
+pwsh scripts/bootstrap.ps1
+```
+
+```sh
+./scripts/bootstrap.sh
+```
+
+---
+
+## Component 1 — C++ Engine
+
+### Configure
+
+Run on first setup, after adding `.cpp` files, or after changing `CMakeLists.txt`.
 
 ```powershell
 cmake --preset windows-debug
 ```
 
-## What it does
+### Build
 
-* Reads `CMakePresets.json`
-* Loads vcpkg toolchain
-* Finds installed libraries
-* Generates Ninja build files
-
----
-
-# 2. Build Project
-
-Use after changing C++ code.
+Run after changing any C++ source file.
 
 ```powershell
 cmake --build --preset windows-debug
 ```
 
-## What it does
-
-* Compiles `.cpp` files
-* Links FreeType + HarfBuzz
-* Builds `pdfengine`
-
----
-
-# 3. Run Tests
-
-Use to verify:
-
-* wrappers
-* font engine
-* integration tests
+### Test
 
 ```powershell
 ctest --preset windows-debug
 ```
 
-## Expected Output
+Expected output: `100% tests passed`
 
-```text
-100% tests passed
-```
+### Fresh / Clean Rebuild
 
----
-
-# 4. Fresh/Clean Rebuild
-
-Use when:
-
-* cache issues occur
-* compiler mismatch happens
-* strange errors appear
+Use when you see cache errors or strange Ninja errors.
 
 ```powershell
 cmake --preset windows-debug --fresh
 cmake --build --preset windows-debug
 ```
 
-## What `--fresh` does
+### Rule R2 Boundary Check
 
-* Deletes old cache
-* Regenerates Ninja files
-* Reconfigures compiler/toolchain
+Verifies no raw `FPDF_*` calls exist outside `engine/src/parser/`.
+
+```powershell
+pwsh scripts/check_pdfium_boundary.ps1
+```
 
 ---
 
+## Component 2 — Gateway (FastAPI / Python)
 
+```powershell
+cd gateway
+python -m pip install -e ".[dev]"
+python -m ruff check .
+python -m ruff format --check .
+python -m pytest
+```
 
+---
 
+## Component 3 — Frontend (React / TypeScript)
 
+```powershell
+cd frontend
+npm install
+npm run dev
+npm run build
+npm run lint
+```
 
+---
 
+## Component 4 — WASM (Emscripten)
 
+Activate Emscripten first (one-time install):
 
+```powershell
+Get-Content wasm/emsdk.pinned
+./emsdk install <version>
+./emsdk activate <version>
+./emsdk_env.ps1
+```
+
+Build and test:
+
+```powershell
+cmake --preset wasm
+cmake --build --preset wasm
+node wasm/hello.test.mjs
+```
+
+Expected output:
+```
+[wasm-smoke] OK — add(2,3)=5, hello_version()=1, cwrap add(40,2)=42
+```
+
+Browser test (optional):
+
+```powershell
+npx serve .
+```
+
+Open `http://localhost:3000/test.html` and check the browser console (F12).
+
+---
+
+## C++ Code Style (clang-format)
+
+Install once (CI is pinned to 22.1.5):
+
+```powershell
+pip install clang-format==22.1.5
+```
+
+Check formatting:
+
+```powershell
+Get-ChildItem -Recurse engine -Include *.cpp,*.cc,*.h,*.hpp |
+  ForEach-Object { clang-format --dry-run --Werror $_.FullName }
+```
+
+Auto-format in place:
+
+```powershell
+Get-ChildItem -Recurse engine -Include *.cpp,*.cc,*.h,*.hpp |
+  ForEach-Object { clang-format -i $_.FullName }
+```
+
+---
+
+## Run Everything at Once
+
+Runs all components and prints one pass/fail per component.
+
+```powershell
+pwsh scripts/test_phase0.ps1 -Preset windows-debug
+pwsh scripts/test_phase0.ps1 -Preset windows-debug -SkipWasm
+```
+
+```sh
+./scripts/test_phase0.sh
+SKIP_WASM=1 ./scripts/test_phase0.sh
+```
+
+---
+
+## Quick Reference
 
 ```powershell
 cmake --preset windows-debug
@@ -109,6 +192,24 @@ cmake --build --preset windows-debug
 ctest --preset windows-debug
 ```
 
----
+```powershell
+cd gateway
+python -m pip install -e ".[dev]"
+python -m pytest
+```
 
+```powershell
+cd frontend
+npm install
+npm run dev
+```
+
+```powershell
+cmake --preset wasm
+cmake --build --preset wasm
+node wasm/hello.test.mjs
+```
+
+```powershell
+pwsh scripts/check_pdfium_boundary.ps1
 ```