@quenty/nevermore-cli 4.47.2 → 4.49.0

package/src/utils/open-cloud/open-cloud-client.ts

@@ -13,6 +13,20 @@ import {
   type ParsedTestLogs,
 } from '../testing/test-log-parser.js';
 import { type LogFetchStats } from '../testing/log-fetch-stats.js';
+import { recompressPlace } from '../build/place-recompression.js';
+
+/**
+ * The largest place file the place version endpoint accepts, measured: 150 MiB
+ * exactly uploads, one byte more is refused from `Content-Length` before the
+ * body is sent, as `400 InvalidRequest: "Request upload was interrupted before
+ * completion."` — and somewhere past ~200 MB as `413 Payload Too Large`.
+ * Neither says anything about size, so it is checked here first.
+ *
+ * Not the 100 MB Roblox documents as supported
+ * (https://create.roblox.com/docs/projects/place-files); that is where Studio
+ * saving "might fail", not where the API cuts off.
+ */
+export const PLACE_UPLOAD_MAX_BYTES = 150 * 1024 * 1024;
 
 /**
  * One engine message, with the severity Open Cloud reported for it.
@@ -276,8 +290,20 @@ export class OpenCloudClient {
     );
 
     const apiKey = await this._resolveApiKeyAsync();
-    const fileBuffer = await fs.readFile(rbxlPath);
+    const fileBuffer = _recompressForUpload(
+      rbxlPath,
+      await fs.readFile(rbxlPath)
+    );
     const totalBytes = fileBuffer.length;
+    if (totalBytes > PLACE_UPLOAD_MAX_BYTES) {
+      throw new Error(
+        `Upload failed: ${path.basename(rbxlPath)} is ${_formatMegabytes(
+          totalBytes
+        )}, over the Open Cloud ${_formatMegabytes(
+          PLACE_UPLOAD_MAX_BYTES
+        )} place upload limit`
+      );
+    }
     const versionType = publish ? 'Published' : 'Saved';
     const url = `https://apis.roblox.com/universes/v1/${universeId}/places/${placeId}/versions?versionType=${versionType}`;
 
@@ -1097,3 +1123,34 @@ async function _readBodyWithProgressAsync(
 
   return Buffer.concat(chunks);
 }
+
+/**
+ * The bytes to upload for a place file: recompressed when that is possible,
+ * the file as read when it is not. An upload never fails for want of zstd —
+ * it only goes up larger.
+ */
+function _recompressForUpload(rbxlPath: string, fileBuffer: Buffer): Buffer {
+  const name = path.basename(rbxlPath);
+  const result = recompressPlace(fileBuffer);
+
+  if (result.kind === 'recompressed') {
+    OutputHelper.verbose(
+      `Recompressed ${name}: ${_formatMegabytes(
+        result.originalBytes
+      )} -> ${_formatMegabytes(result.data.length)}`
+    );
+  } else if (result.kind === 'unsupported') {
+    OutputHelper.warn(
+      `Uploading ${name} as built (${_formatMegabytes(
+        fileBuffer.length
+      )}) without recompressing it: ${result.reason}`
+    );
+  }
+
+  return result.data;
+}
+
+/** In Roblox's MB, which are 1024 * 1024 bytes. */
+function _formatMegabytes(bytes: number): string {
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}

package/src/utils/testing/batch-run.e2e.test.ts

@@ -14,12 +14,13 @@
  * read and on what each package's result came out as.
  */
 
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { OutputHelper } from '@quenty/cli-output-helpers';
 import { BatchScriptJobContext } from '../job-context/batch-script-job-context.js';
 import {
   type BuiltPlace,
   type Deployment,
+  type DeployPlaceOptions,
   type JobContext,
   type JobLogs,
   type RunScriptOptions,
@@ -29,19 +30,33 @@ import { type TaskLogMessage } from '../open-cloud/open-cloud-client.js';
 import { type BatchTarget } from '../batch/changed-packages-utils.js';
 import { renderBatchOutcome } from './parsers/batch-log-renderer.js';
 
-const { SLUG_MAP } = vi.hoisted(() => ({
-  SLUG_MAP: new Map([
+const { SLUG_MAP, combined } = vi.hoisted(() => {
+  const SLUG_MAP = new Map([
     ['@quenty/alpha', 'alpha'],
     ['@quenty/beta', 'beta'],
-  ]),
-}));
+  ]);
+  return {
+    SLUG_MAP,
+    // Which packages share a place. One place unless a test splits them.
+    combined: {
+      chunks: [[...SLUG_MAP]] as Array<Array<[string, string]>>,
+    },
+  };
+});
 
 // The only mocked collaborator: building the combined place shells out to rojo
 // and lune, which is a different subject from what this test is about. What it
-// produces that matters downstream is the slug map.
-vi.mock('./runner/combined-project-generator.js', () => ({
+// produces that matters downstream is the slug map, and how it was split.
+vi.mock('./runner/combined-project-generator.js', async (importOriginal) => ({
+  ...(await importOriginal<
+    typeof import('./runner/combined-project-generator.js')
+  >()),
   generateCombinedProjectAsync: vi.fn(async () => ({
-    rbxlPath: '/tmp/batch.rbxl',
+    chunks: combined.chunks.map((entries, index) => ({
+      rbxlPath: `/tmp/batch-${index + 1}.rbxl`,
+      slugMap: new Map(entries),
+      sizeBytes: 1024,
+    })),
     slugMap: SLUG_MAP,
     primaryTarget: { placeId: 1, universeId: 2 },
     buildContext: { cleanupAsync: async () => {} },
@@ -119,11 +134,17 @@ const TASK_MESSAGES: TaskLogMessage[] = [
   { message: SUMMARY_JSON, messageType: 'OUTPUT' },
 ];
 
-/** A transport that runs nothing and reports the messages it was handed. */
+/**
+ * A transport that runs nothing and reports the messages it was handed — or,
+ * with `messagesFor`, the messages for whichever packages the script ran.
+ */
 class FakeTransport implements JobContext {
   public scriptContent?: string;
+  public scriptContents: string[] = [];
+  public deployedPaths: string[] = [];
   public deployCount = 0;
   public runCount = 0;
+  public messagesFor?: (script: string) => TaskLogMessage[];
 
   constructor(
     private readonly _messages: TaskLogMessage[],
@@ -134,8 +155,11 @@ class FakeTransport implements JobContext {
     throw new Error('the batch context builds the combined place itself');
   }
 
-  async deployBuiltPlaceAsync(): Promise<Deployment> {
+  async deployBuiltPlaceAsync(
+    options: DeployPlaceOptions
+  ): Promise<Deployment> {
     this.deployCount++;
+    this.deployedPaths.push(options.builtPlace.rbxlPath);
     return {};
   }
 
@@ -145,6 +169,7 @@ class FakeTransport implements JobContext {
   ): Promise<ScriptRunResult> {
     this.runCount++;
     this.scriptContent = options.scriptContent;
+    this.scriptContents.push(options.scriptContent);
     return {
       success: true,
       taskState: 'COMPLETE',
@@ -153,15 +178,17 @@ class FakeTransport implements JobContext {
   }
 
   async getLogsAsync(): Promise<JobLogs> {
-    const text = this._messages.map((m) => m.message).join('\n');
+    const messages =
+      this.messagesFor?.(this.scriptContent ?? '') ?? this._messages;
+    const text = messages.map((m) => m.message).join('\n');
     return {
       text,
-      messages: this._messages,
+      messages,
       stats: {
         requests: 1,
         pages: 1,
         entries: 1,
-        messages: this._messages.length,
+        messages: messages.length,
         chars: text.length,
       },
     };
@@ -210,6 +237,10 @@ async function runPackageAsync(
 }
 
 describe('an aggregated batch run, end to end', () => {
+  beforeEach(() => {
+    combined.chunks = [[...SLUG_MAP]];
+  });
+
   it('renders the whole run: every line, in order, grouped and titled', async () => {
     const { batch } = createBatch();
 
@@ -422,4 +453,53 @@ describe('an aggregated batch run, end to end', () => {
     // being scraped out of the section that went missing.
     expect(outcome.results.get('@quenty/alpha')?.testCounts?.total).toBe(68);
   });
+
+  it('uploads and runs each place of a split batch, and merges what they report', async () => {
+    combined.chunks = [
+      [['@quenty/alpha', 'alpha']],
+      [['@quenty/beta', 'beta']],
+    ];
+    const { batch, transport } = createBatch();
+    // Each place prints only the sections and summary of its own packages.
+    transport.messagesFor = (script) => {
+      const slug = script.includes('["alpha"]') ? 'alpha' : 'beta';
+      const entry = SUMMARY_ENTRIES.find((e) => e.slug === slug)!;
+      const verdict = entry.success ? 'PASS' : 'FAIL';
+      return [
+        { message: `===BATCH_TEST_BEGIN ${slug}===`, messageType: 'OUTPUT' },
+        {
+          message: `===BATCH_TEST_END ${slug} ${verdict} ${entry.durationMs}===`,
+          messageType: 'OUTPUT',
+        },
+        { message: '===BATCH_TEST_SUMMARY===', messageType: 'OUTPUT' },
+        { message: JSON.stringify([entry]), messageType: 'OUTPUT' },
+      ];
+    };
+
+    const outcome = await batch.getExecutionOutcomeAsync();
+    const alpha = await runPackageAsync(batch, '@quenty/alpha');
+    const beta = await runPackageAsync(batch, '@quenty/beta');
+
+    expect(transport.deployedPaths).toEqual([
+      '/tmp/batch-1.rbxl',
+      '/tmp/batch-2.rbxl',
+    ]);
+    expect(transport.runCount).toBe(2);
+    expect(transport.scriptContents[0]).toContain('["alpha"]');
+    expect(transport.scriptContents[1]).toContain('["beta"]');
+
+    expect(alpha.success).toBe(true);
+    expect(alpha.testResults).toMatchObject({ passed: 68, total: 68 });
+    expect(beta.success).toBe(false);
+    expect(beta.testResults).toMatchObject({ passed: 3, failed: 1 });
+    expect(outcome.stats?.requests).toBe(2);
+    expect(
+      renderBatchOutcome(outcome, { useGroups: true, color: false })
+    ).toEqual(
+      expect.arrayContaining([
+        '::group::@quenty/alpha - ✅ Passed (68/68) (1.5s)',
+        '::group::@quenty/beta - ❌ FAILED (3/4) (900ms)',
+      ])
+    );
+  });
 });

package/src/utils/testing/runner/combined-project-generator.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { partitionBySize } from './combined-project-generator.js';
+
+describe('partitionBySize', () => {
+  const identity = (n: number) => n;
+
+  it('keeps everything in one group when it fits', () => {
+    expect(partitionBySize([10, 20, 30], identity, 60)).toEqual([[10, 20, 30]]);
+  });
+
+  it('starts a new group, in order, before the budget would be exceeded', () => {
+    expect(partitionBySize([40, 30, 20, 50, 10], identity, 60)).toEqual([
+      [40],
+      [30, 20],
+      [50, 10],
+    ]);
+  });
+
+  it('gives an item over the budget a group of its own', () => {
+    expect(partitionBySize([10, 100, 10], identity, 60)).toEqual([
+      [10],
+      [100],
+      [10],
+    ]);
+  });
+
+  it('returns no groups for no items', () => {
+    expect(partitionBySize([], identity, 60)).toEqual([]);
+  });
+});

package/src/utils/testing/runner/combined-project-generator.ts

@@ -7,11 +7,32 @@ import {
 import { OutputHelper } from '@quenty/cli-output-helpers';
 import { type DeployTarget } from '@quenty/nevermore-deploy';
 import { type BatchTarget } from '../../batch/changed-packages-utils.js';
+import { recompressPlace } from '../../build/place-recompression.js';
 
-export interface CombinedProjectResult {
-  /** Absolute path to the combined .rbxl file. */
+/**
+ * Budget for one combined place, as uploaded (recompressed). Under the upload
+ * limit (`PLACE_UPLOAD_MAX_BYTES`), and under the 100 MB Roblox documents as
+ * supported, since split places run in parallel and cost little.
+ */
+export const DEFAULT_MAX_CHUNK_BYTES = 90 * 1024 * 1024;
+
+/** One combined place: the packages that are uploaded and executed together. */
+export interface CombinedPlaceChunk {
+  /** Absolute path to this chunk's combined .rbxl file. */
   rbxlPath: string;
-  /** batchTarget.name → ServerScriptService slug mapping. */
+  /** batchTarget.name → ServerScriptService slug, for this chunk's packages only. */
+  slugMap: Map<string, string>;
+  /** Size on disk — recompressed whenever the batch has a size budget. */
+  sizeBytes: number;
+}
+
+export interface CombinedProjectResult {
+  /**
+   * The combined places, in package order. Usually one; more when even
+   * recompressed the packages together exceed the per-upload budget.
+   */
+  chunks: CombinedPlaceChunk[];
+  /** batchTarget.name → ServerScriptService slug mapping, across every chunk. */
   slugMap: Map<string, string>;
   /** First batch target's deploy target (provides placeId/universeId for upload). */
   primaryTarget: DeployTarget;
@@ -35,26 +56,36 @@ export interface CombinedBuildProgress {
 
 /** Per-package build info collected during phase 1. */
 interface PackageBuildInfo {
+  name: string;
   slug: string;
   rbxlPath: string;
   scriptPath: string;
+  sizeBytes: number;
 }
 
 /**
- * Build a combined .rbxl containing all testable packages.
+ * Build combined .rbxl files containing all testable packages.
  *
  * Two-phase approach to avoid rojo's symlink deduplication:
  *   Phase 1: Build each package's .rbxl individually via rojo
- *   Phase 2: Use Lune to merge the individual builds into a single .rbxl
+ *   Phase 2: Use Lune to merge the individual builds into one place, split
+ *            into more only if it measures over `maxChunkBytes`
  */
 export async function generateCombinedProjectAsync(options: {
   batchTargets: BatchTarget[];
   repoRoot: string;
   batchPlaceId?: number;
   batchUniverseId?: number;
+  maxChunkBytes?: number;
   progress?: CombinedBuildProgress;
 }): Promise<CombinedProjectResult> {
-  const { batchTargets, batchPlaceId, batchUniverseId, progress } = options;
+  const {
+    batchTargets,
+    batchPlaceId,
+    batchUniverseId,
+    maxChunkBytes = DEFAULT_MAX_CHUNK_BYTES,
+    progress,
+  } = options;
 
   if (batchTargets.length === 0) {
     throw new Error(
@@ -116,50 +147,187 @@ export async function generateCombinedProjectAsync(options: {
     }
     const scriptPath = path.resolve(buildTarget.path, target.scriptTemplate);
 
-    builds.push({ slug, rbxlPath, scriptPath });
+    const { size: sizeBytes } = await fs.stat(rbxlPath);
+
+    builds.push({
+      name: buildTarget.name,
+      slug,
+      rbxlPath,
+      scriptPath,
+      sizeBytes,
+    });
   }
 
   // ── Phase 2: Merge via Lune ──
 
-  const combinedRbxlPath = buildContext.resolvePath('batch-test.rbxl');
   const luneScriptPath = resolvePackagePath(
     import.meta.url,
     'build-scripts',
     'combine-test-places.lua'
   );
 
-  // Build args: <outputPath> <slug1> <rbxl1> <script1> <slug2> <rbxl2> <script2> ...
-  const luneArgs: string[] = [combinedRbxlPath];
-  for (const build of builds) {
-    luneArgs.push(build.slug, build.rbxlPath, build.scriptPath);
-  }
-
-  OutputHelper.verbose(
-    `Merging ${builds.length} targets into combined .rbxl...`
-  );
   progress?.onCombineStart?.();
-  progress?.onStepProgress?.({
-    kind: 'steps',
-    completed: 0,
-    total: builds.length,
-  });
-  await buildContext.executeLuneTransformScriptAsync(
-    luneScriptPath,
-    ...luneArgs
-  );
 
-  OutputHelper.verbose(
-    `Combined ${slugMap.size} targets at ${combinedRbxlPath}`
-  );
+  // One place first, split only if it measures over budget. Sizes do not add
+  // up: recompression dedupes the modules the packages share, so a merge of
+  // many packages costs little more than one, and only measuring it says so.
+  const totalBytes = builds.reduce((sum, b) => sum + b.sizeBytes, 0);
+  let groups = [builds];
+  let chunks: CombinedPlaceChunk[];
+  for (;;) {
+    chunks = await _mergeGroupsAsync(
+      buildContext,
+      luneScriptPath,
+      groups,
+      Number.isFinite(maxChunkBytes),
+      progress
+    );
+
+    const largest = Math.max(...chunks.map((c) => c.sizeBytes));
+    if (largest <= maxChunkBytes || groups.length === builds.length) {
+      break;
+    }
+
+    const groupCount = Math.max(
+      groups.length + 1,
+      Math.ceil((groups.length * largest) / maxChunkBytes)
+    );
+    OutputHelper.info(
+      `Combined place${groups.length === 1 ? ' is' : 's reach'} ` +
+        `${formatMegabytes(largest)}, over the ${formatMegabytes(
+          maxChunkBytes
+        )} per-upload budget — splitting ${builds.length} targets into ` +
+        `about ${groupCount} places.`
+    );
+    groups = partitionBySize(
+      builds,
+      (b) => b.sizeBytes,
+      totalBytes / groupCount
+    );
+  }
 
   return {
-    rbxlPath: combinedRbxlPath,
+    chunks,
     slugMap,
     primaryTarget,
     buildContext,
   };
 }
 
+/**
+ * Merge each group into its own place, recompressed when it will be measured
+ * against a budget — which is also the form it is uploaded in, so the upload
+ * has nothing left to do.
+ */
+async function _mergeGroupsAsync(
+  buildContext: BuildContext,
+  luneScriptPath: string,
+  groups: PackageBuildInfo[][],
+  recompress: boolean,
+  progress: CombinedBuildProgress | undefined
+): Promise<CombinedPlaceChunk[]> {
+  progress?.onStepProgress?.({
+    kind: 'steps',
+    completed: 0,
+    total: groups.length,
+  });
+
+  const chunks: CombinedPlaceChunk[] = [];
+  for (const [index, group] of groups.entries()) {
+    const combinedRbxlPath = buildContext.resolvePath(
+      groups.length === 1 ? 'batch-test.rbxl' : `batch-test-${index + 1}.rbxl`
+    );
+
+    // Build args: <outputPath> <slug1> <rbxl1> <script1> <slug2> <rbxl2> <script2> ...
+    const luneArgs: string[] = [combinedRbxlPath];
+    for (const build of group) {
+      luneArgs.push(build.slug, build.rbxlPath, build.scriptPath);
+    }
+
+    OutputHelper.verbose(
+      `Merging ${group.length} targets into ${path.basename(
+        combinedRbxlPath
+      )}...`
+    );
+    await buildContext.executeLuneTransformScriptAsync(
+      luneScriptPath,
+      ...luneArgs
+    );
+
+    let sizeBytes: number;
+    if (recompress) {
+      const merged = await fs.readFile(combinedRbxlPath);
+      const result = recompressPlace(merged);
+      if (result.kind === 'recompressed') {
+        await fs.writeFile(combinedRbxlPath, result.data);
+      }
+      sizeBytes = result.data.length;
+      OutputHelper.verbose(
+        `Combined ${group.length} targets at ${combinedRbxlPath} ` +
+          `(${formatMegabytes(merged.length)} as built, ` +
+          `${formatMegabytes(sizeBytes)} to upload)`
+      );
+    } else {
+      ({ size: sizeBytes } = await fs.stat(combinedRbxlPath));
+      OutputHelper.verbose(
+        `Combined ${
+          group.length
+        } targets at ${combinedRbxlPath} (${formatMegabytes(sizeBytes)})`
+      );
+    }
+
+    chunks.push({
+      rbxlPath: combinedRbxlPath,
+      slugMap: new Map(group.map((b) => [b.name, b.slug])),
+      sizeBytes,
+    });
+    progress?.onStepProgress?.({
+      kind: 'steps',
+      completed: index + 1,
+      total: groups.length,
+    });
+  }
+
+  return chunks;
+}
+
+/**
+ * Split items, in order, into consecutive groups whose summed size stays within
+ * `maxBytes`. An item larger than the budget on its own gets a group to itself
+ * rather than being dropped — the upload is what reports it as too big.
+ */
+export function partitionBySize<T>(
+  items: T[],
+  sizeOf: (item: T) => number,
+  maxBytes: number
+): T[][] {
+  const groups: T[][] = [];
+  let current: T[] = [];
+  let currentBytes = 0;
+
+  for (const item of items) {
+    const size = sizeOf(item);
+    if (current.length > 0 && currentBytes + size > maxBytes) {
+      groups.push(current);
+      current = [];
+      currentBytes = 0;
+    }
+    current.push(item);
+    currentBytes += size;
+  }
+
+  if (current.length > 0) {
+    groups.push(current);
+  }
+
+  return groups;
+}
+
+/** In Roblox's MB, which are 1024 * 1024 bytes. */
+export function formatMegabytes(bytes: number): string {
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
 /**
  * Extract the slug from a test rojo project.
  * The slug is the first non-`$`, non-`Script` key under ServerScriptService.

package/src/utils/testing/runner/test-runner.test.ts

@@ -102,6 +102,26 @@ describe('runSingleTestAsync', () => {
     });
   }
 
+  it('hands overrides to the build, which owns applying them', async () => {
+    const context = createContext(
+      { success: true, returnValues: [structuredResults()] },
+      PASSING_LOGS
+    );
+    const buildSpy = vi.spyOn(context, 'buildPlaceAsync');
+    const overrides = { placeId: 7, scriptTemplate: 'ServerMain.server.lua' };
+
+    await runSingleTestAsync(context, {
+      packagePath,
+      packageName: 'maid',
+      target: {
+        scriptTemplate: 'ServerMain.server.lua',
+      } as unknown as DeployTarget,
+      overrides,
+    });
+
+    expect(buildSpy.mock.calls[0]![0].overrides).toBe(overrides);
+  });
+
   it('fails a run whose returned results say it failed', async () => {
     // The runner used to announce this by throwing, which failed the task. Now
     // it returns the verdict, and these logs are what a truncated window leaves

package/src/utils/testing/runner/test-runner.ts

@@ -3,6 +3,7 @@ import * as path from 'path';
 import { randomUUID } from 'crypto';
 import { type DeployTarget } from '@quenty/nevermore-deploy';
 import { type JobContext } from '../../job-context/job-context.js';
+import { type DeployOverrides } from '../../build/build.js';
 import {
   type ParsedTestCounts,
   parseTestLogs,
@@ -74,6 +75,8 @@ export interface SingleTestOptions {
    * here (see flattenToBatchTargets) — the runner never picks places[0] itself.
    */
   target: DeployTarget;
+  /** CLI flags that replace the target's universeId, placeId, or scriptTemplate. */
+  overrides?: DeployOverrides;
   timeoutMs?: number;
   /** Luau code to execute directly, bypassing the configured scriptTemplate. */
   scriptText?: string;
@@ -104,6 +107,7 @@ export async function runSingleTestAsync(
     timeoutMs = 300_000,
     scriptText,
     target,
+    overrides,
   } = options;
 
   const sessionId = randomUUID();
@@ -112,6 +116,7 @@ export async function runSingleTestAsync(
     outputFileName: `test-${sessionId}.rbxl`,
     packagePath,
     packageName,
+    overrides,
   });
 
   // Packages that ship or use the manifest get the same deploy-metadata stamp a