Move @epubknowledge/common from GitHub Packages to NPM

.github/workflows/release-package.yml

@@ -1,4 +1,4 @@
-name: Publish @epubknowledge/common package to Github Packages Registry
+name: Publish @epubknowledge/common package to npm
 on:
   push:
     branches:
@@ -9,24 +9,21 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      packages: write
     env:
-      NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
     steps:
       - uses: actions/checkout@v4
-      # Setup .npmrc file to publish to GitHub Packages
+      # Setup .npmrc file to publish to the public npm registry
       - uses: actions/setup-node@v4
         with:
           node-version: '22.x'
-          registry-url: 'https://npm.pkg.github.com'
-          always-auth: true
-          # Defaults to the user or organization that owns the workflow file
+          registry-url: 'https://registry.npmjs.org'
           scope: '@epubknowledge'
       - run: yarn install --frozen-lockfile
       - name: Run Vitest and capture results
         continue-on-error: true
         run: yarn test --reporter=json --outputFile=.test-results.json
       - name: Require 85% test pass rate
         run: node .github/scripts/verify-test-pass-rate.mjs .test-results.json 85
-      - run: yarn publish
+      - run: npm publish --access public

README.md

@@ -2,9 +2,9 @@
 
 Shared runtime helpers for the Epub Knowledge package ecosystem.
 
-## Install From NPM
+## Install
 
-After public testing is complete and this package is published to the public NPM registry, install it directly from NPM with no extra registry configuration or auth token:
+This package is intended to be published to the public npm registry, so consuming repos can install it with no extra registry configuration or GitHub token:
 
 pnpm:
 
@@ -26,71 +26,29 @@ npm install @epubknowledge/common
 
 Requires Node.js `>= 22.0.0`.
 
-## Install From GitHub Packages
+## Publishing
 
-This package is published to the GitHub Package Registry, so consuming repos must be configured to read the `@epubknowledge` scope from `https://npm.pkg.github.com`.
+Maintainers publish this package to npm, not GitHub Packages.
 
-### 1. Configure the registry
+### Publish prerequisites
 
-Add this to the consuming repo's `.npmrc`:
+- The `@epubknowledge` scope must exist on npm and the publisher must have permission to publish under it.
+- Local publishing uses `npm login`.
+- GitHub Actions publishing uses an `NPM_TOKEN` repository secret with permission to publish the package.
 
-```ini
-@epubknowledge:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
-```
-
-Commit the file, but never commit the token itself.
-
-If the consuming repo uses Yarn Berry (`v2+`), add the equivalent to `.yarnrc.yml`:
-
-```yaml
-npmScopes:
-  epubknowledge:
-    npmRegistryServer: 'https://npm.pkg.github.com'
-    npmAuthToken: '${GITHUB_TOKEN}'
-```
-
-### 2. Provide a token
+### Publish from CI
 
-The token needs `read:packages`. If the org uses SSO, the token must also be authorized for `epubknowledge`.
-
-Local development:
-
-```sh
-export GITHUB_TOKEN=ghp_your_token_here
-```
-
-GitHub Actions:
+The release workflow publishes to `https://registry.npmjs.org` with:
 
 ```yaml
-permissions:
-  contents: read
-  packages: read
-
-steps:
-  - run: npm install
-    env:
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+env:
+  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```
 
-### 3. Install the package
-
-pnpm:
+### Publish locally
 
 ```sh
-pnpm add @epubknowledge/common
-```
-
-yarn:
-
-```sh
-yarn add @epubknowledge/common
-```
-
-npm:
-
-```sh
-npm install @epubknowledge/common
+npm publish --access public
 ```
 
 ## Importing

docs/importing.md

@@ -1,20 +1,20 @@
 # Import Readiness Plan
 
-This package is intended to be consumed from other repositories through GitHub Packages.
+This package is intended to be consumed from other repositories through the public npm registry.
 
 ## Completed In This Repo
 
 - The build now emits `dist/` output instead of type-checking only.
 - The package export map matches the documented subpath modules.
-- The README now documents private-registry setup, supported import paths, and TypeScript usage.
+- The README documents public npm install usage, npm publish prerequisites, supported import paths, and TypeScript usage.
 
 ## Remaining Checklist
 
 1. Add a publish verification step in CI that runs `npm run build` and fails if `dist/` is missing.
 2. Add a packaging smoke test that runs `npm pack` and verifies the tarball contains `dist/*.js` and `dist/*.d.ts`.
 3. Add a consumer smoke test that installs the packed tarball into a temporary project and imports at least one runtime module plus one type-only module.
-4. Publish a new package version to GitHub Packages after the packaging checks pass.
-5. Verify install and import from a real consuming private repo using the README setup instructions.
+4. Publish a new package version to npm after the packaging checks pass.
+5. Verify install and import from a real consuming repo with a plain `npm`, `pnpm`, or `yarn` install and no private-registry setup.
 
 ## TypeScript Notes
 
@@ -30,3 +30,4 @@ Optional follow-up:
 
 - Add `typesVersions` if you need compatibility with older TypeScript package resolution behavior.
 - Add a root barrel export if consumers should be able to write `import { ... } from '@epubknowledge/common'` instead of subpath imports.
+- Add a local or CI check that fails early if the publishing account does not have access to the `@epubknowledge` npm scope.

package.json

@@ -38,7 +38,7 @@
     "node": ">=22.0.0"
   },
   "publishConfig": {
-    "registry": "https://npm.pkg.github.com",
+    "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "repository": {