Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(open-knowledge): strip removed config keys, don't reject the file (#3080)
miles-kt-inkeep40ff215458f0
diff --git a/.changeset/config-removed-key-strip-and-continue.md b/.changeset/config-removed-key-strip-and-continue.mdnew file mode 100644index 000000000..5fe99d1aa--- /dev/null+++ b/.changeset/config-removed-key-strip-and-continue.md@@ -0,0 +1,22 @@+---+"@inkeep/open-knowledge": minor+---++A config key that was removed in a newer version no longer discards the rest of the file it appears in.++Config files accumulate keys that later releases retire. Until now, a single retired key anywhere in a file — your committed `.ok/config.yml`, your user-global `~/.ok/global.yml`, or the per-machine `.ok/local/config.yml` — invalidated the **whole** file: every unrelated setting in it silently reverted to its default. A long-dead cosmetic setting left behind in a config could therefore switch off something you actively depend on, with nothing reporting a failure. In one case a retired sidebar preference sitting in a project-local config threw away an explicit `autoSync.mode: full`, so Git sync stopped running and stayed off.++Now every config layer strips only the retired keys it finds, keeps every other setting at the value you wrote on disk, and reports each stripped key together with what replaced it. Genuinely broken files are unaffected by this change: invalid YAML and settings that fail validation are still rejected exactly as before. Only the handling of retired keys changed.++- **`ok start` no longer fails to start over a retired key in your committed `.ok/config.yml`.** It strips the dead key, prints what it found and the replacement guidance, and starts. Previously one stale key could stop the tool from starting at all.+- **`ok config migrate` can now reach your per-machine config.** It defaults to every layer, so the bare `ok config migrate` each error message tells you to run now fixes the key wherever it lives. A new `--scope project-local` targets `.ok/local/config.yml` alone, `--scope all` is the explicit form of the new default, `--scope both` keeps its old project-plus-user reach, and `--dry-run` still previews without writing. Migration only ever removes a retired key and reports its replacement — it never rewrites your other files on your behalf (for example, it will not create or edit `.okignore` for a removed `content.include`, because that rewrite is not a faithful one-to-one translation).+- **`ok config validate` now reports all three config layers.** It previously described only your user-global and committed-project files, so a retired key in the per-machine `.ok/local/config.yml` — the layer the reported bug lived in — got an unqualified `✓`. It now reads that layer too, so a stale key is findable without a running server. Reporting is read-only: an unreadable layer is described, never moved aside.+- **New endpoint `GET /api/config/diagnostics`** lists the retired keys currently present across your user, committed-project, and project-local configs, each identified by its scope, file, key path, and replacement guidance. It reads the files fresh on every request, so fixing a file is reflected on the next request without a restart, and it never returns your actual config values.++**Settings that a retired key was suppressing now take effect.** Some features deliberately fall back to a safe value when a config file cannot be trusted, and until now a retired key made a file untrusted. Those features therefore ignored what you had written in the same file. Now that a retired key leaves the file readable, your settings in it apply — which for an affected config is a real change in behavior, in both directions:++- **External link previews.** A project-local config carrying a retired key had link previews forced off, even when you had explicitly enabled them. Your explicit setting is now honored. If that file has no `linkPreviews` setting at all, the default (previews on) now applies, and hovering an external link sends its URL to the destination site where previously it did not.+- **Semantic search.** A `search.semantic` block sitting alongside a retired key was discarded, leaving semantic search off. Your configured provider and model now apply, and enabling semantic search sends content to that provider.+- **Editor bridge safeguards.** An explicit `bridge.*` opt-out alongside a retired key was overridden back on. Your opt-out now takes effect.++If you rely on any of these being off, check the config file the diagnostics endpoint or `ok config validate` reports a retired key in. A file that is genuinely unreadable (invalid YAML, or settings that fail validation) still falls back to the safe value exactly as before.diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdxindex e0c332e8e..cafcdbd8b 100644--- a/docs/content/reference/cli.mdx+++ b/docs/content/reference/cli.mdx@@ -124,7 +124,7 @@ Serve this project's web UI and `/mcp` endpoint to your other devices through an| `ok preview` | Show what content the watcher will track (read-only) — the quick check after a `content.dir` or `.okignore` change || `ok migrate notion <dir>` | Clean up a Notion export in place, dry-run unless `--apply` (see [migrating from Notion](/docs/migrate/notion)) || `ok config validate` | Validate the merged config (defaults → user → project) |-| `ok config migrate` | Remove deprecated keys from `config.yml` (`--dry-run` to preview; `--scope` project, user, or both) |+| `ok config migrate` | Remove keys the schema no longer reads from your config files (`--dry-run` to preview; `--scope` to narrow — defaults to every layer) || `ok skills installed` | List every skill installed across your agents (read-only, cross-harness) || `ok skills import <source>` | Import a skill as versioned content from skills.sh, a GitHub `owner/repo`, a git URL, or a local path || `ok bug-report` | Package a support bundle — recent app logs, the project's server logs and lock diagnostics, and system info — as an auto-redacted zip under `~/.ok/bug-reports/`, revealed in Finder when it's done (`--no-reveal` to skip). Collects the same `standard` set as the desktop app's **Help → Report a bug…**; `ok diagnose bundle` produces the `full` superset (telemetry spans, live server state) into the project's `.ok/local/diagnostics/` |diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdxindex 863693c0f..6f64aeee6 100644--- a/docs/content/reference/configuration.mdx+++ b/docs/content/reference/configuration.mdx@@ -58,7 +58,13 @@ A key set in a file more specific than its scope (a user-scope key in `.ok/confi| `search.semantic.similarityFloor` | number | (unset) | project-local | Optional hard cutoff (0–1): drops semantic matches whose cosine similarity is below it. Retrieval is rank-based, so most setups leave it unset; set it only for a provider/model whose cosine scale you know. || `linkPreviews.enabled` | boolean | `true` | project-local | Show a rich preview card (site name, page title, description, favicon) when you hover an external link in the editor. Default on (set to `false` to opt out). **When on, hovering an external link sends that link's URL to the destination site** to fetch its preview metadata — outbound egress, one request per previewed link. Previews of links to other documents in the project are read from the local index with no network request and are always on. See [Link previews](#link-previews) below. |-If `.ok/config.yml` contains a key that has been removed from the schema, config load fails with an error naming the replacement — a stale key is never a silent no-op. `ok config migrate` (`--dry-run` to preview; `--scope project|user|both`) strips removed keys from your config files.+## Removed keys++As new versions of OpenKnowledge are released, some keys are retired from the schema. If any of your config files contains a key the schema no longer reads, that key alone is dropped from the loaded config and reported with the setting that replaced it.++This applies to genuinely retired keys only. A file that cannot be trusted — invalid YAML, or a value that fails validation — is rejected and falls back to defaults.++Run `ok config validate` to see which keys are stale and what replaced each one. `ok config migrate` removes them for you; it defaults to every layer, so a bare run reaches whichever file the key lives in. Narrow it with `--scope project`, `project-local`, `user`, or `all` (the default), and preview with `--dry-run`. Migration deletes retired keys, but it never rewrites anything else on your behalf. A key whose replacement is not a one-to-one translation is removed and reported for you to recreate by hand.## Folder propertiesdiff --git a/packages/app/tests/integration/attribution-sweep-coverage.test.ts b/packages/app/tests/integration/attribution-sweep-coverage.test.tsindex 1f87692fb..be015ba02 100644--- a/packages/app/tests/integration/attribution-sweep-coverage.test.ts+++ b/packages/app/tests/integration/attribution-sweep-coverage.test.ts@@ -339,6 +339,10 @@ const EXEMPT_HANDLERS = new Set([// mutation and no agent content, so identity threading is exempt — same// rationale as `handleServerInfo`.'handleApiConfig',+ // `/api/config/diagnostics` — read-only GET reporting active config+ // diagnostics across the three layers. Reads config files, performs no+ // writes and no agent content, so there is nothing to attribute.+ 'handleConfigDiagnostics',// `ok seed` scaffolder endpoints. Operate on project-level// folder structure on behalf of the local user, not agent content — same// rationale as sync/local-op handlers. `handleSeedPacks` is a static-datadiff --git a/packages/app/tests/integration/config-diagnostics-endpoint.test.ts b/packages/app/tests/integration/config-diagnostics-endpoint.test.tsnew file mode 100644index 000000000..8a1edafec--- /dev/null+++ b/packages/app/tests/integration/config-diagnostics-endpoint.test.ts@@ -0,0 +1,184 @@+/**+ * Integration tests for `GET /api/config/diagnostics` — the read-only surface+ * that reports active config diagnostics across the user, committed-project,+ * and project-local layers.+ *+ * Drives the real endpoint against a booted server: the three config files are+ * written on disk, the handler reads them fresh per request, and the response+ * is asserted end to end. The scope→file resolution and the value-free+ * projection are unit-tested in+ * `packages/core/src/config/collect-config-diagnostics.test.ts`.+ */++import { mkdirSync, rmSync, writeFileSync } from 'node:fs';+import { dirname } from 'node:path';+import { REMOVED_KEYS, type WriteScope } from '@inkeep/open-knowledge-core';+import { resolveConfigPath } from '@inkeep/open-knowledge-core/server';+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';+import { stringify } from 'yaml';+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';+import { createTestServer, type TestServer } from './test-harness';++let server: TestServer;+let homeDir: string;++beforeAll(async () => {+ homeDir = `${process.env.TMPDIR ?? '/tmp'}/ok-diag-home-${Date.now()}-${Math.random().toString(36).slice(2)}`;+ mkdirSync(homeDir, { recursive: true });+ server = await createTestServer({ configHomedirOverride: homeDir });+}, HARNESS_BOOT_TIMEOUT_MS);++afterAll(async () => {+ await server.cleanup();+ rmSync(homeDir, { recursive: true, force: true });+});++/** Absolute path of the config file for `scope` under this server's dirs. */+function scopeFile(scope: WriteScope): string {+ return resolveConfigPath(scope, server.contentDir, homeDir);+}++/** Write `value` as YAML at the config path for `scope`. */+function writeScope(scope: WriteScope, value: Record<string, unknown>): void {+ const file = scopeFile(scope);+ mkdirSync(dirname(file), { recursive: true });+ writeFileSync(file, stringify(value), 'utf-8');+}++/** The registry redirect for a dotted key path — pins response ⇄ registry. */+function redirectFor(dottedPath: string): string {+ const entry = REMOVED_KEYS.find((k) => k.path.join('.') === dottedPath);+ if (!entry) throw new Error(`fixture key ${dottedPath} missing from registry`);+ return entry.redirect;+}++afterEach(() => {+ for (const scope of ['user', 'project', 'project-local'] as const) {+ rmSync(scopeFile(scope), { force: true });+ }+});++const url = () => `http://127.0.0.1:${server.port}/api/config/diagnostics`;++interface DiagnosticItem {+ code: string;+ scope: string;+ file: string;+ path?: string[];+ redirect?: string;+}++describe('GET /api/config/diagnostics', () => {+ test('reports each of the three config layers with scope, file, key path, code, and redirect', async () => {+ writeScope('user', {+ content: { dir: 'USER_REAL_DIR' },+ server: { host: 'user-secret-host.internal' },+ });+ writeScope('project', {+ content: { dir: 'PROJECT_REAL_DIR' },+ folders: ['project-secret-folder'],+ });+ writeScope('project-local', {+ content: { dir: 'LOCAL_REAL_DIR' },+ autoSync: { mode: 'full' },+ appearance: { sidebar: { showAllFiles: false } },+ });++ const res = await fetch(url());+ expect(res.status).toBe(200);+ const body = (await res.json()) as { diagnostics: DiagnosticItem[] };++ const byScope = new Map(body.diagnostics.map((d) => [d.scope, d]));+ expect(byScope.get('user')).toEqual({+ code: 'REMOVED_KEY',+ scope: 'user',+ file: scopeFile('user'),+ path: ['server', 'host'],+ redirect: redirectFor('server.host'),+ });+ expect(byScope.get('project')).toEqual({+ code: 'REMOVED_KEY',+ scope: 'project',+ file: scopeFile('project'),+ path: ['folders'],+ redirect: redirectFor('folders'),+ });+ expect(byScope.get('project-local')).toEqual({+ code: 'REMOVED_KEY',+ scope: 'project-local',+ file: scopeFile('project-local'),+ path: ['appearance', 'sidebar', 'showAllFiles'],+ redirect: redirectFor('appearance.sidebar.showAllFiles'),+ });+ });++ test('the response body carries Cache-Control: no-store and no raw config values', async () => {+ writeScope('user', {+ content: { dir: 'USER_REAL_DIR' },+ server: { host: 'user-secret-host.internal' },+ });+ writeScope('project', {+ content: { dir: 'PROJECT_REAL_DIR' },+ folders: ['project-secret-folder'],+ });+ writeScope('project-local', {+ content: { dir: 'LOCAL_REAL_DIR' },+ autoSync: { mode: 'full' },+ appearance: { sidebar: { showAllFiles: false } },+ });++ const res = await fetch(url());+ expect(res.headers.get('cache-control')).toBe('no-store');+ const text = await res.text();+ for (const secret of [+ 'USER_REAL_DIR',+ 'PROJECT_REAL_DIR',+ 'LOCAL_REAL_DIR',+ 'user-secret-host.internal',+ 'project-secret-folder',+ ]) {+ expect(text).not.toContain(secret);+ }+ });++ test('a stale key removed from disk is omitted on the very next request without a restart', async () => {+ writeScope('project-local', {+ appearance: { sidebar: { showAllFiles: false } },+ mcp: { autoStart: false },+ });++ const first = (await (await fetch(url())).json()) as { diagnostics: DiagnosticItem[] };+ const firstPaths = first.diagnostics.map((d) => d.path?.join('.')).sort();+ expect(firstPaths).toEqual(['appearance.sidebar.showAllFiles', 'mcp.autoStart']);++ // Drop one stale key on disk; the same long-lived server must reflect it.+ writeScope('project-local', { mcp: { autoStart: false } });++ const second = (await (await fetch(url())).json()) as { diagnostics: DiagnosticItem[] };+ expect(second.diagnostics.map((d) => d.path?.join('.'))).toEqual(['mcp.autoStart']);+ });++ test('no config files present → 200 with an empty diagnostics list', async () => {+ const res = await fetch(url());+ expect(res.status).toBe(200);+ expect((await res.json()) as unknown).toEqual({ diagnostics: [] });+ });++ test('a non-GET/HEAD method is rejected 405 with an Allow header', async () => {+ for (const method of ['POST', 'PUT', 'DELETE']) {+ const res = await fetch(url(), { method });+ expect(res.status).toBe(405);+ const allow = res.headers.get('allow') ?? '';+ expect(allow).toContain('GET');+ expect(allow).toContain('HEAD');+ }+ });++ test('HEAD returns 200 with no-store and an empty body', async () => {+ writeScope('project-local', { appearance: { sidebar: { showAllFiles: false } } });+ const res = await fetch(url(), { method: 'HEAD' });+ expect(res.status).toBe(200);+ expect(res.headers.get('cache-control')).toBe('no-store');+ expect(await res.text()).toBe('');+ });+});diff --git a/packages/app/tests/integration/conflict-gate-coverage.test.ts b/packages/app/tests/integration/conflict-gate-coverage.test.tsindex adc86ceda..faca93c35 100644--- a/packages/app/tests/integration/conflict-gate-coverage.test.ts+++ b/packages/app/tests/integration/conflict-gate-coverage.test.ts@@ -184,6 +184,11 @@ const EXEMPT_HANDLERS = new Set([// `/api/config` — collab-bootstrap payload. GET reads server-lock. Does not// target a Y.Doc, so the per-doc conflict gate does not apply.'handleApiConfig',+ // `/api/config/diagnostics` (GET) — read-only listing of active config+ // diagnostics across the user, committed-project, and project-local layers.+ // Reads config files fresh per request; targets no Y.Doc, so the per-doc+ // conflict gate does not apply — same posture as `handleApiConfig`.+ 'handleConfigDiagnostics','handleRescueList','handleSyncStatus','handleSyncConflicts',diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.tsindex 7279e01cf..87d216fcd 100644--- a/packages/cli/src/cli.ts+++ b/packages/cli/src/cli.ts@@ -21,6 +21,7 @@ trustSystemCertificates();import { spawn } from 'node:child_process';import { resolve } from 'node:path';+import { humanFormat } from '@inkeep/open-knowledge-core';import { type Config, ConfigSchema, trustSystemCertificates } from '@inkeep/open-knowledge-server';/*** CLI entry point for @inkeep/open-knowledge.@@ -38,7 +39,7 @@ import { authCommand } from './commands/auth/index.ts';import { bugReportCommand } from './commands/bug-report.ts';import { cleanCommand } from './commands/clean.ts';import { cloneCommand } from './commands/clone.ts';-import { configCommand } from './commands/config.ts';+import { configCommand, shouldAnnounceRemovedKeys } from './commands/config.ts';import { coworkCommand } from './commands/cowork.ts';import { deinitCommand } from './commands/deinit.ts';import { createRealDetectDeps, detectDesktop, launchDesktop } from './commands/desktop-dispatch.ts';@@ -149,7 +150,26 @@ program// loud fail-fast so the user notices a config they can fix in place.let config: Config;try {- config = loadConfig(anchorRoot ?? cwd).config;+ const loaded = loadConfig(anchorRoot ?? cwd);+ config = loaded.config;+ // Report stale keys once per invocation. The reader strips them and+ // returns them rather than logging, so for most commands this is the+ // only place a user learns their config carries a key that no longer+ // does anything. stderr keeps `ok mcp`'s stdout JSON-RPC stream clean.+ //+ // The `config` command family owns this reporting and is excluded — see+ // `shouldAnnounceRemovedKeys`.+ //+ // Filtered to `REMOVED_KEY` for the same reason the server's+ // `logConfigDiagnosticsOnce` filters: `readConfigSafely` already warned+ // about every corruption code on its way out, so printing those again+ // here shows the user one fault twice in two different formats.+ if (shouldAnnounceRemovedKeys(subcommandName)) {+ for (const diagnostic of loaded.diagnostics) {+ if (diagnostic.code !== 'REMOVED_KEY') continue;+ console.error(`[ok] ${humanFormat(diagnostic)}`);+ }+ }} catch (err) {if (subcommandName === 'uninstall' || subcommandName === 'deinit') {// Surface the original parse error before degrading — the user shoulddiff --git a/packages/cli/src/commands/config.test.ts b/packages/cli/src/commands/config.test.tsindex 029fdb500..e72f52844 100644--- a/packages/cli/src/commands/config.test.ts+++ b/packages/cli/src/commands/config.test.ts@@ -1,10 +1,17 @@-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import { REMOVED_KEYS } from '@inkeep/open-knowledge-core';-import { afterEach, beforeEach, describe, expect, test } from 'vitest';+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import { CONFIG_FILENAME, OK_DIR } from '../constants.ts';-import { buildClearPatchForTest, DROPPED_FIELD_PATHS, runMigrate, runValidate } from './config.ts';+import {+ buildClearPatchForTest,+ configCommand,+ DROPPED_FIELD_PATHS,+ runMigrate,+ runValidate,+ shouldAnnounceRemovedKeys,+} from './config.ts';// Re-exported via the test module helper at the bottom of this file. The// `buildClearPatch` helper isn't exported by config.ts directly (kept private@@ -33,6 +40,12 @@ function projectConfigPath(cwd: string): string {return join(cwd, OK_DIR, CONFIG_FILENAME);}+function projectLocalConfigPath(cwd: string): string {+ // Project-local config lives at `<cwd>/.ok/local/config.yml` (gitignored,+ // per-machine); see `resolveConfigPath('project-local', …)` in core.+ return join(cwd, OK_DIR, 'local', CONFIG_FILENAME);+}+function userConfigPath(home: string): string {// User-global config lives at `~/.ok/global.yml` (distinct from project// `.ok/config.yml`); see `resolveConfigPath('user', …)` in core.@@ -49,10 +62,13 @@ describe('runValidate', () => {const stderr: string[] = [];const stdout: string[] = [];const outcome = runValidate({+ readProjectLocalFn: () => [],loadConfigFn: () =>({config: {} as never,sources: ['/home/test/project/.ok/config.yml'],+ diagnostics: [],+ sidelined: [],}) as never,log: (msg) => stderr.push(msg),error: (msg) => stderr.push(msg),@@ -63,19 +79,107 @@ describe('runValidate', () => {expect(stdout).toEqual([]);});+ test('degraded layer → headline does not claim valid, and names the file it moved aside', () => {+ // A user whose global config is corrupt gets it renamed out of the way so+ // OK can boot on defaults. Reporting an unqualified "valid" here sends a+ // reader who skims for the checkmark away believing nothing happened, and+ // saying nothing about the rename reads as the file having vanished.+ //+ // The headline stays code-agnostic: this fixture is a YAML_PARSE, where the+ // file read fine and the syntax is what failed, so a "could not be read"+ // summary would send the user after file permissions. `humanFormat` below+ // it names the real cause.+ const stderr: string[] = [];+ const outcome = runValidate({+ readProjectLocalFn: () => [],+ loadConfigFn: () =>+ ({+ config: {} as never,+ sources: ['/home/test/project/.ok/config.yml'],+ diagnostics: [{ code: 'YAML_PARSE', detail: 'unexpected end of flow sequence' }],+ sidelined: [+ {+ from: '/home/test/.ok/global.yml',+ to: '/home/test/.ok/global.yml.invalid-2026-01-01T00-00-00-000Z',+ },+ ],+ }) as never,+ log: (msg) => stderr.push(msg),+ error: (msg) => stderr.push(msg),+ });+ const joined = stderr.join('\n');+ expect(outcome.ok).toBe(true);+ expect(joined).not.toContain('✓ Configuration valid');+ expect(joined).toContain('config layer(s) had issues');+ expect(joined).not.toContain('could not be read');+ expect(joined).toContain('unexpected end of flow sequence');+ expect(joined).toContain('/home/test/.ok/global.yml.invalid-2026-01-01T00-00-00-000Z');+ });++ test('removed keys alone do not qualify the headline', () => {+ // A stripped key leaves the file usable, so it must not downgrade the+ // headline the way an unreadable layer does.+ const stderr: string[] = [];+ runValidate({+ readProjectLocalFn: () => [],+ loadConfigFn: () =>+ ({+ config: {} as never,+ sources: ['/home/test/project/.ok/config.yml'],+ diagnostics: [{ code: 'REMOVED_KEY', path: ['server', 'host'], redirect: 'Use --host.' }],+ sidelined: [],+ }) as never,+ log: (msg) => stderr.push(msg),+ error: (msg) => stderr.push(msg),+ });+ const joined = stderr.join('\n');+ expect(joined).toContain('✓ Configuration valid');+ expect(joined).toContain('server.host');+ });+test('no sources → "defaults only"', () => {const stderr: string[] = [];const outcome = runValidate({- loadConfigFn: () => ({ config: {} as never, sources: [] }) as never,+ readProjectLocalFn: () => [],+ loadConfigFn: () =>+ ({ config: {} as never, sources: [], diagnostics: [], sidelined: [] }) as never,log: (msg) => stderr.push(msg),});expect(outcome.ok).toBe(true);expect(stderr.some((m) => m.includes('defaults only'))).toBe(true);});+ test('removed key in project config → valid (exit 0) with the finding + redirect reported', () => {+ // Full path: a committed config carrying a removed key still validates+ // (removed keys never block), and the finding is reported with its+ // replacement guidance. Mirrors the real-loadConfig test above.+ const project = makeTempProject();+ try {+ writeConfigYaml(+ projectConfigPath(project.cwd),+ 'content:\n dir: docs\nserver:\n host: 0.0.0.0\n',+ );+ const out: string[] = [];+ const outcome = runValidate({+ cwd: project.cwd,+ log: (msg) => out.push(msg),+ error: (msg) => out.push(msg),+ });+ expect(outcome.ok).toBe(true);+ const joined = out.join('\n');+ expect(joined).toContain('✓ Configuration valid');+ // Names the dead key and surfaces its replacement guidance.+ expect(joined).toContain('server.host');+ expect(joined).toContain('--host');+ } finally {+ project.cleanup();+ }+ });+test('schema-fail → ok:false and stderr contains the thrown error message', () => {const stderr: string[] = [];const outcome = runValidate({+ readProjectLocalFn: () => [],loadConfigFn: () => {throw new Error('Invalid configuration at /tmp/.ok/config.yml:7:18\n ...');},@@ -86,6 +190,59 @@ describe('runValidate', () => {expect(stderr.some((m) => m.includes(':7:18'))).toBe(true);});+ // `loadConfig` merges user + committed project only, so the per-machine layer+ // — where a stale key silently discards a live `autoSync.mode` — was the one+ // `validate` could not see: a user following the docs got a ✓ and no way to+ // find the dead key without a running server.+ test('a removed key in project-local config is reported, not answered with ✓', () => {+ const project = makeTempProject();+ try {+ writeConfigYaml(+ projectLocalConfigPath(project.cwd),+ 'autoSync:\n mode: full\nappearance:\n sidebar:\n showAllFiles: false\n',+ );+ const out: string[] = [];+ const outcome = runValidate({+ cwd: project.cwd,+ log: (msg) => out.push(msg),+ error: (msg) => out.push(msg),+ });++ const joined = out.join('\n');+ expect(outcome.ok).toBe(true);+ expect(joined).toContain('appearance.sidebar.showAllFiles');+ // A removed key leaves the layer usable, so the headline stays clean —+ // the finding below it is what the user acts on.+ expect(joined).toContain('✓ Configuration valid');+ } finally {+ project.cleanup();+ }+ });++ test('reporting the project-local layer never renames it', () => {+ // The read is `sideline: false`: `validate` describes a corrupt layer, it+ // does not quarantine one. A command that moved a file aside just for being+ // inspected would be a destructive read.+ const project = makeTempProject();+ try {+ const localPath = projectLocalConfigPath(project.cwd);+ writeConfigYaml(localPath, 'autoSync:\n mode: [invalid yaml');+ const out: string[] = [];++ const outcome = runValidate({+ cwd: project.cwd,+ log: (msg) => out.push(msg),+ error: (msg) => out.push(msg),+ });++ expect(outcome.ok).toBe(true);+ expect(out.join('\n')).toContain('config layer(s) had issues');+ expect(existsSync(localPath)).toBe(true);+ } finally {+ project.cleanup();+ }+ });+test('source-located error rendering through real loadConfig', () => {const project = makeTempProject();try {@@ -108,6 +265,20 @@ describe('runValidate', () => {});});+describe('shouldAnnounceRemovedKeys', () => {+ test('suppressed for the config command family, which reports them itself', () => {+ // `config validate` renders the findings as its result and `config migrate`+ // removes them; a startup announcement would print each finding twice.+ expect(shouldAnnounceRemovedKeys('config')).toBe(false);+ });++ test('announced for every other command, which would otherwise never show them', () => {+ for (const name of ['start', 'ui', 'mcp', 'status', 'embeddings', undefined]) {+ expect(shouldAnnounceRemovedKeys(name)).toBe(true);+ }+ });+});+describe('runMigrate', () => {let project: ReturnType<typeof makeTempProject>;@@ -327,6 +498,173 @@ describe('runMigrate', () => {expect(outcome.outcomes.length).toBe(2);});+ test('--scope project-local strips removed keys, preserves other local settings', async () => {+ const localPath = projectLocalConfigPath(project.cwd);+ // The field-bug shape: an explicit per-machine autoSync.mode alongside the+ // dead appearance.sidebar.showAllFiles key.+ writeConfigYaml(+ localPath,+ 'autoSync:\n mode: full\nappearance:\n sidebar:\n showAllFiles: true\n',+ );+ const outcome = await runMigrate({+ cwd: project.cwd,+ scope: 'project-local',+ homedirOverride: project.userHome,+ log: () => {},+ });+ expect(outcome.ok).toBe(true);+ const migrated = readFileSync(localPath, 'utf-8');+ expect(migrated).not.toContain('showAllFiles');+ // The unrelated per-machine setting survives on disk.+ expect(migrated).toContain('mode: full');+ const localOutcome = outcome.outcomes.find((o) => o.scope === 'project-local');+ expect(localOutcome?.removed).toContain('appearance.sidebar.showAllFiles');+ expect(outcome.outcomes.every((o) => o.scope === 'project-local')).toBe(true);+ });++ test('--scope project-local is idempotent — second run writes nothing', async () => {+ const localPath = projectLocalConfigPath(project.cwd);+ writeConfigYaml(+ localPath,+ 'autoSync:\n mode: full\nappearance:\n sidebar:\n showAllFiles: true\n',+ );+ await runMigrate({+ cwd: project.cwd,+ scope: 'project-local',+ homedirOverride: project.userHome,+ log: () => {},+ });+ const afterFirst = readFileSync(localPath, 'utf-8');+ const stdout: string[] = [];+ const outcome = await runMigrate({+ cwd: project.cwd,+ scope: 'project-local',+ homedirOverride: project.userHome,+ log: (msg) => stdout.push(msg),+ });+ expect(outcome.ok).toBe(true);+ expect(stdout).toEqual(['No deprecated fields found.']);+ expect(readFileSync(localPath, 'utf-8')).toBe(afterFirst);+ });++ test('--scope project-local --dry-run previews without writing', async () => {+ const localPath = projectLocalConfigPath(project.cwd);+ const original = 'autoSync:\n mode: full\nappearance:\n sidebar:\n showAllFiles: true\n';+ writeConfigYaml(localPath, original);+ const stdout: string[] = [];+ const outcome = await runMigrate({+ cwd: project.cwd,+ scope: 'project-local',+ dryRun: true,+ homedirOverride: project.userHome,+ log: (msg) => stdout.push(msg),+ });+ expect(outcome.ok).toBe(true);+ expect(readFileSync(localPath, 'utf-8')).toBe(original);+ expect(stdout.some((m) => m.includes('[dry-run]') && m.includes('showAllFiles'))).toBe(true);+ const localOutcome = outcome.outcomes.find((o) => o.scope === 'project-local');+ expect(localOutcome?.removed).toEqual([]);+ });++ test('--scope all migrates project, project-local, and user files', async () => {+ const wsPath = projectConfigPath(project.cwd);+ const localPath = projectLocalConfigPath(project.cwd);+ const userPath = userConfigPath(project.userHome);+ writeConfigYaml(wsPath, 'folders:\n - notes\ncontent:\n dir: docs\n');+ writeConfigYaml(+ localPath,+ 'autoSync:\n mode: full\nappearance:\n sidebar:\n showAllFiles: true\n',+ );+ writeConfigYaml(userPath, 'appearance:\n editorModeDefault: source\n');+ const outcome = await runMigrate({+ cwd: project.cwd,+ scope: 'all',+ homedirOverride: project.userHome,+ log: () => {},+ });+ expect(outcome.ok).toBe(true);+ expect(readFileSync(wsPath, 'utf-8')).not.toContain('folders');+ expect(readFileSync(wsPath, 'utf-8')).toContain('dir: docs');+ expect(readFileSync(localPath, 'utf-8')).not.toContain('showAllFiles');+ expect(readFileSync(localPath, 'utf-8')).toContain('mode: full');+ expect(readFileSync(userPath, 'utf-8')).not.toContain('editorModeDefault');+ expect(outcome.outcomes.map((o) => o.scope).sort()).toEqual([+ 'project',+ 'project-local',+ 'user',+ ]);+ });++ test('--scope both leaves the project-local file untouched (alias = project + user)', async () => {+ const wsPath = projectConfigPath(project.cwd);+ const localPath = projectLocalConfigPath(project.cwd);+ const userPath = userConfigPath(project.userHome);+ writeConfigYaml(wsPath, 'folders:\n - notes\n');+ writeConfigYaml(localPath, 'appearance:\n sidebar:\n showAllFiles: true\n');+ writeConfigYaml(userPath, 'appearance:\n editorModeDefault: source\n');+ const localOriginal = readFileSync(localPath, 'utf-8');+ const outcome = await runMigrate({+ cwd: project.cwd,+ scope: 'both',+ homedirOverride: project.userHome,+ log: () => {},+ });+ expect(outcome.ok).toBe(true);+ expect(readFileSync(wsPath, 'utf-8')).not.toContain('folders');+ expect(readFileSync(userPath, 'utf-8')).not.toContain('editorModeDefault');+ // project-local is deliberately outside `both` — byte-for-byte unchanged.+ expect(readFileSync(localPath, 'utf-8')).toBe(localOriginal);+ expect(outcome.outcomes.map((o) => o.scope).sort()).toEqual(['project', 'user']);+ });++ test('the default scope reaches project-local, so the redirect hint is truthful', async () => {+ // Every removed-key redirect tells the user to run a bare `ok config+ // migrate`. If the default reach excluded project-local, following that+ // instruction verbatim would not fix a dead key living there.+ const wsPath = projectConfigPath(project.cwd);+ const localPath = projectLocalConfigPath(project.cwd);+ const userPath = userConfigPath(project.userHome);+ writeConfigYaml(wsPath, 'folders:\n - notes\n');+ writeConfigYaml(localPath, 'appearance:\n sidebar:\n showAllFiles: true\n');+ writeConfigYaml(userPath, 'appearance:\n editorModeDefault: source\n');+ // No `scope` passed — exercises the command's default reach.+ const outcome = await runMigrate({+ cwd: project.cwd,+ homedirOverride: project.userHome,+ log: () => {},+ });+ expect(outcome.ok).toBe(true);+ expect(readFileSync(localPath, 'utf-8')).not.toContain('showAllFiles');+ expect(outcome.outcomes.map((o) => o.scope).sort()).toEqual([+ 'project',+ 'project-local',+ 'user',+ ]);+ });++ test('content.include is stripped without writing .okignore', async () => {+ const wsPath = projectConfigPath(project.cwd);+ writeConfigYaml(wsPath, 'content:\n dir: .\n include:\n - "docs/**/*.md"\n');+ // content.dir defaults to '.', so any auto-created .okignore would land at+ // the project root beside .ok/.+ const okignorePath = join(project.cwd, '.okignore');+ const outcome = await runMigrate({+ cwd: project.cwd,+ scope: 'project',+ homedirOverride: project.userHome,+ log: () => {},+ });+ expect(outcome.ok).toBe(true);+ const migrated = readFileSync(wsPath, 'utf-8');+ expect(migrated).not.toContain('include:');+ expect(migrated).toContain('dir: .');+ // include→.okignore inverts intent, so the codemod only deletes the dead+ // key — it must never synthesize an .okignore on the user's behalf.+ expect(existsSync(okignorePath)).toBe(false);+ const wsOutcome = outcome.outcomes.find((o) => o.scope === 'project');+ expect(wsOutcome?.removed).toContain('content.include');+ });+test('unparseable YAML in project → ok:false with parse error reported', async () => {const wsPath = projectConfigPath(project.cwd);writeConfigYaml(wsPath, '{{{ not yaml at all\n');@@ -366,6 +704,40 @@ describe('runMigrate', () => {});});+describe('configCommand migrate --scope', () => {+ function migrateSubcommand() {+ const migrate = configCommand().commands.find((c) => c.name() === 'migrate');+ if (migrate === undefined) throw new Error('migrate subcommand not registered');+ return migrate;+ }++ test('help advertises project | project-local | user | all', () => {+ const migrate = migrateSubcommand();+ const scopeOption = migrate.options.find((o) => o.long === '--scope');+ // The option description is the source of the rendered help line; asserting+ // it directly avoids coupling to commander's terminal-width wrapping.+ expect(scopeOption?.description).toBe(+ 'Which scope to migrate: project | project-local | user | all',+ );+ expect(migrate.helpInformation()).toContain('project-local');+ });++ test('unrecognized --scope prints the accepted values and exits 2', async () => {+ const savedExitCode = process.exitCode;+ const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});+ try {+ await configCommand().parseAsync(['migrate', '--scope', 'bogus'], { from: 'user' });+ expect(process.exitCode).toBe(2);+ const printed = errorSpy.mock.calls.map((c) => c.join(' ')).join('\n');+ expect(printed).toContain('project | project-local | user | all');+ } finally {+ // Restore before assertions can leak exit code 2 to the vitest process.+ process.exitCode = savedExitCode;+ errorSpy.mockRestore();+ }+ });+});+describe('DROPPED_FIELD_PATHS', () => {test('is the silent-drop set followed by every removed-key registry path', () => {// Silently-dropped sections (no removed-key error) come first.diff --git a/packages/cli/src/commands/config.ts b/packages/cli/src/commands/config.tsindex ffa009b23..bbd7f2536 100644--- a/packages/cli/src/commands/config.ts+++ b/packages/cli/src/commands/config.ts@@ -3,9 +3,10 @@** Subcommands:* - `validate` — load merged config (defaults → user → project) and report- * conformance. Exit 0 on success, exit 1 with source-located errors on- * failure. Success message goes to stderr (stdout is reserved for- * structured CI output, of which we emit none).+ * conformance, plus a reporting-only read of the project-local layer that+ * the merge deliberately excludes. Exit 0 on success, exit 1 with+ * source-located errors on failure. Success message goes to stderr (stdout+ * is reserved for structured CI output, of which we emit none).* - `migrate` — codemod removing deprecated fields (`sync.*`,* `persistence.{debounceMs,maxDebounceMs}`, `server.port`, plus every* entry in the shared removed-key registry) idempotently. Funnels through@@ -14,8 +15,18 @@*/import { existsSync, readFileSync } from 'node:fs';-import { type ConfigPatch, humanFormat, REMOVED_KEYS } from '@inkeep/open-knowledge-core';-import { resolveConfigPath, writeConfigPatch } from '@inkeep/open-knowledge-core/server';+import {+ type ConfigDiagnostic,+ type ConfigPatch,+ humanFormat,+ REMOVED_KEYS,+ type WriteScope,+} from '@inkeep/open-knowledge-core';+import {+ readConfigSafely,+ resolveConfigPath,+ writeConfigPatch,+} from '@inkeep/open-knowledge-core/server';import { Command } from 'commander';import { parseDocument } from 'yaml';import { loadConfig } from '../config/loader.ts';@@ -45,6 +56,12 @@ export const DROPPED_FIELD_PATHS: ReadonlyArray<readonly string[]> = [interface ValidateRunOpts {cwd?: string;loadConfigFn?: typeof loadConfig;+ /**+ * Reporting-only read of the project-local layer. Its own seam beside+ * `loadConfigFn` because `loadConfig` does not merge that layer, so a test+ * stubbing the loader would otherwise fall through to the real filesystem.+ */+ readProjectLocalFn?: (cwd: string) => readonly ConfigDiagnostic[];log?: (msg: string) => void;error?: (msg: string) => void;}@@ -53,14 +70,66 @@ interface ValidateOutcome {ok: boolean;}+/**+ * Read `.ok/local/config.yml` for reporting only. `sideline: false` so+ * describing a corrupt layer never renames a user's file, and the parsed value+ * is discarded — this layer is deliberately outside `loadConfig`'s merge.+ */+function defaultReadProjectLocalDiagnostics(cwd: string): readonly ConfigDiagnostic[] {+ return readConfigSafely({+ absPath: resolveConfigPath('project-local', cwd),+ sideline: false,+ }).diagnostics;+}+export function runValidate(opts: ValidateRunOpts = {}): ValidateOutcome {const log = opts.log ?? ((msg) => console.error(msg));const error = opts.error ?? ((msg) => console.error(msg));const load = opts.loadConfigFn ?? loadConfig;try {- const { sources } = load(opts.cwd);+ const { sources, diagnostics, sidelined } = load(opts.cwd);+ // `loadConfig` merges two layers (user + committed project) and so can only+ // ever report on those two. `.ok/local/config.yml` is what+ // `readLinkPreviewsEnabled`, `readProjectLocalSemanticConfig`, and the+ // project-local `autoSync.mode` all read, so a `validate` blind to it hands+ // a user with a dead key there a ✓ and no way to find it without a running+ // server. Read it here purely for reporting: `sideline: false` so a corrupt+ // layer is described and never renamed, and the value is deliberately+ // discarded so `loadConfig`'s two-layer merge contract is untouched.+ const readProjectLocal = opts.readProjectLocalFn ?? defaultReadProjectLocalDiagnostics;+ const projectLocalDiagnostics = readProjectLocal(opts.cwd ?? process.cwd());+ const allDiagnostics = [...diagnostics, ...projectLocalDiagnostics];const renderedSources = sources.length === 0 ? 'defaults only' : sources.join(', ');- log(`✓ Configuration valid (sources: ${renderedSources})`);+ // A removed key leaves the file usable, so it does not qualify the headline.+ // Every other code does: the layer's content was not honored, and claiming+ // "valid" sends a user who skims for the checkmark away believing nothing+ // is wrong. The label stays code-agnostic because this bucket mixes causes+ // — YAML_PARSE read fine but has a syntax error, SCHEMA_INVALID parsed but+ // failed validation, only UNREADABLE could not be read at all. `humanFormat`+ // below names the actual cause per layer.+ const degraded = allDiagnostics.filter((d) => d.code !== 'REMOVED_KEY');+ if (degraded.length === 0) {+ log(`✓ Configuration valid (sources: ${renderedSources})`);+ } else {+ log(+ `! Configuration loaded, but ${degraded.length} config layer(s) had issues ` ++ `(sources: ${renderedSources})`,+ );+ }+ // Removed keys no longer block loading, but the user should still see each+ // one and its migration path. Rendered with source location + replacement+ // guidance by humanFormat.+ for (const diagnostic of allDiagnostics) {+ log('');+ log(humanFormat(diagnostic));+ }+ // Loading an unreadable file renames it aside so OK can boot on defaults.+ // Say so — a command named `validate` that quarantines a file without a+ // word about it reads as the file having vanished.+ for (const { from, to } of sidelined) {+ log('');+ log(`Moved ${from} aside to ${to} so defaults could be used. Restore it once fixed.`);+ }return { ok: true };} catch (e) {error(e instanceof Error ? e.message : String(e));@@ -68,9 +137,17 @@ export function runValidate(opts: ValidateRunOpts = {}): ValidateOutcome {}}+/**+ * Requested migration scope. The three `WriteScope` values each name one+ * config file; `all` fans out to every layer; `both` is a supported legacy+ * alias covering project + user only (project-local excluded), so existing+ * invocations keep their exact reach.+ */+type MigrateScope = WriteScope | 'both' | 'all';+interface MigrateRunOpts {cwd?: string;- scope?: 'project' | 'user' | 'both';+ scope?: MigrateScope;dryRun?: boolean;homedirOverride?: string;log?: (msg: string) => void;@@ -80,7 +157,7 @@ interface MigrateRunOpts {interface MigrateFileOutcome {path: string;- scope: 'project' | 'user';+ scope: WriteScope;/** Dotted paths that exist in the file. */found: string[];/** Dotted paths actually removed (== found unless dry-run or write failed). */@@ -148,27 +225,42 @@ function buildClearPatch(paths: ReadonlyArray<readonly string[]>): ConfigPatch {return root as unknown as ConfigPatch;}+/**+ * Expand a requested scope into the concrete config files to process, in+ * layer order. `all` covers every layer; `both` covers project + user only —+ * project-local is deliberately excluded so existing `both` invocations keep+ * their exact reach.+ */+function fileScopesForScope(scope: MigrateScope): WriteScope[] {+ switch (scope) {+ case 'project':+ return ['project'];+ case 'project-local':+ return ['project-local'];+ case 'user':+ return ['user'];+ case 'both':+ return ['project', 'user'];+ case 'all':+ return ['project', 'project-local', 'user'];+ }+}+export async function runMigrate(opts: MigrateRunOpts = {}): Promise<MigrateOutcome> {const log = opts.log ?? ((msg) => console.log(msg));const error = opts.error ?? ((msg) => console.error(msg));- const scope = opts.scope ?? 'both';+ // Matches the command's `--scope` default. Two defaults that disagree would+ // make a programmatic call reach different files than the CLI invocation the+ // removed-key redirects tell users to run.+ const scope = opts.scope ?? 'all';const dryRun = opts.dryRun ?? false;const cwd = opts.cwd ?? process.cwd();const writePatch = opts.writeConfigPatchFn ?? writeConfigPatch;- const targets: Array<{ scope: 'project' | 'user'; absPath: string }> = [];- if (scope === 'project' || scope === 'both') {- targets.push({- scope: 'project',- absPath: resolveConfigPath('project', cwd, opts.homedirOverride),- });- }- if (scope === 'user' || scope === 'both') {- targets.push({- scope: 'user',- absPath: resolveConfigPath('user', cwd, opts.homedirOverride),- });- }+ const targets = fileScopesForScope(scope).map((fileScope) => ({+ scope: fileScope,+ absPath: resolveConfigPath(fileScope, cwd, opts.homedirOverride),+ }));const outcomes: MigrateFileOutcome[] = [];let allOk = true;@@ -246,6 +338,46 @@ export async function runMigrate(opts: MigrateRunOpts = {}): Promise<MigrateOutcreturn { outcomes, ok: allOk };}+/**+ * Scopes surfaced in `--scope` help and the invalid-scope error. `both` is a+ * supported alias, intentionally omitted here so it is accepted but not+ * advertised.+ */+const ADVERTISED_MIGRATE_SCOPES = 'project | project-local | user | all';++/**+ * Every accepted `--scope` value, including the unadvertised `both` alias.+ * Keyed by `MigrateScope` so widening that union without accepting the new+ * value here is a compile error rather than a confusing "Invalid --scope"+ * rejection of a type-valid input.+ */+const ACCEPTED_MIGRATE_SCOPES: Record<MigrateScope, true> = {+ project: true,+ 'project-local': true,+ user: true,+ both: true,+ all: true,+};++/**+ * Membership view over the same source. Deliberately keyed by `string`: the+ * value being tested is untrusted CLI input, and a set narrowed to+ * `MigrateScope` could not accept it as an argument in the first place.+ */+const VALID_MIGRATE_SCOPES: ReadonlySet<string> = new Set(Object.keys(ACCEPTED_MIGRATE_SCOPES));++/**+ * Whether the CLI-wide startup notice should announce removed-key findings for+ * this invocation.+ *+ * False for the `config` command family, which owns that reporting: `validate`+ * renders the findings as its result and `migrate` is the act of removing them.+ * Announcing them first would print every finding twice.+ */+export function shouldAnnounceRemovedKeys(subcommandName: string | undefined): boolean {+ return subcommandName !== 'config';+}+export function configCommand(): Command {const cmd = new Command('config').description('Inspect and maintain OpenKnowledge configuration files',@@ -266,17 +398,22 @@ export function configCommand(): Command {.description('Remove deprecated config fields from config.yml idempotently (every removed key in the registry — content.*, folders, appearance.editorModeDefault, server.host, etc. — plus the silently-dropped sync.*, persistence.*, server.port)',)- .option('--scope <scope>', 'Which scope to migrate: project | user | both', 'both')+ // Defaults to `all` so the bare `ok config migrate` that every removed-key+ // redirect tells the user to run actually reaches the layer their dead key+ // sits in, project-local included. `both` stays accepted as the legacy+ // project+user reach. Widening the default is safe because the codemod only+ // ever deletes registry keys, is idempotent, and honors --dry-run.+ .option('--scope <scope>', `Which scope to migrate: ${ADVERTISED_MIGRATE_SCOPES}`, 'all').option('--dry-run', 'Preview without writing', false).action(async (subOpts) => {- const scope = subOpts.scope as 'project' | 'user' | 'both';- if (scope !== 'project' && scope !== 'user' && scope !== 'both') {- console.error(`Invalid --scope: ${scope}. Expected: project | user | both`);+ const rawScope = String(subOpts.scope);+ if (!VALID_MIGRATE_SCOPES.has(rawScope)) {+ console.error(`Invalid --scope: ${rawScope}. Expected: ${ADVERTISED_MIGRATE_SCOPES}`);process.exitCode = 2;return;}const outcome = await runMigrate({- scope,+ scope: rawScope as MigrateScope,dryRun: subOpts.dryRun as boolean,});if (!outcome.ok) {diff --git a/packages/cli/src/config/loader.test.ts b/packages/cli/src/config/loader.test.tsindex cf66d0835..e83a87a9f 100644--- a/packages/cli/src/config/loader.test.ts+++ b/packages/cli/src/config/loader.test.ts@@ -2,7 +2,9 @@ import { mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { resolve } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';+import { type ConfigDiagnostic, REMOVED_KEYS } from '@inkeep/open-knowledge-core';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';+import { stringify } from 'yaml';let testDir: string;// Seed a real default so the loader's transitive homedir() call at import time@@ -51,6 +53,28 @@ function writeWorkspaceConfigAt(dir: string, yaml: string) {writeFileSync(resolve(configDir, 'config.yml'), yaml, 'utf-8');}+function isPlainObject(value: unknown): value is Record<string, unknown> {+ return typeof value === 'object' && value !== null && !Array.isArray(value);+}++/** Set a (possibly nested) leaf on `root`, creating intermediate objects. */+function setPath(root: Record<string, unknown>, path: readonly string[], leaf: unknown): void {+ let cur = root;+ for (let i = 0; i < path.length - 1; i++) {+ const seg = path[i] as string;+ if (!isPlainObject(cur[seg])) cur[seg] = {};+ cur = cur[seg] as Record<string, unknown>;+ }+ cur[path[path.length - 1] as string] = leaf;+}++/** Only the REMOVED_KEY diagnostics, dotted-path indexed for lookup. */+function removedKeys(diagnostics: ConfigDiagnostic[]): Array<{ dotted: string; redirect: string }> {+ return diagnostics.flatMap((d) =>+ d.code === 'REMOVED_KEY' ? [{ dotted: d.path.join('.'), redirect: d.redirect }] : [],+ );+}+describe('loadConfig', () => {// ── Defaults ────────────────────────────────────────────────────────@@ -93,23 +117,21 @@ describe('loadConfig', () => {expect(config.content.dir).toBe('.');});- test('removed config keys in project config hard-error in one pass with redirects', () => {- // Single-tier contract: every removed key throws (no warn tier). A project- // config carrying several gets them all in one throw — no two-trip cycle.+ test('removed config keys in project config are stripped and reported; siblings survive', () => {+ // Strip-and-continue: a dead key no longer blocks startup. A project config+ // carrying several gets them all stripped in one pass — no two-trip cycle —+ // and each is reported as a REMOVED_KEY diagnostic naming its replacement.// sync.* and server.port are NOT in the registry (genuinely silent- // loose-mode pass), so they contribute no error.+ // loose-mode pass), so they contribute no diagnostic.writeWorkspaceConfig('sync:\n pushIntervalSeconds: 30\nserver:\n port: 3000\n host: example.dev\n openOnAgentEdit: true\nmcp:\n autoStart: false\n tools:\n grep:\n maxResults: 100\n search:\n maxResults: 100\nupload:\n maxBytes: 100000\ngithub:\n oauthAppClientId: abc\ncontent:\n dir: docs\n',);- let caught: Error | undefined;- try {- loadConfig(testDir);- } catch (e) {- caught = e as Error;- }- expect(caught).toBeDefined();- const msg = caught?.message ?? '';- // Every registry key present is named.+ const { config, diagnostics } = loadConfig(testDir);+ // The unrelated live key resolves to its on-disk value, not a default.+ expect(config.content.dir).toBe('docs');+ const removed = removedKeys(diagnostics);+ const dotted = removed.map((r) => r.dotted);+ // Every registry key present is reported.for (const key of ['server.host','server.openOnAgentEdit',@@ -119,17 +141,23 @@ describe('loadConfig', () => {'upload.maxBytes','github.oauthAppClientId',]) {- expect(msg).toContain(key);+ expect(dotted).toContain(key);}- // Redirect hints name the replacement knob.- expect(msg).toContain('--host');- expect(msg).toContain('HOST');- expect(msg).toContain('OPEN_KNOWLEDGE_GITHUB_CLIENT_ID');- expect(msg).toContain('OK_MCP_AUTOSTART');- expect(msg).toContain('streaming uploads have no user-facing cap');- // Source-located: file:line:col points inside the fixture.+ // Each redirect names the replacement knob.+ const joined = removed.map((r) => r.redirect).join('\n');+ expect(joined).toContain('--host');+ expect(joined).toContain('HOST');+ expect(joined).toContain('OPEN_KNOWLEDGE_GITHUB_CLIENT_ID');+ expect(joined).toContain('OK_MCP_AUTOSTART');+ expect(joined).toContain('streaming uploads have no user-facing cap');+ // Source-located: each diagnostic points inside the committed file.const expectedPath = resolve(testDir, OK_DIR, 'config.yml');- expect(msg).toMatch(new RegExp(`${expectedPath.replace(/[/\\.]/g, '\\$&')}:\\d+:\\d+`));+ for (const d of diagnostics) {+ if (d.code === 'REMOVED_KEY') {+ expect(d.source?.file).toBe(expectedPath);+ expect(d.source?.line ?? 0).toBeGreaterThan(0);+ }+ }});// ── Workspace overrides ─────────────────────────────────────────────@@ -159,116 +187,125 @@ appearance:expect(config.appearance.theme).toBe('dark');});- test('content.include in project config rejects with REMOVED_KEY error directing to .okignore', () => {+ test('content.include in project config is stripped with .okignore redirect; content.dir survives', () => {writeWorkspaceConfig(`content:+ dir: docsinclude:- "**/*.md"`);- let caught: Error | undefined;- try {- loadConfig(testDir);- } catch (e) {- caught = e as Error;- }- expect(caught).toBeDefined();- const expectedPath = resolve(testDir, OK_DIR, 'config.yml');- // Source-located header: file:line:col points inside the fixture.- expect(caught?.message).toMatch(- new RegExp(`${expectedPath.replace(/[/\\.]/g, '\\$&')}:\\d+:\\d+`),- );- expect(caught?.message).toContain('content.include');+ const { config, diagnostics } = loadConfig(testDir);+ // Sibling under the same parent keeps its on-disk value.+ expect(config.content.dir).toBe('docs');+ const include = removedKeys(diagnostics).find((r) => r.dotted === 'content.include');+ expect(include).toBeDefined();// include-specific redirect: surfaces content.dir as the simpler// subdirectory-scoping alternative AND warns that .okignore is// exclude-only (don't copy include patterns directly).- expect(caught?.message).toContain('content.dir');- expect(caught?.message).toContain('.okignore');- expect(caught?.message).toContain('exclude-only');+ expect(include?.redirect).toContain('content.dir');+ expect(include?.redirect).toContain('.okignore');+ expect(include?.redirect).toContain('exclude-only');});- test('content.exclude in project config rejects with REMOVED_KEY error', () => {+ test('content.exclude in project config is stripped with a 1:1 .okignore redirect', () => {writeWorkspaceConfig(`content:+ dir: docsexclude:- "**/drafts/**"`);- let caught: Error | undefined;- try {- loadConfig(testDir);- } catch (e) {- caught = e as Error;- }- expect(caught).toBeDefined();- const expectedPath = resolve(testDir, OK_DIR, 'config.yml');- expect(caught?.message).toMatch(- new RegExp(`${expectedPath.replace(/[/\\.]/g, '\\$&')}:\\d+:\\d+`),- );- expect(caught?.message).toContain('content.exclude');+ const { config, diagnostics } = loadConfig(testDir);+ expect(config.content.dir).toBe('docs');+ const exclude = removedKeys(diagnostics).find((r) => r.dotted === 'content.exclude');+ expect(exclude).toBeDefined();// exclude-specific redirect: 1:1 migration to .okignore.- expect(caught?.message).toContain('.okignore');- expect(caught?.message).toContain('1:1 migration');+ expect(exclude?.redirect).toContain('.okignore');+ expect(exclude?.redirect).toContain('1:1 migration');});- test('content.include AND content.exclude together emit BOTH REMOVED_KEY errors in one pass', () => {+ test('content.include AND content.exclude together are both stripped in one pass', () => {writeWorkspaceConfig(`content:include:- "**/*.md"exclude:- "**/drafts/**"`);- let caught: Error | undefined;- try {- loadConfig(testDir);- } catch (e) {- caught = e as Error;- }- expect(caught).toBeDefined();- // Both keys should appear in the error message — no two-trip fix cycle- // where the user fixes include, restarts, then sees exclude as a fresh- // error.- expect(caught?.message).toContain('content.include');- expect(caught?.message).toContain('content.exclude');+ const { diagnostics } = loadConfig(testDir);+ const dotted = removedKeys(diagnostics).map((r) => r.dotted);+ // Both keys are reported in one read — no two-trip fix cycle where the user+ // fixes include, restarts, then sees exclude as a fresh finding.+ expect(dotted).toContain('content.include');+ expect(dotted).toContain('content.exclude');// Each key carries its own redirect (include → content.dir + exclude-only;// exclude → 1:1 migration).- expect(caught?.message).toContain('content.dir');- expect(caught?.message).toContain('1:1 migration');+ const joined = removedKeys(diagnostics)+ .map((r) => r.redirect)+ .join('\n');+ expect(joined).toContain('content.dir');+ expect(joined).toContain('1:1 migration');});- test('folders in project config rejects with REMOVED_KEY directing to nested .ok/', () => {+ test('folders in project config is stripped with a nested .ok/ redirect', () => {// The headline dead key: previously silent (no warn, no error) while the- // docs still taught it. Now a source-located hard error.- writeWorkspaceConfig(`folders:+ // docs still taught it. Now stripped and reported, not a hard failure.+ writeWorkspaceConfig(`content:+ dir: docs+folders:- path: "drafts/**"frontmatter:status: draft`);- let caught: Error | undefined;- try {- loadConfig(testDir);- } catch (e) {- caught = e as Error;- }- expect(caught).toBeDefined();- const msg = caught?.message ?? '';- expect(msg).toContain('folders');- expect(msg).toContain('.ok/');- expect(msg).toContain('edit({ folder');- const expectedPath = resolve(testDir, OK_DIR, 'config.yml');- expect(msg).toMatch(new RegExp(`${expectedPath.replace(/[/\\.]/g, '\\$&')}:\\d+:\\d+`));+ const { config, diagnostics } = loadConfig(testDir);+ // An unrelated top-level section is untouched by stripping folders.+ expect(config.content.dir).toBe('docs');+ const folders = removedKeys(diagnostics).find((r) => r.dotted === 'folders');+ expect(folders).toBeDefined();+ expect(folders?.redirect).toContain('.ok/');+ expect(folders?.redirect).toContain('edit({ folder');});- test('appearance.editorModeDefault in project config rejects with REMOVED_KEY', () => {+ test('appearance.editorModeDefault in project config is stripped; appearance.theme survives', () => {// Also previously silent — never read by the engine.- writeWorkspaceConfig('appearance:\n editorModeDefault: source\n');- let caught: Error | undefined;- try {- loadConfig(testDir);- } catch (e) {- caught = e as Error;- }- expect(caught).toBeDefined();- expect(caught?.message).toContain('appearance.editorModeDefault');- expect(caught?.message).toContain('WYSIWYG');+ writeWorkspaceConfig('appearance:\n theme: dark\n editorModeDefault: source\n');+ const { config, diagnostics } = loadConfig(testDir);+ // Sibling under the same parent keeps its on-disk value.+ expect(config.appearance.theme).toBe('dark');+ const mode = removedKeys(diagnostics).find((r) => r.dotted === 'appearance.editorModeDefault');+ expect(mode).toBeDefined();+ expect(mode?.redirect).toContain('WYSIWYG');});+ test('a clean committed config yields no diagnostics', () => {+ writeWorkspaceConfig('content:\n dir: docs\n');+ const { config, diagnostics } = loadConfig(testDir);+ expect(config.content.dir).toBe('docs');+ expect(diagnostics).toEqual([]);+ });++ // Parameterized over every registry entry: a committed config carrying that+ // key plus a live sibling loads successfully, strips the key, preserves the+ // sibling, and reports exactly one diagnostic. This is the invariant that+ // keeps a dead key from bricking `ok start`, and it stays correct as the+ // registry grows.+ for (const entry of REMOVED_KEYS) {+ const dotted = entry.path.join('.');+ test(`committed config with ${dotted} loads; sibling preserved; one diagnostic`, () => {+ const obj: Record<string, unknown> = { content: { dir: 'docs' } };+ setPath(obj, entry.path, 'sentinel');+ writeWorkspaceConfig(stringify(obj));++ const { config, diagnostics } = loadConfig(testDir);++ // Sibling resolves to its on-disk value, not a schema default.+ expect(config.content.dir).toBe('docs');+ const removed = diagnostics.filter((d) => d.code === 'REMOVED_KEY');+ expect(removed).toHaveLength(1);+ const [diag] = removed;+ if (diag?.code === 'REMOVED_KEY') {+ expect(diag.path).toEqual(entry.path);+ expect(diag.redirect).toBe(entry.redirect);+ }+ });+ }+// ── Validation ──────────────────────────────────────────────────────test('appearance.theme outside the enum throws', () => {@@ -357,6 +394,44 @@ appearance:expect(config.appearance.theme).toBe('dark');expect(sources).toContain(resolve(okDir, 'global.yml'));});++ // The committed layer is parameterized over the whole registry above; this+ // pins the same strip-and-continue contract through the OTHER layer, which+ // reaches `diagnostics` by a different route (`readConfigSafely` upstream,+ // then a deep merge). Deleting the user-layer diagnostics push, or a merge+ // that dropped user siblings once a key was stripped, would only fail here.+ test('user-global strip-and-continue: sibling survives the merge, key is reported', () => {+ const okDir = resolve(fakeHome, OK_DIR);+ mkdirSync(okDir, { recursive: true });+ writeFileSync(+ resolve(okDir, 'global.yml'),+ 'server:\n host: 0.0.0.0\nappearance:\n theme: dark\n',+ 'utf-8',+ );++ const { config, diagnostics } = loadConfig(testDir);++ expect(config.appearance.theme).toBe('dark');+ const removed = diagnostics.filter((d) => d.code === 'REMOVED_KEY');+ expect(removed).toHaveLength(1);+ const [diag] = removed;+ if (diag?.code === 'REMOVED_KEY') {+ expect(diag.path).toEqual(['server', 'host']);+ }+ });++ // The gap that let `ok config validate` answer "✓ valid" for a file it could+ // not parse: the merged config falls back to defaults, which always validate,+ // so the only evidence a layer was skipped is the diagnostic.+ test('an unparseable committed config degrades to defaults AND reports YAML_PARSE', () => {+ writeWorkspaceConfig('content:\n dir: [invalid yaml');++ const { config, diagnostics } = loadConfig(testDir);++ expect(config.content.dir).toBe('.');+ const parseFailures = diagnostics.filter((d) => d.code === 'YAML_PARSE');+ expect(parseFailures).toHaveLength(1);+ });});describe('createProjectConfigResolver', () => {diff --git a/packages/cli/src/config/loader.ts b/packages/cli/src/config/loader.tsindex f367f2dd2..84883354b 100644--- a/packages/cli/src/config/loader.ts+++ b/packages/cli/src/config/loader.ts@@ -16,20 +16,25 @@* `.ok/config.yml` so the ancestor-walk that detects an OK project can't* treat the user's home directory as a project root.*- * The user-global file is read via `readConfigSafely` — invalid files are- * sidelined to `<path>.invalid-<ISO-timestamp>` and replaced with schema- * defaults so OK can still boot. The project file errors loud (throws) —- * project errors are user-fixable in-place and failing fast helps the user- * notice.+ * Both layers strip removed keys and continue: a key the engine no longer+ * reads is deleted from the parsed value and reported on+ * `LoadConfigResult.diagnostics`, never blocking startup. Genuine corruption+ * still fails the way it did before: the user-global file is sidelined to+ * `<path>.invalid-<ISO-timestamp>` and replaced with schema defaults (via+ * `readConfigSafely`) so OK can still boot, and a schema-invalid project file+ * throws loud — a project error is user-fixable in place and failing fast+ * helps the user notice.*/import { existsSync, readFileSync } from 'node:fs';import { resolve } from 'node:path';import {+ type ConfigDiagnostic,type ConfigIssue,type ConfigValidationError,detectRemovedKeys,humanFormat,locateIssue,+ stripRemovedKeys,} from '@inkeep/open-knowledge-core';import { readConfigSafely, resolveConfigPath } from '@inkeep/open-knowledge-core/server';import { type Config, ConfigSchema } from '@inkeep/open-knowledge-server';@@ -41,6 +46,19 @@ import { normalizeCwd } from '../utils/normalize-cwd.ts';export interface LoadConfigResult {config: Config;sources: string[];+ /**+ * Structured diagnostics for the config that was loaded, across both layers.+ * Removed keys are stripped and reported here rather than blocking the load;+ * a sidelined user-global file surfaces its degradation diagnostic too. Empty+ * for a clean config.+ */+ diagnostics: ConfigDiagnostic[];+ /**+ * Files this load renamed out of the way to boot on defaults. Surfaced so a+ * caller can tell the user their file moved — a load that quarantines a file+ * without saying so reads as a silent data loss.+ */+ sidelined: Array<{ from: string; to: string }>;}/** Short TTL for per-cwd config resolution in long-lived MCP sessions. */@@ -76,6 +94,13 @@ interface LoadedYamlFile {source: string | null;/** yaml@2 Document AST — needed for `getIn(path)` → byte range translation. */doc: Document | null;+ /**+ * Why the file yielded no value, when the cause was corruption rather than+ * absence. Returned rather than only logged so `LoadConfigResult.diagnostics`+ * can carry it: degrading to defaults silently is what let `ok config+ * validate` answer "✓ valid" for a file it could not parse.+ */+ diagnostic?: ConfigDiagnostic;}/**@@ -83,9 +108,10 @@ interface LoadedYamlFile {* the parsed JS value plus the Document AST + raw source so callers can* locate Zod issues back to file:line:col.*- * On YAML syntax errors, logs a warning and returns `value: null` (existing- * graceful-degradation semantic — broken project YAML doesn't block boot;- * the user fixes the file and reloads).+ * On a read or YAML syntax error, logs a warning and returns `value: null`+ * (existing graceful-degradation semantic — broken project YAML doesn't block+ * boot; the user fixes the file and reloads) plus a `diagnostic` describing+ * the cause so the failure is reportable, not just survivable.*/function loadYamlFile(filePath: string): LoadedYamlFile {if (!existsSync(filePath)) {@@ -95,17 +121,30 @@ function loadYamlFile(filePath: string): LoadedYamlFile {try {raw = readFileSync(filePath, 'utf-8');} catch (err) {- console.warn(- `[config] Failed to read ${filePath}: ${err instanceof Error ? err.message : err}`,- );- return { value: null, path: filePath, source: null, doc: null };+ const detail = err instanceof Error ? err.message : String(err);+ console.warn(`[config] Failed to read ${filePath}: ${detail}`);+ return {+ value: null,+ path: filePath,+ source: null,+ doc: null,+ diagnostic: { code: 'UNREADABLE', detail: `${filePath}: ${detail}` },+ };}const doc = parseDocument(raw);if (doc.errors.length > 0) {- console.warn(- `[config] Failed to parse ${filePath}: ${doc.errors.map((e) => e.message).join('; ')}`,- );- return { value: null, path: filePath, source: raw, doc: null };+ const detail = doc.errors.map((e) => e.message).join('; ');+ console.warn(`[config] Failed to parse ${filePath}: ${detail}`);+ return {+ value: null,+ path: filePath,+ source: raw,+ doc: null,+ // The diagnostic variants are value-free by construction, so the file has+ // to be named in `detail` — otherwise a merged report cannot say which+ // layer failed to parse.+ diagnostic: { code: 'YAML_PARSE', detail: `${filePath}: ${detail}` },+ };}const parsed = doc.toJSON();if (isObject(parsed)) {@@ -153,11 +192,18 @@ function annotateIssuesWithSource(export function loadConfig(cwd?: string): LoadConfigResult {const workingDir = cwd ?? process.cwd();const sources: string[] = [];+ const diagnostics: ConfigDiagnostic[] = [];+ const sidelined: Array<{ from: string; to: string }> = [];- // Layer 1: user-global config — go through readConfigSafely so a broken- // file is sidelined and we boot on defaults instead of hanging the user.+ // Layer 1: user-global config — go through readConfigSafely so removed keys+ // are stripped-and-reported and a genuinely broken file is sidelined; either+ // way we boot instead of hanging the user.const userConfigPath = resolveConfigPath('user', workingDir);const userResult = readConfigSafely({ absPath: userConfigPath });+ diagnostics.push(...userResult.diagnostics);+ if (!userResult.valid && userResult.sidelinedTo !== undefined) {+ sidelined.push({ from: userConfigPath, to: userResult.sidelinedTo });+ }let merged: Record<string, unknown> = {};if (userResult.valid && userResult.source !== undefined) {// Re-emit through the JSON projection so deepMerge stays uniform.@@ -168,26 +214,34 @@ export function loadConfig(cwd?: string): LoadConfigResult {// contributed nothing" and proceed with defaults at this layer.}- // Layer 2: project config — fail loud on schema-fail so the user notices.+ // Layer 2: project config. Strip removed keys and continue — a dead key must+ // not brick startup — but a schema violation still throws loud, because a+ // project schema error is user-fixable in place.const projectConfigPath = resolve(workingDir, OK_DIR, CONFIG_FILENAME);const projectFile = loadYamlFile(projectConfigPath);+ // A project file that could not be read or parsed degrades to defaults, same+ // as before — but it now says so. Without this the whole merged config falls+ // back to defaults, which always validate, so every reporting surface built+ // on `diagnostics` would call a broken file clean.+ if (projectFile.diagnostic !== undefined) {+ diagnostics.push(projectFile.diagnostic);+ }if (projectFile.value !== null) {- // Removed keys are a single-tier hard error in the project config (the- // user-fixable, fail-fast path). All keys in one pass — no two-trip cycle.- const removedKeyErrors = detectRemovedKeys({+ const removedKeyDiagnostics = detectRemovedKeys({value: projectFile.value,file: projectFile.path,source: projectFile.source,doc: projectFile.doc,});- if (removedKeyErrors.length > 0) {- throw new Error(removedKeyErrors.map(humanFormat).join('\n\n'));- }- merged = deepMerge(merged, projectFile.value);+ diagnostics.push(...removedKeyDiagnostics);+ const cleaned =+ removedKeyDiagnostics.length > 0 ? stripRemovedKeys(projectFile.value) : projectFile.value;+ merged = deepMerge(merged, cleaned);sources.push(projectConfigPath);}- // Validate the merged result with Zod.+ // Validate the merged result with Zod. Removed keys were already stripped, so+ // a failure here is a genuine schema violation — throw source-located.const result = ConfigSchema.safeParse(merged);if (!result.success) {const issues = annotateIssuesWithSource(result.error.issues, projectFile);@@ -195,7 +249,7 @@ export function loadConfig(cwd?: string): LoadConfigResult {throw new Error(humanFormat(error));}- return { config: result.data, sources };+ return { config: result.data, sources, diagnostics, sidelined };}interface CreateProjectConfigResolverOptions {diff --git a/packages/core/src/config/collect-config-diagnostics.test.ts b/packages/core/src/config/collect-config-diagnostics.test.tsnew file mode 100644index 000000000..a2623d822--- /dev/null+++ b/packages/core/src/config/collect-config-diagnostics.test.ts@@ -0,0 +1,210 @@+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { dirname, resolve } from 'node:path';+import { afterEach, beforeEach, describe, expect, test } from 'vitest';+import { stringify } from 'yaml';+import { collectConfigDiagnostics } from './collect-config-diagnostics.ts';+import type { WriteScope } from './errors.ts';+import { REMOVED_KEYS } from './removed-keys.ts';+import { resolveConfigPath } from './write-config-patch.ts';++/** True when `value` is a non-null, non-array object. */+function isPlainObject(value: unknown): value is Record<string, unknown> {+ return typeof value === 'object' && value !== null && !Array.isArray(value);+}++/** Set a (possibly nested) leaf on `root`, creating intermediate objects. */+function setPath(root: Record<string, unknown>, path: readonly string[], leaf: unknown): void {+ let cur = root;+ for (let i = 0; i < path.length - 1; i++) {+ const seg = path[i] as string;+ if (!isPlainObject(cur[seg])) cur[seg] = {};+ cur = cur[seg] as Record<string, unknown>;+ }+ cur[path[path.length - 1] as string] = leaf;+}++let projectDir: string;+let homeDir: string;+/** Diagnostics are returned, not logged — keep test output clean. */+const quiet = () => {};++beforeEach(() => {+ const stamp = `${Date.now()}-${Math.random().toString(36).slice(2)}`;+ projectDir = resolve(tmpdir(), `ok-diag-project-${stamp}`);+ homeDir = resolve(tmpdir(), `ok-diag-home-${stamp}`);+ mkdirSync(projectDir, { recursive: true });+ mkdirSync(homeDir, { recursive: true });+});++afterEach(() => {+ rmSync(projectDir, { recursive: true, force: true });+ rmSync(homeDir, { recursive: true, force: true });+});++/** Write `value` as YAML at the config path for `scope`; returns that path. */+function writeScopeConfig(scope: WriteScope, value: Record<string, unknown>): string {+ const file = resolveConfigPath(scope, projectDir, homeDir);+ mkdirSync(dirname(file), { recursive: true });+ writeFileSync(file, stringify(value), 'utf-8');+ return file;+}++/** Write raw (possibly malformed) bytes at the config path for `scope`. */+function writeScopeRaw(scope: WriteScope, raw: string): string {+ const file = resolveConfigPath(scope, projectDir, homeDir);+ mkdirSync(dirname(file), { recursive: true });+ writeFileSync(file, raw, 'utf-8');+ return file;+}++function collect() {+ return collectConfigDiagnostics({ cwd: projectDir, homedirOverride: homeDir, warn: quiet });+}++describe('collectConfigDiagnostics', () => {+ test('no config files → empty report', () => {+ expect(collect()).toEqual({ diagnostics: [] });+ });++ test('a single removed key in project-local surfaces one scoped finding', () => {+ const entry = REMOVED_KEYS.find((k) => k.path.join('.') === 'appearance.sidebar.showAllFiles');+ if (!entry) throw new Error('fixture key missing from registry');+ const config: Record<string, unknown> = {};+ setPath(config, entry.path, false);+ const file = writeScopeConfig('project-local', config);++ const { diagnostics } = collect();++ expect(diagnostics).toHaveLength(1);+ expect(diagnostics[0]).toEqual({+ code: 'REMOVED_KEY',+ scope: 'project-local',+ file,+ path: entry.path,+ redirect: entry.redirect,+ });+ });++ test('reports each layer with its own scope, file, and key path', () => {+ // Three different registry keys, one per layer.+ const userKey = ['server', 'host'];+ const projectKey = ['upload', 'maxBytes'];+ const localKey = ['appearance', 'sidebar', 'showAllFiles'];++ const userCfg: Record<string, unknown> = {};+ setPath(userCfg, userKey, 'example.internal');+ const userFile = writeScopeConfig('user', userCfg);++ const projectCfg: Record<string, unknown> = {};+ setPath(projectCfg, projectKey, 1024);+ const projectFile = writeScopeConfig('project', projectCfg);++ const localCfg: Record<string, unknown> = {};+ setPath(localCfg, localKey, false);+ const localFile = writeScopeConfig('project-local', localCfg);++ const { diagnostics } = collect();++ const byScope = new Map(diagnostics.map((d) => [d.scope, d]));+ expect(byScope.get('user')).toMatchObject({ scope: 'user', file: userFile, path: userKey });+ expect(byScope.get('project')).toMatchObject({+ scope: 'project',+ file: projectFile,+ path: projectKey,+ });+ expect(byScope.get('project-local')).toMatchObject({+ scope: 'project-local',+ file: localFile,+ path: localKey,+ });+ // Every requested layer is represented exactly once.+ expect(diagnostics).toHaveLength(3);+ });++ test('every registry key is reported with its scope + registry redirect, and no on-disk value leaks', () => {+ for (const entry of REMOVED_KEYS) {+ const config: Record<string, unknown> = {+ // A schema-valid sibling whose distinctive value must never appear in+ // the report — proves the finding carries key identity, not values.+ content: { dir: 'SENTINEL_SIBLING_DIR' },+ };+ setPath(config, entry.path, 'SENTINEL_REMOVED_LEAF');+ writeScopeConfig('project-local', config);++ const { diagnostics } = collect();++ const finding = diagnostics.find(+ (d) => d.code === 'REMOVED_KEY' && d.path.join('.') === entry.path.join('.'),+ );+ expect(finding, `finding for ${entry.path.join('.')}`).toBeDefined();+ expect(finding).toMatchObject({ scope: 'project-local', redirect: entry.redirect });++ const serialized = JSON.stringify(diagnostics);+ expect(serialized).not.toContain('SENTINEL_SIBLING_DIR');+ expect(serialized).not.toContain('SENTINEL_REMOVED_LEAF');++ // Reset for the next entry so findings don't accumulate across the loop.+ rmSync(resolveConfigPath('project-local', projectDir, homeDir), { force: true });+ }+ });++ test('the response body carries no raw config value from any layer', () => {+ const userCfg: Record<string, unknown> = { content: { dir: 'USER_ONLY_VALUE' } };+ setPath(userCfg, ['server', 'host'], 'USER_HOST_VALUE');+ writeScopeConfig('user', userCfg);++ const projectCfg: Record<string, unknown> = { content: { dir: 'PROJECT_ONLY_VALUE' } };+ setPath(projectCfg, ['folders'], ['PROJECT_FOLDER_VALUE']);+ writeScopeConfig('project', projectCfg);++ const localCfg: Record<string, unknown> = { content: { dir: 'LOCAL_ONLY_VALUE' } };+ setPath(localCfg, ['appearance', 'sidebar', 'showAllFiles'], false);+ writeScopeConfig('project-local', localCfg);++ const serialized = JSON.stringify(collect());+ for (const secret of [+ 'USER_ONLY_VALUE',+ 'USER_HOST_VALUE',+ 'PROJECT_ONLY_VALUE',+ 'PROJECT_FOLDER_VALUE',+ 'LOCAL_ONLY_VALUE',+ ]) {+ expect(serialized).not.toContain(secret);+ }+ });++ test('a schema-invalid layer surfaces a value-free SCHEMA_INVALID finding', () => {+ const file = writeScopeRaw('project-local', 'appearance:\n theme: midnight\n');++ const { diagnostics } = collect();++ expect(diagnostics).toEqual([{ code: 'SCHEMA_INVALID', scope: 'project-local', file }]);+ // The offending value never crosses the boundary.+ expect(JSON.stringify(diagnostics)).not.toContain('midnight');+ // Read is non-destructive — the file is reported, never sidelined/renamed.+ expect(existsSync(file)).toBe(true);+ });++ test('an unparseable layer surfaces a value-free YAML_PARSE finding without renaming the file', () => {+ const file = writeScopeRaw('project', 'content:\n dir: [invalid yaml');++ const { diagnostics } = collect();++ expect(diagnostics).toEqual([{ code: 'YAML_PARSE', scope: 'project', file }]);+ expect(existsSync(file)).toBe(true);+ });++ // A directory where the file belongs: the path exists, so the missing-file+ // arm is skipped and the read itself throws. This is the only variant whose+ // wire projection was reachable only through `readConfigSafely` in isolation+ // — the collector's own arm for it was untested.+ test('a layer that cannot be read at all surfaces a value-free UNREADABLE finding', () => {+ const file = resolveConfigPath('project-local', projectDir, homeDir);+ mkdirSync(file, { recursive: true });++ const { diagnostics } = collect();++ expect(diagnostics).toEqual([{ code: 'UNREADABLE', scope: 'project-local', file }]);+ });+});diff --git a/packages/core/src/config/collect-config-diagnostics.ts b/packages/core/src/config/collect-config-diagnostics.tsnew file mode 100644index 000000000..925fa54c0--- /dev/null+++ b/packages/core/src/config/collect-config-diagnostics.ts@@ -0,0 +1,94 @@+/**+ * Collect active config diagnostics across every scope for the+ * config-diagnostics endpoint.+ *+ * Reads each layer's file fresh through `readConfigSafely` (no boot snapshot),+ * so an on-disk edit is reflected on the next call without a restart, and tags+ * each diagnostic with the scope and absolute file it came from. Reading is+ * non-destructive (`sideline: false`): a corrupt layer is reported, never+ * renamed, so querying diagnostics can't mutate a user's files.+ *+ * NOT browser-safe — routes through `readConfigSafely` (`node:fs`). Use only in+ * server / CLI contexts. Mirrors `inspect-config-paths.ts`.+ */++import type {+ ConfigDiagnostic,+ ConfigDiagnosticsReport,+ ScopedConfigDiagnostic,+ WriteScope,+} from './errors.ts';+import { readConfigSafely } from './read-config-safely.ts';+import { resolveConfigPath } from './write-config-patch.ts';++export interface CollectConfigDiagnosticsOptions {+ /** Project root — resolves the `project` and `project-local` layer files. */+ cwd: string;+ /** Home override for the `user` layer. Defaults to `os.homedir()`. */+ homedirOverride?: string;+ /**+ * Warn sink forwarded to `readConfigSafely`. Diagnostics are returned, so a+ * caller that only wants the structured result can pass a quiet sink to keep+ * a polled endpoint from re-logging on every request.+ */+ warn?: (message: string) => void;+}++/** The config layers the endpoint reports on, in resolution order. */+const DIAGNOSTIC_SCOPES = [+ 'user',+ 'project',+ 'project-local',+] as const satisfies readonly WriteScope[];++/**+ * Read every config layer and return each layer's diagnostics tagged with its+ * scope and file. A read that only strips a removed key stays valid and still+ * contributes its `REMOVED_KEY` diagnostic; a corrupt layer contributes a+ * value-free `YAML_PARSE` / `SCHEMA_INVALID` finding.+ */+export function collectConfigDiagnostics(+ opts: CollectConfigDiagnosticsOptions,+): ConfigDiagnosticsReport {+ const diagnostics: ScopedConfigDiagnostic[] = [];+ for (const scope of DIAGNOSTIC_SCOPES) {+ const file = resolveConfigPath(scope, opts.cwd, opts.homedirOverride);+ const result = readConfigSafely({+ absPath: file,+ sideline: false,+ ...(opts.warn ? { warn: opts.warn } : {}),+ });+ for (const diagnostic of result.diagnostics) {+ diagnostics.push(toScoped(diagnostic, scope, file));+ }+ }+ return { diagnostics };+}++/**+ * Project a core `ConfigDiagnostic` onto the wire finding, dropping the+ * source-frame snippet the corruption variants carry so no raw config bytes+ * cross the boundary.+ */+function toScoped(+ diagnostic: ConfigDiagnostic,+ scope: WriteScope,+ file: string,+): ScopedConfigDiagnostic {+ switch (diagnostic.code) {+ case 'REMOVED_KEY':+ return {+ code: 'REMOVED_KEY',+ scope,+ file,+ path: diagnostic.path,+ redirect: diagnostic.redirect,+ };+ case 'YAML_PARSE':+ return { code: 'YAML_PARSE', scope, file };+ case 'SCHEMA_INVALID':+ return { code: 'SCHEMA_INVALID', scope, file };+ case 'UNREADABLE':+ return { code: 'UNREADABLE', scope, file };+ }+}diff --git a/packages/core/src/config/errors.ts b/packages/core/src/config/errors.tsindex aedc1be01..b9cadd185 100644--- a/packages/core/src/config/errors.ts+++ b/packages/core/src/config/errors.ts@@ -54,15 +54,40 @@ export type FieldScope = z.infer<typeof FieldScopeSchema>;export const WriteScopeSchema = z.enum(['user', 'project', 'project-local']);export type WriteScope = z.infer<typeof WriteScopeSchema>;+/**+ * Read-path diagnostic variants, reused as members of both the full+ * validation-error union and the narrower `ConfigDiagnosticSchema` so each+ * shape is defined once.+ */+const YamlParseErrorSchema = z.object({+ code: z.literal('YAML_PARSE'),+ detail: z.string(),+});+/**+ * The file exists but could not be read at all — permissions, a directory+ * where a file was expected, a symlink loop, a delete racing the read. Its own+ * code rather than the catch-all `UNKNOWN` so the reporting surfaces can tell+ * "this layer could not be read" apart from "this layer read cleanly".+ */+const UnreadableErrorSchema = z.object({+ code: z.literal('UNREADABLE'),+ detail: z.string(),+});+const SchemaInvalidErrorSchema = z.object({+ code: z.literal('SCHEMA_INVALID'),+ issues: z.array(ConfigIssueSchema),+});+const RemovedKeyErrorSchema = z.object({+ code: z.literal('REMOVED_KEY'),+ path: z.array(z.string()),+ redirect: z.string(),+ source: ConfigIssueSourceSchema.optional(),+});+export const KnownConfigValidationErrorSchema = z.discriminatedUnion('code', [- z.object({- code: z.literal('YAML_PARSE'),- detail: z.string(),- }),- z.object({- code: z.literal('SCHEMA_INVALID'),- issues: z.array(ConfigIssueSchema),- }),+ YamlParseErrorSchema,+ SchemaInvalidErrorSchema,+ UnreadableErrorSchema,z.object({code: z.literal('SCOPE_VIOLATION'),path: z.array(z.string()),@@ -82,12 +107,7 @@ export const KnownConfigValidationErrorSchema = z.discriminatedUnion('code', [}),),}),- z.object({- code: z.literal('REMOVED_KEY'),- path: z.array(z.string()),- redirect: z.string(),- source: ConfigIssueSourceSchema.optional(),- }),+ RemovedKeyErrorSchema,z.object({code: z.literal('WRITE_ERROR'),detail: z.string(),@@ -111,6 +131,81 @@ export const KnownConfigValidationErrorSchema = z.discriminatedUnion('code', [export type KnownConfigValidationError = z.infer<typeof KnownConfigValidationErrorSchema>;+/**+ * The subset of validation-error variants a config *read* can surface: a+ * stripped removed key, or a whole-file YAML-parse / schema-invalid+ * degradation. The write-path variants (SCOPE_VIOLATION, WRITE_ERROR, …) never+ * arise from a read and are excluded. This is the return-value contract shared+ * by `readConfigSafely` and the config-diagnostics endpoint.+ */+export const ConfigDiagnosticSchema = z.discriminatedUnion('code', [+ RemovedKeyErrorSchema,+ YamlParseErrorSchema,+ SchemaInvalidErrorSchema,+ UnreadableErrorSchema,+]);++export type ConfigDiagnostic = z.infer<typeof ConfigDiagnosticSchema>;++/** The removed-key diagnostic — every entry `detectRemovedKeys` produces. */+export type RemovedKeyDiagnostic = Extract<ConfigDiagnostic, { code: 'REMOVED_KEY' }>;++/**+ * A config diagnostic tagged with the scope and absolute file it was read from+ * — the per-finding shape the config-diagnostics endpoint returns across the+ * user, committed-project, and project-local layers.+ *+ * A removed-key finding carries the dead key's `path` and the registry's+ * `redirect` guidance. The corruption variants carry only their layer identity:+ * a YAML-parse or schema-invalid detail echoes the file's raw bytes, and this+ * response never exposes config values — the readable detail for a corrupt+ * layer stays in the server log and `ok config validate`.+ *+ * `file` is deliberately the absolute path, and it is the one host-derived+ * string in this response: the user-scope path runs through the home directory,+ * so it carries the OS username. That is accepted rather than incidental —+ * naming the exact file is the whole fix affordance, and a relative path cannot+ * disambiguate three layers. It is worth knowing that under `remotePublicHost`+ * the origin gate admits the tunnel origin, so this path is readable by whoever+ * that tunnel is shared with. No config value ever joins it.+ */+export const ScopedConfigDiagnosticSchema = z.discriminatedUnion('code', [+ z.object({+ code: z.literal('REMOVED_KEY'),+ scope: WriteScopeSchema,+ file: z.string(),+ path: z.array(z.string()),+ redirect: z.string(),+ }),+ z.object({+ code: z.literal('YAML_PARSE'),+ scope: WriteScopeSchema,+ file: z.string(),+ }),+ z.object({+ code: z.literal('SCHEMA_INVALID'),+ scope: WriteScopeSchema,+ file: z.string(),+ }),+ z.object({+ code: z.literal('UNREADABLE'),+ scope: WriteScopeSchema,+ file: z.string(),+ }),+]);++export type ScopedConfigDiagnostic = z.infer<typeof ScopedConfigDiagnosticSchema>;++/**+ * Response body for `GET /api/config/diagnostics`. An object envelope (not a+ * bare array) keeps future top-level fields additive.+ */+export const ConfigDiagnosticsReportSchema = z.object({+ diagnostics: z.array(ScopedConfigDiagnosticSchema),+});++export type ConfigDiagnosticsReport = z.infer<typeof ConfigDiagnosticsReportSchema>;+// Derived from the discriminated-union options so a new variant in// `KnownConfigValidationErrorSchema` flows through to `isKnownConfigError`// + `humanFormat` automatically — no risk of code/set drift.@@ -197,6 +292,8 @@ export function humanFormat(error: ConfigValidationError): string {switch (error.code) {case 'YAML_PARSE':return `Failed to parse YAML: ${error.detail}`;+ case 'UNREADABLE':+ return `Could not read the file: ${error.detail}`;case 'SCHEMA_INVALID': {if (error.issues.length === 0) return 'Invalid configuration.';// Group issues by file so a single header line precedes each file'sdiff --git a/packages/core/src/config/read-config-safely.test.ts b/packages/core/src/config/read-config-safely.test.tsindex a1bcfd2dc..be01cce01 100644--- a/packages/core/src/config/read-config-safely.test.ts+++ b/packages/core/src/config/read-config-safely.test.ts@@ -2,8 +2,36 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSyncimport { tmpdir } from 'node:os';import { resolve } from 'node:path';import { afterEach, beforeEach, describe, expect, test } from 'vitest';+import { stringify } from 'yaml';import { isKnownConfigError } from './errors.ts';import { readConfigSafely } from './read-config-safely.ts';+import { REMOVED_KEYS } from './removed-keys.ts';++/** True when `value` is a non-null, non-array object. */+function isPlainObject(value: unknown): value is Record<string, unknown> {+ return typeof value === 'object' && value !== null && !Array.isArray(value);+}++/** Set a (possibly nested) leaf on `root`, creating intermediate objects. */+function setPath(root: Record<string, unknown>, path: readonly string[], leaf: unknown): void {+ let cur = root;+ for (let i = 0; i < path.length - 1; i++) {+ const seg = path[i] as string;+ if (!isPlainObject(cur[seg])) cur[seg] = {};+ cur = cur[seg] as Record<string, unknown>;+ }+ cur[path[path.length - 1] as string] = leaf;+}++/** Whether a (possibly nested) leaf at `path` is present in `value`. */+function leafPresent(value: unknown, path: readonly string[]): boolean {+ let cur: unknown = value;+ for (let i = 0; i < path.length - 1; i++) {+ if (!isPlainObject(cur)) return false;+ cur = cur[path[i] as string];+ }+ return isPlainObject(cur) && (path[path.length - 1] as string) in cur;+}let testDir: string;@@ -70,41 +98,54 @@ describe('readConfigSafely', () => {expect(warnings.length).toBeGreaterThan(0);});- test('removed config key → valid=false, error.code=REMOVED_KEY, file sidelined, value is defaults', () => {- // Removed keys pass loose-mode schema validation, so this is the cold-start- // recovery contract: a stale user-global config is sidelined and OK boots- // on defaults rather than applying a no-op key the user believes took- // effect. The project loader throws instead.+ test('removed keys → valid=true, keys stripped, siblings preserved, file not sidelined', () => {+ // Strip-and-continue: dead keys are removed from the resolved value and+ // reported as diagnostics, but every live sibling keeps its on-disk value+ // and the file is left in place. A stale key no longer discards the file.const path = resolve(testDir, 'stale.yml');- writeFileSync(path, 'folders:\n - path: "x/**"\nserver:\n host: 0.0.0.0\n', 'utf-8');+ writeFileSync(+ path,+ 'folders:\n - path: "x/**"\nserver:\n host: 0.0.0.0\ncontent:\n dir: docs\n',+ 'utf-8',+ );const warnings: string[] = [];- const result = readConfigSafely({- absPath: path,- timestamp: '2026-06-01T00-00-00-000Z',- warn: (msg) => warnings.push(msg),- });- expect(result.valid).toBe(false);- if (!result.valid) {- expect(result.error.code).toBe('REMOVED_KEY');- expect(result.value.content.dir).toBe('.'); // booted on defaults- expect(existsSync(path)).toBe(false); // sidelined, not crashed- expect(result.sidelinedTo).toBeDefined();+ const result = readConfigSafely({ absPath: path, warn: (msg) => warnings.push(msg) });+ expect(result.valid).toBe(true);+ if (result.valid) {+ // Live sibling keeps its on-disk value, not a schema default.+ expect(result.value.content.dir).toBe('docs');+ // Both removed keys are gone from the resolved value.+ expect(leafPresent(result.value, ['folders'])).toBe(false);+ expect(leafPresent(result.value, ['server', 'host'])).toBe(false);+ // One diagnostic per removed key.+ const removed = result.diagnostics.filter((d) => d.code === 'REMOVED_KEY');+ const dotted = removed.map((d) => (d.code === 'REMOVED_KEY' ? d.path.join('.') : ''));+ expect(dotted).toContain('folders');+ expect(dotted).toContain('server.host');+ expect(removed).toHaveLength(2);}- // Warning names every removed key found in one pass.- expect(warnings.join('\n')).toContain('folders');- expect(warnings.join('\n')).toContain('server.host');+ // File left in place — a removed key is not a reason to sideline.+ expect(existsSync(path)).toBe(true);+ const siblings = readdirSync(testDir).filter((f) => f.includes('.invalid-'));+ expect(siblings).toEqual([]);});- test('pass-through mode leaves a removed-key file in place', () => {- const path = resolve(testDir, 'stale-passthrough.yml');- writeFileSync(path, 'preview:\n baseUrl: https://example.test\n', 'utf-8');- const result = readConfigSafely({ absPath: path, sideline: false });- expect(result.valid).toBe(false);- if (!result.valid) {- expect(result.error.code).toBe('REMOVED_KEY');- expect(result.sidelinedTo).toBeUndefined();+ test('a removed key is never sidelined, regardless of the sideline option', () => {+ for (const sideline of [true, false] as const) {+ const path = resolve(testDir, `stale-${sideline}.yml`);+ writeFileSync(+ path,+ 'preview:\n baseUrl: https://example.test\ncontent:\n dir: docs\n',+ 'utf-8',+ );+ const result = readConfigSafely({ absPath: path, sideline, warn: () => {} });+ expect(result.valid).toBe(true);+ if (result.valid) {+ expect(result.value.content.dir).toBe('docs');+ expect(result.diagnostics.some((d) => d.code === 'REMOVED_KEY')).toBe(true);+ }+ expect(existsSync(path)).toBe(true);}- expect(existsSync(path)).toBe(true); // left in place});test('schema-invalid YAML → valid=false, error.code=SCHEMA_INVALID with structured issues + source', () => {@@ -216,3 +257,109 @@ describe('readConfigSafely', () => {expect(readFileSync(path, 'utf-8')).toContain('dir: docs');});});++describe('readConfigSafely — strip-and-continue invariant', () => {+ let dir: string;+ beforeEach(() => {+ dir = resolve(tmpdir(), `ok-strip-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);+ mkdirSync(dir, { recursive: true });+ });+ afterEach(() => {+ rmSync(dir, { recursive: true, force: true });+ });++ // The regression that matters: for EVERY registry key, a config carrying that+ // key plus a live sibling must resolve the sibling to its on-disk value, strip+ // the dead key, and stay valid + un-sidelined.+ for (const entry of REMOVED_KEYS) {+ const dotted = entry.path.join('.');+ test(`${dotted}: sibling resolves to on-disk value; key stripped; one diagnostic`, () => {+ const obj: Record<string, unknown> = { content: { dir: 'docs' } };+ setPath(obj, entry.path, 'sentinel');+ const path = resolve(dir, 'cfg.yml');+ writeFileSync(path, stringify(obj), 'utf-8');++ const result = readConfigSafely({ absPath: path, warn: () => {} });++ expect(result.valid).toBe(true);+ if (result.valid) {+ expect(result.value.content.dir).toBe('docs'); // sibling, not a default+ expect(leafPresent(result.value, entry.path)).toBe(false); // key stripped+ const removed = result.diagnostics.filter((d) => d.code === 'REMOVED_KEY');+ expect(removed).toHaveLength(1);+ const [diag] = removed;+ if (diag?.code === 'REMOVED_KEY') {+ expect(diag.path).toEqual(entry.path);+ expect(diag.redirect).toBe(entry.redirect);+ }+ }+ expect(existsSync(path)).toBe(true);+ });+ }+});++describe('readConfigSafely — diagnostics on the invalid arm', () => {+ let dir: string;+ beforeEach(() => {+ dir = resolve(tmpdir(), `ok-invalid-diag-${Date.now()}-${Math.random().toString(36).slice(2)}`);+ mkdirSync(dir, { recursive: true });+ });+ afterEach(() => {+ rmSync(dir, { recursive: true, force: true });+ });++ test('YAML parse failure surfaces a YAML_PARSE diagnostic', () => {+ const path = resolve(dir, 'broken.yml');+ writeFileSync(path, 'content:\n dir: [invalid yaml', 'utf-8');+ const result = readConfigSafely({ absPath: path, sideline: false, warn: () => {} });+ expect(result.valid).toBe(false);+ if (!result.valid) {+ expect(result.diagnostics).toHaveLength(1);+ expect(result.diagnostics[0]?.code).toBe('YAML_PARSE');+ }+ });++ test('schema-invalid config surfaces a SCHEMA_INVALID diagnostic', () => {+ const path = resolve(dir, 'bad.yml');+ writeFileSync(path, 'appearance:\n theme: midnight\n', 'utf-8');+ const result = readConfigSafely({ absPath: path, sideline: false, warn: () => {} });+ expect(result.valid).toBe(false);+ if (!result.valid) {+ expect(result.diagnostics.some((d) => d.code === 'SCHEMA_INVALID')).toBe(true);+ }+ });++ test('a clean config reports an empty diagnostics array', () => {+ const path = resolve(dir, 'clean.yml');+ writeFileSync(path, 'content:\n dir: docs\n', 'utf-8');+ const result = readConfigSafely({ absPath: path });+ expect(result.valid).toBe(true);+ if (result.valid) {+ expect(result.diagnostics).toEqual([]);+ }+ });++ test('a file that exists but cannot be read reports UNREADABLE, not silence', () => {+ // A directory where a file is expected reproduces the same class as EACCES+ // or a symlink loop: the path exists, so the missing-file arm is skipped,+ // but the read throws. Reporting nothing here makes an unreadable layer+ // indistinguishable from a clean one on every downstream surface.+ const path = resolve(dir, 'a-directory.yml');+ mkdirSync(path, { recursive: true });+ const result = readConfigSafely({ absPath: path, sideline: false, warn: () => {} });+ expect(result.valid).toBe(false);+ expect(result.diagnostics.map((d) => d.code)).toEqual(['UNREADABLE']);+ });++ test('a removed key is still reported when the same file also fails schema validation', () => {+ // Both problems surface in one pass. Reporting only the schema error would+ // send the user back for a second round once they fixed it.+ const path = resolve(dir, 'both-problems.yml');+ writeFileSync(path, 'appearance:\n theme: midnight\nserver:\n host: 0.0.0.0\n', 'utf-8');+ const result = readConfigSafely({ absPath: path, sideline: false, warn: () => {} });+ expect(result.valid).toBe(false);+ const codes = result.diagnostics.map((d) => d.code);+ expect(codes).toContain('REMOVED_KEY');+ expect(codes).toContain('SCHEMA_INVALID');+ });+});diff --git a/packages/core/src/config/read-config-safely.ts b/packages/core/src/config/read-config-safely.tsindex e4f56e0d0..460d6733b 100644--- a/packages/core/src/config/read-config-safely.ts+++ b/packages/core/src/config/read-config-safely.ts@@ -1,28 +1,38 @@/**- * Cold-start recovery for invalid config files.+ * Safe config reader shared by every non-throwing read path (CLI user-global+ * layer, desktop utility process, server project + project-local layers).*- * Reads a config file, validates it against `ConfigSchema`, and on failure- * sidelines the broken file (rename to `<path>.invalid-<ISO-timestamp>`) so- * the server can boot on schema defaults. If the rename itself fails (e.g.,- * read-only filesystem), the original file is left in place and a warning- * is logged.+ * Always returns a usable `Config` plus structured `diagnostics`:*- * Used at boot for `~/.ok/global.yml` (the user-global path).- * The project path uses the regular loader because project errors are- * user-fixable in-place — failing fast helps the user notice. User-global- * errors block every OK boot until manually repaired, so the recovery path- * is the right default there.+ * - Removed keys (`REMOVED_KEY`) are stripped from the parsed value and+ * reported as diagnostics; the file stays `valid` and every other key+ * resolves to its on-disk value. A dead key can never change runtime+ * behavior — by contract the engine no longer reads it — so it must never+ * invalidate a sibling. The file is left in place (never sidelined);+ * `ok config migrate` is the fix path.*- * Sync rather than async because the loader path it feeds (`loadConfig`)- * is sync and called from Commander.js's preAction hook. The fs ops here- * are a single file read + at most one rename — sub-millisecond on any+ * - Genuine corruption (`YAML_PARSE`, `SCHEMA_INVALID`) means the file cannot+ * be trusted, so `valid` is false, `value` is schema defaults, and — when+ * `sideline` is set — the file is renamed to `<path>.invalid-<ISO-timestamp>`+ * so the server can still boot. If the rename fails (e.g. read-only+ * filesystem), the original is left in place and a warning is logged.+ *+ * Sync rather than async because the loader path it feeds (`loadConfig`) is+ * sync and called from Commander.js's preAction hook. The fs ops here are a+ * single file read + at most one rename — sub-millisecond on any* non-pathological filesystem.*/import { existsSync, readFileSync, renameSync } from 'node:fs';import { type Document, parseDocument } from 'yaml';-import { type ConfigIssue, type ConfigValidationError, humanFormat } from './errors.ts';-import { detectRemovedKeys } from './removed-keys.ts';+import {+ type ConfigDiagnostic,+ type ConfigIssue,+ type ConfigValidationError,+ isKnownConfigError,+ type RemovedKeyDiagnostic,+} from './errors.ts';+import { detectRemovedKeys, stripRemovedKeys } from './removed-keys.ts';import { type Config, ConfigSchema } from './schema.ts';import { locateIssue } from './source-locator.ts';@@ -53,6 +63,13 @@ export type ReadConfigSafelyResult =value: Config;/** Absolute path of the file that was read. `undefined` when missing. */source?: string;+ /**+ * Removed-key diagnostics; empty when the file carried no dead keys.+ * Narrower than the degraded arm's type on purpose: a valid read can only+ * ever report stripped keys, so a corruption code landing here is a type+ * error rather than something a caller has to notice at runtime.+ */+ diagnostics: RemovedKeyDiagnostic[];}| {valid: false;@@ -61,6 +78,8 @@ export type ReadConfigSafelyResult =error: ConfigValidationError;/** Where the original broken file was sidelined to, if rename succeeded. */sidelinedTo?: string;+ /** Diagnostic mirroring the degradation (`YAML_PARSE` / `SCHEMA_INVALID`). */+ diagnostics: ConfigDiagnostic[];};/**@@ -125,7 +144,7 @@ export function readConfigSafely(options: ReadConfigSafelyOptions): ReadConfigSa// Missing file: no error, just defaults. The loader's existing semantic.if (!existsSync(absPath)) {- return { valid: true, value: defaults, source: undefined };+ return { valid: true, value: defaults, source: undefined, diagnostics: [] };}// Read raw source.@@ -135,14 +154,20 @@ export function readConfigSafely(options: ReadConfigSafelyOptions): ReadConfigSa} catch (e) {const detail = e instanceof Error ? e.message : String(e);warn(`[config] Could not read ${absPath}: ${detail}. Using schema defaults.`);+ // A layer that could not be read at all must stay distinguishable from one+ // that read cleanly, or the reporting surfaces answer all-clear for it.+ const diagnostic: ConfigDiagnostic = { code: 'UNREADABLE', detail };return {valid: false,value: defaults,- error: { code: 'UNKNOWN', message: `Read failed: ${detail}` },+ error: diagnostic,+ diagnostics: [{ ...diagnostic }],};}- // Parse via Document (preserves source positions for issue location).+ // Parse via Document (preserves source positions for issue location). A YAML+ // syntax error means the file cannot be trusted: sideline and boot on+ // defaults, unchanged from before strip-and-continue.const doc = parseDocument(source);if (doc.errors.length > 0) {const detail = doc.errors.map((e) => e.message).join('; ');@@ -151,17 +176,30 @@ export function readConfigSafely(options: ReadConfigSafelyOptions): ReadConfigSa(sideline ? '' : ' Pass-through mode: file left in place.'),);const sidelinedTo = sideline ? attemptSideline(absPath, timestamp, warn) : undefined;+ const diagnostic: ConfigDiagnostic = { code: 'YAML_PARSE', detail };return {valid: false,value: defaults,- error: { code: 'YAML_PARSE', detail },+ error: diagnostic,+ // Copy rather than alias: `error` and `diagnostics` are independent+ // public fields, so a caller normalizing one must not mutate the other.+ diagnostics: [{ ...diagnostic }],...(sidelinedTo !== undefined ? { sidelinedTo } : {}),};}- // Validate against ConfigSchema.const merged = doc.toJSON() ?? {};- const parsed = ConfigSchema.safeParse(merged);++ // Removed keys pass loose-mode schema validation silently. Detect them+ // against the original document (so diagnostics stay source-located), then+ // strip them from a clean copy and validate that copy — re-applying schema+ // defaults to the cleaned object. A removed key is never a reason to reject+ // the file: the engine no longer reads it, so stripping it cannot change the+ // resolved value of any live sibling.+ const removedKeyDiagnostics = detectRemovedKeys({ value: merged, file: absPath, source, doc });+ const cleaned = removedKeyDiagnostics.length > 0 ? stripRemovedKeys(merged) : merged;++ const parsed = ConfigSchema.safeParse(cleaned);if (!parsed.success) {const error = buildSchemaInvalidError(parsed, doc, source, absPath);warn(@@ -169,36 +207,29 @@ export function readConfigSafely(options: ReadConfigSafelyOptions): ReadConfigSa(sideline ? '' : ' Pass-through mode: file left in place.'),);const sidelinedTo = sideline ? attemptSideline(absPath, timestamp, warn) : undefined;+ // Copied for the same reason as the YAML-parse arm above: `error` and+ // `diagnostics` must not share a mutable object across two public fields.+ // Removed keys detected before validation are still reported here — a+ // schema error elsewhere in the file must not hide them and force the user+ // into the two-trip fix cycle `detectRemovedKeys` exists to avoid.+ const diagnostics: ConfigDiagnostic[] = [+ ...removedKeyDiagnostics,+ ...(isKnownConfigError(error) && error.code === 'SCHEMA_INVALID' ? [{ ...error }] : []),+ ];return {valid: false,value: defaults,error,+ diagnostics,...(sidelinedTo !== undefined ? { sidelinedTo } : {}),};}- // Removed keys pass loose-mode schema validation silently. Reject them here- // so a stale file is sidelined and boots on defaults rather than applying a- // no-op key the user believes took effect. This is the recovery path- // (user-global `~/.ok/global.yml`); the project loader fails loud instead so- // a user-fixable file gets fixed.- const removedKeyErrors = detectRemovedKeys({ value: merged, file: absPath, source, doc });- const firstRemovedKeyError = removedKeyErrors[0];- if (firstRemovedKeyError !== undefined) {- warn(- `[config] ${absPath} carries removed config key(s):\n` +- `${removedKeyErrors.map(humanFormat).join('\n\n')}\n` +- `Using schema defaults.` +- (sideline ? '' : ' Pass-through mode: file left in place.'),- );- const sidelinedTo = sideline ? attemptSideline(absPath, timestamp, warn) : undefined;- return {- valid: false,- value: defaults,- error: firstRemovedKeyError,- ...(sidelinedTo !== undefined ? { sidelinedTo } : {}),- };- }-- return { valid: true, value: parsed.data, source: absPath };+ // Strip-and-continue: the file is valid, with any dead keys removed. The+ // dead keys are returned, not warned about. Several callers re-read config+ // fresh on every request, so warning here would emit the same multi-line+ // notice on every link hover or lint pass — and it would arrive under a+ // caller's "could not read" label for a read that succeeded. Reporting is+ // the caller's job, once, where it can reach a user.+ return { valid: true, value: parsed.data, source: absPath, diagnostics: removedKeyDiagnostics };}diff --git a/packages/core/src/config/removed-keys.test.ts b/packages/core/src/config/removed-keys.test.tsindex e04654a72..4aea45059 100644--- a/packages/core/src/config/removed-keys.test.ts+++ b/packages/core/src/config/removed-keys.test.ts@@ -1,7 +1,7 @@import { describe, expect, test } from 'vitest';import { parseDocument } from 'yaml';import { isKnownConfigError } from './errors.ts';-import { detectRemovedKeys, REMOVED_KEYS } from './removed-keys.ts';+import { detectRemovedKeys, REMOVED_KEYS, stripRemovedKeys } from './removed-keys.ts';/** Build a nested object `{ a: { b: <leaf> } }` from a dotted path. */function nest(path: readonly string[], leaf: unknown): Record<string, unknown> {@@ -110,3 +110,57 @@ describe('detectRemovedKeys', () => {expect(detectRemovedKeys({ value: [] })).toEqual([]);});});++describe('stripRemovedKeys', () => {+ // Table-driven: every registry entry, in isolation, must be stripped while a+ // top-level sibling survives.+ for (const entry of REMOVED_KEYS) {+ const dotted = entry.path.join('.');+ test(`strips ${dotted} and leaves siblings intact`, () => {+ const input = nest(entry.path, 'x');+ input.keep = 'me';+ const out = stripRemovedKeys(input);+ // The dead key is gone — the detector finds nothing.+ expect(detectRemovedKeys({ value: out })).toEqual([]);+ // The sibling survives.+ expect((out as Record<string, unknown>).keep).toBe('me');+ });+ }++ test('does not mutate the input', () => {+ const input: Record<string, unknown> = {+ folders: [{ path: 'x' }],+ content: { dir: 'docs' },+ };+ const out = stripRemovedKeys(input) as Record<string, unknown>;+ expect(input.folders).toBeDefined(); // original untouched+ expect(out.folders).toBeUndefined();+ expect(out.content).toEqual({ dir: 'docs' });+ });++ test('strips several keys in one pass, keeping live siblings under the same branch', () => {+ const input = {+ folders: [],+ server: { host: '0.0.0.0', openOnAgentEdit: true, keepMe: 1 },+ content: { dir: 'd' },+ };+ const out = stripRemovedKeys(input) as Record<string, unknown>;+ expect(out.folders).toBeUndefined();+ const server = out.server as Record<string, unknown>;+ expect(server.host).toBeUndefined();+ expect(server.openOnAgentEdit).toBeUndefined();+ // A non-removed sibling under `server` survives.+ expect(server.keepMe).toBe(1);+ expect(out.content).toEqual({ dir: 'd' });+ });++ test('non-object input is returned unchanged', () => {+ expect(stripRemovedKeys(null)).toBeNull();+ expect(stripRemovedKeys('s')).toBe('s');+ expect(stripRemovedKeys([1, 2])).toEqual([1, 2]);+ });++ test('a clean config is returned structurally unchanged', () => {+ expect(stripRemovedKeys({ content: { dir: 'docs' } })).toEqual({ content: { dir: 'docs' } });+ });+});diff --git a/packages/core/src/config/removed-keys.ts b/packages/core/src/config/removed-keys.tsindex 3d8a4c2f1..0b53acc8a 100644--- a/packages/core/src/config/removed-keys.ts+++ b/packages/core/src/config/removed-keys.ts@@ -8,20 +8,22 @@* registry a removed key is a silent no-op — the worst failure mode for a* config contract, because the user believes it took effect.*- * Every entry here is rejected loudly with a source-located `REMOVED_KEY`- * error whose `redirect` names the replacement. The same table drives the- * `ok config migrate` codemod, so the "run `ok config migrate`" hint in each- * redirect is always truthful.+ * Readers strip every entry here from the parsed value and surface a+ * source-located `REMOVED_KEY` diagnostic whose `redirect` names the+ * replacement. Stripping a removed key can never change runtime behavior — by+ * contract the engine no longer reads it — so a dead key never invalidates its+ * live siblings. The same table drives the `ok config migrate` codemod, and+ * that command defaults to every config layer, so the bare "run `ok config+ * migrate`" hint in each redirect reaches the key it names wherever it lives —+ * including the project-local layer. Narrowing that default would make the+ * hint false for any key outside the layers it still covers.*- * Severity is uniform — there is no warn tier. Where the error surfaces- * (throw vs. sideline) is the CALLER's decision: the project loader throws- * (fail-fast, the key is user-fixable in place), while the cold-start- * recovery path (`readConfigSafely`, used for `~/.ok/global.yml`) sidelines- * the file and boots on defaults so a stale user-global config can never- * brick every project.+ * Severity is uniform — there is no warn tier. The registry records only the+ * fact of the mismatch; whether a given caller warns, blocks, or degrades a+ * dependent feature is caller policy, not a property of the entry.*/import type { Document } from 'yaml';-import type { ConfigIssueSource, ConfigValidationError } from './errors.ts';+import type { ConfigIssueSource, RemovedKeyDiagnostic } from './errors.ts';import { locateIssue } from './source-locator.ts';export interface RemovedKey {@@ -35,8 +37,12 @@ export interface RemovedKey {* Shared tail appended to every redirect except the bespoke `content.*` ones* (those predate the registry and carry their own, test-pinned wording).*/+// Names no file on purpose. A removed key can sit in any of three layers+// (`~/.ok/global.yml`, `.ok/config.yml`, `.ok/local/config.yml`) and the command+// defaults to all of them, so naming `config.yml` would read as a limit the+// command does not have.const MIGRATE_HINT =- 'Run `ok config migrate` to strip the obsolete key from config.yml automatically, or remove it by hand.';+ 'Run `ok config migrate` to strip the obsolete key automatically, or remove it by hand.';/*** The removed-key registry. Adding a removal is a one-line entry here — the@@ -191,22 +197,66 @@ export interface DetectRemovedKeysInput {* one pass — no two-trip fix cycle. Each error is source-located when `file`,* `source`, and `doc` are supplied.*/-export function detectRemovedKeys(input: DetectRemovedKeysInput): ConfigValidationError[] {+export function detectRemovedKeys(input: DetectRemovedKeysInput): RemovedKeyDiagnostic[] {const { value, file, source, doc } = input;if (!isPlainObject(value)) return [];- const errors: ConfigValidationError[] = [];+ const diagnostics: RemovedKeyDiagnostic[] = [];for (const entry of REMOVED_KEYS) {if (!hasLeaf(value, entry.path)) continue;let located: ConfigIssueSource | undefined;if (doc != null && source != null && file != null) {located = locateIssue({ file, source, doc, path: entry.path });}- errors.push({+ diagnostics.push({code: 'REMOVED_KEY',path: entry.path,redirect: entry.redirect,...(located !== undefined ? { source: located } : {}),});}- return errors;+ return diagnostics;+}++/**+ * Remove `path`'s leaf from `obj`, cloning only the objects along the path so+ * untouched subtrees are shared by reference. Returns a new object; `obj` is+ * never mutated.+ */+function removePath(+ obj: Record<string, unknown>,+ path: readonly string[],+): Record<string, unknown> {+ const [head, ...rest] = path;+ if (head === undefined) return obj;+ const clone: Record<string, unknown> = { ...obj };+ if (rest.length === 0) {+ delete clone[head];+ return clone;+ }+ const child = clone[head];+ if (isPlainObject(child)) {+ clone[head] = removePath(child, rest);+ }+ return clone;+}++/**+ * Return `value` with every registry key removed. Non-object input is returned+ * unchanged; the input is never mutated. Callers strip the dead keys from the+ * parsed config, then re-validate so schema defaults re-apply cleanly to the+ * cleaned object.+ *+ * Stripping keys from an object yields an object, so the object overload lets+ * a caller that passes a typed record use the result without re-narrowing.+ */+export function stripRemovedKeys(value: Record<string, unknown>): Record<string, unknown>;+export function stripRemovedKeys(value: unknown): unknown;+export function stripRemovedKeys(value: unknown): unknown {+ if (!isPlainObject(value)) return value;+ let result: Record<string, unknown> = value;+ for (const entry of REMOVED_KEYS) {+ if (!hasLeaf(result, entry.path)) continue;+ result = removePath(result, entry.path);+ }+ return result;}diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex f237dcfae..89078bfb9 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -161,6 +161,10 @@ export {type OkignoreUnsubscribe,} from './config/bind-okignore-doc.ts';export {+ type ConfigDiagnostic,+ ConfigDiagnosticSchema,+ type ConfigDiagnosticsReport,+ ConfigDiagnosticsReportSchema,type ConfigIssue,ConfigIssueSchema,type ConfigIssueSource,@@ -175,6 +179,9 @@ export {isKnownConfigError,type KnownConfigValidationError,KnownConfigValidationErrorSchema,+ type RemovedKeyDiagnostic,+ type ScopedConfigDiagnostic,+ ScopedConfigDiagnosticSchema,type WriteScope,WriteScopeSchema,} from './config/errors.ts';@@ -189,6 +196,7 @@ export {detectRemovedKeys,REMOVED_KEYS,type RemovedKey,+ stripRemovedKeys,} from './config/removed-keys.ts';export type { Err, Ok, Result } from './config/result.ts';// Config schema, error envelope, and Result helper. Browser+node compatible.diff --git a/packages/core/src/server.ts b/packages/core/src/server.tsindex ba15b687f..5a21e4474 100644--- a/packages/core/src/server.ts+++ b/packages/core/src/server.ts@@ -14,6 +14,10 @@* the split is the contract.*/+export {+ type CollectConfigDiagnosticsOptions,+ collectConfigDiagnostics,+} from './config/collect-config-diagnostics.ts';export {type ConfigPathPresence,type InspectConfigPathsOptions,diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex 15825edf4..287409321 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -62,6 +62,8 @@ import {ClientLogsSuccessSchema,CONFIG_DOC_NAME_OKIGNORE,CommentCountsSuccessSchema,+ type ConfigDiagnosticsReport,+ ConfigDiagnosticsReportSchema,CreateFolderRequestSchema,CreateFolderSuccessSchema,CreatePageRequestSchema,@@ -3024,6 +3026,13 @@ export interface ApiExtensionOptions {* enforcement point.*/getLinkPreviewsEnabled?: () => boolean;+ /**+ * Fresh-read collector for `GET /api/config/diagnostics` — reads the user,+ * committed-project, and project-local config files on each call so an edit+ * is reflected without a restart. Omitted in test harnesses that don't wire+ * config; the handler then reports an empty diagnostics set.+ */+ getConfigDiagnostics?: () => ConfigDiagnosticsReport;/*** Basename-index resolver for `![[photo.png]]` wiki-embed refs. Threaded* into every server-side `mdManager.parseWithFallback` call (managed-rename@@ -3316,6 +3325,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {ephemeral = false,linkPreviewFetch,getLinkPreviewsEnabled,+ getConfigDiagnostics,} = options;// Concurrency guard: at most 1 in-flight request per local-op endpoint@@ -24515,6 +24525,45 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {});}+ // `/api/config/diagnostics` — active config diagnostics across the user,+ // committed-project, and project-local layers. Read-only and open like+ // `/api/config`: the collector reads the files fresh per request (so a+ // hand-edit or `ok config migrate` is reflected without a restart) and+ // returns only structural findings — scope, file, key path, code, redirect —+ // never a raw config value. `no-store` so a poll always sees current disk+ // state.+ async function handleConfigDiagnostics(req: IncomingMessage, res: ServerResponse): Promise<void> {+ if (req.method === 'GET' || req.method === 'HEAD') {+ try {+ const payload = getConfigDiagnostics?.() ?? { diagnostics: [] };+ // HEAD mirrors GET's headers with no body; `successResponse` always+ // writes one, so the no-body verb stays a manual emit.+ if (req.method === 'HEAD') {+ res.setHeader('Content-Type', 'application/json');+ res.setHeader('Cache-Control', 'no-store');+ res.setHeader('X-Content-Type-Options', 'nosniff');+ res.statusCode = 200;+ res.end();+ return;+ }+ successResponse(res, 200, ConfigDiagnosticsReportSchema, payload, {+ handler: 'api-config-diagnostics',+ extraHeaders: { 'Cache-Control': 'no-store' },+ });+ } catch (e) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'api-config-diagnostics',+ cause: e,+ });+ }+ return;+ }+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'api-config-diagnostics',+ extraHeaders: { Allow: 'GET, HEAD' },+ });+ }+// ───────────────────── Embeddings API key — Account control ─────────────────// Loopback + Origin gated (checkLocalOpSecurity) set/clear for the// machine-global embeddings key. The key travels renderer → loopback POST body@@ -25833,6 +25882,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {'/api/config': handleApiConfig,+ '/api/config/diagnostics': handleConfigDiagnostics,'/api/comments': handleCommentsRoute,'/api/comment': handleCommentRoute,'/api/asset': handleAsset,diff --git a/packages/server/src/server-factory.test.ts b/packages/server/src/server-factory.test.tsindex a34edb63b..c1ecd6c1b 100644--- a/packages/server/src/server-factory.test.ts+++ b/packages/server/src/server-factory.test.ts@@ -10,11 +10,12 @@ import {import { mkdtemp, readFile, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';import { join, resolve } from 'node:path';-import { LOCAL_DIR } from '@inkeep/open-knowledge-core';+import { LOCAL_DIR, REMOVED_KEYS } from '@inkeep/open-knowledge-core';import { readConfigSafely, resolveConfigPath } from '@inkeep/open-knowledge-core/server';import shellQuote from 'shell-quote';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 { BacklinkIndex } from './backlink-index.ts';import { getBootTimings, resetBootTimingsForTest, startBootTimings } from './boot-timings.ts';@@ -1329,6 +1330,136 @@ describe('createServer() — project-local file watcher → engine.setMode', ()});});+// ─── removed key in project-local must not disable sync ─────────────────────+//+// A dead key sharing the project-local file with `autoSync.mode` used to+// invalidate the whole file (schema defaults substituted), so the real mode was+// discarded and sync resolved to `off`. Strip-and-continue keeps the mode live+// and reports the dead key as a diagnostic instead of treating it as a degraded+// read. `readLinkPreviewsEnabled`'s egress fail-closed direction is the mirror+// case: it must still trip on genuine corruption but not on a stripped key.++/**+ * Render a single removed-key entry into a nested object `{ a: { b: { leaf } } }`+ * so it can be serialized into a config fixture.+ */+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;+ }++ // The exact field regression: a dead `appearance.sidebar.showAllFiles` beside+ // `autoSync.mode: full` used to fall back to the committed default → `off`.+ 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');++ // Assert the structured field, not the prose: `logConfigDiagnosticsOnce`+ // logs `{ scope, file, path }` as the payload and the human sentence as the+ // message, so `payload.path` is the stable contract and the message text is+ // free to be reworded. The message check only pins that the sentence a user+ // reads names the dead key too.+ 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);+ });++ // The same invariant across the whole registry: no dead key, whatever its+ // path, may reach `autoSync` and change the resolved mode.+ 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');+ });++ // A stripped removed key is a clean read, so the fail-closed egress guard does+ // not trip: an explicit opt-in resolves enabled. Read fresh after a live write+ // to exercise the no-restart contract.+ 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);+ });++ // Genuine degradation still fails egress closed — the per-field direction that+ // a stripped key must no longer trigger.+ 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;diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex a5691b4b3..b3fecb765 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -19,6 +19,7 @@ import {CONFIG_DOC_NAME_PROJECT_LOCAL,CONFIG_DOC_NAME_USER,CONFIG_DOC_NAMES,+ type ConfigDiagnosticsReport,type ConfigIssue,createBasenameIndex,DEFAULT_ATTACHMENT_FOLDER_PATH,@@ -40,6 +41,7 @@ import {toEffectiveBase,} from '@inkeep/open-knowledge-core';import {+ collectConfigDiagnostics,readConfigSafely,resolveConfigPath,writeConfigPatch,@@ -433,6 +435,18 @@ export interface ServerInstance {readonly lockDir: string;/** Active sync engine instance, or null if dormant / no remote detected. */readonly syncEngine: SyncEngine | null;+ /**+ * Fresh-read accessor for the project-local `linkPreviews.enabled` egress+ * setting, resolved through the same strip-and-continue reader the HTTP+ * link-preview handler consumes. Reads disk on each call (a Settings edit+ * applies without a restart) and fails closed when the config can't be+ * trusted.+ *+ * @internal Exposed so tests can pin the fail-closed/fail-open direction+ * directly, which is the highest-risk behavior in the config read path.+ * Production consumers reach this through the api-extension option, not here.+ */+ readonly getLinkPreviewsEnabled: () => boolean;/*** Wiki-embed resolver (basename → contentDir-relative path). Exposed so* consumers that apply agent markdown writes outside the HTTP handlers@@ -680,7 +694,7 @@ export function createServer(options: ServerOptions): ServerInstance {if (!local.valid) {log.warn({},- '[config] project-local autoSync.enabled unavailable (config invalid) — falling back to the committed project default',+ '[config] project-local autoSync.mode unavailable (config invalid) — falling back to the committed project default',);}// Unanswered on this machine: consult the committed project default@@ -770,15 +784,47 @@ export function createServer(options: ServerOptions): ServerInstance {sideline: false,warn: (message) => log.warn({ message }, '[config] could not read project-local config'),});- // Fail closed on a degraded read (unreadable / invalid YAML / schema-invalid- // / removed-key): only a genuinely-absent config resolves to the on-by-default- // schema value. Without this, an explicit `enabled: false` opt-out would- // silently revert to egress-ON the moment the project-local file became- // unparseable (concurrent writer, crash mid-write, a stale key elsewhere).+ // Fail closed on a genuinely degraded read — unreadable, invalid YAML, or+ // schema-invalid — where only schema defaults are available: an explicit+ // `enabled: false` opt-out must not silently revert to egress-ON when the+ // file can't be trusted (concurrent writer, crash mid-write). A stripped+ // removed key is NOT a degraded read — the read stays valid with the dead+ // key dropped — so an unrelated stale key leaves this opt-out intact.if (!local.valid) return false;return local.value.linkPreviews?.enabled === true;}+ // Fresh-read collector for `GET /api/config/diagnostics`. Reads all three+ // config layers on each request (not the boot snapshot), resolving the same+ // files the readers above use, so a hand-edit or `ok config migrate` is+ // reflected without a restart. Diagnostics are returned to the caller, so the+ // per-read warning is demoted to debug — a polled endpoint must not re-log a+ // stale key on every request.+ function readConfigDiagnostics(): ConfigDiagnosticsReport {+ return collectConfigDiagnostics({+ cwd: projectDir,+ homedirOverride: configHomedirOverride,+ warn: (message) => log.debug({ message }, '[config] diagnostics read'),+ });+ }++ /**+ * Report stale config keys once, at boot. The reader strips them and returns+ * them rather than logging, because several readers above re-read config on+ * every request and would otherwise repeat this on every link hover or lint+ * pass. One line per key, at boot, is the whole server-side log signal; the+ * live view is the config-diagnostics endpoint.+ */+ function logConfigDiagnosticsOnce(): void {+ for (const finding of readConfigDiagnostics().diagnostics) {+ if (finding.code !== 'REMOVED_KEY') continue;+ log.warn(+ { scope: finding.scope, file: finding.file, path: finding.path.join('.') },+ `[config] ${finding.path.join('.')} is no longer read and was ignored. ${finding.redirect}`,+ );+ }+ }+// Provider identity for the cache key + the service's re-warm trigger. A change// here (provider/model/dims) re-loads the embedder and invalidates the cache.// Unset `dimensions` is its own stable identity, NOT the OpenAI default: the@@ -1873,6 +1919,7 @@ export function createServer(options: ServerOptions): ServerInstance {getLinterBaseConfig: () => readLinterBaseConfig(),getLinksValidationSetting: () => readLinksValidationSetting(),getLinkPreviewsEnabled: readLinkPreviewsEnabled,+ getConfigDiagnostics: readConfigDiagnostics,embeddingsSecretsFile: secretsFilePath(configHomedirOverride),readSemanticProviderConfig: readSemanticSearchConfig,ephemeral,@@ -4479,6 +4526,8 @@ export function createServer(options: ServerOptions): ServerInstance {// case the field stays absent and the envelope omits it.const readyElapsed = bootElapsedMs();if (readyElapsed !== undefined) recordBootPhase('readyMs', readyElapsed);++ logConfigDiagnosticsOnce();}// `ready` itself is the deferred Promise declared at the top of this factory@@ -4511,6 +4560,7 @@ export function createServer(options: ServerOptions): ServerInstance {get syncEngine() {return syncEngine;},+ getLinkPreviewsEnabled: readLinkPreviewsEnabled,resolveEmbed,acpRegistry,acpPermissions,