@thenavidm/slipway 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.10, 2026-10-05: what TikTok needed
+
+- **`destructiveOff: "hide"`: a server can take its irreversible tools off the list when they are off.** By default `<PREFIX>_ALLOW_DESTRUCTIVE=0` keeps them listed and refuses each call. With `defaults: { destructiveOff: "hide" }` they leave the MCP tool list and the command list, as read-only mode does with every write, and calling one anyway is refused with the setting to unset. TikTok 1.1 hid its publishing tools this way, and keeps doing so.
+- **A shorter general help, for every server.** An agent reads it first and carries it through every later step. Slipway's settings past the two safety switches are named on the "Also" line with the app's tuning settings, the list formats and `--out` and `--timeout` are left to each command's help and `agent-context`, and the command lines say less. On TikTok it went from 530 tokens to 412, which cut Codex's CLI task by about 350 tokens.
+- **`hidden: true` keeps a command out of the general help**, such as `auth`, the name an older release used for `login`. It still runs, and `agent-context` still lists it.
+- **A refusal no longer doubles a period.** A summary that ends its own sentence, as TikTok's "Publish a video at SELF_ONLY." does, read "About to: Publish a video at SELF_ONLY.." in the refusal and the approval messages.
+
 ## 0.1.9, 2026-10-05: what Substack needed
 
 - **A resource can wait for an account.** `listed(env)` leaves a resource out until it returns true. Substack 2.2.3 offered its two resources only once a publication was connected; on Slipway they were always offered, and Claude Code then adds its own two resource tools to every message: 40 tokens in tool search, for reads that could only fail.

package/README.md

@@ -550,7 +550,7 @@ Every server reads these, under its own prefix: the app name in capitals, `NOTES
 | Variable | Default | What it does |
 |---|---|---|
 | `<PREFIX>_READ_ONLY` | `0` | `1` hides and refuses every write |
-| `<PREFIX>_ALLOW_DESTRUCTIVE` | `1` | `0` keeps writes and refuses the irreversible ones |
+| `<PREFIX>_ALLOW_DESTRUCTIVE` | `1` | `0` keeps writes and refuses the irreversible ones; an app with `defaults: { destructiveOff: "hide" }` also leaves them out of the list |
 | `<PREFIX>_AUDIT_LOG` | none | File that records every attempted write |
 | `<PREFIX>_CONFIRM` | `human` | `model` lets `confirm: true` alone confirm, for an agent with no person to ask |
 | `<PREFIX>_CACHE` | `1` | `0` never answers from the local cache |
@@ -572,9 +572,12 @@ See [CHANGELOG.md](CHANGELOG.md).
 
 | Server | Package | Covers |
 | --- | --- | --- |
+| [Apple Podcasts](https://github.com/thenavidm/apple-podcasts-mcp-cli) | [`@thenavidm/apple-podcasts-mcp-cli`](https://www.npmjs.com/package/@thenavidm/apple-podcasts-mcp-cli) 2.0.0 | The catalog, charts per country, reviews and feeds, your library on this Mac with its transcript excerpts, and analytics for a show you own |
 | [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 |
+| [Google Photos](https://github.com/thenavidm/google-photos-mcp-cli) | [`@thenavidm/google-photos-mcp-cli`](https://www.npmjs.com/package/@thenavidm/google-photos-mcp-cli) 2.0.0 | The photo picker, uploads, albums and their captions, places and maps, and media this server uploaded, across several Google accounts |
 | [Mastodon](https://github.com/thenavidm/mastodon-mcp-cli) | [`@thenavidm/mastodon-mcp-cli`](https://www.npmjs.com/package/@thenavidm/mastodon-mcp-cli) 2.0.0 | Posting, editing, threads, timelines, search, lists, notifications and following, on any instance |
 | [Midjourney](https://github.com/thenavidm/midjourney-mcp-cli) | [`@thenavidm/midjourney-mcp-cli`](https://www.npmjs.com/package/@thenavidm/midjourney-mcp-cli) 2.0.0 | Generating images and video, following jobs, downloads, moodboards, the account's library and the explore feeds, through a signed-in browser |
+| [Substack](https://github.com/thenavidm/substack-mcp-cli) | [`@thenavidm/substack-mcp-cli`](https://www.npmjs.com/package/@thenavidm/substack-mcp-cli) 3.0.0 | Drafts, publishing and scheduling, Notes, subscribers, analytics, tags, comments and researching other publications |
 | [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 |
 | [Threads](https://github.com/thenavidm/threads-mcp-cli) | [`@thenavidm/threads-mcp-cli`](https://www.npmjs.com/package/@thenavidm/threads-mcp-cli) 2.0.0 | Posting, threads, carousels, replies and reply approvals, insights and keyword search |
 | [ThriveCart](https://github.com/thenavidm/thrivecart-mcp-cli) | [`@thenavidm/thrivecart-mcp-cli`](https://www.npmjs.com/package/@thenavidm/thrivecart-mcp-cli) 3.0.0 | Products and pricing, transactions and revenue, customers, subscriptions and affiliates, across several carts |

package/dist/app.d.ts

@@ -90,6 +90,11 @@ export type CliCommand = {
      * taken as Slipway's global flag of the same name before the command sees it.
      */
     flags?: readonly string[];
+    /**
+     * Left out of the general help, as for the name an older release used for
+     * `login`. It still runs, and `agent-context` still lists it.
+     */
+    hidden?: boolean;
     run: (io: CliIO, args: string[]) => number | Promise<number>;
 };
 export type AppDefinition<Ctx> = {

package/dist/app.js

@@ -329,6 +329,11 @@ function assertVisible(tool, policy, envPrefix) {
             hint: `Unset ${names.readOnly} to allow writes.`,
         });
     }
+    if (seen.reason === "destructive") {
+        throw new RefusedError(`${tool.name} is unavailable: this server is running with ${names.allowDestructive}=0.`, {
+            hint: `Unset ${names.allowDestructive} to allow irreversible writes.`,
+        });
+    }
     throw new UsageError(`${tool.name} is in a toolset that is off: ${tool.tags.join(", ")}.`, {
         hint: `Add one of them to ${names.toolsets}, or set ${names.toolsets}=all.`,
     });

package/dist/cli/help.js

@@ -57,12 +57,15 @@ function hiddenNote(app, env) {
     const off = new Set();
     let byToolset = 0;
     let byReadOnly = 0;
+    let byDestructive = 0;
     for (const tool of app.allTools) {
         const seen = visibility(tool, policy);
         if (seen.visible)
             continue;
         if (seen.reason === "read-only")
             byReadOnly += 1;
+        else if (seen.reason === "destructive")
+            byDestructive += 1;
         else {
             byToolset += 1;
             for (const tag of tool.tags)
@@ -77,6 +80,8 @@ function hiddenNote(app, env) {
     }
     if (byReadOnly)
         lines.push(`  ${byReadOnly} ${byReadOnly === 1 ? "write is" : "writes are"} hidden by ${names.readOnly}=1.`);
+    if (byDestructive)
+        lines.push(`  ${byDestructive} irreversible ${byDestructive === 1 ? "write is" : "writes are"} hidden by ${names.allowDestructive}=0.`);
     return lines.length ? [...lines, ``] : [];
 }
 export function renderList(app, tools, bin, env = process.env) {
@@ -204,17 +209,18 @@ export function renderGeneralHelp(app, bin) {
     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.
+    // rarely needed commands share one line, an older name for a command is left out, and
+    // Slipway's settings past the two safety switches are named on one line.
     const commands = [
         [app.bins.cli, "list the commands"],
-        [`${bin} <command> --help`, "what one takes, with examples"],
+        [`${bin} <command> --help`, "what one takes"],
         [`${bin} which <words>`, "find the command for a task"],
-        [`${bin} doctor${app.definition.doctorNetwork ? "" : " [--network]"}`, "check the setup and say what is wrong"],
+        [`${bin} doctor${app.definition.doctorNetwork ? "" : " [--network]"}`, "check the setup"],
         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"],
+        ...(app.definition.commands ?? []).filter((command) => !command.hidden).map((command) => [`${bin} ${command.usage ?? command.name}`, command.help]),
+        [`${bin} install <client>`, "add the server to an MCP client"],
         ...(cache || sync ? [[`${bin} data`, "what is kept on this machine; data clear [<command>] deletes it"]] : []),
         ...(sync
             ? [
@@ -223,27 +229,41 @@ export function renderGeneralHelp(app, bin) {
                 [`${bin} data sql "<select>"`, "query local data with read-only SQL"],
             ]
             : []),
-        [app.bins.mcp, "the MCP server over stdio; --http [--port N] for HTTP"],
+        [app.bins.mcp, "the MCP server; --http [--port N] serves HTTP"],
+    ];
+    // Tuning keeps a working default, so it is named on one line with Slipway's own settings past
+    // the two safety switches; agent-context says what each does.
+    const tuning = [
+        ...(app.definition.settings ?? []).filter((setting) => setting.tuning).map((setting) => setting.env),
+        names.surface,
+        names.auditLog,
+        names.toolTimeoutMs,
+        names.confirm,
+        ...(cache ? [names.cache] : []),
+        ...(cache || sync ? [names.dataDir] : []),
+        `${app.envPrefix}_DEBUG`,
     ];
-    // 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 ?? []).filter((setting) => !setting.tuning).map((setting) => [setting.env, setting.description]),
         [`${names.readOnly}=1`, "hide and refuse every write"],
-        [`${names.allowDestructive}=0`, app.allTools.some((tool) => tool.spends) ? "refuse the irreversible writes and paid calls" : "refuse the irreversible writes"],
+        [
+            `${names.allowDestructive}=0`,
+            `${app.definition.defaults?.destructiveOff === "hide" ? "hide and refuse" : "refuse"} the irreversible writes${app.allTools.some((tool) => tool.spends) ? " and paid calls" : ""}`,
+        ],
         // With no tagged tool every tool is always on, so the switch would do nothing.
         ...(app.allTools.some((tool) => tool.tags.length > 0) ? [[`${names.toolsets}=a,b`, "only these toolsets, or all"]] : []),
-        [`${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 / _ALLOWED_ORIGINS`, "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));
+    // The list formats appear in the help of the commands that list; 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 !== "--jsonl" &&
+        flag !== "--csv / --tsv" &&
+        flag !== "--quiet" &&
+        flag !== "--out <file>" &&
+        flag !== "--timeout <ms>" &&
+        (flag !== "--wait" || jobs) &&
+        (flag !== "--refresh" || cache));
     const commandRow = table(commands);
     const settingRow = table(settings);
     const lines = [
@@ -251,13 +271,13 @@ export function renderGeneralHelp(app, bin) {
         `${app.title} ${app.version}`,
         ``,
         ...commands.map(commandRow),
-        `  Also: schema <command>, agent-context [--brief] (all of this as JSON), completion <shell>.`,
+        `  Also: schema <command>, agent-context (all of this as JSON), completion <shell>.`,
         ``,
         `Flags: ${flags.join(", ")}, and --agent: compact JSON, no prompts, never confirms a write.`,
         ``,
         `Settings:`,
         ...settings.map(settingRow),
-        ...(tuning.length ? [`  Also: ${tuning.join(", ")}, described in agent-context.`] : []),
+        `  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

@@ -8,7 +8,7 @@
  */
 import { writeFileSync } from "node:fs";
 import { runDoctor } from "../doctor.js";
-import { EXIT, UsageError, toSlipwayError } from "../errors.js";
+import { EXIT, RefusedError, UsageError, toSlipwayError } from "../errors.js";
 import { eachPage } from "../pages.js";
 import { visibility, policyEnvNames } from "../policy.js";
 import { outputJsonSchema } from "../schema.js";
@@ -169,6 +169,12 @@ export async function runCli(app, argv, partial = {}) {
             });
         }
         const seen = visibility(tool, app.policy(io.env));
+        if (!seen.visible && seen.reason === "destructive") {
+            const names = policyEnvNames(app.envPrefix);
+            throw new RefusedError(`${tool.command} is unavailable: ${names.allowDestructive}=0 hides the irreversible writes.`, {
+                hint: `Unset ${names.allowDestructive} to allow them.`,
+            });
+        }
         if (!seen.visible) {
             const names = policyEnvNames(app.envPrefix);
             throw new UsageError(seen.reason === "read-only"

package/dist/confirm.js

@@ -20,7 +20,7 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, createRequestStateCodec, inputRequired, inputResponse, } from "@modelcontextprotocol/server";
 import { RefusedError } from "./errors.js";
-import { consequence, Guard } from "./guard.js";
+import { consequence, Guard, sentenceBody } from "./guard.js";
 import { phrase, sha256, stableJson, versionAtLeast } from "./util.js";
 /** The key of Slipway's approval form among a call's input requests. */
 export const APPROVAL_KEY = "slipway_approval";
@@ -149,18 +149,18 @@ export async function personApproval(app, tool, rawArgs, ctx, env) {
         return undefined;
     if (answer.kind === "elicit" && answer.action === "accept") {
         guard.record(tool, summary, "blocked: person declined");
-        throw new RefusedError(`The approval form was accepted without ticking Approve, so ${tool.name} did not run. About to: ${summary}.`, {
+        throw new RefusedError(`The approval form was accepted without ticking Approve, so ${tool.name} did not run. About to: ${sentenceBody(summary)}.`, {
             hint: "Ask the user whether they want this, and call again only if they do.",
         });
     }
     if (answer.kind === "elicit" && answer.action === "cancel") {
         guard.record(tool, summary, "blocked: no answer");
-        throw new RefusedError(`The approval form was closed without an answer, so ${tool.name} did not run. About to: ${summary}.`, {
+        throw new RefusedError(`The approval form was closed without an answer, so ${tool.name} did not run. About to: ${sentenceBody(summary)}.`, {
             hint: "Ask the user whether they want this, and call again only if they do.",
         });
     }
     guard.record(tool, summary, "blocked: person declined");
-    throw new RefusedError(`The approval was declined, so ${tool.name} did not run. About to: ${summary}.`, {
+    throw new RefusedError(`The approval was declined, so ${tool.name} did not run. About to: ${sentenceBody(summary)}.`, {
         hint: "Do not call it again unless the user asks for it.",
     });
 }

package/dist/guard.d.ts

@@ -44,3 +44,5 @@ export declare class Guard {
 }
 /** Why a tool needs confirming, in the words a refusal and an approval form both use. */
 export declare function consequence(tool: Pick<Tool, "risk" | "consequence" | "spends">): string;
+/** A summary that ends its own sentence, "Publish a video.", is not given a second period. */
+export declare function sentenceBody(text: string): string;

package/dist/guard.js

@@ -58,7 +58,7 @@ export class Guard {
         }
         if (tool.requireConfirm && !options.confirmedBy) {
             this.record(tool, options.summary, "blocked: no confirm");
-            throw new RefusedError(`${tool.name} ${consequence(tool)}, so it will not run without ${this.confirmFlag}. About to: ${options.summary}. Call again with ${this.confirmFlag} if that is what was asked for.`, { hint: `Pass ${this.confirmFlag} only when the user asked for this exact action.` });
+            throw new RefusedError(`${tool.name} ${consequence(tool)}, so it will not run without ${this.confirmFlag}. About to: ${sentenceBody(options.summary)}. Call again with ${this.confirmFlag} if that is what was asked for.`, { hint: `Pass ${this.confirmFlag} only when the user asked for this exact action.` });
         }
         this.record(tool, options.summary, "allowed", options.confirmedBy);
     }
@@ -91,3 +91,7 @@ export function consequence(tool) {
         return "spends money and cannot be refunded";
     return tool.risk === "destructive" ? "is public or cannot be undone" : "has an effect that cannot be taken back";
 }
+/** A summary that ends its own sentence, "Publish a video.", is not given a second period. */
+export function sentenceBody(text) {
+    return text.trim().replace(/[.!?]+$/, "");
+}

package/dist/policy.d.ts

@@ -31,6 +31,8 @@ export type Policy = {
     confirm: ConfirmMode;
     /** Whether reads that opted in may answer from the local cache. */
     cache: boolean;
+    /** Whether the irreversible tools and paid calls are left out of the list, not only refused. */
+    hideDestructive: boolean;
 };
 export type PolicyDefaults = {
     /**
@@ -41,6 +43,13 @@ export type PolicyDefaults = {
     toolsets?: readonly string[] | "all" | ((env: NodeJS.ProcessEnv) => readonly string[] | "all");
     surface?: ToolSurface;
     confirm?: ConfirmMode;
+    /**
+     * What `<PREFIX>_ALLOW_DESTRUCTIVE=0` does to the irreversible tools and paid
+     * calls: `refuse` each call (the default), or `hide` them from the list, as
+     * read-only mode hides every write. A server that hid them before it moved
+     * keeps doing so.
+     */
+    destructiveOff?: "refuse" | "hide";
 };
 export type PolicyEnv = {
     readOnly: string;
@@ -59,10 +68,12 @@ export type Visibility = {
     visible: true;
 } | {
     visible: false;
-    reason: "read-only" | "toolset";
+    reason: "read-only" | "destructive" | "toolset";
 };
 /** Whether a tool is on under this policy, and if not, why, so a refusal can say how to turn it on. */
-export declare function visibility(tool: Pick<Tool, "risk" | "tags">, policy: Policy): Visibility;
+export declare function visibility(tool: Pick<Tool, "risk" | "tags"> & {
+    spends?: boolean;
+}, policy: Policy): Visibility;
 export declare function riskMark(tool: {
     risk: Risk;
     spends?: boolean;

package/dist/policy.js

@@ -47,21 +47,25 @@ export function readPolicy(env, prefix, defaults = {}) {
     const surface = env[names.surface]?.trim().toLowerCase();
     const timeout = Number(env[names.toolTimeoutMs]);
     const confirm = env[names.confirm]?.trim().toLowerCase();
+    const allowDestructive = flag(env[names.allowDestructive], true);
     return {
         readOnly: flag(env[names.readOnly], false),
-        allowDestructive: flag(env[names.allowDestructive], true),
+        allowDestructive,
         auditLog: env[names.auditLog]?.trim() || undefined,
         toolsets,
         surface: surface === "search" || surface === "full" ? surface : (defaults.surface ?? "full"),
         toolTimeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout : undefined,
         confirm: confirm === "human" || confirm === "model" ? confirm : (defaults.confirm ?? "human"),
         cache: flag(env[names.cache], true),
+        hideDestructive: !allowDestructive && defaults.destructiveOff === "hide",
     };
 }
 /** Whether a tool is on under this policy, and if not, why, so a refusal can say how to turn it on. */
 export function visibility(tool, policy) {
     if (policy.readOnly && tool.risk !== "read")
         return { visible: false, reason: "read-only" };
+    if (policy.hideDestructive && (tool.risk === "destructive" || tool.spends === true))
+        return { visible: false, reason: "destructive" };
     if (policy.toolsets !== "all" && tool.tags.length > 0) {
         const on = policy.toolsets;
         if (!tool.tags.some((tag) => on.has(tag)))

package/package.json

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