Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { spawnSync } from 'node:child_process';
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
renameSync,
rmSync,
statSync,
symlinkSync,
unlinkSync,
writeFileSync,
} from 'node:fs';
import { mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { DatabaseSync } from 'node:sqlite';
import {
BridgeMergeContentLossError,
DEFAULT_LINTER_CONFIG,
type LinterConfig,
LOCAL_DIR,
lintDocument,
REMOVED_KEYS,
} from '@inkeep/open-knowledge-core';
import {
readConfigSafely,
resolveConfigPath,
writeConfigPatch,
} from '@inkeep/open-knowledge-core/server';
import { parseCheckpoint } from '@inkeep/open-knowledge-core/shadow-repo-layout';
import simpleGit from 'simple-git';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { stringify as stringifyYaml } from 'yaml';
import * as Y from 'yjs';
import { runningAsRoot } from '../../../test-support/capabilities.test-helper.ts';
import { configureTestGitRepository } from '../../../test-support/configure-git-fixture.test-helper.ts';
import { processStartTokenFromOs } from '../../../test-support/os-process-start.test-helper.ts';
import { MAX_AGENT_SESSIONS } from './agent-sessions.ts';
import { BacklinkIndex } from './backlink-index.ts';
import { getBootTimings, resetBootTimingsForTest, startBootTimings } from './boot-timings.ts';
import { updateGeneratedIndexGitAttributes } from './content/generated-index-git-attributes.ts';
import { DerivedDocumentIndex } from './derived-document-index.ts';
import { _resetDocExtensionsForTests } from './doc-extensions.ts';
import { classifyGitError } from './error-classification.ts';
import { applyExternalChange } from './external-change.ts';
import type {
CheckPushPermissionOptions,
DetectGhAccountsFn,
DetectGhFn,
ProbeTokenStore,
PushPermission,
} from './github-permissions.ts';
import { buildIngressPolicy } from './ingress-policy.ts';
import { getLogger, loggerFactory, type PinoLogger } from './logger.ts';
import {
createManagedRenameRecoveryJournal,
managedRenameJournalPath,
writeManagedRenameJournal,
} from './managed-rename-journal.ts';
import { getMetrics, resetMetrics } from './metrics.ts';
import type { NativeWatcherBackend } from './parcel-subscription.ts';
import { ensureProjectGit } from './project-git.ts';
import { MAX_LCS_CELLS } from './reconciliation.ts';
import { saveRemovedDocsJournal } from './removed-docs-journal.ts';
import { createServer, type ServerInstance, type ServerOptions } from './server-factory.ts';
import { releaseServerLock } from './server-lock.ts';
import {
initShadowRepo,
listRescueCheckpoints,
type ShadowHandle,
shadowGit,
} from './shadow-repo.ts';
import { SyncEngine } from './sync-engine.ts';
import { TagIndex } from './tag-index.ts';
import { contentHash } from './version-hash.ts';
import { createWatcherDouble } from './watcher-double.test-helper.ts';
const watcherStartupFailures = vi.hoisted(() => ({ file: false, head: false }));
vi.mock('./file-watcher.ts', async (importOriginal) => {
const actual = await importOriginal<typeof import('./file-watcher.ts')>();
return {
...actual,
startWatcher: async (...args: Parameters<typeof actual.startWatcher>) => {
if (watcherStartupFailures.file) {
throw new Error('injected file-watcher startup failure');
}
return actual.startWatcher(...args);
},
};
});
vi.mock('./head-watcher.ts', async (importOriginal) => {
const actual = await importOriginal<typeof import('./head-watcher.ts')>();
return {
...actual,
startHeadWatcher: async (...args: Parameters<typeof actual.startHeadWatcher>) => {
if (watcherStartupFailures.head) {
throw new Error('injected head-watcher startup failure');
}
return actual.startHeadWatcher(...args);
},
};
});
interface LogEntry {
level: 'info' | 'warn' | 'error' | 'debug';
msg: string;
payload: Record<string, unknown>;
}
class CaptureLogger {
readonly entries: LogEntry[] = [];
info(data: unknown, message: string): void {
this.entries.push({
level: 'info',
msg: message,
payload: (data as Record<string, unknown>) ?? {},
});
}
warn(data: unknown, message: string): void {
this.entries.push({
level: 'warn',
msg: message,
payload: (data as Record<string, unknown>) ?? {},
});
}
error(data: unknown, message: string): void {
this.entries.push({
level: 'error',
msg: message,
payload: (data as Record<string, unknown>) ?? {},
});
}
debug(data: unknown, message: string): void {
this.entries.push({
level: 'debug',
msg: message,
payload: (data as Record<string, unknown>) ?? {},
});
}
}
const captureLoggers = new Map<string, CaptureLogger>();
function captureAllLoggers(): {
getCalls: (level?: string, msgContains?: string) => LogEntry[];
getLoggerEntries: (name: string) => LogEntry[];
reset: () => void;
} {
captureLoggers.clear();
loggerFactory.configure({
loggerFactory: (name: string) => {
const capture = new CaptureLogger();
captureLoggers.set(name, capture);
return capture as unknown as PinoLogger;
},
});
return {
getCalls(level?: string, msgContains?: string) {
const all: LogEntry[] = [];
for (const logger of captureLoggers.values()) {
all.push(...logger.entries);
}
return all.filter((e) => {
if (level && e.level !== level) return false;
if (msgContains && !e.msg.includes(msgContains)) return false;
return true;
});
},
getLoggerEntries(name: string) {
return captureLoggers.get(name)?.entries ?? [];
},
reset() {
captureLoggers.clear();
},
};
}
describe('createServer() — document durability state isolation', () => {
test('keeps same-named documents, branch scope, batch state, and disk intake per server', async () => {
const projectA = await mkdtemp(join(tmpdir(), 'ok-durability-a-'));
const projectB = await mkdtemp(join(tmpdir(), 'ok-durability-b-'));
const docName = 'same-doc';
const diskA = '# Disk A\n';
const diskB = '# Disk B\n';
let serverA: ServerInstance | null = null;
let serverB: ServerInstance | null = null;
const beginStartup = vi.spyOn(DerivedDocumentIndex.prototype, 'beginStartup');
try {
writeFileSync(join(projectA, `${docName}.md`), diskA, 'utf-8');
writeFileSync(join(projectB, `${docName}.md`), diskB, 'utf-8');
serverA = createServer({
contentDir: projectA,
projectDir: projectA,
gitEnabled: false,
quiet: true,
});
serverB = createServer({
contentDir: projectB,
projectDir: projectB,
gitEnabled: false,
quiet: true,
});
await Promise.all([serverA.ready, serverB.ready]);
expect(beginStartup).toHaveBeenCalledTimes(2);
expect(beginStartup.mock.instances[0]).not.toBe(beginStartup.mock.instances[1]);
const [connectionA, connectionB] = await Promise.all([
serverA.hocuspocus.openDirectConnection(docName),
serverB.hocuspocus.openDirectConnection(docName),
]);
expect(serverA.durabilityState).not.toBe(serverB.durabilityState);
expect(serverA.durabilityState.getReconciledBase(docName)).toBe(diskA);
expect(serverB.durabilityState.getReconciledBase(docName)).toBe(diskB);
expect(serverA.hocuspocus.documents.get(docName)?.getText('source').toString()).toBe(diskA);
expect(serverB.hocuspocus.documents.get(docName)?.getText('source').toString()).toBe(diskB);
serverA.durabilityState.switchReconciledBaseScope('feature-a');
serverA.durabilityState.setReconciledBase(docName, 'A feature');
serverA.durabilityState.setBatchInProgress(true);
serverA.durabilityState.beginInFlightFlush(docName, 'A flush');
expect(serverA.durabilityState.getReconciledBase(docName)).toBe('A feature');
expect(serverB.durabilityState.getActiveBranch()).toBe('main');
expect(serverB.durabilityState.getReconciledBase(docName)).toBe(diskB);
expect(serverA.durabilityState.isBatchInProgress()).toBe(true);
expect(serverB.durabilityState.isBatchInProgress()).toBe(false);
expect(serverB.durabilityState.peekInFlightFlush(docName)).toBeUndefined();
const externalA = '# External A\n';
applyExternalChange(serverA.durabilityState, serverA.hocuspocus, docName, externalA);
expect(serverA.hocuspocus.documents.get(docName)?.getText('source').toString()).toBe(
externalA,
);
expect(serverA.durabilityState.getReconciledBase(docName)).toBe(externalA);
expect(serverB.hocuspocus.documents.get(docName)?.getText('source').toString()).toBe(diskB);
expect(serverB.durabilityState.getReconciledBase(docName)).toBe(diskB);
await Promise.all([connectionA.disconnect(), connectionB.disconnect()]);
} finally {
await serverA?.destroy();
await serverB?.destroy();
await Promise.all([
rm(projectA, { recursive: true, force: true }),
rm(projectB, { recursive: true, force: true }),
]);
beginStartup.mockRestore();
}
});
});
describe('createServer() — agent-session cap passthrough', () => {
let projectDir: string;
let server: ServerInstance | null;
beforeEach(() => {
projectDir = mkdtempSync(resolve(tmpdir(), 'ok-agent-session-cap-'));
server = null;
});
afterEach(async () => {
await server?.destroy();
rmSync(projectDir, { recursive: true, force: true });
});
test('installs the overridden session cap on the manager', async () => {
const contentDir = mkdtempSync(resolve(projectDir, 'content-'));
server = createServer({
contentDir,
projectDir,
quiet: true,
agentSessionOptions: { maxSessions: 4, minEvictableIdleMs: 0 },
});
await server.ready;
expect(server.sessionManager.sessionLimit).toBe(4);
});
test('defaults to MAX_AGENT_SESSIONS when no override is supplied', async () => {
const contentDir = mkdtempSync(resolve(projectDir, 'content-'));
server = createServer({
contentDir,
projectDir,
quiet: true,
});
await server.ready;
expect(server.sessionManager.sessionLimit).toBe(MAX_AGENT_SESSIONS);
});
});
describe('createServer() — wiki embed target resolution', () => {
let projectDir: string;
let server: ServerInstance | null;
beforeEach(() => {
projectDir = mkdtempSync(resolve(tmpdir(), 'ok-wiki-embed-'));
server = null;
});
afterEach(async () => {
await server?.destroy();
rmSync(projectDir, { recursive: true, force: true });
});
test('a path-form image embed renders the tracked file it resolves to by wiki rules', async () => {
const contentDir = mkdtempSync(resolve(projectDir, 'content-'));
mkdirSync(join(contentDir, 'Pics', 'Deep'), { recursive: true });
writeFileSync(join(contentDir, 'Pics', 'Deep', 'x.png'), 'png');
mkdirSync(join(contentDir, 'assets'), { recursive: true });
writeFileSync(join(contentDir, 'assets', 'Cre\u0300me.png'), 'png');
writeFileSync(join(contentDir, 'wiki.md'), '# Wiki\n\n![[pics/deep/x.png]]\n');
server = createServer({ contentDir, projectDir, quiet: true });
await server.ready;
expect(server.resolveEmbed('pics/deep/x.png', 'wiki.md')).toBe('Pics/Deep/x.png');
expect(server.resolveEmbed('PICS/Deep/X.PNG', 'wiki.md')).toBe('Pics/Deep/x.png');
expect(server.resolveEmbed('assets/CR\u00c8ME.PNG', 'wiki.md')).toBe('assets/Cre\u0300me.png');
expect(server.resolveEmbed('pics/deep/nope.png', 'wiki.md')).toBeNull();
const conn = await server.hocuspocus.openDirectConnection('wiki');
try {
const embedSrc = (): unknown => {
const fragment = server?.hocuspocus.documents.get('wiki')?.getXmlFragment('default');
for (const node of fragment?.toArray() ?? []) {
if (!(node instanceof Y.XmlElement) || node.nodeName !== 'jsxComponent') continue;
const props = node.getAttribute('props') as unknown as
| Record<string, unknown>
| undefined;
return props?.src;
}
return undefined;
};
await vi.waitFor(() => expect(embedSrc()).not.toBeUndefined(), { timeout: 5_000 });
expect(embedSrc()).toBe('/Pics/Deep/x.png');
} finally {
conn.disconnect();
}
});
});
describe('createServer() — derived-index branch lifecycle', () => {
let projectDir: string;
let git: ReturnType<typeof simpleGit>;
let server: ServerInstance | null;
beforeEach(async () => {
projectDir = await mkdtemp(join(tmpdir(), 'ok-derived-branch-'));
git = simpleGit(projectDir);
await git.init(['--initial-branch=main']);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
writeFileSync(join(projectDir, 'main.md'), '# Main\n\n#main-branch\n', 'utf-8');
await git.add('.');
await git.commit('main content');
await git.checkoutLocalBranch('feature');
unlinkSync(join(projectDir, 'main.md'));
writeFileSync(join(projectDir, 'feature.md'), '# Feature\n\n#feature-branch\n', 'utf-8');
await git.add(['-A']);
await git.commit('feature content');
await git.checkout('main');
server = null;
});
afterEach(async () => {
await server?.destroy();
vi.restoreAllMocks();
await rm(projectDir, { recursive: true, force: true });
});
test('settles target indexes before broadcasting branch-switched', async () => {
const beginStartup = vi.spyOn(DerivedDocumentIndex.prototype, 'beginStartup');
server = createServer({
contentDir: projectDir,
projectDir,
quiet: true,
gitEnabled: false,
skipStateManifestCheck: true,
});
await server.ready;
const coordinator = beginStartup.mock.instances[0] as DerivedDocumentIndex;
beginStartup.mockRestore();
const settle = vi.spyOn(DerivedDocumentIndex.prototype, 'settleBranchFromDisk');
const batchStatesAtBroadcast: boolean[] = [];
const broadcast = server.cc1Broadcaster.emitBranchSwitched.bind(server.cc1Broadcaster);
const emit = vi
.spyOn(server.cc1Broadcaster, 'emitBranchSwitched')
.mockImplementation((branch) => {
batchStatesAtBroadcast.push(server.durabilityState.isBatchInProgress());
broadcast(branch);
});
await git.checkout('feature');
await vi.waitFor(() => expect(emit).toHaveBeenCalledWith('feature'), {
timeout: 10_000,
interval: 25,
});
expect(settle).toHaveBeenCalledTimes(1);
expect(settle.mock.invocationCallOrder[0]).toBeLessThan(emit.mock.invocationCallOrder[0] ?? 0);
expect(batchStatesAtBroadcast).toEqual([false]);
expect(await coordinator.getDocsForTagWithMatches('feature-branch')).toEqual([
{ docName: 'feature', matchingTags: ['feature-branch'] },
]);
expect(await coordinator.getDocsForTagWithMatches('main-branch')).toEqual([]);
}, 20_000);
test('aborts a degraded branch settlement and releases coordinator queries', async () => {
const beginStartup = vi.spyOn(DerivedDocumentIndex.prototype, 'beginStartup');
server = createServer({
contentDir: projectDir,
projectDir,
quiet: true,
gitEnabled: false,
skipStateManifestCheck: true,
});
await server.ready;
const coordinator = beginStartup.mock.instances[0] as DerivedDocumentIndex;
beginStartup.mockRestore();
vi.spyOn(DerivedDocumentIndex.prototype, 'settleBranchFromDisk').mockRejectedValueOnce(
new Error('injected branch settlement failure'),
);
const abort = vi.spyOn(DerivedDocumentIndex.prototype, 'abortBranchSwitch');
const batchStatesAtBroadcast: boolean[] = [];
const broadcast = server.cc1Broadcaster.emitBranchSwitched.bind(server.cc1Broadcaster);
const emit = vi
.spyOn(server.cc1Broadcaster, 'emitBranchSwitched')
.mockImplementation((branch) => {
batchStatesAtBroadcast.push(server.durabilityState.isBatchInProgress());
broadcast(branch);
});
await git.checkout('feature');
await vi.waitFor(() => expect(emit).toHaveBeenCalledWith('feature'), {
timeout: 10_000,
interval: 25,
});
expect(abort).toHaveBeenCalled();
expect(batchStatesAtBroadcast).toEqual([false]);
await expect(coordinator.getIndexedDocNames()).resolves.toBeInstanceOf(Array);
}, 20_000);
test('begin-branch failure always restores durability admission and releases queries', async () => {
const beginStartup = vi.spyOn(DerivedDocumentIndex.prototype, 'beginStartup');
server = createServer({
contentDir: projectDir,
projectDir,
quiet: true,
gitEnabled: false,
skipStateManifestCheck: true,
});
await server.ready;
const coordinator = beginStartup.mock.instances[0] as DerivedDocumentIndex;
beginStartup.mockRestore();
let rejectBegin!: (error: Error) => void;
const beginBranch = vi
.spyOn(DerivedDocumentIndex.prototype, 'beginBranchSwitch')
.mockImplementationOnce(() => {
const { promise, reject } = Promise.withResolvers<never>();
rejectBegin = reject;
return promise;
});
const abort = vi.spyOn(DerivedDocumentIndex.prototype, 'abortBranchSwitch');
await git.checkout('feature');
await vi.waitFor(() => expect(beginBranch).toHaveBeenCalledWith('feature'), {
timeout: 10_000,
interval: 25,
});
expect(server.durabilityState.isBatchInProgress()).toBe(true);
rejectBegin(new Error('injected branch begin failure'));
await vi.waitFor(
() => {
expect(abort).toHaveBeenCalled();
expect(server?.durabilityState.isBatchInProgress()).toBe(false);
},
{ timeout: 10_000, interval: 25 },
);
await expect(coordinator.getIndexedDocNames()).resolves.toBeInstanceOf(Array);
}, 20_000);
});
async function executePendingStore(server: ServerInstance, docName: string): Promise<void> {
const debounceId = `onStoreDocument-${docName}`;
await vi.waitFor(() => expect(server.hocuspocus.debouncer.isDebounced(debounceId)).toBe(true), {
timeout: 15_000,
interval: 25,
});
const pending = server.hocuspocus.debouncer.executeNow(debounceId);
if (pending) await pending.catch(() => undefined);
}
describe('createServer().destroy() — graceful shutdown flush', () => {
let tmpDir: string;
let logCapture: ReturnType<typeof captureAllLoggers>;
let finishControlledInit: (() => Promise<void>) | undefined;
beforeEach(async () => {
finishControlledInit = undefined;
tmpDir = await mkdtemp(join(tmpdir(), 'ok-destroy-test-'));
logCapture = captureAllLoggers();
});
afterEach(async () => {
await finishControlledInit?.();
loggerFactory.reset();
await rm(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});
test('late watcher release failure is a shutdown phase error and retains authority', async () => {
const contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
const authorityRegistryPath = join(tmpDir, 'authority.sqlite');
const releaseFailure = new Error('late watcher release failed');
let server: ServerInstance | undefined;
let destroyPromise: Promise<void> | undefined;
const backend: NativeWatcherBackend = {
async subscribe() {
if (destroyPromise === undefined) {
if (server === undefined) throw new Error('server was not returned before subscription');
destroyPromise = server.destroy();
}
return {
async unsubscribe() {
throw releaseFailure;
},
};
},
};
server = createServer({
contentDir,
projectDir: tmpDir,
authorityRegistryPath,
watcherBackend: backend,
gitEnabled: false,
quiet: true,
});
try {
await server.ready;
await destroyPromise;
expect(server.degraded).not.toContain('file-watcher');
expect(server.degraded).not.toContain('head-watcher');
const shutdownLogs = logCapture.getCalls('warn', 'shutdown flushed');
expect(shutdownLogs).toHaveLength(1);
expect(shutdownLogs[0]?.payload.phaseErrors).toContainEqual({
phase: 'watcher-unsubscribe',
error: releaseFailure.message,
});
expect(logCapture.getCalls('error', 'shutdown phase-1 watcher unsubscribe failed')).toEqual(
expect.arrayContaining([
expect.objectContaining({ payload: expect.objectContaining({ watched: 'content' }) }),
]),
);
expect(logCapture.getCalls('error', 'disk bridge watcher failed to start')).toHaveLength(0);
expect(logCapture.getCalls('error', 'HEAD watcher failed to start')).toHaveLength(0);
const registry = new DatabaseSync(authorityRegistryPath, { readOnly: true });
try {
expect(registry.prepare('SELECT count(*) AS count FROM server_authority').get()).toEqual({
count: 1,
});
} finally {
registry.close();
}
} finally {
await server.destroy();
}
});
test('flushes L1 markdown writes before destroy() resolves + emits shutdown log', async () => {
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
debounce: 60_000,
});
await server.ready;
const conn = await server.hocuspocus.openDirectConnection('test-doc');
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('hello world')]);
xmlFragment.insert(0, [paragraph]);
});
const doc = server.hocuspocus.documents.get('test-doc');
expect(doc).toBeDefined();
doc?.removeDirectConnection();
await server.destroy();
const onDisk = await readFile(join(tmpDir, 'test-doc.md'), 'utf-8');
expect(onDisk).toContain('hello world');
const shutdownLogs = logCapture.getCalls('info', 'shutdown flushed');
expect(shutdownLogs).toHaveLength(1);
expect(shutdownLogs[0].payload.documentCount).toBeGreaterThanOrEqual(1);
const warnShutdownLogs = logCapture.getCalls('warn', 'shutdown');
expect(warnShutdownLogs).toHaveLength(0);
});
test('flushes L2 git commit after L1 drain', async () => {
const { mkdirSync } = await import('node:fs');
const projectDir = tmpDir;
const contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
const shadowHandle = await initShadowRepo(projectDir);
const server = createServer({
contentDir,
projectDir,
contentRoot: 'content',
quiet: true,
debounce: 60_000,
shadowRepo: shadowHandle,
});
await server.ready;
const conn = await server.hocuspocus.openDirectConnection('test-doc-2');
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('commit me')]);
xmlFragment.insert(0, [paragraph]);
});
const doc = server.hocuspocus.documents.get('test-doc-2');
expect(doc).toBeDefined();
doc?.removeDirectConnection();
await server.destroy();
const sg = shadowGit(shadowHandle);
const wipRefs = (await sg.raw('for-each-ref', '--format=%(refname)', 'refs/wip/')).trim();
expect(wipRefs).toBeTruthy();
});
test('shutdown order: lock release happens AFTER L1 disk flush completes', async () => {
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
debounce: 60_000,
});
await server.ready;
const lockPath = join(tmpDir, '.ok', LOCAL_DIR, 'server.lock');
const docName = 'shutdown-order';
const contentPath = join(tmpDir, `${docName}.md`);
const captures: Array<{ lockExists: boolean; contentOnDisk: boolean; payload: string }> = [];
server.hocuspocus.configuration.extensions.push({
async afterUnloadDocument(payload: { documentName: string }) {
if (payload.documentName !== docName) return;
captures.push({
lockExists: existsSync(lockPath),
contentOnDisk: existsSync(contentPath),
payload: existsSync(contentPath) ? readFileSync(contentPath, 'utf-8') : '',
});
},
});
const conn = await server.hocuspocus.openDirectConnection(docName);
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('order-marker')]);
xmlFragment.insert(0, [paragraph]);
});
const doc = server.hocuspocus.documents.get(docName);
expect(doc).toBeDefined();
doc?.removeDirectConnection();
expect(existsSync(lockPath)).toBe(true);
await server.destroy();
expect(captures.length).toBe(1);
expect(captures[0]?.lockExists).toBe(true);
expect(captures[0]?.contentOnDisk).toBe(true);
expect(captures[0]?.payload).toContain('order-marker');
expect(existsSync(lockPath)).toBe(true);
const postDestroyLock = JSON.parse(readFileSync(lockPath, 'utf-8'));
expect(postDestroyLock.pid).toBe(process.pid);
expect(postDestroyLock.draining).toBe(true);
expect(readFileSync(contentPath, 'utf-8')).toContain('order-marker');
});
test('destroy() completes within destroyTimeoutMs AND rescues hung docs when onStoreDocument throws', async () => {
const { mkdirSync } = await import('node:fs');
const projectDir = tmpDir;
const contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
const shadowHandle = await initShadowRepo(projectDir);
const server = createServer({
contentDir,
projectDir,
contentRoot: 'content',
quiet: true,
destroyTimeoutMs: 500,
shadowRepo: shadowHandle,
});
await server.ready;
server.hocuspocus.configuration.extensions.push({
async onStoreDocument() {
throw new Error('simulated store failure');
},
});
const conn = await server.hocuspocus.openDirectConnection('pathological-doc');
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('will not be flushed')]);
xmlFragment.insert(0, [paragraph]);
});
const doc = server.hocuspocus.documents.get('pathological-doc');
expect(doc).toBeDefined();
doc?.removeDirectConnection();
const startedAt = Date.now();
await server.destroy();
const elapsed = Date.now() - startedAt;
expect(elapsed).toBeGreaterThanOrEqual(300);
expect(elapsed).toBeLessThan(5_000);
const warnLogs = logCapture.getCalls('warn', 'shutdown flushed');
expect(warnLogs).toHaveLength(1);
expect(warnLogs[0].payload.phaseErrors).toContainEqual(
expect.objectContaining({
phase: 'flush-all-stores',
error: expect.stringContaining('timeout'),
}),
);
const rescuePath = join(shadowHandle.gitDir, 'rescue', 'pathological-doc.md');
expect(existsSync(rescuePath)).toBe(true);
expect(readFileSync(rescuePath, 'utf-8')).toContain('will not be flushed');
const phaseError = warnLogs[0].payload.phaseErrors as Array<{
phase: string;
error: string;
}>;
const flushErr = phaseError.find((e) => e.phase === 'flush-all-stores');
expect(flushErr?.error).toContain('rescued [pathological-doc]');
const rescueLogs = logCapture.getCalls('info', '[rescue]');
expect(rescueLogs.length).toBeGreaterThanOrEqual(1);
expect(rescueLogs[0].payload.docName).toBe('pathological-doc');
});
test('destroy() deliberately rescues and unloads a refused-store doc instead of stranding it to the timeout', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
const projectDir = tmpDir;
const contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
const shadowHandle = await initShadowRepo(projectDir);
const docName = 'refused-store-doc';
const initial = '# Refused store doc\n\nPersisted paragraph.\n';
const docPath = join(contentDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
writeFileSync(join(projectDir, '.okignore'), `content/${docName}.md\n`, 'utf-8');
const server = createServer({
contentDir,
projectDir,
quiet: true,
debounce: 100,
maxDebounce: 500,
destroyTimeoutMs: 1500,
shadowRepo: shadowHandle,
});
await server.ready;
try {
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
chmodSync(docPath, 0o000);
server.durabilityState.deleteReconciledBase(docName);
const refusalsBefore = getMetrics().persistenceDuplicationBaselineRefusals;
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('Unflushed paragraph stranded at shutdown.')]);
xmlFragment.insert(0, [paragraph]);
});
await executePendingStore(server, docName);
await vi.waitFor(
() =>
expect(serverDoc.getText('source').toString()).toContain(
'Unflushed paragraph stranded at shutdown.',
),
{ timeout: 5_000, interval: 25 },
);
serverDoc.removeDirectConnection();
const startedAt = Date.now();
await server.destroy();
const elapsed = Date.now() - startedAt;
expect(elapsed).toBeLessThan(1_450);
expect(getMetrics().persistenceDuplicationBaselineRefusals).toBeGreaterThanOrEqual(
refusalsBefore + 1,
);
const flushPhaseErrors = logCapture
.getCalls('warn', 'shutdown flushed')
.flatMap((entry) => (entry.payload.phaseErrors as Array<{ phase: string }>) ?? []);
expect(flushPhaseErrors.some((p) => p.phase === 'flush-all-stores')).toBe(false);
expect(
logCapture.getCalls('info', 'refused-store doc rescued and unloaded').length,
).toBeGreaterThanOrEqual(1);
const rescuePath = join(shadowHandle.gitDir, 'rescue', `${docName}.md`);
expect(existsSync(rescuePath)).toBe(true);
expect(readFileSync(rescuePath, 'utf-8')).toContain(
'Unflushed paragraph stranded at shutdown.',
);
} finally {
chmodSync(docPath, 0o644);
await server.destroy();
}
});
test('destroy() rescues a doc refused before shutdown that the unload loop would otherwise destroy', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
const projectDir = tmpDir;
const contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
const shadowHandle = await initShadowRepo(projectDir);
const docName = 'runtime-refused-doc';
const initial = '# Runtime refused doc\n\nPersisted paragraph.\n';
const docPath = join(contentDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
writeFileSync(join(projectDir, '.okignore'), `content/${docName}.md\n`, 'utf-8');
const server = createServer({
contentDir,
projectDir,
quiet: true,
debounce: 100,
maxDebounce: 500,
destroyTimeoutMs: 1500,
shadowRepo: shadowHandle,
});
await server.ready;
try {
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
chmodSync(docPath, 0o000);
server.durabilityState.deleteReconciledBase(docName);
const refusalsBefore = getMetrics().persistenceDuplicationBaselineRefusals;
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('Unflushed paragraph refused at runtime.')]);
xmlFragment.insert(0, [paragraph]);
});
await executePendingStore(server, docName);
await vi.waitFor(
() =>
expect(serverDoc.getText('source').toString()).toContain(
'Unflushed paragraph refused at runtime.',
),
{ timeout: 5_000, interval: 25 },
);
await vi.waitFor(
() =>
expect(getMetrics().persistenceDuplicationBaselineRefusals).toBeGreaterThanOrEqual(
refusalsBefore + 1,
),
{ timeout: 10_000, interval: 25 },
);
const markTimeRescuePath = join(shadowHandle.gitDir, 'rescue', `${docName}.md`);
expect(existsSync(markTimeRescuePath)).toBe(true);
expect(readFileSync(markTimeRescuePath, 'utf-8')).toContain(
'Unflushed paragraph refused at runtime.',
);
const doc2Name = 'runtime-refused-neighbor';
const doc2Path = join(contentDir, `${doc2Name}.md`);
writeFileSync(doc2Path, '# Runtime refused neighbor\n\nSecond doc.\n', 'utf-8');
const conn2 = await server.hocuspocus.openDirectConnection(doc2Name);
const serverDoc2 = server.hocuspocus.documents.get(doc2Name);
expect(serverDoc2).toBeDefined();
if (!serverDoc2) return;
await vi.waitFor(
() =>
expect(server.durabilityState.getReconciledBase(doc2Name)).toBe(
'# Runtime refused neighbor\n\nSecond doc.\n',
),
{ timeout: 5_000, interval: 25 },
);
await conn2.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('Neighbor pending store paragraph.')]);
xmlFragment.insert(0, [paragraph]);
});
serverDoc2.removeDirectConnection();
serverDoc.removeDirectConnection();
const startedAt = Date.now();
await server.destroy();
const elapsed = Date.now() - startedAt;
expect(elapsed).toBeLessThan(1_450);
expect(getMetrics().persistenceDuplicationBaselineRefusals).toBeGreaterThanOrEqual(
refusalsBefore + 1,
);
const flushPhaseErrors = logCapture
.getCalls('warn', 'shutdown flushed')
.flatMap((entry) => (entry.payload.phaseErrors as Array<{ phase: string }>) ?? []);
expect(flushPhaseErrors.some((p) => p.phase === 'flush-all-stores')).toBe(false);
expect(
logCapture.getCalls('info', 'refused-store doc rescued and unloaded').length,
).toBeGreaterThanOrEqual(1);
const rescuePath = join(shadowHandle.gitDir, 'rescue', `${docName}.md`);
expect(existsSync(rescuePath)).toBe(true);
expect(readFileSync(rescuePath, 'utf-8')).toContain(
'Unflushed paragraph refused at runtime.',
);
} finally {
chmodSync(docPath, 0o644);
await server.destroy();
}
});
test('a later refused store refreshes the runtime rescue buffer with the newest content', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
const projectDir = tmpDir;
const contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
const shadowHandle = await initShadowRepo(projectDir);
const docName = 'runtime-refused-refresh';
const initial = '# Runtime refused refresh\n\nPersisted paragraph.\n';
const docPath = join(contentDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
writeFileSync(join(projectDir, '.okignore'), `content/${docName}.md\n`, 'utf-8');
const server = createServer({
contentDir,
projectDir,
quiet: true,
debounce: 100,
maxDebounce: 500,
destroyTimeoutMs: 1500,
shadowRepo: shadowHandle,
});
await server.ready;
try {
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
chmodSync(docPath, 0o000);
server.durabilityState.deleteReconciledBase(docName);
const refusalsBefore = getMetrics().persistenceDuplicationBaselineRefusals;
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('First refused edit.')]);
xmlFragment.insert(0, [paragraph]);
});
await executePendingStore(server, docName);
await vi.waitFor(
() =>
expect(getMetrics().persistenceDuplicationBaselineRefusals).toBeGreaterThanOrEqual(
refusalsBefore + 1,
),
{ timeout: 20_000, interval: 25 },
);
const rescuePath = join(shadowHandle.gitDir, 'rescue', `${docName}.md`);
expect(readFileSync(rescuePath, 'utf-8')).toContain('First refused edit.');
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('Second refused edit.')]);
xmlFragment.insert(0, [paragraph]);
});
await executePendingStore(server, docName);
await vi.waitFor(
() =>
expect(getMetrics().persistenceDuplicationBaselineRefusals).toBeGreaterThanOrEqual(
refusalsBefore + 2,
),
{ timeout: 20_000, interval: 25 },
);
expect(readFileSync(rescuePath, 'utf-8')).toContain('Second refused edit.');
} finally {
chmodSync(docPath, 0o644);
await server.destroy();
}
});
test('destroy() leaves a refused-store doc loaded when its shutdown rescue cannot write and reports it lost', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
const projectDir = tmpDir;
const contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
const shadowHandle = await initShadowRepo(projectDir);
const docName = 'refused-rescue-lost-doc';
const initial = '# Refused rescue lost doc\n\nPersisted paragraph.\n';
const docPath = join(contentDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
writeFileSync(join(projectDir, '.okignore'), `content/${docName}.md\n`, 'utf-8');
const server = createServer({
contentDir,
projectDir,
quiet: true,
debounce: 100,
maxDebounce: 500,
destroyTimeoutMs: 1500,
shadowRepo: shadowHandle,
});
await server.ready;
const chmodEntries: Array<{ path: string; mode: number }> = [];
try {
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
const shadowGitDir = shadowHandle.gitDir;
const walk = (dir: string): void => {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const entryPath = join(dir, entry.name);
chmodEntries.push({ path: entryPath, mode: statSync(entryPath).mode & 0o777 });
if (entry.isDirectory()) walk(entryPath);
}
};
chmodEntries.push({ path: shadowGitDir, mode: statSync(shadowGitDir).mode & 0o777 });
walk(shadowGitDir);
for (const entry of chmodEntries) chmodSync(entry.path, 0o500);
chmodSync(docPath, 0o000);
server.durabilityState.deleteReconciledBase(docName);
const refusalsBefore = getMetrics().persistenceDuplicationBaselineRefusals;
const rescueBufferWriteFailuresBefore = getMetrics().rescueBufferWriteFailures;
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('Unflushed paragraph the rescue cannot hold.')]);
xmlFragment.insert(0, [paragraph]);
});
await executePendingStore(server, docName);
await vi.waitFor(
() =>
expect(getMetrics().persistenceDuplicationBaselineRefusals).toBeGreaterThanOrEqual(
refusalsBefore + 1,
),
{ timeout: 20_000, interval: 25 },
);
const rescuePath = join(shadowHandle.gitDir, 'rescue', `${docName}.md`);
expect(existsSync(rescuePath)).toBe(false);
serverDoc.removeDirectConnection();
await server.destroy();
expect(
logCapture
.getCalls('warn', 'refused-store doc rescue failed')
.some((entry) => entry.payload.docName === docName),
).toBe(true);
expect(getMetrics().rescueBufferWriteFailures).toBeGreaterThanOrEqual(
rescueBufferWriteFailuresBefore + 2,
);
expect(
logCapture
.getCalls('info', 'refused-store doc rescued and unloaded')
.some((entry) => entry.payload.docName === docName),
).toBe(false);
expect(existsSync(rescuePath)).toBe(false);
const flushPhaseErrors = logCapture
.getCalls('warn', 'shutdown flushed')
.flatMap(
(entry) => (entry.payload.phaseErrors as Array<{ phase: string; error: string }>) ?? [],
);
const flushErr = flushPhaseErrors.find((e) => e.phase === 'flush-all-stores');
expect(flushErr?.error).toContain(`lost [${docName}]`);
} finally {
for (const entry of chmodEntries) {
if (!existsSync(entry.path)) continue;
chmodSync(entry.path, entry.mode);
}
chmodSync(docPath, 0o644);
await server.destroy();
}
});
test('destroy() leaves a refused-store doc to the flush timeout when its unload hangs past the deadline and reports the late completion', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
const projectDir = tmpDir;
const contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
const shadowHandle = await initShadowRepo(projectDir);
const docName = 'refused-unload-hangs-doc';
const initial = '# Refused unload hangs doc\n\nPersisted paragraph.\n';
const docPath = join(contentDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
writeFileSync(join(projectDir, '.okignore'), `content/${docName}.md\n`, 'utf-8');
const server = createServer({
contentDir,
projectDir,
quiet: true,
debounce: 100,
maxDebounce: 500,
destroyTimeoutMs: 1500,
shadowRepo: shadowHandle,
});
await server.ready;
try {
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
chmodSync(docPath, 0o000);
server.durabilityState.deleteReconciledBase(docName);
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('Unflushed paragraph behind a hanging unload.')]);
xmlFragment.insert(0, [paragraph]);
});
await executePendingStore(server, docName);
server.hocuspocus.configuration.extensions.push({
async beforeUnloadDocument(payload: { documentName: string }) {
if (payload.documentName !== docName) return;
await new Promise((resolve) => setTimeout(resolve, 2_500));
},
});
const rescuePath = join(shadowHandle.gitDir, 'rescue', `${docName}.md`);
const rescueContentBeforeDestroy = readFileSync(rescuePath, 'utf-8');
expect(rescueContentBeforeDestroy).toContain('Unflushed paragraph behind a hanging unload.');
serverDoc.removeDirectConnection();
const startedAt = Date.now();
await server.destroy();
const elapsed = Date.now() - startedAt;
expect(elapsed).toBeLessThan(10_000);
expect(
logCapture
.getCalls('warn', 'did not finish before the flush deadline')
.some((entry) => entry.payload.docName === docName),
).toBe(true);
expect(existsSync(rescuePath)).toBe(true);
expect(readFileSync(rescuePath, 'utf-8')).toContain(
'Unflushed paragraph behind a hanging unload.',
);
const flushPhaseErrors = logCapture
.getCalls('warn', 'shutdown flushed')
.flatMap(
(entry) => (entry.payload.phaseErrors as Array<{ phase: string; error: string }>) ?? [],
);
const flushErr = flushPhaseErrors.find((e) => e.phase === 'flush-all-stores');
expect(flushErr?.error).toContain(`rescued [${docName}]`);
await vi.waitFor(
() =>
expect(
logCapture
.getCalls('info', 'completed after the flush deadline')
.some((entry) => entry.payload.docName === docName),
).toBe(true),
{ timeout: 10_000, interval: 25 },
);
} finally {
chmodSync(docPath, 0o644);
await server.destroy();
}
}, 30_000);
test('destroy() does not hand a second refused-store doc a budget the first one already spent', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
const projectDir = tmpDir;
const contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
const shadowHandle = await initShadowRepo(projectDir);
const firstDoc = 'refused-budget-hog-doc';
const secondDoc = 'refused-budget-starved-doc';
const docNames = [firstDoc, secondDoc];
const initialOf = (docName: string) => `# ${docName}\n\nPersisted paragraph.\n`;
const pathOf = (docName: string) => join(contentDir, `${docName}.md`);
for (const docName of docNames) {
writeFileSync(pathOf(docName), initialOf(docName), 'utf-8');
}
writeFileSync(
join(projectDir, '.okignore'),
docNames.map((docName) => `content/${docName}.md\n`).join(''),
'utf-8',
);
const server = createServer({
contentDir,
projectDir,
quiet: true,
debounce: 100,
maxDebounce: 500,
destroyTimeoutMs: 1500,
shadowRepo: shadowHandle,
});
await server.ready;
try {
for (const docName of docNames) {
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initialOf(docName)),
{ timeout: 5_000, interval: 25 },
);
chmodSync(pathOf(docName), 0o000);
server.durabilityState.deleteReconciledBase(docName);
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText(`Unflushed paragraph for ${docName}.`)]);
xmlFragment.insert(0, [paragraph]);
});
await executePendingStore(server, docName);
await vi.waitFor(() => expect(server.durabilityState.isStoreRefused(docName)).toBe(true), {
timeout: 20_000,
interval: 25,
});
serverDoc.removeDirectConnection();
}
expect(server.durabilityState.getRefusedStoreDocNames()).toEqual(docNames);
server.hocuspocus.configuration.extensions.push({
async beforeUnloadDocument(payload: { documentName: string }) {
if (payload.documentName === firstDoc) {
await new Promise((resolve) => setTimeout(resolve, 2_500));
} else if (payload.documentName === secondDoc) {
await new Promise((resolve) => setTimeout(resolve, 300));
}
},
});
await server.destroy();
const starvedWarns = logCapture.getCalls('warn', 'did not finish before the flush deadline');
expect(
starvedWarns.map((entry) => ({
docName: entry.payload.docName,
unloadDeadline: entry.payload.unloadDeadline,
})),
).not.toContainEqual(expect.objectContaining({ unloadDeadline: 0 }));
expect(starvedWarns.some((entry) => entry.payload.docName === secondDoc)).toBe(false);
} finally {
for (const docName of docNames) chmodSync(pathOf(docName), 0o644);
await server.destroy();
}
}, 40_000);
test('a shadowless server logs and counts the rescue losses the flush timeout and skipped mints declare', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
const projectDir = tmpDir;
const contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
const shadowGitDir = join(projectDir, '.git');
chmodSync(shadowGitDir, 0o500);
writeFileSync(join(projectDir, '.okignore'), 'content/shadowless-flush-doc.md\n', 'utf-8');
const mintDocName = 'shadowless-mint-doc';
const mintInitial = '# Shadowless mint doc\n\nPersisted paragraph.\n';
const mintDocPath = join(contentDir, `${mintDocName}.md`);
writeFileSync(mintDocPath, mintInitial, 'utf-8');
const server = createServer({
contentDir,
projectDir,
quiet: true,
debounce: 100,
maxDebounce: 500,
destroyTimeoutMs: 1500,
gitEnabled: false,
});
await server.ready;
try {
const conn = await server.hocuspocus.openDirectConnection(mintDocName);
const serverDoc = server.hocuspocus.documents.get(mintDocName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(mintDocName)).toBe(mintInitial),
{ timeout: 5_000, interval: 25 },
);
const failuresBefore = getMetrics().rescueBufferWriteFailures;
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [
new Y.XmlText('Unflushed paragraph the shadowless server cannot mint.'),
]);
xmlFragment.insert(0, [paragraph]);
});
chmodSync(mintDocPath, 0o000);
unlinkSync(mintDocPath);
await vi.waitFor(
() =>
expect(
logCapture
.getCalls('warn', 'rescue checkpoint not minted')
.some(
(entry) =>
entry.payload.docName === mintDocName &&
entry.msg.includes('the delete that follows destroys the document content'),
),
).toBe(true),
{ timeout: 15_000, interval: 25 },
);
const flushDocName = 'shadowless-flush-doc';
const flushDocPath = join(contentDir, `${flushDocName}.md`);
writeFileSync(flushDocPath, '# Shadowless flush doc\n\nSecond doc.\n', 'utf-8');
const _conn2 = await server.hocuspocus.openDirectConnection(flushDocName);
const serverDoc2 = server.hocuspocus.documents.get(flushDocName);
expect(serverDoc2).toBeDefined();
if (!serverDoc2) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(flushDocName)).toBeDefined(),
{ timeout: 5_000, interval: 25 },
);
const originalShouldUnload = server.hocuspocus.shouldUnloadDocument.bind(server.hocuspocus);
server.hocuspocus.shouldUnloadDocument = (document) => {
if (document.name === '__system__') return false;
return originalShouldUnload(document);
};
server.hocuspocus.configuration.extensions.push({
async beforeUnloadDocument(payload: { documentName: string }) {
if (payload.documentName !== flushDocName) return;
await new Promise(() => {});
},
});
serverDoc.removeDirectConnection();
serverDoc2.removeDirectConnection();
await server.destroy();
expect(
logCapture.getCalls('warn', 'shadow repo unavailable at flush timeout').length,
).toBeGreaterThanOrEqual(1);
const flushPhaseErrors = logCapture
.getCalls('warn', 'shutdown flushed')
.flatMap(
(entry) => (entry.payload.phaseErrors as Array<{ phase: string; error: string }>) ?? [],
);
const flushErr = flushPhaseErrors.find((e) => e.phase === 'flush-all-stores');
expect(flushErr?.error).toContain(`lost [${flushDocName}]`);
const lostList = flushErr?.error.match(/lost \[[^\]]*\]/)?.[0];
expect(lostList).toBe(`lost [${flushDocName}]`);
expect(getMetrics().rescueBufferWriteFailures).toBeGreaterThanOrEqual(failuresBefore + 2);
} finally {
chmodSync(shadowGitDir, 0o755);
if (existsSync(mintDocPath)) chmodSync(mintDocPath, 0o644);
await server.destroy();
}
}, 30_000);
test('destroy() is idempotent under concurrent calls', async () => {
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
debounce: 60_000,
});
await server.ready;
const conn = await server.hocuspocus.openDirectConnection('test-idempotent');
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('idempotent content')]);
xmlFragment.insert(0, [paragraph]);
});
const doc = server.hocuspocus.documents.get('test-idempotent');
expect(doc).toBeDefined();
doc?.removeDirectConnection();
await Promise.all([server.destroy(), server.destroy()]);
const shutdownLogs = logCapture.getCalls('info', 'shutdown flushed');
expect(shutdownLogs).toHaveLength(1);
await server.destroy();
});
test('destroy() during async init — before ready resolves', async (ctx) => {
const startCompleted = Promise.withResolvers<SyncEngine>();
const releaseStart = Promise.withResolvers<void>();
const realStart = SyncEngine.prototype.start;
let startReturned = false;
const start = vi.spyOn(SyncEngine.prototype, 'start').mockImplementation(async function () {
await realStart.call(this);
startCompleted.resolve(this);
await releaseStart.promise;
startReturned = true;
});
let restored = false;
const releaseAndRestore = () => {
releaseStart.resolve();
if (!restored) {
restored = true;
start.mockRestore();
}
};
finishControlledInit = async () => releaseAndRestore();
ctx.signal.addEventListener('abort', releaseAndRestore, { once: true });
ctx.onTestFinished(() => {
ctx.signal.removeEventListener('abort', releaseAndRestore);
releaseAndRestore();
});
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
});
finishControlledInit = async () => {
releaseAndRestore();
await server.destroy();
};
let readySettled = false;
const readiness = server.ready.then(
() => {
readySettled = true;
},
(error: unknown) => {
readySettled = true;
throw error;
},
);
try {
const engine = await Promise.race([
startCompleted.promise,
readiness.then(() => {
throw new Error('Initialization finished without reaching the held startup');
}),
]);
ctx.signal.throwIfAborted();
expect(engine === server.syncEngine).toBe(true);
expect(startReturned).toBe(false);
expect(readySettled).toBe(false);
const destroying = server.destroy();
releaseStart.resolve();
await Promise.all([readiness, destroying]);
const shutdownLogs = logCapture.getCalls('info', 'shutdown flushed');
expect(shutdownLogs).toHaveLength(1);
} finally {
releaseAndRestore();
}
});
test('destroy() with zero documents loaded (short-circuit path)', async () => {
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
});
await server.ready;
const startedAt = Date.now();
await server.destroy();
const elapsed = Date.now() - startedAt;
expect(elapsed).toBeLessThan(2_000);
const shutdownLogs = logCapture.getCalls('info', 'shutdown flushed');
expect(shutdownLogs).toHaveLength(1);
expect(shutdownLogs[0].payload.documentCount).toBe(5);
});
test('destroy bounds a derived-index close that never settles and records the phase error', async () => {
const beginStartup = vi.spyOn(DerivedDocumentIndex.prototype, 'beginStartup');
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
destroyTimeoutMs: 200,
});
await server.ready;
const coordinator = beginStartup.mock.instances[0] as DerivedDocumentIndex;
beginStartup.mockRestore();
const { promise: tagCloseReleased, resolve: releaseTagClose } = Promise.withResolvers<void>();
let tagCloseEntered = false;
const tagCloseImplementation = TagIndex.prototype.close;
const tagClose = vi.spyOn(TagIndex.prototype, 'close').mockImplementation(async function (
this: TagIndex,
) {
tagCloseEntered = true;
await tagCloseImplementation.call(this);
await tagCloseReleased;
});
try {
await server.destroy();
expect(tagCloseEntered).toBe(true);
const closePhaseErrors = logCapture
.getCalls('warn', 'shutdown flushed')
.flatMap(
(entry) => (entry.payload.phaseErrors as Array<{ phase: string; error: string }>) ?? [],
)
.filter((e) => e.phase === 'derived-index-close');
expect(closePhaseErrors).toHaveLength(1);
expect(logCapture.getCalls('info', 'shutdown flushed')).toHaveLength(0);
} finally {
releaseTagClose();
tagClose.mockRestore();
await coordinator.close();
}
});
test('destroy() flushes multiple documents before resolving (multi-doc drain)', async () => {
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
debounce: 60_000,
});
await server.ready;
const conn1 = await server.hocuspocus.openDirectConnection('doc-a');
const conn2 = await server.hocuspocus.openDirectConnection('doc-b');
const conn3 = await server.hocuspocus.openDirectConnection('doc-c');
await conn1.transact((doc) => {
const frag = doc.getXmlFragment('default');
const p = new Y.XmlElement('paragraph');
p.insert(0, [new Y.XmlText('content A')]);
frag.insert(0, [p]);
});
await conn2.transact((doc) => {
const frag = doc.getXmlFragment('default');
const p = new Y.XmlElement('paragraph');
p.insert(0, [new Y.XmlText('content B')]);
frag.insert(0, [p]);
});
await conn3.transact((doc) => {
const frag = doc.getXmlFragment('default');
const p = new Y.XmlElement('paragraph');
p.insert(0, [new Y.XmlText('content C')]);
frag.insert(0, [p]);
});
for (const name of ['doc-a', 'doc-b', 'doc-c']) {
const doc = server.hocuspocus.documents.get(name);
expect(doc).toBeDefined();
doc?.removeDirectConnection();
}
await server.destroy();
expect(await readFile(join(tmpDir, 'doc-a.md'), 'utf-8')).toContain('content A');
expect(await readFile(join(tmpDir, 'doc-b.md'), 'utf-8')).toContain('content B');
expect(await readFile(join(tmpDir, 'doc-c.md'), 'utf-8')).toContain('content C');
const shutdownLogs = logCapture.getCalls('info', 'shutdown flushed');
expect(shutdownLogs).toHaveLength(1);
expect(shutdownLogs[0].payload.documentCount).toBe(8);
});
});
describe('createServer() degraded signal', () => {
let testProjectDir: string;
beforeEach(() => {
testProjectDir = mkdtempSync(resolve(tmpdir(), 'ok-degraded-test-'));
});
afterEach(() => {
watcherStartupFailures.file = false;
watcherStartupFailures.head = false;
resetBootTimingsForTest();
rmSync(testProjectDir, { recursive: true, force: true });
});
test('clean init — degraded is empty array', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
});
await srv.ready;
expect(Array.isArray(srv.degraded)).toBe(true);
expect(srv.degraded).toEqual([]);
await srv.destroy();
});
test('backlink startup failure labels the server as backlink-index degraded', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const load = vi
.spyOn(BacklinkIndex.prototype, 'loadFromDisk')
.mockRejectedValueOnce(new Error('injected backlink startup failure'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
});
try {
await srv.ready;
expect(load).toHaveBeenCalled();
expect(srv.degraded).toContain('backlink-index');
expect(srv.degraded.filter((name) => name === 'backlink-index')).toHaveLength(1);
} finally {
load.mockRestore();
await srv.destroy();
}
});
test('tag reconciliation failure labels the server as tag-index degraded', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const beginStartup = vi.spyOn(DerivedDocumentIndex.prototype, 'beginStartup');
const reconcile = vi
.spyOn(TagIndex.prototype, 'reconcileWithDisk')
.mockRejectedValueOnce(new Error('injected tag reconciliation failure'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
});
try {
await srv.ready;
const coordinator = beginStartup.mock.instances[0] as DerivedDocumentIndex;
expect(reconcile).toHaveBeenCalled();
expect(srv.degraded).toContain('tag-index');
expect(srv.degraded.filter((name) => name === 'tag-index')).toHaveLength(1);
await expect(coordinator.getAllTags()).resolves.toBeInstanceOf(Array);
} finally {
await srv.destroy();
beginStartup.mockRestore();
reconcile.mockRestore();
}
});
test('shadow-repo init failure — degraded includes "shadow-repo"', async () => {
mkdirSync(resolve(testProjectDir, '.git'));
writeFileSync(resolve(testProjectDir, '.git', 'ok'), 'I am a file, not a directory');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
});
await srv.ready;
expect(srv.degraded).toContain('shadow-repo');
expect(srv.degraded.filter((s) => s === 'shadow-repo')).toHaveLength(1);
await srv.destroy();
});
test('shadow exclude write refusal — degraded includes "shadow-excludes"', async () => {
mkdirSync(resolve(testProjectDir, '.git', 'ok', 'info'), { recursive: true });
symlinkSync(
resolve(testProjectDir, 'planted-exclude-target'),
resolve(testProjectDir, '.git', 'ok', 'info', 'exclude'),
);
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
});
try {
await srv.ready;
expect(srv.degraded).toContain('shadow-excludes');
expect(srv.degraded.filter((s) => s === 'shadow-excludes')).toHaveLength(1);
} finally {
await srv.destroy();
}
});
test.each([
{ failure: 'file' as const, label: 'file-watcher' },
{ failure: 'head' as const, label: 'head-watcher' },
])('$label startup failure is reported at runtime', async ({ failure, label }) => {
watcherStartupFailures[failure] = true;
if (failure === 'file') startBootTimings('2026-07-23T00:00:00.000Z');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
});
try {
await srv.ready;
expect(srv.degraded).toEqual([label]);
if (failure === 'file') {
expect(getBootTimings()?.indexesMs).toEqual(expect.any(Number));
}
} finally {
await srv.destroy();
}
});
test('an .mdx conflict restored before any scan resolves to its .mdx file', async () => {
watcherStartupFailures.file = true;
_resetDocExtensionsForTests();
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const diskContent = 'bytes the editor tried to overwrite';
mkdirSync(join(testProjectDir, '.ok', LOCAL_DIR), { recursive: true });
writeFileSync(
join(testProjectDir, '.ok', LOCAL_DIR, 'stale-external-writes.json'),
JSON.stringify({
version: 1,
branches: {
main: [
{
docName: 'notes/guide',
acknowledgedContent: 'acknowledged',
displacedVersions: [],
staleExternalWrite: {
docName: 'notes/guide',
file: `${resolve(contentDir).slice(resolve(testProjectDir).length + 1)}/notes/guide.mdx`,
diskHash: contentHash(diskContent),
diskContent,
detectedAt: '2026-09-08T10:00:00.000Z',
},
},
],
},
}),
);
const srv = createServer({ contentDir, projectDir: testProjectDir, quiet: true });
try {
await srv.ready;
expect(srv.degraded).toEqual(['file-watcher']);
expect(srv.durabilityState.getStaleExternalWrite('notes/guide')?.file).toMatch(
/notes\/guide\.mdx$/,
);
} finally {
await srv.destroy();
_resetDocExtensionsForTests();
}
});
});
describe('createServer() — config-doc admission (US-005)', () => {
let testProjectDir: string;
beforeEach(() => {
testProjectDir = mkdtempSync(resolve(tmpdir(), 'ok-config-admission-test-'));
});
afterEach(() => {
rmSync(testProjectDir, { recursive: true, force: true });
});
test('boot admits all three config docs alongside __system__', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
});
await srv.ready;
expect(srv.hocuspocus.documents.has('__system__')).toBe(true);
expect(srv.hocuspocus.documents.has('__config__/project')).toBe(true);
expect(srv.hocuspocus.documents.has('__local__/project')).toBe(true);
expect(srv.hocuspocus.documents.has('__user__/config.yml')).toBe(true);
expect(srv.degraded.filter((s) => s.startsWith('config-doc:'))).toEqual([]);
await srv.destroy();
});
test('Y.Text mutation on a config doc does NOT engage the markdown bridge (D41)', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
});
await srv.ready;
const configDoc = srv.hocuspocus.documents.get('__config__/project');
expect(configDoc).toBeDefined();
if (!configDoc) return;
const ytext = configDoc.getText('source');
const xmlFragment = configDoc.getXmlFragment('default');
expect(xmlFragment.length).toBe(0);
configDoc.transact(() => {
ytext.insert(0, 'theme: dark\n');
});
await new Promise((r) => setTimeout(r, 50));
expect(ytext.toString()).toBe('theme: dark\n');
expect(xmlFragment.length).toBe(0);
await srv.destroy();
});
test('connecting a transient client to a config doc succeeds via existing collab WS (D49)', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
});
await srv.ready;
const conn = await srv.hocuspocus.openDirectConnection('__config__/project');
try {
const document = conn.document;
expect(document).toBeDefined();
const text = document.getText('source');
expect(typeof text.toString()).toBe('string');
} finally {
await conn.disconnect();
}
await srv.destroy();
});
});
async function waitFor(predicate: () => boolean, timeoutMs = 4_000): Promise<boolean> {
const start = Date.now();
while (Date.now() - start < timeoutMs) {
if (predicate()) return true;
await new Promise((r) => setTimeout(r, 50));
}
return predicate();
}
describe('createServer() — config file watcher (US-007)', () => {
let testProjectDir: string;
let testHomedir: string;
beforeEach(() => {
testProjectDir = mkdtempSync(resolve(tmpdir(), 'ok-cfg-watcher-test-'));
testHomedir = mkdtempSync(resolve(tmpdir(), 'ok-cfg-watcher-home-'));
});
afterEach(() => {
loggerFactory.reset();
rmSync(testProjectDir, { recursive: true, force: true });
rmSync(testHomedir, { recursive: true, force: true });
});
test('external write to project config.yml propagates to Y.Text within 4s', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
const configDoc = srv.hocuspocus.documents.get('__config__/project');
expect(configDoc).toBeDefined();
if (!configDoc) {
await srv.destroy();
return;
}
const ytext = configDoc.getText('source');
expect(ytext.toString()).toBe('');
const configPath = join(testProjectDir, '.ok', 'config.yml');
mkdirSync(join(testProjectDir, '.ok'), { recursive: true });
const newContent = 'mcp:\n autoStart: false\n';
writeFileSync(configPath, newContent, 'utf-8');
const fired = await waitFor(() => ytext.toString() === newContent);
expect(fired).toBe(true);
await srv.destroy();
});
test('a key-level patch to the user config from outside the server reaches __user__/config.yml', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
const userDoc = srv.hocuspocus.documents.get('__user__/config.yml');
expect(userDoc).toBeDefined();
if (!userDoc) {
await srv.destroy();
return;
}
const ytext = userDoc.getText('source');
const written = await writeConfigPatch({
cwd: testHomedir,
scope: 'user',
patch: { editor: { wordWrap: false } },
homedirOverride: testHomedir,
});
expect(written.ok).toBe(true);
const fired = await waitFor(() => ytext.toString().includes('wordWrap: false'));
expect(fired).toBe(true);
await srv.destroy();
});
test('external broken-YAML write keeps Y.Text at LKG and does not crash the server', async () => {
const logs = captureAllLoggers();
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const configPath = join(testProjectDir, '.ok', 'config.yml');
mkdirSync(join(testProjectDir, '.ok'), { recursive: true });
const validContent = 'mcp:\n autoStart: false\n';
writeFileSync(configPath, validContent, 'utf-8');
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
const configDoc = srv.hocuspocus.documents.get('__config__/project');
expect(configDoc).toBeDefined();
if (!configDoc) {
await srv.destroy();
return;
}
const ytext = configDoc.getText('source');
expect(ytext.toString()).toBe(validContent);
writeFileSync(configPath, 'content: [unclosed\n', 'utf-8');
const warningLogged = await waitFor(
() => logs.getCalls('warn', 'project config invalid').length > 0,
);
expect(warningLogged).toBe(true);
expect(ytext.toString()).toBe(validContent);
const warning = logs.getCalls('warn', 'project config invalid').at(-1);
expect(warning?.payload.err).toBeInstanceOf(Error);
expect((warning?.payload.err as Error | undefined)?.cause).toMatchObject({
code: 'YAML_PARSE',
});
await srv.destroy();
});
test('persistence-hook write does not produce a feedback-loop mutation (LKG-equality short-circuit)', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
const configDoc = srv.hocuspocus.documents.get('__config__/project');
expect(configDoc).toBeDefined();
if (!configDoc) {
await srv.destroy();
return;
}
const ytext = configDoc.getText('source');
const newContent = 'mcp:\n autoStart: false\n';
configDoc.transact(() => {
ytext.insert(0, newContent);
});
const configPath = join(testProjectDir, '.ok', 'config.yml');
const fileLanded = await waitFor(
() => existsSync(configPath) && readFileSync(configPath, 'utf-8') === newContent,
);
expect(fileLanded).toBe(true);
const observedOrigins: unknown[] = [];
configDoc.on('afterTransaction', (tx: { origin: unknown }) => {
observedOrigins.push(tx.origin);
});
await new Promise((r) => setTimeout(r, 1_500));
expect(ytext.toString()).toBe(newContent);
const filewatcherOrigins = observedOrigins.filter(
(o) =>
o !== null &&
typeof o === 'object' &&
'context' in o &&
typeof (o as { context: unknown }).context === 'object' &&
(o as { context: { origin?: unknown } }).context.origin === 'config-file-watcher',
);
expect(filewatcherOrigins).toEqual([]);
await srv.destroy();
});
});
describe('createServer() — project-local file watcher → engine.setMode', () => {
let testProjectDir: string;
let testHomedir: string;
beforeEach(() => {
testProjectDir = mkdtempSync(resolve(tmpdir(), 'ok-pl-engine-test-'));
testHomedir = mkdtempSync(resolve(tmpdir(), 'ok-pl-engine-home-'));
});
afterEach(() => {
rmSync(testProjectDir, { recursive: true, force: true });
rmSync(testHomedir, { recursive: true, force: true });
});
test('external write of autoSync.enabled: true to project-local flips engine state', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(false);
const localDir = join(testProjectDir, '.ok', LOCAL_DIR);
mkdirSync(localDir, { recursive: true });
const configPath = join(localDir, 'config.yml');
writeFileSync(configPath, 'autoSync:\n enabled: true\n', 'utf-8');
const flipped = await waitFor(() => srv.syncEngine?.getStatus().syncEnabled === true);
expect(flipped).toBe(true);
await srv.destroy();
});
test('toggling autoSync.enabled: false on disk disables the engine within 4s', async () => {
mkdirSync(join(testProjectDir, '.ok', LOCAL_DIR), { recursive: true });
writeFileSync(
join(testProjectDir, '.ok', LOCAL_DIR, 'config.yml'),
'autoSync:\n enabled: true\n',
'utf-8',
);
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(true);
writeFileSync(
join(testProjectDir, '.ok', LOCAL_DIR, 'config.yml'),
'autoSync:\n enabled: false\n',
'utf-8',
);
const disabled = await waitFor(() => srv.syncEngine?.getStatus().syncEnabled === false);
expect(disabled).toBe(true);
await srv.destroy();
});
test('external write of committed autoSync.default: true flips engine state (unanswered machine)', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(false);
mkdirSync(join(testProjectDir, '.ok'), { recursive: true });
writeFileSync(
join(testProjectDir, '.ok', 'config.yml'),
'autoSync:\n default: true\n',
'utf-8',
);
const flipped = await waitFor(() => srv.syncEngine?.getStatus().syncEnabled === true);
expect(flipped).toBe(true);
await srv.destroy();
});
});
function nestRemovedKey(path: readonly string[], leaf: unknown): Record<string, unknown> {
const [head, ...rest] = path;
if (head === undefined) return {};
return { [head]: rest.length === 0 ? leaf : nestRemovedKey(rest, leaf) };
}
describe('createServer() — a removed key in project-local config does not disable sync', () => {
let testProjectDir: string;
let testHomedir: string;
let servers: ServerInstance[];
let logCapture: ReturnType<typeof captureAllLoggers>;
beforeEach(() => {
testProjectDir = mkdtempSync(resolve(tmpdir(), 'ok-removed-key-sync-'));
testHomedir = mkdtempSync(resolve(tmpdir(), 'ok-removed-key-home-'));
servers = [];
logCapture = captureAllLoggers();
});
afterEach(async () => {
for (const srv of servers) {
await srv.destroy();
}
loggerFactory.reset();
rmSync(testProjectDir, { recursive: true, force: true });
rmSync(testHomedir, { recursive: true, force: true });
});
function writeProjectLocal(yaml: string): void {
const localDir = join(testProjectDir, '.ok', LOCAL_DIR);
mkdirSync(localDir, { recursive: true });
writeFileSync(join(localDir, 'config.yml'), yaml, 'utf-8');
}
async function boot(): Promise<ServerInstance> {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
servers.push(srv);
await srv.ready;
return srv;
}
test('a stale showAllFiles key beside autoSync.mode: full still resolves full and reports the removed key', async () => {
writeProjectLocal(
stringifyYaml({
autoSync: { mode: 'full' },
appearance: { sidebar: { showAllFiles: false } },
}),
);
const srv = await boot();
expect(srv.syncEngine?.getStatus().syncMode).toBe('full');
const reportedRemovedKey = logCapture
.getCalls('warn')
.some(
(entry) =>
entry.payload.path === 'appearance.sidebar.showAllFiles' &&
typeof entry.msg === 'string' &&
entry.msg.includes('appearance.sidebar.showAllFiles'),
);
expect(reportedRemovedKey).toBe(true);
});
test.each(REMOVED_KEYS.map((entry) => ({ entry, dotted: entry.path.join('.') })))(
'registry key $dotted beside autoSync.mode: full still resolves full',
async ({ entry }) => {
writeProjectLocal(
stringifyYaml({ autoSync: { mode: 'full' }, ...nestRemovedKey(entry.path, false) }),
);
const srv = await boot();
expect(srv.syncEngine?.getStatus().syncMode).toBe('full');
},
);
test('a removed key beside linkPreviews.enabled: true resolves link previews enabled', async () => {
const srv = await boot();
writeProjectLocal(
stringifyYaml({
linkPreviews: { enabled: true },
appearance: { sidebar: { showAllFiles: false } },
}),
);
expect(srv.getLinkPreviewsEnabled()).toBe(true);
});
test('unparseable project-local YAML still fails link previews closed', async () => {
const srv = await boot();
writeProjectLocal('linkPreviews:\n enabled: true\ntrailing: [1, 2\n');
expect(srv.getLinkPreviewsEnabled()).toBe(false);
});
test('a schema-invalid project-local config still fails link previews closed', async () => {
const srv = await boot();
writeProjectLocal(stringifyYaml({ linkPreviews: { enabled: 'not-a-boolean' } }));
expect(srv.getLinkPreviewsEnabled()).toBe(false);
});
});
describe('createServer() — okignore + gitignore multi-path watcher (US-005)', () => {
let testProjectDir: string;
beforeEach(() => {
testProjectDir = mkdtempSync(resolve(tmpdir(), 'ok-okignore-watcher-test-'));
});
afterEach(() => {
rmSync(testProjectDir, { recursive: true, force: true });
});
test('external write to .okignore propagates to __config__/okignore Y.Text + ContentFilter rebuilds', async () => {
mkdirSync(join(testProjectDir, 'drafts'), { recursive: true });
writeFileSync(join(testProjectDir, 'keep.md'), '# Keep\n', 'utf-8');
writeFileSync(join(testProjectDir, 'drafts', 'foo.md'), '# Foo\n', 'utf-8');
const srv = createServer({
contentDir: testProjectDir,
projectDir: testProjectDir,
quiet: true,
});
await srv.ready;
expect(srv.contentFilter.isExcluded('drafts/foo.md')).toBe(false);
expect(srv.contentFilter.isExcluded('keep.md')).toBe(false);
const okignoreDoc = srv.hocuspocus.documents.get('__config__/okignore');
expect(okignoreDoc).toBeDefined();
if (!okignoreDoc) {
await srv.destroy();
return;
}
const ytext = okignoreDoc.getText('source');
expect(ytext.toString()).toBe('');
const okignorePath = join(testProjectDir, '.okignore');
const newContent = 'drafts/\n';
writeFileSync(okignorePath, newContent, 'utf-8');
const ytextSynced = await waitFor(() => ytext.toString() === newContent);
expect(ytextSynced).toBe(true);
const filterUpdated = await waitFor(() => srv.contentFilter.isExcluded('drafts/foo.md'));
expect(filterUpdated).toBe(true);
expect(srv.contentFilter.isExcluded('keep.md')).toBe(false);
await srv.destroy();
});
test('external write to .gitignore triggers ContentFilter rebuild WITHOUT mutating __config__/okignore Y.Text', async () => {
mkdirSync(join(testProjectDir, 'logs'), { recursive: true });
writeFileSync(join(testProjectDir, 'index.md'), '# Index\n', 'utf-8');
writeFileSync(join(testProjectDir, 'logs', 'debug.md'), '# Debug\n', 'utf-8');
const srv = createServer({
contentDir: testProjectDir,
projectDir: testProjectDir,
quiet: true,
});
await srv.ready;
expect(srv.contentFilter.isExcluded('logs/debug.md')).toBe(false);
const okignoreDoc = srv.hocuspocus.documents.get('__config__/okignore');
if (!okignoreDoc) {
await srv.destroy();
return;
}
const ytext = okignoreDoc.getText('source');
expect(ytext.toString()).toBe('');
const gitignorePath = join(testProjectDir, '.gitignore');
writeFileSync(gitignorePath, 'logs/\n', 'utf-8');
const filterUpdated = await waitFor(() => srv.contentFilter.isExcluded('logs/debug.md'));
expect(filterUpdated).toBe(true);
expect(srv.contentFilter.isExcluded('index.md')).toBe(false);
expect(ytext.toString()).toBe('');
await srv.destroy();
});
test('persistence-hook write of __config__/okignore Y.Text ends in atomic .okignore on disk + ContentFilter visibility change', async () => {
writeFileSync(join(testProjectDir, 'visible.md'), '# Visible\n', 'utf-8');
mkdirSync(join(testProjectDir, 'tmp'), { recursive: true });
writeFileSync(join(testProjectDir, 'tmp', 'cache.md'), '# Cache\n', 'utf-8');
const srv = createServer({
contentDir: testProjectDir,
projectDir: testProjectDir,
quiet: true,
});
await srv.ready;
expect(srv.contentFilter.isExcluded('tmp/cache.md')).toBe(false);
const okignoreDoc = srv.hocuspocus.documents.get('__config__/okignore');
if (!okignoreDoc) {
await srv.destroy();
return;
}
const ytext = okignoreDoc.getText('source');
const newContent = 'tmp/\n';
okignoreDoc.transact(() => {
ytext.insert(0, newContent);
});
const okignorePath = join(testProjectDir, '.okignore');
const fileLanded = await waitFor(
() => existsSync(okignorePath) && readFileSync(okignorePath, 'utf-8') === newContent,
);
expect(fileLanded).toBe(true);
const filterUpdated = await waitFor(() => srv.contentFilter.isExcluded('tmp/cache.md'));
expect(filterUpdated).toBe(true);
expect(srv.contentFilter.isExcluded('visible.md')).toBe(false);
await srv.destroy();
});
test('Y.Text mirror throw does NOT block ContentFilter rebuild', async () => {
mkdirSync(join(testProjectDir, 'drafts'), { recursive: true });
writeFileSync(join(testProjectDir, 'keep.md'), '# Keep\n', 'utf-8');
writeFileSync(join(testProjectDir, 'drafts', 'foo.md'), '# Foo\n', 'utf-8');
const logCapture = captureAllLoggers();
const srv = createServer({
contentDir: testProjectDir,
projectDir: testProjectDir,
quiet: true,
});
try {
await srv.ready;
expect(srv.contentFilter.isExcluded('drafts/foo.md')).toBe(false);
const okignoreDoc = srv.hocuspocus.documents.get('__config__/okignore');
expect(okignoreDoc).toBeDefined();
if (!okignoreDoc) return;
const origTransact = okignoreDoc.transact.bind(okignoreDoc);
Object.defineProperty(okignoreDoc, 'transact', {
value: () => {
throw new Error('test-injected: simulated Y.Doc transact failure');
},
writable: true,
configurable: true,
});
try {
const okignorePath = join(testProjectDir, '.okignore');
writeFileSync(okignorePath, 'drafts/\n', 'utf-8');
const filterUpdated = await waitFor(() => srv.contentFilter.isExcluded('drafts/foo.md'));
expect(filterUpdated).toBe(true);
expect(srv.contentFilter.isExcluded('keep.md')).toBe(false);
const errorEntries = logCapture.getCalls('error', 'applyExternalConfigChange failed');
expect(errorEntries.length).toBeGreaterThanOrEqual(1);
} finally {
Object.defineProperty(okignoreDoc, 'transact', {
value: origTransact,
writable: true,
configurable: true,
});
}
} finally {
loggerFactory.reset();
await srv.destroy();
}
});
});
describe('createServer() managed rename recovery', () => {
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'ok-managed-rename-recovery-'));
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
test('replays a pending managed rename journal before watcher startup', async () => {
writeFileSync(join(tmpDir, 'beta.md'), '# Alpha\n', 'utf-8');
writeFileSync(join(tmpDir, 'referrer.md'), 'See [[beta]].\n', 'utf-8');
writeManagedRenameJournal(
tmpDir,
createManagedRenameRecoveryJournal({
fromPath: 'alpha',
toPath: 'beta',
affectedDocs: [{ from: 'alpha', to: 'beta' }],
snapshots: [
{ docName: 'alpha', content: '# Alpha\n' },
{ docName: 'referrer', content: 'See [[alpha]].\n' },
],
}),
);
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
});
await server.ready;
expect(readFileSync(join(tmpDir, 'alpha.md'), 'utf-8')).toBe('# Alpha\n');
expect(readFileSync(join(tmpDir, 'referrer.md'), 'utf-8')).toBe('See [[alpha]].\n');
expect(existsSync(join(tmpDir, 'beta.md'))).toBe(false);
expect(existsSync(managedRenameJournalPath(tmpDir))).toBe(false);
await server.destroy();
});
test('marks the server degraded when the managed rename journal is corrupt', async () => {
mkdirSync(join(tmpDir, '.ok', LOCAL_DIR), { recursive: true });
writeFileSync(managedRenameJournalPath(tmpDir), '{not valid json', 'utf-8');
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
});
await server.ready;
expect(server.degraded).toContain('managed-rename-recovery');
await server.destroy();
});
});
describe('createServer() server-lock integration (V0-1)', () => {
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'ok-server-lock-int-'));
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
test('acquires server.lock at createServer(), drains on destroy() (unlink deferred to exit)', async () => {
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
});
await server.ready;
const lockPath = join(tmpDir, '.ok', LOCAL_DIR, 'server.lock');
expect(existsSync(lockPath)).toBe(true);
const md = JSON.parse(readFileSync(lockPath, 'utf-8'));
expect(md.pid).toBe(process.pid);
expect(md.worktreeRoot).toBe(tmpDir);
expect(md.draining).toBeUndefined();
expect(md.processStart).toEqual(processStartTokenFromOs(process.pid));
await server.destroy();
expect(existsSync(lockPath)).toBe(true);
const drained = JSON.parse(readFileSync(lockPath, 'utf-8'));
expect(drained.pid).toBe(process.pid);
expect(drained.draining).toBe(true);
expect(drained.processStart).toEqual(md.processStart);
});
test('exposes lockDir on ServerInstance', async () => {
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
});
await server.ready;
expect(server.lockDir).toBe(join(tmpDir, '.ok', LOCAL_DIR));
await server.destroy();
});
test('second createServer() on same contentDir rejects with collision error', async () => {
const first = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
});
await first.ready;
const { hostname } = await import('node:os');
const foreignPid = process.ppid > 1 ? process.ppid : process.pid + 1;
const lockPath = join(tmpDir, '.ok', LOCAL_DIR, 'server.lock');
writeFileSync(
lockPath,
JSON.stringify({
pid: foreignPid,
hostname: hostname(),
port: 9999,
startedAt: new Date().toISOString(),
worktreeRoot: tmpDir,
}),
'utf-8',
);
expect(() => createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true })).toThrow(
/content ownership is already held/,
);
writeFileSync(
lockPath,
JSON.stringify({
pid: process.pid,
hostname: hostname(),
port: 0,
startedAt: new Date().toISOString(),
worktreeRoot: tmpDir,
}),
'utf-8',
);
await first.destroy();
});
test('updateServerLockPort through createServer().lockDir updates on-disk port', async () => {
const { updateServerLockPort, readServerLock } = await import('./server-lock.ts');
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
});
await server.ready;
const lockPath = join(tmpDir, '.ok', LOCAL_DIR, 'server.lock');
const before = JSON.parse(readFileSync(lockPath, 'utf-8'));
expect(before.port).toBe(0);
updateServerLockPort(server.lockDir, 5173);
const after = readServerLock(server.lockDir);
expect(after).not.toBeNull();
expect(after?.port).toBe(5173);
expect(after?.pid).toBe(process.pid);
await server.destroy();
});
test('acquire stamps the port=0 sentinel even when an explicit port is configured', async () => {
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
port: 8080,
quiet: true,
});
await server.ready;
const lockPath = join(tmpDir, '.ok', LOCAL_DIR, 'server.lock');
const acquired = JSON.parse(readFileSync(lockPath, 'utf-8'));
expect(acquired.port).toBe(0);
await server.destroy();
});
test('destroy() drains server.lock even when a shutdown phase throws (CC8)', async () => {
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
});
await server.ready;
const lockPath = join(tmpDir, '.ok', LOCAL_DIR, 'server.lock');
expect(existsSync(lockPath)).toBe(true);
const origCloseAll = server.sessionManager.closeAll.bind(server.sessionManager);
server.sessionManager.closeAll = async () => {
await origCloseAll();
throw new Error('Injected Phase 2 failure');
};
await server.destroy();
const drained = JSON.parse(readFileSync(lockPath, 'utf-8'));
expect(drained.draining).toBe(true);
});
});
describe('createServer() — serverInstanceId', () => {
let tmpDirA: string;
let tmpDirB: string;
beforeEach(async () => {
tmpDirA = await mkdtemp(join(tmpdir(), 'ok-iid-a-'));
tmpDirB = await mkdtemp(join(tmpdir(), 'ok-iid-b-'));
});
afterEach(async () => {
await rm(tmpDirA, { recursive: true, force: true });
await rm(tmpDirB, { recursive: true, force: true });
});
test('each createServer() call produces a distinct serverInstanceId (UUID)', async () => {
const serverA = createServer({ contentDir: tmpDirA, projectDir: tmpDirA, quiet: true });
const serverB = createServer({ contentDir: tmpDirB, projectDir: tmpDirB, quiet: true });
try {
await serverA.ready;
await serverB.ready;
expect(typeof serverA.serverInstanceId).toBe('string');
expect(serverA.serverInstanceId.length).toBeGreaterThan(0);
expect(typeof serverB.serverInstanceId).toBe('string');
expect(serverB.serverInstanceId.length).toBeGreaterThan(0);
expect(serverA.serverInstanceId).toMatch(
/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$/,
);
expect(serverB.serverInstanceId).toMatch(
/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$/,
);
expect(serverA.serverInstanceId).not.toBe(serverB.serverInstanceId);
} finally {
await serverA.destroy();
await serverB.destroy();
}
});
});
describe("createServer() — onAuthenticate rejects 'server-instance-mismatch'", () => {
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'ok-auth-mismatch-'));
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
function getAuthExtension(server: Awaited<ReturnType<typeof createServer>>): {
onAuthenticate: (payload: unknown) => Promise<void>;
} {
const ext = server.hocuspocus.configuration.extensions.find(
(e) => (e as { __kind?: string }).__kind === 'principal-auth',
) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
if (!ext) throw new Error('expected principalAuthExtension on hocuspocus.configuration');
return ext;
}
test('token claiming a mismatched expectedServerInstanceId is rejected', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
const staleToken = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
expectedServerInstanceId: 'stale-server-id-from-prior-process',
});
const context: Record<string, unknown> = {};
let thrown: unknown = null;
try {
await authExt.onAuthenticate({
token: staleToken,
context,
documentName: 'test-doc',
});
} catch (err) {
thrown = err;
}
expect(thrown).not.toBeNull();
expect((thrown as { reason?: string }).reason).toBe('server-instance-mismatch');
expect(context.principalId).toBeUndefined();
expect(context.kind).toBeUndefined();
} finally {
await server.destroy();
}
});
test('token claiming the matching serverInstanceId is accepted', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
const goodToken = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
expectedServerInstanceId: server.serverInstanceId,
});
const context: Record<string, unknown> = {};
await authExt.onAuthenticate({
token: goodToken,
context,
documentName: 'test-doc',
});
expect(context.kind).toBe('human');
expect(context.tabSessionId).toBe('s-1');
} finally {
await server.destroy();
}
});
test('legacy token without expectedServerInstanceId is accepted (backward compat)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
const legacyToken = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
});
const context: Record<string, unknown> = {};
await authExt.onAuthenticate({
token: legacyToken,
context,
documentName: 'test-doc',
});
expect(context.kind).toBe('human');
expect(context.tabSessionId).toBe('s-1');
} finally {
await server.destroy();
}
});
test('missing token is accepted (anonymous legacy path)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
const context: Record<string, unknown> = {};
await authExt.onAuthenticate({
token: undefined,
context,
documentName: 'test-doc',
});
expect(context.principalId).toBeUndefined();
expect(context.kind).toBeUndefined();
} finally {
await server.destroy();
}
});
test('empty-string expectedServerInstanceId claim is treated as absent (not rejected)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
const emptyClaimToken = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
expectedServerInstanceId: '',
});
const context: Record<string, unknown> = {};
await authExt.onAuthenticate({
token: emptyClaimToken,
context,
documentName: 'test-doc',
});
expect(context.kind).toBe('human');
} finally {
await server.destroy();
}
});
});
describe("createServer() — onAuthenticate rejects 'branch-mismatch'", () => {
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'ok-auth-branch-'));
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
function getAuthExtension(server: Awaited<ReturnType<typeof createServer>>): {
onAuthenticate: (payload: unknown) => Promise<void>;
} {
const ext = server.hocuspocus.configuration.extensions.find(
(e) => (e as { __kind?: string }).__kind === 'principal-auth',
) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
if (!ext) throw new Error('expected principalAuthExtension on hocuspocus.configuration');
return ext;
}
test('token claiming a mismatched expectedBranch is rejected', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
const staleToken = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
expectedBranch: 'feature',
});
const context: Record<string, unknown> = {};
let thrown: unknown = null;
try {
await authExt.onAuthenticate({
token: staleToken,
context,
documentName: 'test-doc',
});
} catch (err) {
thrown = err;
}
expect(thrown).not.toBeNull();
expect((thrown as { reason?: string }).reason).toBe('branch-mismatch');
expect(context.principalId).toBeUndefined();
} finally {
await server.destroy();
}
});
test('token claiming the matching branch is accepted', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
const goodToken = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
expectedBranch: 'main',
});
const context: Record<string, unknown> = {};
await authExt.onAuthenticate({
token: goodToken,
context,
documentName: 'test-doc',
});
expect(context.kind).toBe('human');
expect(context.tabSessionId).toBe('s-1');
} finally {
await server.destroy();
}
});
test('empty-string expectedBranch is treated as absent (legacy path)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
const emptyClaimToken = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
expectedBranch: '',
});
const context: Record<string, unknown> = {};
await authExt.onAuthenticate({
token: emptyClaimToken,
context,
documentName: 'test-doc',
});
expect(context.kind).toBe('human');
} finally {
await server.destroy();
}
});
test('legacy token without expectedBranch is accepted', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
const legacyToken = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
});
const context: Record<string, unknown> = {};
await authExt.onAuthenticate({
token: legacyToken,
context,
documentName: 'test-doc',
});
expect(context.kind).toBe('human');
} finally {
await server.destroy();
}
});
});
describe('createServer() — onAuthenticate branch gate parks on readiness', () => {
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'ok-auth-branch-boot-'));
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
function getAuthExtension(server: Awaited<ReturnType<typeof createServer>>): {
onAuthenticate: (payload: unknown) => Promise<void>;
} {
const ext = server.hocuspocus.configuration.extensions.find(
(e) => (e as { __kind?: string }).__kind === 'principal-auth',
) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
if (!ext) throw new Error('expected principalAuthExtension on hocuspocus.configuration');
return ext;
}
test('a claim matching the real HEAD branch survives the boot window', async () => {
const git = simpleGit(tmpDir);
await git.init(['--initial-branch=master']);
configureTestGitRepository(tmpDir);
expect
.soft((await simpleGit(tmpDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
await git.addConfig('user.email', '[email protected]');
await git.addConfig('user.name', 'Test');
writeFileSync(join(tmpDir, 'seed.md'), '# Seed\n');
await git.add('.');
await git.commit('seed');
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
const authExt = getAuthExtension(server);
const token = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
expectedBranch: 'master',
});
const context: Record<string, unknown> = {};
let thrown: unknown = null;
try {
await authExt.onAuthenticate({ token, context, documentName: 'boot-window-doc' });
} catch (err) {
thrown = err;
}
expect(thrown).toBeNull();
expect(context.kind).toBe('human');
} finally {
await server.destroy();
}
});
test('a genuinely stale claim is still rejected after the branch resolves', async () => {
const git = simpleGit(tmpDir);
await git.init(['--initial-branch=master']);
configureTestGitRepository(tmpDir);
expect
.soft((await simpleGit(tmpDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
await git.addConfig('user.email', '[email protected]');
await git.addConfig('user.name', 'Test');
writeFileSync(join(tmpDir, 'seed.md'), '# Seed\n');
await git.add('.');
await git.commit('seed');
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
const authExt = getAuthExtension(server);
const token = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
expectedBranch: 'some-other-branch',
});
const context: Record<string, unknown> = {};
let thrown: unknown = null;
try {
await authExt.onAuthenticate({ token, context, documentName: 'boot-window-doc' });
} catch (err) {
thrown = err;
}
expect((thrown as { reason?: string } | null)?.reason).toBe('branch-mismatch');
expect((thrown as { message?: string } | null)?.message).toContain('master');
} finally {
await server.destroy();
}
});
test('admission settles before the rest of boot does', async () => {
const git = simpleGit(tmpDir);
await git.init(['--initial-branch=master']);
configureTestGitRepository(tmpDir);
expect
.soft((await simpleGit(tmpDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
await git.addConfig('user.email', '[email protected]');
await git.addConfig('user.name', 'Test');
const noteCount = 120;
for (let i = 0; i < noteCount; i++) {
writeFileSync(
join(tmpDir, `note-${i}.md`),
`# Note ${i}\n\nSee [[note-${(i + 1) % noteCount}]].\n`,
);
}
await git.add('.');
await git.commit('seed');
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
const order: string[] = [];
const readySettled = server.ready.then(
() => order.push('ready'),
() => order.push('ready'),
);
const authExt = getAuthExtension(server);
const token = JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
expectedBranch: 'master',
});
await authExt.onAuthenticate({ token, context: {}, documentName: 'boot-window-doc' });
order.push('auth');
await readySettled;
expect(order[0]).toBe('auth');
} finally {
await server.destroy();
}
});
});
describe('createServer() — onAuthenticate rejections reach the structured log', () => {
let tmpDir: string;
let logCapture: ReturnType<typeof captureAllLoggers>;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'ok-auth-log-'));
logCapture = captureAllLoggers();
});
afterEach(async () => {
loggerFactory.reset();
await rm(tmpDir, { recursive: true, force: true });
});
function getAuthExtension(server: Awaited<ReturnType<typeof createServer>>): {
onAuthenticate: (payload: unknown) => Promise<void>;
} {
const ext = server.hocuspocus.configuration.extensions.find(
(e) => (e as { __kind?: string }).__kind === 'principal-auth',
) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
if (!ext) throw new Error('expected principalAuthExtension on hocuspocus.configuration');
return ext;
}
test('branch-mismatch rejection emits a warn carrying claimed and current branch', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
await expect(
authExt.onAuthenticate({
token: JSON.stringify({ principalId: 'p-1', expectedBranch: 'feature' }),
context: {},
documentName: 'notes/alpha',
}),
).rejects.toMatchObject({ reason: 'branch-mismatch' });
const warns = logCapture.getCalls('warn', '[auth-rejection]');
expect(warns).toHaveLength(1);
expect(warns[0]?.msg).toBe('[auth-rejection] branch-mismatch');
expect(warns[0]?.payload).toMatchObject({
reason: 'branch-mismatch',
docName: 'notes/alpha',
claimedBranch: 'feature',
currentBranch: 'main',
});
} finally {
await server.destroy();
}
});
test('server-instance-mismatch rejection emits a warn carrying both instance ids', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
await expect(
authExt.onAuthenticate({
token: JSON.stringify({
principalId: 'p-1',
expectedServerInstanceId: 'stale-instance-from-prior-process',
}),
context: {},
documentName: 'notes/beta',
}),
).rejects.toMatchObject({ reason: 'server-instance-mismatch' });
const warns = logCapture.getCalls('warn', '[auth-rejection]');
expect(warns).toHaveLength(1);
expect(warns[0]?.msg).toBe('[auth-rejection] server-instance-mismatch');
expect(warns[0]?.payload).toMatchObject({
reason: 'server-instance-mismatch',
docName: 'notes/beta',
claimedServerInstanceId: 'stale-instance-from-prior-process',
currentServerInstanceId: server.serverInstanceId,
});
} finally {
await server.destroy();
}
});
test('an accepted connection emits no rejection warn', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const authExt = getAuthExtension(server);
await authExt.onAuthenticate({
token: JSON.stringify({
principalId: 'p-1',
tabSessionId: 's-1',
expectedBranch: 'main',
expectedServerInstanceId: server.serverInstanceId,
}),
context: {},
documentName: 'notes/gamma',
});
expect(logCapture.getCalls('warn', '[auth-rejection]')).toHaveLength(0);
} finally {
await server.destroy();
}
});
test('config-doc admission denial emits a warn naming which gate fired', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = server.hocuspocus.configuration.extensions.find(
(e) => (e as { __kind?: string }).__kind === 'config-doc-admission-guard',
) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
if (!guard) throw new Error('expected configDocAdmissionGuard on hocuspocus.configuration');
await expect(
guard.onAuthenticate({
token: undefined,
context: {},
documentName: '__config__/project',
request: { socket: { remoteAddress: '203.0.113.7' }, headers: { host: 'evil.test' } },
}),
).rejects.toThrow(/config-doc admission requires loopback peer/);
const warns = logCapture.getCalls('warn', '[auth-rejection]');
expect(warns).toHaveLength(1);
expect(warns[0]?.payload).toMatchObject({
reason: 'config-doc-admission-denied',
docName: '__config__/project',
check: 'peer',
});
expect(warns[0]?.payload).not.toHaveProperty('peer');
} finally {
await server.destroy();
}
});
});
describe('createServer() — config-doc admission guard', () => {
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'ok-config-admission-'));
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
function getConfigDocAdmissionGuard(server: Awaited<ReturnType<typeof createServer>>): {
onAuthenticate: (payload: unknown) => Promise<void>;
} {
const ext = server.hocuspocus.configuration.extensions.find(
(e) => (e as { __kind?: string }).__kind === 'config-doc-admission-guard',
) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
if (!ext) throw new Error('expected configDocAdmissionGuard on hocuspocus.configuration');
return ext;
}
function makePayload(opts: {
documentName: string;
peer?: string;
host?: string | null;
}): unknown {
const headers: Record<string, string> = {};
if (opts.host !== null && opts.host !== undefined) headers.host = opts.host;
return {
token: undefined,
documentName: opts.documentName,
context: {} as Record<string, unknown>,
request: {
socket: opts.peer === undefined ? undefined : { remoteAddress: opts.peer },
headers,
},
requestHeaders: new Headers(opts.host ? { host: opts.host } : {}),
};
}
test('non-config doc bypasses the gate (no peer, no host)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
await expect(
guard.onAuthenticate(
makePayload({ documentName: 'some-user-doc', peer: undefined, host: null }),
),
).resolves.toBeUndefined();
} finally {
await server.destroy();
}
});
test('config doc accepts loopback IPv4 peer + localhost Host', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
await expect(
guard.onAuthenticate(
makePayload({
documentName: '__config__/project',
peer: '127.0.0.1',
host: 'localhost:5173',
}),
),
).resolves.toBeUndefined();
} finally {
await server.destroy();
}
});
test('config doc accepts IPv6 loopback peer + bracketed Host', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
await expect(
guard.onAuthenticate(
makePayload({ documentName: '__user__/config.yml', peer: '::1', host: '[::1]:5173' }),
),
).resolves.toBeUndefined();
} finally {
await server.destroy();
}
});
test('config doc rejects non-loopback peer (LAN)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
let thrown: unknown = null;
try {
await guard.onAuthenticate(
makePayload({
documentName: '__config__/project',
peer: '192.168.1.5',
host: 'localhost:5173',
}),
);
} catch (err) {
thrown = err;
}
expect(thrown).not.toBeNull();
expect((thrown as Error).message).toContain('loopback peer');
} finally {
await server.destroy();
}
});
test('config doc rejects IPv4-mapped non-loopback peer', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
let thrown: unknown = null;
try {
await guard.onAuthenticate(
makePayload({
documentName: '__user__/config.yml',
peer: '::ffff:192.168.1.5',
host: 'localhost',
}),
);
} catch (err) {
thrown = err;
}
expect(thrown).not.toBeNull();
expect((thrown as Error).message).toContain('loopback peer');
} finally {
await server.destroy();
}
});
test('config doc rejects loopback peer with attacker-domain Host (DNS rebinding)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
let thrown: unknown = null;
try {
await guard.onAuthenticate(
makePayload({
documentName: '__config__/project',
peer: '127.0.0.1',
host: 'attacker.example.com',
}),
);
} catch (err) {
thrown = err;
}
expect(thrown).not.toBeNull();
expect((thrown as Error).message).toContain('loopback or remote Host header');
} finally {
await server.destroy();
}
});
test('config doc admits the tunnel public Host when remote access is enabled', async () => {
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
ingressPolicy: buildIngressPolicy({
serverRuntime: {
port: undefined,
bind: ['127.0.0.1'],
externalUrl: 'https://myproject.ngrok.app',
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',
loopbackOnly: true,
},
}),
});
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
await expect(
guard.onAuthenticate(
makePayload({
documentName: '__config__/project',
peer: '127.0.0.1',
host: 'myproject.ngrok.app',
}),
),
).resolves.not.toThrow();
let thrown: unknown = null;
try {
await guard.onAuthenticate(
makePayload({
documentName: '__config__/project',
peer: '127.0.0.1',
host: 'attacker.example.com',
}),
);
} catch (err) {
thrown = err;
}
expect(thrown).not.toBeNull();
} finally {
await server.destroy();
}
});
test('config doc rejects missing Host header (no fallback to permissive accept)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
let thrown: unknown = null;
try {
await guard.onAuthenticate(
makePayload({ documentName: '__config__/project', peer: '127.0.0.1', host: null }),
);
} catch (err) {
thrown = err;
}
expect(thrown).not.toBeNull();
expect((thrown as Error).message).toContain('loopback or remote Host header');
} finally {
await server.destroy();
}
});
test('config doc accepts undefined peer when Host is loopback (test harness shape)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
await expect(
guard.onAuthenticate(
makePayload({ documentName: '__config__/project', peer: undefined, host: 'localhost' }),
),
).resolves.toBeUndefined();
} finally {
await server.destroy();
}
});
test('config doc rejects attacker Host when peer is undefined (DNS rebinding with no socket)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
let thrown: unknown = null;
try {
await guard.onAuthenticate(
makePayload({
documentName: '__config__/project',
peer: undefined,
host: 'attacker.example.com',
}),
);
} catch (err) {
thrown = err;
}
expect(thrown).not.toBeNull();
expect((thrown as Error).message).toContain('loopback or remote Host header');
} finally {
await server.destroy();
}
});
test('config doc accepts loopback Host via req.headers fallback when requestHeaders absent', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const guard = getConfigDocAdmissionGuard(server);
await expect(
guard.onAuthenticate({
token: undefined,
documentName: '__config__/project',
context: {},
request: {
socket: { remoteAddress: '127.0.0.1' },
headers: { host: 'localhost:5173' },
},
} as unknown as Parameters<typeof guard.onAuthenticate>[0]),
).resolves.toBeUndefined();
} finally {
await server.destroy();
}
});
});
describe('createServer() — readProjectAutoSyncMode precedence', () => {
let testProjectDir: string;
let testHomedir: string;
beforeEach(() => {
testProjectDir = mkdtempSync(resolve(tmpdir(), 'ok-autosync-read-test-'));
testHomedir = mkdtempSync(resolve(tmpdir(), 'ok-autosync-read-home-'));
});
afterEach(() => {
rmSync(testProjectDir, { recursive: true, force: true });
rmSync(testHomedir, { recursive: true, force: true });
});
function seedProjectLocalConfig(content: string): void {
mkdirSync(join(testProjectDir, '.ok', LOCAL_DIR), { recursive: true });
writeFileSync(join(testProjectDir, '.ok', LOCAL_DIR, 'config.yml'), content, 'utf-8');
}
function seedProjectConfig(content: string): void {
mkdirSync(join(testProjectDir, '.ok'), { recursive: true });
writeFileSync(join(testProjectDir, '.ok', 'config.yml'), content, 'utf-8');
}
test('project-local autoSync.enabled: true → engine boots enabled', async () => {
seedProjectLocalConfig('autoSync:\n enabled: true\n');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(true);
await srv.destroy();
});
test('project-local absent + committed autoSync.default: true → engine boots enabled', async () => {
seedProjectConfig('autoSync:\n default: true\n');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(true);
await srv.destroy();
});
test('project-local absent + committed autoSync.default: false → engine boots disabled', async () => {
seedProjectConfig('autoSync:\n default: false\n');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(false);
await srv.destroy();
});
test('committed autoSync.enabled is ignored (scope-mismatched) → engine boots disabled', async () => {
seedProjectConfig('autoSync:\n enabled: true\n');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(false);
await srv.destroy();
});
test('both absent → engine boots disabled (default)', async () => {
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(false);
await srv.destroy();
});
test('project-local enabled: false beats committed default: true (machine override wins)', async () => {
seedProjectLocalConfig('autoSync:\n enabled: false\n');
seedProjectConfig('autoSync:\n default: true\n');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(false);
await srv.destroy();
});
test('project-local enabled: true beats committed default: false (machine override wins)', async () => {
seedProjectLocalConfig('autoSync:\n enabled: true\n');
seedProjectConfig('autoSync:\n default: false\n');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(true);
await srv.destroy();
});
test('project-local autoSync.enabled: null falls through to committed default: true', async () => {
seedProjectLocalConfig('autoSync:\n enabled: null\n');
seedProjectConfig('autoSync:\n default: true\n');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(true);
await srv.destroy();
});
test('invalid project-local YAML falls through to committed default (degraded path)', async () => {
seedProjectLocalConfig('autoSync:\n enabled: : not-yaml [[[\n');
seedProjectConfig('autoSync:\n default: true\n');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(true);
await srv.destroy();
});
test('invalid committed config defaults to disabled (degraded path)', async () => {
seedProjectConfig('autoSync:\n default: : not-yaml [[[\n');
const contentDir = mkdtempSync(resolve(testProjectDir, 'content-'));
const srv = createServer({
contentDir,
projectDir: testProjectDir,
quiet: true,
configHomedirOverride: testHomedir,
});
await srv.ready;
expect(srv.syncEngine?.getStatus().syncEnabled).toBe(false);
await srv.destroy();
});
});
describe('createServer() — protected-branch auto-disable persistence', () => {
test('persists autoSync.enabled=false to project-local config only', async () => {
const projectDir = mkdtempSync(resolve(tmpdir(), 'ok-auto-disable-test-'));
const homedir = mkdtempSync(resolve(tmpdir(), 'ok-auto-disable-home-'));
const contentDir = mkdtempSync(resolve(projectDir, 'content-'));
const projectConfigPath = resolveConfigPath('project', projectDir);
const localConfigPath = resolveConfigPath('project-local', projectDir);
mkdirSync(join(projectDir, '.ok', LOCAL_DIR), { recursive: true });
writeFileSync(projectConfigPath, 'autoSync:\n default: true\n', 'utf-8');
writeFileSync(localConfigPath, 'autoSync:\n enabled: true\n', 'utf-8');
const server = createServer({
contentDir,
projectDir,
quiet: true,
gitEnabled: false,
configHomedirOverride: homedir,
destroyTimeoutMs: 1_000,
});
try {
await server.ready;
const engine = server.syncEngine;
expect(engine).not.toBeNull();
expect(engine?.getStatus().syncEnabled).toBe(true);
const testEngine = engine as unknown as {
handleError: (
classified: ReturnType<typeof classifyGitError>,
operation: 'push' | 'pull',
) => void;
};
testEngine.handleError(
classifyGitError(new Error('remote: error: protected branch')),
'push',
);
expect(engine?.getStatus()).toMatchObject({
state: 'disabled',
syncEnabled: false,
pausedReason: 'protected-branch',
pushErrorCode: 'semantic-protected-branch',
});
await vi.waitFor(
() => {
const local = readConfigSafely({
absPath: localConfigPath,
sideline: false,
warn: () => {},
});
expect(local.valid).toBe(true);
expect(local.value.autoSync.enabled).toBe(false);
},
{ timeout: 2_000, interval: 20 },
);
const project = readConfigSafely({
absPath: projectConfigPath,
sideline: false,
warn: () => {},
});
expect(project.valid).toBe(true);
expect(project.value.autoSync.default).toBe(true);
expect(project.value.autoSync.enabled).toBeNull();
} finally {
await server.destroy();
rmSync(projectDir, { recursive: true, force: true });
rmSync(homedir, { recursive: true, force: true });
}
});
});
describe('createServer() — phantom-doc unload', () => {
let phantomTmpDir: string;
beforeEach(async () => {
phantomTmpDir = await mkdtemp(join(tmpdir(), 'ok-phantom-unload-'));
});
afterEach(async () => {
await rm(phantomTmpDir, { recursive: true, force: true });
});
async function waitForUnload(
server: ServerInstance,
docName: string,
timeoutMs: number,
): Promise<boolean> {
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
if (!server.hocuspocus.documents.has(docName)) return true;
await new Promise((r) => setTimeout(r, 25));
}
return !server.hocuspocus.documents.has(docName);
}
test('phantom doc (no on-disk file, no content) unloads after last disconnect', async () => {
const server = createServer({
contentDir: phantomTmpDir,
projectDir: phantomTmpDir,
quiet: true,
debounce: 50,
maxDebounce: 100,
});
try {
await server.ready;
const docName = 'never-on-disk';
const conn = await server.hocuspocus.openDirectConnection(docName);
expect(server.hocuspocus.documents.has(docName)).toBe(true);
await conn.disconnect();
const unloaded = await waitForUnload(server, docName, 2_000);
expect(unloaded).toBe(true);
} finally {
await server.destroy();
}
});
test('file-backed doc stays resident after disconnect', async () => {
const docName = 'on-disk';
writeFileSync(join(phantomTmpDir, `${docName}.md`), '# hello\n', 'utf-8');
const server = createServer({
contentDir: phantomTmpDir,
projectDir: phantomTmpDir,
quiet: true,
debounce: 50,
maxDebounce: 100,
});
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
expect(server.hocuspocus.documents.has(docName)).toBe(true);
await conn.disconnect();
const controlName = 'phantom-control';
const controlConn = await server.hocuspocus.openDirectConnection(controlName);
await controlConn.disconnect();
const controlUnloaded = await waitForUnload(server, controlName, 2_000);
expect(controlUnloaded).toBe(true);
expect(server.hocuspocus.documents.has(docName)).toBe(true);
} finally {
await server.destroy();
}
}, 15_000);
test('transient doc with CRDT content but no disk file stays resident', async () => {
const server = createServer({
contentDir: phantomTmpDir,
projectDir: phantomTmpDir,
quiet: true,
debounce: 60_000,
maxDebounce: 60_000,
});
try {
await server.ready;
const docName = 'transient-with-content';
const conn = await server.hocuspocus.openDirectConnection(docName);
await conn.transact((doc) => {
const fragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('user-typed-content')]);
fragment.insert(0, [paragraph]);
});
await conn.disconnect();
await new Promise((r) => setTimeout(r, 200));
expect(server.hocuspocus.documents.has(docName)).toBe(true);
} finally {
await server.destroy();
}
});
});
describe('createServer() — shouldUnloadDocument forceUnloadSet branched guard', () => {
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'ok-shouldunload-'));
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
test('force-unload via delete-path unloads document despite live in-process connection and non-empty content', async () => {
const docName = 'force-unload-target';
writeFileSync(join(tmpDir, `${docName}.md`), '# initial-content\n', 'utf-8');
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
});
let localHttp: import('node:http').Server | undefined;
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
expect(server.hocuspocus.documents.has(docName)).toBe(true);
await conn.transact((doc) => {
const ytext = doc.getText('source');
ytext.insert(0, 'pending-bytes');
});
const doc = server.hocuspocus.documents.get(docName);
if (!doc) throw new Error('document missing after transact');
expect(doc.getText('source').toString().length).toBeGreaterThan(0);
const apiExt = server.hocuspocus.configuration.extensions.find(
(e: unknown) =>
typeof (e as { onRequest?: unknown }).onRequest === 'function' &&
(e as { priority?: number }).priority === 100,
) as
| {
onRequest: (ctx: {
request: import('node:http').IncomingMessage;
response: import('node:http').ServerResponse;
}) => Promise<void>;
}
| undefined;
if (!apiExt) throw new Error('api-extension not found in extensions array');
const { createServer: createNodeHttp } = await import('node:http');
const nativeApi = server.nativeApi;
localHttp = createNodeHttp((req, res) => {
void (async () => {
if (await nativeApi.dispatch(req, res)) return;
await apiExt.onRequest({ request: req, response: res });
})();
});
await new Promise<void>((resolve) => localHttp?.listen(0, '127.0.0.1', resolve));
const address = localHttp.address();
if (typeof address !== 'object' || address === null) {
throw new Error('local HTTP server did not bind to a port');
}
const baseURL = `http://127.0.0.1:${address.port}`;
const res = await fetch(`${baseURL}/api/delete-path`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ kind: 'file', path: docName }),
});
expect(res.status).toBe(200);
expect(server.hocuspocus.documents.has(docName)).toBe(false);
} finally {
if (localHttp) {
await new Promise<void>((resolve, reject) =>
localHttp?.close((err) => (err ? reject(err) : resolve())),
);
}
await server.destroy();
}
});
});
describe('createServer() — removalRedirectGuard registration', () => {
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'ok-removal-redirect-'));
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
test('extension is registered with __kind: removal-redirect-guard', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const ext = server.hocuspocus.configuration.extensions.find(
(e) => (e as { __kind?: string }).__kind === 'removal-redirect-guard',
) as { onAuthenticate?: (payload: unknown) => Promise<void> } | undefined;
expect(ext).toBeDefined();
expect(typeof ext?.onAuthenticate).toBe('function');
} finally {
await server.destroy();
}
});
test('extension order: after configDocAdmissionGuard, before apiExtension', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const exts = server.hocuspocus.configuration.extensions;
const idx = (kind: string): number =>
exts.findIndex((e) => (e as { __kind?: string }).__kind === kind);
const principal = idx('principal-auth');
const configGuard = idx('config-doc-admission-guard');
const removal = idx('removal-redirect-guard');
expect(principal).toBeGreaterThan(-1);
expect(configGuard).toBeGreaterThan(principal);
expect(removal).toBeGreaterThan(configGuard);
} finally {
await server.destroy();
}
});
test('onAuthenticate admits a fresh docName (no file, no cache state)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const ext = server.hocuspocus.configuration.extensions.find(
(e) => (e as { __kind?: string }).__kind === 'removal-redirect-guard',
) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
if (!ext) throw new Error('removal-redirect-guard not registered');
let thrown: unknown = null;
try {
await ext.onAuthenticate({
token: undefined,
context: {},
documentName: 'fresh-doc',
});
} catch (err) {
thrown = err;
}
expect(thrown).toBeNull();
} finally {
await server.destroy();
}
});
test('onAuthenticate is a no-op for system docs (cache lookup never happens)', async () => {
const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
try {
await server.ready;
const ext = server.hocuspocus.configuration.extensions.find(
(e) => (e as { __kind?: string }).__kind === 'removal-redirect-guard',
) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
if (!ext) throw new Error('removal-redirect-guard not registered');
let thrown: unknown = null;
try {
await ext.onAuthenticate({
token: undefined,
context: {},
documentName: '__system__',
});
} catch (err) {
thrown = err;
}
expect(thrown).toBeNull();
} finally {
await server.destroy();
}
});
test('warm backlink reconciliation arms deletion rejection for a file removed offline', async () => {
writeFileSync(join(tmpDir, 'removed-offline.md'), '# Removed offline\n', 'utf-8');
const first = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
gitEnabled: false,
});
await first.ready;
await first.destroy();
releaseServerLock(first.lockDir);
unlinkSync(join(tmpDir, 'removed-offline.md'));
const restarted = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
gitEnabled: false,
});
try {
await restarted.ready;
const ext = restarted.hocuspocus.configuration.extensions.find(
(entry) => (entry as { __kind?: string }).__kind === 'removal-redirect-guard',
) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
if (!ext) throw new Error('removal-redirect-guard not registered');
await expect(
ext.onAuthenticate({
token: undefined,
context: {},
documentName: 'removed-offline',
}),
).rejects.toMatchObject({ reason: 'doc-deleted' });
} finally {
await restarted.destroy();
}
});
test('warm removal journal preserves rename redirects', async () => {
writeFileSync(join(tmpDir, 'renamed-source.md'), '# Renamed source\n', 'utf-8');
const first = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
gitEnabled: false,
});
await first.ready;
await first.destroy();
releaseServerLock(first.lockDir);
unlinkSync(join(tmpDir, 'renamed-source.md'));
writeFileSync(join(tmpDir, 'renamed-target.md'), '# Renamed target\n', 'utf-8');
saveRemovedDocsJournal(tmpDir, [
[
'renamed-source',
{
kind: 'renamed',
newDocName: 'renamed-target',
addedAt: Date.now(),
},
],
]);
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
gitEnabled: false,
});
try {
await server.ready;
const ext = server.hocuspocus.configuration.extensions.find(
(entry) => (entry as { __kind?: string }).__kind === 'removal-redirect-guard',
) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
if (!ext) throw new Error('removal-redirect-guard not registered');
await expect(
ext.onAuthenticate({
token: undefined,
context: {},
documentName: 'renamed-source',
}),
).rejects.toMatchObject({ reason: 'rename-redirect:renamed-target' });
} finally {
await server.destroy();
}
});
});
describe('createServer() — push-permission auth wiring', () => {
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'ok-auth-wiring-'));
const git = simpleGit(tmpDir);
await git.init(['--initial-branch=main']);
configureTestGitRepository(tmpDir);
expect
.soft((await simpleGit(tmpDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
writeFileSync(join(tmpDir, 'README.md'), 'seed\n', 'utf-8');
await git.add('.');
await git.commit('seed');
await git.addRemote('origin', 'https://github.com/inkeep/open-knowledge.git');
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
test('forwards detectGh + tokenStore through createServer → SyncEngine → probe call', async () => {
const detectGhStub: DetectGhFn = (host?: string) => ({
available: true,
token: `stub-token-for-${host ?? 'github.com'}`,
});
const tokenStoreStub: ProbeTokenStore = {
async get(host: string) {
return { token: `store-token-for-${host}` };
},
};
const detectGhAccountsStub: DetectGhAccountsFn = () => [{ login: 'stub', active: true }];
const probeCalls: CheckPushPermissionOptions[] = [];
const probeSpy = async (opts: CheckPushPermissionOptions): Promise<PushPermission> => {
probeCalls.push(opts);
return { kind: 'allowed' };
};
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
debounce: 60_000,
destroyTimeoutMs: 1_000,
detectGh: detectGhStub,
detectGhAccounts: detectGhAccountsStub,
tokenStore: tokenStoreStub,
checkPushPermissionFn: probeSpy,
});
try {
await server.ready;
expect(server.syncEngine).not.toBeNull();
await server.syncEngine?.refreshPushPermission();
expect(probeCalls.length).toBeGreaterThan(0);
const firstCall = probeCalls[0];
expect(firstCall.detectGh).toBe(detectGhStub);
expect(firstCall.detectGhAccounts).toBe(detectGhAccountsStub);
expect(firstCall.tokenStore).toBe(tokenStoreStub);
expect(firstCall.owner).toBe('inkeep');
expect(firstCall.repo).toBe('open-knowledge');
} finally {
await server.destroy();
}
});
test('omitting detectGh + tokenStore leaves the probe call with undefined seams (no silent default substitution)', async () => {
const probeCalls: CheckPushPermissionOptions[] = [];
const probeSpy = async (opts: CheckPushPermissionOptions): Promise<PushPermission> => {
probeCalls.push(opts);
return { kind: 'allowed' };
};
const server = createServer({
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
debounce: 60_000,
destroyTimeoutMs: 1_000,
checkPushPermissionFn: probeSpy,
});
try {
await server.ready;
await server.syncEngine?.refreshPushPermission();
expect(probeCalls.length).toBeGreaterThan(0);
expect(probeCalls[0].detectGh).toBeUndefined();
expect(probeCalls[0].tokenStore).toBeUndefined();
} finally {
await server.destroy();
}
});
});
describe('createServer() — generated index wiring', () => {
let projectDir: string;
let contentDir: string;
let server: ServerInstance | null;
let shadowHandle: Awaited<ReturnType<typeof initShadowRepo>>;
let localHttp: import('node:http').Server | null = null;
const indexPath = () => join(contentDir, 'index.md');
const readIndex = () => readFileSync(indexPath(), 'utf-8');
const indexPathAt = (dir: string) => join(contentDir, dir, 'index.md');
const readIndexAt = (dir: string) => readFileSync(indexPathAt(dir), 'utf-8');
async function waitForIndexAt(
dir: string,
predicate: (markdown: string) => boolean,
): Promise<void> {
await vi.waitFor(
() => {
expect(existsSync(indexPathAt(dir))).toBe(true);
expect(predicate(readIndexAt(dir))).toBe(true);
},
{ timeout: 20_000, interval: 50 },
);
}
function writeDoc(rel: string, title: string, type = 'note', description?: string): void {
const fm = [
`title: ${title}`,
`type: ${type}`,
...(description ? [`description: ${description}`] : []),
];
mkdirSync(join(contentDir, rel, '..'), { recursive: true });
writeFileSync(join(contentDir, rel), `---\n${fm.join('\n')}\n---\n\n# ${title}\n`, 'utf-8');
}
async function waitForIndex(predicate: (markdown: string) => boolean): Promise<void> {
await vi.waitFor(
() => {
expect(existsSync(indexPath())).toBe(true);
expect(predicate(readIndex())).toBe(true);
},
{ timeout: 20_000, interval: 50 },
);
}
async function bootServer(): Promise<ServerInstance> {
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
await prepareGeneratedIndexGitAttributes();
shadowHandle = await initShadowRepo(projectDir);
server = createServer({
contentDir,
projectDir,
contentRoot: 'content',
quiet: true,
shadowRepo: shadowHandle,
skipStateManifestCheck: true,
});
await server.ready;
await server.generatedIndexSweepReady;
return server;
}
async function startServerWithIndexHooks(
generatedIndexTestHooks: NonNullable<
Parameters<typeof createServer>[0]['generatedIndexTestHooks']
>,
): Promise<ServerInstance> {
await ensureProjectGit(projectDir);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
await prepareGeneratedIndexGitAttributes();
shadowHandle = await initShadowRepo(projectDir);
server = createServer({
contentDir,
projectDir,
contentRoot: 'content',
quiet: true,
shadowRepo: shadowHandle,
skipStateManifestCheck: true,
generatedIndexTestHooks,
});
return server;
}
async function prepareGeneratedIndexGitAttributes(): Promise<void> {
const config = readConfigSafely({
absPath: resolveConfigPath('project', projectDir),
sideline: false,
});
if (config.value.contentRules?.okf?.generate?.index !== true) return;
const result = await updateGeneratedIndexGitAttributes({
projectDir,
contentDir,
generatedDocNames: ['index'],
enabled: true,
});
expect(result.ok).toBe(true);
}
async function apiBaseUrl(): Promise<string> {
const apiExt = server?.hocuspocus.configuration.extensions.find(
(e: unknown) =>
typeof (e as { onRequest?: unknown }).onRequest === 'function' &&
(e as { priority?: number }).priority === 100,
) as
| {
onRequest: (ctx: {
request: import('node:http').IncomingMessage;
response: import('node:http').ServerResponse;
}) => Promise<void>;
}
| undefined;
if (!apiExt) throw new Error('api-extension not found in extensions array');
const { createServer: createNodeHttp } = await import('node:http');
const nativeApi = server?.nativeApi;
localHttp = createNodeHttp((req, res) => {
void (async () => {
if (nativeApi !== undefined && (await nativeApi.dispatch(req, res))) return;
await apiExt.onRequest({ request: req, response: res });
})();
});
await new Promise<void>((resolve) => localHttp?.listen(0, '127.0.0.1', resolve));
const address = localHttp.address();
if (typeof address !== 'object' || address === null) {
throw new Error('local HTTP server did not bind to a port');
}
return `http://127.0.0.1:${address.port}`;
}
async function agentWriteMd(baseUrl: string, docName: string, markdown: string): Promise<void> {
const res = await fetch(`${baseUrl}/api/agent-write-md`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ docName, markdown, position: 'replace' }),
});
const body = await res.text();
expect(res.status, body).toBe(200);
}
beforeEach(async () => {
projectDir = await mkdtemp(join(tmpdir(), 'ok-index-wiring-'));
contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
mkdirSync(join(projectDir, '.ok'), { recursive: true });
writeFileSync(
join(projectDir, '.ok', 'config.yml'),
stringifyYaml({ contentRules: { okf: { enabled: true, generate: { index: true } } } }),
'utf-8',
);
server = null;
});
async function cleanupFixture(): Promise<void> {
if (localHttp) {
await new Promise<void>((resolve, reject) =>
localHttp?.close((err) => (err ? reject(err) : resolve())),
);
localHttp = null;
}
try {
await server?.destroy();
} finally {
loggerFactory.reset();
await rm(projectDir, { recursive: true, force: true });
}
}
afterEach(cleanupFixture);
test('the setting reaches the server through the real config file', async () => {
await bootServer();
writeDoc('note.md', 'A note', 'note', 'Something to index.');
await waitForIndex((md) => md.includes('A note'));
expect(readIndex()).toContain('okf_version: "0.2"');
});
test('generated metadata warnings identify the production content directory', async () => {
const logs = captureAllLoggers();
writeDoc('warning.md', 'Parser\ue102warning', 'note');
await bootServer();
expect(logs.getLoggerEntries('generated-index')).toEqual([
{
level: 'warn',
msg: 'generated index metadata contained a parser-reserved private-use code point; replaced it with U+FFFD',
payload: { contentDir, path: 'warning.md', field: 'title', kind: 'parser-reservation' },
},
]);
});
test('server readiness settles before the boot index sweep starts planning', async () => {
writeDoc('existing.md', 'Existing at boot', 'note');
const { promise: planningEntered, resolve: enterPlanning } = Promise.withResolvers<void>();
const { promise: planningBarrier, resolve: releasePlanning } = Promise.withResolvers<void>();
let readySettled = false;
const activeServer = await startServerWithIndexHooks({
beforePlan: async ({ fullSweep }) => {
if (!fullSweep) return;
enterPlanning();
await planningBarrier;
},
});
void activeServer.ready.then(() => {
readySettled = true;
});
let sweepSettled = false;
void activeServer.generatedIndexSweepReady.then(() => {
sweepSettled = true;
});
await planningEntered;
expect(readySettled).toBe(true);
expect(sweepSettled).toBe(false);
expect(existsSync(indexPath())).toBe(false);
releasePlanning();
await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({
status: 'completed',
indexCount: 1,
});
expect(existsSync(indexPath())).toBe(true);
expect(readIndex()).toContain('* [Existing at boot](./existing.md)');
});
test('a non-fatal boot sweep error reports a failed settlement', async () => {
const activeServer = await startServerWithIndexHooks({
beforePlan: () => {
throw new Error('injected generated-index failure');
},
});
await expect(activeServer.ready).resolves.toBeUndefined();
await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({
status: 'failed',
indexCount: 0,
});
});
test('disabling generation stops an in-flight sweep before its next write', async () => {
writeDoc('alpha/a.md', 'Alpha', 'note');
writeDoc('beta/b.md', 'Beta', 'note');
const preservedRoot = '# Existing root index\n';
const preservedBeta = '# Existing beta index\n';
writeFileSync(indexPath(), preservedRoot, 'utf-8');
writeFileSync(indexPathAt('beta'), preservedBeta, 'utf-8');
const rootMtime = statSync(indexPath()).mtimeMs;
const betaMtime = statSync(indexPathAt('beta')).mtimeMs;
const { promise: firstWrite, resolve: firstWriteFinished } = Promise.withResolvers<void>();
const { promise: firstWriteBarrier, resolve: releaseFirstWrite } =
Promise.withResolvers<void>();
let paused = false;
const activeServer = await startServerWithIndexHooks({
afterWrite: async ({ docName }) => {
if (paused || docName !== 'alpha/index') return;
paused = true;
firstWriteFinished();
await firstWriteBarrier;
},
});
await activeServer.ready;
await firstWrite;
writeFileSync(
join(projectDir, '.ok', 'config.yml'),
stringifyYaml({ contentRules: { okf: { enabled: true, generate: { index: false } } } }),
'utf-8',
);
releaseFirstWrite();
await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({
status: 'disabled',
indexCount: 1,
});
await new Promise((resolve) => setTimeout(resolve, 750));
expect(existsSync(indexPathAt('alpha'))).toBe(true);
expect(readIndex()).toBe(preservedRoot);
expect(readIndexAt('beta')).toBe(preservedBeta);
expect(statSync(indexPath()).mtimeMs).toBe(rootMtime);
expect(statSync(indexPathAt('beta')).mtimeMs).toBe(betaMtime);
writeDoc('beta/after-disable.md', 'After disable', 'note');
await new Promise((resolve) => setTimeout(resolve, 750));
expect(readIndex()).toBe(preservedRoot);
expect(readIndexAt('beta')).toBe(preservedBeta);
expect(statSync(indexPath()).mtimeMs).toBe(rootMtime);
expect(statSync(indexPathAt('beta')).mtimeMs).toBe(betaMtime);
});
test('boot sweep readiness waits for live requests coalesced behind it', async () => {
writeDoc('anchor.md', 'Anchor', 'note');
const { promise: firstPassStarted, resolve: firstPassEntered } = Promise.withResolvers<void>();
const { promise: firstPassBarrier, resolve: releaseFirstPass } = Promise.withResolvers<void>();
const { promise: coordinatorSettled, resolve: coordinatorIdle } = Promise.withResolvers<void>();
const { promise: followupDeferredBySingleFlight, resolve: blockedKickObserved } =
Promise.withResolvers<void>();
let passCount = 0;
const activeServer = await startServerWithIndexHooks({
beforePlan: async () => {
passCount++;
if (passCount !== 1) return;
firstPassEntered();
await firstPassBarrier;
},
onIdle: () => {
if (passCount === 2) coordinatorIdle();
},
onKickWhileInFlight: blockedKickObserved,
});
await activeServer.ready;
await firstPassStarted;
let sweepSettled = false;
void activeServer.generatedIndexSweepReady.then(() => {
sweepSettled = true;
});
const baseUrl = await apiBaseUrl();
await agentWriteMd(baseUrl, 'one', '---\ntitle: One\ntype: note\n---\n\n# One\n');
await agentWriteMd(baseUrl, 'two', '---\ntitle: Two\ntype: note\n---\n\n# Two\n');
await agentWriteMd(baseUrl, 'three', '---\ntitle: Three\ntype: note\n---\n\n# Three\n');
await followupDeferredBySingleFlight;
expect(passCount).toBe(1);
releaseFirstPass();
await new Promise<void>((resolve) => setImmediate(resolve));
expect(sweepSettled).toBe(false);
await coordinatorSettled;
await expect(activeServer.generatedIndexSweepReady).resolves.toMatchObject({
status: 'completed',
});
expect(passCount).toBe(2);
expect(readIndex()).toContain('* [One](./one.md)');
expect(readIndex()).toContain('* [Two](./two.md)');
expect(readIndex()).toContain('* [Three](./three.md)');
});
test('destroy cancels and drains an in-flight generated-index write', async () => {
writeDoc('deep/note.md', 'Deep note', 'note');
const { promise: firstWritePaused, resolve: writePaused } = Promise.withResolvers<void>();
const { promise: writeBarrier, resolve: releaseWrite } = Promise.withResolvers<void>();
const { promise: regenerationAborted, resolve: abortObserved } = Promise.withResolvers<void>();
let blocked = false;
const activeServer = await startServerWithIndexHooks({
afterWrite: async ({ signal }) => {
if (blocked) return;
blocked = true;
signal.addEventListener('abort', abortObserved, { once: true });
writePaused();
await writeBarrier;
},
});
await activeServer.ready;
await firstWritePaused;
let destroySettled = false;
const destroying = activeServer.destroy().then(() => {
destroySettled = true;
});
await regenerationAborted;
expect(destroySettled).toBe(false);
expect(existsSync(indexPathAt('deep'))).toBe(true);
expect(existsSync(indexPath())).toBe(false);
releaseWrite();
await destroying;
await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({
status: 'cancelled',
indexCount: 1,
});
expect(existsSync(indexPath())).toBe(false);
});
test('creating a document lands its entry in its own folder index', async () => {
await bootServer();
writeDoc('concepts/first.md', 'First', 'concept');
await waitForIndexAt('concepts', (md) => md.includes('* [First](./first.md)'));
await waitForIndex((md) => md.includes('* [concepts](./concepts/index.md)'));
expect(readIndex()).not.toContain('./concepts/first.md');
writeDoc('concepts/second.md', 'Second', 'concept');
await waitForIndexAt('concepts', (md) => md.includes('* [Second](./second.md)'));
expect(readIndexAt('concepts')).toContain('* [First](./first.md)');
});
test('an external metadata update refreshes the existing entry', async () => {
writeDoc('note.md', 'Before', 'note', 'Old description');
await bootServer();
await waitForIndex((md) => md.includes('[Before]'));
writeDoc('note.md', 'After', 'concept', 'New description');
await waitForIndex(
(md) =>
md.includes('# concept') &&
md.includes('[After]') &&
md.includes('New description') &&
!md.includes('[Before]'),
);
});
test('settings endpoint commits the Git rule and config as one lifecycle operation', async () => {
writeFileSync(
join(projectDir, '.ok', 'config.yml'),
stringifyYaml({ contentRules: { okf: { enabled: true, generate: { index: false } } } }),
'utf-8',
);
writeDoc('waiting.md', 'Waiting', 'note');
const activeServer = await bootServer();
await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({
status: 'disabled',
indexCount: 0,
});
expect(existsSync(indexPath())).toBe(false);
expect(existsSync(join(projectDir, '.gitattributes'))).toBe(false);
const baseUrl = await apiBaseUrl();
const enabled = await fetch(`${baseUrl}/api/generated-index/settings`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ enabled: true }),
});
expect(enabled.status).toBe(200);
await expect(enabled.json()).resolves.toMatchObject({
enabled: true,
active: true,
applied: true,
git: { state: 'ready', ownership: 'open-knowledge' },
});
await waitForIndex((md) => md.includes('[Waiting]'));
expect(readFileSync(join(projectDir, '.gitattributes'), 'utf-8')).toContain(
'/content/**/index.md merge=union',
);
const indexBeforeDisable = readIndex();
const disabled = await fetch(`${baseUrl}/api/generated-index/settings`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ enabled: false }),
});
expect(disabled.status).toBe(200);
await expect(disabled.json()).resolves.toMatchObject({
enabled: false,
active: false,
applied: true,
});
expect(existsSync(join(projectDir, '.gitattributes'))).toBe(false);
expect(readIndex()).toBe(indexBeforeDisable);
});
test('settings endpoint rolls the Git rule back when the config write is rejected', async () => {
const invalidConfig = 'contentRules: [\n';
writeFileSync(join(projectDir, '.ok', 'config.yml'), invalidConfig, 'utf-8');
writeDoc('waiting.md', 'Waiting', 'note');
const activeServer = await bootServer();
await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({
status: 'disabled',
indexCount: 0,
});
const response = await fetch(`${await apiBaseUrl()}/api/generated-index/settings`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ enabled: true }),
});
expect(response.status).toBe(200);
await expect(response.json()).resolves.toMatchObject({
enabled: false,
active: false,
applied: false,
reason: 'config-write',
git: { state: 'missing' },
});
expect(readFileSync(join(projectDir, '.ok', 'config.yml'), 'utf-8')).toBe(invalidConfig);
expect(existsSync(join(projectDir, '.gitattributes'))).toBe(false);
expect(existsSync(indexPath())).toBe(false);
});
test('settings endpoint repairs a missing Git rule when config is already enabled', async () => {
writeFileSync(
join(projectDir, '.ok', 'config.yml'),
stringifyYaml({ contentRules: { okf: { enabled: true, generate: { index: true } } } }),
'utf-8',
);
const activeServer = await bootServer();
await activeServer.generatedIndexSweepReady;
unlinkSync(join(projectDir, '.gitattributes'));
expect(existsSync(join(projectDir, '.gitattributes'))).toBe(false);
const response = await fetch(`${await apiBaseUrl()}/api/generated-index/settings`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ enabled: true }),
});
expect(response.status).toBe(200);
await expect(response.json()).resolves.toMatchObject({
enabled: true,
active: true,
applied: true,
git: { state: 'ready', ownership: 'open-knowledge' },
});
await new Promise((resolve) => setTimeout(resolve, 100));
expect(readFileSync(join(projectDir, '.gitattributes'), 'utf-8')).toContain(
'/content/**/index.md merge=union',
);
});
test('external Git-attribute drift pauses regeneration and resumes after repair', async () => {
const logCapture = captureAllLoggers();
await bootServer();
writeDoc('note.md', 'Before drift', 'note');
await waitForIndex((md) => md.includes('[Before drift]'));
const preservedIndex = readIndex();
const preservedMtime = statSync(indexPath()).mtimeMs;
writeFileSync(
join(projectDir, '.gitattributes'),
'/content/index.md merge=ours\n/content/**/index.md merge=ours\n',
'utf-8',
);
writeDoc('note.md', 'Blocked by drift', 'note');
await vi.waitFor(
() => {
expect(
logCapture
.getCalls('warn', 'generated index regeneration paused by Git attributes')
.some((entry) => entry.payload.state === 'conflict'),
).toBe(true);
},
{ timeout: 20_000, interval: 50 },
);
expect(readIndex()).toBe(preservedIndex);
expect(statSync(indexPath()).mtimeMs).toBe(preservedMtime);
const pausedStatus = await fetch(`${await apiBaseUrl()}/api/generated-index/settings`);
expect(pausedStatus.status).toBe(200);
await expect(pausedStatus.json()).resolves.toMatchObject({
enabled: true,
active: false,
git: { state: 'conflict' },
});
unlinkSync(join(projectDir, '.gitattributes'));
const repaired = await updateGeneratedIndexGitAttributes({
projectDir,
contentDir,
generatedDocNames: ['index'],
enabled: true,
});
expect(repaired.ok).toBe(true);
writeDoc('note.md', 'Recovered after repair', 'note');
await waitForIndex(
(md) => md.includes('[Recovered after repair]') && !md.includes('[Before drift]'),
);
});
test('deleting an unopened document removes its entry from its folder index', async () => {
await bootServer();
writeDoc('concepts/doomed.md', 'Doomed', 'concept');
writeDoc('concepts/survivor.md', 'Survivor', 'concept');
await waitForIndexAt('concepts', (md) => md.includes('./doomed.md'));
unlinkSync(join(contentDir, 'concepts', 'doomed.md'));
await waitForIndexAt('concepts', (md) => !md.includes('./doomed.md'));
expect(readIndexAt('concepts')).toContain('./survivor.md');
});
test('an emptied section disappears rather than lingering as a bare heading', async () => {
await bootServer();
writeDoc('only.md', 'Only', 'solo-type');
writeDoc('keep.md', 'Keep', 'note');
await waitForIndex((md) => md.includes('## solo\\-type'));
unlinkSync(join(contentDir, 'only.md'));
await waitForIndex((md) => !md.includes('## solo\\-type'));
expect(readIndex()).toContain('## note');
});
test('a cross-directory rename through the watcher drops the source entry and lands the destination', async () => {
writeDoc('concepts/mover.md', 'Mover', 'concept');
writeDoc('concepts/keeper.md', 'Keeper', 'concept');
writeDoc('archive/anchor.md', 'Anchor', 'note');
await bootServer();
await waitForIndexAt('concepts', (md) => md.includes('./mover.md'));
await waitForIndexAt('archive', (md) => md.includes('./anchor.md'));
renameSync(join(contentDir, 'concepts', 'mover.md'), join(contentDir, 'archive', 'mover.md'));
await waitForIndexAt('archive', (md) => md.includes('./mover.md'));
await waitForIndexAt(
'concepts',
(md) => !md.includes('./mover.md') && md.includes('./keeper.md'),
);
});
test('moving a directory last admitted document preserves its orphan index', async () => {
writeDoc('source/only.md', 'Only', 'note');
writeDoc('destination/anchor.md', 'Anchor', 'note');
await bootServer();
await server?.generatedIndexSweepReady;
await waitForIndex(
(md) => md.includes('./source/index.md') && md.includes('./destination/index.md'),
);
const orphanBytes = readIndexAt('source');
const orphanMtime = statSync(indexPathAt('source')).mtimeMs;
renameSync(join(contentDir, 'source', 'only.md'), join(contentDir, 'destination', 'only.md'));
await waitForIndexAt(
'destination',
(md) => md.includes('./only.md') && md.includes('./anchor.md'),
);
await waitForIndex(
(md) => !md.includes('./source/index.md') && md.includes('./destination/index.md'),
);
expect(readIndexAt('source')).toBe(orphanBytes);
expect(statSync(indexPathAt('source')).mtimeMs).toBe(orphanMtime);
});
test('a rebuild lands on the ok-generator ref, not a human or service writer', async () => {
await bootServer();
writeDoc('note.md', 'A note', 'note', 'Something to index.');
await waitForIndex((md) => md.includes('A note'));
const sg = shadowGit(shadowHandle);
await vi.waitFor(
async () => {
const out = (await sg.raw('for-each-ref', '--format=%(refname)', 'refs/wip/')).trim();
expect(out).toContain('ok-generator');
},
{ timeout: 20_000, interval: 100 },
);
});
test('logs one bounded written outcome for every attempted boot decision', async () => {
const logCapture = captureAllLoggers();
writeDoc('concepts/first.md', 'First', 'concept');
await bootServer();
const events = logCapture
.getCalls()
.filter((entry) => entry.payload.event === 'generated-index-regeneration');
expect(events.map((entry) => entry.payload)).toEqual([
{ event: 'generated-index-regeneration', outcome: 'written', directory: 'concepts' },
{ event: 'generated-index-regeneration', outcome: 'written', directory: '' },
]);
});
test('a rebuild that computes identical bytes performs no write', async () => {
const logCapture = captureAllLoggers();
await bootServer();
writeDoc('note.md', 'A note', 'note', 'A description.');
await waitForIndex((md) => md.includes('A note'));
const regenerationEvents = () =>
logCapture
.getCalls()
.filter((entry) => entry.payload.event === 'generated-index-regeneration');
const baselineEventCount = regenerationEvents().length;
const settled = statSync(indexPath()).mtimeMs;
const bytes = readIndex();
writeFileSync(join(contentDir, 'log.md'), '# Log\n\n## 2026-08-05\n\n- An entry.\n', 'utf-8');
await vi.waitFor(
() => {
expect(
regenerationEvents()
.slice(baselineEventCount)
.map((entry) => entry.payload),
).toEqual([{ event: 'generated-index-regeneration', outcome: 'unchanged', directory: '' }]);
},
{ timeout: 20_000, interval: 50 },
);
expect(readIndex()).toBe(bytes);
expect(statSync(indexPath()).mtimeMs).toBe(settled);
});
test('an unopened tracked index conflict preserves exact bytes until resolution', async () => {
writeDoc('concepts/first.md', 'First', 'concept');
const conflicted = [
'<<<<<<< HEAD',
'# Mine',
'=======',
'# Theirs',
'>>>>>>> incoming',
'',
].join('\n');
writeFileSync(indexPathAt('concepts'), conflicted, 'utf-8');
mkdirSync(join(projectDir, '.ok', LOCAL_DIR), { recursive: true });
writeFileSync(
join(projectDir, '.ok', LOCAL_DIR, 'conflicts.json'),
JSON.stringify({
version: 1,
branch: 'main',
conflicts: [
{
kind: 'reconcile',
file: 'content/concepts/index.md',
detectedAt: '2026-08-07T00:00:00.000Z',
reason: 'disk-markers',
stages: { base: '', ours: '', theirs: conflicted },
},
],
}),
'utf-8',
);
const conflictedMtime = statSync(indexPathAt('concepts')).mtimeMs;
const logCapture = captureAllLoggers();
await bootServer();
expect(server?.hocuspocus.documents.has('concepts/index')).toBe(false);
expect(server?.conflicts.list()).toEqual([
expect.objectContaining({ kind: 'reconcile', file: 'content/concepts/index.md' }),
]);
writeFileSync(
join(contentDir, 'concepts', 'log.md'),
'# Log\n\n## 2026-08-06\n\n- Trigger regeneration.\n',
'utf-8',
);
await vi.waitFor(
() => {
expect(
logCapture
.getCalls('warn', 'generated index regeneration blocked by active conflict')
.some((entry) => entry.payload.directory === 'concepts'),
).toBe(true);
},
{ timeout: 20_000, interval: 50 },
);
expect(readIndexAt('concepts')).toBe(conflicted);
expect(statSync(indexPathAt('concepts')).mtimeMs).toBe(conflictedMtime);
server?.conflicts.dissolveReconcile('concepts/index');
expect(server?.conflicts.list()).toEqual([]);
writeDoc('concepts/second.md', 'Second', 'concept');
await waitForIndexAt(
'concepts',
(md) => md.includes('* [First](./first.md)') && md.includes('* [Second](./second.md)'),
);
expect(readIndexAt('concepts')).not.toMatch(/^(<<<<<<<|=======|>>>>>>>)/m);
});
test('a live index conflict blocks regeneration until the conflict is resolved', async () => {
const logCapture = captureAllLoggers();
await bootServer();
writeDoc('concepts/first.md', 'First', 'concept');
await waitForIndexAt('concepts', (md) => md.includes('* [First](./first.md)'));
await waitForIndex((md) => md.includes('* [concepts](./concepts/index.md)'));
const canonical = readIndexAt('concepts');
const connection = await server?.hocuspocus.openDirectConnection('concepts/index');
const document = server?.hocuspocus.documents.get('concepts/index');
expect(document).toBeDefined();
expect(document?.getText('source').toString()).toBe(canonical);
const conflicted = [
'<<<<<<< HEAD',
canonical.trimEnd(),
'=======',
canonical.replace('[First]', '[Conflicted first]').trimEnd(),
'>>>>>>> incoming',
'',
].join('\n');
writeFileSync(indexPathAt('concepts'), conflicted, 'utf-8');
await vi.waitFor(
() => {
expect(server?.conflicts.findByDocName('concepts/index')).toMatchObject({
kind: 'reconcile',
reason: 'disk-markers',
});
},
{ timeout: 20_000, interval: 50 },
);
const regenerationEvents = () =>
logCapture
.getCalls()
.filter((entry) => entry.payload.event === 'generated-index-regeneration');
const baselineEventCount = regenerationEvents().length;
writeDoc('concepts/second.md', 'Second', 'concept');
await vi.waitFor(
() => {
expect(regenerationEvents().slice(baselineEventCount)).toEqual([
{
level: 'warn',
msg: '[index] generated index regeneration blocked by active conflict',
payload: {
event: 'generated-index-regeneration',
outcome: 'blocked',
directory: 'concepts',
reason: 'conflict',
},
},
{
level: 'info',
msg: '[index] generated index regeneration completed',
payload: {
event: 'generated-index-regeneration',
outcome: 'unchanged',
directory: '',
},
},
]);
},
{ timeout: 20_000, interval: 50 },
);
expect(readIndexAt('concepts')).toBe(conflicted);
expect(document?.getText('source').toString()).toBe(canonical);
expect(server?.conflicts.findByDocName('concepts/index')).toMatchObject({
kind: 'reconcile',
reason: 'disk-markers',
});
writeFileSync(indexPathAt('concepts'), canonical, 'utf-8');
await vi.waitFor(
() => {
expect(server?.conflicts.findByDocName('concepts/index')).toBeUndefined();
},
{ timeout: 20_000, interval: 50 },
);
writeDoc('concepts/third.md', 'Third', 'concept');
await waitForIndexAt(
'concepts',
(md) => md.includes('./second.md') && md.includes('./third.md'),
);
expect(readIndexAt('concepts')).not.toMatch(/^(<<<<<<<|=======|>>>>>>>)/m);
await connection?.disconnect();
});
test('a rebuild reaches an open document THROUGH the CRDT, not behind its back', async () => {
const logCapture = captureAllLoggers();
await bootServer();
writeDoc('first.md', 'First', 'note');
await waitForIndex((md) => md.includes('./first.md'));
const conn = await server?.hocuspocus.openDirectConnection('index');
const doc = server?.hocuspocus.documents.get('index');
expect(doc).toBeDefined();
const origins: unknown[] = [];
doc?.on('update', (_update: Uint8Array, origin: unknown) => origins.push(origin));
const regenerationEvents = () =>
logCapture
.getCalls()
.filter((entry) => entry.payload.event === 'generated-index-regeneration');
const baselineEventCount = regenerationEvents().length;
writeDoc('second.md', 'Second', 'note');
await vi.waitFor(
() => {
const live = doc?.getText('source').toString() ?? '';
expect(live).toContain('./second.md');
expect(live).toContain('./first.md');
},
{ timeout: 20_000, interval: 50 },
);
const viaGenerator = origins.some(
(o) =>
typeof o === 'object' &&
o !== null &&
(o as { context?: { origin?: string } }).context?.origin === 'generated-index',
);
expect(viaGenerator).toBe(true);
expect(
regenerationEvents()
.slice(baselineEventCount)
.map((entry) => entry.payload),
).toEqual([{ event: 'generated-index-regeneration', outcome: 'written', directory: '' }]);
await conn?.disconnect();
});
test('a document edit rebuilds only its own folder index, not a sibling', async () => {
await bootServer();
writeDoc('alpha/a.md', 'A one', 'note');
writeDoc('beta/b.md', 'B one', 'note');
await waitForIndexAt('alpha', (md) => md.includes('[A one]'));
await waitForIndexAt('beta', (md) => md.includes('[B one]'));
const betaBefore = readIndexAt('beta');
const betaMtimeBefore = statSync(indexPathAt('beta')).mtimeMs;
writeDoc('alpha/a.md', 'A renamed', 'note');
await waitForIndexAt('alpha', (md) => md.includes('[A renamed]') && !md.includes('[A one]'));
expect(readIndexAt('beta')).toBe(betaBefore);
expect(statSync(indexPathAt('beta')).mtimeMs).toBe(betaMtimeBefore);
});
test('editing only body prose rebuilds no index', async () => {
await bootServer();
writeDoc('notes/n.md', 'A note', 'note', 'A description.');
await waitForIndexAt('notes', (md) => md.includes('[A note]'));
const before = readIndexAt('notes');
const mtimeBefore = statSync(indexPathAt('notes')).mtimeMs;
writeFileSync(
join(contentDir, 'notes', 'n.md'),
'---\ntitle: A note\ntype: note\ndescription: A description.\n---\n\n# A note\n\nRewritten prose.\n',
'utf-8',
);
await new Promise((r) => setTimeout(r, 3_000));
expect(readIndexAt('notes')).toBe(before);
expect(statSync(indexPathAt('notes')).mtimeMs).toBe(mtimeBefore);
});
test('an agent write through the API that changes a field rebuilds its folder index', async () => {
await bootServer();
writeDoc('notes/n.md', 'Before', 'note', 'A description.');
await waitForIndexAt('notes', (md) => md.includes('[Before]'));
const api = await apiBaseUrl();
await agentWriteMd(
api,
'notes/n',
'---\ntitle: After\ntype: note\ndescription: A description.\n---\n\n# After\n',
);
await waitForIndexAt('notes', (md) => md.includes('[After]') && !md.includes('[Before]'));
});
test('an agent write through the API that changes only body prose rebuilds no index', async () => {
await bootServer();
writeDoc('notes/n.md', 'A note', 'note', 'A description.');
await waitForIndexAt('notes', (md) => md.includes('[A note]'));
const api = await apiBaseUrl();
const before = readIndexAt('notes');
const mtimeBefore = statSync(indexPathAt('notes')).mtimeMs;
await agentWriteMd(
api,
'notes/n',
'---\ntitle: A note\ntype: note\ndescription: A description.\n---\n\n# A note\n\nRewritten prose.\n',
);
await new Promise((r) => setTimeout(r, 3_000));
expect(readIndexAt('notes')).toBe(before);
expect(statSync(indexPathAt('notes')).mtimeMs).toBe(mtimeBefore);
});
test('deleting a populated subdirectory drops it from its parent index', async () => {
await bootServer();
writeDoc('area/top.md', 'Top', 'note');
writeDoc('area/sub/deep.md', 'Deep', 'note');
await waitForIndexAt('area', (md) => md.includes('* [sub](./sub/index.md)'));
expect(readIndexAt('area')).toContain('./top.md');
rmSync(join(contentDir, 'area', 'sub'), { recursive: true, force: true });
await waitForIndexAt('area', (md) => !md.includes('./sub/index.md'));
expect(readIndexAt('area')).toContain('./top.md');
});
test('deleting a directory last admitted document preserves its orphan index', async () => {
writeDoc('area/only.md', 'Only', 'note');
await bootServer();
await server?.generatedIndexSweepReady;
await waitForIndexAt('area', (md) => md.includes('./only.md'));
await waitForIndex((md) => md.includes('* [area](./area/index.md)'));
const orphanBytes = readIndexAt('area');
const orphanMtime = statSync(indexPathAt('area')).mtimeMs;
unlinkSync(join(contentDir, 'area', 'only.md'));
await waitForIndex((md) => !md.includes('./area/index.md'));
expect(readIndexAt('area')).toBe(orphanBytes);
expect(statSync(indexPathAt('area')).mtimeMs).toBe(orphanMtime);
});
test('a burst across two folders settles both in one convergence', async () => {
await bootServer();
writeDoc('one/a.md', 'A', 'note');
writeDoc('one/b.md', 'B', 'note');
writeDoc('two/c.md', 'C', 'note');
await waitForIndexAt('one', (md) => md.includes('[A]') && md.includes('[B]'));
await waitForIndexAt('two', (md) => md.includes('[C]'));
await waitForIndex((md) => md.includes('./one/index.md') && md.includes('./two/index.md'));
});
test('enabling generation sweeps nested folders, not only the root', async () => {
writeFileSync(
join(projectDir, '.ok', 'config.yml'),
stringifyYaml({ contentRules: { okf: { enabled: true, generate: { index: false } } } }),
'utf-8',
);
writeDoc('deep/leaf.md', 'Leaf', 'note');
await bootServer();
expect(existsSync(indexPath())).toBe(false);
expect(existsSync(indexPathAt('deep'))).toBe(false);
const baseUrl = await apiBaseUrl();
const enabled = await fetch(`${baseUrl}/api/generated-index/settings`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ enabled: true }),
});
expect(enabled.status).toBe(200);
await expect(enabled.json()).resolves.toMatchObject({
enabled: true,
active: true,
applied: true,
});
await waitForIndexAt('deep', (md) => md.includes('[Leaf]'));
await waitForIndex((md) => md.includes('./deep/index.md'));
});
test("a document in a pre-existing folder reaches the folder's parent index", async () => {
mkdirSync(join(contentDir, 'concepts'), { recursive: true });
writeDoc('anchor.md', 'Anchor', 'note');
await bootServer();
await waitForIndex((md) => md.includes('[Anchor]'));
expect(readIndex()).not.toContain('./concepts/index.md');
writeDoc('concepts/first.md', 'First', 'concept');
await waitForIndexAt('concepts', (md) => md.includes('* [First](./first.md)'));
await waitForIndex((md) => md.includes('* [concepts](./concepts/index.md)'));
const childMtime = statSync(indexPathAt('concepts')).mtimeMs;
const rootMtime = statSync(indexPath()).mtimeMs;
await new Promise((r) => setTimeout(r, 2_000));
expect(statSync(indexPathAt('concepts')).mtimeMs).toBe(childMtime);
expect(statSync(indexPath()).mtimeMs).toBe(rootMtime);
});
test('a cold boot converges a multi-depth tree in a single pass', async () => {
writeDoc('root-note.md', 'Root note', 'note');
writeDoc('topic/overview.md', 'Overview', 'concept');
writeDoc('topic/deep/detail.md', 'Detail', 'concept');
writeDoc('container/leaf/item.md', 'Item', 'note');
const decisionOrder: string[] = [];
const activeServer = await startServerWithIndexHooks({
beforeDecision: ({ directory, fullSweep }) => {
if (fullSweep) decisionOrder.push(directory);
},
});
await activeServer.ready;
await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({
status: 'completed',
indexCount: 5,
});
expect(decisionOrder).toEqual(['container/leaf', 'topic/deep', 'container', 'topic', '']);
expect(existsSync(indexPath())).toBe(true);
for (const dir of ['topic', 'topic/deep', 'container', 'container/leaf']) {
expect(existsSync(indexPathAt(dir))).toBe(true);
}
const root = readIndex();
expect(root).toContain('* [Root note](./root-note.md)');
expect(root).toContain('* [container](./container/index.md)');
expect(root).toContain('* [topic](./topic/index.md)');
expect(root).not.toContain('./topic/overview.md');
const topic = readIndexAt('topic');
expect(topic).toContain('* [Overview](./overview.md)');
expect(topic).toContain('* [deep](./deep/index.md)');
const deep = readIndexAt('topic/deep');
expect(deep).toContain('* [Detail](./detail.md)');
expect(deep).not.toContain('## Subdirectories');
const container = readIndexAt('container');
expect(container).toContain('* [leaf](./leaf/index.md)');
expect(container).not.toContain('## note');
expect(readIndexAt('container/leaf')).toContain('* [Item](./item.md)');
});
test('a second boot over a converged tree rewrites no index', async () => {
writeDoc('root-note.md', 'Root note', 'note');
writeDoc('topic/overview.md', 'Overview', 'concept');
writeDoc('topic/deep/detail.md', 'Detail', 'concept');
writeDoc('container/leaf/item.md', 'Item', 'note');
await bootServer();
const indexed = ['', 'topic', 'topic/deep', 'container', 'container/leaf'];
const snapshot = indexed.map((dir) => {
const path = dir === '' ? indexPath() : indexPathAt(dir);
return { path, bytes: readFileSync(path, 'utf-8'), mtime: statSync(path).mtimeMs };
});
await server?.destroy();
await bootServer();
for (const { path, bytes, mtime } of snapshot) {
expect(readFileSync(path, 'utf-8')).toBe(bytes);
expect(statSync(path).mtimeMs).toBe(mtime);
}
});
const UNION_FIXTURE_ANCESTOR_INDEX = [
'---',
'okf_version: "0.2"',
'---',
'',
'# Index',
'',
'## Guide',
'',
'* [Alpha](./alpha.md)',
'',
'## Index',
'',
'* [Home](./README.md)',
'',
].join('\n');
const UNION_FIXTURE_OLD_SHAPE_BRANCH_INDEX = [
'---',
'okf_version: "0.2"',
'---',
'',
'# Index',
'',
'## Guide',
'',
'* [Alpha](./alpha.md)',
'* [Beta](./beta.md)',
'',
'## Index',
'',
'* [Home](./README.md)',
'',
].join('\n');
const UNION_FIXTURE_NEW_SHAPE_BRANCH_INDEX = [
'---',
'okf_version: "0.2"',
'---',
'',
'# Index',
'',
'* [Home](./README.md)',
'',
'## Guide',
'',
'* [Alpha](./alpha.md)',
'',
].join('\n');
const UNION_FIXTURE_EXPECTED_SWEPT_INDEX = [
'---',
'okf_version: "0.2"',
'---',
'',
'# Index',
'',
'* [Home](./README.md)',
'',
'## Guide',
'',
'* [Alpha](./alpha.md)',
'* [Beta](./beta.md)',
'',
].join('\n');
const DEFAULT_PROFILE_LINT_CONFIG: LinterConfig = {
...DEFAULT_LINTER_CONFIG,
enabled: true,
plugins: {
...DEFAULT_LINTER_CONFIG.plugins,
markdownlint: { ...DEFAULT_LINTER_CONFIG.plugins.markdownlint, enabled: true },
okf: { enabled: true },
},
};
async function lintIndexCodes(markdown: string): Promise<string[]> {
const findings = await lintDocument(markdown, DEFAULT_PROFILE_LINT_CONFIG, 'index.md');
return findings.map((finding) => finding.code);
}
function countOccurrences(haystack: string, needle: string): number {
return haystack.split(needle).length - 1;
}
function fixtureGit(...args: string[]): string {
const result = spawnSync(
'git',
[
'-c',
'user.name=Open Knowledge Test',
'-c',
'[email protected]',
'-c',
'commit.gpgsign=false',
'-c',
'core.autocrlf=false',
'-c',
'core.attributesFile=',
'-c',
'core.hooksPath=',
...args,
],
{ cwd: projectDir, encoding: 'utf-8' },
);
const ended = result.signal ? `killed by ${result.signal}` : `exited ${result.status}`;
expect(
result.status,
`git ${args.join(' ')} ${ended}\n${result.stdout ?? ''}${result.stderr ?? ''}${result.error?.message ?? ''}`,
).toBe(0);
return result.stdout ?? '';
}
async function commitOldShapeAncestorUnderUnionMerge(): Promise<string> {
fixtureGit('init', '-q', '--template=');
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
const installed = await updateGeneratedIndexGitAttributes({
projectDir,
contentDir,
generatedDocNames: ['index'],
enabled: true,
});
expect(installed.ok).toBe(true);
expect(installed.status).toEqual({ state: 'ready', ownership: 'open-knowledge' });
writeDoc('README.md', 'Home', 'Index');
writeDoc('alpha.md', 'Alpha', 'Guide');
writeFileSync(indexPath(), UNION_FIXTURE_ANCESTOR_INDEX, 'utf-8');
fixtureGit('add', '-A');
fixtureGit('commit', '-qm', 'old-shape ancestor index');
return fixtureGit('branch', '--show-current').trim();
}
test('a union merge across the index layout change leaves a duplicated entry that one boot sweep repairs to canonical bytes', async () => {
const baseBranch = await commitOldShapeAncestorUnderUnionMerge();
fixtureGit('checkout', '-q', '-b', 'edits-the-old-shape-index');
writeDoc('beta.md', 'Beta', 'Guide');
writeFileSync(indexPath(), UNION_FIXTURE_OLD_SHAPE_BRANCH_INDEX, 'utf-8');
fixtureGit('add', '-A');
fixtureGit('commit', '-qm', 'add beta to the old-shape guide section');
fixtureGit('checkout', '-q', baseBranch);
writeFileSync(indexPath(), UNION_FIXTURE_NEW_SHAPE_BRANCH_INDEX, 'utf-8');
fixtureGit('add', '-A');
fixtureGit('commit', '-qm', 'regenerate the index in the new shape');
fixtureGit('merge', '--no-edit', '-q', 'edits-the-old-shape-index');
const merged = readIndex();
expect(await lintIndexCodes(merged)).toEqual(['MD024']);
expect(countOccurrences(merged, '* [Home](./README.md)')).toBe(2);
expect(merged).toContain('## Index');
expect(UNION_FIXTURE_EXPECTED_SWEPT_INDEX).not.toBe(UNION_FIXTURE_OLD_SHAPE_BRANCH_INDEX);
expect(UNION_FIXTURE_EXPECTED_SWEPT_INDEX).not.toBe(UNION_FIXTURE_NEW_SHAPE_BRANCH_INDEX);
const fullSweepDirectories: string[] = [];
const activeServer = await startServerWithIndexHooks({
beforeDecision: ({ directory, fullSweep }) => {
if (fullSweep) fullSweepDirectories.push(directory);
},
});
await activeServer.ready;
await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({
status: 'completed',
indexCount: 1,
});
expect(fullSweepDirectories).toEqual(['']);
const swept = readIndex();
expect(swept).toBe(UNION_FIXTURE_EXPECTED_SWEPT_INDEX);
expect(await lintIndexCodes(swept)).toEqual([]);
});
test('the layout upgrade alone merges to canonical bytes that the boot sweep leaves unwritten', async () => {
const logCapture = captureAllLoggers();
const baseBranch = await commitOldShapeAncestorUnderUnionMerge();
fixtureGit('checkout', '-q', '-b', 'leaves-the-index-alone');
writeFileSync(
join(contentDir, 'alpha.md'),
'---\ntitle: Alpha\ntype: Guide\n---\n\n# Alpha\n\nRevised prose.\n',
'utf-8',
);
fixtureGit('add', '-A');
fixtureGit('commit', '-qm', 'revise alpha without touching the index');
fixtureGit('checkout', '-q', baseBranch);
writeDoc('beta.md', 'Beta', 'Guide');
writeFileSync(indexPath(), UNION_FIXTURE_EXPECTED_SWEPT_INDEX, 'utf-8');
fixtureGit('add', '-A');
fixtureGit('commit', '-qm', 'add beta and regenerate the index in the new shape');
fixtureGit('merge', '--no-edit', '-q', 'leaves-the-index-alone');
const merged = readIndex();
expect(merged).toBe(UNION_FIXTURE_EXPECTED_SWEPT_INDEX);
const bytesBeforeBoot = merged;
const mtimeBeforeBoot = statSync(indexPath()).mtimeMs;
const activeServer = await startServerWithIndexHooks({});
await activeServer.ready;
await expect(activeServer.generatedIndexSweepReady).resolves.toEqual({
status: 'completed',
indexCount: 1,
});
expect(
logCapture
.getCalls()
.filter((entry) => entry.payload.event === 'generated-index-regeneration')
.map((entry) => entry.payload),
).toEqual([{ event: 'generated-index-regeneration', outcome: 'unchanged', directory: '' }]);
expect(readIndex()).toBe(bytesBeforeBoot);
expect(statSync(indexPath()).mtimeMs).toBe(mtimeBeforeBoot);
});
});
interface ReconcileRig {
tmpDir: string;
shadow: ShadowHandle;
cleanup: () => void;
}
async function setupReconcileRig(prefix: string): Promise<ReconcileRig> {
const tmpDir = await realpath(mkdtempSync(join(tmpdir(), prefix)));
const git = simpleGit({ baseDir: tmpDir });
await git.init();
configureTestGitRepository(tmpDir);
expect.soft((await simpleGit(tmpDir).listConfig('local')).all['maintenance.auto']).toBe('false');
await git.raw('symbolic-ref', 'HEAD', 'refs/heads/main');
await git.addConfig('user.name', 'Test User');
await git.addConfig('user.email', '[email protected]');
const shadow = await initShadowRepo(tmpDir);
return {
tmpDir,
shadow,
cleanup: () => rmSync(tmpDir, { recursive: true, force: true }),
};
}
function createReconcileServer(
rig: ReconcileRig,
watcher: Pick<ServerOptions, 'watcherBackend' | 'freshnessIntervalMs'> = {},
): ServerInstance {
return createServer({
contentDir: rig.tmpDir,
projectDir: rig.tmpDir,
quiet: true,
debounce: 100,
maxDebounce: 500,
gitEnabled: false,
shadowRepo: rig.shadow,
...watcher,
});
}
function persistedStaleExternalWrite(
projectDir: string,
docName: string,
): Record<string, unknown> | undefined {
const snapshot = join(projectDir, '.ok', LOCAL_DIR, 'stale-external-writes.json');
if (!existsSync(snapshot)) return undefined;
const parsed = JSON.parse(readFileSync(snapshot, 'utf-8')) as {
branches: Record<string, { docName: string; staleExternalWrite?: Record<string, unknown> }[]>;
};
return parsed.branches.main?.find((entry) => entry.docName === docName)?.staleExternalWrite;
}
async function expectAbsentDuring(
read: () => Promise<string[]>,
absent: string,
durationMs = 1_000,
): Promise<void> {
const deadline = Date.now() + durationMs;
while (Date.now() < deadline) {
const names = await read();
expect(names).not.toContain(absent);
await new Promise((r) => setTimeout(r, 50));
}
}
describe('createServer() — disk-event reconcile with an absent reconciled base', () => {
let rig: ReconcileRig;
beforeEach(() => {
resetMetrics();
});
afterEach(() => {
rig?.cleanup();
});
test('an external disk update on a loaded doc with an absent base adopts disk content instead of concatenating it', async () => {
rig = await setupReconcileRig('ok-reconcile-absent-base-');
const docName = 'absent-base-target';
const initial = '# Absent base target\n\nParagraph that only the editor doc holds.\n';
const theirs = '# Absent base target\n\nDisk-authoritative replacement paragraph.\n';
const docPath = join(rig.tmpDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.deleteReconciledBase(docName);
expect(server.durabilityState.getReconciledBase(docName)).toBeUndefined();
writeFileSync(docPath, theirs, 'utf-8');
await vi.waitFor(() => expect(serverDoc.getText('source').toString()).toBe(theirs), {
timeout: 8_000,
interval: 25,
});
expect(serverDoc.getText('source').toString()).not.toContain(
'Paragraph that only the editor doc holds.',
);
expect(server.durabilityState.getReconciledBase(docName)).toBe(theirs);
expect(readFileSync(docPath, 'utf-8')).toBe(theirs);
await vi.waitFor(
async () => {
const rescues = await listRescueCheckpoints(rig.shadow, 'main');
expect(rescues.map((r) => r.docName)).toContain(docName);
},
{ timeout: 10_000, interval: 50 },
);
conn.disconnect();
} finally {
await server.destroy();
}
}, 30_000);
test('delete-path teardown with an absent base still rescues a non-empty doc and spares an empty doc', async () => {
rig = await setupReconcileRig('ok-reconcile-rescue-guard-');
const fullDoc = 'rescue-guard-full';
const emptyDoc = 'rescue-guard-empty';
const fullContent = '# Rescue guard full\n\nLive body that exists only in the editor doc.\n';
writeFileSync(join(rig.tmpDir, `${fullDoc}.md`), fullContent, 'utf-8');
writeFileSync(join(rig.tmpDir, `${emptyDoc}.md`), '', 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
await server.hocuspocus.openDirectConnection(fullDoc);
await server.hocuspocus.openDirectConnection(emptyDoc);
await vi.waitFor(
() => {
expect(server.durabilityState.getReconciledBase(fullDoc)).toBe(fullContent);
expect(server.durabilityState.getReconciledBase(emptyDoc)).toBe('');
},
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.deleteReconciledBase(fullDoc);
server.durabilityState.deleteReconciledBase(emptyDoc);
unlinkSync(join(rig.tmpDir, `${fullDoc}.md`));
unlinkSync(join(rig.tmpDir, `${emptyDoc}.md`));
await vi.waitFor(
async () => {
const rescues = await listRescueCheckpoints(rig.shadow, 'main');
expect(rescues.map((r) => r.docName)).toContain(fullDoc);
},
{ timeout: 10_000, interval: 50 },
);
await expectAbsentDuring(
async () => (await listRescueCheckpoints(rig.shadow, 'main')).map((r) => r.docName),
emptyDoc,
);
const rescues = await listRescueCheckpoints(rig.shadow, 'main');
expect(rescues).toHaveLength(1);
const rescue = rescues[0];
expect(rescue?.docName).toBe(fullDoc);
expect(rescue?.label).toContain('External change recovered');
expect(rescue?.incomingDiskSha).toBe('');
const deleteRescueBody = (
await shadowGit(rig.shadow).raw('log', '-1', '--format=%B', rescue?.sha ?? '')
).trim();
expect(parseCheckpoint(deleteRescueBody)?.kind).toBe('external-change-rescue');
} finally {
await server.destroy();
}
}, 30_000);
test('a delete resolution rescues unflushed live edits now that the suppressed self-delete no longer routes that teardown through the watcher', async () => {
rig = await setupReconcileRig('ok-resolve-delete-rescue-');
const docName = 'resolve-delete-rescue-target';
const diskContent = '# Resolve delete rescue target\n\nOn-disk body.\n';
writeFileSync(join(rig.tmpDir, `${docName}.md`), diskContent, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(diskContent),
{ timeout: 5_000, interval: 25 },
);
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('Unflushed paragraph only in the editor doc.')]);
xmlFragment.insert(0, [paragraph]);
});
await vi.waitFor(
() =>
expect(server.hocuspocus.documents.get(docName)?.getText('source').toString()).toContain(
'Unflushed paragraph only in the editor doc.',
),
{ timeout: 5_000, interval: 25 },
);
server.conflicts.raise({
kind: 'reconcile',
file: `${docName}.md`,
reason: 'stale-external-write',
stages: { base: diskContent, ours: diskContent, theirs: diskContent },
});
await server.conflicts.resolve(`${docName}.md`, 'delete');
expect(existsSync(join(rig.tmpDir, `${docName}.md`))).toBe(false);
let rescueSha = '';
await vi.waitFor(
async () => {
const rescues = await listRescueCheckpoints(rig.shadow, 'main');
const rescue = rescues.find((r) => r.docName === docName);
expect(rescue).toBeDefined();
rescueSha = rescue?.sha ?? '';
},
{ timeout: 10_000, interval: 50 },
);
const resolveRescueBody = (
await shadowGit(rig.shadow).raw('log', '-1', '--format=%B', rescueSha)
).trim();
expect(parseCheckpoint(resolveRescueBody)?.kind).toBe('external-change-rescue');
const rescuedContents = await shadowGit(rig.shadow).raw('show', `${rescueSha}:${docName}`);
expect(rescuedContents).toContain('Unflushed paragraph only in the editor doc.');
conn.disconnect();
} finally {
await server.destroy();
}
}, 30_000);
test('a delete resolution that fails after its rescue decision leaves the base the retry re-reads', async () => {
rig = await setupReconcileRig('ok-resolve-delete-retry-base-');
const docName = 'resolve-delete-retry-base';
const diskContent = '# Resolve delete retry base\n\nOn-disk body.\n';
writeFileSync(join(rig.tmpDir, `${docName}.md`), diskContent, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(diskContent),
{ timeout: 5_000, interval: 25 },
);
const unloadDocument = server.hocuspocus.unloadDocument.bind(server.hocuspocus);
let failNextUnload = true;
server.hocuspocus.unloadDocument = async (document) => {
if (!failNextUnload) return unloadDocument(document);
failNextUnload = false;
throw new Error('injected unload failure');
};
server.conflicts.raise({
kind: 'reconcile',
file: `${docName}.md`,
reason: 'stale-external-write',
stages: { base: diskContent, ours: diskContent, theirs: diskContent },
});
await expect(server.conflicts.resolve(`${docName}.md`, 'delete')).rejects.toThrow(
'injected unload failure',
);
expect(server.durabilityState.getReconciledBase(docName)).toBe(diskContent);
await server.conflicts.resolve(`${docName}.md`, 'delete');
await expectAbsentDuring(
async () => (await listRescueCheckpoints(rig.shadow, 'main')).map((r) => r.docName),
docName,
);
conn.disconnect();
} finally {
await server.destroy();
}
}, 30_000);
test('a delete resolution whose file is already gone leaves the directory count its remaining markdown justifies', async () => {
rig = await setupReconcileRig('ok-resolve-delete-dircount-');
const notesDir = join(rig.tmpDir, 'notes');
mkdirSync(notesDir);
writeFileSync(join(notesDir, 'keep.md'), '# Keep\n', 'utf-8');
writeFileSync(join(notesDir, 'sibling.png'), 'png-bytes', 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
expect(server.contentFilter.isExcluded('notes/sibling.png')).toBe(false);
server.conflicts.raise({
kind: 'reconcile',
file: 'notes/gone.md',
reason: 'stale-external-write',
stages: { base: '', ours: '', theirs: '' },
});
await server.conflicts.resolve('notes/gone.md', 'delete');
expect(existsSync(join(notesDir, 'keep.md'))).toBe(true);
expect(server.contentFilter.isExcluded('notes/sibling.png')).toBe(false);
} finally {
await server.destroy();
}
}, 30_000);
test('a delete resolution that unlinks then fails, retried with mine, leaves the directory count matching the file it put back', async () => {
rig = await setupReconcileRig('ok-resolve-delete-then-mine-dircount-');
const notesDir = join(rig.tmpDir, 'notes');
mkdirSync(notesDir);
const docName = 'notes/delete-then-mine';
const diskContent = '# Delete then mine\n\nOn-disk body.\n';
writeFileSync(join(notesDir, 'delete-then-mine.md'), diskContent, 'utf-8');
writeFileSync(join(notesDir, 'sibling.png'), 'png-bytes', 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(diskContent),
{ timeout: 5_000, interval: 25 },
);
expect(server.contentFilter.isExcluded('notes/sibling.png')).toBe(false);
const unloadDocument = server.hocuspocus.unloadDocument.bind(server.hocuspocus);
let failNextUnload = true;
server.hocuspocus.unloadDocument = async (document) => {
if (!failNextUnload) return unloadDocument(document);
failNextUnload = false;
throw new Error('injected unload failure');
};
server.conflicts.raise({
kind: 'reconcile',
file: `${docName}.md`,
reason: 'stale-external-write',
stages: { base: diskContent, ours: diskContent, theirs: diskContent },
});
await expect(server.conflicts.resolve(`${docName}.md`, 'delete')).rejects.toThrow(
'injected unload failure',
);
expect(existsSync(join(notesDir, 'delete-then-mine.md'))).toBe(false);
expect(server.contentFilter.isExcluded('notes/sibling.png')).toBe(true);
await server.conflicts.resolve(`${docName}.md`, 'mine');
expect(existsSync(join(notesDir, 'delete-then-mine.md'))).toBe(true);
expect(server.contentFilter.isExcluded('notes/sibling.png')).toBe(false);
conn.disconnect();
} finally {
await server.destroy();
}
}, 30_000);
test('a delete resolution that fails at unload leaves the lifecycle it found, so a later resolution clears the document', async () => {
rig = await setupReconcileRig('ok-resolve-delete-lifecycle-restore-');
const docName = 'resolve-delete-lifecycle-restore';
const diskContent = '# Resolve delete lifecycle restore\n\nOn-disk body.\n';
writeFileSync(join(rig.tmpDir, `${docName}.md`), diskContent, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(diskContent),
{ timeout: 5_000, interval: 25 },
);
const unloadDocument = server.hocuspocus.unloadDocument.bind(server.hocuspocus);
let failNextUnload = true;
server.hocuspocus.unloadDocument = async (document) => {
if (!failNextUnload) return unloadDocument(document);
failNextUnload = false;
throw new Error('injected unload failure');
};
server.conflicts.raise({
kind: 'reconcile',
file: `${docName}.md`,
reason: 'stale-external-write',
stages: { base: diskContent, ours: diskContent, theirs: diskContent },
});
await expect(server.conflicts.resolve(`${docName}.md`, 'delete')).rejects.toThrow(
'injected unload failure',
);
const afterFailure = server.hocuspocus.documents.get(docName);
expect(afterFailure).toBeDefined();
if (!afterFailure) throw new Error('expected the document to stay resident');
expect(server.conflicts.lifecycleOf(afterFailure, docName)).toEqual({
status: 'conflict',
kind: 'reconcile',
reason: 'stale-external-write',
});
await server.conflicts.resolve(`${docName}.md`, 'mine');
const afterRetry = server.hocuspocus.documents.get(docName);
expect(afterRetry).toBeDefined();
if (!afterRetry) throw new Error('expected the document to stay resident');
expect(server.conflicts.lifecycleOf(afterRetry, docName)).toBeNull();
conn.disconnect();
} finally {
await server.destroy();
}
}, 30_000);
test('a delete resolution that fails at unload leaves the stale-external-write record its rehydration re-reads', async () => {
rig = await setupReconcileRig('ok-resolve-delete-durable-restore-');
const docName = 'resolve-delete-durable-restore';
const file = `${docName}.md`;
const retained = '# Resolve delete durable restore\n\nAcknowledged body.\n';
const diskContent = '# Resolve delete durable restore\n\nRejected older save.\n';
writeFileSync(join(rig.tmpDir, file), retained, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(retained),
{ timeout: 5_000, interval: 25 },
);
const raised = server.durabilityState.recordStaleExternalWrite(
docName,
diskContent,
retained,
);
expect(server.durabilityState.listStaleExternalWrites().map((c) => c.docName)).toContain(
docName,
);
expect(server.conflicts.findByFile(file)).toMatchObject({
kind: 'reconcile',
reason: 'stale-external-write',
});
const unloadDocument = server.hocuspocus.unloadDocument.bind(server.hocuspocus);
let failNextUnload = true;
server.hocuspocus.unloadDocument = async (document) => {
if (!failNextUnload) return unloadDocument(document);
failNextUnload = false;
throw new Error('injected unload failure');
};
await expect(server.conflicts.resolve(file, 'delete')).rejects.toThrow(
'injected unload failure',
);
expect(server.durabilityState.getStaleExternalWrite(docName)).toMatchObject({
docName,
diskContent,
retainedContent: retained,
detectedAt: raised.detectedAt,
});
expect(server.durabilityState.listStaleExternalWrites().map((c) => c.docName)).toContain(
docName,
);
expect(persistedStaleExternalWrite(rig.tmpDir, docName)).toMatchObject({
docName,
diskContent,
detectedAt: raised.detectedAt,
});
await server.conflicts.resolve(file, 'mine');
expect(server.durabilityState.listStaleExternalWrites().map((c) => c.docName)).not.toContain(
docName,
);
expect(persistedStaleExternalWrite(rig.tmpDir, docName)).toBeUndefined();
conn.disconnect();
} finally {
await server.destroy();
}
}, 30_000);
test('a delete resolution whose teardown observed a newer external write rolls back to that newer record', async () => {
rig = await setupReconcileRig('ok-resolve-delete-durable-newer-');
const docName = 'resolve-delete-durable-newer';
const file = `${docName}.md`;
const retained = '# Resolve delete durable newer\n\nAcknowledged body.\n';
const olderDisk = '# Resolve delete durable newer\n\nFirst rejected save.\n';
const newerDisk = '# Resolve delete durable newer\n\nSecond rejected save.\n';
writeFileSync(join(rig.tmpDir, file), retained, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(retained),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.recordStaleExternalWrite(docName, olderDisk, retained);
const unloadDocument = server.hocuspocus.unloadDocument.bind(server.hocuspocus);
let failNextUnload = true;
server.hocuspocus.unloadDocument = async (document) => {
if (!failNextUnload) return unloadDocument(document);
failNextUnload = false;
server.durabilityState.recordStaleExternalWrite(docName, newerDisk, retained);
throw new Error('injected unload failure');
};
await expect(server.conflicts.resolve(file, 'delete')).rejects.toThrow(
'injected unload failure',
);
expect(server.durabilityState.getStaleExternalWrite(docName)).toMatchObject({
docName,
diskContent: newerDisk,
});
expect(persistedStaleExternalWrite(rig.tmpDir, docName)).toMatchObject({
docName,
diskContent: newerDisk,
});
conn.disconnect();
} finally {
await server.destroy();
}
}, 30_000);
test('a delete resolution that fails at unload after a checkout restores the record to the branch it was cleared from', async () => {
rig = await setupReconcileRig('ok-resolve-delete-branch-moved-');
const docName = 'resolve-delete-branch-moved';
const file = `${docName}.md`;
const retained = '# Resolve delete branch moved\n\nAcknowledged body.\n';
const diskContent = '# Resolve delete branch moved\n\nRejected older save.\n';
writeFileSync(join(rig.tmpDir, file), retained, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(retained),
{ timeout: 5_000, interval: 25 },
);
const raised = server.durabilityState.recordStaleExternalWrite(
docName,
diskContent,
retained,
);
expect(server.conflicts.findByFile(file)).toMatchObject({
kind: 'reconcile',
reason: 'stale-external-write',
});
const unloadDocument = server.hocuspocus.unloadDocument.bind(server.hocuspocus);
let failNextUnload = true;
server.hocuspocus.unloadDocument = async (document) => {
if (!failNextUnload) return unloadDocument(document);
failNextUnload = false;
server.durabilityState.switchReconciledBaseScope('feature');
server.conflicts.setBranch('feature');
throw new Error('injected unload failure');
};
await expect(server.conflicts.resolve(file, 'delete')).rejects.toThrow(
'injected unload failure',
);
expect(server.durabilityState.getActiveBranch()).toBe('feature');
expect(server.durabilityState.getStaleExternalWrite(docName)).toBeUndefined();
expect(server.durabilityState.listStaleExternalWrites()).toEqual([]);
expect(server.conflicts.findByFile(file)).toBeUndefined();
server.durabilityState.switchReconciledBaseScope('main');
server.conflicts.setBranch('main');
expect(server.durabilityState.getStaleExternalWrite(docName)).toMatchObject({
docName,
diskContent,
retainedContent: retained,
detectedAt: raised.detectedAt,
});
expect(persistedStaleExternalWrite(rig.tmpDir, docName)).toMatchObject({
docName,
diskContent,
detectedAt: raised.detectedAt,
});
conn.disconnect();
} finally {
await server.destroy();
}
}, 30_000);
test('a resolution that rewrites a file already on disk leaves the directory count where it found it', async () => {
rig = await setupReconcileRig('ok-resolve-mine-dircount-');
const notesDir = join(rig.tmpDir, 'notes');
mkdirSync(notesDir);
const docName = 'notes/rewritten-in-place';
const diskContent = '# Rewritten in place\n\nOn-disk body.\n';
writeFileSync(join(notesDir, 'rewritten-in-place.md'), diskContent, 'utf-8');
writeFileSync(join(notesDir, 'sibling.png'), 'png-bytes', 'utf-8');
const server = createReconcileServer(rig);
const raiseFor = (): void =>
server.conflicts.raise({
kind: 'reconcile',
file: `${docName}.md`,
reason: 'stale-external-write',
stages: { base: diskContent, ours: diskContent, theirs: diskContent },
});
try {
await server.ready;
expect(server.contentFilter.isExcluded('notes/sibling.png')).toBe(false);
raiseFor();
await server.conflicts.resolve(`${docName}.md`, 'mine');
expect(existsSync(join(notesDir, 'rewritten-in-place.md'))).toBe(true);
expect(server.contentFilter.isExcluded('notes/sibling.png')).toBe(false);
raiseFor();
await server.conflicts.resolve(`${docName}.md`, 'delete');
expect(existsSync(join(notesDir, 'rewritten-in-place.md'))).toBe(false);
expect(server.contentFilter.isExcluded('notes/sibling.png')).toBe(true);
} finally {
await server.destroy();
}
}, 30_000);
test('rename-path teardown rescues a dirty doc under the same checkpoint kind as the other teardown sites', async () => {
rig = await setupReconcileRig('ok-reconcile-rename-rescue-');
const docName = 'rename-rescue-source';
const newDocName = 'rename-rescue-destination';
const diskContent = '# Rename rescue source\n\nOn-disk body.\n';
writeFileSync(join(rig.tmpDir, `${docName}.md`), diskContent, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(diskContent),
{ timeout: 5_000, interval: 25 },
);
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('Unflushed paragraph only in the editor doc.')]);
xmlFragment.insert(0, [paragraph]);
});
await vi.waitFor(
() =>
expect(server.hocuspocus.documents.get(docName)?.getText('source').toString()).toContain(
'Unflushed paragraph only in the editor doc.',
),
{ timeout: 5_000, interval: 25 },
);
renameSync(join(rig.tmpDir, `${docName}.md`), join(rig.tmpDir, `${newDocName}.md`));
let rescueSha = '';
await vi.waitFor(
async () => {
const rescues = await listRescueCheckpoints(rig.shadow, 'main');
const rescue = rescues.find((r) => r.docName === docName);
expect(rescue).toBeDefined();
rescueSha = rescue?.sha ?? '';
},
{ timeout: 10_000, interval: 50 },
);
const renameRescueBody = (
await shadowGit(rig.shadow).raw('log', '-1', '--format=%B', rescueSha)
).trim();
expect(parseCheckpoint(renameRescueBody)?.kind).toBe('external-change-rescue');
conn.disconnect();
} finally {
await server.destroy();
}
}, 30_000);
test('a branch-switch round trip keeps an absent-base doc on disk content instead of resurrecting parked WIP', async () => {
const projectDir = await realpath(mkdtempSync(join(tmpdir(), 'ok-reconcile-park-')));
const git = simpleGit(projectDir);
await git.init(['--initial-branch=main']);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
const docName = 'park-roundtrip-target';
const mainContent = '# Park roundtrip target\n\nMain branch body.\n';
const featureContent = '# Park roundtrip target\n\nFeature branch body.\n';
writeFileSync(join(projectDir, `${docName}.md`), mainContent, 'utf-8');
await git.add('.');
await git.commit('main content');
await git.checkoutLocalBranch('feature');
writeFileSync(join(projectDir, `${docName}.md`), featureContent, 'utf-8');
await git.add(['-A']);
await git.commit('feature content');
await git.checkout('main');
const shadow = await initShadowRepo(projectDir);
rig = {
tmpDir: projectDir,
shadow,
cleanup: () => rmSync(projectDir, { recursive: true, force: true }),
};
const server = createServer({
contentDir: projectDir,
projectDir,
quiet: true,
debounce: 100,
maxDebounce: 500,
gitEnabled: false,
shadowRepo: shadow,
});
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(mainContent),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.deleteReconciledBase(docName);
await git.checkout('feature');
await vi.waitFor(() => expect(serverDoc.getText('source').toString()).toBe(featureContent), {
timeout: 15_000,
interval: 25,
});
expect(serverDoc.getMap('lifecycle').get('status')).toBeUndefined();
await git.checkout('main');
await vi.waitFor(() => expect(serverDoc.getText('source').toString()).toBe(mainContent), {
timeout: 15_000,
interval: 25,
});
expect(serverDoc.getText('source').toString()).not.toContain('Feature branch body.');
expect(server.durabilityState.getReconciledBase(docName)).toBe(mainContent);
expect(serverDoc.getMap('lifecycle').get('status')).toBeUndefined();
conn.disconnect();
} finally {
await server.destroy();
}
}, 60_000);
test('unsaved WIP survives a branch round trip and is saved by the next store instead of being merged away', async () => {
const projectDir = await realpath(mkdtempSync(join(tmpdir(), 'ok-reconcile-park-store-')));
const git = simpleGit(projectDir);
await git.init(['--initial-branch=main']);
configureTestGitRepository(projectDir);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
const docName = 'park-store-target';
const docPath = join(projectDir, `${docName}.md`);
const mainContent = '# Park store target\n\nMain branch body.\n\nTail.\n';
const featureContent = '# Park store target\n\nFeature branch body.\n\nTail.\n';
writeFileSync(docPath, mainContent, 'utf-8');
await git.add('.');
await git.commit('main content');
await git.checkoutLocalBranch('feature');
writeFileSync(docPath, featureContent, 'utf-8');
await git.add(['-A']);
await git.commit('feature content');
await git.checkout('main');
const shadow = await initShadowRepo(projectDir);
rig = {
tmpDir: projectDir,
shadow,
cleanup: () => rmSync(projectDir, { recursive: true, force: true }),
};
const server = createServer({
contentDir: projectDir,
projectDir,
quiet: true,
debounce: 60_000,
maxDebounce: 120_000,
gitEnabled: false,
shadowRepo: shadow,
});
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(mainContent),
{ timeout: 5_000, interval: 25 },
);
const source = serverDoc.getText('source');
serverDoc.transact(() =>
source.insert(source.toString().indexOf('Tail.'), 'Unsaved WIP.\n\n'),
);
const withWip = '# Park store target\n\nMain branch body.\n\nUnsaved WIP.\n\nTail.\n';
expect(source.toString()).toBe(withWip);
await git.checkout('feature');
const featureWithWip =
'# Park store target\n\nFeature branch body.\n\nUnsaved WIP.\n\nTail.\n';
expect(featureWithWip).not.toBe(featureContent);
await vi.waitFor(() => expect(source.toString()).toBe(featureWithWip), {
timeout: 15_000,
interval: 25,
});
await git.checkout('main');
await vi.waitFor(() => expect(source.toString()).toBe(withWip), {
timeout: 15_000,
interval: 25,
});
serverDoc.transact(() => source.insert(source.length, '\nTyped after the switch.\n'));
await server.hocuspocus.flushPendingStores();
const saved = `${withWip}\nTyped after the switch.\n`;
await vi.waitFor(() => expect(readFileSync(docPath, 'utf-8')).toBe(saved), {
timeout: 10_000,
interval: 25,
});
expect(source.toString()).toBe(saved);
conn.disconnect();
} finally {
await server.destroy();
}
}, 60_000);
test("a branch switch that leaves an absent-base doc's file unchanged keeps its unsaved typing live", async () => {
const projectDir = await realpath(mkdtempSync(join(tmpdir(), 'ok-reconcile-bs-rescue-')));
const git = simpleGit(projectDir);
await git.init(['--initial-branch=main']);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
const docName = 'branch-switch-rescue-target';
const diskContent = '# Branch switch rescue target\n\nSame body on both branches.\n';
writeFileSync(join(projectDir, `${docName}.md`), diskContent, 'utf-8');
await git.add('.');
await git.commit('main content');
await git.checkoutLocalBranch('feature');
await git.checkout('main');
const shadow = await initShadowRepo(projectDir);
rig = {
tmpDir: projectDir,
shadow,
cleanup: () => rmSync(projectDir, { recursive: true, force: true }),
};
const server = createServer({
contentDir: projectDir,
projectDir,
quiet: true,
debounce: 60_000,
maxDebounce: 60_000,
gitEnabled: false,
shadowRepo: shadow,
});
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(diskContent),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.deleteReconciledBase(docName);
await conn.transact((doc) => {
const xmlFragment = doc.getXmlFragment('default');
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText('Unflushed WIP paragraph only in the editor.')]);
xmlFragment.insert(0, [paragraph]);
});
await vi.waitFor(
() =>
expect(serverDoc.getText('source').toString()).toContain(
'Unflushed WIP paragraph only in the editor.',
),
{ timeout: 5_000, interval: 25 },
);
const wipText = serverDoc.getText('source').toString();
expect(wipText).not.toBe(diskContent);
const warnSpy = vi.spyOn(getLogger('server'), 'warn');
const switched = vi.spyOn(server.cc1Broadcaster, 'emitBranchSwitched');
try {
await git.checkout('feature');
await vi.waitFor(() => expect(switched).toHaveBeenCalledWith('feature'), {
timeout: 15_000,
interval: 25,
});
expect(serverDoc.getText('source').toString()).toBe(wipText);
expect(serverDoc.getMap('lifecycle').get('status')).toBeUndefined();
const rescues = await listRescueCheckpoints(rig.shadow, 'feature');
expect(rescues.filter((r) => r.docName === docName)).toEqual([]);
const warnTexts = warnSpy.mock.calls.map((call) => String(call[1] ?? ''));
expect(warnTexts.some((s) => s.includes('skipped parking'))).toBe(true);
} finally {
switched.mockRestore();
warnSpy.mockRestore();
}
conn.disconnect();
} finally {
await server.destroy();
}
}, 60_000);
test('a first-visit branch switch mints no rescue for a settled doc whose content already matches the destination disk', async () => {
const projectDir = await realpath(mkdtempSync(join(tmpdir(), 'ok-reconcile-firstvisit-')));
const git = simpleGit(projectDir);
await git.init(['--initial-branch=main']);
configureTestGitRepository(projectDir);
expect
.soft((await simpleGit(projectDir).listConfig('local')).all['maintenance.auto'])
.toBe('false');
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
const docName = 'first-visit-settled';
const settledContent = '# First visit settled\n\nSame body on both branches.\n';
writeFileSync(join(projectDir, `${docName}.md`), settledContent, 'utf-8');
await git.add('.');
await git.commit('main content');
const shadow = await initShadowRepo(projectDir);
rig = {
tmpDir: projectDir,
shadow,
cleanup: () => rmSync(projectDir, { recursive: true, force: true }),
};
const server = createServer({
contentDir: projectDir,
projectDir,
quiet: true,
debounce: 60_000,
maxDebounce: 60_000,
gitEnabled: false,
shadowRepo: shadow,
});
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(settledContent),
{ timeout: 5_000, interval: 25 },
);
await git.checkoutLocalBranch('feature');
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(settledContent),
{ timeout: 15_000, interval: 25 },
);
expect(serverDoc.getText('source').toString()).toBe(settledContent);
expect(serverDoc.getMap('lifecycle').get('status')).toBeUndefined();
await expectAbsentDuring(
async () => (await listRescueCheckpoints(rig.shadow, 'feature')).map((r) => r.docName),
docName,
);
conn.disconnect();
} finally {
await server.destroy();
}
}, 60_000);
test('a blockless acknowledged base refuses the merge and adopts disk content with a rescue', async () => {
rig = await setupReconcileRig('ok-reconcile-refused-no-base-');
const docName = 'refused-no-base-target';
const initial = '# Refused no-base target\n\nParagraph that only the editor doc holds.\n';
const theirs = '# Refused no-base target\n\nDisk-authoritative replacement paragraph.\n';
const docPath = join(rig.tmpDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.setReconciledBase(docName, '');
expect(server.durabilityState.getReconciledBase(docName)).toBe('');
const ingestsBefore = getMetrics().diskAuthoritativeIngestCount;
writeFileSync(docPath, theirs, 'utf-8');
await vi.waitFor(() => expect(serverDoc.getText('source').toString()).toBe(theirs), {
timeout: 8_000,
interval: 25,
});
expect(serverDoc.getText('source').toString()).not.toContain(
'Paragraph that only the editor doc holds.',
);
expect(server.durabilityState.getReconciledBase(docName)).toBe(theirs);
expect(readFileSync(docPath, 'utf-8')).toBe(theirs);
expect(serverDoc.getMap('lifecycle').get('status')).toBeUndefined();
expect(getMetrics().diskAuthoritativeIngestCount).toBe(ingestsBefore + 1);
await vi.waitFor(
async () => {
const rescues = await listRescueCheckpoints(rig.shadow, 'main');
const rescue = rescues.find((r) => r.docName === docName);
expect(rescue).toBeDefined();
expect(rescue?.incomingDiskSha).toBe(contentHash(theirs).slice(0, 6));
},
{ timeout: 10_000, interval: 50 },
);
conn.disconnect();
} finally {
await server.destroy();
}
}, 30_000);
test('a failed disk-authoritative ingest keeps the live content, leaves no agreed version for the disk bytes it lacks, and takes the next update in again', async () => {
rig = await setupReconcileRig('ok-reconcile-ingest-failure-');
const docName = 'ingest-failure-target';
const initial = '# Ingest failure target\n\nLive paragraph that exists only in the editor.\n';
const theirs = '# Ingest failure target\n\nBase paragraph from disk.\n';
const followUp =
'# Ingest failure target\n\nBase paragraph from disk.\n\nDisk addition after recovery.\n';
const docPath = join(rig.tmpDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.deleteReconciledBase(docName);
const originalGetXmlFragment = serverDoc.getXmlFragment.bind(serverDoc);
const applyFailuresBefore = getMetrics().diskAuthoritativeIngestApplyFailures;
const ingestsBefore = getMetrics().diskAuthoritativeIngestCount;
serverDoc.getXmlFragment = () => {
throw new BridgeMergeContentLossError({
baseline: 'base',
userText: 'user',
agentText: 'agent',
result: 'merged',
lostSubstrings: ['lost-text'],
which: 'substring',
side: 'user',
});
};
try {
writeFileSync(docPath, theirs, 'utf-8');
await vi.waitFor(
() =>
expect(getMetrics().diskAuthoritativeIngestApplyFailures).toBe(applyFailuresBefore + 1),
{ timeout: 10_000, interval: 25 },
);
expect(server.durabilityState.getReconciledBase(docName)).toBeUndefined();
expect(server.durabilityState.getReceipt(docName)).toBeUndefined();
expect(serverDoc.getText('source').toString()).toBe(initial);
expect(serverDoc.getMap('lifecycle').get('status')).toBeUndefined();
expect(getMetrics().diskAuthoritativeIngestApplyFailures).toBe(applyFailuresBefore + 1);
expect(getMetrics().diskAuthoritativeIngestCount).toBe(ingestsBefore + 1);
} finally {
serverDoc.getXmlFragment = originalGetXmlFragment;
}
writeFileSync(docPath, followUp, 'utf-8');
await vi.waitFor(() => expect(serverDoc.getText('source').toString()).toBe(followUp), {
timeout: 15_000,
interval: 25,
});
expect(server.durabilityState.getReconciledBase(docName)).toBe(followUp);
expect(getMetrics().diskAuthoritativeIngestCount).toBe(ingestsBefore + 2);
await vi.waitFor(
async () => {
const rescues = await listRescueCheckpoints(rig.shadow, 'main');
expect(rescues.filter((r) => r.docName === docName).map((r) => r.size)).toEqual(
expect.arrayContaining([initial.length, theirs.length]),
);
},
{ timeout: 10_000, interval: 50 },
);
const rescues = await listRescueCheckpoints(rig.shadow, 'main');
const docRescues = rescues.filter((r) => r.docName === docName);
expect(new Set(docRescues.map((r) => r.size))).toEqual(
new Set([initial.length, theirs.length]),
);
const sg = shadowGit(rig.shadow);
const mintKinds = new Set(
await Promise.all(
docRescues.map(async (r) => {
const body = (await sg.raw('log', '-1', '--format=%B', r.sha)).trim();
return parseCheckpoint(body)?.kind;
}),
),
);
expect(mintKinds).toEqual(new Set(['external-change-rescue-disk-update']));
conn.disconnect();
} finally {
await server.destroy();
}
}, 45_000);
test('the disk-authoritative ingest durably buffers live-only content before it adopts disk bytes', async () => {
rig = await setupReconcileRig('ok-reconcile-ingest-rescue-order-');
const docName = 'ingest-rescue-order-target';
const initial =
'# Ingest rescue order target\n\nLive paragraph that exists only in the editor.\n';
const theirs = '# Ingest rescue order target\n\nDisk-authoritative replacement paragraph.\n';
const docPath = join(rig.tmpDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
const server = createReconcileServer(rig);
const infoSpy = vi.spyOn(getLogger('server'), 'info');
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.deleteReconciledBase(docName);
const rescuePath = join(rig.shadow.gitDir, 'rescue', `${docName}.md`);
expect(existsSync(rescuePath)).toBe(false);
const unrescuedBefore = getMetrics().diskAuthoritativeIngestUnrescuedCount;
writeFileSync(docPath, theirs, 'utf-8');
await vi.waitFor(() => expect(serverDoc.getText('source').toString()).toBe(theirs), {
timeout: 8_000,
interval: 25,
});
expect(existsSync(rescuePath)).toBe(true);
expect(readFileSync(rescuePath, 'utf-8')).toBe(initial);
expect(getMetrics().diskAuthoritativeIngestUnrescuedCount).toBe(unrescuedBefore);
const ingestLog = infoSpy.mock.calls.find(
(call) => (call[0] as { reason?: string } | undefined)?.reason === 'no-base',
);
expect(ingestLog?.[0]).toMatchObject({ docName, result: 'clean', rescue: 'rescued' });
conn.disconnect();
} finally {
infoSpy.mockRestore();
await server.destroy();
}
}, 30_000);
test('an ingest whose rescue writes all fail is not reported as a clean ingest', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
rig = await setupReconcileRig('ok-reconcile-rescue-write-failure-');
const docName = 'rescue-write-failure-target';
const initial =
'# Rescue write failure target\n\nLive paragraph that exists only in the editor.\n';
const theirs = '# Rescue write failure target\n\nDisk-authoritative replacement paragraph.\n';
const docPath = join(rig.tmpDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
const server = createReconcileServer(rig);
const chmodEntries: Array<{ path: string; mode: number }> = [];
const warnSpy = vi.spyOn(getLogger('server'), 'warn');
const errorSpy = vi.spyOn(getLogger('server'), 'error');
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.deleteReconciledBase(docName);
const shadowGitDir = rig.shadow.gitDir;
const walk = (dir: string): void => {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const entryPath = join(dir, entry.name);
chmodEntries.push({ path: entryPath, mode: statSync(entryPath).mode & 0o777 });
if (entry.isDirectory()) walk(entryPath);
}
};
chmodEntries.push({ path: shadowGitDir, mode: statSync(shadowGitDir).mode & 0o777 });
walk(shadowGitDir);
for (const entry of chmodEntries) chmodSync(entry.path, 0o500);
const failuresBefore = getMetrics().rescueCheckpointWriteFailures;
const bufferFailuresBefore = getMetrics().rescueBufferWriteFailures;
const unrescuedBefore = getMetrics().diskAuthoritativeIngestUnrescuedCount;
const ingestsBefore = getMetrics().diskAuthoritativeIngestCount;
try {
writeFileSync(docPath, theirs, 'utf-8');
await vi.waitFor(() => expect(serverDoc.getText('source').toString()).toBe(theirs), {
timeout: 8_000,
interval: 25,
});
expect(server.durabilityState.getReconciledBase(docName)).toBe(theirs);
await vi.waitFor(
() => expect(getMetrics().rescueCheckpointWriteFailures).toBeGreaterThan(failuresBefore),
{ timeout: 10_000, interval: 25 },
);
expect(getMetrics().diskAuthoritativeIngestCount).toBe(ingestsBefore + 1);
expect(getMetrics().rescueBufferWriteFailures).toBeGreaterThan(bufferFailuresBefore);
expect(getMetrics().diskAuthoritativeIngestUnrescuedCount).toBe(unrescuedBefore + 1);
} finally {
for (const entry of chmodEntries) {
if (!existsSync(entry.path)) continue;
chmodSync(entry.path, entry.mode);
}
}
const rescues = await listRescueCheckpoints(rig.shadow, 'main');
expect(rescues.filter((r) => r.docName === docName)).toHaveLength(0);
expect(existsSync(join(rig.shadow.gitDir, 'rescue', `${docName}.md`))).toBe(false);
const ingestLog = warnSpy.mock.calls.find(
(call) => (call[0] as { reason?: string } | undefined)?.reason === 'no-base',
);
expect(ingestLog?.[0]).toMatchObject({ docName, result: 'clean-unrescued', rescue: 'lost' });
const rescueFailure = errorSpy.mock.calls.find((call) =>
String(call[1]).startsWith('[rescue] failed to write rescue buffer'),
);
expect(rescueFailure?.[0]).toMatchObject({ docName, context: 'disk-authoritative-ingest' });
conn.disconnect();
} finally {
warnSpy.mockRestore();
errorSpy.mockRestore();
await server.destroy();
}
}, 45_000);
async function expectFailedIngestsNotCountedUnrescued(deliveries: number): Promise<void> {
rig = await setupReconcileRig('ok-reconcile-compound-ingest-failure-');
const docName = 'compound-ingest-failure-target';
const initial =
'# Compound ingest failure target\n\nLive paragraph that exists only in the editor.\n';
const theirs =
'# Compound ingest failure target\n\nDisk-authoritative replacement paragraph.\n';
const docPath = join(rig.tmpDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
const watcher = createWatcherDouble();
const server = createReconcileServer(rig, {
watcherBackend: watcher.backend,
freshnessIntervalMs: null,
});
const chmodEntries: Array<{ path: string; mode: number }> = [];
const warnSpy = vi.spyOn(getLogger('server'), 'warn');
const infoSpy = vi.spyOn(getLogger('server'), 'info');
const errorSpy = vi.spyOn(getLogger('server'), 'error');
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.deleteReconciledBase(docName);
const shadowGitDir = rig.shadow.gitDir;
const walk = (dir: string): void => {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const entryPath = join(dir, entry.name);
chmodEntries.push({ path: entryPath, mode: statSync(entryPath).mode & 0o777 });
if (entry.isDirectory()) walk(entryPath);
}
};
chmodEntries.push({ path: shadowGitDir, mode: statSync(shadowGitDir).mode & 0o777 });
walk(shadowGitDir);
for (const entry of chmodEntries) chmodSync(entry.path, 0o500);
const originalGetXmlFragment = serverDoc.getXmlFragment.bind(serverDoc);
const applyFailuresBefore = getMetrics().diskAuthoritativeIngestApplyFailures;
const unrescuedBefore = getMetrics().diskAuthoritativeIngestUnrescuedCount;
serverDoc.getXmlFragment = () => {
throw new BridgeMergeContentLossError({
baseline: 'base',
userText: 'user',
agentText: 'agent',
result: 'merged',
lostSubstrings: ['lost-text'],
which: 'substring',
side: 'user',
});
};
try {
writeFileSync(docPath, theirs, 'utf-8');
for (let delivery = 0; delivery < deliveries; delivery++) {
watcher.subscriptionFor(rig.tmpDir).deliver([{ type: 'update', path: docPath }]);
}
await vi.waitFor(
() =>
expect(getMetrics().diskAuthoritativeIngestApplyFailures).toBe(
applyFailuresBefore + deliveries,
),
{ timeout: 10_000, interval: 25 },
);
} finally {
serverDoc.getXmlFragment = originalGetXmlFragment;
for (const entry of chmodEntries) {
if (!existsSync(entry.path)) continue;
chmodSync(entry.path, entry.mode);
}
}
expect(getMetrics().diskAuthoritativeIngestUnrescuedCount).toBe(unrescuedBefore);
expect(serverDoc.getText('source').toString()).toBe(initial);
const reconcileLines = [...warnSpy.mock.calls, ...infoSpy.mock.calls].filter(
(call) => (call[0] as { reason?: string } | undefined)?.reason === 'no-base',
);
expect(reconcileLines).toEqual([]);
const rescueFailure = errorSpy.mock.calls.find((call) =>
String(call[1]).startsWith('[rescue] failed to write rescue buffer'),
);
expect(rescueFailure?.[0]).toMatchObject({ docName, context: 'disk-authoritative-ingest' });
conn.disconnect();
} finally {
warnSpy.mockRestore();
infoSpy.mockRestore();
errorSpy.mockRestore();
await server.destroy();
}
}
test('an ingest that loses its rescue and then fails to apply is not counted as an unrescued clean ingest', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
await expectFailedIngestsNotCountedUnrescued(1);
}, 45_000);
test('a disk update delivered twice whose ingest loses its rescue and fails to apply both times is not counted as an unrescued clean ingest', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
await expectFailedIngestsNotCountedUnrescued(2);
}, 45_000);
test('an ingest that loses its rescue and then fails to apply after the live Y.Text is overwritten is reported as an unrescued loss', async (ctx) => {
ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
rig = await setupReconcileRig('ok-reconcile-post-write-ingest-failure-');
const docName = 'post-write-ingest-failure-target';
const initial =
'# Post-write ingest failure target\n\nLive paragraph that exists only in the editor.\n';
const theirs =
'# Post-write ingest failure target\n\nDisk-authoritative replacement paragraph.\n';
const docPath = join(rig.tmpDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
const server = createReconcileServer(rig);
const chmodEntries: Array<{ path: string; mode: number }> = [];
const warnSpy = vi.spyOn(getLogger('server'), 'warn');
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.deleteReconciledBase(docName);
const shadowGitDir = rig.shadow.gitDir;
const walk = (dir: string): void => {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const entryPath = join(dir, entry.name);
chmodEntries.push({ path: entryPath, mode: statSync(entryPath).mode & 0o777 });
if (entry.isDirectory()) walk(entryPath);
}
};
chmodEntries.push({ path: shadowGitDir, mode: statSync(shadowGitDir).mode & 0o777 });
walk(shadowGitDir);
for (const entry of chmodEntries) chmodSync(entry.path, 0o500);
const originalGetXmlFragment = serverDoc.getXmlFragment.bind(serverDoc);
const applyFailuresBefore = getMetrics().diskAuthoritativeIngestApplyFailures;
const unrescuedBefore = getMetrics().diskAuthoritativeIngestUnrescuedCount;
serverDoc.getXmlFragment = (name?: string) =>
new Proxy(originalGetXmlFragment(name), {
get(target, prop) {
if (serverDoc.getText('source').toString() === theirs) {
throw new BridgeMergeContentLossError({
baseline: 'base',
userText: 'user',
agentText: 'agent',
result: 'merged',
lostSubstrings: ['lost-text'],
which: 'substring',
side: 'user',
});
}
return Reflect.get(target, prop, target);
},
});
try {
writeFileSync(docPath, theirs, 'utf-8');
await vi.waitFor(
() =>
expect(getMetrics().diskAuthoritativeIngestApplyFailures).toBe(applyFailuresBefore + 1),
{ timeout: 10_000, interval: 25 },
);
} finally {
serverDoc.getXmlFragment = originalGetXmlFragment;
for (const entry of chmodEntries) {
if (!existsSync(entry.path)) continue;
chmodSync(entry.path, entry.mode);
}
}
expect(serverDoc.getText('source').toString()).toBe(theirs);
expect(serverDoc.getText('source').toString()).not.toContain(
'Live paragraph that exists only in the editor.',
);
expect(existsSync(join(rig.shadow.gitDir, 'rescue', `${docName}.md`))).toBe(false);
expect(getMetrics().diskAuthoritativeIngestUnrescuedCount).toBe(unrescuedBefore + 1);
const ingestLog = warnSpy.mock.calls.find(
(call) => (call[0] as { reason?: string } | undefined)?.reason === 'no-base',
);
expect(ingestLog?.[0]).toMatchObject({ docName, result: 'clean-unrescued', rescue: 'lost' });
conn.disconnect();
} finally {
warnSpy.mockRestore();
await server.destroy();
}
}, 45_000);
test('an ingest whose apply fails after the live Y.Text is overwritten is not unrescued when the rescue buffer was written', async () => {
rig = await setupReconcileRig('ok-reconcile-post-write-ingest-rescued-');
const docName = 'post-write-ingest-rescued-target';
const initial =
'# Post-write ingest rescued target\n\nLive paragraph that exists only in the editor.\n';
const theirs =
'# Post-write ingest rescued target\n\nDisk-authoritative replacement paragraph.\n';
const docPath = join(rig.tmpDir, `${docName}.md`);
writeFileSync(docPath, initial, 'utf-8');
const server = createReconcileServer(rig);
const warnSpy = vi.spyOn(getLogger('server'), 'warn');
const infoSpy = vi.spyOn(getLogger('server'), 'info');
const errorSpy = vi.spyOn(getLogger('server'), 'error');
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(
() => expect(server.durabilityState.getReconciledBase(docName)).toBe(initial),
{ timeout: 5_000, interval: 25 },
);
server.durabilityState.deleteReconciledBase(docName);
const originalGetXmlFragment = serverDoc.getXmlFragment.bind(serverDoc);
const applyFailuresBefore = getMetrics().diskAuthoritativeIngestApplyFailures;
const unrescuedBefore = getMetrics().diskAuthoritativeIngestUnrescuedCount;
serverDoc.getXmlFragment = (name?: string) =>
new Proxy(originalGetXmlFragment(name), {
get(target, prop) {
if (serverDoc.getText('source').toString() === theirs) {
throw new BridgeMergeContentLossError({
baseline: 'base',
userText: 'user',
agentText: 'agent',
result: 'merged',
lostSubstrings: ['lost-text'],
which: 'substring',
side: 'user',
});
}
return Reflect.get(target, prop, target);
},
});
try {
writeFileSync(docPath, theirs, 'utf-8');
await vi.waitFor(
() =>
expect(getMetrics().diskAuthoritativeIngestApplyFailures).toBe(applyFailuresBefore + 1),
{ timeout: 10_000, interval: 25 },
);
} finally {
serverDoc.getXmlFragment = originalGetXmlFragment;
}
expect(serverDoc.getText('source').toString()).toBe(theirs);
expect(existsSync(join(rig.shadow.gitDir, 'rescue', `${docName}.md`))).toBe(true);
expect(getMetrics().diskAuthoritativeIngestUnrescuedCount).toBe(unrescuedBefore);
const loggedLines = [...warnSpy.mock.calls, ...infoSpy.mock.calls, ...errorSpy.mock.calls]
.map((call) => String(call[1] ?? ''))
.filter((message) => message.includes(docName));
expect(
loggedLines.filter((message) =>
message.includes('failed to apply disk-authoritative ingest'),
),
).toHaveLength(1);
expect(loggedLines.filter((message) => message.includes('clean-unrescued'))).toEqual([]);
conn.disconnect();
} finally {
warnSpy.mockRestore();
infoSpy.mockRestore();
errorSpy.mockRestore();
await server.destroy();
}
}, 45_000);
});
describe('createServer() — disk-event reconcile insert-group dedup reporting', () => {
let rig: ReconcileRig;
beforeEach(() => {
resetMetrics();
});
afterEach(() => {
rig?.cleanup();
});
test('a both-kept reconcile that also skipped insert dedup past the LCS cap still counts the skip', async () => {
rig = await setupReconcileRig('ok-reconcile-conflict-dedup-');
const docName = 'conflict-dedup-target';
const perSide = Math.ceil(Math.sqrt(MAX_LCS_CELLS)) + 10;
const shared = Array.from({ length: 10 }, (_, i) => `Shared ${i}.`);
const base = 'Anchor.\n';
const ourBlocks = [
'Anchor edited by us.',
...shared,
...Array.from({ length: perSide }, (_, i) => `Ours ${i}.`),
];
const theirBlocks = [
'Anchor edited by them.',
...shared,
...Array.from({ length: perSide }, (_, i) => `Theirs ${i}.`),
];
const ours = `${ourBlocks.join('\n\n')}\n`;
const theirs = `${theirBlocks.join('\n\n')}\n`;
const docPath = join(rig.tmpDir, `${docName}.md`);
writeFileSync(docPath, ours, 'utf-8');
const server = createReconcileServer(rig);
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
const serverDoc = server.hocuspocus.documents.get(docName);
expect(serverDoc).toBeDefined();
if (!serverDoc) return;
await vi.waitFor(() => expect(server.durabilityState.getReconciledBase(docName)).toBe(ours), {
timeout: 20_000,
interval: 50,
});
server.durabilityState.setReconciledBase(docName, base);
const conflictsBefore = getMetrics().conflictCount;
const bothKeptBefore = getMetrics().reconcileBothKept;
const dedupSkippedBefore = getMetrics().reconcileInsertDedupSkipped;
writeFileSync(docPath, theirs, 'utf-8');
await vi.waitFor(() => expect(getMetrics().reconcileBothKept).toBe(bothKeptBefore + 1), {
timeout: 20_000,
interval: 50,
});
const merged = serverDoc.getText('source').toString();
expect(merged.startsWith('Anchor edited by us.\n\nAnchor edited by them.\n\n')).toBe(true);
expect(merged).toContain('Ours 0.');
expect(merged).toContain(`Theirs ${perSide - 1}.`);
expect(getMetrics().reconcileInsertDedupSkipped).toBe(dedupSkippedBefore + 1);
expect(getMetrics().conflictCount).toBe(conflictsBefore);
expect(server.conflicts.findByDocName(docName)).toBeUndefined();
conn.disconnect();
} finally {
await server.destroy();
}
}, 90_000);
});