feat: build platform/arch specific npm packages

support libpact_ffi & pact-js-core node bindings to be published in seperate npm packages.

these are segmented by os-arch-libc

users should not need to require these automatically, npm should determine the required
optional dependency to download at install time.

supported_platforms

  "@pact-foundation/pact-core-darwin-arm64": "16.0.0",
    "@pact-foundation/pact-core-darwin-x64": "16.0.0",
    "@pact-foundation/pact-core-linux-arm64-glibc": "16.0.0",
    "@pact-foundation/pact-core-linux-arm64-musl": "16.0.0",
    "@pact-foundation/pact-core-linux-x64-glibc": "16.0.0",
    "@pact-foundation/pact-core-linux-x64-musl": "16.0.0",
    "@pact-foundation/pact-core-win32-x64": "16.0.0"

.github/workflows/build-and-test.yml

@@ -173,11 +173,11 @@ jobs:
 
       - if: ${{ matrix.docker == true && matrix.alpine == true && matrix.arch == 'amd64' && matrix.os == 'ubuntu-latest' }}
         name: test linux amd64 musl
-        run: docker run -v $PWD:/home --platform linux/${{ matrix.arch }} --rm node:${{ matrix.node-version }}-alpine bin/sh -c 'apk add bash curl gcompat file && cd /home && /home/script/ci/unpack-and-test.sh'
+        run: docker run -v $PWD:/home --platform linux/${{ matrix.arch }} --rm node:${{ matrix.node-version }}-alpine bin/sh -c 'apk add jq gettext-envsubst bash curl gcompat file && cd /home && /home/script/ci/unpack-and-test.sh'
 
       - if: ${{ matrix.docker == true && matrix.alpine == true && matrix.arch == 'arm64' && matrix.os == 'ubuntu-24.04-arm' }}
         name: test linux arm64 musl
-        run: docker run -v $PWD:/home --platform linux/${{ matrix.arch }} --rm node:${{ matrix.node-version }}-alpine bin/sh -c 'apk add bash curl file protoc protobuf-dev && cd /home && /home/script/ci/unpack-and-test.sh'
+        run: docker run -v $PWD:/home --platform linux/${{ matrix.arch }} --rm node:${{ matrix.node-version }}-alpine bin/sh -c 'apk add jq gettext-envsubst bash curl file protoc protobuf-dev && cd /home && /home/script/ci/unpack-and-test.sh'
 
   release_dry_run:
     runs-on: ubuntu-latest

.gitignore

@@ -72,3 +72,6 @@ reports
 tmp
 .tmp
 test/__testoutput__
+
+# platform-arch specific packages
+@pact-foundation/*

.npmignore

@@ -90,4 +90,11 @@ DEVELOPER.md
 RELEASING.md
 test.js
 tsconfig.build.json
-tsconfig.json
+tsconfig.json
+
+# Standalone Binaries - Published as seperate packages
+@pact-foundation/
+
+# Cross packaging files
+Makefile
+package.json.tmpl

DEVELOPER.md

@@ -4,13 +4,23 @@ Pact-Js-Core uses FFI bindings from the pact-reference project, which are prebui
 
 Do this and you should be 👌👌👌:
 
-```
+```sh
 bash script/ci/prebuild.sh
-npm ci --ignore-scripts
+supported_platforms=$(./script/ci/build-opt-dependencies.sh determine_platform) 
+./script/ci/build-opt-dependencies.sh build
+./script/ci/build-opt-dependencies.sh link
 npm run build
-npm test
+npm run test
 ```
 
+set supported platform to one of these values
+
+- `linux-x64`
+- `linux-arm64`
+- `darwin-x64`
+- `darwin-arm64`
+- `windows-x64`
+
 _notes_ - 
 
 As a developer, you need to run `bash script/ci/prebuild.sh` to
@@ -32,61 +42,103 @@ Alternatively you can run the following, which will not create a prebuild, but i
 bash script/download-libs.sh
 npm ci
 npm run build
-npm test
+npm run test
 ```
 
-### Linux x86_64 Task
+## Creating Platform specific packages
 
-#### Pre Reqs
+We create cross-platform and architecture binaries which are published individually to NPM, and consumed in this project.
 
-1. x86_64 Machine
-   1. ARM64 Mac - If you have Rosetta (MacOS)
+### Download prebuilt binaries for all platforms
 
-### CI Locally
+```sh
+./script/ci/build_opt_dependencies.sh libs v15.2.1
+```
 
-1. Docker/Podman
-2. Act
+Tag is optional and defaults to latest
+
+This will run the following script, which will grab the latest prebuilt binaries from GitHub.
 
 ```sh
-act --container-architecture linux/amd64 -W .github/workflows/build-and-test.yml --artifact-server-path tmp
+FETCH_ASSETS=true ./script/ci/check-release-libs.sh --fetch-assets -t v15.2.1
 ```
 
-### MacOS ARM64 Task
+### Building all platform specific npm packages
 
-#### Pre Reqs
+```sh
+./script/ci/build_opt_dependencies.sh build
+```
+
+### Building individual platform specific npm package
 
-1. Arm64 Mac
-2. Cirrus-Cli
-3. Tart.run
+Supported platforms are
 
+- linux-x64-glibc
+- linux-arm64-glibc
+- linux-x64-musl
+- linux-arm64-musl
+- darwin-x64
+- darwin-arm64
+- win32-x64
+
+You can detect your platform with
 
 ```sh
-cirrus run --output github-actions macos_arm --artifacts-dir tmp
+./script/ci/build-opt-dependencies.sh determine_platform
 ```
 
-### Linux ARM64 Task
+You can build with one
 
-#### Pre Reqs
+```sh
+supported_platforms=$(./script/ci/build-opt-dependencies.sh determine_platform) ./script/ci/build-opt-dependencies.sh build
+```
 
-1. Arm64 Machine
+or all
 
-### CI Locally
+```sh
+./script/ci/build-opt-dependencies.sh build
+```
 
-1. Arm64 Machine
-2. Docker / Podman
-3. Cirrus-Cli
+### Linking arch specific package, for your local build
 
+Make link will try to link all available packages, for all available platforms, and will link any that apply
 
 ```sh
-cirrus run --output github-actions linux_arm --artifacts-dir tmp
+./script/ci/build-opt-dependencies.sh
 ```
 
-#### Publishing Assets
+You can scope it with `supported_platforms`
+
+```sh
+supported_platforms=$(./script/ci/build-opt-dependencies.sh determine_platform) ./script/ci/build-opt-dependencies.sh link
+```
 
-MacOS ARM64
+### Publishing packages
 
-`cirrus run --output github-actions macos_arm --artifacts-dir tmp --environment GITHUB_TOKEN=$GITHUB_TOKEN --environment CIRRUS_RELEASE=test --environment CIRRUS_REPO_FULL_NAME=pact-foundation/pact-js-core;`
+Dry run publishing optional packages, (default)
+
+```sh
+./script/ci/build-opt-dependencies.sh publish
+```
 
-Linux ARM64
+Publishing packages with `--dry-run` option removed.
 
-`cirrus run --output github-actions linux_arm --artifacts-dir tmp --environment GITHUB_TOKEN=$GITHUB_TOKEN --environment CIRRUS_RELEASE=test --environment CIRRUS_REPO_FULL_NAME=pact-foundation/pact-js-core;`
+```sh
+PUBLISH=true ./script/ci/build-opt-dependencies.sh publish
+```
+
+### Linux x86_64 Task
+
+#### Pre Reqs
+
+1. x86_64 Machine
+   1. ARM64 Mac - If you have Rosetta (MacOS)
+
+### CI Locally
+
+1. Docker/Podman
+2. Act
+
+```sh
+act --container-architecture linux/amd64 -W .github/workflows/build-and-test.yml --artifact-server-path tmp
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pact-foundation/pact-core",
-  "version": "15.2.1",
+  "version": "16.0.0",
   "description": "Core of @pact-foundation/pact. You almost certainly don't want to depend on this directly.",
   "main": "src/index.js",
   "homepage": "https://github.com/pact-foundation/pact-js-core#readme",
@@ -42,8 +42,18 @@
   "publishConfig": {
     "access": "public"
   },
+  "optionalDependencies": {
+    "@pact-foundation/pact-core-darwin-arm64": "16.0.0",
+    "@pact-foundation/pact-core-darwin-x64": "16.0.0",
+    "@pact-foundation/pact-core-linux-arm64-glibc": "16.0.0",
+    "@pact-foundation/pact-core-linux-arm64-musl": "16.0.0",
+    "@pact-foundation/pact-core-linux-x64-glibc": "16.0.0",
+    "@pact-foundation/pact-core-linux-x64-musl": "16.0.0",
+    "@pact-foundation/pact-core-win32-x64": "16.0.0"
+  },
   "dependencies": {
     "check-types": "7.4.0",
+    "detect-libc": "^2.0.3",
     "node-gyp-build": "^4.6.0",
     "pino": "^8.7.0",
     "pino-pretty": "^9.1.1",

package.json.tmpl

@@ -0,0 +1,20 @@
+{
+  "name": "${node_pkg}",
+  "version": "${pkg_version}",
+  "description": "Platform/arch specific libpact_ffi binaries for @pact-foundation/pact-core",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/pact-foundation/pact-js-core.git"
+  },
+  "scripts": {},
+  "author": "Yousaf Nabi <you@saf.dev>",
+  "homepage": "https://github.com/pact-foundation/pact-js-core#readme",
+  "os": [
+    "${node_os}"
+  ],
+  ${libc}
+  "cpu": [
+    "${node_arch}"
+  ]
+}

script/ci/build-and-test.sh

@@ -19,11 +19,15 @@ fi
 
 node --version
 npm --version
+# Update main package.json optional dependencies versions, with those created earlier
+current_platform=$("$SCRIPT_DIR"/build-opt-dependencies.sh determine_platform)
+supported_platforms="$current_platform" "$SCRIPT_DIR"/build-opt-dependencies.sh update
+# update lockfile post building updated opt deps
+npm ci --ignore-scripts || npm i --ignore-scripts
+# Link os/arch specific npm package, for running os/arch system
 
-npm ci --ignore-scripts
-
+supported_platforms="$current_platform" "$SCRIPT_DIR"/build-opt-dependencies.sh link
 npm run format:check
 npm run lint
 npm run build
-npm run test
-ls -1
+npm run test