Skip to content

Commit 0ff8874

Browse files
michaellwestmichaellwest
committed
Update docs for CORS proxy and Out-String wrapping
- CLAUDE.md: Add cors-proxy command, document proxy support in providers section, add conventions for script wrapping and JWT audience override - ARCHITECTURE.md: Move CORS proxy from future work to completed, add Out-String wrapping and proxy to completed list, fix endpoint reference
1 parent 3d932c0 commit 0ff8874

2 files changed

Lines changed: 14 additions & 5 deletions

File tree

‎ARCHITECTURE.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -423,11 +423,13 @@ tutorial to optionally connect to a real Sitecore instance via SPE Remoting.
423423
**Completed:**
424424
- [x] `ExecutionProvider` interface (`src/providers/types.ts`) — `executeScript()`, `executeCommand()`, `getTree()`, `getCwd()`, `reset()`
425425
- [x] `LocalProvider` — wraps existing engine, zero behavior change for tutorials
426-
- [x] `SpeRemotingProvider` — sends scripts to real Sitecore via `speClient.ts` (JWT + Basic auth)
427-
- [x] `ConnectionManager` UI component — connect/disconnect toggle, URL, auth fields (JWT/Basic)
426+
- [x] `SpeRemotingProvider` — sends scripts to real Sitecore via `speClient.ts` (`/-/script/script/`, JWT + Basic auth)
427+
- [x] `ConnectionManager` UI component — connect/disconnect toggle, URL, auth fields (JWT/Basic), CORS proxy toggle
428428
- [x] `App.tsx` refactored to delegate execution through active provider (async)
429429
- [x] Task validation always runs locally (simulation engine) regardless of active provider
430430
- [x] `speClient.ts` migrated from Node `require("crypto")` to Web Crypto API
431+
- [x] Scripts wrapped in `& { <script> } | Out-String` for ps1xml formatting via `rawOutput=true`
432+
- [x] Local CORS proxy (`tools/cors-proxy.ts`) — Bun server that forwards requests and adds CORS headers; works with internal/VPN instances
431433

432434
**Future work:**
433435

@@ -441,7 +443,7 @@ tutorial to optionally connect to a real Sitecore instance via SPE Remoting.
441443
| **REST API provider** | Low | Item CRUD via Sitecore ItemService REST API (no script execution) |
442444
| **SitecoreAI / XM Cloud provider** | Low | Cloud API integration for XM Cloud instances |
443445
| **Connection profiles** | Low | Save multiple named connections in localStorage (not just the last one) |
444-
| **CORS proxy** | Low | Optional proxy for instances that don't allow cross-origin requests from the tutorial domain |
446+
| ~~**CORS proxy**~~ | ~~Low~~ | Done — `tools/cors-proxy.ts` with ConnectionManager toggle |
445447

446448
**Extraction roadmap** (if components are packaged for reuse beyond the tutorial):
447449

‎CLAUDE.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Browser-based interactive tutorial for Sitecore PowerShell Extensions (SPE). Emb
1717
- `bunx vitest run -t "test name pattern"` — Run tests matching a name
1818
- `bun run test:spe` — Integration tests against a real SPE instance (separate config, 30s timeout)
1919
- `bun run deploy` — Build + deploy to Cloudflare Pages via Wrangler
20+
- `bun run cors-proxy -- --target <url> [--port 3001]` — Local CORS proxy for SPE Remoting
2021

2122
## Architecture
2223

@@ -54,9 +55,13 @@ The codebase has two independent layers: a **pure TypeScript simulation engine**
5455

5556
**LocalProvider** — wraps the existing engine and virtual tree. Default for tutorials. Exposes `getContext()` and `getFullTree()` for validation.
5657

57-
**SpeRemotingProvider** — sends scripts to a real Sitecore instance via `speClient.ts`. Uses JWT or Basic auth. Tree panel falls back to virtual tree (SPE Remoting has no tree browsing API).
58+
**SpeRemotingProvider** — sends scripts to a real Sitecore instance via `speClient.ts` (`/-/script/script/` endpoint). Uses JWT or Basic auth. Scripts are wrapped in `& { <script> } | Out-String` so PowerShell's ps1xml formatting rules apply server-side. Tree panel falls back to virtual tree (SPE Remoting has no tree browsing API). Supports optional CORS proxy (`useProxy`/`proxyUrl` in `ConnectionConfig`).
5859

59-
**ConnectionManager** component in the header lets users toggle between local simulation and a live Sitecore connection. URL and username persist to localStorage; credentials are never stored.
60+
**ConnectionManager** component in the header lets users toggle between local simulation and a live Sitecore connection. URL, username, and proxy preferences persist to localStorage; credentials are never stored. Includes a "Use CORS proxy" checkbox for instances that block cross-origin requests.
61+
62+
### CORS Proxy (`tools/`)
63+
64+
**cors-proxy.ts** — Local Bun server that forwards requests to a Sitecore instance and adds CORS headers. Runs on the user's machine, so it can reach internal/VPN-only instances. Usage: `bun run cors-proxy -- --target https://sitecore.example.com`. The user enters `http://localhost:3001` as the proxy URL in ConnectionManager.
6065

6166
### UI (`src/components/`)
6267

@@ -73,6 +78,8 @@ The codebase has two independent layers: a **pure TypeScript simulation engine**
7378
- **Line continuation** — lines ending with `|` or backtick (`` ` ``) are joined before execution.
7479
- **Execution goes through providers** — `App.tsx` never calls `executeScript()`/`executeCommand()` directly; it delegates to `providerRef.current`. New execution backends implement the `ExecutionProvider` interface.
7580
- **Validation always runs locally** — `validateTask()` uses the local engine regardless of active provider, so lesson validation works offline.
81+
- **SPE Remoting wraps scripts** — `speClient.ts` sends `& { <user script> } | Out-String` with `rawOutput=true` so ps1xml formatting applies server-side. Never send raw scripts without wrapping.
82+
- **JWT audience uses real URL** — When using the CORS proxy, `audienceOverride` ensures the JWT audience targets the real Sitecore origin, not the proxy URL.
7683

7784
## Testing
7885

0 commit comments

Comments
 (0)