@quenty/nevermore-cli 4.43.0-canary.783.30683872723.0 → 4.43.0

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

@@ -43,8 +43,16 @@ import {
   readPackageVersionAsync,
 } from '../../utils/nevermore-cli-utils.js';
 import { parseTestLogs } from '../../utils/testing/test-log-parser.js';
-import { parseWatchOption } from '@quenty/nevermore-deploy';
-import { registerWatchesAsync } from '../../utils/watch/register-watches.js';
+import {
+  buildWatchMonitorName,
+  parseWatchOption,
+  type BasePlaceResolver,
+  type WatchOption,
+} from '@quenty/nevermore-deploy';
+import {
+  registerWatchesAsync,
+  type WatchCandidate,
+} from '../../utils/watch/register-watches.js';
 
 const SMOKE_TEST_SCRIPT_PATH = resolvePackagePath(
   import.meta.url,
@@ -185,6 +193,27 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
           'Use --all to deploy every package with this target, or --base <ref> to change the comparison ref.'
       );
     }
+    // Renew anyway. Registration derives from committed config plus the lock,
+    // so it does not need this run to have deployed anything — and the lease is
+    // the only thing keeping the watch alive. Returning here instead is how a
+    // repo whose scheduled builds all diff clean quietly stops being watched,
+    // with no failure anywhere to notice.
+    if (watchOption) {
+      OutputHelper.info(
+        'Renewing watches anyway, so the lease does not lapse.'
+      );
+      await _registerWatchesAsync({
+        targetName,
+        option: watchOption,
+        // Nothing deployed, so the lock is the whole truth about what each
+        // place was built from.
+        resolver: createLockOnlyBasePlaceResolver(),
+        useGhAuth: args.watchUseGhAuth,
+        shareApiKey: args.watchShareApiKey,
+        resolveApiKeyAsync: () => getApiKeyAsync(args),
+        dryrun: args.dryrun,
+      });
+    }
     return;
   }
 
@@ -197,20 +226,7 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
     // lock file, so it runs for real even on a dryrun — that is what makes the
     // watch path testable without shipping a build.
     if (watchOption) {
-      OutputHelper.info(
-        '[DRYRUN] Registering separate dryrun watches and firing them, to ' +
-          'prove routing works. This does not build or upload here — but ' +
-          'firing really does dispatch the workflow once per package, and ' +
-          'each of those runs a real deploy on the runner.'
-      );
-      if (args.watchShareApiKey) {
-        OutputHelper.warn(
-          '[DRYRUN] Registering without the Open Cloud key, so a "saved" base ' +
-            'place is skipped here even though a real run would watch it.'
-        );
-      }
-      const allPackages = await discoverAllTargetPackagesAsync(targetName);
-      // Under its own monitor name, never the one a real run owns.
+      // Under its own monitor names, never the ones a real run owns.
       //
       // Re-registering replaces a monitor's entire watch list, and a dryrun
       // cannot reproduce a real registration: the Open Cloud key is resolved
@@ -219,18 +235,13 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
       // driver and its content-hash vocabulary, dropping the baselines, and
       // deleting any "saved" watch outright, because an anonymous
       // registration skips those.
-      await registerWatchesAsync({
+      await _registerWatchesAsync({
+        targetName,
         option: watchOption,
-        monitorName: `${targetName}/dryrun`,
         resolver: createLockOnlyBasePlaceResolver(),
         useGhAuth: args.watchUseGhAuth,
-        triggerAfterRegister: true,
-        candidates: flattenToBatchTargets(allPackages).map((buildTarget) => ({
-          targetName,
-          packageName: buildTarget.packageName,
-          packagePath: buildTarget.path,
-          place: buildTarget.target,
-        })),
+        shareApiKey: args.watchShareApiKey,
+        dryrun: true,
       });
     }
     return;
@@ -394,25 +405,13 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
     // re-registers the same wrong baseline. The failure becomes permanent and
     // invisible.
     if (watchOption && results.summary.failed === 0) {
-      // Deliberately every package with this target, not just the ones that
-      // deployed. One monitor holds the repo's watches for a target and a
-      // re-apply replaces its whole list, so registering only what changed
-      // would delete the watches of every package that happened not to change
-      // this run. Packages that did not deploy still have a lock entry, which
-      // is the correct baseline for them.
-      const allPackages = await discoverAllTargetPackagesAsync(targetName);
-      await registerWatchesAsync({
+      await _registerWatchesAsync({
+        targetName,
         option: watchOption,
-        monitorName: targetName,
         resolver: basePlaceResolver,
         useGhAuth: args.watchUseGhAuth,
-        robloxApiKey: args.watchShareApiKey ? apiKey : undefined,
-        candidates: flattenToBatchTargets(allPackages).map((buildTarget) => ({
-          targetName,
-          packageName: buildTarget.packageName,
-          packagePath: buildTarget.path,
-          place: buildTarget.target,
-        })),
+        shareApiKey: args.watchShareApiKey,
+        resolveApiKeyAsync: async () => apiKey,
       });
     }
   } catch (err) {
@@ -426,6 +425,101 @@ async function _runAsync(args: BatchDeployArgs): Promise<void> {
   process.exit(exitCode);
 }
 
+/**
+ * Register one monitor per package, covering every package with this target.
+ *
+ * Per package rather than one for the batch, because `deploy run --watch`
+ * registers a package's places too. Two names for one package's watches means
+ * two monitors on the same base place, so one artist publish dispatches twice
+ * and each rebuild races the other's lock write. Both paths take the name from
+ * `buildWatchMonitorName`, so registering from either replaces the same list.
+ *
+ * Every package with the target, never just the ones that deployed: a re-apply
+ * replaces a monitor's whole list, and a package that didn't change still has a
+ * lock entry, which is exactly the right baseline for it.
+ */
+async function _registerWatchesAsync(options: {
+  targetName: string;
+  option: WatchOption;
+  resolver: BasePlaceResolver;
+  useGhAuth?: boolean;
+  /** Whether `--watch-share-api-key` was passed. A dryrun never shares one. */
+  shareApiKey?: boolean;
+  /** Called only if a key is actually going to be sent. */
+  resolveApiKeyAsync?: () => Promise<string>;
+  dryrun?: boolean;
+}): Promise<void> {
+  const { targetName } = options;
+
+  if (options.dryrun) {
+    OutputHelper.info(
+      '[DRYRUN] Registering separate dryrun watches and firing them, to ' +
+        'prove routing works. This does not build or upload here — but ' +
+        'firing really does dispatch the workflow once per package, and ' +
+        'each of those runs a real deploy on the runner.'
+    );
+    if (options.shareApiKey) {
+      OutputHelper.warn(
+        '[DRYRUN] Registering without the Open Cloud key, so a "saved" base ' +
+          'place is skipped here even though a real run would watch it.'
+      );
+    }
+  }
+
+  const robloxApiKey =
+    options.shareApiKey && !options.dryrun
+      ? await options.resolveApiKeyAsync?.()
+      : undefined;
+
+  const allPackages = await discoverAllTargetPackagesAsync(targetName);
+
+  // Places that never asked to be watched are dropped here rather than passed
+  // in to be reported as skips. Most places in a batch are in that state, and
+  // per-package registration would otherwise warn about each package that has
+  // no watch at all. A place that asked and can't be watched still goes
+  // through, because that is the case worth saying out loud.
+  const byPackage = new Map<string, WatchCandidate[]>();
+  for (const buildTarget of flattenToBatchTargets(allPackages)) {
+    if (buildTarget.target.watch == null) {
+      continue;
+    }
+    const candidates = byPackage.get(buildTarget.packageName) ?? [];
+    candidates.push({
+      targetName,
+      packageName: buildTarget.packageName,
+      packagePath: buildTarget.path,
+      place: buildTarget.target,
+    });
+    byPackage.set(buildTarget.packageName, candidates);
+  }
+
+  if (byPackage.size === 0) {
+    OutputHelper.warn(
+      `--watch was requested, but no place in a "${targetName}" target has a ` +
+        '"watch" field. Add one naming the workflow that rebuilds it.'
+    );
+    return;
+  }
+
+  for (const [packageName, candidates] of byPackage) {
+    await registerWatchesAsync({
+      option: options.option,
+      monitorName: buildWatchMonitorName({
+        packageName,
+        targetName,
+        dryrun: options.dryrun,
+      }),
+      resolver: options.resolver,
+      useGhAuth: options.useGhAuth,
+      robloxApiKey,
+      // Firing proves the workflow really receives the selector, which is the
+      // half that historically breaks. Only a dryrun asks for it.
+      triggerAfterRegister: options.dryrun,
+      candidates,
+    });
+  }
+}
+
 function _annotateSmokeTestFailure(logs: string): string {
   const header =
     'Post-deploy smoke test failed. The deploy itself succeeded, but a server ' +

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

@@ -39,16 +39,20 @@ import {
   readPackageVersionAsync,
 } from '../../utils/nevermore-cli-utils.js';
 import {
+  WATCH_MODES,
+  buildWatchMonitorName,
+  checkBasePlaceWatchable,
   formatTargetSelector,
-  isBasePlaceVersionKeyword,
   loadDeployConfigAsync,
   parseTargetSelector,
   parseWatchOption,
   resolveDeployConfigPath,
   resolveDeployTargetPlaces,
+  resolveWatchDelivery,
   toManifestPlaceInfo,
   type BasePlaceResolver,
   type DeployConfig,
+  type WatchMode,
 } from '@quenty/nevermore-deploy';
 import {
   registerWatchesAsync,
@@ -77,14 +81,10 @@ const MULTI_PLACE_CONCURRENCY = 10;
 /**
  * Which base places a local watch polls.
  *
- * Deliberately looser than the cloud plan. `watch` is a GitHub workflow path —
- * a dispatch address — and nothing is dispatched locally, so requiring it would
- * only stop a developer hot-reloading a place that never intends to use CI.
- * `"saved"` is fair game too: the service cannot poll it yet, but this machine
- * has Open Cloud credentials and can.
- *
- * An exact version pin is still excluded, for the same reason as always: it
- * means "hold this still", so there is nothing to follow.
+ * Deliberately looser than the cloud plan, in exactly one way: `watch` is a
+ * dispatch address, nothing is dispatched locally, so requiring it would only
+ * stop a developer hot-reloading a place that never intends to use CI.
+ * Everything about the base place itself is the shared rule.
  */
 async function _buildLocalWatchEntriesAsync(
   config: DeployConfig,
@@ -95,21 +95,19 @@ async function _buildLocalWatchEntriesAsync(
   const entries: LocalWatchEntry[] = [];
   for (const place of resolveDeployTargetPlaces(config, targetName)) {
     const basePlace = place.basePlace;
-    if (basePlace == null) {
-      continue;
-    }
-    if (
-      basePlace.version != null &&
-      !isBasePlaceVersionKeyword(basePlace.version)
-    ) {
+    // The same rule a registration uses, asked with `credentialed: true`: this
+    // machine holds the Open Cloud key, so "saved" is readable here even when
+    // the service could not see it. Only the workflow half differs, and a local
+    // watch has nothing to dispatch.
+    const check = checkBasePlaceWatchable(basePlace, { credentialed: true });
+    if (basePlace == null || !check.watchable) {
       continue;
     }
-    const versionType = basePlace.version ?? 'published';
     entries.push({
       label: formatTargetSelector({ targetName, placeName: place.name }),
       universeId: basePlace.universeId,
       placeId: basePlace.placeId,
-      versionType,
+      versionType: check.versionType,
       baseline: await resolver.peekAsync(packagePath, basePlace),
     });
   }
@@ -130,6 +128,7 @@ export interface DeployArgs extends NevermoreGlobalArgs {
   output?: string;
   logs?: boolean;
   watch?: string;
+  watchMode?: WatchMode;
   watchShareApiKey?: boolean;
   watchUseGhAuth?: boolean;
 }
@@ -303,6 +302,16 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
               'Takes the register endpoint URL, ending in the lease: https://<watch-service>/v1/register/7d',
             type: 'string',
           })
+          .option('watch-mode', {
+            describe:
+              'How the watch reaches whoever rebuilds: "dispatch" fires the workflow, ' +
+              '"notify" holds a stream here and rebuilds in this terminal. ' +
+              'Defaults to "auto", which dispatches on GitHub Actions and notifies elsewhere — ' +
+              'set it explicitly in any other automated context, where notifying would hang the run.',
+            type: 'string',
+            choices: WATCH_MODES,
+            default: 'auto',
+          })
           .option('watch-use-gh-auth', {
             describe:
               'Let the GitHub CLI supply the watch token when no environment variable does. ' +
@@ -420,7 +429,11 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
         // registration skips those.
         await registerWatchesAsync({
           option: watchOption,
-          monitorName: `${packageName}/${watchedTarget}/dryrun`,
+          monitorName: buildWatchMonitorName({
+            packageName,
+            targetName: watchedTarget,
+            dryrun: true,
+          }),
           resolver: createLockOnlyBasePlaceResolver(),
           useGhAuth: args.watchUseGhAuth,
           triggerAfterRegister: true,
@@ -636,7 +649,7 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
       // Only after a clean deploy: what happens next records the base place
       // version that just shipped, which is not a fact yet if the deploy failed.
       if (watchOption && first.failed === 0) {
-        if (isCI()) {
+        if (resolveWatchDelivery(args.watchMode, isCI()) === 'dispatch') {
           // The monitor is named for the whole target, so it has to carry every
           // place in that target — not just the ones this invocation deployed.
           // Re-registering replaces its watch list, so a narrowed selector
@@ -644,9 +657,10 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
           // places' watches. Places that did not deploy keep their lock baseline.
           watchResult = await registerWatchesAsync({
             option: watchOption,
-            // Scoped to this package and target, so deploying one package can
-            // never replace the watch list another package registered.
-            monitorName: `${packageName}/${watchedTarget}`,
+            monitorName: buildWatchMonitorName({
+              packageName,
+              targetName: watchedTarget,
+            }),
             resolver: first.resolver,
             useGhAuth: args.watchUseGhAuth,
             robloxApiKey: args.watchShareApiKey ? apiKey : undefined,
@@ -680,7 +694,10 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
 
           const notify = await tryRegisterNotifyWatchesAsync({
             option: watchOption,
-            monitorName: `${packageName}/${watchedTarget}`,
+            monitorName: buildWatchMonitorName({
+              packageName,
+              targetName: watchedTarget,
+            }),
             entries: localEntries,
             useGhAuth: args.watchUseGhAuth,
             robloxApiKey: args.watchShareApiKey ? apiKey : undefined,

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

@@ -150,8 +150,7 @@ export abstract class BaseJobContext implements JobContext {
       // Waiter: the in-flight build was started under a different
       // packageName, so emit our own 'building' phase change for the reporter.
       const resolvedName =
-        options.packageName ??
-        path.basename(options.packagePath);
+        options.packageName ?? path.basename(options.packagePath);
       this._reporter.onPackagePhaseChange(resolvedName, 'building');
       return existing.promise;
     }

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

@@ -502,10 +502,14 @@ export class OpenCloudClient {
 
   /**
    * Resolve the newest saved or published version number of a place, via the
-   * Open Cloud Assets API (`asset:read` scope; `legacy-asset:manage` also
-   * grants it). The returned number is the same value the Asset Delivery API's
-   * `/version/{n}` route expects, so it can be written straight into a
-   * `basePlace.version` pin.
+   * Open Cloud Assets API (`asset:read` scope). The returned number is the same
+   * value the Asset Delivery API's `/version/{n}` route expects, so it can be
+   * written straight into a `basePlace.version` pin.
+   *
+   * This used to add that `legacy-asset:manage` grants `asset:read` too. They
+   * are separate boxes on the credentials page and nothing here ever verified
+   * the implication, so the claim is gone rather than restated — it had already
+   * been copied into the `nevermore login` instructions as fact once.
    *
    * `saved` is the newest version of any kind — Studio saves and publishes
    * share one increasing version sequence. `published` is the newest version

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

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, afterEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
   describeMissingWatchToken,
   parseGithubRepository,
@@ -35,6 +35,15 @@ describe('tryResolveGithubDispatchContext token', () => {
     'git rev-parse': 'main',
   };
 
+  // Cleared so these exercise the git fallback rather than whatever the host
+  // happens to export. Actions sets both, and on a pull request GITHUB_REF_NAME
+  // is a merge ref — which resolution rightly refuses, so without this the
+  // whole describe passes locally and fails only in CI.
+  beforeEach(() => {
+    vi.stubEnv('GITHUB_REPOSITORY', '');
+    vi.stubEnv('GITHUB_REF_NAME', '');
+  });
+
   // Registering ships the token to the watch service, so it has to be one the
   // user handed over. Nearly every dev machine has a logged-in `gh`, so reading
   // it by default would turn a local watch into a silent credential send.

package/src/utils/watch/http-watch-registry.ts

@@ -239,9 +239,11 @@ function _describeFailure(
     case 422: {
       // 422 is the service's "your config cannot work" answer, and it covers
       // several unrelated causes now — a missing workflow, an Open Cloud key
-      // without universe.place:read, a "saved" watch with no key, a baseline in
-      // the wrong vocabulary. Its own message names which, so the only thing
-      // worth adding is a remedy that could not already be in it.
+      // that cannot read a base place, a "saved" watch with no key, a baseline
+      // in the wrong vocabulary. Its own message names which, so the only thing
+      // worth adding is a remedy that could not already be in it. The scope
+      // itself is deliberately not named here: this file would then be a second
+      // place to correct when it is wrong, and it already has been once.
       const workflows = [
         ...new Set(
           request.watches.flatMap((w) =>