@quenty/nevermore-cli 4.51.0 → 4.52.0

package/src/commands/batch-command/batch-deploy-command.ts

@@ -24,7 +24,13 @@ import {
   buildDeployMetadataAttributes,
   gatherGitDeployInfo,
   injectDeployMetadataAsync,
+  type GitDeployInfo,
 } from '../../utils/deploy/deploy-metadata.js';
+import {
+  type PrebuiltDeployBundle,
+  type PrebuiltDeployPlace,
+  readPrebuiltDeployBundleAsync,
+} from '../../utils/deploy/prebuilt-deploy-bundle.js';
 import { OpenCloudClient } from '../../utils/open-cloud/open-cloud-client.js';
 import {
   RateLimiter,
@@ -38,7 +44,7 @@ import {
 import {
   type BatchTarget,
   discoverAllTargetPackagesAsync,
-  discoverChangedTargetPackagesAsync,
+  discoverDeployBatchTargetsAsync,
   flattenToBatchTargets,
 } from '../../utils/batch/changed-packages-utils.js';
 import {
@@ -77,6 +83,8 @@ interface BatchDeployArgs extends NevermoreGlobalArgs {
   watch?: string;
   watchShareApiKey?: boolean;
   watchUseGhAuth?: boolean;
+  bundle?: string;
+  bundleCommit?: string;
 }
 
 export const batchDeployCommand: CommandModule<
@@ -157,6 +165,36 @@ export const batchDeployCommand: CommandModule<
           'Off by default — the key is stored by the service.',
         type: 'boolean',
         default: false,
+      })
+      .option('bundle', {
+        describe:
+          'Deploy the places in a *.nevermore.deploy.tar written by "batch bundle --deploy" instead of ' +
+          'finding and building packages. The bundle only names places: where each one deploys, ' +
+          "and the base place it merges onto, come from this checkout's deploy.nevermore.json.",
+        type: 'string',
+      })
+      .option('bundle-commit', {
+        describe:
+          'Fail unless the --bundle was built from this full commit sha, e.g. the PR head GitHub reports',
+        type: 'string',
+      })
+      .check((args) => {
+        if (args.bundleCommit !== undefined && args.bundle === undefined) {
+          throw new Error('--bundle-commit checks a --bundle; pass one.');
+        }
+        if (args.bundle !== undefined) {
+          if (args.all || args.limit !== undefined) {
+            throw new Error(
+              '--bundle deploys every place in the bundle; drop --all and --limit.'
+            );
+          }
+          if (args.watch !== undefined) {
+            throw new Error(
+              "--bundle deploys another checkout's build, which must not become a watch baseline; drop --watch."
+            );
+          }
+        }
+        return true;
       });
   },
   handler: async (args) => {
@@ -170,18 +208,58 @@ export const batchDeployCommand: CommandModule<
 };
 
 async function _runAsync(args: BatchDeployArgs): Promise<void> {
+  const bundle =
+    args.bundle !== undefined
+      ? await readPrebuiltDeployBundleAsync(args.bundle)
+      : undefined;
+  let exitCode: number;
+  try {
+    exitCode = await _runDeployAsync(args, bundle);
+  } finally {
+    await bundle?.buildContext.cleanupAsync();
+  }
+  process.exit(exitCode);
+}
+
+async function _runDeployAsync(
+  args: BatchDeployArgs,
+  bundle: PrebuiltDeployBundle | undefined
+): Promise<number> {
   const targetName = args.target ?? 'test';
   // Parsed up front so a typo'd duration fails before anything is deployed.
   const watchOption =
     args.watch == null ? undefined : parseWatchOption(args.watch);
 
-  const discovered = args.all
-    ? await discoverAllTargetPackagesAsync(targetName)
-    : await discoverChangedTargetPackagesAsync(args.base!, targetName);
-  let batchTargets = flattenToBatchTargets(discovered);
+  let batchTargets: BatchTarget[];
+  let prebuiltByName: Map<string, PrebuiltDeployPlace> | undefined;
+  if (
+    bundle &&
+    args.bundleCommit !== undefined &&
+    bundle.git.version !== args.bundleCommit
+  ) {
+    throw new Error(
+      `The bundle was built from ${bundle.git.version}, not ${args.bundleCommit}.`
+    );
+  }
+  if (bundle) {
+    ({ batchTargets, prebuiltByName } = await _resolveBundleTargetsAsync(
+      bundle,
+      targetName
+    ));
+  } else {
+    batchTargets = await discoverDeployBatchTargetsAsync({
+      targetName,
+      all: args.all,
+      base: args.base!,
+      limit: args.limit,
+    });
+  }
 
-  if (args.limit && args.limit > 0) {
-    batchTargets = batchTargets.slice(0, args.limit);
+  if (batchTargets.length === 0 && bundle) {
+    OutputHelper.warn(
+      `The bundle holds no places; nothing changed in a "${targetName}" target.`
+    );
+    return 0;
   }
 
   if (batchTargets.length === 0) {
@@ -217,7 +295,7 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
         dryrun: args.dryrun,
       });
     }
-    return;
+    return 0;
   }
 
   if (args.dryrun) {
@@ -247,7 +325,7 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
         dryrun: true,
       });
     }
-    return;
+    return 0;
   }
 
   const concurrency = args.concurrency ?? 3;
@@ -306,7 +384,8 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
   const context = new CloudJobContext(reporter, client, basePlaceResolver);
 
   // Gathered once so every deployed package shares one timestamp and commit.
-  const deployGitInfo = gatherGitDeployInfo();
+  // A bundle's places carry the commit that built them, not this checkout's.
+  const deployGitInfo: GitDeployInfo = bundle?.git ?? gatherGitDeployInfo();
   const deployTimestamp = new Date().toISOString();
 
   await reporter.startAsync();
@@ -319,11 +398,18 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
       reporter,
       bufferOutput: isGrouped,
       executeAsync: async (buildTarget, pkgReporter) => {
+        const prebuilt = prebuiltByName?.get(buildTarget.name);
         const builtPlace = await context.buildPlaceAsync({
           target: buildTarget.target,
           outputFileName: publish ? 'publish.rbxl' : 'deploy.rbxl',
           packagePath: buildTarget.path,
           packageName: buildTarget.name,
+          overrides: prebuilt
+            ? {
+                placeFile: prebuilt.rbxlPath,
+                projectFile: prebuilt.projectPath,
+              }
+            : undefined,
         });
 
         const injected = await injectDeployMetadataAsync(
@@ -336,7 +422,9 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
               timestamp: deployTimestamp,
               universeId: buildTarget.target.universeId,
               placeId: buildTarget.target.placeId,
-              packageVersion: await readPackageVersionAsync(buildTarget.path),
+              packageVersion: prebuilt
+                ? prebuilt.packageVersion
+                : await readPackageVersionAsync(buildTarget.path),
               basePlaceId: buildTarget.target.basePlace?.placeId,
               basePlaceVersion: builtPlace.basePlaceVersion,
             },
@@ -360,6 +448,18 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
         // Eagerly release build artifacts after upload
         await context.releaseBuiltPlaceAsync(builtPlace);
 
+        const deployed = {
+          packageName: buildTarget.name,
+          placeId: buildTarget.target.placeId,
+          universeId: buildTarget.target.universeId,
+          target: targetName,
+          version,
+          published: publish,
+          basePlaceVersion: builtPlace.basePlaceVersion,
+          commit: deployGitInfo.version,
+          branch: deployGitInfo.branch,
+        };
+
         let logs: string;
         if (args.smokeTest && buildTarget.target.basePlace) {
           OutputHelper.verbose('Running post-deploy smoke test...');
@@ -374,8 +474,7 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
           logs = smokeResult.logs;
           if (!smokeResult.success) {
             return {
-              packageName: buildTarget.name,
-              placeId: buildTarget.target.placeId,
+              ...deployed,
               success: false,
               logs: _annotateSmokeTestFailure(logs),
               failureLabel: 'SMOKE TEST FAILED',
@@ -387,8 +486,7 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
         }
 
         return {
-          packageName: buildTarget.name,
-          placeId: buildTarget.target.placeId,
+          ...deployed,
           success: true,
           logs,
           progressSummary: {
@@ -425,7 +523,53 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
   }
 
   await reporter.stopAsync();
-  process.exit(exitCode);
+  return exitCode;
+}
+
+/**
+ * Match each bundled place to this checkout's target of the same name.
+ *
+ * The bundle is untrusted, so it only gets to say which places it built. Place
+ * ids, universe ids and the base place all come from this checkout, which is
+ * what a same-repo PR's run would have used. A place this checkout does not
+ * know — a fork adding a new game — has nowhere trusted to go, so it fails
+ * rather than deploying to ids the fork chose.
+ */
+async function _resolveBundleTargetsAsync(
+  bundle: PrebuiltDeployBundle,
+  targetName: string
+): Promise<{
+  batchTargets: BatchTarget[];
+  prebuiltByName: Map<string, PrebuiltDeployPlace>;
+}> {
+  if (bundle.target !== targetName) {
+    throw new Error(
+      `The bundle was built for the "${bundle.target}" target, not "${targetName}". ` +
+        `Pass --target ${bundle.target}.`
+    );
+  }
+
+  const known = new Map(
+    flattenToBatchTargets(await discoverAllTargetPackagesAsync(targetName)).map(
+      (t) => [t.name, t]
+    )
+  );
+  const unknown = bundle.places
+    .map((p) => p.name)
+    .filter((name) => !known.has(name));
+  if (unknown.length > 0) {
+    throw new Error(
+      `The bundle holds places this checkout has no "${targetName}" target for: ` +
+        `${unknown.join(
+          ', '
+        )}. A new place deploys once its deploy.nevermore.json is on this branch.`
+    );
+  }
+
+  return {
+    batchTargets: bundle.places.map((p) => known.get(p.name)!),
+    prebuiltByName: new Map(bundle.places.map((p) => [p.name, p])),
+  };
 }
 
 /**

package/src/commands/batch-command/batch-test-command.ts

@@ -138,7 +138,7 @@ export const batchTestCommand: CommandModule<
         })
         .option('bundle', {
           describe:
-            'Run the places in a *.nevermore.tests.tar written by "batch bundle" instead of finding ' +
+            'Run the places in a *.nevermore.tests.tar written by "batch bundle --test" instead of finding ' +
             'and building packages. The bundle never chooses where it is uploaded: ' +
             'that is --batch-place-id/--batch-universe-id, or else the test place this ' +
             'checkout gives one of its packages.',
@@ -152,10 +152,14 @@ export const batchTestCommand: CommandModule<
           hidden: true,
           type: 'string',
         })
+        .option('script-file', {
+          hidden: true,
+          type: 'string',
+        })
         .check((args) => {
-          if (args.scriptText !== undefined) {
+          if (args.scriptText !== undefined || args.scriptFile !== undefined) {
             throw new Error(
-              '--script-text is not supported by "batch test", which runs one shared script for all packages.\n' +
+              '--script-text and --script-file are not supported by "batch test", which runs one shared script for all packages.\n' +
                 'Run it against a single package instead:\n' +
                 '  cd <package> && nevermore test --cloud --script-text \'print("hi")\''
             );

package/src/commands/deploy-command/index.ts

@@ -711,6 +711,13 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
           return {
             packageName: buildTarget.name,
             placeId: uploadedTarget.placeId,
+            universeId: uploadedTarget.universeId,
+            target: targetName,
+            version,
+            published: publish,
+            basePlaceVersion: builtPlace.basePlaceVersion,
+            commit: deployGitInfo.version,
+            branch: deployGitInfo.branch,
             success: true,
             logs: `${action} v${version}`,
             progressSummary: {

package/src/commands/test-command/test-command.ts

@@ -1,3 +1,4 @@
+import * as fs from 'fs/promises';
 import * as path from 'path';
 import { Argv, CommandModule } from 'yargs';
 import { OutputHelper } from '@quenty/cli-output-helpers';
@@ -36,6 +37,7 @@ export interface TestProjectArgs extends NevermoreGlobalArgs {
   placeId?: number;
   scriptTemplate?: string;
   scriptText?: string;
+  scriptFile?: string;
   output?: string;
   timeout?: number;
 }
@@ -58,7 +60,7 @@ export class TestProjectCommand<T>
     });
     args.option('logs', {
       describe:
-        'Show execution logs. Defaults on with --script-text, whose output is the whole point of the run',
+        'Show execution logs. Defaults on with --script-text and --script-file, whose output is the whole point of the run',
       type: 'boolean',
     });
     args.option('universe-id', {
@@ -78,6 +80,12 @@ export class TestProjectCommand<T>
       describe:
         'Luau code to execute directly instead of the configured script template',
       type: 'string',
+      conflicts: 'script-file',
+    });
+    args.option('script-file', {
+      describe:
+        'Path to a Luau file to execute directly, like --script-text but without the command line length limit',
+      type: 'string',
     });
     args.option('output', {
       describe: 'Write JSON results to this file',
@@ -98,7 +106,16 @@ export class TestProjectCommand<T>
     // A probe run exists to show its output. Hiding it behind an opt-in flag
     // made --script-text look broken enough that a workaround was written into
     // the docs instead of a bug report.
-    const showLogs = args.logs ?? args.scriptText !== undefined;
+    let scriptText = args.scriptText;
+    if (args.scriptFile !== undefined) {
+      try {
+        scriptText = await fs.readFile(args.scriptFile, 'utf-8');
+      } catch {
+        OutputHelper.error(`Script file not found: ${args.scriptFile}`);
+        process.exit(1);
+      }
+    }
+    const showLogs = args.logs ?? scriptText !== undefined;
     const useSpinner = process.stdout.isTTY && !args.verbose;
 
     const reporter = new CompositeReporter(
@@ -168,7 +185,7 @@ export class TestProjectCommand<T>
             placeId: args.placeId,
             scriptTemplate: args.scriptTemplate,
           },
-          scriptText: args.scriptText,
+          scriptText,
           timeoutMs:
             args.timeout !== undefined ? args.timeout * 1000 : undefined,
         });

package/src/commands/tools-command/ci-post-deploy-results.ts

@@ -49,8 +49,8 @@ export const ciPostDeployResultsCommand: CommandModule<
       .option('run-outcome', {
         describe:
           'Outcome of the deploy step (e.g. "success", "failure"). ' +
-          'When the results file is missing and run-outcome is "success", ' +
-          'posts a neutral "no deploys" comment instead of an error.',
+          'When the results file is missing, "success" posts a neutral comment, ' +
+          '"cancelled" posts nothing, and anything else posts a failure.',
         type: 'string',
       });
   },
@@ -62,6 +62,13 @@ export const ciPostDeployResultsCommand: CommandModule<
       } catch {
         OutputHelper.warn(`Results file not found: ${args.input}`);
 
+        if (args.runOutcome === 'cancelled') {
+          OutputHelper.info(
+            'Deploy step was cancelled; leaving the PR comment to the run that replaced it.'
+          );
+          return;
+        }
+
         const reporters = _createGithubReporters(undefined);
 
         if (args.runOutcome === 'success') {

package/src/commands/tools-command/ci-post-test-results.ts

@@ -59,8 +59,8 @@ export const ciPostTestResultsCommand: CommandModule<
       .option('run-outcome', {
         describe:
           'Outcome of the test step (e.g. "success", "failure"). ' +
-          'When the results file is missing and run-outcome is "success", ' +
-          'posts a neutral "no tests" comment instead of an error.',
+          'When the results file is missing, "success" posts a neutral comment, ' +
+          '"cancelled" posts nothing, and anything else posts a failure.',
         type: 'string',
       })
       .option('sourcemap', {
@@ -78,6 +78,13 @@ export const ciPostTestResultsCommand: CommandModule<
       } catch {
         OutputHelper.warn(`Results file not found: ${args.input}`);
 
+        if (args.runOutcome === 'cancelled') {
+          OutputHelper.info(
+            'Test step was cancelled; leaving the PR comment to the run that replaced it.'
+          );
+          return;
+        }
+
         const reporters = _createGithubReporters(undefined);
 
         if (args.runOutcome === 'success') {

package/src/utils/batch/changed-packages-utils.ts

@@ -126,6 +126,29 @@ export async function discoverChangedTestableBatchTargetsAsync(
   return _requireScriptTemplate(flattenToBatchTargets(packages));
 }
 
+/**
+ * The places `batch deploy` deploys, and `batch bundle --deploy` builds for a
+ * later deploy. One function so the two can never pick different places: a
+ * fork's bundle must hold what a same-repo run would have deployed.
+ */
+export async function discoverDeployBatchTargetsAsync(options: {
+  targetName: string;
+  all?: boolean;
+  base: string;
+  limit?: number;
+}): Promise<BatchTarget[]> {
+  const discovered = options.all
+    ? await discoverAllTargetPackagesAsync(options.targetName)
+    : await discoverChangedTargetPackagesAsync(
+        options.base,
+        options.targetName
+      );
+  const batchTargets = flattenToBatchTargets(discovered);
+  return options.limit && options.limit > 0
+    ? batchTargets.slice(0, options.limit)
+    : batchTargets;
+}
+
 /**
  * Fan a list of TargetPackages out into BatchTargets — one per place. A
  * single-place package produces one BatchTarget with the package name; a

package/src/utils/build/build.ts

@@ -10,6 +10,12 @@ export interface DeployOverrides {
   placeId?: number;
   scriptTemplate?: string;
   placeFile?: string;
+  /**
+   * Rojo project the base place merge grafts by, in place of the target's own.
+   * Set together with `placeFile` when the place was built from a different
+   * checkout, so the merge follows the project that built it.
+   */
+  projectFile?: string;
 }
 
 export interface BuildPlaceOptions {
@@ -35,6 +41,7 @@ export interface BuildPlaceOptions {
   overrides?: DeployOverrides;
   reporter?: Reporter;
   packageName?: string;
+  deferBasePlaceMerge?: boolean;
 }
 
 /**

package/src/utils/bundle/untrusted-tar.ts

@@ -0,0 +1,160 @@
+import { createReadStream, createWriteStream } from 'fs';
+import * as path from 'path';
+import * as tar from 'tar';
+
+// Names reach the bot's PR comment, so a fork's bundle gets no Markdown links,
+// images, URLs, tables or @mentions: only a leading scope `@`, and plain text
+// for a multi-place target's place name ("pkg - Hub (Test)").
+export const PACKAGE_NAME_PATTERN = /^@?[\p{L}\p{N} /()+.,'_~-]{1,200}$/u;
+
+export type BundleKind = 'tests' | 'deploy';
+
+const RUN_COMMANDS: Record<BundleKind, string> = {
+  tests: 'nevermore batch test --bundle <file>',
+  deploy: 'nevermore batch deploy --bundle <file>',
+};
+
+export interface UntrustedTarOptions {
+  kind: BundleKind;
+  /** The one entry read into memory rather than written to `dir`. */
+  manifestName: string;
+  maxManifestBytes: number;
+  /** Every other entry must pass this, by its exact path in the archive. */
+  isEntryAllowed: (name: string) => boolean;
+  maxEntries: number;
+  /** Message for an archive holding more than `maxEntries` entries. */
+  maxEntriesMessage: string;
+  /** Returns an error message when `size` is too large for this entry. */
+  checkEntrySize: (name: string, size: number) => string | undefined;
+}
+
+export interface UntrustedTarContents {
+  manifestText: string;
+  /** Size of each entry written into `dir`, keyed by its archive path. */
+  entrySizes: Map<string, number>;
+}
+
+/**
+ * Read a bundle written by a fork's CI run into `dir`. Entries are read from the
+ * archive, never extracted by it: only regular files whose paths match
+ * `entryPattern` (or are the manifest) are accepted, so a path can never leave
+ * `dir` and a link can never be followed.
+ */
+export async function readUntrustedTarAsync(
+  file: string,
+  dir: string,
+  options: UntrustedTarOptions
+): Promise<UntrustedTarContents> {
+  let manifestText: string | undefined;
+  const entrySizes = new Map<string, number>();
+  const writes: Promise<void>[] = [];
+  let failure: Error | undefined;
+  // Write errors are recorded rather than rejected: the promises are awaited
+  // only once parsing ends, and one rejecting before then is unhandled.
+  const fail = (err: Error) => {
+    failure ??= err;
+  };
+
+  const parser = new tar.Parser({
+    strict: true,
+    onReadEntry: (entry) => {
+      const name = entry.path;
+      const reject = (message: string) => {
+        failure ??= new Error(message);
+        entry.resume();
+      };
+
+      if (entry.type !== 'File' && entry.type !== 'OldFile') {
+        return reject(`Bundle entry ${name} is not a regular file`);
+      }
+
+      if (name === options.manifestName) {
+        if (
+          manifestText !== undefined ||
+          entry.size > options.maxManifestBytes
+        ) {
+          return reject('Bundle has more than one manifest, or one too large');
+        }
+        const parts: Buffer[] = [];
+        entry.on('data', (part: Buffer) => parts.push(part));
+        entry.on('end', () => {
+          manifestText = Buffer.concat(parts).toString('utf-8');
+        });
+        return;
+      }
+
+      if (!options.isEntryAllowed(name) || entrySizes.has(name)) {
+        return reject(`Bundle has an unexpected entry: ${name}`);
+      }
+      if (entrySizes.size >= options.maxEntries) {
+        return reject(options.maxEntriesMessage);
+      }
+      const sizeError = options.checkEntrySize(name, entry.size);
+      if (sizeError) {
+        return reject(sizeError);
+      }
+      entrySizes.set(name, entry.size);
+      writes.push(
+        new Promise<void>((resolve) => {
+          const done = (err?: Error) => {
+            if (err) {
+              fail(err);
+            }
+            resolve();
+          };
+          const out = createWriteStream(path.join(dir, name));
+          out.on('finish', () => done());
+          out.on('error', (err) => {
+            done(err);
+            entry.resume();
+          });
+          entry.on('error', (err: unknown) =>
+            done(err instanceof Error ? err : new Error(String(err)))
+          );
+          entry.pipe(out);
+        })
+      );
+    },
+  });
+
+  await new Promise<void>((resolve, rejectRead) => {
+    const input = createReadStream(file);
+    input.on('error', rejectRead);
+    parser.on('error', (err: Error) =>
+      rejectRead(new Error(`Bundle is not a valid tar file: ${err.message}`))
+    );
+    parser.on('end', () => resolve());
+    input.pipe(parser);
+  });
+  await Promise.all(writes);
+
+  _checkKind(manifestText, options.kind);
+  if (failure) {
+    throw failure;
+  }
+  if (manifestText === undefined) {
+    throw new Error(`Bundle is missing ${options.manifestName}`);
+  }
+  return { manifestText, entrySizes };
+}
+
+function _checkKind(manifestText: string | undefined, expected: BundleKind) {
+  if (manifestText === undefined) {
+    return;
+  }
+  let kind: unknown;
+  try {
+    kind = (JSON.parse(manifestText) as { kind?: unknown })?.kind;
+  } catch {
+    return;
+  }
+  if (kind === undefined || kind === expected) {
+    return;
+  }
+  if (kind === 'tests' || kind === 'deploy') {
+    throw new Error(
+      `This is a ${kind} bundle, not a ${expected} bundle. Run it with "${RUN_COMMANDS[kind]}".`
+    );
+  }
+  throw new Error(`Bundle is of an unknown kind (expected ${expected})`);
+}

package/src/utils/deploy/deploy-github-columns.ts

@@ -6,9 +6,16 @@ import {
   summarizeError,
 } from '@quenty/cli-output-helpers/reporting';
 
-/** Deploy-specific result that extends the generic PackageResult with placeId. */
+/** Deploy-specific result that extends the generic PackageResult with what was deployed where. */
 export interface BatchDeployResult extends PackageResult {
   placeId: number;
+  universeId?: number;
+  target?: string;
+  version?: number;
+  published?: boolean;
+  basePlaceVersion?: number;
+  commit?: string;
+  branch?: string;
 }
 
 /**