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.

9.9 KB
Raw Blame
import { basename, join, relative } from 'node:path'
import { stringify } from 'yaml'

import { defineCommand } from '@/core/command'
import { EXIT_USAGE, HogError } from '@/core/errors'
import { Output } from '@/core/output'
import { absolutePath } from '@/core/paths'
import { plural } from '@/core/text'
import { findEndpoints, findInsightVariables, getInsightVariable, readAllEndpoints } from '@/endpoints/api'
import { readEndpointFiles, type FileProblem } from '@/endpoints/files'
import { fileFromEndpoint, remoteVariableIds, type Endpoint } from '@/endpoints/model'
import { planPull, type PullItem } from '@/endpoints/plan'
import { ApiError, type PostHogApi } from '@/posthog/api'

import { actionLabel, changeLines, CONFIRM_OPTIONS, confirm, indent, SCOPES_READ, type Styler } from './shared'

type PlannedItem = Omit<PullItem, 'endpoint'>

interface PullResult {
    status: 'written' | 'preview' | 'cancelled' | 'nothing_to_do'
    plan: PlannedItem[]
    written: string[]
    problems: FileProblem[]
}

const isYamlFile = (path: string): boolean => /\.ya?ml$/i.test(path)

function pullPlanLines(plan: PlannedItem[], style: Styler): string[] {
    return plan
        .filter((item) => item.action !== 'skip')
        .flatMap((item) => [
            `${actionLabel(item.action, style)}  ${style(item.path, 'bold')}`,
            ...indent(item.changes.flatMap((change) => changeLines(change, 'pull', style))),
        ])
}

// posthog-cli pulls with only endpoint:read. A key that can't read the project's variables gets
// each type from the variable's value instead, as posthog-cli does.
// A variable past the lookup's page cap is fetched by the ID the endpoint's query holds.
async function variableTypes(api: PostHogApi, ids: ReadonlyMap<string, string>): Promise<Map<string, string>> {
    try {
        const { found, complete } = await findInsightVariables(api, [...ids.keys()])
        const types = new Map([...found].map(([name, variable]) => [name, variable.type]))
        if (!complete) {
            for (const [name, id] of ids) {
                if (!types.has(name)) {
                    const variable = await getInsightVariable(api, id).catch(missingAsUndefined)
                    if (variable) {
                        types.set(name, variable.type)
                    }
                }
            }
        }
        return types
    } catch (error) {
        if (error instanceof ApiError && error.status === 403) {
            return new Map()
        }
        throw error
    }
}

function missingAsUndefined(error: unknown): undefined {
    if (error instanceof ApiError && error.status === 404) {
        return undefined
    }
    throw error
}

export function endpointYaml(path: string, item: PullItem, types: ReadonlyMap<string, string>): string {
    const body = stringify(fileFromEndpoint(item.endpoint, types), { lineWidth: 0, blockQuote: 'literal' })
    return `# ${basename(path)}\n${body}`
}

export default defineCommand({
    description: 'Write PostHog endpoints to local YAML files',
    args: { names: { description: 'The endpoints to pull', variadic: true, optional: true } },
    options: {
        all: { type: 'boolean', description: 'Pull every endpoint in the project' },
        to: {
            type: 'string',
            placeholder: 'path',
            description:
                'A folder, or a .yaml file when pulling one endpoint. Defaults to endpoints.dir in posthog.json, then .',
        },
        ...CONFIRM_OPTIONS,
    },
    scopes: SCOPES_READ,
    notes: 'An endpoint a local file already defines updates that file. Others go to <folder>/<name>.yaml. hog shows the changes and asks before it writes; agents and scripts pass --yes. Exits with code 1 when an endpoint is missing or a file is left alone.',
    examples: [
        'hog endpoints pull daily-signups',
        'hog endpoints pull --all --to endpoints/',
        'hog endpoints pull --all --yes',
    ],

    async run({ args, options, ctx }): Promise<PullResult> {
        if (!options.all && args.names.length === 0) {
            throw new HogError(
                'usage_error',
                'Pass the endpoints to pull, or --all.',
                'Run `hog endpoints list` to see the names.',
                EXIT_USAGE
            )
        }
        const loaded = await ctx.config()
        const configured = loaded?.config.endpoints?.dir
        const target =
            options.to !== undefined
                ? absolutePath(ctx.runtime.cwd(), options.to)
                : loaded && configured
                  ? absolutePath(loaded.root, configured)
                  : ctx.runtime.cwd()
        const fileTarget = isYamlFile(target)

        const api = await ctx.posthog()
        const problems: FileProblem[] = []
        let selected: Endpoint[]
        if (options.all) {
            selected = await readAllEndpoints(api)
        } else {
            const found = await findEndpoints(api, args.names)
            const missing = args.names.filter((name) => !found.has(name))
            if (missing.length === args.names.length) {
                throw new HogError(
                    'endpoint_not_found',
                    `PostHog has no endpoint named ${missing.join(', ')}.`,
                    'Run `hog endpoints list` to see the names.'
                )
            }
            problems.push(...missing.map((name) => ({ path: name, message: 'PostHog has no endpoint with this name' })))
            selected = [...found.values()]
        }
        if (fileTarget && selected.length > 1) {
            throw new HogError(
                'usage_error',
                `--to names one file, but there are ${plural(selected.length, 'endpoint')} to pull.`,
                'Pass a folder, or pull one endpoint at a time.',
                EXIT_USAGE
            )
        }

        const scan = fileTarget
            ? (await ctx.runtime.exists(target))
                ? [target]
                : []
            : (await ctx.runtime.isDirectory(target))
              ? [target]
              : []
        const { endpoints: locals, problems: unreadable } = await readEndpointFiles(ctx.runtime, scan)
        const cwd = ctx.runtime.cwd()
        const claimed = new Set(locals.map((local) => absolutePath(cwd, local.path)))
        const broken = new Map(unreadable.map((problem) => [absolutePath(cwd, problem.path), problem.message]))
        const written = new Set<string>()
        // Never write a file twice, replace a file that defines another endpoint, or overwrite one hog can't read.
        const items = planPull(selected, locals, (name) => (fileTarget ? target : join(target, `${name}.yaml`))).map(
            (planned): PullItem => {
                const item = { ...planned, path: absolutePath(cwd, planned.path) }
                const blocked = written.has(item.path)
                    ? 'Another endpoint pulled to the same file'
                    : item.action === 'create' && broken.has(item.path)
                      ? `The file exists but hog can't read it (${broken.get(item.path)}), so hog leaves it alone`
                      : item.action === 'create' && claimed.has(item.path)
                        ? 'The file defines another endpoint'
                        : undefined
                if (blocked) {
                    problems.push({ path: relative(cwd, item.path) || item.path, message: `${item.name}: ${blocked}` })
                    return { ...item, action: 'skip', reason: blocked }
                }
                if (item.action !== 'skip') {
                    written.add(item.path)
                }
                return item
            }
        )
        const shown = (path: string): string => relative(ctx.runtime.cwd(), path) || path
        const plan = items.map(({ endpoint: _endpoint, ...item }) => ({ ...item, path: shown(item.path) }))
        const pending = items.filter((item) => item.action !== 'skip')
        if (pending.length === 0) {
            return { status: 'nothing_to_do', plan, written: [], problems }
        }
        if (options.dryRun) {
            return { status: 'preview', plan, written: [], problems }
        }
        const style: Styler = (text, ...styles) => new Output(ctx.runtime, ctx.mode).style(text, ...styles)
        if (!(await confirm(ctx, options, pullPlanLines(plan, style), `Write ${plural(pending.length, 'file')}?`))) {
            return { status: 'cancelled', plan, written: [], problems }
        }
        const types = await variableTypes(api, new Map(pending.flatMap((item) => remoteVariableIds(item.endpoint))))
        for (const item of pending) {
            await ctx.runtime.writeFile(item.path, endpointYaml(item.path, item, types))
        }
        return { status: 'written', plan, written: pending.map((item) => shown(item.path)), problems }
    },

    human({ result, out }) {
        const style: Styler = (text, ...styles) => out.style(text, ...styles)
        for (const problem of result.problems) {
            out.line(`${out.style('Skipped', 'yellow', 'bold')} ${problem.path}: ${problem.message}`)
        }
        if (result.status === 'written') {
            result.written.forEach((path) => out.line(`${out.style('Wrote', 'green', 'bold')}  ${path}`))
            out.line(out.style(`${plural(result.written.length, 'file')} written`, 'dim'))
            return
        }
        pullPlanLines(result.plan, style).forEach((line) => out.line(line))
        const messages = {
            preview: 'Dry run: no files written.',
            cancelled: 'Cancelled: no files written.',
            nothing_to_do: 'The local files already match PostHog.',
        }
        out.line(out.style(messages[result.status], 'dim'))
    },

    agent({ result, out }) {
        out.json(result)
    },

    exitCode: (result) => (result.problems.length > 0 ? 1 : 0),

    telemetry: ({ result, options }) => ({
        status: result.status,
        all: options.all === true,
        endpoint_count: result.plan.length,
        written: result.written.length,
    }),
})