@thenavidm/slipway 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.5, 2026-10-04: what Bluesky's move found
+
+- **A request that never got an answer exits 5.** A failed fetch, a refused connection or a DNS failure mapped to exit 1, "unexpected error", so a script that retries on 5 gave up instead. Bluesky 1.2.3 exited 5 for an unreachable host, 0.1.4 made it 1, and it is 5 again.
+- **`--help` and `agent-context` list every variable Slipway reads**, `<PREFIX>_HTTP_PORT`, `_HOST`, `_TOKEN` and `_DEBUG` included. Bluesky's own help listed the HTTP ones before it moved.
+- **A shorter general help.** An agent often reads it first and pays for it again on every later step. The header drops the description, the rarely needed commands share one line, and Slipway's own settings say only what they do: Bluesky's went from 780 tokens to 667.
+- **The command list says `!` needs `--confirm`** when that is true of every command it lists.
+- **The entry turns on Node's compile cache.** The README's `src/index.ts` loads the app after `module.enableCompileCache()`, so every launch after the first skips compiling it: Bluesky answers a client in 183 ms instead of 204. Node before 22.8 starts as before.
+- **The README says what happens to a piped request after stdin closes.** The server stops without answering, as the MCP stdio binding asks; keep stdin open until you read the answer.
+
 ## 0.1.4, 2026-10-04: faster starts, cheaper results in Codex
 
 - **A JSON Schema compiles on its tool's first call.** `jsonSchema()` compiled its validator as soon as a tool was defined, so a server paid for every schema before it could answer. On Teachable's 123 contract tools that held the first answer back by 118 ms. Building Stripe's 611 OpenAPI tools took 1,745 ms and now takes 69; GitHub's 1,230 took 646 ms and now take 60 (medians of three runs on one Mac). A tool's first call now compiles its own schema, a median of 3 ms on Stripe's and under 1 ms on GitHub's.

package/README.md

@@ -174,11 +174,15 @@ export const app = slipway<Context>({
 
 ```ts
 #!/usr/bin/env node
-import { app } from "./app.js";
+import * as nodeModule from "node:module";
 
+nodeModule.enableCompileCache?.();
+const { app } = await import("./app.js");
 await app.main();
 ```
 
+The app loads after Node's compile cache goes on, so every launch after the first skips compiling it again: Bluesky answers a client in 183 ms instead of 204. Node before 22.8 has no compile cache and starts as before, and `NODE_DISABLE_COMPILE_CACHE=1` turns it off.
+
 **`src/npx.ts`** is what `npx -y @you/notes-mcp-cli` runs:
 
 ```ts
@@ -530,6 +534,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` |
+| A request piped to the server gets no answer | Stdin closed before the answer, and the MCP stdio binding stops a server when its input ends | Keep stdin open until you read the answer, as clients do, or run the command from the CLI |
 | `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
@@ -556,6 +561,14 @@ Every server reads these, under its own prefix: the app name in capitals, `NOTES
 
 See [CHANGELOG.md](CHANGELOG.md).
 
+## Servers built on Slipway
+
+| Server | Package | Covers |
+| --- | --- | --- |
+| [Teachable](https://github.com/thenavidm/teachable-mcp-cli) | [`@thenavidm/teachable-mcp-cli`](https://www.npmjs.com/package/@thenavidm/teachable-mcp-cli) 3.0.0 | Courses, users, enrollments, pricing, coupons and transactions |
+
+Each server was measured against its previous release before it moved: startup, what a client receives, CLI exit codes, and tokens in Claude Code and Codex. Its README has the numbers.
+
 ## 15. FAQ ❓
 
 <details>

package/SKILL.md

@@ -22,7 +22,7 @@ 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/index.ts` | `nodeModule.enableCompileCache?.()`, then `await import("./app.js")` and `app.main()` | The only file that starts anything. Both binaries point at it. The cache goes on before the app loads, so later launches skip compiling it |
 | `src/npx.ts` | `import "./index.js";` | What `npx -y <package>` runs. Its binary is named after the package |
 
 `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.

package/dist/cli/context.js

@@ -76,6 +76,10 @@ export function agentContext(app, env, bin, options = {}) {
             { env: names.auditLog, value: policy.auditLog ?? null, description: "file that records every attempted write" },
             { env: names.toolTimeoutMs, value: policy.toolTimeoutMs ?? null, description: "deadline for any tool" },
             { env: names.confirm, value: policy.confirm, description: "who confirms a confirmed call over MCP: human asks a person where the client can, model accepts confirm: true" },
+            { env: `${app.envPrefix}_HTTP_PORT`, value: env[`${app.envPrefix}_HTTP_PORT`] ?? null, description: "port for --http, 8787 when unset" },
+            { env: `${app.envPrefix}_HTTP_HOST`, value: env[`${app.envPrefix}_HTTP_HOST`] ?? null, description: "address for --http, 127.0.0.1 when unset; any other needs a token" },
+            { env: `${app.envPrefix}_HTTP_TOKEN`, set: Boolean(env[`${app.envPrefix}_HTTP_TOKEN`]), secret: true, description: "bearer token --http requires" },
+            { env: `${app.envPrefix}_DEBUG`, value: /^(1|true|yes)$/i.test(env[`${app.envPrefix}_DEBUG`] ?? ""), description: "print debug lines on stderr" },
         ],
         ...(app.definition.toolsets ? { toolsets: app.definition.toolsets } : {}),
         hidden_commands: hidden,

package/dist/cli/help.js

@@ -94,7 +94,9 @@ export function renderList(app, tools, bin, env = process.env) {
         for (const tool of members)
             lines.push(`  ${riskMark(tool.risk)} ${tool.command.padEnd(width)}${tool.title}`);
     }
-    lines.push(``, `  * writes    ! public or irreversible`, ``, `  ${bin} <command> --help    what one takes, with examples`, `  ${bin} which <words>       find the command for a task`, `  ${bin} --help              flags, settings and setup`, ``, ...hiddenNote(app, env));
+    // The legend says `!` needs --confirm only when that holds for every listed command.
+    const confirmByRisk = tools.every((tool) => tool.requireConfirm === (tool.risk === "destructive"));
+    lines.push(``, `  * writes    ! public or irreversible${confirmByRisk ? ", needs --confirm" : ""}`, ``, `  ${bin} <command> --help    what one takes, with examples`, `  ${bin} which <words>       find the command for a task`, `  ${bin} --help              flags, settings and setup`, ``, ...hiddenNote(app, env));
     return lines.join("\n");
 }
 function shellQuote(value) {
@@ -186,16 +188,15 @@ export function renderGeneralHelp(app, bin) {
     const cache = app.allTools.some((tool) => tool.cache);
     const sync = app.allTools.some((tool) => tool.sync);
     const jobs = app.allTools.some((tool) => tool.job);
+    // An agent often reads this first and pays for it again on every later step, so the
+    // rarely needed commands share one line and Slipway's own settings say only what they do.
     const commands = [
         [bin, "list the commands"],
         [`${bin} <command> --help`, "what one takes, with examples"],
         [`${bin} which <words>`, "find the command for a task"],
-        [`${bin} schema <command>`, "its JSON Schema; --output for the result's"],
-        [`${bin} agent-context`, "all of this as JSON; --brief for less"],
         [`${bin} doctor [--network]`, "check the setup and say what is wrong"],
         [`${bin} login`, "how to connect an account"],
-        [`${bin} install <client>`, "add the server to claude-code, codex, claude-desktop, cursor, vscode or gemini"],
-        [`${bin} completion <shell>`, "tab completion for bash, zsh or fish"],
+        [`${bin} install <client>`, "add the server to an MCP client; install --help lists them"],
         ...(cache || sync ? [[`${bin} data`, "what is kept on this machine; data clear [<command>] deletes it"]] : []),
         ...(sync
             ? [
@@ -209,14 +210,16 @@ export function renderGeneralHelp(app, bin) {
     const settings = [
         ...(app.definition.settings ?? []).map((setting) => [setting.env, setting.description]),
         [`${names.readOnly}=1`, "hide and refuse every write"],
-        [`${names.allowDestructive}=0`, "keep writes, refuse the irreversible ones"],
+        [`${names.allowDestructive}=0`, "refuse the irreversible writes"],
         [`${names.toolsets}=a,b`, "only these toolsets, or all"],
-        [`${names.surface}=search`, "MCP serves three tools that find, describe and run the rest"],
-        [`${names.auditLog}=<file>`, "log every attempted write to this file"],
-        [`${names.toolTimeoutMs}=<ms>`, "give up on any tool after this long"],
-        [`${names.confirm}=model`, "confirm: true alone confirms, for an agent with no person to ask"],
+        [`${names.surface}=search`, "MCP lists three finder tools instead"],
+        [`${names.auditLog}=<file>`, "log every attempted write"],
+        [`${names.toolTimeoutMs}=<ms>`, "deadline for any tool"],
+        [`${names.confirm}=model`, "confirm: true alone confirms over MCP"],
         ...(cache ? [[`${names.cache}=0`, "never answer from the local cache"]] : []),
         ...(cache || sync ? [[`${names.dataDir}=<dir>`, "keep local data in this folder"]] : []),
+        [`${app.envPrefix}_HTTP_PORT / _HOST / _TOKEN`, "for --http"],
+        [`${app.envPrefix}_DEBUG=1`, "debug lines on stderr"],
     ];
     // Flags that cannot apply here (jobs, the cache) are left out; agent-context lists every one.
     const flags = GLOBAL_FLAGS.map(([flag]) => flag).filter((flag) => flag !== "--agent" && (flag !== "--wait" || jobs) && (flag !== "--refresh" || cache));
@@ -224,16 +227,17 @@ export function renderGeneralHelp(app, bin) {
     const row = ([left, help]) => `  ${left.padEnd(width)}${help}`;
     const lines = [
         ``,
-        `${app.title} ${app.version}${app.description ? `: ${app.description}` : ""}`,
+        `${app.title} ${app.version}`,
         ``,
         ...commands.map(row),
+        `  Also: schema <command>, agent-context [--brief] (all of this as JSON), completion <shell>.`,
         ``,
-        `Flags: ${flags.join(", ")}, and --agent for compact JSON with no prompts, which never confirms a write.`,
+        `Flags: ${flags.join(", ")}, and --agent: compact JSON, no prompts, never confirms a write.`,
         ``,
         `Settings:`,
         ...settings.map(row),
         ``,
-        `Exit codes: ${EXIT.ok} ok, ${EXIT.error} unexpected error, ${EXIT.usage} usage or refused write, ${EXIT.notFound} not found, ${EXIT.auth} auth, ${EXIT.api} API, ${EXIT.rateLimited} rate limited, ${EXIT.notConfigured} nothing configured`,
+        `Exit codes: ${EXIT.ok} ok, ${EXIT.error} unexpected, ${EXIT.usage} usage or refused, ${EXIT.notFound} not found, ${EXIT.auth} auth, ${EXIT.api} API, ${EXIT.rateLimited} rate limited, ${EXIT.notConfigured} not configured`,
         ``,
     ];
     if (app.definition.links?.repository)

package/dist/errors.js

@@ -149,5 +149,10 @@ export function toSlipwayError(error) {
         return new AuthError(message, { cause: error });
     if (/\b404\b|not found|does not exist/.test(text))
         return new NotFoundError(message, { cause: error });
+    // A request that never got an answer is the service's failure, not a bug here: exit 5, which a script may retry.
+    const codes = [error?.code, error?.cause?.code];
+    const network = codes.some((code) => typeof code === "string" && /^(ECONN(REFUSED|RESET|ABORTED)|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|E(HOST|NET)UNREACH|EPIPE|UND_ERR_\w+)$/.test(code));
+    if (network || /fetch failed|could not reach|network error|socket hang up/.test(text))
+        return new ApiError(message, { cause: error });
     return new SlipwayError(message, "internal", EXIT.error, { cause: error });
 }

package/package.json

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