Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(open-knowledge): hot-apply config changes to running server (PRD-7260) (#2401)
miles-kt-inkeep41f2372ef73f
diff --git a/.changeset/autosync-toggle-hot-apply.md b/.changeset/autosync-toggle-hot-apply.mdnew file mode 100644index 000000000..5604064b1--- /dev/null+++ b/.changeset/autosync-toggle-hot-apply.md@@ -0,0 +1,10 @@+---+"@inkeep/open-knowledge": patch+---++Fix the Git auto-sync and semantic-search toggles silently having no effect until+the server restarts. Config changes made in the editor are now applied to the+running server immediately, without depending on the filesystem watcher echo+(which could drop the event on some platforms, notably Windows). The server now+re-applies a validated config change to its live consumers directly at persist+time, so toggling auto-sync or semantic search on or off takes effect right away.diff --git a/bun.lock b/bun.lockindex c8fbbba68..c9810b22f 100644--- a/bun.lock+++ b/bun.lock@@ -186,6 +186,7 @@"@types/ws": "^8.18.1","@vitejs/plugin-react": "^6.0.1","babel-plugin-react-compiler": "0.0.0-experimental-a8e64ef-20260402",+ "chokidar": "^5.0.0","commonmark.json": "^0.31.0","diff": "^8.0.4","fake-indexeddb": "^6.0.0",diff --git a/packages/app/package.json b/packages/app/package.jsonindex 9bbfe1829..20eceed72 100644--- a/packages/app/package.json+++ b/packages/app/package.json@@ -186,6 +186,7 @@"@types/ws": "^8.18.1","@vitejs/plugin-react": "^6.0.1","babel-plugin-react-compiler": "0.0.0-experimental-a8e64ef-20260402",+ "chokidar": "^5.0.0","commonmark.json": "^0.31.0","diff": "^8.0.4","fake-indexeddb": "^6.0.0",diff --git a/packages/app/tests/integration/config-hot-apply-without-watcher-echo.test.ts b/packages/app/tests/integration/config-hot-apply-without-watcher-echo.test.tsnew file mode 100644index 000000000..e2ce6610e--- /dev/null+++ b/packages/app/tests/integration/config-hot-apply-without-watcher-echo.test.ts@@ -0,0 +1,263 @@+/**+ * Contract: a config change the server itself validates and persists on the+ * client Y.Doc path (ConfigBinding.patch → Hocuspocus → storeConfigDoc) must+ * reach the server's live in-process consumers EVEN IF the chokidar watcher+ * echo of the server's own write never delivers.+ *+ * Before the producer-side `onConfigPersisted` notification existed, the ONLY+ * path that applied a persisted config change to the sync engine and the+ * semantic-search service was the config-file-watcher callback in+ * server-factory.ts — a filesystem round-trip through a polling chokidar watch.+ * That echo channel is non-guaranteed (documented drops under load; a 10s boot+ * fallback poll is the only backstop), so a missed echo left the persisted+ * value unapplied until restart: disk said enabled, engine / semantic service+ * stayed disabled — observed in the field on Windows 11. These tests pin the+ * producer-side guarantee that closes that gap.+ *+ * Fault injection is at the OS filesystem-watcher boundary ONLY: chokidar is+ * mocked to emit `ready` then swallow every event, simulating an undelivered+ * echo. Everything else is real — real server, real WebSocket, real+ * ConfigBinding.patch, real atomic config persistence, real sync engine, real+ * semantic-search service, real HTTP API. The assertions are on observable+ * consumer state (engine `syncEnabled`; `GET /api/semantic-status` `enabled`),+ * not on how the notification is delivered.+ */++import { afterAll, beforeAll, describe, expect, mock, test } from 'bun:test';+import { EventEmitter } from 'node:events';+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';+import { dirname, join } from 'node:path';++// Register BEFORE the server's dynamic `await import('chokidar')` runs. The+// watcher fires `ready` (chokidar's post-initial-scan signal) then swallows+// every subsequent add/change event — the undelivered-echo condition the fix+// must survive.+class SwallowingWatcher extends EventEmitter {+ constructor() {+ super();+ setTimeout(() => this.emit('ready'), 10);+ }+ add(): this {+ return this;+ }+ unwatch(): this {+ return this;+ }+ async close(): Promise<void> {}+}+// `mock.module` replaces chokidar for the WHOLE bun-test process, not just this+// file — sibling test files in the same shard would inherit the swallowed+// watcher and silently starve on filesystem events (observed: managed-artifact+// reconcile timing out in the same shard). Confine the fault injection to this+// file: swallow only while this file's suites run, then delegate to the real+// implementation.+//+// The delegation target MUST be a destructured function reference captured+// BEFORE mock.module runs: when the module was already imported earlier in the+// process, bun patches the existing namespace's live bindings, so delegating+// through a captured namespace object would call the mock itself (infinite+// recursion). A destructured const keeps pointing at the real function.+const { watch: realChokidarWatch } = await import('chokidar');+let swallowChokidarEvents = true;+afterAll(() => {+ swallowChokidarEvents = false;+});+mock.module('chokidar', () => ({+ watch: (...args: Parameters<typeof realChokidarWatch>) =>+ swallowChokidarEvents+ ? (new SwallowingWatcher() as unknown as ReturnType<typeof realChokidarWatch>)+ : realChokidarWatch(...args),+}));++import { HocuspocusProvider } from '@hocuspocus/provider';+import {+ bindConfigDoc,+ CONFIG_DOC_NAME_PROJECT_LOCAL,+ type ConfigBinding,+} from '@inkeep/open-knowledge-core';+import * as Y from 'yjs';+import { createTestServer, pollUntil, type TestServer, wait } from './test-harness';++// The config-file-watcher's fallback poll (server-factory / config-file-watcher)+// calls the change handler directly for ~10s after boot, bypassing chokidar. It+// would mask the swallowed echo inside that window — mirroring production, where+// a toggle minutes after boot has no such backstop. Wait it out so the patch+// lands strictly after the fallback has self-terminated: the exact real-world+// scenario this bug describes. This is a wait on a known bounded backstop, not a+// race-hiding sleep.+const FALLBACK_POLL_WINDOW_MS = 11_000;++describe('PRD-7260 — persisted config change reaches in-process consumers without the watcher echo', () => {+ let srv: TestServer;+ let ydoc: Y.Doc;+ let provider: HocuspocusProvider;+ let binding: ConfigBinding;++ beforeAll(async () => {+ srv = await createTestServer();+ // Let the boot-time fallback poll window expire so the swallowed chokidar+ // echo is the ONLY remaining propagation channel.+ await wait(FALLBACK_POLL_WINDOW_MS);++ ydoc = new Y.Doc();+ provider = new HocuspocusProvider({+ url: `ws://127.0.0.1:${srv.port}/collab`,+ name: CONFIG_DOC_NAME_PROJECT_LOCAL,+ document: ydoc,+ connect: true,+ });+ binding = bindConfigDoc(provider, 'project-local');+ await pollUntil(() => binding.hasSynced(), 10_000);+ }, 40_000);++ afterAll(async () => {+ binding?.dispose();+ provider?.destroy();+ ydoc?.destroy();+ await srv?.cleanup();+ });++ test(+ 'sync engine hot-applies autoSync.enabled from a client patch',+ async () => {+ const configPath = join(srv.contentDir, '.ok', 'local', 'config.yml');+ expect(srv.instance.syncEngine?.getStatus().syncEnabled).toBe(false);++ const result = binding.patch({ autoSync: { enabled: true } });+ expect(result.ok).toBe(true);++ // Persistence leg is healthy on every platform — the disk reflects the+ // patch. This is the last thing that provably works today.+ await pollUntil(+ () => existsSync(configPath) && /enabled:\s*true/.test(readFileSync(configPath, 'utf-8')),+ 15_000,+ );++ // Contract: the live sync engine must observe the persisted value even+ // though the watcher echo never fired.+ await pollUntil(() => srv.instance.syncEngine?.getStatus().syncEnabled === true, 15_000);+ },+ { timeout: 90_000 },+ );++ test(+ 'semantic search hot-applies search.semantic.enabled from a client patch',+ async () => {+ const statusUrl = `http://127.0.0.1:${srv.port}/api/semantic-status`;++ const before = await (await fetch(statusUrl)).json();+ expect(before.enabled).toBe(false);++ const result = binding.patch({ search: { semantic: { enabled: true } } });+ expect(result.ok).toBe(true);++ // Contract: the semantic-search service must observe the persisted value+ // even though the watcher echo never fired. Observed through the existing+ // read-only /api/semantic-status surface.+ await pollUntil(async () => {+ const res = await fetch(statusUrl);+ const body = await res.json();+ return body.enabled === true;+ }, 15_000);+ },+ { timeout: 90_000 },+ );+});++/**+ * The two tests above pin the `'persisted'` success outcome of `storeConfigDoc`.+ * `storeConfigDoc` has a SECOND success outcome — `'reconciled'` — which the+ * producer-side propagation fix must also honor, and which is not exercised+ * above.+ *+ * `'reconciled'` fires when, at store time, the on-disk config file has diverged+ * from the LKG cache AND the disk content validates — i.e. an external /+ * cross-process writer landed on the shared config file while this server's+ * Y.Doc view was stale. `storeConfigDoc` then imports the DISK content into+ * Y.Text (under CONFIG_FILE_WATCHER_ORIGIN), sets LKG = disk, and returns+ * `'reconciled'` WITHOUT writing the client's value. See+ * `config-persistence.ts` storeConfigDocInner: the in-lock+ * `diskContent !== lkg` + `diskValidation.ok` branch.+ *+ * Contract this test pins: after a reconciliation triggered by a client patch,+ * the live in-process consumers must observe the RECONCILED (disk) value — the+ * exact value the (swallowed) chokidar echo would otherwise have carried. A+ * fix that fires the producer notification only on `'persisted'` and not on+ * `'reconciled'` would fail this test.+ *+ * This uses a fresh server (own contentDir) so the LKG / disk / consumer state+ * is controlled from boot and is independent of the two tests above.+ */+describe('PRD-7260 — reconciled config change reaches in-process consumers without the watcher echo', () => {+ let srv: TestServer;+ let ydoc: Y.Doc;+ let provider: HocuspocusProvider;+ let binding: ConfigBinding;++ beforeAll(async () => {+ srv = await createTestServer();+ await wait(FALLBACK_POLL_WINDOW_MS);++ ydoc = new Y.Doc();+ provider = new HocuspocusProvider({+ url: `ws://127.0.0.1:${srv.port}/collab`,+ name: CONFIG_DOC_NAME_PROJECT_LOCAL,+ document: ydoc,+ connect: true,+ });+ binding = bindConfigDoc(provider, 'project-local');+ await pollUntil(() => binding.hasSynced(), 10_000);+ }, 40_000);++ afterAll(async () => {+ binding?.dispose();+ provider?.destroy();+ ydoc?.destroy();+ await srv?.cleanup();+ });++ test(+ 'sync engine hot-applies the reconciled (disk) autoSync.enabled after a client patch',+ async () => {+ const configPath = join(srv.contentDir, '.ok', 'local', 'config.yml');+ expect(srv.instance.syncEngine?.getStatus().syncEnabled).toBe(false);++ // An external / cross-process writer lands `autoSync.enabled: true` on the+ // shared project-local config file. With the chokidar echo swallowed the+ // server never imports it, so at the next store the on-disk content+ // diverges from LKG — the `'reconciled'` precondition.+ mkdirSync(dirname(configPath), { recursive: true });+ writeFileSync(configPath, 'autoSync:\n enabled: true\n', 'utf-8');++ // Client patches the OPPOSITE value. At store time `storeConfigDoc` sees+ // disk (`true`) diverge from LKG, validates it, imports the disk content+ // into Y.Text, and returns `'reconciled'` — the client's `false` is+ // dropped in favor of the external writer's `true`.+ const result = binding.patch({ autoSync: { enabled: false } });+ expect(result.ok).toBe(true);++ // Reconciliation imports disk into Y.Text but does NOT write disk — the+ // client's `false` never reaches the file. Disk still shows the external+ // writer's `true`, proving the reconcile path (not the persist path) ran.+ await pollUntil(+ () =>+ existsSync(configPath) &&+ /enabled:\s*true/.test(readFileSync(configPath, 'utf-8')) &&+ !/enabled:\s*false/.test(readFileSync(configPath, 'utf-8')),+ 15_000,+ );++ // Reconciliation imports the disk content back into Y.Text, which syncs to+ // the client — so the client's own view flips from its patched `false` to+ // the reconciled `true`. This distinguishes a genuine `'reconciled'`+ // outcome from a no-op (a no-op would leave the client at `false`), and+ // holds today, independent of the consumer-propagation fix.+ await pollUntil(() => binding.current().autoSync?.enabled === true, 15_000);++ // Contract: the live sync engine must observe the reconciled DISK value+ // (`true`) even though the watcher echo never fired.+ await pollUntil(() => srv.instance.syncEngine?.getStatus().syncEnabled === true, 15_000);+ },+ { timeout: 90_000 },+ );+});diff --git a/packages/server/src/config-persistence.test.ts b/packages/server/src/config-persistence.test.tsindex 648b74d1b..78054975d 100644--- a/packages/server/src/config-persistence.test.ts+++ b/packages/server/src/config-persistence.test.ts@@ -689,6 +689,85 @@ describe('persistence extension dispatch — config-doc integration', () => {expect(readFileSync(path, 'utf-8')).toBe('mcp:\n autoStart: false\n');});+ test('throwing onConfigPersisted does not surface as a store failure; persist still lands on disk', async () => {+ // The persist already succeeded by the time onConfigPersisted fires — a+ // throwing consumer-notify callback must not propagate into Hocuspocus's+ // onStoreDocument lifecycle (it would misreport a durable write as a+ // store failure).+ const { createPersistenceExtension } = await import('./persistence.ts');+ const notified: string[] = [];++ const handle = createPersistenceExtension({+ contentDir: fx.projectDir,+ projectDir: fx.projectDir,+ gitEnabled: false,+ configHomedirOverride: fx.homedir,+ onConfigPersisted: (docName) => {+ notified.push(docName);+ throw new Error('consumer notify failed');+ },+ });++ const document = new Y.Doc();+ document.getText('source').insert(0, 'mcp:\n autoStart: false\n');++ // The await resolving IS the assertion that no exception escapes the hook.+ await handle.extension.onStoreDocument?.({+ document,+ documentName: CONFIG_DOC_NAME_PROJECT,+ lastTransactionOrigin: undefined,+ // biome-ignore lint/suspicious/noExplicitAny: minimal Hocuspocus shim+ } as any);++ // The callback DID fire with the right docName — the isolation assertion+ // above can't pass vacuously via a never-invoked callback.+ expect(notified).toEqual([CONFIG_DOC_NAME_PROJECT]);+ // And the persist itself succeeded: config content landed on disk.+ const path = configDocAbsPath(CONFIG_DOC_NAME_PROJECT, fx.ctx);+ expect(readFileSync(path, 'utf-8')).toBe('mcp:\n autoStart: false\n');+ });++ test('onConfigPersisted fires only on durable outcomes — a no-op store does not notify', async () => {+ // The callback's contract is "a validated config value just reached durable+ // state". A store whose content matches LKG returns 'no-op' without+ // touching disk; notifying consumers there would widen the contract to+ // "every store attempt" (spurious re-applies + log noise).+ const { createPersistenceExtension } = await import('./persistence.ts');+ const notified: string[] = [];++ const handle = createPersistenceExtension({+ contentDir: fx.projectDir,+ projectDir: fx.projectDir,+ gitEnabled: false,+ configHomedirOverride: fx.homedir,+ onConfigPersisted: (docName) => {+ notified.push(docName);+ },+ });++ const document = new Y.Doc();+ document.getText('source').insert(0, 'mcp:\n autoStart: false\n');++ // First store: durable write ('persisted') — notifies once and sets LKG.+ await handle.extension.onStoreDocument?.({+ document,+ documentName: CONFIG_DOC_NAME_PROJECT,+ lastTransactionOrigin: undefined,+ // biome-ignore lint/suspicious/noExplicitAny: minimal Hocuspocus shim+ } as any);+ expect(notified).toEqual([CONFIG_DOC_NAME_PROJECT]);++ // Second store with unchanged content: LKG equality short-circuits to+ // 'no-op' — consumers must NOT be re-notified.+ await handle.extension.onStoreDocument?.({+ document,+ documentName: CONFIG_DOC_NAME_PROJECT,+ lastTransactionOrigin: undefined,+ // biome-ignore lint/suspicious/noExplicitAny: minimal Hocuspocus shim+ } as any);+ expect(notified).toEqual([CONFIG_DOC_NAME_PROJECT]);+ });+test('config-doc onStoreDocument fires onConfigRejected callback through ctx', async () => {const { createPersistenceExtension } = await import('./persistence.ts');const rejections: Array<{ docName: string; error: ConfigValidationError }> = [];diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.tsindex 7de02cbf5..e41281a56 100644--- a/packages/server/src/persistence.ts+++ b/packages/server/src/persistence.ts@@ -345,6 +345,16 @@ export interface PersistenceOptions {* plugin mode where no CC1Broadcaster is available.*/onConfigRejected?: (docName: string, error: ConfigValidationError) => void;+ /**+ * Fired after the L3 persistence hook durably persists (or reconciles)+ * a config doc on the self-originated Y.Doc path. Wired in boot to+ * re-apply the now-durable config to the live in-process consumers (sync+ * engine, semantic search) directly — either the value this persist wrote+ * (`'persisted'`) or a winning external writer's value imported on reconcile+ * (`'reconciled'`) — so it reaches them even when the chokidar echo never+ * fires. Omitted in plugin mode.+ */+ onConfigPersisted?: (docName: string) => void;/*** MarkdownManager instance used by `storeDocumentNow`'s pre-write* sanity check (`fragmentBody = mgr.serialize(json)`). Defaults to@@ -631,6 +641,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persisconst onAgentCommit = options?.onAgentCommit;const onFlushCommit = options?.onFlushCommit;const onDiskFlush = options?.onDiskFlush;+ const onConfigPersisted = options?.onConfigPersisted;// Per-instance MarkdownManager seam used by `storeDocumentNow`'s pre-write// sanity check. Defaults to the production singleton. Tests inject a// dedicated `new MarkdownManager({ extensions: sharedExtensions })` so the@@ -2180,7 +2191,26 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis}) {if (isSystemDoc(documentName)) return;if (isConfigDoc(documentName)) {- await storeConfigDoc(document, documentName, lastTransactionOrigin, configPersistenceCtx);+ const outcome = await storeConfigDoc(+ document,+ documentName,+ lastTransactionOrigin,+ configPersistenceCtx,+ );+ // A validated config value just reached durable state — either written+ // by this persist (`'persisted'`) or imported from a winning external+ // writer on reconcile (`'reconciled'`). Notify live in-process consumers+ // directly; the chokidar echo is a non-guaranteed, OS-mediated+ // filesystem-event channel that can drop this event (permanent+ // divergence until restart). The persist already succeeded, so a+ // consumer-notify throw must not surface as a store failure.+ if (outcome === 'persisted' || outcome === 'reconciled') {+ try {+ onConfigPersisted?.(documentName);+ } catch (err) {+ log.warn({ err, documentName }, '[persistence] onConfigPersisted callback failed');+ }+ }return;}if (isManagedArtifactDoc(documentName)) {diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex 21ea97169..386967469 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -505,6 +505,56 @@ export function createServer(options: ServerOptions): ServerInstance {return `${normalizeProviderId(cfg.baseUrl)}|${cfg.model}|${cfg.dimensions ?? DEFAULT_EMBEDDINGS_DIMENSIONS}`;}+ // Re-apply a just-persisted config to the live in-process consumers by+ // re-reading it fresh from disk. Shared by two entry points: the producer-side+ // `onConfigPersisted` notification (self-originated Y.Doc writes) and the+ // config-file-watcher callback (genuinely external edits). The producer path is+ // load-bearing because the chokidar echo is a non-guaranteed, OS-mediated+ // filesystem-event channel — a dropped event otherwise leaves a consumer+ // diverged from disk until restart. Hoisted so `onConfigPersisted` can+ // reference it before `syncEngine` is assigned; both consumers resolve at call+ // time (persist time), always after their assignment.+ //+ // Both entry points can fire for the same change (producer notify + watcher+ // echo), so every consumer notified here MUST be idempotent on a same-value+ // re-apply: `SyncEngine.setEnabled` and `SemanticSearchService.applyConfig`+ // both early-return when the value is unchanged. A future non-idempotent+ // consumer added here would double-fire.+ function applyPersistedConfigToConsumers(configDocName: string): void {+ let appliedAutoSyncEnabled: boolean | undefined;+ if (+ configDocName === CONFIG_DOC_NAME_PROJECT ||+ configDocName === CONFIG_DOC_NAME_PROJECT_LOCAL+ ) {+ appliedAutoSyncEnabled = readProjectAutoSyncEnabled();+ void syncEngine?.setEnabled(appliedAutoSyncEnabled).catch((err) => {+ log.warn(+ { err, enabled: appliedAutoSyncEnabled, docName: configDocName },+ '[sync] failed to apply autoSync.enabled from config',+ );+ });+ }+ // Re-evaluate semantic search on every config-doc store. `readSemanticSearchConfig`+ // resolves the project-local layer only, so only a project-local `search.semantic.*`+ // edit changes the result; other layers re-read to the same value (a no-op via+ // `applyConfig`'s early-return). A live disable frees the resident vectors; a+ // provider/model/dims change re-warms. No eager embed — the next opt-in search+ // drives the corpus pass.+ const semCfg = readSemanticSearchConfig();+ semanticSearch.applyConfig({+ enabled: semCfg.enabled,+ providerFingerprint: semanticProviderFingerprint(semCfg),+ });+ log.info(+ {+ docName: configDocName,+ autoSyncEnabled: appliedAutoSyncEnabled,+ semanticEnabled: semCfg.enabled,+ },+ '[config] applied persisted config to in-process consumers',+ );+ }+// Initialize OpenTelemetry before any spans could be emitted. No-op when// OTEL_SDK_DISABLED != 'false' (default — zero overhead). Idempotent; safe// to call multiple times (bootServer also calls it, but dev-plugin path@@ -914,6 +964,12 @@ export function createServer(options: ServerOptions): ServerInstance {// pattern.onConfigRejected: (docName, error) =>cc1Broadcaster?.emitConfigValidationRejected(docName, error),+ // Producer-side hot-apply. Fired when the config-doc branch durably+ // persists (or reconciles) a self-originated change; re-applies it to the+ // live consumers directly so a dropped chokidar echo can't strand them.+ // Closure-deferred: `syncEngine`/`semanticSearch` resolve at call time,+ // always after their assignment.+ onConfigPersisted: applyPersistedConfigToConsumers,mdManager: options.mdManager,};@@ -2668,24 +2724,7 @@ export function createServer(options: ServerOptions): ServerInstance {{ docName: configDocName, outcome },'[config-file-watcher] applyExternalConfigChange outcome',);- if (- configDocName === CONFIG_DOC_NAME_PROJECT ||- configDocName === CONFIG_DOC_NAME_PROJECT_LOCAL- ) {- const enabled = readProjectAutoSyncEnabled();- void syncEngine?.setEnabled(enabled).catch((err) => {- log.warn({ err, enabled }, '[sync] failed to apply autoSync.enabled from config');- });- }- // Re-evaluate semantic search on ANY config-layer change (project-local- // / project / user can all carry `search.semantic.*`). A live disable- // frees the resident vectors; a provider/model/dims change re-warms.- // No eager embed — the next opt-in search drives the corpus pass.- const semCfg = readSemanticSearchConfig();- semanticSearch.applyConfig({- enabled: semCfg.enabled,- providerFingerprint: semanticProviderFingerprint(semCfg),- });+ applyPersistedConfigToConsumers(configDocName);});configFileWatcherCleanups.push({ docName: configDocName, cleanup });log.info({ docName: configDocName, path: absPath }, '[config-file-watcher] started');