@quenty/nevermore-cli 4.51.0 → 4.52.0

package/src/utils/deploy/deploy-metadata.test.ts

@@ -1,9 +1,10 @@
-import { describe, it, expect } from 'vitest';
+import { afterEach, describe, it, expect, vi } from 'vitest';
 import * as fs from 'fs/promises';
 import * as os from 'os';
 import * as path from 'path';
 import {
   buildDeployMetadataAttributes,
+  gatherGitDeployInfo,
   packageUsesManifestAsync,
   type GitDeployInfo,
   type DeployPlaceInfo,
@@ -207,3 +208,51 @@ describe('packageUsesManifestAsync', () => {
     });
   });
 });
+
+describe('gatherGitDeployInfo', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  async function withEventAsync(
+    eventName: string,
+    event: unknown,
+    fn: () => void
+  ): Promise<void> {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'git-info-'));
+    try {
+      const eventPath = path.join(dir, 'event.json');
+      await fs.writeFile(eventPath, JSON.stringify(event));
+      vi.stubEnv('GITHUB_EVENT_NAME', eventName);
+      vi.stubEnv('GITHUB_EVENT_PATH', eventPath);
+      fn();
+    } finally {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  }
+
+  it("stamps a pull_request run with the PR's head, not the merge checkout", async () => {
+    const sha = 'b'.repeat(40);
+    await withEventAsync(
+      'pull_request',
+      { pull_request: { head: { sha, ref: 'feature/x' } } },
+      () => {
+        expect(gatherGitDeployInfo()).toEqual({
+          commit: 'bbbbbbbbbb',
+          version: sha,
+          branch: 'feature/x',
+        });
+      }
+    );
+  });
+
+  it('reads the checkout for any other event', async () => {
+    await withEventAsync(
+      'push',
+      { pull_request: { head: { sha: 'b'.repeat(40), ref: 'feature/x' } } },
+      () => {
+        expect(gatherGitDeployInfo().version).not.toBe('b'.repeat(40));
+      }
+    );
+  });
+});

package/src/utils/deploy/deploy-metadata.ts

@@ -1,4 +1,5 @@
 import { execSync } from 'child_process';
+import { readFileSync } from 'fs';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import {
@@ -53,8 +54,22 @@ export interface GitDeployInfo {
 /**
  * Collect git metadata once per deploy. Every field is best-effort — a missing
  * git binary or a non-repo directory yields an empty object rather than an error.
+ *
+ * A `pull_request` run checks out `refs/pull/N/merge`, a synthetic commit that
+ * exists in neither repo, on a detached HEAD. There the PR's head commit and
+ * branch are read from the event payload instead, so a deployed build traces
+ * back to the commit its checks are reported on.
  */
 export function gatherGitDeployInfo(): GitDeployInfo {
+  const pullRequestHead = _readPullRequestHead();
+  if (pullRequestHead) {
+    return {
+      commit: pullRequestHead.sha.slice(0, 10),
+      version: pullRequestHead.sha,
+      branch: pullRequestHead.ref,
+    };
+  }
+
   const info: GitDeployInfo = {};
   const commit = _git(['rev-parse', '--short', 'HEAD']);
   if (commit) info.commit = commit;
@@ -65,6 +80,30 @@ export function gatherGitDeployInfo(): GitDeployInfo {
   return info;
 }
 
+function _readPullRequestHead(): { sha: string; ref?: string } | undefined {
+  const eventName = process.env.GITHUB_EVENT_NAME;
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  if (
+    !eventPath ||
+    (eventName !== 'pull_request' && eventName !== 'pull_request_target')
+  ) {
+    return undefined;
+  }
+  try {
+    const event = JSON.parse(readFileSync(eventPath, 'utf-8'));
+    const head = event?.pull_request?.head;
+    if (typeof head?.sha !== 'string' || !/^[0-9a-f]{40}$/.test(head.sha)) {
+      return undefined;
+    }
+    return {
+      sha: head.sha,
+      ref: typeof head.ref === 'string' ? head.ref : undefined,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
 /** Per-place facts known at deploy time. */
 export interface DeployPlaceInfo {
   /** Deploy target name from deploy.nevermore.json (e.g. "test", "integration"). */

package/src/utils/deploy/prebuilt-deploy-bundle.test.ts

@@ -0,0 +1,265 @@
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { Header } from 'tar';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  type PrebuiltDeployBundle,
+  readPrebuiltDeployBundleAsync,
+  writePrebuiltDeployBundleAsync,
+} from './prebuilt-deploy-bundle.js';
+
+interface RawEntry {
+  path: string;
+  body?: string;
+  type?: 'File' | 'SymbolicLink';
+  linkpath?: string;
+}
+
+const PROJECT_TEXT = JSON.stringify({ name: 'game', tree: {} });
+const SHA = 'a'.repeat(40);
+
+function rawTar(entries: RawEntry[]): Buffer {
+  const blocks: Buffer[] = [];
+  for (const entry of entries) {
+    const body = Buffer.from(entry.body ?? '');
+    const header = new Header({
+      path: entry.path,
+      type: entry.type ?? 'File',
+      linkpath: entry.linkpath,
+      size: entry.type && entry.type !== 'File' ? 0 : body.length,
+      mode: 0o644,
+      mtime: new Date(0),
+    });
+    header.encode();
+    blocks.push(header.block!);
+    if (!entry.type || entry.type === 'File') {
+      const padded = Buffer.alloc(Math.ceil(body.length / 512) * 512);
+      body.copy(padded);
+      blocks.push(padded);
+    }
+  }
+  blocks.push(Buffer.alloc(1024));
+  return Buffer.concat(blocks);
+}
+
+function validManifest(): any {
+  return {
+    formatVersion: 1,
+    target: 'integration',
+    git: { commit: 'aaaaaaa', version: SHA },
+    places: [
+      {
+        name: '@quenty/integration',
+        file: 'place-1.rbxl',
+        project: 'project-1.json',
+        packageVersion: '1.2.3',
+      },
+    ],
+  };
+}
+
+describe('prebuilt deploy bundle', () => {
+  let workDir: string;
+  const opened: PrebuiltDeployBundle[] = [];
+
+  beforeEach(async () => {
+    workDir = await fs.mkdtemp(path.join(os.tmpdir(), 'deploy-bundle-'));
+  });
+
+  afterEach(async () => {
+    for (const bundle of opened.splice(0)) {
+      await bundle.buildContext.cleanupAsync();
+    }
+    await fs.rm(workDir, { recursive: true, force: true });
+  });
+
+  async function readAsync(file: string) {
+    const bundle = await readPrebuiltDeployBundleAsync(file);
+    opened.push(bundle);
+    return bundle;
+  }
+
+  async function writeRawAsync(entries: RawEntry[]): Promise<string> {
+    const file = path.join(workDir, 'raw.nevermore.deploy.tar');
+    await fs.writeFile(file, rawTar(entries));
+    return file;
+  }
+
+  async function writeManifestAsync(
+    manifest: any,
+    projectText = PROJECT_TEXT
+  ): Promise<string> {
+    return writeRawAsync([
+      { path: 'manifest.json', body: JSON.stringify(manifest) },
+      { path: 'place-1.rbxl', body: 'place bytes' },
+      { path: 'project-1.json', body: projectText },
+    ]);
+  }
+
+  it('round-trips places, projects, versions and git info through one file', async () => {
+    const place = path.join(workDir, 'source.rbxl');
+    const project = path.join(workDir, 'default.project.json');
+    await fs.writeFile(place, 'place bytes');
+    await fs.writeFile(project, PROJECT_TEXT);
+    const file = path.join(workDir, 'out', 'pr-1.nevermore.deploy.tar');
+
+    await writePrebuiltDeployBundleAsync(
+      file,
+      'integration',
+      { commit: 'abc1234', version: SHA, branch: 'feature/x' },
+      [
+        {
+          name: '@quenty/integration',
+          rbxlPath: place,
+          projectPath: project,
+          packageVersion: '1.0.0',
+        },
+      ]
+    );
+    const bundle = await readAsync(file);
+
+    expect(bundle.target).toBe('integration');
+    expect(bundle.git).toEqual({
+      commit: 'abc1234',
+      version: SHA,
+      branch: 'feature/x',
+    });
+    expect(bundle.places).toHaveLength(1);
+    expect(bundle.places[0]!.name).toBe('@quenty/integration');
+    expect(bundle.places[0]!.packageVersion).toBe('1.0.0');
+    expect(await fs.readFile(bundle.places[0]!.rbxlPath, 'utf-8')).toBe(
+      'place bytes'
+    );
+    expect(await fs.readFile(bundle.places[0]!.projectPath, 'utf-8')).toBe(
+      PROJECT_TEXT
+    );
+  });
+
+  it('reads an empty bundle as no places', async () => {
+    const file = path.join(workDir, 'empty.nevermore.deploy.tar');
+    await writePrebuiltDeployBundleAsync(file, 'integration', {}, []);
+
+    const bundle = await readAsync(file);
+
+    expect(bundle.places).toEqual([]);
+  });
+
+  it('never writes outside its own directory for an entry that escapes', async () => {
+    const file = await writeRawAsync([
+      { path: 'manifest.json', body: JSON.stringify(validManifest()) },
+      { path: 'place-1.rbxl', body: 'place bytes' },
+      { path: 'project-1.json', body: PROJECT_TEXT },
+      { path: '../escaped.json', body: 'evil' },
+    ]);
+
+    await expect(readAsync(file)).rejects.toThrow('unexpected entry');
+    await expect(
+      fs.stat(path.join(os.tmpdir(), 'escaped.json'))
+    ).rejects.toThrow();
+  });
+
+  it('rejects a symlink entry', async () => {
+    const file = await writeRawAsync([
+      { path: 'manifest.json', body: JSON.stringify(validManifest()) },
+      { path: 'place-1.rbxl', body: 'place bytes' },
+      { path: 'project-1.json', type: 'SymbolicLink', linkpath: '/etc/passwd' },
+    ]);
+
+    await expect(readAsync(file)).rejects.toThrow('not a regular file');
+  });
+
+  it('rejects a file the manifest does not list', async () => {
+    const file = await writeRawAsync([
+      { path: 'manifest.json', body: JSON.stringify(validManifest()) },
+      { path: 'place-1.rbxl', body: 'place bytes' },
+      { path: 'project-1.json', body: PROJECT_TEXT },
+      { path: 'place-2.rbxl', body: 'extra' },
+    ]);
+
+    await expect(readAsync(file)).rejects.toThrow('every file it holds');
+  });
+
+  it('rejects a place pointing at a project file as its place', async () => {
+    const manifest = validManifest();
+    manifest.places[0].file = 'project-1.json';
+
+    await expect(readAsync(await writeManifestAsync(manifest))).rejects.toThrow(
+      'invalid file'
+    );
+  });
+
+  it('rejects a project without a tree', async () => {
+    await expect(
+      readAsync(await writeManifestAsync(validManifest(), '{"name":"x"}'))
+    ).rejects.toThrow('has no "tree"');
+  });
+
+  it.each([
+    ['target', (m: any) => (m.target = 'integration; rm -rf /')],
+    [
+      'package name',
+      (m: any) => (m.places[0].name = '@quenty/x [a](http://x)'),
+    ],
+    ['git version', (m: any) => (m.git.version = 'not-a-sha')],
+    ['package version', (m: any) => (m.places[0].packageVersion = '1.0 <b>')],
+  ])('rejects an invalid %s', async (label, mutate) => {
+    const manifest = validManifest();
+    mutate(manifest);
+
+    await expect(readAsync(await writeManifestAsync(manifest))).rejects.toThrow(
+      'invalid'
+    );
+  });
+
+  it('drops a branch name it will not stamp instead of failing', async () => {
+    const manifest = validManifest();
+    manifest.git.branch = 'main\n<img>';
+
+    const bundle = await readAsync(await writeManifestAsync(manifest));
+
+    expect(bundle.git.branch).toBeUndefined();
+    expect(bundle.git.version).toBe(SHA);
+  });
+
+  it('rejects an unknown format version', async () => {
+    const manifest = validManifest();
+    manifest.formatVersion = 2;
+
+    await expect(readAsync(await writeManifestAsync(manifest))).rejects.toThrow(
+      'Unsupported bundle format'
+    );
+  });
+
+  it('names the right command for a tests bundle', async () => {
+    const file = await writeRawAsync([
+      {
+        path: 'manifest.json',
+        body: JSON.stringify({
+          formatVersion: 1,
+          kind: 'tests',
+          chunks: [
+            {
+              file: 'place-1.rbxl',
+              packages: [{ name: '@quenty/maid', slug: 'maid' }],
+            },
+          ],
+        }),
+      },
+      { path: 'place-1.rbxl', body: 'place bytes' },
+    ]);
+
+    await expect(readAsync(file)).rejects.toThrow(
+      'This is a tests bundle, not a deploy bundle. Run it with "nevermore batch test --bundle <file>".'
+    );
+  });
+
+  it('rejects a bundle of an unknown kind', async () => {
+    const manifest = validManifest();
+    manifest.kind = 'mystery';
+
+    await expect(readAsync(await writeManifestAsync(manifest))).rejects.toThrow(
+      'unknown kind'
+    );
+  });
+});

package/src/utils/deploy/prebuilt-deploy-bundle.ts

@@ -0,0 +1,297 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as tar from 'tar';
+import { BuildContext } from '@quenty/nevermore-template-helpers';
+import { PLACE_UPLOAD_MAX_BYTES } from '../open-cloud/open-cloud-client.js';
+import {
+  PACKAGE_NAME_PATTERN,
+  readUntrustedTarAsync,
+} from '../bundle/untrusted-tar.js';
+import { type GitDeployInfo } from './deploy-metadata.js';
+
+/**
+ * Places built by `nevermore batch bundle --deploy`, unpacked from a
+ * `*.nevermore.deploy.tar` and ready for `batch deploy --bundle` to deploy.
+ *
+ * Each place is the plain rojo build. Its base place is merged at deploy time,
+ * because downloading one needs the Open Cloud key the building run lacks.
+ */
+export interface PrebuiltDeployBundle {
+  /** Deploy target name the places were built for, e.g. "integration". */
+  target: string;
+  /** The commit the places were built from, not the deploying checkout's. */
+  git: GitDeployInfo;
+  places: PrebuiltDeployPlace[];
+  /** Holds the unpacked files; whoever deploys them owns its cleanup. */
+  buildContext: BuildContext;
+}
+
+export interface PrebuiltDeployPlace {
+  /** Batch target display name, e.g. "@quenty/game" or "@quenty/game - hub". */
+  name: string;
+  rbxlPath: string;
+  /** The building checkout's rojo project, which says what to graft onto the base place. */
+  projectPath: string;
+  packageVersion?: string;
+}
+
+interface ManifestFile {
+  formatVersion: number;
+  kind?: 'deploy';
+  target: string;
+  git: GitDeployInfo;
+  places: Array<{
+    name: string;
+    file: string;
+    project: string;
+    packageVersion?: string;
+  }>;
+}
+
+/** Suggested file suffix, following `deploy.nevermore.json`. */
+export const DEPLOY_BUNDLE_FILE_SUFFIX = '.nevermore.deploy.tar';
+
+const MANIFEST_FILE_NAME = 'manifest.json';
+const FORMAT_VERSION = 1;
+const MAX_PLACES = 64;
+const MAX_MANIFEST_BYTES = 1024 * 1024;
+const MAX_PROJECT_BYTES = 1024 * 1024;
+const PLACE_FILE_PATTERN = /^place-\d{1,3}\.rbxl$/;
+const PROJECT_FILE_PATTERN = /^project-\d{1,3}\.json$/;
+const TARGET_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const SHORT_SHA_PATTERN = /^[0-9a-f]{4,40}$/;
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const BRANCH_PATTERN = /^[A-Za-z0-9._/-]{1,200}$/;
+const PACKAGE_VERSION_PATTERN = /^[0-9A-Za-z.+-]{1,64}$/;
+
+export async function writePrebuiltDeployBundleAsync(
+  file: string,
+  target: string,
+  git: GitDeployInfo,
+  places: PrebuiltDeployPlace[]
+): Promise<void> {
+  const stage = await BuildContext.createAsync({ prefix: 'deploy-bundle-' });
+  const stageDir = stage.buildDir;
+  try {
+    const manifest: ManifestFile = {
+      formatVersion: FORMAT_VERSION,
+      kind: 'deploy',
+      target,
+      git,
+      places: [],
+    };
+    for (const [index, place] of places.entries()) {
+      const placeFile = `place-${index + 1}.rbxl`;
+      const projectFile = `project-${index + 1}.json`;
+      await fs.copyFile(place.rbxlPath, path.join(stageDir, placeFile));
+      await fs.copyFile(place.projectPath, path.join(stageDir, projectFile));
+      manifest.places.push({
+        name: place.name,
+        file: placeFile,
+        project: projectFile,
+        packageVersion: place.packageVersion,
+      });
+    }
+    await fs.writeFile(
+      path.join(stageDir, MANIFEST_FILE_NAME),
+      JSON.stringify(manifest, null, 2)
+    );
+
+    await fs.mkdir(path.dirname(path.resolve(file)), { recursive: true });
+    await tar.c({ file, cwd: stageDir, portable: true }, [
+      MANIFEST_FILE_NAME,
+      ...manifest.places.flatMap((p) => [p.file, p.project]),
+    ]);
+  } finally {
+    await stage.cleanupAsync();
+  }
+}
+
+/**
+ * Read a deploy bundle file. It is untrusted: it comes from a fork's CI run.
+ * Entries are read rather than extracted, every manifest string is checked
+ * before it can reach a place attribute or the PR comment, and the bundle
+ * names places only by target name — where each one deploys, and which base
+ * place it merges onto, come from the deploying checkout's config.
+ */
+export async function readPrebuiltDeployBundleAsync(
+  file: string
+): Promise<PrebuiltDeployBundle> {
+  let stat;
+  try {
+    stat = await fs.lstat(file);
+  } catch {
+    throw new Error(`Bundle file not found: ${file}`);
+  }
+  if (!stat.isFile()) {
+    throw new Error(`Bundle ${file} is not a regular file`);
+  }
+
+  const buildContext = await BuildContext.createAsync({
+    prefix: 'deploy-bundle-',
+  });
+  const dir = buildContext.buildDir;
+  try {
+    const { manifestText, entrySizes } = await readUntrustedTarAsync(
+      file,
+      dir,
+      {
+        kind: 'deploy',
+        manifestName: MANIFEST_FILE_NAME,
+        maxManifestBytes: MAX_MANIFEST_BYTES,
+        isEntryAllowed: (name) =>
+          PLACE_FILE_PATTERN.test(name) || PROJECT_FILE_PATTERN.test(name),
+        maxEntries: MAX_PLACES * 2,
+        maxEntriesMessage: `Bundle must hold at most ${MAX_PLACES} places`,
+        checkEntrySize: (name, size) => {
+          if (PLACE_FILE_PATTERN.test(name) && size > PLACE_UPLOAD_MAX_BYTES) {
+            return `${name} is over the place upload limit`;
+          }
+          if (PROJECT_FILE_PATTERN.test(name) && size > MAX_PROJECT_BYTES) {
+            return `${name} is over the project file size limit`;
+          }
+          return undefined;
+        },
+      }
+    );
+    const parsed = _parseManifest(manifestText, dir, entrySizes);
+    for (const place of parsed.places) {
+      await _validateProjectFileAsync(place.projectPath);
+    }
+    return { ...parsed, buildContext };
+  } catch (err) {
+    await buildContext.cleanupAsync();
+    throw err;
+  }
+}
+
+function _parseManifest(
+  manifestText: string,
+  dir: string,
+  entrySizes: Map<string, number>
+): Omit<PrebuiltDeployBundle, 'buildContext'> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(manifestText);
+  } catch {
+    throw new Error('Bundle manifest is not valid JSON');
+  }
+
+  const manifest = parsed as Partial<ManifestFile>;
+  if (manifest?.formatVersion !== FORMAT_VERSION) {
+    throw new Error(
+      `Unsupported bundle format ${String(manifest?.formatVersion)} ` +
+        `(expected ${FORMAT_VERSION})`
+    );
+  }
+  if (
+    typeof manifest.target !== 'string' ||
+    !TARGET_NAME_PATTERN.test(manifest.target)
+  ) {
+    throw new Error(
+      `Bundle lists an invalid target: ${String(manifest.target)}`
+    );
+  }
+  if (!Array.isArray(manifest.places) || manifest.places.length > MAX_PLACES) {
+    throw new Error(`Bundle must list at most ${MAX_PLACES} places`);
+  }
+  if (manifest.places.length * 2 !== entrySizes.size) {
+    throw new Error('Bundle manifest does not list every file it holds');
+  }
+
+  const git = _parseGit(manifest.git);
+  const seenNames = new Set<string>();
+  const seenFiles = new Set<string>();
+  const places: PrebuiltDeployPlace[] = [];
+
+  for (const entry of manifest.places) {
+    const { name, file, project, packageVersion } = entry ?? {};
+    if (typeof name !== 'string' || !PACKAGE_NAME_PATTERN.test(name)) {
+      throw new Error(`Bundle lists an invalid package name: ${String(name)}`);
+    }
+    if (seenNames.has(name)) {
+      throw new Error(`Bundle lists ${name} more than once`);
+    }
+    seenNames.add(name);
+
+    for (const [listed, pattern] of [
+      [file, PLACE_FILE_PATTERN],
+      [project, PROJECT_FILE_PATTERN],
+    ] as const) {
+      if (
+        typeof listed !== 'string' ||
+        !pattern.test(listed) ||
+        !entrySizes.has(listed) ||
+        seenFiles.has(listed)
+      ) {
+        throw new Error(
+          `Bundle lists an invalid file for ${name}: ${String(listed)}`
+        );
+      }
+      seenFiles.add(listed);
+    }
+
+    if (
+      packageVersion !== undefined &&
+      (typeof packageVersion !== 'string' ||
+        !PACKAGE_VERSION_PATTERN.test(packageVersion))
+    ) {
+      throw new Error(`Bundle lists an invalid package version for ${name}`);
+    }
+
+    places.push({
+      name,
+      rbxlPath: path.join(dir, file!),
+      projectPath: path.join(dir, project!),
+      packageVersion,
+    });
+  }
+
+  return { target: manifest.target, git, places };
+}
+
+function _parseGit(git: unknown): GitDeployInfo {
+  if (git === undefined) {
+    return {};
+  }
+  if (typeof git !== 'object' || git === null) {
+    throw new Error('Bundle lists invalid git info');
+  }
+  const { commit, version, branch } = git as Record<string, unknown>;
+  const result: GitDeployInfo = {};
+  for (const [key, value, pattern] of [
+    ['commit', commit, SHORT_SHA_PATTERN],
+    ['version', version, SHA_PATTERN],
+  ] as const) {
+    if (value === undefined) {
+      continue;
+    }
+    if (typeof value !== 'string' || !pattern.test(value)) {
+      throw new Error(`Bundle lists an invalid git ${key}`);
+    }
+    result[key] = value;
+  }
+  // Git allows branch names this pattern does not, and a branch is only a
+  // label, so one that fails it is dropped rather than failing the deploy.
+  if (typeof branch === 'string' && BRANCH_PATTERN.test(branch)) {
+    result.branch = branch;
+  }
+  return result;
+}
+
+async function _validateProjectFileAsync(projectPath: string): Promise<void> {
+  let project: unknown;
+  try {
+    project = JSON.parse(await fs.readFile(projectPath, 'utf-8'));
+  } catch {
+    throw new Error(
+      `Bundle project ${path.basename(projectPath)} is not valid JSON`
+    );
+  }
+  const tree = (project as { tree?: unknown })?.tree;
+  if (typeof tree !== 'object' || tree === null) {
+    throw new Error(
+      `Bundle project ${path.basename(projectPath)} has no "tree"`
+    );
+  }
+}

package/src/utils/job-context/base-job-context.ts

@@ -111,7 +111,7 @@ export abstract class BaseJobContext implements JobContext {
     );
     this._builtPlaces.add(tracked);
 
-    if (target.basePlace) {
+    if (target.basePlace && !options.deferBasePlaceMerge) {
       await this._mergeBasePlaceAsync(tracked, options);
     }
 
@@ -248,7 +248,9 @@ export abstract class BaseJobContext implements JobContext {
 
     this._reporter.onPackagePhaseChange(resolvedName, 'merging');
     const packagePath = options.packagePath;
-    const projectPath = path.resolve(packagePath, tracked.target.project);
+    const projectPath =
+      options.overrides?.projectFile ??
+      path.resolve(packagePath, tracked.target.project);
     const mergedPath = mergeContext.resolvePath('merged.rbxl');
 
     await mergeContext.executeLuneTransformScriptAsync(