@quenty/nevermore-cli 4.42.0 → 4.42.1-canary.783.30683606415.0

package/src/utils/watch/local-watch-loop.ts

@@ -0,0 +1,190 @@
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  type BasePlaceVersionKeyword,
+  type PlaceVersionSource,
+} from '@quenty/nevermore-deploy';
+
+/** How often to ask Open Cloud whether a base place moved. */
+const DEFAULT_POLL_INTERVAL_MS = 15_000;
+
+/** One base place being watched, and what to rebuild when it moves. */
+export interface LocalWatchEntry {
+  /** Human label for output, e.g. `integration.places.hub`. */
+  label: string;
+  universeId: number;
+  placeId: number;
+  versionType: BasePlaceVersionKeyword;
+  /**
+   * Version this entry was last built from. Undefined means "adopt whatever
+   * the first poll sees", which avoids a rebuild on startup for a place that
+   * has never been locked.
+   */
+  baseline?: number;
+}
+
+export interface LocalWatchLoopOptions {
+  entries: LocalWatchEntry[];
+  source: PlaceVersionSource;
+  /** Stop watching after this long. */
+  durationMs: number;
+  pollIntervalMs?: number;
+  /** Rebuild and redeploy. Errors are reported and the loop continues. */
+  redeployAsync: (entry: LocalWatchEntry, version: number) => Promise<void>;
+  /** Lets a caller stop the loop; SIGINT is wired to one by default. */
+  signal?: AbortSignal;
+  /** Injected in tests. */
+  now?: () => number;
+  sleepAsync?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+
+export interface LocalWatchLoopResult {
+  /** Rebuilds that completed. */
+  redeploys: number;
+  /** Rebuilds that were attempted and threw. */
+  failures: number;
+  /** True when the duration ran out rather than the user interrupting. */
+  expired: boolean;
+}
+
+/**
+ * Poll base places and redeploy in-process when one moves.
+ *
+ * This is what `--watch` does outside CI. Registering with the watch service
+ * would be pointless on a laptop: the service's only action is dispatching a
+ * GitHub workflow, which would rebuild on a runner rather than here — so a
+ * local run keeps the loop in the terminal, where the developer can see it.
+ *
+ * Poll failures never end the loop. A watch is meant to be left running for
+ * hours, and a dropped connection is not a reason to stop watching.
+ */
+export async function runLocalWatchLoopAsync(
+  options: LocalWatchLoopOptions
+): Promise<LocalWatchLoopResult> {
+  const {
+    entries,
+    source,
+    durationMs,
+    redeployAsync,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    now = () => Date.now(),
+    sleepAsync = _sleepAsync,
+  } = options;
+
+  const controller = new AbortController();
+  const signal = options.signal ?? controller.signal;
+  const onSigint = () => controller.abort();
+  if (!options.signal) {
+    process.on('SIGINT', onSigint);
+  }
+
+  const seen = new Map<string, number | undefined>(
+    entries.map((e) => [_key(e), e.baseline])
+  );
+  const deadline = now() + durationMs;
+  let redeploys = 0;
+  let failures = 0;
+
+  OutputHelper.info(
+    `Watching ${entries.length} base place${
+      entries.length === 1 ? '' : 's'
+    } locally. Ctrl-C to stop.`
+  );
+  for (const entry of entries) {
+    OutputHelper.info(
+      `  ${entry.label} — base place ${entry.placeId} (${entry.versionType}${
+        entry.baseline == null ? '' : ` v${entry.baseline}`
+      })`
+    );
+  }
+
+  try {
+    while (!signal.aborted && now() < deadline) {
+      for (const entry of entries) {
+        if (signal.aborted) {
+          break;
+        }
+
+        let latest: number;
+        try {
+          latest = await source.resolveLatestPlaceVersionAsync(
+            entry.universeId,
+            entry.placeId,
+            entry.versionType
+          );
+        } catch (err) {
+          OutputHelper.warn(
+            `Could not check ${entry.label}: ` +
+              (err instanceof Error ? err.message : String(err))
+          );
+          continue;
+        }
+
+        const key = _key(entry);
+        const previous = seen.get(key);
+        if (previous === undefined) {
+          // First sighting of a place with no recorded baseline: adopt it
+          // rather than treating "unknown -> something" as a change.
+          seen.set(key, latest);
+          continue;
+        }
+        if (latest === previous) {
+          continue;
+        }
+
+        OutputHelper.info(
+          `${entry.label}: base place moved v${previous} → v${latest}, rebuilding...`
+        );
+        try {
+          await redeployAsync(entry, latest);
+          redeploys++;
+          // Recorded only on success, so a failed rebuild is retried on the
+          // next poll instead of being silently skipped forever.
+          seen.set(key, latest);
+          OutputHelper.info(`${entry.label}: rebuilt from v${latest}.`);
+        } catch (err) {
+          failures++;
+          OutputHelper.error(
+            `${entry.label}: rebuild failed — ` +
+              (err instanceof Error ? err.message : String(err))
+          );
+        }
+      }
+
+      if (signal.aborted || now() >= deadline) {
+        break;
+      }
+      await sleepAsync(pollIntervalMs, signal);
+    }
+  } finally {
+    if (!options.signal) {
+      process.off('SIGINT', onSigint);
+    }
+  }
+
+  const expired = !signal.aborted;
+  OutputHelper.info(
+    expired
+      ? `Watch lease elapsed. ${redeploys} rebuild${
+          redeploys === 1 ? '' : 's'
+        }.`
+      : `Stopped watching. ${redeploys} rebuild${redeploys === 1 ? '' : 's'}.`
+  );
+
+  return { redeploys, failures, expired };
+}
+
+function _key(entry: LocalWatchEntry): string {
+  return `${entry.placeId}:${entry.versionType}`;
+}
+
+function _sleepAsync(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(finish, ms);
+    function finish() {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', finish);
+      resolve();
+    }
+    signal.addEventListener('abort', finish, { once: true });
+  });
+}

package/src/utils/watch/register-notify-watches.test.ts

@@ -0,0 +1,282 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  parseWatchOption,
+  type WatchNotifyAction,
+  type WatchRegistrationRequest,
+  type WatchRegistry,
+} from '@quenty/nevermore-deploy';
+import { type LocalWatchEntry } from './local-watch-loop.js';
+import {
+  describeNotifyWatchFallback,
+  tryRegisterNotifyWatchesAsync,
+} from './register-notify-watches.js';
+
+const REGISTER_BASE = 'https://watch.example.com/v1/register/';
+const watchOption = () => parseWatchOption(`${REGISTER_BASE}30m`);
+
+beforeEach(() => {
+  vi.stubEnv('GITHUB_REPOSITORY', 'Quenty/egg-hunt-2026');
+  vi.stubEnv('GITHUB_REF_NAME', 'release');
+  vi.stubEnv('NEVERMORE_WATCH_TOKEN', 'token-value');
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+function makeEntry(overrides: Partial<LocalWatchEntry> = {}): LocalWatchEntry {
+  return {
+    label: 'integration.places.hub',
+    universeId: 10,
+    placeId: 20,
+    versionType: 'published',
+    ...overrides,
+  };
+}
+
+function makeRecordingRegistry(monitorId?: string) {
+  const requests: WatchRegistrationRequest[] = [];
+  const create = (): WatchRegistry => ({
+    registerAsync: async (request) => {
+      requests.push(request);
+      return { monitorId: monitorId ?? 'mon_1', changed: true };
+    },
+    triggerAsync: async () => ({ results: [] }),
+  });
+  return { requests, create };
+}
+
+function notifyAction(
+  request: WatchRegistrationRequest,
+  index = 0
+): WatchNotifyAction {
+  const action = request.watches[index]!.action;
+  expect(action.type).toBe('notify');
+  return action as WatchNotifyAction;
+}
+
+describe('tryRegisterNotifyWatchesAsync', () => {
+  it('registers notify actions carrying the selector', async () => {
+    const registry = makeRecordingRegistry();
+
+    const result = await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry({ baseline: 158 })],
+      createRegistry: registry.create,
+    });
+
+    expect(result.success).toBe(true);
+    const request = registry.requests[0]!;
+    // No baseline: the service compares its own token (an asset-delivery
+    // content hash) by string equality, so the lock's Open Cloud version number
+    // would read as drift on the first poll. The `ready` reconcile covers it.
+    expect(request.watches[0]!.baselineVersion).toBeUndefined();
+    expect(request.watches[0]!.baselineVersionKind).toBeUndefined();
+    expect(request.watches[0]!.source).toEqual({
+      type: 'roblox-place',
+      universeId: 10,
+      placeId: 20,
+      versionType: 'published',
+    });
+    expect(notifyAction(request).payload).toEqual({
+      target: 'integration.places.hub',
+    });
+  });
+
+  // Re-registering replaces a monitor's whole watch list, so a local watch that
+  // shared CI's monitor name would silently disarm the workflow dispatch.
+  it('registers under a monitor name distinct from the dispatching one', async () => {
+    const registry = makeRecordingRegistry();
+
+    await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry()],
+      createRegistry: registry.create,
+    });
+
+    expect(registry.requests[0]!.monitorName).toBe(
+      'egg-hunt/integration/local'
+    );
+  });
+
+  it('hands back stream entries keyed by the registered watch name', async () => {
+    const registry = makeRecordingRegistry();
+
+    const result = await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry()],
+      createRegistry: registry.create,
+    });
+
+    expect(result.success && result.entries[0]!.watchName).toBe(
+      registry.requests[0]!.watches[0]!.name
+    );
+    expect(result.success && result.monitorId).toBe('mon_1');
+    expect(result.success && result.credential).toBe('token-value');
+  });
+
+  // Places are only optionally named, so a multi-place target with unnamed
+  // places produces the same selector twice. The service resolves a duplicate
+  // name by dropping a watch rather than failing.
+  it('separates watches that would share a name', async () => {
+    const registry = makeRecordingRegistry();
+
+    await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry({ placeId: 20 }), makeEntry({ placeId: 21 })],
+      createRegistry: registry.create,
+    });
+
+    const names = registry.requests[0]!.watches.map((w) => w.name);
+    expect(new Set(names).size).toBe(2);
+    expect(names).toEqual([
+      'integration.places.hub/20',
+      'integration.places.hub/21',
+    ]);
+  });
+
+  it('shares the Open Cloud key only when asked', async () => {
+    const registry = makeRecordingRegistry();
+
+    await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry()],
+      createRegistry: registry.create,
+    });
+    expect(registry.requests[0]!.robloxApiKey).toBeUndefined();
+
+    await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry()],
+      robloxApiKey: 'secret',
+      createRegistry: registry.create,
+    });
+    expect(registry.requests[1]!.robloxApiKey).toBe('secret');
+  });
+});
+
+describe('tryRegisterNotifyWatchesAsync falling back', () => {
+  // Every failure here has a working answer already — poll Open Cloud from this
+  // machine — so none of them may throw.
+  it('watches a "saved" place when a key is shared', async () => {
+    const registry = makeRecordingRegistry();
+
+    const result = await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry({ versionType: 'saved', baseline: 158 })],
+      robloxApiKey: 'secret',
+      createRegistry: registry.create,
+    });
+
+    expect(result.success).toBe(true);
+    const watch = registry.requests[0]!.watches[0]!;
+    expect(watch.source.versionType).toBe('saved');
+    // Same vocabulary once a key is in play, so the lock value is sendable.
+    expect(watch.baselineVersion).toBe('158');
+    expect(watch.baselineVersionKind).toBe('roblox-place-version');
+  });
+
+  it('declines a "saved" base place the service cannot poll', async () => {
+    const registry = makeRecordingRegistry();
+
+    const result = await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry({ versionType: 'saved' })],
+      createRegistry: registry.create,
+    });
+
+    expect(result).toMatchObject({
+      success: false,
+      reason: 'unwatchable_version_type',
+    });
+    expect(registry.requests).toEqual([]);
+  });
+
+  // Splitting the run — streaming the published places and polling the saved
+  // one — would leave two watch loops disagreeing about what is current.
+  it('declines the whole run when only some places are unwatchable', async () => {
+    const result = await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [
+        makeEntry({ label: 'integration.places.hub' }),
+        makeEntry({ label: 'integration.places.lobby', versionType: 'saved' }),
+      ],
+      createRegistry: makeRecordingRegistry().create,
+    });
+
+    expect(result).toMatchObject({ success: false });
+    expect(
+      result.success === false && describeNotifyWatchFallback(result)
+    ).toMatch(/integration\.places\.lobby/);
+  });
+
+  it('declines without a token, since registration has no identity', async () => {
+    vi.stubEnv('NEVERMORE_WATCH_TOKEN', '');
+    vi.stubEnv('GITHUB_TOKEN', '');
+
+    const result = await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry()],
+      createRegistry: makeRecordingRegistry().create,
+    });
+
+    expect(result).toMatchObject({ success: false, reason: 'no_token' });
+  });
+
+  it('declines when the service refuses the registration', async () => {
+    const result = await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry()],
+      createRegistry: () => ({
+        registerAsync: async () => {
+          throw new Error('503 Service Unavailable');
+        },
+        triggerAsync: async () => ({ results: [] }),
+      }),
+    });
+
+    expect(result).toMatchObject({
+      success: false,
+      reason: 'register_failed',
+    });
+    expect(
+      result.success === false && describeNotifyWatchFallback(result)
+    ).toMatch(/503 Service Unavailable/);
+  });
+
+  it('declines when the service returns no monitor to stream', async () => {
+    const result = await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [makeEntry()],
+      createRegistry: () => ({
+        registerAsync: async () => ({ changed: true }),
+        triggerAsync: async () => ({ results: [] }),
+      }),
+    });
+
+    expect(result).toMatchObject({ success: false, reason: 'no_monitor_id' });
+  });
+
+  it('declines when there is nothing to watch', async () => {
+    const result = await tryRegisterNotifyWatchesAsync({
+      option: watchOption(),
+      monitorName: 'egg-hunt/integration',
+      entries: [],
+      createRegistry: makeRecordingRegistry().create,
+    });
+
+    expect(result).toMatchObject({ success: false, reason: 'no_entries' });
+  });
+});

package/src/utils/watch/register-notify-watches.ts

@@ -0,0 +1,226 @@
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  WATCH_BASELINE_KIND,
+  WATCH_INPUT_NAME,
+  sanitizeWatchName,
+  type WatchEntry,
+  type WatchOption,
+  type WatchRegistry,
+} from '@quenty/nevermore-deploy';
+import { HttpWatchRegistry } from './http-watch-registry.js';
+import { tryResolveGithubDispatchContext } from './github-context.js';
+import { type LocalWatchEntry } from './local-watch-loop.js';
+import { type StreamWatchEntry } from './stream-watch-loop.js';
+
+export interface RegisterNotifyWatchesOptions {
+  option: WatchOption;
+  /** Lease key within the repository, as for a dispatching monitor. */
+  monitorName: string;
+  entries: LocalWatchEntry[];
+  /** Open Cloud key to share, so the service can poll a private base place. */
+  robloxApiKey?: string;
+  /** Let the GitHub CLI supply the token when no env var does. */
+  useGhAuth?: boolean;
+  /** Injected in tests; defaults to the HTTP registry. */
+  createRegistry?: (registerUrl: string) => WatchRegistry;
+}
+
+export type RegisterNotifyWatchesResult =
+  | {
+      success: true;
+      monitorId: string;
+      /** Bearer token for the stream; the same one registration used. */
+      credential: string;
+      entries: StreamWatchEntry[];
+    }
+  | {
+      success: false;
+      reason:
+        | 'no_github_context'
+        | 'no_token'
+        | 'unwatchable_version_type'
+        | 'no_entries'
+        | 'register_failed'
+        | 'no_monitor_id';
+      detail?: string;
+    };
+
+/**
+ * Register a monitor that notifies this process instead of dispatching CI.
+ *
+ * Best-effort on purpose. Every way this can fail — no GitHub identity to
+ * register under, no token, a `"saved"` base place the service cannot poll, a
+ * service that is unreachable — has a working answer already: poll Open Cloud
+ * from here. So a failure downgrades the watch rather than the run, and the
+ * caller falls back.
+ */
+export async function tryRegisterNotifyWatchesAsync(
+  options: RegisterNotifyWatchesOptions
+): Promise<RegisterNotifyWatchesResult> {
+  const { option, entries } = options;
+
+  if (entries.length === 0) {
+    return { success: false, reason: 'no_entries' };
+  }
+
+  // Without a shared key the service reads asset delivery, which reports
+  // published content only — it refuses `"saved"` at registration, and one
+  // refusal fails the whole request. Rather than watch some places one way and
+  // some the other, the whole run falls back to polling, which handles every
+  // version type this machine has credentials for.
+  const credentialed = options.robloxApiKey != null;
+  const unwatchable = credentialed
+    ? []
+    : entries.filter((e) => e.versionType !== 'published');
+  if (unwatchable.length > 0) {
+    return {
+      success: false,
+      reason: 'unwatchable_version_type',
+      detail: unwatchable.map((e) => e.label).join(', '),
+    };
+  }
+
+  const contextResult = tryResolveGithubDispatchContext({
+    useGhAuth: options.useGhAuth,
+  });
+  if (!contextResult.success) {
+    return { success: false, reason: 'no_github_context' };
+  }
+  const context = contextResult.context;
+  // Registration needs a write-scoped PAT even though a notify never spends it:
+  // the repository is the only identity this service has, and it is what a
+  // monitor's leases and caps are counted against.
+  if (!context.token) {
+    return { success: false, reason: 'no_token' };
+  }
+
+  const streamEntries: StreamWatchEntry[] = entries.map((entry) => ({
+    ...entry,
+    watchName: sanitizeWatchName(entry.label),
+  }));
+  _disambiguateWatchNames(streamEntries);
+
+  const watches: WatchEntry[] = streamEntries.map((entry) => ({
+    name: entry.watchName,
+    source: {
+      type: 'roblox-place',
+      universeId: entry.universeId,
+      placeId: entry.placeId,
+      versionType: entry.versionType,
+    },
+    // Only when a key is shared do the two sides speak the same language; the
+    // `ready` reconcile covers this either way, by re-checking every watch
+    // against Open Cloud on connect.
+    ...(credentialed && entry.baseline != null
+      ? {
+          baselineVersion: String(entry.baseline),
+          baselineVersionKind: WATCH_BASELINE_KIND,
+        }
+      : {}),
+    action: {
+      type: 'notify',
+      // Same key a dispatching watch puts the selector under, so the two modes
+      // describe a change the same way even though only one crosses into CI.
+      payload: { [WATCH_INPUT_NAME]: entry.label },
+    },
+  }));
+
+  const registry = (options.createRegistry ?? _defaultRegistry)(
+    option.registerUrl
+  );
+
+  let result;
+  try {
+    result = await registry.registerAsync({
+      // Distinct from the dispatching monitor's name. They hold different
+      // actions, and re-registering replaces a monitor's whole watch list — so
+      // sharing a name would mean a local watch silently disarming CI's.
+      monitorName: sanitizeWatchName(`${options.monitorName}/local`),
+      repository: context.repository,
+      githubToken: context.token,
+      robloxApiKey: options.robloxApiKey,
+      watches,
+    });
+  } catch (err) {
+    return {
+      success: false,
+      reason: 'register_failed',
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  if (!result.monitorId) {
+    return { success: false, reason: 'no_monitor_id' };
+  }
+
+  OutputHelper.verbose(
+    `Registered a notify monitor (${result.monitorId}), lease ${option.lease}.`
+  );
+
+  return {
+    success: true,
+    monitorId: result.monitorId,
+    credential: context.token,
+    entries: streamEntries,
+  };
+}
+
+/** Why the run is polling instead, in words a user can act on. */
+export function describeNotifyWatchFallback(
+  result: RegisterNotifyWatchesResult & { success: false }
+): string {
+  switch (result.reason) {
+    case 'no_entries':
+      return 'nothing to watch';
+    case 'unwatchable_version_type':
+      return (
+        `${result.detail} tracks "saved", which the service can only see ` +
+        'with a shared Open Cloud key (--watch-share-api-key)'
+      );
+    case 'no_github_context':
+      return 'this checkout has no GitHub repository to register under';
+    case 'no_token':
+      return (
+        'no GitHub token — set NEVERMORE_WATCH_TOKEN, or pass ' +
+        '--watch-use-gh-auth to use the one `gh` already holds'
+      );
+    case 'no_monitor_id':
+      return 'the service registered the monitor but returned no id';
+    case 'register_failed':
+      return `the watch service refused the registration — ${result.detail}`;
+  }
+}
+
+function _defaultRegistry(registerUrl: string): WatchRegistry {
+  return new HttpWatchRegistry({ registerUrl });
+}
+
+/**
+ * Make every watch name unique within the monitor.
+ *
+ * Names come from selectors, which are unique per target — except that an
+ * unnamed place in a multi-place target has no name to contribute, so two of
+ * them produce the same selector. Appending the place id separates them without
+ * failing a deploy that already shipped.
+ */
+function _disambiguateWatchNames(entries: StreamWatchEntry[]): void {
+  const byName = new Map<string, StreamWatchEntry[]>();
+  for (const entry of entries) {
+    const group = byName.get(entry.watchName);
+    if (group) {
+      group.push(entry);
+    } else {
+      byName.set(entry.watchName, [entry]);
+    }
+  }
+  for (const group of byName.values()) {
+    if (group.length === 1) {
+      continue;
+    }
+    for (const entry of group) {
+      entry.watchName = sanitizeWatchName(
+        `${entry.watchName}/${entry.placeId}`
+      );
+    }
+  }
+}