@quenty/nevermore-cli 4.41.1 → 4.42.1-canary.783.30683193716.0

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

@@ -0,0 +1,330 @@
+import { describe, it, expect } from 'vitest';
+import { type WatchRegistrationRequest } from '@quenty/nevermore-deploy';
+import { HttpWatchRegistry } from './http-watch-registry.js';
+
+const REGISTER_URL = 'https://watch.example.com/v1/register/7d/';
+
+function makeRequest(
+  overrides: Partial<WatchRegistrationRequest> = {}
+): WatchRegistrationRequest {
+  return {
+    monitorName: 'integration',
+    repository: 'Quenty/egg-hunt-2026',
+    githubToken: 'token-value',
+    watches: [
+      {
+        name: 'quenty/hub/hub',
+        source: {
+          type: 'roblox-place',
+          universeId: 10,
+          placeId: 20,
+          versionType: 'published',
+        },
+        baselineVersion: '158',
+        baselineVersionKind: 'roblox-place-version',
+        action: {
+          type: 'github-workflow-dispatch',
+          workflow: '.github/workflows/build.yml',
+          ref: 'main',
+          inputs: { target: 'integration.places.hub' },
+        },
+      },
+    ],
+    ...overrides,
+  };
+}
+
+function makeResponse(
+  body: string,
+  init: { status?: number; statusText?: string } = {}
+): Response {
+  return {
+    ok: (init.status ?? 200) < 400,
+    status: init.status ?? 200,
+    statusText: init.statusText ?? 'OK',
+    text: async () => body,
+  } as Response;
+}
+
+function registryReturning(
+  response: Response,
+  calls?: Array<{ url: string; init: RequestInit }>
+): HttpWatchRegistry {
+  return new HttpWatchRegistry({
+    registerUrl: REGISTER_URL,
+    fetchImpl: (async (url: string, init: RequestInit) => {
+      calls?.push({ url, init });
+      return response;
+    }) as unknown as typeof fetch,
+  });
+}
+
+describe('HttpWatchRegistry', () => {
+  it('posts a MonitorRequest to the register URL', async () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    await registryReturning(makeResponse('{}'), calls).registerAsync(
+      makeRequest()
+    );
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.url).toBe(REGISTER_URL);
+    expect(calls[0]!.init.method).toBe('POST');
+
+    expect(JSON.parse(calls[0]!.init.body as string)).toEqual({
+      name: 'integration',
+      auth: {
+        github: {
+          token: 'token-value',
+          repository: 'Quenty/egg-hunt-2026',
+        },
+      },
+      watches: [
+        {
+          name: 'quenty/hub/hub',
+          source: {
+            type: 'roblox-place',
+            universeId: 10,
+            placeId: 20,
+            versionType: 'published',
+          },
+          baselineVersion: '158',
+          baselineVersionKind: 'roblox-place-version',
+          action: {
+            type: 'github-workflow-dispatch',
+            workflow: '.github/workflows/build.yml',
+            ref: 'main',
+            inputs: { target: 'integration.places.hub' },
+          },
+        },
+      ],
+    });
+  });
+
+  it('sends every watch in one request', async () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const base = makeRequest();
+    await registryReturning(makeResponse('{}'), calls).registerAsync({
+      ...base,
+      watches: [base.watches[0]!, { ...base.watches[0]!, name: 'pkg/lobby' }],
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(JSON.parse(calls[0]!.init.body as string).watches).toHaveLength(2);
+  });
+
+  it('omits the Open Cloud key unless one was shared', async () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    await registryReturning(makeResponse('{}'), calls).registerAsync(
+      makeRequest()
+    );
+
+    expect(JSON.parse(calls[0]!.init.body as string).auth).not.toHaveProperty(
+      'robloxOpenCloud'
+    );
+  });
+
+  it('includes the Open Cloud key when shared', async () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    await registryReturning(makeResponse('{}'), calls).registerAsync(
+      makeRequest({ robloxApiKey: 'oc-key' })
+    );
+
+    expect(
+      JSON.parse(calls[0]!.init.body as string).auth.robloxOpenCloud
+    ).toEqual({ apiKey: 'oc-key' });
+  });
+
+  // The kind describes the value, so sending it alone would declare the
+  // vocabulary of a baseline that is not there.
+  it('omits the declared kind along with the baseline', async () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const base = makeRequest();
+    await registryReturning(makeResponse('{}'), calls).registerAsync({
+      ...base,
+      watches: [{ ...base.watches[0]!, baselineVersion: undefined }],
+    });
+
+    expect(
+      JSON.parse(calls[0]!.init.body as string).watches[0]
+    ).not.toHaveProperty('baselineVersionKind');
+  });
+
+  it('omits baselineVersion when there is no baseline', async () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const base = makeRequest();
+    await registryReturning(makeResponse('{}'), calls).registerAsync({
+      ...base,
+      watches: [{ ...base.watches[0]!, baselineVersion: undefined }],
+    });
+
+    expect(
+      JSON.parse(calls[0]!.init.body as string).watches[0]
+    ).not.toHaveProperty('baselineVersion');
+  });
+
+  it('reads back the monitor the service reports', async () => {
+    const result = await registryReturning(
+      makeResponse(
+        JSON.stringify({
+          monitorId: 'mon_9f2a',
+          revision: 'abc123',
+          leaseExpiresAt: '2026-08-06T00:00:00Z',
+          changed: true,
+          watches: [{ name: 'a' }, { name: 'b' }],
+          unexpected: 'ignored',
+        })
+      )
+    ).registerAsync(makeRequest());
+
+    expect(result).toEqual({
+      monitorId: 'mon_9f2a',
+      revision: 'abc123',
+      leaseExpiresAt: '2026-08-06T00:00:00Z',
+      changed: true,
+      watchCount: 2,
+    });
+  });
+
+  it('reports an unchanged re-apply', async () => {
+    const result = await registryReturning(
+      makeResponse(JSON.stringify({ monitorId: 'mon_1', changed: false }))
+    ).registerAsync(makeRequest());
+
+    expect(result.changed).toBe(false);
+  });
+
+  it('treats a 2xx with an unusable body as registered without details', async () => {
+    expect(
+      await registryReturning(makeResponse('not json')).registerAsync(
+        makeRequest()
+      )
+    ).toEqual({});
+  });
+
+  describe('failure messages', () => {
+    it('leads with the service message and adds our remedy on 401', async () => {
+      await expect(
+        registryReturning(
+          makeResponse(JSON.stringify({ error: 'bad credentials' }), {
+            status: 401,
+            statusText: 'Unauthorized',
+          })
+        ).registerAsync(makeRequest())
+      ).rejects.toThrowError(/^bad credentials\nSet NEVERMORE_WATCH_TOKEN/);
+    });
+
+    it('falls back to our own wording when the service says nothing', async () => {
+      await expect(
+        registryReturning(
+          makeResponse('', { status: 401, statusText: 'Unauthorized' })
+        ).registerAsync(makeRequest())
+      ).rejects.toThrowError(/^GitHub rejected the dispatch token\./);
+    });
+
+    it('names the repository and required scope on 403', async () => {
+      await expect(
+        registryReturning(
+          makeResponse('', { status: 403, statusText: 'Forbidden' })
+        ).registerAsync(makeRequest())
+      ).rejects.toThrowError(
+        /cannot write to Quenty\/egg-hunt-2026.*actions: write/s
+      );
+    });
+
+    it('explains a quota failure on 409', async () => {
+      await expect(
+        registryReturning(
+          makeResponse('', { status: 409, statusText: 'Conflict' })
+        ).registerAsync(makeRequest())
+      ).rejects.toThrowError(/quota exceeded for Quenty\/egg-hunt-2026/);
+    });
+
+    it('lists the workflows it referenced on 422', async () => {
+      await expect(
+        registryReturning(
+          makeResponse('', { status: 422, statusText: 'Unprocessable Entity' })
+        ).registerAsync(makeRequest())
+      ).rejects.toThrowError(
+        /workflow does not exist.*\.github\/workflows\/build\.yml/s
+      );
+    });
+
+    // Observed against prod: a notify-only monitor was refused 422 because the
+    // Open Cloud key lacked a scope, and the reply appended "Referenced: ." plus
+    // advice about a workflow path — under a message that had nothing to do with
+    // workflows. 422 now covers several causes and the service names which.
+    it('adds no workflow advice when the monitor dispatches none', async () => {
+      const request = makeRequest();
+      request.watches = request.watches.map((watch) => ({
+        ...watch,
+        action: { type: 'notify' as const, payload: { target: 'x' } },
+      }));
+
+      await expect(
+        registryReturning(
+          makeResponse(
+            JSON.stringify({
+              error: 'The Open Cloud key is not allowed to read place 1 (403).',
+            }),
+            { status: 422, statusText: 'Unprocessable Entity' }
+          )
+        ).registerAsync(request)
+      ).rejects.toThrowError(/not allowed to read place 1/);
+
+      await expect(
+        registryReturning(
+          makeResponse(JSON.stringify({ error: 'nope' }), {
+            status: 422,
+            statusText: 'Unprocessable Entity',
+          })
+        ).registerAsync(request)
+      ).rejects.not.toThrowError(/Referenced|workflow/);
+    });
+
+    it('surfaces the API error body', async () => {
+      await expect(
+        registryReturning(
+          makeResponse(JSON.stringify({ error: 'lease too long' }), {
+            status: 400,
+            statusText: 'Bad Request',
+          })
+        ).registerAsync(makeRequest())
+      ).rejects.toThrowError(/lease too long/);
+    });
+
+    it('includes the API validation detail list', async () => {
+      await expect(
+        registryReturning(
+          makeResponse(
+            JSON.stringify({
+              error: "request/body must have required property 'name'",
+              errors: [{ path: '/body/name', errorCode: 'required' }],
+            }),
+            { status: 400, statusText: 'Bad Request' }
+          )
+        ).registerAsync(makeRequest())
+      ).rejects.toThrowError(/\/body\/name/);
+    });
+
+    it('falls back to status text on an unmapped code', async () => {
+      await expect(
+        registryReturning(
+          makeResponse('', { status: 503, statusText: 'Service Unavailable' })
+        ).registerAsync(makeRequest())
+      ).rejects.toThrowError(/503 Service Unavailable/);
+    });
+
+    it('reports the endpoint when the request cannot be made', async () => {
+      const registry = new HttpWatchRegistry({
+        registerUrl: REGISTER_URL,
+        fetchImpl: (async () => {
+          throw new Error('ENOTFOUND');
+        }) as unknown as typeof fetch,
+      });
+
+      await expect(registry.registerAsync(makeRequest())).rejects.toThrowError(
+        /could not reach https:\/\/watch\.example\.com/
+      );
+    });
+  });
+});

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

@@ -0,0 +1,341 @@
+import {
+  type WatchRegistrationRequest,
+  type WatchRegistrationResult,
+  type WatchRegistry,
+  type WatchTriggerResult,
+} from '@quenty/nevermore-deploy';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export interface HttpWatchRegistryOptions {
+  /** Full register endpoint, ending in the lease — `.../v1/register/7d/`. */
+  registerUrl: string;
+  timeoutMs?: number;
+  /** Injected in tests. Defaults to the global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * `WatchRegistry` over the Roblox Analytics Watch API.
+ *
+ * One `POST /v1/register/{lease}` per invocation. The endpoint is whatever URL
+ * `--watch` resolved to, so nothing here assumes a host, and the lease is
+ * already the last path segment of that URL.
+ *
+ * The endpoint takes no `Authorization` header — the GitHub token travels in
+ * `auth.github.token`, because the service holds it to dispatch with later
+ * rather than using it to authenticate this call.
+ */
+export class HttpWatchRegistry implements WatchRegistry {
+  private _registerUrl: string;
+  private _timeoutMs: number;
+  private _fetch: typeof fetch;
+
+  constructor(options: HttpWatchRegistryOptions) {
+    this._registerUrl = options.registerUrl;
+    this._timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this._fetch = options.fetchImpl ?? fetch;
+  }
+
+  async registerAsync(
+    request: WatchRegistrationRequest
+  ): Promise<WatchRegistrationResult> {
+    const body = {
+      name: request.monitorName,
+      auth: {
+        github: {
+          token: request.githubToken,
+          repository: request.repository,
+        },
+        ...(request.robloxApiKey
+          ? { robloxOpenCloud: { apiKey: request.robloxApiKey } }
+          : {}),
+      },
+      watches: request.watches.map((watch) => ({
+        name: watch.name,
+        source: {
+          type: watch.source.type,
+          universeId: watch.source.universeId,
+          placeId: watch.source.placeId,
+          versionType: watch.source.versionType,
+        },
+        // The kind travels with the value or not at all. Without it the service
+        // ignores a baseline outright on the one transition it matters for —
+        // the first registration that supplies an Open Cloud key — and the 422
+        // that should catch a vocabulary mismatch can never fire.
+        ...(watch.baselineVersion == null
+          ? {}
+          : {
+              baselineVersion: watch.baselineVersion,
+              ...(watch.baselineVersionKind == null
+                ? {}
+                : { baselineVersionKind: watch.baselineVersionKind }),
+            }),
+        action: watch.action,
+      })),
+      ...(request.cooldownSeconds == null
+        ? {}
+        : { cooldownSeconds: request.cooldownSeconds }),
+    };
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this._timeoutMs);
+
+    let response: Response;
+    try {
+      response = await this._fetch(this._registerUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      if (controller.signal.aborted) {
+        throw new Error(
+          `Watch registration timed out after ${this._timeoutMs}ms: ${this._registerUrl}`
+        );
+      }
+      throw new Error(
+        `Watch registration could not reach ${this._registerUrl}: ` +
+          (err instanceof Error ? err.message : String(err))
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    const text = await _readTextAsync(response);
+    if (!response.ok) {
+      throw new Error(_describeFailure(response, text, request));
+    }
+
+    return _parseResult(text);
+  }
+
+  async triggerAsync(
+    monitorId: string,
+    credential: string,
+    options: { watchName?: string } = {}
+  ): Promise<WatchTriggerResult> {
+    const url = `${this._apiBase()}/v1/monitors/${encodeURIComponent(
+      monitorId
+    )}/trigger`;
+
+    const response = await this._fetchWithTimeoutAsync(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        // Unlike register, this endpoint authenticates the caller — the token
+        // is the identity, so it travels as a bearer rather than in the body.
+        Authorization: `Bearer ${credential}`,
+      },
+      body: JSON.stringify(
+        options.watchName == null ? {} : { watchName: options.watchName }
+      ),
+    });
+
+    const text = await _readTextAsync(response);
+    if (!response.ok) {
+      const detail = _extractError(text);
+      throw new Error(
+        `Forcing a dispatch failed (${response.status} ${response.statusText})` +
+          (detail ? `: ${detail}` : '')
+      );
+    }
+
+    try {
+      const parsed = JSON.parse(text) as WatchTriggerResult;
+      return { results: Array.isArray(parsed.results) ? parsed.results : [] };
+    } catch {
+      return { results: [] };
+    }
+  }
+
+  /**
+   * The API root, recovered from the register URL.
+   *
+   * `--watch` names the register endpoint because that is the one a user has to
+   * type; every other call is derived from it. The lease-bearing
+   * `/v1/register/<lease>/` suffix is the documented shape, so trimming it is
+   * how a single flag reaches the rest of the API.
+   */
+  private _apiBase(): string {
+    const marker = '/v1/register/';
+    const index = this._registerUrl.indexOf(marker);
+    if (index === -1) {
+      throw new Error(
+        `Cannot derive the watch API root from "${this._registerUrl}" — ` +
+          `expected it to contain "${marker}".`
+      );
+    }
+    return this._registerUrl.slice(0, index);
+  }
+
+  private async _fetchWithTimeoutAsync(
+    url: string,
+    init: RequestInit
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this._timeoutMs);
+    try {
+      return await this._fetch(url, { ...init, signal: controller.signal });
+    } catch (err) {
+      if (controller.signal.aborted) {
+        throw new Error(
+          `Watch request timed out after ${this._timeoutMs}ms: ${url}`
+        );
+      }
+      throw new Error(
+        `Watch request could not reach ${url}: ` +
+          (err instanceof Error ? err.message : String(err))
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+/**
+ * Turn a status code into something actionable. The API documents exactly what
+ * each failure means, and every one of them has a different fix — a generic
+ * "registration failed (403)" would send someone to the wrong place.
+ *
+ * The service's own message wins when it has one, since it knows specifics we
+ * can only guess at; ours is the fallback for a bare status. Only the remedy is
+ * always ours, and it is what the service never supplies.
+ */
+function _describeFailure(
+  response: Response,
+  text: string,
+  request: WatchRegistrationRequest
+): string {
+  const detail = _extractError(text);
+
+  const compose = (fallback: string, remedy?: string): string => {
+    const head = detail || fallback;
+    return remedy ? `${head}\n${remedy}` : head;
+  };
+
+  switch (response.status) {
+    case 400:
+      return compose(
+        'The watch service rejected the registration as invalid.',
+        'This is a bug in how the CLI built the request — please report it.'
+      );
+    case 401:
+      return compose(
+        'GitHub rejected the dispatch token.',
+        'Set NEVERMORE_WATCH_TOKEN to a valid, unexpired token.'
+      );
+    case 403:
+      return compose(
+        `The dispatch token cannot write to ${request.repository}.`,
+        `The token needs "actions: write" on ${request.repository}.`
+      );
+    case 409:
+      return compose(
+        `Watch quota exceeded for ${request.repository}.`,
+        'Release monitors you no longer need, or let their leases expire.'
+      );
+    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.
+      const workflows = [
+        ...new Set(
+          request.watches.flatMap((w) =>
+            w.action.type === 'github-workflow-dispatch'
+              ? [w.action.workflow]
+              : []
+          )
+        ),
+      ];
+      // Volunteering a workflow remedy for a monitor that dispatches none once
+      // produced "Referenced: ." under a message about an API key scope.
+      if (workflows.length === 0) {
+        return compose('The watch service rejected the configuration.');
+      }
+      return compose(
+        `A referenced workflow does not exist in ${request.repository}.`,
+        `Workflows referenced: ${workflows.join(', ')}. A "watch" path in ` +
+          'deploy.nevermore.json must name a workflow that exists on the ' +
+          'dispatched ref.'
+      );
+    }
+    default:
+      return compose(
+        `Watch registration failed (${response.status} ${response.statusText}).`
+      );
+  }
+}
+
+/** Pull the API's `{error, errors}` shape out, falling back to raw text. */
+function _extractError(text: string): string {
+  if (text === '') {
+    return '';
+  }
+  try {
+    const parsed = JSON.parse(text) as {
+      error?: unknown;
+      errors?: unknown[];
+    };
+    const parts: string[] = [];
+    if (typeof parsed.error === 'string') {
+      parts.push(parsed.error);
+    }
+    if (Array.isArray(parsed.errors) && parsed.errors.length > 0) {
+      parts.push(JSON.stringify(parsed.errors));
+    }
+    return parts.length > 0 ? parts.join(' ') : text;
+  } catch {
+    return text;
+  }
+}
+
+async function _readTextAsync(response: Response): Promise<string> {
+  try {
+    return (await response.text()).trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Read back the fields worth reporting. A 2xx whose body we cannot parse still
+ * counts as registered — the service accepted it, and failing here would claim
+ * otherwise.
+ */
+function _parseResult(text: string): WatchRegistrationResult {
+  if (text === '') {
+    return {};
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return {};
+  }
+
+  const record = parsed as Record<string, unknown>;
+  const result: WatchRegistrationResult = {};
+  if (typeof record['monitorId'] === 'string') {
+    result.monitorId = record['monitorId'];
+  }
+  if (typeof record['revision'] === 'string') {
+    result.revision = record['revision'];
+  }
+  if (typeof record['leaseExpiresAt'] === 'string') {
+    result.leaseExpiresAt = record['leaseExpiresAt'];
+  }
+  if (typeof record['changed'] === 'boolean') {
+    result.changed = record['changed'];
+  }
+  if (Array.isArray(record['watches'])) {
+    result.watchCount = record['watches'].length;
+  }
+  return result;
+}