@hasna/connectors 1.3.46 → 1.4.1

package/connectors/googlephotos/src/cli/index.ts

@@ -122,7 +122,7 @@ authCmd
         const userInfo = await getUserInfo(result.tokens!.accessToken);
         const email = userInfo.email;
 
-        // Convert email to profile slug: andrei@hasna.com → andreihasnacom
+        // Convert email to profile slug: user@example.com → userexamplecom
         const profileSlug = email.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
 
         // Create profile if it doesn't exist

package/connectors/x/src/api/oauth.test.ts

@@ -0,0 +1,205 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import {
+  exchangeCodeForTokens,
+  refreshAccessToken,
+  revokeToken,
+  type OAuth2Config,
+} from './oauth';
+
+/**
+ * Regression tests for https://github.com/hasna/connectors/issues/1
+ *
+ * X rejects `Authorization: Basic <client_id:client_secret>` on
+ * POST /2/oauth2/token when the app is registered as a *public* client:
+ *   {"error":"unauthorized_client",
+ *    "error_description":"Missing valid authorization header"}
+ *
+ * The connector therefore must always authenticate the client with POST body
+ * parameters (`client_id`, plus `client_secret` when one is configured) and
+ * must never fall back to an Authorization header on the token/revoke
+ * endpoints.
+ */
+
+interface CapturedRequest {
+  url: string;
+  method?: string;
+  headers: Record<string, string>;
+  body: URLSearchParams;
+}
+
+const realFetch = globalThis.fetch;
+
+/**
+ * Normalise every shape `RequestInit.headers` can take (plain object, entry
+ * array, `Headers` instance) into a lower-cased record. Going through
+ * `new Headers(...)` matters: if the implementation ever switched to a
+ * `Headers` object, a naive `Object.entries()` would yield `[]` and the
+ * "no Authorization header" assertions below would pass vacuously.
+ */
+function normaliseHeaders(init?: RequestInit): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!init?.headers) return out;
+  new Headers(init.headers).forEach((value, key) => {
+    out[key.toLowerCase()] = value;
+  });
+  return out;
+}
+
+function captureTokenRequest(): { calls: CapturedRequest[] } {
+  const calls: CapturedRequest[] = [];
+
+  globalThis.fetch = (async (input: unknown, init?: RequestInit) => {
+    const headers = normaliseHeaders(init);
+
+    calls.push({
+      url: String(input),
+      method: init?.method,
+      headers,
+      body: new URLSearchParams(String(init?.body ?? '')),
+    });
+
+    return new Response(
+      JSON.stringify({
+        access_token: 'ACCESS_TOKEN',
+        refresh_token: 'NEW_REFRESH_TOKEN',
+        expires_in: 7200,
+        scope: 'tweet.read tweet.write offline.access',
+        token_type: 'bearer',
+      }),
+      { status: 200, headers: { 'Content-Type': 'application/json' } }
+    );
+  }) as typeof fetch;
+
+  return { calls };
+}
+
+const PUBLIC_CLIENT: OAuth2Config = {
+  clientId: 'PUBLIC_CLIENT_ID',
+  redirectUri: 'http://localhost:8888/callback',
+};
+
+const CONFIDENTIAL_CLIENT: OAuth2Config = {
+  clientId: 'CONFIDENTIAL_CLIENT_ID',
+  clientSecret: 'CONFIDENTIAL_CLIENT_SECRET',
+  redirectUri: 'http://localhost:8888/callback',
+};
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('OAuth 2.0 token requests - public client (issue #1)', () => {
+  test('exchangeCodeForTokens sends client_id in the body and no auth header', async () => {
+    const { calls } = captureTokenRequest();
+
+    const tokens = await exchangeCodeForTokens(
+      PUBLIC_CLIENT,
+      'AUTH_CODE',
+      'CODE_VERIFIER'
+    );
+
+    expect(calls).toHaveLength(1);
+    const req = calls[0]!;
+    expect(req.url).toBe('https://api.twitter.com/2/oauth2/token');
+    expect(req.method).toBe('POST');
+    expect(req.headers['authorization']).toBeUndefined();
+    expect(req.headers['content-type']).toBe(
+      'application/x-www-form-urlencoded'
+    );
+    expect(req.body.get('client_id')).toBe('PUBLIC_CLIENT_ID');
+    expect(req.body.get('client_secret')).toBeNull();
+    expect(req.body.get('grant_type')).toBe('authorization_code');
+    expect(req.body.get('code')).toBe('AUTH_CODE');
+    expect(req.body.get('code_verifier')).toBe('CODE_VERIFIER');
+    expect(req.body.get('redirect_uri')).toBe(
+      'http://localhost:8888/callback'
+    );
+
+    expect(tokens.accessToken).toBe('ACCESS_TOKEN');
+    expect(tokens.refreshToken).toBe('NEW_REFRESH_TOKEN');
+  });
+
+  test('refreshAccessToken sends client_id in the body and no auth header', async () => {
+    const { calls } = captureTokenRequest();
+
+    await refreshAccessToken(PUBLIC_CLIENT, 'OLD_REFRESH_TOKEN');
+
+    expect(calls).toHaveLength(1);
+    const req = calls[0]!;
+    expect(req.url).toBe('https://api.twitter.com/2/oauth2/token');
+    expect(req.headers['authorization']).toBeUndefined();
+    expect(req.body.get('grant_type')).toBe('refresh_token');
+    expect(req.body.get('refresh_token')).toBe('OLD_REFRESH_TOKEN');
+    expect(req.body.get('client_id')).toBe('PUBLIC_CLIENT_ID');
+    expect(req.body.get('client_secret')).toBeNull();
+  });
+
+  test('revokeToken sends client_id in the body and no auth header', async () => {
+    const { calls } = captureTokenRequest();
+
+    await revokeToken(PUBLIC_CLIENT, 'SOME_ACCESS_TOKEN', 'access_token');
+
+    expect(calls).toHaveLength(1);
+    const req = calls[0]!;
+    expect(req.url).toBe('https://api.twitter.com/2/oauth2/revoke');
+    expect(req.headers['authorization']).toBeUndefined();
+    expect(req.body.get('token')).toBe('SOME_ACCESS_TOKEN');
+    expect(req.body.get('token_type_hint')).toBe('access_token');
+    expect(req.body.get('client_id')).toBe('PUBLIC_CLIENT_ID');
+  });
+});
+
+describe('OAuth 2.0 token requests - configured client secret (issue #1)', () => {
+  // This is the exact trigger of issue #1: a client_secret is present in the
+  // connector config (env var or ~/.hasna/connectors/connect-x/credentials.json)
+  // while the X app itself is registered as a public client. Sending Basic auth
+  // in that situation is what produced "Missing valid authorization header".
+  test('never falls back to Basic auth when a client secret is configured', async () => {
+    const { calls } = captureTokenRequest();
+
+    await exchangeCodeForTokens(
+      CONFIDENTIAL_CLIENT,
+      'AUTH_CODE',
+      'CODE_VERIFIER'
+    );
+    await refreshAccessToken(CONFIDENTIAL_CLIENT, 'OLD_REFRESH_TOKEN');
+    await revokeToken(CONFIDENTIAL_CLIENT, 'SOME_ACCESS_TOKEN');
+
+    expect(calls).toHaveLength(3);
+    for (const req of calls) {
+      expect(req.headers['authorization']).toBeUndefined();
+      expect(req.body.get('client_id')).toBe('CONFIDENTIAL_CLIENT_ID');
+    }
+  });
+
+  test('still authenticates the client via client_secret_post', async () => {
+    const { calls } = captureTokenRequest();
+
+    await exchangeCodeForTokens(
+      CONFIDENTIAL_CLIENT,
+      'AUTH_CODE',
+      'CODE_VERIFIER'
+    );
+
+    expect(calls[0]!.body.get('client_secret')).toBe(
+      'CONFIDENTIAL_CLIENT_SECRET'
+    );
+  });
+});
+
+describe('OAuth 2.0 token requests - error surfacing', () => {
+  test('exchangeCodeForTokens surfaces the X error payload', async () => {
+    globalThis.fetch = (async () =>
+      new Response(
+        JSON.stringify({
+          error: 'unauthorized_client',
+          error_description: 'Missing valid authorization header',
+        }),
+        { status: 400 }
+      )) as typeof fetch;
+
+    await expect(
+      exchangeCodeForTokens(PUBLIC_CLIENT, 'AUTH_CODE', 'CODE_VERIFIER')
+    ).rejects.toThrow(/Token exchange failed:.*unauthorized_client/s);
+  });
+});

package/connectors/yousearch/README.md

@@ -25,7 +25,7 @@ export YOUSEARCH_API_KEY=your-api-key
 connect-yousearch search "latest AI news" --count 5
 
 # Web search with domain filters (POST)
-connect-yousearch search-post "alumia platform" --include-domains "hasna.com,github.com"
+connect-yousearch search-post "agent frameworks" --include-domains "example.com,github.com"
 
 # Multi-step research
 connect-yousearch research "What are the latest developments in AI agents?" --effort deep

package/connectors/zendesk/CLAUDE.md

@@ -43,7 +43,7 @@ connect-zendesk/
 - **EC2 Instance**: `hasna-prod-connect-zendesk`
 - **RDS Database**: `hasna-prod-connect-zendesk`
 - **S3 Bucket**: `hasna-prod-connect-zendesk`
-- **Remote API**: `https://connect.hasna.com/zendesk`
+- **Remote API**: deployment-specific; set `ZENDESK_REMOTE_API_URL` (no shipped default)
 
 ## Key Patterns
 

package/connectors/zendesk/Makefile

@@ -17,6 +17,8 @@ EC2_USER ?= ec2-user
 DEPLOY_PATH ?= /home/ec2-user/connectors/connect-zendesk
 SERVICE_NAME ?= connect-zendesk
 PORT ?= 21010
+# Public URL the deployed server is reachable at. Deployment-specific — no default.
+REMOTE_API_URL ?=
 
 # Default target
 help:
@@ -92,7 +94,7 @@ deploy-ec2: deploy-sync
 
 deploy: build deploy-ec2
 	@echo "✅ Deployment complete"
-	@echo "Server running at https://connect.hasna.com/zendesk"
+	@echo "Server running at $(if $(REMOTE_API_URL),$(REMOTE_API_URL),<REMOTE_API_URL not set>)"
 
 logs:
 	ssh $(EC2_USER)@$(EC2_HOST) "sudo journalctl -u $(SERVICE_NAME) -f"

package/connectors/zendesk/README.md

@@ -11,7 +11,7 @@ This connector provides programmatic access to Zendesk's Support API, including
 | EC2 Instance | `hasna-prod-connect-zendesk` |
 | RDS Database | `hasna-prod-connect-zendesk` |
 | S3 Bucket | `hasna-prod-connect-zendesk` |
-| Remote API | `https://connect.hasna.com/zendesk` |
+| Remote API | configured per deployment via `ZENDESK_REMOTE_API_URL` (no default) |
 
 ## Installation
 
@@ -279,7 +279,8 @@ This connector is deployed to:
 - **Database**: `hasna-prod-connect-zendesk`
 - **S3**: `hasna-prod-connect-zendesk`
 
-The remote API is accessible at `https://connect.hasna.com/zendesk`
+The remote API host is deployment-specific and has no built-in default. Point the CLI at your
+deployment with `ZENDESK_REMOTE_API_URL` or `connect-zendesk config set-remote-url <url>`.
 
 ## License
 

package/connectors/zendesk/SCAFFOLD.md

@@ -43,7 +43,7 @@ Each connector follows this naming pattern:
 | EC2 Instance | `hasna-prod-connect-{name}` | `hasna-prod-connect-notion` |
 | RDS Database | `hasna-prod-connect-{name}` | `hasna-prod-connect-notion` |
 | S3 Bucket | `hasna-prod-connect-{name}` | `hasna-prod-connect-notion` |
-| Remote API | `https://connect.hasna.com/{name}` | `https://connect.hasna.com/notion` |
+| Remote API | `https://<connect-host>/{name}` | `https://connect.example.com/notion` |
 
 ## Project Structure
 
@@ -175,4 +175,4 @@ The connector is deployed to AWS infrastructure:
 
 1. Build the project: `make build`
 2. Deploy to EC2: `make deploy-ec2`
-3. Configure the remote API at `https://connect.hasna.com/{name}`
+3. Point the CLI at the deployment via `<NAME>_REMOTE_API_URL` (no default is shipped)

package/connectors/zendesk/nginx-connector.conf

@@ -54,7 +54,7 @@ http {
 
     server {
         listen 80;
-        server_name connect.hasna.com;
+        server_name connect.example.com;
 
         location / {
             root /usr/share/nginx/html;
@@ -127,7 +127,7 @@ http {
 
     server {
         listen 80;
-        server_name gmail.connect.hasna.com;
+        server_name gmail.connect.example.com;
 
         location / {
             proxy_pass http://127.0.0.1:3001;
@@ -140,7 +140,7 @@ http {
 
     server {
         listen 80;
-        server_name googlecontacts.connect.hasna.com;
+        server_name googlecontacts.connect.example.com;
 
         location / {
             proxy_pass http://127.0.0.1:3002;
@@ -153,7 +153,7 @@ http {
 
     server {
         listen 80;
-        server_name googledrive.connect.hasna.com;
+        server_name googledrive.connect.example.com;
 
         location / {
             proxy_pass http://127.0.0.1:3003;
@@ -166,7 +166,7 @@ http {
 
     server {
         listen 80;
-        server_name linear.connect.hasna.com;
+        server_name linear.connect.example.com;
 
         location / {
             proxy_pass http://127.0.0.1:3004;
@@ -179,7 +179,7 @@ http {
 
     server {
         listen 80;
-        server_name notion.connect.hasna.com;
+        server_name notion.connect.example.com;
 
         location / {
             proxy_pass http://127.0.0.1:3005;
@@ -192,7 +192,7 @@ http {
 
     server {
         listen 80;
-        server_name clickbank.connect.hasna.com;
+        server_name clickbank.connect.example.com;
 
         location / {
             proxy_pass http://127.0.0.1:3013;
@@ -205,7 +205,7 @@ http {
 
     server {
         listen 80;
-        server_name zendesk.connect.hasna.com;
+        server_name zendesk.connect.example.com;
 
         location / {
             proxy_pass http://127.0.0.1:21010;

package/connectors/zendesk/nginx.conf

@@ -12,10 +12,10 @@ upstream connect_zendesk {
     keepalive 32;
 }
 
-# Main server block for connect.hasna.com/zendesk
-# Add this location block to the existing connect.hasna.com server
+# Main server block for connect.example.com/zendesk
+# Add this location block to the existing connect.example.com server
 #
-# If you have a separate server block for connect.hasna.com, add:
+# If you have a separate server block for connect.example.com, add:
 #
 #   location /zendesk {
 #       proxy_pass http://connect_zendesk;
@@ -30,21 +30,21 @@ upstream connect_zendesk {
 #       proxy_read_timeout 86400;
 #   }
 
-# Standalone server configuration (use if connect.hasna.com doesn't exist)
+# Standalone server configuration (use if connect.example.com doesn't exist)
 # Uncomment and modify as needed:
 #
 # server {
 #     listen 80;
-#     server_name connect.hasna.com;
+#     server_name connect.example.com;
 #     return 301 https://$host$request_uri;
 # }
 #
 # server {
 #     listen 443 ssl http2;
-#     server_name connect.hasna.com;
+#     server_name connect.example.com;
 #
-#     ssl_certificate /etc/letsencrypt/live/connect.hasna.com/fullchain.pem;
-#     ssl_certificate_key /etc/letsencrypt/live/connect.hasna.com/privkey.pem;
+#     ssl_certificate /etc/letsencrypt/live/connect.example.com/fullchain.pem;
+#     ssl_certificate_key /etc/letsencrypt/live/connect.example.com/privkey.pem;
 #
 #     location /zendesk {
 #         proxy_pass http://connect_zendesk;

package/connectors/zendesk/src/cli/index.ts

@@ -16,7 +16,7 @@ import {
   getConfigDir,
   getBaseConfigDir,
   getExportsDir,
-  getRemoteApiUrl,
+  findRemoteApiUrl,
   setRemoteApiUrl,
   setProfileOverride,
   getCurrentProfile,
@@ -238,7 +238,7 @@ configCmd
 
 configCmd
   .command('set-remote-url <url>')
-  .description('Set remote API URL (default: https://connect.hasna.com/zendesk)')
+  .description('Set remote API URL (no default; also settable via ZENDESK_REMOTE_API_URL)')
   .action((url: string) => {
     setRemoteApiUrl(url);
     success(`Remote API URL set to: ${url}`);
@@ -253,13 +253,13 @@ configCmd
     const apiToken = getApiToken();
     const baseUrl = getBaseUrl();
     const account = getDefaultAccount();
-    const remoteUrl = getRemoteApiUrl();
+    const remoteUrl = findRemoteApiUrl();
     info(`Profile: ${chalk.cyan(profile)}`);
     info(`Email: ${email || chalk.gray('not set')}`);
     info(`API Token: ${apiToken ? `${apiToken.substring(0, 6)}...${apiToken.substring(apiToken.length - 4)}` : chalk.gray('not set')}`);
     info(`Base URL: ${baseUrl || chalk.gray('not set')}`);
     info(`Default Account: ${account || chalk.gray('not set')}`);
-    info(`Remote API URL: ${remoteUrl}`);
+    info(`Remote API URL: ${remoteUrl || chalk.gray('not set')}`);
     info(`Config Directory: ${getBaseConfigDir()}`);
     info(`Profile Config: ${getConfigDir()}`);
     info(`Exports Directory: ${getExportsDir()}`);
@@ -274,17 +274,28 @@ configCmd
   });
 
 // ============================================
-// Remote API Commands (connect.hasna.com)
+// Remote API Commands (host comes from ZENDESK_REMOTE_API_URL / config)
 // ============================================
 const remoteCmd = program
   .command('remote')
   .description('Interact with the remote Zendesk connector API');
 
+// The remote host has no shipped default. Commands that need it exit with the
+// connector's usual error convention rather than an uncaught throw.
+function requireRemoteApiUrl(): string {
+  const remoteUrl = findRemoteApiUrl();
+  if (!remoteUrl) {
+    error('Remote API URL is not configured. Set ZENDESK_REMOTE_API_URL or run: connect-zendesk config set-remote-url <url>');
+    process.exit(1);
+  }
+  return remoteUrl;
+}
+
 remoteCmd
   .command('status')
   .description('Check remote API status')
   .action(async () => {
-    const remoteUrl = getRemoteApiUrl();
+    const remoteUrl = requireRemoteApiUrl();
     logger.command('remote status', { remoteUrl });
     try {
       const response = await fetch(`${remoteUrl}/status`);
@@ -301,7 +312,7 @@ remoteCmd
   .command('health')
   .description('Check remote API health')
   .action(async () => {
-    const remoteUrl = getRemoteApiUrl();
+    const remoteUrl = requireRemoteApiUrl();
     logger.command('remote health', { remoteUrl });
     try {
       const response = await fetch(`${remoteUrl}/health`);
@@ -321,7 +332,7 @@ remoteCmd
   .command('url')
   .description('Show current remote API URL')
   .action(() => {
-    info(`Remote API URL: ${getRemoteApiUrl()}`);
+    info(`Remote API URL: ${findRemoteApiUrl() || chalk.gray('not set')}`);
   });
 
 // ============================================

package/connectors/zendesk/src/server/index.ts

@@ -2,7 +2,7 @@
 /**
  * connect-zendesk server
  * Remote API server for Zendesk connector
- * Deployed at https://connect.hasna.com/zendesk
+ * Deployment host is environment-specific; see nginx.conf for the reverse-proxy template.
  */
 
 const PORT = parseInt(process.env.PORT || '3000');

package/connectors/zendesk/src/utils/config.test.ts

@@ -2,6 +2,14 @@ import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
 import { existsSync, rmSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
+import {
+  findRemoteApiUrl,
+  getRemoteApiUrl,
+  setRemoteApiUrl,
+  setProfileOverride,
+  getBaseConfigDir,
+  clearConfig,
+} from './config';
 
 // We need to test the config module with a custom config dir
 // to avoid messing with actual user config
@@ -190,4 +198,66 @@ describe('Config utilities', () => {
       else delete process.env.ZENDESK_EMAIL;
     });
   });
+
+  // The remote API URL no longer falls back to a hardcoded deployment host, so
+  // these exercise the real module instead of re-implementing the priority
+  // logic: an unconfigured URL has to fail loudly rather than silently resolve
+  // to a baked-in default, and each configured source has to round-trip.
+  describe('remote API URL resolution', () => {
+    const REMOTE_URL_TEST_PROFILE = 'remote-url-test';
+    const ENV_URL = 'https://env.example.com/zendesk';
+    const STORED_URL = 'https://stored.example.com/zendesk';
+
+    let originalEnv: string | undefined;
+
+    beforeEach(() => {
+      originalEnv = process.env.ZENDESK_REMOTE_API_URL;
+      delete process.env.ZENDESK_REMOTE_API_URL;
+      // Profiles are the module's own isolation seam: point config reads and
+      // writes at a throwaway profile so the real one is never touched.
+      setProfileOverride(REMOTE_URL_TEST_PROFILE);
+      clearConfig();
+    });
+
+    afterEach(() => {
+      setProfileOverride(undefined);
+      // Derive the throwaway path by name rather than from getConfigDir(), so
+      // this stays a delete of the test profile no matter how the override is
+      // sequenced above it.
+      rmSync(join(getBaseConfigDir(), 'profiles', REMOTE_URL_TEST_PROFILE), {
+        recursive: true,
+        force: true,
+      });
+
+      if (originalEnv === undefined) delete process.env.ZENDESK_REMOTE_API_URL;
+      else process.env.ZENDESK_REMOTE_API_URL = originalEnv;
+    });
+
+    test('is unset and throws when neither env nor config provides a URL', () => {
+      expect(findRemoteApiUrl()).toBeUndefined();
+      expect(() => getRemoteApiUrl()).toThrow(/ZENDESK_REMOTE_API_URL/);
+    });
+
+    test('resolves from the environment variable', () => {
+      process.env.ZENDESK_REMOTE_API_URL = ENV_URL;
+
+      expect(findRemoteApiUrl()).toBe(ENV_URL);
+      expect(getRemoteApiUrl()).toBe(ENV_URL);
+    });
+
+    test('resolves from the stored config value', () => {
+      setRemoteApiUrl(STORED_URL);
+
+      expect(findRemoteApiUrl()).toBe(STORED_URL);
+      expect(getRemoteApiUrl()).toBe(STORED_URL);
+    });
+
+    test('environment variable takes precedence over the stored config value', () => {
+      setRemoteApiUrl(STORED_URL);
+      process.env.ZENDESK_REMOTE_API_URL = ENV_URL;
+
+      expect(findRemoteApiUrl()).toBe(ENV_URL);
+      expect(getRemoteApiUrl()).toBe(ENV_URL);
+    });
+  });
 });

package/connectors/zendesk/src/utils/config.ts

@@ -499,10 +499,20 @@ export function clearConfig(): void {
   saveConfig({});
 }
 
-const DEFAULT_REMOTE_API_URL = 'https://connect.hasna.com/zendesk';
+// The remote API host is deployment-specific and has no shippable default.
+// Configure it with ZENDESK_REMOTE_API_URL or `connect-zendesk config set-remote-url <url>`.
+export function findRemoteApiUrl(): string | undefined {
+  return process.env.ZENDESK_REMOTE_API_URL || loadConfig().remoteApiUrl || undefined;
+}
 
 export function getRemoteApiUrl(): string {
-  return process.env.ZENDESK_REMOTE_API_URL || loadConfig().remoteApiUrl || DEFAULT_REMOTE_API_URL;
+  const url = findRemoteApiUrl();
+  if (!url) {
+    throw new Error(
+      'Remote API URL is not configured. Set ZENDESK_REMOTE_API_URL or run: connect-zendesk config set-remote-url <url>',
+    );
+  }
+  return url;
 }
 
 export function setRemoteApiUrl(url: string): void {

package/connectors/zendesk/src/utils/remote-url.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+// The remote API URL used to fall back to a hardcoded deployment host. It no
+// longer has a shipped default, so these lock in how the CLI behaves when it is
+// unset: display commands must still print, and commands that genuinely need
+// the URL must fail with actionable guidance rather than an uncaught throw.
+//
+// Resolution order itself is covered in config.test.ts. This file covers the
+// CLI surface: os.homedir() does not observe runtime process.env.HOME mutation,
+// so each case runs the real CLI in a subprocess with its own HOME.
+
+const CLI = join(import.meta.dir, '..', 'cli', 'index.ts');
+const ENV_KEY = 'ZENDESK_REMOTE_API_URL';
+
+let home: string;
+
+function runCli(args: string[], env: Record<string, string> = {}) {
+  const result = Bun.spawnSync({
+    cmd: ['bun', 'run', CLI, ...args],
+    env: { ...process.env, HOME: home, [ENV_KEY]: '', ...env },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  return {
+    code: result.exitCode,
+    out: new TextDecoder().decode(result.stdout) + new TextDecoder().decode(result.stderr),
+  };
+}
+
+describe('CLI behaviour when the remote API URL is unset', () => {
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'connect-zendesk-remote-url-'));
+  });
+
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+  });
+
+  test('config show reports it as unset instead of throwing', () => {
+    const { code, out } = runCli(['config', 'show']);
+    expect(code).toBe(0);
+    expect(out).toContain('Remote API URL:');
+    expect(out).toContain('not set');
+  });
+
+  test('remote url reports it as unset instead of throwing', () => {
+    const { code, out } = runCli(['remote', 'url']);
+    expect(code).toBe(0);
+    expect(out).toContain('not set');
+    expect(out).not.toContain('at getRemoteApiUrl');
+  });
+
+  test.each(['status', 'health'])(
+    'remote %s fails with actionable guidance, not a stack trace',
+    (sub) => {
+      const { code, out } = runCli(['remote', sub]);
+      expect(code).toBe(1);
+      expect(out).toContain(ENV_KEY);
+      expect(out).toContain('config set-remote-url');
+      expect(out).not.toContain('at getRemoteApiUrl');
+    },
+  );
+
+  test('no deployment host is baked in as a fallback', () => {
+    // A regression here means someone reintroduced a literal default.
+    const { out } = runCli(['remote', 'url']);
+    expect(out).not.toMatch(/https?:\/\/\S+/);
+  });
+});