@thenavidm/slipway 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 What changed in Slipway, newest first.
 
+## 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.
+- **`install` follows `@latest`.** Clients start `npx --package=<package>@latest <name>-mcp`, so they pick up every release on their next start. The binary is still named, so the order in `package.json` cannot pick the wrong one.
+
+## 0.1.1, 2026-10-04: a safer install check
+
+- **No stranger's package through npx.** An unrelated npm package owns the bare name `slipway`, so a bare `npx slipway` with nothing installed fetched and ran it. SKILL.md now checks the install with `npm ls @thenavidm/slipway`, and every command that may run before an install names the package: `npx -p @thenavidm/slipway slipway <command>`.
+
 ## 0.1.0, 2026-10-04: the first release
 
 - **One definition, two surfaces.** `defineTool` describes a tool once; `slipway()` ships it as an MCP server tool and a CLI command under the same name. Both surfaces send every call through one function, so validation, the write guard, timeouts, cancellation and redaction cannot differ between them.

package/README.md

@@ -444,7 +444,7 @@ notes-cli install cursor --dry-run
 | `vscode` | `.vscode/mcp.json` | VS Code asks for each credential once and stores it securely |
 | `gemini` | `~/.gemini/settings.json`, or `.gemini/settings.json` | `${NAME}` references, which Gemini CLI needs to pass anything named like a key |
 
-A published server is started with `npx --package=<package>@<version> <name>-mcp`, pinned to the version you installed, with Codex's startup timeout raised for the first download. Without `package`, or with `--local`, the client starts this copy on disk. Installing again updates the entry in place: anything you added to it by hand stays, and the old file is kept as a backup.
+A published server is started with `npx --package=<package>@latest <name>-mcp`, so a client picks up every release on its next start, with Codex's startup timeout raised for the download. The binary is named, because npx alone starts whichever binary a package lists first. Without `package`, or with `--local`, the client starts this copy on disk. Installing again updates the entry in place: anything you added to it by hand stays, and the old file is kept as a backup.
 
 ## 11. Large catalogs
 
@@ -459,9 +459,11 @@ A server with a hundred tools costs a client that loads every definition up fron
 `slipway check` runs against your built app and its real MCP server:
 
 ```bash
-slipway check dist/app.js --bin dist/index.js --docs README.md,SKILL.md
+npx slipway check dist/app.js --bin dist/index.js --docs README.md,SKILL.md
 ```
 
+Run it in a project that has `@thenavidm/slipway` installed, where npx uses that copy. Anywhere else, name the package: `npx -p @thenavidm/slipway slipway openapi spec.json`. A bare `npx slipway` with nothing installed fetches an unrelated npm package of the same name.
+
 | Check | What fails |
 |---|---|
 | Names | A tool that takes a built-in command's name |
@@ -474,7 +476,7 @@ slipway check dist/app.js --bin dist/index.js --docs README.md,SKILL.md
 | Parity | A tool, schema, annotation or approval flag that differs between MCP and the CLI |
 | Docs | A command or flag in your README or SKILL.md that does not exist |
 | Startup | A built server that exits or hangs when nothing is configured |
-| Install | No `package`, so `install` cannot point clients at the published server |
+| Install | No `package`, or a package.json whose `npx -y` default starts the CLI instead of the server |
 
 Parity runs on both protocol revisions a client may open with. `slipway docs dist/app.js` prints the command table, every argument and the settings as Markdown, from the same definitions. `slipway inspect dist/app.js` lists the tools exactly as a client receives them, and `slipway openapi <file|url>` previews what an OpenAPI document becomes.
 
@@ -519,6 +521,7 @@ const mcp = await connect(app, { era: "modern", elicit: () => ({ action: "accept
 | Codex shows the server as failed at startup | The first npx download outlasted 10 seconds | `install codex` sets `startup_timeout_sec = 60`; add it by hand to an older entry |
 | `slipway check` warns about schema size | One tool's schema is large or repeats its definitions | Send the body schema once, or advertise a short one and validate the full one in the handler |
 | `slipway check` cannot load the app | The module starts the server when imported | Export the app from `app.ts` and call `app.main()` only in `index.ts` |
+| `npx slipway` prints something unexpected | Slipway is not installed in this folder, so npx fetched an unrelated package called `slipway` | Run `npm install @thenavidm/slipway`, or `npx -p @thenavidm/slipway slipway <command>` |
 
 ## Environment variables
 

package/SKILL.md

@@ -5,7 +5,7 @@ metadata:
   install:
     package: "@thenavidm/slipway"
     node: ">=22"
-    check: "npx slipway --version"
+    check: "npm ls @thenavidm/slipway"
 ---
 
 # Building with Slipway
@@ -14,7 +14,7 @@ Slipway turns one list of tool definitions into an MCP server and a CLI. Both su
 
 ## Install gate
 
-Run `npx slipway --version` in the repo. If it does not print a version, STOP: the package is missing. Install it with `npm install @thenavidm/slipway`, then check again.
+Run `npm ls @thenavidm/slipway` in the repo. If it does not list a version, STOP: the package is missing. Install it with `npm install @thenavidm/slipway`, then check again. Never test with a bare `npx slipway` before it is installed: an unrelated package on npm is called `slipway`, and npx would fetch and run that one.
 
 ## The three files
 
@@ -93,7 +93,7 @@ tools: fromOpenAPI(spec, {
 }),
 ```
 
-Run `npx slipway openapi openapi.json` first: it lists every tool the document becomes, what it skips and why, the schemas too large for a model, and the hash to pin. Fix a misleading method with `risk: { searchProducts: "read" }`, and rename with `names`.
+Run `npx -p @thenavidm/slipway slipway openapi openapi.json` first: it lists every tool the document becomes, what it skips and why, the schemas too large for a model, and the hash to pin. Fix a misleading method with `risk: { searchProducts: "read" }`, and rename with `names`.
 
 ## Shipping it to clients
 

package/dist/bin.js

@@ -95,7 +95,13 @@ async function main(argv) {
     if (command === "check") {
         const docs = option(rest, "--docs")?.split(",").filter(Boolean);
         const bin = option(rest, "--bin");
-        const report = await checkApp(app, { env: process.env, ...(docs ? { docs } : {}), ...(bin ? { bin: resolve(bin) } : {}) });
+        const packageJson = resolve("package.json");
+        const report = await checkApp(app, {
+            env: process.env,
+            ...(docs ? { docs } : {}),
+            ...(bin ? { bin: resolve(bin) } : {}),
+            ...(existsSync(packageJson) ? { packageJson } : {}),
+        });
         const strict = rest.includes("--strict");
         const failed = report.errors > 0 || (strict && report.warnings > 0);
         if (rest.includes("--json")) {

package/dist/check.d.ts

@@ -25,6 +25,8 @@ export type CheckOptions = {
         warnBytes: number;
         errorBytes: number;
     };
+    /** The app's package.json, to check that `npx -y <package>` starts the MCP server. */
+    packageJson?: string;
 };
 export type CheckReport = {
     ok: boolean;

package/dist/check.js

@@ -108,6 +108,8 @@ export async function checkApp(app, options = {}) {
     if (!app.definition.package) {
         add("warn", "install", "No package is set, so `install` points clients at this copy on disk instead of the published one. Set package to the npm name.");
     }
+    if (options.packageJson)
+        checkBins(app, options.packageJson, add);
     const instructions = app.instructions ?? "";
     if (!instructions)
         add("warn", "instructions", "No server instructions. Clients use them to decide when to reach for these tools.");
@@ -215,6 +217,42 @@ async function checkParityIn(era, app, env, tools, add) {
         await client.close().catch(() => undefined);
     }
 }
+/**
+ * `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.
+ */
+function checkBins(app, file, add) {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        add("error", "install", `Could not read ${file}: ${error.message}`);
+        return;
+    }
+    if (app.definition.package && pkg.name && pkg.name !== app.definition.package) {
+        add("warn", "install", `The app's package is ${app.definition.package} but package.json is ${pkg.name}.`);
+    }
+    if (!pkg.bin || typeof pkg.bin === "string")
+        return;
+    const bins = pkg.bin;
+    const keys = Object.keys(bins);
+    if (!keys.includes(app.bins.mcp)) {
+        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.`);
+    }
+    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.`);
+    }
+}
 /** Every command and flag a README or SKILL.md tells someone to type must exist. */
 function checkDocs(app, file, add) {
     if (!existsSync(file)) {

package/dist/install.d.ts

@@ -59,7 +59,8 @@ export type InstallPlan = {
 };
 /**
  * How a client should start this server: the published package through npx,
- * pinned to this version, or this copy on disk.
+ * at `@latest` so a client picks up every release on its next start, or this
+ * copy on disk.
  *
  * npx needs the binary named: a package with an MCP and a CLI binary leaves
  * npx to pick one otherwise, and the CLI started with no arguments prints its

package/dist/install.js

@@ -27,7 +27,8 @@ export const CLIENTS = {
 };
 /**
  * How a client should start this server: the published package through npx,
- * pinned to this version, or this copy on disk.
+ * at `@latest` so a client picks up every release on its next start, or this
+ * copy on disk.
  *
  * npx needs the binary named: a package with an MCP and a CLI binary leaves
  * npx to pick one otherwise, and the CLI started with no arguments prints its
@@ -37,7 +38,7 @@ export function launchFor(app, options) {
     const platform = options.platform ?? process.platform;
     let launch;
     if (app.definition.package && !options.local) {
-        launch = { command: "npx", args: ["--yes", `--package=${app.definition.package}@${app.version}`, app.bins.mcp] };
+        launch = { command: "npx", args: ["--yes", `--package=${app.definition.package}@latest`, app.bins.mcp] };
     }
     else {
         const entry = options.entry ?? (process.argv[1] ? realpathSync(process.argv[1]) : undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenavidm/slipway",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",