@microsoft/rayfin-guide 1.35.0-alpha.1368 → 1.35.0-alpha.1374

package/assets/docs/cli/environment-variables.md

@@ -18,7 +18,7 @@ The `rayfin env` command (or the auto-emit built into `rayfin up`) maps them to
 | `RAYFIN_PUBLIC_TENANT_ID` | Entra ID tenant for workspace disambiguation. | `rayfin up` |
 | `RAYFIN_PUBLIC_PORTAL_URL` | Fabric Portal base URL (for example, `https://app.fabric.microsoft.com/`). | `rayfin up` |
 | `RAYFIN_PUBLIC_SERVICE_MODE` | `rayfin` (real backend) or `mock` (local testing). | User-set in `rayfin/.env` |
-| `RAYFIN_PUBLIC_FRONTEND_PORT` | Stable per-project frontend dev-server port. Assigned once and reused so the dev server pins a deterministic origin the deployed backend can allow-list. | `rayfin dev` / `rayfin up` |
+| `RAYFIN_PUBLIC_FRONTEND_PORT` | Stable per-project frontend dev-server port. Reused while available and automatically replaced when occupied so the frontend and backend allow-list stay aligned. | `rayfin dev` / `rayfin up` |
 
 ### Framework mapping
 
@@ -39,8 +39,12 @@ The `rayfin env` command (or the auto-emit built into `rayfin up`) maps them to
 Custom `RAYFIN_PUBLIC_*` variables you add follow a generic pattern: `RAYFIN_PUBLIC_FOO` becomes `VITE_RAYFIN_FOO` (Vite), `NEXT_PUBLIC_RAYFIN_FOO` (Next.js), or `FOO` (plain).
 
 `RAYFIN_PUBLIC_FRONTEND_PORT` maps to the port variable each dev server reads (`VITE_PORT` for Vite, `PORT` for Next.js).
-The sample `vite.config.ts` files pin the server to it with `strictPort`, so if the assigned port is already taken the dev server fails fast instead of silently drifting to another port.
-To run on a different port, set `RAYFIN_PUBLIC_FRONTEND_PORT` in `rayfin/.env` (then re-run `rayfin env`); `rayfin up` registers whatever value is assigned in the deployed redirect allow-list.
+Before local frontend wiring, Rayfin checks whether the persisted port is available.
+If it is occupied, Rayfin selects the next available port, updates `rayfin/.env`, and registers the replacement origin in the deployed redirect allow-list when authentication is enabled.
+Rayfin temporarily retains an occupied prior port in `RAYFIN_FRONTEND_DEV_PORT_ALIASES` so an already-running frontend keeps authenticating; the alias is removed after the port becomes available.
+This managed variable is not exposed to frontend builds and should not be edited manually.
+The sample `vite.config.ts` files use `strictPort` so Vite cannot silently drift from that persisted, allow-listed origin.
+To prefer a different port, set `RAYFIN_PUBLIC_FRONTEND_PORT` in `rayfin/.env`, then run `rayfin dev` or `rayfin up` to validate and project it into `.env.local`.
 
 ### Bare development runtime wiring
 
@@ -59,12 +63,19 @@ When `services.functions.enabled` is `true`, the same command builds and starts
 The CLI reserves the nearest available Functions port starting at `7071` and writes its URL to `RAYFIN_PUBLIC_FUNCTIONS_URL` before starting the frontend.
 When functions are disabled, the CLI removes any stale `RAYFIN_PUBLIC_FUNCTIONS_URL` from `rayfin/.env` and regenerates the framework environment file without it.
 
+Bundled Vite templates use `@microsoft/rayfin-local-dev` to keep local function calls on the frontend origin.
+During `vite serve`, the client calls `/.rayfin/api/<name>` and the Vite adapter forwards that request to the exact Functions URL selected by `rayfin dev`.
+If the local Functions host becomes unavailable, the adapter returns HTTP 502 and does not invoke deployed function code.
+Production builds leave `functionsBaseUrl` unset, so function calls use the deployed Rayfin backend route.
+Non-Vite projects can continue to pass their framework-mapped Functions URL directly to `RayfinClient` during development.
+The proxy is reachable wherever the Vite dev server is reachable, so keep Vite bound to loopback or restrict its `host` and `allowedHosts` settings to the trusted development network.
+
 The local functions setup makes these workspace changes:
 
 - Merges backend coordinates and the Node inspector argument into the configured functions package's `local.settings.json`.
 - Adds a `Functions: Attach` configuration to the root `.vscode/launch.json` after the Functions host becomes ready.
 - Leaves JSON-with-comments launch files unchanged and reports that the attach configuration must be added manually.
-- Patches recognized `src/services/rayfinClient.ts` and `src/services/bootstrap.ts` template files once so `functionsBaseUrl` reads `VITE_RAYFIN_FUNCTIONS_URL`.
+- Patches recognized existing `src/services/rayfinClient.ts` and `src/services/bootstrap.ts` files once so non-adapter projects read `VITE_RAYFIN_FUNCTIONS_URL` only during Vite development.
 - Regenerates the framework `.env.local` file unless `--no-emit-env` is set.
 
 The Node inspector defaults to port `9229` and slides to the nearest available port when needed.
@@ -203,6 +214,7 @@ These variables are read from the shell environment and are never written to fil
 | `.env.local` | Framework-specific frontend variables, auto-generated by `rayfin env`. | No (gitignored) |
 | `~/.rayfin/auth-state.json` | CLI authentication state (tenant, account hints). | N/A (user home) |
 | `~/.rayfin/token-cache.json` | Encrypted token cache (OS-backed encryption). | N/A (user home) |
+| `~/.rayfin/dev-device-id` | Random anonymous identifier correlating telemetry from this installation. Not written when telemetry is off; delete it to reset. | N/A (user home) |
 
 ## Resolution priority
 

package/assets/docs/preview/local-dev-docker.md

@@ -40,12 +40,16 @@ When functions are enabled, `rayfin dev --provider docker` reserves the nearest
 It writes the selected URL to `RAYFIN_PUBLIC_FUNCTIONS_URL` in `rayfin/.env` and regenerates the framework `.env.local` file.
 When functions are disabled, it removes a stale Functions URL instead.
 
+Bundled Vite templates route local function calls through the same-origin `/.rayfin` path.
+The Vite adapter forwards only function calls to the selected local host; data, auth, and storage continue to target the Docker backend directly.
+An unavailable local Functions host returns HTTP 502 without falling back to deployed function code.
+
 The command also:
 
 - Merges local backend settings into the configured functions package's `local.settings.json`.
 - Reserves a Node inspector port starting at `9229`.
 - Adds `Functions: Attach` to the root `.vscode/launch.json` after the Functions host is ready.
-- Patches recognized `src/services/rayfinClient.ts` and `src/services/bootstrap.ts` files to pass `VITE_RAYFIN_FUNCTIONS_URL` as `functionsBaseUrl`.
+- Patches recognized existing `src/services/rayfinClient.ts` and `src/services/bootstrap.ts` files to pass `VITE_RAYFIN_FUNCTIONS_URL` directly only during Vite development.
 
 If `.vscode/launch.json` contains JSON with comments, Rayfin leaves it unchanged to avoid losing those comments and asks you to add the attach configuration manually.
 Use `--no-emit-env` to leave a hand-managed `.env.local` file unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-guide",
-  "version": "1.35.0-alpha.1368",
+  "version": "1.35.0-alpha.1374",
   "description": "Cross-cutting Builder guides for the Rayfin platform — discovered by `@microsoft/rayfin-docs` via the `rayfinDocs` package.json field convention.",
   "type": "module",
   "files": [