@isentinel/jest-roblox 0.3.7 → 0.3.9

package/README.md

@@ -15,10 +15,13 @@ Run your roblox-ts and Luau tests inside Roblox, get results in your terminal.
 - roblox-ts and pure Luau
 - Source-mapped errors (Luau line numbers back to `.ts` files)
 - Code coverage (via [Lute](https://github.com/luau-lang/lute) instrumentation)
-- Two backends: Open Cloud (remote) and Studio (local)
+- Three backends: Open Cloud (remote), Studio (attached, local), and Studio CLI
+  (self-launched headless Studio, local)
 - Multiple output formatters (human, agent, JSON, GitHub Actions)
 
-> [!NOTE] roblox-ts projects currently require
+<!-- prettier-ignore -->
+> [!NOTE]
+> roblox-ts projects currently require
 > [@isentinel/roblox-ts](https://npmx.dev/package/@isentinel/roblox-ts) for
 > source maps and coverage support.
 
@@ -68,6 +71,15 @@ Then run:
 jest-roblox
 ```
 
+<!-- prettier-ignore -->
+> [!NOTE]
+> `projects` is optional. With it omitted, the CLI derives one project per
+> `luauRoots` mount (the compiled-output dirs your Rojo project mounts,
+> auto-detected from your tsconfig `outDir`), generating each project's
+> `jest.config` stub for you. Set `projects` explicitly when you need
+> per-project overrides (a distinct `displayName`, `setupFiles`, `include`,
+> etc.) or a tighter project layout than the luau roots imply.
+
 ## Usage
 
 ```bash
@@ -88,6 +100,7 @@ jest-roblox --testPathPattern="modifiers|define\\.spec|triggers"
 # Use a specific backend (default "auto" picks Studio if the plugin is
 # connected, else Open Cloud if credentials are set — see Backends below)
 jest-roblox --backend studio
+jest-roblox --backend studio-cli
 jest-roblox --backend open-cloud
 
 # Collect coverage
@@ -133,7 +146,7 @@ per-package declarations error loudly.
 
 | Field                  | What it does                                                                                                                                                        | Default       |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| `backend`              | `"auto"`, `"open-cloud"`, or `"studio"`                                                                                                                             | `"auto"`      |
+| `backend`              | `"auto"`, `"open-cloud"`, `"studio"`, or `"studio-cli"`                                                                                                             | `"auto"`      |
 | `color`                | Use ANSI colors in console output                                                                                                                                   | `true`        |
 | `formatters`           | Output formatters (`"default"`, `"agent"`, `"json"`, `"github-actions"`)                                                                                            | `["default"]` |
 | `gameOutput`           | Write Game Output to a file — a path, or `true` for `game-output.log` under the root. In `--workspace` mode this is one grouped aggregate file across every package | —             |
@@ -144,6 +157,7 @@ per-package declarations error loudly.
 | `placeId`              | Open Cloud place ID                                                                                                                                                 | —             |
 | `port`                 | WebSocket port for Studio backend                                                                                                                                   | `3001`        |
 | `silent`               | Suppress console output                                                                                                                                             | `false`       |
+| `studioPath`           | Roblox Studio executable for the `studio-cli` backend (auto-detected if unset; also `--studioPath` / `JEST_ROBLOX_STUDIO_PATH`)                                     | —             |
 | `universeId`           | Open Cloud universe ID                                                                                                                                              | —             |
 
 #### Per-package fields
@@ -169,7 +183,7 @@ Put these under `test: { ... }`.
 
 | Field                    | What it does                                     | Default                              |
 | ------------------------ | ------------------------------------------------ | ------------------------------------ |
-| `projects`               | Where to look for tests in the DataModel         | **required**                         |
+| `projects`               | Where to look for tests in the DataModel         | one project per `luauRoots` mount    |
 | `testMatch`              | Glob patterns that find test files               | `**/*.spec.ts`, `**/*.test.ts`, etc. |
 | `testPathIgnorePatterns` | Patterns to skip                                 | `/node_modules/`, `/dist/`, `/out/`  |
 | `setupFiles`             | Scripts to run before the test environment loads | —                                    |
@@ -181,7 +195,9 @@ Put these under `test: { ... }`.
 
 Put these under `test: { ... }`.
 
-> [!IMPORTANT] Coverage requires [Lute](https://github.com/luau-lang/lute) to be
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> Coverage requires [Lute](https://github.com/luau-lang/lute) to be
 > installed and on your `PATH`. Lute parses Luau ASTs so the CLI can insert
 > coverage probes.
 
@@ -194,7 +210,9 @@ Put these under `test: { ... }`.
 | `coveragePathIgnorePatterns` | Files to leave out of coverage         | test files, `node_modules`, `rbxts_include` |
 | `collectCoverageFrom`        | Globs for files to include in coverage | —                                           |
 
-> [!NOTE] Coverage uses vitest `all` / Istanbul semantics: every instrumented
+<!-- prettier-ignore -->
+> [!NOTE]
+> Coverage uses vitest `all` / Istanbul semantics: every instrumented
 > file matching the include globs is reported, so a source file with no test
 > shows **0%** (and fails `coverageThreshold`) instead of being silently
 > omitted. When `collectCoverageFrom` is unset for a multi-project run, the
@@ -258,7 +276,7 @@ export default defineConfig({
 
 ## Backends
 
-Two ways to run tests, plus an auto-pick:
+Three ways to run tests, plus an auto-pick:
 
 ### Auto (default)
 
@@ -320,7 +338,9 @@ Connects to Roblox Studio over WebSocket. Faster than Open Cloud (no upload
 step), but Studio must be open with the plugin running. Studio doesn't expose
 which place is open, so multiple concurrent projects aren't supported yet.
 
-> [!NOTE] For `--coverage`, prefer `--backend open-cloud` since the coverage
+<!-- prettier-ignore -->
+> [!NOTE]
+> For `--coverage`, prefer `--backend open-cloud` since the coverage
 > output is built to a separate output under `.jest-roblox/coverage/` that is
 > likely not the studio place being served.
 
@@ -342,12 +362,54 @@ Or download `JestRobloxRunner.rbxm` from the
 [latest release](https://github.com/christopher-buss/jest-roblox-cli/releases)
 and drop it into your Studio plugins folder.
 
+### Studio CLI (self-launched, local)
+
+`--backend studio-cli` owns the whole Studio lifecycle: it builds its own place,
+launches Roblox Studio headless via Studio's `--task RunScript` interface,
+drives the installed plugin's Run mode, reads the result from Studio's output
+log, and quits Studio. No API key, no upload, no pre-opened editor — you just
+need Studio installed (logged in) with the jest plugin. It spawns its own
+isolated Studio instance, so any editor you already have open is untouched.
+
+It is selected only when you ask for it explicitly — `auto` never launches a
+Studio process on its own. Studio is auto-discovered per-OS; override the
+executable with `studioPath` (config key), `--studioPath`, or
+`JEST_ROBLOX_STUDIO_PATH`. The backend is serial: `--parallel > 1` errors.
+
+Pass `--headed` to show the Studio window during the run instead of the default
+hidden one — useful for watching a slow run or a hang (Studio still self-quits
+when tests finish, so a fast run just flashes). It is a per-run debugging flag,
+CLI-only and inert on every other backend.
+
+Once the result lands, Studio is shut down gracefully: it is allowed to close
+the place — running any edit-mode plugin `BindToClose` handlers and freeing the
+place lock — and is then killed the instant the lock releases, skipping Studio's
+slow telemetry teardown. The shutdown is decoupled from the result, so pass/fail
+prints immediately and the process exits once teardown finishes.
+
+Unlike the attached `studio` backend, `--coverage` works here: studio-cli opens
+the Coverage-Instrumented Place instead of the Clean Place, so the report
+universe, thresholds, reporters, and exclusions behave identically to the
+open-cloud backend (including the all-files semantics where an untested included
+file reports **0%** and fails `coverageThreshold`).
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> studio-cli is a local-developer convenience backend (it needs a logged-in
+> Studio and the installed plugin), not a CI path.
+
 ## Workspace mode
 
 Run tests across multiple packages in a pnpm workspace in a single invocation.
-Open Cloud only — Studio backend is not supported.
-
-> [!NOTE] Package discovery uses one of two sources. By default it reads
+Works on every backend: Open Cloud (fans packages across parallel tasks),
+`studio-cli` (one self-launched Studio process drives every package, no
+sharding), and the attached `studio` backend (runs the workspace inside an open
+Studio — handy for debugging the flow). `studio-cli` is serial, so
+`--parallel > 1` is rejected with `--workspace`.
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> Package discovery uses one of two sources. By default it reads
 > `pnpm-workspace.yaml` at the workspace root. Alternatively, declare a
 > `workspace` block in your jest config (see
 > [Workspaces without pnpm](#workspaces-without-pnpm)) to enumerate packages by
@@ -440,8 +502,10 @@ project) under `.jest-roblox/output/`.
 
 | Flag                             | What it does                                                                                                |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `--backend <type>`               | Choose `auto`, `open-cloud`, or `studio`                                                                    |
+| `--backend <type>`               | Choose `auto`, `open-cloud`, `studio`, or `studio-cli`                                                      |
 | `--port <n>`                     | WebSocket port for Studio                                                                                   |
+| `--studioPath <path>`            | Roblox Studio executable for `studio-cli` (auto-detected if unset)                                          |
+| `--headed`                       | Show the Studio window during the run (`studio-cli` only; default: hidden)                                  |
 | `--config <path>`                | Path to config file                                                                                         |
 | `--testPathPattern <regex>`      | Filter test files by path                                                                                   |
 | `-t, --testNamePattern <regex>`  | Filter tests by name                                                                                        |
@@ -486,7 +550,9 @@ project) under `.jest-roblox/output/`.
 5. Maps Luau line numbers to TypeScript via source maps (roblox-ts only)
 6. Prints results
 
-> [!NOTE] Coverage adds extra steps: copy Luau files, insert tracking probes,
+<!-- prettier-ignore -->
+> [!NOTE]
+> Coverage adds extra steps: copy Luau files, insert tracking probes,
 > build a separate place file, then map hit counts back to source. For
 > roblox-ts, this goes through source maps to report TypeScript lines.
 

package/bin/jest-roblox.js

@@ -1,17 +1,16 @@
 #!/usr/bin/env node
 import { existsSync } from "node:fs";
+import { registerHooks } from "node:module";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { load, resolve as resolveLuau } from "../loaders/luau-raw.mjs";
+
 const sourceEntry = resolve(dirname(fileURLToPath(import.meta.url)), "../src/cli.ts");
 
-const { register } = await import("node:module");
-register("../loaders/luau-raw.mjs", import.meta.url);
+registerHooks({ load, resolve: resolveLuau });
 
-if (existsSync(sourceEntry)) {
-	const { main } = await import("../src/cli.ts");
-	await main();
-} else {
-	const { main } = await import("../dist/cli.mjs");
-	await main();
-}
+const { main } = existsSync(sourceEntry)
+	? await import("../src/cli.ts")
+	: await import("../dist/cli.mjs");
+await main();

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { t as CliOptions } from "./schema-CCF2E3k_.mjs";
+import { t as CliOptions } from "./schema-i-pZhLCV.mjs";
 
 //#region src/cli.d.ts
 declare function parseArgs(args: Array<string>): CliOptions;

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { $ as loadConfig, D as outputMultiResult, H as formatBanner, O as outputSingleResult, P as parseGameOutput, Q as mergeCliWithConfig, Y as LuauScriptError, dt as version, f as formatMissingScopes, lt as isValidBackend, n as runJestRoblox, ot as VALID_BACKENDS, p as walkErrorChain, ut as ConfigError } from "./run-Bh8G33J1.mjs";
+import { B as parseGameOutput, J as formatBanner, N as outputMultiResult, P as outputSingleResult, bt as version, ct as loadConfig, ht as VALID_BACKENDS, n as runJestRoblox, st as mergeCliWithConfig, tt as LuauScriptError, v as formatMissingScopes, vt as isValidBackend, y as walkErrorChain, yt as ConfigError } from "./run-BM5sqclu.mjs";
 import { OpenCloudError } from "@bedrock-rbx/ocale";
 import process from "node:process";
 import { parseArgs as parseArgs$1 } from "node:util";
@@ -9,8 +9,13 @@ const HELP_TEXT = `
 Usage: jest-roblox [options] [files...]
 
 Options:
-  --backend <type>                  Backend: "auto", "open-cloud", or "studio" (default: auto)
+  --backend <type>                  Backend: "auto", "open-cloud", "studio", or
+                                    "studio-cli" (default: auto)
   --port <number>                   WebSocket port for studio backend (default: 3001)
+  --studioPath <path>               Roblox Studio executable for the studio-cli
+                                    backend (auto-detected if not set)
+  --headed                          Show the Studio window during the run
+                                    (studio-cli backend only; default: hidden)
   --config <path>                   Path to config file
   --testPathPattern <regex>         Filter test files by path pattern
   -t, --testNamePattern <regex>     Filter tests by name pattern
@@ -96,6 +101,7 @@ function parseArgs(args) {
 				type: "string"
 			},
 			"gameOutput": { type: "string" },
+			"headed": { type: "boolean" },
 			"help": {
 				default: false,
 				type: "boolean"
@@ -126,6 +132,7 @@ function parseArgs(args) {
 			"showLuau": { type: "boolean" },
 			"silent": { type: "boolean" },
 			"sourceMap": { type: "boolean" },
+			"studioPath": { type: "string" },
 			"testNamePattern": {
 				short: "t",
 				type: "string"
@@ -166,6 +173,7 @@ function parseArgs(args) {
 		files: positionals.length > 0 ? positionals : void 0,
 		formatters: values.formatters,
 		gameOutput: values.gameOutput,
+		headed: values.headed,
 		help: values.help,
 		outputFile: values.outputFile,
 		packages: values.packages,
@@ -180,6 +188,7 @@ function parseArgs(args) {
 		showLuau: values["no-show-luau"] === true ? false : values.showLuau,
 		silent: values.silent,
 		sourceMap: values.sourceMap,
+		studioPath: values.studioPath,
 		testNamePattern: values.testNamePattern,
 		testPathPattern: values.testPathPattern,
 		timeout,
@@ -206,6 +215,7 @@ async function main() {
 	process.exitCode = await run(process.argv.slice(2));
 }
 const PARALLEL_FLAG = "--parallel";
+const IntegerLikePattern = /^-?\d+$/;
 function normalizeParallelFlag(args) {
 	const out = [];
 	for (let index = 0; index < args.length; index++) {
@@ -215,7 +225,7 @@ function normalizeParallelFlag(args) {
 			continue;
 		}
 		const next = args[index + 1];
-		if (next !== void 0 && !next.startsWith("-") && (next === "auto" || /^-?\d+$/.test(next))) {
+		if (next !== void 0 && !next.startsWith("-") && (next === "auto" || IntegerLikePattern.test(next))) {
 			out.push(PARALLEL_FLAG, next);
 			index += 1;
 		} else out.push(PARALLEL_FLAG, "auto");

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { _ as SnapshotFormatOptions, a as DisplayName, b as defineProject, c as GlobalTestConfig, d as ProjectEntry, f as ProjectTestConfig, g as SharedTestConfig, h as SHARED_TEST_KEYS, i as DEFAULT_CONFIG, l as InlineProjectConfig, m as ResolvedConfig, n as Config, o as FormatterEntry, p as ROOT_CLI_KEYS, r as ConfigInput, s as GLOBAL_TEST_KEYS, t as CliOptions, u as JEST_ARGV_EXCLUDED_KEYS, v as WorkspaceConfig, x as TypecheckConfig, y as defineConfig } from "./schema-CCF2E3k_.mjs";
+import { _ as SnapshotFormatOptions, a as DisplayName, b as defineProject, c as GlobalTestConfig, d as ProjectEntry, f as ProjectTestConfig, g as SharedTestConfig, h as SHARED_TEST_KEYS, i as DEFAULT_CONFIG, l as InlineProjectConfig, m as ResolvedConfig, n as Config, o as FormatterEntry, p as ROOT_CLI_KEYS, r as ConfigInput, s as GLOBAL_TEST_KEYS, t as CliOptions, u as JEST_ARGV_EXCLUDED_KEYS, v as WorkspaceConfig, x as TypecheckConfig, y as defineConfig } from "./schema-i-pZhLCV.mjs";
 import { type } from "arktype";
 import { StorageClient } from "@bedrock-rbx/ocale/storage";
 import { WebSocket, WebSocketServer } from "ws";
@@ -106,6 +106,44 @@ interface CoverageArtifacts {
 }
 declare function readBuildManifest(filePath: string, options?: ReadBuildManifestOptions): ReadBuildManifestResult;
 //#endregion
+//#region src/artifacts/build-coverage-place.d.ts
+/**
+* Everything a caller (a Node-only "Machine A") needs after producing the
+* coverage-instrumented place offline, without executing any suite: the built
+* place (`coveragePlace.path` + content hash) and the paths of the sibling
+* manifests it shares a `buildId` with. The place is left on disk for the caller
+* to copy to the run machine — it is never cleaned.
+*/
+interface CoveragePlaceBundle {
+  buildId: string;
+  /** The always-on build record's path (`build-manifest.json`). */
+  buildManifestPath: string;
+  /** The coverage-data sibling manifest's path (`coverage-manifest.json`). */
+  coverageManifestPath: string;
+  /** The instrumented place: cwd-relative path + SHA-256 of its bytes. */
+  coveragePlace: BuildManifestArtifact;
+  /** Per-project DataModel paths baked into the place. */
+  projects: Array<BuildManifestProject>;
+  /** `false` on the incremental no-change reuse path (place was not rebuilt). */
+  rebuilt: boolean;
+}
+/**
+* Build the coverage-instrumented place **without running it** — the offline
+* half of the split producer. Instruments (incrementally) and rojo-builds the
+* place, bakes each project's `jest.config` stub into it so any runner that
+* opens the place can discover and run the suite unaided, publishes the sibling
+* Build + Coverage manifests, and hands back the place. No backend is resolved,
+* no suite executes, nothing hits the network. Coverage collection is forced on
+* regardless of the input config.
+*
+* The counterpart to `prepareArtifacts`, minus the run and the Clean Place —
+* the entry point for a machine that cannot execute Roblox at all. It shares the
+* `prepareBakedCoverage` seam with the run path but always bakes stubs (the run
+* path skips baking for studio-cli, which injects configs at runtime), because a
+* place handed to a foreign runner must be self-contained.
+*/
+declare function buildCoveragePlace(config: ResolvedConfig): Promise<CoveragePlaceBundle>;
+//#endregion
 //#region src/coverage-pipeline/types.d.ts
 /**
 * Raw hit counts for a single file, keyed by statement/function index.
@@ -352,7 +390,16 @@ interface Backend {
   readonly kind: BackendKind;
   runTests(options: BackendOptions): Promise<BackendResult>;
 }
-type BackendKind = "open-cloud" | "studio";
+type BackendKind = "open-cloud" | "studio" | "studio-cli";
+/**
+* Whether this is a workspace (multi-package) run. Workspace jobs each carry
+* their owning package name (`pkg`); single-/multi-project jobs never do, and
+* the run layer builds them all-or-none — so any job with `pkg` means the whole
+* run is a workspace run. The Studio backends key off this to drive the plugin's
+* staged-materializer dispatch (`workspace.entries`) instead of the configs
+* path. `buildWorkspaceEntries` then fails fast if a job is missing `pkg`, so a
+* malformed (mixed) array surfaces as a clear error rather than a bad payload.
+*/
 //#endregion
 //#region packages/roblox-runner/dist/index.d.mts
 //#endregion
@@ -423,6 +470,154 @@ declare class OpenCloudBackend implements Backend {
 }
 declare function createOpenCloudBackend(credentials: OpenCloudCredentials): OpenCloudBackend;
 //#endregion
+//#region src/staging/synthesizer.d.ts
+interface StubMount {
+  absStubPath: string;
+  dataModelPath: string;
+}
+interface CoverageRoot {
+  /** Path relative to `packageDirectory` that points at the original luau root. */
+  luauRoot: string;
+  /** Absolute path to the instrumented shadow directory for the same root. */
+  shadowDir: string;
+}
+interface PackageDescriptor {
+  name: string;
+  /**
+  * Per-package `coverageCache` opt-out, forwarded to
+  * `prepareWorkspaceCoverage` so the cache gate honors each package's own
+  * declaration. Not read by synthesis itself.
+  */
+  coverageCache?: boolean;
+  /**
+  * Per-package coverage ignore patterns, forwarded to
+  * `prepareWorkspaceCoverage` so the matcher reflects the merged pkgConfig
+  * instead of the workspace-root default. Not read by synthesis itself.
+  */
+  coveragePathIgnorePatterns?: Array<string>;
+  /**
+  * When set, $path entries that fall inside any listed `luauRoot` are
+  * redirected to the corresponding `shadowDir` so the synthesized place
+  * picks up instrumented sources for this package only. Packages without
+  * `coverageRoots` use their original $path entries unchanged.
+  */
+  coverageRoots?: Array<CoverageRoot>;
+  /**
+  * Per-package `luauRoots`, forwarded to `prepareWorkspaceCoverage` so the
+  * short-circuit honors the user-listed source dirs. Not read by synthesis
+  * itself.
+  */
+  luauRoots?: Array<string>;
+  packageDirectory: string;
+  rojoProjectPath: string;
+  stubMounts?: Array<StubMount>;
+}
+//#endregion
+//#region src/staging/place-builder.d.ts
+interface BuildPlaceOptions {
+  /**
+  * Force `ServerScriptService.LoadStringEnabled = true` on the built place.
+  * Used by studio-cli's Clean Place, whose Run-mode runner gates on
+  * LoadString. Forwarded verbatim to {@link synthesize}.
+  */
+  loadStringEnabled?: boolean;
+  packages: Array<PackageDescriptor>;
+  placeFile: string;
+  projectFile: string;
+  wrap?: boolean;
+}
+//#endregion
+//#region src/backends/studio-cli.d.ts
+interface StudioCliLaunchRequest {
+  /** Full Studio CLI argument vector (already absolute paths). */
+  args: Array<string>;
+  /**
+  * Show the Studio window during the run (`--headed`) instead of the default
+  * hidden window. Maps to `windowsHide: !headed` in {@link spawnStudio}.
+  */
+  headed: boolean;
+  /**
+  * Absolute path of the place Studio opens. Used only to clear a stale
+  * `<place>.lock` a previously killed Studio could not remove itself.
+  */
+  placeFile: string;
+  /** Absolute path to the Studio executable. */
+  studioPath: string;
+}
+/**
+* A launched Studio the host can kill once the result arrives (or on timeout).
+* The injected seam: unit tests return a fake that drives a canned result frame
+* over the mock WebSocket server instead of launching Studio.
+*/
+interface StudioCliProcess {
+  /**
+  * Terminate Studio immediately (`TerminateProcess`), skipping graceful
+  * shutdown. Used on every hung/error/timeout path.
+  */
+  kill: () => void;
+  /**
+  * Graceful teardown: wait for Studio to release
+  * `<place>.lock` — which happens only after every edit-mode `BindToClose`
+  * handler ran and `ClosePlace` finished — then terminate it, skipping
+  * Studio's ~30s post-close telemetry drain. Hard-kills anyway after
+  * `graceCapMs` (a long-yielding handler). Returns immediately; the watch runs
+  * in the background, keeping node's event loop alive (the child handle + a
+  * poll timer) until it fires, so the CLI prints results now and the process
+  * exits once teardown completes. The caller closes the result server first,
+  * which is what lets the bootstrap return and `--quitAfterExecution` begin
+  * the graceful close.
+  */
+  killOnLockRelease: (graceCapMs: number) => void;
+  /** Subscribe to a spawn failure (e.g. a bad `studioPath`). */
+  onError: (listener: (error: Error) => void) => void;
+}
+/** Spawns Studio and returns the handle the host kills. */
+type StudioCliLauncher = (request: StudioCliLaunchRequest) => StudioCliProcess;
+interface StudioCliOptions {
+  /** Place Builder seam; defaults to the real {@link defaultBuildPlace}. */
+  buildPlace?: (options: BuildPlaceOptions) => BuildManifestArtifact;
+  /** Result-server factory seam; defaults to an ephemeral-port `ws` server. */
+  createServer?: () => WebSocketServer;
+  /** Studio-executable resolver seam; defaults to {@link discoverStudioPath}. */
+  discover?: (override: string | undefined) => string;
+  /**
+  * Backstop for the graceful teardown: hard-kill if `<place>.lock` isn't
+  * released within this many ms. Defaults to {@link GRACEFUL_SHUTDOWN_CAP_MS}.
+  */
+  gracefulShutdownTimeout?: number;
+  /**
+  * Show the Studio window during the run (`--headed`). CLI-only — never read
+  * from config. Defaults to false (hidden window).
+  */
+  headed?: boolean;
+  /** Process launcher seam; defaults to the real {@link spawnStudio}. */
+  launch?: StudioCliLauncher;
+  /** Explicit Studio executable path (override from config / CLI / env). */
+  studioPath?: string;
+  /** Run timeout in milliseconds. Defaults to 300000. */
+  timeout?: number;
+}
+declare class StudioCliBackend implements Backend {
+  private readonly buildPlace;
+  private readonly createServer;
+  private readonly discover;
+  private readonly gracefulShutdownTimeout;
+  private readonly headed;
+  private readonly launch;
+  private readonly studioPath?;
+  private readonly timeout;
+  readonly kind = "studio-cli";
+  constructor(options?: StudioCliOptions);
+  runTests(options: BackendOptions): Promise<BackendResult>;
+  /**
+  * Build the Clean Place for a normal (non-coverage) run and return its path.
+  * `loadStringEnabled` is forced on so the Run-mode runner's LoadString gate
+  * passes. Coverage runs skip this and open the instrumented place instead.
+  */
+  private buildCleanPlace;
+}
+declare function createStudioCliBackend(options?: StudioCliOptions): StudioCliBackend;
+//#endregion
 //#region src/backends/studio.d.ts
 interface PreConnected {
   server: WebSocketServer;
@@ -604,6 +799,40 @@ type ReadManifestResult = ParsedManifest<CoverageManifest>;
 declare const manifestSchema: type<CoverageManifest>;
 declare function readManifest(filePath: string): ReadManifestResult;
 //#endregion
+//#region src/coverage-pipeline/merge-raw-coverage.d.ts
+/**
+* Additively merge two raw coverage datasets. Overlapping files have their
+* hit counts summed (matching istanbul-lib-coverage's semantics).
+*/
+declare function mergeRawCoverage(target: RawCoverageData | undefined, source: RawCoverageData | undefined): RawCoverageData | undefined;
+//#endregion
+//#region src/coverage-pipeline/raw-coverage.d.ts
+/**
+* Normalize a raw coverage table into typed {@link RawCoverageData}. The input
+* is the per-file hit table the coverage probes accumulate at runtime — the
+* `_G.__jest_roblox_cov` global, or the `_coverage` field of a run envelope —
+* keyed by the stable per-file join key (`fileKey`). Luau serializes the
+* `s`/`f` counters as 1-based arrays and `b` as an array of arrays; this
+* canonicalizes them to string-keyed records while leaving the fileKey verbatim
+* (it is the byte-identical join key the static maps are also keyed to). Returns
+* `undefined` when the input is not an object or carries no file with a
+* statement map.
+*/
+declare function normalizeRawCoverage(coverage: unknown): RawCoverageData | undefined;
+/**
+* Extract raw coverage from a completed run's result envelope — the companion
+* seam for a run this CLI did not launch. Accepts the plugin's `jestOutput`
+* (a JSON string or an already-parsed object), or the bare `_G.__jest_roblox_cov`
+* table read straight off the run. When an object carries a `_coverage` field it
+* is used; otherwise the object is treated as the hit table itself. Returns
+* `undefined` for malformed JSON or an envelope with no coverage.
+*
+* A multi-project result (`{ entries: [{ jestOutput }, …] }`) carries one
+* envelope per project; parse each `entries[i].jestOutput` and combine with
+* `mergeRawCoverage`.
+*/
+declare function parseCoverageEnvelope(output: unknown): RawCoverageData | undefined;
+//#endregion
 //#region src/coverage-pipeline/attribution.d.ts
 interface AttributionResult {
   /** Per Luau file: statement id → ids of the tests that covered it. */
@@ -942,6 +1171,16 @@ interface MappedCoverageResult {
   files: Record<string, MappedFileCoverage>;
 }
 //#endregion
+//#region src/coverage-pipeline/agent-table-filter.d.ts
+/**
+* Decides whether a single coverage-universe source file is shown in the agent
+* **text table**. Receives a normalized-absolute source path (see
+* {@link narrowMappedForAgentTable}). This is a display-only narrowing layered
+* on top of `filterCoverageUniverse`: thresholds, the totals line, and the
+* lcov/html/json artifacts always keep the full universe.
+*/
+type CoverageDisplayPredicate = (normalizedAbsolutePath: string) => boolean;
+//#endregion
 //#region src/run/types.d.ts
 type RunMode = "multi" | "single" | "workspace";
 interface ProjectResult {
@@ -961,6 +1200,13 @@ interface SingleRunResult {
   * place set it has.
   */
   coverageArtifacts?: CoverageArtifacts;
+  /**
+  * Narrows the agent coverage **text table** to the directly-filtered source
+  * files on a filtered run (single file / `--testPathPattern`). Display-only:
+  * thresholds, totals, and lcov/html/json keep the full universe. Undefined on
+  * a full run.
+  */
+  coverageDisplayFilter?: CoverageDisplayPredicate;
   mode: "single";
   preCoverageMs: number;
   runtimeResult?: ExecuteResult;
@@ -971,6 +1217,13 @@ interface MultiRunResult {
   collectCoverageFrom?: Array<string>;
   /** Producer record for the entry point to emit a Build Manifest from. */
   coverageArtifacts?: CoverageArtifacts;
+  /**
+  * Narrows the agent coverage **text table** to the directly-filtered source
+  * files on a filtered run (positional files / `--testPathPattern`, or the
+  * selected `--project` scope). Display-only: thresholds, totals, and
+  * lcov/html/json keep the full universe. Undefined on a full run.
+  */
+  coverageDisplayFilter?: CoverageDisplayPredicate;
   merged: MultiProjectMerged;
   mode: "multi";
   preCoverageMs: number;
@@ -1427,4 +1680,4 @@ declare function visitExpression(expression: AstExpr, visitor: LuauVisitor): voi
 declare function visitStatement(statement: AstStat, visitor: LuauVisitor): void;
 declare function visitBlock(block: AstStatBlock, visitor: LuauVisitor): void; //#endregion
 //#endregion
-export { type ArtifactBundle, type AstExpr, type AstExprBinary, type AstExprCall, type AstExprFunction, type AstStat, type AstStatBlock, BUILD_MANIFEST_VERSION, type Backend, type BackendOptions, type BuildManifest, type BuildManifestArtifact, type BuildManifestFileRecord, type BuildManifestProject, type CliOptions, type Config, type ConfigInput, type CoverageManifest, DEFAULT_CONFIG, type DisplayName, type ExecuteResult, type FormatOutputOptions, type FormatterEntry, GLOBAL_TEST_KEYS, type GameOutputEntry, type GitHubActionsFormatterOptions, type GlobalTestConfig, type InlineProjectConfig, type InstrumentedFileRecord, JEST_ARGV_EXCLUDED_KEYS, type JestArgv, type JestResult, type LuauSpan, type LuauVisitor, MANIFEST_VERSION, type MultiProjectMerged, type MultiRunResult, type NonInstrumentedFileRecord, OpenCloudBackend, type ProjectEntry, type ProjectInput, type ProjectResult, type ProjectTestConfig, ROOT_CLI_KEYS, type ReadBuildManifestOptions, type ReadBuildManifestResult, type ReadManifestResult as ReadCoverageManifestResult, type ResolvedConfig, type ResolvedProjectConfig, type RunMode, type RunOptions, type RunProjectsOptions, type RunProjectsResult, type RunResult, SHARED_TEST_KEYS, type SharedTestConfig, type SingleRunResult, StudioBackend, type TestCaseResult, type TestDefinition, type TestFileResult, type TestRecord, type TestStatus, type TscErrorInfo, type TypecheckOptions, type WorkspaceConfig, type WorkspaceRunResult, buildJestArgv, buildManifestSchema, manifestSchema as coverageManifestSchema, createOpenCloudBackend, createStudioBackend, defineConfig, defineProject, extractJsonFromOutput, formatAnnotations, formatExecuteOutput, formatFailure, formatGameOutputNotice, formatJobSummary, formatJson, formatResult, formatTestSummary, generateTestScript, hashFile, loadConfig, parseGameOutput, parseJestOutput, prepareArtifacts, readBuildManifest, readManifest as readCoverageManifest, resolveConfig, runJestRoblox, runProjects, runTypecheck, visitBlock, visitExpression, visitStatement, writeGameOutput, writeJsonFile };
+export { type ArtifactBundle, type AstExpr, type AstExprBinary, type AstExprCall, type AstExprFunction, type AstStat, type AstStatBlock, BUILD_MANIFEST_VERSION, type Backend, type BackendOptions, type BuildManifest, type BuildManifestArtifact, type BuildManifestFileRecord, type BuildManifestProject, type CliOptions, type Config, type ConfigInput, type CoverageManifest, type CoveragePlaceBundle, DEFAULT_CONFIG, type DisplayName, type ExecuteResult, type FormatOutputOptions, type FormatterEntry, GLOBAL_TEST_KEYS, type GameOutputEntry, type GitHubActionsFormatterOptions, type GlobalTestConfig, type InlineProjectConfig, type InstrumentedFileRecord, JEST_ARGV_EXCLUDED_KEYS, type JestArgv, type JestResult, type LuauSpan, type LuauVisitor, MANIFEST_VERSION, type MultiProjectMerged, type MultiRunResult, type NonInstrumentedFileRecord, OpenCloudBackend, type ProjectEntry, type ProjectInput, type ProjectResult, type ProjectTestConfig, ROOT_CLI_KEYS, type RawCoverageData, type RawFileCoverage, type ReadBuildManifestOptions, type ReadBuildManifestResult, type ReadManifestResult as ReadCoverageManifestResult, type ResolvedConfig, type ResolvedProjectConfig, type RunMode, type RunOptions, type RunProjectsOptions, type RunProjectsResult, type RunResult, SHARED_TEST_KEYS, type SharedTestConfig, type SingleRunResult, StudioBackend, StudioCliBackend, type TestCaseResult, type TestDefinition, type TestFileResult, type TestRecord, type TestStatus, type TscErrorInfo, type TypecheckOptions, type WorkspaceConfig, type WorkspaceRunResult, buildCoveragePlace, buildJestArgv, buildManifestSchema, manifestSchema as coverageManifestSchema, createOpenCloudBackend, createStudioBackend, createStudioCliBackend, defineConfig, defineProject, extractJsonFromOutput, formatAnnotations, formatExecuteOutput, formatFailure, formatGameOutputNotice, formatJobSummary, formatJson, formatResult, formatTestSummary, generateTestScript, hashFile, loadConfig, mergeRawCoverage, normalizeRawCoverage, parseCoverageEnvelope, parseGameOutput, parseJestOutput, prepareArtifacts, readBuildManifest, readManifest as readCoverageManifest, resolveConfig, runJestRoblox, runProjects, runTypecheck, visitBlock, visitExpression, visitStatement, writeGameOutput, writeJsonFile };