: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(hog): manage endpoints as YAML files with hog endpoints (#125523)
Rafael Audiberte0871caf862b
diff --git a/hog/AGENTS.md b/hog/AGENTS.mdindex 642f6bef1b25..917d31b397db 100644--- a/hog/AGENTS.md+++ b/hog/AGENTS.md@@ -10,6 +10,7 @@| `src/core/` | The shared parts every command uses: command definitions, context and global options, output, agent detection, errors, runtime, the manifest || `src/posthog/` | The PostHog API client and credentials || `src/error-tracking/` | Symbol upload: discovery, artifact types under `kinds/`, the container and content hash, releases, git, the upload protocol, and `run.ts`, the inject and upload steps the commands share |+| `src/endpoints/` | The endpoint YAML files, how they compare with PostHog, and the push and pull plans || `test/parity/` | Goldens recorded from posthog-cli and the tests that hold hog to them. Read its README before changing anything that reaches an upload || `src/cli.ts` | Turns the command tree into a commander program, runs it, and maps errors to exit codes || `src/testing.ts` | `runHog` and a fake runtime, so tests run the real CLI without a process or a network |diff --git a/hog/README.md b/hog/README.mdindex 10965651a85d..2094867cc807 100644--- a/hog/README.md+++ b/hog/README.md@@ -29,6 +29,9 @@ The commands `posthog-cli` keeps under `exp` (`query`, `endpoints`, `logs`, `tas| `hog error-tracking release` | Finds or creates the release for this build. `-o text` prints just its ID. || `hog error-tracking download <id/ref>` | Downloads a symbol set from PostHog and unpacks it. || `hog error-tracking extract <file>` | Unpacks a symbol set file. |+| `hog endpoints list`, `get`, `open` | List your endpoints, show one, or open it in PostHog. |+| `hog endpoints run [name]` | Runs an endpoint, or the query in a local file with `--file`. `--var name=value` sets variables. |+| `hog endpoints pull`, `diff`, `push` | Keep endpoints as YAML files: pull them, see how they differ, and push changes. `diff` exits with code 1 on drift. || `hog schema pull` | Generates a typed SDK (TypeScript, Go or Python) from your event definitions, and records it in `posthog.json`. || `hog schema status` | Checks each generated SDK against PostHog. Exits with code 1 when one is missing or out of date. || `hog config check`, `hog config schema` | Check `posthog.json` against its schema, or print the schema. |@@ -42,7 +45,6 @@ hog replaces posthog-cli once everything below is done.First, the commands that make hog a complete CLI:- [ ] `hog api skill` and `hog api agents-md`, which install PostHog agent skills and the AGENTS.md snippet.-- [ ] `hog endpoints`: `list`, `get`, `open`, `run`, `push`, `pull` and `diff`.Then, once the commands above work:@@ -87,6 +89,7 @@ Point `$schema` at the published schema to get validation in your editor:}```+`endpoints.dir` names the folder of endpoint files, so `hog endpoints pull`, `diff` and `push` work without a path.`hog schema pull` keeps its entries under `languages` in the snake case posthog-cli uses, so either CLI can regenerate an SDK the other set up.posthog-cli rewrites `posthog.json` with only `languages` when it pulls, so it drops the other settings. Restore them from version control after running it.diff --git a/hog/package.json b/hog/package.jsonindex 6ecaaf68a51a..b648e1f550ac 100644--- a/hog/package.json+++ b/hog/package.json@@ -20,7 +20,9 @@"@posthog/mcp": "workspace:*","cli-table3": "0.6.5","commander": "15.0.0",+ "diff": "8.0.4","pako": "2.1.0",+ "yaml": "2.9.0","zod": "^4.3.6"},"devDependencies": {diff --git a/hog/posthog.schema.json b/hog/posthog.schema.jsonindex 0ed10faf91d5..0f279d6e76d1 100644--- a/hog/posthog.schema.json+++ b/hog/posthog.schema.json@@ -65,6 +65,18 @@"additionalProperties": false,"description": "Settings for `hog error-tracking`."},+ "endpoints": {+ "description": "Settings for `hog endpoints`.",+ "type": "object",+ "properties": {+ "dir": {+ "description": "The folder of endpoint YAML files, relative to posthog.json. `hog endpoints pull` writes there, and `push` and `diff` read it when no path is passed.",+ "type": "string",+ "minLength": 1+ }+ },+ "additionalProperties": false+ },"languages": {"description": "The typed SDKs `hog schema pull` generates, by language. posthog-cli reads the same entries.","type": "object",diff --git a/hog/src/cli.test.ts b/hog/src/cli.test.tsindex 30184bc753b7..d9db0b1c97ae 100644--- a/hog/src/cli.test.ts+++ b/hog/src/cli.test.ts@@ -46,8 +46,8 @@ describe('hog', () => {],['an --output that the legacy command owns',- ['endpoints', 'pull', 'example', '--output', './queries'],- 'posthog-cli exp endpoints pull example --output ./queries',+ ['logs', 'import', '--output', './logs'],+ 'posthog-cli exp logs import --output ./logs',],])('%s points to posthog-cli', async (_name, argv, invocation) => {const result = await runHog(argv)@@ -115,6 +115,13 @@ describe('hog', () => {'error-tracking release','error-tracking download','error-tracking extract',+ 'endpoints list',+ 'endpoints get',+ 'endpoints open',+ 'endpoints run',+ 'endpoints push',+ 'endpoints pull',+ 'endpoints diff','schema pull','schema status','config check',diff --git a/hog/src/cli.ts b/hog/src/cli.tsindex a2e4e06b1278..4a50d70ea274 100644--- a/hog/src/cli.ts+++ b/hog/src/cli.ts@@ -28,6 +28,9 @@ const LEGACY_HELP_GROUP = 'Not ported yet (each one prints the posthog-cli commafunction toOption(name: string, spec: OptionSpec): Option {const option = new Option(optionFlags(name, spec), spec.description)+ if (spec.type === 'string' && spec.multiple) {+ option.argParser((value: string, previous: string[] | undefined) => [...(previous ?? []), value])+ }return spec.type === 'string' && spec.choices ? option.choices(spec.choices) : option}diff --git a/hog/src/commands/endpoints/diff.ts b/hog/src/commands/endpoints/diff.tsnew file mode 100644index 000000000000..a494c0a2fa3d--- /dev/null+++ b/hog/src/commands/endpoints/diff.ts@@ -0,0 +1,56 @@+import { defineCommand } from '@/core/command'+import { listEndpoints } from '@/endpoints/api'+import { readEndpointFiles } from '@/endpoints/files'+import { planPush } from '@/endpoints/plan'++import { pushPlanLines } from './push'+import { endpointPaths, problemLines, SCOPES_READ, type Styler } from './shared'++const inSync = (item: { action: string; reason?: string }): boolean =>+ item.action === 'skip' && item.reason === 'No changes'++export default defineCommand({+ description: 'Show how local endpoint files differ from PostHog',+ args: {+ paths: {+ description: 'Endpoint files, folders of them, or glob patterns. Defaults to endpoints.dir in posthog.json',+ variadic: true,+ optional: true,+ },+ },+ options: {+ verbose: { type: 'boolean', description: 'List the endpoints that match PostHog too' },+ },+ scopes: SCOPES_READ,+ notes: 'Exits with code 1 when a file differs from PostHog or is invalid, like `git diff --exit-code`, so CI can catch drift. `hog endpoints push` applies the changes.',+ examples: ['hog endpoints diff endpoints/', 'hog endpoints diff'],++ async run({ args, ctx }) {+ const { endpoints, problems } = await readEndpointFiles(ctx.runtime, await endpointPaths(ctx, args.paths))+ const remotes = endpoints.length > 0 ? await listEndpoints(await ctx.posthog()) : []+ // Variable types live on the project, so a diff only compares which variables each query uses.+ const plan = planPush(endpoints, remotes, []).map(({ file: _file, ...item }) => item)+ return { plan, problems }+ },++ human({ result, out, options }) {+ const style: Styler = (text, ...styles) => out.style(text, ...styles)+ problemLines(result.problems, style).forEach((line) => out.line(line))+ const shown = options.verbose ? result.plan : result.plan.filter((item) => !inSync(item))+ pushPlanLines(shown, style).forEach((line) => out.line(line))+ const count = (test: (item: (typeof result.plan)[number]) => boolean): number => result.plan.filter(test).length+ const parts = [+ `${count((item) => item.action === 'create')} new`,+ `${count((item) => item.action === 'update')} changed`,+ `${count(inSync)} unchanged`,+ `${count((item) => item.action === 'skip' && !inSync(item)) + result.problems.length} invalid`,+ ]+ out.line(out.style(parts.join(', '), 'dim'))+ },++ agent({ result, out }) {+ out.json(result)+ },++ exitCode: (result) => (result.problems.length > 0 || !result.plan.every(inSync) ? 1 : 0),+})diff --git a/hog/src/commands/endpoints/endpoints.test.ts b/hog/src/commands/endpoints/endpoints.test.tsnew file mode 100644index 000000000000..e24a49a5f3a4--- /dev/null+++ b/hog/src/commands/endpoints/endpoints.test.ts@@ -0,0 +1,358 @@+import { describe, expect, test } from 'bun:test'++import { runHog, TEST_CREDENTIALS } from '@/testing'++import { pushPlanLines } from './push'++const AGENT = { ...TEST_CREDENTIALS, CLAUDECODE: '1' }+const BASE = 'https://ph.example.com/api/environments/7/'++const endpoint = (+ name: string,+ query: Record<string, unknown>,+ extra: Record<string, unknown> = {}+): Record<string, unknown> => ({+ id: `id-${name}`,+ name,+ description: '',+ query,+ is_active: true,+ is_materialized: false,+ created_at: '2026-01-01T00:00:00Z',+ updated_at: '2026-01-01T00:00:00Z',+ ui_url: `https://ph.example.com/project/7/endpoints/${name}`,+ ...extra,+})++// A trends endpoint as PostHog returns it: nulls for unset fields, variables keyed by ID, and a+// refresh interval kept after materialization was turned off.+const TRENDS = endpoint(+ 'weekly',+ {+ kind: 'TrendsQuery',+ interval: 'week',+ series: [{ kind: 'EventsNode', event: 'signed_up', math: null }],+ tags: null,+ },+ { data_freshness_seconds: 86400, description: 'Weekly signups' }+)+const HOGQL = endpoint('by-type', {+ kind: 'HogQLQuery',+ query: 'SELECT count()\r\nFROM events\r\nWHERE event = {variables.event_type}',+ variables: { 'var-1': { variableId: 'var-1', code_name: 'event_type', value: '$pageview' } },+})+const VARIABLES = [{ id: 'var-1', name: 'event_type', code_name: 'event_type', type: 'String' }]++function server(endpoints: unknown[], extra: (url: string, body: unknown) => unknown = () => undefined) {+ return (url: string, body: unknown) => {+ const reply = extra(url, body)+ if (reply) {+ return reply as { status: number; body: unknown }+ }+ if (url === `${BASE}endpoints/`) {+ return { status: 200, body: { results: endpoints } }+ }+ if (url === `${BASE}insight_variables/`) {+ return { status: 200, body: { results: VARIABLES } }+ }+ return { status: 404, body: { detail: 'Not found.' } }+ }+}++const PULLED_WEEKLY =+ 'name: weekly\ndescription: Weekly signups\nquery_definition:\n kind: TrendsQuery\n interval: week\n series:\n - kind: EventsNode\n event: signed_up\n'++const PULLED_BY_TYPE = `# by-type.yaml+name: by-type+query: |-+ SELECT count()+ FROM events+ WHERE event = {variables.event_type}+variables:+ - name: event_type+ type: String+ default: $pageview+`++describe('hog endpoints', () => {+ test('list follows pages until PostHog has no more', async () => {+ const result = await runHog(['endpoints', 'list'], {+ env: AGENT,+ respond: (url) =>+ url === `${BASE}endpoints/`+ ? { status: 200, body: { results: [TRENDS], next: `${BASE}endpoints/?offset=1` } }+ : { status: 200, body: { results: [HOGQL], next: null } },+ })+ expect(+ result.stdout+ .trim()+ .split('\n')+ .map((line) => JSON.parse(line).name)+ ).toEqual(['weekly', 'by-type'])+ })++ test('pull writes short files with the project variable types, and updates a file in place', async () => {+ const result = await runHog(['endpoints', 'pull', '--all', '--yes'], {+ env: AGENT,+ files: {+ '/work/posthog.json': JSON.stringify({ endpoints: { dir: 'endpoints' } }),+ '/work/endpoints/signups.yaml': 'name: weekly\nquery_definition:\n kind: TrendsQuery\n',+ },+ respond: server([TRENDS, HOGQL]),+ })+ expect(result.exitCode).toBe(0)+ expect(result.files['/work/endpoints/by-type.yaml']).toBe(PULLED_BY_TYPE)+ expect(result.files['/work/endpoints/signups.yaml']).toBe(`# signups.yaml\n${PULLED_WEEKLY}`)+ expect(result.files['/work/endpoints/weekly.yaml']).toBeUndefined()+ })++ test('pull takes variable types from the values when the key cannot read project variables', async () => {+ const result = await runHog(['endpoints', 'pull', 'by-type', '--yes'], {+ env: AGENT,+ respond: server([HOGQL], (url) =>+ url === `${BASE}insight_variables/` ? { status: 403, body: { detail: 'Forbidden' } } : undefined+ ),+ })++ expect(result.exitCode).toBe(0)+ expect(result.files['/work/by-type.yaml']).toBe(PULLED_BY_TYPE.replace('type: String', 'type: string'))+ })++ test.each([+ [+ 'a file that defines another endpoint',+ { '/work/weekly.yaml': 'name: by-type\nquery: SELECT 1\n' },+ { '/work/weekly.yaml': PULLED_BY_TYPE.replace('# by-type.yaml', '# weekly.yaml') },+ ],+ [+ 'a file hog cannot read',+ { '/work/weekly.yaml': 'name: weekly\nquery: [unclosed\n' },+ { '/work/weekly.yaml': 'name: weekly\nquery: [unclosed\n' },+ ],+ ])('pull never overwrites %s with another endpoint', async (_name, files, expected) => {+ const result = await runHog(['endpoints', 'pull', '--all', '--yes'], {+ env: AGENT,+ files,+ respond: server([TRENDS, HOGQL]),+ })+ expect(result.exitCode).toBe(1)+ expect(result.files).toMatchObject(expected)+ expect(result.json().problems).toEqual([expect.objectContaining({ path: 'weekly.yaml' })])+ })++ test.each([+ ['files that match PostHog', { 'by-type.yaml': PULLED_BY_TYPE }, 0, []],+ [+ 'a changed query',+ { 'by-type.yaml': PULLED_BY_TYPE.replace('count()', 'count(*)') },+ 1,+ [{ name: 'by-type', action: 'update', fields: ['query'] }],+ ],+ [+ // The file posthog-cli writes, with the lowercase type it infers from the default.+ 'a posthog-cli file',+ { 'by-type.yaml': PULLED_BY_TYPE.replace('type: String', 'type: string') },+ 0,+ [],+ ],+ [+ // PostHog keeps the refresh interval of an endpoint that is no longer materialized.+ 'materialization turned off on both sides',+ { 'weekly.yaml': `${PULLED_WEEKLY}materialization:\n enabled: false\n schedule: 1hour\n` },+ 0,+ [],+ ],+ [+ 'a changed default',+ { 'by-type.yaml': PULLED_BY_TYPE.replace('default: $pageview', 'default: $autocapture') },+ 1,+ [{ name: 'by-type', action: 'update', fields: ['defaults'] }],+ ],+ ['a file with a typo', { 'by-type.yaml': `${PULLED_BY_TYPE}descripton: oops\n` }, 1, []],+ ])('diff with %s', async (_name, files, exitCode, changed) => {+ const result = await runHog(['endpoints', 'diff'], {+ env: AGENT,+ files: {+ '/work/posthog.json': JSON.stringify({ endpoints: { dir: 'endpoints' } }),+ ...Object.fromEntries(Object.entries(files).map(([name, text]) => [`/work/endpoints/${name}`, text])),+ },+ respond: server([TRENDS, HOGQL]),+ })+ expect(result.exitCode).toBe(exitCode)+ const plan = result.json().plan as { name: string; action: string; changes: { field: string }[] }[]+ expect(+ plan+ .filter((item) => item.action !== 'skip')+ .map((item) => ({ name: item.name, action: item.action, fields: item.changes.map((c) => c.field) }))+ ).toEqual(changed)+ })++ test('pull escapes terminal control characters in the PostHog side of a preview', async () => {+ const edited = { ...TRENDS, description: '\u001b]52;c;eA==\u0007Weekly signups' }++ const result = await runHog(['endpoints', 'pull', 'weekly', '--dry-run'], {+ stdoutIsTTY: true,+ env: { ...TEST_CREDENTIALS, NO_COLOR: '1' },+ files: { '/work/weekly.yaml': PULLED_WEEKLY },+ respond: server([edited]),+ })++ expect(result.stdout).toContain('\\x1b]52;c;eA==\\x07Weekly signups')+ expect(result.stdout).not.toContain('\u001b')+ })++ test('push previews escape variable names and rejection reasons from PostHog', () => {+ const name = '\u001b]52;c;eA==\u0007x'+ const item = {+ name: 'weekly',+ path: 'weekly.yaml',+ action: 'skip' as const,+ reason: `${name} is used by the query`,+ changes: [],+ variables: [+ { name, change: 'remove' as const },+ { name, change: 'retype' as const, type: 'String', from: 'Number' },+ ],+ }++ const lines = pushPlanLines([item], (text) => text).join('\n')++ expect(lines).toContain('\\x1b]52;c;eA==\\x07x')+ expect(lines).not.toContain('\u001b')+ })++ test('push asks agents for --yes before it changes anything', async () => {+ const result = await runHog(['endpoints', 'push', 'new.yaml'], {+ env: AGENT,+ files: { '/work/new.yaml': 'name: new\nquery: SELECT 1\n' },+ respond: server([]),+ })+ expect(result.error().code).toBe('confirmation_required')+ expect(result.requests.filter((request) => request.method !== 'GET')).toEqual([])+ })++ test('push creates the variables a file needs, then the endpoint, and skips files PostHog would reject', async () => {+ const result = await runHog(['endpoints', 'push', 'endpoints', '--yes'], {+ env: AGENT,+ files: {+ '/work/endpoints/a.yaml': [+ 'name: by-country',+ 'query: SELECT count() FROM events WHERE properties.$geoip_country_code = {variables.country} AND properties.region IN {variables.regions}',+ 'variables:',+ ' - name: country',+ // posthog-cli writes lowercase types, and PostHog only accepts its own names.+ ' type: string',+ ' default: US',+ ' - name: regions',+ ' type: array',+ ' default: [eu, us]',+ 'materialization:',+ ' enabled: true',+ ' schedule: 1hour',+ ].join('\n'),+ '/work/endpoints/b.yaml':+ 'name: unused\nquery: SELECT 1\nvariables:\n - name: extra\n type: String\n',+ },+ respond: server([], (url, body) =>+ url === `${BASE}insight_variables/` && body+ ? {+ status: 201,+ body:+ (body as { code_name: string }).code_name === 'country'+ ? { id: 'var-2', name: 'country', code_name: 'country', type: 'String' }+ : {+ id: 'var-3',+ name: 'regions',+ code_name: 'regions',+ type: 'List',+ is_multi: true,+ },+ }+ : url === `${BASE}endpoints/` && body+ ? { status: 201, body: { ...endpoint('by-country', {}), ui_url: 'https://ph.example.com/e' } }+ : undefined+ ),+ })+ expect(result.exitCode).toBe(1)+ expect(result.requests.filter((request) => request.method === 'POST').map((request) => request.body)).toEqual([+ { name: 'country', code_name: 'country', type: 'String', default_value: 'US' },+ // An array default makes a multiple-selection list, or PostHog keeps only its first value.+ { name: 'regions', code_name: 'regions', type: 'List', default_value: ['eu', 'us'], is_multi: true },+ {+ name: 'by-country',+ description: '',+ query: {+ kind: 'HogQLQuery',+ query: 'SELECT count() FROM events WHERE properties.$geoip_country_code = {variables.country} AND properties.region IN {variables.regions}',+ variables: {+ 'var-2': { variableId: 'var-2', code_name: 'country', value: 'US' },+ 'var-3': { variableId: 'var-3', code_name: 'regions', value: ['eu', 'us'] },+ },+ },+ is_materialized: true,+ data_freshness_seconds: 3600,+ },+ ])+ expect(result.json()).toMatchObject({+ outcomes: [{ name: 'by-country', status: 'created' }],+ plan: [{}, { name: 'unused', action: 'skip', invalid: true, reason: expect.stringContaining('extra') }],+ })+ })++ test.each([+ ['neither a name nor --file', ['endpoints', 'run'], 'usage_error'],+ ['a name and --file', ['endpoints', 'run', 'x', '--file', 'x.yaml'], 'usage_error'],+ ['a variable without a value', ['endpoints', 'run', 'x', '--var', 'country'], 'invalid_variable'],+ ])('run refuses %s', async (_name, argv, code) => {+ const result = await runHog(argv, { env: AGENT })+ expect(result.exitCode).toBe(2)+ expect(result.error().code).toBe(code)+ })++ test('run passes every --var to the endpoint', async () => {+ const result = await runHog(['endpoints', 'run', 'by-type', '--var', 'a=1', '--var', 'b=x=y'], {+ env: AGENT,+ respond: () => ({ status: 200, body: { columns: ['total'], results: [[3]] } }),+ })+ expect(result.requests[0]).toMatchObject({+ url: `${BASE}endpoints/by-type/run/`,+ body: { variables: { a: '1', b: 'x=y' } },+ })+ expect(result.stdout).toBe('[3]\n')+ })++ test('run --file puts variables in the query with their project IDs, and falls back to the file defaults', async () => {+ const result = await runHog(['endpoints', 'run', '--file', 'by-type.yaml', '--var', 'limit=5'], {+ env: AGENT,+ files: {+ '/work/by-type.yaml': `${PULLED_BY_TYPE.replace('count()', 'count() LIMIT {variables.limit}')} - name: limit\n type: Number\n`,+ },+ respond: server([], (url) =>+ url === `${BASE}insight_variables/`+ ? {+ status: 200,+ body: {+ results: [+ ...VARIABLES,+ { id: 'var-9', name: 'limit', code_name: 'limit', type: 'Number' },+ ],+ },+ }+ : url === `${BASE}query/`+ ? { status: 200, body: { columns: ['n'], results: [[1]] } }+ : undefined+ ),+ })+ expect(result.exitCode).toBe(0)+ expect(result.requests.at(-1)!.body).toMatchObject({+ query: {+ kind: 'HogQLQuery',+ variables: {+ 'var-1': { variableId: 'var-1', code_name: 'event_type', value: '$pageview' },+ 'var-9': { variableId: 'var-9', code_name: 'limit', value: '5' },+ },+ },+ })+ expect(result.requests.at(-1)!.body).not.toHaveProperty('variables')+ })+})diff --git a/hog/src/commands/endpoints/get.ts b/hog/src/commands/endpoints/get.tsnew file mode 100644index 000000000000..4f67509efe19--- /dev/null+++ b/hog/src/commands/endpoints/get.ts@@ -0,0 +1,59 @@+import { defineCommand } from '@/core/command'+import { escapeControls } from '@/core/output'+import { getEndpoint } from '@/endpoints/api'++import { materializationLabel, SCOPES_READ } from './shared'++export default defineCommand({+ description: 'Show an endpoint: its URLs, query, versions and materialization',+ args: { name: { description: 'The endpoint name' } },+ scopes: SCOPES_READ,+ examples: ['hog endpoints get daily-signups'],++ async run({ args, ctx }) {+ return getEndpoint(await ctx.posthog(), args.name)+ },++ human({ result: endpoint, out }) {+ const field = (label: string, value: string): void =>+ out.line(` ${out.style(label.padEnd(12), 'bold')}${value}`)+ // Anyone in the project can edit this text, so escape sequences in it must not reach the terminal.+ const text = escapeControls+ if (endpoint.ui_url) {+ field('View', out.style(text(endpoint.ui_url), 'cyan'))+ }+ if (endpoint.url) {+ field('Run', out.style(text(endpoint.url), 'cyan'))+ }+ field('Name', text(endpoint.name))+ field('Status', endpoint.is_active ? out.style('active', 'green') : out.style('inactive', 'red'))+ if (endpoint.description) {+ field('Description', text(endpoint.description))+ }+ field('Version', `${endpoint.current_version ?? 1} (${endpoint.versions_count ?? 1} total)`)+ field('Refresh', materializationLabel(endpoint))+ const materialization = endpoint.materialization+ if (endpoint.is_materialized && materialization) {+ if (materialization.status) {+ field('Last run', text(materialization.status.toLowerCase()))+ }+ if (materialization.last_materialized_at) {+ field('Last done', text(materialization.last_materialized_at))+ }+ if (materialization.error) {+ field('Error', out.style(text(materialization.error), 'red'))+ }+ } else if (materialization && materialization.can_materialize === false && materialization.reason) {+ field('', out.style(text(materialization.reason), 'dim'))+ }+ field('Created', text(endpoint.created_at))+ field('Updated', text(endpoint.updated_at))+ out.line()+ out.line(` ${out.style('Query', 'bold')}`)+ const query =+ typeof endpoint.query.query === 'string' ? endpoint.query.query : JSON.stringify(endpoint.query, null, 2)+ for (const line of query.split('\n')) {+ out.line(` ${out.style(text(line), 'dim')}`)+ }+ },+})diff --git a/hog/src/commands/endpoints/index.ts b/hog/src/commands/endpoints/index.tsnew file mode 100644index 000000000000..824097c677eb--- /dev/null+++ b/hog/src/commands/endpoints/index.ts@@ -0,0 +1,14 @@+import { defineGroup } from '@/core/command'++import diff from './diff'+import get from './get'+import list from './list'+import open from './open'+import pull from './pull'+import push from './push'+import run from './run'++export default defineGroup({+ description: 'Manage PostHog endpoints as YAML files: pull, diff, push and run them',+ commands: { list, get, open, run, push, pull, diff },+})diff --git a/hog/src/commands/endpoints/list.ts b/hog/src/commands/endpoints/list.tsnew file mode 100644index 000000000000..4fd30514e13b--- /dev/null+++ b/hog/src/commands/endpoints/list.ts@@ -0,0 +1,38 @@+import { defineCommand } from '@/core/command'+import { plural } from '@/core/text'+import { listEndpoints } from '@/endpoints/api'++import { materializationLabel, SCOPES_READ, summary } from './shared'++export default defineCommand({+ description: 'List the endpoints in your project',+ scopes: SCOPES_READ,+ examples: ['hog endpoints list'],++ async run({ ctx }) {+ const api = await ctx.posthog()+ return { projectId: (await ctx.credentials()).projectId, endpoints: await listEndpoints(api) }+ },++ human({ result, out }) {+ if (result.endpoints.length === 0) {+ out.line(`No endpoints in project ${result.projectId} yet.`)+ out.line(`Create one from a YAML file with ${out.style('hog endpoints push my-endpoint.yaml', 'bold')}.`)+ return+ }+ out.table(+ ['name', 'refresh', 'active', 'description'],+ result.endpoints.map((endpoint) => [+ endpoint.name,+ materializationLabel(endpoint),+ endpoint.is_active,+ endpoint.description ?? '',+ ])+ )+ out.line(out.style(`${plural(result.endpoints.length, 'endpoint')} in project ${result.projectId}`, 'dim'))+ },++ agent({ result, out }) {+ out.jsonLines(result.endpoints.map(summary))+ },+})diff --git a/hog/src/commands/endpoints/open.ts b/hog/src/commands/endpoints/open.tsnew file mode 100644index 000000000000..e871451dd5ca--- /dev/null+++ b/hog/src/commands/endpoints/open.ts@@ -0,0 +1,26 @@+import { defineCommand } from '@/core/command'+import { HogError } from '@/core/errors'+import { getEndpoint } from '@/endpoints/api'++import { SCOPES_READ } from './shared'++export default defineCommand({+ description: 'Open an endpoint in PostHog in your browser',+ args: { name: { description: 'The endpoint name' } },+ scopes: SCOPES_READ,+ notes: 'Agents get the link instead of a browser window.',+ examples: ['hog endpoints open daily-signups'],++ async run({ args, ctx }) {+ const endpoint = await getEndpoint(await ctx.posthog(), args.name)+ if (!endpoint.ui_url) {+ throw new HogError('no_ui_url', `PostHog didn't return a link for ${args.name}.`)+ }+ const opened = ctx.mode.agent === undefined && (await ctx.runtime.openUrl(endpoint.ui_url))+ return { name: endpoint.name, url: endpoint.ui_url, opened }+ },++ human({ result, out }) {+ out.line(result.opened ? `Opened ${result.url}` : `Open ${result.url}`)+ },+})diff --git a/hog/src/commands/endpoints/pull.ts b/hog/src/commands/endpoints/pull.tsnew file mode 100644index 000000000000..b4ae8f37b16d--- /dev/null+++ b/hog/src/commands/endpoints/pull.ts@@ -0,0 +1,199 @@+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 { listEndpoints, listInsightVariables } from '@/endpoints/api'+import { readEndpointFiles, type FileProblem } from '@/endpoints/files'+import { fileFromEndpoint, remoteVariableNames } 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.+async function variableTypes(api: PostHogApi): Promise<Map<string, string>> {+ try {+ return new Map((await listInsightVariables(api)).map((variable) => [variable.code_name, variable.type]))+ } catch (error) {+ if (error instanceof ApiError && error.status === 403) {+ return new Map()+ }+ 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 remotes = await listEndpoints(await ctx.posthog())+ const problems: FileProblem[] = []+ let selected = remotes+ if (!options.all) {+ const known = new Set(remotes.map((endpoint) => endpoint.name))+ const missing = args.names.filter((name) => !known.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 = remotes.filter((endpoint) => args.names.includes(endpoint.name))+ }+ 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 = pending.some((item) => remoteVariableNames(item.endpoint).length > 0)+ ? await variableTypes(await ctx.posthog())+ : new Map<string, string>()+ 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),+})diff --git a/hog/src/commands/endpoints/push.ts b/hog/src/commands/endpoints/push.tsnew file mode 100644index 000000000000..7c5982913e2c--- /dev/null+++ b/hog/src/commands/endpoints/push.ts@@ -0,0 +1,130 @@+import { defineCommand } from '@/core/command'+import { escapeControls, Output } from '@/core/output'+import { plural } from '@/core/text'+import { listEndpoints, listInsightVariables } from '@/endpoints/api'+import { readEndpointFiles, type FileProblem } from '@/endpoints/files'+import type { InsightVariable } from '@/endpoints/model'+import { applyPush, planPush, type PushItem, type PushOutcome } from '@/endpoints/plan'++import {+ actionLabel,+ changeLines,+ CONFIRM_OPTIONS,+ confirm,+ endpointPaths,+ indent,+ problemLines,+ SCOPES_WRITE,+ variableLines,+ type Styler,+} from './shared'++type PlannedItem = Omit<PushItem, 'file'>++interface PushResult {+ status: 'applied' | 'preview' | 'cancelled' | 'nothing_to_do'+ plan: PlannedItem[]+ outcomes: PushOutcome[]+ problems: FileProblem[]+}++export function pushPlanLines(plan: PlannedItem[], style: Styler): string[] {+ return plan.flatMap((item) => [+ `${actionLabel(item.action, style)} ${style(item.name, 'bold')} ${style(item.path, 'dim')}`,+ ...indent(+ item.reason && item.action === 'skip' && item.reason !== 'No changes'+ ? [style(escapeControls(item.reason), 'yellow')]+ : []+ ),+ ...indent(item.changes.flatMap((change) => changeLines(change, 'push', style))),+ ...indent(variableLines(item.variables, style)),+ ])+}++export default defineCommand({+ description: 'Create or update PostHog endpoints from local YAML files',+ args: {+ paths: {+ description: 'Endpoint files, folders of them, or glob patterns. Defaults to endpoints.dir in posthog.json',+ variadic: true,+ optional: true,+ },+ },+ options: CONFIRM_OPTIONS,+ scopes: SCOPES_WRITE,+ notes: 'hog shows the changes and asks before it makes them. Agents and scripts pass --yes. hog creates the insight variables a file uses that the project lacks. Exits with code 1 when a file is invalid, PostHog would reject it, or an endpoint fails to save.',+ examples: [+ 'hog endpoints push endpoints/',+ 'hog endpoints push daily-signups.yaml --dry-run',+ 'hog endpoints push --yes',+ ],++ async run({ args, options, ctx }): Promise<PushResult> {+ const { endpoints, problems } = await readEndpointFiles(ctx.runtime, await endpointPaths(ctx, args.paths))+ if (endpoints.length === 0) {+ return { status: 'nothing_to_do', plan: [], outcomes: [], problems }+ }+ const api = await ctx.posthog()+ const usesVariables = endpoints.some((local) => (local.file.variables ?? []).length > 0)+ const [remotes, variables] = await Promise.all([+ listEndpoints(api),+ usesVariables ? listInsightVariables(api) : Promise.resolve([] as InsightVariable[]),+ ])+ const items = planPush(endpoints, remotes, variables)+ const plan = items.map(({ file: _file, ...item }) => item)+ const pending = plan.filter((item) => item.action !== 'skip')+ if (pending.length === 0) {+ return { status: 'nothing_to_do', plan, outcomes: [], problems }+ }+ if (options.dryRun) {+ return { status: 'preview', plan, outcomes: [], problems }+ }+ const style = (text: string, ...styles: Parameters<Styler>[1][]): string =>+ new Output(ctx.runtime, ctx.mode).style(text, ...styles)+ const question = `Push ${plural(pending.length, 'endpoint')} to PostHog?`+ if (!(await confirm(ctx, options, pushPlanLines(pending, style), question))) {+ return { status: 'cancelled', plan, outcomes: [], problems }+ }+ return { status: 'applied', plan, outcomes: await applyPush(api, items, variables), problems }+ },++ human({ result, out }) {+ const style: Styler = (text, ...styles) => out.style(text, ...styles)+ problemLines(result.problems, style).forEach((line) => out.line(line))+ if (result.status === 'applied') {+ for (const outcome of result.outcomes) {+ if (outcome.status === 'failed') {+ out.line(+ `${out.style('Failed', 'red', 'bold')} ${outcome.name}: ${escapeControls(outcome.error ?? '')}`+ )+ } else {+ const verb = outcome.status === 'created' ? 'Created' : 'Updated'+ out.line(+ `${out.style(verb, 'green', 'bold')} ${outcome.name} ${out.style(outcome.uiUrl ?? '', 'dim')}`+ )+ }+ }+ const saved = result.outcomes.filter((outcome) => outcome.status !== 'failed').length+ out.line(out.style(`${plural(saved, 'endpoint')} pushed`, 'dim'))+ return+ }+ pushPlanLines(result.plan, style).forEach((line) => out.line(line))+ const messages = {+ preview: 'Dry run: nothing changed in PostHog.',+ cancelled: 'Cancelled: nothing changed in PostHog.',+ nothing_to_do: 'Nothing to push.',+ }+ out.line(out.style(messages[result.status], 'dim'))+ },++ agent({ result, out }) {+ out.json(result)+ },++ exitCode: (result) =>+ result.problems.length > 0 ||+ result.plan.some((item) => item.invalid) ||+ result.outcomes.some((outcome) => outcome.status === 'failed')+ ? 1+ : 0,+})diff --git a/hog/src/commands/endpoints/run.ts b/hog/src/commands/endpoints/run.tsnew file mode 100644index 000000000000..b2fe3b1e6bb6--- /dev/null+++ b/hog/src/commands/endpoints/run.ts@@ -0,0 +1,145 @@+import { defineCommand } from '@/core/command'+import { EXIT_USAGE, HogError } from '@/core/errors'+import { plural } from '@/core/text'+import { listInsightVariables } from '@/endpoints/api'+import { readEndpointFiles } from '@/endpoints/files'+import { ApiError, type PostHogApi } from '@/posthog/api'++interface RunResponse {+ columns?: string[] | null+ results?: unknown[] | null+ hasMore?: boolean | null+}++// HogQL finds a variable by its project ID, so a file's variables must exist in the project. A+// value left out uses the variable's default.+async function queryVariables(api: PostHogApi, values: Map<string, unknown>): Promise<Record<string, unknown>> {+ const known = new Map((await listInsightVariables(api)).map((variable) => [variable.code_name, variable]))+ const missing = [...values.keys()].filter((name) => !known.has(name))+ if (missing.length > 0) {+ throw new HogError(+ 'unknown_variable',+ `The project has no variable named ${missing.join(', ')}.`,+ '`hog endpoints push` creates the variables a file defines.'+ )+ }+ return Object.fromEntries(+ [...values].map(([name, value]) => {+ const { id } = known.get(name)!+ const entry = { variableId: id, code_name: name, ...(value === undefined ? {} : { value }) }+ // Without `isNull`, PostHog replaces a null value with the project's default.+ return [id, value === null ? { ...entry, isNull: true } : entry]+ })+ )+}++function parseVariables(pairs: readonly string[]): Record<string, string> {+ return Object.fromEntries(+ pairs.map((pair) => {+ const separator = pair.indexOf('=')+ if (separator <= 0) {+ throw new HogError(+ 'invalid_variable',+ `--var ${pair} isn't name=value.`,+ 'Pass each variable as --var name=value.',+ EXIT_USAGE+ )+ }+ return [pair.slice(0, separator), pair.slice(separator + 1)]+ })+ )+}++export default defineCommand({+ description: 'Run an endpoint, or the query in a local endpoint file, and print the results',+ args: { name: { description: 'The endpoint to run', optional: true } },+ options: {+ file: {+ type: 'string',+ short: 'f',+ placeholder: 'path',+ description: 'Run the query in this endpoint file without creating the endpoint',+ },+ var: {+ type: 'string',+ short: 'v',+ placeholder: 'name=value',+ multiple: true,+ description: 'A variable value for the query. Repeat it for each variable',+ },+ },+ scopes: ['endpoint:read', 'query:read', 'insight_variable:read'],+ notes: 'Prints a table in a terminal, and one JSON array per row for agents and pipes. --raw prints the full response.',+ examples: [+ 'hog endpoints run daily-signups',+ 'hog endpoints run events-by-type --var event_type=$pageview',+ 'hog endpoints run --file endpoints/daily-signups.yaml',+ ],++ async run({ args, options, ctx }): Promise<RunResponse> {+ if ((args.name === undefined) === (options.file === undefined)) {+ throw new HogError(+ 'usage_error',+ 'Pass an endpoint name or --file, but not both.',+ 'Run `hog endpoints list` to see the endpoint names.',+ EXIT_USAGE+ )+ }+ const variables = parseVariables(options.var ?? [])+ const withVariables = Object.keys(variables).length > 0 ? { variables } : {}+ const api = await ctx.posthog()++ if (options.file !== undefined) {+ const { endpoints, problems } = await readEndpointFiles(ctx.runtime, [options.file])+ const [local] = endpoints+ if (!local) {+ const [problem] = problems+ throw new HogError(+ 'invalid_endpoint_file',+ `${problem?.path ?? options.file}: ${problem?.message ?? 'not an endpoint file'}`+ )+ }+ const query: Record<string, unknown> = local.file.query_definition ?? {+ kind: 'HogQLQuery',+ query: local.file.query,+ }+ const values = new Map<string, unknown>()+ for (const variable of local.file.variables ?? []) {+ values.set(variable.name, variable.default)+ }+ for (const [name, value] of Object.entries(variables)) {+ values.set(name, value)+ }+ if (values.size > 0) {+ query.variables = await queryVariables(api, values)+ }+ return api.post<RunResponse>('query/', { query, name: 'endpoints_cli', refresh: 'blocking' })+ }++ try {+ return await api.post<RunResponse>(`endpoints/${encodeURIComponent(args.name!)}/run/`, withVariables)+ } catch (error) {+ if (error instanceof ApiError && error.status === 404) {+ throw error.withHint(+ `Check that ${args.name} is in \`hog endpoints list\` and active. Inactive endpoints don't run.`+ )+ }+ throw error+ }+ },++ human({ result, out }) {+ const rows = (result.results ?? []) as unknown[][]+ if (result.columns && rows.every(Array.isArray)) {+ out.table(result.columns, rows)+ const count = plural(rows.length, 'row')+ out.line(out.style(result.hasMore ? `${count}, more available` : count, 'dim'))+ return+ }+ out.json(result.results ?? result)+ },++ agent({ result, out }) {+ out.jsonLines(result.results ?? [])+ },+})diff --git a/hog/src/commands/endpoints/shared.ts b/hog/src/commands/endpoints/shared.tsnew file mode 100644index 000000000000..fcf8e0af0c08--- /dev/null+++ b/hog/src/commands/endpoints/shared.ts@@ -0,0 +1,151 @@+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}`)+}diff --git a/hog/src/commands/index.ts b/hog/src/commands/index.tsindex 72a8155c179b..daf260593667 100644--- a/hog/src/commands/index.ts+++ b/hog/src/commands/index.ts@@ -4,6 +4,7 @@ import api from './api'import auth from './auth'import commands from './commands'import config from './config'+import endpoints from './endpoints'import errorTracking from './error-tracking'import { LEGACY_COMMANDS } from './legacy'import query from './query'@@ -14,6 +15,7 @@ export const COMMANDS: CommandTree = {query,api,'error-tracking': errorTracking,+ endpoints,schema,config,commands,diff --git a/hog/src/commands/legacy.ts b/hog/src/commands/legacy.tsindex 3af0e3e1ede0..8393383729b6 100644--- a/hog/src/commands/legacy.ts+++ b/hog/src/commands/legacy.ts@@ -1,7 +1,6 @@import { defineLegacy, type CommandTree } from '@/core/command'export const LEGACY_COMMANDS: CommandTree = {- endpoints: defineLegacy({ description: 'Manage PostHog endpoints', use: 'posthog-cli exp endpoints' }),logs: defineLegacy({description: 'Import historical logs from another log store into PostHog',use: 'posthog-cli exp logs',diff --git a/hog/src/commands/schema/pull.ts b/hog/src/commands/schema/pull.tsindex 3606d7bb44ba..253819dbfbc1 100644--- a/hog/src/commands/schema/pull.ts+++ b/hog/src/commands/schema/pull.ts@@ -1,19 +1,10 @@import { defineCommand } from '@/core/command'import { updateConfig, type SchemaLanguage } from '@/core/config'import { EXIT_USAGE, HogError } from '@/core/errors'+import { absolutePath, storedPath } from '@/core/paths'import { plural } from '@/core/text'-import {- absolutePath,- chosenFile,- configRoot,- fetchDefinitions,- isLanguage,- LANGUAGE_INFO,- LANGUAGES,- storedPath,- type Language,-} from './shared'+import { chosenFile, configRoot, fetchDefinitions, isLanguage, LANGUAGE_INFO, LANGUAGES, type Language } from './shared'interface PulledLanguage {language: Languagediff --git a/hog/src/commands/schema/shared.ts b/hog/src/commands/schema/shared.tsindex f75c46887e42..8bda0d10d3a0 100644--- a/hog/src/commands/schema/shared.ts+++ b/hog/src/commands/schema/shared.ts@@ -1,7 +1,8 @@-import { isAbsolute, join, relative, resolve } from 'node:path'+import { join } from 'node:path'import type { LoadedConfig } from '@/core/config'import type { Context } from '@/core/context'+import { absolutePath } from '@/core/paths'export const LANGUAGES = ['typescript', 'golang', 'python'] as constexport type Language = (typeof LANGUAGES)[number]@@ -62,16 +63,6 @@ export function configRoot(ctx: Context, loaded: LoadedConfig | undefined): strireturn loaded?.root ?? ctx.runtime.cwd()}-export function absolutePath(root: string, path: string): string {- return isAbsolute(path) ? path : resolve(root, path)-}--// A sibling folder stays relative, as posthog-cli stored it, so the file works in any checkout.-export function storedPath(root: string, path: string): string {- const rel = relative(root, path)- return isAbsolute(rel) ? path : rel-}-// Resolves a path the caller typed. A folder, or a path that ends with a slash, gets the// language's default file name.export async function chosenFile(ctx: Context, path: string, language: Language): Promise<string> {diff --git a/hog/src/commands/schema/status.ts b/hog/src/commands/schema/status.tsindex f921f9bc094a..abc9b4c73af1 100644--- a/hog/src/commands/schema/status.ts+++ b/hog/src/commands/schema/status.ts@@ -1,7 +1,8 @@import { defineCommand } from '@/core/command'+import { absolutePath } from '@/core/paths'import { plural } from '@/core/text'-import { absolutePath, configRoot, fetchDefinitions, isLanguage, LANGUAGE_INFO } from './shared'+import { configRoot, fetchDefinitions, isLanguage, LANGUAGE_INFO } from './shared'interface LanguageStatus {language: stringdiff --git a/hog/src/core/command.ts b/hog/src/core/command.tsindex 44b30b639e51..dd36f97e9b07 100644--- a/hog/src/core/command.ts+++ b/hog/src/core/command.ts@@ -20,6 +20,8 @@ export type OptionSpec =// The name shown in help, as in `--host <url>`. Defaults to the option name.placeholder?: stringchoices?: readonly string[]+ // The option can repeat, as in `--var a=1 --var b=2`, and its value is a list.+ multiple?: boolean}type ArgumentValues<Args> = {@@ -33,7 +35,9 @@ type ArgumentValues<Args> = {export type OptionValues<Options> = {[Name in keyof Options]: Options[Name] extends { type: 'boolean' }? boolean | undefined- : (Options[Name] extends { choices: readonly (infer Choice)[] } ? Choice : string) | undefined+ : Options[Name] extends { multiple: true }+ ? string[] | undefined+ : (Options[Name] extends { choices: readonly (infer Choice)[] } ? Choice : string) | undefined}interface CommandInput<Args, Options> {diff --git a/hog/src/core/config.ts b/hog/src/core/config.tsindex 7d032654d99d..4d70d36d2c9d 100644--- a/hog/src/core/config.ts+++ b/hog/src/core/config.ts@@ -64,6 +64,18 @@ export const PostHogConfig = z.strictObject({$schema: z.string().optional().describe('The JSON schema for this file.'),errorTracking: ErrorTracking.optional(),+ endpoints: z+ .strictObject({+ dir: z+ .string()+ .min(1)+ .optional()+ .describe(+ 'The folder of endpoint YAML files, relative to posthog.json. `hog endpoints pull` writes there, and `push` and `diff` read it when no path is passed.'+ ),+ })+ .optional()+ .describe('Settings for `hog endpoints`.'),languages: z.record(z.string(), SchemaLanguage).optional()diff --git a/hog/src/core/manifest.ts b/hog/src/core/manifest.tsindex e89c977b1293..a9df11756cca 100644--- a/hog/src/core/manifest.ts+++ b/hog/src/core/manifest.ts@@ -7,6 +7,7 @@ interface OptionEntry {description: stringtakesValue: booleanchoices?: readonly string[]+ repeatable?: boolean}export interface ManifestEntry {@@ -27,6 +28,7 @@ function describeOptions(options: Readonly<Record<string, OptionSpec>>): OptionEdescription: spec.description,takesValue: spec.type === 'string',choices: spec.type === 'string' ? spec.choices : undefined,+ repeatable: spec.type === 'string' && spec.multiple === true ? true : undefined,}))}diff --git a/hog/src/core/paths.ts b/hog/src/core/paths.tsnew file mode 100644index 000000000000..cb8ef7343f36--- /dev/null+++ b/hog/src/core/paths.ts@@ -0,0 +1,12 @@+import { isAbsolute, relative, resolve } from 'node:path'++export function absolutePath(root: string, path: string): string {+ return isAbsolute(path) ? path : resolve(root, path)+}++// The path to store in posthog.json, relative to its folder. A sibling folder stays relative, as+// posthog-cli stored it, so the file works in any checkout.+export function storedPath(root: string, path: string): string {+ const rel = relative(root, path)+ return isAbsolute(rel) ? path : rel+}diff --git a/hog/src/core/prompts.ts b/hog/src/core/prompts.tsindex 75e72d589b9f..d965885a916b 100644--- a/hog/src/core/prompts.ts+++ b/hog/src/core/prompts.ts@@ -25,6 +25,7 @@ export interface Prompts {): Promise<Value>text(message: string, options?: { initialValue?: string; validate?: Validate }): Promise<string>password(message: string, options?: { validate?: Validate }): Promise<string>+ confirm(message: string, options?: { initialValue?: boolean }): Promise<boolean>note(message: string, title: string): voidspinner(message: string): Spinner}@@ -68,6 +69,9 @@ export function clackPrompts(): Prompts {await clack.password({ message, validate: validate ? (value) => validate(value ?? '') : undefined }))},+ async confirm(message, options = {}) {+ return answer(await clack.confirm({ message, initialValue: options.initialValue ?? true }))+ },note(message, title) {clack.note(message, title)},diff --git a/hog/src/core/runtime.ts b/hog/src/core/runtime.tsindex b230812760b0..261541eb5360 100644--- a/hog/src/core/runtime.ts+++ b/hog/src/core/runtime.ts@@ -1,5 +1,5 @@import { randomUUID } from 'node:crypto'-import { access, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'+import { access, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'import { homedir } from 'node:os'import { dirname } from 'node:path'@@ -28,6 +28,10 @@ export interface Runtime {exists: (path: string) => Promise<boolean>readFile: (path: string) => Promise<string>isDirectory: (path: string) => Promise<boolean>+ // The names of the files directly in a folder, sorted. Folders inside it are left out.+ listFiles: (folder: string) => Promise<string[]>+ // The files under `cwd` that match a glob pattern, as paths relative to it, sorted.+ glob: (pattern: string, cwd: string) => Promise<string[]>// Writes a project file, such as a generated SDK, and creates the folders above it.writeFile: (path: string, contents: string) => Promise<void>writePrivateFile: (path: string, contents: string) => Promise<void>@@ -89,6 +93,15 @@ export function processRuntime(): Runtime {(stats) => stats.isDirectory(),() => false),+ listFiles: async (folder) => {+ const entries = await readdir(folder, { withFileTypes: true })+ return entries+ .filter((entry) => entry.isFile())+ .map((entry) => entry.name)+ .sort()+ },+ glob: async (pattern, cwd) =>+ (await Array.fromAsync(new Bun.Glob(pattern).scan({ cwd, onlyFiles: true }))).sort(),writeFile: async (path, contents) => {await mkdir(dirname(path), { recursive: true })await writeFile(path, contents)diff --git a/hog/src/endpoints/api.ts b/hog/src/endpoints/api.tsnew file mode 100644index 000000000000..b4ca0daf20e1--- /dev/null+++ b/hog/src/endpoints/api.ts@@ -0,0 +1,47 @@+import type { PostHogApi } from '@/posthog/api'++import type { Endpoint, InsightVariable } from './model'++interface Page<T> {+ results: T[]+ next?: string | null+}++// Follows `next` links, so a project with more endpoints than one page holds still gets all of them.+async function all<T>(api: PostHogApi, path: string): Promise<T[]> {+ const results: T[] = []+ let next: string | null | undefined = path+ while (next) {+ const page: Page<T> = await api.get<Page<T>>(next)+ results.push(...page.results)+ next = page.next ? new URL(page.next).pathname + new URL(page.next).search : undefined+ }+ return results+}++export function listEndpoints(api: PostHogApi): Promise<Endpoint[]> {+ return all<Endpoint>(api, 'endpoints/')+}++export function getEndpoint(api: PostHogApi, name: string): Promise<Endpoint> {+ return api.get<Endpoint>(`endpoints/${encodeURIComponent(name)}/`)+}++export function listInsightVariables(api: PostHogApi): Promise<InsightVariable[]> {+ return all<InsightVariable>(api, 'insight_variables/')+}++export function createInsightVariable(+ api: PostHogApi,+ variable: { code_name: string; type: string; default_value?: unknown; is_multi?: boolean }+): Promise<InsightVariable> {+ return api.post<InsightVariable>('insight_variables/', { name: variable.code_name, ...variable })+}++export function createEndpoint(api: PostHogApi, body: Record<string, unknown>): Promise<Endpoint> {+ return api.post<Endpoint>('endpoints/', body)+}++export function updateEndpoint(api: PostHogApi, name: string, body: Record<string, unknown>): Promise<Endpoint> {+ return api.patch<Endpoint>(`endpoints/${encodeURIComponent(name)}/`, body)+}diff --git a/hog/src/endpoints/changes.ts b/hog/src/endpoints/changes.tsnew file mode 100644index 000000000000..61d4acab2d7d--- /dev/null+++ b/hog/src/endpoints/changes.ts@@ -0,0 +1,100 @@+import {+ isPlainHogql,+ remoteVariableNames,+ remoteVariableValues,+ scheduleFor,+ withoutNulls,+ type Endpoint,+ type EndpointFile,+} from './model'++export type ChangeField = 'description' | 'query' | 'materialization' | 'schedule' | 'variables' | 'defaults'++// One field that differs between a local file and PostHog. Push reads it from remote to local,+// pull from local to remote.+export interface Change {+ field: ChangeField+ local: string+ remote: string+}++function sortKeys(value: unknown): unknown {+ if (Array.isArray(value)) {+ return value.map(sortKeys)+ }+ if (value !== null && typeof value === 'object') {+ return Object.fromEntries(+ Object.keys(value)+ .sort()+ .map((key) => [key, sortKeys((value as Record<string, unknown>)[key])])+ )+ }+ return value+}++// PostHog stores variables inside the query, under IDs a file never names, so they're compared on their own.+function comparableQuery(query: Record<string, unknown>): string {+ if (isPlainHogql(query) && typeof query.query === 'string') {+ return query.query.replace(/\r\n?/g, '\n')+ }+ const { variables: _variables, ...rest } = query+ return JSON.stringify(sortKeys(withoutNulls(rest)), null, 2)+}++export function localQuery(file: EndpointFile): string {+ return file.query?.replace(/\r\n?/g, '\n') ?? comparableQuery(file.query_definition ?? {})+}++export function remoteQuery(endpoint: Endpoint): string {+ return comparableQuery(endpoint.query)+}++const sameSet = (a: string[], b: string[]): boolean =>+ a.length === b.length && [...a].sort().every((value, index) => value === [...b].sort()[index])++export function compare(file: EndpointFile, endpoint: Endpoint): Change[] {+ const changes: Change[] = []+ const add = (field: ChangeField, local: string, remote: string): void => {+ if (local !== remote) {+ changes.push({ field, local, remote })+ }+ }+ add('description', file.description ?? '', endpoint.description ?? '')+ add('query', localQuery(file), remoteQuery(endpoint))+ add(+ 'materialization',+ file.materialization?.enabled ? 'enabled' : 'disabled',+ endpoint.is_materialized ? 'enabled' : 'disabled'+ )+ // PostHog keeps the refresh interval after materialization is turned off, so it only counts while on.+ const remoteSchedule = endpoint.is_materialized ? scheduleFor(endpoint.data_freshness_seconds) : undefined+ const localSchedule = file.materialization?.enabled ? file.materialization.schedule : undefined+ // A push without a schedule keeps the one PostHog has, so a file that names none matches any.+ if (localSchedule !== undefined) {+ add('schedule', localSchedule, remoteSchedule ?? '')+ }+ const localVariables = (file.variables ?? []).map((variable) => variable.name)+ const remoteVariables = remoteVariableNames(endpoint)+ if (!sameSet(localVariables, remoteVariables)) {+ changes.push({ field: 'variables', local: localVariables.join(', '), remote: remoteVariables.join(', ') })+ }+ // A variable without a default in the file takes the project's, so only the defaults a file sets count.+ const remoteValues = remoteVariableValues(endpoint)+ const show = (value: unknown): string => JSON.stringify(sortKeys(value ?? null))+ const changedDefaults = (file.variables ?? []).filter(+ (variable) =>+ variable.default !== undefined &&+ remoteValues.has(variable.name) &&+ show(variable.default) !== show(remoteValues.get(variable.name))+ )+ if (changedDefaults.length > 0) {+ changes.push({+ field: 'defaults',+ local: changedDefaults.map((variable) => `${variable.name}=${show(variable.default)}`).join(', '),+ remote: changedDefaults+ .map((variable) => `${variable.name}=${show(remoteValues.get(variable.name))}`)+ .join(', '),+ })+ }+ return changes+}diff --git a/hog/src/endpoints/files.ts b/hog/src/endpoints/files.tsnew file mode 100644index 000000000000..ff6b804f3c28--- /dev/null+++ b/hog/src/endpoints/files.ts@@ -0,0 +1,66 @@+import { relative } from 'node:path'+import { parse } from 'yaml'++import { absolutePath } from '@/core/paths'+import type { Runtime } from '@/core/runtime'++import { EndpointFile } from './model'++export interface LocalEndpoint {+ path: string+ file: EndpointFile+}++export interface FileProblem {+ path: string+ message: string+}++const isYaml = (name: string): boolean => /\.ya?ml$/i.test(name)++// Reads the endpoint files in the given files, folders (not recursive) and glob patterns. A file+// that doesn't parse is a problem to report, not a reason to stop the others.+export async function readEndpointFiles(+ runtime: Runtime,+ paths: readonly string[]+): Promise<{ endpoints: LocalEndpoint[]; problems: FileProblem[] }> {+ const cwd = runtime.cwd()+ const found: string[] = []+ const problems: FileProblem[] = []+ for (const path of paths) {+ const absolute = absolutePath(cwd, path)+ if (await runtime.isDirectory(absolute)) {+ const names = (await runtime.listFiles(absolute)).filter(isYaml)+ found.push(...names.map((name) => `${absolute.replace(/\/$/, '')}/${name}`))+ } else if (await runtime.exists(absolute)) {+ found.push(absolute)+ } else {+ const matches = await runtime.glob(path, cwd)+ if (matches.length === 0) {+ problems.push({ path, message: 'No such file or folder' })+ }+ found.push(...matches.map((match) => absolutePath(cwd, match)))+ }+ }++ const endpoints: LocalEndpoint[] = []+ for (const absolute of new Set(found)) {+ const path = relative(cwd, absolute) || absolute+ let raw: unknown+ try {+ raw = parse(await runtime.readFile(absolute))+ } catch (error) {+ problems.push({ path, message: `Not valid YAML: ${error instanceof Error ? error.message : error}` })+ continue+ }+ const parsed = EndpointFile.safeParse(raw)+ if (parsed.success) {+ endpoints.push({ path, file: parsed.data })+ } else {+ const [issue] = parsed.error.issues+ const where = issue?.path.length ? `${issue.path.join('.')}: ` : ''+ problems.push({ path, message: `${where}${issue?.message ?? 'not an endpoint file'}` })+ }+ }+ return { endpoints, problems }+}diff --git a/hog/src/endpoints/model.ts b/hog/src/endpoints/model.tsnew file mode 100644index 000000000000..2e9eee95975e--- /dev/null+++ b/hog/src/endpoints/model.ts@@ -0,0 +1,260 @@+import { z } from 'zod'++// The materialization schedules PostHog accepts, as posthog-cli writes them, with their refresh interval.+export const SCHEDULES = {+ '15min': 900,+ '30min': 1800,+ '1hour': 3600,+ '6hour': 21600,+ '12hour': 43200,+ '24hour': 86400,+ '7day': 604800,+} as const++export type Schedule = keyof typeof SCHEDULES++export const SCHEDULE_LABELS: Record<Schedule, string> = {+ '15min': 'every 15 min',+ '30min': 'every 30 min',+ '1hour': 'hourly',+ '6hour': 'every 6 hours',+ '12hour': 'every 12 hours',+ '24hour': 'daily',+ '7day': 'weekly',+}++export function scheduleFor(seconds: number | null | undefined): Schedule | undefined {+ return (Object.keys(SCHEDULES) as Schedule[]).find((schedule) => SCHEDULES[schedule] === seconds)+}++// The same fields and names as the files posthog-cli writes, so either CLI reads the other's files.+export const EndpointFile = z+ .strictObject({+ name: z.string().min(1, 'name is required'),+ description: z.string().optional(),+ query: z.string().optional(),+ query_definition: z.record(z.string(), z.unknown()).optional(),+ variables: z+ .array(+ z.strictObject({+ name: z.string().min(1),+ type: z.string().min(1),+ default: z.unknown().optional(),+ })+ )+ .optional(),+ materialization: z+ .strictObject({+ enabled: z.boolean().default(false),+ schedule: z+ .enum(Object.keys(SCHEDULES) as [Schedule, ...Schedule[]], {+ error: `schedule must be one of ${Object.keys(SCHEDULES).join(', ')}`,+ })+ .optional(),+ })+ .optional(),+ })+ .refine((file) => file.query !== undefined || file.query_definition !== undefined, {+ message: 'the file needs a query or a query_definition',+ })++export type EndpointFile = z.infer<typeof EndpointFile>+export type EndpointVariable = NonNullable<EndpointFile['variables']>[number]++export interface MaterializationStatus {+ status?: string | null+ can_materialize?: boolean+ last_materialized_at?: string | null+ error?: string | null+ reason?: string | null+}++export interface Endpoint {+ id: string+ name: string+ description?: string | null+ query: Record<string, unknown>+ is_active: boolean+ data_freshness_seconds?: number | null+ endpoint_path?: string+ url?: string | null+ ui_url?: string | null+ created_at: string+ updated_at: string+ is_materialized: boolean+ current_version?: number+ versions_count?: number+ materialization?: MaterializationStatus | null+}++export interface InsightVariable {+ id: string+ name: string+ code_name: string+ type: string+ default_value?: unknown+}++const VARIABLE_REFERENCE = /\{variables\.([a-zA-Z_][a-zA-Z0-9_]*)\}/g++// The HogQL text of a file: the `query` string, or the `query` field of a HogQL query definition.+export function hogqlOf(file: EndpointFile): string {+ const fromDefinition = file.query_definition?.query+ return file.query ?? (typeof fromDefinition === 'string' ? fromDefinition : '')+}++export function variableReferences(query: string): string[] {+ return [...new Set(Array.from(query.matchAll(VARIABLE_REFERENCE), (match) => match[1]!))]+}++export function remoteHogql(endpoint: Endpoint): string {+ return typeof endpoint.query.query === 'string' ? endpoint.query.query : ''+}++// A variable's value on the endpoint, by code name.+export function remoteVariableValues(endpoint: Endpoint): Map<string, unknown> {+ const variables = (endpoint.query.variables ?? {}) as Record<string, { code_name?: unknown; value?: unknown }>+ return new Map(+ Object.values(variables)+ .filter((variable) => typeof variable.code_name === 'string')+ .map((variable) => [variable.code_name as string, variable.value])+ )+}++// posthog-cli writes the lowercase type it infers from a default. PostHog only accepts its own type names.+const API_VARIABLE_TYPES: Record<string, string> = {+ string: 'String',+ integer: 'Number',+ number: 'Number',+ boolean: 'Boolean',+ array: 'List',+ list: 'List',+ date: 'Date',+}++export function apiVariableType(type: string): string {+ return API_VARIABLE_TYPES[type.toLowerCase()] ?? type+}++// A HogQL query can hold settings besides its text, such as `connectionId` or `filters`. A file+// keeps only the text when there are none, so that a push never drops them.+export function isPlainHogql(query: Record<string, unknown>): boolean {+ return (+ query.kind === 'HogQLQuery' &&+ typeof query.query === 'string' &&+ Object.entries(query).every(+ ([key, value]) =>+ ['kind', 'query', 'variables'].includes(key) ||+ value === null ||+ (typeof value === 'object' && Object.keys(value).length === 0)+ )+ )+}++export function remoteVariableNames(endpoint: Endpoint | undefined): string[] {+ const variables = endpoint?.query.variables+ if (!variables || typeof variables !== 'object') {+ return []+ }+ return Object.values(variables as Record<string, { code_name?: unknown }>)+ .map((variable) => variable.code_name)+ .filter((name): name is string => typeof name === 'string')+}++function inferType(value: unknown): string {+ if (typeof value === 'number') {+ return Number.isInteger(value) ? 'integer' : 'number'+ }+ if (typeof value === 'boolean') {+ return 'boolean'+ }+ if (Array.isArray(value)) {+ return 'array'+ }+ return value !== null && typeof value === 'object' ? 'object' : 'string'+}++// Query definitions come back with every optional field set to null. Dropping them keeps pulled+// files short, and PostHog fills the same defaults back in on push.+export function withoutNulls(value: unknown): unknown {+ if (Array.isArray(value)) {+ return value.map(withoutNulls)+ }+ if (value !== null && typeof value === 'object') {+ return Object.fromEntries(+ Object.entries(value)+ .filter(([, child]) => child !== null)+ .map(([key, child]) => [key, withoutNulls(child)])+ )+ }+ return value+}++// `types` maps a variable's code name to its type in the project. Without it, the type comes from the default value.+export function fileFromEndpoint(endpoint: Endpoint, types: ReadonlyMap<string, string> = new Map()): EndpointFile {+ const file: EndpointFile = { name: endpoint.name }+ if (endpoint.description) {+ file.description = endpoint.description+ }+ if (isPlainHogql(endpoint.query) && typeof endpoint.query.query === 'string') {+ file.query = endpoint.query.query.replace(/\r\n?/g, '\n')+ } else {+ const { variables: _variables, ...definition } = endpoint.query+ file.query_definition = withoutNulls(definition) as Record<string, unknown>+ }+ const variables = Object.values((endpoint.query.variables ?? {}) as Record<string, Record<string, unknown>>)+ .filter((variable) => typeof variable.code_name === 'string')+ .map((variable) => ({+ name: variable.code_name as string,+ type: types.get(variable.code_name as string) ?? inferType(variable.value),+ ...(variable.value !== undefined ? { default: variable.value } : {}),+ }))+ if (variables.length > 0) {+ file.variables = variables+ }+ if (endpoint.is_materialized) {+ const schedule = scheduleFor(endpoint.data_freshness_seconds)+ file.materialization = { enabled: true, ...(schedule ? { schedule } : {}) }+ }+ return file+}++export type ResolvedVariables = Map<string, InsightVariable>++// The request body for creating or updating the endpoint a file describes.+export function requestBody(file: EndpointFile, resolved: ResolvedVariables): Record<string, unknown> {+ const query: Record<string, unknown> = file.query_definition+ ? { ...file.query_definition }+ : { kind: 'HogQLQuery', query: file.query }+ const variables = Object.fromEntries(+ (file.variables ?? []).flatMap((variable) => {+ const resolvedVariable = resolved.get(variable.name)+ if (!resolvedVariable) {+ return []+ }+ const entry: Record<string, unknown> = {+ variableId: resolvedVariable.id,+ code_name: resolvedVariable.code_name,+ }+ if (variable.default !== undefined) {+ entry.value = variable.default+ // Without `isNull`, PostHog replaces a null value with the project's default.+ if (variable.default === null) {+ entry.isNull = true+ }+ }+ return [[resolvedVariable.id, entry]]+ })+ )+ if (Object.keys(variables).length > 0) {+ query.variables = variables+ }+ // PostHog keeps the description when the field is missing, so a file without one sends it empty.+ const body: Record<string, unknown> = { name: file.name, description: file.description ?? '', query }+ // A file without materialization turns it off, or the endpoint would differ from the file forever.+ body.is_materialized = file.materialization?.enabled ?? false+ if (file.materialization?.schedule) {+ body.data_freshness_seconds = SCHEDULES[file.materialization.schedule]+ }+ return body+}diff --git a/hog/src/endpoints/plan.ts b/hog/src/endpoints/plan.tsnew file mode 100644index 000000000000..78eb79008a33--- /dev/null+++ b/hog/src/endpoints/plan.ts@@ -0,0 +1,188 @@+import type { PostHogApi } from '@/posthog/api'++import { createEndpoint, createInsightVariable, updateEndpoint } from './api'+import { compare, type Change } from './changes'+import type { LocalEndpoint } from './files'+import {+ apiVariableType,+ hogqlOf,+ remoteVariableNames,+ requestBody,+ variableReferences,+ type Endpoint,+ type EndpointFile,+ type InsightVariable,+ type ResolvedVariables,+} from './model'++export interface VariableChange {+ name: string+ change: 'add' | 'remove' | 'retype'+ type?: string+ from?: string+}++export interface PushItem {+ name: string+ path: string+ action: 'create' | 'update' | 'skip'+ reason?: string+ // PostHog would reject the file, so the push fails.+ invalid?: boolean+ changes: Change[]+ variables: VariableChange[]+ file: EndpointFile+}++function variableChanges(+ file: EndpointFile,+ remoteNames: string[],+ existing: Map<string, InsightVariable>+): VariableChange[] {+ const changes: VariableChange[] = []+ for (const variable of file.variables ?? []) {+ const known = existing.get(variable.name)+ if (!remoteNames.includes(variable.name)) {+ changes.push({ name: variable.name, change: 'add', type: variable.type })+ } else if (known && known.type !== apiVariableType(variable.type)) {+ changes.push({ name: variable.name, change: 'retype', type: variable.type, from: known.type })+ }+ }+ const localNames = new Set((file.variables ?? []).map((variable) => variable.name))+ for (const name of remoteNames.filter((remote) => !localNames.has(remote))) {+ changes.push({ name, change: 'remove' })+ }+ return changes+}++// Why PostHog would reject the file, checked before anything is sent.+function rejection(file: EndpointFile, remoteNames: string[]): string | undefined {+ const references = variableReferences(hogqlOf(file))+ const localNames = (file.variables ?? []).map((variable) => variable.name)+ const removedButUsed = remoteNames.filter((name) => !localNames.includes(name) && references.includes(name))+ if (removedButUsed.length > 0) {+ return `The query still uses removed variables: ${removedButUsed.join(', ')}`+ }+ const unused = localNames.filter((name) => !references.includes(name))+ if (unused.length > 0) {+ return `The query doesn't use these variables, so remove them from the file: ${unused.join(', ')}`+ }+ return undefined+}++export function planPush(locals: LocalEndpoint[], remotes: Endpoint[], variables: InsightVariable[]): PushItem[] {+ const remoteByName = new Map(remotes.map((endpoint) => [endpoint.name, endpoint]))+ const existing = new Map(variables.map((variable) => [variable.code_name, variable]))+ const seen = new Map<string, string>()+ return locals.map(({ path, file }): PushItem => {+ const remote = remoteByName.get(file.name)+ const remoteNames = remoteVariableNames(remote)+ const base = { name: file.name, path, file, changes: [], variables: [] }+ const duplicate = seen.get(file.name)+ if (duplicate) {+ return { ...base, action: 'skip', invalid: true, reason: `${duplicate} defines the same endpoint` }+ }+ seen.set(file.name, path)+ const reason = rejection(file, remoteNames)+ if (reason) {+ return { ...base, action: 'skip', invalid: true, reason }+ }+ const variableDiff = variableChanges(file, remoteNames, existing)+ if (!remote) {+ return { ...base, action: 'create', variables: variableDiff }+ }+ const changes = compare(file, remote)+ // PostHog keeps a variable's type when an endpoint changes, so a type change alone is nothing to push.+ const retyped = variableDiff.filter((change) => change.change === 'retype')+ if (changes.length === 0 && variableDiff.length === retyped.length) {+ const reason = retyped.length+ ? `No changes hog can push. Change the type of ${retyped.map((change) => change.name).join(', ')} in PostHog`+ : 'No changes'+ return { ...base, action: 'skip', reason, variables: retyped }+ }+ return { ...base, action: 'update', changes, variables: variableDiff }+ })+}++export interface PushOutcome {+ name: string+ path: string+ status: 'created' | 'updated' | 'failed'+ uiUrl?: string | null+ error?: string+}++// Creates the variables a file adds that the project doesn't have yet, then the endpoint. A+// failure stops only its own endpoint.+export async function applyPush(+ api: PostHogApi,+ items: PushItem[],+ variables: InsightVariable[]+): Promise<PushOutcome[]> {+ const known = new Map(variables.map((variable) => [variable.code_name, variable]))+ const outcomes: PushOutcome[] = []+ for (const item of items) {+ if (item.action === 'skip') {+ continue+ }+ try {+ const resolved: ResolvedVariables = new Map()+ for (const variable of item.file.variables ?? []) {+ let insightVariable = known.get(variable.name)+ if (!insightVariable) {+ insightVariable = await createInsightVariable(api, {+ code_name: variable.name,+ type: apiVariableType(variable.type),+ ...(variable.default !== undefined ? { default_value: variable.default } : {}),+ // A single-selection list keeps only the first value of an array default.+ ...(Array.isArray(variable.default) ? { is_multi: true } : {}),+ })+ known.set(variable.name, insightVariable)+ }+ resolved.set(variable.name, insightVariable)+ }+ const body = requestBody(item.file, resolved)+ const saved =+ item.action === 'create' ? await createEndpoint(api, body) : await updateEndpoint(api, item.name, body)+ outcomes.push({+ name: item.name,+ path: item.path,+ status: item.action === 'create' ? 'created' : 'updated',+ uiUrl: saved.ui_url,+ })+ } catch (error) {+ outcomes.push({+ name: item.name,+ path: item.path,+ status: 'failed',+ error: error instanceof Error ? error.message : String(error),+ })+ }+ }+ return outcomes+}++export interface PullItem {+ name: string+ path: string+ action: 'create' | 'update' | 'skip'+ reason?: string+ changes: Change[]+ endpoint: Endpoint+}++// An endpoint a local file already defines updates that file in place. Any other goes to+// `<folder>/<name>.yaml`, or to `file` when the target is a single YAML file.+export function planPull(remotes: Endpoint[], locals: LocalEndpoint[], pathFor: (name: string) => string): PullItem[] {+ const localByName = new Map(locals.map((local) => [local.file.name, local]))+ return remotes.map((endpoint): PullItem => {+ const local = localByName.get(endpoint.name)+ if (!local) {+ return { name: endpoint.name, path: pathFor(endpoint.name), action: 'create', changes: [], endpoint }+ }+ const changes = compare(local.file, endpoint)+ return changes.length === 0+ ? { name: endpoint.name, path: local.path, action: 'skip', reason: 'No changes', changes, endpoint }+ : { name: endpoint.name, path: local.path, action: 'update', changes, endpoint }+ })+}diff --git a/hog/src/testing.ts b/hog/src/testing.tsindex a45e7c27a63f..d23762a2259e 100644--- a/hog/src/testing.ts+++ b/hog/src/testing.ts@@ -45,6 +45,7 @@ function fakePrompts(answers: string[]): Prompts {select: (message) => next(message) as never,text: (message) => next(message),password: (message) => next(message),+ confirm: async (message) => (await next(message)) === 'yes',note: () => {},spinner: () => ({ stop: () => {}, error: () => {} }),}@@ -103,6 +104,21 @@ export function fakeRuntime(options: FakeRuntimeOptions = {}): FakeRuntime {options.useDisk? existsSync(path) && statSync(path).isDirectory(): Object.keys(files).some((file) => file.startsWith(`${path.replace(/\/$/, '')}/`)),+ listFiles: async (folder) => {+ const prefix = `${folder.replace(/\/$/, '')}/`+ return Object.keys(files)+ .filter((file) => file.startsWith(prefix) && !file.slice(prefix.length).includes('/'))+ .map((file) => file.slice(prefix.length))+ .sort()+ },+ glob: async (pattern, cwd) => {+ const prefix = `${cwd.replace(/\/$/, '')}/`+ const glob = new Bun.Glob(pattern)+ return Object.keys(files)+ .filter((file) => file.startsWith(prefix) && glob.match(file.slice(prefix.length)))+ .map((file) => file.slice(prefix.length))+ .sort()+ },writeFile: async (path, contents) => {files[path] = contents},diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex e3493e0f684e..3382f85e2a30 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -1532,9 +1532,15 @@ importers:commander:specifier: 15.0.0version: 15.0.0+ diff:+ specifier: 8.0.4+ version: 8.0.4pako:specifier: 2.1.0version: 2.1.0+ yaml:+ specifier: 2.9.0+ version: 2.9.0zod:specifier: ^4.3.6version: 4.3.6