@rosepetal/barcode-engine-client 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,209 @@
+# @rosepetal/barcode-engine-client
+
+Node client of `rp-barcode serve`, the persistent decode and verify service of
+[rosepetal-barcode-sdk](https://github.com/rosepetal-ai/rosepetal-barcode-sdk) (Go, static binary). It spawns the
+binary once, talks protocol 1 over its stdin/stdout (length-prefixed frames, see below), keeps one request timer per
+request (`decode`, `verify`, `analyze`), bounds what is in flight, restarts a dead engine with a growing wait and
+stops it cleanly. CommonJS, no runtime dependencies, Node >= 18.
+
+It exists as a package because `node-red-contrib-barcode-reader` and `node-red-contrib-barcode-verifier` share the same
+binary and must share **one engine process per Node-RED runtime**: both `require` this module and `acquire()` its
+singleton, so the process is started by the first decode or verify and stopped by the last `release()`.
+
+## Install
+
+```sh
+npm i @rosepetal/barcode-engine-client
+```
+
+The binary is not in this package. It comes from one of the platform packages, declared here as optional
+dependencies and installed next to the client when the registry that carries them is configured for the
+`@rosepetal` scope (they are published by the SDK's release workflow, `0.2.x` = the SDK version):
+
+- `@rosepetal/barcode-engine-linux-x64`
+- `@rosepetal/barcode-engine-linux-arm64`
+
+each with the static binary at `bin/rp-barcode` (musl uses the same one). Without them, `RP_BARCODE_ENGINE` points at
+an `rp-barcode` binary (SDK >= 0.2.0), or `rp-barcode` is looked up in `PATH`. `resolveBinary()` tries in that order:
+
+1. `RP_BARCODE_ENGINE` (explicit: when set and unusable the start fails, it never falls back),
+2. the platform package for `<platform>-<arch>` (`${process.platform}-${process.arch}`: `linux-x64`, `linux-arm64`),
+   along this module's `node_modules` chain,
+3. `rp-barcode` in `PATH`,
+
+and throws `EngineError` `unavailable` listing every place it tried. The binary runs as `<path> serve`.
+
+## API
+
+```js
+const rp = require('@rosepetal/barcode-engine-client');
+
+// One shared engine per process (started lazily by the first decode or verify)
+const engine = rp.acquire();                 // refs + 1, returns the singleton (rp.getEngine() returns it without counting)
+rp.setEngineOptions({ defaultTimeoutMs: 8000 });   // merges into the singleton's options (see the table below)
+
+const image = { width: 640, height: 480, channels: 1, colorSpace: 'GRAY' };   // encoding defaults to "raw"
+const { symbols, image: size, timing } = await engine.decode(image, pixels, { symbologies: ['EAN13'], effort: 'robust' },
+                                                              { timeoutMs: 5000 });
+// symbols: schema-1.0 symbol objects as the SDK writes them ([] when none); size: {width, height}; timing: {totalMs, decodeMs, queuedMs}
+
+const { result } = await engine.verify(image, pixels, { region: { x: 120, y: 80, w: 400, h: 200, orientation: 0 },
+                                                         options: { spec: { kind: 'gs1_table', table: '1' } },
+                                                         acquisition: { milsPerPixel: 3.25 } }, { timeoutMs: 10000 });
+// result: the schema-1.0 VerifyResult as the SDK writes it (status, reasons, symbol, quality, dimensions, gs1, report, …)
+
+await rp.release();                          // refs - 1; the last release() stops the process
+```
+
+After its `release()`, a holder must not call `decode()`/`verify()`/`ping()` on the engine: a request after the last
+release starts a process that no release will stop (it lives until the runtime exits). The reader node guards this
+with its `rpClosed` flag; the verifier needs the same rule.
+
+`engine.decode(image, payload, options, { timeoutMs })`: `image` is `{width, height, channels, colorSpace, encoding?}`
+(`encoding` `raw`, payload = packed rows of `width·height·channels` bytes, `colorSpace` `GRAY|RGB|BGR|RGBA|BGRA`; or
+`encoded`, payload = a JPEG/PNG/BMP/TIFF file); `options` is the `decodeOptions` object of the SDK's result schema 1.0
+§12.1 (known keys only, every key optional, the server rejects unknown ones); `timeoutMs` (default
+`defaultTimeoutMs`) is the client's timer and also travels as `deadlineMs` (sent as an integer number of milliseconds,
+rounded up; the timer is capped at 2^31 − 1 ms). A payload larger than the engine's advertised `limits.maxPayload` is
+refused with `invalid_input` before anything is sent.
+
+`engine.verify(image, payload, { region, options, acquisition, analyze }, { timeoutMs })` (SDK service 2D): the
+ISO/IEC 15416 verification of the symbol in `region`. `image`/`payload` as `decode`; `region` is
+`{x, y, w, h, orientation}` in image pixels: `w`/`h` are extents along the image axes whatever the orientation,
+`orientation` is the reading direction in clockwise degrees (a multiple of 90, default 0). The client checks and
+rounds the region before sending (`Math.round` on `x`, `y`, `w`, `h`; the orientation never rounded, an integer
+multiple of 90 normalised to 0/90/180/270, so −90 is 270 and 450 is 90; `w` and `h` at least 2 px after rounding; a
+missing or non-finite coordinate, an orientation that is not an integer multiple of 90 (`90.4` included) or an
+unknown key is `invalid_input` without anything sent), so a
+normalised region scaled to pixels never reaches the server as a fraction; the bounds against the image are the
+server's check (`barcode: region {…} outside image WxH`). `options` is the `verifyOptions` object of the schema
+(§12.2, known keys only, every key optional; the server refuses unknown keys and values outside their vocabularies)
+and `acquisition` the `acquisition` object (§12.3, `calibration` §12.4) or `null` (no physical scale, 660 nm, no
+calibration); `analyze: true` sends `analyze` and the result carries `scans`. `timeoutMs` as `decode` (the verifier
+node passes its own 10 s). Resolves `{ result, image, timing }`: `result` is the `VerifyResult` (or
+`AnalysisResult`) exactly as the SDK writes it, `report` included; `status: "not_detected"` is a result, not an
+error; `image` the real size; `timing` is `{totalMs, verifyMs, queuedMs}`. An engine whose hello does not list the op
+(an SDK 0.2.0 built before 2D) rejects with `unsupported` before anything is sent.
+
+Other members of an `Engine`: `start()` (resolves with the hello; idempotent, never two processes), `ping()` (a
+liveness probe the server answers without queueing), `stop()` (drain → `shutdown` → SIGTERM → SIGKILL, resolves when
+the child is gone; what was pending rejects with `exited`), `running`, `hello`, `pid`, `refs`, `lastError`,
+`configure(options)`.
+
+`new Engine(options)` and `setEngineOptions(options)` take (defaults in `DEFAULTS`):
+
+| Option | Default | Meaning |
+|---|---|---|
+| `command`, `args` | `null`, `['serve']` | `null` resolves the binary at every start (`RP_BARCODE_ENGINE` may change) |
+| `env` | `null` (= `process.env`) | environment of the child |
+| `maxQueue` | 128 | requests in flight before `overloaded` |
+| `maxBufferedBytes` | 256 MiB | bytes still unwritten to the engine's stdin before `overloaded` (an idle pipe always takes one frame) |
+| `helloTimeoutMs` | 5000 | wait for the hello after the spawn |
+| `defaultTimeoutMs` | 5000 | `timeoutMs` of `decode`/`verify`/`ping` when not given (the verifier node passes its own 10 s) |
+| `backoff` | `{initialMs: 1000, maxMs: 30000}` | wait before restarting after a failed start or a crash, doubled each time, reset by a good hello |
+| `drainMs`, `exitMs` | 2000, 1000 | `stop()`: wait for the requests in flight; wait after `shutdown`, then after SIGTERM |
+
+Every failure is an `EngineError` with a `code`:
+
+| `code` | From | When |
+|---|---|---|
+| `unavailable` | client | no binary, no hello in time, the spawn failed, or a start inside the wait after a failure (`retry in N ms`) |
+| `protocol` | client | hello with another `protocol`, a bad frame from the engine, a reply that carries a payload, a `verify` reply without a `result` object, an unprompted `bad_frame` |
+| `exited` | client | the process went away with the request in flight, `stop()`, or a `stop()` that landed while the request waited for a broken child to die (the engine is not relaunched for a holder that let go) |
+| `timeout` | client | the request timer |
+| `overloaded` | client or server | `maxQueue` / `maxBufferedBytes` reached, or the server's queue is full |
+| `invalid_input` | client or server | client: `image` is not an object, `payload` is not a Buffer/Uint8Array, the `region` of a `verify` is not an object, has an unknown key, a missing or non-finite coordinate, a side under 2 px or an orientation that is not a multiple of 90, the payload exceeds the engine's `limits.maxPayload` (all refused before anything is sent) or the header cannot be framed; server: verbatim (a bad `image`, a payload of another length, an unknown `options`/`acquisition` key or a value outside its vocabulary, a region outside the image), the engine keeps running |
+| `unsupported` | client or server | client: the hello does not list `verify`/`analyze` (refused before anything is sent); server: verbatim, the engine keeps running |
+| `deadline`, `internal` | server | verbatim, the engine keeps running |
+
+Events of an `Engine` (never `'error'`): `'started'` `({pid, hello, source})` after each good hello (`source` is
+`RP_BARCODE_ENGINE`, the package name, `PATH` or `command`), `'exit'` `({code, signal})` when the child is gone,
+`'stderr'` `(text)` with the engine's log lines.
+
+Also exported: `resolveBinary({paths})`, `ENGINE_PACKAGES`, `PROTOCOL` (1), `DEFAULT_TIMEOUT_MS`, `INSTALL_HINT` (the
+sentence a node prints next to an `unavailable`), the frame codec `encodeFrame`, `FrameParser`, `FramingError`, and
+`formatName(symbol)` / `FORMAT_NAMES` / `ADDON_NAMES`: the `format` string the nodes print for a schema-1.0 symbol
+(ZXing's spelling, `EAN-2`/`EAN-5` for the add-ons by their `identifier`), so the reader and the verifier agree.
+
+## Protocol 1 in short
+
+Specified in the SDK's [`docs/service.md`](https://github.com/rosepetal-ai/rosepetal-barcode-sdk/blob/dev/docs/service.md)
+(a private repository: the link works for the organisation's members); this client implements it as written.
+
+- Everything on stdin/stdout is a frame: `u32 BE headerLen | u32 BE payloadLen | header (UTF-8 JSON object) | payload`.
+  `headerLen` 2..1 MiB, `payloadLen` <= `maxPayload` (256 MiB by default, `--max-payload`).
+- The server writes a `hello` first (`id` 0): `protocol`, `sdk`, `engineVersion`, `schema`, `ops`, `workers`, `queue`,
+  `limits {maxHeader, maxPayload, maxSide, maxPixels}`. The client requires `protocol === 1`.
+- `decode` (`id`, `image`, `options`, `deadlineMs`) with the pixels as payload → `{id, ok: true, image, symbols, timing}`,
+  never with a payload. `ping` → `{id, ok: true}`, answered without queueing. `shutdown` → `{id, ok: true}`; what is in
+  flight finishes, what is still queued is answered `unsupported`, then exit 0.
+- `verify`/`analyze` (`id`, `image`, `region`, `options`, `acquisition`, `deadlineMs`) with the pixels as payload →
+  `{id, ok: true, image, result, timing}`: `result` the schema-1.0 `VerifyResult`/`AnalysisResult` (`report`
+  included; `not_detected` is a result), `timing` `{totalMs, verifyMs, queuedMs}`. Since SDK 0.2.0 with 2D: the hello
+  lists them in `ops` (a 2A engine answers `unsupported`; the client checks `ops` first).
+- Errors: `{id, ok: false, error: {code, message}}` with `invalid_input`, `unsupported`, `overloaded`, `deadline`,
+  `internal` (the server keeps running) or `bad_frame` (`id` 0, then the server exits 3: the stream is no longer
+  delimited, the client restarts it).
+- EOF on stdin: the server decodes what is in flight **and what is already queued** (a queued request whose
+  `deadlineMs` expired answers `deadline`), then exits 0; a broken stdout is exit 1.
+- Replies come out in the order they finish; `deadlineMs` only rejects a request still queued when it expires.
+
+## Testing with the fake engine
+
+`FAKE_ENGINE` is the path of `test/fake-engine.js`, a fake `rp-barcode serve` in Node (protocol 1, one fixed EAN-13
+per decode, canned `VerifyResult`s for `verify`/`analyze`) that ships with the package so the tests of the nodes
+never need a real binary:
+
+```js
+const rp = require('@rosepetal/barcode-engine-client');
+process.env.RP_BARCODE_ENGINE = rp.FAKE_ENGINE;      // the shared engine spawns the fake (executable, #!/usr/bin/env node)
+rp.setEngineOptions({ helloTimeoutMs: 3000, backoff: { initialMs: 50, maxMs: 200 }, drainMs: 500, exitMs: 300 });
+// or, for an engine of your own: new Engine({ command: process.execPath, args: [rp.FAKE_ENGINE, 'serve'], env: { ...process.env, FAKE_DELAY_MS: '300' } })
+```
+
+Its behaviour is driven by the child's environment: `FAKE_DELAY_MS`, `FAKE_CRASH_AFTER`, `FAKE_PROTOCOL`,
+`FAKE_GARBAGE`, `FAKE_OVERLOAD`, `FAKE_NO_HELLO`, `FAKE_IGNORE_STOP`, `FAKE_MAX_PAYLOAD`, `FAKE_REPLY_PAYLOAD`,
+`FAKE_STALL`, and for the verifier `FAKE_VERIFY_STATUS=pass|fail|not_detected` (the canned result of
+`verify`/`analyze`, default `pass`), `FAKE_DECODE_SYMBOLS=n` (copies of the EAN-13 a `decode` answers, default 1,
+`0` = none) and `FAKE_OPS=a,b,c` (the ops the hello announces: `FAKE_OPS=decode,ping,shutdown` is a 2A engine
+without `verify`), all documented at the top of the file. `verify`/`analyze` answer the canned results of
+`test/fixtures/*.json` (`verify-pass.json`, `verify-fail.json`, `verify-not-detected.json`, `analyze-pass.json`:
+what the CLI printed for synthetic renders, generated by `test/tools/make-verify-fixtures.sh` from the SDK
+checkout, shipped in the package so a consumer's tests can `require('@rosepetal/barcode-engine-client/test/fixtures/verify-pass.json')`),
+with the request's region echoed in `result.symbol.region`; `analyze` under `fail`/`not_detected` is the verify
+fixture plus `scans: []`. Like the real server it takes `encoding` `raw` (`payload.length === width·height·channels`)
+and `encoded` (a non-empty PNG/JPEG/BMP/TIFF file told by its magic bytes; the size answered is the PNG's IHDR,
+else the header's `width`/`height`; with no size at all the bounds check is skipped), rejects unknown keys inside
+`image`, `region`, `options` and `acquisition`, a region under 2 px, off a multiple of 90 or outside the image, and a
+non-integer `deadlineMs` with `invalid_input` and the server's wording (`options: json: unknown field "scans"`);
+unlike it, it matches keys case-sensitively (the binary's `encoding/json` also takes `TryInvert` for `tryInvert`),
+does not check option values against their vocabularies (`edition: "2020"` passes the fake, the server refuses it)
+nor that `options`/`acquisition` (and their `spec`/`calibration`) are objects.
+
+## Development
+
+```sh
+cd clients/node
+npm test        # node --test: framing (10) + engine (32, verify/analyze included) on the fake engine, no child left behind
+```
+
+To regenerate the canned results after a change of the SDK's verification (never by `npm test`):
+
+```sh
+make build GO=/usr/local/go/bin/go                                             # from the SDK root: bin/rp-barcode
+cd clients/node && RP_BARCODE=../../bin/rp-barcode sh test/tools/make-verify-fixtures.sh
+```
+
+No lockfile: the package has zero dependencies, so there is nothing to install and nothing to `npm ci`; the tests need
+only Node's built-ins and the package's own files. The optional platform packages are resolved by each consumer's own
+install (its lock), never through a lock of this package.
+
+CI runs `npm test` in the `node-client` job of `.github/workflows/ci.yml` (Node 22, no install step). The Go targets
+of the repository (`make lint`, `make test`) do not touch this directory.
+
+The SDK's release workflow (`.github/workflows/publish-engine.yml`, on every `v*` tag) publishes this package to
+npmjs (`npm test`, then `npm publish --access public` with `NPM_TOKEN`; a prerelease tag goes to the dist-tag of its
+preid) in the same run that publishes the platform packages to the private registry, and installs both in clean
+containers afterwards (`scripts/verify-published.sh`). Its version is pinned to the SDK's by `TestNpmClientVersion`.
+Until the first tag (`v0.2.0`, `docs/release-runbook.md`) install it from a checkout
+(`npm i /path/to/rosepetal-barcode-sdk/clients/node`).