@thenavidm/slipway 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.6, 2026-10-05: what Mastodon's move needed
+
+- **`login` runs the app's own sign-in, with the words after it.** `mastodon-cli login mastodon.social --oob` hands `mastodon.social --oob` to Mastodon's flow, which registers an app on that instance and signs in. A flow given with `usage` and `help` shows them in help, `login --help` and `agent-context`, so nobody has to guess that it takes an instance.
+- **Terminal commands beside the tools.** `commands` adds commands such as `logout` to the CLI only. Each is listed in help, `agent-context` and tab completion, `slipway check` fails one named like a built-in or a tool, and an MCP client never sees it.
+- **Tuning stays out of the way.** A setting marked `tuning: true`, such as a timeout with a working default, is named on one line of help and left out of what `install` writes. On Mastodon, `install claude-code` told people to set 13 variables and now names the 6 that connect an account, and the general help is 64 tokens shorter.
+- **`httpPort` sets the default port for `--http`.** A server that shipped another default, such as 8000, keeps it after the move; `<PREFIX>_HTTP_PORT` and `--port` still override it.
+- **`doctorNetwork` calls the service on every `doctor`.** Doctor stays local unless `--network` is passed, which keeps it quick and spends no requests. Mastodon's most common failure is a token without the `write` scope, which only a request finds, and its docs have always told people to run plain `doctor` for it.
+- **The MCP binary's help names the CLI binary for the command list.** `mastodon-mcp --help` said a bare `mastodon-mcp` lists the commands, when it starts the server. Every hint that says where to list the commands now names the CLI binary.
+- **Advertised schemas leave out Zod 4's safe-integer bounds.** Zod 4 gives every whole number `maximum: 9007199254740991` and its negative unless the schema sets its own. They tell a client nothing, so they are left out of what it receives; three were in Mastodon's tool list. Validation still runs on the full schema.
+
 ## 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.

package/README.md

@@ -388,10 +388,11 @@ Override any operation's name or risk with `names` and `risk`, keep a subset wit
 | `<cli> which <words>` | Find the command for a task, by what it does |
 | `<cli> schema <command>` | The JSON Schema an MCP client receives. `--output` for the result's |
 | `<cli> agent-context` | Commands, flags, risk, examples, exit codes and settings as JSON. `--brief` for just the commands, which ones write or need `--confirm`, and the exit codes |
-| `<cli> doctor` | Check the setup. `--network` also calls the service |
-| `<cli> login` | How to connect an account |
+| `<cli> doctor` | Check the setup. `--network` also calls the service, which an app with `doctorNetwork` does every time |
+| `<cli> login` | How to connect an account: printed steps, or the app's own sign-in flow with the words after `login` |
 | `<cli> install <client>` | Add the MCP server to a client. See [Add it to a client](#10-add-it-to-a-client) |
 | `<cli> data` | The local cache and synced lists: `sync`, `search`, `sql`, `clear` |
+| `<cli> <command>` from `commands` | A terminal command the app adds, such as `logout`. Listed in help and `agent-context`, never sent to an MCP client |
 | `<cli> completion bash` | Tab completion for bash, zsh or fish |
 
 Flags come from the schema: `--flag value`, `--flag=value`, the underscore spelling, `--no-flag` for a boolean, repeated or comma-separated lists of numbers and choices, and JSON or `@file.json` for an object. `--input` takes every argument as one JSON object, from the flag, a file or stdin, and flags on the same line override it.
@@ -426,7 +427,7 @@ Errors are JSON on stderr, always, with `error`, `code` and a `hint` that names
 | Run | Serves |
 |---|---|
 | `<mcp>` | MCP over stdio, what a client launches |
-| `<mcp> --http [--port 8787]` | Streamable HTTP at `/mcp`, with `/health` |
+| `<mcp> --http [--port 8787]` | Streamable HTTP at `/mcp`, with `/health`. The app's `httpPort` replaces 8787, for a server that shipped another default |
 
 HTTP binds `127.0.0.1` and checks the Host header, so a web page cannot reach it through a name that resolves to localhost. It refuses to listen on any other address without `<PREFIX>_HTTP_TOKEN`, because anyone who reached the port would act as your account.
 
@@ -457,7 +458,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>@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.
+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. A setting marked `tuning: true`, such as a timeout with a working default, stays out of the entry, so it carries only what connects an account.
 
 ## 11. Large catalogs
 
@@ -539,7 +540,7 @@ const mcp = await connect(app, { era: "modern", elicit: () => ({ action: "accept
 
 ## Environment variables
 
-Every server reads these, under its own prefix: the app name in capitals, `NOTES` for `notes`, unless `envPrefix` says otherwise. A server's own settings, declared with `settings`, are listed in its help, its `agent-context` and its generated docs.
+Every server reads these, under its own prefix: the app name in capitals, `NOTES` for `notes`, unless `envPrefix` says otherwise. A server's own settings, declared with `settings`, are listed in its help, its `agent-context` and its generated docs, and `install` passes on every one not marked `tuning`.
 
 | Variable | Default | What it does |
 |---|---|---|
@@ -552,7 +553,7 @@ Every server reads these, under its own prefix: the app name in capitals, `NOTES
 | `<PREFIX>_TOOLSETS` | `all` | Comma-separated toolsets to turn on |
 | `<PREFIX>_SURFACE` | `full` | `search` lists three tools that find, describe and run the rest |
 | `<PREFIX>_TOOL_TIMEOUT_MS` | none | Give up on any tool after this long |
-| `<PREFIX>_HTTP_PORT` | `8787` | For `--http` |
+| `<PREFIX>_HTTP_PORT` | `8787`, or the app's `httpPort` | For `--http` |
 | `<PREFIX>_HTTP_HOST` | `127.0.0.1` | For `--http`. Any other address needs a token |
 | `<PREFIX>_HTTP_TOKEN` | none | Bearer token required by `--http` |
 | `<PREFIX>_DEBUG` | `0` | `1` prints debug lines on stderr |
@@ -565,6 +566,7 @@ See [CHANGELOG.md](CHANGELOG.md).
 
 | Server | Package | Covers |
 | --- | --- | --- |
+| [Bluesky](https://github.com/thenavidm/bluesky-mcp-cli) | [`@thenavidm/bluesky-mcp-cli`](https://www.npmjs.com/package/@thenavidm/bluesky-mcp-cli) 2.0.0 | Posting, threads, replies, the timeline, search, feeds, lists, notifications and the social graph |
 | [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.

package/dist/app.d.ts

@@ -48,6 +48,13 @@ export type ServiceSetting = {
     description: string;
     /** A credential: shown as set or unset, never printed. */
     secret?: boolean;
+    /**
+     * Tuning with a working default, such as a timeout or a retry count, or a
+     * second name for another setting. Listed in help and `agent-context`, but
+     * `install` leaves it out, so a client entry and its instructions hold only
+     * what connects an account.
+     */
+    tuning?: boolean;
 };
 export type CliIO = {
     stdout: (text: string) => void;
@@ -62,6 +69,18 @@ export type CliIO = {
     /** The folder a project-scoped `install` writes into. Defaults to the current one. */
     cwd?: string;
 };
+/** An interactive sign-in. It gets the words after `login` and returns an exit code. */
+export type LoginFlow = (io: CliIO, args: string[]) => number | Promise<number>;
+/** A terminal-only command an app adds beside its tools. */
+export type CliCommand = {
+    /** The word typed after the binary: `logout`. Must not be a tool's command or a built-in. */
+    name: string;
+    /** What it takes, as help shows it: `logout [<handle>]`. Defaults to the name. */
+    usage?: string;
+    /** One line: what it does. */
+    help: string;
+    run: (io: CliIO, args: string[]) => number | Promise<number>;
+};
 export type AppDefinition<Ctx> = {
     /** The service slug: "bluesky". Binaries default to bluesky-mcp and bluesky-cli. */
     name: string;
@@ -83,6 +102,12 @@ export type AppDefinition<Ctx> = {
     };
     /** The npm package that ships the binaries, so `install` can have a client start it with npx. */
     package?: string;
+    /**
+     * The port `--http` listens on when neither `--port` nor `<PREFIX>_HTTP_PORT`
+     * names one. 8787 when unset; a server that already shipped another default
+     * keeps it here.
+     */
+    httpPort?: number;
     /**
      * Builds what handlers need: an API client, config, accounts. Called once,
      * on the first call that needs it, so `--help` works with nothing configured.
@@ -93,12 +118,34 @@ export type AppDefinition<Ctx> = {
     prompts?: readonly PromptDefinition<Ctx>[];
     /** Whether any credentials are set. False makes `doctor` exit 10 and the server warn at startup. */
     configured?: (ctx: Ctx) => boolean | Promise<boolean>;
-    /** Service checks for `doctor`. `network` is true only when the person passed --network. */
+    /** Service checks for `doctor`. `network` is true only when the person passed --network, or `doctorNetwork` is set. */
     doctor?: (ctx: Ctx, options: {
         network: boolean;
     }) => DoctorCheck[] | Promise<DoctorCheck[]>;
-    /** How to sign in: printed instructions, or an interactive flow that returns an exit code. */
-    login?: string | ((io: CliIO) => number | Promise<number>);
+    /**
+     * Call the service on every `doctor`, not only with --network. Off by
+     * default, so doctor stays quick and spends no requests; on for a service
+     * whose most common failure only a request finds, such as a token missing
+     * a scope.
+     */
+    doctorNetwork?: boolean;
+    /**
+     * How to sign in: printed instructions, or an interactive flow that returns an
+     * exit code. A flow gets the words after `login`: `mastodon-cli login mastodon.social`.
+     * A flow given with `usage` and `help` shows them in help, `login --help` and
+     * `agent-context`, so nobody has to guess that it takes an instance.
+     */
+    login?: string | LoginFlow | {
+        usage?: string;
+        help: string;
+        run: LoginFlow;
+    };
+    /**
+     * Terminal commands beyond the tools, such as `logout`, `auth` or `refresh`.
+     * An MCP client never sees them. Each is listed in help and `agent-context`,
+     * and gets the words after its name.
+     */
+    commands?: readonly CliCommand[];
     /** Values to mask in every result: API keys, tokens. */
     secrets?: (ctx: Ctx) => Array<string | undefined | null>;
     /**

package/dist/check.js

@@ -50,6 +50,15 @@ export async function checkApp(app, options = {}) {
         add("warn", "schema", "ajv is not installed, so schemas were not checked against JSON Schema 2020-12. Add ajv as a dev dependency.");
     let totalBytes = 0;
     let largest;
+    for (const command of app.definition.commands ?? []) {
+        if (BUILTINS.includes(command.name) || app.find(command.name)) {
+            add("error", "names", `The terminal command '${command.name}' has the name of a built-in or a tool. Rename it.`);
+        }
+    }
+    const httpPort = app.definition.httpPort;
+    if (httpPort !== undefined && (!Number.isInteger(httpPort) || httpPort < 1 || httpPort > 65535)) {
+        add("error", "http", `httpPort is ${httpPort}, which is not a port number from 1 to 65535.`);
+    }
     for (const tool of app.allTools) {
         if (BUILTINS.includes(tool.command)) {
             add("error", "names", `'${tool.command}' is a built-in CLI command. Rename the tool.`, tool.name);
@@ -288,7 +297,7 @@ function checkDocs(app, file, add) {
             // The match may begin on the character before the binary, a newline included.
             const at = segment.offset + (match.index ?? 0) + (match[0].length - match[0].trimStart().length);
             const line = text.slice(0, at).split("\n").length;
-            if (BUILTINS.includes(command))
+            if (BUILTINS.includes(command) || app.definition.commands?.some((custom) => custom.name === command))
                 continue;
             const tool = app.find(command);
             if (!tool) {

package/dist/cli/completion.js

@@ -10,9 +10,9 @@ function globalFlags() {
 function toolFlags(tool) {
     return flagsFor(tool.jsonSchema).map((flag) => flag.flag);
 }
-function bash(bin, tools) {
+function bash(bin, tools, words) {
     const fn = `_${bin.replace(/[^A-Za-z0-9]/g, "_")}`;
-    const commands = [...tools.map((tool) => tool.command), ...BUILTINS].join(" ");
+    const commands = [...tools.map((tool) => tool.command), ...words].join(" ");
     const globals = globalFlags().join(" ");
     const cases = tools
         .map((tool) => `    ${tool.command}) COMPREPLY=( $(compgen -W "${[...toolFlags(tool), ...(tool.paginate ? ["--all", "--max-items"] : [])].join(" ")} ${globals}" -- "$cur") ) ;;`)
@@ -35,16 +35,16 @@ ${cases}
 complete -F ${fn} ${bin}
 `;
 }
-function zsh(bin, tools) {
+function zsh(bin, tools, words) {
     return `#compdef ${bin}
 # ${bin} completion for zsh, through zsh's bash compatibility layer.
 autoload -U +X bashcompinit && bashcompinit
-${bash(bin, tools)}`;
+${bash(bin, tools, words)}`;
 }
 function fishEscape(text) {
     return text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
 }
-function fish(bin, tools) {
+function fish(bin, tools, words) {
     const lines = [`# ${bin} completion for fish`, `complete -c ${bin} -f`];
     for (const tool of tools) {
         lines.push(`complete -c ${bin} -n '__fish_use_subcommand' -a '${tool.command}' -d '${fishEscape(tool.title)}'`);
@@ -52,20 +52,22 @@ function fish(bin, tools) {
             lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${tool.command}' -l '${flag.flag.slice(2)}' -d '${fishEscape(flag.help.slice(0, 80))}'`);
         }
     }
-    for (const builtin of BUILTINS)
-        lines.push(`complete -c ${bin} -n '__fish_use_subcommand' -a '${builtin}'`);
+    for (const word of words)
+        lines.push(`complete -c ${bin} -n '__fish_use_subcommand' -a '${word}'`);
     for (const flag of globalFlags())
         lines.push(`complete -c ${bin} -l '${flag.slice(2)}'`);
     return `${lines.join("\n")}\n`;
 }
 export function completionScript(app, shell, bin, env) {
     const tools = app.tools(env);
+    // The built-ins, then any terminal commands the app adds, such as logout.
+    const words = [...BUILTINS, ...(app.definition.commands ?? []).map((command) => command.name)];
     if (shell === "bash")
-        return bash(bin, tools);
+        return bash(bin, tools, words);
     if (shell === "zsh")
-        return zsh(bin, tools);
+        return zsh(bin, tools, words);
     if (shell === "fish")
-        return fish(bin, tools);
+        return fish(bin, tools, words);
     throw new UsageError(`completion expects bash, zsh or fish${shell ? `, got '${shell}'` : ""}.`, {
         hint: `Add \`source <(${bin} completion bash)\` to your shell's startup file.`,
     });

package/dist/cli/context.d.ts

@@ -24,6 +24,11 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
     exit_codes: Record<number, string>;
     hidden_commands?: number | undefined;
     toolsets?: Record<string, string> | undefined;
+    extra_commands?: {
+        command: string;
+        usage: string;
+        description: string;
+    }[] | undefined;
     commands: {
         command: string;
         title: string;
@@ -79,6 +84,11 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
     })[];
     toolsets?: Record<string, string> | undefined;
     hidden_commands: number;
+    extra_commands?: {
+        command: string;
+        usage: string;
+        description: string;
+    }[] | undefined;
     commands: {
         command: string;
         tool: string;

package/dist/cli/context.js

@@ -28,6 +28,13 @@ export function agentContext(app, env, bin, options = {}) {
     const names = policyEnvNames(app.envPrefix);
     const tools = app.tools(env);
     const hidden = app.allTools.length - tools.length;
+    // Terminal commands the app adds beside its tools, such as logout, and a sign-in flow that says what it takes.
+    const login = app.definition.login;
+    const extra = [...(typeof login === "object" ? [{ name: "login", ...login }] : []), ...(app.definition.commands ?? [])].map((command) => ({
+        command: command.name,
+        usage: `${bin} ${command.usage ?? command.name}`,
+        description: command.help,
+    }));
     const note = "--agent never confirms a write. A command that requires --confirm runs only when it is passed explicitly.";
     if (options.brief) {
         // Enough to pick a command: what each one is, and which write or need --confirm. The full read adds flags and settings.
@@ -38,6 +45,7 @@ export function agentContext(app, env, bin, options = {}) {
             usage: { run: `${bin} <command> [flags]`, help: `${bin} <command> --help`, note },
             exit_codes: EXIT_MEANINGS,
             ...(hidden ? { hidden_commands: hidden, ...(app.definition.toolsets ? { toolsets: app.definition.toolsets } : {}) } : {}),
+            ...(extra.length ? { extra_commands: extra } : {}),
             commands: tools.map((tool) => ({
                 command: tool.command,
                 title: tool.title,
@@ -76,13 +84,14 @@ 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_PORT`, value: env[`${app.envPrefix}_HTTP_PORT`] ?? null, description: `port for --http, ${app.definition.httpPort ?? 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,
+        ...(extra.length ? { extra_commands: extra } : {}),
         commands: tools.map((tool) => ({
             command: tool.command,
             tool: tool.name,

package/dist/cli/data.js

@@ -59,7 +59,7 @@ export async function runData(app, io, tokens, options) {
                 throw new UsageError("data sync expects the command to copy: data sync <command>.");
             const tool = app.find(command);
             if (!tool)
-                throw new UsageError(`Unknown command '${command}'.`, { hint: `Run \`${io.bin}\` to list commands.` });
+                throw new UsageError(`Unknown command '${command}'.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
             if (!tool.sync) {
                 const lists = app.allTools.filter((candidate) => candidate.sync).map((candidate) => candidate.command);
                 throw new UsageError(`${tool.command} is not a list that can be synced.`, { hint: `Lists that can: ${lists.join(", ") || "none"}.` });

package/dist/cli/help.js

@@ -191,11 +191,14 @@ export function renderGeneralHelp(app, bin) {
     // 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"],
+        [app.bins.cli, "list the commands"],
         [`${bin} <command> --help`, "what one takes, with examples"],
         [`${bin} which <words>`, "find the command for a task"],
-        [`${bin} doctor [--network]`, "check the setup and say what is wrong"],
-        [`${bin} login`, "how to connect an account"],
+        [`${bin} doctor${app.definition.doctorNetwork ? "" : " [--network]"}`, "check the setup and say what is wrong"],
+        typeof app.definition.login === "object"
+            ? [`${bin} ${app.definition.login.usage ?? "login"}`, app.definition.login.help]
+            : [`${bin} login`, "how to connect an account"],
+        ...(app.definition.commands ?? []).map((command) => [`${bin} ${command.usage ?? command.name}`, command.help]),
         [`${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
@@ -207,8 +210,10 @@ export function renderGeneralHelp(app, bin) {
             : []),
         [app.bins.mcp, "the MCP server over stdio; --http [--port N] for HTTP"],
     ];
+    // Tuning keeps a working default, so it is named on one line; agent-context says what each does.
+    const tuning = (app.definition.settings ?? []).filter((setting) => setting.tuning).map((setting) => setting.env);
     const settings = [
-        ...(app.definition.settings ?? []).map((setting) => [setting.env, setting.description]),
+        ...(app.definition.settings ?? []).filter((setting) => !setting.tuning).map((setting) => [setting.env, setting.description]),
         [`${names.readOnly}=1`, "hide and refuse every write"],
         [`${names.allowDestructive}=0`, "refuse the irreversible writes"],
         [`${names.toolsets}=a,b`, "only these toolsets, or all"],
@@ -236,6 +241,7 @@ export function renderGeneralHelp(app, bin) {
         ``,
         `Settings:`,
         ...settings.map(row),
+        ...(tuning.length ? [`  Also: ${tuning.join(", ")}, described in agent-context.`] : []),
         ``,
         `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`,
         ``,

package/dist/cli/run.js

@@ -140,7 +140,8 @@ export async function runCli(app, argv, partial = {}) {
     const at = findCommand(argv);
     const command = at === -1 ? undefined : argv[at];
     const builtin = command !== undefined && BUILTINS.includes(command);
-    const tool = command !== undefined && !builtin ? app.find(command) : undefined;
+    const custom = command !== undefined && !builtin ? app.definition.commands?.find((candidate) => candidate.name === command) : undefined;
+    const tool = command !== undefined && !builtin && !custom ? app.find(command) : undefined;
     const reserved = new Set(tool ? flagsFor(tool.jsonSchema).map((flag) => flag.flag) : []);
     let agent = argv.includes("--agent");
     try {
@@ -155,11 +156,16 @@ export async function runCli(app, argv, partial = {}) {
         }
         if (builtin)
             return await runBuiltin(app, io, command, rest, globals);
+        if (custom) {
+            if (globals.help)
+                return print(io, `\nUsage: ${io.bin} ${custom.usage ?? custom.name}\n\n${custom.help}\n`);
+            return await custom.run(io, rest);
+        }
         if (!tool) {
-            const candidates = [...app.tools(io.env).map((t) => t.command), ...BUILTINS];
+            const candidates = [...app.tools(io.env).map((t) => t.command), ...BUILTINS, ...(app.definition.commands ?? []).map((c) => c.name)];
             const guess = didYouMean(command, candidates);
             throw new UsageError(`Unknown command '${command}'.${guess ? ` Did you mean '${guess}'?` : ""}`, {
-                hint: `Run \`${io.bin}\` to list commands, or \`${io.bin} which <words>\` to find one.`,
+                hint: `Run \`${app.bins.cli}\` to list commands, or \`${io.bin} which <words>\` to find one.`,
             });
         }
         const seen = visibility(tool, app.policy(io.env));
@@ -196,6 +202,9 @@ async function runBuiltin(app, io, command, rest, globals) {
     // `<built-in> --help` explains the command instead of running it.
     if (globals.help && command === "install")
         return print(io, (await import("./install.js")).installHelp(app, io.bin));
+    const login = app.definition.login;
+    if (globals.help && command === "login" && typeof login === "object")
+        return print(io, `\nUsage: ${io.bin} ${login.usage ?? "login"}\n\n${login.help}\n`);
     if (globals.help && command !== "help")
         return print(io, renderGeneralHelp(app, io.bin));
     const target = rest.find((token) => !token.startsWith("-"));
@@ -209,13 +218,13 @@ async function runBuiltin(app, io, command, rest, globals) {
                 return print(io, renderGeneralHelp(app, io.bin));
             const tool = app.find(target);
             if (!tool)
-                throw new UsageError(`Unknown command '${target}'.`, { hint: `Run \`${io.bin}\` to list commands.` });
+                throw new UsageError(`Unknown command '${target}'.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
             return print(io, renderToolHelp(tool, io.bin));
         }
         case "schema": {
             const tool = target ? app.find(target) : undefined;
             if (!tool)
-                throw new UsageError(`schema expects a command${target ? `; '${target}' is not one` : ""}.`, { hint: `Run \`${io.bin}\` to list commands.` });
+                throw new UsageError(`schema expects a command${target ? `; '${target}' is not one` : ""}.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
             if (rest.includes("--output")) {
                 if (!tool.output)
                     throw new UsageError(`${tool.command} declares no output schema.`);
@@ -234,15 +243,16 @@ async function runBuiltin(app, io, command, rest, globals) {
                 return print(io, json(globals, matches.map(({ tool, score }) => ({ command: tool.command, title: tool.title, risk: tool.risk, score: Number(score.toFixed(2)) }))));
             }
             if (!matches.length)
-                return print(io, `No command matches '${query}'. Run \`${io.bin}\` to see them all.`);
+                return print(io, `No command matches '${query}'. Run \`${app.bins.cli}\` to see them all.`);
             return print(io, matches.map(({ tool }) => toolLine(tool)).join("\n"));
         }
         case "doctor":
             return runDoctor(app, io, { network: rest.includes("--network"), json: globals.format !== "auto" });
         case "login": {
-            const login = app.definition.login;
             if (typeof login === "function")
-                return await login(io);
+                return await login(io, rest);
+            if (typeof login === "object")
+                return await login.run(io, rest);
             if (typeof login === "string")
                 return print(io, login);
             return print(io, `${app.title} reads its credentials from the environment. Run \`${io.bin} doctor\` to see what is missing.`);

package/dist/doctor.js

@@ -68,15 +68,16 @@ export async function runDoctor(app, io, options) {
             ...(configured ? {} : { fix: `Run \`${app.bins.cli} login\` to see how to connect an account.` }),
         });
     }
+    const network = options.network || app.definition.doctorNetwork === true;
     if (ctx !== undefined && app.definition.doctor) {
         try {
-            checks.push(...(await app.definition.doctor(ctx, { network: options.network })));
+            checks.push(...(await app.definition.doctor(ctx, { network })));
         }
         catch (error) {
             checks.push({ name: "Service check", ok: false, detail: app.secrets.redact(error?.message ?? String(error)) });
         }
     }
-    if (!options.network && app.definition.doctor) {
+    if (!network && app.definition.doctor) {
         checks.push({ name: "Network", ok: true, warn: true, detail: "not checked; run with --network to call the service" });
     }
     const failed = checks.filter((check) => !check.ok && !check.warn);

package/dist/install.js

@@ -207,7 +207,7 @@ export function planInstall(app, options, context) {
     }
     const launch = launchFor(app, { local: options.local, ...(context.entry ? { entry: context.entry } : {}), ...(context.platform ? { platform: context.platform } : {}) });
     const usesNpx = launch.command === "npx" || launch.args.includes("npx");
-    const settings = app.definition.settings ?? [];
+    const settings = (app.definition.settings ?? []).filter((setting) => !setting.tuning);
     const variables = settings.map((setting) => setting.env);
     const env = { forwarded: [], copied: [], toAdd: [] };
     const notes = [];

package/dist/schema.js

@@ -83,6 +83,25 @@ export const CONTROL_NAMES = ["confirm", "wait_seconds"];
 export const CONFIRM_DESCRIPTION = "Set true only when the user asked for exactly this action.";
 /** The schema already carries the range and the default, so the words only say what the number is for. */
 export const WAIT_DESCRIPTION = "Seconds to wait for the job to finish before returning it to check later.";
+/**
+ * Zod 4 gives every whole number the safe-integer bounds, `maximum:
+ * 9007199254740991` and its negative, unless the schema sets its own. They say
+ * nothing a client can use, so they are left out of what it receives.
+ * Validation still runs on the schema itself.
+ */
+function withoutSafeIntegerBounds(node) {
+    if (Array.isArray(node))
+        return node.map(withoutSafeIntegerBounds);
+    if (node === null || typeof node !== "object")
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if ((key === "maximum" && value === Number.MAX_SAFE_INTEGER) || (key === "minimum" && value === Number.MIN_SAFE_INTEGER))
+            continue;
+        out[key] = withoutSafeIntegerBounds(value);
+    }
+    return out;
+}
 /**
  * A schema as clients receive it, without the `$schema` line that names its
  * dialect. A client reads JSON Schema 2020-12 when no dialect is named, so
@@ -91,10 +110,8 @@ export const WAIT_DESCRIPTION = "Seconds to wait for the job to finish before re
 export function advertised(schema) {
     const std = schema["~standard"];
     const plain = (json) => {
-        if (!("$schema" in json))
-            return json;
         const { $schema: _dialect, ...rest } = json;
-        return rest;
+        return withoutSafeIntegerBounds(rest);
     };
     return {
         "~standard": {

package/dist/serve.js

@@ -43,7 +43,7 @@ async function warnIfUnconfigured(app, env, warn) {
 export function httpOptions(app, env, argv) {
     const at = argv.findIndex((token) => token === "--port" || token.startsWith("--port="));
     const raw = at === -1 ? env[`${app.envPrefix}_HTTP_PORT`] : argv[at].includes("=") ? argv[at].split("=")[1] : argv[at + 1];
-    const port = Number(raw ?? 8787);
+    const port = Number(raw ?? app.definition.httpPort ?? 8787);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         throw new UsageError(`--port expects a port number, got '${raw}'.`);
     return {

package/package.json

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