@cpajs/cpa 0.1.0-rc.3 → 0.1.0-rc.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/README.md +185 -31
  2. package/assets/management.html +169 -0
  3. package/dist/binary-packages.cjs +84 -0
  4. package/dist/binary-packages.d.cts +30 -0
  5. package/dist/binary.d.ts +11 -0
  6. package/dist/binary.d.ts.map +1 -0
  7. package/dist/binary.js +10 -0
  8. package/dist/binary.js.map +1 -0
  9. package/dist/client/errors.d.ts +33 -0
  10. package/dist/client/errors.d.ts.map +1 -1
  11. package/dist/client/errors.js +47 -0
  12. package/dist/client/errors.js.map +1 -1
  13. package/dist/client/index.d.ts +3 -3
  14. package/dist/client/index.d.ts.map +1 -1
  15. package/dist/client/index.js +1 -1
  16. package/dist/client/index.js.map +1 -1
  17. package/dist/client/resources/config.d.ts +48 -3
  18. package/dist/client/resources/config.d.ts.map +1 -1
  19. package/dist/client/resources/config.js +149 -0
  20. package/dist/client/resources/config.js.map +1 -1
  21. package/dist/client/resources/credentials.d.ts +77 -0
  22. package/dist/client/resources/credentials.d.ts.map +1 -1
  23. package/dist/client/resources/credentials.js +476 -0
  24. package/dist/client/resources/credentials.js.map +1 -1
  25. package/dist/client/resources/requests.d.ts +12 -0
  26. package/dist/client/resources/requests.d.ts.map +1 -1
  27. package/dist/client/resources/requests.js +31 -0
  28. package/dist/client/resources/requests.js.map +1 -1
  29. package/dist/client/transport.d.ts +6 -0
  30. package/dist/client/transport.d.ts.map +1 -1
  31. package/dist/client/transport.js +24 -8
  32. package/dist/client/transport.js.map +1 -1
  33. package/dist/client/types/config.d.ts +8 -0
  34. package/dist/client/types/config.d.ts.map +1 -1
  35. package/dist/server/binary.d.ts.map +1 -1
  36. package/dist/server/binary.js +7 -15
  37. package/dist/server/binary.js.map +1 -1
  38. package/dist/server/config.d.ts +14 -0
  39. package/dist/server/config.d.ts.map +1 -1
  40. package/dist/server/config.js +34 -1
  41. package/dist/server/config.js.map +1 -1
  42. package/dist/server/cpa-version.d.ts +12 -0
  43. package/dist/server/cpa-version.d.ts.map +1 -1
  44. package/dist/server/cpa-version.js +12 -0
  45. package/dist/server/cpa-version.js.map +1 -1
  46. package/dist/server/errors.d.ts +2 -0
  47. package/dist/server/errors.d.ts.map +1 -1
  48. package/dist/server/errors.js.map +1 -1
  49. package/dist/server/index.d.ts +5 -1
  50. package/dist/server/index.d.ts.map +1 -1
  51. package/dist/server/index.js +441 -71
  52. package/dist/server/index.js.map +1 -1
  53. package/dist/server/internal.d.ts +2 -0
  54. package/dist/server/internal.d.ts.map +1 -1
  55. package/dist/server/logs.d.ts +7 -0
  56. package/dist/server/logs.d.ts.map +1 -0
  57. package/dist/server/logs.js +30 -0
  58. package/dist/server/logs.js.map +1 -0
  59. package/dist/server/management.d.ts +12 -5
  60. package/dist/server/management.d.ts.map +1 -1
  61. package/dist/server/management.js +8 -1
  62. package/dist/server/management.js.map +1 -1
  63. package/dist/server/panel.d.ts +5 -0
  64. package/dist/server/panel.d.ts.map +1 -0
  65. package/dist/server/panel.js +9 -0
  66. package/dist/server/panel.js.map +1 -0
  67. package/dist/server/process.d.ts +3 -1
  68. package/dist/server/process.d.ts.map +1 -1
  69. package/dist/server/process.js +7 -2
  70. package/dist/server/process.js.map +1 -1
  71. package/dist/server/types.d.ts +147 -12
  72. package/dist/server/types.d.ts.map +1 -1
  73. package/package.json +33 -25
  74. package/src/binary-packages.cjs +84 -0
  75. package/src/binary-packages.d.cts +30 -0
  76. package/src/binary.ts +10 -0
  77. package/src/client/errors.ts +50 -0
  78. package/src/client/index.ts +23 -2
  79. package/src/client/resources/config.ts +188 -3
  80. package/src/client/resources/credentials.ts +550 -0
  81. package/src/client/resources/requests.ts +35 -0
  82. package/src/client/transport.ts +28 -7
  83. package/src/client/types/config.ts +18 -0
  84. package/src/server/binary.ts +5 -14
  85. package/src/server/config.ts +38 -1
  86. package/src/server/cpa-version.ts +13 -0
  87. package/src/server/errors.ts +2 -0
  88. package/src/server/index.ts +498 -72
  89. package/src/server/internal.ts +2 -0
  90. package/src/server/logs.ts +34 -0
  91. package/src/server/management.ts +13 -5
  92. package/src/server/panel.ts +10 -0
  93. package/src/server/process.ts +9 -3
  94. package/src/server/types.ts +158 -12
package/README.md CHANGED
@@ -45,11 +45,19 @@ await server.stop();
45
45
  ```
46
46
 
47
47
  - `config` and `configPath` are mutually exclusive.
48
- - `config` is written as YAML to `<stateDir>/config.yaml` only when that file does not exist yet. On later
49
- starts the existing file is reused, so changes made through the management API (or by CPA itself) survive
50
- `stop()` and `startServer()`. Pass `overwriteConfig: true` to replace it; when a file is kept, `config`, `host`
51
- and `port` are not applied and a `configReused` warning is emitted. Credentials go to `<stateDir>/auths`
52
- unless `oauth.auth-dir` is set. The server binds `127.0.0.1` unless you pass `host` or set `server.host`.
48
+ - `config` is either a native config object or a function that returns one.
49
+ - An object is written as YAML to `<stateDir>/config.yaml` only when that file does not exist yet. On later
50
+ starts the existing file is reused, so changes made through the management API (or by CPA itself) survive
51
+ `stop()` and `startServer()`. Pass `overwriteConfig: true` to replace it; when a file is kept, `config`, `host`
52
+ and `port` are not applied and a `configReused` warning is emitted. Credentials go to `<stateDir>/auths`
53
+ unless `oauth.auth-dir` is set. The server binds `127.0.0.1` unless you pass `host` or set `server.host`.
54
+ - A function is called before the first start and again before every restart. It receives
55
+ `{ existing, reason }`: the parsed current `<stateDir>/config.yaml` (or `undefined`) and `'start'` or
56
+ `'restart'`. Its result replaces the file each time, like `overwriteConfig: true`, while cpajs still fills in
57
+ the listener, management secret and panel fields. It cannot be combined with `overwriteConfig`, and a
58
+ `configReused` warning is never emitted. The management key is resolved before the function runs, so
59
+ `management['secret-key']` in its result does not choose the key behind `server.client()`; pass
60
+ `management` for that (or keep the generated key).
53
61
  - `configPath` hands an existing file to CPA unchanged. CPA may rewrite it on startup: it hashes a plaintext
54
62
  `management.secret-key`, removes legacy keys that conflict with their v8 equivalents, and normalizes the
55
63
  layout (`internal/config/config_load.go` and `NormalizeConfigLayout`).
@@ -60,8 +68,8 @@ await server.stop();
60
68
  `tls.enable`. When cpajs writes the file and no port is given, it picks a free port first; a reused file keeps
61
69
  the port it already has.
62
70
  - `startServer` resolves only once `/healthz` answers. It rejects with `CpaStartError` on early exit, port
63
- conflict, timeout (`startupTimeoutMs`, default 30 s) or `signal` abort. In every failure case the process is
64
- stopped and the temporary directory removed.
71
+ conflict, timeout (`startupTimeoutMs`, default 30 s), `signal` abort, or an `afterStart` hook failure. In every
72
+ failure case the process is stopped and the temporary directory removed.
65
73
  - `stop()` is idempotent: on POSIX it sends SIGTERM and then SIGKILL after `stopTimeoutMs` (default 10 s). On
66
74
  Windows Node cannot deliver a graceful shutdown signal, so `stop()` terminates the process forcefully (equivalent
67
75
  to SIGKILL), `stopTimeoutMs` has no effect, and CPA gets no chance to flush state or update auth files. The same
@@ -69,11 +77,38 @@ await server.stop();
69
77
  - `restart({ timeoutMs, signal })` stops the old process with the same SIGTERM → SIGKILL sequence
70
78
  (`timeoutMs` defaults to `stopTimeoutMs`) and starts it again with the original options. The handle keeps
71
79
  `origin`, `baseUrl`, `host`, `port`, `stateDir` and `configPath`; `pid`, `process` and `recentLogs` point at the
72
- new process. The existing `config.yaml` is reused and never rewritten, so changes made through the management
73
- API survive. A dynamic port is reused too; if another process took it meanwhile, restart fails with
80
+ new process. With an object `config`, the existing `config.yaml` is reused and never rewritten, so changes made
81
+ through the management API survive. A function `config` is evaluated again before each restart and its result
82
+ replaces the file. A dynamic port is reused too; if another process took it meanwhile, restart fails with
74
83
  `CpaStartError` code `port-in-use` instead of changing `origin`. Concurrent `restart()` calls share one
75
84
  operation, `stop()` during a restart aborts it, and `restart()` after `stop()` rejects. A failed restart leaves
76
85
  the handle stopped and cleans up a temporary state directory like `startServer` does.
86
+ - `restart: { onUnexpectedExit, backoffMs, stableAfterMs, maxAttempts }` restarts CPA by itself after an
87
+ unexpected exit. It goes through the same path as `restart()`, so `origin`, `port`, the handle, the existing
88
+ config file and already-created `server.client()` instances keep working. `backoffMs` defaults to
89
+ `[500, 1000, 5000, 30_000]` and its last value repeats. A restarted process must stay up for `stableAfterMs`
90
+ (default 60 s) to count as healthy; one that exits before it keeps the backoff position, so a crash loop
91
+ escalates instead of restarting every 500 ms. `maxAttempts` consecutive restarts without a stable run stop the
92
+ server and settle `exited` (default `Infinity`); a manual `restart()` resets the count. `stop()` cancels a
93
+ pending wait, and `restart()` during one tries immediately. A port taken by another process makes that attempt
94
+ fail and retries after the next backoff instead of changing `origin`.
95
+ - `singleton: true` reuses one server per process for the same resolved `stateDir` (or absolute `configPath`),
96
+ so a dev server that evaluates a module more than once cannot start CPA twice. Concurrent calls share the
97
+ in-flight start and its promise; a handle that has not stopped yet is returned as-is, including while it is
98
+ backing off or restarting. Once the handle stops, the next call starts a new process. It requires an explicit
99
+ `stateDir` or `configPath`, and the options of the first call win: options on later calls are not compared.
100
+ The registry lives on `globalThis` (keyed by `Symbol.for('cpajs.servers')`), so duplicate module instances
101
+ in the same process share it.
102
+ - Lifecycle events: `server.on('exit' | 'restart' | 'restarted' | 'restart-failed', listener)` returns an
103
+ unsubscribe function. An `exit` payload has `code`, `signal`, `recentLogs` and `willRestart`; `restart` and
104
+ `restarted` carry `reason` (`'unexpected-exit' | 'manual'`) and `attempt`, and `restarted` also has
105
+ `originChanged` (currently always `false`); `restart-failed` has `error`, `attempt` and `willRetry`. A
106
+ listener that throws is reported through `process.emitWarning` and never disturbs the server.
107
+ - `hooks.afterStart({ server, client, reason })` runs after each process is ready: the first start and every
108
+ restart, manual or automatic. `reason` is `'start'` or `'restart'`; `client` is `server.client()` when cpajs
109
+ knows the plaintext management key and `undefined` otherwise. If it throws, the first start rejects with
110
+ `CpaStartError` code `hook-failed` after stopping the process, while a restart fails like any other
111
+ (`restart-failed`, then backoff or a rejected `restart()`).
77
112
  - Shutdown: CPA does not outlive your process, even if it is killed with SIGKILL, crashes, or is restarted by
78
113
  `tsx watch` / `nodemon`. Each platform package ships a small `cpa-launcher` (pure Go, in `launcher/`) that
79
114
  relies only on operating-system facilities:
@@ -99,17 +134,46 @@ await server.stop();
99
134
  ```
100
135
 
101
136
  Lines longer than 64 KiB in CPA's output are truncated, with a marker saying how much was dropped.
137
+ - Logs: `onLog` receives every line with `stream` and the redacted `line`. When the line uses CPA's log format,
138
+ it also has `level` (`debug`, `info`, `warn`, `error` or `fatal`), the short 8-character `requestId` (omitted
139
+ for CPA's `--------` placeholder) and `message` (the text after CPA's timestamp, request-id, level and caller
140
+ prefixes). Output that does not match the format still arrives, with only `stream` and `line`.
141
+
142
+ Pass `logs: { minLevel: 'warn' }` to drop lower-severity lines from `onLog`; `recentLogs` keeps everything,
143
+ because error messages often need the surrounding info lines. Lines without a parsed level always pass, so
144
+ unknown output is never hidden.
145
+
146
+ ```ts
147
+ await startServer({ config, logs: { minLevel: 'warn' }, onLog: ({ level, message, line }) => {
148
+ console.log(`[${level ?? 'raw'}] ${message ?? line}`);
149
+ } });
150
+ ```
102
151
  - Management key: you usually don't need one. Without `management`, cpajs generates a random key for each start,
103
152
  writes only its bcrypt hash into the managed config (remote management off), keeps the plaintext in memory,
104
153
  and gives you `server.client()`: a management client bound to this server. The key is never exposed, and
105
154
  because nobody types it, it can never be wrong and trigger CPA's 30-minute IP ban. `restart()` keeps the key,
106
- so existing clients keep working; a new `startServer()` generates a new one. `management: false` turns the
107
- management API off.
108
-
109
- Pass a key yourself only when something else needs it, for example a remote admin tool or another process:
110
- `management: { key }`. The default mode writes a bcrypt hash into `management.secret-key` of the managed config
111
- and sets `management.allow-remote` from `allowRemote` (default `false`), so the plaintext never reaches disk
112
- and remote management stays off. `server.client()` works there too.
155
+ so existing clients keep working; a new `startServer()` generates a new one. Since no one could log in to the
156
+ web control panel with that key, the panel defaults to off (`disable-control-panel: true`). `management: false`
157
+ turns the management API off.
158
+
159
+ Pass a key yourself when a person or something else needs it, for example the web control panel, a remote
160
+ admin tool or another process: `management: { key }`. The default mode writes a bcrypt hash into
161
+ `management.secret-key` of the managed config and sets `management.allow-remote` from `allowRemote` (default
162
+ `false`), so the plaintext never reaches disk and remote management stays off. `server.client()` works there
163
+ too.
164
+
165
+ The three steps build on each other: no key (only this process), `management: { key }` (people on this
166
+ machine, with the control panel), `allowRemote: true` (people elsewhere too). The rest of the table below is
167
+ for setups that need more control.
168
+
169
+ Control panel: `@cpajs/cpa` ships a pinned copy of the web control panel (`management.html`, see
170
+ [compatibility](docs/compatibility.md)), checked against its sha256 when the package is built. In a config
171
+ cpajs manages, CPA serves that copy at `/management.html` and never downloads one: cpajs copies it to
172
+ `<stateDir>/static/`, points `MANAGEMENT_STATIC_PATH` at it and defaults `disable-auto-update-panel` to `true`.
173
+ Upstream would otherwise fetch the latest panel from GitHub on start and every 3 hours, falling back to an
174
+ unverified mirror. To get that behaviour back, set `disable-auto-update-panel: false` or
175
+ `panel-github-repository` in `config.management`, or set `MANAGEMENT_STATIC_PATH` in `env`. With `configPath`,
176
+ cpajs leaves the panel to your file.
113
177
 
114
178
  Redaction: the key, secrets found in the config when the server starts, and `redact` values are replaced with
115
179
  `[REDACTED]` in `onLog`, `recentLogs` and startup errors. This is best-effort, with known limits:
@@ -120,16 +184,16 @@ await server.stop();
120
184
 
121
185
  Do not treat CPA's output as safe to publish.
122
186
 
123
- | Mode | How CPA compares the key | Remote access | `server.client()` |
124
- | --- | --- | --- | --- |
125
- | omitted (default) | bcrypt hash of a key generated per start | Off | Yes |
126
- | `management: false` | — (management API disabled) | — | No |
127
- | `management: { key }` | bcrypt hash in `management.secret-key` | Written from `allowRemote`, default `false` | Yes |
128
- | `management: { key, allowRemote: true }` | bcrypt hash in `management.secret-key` | Non-loopback clients allowed | Yes |
129
- | `management: { key, viaEnvironment: true }` | Plaintext `MANAGEMENT_PASSWORD` | Always allowed: upstream treats the variable as `allow-remote: true` | Yes |
130
- | `config.management['secret-key']` | What you write; CPA hashes plaintext on startup | `config.management['allow-remote']` | No: the key is yours |
131
- | `configPath` | `secret-key` in the file | `allow-remote` in the file | Only with `management: { key, viaEnvironment: true }` |
132
- | `managementKey` (deprecated) | bcrypt hash, same as `management: { key }` | Off unless the file allows it | Yes |
187
+ | Mode | How CPA compares the key | Remote access | `server.client()` | Control panel |
188
+ | --- | --- | --- | --- | --- |
189
+ | omitted (default) | bcrypt hash of a key generated per start | Off | Yes | Off (nobody knows the key) |
190
+ | `management: false` | — (management API disabled) | — | No | — |
191
+ | `management: { key }` | bcrypt hash in `management.secret-key` | Written from `allowRemote`, default `false` | Yes | Pinned copy |
192
+ | `management: { key, allowRemote: true }` | bcrypt hash in `management.secret-key` | Non-loopback clients allowed | Yes | Pinned copy |
193
+ | `management: { key, viaEnvironment: true }` | Plaintext `MANAGEMENT_PASSWORD` | Always allowed: upstream treats the variable as `allow-remote: true` | Yes | Pinned copy |
194
+ | `config.management['secret-key']` | What you write; CPA hashes plaintext on startup | `config.management['allow-remote']` | No: the key is yours | Pinned copy |
195
+ | `configPath` | `secret-key` in the file | `allow-remote` in the file | Only with `management: { key, viaEnvironment: true }` | Your file decides |
196
+ | `managementKey` (deprecated) | bcrypt hash, same as `management: { key }` | Off unless the file allows it | Yes | Pinned copy |
133
197
 
134
198
  `management.key` is rejected together with `config.management['secret-key']`, or with a `secret-key`
135
199
  already present in `configPath`. In `configPath` mode it also requires `viaEnvironment: true`, because
@@ -182,11 +246,30 @@ const client = createClient({
182
246
 
183
247
  const { data: config, etag } = await client.config.get();
184
248
  await client.config.patch({ routing: { strategy: 'round-robin' } }, { ifMatch: etag });
185
- await client.config.set('routing/retry/request-retry', 2);
249
+ await client.config.set('routing/retry/request-retry', 2); // value typed by path: number
250
+
251
+ // Read → change → write with If-Match. `auth_index` (injected on reads) is removed,
252
+ // a 412 re-reads and retries, and returning undefined skips the write.
253
+ await client.config.update('routing/strategy', (current) => current ?? 'fill-first');
254
+
255
+ // Deep-compares each top-level section and replaces only the ones that differ.
256
+ // A listed section is written wholesale, so nested keys absent from it are removed;
257
+ // sections not listed are untouched.
258
+ await client.config.reconcile({ routing: { strategy: 'fill-first' } });
186
259
 
187
260
  const { files } = await client.credentials.list();
188
261
  await client.credentials.upload({ name: 'codex-me.json', content: credentialJson });
189
262
 
263
+ // Files and config `api-keys` entries in one list, with the runtime auth_index.
264
+ const all = await client.credentials.listAll();
265
+ const models = await client.credentials.modelsFor({ auth_index: all[0]!.auth_index }, { details: true });
266
+
267
+ const synced = await client.credentials.reconcile({
268
+ owner: 'chat',
269
+ files: [{ name: 'chat-a.json', content: credentialJson, revision: '2026-10-27' }],
270
+ });
271
+ console.log(synced); // { uploaded: ['chat-a.json'], deleted: [], unchanged: [] }
272
+
190
273
  const login = await client.oauth.start({ provider: 'claude' });
191
274
  console.log('open', login.url);
192
275
  await client.oauth.waitForCompletion(login.state);
@@ -198,22 +281,43 @@ try {
198
281
  }
199
282
  ```
200
283
 
284
+ `credentials.reconcile` keeps a set of files owned by one caller in sync. Uploads carry a reserved
285
+ `x-cpajs: { owner, revision }` field. Only `revision` is compared, so CPA rewriting a file during a token
286
+ refresh does not cause another upload. With `prune` (the default), files owned by `owner` that are no longer
287
+ in `files` are deleted; files owned by anyone else are never touched. The caller's content objects are not
288
+ mutated.
289
+
290
+ `credentials.listAll` merges credential files with the config's `api-keys` entries, which `/credentials` only
291
+ exposes as a runtime view. Select either a file by `name` or any credential by `auth_index` with
292
+ `credentials.modelsFor`. Config-key models follow CPA's own resolution (model aliases, `excluded-models` with
293
+ `*` wildcards, and per-key overrides); `details: true` adds the channel's static model definitions. Runtime
294
+ state such as cooldowns is only available for files.
295
+
201
296
  | Group | Routes |
202
297
  | --- | --- |
203
- | `config` | `/config`, `/config.yaml`, `/config/*path`, with ETag / `If-Match` |
204
- | `credentials` | list, upload (raw or multipart), delete, models, download, status, fields, refresh, SIWC status |
298
+ | `config` | `/config`, `/config.yaml`, `/config/*path`, with ETag / `If-Match`, plus `update` / `reconcile` |
299
+ | `credentials` | list all (files + config keys), models per credential (with details), upload (raw or multipart), reconcile by owner/revision, delete, download, status, fields, refresh, SIWC status |
205
300
  | `oauth` | auth URL, status / wait, cancel, callback, Vertex import, SIWC bind |
206
301
  | `logs` | main log with cursor, clear, error logs, request logs |
207
302
  | `usage` | API-key counters, usage queue (destructive pop) |
208
303
  | `routing` | cooldown reset, model definitions |
209
- | `requests` | server-side `api-call` |
304
+ | `requests` | server-side `api-call` (`apiCall`, `apiCallJson`) |
210
305
  | `plugins` | list, delete, store, install, quota |
211
306
  | `server` | `/healthz`, version headers, latest release |
212
307
 
213
- Every method takes `{ signal, timeoutMs, headers }`. Errors:
308
+ `requests.apiCallJson()` is the throwing variant of `apiCall`: a JSON string body becomes `data`, a non-2xx
309
+ upstream status throws `CpaUpstreamError`, and an unresolvable `$TOKEN$` throws `CpaCredentialTokenError`.
310
+
311
+ Every method takes `{ signal, timeoutMs, headers }`. GET requests retry CPA's transient
312
+ `500 invalid_config` (a read landing while `config.yaml` is rewritten) up to three times after
313
+ 100/200/400 ms; writes never retry. Pass `retryInvalidConfig: false` to `createClient` to disable it. Errors:
214
314
 
215
315
  - `CpaHttpError` for a non-2xx response. It carries `status`, the raw `body`, parsed `data`, and `errorCode` /
216
316
  `errorMessage`.
317
+ - `CpaUpstreamError` when `requests.apiCallJson` gets a non-2xx upstream status. It carries the upstream
318
+ `status`, `headers`, and `body` (parsed when JSON).
319
+ - `CpaCredentialTokenError` when `requests.apiCallJson` cannot resolve `$TOKEN$`. It carries `status` and
320
+ `errorCode`.
217
321
  - `CpaNetworkError` when the request fails.
218
322
  - `CpaTimeoutError` when the request times out.
219
323
  - `CpaAbortError` when your `signal` aborts the request.
@@ -241,6 +345,55 @@ import OpenAI from 'openai';
241
345
  const openai = new OpenAI({ baseURL: server.baseUrl, apiKey: 'sk-my-model-key' });
242
346
  ```
243
347
 
348
+ ## Bundling and deploying
349
+
350
+ The platform package is an optional dependency picked at runtime, so a bundler cannot see it in a normal
351
+ `import`. `@cpajs/cpa/binary` is a small entry that contains a literal `require.resolve()` for every target;
352
+ importing it for its side effect puts the installed platform packages in the module graph:
353
+
354
+ ```ts
355
+ import '@cpajs/cpa/binary';
356
+ ```
357
+
358
+ Trace on the deployment platform (including glibc vs musl). A file tracer such as `@vercel/nft` then copies
359
+ the package that matches the build machine. Keep `@cpajs/cpa` and `@cpajs/<target>` external rather than
360
+ bundling them. nft reports a warning for every platform package that is not installed; those are expected
361
+ and non-fatal.
362
+
363
+ Nitro uses nft. Import the entry from the server code, and full-trace the platform package so its `bin/`
364
+ directory is copied too (`pkg*` copies every file, not only the traced ones):
365
+
366
+ ```ts
367
+ export default defineNitroConfig({
368
+ // Replace linux-x64-gnu with the target you deploy to (see src/server/targets.ts).
369
+ traceDeps: ['@cpajs/cpa', '@cpajs/linux-x64-gnu*'],
370
+ });
371
+ ```
372
+
373
+ Vite SSR leaves packages in `node_modules` external; make that explicit and run nft over the server output (or
374
+ over `@cpajs/cpa/binary`) as part of the deploy step:
375
+
376
+ ```ts
377
+ export default defineConfig({
378
+ ssr: { external: ['@cpajs/cpa'] },
379
+ });
380
+ ```
381
+
382
+ Next.js: keep cpajs outside the server bundle and let output file tracing include it:
383
+
384
+ ```js
385
+ module.exports = {
386
+ serverExternalPackages: ['@cpajs/cpa'],
387
+ };
388
+ ```
389
+
390
+ In all three setups the side-effect import is what makes the table visible; if a trace still misses the
391
+ binary, copy `node_modules/@cpajs/<target>/` into the deployment or pass `binaryPath` to `startServer`.
392
+
393
+ Bun ignores `libc`, so `bun install` on Linux installs both `@cpajs/linux-*-gnu` and `@cpajs/linux-*-musl`
394
+ (about 72 MB extra). Install with npm or pnpm, or delete the packages for the other libc before packaging;
395
+ cpajs still picks the right target at runtime. `binaryPath` also lets you ship a single binary yourself.
396
+
244
397
  ## Development
245
398
 
246
399
  ```sh
@@ -261,6 +414,7 @@ Release tooling, all in `scripts/` and run directly with Node's type stripping:
261
414
  | Script | Purpose |
262
415
  | --- | --- |
263
416
  | `fetch-source.ts` | Clone the pinned CPA tag and verify the commit. |
417
+ | `generate-binary-table.ts` | Regenerate `src/binary-packages.cjs` and its types from `TARGETS`; `--check` fails on drift. |
264
418
  | `build-binary.ts` | Build one or more targets, with the same CGO/plugin split as upstream. |
265
419
  | `verify-binary.ts` | Check format, CPU, static linking and the glibc baseline; `--smoke` starts the binary. |
266
420
  | `assemble-packages.ts` | Create the `@cpajs/*` platform packages. |