Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { execFile } from 'node:child_process';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { promisify } from 'node:util';
import { emitToleranceFire, OK_DIR, resolveServerRuntimeConfig } from '@inkeep/open-knowledge-core';
import { context, metrics, propagation, trace } from '@opentelemetry/api';
import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
import { W3CTraceContextPropagator } from '@opentelemetry/core';
import {
BasicTracerProvider,
InMemorySpanExporter,
SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-base';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { bootServer } from '../../../test-support/boot-server.test-helper.ts';
import { configureTestGitRepository } from '../../../test-support/configure-git-fixture.test-helper.ts';
import { getBootTimings } from './boot-timings.ts';
import { ConfigSchema } from './config/schema.ts';
import { getLogger } from './logger.ts';
import { parseKeepaliveConnectionId } from './mcp-mount.ts';
import { shutdownTelemetry } from './telemetry.ts';
beforeEach(() => {
vi.stubEnv('OK_CHANNEL', 'stable');
});
afterEach(() => {
vi.unstubAllEnvs();
});
function seedOkScaffold(projectDir: string): void {
const okDir = resolve(projectDir, OK_DIR);
mkdirSync(okDir, { recursive: true });
writeFileSync(resolve(okDir, 'config.yml'), '', 'utf-8');
writeFileSync(resolve(okDir, '.gitignore'), '', 'utf-8');
}
const execFileAsync = promisify(execFile);
const TEST_CONFIG = ConfigSchema.parse({});
const bootHome = vi.hoisted(() => ({ path: undefined as string | undefined }));
vi.mock('node:os', async (importOriginal) => {
const os = await importOriginal<typeof import('node:os')>();
return { ...os, homedir: () => bootHome.path ?? os.homedir() };
});
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-boot-test-'));
bootHome.path = mkdtempSync(resolve(tmpDir, 'home-'));
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
bootHome.path = undefined;
});
describe('bootServer — MissingOkConfigError pre-listen check', () => {
test('rejects with kind=okdir when .ok/ directory is absent (State A)', async () => {
const contentDir = mkdtempSync(resolve(tmpDir, 'state-a-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
let caught: unknown;
try {
await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
const e = caught as Error & { kind?: string; projectDir?: string };
expect(e.name).toBe('MissingOkConfigError');
expect(e.kind).toBe('okdir');
expect(e.projectDir).toBe(contentDir);
expect(e.message).toContain('OpenKnowledge config not found at .ok/config.yml');
expect(e.message).toContain('Run ok init');
expect(existsSync(resolve(contentDir, '.git/ok'))).toBe(false);
});
test('rejects with kind=config when .ok/ exists but config.yml is missing (State B)', async () => {
const contentDir = mkdtempSync(resolve(tmpDir, 'state-b-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
const okDir = resolve(contentDir, '.ok');
writeFileSync(resolve(contentDir, 'placeholder'), '');
await execFileAsync('mkdir', [okDir]);
let caught: unknown;
try {
await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
const e = caught as Error & { kind?: string };
expect(e.name).toBe('MissingOkConfigError');
expect(e.kind).toBe('config');
expect(e.message).toContain('OpenKnowledge config not found at .ok/config.yml');
expect(existsSync(resolve(contentDir, '.git/ok'))).toBe(false);
});
test('preflight checks projectDir/.ok/config.yml when projectDir != contentDir', async () => {
const projectDir = mkdtempSync(resolve(tmpDir, 'projectdir-preflight-'));
await execFileAsync('git', ['init', '--initial-branch=main', projectDir]);
configureTestGitRepository(projectDir);
seedOkScaffold(projectDir);
const contentDir = resolve(projectDir, 'docs');
mkdirSync(contentDir, { recursive: true });
expect(existsSync(resolve(contentDir, '.ok', 'config.yml'))).toBe(false);
let booted: Awaited<ReturnType<typeof bootServer>> | null = null;
try {
booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
projectDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
expect(booted.port).toBeGreaterThan(0);
} finally {
if (booted) await booted.destroy();
}
});
test('rejects when projectDir/.ok/config.yml is missing even though contentDir/.ok/config.yml exists', async () => {
const projectDir = mkdtempSync(resolve(tmpDir, 'projectdir-only-content-'));
await execFileAsync('git', ['init', '--initial-branch=main', projectDir]);
configureTestGitRepository(projectDir);
const contentDir = resolve(projectDir, 'docs');
mkdirSync(contentDir, { recursive: true });
seedOkScaffold(contentDir);
let caught: unknown;
try {
await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
projectDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
const e = caught as Error & { kind?: string; projectDir?: string };
expect(e.name).toBe('MissingOkConfigError');
expect(e.kind).toBe('okdir');
expect(e.projectDir).toBe(projectDir);
});
test('proceeds and emits a one-time stderr warning when only .ok/.gitignore is missing (State C)', async () => {
const contentDir = mkdtempSync(resolve(tmpDir, 'state-c-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
const okDir = resolve(contentDir, '.ok');
await execFileAsync('mkdir', [okDir]);
writeFileSync(resolve(okDir, 'config.yml'), '', 'utf-8');
const warnSpy = vi.spyOn(getLogger('boot'), 'warn');
let booted: Awaited<ReturnType<typeof bootServer>> | null = null;
try {
booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
const bootWarnings = warnSpy.mock.calls
.map((call) => String(call[1] ?? ''))
.filter((w) => w.includes('.gitignore is missing'));
expect(bootWarnings.length).toBe(1);
expect(bootWarnings[0]).toContain('.ok/.gitignore');
expect(bootWarnings[0]).toContain('Run `ok init` to add the recommended ignore entries.');
} finally {
warnSpy.mockRestore();
if (booted) await booted.destroy();
}
});
});
describe('bootServer — runtime state lives at projectDir, not contentDir', () => {
test('boot writes server.lock, principal.json, state.json under projectDir, not contentDir', async () => {
const projectDir = mkdtempSync(resolve(tmpDir, 'fake-repo-'));
await execFileAsync('git', ['init', '--initial-branch=main', projectDir]);
configureTestGitRepository(projectDir);
seedOkScaffold(projectDir);
const contentDir = resolve(projectDir, 'template-projects');
mkdirSync(contentDir, { recursive: true });
const booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
try {
await booted.ready;
const contentLocalDir = resolve(contentDir, '.ok');
expect(existsSync(contentLocalDir)).toBe(false);
const projectLocalDir = resolve(projectDir, '.ok', 'local');
expect(existsSync(resolve(projectLocalDir, 'server.lock'))).toBe(true);
expect(existsSync(resolve(projectLocalDir, 'principal.json'))).toBe(true);
expect(existsSync(resolve(projectLocalDir, 'state.json'))).toBe(true);
} finally {
await booted.destroy();
}
});
});
describe('bootServer — tolerance-telemetry writer wired through the real boot path', () => {
test('flag=1 boot produces tolerance-telemetry.jsonl from an emitToleranceFire', async () => {
const prevFlag = process.env.OK_BRIDGE_TOLERANCE_TELEMETRY;
process.env.OK_BRIDGE_TOLERANCE_TELEMETRY = '1';
const projectDir = mkdtempSync(resolve(tmpDir, 'tolerance-telemetry-'));
await execFileAsync('git', ['init', '--initial-branch=main', projectDir]);
configureTestGitRepository(projectDir);
seedOkScaffold(projectDir);
const booted = await bootServer({
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
try {
await booted.ready;
emitToleranceFire(['crlf'], 'a\r\n', 'a\n', 'smoke-doc');
} finally {
await booted.destroy();
if (prevFlag === undefined) delete process.env.OK_BRIDGE_TOLERANCE_TELEMETRY;
else process.env.OK_BRIDGE_TOLERANCE_TELEMETRY = prevFlag;
}
const logPath = resolve(projectDir, '.ok', 'local', 'tolerance-telemetry.jsonl');
expect(existsSync(logPath)).toBe(true);
const record = JSON.parse(readFileSync(logPath, 'utf-8').trim().split('\n')[0] ?? '');
expect(record.event).toBe('bridge-tolerance-fire');
expect(record.class).toBe('crlf');
expect(record.document).toBe('smoke-doc');
});
});
describe('bootServer — idle-shutdown runs full destroy', () => {
test('after idle-shutdown fires with zero WS clients, httpServer is no longer listening', async () => {
const projectDir = mkdtempSync(resolve(tmpDir, 'idle-full-destroy-'));
await execFileAsync('git', ['init', '--initial-branch=main', projectDir]);
configureTestGitRepository(projectDir);
seedOkScaffold(projectDir);
const booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: projectDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: 50,
});
try {
expect(booted.httpServer.listening).toBe(true);
const deadline = Date.now() + 3_000;
while (booted.httpServer.listening && Date.now() < deadline) {
await new Promise((r) => setTimeout(r, 25));
}
expect(booted.httpServer.listening).toBe(false);
} finally {
await booted.destroy();
}
});
test('keeps the listener available when global skill migration is slow', async () => {
const projectDir = mkdtempSync(resolve(tmpDir, 'idle-global-skills-'));
await execFileAsync('git', ['init', '--initial-branch=main', projectDir]);
configureTestGitRepository(projectDir);
seedOkScaffold(projectDir);
if (bootHome.path === undefined) throw new Error('boot home was not initialized');
const home = bootHome.path;
const storeSkill = resolve(home, '.ok', 'skills', 'valid-name');
const globalSkills = resolve(home, '.claude', 'skills');
mkdirSync(storeSkill, { recursive: true });
mkdirSync(globalSkills, { recursive: true });
writeFileSync(
resolve(storeSkill, 'SKILL.md'),
'---\nname: valid-name\ndescription: A valid store skill.\n---\n# Valid\n',
'utf-8',
);
for (let index = 0; index < 300; index += 1) {
const skillDir = resolve(globalSkills, `global-${index}`);
mkdirSync(skillDir, { recursive: true });
writeFileSync(
resolve(skillDir, 'SKILL.md'),
`---\nname: global-${index}\ndescription: A global skill.\n---\n# Global\n`,
'utf-8',
);
}
bootHome.path = home;
let idleAttachedAfterMigration = false;
const booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: projectDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: 50,
idleShutdownHandler: (destroyServer) => {
idleAttachedAfterMigration = existsSync(resolve(globalSkills, 'valid-name', 'SKILL.md'));
return async () => {
await destroyServer();
};
},
});
try {
expect(existsSync(resolve(globalSkills, 'valid-name', 'SKILL.md'))).toBe(true);
expect(idleAttachedAfterMigration).toBe(true);
expect(booted.httpServer.listening).toBe(true);
} finally {
await booted.destroy();
}
});
});
describe('bootServer — reactShellDistDir + server.lock ui advertisement', () => {
test('server.lock advertises the ui capability when --react-shell-dist-dir is set', async () => {
const projectDir = mkdtempSync(resolve(tmpDir, 'fake-repo-shell-'));
await execFileAsync('git', ['init', '--initial-branch=main', projectDir]);
configureTestGitRepository(projectDir);
seedOkScaffold(projectDir);
const shellDistDir = mkdtempSync(resolve(tmpDir, 'fake-shell-dist-'));
writeFileSync(resolve(shellDistDir, 'index.html'), '<html>shell</html>', 'utf-8');
const booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
reactShellDistDir: shellDistDir,
});
try {
await booted.ready;
const serverLockPath = resolve(projectDir, '.ok', 'local', 'server.lock');
const raw = await import('node:fs/promises').then((m) => m.readFile(serverLockPath, 'utf-8'));
const parsed = JSON.parse(raw) as { port: number; pid: number; capabilities?: string[] };
expect(parsed.capabilities).toContain('ui');
expect(parsed.port).toBe(booted.port);
expect(parsed.pid).toBe(process.pid);
expect(existsSync(resolve(projectDir, '.ok', 'local', 'ui.lock'))).toBe(false);
} finally {
await booted.destroy();
}
});
test('server.lock omits the ui capability when reactShellDistDir is absent (CLI default)', async () => {
const projectDir = mkdtempSync(resolve(tmpDir, 'fake-repo-no-shell-'));
await execFileAsync('git', ['init', '--initial-branch=main', projectDir]);
configureTestGitRepository(projectDir);
seedOkScaffold(projectDir);
const booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
try {
await booted.ready;
const serverLockPath = resolve(projectDir, '.ok', 'local', 'server.lock');
const raw = await import('node:fs/promises').then((m) => m.readFile(serverLockPath, 'utf-8'));
const parsed = JSON.parse(raw) as { capabilities?: string[] };
expect(parsed.capabilities ?? []).not.toContain('ui');
} finally {
await booted.destroy();
}
});
});
describe('bootServer — reactShellDistDir end-to-end HTTP shape', () => {
test('serves the React shell, bundled assets, content assets, and API on one port', async () => {
const projectDir = mkdtempSync(resolve(tmpDir, 'shell-e2e-'));
await execFileAsync('git', ['init', '--initial-branch=main', projectDir]);
configureTestGitRepository(projectDir);
seedOkScaffold(projectDir);
const shellDistDir = mkdtempSync(resolve(tmpDir, 'shell-e2e-dist-'));
writeFileSync(
resolve(shellDistDir, 'index.html'),
'<!DOCTYPE html><html><body data-test="shell">ok</body></html>',
'utf-8',
);
mkdirSync(resolve(shellDistDir, 'assets'));
writeFileSync(
resolve(shellDistDir, 'assets', 'app-deadbeef.js'),
'console.log("bundle");',
'utf-8',
);
const fontBytes = Buffer.from('woff2-bundle-bytes', 'utf-8');
writeFileSync(resolve(shellDistDir, 'assets', 'inter-cafebabe.woff2'), fontBytes);
mkdirSync(resolve(projectDir, 'docs'), { recursive: true });
const pngBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
writeFileSync(resolve(projectDir, 'docs', 'image.png'), pngBytes);
mkdirSync(resolve(projectDir, 'assets'), { recursive: true });
const uploadBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x11, 0x22, 0x33, 0x44]);
writeFileSync(resolve(projectDir, 'assets', 'upload.png'), uploadBytes);
const booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
serveContentAssets: true,
reactShellDistDir: shellDistDir,
});
try {
await booted.ready;
const base = `http://127.0.0.1:${booted.port}`;
const rootRes = await fetch(`${base}/`);
expect(rootRes.status).toBe(200);
const rootBody = await rootRes.text();
expect(rootBody).toContain('data-test="shell"');
const deepRes = await fetch(`${base}/some/unknown/route`);
expect(deepRes.status).toBe(200);
expect(await deepRes.text()).toContain('data-test="shell"');
const bundleRes = await fetch(`${base}/assets/app-deadbeef.js`);
expect(bundleRes.status).toBe(200);
expect(await bundleRes.text()).toContain('console.log');
const fontRes = await fetch(`${base}/assets/inter-cafebabe.woff2`);
expect(fontRes.status).toBe(200);
expect(Buffer.from(await fontRes.arrayBuffer()).equals(fontBytes)).toBe(true);
const uploadRes = await fetch(`${base}/assets/upload.png`);
expect(uploadRes.status).toBe(200);
expect(uploadRes.headers.get('content-disposition')).toBe('inline');
expect(Buffer.from(await uploadRes.arrayBuffer()).equals(uploadBytes)).toBe(true);
const imageRes = await fetch(`${base}/docs/image.png`);
expect(imageRes.status).toBe(200);
expect(imageRes.headers.get('content-disposition')).toBe('inline');
const imageGot = Buffer.from(await imageRes.arrayBuffer());
expect(imageGot.equals(pngBytes)).toBe(true);
const apiRes = await fetch(`${base}/api/nonexistent-endpoint`);
expect(apiRes.status).toBe(404);
expect(apiRes.headers.get('content-type')).toBe('application/problem+json');
const serverLockPath = resolve(projectDir, '.ok', 'local', 'server.lock');
expect(existsSync(serverLockPath)).toBe(true);
const lockRaw = await import('node:fs/promises').then((m) =>
m.readFile(serverLockPath, 'utf-8'),
);
const parsed = JSON.parse(lockRaw) as { port: number; capabilities?: string[] };
expect(parsed.port).toBe(booted.port);
expect(parsed.capabilities).toContain('ui');
} finally {
await booted.destroy();
}
});
});
describe('bootServer — MCP internal RPC stays loopback under a public externalUrl', () => {
const MCP_PROTOCOL_VERSION = '2025-06-18';
const UNREACHABLE_EXTERNAL_URL = 'https://prd-8062-unreachable.invalid';
async function mcpFetch(port: number, headers: Record<string, string>, body: unknown) {
return fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
'content-type': 'application/json',
...headers,
},
body: JSON.stringify(body),
});
}
test('MCP write succeeds when externalUrl is a public, non-loopback origin', async () => {
const projectDir = mkdtempSync(resolve(tmpDir, 'mcp-loopback-'));
seedOkScaffold(projectDir);
const config = ConfigSchema.parse({
server: { externalUrl: UNREACHABLE_EXTERNAL_URL, allowExternal: true },
});
expect(resolveServerRuntimeConfig(config).externalUrl).toBe(UNREACHABLE_EXTERNAL_URL);
const booted = await bootServer({
host: '127.0.0.1',
config,
projectDir,
contentDir: projectDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
try {
await booted.ready;
const port = booted.port;
const init = await mcpFetch(
port,
{},
{
jsonrpc: '2.0',
id: 1,
method: 'initialize',
params: {
protocolVersion: MCP_PROTOCOL_VERSION,
capabilities: {},
clientInfo: { name: 'prd-8062-test', version: '0.0.0' },
},
},
);
expect(init.status).toBe(200);
const sessionId = init.headers.get('mcp-session-id');
expect(sessionId).toBeTruthy();
const sessionHeaders = {
'mcp-session-id': sessionId as string,
'mcp-protocol-version': MCP_PROTOCOL_VERSION,
};
const initialized = await mcpFetch(port, sessionHeaders, {
jsonrpc: '2.0',
method: 'notifications/initialized',
});
expect(initialized.status).toBe(202);
const write = await mcpFetch(port, sessionHeaders, {
jsonrpc: '2.0',
id: 2,
method: 'tools/call',
params: {
name: 'write',
arguments: {
document: { path: 'prd-8062-note', content: '# PRD-8062\n\nLoopback write.\n' },
cwd: projectDir,
},
},
});
expect(write.status).toBe(200);
const body = (await write.json()) as {
result?: { isError?: boolean; content?: Array<{ text?: string }> };
error?: unknown;
};
expect(body.error).toBeUndefined();
const text = body.result?.content?.map((c) => c.text ?? '').join('') ?? '';
expect(body.result?.isError ?? false, `write returned an error: ${text}`).toBe(false);
} finally {
await booted.destroy();
}
});
});
describe('bootServer — ok.boot OTel span attributes', () => {
let exporter: InMemorySpanExporter | null = null;
let provider: BasicTracerProvider | null = null;
let savedDisableLocalSink: string | undefined;
beforeEach(() => {
trace.disable();
metrics.disable();
context.disable();
savedDisableLocalSink = process.env.OK_DISABLE_LOCAL_SINK;
process.env.OK_DISABLE_LOCAL_SINK = '1';
exporter = new InMemorySpanExporter();
provider = new BasicTracerProvider({
spanProcessors: [new SimpleSpanProcessor(exporter)],
});
trace.setGlobalTracerProvider(provider);
});
afterEach(async () => {
await shutdownTelemetry();
await provider?.shutdown();
trace.disable();
metrics.disable();
context.disable();
exporter = null;
provider = null;
if (savedDisableLocalSink === undefined) {
delete process.env.OK_DISABLE_LOCAL_SINK;
} else {
process.env.OK_DISABLE_LOCAL_SINK = savedDisableLocalSink;
}
});
test('main worktree: ok.boot span has worktree.kind=main', async () => {
const contentDir = mkdtempSync(resolve(tmpDir, 'span-main-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
seedOkScaffold(contentDir);
const booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
try {
const spans = exporter?.getFinishedSpans() ?? [];
const bootSpan = spans.find((s) => s.name === 'ok.boot');
expect(bootSpan).toBeDefined();
expect(bootSpan?.attributes['ok.worktree.kind']).toBe('main');
expect(typeof bootSpan?.attributes['ok.worktree.gitdir']).toBe('string');
const gitdirAttr = bootSpan?.attributes['ok.worktree.gitdir'] as string;
expect(gitdirAttr.split('/').filter(Boolean).length).toBeLessThanOrEqual(3);
} finally {
await booted.destroy();
}
});
test('linked worktree: ok.boot span has worktree.kind=linked', async () => {
const repoRoot = mkdtempSync(resolve(tmpDir, 'span-linked-repo-'));
await execFileAsync('git', ['init', '--initial-branch=main', repoRoot]);
configureTestGitRepository(repoRoot);
await execFileAsync('git', ['-C', repoRoot, 'config', 'user.email', '[email protected]']);
await execFileAsync('git', ['-C', repoRoot, 'config', 'user.name', 'Test']);
writeFileSync(resolve(repoRoot, 'README.md'), '# test\n');
await execFileAsync('git', ['-C', repoRoot, 'add', '.']);
await execFileAsync('git', ['-C', repoRoot, 'commit', '-m', 'init']);
const wtPath = mkdtempSync(resolve(tmpDir, 'span-linked-wt-'));
await rm(wtPath, { recursive: true, force: true });
await execFileAsync('git', [
'-C',
repoRoot,
'worktree',
'add',
'-b',
`wt-span-${Date.now()}`,
wtPath,
]);
seedOkScaffold(wtPath);
const booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: wtPath,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
try {
const spans = exporter?.getFinishedSpans() ?? [];
const bootSpan = spans.find((s) => s.name === 'ok.boot');
expect(bootSpan).toBeDefined();
expect(bootSpan?.attributes['ok.worktree.kind']).toBe('linked');
const gitdirAttr = bootSpan?.attributes['ok.worktree.gitdir'] as string;
expect(typeof gitdirAttr).toBe('string');
expect(gitdirAttr.split('/').filter(Boolean).length).toBeLessThanOrEqual(3);
} finally {
await booted.destroy();
}
});
test('boot failure (MissingOkConfigError): span still records the worktree kind', async () => {
const contentDir = mkdtempSync(resolve(tmpDir, 'span-fail-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
let caught: unknown;
try {
await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
const spans = exporter?.getFinishedSpans() ?? [];
const bootSpan = spans.find((s) => s.name === 'ok.boot');
expect(bootSpan).toBeDefined();
expect(bootSpan?.attributes['ok.worktree.kind']).toBe('main');
expect(bootSpan?.status.code).toBe(2);
});
test('cross-invocation: main first, linked second — kinds flip correctly with no state leakage', async () => {
const mainDir = mkdtempSync(resolve(tmpDir, 'flip-main-'));
await execFileAsync('git', ['init', '--initial-branch=main', mainDir]);
configureTestGitRepository(mainDir);
seedOkScaffold(mainDir);
const bootedMain = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: mainDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
await bootedMain.destroy();
const repoRoot = mkdtempSync(resolve(tmpDir, 'flip-linked-repo-'));
await execFileAsync('git', ['init', '--initial-branch=main', repoRoot]);
configureTestGitRepository(repoRoot);
await execFileAsync('git', ['-C', repoRoot, 'config', 'user.email', '[email protected]']);
await execFileAsync('git', ['-C', repoRoot, 'config', 'user.name', 'Test']);
writeFileSync(resolve(repoRoot, 'README.md'), '# test\n');
await execFileAsync('git', ['-C', repoRoot, 'add', '.']);
await execFileAsync('git', ['-C', repoRoot, 'commit', '-m', 'init']);
const wtPath = mkdtempSync(resolve(tmpDir, 'flip-linked-wt-'));
await rm(wtPath, { recursive: true, force: true });
await execFileAsync('git', [
'-C',
repoRoot,
'worktree',
'add',
'-b',
`wt-flip-${Date.now()}`,
wtPath,
]);
seedOkScaffold(wtPath);
const bootedLinked = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir: wtPath,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
await bootedLinked.destroy();
const spans = exporter?.getFinishedSpans() ?? [];
const bootSpans = spans.filter((s) => s.name === 'ok.boot');
expect(bootSpans.length).toBe(2);
expect(bootSpans[0]?.attributes['ok.worktree.kind']).toBe('main');
expect(bootSpans[1]?.attributes['ok.worktree.kind']).toBe('linked');
expect(bootSpans[0]?.attributes['ok.worktree.gitdir']).not.toBe(
bootSpans[1]?.attributes['ok.worktree.gitdir'],
);
});
test('OK_STARTUP_TRACEPARENT (valid): ok.boot joins the desktop-main launch trace', async () => {
const parentTraceId = '0af7651916cd43dd8448eb211c80319c';
const prev = process.env.OK_STARTUP_TRACEPARENT;
process.env.OK_STARTUP_TRACEPARENT = `00-${parentTraceId}-b7ad6b7169203331-01`;
context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
propagation.setGlobalPropagator(new W3CTraceContextPropagator());
const contentDir = mkdtempSync(resolve(tmpDir, 'traceparent-valid-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
seedOkScaffold(contentDir);
let booted: Awaited<ReturnType<typeof bootServer>> | null = null;
try {
booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
const bootSpan = (exporter?.getFinishedSpans() ?? []).find((s) => s.name === 'ok.boot');
expect(bootSpan).toBeDefined();
expect(bootSpan?.spanContext().traceId).toBe(parentTraceId);
} finally {
if (booted) await booted.destroy();
if (prev === undefined) delete process.env.OK_STARTUP_TRACEPARENT;
else process.env.OK_STARTUP_TRACEPARENT = prev;
}
});
test('OK_STARTUP_TRACEPARENT (malformed): boot still completes; ok.boot is a fresh root', async () => {
const prev = process.env.OK_STARTUP_TRACEPARENT;
process.env.OK_STARTUP_TRACEPARENT = 'not-a-valid-traceparent';
const contentDir = mkdtempSync(resolve(tmpDir, 'traceparent-malformed-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
seedOkScaffold(contentDir);
let booted: Awaited<ReturnType<typeof bootServer>> | null = null;
try {
booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
expect(booted.port).toBeGreaterThan(0);
const bootSpan = (exporter?.getFinishedSpans() ?? []).find((s) => s.name === 'ok.boot');
expect(bootSpan).toBeDefined();
expect(bootSpan?.spanContext().traceId).toMatch(/^[0-9a-f]{32}$/);
} finally {
if (booted) await booted.destroy();
if (prev === undefined) delete process.env.OK_STARTUP_TRACEPARENT;
else process.env.OK_STARTUP_TRACEPARENT = prev;
}
});
});
describe('bootServer — boot timings recorded end-to-end', () => {
test('a full boot populates httpListen / seedWalk / indexes / ready / fileCount', async () => {
const projectDir = mkdtempSync(resolve(tmpDir, 'boot-timings-e2e-'));
await execFileAsync('git', ['init', '--initial-branch=main', projectDir]);
configureTestGitRepository(projectDir);
seedOkScaffold(projectDir);
writeFileSync(resolve(projectDir, 'note.md'), '# note\n', 'utf-8');
const booted = await bootServer({
host: '127.0.0.1',
config: TEST_CONFIG,
projectDir,
contentDir: projectDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
try {
await booted.ready;
const timings = getBootTimings();
expect(timings).toBeDefined();
expect(typeof timings?.startedAt).toBe('string');
expect(typeof timings?.httpListenMs).toBe('number');
expect(typeof timings?.seedWalkMs).toBe('number');
expect(typeof timings?.indexesMs).toBe('number');
expect(typeof timings?.readyMs).toBe('number');
expect(typeof timings?.fileCount).toBe('number');
expect(timings?.fileCount).toBeGreaterThanOrEqual(1);
} finally {
await booted.destroy();
}
});
});
describe('parseKeepaliveConnectionId', () => {
test('returns null for undefined URL (defensive)', () => {
expect(parseKeepaliveConnectionId(undefined)).toBeNull();
});
test('returns null for empty URL', () => {
expect(parseKeepaliveConnectionId('')).toBeNull();
});
test('returns null when connectionId query param is absent', () => {
expect(parseKeepaliveConnectionId('/collab/keepalive?pid=1234')).toBeNull();
});
test('returns null when connectionId is present but empty', () => {
expect(parseKeepaliveConnectionId('/collab/keepalive?pid=1234&connectionId=')).toBeNull();
});
test('returns the connectionId when present (happy path)', () => {
expect(parseKeepaliveConnectionId('/collab/keepalive?pid=1234&connectionId=uuid-A')).toBe(
'uuid-A',
);
});
test('rejects percent-encoded connectionId values that decode to invalid chars', () => {
expect(
parseKeepaliveConnectionId('/collab/keepalive?connectionId=user%2Fagent%3D1%262'),
).toBeNull();
});
test('rejects connectionId containing CR/LF (log-injection defense)', () => {
expect(parseKeepaliveConnectionId('/collab/keepalive?connectionId=abc%0D%0Aadmin')).toBeNull();
});
test('tolerates query order', () => {
expect(parseKeepaliveConnectionId('/collab/keepalive?connectionId=foo&pid=1')).toBe('foo');
});
test('tolerates a UUID-shaped connectionId', () => {
expect(
parseKeepaliveConnectionId(
'/collab/keepalive?connectionId=abcdef12-3456-7890-abcd-ef1234567890',
),
).toBe('abcdef12-3456-7890-abcd-ef1234567890');
});
test('does not throw on a blatantly malformed URL', () => {
expect(() => parseKeepaliveConnectionId('?connectionId=foo')).not.toThrow();
expect(parseKeepaliveConnectionId('?connectionId=foo')).toBe('foo');
});
test('never throws on garbage input', () => {
expect(() => parseKeepaliveConnectionId('not a url at all')).not.toThrow();
expect(parseKeepaliveConnectionId('/collab/keepalive')).toBeNull();
});
});
describe('bootServer — exposure consent interlock', () => {
async function tryBoot(
server: Record<string, unknown>,
passServerRuntime = false,
): Promise<unknown> {
const contentDir = mkdtempSync(resolve(tmpDir, 'interlock-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
seedOkScaffold(contentDir);
const config = ConfigSchema.parse({ server });
try {
const booted = await bootServer({
host: '127.0.0.1',
config,
...(passServerRuntime ? { serverRuntime: resolveServerRuntimeConfig(config) } : {}),
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
await booted.destroy();
} catch (err) {
return err;
}
return null;
}
test('non-loopback bind without consent refuses to boot with the one-line fix', async () => {
const err = await tryBoot({ bind: ['127.0.0.1', '100.64.0.7'] });
expect(err).toBeInstanceOf(Error);
const e = err as Error;
expect(e.constructor.name).toBe('ExposureConsentError');
expect(e.message).toContain('would bind a non-loopback address');
expect(e.message).toContain('OK_ALLOW_EXTERNAL=1');
expect(e.message).toContain('.ok/local/config.yml');
});
test('a committed externalUrl under a loopback bind is inert — boots, no lockout (CLI path)', async () => {
const err = await tryBoot({ externalUrl: 'https://notes.example.com' }, true);
expect((err as Error | null)?.constructor.name).not.toBe('ExposureConsentError');
});
test('a committed externalUrl under a loopback bind is inert — boots on the desktop / embedder path too', async () => {
const err = await tryBoot({ externalUrl: 'https://notes.example.com' });
expect((err as Error | null)?.constructor.name).not.toBe('ExposureConsentError');
});
test('a loopback-only server with no externalUrl never trips the interlock', async () => {
const err = await tryBoot({});
expect((err as Error | null)?.constructor.name).not.toBe('ExposureConsentError');
});
test('an externalUrl + consent on a loopback bind boots outright', async () => {
const err = await tryBoot(
{ externalUrl: 'https://myproject.ngrok.app', allowExternal: true },
true,
);
expect(err).toBeNull();
});
test('an explicit (scope-correct) serverRuntime with consent admits a non-loopback bind', async () => {
const err = await tryBoot({ bind: ['127.0.0.1', '100.64.0.7'], allowExternal: true }, true);
expect((err as Error | null)?.constructor.name).not.toBe('ExposureConsentError');
});
test('config-derived allowExternal does NOT satisfy the interlock (desktop / embedder path)', async () => {
const err = await tryBoot({ bind: ['0.0.0.0'], allowExternal: true });
expect(err).toBeInstanceOf(Error);
expect((err as Error).constructor.name).toBe('ExposureConsentError');
});
test('a non-loopback host with no bind/serverRuntime still trips the interlock (single-file shape)', async () => {
const contentDir = mkdtempSync(resolve(tmpDir, 'interlock-host-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
seedOkScaffold(contentDir);
let err: unknown = null;
try {
const booted = await bootServer({
host: '0.0.0.0',
config: ConfigSchema.parse({}),
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
await booted.destroy();
} catch (e) {
err = e;
}
expect(err).toBeInstanceOf(Error);
expect((err as Error).constructor.name).toBe('ExposureConsentError');
expect((err as Error).message).toContain('0.0.0.0');
});
});
describe('bootServer — multi-address bind', () => {
test('every bind address answers on the same port; teardown closes all listeners', async () => {
const contentDir = mkdtempSync(resolve(tmpDir, 'multibind-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
seedOkScaffold(contentDir);
const booted = await bootServer({
host: '127.0.0.1',
bind: ['127.0.0.1', '::1'],
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
try {
expect(booted.port).toBeGreaterThan(0);
const v4 = await fetch(`http://127.0.0.1:${booted.port}/healthz`);
expect(v4.status).toBe(200);
const v6 = await fetch(`http://[::1]:${booted.port}/healthz`);
expect(v6.status).toBe(200);
} finally {
await booted.destroy();
}
await expect(fetch(`http://[::1]:${booted.port}/healthz`)).rejects.toThrow();
await expect(fetch(`http://127.0.0.1:${booted.port}/healthz`)).rejects.toThrow();
});
test('the listen record names the bound port, pid and every address, and agrees with the lock', async () => {
const contentDir = mkdtempSync(resolve(tmpDir, 'listenlog-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
seedOkScaffold(contentDir);
const entries: Array<{ fields: Record<string, unknown>; msg: string }> = [];
const noop = (): void => {};
const captureLogger = {
info: (fields: Record<string, unknown>, msg: string) => entries.push({ fields, msg }),
warn: noop,
error: noop,
debug: noop,
trace: noop,
fatal: noop,
level: 'info',
silent: noop,
bindings: () => ({}),
child: () => captureLogger,
};
const booted = await bootServer({
host: '127.0.0.1',
bind: ['127.0.0.1', '::1'],
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
log: captureLogger as never,
});
try {
const listened = entries.filter((e) => e.fields.event === 'server-listening');
expect(listened).toHaveLength(1);
const fields = listened[0]?.fields ?? {};
expect(fields.port).toBe(booted.port);
expect(fields.pid).toBe(process.pid);
expect(fields.addresses).toEqual(['127.0.0.1', '::1']);
expect(typeof fields.url).toBe('string');
expect(String(fields.url)).toContain(String(booted.port));
const lock = JSON.parse(
readFileSync(resolve(contentDir, OK_DIR, 'local', 'server.lock'), 'utf-8'),
) as { port: number };
expect(fields.port).toBe(lock.port);
} finally {
await booted.destroy();
}
});
test('duplicate bind entries collapse instead of failing with EADDRINUSE', async () => {
const contentDir = mkdtempSync(resolve(tmpDir, 'multibind-dup-'));
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
seedOkScaffold(contentDir);
const booted = await bootServer({
host: '127.0.0.1',
bind: ['127.0.0.1', '127.0.0.1'],
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
try {
const res = await fetch(`http://127.0.0.1:${booted.port}/healthz`);
expect(res.status).toBe(200);
} finally {
await booted.destroy();
}
});
});