@quenty/nevermore-cli 4.46.0 → 4.47.0

package/dist/utils/assets/asset-formats.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare const ASSET_TYPES: readonly ["Animation", "Audio", "Decal", "Image", "Model", "Video"];
+export type AssetType = typeof ASSET_TYPES[number];
+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 declare function resolveAssetFormat(filePath: string, explicitType?: AssetType): ResolvedAssetFormat;
+/**
+ * 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 declare function canUpdateAssetContent(assetType: AssetType): boolean;
+//# sourceMappingURL=asset-formats.d.ts.map

package/dist/utils/assets/asset-formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-formats.d.ts","sourceRoot":"","sources":["../../../src/utils/assets/asset-formats.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,qEAOd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;AAoCnD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,SAAS,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,SAAS,GACvB,mBAAmB,CAuBrB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAEnE"}

package/dist/utils/assets/asset-formats.js

@@ -0,0 +1,72 @@
+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',
+];
+// 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'];
+// A Roblox model file holds either, and nothing in its name says which.
+const ROBLOX_MODEL_TYPES = ['Model', 'Animation'];
+const ASSET_FILE_FORMATS = {
+    '.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'] },
+};
+/**
+ * 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, explicitType) {
+    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) {
+    return assetType === 'Model';
+}
+//# sourceMappingURL=asset-formats.js.map

package/dist/utils/assets/asset-formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-formats.js","sourceRoot":"","sources":["../../../src/utils/assets/asset-formats.ts"],"names":[],"mappings":"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"}

package/dist/utils/assets/asset-formats.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=asset-formats.test.d.ts.map

package/dist/utils/assets/asset-formats.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-formats.test.d.ts","sourceRoot":"","sources":["../../../src/utils/assets/asset-formats.test.ts"],"names":[],"mappings":""}

package/dist/utils/assets/asset-formats.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { canUpdateAssetContent, resolveAssetFormat } from './asset-formats.js';
+describe('resolveAssetFormat', () => {
+    it('reads the asset type and content type off the extension', () => {
+        expect(resolveAssetFormat('models/City.fbx')).toEqual({
+            assetType: 'Model',
+            contentType: 'model/fbx',
+        });
+        expect(resolveAssetFormat('sfx/click.ogg')).toEqual({
+            assetType: 'Audio',
+            contentType: 'audio/ogg',
+        });
+    });
+    it('ignores the case of the extension', () => {
+        expect(resolveAssetFormat('ICON.PNG').contentType).toBe('image/png');
+    });
+    it('uploads an image as an Image unless told Decal', () => {
+        expect(resolveAssetFormat('icon.png').assetType).toBe('Image');
+        expect(resolveAssetFormat('icon.png', 'Decal')).toEqual({
+            assetType: 'Decal',
+            contentType: 'image/png',
+        });
+    });
+    it('uploads an .rbxm as a Model unless told Animation', () => {
+        expect(resolveAssetFormat('rig.rbxm').assetType).toBe('Model');
+        expect(resolveAssetFormat('walk.rbxm', 'Animation').assetType).toBe('Animation');
+    });
+    it('refuses a type the extension cannot upload as', () => {
+        expect(() => resolveAssetFormat('icon.png', 'Audio')).toThrowError(/a "\.png" file uploads as Image or Decal/);
+    });
+    it('refuses an extension the API does not accept, naming the ones it does', () => {
+        expect(() => resolveAssetFormat('notes.txt')).toThrowError(/"\.txt" is not an asset format[\s\S]*\.fbx/);
+        expect(() => resolveAssetFormat('README')).toThrowError(/a file with no extension/);
+    });
+});
+describe('canUpdateAssetContent', () => {
+    it('is only true for models', () => {
+        expect(canUpdateAssetContent('Model')).toBe(true);
+        expect(canUpdateAssetContent('Image')).toBe(false);
+        expect(canUpdateAssetContent('Audio')).toBe(false);
+    });
+});
+//# sourceMappingURL=asset-formats.test.js.map

package/dist/utils/assets/asset-formats.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-formats.test.js","sourceRoot":"","sources":["../../../src/utils/assets/asset-formats.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE/E,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAC,CAAC,OAAO,CAAC;YACpD,SAAS,EAAE,OAAO;YAClB,WAAW,EAAE,WAAW;SACzB,CAAC,CAAC;QACH,MAAM,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC,CAAC,OAAO,CAAC;YAClD,SAAS,EAAE,OAAO;YAClB,WAAW,EAAE,WAAW;SACzB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/D,MAAM,CAAC,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;YACtD,SAAS,EAAE,OAAO;YAClB,WAAW,EAAE,WAAW;SACzB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC3D,MAAM,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/D,MAAM,CAAC,kBAAkB,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CACjE,WAAW,CACZ,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,YAAY,CAChE,0CAA0C,CAC3C,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uEAAuE,EAAE,GAAG,EAAE;QAC/E,MAAM,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CACxD,4CAA4C,CAC7C,CAAC;QACF,MAAM,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CACrD,0BAA0B,CAC3B,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,EAAE,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACjC,MAAM,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnD,MAAM,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/utils/assets/asset-upload-plan.d.ts

@@ -0,0 +1,27 @@
+import { 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 declare function buildAssetUploadPlan(options: AssetUploadPlanOptions): AssetUploadPlanEntry[];
+//# sourceMappingURL=asset-upload-plan.d.ts.map

package/dist/utils/assets/asset-upload-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-upload-plan.d.ts","sourceRoot":"","sources":["../../../src/utils/assets/asset-upload-plan.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,gEAAgE;IAChE,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,GAC9B,oBAAoB,EAAE,CA2CxB"}

package/dist/utils/assets/asset-upload-plan.js

@@ -0,0 +1,43 @@
+import * as path from 'path';
+import { canUpdateAssetContent, resolveAssetFormat, } from './asset-formats.js';
+/**
+ * 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) {
+    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,
+        };
+    });
+}
+//# sourceMappingURL=asset-upload-plan.js.map

package/dist/utils/assets/asset-upload-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-upload-plan.js","sourceRoot":"","sources":["../../../src/utils/assets/asset-upload-plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,GAEnB,MAAM,oBAAoB,CAAC;AAuB5B;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA+B;IAE/B,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAE5D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,+BAA+B,KAAK,CAAC,MAAM,qBAAqB;YAC9D,4CAA4C,CAC/C,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,sCAAsC,KAAK,CAAC,MAAM,oBAAoB,CACvE,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,IAAI,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;QAC5B,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,kBAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACtE,IAAI,OAAO,IAAI,IAAI,IAAI,CAAC,qBAAqB,CAAC,SAAS,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,KAAK,CACb,wBAAwB,OAAO,UAAU,QAAQ,oBAAoB;gBACnE,oDAAoD,SAAS,GAAG;gBAChE,mDAAmD,CACtD,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC5E,OAAO;YACL,QAAQ;YACR,SAAS;YACT,WAAW;YACX,WAAW;YACX,yEAAyE;YACzE,gDAAgD;YAChD,WAAW,EAAE,WAAW,IAAI,WAAW;YACvC,OAAO;SACR,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/assets/asset-upload-plan.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=asset-upload-plan.test.d.ts.map

package/dist/utils/assets/asset-upload-plan.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-upload-plan.test.d.ts","sourceRoot":"","sources":["../../../src/utils/assets/asset-upload-plan.test.ts"],"names":[],"mappings":""}

package/dist/utils/assets/asset-upload-plan.test.js

@@ -0,0 +1,57 @@
+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/);
+    });
+});
+//# sourceMappingURL=asset-upload-plan.test.js.map

package/dist/utils/assets/asset-upload-plan.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-upload-plan.test.js","sourceRoot":"","sources":["../../../src/utils/assets/asset-upload-plan.test.ts"],"names":[],"mappings":"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"}

package/dist/utils/open-cloud/open-cloud-client.d.ts

@@ -70,6 +70,56 @@ export interface OpenCloudClientOptions {
  * written in deploy.nevermore.json.
  */
 export type PlaceVersionType = 'saved' | 'published';
+/** Who owns a newly created asset. */
+export type AssetCreator = {
+    userId: number;
+} | {
+    groupId: number;
+};
+export interface AssetFile {
+    filePath: string;
+    /** MIME type of the file. The Assets API picks its importer from it. */
+    contentType: string;
+}
+export interface CreateAssetOptions extends AssetFile {
+    /** `Model`, `Image`, `Audio`, ... as the Assets API spells them. */
+    assetType: string;
+    displayName: string;
+    description: string;
+    creator: AssetCreator;
+}
+/**
+ * The long-running operation every asset upload returns. Creating an asset is
+ * not synchronous — the file is imported and moderated first — so the id only
+ * exists once the operation reports `done`.
+ */
+export interface AssetOperation {
+    /** `operations/{operationId}` */
+    path: string;
+    done?: boolean;
+    response?: {
+        /** A string in practice, though the API's own schema calls it an integer. */
+        assetId?: string | number;
+        revisionId?: string;
+        moderationResult?: {
+            moderationState?: string;
+        };
+    };
+    error?: {
+        code?: number | string;
+        message?: string;
+    };
+}
+export interface UploadedAsset {
+    assetId: number;
+    revisionId?: string;
+    /**
+     * `Approved`, `Reviewing`, ... exactly as the API reports it — which is not
+     * the `MODERATION_STATE_APPROVED` spelling its documentation shows. Audio
+     * routinely finishes uploading while still `Reviewing`.
+     */
+    moderationState?: string;
+}
 export declare class OpenCloudClient {
     private _apiKey;
     private _apiKeySource;
@@ -124,5 +174,32 @@ export declare class OpenCloudClient {
      * is capped so a never-published place fails fast instead of paging forever.
      */
     resolveLatestPlaceVersionAsync(universeId: number, placeId: number, versionType: PlaceVersionType): Promise<number>;
+    /**
+     * Start uploading a file as a new asset via the Open Cloud Assets API
+     * (`asset:read` and `asset:write`). Returns the operation to hand to
+     * {@link pollAssetOperationAsync}; the asset has no id until that finishes.
+     */
+    createAssetAsync(options: CreateAssetOptions): Promise<AssetOperation>;
+    /**
+     * Start replacing an existing asset's file, keeping its id — the upload
+     * becomes a new version of the same asset. The API only does this for models.
+     */
+    updateAssetContentAsync(assetId: number, file: AssetFile): Promise<AssetOperation>;
+    /**
+     * Wait for an asset upload to finish and return the asset it produced.
+     *
+     * Throws if the operation reports an error or outlives `timeoutMs`. A timeout
+     * is not a failed upload: Roblox may still finish creating the asset, which
+     * is why the message says to look before uploading again.
+     */
+    pollAssetOperationAsync(operation: AssetOperation, timeoutMs?: number): Promise<UploadedAsset>;
+    /**
+     * Who owns a universe: the user or group its assets should belong to if the
+     * experience is to use them. Needs no scope beyond a valid key.
+     */
+    getUniverseOwnerAsync(universeId: number): Promise<AssetCreator>;
+    /** The user the API key acts as — whoever created it. */
+    getApiKeyUserIdAsync(): Promise<number>;
+    private _sendAssetAsync;
 }
 //# sourceMappingURL=open-cloud-client.d.ts.map

package/dist/utils/open-cloud/open-cloud-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"open-cloud-client.d.ts","sourceRoot":"","sources":["../../../src/utils/open-cloud/open-cloud-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"open-cloud-client.d.ts","sourceRoot":"","sources":["../../../src/utils/open-cloud/open-cloud-client.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAkB,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EACD,mBAAmB,GACnB,QAAQ,GACR,YAAY,GACZ,WAAW,GACX,UAAU,GACV,QAAQ,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IACjC,2CAA2C;IAC3C,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,EAAE,GAAG,SAAS,CAKzE;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACzC,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,WAAW,CAAC;AAErD,sCAAsC;AACtC,MAAM,MAAM,YAAY,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAmB,SAAQ,SAAS;IACnD,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE;QACT,6EAA6E;QAC7E,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE;YAAE,eAAe,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACjD,CAAC;IACF,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoGD,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,YAAY,CAAc;gBAEtB,OAAO,EAAE,sBAAsB;YAQ7B,mBAAmB;IAW3B,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,EACjB,UAAU,CAAC,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,GAClE,OAAO,CAAC,MAAM,CAAC;IA4FZ,wBAAwB,CAC5B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,QAAQ,CAAC;IAyDd,uBAAuB,CAC3B,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,IAAI,GAC9C,OAAO,CAAC,QAAQ,CAAC;IAkCd,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAKjE;;;;;;;OAOG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;YAuBpD,kBAAkB;IAmFhC;;;;;;;;OAQG;IACG,kBAAkB,CACtB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,EACnE,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC;IAoElB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,8BAA8B,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,MAAM,CAAC;IA2FlB;;;;OAIG;IACG,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;IAoB5E;;;OAGG;IACG,uBAAuB,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,CAAC;IAS1B;;;;;;OAMG;IACG,uBAAuB,CAC3B,SAAS,EAAE,cAAc,EACzB,SAAS,GAAE,MAAmC,GAC7C,OAAO,CAAC,aAAa,CAAC;IA6DzB;;;OAGG;IACG,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA8BtE,yDAAyD;IACnD,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC;YAuB/B,eAAe;CAwC9B"}

package/dist/utils/open-cloud/open-cloud-client.js

@@ -1,4 +1,5 @@
 import * as fs from 'fs/promises';
+import * as path from 'path';
 import { Readable, Transform } from 'node:stream';
 import nodeFetch from 'node-fetch';
 import { OutputHelper } from '@quenty/cli-output-helpers';
@@ -17,21 +18,49 @@ export function getTaskReturnValues(task) {
     }
     return task.output.results ?? [];
 }
-function formatAuthError(action, scope, universeId, placeId, status, statusText, body, method, url) {
-    // Extract human-readable message from JSON body if possible
-    let apiMessage = '';
+const ASSETS_API_URL = 'https://apis.roblox.com/assets/v1';
+const ASSET_OPERATION_POLL_MS = 2000;
+const ASSET_OPERATION_TIMEOUT_MS = 5 * 60 * 1000;
+/** Pull the human-readable message out of an Open Cloud error body. */
+function _extractApiMessage(body) {
     try {
         const parsed = JSON.parse(body);
         if (Array.isArray(parsed.errors) && parsed.errors[0]?.message) {
-            apiMessage = parsed.errors[0].message;
+            return parsed.errors[0].message;
         }
-        else if (typeof parsed.message === 'string') {
-            apiMessage = parsed.message;
+        if (typeof parsed.message === 'string') {
+            return parsed.message;
         }
     }
     catch {
         // Not JSON
     }
+    return '';
+}
+function formatAssetApiError(action, status, statusText, body, method, url) {
+    if (status !== 401 && status !== 403) {
+        return `${action} failed: ${status} ${statusText}: ${body}`;
+    }
+    const apiMessage = _extractApiMessage(body);
+    const headline = apiMessage
+        ? `${action} failed: ${apiMessage} (${status})`
+        : `${action} failed: ${status} ${statusText}`;
+    const dim = OutputHelper.formatDim;
+    const info = OutputHelper.formatInfo;
+    return [
+        OutputHelper.formatError(headline),
+        '',
+        `  ${dim('Scope:')}       asset:read, asset:write`,
+        '',
+        OutputHelper.formatWarning('Ensure the API key has the Assets API with both Read and Write, and ' +
+            'that its owner may create assets for the user or group named as creator.'),
+        '',
+        `  ${dim('Credentials:')} ${info('https://create.roblox.com/dashboard/credentials')}`,
+        `  ${dim('Route:')}       ${dim(`${method} ${url}`)}`,
+    ].join('\n');
+}
+function formatAuthError(action, scope, universeId, placeId, status, statusText, body, method, url) {
+    const apiMessage = _extractApiMessage(body);
     const headline = apiMessage
         ? `${action} failed: ${apiMessage} (${status})`
         : `${action} failed: ${status} ${statusText}`;
@@ -404,6 +433,137 @@ export class OpenCloudClient {
                 : '') +
             `. Pin an explicit version number in deploy.nevermore.json, or publish the place once.`);
     }
+    /**
+     * Start uploading a file as a new asset via the Open Cloud Assets API
+     * (`asset:read` and `asset:write`). Returns the operation to hand to
+     * {@link pollAssetOperationAsync}; the asset has no id until that finishes.
+     */
+    async createAssetAsync(options) {
+        const { creator } = options;
+        return this._sendAssetAsync('POST', `${ASSETS_API_URL}/assets`, {
+            assetType: options.assetType,
+            displayName: options.displayName,
+            description: options.description,
+            creationContext: {
+                creator: 'userId' in creator
+                    ? { userId: String(creator.userId) }
+                    : { groupId: String(creator.groupId) },
+            },
+        }, options);
+    }
+    /**
+     * Start replacing an existing asset's file, keeping its id — the upload
+     * becomes a new version of the same asset. The API only does this for models.
+     */
+    async updateAssetContentAsync(assetId, file) {
+        return this._sendAssetAsync('PATCH', `${ASSETS_API_URL}/assets/${assetId}`, { assetId }, file);
+    }
+    /**
+     * Wait for an asset upload to finish and return the asset it produced.
+     *
+     * Throws if the operation reports an error or outlives `timeoutMs`. A timeout
+     * is not a failed upload: Roblox may still finish creating the asset, which
+     * is why the message says to look before uploading again.
+     */
+    async pollAssetOperationAsync(operation, timeoutMs = ASSET_OPERATION_TIMEOUT_MS) {
+        const apiKey = await this._resolveApiKeyAsync();
+        const url = `${ASSETS_API_URL}/${operation.path}`;
+        const maxPolls = Math.ceil(timeoutMs / ASSET_OPERATION_POLL_MS);
+        let current = operation;
+        for (let poll = 0; !current.done && poll < maxPolls; poll++) {
+            await new Promise((resolve) => setTimeout(resolve, ASSET_OPERATION_POLL_MS));
+            const response = await this._rateLimiter.fetchAsync(url, {
+                method: 'GET',
+                headers: { 'x-api-key': apiKey },
+            });
+            if (!response.ok) {
+                throw new Error(formatAssetApiError('Read asset upload status', response.status, response.statusText, await response.text(), 'GET', url));
+            }
+            current = (await response.json());
+        }
+        if (!current.done) {
+            throw new Error(`Asset upload ${operation.path} did not finish within ` +
+                `${Math.round(timeoutMs / 1000)}s. Roblox may still create the ` +
+                `asset — check https://create.roblox.com/dashboard/creations ` +
+                `before uploading it again.`);
+        }
+        if (current.error) {
+            throw new Error(`Asset upload failed: ${current.error.message ?? JSON.stringify(current.error)}`);
+        }
+        const assetId = Number(current.response?.assetId);
+        if (!Number.isSafeInteger(assetId) || assetId < 1) {
+            throw new Error(`Asset upload ${operation.path} finished without an asset id: ` +
+                JSON.stringify(current));
+        }
+        return {
+            assetId,
+            revisionId: current.response?.revisionId,
+            moderationState: current.response?.moderationResult?.moderationState,
+        };
+    }
+    /**
+     * Who owns a universe: the user or group its assets should belong to if the
+     * experience is to use them. Needs no scope beyond a valid key.
+     */
+    async getUniverseOwnerAsync(universeId) {
+        const apiKey = await this._resolveApiKeyAsync();
+        const url = `https://apis.roblox.com/cloud/v2/universes/${universeId}`;
+        const response = await this._rateLimiter.fetchAsync(url, {
+            method: 'GET',
+            headers: { 'x-api-key': apiKey },
+        });
+        if (!response.ok) {
+            throw new Error(`Read universe ${universeId} failed: ${response.status} ${response.statusText}`);
+        }
+        // Exactly one of the two is present: `users/123` or `groups/456`.
+        const universe = (await response.json());
+        const userId = Number(universe.user?.match(/^users\/(\d+)$/)?.[1]);
+        if (Number.isSafeInteger(userId)) {
+            return { userId };
+        }
+        const groupId = Number(universe.group?.match(/^groups\/(\d+)$/)?.[1]);
+        if (Number.isSafeInteger(groupId)) {
+            return { groupId };
+        }
+        throw new Error(`Universe ${universeId} did not report an owner`);
+    }
+    /** The user the API key acts as — whoever created it. */
+    async getApiKeyUserIdAsync() {
+        const apiKey = await this._resolveApiKeyAsync();
+        const url = 'https://apis.roblox.com/api-keys/v1/introspect';
+        // The key travels in the body here, not the usual header.
+        const response = await this._rateLimiter.fetchAsync(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ apiKey }),
+        });
+        if (!response.ok) {
+            throw new Error(`Read API key owner failed: ${response.status} ${response.statusText}`);
+        }
+        const key = (await response.json());
+        if (!Number.isSafeInteger(key.authorizedUserId)) {
+            throw new Error('The API key did not report which user it belongs to');
+        }
+        return key.authorizedUserId;
+    }
+    async _sendAssetAsync(method, url, request, file) {
+        const apiKey = await this._resolveApiKeyAsync();
+        const fileBuffer = await fs.readFile(file.filePath);
+        const form = new FormData();
+        form.append('request', JSON.stringify(request));
+        form.append('fileContent', new Blob([new Uint8Array(fileBuffer)], { type: file.contentType }), path.basename(file.filePath));
+        // No Content-Type header: fetch writes the multipart boundary itself, and
+        // setting one by hand sends a body the API cannot split into parts.
+        const response = await this._rateLimiter.fetchAsync(url, {
+            method,
+            headers: { 'x-api-key': apiKey },
+            body: form,
+        });
+        if (!response.ok) {
+            throw new Error(formatAssetApiError(method === 'POST' ? 'Create asset' : 'Update asset', response.status, response.statusText, await response.text(), method, url));
+        }
+        return (await response.json());
+    }
 }
 const VERSION_SCAN_PAGE_SIZE = 50;
 const VERSION_SCAN_MAX_PAGES = 20;