@microsoft/rayfin-guide 1.36.0-alpha.1687 → 1.36.0-alpha.1756

package/assets/docs/app-backend/deep-linking.md

@@ -33,6 +33,8 @@ Your app owns the shape of the state object.
 npm install @microsoft/rayfin-app-state-fabric
 ```
 
+If your project uses prerelease Rayfin packages, install the same exact version of `@microsoft/rayfin-app-state-fabric` as the other `@microsoft/rayfin-*` packages in the project.
+
 ## Create the client
 
 Create one client for the lifetime of your app and share it, rather than constructing one per component.
@@ -40,13 +42,13 @@ Create one client for the lifetime of your app and share it, rather than constru
 ```typescript
 import { createFabricAppStateClient } from '@microsoft/rayfin-app-state-fabric';
 
-const appState = createFabricAppStateClient({
-  targetOrigin: 'https://app.fabric.microsoft.com',
-});
+const appState = createFabricAppStateClient();
 ```
 
-Pass `targetOrigin` whenever you know it.
-Without it, messages are posted with `"*"` and inbound events are not origin-checked.
+Leave `targetOrigin` unset.
+The parent window is a Fabric extension host, not the portal origin shown in the address bar, and its origin varies by environment.
+Pinning the portal origin makes the browser silently discard every message.
+When `targetOrigin` is omitted, messages are posted with `"*"` and inbound events are not origin-checked.
 
 ## Read launch state before first render
 
@@ -66,6 +68,36 @@ It resolves from the seeded URL on hosts that support it, so awaiting it does no
 Treat launch state as untrusted input.
 Anyone can edit a link before sharing it, so validate it exactly as you would a query parameter before using it to drive queries.
 
+## Keep the restored route through sign-in
+
+A Rayfin app is authenticated, and its route guard sends a signed-out visitor to the sign-in route.
+That redirect runs after the launch state has been restored, so a guard that does not carry the requested route forward replaces it, and the visitor lands on the default page.
+
+This is the normal path for a shared link, because the recipient is usually not signed in yet.
+
+Capture the requested route when you redirect to the sign-in route, then return to it after sign-in.
+
+```tsx
+if (requireAuth && !isAuthenticated) {
+  const redirectState: AuthRedirectState = {
+    from: `${location.pathname}${location.search}`,
+  };
+  return <Navigate to="/auth" replace state={redirectState} />;
+}
+
+if (!requireAuth && isAuthenticated) {
+  return <Navigate to={resolveReturnPath(location.state)} replace />;
+}
+```
+
+Validate the captured route before navigating back to it.
+Accept only same-origin application paths, and reject the sign-in route itself so sign-in cannot loop.
+
+Keeping the sign-in route out of the state you persist is not the same thing.
+A shared link needs both: never write the sign-in route into deep-link state, and carry the requested route across the sign-in redirect.
+
+Templates that ship a route guard already carry the requested route through sign-in, so preserve that behavior as you add routes.
+
 ## Write state as the user navigates
 
 Choose between the two writers by asking who caused the change.
@@ -167,6 +199,12 @@ Validate launch state before using it, and tolerate state written by a different
 **`isSupported()` resolves to `undefined`.**
 Either the app is not embedded in the Fabric portal, or deep linking has not reached this tenant yet.
 Both are expected, and your app should fall back to its own routing.
+Also check that the client does not set `targetOrigin`; pinning the portal origin silently prevents communication with the Fabric extension host.
+
+**A shared link opens the default page instead of the shared view.**
+The app restored the launch state and then replaced it.
+Check the sign-in redirect first, because the recipient of a shared link is usually signed out.
+See [Keep the restored route through sign-in](#keep-the-restored-route-through-sign-in).
 
 **Writes reject with `STATE_TOO_LARGE`.**
 The state exceeds the encoded budget the host reported.

package/assets/docs/app-backend/deploy.md

@@ -107,7 +107,9 @@ After deployment, the CLI prints:
 
 Each deployment is recorded in `rayfin/.deployments.json` (the registry of every workspace you have deployed to from this project), and the corresponding `RAYFIN_PUBLIC_*` variables are merged into `rayfin/.env` so subsequent commands and your frontend pick up the same values.
 
-For frontend frameworks, the CLI also runs `rayfin env` to emit a framework-specific `.env.local` (e.g. for Vite) before the static build. That file is what your client code reads at runtime.
+For frontend frameworks, the CLI refreshes a framework-specific `.env.local` (for example, for Vite) before the static build.
+Detection and environment generation use the frontend directory selected by `services.staticHosting.path` and its optional `root`, while the public deployment values come from the project's `rayfin/.env`.
+If detection or environment generation fails, the deployment reports a warning with guidance instead of treating it as a successful refresh.
 
 ```text title="rayfin/.deployments.json"
 {
@@ -165,9 +167,23 @@ services:
 Use `-n, --dry-run` to see what the CLI would do without creating or modifying any resources:
 
 ```bash
-npx rayfin up -n
+npx rayfin up -n --workspace-id <workspace-id>
 ```
 
+Preview validates deterministic local static-hosting inputs before authentication or remote lookup.
+The configured frontend `path` and optional build `root` must exist and be directories.
+When `buildCommand` is configured, the output `folder` may be missing because the build has not run yet.
+Without a build command, the output folder must already exist and contain files.
+Static input checks are skipped when static hosting is disabled or excluded.
+
+After local validation, preview uses the same authentication and workspace-selection rules as deployment.
+It makes read-only Fabric requests to resolve the current workspace display name and ID, showing both before the planned operations.
+With `--json`, these values are available as `plan.workspaceName` and `plan.workspaceId`.
+If the workspace cannot be resolved, preview exits nonzero without creating or modifying resources.
+
+Preview does not run builds, provision an item, apply settings or schemas, or update project deployment files.
+A successful preview is not a build result or a guarantee that remote deployment operations will succeed.
+
 ### Skip specific services
 
 Use `--exclude-services <names>` to skip the build/package/deploy phase for supported services without touching the rest of the deployment.

package/assets/docs/cli/connectors/invoke.md

@@ -5,7 +5,7 @@ sidebar_position: 4
 # connector invoke
 
 ```bash
-npx rayfin connector invoke <connector-name> <operation> (--input '<json>' | --file <path>) [--verbose] [--json]
+npx rayfin connector invoke <connector-name> <operation> (--input '<json>' | --file <path>) [--output-file <path>] [--max-inline-bytes <bytes>] [--verbose] [--json]
 ```
 
 `connector invoke` runs a single named operation against a configured connector and prints the result. It is the loop for exercising [Category B connectors](./index.md#two-categories-of-connector) — `executeQuery` over DAX or KQL — without writing any app code.
@@ -50,6 +50,8 @@ Two transports, chosen by connector type:
 
 Success emits `{status: 'ok', connector, operation, output}`. In non-JSON modes it prints `✅ Invoked <name>.<operation>` followed by the output.
 
+A result larger than 8 KB is written to a file instead of being printed whole; see [Large results](#large-results).
+
 What `output` holds depends on the connector. `fabric-semanticmodel` normalises inside its `invoke` middleware, so `output` is already a discriminated result rather than the raw service envelope: `{status: 'success', table, requestId}`, where `table.columns` are `{name, dataType}` and `table.rows` are column-aligned arrays. No caller-side conversion is needed, and the same shape comes back whether the operation ran locally or through the deployed item.
 
 A resolved call is **not** automatically a success, and the failure signal depends on the same distinction. A connector that normalises reports Power BI failures — expired token, missing Build permission, throttling — as `{status: 'error', error, requestId}`, where `error` carries `category`, `message`, and optional `code` and `details`. A connector that returns the raw envelope reports failure as `status: 'Failed'` instead. The CLI reads both, converts either into a non-zero exit, and surfaces the service-supplied request id for tracing.
@@ -82,6 +84,56 @@ For example, an invalid DAX query exits with code `1` and can emit:
 Read `connectorError.code` and `connectorError.details` rather than parsing the display string.
 Service diagnostics may contain query or model content; review them before sharing or recording them in logs.
 
+## Large results
+
+A query has no upper bound on how much it returns, and printing a multi-megabyte result set floods a terminal — or, when an agent runs the CLI and reads its stdout, burns the agent's context window on rows it cannot use.
+
+When the serialized result exceeds **8 KB**, the full payload is written to a file and `output` carries only a preview.
+
+That threshold is a token budget, not a byte intuition.
+Connector output tokenizes at roughly 2.8 characters per token, and numeric table data at about 1.8, so 8 KB is around 3k–4.5k tokens — a reasonable cost for one probe.
+For scale, 256 KB of the same data is 93,000–144,000 tokens, which is most of a typical context window.
+
+The preview samples bulk data but preserves metadata: arrays of **50 or fewer** entries pass through whole, longer arrays keep their first 20 entries, and long strings are cut.
+That rule is what keeps a column list intact — a sampled column list would report a partial schema with nothing marking it partial, so a caller asking what a query returns would get a confident wrong answer.
+If a 20-entry sample would itself exceed the threshold, the sample shrinks (10, 5, 2, 1) until it fits; only if no setting fits does `output` become `null`.
+
+The envelope gains these fields, so this is detectable rather than silent:
+
+| Field             | Meaning                                                      |
+| ----------------- | ------------------------------------------------------------ |
+| `outputFile`      | Absolute path the full result was written to.                |
+| `outputBytes`     | Serialized size of the full result, in bytes.                 |
+| `outputTruncated` | `true` when `output` is a preview rather than the whole result. |
+| `previewItems`    | Entries kept from each sampled array, or `0` when `output` is `null`. |
+
+Read `outputFile` instead of re-running the query.
+The file holds exactly what `output` would have held, so it can be passed straight to `jq` or opened by an agent.
+
+Spilled results are written to `<project-root>/rayfin/.temp/invoke-results/` with owner-only permissions, and are pruned after 14 days or 20 files, whichever comes first.
+`rayfin/.temp/` is the CLI's existing scratch directory and is covered by the scaffolded `.gitignore`, so query results — which are customer data — cannot be committed by a stray `git add`.
+
+Two flags control this:
+
+- `--max-inline-bytes <bytes>` — change the threshold. `0` restores the old behavior and always prints the result in full.
+- `--output-file <path>` — always write the full result to `<path>`, whatever its size. The inline result is still shown in full unless it also crosses the threshold.
+
+```json
+{
+  "status": "ok",
+  "connector": "mymodel",
+  "operation": "executeQuery",
+  "output": { "status": "success", "table": { "columns": [], "rows": [] } },
+  "outputFile": "/path/to/app/rayfin/.temp/invoke-results/2026-09-21T101500.123Z-mymodel-executequery-1a2b3c4d.json",
+  "outputBytes": 4821004,
+  "outputTruncated": true,
+  "previewItems": 20
+}
+```
+
+If the file cannot be written, the command still succeeds with a truncated `output` and warns — falling back to printing the whole payload would recreate the problem this exists to prevent.
+An explicit `--output-file` that cannot be written fails instead, because the caller named that path.
+
 ## Examples
 
 ```bash
@@ -93,6 +145,9 @@ npx rayfin connector invoke --name mymodel --operation executeQuery --file ./pay
 
 # Machine-readable (no --verbose allowed alongside)
 npx rayfin connector invoke mymodel executeQuery --input '{"query":"EVALUATE TOPN(1, Sales)"}' --json
+
+# Send the full result to a known path instead of hunting for the spill file
+npx rayfin connector invoke mymodel executeQuery --file ./payload.json --output-file ./result.json --json
 ```
 
 ## Errors
@@ -106,3 +161,5 @@ npx rayfin connector invoke mymodel executeQuery --input '{"query":"EVALUATE TOP
 | `missing workspaceId/itemId in rayfin.yml`                       | Add both under `config:`, or re-run [`connector add`](./add.md).                      |
 | `Access token has the wrong audience for the Power BI query API` | Unset or replace `RAYFIN_TOKEN`, or re-run without `--json` to consent interactively. |
 | `No remote endpoint configured`                                  | The non-semantic-model transport needs a deployed item — run `npx rayfin up` first.   |
+| `Invalid --max-inline-bytes value`                               | Pass a non-negative whole number of bytes, or `0` to always print inline.             |
+| `Could not write the result to <path>`                           | Point `--output-file` at a writable path, or drop the flag to use the default location. |

package/assets/docs/cli/functions/dev-apply.md

@@ -4,7 +4,8 @@ sidebar_position: 2
 
 # dev functions apply
 
-Start the local Rayfin functions runtime against your active deployment, with a live typegen watcher and debugger support. This is the command you run while developing and debugging functions.
+Start the local Rayfin functions runtime against your active deployment, with automatic recompilation when a `build:watch` script is configured, a live typegen watcher, and debugger support.
+This is the command you run while developing and debugging functions.
 
 ```bash
 npx rayfin dev functions apply [--port <port>] [--inspect-port <port>] [--no-debug] [--no-emit-env]
@@ -34,13 +35,32 @@ npx rayfin dev functions apply [--port <port>] [--inspect-port <port>] [--no-deb
 5. Preserves the existing same-origin adapter in bundled Vite templates.
    For recognized older or custom Vite clients, the first run patches `functionsBaseUrl` to read the generated URL only during development.
 6. Builds the functions project, runs a one-shot typegen, then starts a visible **typegen watcher** (`[typegen]` prefix) that keeps `src/types.ts` in sync as you edit `function_app.ts`.
-7. Starts `func start` in the foreground and writes a `.vscode/launch.json` **"Functions: Attach"** configuration for debugging.
+7. Starts `func start` alongside the package's `npm run build:watch` compiler watcher when configured, and writes a `.vscode/launch.json` **"Functions: Attach"** configuration for debugging.
 
-Press `Ctrl+C` to stop the host and watcher.
+Press `Ctrl+C` to stop the host and watchers.
 This command does not start the frontend.
 Run the Vite frontend separately to invoke local functions through `/.rayfin/api/<name>`, or use `npx rayfin dev` to start both together.
 If the local Functions host is unavailable, the Vite adapter returns HTTP 502 instead of invoking deployed function code.
 
+## Automatic recompilation
+
+Both `npx rayfin dev functions apply` and `npx rayfin dev` build the functions package once, then run its `build:watch` script alongside the local Functions host if the script is configured.
+Both commands use `services.functions.path` from `rayfin.yml` and preserve `services.functions.buildCommand` for the initial build.
+
+To enable automatic recompilation, define a long-running `build:watch` script in the functions package's `package.json`; the TypeScript scaffold uses `"build:watch": "tsc --build --watch"`.
+If you use a custom compiler or bundler, set that script to its watch command instead.
+Source edits are compiled into `dist`, which the host watches to reload handlers.
+The separate typegen watcher keeps `src/types.ts` up to date and does not rewrite the file when the generated types are unchanged.
+
+If `build:watch` is absent, the CLI warns and starts the host without a compiler watcher; run the functions package's build command manually after source edits.
+Type generation remains enabled without a compiler watcher.
+An invalid watch script or an unreadable package manifest remains an error.
+An initial build failure prevents host startup; later compiler diagnostics can be fixed without restarting the session.
+If the compiler watcher exits, the session stops rather than serving stale code.
+
+Core Tools owns worker reloads; edits made while it is restarting can occasionally leave a stale handler running.
+If the response remains stale after compilation finishes, restart the dev session.
+
 ## Debugging
 
 With debugging enabled (default), attach your debugger to the inspector port (`9229` by default) using the generated **"Functions: Attach"** launch configuration in VS Code. Pass `--no-debug` to run without the inspector.

package/assets/docs/cli/functions/init.md

@@ -30,6 +30,15 @@ Run this from a directory that already contains a `rayfin/` project (i.e. you ha
 5. **Generates types** — runs a one-shot typegen to produce `rayfin/functions/src/types.ts` (the `AppFunctionsSchema`).
 6. **Installs AI agent files** so assistants understand the functions surface.
 
+## Runtime version
+
+Fresh and forced scaffolds pin `@microsoft/fabric-user-data-functions` to the exact version of the running Rayfin CLI, matching connector scaffolding.
+This also applies when `rayfin init` scaffolds the Functions service.
+
+The running CLI version may differ from the SDK version already installed in your app.
+Run the CLI release you want the Functions runtime to match.
+Re-running without `--force` preserves the existing Functions `package.json`, including any runtime version you selected.
+
 ## Scaffolded structure
 
 ```text

package/assets/docs/cli/index.md

@@ -70,7 +70,7 @@ Functions are server-side user-defined functions (UDFs) that run in the Fabric r
 | Command | Description |
 | --- | --- |
 | `npx rayfin functions init [directory]` | Scaffold `rayfin/functions/`, enable the functions service, install dependencies, build, and generate types. See [functions init](./functions/init.md). |
-| `npx rayfin dev functions apply` | Run the local function host with a live typegen watcher and debugger support. See [dev functions apply](./functions/dev-apply.md). |
+| `npx rayfin dev functions apply` | Run the local function host with an optional compiler watcher, live typegen, and debugger support. See [dev functions apply](./functions/dev-apply.md). |
 | `npx rayfin up functions deploy` | Build, package, and deploy functions to the remote Rayfin item. `rayfin up` runs this automatically. See [up functions deploy](./functions/deploy.md). |
 
 ### Connectors

package/assets/docs/cli/templates.md

@@ -80,6 +80,13 @@ To skip the prompt, pass `-t`/`--template <name>` using one of the names from `-
 npm create @microsoft/rayfin@latest my-app -- --template todoapp
 ```
 
+> **Windows PowerShell:** some npm/Node.js versions drop the `--` separator, so `--template` is read by npm itself instead of being forwarded to Rayfin.
+> Use `npm.cmd` instead of `npm` to avoid the issue on every Node.js version:
+>
+> ```powershell
+> npm.cmd create @microsoft/rayfin@latest my-app -- --template todoapp
+> ```
+
 ## Scaffold from an external git repository
 
 Pass any git URL to `-t`/`--template`:
@@ -181,6 +188,8 @@ registries:
     description: Our team's reusable starters
     url: https://github.com/example-org/rayfin-templates.git
     ref: v1.2.0
+    alphaRef: v1.3.0-alpha
+    betaRef: v1.3.0-beta
     path: catalogs/official
 ```
 
@@ -192,10 +201,17 @@ Each entry supports the following fields:
 | `url` | Yes | Git URL of the template repository (HTTPS, SSH, `git@`, or `file://`) |
 | `displayName` | No | Human-readable label (defaults to `name`) |
 | `description` | No | Short description shown in pickers and `--list-templates` |
-| `ref` | No | Git tag, branch, or full commit SHA to pin to (defaults to the repository's default branch) |
+| `ref` | No | Stable/default Git tag, branch, or full commit SHA to pin to (defaults to the repository's default branch) |
+| `alphaRef` | No | Git ref used by alpha CLI versions; falls back to `ref` |
+| `betaRef` | No | Git ref used by beta CLI versions; falls back to `ref` |
 | `path` | No | Subdirectory inside the repo where the manifest lives |
 | `templateName` | No | For a multi-template repo, the entry `name` or `path` to pre-select so consumers skip the picker |
 
+The running CLI's package version selects the ref. Stable releases use `ref`,
+versions such as `1.2.0-alpha.3` use `alphaRef`, and versions such as
+`1.2.0-beta.2` use `betaRef`. If the matching channel ref is omitted, the CLI
+uses `ref`. Other prerelease labels also use `ref`.
+
 ### Conflict handling
 
 The CLI loads registries in tier order (bundled → user-global → project-local).

package/assets/docs/hosting/index.md

@@ -34,7 +34,8 @@ services:
 | --- | --- | --- | --- |
 | `enabled` | Yes | — | Set to `true` to enable static hosting. |
 | `folder` | Yes | — | Output folder containing built static files, relative to `root`. |
-| `root` | No | Project root | Root directory of the frontend project, relative to the project root. |
+| `path` | No | Project root | Frontend package directory, relative to the Rayfin project root. |
+| `root` | No | `path` or project root | Build directory, relative to `path` when configured, otherwise the project root. |
 | `buildCommand` | No | — | Shell command to run before packaging (for example, `npm run build`). |
 | `indexDocument` | No | — | Default document to serve for directory requests (for example, `index.html`). |
 
@@ -72,6 +73,11 @@ services:
 
 This resolves the output path to `<project-root>/frontend/dist`.
 
+For a workspace package, use `path: packages/frontend` instead of `root: frontend`.
+The CLI detects the framework and refreshes `.env.local` in that frontend directory before building.
+When both `path` and `root` are configured, the build and environment directory is `<project-root>/<path>/<root>`.
+The `path`, `root`, and `folder` values must be relative and cannot traverse outside their containing directory.
+
 ## Deploying static content
 
 ### Full deployment with `rayfin up`
@@ -85,6 +91,11 @@ rayfin up
 
 After deployment, the CLI prints the hosting URL and stores it in `rayfin/.deployments.json` for reference.
 
+Use `rayfin up --dry-run --workspace-id <workspace-id>` to validate local inputs and display the resolved target without deploying.
+Preview requires the frontend package and build directory to exist.
+It does not run the build, so a missing output folder is allowed when `buildCommand` is configured.
+Without a build command, preview requires existing, nonempty output.
+
 #### Skip static deployment during local dev
 
 Use `rayfin dev` for the normal inner loop.

package/package.json

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