Changelog

Add defineExtension to define a plugin, an adapter, or a parser. definePlugin, defineParser, and createAdapter still work but are deprecated. (#4258)

export const pluginZod = defineExtension<PluginZod>({
  kind: 'plugin',
  meta: { name: 'plugin-zod' },
  setup(options, kubb) {
    kubb.addGenerator(zodGenerator)
    return options
  },
})

Visit schemas inside a tuple's rest and inside patternProperties, so refs there are collected, transformed by macros, and imported in generated files.

• transform, collect and collectImportedRefNames now reach rest and patternProperties on a SchemaNode.
• createInput() gives every node its own schemas, operations and meta objects instead of sharing one default. (#4188, 62485c5)

Run output.format, output.lint and output.postGenerate from Kubb.generate() by default, so every host gets the same passes.

• Adds runOutputPasses and runHook, the one implementation of the format, lint and post-generate steps. runHook spawns the command with node:child_process, in the config root, and emits kubb:hook:start, kubb:hook:line and kubb:hook:end itself.
• generate({ processOutput }) still replaces the passes when a host needs to; its context now also carries hooks and signal.
• unplugin-kubb and kubb mcp start honoring output.format, output.lint and output.postGenerate, which they ignored before. (#4196, 50617dd)

Run output.format, output.lint and output.postGenerate commands through tinyexec, which resolves Windows command shims and the project's node_modules/.bin.

Formatter and linter detection for 'auto' also finds a tool installed only in node_modules/.bin under config.root, the folder the tool then runs from. (#4218, 0fb79d5)

Fix a batch of small bugs:

• @kubb/adapter-oas: resolve local $ref pointers per RFC 6901, so #/paths/~1pets/get and keys with ~ or an encoded / resolve. On Windows, an absolute input such as C:\specs\api.yaml no longer counts as a URL, so a missing file now reports KUBB_INPUT_NOT_FOUND instead of failing later.
• @kubb/mcp: reload kubb.config.ts on every tool call. The server cached the first load, so edits only showed up after a restart.
• @kubb/cli: CI=false and CI=0 no longer count as running in CI, and kubb init detects Bun from bun.lock as well as bun.lockb.
• @kubb/studio: a failing format, lint or postGenerate command reports one kubb:error instead of two.
• @kubb/renderer-jsx: fix the meta prop type on <kubb-file>, which referenced FileNode without importing it. (#4175, 11cd291)

Add kubb studio start and stop for a background connection per project. status reports its connection state and log path, and logout stops it before removing credentials. Rejected tokens stop the worker until you log in again.

Use one shared connection loop for the CLI and Docker agent. Abort pending registration on shutdown and wait for canceled generation cleanup before reconnecting. (#4128, 5d9151c)

kubb studio snapshot runs its snapshot job on the agent process it connected, so two overlapping pipelines of the same CI agent never build each other's checkout.

• createJob accepts instanceId, and sends it on POST /api/jobs. A Studio that does not know the field ignores it.
• createClient accepts an instanceId, so a host that queues its own jobs can name its process. Without one, each client still gets a random id. (#4119, 955b6b5)

Report which files a Studio run added, changed, or removed, and serve the previous run's contents so Studio can show a diff.

• GenerateResult.changes maps each path that differs from the session's previous successful run to added, changed, or removed. Unchanged files are left out, and the field is absent on a session's first run.
• readFiles takes revision: 'previous' to read the run before the latest one, including files the latest run removed. The previous run is read into memory before the next run starts, so a session that writes to disk can still be diffed after its files are overwritten.
• A failed run leaves the last successful run as the one to compare against.
• FileChange is exported from @kubb/studio. (#4086, 300186d)

Carry an agent's organization slug through pairing and connecting, so a host can log and trace it alongside the agent's own slug.

PairingResult.agent and the studio:connected hook context gain an optional organizationSlug, absent for a sandbox or global agent, which has none. studio:connected also gains agentSlug, refreshed on every connect so a rename in Studio shows up without a re-pair. Both fields are additive: a host built against an older type just ignores them. (#4066, eb5fa50)

Fix generation and heartbeat lifecycle bugs left over from the Cap'n Web RPC cutover:

• A dropped Studio connection now cancels the in-flight generation instead of letting it finish unwatched.
• Two startGeneration calls arriving in the same tick can no longer both start a run.
• A heartbeat ping that never settles (a half-open socket) now closes the session instead of hanging it indefinitely.
• Removed an unreachable error path left over from the old JSON transport. (#4061, f880342)

Stop holding a whole generation's output in memory for the life of a Studio session.

studio:files and studio:snapshot used to read every generated file into one Record<string, string> the moment a run finished, and kept that map alive until the next generation. A run producing gigabytes of source meant the agent process held gigabytes in RAM, whether or not anyone ever opened a file or took a snapshot.

The agent now keeps the live Storage a run wrote through, plus the list of paths it produced, and reads a file's content back from Storage only when studio:files or studio:snapshot actually asks for it. A path outside that list is refused before it reaches storage, so this changes nothing about what a session can read, only when the read happens. (#4059, 351e3c9)

Stop streaming generated source over the agent WebSocket by default. Reading it now needs --allow-read (or KUBB_AGENT_ALLOW_READ=true), matching the other four Studio permissions.

Every kubb studio session used to send the full text of every generated file on kubb:generation:end, whether or not anyone in the browser opened one. A spec producing hundreds of files could put megabytes of source on the wire per run, and nothing gated it: allowWrite, allowConfigEdit, allowInput, and allowExec all cover what Studio may do to a project, but reading generated output back was never one of the four.

kubb:generation:end now carries nothing. Everything it used to carry moved somewhere better:

• The list of generated files is on kubb:build:end, which already carried every path and fires earlier in a run. Its paths are now relative to the agent's root, matching every other path on the wire, where they used to be absolute.
• The file count is on kubb:generation:summary, which already had it and was always the accurate number (kubb:generation:end's old count went to 0 for a CI connection).
• File contents are fetched on demand with a new studio:files command, which the browser sends when someone opens a file. The agent replies with agent:files, refusing unless allowRead was granted.
• Peer dependency metadata, previously sent on every generation and round-tripped straight back into studio:snapshot, now travels with the agent:snapshot reply instead, since the CI snapshot flow is its only consumer. studio:snapshot takes bundledDependencies in place of peerDependencies.

--allow-read is off by default everywhere, like every other permission. A sandbox or global agent is always granted it, since its output is the only thing it has:

kubb studio --allow-read   # show generated files in the browser

An older Studio instance talking to this version of the agent (or the reverse) can fail: a snapshot build errors because bundledDependencies and peerDependencies no longer line up between the two ends, and a plain session shows an empty editor with no file contents. Point --url at a Studio build that matches this version.

The in-process kubb:generation:end hook (kubb.hooks.hook('kubb:generation:end', ...), or a plugin's own listener) is unaffected. It still carries config, storage, diagnostics, status, hrStart, and filesCreated, exactly as before. Only the payload this event sends over the Studio WebSocket changed. (#4059, 351e3c9)

Back off while polling a Studio job, so a long snapshot stops exhausting the API key rate limit.

waitForJob polled GET /api/jobs/{id} every second, starting the instant the job was queued. The CLI's kubb studio snapshot waits up to 10 minutes by default, which is up to 600 requests against a budget of 100 per window. The window only resets after a whole window with no request, so a one-second poll could never escape the limit once it hit it, and every later call failed until the run gave up. The budget belongs to the organization key, so concurrent CI runs share it.

The first poll now waits two seconds, since a job runs a generation and packs a tarball before it can possibly finish. From there the interval doubles to a 30 second ceiling, bringing a 10 minute wait down from 600 requests to 22. A 429 pushes the next poll out by the tryAgainIn Studio returns and never pulls it back in, and retry: false stops ofetch retrying a 429 with no delay. (#4057, 52637b6)

The agent runtime now packs snapshot tarballs itself. A new studio:snapshot command builds the npm-installable tarball from the session's most recent generation and uploads it to a Studio endpoint, instead of Studio building the tarball on its own server. A snapshot request with no prior generation is refused.

A CI connection also keeps generated files off every kubb:generation:end reply, since it has no UI to render them in. kubb studio snapshot and the Studio UI's "Create snapshot" button keep working as before, now backed by this protocol message. (#4052, 19e9c2c)

The background reconnect loop's "Retrying connection" and "Reconnect attempt failed" lines, and the teardown notice disconnect() prints on the way out, now go through console.error instead of console.info/console.log, and only print when a host passes a logLevel above silent to StudioSession. Previously they always printed unconditionally, which a CI runner that only streams a child process's stderr live (such as kubb-labs/action) never surfaces, and which contradicted installLogger's own "prints nothing when left out" default.

kubb studio and kubb studio snapshot now pass their --log-level flag through, so these lines respect the same flag as the rest of the command's output. (#4052, 19e9c2c)

CLI flags are now kebab-case, matching the convention used by most command-line tools.

• kubb generate --log-level and kubb generate --dry-run replace --logLevel and --dryRun.
• kubb studio --allow-write, --allow-config-edit, --allow-input, and --allow-exec replace --allowWrite, --allowConfigEdit, --allowInput, and --allowExec.
• kubb init --dry-run replaces --dryRun.

To upgrade, replace any camelCase flag in a script or CI job with its kebab-case name. The CLI now rejects an unrecognized flag with an error instead of silently ignoring it.

# Before
kubb studio --allowWrite --allowExec

# After
kubb studio --allow-write --allow-exec
``` ([#4046](https://github.com/kubb-labs/kubb/pull/4046), [`e5ecdda`](https://github.com/kubb-labs/kubb/commit/e5ecdda06acbd3b99c2716384b2a8ac56eedfad8))

Renamed the studio:ping heartbeat reply to studio:pong, matching the ping/pong pattern agent:ping already implies (StudioPingMessage is now StudioPongMessage, isStudioPingMessage is now isStudioPongMessage). This is a wire-protocol change: an agent running an older @kubb/studio and a Studio running the new one won't recognize each other's heartbeat reply. Update both sides together.

Also documented the full studio:/agent: message table in packages/studio/src/protocol/index.ts, including why studio:generate has no dedicated agent:generate reply (its result rides the agent:data/kubb:generation:end event stream instead, unlike studio:save/studio:snapshot, which reply directly). (#4053, 76dd283)

Add kubb studio snapshot to generate and publish a Kubb Studio snapshot from any CI, not only GitHub Actions.

• Registers or reuses a CI agent, connects it, queues a snapshot job, and polls until the tarball is ready.
• Reads the organization CI API key from --token or KUBB_TOKEN.
• Detects the calling CI (GitHub Actions, GitLab CI, Bitbucket Pipelines, CircleCI) to reuse one agent per pull or merge request, or takes an explicit --id on any other CI.
• Prints a summary, or one JSON object with --json for a script to read.
• @kubb/studio now also exports createAgent and machineTokenFrom, so a host can register a CI agent without hand-rolling the request.

KUBB_TOKEN=$KUBB_TOKEN kubb studio snapshot --json
``` ([#4038](https://github.com/kubb-labs/kubb/pull/4038), [`4cd9f5e`](https://github.com/kubb-labs/kubb/commit/4cd9f5e311e5dc6edb14287c13db0a5466b4e892))

Add a studio:ready acknowledgement so a host can tell "the socket is open" apart from "Studio has registered this connection and will dispatch jobs to it".

A connected socket announces itself with agent:connect but never waited for a reply, so a job could arrive at Studio moments before the agent was actually registered. StudioSession now waits up to 10 seconds for studio:ready after sending that handshake and fires a new studio:ready hook once it lands, warning instead of failing if an older Studio never sends one. kubb studio prints ✓ Ready to receive jobs once it does. (#4028, b93eb64)

Report the package a plugin ships from, so plugin-ts reaches Studio as @kubb/plugin-ts while a third-party plugin keeps its own name.

The connect payload scoped every plugin name under @kubb/, which claimed a third-party plugin as one of Kubb's. It now follows the same rule the dependency check already used. (#4026, 628c98b)

Trim @kubb/studio's public API to what the kubb studio CLI command and the Docker agent actually use.

• Removed the unused hook context types StudioCommandStartContext, StudioCommandEndContext, StudioConnectingContext, StudioDisconnectedContext, StudioErrorContext, and StudioWarnContext from the package's root export. StudioConnectedContext stays exported. Hook payloads for studio:connecting, studio:command:start, studio:command:end, studio:disconnected, studio:warn, and studio:error still type-check through Hookable<KubbHooks>['hook'], since the underlying types are still declared, just no longer importable by name.
• Removed ConnectionOutcome and TokenRejection from the root export. Both stay inferable from runConnection's return value and onTokenRejected callback.

Neither the CLI nor the Docker agent imports any of these by name, so this does not change their behavior. A consumer that did import one of them by name gets the same type through inference at the call site instead, such as runConnection's return value or a hooks.hook('studio:warn', ...) callback's parameter. (#4012, 109abe8)

Let dateType set date-time, date, and time independently, instead of one value driving all three

Pass an object to represent timestamps as a JS Date while keeping date-only and time-only fields as strings, since Date cannot round-trip those without inventing a timezone.

adapterOas({
  dateType: {
    dateTime: 'date',
    date: 'string',
    time: 'string',
  },
})

The scalar form (dateType: 'date') still applies one value to all three formats. (#3957, 9fca8e9)

Move unplugin-kubb past its squatted npm version range.

Versions 5.0.1 through 5.0.30 were already published on npm from unplugin-kubb's pre-monorepo history and depend on kubb v4, so the package's version was set directly to 5.0.31 to clear that range. This changeset picks up from that 5.0.31 baseline and puts unplugin-kubb back through the normal release process, independent of kubb and @kubb/*. (#3940, b45071e)

Fix Url.toPath producing route masks that path-to-regexp (used by MSW/Express) rejects or misparses:

• A parameter name starting with a character outside [A-Za-z0-9_] (e.g. {$id}) now sanitizes to a safe capture name instead of keeping the disallowed character.
• Distinct parameter names that normalize to the same identifier (e.g. {group-id} and {group.id}) are now deduplicated with an incrementing suffix (groupId, groupId2) instead of producing two identically named captures. (#3922, 56a072c)