@quenty/nevermore-cli 4.42.0 → 4.42.1-canary.783.30683606415.0

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

@@ -11,6 +11,7 @@ import {
   type RunScriptOptions,
   type ScriptRunResult,
 } from './job-context.js';
+import { type BasePlaceResolver } from '@quenty/nevermore-deploy';
 import { BaseJobContext } from './base-job-context.js';
 
 const SKIP_RENAMING_PLACE = true;
@@ -30,8 +31,12 @@ class CloudDeployment implements Deployment {
 }
 
 export class CloudJobContext extends BaseJobContext {
-  constructor(reporter: Reporter, openCloudClient: OpenCloudClient) {
-    super(reporter, openCloudClient);
+  constructor(
+    reporter: Reporter,
+    openCloudClient: OpenCloudClient,
+    basePlaceResolver?: BasePlaceResolver
+  ) {
+    super(reporter, openCloudClient, basePlaceResolver);
   }
 
   async deployBuiltPlaceAsync(

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

@@ -7,6 +7,7 @@ import {
   type RunScriptOptions,
   type ScriptRunResult,
 } from './job-context.js';
+import { type BasePlaceResolver } from '@quenty/nevermore-deploy';
 import { BaseJobContext } from './base-job-context.js';
 import { type OpenCloudClient } from '../open-cloud/open-cloud-client.js';
 
@@ -24,8 +25,12 @@ class LocalDeployment implements Deployment {
 export class LocalJobContext extends BaseJobContext {
   private _deployments = new Set<LocalDeployment>();
 
-  constructor(reporter: Reporter, openCloudClient?: OpenCloudClient) {
-    super(reporter, openCloudClient);
+  constructor(
+    reporter: Reporter,
+    openCloudClient?: OpenCloudClient,
+    basePlaceResolver?: BasePlaceResolver
+  ) {
+    super(reporter, openCloudClient, basePlaceResolver);
   }
 
   async deployBuiltPlaceAsync(

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

@@ -203,38 +203,157 @@ describe('OpenCloudClient.downloadPlaceAsync', () => {
   });
 });
 
-describe('OpenCloudClient.getLatestPlaceVersionAsync', () => {
+describe('OpenCloudClient.resolveLatestPlaceVersionAsync', () => {
   afterEach(() => {
     vi.restoreAllMocks();
   });
 
-  it('returns the numeric revisionId from the Assets API', async () => {
-    const urls: string[] = [];
-    const fakeLimiter = {
+  /** Page the Assets API newest-first, as the real endpoint does. */
+  function makeVersionsLimiter(
+    pages: Array<Array<{ version: number; published?: boolean }>>,
+    urls: string[] = []
+  ): RateLimiter {
+    return {
       fetchAsync: vi.fn(async (url: string | URL) => {
         urls.push(String(url));
+        const page = pages[urls.length - 1] ?? [];
         return new Response(
-          JSON.stringify({ assetId: '22', revisionId: '5781' }),
+          JSON.stringify({
+            assetVersions: page.map((entry) => ({
+              path: `assets/22/versions/${entry.version}`,
+              // The real API omits `published` entirely on save-only versions.
+              ...(entry.published ? { published: true } : {}),
+            })),
+            ...(urls.length < pages.length
+              ? { nextPageToken: `token-${urls.length}` }
+              : {}),
+          }),
           { status: 200 }
         );
       }),
     } as unknown as RateLimiter;
+  }
 
+  it('resolves "saved" to the newest version of any kind', async () => {
+    const urls: string[] = [];
     const client = new OpenCloudClient({
       apiKey: 'test-key',
-      rateLimiter: fakeLimiter,
+      rateLimiter: makeVersionsLimiter(
+        [[{ version: 5781 }, { version: 5780, published: true }]],
+        urls
+      ),
+    });
+
+    expect(await client.resolveLatestPlaceVersionAsync(1, 22, 'saved')).toBe(
+      5781
+    );
+    expect(urls).toHaveLength(1);
+    expect(urls[0]).toBe(
+      'https://apis.roblox.com/assets/v1/assets/22/versions?maxPageSize=50'
+    );
+  });
+
+  it('resolves "published" past unpublished saves at the head', async () => {
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeVersionsLimiter([
+        [
+          { version: 5781 },
+          { version: 5780 },
+          { version: 5779, published: true },
+        ],
+      ]),
+    });
+
+    expect(
+      await client.resolveLatestPlaceVersionAsync(1, 22, 'published')
+    ).toBe(5779);
+  });
+
+  it('pages only until the newest published version is found', async () => {
+    const urls: string[] = [];
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeVersionsLimiter(
+        [
+          [{ version: 300 }, { version: 299 }],
+          [{ version: 298, published: true }, { version: 297 }],
+          [{ version: 296, published: true }],
+        ],
+        urls
+      ),
+    });
+
+    expect(
+      await client.resolveLatestPlaceVersionAsync(1, 22, 'published')
+    ).toBe(298);
+    expect(urls).toHaveLength(2);
+    expect(urls[1]).toContain('pageToken=token-1');
+  });
+
+  it('throws when the place has never been published', async () => {
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeVersionsLimiter([[{ version: 2 }, { version: 1 }]]),
+    });
+
+    await expect(
+      client.resolveLatestPlaceVersionAsync(1, 22, 'published')
+    ).rejects.toThrowError(/no published version/);
+  });
+
+  it('refuses to guess when the API stops paging newest-first', async () => {
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeVersionsLimiter([
+        [{ version: 1 }, { version: 2, published: true }],
+      ]),
     });
-    const version = await client.getLatestPlaceVersionAsync(1, 22);
 
-    expect(version).toBe(5781);
-    expect(urls[0]).toBe('https://apis.roblox.com/assets/v1/assets/22');
+    await expect(
+      client.resolveLatestPlaceVersionAsync(1, 22, 'published')
+    ).rejects.toThrowError(/no longer paging newest-first/);
   });
 
-  it('throws when the Assets API omits a revisionId', async () => {
+  it('refuses a "saved" lookup when the page is not newest-first', async () => {
+    // "saved" answers from the first entry, so the ordering guard has to check
+    // the whole page before returning or this silently pins the oldest build.
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeVersionsLimiter([
+        [{ version: 1 }, { version: 2 }, { version: 3 }],
+      ]),
+    });
+
+    await expect(
+      client.resolveLatestPlaceVersionAsync(1, 22, 'saved')
+    ).rejects.toThrowError(/no longer paging newest-first/);
+  });
+
+  it('reports the scan limit when every page is unpublished', async () => {
+    const pages = Array.from({ length: 25 }, (_, page) =>
+      Array.from({ length: 2 }, (_, i) => ({ version: 1000 - page * 2 - i }))
+    );
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeVersionsLimiter(pages),
+    });
+
+    await expect(
+      client.resolveLatestPlaceVersionAsync(1, 22, 'published')
+    ).rejects.toThrowError(/in its most recent 1000 versions/);
+  });
+
+  it('throws on an unparseable version path', async () => {
     const fakeLimiter = {
       fetchAsync: vi.fn(
         async () =>
-          new Response(JSON.stringify({ assetId: '22' }), { status: 200 })
+          new Response(
+            JSON.stringify({
+              assetVersions: [{ path: 'assets/22/versions/' }],
+            }),
+            { status: 200 }
+          )
       ),
     } as unknown as RateLimiter;
 
@@ -243,8 +362,8 @@ describe('OpenCloudClient.getLatestPlaceVersionAsync', () => {
       rateLimiter: fakeLimiter,
     });
 
-    await expect(client.getLatestPlaceVersionAsync(1, 22)).rejects.toThrowError(
-      /no revisionId/
-    );
+    await expect(
+      client.resolveLatestPlaceVersionAsync(1, 22, 'saved')
+    ).rejects.toThrowError(/unparseable version path/);
   });
 });

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

@@ -33,6 +33,13 @@ export interface OpenCloudClientOptions {
   rateLimiter: RateLimiter;
 }
 
+/**
+ * Which end of a place's version history to resolve. Mirrors the `versionType`
+ * the place-publishing API takes on upload, lowercased to match how it is
+ * written in deploy.nevermore.json.
+ */
+export type PlaceVersionType = 'saved' | 'published';
+
 function formatAuthError(
   action: string,
   scope: string,
@@ -494,57 +501,143 @@ export class OpenCloudClient {
   }
 
   /**
-   * Resolve the current latest published version number of a place, via the
+   * Resolve the newest saved or published version number of a place, via the
    * Open Cloud Assets API (`asset:read` scope; `legacy-asset:manage` also
    * grants it). The returned number is the same value the Asset Delivery API's
    * `/version/{n}` route expects, so it can be written straight into a
    * `basePlace.version` pin.
+   *
+   * `saved` is the newest version of any kind — Studio saves and publishes
+   * share one increasing version sequence. `published` is the newest version
+   * that actually went live, which is what players see and what a deploy
+   * merging against a base place normally wants.
+   *
+   * The endpoint pages newest-first, which is what makes this affordable: an
+   * actively-developed place accumulates tens of thousands of versions, and we
+   * never walk the history. `saved` is the first entry of the first page, and
+   * `published` only walks back as far as the most recent live version — one
+   * page unless the place has been saved 50+ times without publishing. The scan
+   * is capped so a never-published place fails fast instead of paging forever.
    */
-  async getLatestPlaceVersionAsync(
+  async resolveLatestPlaceVersionAsync(
     universeId: number,
-    placeId: number
+    placeId: number,
+    versionType: PlaceVersionType
   ): Promise<number> {
     const apiKey = await this._resolveApiKeyAsync();
-    const url = `https://apis.roblox.com/assets/v1/assets/${placeId}`;
+    let pageToken: string | undefined;
+    let previousVersion: number | undefined;
 
-    const response = await this._rateLimiter.fetchAsync(url, {
-      method: 'GET',
-      headers: {
-        'x-api-key': apiKey,
-      },
-    });
+    for (let page = 0; page < VERSION_SCAN_MAX_PAGES; page++) {
+      const url =
+        `https://apis.roblox.com/assets/v1/assets/${placeId}/versions` +
+        `?maxPageSize=${VERSION_SCAN_PAGE_SIZE}` +
+        (pageToken ? `&pageToken=${encodeURIComponent(pageToken)}` : '');
 
-    if (!response.ok) {
-      const text = await response.text();
-      if (response.status === 401 || response.status === 403) {
+      const response = await this._rateLimiter.fetchAsync(url, {
+        method: 'GET',
+        headers: {
+          'x-api-key': apiKey,
+        },
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        if (response.status === 401 || response.status === 403) {
+          throw new Error(
+            formatAuthError(
+              'Read place version',
+              'asset:read',
+              universeId,
+              placeId,
+              response.status,
+              response.statusText,
+              text,
+              'GET',
+              url
+            )
+          );
+        }
         throw new Error(
-          formatAuthError(
-            'Read place version',
-            'asset:read',
-            universeId,
-            placeId,
-            response.status,
-            response.statusText,
-            text,
-            'GET',
-            url
-          )
+          `Read place version failed: ${response.status} ${response.statusText}: ${text}`
         );
       }
-      throw new Error(
-        `Read place version failed: ${response.status} ${response.statusText}: ${text}`
-      );
-    }
 
-    const data = (await response.json()) as { revisionId?: string };
-    const version = Number(data.revisionId);
-    if (!data.revisionId || !Number.isFinite(version)) {
-      throw new Error(
-        `Read place version failed: no revisionId for place ${placeId}`
+      const data = (await response.json()) as {
+        assetVersions?: AssetVersion[];
+        nextPageToken?: string;
+      };
+
+      const page = (data.assetVersions ?? []).map((assetVersion) => ({
+        versionNumber: _parseAssetVersionNumber(placeId, assetVersion),
+        published: assetVersion.published === true,
+      }));
+
+      // Everything here rests on the API paging newest-first, and a `saved`
+      // lookup answers from the very first entry — so the whole page is checked
+      // before anything is returned. Validating only as far as the match would
+      // leave the common case unchecked and quietly pin a years-old build.
+      for (const { versionNumber } of page) {
+        if (previousVersion != null && versionNumber >= previousVersion) {
+          throw new Error(
+            `Read place version failed: place ${placeId} returned version ` +
+              `${versionNumber} after ${previousVersion}. The Assets API is no ` +
+              `longer paging newest-first, so "${versionType}" cannot be resolved ` +
+              `safely — pin an explicit version number in deploy.nevermore.json.`
+          );
+        }
+        previousVersion = versionNumber;
+      }
+
+      // `published` is omitted rather than false on save-only versions.
+      const match = page.find(
+        (entry) => versionType === 'saved' || entry.published
       );
+      if (match) {
+        return match.versionNumber;
+      }
+
+      pageToken = data.nextPageToken;
+      if (!pageToken) {
+        break;
+      }
     }
-    return version;
+
+    throw new Error(
+      `Place ${placeId} has no ${versionType} version` +
+        (pageToken
+          ? ` in its most recent ${
+              VERSION_SCAN_MAX_PAGES * VERSION_SCAN_PAGE_SIZE
+            } versions`
+          : '') +
+        `. Pin an explicit version number in deploy.nevermore.json, or publish the place once.`
+    );
+  }
+}
+
+/** How the Assets API reports one entry of a place's version history. */
+interface AssetVersion {
+  /** `assets/{assetId}/versions/{versionNumber}` */
+  path?: string;
+  /** Present and true only once the version has been published live. */
+  published?: boolean;
+}
+
+const VERSION_SCAN_PAGE_SIZE = 50;
+const VERSION_SCAN_MAX_PAGES = 20;
+
+function _parseAssetVersionNumber(
+  placeId: number,
+  version: AssetVersion
+): number {
+  const versionNumber = Number(version.path?.split('/').pop());
+  if (!Number.isInteger(versionNumber) || versionNumber < 1) {
+    throw new Error(
+      `Read place version failed: place ${placeId} returned an unparseable ` +
+        `version path "${version.path}"`
+    );
   }
+  return versionNumber;
 }
 
 const CDN_MAX_ATTEMPTS = 4;

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

@@ -5,7 +5,7 @@ import {
   resolvePackagePath,
 } from '@quenty/nevermore-template-helpers';
 import { OutputHelper } from '@quenty/cli-output-helpers';
-import { type DeployTarget } from '../../build/deploy-config.js';
+import { type DeployTarget } from '@quenty/nevermore-deploy';
 import { type BatchTarget } from '../../batch/changed-packages-utils.js';
 
 export interface CombinedProjectResult {

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

@@ -1,7 +1,7 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
-import { type DeployTarget } from '../../build/deploy-config.js';
+import { type DeployTarget } from '@quenty/nevermore-deploy';
 import { type JobContext } from '../../job-context/job-context.js';
 import {
   type ParsedTestCounts,

package/src/utils/watch/github-context.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import {
+  describeMissingWatchToken,
+  parseGithubRepository,
+  tryResolveGithubDispatchContext,
+} from './github-context.js';
+
+// ESM exports cannot be spied on, so the module is mocked outright.
+const execSyncMock = vi.hoisted(() => vi.fn());
+vi.mock('child_process', () => ({ execSync: execSyncMock }));
+
+afterEach(() => {
+  execSyncMock.mockReset();
+  vi.unstubAllEnvs();
+});
+
+/** Answers the subprocesses github-context shells out to. */
+function stubCommands(answers: Record<string, string | Error>) {
+  execSyncMock.mockImplementation((cmd: string) => {
+    for (const [prefix, answer] of Object.entries(answers)) {
+      if (cmd.startsWith(prefix)) {
+        if (answer instanceof Error) {
+          throw answer;
+        }
+        return answer;
+      }
+    }
+    throw new Error(`unstubbed command: ${cmd}`);
+  });
+}
+
+describe('tryResolveGithubDispatchContext token', () => {
+  const REPO_AND_REF = {
+    'git remote get-url origin': 'git@github.com:Quenty/Nevermore.git',
+    'git rev-parse': 'main',
+  };
+
+  // Registering ships the token to the watch service, so it has to be one the
+  // user handed over. Nearly every dev machine has a logged-in `gh`, so reading
+  // it by default would turn a local watch into a silent credential send.
+  it('does not consult gh unless asked', () => {
+    vi.stubEnv('NEVERMORE_WATCH_TOKEN', '');
+    vi.stubEnv('GITHUB_TOKEN', '');
+    stubCommands({
+      ...REPO_AND_REF,
+      'gh auth token': new Error('gh must not be consulted'),
+    });
+
+    const result = tryResolveGithubDispatchContext();
+    expect(result.success && result.context.token).toBeUndefined();
+  });
+
+  it('reads the GitHub CLI token when explicitly asked', () => {
+    vi.stubEnv('NEVERMORE_WATCH_TOKEN', '');
+    vi.stubEnv('GITHUB_TOKEN', '');
+    stubCommands({ ...REPO_AND_REF, 'gh auth token': 'gho_from_cli' });
+
+    const result = tryResolveGithubDispatchContext({ useGhAuth: true });
+    expect(result.success && result.context.token).toBe('gho_from_cli');
+  });
+
+  // CI sets the env var, and must never pay for the subprocess.
+  it('prefers the env var and does not shell out to gh', () => {
+    vi.stubEnv('NEVERMORE_WATCH_TOKEN', 'from-env');
+    stubCommands({
+      ...REPO_AND_REF,
+      'gh auth token': new Error('gh should not be consulted'),
+    });
+
+    const result = tryResolveGithubDispatchContext({ useGhAuth: true });
+    expect(result.success && result.context.token).toBe('from-env');
+  });
+
+  it('reports no token when gh is missing or logged out', () => {
+    vi.stubEnv('NEVERMORE_WATCH_TOKEN', '');
+    vi.stubEnv('GITHUB_TOKEN', '');
+    stubCommands({
+      ...REPO_AND_REF,
+      'gh auth token': new Error('gh: command not found'),
+    });
+
+    const result = tryResolveGithubDispatchContext({ useGhAuth: true });
+    expect(result.success && result.context.token).toBeUndefined();
+  });
+
+  // A logged-out `gh` exits non-zero, but a notice printed to stdout would sail
+  // through as a "token" and fail much later as a confusing 401.
+  it('refuses output that cannot be a token', () => {
+    vi.stubEnv('NEVERMORE_WATCH_TOKEN', '');
+    vi.stubEnv('GITHUB_TOKEN', '');
+    stubCommands({
+      ...REPO_AND_REF,
+      'gh auth token': 'You are not logged in. Run gh auth login',
+    });
+
+    const result = tryResolveGithubDispatchContext({ useGhAuth: true });
+    expect(result.success && result.context.token).toBeUndefined();
+  });
+
+  it('names both ways of supplying a token when none is found', () => {
+    expect(describeMissingWatchToken()).toMatch(/NEVERMORE_WATCH_TOKEN/);
+    expect(describeMissingWatchToken()).toMatch(/--watch-use-gh-auth/);
+  });
+});
+
+describe('parseGithubRepository', () => {
+  it('parses an https remote', () => {
+    expect(
+      parseGithubRepository('https://github.com/Quenty/Nevermore.git')
+    ).toBe('Quenty/Nevermore');
+  });
+
+  it('parses an https remote without the .git suffix', () => {
+    expect(parseGithubRepository('https://github.com/Quenty/Nevermore')).toBe(
+      'Quenty/Nevermore'
+    );
+  });
+
+  it('parses an scp-style ssh remote', () => {
+    expect(parseGithubRepository('git@github.com:Quenty/Nevermore.git')).toBe(
+      'Quenty/Nevermore'
+    );
+  });
+
+  it('parses an ssh:// remote', () => {
+    expect(
+      parseGithubRepository('ssh://git@github.com/Quenty/Nevermore.git')
+    ).toBe('Quenty/Nevermore');
+  });
+
+  it('parses a remote with credentials embedded', () => {
+    expect(
+      parseGithubRepository(
+        'https://user:token@github.com/Quenty/Nevermore.git'
+      )
+    ).toBe('Quenty/Nevermore');
+  });
+
+  it('tolerates surrounding whitespace and a trailing slash', () => {
+    expect(
+      parseGithubRepository('  https://github.com/Quenty/Nevermore/  ')
+    ).toBe('Quenty/Nevermore');
+  });
+
+  it('ignores a non-GitHub host', () => {
+    expect(
+      parseGithubRepository('https://gitlab.com/Quenty/Nevermore.git')
+    ).toBeUndefined();
+  });
+
+  it('ignores a local path remote', () => {
+    expect(parseGithubRepository('/srv/git/Nevermore.git')).toBeUndefined();
+  });
+});