Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

104 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from 'vitest'

import {
    buildResponseFilter,
    composeToolSchema,
    extractPathParams,
    generateCategoryFile,
    generateDefinitionsJson,
    generateQueryWrapperDefinitionsJson,
    generateQueryWrapperFile,
    generateToolCode,
} from '../../scripts/generate-tools'
import type { OpenApiSpec, ResolvedOperation } from '../../scripts/generate-tools'
import { QueryWrapperToolConfigSchema, ToolConfigSchema } from '../../scripts/yaml-config-schema'
import type { EnabledQueryWrapperToolConfig, EnabledToolConfig, ToolConfig } from '../../scripts/yaml-config-schema'

function makeSpec(overrides: Partial<OpenApiSpec> = {}): OpenApiSpec {
    return {
        paths: {},
        components: { schemas: {} },
        ...overrides,
    }
}

function makeResolved(overrides: Partial<ResolvedOperation> = {}): ResolvedOperation {
    return {
        method: 'GET',
        path: '/api/projects/{project_id}/things/',
        operation: {
            operationId: 'things_list',
            parameters: [],
        },
        ...overrides,
    }
}

const defaultCategory = {
    category: 'Things',
    feature: 'things',
    url_prefix: '/things',
    tools: {},
}

// Tests don't exercise schema_ref param_overrides, so return an empty JsonSchemaRoot stub.
const stubGetQuerySchema = (): { definitions: Record<string, never> } => ({ definitions: {} })

describe('extractPathParams', () => {
    const cases = [
        {
            name: 'returns empty for path without params',
            url: '/api/projects/things/',
            expected: [],
        },
        {
            name: 'excludes project_id',
            url: '/api/projects/{project_id}/things/',
            expected: [],
        },
        {
            name: 'extracts non-project_id params',
            url: '/api/projects/{project_id}/things/{id}/',
            expected: ['id'],
        },
        {
            name: 'extracts multiple params',
            url: '/api/projects/{project_id}/things/{thing_id}/sub/{sub_id}/',
            expected: ['thing_id', 'sub_id'],
        },
    ]

    it.each(cases)('$name', ({ url, expected }) => {
        expect(extractPathParams(url)).toEqual(expected)
    })
})

describe('composeToolSchema', () => {
    it('returns empty toolInputsImports when no param_overrides have input_schema', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
        }
        const resolved = makeResolved()
        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        expect(result.toolInputsImports).toEqual([])
    })

    it('returns empty toolInputsImports when param_overrides only have descriptions', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            param_overrides: {
                name: { description: 'A custom description' },
            },
        }
        const resolved = makeResolved()
        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        expect(result.toolInputsImports).toEqual([])
    })

    it('requires a PATCH field without removing its Orval description', () => {
        const config: ToolConfig = {
            operation: 'things_partial_update',
            enabled: true,
            param_overrides: { destination: { required: true } },
        }
        const resolved = makeResolved({
            method: 'PATCH',
            operation: {
                operationId: 'things_partial_update',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: { properties: { destination: { type: 'integer' } } },
                        },
                    },
                },
            },
        })

        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        expect(result.schemaExpr).toContain("ThingsPartialUpdateBody.shape['destination'].nonoptional()")
    })

    it('collects toolInputsImports from param_overrides with input_schema', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            param_overrides: {
                steps: { input_schema: 'StepsSchema' },
                filters: { input_schema: 'FiltersSchema' },
                name: { description: 'Just a description' },
            },
        }
        const resolved = makeResolved({
            method: 'POST',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                properties: {
                                    steps: { type: 'object' },
                                    filters: { type: 'object' },
                                    name: { type: 'string' },
                                },
                            },
                        },
                    },
                },
            },
        })

        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        expect(result.toolInputsImports).toContain('StepsSchema')
        expect(result.toolInputsImports).toContain('FiltersSchema')
        expect(result.toolInputsImports).toHaveLength(2)
    })

    it('applies .extend() for param_overrides with input_schema', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            param_overrides: {
                steps: { input_schema: 'StepsSchema' },
            },
        }
        const resolved = makeResolved({
            method: 'POST',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                properties: {
                                    steps: { type: 'object' },
                                    name: { type: 'string' },
                                },
                            },
                        },
                    },
                },
            },
        })

        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        expect(result.schemaExpr).toContain('.extend({ steps: StepsSchema })')
    })
})

describe('generateToolCode with input_schema', () => {
    it('uses custom schema import when input_schema is set', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            input_schema: 'ThingCreateSchema',
            scopes: ['thing:write'],
            annotations: { readOnly: false, destructive: false, idempotent: false },
        }
        const resolved = makeResolved({ method: 'POST' })

        const result = generateToolCode(
            'things-create',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.toolInputsImports).toEqual(['ThingCreateSchema'])
        expect(result.orvalImports).toEqual([])
        expect(result.code).toMatchSnapshot()
    })

    it('generates body forwarding for POST with input_schema', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            input_schema: 'ThingCreateSchema',
        }
        const resolved = makeResolved({ method: 'POST' })

        const result = generateToolCode(
            'things-create',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('const parsedParams = ThingsCreateSchema().parse(params)')
        expect(result.code).toContain('body: parsedParams')
    })

    it('generates query forwarding for GET with input_schema', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            input_schema: 'ThingListSchema',
        }
        const resolved = makeResolved({ method: 'GET' })

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('const parsedParams = ThingsListSchema().parse(params)')
        expect(result.code).toContain('query: parsedParams')
    })

    it('uses response_type override for custom input schema tools', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            input_schema: 'ThingListSchema',
            response_type: "Omit<Schemas.ThingList, 'results'> & { results: unknown[] }",
        }
        const resolved = makeResolved({ method: 'GET' })

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain(
            "const thingsList = (): ToolBase<ReturnType<typeof ThingsListSchema>, Omit<Schemas.ThingList, 'results'> & { results: unknown[] }>"
        )
        expect(result.code).toContain(
            "const result = await context.api.request<Omit<Schemas.ThingList, 'results'> & { results: unknown[] }>({"
        )
    })

    it('destructures path params for input_schema with path params', () => {
        const config: ToolConfig = {
            operation: 'things_update',
            enabled: true,
            input_schema: 'ThingUpdateSchema',
        }
        const resolved = makeResolved({
            method: 'PATCH',
            path: '/api/projects/{project_id}/things/{id}/',
        })

        const result = generateToolCode(
            'things-update',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('id, ...body')
        expect(result.code).toContain('${encodeURIComponent(String(id))}')
    })

    it('destructures path params into query for GET with path params', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            input_schema: 'ThingGetSchema',
        }
        const resolved = makeResolved({
            method: 'GET',
            path: '/api/projects/{project_id}/things/{id}/',
        })

        const result = generateToolCode(
            'things-retrieve',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('id, ...query')
    })

    it('applies enrich_url with input_schema', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            input_schema: 'ThingCreateSchema',
            enrich_url: '{id}',
        }
        const resolved = makeResolved({ method: 'POST' })

        const result = generateToolCode(
            'things-create',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toMatchSnapshot()
    })

    it('applies list enrichment with input_schema', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            input_schema: 'ThingListSchema',
            list: true,
            enrich_url: '{id}',
        }
        const resolved = makeResolved({ method: 'GET' })

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(result.code).toMatchSnapshot()
    })

    it('applies list enrichment without inserting a path slash before a query-string prefix', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            input_schema: 'ThingListSchema',
            list: true,
            enrich_url: '?tab=alerts&alert_id={id}',
        }
        const resolved = makeResolved({ method: 'GET' })

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('`/things?tab=alerts&alert_id=${item.id}`')
    })

    it('applies list enrichment without inserting a path slash before a fragment prefix', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            input_schema: 'ThingListSchema',
            list: true,
            enrich_url: '#tab-{id}',
        }
        const resolved = makeResolved({ method: 'GET' })

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('`/things#tab-${item.id}`')
    })

    it('extends the custom schema with a selectable `fields` param and narrows the response', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            input_schema: 'ThingListSchema',
            list: true,
            response: { include: ['id', 'name'], selectable: true },
        }
        const resolved = makeResolved({ method: 'GET' })

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        // The `fields` param must be added to the custom schema, constrained to the allowlist,
        // and reject an empty array so it can't silently fall back to the full payload.
        expect(result.code).toContain('.extend({ fields: z.array(z.enum([')
        expect(result.code).toContain("z.enum(['id', 'name'])")
        expect(result.code).toContain('.min(1)')
        // And the response filter must honor it, falling back to the full allowlist when omitted.
        expect(result.code).toContain("params.fields?.length ? params.fields : ['id', 'name']")
    })

    it('adds an `expand` param that restores the expandable fields the response omits by default', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            input_schema: 'ThingGetSchema',
            response: { exclude: ['secret'], expandable: ['items.*.body'] },
        }
        const resolved = makeResolved({ method: 'GET' })

        const result = generateToolCode(
            'thing-get',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain(".extend({ expand: z.array(z.enum(['items.*.body'])).min(1).optional()")
        expect(result.code).toContain('const { expand: _expand, ...parsedParams } = ThingGetSchema().parse(params)')
        expect(result.code).toContain(
            "omitResponseFields(result, ['secret', ...(['items.*.body'] as const).filter((path) => !params.expand?.includes(path))])"
        )
    })

    it('throws when selectable is set without an include allowlist', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            input_schema: 'ThingListSchema',
            list: true,
            response: { selectable: true },
        }
        const resolved = makeResolved({ method: 'GET' })

        // selectable has no allowlist to constrain `fields` against — codegen must fail loudly rather
        // than silently emit a tool whose selectable flag does nothing.
        expect(() =>
            generateToolCode(
                'things-list',
                config,
                resolved,
                defaultCategory,
                makeSpec(),
                new Set<string>(),
                stubGetQuerySchema
            )
        ).toThrow(/response\.selectable requires a non-empty response\.include allowlist/)
    })
})

describe('generateToolCode without input_schema', () => {
    it('returns orvalImports and no toolInputsImports', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
        }
        const resolved = makeResolved({
            operation: {
                operationId: 'things_list',
                parameters: [
                    {
                        in: 'path',
                        name: 'project_id',
                        required: true,
                        schema: { type: 'string' },
                    },
                ],
            },
        })

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.toolInputsImports).toEqual([])
    })

    it('comma-joins explode:false array query params (DRF comma-separated filters)', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
        }
        const resolved = makeResolved({
            operation: {
                operationId: 'things_list',
                parameters: [
                    {
                        in: 'query',
                        name: 'type',
                        style: 'form',
                        explode: false,
                        schema: { type: 'array', items: { type: 'string' } },
                    },
                ],
            },
        })

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain(
            "type: Array.isArray(params.type) ? params.type.join(',') || undefined : params.type,"
        )
    })

    it('forwards array query params without explode:false untouched (json.loads()-style backends)', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
        }
        const resolved = makeResolved({
            operation: {
                operationId: 'things_list',
                parameters: [
                    {
                        in: 'query',
                        name: 'serviceNames',
                        schema: { type: 'array', items: { type: 'string' } },
                    },
                ],
            },
        })

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('serviceNames: params.serviceNames,')
        expect(result.code).not.toContain('serviceNames.join')
    })

    it('keeps explode:false params with object items on the JSON path', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
        }
        const resolved = makeResolved({
            operation: {
                operationId: 'things_list',
                parameters: [
                    {
                        in: 'query',
                        name: 'filters',
                        style: 'form',
                        explode: false,
                        schema: { type: 'array', items: { $ref: '#/components/schemas/Filter' } },
                    },
                ],
            },
        })

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('filters: params.filters,')
        expect(result.code).not.toContain('filters.join')
    })

    it('collects toolInputsImports from param_overrides', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            param_overrides: {
                steps: { input_schema: 'StepsSchema' },
            },
        }
        const resolved = makeResolved({
            method: 'POST',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                properties: {
                                    steps: { type: 'object' },
                                    name: { type: 'string' },
                                },
                            },
                        },
                    },
                },
            },
        })

        const result = generateToolCode(
            'things-create',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.toolInputsImports).toContain('StepsSchema')
        expect(result.code).toContain('.extend({ steps: StepsSchema })')
    })
})

describe('inject_body', () => {
    const injectBodyResolved = (): ResolvedOperation =>
        makeResolved({
            method: 'POST',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                properties: {
                                    name: { type: 'string' },
                                },
                            },
                        },
                    },
                },
            },
        })

    it('emits hardcoded body assignments for inject_body entries', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            inject_body: { created_via: 'mcp' },
        }

        const result = generateToolCode(
            'things-create',
            config,
            injectBodyResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain(`body["created_via"] = "mcp"`)
    })

    it('emits inject_body after dynamic body builder so it overrides caller input', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            inject_body: { created_via: 'mcp' },
        }

        const result = generateToolCode(
            'things-create',
            config,
            injectBodyResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        const nameIdx = result.code.indexOf(`body["name"]`)
        const injectIdx = result.code.indexOf(`body["created_via"]`)
        expect(nameIdx).toBeGreaterThan(-1)
        expect(injectIdx).toBeGreaterThan(nameIdx)
    })

    it('initializes body even when inject_body is the only source', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            exclude_params: ['name'],
            inject_body: { created_via: 'mcp' },
        }

        const result = generateToolCode(
            'things-create',
            config,
            injectBodyResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('const body: Record<string, unknown> = {}')
        expect(result.code).toContain(`body["created_via"] = "mcp"`)
        expect(result.code).toContain('body,')
    })

    it('escapes inject_body keys that contain special characters', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            inject_body: { "weird'key": 'safe' },
        }

        const result = generateToolCode(
            'things-create',
            config,
            injectBodyResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        // JSON.stringify escapes the single quote so the generated TS stays valid.
        expect(result.code).toContain(`body["weird'key"] = "safe"`)
    })
})

describe('anyOf / oneOf body schemas (discriminated unions)', () => {
    // Polymorphic Python serializers (e.g. file-download-batch-exports) emit
    // request bodies as `anyOf` of per-variant object schemas. Without union
    // handling, `bodyFieldNames` stays empty and the generated handler POSTs
    // with no body — the server rejects the request as "field required".
    const unionResolved = (): ResolvedOperation =>
        makeResolved({
            method: 'POST',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                anyOf: [
                                    {
                                        type: 'object',
                                        properties: {
                                            kind: { type: 'string', enum: ['a'] },
                                            shared_field: { type: 'string' },
                                            only_in_a: { type: 'string' },
                                        },
                                        required: ['kind', 'shared_field'],
                                    },
                                    {
                                        type: 'object',
                                        properties: {
                                            kind: { type: 'string', enum: ['b'] },
                                            shared_field: { type: 'string' },
                                            only_in_b: { type: 'number' },
                                        },
                                        required: ['kind', 'shared_field', 'only_in_b'],
                                    },
                                ],
                            },
                        },
                    },
                },
            },
        })

    it('emits body assembly for every field, guarding variant-specific access with `in`', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
        }

        const result = generateToolCode(
            'things-create',
            config,
            unionResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        // Body is initialized and forwarded.
        expect(result.code).toContain('const body: Record<string, unknown> = {}')
        expect(result.code).toContain('body,')

        // Every field across all variants is assembled into the body.
        expect(result.code).toContain(`body["kind"] = params.kind`)
        expect(result.code).toContain(`body["shared_field"] = params.shared_field`)
        expect(result.code).toContain(`body["only_in_a"] = params.only_in_a`)
        expect(result.code).toContain(`body["only_in_b"] = params.only_in_b`)

        // Fields present in every variant don't need the `in` guard.
        expect(result.code).toContain('if (params.kind !== undefined)')
        expect(result.code).toContain('if (params.shared_field !== undefined)')
        // Fields only in some variants must be guarded with `'X' in params` so
        // accessing them on the inferred union type still type-checks.
        expect(result.code).toContain(`if ('only_in_a' in params && params.only_in_a !== undefined)`)
        expect(result.code).toContain(`if ('only_in_b' in params && params.only_in_b !== undefined)`)
    })

    it('flattens allOf composition inside a union variant', () => {
        // Mirrors the common OpenAPI pattern of a variant that extends a base
        // schema via allOf (e.g. `$ref` + extra properties). Without allOf
        // handling the base-schema fields would be dropped from the body.
        const spec = makeSpec({
            components: {
                schemas: {
                    BaseFields: {
                        type: 'object',
                        properties: {
                            base_field: { type: 'string' },
                        },
                        required: ['base_field'],
                    },
                },
            },
        })
        const resolved = makeResolved({
            method: 'POST',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                anyOf: [
                                    {
                                        allOf: [
                                            { $ref: '#/components/schemas/BaseFields' },
                                            {
                                                type: 'object',
                                                properties: {
                                                    kind: { type: 'string', enum: ['a'] },
                                                    only_in_a: { type: 'string' },
                                                },
                                                required: ['kind'],
                                            },
                                        ],
                                    },
                                    {
                                        type: 'object',
                                        properties: {
                                            base_field: { type: 'string' },
                                            kind: { type: 'string', enum: ['b'] },
                                        },
                                        required: ['base_field', 'kind'],
                                    },
                                ],
                            },
                        },
                    },
                },
            },
        })

        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
        }
        const result = generateToolCode(
            'things-create',
            config,
            resolved,
            defaultCategory,
            spec,
            new Set<string>(),
            stubGetQuerySchema
        )

        // allOf-composed fields reach the body builder, treated as shared
        // (present in every variant) rather than variant-specific.
        expect(result.code).toContain(`body["base_field"] = params.base_field`)
        expect(result.code).toContain('if (params.base_field !== undefined)')
        expect(result.code).toContain('if (params.kind !== undefined)')
        // The variant-only field still gets `in`-guarded.
        expect(result.code).toContain(`if ('only_in_a' in params && params.only_in_a !== undefined)`)
    })

    it('resolves $ref-based union variants from components.schemas', () => {
        const spec = makeSpec({
            components: {
                schemas: {
                    VariantA: {
                        type: 'object',
                        properties: { kind: { type: 'string' }, payload_a: { type: 'string' } },
                        required: ['kind'],
                    },
                    VariantB: {
                        type: 'object',
                        properties: { kind: { type: 'string' }, payload_b: { type: 'string' } },
                        required: ['kind'],
                    },
                },
            },
        })
        const resolved = makeResolved({
            method: 'POST',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                oneOf: [
                                    { $ref: '#/components/schemas/VariantA' },
                                    { $ref: '#/components/schemas/VariantB' },
                                ],
                            },
                        },
                    },
                },
            },
        })

        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
        }

        const result = generateToolCode(
            'things-create',
            config,
            resolved,
            defaultCategory,
            spec,
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain(`body["payload_a"] = params.payload_a`)
        expect(result.code).toContain(`body["payload_b"] = params.payload_b`)
    })
})

describe('rename_params', () => {
    it('maps a query alias to the original HTTP key and preserves its schema override', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            rename_params: { tile_ids: 'dashboard_tile_ids' },
            param_overrides: { tile_ids: { input_schema: 'DashboardInsightTileIdsSchema', aliases: ['tile_ids'] } },
        }
        const resolved = makeResolved({
            operation: {
                operationId: 'things_list',
                parameters: [{ in: 'query', name: 'tile_ids', schema: { type: 'string' } }],
            },
        })
        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('dashboard_tile_ids:')
        expect(result.code).toContain('DashboardInsightTileIdsSchema')
        expect(result.code).toContain('tile_ids: params.dashboard_tile_ids')
        expect(result.code).not.toContain('ThingsListBody')
        expect(result.code).toContain("normalizeParamAliases({ dashboard_tile_ids: ['tile_ids'] })")
    })

    it('swaps field names in schema expression and tracks renames', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            rename_params: { $unset: 'property_key' },
        }
        const resolved = makeResolved({
            method: 'POST',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                properties: {
                                    $unset: { type: 'string' },
                                },
                            },
                        },
                    },
                },
            },
        })

        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        expect(result.schemaExpr).toContain(".omit({ '$unset': true })")
        expect(result.schemaExpr).toContain(".extend({ property_key: ThingsCreateBody.shape['$unset'] })")
        expect(result.bodyFieldNames).toContain('property_key')
        expect(result.bodyFieldNames).not.toContain('$unset')
        expect(result.renamedFields).toEqual({ property_key: '$unset' })
    })

    it('generates handler that maps alias to original body key', () => {
        const config: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            rename_params: { $unset: 'property_key' },
        }
        const resolved = makeResolved({
            method: 'POST',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                properties: {
                                    $unset: { type: 'string' },
                                },
                            },
                        },
                    },
                },
            },
        })

        const result = generateToolCode(
            'things-create',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('params.property_key !== undefined')
        expect(result.code).toContain('body["$unset"] = params.property_key')
        expect(result.code).not.toContain('params.$unset')
    })

    it('keeps the path param when the renamed body field shares its name', () => {
        // The body part is merged over the path part, so a writable body field that shares a
        // path param's name collapses into one input: the URL and the new value become the same
        // string, and the resource can never be renamed. Renaming must drop only the body copy.
        const config: ToolConfig = {
            operation: 'things_partial_update',
            enabled: true,
            rename_params: { name: 'new_name' },
        }
        const resolved = makeResolved({
            method: 'PATCH',
            path: '/api/projects/{project_id}/things/{name}/',
            operation: {
                operationId: 'things_partial_update',
                parameters: [{ name: 'name', in: 'path', required: true, schema: { type: 'string' } }],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                properties: {
                                    name: { type: 'string' },
                                },
                            },
                        },
                    },
                },
            },
        })

        const composed = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)
        expect(composed.schemaExpr).toContain("ThingsPartialUpdateBody.omit({ 'name': true })")
        expect(composed.schemaExpr).not.toContain("ThingsPartialUpdateParams.omit({ 'name': true })")
        expect(composed.renamedFields).toEqual({ new_name: 'name' })

        const generated = generateToolCode(
            'things-partial-update',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(generated.code).toContain('body["name"] = params.new_name')
        expect(generated.code).toContain('String(params.name)')
    })
})

describe('param_overrides aliases', () => {
    it('wraps the composed schema with normalizeParamAliases and imports the helper', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            param_overrides: {
                id: { aliases: ['thingId', 'thing_id'] },
            },
        }
        const resolved = makeResolved({
            method: 'GET',
            path: '/api/projects/{project_id}/things/{id}/',
            operation: {
                operationId: 'things_retrieve',
                parameters: [
                    { name: 'project_id', in: 'path', required: true, schema: { type: 'string' } },
                    { name: 'id', in: 'path', required: true, schema: { type: 'integer' } },
                ],
            },
        })

        const result = generateToolCode(
            'things-get',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.castHelperImports.has('normalizeParamAliases')).toBe(true)
        expect(result.code).toContain(
            "const ThingsGetSchema = () => {\n    const ThingsRetrieveParams = orvalSchemas.ThingsRetrieveParams()\n    return z.preprocess(normalizeParamAliases({ id: ['thingId', 'thing_id'] }), ThingsRetrieveParams.omit({ project_id: true }))\n}"
        )
    })
})

describe('x-accepts-stringified-json query params', () => {
    function resolvedWith(parameters: NonNullable<ResolvedOperation['operation']['parameters']>): ResolvedOperation {
        return makeResolved({
            operation: {
                operationId: 'things_list',
                parameters,
            },
        })
    }

    it('widens schema for params marked x-accepts-stringified-json', () => {
        const config: ToolConfig = { operation: 'things_list', enabled: true }
        const resolved = resolvedWith([
            {
                in: 'query',
                name: 'filters_override',
                schema: { type: 'string' },
                description: 'Filters override.',
                'x-accepts-stringified-json': true,
            },
        ])

        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        expect(result.schemaExpr).toContain(
            "filters_override: z.union([z.string(), z.record(z.string(), z.unknown())]).optional().describe('Filters override.')"
        )
    })

    it('does not widen sibling params that lack the extension', () => {
        const config: ToolConfig = { operation: 'things_list', enabled: true }
        const resolved = resolvedWith([
            {
                in: 'query',
                name: 'filters_override',
                schema: { type: 'string' },
                'x-accepts-stringified-json': true,
            },
            {
                in: 'query',
                name: 'plain_string',
                schema: { type: 'string' },
            },
        ])

        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        expect(result.schemaExpr).toContain('filters_override: z.union([z.string()')
        expect(result.schemaExpr).not.toContain('plain_string: z.union(')
    })

    it('does not widen params named *_override without the extension', () => {
        const config: ToolConfig = { operation: 'things_list', enabled: true }
        const resolved = resolvedWith([
            {
                in: 'query',
                name: 'filters_override',
                schema: { type: 'string' },
                // no x-accepts-stringified-json — magic naming alone must not trigger widening
            },
        ])

        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        expect(result.schemaExpr).not.toContain('z.union([z.string()')
    })

    it('skips widening when the YAML config also defines a param_override for the same field', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            param_overrides: {
                filters_override: { description: 'Custom YAML description' },
            },
        }
        const resolved = resolvedWith([
            {
                in: 'query',
                name: 'filters_override',
                schema: { type: 'string' },
                description: 'OpenAPI description',
                'x-accepts-stringified-json': true,
            },
        ])

        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        // YAML wins — describe() comes through, no union extension afterwards.
        expect(result.schemaExpr).toContain('Custom YAML description')
        expect(result.schemaExpr).not.toContain('z.union([z.string()')
    })

    it('respects exclude_params — excluded fields are not widened', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            exclude_params: ['filters_override'],
        }
        const resolved = resolvedWith([
            {
                in: 'query',
                name: 'filters_override',
                schema: { type: 'string' },
                'x-accepts-stringified-json': true,
            },
            {
                in: 'query',
                name: 'variables_override',
                schema: { type: 'string' },
                'x-accepts-stringified-json': true,
            },
        ])

        const result = composeToolSchema(config, resolved, makeSpec(), stubGetQuerySchema)

        expect(result.schemaExpr).not.toContain('filters_override: z.union(')
        expect(result.schemaExpr).toContain('variables_override: z.union([z.string()')
    })
})

describe('QueryWrapperToolConfigSchema validation', () => {
    it.each([true, false] as const)('accepts use_optimized_output: %s', (value) => {
        const result = QueryWrapperToolConfigSchema.safeParse({
            schema_ref: 'AssistantTrendsQuery',
            enabled: true,
            scopes: ['query:read'],
            annotations: { readOnly: true, destructive: false, idempotent: true },
            use_optimized_output: value,
        })
        expect(result.success).toBe(true)
    })

    it('rejects non-boolean use_optimized_output values', () => {
        const result = QueryWrapperToolConfigSchema.safeParse({
            schema_ref: 'AssistantTrendsQuery',
            enabled: true,
            use_optimized_output: 'optimized',
        })
        expect(result.success).toBe(false)
    })

    it('accepts system_prompt_hint on query wrappers', () => {
        const result = QueryWrapperToolConfigSchema.safeParse({
            schema_ref: 'AssistantTrendsQuery',
            enabled: true,
            scopes: ['query:read'],
            annotations: { readOnly: true, destructive: false, idempotent: true },
            system_prompt_hint: 'Time series, aggregations, formulas',
        })
        expect(result.success).toBe(true)
    })

    it('accepts system_prompt_hint on standard tools', () => {
        const result = ToolConfigSchema.safeParse({
            operation: 'logs_query_create',
            enabled: true,
            system_prompt_hint: 'Log filtering by severity/service/attribute',
        })
        expect(result.success).toBe(true)
    })
})

describe('system_prompt_hint flows into tool definitions', () => {
    it('propagates system_prompt_hint from wrapper YAML into the generated definition', () => {
        const wrapperConfig: EnabledQueryWrapperToolConfig = {
            schema_ref: 'AssistantTrendsQuery',
            enabled: true,
            scopes: ['query:read'],
            annotations: { readOnly: true, destructive: false, idempotent: true },
            system_prompt_hint: 'Time series, aggregations, formulas',
        }
        const definitions = generateQueryWrapperDefinitionsJson(
            { category: 'Query wrappers', feature: 'insights', wrappers: {} },
            [['query-trends', wrapperConfig]],
            '/tmp'
        ) as Record<string, { system_prompt_hint?: string }>
        expect(definitions['query-trends']?.system_prompt_hint).toBe('Time series, aggregations, formulas')
    })

    it('omits system_prompt_hint from the wrapper definition when not set', () => {
        const wrapperConfig: EnabledQueryWrapperToolConfig = {
            schema_ref: 'AssistantTrendsQuery',
            enabled: true,
            scopes: ['query:read'],
            annotations: { readOnly: true, destructive: false, idempotent: true },
        }
        const definitions = generateQueryWrapperDefinitionsJson(
            { category: 'Query wrappers', feature: 'insights', wrappers: {} },
            [['query-trends', wrapperConfig]],
            '/tmp'
        )
        expect((definitions['query-trends'] as Record<string, unknown>).system_prompt_hint).toBeUndefined()
    })

    it('propagates system_prompt_hint from standard tool YAML into the generated definition', () => {
        const toolConfig: EnabledToolConfig = {
            operation: 'logs_query_create',
            enabled: true,
            scopes: ['logs:read'],
            annotations: { readOnly: true, destructive: false, idempotent: true },
            system_prompt_hint: 'Log filtering by severity/service/attribute',
        }
        const resolved: ResolvedOperation = {
            method: 'POST',
            path: '/api/projects/{project_id}/logs/query/',
            operation: { operationId: 'logs_query_create', description: 'Query logs' },
        }
        const definitions = generateDefinitionsJson([
            {
                config: { category: 'Logs', feature: 'logs', url_prefix: '/logs', tools: {} },
                enabledTools: [['query-logs', toolConfig, resolved]],
                enabledWrappers: [],
                yamlDir: '/tmp',
            },
        ]) as Record<string, { system_prompt_hint?: string }>
        expect(definitions['query-logs']?.system_prompt_hint).toBe('Log filtering by severity/service/attribute')
    })
})

describe('per-tool category in tool definitions', () => {
    it.each([
        { toolCategory: undefined, expected: 'AI observability' },
        { toolCategory: 'Experiments', expected: 'Experiments' },
    ])('uses $expected when the tool category is $toolCategory', ({ toolCategory, expected }) => {
        const toolConfig: EnabledToolConfig = {
            operation: 'llm_prompts_list',
            enabled: true,
            scopes: ['llm_prompt:read'],
            annotations: { readOnly: true, destructive: false, idempotent: true },
            ...(toolCategory ? { category: toolCategory } : {}),
        }
        const resolved: ResolvedOperation = {
            method: 'GET',
            path: '/api/environments/{project_id}/llm_prompts/',
            operation: { operationId: 'llm_prompts_list', description: 'List prompts' },
        }
        const definitions = generateDefinitionsJson([
            {
                config: {
                    category: 'AI observability',
                    feature: 'llm_analytics',
                    url_prefix: '/ai-observability',
                    tools: {},
                },
                enabledTools: [['llma-prompt-list', toolConfig, resolved]],
                enabledWrappers: [],
                yamlDir: '/tmp',
            },
        ]) as Record<string, { category?: string; feature?: string }>
        expect(definitions['llma-prompt-list']).toMatchObject({ category: expected, feature: 'llm_analytics' })
    })
})

describe('generateQueryWrapperFile with use_optimized_output', () => {
    const minimalQuerySchema = {
        definitions: {
            AssistantTestQuery: {
                type: 'object' as const,
                properties: {
                    kind: { const: 'TestQuery', type: 'string' as const },
                },
                required: ['kind'],
            },
        },
    }

    it('emits outputFormat: optimized when use_optimized_output is true', () => {
        const { code } = generateQueryWrapperFile(
            {
                category: 'Test',
                feature: 'test',
                wrappers: {
                    'query-test': {
                        schema_ref: 'AssistantTestQuery',
                        enabled: true,
                        scopes: ['query:read'],
                        annotations: { readOnly: true, destructive: false, idempotent: true },
                        use_optimized_output: true,
                    },
                },
            },
            'test.yaml',
            minimalQuerySchema
        )

        expect(code).toContain("outputFormat: 'optimized'")
    })

    it.each([false, undefined] as const)('emits outputFormat: json when use_optimized_output is %s', (value) => {
        const { code } = generateQueryWrapperFile(
            {
                category: 'Test',
                feature: 'test',
                wrappers: {
                    'query-test': {
                        schema_ref: 'AssistantTestQuery',
                        enabled: true,
                        scopes: ['query:read'],
                        annotations: { readOnly: true, destructive: false, idempotent: true },
                        ...(value === undefined ? {} : { use_optimized_output: value }),
                    },
                },
            },
            'test.yaml',
            minimalQuerySchema
        )

        expect(code).toContain("outputFormat: 'json'")
    })

    it('extends the wrapper schema with an output_format input when use_optimized_output is true', () => {
        const { code } = generateQueryWrapperFile(
            {
                category: 'Test',
                feature: 'test',
                wrappers: {
                    'query-test': {
                        schema_ref: 'AssistantTestQuery',
                        enabled: true,
                        scopes: ['query:read'],
                        annotations: { readOnly: true, destructive: false, idempotent: true },
                        use_optimized_output: true,
                    },
                },
            },
            'test.yaml',
            minimalQuerySchema
        )

        expect(code).toContain('QueryTestSchema = AssistantTestQuery.extend({')
        expect(code).toContain('output_format: z')
        expect(code).toContain(".enum(['optimized', 'json'])")
        expect(code).toContain(".default('optimized')")
    })

    it('does not expose an output_format input when use_optimized_output is false', () => {
        const { code } = generateQueryWrapperFile(
            {
                category: 'Test',
                feature: 'test',
                wrappers: {
                    'query-test': {
                        schema_ref: 'AssistantTestQuery',
                        enabled: true,
                        scopes: ['query:read'],
                        annotations: { readOnly: true, destructive: false, idempotent: true },
                    },
                },
            },
            'test.yaml',
            minimalQuerySchema
        )

        expect(code).not.toContain('output_format: z')
    })
})

describe('ToolConfigSchema validation', () => {
    const validBase = {
        operation: 'things_create',
        enabled: true,
        input_schema: 'ThingCreateSchema',
    }

    const conflictCases = [
        {
            name: 'rejects input_schema with include_params',
            extra: { include_params: ['name'] },
        },
        {
            name: 'rejects input_schema with exclude_params',
            extra: { exclude_params: ['name'] },
        },
        {
            name: 'rejects input_schema with param_overrides',
            extra: { param_overrides: { name: { description: 'x' } } },
        },
    ]

    it.each(conflictCases)('$name', ({ extra }) => {
        const result = ToolConfigSchema.safeParse({ ...validBase, ...extra })
        expect(result.success).toBe(false)
    })

    it.each([
        { name: 'rejects a blank disabled_reason', extra: { enabled: false, disabled_reason: '  ' }, valid: false },
        { name: 'rejects disabled_reason on an enabled tool', extra: { disabled_reason: 'Old' }, valid: false },
        {
            name: 'accepts enabled: false with disabled_reason',
            extra: { enabled: false, disabled_reason: 'Superseded by things-list' },
            valid: true,
        },
    ])('$name', ({ extra, valid }) => {
        const result = ToolConfigSchema.safeParse({ operation: 'things_list', enabled: true, ...extra })
        expect(result.success).toBe(valid)
    })

    it('allows input_schema without include_params, exclude_params, or param_overrides', () => {
        const result = ToolConfigSchema.safeParse(validBase)
        expect(result.success).toBe(true)
    })

    it('accepts response_type override', () => {
        const result = ToolConfigSchema.safeParse({
            operation: 'things_list',
            enabled: true,
            response_type: "Omit<Schemas.ThingList, 'results'>",
        })
        expect(result.success).toBe(true)
    })

    it.each([
        { name: 'rejects response.include with response.exclude', response: { include: ['id'], exclude: ['name'] } },
        {
            name: 'rejects response.expandable with response.include',
            response: { include: ['id'], expandable: ['body'] },
        },
        {
            name: 'rejects a response.expandable path that response.exclude also removes',
            response: { exclude: ['body'], expandable: ['body'] },
        },
    ])('$name', ({ response }) => {
        const result = ToolConfigSchema.safeParse({ operation: 'things_get', enabled: true, response })
        expect(result.success).toBe(false)
    })

    it('accepts response.include alone', () => {
        const result = ToolConfigSchema.safeParse({
            operation: 'things_list',
            enabled: true,
            response: { include: ['id', 'name'] },
        })
        expect(result.success).toBe(true)
    })

    it('rejects response.strip_nulls on a list tool', () => {
        const result = ToolConfigSchema.safeParse({
            operation: 'things_list',
            enabled: true,
            list: true,
            response: { strip_nulls: true },
        })
        expect(result.success).toBe(false)
    })

    it('accepts response.exclude alone', () => {
        const result = ToolConfigSchema.safeParse({
            operation: 'things_list',
            enabled: true,
            response: { exclude: ['filters', 'created_by'] },
        })
        expect(result.success).toBe(true)
    })
})

// ------------------------------------------------------------------
// buildResponseFilter
// ------------------------------------------------------------------

describe('buildResponseFilter', () => {
    it('returns empty code when no response filtering configured', () => {
        const config: ToolConfig = { operation: 'things_list', enabled: true }
        const result = buildResponseFilter(config)
        expect(result.code).toBe('')
        expect(result.helperImports).toEqual([])
    })

    it('generates pickResponseFields for detail endpoint with response.include', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            response: { include: ['id', 'name', 'status'] },
        }
        const result = buildResponseFilter(config)
        expect(result.code).toContain('pickResponseFields(result, ')
        expect(result.code).toContain("'id', 'name', 'status'")
        expect(result.helperImports).toEqual(['pickResponseFields'])
    })

    it('generates omitResponseFields for detail endpoint with response.exclude', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            response: { exclude: ['filters', 'created_by'] },
        }
        const result = buildResponseFilter(config)
        expect(result.code).toContain('omitResponseFields(result, ')
        expect(result.code).toContain("'filters', 'created_by'")
        expect(result.helperImports).toEqual(['omitResponseFields'])
    })

    it('maps pickResponseFields over results for list endpoint with response.include', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            list: true,
            response: { include: ['id', 'key'] },
        }
        const result = buildResponseFilter(config)
        expect(result.code).toContain('(result.results ?? []).map')
        expect(result.code).toContain('pickResponseFields(item, ')
        expect(result.helperImports).toEqual(['pickResponseFields'])
    })

    it('maps omitResponseFields over results for list endpoint with response.exclude', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            list: true,
            response: { exclude: ['large_blob'] },
        }
        const result = buildResponseFilter(config)
        expect(result.code).toContain('(result.results ?? []).map')
        expect(result.code).toContain('omitResponseFields(item, ')
        expect(result.helperImports).toEqual(['omitResponseFields'])
    })

    it('wraps the exclude expression in stripNullFields for response.strip_nulls', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            response: { exclude: ['filters'], strip_nulls: true },
        }
        const result = buildResponseFilter(config)
        expect(result.code).toContain("stripNullFields(omitResponseFields(result, ['filters']))")
        expect(result.helperImports).toEqual(['omitResponseFields', 'stripNullFields'])
    })

    it('generates stripNullFields alone when no include or exclude is configured', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            response: { strip_nulls: true },
        }
        const result = buildResponseFilter(config)
        expect(result.code).toContain('stripNullFields(result)')
        expect(result.helperImports).toEqual(['stripNullFields'])
    })

    it('preserves wildcard dot-path patterns in generated code', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            response: { exclude: ['filters.groups.*.properties', 'created_by'] },
        }
        const result = buildResponseFilter(config)
        expect(result.code).toContain("'filters.groups.*.properties'")
        expect(result.code).toContain("'created_by'")
    })
})

// ------------------------------------------------------------------
// generateToolCode — response filtering
// ------------------------------------------------------------------

describe('generateToolCode with response filtering', () => {
    it('generates pickResponseFields and uses filtered var for enrichment', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            response: { include: ['id', 'name'] },
            enrich_url: '{id}',
        }
        const resolved = makeResolved({
            method: 'GET',
            path: '/api/projects/{project_id}/things/{id}/',
        })

        const result = generateToolCode(
            'things-get',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('pickResponseFields(result, ')
        expect(result.code).toContain('const filtered = ')
        expect(result.code).toContain('withPostHogUrl(context, filtered,')
        expect(result.toolUtilsValueImports).toEqual(new Set(['pickResponseFields']))
    })

    it('generates omitResponseFields for detail endpoint', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            response: { exclude: ['filters'] },
        }
        const resolved = makeResolved({
            method: 'GET',
            path: '/api/projects/{project_id}/things/{id}/',
        })

        const result = generateToolCode(
            'things-get',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('omitResponseFields(result, ')
        expect(result.code).toContain('return filtered')
        expect(result.toolUtilsValueImports).toEqual(new Set(['omitResponseFields']))
    })

    it('returns no tool utility imports when none are needed', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
        }
        const resolved = makeResolved()

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.toolUtilsValueImports).toEqual(new Set())
    })

    it('generates response filtering for list endpoint with enrichment', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            list: true,
            enrich_url: '{id}',
            response: { exclude: ['large_field'] },
        }
        const resolved = makeResolved()

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('(result.results ?? []).map((item: any) => omitResponseFields(item, ')
        expect(result.code).toContain('...filtered,')
        expect(result.code).toContain('(filtered.results ?? []).map')
        expect(result.toolUtilsValueImports).toEqual(new Set(['omitResponseFields']))
    })
})

describe('generateToolCode with informational response wrapping', () => {
    it('wraps a filtered and enriched list after all response transformations', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            list: true,
            enrich_url: '{id}',
            response: {
                exclude: ['large_field'],
                informational_wrapper: {
                    tag: 'thing-references',
                    purpose: 'Use it only to identify relevant things.',
                },
            },
        }
        const resolved = makeResolved()

        const result = generateToolCode(
            'things-get',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain(
            'ToolBase<ReturnType<typeof ThingsGetSchema>, WithInformationalResponse<unknown>>'
        )
        const filteringIndex = result.code.indexOf('const filtered =')
        const wrappingIndex = result.code.indexOf('withInformationalResponse(')
        expect(filteringIndex).toBeGreaterThan(-1)
        expect(wrappingIndex).toBeGreaterThan(filteringIndex)
        expect(result.code).toContain(
            'withInformationalResponse(await withPostHogUrl(context, {\n            ...filtered,'
        )
        expect(result.code).toContain('"thing-references", "Use it only to identify relevant things.")')
        expect(result.needsWithInformationalResponse).toBe(true)
        expect(result.toolUtilsValueImports).toEqual(new Set(['omitResponseFields', 'withInformationalResponse']))
    })
})

describe('generateToolCode with a text projection', () => {
    it('projects outside the enrichment, so the projected fields can name `_posthogUrl`', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
            list: true,
            enrich_url: '{id}',
            response: { text_include: ['id', 'status', '_posthogUrl'] },
        }

        const result = generateToolCode(
            'things-list',
            config,
            makeResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('withTextProjection(await withPostHogUrl(context, {')
        expect(result.code).toContain("}, '/things'), ['id', 'status', '_posthogUrl'])")
        expect(result.toolUtilsValueImports).toEqual(new Set(['withTextProjection']))
    })
})

describe('path parameter encoding', () => {
    it('wraps project_id with encodeURIComponent in generated paths', () => {
        const config: ToolConfig = {
            operation: 'things_list',
            enabled: true,
        }
        const resolved = makeResolved()

        const result = generateToolCode(
            'things-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('${encodeURIComponent(String(projectId))}')
        expect(result.code).not.toMatch(/\$\{projectId\}/)
    })

    it('wraps organization_id with encodeURIComponent in generated paths', () => {
        const config: ToolConfig = {
            operation: 'members_list',
            enabled: true,
        }
        const resolved = makeResolved({
            path: '/api/organizations/{organization_id}/members/',
            operation: {
                operationId: 'members_list',
                parameters: [{ name: 'organization_id', in: 'path', required: true, schema: { type: 'string' } }],
            },
        })

        const result = generateToolCode(
            'org-members-list',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('${encodeURIComponent(String(orgId))}')
        expect(result.code).not.toMatch(/\$\{orgId\}/)
    })

    it('wraps user-provided path params with encodeURIComponent', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
        }
        const resolved = makeResolved({
            method: 'GET',
            path: '/api/projects/{project_id}/things/{id}/',
            operation: {
                operationId: 'things_retrieve',
                parameters: [
                    { name: 'project_id', in: 'path', required: true, schema: { type: 'string' } },
                    { name: 'id', in: 'path', required: true, schema: { type: 'integer' } },
                ],
            },
        })

        const result = generateToolCode(
            'things-get',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(result.code).toContain('${encodeURIComponent(String(params.id))}')
        expect(result.code).not.toMatch(/\$\{params\.id\}/)
    })

    it('wraps fallback-resolved params with encodeURIComponent', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            param_overrides: {
                id: { optional: true, fallback: 'orgId', description: 'Optional ID' },
            },
        }
        const resolved = makeResolved({
            method: 'GET',
            path: '/api/projects/{project_id}/things/{id}/',
            operation: {
                operationId: 'things_retrieve',
                parameters: [
                    { name: 'project_id', in: 'path', required: true, schema: { type: 'string' } },
                    { name: 'id', in: 'path', required: true, schema: { type: 'string' } },
                ],
            },
        })

        const result = generateToolCode(
            'things-get',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        // Fallback params use local variable (no params. prefix) but still get encoded
        expect(result.code).toContain('${encodeURIComponent(String(id))}')
        expect(result.code).not.toMatch(/\$\{id\}[^)]/)
    })
})

// ------------------------------------------------------------------
// confirmed_action — schema validation
// ------------------------------------------------------------------

describe('ToolConfigSchema confirmed_action', () => {
    const base = {
        operation: 'organizations_partial_update',
        enabled: true,
    } as const

    it('accepts a minimal confirmed_action block', () => {
        const result = ToolConfigSchema.safeParse({
            ...base,
            confirmed_action: { message: 'Confirm action on {orgId}?' },
        })
        expect(result.success).toBe(true)
    })

    it('accepts an action_label override', () => {
        const result = ToolConfigSchema.safeParse({
            ...base,
            confirmed_action: { message: 'Confirm', action_label: 'enforce 2FA' },
        })
        expect(result.success).toBe(true)
    })

    it('rejects missing message', () => {
        const result = ToolConfigSchema.safeParse({
            ...base,
            confirmed_action: { action_label: 'foo' },
        })
        expect(result.success).toBe(false)
    })

    it('rejects confirmed_action combined with ui_app (silent UI-app drop)', () => {
        const result = ToolConfigSchema.safeParse({
            ...base,
            ui_app: 'org-2fa',
            confirmed_action: { message: 'x' },
        })
        expect(result.success).toBe(false)
        if (!result.success) {
            expect(result.error.issues[0]!.message).toContain('ui_app')
        }
    })

    it('rejects confirmed_action combined with a whole-tool input_schema', () => {
        const result = ToolConfigSchema.safeParse({
            ...base,
            input_schema: 'OrganizationUpdateSchema',
            confirmed_action: { message: 'x' },
        })
        expect(result.success).toBe(false)
        if (!result.success) {
            expect(result.error.issues[0]!.message).toContain('input_schema')
        }
    })

    it('rejects unknown keys inside the confirmed_action object', () => {
        const result = ToolConfigSchema.safeParse({
            ...base,
            confirmed_action: { message: 'x', bogus: true },
        })
        expect(result.success).toBe(false)
    })
})

// ------------------------------------------------------------------
// generateToolCode — confirmed_action codegen
// ------------------------------------------------------------------

describe('generateToolCode with confirmed_action', () => {
    function makeConfirmedConfig(): ToolConfig {
        return {
            operation: 'organizations_partial_update',
            enabled: true,
            title: 'Enforce 2FA',
            confirmed_action: {
                message: 'About to enable enforce 2FA on organization {id}.',
                action_label: 'enforce 2FA',
            },
        }
    }

    function makePatchResolved(): ResolvedOperation {
        return {
            method: 'PATCH',
            path: '/api/organizations/{id}/',
            operation: { operationId: 'organizations_partial_update', parameters: [] },
        }
    }

    it('emits TWO factories (prepare and execute), not the base factory', () => {
        const result = generateToolCode(
            'organization-enforce-2fa-update',
            makeConfirmedConfig(),
            makePatchResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(result.code).toContain('organizationEnforce2faUpdatePrepare')
        expect(result.code).toContain('organizationEnforce2faUpdateExecute')
        // No base factory of the original name should be emitted.
        expect(result.code).not.toMatch(/const organizationEnforce2faUpdate\s*=/)
    })

    it('emits a strict confirmation-only schema for the execute variant', () => {
        const result = generateToolCode(
            'organization-enforce-2fa-update',
            makeConfirmedConfig(),
            makePatchResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(result.code).toContain('OrganizationEnforce2faUpdateSchemaExecute')
        expect(result.code).toContain('z.strictObject({')
        expect(result.code).not.toContain('OrganizationEnforce2faUpdateSchema.extend({')
        expect(result.code).toContain('confirmation_hash')
        expect(result.code).toContain('confirmation:')
    })

    it('wires prepare into prepareConfirmedAction with the messageTemplate', () => {
        const result = generateToolCode(
            'organization-enforce-2fa-update',
            makeConfirmedConfig(),
            makePatchResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(result.code).toContain('await prepareConfirmedAction')
        expect(result.code).toContain('purpose: "organization-enforce-2fa-update"')
        expect(result.code).toContain('actionLabel: "enforce 2FA"')
        expect(result.code).toContain('messageTemplate: "About to enable enforce 2FA on organization {id}."')
    })

    it('wires execute into executeConfirmedAction and falls through to the original API call', () => {
        const result = generateToolCode(
            'organization-enforce-2fa-update',
            makeConfirmedConfig(),
            makePatchResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(result.code).toContain('await executeConfirmedAction')
        expect(result.code).toContain('if (!__guard.ok)')
        // After the guard, the handler runs the original API request.
        expect(result.code).toContain('await context.api.request')
        expect(result.code).toContain("method: 'PATCH'")
    })

    it('uses only verifiedArgs as the downstream action params', () => {
        const result = generateToolCode(
            'organization-enforce-2fa-update',
            makeConfirmedConfig(),
            makePatchResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(result.code).toContain('const params = __guard.verifiedArgs')
        expect(result.code).toContain('incomingArgs: confirmationParams')
    })

    it('uses the tool title as the fallback action_label when none is set', () => {
        const config: ToolConfig = {
            ...makeConfirmedConfig(),
            title: 'Enforce 2FA',
            confirmed_action: { message: 'msg' },
        }
        const result = generateToolCode(
            'organization-enforce-2fa-update',
            config,
            makePatchResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(result.code).toContain('actionLabel: "Enforce 2FA"')
    })

    it('binds the active project scope into prepare and re-checks it in execute (cross-project replay guard)', () => {
        // A project-scoped confirmed action must sign the active project at
        // prepare time (boundScope) and re-verify it at execute time
        // (expectedScope). Without this, a confirmation prepared while one
        // project was active could be replayed against another after
        // switch-project.
        const result = generateToolCode(
            'metric-approve',
            makeConfirmedConfig(),
            makeResolved({
                method: 'POST',
                path: '/api/projects/{project_id}/metrics/{name}/approve/',
                operation: {
                    operationId: 'organizations_partial_update',
                    parameters: [
                        { in: 'path', name: 'project_id', required: true, schema: { type: 'string' } },
                        { in: 'path', name: 'name', required: true, schema: { type: 'string' } },
                    ],
                },
            }),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(result.code).toContain('boundScope: { projectId: String(__scopeProjectId) }')
        expect(result.code).toContain('expectedScope: { projectId: String(__scopeProjectId) }')
    })

    it('reuses the scope-checked project id to build the execute path (no post-guard re-read)', () => {
        // The path must be built from the same project id that was verified
        // against expectedScope. Re-reading state after the guard would let a
        // concurrent switch-project retarget the request at a different
        // project than the confirmation was bound to.
        const result = generateToolCode(
            'metric-approve',
            makeConfirmedConfig(),
            makeResolved({
                method: 'POST',
                path: '/api/projects/{project_id}/metrics/{name}/approve/',
                operation: {
                    operationId: 'organizations_partial_update',
                    parameters: [
                        { in: 'path', name: 'project_id', required: true, schema: { type: 'string' } },
                        { in: 'path', name: 'name', required: true, schema: { type: 'string' } },
                    ],
                },
            }),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(result.code).toContain('const projectId = __scopeProjectId')
        expect(result.code).not.toContain(
            'const params = __guard.verifiedArgs\n        const projectId = await context.stateManager.getProjectId()'
        )
    })

    it('resolves an omitted state-fallback id and signs it into the confirmed args (cross-org replay guard)', () => {
        // When the target id is optional with a state fallback, prepare must
        // resolve the active org/project to a concrete value and sign it, so a
        // switch-organization between prepare and execute can't retarget the
        // confirmed action at a different entity where the user is also an admin.
        const config: ToolConfig = {
            ...makeConfirmedConfig(),
            param_overrides: {
                id: { optional: true, fallback: 'orgId', description: 'Organization ID.' },
            },
        }
        const result = generateToolCode(
            'organization-enforce-2fa-update',
            config,
            makePatchResolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        expect(result.code).toContain('const id = params.id ?? await context.stateManager.getOrgID()')
        expect(result.code).toContain('args: { ...params, id }')
        // The unresolved args object must not be what gets signed.
        expect(result.code).not.toContain('args: params,')
    })
})

describe('object-json-string cast', () => {
    const resolved = (): ResolvedOperation =>
        makeResolved({
            method: 'GET',
            path: '/api/projects/{project_id}/things/service-names/',
            operation: {
                operationId: 'things_service_names_retrieve',
                parameters: [
                    { in: 'path', name: 'project_id', required: true, schema: { type: 'string' } },
                    { in: 'query', name: 'dateRange', required: false, schema: { type: 'string' } },
                ],
            },
        })

    it('wraps the param with castObjectToJsonString and imports the helper', () => {
        const result = generateToolCode(
            'things-service-names',
            {
                operation: 'things_service_names_retrieve',
                enabled: true,
                param_overrides: { dateRange: { cast: 'object-json-string' } },
            },
            resolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        const collapsed = result.code.replace(/\s+/g, ' ')
        expect(collapsed).toContain('z.preprocess(castObjectToJsonString')
        expect(result.castHelperImports.has('castObjectToJsonString')).toBe(true)
    })
})

describe('optional param with state fallback', () => {
    const resolved = (): ResolvedOperation =>
        makeResolved({
            path: '/api/organizations/{organization_id}/things/{id}/',
            operation: {
                operationId: 'things_retrieve',
                parameters: [
                    { in: 'path', name: 'organization_id', required: true, schema: { type: 'string' } },
                    { in: 'path', name: 'id', required: true, schema: { type: 'integer' } },
                ],
            },
        })

    const config = (): ToolConfig => ({
        operation: 'things_retrieve',
        enabled: true,
        param_overrides: {
            id: {
                description: 'Thing ID. If omitted, uses the active project.',
                optional: true,
                fallback: 'projectId',
                cast: 'string-int',
            },
        },
    })

    it('resolves the omitted param from state in the handler', () => {
        const result = generateToolCode(
            'things-retrieve',
            config(),
            resolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        const collapsed = result.code.replace(/\s+/g, ' ')
        expect(collapsed).toContain('const id = params.id ?? await context.stateManager.getProjectId()')
    })

    it('surfaces the field as optional despite the cast wrapper (z.preprocess strips inner optionality)', () => {
        const result = generateToolCode(
            'things-retrieve',
            config(),
            resolved(),
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        // The outer `.optional()` after the preprocess is what makes the agent-facing
        // JSON Schema treat the param as optional. Without it, the tool would still
        // demand the id the fallback exists to supply.
        const collapsed = result.code.replace(/\s+/g, ' ')
        expect(collapsed).toContain('.optional()).optional()')
    })

    it('sends the state-resolved value for a body field, not the omitted param', () => {
        const bodyConfig: ToolConfig = {
            operation: 'things_create',
            enabled: true,
            param_overrides: {
                organization: {
                    description: 'Organization ID. If omitted, uses the active organization.',
                    optional: true,
                    fallback: 'orgId',
                },
            },
        }
        const bodyResolved = makeResolved({
            method: 'POST',
            path: '/api/things/',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: {
                        'application/json': {
                            schema: {
                                properties: {
                                    organization: { type: 'string' },
                                    title: { type: 'string' },
                                },
                            },
                        },
                    },
                },
            },
        })

        const result = generateToolCode(
            'things-create',
            bodyConfig,
            bodyResolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )
        const collapsed = result.code.replace(/\s+/g, ' ')
        expect(collapsed).toContain('body["organization"] = organization')
        expect(collapsed).not.toContain('body["organization"] = params.organization')
    })
})

describe('composeToolSchema param aliases', () => {
    const resolvedWithIdAndQuery = makeResolved({
        path: '/api/projects/{project_id}/things/{id}/',
        operation: {
            operationId: 'things_retrieve',
            parameters: [
                { name: 'project_id', in: 'path', required: true, schema: { type: 'string' } },
                { name: 'id', in: 'path', required: true, schema: { type: 'integer' } },
                { name: 'thing_id', in: 'query', required: false, schema: { type: 'string' } },
            ],
        },
    })

    it('collects aliases that shadow nothing', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            param_overrides: { id: { aliases: ['thingId', 'thing_identifier'] } },
        }

        const result = composeToolSchema(config, resolvedWithIdAndQuery, makeSpec(), stubGetQuerySchema)

        expect(result.paramAliases).toEqual({ id: ['thingId', 'thing_identifier'] })
    })

    // normalizeParamAliases deletes alias keys, so an alias that is also a real parameter
    // would drop that parameter's value with no error at runtime. The generator is the only
    // place that sees both the alias list and the operation's parameters.
    it('rejects an alias that is also a declared parameter of the operation', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            param_overrides: { id: { aliases: ['thingId', 'thing_id'] } },
        }

        expect(() => composeToolSchema(config, resolvedWithIdAndQuery, makeSpec(), stubGetQuerySchema)).toThrow(
            /alias "thing_id" for param "id" is also a declared parameter/
        )
    })

    it('rejects an alias that collides with a body field, including one added by a later override', () => {
        const withBody = makeResolved({
            method: 'POST',
            path: '/api/projects/{project_id}/things/{id}/',
            operation: {
                operationId: 'things_update',
                parameters: [
                    { name: 'project_id', in: 'path', required: true, schema: { type: 'string' } },
                    { name: 'id', in: 'path', required: true, schema: { type: 'integer' } },
                ],
                requestBody: {
                    content: { 'application/json': { schema: { properties: { name: { type: 'string' } } } } },
                },
            },
        })

        const collidesWithBody: ToolConfig = {
            operation: 'things_update',
            enabled: true,
            param_overrides: { id: { aliases: ['name'] } },
        }
        expect(() => composeToolSchema(collidesWithBody, withBody, makeSpec(), stubGetQuerySchema)).toThrow(
            /alias "name" for param "id" is also a declared parameter/
        )

        // The alias override comes first in key order; the field it collides with is only
        // added by the input_schema override after it, so the check must run after the loop.
        const collidesWithLaterOverride: ToolConfig = {
            operation: 'things_update',
            enabled: true,
            param_overrides: { id: { aliases: ['steps'] }, steps: { input_schema: 'StepsSchema' } },
        }
        expect(() => composeToolSchema(collidesWithLaterOverride, withBody, makeSpec(), stubGetQuerySchema)).toThrow(
            /alias "steps" for param "id" is also a declared parameter/
        )
    })

    it('rejects one alias claimed by two params', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            param_overrides: { id: { aliases: ['ref'] }, thing_id: { aliases: ['ref'] } },
        }

        expect(() => composeToolSchema(config, resolvedWithIdAndQuery, makeSpec(), stubGetQuerySchema)).toThrow(
            /alias "ref" is declared by both "id" and "thing_id"/
        )
    })

    it('rejects an alias equal to its own canonical name', () => {
        const config: ToolConfig = {
            operation: 'things_retrieve',
            enabled: true,
            param_overrides: { id: { aliases: ['id'] } },
        }

        expect(() => composeToolSchema(config, resolvedWithIdAndQuery, makeSpec(), stubGetQuerySchema)).toThrow(
            /alias "id" for param "id"/
        )
    })
})

describe('generateCategoryFile with a missing operation', () => {
    const tool = {
        operation: 'things_gone',
        scopes: ['thing:read'],
        annotations: { readOnly: true, destructive: false, idempotent: true },
    }

    it.each([
        { name: 'exits for an enabled tool', enabled: true, exits: true },
        { name: 'skips a disabled tool', enabled: false, exits: false },
    ])('$name', ({ enabled, exits }) => {
        const exit = vi.spyOn(process, 'exit').mockImplementation((() => {
            throw new Error('process.exit')
        }) as never)
        const error = vi.spyOn(console, 'error').mockImplementation(() => {})
        const category = { ...defaultCategory, tools: { 'thing-get': { ...tool, enabled } } }
        const generate = (): unknown =>
            generateCategoryFile(category, 'things.yaml', 'things', makeSpec(), new Set(), stubGetQuerySchema as never)

        if (exits) {
            expect(generate).toThrow('process.exit')
            expect(exit).toHaveBeenCalledWith(1)
            expect(error).toHaveBeenCalledWith(expect.stringContaining('things_gone'))
        } else {
            expect(generate).not.toThrow()
            expect(exit).not.toHaveBeenCalled()
        }
        vi.restoreAllMocks()
    })
})

describe('derived scopes and annotations', () => {
    const readAndWrite = [{ PersonalAPIKeyAuth: ['thing:read', 'thing:write'] }]

    function specWith(
        method: string,
        security?: Array<Record<string, string[]>>,
        requestDependentScopes?: boolean
    ): OpenApiSpec {
        return makeSpec({
            paths: {
                '/api/projects/{project_id}/things/': {
                    [method.toLowerCase()]: {
                        operationId: 'things_op',
                        parameters: [],
                        security,
                        'x-request-dependent-scopes': requestDependentScopes,
                    },
                },
            },
        })
    }

    function generate(spec: OpenApiSpec, tool: Partial<ToolConfig>): ReturnType<typeof generateCategoryFile> {
        const category = {
            ...defaultCategory,
            tools: { 'thing-op': { operation: 'things_op', enabled: true, ...tool } as ToolConfig },
        }
        return generateCategoryFile(category, 'products/things/mcp/tools.yaml', 'things', spec, new Set(), () => ({
            definitions: {},
        }))
    }

    function generateAndCaptureExit(spec: OpenApiSpec, tool: Partial<ToolConfig>): string {
        const errors: string[] = []
        vi.spyOn(console, 'error').mockImplementation((message: string) => {
            errors.push(message)
        })
        vi.spyOn(process, 'exit').mockImplementation((() => {
            throw new Error('exit')
        }) as never)
        expect(() => generate(spec, tool)).toThrow('exit')
        return errors.join('\n')
    }

    afterEach(() => {
        vi.restoreAllMocks()
        vi.unstubAllEnvs()
    })

    it.each([
        {
            name: 'takes scopes from the spec when the YAML has none',
            security: readAndWrite,
            yamlScopes: undefined,
            expected: ['thing:read', 'thing:write'],
        },
        {
            name: 'dedupes scopes repeated across security entries',
            security: [{ PersonalAPIKeyAuth: ['thing:read'] }, { PersonalAPIKeyAuth: ['thing:read'] }],
            yamlScopes: undefined,
            expected: ['thing:read'],
        },
        {
            name: 'prefers explicit YAML scopes over the spec',
            security: readAndWrite,
            yamlScopes: ['thing:write'],
            expected: ['thing:write'],
        },
    ])('scopes: $name', ({ security, yamlScopes, expected }) => {
        const { enabledTools } = generate(specWith('GET', security), { scopes: yamlScopes })

        expect(enabledTools[0]?.[1].scopes).toEqual(expected)
    })

    it.each([
        {
            name: 'no security block',
            security: undefined,
            requestDependent: false,
            error: /Add "scopes" to the tool's YAML/,
        },
        {
            name: 'an empty security requirement',
            security: [{}],
            requestDependent: false,
            error: /Add "scopes" to the tool's YAML/,
        },
        {
            name: 'request-dependent scopes',
            security: readAndWrite,
            requestDependent: true,
            error: /picks the scopes for "things_op" per request/,
        },
    ])('scopes: fails when the YAML has none and the spec has $name', ({ security, requestDependent, error }) => {
        expect(generateAndCaptureExit(specWith('GET', security, requestDependent), {})).toMatch(error)
    })

    it.each([
        { method: 'GET', expected: { readOnly: true, destructive: false, idempotent: true } },
        { method: 'DELETE', expected: { readOnly: false, destructive: true, idempotent: true } },
    ])('annotations: $method defaults to $expected', ({ method, expected }) => {
        const { enabledTools } = generate(specWith(method, readAndWrite), {})

        expect(enabledTools[0]?.[1].annotations).toEqual(expected)
    })

    it.each(['PATCH', 'POST', 'PUT'])('annotations: %s without annotations fails', (method) => {
        expect(generateAndCaptureExit(specWith(method, readAndWrite), {})).toMatch(
            new RegExp(`${method} endpoints have no defaults`)
        )
    })

    it('annotations: explicit YAML wins over the method default', () => {
        const explicit = { readOnly: false, destructive: true, idempotent: false }

        const { enabledTools } = generate(specWith('GET', readAndWrite), { annotations: explicit })

        expect(enabledTools[0]?.[1].annotations).toEqual(explicit)
    })

    describe('scope coverage check', () => {
        function runCoverage(spec: OpenApiSpec, tool: Partial<ToolConfig>): { exited: boolean; output: string } {
            const lines: string[] = []
            vi.spyOn(console, 'error').mockImplementation((message: string) => {
                lines.push(message)
            })
            vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
                lines.push(String(chunk))
                return true
            })
            vi.spyOn(process, 'exit').mockImplementation((() => {
                throw new Error('exit')
            }) as never)
            let exited = false
            try {
                generate(spec, tool)
            } catch {
                exited = true
            }
            return { exited, output: lines.join('') }
        }

        it.each([
            { name: 'YAML misses a spec scope', yamlScopes: ['thing:read'], requestDependent: false, fails: true },
            {
                name: 'YAML is broader than the spec',
                yamlScopes: ['thing:read', 'thing:write', 'thing:admin'],
                requestDependent: false,
                fails: false,
            },
            { name: 'YAML has no scopes', yamlScopes: undefined, requestDependent: false, fails: false },
            {
                name: 'the API picks the scopes per request',
                yamlScopes: ['task:read'],
                requestDependent: true,
                fails: false,
            },
        ])('$name -> fails: $fails', ({ yamlScopes, requestDependent, fails }) => {
            const { exited, output } = runCoverage(specWith('GET', readAndWrite, requestDependent), {
                scopes: yamlScopes,
            })

            expect(exited).toBe(fails)
            expect(output.includes('thing:write')).toBe(fails)
            if (fails) {
                expect(output).toContain('Tool "thing-op"')
                expect(output).toContain('products/things/mcp/tools.yaml')
            }
        })

        it('treats a write scope as covering a spec read scope', () => {
            const { exited, output } = runCoverage(specWith('GET', [{ PersonalAPIKeyAuth: ['thing:read'] }]), {
                scopes: ['thing:write'],
            })

            expect(exited).toBe(false)
            expect(output).toBe('')
        })

        it('skips tools whose spec declares no scopes', () => {
            const { exited, output } = runCoverage(specWith('GET', undefined), { scopes: ['thing:read'] })

            expect(exited).toBe(false)
            expect(output).toBe('')
        })

        it.each([
            { githubActions: 'true', annotated: true },
            { githubActions: 'false', annotated: false },
        ])('emits a GitHub annotation only on CI (GITHUB_ACTIONS=$githubActions)', ({ githubActions, annotated }) => {
            vi.stubEnv('GITHUB_ACTIONS', githubActions)

            const { output } = runCoverage(specWith('GET', readAndWrite), { scopes: ['thing:read'] })

            expect(output.includes('::error file=products/things/mcp/tools.yaml::')).toBe(annotated)
        })
    })
})

describe('hooks', () => {
    const spec = makeSpec({
        paths: {
            '/api/projects/{project_id}/things/': {
                get: { operationId: 'things_list', parameters: [], security: [{ PersonalAPIKeyAuth: ['thing:read'] }] },
            },
        },
    })

    function generate(tool: Partial<ToolConfig>): ReturnType<typeof generateCategoryFile> {
        const category = {
            ...defaultCategory,
            tools: { 'thing-list': { operation: 'things_list', enabled: true, ...tool } as ToolConfig },
        }
        return generateCategoryFile(category, 'products/things/mcp/tools.yaml', 'things', spec, new Set(), () => ({
            definitions: {},
        }))
    }

    afterEach(() => {
        vi.restoreAllMocks()
    })

    it('imports the hooks module and wraps the handler', () => {
        const { code } = generate({ hooks: 'tool-hooks' })

        expect(code).toContain("import hooks_thingList from '@/tools/tool-hooks'")
        expect(code).toContain("import { withToolHooks } from '@/tools/tool-hooks'")
        expect(code).toMatch(/handler: withToolHooks\(\s*hooks_thingList,\s*async \(context: Context/)
    })

    it('passes the built request body through transformRequestBody', () => {
        const resolved = makeResolved({
            method: 'POST',
            operation: {
                operationId: 'things_create',
                parameters: [],
                requestBody: {
                    content: { 'application/json': { schema: { properties: { name: { type: 'string' } } } } },
                },
            },
        })
        const config: ToolConfig = { operation: 'things_create', enabled: true, hooks: 'tool-hooks' }

        const { code } = generateToolCode(
            'things-create',
            config,
            resolved,
            defaultCategory,
            makeSpec(),
            new Set<string>(),
            stubGetQuerySchema
        )

        expect(code).toContain('body: await transformRequestBody(hooks_thingsCreate, context, params, body)')
    })

    it('leaves tools without hooks unwrapped', () => {
        const { code } = generate({})

        expect(code).not.toContain('withToolHooks')
        expect(code).toContain('handler: async (context: Context')
    })

    it('fails when the hooks module does not exist', () => {
        const errors: string[] = []
        vi.spyOn(console, 'error').mockImplementation((message: string) => {
            errors.push(message)
        })
        vi.spyOn(process, 'exit').mockImplementation((() => {
            throw new Error('exit')
        }) as never)

        expect(() => generate({ hooks: 'nowhere/missingHooks' })).toThrow('exit')
        expect(errors.join('\n')).toMatch(/hooks module "nowhere\/missingHooks" not found/)
    })

    it('rejects hooks combined with confirmed_action', () => {
        const result = ToolConfigSchema.safeParse({
            operation: 'things_list',
            enabled: true,
            hooks: 'tool-hooks',
            confirmed_action: {},
        })

        expect(result.success).toBe(false)
    })
})