feat: scaffold @socketaddon/iocraft publish pipeline

.github/workflows/provenance.yml

@@ -0,0 +1,50 @@
+name: 📦 Publish
+
+# Dependencies:
+#   - SocketDev/socket-registry/.github/workflows/provenance.yml
+#
+# socket-addon is a publish-only repo. The .node binaries are downloaded
+# from socket-btm's GitHub Releases by scripts/publish.mts at publish
+# time, verified against embedded SHA-256 checksums, then republished
+# under the @socketaddon/* scope.
+#
+# No setup-script is needed — packages are static, the publish script
+# pulls binaries on demand.
+
+on:
+  workflow_dispatch:
+    inputs:
+      dist-tag:
+        description: 'npm dist-tag (latest, next, beta, canary, backport, etc.)'
+        required: false
+        default: 'latest'
+        type: string
+      debug:
+        description: 'Enable debug output'
+        required: false
+        default: '0'
+        type: choice
+        options:
+          - '0'
+          - '1'
+      publish-without-sfw:
+        description: 'Publish directly to npm, bypassing Socket firewall shims'
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    uses: SocketDev/socket-registry/.github/workflows/provenance.yml@b74ae5083d662df0045731bcf35b4e54b1e03d37 # main
+    with:
+      debug: ${{ inputs.debug }}
+      dist-tag: ${{ inputs.dist-tag }}
+      publish-script: 'publish:ci'
+      publish-without-sfw: ${{ inputs.publish-without-sfw }}
+      use-trusted-publishing: true
+    secrets:
+      SOCKET_API_KEY: ${{ secrets.SOCKET_API_KEY }}

docs/trusted-publisher-migration.md

@@ -0,0 +1,109 @@
+# npm Trusted-Publisher Migration
+
+This is a one-time set of npm UI + GitHub steps to move trusted-publisher
+ownership of the `@socketaddon/iocraft*` packages from `SocketDev/socket-cli`
+to `SocketDev/socket-addon`. After this is done, `socket-cli`'s OIDC
+token can no longer publish iocraft packages — only this repo can.
+
+## Prerequisites
+
+- npm 2FA enabled on the org (already done)
+- Admin role on the `@socketaddon` npm org
+- Admin role on `SocketDev/socket-addon` GitHub repo
+- All 9 placeholders already published at `0.0.0`:
+  - `@socketaddon/iocraft`
+  - `@socketaddon/iocraft-darwin-arm64`
+  - `@socketaddon/iocraft-darwin-x64`
+  - `@socketaddon/iocraft-linux-arm64`
+  - `@socketaddon/iocraft-linux-arm64-musl`
+  - `@socketaddon/iocraft-linux-x64`
+  - `@socketaddon/iocraft-linux-x64-musl`
+  - `@socketaddon/iocraft-win32-arm64`
+  - `@socketaddon/iocraft-win32-x64`
+
+> Note: the legacy names `@socketaddon/iocraft-win-arm64` and
+> `@socketaddon/iocraft-win-x64` are deprecated and not part of this
+> migration.
+
+## Step 1 — Add socket-addon as a trusted publisher (per package)
+
+For each of the 9 packages above:
+
+1. https://www.npmjs.com/package/<pkg>/access (signed in as an admin)
+2. Scroll to **Trusted Publishers**
+3. Click **Add trusted publisher**
+4. Fill in:
+   - **Publisher**: GitHub Actions
+   - **Repository owner**: `SocketDev`
+   - **Repository name**: `socket-addon`
+   - **Workflow filename**: `provenance.yml`
+   - **Environment** *(optional, leave blank — we don't gate publishing on a GH environment)*
+5. Save.
+
+This authorizes `SocketDev/socket-addon`'s `provenance.yml` workflow to
+publish that package via OIDC. **Do not remove the existing socket-cli
+trusted publisher yet** — it remains the active publisher until step 3.
+
+## Step 2 — Run a dry publish from socket-addon
+
+Locally:
+
+```sh
+cd ~/projects/socket-addon
+pnpm install
+pnpm run publish:dry
+```
+
+This runs `scripts/publish.mts --dry-run` — it stages each per-platform
+package, downloads the `.node` from socket-btm, verifies the SHA-256,
+and runs `pnpm publish --dry-run`. Nothing hits the registry.
+
+Verify the output shows:
+
+- `Using iocraft release: iocraft-20260424-18f0f46` *(or current tag)*
+- For each per-platform package:
+  - `downloading iocraft-...-<suffix>.node from socket-btm@<tag>`
+  - `verified iocraft-...-<suffix>.node (<bytes> bytes, sha-256 ok)`
+  - `--- 9 packages will be published`
+
+If any checksum fails, the run aborts before any publish. That's the
+fail-loudly intent.
+
+## Step 3 — Run the workflow once (real publish)
+
+Once the dry run is clean:
+
+1. Bump the placeholder versions from `0.0.0` to e.g. `1.0.0-pre.0` in
+   each of the 9 `package.json` files (all per-platform packages must
+   advance in lockstep with the umbrella's `optionalDependencies` pins).
+2. Commit + push.
+3. Trigger the workflow:
+   - https://github.com/SocketDev/socket-addon/actions/workflows/provenance.yml
+   - **Run workflow** → branch `main` → `dist-tag = pre`
+4. Watch the run. Each per-platform package publishes via OIDC, then
+   the umbrella publishes last.
+
+## Step 4 — Remove socket-cli as a trusted publisher (per package)
+
+After the socket-addon publish succeeds and you've verified the new
+versions are installable (`npm install @socketaddon/iocraft@pre`), come
+back to each package's `/access` page and remove the
+`SocketDev/socket-cli` trusted-publisher entry.
+
+This is the irreversible step: socket-cli can no longer publish these
+packages after it's removed.
+
+## Step 5 — Update socket-cli to consume @socketaddon/iocraft
+
+See the companion task in socket-cli — strip
+`scripts/download-iocraft-binaries.mts`, the `iocraft` block in
+`provenance.yml`, and add `@socketaddon/iocraft: <version>` as a
+dependency in `packages/cli/package.json`.
+
+## Rollback
+
+If something goes wrong between steps 1 and 4, the original socket-cli
+trusted publisher is still active — re-trigger socket-cli's
+provenance workflow with `iocraft = true` to publish a hotfix. After
+step 4 the rollback path requires re-adding socket-cli as a trusted
+publisher, which is reversible but takes a couple minutes per package.

package.json

@@ -14,7 +14,10 @@
     "lint": "oxlint",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
-    "test": "vitest run"
+    "test": "vitest run",
+    "publish": "node scripts/publish.mts",
+    "publish:ci": "node scripts/publish.mts --tag ${DIST_TAG:-latest}",
+    "publish:dry": "node scripts/publish.mts --dry-run"
   },
   "devDependencies": {
     "@socketsecurity/lib": "catalog:",

packages/iocraft-darwin-arm64/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Socket Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/iocraft-darwin-arm64/README.md

@@ -0,0 +1,16 @@
+# @socketaddon/iocraft-darwin-arm64
+
+iocraft native bindings for **macOS Apple Silicon (arm64)**.
+
+This is a per-platform package. You almost certainly want
+[`@socketaddon/iocraft`](https://www.npmjs.com/package/@socketaddon/iocraft)
+instead, which loads the matching per-platform binary automatically.
+
+```sh
+npm install @socketaddon/iocraft
+```
+
+The `.node` binary in this package is built in
+[`SocketDev/socket-btm`](https://github.com/SocketDev/socket-btm) under
+`packages/iocraft-builder/` and republished from a signed GitHub Release
+with SHA-256 verification.

packages/iocraft-darwin-arm64/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@socketaddon/iocraft-darwin-arm64",
+  "version": "0.0.0",
+  "description": "iocraft native bindings for macOS Apple Silicon (arm64).",
+  "license": "MIT",
+  "main": "iocraft.node",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "iocraft.node"
+  ],
+  "os": ["darwin"],
+  "cpu": ["arm64"],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SocketDev/socket-addon.git"
+  },
+  "author": {
+    "name": "Socket Inc",
+    "email": "eng@socket.dev",
+    "url": "https://socket.dev"
+  },
+  "homepage": "https://github.com/SocketDev/socket-addon",
+  "bugs": {
+    "url": "https://github.com/SocketDev/socket-addon/issues"
+  },
+  "keywords": [
+    "socket",
+    "iocraft",
+    "tui",
+    "terminal",
+    "native",
+    "bindings",
+    "darwin",
+    "arm64"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

packages/iocraft-darwin-x64/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Socket Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/iocraft-darwin-x64/README.md

@@ -0,0 +1,16 @@
+# @socketaddon/iocraft-darwin-x64
+
+iocraft native bindings for **macOS Intel (x64)**.
+
+This is a per-platform package. You almost certainly want
+[`@socketaddon/iocraft`](https://www.npmjs.com/package/@socketaddon/iocraft)
+instead, which loads the matching per-platform binary automatically.
+
+```sh
+npm install @socketaddon/iocraft
+```
+
+The `.node` binary in this package is built in
+[`SocketDev/socket-btm`](https://github.com/SocketDev/socket-btm) under
+`packages/iocraft-builder/` and republished from a signed GitHub Release
+with SHA-256 verification.

packages/iocraft-darwin-x64/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@socketaddon/iocraft-darwin-x64",
+  "version": "0.0.0",
+  "description": "iocraft native bindings for macOS Intel (x64).",
+  "license": "MIT",
+  "main": "iocraft.node",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "iocraft.node"
+  ],
+  "os": ["darwin"],
+  "cpu": ["x64"],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SocketDev/socket-addon.git"
+  },
+  "author": {
+    "name": "Socket Inc",
+    "email": "eng@socket.dev",
+    "url": "https://socket.dev"
+  },
+  "homepage": "https://github.com/SocketDev/socket-addon",
+  "bugs": {
+    "url": "https://github.com/SocketDev/socket-addon/issues"
+  },
+  "keywords": [
+    "socket",
+    "iocraft",
+    "tui",
+    "terminal",
+    "native",
+    "bindings",
+    "darwin",
+    "x64"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

packages/iocraft-linux-arm64-musl/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Socket Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/iocraft-linux-arm64-musl/README.md

@@ -0,0 +1,16 @@
+# @socketaddon/iocraft-linux-arm64-musl
+
+iocraft native bindings for **Linux arm64 (musl)**.
+
+This is a per-platform package. You almost certainly want
+[`@socketaddon/iocraft`](https://www.npmjs.com/package/@socketaddon/iocraft)
+instead, which loads the matching per-platform binary automatically.
+
+```sh
+npm install @socketaddon/iocraft
+```
+
+The `.node` binary in this package is built in
+[`SocketDev/socket-btm`](https://github.com/SocketDev/socket-btm) under
+`packages/iocraft-builder/` and republished from a signed GitHub Release
+with SHA-256 verification.