Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

47.1 KB
Raw Blame
import { mkdirSync } from 'node:fs';
import { join } from 'node:path';
import {
  AUDIT_EMPTY_SCOPE_WARNING,
  RE_LINT_FAILED_WARNING_PREFIX,
} from '@inkeep/open-knowledge-core';
import { normalizeObjectSchema } from '@modelcontextprotocol/sdk/server/zod-compat.js';
import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
import { afterAll, afterEach, beforeAll, describe, expect, test, vi } from 'vitest';
import { createTempDirFactory } from '../../../../../test-support/temp-dir.test-helper.ts';
import { type Config, ConfigSchema } from '../../config/schema.ts';
import { register as registerAudit } from './audit.ts';
import { register as registerConfig } from './config.ts';
import { register as registerEdit } from './edit.ts';
import { register as registerImport } from './import.ts';
import { registerAllTools } from './index.ts';
import { register as registerInstall } from './install.ts';
import { register as registerLint } from './lint.ts';
import { register as registerPalette } from './palette.ts';
import { register as registerSearch } from './search.ts';
import { AUDIT_WARNING_CAP, type ServerInstance, WARNINGS_FIELD_CONTRACT } from './shared.ts';

const makeTempDir = createTempDirFactory(afterAll);

const BASE_CONFIG: Config = ConfigSchema.parse({});

const legacyReLint = (message: string) => `${RE_LINT_FAILED_WARNING_PREFIX}${message}`;

interface ToolResult {
  content: Array<{ type: 'text'; text: string }>;
  structuredContent?: Record<string, unknown>;
  isError?: boolean;
}

type AnyHandler = (args: Record<string, unknown>) => Promise<ToolResult>;

interface Captured {
  cfg: {
    outputSchema?: Record<string, unknown>;
  };
  handler: AnyHandler;
}

function captureRegistration<TDeps>(
  register: (server: ServerInstance, deps: TDeps) => void,
  deps: TDeps,
): Captured {
  let captured: Captured | null = null;
  const server = {
    registerTool(
      _name: string,
      cfg: Captured['cfg'],
      handler: (
        args: Record<string, unknown>,
        extra: { signal: AbortSignal },
      ) => Promise<ToolResult>,
    ) {
      captured = {
        cfg,
        handler: (args) => handler(args, { signal: new AbortController().signal }),
      };
    },
    tool() {
      throw new Error('not used');
    },
  } as unknown as ServerInstance;
  register(server, deps);
  if (!captured) throw new Error('tool did not register');
  return captured;
}

function newProject(): string {
  const cwd = makeTempDir('ok-output-strict-');
  mkdirSync(join(cwd, '.ok'), { recursive: true });
  return cwd;
}

function compileOutputSchemaForClient(rawShape: unknown): Record<string, unknown> {
  const normalized = normalizeObjectSchema(rawShape);
  if (!normalized) {
    throw new Error('outputSchema did not normalize to an object schema');
  }
  return toJsonSchemaCompat(normalized, {
    strictUnions: true,
    pipeStrategy: 'output',
  }) as Record<string, unknown>;
}

describe('MCP outputSchema strictness — every registerTool+textPlusStructured tool must admit `text`', () => {
  function compileFromRegistration<TDeps>(
    register: (server: ServerInstance, deps: TDeps) => void,
    deps: TDeps,
  ): Record<string, unknown> {
    const captured = captureRegistration(register, deps);
    return compileOutputSchemaForClient(captured.cfg.outputSchema);
  }

  let cwd: string;
  beforeAll(() => {
    cwd = newProject();
  });
  const deps = { config: BASE_CONFIG, resolveCwd: async () => cwd };
  const depsWithServer = {
    config: BASE_CONFIG,
    resolveCwd: async () => cwd,
    serverUrl: undefined,
  };

  const cases: Array<{ name: string; build: () => Record<string, unknown> }> = [
    { name: 'config', build: () => compileFromRegistration(registerConfig, deps) },
    {
      name: 'palette',
      build: () => compileFromRegistration(registerPalette, deps),
    },
    { name: 'search', build: () => compileFromRegistration(registerSearch, depsWithServer) },
  ];

  for (const { name, build } of cases) {
    test(`${name}: outputSchema admits the auto-injected \`text\` field`, () => {
      const jsonSchema = build();
      const validator = new AjvJsonSchemaValidator();
      const probe = { text: 'mirror body' };
      const fn = validator.getValidator(jsonSchema);
      const result = fn(probe);
      if (!result.valid) {
        expect(result.errorMessage).not.toMatch(/additional propert/i);
      }
    });
  }
});

describe('MCP outputSchema strictness — auto-discovered registerTool sweep (no new tools may regress)', () => {
  interface RegisterToolCapture {
    name: string;
    outputSchema?: unknown;
  }

  function captureAllRegistrations(cwd: string): RegisterToolCapture[] {
    const captured: RegisterToolCapture[] = [];
    const server = {
      registerTool(name: string, cfg: { outputSchema?: unknown }, _handler: unknown) {
        captured.push({ name, outputSchema: cfg.outputSchema });
      },
      tool() {},
    } as unknown as ServerInstance;
    registerAllTools(server, {
      config: BASE_CONFIG,
      resolveCwd: async () => cwd,
      serverUrl: undefined,
    });
    return captured;
  }

  const KNOWN_REGISTER_TOOL_NAMES = new Set([
    'palette',
    'config',
    'preview_url',
    'search',
    'share_link',
    'history',
    'checkpoint',
    'restore_version',
    'delete',
    'move',
    'exec',
    'edit',
    'write',
    'links',
    'audit',
    'lint',
  ]);

  test('every registerTool registration declares `text` in its outputSchema', () => {
    const cwd = newProject();
    const registrations = captureAllRegistrations(cwd);

    const capturedNames = new Set(registrations.map((r) => r.name));
    for (const name of KNOWN_REGISTER_TOOL_NAMES) {
      expect(capturedNames).toContain(name);
    }
    expect(registrations.length).toBeGreaterThanOrEqual(KNOWN_REGISTER_TOOL_NAMES.size);

    const missingSchema = registrations
      .filter((r) => KNOWN_REGISTER_TOOL_NAMES.has(r.name) && r.outputSchema === undefined)
      .map((r) => r.name);
    expect(missingSchema).toEqual([]);

    const offenders: Array<{ name: string; error: string }> = [];
    const validator = new AjvJsonSchemaValidator();
    for (const { name, outputSchema } of registrations) {
      if (outputSchema === undefined) continue;
      const jsonSchema = compileOutputSchemaForClient(outputSchema);
      const probe = fn(validator, jsonSchema);
      if (!probe.valid && /additional propert/i.test(probe.errorMessage ?? '')) {
        offenders.push({ name, error: probe.errorMessage ?? '' });
      }
    }
    expect(offenders).toEqual([]);
  });

  function fn(
    validator: AjvJsonSchemaValidator,
    jsonSchema: Record<string, unknown>,
  ): { valid: boolean; errorMessage?: string } {
    const validate = validator.getValidator(jsonSchema);
    const probe = { text: 'mirror body' };
    return validate(probe) as { valid: boolean; errorMessage?: string };
  }
});

describe('audit and lint emitted coverage validates against the client schema', () => {
  afterEach(() => {
    vi.unstubAllGlobals();
  });

  const cases = [
    {
      name: 'audit',
      register: registerAudit,
      args: {},
      payload: {
        files: [],
        fileCount: 1,
        errorCount: 0,
        warningCount: 0,
        warnings: [],
        ran: ['markdownlint', 'links'],
      },
    },
    {
      name: 'lint project',
      register: registerLint,
      args: {},
      payload: {
        files: [],
        fileCount: 1,
        errorCount: 0,
        warningCount: 0,
        warnings: [],
        ran: ['markdownlint'],
      },
    },
    {
      name: 'lint document',
      register: registerLint,
      args: { document: 'notes' },
      payload: { file: 'notes.md', diagnostics: [], warnings: [], ran: ['frontmatter'] },
    },
    {
      name: 'lint fix',
      register: registerLint,
      args: { document: 'notes', fix: true },
      payload: {
        file: 'notes.md',
        fixedCount: 0,
        diagnostics: [],
        errorCount: 0,
        warningCount: 0,
        warnings: [],
        ran: [],
      },
    },
  ] as const;

  for (const testCase of cases) {
    test(`${testCase.name}: actual structuredContent admits ran`, async () => {
      const cwd = newProject();
      const captured = captureRegistration(testCase.register, {
        config: BASE_CONFIG,
        resolveCwd: async () => cwd,
        serverUrl: 'http://127.0.0.1:31337',
      });
      vi.stubGlobal(
        'fetch',
        vi.fn(async () => Response.json(testCase.payload)),
      );

      const result = await captured.handler(testCase.args);
      expect(result.structuredContent?.ran).toEqual(testCase.payload.ran);
      const validator = new AjvJsonSchemaValidator();
      const validate = validator.getValidator(
        compileOutputSchemaForClient(captured.cfg.outputSchema),
      );
      const validation = validate(result.structuredContent) as {
        valid: boolean;
        errorMessage?: string;
      };
      expect(validation.valid, validation.errorMessage).toBe(true);
    });
  }

  test.each([
    { name: 'audit', register: registerAudit },
    { name: 'lint', register: registerLint },
  ])('$name keeps empty-scope information distinct from degradation', async ({ register }) => {
    const cwd = newProject();
    const captured = captureRegistration(register, {
      config: BASE_CONFIG,
      resolveCwd: async () => cwd,
      serverUrl: 'http://127.0.0.1:31337',
    });
    const unknownWarning = 'No documents were checked: source could not be read.';
    for (const warnings of [
      [AUDIT_EMPTY_SCOPE_WARNING],
      [AUDIT_EMPTY_SCOPE_WARNING, unknownWarning],
    ]) {
      const payload = {
        files: [],
        fileCount: 0,
        errorCount: 0,
        warningCount: 0,
        warnings,
        ran: ['markdownlint'],
      };
      vi.stubGlobal(
        'fetch',
        vi.fn(async () => Response.json(payload)),
      );
      const result = await captured.handler({ path: 'empty' });
      expect(result.structuredContent).toMatchObject(payload);
      const text = result.content[0]?.text ?? '';
      expect(text).toContain(
        'No documents were checked in empty; this scope contains no admitted documents.',
      );
      expect(text).toContain('Checks selected: markdownlint; no document checks ran.');
      expect(text).not.toContain('No problems');
      if (warnings.length === 1) expect(text).not.toContain('incomplete');
      else {
        expect(text).toContain('incomplete — 1 warning');
        expect(text).toContain(unknownWarning);
      }
      const validate = new AjvJsonSchemaValidator().getValidator(
        compileOutputSchemaForClient(captured.cfg.outputSchema),
      );
      const validation = validate(result.structuredContent) as {
        valid: boolean;
        errorMessage?: string;
      };
      expect(validation.valid, validation.errorMessage).toBe(true);
    }
  });

  test.each([
    { name: 'audit', register: registerAudit },
    { name: 'lint', register: registerLint },
  ])(
    '$name reports a refused zero-document scope as incomplete, not empty',
    async ({ name, register }) => {
      const cwd = newProject();
      const captured = captureRegistration(register, {
        config: BASE_CONFIG,
        resolveCwd: async () => cwd,
        serverUrl: 'http://127.0.0.1:31337',
      });
      const refused = 'refusing audit scope under a hidden path segment: .ok';
      vi.stubGlobal(
        'fetch',
        vi.fn(async () =>
          Response.json({
            files: [],
            fileCount: 0,
            errorCount: 0,
            warningCount: 0,
            warnings: [refused],
            ran: ['markdownlint'],
          }),
        ),
      );
      const text = (await captured.handler({ path: 'private' })).content[0]?.text ?? '';
      expect(text).toContain(
        `No problems found across 0 documents in private, but the ${name} could not fully complete.`,
      );
      expect(text).toContain(`  ⚠ ${refused}`);
      expect(text).not.toContain('No documents were checked');
    },
  );

  test('audit text distinguishes clean, findings, empty selection, and degradation', async () => {
    const captured = captureRegistration(registerAudit, {
      config: BASE_CONFIG,
      resolveCwd: async () => newProject(),
      serverUrl: 'http://127.0.0.1:31337',
    });
    const call = async (payload: Record<string, unknown>): Promise<string> => {
      vi.stubGlobal(
        'fetch',
        vi.fn(async () => Response.json(payload)),
      );
      const result = await captured.handler({});
      return result.content[0]?.text ?? '';
    };
    const base = { fileCount: 1, errorCount: 0, warningCount: 0, warnings: [] };

    expect(await call({ ...base, files: [], ran: ['links'] })).toContain(
      'No problems across 1 document.\nChecks run: links.',
    );

    const findings = await call({
      ...base,
      files: [{ file: 'notes.md', diagnostics: [warningDiagnostic('links')] }],
      warningCount: 1,
      ran: ['links'],
    });
    expect(findings.endsWith('Checks run: links.')).toBe(true);

    expect(await call({ ...base, files: [], ran: [] })).toContain(
      'No problems across 1 document.\nNo checks ran.',
    );

    const degraded = await call({
      ...base,
      files: [],
      ran: ['links'],
      warnings: ['source family "links" validation failed: unavailable'],
    });
    expect(degraded).toContain('No problems found across 1 document');
    expect(degraded).toContain('Checks run: links.');
    expect(degraded).toContain('source family "links" validation failed: unavailable');
  });

  test('lint text distinguishes clean, findings, empty selection, fix, and degradation', async () => {
    const captured = captureRegistration(registerLint, {
      config: BASE_CONFIG,
      resolveCwd: async () => newProject(),
      serverUrl: 'http://127.0.0.1:31337',
    });
    const call = async (
      args: Record<string, unknown>,
      payload: Record<string, unknown>,
    ): Promise<string> => {
      vi.stubGlobal(
        'fetch',
        vi.fn(async () => Response.json(payload)),
      );
      const result = await captured.handler(args);
      return result.content[0]?.text ?? '';
    };

    expect(
      await call(
        { document: 'notes' },
        { file: 'notes.md', diagnostics: [], warnings: [], ran: ['frontmatter'] },
      ),
    ).toContain('No problems in notes.md.\nChecks run: frontmatter.');

    const findings = await call(
      { document: 'notes' },
      {
        file: 'notes.md',
        diagnostics: [warningDiagnostic('frontmatter')],
        warnings: [],
        ran: ['frontmatter'],
      },
    );
    expect(findings.endsWith('Checks run: frontmatter.')).toBe(true);

    expect(
      await call(
        {},
        {
          files: [],
          fileCount: 1,
          errorCount: 0,
          warningCount: 0,
          warnings: [],
          ran: [],
        },
      ),
    ).toContain('No problems across 1 document.\nNo checks ran.');

    expect(
      await call(
        { document: 'notes', fix: true },
        {
          file: 'notes.md',
          fixedCount: 0,
          diagnostics: [],
          errorCount: 0,
          warningCount: 0,
          ran: [],
        },
      ),
    ).toContain('No auto-fixable problems in notes.md.\nNo checks ran.');

    const degraded = await call(
      { document: 'notes' },
      {
        file: 'notes.md',
        diagnostics: [],
        ran: ['frontmatter'],
        warnings: ['source "frontmatter" lint failed on "notes.md": unavailable'],
      },
    );
    expect(degraded).toContain(
      'No problems found in notes.md, but the lint could not fully complete.\nChecks run: frontmatter.',
    );
    expect(degraded).toContain('Lint incomplete — 1 warning (findings may be partial):');
    expect(degraded).toContain('source "frontmatter" lint failed');

    const degradedAudit = await call(
      {},
      {
        files: [],
        fileCount: 3,
        errorCount: 0,
        warningCount: 0,
        ran: ['markdownlint'],
        warnings: ['source "markdownlint" lint failed on 3 documents (first: "a.md"): boom'],
      },
    );
    expect(degradedAudit).toContain(
      'No problems found across 3 documents, but the lint could not fully complete.\nChecks run: markdownlint.',
    );

    const degradedFix = await call(
      { document: 'notes', fix: true },
      {
        file: 'notes.md',
        fixedCount: 0,
        diagnostics: [],
        errorCount: 0,
        warningCount: 0,
        ran: ['markdownlint'],
        warnings: ['source "markdownlint" fix failed on "notes.md": boom'],
      },
    );
    expect(degradedFix).toContain(
      'No auto-fixable problems in notes.md, but the lint could not fully complete.',
    );
  });

  test('diagnosticsArePreFix drives the fix header, renders the bare reason once, and drops the remaining-problems footer', async () => {
    const captured = captureRegistration(registerLint, {
      config: BASE_CONFIG,
      resolveCwd: async () => newProject(),
      serverUrl: 'http://127.0.0.1:31337',
    });
    const reLint = legacyReLint('boom');
    const fixPayload = (
      warnings: string[],
      diagnosticsArePreFix?: boolean,
    ): Record<string, unknown> => ({
      file: 'notes.md',
      fixedCount: diagnosticsArePreFix ? 0 : 1,
      diagnostics: [warningDiagnostic('markdownlint')],
      errorCount: 0,
      warningCount: 1,
      ran: ['markdownlint'],
      warnings,
      ...(diagnosticsArePreFix === undefined ? {} : { diagnosticsArePreFix }),
    });
    const call = async (warnings: string[], diagnosticsArePreFix?: boolean) => {
      vi.stubGlobal(
        'fetch',
        vi.fn(async () => Response.json(fixPayload(warnings, diagnosticsArePreFix))),
      );
      return captured.handler({ document: 'notes', fix: true });
    };

    const result = await call([reLint], true);

    expect(result.structuredContent).not.toHaveProperty('warnings');
    expect(result.structuredContent).toMatchObject({
      diagnosticsArePreFix: true,
      reLintFailure: { reason: 're-lint-threw', message: 'boom' },
    });
    const text = result.content[0]?.text ?? '';
    expect(text.split('\n')[0]).toBe(
      'Applied auto-fixes to notes.md, but re-lint failed (boom); the fix landed — problems below are the pre-fix set, re-run `lint` to confirm.',
    );
    expect(text).not.toContain(RE_LINT_FAILED_WARNING_PREFIX);
    expect(text).not.toContain('problem remain');

    const legacyOnly = await (async () => {
      vi.stubGlobal(
        'fetch',
        vi.fn(async () =>
          Response.json({
            file: 'notes.md',
            fixedCount: 0,
            diagnostics: [warningDiagnostic('markdownlint')],
            errorCount: 0,
            warningCount: 1,
            ran: ['markdownlint'],
            warning: reLint,
          }),
        ),
      );
      return captured.handler({ document: 'notes', fix: true });
    })();
    const legacyText = legacyOnly.content[0]?.text ?? '';
    expect(legacyText.split('\n')[0]).toBe(
      'Applied auto-fixes to notes.md, but re-lint failed (boom); the fix landed — problems below are the pre-fix set, re-run `lint` to confirm.',
    );
    expect(legacyText).not.toContain('problem remain');
    expect(legacyOnly.structuredContent).not.toHaveProperty('warnings');
    expect(legacyOnly.structuredContent).toMatchObject({
      diagnosticsArePreFix: true,
      reLintFailure: { reason: 're-lint-threw', message: 'boom' },
    });

    const ordinary = await call(['source "markdownlint" lint failed on "notes.md": boom']);
    const ordinaryStructured = ordinary.structuredContent as { diagnosticsArePreFix?: boolean };
    expect(ordinaryStructured.diagnosticsArePreFix).toBeUndefined();
    const ordinaryText = ordinary.content[0]?.text ?? '';
    expect(ordinaryText.split('\n')[0]).toBe('Fixed 1 problem in notes.md.');
    expect(ordinaryText).toContain('1 problem remain');

    const validator = new AjvJsonSchemaValidator();
    const validate = validator.getValidator(
      compileOutputSchemaForClient(captured.cfg.outputSchema),
    );
    const validation = validate(result.structuredContent) as {
      valid: boolean;
      errorMessage?: string;
    };
    expect(validation.valid, validation.errorMessage).toBe(true);
  });

  test('the pre-fix signal survives a server that sends only the prefix or only the boolean', async () => {
    const captured = captureRegistration(registerLint, {
      config: BASE_CONFIG,
      resolveCwd: async () => newProject(),
      serverUrl: 'http://127.0.0.1:31337',
    });
    const call = async (extra: Record<string, unknown>) => {
      vi.stubGlobal(
        'fetch',
        vi.fn(async () =>
          Response.json({
            file: 'notes.md',
            fixedCount: 0,
            diagnostics: [warningDiagnostic('markdownlint')],
            errorCount: 0,
            warningCount: 1,
            ran: ['markdownlint'],
            ...extra,
          }),
        ),
      );
      return captured.handler({ document: 'notes', fix: true });
    };

    const prefixOnly = await call({ warnings: [legacyReLint('boom')] });
    expect(
      (prefixOnly.structuredContent as { diagnosticsArePreFix?: boolean }).diagnosticsArePreFix,
    ).toBe(true);
    expect(prefixOnly.structuredContent).not.toHaveProperty('warnings');
    expect(prefixOnly.structuredContent).toHaveProperty('reLintFailure', {
      reason: 're-lint-threw',
      message: 'boom',
    });
    const prefixText = prefixOnly.content[0]?.text ?? '';
    expect(prefixText.split('\n')[0]).toBe(
      'Applied auto-fixes to notes.md, but re-lint failed (boom); the fix landed — problems below are the pre-fix set, re-run `lint` to confirm.',
    );
    expect(prefixText).not.toContain(RE_LINT_FAILED_WARNING_PREFIX);
    expect(prefixText).not.toContain('problem remain');

    const booleanOnly = await call({ diagnosticsArePreFix: true });
    expect(booleanOnly.structuredContent).toHaveProperty('diagnosticsArePreFix', true);
    expect(booleanOnly.structuredContent).not.toHaveProperty('reLintFailure');
    expect((booleanOnly.content[0]?.text ?? '').split('\n')[0]).toBe(
      'Applied auto-fixes to notes.md, but re-lint failed; the fix landed — problems below are the pre-fix set, re-run `lint` to confirm.',
    );
  });

  test.each(['boom', ' \tboom\n '])(
    'reLintFailure alone marks diagnostics as pre-fix and carries its message in both outputs (%j)',
    async (message) => {
      const captured = captureRegistration(registerLint, {
        config: BASE_CONFIG,
        resolveCwd: async () => newProject(),
        serverUrl: 'http://127.0.0.1:31337',
      });
      const diagnostics = [warningDiagnostic('markdownlint')];
      vi.stubGlobal(
        'fetch',
        vi.fn(async () =>
          Response.json({
            file: 'notes.md',
            fixedCount: 0,
            diagnostics,
            ran: ['markdownlint'],
            reLintFailure: { reason: 'source-went-blind', message },
          }),
        ),
      );

      const result = await captured.handler({ document: 'notes', fix: true });
      const text = result.content[0]?.text ?? '';
      expect(text.split('\n')[0]).toBe(
        'Applied auto-fixes to notes.md, but re-lint failed (boom); the fix landed — problems below are the pre-fix set, re-run `lint` to confirm.',
      );
      expect(text.match(/boom/g)).toHaveLength(1);
      expect(text).not.toContain('problem remain');
      expect(result.structuredContent).toMatchObject({
        files: [{ file: 'notes.md', diagnostics }],
        fixedCount: 0,
        errorCount: 0,
        warningCount: 1,
        diagnosticsArePreFix: true,
        reLintFailure: { reason: 'source-went-blind', message: 'boom' },
      });
      expect(result.structuredContent).not.toHaveProperty('warnings');
      expect(result.structuredContent).not.toHaveProperty('warning');
      const validate = new AjvJsonSchemaValidator().getValidator(
        compileOutputSchemaForClient(captured.cfg.outputSchema),
      );
      const validation = validate(result.structuredContent);
      expect(validation.valid, validation.errorMessage).toBe(true);
    },
  );

  test.each([{}, { reason: 're-lint-threw', message: '   ' }])(
    'a malformed typed reLintFailure (%j) falls through to the legacy prefixed warning without throwing',
    async (reLintFailure) => {
      const captured = captureRegistration(registerLint, {
        config: BASE_CONFIG,
        resolveCwd: async () => newProject(),
        serverUrl: 'http://127.0.0.1:31337',
      });
      vi.stubGlobal(
        'fetch',
        vi.fn(async () =>
          Response.json({
            file: 'notes.md',
            fixedCount: 0,
            diagnostics: [warningDiagnostic('markdownlint')],
            ran: ['markdownlint'],
            warnings: [legacyReLint('legacy reason')],
            reLintFailure,
          }),
        ),
      );

      const result = await captured.handler({ document: 'notes', fix: true });
      expect(result.isError).toBeUndefined();
      expect(result.structuredContent).toMatchObject({
        diagnosticsArePreFix: true,
        reLintFailure: { reason: 're-lint-threw', message: 'legacy reason' },
      });
      expect(result.structuredContent).not.toHaveProperty('warnings');
      const text = result.content[0]?.text ?? '';
      expect(text.split('\n')[0]).toContain('re-lint failed (legacy reason);');
      expect(text).not.toContain(RE_LINT_FAILED_WARNING_PREFIX);
      const validate = new AjvJsonSchemaValidator().getValidator(
        compileOutputSchemaForClient(captured.cfg.outputSchema),
      );
      const validation = validate(result.structuredContent);
      expect(validation.valid, validation.errorMessage).toBe(true);
    },
  );

  test.each([
    { reLintFailure: undefined, reason: 're-lint-threw', message: 'plural reason' },
    {
      reLintFailure: { reason: 'source-went-blind', message: '  typed reason  ' },
      reason: 'source-went-blind',
      message: 'typed reason',
    },
  ])(
    'fix output keeps ordinary warnings and normalizes legacy failures to $message',
    async ({ reLintFailure, reason, message }) => {
      const captured = captureRegistration(registerLint, {
        config: BASE_CONFIG,
        resolveCwd: async () => newProject(),
        serverUrl: 'http://127.0.0.1:31337',
      });
      const warnings = [
        'source "markdownlint" fix failed on "notes.md": unavailable',
        'frontmatter schema unavailable',
      ];
      vi.stubGlobal(
        'fetch',
        vi.fn(async () =>
          Response.json({
            file: 'notes.md',
            fixedCount: 0,
            diagnostics: [warningDiagnostic('markdownlint')],
            warnings: [
              warnings[0],
              legacyReLint('plural reason'),
              warnings[1],
              legacyReLint('another legacy reason'),
            ],
            warning: legacyReLint('singular reason'),
            reLintFailure,
          }),
        ),
      );

      const result = await captured.handler({ document: 'notes', fix: true });
      expect(result.structuredContent).toMatchObject({
        warnings,
        diagnosticsArePreFix: true,
        reLintFailure: { reason, message },
      });
      const text = result.content[0]?.text ?? '';
      expect(text.split('\n')[0]).toContain(`re-lint failed (${message});`);
      expect(text).toContain('Lint incomplete — 2 warnings (findings may be partial):');
      for (const warning of warnings) expect(text).toContain(warning);
      expect(text).not.toContain(RE_LINT_FAILED_WARNING_PREFIX);
      expect(text).not.toContain('another legacy reason');
      expect(text).not.toContain('singular reason');
      expect(text).not.toContain('problem remain');
    },
  );

  test('an older server that sends the same prefixed string in warning and warnings renders it once', async () => {
    const captured = captureRegistration(registerLint, {
      config: BASE_CONFIG,
      resolveCwd: async () => newProject(),
      serverUrl: 'http://127.0.0.1:31337',
    });
    vi.stubGlobal(
      'fetch',
      vi.fn(async () =>
        Response.json({
          file: 'notes.md',
          fixedCount: 0,
          diagnostics: [warningDiagnostic('markdownlint')],
          ran: ['markdownlint'],
          warning: legacyReLint('same'),
          warnings: [legacyReLint('same')],
        }),
      ),
    );

    const result = await captured.handler({ document: 'notes', fix: true });

    expect(result.structuredContent).not.toHaveProperty('warnings');
    expect(result.structuredContent).toMatchObject({
      diagnosticsArePreFix: true,
      reLintFailure: { reason: 're-lint-threw', message: 'same' },
    });
    const text = result.content[0]?.text ?? '';
    expect(text.split('\n')[0]).toBe(
      'Applied auto-fixes to notes.md, but re-lint failed (same); the fix landed — problems below are the pre-fix set, re-run `lint` to confirm.',
    );
    expect(text.match(/same/g)).toHaveLength(1);
    expect(text).not.toContain(RE_LINT_FAILED_WARNING_PREFIX);
  });

  test('a reason an older or newer server does not share normalizes to the closed discriminant', async () => {
    const captured = captureRegistration(registerLint, {
      config: BASE_CONFIG,
      resolveCwd: async () => newProject(),
      serverUrl: 'http://127.0.0.1:31337',
    });
    vi.stubGlobal(
      'fetch',
      vi.fn(async () =>
        Response.json({
          file: 'notes.md',
          fixedCount: 0,
          diagnostics: [warningDiagnostic('markdownlint')],
          ran: ['markdownlint'],
          reLintFailure: { reason: 'a-reason-from-the-future', message: 'still readable' },
        }),
      ),
    );

    const result = await captured.handler({ document: 'notes', fix: true });

    expect(result.structuredContent).toMatchObject({
      diagnosticsArePreFix: true,
      reLintFailure: { reason: 're-lint-threw', message: 'still readable' },
    });
    const validate = new AjvJsonSchemaValidator().getValidator(
      compileOutputSchemaForClient(captured.cfg.outputSchema),
    );
    const validation = validate(result.structuredContent);
    expect(validation.valid, validation.errorMessage).toBe(true);
  });

  test('lint audit caps the warning channel the way audit does', async () => {
    const captured = captureRegistration(registerLint, {
      config: BASE_CONFIG,
      resolveCwd: async () => newProject(),
      serverUrl: 'http://127.0.0.1:31337',
    });
    const warnings = Array.from({ length: AUDIT_WARNING_CAP + 5 }, (_, i) =>
      i === AUDIT_WARNING_CAP + 4 ? 'validator "lint" failed: EACCES' : `warning ${i}`,
    );
    vi.stubGlobal(
      'fetch',
      vi.fn(async () =>
        Response.json({
          files: [],
          fileCount: 1,
          errorCount: 0,
          warningCount: 0,
          ran: ['markdownlint'],
          warnings,
        }),
      ),
    );

    const result = await captured.handler({});

    const structured = result.structuredContent as {
      warnings?: string[];
      omittedWarningCount?: number;
    };
    expect(structured.warnings).toHaveLength(AUDIT_WARNING_CAP);
    expect(structured.warnings?.[0]).toBe('validator "lint" failed: EACCES');
    expect(structured.omittedWarningCount).toBe(5);
    const text = result.content[0]?.text ?? '';
    expect(text).toContain('… and 5 more warnings');

    const validator = new AjvJsonSchemaValidator();
    const validate = validator.getValidator(
      compileOutputSchemaForClient(captured.cfg.outputSchema),
    );
    const validation = validate(result.structuredContent) as {
      valid: boolean;
      errorMessage?: string;
    };
    expect(validation.valid, validation.errorMessage).toBe(true);
  });

  function warningDiagnostic(source: string): Record<string, unknown> {
    return {
      range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } },
      severity: 'warning',
      source,
      code: 'test',
      message: 'problem',
    };
  }
});

describe('the warnings-field contract is single-sourced across every tool that states it', () => {
  const INVARIANT_TAIL = WARNINGS_FIELD_CONTRACT.slice(
    WARNINGS_FIELD_CONTRACT.indexOf('`content[0].text`'),
  );

  function warningsDescriptions(tool: string, container: string | null): string[] {
    const cwd = newProject();
    const captured: Array<{ name: string; outputSchema?: unknown }> = [];
    const server = {
      registerTool(name: string, cfg: { outputSchema?: unknown }) {
        captured.push({ name, outputSchema: cfg.outputSchema });
      },
      tool() {},
    } as unknown as ServerInstance;
    registerAllTools(server, {
      config: BASE_CONFIG,
      resolveCwd: async () => cwd,
      serverUrl: undefined,
    });
    const registered = captured.find((r) => r.name === tool);
    if (!registered?.outputSchema) throw new Error(`${tool} did not register an outputSchema`);
    const found: string[] = [];
    const walk = (node: unknown, key: string | null): void => {
      if (!node || typeof node !== 'object') return;
      const record = node as Record<string, unknown>;
      if (key === 'warnings' && typeof record.description === 'string') {
        found.push(record.description);
      }
      for (const [childKey, child] of Object.entries(record.properties ?? {})) {
        walk(child, childKey);
      }
      for (const branch of ['items', 'anyOf', 'allOf', 'oneOf'] as const) {
        const value = record[branch];
        if (Array.isArray(value)) for (const entry of value) walk(entry, key);
        else if (value) walk(value, key);
      }
    };
    const compiled = compileOutputSchemaForClient(registered.outputSchema);
    const properties = (compiled.properties ?? {}) as Record<string, unknown>;
    walk(container === null ? compiled : properties[container], null);
    return found;
  }

  test.each([
    ['write', 'skill'],
    ['edit', 'skill'],
    ['install', null],
    ['import', null],
  ] as ReadonlyArray<readonly [string, string | null]>)(
    '%s states the same unreadable-payload invariant, verbatim',
    (tool, container) => {
      const descriptions = warningsDescriptions(tool, container);
      expect(descriptions.length).toBeGreaterThan(0);
      for (const description of descriptions) {
        expect(description).toContain(INVARIANT_TAIL);
      }
    },
  );
});

describe('move outputSchema admits the cross-level skill-move payloads (CORR-1)', () => {
  function moveOutputJsonSchema(): Record<string, unknown> {
    const cwd = newProject();
    const captured: Array<{ name: string; outputSchema?: unknown }> = [];
    const server = {
      registerTool(name: string, cfg: { outputSchema?: unknown }) {
        captured.push({ name, outputSchema: cfg.outputSchema });
      },
      tool() {},
    } as unknown as ServerInstance;
    registerAllTools(server, {
      config: BASE_CONFIG,
      resolveCwd: async () => cwd,
      serverUrl: undefined,
    });
    const move = captured.find((r) => r.name === 'move');
    if (!move?.outputSchema) throw new Error('move tool did not register an outputSchema');
    return compileOutputSchemaForClient(move.outputSchema);
  }

  const crossScopeSuccess = {
    ok: true,
    kind: 'skill',
    committed: false,
    crossScope: true,
    text: 'Moved skill "trip-log" (Project) → "trip-log" (Global). …',
  };
  const crossScopeRefusal = {
    ok: false,
    kind: 'skill',
    error: 'A global skill named "fishing-log" already exists.',
    moveState: 'nothing-written',
    droppedLocations: [],
    text: 'Error: A global skill named "fishing-log" already exists.',
  };
  const crossScopePartialFailure = {
    ok: false,
    kind: 'skill',
    error: 'Failed to move skill (source removal failed); destination copy retained for recovery.',
    moveState: 'destination-retained',
    sourceState: 'lossy',
    droppedLocations: ['.team/skills', 'agents'],
    text: 'Error: Failed to move skill (source removal failed); destination copy retained for recovery.',
  };
  const crossScopeRefusalWithUnverifiableOccupant = {
    ...crossScopeRefusal,
    retentionLedger: 'occupant-unverifiable',
  };
  const crossScopeRefusalWithUnreadableLedger = {
    ...crossScopeRefusal,
    retentionLedger: 'unreadable',
  };
  const crossScopeSuccessWithDroppedLocations = {
    ...crossScopeSuccess,
    droppedLocations: ['.team/skills', 'agents'],
  };

  for (const [label, payload] of [
    ['cross-level success', crossScopeSuccess],
    ['cross-level success carrying droppedLocations', crossScopeSuccessWithDroppedLocations],
    ['cross-level refusal (destination taken)', crossScopeRefusal],
    ['cross-level partial failure (destination retained)', crossScopePartialFailure],
    [
      'cross-level refusal with an unverifiable occupant',
      crossScopeRefusalWithUnverifiableOccupant,
    ],
    [
      'cross-level refusal with an unreadable retention ledger',
      crossScopeRefusalWithUnreadableLedger,
    ],
  ] as const) {
    test(`${label} structuredContent validates against the compiled move schema`, () => {
      const validator = new AjvJsonSchemaValidator();
      const validate = validator.getValidator(moveOutputJsonSchema());
      const result = validate(payload) as { valid: boolean; errorMessage?: string };
      expect(result.valid).toBe(true);
      if (!result.valid) {
        expect(result.errorMessage).not.toMatch(/additional propert/i);
      }
    });
  }
});

describe('share_link outputSchema admits emitted success and error payloads', () => {
  function shareLinkOutputJsonSchema(): Record<string, unknown> {
    const cwd = newProject();
    const captured: Array<{ name: string; outputSchema?: unknown }> = [];
    const server = {
      registerTool(name: string, cfg: { outputSchema?: unknown }) {
        captured.push({ name, outputSchema: cfg.outputSchema });
      },
      tool() {},
    } as unknown as ServerInstance;
    registerAllTools(server, {
      config: BASE_CONFIG,
      resolveCwd: async () => cwd,
      serverUrl: undefined,
    });
    const shareLink = captured.find((r) => r.name === 'share_link');
    if (!shareLink?.outputSchema) {
      throw new Error('share_link tool did not register an outputSchema');
    }
    return compileOutputSchemaForClient(shareLink.outputSchema);
  }

  const base = {
    ok: true,
    shareUrl: 'https://openknowledge.ai/d/enc',
    sharedUrl: 'https://github.com/o/r/blob/main/notes.md',
    branch: 'main',
    resolvedKind: 'doc',
    previewUrl: null,
  };
  const withFreshness = {
    ...base,
    freshness: 'stale',
    text: 'This doc has unpushed changes. Recipients will see the last pushed version.\n\nShare link for doc `notes` on branch `main`:\nhttps://openknowledge.ai/d/enc',
  };
  const withoutFreshness = {
    ...base,
    text: 'Share link for doc `notes` on branch `main`:\nhttps://openknowledge.ai/d/enc',
  };
  const withEmptyFreshness = {
    ...base,
    sharedUrl: 'https://github.com/o/r/tree/main/hollow',
    resolvedKind: 'folder',
    freshness: 'empty',
    text: "Git can't track this folder — it's empty or contains only ignored files. The link won't work until you add a tracked document.\n\nShare link for folder `hollow` on branch `main`:\nhttps://openknowledge.ai/d/enc",
  };
  const withUnsupportedUrlError = {
    ok: false,
    error: 'unsupported-share-url',
    message:
      'The GitHub URL cannot be represented by the share-link format. Use a canonical DNS GitHub host and a shorter repository path.',
    text: 'Error: The GitHub URL cannot be represented by the share-link format. Use a canonical DNS GitHub host and a shorter repository path.',
  };

  for (const [label, payload] of [
    ['success with freshness', withFreshness],
    ['success without freshness (happy-path passthrough)', withoutFreshness],
    ['success with the empty-folder verdict', withEmptyFreshness],
    ['unsupported share URL error', withUnsupportedUrlError],
  ] as const) {
    test(`${label} structuredContent validates against the compiled share_link schema`, () => {
      const validator = new AjvJsonSchemaValidator();
      const validate = validator.getValidator(shareLinkOutputJsonSchema());
      const result = validate(payload) as { valid: boolean; errorMessage?: string };
      expect(result.valid).toBe(true);
      if (!result.valid) {
        expect(result.errorMessage).not.toMatch(/additional propert/i);
      }
    });
  }
});

describe('skill warningCodes normalize across server skew (closed enum, 1:1 with warnings)', () => {
  afterEach(() => {
    vi.unstubAllGlobals();
  });

  const skillDeps = () => ({
    config: BASE_CONFIG,
    resolveCwd: async () => newProject(),
    serverUrl: 'http://127.0.0.1:31337',
  });

  const jsonRoutes = (routes: Array<[test: (url: string) => boolean, body: unknown]>) =>
    vi.fn(async (url: string | URL | Request) => {
      const href = String(url);
      const hit = routes.find(([matches]) => matches(href));
      if (!hit) throw new Error(`unexpected fetch: ${href}`);
      return Response.json(hit[1]);
    });

  const expectValidates = (captured: Captured, structured: unknown) => {
    const validate = new AjvJsonSchemaValidator().getValidator(
      compileOutputSchemaForClient(captured.cfg.outputSchema),
    );
    const validation = validate(structured);
    expect(validation.valid, validation.errorMessage).toBe(true);
  };

  test('edit withholds authoring codes a newer server skewed, and keeps every warning', async () => {
    const captured = captureRegistration(registerEdit, skillDeps());
    vi.stubGlobal(
      'fetch',
      jsonRoutes([
        [
          (href) => href.includes('/api/skill?'),
          { skill: { frontmatter: { description: 'old' }, body: 'body', files: [] } },
        ],
        [
          () => true,
          {
            path: '.agents/skills/review-bot/SKILL.md',
            created: false,
            warnings: ['Skill name contains "claude".', 'A warning from the future.'],
            warningCodes: ['skill-name-vendor-word', 'skill-warning-from-the-future'],
          },
        ],
      ]),
    );

    const result = await captured.handler({ skill: { name: 'review-bot', description: 'new' } });

    expect(result.isError).toBeUndefined();
    expect(result.structuredContent?.skill).toMatchObject({
      warnings: ['Skill name contains "claude".', 'A warning from the future.'],
    });
    expect(result.structuredContent?.skill).not.toHaveProperty('warningCodes');
    expect(result.content[0]?.text).toContain('A warning from the future.');
    expectValidates(captured, result.structuredContent);
  });

  test('import keeps a code-less half text and omits warningCodes rather than reporting an all-clear', async () => {
    const captured = captureRegistration(registerImport, skillDeps());
    vi.stubGlobal(
      'fetch',
      jsonRoutes([
        [
          (href) => href.endsWith('/api/skill/import'),
          {
            name: 'review-bot',
            warnings: ['Skill name contains "claude".', 'SKILL.md body is 600 lines.'],
            warningCodes: ['skill-name-vendor-word', 'skill-body-too-long'],
          },
        ],
        [() => true, { warnings: ['An older server sent no codes.'] }],
      ]),
    );

    const result = await captured.handler({ source: 'acme/skills', add: ['agents'] });

    expect(result.isError).toBeUndefined();
    expect(result.structuredContent).toMatchObject({
      warnings: [
        'Skill name contains "claude".',
        'SKILL.md body is 600 lines.',
        'An older server sent no codes.',
      ],
    });
    expect(result.structuredContent).not.toHaveProperty('warningCodes');
    expect(result.content[0]?.text).toContain('An older server sent no codes.');
    expectValidates(captured, result.structuredContent);
  });

  test('import withholds codes when a step sent one a newer server invented, and keeps every warning', async () => {
    const captured = captureRegistration(registerImport, skillDeps());
    vi.stubGlobal(
      'fetch',
      jsonRoutes([
        [(href) => href.endsWith('/api/skill/import'), { name: 'review-bot', warnings: [] }],
        [
          () => true,
          {
            warnings: ['A placement warning from the future.', 'Nothing was projected.'],
            warningCodes: ['place-from-the-future', 'no-targets'],
          },
        ],
      ]),
    );

    const result = await captured.handler({ source: 'acme/skills', add: ['agents'] });

    expect(result.structuredContent).toMatchObject({
      warnings: ['A placement warning from the future.', 'Nothing was projected.'],
    });
    expect(result.structuredContent).not.toHaveProperty('warningCodes');
    expect(result.content[0]?.text).toContain('A placement warning from the future.');
    expectValidates(captured, result.structuredContent);
  });

  test('import emits both arrays empty rather than absent when there are no warnings', async () => {
    const captured = captureRegistration(registerImport, skillDeps());
    vi.stubGlobal(
      'fetch',
      jsonRoutes([
        [(href) => href.endsWith('/api/skill/import'), { name: 'review-bot', warnings: [] }],
        [() => true, { warnings: [] }],
      ]),
    );

    const result = await captured.handler({ source: 'acme/skills', add: ['agents'] });

    expect(result.structuredContent).toHaveProperty('warnings', []);
    expect(result.structuredContent).toHaveProperty('warningCodes', []);
    expectValidates(captured, result.structuredContent);
  });
  test('install withholds codes on an unknown one, and still emits both arrays when there are none', async () => {
    const skewed = captureRegistration(registerInstall, skillDeps());
    vi.stubGlobal(
      'fetch',
      jsonRoutes([
        [
          () => true,
          {
            hosts: ['agents'],
            scripts: false,
            warnings: ['A placement warning from the future.', 'Nothing was projected.'],
            warningCodes: ['place-from-the-future', 'no-targets'],
          },
        ],
      ]),
    );

    const skewedResult = await skewed.handler({ name: 'review-bot', add: ['agents'] });

    expect(skewedResult.structuredContent).toMatchObject({
      warnings: ['A placement warning from the future.', 'Nothing was projected.'],
    });
    expect(skewedResult.structuredContent).not.toHaveProperty('warningCodes');
    expect(skewedResult.content[0]?.text).toContain('A placement warning from the future.');
    expectValidates(skewed, skewedResult.structuredContent);

    vi.unstubAllGlobals();
    const quiet = captureRegistration(registerInstall, skillDeps());
    vi.stubGlobal(
      'fetch',
      jsonRoutes([[() => true, { hosts: ['agents'], scripts: false, warnings: [] }]]),
    );

    const quietResult = await quiet.handler({ name: 'review-bot', add: ['agents'] });

    expect(quietResult.structuredContent).toHaveProperty('warnings', []);
    expect(quietResult.structuredContent).toHaveProperty('warningCodes', []);
    expectValidates(quiet, quietResult.structuredContent);
  });

  test('install keeps a pre-codes server warnings and omits warningCodes rather than reporting an all-clear', async () => {
    const captured = captureRegistration(registerInstall, skillDeps());
    vi.stubGlobal(
      'fetch',
      jsonRoutes([
        [
          () => true,
          {
            hosts: ['agents'],
            scripts: true,
            warnings: ['This skill ships executable scripts/.'],
          },
        ],
      ]),
    );

    const result = await captured.handler({ name: 'review-bot', add: ['agents'] });

    expect(result.structuredContent).toMatchObject({
      warnings: ['This skill ships executable scripts/.'],
    });
    expect(result.structuredContent).not.toHaveProperty('warningCodes');
    expectValidates(captured, result.structuredContent);
  });
});