@amodalai/amodal 0.1.2

package/src/auth/test-connection.ts

@@ -0,0 +1,196 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {readEnvFile} from '@amodalai/core';
+import type {PackageAuth} from '@amodalai/core';
+
+import type {ConnectionTestReport, EndpointTestResult} from './types.js';
+
+export interface TestConnectionOptions {
+  connectionName: string;
+  testEndpoints: string[];
+  envFilePath: string;
+  auth?: PackageAuth;
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * Substitute $VAR and ${VAR} placeholders in a URL.
+ */
+export function resolveEndpointUrl(
+  url: string,
+  envVars: Map<string, string>,
+): string {
+  return url.replace(/\$\{([A-Z_][A-Z0-9_]*)\}|\$([A-Z_][A-Z0-9_]*)/g, (_match, braced, bare) => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- regex capture groups are string|undefined
+    const varName = (braced ?? bare) as string;
+    return envVars.get(varName) ?? '';
+  });
+}
+
+/**
+ * Build auth headers based on auth config and env vars.
+ */
+export function buildAuthHeaders(
+  auth: PackageAuth | undefined,
+  envVars: Map<string, string>,
+): Record<string, string> {
+  if (!auth) return {};
+
+  switch (auth.type) {
+    case 'bearer': {
+      // Use first envVar value as the token
+      const envVarEntries = auth['envVars'] ?? {};
+      const firstKey = Object.keys(envVarEntries)[0];
+      if (firstKey) {
+        const token = envVars.get(firstKey) ?? '';
+        if (token) {
+          return {Authorization: `Bearer ${token}`};
+        }
+      }
+      return {};
+    }
+    case 'api_key': {
+      const headers: Record<string, string> = {};
+      const headerDefs = auth['headers'] ?? {};
+      for (const [headerName, template] of Object.entries(headerDefs)) {
+        headers[headerName] = template.replace(
+          /\$\{?([A-Z_][A-Z0-9_]*)\}?/g,
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- regex capture group
+          (_match, varName) => envVars.get(varName as string) ?? '',
+        );
+      }
+      return headers;
+    }
+    case 'oauth2': {
+      const envVarEntries = auth['envVars'] ?? {};
+      // Look for access_token mapping or use first entry
+      const tokenKey =
+        Object.entries(envVarEntries).find(([, desc]) =>
+          desc.toLowerCase().includes('access'),
+        )?.[0] ?? Object.keys(envVarEntries)[0];
+      if (tokenKey) {
+        const token = envVars.get(tokenKey) ?? '';
+        if (token) {
+          return {Authorization: `Bearer ${token}`};
+        }
+      }
+      return {};
+    }
+    default:
+      return {};
+  }
+}
+
+/**
+ * Test a single endpoint. Never throws.
+ */
+async function testSingleEndpoint(
+  url: string,
+  headers: Record<string, string>,
+  timeoutMs: number,
+): Promise<EndpointTestResult> {
+  const start = Date.now();
+  try {
+    const response = await fetch(url, {
+      method: 'GET',
+      headers,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+
+    const durationMs = Date.now() - start;
+
+    if (!response.ok) {
+      return {
+        url,
+        status: 'error',
+        statusCode: response.status,
+        error: `HTTP ${response.status}`,
+        durationMs,
+      };
+    }
+
+    // Best-effort record count extraction
+    let recordCount: number | undefined;
+    try {
+      const body: unknown = await response.json();
+      if (Array.isArray(body)) {
+        recordCount = body.length;
+      } else if (body && typeof body === 'object') {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- narrowed by typeof check above
+        const obj = body as Record<string, unknown>;
+        if (typeof obj['total'] === 'number') {
+          recordCount = obj['total'];
+        } else if (typeof obj['count'] === 'number') {
+          recordCount = obj['count'];
+        }
+      }
+    } catch {
+      // Not JSON — that's fine
+    }
+
+    return {
+      url,
+      status: 'ok',
+      statusCode: response.status,
+      recordCount,
+      durationMs,
+    };
+  } catch (err) {
+    const durationMs = Date.now() - start;
+    const message =
+      err instanceof Error ? err.message : 'Unknown error';
+    return {
+      url,
+      status: 'error',
+      error: message,
+      durationMs,
+    };
+  }
+}
+
+/**
+ * Test connection endpoints sequentially. Never throws.
+ */
+export async function testConnection(
+  options: TestConnectionOptions,
+): Promise<ConnectionTestReport> {
+  const {
+    connectionName,
+    testEndpoints,
+    envFilePath,
+    auth,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+  } = options;
+
+  const envVars = await readEnvFile(envFilePath);
+  const headers = buildAuthHeaders(auth, envVars);
+  const results: EndpointTestResult[] = [];
+
+  for (const endpoint of testEndpoints) {
+    const url = resolveEndpointUrl(endpoint, envVars);
+    process.stderr.write(`  Testing ${url} ... `);
+    const result = await testSingleEndpoint(url, headers, timeoutMs);
+    if (result.status === 'ok') {
+      const countInfo =
+        result.recordCount !== undefined
+          ? ` (${result.recordCount} records)`
+          : '';
+      process.stderr.write(`OK ${result.statusCode}${countInfo} [${result.durationMs}ms]\n`);
+    } else {
+      process.stderr.write(`FAILED ${result.error ?? 'unknown'} [${result.durationMs}ms]\n`);
+    }
+    results.push(result);
+  }
+
+  return {
+    connectionName,
+    results,
+    allPassed: results.every((r) => r.status === 'ok'),
+  };
+}

package/src/auth/types.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Result returned by oauth2 and credential prompt flows.
+ */
+export interface AuthResult {
+  credentials: Record<string, string>;
+  summary: string;
+}
+
+/**
+ * Per-endpoint test result.
+ */
+export interface EndpointTestResult {
+  url: string;
+  status: 'ok' | 'error';
+  statusCode?: number;
+  recordCount?: number;
+  error?: string;
+  durationMs: number;
+}
+
+/**
+ * Aggregated connection test report.
+ */
+export interface ConnectionTestReport {
+  connectionName: string;
+  results: EndpointTestResult[];
+  allPassed: boolean;
+}

package/src/commands/audit.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+
+describe('runAudit', () => {
+  let fetchSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    fetchSpy = vi.fn();
+    vi.stubGlobal('fetch', fetchSpy);
+  });
+
+  it('outputs JSON format', async () => {
+    fetchSpy.mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        sessionId: 'sess-1',
+        events: [
+          {id: 'e1', eventType: 'tool_call', data: {}, tokenCount: 10, durationMs: 50, createdAt: '2026-03-15T10:00:00Z'},
+        ],
+      }),
+    });
+
+    const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+
+    const {runAudit} = await import('./audit.js');
+    await runAudit({
+      sessionId: 'sess-1',
+      format: 'json',
+      platformUrl: 'http://localhost:4000',
+      platformApiKey: 'key-123',
+    });
+
+    expect(fetchSpy).toHaveBeenCalledOnce();
+    const output = stdoutSpy.mock.calls.map(([s]) => s).join('');
+    expect(output).toContain('"sessionId"');
+    stdoutSpy.mockRestore();
+  });
+
+  it('outputs table format by default', async () => {
+    fetchSpy.mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        sessionId: 'sess-1',
+        events: [
+          {id: 'e1', eventType: 'tool_call', data: {}, tokenCount: null, durationMs: 50, createdAt: '2026-03-15T10:00:00Z'},
+          {id: 'e2', eventType: 'session_end', data: {}, tokenCount: null, durationMs: null, createdAt: '2026-03-15T10:01:00Z'},
+        ],
+      }),
+    });
+
+    const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+
+    const {runAudit} = await import('./audit.js');
+    await runAudit({
+      sessionId: 'sess-1',
+      platformUrl: 'http://localhost:4000',
+      platformApiKey: 'key-123',
+    });
+
+    const output = stdoutSpy.mock.calls.map(([s]) => s).join('');
+    expect(output).toContain('tool_call');
+    expect(output).toContain('session_end');
+    expect(output).toContain('Total: 2 events');
+    stdoutSpy.mockRestore();
+  });
+
+  it('handles empty events', async () => {
+    fetchSpy.mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({sessionId: 'sess-1', events: []}),
+    });
+
+    const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+
+    const {runAudit} = await import('./audit.js');
+    await runAudit({
+      sessionId: 'sess-1',
+      platformUrl: 'http://localhost:4000',
+      platformApiKey: 'key-123',
+    });
+
+    const output = stdoutSpy.mock.calls.map(([s]) => s).join('');
+    expect(output).toContain('No audit events found');
+    stdoutSpy.mockRestore();
+  });
+});

package/src/commands/audit.ts

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import type {CommandModule} from 'yargs';
+import {resolvePlatformConfig} from '../shared/platform-client.js';
+
+export interface AuditOptions {
+  sessionId: string;
+  format?: 'json' | 'table';
+  platformUrl?: string;
+  platformApiKey?: string;
+}
+
+/**
+ * Retrieve audit trail for a session from the platform.
+ */
+export async function runAudit(options: AuditOptions): Promise<void> {
+  let platformUrl: string;
+  let apiKey: string;
+  try {
+    const config = await resolvePlatformConfig({
+      url: options.platformUrl,
+      apiKey: options.platformApiKey,
+    });
+    platformUrl = config.url;
+    apiKey = config.apiKey;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[audit] ${msg}\n`);
+    process.exit(1);
+  }
+
+  try {
+    const response = await fetch(`${platformUrl}/api/audit/sessions/${options.sessionId}`, {
+      headers: {'Authorization': `Bearer ${apiKey}`},
+    });
+
+    if (!response.ok) {
+      process.stderr.write(`[audit] HTTP ${response.status}: ${await response.text()}\n`);
+      process.exit(1);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- platform response
+    const data = await response.json() as {
+      sessionId: string;
+      events: Array<{
+        id: string;
+        eventType: string;
+        data: Record<string, unknown>;
+        tokenCount: number | null;
+        durationMs: number | null;
+        createdAt: string;
+      }>;
+    };
+
+    if (options.format === 'json') {
+      process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+      return;
+    }
+
+    // Table format
+    const events = data.events;
+    if (events.length === 0) {
+      process.stdout.write('No audit events found for this session.\n');
+      return;
+    }
+
+    const typeWidth = Math.max(10, ...events.map((e) => e.eventType.length));
+    process.stdout.write(`\nSession: ${data.sessionId}\n`);
+    process.stdout.write(`${'Type'.padEnd(typeWidth)}  ${'Time'.padEnd(24)}  Details\n`);
+    process.stdout.write('-'.repeat(typeWidth + 50) + '\n');
+
+    for (const event of events) {
+      const time = event.createdAt.slice(0, 24);
+      const details = event.durationMs ? `${event.durationMs}ms` : '';
+      process.stdout.write(`${event.eventType.padEnd(typeWidth)}  ${time.padEnd(24)}  ${details}\n`);
+    }
+
+    process.stdout.write(`\nTotal: ${events.length} events\n`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[audit] Error: ${msg}\n`);
+    process.exit(1);
+  }
+}
+
+export const auditCommand: CommandModule = {
+  command: 'audit <session-id>',
+  describe: 'View audit trail for a session',
+  builder: (yargs) =>
+    yargs
+      .positional('session-id', {
+        type: 'string',
+        demandOption: true,
+        describe: 'The session ID to retrieve audit events for',
+      })
+      .option('format', {
+        type: 'string',
+        choices: ['json', 'table'] as const,
+        default: 'table',
+        describe: 'Output format',
+      }),
+  handler: async (argv) => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    const sessionId = argv['sessionId'] as string;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    const format = argv['format'] as 'json' | 'table';
+    await runAudit({sessionId, format});
+  },
+};

package/src/commands/automations.test.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {runAutomationsList, runAutomationsStart, runAutomationsStop, runAutomationsRun} from './automations.js';
+
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? 'OK' : 'Error',
+    json: () => Promise.resolve(body),
+  } as unknown as Response;
+}
+
+describe('automations CLI', () => {
+  beforeEach(() => {
+    mockFetch.mockReset();
+  });
+
+  describe('list', () => {
+    it('should list automations from server', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({
+        automations: [
+          {name: 'monitor', title: 'Zone Monitor', schedule: '*/5 * * * *', webhookTriggered: false, running: true},
+          {name: 'alerts', title: 'Alert Handler', webhookTriggered: true, running: true},
+        ],
+      }));
+
+      const code = await runAutomationsList({url: 'http://test:3847'});
+      expect(code).toBe(0);
+      expect(mockFetch).toHaveBeenCalledWith('http://test:3847/automations', {method: 'GET'});
+    });
+
+    it('should return 1 on error', async () => {
+      mockFetch.mockRejectedValue(new Error('Connection refused'));
+
+      const code = await runAutomationsList();
+      expect(code).toBe(1);
+    });
+  });
+
+  describe('start', () => {
+    it('should start an automation', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({status: 'started', automation: 'monitor'}));
+
+      const code = await runAutomationsStart('monitor', {url: 'http://test:3847'});
+      expect(code).toBe(0);
+      expect(mockFetch).toHaveBeenCalledWith('http://test:3847/automations/monitor/start', {method: 'POST'});
+    });
+
+    it('should return 1 on error', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({error: 'Already running'}, 400));
+
+      const code = await runAutomationsStart('monitor');
+      expect(code).toBe(1);
+    });
+  });
+
+  describe('stop', () => {
+    it('should stop an automation', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({status: 'stopped', automation: 'monitor'}));
+
+      const code = await runAutomationsStop('monitor', {url: 'http://test:3847'});
+      expect(code).toBe(0);
+      expect(mockFetch).toHaveBeenCalledWith('http://test:3847/automations/monitor/stop', {method: 'POST'});
+    });
+  });
+
+  describe('run', () => {
+    it('should trigger an automation', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({status: 'triggered', automation: 'monitor'}));
+
+      const code = await runAutomationsRun('monitor', {url: 'http://test:3847'});
+      expect(code).toBe(0);
+      expect(mockFetch).toHaveBeenCalledWith('http://test:3847/automations/monitor/run', {method: 'POST'});
+    });
+  });
+});