coaiajs 0.1.0

package/src/config.ts

@@ -0,0 +1,172 @@
+// coaiajs/src/config.ts — Config management
+// Priority: env vars > .env > coaia.json > defaults
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { homedir } from 'node:os';
+import dotenv from 'dotenv';
+import type { CoaiaConfig } from './types.js';
+
+const CONFIG_FILENAMES = ['coaia.json', '.coaia/config.json'];
+
+/** Search for an existing coaia.json config file. */
+export function findExistingConfig(): string | null {
+  const searchDirs = [process.cwd(), homedir()];
+
+  for (const dir of searchDirs) {
+    for (const filename of CONFIG_FILENAMES) {
+      const candidate = join(dir, filename);
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return null;
+}
+
+/** Deep-merge two config objects; override wins on conflicts. */
+export function mergeConfigs(
+  base: Partial<CoaiaConfig>,
+  override: Partial<CoaiaConfig>,
+): CoaiaConfig {
+  const result: Record<string, unknown> = { ...base };
+
+  for (const [key, val] of Object.entries(override)) {
+    if (
+      val !== null &&
+      val !== undefined &&
+      typeof val === 'object' &&
+      !Array.isArray(val) &&
+      typeof result[key] === 'object' &&
+      result[key] !== null &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = mergeConfigs(
+        result[key] as Partial<CoaiaConfig>,
+        val as Partial<CoaiaConfig>,
+      );
+    } else if (val !== undefined) {
+      result[key] = val;
+    }
+  }
+  return result as CoaiaConfig;
+}
+
+function loadJsonConfig(filePath: string): Partial<CoaiaConfig> {
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    return JSON.parse(raw) as Partial<CoaiaConfig>;
+  } catch {
+    return {};
+  }
+}
+
+function envOverrides(): Partial<CoaiaConfig> {
+  const cfg: Partial<CoaiaConfig> = {};
+  const env = process.env;
+
+  // Redis
+  if (env['REDIS_URL'] || env['REDIS_HOST'] || env['UPSTASH_REDIS_REST_URL']) {
+    cfg.redis = {
+      url: env['REDIS_URL'],
+      host: env['REDIS_HOST'],
+      port: env['REDIS_PORT'] ? parseInt(env['REDIS_PORT'], 10) : undefined,
+      password: env['REDIS_PASSWORD'],
+      upstashUrl: env['UPSTASH_REDIS_REST_URL'],
+      upstashToken: env['UPSTASH_REDIS_REST_TOKEN'],
+    };
+  }
+
+  // Langfuse
+  if (env['LANGFUSE_PUBLIC_KEY'] || env['LANGFUSE_SECRET_KEY']) {
+    cfg.langfuse = {
+      publicKey: env['LANGFUSE_PUBLIC_KEY'],
+      secretKey: env['LANGFUSE_SECRET_KEY'],
+      baseUrl: env['LANGFUSE_BASE_URL'] ?? env['LANGFUSE_HOST'],
+    };
+  }
+
+  // OpenAI
+  if (env['OPENAI_API_KEY']) {
+    cfg.openai = {
+      apiKey: env['OPENAI_API_KEY'],
+      model: env['OPENAI_MODEL'] ?? env['LLM_MODEL'],
+    };
+  }
+
+  // AWS
+  if (env['AWS_ACCESS_KEY_ID']) {
+    cfg.aws = {
+      accessKeyId: env['AWS_ACCESS_KEY_ID'],
+      secretAccessKey: env['AWS_SECRET_ACCESS_KEY'],
+      region: env['AWS_REGION'] ?? env['AWS_DEFAULT_REGION'],
+    };
+  }
+
+  // GitHub
+  if (env['GITHUB_TOKEN'] || env['GH_TOKEN']) {
+    cfg.github = {
+      token: env['GITHUB_TOKEN'] ?? env['GH_TOKEN'],
+    };
+  }
+
+  return cfg;
+}
+
+/**
+ * Read and assemble the full CoaiaConfig.
+ * Priority: env vars > .env file > coaia.json > defaults.
+ */
+export function readConfig(envPath?: string): CoaiaConfig {
+  // 1. Load .env (lowest priority file source)
+  const dotenvPath = envPath ?? resolve(process.cwd(), '.env');
+  if (existsSync(dotenvPath)) {
+    dotenv.config({ path: dotenvPath });
+  } else {
+    dotenv.config(); // default search
+  }
+
+  // 2. Load coaia.json
+  const configPath = findExistingConfig();
+  const jsonConfig = configPath ? loadJsonConfig(configPath) : {};
+
+  // 3. Env var overrides (highest priority)
+  const envCfg = envOverrides();
+
+  // 4. Merge: json < env
+  return mergeConfigs(jsonConfig, envCfg);
+}
+
+/** Singleton config instance, lazily loaded on first access. */
+let _config: CoaiaConfig | null = null;
+
+export function getConfig(): CoaiaConfig {
+  if (!_config) {
+    _config = readConfig();
+  }
+  return _config;
+}
+
+/** Reset singleton (useful in tests). */
+export function resetConfig(): void {
+  _config = null;
+}
+
+export const config = new Proxy({} as CoaiaConfig, {
+  get(_target, prop: string) {
+    return getConfig()[prop];
+  },
+  ownKeys() {
+    return Object.keys(getConfig());
+  },
+  getOwnPropertyDescriptor(_target, prop: string) {
+    const cfg = getConfig();
+    if (prop in cfg) {
+      return { configurable: true, enumerable: true, value: cfg[prop] };
+    }
+    return undefined;
+  },
+  has(_target, prop: string) {
+    return prop in getConfig();
+  },
+});

package/src/environment.ts

@@ -0,0 +1,171 @@
+// coaiajs/src/environment.ts — Environment management
+// Parity with coaiapy's environment.py
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const ENV_FILENAME = '.coaia-env';
+
+/** Well-known CoAIA environment variable names. */
+const KNOWN_VARS = [
+  'COAIA_TRACE_ID',
+  'COAIA_SESSION_ID',
+  'COAIA_USER_ID',
+  'COAIA_PROJECT_ID',
+  'COAIA_ENV',
+  'COAIA_LOG_LEVEL',
+  'COAIA_CONFIG_PATH',
+  'COAIA_REDIS_URL',
+  'COAIA_PDE_DIR',
+] as const;
+
+export type KnownVar = (typeof KNOWN_VARS)[number];
+
+export interface EnvStore {
+  [key: string]: string;
+}
+
+export class EnvironmentManager {
+  private store: EnvStore = {};
+  private filePath: string;
+
+  constructor(dir?: string) {
+    const baseDir = dir ?? process.cwd();
+    this.filePath = resolve(baseDir, ENV_FILENAME);
+  }
+
+  /** Initialize environment — load from file if it exists. */
+  init(): void {
+    if (existsSync(this.filePath)) {
+      this.load();
+    }
+  }
+
+  /** List all environment variables in the store. */
+  list(): EnvStore {
+    return { ...this.store };
+  }
+
+  /** Get a single variable value. */
+  get(key: string): string | undefined {
+    // Check store first, fall back to process.env
+    return this.store[key] ?? process.env[key];
+  }
+
+  /** Set an environment variable (in-memory + process.env). */
+  set(key: string, value: string): void {
+    this.store[key] = value;
+    process.env[key] = value;
+  }
+
+  /** Remove a variable from the store and process.env. */
+  unset(key: string): void {
+    delete this.store[key];
+    delete process.env[key];
+  }
+
+  /** Clear all stored variables. */
+  clear(): void {
+    for (const key of Object.keys(this.store)) {
+      delete process.env[key];
+    }
+    this.store = {};
+  }
+
+  /**
+   * Source variables into process.env (like `source .env`).
+   * Applies all stored vars to process.env.
+   */
+  source(): void {
+    for (const [key, value] of Object.entries(this.store)) {
+      process.env[key] = value;
+    }
+  }
+
+  /** Save the current store to .coaia-env (JSON format). */
+  save(): void {
+    writeFileSync(this.filePath, JSON.stringify(this.store, null, 2), 'utf-8');
+  }
+
+  /** Save as .env format. */
+  saveAsEnv(outPath?: string): void {
+    const target = outPath ?? this.filePath.replace(/\.coaia-env$/, '.coaia.env');
+    const lines = Object.entries(this.store)
+      .map(([k, v]) => `${k}=${v}`)
+      .join('\n');
+    writeFileSync(target, lines + '\n', 'utf-8');
+  }
+
+  /** Load from .coaia-env file. Supports JSON and .env formats. */
+  private load(): void {
+    const raw = readFileSync(this.filePath, 'utf-8').trim();
+
+    // Try JSON first
+    if (raw.startsWith('{')) {
+      try {
+        this.store = JSON.parse(raw) as EnvStore;
+        return;
+      } catch {
+        // Fall through to .env parsing
+      }
+    }
+
+    // Parse .env format: KEY=VALUE lines
+    this.store = {};
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eqIdx = trimmed.indexOf('=');
+      if (eqIdx === -1) continue;
+      const key = trimmed.slice(0, eqIdx).trim();
+      let value = trimmed.slice(eqIdx + 1).trim();
+      // Strip surrounding quotes
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+      this.store[key] = value;
+    }
+  }
+
+  /** Get the file path being used. */
+  getFilePath(): string {
+    return this.filePath;
+  }
+
+  /** Get well-known CoAIA variables that are currently set. */
+  getKnownVars(): Partial<Record<KnownVar, string>> {
+    const result: Partial<Record<KnownVar, string>> = {};
+    for (const key of KNOWN_VARS) {
+      const val = this.get(key);
+      if (val !== undefined) {
+        result[key] = val;
+      }
+    }
+    return result;
+  }
+}
+
+/** Create a default EnvironmentManager for the current directory. */
+export function createEnvironment(dir?: string): EnvironmentManager {
+  const mgr = new EnvironmentManager(dir);
+  mgr.init();
+  return mgr;
+}
+
+/** Find and load environment from cwd or home. */
+export function findEnvironment(): EnvironmentManager {
+  const cwdPath = resolve(process.cwd(), ENV_FILENAME);
+  if (existsSync(cwdPath)) {
+    return createEnvironment(process.cwd());
+  }
+  const homePath = join(homedir(), ENV_FILENAME);
+  if (existsSync(homePath)) {
+    return createEnvironment(homedir());
+  }
+  // Return empty manager for cwd
+  return new EnvironmentManager(process.cwd());
+}

package/src/github.ts

@@ -0,0 +1,143 @@
+// coaiajs/src/github.ts — GitHub module
+// Parity with coaiapy's cogh.py using @octokit/rest
+
+import { Octokit } from '@octokit/rest';
+import { getConfig } from './config.js';
+
+let _client: Octokit | null = null;
+
+function getOctokit(): Octokit {
+  if (!_client) {
+    const cfg = getConfig();
+    _client = new Octokit({
+      auth: cfg.github?.token ?? process.env['GITHUB_TOKEN'] ?? process.env['GH_TOKEN'],
+    });
+  }
+  return _client;
+}
+
+/** Reset client (testing). */
+export function resetClient(): void {
+  _client = null;
+}
+
+export interface Issue {
+  number: number;
+  title: string;
+  state: string;
+  body: string | null;
+  labels: Array<{ name: string }>;
+  assignees: Array<{ login: string }>;
+  created_at: string;
+  updated_at: string;
+  html_url: string;
+  user: { login: string } | null;
+}
+
+export interface IssueComment {
+  id: number;
+  body: string;
+  user: { login: string } | null;
+  created_at: string;
+}
+
+/**
+ * List issues for a repository.
+ * Parity with coaiapy's cogh list_issues.
+ */
+export async function listIssues(
+  owner: string,
+  repo: string,
+  options?: {
+    state?: 'open' | 'closed' | 'all';
+    labels?: string;
+    per_page?: number;
+    page?: number;
+  },
+): Promise<Issue[]> {
+  const client = getOctokit();
+
+  const response = await client.issues.listForRepo({
+    owner,
+    repo,
+    state: options?.state ?? 'open',
+    labels: options?.labels,
+    per_page: options?.per_page ?? 30,
+    page: options?.page ?? 1,
+  });
+
+  return response.data.map(mapIssue);
+}
+
+/**
+ * Get a single issue by number.
+ */
+export async function getIssue(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+): Promise<Issue> {
+  const client = getOctokit();
+
+  const response = await client.issues.get({
+    owner,
+    repo,
+    issue_number: issueNumber,
+  });
+
+  return mapIssue(response.data);
+}
+
+/**
+ * Get comments for an issue.
+ */
+export async function getIssueComments(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+): Promise<IssueComment[]> {
+  const client = getOctokit();
+
+  const response = await client.issues.listComments({
+    owner,
+    repo,
+    issue_number: issueNumber,
+  });
+
+  return response.data.map((c) => ({
+    id: c.id,
+    body: c.body ?? '',
+    user: c.user ? { login: c.user.login } : null,
+    created_at: c.created_at,
+  }));
+}
+
+function mapIssue(data: Record<string, unknown>): Issue {
+  const d = data as {
+    number: number;
+    title: string;
+    state: string;
+    body: string | null;
+    labels: Array<{ name?: string } | string>;
+    assignees: Array<{ login: string }> | null;
+    created_at: string;
+    updated_at: string;
+    html_url: string;
+    user: { login: string } | null;
+  };
+
+  return {
+    number: d.number,
+    title: d.title,
+    state: d.state,
+    body: d.body,
+    labels: (d.labels ?? []).map((l) =>
+      typeof l === 'string' ? { name: l } : { name: l.name ?? '' },
+    ),
+    assignees: (d.assignees ?? []).map((a) => ({ login: a.login })),
+    created_at: d.created_at,
+    updated_at: d.updated_at,
+    html_url: d.html_url,
+    user: d.user ? { login: d.user.login } : null,
+  };
+}

package/src/langfuse/client.ts

@@ -0,0 +1,105 @@
+// coaiajs/src/langfuse/client.ts — Langfuse REST client
+// Parity with cofuse.py's direct REST approach (no SDK dependency for API calls)
+
+import { getConfig } from '../config.js';
+
+export interface IngestionEvent {
+  id: string;
+  timestamp: string;
+  type: 'trace-create' | 'observation-create' | 'score-create' | 'sdk-log';
+  body: Record<string, unknown>;
+}
+
+export interface LangfuseClientConfig {
+  publicKey?: string;
+  secretKey?: string;
+  baseUrl?: string;
+}
+
+export class LangfuseClient {
+  private publicKey: string;
+  private secretKey: string;
+  private baseUrl: string;
+
+  constructor(config?: LangfuseClientConfig) {
+    const appConfig = getConfig();
+    this.publicKey = config?.publicKey ?? appConfig.langfuse?.publicKey ?? '';
+    this.secretKey = config?.secretKey ?? appConfig.langfuse?.secretKey ?? '';
+    this.baseUrl = (config?.baseUrl ?? appConfig.langfuse?.baseUrl ?? 'https://cloud.langfuse.com').replace(/\/+$/, '');
+  }
+
+  private getAuthHeader(): string {
+    const credentials = Buffer.from(`${this.publicKey}:${this.secretKey}`).toString('base64');
+    return `Basic ${credentials}`;
+  }
+
+  async request<T = unknown>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      'Authorization': this.getAuthHeader(),
+      'Content-Type': 'application/json',
+    };
+
+    const init: RequestInit = { method, headers };
+    if (body !== undefined) {
+      init.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, init);
+    const text = await response.text();
+
+    if (!response.ok) {
+      let detail: string;
+      try {
+        detail = JSON.stringify(JSON.parse(text), null, 2);
+      } catch {
+        detail = text;
+      }
+      throw new LangfuseApiError(
+        `Langfuse API error ${response.status}: ${detail}`,
+        response.status,
+        detail,
+      );
+    }
+
+    if (!text) return undefined as T;
+    return JSON.parse(text) as T;
+  }
+
+  async ingest(events: IngestionEvent[]): Promise<void> {
+    await this.request('POST', '/api/public/ingestion', { batch: events });
+  }
+
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+}
+
+export class LangfuseApiError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number,
+    public readonly detail: string,
+  ) {
+    super(message);
+    this.name = 'LangfuseApiError';
+  }
+}
+
+// Singleton with lazy init
+let _client: LangfuseClient | null = null;
+
+export function getClient(config?: LangfuseClientConfig): LangfuseClient {
+  if (!_client) {
+    _client = new LangfuseClient(config);
+  }
+  return _client;
+}
+
+export function resetClient(): void {
+  _client = null;
+}
+
+export function nowISO(): string {
+  return new Date().toISOString();
+}

package/src/langfuse/comments.ts

@@ -0,0 +1,52 @@
+// coaiajs/src/langfuse/comments.ts — Comment operations
+// Port of cofuse.py comment functions
+
+import { getClient } from './client.js';
+
+export interface CommentFilters {
+  objectType?: string;
+  objectId?: string;
+  authorUserId?: string;
+  page?: number;
+  limit?: number;
+}
+
+export async function listComments(filters: CommentFilters): Promise<string> {
+  const client = getClient();
+  const params = new URLSearchParams();
+
+  if (filters.objectType) params.set('objectType', filters.objectType);
+  if (filters.objectId) params.set('objectId', filters.objectId);
+  if (filters.authorUserId) params.set('authorUserId', filters.authorUserId);
+  params.set('page', String(filters.page ?? 1));
+  params.set('limit', String(filters.limit ?? 50));
+
+  const qs = params.toString();
+  const result = await client.request<unknown>('GET', `/api/public/comments?${qs}`);
+  return JSON.stringify(result, null, 2);
+}
+
+export async function getComment(commentId: string): Promise<string> {
+  const client = getClient();
+  const result = await client.request<unknown>('GET', `/api/public/comments/${commentId}`);
+  return JSON.stringify(result, null, 2);
+}
+
+export async function createComment(params: {
+  text: string;
+  objectType: string;
+  objectId: string;
+  authorUserId?: string;
+}): Promise<string> {
+  const client = getClient();
+  const data: Record<string, unknown> = {
+    content: params.text,
+    objectType: params.objectType,
+    objectId: params.objectId,
+  };
+
+  if (params.authorUserId) data.authorUserId = params.authorUserId;
+
+  const result = await client.request<unknown>('POST', '/api/public/comments', data);
+  return JSON.stringify(result, null, 2);
+}