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

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

@@ -0,0 +1,184 @@
+import { execSync } from 'child_process';
+
+/**
+ * Env var holding the token the watch service dispatches with. Checked before
+ * `GITHUB_TOKEN` so a long-lived registration token can be kept separate from
+ * the short-lived one a workflow run is handed — an Actions `GITHUB_TOKEN`
+ * expires with its job, which would outlive nothing.
+ */
+const WATCH_TOKEN_ENV = 'NEVERMORE_WATCH_TOKEN';
+
+/** Everything the watch service needs to dispatch a workflow back at us. */
+export interface GithubDispatchContext {
+  /** `owner/repo`. */
+  repository: string;
+  /** Git ref the dispatched workflow should run on. */
+  ref: string;
+  /** Token the service dispatches with; absent when none was provided. */
+  token?: string;
+}
+
+export interface GithubContextOptions {
+  /**
+   * Read the token from the GitHub CLI when no environment variable supplies
+   * one.
+   *
+   * Off unless asked for, and that is the whole point. Registering sends a PAT
+   * to the watch service and creates a monitor against the repository, so the
+   * credential has to be one the user handed over — an env var is handing it
+   * over, reading whatever `gh` happens to be holding is not. Nearly every
+   * developer machine has a logged-in `gh`, so defaulting this on would turn a
+   * command that used to watch locally into one that quietly ships a token.
+   */
+  useGhAuth?: boolean;
+}
+
+export type GithubContextResult =
+  | { success: true; context: GithubDispatchContext }
+  | {
+      success: false;
+      reason: 'no_repository' | 'no_ref' | 'undispatchable_ref';
+    };
+
+/**
+ * A `pull_request` run exposes `GITHUB_REF_NAME` as `42/merge` — a synthetic
+ * merge ref that exists only for that check run. It is not a branch, so
+ * `workflow_dispatch` cannot run on it, and it disappears when the PR closes.
+ */
+const MERGE_REF_PATTERN = /^\d+\/(merge|head)$/;
+
+/**
+ * Read an env var, treating empty as absent.
+ *
+ * CI sets a variable to the empty string when the secret behind it is missing
+ * (`FOO: ${{ secrets.ABSENT }}`), which `??` would accept as a real value —
+ * so the documented fallback to the next source would never fire.
+ */
+function _env(name: string): string | undefined {
+  const value = process.env[name];
+  return value == null || value === '' ? undefined : value;
+}
+
+/**
+ * Work out which repo and ref a watch should dispatch.
+ *
+ * Prefers the Actions environment, which is authoritative when we are already
+ * running inside the workflow being registered, and falls back to the git
+ * remote so `--watch <url>` also works from a developer's machine. Best-effort:
+ * outside a git repo with no Actions env there is simply nothing to dispatch.
+ */
+export function tryResolveGithubDispatchContext(
+  options: GithubContextOptions = {}
+): GithubContextResult {
+  const repository = _env('GITHUB_REPOSITORY') ?? _repositoryFromRemote();
+  if (!repository) {
+    return { success: false, reason: 'no_repository' };
+  }
+
+  const ref =
+    _env('GITHUB_REF_NAME') ?? _git(['rev-parse', '--abbrev-ref', 'HEAD']);
+  // A detached HEAD gives "HEAD", which is not a ref a dispatch can run on.
+  if (!ref || ref === 'HEAD') {
+    return { success: false, reason: 'no_ref' };
+  }
+  if (MERGE_REF_PATTERN.test(ref)) {
+    return { success: false, reason: 'undispatchable_ref' };
+  }
+
+  const token =
+    _env(WATCH_TOKEN_ENV) ??
+    _env('GITHUB_TOKEN') ??
+    (options.useGhAuth ? _githubCliToken() : undefined);
+
+  return { success: true, context: { repository, ref, token } };
+}
+
+/** Human-facing explanation for a failed context resolution. */
+export function describeGithubContextFailure(
+  reason: 'no_repository' | 'no_ref' | 'undispatchable_ref'
+): string {
+  if (reason === 'no_repository') {
+    return (
+      'Could not determine the GitHub repository to dispatch. Set ' +
+      'GITHUB_REPOSITORY (owner/repo), or run from a clone with a GitHub ' +
+      '"origin" remote.'
+    );
+  }
+  if (reason === 'undispatchable_ref') {
+    return (
+      'Refusing to register a watch from a pull request merge ref. That ref ' +
+      'exists only for this check run, so a dispatch against it would fail ' +
+      'and it disappears when the PR closes. Register from a branch instead ' +
+      '(e.g. on push to main).'
+    );
+  }
+  return (
+    'Could not determine the git ref to dispatch on. Set GITHUB_REF_NAME, or ' +
+    'check out a branch (a detached HEAD has no ref to run a workflow from).'
+  );
+}
+
+/** Hint printed when a cloud registration has no credential to hand over. */
+export function describeMissingWatchToken(): string {
+  return [
+    'No GitHub token found. The watch service identifies you by repository, ' +
+      'so registering needs a token with "actions: write" on it. Either:',
+    `  - Set: ${WATCH_TOKEN_ENV} (or GITHUB_TOKEN)`,
+    '  - Pass: --watch-use-gh-auth, to use the token `gh` already holds',
+  ].join('\n');
+}
+
+/**
+ * Pull `owner/repo` out of a git remote URL. Handles the HTTPS, SCP-style, and
+ * ssh:// spellings git hands out, and ignores non-GitHub hosts — a watch
+ * registration names a GitHub workflow, so anything else is not dispatchable.
+ */
+export function parseGithubRepository(remoteUrl: string): string | undefined {
+  const trimmed = remoteUrl.trim();
+  const match =
+    /^(?:https?:\/\/|ssh:\/\/)?(?:[^@/]+@)?github\.com[:/]+([^/]+)\/(.+?)(?:\.git)?\/?$/i.exec(
+      trimmed
+    );
+  if (!match) {
+    return undefined;
+  }
+  return `${match[1]}/${match[2]}`;
+}
+
+function _repositoryFromRemote(): string | undefined {
+  const remote = _git(['remote', 'get-url', 'origin']);
+  return remote == null ? undefined : parseGithubRepository(remote);
+}
+
+/**
+ * The token `gh` is already holding, if it is installed and logged in.
+ *
+ * Only ever called when the caller opted in. Not stored anywhere by us on
+ * purpose: `gh` owns its own refresh, and copying a token into `~/.nevermore`
+ * would leave a stale duplicate to expire behind everyone's back — the point is
+ * reading the live one, for the one run that asked.
+ */
+function _githubCliToken(): string | undefined {
+  const token = _run('gh', ['auth', 'token']);
+  // A logged-out `gh` exits non-zero, but an odd version could print a notice
+  // on stdout instead; a token is never whitespace.
+  return token == null || /\s/.test(token) ? undefined : token;
+}
+
+function _git(args: string[]): string | undefined {
+  return _run('git', args);
+}
+
+function _run(command: string, args: string[]): string | undefined {
+  try {
+    const output = execSync(`${command} ${args.join(' ')}`, {
+      encoding: 'utf-8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return output === '' ? undefined : output;
+  } catch {
+    // Not installed, not logged in, or not a repo — all "no answer here".
+    return undefined;
+  }
+}

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/
+      );
+    });
+  });
+});