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.

5.5 KB
Raw Blame
import { diffLines } from 'diff'

import type { Context } from '@/core/context'
import { EXIT_USAGE, HogError } from '@/core/errors'
import { escapeControls, type Style } from '@/core/output'
import { absolutePath } from '@/core/paths'
import type { Change } from '@/endpoints/changes'
import type { FileProblem } from '@/endpoints/files'
import { SCHEDULE_LABELS, scheduleFor, type Endpoint } from '@/endpoints/model'
import type { VariableChange } from '@/endpoints/plan'

export type Styler = (text: string, ...styles: Style[]) => string

export const SCOPES_READ = ['endpoint:read'] as const
export const SCOPES_WRITE = [
    'endpoint:read',
    'endpoint:write',
    'insight_variable:read',
    'insight_variable:write',
] as const

export const CONFIRM_OPTIONS = {
    dryRun: { type: 'boolean', description: 'Show the changes without making them' },
    yes: { type: 'boolean', short: 'y', description: 'Make the changes without asking. Agents and scripts need it' },
} as const

export function summary(endpoint: Endpoint): Record<string, unknown> {
    return {
        name: endpoint.name,
        description: endpoint.description ?? '',
        active: endpoint.is_active,
        materialized: endpoint.is_materialized,
        schedule: endpoint.is_materialized ? (scheduleFor(endpoint.data_freshness_seconds) ?? null) : null,
        url: endpoint.url ?? null,
        uiUrl: endpoint.ui_url ?? null,
    }
}

export function materializationLabel(endpoint: Endpoint): string {
    if (!endpoint.is_materialized) {
        return 'on demand'
    }
    const schedule = scheduleFor(endpoint.data_freshness_seconds)
    return `materialized, ${schedule ? SCHEDULE_LABELS[schedule] : 'scheduled'}`
}

// The paths a push or diff reads: the arguments, or `endpoints.dir` from posthog.json.
export async function endpointPaths(ctx: Context, paths: readonly string[]): Promise<string[]> {
    if (paths.length > 0) {
        return [...paths]
    }
    const loaded = await ctx.config()
    const dir = loaded?.config.endpoints?.dir
    if (loaded && dir) {
        return [absolutePath(loaded.root, dir)]
    }
    throw new HogError(
        'paths_required',
        'Pass the endpoint files or folders to read.',
        'Or set endpoints.dir in posthog.json to the folder that holds them.',
        EXIT_USAGE
    )
}

// Asks a person before changes happen. Agents and scripts can't answer, so they pass --yes.
export async function confirm(
    ctx: Context,
    options: { yes?: boolean },
    preview: string[],
    question: string
): Promise<boolean> {
    if (options.yes) {
        return true
    }
    if (!ctx.prompts) {
        throw new HogError(
            'confirmation_required',
            'hog needs a confirmation before it makes these changes.',
            'Pass --yes to make them, or --dry-run to only see them.'
        )
    }
    ctx.prompts.note(preview.join('\n'), 'Changes')
    return ctx.prompts.confirm(question)
}

const LABELS: Record<Change['field'], string> = {
    description: 'Description',
    query: 'Query',
    materialization: 'Materialization',
    schedule: 'Schedule',
    variables: 'Variables',
    defaults: 'Defaults',
}

// `from` is the side that changes: PostHog for a push, the file for a pull. Anyone in the project
// can edit the PostHog side, so escape sequences in it must not reach the terminal.
export function changeLines(change: Change, direction: 'push' | 'pull', style: Styler): string[] {
    const [from, to] = direction === 'push' ? [change.remote, change.local] : [change.local, change.remote]
    if (change.field !== 'query') {
        return [`${LABELS[change.field]}: ${escapeControls(from) || '(none)'} → ${escapeControls(to) || '(none)'}`]
    }
    const lines = [`${LABELS.query}:`]
    for (const part of diffLines(from.endsWith('\n') ? from : `${from}\n`, to.endsWith('\n') ? to : `${to}\n`)) {
        const sign = part.added ? '+' : part.removed ? '-' : ' '
        const color: Style = part.added ? 'green' : part.removed ? 'red' : 'dim'
        for (const line of part.value.replace(/\n$/, '').split('\n')) {
            lines.push(style(`  ${sign} ${escapeControls(line)}`, color))
        }
    }
    return lines
}

export function variableLines(changes: VariableChange[], style: Styler): string[] {
    if (changes.length === 0) {
        return []
    }
    return [
        'Variables:',
        ...changes.map((change) => {
            // A name can come from the endpoint in PostHog, which another member can edit.
            const name = escapeControls(change.name)
            if (change.change === 'add') {
                return style(`  + ${name} (${escapeControls(change.type ?? '')})`, 'green')
            }
            if (change.change === 'retype') {
                return style(
                    `  ~ ${name} (${escapeControls(change.from ?? '')} → ${escapeControls(change.type ?? '')})`,
                    'yellow'
                )
            }
            return style(`  - ${name}`, 'red')
        }),
    ]
}

export function actionLabel(action: 'create' | 'update' | 'skip', style: Styler): string {
    const labels = {
        create: style('create', 'green', 'bold'),
        update: style('update', 'yellow', 'bold'),
        skip: style('skip  ', 'dim'),
    }
    return labels[action]
}

export function problemLines(problems: FileProblem[], style: Styler): string[] {
    return problems.map((problem) => `${style('Skipped', 'yellow', 'bold')} ${problem.path}: ${problem.message}`)
}

export function indent(lines: string[], by = '    '): string[] {
    return lines.map((line) => `${by}${line}`)
}