Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

9.1 KB
Raw Blame
import { MAX_TERMINAL_FILE_BYTES, TerminalFilesystem } from './terminalFilesystem'
import { HOGQL_SCRIPT } from './terminalHogql'

const OPEN_SCRIPT = String.raw`#!/bin/sh
set -eu
if [ "$#" -gt 1 ]; then
    printf '%s\n' 'Use open with one file or folder path. Quote paths containing spaces.' >&2
    exit 1
fi
if [ "$#" -eq 0 ]; then
    set -- .
fi
target="$1"
case "$target" in
    /*) ;;
    *) target="$PWD/$target" ;;
esac
target=$(realpath "$target")
exec ph open "$target"
`

export const PH_SCRIPT = String.raw`#!/bin/sh
set -eu
set -o pipefail
temporary=$(mktemp -d)
trap 'rm -rf "$temporary"' EXIT
trap 'exit 130' HUP INT TERM
previous=''
command=''
if [ "$#" -gt 0 ]; then command="$1"; fi
for argument in "$@"; do
    original="$argument"
    { if [ "$command" = '_complete' ]; then
        printf '%s' "$argument"
    else case "$argument" in
        @*) cat -- "$(printf '%s' "$argument" | cut -c2-)" ;;
        -)
            if [ "$previous" = '--json' ]; then
                cat
            else
                printf '%s' "$argument"
            fi
            ;;
        *) printf '%s' "$argument" ;;
    esac; fi; } | base64 | tr -d '\n'
    previous="$original"
    printf '\n'
done > "$temporary/args"
jq -Rs --arg cwd "$PWD" '{argv: (split("\n")[:-1] | map(@base64d)), cwd: $cwd}' < "$temporary/args" > "$temporary/request"
exec 9>/tmp/posthog-ph.lock
flock -x 9
cat "$temporary/request" > /posthog/.ph/request
response=$(cat /posthog/.ph/response)
flock -u 9
if printf '%s' "$response" | jq -e '.ok' >/dev/null; then
    printf '%s' "$response" | jq -r '.warnings[]? | "Warning: " + .' >&2
    printf '%s' "$response" | jq -r '.result'
else
    printf '%s' "$response" | jq -r '.error' >&2
    exit 1
fi
`

export const SHELL_RC = `
alias ls='ls --color=auto'
if [ -n "$BASH_VERSION" ]; then
    _ph_complete() {
        mapfile -t COMPREPLY < <(ph _complete "$COMP_CWORD" "$2" "$3" "\${COMP_WORDS[1]}" 2>/dev/null)
        if [ "\${#COMPREPLY[@]}" -eq 1 ] && [ -z "\${COMPREPLY[0]}" ]; then COMPREPLY=(); fi
    }
    complete -o bashdefault -o default -F _ph_complete ph
fi
`

export const RUN_HELP = `Usage: run [format] <file[.sql]>

Run a SQL file in the current PostHog project.
If the file is missing, run also looks for <file>.sql.

Formats (choose one, before or after the filename):
  --markdown       Markdown table with headers and rows (default)
  --json           Full query result as JSON, including metadata
  --csv            Comma-separated headers and rows
  --tsv            Tab-separated headers and rows
  --help, -h       Show this help

Markdown, CSV, and TSV contain only the returned table. Use --json
to check hasMore for additional rows. CSV and TSV quote fields containing
delimiters, quotes, or newlines; null values are empty fields.

Examples:
  run report.sql
  run report > results.md
  run --json report.sql > /tmp/results.json
  run report.sql --csv > /tmp/results.csv

Use /tmp for exports.
Query errors go to stderr and exit nonzero.
Query warnings go to stderr in every output format.
`

const RUN_SCRIPT = String.raw`#!/bin/sh
set -eu
usage() {
    cat <<'HELP'
${RUN_HELP}
HELP
}
format=''
file=''
while [ "$#" -gt 0 ]; do
    case "$1" in
        --help|-h) usage; exit 0 ;;
        --markdown|--json|--csv|--tsv)
            [ -z "$format" ] || { echo 'Choose one output format. Run run --help for formats.' >&2; exit 1; }
            format="$1"
            ;;
        --)
            shift
            [ "$#" -eq 1 ] && [ -z "$file" ] || { usage >&2; exit 1; }
            file="$1"
            break
            ;;
        -*) echo "Unknown option: $1. Run run --help for options." >&2; exit 1 ;;
        *) [ -z "$file" ] || { usage >&2; exit 1; }; file="$1" ;;
    esac
    shift
done
[ -n "$file" ] || { usage >&2; exit 1; }
if [ ! -e "$file" ] && [ -f "$file.sql" ]; then file="$file.sql"; fi
case "$file" in
    *.sql) ;;
    *.md) echo 'Running Markdown notebooks is not supported yet. Use run <file.sql>.' >&2; exit 1 ;;
    *) echo 'Only .sql files can be run. Use run <file.sql>.' >&2; exit 1 ;;
esac
[ -f "$file" ] || { echo "SQL file not found: $file" >&2; exit 1; }
target=$(readlink -f -- "$file")
[ -n "$format" ] || format='--markdown'
exec ph run "$target" "@$target" "$format"
`

export interface TerminalCommandContext {
    signal?: AbortSignal
    onWarning?: (message: string) => void
}

export class TerminalCommands {
    constructor(
        filesystem: TerminalFilesystem,
        execute: (argv: string[], cwd: string, context: TerminalCommandContext) => Promise<unknown>
    ) {
        const encoder = new TextEncoder()
        const decoder = new TextDecoder('utf-8', { fatal: true })
        const envelope = (value: object): Uint8Array => encoder.encode(JSON.stringify(value))
        let response = envelope({ ok: false, error: 'Run a ph command first.' })
        let pending: { controller: AbortController; result: Promise<void> } | undefined
        const directory = filesystem.directory('.ph', filesystem.root)
        const responseNode = filesystem.file('response', directory, async (signal) => {
            const command = pending
            if (command) {
                const abort = (): void => command.controller.abort()
                if (signal?.aborted) {
                    abort()
                }
                signal?.addEventListener('abort', abort, { once: true })
                try {
                    await command.result
                } finally {
                    signal?.removeEventListener('abort', abort)
                }
            }
            return { bytes: response }
        })
        filesystem.file(
            'request',
            directory,
            async () => ({
                bytes: new Uint8Array(),
                save: async (bytes) => {
                    pending?.controller.abort()
                    await pending?.result
                    const controller = new AbortController()
                    const warnings: string[] = []
                    let query = false
                    const run = async (): Promise<void> => {
                        try {
                            const request = JSON.parse(decoder.decode(bytes))
                            if (
                                !request ||
                                !Array.isArray(request.argv) ||
                                request.argv.length > 1000 ||
                                !request.argv.every((value: unknown) => typeof value === 'string') ||
                                typeof request.cwd !== 'string'
                            ) {
                                throw new Error('Invalid command request. Run ph help for usage.')
                            }
                            query = ['hogql', 'run'].includes(request.argv[0])
                            const result = await execute(request.argv, request.cwd, {
                                signal: controller.signal,
                                onWarning: (message) => warnings.push(message),
                            })
                            const encoded = envelope({
                                ok: true,
                                result: result ?? null,
                                ...(warnings.length ? { warnings } : {}),
                            })
                            if (encoded.length > MAX_TERMINAL_FILE_BYTES) {
                                throw new Error('The result exceeds 4 MiB. Reduce the limit or narrow the query.')
                            }
                            response = encoded
                        } catch (error) {
                            // A failed tool can put its whole payload in the message, and the guest reads
                            // this file into a shell variable inside the virtual machine.
                            const encoded = envelope({
                                ok: false,
                                error: error instanceof Error ? error.message : 'The command failed. Try ph help.',
                            })
                            response =
                                encoded.length > MAX_TERMINAL_FILE_BYTES
                                    ? envelope({
                                          ok: false,
                                          error: 'The command failed, and its error exceeds 4 MiB. Check the tool that returned it.',
                                      })
                                    : encoded
                        }
                        responseNode.size = response.length
                    }
                    pending = { controller, result: run() }
                    // Linux does not flush Tclunk on Ctrl+C. Query waits belong in the interruptible response open.
                    if (!query) {
                        await pending.result
                    }
                },
            }),
            true
        )
        const bin = filesystem.directory('bin', filesystem.root)
        filesystem.text('ph', bin, PH_SCRIPT)
        filesystem.text('run', bin, RUN_SCRIPT)
        filesystem.text('hogql', bin, HOGQL_SCRIPT)
        filesystem.text('shellrc', bin, SHELL_RC)
        filesystem.text('open', bin, OPEN_SCRIPT)
    }
}