Unused @workos/oagen transitive dependency causes installation failures

[mjvmiller]

Summary

The CLI depends on @workos/openapi-spec, but only uses its exported
OpenAPI YAML file. @workos/openapi-spec includes @workos/oagen as a
runtime dependency, which brings an unused tree-sitter toolchain into
CLI installations.

This dependency chain causes several installation problems:

1. @workos/oagen requires Node.js >=24.10.0, while the CLI declares
   support for Node.js >=22.11.
2. tree-sitter-kotlin is resolved from a GitHub tarball, which pnpm
   can reject as an exotic transitive dependency.
3. On platforms without a compatible prebuilt tree-sitter binary,
   tree-sitter@0.21.1 fails to compile against Node.js 24 because it
   requests C++17 while the Node.js 24 V8 headers require C++20.

The heavy transitive dependency and GitHub-hosted Kotlin parser were
previously identified during #178:
#178 (comment)

Environment

The native compilation failure was independently reproduced with:

• Node.js 24.16.0
• pnpm 10.34.4
• Linux ARM64
• tree-sitter 0.21.1

Steps to reproduce

Exotic transitive dependency

1. Perform a dependency resolution using the repository's pinned pnpm
   version.
2. Observe that pnpm may block the transitive tree-sitter-kotlin
   GitHub tarball.
3. Allowing the resolution requires weakening the default
   blockExoticSubdeps protection.

Native tree-sitter build

1. Install on Linux ARM64 with Node.js 24.

2. Permit the tree-sitter install script to run.

3. Because tree-sitter@0.21.1 does not include a Linux ARM64 prebuild,
   it falls back to node-gyp.

4. The compilation fails with:

   v8config.h:13:2: error: "C++20 or later required."
   

tree-sitter@0.21.1 explicitly passes -std=c++17 in its
binding.gyp, conflicting with the Node.js 24 V8 headers.

Expected behavior

Installing the CLI should succeed throughout its declared Node.js
support range without:

• disabling pnpm supply-chain protections,
• accepting an incompatible Node.js engine requirement, or
• compiling native parser dependencies that the CLI does not use.

Root cause

The relevant dependency chain is:

workos
  → @workos/openapi-spec
    → @workos/oagen
      → tree-sitter@0.21.1
      → tree-sitter-kotlin (GitHub tarball)
      → other native language parsers

The CLI's only use of @workos/openapi-spec is resolving and reading
@workos/openapi-spec/spec in src/commands/api/catalog.ts.
@workos/oagen is not used by the CLI at runtime.

Possible resolution

Remove the unused oagen/tree-sitter dependency chain from CLI
installations while preserving access to the OpenAPI catalog.

One option is to bundle the OpenAPI YAML as a CLI runtime asset and
remove @workos/openapi-spec from the CLI's production dependencies.

An upstream alternative would be for @workos/openapi-spec to avoid
publishing @workos/oagen as a runtime dependency when consumers only
use the generated specification.