Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): log git credential helper hit/miss to ~/.ok/logs (#1742)

Andrew Mikofalvyc804a7ae6e58
diff --git a/.changeset/git-credential-diagnostics.md b/.changeset/git-credential-diagnostics.md
new file mode 100644
index 000000000..226c2ed2b
--- /dev/null
+++ b/.changeset/git-credential-diagnostics.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+The git credential helper (`ok auth git-credential get`, invoked by git on every sync) now records a diagnostic line to `~/.ok/logs/cli.*.log` on every credential lookup: the host, the active storage backend, and the outcome — `found`, `absent` (no credential stored), or `read-error` (the keychain read failed, e.g. locked keychain or access denied). Hits log at `debug` (silent at the default level); misses log at `warn`. Previously these only went to stderr, which git swallows, so a vanished credential left no trace. The log is flushed before the helper exits so the record reliably lands. Token values are never logged.
diff --git a/packages/cli/src/auth/token-store.test.ts b/packages/cli/src/auth/token-store.test.ts
index 53320f547..200606d0a 100644
--- a/packages/cli/src/auth/token-store.test.ts
+++ b/packages/cli/src/auth/token-store.test.ts
@@ -14,6 +14,7 @@ interface SetPasswordCall extends KeyringCall {
const keyringMockState = {
throwOnImport: false,
throwOnConstruct: false,
+ throwOnGetPassword: false,
setPasswordCalls: [] as SetPasswordCall[],
deletePasswordCalls: [] as KeyringCall[],
getPasswordCalls: [] as KeyringCall[],
@@ -23,6 +24,7 @@ const keyringMockState = {
function resetKeyringMockState(): void {
keyringMockState.throwOnImport = false;
keyringMockState.throwOnConstruct = false;
+ keyringMockState.throwOnGetPassword = false;
keyringMockState.setPasswordCalls = [];
keyringMockState.deletePasswordCalls = [];
keyringMockState.getPasswordCalls = [];
@@ -52,6 +54,9 @@ class MockKeyringEntry {
service: this.service,
account: this.account,
});
+ if (keyringMockState.throwOnGetPassword) {
+ throw new Error('keychain read denied');
+ }
return keyringMockState.getPasswordReturns.get(`${this.service}:${this.account}`) ?? null;
}
deletePassword(): void {
@@ -190,6 +195,106 @@ describe('createTokenStore', () => {
});
});
+describe('createTokenStore diagnostics', () => {
+ let tmpDir: string;
+
+ beforeEach(() => {
+ resetKeyringMockState();
+ tmpDir = mkdtempSync(join(tmpdir(), 'ok-ts-diag-'));
+ });
+
+ afterEach(() => {
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ test('onBackendSelected reports keyring when the native module loads', async () => {
+ const { createTokenStore } = await import('./token-store.ts');
+ const selected: Array<{ backend: string; reason?: string }> = [];
+ await createTokenStore(join(tmpDir, 'auth.yml'), {
+ onBackendSelected: (info) => selected.push(info),
+ });
+ expect(selected).toEqual([{ backend: 'keyring' }]);
+ });
+
+ test('onBackendSelected reports file + reason when keyring is unavailable', async () => {
+ keyringMockState.throwOnImport = true;
+ const { createTokenStore } = await import('./token-store.ts');
+ const selected: Array<{ backend: string; reason?: string }> = [];
+ await createTokenStore(join(tmpDir, 'auth.yml'), {
+ onBackendSelected: (info) => selected.push(info),
+ });
+ expect(selected).toHaveLength(1);
+ expect(selected[0]?.backend).toBe('file');
+ expect(selected[0]?.reason).toContain('keyring unavailable');
+ });
+
+ test('onKeychainRead reports absent when no credential is stored', async () => {
+ const { createTokenStore } = await import('./token-store.ts');
+ const reads: Array<{ kind: string; host: string; error?: string }> = [];
+ const store = await createTokenStore(join(tmpDir, 'auth.yml'), {
+ onKeychainRead: (info) => reads.push(info),
+ });
+ const entry = await store.get('github.com');
+ expect(entry).toBeNull();
+ expect(reads).toEqual([{ kind: 'absent', host: 'github.com' }]);
+ });
+
+ test('onKeychainRead reports read-error with the error NAME only when getPassword throws', async () => {
+ keyringMockState.throwOnGetPassword = true;
+ const { createTokenStore } = await import('./token-store.ts');
+ const reads: Array<{ kind: string; host: string; error?: string }> = [];
+ const store = await createTokenStore(join(tmpDir, 'auth.yml'), {
+ onKeychainRead: (info) => reads.push(info),
+ });
+ const entry = await store.get('github.com');
+ expect(entry).toBeNull();
+ expect(reads).toHaveLength(1);
+ expect(reads[0]?.kind).toBe('read-error');
+ expect(reads[0]?.host).toBe('github.com');
+ expect(reads[0]?.error).toBe('Error');
+ expect(JSON.stringify(reads)).not.toContain('keychain read denied');
+ });
+
+ test('onKeychainRead reports corrupt-entry (no stored bytes) when JSON.parse fails', async () => {
+ const TOKEN_BYTES = 'gho_corrupt_secret_value_xyz';
+ keyringMockState.getPasswordReturns.set(`open-knowledge:github.com`, TOKEN_BYTES);
+ const { createTokenStore } = await import('./token-store.ts');
+ const reads: Array<{ kind: string; host: string; error?: string }> = [];
+ const store = await createTokenStore(join(tmpDir, 'auth.yml'), {
+ onKeychainRead: (info) => reads.push(info),
+ });
+ const entry = await store.get('github.com');
+ expect(entry).toBeNull();
+ expect(reads).toHaveLength(1);
+ expect(reads[0]?.kind).toBe('corrupt-entry');
+ expect(reads[0]?.host).toBe('github.com');
+ expect(reads[0]?.error).toBe('corrupt-entry');
+ expect(JSON.stringify(reads)).not.toContain(TOKEN_BYTES);
+ });
+
+ test('a throwing onKeychainRead callback never breaks the lookup', async () => {
+ const { createTokenStore } = await import('./token-store.ts');
+ const store = await createTokenStore(join(tmpDir, 'auth.yml'), {
+ onKeychainRead: () => {
+ throw new Error('diagnostic boom');
+ },
+ });
+ const miss = await store.get('github.com');
+ expect(miss).toBeNull();
+ });
+
+ test('a throwing onKeychainRead callback never breaks the read-error path', async () => {
+ keyringMockState.throwOnGetPassword = true;
+ const { createTokenStore } = await import('./token-store.ts');
+ const store = await createTokenStore(join(tmpDir, 'auth.yml'), {
+ onKeychainRead: () => {
+ throw new Error('diagnostic boom');
+ },
+ });
+ expect(await store.get('github.com')).toBeNull();
+ });
+});
+
describe('KeyringBackend upsert semantics', () => {
let tmpDir: string;
diff --git a/packages/cli/src/auth/token-store.ts b/packages/cli/src/auth/token-store.ts
index 728d018ce..bb8ebc2b0 100644
--- a/packages/cli/src/auth/token-store.ts
+++ b/packages/cli/src/auth/token-store.ts
@@ -25,17 +25,53 @@ export interface TokenStore {
const KEYRING_SERVICE = 'open-knowledge';
+function safeDiag(fn: () => void): void {
+ try {
+ fn();
+ } catch {}
+}
+
+export interface TokenStoreDiagnostics {
+ onKeychainRead?: (info: {
+ kind: 'absent' | 'read-error' | 'corrupt-entry';
+ host: string;
+ error?: string;
+ }) => void;
+ onBackendSelected?: (info: { backend: 'keyring' | 'file'; reason?: string }) => void;
+}
+
class KeyringBackend implements TokenStore {
readonly backend = 'keyring' as const;
+ constructor(private readonly onKeychainRead?: TokenStoreDiagnostics['onKeychainRead']) {}
+
async get(host: string): Promise<TokenEntry | null> {
const { Entry } = await import('@napi-rs/keyring');
+ let raw: string | null;
+ try {
+ raw = new Entry(KEYRING_SERVICE, host).getPassword();
+ } catch (e) {
+ safeDiag(() =>
+ this.onKeychainRead?.({
+ kind: 'read-error',
+ host,
+ error: e instanceof Error ? e.name : 'unknown',
+ }),
+ );
+ return null;
+ }
+
+ if (raw == null) {
+ safeDiag(() => this.onKeychainRead?.({ kind: 'absent', host }));
+ return null;
+ }
+
try {
- const entry = new Entry(KEYRING_SERVICE, host);
- const raw = entry.getPassword();
- if (raw == null) return null;
return JSON.parse(raw) as TokenEntry;
} catch {
+ safeDiag(() =>
+ this.onKeychainRead?.({ kind: 'corrupt-entry', host, error: 'corrupt-entry' }),
+ );
return null;
}
}
@@ -154,17 +190,25 @@ class KeychainWithFileFallback implements TokenStore {
}
}
-export async function createTokenStore(authFile?: string): Promise<TokenStore> {
+export async function createTokenStore(
+ authFile?: string,
+ diag?: TokenStoreDiagnostics,
+): Promise<TokenStore> {
try {
const { Entry } = await import('@napi-rs/keyring');
new Entry(KEYRING_SERVICE, '__probe__');
process.stderr.write('[auth] token storage: OS keychain\n');
- return new KeychainWithFileFallback(new KeyringBackend(), new FileBackend(authFile));
+ safeDiag(() => diag?.onBackendSelected?.({ backend: 'keyring' }));
+ return new KeychainWithFileFallback(
+ new KeyringBackend(diag?.onKeychainRead),
+ new FileBackend(authFile),
+ );
} catch (e) {
const reason = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
process.stderr.write(
`[auth] token storage: file (~/.ok/auth.yml) — OS keychain unavailable: ${reason}\n`,
);
+ safeDiag(() => diag?.onBackendSelected?.({ backend: 'file', reason }));
return new FileBackend(authFile);
}
}
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 74d475279..4bddee662 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -143,7 +143,7 @@ program.addCommand(bugReportCommand());
program.addCommand(configCommand());
-program.addCommand(authCommand());
+program.addCommand(authCommand(getCliLogger));
program.addCommand(embeddingsCommand());
diff --git a/packages/cli/src/commands/auth/git-credential.test.ts b/packages/cli/src/commands/auth/git-credential.test.ts
index 066964c5a..2cec49626 100644
--- a/packages/cli/src/commands/auth/git-credential.test.ts
+++ b/packages/cli/src/commands/auth/git-credential.test.ts
@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Readable, Writable } from 'node:stream';
import { FileBackend } from '../../auth/token-store.ts';
-import { handleCredentialGet } from './git-credential.ts';
+import { type CredentialGetLogContext, handleCredentialGet } from './git-credential.ts';
function makeStream(content: string): Readable {
return Readable.from([Buffer.from(content, 'utf-8')]);
@@ -123,3 +123,136 @@ describe('handleCredentialGet', () => {
expect(lines[2]).toBe('');
});
});
+
+interface LogCall {
+ level: 'debug' | 'warn';
+ fields: Record<string, unknown>;
+ msg: string;
+}
+
+function makeFakeLogger() {
+ const calls: LogCall[] = [];
+ const record = (level: 'debug' | 'warn') => (fields: Record<string, unknown>, msg: string) =>
+ calls.push({ level, fields, msg });
+ const logger = {
+ debug: record('debug'),
+ warn: record('warn'),
+ info: () => {},
+ error: () => {},
+ fatal: () => {},
+ trace: () => {},
+ } as unknown as NonNullable<CredentialGetLogContext['log']>;
+ return { logger, calls };
+}
+
+describe('handleCredentialGet diagnostic logging', () => {
+ let tmpDir: string;
+ beforeEach(() => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'ok-git-cred-log-'));
+ });
+ afterEach(() => {
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ test('logs found at debug with host/backend and never the token', async () => {
+ const store = makeStore(tmpDir);
+ await store.set('github.com', 'alice', 'gho_super_secret');
+ const input = makeStream('protocol=https\nhost=github.com\n\n');
+ const { writable } = makeOutput();
+ const { logger, calls } = makeFakeLogger();
+
+ const code = await handleCredentialGet(input, writable, store, { log: logger });
+
+ expect(code).toBe(0);
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.level).toBe('debug');
+ expect(calls[0]?.fields).toMatchObject({
+ host: 'github.com',
+ outcome: 'found',
+ backend: 'file',
+ });
+ expect(JSON.stringify(calls)).not.toContain('gho_super_secret');
+ });
+
+ test('logs absent at warn when no credential is stored', async () => {
+ const store = makeStore(tmpDir);
+ const input = makeStream('protocol=https\nhost=github.com\n\n');
+ const { writable } = makeOutput();
+ const { logger, calls } = makeFakeLogger();
+
+ const code = await handleCredentialGet(input, writable, store, { log: logger });
+
+ expect(code).toBe(1);
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.level).toBe('warn');
+ expect(calls[0]?.fields).toMatchObject({
+ host: 'github.com',
+ outcome: 'absent',
+ backend: 'file',
+ });
+ });
+
+ test('logs read-error at warn when the keychain read failed', async () => {
+ const store = makeStore(tmpDir);
+ const input = makeStream('protocol=https\nhost=github.com\n\n');
+ const { writable } = makeOutput();
+ const { logger, calls } = makeFakeLogger();
+
+ const code = await handleCredentialGet(input, writable, store, {
+ log: logger,
+ getDiag: () => ({ kind: 'read-error', host: 'github.com', error: 'Error: denied' }),
+ });
+
+ expect(code).toBe(1);
+ expect(calls[0]?.level).toBe('warn');
+ expect(calls[0]?.fields).toMatchObject({
+ host: 'github.com',
+ outcome: 'read-error',
+ keychainError: 'Error: denied',
+ });
+ });
+
+ test('logs corrupt-entry at warn with a bytes-free keychainError', async () => {
+ const store = makeStore(tmpDir);
+ const input = makeStream('protocol=https\nhost=github.com\n\n');
+ const { writable } = makeOutput();
+ const { logger, calls } = makeFakeLogger();
+
+ const code = await handleCredentialGet(input, writable, store, {
+ log: logger,
+ getDiag: () => ({ kind: 'corrupt-entry', host: 'github.com', error: 'corrupt-entry' }),
+ });
+
+ expect(code).toBe(1);
+ expect(calls[0]?.level).toBe('warn');
+ expect(calls[0]?.fields).toMatchObject({
+ host: 'github.com',
+ outcome: 'corrupt-entry',
+ keychainError: 'corrupt-entry',
+ });
+ });
+
+ test('logs no-host at warn when the request omits a host', async () => {
+ const store = makeStore(tmpDir);
+ const input = makeStream('protocol=https\n\n');
+ const { writable } = makeOutput();
+ const { logger, calls } = makeFakeLogger();
+
+ const code = await handleCredentialGet(input, writable, store, { log: logger });
+
+ expect(code).toBe(1);
+ expect(calls[0]?.level).toBe('warn');
+ expect(calls[0]?.fields).toMatchObject({ outcome: 'no-host' });
+ });
+
+ test('no logger → no throw, behaviour unchanged', async () => {
+ const store = makeStore(tmpDir);
+ await store.set('github.com', 'alice', 'gho_abc');
+ const input = makeStream('protocol=https\nhost=github.com\n\n');
+ const { writable, result } = makeOutput();
+
+ const code = await handleCredentialGet(input, writable, store);
+ expect(code).toBe(0);
+ expect(result()).toBe('username=alice\npassword=gho_abc\n');
+ });
+});
diff --git a/packages/cli/src/commands/auth/git-credential.ts b/packages/cli/src/commands/auth/git-credential.ts
index 0aa40225a..31c7104df 100644
--- a/packages/cli/src/commands/auth/git-credential.ts
+++ b/packages/cli/src/commands/auth/git-credential.ts
@@ -1,19 +1,48 @@
import type { Readable, Writable } from 'node:stream';
+import { flushFileLogger } from '@inkeep/open-knowledge-server';
import { Command } from 'commander';
-import type { TokenStore } from '../../auth/token-store.ts';
+import type { Logger as PinoLoggerInstance } from 'pino';
+import type { TokenStore, TokenStoreDiagnostics } from '../../auth/token-store.ts';
+
+type KeychainReadInfo = Parameters<NonNullable<TokenStoreDiagnostics['onKeychainRead']>>[0];
+
+export interface CredentialGetLogContext {
+ log?: PinoLoggerInstance;
+ getDiag?: () => KeychainReadInfo | undefined;
+}
export async function handleCredentialGet(
input: Readable,
output: Writable,
tokenStore: TokenStore,
+ ctx?: CredentialGetLogContext,
): Promise<number> {
const text = await readAll(input);
const attrs = parseCredentialInput(text);
const host = attrs.host ?? '';
- if (!host) return 1;
+ if (!host) {
+ ctx?.log?.warn(
+ { outcome: 'no-host', backend: tokenStore.backend },
+ '[auth] git-credential get',
+ );
+ return 1;
+ }
const entry = await tokenStore.get(host);
+ const diag = ctx?.getDiag?.();
+ const outcome = entry != null ? 'found' : (diag?.kind ?? 'absent');
+ if (ctx?.log) {
+ const fields = {
+ host,
+ outcome,
+ backend: tokenStore.backend,
+ ...(diag?.error ? { keychainError: diag.error } : {}),
+ };
+ if (outcome === 'found') ctx.log.debug(fields, '[auth] git-credential get');
+ else ctx.log.warn(fields, '[auth] git-credential get');
+ }
+
if (entry == null) return 1;
const safeLine = (s: string) => s.replace(/[\r\n]/g, '');
@@ -42,7 +71,10 @@ function readAll(stream: Readable): Promise<string> {
});
}
-export function gitCredentialCommand(getTokenStore: () => Promise<TokenStore>): Command {
+export function gitCredentialCommand(
+ getTokenStore: (diag?: TokenStoreDiagnostics) => Promise<TokenStore>,
+ getLog?: () => PinoLoggerInstance | undefined,
+): Command {
const cmd = new Command('git-credential');
cmd.description('Git credential helper (git credential-helper protocol)');
@@ -50,9 +82,33 @@ export function gitCredentialCommand(getTokenStore: () => Promise<TokenStore>):
.command('get')
.description('Lookup credentials from TokenStore (called by git)')
.action(async () => {
- const store = await getTokenStore();
- const exitCode = await handleCredentialGet(process.stdin, process.stdout, store);
- process.exit(exitCode);
+ const log = getLog?.();
+ try {
+ let lastKeychainRead: KeychainReadInfo | undefined;
+ const store = await getTokenStore({
+ onKeychainRead: (info) => {
+ lastKeychainRead = info;
+ },
+ onBackendSelected: (info) => {
+ if (info.backend === 'file' && info.reason) {
+ log?.warn({ backend: 'file', reason: info.reason }, '[auth] token storage fallback');
+ }
+ },
+ });
+ const exitCode = await handleCredentialGet(process.stdin, process.stdout, store, {
+ log,
+ getDiag: () => lastKeychainRead,
+ });
+ await flushFileLogger(log);
+ process.exit(exitCode);
+ } catch (err) {
+ log?.error(
+ { error: err instanceof Error ? err.message : String(err) },
+ '[auth] git-credential get: unexpected error',
+ );
+ await flushFileLogger(log);
+ process.exit(1);
+ }
});
return cmd;
diff --git a/packages/cli/src/commands/auth/index.ts b/packages/cli/src/commands/auth/index.ts
index 3c6b93b61..c758157fc 100644
--- a/packages/cli/src/commands/auth/index.ts
+++ b/packages/cli/src/commands/auth/index.ts
@@ -1,5 +1,6 @@
import { Command } from 'commander';
-import { createTokenStore } from '../../auth/token-store.ts';
+import type { Logger as PinoLoggerInstance } from 'pino';
+import { createTokenStore, type TokenStoreDiagnostics } from '../../auth/token-store.ts';
import { gitCredentialCommand } from './git-credential.ts';
import { loginCommand } from './login.ts';
import { patCommand } from './pat.ts';
@@ -7,18 +8,18 @@ import { reposCommand } from './repos.ts';
import { signoutCommand } from './signout.ts';
import { statusCommand } from './status.ts';
-export function authCommand(): Command {
+export function authCommand(getLog?: () => PinoLoggerInstance | undefined): Command {
const cmd = new Command('auth');
cmd.description('GitHub authentication management');
- const getTokenStore = () => createTokenStore();
+ const getTokenStore = (diag?: TokenStoreDiagnostics) => createTokenStore(undefined, diag);
cmd.addCommand(loginCommand(getTokenStore));
cmd.addCommand(statusCommand(getTokenStore));
cmd.addCommand(reposCommand(getTokenStore));
cmd.addCommand(signoutCommand());
cmd.addCommand(patCommand(getTokenStore));
- cmd.addCommand(gitCredentialCommand(getTokenStore));
+ cmd.addCommand(gitCredentialCommand(getTokenStore, getLog));
return cmd;
}
diff --git a/packages/server/src/file-logger.test.ts b/packages/server/src/file-logger.test.ts
index 487caf738..70abc5148 100644
--- a/packages/server/src/file-logger.test.ts
+++ b/packages/server/src/file-logger.test.ts
@@ -1,9 +1,9 @@
import { afterEach, describe, expect, test } from 'bun:test';
-import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import pino from 'pino';
-import { MAX_FILE_SIZE } from './file-logger.ts';
+import { flushFileLogger, MAX_FILE_SIZE } from './file-logger.ts';
const TEST_DIR = join(tmpdir(), `ok-file-logger-test-${process.pid}`);
@@ -100,4 +100,85 @@ describe('file logger', () => {
expect(unrefCalls).toBe(1);
expect(scheduledMs).toBe(5000);
});
+
+ test('flushFileLogger persists a record logged immediately before exit', async () => {
+ mkdirSync(TEST_DIR, { recursive: true });
+ const filePath = join(TEST_DIR, 'flush.log');
+ const prev = process.env.OK_LOG_LEVEL;
+ process.env.OK_LOG_LEVEL = 'info';
+ try {
+ const { createFileLogger } = require('./file-logger.ts');
+ const logger = createFileLogger({ name: 'flush', filePath });
+ logger.warn({ outcome: 'absent', host: 'github.com' }, '[auth] git-credential get');
+ await flushFileLogger(logger);
+ const content = readFileSync(filePath, 'utf8');
+ expect(content).toContain('git-credential get');
+ expect(content).toContain('"outcome":"absent"');
+ } finally {
+ if (prev === undefined) delete process.env.OK_LOG_LEVEL;
+ else process.env.OK_LOG_LEVEL = prev;
+ }
+ });
+
+ test('flushFileLogger(undefined) resolves without throwing', async () => {
+ await expect(flushFileLogger(undefined)).resolves.toBeUndefined();
+ });
+
+ function makeFakeLogger(stream: unknown): PinoLoggerInstance {
+ return { [pino.symbols.streamSym]: stream } as unknown as PinoLoggerInstance;
+ }
+
+ test("flushFileLogger waits for 'ready' when the fd is not open yet, then flushes", async () => {
+ let flushed = false;
+ let readyCb: (() => void) | undefined;
+ const stream = {
+ fd: -1,
+ flushSync: () => {
+ flushed = true;
+ },
+ once: (event: string, cb: () => void) => {
+ if (event === 'ready') readyCb = cb;
+ },
+ };
+
+ const p = flushFileLogger(makeFakeLogger(stream), 5000);
+ expect(flushed).toBe(false);
+ expect(typeof readyCb).toBe('function');
+
+ readyCb?.();
+ await p;
+ expect(flushed).toBe(true);
+ });
+
+ test('flushFileLogger resolves within the bound when the stream never becomes ready', async () => {
+ let flushed = false;
+ const stream = {
+ fd: -1,
+ flushSync: () => {
+ flushed = true;
+ },
+ once: (_event: string, _cb: () => void) => {},
+ };
+
+ const start = Date.now();
+ await flushFileLogger(makeFakeLogger(stream), 30);
+ const elapsed = Date.now() - start;
+ expect(flushed).toBe(false);
+ expect(elapsed).toBeLessThan(1000);
+ });
+
+ test('flushFileLogger flushes immediately when the fd is already open', async () => {
+ let flushed = false;
+ const stream = {
+ fd: 7,
+ flushSync: () => {
+ flushed = true;
+ },
+ once: () => {
+ throw new Error('should not wait for ready when fd is already open');
+ },
+ };
+ await flushFileLogger(makeFakeLogger(stream), 5000);
+ expect(flushed).toBe(true);
+ });
});
diff --git a/packages/server/src/file-logger.ts b/packages/server/src/file-logger.ts
index 3964716f0..dadda7429 100644
--- a/packages/server/src/file-logger.ts
+++ b/packages/server/src/file-logger.ts
@@ -145,6 +145,57 @@ export function createFileLogger(opts: FileLoggerOptions): PinoLoggerInstance {
return logger;
}
+interface FlushableStream {
+ fd?: number;
+ flushSync?: () => void;
+ once?: (event: string, cb: () => void) => void;
+}
+
+export function flushFileLogger(
+ logger: PinoLoggerInstance | undefined,
+ timeoutMs = 250,
+): Promise<void> {
+ return new Promise((resolve) => {
+ if (!logger) {
+ resolve();
+ return;
+ }
+ const stream = (logger as unknown as Record<symbol, unknown>)[pino.symbols.streamSym] as
+ | FlushableStream
+ | undefined;
+ let settled = false;
+ const done = (): void => {
+ if (settled) return;
+ settled = true;
+ resolve();
+ };
+ if (!stream || typeof stream.flushSync !== 'function') {
+ done();
+ return;
+ }
+ const flushAndDone = (): void => {
+ try {
+ stream.flushSync?.();
+ } catch {}
+ done();
+ };
+ const timer = setTimeout(done, timeoutMs);
+ if (typeof timer.unref === 'function') timer.unref();
+ if (typeof stream.fd === 'number' && stream.fd >= 0) {
+ clearTimeout(timer);
+ flushAndDone();
+ } else if (typeof stream.once === 'function') {
+ stream.once('ready', () => {
+ clearTimeout(timer);
+ flushAndDone();
+ });
+ } else {
+ clearTimeout(timer);
+ flushAndDone();
+ }
+ });
+}
+
export function getLogFilePath(name: string): string {
return join(OK_LOGS_DIR, `${name}.${todayDateString()}.log`);
}
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index 0b6099699..f99444644 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -119,7 +119,7 @@ export {
createExternalChangeHandler,
FILE_WATCHER_ORIGIN,
} from './external-change.ts';
-export { createFileLogger, getLogFilePath, getLogsDir } from './file-logger.ts';
+export { createFileLogger, flushFileLogger, getLogFilePath, getLogsDir } from './file-logger.ts';
export {
type AsyncSubscription,
assertNeverDiskEvent,