@kubb/studio 5.6.0 → 5.6.2

package/README.md

@@ -24,9 +24,9 @@
 
 Kubb Studio client runtime.
 
-Connects a Kubb project to [Kubb Studio](https://kubb.studio) through typed Cap'n Web RPC over an
-authenticated WebSocket. It backs both front ends: the `kubb studio` CLI command and the
-`kubblabs/kubb-agent` Docker image. Browser clients use Studio’s HTTP/SSE API, not this socket.
+Connects a Kubb project to [Kubb Studio](https://kubb.studio) through typed Cap'n Web RPC over one
+authenticated WebSocket, and publishes snapshots from CI in one HTTP request. It backs the `kubb studio`
+CLI command and the `kubblabs/kubb-agent` Docker image.
 
 Most people never install this directly. Reach for `kubb studio` instead, which pairs your machine
 and runs this for you.
@@ -40,63 +40,63 @@ npm install @kubb/studio
 ## Usage
 
 ```typescript
-import { createFileStorage, runConnection, setStorage } from '@kubb/studio'
-
-// The machine identity lives in this storage, so install it before anything pairs or connects.
-setStorage(createFileStorage('./.kubb-cache'))
-
-const outcome = await runConnection({
-  credentials: { token: process.env.KUBB_AGENT_TOKEN! },
-  clientOptions: () => ({
-    configPath: 'kubb.config.ts',
-    version: '1.0.0',
-    loadConfig: () => loadMyKubbConfig(),
-    installLogger: (hooks) => {
-      hooks.hook('studio:connected', ({ url }) => console.log(`Connected to ${url}`))
-      hooks.hook('studio:reconnecting', ({ delayMs }) => console.log(`Retrying in ${delayMs}ms`))
-      hooks.hook('studio:warn', ({ message }) => console.warn(message))
-      hooks.hook('studio:error', ({ error }) => console.error(error.message))
-    },
-  }),
-  signal: shutdown.signal,
-  // Return a new credential to reconnect with, `null` to stop, or throw to fail the run.
-  onTokenRejected: async () => null,
-})
+import { Hookable, type KubbHooks } from '@kubb/core'
+import { connectAgent, InvalidAgentTokenError, pairAgent } from '@kubb/studio'
+
+const hooks = new Hookable<KubbHooks>()
+hooks.hook('studio:connected', ({ agentSlug }) => console.log(`Connected as ${agentSlug}`))
+hooks.hook('studio:warn', ({ message }) => console.warn(message))
+
+let token = await readStoredToken()
+
+for (;;) {
+  token ??= (await pairAgent({ type: 'cli', name: 'my-project', hostname, machineId, onCode })).token
+  try {
+    // Resolves on shutdown, rejects when Studio refuses the token.
+    await connectAgent({ token, configPath: 'kubb.config.ts', loadConfig, version: '1.0.0', hooks, signal })
+    break
+  } catch (error) {
+    if (!(error instanceof InvalidAgentTokenError)) throw error
+    token = undefined
+  }
+}
 ```
 
-The runtime discovers nothing on its own: the host injects the config loader, the storage, and its
-own version. That is what lets one runtime serve a CLI running in a developer's project and a
-container running a fixed plugin set.
+The runtime discovers nothing on its own. The host passes the token, the config loader, its own
+version, and a hook emitter, and keeps its own credentials. That is what lets one runtime serve a CLI
+running in a developer's project and a container running a fixed plugin set.
+
+## Source layout
 
-## Package layers
+| File             | What it owns                                                                     |
+| ---------------- | -------------------------------------------------------------------------------- |
+| `protocol.ts`    | The wire contract Studio compiles against, published as `@kubb/studio/protocol`. |
+| `connect.ts`     | `connectAgent`: the socket loop and the `Agent` that serves Studio's calls.      |
+| `pair.ts`        | `pairAgent`: RFC 8628 device pairing.                                            |
+| `snapshot.ts`    | `createSnapshot` for CI, and packing a generation into an npm tarball.           |
+| `generations.ts` | Running a generation and keeping its files for `readFiles`.                      |
+| `configFile.ts`  | Reading and patching plugin options in `kubb.config.ts`.                         |
 
-`src/protocol` defines the shared wire contracts and imports no Studio implementation. `src/operations`
-contains focused work such as pairing, generation, config edits, snapshots, and transport; it may
-import the protocol. `src/runtime` owns connection state and coordinates operations; it may import
-both lower layers. Keep new code in the lowest layer that can own it, with direct internal imports.
-Only `@kubb/studio` and `@kubb/studio/protocol` are public entry points.
+## Connection
 
-## Hosts and the runtime
+`connectAgent` opens `wss://<studio>/api/agent/socket` with the agent's bearer token and an
+`x-kubb-instance-id` header. Studio calls `connect(info)` as the first RPC call. `info` says whether
+the agent is a sandbox and carries its slug and Studio's version. From then on the agent pings every
+30 seconds, and Studio schedules one job at a time on the socket.
 
-Three hosts run this package: `kubb studio`, the `kubblabs/kubb-agent` Docker image, and
-`kubb studio snapshot` in CI. All three follow the steps below. The runtime owns only the
-connection: it doesn't read CI environment variables or print anything, and behaves the same in
-every host.
+Studio ends a socket on purpose with one of these close codes:
 
-| Step             | `kubb studio`                           | Docker agent                             | `kubb studio snapshot`                   |
-| ---------------- | --------------------------------------- | ---------------------------------------- | ---------------------------------------- |
-| Machine identity | `setStorage` under project Kubb home    | `setStorage` on the cache volume         | `KUBB_AGENT_SECRET` from the CI identity |
-| Credentials      | stored, or `pairAgent({ type: 'cli' })` | stored, or `pairAgent({ type: 'user' })` | `createAgent` with the CI API key        |
-| Permissions      | flags and a per-project prompt          | `KUBB_AGENT_ALLOW_*`                     | flags only                               |
-| Connection       | `runConnection`                         | `runConnection`                          | `runConnection`                          |
-| Token rejected   | pair again once                         | pair again once                          | fail the run                             |
-| Output           | renders the `studio:*` hooks            | renders the `studio:*` hooks             | renders the `studio:*` hooks             |
+| Code   | Meaning                                       | `connectAgent`                        |
+| ------ | --------------------------------------------- | ------------------------------------- |
+| `4001` | The token is invalid, expired, or revoked     | Rejects with `InvalidAgentTokenError` |
+| `4002` | Another process of the same agent took over   | Resolves                              |
+| `4003` | The agent is older than Studio accepts        | Rejects with `IncompatibleAgentError` |
+| other  | An ordinary drop, `1011` for a Studio failure | Reconnects with jittered backoff      |
 
-Everything the runtime has to say goes through hooks on the emitter `installLogger` receives:
-`studio:connecting`, `studio:connected`, `studio:ready`, `studio:reconnecting`,
-`studio:disconnected`, `studio:command:start`, `studio:command:end`, `studio:warn`, and
-`studio:error`. When a request is refused for a missing permission, `studio:warn` carries it as
-`permission`, and the host adds its own remedy, a CLI flag or an environment variable.
+Everything the runtime has to say goes through the `hooks` emitter: `studio:connected`,
+`studio:disconnected`, `studio:reconnecting`, `studio:command`, `studio:warn`, and `studio:error`,
+next to the `kubb:*` hooks of each generation. When a request is refused for a missing permission,
+`studio:warn` names it as `permission`, so the host can add its own remedy.
 
 ## Permissions
 
@@ -109,135 +109,46 @@ Every permission is off by default, and each covers one trust boundary:
 | `allowConfigEdit` | Studio may change plugin options in `kubb.config.ts`.                                          |
 | `allowRead`       | Studio may read back the files a generation produced.                                          |
 
-## Connection flow
-
-Both hosts follow the same steps and send the agent's bearer token with every call. `/api/agent` is
-the machine-facing surface, singular because the caller is describing itself. The plural
-`/api/agents` is the collection a signed-in user manages in the browser, and the runtime never
-touches it.
-
-| Step     | Call                                    | What it does                                                                                                                              |
-| -------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| Register | `POST /api/agent/connect`               | Binds the token to this machine and process (`machineToken`, `instanceId`), reports `capacity`, and returns `socketUrl`                   |
-| Connect  | Configured RPC connector on `socketUrl` | Opens the process's one socket with the bearer token and `x-kubb-instance-id`, then attaches the typed `AgentApi`/`StudioApi` RPC session |
-
-Every connection attempt registers first, so a reconnect is also how the agent registers again.
-Each heartbeat carries the agent's load. A process keeps one socket, not one per job: Studio
-schedules jobs onto it up to the advertised `maxConcurrent`. Studio's close codes say whether to
-come back: `4001` registers and reconnects, `4002` (another instance took over) and `4003` (the
-agent is too old or was deleted) stay down. A `426` at registration means the agent is too old for
-that Studio.
-
-`runConnection` owns registration retries, capped reconnect backoff, credential replacement, and
-shutdown. `StudioSession` serves one attempt and waits for canceled generation work to settle before
-the loop reconnects. `createClient` remains a thin compatibility facade over that loop.
-
-The runtime reconnects when the socket drops and keeps retrying while Studio is unreachable. Generation progress is a native Cap'n Web `ReadableStream` on the generation
-capability; durable job status is read through the HTTP job API.
+A sandbox never writes or edits config, and always allows reads.
 
-## Studio job events
-
-`@kubb/studio` exposes a deliberately small public event API. Every live event uses the envelope
-`{ version: 1, jobId, type, data, timestamp }`. The native stream preserves order and applies
-backpressure; it is not a replay cursor. Job status and the terminal result remain authoritative
-after a reconnect.
-
-The stable catalog is `generationEventTypes`: generation and build progress, file processing,
-plugin progress, log levels, diagnostics, command-hook output, and the terminal generation summary.
-Each `type` is a lifecycle name registered by `@kubb/core`, while `data` is the JSON-safe projection
-defined by `GenerationEventPayloads`. AST traversal, live config and adapter objects, storage, and
-plugin implementations never leave the agent. New core hooks stay private until Studio explicitly
-adds their name and serializer projection.
-
-### Pairing
+## Pairing
 
 No host starts with a token, so each one pairs over
-[RFC 8628](https://www.rfc-editor.org/rfc/rfc8628.html) device authorization: it asks
-`POST /api/auth/device/code` for a `device_code` and a short `user_code`, shows the code, and polls
-`POST /api/agent/token` until someone approves in the browser. Studio mints the token once and stores only its hash, so
-nothing can read it back.
-
-`pairAgent` runs that whole flow and hands each code to the host's `onCode` to show. The `type` is
-what Studio registers the machine as: `cli` is a `kubb studio` machine any signed-in member can
-approve, and `user` or `sandbox` is the Docker image, whose codes only an admin can approve. With
-`maxAttempts` above 1 it asks for a fresh code when one expires unapproved. A denial throws
-`PairingDeniedError`, an expired code `PairingExpiredError`, and an aborted `signal`
+[RFC 8628](https://www.rfc-editor.org/rfc/rfc8628.html) device authorization. `pairAgent` asks Studio
+for a code, hands it to `onCode` to show, and polls until someone approves it in the browser.
+
+`machineId` is a secret the host keeps for the machine. Studio stores its hash, so the same machine
+pairing again rotates one agent's token instead of creating a second agent. Studio records the
+`type` with the agent. `cli` is `kubb studio`, which any member can approve. `user` and `sandbox`
+are the Docker image, run normally or as a sandbox. Only an admin can approve them. A denial
+throws `PairingDeniedError`, an expired code `PairingExpiredError`, and an aborted `signal`
 `PairingCanceledError`.
 
-```typescript
-import { pairAgent } from '@kubb/studio'
-
-const { token, agent } = await pairAgent({
-  type: 'cli',
-  name: 'my-project',
-  hostname: os.hostname(),
-  onCode: (session) => console.log(`Approve ${session.user_code} at ${session.verification_uri}`),
-})
-```
-
-## Asynchronous jobs
-
-CI and automation queue work with `createJob` and poll with `waitForJob`. Both send the
-organization CI API key as `x-api-key`. They do not open a WebSocket.
+## CI snapshots
 
-| Step   | Call                 | What it does                                                          |
-| ------ | -------------------- | --------------------------------------------------------------------- |
-| Queue  | `POST /api/jobs`     | Accepts a `generation` or `snapshot` job and returns `202` with an id |
-| Status | `GET /api/jobs/{id}` | Returns the job until `success`, `failed`, or `canceled`              |
+`createSnapshot` generates the project like `kubb generate`, with the formatter, the linter, and
+`output.postGenerate`. It then packs the output as an npm tarball and sends one
+`POST /api/snapshots` with the organization CI API key as `x-api-key`.
 
 ```typescript
-import { createJob, waitForJob } from '@kubb/studio'
-
-const job = await createJob({
-  studioUrl: 'https://kubb.studio',
-  token: process.env.KUBB_TOKEN!,
-  type: 'snapshot',
-  agentId: agent.id,
-  name: '@scope/package',
+import { createSnapshot } from '@kubb/studio'
+
+const snapshot = await createSnapshot({
+  apiKey: process.env.KUBB_TOKEN!,
+  config,
+  id: 'gh:123:pr-4',
+  name: 'acme/api#4',
+  packageName: '@acme/api',
   version: '1.0.0',
+  commit: process.env.GITHUB_SHA,
+  baseId: 'gh:123:refs/heads/main',
 })
-
-const finished = await waitForJob({
-  studioUrl: 'https://kubb.studio',
-  token: process.env.KUBB_TOKEN!,
-  id: job.id,
-})
-
-if (finished.status === 'failed') throw new Error(finished.error)
-if (finished.status === 'canceled') throw new Error('Studio job was canceled')
-const snapshot = finished.snapshot
-```
-
-Pass `commit` with a snapshot job, and the finished snapshot carries `changes`: the files added,
-changed, and removed since the previous snapshot of the same package on the same agent, and which
-snapshot (and commit) that was. `base` is `null` on the first one.
-
-Pass `baseId` (the `id` another CI agent's runs register under) and the snapshot also carries
-`branchChanges`: the same comparison against that agent's latest snapshot. On a GitHub pull
-request or a GitLab merge request, `kubb studio snapshot` passes the agent its base branch's runs
-use. Elsewhere, pass `--base-id` with the `--id` those runs use.
-
-Runs that share an agent (one pull request, or one branch) must not overlap, since registering it
-again ends the other run's session. Serialize them per ref, such as a GitHub Actions `concurrency`
-group on `github.ref` or a GitLab `resource_group` on `$CI_COMMIT_REF_SLUG`.
-
-A snapshot job packs the tarball on the agent, not on Studio. The agent `PUT`s an empty request to
-a path Studio provides, gets back a redirect to a short-lived storage URL, and uploads the tarball
-there. The storage URL never crosses the RPC socket.
-
-## Protocol
-
-`@kubb/studio/protocol` holds the RPC contracts both ends share, so the agent and Studio compile
-against one definition rather than two hand-maintained copies. Its only import is `KubbHooks` from
-`@kubb/core`, which the published event names are checked against.
-
-```typescript
-import type { AgentApi, GenerationEvent, GenerationRun, RpcConnection, RpcConnector, StudioApi } from '@kubb/studio'
 ```
 
-Hosts supply an `RpcConnector`, which keeps transport details in the CLI, Docker agent, or Studio
-host rather than in the generation runtime. A `GenerationRun.cancel()` call aborts the matching
-generation cooperatively, including configured formatter, linter, and `postGenerate` processes.
+Snapshots that share an `id` belong to one CI agent in Studio. `changes` lists the files added,
+changed, and removed since that agent's previous snapshot of the package. With `baseId`,
+`branchChanges` compares against the latest snapshot of the CI agent with that id, such as the base
+branch's.
 
 ## Supporting Kubb