@cbxss/eoka 0.1.0-beta.3 → 0.1.0-beta.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.
- package/README.md +106 -500
- package/dist/browser.d.ts +3 -0
- package/dist/browser.js +10 -1
- package/dist/cloudflare.d.ts +45 -0
- package/dist/cloudflare.js +154 -0
- package/dist/generated/protocol.d.ts +17 -1
- package/dist/generated/protocol.js +1 -1
- package/dist/generated/schema-bundle.json +59 -0
- package/dist/index.d.ts +1 -0
- package/dist/page.d.ts +20 -0
- package/dist/page.js +58 -0
- package/dist/release-manifest.json +17 -17
- package/dist/release.js +1 -1
- package/dist/server-binary.d.ts +1 -0
- package/dist/server-binary.js +24 -1
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,579 +1,185 @@
|
|
|
1
1
|
# @cbxss/eoka
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Node.js SDK for eoka, a stealth Chrome automation sidecar.
|
|
4
4
|
|
|
5
5
|
```sh
|
|
6
|
-
npm install @cbxss/eoka@
|
|
6
|
+
npm install @cbxss/eoka@latest
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Requires Node.js 24.21+ (ESM only). Supported platforms: Linux x64/arm64 (glibc 2.35+), macOS x64/arm64, Windows x64.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
Managed targets are `linux-x64-gnu`, `linux-arm64-gnu`, `darwin-x64`, `darwin-arm64`, and `win32-x64`. Linux managed selection requires glibc >= 2.35 and rejects musl/Alpine; Windows arm64 and unknown combinations are rejected before downloads. GNU release artifacts are built on Ubuntu 22.04 and checked for GLIBC requirements no higher than 2.35. Arbitrary source-built or host-development binaries are not qualified by that result.
|
|
14
|
-
|
|
15
|
-
Both explicit server and Chrome paths are an expert override for managed platform checks, not a new support guarantee. Node.js support does not imply Bun, Deno, browser-side JavaScript, or drop-in Puppeteer compatibility. Packed npm consumption and credential-free registry installation with a Linux Chrome smoke are verified for beta.2; beta.3 requires fresh qualification. pnpm/Yarn remain unqualified.
|
|
16
|
-
|
|
17
|
-
## Managed launch and explicit preparation
|
|
11
|
+
## Quick start
|
|
18
12
|
|
|
19
13
|
```js
|
|
20
|
-
import { Browser
|
|
21
|
-
|
|
22
|
-
await installBrowser({
|
|
23
|
-
browserCacheDir: "/opt/eoka/cache",
|
|
24
|
-
timeoutMs: 300000,
|
|
25
|
-
onProgress: ({ downloadedBytes, totalBytes, buildId }) => {
|
|
26
|
-
process.stderr.write(`${buildId}: ${downloadedBytes}/${totalBytes} bytes\n`);
|
|
27
|
-
},
|
|
28
|
-
});
|
|
14
|
+
import { Browser } from "@cbxss/eoka";
|
|
29
15
|
|
|
30
|
-
const browser = await Browser.launch(
|
|
31
|
-
browserCacheDir: "/opt/eoka/cache",
|
|
32
|
-
download: "never",
|
|
33
|
-
sandbox: true,
|
|
34
|
-
timeoutMs: 30000,
|
|
35
|
-
});
|
|
16
|
+
const browser = await Browser.launch();
|
|
36
17
|
try {
|
|
37
|
-
const page = await browser.newPage("
|
|
38
|
-
console.log(await page.
|
|
18
|
+
const page = await browser.newPage("https://example.com");
|
|
19
|
+
console.log(await page.title());
|
|
20
|
+
await page.screenshotToFile({ path: "./example.png" });
|
|
39
21
|
} finally {
|
|
40
22
|
await browser.close();
|
|
41
23
|
}
|
|
42
24
|
```
|
|
43
25
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
`installBrowser` prepares only Chrome; it does not install system libraries or native server packages. Its options are `browserCacheDir`, `download` (`"auto"` by default or `"never"`), `signal`, `timeoutMs` (300000 ms by default), and `onProgress`. It returns `{ executablePath, cacheDir, buildId, platform, source }`, with `source: "cache"` or `"download"`. Cancellation/deadlines terminate the owned installer worker before cleaning its own staging resources. One launch deadline covers server resolution, Chrome installation, handshake, and native launch.
|
|
26
|
+
The first launch downloads a pinned Chrome for Testing build (about 200 MB) into a per-user cache. Later launches reuse it.
|
|
47
27
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
## Cache, runtime, and offline operation
|
|
51
|
-
|
|
52
|
-
Cache root precedence is `browserCacheDir` > `EOKA_BROWSER_CACHE_DIR` > the per-user OS default:
|
|
53
|
-
|
|
54
|
-
| OS | Default cache root |
|
|
55
|
-
| --- | --- |
|
|
56
|
-
| Linux | `${XDG_CACHE_HOME}/eoka`, or `~/.cache/eoka` |
|
|
57
|
-
| macOS | `~/Library/Caches/eoka` |
|
|
58
|
-
| Windows | `${LOCALAPPDATA}/eoka/Cache`, or `~/AppData/Local/eoka/Cache` |
|
|
28
|
+
## Pages
|
|
59
29
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
From an installed SDK application, run the shipped examples directly:
|
|
67
|
-
|
|
68
|
-
```sh
|
|
69
|
-
node node_modules/@cbxss/eoka/examples/install-browser.mjs /opt/eoka/cache
|
|
70
|
-
EOKA_RUNTIME_DIR=/tmp/eoka node node_modules/@cbxss/eoka/examples/offline.mjs /opt/eoka/cache
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
The offline example uses a data URL, so its page also requires no network. `download: "never"` governs installation, not web page requests; use an OS/container network policy to prevent application traffic.
|
|
74
|
-
|
|
75
|
-
## Download pins, size, and proxy configuration
|
|
76
|
-
|
|
77
|
-
This source pins full Chrome for Testing **155.0.8059.39**, not ChromeDriver or a runtime-selected latest version. `releaseManifest` and `@cbxss/eoka/release-manifest.json` expose the release metadata. The archive SHA-256 values were computed from full HTTPS archives during controlled release preparation; they are reviewed integrity pins, **not vendor signatures**. Runtime installation uses those embedded pins and never looks up a hash or substitutes a mirror/build. Browser updates require a deliberate new release and fresh native gates.
|
|
78
|
-
|
|
79
|
-
Measured compressed archive sizes for this pin:
|
|
80
|
-
|
|
81
|
-
| Chrome platform | Bytes |
|
|
82
|
-
| --- | ---: |
|
|
83
|
-
| linux64 | 198195769 |
|
|
84
|
-
| linux-arm64 | 198202003 |
|
|
85
|
-
| mac-x64 | 203101743 |
|
|
86
|
-
| mac-arm64 | 192634606 |
|
|
87
|
-
| win64 | 207197429 |
|
|
88
|
-
|
|
89
|
-
Budget additional space for the expanded distribution, temporary archive/staging, and concurrent runtime profiles. The SDK does not download browser drivers.
|
|
90
|
-
|
|
91
|
-
The installer honors `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, and `NO_PROXY` through its pinned proxy dependency. Configure them in the setup process environment, or in `serverEnv` for a launch-scoped child environment. Do not put proxy credentials in progress logs. Standard Node trust configuration such as `NODE_EXTRA_CA_CERTS` must be set before starting Node when an enterprise CA is required. TLS failures and hash mismatches fail closed; do not disable certificate verification.
|
|
92
|
-
|
|
93
|
-
```sh
|
|
94
|
-
HTTPS_PROXY=http://proxy.example:8080 NO_PROXY=localhost,127.0.0.1 \
|
|
95
|
-
node node_modules/@cbxss/eoka/examples/install-browser.mjs /opt/eoka/cache
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
## Linux libraries, sandbox, and containers
|
|
99
|
-
|
|
100
|
-
The SDK does not install privileged OS packages. Chrome requires its host libraries and fonts even in headless mode: NSS/NSPR, ATK/AT-SPI, CUPS, DRM/GBM, X11/XCB/Xcomposite/Xdamage/Xfixes/Xrandr, xkbcommon, ALSA, GLib, Cairo/Pango, and fonts. The native server's dependencies are artifact-specific; current Linux staging also needs OpenSSL 3 (`libssl.so.3` and `libcrypto.so.3`). Inspect actual release binaries and qualify the chosen distribution rather than treating this list as an ABI certification.
|
|
101
|
-
|
|
102
|
-
Sandboxing is enabled by default. Run as an unprivileged user with Chrome's sandbox requirements satisfied (including the host/container user-namespace and seccomp policy). A sandbox failure is an error; the SDK never retries with sandbox disabled. `sandbox: false` is an explicit security-reducing expert choice for a separately isolated environment, not the default container recipe.
|
|
103
|
-
|
|
104
|
-
Ubuntu 23.10+ can deny unprivileged user namespaces through AppArmor even when
|
|
105
|
-
Chrome itself is sandbox-enabled. An administrator must provide a narrowly
|
|
106
|
-
scoped executable-path policy for the owned Chrome runtime, as described in
|
|
107
|
-
[Chromium's AppArmor guidance](https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md).
|
|
108
|
-
Any process able to replace an executable at an allowed path gains that
|
|
109
|
-
permission; use a private runtime directory, not a broad `/tmp/**/chrome` rule.
|
|
110
|
-
The SDK neither installs privileged policies nor disables the host restriction.
|
|
111
|
-
ARM release CI uses a private per-job path exception, removes it afterward,
|
|
112
|
-
and checks Chrome's actual PID/network namespace and seccomp status.
|
|
113
|
-
|
|
114
|
-
For example, prepare a Linux x64 image with Node 24.21.0 and a distribution new enough for the **actual staged binary**. The following Debian trixie setup is a recipe to qualify, not a statement of completed container support. Supply the two locally staged tarballs described below as build inputs:
|
|
115
|
-
|
|
116
|
-
```dockerfile
|
|
117
|
-
FROM node:24.21.0-trixie
|
|
118
|
-
RUN apt-get update && apt-get install -y --no-install-recommends \
|
|
119
|
-
ca-certificates fonts-liberation libasound2t64 libatk-bridge2.0-0t64 libatk1.0-0t64 \
|
|
120
|
-
libcairo2 libcups2t64 libdbus-1-3 libdrm2 libgbm1 libglib2.0-0t64 libnspr4 \
|
|
121
|
-
libnss3 libpango-1.0-0 libssl3t64 libx11-6 libxcb1 libxcomposite1 libxdamage1 \
|
|
122
|
-
libxext6 libxfixes3 libxkbcommon0 libxrandr2 \
|
|
123
|
-
&& rm -rf /var/lib/apt/lists/*
|
|
124
|
-
WORKDIR /app
|
|
125
|
-
RUN chown node:node /app
|
|
126
|
-
COPY --chown=node:node cbxss-eoka-0.1.0-beta.3.tgz cbxss-eoka-server-linux-x64-gnu-0.1.0-beta.3.tgz ./
|
|
127
|
-
USER node
|
|
128
|
-
RUN npm init -y && npm install --ignore-scripts --omit=optional --no-audit --no-fund \
|
|
129
|
-
./cbxss-eoka-server-linux-x64-gnu-0.1.0-beta.3.tgz ./cbxss-eoka-0.1.0-beta.3.tgz
|
|
130
|
-
ENV EOKA_BROWSER_CACHE_DIR=/app/browser-cache
|
|
131
|
-
ENV EOKA_RUNTIME_DIR=/tmp/eoka
|
|
132
|
-
RUN node node_modules/@cbxss/eoka/examples/install-browser.mjs
|
|
133
|
-
CMD ["node", "node_modules/@cbxss/eoka/examples/offline.mjs"]
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
Network is needed during image preparation for npm dependencies and the pinned Chrome ZIP. Runtime can then be isolated with `docker run --init --network=none --read-only --tmpfs /tmp:rw,nosuid,size=1g IMAGE`, provided the host's sandbox policy permits Chrome. Use an init process to reap orphaned browser children. Preserve cache ownership/metadata in the image and keep `/tmp` writable. Adapt library names, resource limits, and sandbox policy to the deployment; never use an Alpine/musl base for managed mode.
|
|
137
|
-
|
|
138
|
-
## Build, source staging, and local consumption
|
|
139
|
-
|
|
140
|
-
This SDK and its five native packages share reserved npm version `0.1.0-beta.3`. The native server is pinned separately to `0.6.1`, published registry core to `0.7.2`, and the protocol to `1.3`; npm version equality is not wire compatibility. Release manifests accept exact semantic versions, including prereleases, but reject floating ranges, tags, and malformed versions. Packaged servers are checked against their name/version/platform, staged release metadata, actual binary digest, and expected handshake version. Explicit servers still must pass the protocol handshake.
|
|
141
|
-
|
|
142
|
-
The source manifest intentionally has no fabricated hashes for unprepared native artifacts. The source package omits native optional dependencies so a clean `npm ci` does not need unpublished packages. Staging derives all five exact native dependencies from the validated release manifest and adds them to the staged SDK's package metadata. Packing the source SDK alone is useful for import/type gates, but is **not** a ready managed server distribution. Missing native packages (including after `--omit=optional`) raise `ServerPackageMissing`; a present package with an unstaged SDK pin raises `ReleaseNotPrepared`. There is no compile/download fallback.
|
|
143
|
-
|
|
144
|
-
Run `mise install` at the repository root to install the pinned Node 24.21.0 toolchain. With mise activated, prepare local artifacts from this package directory without publishing:
|
|
30
|
+
```js
|
|
31
|
+
await page.goto("https://example.com/login");
|
|
32
|
+
await page.fill("#email", "ada@example.com");
|
|
33
|
+
await page.click("button[type=submit]", {
|
|
34
|
+
actionOptions: { expect: { kind: "url", value: "/home", contains: true } },
|
|
35
|
+
});
|
|
145
36
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
npm run stage:release -- --artifacts /absolute/path/to/release-server-artifacts \
|
|
150
|
-
--output /absolute/path/to/new-stage --host-only
|
|
151
|
-
npm pack --ignore-scripts --pack-destination /absolute/path/to/tarballs \
|
|
152
|
-
/absolute/path/to/new-stage/platforms/linux-x64-gnu
|
|
153
|
-
npm pack --ignore-scripts --pack-destination /absolute/path/to/tarballs \
|
|
154
|
-
/absolute/path/to/new-stage/sdk
|
|
37
|
+
await page.waitForText("Welcome");
|
|
38
|
+
const heading = await page.getText("h1");
|
|
39
|
+
const count = await page.evaluate("document.querySelectorAll('li').length");
|
|
155
40
|
```
|
|
156
41
|
|
|
157
|
-
|
|
42
|
+
String targets are CSS selectors. An action resolves only after its result is verified. `click`, `type`, `pressKey`, `submit` and `drag` need an `expect` that describes the result.
|
|
158
43
|
|
|
159
|
-
|
|
44
|
+
- **Reads:** `text`, `content`, `title`, `url`, `getText`, `getAttribute`, `exists`, `evaluate`
|
|
45
|
+
- **Waits:** `waitFor`, `waitForVisible`, `waitForText`
|
|
46
|
+
- **Actions:** `goto`, `fill`, `select`, `hover`, `click`, `type`, `pressKey`, `submit`, `drag`
|
|
160
47
|
|
|
161
|
-
|
|
162
|
-
| --- | --- |
|
|
163
|
-
| linux-x64-gnu | `eoka-server-linux-amd64` |
|
|
164
|
-
| linux-arm64-gnu | `eoka-server-linux-arm64` |
|
|
165
|
-
| darwin-x64 | `eoka-server-darwin-amd64` |
|
|
166
|
-
| darwin-arm64 | `eoka-server-darwin-arm64` |
|
|
167
|
-
| win32-x64 | `eoka-server-windows-amd64.exe` |
|
|
48
|
+
## Shadow DOM and Turnstile
|
|
168
49
|
|
|
169
|
-
|
|
50
|
+
`page.frames()` lists every frame, including cross-origin OOPIFs. `page.clickShadow(selector, { frameId?, resolveTimeoutMs? })` searches the frame's light DOM and every shadow root (closed roots included), maps the matched node's center to viewport coordinates, and clicks with human-like movement. `resolveTimeoutMs` bounds the server-side resolution; `CallOptions.timeoutMs` remains the RPC deadline and defaults to the resolution deadline plus 10 seconds when omitted:
|
|
170
51
|
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
52
|
+
```js
|
|
53
|
+
const challenge = (await page.frames()).find(frame =>
|
|
54
|
+
frame.url.includes("challenges.cloudflare.com"));
|
|
55
|
+
if (challenge) {
|
|
56
|
+
await page.clickShadow('input[type="checkbox"]', { frameId: challenge.id });
|
|
57
|
+
}
|
|
176
58
|
```
|
|
177
59
|
|
|
178
|
-
|
|
60
|
+
`page.solveTurnstile({ timeoutMs })` is a best-effort helper for interactive Cloudflare challenge pages. It finds the challenge frame, clicks the checkbox, and waits for the page to leave the challenge state. It is not a general CAPTCHA solver.
|
|
179
61
|
|
|
180
|
-
|
|
62
|
+
### Automatic challenge handling
|
|
181
63
|
|
|
182
|
-
|
|
64
|
+
`Browser.launch({ autoSolveCloudflare: true })` (and `Browser.connect`) watches every tab and calls `solveTurnstile()` when a full-page Cloudflare challenge appears. It does not click Turnstile widgets embedded in normal forms.
|
|
183
65
|
|
|
184
66
|
```js
|
|
185
|
-
|
|
186
|
-
import { Browser } from "@cbxss/eoka";
|
|
187
|
-
|
|
188
|
-
const browser = await Browser.launch({
|
|
189
|
-
serverPath: "/absolute/path/to/eoka-server",
|
|
190
|
-
executablePath: "/absolute/path/to/chrome",
|
|
191
|
-
headless: true,
|
|
192
|
-
sandbox: true,
|
|
193
|
-
viewport: { width: 1024, height: 768, deviceScaleFactor: 1 },
|
|
194
|
-
timeoutMs: 15000,
|
|
195
|
-
});
|
|
196
|
-
|
|
67
|
+
const browser = await Browser.launch({ autoSolveCloudflare: true });
|
|
197
68
|
try {
|
|
198
|
-
const
|
|
199
|
-
|
|
200
|
-
const target = { query: { kind: "css", selector: "#name" } };
|
|
201
|
-
const operationId = randomUUID();
|
|
202
|
-
const receipt = await page.fill(target, "Ada", {
|
|
203
|
-
operationId,
|
|
204
|
-
timeoutMs: 10000,
|
|
205
|
-
actionOptions: {
|
|
206
|
-
expect: { kind: "value", target, value: "Ada" },
|
|
207
|
-
timeout_ms: 5000,
|
|
208
|
-
},
|
|
209
|
-
});
|
|
210
|
-
console.log({ operationId, receipt });
|
|
211
|
-
console.log(await page.invoke("page.evaluate", {
|
|
212
|
-
pageId: page.id,
|
|
213
|
-
js: '({name: document.querySelector("#name").value})',
|
|
214
|
-
}));
|
|
69
|
+
const page = await browser.newPage("https://1337x.to/");
|
|
70
|
+
console.log(await page.title()); // Torrent Search Engine | 1337x.to
|
|
215
71
|
} finally {
|
|
216
72
|
await browser.close();
|
|
217
73
|
}
|
|
218
74
|
```
|
|
219
75
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
`newPage(url)` and `goto(url)` verify a navigation commit, not DOM parsing or application readiness. Before parser-dependent reads, use `evaluate` to await `DOMContentLoaded` only while `document.readyState === "loading"`; resolve the promise to a JSON-compatible value such as `true`. `goto` accepts an explicit `actionOptions.expect` when navigation must also establish application readiness.
|
|
223
|
-
|
|
224
|
-
Run the included example after building:
|
|
225
|
-
|
|
226
|
-
```sh
|
|
227
|
-
npm run example -- /absolute/path/to/eoka-server /absolute/path/to/chrome
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
Alternatively set `EOKA_SERVER_BIN` and `EOKA_CHROME_PATH`. Explicit options take precedence. Providing both paths bypasses managed installation/platform selection; no arbitrary system discovery is performed. `userDataDir` remains caller-owned. A temporary profile belongs to its owned session.
|
|
231
|
-
|
|
232
|
-
## Durable operations and uncertainty
|
|
76
|
+
Tune the watcher or observe it:
|
|
233
77
|
|
|
234
78
|
```js
|
|
235
|
-
const
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
)
|
|
240
|
-
|
|
241
|
-
|
|
79
|
+
const browser = await Browser.launch({
|
|
80
|
+
autoSolveCloudflare: {
|
|
81
|
+
intervalMs: 500, // tab poll interval
|
|
82
|
+
timeoutMs: 45_000, // deadline per challenge
|
|
83
|
+
onChallenge: page => console.log("cloudflare challenge", page.id),
|
|
84
|
+
onSolved: page => console.log("cloudflare solved", page.id),
|
|
85
|
+
onError: (error, page) => console.warn("cloudflare", error, page?.id),
|
|
86
|
+
},
|
|
87
|
+
});
|
|
242
88
|
```
|
|
243
89
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
Get/cancel for an already-admitted operation remain responsive while an unrelated page request waits. Unknown IDs retain ordering behind earlier queued admissions. Operation lists are independent snapshots of currently admitted records, not barriers for queued mutations. These controls still obey the negotiated in-flight limit.
|
|
90
|
+
The watcher polls; it is not an event hook. It stops on `browser.close()` and never keeps the Node process alive by itself.
|
|
247
91
|
|
|
248
|
-
|
|
92
|
+
## Screenshots and recording
|
|
249
93
|
|
|
250
94
|
```js
|
|
251
|
-
|
|
95
|
+
const png = await page.screenshot(); // Buffer
|
|
96
|
+
await page.screenshot({ format: "webp", quality: 80 });
|
|
97
|
+
await page.screenshotToFile({ path: "./full.png", fullPage: true });
|
|
252
98
|
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
if (!(error instanceof EokaError)) throw error;
|
|
257
|
-
console.error({
|
|
258
|
-
code: error.code,
|
|
259
|
-
requestId: error.requestId,
|
|
260
|
-
operationId: error.operationId,
|
|
261
|
-
requestState: error.requestState,
|
|
262
|
-
receipt: error.receipt,
|
|
263
|
-
});
|
|
264
|
-
if (error.operationId) {
|
|
265
|
-
console.log(await browser.operation(error.operationId).get({ timeoutMs: 5000 }));
|
|
266
|
-
}
|
|
267
|
-
}
|
|
99
|
+
const recording = await page.record({ path: "./session.mp4" });
|
|
100
|
+
// ...
|
|
101
|
+
await recording.stop();
|
|
268
102
|
```
|
|
269
103
|
|
|
270
|
-
|
|
104
|
+
File output never overwrites an existing file, and the directory must already exist. Recordings are silent MP4s. For screenshots larger than 16 MiB, use `screenshotToFile`.
|
|
271
105
|
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
When both an operation/lifecycle failure and its cleanup fail, the SDK reports an `AggregateError`. Its `cause` preserves the primary error (also `errors[0]`), including any `operationId`, request state, and receipt; inspect that cause when recovering an operation. The remaining `errors` preserve cleanup failures rather than replacing the original evidence.
|
|
275
|
-
|
|
276
|
-
## Typed reads and invocation
|
|
277
|
-
|
|
278
|
-
`Browser` and `Page` implement the generated `InvokeClient` contract:
|
|
279
|
-
|
|
280
|
-
```ts
|
|
281
|
-
import type { MethodResults } from "@cbxss/eoka";
|
|
282
|
-
import { protocolVersion } from "@cbxss/eoka/protocol";
|
|
283
|
-
|
|
284
|
-
const result: MethodResults["page.evaluate"] = await page.invoke(
|
|
285
|
-
"page.evaluate",
|
|
286
|
-
{ pageId: page.id, js: "({answer: 42, items: [1, null]})" },
|
|
287
|
-
{ timeoutMs: 5000 },
|
|
288
|
-
);
|
|
289
|
-
console.log(protocolVersion, result.result);
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
The method map is generated from the canonical sidecar schemas, including dynamic JSON evaluation results. Use `browser.supports(method)` and `browser.hasCapability(name)` to inspect the actual handshake rather than assuming every generated method is available on an older sidecar. `hello`, `sessionInfo`, `ownership`, and `browserVersion` expose negotiated/session metadata.
|
|
293
|
-
|
|
294
|
-
Page conveniences cover text/content/title/URL, element reads/waits, evaluation/execution, screenshots, viewport, browser state, and agent observation/steps. `page.fetch` is the legacy unbounded response API. Prefer `page.fetchBounded` for response-body reads: its default body budget is 8192 bytes and maximum is 1048576 bytes; inspect `truncated`, `bytesRead`, and `bodyOmitted` along with the body/status/headers. The `boundedFetch` capability indicates sidecar support. A bounded read is not the same as a complete response.
|
|
295
|
-
|
|
296
|
-
## Screenshots and native recording
|
|
106
|
+
## Options
|
|
297
107
|
|
|
298
108
|
```js
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
}
|
|
305
|
-
|
|
306
|
-
path: "./captures/page.png",
|
|
307
|
-
fullPage: true,
|
|
308
|
-
});
|
|
309
|
-
const recording = await page.record({
|
|
310
|
-
path: "./captures/session.mp4",
|
|
311
|
-
maxWidth: 1280,
|
|
312
|
-
maxHeight: 720,
|
|
313
|
-
fps: 30,
|
|
109
|
+
await Browser.launch({
|
|
110
|
+
headless: true, // default
|
|
111
|
+
sandbox: true, // default; leave it on
|
|
112
|
+
download: "auto", // "never" fails when Chrome isn't cached
|
|
113
|
+
browserCacheDir: "/opt/eoka/cache",
|
|
114
|
+
viewport: { width: 1280, height: 720, deviceScaleFactor: 1 },
|
|
115
|
+
timeoutMs: 30000,
|
|
314
116
|
});
|
|
315
|
-
console.log(recording.id, await recording.status());
|
|
316
|
-
const video = await recording.stop({ timeoutMs: 60000 });
|
|
317
|
-
console.log(screenshot.path, screenshot.bytes, video.path, video.container);
|
|
318
117
|
```
|
|
319
118
|
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
Returned artifact paths are canonical and may use Windows' `\\?\` namespace
|
|
323
|
-
prefix. Compare filesystem identity, not the spelling of the requested path.
|
|
324
|
-
|
|
325
|
-
`screenshot()` returns a PNG Buffer by default and still accepts the original `{signal, timeoutMs}` call options. `format` supports `png`, `jpeg`, and `webp` where Chrome supports them. `quality` is an integer from 0 through 100 for JPEG/WebP and is invalid for PNG. `clip` uses nonnegative CSS-pixel positions and positive sizes. `fullPage` and `clip` are mutually exclusive. Viewport `deviceScaleFactor` is the only render-scale control. Full-page dimensions depend on current layout and Chrome's image limits; prefer a fixed viewport/crop for deterministic output. In-memory screenshots are bounded to 16 MiB raw bytes; `ScreenshotTooLarge` directs callers to `screenshotToFile`, with no automatic retry or fallback.
|
|
326
|
-
|
|
327
|
-
Direct file output bypasses the 16 MiB sidecar response limit, not Chrome's image limits or the core's 64 MiB CDP message/frame budget (which includes base64 encoding and JSON). It is not an unbounded streaming screenshot API.
|
|
328
|
-
|
|
329
|
-
Capture dispatch requires negotiated methods and capabilities: `screenshotOptions`, `screenshotFile`, and `nativeRecording`. Native recording additionally requires a ready active page and an encoder supported by the actual Chrome build. Unsupported recording raises `RecordingUnsupported`; the SDK never switches engines/browser versions. Video is silent native MP4 with Chrome-selected codec, not a promise of H.264. FFmpeg is not an SDK runtime dependency. `fps` is an integral ceiling from 1 through 120, not deterministic fixed-rate playback; optional `maxWidth`/`maxHeight` are positive integers no greater than 2147483647. Screenshot crops/quality are not recording options.
|
|
330
|
-
|
|
331
|
-
Chrome 155.0.8059.39 can emit duplicate MP4 decoding timestamps, including
|
|
332
|
-
zero-duration prefixes and terminal tails. The sidecar validates the fragmented
|
|
333
|
-
MP4 before publication and applies bounded, lossless timing corrections.
|
|
334
|
-
Within a fragment, a run of `k` explicit zero durations becomes `k` one-tick
|
|
335
|
-
durations; the following duration decreases by `k` and must remain positive.
|
|
336
|
-
The run endpoint and later timestamps remain unchanged. A duplicate final sample
|
|
337
|
-
starting a new fragment advances by one tick, with its duration reduced by one
|
|
338
|
-
tick and matching fragment decode/index times corrected.
|
|
339
|
-
Encoded packets, sample count, file length and the final presentation endpoint
|
|
340
|
-
are preserved; clean recordings stay byte-identical.
|
|
341
|
-
|
|
342
|
-
This changes container timing metadata, not the codec or encoded frames. It
|
|
343
|
-
requires neither a Chrome fork nor FFmpeg. Unsupported or malformed containers,
|
|
344
|
-
insufficient donor duration and unresolved cross-fragment timing collisions
|
|
345
|
-
fail finalization without publishing a success-named file. Validation/repair uses the original
|
|
346
|
-
staging descriptor under a five-second deadline; failure retains partial-file
|
|
347
|
-
evidence. The core Rust raw-stream primitive remains unmodified Chrome output.
|
|
348
|
-
Release checks require strictly increasing finalized packet DTS and semantically
|
|
349
|
-
verified diagnostics, not merely a successful decoder exit. The
|
|
350
|
-
[qualification policy](#prerelease-qualification-and-publication) distinguishes
|
|
351
|
-
proven frame-rate-estimation advisories from failures without retiming the video.
|
|
352
|
-
|
|
353
|
-
`page.record` generates a UUID before dispatch, or accepts a caller-provided `recordingId`. There is one active recorder per target. A repeated start with the same ID and equivalent parameters recovers the existing record; changed parameters conflict instead of restarting. After a lost response use the ID rather than starting another recorder:
|
|
119
|
+
To install Chrome ahead of time, for example while building a Docker image:
|
|
354
120
|
|
|
355
121
|
```js
|
|
356
|
-
import {
|
|
357
|
-
|
|
358
|
-
try {
|
|
359
|
-
const recording = await page.record({ path: "./captures/session.mp4" });
|
|
360
|
-
await recording.stop();
|
|
361
|
-
} catch (error) {
|
|
362
|
-
if (!(error instanceof RecordingError)) throw error;
|
|
363
|
-
const recording = browser.recording(error.recordingId);
|
|
364
|
-
const record = await recording.status();
|
|
365
|
-
console.log(record.state, record.failure?.stage, record.failure?.partialPath);
|
|
366
|
-
}
|
|
122
|
+
import { installBrowser } from "@cbxss/eoka";
|
|
123
|
+
await installBrowser({ browserCacheDir: "/opt/eoka/cache" });
|
|
367
124
|
```
|
|
368
125
|
|
|
369
|
-
|
|
126
|
+
To drive a Chrome you already run, use `Browser.connect({ browserWSEndpoint })`. Closing the SDK leaves that browser running.
|
|
370
127
|
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
`
|
|
378
|
-
reset history.
|
|
379
|
-
|
|
380
|
-
`RecordingError` preserves `recordingId`, `record`, `failure`, `path`, `partialPath`, and `cleanupUncertain`, plus the normal request state/ID, cause, server data, and stderr evidence. Failed/cancelled stop outcomes are errors, never completed artifacts. A retained partial file is not the destination success name. Closing a tab/browser cancels unfinished recordings by default; explicitly await stop to save first. Disconnect/target-loss outcomes preserve honest failure/cleanup uncertainty; closing a borrowed session never kills the borrowed browser.
|
|
381
|
-
|
|
382
|
-
Error-carried recording records receive the same identity, output-path and completed-artifact checks as successful responses. Inconsistent records raise `Protocol`, retain the rejected wire evidence, and do not replace a handle's known record. Valid later evidence for the same failed terminal recording may still add partial-file or publication details.
|
|
128
|
+
| Environment variable | Purpose |
|
|
129
|
+
| --- | --- |
|
|
130
|
+
| `EOKA_BROWSER_CACHE_DIR` | Where Chrome is cached |
|
|
131
|
+
| `EOKA_RUNTIME_DIR` | Scratch directory for sessions |
|
|
132
|
+
| `EOKA_CHROME_PATH` | Use your own Chrome binary |
|
|
133
|
+
| `EOKA_SERVER_BIN` | Use your own `eoka-server` binary |
|
|
134
|
+
| `HTTPS_PROXY`, `NO_PROXY` | Proxy for the Chrome download |
|
|
383
135
|
|
|
384
|
-
|
|
136
|
+
## Errors
|
|
385
137
|
|
|
386
|
-
|
|
138
|
+
Every SDK error extends `EokaError` and has a stable `code`:
|
|
387
139
|
|
|
388
140
|
```js
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
browserWSEndpoint: "ws://127.0.0.1:9222/devtools/browser/your-browser-id",
|
|
392
|
-
});
|
|
141
|
+
import { EokaError } from "@cbxss/eoka";
|
|
142
|
+
|
|
393
143
|
try {
|
|
394
|
-
|
|
395
|
-
}
|
|
396
|
-
|
|
144
|
+
await page.fill("#name", "Ada");
|
|
145
|
+
} catch (error) {
|
|
146
|
+
if (error instanceof EokaError) console.error(error.code, error.message);
|
|
147
|
+
throw error;
|
|
397
148
|
}
|
|
398
149
|
```
|
|
399
150
|
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
Cleanup failures remain errors. The normal owned-Chrome cleanup path is graceful shutdown/sidecar EOF. Forced termination reports cleanup uncertainty: it cannot guarantee removal of runtime files or termination of descendants that left the owned process group/tree. Caller-owned profiles are never an SDK installation cache.
|
|
151
|
+
## Linux and Docker
|
|
403
152
|
|
|
404
|
-
|
|
153
|
+
Chrome needs its usual system libraries even in headless mode. On Debian:
|
|
405
154
|
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
155
|
+
```dockerfile
|
|
156
|
+
FROM node:24-trixie
|
|
157
|
+
RUN apt-get update && apt-get install -y --no-install-recommends \
|
|
158
|
+
ca-certificates fonts-liberation libasound2t64 libatk-bridge2.0-0t64 libatk1.0-0t64 \
|
|
159
|
+
libcairo2 libcups2t64 libdbus-1-3 libdrm2 libgbm1 libglib2.0-0t64 libnspr4 \
|
|
160
|
+
libnss3 libpango-1.0-0 libssl3t64 libx11-6 libxcb1 libxcomposite1 libxdamage1 \
|
|
161
|
+
libxext6 libxfixes3 libxkbcommon0 libxrandr2 \
|
|
162
|
+
&& rm -rf /var/lib/apt/lists/*
|
|
163
|
+
USER node
|
|
413
164
|
```
|
|
414
165
|
|
|
415
|
-
|
|
166
|
+
Run as a non-root user. On Ubuntu 23.10 and later, AppArmor may block Chrome's sandbox; see [Chromium's AppArmor notes](https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md). Alpine (musl) isn't supported.
|
|
416
167
|
|
|
417
|
-
|
|
168
|
+
## Examples
|
|
418
169
|
|
|
419
170
|
```sh
|
|
420
|
-
|
|
421
|
-
|
|
171
|
+
node node_modules/@cbxss/eoka/examples/install-browser.mjs
|
|
172
|
+
node node_modules/@cbxss/eoka/examples/offline.mjs
|
|
173
|
+
node node_modules/@cbxss/eoka/examples/capture.mjs ./captures
|
|
422
174
|
```
|
|
423
175
|
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
From the repository root use `mise run node-build`, `node-check`, or `node-consumer`; `node-stage-release -- --artifacts DIR --output NEWDIR --host-only`, `node-install-browser -- CACHE`, and `node-offline -- CACHE` expose the preparation/offline workflows. `npm run example:schema` retains the generated-schema example.
|
|
427
|
-
|
|
428
|
-
`mise.toml` pins the development and CI runtime to Node 24.21.0; CI reads that configuration rather than maintaining another Node version. Node types are pinned to `@types/node` 24.19.2. SDK and consumer fixtures target ES2024. Native-package staging inherits the SDK's `engines` field. The Node CI job checks the committed schema projection, accepted/rejected consumers, runtime regressions, and packed imports without requiring Rust or Chrome; the full local `node-check` additionally checks the schema against the Rust exporter. Native gates still require the explicit environment above.
|
|
429
|
-
|
|
430
|
-
## Prerelease qualification and publication
|
|
431
|
-
|
|
432
|
-
Core `0.7.2` is published on crates.io. Reserved prerelease versions are
|
|
433
|
-
server crate `0.6.1`, protocol crate `0.6.0`, wire protocol `1.3`, and SDK/native
|
|
434
|
-
npm packages `0.1.0-beta.3`. Source and ordinary staged packages remain private;
|
|
435
|
-
`--publication` is a separate, fail-closed staging mode.
|
|
436
|
-
|
|
437
|
-
### Pending beta.3
|
|
438
|
-
|
|
439
|
-
Beta.2 was published under `next` on 2026-10-18 from
|
|
440
|
-
`bd346b47d907ba9b71c603c4c94e77024c9f0fdd` (server `0.6.0`, core `0.7.0`).
|
|
441
|
-
Beta.3 rebuilds the native server as `0.6.1` against published core `0.7.2`,
|
|
442
|
-
which removes reflection-visible headless and platform leaks
|
|
443
|
-
([eoka#37](https://github.com/shrimp-software/eoka/pull/37)). No protocol, Chrome,
|
|
444
|
-
or SDK API changes are required. Native binaries must be rebuilt from the new
|
|
445
|
-
release source; repacking beta.2 binaries would omit the core fixes.
|
|
446
|
-
|
|
447
|
-
Beta.3 has not been published. Release authorization requires local SDK checks
|
|
448
|
-
and fresh five-platform native qualification (including Windows live-owner
|
|
449
|
-
recovery) in the publication workflow at the exact current protected `main` commit.
|
|
450
|
-
The readiness record's `ready` status means no recorded source defect blocks
|
|
451
|
-
qualification; it is not beta.3 runtime evidence or permission to publish.
|
|
452
|
-
The historical evidence below is retained and does not qualify beta.3.
|
|
453
|
-
|
|
454
|
-
`.github/workflows/qualify-node-release.yml` builds all five native targets and
|
|
455
|
-
qualifies installed tarballs outside the repository. GNU builds use Ubuntu 22.04
|
|
456
|
-
and enforce glibc ≤2.35; runtime checks use non-root hosted runners with Chrome's
|
|
457
|
-
sandbox enabled. Evidence includes fresh/cache/offline installation, artifact
|
|
458
|
-
rejection, verified input, image dimensions, finalized MP4 packet timestamps and
|
|
459
|
-
decode diagnostics, headed launch, owned cleanup, and borrowed-browser survival.
|
|
460
|
-
Failures retain recordings and diagnostics as workflow artifacts. FFmpeg/ffprobe
|
|
461
|
-
are qualification tools, not consumer dependencies.
|
|
462
|
-
|
|
463
|
-
The [lossless-repair preview](https://github.com/shrimp-software/eoka-tools/actions/runs/38612635401)
|
|
464
|
-
at tools `70b47e0ff27b271407c3073f5c1a389d87a5fd0a` and core
|
|
465
|
-
`9bae96b9cefa02794a4058ae54b67273ad453490` completed every runtime check on
|
|
466
|
-
Ubuntu 22.04 x64, Ubuntu 24.04 ARM64, macOS 15 x64/ARM64, and Windows 2025 x64.
|
|
467
|
-
All 50 one-attempt finalized recordings passed strict packet DTS and empty
|
|
468
|
-
decoder diagnostics; all 28 deterministic repair regressions passed on each
|
|
469
|
-
architecture. Image, sandbox, headed-launch and ownership checks also passed.
|
|
470
|
-
Those jobs ended **blocked** solely by the then-closed source readiness record.
|
|
471
|
-
The recording blocker is now cleared using that native evidence plus retained
|
|
472
|
-
defective-file repair/preservation proof, not passing live samples alone.
|
|
473
|
-
Registry-backed qualification and npm publication prerequisites remain separate.
|
|
474
|
-
Live recording still does not promise fixed-cadence export.
|
|
475
|
-
|
|
476
|
-
For local host-development evidence, not release qualification:
|
|
176
|
+
## Development
|
|
477
177
|
|
|
478
178
|
```sh
|
|
479
|
-
mise
|
|
480
|
-
|
|
179
|
+
mise install
|
|
180
|
+
npm ci --ignore-scripts --omit=optional
|
|
181
|
+
npm run build
|
|
182
|
+
npm test
|
|
481
183
|
```
|
|
482
184
|
|
|
483
|
-
|
|
484
|
-
against published registry core `0.7.2`, without a sibling checkout or Cargo
|
|
485
|
-
patch. It checks every native build's core identity and exact source lockfile,
|
|
486
|
-
including registry checksum
|
|
487
|
-
`bb088753bbef0585bcbaa1e868e4e59b5ee99db40844ba9cb3ec4822ca95e019`.
|
|
488
|
-
Local host-development staging and `--preview` remain separate from release
|
|
489
|
-
qualification and cannot authorize publication.
|
|
490
|
-
|
|
491
|
-
Every native build runs the live-runtime recovery regression, including Windows.
|
|
492
|
-
A held owner lock must preserve running operations; releasing it permits
|
|
493
|
-
interruption recovery. Only the platform's lock-contention error means the owner
|
|
494
|
-
is still alive; other lock failures remain errors.
|
|
495
|
-
|
|
496
|
-
`scripts/publication-readiness.json` records unresolved release defects. Clearing
|
|
497
|
-
a recording blocker requires deterministic repair/preservation regressions and
|
|
498
|
-
fresh five-platform qualification, not passing samples alone. Every Chrome pin
|
|
499
|
-
update must pass the complete recording suite on each architecture and ten
|
|
500
|
-
single-attempt native captures: four short/default-rate clips, two short
|
|
501
|
-
120-fps clips, one 1-fps clip, two two-second clips, and one multi-fragment clip.
|
|
502
|
-
Both artifact collection and publication independently require the actual running
|
|
503
|
-
Chrome version to match the pin, the complete schedule, published MP4 records,
|
|
504
|
-
strictly increasing packet DTS, and successful full decoding. A `passed` summary
|
|
505
|
-
alone is insufficient. One known FFmpeg MOV input-rate-estimation diagnostic may
|
|
506
|
-
be retained as a VFR advisory only when its adjacent packet indices and exact
|
|
507
|
-
timestamps match the probe and the declared positive packet duration exactly
|
|
508
|
-
reaches the next timestamp. Missing or inexact timing evidence, unknown
|
|
509
|
-
diagnostics, and nonzero decoder exits remain fatal. Raw probe/decoder logs are
|
|
510
|
-
preserved, and collection/publication independently recompute advisory
|
|
511
|
-
classifications; labels alone cannot authorize release. Probe logging includes
|
|
512
|
-
warnings. There is no retry-to-pass, hidden warning filtering, or retiming to
|
|
513
|
-
satisfy a frame-rate heuristic. The private MP4 correction remains limited to
|
|
514
|
-
the documented native timing defects; changing Chrome's container layout requires
|
|
515
|
-
renewed qualification, not an implicit generic muxer or transcoder.
|
|
516
|
-
|
|
517
|
-
`publish-node.yml` is manual, restricted to an exact current protected `main`
|
|
518
|
-
commit, and publishes only `0.1.0-beta.3` under `next` with npm provenance.
|
|
519
|
-
It requires an existing `npm-prerelease` environment with required reviewers
|
|
520
|
-
and a single allowed deployment branch, `main`. By default it uses only npm
|
|
521
|
-
trusted publishing through OIDC, requires self-review to be disabled, and
|
|
522
|
-
requires all six scoped package names to exist with trusted publishers configured
|
|
523
|
-
for this repository, workflow, and environment. There is no automatic token fallback.
|
|
524
|
-
|
|
525
|
-
For the first release, explicitly dispatch with `bootstrap: true` and an
|
|
526
|
-
environment-scoped `NPM_BOOTSTRAP_TOKEN` secret. Use a short-lived npm granular
|
|
527
|
-
token authorized to create and publish these scoped packages, with the permissions
|
|
528
|
-
required for unattended publication under the account's 2FA policy. Never commit
|
|
529
|
-
the token or pass it as a workflow input. Bootstrap still requires environment
|
|
530
|
-
reviewer approval, but permits the owner to approve their own deployment; this
|
|
531
|
-
exception does not apply to normal OIDC publication.
|
|
532
|
-
|
|
533
|
-
Only the bootstrap publish step receives the token. Its temporary private npm
|
|
534
|
-
configuration contains an environment-variable reference, not the token value.
|
|
535
|
-
Package verification and the final registry installation remain credential-free.
|
|
536
|
-
Bootstrap accepts an absent name only when both public and authenticated registry
|
|
537
|
-
reads return 404; an existing private package or an authorization failure aborts.
|
|
538
|
-
Both modes retain GitHub OIDC provenance and the same qualification checks.
|
|
539
|
-
|
|
540
|
-
Normal trusted publication still requires operator setup. On 2026-10-15, the
|
|
541
|
-
GitHub `npm-prerelease` environment allowed only branch `main`, but its sole
|
|
542
|
-
required reviewer was `cbxss` and `prevent_self_review` was `false`. The normal
|
|
543
|
-
publication gate therefore rejects that configuration. Before beta.3 publication,
|
|
544
|
-
an operator must enable `prevent_self_review: true`, arrange an independent
|
|
545
|
-
required reviewer, and confirm npm trusted publishers on all six existing packages
|
|
546
|
-
for owner `shrimp-software`, repository `eoka-tools`, workflow `publish-node.yml`,
|
|
547
|
-
and environment `npm-prerelease`. npm publisher settings were not independently
|
|
548
|
-
verified from public registry metadata; a provenance attestation does not prove
|
|
549
|
-
trusted-publisher configuration. Remove any remaining bootstrap environment
|
|
550
|
-
secret and revoke its token after confirming the migration. No environment,
|
|
551
|
-
secret, token, or npm setting is changed by this release preparation.
|
|
552
|
-
|
|
553
|
-
The bootstrap procedure above is historical first-publication guidance, not the
|
|
554
|
-
normal beta.3 release path or an automatic fallback. A bootstrap rerun after a
|
|
555
|
-
partial upload still needs the token and must follow same-run recovery below.
|
|
556
|
-
|
|
557
|
-
The publish job accepts only same-run, same-source qualified artifacts and
|
|
558
|
-
preflights all six registry versions before writing anything. Existing versions
|
|
559
|
-
are skipped only when their SHA-512 integrity matches the qualified tarball,
|
|
560
|
-
`next` already points at that version, npm registry signatures verify, and
|
|
561
|
-
keyless Sigstore provenance binds the exact artifact, source commit, protected
|
|
562
|
-
main workflow, manual event, and original workflow run. The pinned public Sigstore
|
|
563
|
-
verifier is release-tooling-only, not an SDK runtime dependency. Registry signature
|
|
564
|
-
checks use isolated installs with lifecycle scripts disabled; foreign-platform
|
|
565
|
-
packages are installed only for verification, never executed.
|
|
566
|
-
|
|
567
|
-
After a partial publication or lost publish response, rerun the failed jobs of
|
|
568
|
-
the **same workflow run**, retaining its qualified artifacts and unchanged current
|
|
569
|
-
`main` source. Verified existing uploads are preserved; only missing native
|
|
570
|
-
packages are published, followed by the SDK. Mismatched integrity, provenance,
|
|
571
|
-
tags, source, or unavailable registry evidence abort before any new upload.
|
|
572
|
-
There is no automatic publish retry or retagging. If source or artifacts changed,
|
|
573
|
-
do not bypass these checks: use a separately reviewed roll-forward release.
|
|
574
|
-
The final smoke checks a credential-free registry installation and provenance.
|
|
575
|
-
Its private runtime root stays short for Chrome's POSIX socket-path limits;
|
|
576
|
-
cache/state isolation and sandboxing remain enabled.
|
|
577
|
-
|
|
578
|
-
No tag, merge, or publication is part of PR preparation. Existing Rust publishing
|
|
579
|
-
workflows trigger on `main`; merging the version changes is a release action.
|
|
185
|
+
Releases are automatic: merge a version bump to `main` and approve the `npm-prerelease` deployment.
|