work-ally 0.2.0-alpha.1

package/bridge/src/handoff-service.ts

@@ -0,0 +1,494 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { WorkAllyConfig } from './config.ts';
+import type { WorkSessionCliResumeRefType, WorkSessionMeta } from './types.ts';
+import { nowIso } from './utils.ts';
+import { WorkSessionStore } from './work-session-store.ts';
+
+export type HandoffExportStatus = 'ready' | 'not_ready' | 'not_found';
+export type HandoffExportReason = 'active_work_session_missing' | 'cli_resume_ref_missing';
+export type AttachStatus = 'attached' | 'error';
+export type AttachReason =
+  | 'assistant_codex_home_missing'
+  | 'attach_selector_required'
+  | 'attach_selector_conflict'
+  | 'candidate_not_found'
+  | 'candidate_ambiguous'
+  | 'workspace_mismatch';
+
+export interface HandoffExportPayload {
+  status: HandoffExportStatus;
+  reason?: HandoffExportReason;
+  assistantName: string;
+  workspaceRoot: string;
+  assistantCodexHome: string | null;
+  workSessionId: string | null;
+  runtimeThreadId: string | null;
+  cliResumeRef: string | null;
+  cliResumeRefType: WorkSessionCliResumeRefType;
+  threadName: string | null;
+  activeSurface: WorkSessionMeta['activeSurface'] | null;
+  ownershipSource: WorkSessionMeta['ownershipSource'] | null;
+  resumeCapability: WorkSessionMeta['resumeCapability'] | 'not_ready';
+  command: string | null;
+  exportedAt: string;
+}
+
+interface AttachSelector {
+  last: boolean;
+  runtimeThreadId: string | null;
+  resumeRef: string | null;
+}
+
+interface AttachCandidate {
+  runtimeThreadId: string;
+  cliResumeRef: string;
+  cliResumeRefType: 'session_id';
+  threadName: string | null;
+  workspaceRoot: string;
+  updatedAt: string | null;
+}
+
+export interface AttachPayload {
+  status: AttachStatus;
+  reason?: AttachReason;
+  assistantName: string;
+  workspaceRoot: string;
+  assistantCodexHome: string | null;
+  selector: { mode: 'last' | 'thread' | 'resume_ref' | 'invalid'; value: string | null };
+  workSessionId: string | null;
+  threadHandle: string | null;
+  runtimeThreadId: string | null;
+  cliResumeRef: string | null;
+  cliResumeRefType: WorkSessionCliResumeRefType;
+  threadName: string | null;
+  activeSurface: WorkSessionMeta['activeSurface'] | null;
+  ownershipSource: WorkSessionMeta['ownershipSource'] | null;
+  candidateCount: number;
+  attachedAt: string;
+}
+
+function normalizeNullableText(value: string | null | undefined): string | null {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const trimmed = String(value).trim();
+  return trimmed || null;
+}
+
+function shellQuote(value: string): string {
+  if (value.length === 0) {
+    return "''";
+  }
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function formatResumeCommand(codexHome: string | null, workspaceRoot: string, cliResumeRef: string): string {
+  const envPrefix = codexHome ? `CODEX_HOME=${shellQuote(codexHome)} ` : '';
+  return `${envPrefix}codex resume --cd ${shellQuote(workspaceRoot)} ${shellQuote(cliResumeRef)}`;
+}
+
+function dbTimestampToIso(value: unknown): string | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return null;
+  }
+  const millis = value > 1e12 ? value : value * 1000;
+  return new Date(millis).toISOString();
+}
+
+function parseSessionIndex(filePath: string): Map<string, { threadName: string | null; updatedAt: string | null }> {
+  const result = new Map<string, { threadName: string | null; updatedAt: string | null }>();
+  if (!fs.existsSync(filePath)) {
+    return result;
+  }
+  const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(trimmed) as { id?: unknown; thread_name?: unknown; updated_at?: unknown };
+      if (typeof parsed.id !== 'string' || !parsed.id.trim()) {
+        continue;
+      }
+      result.set(parsed.id, {
+        threadName: typeof parsed.thread_name === 'string' ? parsed.thread_name : null,
+        updatedAt: typeof parsed.updated_at === 'string' ? parsed.updated_at : null,
+      });
+    } catch {
+      continue;
+    }
+  }
+  return result;
+}
+
+function attachSelectorFromArgs(args: string[]): AttachSelector {
+  let last = false;
+  let runtimeThreadId: string | null = null;
+  let resumeRef: string | null = null;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === '--last') {
+      last = true;
+      continue;
+    }
+    if (value === '--thread') {
+      runtimeThreadId = normalizeNullableText(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (value.startsWith('--thread=')) {
+      runtimeThreadId = normalizeNullableText(value.slice('--thread='.length));
+      continue;
+    }
+    if (value === '--resume-ref') {
+      resumeRef = normalizeNullableText(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (value.startsWith('--resume-ref=')) {
+      resumeRef = normalizeNullableText(value.slice('--resume-ref='.length));
+    }
+  }
+
+  return { last, runtimeThreadId, resumeRef };
+}
+
+async function openReadonlyDatabase(filePath: string) {
+  const sqlite = await import('node:sqlite');
+  return new sqlite.DatabaseSync(filePath, { open: true, readOnly: true });
+}
+
+export class HandoffService {
+  private readonly config: WorkAllyConfig;
+  private readonly workSessionStore: WorkSessionStore;
+
+  constructor(config: WorkAllyConfig, workSessionStore?: WorkSessionStore) {
+    this.config = config;
+    this.workSessionStore = workSessionStore || new WorkSessionStore(this.config.paths.workSessionsDir || path.join(this.config.paths.runtimeDir, 'work-sessions'));
+  }
+
+  private async hydrateCliResumeRef(current: WorkSessionMeta): Promise<WorkSessionMeta> {
+    if (current.cliResumeRef || current.resumeCapability === 'ready') {
+      return current;
+    }
+    const candidates = await this.loadAttachCandidates();
+    const candidate = candidates.find((item) => item.runtimeThreadId === current.runtimeThreadId) || null;
+    if (!candidate) {
+      return current;
+    }
+    return this.workSessionStore.updateWorkSession(current.workSessionId, {
+      cliResumeRef: candidate.cliResumeRef,
+      cliResumeRefType: candidate.cliResumeRefType,
+      threadName: candidate.threadName,
+      resumeCapability: 'ready',
+      lastRuntimeActivityAt: candidate.updatedAt,
+    });
+  }
+
+  async exportCurrentWorkSession(current: WorkSessionMeta | null): Promise<HandoffExportPayload> {
+    const exportedAt = nowIso();
+    if (!current) {
+      return {
+        status: 'not_found',
+        reason: 'active_work_session_missing',
+        assistantName: String(this.config.assistant?.name || '').trim() || 'native',
+        workspaceRoot: this.config.workspaceRoot,
+        assistantCodexHome: normalizeNullableText(this.config.assistant?.codexHome),
+        workSessionId: null,
+        threadHandle: null,
+        runtimeThreadId: null,
+        cliResumeRef: null,
+        cliResumeRefType: 'null',
+        threadName: null,
+        activeSurface: null,
+        ownershipSource: null,
+        resumeCapability: 'not_ready',
+        command: null,
+        exportedAt,
+      };
+    }
+
+    const hydrated = await this.hydrateCliResumeRef(current);
+
+    if (hydrated.resumeCapability !== 'ready' || !hydrated.cliResumeRef) {
+      return {
+        status: 'not_ready',
+        reason: 'cli_resume_ref_missing',
+        assistantName: hydrated.assistantName,
+        workspaceRoot: hydrated.workspaceRoot,
+        assistantCodexHome: hydrated.assistantCodexHome,
+        workSessionId: hydrated.workSessionId,
+        runtimeThreadId: hydrated.runtimeThreadId,
+        cliResumeRef: null,
+        cliResumeRefType: hydrated.cliResumeRefType,
+        threadName: hydrated.threadName,
+        activeSurface: hydrated.activeSurface,
+        ownershipSource: hydrated.ownershipSource,
+        resumeCapability: 'not_ready',
+        command: null,
+        exportedAt,
+      };
+    }
+
+    const updated = this.workSessionStore.updateWorkSession(hydrated.workSessionId, {
+      lastHandoffExportAt: exportedAt,
+    });
+    return {
+      status: 'ready',
+      assistantName: updated.assistantName,
+      workspaceRoot: updated.workspaceRoot,
+      assistantCodexHome: updated.assistantCodexHome,
+      workSessionId: updated.workSessionId,
+      runtimeThreadId: updated.runtimeThreadId,
+      cliResumeRef: updated.cliResumeRef,
+      cliResumeRefType: updated.cliResumeRefType,
+      threadName: updated.threadName,
+      activeSurface: updated.activeSurface,
+      ownershipSource: updated.ownershipSource,
+      resumeCapability: updated.resumeCapability,
+      command: formatResumeCommand(updated.assistantCodexHome, updated.workspaceRoot, updated.cliResumeRef),
+      exportedAt,
+    };
+  }
+
+  async exportActiveWorkSessionForAssistant(): Promise<HandoffExportPayload> {
+    const assistantName = String(this.config.assistant?.name || '').trim();
+    const current = assistantName
+      ? this.workSessionStore.getActiveWorkSessionForAssistant(assistantName)
+      : null;
+    return this.exportCurrentWorkSession(current);
+  }
+
+  markWorkSessionOfficialCli(workSessionId: string): WorkSessionMeta {
+    return this.workSessionStore.updateWorkSession(workSessionId, {
+      activeSurface: 'official_codex_cli',
+      ownershipSource: 'explicit_codex_launch',
+      lastSurfaceSwitchAt: nowIso(),
+    });
+  }
+
+  private existingManagedSessionFor(threadId: string): WorkSessionMeta | null {
+    const assistantName = String(this.config.assistant?.name || '').trim();
+    return this.workSessionStore.listWorkSessions().find((item) => (
+      item.assistantName === assistantName
+      && item.workspaceRoot === this.config.workspaceRoot
+      && item.runtimeThreadId === threadId
+      && !item.archivedAt
+    )) || null;
+  }
+
+  private async loadAttachCandidates(): Promise<AttachCandidate[]> {
+    const codexHome = normalizeNullableText(this.config.assistant?.codexHome);
+    if (!codexHome) {
+      return [];
+    }
+    const sqliteFile = path.join(codexHome, 'state_5.sqlite');
+    const sessionIndexFile = path.join(codexHome, 'session_index.jsonl');
+    if (!fs.existsSync(sqliteFile)) {
+      return [];
+    }
+
+    const sessionIndex = parseSessionIndex(sessionIndexFile);
+    const database = await openReadonlyDatabase(sqliteFile);
+    try {
+      const statement = database.prepare(`
+        SELECT id, cwd, title, updated_at
+        FROM threads
+        WHERE archived = 0 AND cwd = ?
+        ORDER BY updated_at DESC, id DESC
+      `);
+      const rows = statement.all(this.config.workspaceRoot) as Array<{ id: string; cwd: string; title: string; updated_at: number }>;
+      return rows.map((row) => {
+        const indexed = sessionIndex.get(row.id);
+        return {
+          runtimeThreadId: row.id,
+          cliResumeRef: row.id,
+          cliResumeRefType: 'session_id' as const,
+          threadName: indexed?.threadName || normalizeNullableText(row.title),
+          workspaceRoot: row.cwd,
+          updatedAt: indexed?.updatedAt || dbTimestampToIso(row.updated_at),
+        };
+      });
+    } finally {
+      database.close();
+    }
+  }
+
+  private async selectAttachCandidate(
+    selector: AttachSelector,
+    candidates: AttachCandidate[],
+  ): Promise<{ candidate: AttachCandidate | null; reason?: AttachReason; candidateCount: number; mode: 'last' | 'thread' | 'resume_ref' | 'invalid'; value: string | null }> {
+    const activeSelectors = Number(selector.last) + Number(Boolean(selector.runtimeThreadId)) + Number(Boolean(selector.resumeRef));
+    if (activeSelectors === 0) {
+      return { candidate: null, reason: 'attach_selector_required', candidateCount: candidates.length, mode: 'invalid', value: null };
+    }
+    if (activeSelectors > 1) {
+      return { candidate: null, reason: 'attach_selector_conflict', candidateCount: candidates.length, mode: 'invalid', value: null };
+    }
+
+    if (selector.last) {
+      if (candidates.length === 1) {
+        return { candidate: candidates[0], candidateCount: 1, mode: 'last', value: null };
+      }
+      return {
+        candidate: null,
+        reason: candidates.length === 0 ? 'candidate_not_found' : 'candidate_ambiguous',
+        candidateCount: candidates.length,
+        mode: 'last',
+        value: null,
+      };
+    }
+
+    if (selector.runtimeThreadId) {
+      const match = candidates.find((candidate) => candidate.runtimeThreadId === selector.runtimeThreadId) || null;
+      if (match) {
+        return { candidate: match, candidateCount: candidates.length, mode: 'thread', value: selector.runtimeThreadId };
+      }
+
+      const sqliteFile = path.join(String(this.config.assistant?.codexHome || ''), 'state_5.sqlite');
+      if (fs.existsSync(sqliteFile)) {
+        const database = await openReadonlyDatabase(sqliteFile);
+        try {
+          const row = database.prepare('SELECT cwd FROM threads WHERE id = ? LIMIT 1').get(selector.runtimeThreadId) as { cwd?: string } | undefined;
+          if (row?.cwd && row.cwd !== this.config.workspaceRoot) {
+            return { candidate: null, reason: 'workspace_mismatch', candidateCount: candidates.length, mode: 'thread', value: selector.runtimeThreadId };
+          }
+        } finally {
+          database.close();
+        }
+      }
+      return { candidate: null, reason: 'candidate_not_found', candidateCount: candidates.length, mode: 'thread', value: selector.runtimeThreadId };
+    }
+
+    const resumeRef = String(selector.resumeRef);
+    const exactId = candidates.find((candidate) => candidate.runtimeThreadId === resumeRef) || null;
+    if (exactId) {
+      return { candidate: exactId, candidateCount: candidates.length, mode: 'resume_ref', value: resumeRef };
+    }
+    const threadNameMatches = candidates.filter((candidate) => candidate.threadName === resumeRef);
+    if (threadNameMatches.length === 1) {
+      return { candidate: threadNameMatches[0], candidateCount: candidates.length, mode: 'resume_ref', value: resumeRef };
+    }
+    if (threadNameMatches.length > 1) {
+      return { candidate: null, reason: 'candidate_ambiguous', candidateCount: candidates.length, mode: 'resume_ref', value: resumeRef };
+    }
+    return { candidate: null, reason: 'candidate_not_found', candidateCount: candidates.length, mode: 'resume_ref', value: resumeRef };
+  }
+
+  async attachFromCliArgs(args: string[]): Promise<AttachPayload> {
+    const attachedAt = nowIso();
+    const assistantName = String(this.config.assistant?.name || '').trim() || 'native';
+    const assistantCodexHome = normalizeNullableText(this.config.assistant?.codexHome);
+    if (!assistantCodexHome) {
+      return {
+        status: 'error',
+        reason: 'assistant_codex_home_missing',
+        assistantName,
+        workspaceRoot: this.config.workspaceRoot,
+        assistantCodexHome: null,
+        selector: { mode: 'invalid', value: null },
+        workSessionId: null,
+        runtimeThreadId: null,
+        cliResumeRef: null,
+        cliResumeRefType: 'null',
+        threadName: null,
+        activeSurface: null,
+        ownershipSource: null,
+        candidateCount: 0,
+        attachedAt,
+      };
+    }
+
+    const candidates = await this.loadAttachCandidates();
+    const selected = await this.selectAttachCandidate(attachSelectorFromArgs(args), candidates);
+    if (!selected.candidate) {
+      return {
+        status: 'error',
+        reason: selected.reason,
+        assistantName,
+        workspaceRoot: this.config.workspaceRoot,
+        assistantCodexHome,
+        selector: { mode: selected.mode, value: selected.value },
+        workSessionId: null,
+        runtimeThreadId: null,
+        cliResumeRef: null,
+        cliResumeRefType: 'null',
+        threadName: null,
+        activeSurface: null,
+        ownershipSource: null,
+        candidateCount: selected.candidateCount,
+        attachedAt,
+      };
+    }
+
+    const existing = this.existingManagedSessionFor(selected.candidate.runtimeThreadId);
+    if (existing) {
+      this.workSessionStore.setAssistantActiveWorkSession(existing.assistantName, existing.workSessionId, attachedAt);
+      const updated = this.workSessionStore.updateWorkSession(existing.workSessionId, {
+        activeSurface: 'official_codex_cli',
+        ownershipSource: 'manual_attach',
+        lastAttachAt: attachedAt,
+        lastSurfaceSwitchAt: attachedAt,
+        cliResumeRef: selected.candidate.cliResumeRef,
+        cliResumeRefType: selected.candidate.cliResumeRefType,
+        threadName: selected.candidate.threadName,
+        resumeCapability: 'ready',
+        lastRuntimeActivityAt: selected.candidate.updatedAt,
+      });
+      return {
+        status: 'attached',
+        assistantName,
+        workspaceRoot: this.config.workspaceRoot,
+        assistantCodexHome,
+        selector: { mode: selected.mode, value: selected.value },
+        workSessionId: updated.workSessionId,
+        threadHandle: updated.threadHandle,
+        runtimeThreadId: updated.runtimeThreadId,
+        cliResumeRef: updated.cliResumeRef,
+        cliResumeRefType: updated.cliResumeRefType,
+        threadName: updated.threadName,
+        activeSurface: updated.activeSurface,
+        ownershipSource: updated.ownershipSource,
+        candidateCount: selected.candidateCount,
+        attachedAt,
+      };
+    }
+
+    const created = this.workSessionStore.createWorkSession({
+      assistantName,
+      assistantCodexHome,
+      workspaceRoot: this.config.workspaceRoot,
+      runtimeThreadId: selected.candidate.runtimeThreadId,
+      cliResumeRef: selected.candidate.cliResumeRef,
+      cliResumeRefType: selected.candidate.cliResumeRefType,
+      threadName: selected.candidate.threadName,
+      origin: 'codex_cli_attach',
+      activeSurface: 'official_codex_cli',
+      ownershipSource: 'manual_attach',
+      resumeCapability: 'ready',
+      lastAttachAt: attachedAt,
+      lastRuntimeActivityAt: selected.candidate.updatedAt,
+    });
+
+    return {
+      status: 'attached',
+      assistantName,
+      workspaceRoot: this.config.workspaceRoot,
+      assistantCodexHome,
+      selector: { mode: selected.mode, value: selected.value },
+      workSessionId: created.workSessionId,
+      threadHandle: created.threadHandle,
+      runtimeThreadId: created.runtimeThreadId,
+      cliResumeRef: created.cliResumeRef,
+      cliResumeRefType: created.cliResumeRefType,
+      threadName: created.threadName,
+      activeSurface: created.activeSurface,
+      ownershipSource: created.ownershipSource,
+      candidateCount: selected.candidateCount,
+      attachedAt,
+    };
+  }
+}

package/bridge/src/logger.ts

@@ -0,0 +1,194 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import util from 'node:util';
+import { ensureDir, nowIso, todayStamp } from './utils.ts';
+
+export interface ProcessLoggerOptions {
+  logsDir: string;
+  component: string;
+  timezone: string;
+  retentionDays: number;
+  mirrorToStdout?: boolean;
+  captureConsole?: boolean;
+}
+
+type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+
+const originalConsole = {
+  log: console.log.bind(console),
+  info: console.info.bind(console),
+  warn: console.warn.bind(console),
+  error: console.error.bind(console),
+  debug: console.debug.bind(console),
+};
+
+let processLogger: ProcessLogger | null = null;
+let consolePatched = false;
+
+function normalizeRetentionDays(value: number): number {
+  if (!Number.isFinite(value) || value < 1) {
+    return 3;
+  }
+  return Math.floor(value);
+}
+
+function serializeValue(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+  return util.inspect(value, {
+    depth: 6,
+    breakLength: 120,
+    maxArrayLength: 50,
+    compact: true,
+  });
+}
+
+function formatMeta(meta?: Record<string, unknown>): string {
+  if (!meta || Object.keys(meta).length === 0) {
+    return '';
+  }
+  return ` ${JSON.stringify(meta)}`;
+}
+
+export class ProcessLogger {
+  private readonly logsDir: string;
+  private readonly component: string;
+  private readonly timezone: string;
+  private readonly retentionDays: number;
+  private readonly mirrorToStdout: boolean;
+  private lastPrunedStamp: string | null = null;
+
+  constructor(options: ProcessLoggerOptions) {
+    this.logsDir = ensureDir(options.logsDir);
+    this.component = options.component;
+    this.timezone = options.timezone;
+    this.retentionDays = normalizeRetentionDays(options.retentionDays);
+    this.mirrorToStdout = options.mirrorToStdout === true;
+  }
+
+  currentLogFile(date = new Date(), component = this.component): string {
+    return path.join(this.logsDir, `${component}-${todayStamp(date, this.timezone)}.log`);
+  }
+
+  private prune(now = new Date()): void {
+    const pruneStamp = todayStamp(now, this.timezone);
+    if (this.lastPrunedStamp === pruneStamp) {
+      return;
+    }
+    this.lastPrunedStamp = pruneStamp;
+
+    const entries = fs.readdirSync(this.logsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) {
+        continue;
+      }
+      const match = entry.name.match(/^(?<name>[a-z0-9-]+)-(?<date>\d{4}-\d{2}-\d{2})\.log$/i);
+      if (!match?.groups) {
+        continue;
+      }
+      const fileDate = new Date(`${match.groups.date}T00:00:00Z`);
+      if (Number.isNaN(fileDate.getTime())) {
+        continue;
+      }
+      const ageMs = now.getTime() - fileDate.getTime();
+      if (ageMs <= this.retentionDays * 24 * 60 * 60 * 1000) {
+        continue;
+      }
+      try {
+        fs.rmSync(path.join(this.logsDir, entry.name), { force: true });
+      } catch {
+        // noop
+      }
+    }
+  }
+
+  private append(line: string): void {
+    const now = new Date();
+    this.prune(now);
+    fs.appendFileSync(this.currentLogFile(now), line, 'utf8');
+    if (this.component !== 'timeline') {
+      fs.appendFileSync(this.currentLogFile(now, 'timeline'), line, 'utf8');
+    }
+  }
+
+  private emitStdout(level: LogLevel, line: string): void {
+    if (!this.mirrorToStdout) {
+      return;
+    }
+    if (level === 'WARN') {
+      originalConsole.warn(line.trimEnd());
+      return;
+    }
+    if (level === 'ERROR') {
+      originalConsole.error(line.trimEnd());
+      return;
+    }
+    originalConsole.log(line.trimEnd());
+  }
+
+  event(level: LogLevel, event: string, meta?: Record<string, unknown>): void {
+    const line = `${nowIso()} [${level}] [${this.component}] ${event}${formatMeta(meta)}\n`;
+    this.append(line);
+    this.emitStdout(level, line);
+  }
+
+  info(event: string, meta?: Record<string, unknown>): void {
+    this.event('INFO', event, meta);
+  }
+
+  warn(event: string, meta?: Record<string, unknown>): void {
+    this.event('WARN', event, meta);
+  }
+
+  error(event: string, meta?: Record<string, unknown>): void {
+    this.event('ERROR', event, meta);
+  }
+
+  debug(event: string, meta?: Record<string, unknown>): void {
+    this.event('DEBUG', event, meta);
+  }
+
+  console(level: LogLevel, args: unknown[]): void {
+    const rendered = args.map((item) => serializeValue(item)).join(' ');
+    const line = `${nowIso()} [${level}] [console] ${rendered}\n`;
+    this.append(line);
+    this.emitStdout(level, line);
+  }
+}
+
+export function initializeProcessLogger(options: ProcessLoggerOptions): ProcessLogger {
+  processLogger = new ProcessLogger(options);
+  if (options.captureConsole === false) {
+    return processLogger;
+  }
+  if (!consolePatched) {
+    console.log = (...args: unknown[]) => processLogger?.console('INFO', args);
+    console.info = (...args: unknown[]) => processLogger?.console('INFO', args);
+    console.warn = (...args: unknown[]) => processLogger?.console('WARN', args);
+    console.error = (...args: unknown[]) => processLogger?.console('ERROR', args);
+    console.debug = (...args: unknown[]) => processLogger?.console('DEBUG', args);
+    consolePatched = true;
+  }
+  return processLogger;
+}
+
+export function getProcessLogger(): ProcessLogger | null {
+  return processLogger;
+}
+
+export function logInfo(component: string, event: string, meta?: Record<string, unknown>): void {
+  processLogger?.info(`${component}.${event}`, meta);
+}
+
+export function logWarn(component: string, event: string, meta?: Record<string, unknown>): void {
+  processLogger?.warn(`${component}.${event}`, meta);
+}
+
+export function logError(component: string, event: string, meta?: Record<string, unknown>): void {
+  processLogger?.error(`${component}.${event}`, meta);
+}
+
+export function logDebug(component: string, event: string, meta?: Record<string, unknown>): void {
+  processLogger?.debug(`${component}.${event}`, meta);
+}