Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-8617: Move remaining lint writes to native Hono (#4441)

omar-inkeep2c58a473fb60
diff --git a/.changeset/smart-flies-hug.md b/.changeset/smart-flies-hug.md
new file mode 100644
index 000000000..cce5fd0fa
--- /dev/null
+++ b/.changeset/smart-flies-hug.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+The frontmatter schema editor now rejects `__proto__` as a field name, rename target, or parent path with a `400` validation error. Other property names that shadow `Object.prototype` members are treated as ordinary keys.
diff --git a/docs/content/remote-control/authentication.mdx b/docs/content/remote-control/authentication.mdx
index fbd1b3a65..4de22f981 100644
--- a/docs/content/remote-control/authentication.mdx
+++ b/docs/content/remote-control/authentication.mdx
@@ -263,7 +263,7 @@ Common symptoms and their fixes:
- **The editor loads but never syncs, and the browser console shows a `ws://` "Mixed Content" error.** The proxy terminates TLS but reports the request to the server as plain HTTP, so the server hands the editor an insecure `ws://` socket. Make the proxy forward `X-Forwarded-Proto: https` (Caddy: `header_up X-Forwarded-Proto https`).
- **Every request returns `403` with a problem-JSON `"title"` of `Host header not allowed.`.** The request `Host` does not match `OK_EXTERNAL_URL`. Configure the proxy to preserve the client's `Host`. For Caddy, use `header_up Host {host}`. Set `OK_EXTERNAL_URL` to the public origin. See the full [proxy rules](/docs/remote-control/methods/docker#rules-for-anything-in-front-of-the-server).
-- **Every request returns `403` with a problem-JSON `"title"` of `Proxied request refused: ...`.** The proxy stamps forwarding headers (`X-Forwarded-For`, `Forwarded`, `X-Forwarded-Proto`, ...) but the server has not consented to external exposure. Set BOTH `OK_EXTERNAL_URL` to the public origin and `OK_ALLOW_EXTERNAL=1` — tolerance for forwarding headers requires the pair, and `OK_EXTERNAL_URL` alone is not enough. `OK_ALLOW_EXTERNAL` consents to exposing a server with no authentication of its own, so only set it behind an authenticating edge.
+- **A request returns `403` with a problem-JSON `"title"` of `Proxied request refused: ...`.** The request reached the server through a proxy that stamps forwarding headers (`X-Forwarded-For`, `Forwarded`, `X-Forwarded-Proto`, ...), but the server has not consented to external exposure. Set BOTH `OK_EXTERNAL_URL` to the public origin and `OK_ALLOW_EXTERNAL=1`; tolerance for forwarding headers requires the pair, and `OK_EXTERNAL_URL` alone is not enough. `OK_ALLOW_EXTERNAL` consents to exposing a server with no authentication of its own, so only set it behind an authenticating edge.
- **The browser login returns to the login page.** oauth2-proxy is rejecting the post-login redirect because the domain is not allowed. Add the public domain to `OAUTH2_PROXY_WHITELIST_DOMAINS`.
- **An agent gets an HTML login page back from `/mcp`.** The `/mcp` path is behind the browser login instead of a token. Route `/mcp` around the login proxy and gate it with a token, or if you use an MCP-OAuth edge, confirm the client supports it (see [Connect remote agents](/docs/remote-control/connecting-agents)).
- **`/mcp` hangs or times out.** A proxy is buffering the streamed response. Turn off buffering for `/mcp`. In nginx, set `proxy_buffering` to `off`. For oauth2-proxy, set `FLUSH_INTERVAL=100ms`. Caddy streams by default.
diff --git a/packages/app/src/editor/lint-config-client.test.ts b/packages/app/src/editor/lint-config-client.test.ts
index 971c32230..b442c62dd 100644
--- a/packages/app/src/editor/lint-config-client.test.ts
+++ b/packages/app/src/editor/lint-config-client.test.ts
@@ -1,5 +1,16 @@
+import { DEFAULT_LINTER_CONFIG } from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { fixLintDoc, LINT_FIX_TIMEOUT_MS } from './lint-config-client.ts';
+import {
+ createEmptyFrontmatterSchema,
+ deleteFrontmatterSchema,
+ fixLintDoc,
+ LINT_FIX_TIMEOUT_MS,
+ removeFrontmatterSchemaField,
+ renameFrontmatterSchemaField,
+ subscribeToLintConfigChanged,
+ writeFrontmatterSchemaField,
+ writeMarkdownlintRule,
+} from './lint-config-client.ts';
type FetchFn = typeof globalThis.fetch;
@@ -14,6 +25,181 @@ beforeEach(() => {
});
afterEach(() => {
globalThis.fetch = originalFetch;
+ vi.unstubAllGlobals();
+});
+
+const CONFIG_RESPONSE = {
+ effective: DEFAULT_LINTER_CONFIG,
+ configFile: null,
+ configProblems: [],
+};
+
+describe('writeMarkdownlintRule', () => {
+ it('posts the rule update and returns the schema-parsed configuration', async () => {
+ const calls: Array<{ input: string | URL | Request; init?: RequestInit }> = [];
+ stubFetch(async (input, init) => {
+ calls.push({ input, init });
+ return new Response(JSON.stringify(CONFIG_RESPONSE), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+ });
+
+ const outcome = await writeMarkdownlintRule('MD012', { maximum: 3 });
+
+ expect(outcome).toEqual({ ok: true, response: CONFIG_RESPONSE });
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.input).toBe('/api/lint/markdownlint-config');
+ expect(calls[0]?.init).toMatchObject({
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ ruleId: 'MD012', value: { maximum: 3 } }),
+ });
+ });
+
+ it.each([
+ ['malformed JSON', new Response('{', { status: 200 })],
+ ['a schema-invalid body', new Response(JSON.stringify({ unexpected: true }), { status: 200 })],
+ ])('rejects a successful response with %s', async (_label, response) => {
+ stubFetch(async () => response.clone());
+ await expect(writeMarkdownlintRule('MD012', false)).resolves.toEqual({
+ ok: false,
+ errorDetail: null,
+ });
+ });
+
+ it('preserves a problem title from a rejected write', async () => {
+ stubFetch(
+ async () =>
+ new Response(JSON.stringify({ title: 'Config cannot be rewritten.' }), { status: 409 }),
+ );
+ await expect(writeMarkdownlintRule('MD012', false)).resolves.toEqual({
+ ok: false,
+ errorDetail: 'Config cannot be rewritten.',
+ });
+ });
+
+ it('returns a title-less failure when the request does not reach the server', async () => {
+ stubFetch(async () => {
+ throw new TypeError('fetch failed');
+ });
+ await expect(writeMarkdownlintRule('MD012', false)).resolves.toEqual({
+ ok: false,
+ errorDetail: null,
+ });
+ });
+});
+
+describe('frontmatter schema writes', () => {
+ it('serializes every operation and emits the local event only for successful create and delete', async () => {
+ const calls: Array<{ input: string | URL | Request; init?: RequestInit }> = [];
+ stubFetch(async (input, init) => {
+ calls.push({ input, init });
+ return new Response(JSON.stringify(CONFIG_RESPONSE), { status: 200 });
+ });
+ vi.stubGlobal('window', new EventTarget());
+ let eventCount = 0;
+ const unsubscribe = subscribeToLintConfigChanged(() => {
+ eventCount += 1;
+ });
+ try {
+ await expect(createEmptyFrontmatterSchema('.ok/schemas/doc.schema.json')).resolves.toEqual({
+ ok: true,
+ response: CONFIG_RESPONSE,
+ });
+ await expect(
+ writeFrontmatterSchemaField(
+ '.ok/schemas/doc.schema.json',
+ 'name',
+ { type: 'string', required: true },
+ ['items', { items: true }],
+ ),
+ ).resolves.toEqual({ ok: true, response: CONFIG_RESPONSE });
+ await expect(
+ removeFrontmatterSchemaField('.ok/schemas/doc.schema.json', 'name', ['items']),
+ ).resolves.toEqual({ ok: true, response: CONFIG_RESPONSE });
+ await expect(
+ renameFrontmatterSchemaField('.ok/schemas/doc.schema.json', 'name', 'title'),
+ ).resolves.toEqual({ ok: true, response: CONFIG_RESPONSE });
+ await expect(deleteFrontmatterSchema('.ok/schemas/doc.schema.json')).resolves.toEqual({
+ ok: true,
+ response: CONFIG_RESPONSE,
+ });
+
+ expect(eventCount).toBe(2);
+ expect(calls.map((call) => call.input)).toEqual(
+ Array.from({ length: 5 }, () => '/api/lint/frontmatter-schema'),
+ );
+ expect(calls.map((call) => call.init?.method)).toEqual(
+ Array.from({ length: 5 }, () => 'POST'),
+ );
+ expect(calls.map((call) => JSON.parse(String(call.init?.body)))).toEqual([
+ { file: '.ok/schemas/doc.schema.json' },
+ {
+ file: '.ok/schemas/doc.schema.json',
+ field: 'name',
+ constraint: { type: 'string', required: true },
+ parentPath: ['items', { items: true }],
+ },
+ {
+ file: '.ok/schemas/doc.schema.json',
+ field: 'name',
+ removeField: true,
+ parentPath: ['items'],
+ },
+ { file: '.ok/schemas/doc.schema.json', field: 'name', renameTo: 'title' },
+ { file: '.ok/schemas/doc.schema.json', delete: true },
+ ]);
+ } finally {
+ unsubscribe();
+ }
+ });
+
+ it('does not emit a local event when create or delete fails', async () => {
+ stubFetch(
+ async () =>
+ new Response(JSON.stringify({ title: 'Schema cannot be rewritten.' }), { status: 409 }),
+ );
+ vi.stubGlobal('window', new EventTarget());
+ let eventCount = 0;
+ const unsubscribe = subscribeToLintConfigChanged(() => {
+ eventCount += 1;
+ });
+ try {
+ await expect(createEmptyFrontmatterSchema('.ok/schemas/doc.schema.json')).resolves.toEqual({
+ ok: false,
+ errorDetail: 'Schema cannot be rewritten.',
+ });
+ await expect(deleteFrontmatterSchema('.ok/schemas/doc.schema.json')).resolves.toEqual({
+ ok: false,
+ errorDetail: 'Schema cannot be rewritten.',
+ });
+ expect(eventCount).toBe(0);
+ } finally {
+ unsubscribe();
+ }
+ });
+
+ it.each([
+ ['malformed JSON', new Response('{', { status: 200 })],
+ ['a schema-invalid body', new Response(JSON.stringify({ unexpected: true }), { status: 200 })],
+ ])('rejects a successful response with %s', async (_label, response) => {
+ stubFetch(async () => response.clone());
+ await expect(createEmptyFrontmatterSchema('.ok/schemas/doc.schema.json')).resolves.toEqual({
+ ok: false,
+ errorDetail: null,
+ });
+ });
+
+ it('returns a title-less failure when the request does not reach the server', async () => {
+ stubFetch(async () => {
+ throw new TypeError('fetch failed');
+ });
+ await expect(createEmptyFrontmatterSchema('.ok/schemas/doc.schema.json')).resolves.toEqual({
+ ok: false,
+ errorDetail: null,
+ });
+ });
});
describe('fixLintDoc', () => {
@@ -138,4 +324,58 @@ describe('fixLintDoc', () => {
result: { file: 'doc-a', fixedCount: 2, diagnostics: [], errorCount: 0, warningCount: 0 },
});
});
+
+ it('preserves degraded success fields, nested fixes, and request serialization', async () => {
+ const calls: Array<{ input: string | URL | Request; init?: RequestInit }> = [];
+ const result = {
+ file: 'doc-a.md',
+ fixedCount: 0,
+ diagnostics: [
+ {
+ range: {
+ start: { line: 2, character: 0 },
+ end: { line: 2, character: 1 },
+ },
+ severity: 'warning',
+ source: 'markdownlint',
+ code: 'MD010',
+ message: 'Hard tabs',
+ fixes: [
+ {
+ range: {
+ start: { line: 2, character: 0 },
+ end: { line: 2, character: 1 },
+ },
+ newText: ' ',
+ },
+ ],
+ },
+ ],
+ errorCount: 0,
+ warningCount: 1,
+ ran: ['markdownlint', 'frontmatter'],
+ warnings: ['frontmatter config warning'],
+ diagnosticsArePreFix: true,
+ reLintFailure: {
+ reason: 'source-went-blind',
+ message: 'markdownlint became unavailable',
+ },
+ };
+ stubFetch(async (input, init) => {
+ calls.push({ input, init });
+ return Response.json(result);
+ });
+
+ const outcome = await fixLintDoc('doc-a');
+
+ expect(outcome).toEqual({ ok: true, result });
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.input).toBe('/api/lint/fix');
+ expect(calls[0]?.init).toMatchObject({
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ docName: 'doc-a' }),
+ });
+ expect(calls[0]?.init?.signal).toBeInstanceOf(AbortSignal);
+ });
});
diff --git a/packages/app/tests/integration/audit-config-epoch.test.ts b/packages/app/tests/integration/audit-config-epoch.test.ts
index 151556f44..97fa0ee04 100644
--- a/packages/app/tests/integration/audit-config-epoch.test.ts
+++ b/packages/app/tests/integration/audit-config-epoch.test.ts
@@ -18,8 +18,20 @@ import {
let server: TestServer;
+const SEED_CONFIG = [
+ 'contentRules:',
+ ' markdownlint:',
+ ' enabled: true',
+ ' frontmatter:',
+ ' enabled: true',
+ ' schemas:',
+ ' - appliesTo: "audit-epoch/**"',
+ ' file: ".ok/schemas/audit-epoch.schema.json"',
+ '',
+].join('\n');
+
beforeAll(async () => {
- server = await createTestServer({ markdownlintEnabled: true });
+ server = await createTestServer({ seedProjectConfigYml: SEED_CONFIG });
}, HARNESS_BOOT_TIMEOUT_MS);
afterAll(async () => {
@@ -49,8 +61,8 @@ function seedTabbedCorpus(folder: string): void {
}
}
-async function auditScope(): Promise<Response> {
- return fetch(api(`/api/audit?path=${SCOPE}`));
+async function auditScope(scope = SCOPE): Promise<Response> {
+ return fetch(api(`/api/audit?path=${scope}`));
}
function md010Count(body: unknown): number {
@@ -186,4 +198,117 @@ describe('GET /api/audit across a lint-config change', () => {
},
TEST_TIMEOUT_MS,
);
+
+ test(
+ 'an in-flight audit is superseded when a frontmatter schema write changes its results',
+ async () => {
+ const scope = `${SCOPE}/frontmatter`;
+ const folder = join(server.contentDir, scope);
+ const schemaPath = join(server.contentDir, '.ok', 'schemas', 'audit-epoch.schema.json');
+ seedTabbedCorpus(folder);
+ mkdirSync(join(server.contentDir, '.ok', 'schemas'), { recursive: true });
+ writeFileSync(schemaPath, JSON.stringify({ type: 'object', properties: {} }), 'utf-8');
+ try {
+ let firstSettled = false;
+ const first = auditScope(scope).then((res) => {
+ firstSettled = true;
+ return res;
+ });
+ const write = await fetch(api('/api/lint/frontmatter-schema'), {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ file: '.ok/schemas/audit-epoch.schema.json',
+ field: 'owner',
+ constraint: { type: 'string', required: true },
+ }),
+ });
+ expect(write.status).toBe(200);
+ expect(firstSettled).toBe(false);
+
+ const firstRes = await first;
+ expect(firstRes.status).toBe(409);
+ const problem = (await firstRes.json()) as { type?: string };
+ expect(problem.type).toBe('urn:ok:error:audit-superseded');
+
+ const after = await auditScope(scope);
+ expect(after.status).toBe(200);
+ const afterBody = ValidationAuditResponseSchema.parse(await after.json());
+ expect(
+ afterBody.files
+ .flatMap((file) => file.diagnostics)
+ .some(
+ (diagnostic) =>
+ diagnostic.source === 'frontmatter' &&
+ diagnostic.code === 'required' &&
+ diagnostic.message.includes('owner'),
+ ),
+ ).toBe(true);
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ rmSync(schemaPath, { force: true });
+ }
+ },
+ TEST_TIMEOUT_MS,
+ );
+
+ test(
+ 'refused and failed config writes do not supersede an in-flight audit',
+ async () => {
+ const scope = `${SCOPE}/rejected`;
+ const folder = join(server.contentDir, scope);
+ const executableConfig = join(server.contentDir, '.markdownlint.cjs');
+ const brokenConfig = join(server.contentDir, '.markdownlint.json');
+ const blockedSchemaParent = join(server.contentDir, 'blocked-schema-parent');
+ seedTabbedCorpus(folder);
+ try {
+ let firstSettled = false;
+ const first = auditScope(scope).then((res) => {
+ firstSettled = true;
+ return res;
+ });
+ writeFileSync(executableConfig, 'module.exports = { MD012: false };\n', 'utf-8');
+ const declined = await fetch(api('/api/lint/markdownlint-config'), {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ ruleId: 'MD012', value: false }),
+ });
+ expect(declined.status).toBe(409);
+
+ const refused = await fetch(api('/api/lint/frontmatter-schema'), {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ file: '../escape.schema.json' }),
+ });
+ expect(refused.status).toBe(409);
+
+ rmSync(executableConfig, { force: true });
+ mkdirSync(brokenConfig);
+ const failedMarkdown = await fetch(api('/api/lint/markdownlint-config'), {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ ruleId: 'MD012', value: false }),
+ });
+ expect(failedMarkdown.status).toBe(500);
+
+ writeFileSync(blockedSchemaParent, 'not a directory', 'utf-8');
+ const failedFrontmatter = await fetch(api('/api/lint/frontmatter-schema'), {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ file: 'blocked-schema-parent/failure.schema.json' }),
+ });
+ expect(failedFrontmatter.status).toBe(500);
+ expect(firstSettled).toBe(false);
+
+ const firstRes = await first;
+ expect(firstRes.status).toBe(200);
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ rmSync(executableConfig, { force: true });
+ rmSync(brokenConfig, { recursive: true, force: true });
+ rmSync(blockedSchemaParent, { force: true });
+ }
+ },
+ TEST_TIMEOUT_MS,
+ );
});
diff --git a/packages/app/tests/integration/cc1-broadcast.test.ts b/packages/app/tests/integration/cc1-broadcast.test.ts
index a22833520..d6a9f07c8 100644
--- a/packages/app/tests/integration/cc1-broadcast.test.ts
+++ b/packages/app/tests/integration/cc1-broadcast.test.ts
@@ -1,4 +1,4 @@
-import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { HocuspocusProvider } from '@hocuspocus/provider';
@@ -24,7 +24,10 @@ afterAll(async () => {
await server.cleanup();
});
-function connectSystemDoc(port: number): {
+function connectSystemDoc(
+ port: number,
+ channels: ReadonlySet<string> = new Set(['files']),
+): {
provider: HocuspocusProvider;
signals: CC1DerivedViewPayload[];
destroy: () => void;
@@ -44,7 +47,7 @@ function connectSystemDoc(port: number): {
return;
}
const result = CC1DerivedViewPayloadSchema.safeParse(raw);
- if (result.success && result.data.ch === 'files') {
+ if (result.success && channels.has(result.data.ch)) {
signals.push(result.data);
}
},
@@ -83,6 +86,88 @@ describe('CC1 broadcast — L1 integration', () => {
}
});
+ test('accepted lint config writes advance their intended system channels', async () => {
+ const { provider, signals, destroy } = connectSystemDoc(
+ server.port,
+ new Set(['files', 'lint-config']),
+ );
+ const markdownlintFile = join(server.contentDir, '.markdownlint.json');
+ const schemaFile = `.ok/schemas/cc1-${crypto.randomUUID()}.schema.json`;
+ const schemaPath = join(server.contentDir, schemaFile);
+ try {
+ await waitForSync(provider);
+ const lintBefore = Math.max(
+ 0,
+ ...signals.filter((signal) => signal.ch === 'lint-config').map((signal) => signal.seq),
+ );
+ const markdown = await fetch(`http://127.0.0.1:${server.port}/api/lint/markdownlint-config`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ ruleId: 'MD012', value: false }),
+ });
+ expect(markdown.status).toBe(200);
+ await pollUntil(
+ () => signals.some((signal) => signal.ch === 'lint-config' && signal.seq > lintBefore),
+ 5_000,
+ 20,
+ );
+
+ const filesBefore = Math.max(
+ 0,
+ ...signals.filter((signal) => signal.ch === 'files').map((signal) => signal.seq),
+ );
+ const nextLintBefore = Math.max(
+ 0,
+ ...signals.filter((signal) => signal.ch === 'lint-config').map((signal) => signal.seq),
+ );
+ const frontmatter = await fetch(
+ `http://127.0.0.1:${server.port}/api/lint/frontmatter-schema`,
+ {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ file: schemaFile }),
+ },
+ );
+ expect(frontmatter.status).toBe(200);
+ await pollUntil(
+ () =>
+ signals.some((signal) => signal.ch === 'files' && signal.seq > filesBefore) &&
+ signals.some((signal) => signal.ch === 'lint-config' && signal.seq > nextLintBefore),
+ 5_000,
+ 20,
+ );
+ expect(
+ Math.max(...signals.filter((signal) => signal.ch === 'files').map((signal) => signal.seq)),
+ ).toBeGreaterThan(filesBefore);
+ expect(
+ Math.max(
+ ...signals.filter((signal) => signal.ch === 'lint-config').map((signal) => signal.seq),
+ ),
+ ).toBeGreaterThan(nextLintBefore);
+
+ const filesBeforeCleanup = Math.max(
+ 0,
+ ...signals.filter((signal) => signal.ch === 'files').map((signal) => signal.seq),
+ );
+ const cleanup = await fetch(`http://127.0.0.1:${server.port}/api/lint/frontmatter-schema`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ file: schemaFile, delete: true }),
+ });
+ expect(cleanup.status).toBe(200);
+ await pollUntil(
+ () => signals.some((signal) => signal.ch === 'files' && signal.seq > filesBeforeCleanup),
+ 5_000,
+ 20,
+ 'the schema-removal files signal before provider teardown',
+ );
+ } finally {
+ rmSync(markdownlintFile, { force: true });
+ rmSync(schemaPath, { force: true });
+ destroy();
+ }
+ });
+
test('empty disk-created markdown file triggers ch:files and appears in documents', async () => {
const { provider, signals, destroy } = connectSystemDoc(server.port);
try {
@@ -90,13 +175,26 @@ describe('CC1 broadcast — L1 integration', () => {
await wait(100);
const docName = `cc1-empty-${crypto.randomUUID()}`;
+ const filesBefore = Math.max(0, ...signals.map((signal) => signal.seq));
writeFileSync(join(server.contentDir, `${docName}.md`), '', 'utf-8');
- await pollUntil(() => signals.length > 0, 5000, 50);
+ await pollUntil(
+ () => signals.some((signal) => signal.seq > filesBefore),
+ 5000,
+ 50,
+ 'a files signal caused after the empty-file write',
+ );
- const docsRes = await fetch(`http://127.0.0.1:${server.port}/api/documents`);
- const docsBody: { documents?: Array<{ docName: string }> } = await docsRes.json();
- expect(docsBody.documents?.some((doc) => doc.docName === docName)).toBe(true);
+ await pollUntil(
+ async () => {
+ const docsRes = await fetch(`http://127.0.0.1:${server.port}/api/documents`);
+ const docsBody: { documents?: Array<{ docName: string }> } = await docsRes.json();
+ return docsBody.documents?.some((doc) => doc.docName === docName) === true;
+ },
+ 5000,
+ 50,
+ 'the empty file to appear in documents',
+ );
} finally {
destroy();
}
diff --git a/packages/app/tests/integration/frontmatter-lint-http.test.ts b/packages/app/tests/integration/frontmatter-lint-http.test.ts
index c55cbbe49..3d4049869 100644
--- a/packages/app/tests/integration/frontmatter-lint-http.test.ts
+++ b/packages/app/tests/integration/frontmatter-lint-http.test.ts
@@ -1,4 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ realpathSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
import { join } from 'node:path';
import {
FrontmatterSchemasListSuccessSchema,
@@ -408,6 +417,39 @@ describe('POST /api/lint/frontmatter-schema — write surface over HTTP', () =>
});
expect(res.status).toBe(400);
});
+
+ test('schema writes resolve from projectDir when contentDir is nested', async () => {
+ const projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-fm-project-root-')));
+ const contentDir = join(projectDir, 'content');
+ mkdirSync(contentDir);
+ const distinctServer = await createTestServer({ contentDir, projectDir });
+ const file = '.ok/schemas/project-root.schema.json';
+ try {
+ const res = await fetch(
+ `http://127.0.0.1:${distinctServer.port}/api/lint/frontmatter-schema`,
+ {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ file }),
+ },
+ );
+ expect(res.status).toBe(200);
+ LintConfigResponseSchema.parse(await res.json());
+ expect(existsSync(join(projectDir, file))).toBe(true);
+ expect(existsSync(join(contentDir, file))).toBe(false);
+
+ const listed = await fetch(
+ `http://127.0.0.1:${distinctServer.port}/api/lint/frontmatter-schemas`,
+ );
+ expect(listed.status).toBe(200);
+ expect(FrontmatterSchemasListSuccessSchema.parse(await listed.json()).schemas).toContain(
+ file,
+ );
+ } finally {
+ await distinctServer.cleanup();
+ rmSync(projectDir, { recursive: true, force: true });
+ }
+ });
});
describe('GET /api/lint/frontmatter-schemas — file listing for the picker', () => {
diff --git a/packages/app/tests/integration/lint-fix-live-preservation.test.ts b/packages/app/tests/integration/lint-fix-live-preservation.test.ts
new file mode 100644
index 000000000..832a8ac69
--- /dev/null
+++ b/packages/app/tests/integration/lint-fix-live-preservation.test.ts
@@ -0,0 +1,691 @@
+import { randomUUID } from 'node:crypto';
+import {
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ realpathSync,
+ symlinkSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+ AgentUndoSuccessSchema,
+ LINT_PLUGINS,
+ LintFixResultSchema,
+ PrincipalSuccessSchema,
+} from '@inkeep/open-knowledge-core';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import {
+ __formatContributorsForTests,
+ __resetContributorsForTests,
+} from '../../../server/src/contributor-tracker.ts';
+import { writeTracker } from '../../../server/src/file-watcher.ts';
+import { contentHash } from '../../../server/src/version-hash.ts';
+import {
+ agentWriteMd,
+ assertAllConverged,
+ assertBridgeInvariant,
+ awaitConvergedServerText,
+ createTestClients,
+ createTestServer,
+ getServerState,
+ pollUntil,
+ type TestClient,
+ type TestServer,
+} from './test-harness.ts';
+
+const TABBED_BODY = '# Doc\n\n\tindented with a hard tab\n';
+
+interface ContributorPayload {
+ id: string;
+ docs: string[];
+ summaries?: string[];
+}
+
+let server: TestServer | undefined;
+let clients: TestClient[] = [];
+
+afterEach(async () => {
+ vi.restoreAllMocks();
+ delete process.env.OK_TEST_STORE_DIVERGENCE;
+ delete process.env.OK_TEST_STORE_FAULT;
+ await Promise.all(clients.map((client) => client.cleanup()));
+ clients = [];
+ await server?.cleanup();
+ server = undefined;
+ __resetContributorsForTests();
+});
+
+function postFix(body: Record<string, unknown>): Promise<Response> {
+ if (!server) throw new Error('Test server is not running');
+ return fetch(`${server.baseUrl}/api/lint/fix`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(body),
+ });
+}
+
+function contributors(): ContributorPayload[] {
+ return __formatContributorsForTests()
+ .split('\n')
+ .filter((line) => line.startsWith('ok-contributors: '))
+ .map((line) => JSON.parse(line.slice('ok-contributors: '.length)) as ContributorPayload);
+}
+
+function markdownlintPlugin() {
+ const plugin = LINT_PLUGINS.find((candidate) => candidate.id === 'markdownlint');
+ if (!plugin) throw new Error('markdownlint plugin missing');
+ return plugin;
+}
+
+describe('lint fix live-write preservation', () => {
+ test('fixes live source through the frozen session origin and converges peers, fragment and disk', async () => {
+ server = await createTestServer({
+ markdownlintEnabled: true,
+ debounce: 300_000,
+ maxDebounce: 600_000,
+ });
+ const docName = `lint-live-${randomUUID()}`;
+ const file = join(server.contentDir, `${docName}.md`);
+ writeFileSync(file, TABBED_BODY, 'utf-8');
+ clients = await createTestClients(server.port, { count: 2, docName });
+ const writer = clients[0];
+ if (!writer) throw new Error('Expected a writer client');
+ for (const client of clients) {
+ await pollUntil(() => client.ytext.toString() === TABBED_BODY);
+ }
+
+ const session = await server.instance.sessionManager.getSession(docName, 'agent-lint-live', {
+ displayName: 'Codex Live',
+ colorSeed: 'lint-live',
+ clientName: 'codex',
+ });
+ const origins: unknown[] = [];
+ const observeOrigin = (event: { transaction: { origin: unknown } }): void => {
+ origins.push(event.transaction.origin);
+ };
+ session.dc.document.getText('source').observe(observeOrigin);
+
+ try {
+ writer.doc.transact(() => {
+ writer.ytext.insert(writer.ytext.length, '\nLive peer edit.\n');
+ });
+ await pollUntil(() =>
+ getServerState(server as TestServer, docName)
+ ?.ytext.toString()
+ .includes('Live peer edit'),
+ );
+ await assertAllConverged(clients);
+ expect(readFileSync(file, 'utf-8')).toBe(TABBED_BODY);
+
+ __resetContributorsForTests();
+ const response = await postFix({
+ docName,
+ agentId: 'lint-live',
+ agentName: 'Codex Live',
+ clientName: 'codex',
+ summary: ' Fix the live source ',
+ });
+ expect(response.status).toBe(200);
+ const result = LintFixResultSchema.parse(await response.json());
+ expect(result.fixedCount).toBeGreaterThanOrEqual(1);
+
+ const settled = await awaitConvergedServerText(server, writer);
+ await assertAllConverged(clients);
+ const state = getServerState(server, docName);
+ if (state === null) throw new Error('Expected a loaded server document');
+ expect(settled).toBe(state.ytext.toString());
+ expect(settled).toContain('Live peer edit.');
+ expect(settled).not.toContain('\t');
+ expect(readFileSync(file, 'utf-8')).toBe(settled);
+ assertBridgeInvariant(state.ytext, state.fragment);
+ expect(origins).toContain(session.origin);
+ expect(Object.isFrozen(session.origin)).toBe(true);
+ expect(Object.isFrozen(session.origin.context)).toBe(true);
+ expect(session.origin.context).toMatchObject({
+ origin: 'agent-write',
+ paired: true,
+ session_id: 'lint-live',
+ agent_type: 'codex',
+ });
+
+ const contributors = __formatContributorsForTests();
+ expect(contributors).toContain('"id":"agent-lint-live"');
+ expect(contributors).toContain('"summaries":[" Fix the live source "]');
+ expect(
+ server.instance.agentPresenceBroadcaster.getPresenceMap()['agent-lint-live'],
+ ).toMatchObject({ currentDoc: docName, mode: 'idle' });
+
+ const undoResponse = await fetch(`${server.baseUrl}/api/agent-undo`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ docName,
+ connectionId: 'agent-lint-live',
+ agentId: 'lint-live',
+ agentName: 'Codex Live',
+ clientName: 'codex',
+ scope: 'last',
+ }),
+ });
+ expect(undoResponse.status).toBe(200);
+ expect(AgentUndoSuccessSchema.parse(await undoResponse.json())).toMatchObject({
+ docName,
+ scope: 'last',
+ undone: true,
+ });
+ const undone = await awaitConvergedServerText(server, writer);
+ await assertAllConverged(clients);
+ expect(undone).toContain('\tindented with a hard tab');
+ expect(undone).toContain('Live peer edit.');
+ expect(readFileSync(file, 'utf-8')).toBe(undone);
+ } finally {
+ session.dc.document.getText('source').unobserve(observeOrigin);
+ }
+ });
+
+ test('records the current two-identity attribution split for a principal', async () => {
+ server = await createTestServer({ markdownlintEnabled: true });
+ const docName = `lint-principal-${randomUUID()}`;
+ const file = join(server.contentDir, `${docName}.md`);
+ writeFileSync(file, TABBED_BODY, 'utf-8');
+
+ const principalResponse = await fetch(`${server.baseUrl}/api/principal`);
+ expect(principalResponse.status).toBe(200);
+ const principal = PrincipalSuccessSchema.parse(await principalResponse.json());
+ __resetContributorsForTests();
+
+ const response = await postFix({
+ docName,
+ principalId: 'principal-forged',
+ summary: 'Principal lint fix',
+ });
+ expect(response.status).toBe(200);
+ expect(LintFixResultSchema.parse(await response.json()).fixedCount).toBeGreaterThanOrEqual(1);
+ expect(readFileSync(file, 'utf-8')).not.toContain('\t');
+
+ expect(contributors()).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ id: principal.id,
+ docs: [docName],
+ summaries: ['Principal lint fix'],
+ }),
+ expect.objectContaining({ id: `agent-${principal.id}`, docs: [docName] }),
+ ]),
+ );
+ expect(__formatContributorsForTests()).not.toContain('principal-forged');
+
+ const session = server.instance.sessionManager.getLiveSession(docName, principal.id);
+ if (!session) throw new Error('Expected the principal lint session');
+ expect(session.origin.context.session_id).toBe(principal.id);
+ expect(session.um.trackedOrigins.has(session.origin)).toBe(true);
+ expect(session.um.undoStack.length).toBeGreaterThan(0);
+ expect(server.instance.agentPresenceBroadcaster.getPresenceMap()[principal.id]).toBeUndefined();
+ });
+
+ test('records the current anonymous direct and persistence attribution split', async () => {
+ const root = realpathSync(mkdtempSync(join(tmpdir(), 'ok-lint-anonymous-')));
+ mkdirSync(join(root, '.ok', 'local', 'principal.json'), { recursive: true });
+ writeFileSync(
+ join(root, '.ok', 'config.yml'),
+ 'contentRules:\n markdownlint:\n enabled: true\n',
+ 'utf-8',
+ );
+ const docName = `lint-anonymous-${randomUUID()}`;
+ const file = join(root, `${docName}.md`);
+ writeFileSync(file, TABBED_BODY, 'utf-8');
+ server = await createTestServer({ contentDir: root, projectDir: root });
+ __resetContributorsForTests();
+
+ const response = await postFix({ docName, principalId: 'principal-forged' });
+ expect(response.status).toBe(200);
+ expect(LintFixResultSchema.parse(await response.json()).fixedCount).toBeGreaterThanOrEqual(1);
+ expect(readFileSync(file, 'utf-8')).not.toContain('\t');
+
+ expect(contributors()).toEqual([
+ expect.objectContaining({ id: 'agent-principal-anonymous', docs: [docName] }),
+ ]);
+ const session = server.instance.sessionManager.getLiveSession(docName, 'principal-anonymous');
+ if (!session) throw new Error('Expected the anonymous lint session');
+ expect(session.origin.context.session_id).toBe('principal-anonymous');
+ expect(session.um.trackedOrigins.has(session.origin)).toBe(true);
+ expect(session.um.undoStack.length).toBeGreaterThan(0);
+ expect(
+ server.instance.agentPresenceBroadcaster.getPresenceMap()['principal-anonymous'],
+ ).toBeUndefined();
+ });
+
+ test('a no-op performs one lint pass without a write, contributor, presence or disk flush', async () => {
+ server = await createTestServer({ markdownlintEnabled: true });
+ const docName = `lint-noop-${randomUUID()}`;
+ const clean = '# Clean\n\nNo problems here.\n';
+ const file = join(server.contentDir, `${docName}.md`);
+ writeFileSync(file, clean, 'utf-8');
+ const session = await server.instance.sessionManager.getSession(docName, 'agent-lint-noop', {
+ displayName: 'Noop Agent',
+ colorSeed: 'lint-noop',
+ clientName: 'codex',
+ });
+ const origins: unknown[] = [];
+ const observeOrigin = (event: { transaction: { origin: unknown } }): void => {
+ origins.push(event.transaction.origin);
+ };
+ session.dc.document.getText('source').observe(observeOrigin);
+ const lint = vi.spyOn(markdownlintPlugin(), 'lint');
+ process.env.OK_TEST_STORE_FAULT = docName;
+ __resetContributorsForTests();
+
+ try {
+ const response = await postFix({
+ docName,
+ agentId: 'lint-noop',
+ agentName: 'Noop Agent',
+ clientName: 'codex',
+ summary: 'Should not be recorded',
+ });
+ expect(response.status).toBe(200);
+ const result = LintFixResultSchema.parse(await response.json());
+ expect(result.fixedCount).toBe(0);
+ expect(lint).toHaveBeenCalledTimes(1);
+ expect(origins).not.toContain(session.origin);
+ expect(readFileSync(file, 'utf-8')).toBe(clean);
+ expect(contributors()).toEqual([]);
+ expect(
+ server.instance.agentPresenceBroadcaster.getPresenceMap()['agent-lint-noop'],
+ ).toBeUndefined();
+ } finally {
+ session.dc.document.getText('source').unobserve(observeOrigin);
+ }
+ });
+
+ test('a failed disk flush retains the session-origin edit and direct contribution but reports 507', async () => {
+ server = await createTestServer({ markdownlintEnabled: true });
+ const docName = `lint-storage-fault-${randomUUID()}`;
+ const file = join(server.contentDir, `${docName}.md`);
+ writeFileSync(file, TABBED_BODY, 'utf-8');
+ const session = await server.instance.sessionManager.getSession(docName, 'agent-lint-fault', {
+ displayName: 'Fault Agent',
+ colorSeed: 'lint-fault',
+ clientName: 'codex',
+ });
+ const origins: unknown[] = [];
+ const observeOrigin = (event: { transaction: { origin: unknown } }): void => {
+ origins.push(event.transaction.origin);
+ };
+ session.dc.document.getText('source').observe(observeOrigin);
+ const lint = vi.spyOn(markdownlintPlugin(), 'lint');
+ process.env.OK_TEST_STORE_FAULT = docName;
+ __resetContributorsForTests();
+
+ try {
+ const response = await postFix({
+ docName,
+ agentId: 'lint-fault',
+ agentName: 'Fault Agent',
+ clientName: 'codex',
+ summary: 'Failed durability',
+ });
+ expect(response.status).toBe(507);
+ expect(await response.json()).toMatchObject({ type: 'urn:ok:error:storage-full' });
+ expect(session.dc.document.getText('source').toString()).not.toContain('\t');
+ expect(readFileSync(file, 'utf-8')).toBe(TABBED_BODY);
+ expect(origins).toContain(session.origin);
+ expect(lint).toHaveBeenCalledTimes(1);
+ expect(contributors()).toEqual([
+ expect.objectContaining({
+ id: 'agent-lint-fault',
+ docs: [docName],
+ summaries: ['Failed durability'],
+ }),
+ ]);
+ expect(
+ server.instance.agentPresenceBroadcaster.getPresenceMap()['agent-lint-fault'],
+ ).toMatchObject({ currentDoc: docName, mode: 'idle' });
+ } finally {
+ session.dc.document.getText('source').unobserve(observeOrigin);
+ }
+ });
+
+ test.each([
+ {
+ name: 'disjoint append',
+ marker: 'Peer disjoint append.',
+ apply: (client: TestClient) => {
+ client.ytext.insert(client.ytext.length, '\nPeer disjoint append.\n');
+ },
+ },
+ {
+ name: 'overlapping line edit',
+ marker: 'peer overlapping wording',
+ apply: (client: TestClient) => {
+ const start = client.ytext.toString().indexOf('indented with a hard tab');
+ client.ytext.delete(start, 'indented with a hard tab'.length);
+ client.ytext.insert(start, 'peer overlapping wording');
+ },
+ },
+ ])(
+ 'retains the baseline snapshot outcome for a $name during the lint barrier',
+ async (scenario) => {
+ server = await createTestServer({
+ markdownlintEnabled: true,
+ debounce: 300_000,
+ maxDebounce: 600_000,
+ });
+ const docName = `lint-peer-${randomUUID()}`;
+ const file = join(server.contentDir, `${docName}.md`);
+ writeFileSync(file, TABBED_BODY, 'utf-8');
+ clients = await createTestClients(server.port, {
+ count: 2,
+ docName,
+ perClientOptions: { syncControl: true },
+ });
+ const writer = clients[0];
+ if (!writer) throw new Error('Expected a writer client');
+ for (const client of clients) {
+ await pollUntil(() => client.ytext.toString() === TABBED_BODY);
+ }
+
+ const plugin = markdownlintPlugin();
+ const originalLint = plugin.lint;
+ const started = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ let calls = 0;
+ vi.spyOn(plugin, 'lint').mockImplementation(async (text, slice, context) => {
+ calls += 1;
+ if (calls === 1) {
+ started.resolve();
+ await release.promise;
+ }
+ return originalLint.call(plugin, text, slice, context);
+ });
+
+ writer.pauseSync();
+ try {
+ const request = postFix({ docName, agentId: 'lint-peer', clientName: 'codex' });
+ await started.promise;
+ writer.doc.transact(() => scenario.apply(writer));
+ await pollUntil(() =>
+ Boolean(
+ getServerState(server as TestServer, docName)
+ ?.ytext.toString()
+ .includes(scenario.marker),
+ ),
+ );
+ release.resolve();
+
+ const response = await request;
+ expect(response.status).toBe(200);
+ expect(LintFixResultSchema.parse(await response.json()).fixedCount).toBeGreaterThanOrEqual(
+ 1,
+ );
+ writer.resumeSync();
+ await assertAllConverged(clients, { timeout: 5_000 });
+ const settled = await awaitConvergedServerText(server, writer);
+ expect(settled).not.toContain('\t');
+ expect(settled).not.toContain(scenario.marker);
+ expect(settled).toContain('indented with a hard tab');
+ expect(readFileSync(file, 'utf-8')).toBe(settled);
+ } finally {
+ release.resolve();
+ writer.resumeSync();
+ }
+ },
+ );
+
+ test('a disk divergence returns 409 and realigns the live document to the injected disk state', async () => {
+ server = await createTestServer({ markdownlintEnabled: true });
+ const docName = `lint-divergence-${randomUUID()}`;
+ const file = join(server.contentDir, `${docName}.md`);
+ writeFileSync(file, TABBED_BODY, 'utf-8');
+ process.env.OK_TEST_STORE_DIVERGENCE = docName;
+ __resetContributorsForTests();
+
+ const response = await postFix({
+ docName,
+ agentId: 'lint-divergence',
+ agentName: 'Divergence Agent',
+ summary: 'Divergent durability',
+ });
+ expect(response.status).toBe(409);
+ expect(await response.json()).toMatchObject({ type: 'urn:ok:error:disk-divergence' });
+
+ await pollUntil(() => readFileSync(file, 'utf-8').includes('native-divergence-injected'));
+ await pollUntil(() =>
+ Boolean(
+ getServerState(server as TestServer, docName)
+ ?.ytext.toString()
+ .includes('native-divergence-injected'),
+ ),
+ );
+ const state = getServerState(server, docName);
+ if (state === null) throw new Error('Expected a realigned server document');
+ expect(state.ytext.toString()).toBe(readFileSync(file, 'utf-8'));
+ expect(state.ytext.toString()).toBe('# NATIVE\n\nnative-divergence-injected\n');
+ expect(contributors()).toEqual([
+ expect.objectContaining({
+ id: 'agent-lint-divergence',
+ docs: [docName],
+ summaries: ['Divergent durability'],
+ }),
+ ]);
+ expect(
+ server.instance.agentPresenceBroadcaster.getPresenceMap()['agent-lint-divergence'],
+ ).toMatchObject({ currentDoc: docName, mode: 'idle' });
+ });
+
+ test('a stale external write returns 409 while retaining the fixed live source for recovery', async () => {
+ server = await createTestServer({
+ markdownlintEnabled: true,
+ debounce: 50,
+ maxDebounce: 200,
+ });
+ const docName = `lint-stale-${randomUUID()}`;
+ const file = join(server.contentDir, `${docName}.md`);
+ writeFileSync(file, TABBED_BODY, 'utf-8');
+ const stale = readFileSync(file, 'utf-8');
+ await agentWriteMd(server.port, 'Acknowledged before lint.\n', {
+ docName,
+ position: 'append',
+ agentId: 'seed-lint-stale',
+ });
+ await pollUntil(() => readFileSync(file, 'utf-8').includes('Acknowledged before lint.'));
+ await pollUntil(
+ () => !writeTracker.get(file)?.some((entry) => entry.hash === contentHash(stale)),
+ );
+ const state = getServerState(server, docName);
+ if (state === null) throw new Error('Expected a loaded stale-write document');
+ const restoreStale = (): void => {
+ if (state.ytext.toString().includes('\t')) return;
+ state.ytext.unobserve(restoreStale);
+ writeFileSync(file, stale, 'utf-8');
+ };
+ state.ytext.observe(restoreStale);
+ __resetContributorsForTests();
+
+ try {
+ const response = await postFix({
+ docName,
+ agentId: 'lint-stale',
+ agentName: 'Stale Agent',
+ summary: 'Retain stale-race fix',
+ });
+ expect(response.status).toBe(409);
+ expect(await response.json()).toMatchObject({ type: 'urn:ok:error:stale-external-write' });
+ expect(readFileSync(file, 'utf-8')).toBe(stale);
+ expect(state.ytext.toString()).not.toContain('\t');
+ expect(state.ytext.toString()).toContain('Acknowledged before lint.');
+ expect(server.instance.durabilityState.getStaleExternalWrite(docName)?.retainedContent).toBe(
+ state.ytext.toString(),
+ );
+ expect(
+ readFileSync(join(server.instance.lockDir, 'stale-external-writes.json'), 'utf-8'),
+ ).toContain('Acknowledged before lint.');
+ expect(contributors()).toEqual([
+ expect.objectContaining({
+ id: 'agent-lint-stale',
+ docs: [docName],
+ summaries: ['Retain stale-race fix'],
+ }),
+ ]);
+ expect(
+ server.instance.agentPresenceBroadcaster.getPresenceMap()['agent-lint-stale'],
+ ).toMatchObject({ currentDoc: docName, mode: 'idle' });
+ } finally {
+ state.ytext.unobserve(restoreStale);
+ }
+ });
+
+ test.each([
+ { name: 'missing document', body: {}, type: 'urn:ok:error:invalid-request' },
+ { name: 'empty document', body: { docName: '' }, type: 'urn:ok:error:invalid-request' },
+ {
+ name: 'system document',
+ body: { docName: '__system__' },
+ type: 'urn:ok:error:reserved-doc-name',
+ },
+ {
+ name: 'config document',
+ body: { docName: '__config__/project' },
+ type: 'urn:ok:error:reserved-doc-name',
+ },
+ {
+ name: 'unknown document',
+ body: { docName: `missing-${randomUUID()}` },
+ type: 'urn:ok:error:doc-not-found',
+ },
+ ])('retains the ordered 400 or 404 problem for a $name', async ({ body, type }) => {
+ server = await createTestServer({ markdownlintEnabled: true });
+ const response = await postFix(body);
+ expect(response.status).toBe(type === 'urn:ok:error:doc-not-found' ? 404 : 400);
+ expect(await response.json()).toMatchObject({ type });
+ expect(contributors()).toEqual([]);
+ });
+
+ test('an active conflict refuses the fix before it mutates source, disk or attribution', async () => {
+ server = await createTestServer({ markdownlintEnabled: true });
+ const docName = `lint-conflict-${randomUUID()}`;
+ const file = join(server.contentDir, `${docName}.md`);
+ writeFileSync(file, TABBED_BODY, 'utf-8');
+ const session = await server.instance.sessionManager.getSession(
+ docName,
+ 'agent-lint-conflict',
+ {
+ displayName: 'Conflict Agent',
+ colorSeed: 'lint-conflict',
+ clientName: 'codex',
+ },
+ );
+ session.dc.document.getMap('lifecycle').set('status', 'conflict');
+ __resetContributorsForTests();
+
+ const response = await postFix({
+ docName,
+ agentId: 'lint-conflict',
+ agentName: 'Conflict Agent',
+ clientName: 'codex',
+ summary: 'Must not land',
+ });
+ expect(response.status).toBe(409);
+ expect(await response.json()).toMatchObject({ type: 'urn:ok:error:doc-in-conflict' });
+ expect(session.dc.document.getText('source').toString()).toBe(TABBED_BODY);
+ expect(readFileSync(file, 'utf-8')).toBe(TABBED_BODY);
+ expect(contributors()).toEqual([]);
+ expect(
+ server.instance.agentPresenceBroadcaster.getPresenceMap()['agent-lint-conflict'],
+ ).toMatchObject({ currentDoc: docName, mode: 'idle' });
+ });
+
+ test('a malformed snapshot frontmatter refuses the patch when live frontmatter changes mid-fix', async () => {
+ server = await createTestServer({
+ markdownlintEnabled: true,
+ debounce: 300_000,
+ maxDebounce: 600_000,
+ });
+ const docName = `lint-malformed-${randomUUID()}`;
+ const malformed = `---\ntitle: [unterminated\n---\n\n${TABBED_BODY}`;
+ const file = join(server.contentDir, `${docName}.md`);
+ writeFileSync(file, malformed, 'utf-8');
+ clients = await createTestClients(server.port, { count: 1, docName });
+ const writer = clients[0];
+ if (!writer) throw new Error('Expected a writer client');
+ await pollUntil(() => writer.ytext.toString() === malformed);
+
+ const plugin = markdownlintPlugin();
+ const originalLint = plugin.lint;
+ const started = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ let calls = 0;
+ vi.spyOn(plugin, 'lint').mockImplementation(async (text, slice, context) => {
+ calls += 1;
+ if (calls === 1) {
+ started.resolve();
+ await release.promise;
+ }
+ return originalLint.call(plugin, text, slice, context);
+ });
+ __resetContributorsForTests();
+
+ try {
+ const request = postFix({
+ docName,
+ agentId: 'lint-malformed',
+ clientName: 'codex',
+ summary: 'Must refuse malformed frontmatter',
+ });
+ await started.promise;
+ const start = writer.ytext.toString().indexOf('[unterminated');
+ writer.doc.transact(() => {
+ writer.ytext.delete(start, '[unterminated'.length);
+ writer.ytext.insert(start, 'Valid now');
+ });
+ await pollUntil(() =>
+ Boolean(
+ getServerState(server as TestServer, docName)
+ ?.ytext.toString()
+ .includes('Valid now'),
+ ),
+ );
+ release.resolve();
+
+ const response = await request;
+ expect(response.status).toBe(400);
+ expect(await response.json()).toMatchObject({ type: 'urn:ok:error:frontmatter-malformed' });
+ const state = getServerState(server, docName);
+ if (state === null) throw new Error('Expected the live malformed-frontmatter document');
+ expect(state.ytext.toString()).toContain('title: Valid now');
+ expect(state.ytext.toString()).toContain('\t');
+ expect(readFileSync(file, 'utf-8')).toBe(malformed);
+ expect(contributors()).toEqual([]);
+ expect(
+ server.instance.agentPresenceBroadcaster.getPresenceMap()['agent-lint-malformed'],
+ ).toMatchObject({ currentDoc: docName, mode: 'idle' });
+ } finally {
+ release.resolve();
+ }
+ });
+
+ test('an indexed in-root alias fixes the canonical document and reports its canonical path', async () => {
+ const root = realpathSync(mkdtempSync(join(tmpdir(), 'ok-lint-alias-')));
+ mkdirSync(join(root, '.ok'), { recursive: true });
+ writeFileSync(
+ join(root, '.ok', 'config.yml'),
+ 'contentRules:\n markdownlint:\n enabled: true\n',
+ 'utf-8',
+ );
+ const canonicalName = `lint-canonical-${randomUUID()}`;
+ const aliasName = `lint-alias-${randomUUID()}`;
+ const canonicalFile = join(root, `${canonicalName}.md`);
+ writeFileSync(canonicalFile, TABBED_BODY, 'utf-8');
+ symlinkSync(canonicalFile, join(root, `${aliasName}.md`));
+ server = await createTestServer({ contentDir: root, projectDir: root });
+
+ const response = await postFix({ docName: aliasName, agentId: 'lint-alias' });
+ expect(response.status).toBe(200);
+ const result = LintFixResultSchema.parse(await response.json());
+ expect(result.file).toBe(`${canonicalName}.md`);
+ expect(result.fixedCount).toBeGreaterThanOrEqual(1);
+ expect(readFileSync(canonicalFile, 'utf-8')).not.toContain('\t');
+ });
+});
diff --git a/packages/app/tests/integration/lint-http.test.ts b/packages/app/tests/integration/lint-http.test.ts
index 29c9462d6..9ae90d5e1 100644
--- a/packages/app/tests/integration/lint-http.test.ts
+++ b/packages/app/tests/integration/lint-http.test.ts
@@ -294,6 +294,27 @@ describe('POST /api/lint/markdownlint-config', () => {
}
});
+ test('removing the last rule deletes its file and repeating the removal is an accepted no-op', async () => {
+ const nativeFile = join(server.contentDir, '.markdownlint.json');
+ writeFileSync(nativeFile, JSON.stringify({ MD012: false }), 'utf-8');
+ try {
+ const removed = await postRule('MD012', null);
+ expect(removed.status).toBe(200);
+ const removedBody = LintConfigResponseSchema.parse(await removed.json());
+ expect(removedBody.configFile).toBeNull();
+ expect(removedBody.effective.plugins.markdownlint.rules.MD012).not.toBe(false);
+ expect(existsSync(nativeFile)).toBe(false);
+
+ const noop = await postRule('MD012', null);
+ expect(noop.status).toBe(200);
+ const noopBody = LintConfigResponseSchema.parse(await noop.json());
+ expect(noopBody.configFile).toBeNull();
+ expect(existsSync(nativeFile)).toBe(false);
+ } finally {
+ rmSync(nativeFile, { force: true });
+ }
+ });
+
test('an executable native config declines the write with a 409', async () => {
const cjsFile = join(server.contentDir, '.markdownlint.cjs');
writeFileSync(cjsFile, 'module.exports = { MD010: false };\n', 'utf-8');
diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.ts
index c93dd2f8c..dfecb41e1 100644
--- a/packages/core/src/markdown/lint/config-schemas.ts
+++ b/packages/core/src/markdown/lint/config-schemas.ts
@@ -68,6 +68,15 @@ export const LintConfigResponseSchema = z.object({
const MarkdownlintRuleWriteValueSchema = z.union([z.boolean(), z.record(z.string(), z.unknown())]);
+const RESERVED_SCHEMA_PROPERTY_KEYS = new Set(['__proto__']);
+const SchemaPropertyKeyStringSchema = z
+ .string()
+ .min(1)
+ .max(256)
+ .refine((key) => !RESERVED_SCHEMA_PROPERTY_KEYS.has(key), {
+ message: 'schema property name cannot be __proto__',
+ });
+
export const MarkdownlintRuleWriteRequestSchema = z.object({
ruleId: z
.string()
@@ -81,13 +90,15 @@ export const FrontmatterSchemaWriteRequestSchema = z
.object({
file: z.string().min(1).max(512),
delete: z.literal(true).optional(),
- field: z.string().min(1).max(256).optional(),
+ field: SchemaPropertyKeyStringSchema.optional(),
parentPath: z
- .array(z.union([z.string().min(1).max(256), z.object({ items: z.literal(true) }).strict()]))
+ .array(
+ z.union([SchemaPropertyKeyStringSchema, z.object({ items: z.literal(true) }).strict()]),
+ )
.max(8)
.optional(),
removeField: z.literal(true).optional(),
- renameTo: z.string().min(1).max(256).optional(),
+ renameTo: SchemaPropertyKeyStringSchema.optional(),
constraint: z
.object({
type: z.enum(['string', 'number', 'boolean', 'array', 'object']).nullable().optional(),
diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
index ef478e268..a244029e3 100644
--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
@@ -64,7 +64,7 @@ function navigateToParent(
continue;
}
const properties = schemaProperties(node);
- const child = properties[segment];
+ const child = Object.hasOwn(properties, segment) ? properties[segment] : undefined;
if (child === undefined) {
if (!create) {
throw new FrontmatterSchemaEditError(
@@ -101,7 +101,8 @@ export function applyFieldConstraint(
const parent = navigateToParent(schema, parentPath, true);
const properties = schemaProperties(parent);
- const existing = isRecord(properties[field]) ? properties[field] : {};
+ const existingValue = Object.hasOwn(properties, field) ? properties[field] : undefined;
+ const existing = isRecord(existingValue) ? existingValue : {};
const property: Record<string, unknown> = { ...existing };
for (const keyword of ['type', 'enum', 'pattern', 'format', 'description'] as const) {
@@ -130,7 +131,7 @@ export function applyFieldConstraint(
if (Object.keys(property).length > 0) {
parent.properties = { ...properties, [field]: property };
- } else if (field in properties) {
+ } else if (Object.hasOwn(properties, field)) {
const { [field]: _removed, ...rest } = properties;
if (Object.keys(rest).length > 0) parent.properties = rest;
else delete parent.properties;
@@ -189,7 +190,7 @@ export function removeSchemaField(
const schema = parseSchemaObject(schemaText);
const parent = navigateToParent(schema, parentPath, false);
const properties = schemaProperties(parent);
- if (field in properties) {
+ if (Object.hasOwn(properties, field)) {
const { [field]: _removed, ...rest } = properties;
if (Object.keys(rest).length > 0) parent.properties = rest;
else delete parent.properties;
@@ -210,16 +211,18 @@ export function renameSchemaField(
const schema = parseSchemaObject(schemaText);
const parent = navigateToParent(schema, parentPath, false);
const properties = schemaProperties(parent);
- if (!(field in properties)) {
+ if (!Object.hasOwn(properties, field)) {
throw new FrontmatterSchemaEditError(`field ${JSON.stringify(field)} does not exist`);
}
- if (to in properties) {
+ if (Object.hasOwn(properties, to)) {
throw new FrontmatterSchemaEditError(`field ${JSON.stringify(to)} already exists`);
}
- const renamed: Record<string, unknown> = {};
- for (const [key, value] of Object.entries(properties)) {
- renamed[key === field ? to : key] = value;
- }
+ const renamed = Object.fromEntries(
+ Object.entries(properties).map(([key, value]): [string, unknown] => [
+ key === field ? to : key,
+ value,
+ ]),
+ );
parent.properties = renamed;
setRequired(
parent,
diff --git a/packages/server/src/agent-write-loss-detect-coverage.test.ts b/packages/server/src/agent-write-loss-detect-coverage.test.ts
index d3ee4833f..20f19a018 100644
--- a/packages/server/src/agent-write-loss-detect-coverage.test.ts
+++ b/packages/server/src/agent-write-loss-detect-coverage.test.ts
@@ -2,13 +2,9 @@ import { basename, dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { Node, Project, SyntaxKind } from 'ts-morph';
import { describe, expect, it } from 'vitest';
+import { listAgentWriteSpineFiles } from './agent-write-spine-files.test-helper.ts';
const here = dirname(fileURLToPath(import.meta.url));
-const SPINE_FILES = [
- join(here, 'api-extension.ts'),
- join(here, 'http', 'agent-write-routes.ts'),
- join(here, 'acp', 'thread-manager.ts'),
-];
function newProject(): Project {
return new Project({
@@ -37,9 +33,11 @@ function threadsLossDetect(call: Node): boolean {
describe('agent-write loss-detect coverage', () => {
it('every applyAgentMarkdownWrite spine call threads agentWriteLossDetect', () => {
const project = newProject();
- const spineCalls = SPINE_FILES.flatMap((path) =>
+ const spineFiles = listAgentWriteSpineFiles(here);
+ expect(spineFiles.length).toBeGreaterThan(0);
+ const spineCalls = spineFiles.flatMap((path) =>
project
- .addSourceFileAtPath(path)
+ .addSourceFileAtPath(join(here, path))
.getDescendantsOfKind(SyntaxKind.CallExpression)
.filter((c) => calleeName(c) === 'applyAgentMarkdownWrite'),
);
diff --git a/packages/server/src/agent-write-pre-drain-coverage.test.ts b/packages/server/src/agent-write-pre-drain-coverage.test.ts
index 204fa4ebc..0252d6890 100644
--- a/packages/server/src/agent-write-pre-drain-coverage.test.ts
+++ b/packages/server/src/agent-write-pre-drain-coverage.test.ts
@@ -2,13 +2,9 @@ import { basename, dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { Node, Project, SyntaxKind } from 'ts-morph';
import { describe, expect, it } from 'vitest';
+import { listAgentWriteSpineFiles } from './agent-write-spine-files.test-helper.ts';
const here = dirname(fileURLToPath(import.meta.url));
-const SPINE_FILES = [
- join(here, 'api-extension.ts'),
- join(here, 'http', 'agent-write-routes.ts'),
- join(here, 'acp', 'thread-manager.ts'),
-];
const FULL_BODY_OVERWRITE = new Set(['replace', 'patch']);
@@ -65,9 +61,11 @@ function handlerScope(call: Node): Node | undefined {
describe('agent-write pre-drain coverage', () => {
it('every pre-drainable applyAgentMarkdownWrite spine call is preceded by agentWritePreDrain', () => {
const project = newProject();
- const spineCalls = SPINE_FILES.flatMap((path) =>
+ const spineFiles = listAgentWriteSpineFiles(here);
+ expect(spineFiles.length).toBeGreaterThan(0);
+ const spineCalls = spineFiles.flatMap((path) =>
project
- .addSourceFileAtPath(path)
+ .addSourceFileAtPath(join(here, path))
.getDescendantsOfKind(SyntaxKind.CallExpression)
.filter((c) => calleeName(c) === 'applyAgentMarkdownWrite'),
);
diff --git a/packages/server/src/agent-write-spine-files.test-helper.ts b/packages/server/src/agent-write-spine-files.test-helper.ts
new file mode 100644
index 000000000..ff7a1fe6d
--- /dev/null
+++ b/packages/server/src/agent-write-spine-files.test-helper.ts
@@ -0,0 +1,17 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export function listAgentWriteSpineFiles(serverSrcRoot: string): string[] {
+ return readdirSync(serverSrcRoot, { recursive: true, withFileTypes: true })
+ .filter(
+ (entry) =>
+ entry.isFile() &&
+ entry.name.endsWith('.ts') &&
+ !entry.name.endsWith('.test.ts') &&
+ !entry.name.endsWith('.test-helper.ts'),
+ )
+ .map((entry) => join(entry.parentPath, entry.name))
+ .filter((path) => readFileSync(path, 'utf8').includes('applyAgentMarkdownWrite'))
+ .map((path) => relative(serverSrcRoot, path))
+ .sort();
+}
diff --git a/packages/server/src/api-agent-write-native-preservation.test.ts b/packages/server/src/api-agent-write-native-preservation.test.ts
index 7fb1750e7..c7f886329 100644
--- a/packages/server/src/api-agent-write-native-preservation.test.ts
+++ b/packages/server/src/api-agent-write-native-preservation.test.ts
@@ -19,20 +19,18 @@ const WRITES = [
'/api/save-version',
'/api/rollback',
];
+const LINT_WRITES = [
+ '/api/lint/markdownlint-config',
+ '/api/lint/frontmatter-schema',
+ '/api/lint/fix',
+];
const TEST_PATHS = [
'/api/test-reset',
'/api/test-flush-git',
'/api/test-rescan-backlinks',
'/api/test-rescan-files',
];
-const RESIDUAL = [
- '/api/skill/uninstall',
- '/api/agent-write',
- '/api/agent-write-batch',
- '/api/lint/markdownlint-config',
- '/api/lint/frontmatter-schema',
- '/api/lint/fix',
-];
+const RESIDUAL = ['/api/skill/uninstall', '/api/agent-write', '/api/agent-write-batch'];
const AGENT_INTEGRATIONS_APPLY = '/api/agent-integrations/apply';
let root: string;
let enabled: BootedServer;
@@ -59,7 +57,7 @@ afterAll(async () => {
test('native ownership is exclusive and the remaining legacy registry matches its explicit owners', () => {
for (const server of [enabled, disabled]) {
- for (const path of [...READS, ...WRITES, '/api/asset', '/api/asset-text'])
+ for (const path of [...READS, ...WRITES, ...LINT_WRITES, '/api/asset', '/api/asset-text'])
expect(server.serverInstance.nativeApi.paths.filter((entry) => entry === path)).toHaveLength(
1,
);
@@ -81,7 +79,14 @@ test('native ownership is exclusive and the remaining legacy registry matches it
});
test('ingress rejects every migrated route before method or malformed-body admission', async () => {
- for (const path of [...READS, ...WRITES, ...TEST_PATHS, '/api/asset', '/api/asset-text']) {
+ for (const path of [
+ ...READS,
+ ...WRITES,
+ ...LINT_WRITES,
+ ...TEST_PATHS,
+ '/api/asset',
+ '/api/asset-text',
+ ]) {
for (const [headers, type] of [
[{ Host: 'evil.example' }, 'urn:ok:error:host-not-allowed'],
[{ Origin: 'https://evil.example' }, 'urn:ok:error:invalid-origin'],
@@ -89,33 +94,53 @@ test('ingress rejects every migrated route before method or malformed-body admis
] as const) {
const response = await rawRequest(enabled.port, path, {
method: 'PATCH',
- headers,
+ headers: { ...headers, 'X-Request-Id': 'native-admission' },
body: '{',
});
expect(response.status, `${path}: ${response.body}`).toBe(403);
expect(response.headers.allow).toBeUndefined();
+ expect(response.headers['x-request-id']).toBe(
+ 'X-Forwarded-For' in headers ? undefined : 'native-admission',
+ );
+ expect(response.headers['access-control-allow-origin']).toBeUndefined();
expect(parseProblem(response.body).type).toBe(type);
}
}
});
test('methods, preflight, HEAD and request IDs retain the transport contracts', async () => {
- for (const path of [...READS, ...WRITES, ...TEST_PATHS]) {
+ for (const path of [...READS, ...WRITES, ...LINT_WRITES, ...TEST_PATHS]) {
const allowed = READS.includes(path) ? 'GET' : 'POST';
const wrong = await rawRequest(enabled.port, path, {
method: 'PATCH',
- headers: { 'X-Request-Id': 'spine-method' },
+ headers: {
+ Origin: 'http://localhost:5173',
+ 'X-Request-Id': 'spine-method',
+ },
body: '{',
});
expect(wrong.status, `${path}: ${wrong.body}`).toBe(405);
expect(wrong.headers.allow).toBe(allowed);
expect(wrong.headers['x-request-id']).toBe('spine-method');
+ expect(wrong.headers['access-control-allow-origin']).toBe('http://localhost:5173');
expect(parseProblem(wrong.body).type).toBe('urn:ok:error:method-not-allowed');
const head = await rawRequest(enabled.port, path, { method: 'HEAD' });
expect(head.status, path).toBe(405);
expect(head.body).toBe('');
- const preflight = await rawRequest(enabled.port, path, { method: 'OPTIONS' });
+ const preflight = await rawRequest(enabled.port, path, {
+ method: 'OPTIONS',
+ headers: { Host: 'evil.example', Origin: 'http://localhost:5173' },
+ });
expect(preflight.status, path).toBe(204);
+ expect(preflight.headers['access-control-allow-origin']).toBe('http://localhost:5173');
+ const disallowedPreflight = await rawRequest(enabled.port, path, {
+ method: 'OPTIONS',
+ headers: { Origin: 'https://evil.example', 'X-Request-Id': 'preflight-origin' },
+ });
+ expect(disallowedPreflight.status, path).toBe(403);
+ expect(disallowedPreflight.headers['x-request-id']).toBe('preflight-origin');
+ expect(disallowedPreflight.headers['access-control-allow-origin']).toBeUndefined();
+ expect(parseProblem(disallowedPreflight.body).type).toBe('urn:ok:error:invalid-origin');
}
});
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index b6e7ed8f1..ba7a414b8 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -36,21 +36,15 @@ import {
type DiskEditReconciledWarning,
type DocumentListEntry,
estimateSkillCost,
- FrontmatterSchemaWriteRequestSchema,
type HeadingEntry,
type InlineAssetMediaKind,
isManagedArtifactDocName,
LEGACY_SKILL_STORE_ROOT,
- LintConfigResponseSchema,
type LinterConfig,
- LintFixRequestSchema,
- LintFixResultSchema,
- type LintPluginFailure,
type LintViolationWarning,
LOCAL_DIR,
lintDocument,
MANAGED_ARTIFACT_PREFIX_SKILL,
- MarkdownlintRuleWriteRequestSchema,
mediaKindForSidebarAssetExtension,
OK_DIR,
OPENKNOWLEDGE_SKILLS_REPO,
@@ -58,7 +52,6 @@ import {
type ProblemType,
parseFrontmatterRecord,
pathspecArgs,
- type ReLintFailure,
readFmMap,
SKILL_NAME_REGEX,
SkillScopeSchema,
@@ -66,7 +59,6 @@ import {
SkillUninstallSuccessSchema,
scanHeadingLine,
stripFrontmatter,
- summarizeLintPluginFailures,
type ValidationDiagnostic,
} from '@inkeep/open-knowledge-core';
import { formatRenameSubject } from '@inkeep/open-knowledge-core/shadow-repo-layout';
@@ -140,24 +132,10 @@ import { createSkillsRecoveryRoutes } from './http/skills-recovery-routes.ts';
import { createSkillsTrackingRoutes } from './http/skills-tracking-routes.ts';
import { findHubCandidates } from './hub-candidates.ts';
import { recordSkillInstall, removeSkillInstall } from './installed-skills-marker.ts';
-import { collectDocFiles, lintAndFixSource } from './lint/audit.ts';
+import { collectDocFiles } from './lint/audit.ts';
import { composeAuditGeneration } from './lint/audit-generation.ts';
-import {
- createEmptyFrontmatterSchemaFile,
- deleteFrontmatterSchemaFile,
- removeFrontmatterSchemaField,
- renameFrontmatterSchemaField,
- type WriteFrontmatterSchemaResult,
- writeFrontmatterSchemaField,
-} from './lint/frontmatter-schema-write.ts';
import { unmatchedAppliesToProblems } from './lint/frontmatter-schemas.ts';
-import { type WriteMarkdownlintResult, writeMarkdownlintRule } from './lint/markdownlint-write.ts';
-import {
- composeEffectiveLinterConfig,
- composeFrontmatterSchemasConfig,
- resolveEffectiveLinterConfig,
- resolveNativeConfigForDoc,
-} from './lint/resolve-config.ts';
+import { resolveEffectiveLinterConfig } from './lint/resolve-config.ts';
import { createProjectValidators } from './lint/validation-audit.ts';
import {
extractPageTitle,
@@ -273,6 +251,7 @@ import { createHistoryRoutes } from './http/history-routes.ts';
import { assertSingleRouterOwnership, type NativeApiHandle } from './http/http-app.ts';
import { createLinkGraphRoutes } from './http/link-graph-routes.ts';
import { createLintRoutes } from './http/lint-routes.ts';
+import { createLintWriteRoutes } from './http/lint-write-routes.ts';
import { createLocalApiDispatch, type LocalApiDispatch } from './http/local-api-dispatch.ts';
import { createLocalOpRoutes } from './http/local-op-routes.ts';
import { createMetricsRoutes } from './http/metrics-routes.ts';
@@ -4648,392 +4627,13 @@ export function createApiExtension(
return unmatchedAppliesToProblems(slice.schemas, docFiles);
}
- const handleWriteMarkdownlintRule = withValidation(
- MarkdownlintRuleWriteRequestSchema,
- async (_req, res, body) => {
- let writeResult: WriteMarkdownlintResult;
- try {
- writeResult = writeMarkdownlintRule(resolve(contentDir), body.ruleId, body.value);
- } catch (e) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'Failed to write markdownlint config.',
- { handler: 'markdownlint-config', cause: e },
- );
- return;
- }
- if (writeResult.action === 'declined-executable') {
- errorResponse(
- res,
- 409,
- 'urn:ok:error:config-not-writable',
- `The native markdownlint config (${writeResult.file}) is an executable module OK will not rewrite — edit it directly or convert it to JSON/JSONC/YAML.`,
- { handler: 'markdownlint-config' },
- );
- return;
- }
- signalLintConfigChanged();
- try {
- const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
- const configProblems: string[] = [];
- const native = resolveNativeConfigForDoc(contentDir, undefined, (problem) =>
- configProblems.push(problem),
- );
- const effective = composeFrontmatterSchemasConfig(
- projectDir ?? contentDir,
- composeEffectiveLinterConfig(base, native),
- (problem) => configProblems.push(problem),
- );
- configProblems.push(...unmatchedGlobProblems(effective));
- successResponse(
- res,
- 200,
- LintConfigResponseSchema,
- { effective, configFile: native?.file ?? null, configProblems },
- { handler: 'markdownlint-config' },
- );
- } catch (e) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'The markdownlint rule was saved, but the effective config could not be re-read.',
- { handler: 'markdownlint-config', cause: e },
- );
- }
- },
- { handler: 'markdownlint-config', method: 'POST' },
- );
-
- const handleWriteFrontmatterSchema = withValidation(
- FrontmatterSchemaWriteRequestSchema,
- async (_req, res, body) => {
- let writeResult: WriteFrontmatterSchemaResult;
- try {
- const root = resolve(projectDir ?? contentDir);
- const parentPath = body.parentPath ?? [];
- writeResult = body.delete
- ? deleteFrontmatterSchemaFile(root, body.file)
- : body.field !== undefined && body.removeField
- ? removeFrontmatterSchemaField(root, body.file, body.field, parentPath)
- : body.field !== undefined && body.renameTo !== undefined
- ? renameFrontmatterSchemaField(root, body.file, body.field, body.renameTo, parentPath)
- : body.field !== undefined && body.constraint !== undefined
- ? writeFrontmatterSchemaField(
- root,
- body.file,
- body.field,
- body.constraint,
- parentPath,
- )
- : createEmptyFrontmatterSchemaFile(root, body.file);
- } catch (e) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'Failed to write the frontmatter schema.',
- { handler: 'frontmatter-schema', cause: e },
- );
- return;
- }
- if (writeResult.action === 'refused') {
- errorResponse(
- res,
- 409,
- 'urn:ok:error:config-not-writable',
- `The frontmatter schema (${writeResult.file}) was not written: ${writeResult.reason}.`,
- { handler: 'frontmatter-schema' },
- );
- return;
- }
- if (writeResult.action === 'created' || writeResult.action === 'deleted') {
- signalChannel?.('files');
- }
- signalLintConfigChanged();
- try {
- const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
- const configProblems: string[] = [];
- const native = resolveNativeConfigForDoc(contentDir, undefined, (problem) =>
- configProblems.push(problem),
- );
- const effective = composeFrontmatterSchemasConfig(
- projectDir ?? contentDir,
- composeEffectiveLinterConfig(base, native),
- (problem) => configProblems.push(problem),
- );
- configProblems.push(...unmatchedGlobProblems(effective));
- successResponse(
- res,
- 200,
- LintConfigResponseSchema,
- { effective, configFile: native?.file ?? null, configProblems },
- { handler: 'frontmatter-schema' },
- );
- } catch (e) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'The schema was saved, but the effective config could not be re-read.',
- { handler: 'frontmatter-schema', cause: e },
- );
- }
- },
- { handler: 'frontmatter-schema', method: 'POST' },
- );
-
- const handleLintFix = withValidation(
- LintFixRequestSchema,
- async (_req, res, body) => {
- try {
- const effectiveDocName = requireNonEmptyDocName(body.docName, res, 'lint-fix');
- if (effectiveDocName === null) return;
- const resolvedDocName = resolveAlias(effectiveDocName);
-
- const actor = extractActorIdentity(
- body as unknown as Record<string, unknown>,
- getPrincipal,
- );
- if (actor.kind === 'invalid-summary') {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
- handler: 'lint-fix',
- });
- return;
- }
- const agentId = actor.kind === 'anonymous' ? 'principal-anonymous' : actor.writerId;
- const agentName = actor.kind === 'anonymous' ? 'Anonymous' : actor.displayName;
- const colorSeed = actor.kind === 'anonymous' ? agentId : actor.colorSeed;
- const clientName = actor.kind === 'agent' ? actor.clientName : undefined;
-
- if (isSystemDoc(resolvedDocName) || isConfigDoc(resolvedDocName)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- `'${resolvedDocName}' is a reserved document name.`,
- { handler: 'lint-fix' },
- );
- return;
- }
-
- const docRelPath = resolveDocFilePath(contentDir, resolvedDocName);
- if (docRelPath === null) {
- errorResponse(res, 404, 'urn:ok:error:doc-not-found', 'Document not found.', {
- handler: 'lint-fix',
- });
- return;
- }
- assertNoSymlinkEscape(resolve(contentDir, docRelPath), contentDir);
-
- const baseConfig = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
- const { stored: storedSummary } = summaryResponseFields(actor.summary);
- const session = await sessionManager.getSession(resolvedDocName, agentId, {
- displayName: agentName,
- colorSeed,
- clientName,
- });
-
- const source = session.dc.document.getText('source').toString();
- const configWarnings: string[] = [];
- const { cfg, before, fixed, ran, failures } = await lintAndFixSource({
- projectDir: projectDir ?? contentDir,
- contentDir,
- baseConfig,
- docRelPath,
- source,
- onConfigProblem: (problem) => configWarnings.push(problem),
- });
-
- let after = before;
- let reLintFailure: ReLintFailure | undefined;
- const reLintFailures: LintPluginFailure[] = [];
- if (fixed !== source) {
- try {
- const icon = iconFromClientName(clientName);
- const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
- agentPresenceBroadcaster?.setPresence(agentId, {
- displayName: agentName,
- icon,
- color,
- currentDoc: resolvedDocName,
- mode: 'writing',
- ts: Date.now(),
- });
- session.dc.document.transact(() => {
- applyAgentMarkdownWrite(
- session.dc.document,
- fixed,
- 'patch',
- options.resolveEmbed
- ? { resolveEmbed: options.resolveEmbed, sourcePath: resolvedDocName }
- : undefined,
- undefined,
- agentWriteLossDetect(session),
- );
- }, session.origin);
-
- if (actor.kind !== 'anonymous') {
- recordContributor(
- resolvedDocName,
- agentId,
- agentName,
- colorSeed,
- undefined,
- actor.kind === 'agent'
- ? buildAgentActor({
- clientName: actor.clientName,
- clientVersion: actor.clientVersion,
- label: actor.label,
- })
- : actor.actor,
- storedSummary,
- );
- }
- } finally {
- agentPresenceBroadcaster?.touchMode(agentId, 'idle');
- }
-
- const flushOutcome = await flushDiskAndDetectOutcome(resolvedDocName);
- if (flushOutcome?.kind === 'failure') {
- respondPersistenceFailure(res, flushOutcome.failure, 'lint-fix');
- return;
- }
- if (flushOutcome?.kind === 'divergence') {
- respondDiskDivergence(res, 'lint-fix');
- return;
- }
- if (flushOutcome?.kind === 'stale-external-write') {
- respondStaleExternalWrite(res, 'lint-fix', resolvedDocName);
- return;
- }
- flushDocToDisk(resolvedDocName, 'lint-fix');
-
- try {
- after = await lintDocument(
- session.dc.document.getText('source').toString(),
- cfg,
- docRelPath,
- (failure) => reLintFailures.push(failure),
- );
- } catch (relintErr) {
- const relintMessage =
- relintErr instanceof Error ? relintErr.message : String(relintErr);
- reLintFailure = {
- reason: 're-lint-threw',
- message:
- relintMessage.trim().length > 0
- ? relintMessage
- : `${relintErr instanceof Error ? relintErr.name : 'non-Error value'} thrown with no message`,
- };
- log.warn(
- { err: relintErr, handler: 'lint-fix', doc: resolvedDocName, agentId },
- 'post-write re-lint failed; reporting pre-fix diagnostics',
- );
- after = before;
- }
- }
-
- const blindBeforeFix = new Set(
- failures.filter((f) => f.phase === 'lint').map((f) => f.source),
- );
- const blindOnlyAfterFix = [
- ...new Set(
- reLintFailures
- .filter((f) => f.phase === 'lint' && !blindBeforeFix.has(f.source))
- .map((f) => f.source),
- ),
- ];
- if (reLintFailure === undefined && blindOnlyAfterFix.length > 0) {
- reLintFailure = {
- reason: 'source-went-blind',
- message: `${blindOnlyAfterFix.join(', ')} linted the pre-fix text and failed on the post-fix text, so the re-lint is short their diagnostics and cannot be compared against the pre-fix run`,
- };
- log.warn(
- { handler: 'lint-fix', doc: resolvedDocName, agentId, sources: blindOnlyAfterFix },
- 'post-write re-lint lost a source that linted before the fix; reporting pre-fix diagnostics',
- );
- after = before;
- }
-
- const errorCount = after.filter((d) => d.severity === 'error').length;
- const warningCount = after.length - errorCount;
- const comparable = (d: (typeof before)[number]) => !blindBeforeFix.has(d.source);
- const fixedCount = Math.max(
- 0,
- before.filter(comparable).length - after.filter(comparable).length,
- );
- const responseWarnings = [
- ...configWarnings,
- ...summarizeLintPluginFailures([...failures, ...reLintFailures]),
- ];
-
- successResponse(
- res,
- 200,
- LintFixResultSchema,
- {
- file: docRelPath,
- fixedCount,
- diagnostics: after,
- errorCount,
- warningCount,
- ran,
- ...(responseWarnings.length > 0 ? { warnings: responseWarnings } : {}),
- ...(reLintFailure ? { diagnosticsArePreFix: true, reLintFailure } : {}),
- },
- { handler: 'lint-fix' },
- );
- } catch (e) {
- if (isContainmentRejection(e)) {
- errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {
- handler: 'lint-fix',
- });
- return;
- }
- if (e instanceof DocInConflictError) {
- respondDocInConflict(res, e, 'lint-fix');
- return;
- }
- if (e instanceof FrontmatterMalformedError) {
- respondFrontmatterMalformed(res, e, 'lint-fix');
- return;
- }
- if (e instanceof AgentSessionCapacityError) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:too-many-agent-sessions',
- 'Too many agent sessions.',
- { handler: 'lint-fix', cause: e, extraHeaders: { 'Retry-After': '10' } },
- );
- return;
- }
- log.error({ err: e }, '[lint-fix] handler failed');
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to fix document.', {
- handler: 'lint-fix',
- cause: e,
- });
- }
- },
- { handler: 'lint-fix', method: 'POST' },
- );
-
const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {
'/api/skill/uninstall': handleSkillUninstall,
- '/api/lint/markdownlint-config': handleWriteMarkdownlintRule,
- '/api/lint/frontmatter-schema': handleWriteFrontmatterSchema,
- '/api/lint/fix': handleLintFix,
'/api/agent-write': handleAgentWrite,
'/api/agent-write-batch': handleAgentWriteBatch,
};
const MUTATING_ROUTES: ReadonlySet<string> = new Set([
- '/api/lint/markdownlint-config',
- '/api/lint/frontmatter-schema',
- '/api/lint/fix',
'/api/agent-write',
'/api/agent-write-batch',
'/api/test-reset',
@@ -5121,6 +4721,29 @@ export function createApiExtension(
unmatchedGlobProblems,
readAuditGeneration,
});
+ const lintWriteRoutes = createLintWriteRoutes({
+ contentDir,
+ projectDir,
+ signalLintConfigChanged,
+ getLinterBaseConfig,
+ unmatchedGlobProblems,
+ signalChannel,
+ requireNonEmptyDocName,
+ resolveAlias,
+ getPrincipal,
+ resolveDocFilePath,
+ summaryResponseFields,
+ sessionManager,
+ options,
+ agentPresenceBroadcaster,
+ buildAgentActor,
+ flushDiskAndDetectOutcome,
+ respondPersistenceFailure,
+ respondDiskDivergence,
+ respondStaleExternalWrite,
+ flushDocToDisk,
+ log,
+ });
const historyRoutes = createHistoryRoutes({
contentRoot,
log,
@@ -5525,6 +5148,7 @@ export function createApiExtension(
documentRoutes,
configSystemRoutes,
lintRoutes,
+ lintWriteRoutes,
historyRoutes,
skillsDocumentRoutes,
skillsListRoutes,
diff --git a/packages/server/src/api-lint-composition.test.ts b/packages/server/src/api-lint-composition.test.ts
index be082ab46..4239dffdf 100644
--- a/packages/server/src/api-lint-composition.test.ts
+++ b/packages/server/src/api-lint-composition.test.ts
@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
import type { BootedServer } from './boot.ts';
-import { bootCompositionRig } from './composition-rig.test-helper.ts';
+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';
const READ_GETS = [
'/api/lint/config',
@@ -22,19 +22,38 @@ const ALL_ROUTES = [
'/api/audit',
];
+const WRITE_POSTS = [
+ '/api/lint/markdownlint-config',
+ '/api/lint/frontmatter-schema',
+ '/api/lint/fix',
+];
+
let tmpRoot: string;
let server: BootedServer;
+let external: BootedServer;
beforeAll(async () => {
tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-lint-native-'));
const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));
writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');
server = await bootCompositionRig(contentDir);
- await server.ready;
+ const externalDir = mkdtempSync(resolve(tmpRoot, 'external-'));
+ external = await bootCompositionRig(externalDir, {
+ serverRuntime: {
+ bind: ['127.0.0.1'],
+ port: 0,
+ externalUrl: 'https://lint.example.com',
+ allowExternal: true,
+ openBrowser: false,
+ idleShutdown: 'off',
+ loopbackOnly: true,
+ },
+ });
+ await Promise.all([server.ready, external.ready]);
}, 60_000);
afterAll(async () => {
- await server?.destroy();
+ await Promise.allSettled([server?.destroy(), external?.destroy()]);
await rm(tmpRoot, { recursive: true, force: true });
});
@@ -62,4 +81,61 @@ describe('lint group over the composed listener — served natively', () => {
const lintConfig = await fetch(`http://127.0.0.1:${server.port}/api/lint/config`);
expect(lintConfig.status).toBe(200);
});
+
+ test('the three writes retain conditional admission under external consent', async () => {
+ for (const path of WRITE_POSTS) {
+ const refused = await rawRequest(external.port, path, {
+ method: 'OPTIONS',
+ headers: {
+ Host: 'evil.example',
+ Origin: 'https://lint.example.com',
+ 'X-Forwarded-For': '203.0.113.8',
+ 'X-Request-Id': 'outer-refusal',
+ },
+ });
+ expect(refused.status, `${path}: ${refused.body}`).toBe(403);
+ expect(refused.headers['x-request-id']).toBeUndefined();
+ expect(refused.headers['access-control-allow-origin']).toBeUndefined();
+ expect(parseProblem(refused.body).type).toBe('urn:ok:error:host-not-allowed');
+
+ const origin = await rawRequest(external.port, path, {
+ method: 'PATCH',
+ headers: {
+ Host: 'lint.example.com',
+ Origin: 'https://evil.example',
+ 'X-Forwarded-For': '203.0.113.8',
+ 'X-Request-Id': 'origin-refusal',
+ },
+ body: '{',
+ });
+ expect(origin.status, `${path}: ${origin.body}`).toBe(403);
+ expect(origin.headers['x-request-id']).toBe('origin-refusal');
+ expect(origin.headers['access-control-allow-origin']).toBeUndefined();
+ expect(parseProblem(origin.body).type).toBe('urn:ok:error:invalid-origin');
+
+ const wrongMethod = await rawRequest(external.port, path, {
+ method: 'PATCH',
+ headers: {
+ Host: 'lint.example.com',
+ Origin: 'https://lint.example.com',
+ 'X-Forwarded-For': '203.0.113.8',
+ },
+ body: '{',
+ });
+ expect(wrongMethod.status, `${path}: ${wrongMethod.body}`).toBe(405);
+ expect(wrongMethod.headers.allow).toBe('POST');
+ expect(wrongMethod.headers['access-control-allow-origin']).toBe('https://lint.example.com');
+
+ const preflight = await rawRequest(external.port, path, {
+ method: 'OPTIONS',
+ headers: {
+ Host: 'lint.example.com',
+ Origin: 'https://lint.example.com',
+ 'X-Forwarded-For': '203.0.113.8',
+ },
+ });
+ expect(preflight.status, path).toBe(204);
+ expect(preflight.headers['access-control-allow-origin']).toBe('https://lint.example.com');
+ }
+ });
});
diff --git a/packages/server/src/api-lint-config-preservation.test.ts b/packages/server/src/api-lint-config-preservation.test.ts
new file mode 100644
index 000000000..88b899fd7
--- /dev/null
+++ b/packages/server/src/api-lint-config-preservation.test.ts
@@ -0,0 +1,223 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import type { IncomingMessage } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { afterAll, beforeAll, expect, test } from 'vitest';
+import { createApiExtension } from './api-extension.test-helper.ts';
+import type { BootedServer } from './boot.ts';
+import {
+ bootCompositionRig,
+ makeCaptureRes,
+ makeSyntheticReq,
+} from './composition-rig.test-helper.ts';
+
+let root: string;
+let server: BootedServer;
+
+beforeAll(async () => {
+ root = mkdtempSync(join(tmpdir(), 'ok-lint-config-preservation-'));
+ const contentDir = join(root, 'composition');
+ mkdirSync(contentDir);
+ server = await bootCompositionRig(contentDir);
+ await server.ready;
+}, 60_000);
+
+afterAll(async () => {
+ await server?.destroy();
+ await rm(root, { recursive: true, force: true });
+});
+
+function createRig(
+ overrides: { getLinterBaseConfig?: () => never; signalChannel?: (channel: string) => void } = {},
+) {
+ const contentDir = mkdtempSync(join(root, 'content-'));
+ const homeDirOverride = mkdtempSync(join(root, 'home-'));
+ const extension = createApiExtension({
+ contentDir,
+ projectDir: contentDir,
+ homeDirOverride,
+ hocuspocus: server.serverInstance.hocuspocus,
+ sessionManager: server.serverInstance.sessionManager,
+ ...overrides,
+ });
+ return { contentDir, extension };
+}
+
+async function post(
+ extension: ReturnType<typeof createApiExtension>,
+ path: string,
+ body: Record<string, unknown>,
+): Promise<{ status: number; body: Record<string, unknown> }> {
+ const base = makeSyntheticReq({ method: 'POST', url: path });
+ const req = Object.assign(Readable.from([Buffer.from(JSON.stringify(body))]), {
+ method: 'POST',
+ url: path,
+ headers: { ...base.headers, 'content-type': 'application/json' },
+ socket: base.socket,
+ }) as IncomingMessage;
+ const { res, captured } = makeCaptureRes();
+ await extension.onRequest({ request: req, response: res });
+ return {
+ status: captured.status,
+ body: JSON.parse(captured.body) as Record<string, unknown>,
+ };
+}
+
+test('accepted config actions preserve their synchronous invalidation schedule', async () => {
+ const signals: string[] = [];
+ const { contentDir, extension } = createRig({
+ signalChannel: (channel) => signals.push(channel),
+ });
+
+ const markdown = await post(extension, '/api/lint/markdownlint-config', {
+ ruleId: 'MD012',
+ value: false,
+ });
+ expect(markdown.status).toBe(200);
+ expect(signals.splice(0)).toEqual(['lint-config']);
+
+ const file = '.ok/schemas/signals.schema.json';
+ const created = await post(extension, '/api/lint/frontmatter-schema', { file });
+ expect(created.status).toBe(200);
+ expect(signals.splice(0)).toEqual(['files', 'lint-config']);
+
+ const noop = await post(extension, '/api/lint/frontmatter-schema', { file });
+ expect(noop.status).toBe(200);
+ expect(signals.splice(0)).toEqual(['lint-config']);
+
+ const written = await post(extension, '/api/lint/frontmatter-schema', {
+ file,
+ field: 'status',
+ constraint: { type: 'string' },
+ });
+ expect(written.status).toBe(200);
+ expect(signals.splice(0)).toEqual(['lint-config']);
+
+ const deleted = await post(extension, '/api/lint/frontmatter-schema', {
+ file,
+ delete: true,
+ });
+ expect(deleted.status).toBe(200);
+ expect(signals.splice(0)).toEqual(['files', 'lint-config']);
+
+ const idempotentDelete = await post(extension, '/api/lint/frontmatter-schema', {
+ file,
+ delete: true,
+ });
+ expect(idempotentDelete.status).toBe(200);
+ expect(signals.splice(0)).toEqual(['files', 'lint-config']);
+
+ writeFileSync(join(contentDir, '.markdownlint.json'), JSON.stringify({ MD012: false }));
+ const removed = await post(extension, '/api/lint/markdownlint-config', {
+ ruleId: 'MD012',
+ value: null,
+ });
+ expect(removed.status).toBe(200);
+ expect(signals.splice(0)).toEqual(['lint-config']);
+
+ const markdownNoop = await post(extension, '/api/lint/markdownlint-config', {
+ ruleId: 'MD012',
+ value: null,
+ });
+ expect(markdownNoop.status).toBe(200);
+ expect(signals).toEqual(['lint-config']);
+});
+
+test('refused and failed config writes leave accepted-write invalidation silent', async () => {
+ const markdownSignals: string[] = [];
+ const markdownRig = createRig({
+ signalChannel: (channel) => markdownSignals.push(channel),
+ });
+ writeFileSync(
+ join(markdownRig.contentDir, '.markdownlint.cjs'),
+ 'module.exports = { MD012: false };\n',
+ );
+ const declined = await post(markdownRig.extension, '/api/lint/markdownlint-config', {
+ ruleId: 'MD012',
+ value: true,
+ });
+ expect(declined.status).toBe(409);
+ expect(declined.body.type).toBe('urn:ok:error:config-not-writable');
+ expect(markdownSignals).toEqual([]);
+
+ const frontmatterSignals: string[] = [];
+ const frontmatterRig = createRig({
+ signalChannel: (channel) => frontmatterSignals.push(channel),
+ });
+ const refused = await post(frontmatterRig.extension, '/api/lint/frontmatter-schema', {
+ file: '../escape.schema.json',
+ });
+ expect(refused.status).toBe(409);
+ expect(refused.body.type).toBe('urn:ok:error:config-not-writable');
+ expect(frontmatterSignals).toEqual([]);
+
+ const markdownFailureSignals: string[] = [];
+ const markdownFailureRig = createRig({
+ signalChannel: (channel) => markdownFailureSignals.push(channel),
+ });
+ mkdirSync(join(markdownFailureRig.contentDir, '.markdownlint.json'));
+ const markdownFailure = await post(
+ markdownFailureRig.extension,
+ '/api/lint/markdownlint-config',
+ { ruleId: 'MD012', value: false },
+ );
+ expect(markdownFailure.status).toBe(500);
+ expect(markdownFailure.body.title).toBe('Failed to write markdownlint config.');
+ expect(markdownFailureSignals).toEqual([]);
+
+ const frontmatterFailureSignals: string[] = [];
+ const frontmatterFailureRig = createRig({
+ signalChannel: (channel) => frontmatterFailureSignals.push(channel),
+ });
+ writeFileSync(join(frontmatterFailureRig.contentDir, '.ok'), 'not a directory');
+ const frontmatterFailure = await post(
+ frontmatterFailureRig.extension,
+ '/api/lint/frontmatter-schema',
+ { file: '.ok/schemas/failure.schema.json' },
+ );
+ expect(frontmatterFailure.status).toBe(500);
+ expect(frontmatterFailure.body.title).toBe('Failed to write the frontmatter schema.');
+ expect(frontmatterFailureSignals).toEqual([]);
+});
+
+test('saved config changes and invalidation survive an effective-config reread failure', async () => {
+ const markdownSignals: string[] = [];
+ const markdownRig = createRig({
+ getLinterBaseConfig: () => {
+ throw new Error('controlled reread failure');
+ },
+ signalChannel: (channel) => markdownSignals.push(channel),
+ });
+ const markdown = await post(markdownRig.extension, '/api/lint/markdownlint-config', {
+ ruleId: 'MD012',
+ value: false,
+ });
+ expect(markdown.status).toBe(500);
+ expect(markdown.body.title).toBe(
+ 'The markdownlint rule was saved, but the effective config could not be re-read.',
+ );
+ expect(readFileSync(join(markdownRig.contentDir, '.markdownlint.json'), 'utf-8')).toContain(
+ '"MD012": false',
+ );
+ expect(markdownSignals).toEqual(['lint-config']);
+
+ const frontmatterSignals: string[] = [];
+ const frontmatterRig = createRig({
+ getLinterBaseConfig: () => {
+ throw new Error('controlled reread failure');
+ },
+ signalChannel: (channel) => frontmatterSignals.push(channel),
+ });
+ const file = '.ok/schemas/saved.schema.json';
+ const frontmatter = await post(frontmatterRig.extension, '/api/lint/frontmatter-schema', {
+ file,
+ });
+ expect(frontmatter.status).toBe(500);
+ expect(frontmatter.body.title).toBe(
+ 'The schema was saved, but the effective config could not be re-read.',
+ );
+ expect(existsSync(join(frontmatterRig.contentDir, file))).toBe(true);
+ expect(frontmatterSignals).toEqual(['files', 'lint-config']);
+});
diff --git a/packages/server/src/api-skills-cache.test.ts b/packages/server/src/api-skills-cache.test.ts
index 01519119a..7293fb4b3 100644
--- a/packages/server/src/api-skills-cache.test.ts
+++ b/packages/server/src/api-skills-cache.test.ts
@@ -126,6 +126,22 @@ test.each([false, true])(
},
);
+test('a frontmatter schema creation refreshes the skills cache and schedules files before lint', async () => {
+ const signals: string[] = [];
+ const r = rig((channel) => signals.push(channel));
+ vi.spyOn(Date, 'now').mockReturnValue(100_000);
+ expect(await description(r.extension)).toBe('before');
+ writeSkill(r.contentDir, '.ok/skills/alpha', 'after');
+ expect(await description(r.extension)).toBe('before');
+
+ await request(r.extension, '/api/lint/frontmatter-schema', 'POST', {
+ file: '.ok/schemas/cache-refresh.schema.json',
+ });
+
+ expect(await description(r.extension)).toBe('after');
+ expect(signals).toEqual(['files', 'lint-config']);
+});
+
test('a detected editor fingerprint change refreshes list content before expiry', async () => {
const r = rig();
vi.spyOn(Date, 'now').mockReturnValue(100_000);
diff --git a/packages/server/src/http/handler-equivalence.test-helper.ts b/packages/server/src/http/handler-equivalence.test-helper.ts
index 57c7969dc..3b88739ee 100644
--- a/packages/server/src/http/handler-equivalence.test-helper.ts
+++ b/packages/server/src/http/handler-equivalence.test-helper.ts
@@ -2,7 +2,7 @@ import { type Node, Project, SyntaxKind, ts } from 'ts-morph';
export type NormalizedSyntax = readonly [kind: string, value: string | readonly NormalizedSyntax[]];
-function readHandlerDeclaration(source: string, handlerName: string): Node {
+function sourceFile(source: string) {
const project = new Project({
useInMemoryFileSystem: true,
skipFileDependencyResolution: true,
@@ -10,11 +10,20 @@ function readHandlerDeclaration(source: string, handlerName: string): Node {
skipAddingFilesFromTsConfig: true,
compilerOptions: { noLib: true },
});
- const sourceFile = project.createSourceFile('handler.ts', source);
- const declaration = sourceFile
+ const file = project.createSourceFile('handler.ts', source);
+ if (project.getProgram().getSyntacticDiagnostics(file).length > 0) {
+ throw new Error('handler.ts must parse');
+ }
+ return file;
+}
+
+function readHandlerDeclaration(source: string, handlerName: string): Node {
+ const declarations = sourceFile(source)
.getDescendantsOfKind(SyntaxKind.VariableDeclaration)
- .find((candidate) => candidate.getName() === handlerName);
- if (declaration === undefined) throw new Error(`${handlerName} is absent`);
+ .filter((candidate) => candidate.getName() === handlerName);
+ if (declarations.length === 0) throw new Error(`${handlerName} is absent`);
+ if (declarations.length > 1) throw new Error(`duplicate ${handlerName}`);
+ const declaration = declarations[0];
const statement = declaration.getFirstAncestorByKind(SyntaxKind.VariableStatement);
if (statement === undefined) throw new Error(`${handlerName} has no statement`);
return statement;
@@ -56,3 +65,10 @@ export function orderedComments(source: string, handlerName: string): string[] {
}
return comments;
}
+
+export function handlerNames(source: string): string[] {
+ return sourceFile(source)
+ .getDescendantsOfKind(SyntaxKind.VariableDeclaration)
+ .map((declaration) => declaration.getName())
+ .filter((name) => name.startsWith('handle'));
+}
diff --git a/packages/server/src/http/handler-equivalence.test.ts b/packages/server/src/http/handler-equivalence.test.ts
index 39d25c3fb..3604525ad 100644
--- a/packages/server/src/http/handler-equivalence.test.ts
+++ b/packages/server/src/http/handler-equivalence.test.ts
@@ -1,5 +1,9 @@
import { describe, expect, test } from 'vitest';
-import { normalizedHandler, orderedComments } from './handler-equivalence.test-helper.ts';
+import {
+ handlerNames,
+ normalizedHandler,
+ orderedComments,
+} from './handler-equivalence.test-helper.ts';
const HANDLER_NAME = 'handleExample';
const BASELINE = `
@@ -37,4 +41,22 @@ describe('handler equivalence test helper', () => {
'handleExample is absent',
);
});
+
+ test('fails on duplicate declarations and malformed source', () => {
+ expect(() =>
+ normalizedHandler(
+ 'const handleExample = () => 1; const handleExample = () => 2;',
+ HANDLER_NAME,
+ ),
+ ).toThrow('duplicate handleExample');
+ expect(() => normalizedHandler('const handleExample = () => {', HANDLER_NAME)).toThrow(
+ 'handler.ts must parse',
+ );
+ });
+
+ test('lists handler variable declarations in source order', () => {
+ expect(
+ handlerNames('const handleOne = () => 1; const other = 2; const handleTwo = 3;'),
+ ).toEqual(['handleOne', 'handleTwo']);
+ });
});
diff --git a/packages/server/src/http/lint-write-routes.test.ts b/packages/server/src/http/lint-write-routes.test.ts
new file mode 100644
index 000000000..087516e2a
--- /dev/null
+++ b/packages/server/src/http/lint-write-routes.test.ts
@@ -0,0 +1,179 @@
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import type { IncomingMessage } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { Hocuspocus } from '@hocuspocus/server';
+import { afterEach, describe, expect, test } from 'vitest';
+import { AgentSessionManager } from '../agent-sessions.ts';
+import { makeCaptureRes } from '../composition-rig.test-helper.ts';
+import { loggerFactory } from '../logger.ts';
+import { createLintWriteRoutes } from './lint-write-routes.ts';
+
+type Deps = Parameters<typeof createLintWriteRoutes>[0];
+
+const roots: string[] = [];
+
+afterEach(async () => {
+ await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+function notDispatched(): never {
+ throw new Error('Dependency is not used by this test');
+}
+
+function buildGroup(overrides: Partial<Deps> = {}) {
+ const contentDir = mkdtempSync(join(tmpdir(), 'ok-lint-write-routes-'));
+ roots.push(contentDir);
+ const hocuspocus = new Hocuspocus({ quiet: true });
+ const deps = {
+ contentDir,
+ projectDir: undefined,
+ signalLintConfigChanged: notDispatched,
+ getLinterBaseConfig: undefined,
+ unmatchedGlobProblems: () => [],
+ signalChannel: undefined,
+ requireNonEmptyDocName: notDispatched,
+ resolveAlias: (docName) => docName,
+ getPrincipal: undefined,
+ resolveDocFilePath: notDispatched,
+ summaryResponseFields: () => ({ stored: undefined }),
+ sessionManager: new AgentSessionManager(hocuspocus),
+ options: {},
+ agentPresenceBroadcaster: undefined,
+ buildAgentActor: notDispatched,
+ flushDiskAndDetectOutcome: notDispatched,
+ respondPersistenceFailure: notDispatched,
+ respondDiskDivergence: notDispatched,
+ respondStaleExternalWrite: notDispatched,
+ flushDocToDisk: notDispatched,
+ log: loggerFactory.getLogger('test'),
+ ...overrides,
+ } satisfies Deps;
+ return { contentDir, group: createLintWriteRoutes(deps), sessionManager: deps.sessionManager };
+}
+
+function makeReq(path: string, body: unknown): IncomingMessage {
+ const req = Readable.from(Buffer.from(JSON.stringify(body))) as unknown as IncomingMessage;
+ req.method = 'POST';
+ req.url = path;
+ req.headers = { host: 'localhost', 'content-type': 'application/json' };
+ return req;
+}
+
+async function dispatch(
+ group: ReturnType<typeof createLintWriteRoutes>,
+ path: string,
+ body: unknown,
+) {
+ const route = group.table.resolve(path);
+ if (!route?.dispatch) throw new Error(`${path} did not resolve to a dispatch handler`);
+ const { res, captured } = makeCaptureRes();
+ await route.dispatch(makeReq(path, body), res);
+ return captured;
+}
+
+const PATHS = ['/api/lint/markdownlint-config', '/api/lint/frontmatter-schema', '/api/lint/fix'];
+
+describe('createLintWriteRoutes table', () => {
+ test('registers exactly the three lint write paths and classifies all three as mutating', async () => {
+ const { group, sessionManager } = buildGroup();
+ try {
+ expect([...group.paths].sort()).toEqual([...PATHS].sort());
+ for (const path of PATHS) expect(group.table.isMutating(path), path).toBe(true);
+ } finally {
+ await sessionManager.closeAll();
+ }
+ });
+});
+
+describe('createLintWriteRoutes config handlers', () => {
+ test('persists a markdownlint rule before invalidating the shared config generation', async () => {
+ const signals: string[] = [];
+ const { contentDir, group, sessionManager } = buildGroup({
+ signalLintConfigChanged: () => signals.push('lint-config'),
+ });
+ try {
+ const response = await dispatch(group, '/api/lint/markdownlint-config', {
+ ruleId: 'MD012',
+ value: false,
+ });
+ expect(response.status).toBe(200);
+ expect(readFileSync(join(contentDir, '.markdownlint.json'), 'utf8')).toContain(
+ '"MD012": false',
+ );
+ expect(signals).toEqual(['lint-config']);
+ } finally {
+ await sessionManager.closeAll();
+ }
+ });
+
+ test('creates a frontmatter schema and schedules files before lint invalidation', async () => {
+ const signals: string[] = [];
+ const { contentDir, group, sessionManager } = buildGroup({
+ signalChannel: (channel) => signals.push(channel),
+ signalLintConfigChanged: () => signals.push('lint-config'),
+ });
+ try {
+ const response = await dispatch(group, '/api/lint/frontmatter-schema', {
+ file: '.ok/schemas/native.schema.json',
+ });
+ expect(response.status).toBe(200);
+ expect(
+ JSON.parse(readFileSync(join(contentDir, '.ok/schemas/native.schema.json'), 'utf8')),
+ ).toEqual({ $schema: 'http://json-schema.org/draft-07/schema#', type: 'object' });
+ expect(signals).toEqual(['files', 'lint-config']);
+ } finally {
+ await sessionManager.closeAll();
+ }
+ });
+
+ test('rejects __proto__ schema fields with a caller-facing validation detail', async () => {
+ const { group, sessionManager } = buildGroup();
+ try {
+ const response = await dispatch(group, '/api/lint/frontmatter-schema', {
+ file: '.ok/schemas/native.schema.json',
+ field: '__proto__',
+ constraint: { type: 'string' },
+ });
+ expect(response.status).toBe(400);
+ expect(response.headers['content-type']).toContain('application/problem+json');
+ expect(JSON.parse(response.body)).toMatchObject({
+ type: 'urn:ok:error:invalid-request',
+ detail: 'field: schema property name cannot be __proto__',
+ });
+ } finally {
+ await sessionManager.closeAll();
+ }
+ });
+});
+
+describe('createLintWriteRoutes lint-fix capacity response', () => {
+ test('returns the retryable problem when the session limit is full', async () => {
+ const hocuspocus = new Hocuspocus({ quiet: true });
+ const sessionManager = new AgentSessionManager(hocuspocus, {
+ maxSessions: 1,
+ minEvictableIdleMs: Number.POSITIVE_INFINITY,
+ });
+ try {
+ await sessionManager.getSession('occupied', 'agent-occupant');
+ const { contentDir, group } = buildGroup({
+ sessionManager,
+ requireNonEmptyDocName: (docName) => docName ?? null,
+ resolveDocFilePath: () => 'note.md',
+ });
+ writeFileSync(join(contentDir, 'note.md'), '# Heading \n');
+ const response = await dispatch(group, '/api/lint/fix', { docName: 'note' });
+ expect(response.status).toBe(503);
+ expect(response.headers['content-type']).toContain('application/problem+json');
+ expect(response.headers['retry-after']).toBe('10');
+ expect(JSON.parse(response.body)).toMatchObject({
+ status: 503,
+ type: 'urn:ok:error:too-many-agent-sessions',
+ });
+ } finally {
+ await sessionManager.closeAll();
+ }
+ });
+});
diff --git a/packages/server/src/http/lint-write-routes.ts b/packages/server/src/http/lint-write-routes.ts
new file mode 100644
index 000000000..2a8340c8b
--- /dev/null
+++ b/packages/server/src/http/lint-write-routes.ts
@@ -0,0 +1,517 @@
+import type { ServerResponse } from 'node:http';
+import { resolve } from 'node:path';
+import {
+ AGENT_ICON_COLORS,
+ colorFromSeed,
+ DEFAULT_LINTER_CONFIG,
+ FrontmatterSchemaWriteRequestSchema,
+ LintConfigResponseSchema,
+ type LinterConfig,
+ LintFixRequestSchema,
+ LintFixResultSchema,
+ type LintPluginFailure,
+ lintDocument,
+ MarkdownlintRuleWriteRequestSchema,
+ type Principal,
+ type ReLintFailure,
+ summarizeLintPluginFailures,
+} from '@inkeep/open-knowledge-core';
+import type { AgentPresenceBroadcaster } from '../agent-presence.ts';
+import {
+ AgentSessionCapacityError,
+ type AgentSessionManager,
+ agentWriteLossDetect,
+ applyAgentMarkdownWrite,
+ iconFromClientName,
+} from '../agent-sessions.ts';
+import type { NormalizedSummary, SummaryResponse } from '../agent-write-summary.ts';
+import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';
+import { DocInConflictError, respondDocInConflict } from '../conflict-errors.ts';
+import { recordContributor } from '../contributor-tracker.ts';
+import type { StoreFailure } from '../document-durability-state.ts';
+import { extractActorIdentity } from '../extract-actor-identity.ts';
+import {
+ FrontmatterMalformedError,
+ respondFrontmatterMalformed,
+} from '../frontmatter-malformed-error.ts';
+import { assertNoSymlinkEscape, isContainmentRejection } from '../fs-safety.ts';
+import { lintAndFixSource } from '../lint/audit.ts';
+import {
+ createEmptyFrontmatterSchemaFile,
+ deleteFrontmatterSchemaFile,
+ removeFrontmatterSchemaField,
+ renameFrontmatterSchemaField,
+ type WriteFrontmatterSchemaResult,
+ writeFrontmatterSchemaField,
+} from '../lint/frontmatter-schema-write.ts';
+import { type WriteMarkdownlintResult, writeMarkdownlintRule } from '../lint/markdownlint-write.ts';
+import {
+ composeEffectiveLinterConfig,
+ composeFrontmatterSchemasConfig,
+ resolveNativeConfigForDoc,
+} from '../lint/resolve-config.ts';
+import type { PinoLogger } from '../logger.ts';
+import { type ApiRouteGroup, createApiRouteGroup } from './api-pipeline.ts';
+import { errorResponse } from './error-response.ts';
+import { withValidation } from './request-validation.ts';
+import { successResponse } from './success-response.ts';
+
+export interface LintWriteRouteDeps {
+ contentDir: string;
+ projectDir: string | undefined;
+ signalLintConfigChanged: () => void;
+ getLinterBaseConfig: (() => LinterConfig) | undefined;
+ unmatchedGlobProblems: (effective: LinterConfig) => string[];
+ signalChannel: ((channel: 'files' | 'lint-config' | 'comments') => void) | undefined;
+ requireNonEmptyDocName: (
+ docName: string | undefined,
+ res: ServerResponse,
+ handler: string,
+ ) => string | null;
+ resolveAlias: (docName: string) => string;
+ getPrincipal: (() => Principal | null) | undefined;
+ resolveDocFilePath: (contentDir: string, docName: string) => string | null;
+ summaryResponseFields: (normalized: NormalizedSummary) => {
+ response?: SummaryResponse;
+ stored: string | undefined;
+ };
+ sessionManager: AgentSessionManager;
+ options: {
+ resolveEmbed?: (basename: string, sourcePath: string) => string | null;
+ };
+ agentPresenceBroadcaster: AgentPresenceBroadcaster | undefined;
+ buildAgentActor: (args: {
+ clientName: string | undefined;
+ clientVersion?: string;
+ label?: string;
+ }) => {
+ principalId?: string;
+ agentType?: string;
+ clientName?: string;
+ clientVersion?: string;
+ label?: string;
+ };
+ flushDiskAndDetectOutcome: (
+ docName: string,
+ ) => Promise<
+ | { kind: 'failure'; failure: StoreFailure }
+ | { kind: 'divergence' }
+ | { kind: 'stale-external-write' }
+ | null
+ >;
+ respondPersistenceFailure: (res: ServerResponse, failure: StoreFailure, handler: string) => void;
+ respondDiskDivergence: (res: ServerResponse, handler: string) => void;
+ respondStaleExternalWrite: (res: ServerResponse, handler: string, docName: string) => void;
+ flushDocToDisk: (docName: string, label: string) => void;
+ log: PinoLogger;
+}
+
+export function createLintWriteRoutes(deps: LintWriteRouteDeps): ApiRouteGroup {
+ const {
+ contentDir,
+ projectDir,
+ signalLintConfigChanged,
+ getLinterBaseConfig,
+ unmatchedGlobProblems,
+ signalChannel,
+ requireNonEmptyDocName,
+ resolveAlias,
+ getPrincipal,
+ resolveDocFilePath,
+ summaryResponseFields,
+ sessionManager,
+ options,
+ agentPresenceBroadcaster,
+ buildAgentActor,
+ flushDiskAndDetectOutcome,
+ respondPersistenceFailure,
+ respondDiskDivergence,
+ respondStaleExternalWrite,
+ flushDocToDisk,
+ log,
+ } = deps;
+
+ const handleWriteMarkdownlintRule = withValidation(
+ MarkdownlintRuleWriteRequestSchema,
+ async (_req, res, body) => {
+ let writeResult: WriteMarkdownlintResult;
+ try {
+ writeResult = writeMarkdownlintRule(resolve(contentDir), body.ruleId, body.value);
+ } catch (e) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Failed to write markdownlint config.',
+ { handler: 'markdownlint-config', cause: e },
+ );
+ return;
+ }
+ if (writeResult.action === 'declined-executable') {
+ errorResponse(
+ res,
+ 409,
+ 'urn:ok:error:config-not-writable',
+ `The native markdownlint config (${writeResult.file}) is an executable module OK will not rewrite — edit it directly or convert it to JSON/JSONC/YAML.`,
+ { handler: 'markdownlint-config' },
+ );
+ return;
+ }
+ signalLintConfigChanged();
+ try {
+ const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
+ const configProblems: string[] = [];
+ const native = resolveNativeConfigForDoc(contentDir, undefined, (problem) =>
+ configProblems.push(problem),
+ );
+ const effective = composeFrontmatterSchemasConfig(
+ projectDir ?? contentDir,
+ composeEffectiveLinterConfig(base, native),
+ (problem) => configProblems.push(problem),
+ );
+ configProblems.push(...unmatchedGlobProblems(effective));
+ successResponse(
+ res,
+ 200,
+ LintConfigResponseSchema,
+ { effective, configFile: native?.file ?? null, configProblems },
+ { handler: 'markdownlint-config' },
+ );
+ } catch (e) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'The markdownlint rule was saved, but the effective config could not be re-read.',
+ { handler: 'markdownlint-config', cause: e },
+ );
+ }
+ },
+ { handler: 'markdownlint-config', method: 'POST' },
+ );
+
+ const handleWriteFrontmatterSchema = withValidation(
+ FrontmatterSchemaWriteRequestSchema,
+ async (_req, res, body) => {
+ let writeResult: WriteFrontmatterSchemaResult;
+ try {
+ const root = resolve(projectDir ?? contentDir);
+ const parentPath = body.parentPath ?? [];
+ writeResult = body.delete
+ ? deleteFrontmatterSchemaFile(root, body.file)
+ : body.field !== undefined && body.removeField
+ ? removeFrontmatterSchemaField(root, body.file, body.field, parentPath)
+ : body.field !== undefined && body.renameTo !== undefined
+ ? renameFrontmatterSchemaField(root, body.file, body.field, body.renameTo, parentPath)
+ : body.field !== undefined && body.constraint !== undefined
+ ? writeFrontmatterSchemaField(
+ root,
+ body.file,
+ body.field,
+ body.constraint,
+ parentPath,
+ )
+ : createEmptyFrontmatterSchemaFile(root, body.file);
+ } catch (e) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Failed to write the frontmatter schema.',
+ { handler: 'frontmatter-schema', cause: e },
+ );
+ return;
+ }
+ if (writeResult.action === 'refused') {
+ errorResponse(
+ res,
+ 409,
+ 'urn:ok:error:config-not-writable',
+ `The frontmatter schema (${writeResult.file}) was not written: ${writeResult.reason}.`,
+ { handler: 'frontmatter-schema' },
+ );
+ return;
+ }
+ if (writeResult.action === 'created' || writeResult.action === 'deleted') {
+ signalChannel?.('files');
+ }
+ signalLintConfigChanged();
+ try {
+ const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
+ const configProblems: string[] = [];
+ const native = resolveNativeConfigForDoc(contentDir, undefined, (problem) =>
+ configProblems.push(problem),
+ );
+ const effective = composeFrontmatterSchemasConfig(
+ projectDir ?? contentDir,
+ composeEffectiveLinterConfig(base, native),
+ (problem) => configProblems.push(problem),
+ );
+ configProblems.push(...unmatchedGlobProblems(effective));
+ successResponse(
+ res,
+ 200,
+ LintConfigResponseSchema,
+ { effective, configFile: native?.file ?? null, configProblems },
+ { handler: 'frontmatter-schema' },
+ );
+ } catch (e) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'The schema was saved, but the effective config could not be re-read.',
+ { handler: 'frontmatter-schema', cause: e },
+ );
+ }
+ },
+ { handler: 'frontmatter-schema', method: 'POST' },
+ );
+
+ const handleLintFix = withValidation(
+ LintFixRequestSchema,
+ async (_req, res, body) => {
+ try {
+ const effectiveDocName = requireNonEmptyDocName(body.docName, res, 'lint-fix');
+ if (effectiveDocName === null) return;
+ const resolvedDocName = resolveAlias(effectiveDocName);
+
+ const actor = extractActorIdentity(
+ body as unknown as Record<string, unknown>,
+ getPrincipal,
+ );
+ if (actor.kind === 'invalid-summary') {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
+ handler: 'lint-fix',
+ });
+ return;
+ }
+ const agentId = actor.kind === 'anonymous' ? 'principal-anonymous' : actor.writerId;
+ const agentName = actor.kind === 'anonymous' ? 'Anonymous' : actor.displayName;
+ const colorSeed = actor.kind === 'anonymous' ? agentId : actor.colorSeed;
+ const clientName = actor.kind === 'agent' ? actor.clientName : undefined;
+
+ if (isSystemDoc(resolvedDocName) || isConfigDoc(resolvedDocName)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `'${resolvedDocName}' is a reserved document name.`,
+ { handler: 'lint-fix' },
+ );
+ return;
+ }
+
+ const docRelPath = resolveDocFilePath(contentDir, resolvedDocName);
+ if (docRelPath === null) {
+ errorResponse(res, 404, 'urn:ok:error:doc-not-found', 'Document not found.', {
+ handler: 'lint-fix',
+ });
+ return;
+ }
+ assertNoSymlinkEscape(resolve(contentDir, docRelPath), contentDir);
+
+ const baseConfig = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
+ const { stored: storedSummary } = summaryResponseFields(actor.summary);
+ const session = await sessionManager.getSession(resolvedDocName, agentId, {
+ displayName: agentName,
+ colorSeed,
+ clientName,
+ });
+
+ const source = session.dc.document.getText('source').toString();
+ const configWarnings: string[] = [];
+ const { cfg, before, fixed, ran, failures } = await lintAndFixSource({
+ projectDir: projectDir ?? contentDir,
+ contentDir,
+ baseConfig,
+ docRelPath,
+ source,
+ onConfigProblem: (problem) => configWarnings.push(problem),
+ });
+
+ let after = before;
+ let reLintFailure: ReLintFailure | undefined;
+ const reLintFailures: LintPluginFailure[] = [];
+ if (fixed !== source) {
+ try {
+ const icon = iconFromClientName(clientName);
+ const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
+ agentPresenceBroadcaster?.setPresence(agentId, {
+ displayName: agentName,
+ icon,
+ color,
+ currentDoc: resolvedDocName,
+ mode: 'writing',
+ ts: Date.now(),
+ });
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(
+ session.dc.document,
+ fixed,
+ 'patch',
+ options.resolveEmbed
+ ? { resolveEmbed: options.resolveEmbed, sourcePath: resolvedDocName }
+ : undefined,
+ undefined,
+ agentWriteLossDetect(session),
+ );
+ }, session.origin);
+
+ if (actor.kind !== 'anonymous') {
+ recordContributor(
+ resolvedDocName,
+ agentId,
+ agentName,
+ colorSeed,
+ undefined,
+ actor.kind === 'agent'
+ ? buildAgentActor({
+ clientName: actor.clientName,
+ clientVersion: actor.clientVersion,
+ label: actor.label,
+ })
+ : actor.actor,
+ storedSummary,
+ );
+ }
+ } finally {
+ agentPresenceBroadcaster?.touchMode(agentId, 'idle');
+ }
+
+ const flushOutcome = await flushDiskAndDetectOutcome(resolvedDocName);
+ if (flushOutcome?.kind === 'failure') {
+ respondPersistenceFailure(res, flushOutcome.failure, 'lint-fix');
+ return;
+ }
+ if (flushOutcome?.kind === 'divergence') {
+ respondDiskDivergence(res, 'lint-fix');
+ return;
+ }
+ if (flushOutcome?.kind === 'stale-external-write') {
+ respondStaleExternalWrite(res, 'lint-fix', resolvedDocName);
+ return;
+ }
+ flushDocToDisk(resolvedDocName, 'lint-fix');
+
+ try {
+ after = await lintDocument(
+ session.dc.document.getText('source').toString(),
+ cfg,
+ docRelPath,
+ (failure) => reLintFailures.push(failure),
+ );
+ } catch (relintErr) {
+ const relintMessage =
+ relintErr instanceof Error ? relintErr.message : String(relintErr);
+ reLintFailure = {
+ reason: 're-lint-threw',
+ message:
+ relintMessage.trim().length > 0
+ ? relintMessage
+ : `${relintErr instanceof Error ? relintErr.name : 'non-Error value'} thrown with no message`,
+ };
+ log.warn(
+ { err: relintErr, handler: 'lint-fix', doc: resolvedDocName, agentId },
+ 'post-write re-lint failed; reporting pre-fix diagnostics',
+ );
+ after = before;
+ }
+ }
+
+ const blindBeforeFix = new Set(
+ failures.filter((f) => f.phase === 'lint').map((f) => f.source),
+ );
+ const blindOnlyAfterFix = [
+ ...new Set(
+ reLintFailures
+ .filter((f) => f.phase === 'lint' && !blindBeforeFix.has(f.source))
+ .map((f) => f.source),
+ ),
+ ];
+ if (reLintFailure === undefined && blindOnlyAfterFix.length > 0) {
+ reLintFailure = {
+ reason: 'source-went-blind',
+ message: `${blindOnlyAfterFix.join(', ')} linted the pre-fix text and failed on the post-fix text, so the re-lint is short their diagnostics and cannot be compared against the pre-fix run`,
+ };
+ log.warn(
+ { handler: 'lint-fix', doc: resolvedDocName, agentId, sources: blindOnlyAfterFix },
+ 'post-write re-lint lost a source that linted before the fix; reporting pre-fix diagnostics',
+ );
+ after = before;
+ }
+
+ const errorCount = after.filter((d) => d.severity === 'error').length;
+ const warningCount = after.length - errorCount;
+ const comparable = (d: (typeof before)[number]) => !blindBeforeFix.has(d.source);
+ const fixedCount = Math.max(
+ 0,
+ before.filter(comparable).length - after.filter(comparable).length,
+ );
+ const responseWarnings = [
+ ...configWarnings,
+ ...summarizeLintPluginFailures([...failures, ...reLintFailures]),
+ ];
+
+ successResponse(
+ res,
+ 200,
+ LintFixResultSchema,
+ {
+ file: docRelPath,
+ fixedCount,
+ diagnostics: after,
+ errorCount,
+ warningCount,
+ ran,
+ ...(responseWarnings.length > 0 ? { warnings: responseWarnings } : {}),
+ ...(reLintFailure ? { diagnosticsArePreFix: true, reLintFailure } : {}),
+ },
+ { handler: 'lint-fix' },
+ );
+ } catch (e) {
+ if (isContainmentRejection(e)) {
+ errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {
+ handler: 'lint-fix',
+ });
+ return;
+ }
+ if (e instanceof DocInConflictError) {
+ respondDocInConflict(res, e, 'lint-fix');
+ return;
+ }
+ if (e instanceof FrontmatterMalformedError) {
+ respondFrontmatterMalformed(res, e, 'lint-fix');
+ return;
+ }
+ if (e instanceof AgentSessionCapacityError) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:too-many-agent-sessions',
+ 'Too many agent sessions.',
+ { handler: 'lint-fix', cause: e, extraHeaders: { 'Retry-After': '10' } },
+ );
+ return;
+ }
+ log.error({ err: e }, '[lint-fix] handler failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to fix document.', {
+ handler: 'lint-fix',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'lint-fix', method: 'POST' },
+ );
+
+ return createApiRouteGroup(
+ {
+ '/api/lint/markdownlint-config': handleWriteMarkdownlintRule,
+ '/api/lint/frontmatter-schema': handleWriteFrontmatterSchema,
+ '/api/lint/fix': handleLintFix,
+ },
+ {
+ mutating: ['/api/lint/markdownlint-config', '/api/lint/frontmatter-schema', '/api/lint/fix'],
+ },
+ );
+}
diff --git a/packages/server/src/mcp-lint-http-preservation.test.ts b/packages/server/src/mcp-lint-http-preservation.test.ts
new file mode 100644
index 000000000..b8c42a541
--- /dev/null
+++ b/packages/server/src/mcp-lint-http-preservation.test.ts
@@ -0,0 +1,243 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { OK_DIR } from '@inkeep/open-knowledge-core';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
+import { type BootedServer, bootServer } from './boot.ts';
+import { ConfigSchema } from './config/schema.ts';
+import {
+ __formatContributorsForTests,
+ __resetContributorsForTests,
+} from './contributor-tracker.ts';
+
+const TEST_CONFIG = ConfigSchema.parse({
+ contentRules: { markdownlint: { enabled: true } },
+});
+const TABBED_BODY = '# Doc\n\n\tindented with a hard tab\n';
+
+interface ToolResult {
+ content?: Array<{ type: string; text?: string }>;
+ structuredContent?: Record<string, unknown>;
+ isError?: boolean;
+}
+
+interface ObservedLintRequest {
+ method: string | undefined;
+ body: Record<string, unknown>;
+}
+
+let tmpDir: string;
+let contentDir: string;
+let booted: BootedServer;
+let client: Client;
+let apiHits: string[];
+let nativeApiHits: string[];
+
+function observeLintRequests(): ObservedLintRequest[] {
+ const observed: ObservedLintRequest[] = [];
+ const realFetch = globalThis.fetch;
+ vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+ const rawUrl =
+ typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+ if (new URL(rawUrl).pathname === '/api/lint/fix') {
+ if (typeof init?.body !== 'string')
+ throw new Error('Expected a serialized lint request body');
+ observed.push({
+ method: init.method,
+ body: JSON.parse(init.body) as Record<string, unknown>,
+ });
+ }
+ return realFetch(input, init);
+ });
+ return observed;
+}
+
+function writeFixableDocument(docName: string): string {
+ const file = resolve(contentDir, `${docName}.md`);
+ mkdirSync(resolve(file, '..'), { recursive: true });
+ writeFileSync(file, TABBED_BODY, 'utf-8');
+ return file;
+}
+
+function resultText(result: ToolResult): string {
+ return result.content?.[0]?.text ?? '';
+}
+
+beforeAll(async () => {
+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-mcp-lint-http-'));
+ contentDir = resolve(tmpDir, 'project');
+ const okDir = resolve(contentDir, OK_DIR);
+ mkdirSync(okDir, { recursive: true });
+ writeFileSync(
+ resolve(okDir, 'config.yml'),
+ 'contentRules:\n markdownlint:\n enabled: true\n',
+ );
+ writeFileSync(resolve(okDir, '.gitignore'), '');
+
+ booted = await bootServer({
+ host: '127.0.0.1',
+ config: TEST_CONFIG,
+ contentDir,
+ port: 0,
+ quiet: true,
+ gitEnabled: false,
+ idleShutdownMs: null,
+ skipStateManifestCheck: true,
+ });
+ await booted.ready;
+
+ apiHits = [];
+ nativeApiHits = [];
+ booted.httpServer.on('request', (req) => {
+ const path = req.url?.split('?')[0];
+ if (path?.startsWith('/api/')) apiHits.push(path);
+ });
+ const nativeDispatch = booted.serverInstance.nativeApi.dispatch;
+ booted.serverInstance.nativeApi.dispatch = async (req, res) => {
+ const handled = await nativeDispatch(req, res);
+ if (handled) nativeApiHits.push(req.url?.split('?')[0] ?? '');
+ return handled;
+ };
+
+ client = new Client({ name: 'codex', version: '0.0.0-test' });
+ await client.connect(
+ new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${booted.port}/mcp`)),
+ );
+}, 60_000);
+
+beforeEach(() => {
+ apiHits.length = 0;
+ nativeApiHits.length = 0;
+ __resetContributorsForTests();
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+afterAll(async () => {
+ await client?.close().catch(() => {});
+ await booted?.destroy();
+ await rm(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+});
+
+describe('MCP lint fix over the composed HTTP server', () => {
+ test('fixes an extension-bearing document through the real lint HTTP endpoint with MCP identity', async () => {
+ const docName = `nested/sdk-lint-${randomUUID()}`;
+ const file = writeFixableDocument(docName);
+ const requests = observeLintRequests();
+
+ const result = (await client.callTool({
+ name: 'lint',
+ arguments: { document: `${docName}.md`, fix: true, cwd: contentDir },
+ })) as ToolResult;
+
+ expect(result.isError ?? false).toBe(false);
+ expect(result.content?.[0]?.text).toContain('Fixed 1 problem');
+ expect(result.structuredContent).toMatchObject({
+ fixedCount: 1,
+ errorCount: 0,
+ warningCount: 0,
+ ran: ['markdownlint'],
+ cwd: contentDir,
+ files: [{ file: `${docName}.md`, diagnostics: [] }],
+ });
+ expect(apiHits).toEqual(['/api/lint/fix']);
+ expect(nativeApiHits).toEqual(['/api/lint/fix']);
+ expect(requests).toHaveLength(1);
+ expect(requests[0]?.method).toBe('POST');
+ expect(requests[0]?.body).toMatchObject({
+ docName,
+ agentName: 'Codex',
+ clientName: 'codex',
+ });
+ expect(requests[0]?.body.agentId).toMatch(
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+ );
+ expect(requests[0]?.body.colorSeed).toBe('codex');
+ const disk = readFileSync(file, 'utf-8');
+ expect(disk).not.toContain('\t');
+
+ const writerId = `agent-${String(requests[0]?.body.agentId)}`;
+ expect(__formatContributorsForTests()).toContain(`"id":"${writerId}"`);
+ const session = booted.serverInstance.sessionManager.getLiveSession(docName, writerId);
+ expect(session?.dc.document.getText('source').toString()).toBe(disk);
+ expect(session?.origin.context).toMatchObject({
+ origin: 'agent-write',
+ paired: true,
+ session_id: requests[0]?.body.agentId,
+ agent_type: 'codex',
+ });
+ });
+
+ test('keeps an extension-less document name unchanged across the HTTP hop', async () => {
+ const docName = `sdk-lint-${randomUUID()}`;
+ const file = writeFixableDocument(docName);
+ const requests = observeLintRequests();
+
+ const result = (await client.callTool({
+ name: 'lint',
+ arguments: { document: docName, fix: true, cwd: contentDir },
+ })) as ToolResult;
+
+ expect(result.isError ?? false).toBe(false);
+ expect(requests).toHaveLength(1);
+ expect(requests[0]?.body.docName).toBe(docName);
+ expect(apiHits).toEqual(['/api/lint/fix']);
+ expect(nativeApiHits).toEqual(['/api/lint/fix']);
+ expect(readFileSync(file, 'utf-8')).not.toContain('\t');
+ });
+
+ test('rejects fix mode without a document before making a fix request', async () => {
+ const requests = observeLintRequests();
+
+ const result = (await client.callTool({
+ name: 'lint',
+ arguments: { fix: true, cwd: contentDir },
+ })) as ToolResult;
+
+ expect(result.isError).toBe(true);
+ expect(resultText(result)).toContain('requires `document`');
+ expect(requests).toEqual([]);
+ expect(apiHits).toEqual([]);
+ expect(nativeApiHits).toEqual([]);
+ });
+
+ test.each([
+ {
+ document: '../outside',
+ expected: 'docName must not contain',
+ expectedHits: [],
+ },
+ {
+ document: '__system__',
+ expected: 'reserved document name',
+ expectedHits: ['/api/lint/fix'],
+ },
+ {
+ document: `missing-${randomUUID()}`,
+ expected: 'Document not found',
+ expectedHits: ['/api/lint/fix'],
+ },
+ ])(
+ 'preserves the MCP failure projection for $document',
+ async ({ document, expected, expectedHits }) => {
+ const requests = observeLintRequests();
+
+ const result = (await client.callTool({
+ name: 'lint',
+ arguments: { document, fix: true, cwd: contentDir },
+ })) as ToolResult;
+
+ expect(result.isError).toBe(true);
+ expect(resultText(result)).toContain(expected);
+ expect(apiHits).toEqual(expectedHits);
+ expect(nativeApiHits).toEqual(expectedHits);
+ expect(requests).toHaveLength(expectedHits.length);
+ },
+ );
+});