@thenavidm/slipway 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.3, 2026-10-04: npx picks the server by name
+
+- **`slipway check` matches npm's real rule.** npx picks a binary named after the package only when the binaries point to different files. When they share one file it starts whichever one the registry lists first, and the registry does not keep the published order: 23 published servers listed their MCP binary first and still started the CLI. 0.1.2's order check could not catch that. The check now requires a binary named after the package on a file of its own, and the README shows the one-line `src/npx.ts` it runs.
+
 ## 0.1.2, 2026-10-04: clients always start the server
 
 - **`slipway check` fails a package whose `npx -y` default is the CLI.** With several binaries on one file, npx starts the first one listed. A package that lists its CLI first hands every client launched with `npx -y <package>` the command list instead of a server. The check reads `package.json` and names the fix: list the MCP binary first.

package/README.md

@@ -124,7 +124,7 @@ npm install --save-dev ajv
 
 ## 2. Build a server
 
-A server is three files.
+A server is three files, plus a one-line fourth for npx.
 
 **`src/tools.ts`** says what the server can do. `toolkit<Context>()` binds the context type once, so every handler gets `ctx.api` typed:
 
@@ -179,12 +179,21 @@ import { app } from "./app.js";
 await app.main();
 ```
 
+**`src/npx.ts`** is what `npx -y @you/notes-mcp-cli` runs:
+
+```ts
+#!/usr/bin/env node
+import "./index.js";
+```
+
 ```json
 {
-  "bin": { "notes-mcp": "dist/index.js", "notes-cli": "dist/index.js" }
+  "bin": { "notes-mcp": "dist/index.js", "notes-cli": "dist/index.js", "notes-mcp-cli": "dist/npx.js" }
 }
 ```
 
+npx picks a binary named after the package only when the binaries point to different files. When they all share one file it starts whichever one the registry lists first, and the registry does not keep the order they were published in, so a client could get the CLI's command list instead of a server. The fourth binary, on its own file, is picked every time, and `slipway check` fails a package without it.
+
 `notes-mcp` with no arguments serves MCP over stdio and stays silent on stdout. `notes-cli` with no arguments lists the commands. Any argument on either binary is a command, so a typo is reported instead of starting a server that waits on stdin.
 
 The context is built on the first call that needs it, never at startup. `--help` works with nothing configured, and the server answers a client at once and explains what is missing instead of exiting.

package/SKILL.md

@@ -23,8 +23,9 @@ Run `npm ls @thenavidm/slipway` in the repo. If it does not list a version, STOP
 | `src/tools.ts` | The tools, from `toolkit<Context>().defineTool` | One `defineTool` per action |
 | `src/app.ts` | `export const app = slipway({...})` | Describes only. Never calls `main()`, so checks and tests can import it |
 | `src/index.ts` | `await app.main()` | The only file that starts anything. Both binaries point at it |
+| `src/npx.ts` | `import "./index.js";` | What `npx -y <package>` runs. Its binary is named after the package |
 
-`package.json` declares both binaries on the same file: `"<name>-mcp"` and `"<name>-cli"`, both `dist/index.js`.
+`package.json` declares `"<name>-mcp"` and `"<name>-cli"` on `dist/index.js`, and a third binary named after the package (`"<name>-mcp-cli"`) on `dist/npx.js`. npx only picks a binary by name when they point to different files; otherwise it takes whichever one the registry lists first, which may be the CLI.
 
 ## Defining a tool
 

package/dist/check.js

@@ -219,9 +219,10 @@ async function checkParityIn(era, app, env, tools, add) {
 }
 /**
  * `npx -y <package>` is how most people install a server, and npx starts one
- * binary without being told which. With several binaries on one file it runs
- * the first listed, so a package that lists its CLI first hands every client
- * the command list instead of a server.
+ * binary without being told which. npm's rule: when every binary points to
+ * the same file, it starts whichever one the registry lists first, and the
+ * registry does not keep the order they were published in. Only a binary
+ * named after the package, on a file of its own, is picked every time.
  */
 function checkBins(app, file, add) {
     let pkg;
@@ -238,19 +239,20 @@ function checkBins(app, file, add) {
     if (!pkg.bin || typeof pkg.bin === "string")
         return;
     const bins = pkg.bin;
-    const keys = Object.keys(bins);
-    if (!keys.includes(app.bins.mcp)) {
+    if (!(app.bins.mcp in bins)) {
         add("error", "install", `package.json has no ${app.bins.mcp} binary, so clients cannot start the server by name.`);
         return;
     }
     const unscoped = (pkg.name ?? "").split("/").pop() ?? "";
-    // npx's own order: a binary named after the package, then the only file all binaries share.
-    const chosen = keys.includes(unscoped) ? unscoped : new Set(Object.values(bins)).size === 1 ? keys[0] : undefined;
-    if (chosen === undefined) {
-        add("error", "install", `npx -y ${pkg.name} cannot choose between ${keys.join(" and ")}. Point them at one file and list ${app.bins.mcp} first.`);
+    const fix = `Add "${unscoped}": "dist/npx.js" to bin, where src/npx.ts holds only: import "./index.js";`;
+    if (new Set(Object.values(bins)).size === 1) {
+        add("error", "install", `Every binary runs the same file, so npx -y ${pkg.name} starts whichever one the registry lists first, which may be ${app.bins.cli}. ${fix}`);
     }
-    else if (chosen !== app.bins.mcp && bins[chosen] === bins[app.bins.mcp] && chosen === app.bins.cli) {
-        add("error", "install", `npx -y ${pkg.name} starts ${chosen}, the CLI, so a client launched that way gets the command list instead of a server. List ${app.bins.mcp} first in package.json's bin.`);
+    else if (!(unscoped in bins)) {
+        add("error", "install", `npx -y ${pkg.name} cannot choose between ${Object.keys(bins).join(", ")}. ${fix}`);
+    }
+    else if (unscoped === app.bins.cli || unscoped.startsWith(app.bins.cli)) {
+        add("error", "install", `npx -y ${pkg.name} starts ${unscoped}, which runs as the CLI. Name the package so it does not start with ${app.bins.cli}.`);
     }
 }
 /** Every command and flag a README or SKILL.md tells someone to type must exist. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenavidm/slipway",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Slipway, the TypeScript framework for MCP servers and agent-native CLIs. One tool definition ships an MCP server and a CLI, with write safety, typed results and release checks built in.",
   "type": "module",
   "license": "Apache-2.0",