@vellumai/assistant 0.3.0

package/src/__tests__/twitter-cli-error-shaping.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Tests for CLI error-shaping logic in the `run()` helper of twitter.ts.
+ *
+ * These tests verify that structured router metadata (pathUsed,
+ * suggestAlternative, oauthError) is preserved in CLI output while
+ * maintaining backward-compatible error codes.
+ */
+import { describe, test, expect } from 'bun:test';
+import { SessionExpiredError } from '../twitter/client.js';
+
+// ---------------------------------------------------------------------------
+// We test the error-shaping logic directly by reproducing the branching in
+// the CLI `run()` function. The actual `run()` function writes to stdout and
+// sets process.exitCode, which makes it awkward to test in isolation. Instead
+// we extract the payload-building logic into a pure helper and verify its
+// output here.
+// ---------------------------------------------------------------------------
+
+const SESSION_EXPIRED_MSG =
+  'Your Twitter session has expired. Please sign in to Twitter in Chrome — ' +
+  'run `vellum twitter refresh` to capture your session automatically.';
+
+/**
+ * Replicates the error-to-payload logic from `run()` in twitter.ts.
+ * Returns the JSON payload that would be written to stdout.
+ */
+function buildErrorPayload(err: unknown): Record<string, unknown> | null {
+  const meta = err as Record<string, unknown>;
+
+  if (err instanceof SessionExpiredError) {
+    const payload: Record<string, unknown> = {
+      ok: false,
+      error: 'session_expired',
+      message: SESSION_EXPIRED_MSG,
+    };
+    if (meta.pathUsed !== undefined) payload.pathUsed = meta.pathUsed;
+    if (meta.suggestAlternative !== undefined) payload.suggestAlternative = meta.suggestAlternative;
+    if (meta.oauthError !== undefined) payload.oauthError = meta.oauthError;
+    return payload;
+  }
+
+  if (err instanceof Error && (meta.pathUsed !== undefined || meta.suggestAlternative !== undefined || meta.oauthError !== undefined)) {
+    const payload: Record<string, unknown> = {
+      ok: false,
+      error: err.message,
+    };
+    if (meta.pathUsed !== undefined) payload.pathUsed = meta.pathUsed;
+    if (meta.suggestAlternative !== undefined) payload.suggestAlternative = meta.suggestAlternative;
+    if (meta.oauthError !== undefined) payload.oauthError = meta.oauthError;
+    return payload;
+  }
+
+  // Generic fallback
+  return { ok: false, error: err instanceof Error ? err.message : String(err) };
+}
+
+describe('CLI error shaping', () => {
+  test('plain SessionExpiredError preserves backward-compatible error code', () => {
+    const err = new SessionExpiredError('No Twitter session found.');
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'session_expired',
+      message: SESSION_EXPIRED_MSG,
+    });
+  });
+
+  test('SessionExpiredError from browser path preserves pathUsed and suggestAlternative', () => {
+    const err = Object.assign(new SessionExpiredError('Session cookies expired'), {
+      pathUsed: 'browser' as const,
+      suggestAlternative: 'oauth' as const,
+    });
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'session_expired',
+      message: SESSION_EXPIRED_MSG,
+      pathUsed: 'browser',
+      suggestAlternative: 'oauth',
+    });
+  });
+
+  test('SessionExpiredError from auto path preserves pathUsed and oauthError', () => {
+    const err = Object.assign(new SessionExpiredError('Session cookies expired'), {
+      pathUsed: 'auto' as const,
+      oauthError: 'Token revoked',
+    });
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'session_expired',
+      message: SESSION_EXPIRED_MSG,
+      pathUsed: 'auto',
+      oauthError: 'Token revoked',
+    });
+  });
+
+  test('routed non-session error with suggestAlternative emits structured JSON', () => {
+    const err = Object.assign(
+      new Error('OAuth is not configured. Set up OAuth credentials in Settings, or switch to browser strategy.'),
+      {
+        pathUsed: 'oauth' as const,
+        suggestAlternative: 'browser' as const,
+      },
+    );
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'OAuth is not configured. Set up OAuth credentials in Settings, or switch to browser strategy.',
+      pathUsed: 'oauth',
+      suggestAlternative: 'browser',
+    });
+  });
+
+  test('routed auto-mode error with oauthError and suggestAlternative', () => {
+    const err = Object.assign(
+      new Error('Both OAuth and browser paths failed'),
+      {
+        pathUsed: 'auto' as const,
+        suggestAlternative: 'browser' as const,
+        oauthError: 'Twitter API error (401)',
+      },
+    );
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'Both OAuth and browser paths failed',
+      pathUsed: 'auto',
+      suggestAlternative: 'browser',
+      oauthError: 'Twitter API error (401)',
+    });
+  });
+
+  test('auto-mode error with pathUsed and oauthError but no suggestAlternative preserves metadata', () => {
+    // This is the scenario flagged by Codex: routedPostTweet in auto mode tries
+    // OAuth (fails), then browser (fails with non-SessionExpiredError). The thrown
+    // error has pathUsed and oauthError but no suggestAlternative.
+    const err = Object.assign(
+      new Error('Browser automation failed: element not found'),
+      {
+        pathUsed: 'auto' as const,
+        oauthError: 'Twitter API error (401)',
+      },
+    );
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'Browser automation failed: element not found',
+      pathUsed: 'auto',
+      oauthError: 'Twitter API error (401)',
+    });
+  });
+
+  test('error with only pathUsed (no oauthError or suggestAlternative) preserves metadata', () => {
+    const err = Object.assign(
+      new Error('Something went wrong'),
+      { pathUsed: 'browser' as const },
+    );
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'Something went wrong',
+      pathUsed: 'browser',
+    });
+  });
+
+  test('generic error without router metadata falls back to plain error', () => {
+    const err = new Error('Network connection failed');
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'Network connection failed',
+    });
+  });
+
+  test('non-Error value falls back to stringified error', () => {
+    const payload = buildErrorPayload('some string error');
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'some string error',
+    });
+  });
+
+  test('backward compatibility: session_expired error code is always preserved', () => {
+    // Even with metadata, the error code stays 'session_expired'
+    const err = Object.assign(new SessionExpiredError('expired'), {
+      pathUsed: 'auto' as const,
+      suggestAlternative: 'oauth' as const,
+      oauthError: 'token expired',
+    });
+    const payload = buildErrorPayload(err);
+
+    expect(payload!.error).toBe('session_expired');
+    expect(payload!.ok).toBe(false);
+    expect(payload!.pathUsed).toBe('auto');
+    expect(payload!.suggestAlternative).toBe('oauth');
+    expect(payload!.oauthError).toBe('token expired');
+  });
+});

package/src/__tests__/twitter-cli-routing.test.ts

@@ -0,0 +1,252 @@
+import { describe, test, expect, mock, beforeEach } from 'bun:test';
+
+// --- Mocks (must be declared before importing the module under test) ---
+
+let mockStrategy: string | undefined = undefined;
+let mockOauthAvailable = false;
+let mockOauthPostResult: { tweetId: string; text: string; url?: string } | null = null;
+let mockOauthPostError: Error | null = null;
+let mockBrowserPostResult: { tweetId: string; text: string; url: string } | null = null;
+let mockBrowserPostError: Error | null = null;
+
+// Mock the config loader to return a controllable strategy
+mock.module('../config/loader.js', () => ({
+  loadRawConfig: () => {
+    if (mockStrategy !== undefined) {
+      return { twitterOperationStrategy: mockStrategy };
+    }
+    return {};
+  },
+  loadConfig: () => ({}),
+  saveConfig: () => {},
+  saveRawConfig: () => {},
+  getConfig: () => ({}),
+  invalidateConfigCache: () => {},
+  getNestedValue: () => undefined,
+  setNestedValue: () => {},
+  API_KEY_PROVIDERS: [],
+}));
+
+// Mock the OAuth client
+mock.module('../twitter/oauth-client.js', () => ({
+  oauthIsAvailable: () => mockOauthAvailable,
+  oauthSupportsOperation: (op: string) => op === 'post' || op === 'reply',
+  oauthPostTweet: async (_text: string, _opts?: { inReplyToTweetId?: string }) => {
+    if (mockOauthPostError) throw mockOauthPostError;
+    if (mockOauthPostResult) return mockOauthPostResult;
+    throw new Error('OAuth mock not configured');
+  },
+  UnsupportedOAuthOperationError: class UnsupportedOAuthOperationError extends Error {
+    public readonly suggestFallback = true;
+    public readonly fallbackPath = 'browser' as const;
+    public readonly operation: string;
+    constructor(operation: string) {
+      super(`The "${operation}" operation is not available via the OAuth API.`);
+      this.name = 'UnsupportedOAuthOperationError';
+      this.operation = operation;
+    }
+  },
+}));
+
+// Create a SessionExpiredError class that matches the real one
+class MockSessionExpiredError extends Error {
+  constructor(reason: string) {
+    super(reason);
+    this.name = 'SessionExpiredError';
+  }
+}
+
+// Mock the browser client
+mock.module('../twitter/client.js', () => ({
+  postTweet: async (_text: string, _opts?: { inReplyToTweetId?: string }) => {
+    if (mockBrowserPostError) throw mockBrowserPostError;
+    if (mockBrowserPostResult) return mockBrowserPostResult;
+    throw new Error('Browser mock not configured');
+  },
+  SessionExpiredError: MockSessionExpiredError,
+}));
+
+// Mock the logger to silence output
+mock.module('../util/logger.js', () => ({
+  getLogger: () => ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+    trace: () => {},
+    fatal: () => {},
+    child: () => ({
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    }),
+  }),
+}));
+
+import { routedPostTweet } from '../twitter/router.js';
+
+beforeEach(() => {
+  mockStrategy = undefined;
+  mockOauthAvailable = false;
+  mockOauthPostResult = null;
+  mockOauthPostError = null;
+  mockBrowserPostResult = null;
+  mockBrowserPostError = null;
+});
+
+describe('Twitter strategy router', () => {
+  describe('auto strategy', () => {
+    test('uses OAuth when available and supported', async () => {
+      mockOauthAvailable = true;
+      mockOauthPostResult = { tweetId: '111', text: 'hello', url: 'https://x.com/u/status/111' };
+
+      const { result, pathUsed } = await routedPostTweet('hello');
+
+      expect(pathUsed).toBe('oauth');
+      expect(result.tweetId).toBe('111');
+      expect(result.text).toBe('hello');
+      expect(result.url).toBe('https://x.com/u/status/111');
+    });
+
+    test('falls back to browser when OAuth is unavailable', async () => {
+      mockOauthAvailable = false;
+      mockBrowserPostResult = { tweetId: '222', text: 'hello', url: 'https://x.com/u/status/222' };
+
+      const { result, pathUsed } = await routedPostTweet('hello');
+
+      expect(pathUsed).toBe('browser');
+      expect(result.tweetId).toBe('222');
+    });
+
+    test('falls back to browser when OAuth fails', async () => {
+      mockOauthAvailable = true;
+      mockOauthPostError = new Error('OAuth token expired');
+      mockBrowserPostResult = { tweetId: '333', text: 'hello', url: 'https://x.com/u/status/333' };
+
+      const { result, pathUsed } = await routedPostTweet('hello');
+
+      expect(pathUsed).toBe('browser');
+      expect(result.tweetId).toBe('333');
+    });
+
+    test('constructs URL from tweetId when OAuth result has no url', async () => {
+      mockOauthAvailable = true;
+      mockOauthPostResult = { tweetId: '444', text: 'no url' };
+
+      const { result, pathUsed } = await routedPostTweet('no url');
+
+      expect(pathUsed).toBe('oauth');
+      expect(result.url).toBe('https://x.com/i/status/444');
+    });
+
+    test('throws combined error when both OAuth and browser fail with SessionExpiredError', async () => {
+      mockOauthAvailable = true;
+      mockOauthPostError = new Error('OAuth failed');
+      mockBrowserPostError = new MockSessionExpiredError('Browser session expired');
+
+      try {
+        await routedPostTweet('will fail');
+        expect(true).toBe(false); // should not reach
+      } catch (err) {
+        const e = err as Error & { pathUsed: string; oauthError?: string };
+        expect(e).toBeInstanceOf(MockSessionExpiredError);
+        expect(e.message).toBe('Browser session expired');
+        expect(e.pathUsed).toBe('auto');
+        expect(e.oauthError).toBe('OAuth failed');
+      }
+    });
+  });
+
+  describe('explicit oauth strategy', () => {
+    test('fails with helpful error when OAuth is not configured', async () => {
+      mockStrategy = 'oauth';
+      mockOauthAvailable = false;
+
+      try {
+        await routedPostTweet('hello');
+        expect(true).toBe(false); // should not reach
+      } catch (err) {
+        const e = err as Error & { pathUsed: string; suggestAlternative: string };
+        expect(e.message).toContain('OAuth is not configured');
+        expect(e.message).toContain('vellum x strategy set browser');
+        expect(e.pathUsed).toBe('oauth');
+        expect(e.suggestAlternative).toBe('browser');
+      }
+    });
+
+    test('uses OAuth when available', async () => {
+      mockStrategy = 'oauth';
+      mockOauthAvailable = true;
+      mockOauthPostResult = { tweetId: '555', text: 'oauth post' };
+
+      const { result, pathUsed } = await routedPostTweet('oauth post');
+
+      expect(pathUsed).toBe('oauth');
+      expect(result.tweetId).toBe('555');
+    });
+  });
+
+  describe('explicit browser strategy', () => {
+    test('uses browser directly, ignoring OAuth availability', async () => {
+      mockStrategy = 'browser';
+      mockOauthAvailable = true; // available but should be ignored
+      mockBrowserPostResult = { tweetId: '666', text: 'browser post', url: 'https://x.com/u/status/666' };
+
+      const { result, pathUsed } = await routedPostTweet('browser post');
+
+      expect(pathUsed).toBe('browser');
+      expect(result.tweetId).toBe('666');
+    });
+
+    test('preserves SessionExpiredError type with router metadata', async () => {
+      mockStrategy = 'browser';
+      mockBrowserPostError = new MockSessionExpiredError('Session expired');
+
+      try {
+        await routedPostTweet('will fail');
+        expect(true).toBe(false); // should not reach
+      } catch (err) {
+        const e = err as Error & { pathUsed: string; suggestAlternative: string };
+        expect(e).toBeInstanceOf(MockSessionExpiredError);
+        expect(e.message).toBe('Session expired');
+        expect(e.pathUsed).toBe('browser');
+        expect(e.suggestAlternative).toBe('oauth');
+      }
+    });
+
+    test('re-throws non-session errors without wrapping', async () => {
+      mockStrategy = 'browser';
+      mockBrowserPostError = new Error('Network failure');
+
+      try {
+        await routedPostTweet('will fail');
+        expect(true).toBe(false); // should not reach
+      } catch (err) {
+        expect((err as Error).message).toBe('Network failure');
+      }
+    });
+  });
+
+  describe('reply routing', () => {
+    test('auto strategy routes reply through OAuth when available', async () => {
+      mockOauthAvailable = true;
+      mockOauthPostResult = { tweetId: '777', text: 'reply text', url: 'https://x.com/u/status/777' };
+
+      const { result, pathUsed } = await routedPostTweet('reply text', { inReplyToTweetId: '100' });
+
+      expect(pathUsed).toBe('oauth');
+      expect(result.tweetId).toBe('777');
+    });
+
+    test('browser strategy routes reply through browser', async () => {
+      mockStrategy = 'browser';
+      mockBrowserPostResult = { tweetId: '888', text: 'reply text', url: 'https://x.com/u/status/888' };
+
+      const { result, pathUsed } = await routedPostTweet('reply text', { inReplyToTweetId: '200' });
+
+      expect(pathUsed).toBe('browser');
+      expect(result.tweetId).toBe('888');
+    });
+  });
+});

package/src/__tests__/twitter-oauth-client.test.ts

@@ -0,0 +1,209 @@
+import { describe, test, expect, mock, beforeEach, afterEach } from 'bun:test';
+
+// --- Mocks (must be declared before importing the module under test) ---
+
+let secureKeyStore: Record<string, string> = {};
+
+mock.module('../security/secure-keys.js', () => ({
+  getSecureKey: (account: string) => secureKeyStore[account] ?? undefined,
+  setSecureKey: (account: string, value: string) => {
+    secureKeyStore[account] = value;
+    return true;
+  },
+  deleteSecureKey: () => true,
+  listSecureKeys: () => Object.keys(secureKeyStore),
+  getBackendType: () => 'encrypted',
+  isDowngradedFromKeychain: () => false,
+  _resetBackend: () => {},
+  _setBackend: () => {},
+}));
+
+// withValidToken: call the callback directly with a fake token.
+mock.module('../security/token-manager.js', () => ({
+  withValidToken: async (_service: string, cb: (token: string) => Promise<unknown>) =>
+    cb('fake-oauth-token'),
+  TokenExpiredError: class TokenExpiredError extends Error {
+    constructor(public readonly service: string, message?: string) {
+      super(message ?? `Token expired for "${service}".`);
+      this.name = 'TokenExpiredError';
+    }
+  },
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+    trace: () => {},
+    fatal: () => {},
+    child: () => ({
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    }),
+  }),
+}));
+
+import {
+  oauthPostTweet,
+  oauthIsAvailable,
+  oauthSupportsOperation,
+  UnsupportedOAuthOperationError,
+} from '../twitter/oauth-client.js';
+
+// --- Global fetch mock ---
+
+const originalFetch = globalThis.fetch;
+let _fetchMock: ReturnType<typeof mock> | null = null;
+
+beforeEach(() => {
+  secureKeyStore = {};
+  _fetchMock = null;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+function mockFetch(response: { ok: boolean; status: number; json?: unknown; text?: string }) {
+  const fn = mock(() =>
+    Promise.resolve({
+      ok: response.ok,
+      status: response.status,
+      json: () => Promise.resolve(response.json),
+      text: () => Promise.resolve(response.text ?? ''),
+    }),
+  );
+  globalThis.fetch = fn as unknown as typeof fetch;
+  _fetchMock = fn;
+  return fn;
+}
+
+describe('Twitter OAuth client', () => {
+  describe('oauthPostTweet', () => {
+    test('successfully posts and returns tweet ID', async () => {
+      const fn = mockFetch({
+        ok: true,
+        status: 200,
+        json: { data: { id: '12345', text: 'Hello world' } },
+      });
+
+      const result = await oauthPostTweet('Hello world');
+
+      expect(result.tweetId).toBe('12345');
+      expect(result.text).toBe('Hello world');
+
+      // Verify the request was made correctly
+      expect(fn).toHaveBeenCalledTimes(1);
+      const [url, opts] = fn.mock.calls[0] as unknown as [string, RequestInit];
+      expect(url).toBe('https://api.x.com/2/tweets');
+      expect(opts.method).toBe('POST');
+      expect((opts.headers as Record<string, string>)['Authorization']).toBe('Bearer fake-oauth-token');
+      expect((opts.headers as Record<string, string>)['Content-Type']).toBe('application/json');
+
+      const body = JSON.parse(opts.body as string);
+      expect(body.text).toBe('Hello world');
+      expect(body.reply).toBeUndefined();
+    });
+
+    test('with reply returns correct result', async () => {
+      const fn = mockFetch({
+        ok: true,
+        status: 200,
+        json: { data: { id: '67890', text: 'My reply' } },
+      });
+
+      const result = await oauthPostTweet('My reply', { inReplyToTweetId: '11111' });
+
+      expect(result.tweetId).toBe('67890');
+      expect(result.text).toBe('My reply');
+
+      const [, opts] = fn.mock.calls[0] as unknown as [string, RequestInit];
+      const body = JSON.parse(opts.body as string);
+      expect(body.text).toBe('My reply');
+      expect(body.reply).toEqual({ in_reply_to_tweet_id: '11111' });
+    });
+
+    test('throws on API error', async () => {
+      mockFetch({
+        ok: false,
+        status: 429,
+        text: 'Rate limit exceeded',
+      });
+
+      await expect(oauthPostTweet('will fail')).rejects.toThrow(
+        /Twitter API error \(429\)/,
+      );
+    });
+
+    test('attaches status to thrown error for token manager retry', async () => {
+      mockFetch({
+        ok: false,
+        status: 401,
+        text: 'Unauthorized',
+      });
+
+      try {
+        await oauthPostTweet('will fail');
+        expect(true).toBe(false); // should not reach
+      } catch (err) {
+        expect((err as Error & { status: number }).status).toBe(401);
+      }
+    });
+  });
+
+  describe('oauthIsAvailable', () => {
+    test('returns true when access token exists', () => {
+      secureKeyStore['credential:integration:twitter:access_token'] = 'some-token';
+      expect(oauthIsAvailable()).toBe(true);
+    });
+
+    test('returns false when no access token', () => {
+      expect(oauthIsAvailable()).toBe(false);
+    });
+  });
+
+  describe('oauthSupportsOperation', () => {
+    test('returns true for post', () => {
+      expect(oauthSupportsOperation('post')).toBe(true);
+    });
+
+    test('returns true for reply', () => {
+      expect(oauthSupportsOperation('reply')).toBe(true);
+    });
+
+    test('returns false for unsupported operations', () => {
+      const unsupported = [
+        'timeline',
+        'search',
+        'bookmarks',
+        'home',
+        'notifications',
+        'likes',
+        'followers',
+        'following',
+        'media',
+        'tweet',
+      ];
+      for (const op of unsupported) {
+        expect(oauthSupportsOperation(op)).toBe(false);
+      }
+    });
+  });
+
+  describe('UnsupportedOAuthOperationError', () => {
+    test('has correct properties', () => {
+      const err = new UnsupportedOAuthOperationError('search');
+      expect(err.name).toBe('UnsupportedOAuthOperationError');
+      expect(err.operation).toBe('search');
+      expect(err.suggestFallback).toBe(true);
+      expect(err.fallbackPath).toBe('browser');
+      expect(err.message).toContain('search');
+      expect(err.message).toContain('not available via the OAuth API');
+      expect(err).toBeInstanceOf(Error);
+    });
+  });
+});