Skip to content

fix(packaging): shebang bins and block empty publishes (#18) - #19

Merged
Markgatcha merged 1 commit into
mainfrom
fix/issue-18-packaging
Nov 3, 2026
Merged

Markgatcha merged 1 commit into
mainfrom
fix/issue-18-packaging

Conversation

@Markgatcha

Copy link
Copy Markdown
Owner

Root cause

Two independent defects made npx -y <pkg> --transport stdio fail on macOS/Linux:

  1. No shebang on published bins. npm symlinks JS bin entries on POSIX, so the kernel fell back to /bin/sh and tried to parse the bundle as shell.
  2. Missing dist/ in core@0.2.1. Every server pinned to it failed with ERR_MODULE_NOT_FOUND.

While reproducing #1 I found a third defect: every server and the CLI compared process.argv[1] to import.meta.url directly. Node reports the real path in import.meta.url but keeps the symlink path in process.argv[1], so even with a shebang the entry point never matched and the process exited silently (exit 0, no output).

Changes

  • Add a #!/usr/bin/env node banner for every declared bin in the shared tsdown.config.ts.
  • Add isMainModule(import.meta.url) to core, resolving both paths with realpathSync, and use it from all 31 servers plus the CLI.
  • Add scripts/verify-packages.mjs as a prepack guard: missing dist files, missing bin shebangs, and incomplete npm tarballs now fail the publish.
  • Run verify:pack in CI and release, plus a Linux-only verify:launch smoke test that boots every bin through a .bin symlink.
  • Add a changeset so the fixed packages are republished.

Verification

  • pnpm build, pnpm typecheck, pnpm test, pnpm lint:ox: pass (35 build tasks, 37 test tasks).
  • pnpm verify:pack: 35 packages, 33 bin targets, tarball contents checked.
  • pnpm verify:launch: all 33 bins start through a symlinked package path.
  • Manual MCP initialize against server-hackernews launched through a .bin-style symlink returns serverInfo.name = "hackernews" and protocol 2025-06-18.
  • New unit test covers direct, symlinked, mismatched, and missing entry points.

The arXiv 429 mentioned in the issue is left as a separate follow-up: it reproduces a host-level rate limit rather than a URL/limit bug in the server, and no code path here changes it.

- Emit a node shebang for every published bin from the shared tsdown config. npm links JS bins as symlinks on macOS/Linux, so a missing shebang made the kernel parse the bundle as shell.

- Resolve entry points with realpath before comparing them to import.meta.url. The .bin symlink made the old check false, so servers exited silently even with a shebang.

- Share isMainModule from core across every server and the CLI.

- Add a prepack guard that refuses packages with missing dist files, missing bin shebangs, or incomplete npm tarballs. core@0.2.1 was published without dist/.

- Run verify:pack in CI and release, plus a Linux-only verify:launch smoke test that boots each bin through a .bin symlink.
Copilot AI balanced review requested due to automatic review settings November 3, 2026 15:28

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-03T15:33:54.604690Z 5254223 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 52542238e0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const flags = new Set(process.argv.slice(2));
const verifyAll = flags.has("--all");
const checkTarball = verifyAll ? !flags.has("--no-pack") : flags.has("--pack");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Enable tarball checks in the per-package prepack hook

When a package is published directly with npm publish (outside the release workflow), npm runs prepack before creating the tarball (npm lifecycle docs). That hook invokes this script without --all or --pack, so this condition disables the tarball-content check; a files or .npmignore change that excludes a declared export can therefore pass prepack and still publish an incomplete package. Have the prepack invocation enable the tarball check.

Useful? React with 👍 / 👎.

if (result.error.code !== "ETIMEDOUT") {
problems.push(`${target} could not be launched through a bin symlink: ${result.error.message}`);
}
} else if (result.status === 0 && output.trim().length === 0) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Fail the launch smoke test on startup errors

When --launch is used, this condition only rejects a silent exit with status 0. A bin that fails during startup—for example, because a runtime import is missing—exits nonzero with an error message and is treated as successfully launched, so CI can pass while the published command is unusable. Assert the expected startup/transport behavior instead of accepting arbitrary non-silent exits.

Useful? React with 👍 / 👎.

@Markgatcha
Markgatcha merged commit c31699f into main Nov 3, 2026
12 checks passed
@Markgatcha
Markgatcha deleted the fix/issue-18-packaging branch November 3, 2026 15:38
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.

2 participants