@amodalai/amodal 0.1.2

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@amodalai/amodal",
+  "version": "0.1.2",
+  "description": "Amodal CLI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amodalai/amodal.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/amodalai/amodal",
+  "bugs": {
+    "url": "https://github.com/amodalai/amodal/issues"
+  },
+  "type": "module",
+  "main": "dist/src/main.js",
+  "bin": {
+    "amodal": "dist/src/main.js"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "ink": "^6.8.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "marked": "^17.0.4",
+    "marked-terminal": "^7.3.0",
+    "open": "^10.1.0",
+    "prompts": "^2.4.2",
+    "react": "^19.2.4",
+    "semver": "^7.6.0",
+    "yargs": "^17.7.2",
+    "zod": "^4.3.6",
+    "@amodalai/core": "0.1.2",
+    "@amodalai/runtime": "0.1.2"
+  },
+  "peerDependencies": {
+    "@amodalai/runtime-app": "0.1.2"
+  },
+  "peerDependenciesMeta": {
+    "@amodalai/runtime-app": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "@types/prompts": "^2.4.9",
+    "@types/react": "^19.2.14",
+    "@types/semver": "^7.7.0",
+    "@types/yargs": "^17.0.32",
+    "typescript": "^5.3.3",
+    "vitest": "^3.1.1"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:ci": "vitest run --exclude 'src/e2e*.test.ts'",
+    "lint": "eslint src/"
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './types.js';
+export {getRequiredEnvVars, promptForCredentials} from './prompt.js';
+export type {PromptCredentialsOptions} from './prompt.js';
+export {testConnection} from './test-connection.js';
+export type {TestConnectionOptions} from './test-connection.js';
+export {runOAuth2Flow, OAuth2Error} from './oauth2.js';
+export type {OAuth2Options} from './oauth2.js';

package/src/auth/oauth2.test.ts

@@ -0,0 +1,305 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+
+const mockOpen = vi.fn();
+
+vi.mock('open', () => ({
+  default: (...args: unknown[]) => mockOpen(...args),
+}));
+
+import {
+  startCallbackServer,
+  buildAuthorizeUrl,
+  exchangeCodeForTokens,
+  mapTokensToEnvVars,
+  runOAuth2Flow,
+  OAuth2Error,
+} from './oauth2.js';
+import type {OAuth2Options} from './oauth2.js';
+
+describe('startCallbackServer', () => {
+  it('starts a server on a random port', async () => {
+    const {server, port} = await startCallbackServer();
+    expect(port).toBeGreaterThan(0);
+    server.close();
+  });
+
+  it('resolves code from callback request', async () => {
+    const {server, port, codePromise} = await startCallbackServer();
+
+    // Simulate browser callback
+    await fetch(`http://127.0.0.1:${port}/callback?code=abc123&state=mystate`);
+    const result = await codePromise;
+
+    expect(result.code).toBe('abc123');
+    expect(result.state).toBe('mystate');
+    server.close();
+  });
+
+  it('rejects on error callback', async () => {
+    const {server, port, codePromise} = await startCallbackServer();
+
+    // Attach catch handler before triggering to avoid unhandled rejection
+    const rejection = codePromise.catch((err: unknown) => err);
+    await fetch(`http://127.0.0.1:${port}/callback?error=access_denied&error_description=User+denied`);
+    const err = await rejection;
+    expect(err).toBeInstanceOf(OAuth2Error);
+    expect((err as Error).message).toContain('User denied');
+    server.close();
+  });
+
+  it('rejects on missing code parameter', async () => {
+    const {server, port, codePromise} = await startCallbackServer();
+
+    const rejection = codePromise.catch((err: unknown) => err);
+    await fetch(`http://127.0.0.1:${port}/callback`);
+    const err = await rejection;
+    expect(err).toBeInstanceOf(OAuth2Error);
+    expect((err as Error).message).toContain('Missing code or state');
+    server.close();
+  });
+
+  it('returns 404 for non-callback paths', async () => {
+    const {server, port} = await startCallbackServer();
+
+    const response = await fetch(`http://127.0.0.1:${port}/other`);
+    expect(response.status).toBe(404);
+    server.close();
+  });
+});
+
+describe('buildAuthorizeUrl', () => {
+  const baseOptions: OAuth2Options = {
+    authorizeUrl: 'https://auth.example.com/authorize',
+    tokenUrl: 'https://auth.example.com/token',
+    clientId: 'client123',
+  };
+
+  it('includes required parameters', () => {
+    const url = buildAuthorizeUrl(baseOptions.authorizeUrl, baseOptions, 8080, 'state123');
+    const parsed = new URL(url);
+
+    expect(parsed.searchParams.get('response_type')).toBe('code');
+    expect(parsed.searchParams.get('client_id')).toBe('client123');
+    expect(parsed.searchParams.get('redirect_uri')).toBe('http://127.0.0.1:8080/callback');
+    expect(parsed.searchParams.get('state')).toBe('state123');
+  });
+
+  it('includes scopes when provided', () => {
+    const options = {...baseOptions, scopes: ['read', 'write']};
+    const url = buildAuthorizeUrl(options.authorizeUrl, options, 8080, 'state');
+    const parsed = new URL(url);
+
+    expect(parsed.searchParams.get('scope')).toBe('read write');
+  });
+
+  it('omits scope when empty', () => {
+    const url = buildAuthorizeUrl(baseOptions.authorizeUrl, baseOptions, 8080, 'state');
+    const parsed = new URL(url);
+
+    expect(parsed.searchParams.has('scope')).toBe(false);
+  });
+});
+
+describe('exchangeCodeForTokens', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- vitest spy type mismatch with globalThis.fetch overloads
+  let fetchSpy: any;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  it('exchanges code for tokens', async () => {
+    const tokenResponse = {access_token: 'at123', refresh_token: 'rt456', token_type: 'Bearer'};
+    fetchSpy.mockResolvedValue(new Response(JSON.stringify(tokenResponse), {status: 200}));
+
+    const tokens = await exchangeCodeForTokens(
+      'https://auth.example.com/token',
+      'authcode',
+      'http://127.0.0.1:9999/callback',
+      'client123',
+      'secret456',
+    );
+
+    expect(tokens['access_token']).toBe('at123');
+    expect(tokens['refresh_token']).toBe('rt456');
+
+    // Verify POST body
+    const [, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(init.method).toBe('POST');
+    const body = init.body as string;
+    expect(body).toContain('grant_type=authorization_code');
+    expect(body).toContain('code=authcode');
+    expect(body).toContain('client_secret=secret456');
+  });
+
+  it('throws on HTTP error', async () => {
+    fetchSpy.mockResolvedValue(new Response('Bad Request', {status: 400}));
+
+    await expect(
+      exchangeCodeForTokens('https://auth.example.com/token', 'bad', 'http://localhost/cb', 'c'),
+    ).rejects.toThrow(OAuth2Error);
+  });
+
+  it('throws on network error', async () => {
+    fetchSpy.mockRejectedValue(new Error('ECONNREFUSED'));
+
+    await expect(
+      exchangeCodeForTokens('https://auth.example.com/token', 'code', 'http://localhost/cb', 'c'),
+    ).rejects.toThrow('ECONNREFUSED');
+  });
+});
+
+describe('mapTokensToEnvVars', () => {
+  it('uses default mapping when no envVars', () => {
+    const tokens = {access_token: 'at', refresh_token: 'rt'};
+    const result = mapTokensToEnvVars(tokens);
+
+    expect(result).toEqual({
+      OAUTH_ACCESS_TOKEN: 'at',
+      OAUTH_REFRESH_TOKEN: 'rt',
+    });
+  });
+
+  it('uses custom mapping based on var name hints', () => {
+    const tokens = {access_token: 'at', refresh_token: 'rt'};
+    const result = mapTokensToEnvVars(tokens, {
+      MY_ACCESS: 'Access token',
+      MY_REFRESH: 'Refresh token',
+    });
+
+    expect(result).toEqual({
+      MY_ACCESS: 'at',
+      MY_REFRESH: 'rt',
+    });
+  });
+
+  it('defaults to access_token when var name has no hint', () => {
+    const tokens = {access_token: 'at'};
+    const result = mapTokensToEnvVars(tokens, {SOME_TOKEN: 'desc'});
+
+    expect(result).toEqual({SOME_TOKEN: 'at'});
+  });
+
+  it('handles missing tokens gracefully', () => {
+    const tokens = {};
+    const result = mapTokensToEnvVars(tokens, {ACCESS: 'desc'});
+
+    expect(result).toEqual({});
+  });
+});
+
+describe('runOAuth2Flow', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- vitest spy type mismatch with globalThis.fetch overloads
+  let fetchSpy: any;
+  const stderrSpy = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    fetchSpy = vi.spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  it('completes the full flow', async () => {
+    const tokenResponse = {access_token: 'tok123', refresh_token: 'ref456'};
+
+    // Mock open to simulate browser callback
+    mockOpen.mockImplementation(async (url: string) => {
+      const parsed = new URL(url);
+      const state = parsed.searchParams.get('state');
+      const redirectUri = parsed.searchParams.get('redirect_uri')!;
+      // Hit the callback
+      await fetch(`${redirectUri}?code=authcode&state=${state}`);
+    });
+
+    // Mock token exchange
+    fetchSpy.mockImplementation(async (input: string | URL | Request) => {
+      const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+      if (url.includes('/callback')) {
+        // This is the real callback to our server, let it through
+        return fetch(input);
+      }
+      // Token exchange
+      return new Response(JSON.stringify(tokenResponse), {status: 200});
+    });
+
+    // Can't easily test the full flow with mocked fetch intercepting all calls.
+    // Instead test the helper functions above. This test verifies error paths.
+  });
+
+  it('falls back to printing URL when browser fails', async () => {
+    mockOpen.mockRejectedValue(new Error('No browser'));
+
+    // Start the flow but let it timeout quickly
+    const options: OAuth2Options = {
+      authorizeUrl: 'https://auth.example.com/authorize',
+      tokenUrl: 'https://auth.example.com/token',
+      clientId: 'client123',
+      timeoutMs: 100,
+    };
+
+    await expect(runOAuth2Flow(options)).rejects.toThrow('timed out');
+    expect(stderrSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Open this URL'),
+    );
+  });
+
+  it('throws on timeout', async () => {
+    mockOpen.mockResolvedValue(undefined);
+
+    const options: OAuth2Options = {
+      authorizeUrl: 'https://auth.example.com/authorize',
+      tokenUrl: 'https://auth.example.com/token',
+      clientId: 'client123',
+      timeoutMs: 100,
+    };
+
+    await expect(runOAuth2Flow(options)).rejects.toThrow(OAuth2Error);
+  });
+
+  it('cleans up server on error', async () => {
+    mockOpen.mockResolvedValue(undefined);
+
+    const options: OAuth2Options = {
+      authorizeUrl: 'https://auth.example.com/authorize',
+      tokenUrl: 'https://auth.example.com/token',
+      clientId: 'client123',
+      timeoutMs: 50,
+    };
+
+    try {
+      await runOAuth2Flow(options);
+    } catch {
+      // Expected
+    }
+
+    // Server should be closed — no dangling listeners
+  });
+});
+
+describe('OAuth2Error', () => {
+  it('has correct name and code', () => {
+    const err = new OAuth2Error('TIMEOUT', 'timed out');
+    expect(err.name).toBe('OAuth2Error');
+    expect(err.code).toBe('TIMEOUT');
+    expect(err.message).toBe('timed out');
+  });
+
+  it('preserves cause', () => {
+    const cause = new Error('original');
+    const err = new OAuth2Error('SERVER_FAILED', 'failed', cause);
+    expect(err.cause).toBe(cause);
+  });
+});

package/src/auth/oauth2.ts

@@ -0,0 +1,269 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {createServer} from 'node:http';
+import type {Server} from 'node:http';
+import {randomUUID} from 'node:crypto';
+import {URL, URLSearchParams} from 'node:url';
+import open from 'open';
+
+import type {AuthResult} from './types.js';
+
+export type OAuth2ErrorCode =
+  | 'SERVER_FAILED'
+  | 'BROWSER_FAILED'
+  | 'TIMEOUT'
+  | 'TOKEN_EXCHANGE_FAILED'
+  | 'CALLBACK_ERROR'
+  | 'STATE_MISMATCH';
+
+export class OAuth2Error extends Error {
+  readonly code: OAuth2ErrorCode;
+
+  constructor(code: OAuth2ErrorCode, message: string, cause?: unknown) {
+    super(message, {cause});
+    this.name = 'OAuth2Error';
+    this.code = code;
+  }
+}
+
+export interface OAuth2Options {
+  authorizeUrl: string;
+  tokenUrl: string;
+  scopes?: string[];
+  envVars?: Record<string, string>;
+  clientId: string;
+  clientSecret?: string;
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+interface CallbackServerResult {
+  server: Server;
+  port: number;
+  codePromise: Promise<{code: string; state: string}>;
+}
+
+/**
+ * Start a local HTTP server that listens for the OAuth2 callback.
+ */
+export function startCallbackServer(): Promise<CallbackServerResult> {
+  return new Promise((resolve, reject) => {
+    let resolveCode: (value: {code: string; state: string}) => void;
+    let rejectCode: (reason: Error) => void;
+    const codePromise = new Promise<{code: string; state: string}>((res, rej) => {
+      resolveCode = res;
+      rejectCode = rej;
+    });
+
+    const server = createServer((req, res) => {
+      try {
+        const url = new URL(req.url ?? '/', `http://localhost`);
+        if (url.pathname !== '/callback') {
+          res.writeHead(404);
+          res.end('Not found');
+          return;
+        }
+
+        const code = url.searchParams.get('code');
+        const state = url.searchParams.get('state');
+        const error = url.searchParams.get('error');
+
+        if (error) {
+          const description = url.searchParams.get('error_description') ?? error;
+          res.writeHead(200, {'Content-Type': 'text/html'});
+          res.end('<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>');
+          rejectCode(new OAuth2Error('CALLBACK_ERROR', `OAuth2 error: ${description}`));
+          return;
+        }
+
+        if (!code || !state) {
+          res.writeHead(400, {'Content-Type': 'text/html'});
+          res.end('<html><body><h1>Missing Parameters</h1></body></html>');
+          rejectCode(new OAuth2Error('CALLBACK_ERROR', 'Missing code or state parameter'));
+          return;
+        }
+
+        res.writeHead(200, {'Content-Type': 'text/html'});
+        res.end('<html><body><h1>Authorization Complete</h1><p>You can close this window.</p></body></html>');
+        resolveCode({code, state});
+      } catch (err) {
+        res.writeHead(500);
+        res.end('Internal error');
+        rejectCode(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address();
+      if (!addr || typeof addr === 'string') {
+        server.close();
+        reject(new OAuth2Error('SERVER_FAILED', 'Failed to get server port'));
+        return;
+      }
+      resolve({server, port: addr.port, codePromise});
+    });
+
+    server.on('error', (err) => {
+      reject(new OAuth2Error('SERVER_FAILED', 'Failed to start callback server', err));
+    });
+  });
+}
+
+/**
+ * Build the OAuth2 authorize URL.
+ */
+export function buildAuthorizeUrl(
+  baseUrl: string,
+  options: OAuth2Options,
+  port: number,
+  state: string,
+): string {
+  const url = new URL(baseUrl);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', options.clientId);
+  url.searchParams.set('redirect_uri', `http://127.0.0.1:${port}/callback`);
+  url.searchParams.set('state', state);
+  if (options.scopes && options.scopes.length > 0) {
+    url.searchParams.set('scope', options.scopes.join(' '));
+  }
+  return url.toString();
+}
+
+/**
+ * Exchange authorization code for tokens.
+ */
+export async function exchangeCodeForTokens(
+  tokenUrl: string,
+  code: string,
+  redirectUri: string,
+  clientId: string,
+  clientSecret?: string,
+): Promise<Record<string, unknown>> {
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: redirectUri,
+    client_id: clientId,
+  });
+  if (clientSecret) {
+    body.set('client_secret', clientSecret);
+  }
+
+  const response = await fetch(tokenUrl, {
+    method: 'POST',
+    headers: {'Content-Type': 'application/x-www-form-urlencoded'},
+    body: body.toString(),
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => '');
+    throw new OAuth2Error(
+      'TOKEN_EXCHANGE_FAILED',
+      `Token exchange failed: HTTP ${response.status}${text ? ` — ${text}` : ''}`,
+    );
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return (await response.json()) as Record<string, unknown>;
+}
+
+/**
+ * Map token response fields to env var names.
+ */
+export function mapTokensToEnvVars(
+  tokens: Record<string, unknown>,
+  envVars?: Record<string, string>,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  if (envVars && Object.keys(envVars).length > 0) {
+    // envVars maps envVarName → description (for prompting)
+    // Token fields: access_token, refresh_token, etc.
+    // Convention: env var name hints at which token field
+    for (const envVarName of Object.keys(envVars)) {
+      const lower = envVarName.toLowerCase();
+      if (lower.includes('refresh') && typeof tokens['refresh_token'] === 'string') {
+        result[envVarName] = tokens['refresh_token'];
+      } else if (lower.includes('access') && typeof tokens['access_token'] === 'string') {
+        result[envVarName] = tokens['access_token'];
+      } else if (typeof tokens['access_token'] === 'string') {
+        // Default: map to access_token
+        result[envVarName] = tokens['access_token'];
+      }
+    }
+  } else {
+    // Default mapping
+    if (typeof tokens['access_token'] === 'string') {
+      result['OAUTH_ACCESS_TOKEN'] = tokens['access_token'];
+    }
+    if (typeof tokens['refresh_token'] === 'string') {
+      result['OAUTH_REFRESH_TOKEN'] = tokens['refresh_token'];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Run the full OAuth2 authorization code flow.
+ */
+export async function runOAuth2Flow(options: OAuth2Options): Promise<AuthResult> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let server: Server | undefined;
+
+  try {
+    const serverResult = await startCallbackServer();
+    server = serverResult.server;
+    const {port, codePromise} = serverResult;
+
+    const state = randomUUID();
+    const authorizeUrl = buildAuthorizeUrl(options.authorizeUrl, options, port, state);
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+    // Try to open browser, fall back to printing URL
+    try {
+      await open(authorizeUrl);
+    } catch {
+      process.stderr.write(`\nOpen this URL in your browser to authorize:\n${authorizeUrl}\n\n`);
+    }
+
+    // Wait for callback or timeout
+    const timeoutPromise = new Promise<never>((_resolve, reject) => {
+      setTimeout(() => {
+        reject(new OAuth2Error('TIMEOUT', `OAuth2 flow timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+
+    const callbackResult = await Promise.race([codePromise, timeoutPromise]);
+
+    // Verify state (CSRF protection)
+    if (callbackResult.state !== state) {
+      throw new OAuth2Error('STATE_MISMATCH', 'OAuth2 state parameter mismatch');
+    }
+
+    // Exchange code for tokens
+    const tokens = await exchangeCodeForTokens(
+      options.tokenUrl,
+      callbackResult.code,
+      redirectUri,
+      options.clientId,
+      options.clientSecret,
+    );
+
+    const credentials = mapTokensToEnvVars(tokens, options.envVars);
+
+    return {
+      credentials,
+      summary: `OAuth2 authorization complete. ${Object.keys(credentials).length} token${Object.keys(credentials).length === 1 ? '' : 's'} obtained`,
+    };
+  } finally {
+    if (server) {
+      server.close();
+    }
+  }
+}