developer

TrackCTL

Config-as-code product analytics for PostHog - a free OSS CLI and SDK adoption wedge with deferred hosted team-governance monetization.

Competes with PostHog Terraform Provider

OSS/PLG validationdeveloper

Key metrics

Metrics being defined

Roadmap

287 items

Planned96

[packages/cli/src/codegen/typegen.ts:45] — Property names from config are interpolated as bare TypeScript identifiers without validation. Add a safe-identifier pattern check in `schema.ts` or use bracket notation in generated output.

[packages/cli/src/commands/deploy.ts:344-357] — Lockfile not persisted on mid-deploy API failure; crash after partial creates causes duplicate resources on next deploy. Write lockfile in the catch block before re-throwing.

[packages/cli/src/lockfile/index.ts:38] — `readLockfile` uses raw type assertion with no schema validation; corrupted lockfile causes runtime crash. Validate parsed YAML against a Zod schema or structural guard.

[packages/cli/src/lockfile/index.ts:47] — `computeChecksum` only sorts top-level keys; nested objects retain insertion order, making checksums non-deterministic. Use recursive stable-stringify.

[packages/cli/src/posthog/client.ts:75-83] — `listInsights`/`listDashboards` do not paginate; projects with >100 resources silently miss tagged items during recovery. Follow `data.next` until exhausted.

[packages/web/package.json:22] — Next.js `^14.2.0` is eligible for versions with known Server Actions and SSRF CVEs. Pin to `^14.2.25` minimum or upgrade to 15.x.

[packages/web/src/lib/launch-submission-route.ts:9] — In-memory rate-limit map grows without bound (no eviction). Add max-size cap or periodic pruning of entries older than the throttle window.

`/dashboard` is unavailable without authentication and reachable after GitHub OAuth in a configured environment.

`trackctl ask` works from the terminal with text output + terminal chart

`trackctl auth login` completes OAuth flow and stores credentials

`trackctl check` detects invalid YAML, missing env vars, broken references, and PostHog API connectivity issues

`trackctl connect posthog --method api-key --host ... --project-id ... --api-key-env ... --non-interactive` writes or patches the intended non-secret config.

`trackctl diff` shows created, updated, and unchanged resources correctly

`trackctl init --non-interactive --template saas --app-type saas` works without prompts

`trackctl init` generates a valid config file from each template (starter, full, empty)

`trackctl status` shows event flow data and flags configured-but-unseen events

`trackctl.lock` is written after deploy and maps config names to PostHog resource IDs

After Phase 16 completion, move Phase 17 from `tasks/roadmap.md` into `tasks/todo.md` and execute `$run` for hosted OAuth/BYOP connection onboarding.

AI responses are accurate (match what PostHog would show for the same query)

All commands support `--non-interactive` with equivalent CLI flags

All four insight types (trend, funnel, retention, paths) are translated to PostHog API format and render correctly in PostHog's UI

All phase acceptance criteria above are evidence-backed.

All phase tests pass

All phase tests pass.

An AI coding agent (Claude Code) can run the full flow: `init --non-interactive` → edit config → `deploy` without human interaction

Complete manual task: "Complete production or staging GitHub OAuth callback configuration and verify sign-in with a real GitHub account" _(blocks: Step 16.8 final launch auth smoke)_ — resolve before `$run` can complete Step 16.8.

Config validation catches missing required fields, invalid types, and broken references (insights → events, dashboards → insights)

Connection validation reports capability-level health in stable JSON for agents and CI.

Dashboard loads in under 2 seconds on a typical connection

Dashboard reflects changes after `trackctl deploy` without manual refresh

Dashboard renders all insight types from a deployed config (trends, funnels, retention, paths)

Date range picker changes the data range for all insights

Environment variables are resolved at runtime; missing vars produce clear error messages

Final launch evidence records remaining external gates: real PostHog proof, agent transcript proof, downstream CI proof, credential safety, first-run usability, and pricing evidence.

First required Codex run uses a real disposable PostHog Cloud project or records an explicit blocker in manual/record tasks.

Fixture starts with no TrackCTL config, generated artifact, or analytics instrumentation.

Homepage, quickstart, examples, docs/agents, pricing, pilot, and dashboard overview pass responsive and accessibility QA at supported desktop/mobile widths.

Hosted onboarding produces copyable CLI commands or config patches and does not create/update/delete PostHog analytics resources.

Hosted-vault references require workspace context and TrackCTL auth.

Insight cards show title, primary metric, and chart visualization

Insight detail view shows a full-page chart with property breakdown table

Launch funnel events are implemented without collecting secrets, raw config contents, raw emails from CLI, API keys, tokens, bearer headers, or event property values.

Legacy connection configs still work and emit clear migration warnings.

Local BYOP API-key mode works without TrackCTL login.

New BYOP connection descriptors validate without raw secrets in config, lockfiles, generated artifacts, logs, audit payloads, or public route content.

No regressions in previous phase tests

No regressions in previous phase tests.

Pilot and waitlist submissions work or intentionally route to documented fallback CTAs.

Pinned visualizations persist across sessions

Preflight blocks transcript runs when CLI init/check/deploy handoff readiness, ignored secret paths, or public agent docs are not ready.

Private raw transcript paths are ignored and no secret-bearing raw evidence is committed.

Public claims remain Codex-scoped unless Claude Code and Cursor compatibility runs are later completed.

Public examples, machine-readable docs, and route content pass redaction/build checks.

Redacted summary passes launch redaction checks before being linked from `tasks/launch-evidence.md`.

Responsive desktop/tablet/mobile layouts are verified for dashboard and alert workflows. Desktop smoke was completed for project list and dashboard view; tablet/mobile screenshots and deeper GUI route inspection remain release evidence.

Responsive layout works on desktop, tablet, and mobile

Running `trackctl deploy` a second time with no config changes produces zero PostHog mutations

Running `trackctl deploy` after modifying an insight in the config updates only that insight in PostHog

Running `trackctl deploy` with a valid config file creates dashboards and insights in PostHog Cloud

Search/public pages render without authentication.

Suggested question chips generate valid queries

Summary template captures scenario metadata, preflight status, outcome, commands, rubric, deploy handoff, interventions, redaction, cleanup, and claim boundary.

Tests cover schema compatibility, secret redaction, CLI flow, connection health JSON, and hosted handoff boundaries.

TypeScript types generated from events section match the config and provide compile-time type safety

User can ask "How is my signup funnel performing?" and get a funnel visualization with conversion rates

User can ask "Show me daily active users for the last 30 days" and get a trend chart

User can ask "What changed this week?" and get a summary of metric changes

Done191

`@trackctl/sdk` exports `createTrackctlClient`, `TrackCTLValidationError`, and public SDK types.

`/` is the public marketing homepage and links to quickstart, examples, docs, pricing, pilot, and future dashboard sign-in.

`/alerts` shows YAML-defined alert evaluations, invalid configs, delivery outcomes, filters, stale-activity guidance, and deep links to dashboard/insight views.

`/dashboard` is unavailable without authentication and reachable after GitHub OAuth in a configured environment.

`/dashboard` redirects unauthenticated users to GitHub sign-in and preserves intended destination.

`/docs` and `/docs/agents` include copyable Codex, Claude Code, Cursor, and generic agent instructions.

`/examples` includes minimal config, SaaS config, CI JSON, PR summary, deploy handoff, GitHub Actions, and generic CI examples.

`/llms.txt` and `/agents.md` expose machine-readable agent guidance, safe boundaries, commands, and docs links.

`/pilot` supports Team Governance and BYOP Enterprise pilot intent capture without requiring auth.

`/pricing` reflects Free OSS, Team Governance pilot, BYOP Enterprise pilot, and managed hosting waitlist without fixed managed-hosting pricing.

`$reconcile-dev-docs fix tasks` - reconciled `specs/hosted-oauth-and-byop-connection-onboarding.md` and `specs/agent-adoption-evidence-harness.md` into `tasks/roadmap.md` as Phases 17 and 18 on 2026-05-15.

`$run` - execute Phase 16 Step 16.8 after blockers because `tasks/todo.md` has Steps 16.1-16.7 checked and Step 16.8 unchecked.

`identify()` and `reset()` delegate to the configured PostHog-compatible adapter.

`specs/ui-*.md` written with implementation-ready screen-level detail

`track()` provides compile-time event-name and property typing when supplied generated `TrackCTLEvents`.

`trackctl ask` works from the terminal with text output + terminal chart

`trackctl auth login` completes OAuth flow and stores credentials

`trackctl auth login` uses a browser OAuth/token-exchange abstraction and stores a scoped CLI token with user-only file permissions.

`trackctl auth status` reports actor/workspace/token state, and `trackctl auth logout` removes local CLI token state.

`trackctl check` detects invalid YAML, missing env vars, broken references, and PostHog API connectivity issues

`trackctl dashboard overview` renders all dashboard insights in a terminal grid

`trackctl deploy`, `trackctl check`, `trackctl dashboard`, `trackctl insights`, and `trackctl watch --once` print relevant local URLs when enough context exists.

`trackctl diff` shows created, updated, and unchanged resources correctly

`trackctl init --non-interactive --template saas --app-type saas` works without prompts

`trackctl init` generates a valid config file from each template (starter, full, empty)

`trackctl insights daily_active_users` renders a trend chart in the terminal

`trackctl insights signup_funnel` renders a funnel visualization in the terminal

`trackctl status` shows event flow data and flags configured-but-unseen events

`trackctl watch` displays periodic metric summaries in the terminal

`validation: "strict"` throws `TrackCTLValidationError` and does not send invalid events.

`viewer` cannot deploy; `developer`, `admin`, and `owner` can deploy.

A repository can run TrackCTL validation in CI using documented template configuration.

AI responses are accurate (match what PostHog would show for the same query)

Alert configuration in YAML is validated on deploy

Alert triggers when a configured threshold is crossed (e.g., conversion < 10%)

Alerts are delivered to configured channels (terminal, Slack webhook)

All 5 variations evaluated with documented scores against criteria

All commands support `--non-interactive` with equivalent CLI flags

All phase tests pass

All phase tests pass (195 tests)

All terminal commands support `--json` flag for machine-readable output (agent compatibility)

An AI coding agent (Claude Code) can run the full flow: `init --non-interactive` → edit config → `deploy` without human interaction

Audit events are emitted for successful deploys, denied deploys, invalid configs, missing/expired tokens, and PostHog API failures.

Audit records store metadata/checksums by default and never include raw API keys, OAuth tokens, or environment variable values.

Auth/session helpers and dashboard access control are covered by tests.

Authenticated users can reach `/dashboard` and sign out.

Build/typecheck proves `@trackctl/sdk` does not depend on CLI-only modules or Node filesystem APIs.

BYOP PostHog deploys are gated when `trackctl.workspace` is declared.

CI output includes stable JSON artifacts for agents and platform automation.

CI/service-account auth model is documented and covered by tests.

CLI codegen writes valid TypeScript containing `TrackCTLEvents` and `trackctlSchema`.

CLI dashboard and insights workflows provide human-readable output, JSON output, and matching web deep links for agent handoff.

Config history allows viewing and restoring previous versions

Config parsing accepts optional `trackctl.workspace`, `trackctl.project`, and `trackctl.environment` fields.

Custom event names are validated as snake_case config keys, while PostHog built-ins remain valid in insight definitions.

Dashboard copy does not imply repository access, Google OAuth, automated production deploys, or managed hosting availability.

Dashboard overview renders account/team overview, connected PostHog workspaces, user projects, recent CI artifacts, authorization/audit status, and deploy handoff activity.

Dashboard renders all insight types from a deployed config (trends, funnels, retention, paths)

Dashboard view renders configured insights in YAML order with date range controls, alert/activity summary, provenance access, and no browser-only create/edit/delete state.

Date range picker changes the data range for all insights

Deploy button shows a diff of changes before deploying

Docs show a complete browser instrumentation path from generated artifact to `analytics.track(...)`.

Editing YAML in the left pane updates the dashboard preview in the right pane in under 1 second

Empty states explain how to connect PostHog workspaces, run CI checks, and return to public docs.

Existing CLI deploy/check/typegen tests are updated without regressing current behavior.

Final direction selected with rationale documented

Final launch evidence records remaining external gates: real PostHog proof, agent transcript proof, downstream CI proof, credential safety, first-run usability, and pricing evidence.

Generated output contains no secrets or connection/workspace settings.

Generated runtime schema is accepted by `createTrackctlClient` and enables development warnings.

GitHub OAuth uses identity/email scope only and rejects callback state mismatches.

Homepage, quickstart, examples, docs/agents, pricing, pilot, and dashboard overview pass responsive and accessibility QA at supported desktop/mobile widths.

Human and JSON CLI output expose authorization and audit status for agents and CI.

Insight cards show title, primary metric, and chart visualization

Insight detail renders full chart/detail state, source/query/provenance data, equivalent CLI commands, related alert activity, and partial-failure diagnostics.

Insight detail view shows a full-page chart with property breakdown table

Launch funnel events are implemented without collecting secrets, raw config contents, raw emails from CLI, API keys, tokens, bearer headers, or event property values.

Loading, empty, invalid config, missing lockfile, missing credentials, PostHog unavailable, partial query failure, invalid alert, stale data, and unsupported insight states are handled without hiding config inventory.

Local OSS configs without `trackctl.workspace` continue to deploy without TrackCTL control-plane enforcement.

Lock-in checklist from UX variations spec completed

Minimal web viewer serves a read-only dashboard at a shareable URL

No regressions in previous phase tests

Phase 9 documentation updates README/CLI help/config references for the final dashboard, CLI handoff, provenance, and alert workflows.

Pilot and waitlist submissions work or intentionally route to documented fallback CTAs.

Pinned visualizations persist across sessions

PR review output reports config validity, drift status, workspace authorization status, and deploy handoff instructions.

Project dashboard list renders configured dashboards, health/provenance status, and recovery states from config/lockfile inputs.

Public docs do not instruct agents or CI to run browser login or automatic production deploys.

Public examples are covered by contract/redaction tests and contain no raw API keys, bearer tokens, OAuth tokens, or service-account secrets.

Public examples, machine-readable docs, and route content pass redaction/build checks.

Public pages include canonical metadata and appropriate JSON-LD whose text matches visible page content.

Required public routes render crawlable, answer-shaped content matching `specs/public-marketing-and-launch-routes.md`.

Responsive layout works on desktop, tablet, and mobile

Runtime validation defaults to `warn` in development and `off` in production.

Search/public pages render without authentication.

Source-of-truth contract is preserved: production analytics state comes from `trackctl.config.yaml` plus `trackctl.lock`; browser/AI outputs are not deployable unless file-backed, patch-backed, or PR-ready.

Split pane is resizable and defaults to 50/50

Step 16.1: Write failing tests for privacy-safe launch instrumentation contracts

Step 16.2: Write failing tests for pilot/waitlist submissions, redaction checks, and route access

Step 16.3: Implement privacy-safe launch event helpers and wire public/auth surfaces

Step 16.4: Add pilot and waitlist submission endpoints with launch abuse controls

Step 16.5: Add redaction/build checks for public launch content

Step 16.6: Add automated launch accessibility and responsive smoke coverage

Step 16.7: Capture final launch evidence and run review lanes

Step 16.8: Run launch validation, final auth/public smoke, and full regression

Suggested question chips generate valid queries

Tablet view switches to tabbed editor/preview

Terminal output is readable in standard 80-column and wide terminals

Tests cover required/optional properties, no-property events, unsupported type fallback or rejection, invalid event names, and configurable output path.

The generated artifact compiles under strict TypeScript settings.

The SDK has focused unit tests for valid tracking, unknown events, missing required properties, primitive mismatches, all validation modes, and adapter delegation.

The workflow does not require browser interaction during CI.

TypeScript types generated from events section match the config and provide compile-time type safety

Unknown extra properties remain allowed by default.

User can ask "How is my signup funnel performing?" and get a funnel visualization with conversion rates

User can ask "Show me daily active users for the last 30 days" and get a trend chart

User can ask "What changed this week?" and get a summary of metric changes

View mode shows full-screen dashboard (like V2)

Web dashboard shows activity feed with recent metric changes and alerts

Web dashboard supports interactive drill-down (date range, breakdowns, comparisons)

Weekly email digest summarizes key metrics and changes

Workspace-backed configs require a valid CLI token before deploy.

YAML editor provides syntax highlighting and validation errors inline