: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
import { randomUUID } from 'node:crypto'
import { access, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
import { homedir } from 'node:os'
import { basename, dirname } from 'node:path'
import type { ApiToolLibrary } from '@posthog/mcp/src/cli/library-types'
import { HogError } from './errors'
import { clackPrompts, type Prompts } from './prompts'
import { DEFAULT_TELEMETRY_TOKEN } from './telemetry'
export type Env = Readonly<Record<string, string | undefined>>
// `timeoutMs` starts when the request leaves, so time spent waiting for --rate-limit doesn't count.
// `skipRateLimit` marks a signed storage URL, which posthog-cli's --rate-limit doesn't count either.
export type RuntimeFetch = (
input: string | URL | Request,
init?: RequestInit & { timeoutMs?: number; skipRateLimit?: boolean }
) => Promise<Response>
// The operating system's secret store: Keychain on macOS, Credential Manager on Windows and Secret
// Service on Linux. Every item belongs to hog's own service, so `name` only has to be unique within hog.
export interface Secrets {
// Resolves to null when there is no item with this name.
get: (name: string) => Promise<string | null>
set: (name: string, value: string) => Promise<void>
// Resolves to false when there was no item to delete.
delete: (name: string) => Promise<boolean>
}
// Everything a command touches outside its own arguments. Tests build one by hand,
// so no command reads `process` or the network directly.
export interface Runtime {
env: Env
platform: NodeJS.Platform
// True for `bun src/index.ts`, false for a compiled hog. A run from source keeps its credentials
// and settings apart, so it never reads or replaces those of an installed hog.
isDevelopment: boolean
stdinIsTTY: boolean
stdoutIsTTY: boolean
stdoutHasColors: boolean
stdoutColumns: number | undefined
writeStdout: (text: string) => void
writeStderr: (text: string) => void
fetch: RuntimeFetch
now: () => number
// Resolves early when `signal` aborts, so a timer that lost a race doesn't keep hog running.
sleep: (ms: number, signal?: AbortSignal) => Promise<void>
homeDir: () => string | undefined
cwd: () => string
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>
// Creates a private file unless the path exists, and resolves to false if it does, so it works as a lock.
createFile: (path: string, contents: string) => Promise<boolean>
removeFile: (path: string) => Promise<void>
readStdin: () => Promise<string>
// Resolves to false when no browser could be started, for example on a server without one.
openUrl: (url: string) => Promise<boolean>
prompts: Prompts
secrets: Secrets
// The project token for anonymous usage events. Undefined turns them off, as in tests.
telemetryToken: string | undefined
// Accepts any TLS certificate from here on, for every request, including the API tools' own.
skipTlsVerification: () => void
// The MCP server's tool catalog, which `hog api` browses and calls. Loaded on first use: it is large.
loadApiTools: () => Promise<ApiToolLibrary>
}
const BROWSER_LAUNCH_MS = 1000
function browserCommand(url: string): string[] {
switch (process.platform) {
case 'darwin':
return ['open', url]
case 'win32':
// Not `cmd /c start`: cmd treats the `&` in a URL's query string as a command separator.
return ['rundll32', 'url.dll,FileProtocolHandler', url]
default:
return ['xdg-open', url]
}
}
// `bun src/index.ts` runs as the bun executable, a compiled hog as itself.
const FROM_SOURCE = basename(process.execPath).replace(/\.exe$/i, '') === 'bun'
// Keychain calls that haven't settled. A call hog stopped waiting for, such as one behind a dialog
// nobody answers, keeps the process alive, so the entry point ends the process when this is not zero.
let pendingSecretCalls = 0
export function hasPendingSecretCalls(): boolean {
return pendingSecretCalls > 0
}
async function tracked<T>(call: () => Promise<T>): Promise<T> {
pendingSecretCalls += 1
try {
return await call()
} finally {
pendingSecretCalls -= 1
}
}
function bunSecrets(service: string): Secrets {
return {
get: (name) => tracked(() => Bun.secrets.get({ service, name })),
// Windows only: the default `enterprise` lets a roaming profile copy the item to every machine the
// person signs in to. Bun before 1.4.3 ignores the option, so the item still roams there.
// TODO: require Bun 1.4.3+ (engines.bun and the flox pin) once hog can move to it.
set: (name, value) =>
tracked(() =>
Bun.secrets.set({ service, name, value, persist: 'local' } as Parameters<typeof Bun.secrets.set>[0])
),
delete: (name) => tracked(() => Bun.secrets.delete({ service, name })),
}
}
function sleep(ms: number, signal?: AbortSignal): Promise<void> {
return new Promise((resolve) => {
if (signal?.aborted) {
resolve()
return
}
const timer = setTimeout(resolve, ms)
signal?.addEventListener(
'abort',
() => {
clearTimeout(timer)
resolve()
},
{ once: true }
)
})
}
export function processRuntime(): Runtime {
return {
env: process.env,
platform: process.platform,
isDevelopment: FROM_SOURCE,
stdinIsTTY: process.stdin.isTTY === true,
stdoutIsTTY: process.stdout.isTTY === true,
stdoutHasColors: process.stdout.isTTY === true && process.stdout.hasColors(),
stdoutColumns: process.stdout.columns || undefined,
writeStdout: (text) => {
process.stdout.write(text)
},
writeStderr: (text) => {
process.stderr.write(text)
},
fetch: (input, { timeoutMs, skipRateLimit: _skipRateLimit, ...init } = {}) =>
globalThis.fetch(
input,
timeoutMs === undefined ? init : { ...init, signal: AbortSignal.timeout(timeoutMs) }
),
now: () => Date.now(),
sleep,
homeDir: () => {
try {
const home = homedir()
// When HOME is unset and the user has no passwd entry, Node throws but Bun returns "/".
// A "/" that came from HOME itself is a real choice, so it still counts.
return !home || (home === '/' && !process.env.HOME) ? undefined : home
} catch {
return undefined
}
},
cwd: () => process.cwd(),
exists: (path) =>
access(path).then(
() => true,
() => false
),
readFile: (path) => readFile(path, 'utf8'),
isDirectory: (path) =>
stat(path).then(
(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)
},
// A rename is atomic, so a crash never leaves a half-written file. The temporary name is
// random and `wx` refuses an existing path, so nobody can plant a symlink there first.
writePrivateFile: async (path, contents) => {
await mkdir(dirname(path), { recursive: true, mode: 0o700 })
const temporary = `${path}.${randomUUID()}.tmp`
try {
await writeFile(temporary, contents, { mode: 0o600, flag: 'wx' })
await rename(temporary, path)
} catch (error) {
await rm(temporary, { force: true })
throw error
}
},
createFile: async (path, contents) => {
await mkdir(dirname(path), { recursive: true, mode: 0o700 })
try {
await writeFile(path, contents, { mode: 0o600, flag: 'wx' })
return true
} catch (error) {
if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
return false
}
throw error
}
},
removeFile: (path) => rm(path, { force: true }),
readStdin: () => new Response(Bun.stdin.stream()).text(),
openUrl: async (url) => {
if (!URL.canParse(url) || !['http:', 'https:'].includes(new URL(url).protocol)) {
return false
}
try {
const child = Bun.spawn(browserCommand(url), { stdin: 'ignore', stdout: 'ignore', stderr: 'ignore' })
child.unref()
// Some openers, like xdg-open, stay attached to the browser they start. Waiting for
// them to exit would hold up polling, so hog only waits long enough to see a failed launch.
const code = await Promise.race([child.exited, Bun.sleep(BROWSER_LAUNCH_MS).then(() => undefined)])
return code === undefined || code === 0
} catch {
return false
}
},
prompts: clackPrompts(),
secrets: bunSecrets(FROM_SOURCE ? 'com.posthog.hog.dev' : 'com.posthog.hog'),
telemetryToken: DEFAULT_TELEMETRY_TOKEN,
skipTlsVerification: () => {
// Runs only for --skip-ssl-verification, posthog-cli's opt-in flag for self-hosted certificates.
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0' // nosemgrep: trailofbits.generic.node-disable-certificate-validation.node-disable-certificate-validation
},
loadApiTools: async () => {
try {
const { createApiToolLibrary } = await import('@posthog/mcp/dist/cli-library.mjs')
return createApiToolLibrary()
} catch (error) {
if ((error as { code?: string }).code === 'ERR_MODULE_NOT_FOUND') {
throw new HogError(
'api_tools_missing',
"hog couldn't find the API tool catalog.",
'Run `pnpm --filter @posthog/hog build:mcp`, then run the command again.'
)
}
throw error
}
},
}
}