feat(cli): let a generator image declare that it needs the raw API specs

[ATechAdventurer]

Description

Local generation decides whether to bundle and mount the pre-processed raw API specs from GENERATORS_WANTING_SPECS — an exact-string allowlist of generator names, currently one entry.

That cannot describe a generator image published under an existing Fern generator name in a different registry, which is exactly how the private registry setup documented for self-hosting works:

- image:
    name: fern-python-sdk
    registry: ghcr.io/your-org
  version: 4.0.0

The generator name is identical whether the image is Fern's or the org's own. Only the image can say what it needs.

What changed

• getImageLabels added to docker-utils. The package had no image inspection at all — just runDocker.ts and buildContainerEnvVars.ts.
• com.postman.sdk-gen.adapter.wants-raw-specs is read off the resolved image, alongside the existing name check. An image can opt in without a CLI release.
• resolveGeneratorImage extracted so the capability check and the container execution resolve the same reference, instead of duplicating the containerImage-or-name expression in two places.

Generators without the label are unaffected, and the existing first-party allowlist entry keeps working unchanged.

Best-effort by construction

This now runs on every local generation, so it must never be the reason a run fails. A generator with no labels, an image that cannot be pulled, or an unavailable container runtime all fall back to the previous behaviour.

One detail worth flagging for review: Docker reports an unlabelled image as JSON null, not {}. I found that by building a control image and inspecting it, and the parser handles it explicitly. Verified across four shapes — labelled image, unlabelled image, malformed output, and non-string label values.

The label read pulls the image if it is absent. That is not an extra pull: local generation is about to pull and run this exact image, so it is the same pull moved earlier.

Testing

• 10 unit tests covering the label predicate, image resolution with and without a custom registry, and the existing allowlist behaviour.
• The package's compile-error count is unchanged from baseline — 243 either way, all from uncompiled workspace dependencies in my environment.
• biome check clean.

I was not able to run the full monorepo build locally, so CI is the real check on integration.

Context

This unblocks a self-hosted SDK generation adapter that generates from the API spec rather than the Fern IR — without the raw-spec mount it has no input at all. Related work lives outside this repo.

Draft while the consuming image is still in review on our side.