@quenty/nevermore-cli 4.46.0 → 4.47.0

package/src/utils/assets/asset-formats.ts

@@ -0,0 +1,102 @@
+import * as path from 'path';
+
+/**
+ * The `assetType` values `nevermore deploy asset upload` can send to the Open
+ * Cloud Assets API. Mesh is left out on purpose: the API only accepts mesh data
+ * that was itself downloaded from Roblox, which is not something a file on disk
+ * can be recognized as.
+ *
+ * https://create.roblox.com/docs/cloud/guides/usage-assets
+ */
+export const ASSET_TYPES = [
+  'Animation',
+  'Audio',
+  'Decal',
+  'Image',
+  'Model',
+  'Video',
+] as const;
+
+export type AssetType = typeof ASSET_TYPES[number];
+
+interface AssetFileFormat {
+  /** Sent as the `fileContent` part's type; the API picks its importer from it. */
+  contentType: string;
+  /** Every type this extension can upload as. The first is the default. */
+  assetTypes: readonly AssetType[];
+}
+
+// An image defaults to Image rather than Decal: an Image id is usable directly
+// as `rbxassetid://`, where a Decal is a wrapper whose id has to be resolved to
+// the image inside it before an ImageLabel can show it.
+const IMAGE_TYPES = ['Image', 'Decal'] as const;
+
+// A Roblox model file holds either, and nothing in its name says which.
+const ROBLOX_MODEL_TYPES = ['Model', 'Animation'] as const;
+
+const ASSET_FILE_FORMATS: Record<string, AssetFileFormat> = {
+  '.mp3': { contentType: 'audio/mpeg', assetTypes: ['Audio'] },
+  '.ogg': { contentType: 'audio/ogg', assetTypes: ['Audio'] },
+  '.wav': { contentType: 'audio/wav', assetTypes: ['Audio'] },
+  '.flac': { contentType: 'audio/flac', assetTypes: ['Audio'] },
+  '.png': { contentType: 'image/png', assetTypes: IMAGE_TYPES },
+  '.jpg': { contentType: 'image/jpeg', assetTypes: IMAGE_TYPES },
+  '.jpeg': { contentType: 'image/jpeg', assetTypes: IMAGE_TYPES },
+  '.bmp': { contentType: 'image/bmp', assetTypes: IMAGE_TYPES },
+  '.tga': { contentType: 'image/tga', assetTypes: IMAGE_TYPES },
+  '.fbx': { contentType: 'model/fbx', assetTypes: ['Model'] },
+  '.gltf': { contentType: 'model/gltf+json', assetTypes: ['Model'] },
+  '.glb': { contentType: 'model/gltf-binary', assetTypes: ['Model'] },
+  '.rbxm': { contentType: 'model/x-rbxm', assetTypes: ROBLOX_MODEL_TYPES },
+  '.rbxmx': { contentType: 'model/x-rbxm', assetTypes: ROBLOX_MODEL_TYPES },
+  '.mp4': { contentType: 'video/mp4', assetTypes: ['Video'] },
+  '.mov': { contentType: 'video/mov', assetTypes: ['Video'] },
+};
+
+export interface ResolvedAssetFormat {
+  assetType: AssetType;
+  contentType: string;
+}
+
+/**
+ * Work out how a file uploads: its asset type and the content type to send.
+ * The extension decides both unless `explicitType` picks one of the
+ * alternatives it allows (`Decal` for an image, `Animation` for an `.rbxm`).
+ */
+export function resolveAssetFormat(
+  filePath: string,
+  explicitType?: AssetType
+): ResolvedAssetFormat {
+  const extension = path.extname(filePath).toLowerCase();
+  const format = ASSET_FILE_FORMATS[extension];
+  if (!format) {
+    throw new Error(
+      `Cannot upload "${filePath}": ${
+        extension === '' ? 'a file with no extension' : `"${extension}"`
+      } is not an asset format the Open Cloud Assets API accepts.\n` +
+        `Supported: ${Object.keys(ASSET_FILE_FORMATS).join(', ')}`
+    );
+  }
+
+  if (explicitType != null && !format.assetTypes.includes(explicitType)) {
+    throw new Error(
+      `Cannot upload "${filePath}" as ${explicitType}: ` +
+        `a "${extension}" file uploads as ${format.assetTypes.join(' or ')}.`
+    );
+  }
+
+  return {
+    assetType: explicitType ?? format.assetTypes[0]!,
+    contentType: format.contentType,
+  };
+}
+
+/**
+ * Whether an existing asset of this type can have its file replaced in place,
+ * keeping its id. The API documents this for models only, and marks images,
+ * audio and video "not available for updating" — so a changed image or sound
+ * is always a new asset with a new id.
+ */
+export function canUpdateAssetContent(assetType: AssetType): boolean {
+  return assetType === 'Model';
+}

package/src/utils/assets/asset-upload-plan.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { buildAssetUploadPlan } from './asset-upload-plan.js';
+
+describe('buildAssetUploadPlan', () => {
+  it('names each asset after its file, and describes it by its name', () => {
+    expect(
+      buildAssetUploadPlan({ files: ['art/icons_1.png', 'models/City.fbx'] })
+    ).toEqual([
+      {
+        filePath: 'art/icons_1.png',
+        assetType: 'Image',
+        contentType: 'image/png',
+        displayName: 'icons_1',
+        description: 'icons_1',
+        assetId: undefined,
+      },
+      {
+        filePath: 'models/City.fbx',
+        assetType: 'Model',
+        contentType: 'model/fbx',
+        displayName: 'City',
+        description: 'City',
+        assetId: undefined,
+      },
+    ]);
+  });
+
+  it('takes an explicit name and description for a single file', () => {
+    const [entry] = buildAssetUploadPlan({
+      files: ['City.fbx'],
+      name: 'Openfront City',
+      description: 'Unit model',
+    });
+
+    expect(entry?.displayName).toBe('Openfront City');
+    expect(entry?.description).toBe('Unit model');
+  });
+
+  it('refuses one name for several files', () => {
+    expect(() =>
+      buildAssetUploadPlan({ files: ['a.png', 'b.png'], name: 'Icon' })
+    ).toThrowError(/--name names one asset, but 2 files were given/);
+  });
+
+  it('plans a replacement when given the id of an existing model', () => {
+    const [entry] = buildAssetUploadPlan({
+      files: ['City.fbx'],
+      assetId: 123,
+    });
+
+    expect(entry?.assetId).toBe(123);
+  });
+
+  it('refuses to replace anything but a model', () => {
+    // The API has no in-place update for these, so letting the request through
+    // would only trade a clear message for whatever the server says instead.
+    expect(() =>
+      buildAssetUploadPlan({ files: ['icon.png'], assetId: 123 })
+    ).toThrowError(/only replaces the content of a Model/);
+  });
+
+  it('refuses one asset id for several files', () => {
+    expect(() =>
+      buildAssetUploadPlan({ files: ['a.fbx', 'b.fbx'], assetId: 123 })
+    ).toThrowError(/--asset-id replaces one asset, but 2 files were given/);
+  });
+
+  it('rejects the whole batch when one file cannot be uploaded', () => {
+    // Nothing is uploaded until every file is known to be uploadable: a batch
+    // that fails partway has already created assets that cannot be taken back.
+    expect(() =>
+      buildAssetUploadPlan({ files: ['a.png', 'notes.txt'] })
+    ).toThrowError(/"\.txt" is not an asset format/);
+  });
+});

package/src/utils/assets/asset-upload-plan.ts

@@ -0,0 +1,79 @@
+import * as path from 'path';
+import {
+  canUpdateAssetContent,
+  resolveAssetFormat,
+  type AssetType,
+} from './asset-formats.js';
+
+export interface AssetUploadPlanOptions {
+  files: string[];
+  /** Applied to every file; each must be able to upload as it. */
+  type?: AssetType;
+  /** Display name. Single file only — defaults to the file's base name. */
+  name?: string;
+  description?: string;
+  /** Replace this asset's content instead of creating one. Single file only. */
+  assetId?: number;
+}
+
+export interface AssetUploadPlanEntry {
+  filePath: string;
+  assetType: AssetType;
+  contentType: string;
+  displayName: string;
+  description: string;
+  /** Set when the upload replaces an existing asset's content in place. */
+  assetId?: number;
+}
+
+/**
+ * Turn the command line into one upload per file, rejecting anything that
+ * could not work before a single request is sent — a batch that fails on its
+ * fifth file has already created four assets.
+ */
+export function buildAssetUploadPlan(
+  options: AssetUploadPlanOptions
+): AssetUploadPlanEntry[] {
+  const { files, type, name, description, assetId } = options;
+
+  if (files.length === 0) {
+    throw new Error('No files to upload.');
+  }
+  if (files.length > 1 && name != null) {
+    throw new Error(
+      `--name names one asset, but ${files.length} files were given. ` +
+        `Drop it to name each asset after its file.`
+    );
+  }
+  if (files.length > 1 && assetId != null) {
+    throw new Error(
+      `--asset-id replaces one asset, but ${files.length} files were given.`
+    );
+  }
+  if (assetId != null && (!Number.isSafeInteger(assetId) || assetId < 1)) {
+    throw new Error('--asset-id must be a positive integer.');
+  }
+
+  return files.map((filePath) => {
+    const { assetType, contentType } = resolveAssetFormat(filePath, type);
+    if (assetId != null && !canUpdateAssetContent(assetType)) {
+      throw new Error(
+        `Cannot replace asset ${assetId} with "${filePath}": the Assets API ` +
+          `only replaces the content of a Model. Upload the ${assetType} ` +
+          `without --asset-id to create a new asset instead.`
+      );
+    }
+
+    const displayName = name ?? path.basename(filePath, path.extname(filePath));
+    return {
+      filePath,
+      assetType,
+      contentType,
+      displayName,
+      // The API requires a description on create, so an omitted one falls back
+      // to the name rather than to text nobody chose.
+      description: description ?? displayName,
+      assetId,
+    };
+  });
+}

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

@@ -372,6 +372,367 @@ describe('OpenCloudClient.resolveLatestPlaceVersionAsync', () => {
   });
 });
 
+describe('OpenCloudClient asset uploads', () => {
+  beforeEach(() => {
+    vi.mocked(fs.readFile).mockResolvedValue(
+      Buffer.from([1, 2, 3]) as unknown as string
+    );
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  interface CapturedRequest {
+    url: string;
+    method?: string;
+    headers: Record<string, string>;
+    form: FormData;
+  }
+
+  /** Answer every request with `operation`, recording what was sent. */
+  function makeUploadLimiter(
+    operation: unknown,
+    captured: CapturedRequest[] = []
+  ): RateLimiter {
+    return {
+      fetchAsync: vi.fn(async (url: string | URL, init?: RequestInit) => {
+        captured.push({
+          url: String(url),
+          method: init?.method,
+          headers: init?.headers as Record<string, string>,
+          form: init?.body as FormData,
+        });
+        return new Response(JSON.stringify(operation), { status: 200 });
+      }),
+    } as unknown as RateLimiter;
+  }
+
+  it('creates an asset as a multipart request naming its owner', async () => {
+    const captured: CapturedRequest[] = [];
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeUploadLimiter({ path: 'operations/abc' }, captured),
+    });
+
+    const operation = await client.createAssetAsync({
+      filePath: '/art/icons_1.png',
+      contentType: 'image/png',
+      assetType: 'Image',
+      displayName: 'icons_1',
+      description: 'Interface art',
+      creator: { userId: 4397833 },
+    });
+
+    expect(operation.path).toBe('operations/abc');
+    expect(captured[0]?.url).toBe('https://apis.roblox.com/assets/v1/assets');
+    expect(captured[0]?.method).toBe('POST');
+    // The multipart boundary is fetch's to write; a hand-set Content-Type would
+    // send a body the API cannot split into its two parts.
+    expect(captured[0]?.headers).toEqual({ 'x-api-key': 'test-key' });
+
+    const form = captured[0]!.form;
+    expect(JSON.parse(form.get('request') as string)).toEqual({
+      assetType: 'Image',
+      displayName: 'icons_1',
+      description: 'Interface art',
+      creationContext: { creator: { userId: '4397833' } },
+    });
+    const file = form.get('fileContent') as File;
+    expect(file.name).toBe('icons_1.png');
+    expect(file.type).toBe('image/png');
+    expect([...new Uint8Array(await file.arrayBuffer())]).toEqual([1, 2, 3]);
+  });
+
+  it('names a group as the owner when given a group id', async () => {
+    const captured: CapturedRequest[] = [];
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeUploadLimiter({ path: 'operations/abc' }, captured),
+    });
+
+    await client.createAssetAsync({
+      filePath: '/models/City.fbx',
+      contentType: 'model/fbx',
+      assetType: 'Model',
+      displayName: 'City',
+      description: 'City',
+      creator: { groupId: 77 },
+    });
+
+    const request = JSON.parse(captured[0]!.form.get('request') as string);
+    expect(request.creationContext).toEqual({ creator: { groupId: '77' } });
+  });
+
+  it('replaces an asset in place with a PATCH to its id', async () => {
+    const captured: CapturedRequest[] = [];
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeUploadLimiter({ path: 'operations/abc' }, captured),
+    });
+
+    await client.updateAssetContentAsync(123, {
+      filePath: '/models/City.fbx',
+      contentType: 'model/fbx',
+    });
+
+    expect(captured[0]?.url).toBe(
+      'https://apis.roblox.com/assets/v1/assets/123'
+    );
+    expect(captured[0]?.method).toBe('PATCH');
+    expect(JSON.parse(captured[0]!.form.get('request') as string)).toEqual({
+      assetId: 123,
+    });
+    expect((captured[0]!.form.get('fileContent') as File).type).toBe(
+      'model/fbx'
+    );
+  });
+
+  it('names the scopes an upload needs when the key is refused', async () => {
+    const rateLimiter = {
+      fetchAsync: vi.fn(
+        async () =>
+          new Response(JSON.stringify({ code: 7, message: 'Forbidden' }), {
+            status: 403,
+            statusText: 'Forbidden',
+          })
+      ),
+    } as unknown as RateLimiter;
+    const client = new OpenCloudClient({ apiKey: 'test-key', rateLimiter });
+
+    await expect(
+      client.createAssetAsync({
+        filePath: '/art/icon.png',
+        contentType: 'image/png',
+        assetType: 'Image',
+        displayName: 'icon',
+        description: 'icon',
+        creator: { userId: 1 },
+      })
+    ).rejects.toThrowError(
+      /Create asset failed: Forbidden \(403\)[\s\S]*asset:read, asset:write/
+    );
+  });
+
+  describe('pollAssetOperationAsync', () => {
+    beforeEach(() => {
+      vi.spyOn(global, 'setTimeout').mockImplementation((fn: () => void) => {
+        fn();
+        return 0 as unknown as NodeJS.Timeout;
+      });
+    });
+
+    /** Answer successive polls with successive operation states. */
+    function makePollLimiter(
+      states: unknown[],
+      urls: string[] = []
+    ): RateLimiter {
+      return {
+        fetchAsync: vi.fn(async (url: string | URL) => {
+          urls.push(String(url));
+          const state = states[Math.min(urls.length, states.length) - 1];
+          return new Response(JSON.stringify(state), { status: 200 });
+        }),
+      } as unknown as RateLimiter;
+    }
+
+    it('polls the operation until it is done and returns the asset', async () => {
+      const urls: string[] = [];
+      const client = new OpenCloudClient({
+        apiKey: 'test-key',
+        rateLimiter: makePollLimiter(
+          [
+            { path: 'operations/abc' },
+            {
+              path: 'operations/abc',
+              done: true,
+              // As the live API answers: the id is a string despite the
+              // schema's integer, and the moderation state is a bare word.
+              response: {
+                assetId: '2205400862',
+                revisionId: '1',
+                moderationResult: { moderationState: 'Reviewing' },
+              },
+            },
+          ],
+          urls
+        ),
+      });
+
+      const asset = await client.pollAssetOperationAsync({
+        path: 'operations/abc',
+      });
+
+      expect(asset).toEqual({
+        assetId: 2205400862,
+        revisionId: '1',
+        moderationState: 'Reviewing',
+      });
+      expect(urls).toEqual([
+        'https://apis.roblox.com/assets/v1/operations/abc',
+        'https://apis.roblox.com/assets/v1/operations/abc',
+      ]);
+    });
+
+    it('does not poll an operation that is already done', async () => {
+      const urls: string[] = [];
+      const client = new OpenCloudClient({
+        apiKey: 'test-key',
+        rateLimiter: makePollLimiter([], urls),
+      });
+
+      const asset = await client.pollAssetOperationAsync({
+        path: 'operations/abc',
+        done: true,
+        response: { assetId: 9 },
+      });
+
+      expect(asset.assetId).toBe(9);
+      expect(urls).toHaveLength(0);
+    });
+
+    it('throws the reason when the upload is rejected', async () => {
+      const client = new OpenCloudClient({
+        apiKey: 'test-key',
+        rateLimiter: makePollLimiter([
+          {
+            path: 'operations/abc',
+            done: true,
+            error: { code: 3, message: 'File type is not supported' },
+          },
+        ]),
+      });
+
+      await expect(
+        client.pollAssetOperationAsync({ path: 'operations/abc' })
+      ).rejects.toThrowError(/Asset upload failed: File type is not supported/);
+    });
+
+    it('gives up after the timeout, without calling the upload failed', async () => {
+      // An operation that outlives the wait may still produce an asset, so the
+      // caller has to be told to look before uploading the same file again.
+      const urls: string[] = [];
+      const client = new OpenCloudClient({
+        apiKey: 'test-key',
+        rateLimiter: makePollLimiter([{ path: 'operations/abc' }], urls),
+      });
+
+      await expect(
+        client.pollAssetOperationAsync({ path: 'operations/abc' }, 6000)
+      ).rejects.toThrowError(
+        /did not finish within 6s\. Roblox may still create the asset/
+      );
+      expect(urls).toHaveLength(3);
+    });
+
+    it('refuses a finished operation that carries no asset id', async () => {
+      const client = new OpenCloudClient({
+        apiKey: 'test-key',
+        rateLimiter: makePollLimiter([
+          { path: 'operations/abc', done: true, response: {} },
+        ]),
+      });
+
+      await expect(
+        client.pollAssetOperationAsync({ path: 'operations/abc' })
+      ).rejects.toThrowError(/finished without an asset id/);
+    });
+  });
+});
+
+describe('OpenCloudClient asset owner lookups', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  interface CapturedRequest {
+    url: string;
+    init?: RequestInit;
+  }
+
+  function makeLimiter(
+    body: unknown,
+    status = 200,
+    captured: CapturedRequest[] = []
+  ): RateLimiter {
+    return {
+      fetchAsync: vi.fn(async (url: string | URL, init?: RequestInit) => {
+        captured.push({ url: String(url), init });
+        return new Response(JSON.stringify(body), { status });
+      }),
+    } as unknown as RateLimiter;
+  }
+
+  it('reads a user-owned universe as that user', async () => {
+    const captured: CapturedRequest[] = [];
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeLimiter(
+        { path: 'universes/10', user: 'users/4397833' },
+        200,
+        captured
+      ),
+    });
+
+    expect(await client.getUniverseOwnerAsync(10)).toEqual({ userId: 4397833 });
+    expect(captured[0]?.url).toBe(
+      'https://apis.roblox.com/cloud/v2/universes/10'
+    );
+  });
+
+  it('reads a group-owned universe as that group', async () => {
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeLimiter({ path: 'universes/10', group: 'groups/77' }),
+    });
+
+    expect(await client.getUniverseOwnerAsync(10)).toEqual({ groupId: 77 });
+  });
+
+  it('throws when the universe cannot be read', async () => {
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeLimiter({}, 403),
+    });
+
+    await expect(client.getUniverseOwnerAsync(10)).rejects.toThrowError(
+      /Read universe 10 failed: 403/
+    );
+  });
+
+  it('asks Roblox which user the API key belongs to', async () => {
+    const captured: CapturedRequest[] = [];
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeLimiter(
+        { name: 'my-key', authorizedUserId: 4397833 },
+        200,
+        captured
+      ),
+    });
+
+    expect(await client.getApiKeyUserIdAsync()).toBe(4397833);
+    expect(captured[0]?.url).toBe(
+      'https://apis.roblox.com/api-keys/v1/introspect'
+    );
+    // Introspection takes the key in the body rather than the usual header.
+    expect(JSON.parse(captured[0]!.init!.body as string)).toEqual({
+      apiKey: 'test-key',
+    });
+  });
+
+  it('throws when the key does not name a user', async () => {
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeLimiter({ name: 'my-key' }),
+    });
+
+    await expect(client.getApiKeyUserIdAsync()).rejects.toThrowError(
+      /did not report which user/
+    );
+  });
+});
+
 describe('getTaskReturnValues', () => {
   function makeTask(overrides: Partial<LuauTask>): LuauTask {
     return {