feat(configure): add --instance preflight validation for configure

Add capability to validate instance names before proceeding with
operations. The validation makes a request to the running instance's
liveness check endpoint to verify that the instance exists and is
accessible.

Author: rwjblue-glean

src/configure.ts

@@ -14,7 +14,8 @@ import dotenv from 'dotenv';
 import { availableClients, ensureClientsLoaded } from './configure/index.js';
 import { VERSION } from './common/version.js';
 import { ensureAuthTokenPresence } from './auth/auth.js';
-import { trace } from './log/logger.js';
+import { trace, error } from './log/logger.js';
+import { validateInstance } from './util/preflight.js';
 
 /**
  * Configure options interface
@@ -118,6 +119,16 @@ export async function configure(client: string, options: ConfigureOptions) {
   const homedir = os.homedir();
   const configFilePath = clientConfig.configFilePath(homedir);
 
+  if (options.instance && process.env._SKIP_INSTANCE_PREFLIGHT !== 'true') {
+    trace(`Validating instance: ${options.instance}...`);
+    if (!(await validateInstance(options.instance))) {
+      error(`Error validating instance: ${options.instance}`);
+      console.error(`Could not validate instance: ${options.instance}`);
+      console.error('Please check the `--instance` and try again.');
+      process.exit(1);
+    }
+  }
+
   try {
     // If token is provided, use token auth
     if (options.token) {

src/test/cli.test.ts

@@ -37,11 +37,13 @@ describe('CLI', () => {
   });
 
   beforeEach(async () => {
+    process.env._SKIP_INSTANCE_PREFLIGHT = 'true';
     project = await setupProject();
   });
 
   afterEach(() => {
     teardownProject();
+    delete process.env._SKIP_INSTANCE_PREFLIGHT;
   });
 
   it('shows help when no arguments provided', async () => {

src/test/mocks/handlers.ts

@@ -1,6 +1,32 @@
 import { http, HttpResponse } from 'msw';
 
 export const handlers = [
+  http.get(
+    'https://:instance-be.glean.com/liveness_check',
+    async ({ params }) => {
+      const { instance } = params;
+
+      if (instance === 'invalid-instance') {
+        return new HttpResponse(null, {
+          status: 404,
+          statusText: 'Not Found',
+        });
+      }
+
+      if (instance === 'network-error') {
+        const error = new Error('Network error');
+        error.name = 'FetchError';
+        throw error;
+      }
+
+      return new HttpResponse(JSON.stringify({ status: 'ok' }), {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+    },
+  ),
   http.post(
     'https://:instance-be.glean.com/rest/api/v1/search',
     async ({ request }) => {

src/test/util/preflight.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { validateInstance } from '../../util/preflight.js';
+import '../mocks/setup';
+
+describe('Preflight Validation', () => {
+  beforeEach(() => {
+    // Reset any environment variables that might affect the tests
+    delete process.env.GLEAN_BASE_URL;
+    delete process.env.GLEAN_INSTANCE;
+  });
+
+  it('returns true for a valid instance name', async () => {
+    const result = await validateInstance('valid-instance');
+    expect(result).toBe(true);
+  });
+
+  it('returns false for invalid instance name', async () => {
+    expect(await validateInstance('invalid-instance')).toEqual(false);
+  });
+
+  it('returns false for network errors', async () => {
+    expect(await validateInstance('network-error')).toEqual(false);
+  });
+
+  it('returns false if `instance` is missing', async () => {
+    expect(await validateInstance('')).toEqual(false);
+  });
+});

src/util/preflight.ts

@@ -0,0 +1,42 @@
+import { trace, error } from '../log/logger.js';
+
+/**
+ * Validates that the given instance name is valid by checking its liveness endpoint.
+ * Makes a fetch request to https://{instance}-be.glean.com/liveness_check
+ *
+ * @param instance - The instance name to validate
+ * @returns A Promise that resolves to true if the instance is valid
+ */
+export async function validateInstance(instance: string): Promise<boolean> {
+  if (!instance) {
+    trace('No instance provided for validation');
+    return false;
+  }
+
+  try {
+    const url = `https://${instance}-be.glean.com/liveness_check`;
+    trace(`Checking instance validity with: ${url}`);
+
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+      },
+    });
+
+    // We only care that the request succeeds, not about the response content
+    if (!response.ok) {
+      error(
+        `Instance validation failed for ${instance}: ${response.status} ${response.statusText}`,
+      );
+      return false;
+    }
+
+    return true;
+  } catch (err) {
+    const cause = err instanceof Error ? err : new Error(String(err));
+
+    error(`Instance validation failed: ${cause.message}`);
+    return false;
+  }
+}