@quenty/nevermore-cli 4.45.0 → 4.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/nevermore-cli",
-  "version": "4.45.0",
+  "version": "4.47.0",
   "description": "CLI interface for Nevermore",
   "type": "module",
   "keywords": [
@@ -26,10 +26,10 @@
   ],
   "dependencies": {
     "@quenty/cli-output-helpers": "1.18.0",
-    "@quenty/nevermore-cli-helpers": "1.18.0",
+    "@quenty/nevermore-cli-helpers": "1.19.0",
     "@quenty/nevermore-deploy": "1.1.1",
-    "@quenty/nevermore-template-helpers": "1.19.0",
-    "@quenty/studio-bridge": "0.19.0",
+    "@quenty/nevermore-template-helpers": "1.20.0",
+    "@quenty/studio-bridge": "0.21.0",
     "execa": "^9.6.1",
     "find-git-root": "^1.0.4",
     "inquirer": "^13.2.0",
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=16"
   },
-  "gitHead": "346201e192e467cb71160f43029863853be855b5"
+  "gitHead": "6b26147a6b432f17270769342498b4f2f08f60b1"
 }

package/src/commands/deploy-command/asset-command.ts

@@ -0,0 +1,279 @@
+import * as fs from 'fs/promises';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  CompositeResultReporter,
+  FileResultReporter,
+  StdoutResultReporter,
+  formatJson,
+  formatTable,
+  type ResultReporter,
+  type TableColumn,
+} from '@quenty/cli-output-helpers/reporting';
+import { getApiKeyAsync } from '@quenty/nevermore-cli-helpers';
+import { NevermoreGlobalArgs } from '../../args/global-args.js';
+import { discoverUniverseIdAsync } from '@quenty/nevermore-deploy';
+import {
+  formatAssetCreator,
+  resolveAssetCreatorAsync,
+} from '../../utils/assets/asset-creator.js';
+import { type AssetType } from '../../utils/assets/asset-formats.js';
+import {
+  buildAssetUploadPlan,
+  type AssetUploadPlanEntry,
+} from '../../utils/assets/asset-upload-plan.js';
+import {
+  OpenCloudClient,
+  type AssetCreator,
+} from '../../utils/open-cloud/open-cloud-client.js';
+import { RateLimiter } from '../../utils/open-cloud/rate-limiter.js';
+
+export interface AssetUploadArgs extends NevermoreGlobalArgs {
+  files?: string[];
+  apiKey?: string;
+  type?: AssetType;
+  name?: string;
+  description?: string;
+  userId?: number;
+  groupId?: number;
+  assetId?: number;
+  output?: string;
+  timeout?: number;
+}
+
+/** What happened to one file. Written to `--output` as-is. */
+export interface AssetUploadResult {
+  file: string;
+  assetType: AssetType;
+  displayName: string;
+  action: 'created' | 'updated';
+  success: boolean;
+  assetId?: number;
+  /** `rbxassetid://<assetId>`, ready to paste into a content property. */
+  assetUri?: string;
+  revisionId?: string;
+  moderationState?: string;
+  error?: string;
+}
+
+export interface AssetUploadReport {
+  /** Who owns the assets this run created. Absent when it only replaced one. */
+  creator?: AssetCreator;
+  assets: AssetUploadResult[];
+}
+
+function _plural(count: number): string {
+  return count === 1 ? '' : 's';
+}
+
+function _action(entry: AssetUploadPlanEntry): AssetUploadResult['action'] {
+  return entry.assetId == null ? 'created' : 'updated';
+}
+
+/**
+ * Who will own the created assets, announced so an inferred owner is never a
+ * surprise. Only a create needs one — replacing an asset's content leaves its
+ * owner alone, so a run that is all `--asset-id` asks nobody.
+ */
+async function _resolveCreatorAsync(
+  args: AssetUploadArgs,
+  plan: AssetUploadPlanEntry[],
+  client: OpenCloudClient
+): Promise<AssetCreator | undefined> {
+  if (plan.every((entry) => entry.assetId != null)) {
+    return undefined;
+  }
+
+  const { creator, reason } = await resolveAssetCreatorAsync({
+    userId: args.userId,
+    groupId: args.groupId,
+    universeId: await discoverUniverseIdAsync(process.cwd()),
+    source: client,
+    onFallback: (message) => OutputHelper.warn(message),
+  });
+  OutputHelper.info(`Owner: ${formatAssetCreator(creator)} (${reason})`);
+  return creator;
+}
+
+async function _requireFilesAsync(plan: AssetUploadPlanEntry[]): Promise<void> {
+  for (const entry of plan) {
+    let isFile = false;
+    try {
+      isFile = (await fs.stat(entry.filePath)).isFile();
+    } catch {
+      // Reported below
+    }
+    if (!isFile) {
+      throw new Error(`Cannot upload "${entry.filePath}": no such file.`);
+    }
+  }
+}
+
+async function _uploadAsync(
+  client: OpenCloudClient,
+  entry: AssetUploadPlanEntry,
+  creator: AssetCreator | undefined,
+  timeoutMs: number
+): Promise<AssetUploadResult> {
+  const result: AssetUploadResult = {
+    file: entry.filePath,
+    assetType: entry.assetType,
+    displayName: entry.displayName,
+    action: _action(entry),
+    success: false,
+  };
+
+  try {
+    const operation =
+      entry.assetId != null
+        ? await client.updateAssetContentAsync(entry.assetId, entry)
+        : await client.createAssetAsync({ ...entry, creator: creator! });
+    OutputHelper.verbose(`${entry.filePath}: waiting on ${operation.path}`);
+
+    const asset = await client.pollAssetOperationAsync(operation, timeoutMs);
+    return {
+      ...result,
+      success: true,
+      assetId: asset.assetId,
+      assetUri: `rbxassetid://${asset.assetId}`,
+      revisionId: asset.revisionId,
+      moderationState: asset.moderationState,
+    };
+  } catch (err) {
+    return {
+      ...result,
+      error: OutputHelper.stripAnsi(
+        err instanceof Error ? err.message : String(err)
+      ),
+    };
+  }
+}
+
+function _renderTable(report: AssetUploadReport): string {
+  const columns: TableColumn<AssetUploadResult>[] = [
+    { header: 'File', value: (r) => r.file },
+    { header: 'Type', value: (r) => r.assetType },
+    {
+      header: 'Result',
+      value: (r) => (r.success ? r.action : 'FAILED'),
+      format: (value, r) =>
+        r.success ? value : OutputHelper.formatError(value),
+    },
+    { header: 'Asset', value: (r) => r.assetUri ?? '' },
+    { header: 'Moderation', value: (r) => r.moderationState ?? '' },
+  ];
+  return formatTable(report.assets, columns);
+}
+
+function _buildReporter(
+  outputPath: string | undefined
+): ResultReporter<AssetUploadReport> {
+  const reporters: ResultReporter<AssetUploadReport>[] = [
+    new StdoutResultReporter({ render: _renderTable }),
+  ];
+  if (outputPath != null) {
+    reporters.push(
+      new FileResultReporter({
+        outputPath,
+        render: (report) => formatJson(report, { pretty: true }) + '\n',
+      })
+    );
+  }
+  return new CompositeResultReporter(reporters);
+}
+
+/**
+ * `nevermore deploy asset upload <files..>` — upload files as Roblox assets
+ * through the Open Cloud Assets API and print the id each one was given.
+ *
+ * Every file is attempted and reported, even after one fails. The assets that
+ * did upload now exist, so their ids are the one thing a failed run must not
+ * lose.
+ */
+export async function handleAssetUploadAsync(
+  args: AssetUploadArgs
+): Promise<void> {
+  const plan = buildAssetUploadPlan({
+    files: args.files ?? [],
+    type: args.type,
+    name: args.name,
+    description: args.description,
+    assetId: args.assetId,
+  });
+  await _requireFilesAsync(plan);
+
+  // The key is only resolved when something asks for it, so a dryrun that was
+  // told its owner still runs without credentials.
+  const client = new OpenCloudClient({
+    apiKey: () => getApiKeyAsync(args),
+    rateLimiter: new RateLimiter(),
+  });
+  const creator = await _resolveCreatorAsync(args, plan, client);
+
+  if (args.dryrun) {
+    OutputHelper.info(
+      `[DRYRUN] Would upload ${plan.length} asset${_plural(plan.length)}:`
+    );
+    const columns: TableColumn<AssetUploadPlanEntry>[] = [
+      { header: 'File', value: (e) => e.filePath },
+      { header: 'Type', value: (e) => e.assetType },
+      { header: 'Name', value: (e) => e.displayName },
+      {
+        header: 'Action',
+        value: (e) =>
+          e.assetId == null ? 'create' : `replace asset ${e.assetId}`,
+      },
+    ];
+    console.log(formatTable(plan, columns, { indent: '  ' }));
+    return;
+  }
+
+  const timeoutMs = (args.timeout ?? 300) * 1000;
+
+  OutputHelper.info(`Uploading ${plan.length} asset${_plural(plan.length)}...`);
+  // The rate limiter caps how many of these are in flight at once.
+  const report: AssetUploadReport = {
+    creator,
+    assets: await Promise.all(
+      plan.map((entry) => _uploadAsync(client, entry, creator, timeoutMs))
+    ),
+  };
+
+  const reporter = _buildReporter(args.output);
+  await reporter.startAsync();
+  reporter.onResult(report);
+  await reporter.stopAsync();
+
+  // An upload normally finishes while Roblox is still reviewing it, so this is
+  // a note on the table rather than a warning per file.
+  const unapproved = report.assets.filter(
+    (asset) =>
+      asset.success &&
+      asset.moderationState != null &&
+      !/approved$/i.test(asset.moderationState)
+  );
+  if (unapproved.length > 0) {
+    OutputHelper.hint(
+      `${unapproved.length} asset${_plural(unapproved.length)} not approved ` +
+        `by moderation yet. The id is final, but the asset may not load until ` +
+        `Roblox approves it.`
+    );
+  }
+
+  // One bad key fails every file the same way, so identical errors are
+  // reported once against all the files they hit.
+  const filesByError = new Map<string, string[]>();
+  for (const asset of report.assets) {
+    if (!asset.success) {
+      const error = asset.error ?? 'unknown error';
+      filesByError.set(error, [...(filesByError.get(error) ?? []), asset.file]);
+    }
+  }
+  for (const [error, files] of filesByError) {
+    OutputHelper.error(`${files.join(', ')}: ${error}`);
+  }
+  if (filesByError.size > 0) {
+    // Not process.exit(): on Windows, exiting while fetch's sockets are still
+    // closing aborts Node with a libuv assertion and exit code 127.
+    process.exitCode = 1;
+  }
+}

package/src/commands/deploy-command/index.ts

@@ -75,6 +75,11 @@ import {
   type VersionPromoteArgs,
 } from './version-command.js';
 import { selectTargetAsync } from './select-target.js';
+import {
+  handleAssetUploadAsync,
+  type AssetUploadArgs,
+} from './asset-command.js';
+import { ASSET_TYPES } from '../../utils/assets/asset-formats.js';
 
 const MULTI_PLACE_CONCURRENCY = 10;
 
@@ -253,6 +258,86 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
       () => {}
     );
 
+    args.command(
+      'asset',
+      'Upload files as Roblox assets (images, models, audio, ...)',
+      (yargs) => {
+        return yargs
+          .command(
+            'upload <files..>',
+            'Upload files as assets and print the id each one was given',
+            (uploadYargs) => {
+              return uploadYargs
+                .positional('files', {
+                  describe:
+                    'Files to upload. The asset type comes from each extension.',
+                  type: 'string',
+                  array: true,
+                })
+                .option('user-id', {
+                  describe:
+                    'Roblox user who will own the new assets. Without this or --group-id, ' +
+                    'the owner of the universe in the nearest deploy.nevermore.json, else the owner of the API key',
+                  type: 'number',
+                })
+                .option('group-id', {
+                  describe: 'Roblox group who will own the new assets',
+                  type: 'number',
+                })
+                .option('type', {
+                  describe:
+                    'Asset type, where the extension allows more than one: ' +
+                    'an image is an Image unless told Decal, an .rbxm a Model unless told Animation',
+                  type: 'string',
+                  choices: ASSET_TYPES,
+                })
+                .option('name', {
+                  describe:
+                    'Display name (single file only; defaults to the file name)',
+                  type: 'string',
+                })
+                .option('description', {
+                  describe: 'Description (defaults to the display name)',
+                  type: 'string',
+                })
+                .option('asset-id', {
+                  describe:
+                    'Replace this existing asset instead of creating one, keeping its id (single Model file only)',
+                  type: 'number',
+                })
+                .option('output', {
+                  describe: 'Write JSON results to this file',
+                  type: 'string',
+                })
+                .option('timeout', {
+                  describe:
+                    'Seconds to wait for Roblox to finish importing each file',
+                  type: 'number',
+                  default: 300,
+                })
+                .option('api-key', {
+                  describe: 'Roblox Open Cloud API key',
+                  type: 'string',
+                });
+            },
+            async (uploadArgs) => {
+              try {
+                await handleAssetUploadAsync(
+                  uploadArgs as unknown as AssetUploadArgs
+                );
+              } catch (err) {
+                OutputHelper.error(
+                  err instanceof Error ? err.message : String(err)
+                );
+                process.exitCode = 1;
+              }
+            }
+          )
+          .demandCommand(1, 'Specify an asset action, e.g. "upload".');
+      },
+      () => {}
+    );
+
     args.command(
       ['run [target]', '$0 [target]'],
       'Deploy a target from deploy.nevermore.json',

package/src/commands/init-command/init-game-command.ts

@@ -85,7 +85,7 @@ export class InitGameCommand<T> implements CommandModule<T, InitGameArgs> {
   public async handler(args: InitGameArgs) {
     const rawGameName = await InitGameCommand._ensureGameName(args);
 
-    const gameName = TemplateHelper.camelize(rawGameName).toLowerCase();
+    const gameName = TemplateHelper.toPackageName(rawGameName);
     const gameNameProper = TemplateHelper.camelize(rawGameName);
 
     const srcRoot = process.cwd();

package/src/commands/init-command/init-package-command.ts

@@ -51,7 +51,7 @@ export class InitPackageCommand<T>
   public handler = async (args: InitPackageArgs) => {
     let rawPackageName = await InitPackageCommand._ensurePackageName(args);
 
-    const packageName = TemplateHelper.camelize(rawPackageName).toLowerCase();
+    const packageName = TemplateHelper.toPackageName(rawPackageName);
     const packageNameProper = TemplateHelper.camelize(rawPackageName);
     const description = await InitPackageCommand._ensureDescription(args);
 
@@ -71,6 +71,7 @@ export class InitPackageCommand<T>
       {
         packageName: packageName,
         packageNameProper: packageNameProper,
+        packageNameIndex: TemplateHelper.toIndexExpression(packageName),
         description: description,
       },
       args.dryrun

package/src/commands/init-command/init-plugin-command.ts

@@ -35,7 +35,7 @@ export class InitPluginCommand<T> implements CommandModule<T, initGameArgs> {
   public handler = async (args: initGameArgs) => {
     const rawPluginName = await InitPluginCommand._ensurePluginName(args);
 
-    const pluginName = TemplateHelper.camelize(rawPluginName).toLowerCase();
+    const pluginName = TemplateHelper.toPackageName(rawPluginName);
     const pluginNameProper = TemplateHelper.camelize(rawPluginName);
 
     const srcRoot = process.cwd();

package/src/utils/assets/asset-creator.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  formatAssetCreator,
+  resolveAssetCreatorAsync,
+  type AssetCreatorSource,
+} from './asset-creator.js';
+
+function makeSource(
+  overrides: Partial<AssetCreatorSource> = {}
+): AssetCreatorSource {
+  return {
+    getUniverseOwnerAsync: vi.fn(async () => ({ groupId: 77 })),
+    getApiKeyUserIdAsync: vi.fn(async () => 4397833),
+    ...overrides,
+  };
+}
+
+describe('resolveAssetCreatorAsync', () => {
+  it('takes an explicit owner without asking Roblox anything', async () => {
+    const source = makeSource();
+
+    expect(
+      await resolveAssetCreatorAsync({ userId: 5, universeId: 1, source })
+    ).toEqual({ creator: { userId: 5 }, reason: '--user-id' });
+    expect(
+      await resolveAssetCreatorAsync({ groupId: 6, universeId: 1, source })
+    ).toEqual({ creator: { groupId: 6 }, reason: '--group-id' });
+
+    expect(source.getUniverseOwnerAsync).not.toHaveBeenCalled();
+    expect(source.getApiKeyUserIdAsync).not.toHaveBeenCalled();
+  });
+
+  it('refuses both owner flags, and an id that is not one', async () => {
+    const source = makeSource();
+
+    await expect(
+      resolveAssetCreatorAsync({ userId: 5, groupId: 6, source })
+    ).rejects.toThrowError(/--user-id or --group-id, not both/);
+    await expect(
+      resolveAssetCreatorAsync({ userId: NaN, source })
+    ).rejects.toThrowError(/--user-id must be a positive integer/);
+  });
+
+  it("prefers the project universe's owner over the key's", async () => {
+    // In a group's game the person holding the key is the wrong owner: the
+    // experience loads assets its own creator owns.
+    const source = makeSource();
+
+    expect(await resolveAssetCreatorAsync({ universeId: 123, source })).toEqual(
+      {
+        creator: { groupId: 77 },
+        reason: 'owns universe 123, from deploy.nevermore.json',
+      }
+    );
+    expect(source.getApiKeyUserIdAsync).not.toHaveBeenCalled();
+  });
+
+  it("uses the API key's owner outside a project", async () => {
+    const source = makeSource();
+
+    expect(await resolveAssetCreatorAsync({ source })).toEqual({
+      creator: { userId: 4397833 },
+      reason: 'owns the API key',
+    });
+    expect(source.getUniverseOwnerAsync).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the key's owner, out loud, when the universe is unreadable", async () => {
+    const onFallback = vi.fn();
+    const source = makeSource({
+      getUniverseOwnerAsync: vi.fn(async () => {
+        throw new Error('Read universe 123 failed: 403 Forbidden');
+      }),
+    });
+
+    const resolved = await resolveAssetCreatorAsync({
+      universeId: 123,
+      source,
+      onFallback,
+    });
+
+    expect(resolved.creator).toEqual({ userId: 4397833 });
+    expect(onFallback).toHaveBeenCalledWith(
+      expect.stringMatching(/universe 123 \(.*403 Forbidden\)/)
+    );
+  });
+
+  it('says which flags to pass when no owner can be inferred', async () => {
+    const source = makeSource({
+      getApiKeyUserIdAsync: vi.fn(async () => {
+        throw new Error('Read API key owner failed: 401 Unauthorized');
+      }),
+    });
+
+    await expect(resolveAssetCreatorAsync({ source })).rejects.toThrowError(
+      /401 Unauthorized[\s\S]*--user-id <id>[\s\S]*--group-id <id>/
+    );
+  });
+});
+
+describe('formatAssetCreator', () => {
+  it('names the kind of owner', () => {
+    expect(formatAssetCreator({ userId: 5 })).toBe('user 5');
+    expect(formatAssetCreator({ groupId: 6 })).toBe('group 6');
+  });
+});

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

@@ -0,0 +1,96 @@
+import { type AssetCreator } from '../open-cloud/open-cloud-client.js';
+
+/** The two lookups an owner can be inferred from; `OpenCloudClient` is one. */
+export interface AssetCreatorSource {
+  getUniverseOwnerAsync(universeId: number): Promise<AssetCreator>;
+  getApiKeyUserIdAsync(): Promise<number>;
+}
+
+export interface ResolveAssetCreatorOptions {
+  userId?: number;
+  groupId?: number;
+  /** The universe of the nearest deploy.nevermore.json, when there is one. */
+  universeId?: number;
+  source: AssetCreatorSource;
+  /** Told when an inference had to be skipped, so the fallback is not silent. */
+  onFallback?: (message: string) => void;
+}
+
+export interface ResolvedAssetCreator {
+  creator: AssetCreator;
+  /** Why this owner, for the line that tells the user who it will be. */
+  reason: string;
+}
+
+export function formatAssetCreator(creator: AssetCreator): string {
+  return 'userId' in creator
+    ? `user ${creator.userId}`
+    : `group ${creator.groupId}`;
+}
+
+/**
+ * Decide who owns newly uploaded assets, so a bare
+ * `nevermore deploy asset upload icon.png` works.
+ *
+ * An explicit flag wins. Otherwise the owner of the surrounding project's
+ * universe is preferred over the API key's owner: an experience can only be
+ * relied on to load assets its own creator owns, so in a group's game the
+ * person holding the key is the wrong owner.
+ */
+export async function resolveAssetCreatorAsync(
+  options: ResolveAssetCreatorOptions
+): Promise<ResolvedAssetCreator> {
+  const { userId, groupId, universeId, source } = options;
+
+  if (userId != null && groupId != null) {
+    throw new Error('Pass --user-id or --group-id, not both.');
+  }
+  for (const [flag, id] of [
+    ['--user-id', userId],
+    ['--group-id', groupId],
+  ] as const) {
+    if (id != null && (!Number.isSafeInteger(id) || id < 1)) {
+      throw new Error(`${flag} must be a positive integer.`);
+    }
+  }
+
+  if (userId != null) {
+    return { creator: { userId }, reason: '--user-id' };
+  }
+  if (groupId != null) {
+    return { creator: { groupId }, reason: '--group-id' };
+  }
+
+  if (universeId != null) {
+    try {
+      return {
+        creator: await source.getUniverseOwnerAsync(universeId),
+        reason: `owns universe ${universeId}, from deploy.nevermore.json`,
+      };
+    } catch (err) {
+      options.onFallback?.(
+        `Could not read who owns universe ${universeId} ` +
+          `(${err instanceof Error ? err.message : String(err)}); ` +
+          `uploading as the API key's owner instead.`
+      );
+    }
+  }
+
+  try {
+    return {
+      creator: { userId: await source.getApiKeyUserIdAsync() },
+      reason: 'owns the API key',
+    };
+  } catch (err) {
+    throw new Error(
+      [
+        `Could not work out who should own the new assets: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+        'Check the key with "nevermore login --status", or name the owner:',
+        '  --user-id <id>    the Roblox user who should own them',
+        '  --group-id <id>   the Roblox group who should own them',
+      ].join('\n')
+    );
+  }
+}