Skip to content

Release v1.4.1: make the documented install paths real, and stop the pipeline lying about why it failed - #3

Merged
celikgo merged 2 commits into
mainfrom
fix/release-npm-auth-diagnostics
Aug 20, 2026
Merged

Release v1.4.1: make the documented install paths real, and stop the pipeline lying about why it failed#3
celikgo merged 2 commits into
mainfrom
fix/release-npm-auth-diagnostics

Conversation

@celikgo

@celikgo celikgo commented Aug 19, 2026

Copy link
Copy Markdown
Owner

The Actions tab has shown red since 2026-07-17 and two of the four install
paths the README teaches have never worked. Both have the same root cause.

What was actually wrong

The v1.4.0 Release run failed on npm publish:

npm error 404 Not Found - PUT https://registry.npmjs.org/webmobai-mcp
npm error 404  'webmobai-mcp@1.4.0' is not in this registry.

That reads as a misnamed package. It was not. The registry answers an
unauthenticated or under-scoped request to create a package with 404
rather than 401, on purpose, so a token cannot be used to enumerate names —
so an expired NPM_TOKEN and a typo in name produce byte-identical logs.
The credential was the cause: the secret was minted 2026-04-12, the run was
2026-07-17.

Because the publish never landed, npm install -g webmobai-mcp and the
npx -y webmobai-mcp invocation in the Claude Desktop / Claude Code MCP config
have both 404'd for every reader since. The MCP path is the one that
demonstrates the AI-native design, and it was the one that did not resolve.

The packaging itself was never broken — mcp-server/package.json already
declared the name, main, and all seven bin entries, and a local
npm publish --dry-run produces a clean 203-file tarball with every binary
resolving.

Changes

release.yml

  • Is this version already on the registry? runs before anything needing a
    credential. Publishing nothing requires no permission to do it, and demanding
    a valid token in order to then decide there is nothing to do is how a green
    release turns red.
  • npm credentials are valid runs npm whoami and fails with the token named
    as the cause and the page to fix it on, instead of the 404 folklore above.
  • Publish to npm is now skipped when the version is already up. npm versions
    are immutable, so re-running a shipped release was a guaranteed E403.
  • verify-npm is a new job with no actions/checkout. Every other job
    tests the working copy; this one tests what a stranger receives. It resolves
    the version from the registry, runs npx -y webmobai-mcp --help, does the
    README's global install, runs webmobai-doctor, and asserts all seven
    binaries reach PATH. A file present on the runner but missing from files in
    package.json now fails CI rather than failing a reader.

docs-links.yml — the npmjs.com exclusion was justified by a readme-claims
job in ci.yml that does not exist under that name and never touched the
registry. The exclusion is fine; the justification was not. It now points at
verify-npm, which actually does the thing.

v1.4.1 — a distribution release, no functional change. v1.4.0's tag is
public and its release already carries four macOS assets, so re-pointing it
would rewrite history to fix what a patch version fixes cleanly. Version bumped
in lockstep across package.json, mcp-server/package.json, both lockfiles,
tauri.conf.json, Cargo.toml, Cargo.lock, and server.json (twice), which
is what the existing Tag and package version agree gate checks.

Also landing with this tag

The release matrix already gained ubuntu-22.04 and windows-latest after the
failed run, so v1.4.1 is the first tag that ships .AppImage/.deb and
.msi/.exe alongside the macOS .dmg. All five previous releases were
macOS-only.

Verification

  • scripts/check-doc-claims.mjs: 21 claims across 3 files still match — 51
    tools, 7 binaries, 219 tests.
  • npm publish --dry-run: clean tarball, all seven bin targets resolve.
  • node dist/index.js --help / --version: pass, and report 1.4.1.
  • Every run: block in both workflows parses under bash -n; both files parse
    as YAML.

Not covered here

NPM_TOKEN in repository secrets is still the dead credential. This PR makes
the failure legible and makes the job idempotent, but a valid token is required
before Actions can publish on its own.

celikgo and others added 2 commits August 20, 2026 02:28
… install paths

The v1.4.0 Release run went red on `npm publish` with

    npm error 404 Not Found - PUT https://registry.npmjs.org/webmobai-mcp
    npm error 404  'webmobai-mcp@1.4.0' is not in this registry.

which reads as "the package is misnamed" and is not. The registry answers an
unauthenticated or under-scoped *create-package* request with 404 rather than
401 on purpose, so that a token cannot be used to enumerate names. An expired
NPM_TOKEN and a typo in `name` produce byte-identical output. The token was
the cause: the secret was minted 2026-04-12 and the run was 2026-07-17.

Nothing here papers over that — the publish step is required, so it stays.
What changes is that the next person does not have to know the 404 folklore:

- `npm credentials are valid` runs `npm whoami` before the publish and fails
  with the token as the stated reason and the page to fix it on.
- `Publish to npm` no-ops when the version is already on the registry. npm
  versions are immutable, so re-running a release that published is a
  guaranteed E403 — the Actions tab should not go red for a job that already
  succeeded.
- `verify-npm` is a new job with no `actions/checkout`. Every other job tests
  the working copy; this one tests what a stranger receives. It resolves the
  published version, runs `npx -y webmobai-mcp --help` (the invocation in the
  Claude Desktop and Claude Code config blocks), does the README's global
  install, runs `webmobai-doctor`, and asserts all seven `bin` entries reach
  PATH. A file present on the runner but absent from `files` in package.json
  now fails here instead of failing the reader.

docs-links.yml excluded npmjs.com on the grounds that a `readme-claims` job in
ci.yml verified the package against the registry. No such job exists under
that name and the one it meant checks counts in prose, not the registry. The
exclusion is fine; the justification was not. It now points at verify-npm,
which actually does the thing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HDC1iraSA12i16CWbHtAMm
No functional change to the tools, the CLIs, or the desktop app. This version
exists so that the documented ways of getting WebMobAI resolve: `webmobai-mcp`
reaches npm, and the desktop build ships for Linux and Windows rather than
macOS alone.

v1.4.0 cannot be reused for this. Its tag is public and its release already
carries four macOS assets, so re-pointing it would rewrite history to fix a
problem a new patch version fixes cleanly.

Bumped together, because a version that disagrees with itself is the bug the
"Tag and package version agree" gate exists to catch: package.json,
mcp-server/package.json, both lockfiles, src-tauri/tauri.conf.json,
src-tauri/Cargo.toml, src-tauri/Cargo.lock, and server.json (twice — the MCP
server version and the npm package version it points at).

.claude/skills/README.md states the version the server advertises, which is a
live claim rather than a historical one, so it moves too. The v1.4.0 references
in CHANGELOG.md, ROADMAP.md, FEATURES.md and USER_MANUAL.md describe what
shipped in that release and correctly stay put.

`scripts/check-doc-claims.mjs` still passes: 21 claims across 3 files, 51 tools,
7 binaries, 219 tests.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HDC1iraSA12i16CWbHtAMm
@celikgo
celikgo merged commit 1d81f69 into main Aug 20, 2026
5 checks passed
@celikgo
celikgo deleted the fix/release-npm-auth-diagnostics branch August 20, 2026 06:37
celikgo added a commit that referenced this pull request Aug 20, 2026
…ishing (#4)

The `npm credentials are valid` step added in #3 runs `npm whoami` before
publishing, to turn npm's misleading 404-on-PUT into a plain statement that the
token is dead. That is right for the token path and wrong for the one this
repository should be moving to.

Under trusted publishing there is no long-lived credential at all: the npm CLI
exchanges the Actions OIDC token for a short-lived one during publish, and
attests provenance without being asked. `npm whoami` has nothing to answer with
and exits non-zero — so a repository configured exactly as npm recommends would
fail this gate and never reach the publish it was ready to do. The check would
have become a new cause of the red pipeline it was written to explain.

It now returns early when NPM_TOKEN is unset, and only enforces `whoami` when a
token is actually present. Diagnostic on the path that has a credential to
diagnose; silent on the path that does not.

This is not hypothetical maintenance. npm restricted 2FA-bypass granular access
tokens on 2026-07-31: creating a package and setting its access now require an
interactive 2FA challenge, and `npm publish --access public` against a name that
has never been published does both. Direct publish is withdrawn from these
tokens entirely in January 2027. The failure message now points at configuring a
trusted publisher rather than at minting another token that will stop working.

https://github.blog/changelog/2026-07-31-restricting-npm-bypass-2fa-granular-access-tokens/


Claude-Session: https://claude.ai/code/session_01HDC1iraSA12i16CWbHtAMm

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant