@quenty/nevermore-cli 4.46.0 → 4.47.1

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/build/upload.ts

@@ -4,6 +4,7 @@ import {
 } from '@quenty/nevermore-cli-helpers';
 import { type DeployTarget } from '@quenty/nevermore-deploy';
 import { OpenCloudClient } from '../open-cloud/open-cloud-client.js';
+import { reportRateLimitWait } from '../open-cloud/rate-limiter.js';
 import { type BuiltPlace } from './build.js';
 import { type Reporter } from '@quenty/cli-output-helpers/reporting';
 
@@ -53,7 +54,10 @@ export async function uploadPlaceAsync(
     target.placeId,
     rbxlPath,
     args.publish,
-    onProgress
+    onProgress,
+    reporter && packageName
+      ? reportRateLimitWait(reporter, packageName)
+      : undefined
   );
 
   return { client, apiKey, target, version };

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

@@ -4,6 +4,7 @@ import {
   type LuauTask,
   type OpenCloudClient,
 } from '../open-cloud/open-cloud-client.js';
+import { reportRateLimitWait } from '../open-cloud/rate-limiter.js';
 import { tryRenamePlaceAsync } from '@quenty/nevermore-cli-helpers';
 import { buildPlaceNameAsync, timeoutAsync } from '../nevermore-cli-utils.js';
 import {
@@ -60,7 +61,8 @@ export class CloudJobContext extends BaseJobContext {
           transferredBytes: transferred,
           totalBytes: total,
         });
-      }
+      },
+      reportRateLimitWait(this._reporter, packageName)
     );
 
     // Eagerly release build artifacts after upload (disposeAsync is safety net)
@@ -82,13 +84,16 @@ export class CloudJobContext extends BaseJobContext {
     const cloudDeployment = deployment as CloudDeployment;
     const { scriptContent, packageName, timeoutMs = 120_000 } = options;
 
+    const onRateLimitWait = reportRateLimitWait(this._reporter, packageName);
+
     this._reporter.onPackagePhaseChange(packageName, 'scheduling');
     const task = await this._openCloudClient!.createExecutionTaskAsync(
       cloudDeployment.universeId,
       cloudDeployment.placeId,
       cloudDeployment.version,
       scriptContent,
-      timeoutMs
+      timeoutMs,
+      onRateLimitWait
     );
 
     // Give the server-side timeout a head start so we observe the cancelled
@@ -97,19 +102,23 @@ export class CloudJobContext extends BaseJobContext {
 
     let pollCount = 0;
     const completedTask = await Promise.race([
-      this._openCloudClient!.pollTaskCompletionAsync(task.path, (state) => {
-        pollCount++;
-        if (state === 'PROCESSING') {
-          this._reporter.onPackagePhaseChange(packageName, 'executing');
-        }
-        const label = state === 'QUEUED' ? 'queued' : `poll #${pollCount}`;
-        this._reporter.onPackageProgressUpdate(packageName, {
-          kind: 'steps',
-          completed: pollCount,
-          total: 0,
-          label,
-        });
-      }),
+      this._openCloudClient!.pollTaskCompletionAsync(
+        task.path,
+        (state) => {
+          pollCount++;
+          if (state === 'PROCESSING') {
+            this._reporter.onPackagePhaseChange(packageName, 'executing');
+          }
+          const label = state === 'QUEUED' ? 'queued' : `poll #${pollCount}`;
+          this._reporter.onPackageProgressUpdate(packageName, {
+            kind: 'steps',
+            completed: pollCount,
+            total: 0,
+            label,
+          });
+        },
+        onRateLimitWait
+      ),
       timeoutAsync(
         timeoutMs + CLIENT_TIMEOUT_GRACE_MS,
         `Test timed out after ${timeoutMs / 1000}s`