feat(scripts): scaffold new resources from OpenAPI + drift-check existing ones

[timgl]

Summary

Two devtools, both driven by the PostHog OpenAPI spec (../posthog/frontend/tmp/openapi.json):

• pnpm scaffold-resource --name <foo> --path <list-endpoint> --key-field <field> generates a new resource end-to-end: client.ts (deep Zod schema with all transitive component refs inlined via openapi-zod-client, plus CRUD wrappers), sdk.ts, pipeline.ts (skeleton with TODO(human) markers over the per-resource judgment calls — hash projection, identity mechanism, payload, validation, display), pipeline.test.ts, index.ts. Wires the resource into src/resources/index.ts, src/index.ts, scripts/lib/registry.ts, and flips the matching row in docs/resources.md.
• pnpm check-resources walks the resource registry, compares each ServerXSchema (or type ServerX = {…} fallback for the older resources) against the current OpenAPI component, and reports added / removed / type-mismatched fields. readOnly server-set fields hidden by default; --all to include. Exits non-zero on drift so it can gate CI.

Skill updates (add-resource, add-singleton-resource) document the new entry point and the TODO(human) markers that still require human judgment.

Why the openapi-zod-client path

A homegrown OpenAPI-to-Zod converter would punt on $ref resolution, allOf merging, and recursive types — the cohort schema alone has 5 levels of $ref cycles. openapi-zod-client handles all of that. The output is 1.6MB for the full spec, so we don't commit it: the extractor (scripts/lib/extract-zod.ts) runs the CLI to a tmp file (cached by openapi mtime), parses the prettier-formatted output into top-level declarations, transitively closes from a single component, topo-sorts, and inlines only what each resource needs.

Two rewrites make the output satisfy strict Zod 4:

• const X: z.ZodType<X> = z.lazy(...) → const X = (z.lazy(...)) as z.ZodType<X>
• z.discriminatedUnion("type", [...]) → z.union([...])

Test plan

• pnpm typecheck passes (pre-existing acceptance.ts error is unrelated to this PR).
• pnpm test — all 59 unit tests pass.
• pnpm check-resources against the 4 shipped resources surfaces 27 added user fields and 1 removed (data_freshness_seconds on endpoint).
• Smoke test: scaffold cohort end-to-end. ServerCohortSchema.filters is CohortFilters.nullish() with the full recursive CohortFilterGroup; created_by is UserBasic; cohort_type is z.union([CohortTypeEnum, BlankEnum, NullEnum]). Typechecks under strict Zod 4. Reverted before commit.
• Reviewer: spot-check the generated client.ts for one resource by running pnpm scaffold-resource --name cohort --path /api/projects/{project_id}/cohorts/ --key-field name against your local ../posthog/frontend/tmp/openapi.json.

---

Created with PostHog Code