Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import type { spawn as NativeSpawn } from 'node:child_process';
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
realpathSync,
rmSync,
symlinkSync,
writeFileSync,
} from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { request as httpRequest } from 'node:http';
import { tmpdir } from 'node:os';
import { basename, dirname, join, relative, resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { idleShutdownToMs } from '@inkeep/open-knowledge-core';
import { type Config, ConfigSchema } from '@inkeep/open-knowledge-server';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import {
type BootedStartServer,
bootStartServer,
deriveServerProcessTitle,
EphemeralProjectDirNotThrowawayError,
formatServerReuseNotice,
formatShutdownNotice,
isLoopbackHost,
isReapableEphemeralProjectDir,
isServerLockCollision,
OkDirMissingError,
parseExternalUrlFlag,
parseIdleShutdownFlag,
parseOnlyModule,
resolveBundledReactShellDir,
resolveHost,
resolveServerReuse,
resolveStartConfig,
resolveStartConsoleLevel,
resolveStartShellDir,
shouldOpenBrowser,
shouldWarnHostOverridesMultiBind,
startCommand,
tryDescribeLockCollision,
withEphemeralTempDirReap,
withIdleShutdownProcessExit,
} from './start.ts';
beforeEach(() => {
vi.stubEnv('OK_CHANNEL', 'stable');
});
afterEach(() => {
vi.unstubAllEnvs();
});
describe('resolveHost', () => {
test('falls back to HOST env when --bind is absent', () => {
expect(resolveHost({}, { HOST: '0.0.0.0' })).toBe('0.0.0.0');
});
test('falls back to DEFAULT_SERVER_HOST (numeric IPv4 loopback) when both flag and env are absent', () => {
expect(resolveHost({}, {})).toBe('127.0.0.1');
});
});
describe('parseExternalUrlFlag', () => {
test('accepts http and https origins (http covers tailnet/LAN deployments)', () => {
expect(parseExternalUrlFlag('https://kb.example.com')).toBe('https://kb.example.com');
expect(parseExternalUrlFlag('http://laptop.tail:55222')).toBe('http://laptop.tail:55222');
});
test('rejects garbage and non-http(s) schemes', () => {
expect(() => parseExternalUrlFlag('not a url')).toThrow(/not a valid URL/);
expect(() => parseExternalUrlFlag('ftp://kb.example.com')).toThrow(/http\(s\) origin/);
});
test('flag errors name the flag the user typed', () => {
expect(() => parseExternalUrlFlag('not a url')).toThrow(/--external-url/);
});
});
describe('formatShutdownNotice', () => {
test('SIGINT includes the headline, the wait notice, and the force-quit hint', () => {
const lines = formatShutdownNotice('SIGINT');
expect(lines[0]).toContain('Stopping OpenKnowledge');
expect(lines.some((l) => l.includes('few seconds'))).toBe(true);
expect(lines.some((l) => l.includes('force quit'))).toBe(true);
});
test('SIGTERM omits the force-quit hint (no interactive second-press path)', () => {
const lines = formatShutdownNotice('SIGTERM');
expect(lines[0]).toContain('Stopping OpenKnowledge');
expect(lines.some((l) => l.includes('few seconds'))).toBe(true);
expect(lines.some((l) => l.includes('force quit'))).toBe(false);
});
});
describe('resolveStartConsoleLevel', () => {
test('returns "warn" when no level is pinned (quiet terminal by default)', () => {
expect(resolveStartConsoleLevel({})).toBe('warn');
});
test('returns null (leave env untouched) when LOG_LEVEL is set', () => {
expect(resolveStartConsoleLevel({ LOG_LEVEL: 'info' })).toBeNull();
expect(resolveStartConsoleLevel({ LOG_LEVEL: 'debug' })).toBeNull();
});
test('returns null when OK_CONSOLE_LEVEL is already set', () => {
expect(resolveStartConsoleLevel({ OK_CONSOLE_LEVEL: 'info' })).toBeNull();
});
});
describe('deriveServerProcessTitle', () => {
test('returns "open-knowledge-server <basename>" for a typical project path', () => {
expect(deriveServerProcessTitle('/Users/alice/projects/my-notes')).toBe(
'open-knowledge-server my-notes',
);
});
test('strips non-printable bytes from the project name', () => {
expect(deriveServerProcessTitle('/path/to/bad\x07name\x7F')).toBe(
'open-knowledge-server badname',
);
});
test('falls back to "unknown" when basename is empty or all non-printable', () => {
expect(deriveServerProcessTitle('/')).toBe('open-knowledge-server unknown');
expect(deriveServerProcessTitle('/path/to/\x00\x01\x02')).toBe('open-knowledge-server unknown');
});
test('truncates long project names to keep ps lines readable', () => {
const longName = 'a'.repeat(200);
const result = deriveServerProcessTitle(`/parent/${longName}`);
expect(result.length).toBeLessThanOrEqual(86);
expect(result.startsWith('open-knowledge-server ')).toBe(true);
expect(result.length).toBe(22 + 64);
});
test('trims leading/trailing whitespace from the project name', () => {
expect(deriveServerProcessTitle('/parent/ leading-trailing ')).toBe(
'open-knowledge-server leading-trailing',
);
});
test('preserves typical kebab-case, snake_case, and dotted names', () => {
expect(deriveServerProcessTitle('/x/my-project')).toBe('open-knowledge-server my-project');
expect(deriveServerProcessTitle('/x/my_project')).toBe('open-knowledge-server my_project');
expect(deriveServerProcessTitle('/x/v1.2.3')).toBe('open-knowledge-server v1.2.3');
});
});
function makeTestConfig(): Config {
return ConfigSchema.parse({});
}
const TEST_HOST = '127.0.0.1';
function fetchText(
port: number,
path: string,
): Promise<{
status: number;
body: string;
headers: Record<string, string | string[] | undefined>;
}> {
return new Promise((resolveFetch, reject) => {
const req = httpRequest({ hostname: '127.0.0.1', port, path, method: 'GET' }, (res) => {
let body = '';
res.setEncoding('utf-8');
res.on('data', (chunk) => {
body += chunk;
});
res.on('end', () => {
resolveFetch({ status: res.statusCode ?? 0, body, headers: res.headers });
});
res.on('error', reject);
});
req.on('error', reject);
req.end();
});
}
function postJson(
port: number,
path: string,
payload: unknown,
): Promise<{ status: number; body: string }> {
const encoded = Buffer.from(JSON.stringify(payload), 'utf-8');
return new Promise((resolveFetch, reject) => {
const req = httpRequest(
{
hostname: '127.0.0.1',
port,
path,
method: 'POST',
headers: { 'content-type': 'application/json', 'content-length': encoded.length },
},
(res) => {
let body = '';
res.setEncoding('utf-8');
res.on('data', (chunk) => {
body += chunk;
});
res.on('end', () => {
resolveFetch({ status: res.statusCode ?? 0, body });
});
res.on('error', reject);
},
);
req.on('error', reject);
req.end(encoded);
});
}
describe('withIdleShutdownProcessExit (idle-path zombie prevention)', () => {
test('exits 0 after the handler completes, logging an open-handle summary', async () => {
const order: string[] = [];
const logged: object[] = [];
let exitCode: number | undefined;
const wrapped = withIdleShutdownProcessExit(
async () => {
order.push('handler');
},
{
log: {
info: (obj) => {
logged.push(obj);
},
error: () => {},
},
exit: (code) => {
order.push('exit');
exitCode = code;
},
getActiveHandles: () => [new (class Socket {})(), new (class Socket {})(), null],
},
);
await wrapped();
expect(order).toEqual(['handler', 'exit']);
expect(exitCode).toBe(0);
const event = logged.find((o) => (o as { event?: string }).event === 'idle-shutdown-exit') as
| { openHandles: Record<string, number> }
| undefined;
expect(event).toBeDefined();
expect(event?.openHandles.Socket).toBe(2);
});
test('reports handlesAvailable: false when the runtime cannot enumerate handles (Bun)', async () => {
const logged: object[] = [];
let exitCode: number | undefined;
const wrapped = withIdleShutdownProcessExit(async () => {}, {
log: {
info: (obj) => {
logged.push(obj);
},
error: () => {},
},
exit: (code) => {
exitCode = code;
},
getActiveHandles: () => null,
});
await wrapped();
expect(exitCode).toBe(0);
const event = logged.find((o) => (o as { event?: string }).event === 'idle-shutdown-exit') as
| { openHandles: Record<string, number>; handlesAvailable: boolean }
| undefined;
expect(event?.handlesAvailable).toBe(false);
expect(event?.openHandles).toEqual({});
});
test('exits 1 when the handler throws — a failed teardown must not zombify', async () => {
let exitCode: number | undefined;
const wrapped = withIdleShutdownProcessExit(
async () => {
throw new Error('destroy blew up');
},
{
exit: (code) => {
exitCode = code;
},
getActiveHandles: () => [],
},
);
await wrapped();
expect(exitCode).toBe(1);
});
});
describe('isServerLockCollision (D1/C3 gate)', () => {
test('same-project authority refusal is reusable before its discovery record appears', async () => {
const mod = await import('@inkeep/open-knowledge-server');
const fixture = mkdtempSync(join(tmpdir(), 'ok-reuse-authority-'));
const cwd = join(fixture, 'project');
const other = join(fixture, 'other-project');
const alias = join(fixture, 'alias');
mkdirSync(cwd);
mkdirSync(other);
symlinkSync(cwd, alias, 'junction');
const err = new mod.ServerAuthorityCollisionError({
projectDir: realpathSync.native(cwd),
scope: { kind: 'tree', path: cwd, excluded: [] },
pid: process.pid,
serverInstanceId: 'starting-holder',
});
try {
expect(isServerLockCollision(err, mod, cwd)).toBe(true);
expect(isServerLockCollision(err, mod, alias)).toBe(true);
expect(isServerLockCollision(err, mod, other)).toBe(false);
const preview = new mod.ServerAuthorityCollisionError({
...err.existing,
scope: { kind: 'file', path: join(cwd, 'note.md') },
});
expect(isServerLockCollision(preview, mod, cwd)).toBe(false);
} finally {
rmSync(fixture, { recursive: true, force: true });
}
});
class FakeServerLockErr extends Error {}
const fakeModule = {
ServerLockCollisionError: FakeServerLockErr,
} as unknown as typeof import('@inkeep/open-knowledge-server');
test('true for a ServerLockCollisionError instance', () => {
expect(isServerLockCollision(new FakeServerLockErr('held'), fakeModule, tmpdir())).toBe(true);
});
test('false for any other error', () => {
expect(isServerLockCollision(new Error('boom'), fakeModule, tmpdir())).toBe(false);
expect(isServerLockCollision('not-an-error', fakeModule, tmpdir())).toBe(false);
});
test('false (never throws) when the module lacks the class export', () => {
const empty = {} as unknown as typeof import('@inkeep/open-knowledge-server');
expect(isServerLockCollision(new Error('boom'), empty, tmpdir())).toBe(false);
});
});
describe('bootStartServer (integration)', () => {
let tmpDir: string;
let booted: BootedStartServer | null = null;
let originalHome: string | undefined;
beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-start-boot-'));
const okDir = resolve(tmpDir, '.ok');
mkdirSync(okDir, { recursive: true });
writeFileSync(resolve(okDir, 'config.yml'), '', 'utf-8');
writeFileSync(resolve(okDir, '.gitignore'), '', 'utf-8');
originalHome = process.env.HOME;
process.env.HOME = tmpDir;
booted = null;
});
afterEach(async () => {
if (booted) {
try {
await booted.destroy();
} catch {}
booted = null;
}
if (originalHome === undefined) {
delete process.env.HOME;
} else {
process.env.HOME = originalHome;
}
await rm(tmpDir, { recursive: true, force: true });
});
test('GET / returns 404 with React-UI-served-by-ok-ui pointer', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
const res = await fetchText(booted.port, '/');
expect(res.status).toBe(404);
expect(res.headers['content-type']).toContain('application/problem+json');
const body = JSON.parse(res.body);
expect(body.type).toBe('urn:ok:error:not-found');
expect(body.title).toBe('Not found.');
expect(body.status).toBe(404);
expect(body.detail).toContain('This server is running without the web UI');
expect(body.detail).toContain('/');
});
test('idleThresholdMs: null (--idle-shutdown off) threads through and boots (not the 30-min default)', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
idleThresholdMs: null,
});
expect(booted.port).toBeGreaterThan(0);
await booted.ready;
});
test('GET /assets/anything also returns the same pointer (no static fallthrough)', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
const res = await fetchText(booted.port, '/assets/main-abcdef.js');
expect(res.status).toBe(404);
const body = JSON.parse(res.body);
expect(body.type).toBe('urn:ok:error:not-found');
expect(body.title).toBe('Not found.');
expect(body.detail).toContain('This server is running without the web UI');
expect(body.detail).toContain('/assets/main-abcdef.js');
});
test('GET /api/document is routed through Hocuspocus onRequest (not the SPA pointer)', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
await booted.ready;
const res = await fetchText(booted.port, '/api/document?docName=integration-test-doc');
if (res.body.length > 0 && res.headers['content-type']?.toString().includes('json')) {
const parsed = (() => {
try {
return JSON.parse(res.body);
} catch {
return null;
}
})();
if (parsed && typeof parsed.error === 'string') {
expect(parsed.error).not.toContain('This server is running without the web UI');
}
}
expect(res.status).toBeGreaterThanOrEqual(200);
expect(res.status).toBeLessThan(600);
});
test('GET /api/nonexistent-route returns the API-route-not-found 404 (not the SPA pointer)', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
await booted.ready;
const res = await fetchText(booted.port, '/api/totally-nonexistent-xyz');
expect(res.status).toBe(404);
const body = JSON.parse(res.body);
expect(body.type).toBe('urn:ok:error:not-found');
expect(body.title).toBe('API endpoint not found.');
expect(body.status).toBe(404);
expect(typeof body.instance).toBe('string');
expect(body.detail).toContain('/api/totally-nonexistent-xyz');
});
test('destroy() is idempotent — second call is a no-op', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
await booted.destroy();
await expect(booted.destroy()).resolves.toBeUndefined();
booted = null;
});
test('booted.port reflects the kernel-assigned port (server.port=0)', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
expect(booted.port).toBeGreaterThan(0);
expect(booted.port).toBeLessThan(65536);
});
test('D-034: /collab/keepalive accepts a bare WS upgrade without routing to Hocuspocus', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
const ws = new WebSocket(`ws://127.0.0.1:${booted.port}/collab/keepalive?pid=${process.pid}`);
try {
await new Promise<void>((done, fail) => {
const onOpen = () => {
ws.removeEventListener('error', onError);
done();
};
const onError = () => {
ws.removeEventListener('open', onOpen);
fail(new Error('keepalive WS did not open'));
};
ws.addEventListener('open', onOpen, { once: true });
ws.addEventListener('error', onError, { once: true });
});
expect(ws.readyState).toBe(1);
await wait(100);
expect(ws.readyState).toBe(1);
} finally {
ws.close();
}
});
test('invokes repairMcpConfigsFn with the project cwd before bootServer', async () => {
const captured: { projectDir: string }[] = [];
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
repairMcpConfigsFn: (opts) => {
captured.push(opts as { projectDir: string });
return { outcomes: [], repairedCount: 0 };
},
});
expect(captured).toHaveLength(1);
expect(captured[0].projectDir).toBe(tmpDir);
});
test('warns about a sweep that detected a tamper it could not heal', async () => {
const warned: unknown[] = [];
const debugged: unknown[] = [];
const log = {
warn: (ctx: unknown) => warned.push(ctx),
debug: (ctx: unknown) => debugged.push(ctx),
info: () => {},
error: () => {},
child: () => log,
};
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
log: log as unknown as NonNullable<Parameters<typeof bootStartServer>[0]['log']>,
repairMcpConfigsFn: (opts) => {
opts.logger?.({ event: 'mcp-config-repair-prune-unchanged', severity: 'warn' });
opts.logger?.({ event: 'mcp-config-repair-declined', severity: 'warn' });
opts.logger?.({ event: 'mcp-config-repair-pruned', severity: 'info' });
opts.logger?.({ event: 'mcp-config-repair-something-new' });
return {
outcomes: [
{
scope: 'user',
editorId: 'claude',
configPath: '/home/x/.claude.json',
outcome: 'prune-unchanged',
},
{
scope: 'user',
editorId: 'codex',
configPath: '/home/x/.codex/config.toml',
outcome: 'declined',
reason: 'no-native-writer',
},
{
scope: 'user',
editorId: 'cursor',
configPath: '/home/x/.cursor/mcp.json',
outcome: 'canonical',
},
],
repairedCount: 0,
};
},
});
const warnedEvents = warned
.map((ctx) => (ctx as { event?: { event?: string } }).event?.event)
.filter((name): name is string => typeof name === 'string');
expect(warnedEvents).toEqual([
'mcp-config-repair-prune-unchanged',
'mcp-config-repair-declined',
'mcp-config-repair-something-new',
]);
expect(
debugged.some(
(ctx) =>
(ctx as { event?: { event?: string } }).event?.event === 'mcp-config-repair-pruned',
),
).toBe(true);
const unhealed = warned
.map((ctx) => (ctx as { unhealed?: unknown }).unhealed)
.find((value) => Array.isArray(value));
expect(unhealed).toEqual([
{
scope: 'user',
editorId: 'claude',
configPath: '/home/x/.claude.json',
outcome: 'prune-unchanged',
},
{
scope: 'user',
editorId: 'codex',
configPath: '/home/x/.codex/config.toml',
outcome: 'declined',
reason: 'no-native-writer',
},
]);
});
test('continues booting even when repairMcpConfigsFn throws', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
repairMcpConfigsFn: () => {
throw new Error('synthetic repair failure');
},
});
expect(booted.port).toBeGreaterThan(0);
});
test('the AI-tool connections batch reaches the CLI writers and probes injected at boot', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
const satisfierId = 'claude/mcp/project/config-entry';
const res = await postJson(booted.port, '/api/agent-integrations/apply', {
intents: [{ satisfierId, desired: 'present' }],
});
expect(res.status).toBe(200);
const body = JSON.parse(res.body) as {
actions: { satisfierId: string; action: string; errorId?: string }[];
snapshot: { probes: { satisfiers: Record<string, { state: string }> } };
};
const step = body.actions.find((action) => action.satisfierId === satisfierId);
expect(step?.action).toBe('written');
expect(step?.errorId).toBeUndefined();
expect(existsSync(resolve(tmpDir, '.mcp.json'))).toBe(true);
expect(body.snapshot.probes.satisfiers[satisfierId]?.state).toBe('satisfied');
});
test('invokes repairLaunchJsonFn with the project cwd before bootServer', async () => {
const captured: { projectDir: string }[] = [];
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
repairLaunchJsonFn: (opts) => {
captured.push(opts as { projectDir: string });
},
});
expect(captured).toHaveLength(1);
expect(captured[0].projectDir).toBe(tmpDir);
});
test('the real launch.json sweep logs a removal as routine, not as a problem', async () => {
const warned: unknown[] = [];
const debugged: unknown[] = [];
const log = {
warn: (ctx: unknown) => warned.push(ctx),
debug: (ctx: unknown) => debugged.push(ctx),
info: () => {},
error: () => {},
child: () => log,
};
mkdirSync(join(tmpDir, '.claude'), { recursive: true });
writeFileSync(
join(tmpDir, '.claude', 'launch.json'),
JSON.stringify(
{
configurations: [
{
name: 'open-knowledge-ui',
runtimeExecutable: '/bin/sh',
runtimeArgs: ['-l', '-c', '# ok-ui-v1\nexit 0'],
},
],
},
null,
2,
),
);
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
log: log as unknown as NonNullable<Parameters<typeof bootStartServer>[0]['log']>,
repairMcpConfigsFn: () => ({ outcomes: [], repairedCount: 0 }),
});
const eventNames = (list: unknown[]) =>
list
.map((ctx) => (ctx as { event?: { event?: string } }).event?.event)
.filter((name): name is string => typeof name === 'string');
expect(eventNames(debugged)).toContain('launch-json-repair-removed');
expect(eventNames(warned)).not.toContain('launch-json-repair-removed');
expect(
JSON.parse(readFileSync(join(tmpDir, '.claude', 'launch.json'), 'utf-8')).configurations,
).toEqual([]);
});
test('continues booting even when repairLaunchJsonFn throws', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
repairLaunchJsonFn: () => {
throw new Error('synthetic launch-json repair failure');
},
});
expect(booted.port).toBeGreaterThan(0);
});
test('writes no SKILL.md anywhere on boot', async () => {
const home = mkdtempSync(join(tmpdir(), 'ok-start-home-'));
const prevHome = process.env.HOME;
process.env.HOME = home;
try {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
await new Promise((r) => setTimeout(r, 0));
await new Promise((r) => setTimeout(r, 0));
const wrote: string[] = [];
const walk = (dir: string): void => {
for (const e of readdirSync(dir, { withFileTypes: true })) {
const p = join(dir, e.name);
if (e.isDirectory()) walk(p);
else if (e.name === 'SKILL.md') wrote.push(relative(home, p));
}
};
walk(home);
expect(wrote).toEqual([]);
expect(existsSync(join(tmpDir, '.claude', 'skills', 'open-knowledge', 'SKILL.md'))).toBe(
false,
);
} finally {
if (prevHome === undefined) delete process.env.HOME;
else process.env.HOME = prevHome;
rmSync(home, { recursive: true, force: true });
}
});
test('AC-C4: OK_RECLAIM_DISABLE=1 forwards reclaimDisableEnv to both sweep fns', async () => {
const prevEnv = process.env.OK_RECLAIM_DISABLE;
process.env.OK_RECLAIM_DISABLE = '1';
const mcpCaptures: Array<{ reclaimDisableEnv: string | null }> = [];
const launchCaptures: Array<{ reclaimDisableEnv: string | null }> = [];
try {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
repairMcpConfigsFn: (opts) => {
mcpCaptures.push(opts as { reclaimDisableEnv: string | null });
},
repairLaunchJsonFn: (opts) => {
launchCaptures.push(opts as { reclaimDisableEnv: string | null });
},
});
} finally {
if (prevEnv === undefined) delete process.env.OK_RECLAIM_DISABLE;
else process.env.OK_RECLAIM_DISABLE = prevEnv;
}
expect(mcpCaptures[0]?.reclaimDisableEnv).toBe('1');
expect(launchCaptures[0]?.reclaimDisableEnv).toBe('1');
});
test('default (no OK_RECLAIM_DISABLE) forwards reclaimDisableEnv=null to both sweeps', async () => {
const prevEnv = process.env.OK_RECLAIM_DISABLE;
delete process.env.OK_RECLAIM_DISABLE;
const captured: Array<{ reclaimDisableEnv: string | null }> = [];
try {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
repairMcpConfigsFn: (opts) => {
captured.push(opts as { reclaimDisableEnv: string | null });
},
repairLaunchJsonFn: (opts) => {
captured.push(opts as { reclaimDisableEnv: string | null });
},
});
} finally {
if (prevEnv !== undefined) process.env.OK_RECLAIM_DISABLE = prevEnv;
}
expect(captured).toHaveLength(2);
for (const c of captured) expect(c.reclaimDisableEnv).toBeNull();
});
test('default — content assets are served from the server origin', async () => {
const assetBytes = `fake-png-bytes-${Math.random()}`;
mkdirSync(join(tmpDir, 'specs', 'nested'), { recursive: true });
writeFileSync(join(tmpDir, 'specs', 'nested', 'mockup.png'), assetBytes, 'utf-8');
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
const res = await fetchText(booted.port, '/specs/nested/mockup.png');
expect(res.status).toBe(200);
expect(res.body).toBe(assetBytes);
const disposition = res.headers['content-disposition'];
expect(typeof disposition === 'string' ? disposition : '').toContain('inline');
});
test('serveContentAssets: false — content paths return the SPA-pointer 404', async () => {
writeFileSync(join(tmpDir, 'fixture-asset.png'), 'fake-png-bytes', 'utf-8');
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
serveContentAssets: false,
});
const res = await fetchText(booted.port, '/fixture-asset.png');
expect(res.status).toBe(404);
const body = JSON.parse(res.body);
expect(body.detail).toContain('This server is running without the web UI');
});
test('reactShellDistDir — server serves the shell on /', async () => {
const shellDir = await mkdtemp(resolve(tmpdir(), 'ok-start-shell-'));
const shellHtml = '<!doctype html><html><body>react-shell-test-sentinel</body></html>';
writeFileSync(join(shellDir, 'index.html'), shellHtml, 'utf-8');
const spawnCalls: Array<{ cmd: string }> = [];
const fakeSpawn: typeof NativeSpawn = ((cmd: string) => {
spawnCalls.push({ cmd });
return {
unref: () => {},
on: () => {},
kill: () => {},
} as unknown as ReturnType<typeof NativeSpawn>;
}) as never;
try {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
spawn: fakeSpawn,
reactShellDistDir: shellDir,
});
const rootRes = await fetchText(booted.port, '/');
expect(rootRes.status).toBe(200);
expect(rootRes.body).toContain('react-shell-test-sentinel');
const deepRes = await fetchText(booted.port, '/some/deep/route');
expect(deepRes.status).toBe(200);
expect(deepRes.body).toContain('react-shell-test-sentinel');
expect(spawnCalls.length).toBe(0);
const apiRes = await fetchText(booted.port, '/api/totally-nonexistent-xyz');
expect(apiRes.status).toBe(404);
const apiBody = JSON.parse(apiRes.body);
expect(apiBody.title).toBe('API endpoint not found.');
} finally {
await rm(shellDir, { recursive: true, force: true });
}
});
test('--serve-content-assets and --react-shell-dist-dir compose additively', async () => {
writeFileSync(join(tmpDir, 'fixture-image.png'), 'fake-png-bytes', 'utf-8');
const shellDir = await mkdtemp(resolve(tmpdir(), 'ok-start-shell-both-'));
writeFileSync(
join(shellDir, 'index.html'),
'<!doctype html><html><body>compose-test-sentinel</body></html>',
'utf-8',
);
try {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
serveContentAssets: true,
reactShellDistDir: shellDir,
});
const assetRes = await fetchText(booted.port, '/fixture-image.png');
expect(assetRes.status).toBe(200);
expect(assetRes.body).toBe('fake-png-bytes');
const rootRes = await fetchText(booted.port, '/');
expect(rootRes.status).toBe(200);
expect(rootRes.body).toContain('compose-test-sentinel');
} finally {
await rm(shellDir, { recursive: true, force: true });
}
});
test('--single-file with no projectDir self-provisions a throwaway root — cwd is never consumed', async () => {
const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
const sentinel = join(tmpDir, 'IMPORTANT.md');
writeFileSync(sentinel, 'keep me', 'utf-8');
try {
writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
singleFile: join(looseDir, 'note.md'),
});
await booted.ready;
const ephemeralRoot = dirname(dirname(booted.lockDir));
expect(ephemeralRoot).not.toBe(tmpDir);
expect(booted.lockDir.startsWith(tmpDir)).toBe(false);
expect(basename(ephemeralRoot).startsWith('ok-ephemeral-')).toBe(true);
expect(existsSync(join(ephemeralRoot, '.ok', 'config.yml'))).toBe(true);
await booted.destroy();
booted = null;
expect(existsSync(ephemeralRoot)).toBe(false);
expect(existsSync(sentinel)).toBe(true);
expect(existsSync(join(tmpDir, '.ok', 'config.yml'))).toBe(true);
} finally {
await rm(looseDir, { recursive: true, force: true });
}
});
test('--single-file ephemeral teardown records the signal that stopped it', async () => {
const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
const shutdownRecords: Array<Record<string, unknown>> = [];
const record = (data: unknown, message?: string): void => {
if (message?.includes('shutdown initiated') === true) {
shutdownRecords.push(data as Record<string, unknown>);
}
};
const log = {
info: record,
warn: record,
error: record,
debug: record,
trace: record,
fatal: record,
} as unknown as NonNullable<Parameters<typeof bootStartServer>[0]['log']>;
try {
writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
singleFile: join(looseDir, 'note.md'),
log,
});
await booted.ready;
await booted.destroy('external-signal', { signal: 'SIGINT' });
booted = null;
expect(shutdownRecords).toEqual([
expect.objectContaining({ reason: 'external-signal', signal: 'SIGINT' }),
]);
} finally {
await rm(looseDir, { recursive: true, force: true });
}
});
test('--single-file with a provided empty --project-dir seeds the synthesized config and boots', async () => {
const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
const providedDir = await mkdtemp(resolve(tmpdir(), 'ok-ephemeral-'));
try {
writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
singleFile: join(looseDir, 'note.md'),
projectDir: providedDir,
});
await booted.ready;
expect(existsSync(join(providedDir, '.ok', 'config.yml'))).toBe(true);
expect(existsSync(join(providedDir, '.ok', '.gitignore'))).toBe(true);
await booted.destroy();
booted = null;
expect(existsSync(providedDir)).toBe(true);
} finally {
await rm(looseDir, { recursive: true, force: true });
await rm(providedDir, { recursive: true, force: true });
}
});
test('--single-file with an ordinary bare --project-dir is refused, not seeded', async () => {
const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
const ordinaryDir = await mkdtemp(resolve(tmpdir(), 'ok-start-ordinary-'));
try {
writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
await expect(
bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
singleFile: join(looseDir, 'note.md'),
projectDir: ordinaryDir,
}),
).rejects.toThrow(EphemeralProjectDirNotThrowawayError);
expect(existsSync(join(ordinaryDir, '.ok'))).toBe(false);
} finally {
await rm(looseDir, { recursive: true, force: true });
await rm(ordinaryDir, { recursive: true, force: true });
}
});
test('--single-file with an initialized real project as --project-dir is refused untouched', async () => {
const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
const realProject = await mkdtemp(resolve(tmpdir(), 'ok-start-realproj-'));
try {
writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
mkdirSync(join(realProject, '.ok'), { recursive: true });
writeFileSync(join(realProject, '.ok', 'config.yml'), 'content:\n dir: .\n', 'utf-8');
writeFileSync(join(realProject, 'KEEP.md'), 'keep me', 'utf-8');
await expect(
bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
singleFile: join(looseDir, 'note.md'),
projectDir: realProject,
}),
).rejects.toThrow(EphemeralProjectDirNotThrowawayError);
expect(existsSync(join(realProject, 'KEEP.md'))).toBe(true);
expect(existsSync(join(realProject, '.ok', 'local'))).toBe(false);
} finally {
await rm(looseDir, { recursive: true, force: true });
await rm(realProject, { recursive: true, force: true });
}
});
test('boot failure after self-provisioning reaps the freshly created ephemeral dir', async () => {
const looseDir = await mkdtemp(resolve(tmpdir(), 'ok-start-loose-'));
const privateTmp = await mkdtemp(resolve(tmpdir(), 'ok-start-privtmp-'));
const prevTmpdirEnv = process.env.TMPDIR;
const { createServer } = await import('node:http');
const blocker = createServer(() => {});
await new Promise<void>((r) => blocker.listen(0, '127.0.0.1', () => r()));
const addr = blocker.address();
const blockedPort = typeof addr === 'object' && addr !== null ? addr.port : 0;
try {
writeFileSync(join(looseDir, 'note.md'), '# loose note\n', 'utf-8');
process.env.TMPDIR = privateTmp;
await expect(
bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
singleFile: join(looseDir, 'note.md'),
port: blockedPort,
}),
).rejects.toThrow();
expect(readdirSync(privateTmp).filter((n) => n.startsWith('ok-ephemeral-'))).toEqual([]);
} finally {
if (prevTmpdirEnv === undefined) delete process.env.TMPDIR;
else process.env.TMPDIR = prevTmpdirEnv;
await new Promise<void>((r) => blocker.close(() => r()));
await rm(looseDir, { recursive: true, force: true });
await rm(privateTmp, { recursive: true, force: true });
}
});
});
describe('bootStartServer — no auto git-init from ok start (US-004)', () => {
let tmpDir: string;
let booted: BootedStartServer | null = null;
let originalHome: string | undefined;
beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-start-git-'));
const okDir = resolve(tmpDir, '.ok');
mkdirSync(okDir, { recursive: true });
writeFileSync(resolve(okDir, 'config.yml'), '', 'utf-8');
writeFileSync(resolve(okDir, '.gitignore'), '', 'utf-8');
originalHome = process.env.HOME;
process.env.HOME = tmpDir;
booted = null;
});
afterEach(async () => {
if (booted) {
try {
await booted.destroy();
} catch {}
booted = null;
}
if (originalHome === undefined) {
delete process.env.HOME;
} else {
process.env.HOME = originalHome;
}
await rm(tmpDir, { recursive: true, force: true });
});
test('fresh tmpdir (no .git/) → ok start does NOT create .git/HEAD', async () => {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: false,
});
expect(existsSync(join(tmpDir, '.git/HEAD'))).toBe(false);
});
test('missing git binary does not prevent ok start from booting', async () => {
const originalPath = process.env.PATH;
process.env.PATH = '/nonexistent-path';
try {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: false,
});
await booted.ready;
expect(booted.degraded).toContain('shadow-repo');
} finally {
process.env.PATH = originalPath;
}
});
});
describe('bootStartServer — rejects with init-required when .ok/config.yml is absent', () => {
let tmpDir: string;
let originalHome: string | undefined;
beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-start-no-scaffold-'));
originalHome = process.env.HOME;
process.env.HOME = tmpDir;
});
afterEach(async () => {
if (originalHome === undefined) {
delete process.env.HOME;
} else {
process.env.HOME = originalHome;
}
await rm(tmpDir, { recursive: true, force: true });
});
test('fresh dir (no .ok/) → bootStartServer throws OkDirMissingError', async () => {
await expect(
bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: false,
}),
).rejects.toBeInstanceOf(OkDirMissingError);
});
test('fresh dir (no .ok/) → OkDirMissingError message contains "ok init"', async () => {
await expect(
bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: false,
}),
).rejects.toThrow('ok init');
expect(existsSync(join(tmpDir, '.ok'))).toBe(false);
});
test('fresh dir (no .ok/) → bootStartServer does not create config.yml', async () => {
await expect(
bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: false,
}),
).rejects.toBeInstanceOf(OkDirMissingError);
expect(existsSync(join(tmpDir, '.ok', 'config.yml'))).toBe(false);
});
test('bare .ok/ without config.yml is NOT a project root — bootStartServer still throws', async () => {
mkdirSync(join(tmpDir, '.ok'), { recursive: true });
await expect(
bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: false,
}),
).rejects.toBeInstanceOf(OkDirMissingError);
expect(existsSync(join(tmpDir, '.ok', 'config.yml'))).toBe(false);
});
test('skipAutoInit: true bypasses the CLI guard — server requires config.yml to be pre-seeded', async () => {
const okDir = join(tmpDir, '.ok');
mkdirSync(okDir, { recursive: true });
writeFileSync(join(okDir, 'config.yml'), '', 'utf-8');
writeFileSync(join(okDir, '.gitignore'), '', 'utf-8');
let booted: BootedStartServer | null = null;
try {
booted = await bootStartServer({
config: makeTestConfig(),
cwd: tmpDir,
host: TEST_HOST,
skipAutoInit: true,
});
expect(booted.port).toBeGreaterThan(0);
} finally {
if (booted) await booted.destroy();
}
});
});
describe('startCommand — --mode flag wiring', () => {
function fakeConfig() {
return makeTestConfig();
}
function quietCommand() {
const cmd = startCommand(fakeConfig);
cmd.exitOverride();
cmd.configureOutput({ writeOut: () => {}, writeErr: () => {} });
return cmd;
}
test('reports a preserved corrupt recovery snapshot without an unhandled startup stack', async () => {
const dir = mkdtempSync(join(tmpdir(), 'ok-start-corrupt-snapshot-'));
const snapshot = join(dir, '.ok', 'local', 'stale-external-writes.json');
mkdirSync(join(dir, '.ok', 'local'), { recursive: true });
writeFileSync(join(dir, '.ok', 'config.yml'), '');
writeFileSync(snapshot, '{protected edits, truncated');
const cwdSpy = vi.spyOn(process, 'cwd').mockReturnValue(dir);
const stderrSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
const exit = new Error('test process exit');
const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
throw exit;
});
const originalTitle = process.title;
try {
await expect(
quietCommand().parseAsync(['--mode', 'browser', '--only', 'server', '--no-open-browser'], {
from: 'user',
}),
).rejects.toBe(exit);
expect(exitSpy).toHaveBeenCalledWith(1);
const output = stderrSpy.mock.calls.flat().join('\n');
expect(output).toContain(snapshot);
expect(output).toContain('ok bug-report');
expect(output).not.toContain(' at ');
expect(readFileSync(snapshot, 'utf-8')).toBe('{protected edits, truncated');
} finally {
cwdSpy.mockRestore();
stderrSpy.mockRestore();
exitSpy.mockRestore();
process.title = originalTitle;
rmSync(dir, { recursive: true, force: true });
}
});
test('--mode <value> rejects values outside the browser|app enum (FR13)', () => {
const cmd = quietCommand();
expect(() => cmd.parse(['--mode', 'desktop'], { from: 'user' })).toThrow(
/--mode must be 'browser' or 'app'/,
);
});
test("--mode 'browser' parses successfully (no exit)", () => {
const cmd = quietCommand();
let helpDisplayed = false;
try {
cmd.parse(['--mode', 'browser', '--help'], { from: 'user' });
} catch (err) {
helpDisplayed = (err as { code?: string }).code === 'commander.helpDisplayed';
}
expect(helpDisplayed).toBe(true);
});
test('--mode=app with detection unavailable exits 1 + emits a contextual notFoundMessage (FR5)', async () => {
const previousForceBrowser = process.env.OK_FORCE_BROWSER;
process.env.OK_FORCE_BROWSER = '1';
const cmd = quietCommand();
let capturedExitCode: number | undefined;
let capturedStderr = '';
const originalExit = process.exit;
const originalConsoleError = console.error;
process.exit = ((code?: number) => {
capturedExitCode = code;
throw new Error('exit-stub');
}) as never;
console.error = (...args: unknown[]) => {
capturedStderr += `${args.map(String).join(' ')}\n`;
};
try {
await cmd.parseAsync(['--mode', 'app'], { from: 'user' });
} catch (err) {
if ((err as Error).message !== 'exit-stub') throw err;
} finally {
process.exit = originalExit;
console.error = originalConsoleError;
if (previousForceBrowser === undefined) {
delete process.env.OK_FORCE_BROWSER;
} else {
process.env.OK_FORCE_BROWSER = previousForceBrowser;
}
}
expect(capturedExitCode).toBe(1);
expect(capturedStderr).toContain('OK_FORCE_BROWSER');
expect(capturedStderr).toMatch(/disabled|unset/i);
expect(capturedStderr).not.toContain('not found');
});
});
describe('tryDescribeLockCollision', () => {
test('overlapping content ownership has an actionable message without a stack', async () => {
const serverModule = await import('@inkeep/open-knowledge-server');
const err = new serverModule.ServerAuthorityCollisionError({
projectDir: '/holder',
scope: { kind: 'tree', path: '/content', excluded: [] },
pid: process.pid,
serverInstanceId: 'holder-instance',
});
expect(tryDescribeLockCollision(err, '/other', serverModule)).toBe(err.message);
expect(err.message).toContain('Close that session');
});
test.runIf(process.platform !== 'win32' && process.getuid?.() !== 0)(
'a lock acquisition cannot read has its remedy as the message, without a stack',
async () => {
const serverModule = await import('@inkeep/open-knowledge-server');
const projectDir = await mkdtemp(join(tmpdir(), 'ok-start-unreadable-lock-'));
const lockDir = join(projectDir, '.ok', 'local');
const lockPath = join(lockDir, 'server.lock');
try {
mkdirSync(lockDir, { recursive: true });
writeFileSync(lockPath, '{}');
chmodSync(lockPath, 0o000);
const err = (() => {
try {
serverModule.acquireProcessLock({
lockName: 'server',
lockDir,
metadata: { port: 0, worktreeRoot: projectDir },
});
} catch (thrown) {
return thrown;
}
return undefined;
})();
expect(tryDescribeLockCollision(err, projectDir, serverModule)).toBe(
`[server-lock] Could not read the lock at ${lockPath}: EACCES: permission denied, open '${lockPath}'. Restore file and parent-directory access, then retry.`,
);
} finally {
chmodSync(lockPath, 0o600);
await rm(projectDir, { recursive: true, force: true });
}
},
);
function fakeServerModule(opts: {
meta?: { kind?: string; pid?: number; port?: number; hostname?: string } | null;
throwOnRead?: boolean;
}) {
class ServerLockCollisionError extends Error {}
return {
ServerLockCollisionError,
resolveLockDir: (projectDir: string) => join(projectDir, '.ok', 'local'),
readServerLock: () => {
if (opts.throwOnRead) throw new Error('synthetic read failure');
return opts.meta;
},
} as unknown as typeof import('@inkeep/open-knowledge-server');
}
test('non-lock-collision error → null (caller falls back to generic)', () => {
const fm = fakeServerModule({ meta: null });
const result = tryDescribeLockCollision(new TypeError('unrelated'), '/tmp', fm);
expect(result).toBeNull();
});
test("kind='interactive' → generic message (covers terminal AND desktop holders)", () => {
const fm = fakeServerModule({ meta: { kind: 'interactive', pid: 42, port: 3000 } });
const err = new fm.ServerLockCollisionError();
const result = tryDescribeLockCollision(err, '/tmp/proj', fm);
expect(result).toContain('already running');
expect(result).not.toContain('desktop');
});
test("kind='mcp-spawned' → MCP idle-shutdown message", () => {
const fm = fakeServerModule({ meta: { kind: 'mcp-spawned', pid: 99, port: 3001 } });
const err = new fm.ServerLockCollisionError();
const result = tryDescribeLockCollision(err, '/tmp/proj', fm);
expect(result).toContain('MCP-spawned');
expect(result).toContain('idle-shutdown');
});
test('meta returned but kind absent → generic already-running message', () => {
const fm = fakeServerModule({ meta: { pid: 1, port: 3000 } });
const err = new fm.ServerLockCollisionError();
const result = tryDescribeLockCollision(err, '/tmp/proj', fm);
expect(result).toContain('already running');
expect(result).toContain('ok status');
});
test('meta=null → generic already-running message', () => {
const fm = fakeServerModule({ meta: null });
const err = new fm.ServerLockCollisionError();
const result = tryDescribeLockCollision(err, '/tmp/proj', fm);
expect(result).toContain('already running');
});
test('readServerLock throws → null (defense in depth)', () => {
const fm = fakeServerModule({ throwOnRead: true });
const err = new fm.ServerLockCollisionError();
const result = tryDescribeLockCollision(err, '/tmp/proj', fm);
expect(result).toBeNull();
});
test('serverModule.ServerLockCollisionError missing → null (back-compat)', () => {
const fm = {
readServerLock: () => null,
} as unknown as typeof import('@inkeep/open-knowledge-server');
const err = new Error('any');
const result = tryDescribeLockCollision(err, '/tmp/proj', fm);
expect(result).toBeNull();
});
});
describe('resolveStartConfig (ephemeral config isolation)', () => {
test('single-file sessions drop the project config but keep the user-global layer', () => {
const projectConfig = ConfigSchema.parse({ server: { port: 4242 } });
const userConfig = ConfigSchema.parse({ server: { port: 5151 } });
const resolved = resolveStartConfig(projectConfig, '/tmp/note.md', () => userConfig);
expect(resolved.server?.port).toBe(5151);
expect(resolved).not.toBe(projectConfig);
});
test('plain ok start keeps the loaded project config untouched', () => {
const projectConfig = ConfigSchema.parse({ server: { port: 4242 } });
let userReads = 0;
const resolved = resolveStartConfig(projectConfig, undefined, () => {
userReads += 1;
return ConfigSchema.parse({});
});
expect(resolved).toBe(projectConfig);
expect(userReads).toBe(0);
});
});
describe('isReapableEphemeralProjectDir', () => {
test('accepts a direct ok-ephemeral-* child of os.tmpdir()', () => {
expect(isReapableEphemeralProjectDir(join(tmpdir(), 'ok-ephemeral-abc123'))).toBe(true);
});
test('rejects a dir outside the temp root, whatever its name', () => {
expect(isReapableEphemeralProjectDir('/Users/someone/my-project')).toBe(false);
});
test('rejects a temp-root child without the ok-ephemeral- prefix', () => {
expect(isReapableEphemeralProjectDir(join(tmpdir(), 'my-scratch-project'))).toBe(false);
});
test('rejects an ok-ephemeral-* dir nested deeper than the temp root', () => {
expect(isReapableEphemeralProjectDir(join(tmpdir(), 'nested', 'ok-ephemeral-x'))).toBe(false);
});
test('pierces temp-root symlinks via the injected realpath (macOS /tmp → /private/tmp)', () => {
const realpathFn = (p: string): string =>
p === '/tmp' || p.startsWith('/tmp/') ? p.replace(/^\/tmp/, '/private/tmp') : p;
expect(
isReapableEphemeralProjectDir('/tmp/ok-ephemeral-x', {
tmpdirFn: () => '/private/tmp',
realpathFn,
}),
).toBe(true);
});
test('resolves a symlink leaf: an ok-ephemeral-* link pointing elsewhere is refused', () => {
const targetDir = mkdtempSync(join(tmpdir(), 'ok-start-symtarget-'));
const link = join(tmpdir(), `ok-ephemeral-link-${basename(targetDir)}`);
symlinkSync(targetDir, link);
try {
expect(isReapableEphemeralProjectDir(link)).toBe(false);
} finally {
rmSync(link, { force: true });
rmSync(targetDir, { recursive: true, force: true });
}
});
test('accepts a real mkdtemp ok-ephemeral-* dir on this OS (symlinked temp prefix and all)', () => {
const real = mkdtempSync(join(tmpdir(), 'ok-ephemeral-'));
try {
expect(isReapableEphemeralProjectDir(real)).toBe(true);
} finally {
rmSync(real, { recursive: true, force: true });
}
});
});
describe('withEphemeralTempDirReap', () => {
const reapable = join(tmpdir(), 'ok-ephemeral-x');
test('runs the inner handler, then removes the temp projectDir', async () => {
const order: string[] = [];
const handler = async () => {
order.push('handler');
};
const removed: string[] = [];
const wrapped = withEphemeralTempDirReap(handler, reapable, async (dir) => {
order.push('rm');
removed.push(dir);
});
await wrapped();
expect(order).toEqual(['handler', 'rm']);
expect(removed).toEqual([reapable]);
});
test('swallows a rm failure (best-effort) — the handler still completes', async () => {
let handled = false;
const wrapped = withEphemeralTempDirReap(
async () => {
handled = true;
},
reapable,
async () => {
throw new Error('EBUSY');
},
);
await expect(wrapped()).resolves.toBeUndefined();
expect(handled).toBe(true);
});
test('reaps the temp dir even when the inner handler throws (finally)', async () => {
const removed: string[] = [];
const wrapped = withEphemeralTempDirReap(
async () => {
throw new Error('destroy failed');
},
reapable,
async (dir) => {
removed.push(dir);
},
);
await expect(wrapped()).rejects.toThrow('destroy failed');
expect(removed).toEqual([reapable]);
});
test('REFUSES to rm a non-throwaway target — the containment backstop', async () => {
const removed: string[] = [];
let handled = false;
const wrapped = withEphemeralTempDirReap(
async () => {
handled = true;
},
'/Users/someone/my-project',
async (dir) => {
removed.push(dir);
},
);
await wrapped();
expect(handled).toBe(true);
expect(removed).toEqual([]);
});
});
describe('resolveHost — --bind precedence', () => {
test('--bind wins over env', () => {
expect(resolveHost({ bind: ['0.0.0.0'] }, { HOST: '127.0.0.3' })).toBe('0.0.0.0');
});
test('empty bind list falls through to env', () => {
expect(resolveHost({ bind: [] }, { HOST: '127.0.0.2' })).toBe('127.0.0.2');
});
});
describe('parseOnlyModule', () => {
test('accepts server', () => {
expect(parseOnlyModule('server')).toBe('server');
});
test('rejects ui (retired with ui.lock) and anything else', () => {
expect(() => parseOnlyModule('ui')).toThrow(/--only must be/);
expect(() => parseOnlyModule('api')).toThrow(/--only must be/);
});
});
describe('resolveBundledReactShellDir (candidate-path probe)', () => {
test('returns the first candidate that exists', () => {
const dir = resolveBundledReactShellDir(() => true);
expect(dir).not.toBeUndefined();
expect(dir?.endsWith('public')).toBe(true);
});
test('returns undefined when no candidate exists (→ API/MCP-only degrade)', () => {
expect(resolveBundledReactShellDir(() => false)).toBeUndefined();
});
test('inside a packaged desktop app, serves the app window bundle beside app.asar', () => {
const present = new Set([
'/OK.app/Contents/Resources/app.asar',
'/OK.app/Contents/Resources/app',
]);
expect(
resolveBundledReactShellDir((p) => present.has(p), '/OK.app/Contents/Resources/cli/dist'),
).toBe('/OK.app/Contents/Resources/app');
});
test('outside a packaged desktop app, never serves a sibling app source dir', () => {
const present = new Set(['/repo/packages/app']);
expect(
resolveBundledReactShellDir((p) => present.has(p), '/repo/packages/cli/dist'),
).toBeUndefined();
});
});
describe('resolveStartShellDir (the Wave 3 default-flip decision)', () => {
const bundled = () => '/bundled/dist';
const noBundle = () => undefined;
test('default: resolves the bundled shell — the flip', () => {
expect(
resolveStartShellDir({
explicitDir: undefined,
only: undefined,
findBundledDir: bundled,
}),
).toEqual({ dir: '/bundled/dist', missingBundle: false });
});
test('explicit --react-shell-dist-dir always wins', () => {
expect(
resolveStartShellDir({
explicitDir: '/explicit',
only: undefined,
findBundledDir: noBundle,
}).dir,
).toBe('/explicit');
});
test('--only server opts out of the UI module entirely', () => {
expect(
resolveStartShellDir({
explicitDir: undefined,
only: 'server',
findBundledDir: bundled,
}),
).toEqual({ dir: undefined, missingBundle: false });
});
test('missing bundle degrades (API/MCP-only) and is flagged for the warning', () => {
expect(
resolveStartShellDir({
explicitDir: undefined,
only: undefined,
findBundledDir: noBundle,
}),
).toEqual({ dir: undefined, missingBundle: true });
});
});
describe('isLoopbackHost', () => {
test('loopback shapes', () => {
expect(isLoopbackHost('127.0.0.1')).toBe(true);
expect(isLoopbackHost('127.1.2.3')).toBe(true);
expect(isLoopbackHost('localhost')).toBe(true);
expect(isLoopbackHost('::1')).toBe(true);
expect(isLoopbackHost('[::1]')).toBe(true);
});
test('non-loopback shapes', () => {
expect(isLoopbackHost('0.0.0.0')).toBe(false);
expect(isLoopbackHost('::')).toBe(false);
expect(isLoopbackHost('192.168.1.5')).toBe(false);
});
});
describe('shouldOpenBrowser (interactive-loopback default open)', () => {
const base = {
openBrowser: true,
explicitOn: false,
host: '127.0.0.1',
isTTY: true,
ephemeral: false,
only: undefined,
servesUi: true,
} as const;
test('interactive loopback start serving the UI opens by default', () => {
expect(shouldOpenBrowser({ ...base })).toBe(true);
});
test('explicit openBrowser=true (config/env) lifts the loopback-bind condition', () => {
expect(shouldOpenBrowser({ ...base, host: '100.64.0.7', explicitOn: true })).toBe(true);
});
test('explicit openBrowser=true still never opens without a TTY (container safety)', () => {
expect(shouldOpenBrowser({ ...base, explicitOn: true, isTTY: false })).toBe(false);
});
test('--no-open-browser suppresses', () => {
expect(shouldOpenBrowser({ ...base, openBrowser: false })).toBe(false);
});
test('no TTY (spawned/CI) stays quiet', () => {
expect(shouldOpenBrowser({ ...base, isTTY: false })).toBe(false);
});
test('non-loopback bind stays quiet', () => {
expect(shouldOpenBrowser({ ...base, host: '0.0.0.0' })).toBe(false);
});
test('ephemeral single-file stays quiet (owns its own open flow)', () => {
expect(shouldOpenBrowser({ ...base, ephemeral: true })).toBe(false);
});
test('--only server stays quiet', () => {
expect(shouldOpenBrowser({ ...base, only: 'server' })).toBe(false);
});
test('a start that ended up serving no shell stays quiet', () => {
expect(shouldOpenBrowser({ ...base, servesUi: false })).toBe(false);
});
});
describe('resolveServerReuse (spawn-or-reuse)', () => {
const immediate = { now: () => 0, sleep: async () => {}, timeoutMs: 1000, pollIntervalMs: 10 };
test('ui-capable holder: reports the lock v2 url (the canonical one-URL contract)', async () => {
const info = await resolveServerReuse({
...immediate,
readServerLock: () => ({
pid: 42,
port: 24_550,
url: 'http://127.0.0.1:24550',
kind: 'interactive',
capabilities: ['http', 'ws', 'ui'],
}),
});
expect(info).toEqual({
url: 'http://127.0.0.1:24550',
kind: 'interactive',
pid: 42,
servesUi: true,
});
});
test('explicit no-ui holder (--only server): reports the server address, servesUi false', async () => {
const info = await resolveServerReuse({
...immediate,
readServerLock: () => ({
pid: 42,
port: 24_550,
url: 'http://127.0.0.1:24550',
capabilities: ['http', 'ws'],
}),
});
expect(info?.url).toBe('http://127.0.0.1:24550');
expect(info?.servesUi).toBe(false);
});
test('no ui anywhere: falls back to the server address', async () => {
const info = await resolveServerReuse({
...immediate,
readServerLock: () => ({ pid: 42, port: 24_550 }),
});
expect(info?.url).toBe('http://127.0.0.1:24550');
});
test('polls through the pre-listen port-0 sentinel to the bound port', async () => {
let clock = 0;
let reads = 0;
const info = await resolveServerReuse({
readServerLock: () => {
reads += 1;
return reads < 3
? { pid: 42, port: 0 }
: {
pid: 42,
port: 24_550,
url: 'http://127.0.0.1:24550',
capabilities: ['http', 'ws', 'ui'],
};
},
now: () => clock,
sleep: async (ms) => {
clock += ms;
},
timeoutMs: 1000,
pollIntervalMs: 10,
});
expect(info?.url).toBe('http://127.0.0.1:24550');
});
test('draining holder yields null (caller falls back to the error path)', async () => {
const info = await resolveServerReuse({
...immediate,
readServerLock: () => ({ pid: 42, port: 24_550, draining: true }),
});
expect(info).toBeNull();
});
test('sentinel that never binds times out to null', async () => {
let clock = 0;
const info = await resolveServerReuse({
readServerLock: () => ({ pid: 42, port: 0 }),
now: () => clock,
sleep: async (ms) => {
clock += ms;
},
timeoutMs: 100,
pollIntervalMs: 10,
});
expect(info).toBeNull();
});
test('missing lock yields null', async () => {
const info = await resolveServerReuse({
...immediate,
readServerLock: () => null,
});
expect(info).toBeNull();
});
});
describe('formatServerReuseNotice', () => {
test("kind='interactive' gets the neutral copy — it covers terminal AND desktop holders", () => {
const lines = formatServerReuseNotice({
url: 'http://127.0.0.1:1',
kind: 'interactive',
pid: 7,
servesUi: true,
});
expect(lines[0]).toContain('already running');
expect(lines[0]).not.toContain('desktop');
expect(lines.join('\n')).toContain('http://127.0.0.1:1');
});
test('names the mcp-spawned holder and the generic holder', () => {
expect(
formatServerReuseNotice({ url: 'u', kind: 'mcp-spawned', pid: 7, servesUi: true })[0],
).toContain('MCP-spawned');
expect(formatServerReuseNotice({ url: 'u', pid: 7, servesUi: false })[0]).toContain(
'already running',
);
});
});
describe('shouldWarnHostOverridesMultiBind', () => {
const base = { flagBindSet: false, okBindSet: false, hostEnvSet: true, fileBindCount: 2 };
test('warns when HOST alone drives the bind over a multi-element file list', () => {
expect(shouldWarnHostOverridesMultiBind(base)).toBe(true);
});
test('boundary: a single-element (or empty) file bind does NOT warn (> 1, not >= 1)', () => {
expect(shouldWarnHostOverridesMultiBind({ ...base, fileBindCount: 1 })).toBe(false);
expect(shouldWarnHostOverridesMultiBind({ ...base, fileBindCount: 0 })).toBe(false);
});
test('does not warn when a flag or OK_BIND is the bind source (HOST is not)', () => {
expect(shouldWarnHostOverridesMultiBind({ ...base, flagBindSet: true })).toBe(false);
expect(shouldWarnHostOverridesMultiBind({ ...base, okBindSet: true })).toBe(false);
});
test('does not warn when HOST is unset', () => {
expect(shouldWarnHostOverridesMultiBind({ ...base, hostEnvSet: false })).toBe(false);
});
});
describe('parseIdleShutdownFlag (--idle-shutdown, Table 3 semantics)', () => {
test("'off' is preserved as a string (idleShutdownToMs maps it to null)", () => {
expect(parseIdleShutdownFlag('off')).toBe('off');
expect(idleShutdownToMs(parseIdleShutdownFlag('off'))).toBeNull();
});
test('valid durations pass through as strings (converted to ms at the boundary)', () => {
expect(parseIdleShutdownFlag('90s')).toBe('90s');
expect(parseIdleShutdownFlag('30m')).toBe('30m');
expect(parseIdleShutdownFlag('2h')).toBe('2h');
expect(idleShutdownToMs(parseIdleShutdownFlag('90s'))).toBe(90_000);
expect(idleShutdownToMs(parseIdleShutdownFlag('2h'))).toBe(7_200_000);
});
test('rejects unitless, zero-led, and unknown-unit values', () => {
for (const bad of ['30', '0s', '05m', '1d', 'forever', '']) {
expect(() => parseIdleShutdownFlag(bad)).toThrow(/--idle-shutdown/);
}
});
});
describe('--idle-shutdown threading through Commander (regression)', () => {
async function captureParsedOpts(argv: string[]): Promise<Record<string, unknown>> {
const cmd = startCommand(() => makeTestConfig());
cmd.exitOverride();
cmd.configureOutput({ writeOut: () => {}, writeErr: () => {} });
let captured: Record<string, unknown> = {};
cmd.action((opts: Record<string, unknown>) => {
captured = opts;
});
await cmd.parseAsync(argv, { from: 'user' });
return captured;
}
test('--idle-shutdown off survives Commander and resolves to null (no idle shutdown)', async () => {
const opts = await captureParsedOpts(['--idle-shutdown', 'off']);
expect(opts.idleShutdown).toBe('off');
expect(idleShutdownToMs(opts.idleShutdown as string)).toBeNull();
});
test('--idle-shutdown 90s survives Commander and resolves to 90000 ms', async () => {
const opts = await captureParsedOpts(['--idle-shutdown', '90s']);
expect(opts.idleShutdown).toBe('90s');
expect(idleShutdownToMs(opts.idleShutdown as string)).toBe(90_000);
});
test('no --idle-shutdown flag leaves the value undefined (derived default applies)', async () => {
const opts = await captureParsedOpts([]);
expect(opts.idleShutdown).toBeUndefined();
});
});
describe('startCommand — flag-conflict guards (exit 2)', () => {
function quietCommand(config?: Config) {
const cmd = startCommand(() => config ?? makeTestConfig());
cmd.exitOverride();
cmd.configureOutput({ writeOut: () => {}, writeErr: () => {} });
return cmd;
}
async function captureGuard(
argv: string[],
config?: Config,
): Promise<{ code: number | undefined; stderr: string }> {
const cmd = quietCommand(config);
let code: number | undefined;
let stderr = '';
const originalExit = process.exit;
const originalWrite = process.stderr.write.bind(process.stderr);
process.exit = ((c?: number) => {
code = c;
throw new Error('exit-stub');
}) as never;
process.stderr.write = ((chunk: unknown) => {
stderr += String(chunk);
return true;
}) as never;
try {
await cmd.parseAsync(argv, { from: 'user' });
} catch (err) {
if ((err as Error).message !== 'exit-stub') throw err;
} finally {
process.exit = originalExit;
process.stderr.write = originalWrite;
}
return { code, stderr };
}
test('--only server + --react-shell-dist-dir exits 2', async () => {
const { code, stderr } = await captureGuard([
'--only',
'server',
'--react-shell-dist-dir',
'/tmp/shell',
]);
expect(code).toBe(2);
expect(stderr).toContain('--react-shell-dist-dir');
});
});
describe('start messages name the running channel command', () => {
afterEach(() => {
vi.unstubAllEnvs();
});
test('Stable keeps ok in the missing-setup error and the reuse notice', () => {
vi.stubEnv('OK_CHANNEL', 'stable');
expect(new OkDirMissingError('/p').message).toBe(
"This directory isn't set up yet. Run `ok init` first, then `ok start` again.",
);
expect(formatServerReuseNotice({ url: 'u', pid: 7, servesUi: true })[2]).toBe(
'Leaving it running — run `ok stop` first if you want a fresh server.',
);
});
test('Beta names ok-beta in the missing-setup error and the reuse notice', () => {
vi.stubEnv('OK_CHANNEL', 'beta');
expect(new OkDirMissingError('/p').message).toBe(
"This directory isn't set up yet. Run `ok-beta init` first, then `ok-beta start` again.",
);
expect(formatServerReuseNotice({ url: 'u', pid: 7, servesUi: true })[2]).toBe(
'Leaving it running — run `ok-beta stop` first if you want a fresh server.',
);
});
});