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.

30.9 KB
Raw Blame
#!/usr/bin/env tsx
/**
 * Scaffolds and maintains YAML tool definitions from the OpenAPI schema.
 *
 * Discovers operations by the x-product values the spec emits per operation:
 * auto-derived from the ViewSet module path (products/<name>/backend/) or
 * declared explicitly via @extend_schema(extensions={"x-product": "<name>"}).
 * There is deliberately no URL-based guessing — paths are a lossy projection
 * of ownership and used to poach operations across products.
 *
 * Tools are opt-in. An operation has a YAML entry only when someone added it
 * (`--add`) or keeps it off on purpose (`enabled: false` + `disabled_reason`).
 * Sync never writes entries for new operations, so a new endpoint does not
 * rewrite the product's YAML file. `--candidates` lists the operations that
 * have no entry yet.
 *
 * Usage:
 *   pnpm scaffold-yaml --product error_tracking --output ../../products/error_tracking/mcp/tools.yaml
 *   pnpm scaffold-yaml --candidates --product error_tracking
 *   pnpm scaffold-yaml --add error_tracking_issues_list --product error_tracking [--file <yaml>]
 *   pnpm scaffold-yaml --sync-all
 */
import { spawnSync } from 'node:child_process'
import * as fs from 'node:fs'
import * as path from 'node:path'
import { fileURLToPath } from 'node:url'
import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'

import { discoverDefinitions } from './lib/definitions.mjs'
import { type CategoryConfig, CategoryConfigSchema } from './yaml-config-schema'

const MCP_ROOT = path.resolve(__dirname, '..')
const REPO_ROOT = path.resolve(MCP_ROOT, '../..')
const PRODUCTS_DIR = path.resolve(REPO_ROOT, 'products')
const OPENAPI_PATH = path.resolve(REPO_ROOT, 'frontend/tmp/openapi.json')
const DEFINITIONS_DIR = path.resolve(MCP_ROOT, 'definitions')

const productAliases: Record<string, string> = {
    llm_analytics: 'ai_observability',
}

// ------------------------------------------------------------------
// Types
// ------------------------------------------------------------------

interface OpenApiOperation {
    operationId: string
    parameters?: Array<{ in: string; name: string }>
    summary?: string
    description?: string
    deprecated?: boolean
    security?: Array<Record<string, string[]>>
    'x-product'?: string[]
    'x-request-dependent-scopes'?: boolean
}

interface OpenApiSpec {
    paths: Record<string, Record<string, OpenApiOperation>>
}

interface DiscoveredOperation {
    operationId: string
    method: string
    path: string
    summary?: string | undefined
    description?: string | undefined
    /** Codegen cannot take the scopes from the spec, so the YAML entry must list them. */
    needsExplicitScopes: boolean
}

// A file other than the product's default `--add` target needs `--file`, or the command fails or writes to tools.yaml.
function addCommandFlags(product: string, filePath: string | undefined): string {
    const flags = `--product ${product}`
    if (!filePath || path.resolve(filePath) === defaultProductFile(product)) {
        return flags
    }
    return `${flags} --file ${path.relative(MCP_ROOT, filePath)}`
}

function yamlHeader(product: string, filePath: string | undefined): string {
    return `# MCP tool definitions. Tools are opt-in: an operation is exposed only when it has an entry here.
# List operations without an entry: pnpm --filter=@posthog/mcp run scaffold-yaml -- --candidates --product ${product}
# Add one: pnpm --filter=@posthog/mcp run scaffold-yaml -- --add <operationId> ${addCommandFlags(product, filePath)}
# To keep an operation off on purpose, set enabled: false and give a disabled_reason.
`
}

// ------------------------------------------------------------------
// Helpers
// ------------------------------------------------------------------

function formatWithPrettier(filePaths: string[]): void {
    if (filePaths.length === 0) {
        return
    }
    try {
        spawnSync('pnpm', ['exec', 'oxfmt', '--no-error-on-unmatched-pattern', ...filePaths], {
            stdio: 'pipe',
            cwd: REPO_ROOT,
        })
    } catch {
        // Not critical — oxfmt may not be available in all environments
    }
}

function loadOpenApi(): OpenApiSpec {
    if (!fs.existsSync(OPENAPI_PATH)) {
        console.error(`OpenAPI schema not found at ${OPENAPI_PATH}. Run \`hogli build:openapi-schema\` first.`)
        process.exit(1)
    }
    return JSON.parse(fs.readFileSync(OPENAPI_PATH, 'utf-8')) as OpenApiSpec
}

function operationIdToToolName(operationId: string): string {
    return operationId.replace(/[_.]+/g, '-')
}

/** drf-spectacular appends _N to an operationId mounted at several paths (/api/environments/ and /api/projects/). */
function baseOperationId(operationId: string): string {
    return operationId.replace(/_\d+$/, '')
}

/**
 * Find operations whose x-product list names this product. Values are
 * auto-derived from the ViewSet module path (products/<name>/backend/ →
 * "<name>") or declared via @extend_schema(extensions={"x-product": "..."}).
 * Both sides are normalized (kebab → snake) so hyphenated definition
 * filenames like proxy-records match the snake_case x-product value.
 */
function findOperationsByProduct(spec: OpenApiSpec, product: string): DiscoveredOperation[] {
    const ops: DiscoveredOperation[] = []
    const httpMethods = new Set(['get', 'post', 'put', 'patch', 'delete'])
    const normalize = (name: string): string => name.toLowerCase().replace(/-/g, '_')
    const matchingProducts = new Set(
        [
            product,
            ...Object.entries(productAliases)
                .filter(([, target]) => target === product)
                .map(([source]) => source),
        ].map(normalize)
    )

    for (const [urlPath, methods] of Object.entries(spec.paths)) {
        for (const [method, op] of Object.entries(methods)) {
            if (!httpMethods.has(method) || !op?.operationId || op.deprecated) {
                continue
            }
            const xProduct = op['x-product'] ?? []
            if (xProduct.some((value) => matchingProducts.has(normalize(value)))) {
                ops.push({
                    operationId: op.operationId,
                    method: method.toUpperCase(),
                    path: urlPath,
                    summary: op.summary,
                    description: op.description,
                    needsExplicitScopes:
                        Boolean(op['x-request-dependent-scopes']) ||
                        !(op.security ?? []).some((requirement) =>
                            Object.values(requirement).some((scopes) => scopes.length > 0)
                        ),
                })
            }
        }
    }

    return ops
}

function specHasOperation(spec: OpenApiSpec, operationId: string): boolean {
    return Object.values(spec.paths).some((methods) =>
        Object.values(methods).some((op) => op?.operationId === operationId)
    )
}

/**
 * Deduplicate operations mounted at both /api/environments/ and /api/projects/.
 * Prefers /api/projects/ paths. Uses the clean base operationId (strips _N suffix).
 */
function deduplicateOperations(ops: DiscoveredOperation[]): DiscoveredOperation[] {
    const groups = new Map<string, DiscoveredOperation[]>()
    for (const op of ops) {
        const base = baseOperationId(op.operationId)
        const group = groups.get(base) ?? []
        group.push(op)
        groups.set(base, group)
    }

    const result: DiscoveredOperation[] = []
    for (const [base, group] of groups) {
        if (group.length === 1) {
            result.push(group[0]!)
            continue
        }
        // Prefer /api/projects/ over /api/environments/
        const preferred = group.find((op) => op.path.startsWith('/api/projects/')) ?? group[0]!
        // Use clean base operationId for the tool name
        result.push({ ...preferred, operationId: base })
    }

    return result
}

function renderCategoryYaml(
    existing: CategoryConfig,
    tag: string,
    tools: Record<string, unknown>,
    filePath?: string
): string {
    const sortedTools = Object.fromEntries(Object.entries(tools).sort(([a], [b]) => a.localeCompare(b)))

    const merged: Record<string, unknown> = {
        category: existing.category ?? tag.charAt(0).toUpperCase() + tag.slice(1),
        feature: existing.feature ?? tag.replace(/-/g, '_'),
        url_prefix: existing.url_prefix ?? `/${tag.replace(/_/g, '-')}`,
        // Hand-authored category-level gate — sync must not drop it.
        ...(existing.feature_flag ? { feature_flag: existing.feature_flag } : {}),
        ...(existing.feature_flag_behavior ? { feature_flag_behavior: existing.feature_flag_behavior } : {}),
        ...(existing.feature_flag_variant ? { feature_flag_variant: existing.feature_flag_variant } : {}),
        ...(existing.feature_entitlement ? { feature_entitlement: existing.feature_entitlement } : {}),
        ui_apps: existing.ui_apps ?? {},
        tools: sortedTools,
    }

    // Query wrappers are hand-authored (schema.json); OpenAPI sync must not drop them.
    if (existing.wrappers !== undefined) {
        merged.wrappers = existing.wrappers
    }

    return yamlHeader(tag, filePath) + stringifyYaml(merged, { indent: 4, lineWidth: 120 })
}

function generateFreshYaml(tag: string, filePath?: string): string {
    const fresh = CategoryConfigSchema.parse({
        category: tag.charAt(0).toUpperCase() + tag.slice(1),
        feature: tag.replace(/-/g, '_'),
        url_prefix: `/${tag.replace(/_/g, '-')}`,
        tools: {},
    })
    return renderCategoryYaml(fresh, tag, {}, filePath)
}

function loadCategoryConfig(filePath: string): CategoryConfig {
    const parsed = parseYaml(fs.readFileSync(filePath, 'utf-8'))
    const result = CategoryConfigSchema.safeParse(parsed)
    if (!result.success) {
        console.error(`Invalid existing YAML config in ${filePath}:`)
        for (const issue of result.error.issues) {
            console.error(`  ${issue.path.join('.')}: ${issue.message}`)
        }
        process.exit(1)
    }
    return result.data
}

/**
 * Never adds entries for new operations, because tools are opt-in (see `--add`).
 * A disabled entry without a `disabled_reason` is a leftover stub: dropped and
 * reported in `droppedDisabledTools`. An entry whose operation is gone:
 * - enabled: kept and reported in `lostEnabledTools`, because dropping it would
 *   silently remove a live tool.
 * - disabled (with its disabled_reason): dropped and reported in
 *   `droppedDisabledTools`, because the decision no longer applies.
 * - in a subset file: kept and reported in `unmatchedTools`, because a subset
 *   file can reference operations of another product.
 */
function mergeWithExisting(
    existing: CategoryConfig,
    ops: DiscoveredOperation[],
    tag: string,
    validOperationIds: Set<string>,
    subset = false,
    filePath?: string
): {
    content: string
    updated: number
    matched: number
    unmatchedTools: string[]
    lostEnabledTools: string[]
    droppedDisabledTools: string[]
} {
    const openApiByBase = new Map(ops.map((op) => [baseOperationId(op.operationId), op]))
    const mergedTools: Record<string, unknown> = {}
    let updated = 0
    let matched = 0
    const unmatchedTools: string[] = []
    const lostEnabledTools: string[] = []
    const droppedDisabledTools: string[] = []

    for (const [name, config] of Object.entries(existing.tools)) {
        if (!config.enabled && !config.disabled_reason) {
            droppedDisabledTools.push(`${name} (${config.operation}): no disabled_reason`)
            continue
        }
        const op = openApiByBase.get(baseOperationId(config.operation))
        if (op) {
            // Keep the author's chosen operation variant if it still exists in
            // OpenAPI — they may have picked a specific _N suffix deliberately
            // (e.g. _2 for /api/projects/ path). Fall back to the deduped
            // operationId when their variant was renumbered or removed.
            const operation = validOperationIds.has(config.operation) ? config.operation : op.operationId
            mergedTools[name] = { ...config, operation }
            if (operation !== config.operation) {
                updated++
            }
            matched++
        } else if (subset) {
            mergedTools[name] = { ...config }
            unmatchedTools.push(`${name} (${config.operation})`)
        } else if (config.enabled) {
            mergedTools[name] = { ...config }
            lostEnabledTools.push(`${name} (${config.operation})`)
        } else {
            droppedDisabledTools.push(`${name} (${config.operation}): operation no longer in OpenAPI`)
        }
    }

    return {
        content: renderCategoryYaml(existing, tag, mergedTools, filePath),
        updated,
        matched,
        unmatchedTools,
        lostEnabledTools,
        droppedDisabledTools,
    }
}

/**
 * An enabled tool whose operation vanished stays in the YAML. Report it and
 * fail the command so the author fixes it before codegen rejects the file.
 */
function reportLostEnabledTools(lostEnabledTools: string[]): void {
    if (lostEnabledTools.length === 0) {
        return
    }
    process.stderr.write(
        `  ✗ ${lostEnabledTools.length} enabled tool(s) reference an operationId that no longer exists in OpenAPI. ` +
            `Fix "operation:" or remove the tool:\n`
    )
    for (const tool of lostEnabledTools) {
        process.stderr.write(`    - ${tool}\n`)
    }
    process.exitCode = 1
}

function reportDroppedDisabledTools(droppedDisabledTools: string[]): void {
    if (droppedDisabledTools.length === 0) {
        return
    }
    process.stdout.write(`  ${droppedDisabledTools.length} disabled tool(s) removed:\n`)
    for (const tool of droppedDisabledTools) {
        process.stdout.write(`    - ${tool}\n`)
    }
}

interface Claims {
    baseIds: Set<string>
    fileByToolName: Map<string, string>
}

// Reads every definition file because an operation can be claimed outside its
// product's tools.yaml, for example by a subset file of another product.
// Tool names are global: codegen merges all files into one tool map, so a duplicate name replaces a tool.
function collectClaims(): Claims {
    const claims: Claims = { baseIds: new Set(), fileByToolName: new Map() }
    for (const { filePath } of discoverDefinitions({ definitionsDir: DEFINITIONS_DIR, productsDir: PRODUCTS_DIR })) {
        const parsed = parseYaml(fs.readFileSync(filePath, 'utf-8')) as {
            tools?: Record<string, unknown>
            wrappers?: Record<string, unknown>
        } | null
        const label = path.relative(REPO_ROOT, filePath)
        for (const [name, config] of Object.entries(parsed?.tools ?? {})) {
            const entry = config as { operation?: unknown; enabled?: unknown; disabled_reason?: unknown } | null
            // Sync removes a disabled entry without a reason, so it claims nothing.
            if (entry?.enabled !== true && !entry?.disabled_reason) {
                continue
            }
            claims.fileByToolName.set(name, label)
            const operation = entry.operation
            if (typeof operation === 'string') {
                claims.baseIds.add(baseOperationId(operation))
            }
        }
        for (const name of Object.keys(parsed?.wrappers ?? {})) {
            claims.fileByToolName.set(name, label)
        }
    }
    return claims
}

function findCandidates(spec: OpenApiSpec, product: string, claimedBaseIds: Set<string>): DiscoveredOperation[] {
    return deduplicateOperations(findOperationsByProduct(spec, product))
        .filter((op) => !claimedBaseIds.has(baseOperationId(op.operationId)))
        .sort((a, b) => a.operationId.localeCompare(b.operationId))
}

function oneLine(text: string | undefined, maxLength: number): string {
    const flat = (text ?? '').replace(/\s+/g, ' ').trim()
    return flat.length > maxLength ? `${flat.slice(0, maxLength - 1)}…` : flat
}

function productDefinitionFiles(product: string): string[] {
    const files: string[] = []
    const mcpDir = path.join(PRODUCTS_DIR, product, 'mcp')
    if (fs.existsSync(mcpDir)) {
        files.push(...fs.readdirSync(mcpDir).map((file) => path.join(mcpDir, file)))
    }
    files.push(path.join(DEFINITIONS_DIR, `${product}.yaml`), path.join(DEFINITIONS_DIR, `${product}.yml`))
    return files.filter((file) => /\.ya?ml$/.test(file) && fs.existsSync(file)).sort()
}

function formatCandidates(
    candidates: DiscoveredOperation[],
    product: string,
    productFiles: string[],
    defaultFile: string | undefined
): string {
    if (candidates.length === 0) {
        return `Every OpenAPI operation of "${product}" already has a YAML entry.\n`
    }
    const idWidth = Math.max(...candidates.map((op) => op.operationId.length))
    const lines = candidates.map((op) =>
        [op.operationId.padEnd(idWidth), op.method.padEnd(6), op.path, oneLine(op.summary || op.description, 80)]
            .join('  ')
            .trimEnd()
    )
    return (
        `${candidates.length} operation(s) of "${product}" have no YAML entry:\n` +
        lines.map((line) => `  ${line}\n`).join('') +
        `\nAdd one as an enabled tool:\n` +
        `  pnpm --filter=@posthog/mcp run scaffold-yaml -- --add <operationId> --product ${product}\n` +
        // Without --file the entry lands in the default file, and codegen builds its links from that file's url_prefix.
        (productFiles.some((file) => file !== defaultFile)
            ? (defaultFile
                  ? `Add --file <path> to write it to another file of "${product}":\n`
                  : `"${product}" has no tools.yaml, so add --file <path>:\n`) +
              productFiles.map((file) => `  ${path.relative(MCP_ROOT, file)}\n`).join('')
            : '')
    )
}

function buildAddedTool(
    spec: OpenApiSpec,
    product: string,
    operationId: string,
    claims: Claims
): { toolName: string; op: DiscoveredOperation; entry: Record<string, unknown> } {
    const rawOps = findOperationsByProduct(spec, product)
    const ops = deduplicateOperations(rawOps)
    const isProductOperation = [...rawOps, ...ops].some((candidate) => candidate.operationId === operationId)
    if (!isProductOperation) {
        if (specHasOperation(spec, operationId)) {
            throw new Error(
                `Operation "${operationId}" is not attributed to product "${product}". ` +
                    `Pass the product its x-product names, or fix the x-product attribution on the ViewSet.`
            )
        }
        throw new Error(`Operation "${operationId}" is not in the OpenAPI schema. Run hogli build:openapi first.`)
    }

    const base = baseOperationId(operationId)
    if (claims.baseIds.has(base)) {
        throw new Error(`Operation "${operationId}" already has a YAML entry. Edit that entry instead.`)
    }

    const op = ops.find((candidate) => baseOperationId(candidate.operationId) === base)!
    const toolName = operationIdToToolName(op.operationId)
    const nameOwner = claims.fileByToolName.get(toolName)
    if (nameOwner) {
        throw new Error(`Tool name "${toolName}" is already used in ${nameOwner}.`)
    }

    // Title and description fall back to the spec in codegen, so the entry only overrides them when needed.
    const entry: Record<string, unknown> = { operation: operationId, enabled: true }
    // The entry names this exact variant, so its scopes decide the next-step hints.
    const selected = rawOps.find((candidate) => candidate.operationId === operationId) ?? op
    return { toolName, op: selected, entry }
}

function defaultProductFile(product: string): string | undefined {
    const candidates = [
        path.join(PRODUCTS_DIR, product, 'mcp', 'tools.yaml'),
        path.join(PRODUCTS_DIR, product, 'mcp', 'tools.yml'),
        path.join(DEFINITIONS_DIR, `${product}.yaml`),
        path.join(DEFINITIONS_DIR, `${product}.yml`),
    ]
    return candidates.find((candidate) => fs.existsSync(candidate))
}

// ------------------------------------------------------------------
// CLI
// ------------------------------------------------------------------

/**
 * Re-sync all existing YAML definitions. Derives the product name from the
 * file/directory structure, finds its OpenAPI operations by x-product, and
 * merges them with `mergeWithExisting`. Idempotent, and never adds entries.
 * Runs oxfmt on written files so output matches what lint-staged produces.
 */
function syncAll(spec: OpenApiSpec): void {
    interface SyncTarget {
        product: string
        filePath: string
        /** Subset files (filename != tools.yaml) keep entries whose operation is not found */
        subset: boolean
    }

    const targets: SyncTarget[] = []

    // Core definitions — product derived from filename (e.g. actions.yaml → "actions")
    if (fs.existsSync(DEFINITIONS_DIR)) {
        for (const file of fs.readdirSync(DEFINITIONS_DIR)) {
            if (!file.endsWith('.yaml') && !file.endsWith('.yml')) {
                continue
            }
            // Skip query wrapper configs — they don't map to OpenAPI operations
            const filePath = path.join(DEFINITIONS_DIR, file)
            const parsed = parseYaml(fs.readFileSync(filePath, 'utf-8'))
            if (typeof parsed === 'object' && parsed !== null && 'wrappers' in parsed && !('tools' in parsed)) {
                continue
            }
            targets.push({
                product: file.replace(/\.ya?ml$/, ''),
                filePath,
                subset: false,
            })
        }
    }

    // Product definitions — product always from directory name.
    // Non-tools.yaml files are subset files that own a curated slice of the
    // product's operations (e.g. prompts.yaml inside llm_analytics/mcp/).
    if (fs.existsSync(PRODUCTS_DIR)) {
        for (const entry of fs.readdirSync(PRODUCTS_DIR, { withFileTypes: true })) {
            if (!entry.isDirectory() || entry.name.startsWith('_')) {
                continue
            }
            const mcpDir = path.join(PRODUCTS_DIR, entry.name, 'mcp')
            if (!fs.existsSync(mcpDir)) {
                continue
            }
            for (const file of fs.readdirSync(mcpDir)) {
                if (!file.endsWith('.yaml') && !file.endsWith('.yml')) {
                    continue
                }
                const subset = file !== 'tools.yaml' && file !== 'tools.yml'
                targets.push({ product: entry.name, filePath: path.join(mcpDir, file), subset })
            }
        }
    }

    if (targets.length === 0) {
        process.stdout.write('No existing YAML definitions found.\n')
        return
    }

    const writtenFiles: string[] = []
    const noOpsProducts: string[] = []

    for (const { product, filePath, subset } of targets) {
        const rawOps = findOperationsByProduct(spec, product)
        const ops = deduplicateOperations(rawOps)
        if (ops.length === 0) {
            const label = path.relative(REPO_ROOT, filePath)
            const normalized = product.replace(/-/g, '_').toLowerCase()
            process.stderr.write(
                `⚠ ${label}: no operations found in OpenAPI for "${product}"\n` +
                    `  → declare @extend_schema(extensions={"x-product": "${normalized}"}) on the ViewSet, ` +
                    `or place it in products/${normalized}/backend/ for module-path auto-attribution\n`
            )
            noOpsProducts.push(label)
            continue
        }
        const label = path.relative(REPO_ROOT, filePath)
        const validIds = new Set(rawOps.map((op) => op.operationId))
        const { content, updated, matched, unmatchedTools, lostEnabledTools, droppedDisabledTools } = mergeWithExisting(
            loadCategoryConfig(filePath),
            ops,
            product,
            validIds,
            subset,
            filePath
        )
        fs.writeFileSync(filePath, content)
        writtenFiles.push(filePath)
        const total = matched + unmatchedTools.length
        const parts = [
            subset ? (total === 0 ? '0 tool(s)' : `${matched}/${total} tool(s) matched`) : `${matched} tool(s)`,
        ]
        if (droppedDisabledTools.length > 0) {
            parts.push(`${droppedDisabledTools.length} removed`)
        }
        if (updated > 0) {
            parts.push(`${updated} operation ID(s) updated`)
        }
        if (droppedDisabledTools.length === 0 && updated === 0 && unmatchedTools.length === 0) {
            parts.push('no changes')
        }
        process.stdout.write(`${label}: ${parts.join(', ')}\n`)
        if (unmatchedTools.length > 0) {
            process.stderr.write(
                `  ⚠ ${unmatchedTools.length} tool(s) not found in OpenAPI — add @extend_schema(extensions={"x-product": "${product}"}) to the ViewSet\n`
            )
            for (const tool of unmatchedTools) {
                process.stderr.write(`    - ${tool}\n`)
            }
        }
        reportDroppedDisabledTools(droppedDisabledTools)
        reportLostEnabledTools(lostEnabledTools)
    }

    formatWithPrettier(writtenFiles)

    if (noOpsProducts.length > 0) {
        process.stderr.write(
            `\n${noOpsProducts.length} file(s) had no matching OpenAPI operations — see warnings above\n`
        )
        process.exitCode = 1
    }
}

function formatAddNextSteps(op: DiscoveredOperation): string {
    const steps = [
        'check the title and description the API gives the tool, set them in the YAML if they do not read well for an agent',
    ]
    if (!['GET', 'DELETE'].includes(op.method)) {
        steps.push(`add annotations (required for ${op.method})`)
    }
    if (op.needsExplicitScopes) {
        steps.push('add "scopes" (required: the API picks the scopes per request, so the spec cannot supply them)')
    }
    return `Next: ${steps.join(', ')}, then run hogli build:openapi to generate the tool.\n`
}

function addTool(spec: OpenApiSpec, product: string, operationId: string, filePath: string | undefined): void {
    const targetFile = filePath ? path.resolve(MCP_ROOT, filePath) : defaultProductFile(product)
    if (!targetFile || !fs.existsSync(targetFile)) {
        console.error(
            `No YAML file for product "${product}". Create one with ` +
                `--product ${product} --output ../../products/${product}/mcp/tools.yaml, or pass --file <path>.`
        )
        process.exit(1)
    }

    const existing = loadCategoryConfig(targetFile)
    let added: ReturnType<typeof buildAddedTool>
    try {
        added = buildAddedTool(spec, product, operationId, collectClaims())
    } catch (error) {
        console.error(error instanceof Error ? error.message : String(error))
        process.exit(1)
    }

    fs.writeFileSync(
        targetFile,
        renderCategoryYaml(existing, product, { ...existing.tools, [added.toolName]: added.entry }, targetFile)
    )
    formatWithPrettier([targetFile])

    const label = path.relative(REPO_ROOT, targetFile)
    process.stdout.write(`Added "${added.toolName}" (${added.op.method} ${added.op.path}) to ${label}.\n`)
    process.stdout.write(formatAddNextSteps(added.op))
}

const USAGE = `Usage: scaffold-yaml --product <name> [--output <file>]   create or re-sync one product file
       scaffold-yaml --candidates --product <name>          list operations without a YAML entry
       scaffold-yaml --add <operationId> --product <name> [--file <yaml>]
       scaffold-yaml --sync-all                             re-sync every YAML file

--product discovers endpoints by x-product: module-path auto-attribution,
or declared explicitly via @extend_schema(extensions={"x-product": "..."}).
Uses the product folder name (underscores), e.g. error_tracking, workflows.
--output and --file resolve relative to services/mcp/.`

function main(): void {
    const args = process.argv.slice(2)
    let product: string | undefined
    let outputPath: string | undefined
    let addOperationId: string | undefined
    let filePath: string | undefined

    for (let i = 0; i < args.length; i++) {
        const flag = args[i]
        if (!flag || !['--product', '--output', '--add', '--file'].includes(flag)) {
            continue
        }
        const value = args[i + 1]
        if (!value || value.startsWith('--')) {
            console.error(`${flag} needs a value.\n\n${USAGE}`)
            process.exit(1)
        }
        i++
        if (flag === '--product') {
            product = value
        } else if (flag === '--output') {
            outputPath = value
        } else if (flag === '--add') {
            addOperationId = value
        } else {
            filePath = value
        }
    }

    if (args.includes('--sync-all')) {
        syncAll(loadOpenApi())
        return
    }

    if (!product) {
        console.error(USAGE)
        process.exit(1)
    }

    if (args.includes('--candidates')) {
        const spec = loadOpenApi()
        if (findOperationsByProduct(spec, product).length === 0) {
            console.error(`No operations found for product "${product}"`)
            process.exit(1)
        }
        const candidates = findCandidates(spec, product, collectClaims().baseIds)
        process.stdout.write(
            formatCandidates(candidates, product, productDefinitionFiles(product), defaultProductFile(product))
        )
        return
    }

    if (addOperationId) {
        addTool(loadOpenApi(), product, addOperationId, filePath)
        return
    }

    const spec = loadOpenApi()
    const rawOps = findOperationsByProduct(spec, product)
    const ops = deduplicateOperations(rawOps)

    if (ops.length === 0) {
        console.error(`No operations found for product "${product}"`)
        process.exit(1)
    }

    const resolvedOutput = outputPath
        ? path.resolve(MCP_ROOT, outputPath)
        : path.join(DEFINITIONS_DIR, `${product.replace(/-/g, '_')}.yaml`)

    if (fs.existsSync(resolvedOutput)) {
        const validIds = new Set(rawOps.map((op) => op.operationId))
        const { content, matched, lostEnabledTools, droppedDisabledTools } = mergeWithExisting(
            loadCategoryConfig(resolvedOutput),
            ops,
            product,
            validIds,
            false,
            resolvedOutput
        )
        fs.writeFileSync(resolvedOutput, content)
        process.stdout.write(`${matched} tool(s), ${droppedDisabledTools.length} removed — ${resolvedOutput}\n`)
        reportDroppedDisabledTools(droppedDisabledTools)
        reportLostEnabledTools(lostEnabledTools)
    } else {
        fs.mkdirSync(path.dirname(resolvedOutput), { recursive: true })
        fs.writeFileSync(resolvedOutput, generateFreshYaml(product, resolvedOutput))
        process.stdout.write(
            `Created ${resolvedOutput} with no tools. ${ops.length} operation(s) found; list them with --candidates.\n`
        )
    }

    formatWithPrettier([resolvedOutput])
}

export { buildAddedTool, findCandidates, formatAddNextSteps, formatCandidates, mergeWithExisting, renderCategoryYaml }
export type { Claims, OpenApiSpec }

function stripExt(filePath: string): string {
    return filePath.replace(/\.[jt]s$/, '')
}

// Tests import this module, so run the CLI only when the script itself is executed.
const isDirectRun =
    typeof process !== 'undefined' &&
    process.argv[1] &&
    stripExt(path.resolve(process.argv[1])) === stripExt(fileURLToPath(import.meta.url))

if (isDirectRun) {
    main()
}