{"owner":"jitsucom","repo":"jitsu","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Jitsu — Agent Guidelines\n\n## Project Overview\n\nJitsu is an open-source data pipeline platform (self-hosted Segment alternative). It\ncollects events from websites/apps and routes them to data warehouses and other\ndestinations.\n\n## Repository Structure\n\nThis is a monorepo with two main technology stacks:\n\n### Go (`/bulker`)\n\nData ingestion engine for streaming events to warehouses.\n\n- `bulkerapp/` — main Bulker service\n- `ingest/` — HTTP ingest endpoint\n- `sync-controller/` — connector sync orchestration\n- `bulkerlib/` — core ingestion library\n- `connectors/` — warehouse connectors (ClickHouse, BigQuery, Redshift, Snowflake, S3,\n  GCS, etc.)\n\n### Node.js / TypeScript\n\n**Services (`/services`)**\n- `rotor/` — event routing, transformation, and function execution\n\n**Web apps (`/webapps`)**\n- `console/` — admin UI (Next.js)\n\n> The enterprise-edition billing/admin API now lives in\n> [`jitsucom/jitsu-cloud-billing`](https://github.com/jitsucom/jitsu-cloud-billing)\n> (deployed at `billing.jitsu.com`).\n\n**Libraries (`/libs`)**\n- `jitsu-js/` — browser JS SDK (`@jitsu/js`)\n- `jitsu-react/` — React bindings (`@jitsu/jitsu-react`)\n- `functions/` — functions runtime (`@jitsu/functions-lib`)\n- `juava/` — shared utilities\n\n**CLI (`/cli`)**\n- `jitsu-cli/` — developer CLI (`jitsu-cli` on npm)\n\n**Types (`/types`)**\n- `protocols/` — shared TypeScript protocols (`@jitsu/protocols`)\n\n## Tooling\n\n- **Node.js:** pnpm ≥10 (workspace manager), Turbo (build orchestration), Node.js ≥22\n- **Go:** Go 1.26 with Go workspaces (`go.work` at repo root)\n- **Frontend:** Next.js, React 18, TypeScript, Tailwind CSS\n- **Testing:** Jest (unit), Playwright (E2E), Go's built-in `testing`\n- **CI:** GitHub Actions (`.github/workflows/`)\n\n## Common Commands\n\n```bash\n# Install JS dependencies\npnpm install\n\n# Generate Prisma client + zod schemas (required once after a fresh checkout\n# or worktree). Skipping this leaves Turbopack panicking in\n# ModuleGraphImportTracer::get_traces because it can't render the missing-\n# module error for `prisma/schema`.\npnpm codegen\n\n# Build all JS packages\npnpm build:turbo\n\n# Type-check\npnpm typecheck:turbo\n\n# Run tests. Console tests include an integration project that needs Docker\n# (testcontainers: Postgres + ClickHouse); run only the pure tests with\n# `pnpm exec vitest run --project unit` from webapps/console.\n# Details: CONTRIBUTING.md \"Testing\".\npnpm test\n\n# Lint / format\npnpm lint\npnpm format\n\n# Start all dev services (hot-reload)\npnpm dev\n\n# Start only the console\npnpm console:dev\n```\n\n## Running the app for the user\n\nIf the user asks you to run the app (console / dev stack), use:\n\n- `pnpm console:dev` — only console\n- `pnpm ui:dev` — equivalent (turbo)\n\nThese go through [portless](https://portless.sh) and serve the app at\n`https://console.jitsu.localhost`.\n\n**Branch hosting.** The dev wrapper auto-detects the current git branch and\nsuffixes the dev host with it: `https://console-$BRANCH.jitsu.localhost`. This\navoids cookie / port collisions with whatever the user has running from another\nbranch.\n\n- The repo's default branch (resolved via `git rev-parse origin/HEAD`) gets no\n  suffix.\n- The branch name is sanitized for DNS (lowercased, non-`[a-z0-9-]` → `-`,\n  collapsed, capped at 30 chars).\n- `pnpm console:dev --no-branch` disables the suffix (use the bare\n  `console.jitsu.localhost` host).\n\nIf the user explicitly asks you not to use a branch suffix, pass `--no-branch`.\n\n> Implementation note: `dev-scripts/src/bin/run-app.ts` loads root `.env` /\n> `.env.local`, computes the slug, and runs portless from a non-git scratch dir\n> with `--name <slug>` and a `bash -c \"cd <ws> && <cmd>\"` wrapper — sidesteps\n> portless's hardcoded dot-style worktree prefix.\n\n`portless` is a workspace devDependency — `pnpm install` is enough, no global\ninstall. First-run on a machine prompts once for `sudo` to bind port 443 and\ntrust the local CA.\n\n## Dev scripts\n\nThe `dev-scripts` package (`./dev-scripts`) hosts repo-wide developer tooling.\nInvoke via `pnpm dev <subcommand>`:\n\n```bash\npnpm dev                            # turbo run dev (start everything)\npnpm dev copy-db --src URL --dst URL   # rsync-style postgres copy ($ENV_VAR placeholders)\npnpm dev help\n```\n\nFor Go (run inside `/bulker`):\n\n```bash\ngo build ./...\ngo test ./...\n```\n\n## Git Workflow\n\nWhen you need to create branches, make commits, or open pull requests, read\n[CONTRIBUTING.md](CONTRIBUTING.md) first. No need to read it for code exploration —\nonly when interacting with git.\n\n### Referencing Linear issues\n\nWhen referencing a Linear issue in GitHub (PR descriptions, commit messages,\ncomments), use the bare issue id — `` `JITSU-67` `` — not a Linear URL or a\nmarkdown link to one.\n\nBefore opening a PR, try to work out which Linear issue the work relates to —\ncheck the branch name, search via the Linear MCP if it's available, or ask the\nuser with the question tool. If the PR clearly relates to an issue, prefix the\nPR title with the issue id and put the id in the body. It's fine if there's no\nissue — but offer to create one (when the Linear MCP is available).\n\n## Deployments\n\nThe console can be auto-deployed to **beta** on PR merge via the\n[`deploy-console-on-merge`](.github/workflows/deploy-console-on-merge.yml)\nworkflow: any PR carrying the **`deploy:console`** label triggers a beta console\ndeployment in `jitsu-cloud-infra` the moment it merges into `newjitsu`. This\nexists because the post-merge deploy step is easy to forget, so fixes sit\nundeployed for weeks (see JITSU-68). It's scoped to `console` only — its error\ntolerance is high (a brief outage doesn't drop data); `bulker` and `rotor` still\ndeploy manually and deliberately.\n\n**When you open a PR (including a draft), explicitly ask the user whether they\nwant the console to auto-deploy on merge.** If yes, add the `deploy:console`\nlabel to the PR (e.g. `gh pr edit <pr> --add-label deploy:console`). Only offer\nthis for PRs that actually touch the console; never add the label to `bulker` /\n`rotor` changes.\n"},"files":{"AGENTS.md":"# Jitsu — Agent Guidelines\n\n## Project Overview\n\nJitsu is an open-source data pipeline platform (self-hosted Segment alternative). It\ncollects events from websites/apps and routes them to data warehouses and other\ndestinations.\n\n## Repository Structure\n\nThis is a monorepo with two main technology stacks:\n\n### Go (`/bulker`)\n\nData ingestion engine for streaming events to warehouses.\n\n- `bulkerapp/` — main Bulker service\n- `ingest/` — HTTP ingest endpoint\n- `sync-controller/` — connector sync orchestration\n- `bulkerlib/` — core ingestion library\n- `connectors/` — warehouse connectors (ClickHouse, BigQuery, Redshift, Snowflake, S3,\n  GCS, etc.)\n\n### Node.js / TypeScript\n\n**Services (`/services`)**\n- `rotor/` — event routing, transformation, and function execution\n\n**Web apps (`/webapps`)**\n- `console/` — admin UI (Next.js)\n\n> The enterprise-edition billing/admin API now lives in\n> [`jitsucom/jitsu-cloud-billing`](https://github.com/jitsucom/jitsu-cloud-billing)\n> (deployed at `billing.jitsu.com`).\n\n**Libraries (`/libs`)**\n- `jitsu-js/` — browser JS SDK (`@jitsu/js`)\n- `jitsu-react/` — React bindings (`@jitsu/jitsu-react`)\n- `functions/` — functions runtime (`@jitsu/functions-lib`)\n- `juava/` — shared utilities\n\n**CLI (`/cli`)**\n- `jitsu-cli/` — developer CLI (`jitsu-cli` on npm)\n\n**Types (`/types`)**\n- `protocols/` — shared TypeScript protocols (`@jitsu/protocols`)\n\n## Tooling\n\n- **Node.js:** pnpm ≥10 (workspace manager), Turbo (build orchestration), Node.js ≥22\n- **Go:** Go 1.26 with Go workspaces (`go.work` at repo root)\n- **Frontend:** Next.js, React 18, TypeScript, Tailwind CSS\n- **Testing:** Jest (unit), Playwright (E2E), Go's built-in `testing`\n- **CI:** GitHub Actions (`.github/workflows/`)\n\n## Common Commands\n\n```bash\n# Install JS dependencies\npnpm install\n\n# Generate Prisma client + zod schemas (required once after a fresh checkout\n# or worktree). Skipping this leaves Turbopack panicking in\n# ModuleGraphImportTracer::get_traces because it can't render the missing-\n# module error for `prisma/schema`.\npnpm codegen\n\n# Build all JS packages\npnpm build:turbo\n\n# Type-check\npnpm typecheck:turbo\n\n# Run tests. Console tests include an integration project that needs Docker\n# (testcontainers: Postgres + ClickHouse); run only the pure tests with\n# `pnpm exec vitest run --project unit` from webapps/console.\n# Details: CONTRIBUTING.md \"Testing\".\npnpm test\n\n# Lint / format\npnpm lint\npnpm format\n\n# Start all dev services (hot-reload)\npnpm dev\n\n# Start only the console\npnpm console:dev\n```\n\n## Running the app for the user\n\nIf the user asks you to run the app (console / dev stack), use:\n\n- `pnpm console:dev` — only console\n- `pnpm ui:dev` — equivalent (turbo)\n\nThese go through [portless](https://portless.sh) and serve the app at\n`https://console.jitsu.localhost`.\n\n**Branch hosting.** The dev wrapper auto-detects the current git branch and\nsuffixes the dev host with it: `https://console-$BRANCH.jitsu.localhost`. This\navoids cookie / port collisions with whatever the user has running from another\nbranch.\n\n- The repo's default branch (resolved via `git rev-parse origin/HEAD`) gets no\n  suffix.\n- The branch name is sanitized for DNS (lowercased, non-`[a-z0-9-]` → `-`,\n  collapsed, capped at 30 chars).\n- `pnpm console:dev --no-branch` disables the suffix (use the bare\n  `console.jitsu.localhost` host).\n\nIf the user explicitly asks you not to use a branch suffix, pass `--no-branch`.\n\n> Implementation note: `dev-scripts/src/bin/run-app.ts` loads root `.env` /\n> `.env.local`, computes the slug, and runs portless from a non-git scratch dir\n> with `--name <slug>` and a `bash -c \"cd <ws> && <cmd>\"` wrapper — sidesteps\n> portless's hardcoded dot-style worktree prefix.\n\n`portless` is a workspace devDependency — `pnpm install` is enough, no global\ninstall. First-run on a machine prompts once for `sudo` to bind port 443 and\ntrust the local CA.\n\n## Dev scripts\n\nThe `dev-scripts` package (`./dev-scripts`) hosts repo-wide developer tooling.\nInvoke via `pnpm dev <subcommand>`:\n\n```bash\npnpm dev                            # turbo run dev (start everything)\npnpm dev copy-db --src URL --dst URL   # rsync-style postgres copy ($ENV_VAR placeholders)\npnpm dev help\n```\n\nFor Go (run inside `/bulker`):\n\n```bash\ngo build ./...\ngo test ./...\n```\n\n## Git Workflow\n\nWhen you need to create branches, make commits, or open pull requests, read\n[CONTRIBUTING.md](CONTRIBUTING.md) first. No need to read it for code exploration —\nonly when interacting with git.\n\n### Referencing Linear issues\n\nWhen referencing a Linear issue in GitHub (PR descriptions, commit messages,\ncomments), use the bare issue id — `` `JITSU-67` `` — not a Linear URL or a\nmarkdown link to one.\n\nBefore opening a PR, try to work out which Linear issue the work relates to —\ncheck the branch name, search via the Linear MCP if it's available, or ask the\nuser with the question tool. If the PR clearly relates to an issue, prefix the\nPR title with the issue id and put the id in the body. It's fine if there's no\nissue — but offer to create one (when the Linear MCP is available).\n\n## Deployments\n\nThe console can be auto-deployed to **beta** on PR merge via the\n[`deploy-console-on-merge`](.github/workflows/deploy-console-on-merge.yml)\nworkflow: any PR carrying the **`deploy:console`** label triggers a beta console\ndeployment in `jitsu-cloud-infra` the moment it merges into `newjitsu`. This\nexists because the post-merge deploy step is easy to forget, so fixes sit\nundeployed for weeks (see JITSU-68). It's scoped to `console` only — its error\ntolerance is high (a brief outage doesn't drop data); `bulker` and `rotor` still\ndeploy manually and deliberately.\n\n**When you open a PR (including a draft), explicitly ask the user whether they\nwant the console to auto-deploy on merge.** If yes, add the `deploy:console`\nlabel to the PR (e.g. `gh pr edit <pr> --add-label deploy:console`). Only offer\nthis for PRs that actually touch the console; never add the label to `bulker` /\n`rotor` changes.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Jitsu — Agent Guidelines\n\n## Project Overview\n\nJitsu is an open-source data pipeline platform (self-hosted Segment alternative). It\ncollects events from websites/apps and routes them to data warehouses and other\ndestinations.\n\n## Repository Structure\n\nThis is a monorepo with two main technology stacks:\n\n### Go (`/bulker`)\n\nData ingestion engine for streaming events to warehouses.\n\n- `bulkerapp/` — main Bulker service\n- `ingest/` — HTTP ingest endpoint\n- `sync-controller/` — connector sync orchestration\n- `bulkerlib/` — core ingestion library\n- `connectors/` — warehouse connectors (ClickHouse, BigQuery, Redshift, Snowflake, S3,\n  GCS, etc.)\n\n### Node.js / TypeScript\n\n**Services (`/services`)**\n- `rotor/` — event routing, transformation, and function execution\n\n**Web apps (`/webapps`)**\n- `console/` — admin UI (Next.js)\n\n> The enterprise-edition billing/admin API now lives in\n> [`jitsucom/jitsu-cloud-billing`](https://github.com/jitsucom/jitsu-cloud-billing)\n> (deployed at `billing.jitsu.com`).\n\n**Libraries (`/libs`)**\n- `jitsu-js/` — browser JS SDK (`@jitsu/js`)\n- `jitsu-react/` — React bindings (`@jitsu/jitsu-react`)\n- `functions/` — functions runtime (`@jitsu/functions-lib`)\n- `juava/` — shared utilities\n\n**CLI (`/cli`)**\n- `jitsu-cli/` — developer CLI (`jitsu-cli` on npm)\n\n**Types (`/types`)**\n- `protocols/` — shared TypeScript protocols (`@jitsu/protocols`)\n\n## Tooling\n\n- **Node.js:** pnpm ≥10 (workspace manager), Turbo (build orchestration), Node.js ≥22\n- **Go:** Go 1.26 with Go workspaces (`go.work` at repo root)\n- **Frontend:** Next.js, React 18, TypeScript, Tailwind CSS\n- **Testing:** Jest (unit), Playwright (E2E), Go's built-in `testing`\n- **CI:** GitHub Actions (`.github/workflows/`)\n\n## Common Commands\n\n```bash\n# Install JS dependencies\npnpm install\n\n# Generate Prisma client + zod schemas (required once after a fresh checkout\n# or worktree). Skipping this leaves Turbopack panicking in\n# ModuleGraphImportTracer::get_traces because it can't render the missing-\n# module error for `prisma/schema`.\npnpm codegen\n\n# Build all JS packages\npnpm build:turbo\n\n# Type-check\npnpm typecheck:turbo\n\n# Run tests. Console tests include an integration project that needs Docker\n# (testcontainers: Postgres + ClickHouse); run only the pure tests with\n# `pnpm exec vitest run --project unit` from webapps/console.\n# Details: CONTRIBUTING.md \"Testing\".\npnpm test\n\n# Lint / format\npnpm lint\npnpm format\n\n# Start all dev services (hot-reload)\npnpm dev\n\n# Start only the console\npnpm console:dev\n```\n\n## Running the app for the user\n\nIf the user asks you to run the app (console / dev stack), use:\n\n- `pnpm console:dev` — only console\n- `pnpm ui:dev` — equivalent (turbo)\n\nThese go through [portless](https://portless.sh) and serve the app at\n`https://console.jitsu.localhost`.\n\n**Branch hosting.** The dev wrapper auto-detects the current git branch and\nsuffixes the dev host with it: `https://console-$BRANCH.jitsu.localhost`. This\navoids cookie / port collisions with whatever the user has running from another\nbranch.\n\n- The repo's default branch (resolved via `git rev-parse origin/HEAD`) gets no\n  suffix.\n- The branch name is sanitized for DNS (lowercased, non-`[a-z0-9-]` → `-`,\n  collapsed, capped at 30 chars).\n- `pnpm console:dev --no-branch` disables the suffix (use the bare\n  `console.jitsu.localhost` host).\n\nIf the user explicitly asks you not to use a branch suffix, pass `--no-branch`.\n\n> Implementation note: `dev-scripts/src/bin/run-app.ts` loads root `.env` /\n> `.env.local`, computes the slug, and runs portless from a non-git scratch dir\n> with `--name <slug>` and a `bash -c \"cd <ws> && <cmd>\"` wrapper — sidesteps\n> portless's hardcoded dot-style worktree prefix.\n\n`portless` is a workspace devDependency — `pnpm install` is enough, no global\ninstall. First-run on a machine prompts once for `sudo` to bind port 443 and\ntrust the local CA.\n\n## Dev scripts\n\nThe `dev-scripts` package (`./dev-scripts`) hosts repo-wide developer tooling.\nInvoke via `pnpm dev <subcommand>`:\n\n```bash\npnpm dev                            # turbo run dev (start everything)\npnpm dev copy-db --src URL --dst URL   # rsync-style postgres copy ($ENV_VAR placeholders)\npnpm dev help\n```\n\nFor Go (run inside `/bulker`):\n\n```bash\ngo build ./...\ngo test ./...\n```\n\n## Git Workflow\n\nWhen you need to create branches, make commits, or open pull requests, read\n[CONTRIBUTING.md](CONTRIBUTING.md) first. No need to read it for code exploration —\nonly when interacting with git.\n\n### Referencing Linear issues\n\nWhen referencing a Linear issue in GitHub (PR descriptions, commit messages,\ncomments), use the bare issue id — `` `JITSU-67` `` — not a Linear URL or a\nmarkdown link to one.\n\nBefore opening a PR, try to work out which Linear issue the work relates to —\ncheck the branch name, search via the Linear MCP if it's available, or ask the\nuser with the question tool. If the PR clearly relates to an issue, prefix the\nPR title with the issue id and put the id in the body. It's fine if there's no\nissue — but offer to create one (when the Linear MCP is available).\n\n## Deployments\n\nThe console can be auto-deployed to **beta** on PR merge via the\n[`deploy-console-on-merge`](.github/workflows/deploy-console-on-merge.yml)\nworkflow: any PR carrying the **`deploy:console`** label triggers a beta console\ndeployment in `jitsu-cloud-infra` the moment it merges into `newjitsu`. This\nexists because the post-merge deploy step is easy to forget, so fixes sit\nundeployed for weeks (see JITSU-68). It's scoped to `console` only — its error\ntolerance is high (a brief outage doesn't drop data); `bulker` and `rotor` still\ndeploy manually and deliberately.\n\n**When you open a PR (including a draft), explicitly ask the user whether they\nwant the console to auto-deploy on merge.** If yes, add the `deploy:console`\nlabel to the PR (e.g. `gh pr edit <pr> --add-label deploy:console`). Only offer\nthis for PRs that actually touch the console; never add the label to `bulker` /\n`rotor` changes.\n","category":"root","tokens":1501}]}