Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.mdxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ },+ );+});