Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): make server.bind per-machine to protect local clones (#3500)
omar-inkeepabc145e4be56
diff --git a/.changeset/server-bind-per-machine.md b/.changeset/server-bind-per-machine.mdnew file mode 100644index 000000000..b7c20cc03--- /dev/null+++ b/.changeset/server-bind-per-machine.md@@ -0,0 +1,11 @@+---+"@inkeep/open-knowledge": patch+---++`server.bind` is now a per-machine setting, so a committed bind can no longer break local runs for people who clone a shared project.++Before this change, a project that committed `server.bind: 0.0.0.0` (or `::`) to `.ok/config.yml` so one machine could serve it remotely made `ok start` fail for every teammate who cloned the repo and ran it locally. The exposure interlock refused to boot because a non-loopback bind requires per-machine `server.allowExternal` consent, and consent is never committed.++`server.bind` moves from `project` scope to `project-local`, the same posture as `server.allowExternal`. A bind committed to the shared `.ok/config.yml` is now ignored, and named at startup with the fix, so local clones always bind loopback and boot. The machine that actually exposes the server sets the bind per-machine with `OK_BIND`, `ok start --bind <address>`, or `.ok/local/config.yml`.++The exposure gate is unchanged: an explicit `OK_BIND` or `--bind` to a non-loopback address without consent still refuses to start.diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdxindex cd12d81db..beeb77236 100644--- a/docs/content/reference/configuration.mdx+++ b/docs/content/reference/configuration.mdx@@ -47,7 +47,7 @@ A key set in a file more specific than its scope (a user-scope key in `.ok/confi| `autoSync.mode` | `"off" \| "follow" \| "full" \| null` | `null` | project-local | Per-machine sync mode for this project: `off` (no sync), `follow` (one-directional — pull remote changes, never push your own; the earlier value `pull` is accepted as an alias), `full` (bidirectional pull and push). `null` means "unanswered"; the editor's onboarding modal triggers on first remote-detected open. Supersedes `autoSync.enabled`. || `autoSync.enabled` | `boolean \| null` | `null` | project-local | Legacy per-machine auto-sync toggle, superseded by `autoSync.mode`. Read only when `mode` is absent (`true` = full, `false` = off). `null` means "unanswered". || `autoSync.default` | `"off" \| "follow" \| "full" \| boolean \| null` | `null` | project | Committed seed for each machine's first-open sync mode: `off` / `follow` / `full`, or the legacy boolean (`true` = full, `false` = off). `null` = ask. Lets a maintainer pre-answer the onboarding prompt for everyone who clones; a per-machine `autoSync.mode` overrides it. Compatibility note: a committed string value (`off` / `follow` / `full`) is rejected by app versions released before `autoSync.mode` existed, resetting that machine to config defaults until it updates (it never silently syncs). The legacy boolean seed (`true` / `false`) stays readable by older apps — commit `follow` only once collaborators are on a current version. |-| `server.bind` | list of addresses | `["127.0.0.1"]` | project | Addresses the server binds, e.g. `[127.0.0.1]` or `[0.0.0.0]`. The loopback default keeps everything off-machine out. A non-loopback bind additionally requires the `server.allowExternal` consent interlock. Lists replace, never merge. Env: `OK_BIND` (space-separated). Read at server start. |+| `server.bind` | list of addresses | `["127.0.0.1"]` | project-local | Addresses the server binds, e.g. `[127.0.0.1]` or `[0.0.0.0]`. The loopback default keeps everything off-machine out. A non-loopback bind additionally requires the `server.allowExternal` consent interlock. Per-machine — a value committed to `.ok/config.yml` is ignored (the exposing host would otherwise refuse to boot for every teammate who clones and runs locally, since the interlock needs per-machine consent that is never committed). Set it where the server is exposed: `OK_BIND` (space-separated), `ok start --bind <address>`, or `.ok/local/config.yml`. Lists replace, never merge. Read at server start. || `server.port` | number | (unset) | project | TCP port the server listens on. Unset = a local start picks a free port dynamically (deployment platforms inject `PORT` instead). Supersedes `remote.port`, which is still read while this key is absent. Read at server start. || `server.externalUrl` | string | (unset) | project | Canonical external origin the server is reached at, e.g. `https://kb.example.com` — its host joins the Host/Origin allowlists and issued URLs. Setting it declares external exposure, which additionally requires the `server.allowExternal` consent interlock. Supersedes `server.publicUrl` (the key's former name — still read as a deprecated alias while this key is absent) and `remote.url`. Env: `OK_EXTERNAL_URL` (`OK_PUBLIC_URL` remains a deprecated alias); flag: `ok start --external-url <url>`. Read at server start. Compatibility note: app versions from before this key existed read only `server.publicUrl` and silently ignore `server.externalUrl` (config is open-shape), so committing only the new key drops the declared host from those versions' Host/Origin allowlists and external requests 403. While collaborators are still on older versions, commit **both** keys with the same value — current versions prefer `server.externalUrl` (no deprecation notice when both are set) and older versions keep reading `server.publicUrl`; drop the old key once everyone has upgraded. || `server.publicUrl` | string | (unset) | project | Deprecated alias of `server.externalUrl` (the key's former name) — read only while that key is absent, with identical semantics; the CLI prints a rename notice when it is the one in effect. Env alias: `OK_PUBLIC_URL`; flag alias: `ok start --public-url <url>`. May be committed alongside `server.externalUrl` during a mixed-version window (see that key's compatibility note). Slated for removal after a deprecation window. |diff --git a/packages/cli/src/cli.test.ts b/packages/cli/src/cli.test.tsindex 61d5f5aa7..ab10cc42a 100644--- a/packages/cli/src/cli.test.ts+++ b/packages/cli/src/cli.test.ts@@ -1,4 +1,7 @@-import { describe, expect, test } from 'vitest';+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { afterEach, beforeEach, describe, expect, test } from 'vitest';const CLI_PACKAGE_ROOT = import.meta.dir.replace(/\/src$/, '');@@ -97,3 +100,56 @@ describe('CLI --version notice', () => {expect(stdout).toMatch(/NO WARRANTY/);}, 30_000);});++describe('committed project-local key startup warning', () => {+ let projectDir: string;++ beforeEach(() => {+ projectDir = mkdtempSync(join(tmpdir(), 'ok-committed-bind-'));+ mkdirSync(join(projectDir, '.ok'), { recursive: true });+ // A committed non-loopback bind — the clone-breaking case. It resolves to+ // the loopback default (ignored), and the preAction hook must name it.+ writeFileSync(join(projectDir, '.ok', 'config.yml'), 'server:\n bind:\n - 0.0.0.0\n');+ });++ afterEach(() => {+ rmSync(projectDir, { recursive: true, force: true });+ });++ test('the preAction hook names a committed server.bind as ignored and points at the OK_BIND fix', () => {+ // Exercises the wired emission loop in cli.ts — the loader-level and+ // formatter-level unit tests both pass even if this glue is removed, so a+ // command that goes through the preAction hook (`ok ps`) is the surface that+ // proves the startup warning actually reaches stderr.+ const result = Bun.spawnSync({+ cmd: [+ 'node',+ '--import',+ 'tsx',+ '--conditions=development',+ '-e',+ `+ process.argv = [+ process.execPath,+ process.cwd() + '/src/cli.ts',+ '--cwd',+ ${JSON.stringify(projectDir)},+ 'ps',+ '--json',+ ];+ await import('./src/cli.ts');+ `,+ ],+ cwd: CLI_PACKAGE_ROOT,+ env: { ...process.env, NO_COLOR: '1' },+ });++ const stderr = result.stderr.toString();+ expect(stderr).toContain('server.bind is a per-machine (project-local) setting');+ expect(stderr).toContain('.ok/local/config.yml');+ expect(stderr).toContain('OK_BIND');+ // The committed value is IGNORED, not applied — nothing exposes, so the+ // exposure interlock must never fire on this read-only listing.+ expect(stderr).not.toContain('ExposureConsentError');+ }, 30_000);+});diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.tsindex b7bea6998..7ecf13014 100644--- a/packages/cli/src/cli.ts+++ b/packages/cli/src/cli.ts@@ -21,7 +21,7 @@ trustSystemCertificates();import { spawn } from 'node:child_process';import { resolve } from 'node:path';-import { humanFormat } from '@inkeep/open-knowledge-core';+import { formatIgnoredCommittedKey, humanFormat } from '@inkeep/open-knowledge-core';import { type Config, ConfigSchema, trustSystemCertificates } from '@inkeep/open-knowledge-server';/*** CLI entry point for @inkeep/open-knowledge.@@ -169,6 +169,14 @@ programconsole.error(`[ok] ${humanFormat(diagnostic)}`);}}+ // Project-local keys committed to the shared `.ok/config.yml` are silently+ // dropped by the scope-aware merge — a committed `server.bind` would+ // otherwise refuse to boot for every teammate who clones and runs locally.+ // Name each one and its per-machine fix, once per invocation, for every+ // command (including the config family — nothing else reports these yet).+ for (const key of loaded.ignoredCommittedKeys) {+ console.error(`[ok] ${formatIgnoredCommittedKey(key)}`);+ }} catch (err) {if (subcommandName === 'uninstall' || subcommandName === 'deinit') {// Surface the original parse error before degrading — the user shoulddiff --git a/packages/cli/src/config/loader.test.ts b/packages/cli/src/config/loader.test.tsindex e4f847a31..8ad3e430e 100644--- a/packages/cli/src/config/loader.test.ts+++ b/packages/cli/src/config/loader.test.ts@@ -2,7 +2,14 @@ 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 {+ applyConfigOverlay,+ type ConfigDiagnostic,+ REMOVED_KEYS,+ requiresExternalConsent,+ resolveEnvConfigLayer,+ resolveServerRuntimeConfig,+} from '@inkeep/open-knowledge-core';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import { stringify } from 'yaml';@@ -623,10 +630,73 @@ describe('loadConfig — scope-aware layering (project-local)', () => {expect(config.server.openBrowser).toBe(false);});- test('project layer still owns project-scoped server keys', () => {- writeWorkspaceConfig('server:\n bind:\n - 127.0.0.1\n - 100.64.0.7\n');+ test('project layer still owns project-scoped server keys (port, externalUrl)', () => {+ writeWorkspaceConfig('server:\n port: 8080\n externalUrl: https://kb.example.com\n');const { config } = loadConfig(testDir);- expect(config.server.bind).toEqual(['127.0.0.1', '100.64.0.7']);+ expect(config.server.port).toBe(8080);+ expect(config.server.externalUrl).toBe('https://kb.example.com');+ });++ test('a committed server.bind is ignored (clone-safety) and reported as an ignored committed key', () => {+ // The footgun: a repo commits a non-loopback bind so one machine serves+ // remotely; a teammate who clones and runs `ok start` locally must bind the+ // loopback default (and boot), never inherit the committed value — which+ // would trip the exposure interlock they never consented to.+ writeWorkspaceConfig('server:\n bind:\n - 0.0.0.0\n');+ const { config, ignoredCommittedKeys } = loadConfig(testDir);+ expect(config.server.bind).toEqual(['127.0.0.1']);+ const bindKey = ignoredCommittedKeys.find((k) => k.path.join('.') === 'server.bind');+ expect(bindKey).toBeDefined();+ expect(bindKey?.envVar).toBe('OK_BIND');+ });++ test('a project-local server.bind is honored, with no ignored-committed-key warning', () => {+ writeLocalConfig('server:\n bind:\n - 0.0.0.0\n');+ const { config, ignoredCommittedKeys } = loadConfig(testDir);+ expect(config.server.bind).toEqual(['0.0.0.0']);+ expect(ignoredCommittedKeys).toEqual([]);+ });++ test('a committed file with both a removed key and a project-local key reports each correctly', () => {+ // strip-removed-keys runs BEFORE the project-local detector in loadRawLayer.+ // Pin that the two don't interfere: the removed `server.host` is stripped and+ // reported as REMOVED_KEY, the committed `server.bind` survives stripping and+ // is still flagged as ignored, and the in-scope `server.port` takes effect.+ writeWorkspaceConfig('server:\n host: 0.0.0.0\n bind:\n - 0.0.0.0\n port: 8080\n');+ const { config, diagnostics, ignoredCommittedKeys } = loadConfig(testDir);+ expect(config.server.port).toBe(8080);+ expect(config.server.bind).toEqual(['127.0.0.1']);+ expect(removedKeys(diagnostics).some((k) => k.dotted === 'server.host')).toBe(true);+ const bindKey = ignoredCommittedKeys.find((k) => k.path.join('.') === 'server.bind');+ expect(bindKey).toBeDefined();+ expect(bindKey?.envVar).toBe('OK_BIND');+ });++ test('interlock resolution: a committed bind boots on loopback, but explicit OK_BIND stays exposing', () => {+ // Mirrors the `ok start` resolution pipeline: loadConfig (scope-aware merge)+ // -> env overlay -> resolveServerRuntimeConfig. A committed non-loopback+ // bind resolves loopback-only, so the exposure interlock passes and the+ // server boots. The SAME value supplied per-machine via OK_BIND resolves+ // non-loopback (loopbackOnly false, no consent) -> the interlock still+ // refuses. That path is the real exposing host and must stay loud.+ writeWorkspaceConfig('server:\n bind:\n - 0.0.0.0\n');+ const { config } = loadConfig(testDir);++ const committedRuntime = resolveServerRuntimeConfig(config);+ expect(committedRuntime.bind).toEqual(['127.0.0.1']);+ expect(committedRuntime.loopbackOnly).toBe(true);+ // The interlock decision itself, not just its input: no consent required.+ expect(requiresExternalConsent(committedRuntime)).toBe(false);++ const envLayer = resolveEnvConfigLayer({ OK_BIND: '0.0.0.0' });+ const envConfig = applyConfigOverlay(config, envLayer.layer) as typeof config;+ const envRuntime = resolveServerRuntimeConfig(envConfig);+ expect(envRuntime.bind).toEqual(['0.0.0.0']);+ expect(envRuntime.loopbackOnly).toBe(false);+ expect(envRuntime.allowExternal).toBe(false);+ // The interlock still refuses: consent is required and not granted, so the+ // exposing OK_BIND host stays loud (asserts the predicate, not just inputs).+ expect(requiresExternalConsent(envRuntime)).toBe(true);});test('schema-invalid project-local file throws loud with the file named', () => {diff --git a/packages/cli/src/config/loader.ts b/packages/cli/src/config/loader.tsindex 78d16b178..1462c14f9 100644--- a/packages/cli/src/config/loader.ts+++ b/packages/cli/src/config/loader.ts@@ -36,8 +36,10 @@ import {type ConfigDiagnostic,type ConfigIssue,type ConfigValidationError,+ detectCommittedProjectLocalKeys,detectRemovedKeys,humanFormat,+ type IgnoredCommittedKey,locateIssue,mergeLayered,stripRemovedKeys,@@ -65,6 +67,15 @@ export interface LoadConfigResult {* without saying so reads as a silent data loss.*/sidelined: Array<{ from: string; to: string }>;+ /**+ * Project-local settings found in the committed `.ok/config.yml`, where+ * `mergeLayered` silently drops them. Surfaced so the caller can warn once+ * per invocation that the committed value is ignored and name the per-machine+ * fix (`.ok/local/config.yml` / `OK_*`). The canonical offender is a+ * committed `server.bind` that would otherwise refuse to boot for cloners.+ * Empty when the committed layer sets nothing out of scope.+ */+ ignoredCommittedKeys: IgnoredCommittedKey[];}/** Short TTL for per-cwd config resolution in long-lived MCP sessions. */@@ -179,6 +190,7 @@ export function loadConfig(cwd?: string): LoadConfigResult {const sources: string[] = [];const diagnostics: ConfigDiagnostic[] = [];const sidelined: Array<{ from: string; to: string }> = [];+ const ignoredCommittedKeys: IgnoredCommittedKey[] = [];// Layer 1: user-global config — go through readConfigSafely so removed keys// are stripped-and-reported and a genuinely broken file is sidelined; either@@ -206,7 +218,11 @@ export function loadConfig(cwd?: string): LoadConfigResult {// key) resolves to its schema default — never the cloned value.// A file that could not be read/parsed degrades to `{}` but says so via// `diagnostics`.- const loadRawLayer = (filePath: string): Record<string, unknown> => {+ // `isCommittedLayer` is true only for the shared project file. Project-local+ // keys belong in the gitignored local layer, so a project-local value there+ // (or in the user layer) is expected — only a committed one is the ignored+ // misconfiguration this reports.+ const loadRawLayer = (filePath: string, isCommittedLayer = false): Record<string, unknown> => {const file = loadYamlFile(filePath);if (file.diagnostic !== undefined) {diagnostics.push(file.diagnostic);@@ -220,11 +236,22 @@ export function loadConfig(cwd?: string): LoadConfigResult {});diagnostics.push(...removedKeyDiagnostics);sources.push(filePath);- return removedKeyDiagnostics.length > 0 ? stripRemovedKeys(file.value) : file.value;+ const value = removedKeyDiagnostics.length > 0 ? stripRemovedKeys(file.value) : file.value;+ if (isCommittedLayer) {+ ignoredCommittedKeys.push(+ ...detectCommittedProjectLocalKeys({+ value,+ file: file.path,+ source: file.source,+ doc: file.doc,+ }),+ );+ }+ return value;};const projectPath = resolve(workingDir, OK_DIR, CONFIG_FILENAME);- const projectRaw = loadRawLayer(projectPath);+ const projectRaw = loadRawLayer(projectPath, true);const localRaw = loadRawLayer(resolveConfigPath('project-local', workingDir));// Scope-aware merge over the raw layers, then ONE parse fills defaults for@@ -242,7 +269,7 @@ export function loadConfig(cwd?: string): LoadConfigResult {const error: ConfigValidationError = { code: 'SCHEMA_INVALID', issues };throw new Error(humanFormat(error));}- return { config: result.data, sources, diagnostics, sidelined };+ return { config: result.data, sources, diagnostics, sidelined, ignoredCommittedKeys };}interface CreateProjectConfigResolverOptions {diff --git a/packages/core/src/config/committed-scope-diagnostics.test.ts b/packages/core/src/config/committed-scope-diagnostics.test.tsnew file mode 100644index 000000000..d6501b698--- /dev/null+++ b/packages/core/src/config/committed-scope-diagnostics.test.ts@@ -0,0 +1,134 @@+import { describe, expect, test } from 'vitest';+import { parseDocument } from 'yaml';+import {+ detectCommittedProjectLocalKeys,+ formatIgnoredCommittedKey,+} from './committed-scope-diagnostics.ts';++/** Dotted paths of the findings, sorted for order-independent assertions. */+function paths(value: unknown): string[] {+ return detectCommittedProjectLocalKeys({ value })+ .map((f) => f.path.join('.'))+ .sort();+}++describe('detectCommittedProjectLocalKeys', () => {+ test('flags a committed server.bind — the clone-breaking case — with the OK_BIND fix', () => {+ const findings = detectCommittedProjectLocalKeys({ value: { server: { bind: ['0.0.0.0'] } } });+ expect(findings).toHaveLength(1);+ expect(findings[0]?.path).toEqual(['server', 'bind']);+ expect(findings[0]?.envVar).toBe('OK_BIND');+ });++ test('flags a committed loopback bind too — placement, not value, is the fault', () => {+ // The whole point is that a committed bind is IGNORED regardless of value;+ // a loopback one is harmless but still silently dropped, so name it.+ expect(paths({ server: { bind: ['127.0.0.1'] } })).toEqual(['server.bind']);+ });++ test('flags committed exposure consent (server.allowExternal) with its env fix', () => {+ const findings = detectCommittedProjectLocalKeys({+ value: { server: { allowExternal: true } },+ });+ expect(findings).toHaveLength(1);+ expect(findings[0]?.path).toEqual(['server', 'allowExternal']);+ expect(findings[0]?.envVar).toBe('OK_ALLOW_EXTERNAL');+ });++ test('flags a project-local leaf with no env surface, and omits envVar', () => {+ const findings = detectCommittedProjectLocalKeys({ value: { autoSync: { mode: 'full' } } });+ expect(findings).toHaveLength(1);+ expect(findings[0]?.path).toEqual(['autoSync', 'mode']);+ expect(findings[0]?.envVar).toBeUndefined();+ });++ test('flags nested project-local leaves (search + sidebar)', () => {+ expect(+ paths({+ search: { semantic: { enabled: true } },+ appearance: { sidebar: { showHiddenFiles: true } },+ }),+ ).toEqual(['appearance.sidebar.showHiddenFiles', 'search.semantic.enabled']);+ });++ test('does NOT flag project-scope keys (the committed, shared shape)', () => {+ expect(+ paths({+ content: { dir: 'docs' },+ server: { port: 8080, externalUrl: 'https://kb.example.com' },+ }),+ ).toEqual([]);+ });++ test('does NOT flag user-scope keys', () => {+ expect(paths({ slides: { enabled: true } })).toEqual([]);+ });++ test('ignores loose/unknown keys the schema does not register', () => {+ expect(paths({ chrome: { totallyUnknown: 42 }, notAConfigKey: true })).toEqual([]);+ });++ test('separates ignored project-local keys from in-scope siblings in one pass', () => {+ // A realistic mixed committed file: a shared content.dir + port (fine)+ // alongside a bind + allowExternal that leaked in (ignored).+ expect(+ paths({+ content: { dir: 'docs' },+ server: { port: 8080, bind: ['0.0.0.0'], allowExternal: true },+ }),+ ).toEqual(['server.allowExternal', 'server.bind']);+ });++ test('non-object / empty input yields no findings', () => {+ expect(detectCommittedProjectLocalKeys({ value: null })).toEqual([]);+ expect(detectCommittedProjectLocalKeys({ value: 'nope' })).toEqual([]);+ expect(detectCommittedProjectLocalKeys({ value: [] })).toEqual([]);+ expect(detectCommittedProjectLocalKeys({ value: {} })).toEqual([]);+ });++ test('attaches source location when doc + source supplied', () => {+ const source = 'server:\n bind:\n - 0.0.0.0\n';+ const doc = parseDocument(source);+ const findings = detectCommittedProjectLocalKeys({+ value: doc.toJSON(),+ file: '/tmp/.ok/config.yml',+ source,+ doc,+ });+ expect(findings).toHaveLength(1);+ expect(findings[0]?.source?.file).toBe('/tmp/.ok/config.yml');+ expect(findings[0]?.source?.line).toBeGreaterThanOrEqual(1);+ });+});++describe('formatIgnoredCommittedKey', () => {+ test('names the key, says it is ignored, and points at the per-machine fix + env var', () => {+ const msg = formatIgnoredCommittedKey({ path: ['server', 'bind'], envVar: 'OK_BIND' });+ expect(msg).toContain('server.bind');+ expect(msg).toContain('ignored');+ expect(msg).toContain('.ok/local/config.yml');+ expect(msg).toContain('OK_BIND');+ });++ test('omits the env hint when the leaf has no env surface', () => {+ const msg = formatIgnoredCommittedKey({ path: ['autoSync', 'mode'] });+ expect(msg).toContain('autoSync.mode');+ expect(msg).toContain('.ok/local/config.yml');+ expect(msg).not.toContain('OK_');+ });++ test('prefixes file:line:column when the finding was source-located', () => {+ const msg = formatIgnoredCommittedKey({+ path: ['server', 'bind'],+ envVar: 'OK_BIND',+ source: { file: '/repo/.ok/config.yml', line: 3, column: 5 },+ });+ expect(msg.startsWith('/repo/.ok/config.yml:3:5: ')).toBe(true);+ expect(msg).toContain('server.bind');+ });++ test('omits the location prefix when no source is attached', () => {+ const msg = formatIgnoredCommittedKey({ path: ['server', 'bind'], envVar: 'OK_BIND' });+ expect(msg.startsWith('server.bind')).toBe(true);+ });+});diff --git a/packages/core/src/config/committed-scope-diagnostics.ts b/packages/core/src/config/committed-scope-diagnostics.tsnew file mode 100644index 000000000..d69814093--- /dev/null+++ b/packages/core/src/config/committed-scope-diagnostics.ts@@ -0,0 +1,117 @@+/**+ * Detect project-local settings that were committed to the shared project+ * layer (`.ok/config.yml`), where they are silently ignored.+ *+ * `mergeLayered` skips the committed project layer for every project-local leaf+ * (consent, per-machine listener + workflow knobs), so a value written there+ * never reaches the running server — it resolves to the schema default or the+ * user layer instead. That skip is a security + clone-safety feature (a+ * committed `server.allowExternal` or `server.bind` can't arm exposure or break+ * a teammate's local run), but it is also silent: the author believes the+ * committed value took effect. This detector turns that silent no-op into a+ * loud, source-located diagnostic so the value gets moved to where it works.+ *+ * The classic offender is `server.bind`: committing a non-loopback bind so one+ * machine can serve remotely would otherwise refuse to boot for every teammate+ * who clones the repo and runs it locally (the exposure interlock needs+ * per-machine `allowExternal` consent that is never committed). Now a committed+ * bind is inert AND named at start, with the OK_BIND / `.ok/local` fix.+ *+ * Pure introspection — no I/O. Keys off the field registry's `scope` metadata,+ * exactly as `mergeLayered` does, so the two can never disagree about which+ * leaves are project-local.+ */++import type { Document } from 'yaml';+import { mechanicalEnvName, RECOGNIZED_ENV_VARS } from './env-layer.ts';+import type { ConfigIssueSource } from './errors.ts';+import { ConfigSchema } from './schema.ts';+import { getLeafFieldMeta } from './schema-leaf.ts';+import { locateIssue } from './source-locator.ts';++/** A project-local leaf found in the committed project layer, where it is ignored. */+export interface IgnoredCommittedKey {+ /** Dotted-path segments of the ignored leaf, e.g. `['server', 'bind']`. */+ path: string[];+ /**+ * The `OK_*` environment variable that sets this leaf per-machine, when one+ * is ratified (e.g. `OK_BIND`). Absent for project-local leaves with no env+ * surface — those move to `.ok/local/config.yml` only.+ */+ envVar?: string;+ /** Source location in the committed file, when `file`/`source`/`doc` are supplied. */+ source?: ConfigIssueSource;+}++export interface DetectCommittedProjectLocalKeysInput {+ /** Raw committed project-layer value (pre-merge, pre-schema — the YAML projection). */+ value: unknown;+ /** Absolute file path, for source-located findings. Omit for value-only mode. */+ file?: string | null;+ /** Raw file source, for source-located findings. */+ source?: string | null;+ /** yaml@2 Document AST, for source-located findings. */+ doc?: Document | null;+}++function isPlainObject(value: unknown): value is Record<string, unknown> {+ return typeof value === 'object' && value !== null && !Array.isArray(value);+}++/**+ * Walk a raw committed project config and return one finding per project-local+ * leaf present in it. A registered leaf stops the descent (even an object /+ * array leaf like `server.bind`); an unregistered container recurses; an+ * unregistered scalar (a loose key the schema does not know) is skipped. Each+ * finding is source-located when `file`, `source`, and `doc` are supplied.+ */+export function detectCommittedProjectLocalKeys(+ input: DetectCommittedProjectLocalKeysInput,+): IgnoredCommittedKey[] {+ const { value, file, source, doc } = input;+ const findings: IgnoredCommittedKey[] = [];++ const walk = (node: unknown, path: string[]): void => {+ if (path.length > 0) {+ const meta = getLeafFieldMeta(ConfigSchema, path);+ if (meta !== undefined) {+ // A registered leaf: this is the scope-bearing node, so stop here.+ if (meta.scope === 'project-local') {+ const envVar = mechanicalEnvName(path);+ let located: ConfigIssueSource | undefined;+ if (doc != null && source != null && file != null) {+ located = locateIssue({ file, source, doc, path });+ }+ findings.push({+ path: [...path],+ ...(RECOGNIZED_ENV_VARS.has(envVar) ? { envVar } : {}),+ ...(located !== undefined ? { source: located } : {}),+ });+ }+ return;+ }+ }+ // Not a registered leaf: recurse into containers, ignore loose scalars.+ if (isPlainObject(node)) {+ for (const [key, child] of Object.entries(node)) walk(child, [...path, key]);+ }+ };++ walk(value, []);+ return findings;+}++/**+ * Render a start-time warning for a project-local key found in committed+ * config. Prefixes the `file:line:column` of the offending value when it was+ * source-located (the IDE/CLI convention, matching `humanFormat(REMOVED_KEY)`),+ * then names the key, states it is ignored, and points at the per-machine fix+ * (`.ok/local/config.yml`, plus the `OK_*` env var when one exists).+ */+export function formatIgnoredCommittedKey(key: IgnoredCommittedKey): string {+ const dotted = key.path.join('.');+ const location =+ key.source !== undefined ? `${key.source.file}:${key.source.line}:${key.source.column}: ` : '';+ const envHint = key.envVar !== undefined ? `, or set ${key.envVar} on this host` : '';+ return `${location}${dotted} is a per-machine (project-local) setting; the value committed in .ok/config.yml is ignored. Set it in .ok/local/config.yml (this machine only)${envHint}.`;+}diff --git a/packages/core/src/config/field-registry.test.ts b/packages/core/src/config/field-registry.test.tsindex ce3c1f24f..66871404f 100644--- a/packages/core/src/config/field-registry.test.ts+++ b/packages/core/src/config/field-registry.test.ts@@ -267,11 +267,10 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)''lossCapture.maxBytes','remote.port','remote.url',- // `server.{port,bind,externalUrl}` are the committed, reviewed shape of- // this knowledge base's server — project scope, like the `remote.*`- // keys they supersede. Their consent/workflow siblings are- // project-local (below).- 'server.bind',+ // `server.{port,externalUrl}` are the committed, reviewed shape of this+ // knowledge base's server — project scope, like the `remote.*` keys they+ // supersede. `server.bind` and the rest of the listener's consent/workflow+ // siblings are project-local (below).'server.externalUrl','server.port','server.publicUrl',@@ -325,9 +324,12 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'// `server.allowExternal` is exposure CONSENT — the `terminal.enabled`// posture: never inherited via clone, sync, or share, so a committed// `allowExternal: true` can never expose a future cloner's machine.+ // `server.bind` is per-machine for the same clone-safety reason: a+ // committed non-loopback bind must never break a teammate's local run.// `server.{openBrowser,idleShutdown}` are personal workflow, like the// sidebar toggles.'server.allowExternal',+ 'server.bind','server.idleShutdown','server.openBrowser','terminal.enabled',diff --git a/packages/core/src/config/merge-layered.test.ts b/packages/core/src/config/merge-layered.test.tsindex 7b83ef797..a1d039a52 100644--- a/packages/core/src/config/merge-layered.test.ts+++ b/packages/core/src/config/merge-layered.test.ts@@ -227,15 +227,47 @@ describe('mergeLayered — scope-aware leaf short-circuits', () => {expect(merged.terminal?.enabled).toBeNull();});- test("scope: 'project' (server.bind) returns project, ignoring a project-local override attempt", () => {+ test("scope: 'project-local' (server.bind) ignores a committed project value; the project-local layer wins", () => {+ // server.bind is per-machine: a committed bind (one machine exposing the+ // server) must never reach a teammate's local run — only this machine's+ // gitignored project-local layer sets it. Same posture as allowExternal.const user = makeConfig({});- const project = makeConfig({ server: { bind: ['127.0.0.1'] } });- const projectLocal = makeConfig({ server: { bind: ['0.0.0.0'] } });+ const project = makeConfig({ server: { bind: ['0.0.0.0'] } });+ const projectLocal = makeConfig({ server: { bind: ['192.168.1.5'] } });++ const merged = mergeLayered(user, project, projectLocal);+ expect(merged.server?.bind).toEqual(['192.168.1.5']);+ });++ test('a clone with a committed non-loopback bind but no project-local layer falls to the loopback default', () => {+ // The exact footgun: a repo commits `server.bind: [0.0.0.0]` so one box+ // serves remotely; every teammate who clones and runs locally must still+ // bind loopback (and boot), never inherit the committed non-loopback value+ // (which would trip the exposure interlock they never consented to).+ const user = makeConfig({});+ const project = makeConfig({ server: { bind: ['0.0.0.0'] } });+ const projectLocal = makeConfig({});const merged = mergeLayered(user, project, projectLocal);expect(merged.server?.bind).toEqual(['127.0.0.1']);});+ test('RAW-layer path: a committed bind is skipped; a user-global bind is honored as a personal default', () => {+ // The loader's inputs are RAW (un-parsed) partials. A committed project+ // `bind` surfaces no `bind` from the merge (→ the final parse fills the+ // loopback default), while a user-global bind still wins as a cross-project+ // personal default (the project-local fallback is user, never project).+ const committed = mergeLayered({}, { server: { bind: ['0.0.0.0'] } }, {});+ expect((committed.server as { bind?: string[] } | undefined)?.bind).toBeUndefined();++ const userDefault = mergeLayered(+ { server: { bind: ['::1'] } },+ { server: { bind: ['0.0.0.0'] } },+ {},+ );+ expect((userDefault.server as { bind?: string[] } | undefined)?.bind).toEqual(['::1']);+ });+test("scope: 'project-local' (server.allowExternal) ignores a committed project value", () => {// Exposure consent has the terminal.enabled posture: a committed// `allowExternal: true` must never grant consent on a cloner's machine —diff --git a/packages/core/src/config/schema.test.ts b/packages/core/src/config/schema.test.tsindex 482feb9f9..76310c8ac 100644--- a/packages/core/src/config/schema.test.ts+++ b/packages/core/src/config/schema.test.ts@@ -7,6 +7,7 @@ import {isValidAttachmentFolderPath,normalizeAttachmentFolderPath,} from './schema.ts';+import { getLeafFieldMeta } from './schema-leaf.ts';describe('checkEmbeddingsBaseUrl', () => {test('accepts https endpoints', () => {@@ -420,6 +421,15 @@ describe('server.* (canonical listener/exposure surface)', () => {expect(ConfigSchema.safeParse({ server: { bind: '127.0.0.1' } }).success).toBe(false);});+ test('bind is registered project-local so a committed value is ignored (clone-safety)', () => {+ // Per-machine listener knob: a committed non-loopback bind must never break+ // a teammate who clones and runs locally, so it lives in .ok/local, not the+ // shared .ok/config.yml. mergeLayered keys off this scope to drop it.+ const meta = getLeafFieldMeta(ConfigSchema, ['server', 'bind']);+ expect(meta?.scope).toBe('project-local');+ expect(meta?.defaultScope).toBe('project-local');+ });+test('the deprecated publicUrl spelling still validates with the same URL shape', () => {expect(ConfigSchema.parse({ server: { publicUrl: 'https://kb.example.com' } }).server.publicUrl,diff --git a/packages/core/src/config/schema.ts b/packages/core/src/config/schema.tsindex 015ab597f..56eb3372a 100644--- a/packages/core/src/config/schema.ts+++ b/packages/core/src/config/schema.ts@@ -1245,13 +1245,22 @@ export const ConfigSchema = z.looseObject({// target that drifts from the values that actually matter; "hosted" is// just what a non-loopback bind, a public URL, and consent look like.//- // Scopes: `port` / `bind` / `externalUrl` are PROJECT — the committed,- // reviewed shape of this knowledge base's server. `openBrowser` /- // `idleShutdown` are PROJECT-LOCAL — personal workflow, like the sidebar- // toggles. `allowExternal` is PROJECT-LOCAL consent, the same posture as- // `terminal.enabled`: consent never travels via git, clone, or share, so a- // committed `allowExternal: true` can never expose a future cloner's- // machine (containers consent via environment instead).+ // Scopes: `port` / `externalUrl` are PROJECT — the committed, reviewed shape+ // of this knowledge base's server. `bind` is PROJECT-LOCAL, alongside+ // `allowExternal` / `openBrowser` / `idleShutdown`: it is a per-machine+ // listener knob, and a committed non-loopback `bind` would otherwise refuse to+ // boot for every teammate who clones the repo and runs it locally — the+ // exposure interlock needs per-machine `allowExternal` consent, which is never+ // committed. Keeping `bind` project-local makes a committed value inert (the+ // loader's scope-aware merge skips the committed layer), so one machine+ // exposing the server can't break local clones for the rest of the team; the+ // exposing host sets it per-machine via `OK_BIND` / `--bind` or+ // `.ok/local/config.yml`. `allowExternal` is PROJECT-LOCAL consent, the same+ // posture as `terminal.enabled`: consent never travels via git, clone, or+ // share, so a committed `allowExternal: true` can never expose a future+ // cloner's machine (containers consent via environment instead). `openBrowser`+ // / `idleShutdown` are PROJECT-LOCAL personal workflow, like the sidebar+ // toggles.//// `agentSettable: false` on every leaf, same reasoning as `remote.*`: an// agent must never widen its own network exposure.@@ -1282,12 +1291,12 @@ export const ConfigSchema = z.looseObject({.array(z.string().min(1)).min(1).register(fieldRegistry, {- scope: 'project',+ scope: 'project-local',agentSettable: false,reload: 'boot',- defaultScope: 'project',+ defaultScope: 'project-local',description:- 'Addresses the server binds, e.g. [127.0.0.1] or [0.0.0.0]. Default loopback-only ([127.0.0.1]): nothing off this machine can connect. A non-loopback bind additionally requires the server.allowExternal consent interlock. Lists replace, never merge. Read at server start; changing it requires a restart.',+ 'Addresses the server binds, e.g. [127.0.0.1] or [0.0.0.0]. Default loopback-only ([127.0.0.1]): nothing off this machine can connect. A non-loopback bind additionally requires the server.allowExternal consent interlock. Per-machine (project-local): a value committed to .ok/config.yml is ignored, so one machine exposing the server can never break local clones for the rest of the team — the exposing host sets it via OK_BIND, --bind, or .ok/local/config.yml. Lists replace, never merge. Read at server start; changing it requires a restart.',}).default([...DEFAULT_SERVER_BIND]),externalUrl: zdiff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex e68fd34c2..bf9e41315 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -166,6 +166,12 @@ export {type OkignoreDocProvider,type OkignoreUnsubscribe,} from './config/bind-okignore-doc.ts';+export {+ type DetectCommittedProjectLocalKeysInput,+ detectCommittedProjectLocalKeys,+ formatIgnoredCommittedKey,+ type IgnoredCommittedKey,+} from './config/committed-scope-diagnostics.ts';export {applyConfigOverlay,type EnvConfigLayer,