Rename npm package to @joaoh82/sqlrite (scoped) (#30)

The unscoped `sqlrite` name on npm was rejected during the v0.1.5
canary setup with:

  403 Forbidden — Package name too similar to existing packages
  sqlite, sqlite3; try renaming your package to '@joaoh82/sqlrite'
  and publishing with 'npm publish --access=public' instead.

Levenshtein distance between "sqlrite" and "sqlite" is 1, which
trips npm's similar-names check. This is a registry-side policy,
not something we can work around with a suffix — `sqlrite-db`,
`sqlrite-node`, etc. all share the same stem and would hit the
same check.

**Switch to `@joaoh82/sqlrite`** — npm's own recommended fix, and
the standard pattern in the Node ecosystem (`@napi-rs/canvas`,
`@aws-sdk/client-s3`, `@swc/core`, `@types/*`). Scoped names
bypass the similarity check because the scope itself is a
namespace. The scope `@joaoh82` is auto-owned by the author's
npm user account, so no additional reservation step needed.

**Paralleling the crates.io workaround:** this is the same
registry-forced rename pattern we hit with `sqlrite-engine` on
crates.io (the `sqlrite` name there was taken by an unrelated
RAG-SQLite wrapper). Different registries, different reasons,
same pragmatic outcome — rename the *package* while keeping the
Rust import alias stable inside the codebase.

Files touched (12):

  Source & manifests:
    sdk/nodejs/package.json        — name: "@joaoh82/sqlrite"
    sdk/nodejs/package-lock.json   — refreshed via npm install
    sdk/nodejs/Cargo.toml          — description + comment
    sdk/nodejs/src/lib.rs          — module doc-comment

  Workflows:
    .github/workflows/release.yml  — npm URL + install/require
                                     snippets in release body,
                                     comment block explaining
                                     --access public requirement

  Docs:
    README.md                      — Phase 6c runbook summary
    docs/embedding.md              — distribution channel list
    docs/release-plan.md           — publish-channels table
    docs/release-secrets.md        — §3 npm trusted-publisher
                                     flow, now notes scoped names
                                     auto-own + skip bootstrap
                                     NPM_TOKEN dance
    docs/roadmap.md                — Phase 6c trusted-publishers
                                     bullet
    examples/README.md             — language→publish-channel
                                     table

sdk/nodejs/README.md gets a new "Why the scoped name?" callout
near the top explaining the rename to users reading the readme
cold.

No engine changes, no src/ changes outside the doc-comment in
sdk/nodejs/src/lib.rs. The underlying napi-rs binding is byte-
identical; only how npm addresses the tarball changed.

Next release canary (v0.1.5) will push the first real build
under the new name. First publish also auto-creates the scoped
package, so the trusted-publisher registration on npmjs.com can
run straight against the non-existent-yet package name (npm's
chicken-and-egg from the PyPI comparison doesn't apply to scoped
names under your own user scope).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: joaoh82

.github/workflows/release.yml

@@ -811,9 +811,11 @@ jobs:
 
       # Single atomic publish. `--provenance` signs the package
       # with a sigstore-backed attestation linking it to this
-      # workflow run. `--access public` because scoped packages
-      # default to private — we're using an unscoped name, but
-      # the flag is harmless and future-proofs against a rename.
+      # workflow run. `--access public` is REQUIRED because
+      # `@joaoh82/sqlrite` is a scoped package and scoped
+      # packages default to private; without the flag, npm
+      # would reject the upload for a free-tier account that
+      # can't host private packages.
       - name: Publish to npm
         working-directory: sdk/nodejs
         run: npm publish --provenance --access public
@@ -827,14 +829,14 @@ jobs:
           tag_name: sqlrite-node-v${{ needs.detect.outputs.version }}
           name: Node.js v${{ needs.detect.outputs.version }}
           body: |
-            Published to npm: https://www.npmjs.com/package/sqlrite/v/${{ needs.detect.outputs.version }}
+            Published to npm: https://www.npmjs.com/package/@joaoh82/sqlrite/v/${{ needs.detect.outputs.version }}
 
             ```bash
-            npm install sqlrite@${{ needs.detect.outputs.version }}
+            npm install @joaoh82/sqlrite@${{ needs.detect.outputs.version }}
             ```
 
             ```javascript
-            const { Database } = require('sqlrite');
+            const { Database } = require('@joaoh82/sqlrite');
 
             const db = new Database(':memory:');
             db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
@@ -892,7 +894,7 @@ jobs:
             - 🔧 [C FFI](../../releases/tag/sqlrite-ffi-v${{ needs.detect.outputs.version }}) — prebuilt `libsqlrite_c` for Linux x86_64/aarch64, macOS aarch64, Windows x86_64
             - 🖥️ [Desktop](../../releases/tag/sqlrite-desktop-v${{ needs.detect.outputs.version }}) — unsigned installers for Linux (AppImage + deb), macOS (dmg aarch64), Windows (msi)
             - 🐍 [Python](../../releases/tag/sqlrite-py-v${{ needs.detect.outputs.version }}) → [PyPI](https://pypi.org/project/sqlrite/${{ needs.detect.outputs.version }}/) — abi3-py38 wheels for Linux x86_64/aarch64, macOS aarch64, Windows x86_64 + sdist
-            - 🟢 [Node.js](../../releases/tag/sqlrite-node-v${{ needs.detect.outputs.version }}) → [npm](https://www.npmjs.com/package/sqlrite/v/${{ needs.detect.outputs.version }}) — N-API bindings with prebuilt `.node` binaries for Linux x86_64/aarch64, macOS aarch64, Windows x86_64
+            - 🟢 [Node.js](../../releases/tag/sqlrite-node-v${{ needs.detect.outputs.version }}) → [npm](https://www.npmjs.com/package/@joaoh82/sqlrite/v/${{ needs.detect.outputs.version }}) — N-API bindings with prebuilt `.node` binaries for Linux x86_64/aarch64, macOS aarch64, Windows x86_64
 
             _WASM / Go SDKs land as their publish jobs come online (Phases 6h–6i)._
 

README.md

@@ -224,7 +224,7 @@ Lockstep versioning — one dispatch bumps every product to the same `vX.Y.Z`. T
 
 - [x] **6a — Bump script**: `scripts/bump-version.sh` rewrites the version string in ten manifests (7 TOML, 3 JSON) in a single pass; semver-validated, idempotent, cross-platform (BSD + GNU sed). Runnable locally for rehearsing a release: `./scripts/bump-version.sh 0.2.0 && cargo build && git diff`.
 - [x] **6b — CI**: `.github/workflows/ci.yml` runs on every PR + push to main. Seven parallel jobs: `rust-build-and-test` (Linux/macOS/Windows × cargo build + test), `rust-lint` (fmt + clippy + doc), `python-sdk` (Linux/macOS/Windows × maturin develop + pytest in a venv), `nodejs-sdk` (Linux/macOS/Windows × napi build + node --test), `go-sdk` (Linux/macOS × cargo build sqlrite-ffi + go test), `wasm-build` (wasm-pack + size report), `desktop-build` (npm ci + Tauri Rust compile). Cargo / npm / pip caching for fast PR turnaround.
-- [x] **6c — Trusted publisher setup + branch protection runbook**: [`docs/release-secrets.md`](docs/release-secrets.md) captures the one-time web-UI setup — crates.io token in the `release` environment, OIDC trusted publishers on PyPI (`sqlrite`) and npm (`sqlrite` + `sqlrite-wasm`), GitHub `release` environment with required reviewer, branch protection on `main` requiring 14 CI jobs + 1 review. No code changes — executable as-is, ready to run through in the GitHub + registry UIs.
+- [x] **6c — Trusted publisher setup + branch protection runbook**: [`docs/release-secrets.md`](docs/release-secrets.md) captures the one-time web-UI setup — crates.io token in the `release` environment, OIDC trusted publishers on PyPI (`sqlrite`) and npm (`@joaoh82/sqlrite` + `sqlrite-wasm` — Node binding is scoped because npm's similarity check rejects the unscoped name against `sqlite`/`sqlite3`), GitHub `release` environment with required reviewer, branch protection on `main` requiring 14 CI jobs + 1 review. No code changes — executable as-is, ready to run through in the GitHub + registry UIs.
 - [x] **6d — Release PR + skeleton publish**: two workflows under `.github/workflows/`. `release-pr.yml` (manual dispatch with version input → bump-version.sh → PR), `release.yml` (fires on `release: v<semver>` merge commit → `tag-all` + `publish-crate` + `publish-ffi` matrix [linux x86_64/aarch64, macOS aarch64, windows x86_64] + umbrella release). Idempotent tag creation so "Re-run failed jobs" works after partial failures. `cargo publish` gated by the `release` environment's required-reviewer rule. First canary: `v0.1.1`.
 - [ ] **6e — Desktop publish**: add `publish-desktop` to `release.yml` — Tauri build matrix → unsigned `.AppImage` / `.deb` / `.dmg` / `.msi` → GitHub Release
 - [ ] **6f — Python SDK publish**: `maturin-action` → abi3 wheels for manylinux x86_64/aarch64 + macOS universal + Windows x86_64 → PyPI via OIDC

docs/embedding.md

@@ -217,7 +217,7 @@ Phase 6 lands GitHub Actions CI + release automation:
 
 - **crates.io** — `sqlrite-engine` crate (published under a different name from the `sqlrite` lib target because the short name was already taken; users `cargo add sqlrite-engine` but still write `use sqlrite::…`)
 - **PyPI** — `sqlrite` wheels (manylinux x86_64/aarch64, macOS universal, Windows x86_64)
-- **npm** — `sqlrite` (Node) + `sqlrite-wasm` (browser) packages
+- **npm** — `@joaoh82/sqlrite` (Node) + `sqlrite-wasm` (browser) packages
 - **Go modules** — `sdk/go/v*` git tags
 - **GitHub Releases** — Tauri desktop builds + C FFI prebuilt libraries
 

docs/release-plan.md

@@ -73,7 +73,7 @@ GitHub Releases by product ("show me every Python release").
 | Rust engine     | `sqlrite-vX.Y.Z`       | crates.io + GitHub Release                       |
 | C FFI shim      | `sqlrite-ffi-vX.Y.Z`   | GitHub Release (per-platform tarballs)           |
 | Python SDK      | `sqlrite-py-vX.Y.Z`    | PyPI + GitHub Release                            |
-| Node.js SDK     | `sqlrite-node-vX.Y.Z`  | npm + GitHub Release                             |
+| Node.js SDK     | `sqlrite-node-vX.Y.Z`  | npm (`@joaoh82/sqlrite`) + GitHub Release        |
 | Go SDK          | `sdk/go/vX.Y.Z`        | Git tag (no registry) + GitHub Release assets    |
 | WASM            | `sqlrite-wasm-vX.Y.Z`  | npm (`sqlrite-wasm`) + GitHub Release            |
 | Desktop app     | `sqlrite-desktop-vX.Y.Z` | GitHub Release (unsigned installers)           |

docs/release-secrets.md

@@ -105,48 +105,51 @@ release, status flips to "active".
 
 ## 3. npm trusted publishers (two packages)
 
-**Why two:** we publish `sqlrite` (Node.js bindings from
+**Why two:** we publish `@joaoh82/sqlrite` (Node.js bindings from
 `sdk/nodejs/`) and `sqlrite-wasm` (browser bindings from
 `sdk/wasm/`) as separate npm packages. Each needs its own
 trusted-publisher record.
 
-### 3a. Reserve `sqlrite` on npm
+**Why the scoped name on the Node.js package:** npm's registry
+rejects the unscoped `sqlrite` name because of a similarity check
+against the existing `sqlite` / `sqlite3` packages (levenshtein
+distance 1). Scoping under `@joaoh82` (the author's npm user
+scope) bypasses the check cleanly — same pattern as `@napi-rs/*`,
+`@swc/core`, etc. Discovered during the v0.1.5 canary attempt;
+rename PR landed before the retry. Applies to the Node.js
+package only; `sqlrite-wasm` may or may not hit the same check
+when 6h lands (if it does, rename to `@joaoh82/sqlrite-wasm`).
 
-1. Log in at <https://www.npmjs.com/>.
-2. Search for `sqlrite` — confirm it's not taken. (If it is,
-   we'll rename — update `sdk/nodejs/package.json`'s `name` +
-   `napi.name` to something like `@joaoh82/sqlrite` and file an
-   issue.)
+### 3a. Reserve `@joaoh82/sqlrite` on npm
 
-### 3b. Trusted publisher for `sqlrite`
+1. Log in at <https://www.npmjs.com/> as `joaoh82`.
+2. Scoped packages under your user scope are auto-owned — no
+   manual name reservation step required. First-time publish
+   against the trusted publisher will create the package.
+
+### 3b. Trusted publisher for `@joaoh82/sqlrite`
 
 npm's trusted publishing flow:
 
-1. From the package page (after first manual publish, or via
-   <https://www.npmjs.com/package/sqlrite> once pre-registered),
-   click **Settings** → **Trusted Publishers**.
+1. Go to <https://www.npmjs.com/settings/~/packages> (or your
+   profile → Packages) → **Trusted Publishers** tab.
 2. **Add a new publisher**:
+   - **Package name**: `@joaoh82/sqlrite`
    - **Publisher**: GitHub Actions
    - **Organization or user**: `joaoh82`
    - **Repository**: `rust_sqlite`
    - **Workflow filename**: `release.yml`
    - **Environment**: `release`
 3. Save.
 
-**npm's chicken-and-egg:** npm doesn't offer a "pending
-publisher" mode like PyPI. A package must exist before you can
-add a trusted publisher for it. First-time publish workaround:
-
-- Use a classic npm access token (generate one scoped to publish
-  for `sqlrite` only) for the very first publish only.
-- Store it temporarily as `NPM_TOKEN` in the `release`
-  environment's secrets.
-- After the first publish succeeds, add the trusted publisher
-  via the UI, then delete `NPM_TOKEN` from the secrets.
-- On the next release, OIDC takes over automatically.
-
-Document the temporary token in a pinned issue so it gets
-rotated out once OIDC is live.
+**npm's chicken-and-egg, resolved for scoped packages:** For
+unscoped names (like the abandoned `sqlrite` attempt), npm
+requires the package to already exist before you can add a
+trusted publisher — first publish needs a temporary `NPM_TOKEN`.
+For scoped packages under your own user scope, npm auto-owns
+the scope, and the trusted-publisher registration works against
+the future package before it exists. First CI publish creates
+it cleanly with OIDC. **No temporary token needed.**
 
 ### 3c. Repeat for `sqlrite-wasm`
 

docs/roadmap.md

@@ -360,7 +360,7 @@ One-time non-code setup — the state lives in registry web UIs + GitHub setting
 
 1. **crates.io API token** → `CRATES_IO_TOKEN` in the `release` environment's secrets (crates.io doesn't support OIDC yet, so this is the only long-lived token in the pipeline).
 2. **PyPI trusted publisher** pointed at `release.yml` / environment `release` — short-lived OIDC tokens, no secret to leak.
-3. **npm trusted publishers** for both `sqlrite` (the Node binding) and `sqlrite-wasm` (the browser binding). npm doesn't have a pending-publisher mode like PyPI, so the runbook captures the first-release bootstrap: temporary `NPM_TOKEN`, then swap to OIDC.
+3. **npm trusted publishers** for both `@joaoh82/sqlrite` (the Node binding — scoped because npm rejected the unscoped `sqlrite` name as too similar to `sqlite`/`sqlite3`) and `sqlrite-wasm` (the browser binding). Scoped packages under your own user scope auto-own the name, so the trusted-publisher flow works without a bootstrap `NPM_TOKEN`. See `docs/release-secrets.md` §3 for the full flow.
 4. **GitHub `release` environment** — required reviewer (maintainer), `main`-only deployments, scoped secrets. Acts as a second human-in-the-loop gate after the Release PR merge but before any registry write.
 5. **Branch protection on `main`** — require 14 CI status checks green + 1 review + conversation resolution. Admin bypass left available for emergencies.
 

examples/README.md

@@ -6,12 +6,12 @@ Phase 5 lands these incrementally — each sub-phase fills in one language. The
 
 | Language | Status | SDK published | Directory |
 |----------|--------|---------------|-----------|
-| Rust     | ✅ Phase 5a       | crates.io (Phase 6c) | [`rust/`](rust/)     |
+| Rust     | ✅ Phase 5a       | crates.io as `sqlrite-engine` (Phase 6d) | [`rust/`](rust/)     |
 | C (FFI)  | ✅ Phase 5b       | GitHub Releases (Phase 6d) | [`c/`](c/)           |
-| Python   | ✅ Phase 5c       | PyPI (Phase 6e)      | [`python/`](python/) |
-| Node.js  | ✅ Phase 5d       | npm (Phase 6e)       | [`nodejs/`](nodejs/) |
-| Go       | ✅ Phase 5e       | Go modules (Phase 6e)| [`go/`](go/)         |
-| WASM     | ✅ Phase 5g       | npm as `sqlrite-wasm` (Phase 6e) | [`wasm/`](wasm/)     |
+| Python   | ✅ Phase 5c       | PyPI as `sqlrite` (Phase 6f) | [`python/`](python/) |
+| Node.js  | ✅ Phase 5d       | npm as `@joaoh82/sqlrite` (Phase 6g) | [`nodejs/`](nodejs/) |
+| Go       | ✅ Phase 5e       | Go modules (Phase 6i) | [`go/`](go/)         |
+| WASM     | ✅ Phase 5g       | npm as `sqlrite-wasm` (Phase 6h) | [`wasm/`](wasm/)     |
 
 See [docs/roadmap.md](../docs/roadmap.md) for what each sub-phase delivers.
 

sdk/nodejs/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.4"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"
-description = "Node.js bindings for the SQLRite embedded database engine. Ships the `sqlrite` npm package with prebuilt `.node` binaries."
+description = "Node.js bindings for the SQLRite embedded database engine. Ships the `@joaoh82/sqlrite` npm package with prebuilt `.node` binaries."
 repository = "https://github.com/joaoh82/rust_sqlite"
 license = "MIT"
 
@@ -14,8 +14,10 @@ license = "MIT"
 #
 # Named `sqlrite_nodejs` so the rlib doesn't collide with the root
 # `sqlrite` crate or with the FFI crate's `sqlrite_c`. The user-
-# facing import is `const { Database } = require('sqlrite')` — that
-# naming lives in package.json, not Cargo.
+# facing import is `const { Database } = require('@joaoh82/sqlrite')`
+# — scoped because the unscoped `sqlrite` name was rejected by npm
+# as too similar to `sqlite`/`sqlite3`. That naming lives in
+# package.json, not Cargo.
 [lib]
 name = "sqlrite_nodejs"
 crate-type = ["cdylib", "rlib"]

sdk/nodejs/README.md

@@ -1,12 +1,13 @@
-# sqlrite (Node.js)
+# @joaoh82/sqlrite (Node.js)
 
 Node.js bindings for [SQLRite](https://github.com/joaoh82/rust_sqlite) — a small, embeddable SQLite clone written in Rust. Shape follows [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) (sync API, row-as-object), so Node developers who've used that library can pick this up without reading the docs.
 
+> **Why the scoped name?** npm's registry rejected the unscoped `sqlrite` name as too similar to the existing `sqlite` / `sqlite3` packages. Scoping under `@joaoh82` (my npm user scope) bypasses that check cleanly — same pattern as `@napi-rs/canvas`, `@swc/core`, `@aws-sdk/client-s3`.
+
 ## Install
 
 ```bash
-# From npm (once Phase 6e's CI/CD release pipeline is live):
-npm install sqlrite
+npm install @joaoh82/sqlrite
 
 # From source in a clone of the repo:
 cd sdk/nodejs
@@ -17,7 +18,7 @@ npm run build         # produces sqlrite.<platform>-<arch>.node
 ## Quick tour
 
 ```js
-import { Database } from 'sqlrite';
+import { Database } from '@joaoh82/sqlrite';
 
 // File-backed or in-memory (use `":memory:"` to match better-sqlite3).
 const db = new Database('foo.sqlrite');