Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { setTimeout as wait } from 'node:timers/promises';
import type { HandoffOutcome, HandoffPayload, HandoffTarget } from '@inkeep/open-knowledge-core';
import {
composeTerminalBareLaunchPrompt,
OK_TERMINAL_SURFACE_PREAMBLE,
withSkillPointer,
} from '@inkeep/open-knowledge-core';
import { describe, expect, test, vi } from 'vitest';
import type {
HandoffDispatchDeps,
HandoffDispatchInput,
ToastAction,
ToastSurface,
} from './useHandoffDispatch';
function sampleInput(overrides: Partial<HandoffDispatchInput> = {}): HandoffDispatchInput {
return {
docContext: { relativePath: 'specs/foo/SPEC.md' },
projectDir: '/Users/andrew/Documents/code/open-knowledge',
docPath: '/Users/andrew/Documents/code/open-knowledge/specs/foo/SPEC.md',
...overrides,
};
}
interface ErrorToastCall {
readonly message: string;
readonly action?: ToastAction;
}
interface RecordingToast extends ToastSurface {
readonly successCalls: string[];
readonly errorCalls: ErrorToastCall[];
}
function recordingToast(): RecordingToast {
const successCalls: string[] = [];
const errorCalls: ErrorToastCall[] = [];
return {
successCalls,
errorCalls,
success(message) {
successCalls.push(message);
},
error(message, options) {
errorCalls.push({ message, action: options?.action });
},
};
}
function buildDeps(
overrides: Partial<HandoffDispatchDeps> = {},
): HandoffDispatchDeps & { toast: RecordingToast } {
const toast = recordingToast();
const defaults: HandoffDispatchDeps = {
dispatchHandoff: vi.fn(async (_payload: HandoffPayload) => ({ ok: true }) as HandoffOutcome),
recordHandoff: vi.fn(async (_line) => {}),
toast,
now: () => new Date('2026-04-22T03:00:00.000Z'),
isElectronHost: () => true,
getDisplayName: (target: HandoffTarget) =>
target === 'claude-cowork'
? 'Claude Cowork'
: target === 'claude-code'
? 'Claude'
: target === 'codex'
? 'Codex'
: 'Cursor',
ensureCoworkSkillInstalled: vi.fn(async () => ({ kind: 'already-installed' }) as const),
autoOpen: true,
};
return { ...defaults, ...overrides, toast };
}
describe('useHandoffDispatch module surface', () => {
test('exports the hook + helper + deps factory + copy helpers', async () => {
const mod = await import('./useHandoffDispatch');
expect(typeof mod.useHandoffDispatch).toBe('function');
expect(typeof mod.runHandoffDispatch).toBe('function');
expect(typeof mod.defaultHandoffDispatchDeps).toBe('function');
expect(typeof mod.successToastMessage).toBe('function');
expect(typeof mod.errorToastMessage).toBe('function');
expect(typeof mod.getDisplayNameDefault).toBe('function');
expect(typeof mod.isElectronHostDefault).toBe('function');
});
});
describe('successToastMessage / errorToastMessage — exact copy', () => {
test('success copy matches spec §5.1 E5a', async () => {
const { successToastMessage } = await import('./useHandoffDispatch');
expect(successToastMessage('Claude Cowork')).toBe('Opened in Claude Cowork.');
expect(successToastMessage('Codex')).toBe('Opened in Codex.');
});
test('error copy uses plain ASCII apostrophe + em-dash on first attempt', async () => {
const { errorToastMessage } = await import('./useHandoffDispatch');
expect(errorToastMessage('Cursor')).toBe("Couldn't reach Cursor — try again?");
expect(errorToastMessage('Cursor', 1)).toBe("Couldn't reach Cursor — try again?");
});
test('error copy escalates on attempt 2 (still-not-reached shape)', async () => {
const { errorToastMessage } = await import('./useHandoffDispatch');
expect(errorToastMessage('Cursor', 2)).toBe("Still couldn't reach Cursor — try one more time?");
});
test('error copy on final attempt omits the "try again?" question and names a retry delay', async () => {
const { errorToastMessage, MAX_DISPATCH_ATTEMPTS } = await import('./useHandoffDispatch');
expect(errorToastMessage('Cursor', MAX_DISPATCH_ATTEMPTS)).toBe(
"Couldn't reach Cursor — please try again later.",
);
});
test('retryActionLabel returns Retry / Try one more time / null across attempts', async () => {
const { retryActionLabel, MAX_DISPATCH_ATTEMPTS } = await import('./useHandoffDispatch');
expect(MAX_DISPATCH_ATTEMPTS).toBe(3);
expect(retryActionLabel(1)).toBe('Try again');
expect(retryActionLabel(2)).toBe('Try one more time');
expect(retryActionLabel(3)).toBeNull();
expect(retryActionLabel(4)).toBeNull();
});
});
describe('getDisplayNameDefault — KNOWN_TARGETS lookup', () => {
test('maps each v0 target id to its SPEC §7.2 display name', async () => {
const { getDisplayNameDefault } = await import('./useHandoffDispatch');
expect(getDisplayNameDefault('claude-cowork')).toBe('Claude Cowork');
expect(getDisplayNameDefault('claude-code')).toBe('Claude');
expect(getDisplayNameDefault('codex')).toBe('ChatGPT');
expect(getDisplayNameDefault('cursor')).toBe('Cursor');
});
test('falls back to target id for an unknown cast value', async () => {
const { getDisplayNameDefault } = await import('./useHandoffDispatch');
expect(getDisplayNameDefault('zed' as HandoffTarget)).toBe('zed');
});
});
describe('isElectronHostDefault — host classifier', () => {
test('returns false when no windowLike is supplied in a non-DOM context', async () => {
const { isElectronHostDefault } = await import('./useHandoffDispatch');
expect(isElectronHostDefault(undefined)).toBe(false);
});
test('returns false when okDesktop is absent', async () => {
const { isElectronHostDefault } = await import('./useHandoffDispatch');
expect(isElectronHostDefault({})).toBe(false);
});
test('returns true when okDesktop is any non-nullish value', async () => {
const { isElectronHostDefault } = await import('./useHandoffDispatch');
expect(isElectronHostDefault({ okDesktop: { shell: {} } })).toBe(true);
});
});
describe('runHandoffDispatch — success path', () => {
test('renders success toast and records one ok stats line', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps();
const input = sampleInput();
const outcome = await runHandoffDispatch('claude-cowork', input, deps);
expect(outcome).toEqual({ ok: true });
expect(deps.toast.successCalls).toEqual(['Opened in Claude Cowork.']);
expect(deps.toast.errorCalls).toEqual([]);
expect(deps.recordHandoff).toHaveBeenCalledTimes(1);
expect(deps.recordHandoff).toHaveBeenCalledWith({
target: 'claude-cowork',
host: 'electron',
outcome: 'ok',
ts: '2026-04-22T03:00:00.000Z',
});
});
test('passes a fully-formed HandoffPayload (target + paths + file prompt with autoOpen=true trailer) to dispatchHandoff', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps();
const input = sampleInput({
docContext: { relativePath: 'specs/2026-04-21-open-in-agent-desktop/SPEC.md' },
projectDir: '/tmp/demo-project',
docPath: '/tmp/demo-project/specs/2026-04-21-open-in-agent-desktop/SPEC.md',
});
await runHandoffDispatch('codex', input, deps);
expect(deps.dispatchHandoff).toHaveBeenCalledTimes(1);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.target).toBe('codex');
expect(payload.projectDir).toBe('/tmp/demo-project');
expect(payload.docPath).toBe(
'/tmp/demo-project/specs/2026-04-21-open-in-agent-desktop/SPEC.md',
);
expect(payload.prompt).toBe(
withSkillPointer(
"Let's work on `specs/2026-04-21-open-in-agent-desktop/SPEC.md` using OpenKnowledge. Open the OK editor in web view.",
),
);
});
test('records host="web" when isElectronHost() is false', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({ isElectronHost: () => false });
await runHandoffDispatch('codex', sampleInput(), deps);
expect(deps.recordHandoff).toHaveBeenCalledTimes(1);
expect(deps.recordHandoff).toHaveBeenCalledWith({
target: 'codex',
host: 'web',
outcome: 'ok',
ts: '2026-04-22T03:00:00.000Z',
});
});
test('project-scoped (docContext: null, no folderRelativePath) emits empty-space prompt + empty docPath', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const { composeEmptySpacePrompt } = await import('@inkeep/open-knowledge-core');
const deps = buildDeps();
const input: HandoffDispatchInput = {
docContext: null,
projectDir: '/Users/sarah/proj',
docPath: '',
};
await runHandoffDispatch('codex', input, deps);
expect(deps.dispatchHandoff).toHaveBeenCalledTimes(1);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.target).toBe('codex');
expect(payload.projectDir).toBe('/Users/sarah/proj');
expect(payload.docPath).toBe('');
expect(payload.prompt).toBe(withSkillPointer(composeEmptySpacePrompt(true)));
expect(payload.prompt).toBe(
withSkillPointer(
"Let's work on this project using OpenKnowledge. Open the OK editor in web view.",
),
);
});
test('folder-scoped (docContext: null, folderRelativePath set) emits folder prompt with autoOpen=true trailer', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const { composeFolderPrompt } = await import('@inkeep/open-knowledge-core');
const deps = buildDeps();
const input: HandoffDispatchInput = {
docContext: null,
folderRelativePath: 'specs/2026-05-16-sidebar-context-menus',
projectDir: '/Users/sarah/proj',
docPath: '',
};
await runHandoffDispatch('codex', input, deps);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.target).toBe('codex');
expect(payload.projectDir).toBe('/Users/sarah/proj');
expect(payload.docPath).toBe('');
expect(payload.prompt).toBe(
withSkillPointer(composeFolderPrompt('specs/2026-05-16-sidebar-context-menus', true)),
);
expect(payload.prompt).toBe(
withSkillPointer(
"Let's work on the `specs/2026-05-16-sidebar-context-menus` folder using OpenKnowledge. Open the OK editor in web view.",
),
);
});
});
describe('runHandoffDispatch — autoOpen=false honors the user preference', () => {
test('file scope: prompt drops the "Open the OK editor in web view." trailer when autoOpen=false', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({ autoOpen: false });
await runHandoffDispatch('codex', sampleInput(), deps);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.prompt).toBe(
withSkillPointer("Let's work on `specs/foo/SPEC.md` using OpenKnowledge."),
);
expect(payload.prompt).not.toContain('Open the OK editor');
});
test('folder scope: prompt drops the "Open the OK editor in web view." trailer when autoOpen=false', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({ autoOpen: false });
const input: HandoffDispatchInput = {
docContext: null,
folderRelativePath: 'specs/notes',
projectDir: '/Users/sarah/proj',
docPath: '',
};
await runHandoffDispatch('codex', input, deps);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.prompt).toBe(
withSkillPointer("Let's work on the `specs/notes` folder using OpenKnowledge."),
);
expect(payload.prompt).not.toContain('Open the OK editor');
});
test('empty-space scope: prompt drops the "Open the OK editor in web view." trailer when autoOpen=false', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({ autoOpen: false });
const input: HandoffDispatchInput = {
docContext: null,
projectDir: '/Users/sarah/proj',
docPath: '',
};
await runHandoffDispatch('codex', input, deps);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.prompt).toBe(
withSkillPointer("Let's work on this project using OpenKnowledge."),
);
expect(payload.prompt).not.toContain('Open the OK editor');
});
});
describe('runHandoffDispatch — failure path', () => {
test('renders error toast with Try again action and records error stats line', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({
dispatchHandoff: vi.fn(
async (_p: HandoffPayload) => ({ ok: false, reason: 'not-installed' }) as HandoffOutcome,
),
});
const outcome = await runHandoffDispatch('cursor', sampleInput(), deps);
expect(outcome).toEqual({ ok: false, reason: 'not-installed' });
expect(deps.toast.successCalls).toEqual([]);
expect(deps.toast.errorCalls).toHaveLength(1);
const errorCall = deps.toast.errorCalls[0];
expect(errorCall).toBeDefined();
if (!errorCall) throw new Error('unreachable');
expect(errorCall.message).toBe("Couldn't reach Cursor — try again?");
expect(errorCall.action?.label).toBe('Try again');
expect(typeof errorCall.action?.onClick).toBe('function');
expect(deps.recordHandoff).toHaveBeenCalledTimes(1);
expect(deps.recordHandoff).toHaveBeenCalledWith({
target: 'cursor',
host: 'electron',
outcome: 'error',
ts: '2026-04-22T03:00:00.000Z',
reason: 'not-installed',
});
});
test('retry action re-invokes dispatchHandoff with the same payload', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const dispatch = vi.fn(async (_p: HandoffPayload) => ({ ok: true }) as HandoffOutcome);
let firstCall = true;
(
dispatch as unknown as { mockImplementation: (fn: typeof dispatch) => void }
).mockImplementation?.((async (_p: HandoffPayload) => {
if (firstCall) {
firstCall = false;
return { ok: false, reason: 'not-installed' } as HandoffOutcome;
}
return { ok: true } as HandoffOutcome;
}) as typeof dispatch);
const deps = buildDeps({ dispatchHandoff: dispatch });
const input = sampleInput();
const first = await runHandoffDispatch('cursor', input, deps);
expect(first.ok).toBe(false);
expect(deps.recordHandoff).toHaveBeenCalledTimes(1);
const action = deps.toast.errorCalls[0]?.action;
expect(action).toBeDefined();
action?.onClick();
await wait(0);
expect(dispatch).toHaveBeenCalledTimes(2);
const firstPayload = (dispatch as ReturnType<typeof vi.fn>).mock
.calls[0]?.[0] as HandoffPayload;
const secondPayload = (dispatch as ReturnType<typeof vi.fn>).mock
.calls[1]?.[0] as HandoffPayload;
expect(secondPayload).toEqual(firstPayload);
expect(deps.recordHandoff).toHaveBeenCalledTimes(2);
expect(deps.toast.successCalls).toEqual(['Opened in Cursor.']);
});
test('third consecutive failure drops the Try again action (Review M5 bounded retry)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const dispatch = vi.fn(
async (_p: HandoffPayload) => ({ ok: false, reason: 'dispatch-error' }) as HandoffOutcome,
);
const deps = buildDeps({ dispatchHandoff: dispatch });
const input = sampleInput();
await runHandoffDispatch('cursor', input, deps);
expect(deps.toast.errorCalls).toHaveLength(1);
expect(deps.toast.errorCalls[0]?.message).toBe("Couldn't reach Cursor — try again?");
expect(deps.toast.errorCalls[0]?.action?.label).toBe('Try again');
const firstAction = deps.toast.errorCalls[0]?.action;
expect(firstAction).toBeDefined();
firstAction?.onClick();
await wait(0);
expect(deps.toast.errorCalls).toHaveLength(2);
expect(deps.toast.errorCalls[1]?.message).toBe(
"Still couldn't reach Cursor — try one more time?",
);
expect(deps.toast.errorCalls[1]?.action?.label).toBe('Try one more time');
const secondAction = deps.toast.errorCalls[1]?.action;
expect(secondAction).toBeDefined();
secondAction?.onClick();
await wait(0);
expect(deps.toast.errorCalls).toHaveLength(3);
expect(deps.toast.errorCalls[2]?.message).toBe(
"Couldn't reach Cursor — please try again later.",
);
expect(deps.toast.errorCalls[2]?.action).toBeUndefined();
expect(deps.recordHandoff).toHaveBeenCalledTimes(3);
expect(dispatch).toHaveBeenCalledTimes(3);
});
test('a superseded retry tells the user it was replaced without recording a second transport', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({
dispatchHandoff: vi.fn(
async () => ({ ok: false, reason: 'dispatch-error' }) as HandoffOutcome,
),
});
const retryDispatch = vi.fn(
async () => ({ ok: false, reason: 'superseded' }) as HandoffOutcome,
);
await runHandoffDispatch('cursor', sampleInput(), deps, 1, retryDispatch);
deps.toast.errorCalls[0]?.action?.onClick();
await vi.waitFor(() => expect(deps.toast.errorCalls).toHaveLength(2));
expect(deps.toast.errorCalls[1]?.message).toBe('A newer handoff replaced this retry.');
expect(deps.recordHandoff).toHaveBeenCalledTimes(1);
expect(deps.dispatchHandoff).toHaveBeenCalledTimes(1);
});
test('web-host-cursor-unsupported reason flows through to telemetry + toast', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({
dispatchHandoff: vi.fn(
async (_p: HandoffPayload) =>
({
ok: false,
reason: 'web-host-cursor-unsupported',
}) as HandoffOutcome,
),
isElectronHost: () => false,
});
await runHandoffDispatch('cursor', sampleInput(), deps);
expect(deps.recordHandoff).toHaveBeenCalledWith({
target: 'cursor',
host: 'web',
outcome: 'error',
ts: '2026-04-22T03:00:00.000Z',
reason: 'web-host-cursor-unsupported',
});
expect(deps.toast.errorCalls[0]?.message).toBe("Couldn't reach Cursor — try again?");
});
});
describe('defaultHandoffDispatchDeps — production wiring', () => {
test('returns a full deps object with every slot populated', async () => {
const { defaultHandoffDispatchDeps } = await import('./useHandoffDispatch');
const deps = defaultHandoffDispatchDeps();
expect(typeof deps.dispatchHandoff).toBe('function');
expect(typeof deps.recordHandoff).toBe('function');
expect(typeof deps.toast.success).toBe('function');
expect(typeof deps.toast.error).toBe('function');
expect(deps.now()).toBeInstanceOf(Date);
expect(typeof deps.isElectronHost()).toBe('boolean');
expect(deps.getDisplayName('claude-cowork')).toBe('Claude Cowork');
expect(typeof deps.ensureCoworkSkillInstalled).toBe('function');
expect(deps.autoOpen).toBe(true);
});
});
describe('runHandoffDispatch — Cowork install gate', () => {
test('first click + bridge ran: shows install toast and skips URL dispatch', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({
ensureCoworkSkillInstalled: vi.fn(
async () => ({ kind: 'installed-now', path: '/tmp/openknowledge.skill' }) as const,
),
});
const outcome = await runHandoffDispatch('claude-cowork', sampleInput(), deps);
expect(outcome).toEqual({ ok: true });
expect(deps.dispatchHandoff).not.toHaveBeenCalled();
expect(deps.recordHandoff).not.toHaveBeenCalled();
expect(deps.toast.successCalls).toEqual([
'OpenKnowledge skill saved. Upload it in Claude Desktop, then click Cowork again.',
]);
});
test('install-failed: surfaces error toast and returns dispatch-error outcome', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({
ensureCoworkSkillInstalled: vi.fn(
async () =>
({
kind: 'install-failed',
reason: 'open-failed',
message: 'Claude Desktop not found',
}) as const,
),
});
const outcome = await runHandoffDispatch('claude-cowork', sampleInput(), deps);
expect(outcome.ok).toBe(false);
if (!outcome.ok) {
expect(outcome.reason).toBe('dispatch-error');
expect(outcome.detail).toContain('install-failed');
}
expect(deps.dispatchHandoff).not.toHaveBeenCalled();
expect(deps.toast.errorCalls[0]?.message).toBe(
"Couldn't install OpenKnowledge skill — Claude Desktop not found",
);
});
test('already-installed: falls through to URL dispatch (default test path)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps();
await runHandoffDispatch('claude-cowork', sampleInput(), deps);
expect(deps.dispatchHandoff).toHaveBeenCalledTimes(1);
expect(deps.toast.successCalls).toEqual(['Opened in Claude Cowork.']);
});
test('host-unsupported (web): falls through to URL dispatch unchanged', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({
isElectronHost: () => false,
ensureCoworkSkillInstalled: vi.fn(async () => ({ kind: 'host-unsupported' }) as const),
});
await runHandoffDispatch('claude-cowork', sampleInput(), deps);
expect(deps.dispatchHandoff).toHaveBeenCalledTimes(1);
expect(deps.toast.successCalls).toEqual(['Opened in Claude Cowork.']);
});
test('non-Cowork target: install gate is never consulted', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const ensureSpy = vi.fn(async () => ({ kind: 'already-installed' }) as const);
const deps = buildDeps({ ensureCoworkSkillInstalled: ensureSpy });
await runHandoffDispatch('codex', sampleInput(), deps);
await runHandoffDispatch('claude-code', sampleInput(), deps);
await runHandoffDispatch('cursor', sampleInput(), deps);
expect(ensureSpy).not.toHaveBeenCalled();
});
test('retry attempt skips the install gate (only first attempt invokes it)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const ensureSpy = vi.fn(async () => ({ kind: 'already-installed' }) as const);
const deps = buildDeps({ ensureCoworkSkillInstalled: ensureSpy });
await runHandoffDispatch('claude-cowork', sampleInput(), deps, 2);
expect(ensureSpy).not.toHaveBeenCalled();
expect(deps.dispatchHandoff).toHaveBeenCalledTimes(1);
});
test('install gate throws: surfaces error toast + dispatch-error outcome (no unhandled rejection)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({
ensureCoworkSkillInstalled: vi.fn(async () => {
throw new Error('IPC channel closed');
}),
});
const outcome = await runHandoffDispatch('claude-cowork', sampleInput(), deps);
expect(outcome.ok).toBe(false);
if (!outcome.ok) {
expect(outcome.reason).toBe('dispatch-error');
expect(outcome.detail).toContain('install-error');
expect(outcome.detail).toContain('IPC channel closed');
}
expect(deps.dispatchHandoff).not.toHaveBeenCalled();
expect(deps.toast.errorCalls[0]?.message).toBe(
"Couldn't install OpenKnowledge skill — IPC channel closed",
);
});
});
describe('buildHandoffInput — shared surface helper (US-011)', () => {
test('null docName returns null', async () => {
const { buildHandoffInput } = await import('./useHandoffDispatch');
expect(
buildHandoffInput({
docName: null,
workspace: { contentDir: '/repo', pathSeparator: '/' },
}),
).toBeNull();
});
test('null workspace returns null', async () => {
const { buildHandoffInput } = await import('./useHandoffDispatch');
expect(buildHandoffInput({ docName: 'specs/foo/SPEC', workspace: null })).toBeNull();
});
test('POSIX: composes relativePath + projectDir + docPath', async () => {
const { buildHandoffInput } = await import('./useHandoffDispatch');
const input = buildHandoffInput({
docName: 'specs/foo/SPEC',
workspace: { contentDir: '/Users/andrew/repo', pathSeparator: '/' },
});
expect(input).toEqual({
docContext: { relativePath: 'specs/foo/SPEC.md' },
projectDir: '/Users/andrew/repo',
docPath: '/Users/andrew/repo/specs/foo/SPEC.md',
});
});
test('POSIX: preserves extension-qualified mdx relativePath + docPath', async () => {
const { buildHandoffInput } = await import('./useHandoffDispatch');
const input = buildHandoffInput({
docName: 'specs/foo/SPEC.mdx',
workspace: { contentDir: '/Users/andrew/repo', pathSeparator: '/' },
});
expect(input).toEqual({
docContext: { relativePath: 'specs/foo/SPEC.mdx' },
projectDir: '/Users/andrew/repo',
docPath: '/Users/andrew/repo/specs/foo/SPEC.mdx',
});
});
test('Windows: rewrites relativePath slashes to backslash for docPath', async () => {
const { buildHandoffInput } = await import('./useHandoffDispatch');
const input = buildHandoffInput({
docName: 'specs/foo/SPEC',
workspace: { contentDir: 'C:\\repo', pathSeparator: '\\' },
});
expect(input?.docContext.relativePath).toBe('specs/foo/SPEC.md');
expect(input?.projectDir).toBe('C:\\repo');
expect(input?.docPath).toBe('C:\\repo\\specs\\foo\\SPEC.md');
});
test('empty-string docName is treated as no active doc (null return)', async () => {
const { buildHandoffInput } = await import('./useHandoffDispatch');
expect(
buildHandoffInput({
docName: '',
workspace: { contentDir: '/repo', pathSeparator: '/' },
}),
).toBeNull();
});
});
describe('buildSkillHandoffInput + selectScopedPrompt — skill scope (author-with-AI)', () => {
test('null workspace or empty name returns null', async () => {
const { buildSkillHandoffInput } = await import('./useHandoffDispatch');
expect(
buildSkillHandoffInput({ skillName: 'x', scope: 'project', workspace: null }),
).toBeNull();
expect(
buildSkillHandoffInput({
skillName: '',
scope: 'project',
workspace: { contentDir: '/repo', pathSeparator: '/' },
}),
).toBeNull();
});
test('carries the skill name + scope; no doc path (agent reaches it via OK MCP)', async () => {
const { buildSkillHandoffInput } = await import('./useHandoffDispatch');
const input = buildSkillHandoffInput({
skillName: 'commit-helper',
scope: 'global',
workspace: { contentDir: '/Users/sarah/proj', pathSeparator: '/' },
});
expect(input).toEqual({
docContext: null,
skill: { name: 'commit-helper', scope: 'global' },
projectDir: '/Users/sarah/proj',
docPath: '',
});
});
test('selectScopedPrompt routes a skill input to composeSkillPrompt', async () => {
const { buildSkillHandoffInput, selectScopedPrompt } = await import('./useHandoffDispatch');
const input = buildSkillHandoffInput({
skillName: 'commit-helper',
scope: 'project',
workspace: { contentDir: '/repo', pathSeparator: '/' },
});
if (!input) throw new Error('expected a non-null skill input');
expect(selectScopedPrompt(input, 'claude-code', true, 'url')).toBe(
'Use your open-knowledge-write-skill skill to author the project Open Knowledge skill `commit-helper`. Edit it with the Open Knowledge tools. Open the OK editor in web view.',
);
});
});
describe('buildProjectScopedHandoffInput — empty-state cards helper', () => {
test('null workspace returns null (cards render disabled while resolving)', async () => {
const { buildProjectScopedHandoffInput } = await import('./useHandoffDispatch');
expect(buildProjectScopedHandoffInput({ workspace: null })).toBeNull();
});
test('returns docContext: null + empty docPath + projectDir from workspace', async () => {
const { buildProjectScopedHandoffInput } = await import('./useHandoffDispatch');
const input = buildProjectScopedHandoffInput({
workspace: { contentDir: '/Users/sarah/proj', pathSeparator: '/' },
});
expect(input).toEqual({
docContext: null,
projectDir: '/Users/sarah/proj',
docPath: '',
});
});
test('Windows: projectDir carries native backslash path verbatim', async () => {
const { buildProjectScopedHandoffInput } = await import('./useHandoffDispatch');
const input = buildProjectScopedHandoffInput({
workspace: { contentDir: 'C:\\Users\\sarah\\proj', pathSeparator: '\\' },
});
expect(input?.projectDir).toBe('C:\\Users\\sarah\\proj');
expect(input?.docPath).toBe('');
expect(input?.docContext).toBeNull();
});
});
describe('buildCreateHandoffInput — empty-state create-composer helper', () => {
test('null workspace returns null (composer dispatches disabled while resolving)', async () => {
const { buildCreateHandoffInput } = await import('./useHandoffDispatch');
expect(
buildCreateHandoffInput({
workspace: null,
description: 'a wiki',
scenario: 'new-project',
mentions: [],
}),
).toBeNull();
});
test('empty workspace.contentDir returns null (same falsy guard as siblings)', async () => {
const { buildCreateHandoffInput } = await import('./useHandoffDispatch');
expect(
buildCreateHandoffInput({
workspace: { contentDir: '', pathSeparator: '/' },
description: 'a wiki',
scenario: 'new-project',
mentions: [],
}),
).toBeNull();
});
test('carries the brief + scenario + mentions on the create-scope shape (docContext null, empty docPath)', async () => {
const { buildCreateHandoffInput } = await import('./useHandoffDispatch');
const input = buildCreateHandoffInput({
workspace: { contentDir: '/Users/sarah/proj', pathSeparator: '/' },
description: 'a research knowledge base',
scenario: 'existing-repo',
mentions: ['notes/a.md', 'glossary.md'],
});
expect(input).toEqual({
docContext: null,
createDescription: 'a research knowledge base',
createScenario: 'existing-repo',
createMentions: ['notes/a.md', 'glossary.md'],
projectDir: '/Users/sarah/proj',
docPath: '',
});
});
test('empty description is preserved verbatim (composer degrades it, not the builder)', async () => {
const { buildCreateHandoffInput } = await import('./useHandoffDispatch');
const input = buildCreateHandoffInput({
workspace: { contentDir: '/Users/sarah/proj', pathSeparator: '/' },
description: '',
scenario: 'new-project',
mentions: [],
});
expect(input?.createDescription).toBe('');
});
});
describe('buildFolderHandoffInput — folder-scoped helper (D23 / FR4 / FR14)', () => {
test('null workspace returns null (submenu renders disabled while resolving)', async () => {
const { buildFolderHandoffInput } = await import('./useHandoffDispatch');
expect(
buildFolderHandoffInput({
folderRelativePath: 'notes',
workspace: null,
}),
).toBeNull();
});
test('empty folderRelativePath returns null (renderer-bug short-circuit)', async () => {
const { buildFolderHandoffInput } = await import('./useHandoffDispatch');
expect(
buildFolderHandoffInput({
folderRelativePath: '',
workspace: { contentDir: '/Users/sarah/proj', pathSeparator: '/' },
}),
).toBeNull();
});
test('empty workspace.contentDir returns null (total-function ergonomics)', async () => {
const { buildFolderHandoffInput } = await import('./useHandoffDispatch');
expect(
buildFolderHandoffInput({
folderRelativePath: 'notes',
workspace: { contentDir: '', pathSeparator: '/' },
}),
).toBeNull();
});
test('POSIX: returns docContext: null + folderRelativePath + contentDir as projectDir', async () => {
const { buildFolderHandoffInput } = await import('./useHandoffDispatch');
const input = buildFolderHandoffInput({
folderRelativePath: 'specs/foo',
workspace: { contentDir: '/Users/sarah/proj', pathSeparator: '/' },
});
expect(input).toEqual({
docContext: null,
folderRelativePath: 'specs/foo',
projectDir: '/Users/sarah/proj',
docPath: '',
});
});
test('Windows: projectDir carries contentDir backslash path verbatim; folderRelativePath stays POSIX', async () => {
const { buildFolderHandoffInput } = await import('./useHandoffDispatch');
const input = buildFolderHandoffInput({
folderRelativePath: 'specs/foo',
workspace: { contentDir: 'C:\\Users\\sarah\\proj', pathSeparator: '\\' },
});
expect(input?.projectDir).toBe('C:\\Users\\sarah\\proj');
expect(input?.folderRelativePath).toBe('specs/foo');
expect(input?.docPath).toBe('');
expect(input?.docContext).toBeNull();
});
test('sibling shape parity with buildProjectScopedHandoffInput: same field set + same projectDir', async () => {
const { buildFolderHandoffInput, buildProjectScopedHandoffInput } = await import(
'./useHandoffDispatch'
);
const workspace = { contentDir: '/Users/sarah/proj', pathSeparator: '/' as const };
const project = buildProjectScopedHandoffInput({ workspace });
const folder = buildFolderHandoffInput({
folderRelativePath: 'notes',
workspace,
});
expect(project?.docContext).toBeNull();
expect(folder?.docContext).toBeNull();
expect(project?.docPath).toBe('');
expect(folder?.docPath).toBe('');
expect(project?.folderRelativePath).toBeUndefined();
expect(folder?.folderRelativePath).toBe('notes');
expect(project?.projectDir).toBe('/Users/sarah/proj');
expect(folder?.projectDir).toBe('/Users/sarah/proj');
});
});
describe('selectScopedPrompt — template selection across autoOpen modes', () => {
test('file scope (docContext set) returns composeFilePrompt(relativePath, autoOpen=true)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeFilePrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: { relativePath: 'notes/today.md' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
true,
'url',
);
expect(out).toBe(withSkillPointer(composeFilePrompt('notes/today.md', true)));
expect(out).toBe(
withSkillPointer(
"Let's work on `notes/today.md` using OpenKnowledge. Open the OK editor in web view.",
),
);
});
test('file scope (docContext set) drops the trailer when autoOpen=false', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const out = selectScopedPrompt(
{
docContext: { relativePath: 'notes/today.md' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
false,
'url',
);
expect(out).toBe(withSkillPointer("Let's work on `notes/today.md` using OpenKnowledge."));
});
test('folder scope (docContext null + folderRelativePath set) returns composeFolderPrompt with autoOpen=true trailer', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeFolderPrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: null,
folderRelativePath: 'notes',
projectDir: '/proj',
docPath: '',
},
'claude-code',
true,
'url',
);
expect(out).toBe(withSkillPointer(composeFolderPrompt('notes', true)));
expect(out).toBe(
withSkillPointer(
"Let's work on the `notes` folder using OpenKnowledge. Open the OK editor in web view.",
),
);
});
test('folder scope drops the trailer when autoOpen=false', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const out = selectScopedPrompt(
{
docContext: null,
folderRelativePath: 'notes',
projectDir: '/proj',
docPath: '',
},
'claude-code',
false,
'url',
);
expect(out).toBe(withSkillPointer("Let's work on the `notes` folder using OpenKnowledge."));
});
test('empty-space scope (both null/absent) returns composeEmptySpacePrompt(autoOpen=true)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeEmptySpacePrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: null,
projectDir: '/proj',
docPath: '',
},
'claude-code',
true,
'url',
);
expect(out).toBe(withSkillPointer(composeEmptySpacePrompt(true)));
expect(out).toBe(
withSkillPointer(
"Let's work on this project using OpenKnowledge. Open the OK editor in web view.",
),
);
});
test('empty-space scope drops the trailer when autoOpen=false', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const out = selectScopedPrompt(
{
docContext: null,
projectDir: '/proj',
docPath: '',
},
'claude-code',
false,
'url',
);
expect(out).toBe(withSkillPointer("Let's work on this project using OpenKnowledge."));
});
test('file scope threads the toolbar instruction into the directive prompt', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeFilePrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: { relativePath: 'notes/today.md' },
instruction: 'Tighten the intro',
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
true,
'url',
);
expect(out).toBe(
withSkillPointer(composeFilePrompt('notes/today.md', true, 'Tighten the intro')),
);
expect(out).toContain('Instruction:\n\n> Tighten the intro');
});
test('folder scope threads the toolbar instruction', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const out = selectScopedPrompt(
{
docContext: null,
folderRelativePath: 'notes',
instruction: 'Review the structure',
projectDir: '/proj',
docPath: '',
},
'claude-code',
true,
'url',
);
expect(out).toContain("Let's work on the `notes` folder using OpenKnowledge.");
expect(out).toContain('> Review the structure');
});
test('empty-space scope threads the toolbar instruction', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const out = selectScopedPrompt(
{
docContext: null,
instruction: 'Scaffold the wiki',
projectDir: '/proj',
docPath: '',
},
'claude-code',
true,
'url',
);
expect(out).toContain("Let's work on this project using OpenKnowledge.");
expect(out).toContain('> Scaffold the wiki');
});
test('selection scope ignores the top-level instruction — selection.instruction wins', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const out = selectScopedPrompt(
{
docContext: null,
instruction: 'top-level directive instruction',
selection: {
relativePath: 'notes/today.md',
instruction: 'selection instruction',
selectionMarkdown: 'the passage',
},
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
true,
'url',
);
expect(out).toContain('> selection instruction');
expect(out).not.toContain('top-level directive instruction');
});
test('create scope ignores the top-level instruction — createDescription is the only free-text', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const out = selectScopedPrompt(
{
docContext: null,
instruction: 'top-level directive instruction',
createDescription: 'a worldbuilding wiki',
createScenario: 'new-project',
projectDir: '/proj',
docPath: '',
},
'claude-code',
true,
'url',
);
expect(out).toContain('> a worldbuilding wiki');
expect(out).not.toContain('top-level directive instruction');
});
test('file scope threads the instruction even when autoOpen=false (trailer dropped, instruction kept)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const out = selectScopedPrompt(
{
docContext: { relativePath: 'notes/today.md' },
instruction: 'Fix the intro',
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
false,
'url',
);
expect(out).toContain('> Fix the intro');
expect(out).not.toContain('Open the OK editor');
});
test('create scope (createDescription set) returns composeCreatePrompt with the scenario', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeCreatePrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: null,
createDescription: 'a worldbuilding wiki',
createScenario: 'new-project',
projectDir: '/proj',
docPath: '',
},
'claude-code',
true,
'url',
);
expect(out).toBe(
withSkillPointer(composeCreatePrompt('a worldbuilding wiki', true, 'new-project', [])),
);
expect(out).toContain('> a worldbuilding wiki');
expect(out).toContain('Open the OK editor in web view.');
});
test('create scope threads createMentions into composeCreatePrompt', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeCreatePrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: null,
createDescription: 'a worldbuilding wiki',
createScenario: 'new-project',
createMentions: ['notes/lore.md', 'maps/world.md'],
projectDir: '/proj',
docPath: '',
},
'claude-code',
false,
'url',
);
expect(out).toBe(
withSkillPointer(
composeCreatePrompt('a worldbuilding wiki', false, 'new-project', [
'notes/lore.md',
'maps/world.md',
]),
),
);
expect(out).toContain('Also reference:\n\n@notes/lore.md\n@maps/world.md');
});
test('create scope threads existing-repo — no "new project" framing', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const out = selectScopedPrompt(
{
docContext: null,
createDescription: 'draft a spec for this codebase',
createScenario: 'existing-repo',
projectDir: '/proj',
docPath: '',
},
'claude-code',
true,
'url',
);
expect(out).not.toContain('new OpenKnowledge project');
expect(out).toContain('> draft a spec for this codebase');
});
test('create scope defaults to new-project when createScenario is absent', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeCreatePrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{ docContext: null, createDescription: 'a wiki', projectDir: '/proj', docPath: '' },
'claude-code',
false,
'url',
);
expect(out).toBe(withSkillPointer(composeCreatePrompt('a wiki', false, 'new-project', [])));
});
test('create scope with empty createDescription routes to the create composer, NOT empty-space', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeCreatePrompt, composeEmptySpacePrompt } = await import(
'@inkeep/open-knowledge-core'
);
const out = selectScopedPrompt(
{
docContext: null,
createDescription: '',
createScenario: 'new-project',
projectDir: '/proj',
docPath: '',
},
'claude-code',
true,
'url',
);
expect(out).toBe(withSkillPointer(composeCreatePrompt('', true, 'new-project', [])));
expect(out).not.toBe(withSkillPointer(composeEmptySpacePrompt(true)));
});
test('precedence: docContext beats folderRelativePath when both are set (defensive ordering)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeFilePrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: { relativePath: 'a.md' },
folderRelativePath: 'folder',
projectDir: '/proj',
docPath: '/proj/a.md',
},
'claude-code',
true,
'url',
);
expect(out).toBe(withSkillPointer(composeFilePrompt('a.md', true)));
});
test('selection scope (selection set) returns composeSelectionPrompt for the target', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeSelectionPrompt } = await import('@inkeep/open-knowledge-core');
const selection = {
relativePath: 'notes/today.md',
instruction: 'tighten this',
selectionMarkdown: 'A wordy sentence that could be shorter.',
};
const out = selectScopedPrompt(
{
docContext: null,
selection,
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'cursor',
true,
'url',
);
expect(out).toBe(composeSelectionPrompt({ ...selection, target: 'cursor' }));
});
test('the standing skill pointer rides every directive scope but NOT selection', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { OK_PROJECT_SKILL_POINTER } = await import('@inkeep/open-knowledge-core');
const base = { projectDir: '/proj', docPath: '' } as const;
const file = selectScopedPrompt(
{ ...base, docContext: { relativePath: 'a.md' }, docPath: '/proj/a.md' },
'claude-code',
true,
'url',
);
const folder = selectScopedPrompt(
{ ...base, docContext: null, folderRelativePath: 'specs' },
'claude-code',
true,
'url',
);
const empty = selectScopedPrompt({ ...base, docContext: null }, 'claude-code', true, 'url');
const create = selectScopedPrompt(
{ ...base, docContext: null, createDescription: 'a wiki' },
'claude-code',
true,
'url',
);
const selection = selectScopedPrompt(
{
...base,
docContext: null,
selection: { relativePath: 'a.md', instruction: 'x', selectionMarkdown: 'y' },
},
'claude-code',
true,
'url',
);
for (const prompt of [file, folder, empty, create]) {
expect(prompt.startsWith(OK_PROJECT_SKILL_POINTER)).toBe(true);
}
expect(selection).not.toContain(OK_PROJECT_SKILL_POINTER);
});
test('precedence: selection beats docContext when both are set (defensive ordering)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeSelectionPrompt } = await import('@inkeep/open-knowledge-core');
const selection = {
relativePath: 'a.md',
instruction: '',
selectionMarkdown: 'passage',
};
const out = selectScopedPrompt(
{
docContext: { relativePath: 'a.md' },
selection,
projectDir: '/proj',
docPath: '/proj/a.md',
},
'claude-code',
true,
'url',
);
expect(out).toBe(composeSelectionPrompt({ ...selection, target: 'claude-code' }));
});
});
describe('buildSelectionHandoffInput — selection-scoped helper', () => {
test('null docName returns null', async () => {
const { buildSelectionHandoffInput } = await import('./useHandoffDispatch');
expect(
buildSelectionHandoffInput({
docName: null,
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'rewrite',
selectionMarkdown: 'passage',
}),
).toBeNull();
});
test('null workspace returns null', async () => {
const { buildSelectionHandoffInput } = await import('./useHandoffDispatch');
expect(
buildSelectionHandoffInput({
docName: 'notes/today',
workspace: null,
instruction: 'rewrite',
selectionMarkdown: 'passage',
}),
).toBeNull();
});
test('empty selectionMarkdown returns null (renderer-bug short-circuit)', async () => {
const { buildSelectionHandoffInput } = await import('./useHandoffDispatch');
expect(
buildSelectionHandoffInput({
docName: 'notes/today',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'rewrite',
selectionMarkdown: '',
}),
).toBeNull();
});
test('POSIX: composes the selection payload + projectDir + absolute docPath', async () => {
const { buildSelectionHandoffInput } = await import('./useHandoffDispatch');
const input = buildSelectionHandoffInput({
docName: 'specs/foo/SPEC',
workspace: { contentDir: '/Users/andrew/repo', pathSeparator: '/' },
instruction: 'rewrite this passage',
selectionMarkdown: 'The selected passage.',
});
expect(input).toEqual({
docContext: null,
selection: {
relativePath: 'specs/foo/SPEC.md',
instruction: 'rewrite this passage',
selectionMarkdown: 'The selected passage.',
},
projectDir: '/Users/andrew/repo',
docPath: '/Users/andrew/repo/specs/foo/SPEC.md',
});
});
test('Windows: docPath uses backslashes; selection.relativePath stays POSIX', async () => {
const { buildSelectionHandoffInput } = await import('./useHandoffDispatch');
const input = buildSelectionHandoffInput({
docName: 'specs/foo/SPEC',
workspace: { contentDir: 'C:\\repo', pathSeparator: '\\' },
instruction: '',
selectionMarkdown: 'passage',
});
expect(input?.selection?.relativePath).toBe('specs/foo/SPEC.md');
expect(input?.projectDir).toBe('C:\\repo');
expect(input?.docPath).toBe('C:\\repo\\specs\\foo\\SPEC.md');
});
test('empty instruction is allowed — passes through, not a null trigger', async () => {
const { buildSelectionHandoffInput } = await import('./useHandoffDispatch');
const input = buildSelectionHandoffInput({
docName: 'd',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: '',
selectionMarkdown: 'passage',
});
expect(input).not.toBeNull();
expect(input?.selection?.instruction).toBe('');
});
});
describe('buildSelectionOrDocHandoffInput — selection/file fallback helper', () => {
test('prefers selection scope when the serialized selection is non-empty', async () => {
const { buildSelectionOrDocHandoffInput } = await import('./useHandoffDispatch');
const input = buildSelectionOrDocHandoffInput({
docName: 'specs/foo/SPEC',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'rewrite',
selectionMarkdown: 'selected passage',
});
expect(input?.docContext).toBeNull();
expect(input?.selection).toEqual({
relativePath: 'specs/foo/SPEC.md',
instruction: 'rewrite',
selectionMarkdown: 'selected passage',
});
expect(input?.docPath).toBe('/repo/specs/foo/SPEC.md');
});
test('falls back to file scope when the serialized selection is empty', async () => {
const { buildSelectionOrDocHandoffInput } = await import('./useHandoffDispatch');
const input = buildSelectionOrDocHandoffInput({
docName: 'specs/foo/SPEC',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'rewrite',
selectionMarkdown: '',
});
expect(input).toEqual({
docContext: { relativePath: 'specs/foo/SPEC.md' },
projectDir: '/repo',
docPath: '/repo/specs/foo/SPEC.md',
});
});
test('returns null when neither selection nor file scope can be built', async () => {
const { buildSelectionOrDocHandoffInput } = await import('./useHandoffDispatch');
expect(
buildSelectionOrDocHandoffInput({
docName: null,
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'rewrite',
selectionMarkdown: '',
}),
).toBeNull();
});
});
describe('runHandoffDispatch — selection scope', () => {
function selectionInput(): HandoffDispatchInput {
return {
docContext: null,
selection: {
relativePath: 'guides/style.md',
instruction: 'make this concise',
selectionMarkdown: 'This sentence is wordy.',
},
projectDir: '/tmp/proj',
docPath: '/tmp/proj/guides/style.md',
};
}
test('composes the selection prompt and dispatches it to the picked target', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const { composeSelectionPrompt } = await import('@inkeep/open-knowledge-core');
const deps = buildDeps();
await runHandoffDispatch('claude-code', selectionInput(), deps);
expect(deps.dispatchHandoff).toHaveBeenCalledTimes(1);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.target).toBe('claude-code');
expect(payload.projectDir).toBe('/tmp/proj');
expect(payload.docPath).toBe('/tmp/proj/guides/style.md');
expect(payload.prompt).toBe(
composeSelectionPrompt({
relativePath: 'guides/style.md',
instruction: 'make this concise',
selectionMarkdown: 'This sentence is wordy.',
target: 'claude-code',
}),
);
});
test('records the selection scope on the telemetry line (Electron host)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps();
await runHandoffDispatch('codex', selectionInput(), deps);
expect(deps.recordHandoff).toHaveBeenCalledTimes(1);
expect(deps.recordHandoff).toHaveBeenCalledWith({
target: 'codex',
host: 'electron',
outcome: 'ok',
ts: '2026-04-22T03:00:00.000Z',
scope: 'selection',
});
});
test('selection dispatch on a web host builds a web-tagged line carrying the scope', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({ isElectronHost: () => false });
await runHandoffDispatch('codex', selectionInput(), deps);
expect(deps.recordHandoff).toHaveBeenCalledWith({
target: 'codex',
host: 'web',
outcome: 'ok',
ts: '2026-04-22T03:00:00.000Z',
scope: 'selection',
});
});
});
describe('composeTerminalLaunchPrompt — docked-terminal bare launch is load + read + stop', () => {
test('file scope reads the open file via OK MCP, then stops', async () => {
const { composeTerminalLaunchPrompt } = await import('./useHandoffDispatch');
const out = composeTerminalLaunchPrompt(
{
docContext: { relativePath: 'notes/today.md' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude',
);
expect(out).toBe(composeTerminalBareLaunchPrompt('notes/today.md'));
expect(out).toContain(OK_TERMINAL_SURFACE_PREAMBLE);
expect(out).toContain('Read `notes/today.md` via the OpenKnowledge MCP server, then stop.');
expect(out).not.toContain("Let's work on");
expect(out).not.toContain('Open the OK editor');
});
test('folder scope has no file to read — just load and stop', async () => {
const { composeTerminalLaunchPrompt } = await import('./useHandoffDispatch');
const out = composeTerminalLaunchPrompt(
{
docContext: null,
folderRelativePath: 'specs/foo',
projectDir: '/proj',
docPath: '',
},
'claude',
);
expect(out).toBe(composeTerminalBareLaunchPrompt(null));
expect(out).toContain(OK_TERMINAL_SURFACE_PREAMBLE);
expect(out.endsWith('Then stop.')).toBe(true);
expect(out).not.toContain('Read `');
expect(out).not.toContain("Let's work on");
});
test('project / empty-space scope — just load and stop', async () => {
const { composeTerminalLaunchPrompt } = await import('./useHandoffDispatch');
const out = composeTerminalLaunchPrompt(
{
docContext: null,
projectDir: '/proj',
docPath: '',
},
'claude',
);
expect(out).toBe(composeTerminalBareLaunchPrompt(null));
expect(out.endsWith('Then stop.')).toBe(true);
expect(out).not.toContain("Let's work on");
});
test('bare launch is CLI-agnostic — codex / cursor compose the same prompt as claude', async () => {
const { composeTerminalLaunchPrompt } = await import('./useHandoffDispatch');
const input = {
docContext: { relativePath: 'notes/today.md' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
};
const claudeOut = composeTerminalLaunchPrompt(input, 'claude');
expect(claudeOut).toBe(composeTerminalBareLaunchPrompt('notes/today.md'));
expect(composeTerminalLaunchPrompt(input, 'codex')).toBe(claudeOut);
expect(composeTerminalLaunchPrompt(input, 'cursor')).toBe(claudeOut);
});
test('typed instruction is preserved per CLI, led by the terminal-surface preamble', async () => {
const { composeTerminalLaunchPrompt, selectScopedPrompt } = await import(
'./useHandoffDispatch'
);
const input = {
docContext: { relativePath: 'notes/today.md' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
instruction: 'summarize the open questions',
};
expect(composeTerminalLaunchPrompt(input, 'claude')).toBe(
`${OK_TERMINAL_SURFACE_PREAMBLE} ${selectScopedPrompt(input, 'claude-code', false, 'terminal')}`,
);
expect(composeTerminalLaunchPrompt(input, 'codex')).toBe(
`${OK_TERMINAL_SURFACE_PREAMBLE} ${selectScopedPrompt(input, 'codex', false, 'terminal')}`,
);
expect(composeTerminalLaunchPrompt(input, 'cursor')).toBe(
`${OK_TERMINAL_SURFACE_PREAMBLE} ${selectScopedPrompt(input, 'cursor', false, 'terminal')}`,
);
const claudeOut = composeTerminalLaunchPrompt(input, 'claude');
expect(claudeOut).toContain('summarize the open questions');
expect(claudeOut).toContain(OK_TERMINAL_SURFACE_PREAMBLE);
expect(claudeOut).not.toContain('Then stop.');
});
test('composer (compose scope) threads the typed instruction — NOT a bare launch', async () => {
const { composeTerminalLaunchPrompt, selectScopedPrompt } = await import(
'./useHandoffDispatch'
);
const input = {
docContext: null,
compose: {
scope: 'doc' as const,
docRelativePath: 'notes/work-log.md',
instruction: 'What does this file do?',
mentions: [],
},
projectDir: '/proj',
docPath: '/proj/notes/work-log.md',
};
expect(composeTerminalLaunchPrompt(input, 'claude')).toBe(
`${OK_TERMINAL_SURFACE_PREAMBLE} ${selectScopedPrompt(input, 'claude-code', false, 'terminal')}`,
);
expect(composeTerminalLaunchPrompt(input, 'codex')).toBe(
`${OK_TERMINAL_SURFACE_PREAMBLE} ${selectScopedPrompt(input, 'codex', false, 'terminal')}`,
);
expect(composeTerminalLaunchPrompt(input, 'cursor')).toBe(
`${OK_TERMINAL_SURFACE_PREAMBLE} ${selectScopedPrompt(input, 'cursor', false, 'terminal')}`,
);
const claudeOut = composeTerminalLaunchPrompt(input, 'claude');
expect(claudeOut).toContain('What does this file do?');
expect(claudeOut).not.toBe(composeTerminalBareLaunchPrompt('notes/work-log.md'));
expect(claudeOut).toContain(OK_TERMINAL_SURFACE_PREAMBLE);
});
test('skill scope threads the author-with-AI directive — NOT a bare launch', async () => {
const { composeTerminalLaunchPrompt, selectScopedPrompt } = await import(
'./useHandoffDispatch'
);
const input = {
docContext: null,
skill: { name: 'my-skill', scope: 'project' as const },
projectDir: '/proj',
docPath: '',
};
expect(composeTerminalLaunchPrompt(input, 'claude')).toBe(
`${OK_TERMINAL_SURFACE_PREAMBLE} ${selectScopedPrompt(input, 'claude-code', false, 'terminal')}`,
);
const claudeOut = composeTerminalLaunchPrompt(input, 'claude');
expect(claudeOut).toContain('`my-skill`');
expect(claudeOut).toContain('open-knowledge-write-skill');
expect(claudeOut).not.toContain('Then stop.');
});
test('whitespace-only instruction is treated as a bare launch', async () => {
const { composeTerminalLaunchPrompt } = await import('./useHandoffDispatch');
const out = composeTerminalLaunchPrompt(
{
docContext: { relativePath: 'notes/today.md' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
instruction: ' ',
},
'claude',
);
expect(out).toBe(composeTerminalBareLaunchPrompt('notes/today.md'));
expect(out).toContain(OK_TERMINAL_SURFACE_PREAMBLE);
expect(out).not.toContain('Instruction:');
expect(out).not.toContain("Let's work on");
});
test('create brief is preserved (keeps the directive composer)', async () => {
const { composeTerminalLaunchPrompt, selectScopedPrompt } = await import(
'./useHandoffDispatch'
);
const input = {
docContext: null,
createDescription: 'a fishing log',
createScenario: 'new-project' as const,
projectDir: '/proj',
docPath: '',
};
const out = composeTerminalLaunchPrompt(input, 'claude');
expect(out).toBe(
`${OK_TERMINAL_SURFACE_PREAMBLE} ${selectScopedPrompt(input, 'claude-code', false, 'terminal')}`,
);
expect(out).toContain('a fishing log');
expect(out).toContain(OK_TERMINAL_SURFACE_PREAMBLE);
});
test('empty create brief still routes to the directive composer (createDescription !== undefined)', async () => {
const { composeTerminalLaunchPrompt, selectScopedPrompt } = await import(
'./useHandoffDispatch'
);
const input = {
docContext: null,
createDescription: '',
createScenario: 'new-project' as const,
projectDir: '/proj',
docPath: '',
};
const out = composeTerminalLaunchPrompt(input, 'claude');
expect(out).toBe(
`${OK_TERMINAL_SURFACE_PREAMBLE} ${selectScopedPrompt(input, 'claude-code', false, 'terminal')}`,
);
expect(out).not.toBe(composeTerminalBareLaunchPrompt(null));
expect(out).toContain(OK_TERMINAL_SURFACE_PREAMBLE);
});
test('bare terminal launch never carries the web-view preview trailer', async () => {
const { composeTerminalLaunchPrompt, selectScopedPrompt } = await import(
'./useHandoffDispatch'
);
const input = {
docContext: { relativePath: 'notes/today.md' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
};
expect(composeTerminalLaunchPrompt(input, 'claude')).not.toContain('Open the OK editor');
expect(selectScopedPrompt(input, 'claude-code', true, 'url')).toContain(
'Open the OK editor in web view.',
);
});
});
describe('buildAskHandoffInput — ask-scoped helper', () => {
test('null docName returns null', async () => {
const { buildAskHandoffInput } = await import('./useHandoffDispatch');
expect(
buildAskHandoffInput({
docName: null,
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'condense this doc',
}),
).toBeNull();
});
test('null workspace returns null', async () => {
const { buildAskHandoffInput } = await import('./useHandoffDispatch');
expect(
buildAskHandoffInput({
docName: 'notes/today',
workspace: null,
instruction: 'condense this doc',
}),
).toBeNull();
});
test('empty-string docName is treated as no active doc (null return)', async () => {
const { buildAskHandoffInput } = await import('./useHandoffDispatch');
expect(
buildAskHandoffInput({
docName: '',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'condense this doc',
}),
).toBeNull();
});
test('POSIX: composes the ask payload + projectDir + absolute docPath', async () => {
const { buildAskHandoffInput } = await import('./useHandoffDispatch');
const input = buildAskHandoffInput({
docName: 'specs/foo/SPEC',
workspace: { contentDir: '/Users/andrew/repo', pathSeparator: '/' },
instruction: 'condense this doc',
});
expect(input).toEqual({
docContext: null,
ask: {
relativePath: 'specs/foo/SPEC.md',
instruction: 'condense this doc',
},
projectDir: '/Users/andrew/repo',
docPath: '/Users/andrew/repo/specs/foo/SPEC.md',
});
});
test('Windows: docPath uses backslashes; ask.relativePath stays POSIX', async () => {
const { buildAskHandoffInput } = await import('./useHandoffDispatch');
const input = buildAskHandoffInput({
docName: 'specs/foo/SPEC',
workspace: { contentDir: 'C:\\repo', pathSeparator: '\\' },
instruction: '',
});
expect(input?.ask?.relativePath).toBe('specs/foo/SPEC.md');
expect(input?.projectDir).toBe('C:\\repo');
expect(input?.docPath).toBe('C:\\repo\\specs\\foo\\SPEC.md');
});
test('empty instruction is allowed — passes through, not a null trigger', async () => {
const { buildAskHandoffInput } = await import('./useHandoffDispatch');
const input = buildAskHandoffInput({
docName: 'd',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: '',
});
expect(input).not.toBeNull();
expect(input?.ask?.instruction).toBe('');
expect(input?.docContext).toBeNull();
});
test('sets docContext null and carries the instruction on `ask` (no file-scope leak)', async () => {
const { buildAskHandoffInput } = await import('./useHandoffDispatch');
const input = buildAskHandoffInput({
docName: 'notes/today',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'do the thing',
});
expect(input?.docContext).toBeNull();
expect(input?.ask).toEqual({ relativePath: 'notes/today.md', instruction: 'do the thing' });
});
});
describe('selectScopedPrompt — ask scope', () => {
test('ask set returns composeAskPrompt(relativePath, instruction, autoOpen, target)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeAskPrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: null,
ask: { relativePath: 'notes/today.md', instruction: 'condense this doc' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
true,
'url',
);
expect(out).toBe(composeAskPrompt('notes/today.md', 'condense this doc', true, 'claude-code'));
expect(out).toContain('> condense this doc');
expect(out).toContain('@notes/today.md');
});
test('ask scope drops the preview trailer when autoOpen=false but keeps the instruction', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const out = selectScopedPrompt(
{
docContext: null,
ask: { relativePath: 'notes/today.md', instruction: 'condense this doc' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
false,
'url',
);
expect(out).toContain('> condense this doc');
expect(out).not.toContain('Open the OK editor');
});
test('R10 regression guard: an ask input does NOT fall through to composeFilePrompt', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeFilePrompt, composeAskPrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: null,
ask: { relativePath: 'notes/today.md', instruction: 'condense this doc' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
true,
'url',
);
expect(out).toContain('condense this doc');
expect(out).not.toBe(composeFilePrompt('notes/today.md', true));
expect(out).toBe(composeAskPrompt('notes/today.md', 'condense this doc', true, 'claude-code'));
});
test('precedence: ask beats docContext when both are set (defensive ordering)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeAskPrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: { relativePath: 'notes/today.md' },
ask: { relativePath: 'notes/today.md', instruction: 'condense this doc' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
true,
'url',
);
expect(out).toBe(composeAskPrompt('notes/today.md', 'condense this doc', true, 'claude-code'));
});
test('precedence: selection beats ask when both are set (defensive ordering)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeSelectionPrompt } = await import('@inkeep/open-knowledge-core');
const selection = {
relativePath: 'notes/today.md',
instruction: 'edit the passage',
selectionMarkdown: 'a passage',
};
const out = selectScopedPrompt(
{
docContext: null,
selection,
ask: { relativePath: 'notes/today.md', instruction: 'condense this doc' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
true,
'url',
);
expect(out).toBe(composeSelectionPrompt({ ...selection, target: 'claude-code' }));
});
test('empty instruction degrades to the bare doc directive (no dangling blockquote)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeAskPrompt } = await import('@inkeep/open-knowledge-core');
const out = selectScopedPrompt(
{
docContext: null,
ask: { relativePath: 'notes/today.md', instruction: '' },
projectDir: '/proj',
docPath: '/proj/notes/today.md',
},
'claude-code',
true,
'url',
);
expect(out).toBe(composeAskPrompt('notes/today.md', '', true, 'claude-code'));
expect(out).not.toContain('>');
});
});
describe('runHandoffDispatch — ask scope', () => {
function askInput(instruction = 'condense this doc'): HandoffDispatchInput {
return {
docContext: null,
ask: { relativePath: 'guides/style.md', instruction },
projectDir: '/tmp/proj',
docPath: '/tmp/proj/guides/style.md',
};
}
test('composes the ask prompt and dispatches it to the picked target', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const { composeAskPrompt } = await import('@inkeep/open-knowledge-core');
const deps = buildDeps();
await runHandoffDispatch('claude-code', askInput(), deps);
expect(deps.dispatchHandoff).toHaveBeenCalledTimes(1);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.target).toBe('claude-code');
expect(payload.projectDir).toBe('/tmp/proj');
expect(payload.docPath).toBe('/tmp/proj/guides/style.md');
expect(payload.prompt).toBe(
composeAskPrompt('guides/style.md', 'condense this doc', true, 'claude-code'),
);
});
test('R10: the typed instruction is present in the dispatched prompt (no composeFilePrompt drop)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const { composeFilePrompt } = await import('@inkeep/open-knowledge-core');
const deps = buildDeps();
await runHandoffDispatch(
'codex',
askInput('research the extinction of flightless birds'),
deps,
);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.prompt).toContain('research the extinction of flightless birds');
expect(payload.prompt).not.toBe(composeFilePrompt('guides/style.md', true));
});
test('ask dispatch records NO telemetry scope tag (untagged, like the directive scopes)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps();
await runHandoffDispatch('codex', askInput(), deps);
expect(deps.recordHandoff).toHaveBeenCalledTimes(1);
expect(deps.recordHandoff).toHaveBeenCalledWith({
target: 'codex',
host: 'electron',
outcome: 'ok',
ts: '2026-04-22T03:00:00.000Z',
});
});
test('autoOpen=false drops the preview trailer but keeps the instruction', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps({ autoOpen: false });
await runHandoffDispatch('codex', askInput(), deps);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.prompt).toContain('> condense this doc');
expect(payload.prompt).not.toContain('Open the OK editor');
});
test('end-to-end: buildAskHandoffInput → dispatch carries the instruction', async () => {
const { runHandoffDispatch, buildAskHandoffInput } = await import('./useHandoffDispatch');
const { composeAskPrompt } = await import('@inkeep/open-knowledge-core');
const deps = buildDeps();
const input = buildAskHandoffInput({
docName: 'guides/style',
workspace: { contentDir: '/tmp/proj', pathSeparator: '/' },
instruction: 'make a spec from this user story',
});
expect(input).not.toBeNull();
if (!input) throw new Error('unreachable');
await runHandoffDispatch('cursor', input, deps);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.prompt).toBe(
composeAskPrompt('guides/style.md', 'make a spec from this user story', true, 'cursor'),
);
expect(payload.prompt).toContain('make a spec from this user story');
});
});
describe('buildComposerHandoffInput — compose-scoped helper (US-002)', () => {
test('null workspace returns null', async () => {
const { buildComposerHandoffInput } = await import('./useHandoffDispatch');
expect(
buildComposerHandoffInput({
docName: 'notes/today',
workspace: null,
instruction: 'summarize',
mentions: [],
}),
).toBeNull();
});
test('null docName builds a project-scope compose input (no doc lead, empty docPath)', async () => {
const { buildComposerHandoffInput } = await import('./useHandoffDispatch');
const input = buildComposerHandoffInput({
docName: null,
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'plan the migration',
mentions: ['AGENTS.md'],
});
expect(input?.compose).toEqual({
scope: 'project',
instruction: 'plan the migration',
mentions: ['AGENTS.md'],
});
expect(input?.docContext).toBeNull();
expect(input?.projectDir).toBe('/repo');
expect(input?.docPath).toBe('');
});
test('non-null docName builds a doc-scope compose input with the .md relative path + absolute docPath', async () => {
const { buildComposerHandoffInput } = await import('./useHandoffDispatch');
const input = buildComposerHandoffInput({
docName: 'specs/foo/SPEC',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'tighten the intro',
mentions: ['guides/style.md'],
});
expect(input?.compose).toEqual({
scope: 'doc',
docRelativePath: 'specs/foo/SPEC.md',
instruction: 'tighten the intro',
mentions: ['guides/style.md'],
});
expect(input?.docPath).toBe('/repo/specs/foo/SPEC.md');
});
test('docRelativePath overrides the fallback docName extension for compose input', async () => {
const { buildComposerHandoffInput } = await import('./useHandoffDispatch');
const input = buildComposerHandoffInput({
docName: 'specs/foo/SPEC',
docRelativePath: 'specs/foo/SPEC.mdx',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'tighten the intro',
mentions: [],
});
expect(input?.compose).toEqual({
scope: 'doc',
docRelativePath: 'specs/foo/SPEC.mdx',
instruction: 'tighten the intro',
mentions: [],
});
expect(input?.docPath).toBe('/repo/specs/foo/SPEC.mdx');
});
test('folderRelativePath with null docName builds a folder-scope compose input (folder lead, empty docPath)', async () => {
const { buildComposerHandoffInput } = await import('./useHandoffDispatch');
const input = buildComposerHandoffInput({
docName: null,
folderRelativePath: 'specs/foo',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'audit this folder',
mentions: ['AGENTS.md'],
});
expect(input?.compose).toEqual({
scope: 'folder',
folderRelativePath: 'specs/foo',
instruction: 'audit this folder',
mentions: ['AGENTS.md'],
});
expect(input?.docContext).toBeNull();
expect(input?.projectDir).toBe('/repo');
expect(input?.docPath).toBe('');
});
test('docName takes precedence over folderRelativePath (doc scope wins)', async () => {
const { buildComposerHandoffInput } = await import('./useHandoffDispatch');
const input = buildComposerHandoffInput({
docName: 'notes/today',
folderRelativePath: 'specs/foo',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: 'tidy',
mentions: [],
});
expect(input?.compose?.scope).toBe('doc');
});
test('doc scope carries a provided selection; an omitted selection is absent', async () => {
const { buildComposerHandoffInput } = await import('./useHandoffDispatch');
const withSel = buildComposerHandoffInput({
docName: 'notes/today',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: '',
mentions: [],
selection: { kind: 'inline', markdown: 'A wordy sentence.' },
});
expect(withSel?.compose).toEqual({
scope: 'doc',
docRelativePath: 'notes/today.md',
instruction: '',
mentions: [],
selection: { kind: 'inline', markdown: 'A wordy sentence.' },
});
const noSel = buildComposerHandoffInput({
docName: 'notes/today',
workspace: { contentDir: '/repo', pathSeparator: '/' },
instruction: '',
mentions: [],
});
expect(noSel?.compose).not.toHaveProperty('selection');
});
});
describe('selectScopedPrompt — compose scope (US-002)', () => {
test('doc scope routes through assembleHandoffPrompt for the target (doc lead + mentions present)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { assembleHandoffPrompt } = await import('@inkeep/open-knowledge-core');
const input: HandoffDispatchInput = {
docContext: null,
compose: {
scope: 'doc',
docRelativePath: 'specs/foo/SPEC.md',
instruction: 'tighten the intro',
mentions: ['guides/style.md', 'AGENTS.md'],
},
projectDir: '/repo',
docPath: '/repo/specs/foo/SPEC.md',
};
const out = selectScopedPrompt(input, 'cursor', true, 'url');
expect(out).toBe(
assembleHandoffPrompt({
scope: 'doc',
docRelativePath: 'specs/foo/SPEC.md',
instruction: 'tighten the intro',
mentions: ['guides/style.md', 'AGENTS.md'],
autoOpen: true,
target: 'cursor',
}),
);
expect(out).toContain('@specs/foo/SPEC.md');
expect(out).toContain('@guides/style.md');
expect(out).toContain('@AGENTS.md');
expect(out).toContain('> tighten the intro');
});
test('folder scope routes through assembleHandoffPrompt with the folder @-mention lead + mentions', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { assembleHandoffPrompt } = await import('@inkeep/open-knowledge-core');
const input: HandoffDispatchInput = {
docContext: null,
compose: {
scope: 'folder',
folderRelativePath: 'specs/foo',
instruction: 'audit this folder',
mentions: ['AGENTS.md'],
},
projectDir: '/repo',
docPath: '',
};
const out = selectScopedPrompt(input, 'cursor', true, 'url');
expect(out).toBe(
assembleHandoffPrompt({
scope: 'folder',
folderRelativePath: 'specs/foo',
instruction: 'audit this folder',
mentions: ['AGENTS.md'],
autoOpen: true,
target: 'cursor',
}),
);
expect(out).toContain('@specs/foo folder');
expect(out).toContain('@AGENTS.md');
expect(out).toContain('> audit this folder');
});
test('project scope routes through assembleHandoffPrompt with no doc @-mention', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { assembleHandoffPrompt } = await import('@inkeep/open-knowledge-core');
const input: HandoffDispatchInput = {
docContext: null,
compose: { scope: 'project', instruction: 'plan the migration', mentions: [] },
projectDir: '/repo',
docPath: '',
};
const out = selectScopedPrompt(input, 'codex', true, 'url');
expect(out).toBe(
assembleHandoffPrompt({
scope: 'project',
instruction: 'plan the migration',
mentions: [],
autoOpen: true,
target: 'codex',
}),
);
expect(out).toContain('plan the migration');
expect(out).not.toContain('@');
});
test('doc scope with a selection threads the passage to the assembler', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { assembleHandoffPrompt } = await import('@inkeep/open-knowledge-core');
const input: HandoffDispatchInput = {
docContext: null,
compose: {
scope: 'doc',
docRelativePath: 'notes/today.md',
instruction: 'make concise',
mentions: [],
selection: { kind: 'inline', markdown: 'This sentence is wordy.' },
},
projectDir: '/repo',
docPath: '/repo/notes/today.md',
};
const out = selectScopedPrompt(input, 'claude-code', true, 'url');
expect(out).toBe(
assembleHandoffPrompt({
scope: 'doc',
docRelativePath: 'notes/today.md',
instruction: 'make concise',
mentions: [],
selection: { kind: 'inline', markdown: 'This sentence is wordy.' },
autoOpen: true,
target: 'claude-code',
}),
);
expect(out).toContain('This sentence is wordy.');
});
test('precedence: compose beats selection + docContext when several are set (defensive ordering)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { assembleHandoffPrompt } = await import('@inkeep/open-knowledge-core');
const input: HandoffDispatchInput = {
docContext: { relativePath: 'a.md' },
selection: { relativePath: 'a.md', instruction: 'x', selectionMarkdown: 'p' },
compose: { scope: 'project', instruction: 'unified path wins', mentions: [] },
projectDir: '/repo',
docPath: '/repo/a.md',
};
const out = selectScopedPrompt(input, 'claude-code', true, 'url');
expect(out).toBe(
assembleHandoffPrompt({
scope: 'project',
instruction: 'unified path wins',
mentions: [],
autoOpen: true,
target: 'claude-code',
}),
);
});
test('autoOpen=false drops the "Open the OK editor" trailer via the assembler', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const input: HandoffDispatchInput = {
docContext: null,
compose: { scope: 'project', instruction: 'plan', mentions: [] },
projectDir: '/repo',
docPath: '',
};
const out = selectScopedPrompt(input, 'codex', false, 'url');
expect(out).not.toContain('Open the OK editor');
});
});
describe('runHandoffDispatch — compose scope (US-002)', () => {
function composeProjectInput(): HandoffDispatchInput {
return {
docContext: null,
compose: { scope: 'project', instruction: 'plan the migration', mentions: [] },
projectDir: '/tmp/proj',
docPath: '',
};
}
test('project scope: composes via the assembler, prompt has the instruction + no doc mention, empty docPath dispatched (R1 dispatch half)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const { assembleHandoffPrompt } = await import('@inkeep/open-knowledge-core');
const deps = buildDeps();
await runHandoffDispatch('codex', composeProjectInput(), deps);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.docPath).toBe('');
expect(payload.prompt).toBe(
assembleHandoffPrompt({
scope: 'project',
instruction: 'plan the migration',
mentions: [],
autoOpen: true,
target: 'codex',
}),
);
expect(payload.prompt).toContain('plan the migration');
expect(payload.prompt).not.toContain('@');
});
test('multi-mention doc scope: every sanitized @path appears in the dispatched prompt (R4 dispatch half)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps();
const input: HandoffDispatchInput = {
docContext: null,
compose: {
scope: 'doc',
docRelativePath: 'specs/foo/SPEC.md',
instruction: 'compare these',
mentions: ['guides/style.md', 'AGENTS.md'],
},
projectDir: '/tmp/proj',
docPath: '/tmp/proj/specs/foo/SPEC.md',
};
await runHandoffDispatch('claude-code', input, deps);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.prompt).toContain('@specs/foo/SPEC.md');
expect(payload.prompt).toContain('@guides/style.md');
expect(payload.prompt).toContain('@AGENTS.md');
});
test('selection passage embedded + telemetry scope tagged selection (R5 dispatch half)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps();
const input: HandoffDispatchInput = {
docContext: null,
compose: {
scope: 'doc',
docRelativePath: 'notes/today.md',
instruction: 'make concise',
mentions: [],
selection: { kind: 'inline', markdown: 'This sentence is wordy.' },
},
projectDir: '/tmp/proj',
docPath: '/tmp/proj/notes/today.md',
};
await runHandoffDispatch('codex', input, deps);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.prompt).toContain('This sentence is wordy.');
expect(deps.recordHandoff).toHaveBeenCalledWith({
target: 'codex',
host: 'electron',
outcome: 'ok',
ts: '2026-04-22T03:00:00.000Z',
scope: 'selection',
});
});
test('compose with no passage stays untagged (no scope field on the telemetry line)', async () => {
const { runHandoffDispatch } = await import('./useHandoffDispatch');
const deps = buildDeps();
await runHandoffDispatch('codex', composeProjectInput(), deps);
expect(deps.recordHandoff).toHaveBeenCalledWith({
target: 'codex',
host: 'electron',
outcome: 'ok',
ts: '2026-04-22T03:00:00.000Z',
});
});
test('end-to-end: buildComposerHandoffInput (no doc) → dispatch carries the instruction, no doc mention', async () => {
const { runHandoffDispatch, buildComposerHandoffInput } = await import('./useHandoffDispatch');
const deps = buildDeps();
const input = buildComposerHandoffInput({
docName: null,
workspace: { contentDir: '/tmp/proj', pathSeparator: '/' },
instruction: 'set up CI',
mentions: [],
});
expect(input).not.toBeNull();
if (!input) throw new Error('unreachable');
await runHandoffDispatch('cursor', input, deps);
const [payload] = (deps.dispatchHandoff as ReturnType<typeof vi.fn>).mock.calls[0] as [
HandoffPayload,
];
expect(payload.docPath).toBe('');
expect(payload.prompt).toContain('set up CI');
expect(payload.prompt).not.toContain('@');
});
});
describe('threadTitleHintFromInput — the thread-title source', () => {
const base = { docContext: null, projectDir: '/proj', docPath: '' };
test('returns the create brief so the title skips the handoff preamble', async () => {
const { threadTitleHintFromInput } = await import('./useHandoffDispatch');
expect(threadTitleHintFromInput({ ...base, createDescription: 'Fix the login bug' })).toBe(
'Fix the login bug',
);
});
test('prefers compose instruction over a later scope, in selectScopedPrompt order', async () => {
const { threadTitleHintFromInput } = await import('./useHandoffDispatch');
expect(
threadTitleHintFromInput({
...base,
compose: { scope: 'project', instruction: 'summarize the specs', mentions: [] },
instruction: 'toolbar text that should lose',
}),
).toBe('summarize the specs');
});
test('skips blank candidates and falls back to the toolbar instruction', async () => {
const { threadTitleHintFromInput } = await import('./useHandoffDispatch');
expect(
threadTitleHintFromInput({
...base,
createDescription: ' ',
instruction: 'rename headings',
}),
).toBe('rename headings');
});
test('returns null when no typed text is present (bare launch)', async () => {
const { threadTitleHintFromInput } = await import('./useHandoffDispatch');
expect(
threadTitleHintFromInput({ ...base, docContext: { relativePath: 'notes/today.md' } }),
).toBeNull();
});
});