Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { existsSync, mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { AutoStartDisabledError } from '../../autostart.ts';
import { resolveLockDir } from '../../config/paths.ts';
import { type Config, ConfigSchema } from '../../config/schema.ts';
import type { OffCwdResolverDeps } from '../../off-cwd-resolver.ts';
import { markServerLockDraining } from '../../server-lock.ts';
import { register } from './get-preview-url.ts';
import { bindTestServerLock, bindTestUiServerLock } from './preview-url-test-helpers.ts';
import type { ServerInstance } from './shared.ts';
beforeEach(() => {
vi.stubEnv('OK_CHANNEL', 'stable');
});
afterEach(() => {
vi.unstubAllEnvs();
});
const ownedDirectories: string[] = [];
function temporaryProject(prefix = 'ok-get-preview-url-'): string {
const dir = mkdtempSync(join(tmpdir(), prefix));
ownedDirectories.push(dir);
return dir;
}
afterEach(() => {
const owned = ownedDirectories.splice(0);
for (const dir of owned) rmSync(dir, { recursive: true, force: true });
for (const dir of owned) expect(existsSync(dir)).toBe(false);
});
const BASE_CONFIG: Config = ConfigSchema.parse({});
const CONFIG_AUTOOPEN_OFF: Config = ConfigSchema.parse({
appearance: { preview: { autoOpen: false } },
});
interface ToolResult {
content: Array<{ type: 'text'; text: string }>;
structuredContent?: Record<string, unknown>;
isError?: boolean;
}
type ToolHandler = (args: {
document?: string;
folder?: string;
skill?: { name: string; scope?: 'project' | 'global' };
file?: string;
cwd?: string;
}) => Promise<ToolResult>;
interface EnsureDeps {
serverUrl?: (cwd?: string) => Promise<string | undefined>;
uiBindWait?: { timeoutMs?: number; pollIntervalMs?: number };
offCwdResolverDeps?: OffCwdResolverDeps;
ensureSingleFileSession?: (absFile: string) => Promise<boolean>;
resolveUserAutoOpen?: () => boolean;
isHostedAgent?: boolean;
}
function captureRegistration(
cwd: string,
config: Config = BASE_CONFIG,
ensure?: EnsureDeps,
): ToolHandler {
let captured: ToolHandler | null = null;
const server = {
registerTool(_name: string, _config: unknown, handler: ToolHandler) {
captured = handler;
},
tool() {
throw new Error('legacy tool() should not be called by preview_url');
},
} as unknown as ServerInstance;
register(server, {
config,
resolveCwd: async () => cwd,
...ensure,
});
if (!captured) throw new Error('tool not registered');
return captured;
}
describe('preview_url tool — UI running', () => {
test('with document: composes baseUrl + the doc route', async () => {
const cwd = temporaryProject();
const uiBase = bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd);
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(true);
expect(result.structuredContent?.baseUrl).toBe(uiBase);
expect(result.structuredContent?.url).toBe(`${uiBase}/#/specs/foo/SPEC`);
expect(result.structuredContent?.autoOpen).toBe(true);
expect(result.content[0]?.text).toContain(`${uiBase}/#/specs/foo/SPEC`);
});
test('with folder: composes the folder route with a trailing slash', async () => {
const cwd = temporaryProject();
const uiBase = bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd);
const result = await handler({ folder: 'specs/foo' });
expect(result.structuredContent?.url).toBe(`${uiBase}/#/specs/foo/`);
});
test('folder route tolerates surrounding slashes and per-segment encodes', async () => {
const cwd = temporaryProject();
const uiBase = bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd);
const result = await handler({ folder: '/My Notes/sub/' });
expect(result.structuredContent?.url).toBe(`${uiBase}/#/My%20Notes/sub/`);
});
describe('isHostedAgent steer (desktop terminal or in-app agent panel)', () => {
test('document: response leads with `ok open <doc>` and tells the agent not to navigate the URL', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const result = await handler({ document: 'specs/foo/SPEC' });
const text = result.content[0]?.text ?? '';
expect(text).toContain('ok open specs/foo/SPEC');
expect(text).toMatch(/Don't navigate the URL|reference only/);
expect(result.structuredContent?.running).toBe(true);
expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo/SPEC');
});
test('document: steer tells the agent not to paste the URL into its reply', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.content[0]?.text ?? '').toContain('paste the URL into your reply');
});
test('folder: steers to `ok open <folder>`', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const result = await handler({ folder: 'specs/foo' });
expect(result.content[0]?.text ?? '').toContain('ok open specs/foo');
expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo');
});
test('skill default scope (project): steers to `ok open <name> --skill` (no --scope)', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const result = await handler({ skill: { name: 'trip-log' } });
expect(result.content[0]?.text ?? '').toContain('ok open trip-log --skill');
expect(result.content[0]?.text ?? '').not.toContain('--scope');
expect(result.structuredContent?.okOpenCommand).toBe('ok open trip-log --skill');
});
test('skill --scope global: steers to `ok open <name> --skill --scope global`', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const result = await handler({ skill: { name: 'trip-log', scope: 'global' } });
expect(result.content[0]?.text ?? '').toContain('ok open trip-log --skill --scope global');
expect(result.structuredContent?.okOpenCommand).toBe(
'ok open trip-log --skill --scope global',
);
});
test('no target (root): no steer — nothing to `ok open`', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const result = await handler({});
expect(result.content[0]?.text ?? '').not.toContain('ok open');
});
test('NOT a hosted agent (default): no steer — plain Preview URL', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd);
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.content[0]?.text ?? '').not.toContain('ok open');
expect(result.structuredContent?.okOpenCommand ?? null).toBeNull();
});
test('hosted agent + no UI running: steer + okOpenCommand still fire (ok open does not need the UI)', async () => {
const cwd = temporaryProject();
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.structuredContent?.running).toBe(false);
expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo/SPEC');
expect(result.content[0]?.text ?? '').toContain('ok open specs/foo/SPEC');
expect(result.content[0]?.text ?? '').toContain('paste the URL into your reply');
});
test('document with a space: okOpenCommand shell-quotes the path', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const result = await handler({ document: 'notes/My Doc' });
expect(result.structuredContent?.okOpenCommand).toBe("ok open 'notes/My Doc'");
});
test('document with an embedded single quote: okOpenCommand POSIX-escapes it', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const result = await handler({ document: "Q&A/what's new" });
expect(result.structuredContent?.okOpenCommand).toBe("ok open 'Q&A/what'\\''s new'");
});
test('hosted agent + no UI + folder: okOpenCommand still fires', async () => {
const cwd = temporaryProject();
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const result = await handler({ folder: 'specs/foo' });
expect(result.structuredContent?.running).toBe(false);
expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo');
});
});
test('docName + folder together is rejected (mutually exclusive)', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd);
const result = await handler({ document: 'specs/foo/SPEC', folder: 'specs/foo' });
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toContain('mutually exclusive');
});
test('without docName: returns the UI root URL', async () => {
const cwd = temporaryProject();
const uiBase = bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd);
const result = await handler({});
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(true);
expect(result.structuredContent?.url).toBe(uiBase);
expect(result.structuredContent?.baseUrl).toBe(uiBase);
expect(result.structuredContent?.autoOpen).toBe(true);
});
test('per-segment encodes docName when composing the URL', async () => {
const cwd = temporaryProject();
const uiBase = bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd);
const result = await handler({ document: 'notes/My Doc' });
expect(result.structuredContent?.url).toBe(`${uiBase}/#/notes/My%20Doc`);
});
});
describe('preview_url tool — skill target', () => {
test('with skill: composes the __skill__ route (default project scope)', async () => {
const cwd = temporaryProject();
const uiBase = bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd);
const result = await handler({ skill: { name: 'trip-log' } });
expect(result.structuredContent?.url).toBe(`${uiBase}/#/__skill__/project/trip-log`);
});
test('with skill + explicit global scope and a spaced name', async () => {
const cwd = temporaryProject();
const uiBase = bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd);
const result = await handler({ skill: { name: 'run tests', scope: 'global' } });
expect(result.structuredContent?.url).toBe(`${uiBase}/#/__skill__/global/run%20tests`);
});
test('skill + document together is rejected (mutually exclusive)', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd);
const result = await handler({ skill: { name: 'trip-log' }, document: 'specs/foo/SPEC' });
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toContain('mutually exclusive');
});
});
describe('preview_url tool — no UI running', () => {
test('returns running:false + the ok-start hint when nothing is running', async () => {
const cwd = temporaryProject();
const handler = captureRegistration(cwd);
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(false);
expect(result.structuredContent?.url).toBeNull();
expect(result.structuredContent?.baseUrl).toBeNull();
expect(result.structuredContent?.autoOpen).toBe(true);
expect(result.content[0]?.text).toContain('No OpenKnowledge server is running');
expect(result.content[0]?.text).toContain('`ok start`');
expect(result.content[0]?.text).not.toContain('`ok ui`');
});
test('no-UI branch is the same regardless of docName', async () => {
const cwd = temporaryProject();
const handler = captureRegistration(cwd);
const result = await handler({});
expect(result.structuredContent?.running).toBe(false);
expect(result.structuredContent?.url).toBeNull();
expect(result.structuredContent?.autoOpen).toBe(true);
});
test('draining ui-capable server: transient retry hint, no spawn advice', async () => {
const cwd = temporaryProject();
bindTestServerLock(cwd, 4321, ['http', 'ws', 'ui']);
markServerLockDraining(resolveLockDir(cwd));
const handler = captureRegistration(cwd);
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.structuredContent?.running).toBe(false);
expect(result.content[0]?.text).toContain('OK server is running');
expect(result.content[0]?.text).toContain('Retry in a few seconds');
expect(result.content[0]?.text).not.toContain('`ok start`');
});
test('--only server (capabilities omit ui): permanent hint, no "Retry" (UI never binds on its own)', async () => {
const cwd = temporaryProject();
bindTestServerLock(cwd, 4321, ['http', 'ws']);
const handler = captureRegistration(cwd);
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.structuredContent?.running).toBe(false);
expect(result.content[0]?.text).toContain('no preview UI is mounted');
expect(result.content[0]?.text).toContain('--only server');
expect(result.content[0]?.text).toContain('Restart it with plain `ok start`');
expect(result.content[0]?.text).not.toContain('`ok ui`');
expect(result.content[0]?.text).not.toContain('Retry');
});
test('ui-capable server.lock resolves directly (single-listener): running, own origin, no ui.lock needed', async () => {
const cwd = temporaryProject();
bindTestServerLock(cwd, 4321, ['http', 'ws', 'ui']);
const handler = captureRegistration(cwd);
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.structuredContent?.running).toBe(true);
expect(result.structuredContent?.url).toBe('http://localhost:4321/#/specs/foo/SPEC');
expect(result.content[0]?.text).not.toContain('no preview UI is mounted');
});
});
describe('preview_url tool — backend demand-ensure', () => {
test('cold project: ensure spawns the backend and the call returns a live URL', async () => {
const cwd = temporaryProject();
let resolverCalls = 0;
let uiBase = '';
const handler = captureRegistration(cwd, BASE_CONFIG, {
serverUrl: async () => {
resolverCalls += 1;
uiBase = bindTestUiServerLock(cwd, 4321);
return 'http://localhost:4321';
},
uiBindWait: { timeoutMs: 1500, pollIntervalMs: 10 },
});
const result = await handler({ document: 'specs/foo/SPEC' });
expect(resolverCalls).toBe(1);
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(true);
expect(result.structuredContent?.url).toBe(`${uiBase}/#/specs/foo/SPEC`);
});
test('resolver runs on every call, even with a live UI (orphan-heal contract)', async () => {
const cwd = temporaryProject();
const uiBase = bindTestUiServerLock(cwd);
let resolverCalls = 0;
const handler = captureRegistration(cwd, BASE_CONFIG, {
serverUrl: async () => {
resolverCalls += 1;
return 'http://localhost:4321';
},
});
const result = await handler({});
expect(resolverCalls).toBe(1);
expect(result.structuredContent?.running).toBe(true);
expect(result.structuredContent?.url).toBe(uiBase);
});
test('auto-start opt-out: soft not-running payload naming the knob', async () => {
const cwd = temporaryProject();
const handler = captureRegistration(cwd, BASE_CONFIG, {
serverUrl: async () => {
throw new AutoStartDisabledError(
'OpenKnowledge server is not running and OK_MCP_AUTOSTART=0 disables auto-start.',
);
},
});
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(false);
expect(result.structuredContent?.url).toBeNull();
expect(result.content[0]?.text).toContain('`ok start`');
expect(result.content[0]?.text).toContain('OK_MCP_AUTOSTART=0');
expect(result.content[0]?.text).not.toContain('`ok ui`');
});
test('spawn failure surfaces as a tool error carrying the resolver message', async () => {
const cwd = temporaryProject();
const handler = captureRegistration(cwd, BASE_CONFIG, {
serverUrl: async () => {
throw new Error('server did not start within 5000ms stderr:\nboom');
},
});
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toContain('did not start within');
});
test('fresh spawn that comes up draining: server-running retry hint after the bounded wait', async () => {
const cwd = temporaryProject();
const handler = captureRegistration(cwd, BASE_CONFIG, {
serverUrl: async () => {
bindTestServerLock(cwd, 4321, ['http', 'ws', 'ui']);
markServerLockDraining(resolveLockDir(cwd));
return 'http://localhost:4321';
},
uiBindWait: { timeoutMs: 60, pollIntervalMs: 10 },
});
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(false);
expect(result.content[0]?.text).toContain('OK server is running');
expect(result.content[0]?.text).toContain('Retry in a few seconds');
expect(result.content[0]?.text).not.toContain('`ok start`');
});
test('spawn failure during demand-ensure surfaces isError', async () => {
const cwd = temporaryProject();
const handler = captureRegistration(cwd, BASE_CONFIG, {
serverUrl: async () => {
throw new Error('spawn failed: ENOENT');
},
});
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.isError).toBe(true);
});
});
describe('preview_url tool — autoOpen field', () => {
test('echoes resolved autoOpen=false when the user has disabled it', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd, CONFIG_AUTOOPEN_OFF);
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(true);
expect(result.structuredContent?.autoOpen).toBe(false);
});
test('echoes autoOpen=false when no UI is running', async () => {
const cwd = temporaryProject();
const handler = captureRegistration(cwd, CONFIG_AUTOOPEN_OFF);
const result = await handler({});
expect(result.structuredContent?.running).toBe(false);
expect(result.structuredContent?.autoOpen).toBe(false);
});
test('reads config fresh per call (resolver invoked on every invocation)', async () => {
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
let currentAutoOpen = true;
const configResolver = async (): Promise<Config> =>
ConfigSchema.parse({ appearance: { preview: { autoOpen: currentAutoOpen } } });
let captured: ToolHandler | null = null;
const server = {
registerTool(_name: string, _config: unknown, handler: ToolHandler) {
captured = handler;
},
tool() {
throw new Error('legacy tool() should not be called by preview_url');
},
} as unknown as ServerInstance;
register(server, {
config: configResolver,
resolveCwd: async () => cwd,
});
if (!captured) throw new Error('tool not registered');
const handler = captured as ToolHandler;
const first = await handler({ document: 'foo' });
expect(first.structuredContent?.autoOpen).toBe(true);
currentAutoOpen = false;
const second = await handler({ document: 'foo' });
expect(second.structuredContent?.autoOpen).toBe(false);
});
});
describe('preview_url tool — error path', () => {
test('returns isError when resolveCwd rejects', async () => {
let captured: ToolHandler | undefined;
const server = {
registerTool(_name: string, _config: unknown, handler: ToolHandler) {
captured = handler;
},
tool() {
throw new Error('legacy tool() should not be called by preview_url');
},
} as unknown as ServerInstance;
register(server, {
config: BASE_CONFIG,
resolveCwd: async () => {
throw new Error('no roots configured');
},
});
if (!captured) throw new Error('tool not registered');
const result = await captured({ document: 'specs/foo/SPEC' });
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toContain('no roots configured');
});
});
function mockOffCwdDeps(
candidates: Array<{ contentDir: string; baseUrl: string; alive?: boolean }>,
): OffCwdResolverDeps {
const cands = candidates.map((c) => ({
lockDir: `${c.contentDir}/.ok/local`,
contentDir: c.contentDir,
baseUrl: c.baseUrl,
alive: c.alive ?? true,
}));
return {
discover: async () => cands.map((c) => c.lockDir),
inspect: async (d) => cands.find((c) => c.lockDir === d) ?? null,
realpath: async (p) => p,
};
}
describe('preview_url tool — file branch (out-of-project)', () => {
test('resolves a loose file to the session whose contentDir contains it', async () => {
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG, {
offCwdResolverDeps: mockOffCwdDeps([
{ contentDir: '/loose', baseUrl: 'http://localhost:6001' },
]),
resolveUserAutoOpen: () => true,
});
const result = await handler({ file: '/loose/notes.md' });
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(true);
expect(result.structuredContent?.baseUrl).toBe('http://localhost:6001');
expect(result.structuredContent?.url).toBe('http://localhost:6001/#/notes');
expect(result.structuredContent?.autoOpen).toBe(true);
});
test('no session for the file → running:false with an ok-open hint', async () => {
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG, {
offCwdResolverDeps: mockOffCwdDeps([]),
});
const result = await handler({ file: '/loose/notes.md' });
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(false);
expect(result.structuredContent?.url).toBeNull();
expect(result.content[0]?.text).toContain('ok open /loose/notes.md');
});
test('file is mutually exclusive with document', async () => {
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG, {
offCwdResolverDeps: mockOffCwdDeps([]),
});
const result = await handler({ file: '/loose/notes.md', document: 'specs/foo' });
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toContain('mutually exclusive');
});
});
describe('preview_url tool — file branch boot-on-demand', () => {
test('boots a session when none serves the file yet, then resolves its URL', async () => {
let candidate: { contentDir: string; baseUrl: string } | null = null;
const liveDeps: OffCwdResolverDeps = {
discover: async () => (candidate ? [`${candidate.contentDir}/.ok/local`] : []),
inspect: async () =>
candidate
? {
lockDir: `${candidate.contentDir}/.ok/local`,
contentDir: candidate.contentDir,
baseUrl: candidate.baseUrl,
alive: true,
}
: null,
realpath: async (p) => p,
};
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG, {
offCwdResolverDeps: liveDeps,
ensureSingleFileSession: async () => {
candidate = { contentDir: '/loose', baseUrl: 'http://localhost:6010' };
return true;
},
});
const result = await handler({ file: '/loose/new.md' });
expect(result.structuredContent?.running).toBe(true);
expect(result.structuredContent?.url).toBe('http://localhost:6010/#/new');
});
test('boot-on-demand that never registers → running:false + ok-open hint', async () => {
const empty: OffCwdResolverDeps = {
discover: async () => [],
inspect: async () => null,
realpath: async (p) => p,
};
let called = false;
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG, {
offCwdResolverDeps: empty,
ensureSingleFileSession: async () => {
called = true;
return false;
},
});
const result = await handler({ file: '/loose/x.md' });
expect(called).toBe(true);
expect(result.structuredContent?.running).toBe(false);
expect(result.content[0]?.text).toContain('ok open');
});
test('no ensureSingleFileSession dep (no spawn authority) → hint, no boot', async () => {
const empty: OffCwdResolverDeps = {
discover: async () => [],
inspect: async () => null,
realpath: async (p) => p,
};
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG, {
offCwdResolverDeps: empty,
});
const result = await handler({ file: '/loose/y.md' });
expect(result.structuredContent?.running).toBe(false);
expect(result.content[0]?.text).toContain('ok open');
});
test('ensureSingleFileSession rejection → running:false + hint (not a tool error)', async () => {
const empty: OffCwdResolverDeps = {
discover: async () => [],
inspect: async () => null,
realpath: async (p) => p,
};
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG, {
offCwdResolverDeps: empty,
ensureSingleFileSession: async () => {
throw new Error('spawn boom');
},
});
const result = await handler({ file: '/loose/z.md' });
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(false);
expect(result.content[0]?.text).toContain('ok open');
});
test('relative file path is rejected (must be absolute)', async () => {
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG);
const result = await handler({ file: 'notes.md' });
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toContain('absolute');
});
test('boot reports success but the session is not discoverable → falls back to the hint', async () => {
const empty: OffCwdResolverDeps = {
discover: async () => [],
inspect: async () => null,
realpath: async (p) => p,
};
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG, {
offCwdResolverDeps: empty,
ensureSingleFileSession: async () => true,
});
const result = await handler({ file: '/loose/gone.md' });
expect(result.isError).toBeUndefined();
expect(result.structuredContent?.running).toBe(false);
expect(result.content[0]?.text).toContain('ok open');
});
test('file branch honors a user-scoped autoOpen=false preference', async () => {
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG, {
offCwdResolverDeps: mockOffCwdDeps([
{ contentDir: '/loose', baseUrl: 'http://127.0.0.1:6020' },
]),
resolveUserAutoOpen: () => false,
});
const result = await handler({ file: '/loose/notes.md' });
expect(result.structuredContent?.running).toBe(true);
expect(result.structuredContent?.autoOpen).toBe(false);
});
});
describe('preview_url tool — names the running channel command', () => {
afterEach(() => {
vi.unstubAllEnvs();
});
test('a Beta hosted agent is steered to ok-beta open', async () => {
vi.stubEnv('OK_CHANNEL', 'beta');
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const handler = captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true });
const doc = await handler({ document: 'specs/foo/SPEC' });
expect(doc.structuredContent?.okOpenCommand).toBe('ok-beta open specs/foo/SPEC');
expect(doc.content[0]?.text ?? '').toContain('run `ok-beta open specs/foo/SPEC`');
const skill = await handler({ skill: { name: 'trip-log', scope: 'global' } });
expect(skill.structuredContent?.okOpenCommand).toBe(
'ok-beta open trip-log --skill --scope global',
);
});
test('a Beta server with nothing running says ok-beta start', async () => {
vi.stubEnv('OK_CHANNEL', 'beta');
const handler = captureRegistration(temporaryProject());
const result = await handler({ document: 'specs/foo/SPEC' });
expect(result.content[0]?.text).toContain('Start it with `ok-beta start`');
expect(result.content[0]?.text).not.toContain('`ok start`');
});
test('a Beta server without a mounted UI says ok-beta start', async () => {
vi.stubEnv('OK_CHANNEL', 'beta');
const cwd = temporaryProject();
bindTestServerLock(cwd, 4321, ['http', 'ws']);
const result = await captureRegistration(cwd)({ document: 'specs/foo/SPEC' });
expect(result.content[0]?.text).toContain('Restart it with plain `ok-beta start`');
});
test('a Beta loose file without a session says ok-beta open', async () => {
vi.stubEnv('OK_CHANNEL', 'beta');
const empty: OffCwdResolverDeps = {
discover: async () => [],
inspect: async () => null,
realpath: async (p) => p,
};
const handler = captureRegistration(temporaryProject('ok-pv-'), BASE_CONFIG, {
offCwdResolverDeps: empty,
});
const result = await handler({ file: '/loose/y.md' });
expect(result.content[0]?.text).toContain('`ok-beta open /loose/y.md` starts one');
});
test('Stable hints stay byte-identical', async () => {
vi.stubEnv('OK_CHANNEL', 'stable');
const cwd = temporaryProject();
bindTestUiServerLock(cwd);
const steered = await captureRegistration(cwd, BASE_CONFIG, { isHostedAgent: true })({
folder: 'specs/foo',
});
expect(steered.structuredContent?.okOpenCommand).toBe('ok open specs/foo');
const idle = await captureRegistration(temporaryProject())({ document: 'specs/foo/SPEC' });
expect(idle.content[0]?.text).toContain(
'No OpenKnowledge server is running for this project. Start it with `ok start` (also starts the preview UI), or open the project in OK Electron.',
);
});
});