@thenavidm/slipway 0.1.0

package/dist/cli/data.js

@@ -0,0 +1,120 @@
+/**
+ * `data`: the local data file from a terminal.
+ *
+ *   data                        what is kept, where, and for which account
+ *   data sync <command> [flags] copy every page of a list to this machine
+ *   data search <words>         search synced records offline
+ *   data sql "<select>"         query it with read-only SQL
+ *   data clear [<command>]      delete this account's local data
+ */
+import { EXIT, UsageError } from "../errors.js";
+import { syncTool } from "../sync.js";
+import { flagsFor, parseToolArgs } from "./flags.js";
+import { formatOutput } from "./output.js";
+const SUBCOMMANDS = ["status", "sync", "search", "sql", "clear"];
+/** The value of `--name value` or `--name=value` in a list of tokens, and the tokens without it. */
+function take(tokens, name) {
+    const rest = [];
+    let value;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token === name) {
+            value = tokens[++i];
+            if (value === undefined)
+                throw new UsageError(`${name} expects a value.`);
+        }
+        else if (token.startsWith(`${name}=`))
+            value = token.slice(name.length + 1);
+        else
+            rest.push(token);
+    }
+    return { value, rest };
+}
+function print(io, value, options) {
+    io.stdout(formatOutput(value, undefined, { format: options.format === "auto" ? "json" : options.format, select: options.select }));
+    return EXIT.ok;
+}
+export async function runData(app, io, tokens, options) {
+    const [first, ...rest] = tokens;
+    const sub = first ?? "status";
+    if (!SUBCOMMANDS.includes(sub)) {
+        throw new UsageError(`data has no '${sub}'. It takes: ${SUBCOMMANDS.join(", ")}.`, { hint: `Run \`${io.bin} help\` for what each does.` });
+    }
+    const store = await app.localData(io.env);
+    const scope = app.dataScope(await app.context(io.env));
+    switch (sub) {
+        case "status": {
+            const synced = store.synced(scope).map((entry) => ({ ...entry, command: app.find(entry.tool)?.command ?? entry.tool }));
+            return print(io, {
+                file: store.file,
+                account: scope,
+                cached_results: store.cacheEntries(scope),
+                synced,
+                can_sync: app.allTools.filter((tool) => tool.sync).map((tool) => tool.command),
+            }, options);
+        }
+        case "sync": {
+            const [command, ...flags] = rest;
+            if (!command)
+                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.` });
+            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"}.` });
+            }
+            const args = await app.parse(tool, parseToolArgs(flags, flagsFor(tool.jsonSchema), tool.positional));
+            const report = await syncTool(app, tool, args, {
+                surface: "cli",
+                env: io.env,
+                ...(io.isTTY && !options.agent ? { onProgress: ({ message }) => io.stderr(`… ${message ?? ""}\n`) } : {}),
+            });
+            return print(io, report, options);
+        }
+        case "search": {
+            const where = take(rest, "--in");
+            const limit = take(where.rest, "--limit");
+            const words = limit.rest.filter((token) => !token.startsWith("--")).join(" ");
+            if (!words)
+                throw new UsageError("data search expects the words to find: data search <words>.");
+            const tool = where.value ? app.find(where.value) : undefined;
+            if (where.value && !tool)
+                throw new UsageError(`Unknown command '${where.value}'.`);
+            const count = limit.value === undefined ? 20 : Number(limit.value);
+            if (!Number.isInteger(count) || count < 1 || count > 100)
+                throw new UsageError(`--limit expects a whole number from 1 to 100, got '${limit.value}'.`);
+            const hits = store.search(scope, words, { ...(tool ? { tool: tool.name } : {}), limit: count });
+            if (options.format === "auto" && io.isTTY && !options.select?.length) {
+                if (!hits.length) {
+                    io.stdout(`Nothing synced matches '${words}'. Sync a list first: ${io.bin} data sync <command>.\n`);
+                    return EXIT.ok;
+                }
+                for (const hit of hits)
+                    io.stdout(`${app.find(hit.tool)?.command ?? hit.tool}  ${hit.id}  ${hit.snippet.replace(/\s+/g, " ")}\n`);
+                return EXIT.ok;
+            }
+            return print(io, { query: words, count: hits.length, results: hits }, options);
+        }
+        case "sql": {
+            const sql = rest.join(" ").trim();
+            if (!sql)
+                throw new UsageError(`data sql expects one SELECT statement: ${io.bin} data sql "select tool, count(*) from records group by tool"`);
+            const rows = store.query(sql);
+            return print(io, rows, options);
+        }
+        case "clear": {
+            const cacheOnly = rest.includes("--cache");
+            const command = rest.find((token) => !token.startsWith("--"));
+            const tool = command ? app.find(command) : undefined;
+            if (command && !tool)
+                throw new UsageError(`Unknown command '${command}'.`);
+            const cleared = {
+                cached_results: tool ? 0 : store.cacheClear(scope),
+                records: cacheOnly ? 0 : store.clearRecords(scope, tool?.name),
+            };
+            return print(io, cleared, options);
+        }
+    }
+    return EXIT.ok;
+}

package/dist/cli/flags.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Flags derived from the JSON Schema an MCP client receives.
+ *
+ * The terminal and the model read the same schema, so a flag cannot exist on
+ * one surface and not the other, and its help text is the description the
+ * model reads.
+ */
+import type { JsonSchema } from "../schema.js";
+export type FlagKind = "string" | "number" | "integer" | "boolean" | "enum" | "json";
+export type Flag = {
+    /** The property name: `reply_to`. */
+    key: string;
+    /** The long flag: `--reply-to`. */
+    flag: string;
+    kind: FlagKind;
+    required: boolean;
+    repeatable: boolean;
+    choices?: string[];
+    help: string;
+    default?: unknown;
+};
+export declare function flagName(key: string): string;
+export declare function flagsFor(schema: JsonSchema): Flag[];
+/** JSON inline, or `@path` to read it from a file, which spares a person quoting a large body. */
+export declare function parseJsonValue(raw: string, label: string): unknown;
+/**
+ * Parse argv against a tool's flags.
+ *
+ * Accepts `--flag value`, `--flag=value`, the underscore spelling, `--no-flag`
+ * for a boolean, repeated or comma-separated lists, and bare words for the
+ * positional arguments. The schema validates the result afterwards; this only
+ * gets values into the right types and reports mistakes in terms of flags.
+ */
+export declare function parseToolArgs(argv: readonly string[], flags: readonly Flag[], positional: readonly string[]): Record<string, unknown>;
+export declare function missingRequired(flags: readonly Flag[], args: Record<string, unknown>): Flag[];

package/dist/cli/flags.js

@@ -0,0 +1,208 @@
+/**
+ * Flags derived from the JSON Schema an MCP client receives.
+ *
+ * The terminal and the model read the same schema, so a flag cannot exist on
+ * one surface and not the other, and its help text is the description the
+ * model reads.
+ */
+import { readFileSync } from "node:fs";
+import { UsageError } from "../errors.js";
+import { didYouMean } from "../search.js";
+/** The first concrete type, looking through nullable unions and type lists. */
+function concrete(node) {
+    const union = node.anyOf ?? node.oneOf;
+    if (union) {
+        const options = union.filter((option) => option.type !== "null");
+        // A union of plain literals is an enum in disguise, which a person types as a word.
+        if (options.length > 1 && options.every((option) => option.const !== undefined)) {
+            return { ...node, enum: options.map((option) => option.const) };
+        }
+        return concrete({ ...(options[0] ?? {}), description: node.description ?? options[0]?.description });
+    }
+    if (Array.isArray(node.type))
+        return { ...node, type: node.type.find((type) => type !== "null") ?? "string" };
+    return node;
+}
+function kindOf(node) {
+    const n = concrete(node);
+    if (n.enum)
+        return { kind: "enum", repeatable: false, choices: n.enum.map(String) };
+    if (n.type === "array") {
+        const item = concrete(n.items ?? {});
+        if (item.enum)
+            return { kind: "enum", repeatable: true, choices: item.enum.map(String) };
+        if (item.type === "object" || item.type === "array")
+            return { kind: "json", repeatable: true };
+        if (item.type === "number" || item.type === "integer" || item.type === "boolean")
+            return { kind: item.type, repeatable: true };
+        return { kind: "string", repeatable: true };
+    }
+    if (n.type === "object")
+        return { kind: "json", repeatable: false };
+    if (n.type === "number" || n.type === "integer" || n.type === "boolean")
+        return { kind: n.type, repeatable: false };
+    return { kind: "string", repeatable: false };
+}
+export function flagName(key) {
+    return `--${key.replace(/_/g, "-")}`;
+}
+export function flagsFor(schema) {
+    const properties = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    return Object.entries(properties).map(([key, node]) => {
+        const n = concrete(node);
+        return {
+            key,
+            flag: flagName(key),
+            ...kindOf(node),
+            required: required.has(key),
+            help: (node.description ?? n.description ?? "").trim(),
+            ...(node.default !== undefined ? { default: node.default } : n.default !== undefined ? { default: n.default } : {}),
+        };
+    });
+}
+function coerce(flag, raw) {
+    switch (flag.kind) {
+        case "number":
+        case "integer": {
+            const value = Number(raw);
+            if (raw.trim() === "" || !Number.isFinite(value) || (flag.kind === "integer" && !Number.isInteger(value))) {
+                throw new UsageError(`${flag.flag} expects ${flag.kind === "integer" ? "a whole number" : "a number"}, got '${raw}'.`);
+            }
+            return value;
+        }
+        case "boolean":
+            if (/^(true|1|yes)$/i.test(raw))
+                return true;
+            if (/^(false|0|no)$/i.test(raw))
+                return false;
+            throw new UsageError(`${flag.flag} expects true or false, got '${raw}'.`);
+        case "enum":
+            if (flag.choices && !flag.choices.includes(raw)) {
+                throw new UsageError(`${flag.flag} expects one of: ${flag.choices.join(", ")}. Got '${raw}'.`);
+            }
+            return raw;
+        case "json":
+            return parseJsonValue(raw, flag.flag);
+        default:
+            return raw;
+    }
+}
+/** JSON inline, or `@path` to read it from a file, which spares a person quoting a large body. */
+export function parseJsonValue(raw, label) {
+    let text = raw;
+    if (raw.startsWith("@") && raw.length > 1) {
+        try {
+            text = readFileSync(raw.slice(1), "utf8");
+        }
+        catch (error) {
+            throw new UsageError(`${label} could not read ${raw.slice(1)}: ${error.message}`);
+        }
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new UsageError(`${label} expects JSON${raw.startsWith("@") ? " in that file" : ""}, got '${text.slice(0, 60)}'.`);
+    }
+}
+/** Lists of numbers and fixed choices may be written once with commas; free text never is, since it may contain commas. */
+function splits(flag) {
+    return flag.repeatable && (flag.kind === "enum" || flag.kind === "number" || flag.kind === "integer");
+}
+/**
+ * Parse argv against a tool's flags.
+ *
+ * Accepts `--flag value`, `--flag=value`, the underscore spelling, `--no-flag`
+ * for a boolean, repeated or comma-separated lists, and bare words for the
+ * positional arguments. The schema validates the result afterwards; this only
+ * gets values into the right types and reports mistakes in terms of flags.
+ */
+export function parseToolArgs(argv, flags, positional) {
+    const out = {};
+    const bare = [];
+    const byName = new Map();
+    for (const flag of flags) {
+        byName.set(flag.flag, flag);
+        byName.set(`--${flag.key}`, flag);
+    }
+    const assign = (flag, value) => {
+        if (flag.repeatable) {
+            const values = Array.isArray(value) ? value : [value];
+            out[flag.key] = [...(out[flag.key] ?? []), ...values];
+        }
+        else {
+            out[flag.key] = value;
+        }
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--") {
+            bare.push(...argv.slice(i + 1));
+            break;
+        }
+        if (!token.startsWith("--") || token === "-") {
+            bare.push(token);
+            continue;
+        }
+        const eq = token.indexOf("=");
+        const name = eq === -1 ? token : token.slice(0, eq);
+        let flag = byName.get(name);
+        if (!flag && name.startsWith("--no-")) {
+            const positive = byName.get(`--${name.slice(5)}`);
+            if (positive?.kind === "boolean" && eq === -1) {
+                assign(positive, false);
+                continue;
+            }
+        }
+        if (!flag) {
+            const guess = didYouMean(name, flags.map((f) => f.flag));
+            throw new UsageError(`Unknown option ${name}.${guess ? ` Did you mean ${guess}?` : ""}`);
+        }
+        let raw = eq === -1 ? undefined : token.slice(eq + 1);
+        if (raw === undefined && flag.kind === "boolean") {
+            // A bare boolean is true. Only an explicit true or false after it is
+            // taken as its value, so a positional word after a switch is not swallowed.
+            const next = argv[i + 1];
+            if (next !== undefined && /^(true|false)$/i.test(next)) {
+                raw = next;
+                i++;
+            }
+            else {
+                assign(flag, true);
+                continue;
+            }
+        }
+        if (raw === undefined)
+            raw = argv[++i];
+        if (raw === undefined)
+            throw new UsageError(`${flag.flag} expects a value.`);
+        if (splits(flag) && raw.includes(","))
+            assign(flag, raw.split(",").map((part) => coerce(flag, part.trim())));
+        else
+            assign(flag, coerce(flag, raw));
+    }
+    if (bare.length > 0) {
+        const byKey = new Map(flags.map((flag) => [flag.key, flag]));
+        const slots = positional.length > 0 ? positional.map((key) => byKey.get(key)).filter(Boolean) : [];
+        if (slots.length === 0) {
+            // With nothing declared, one bare word fills the first required argument,
+            // so `search-posts cats` works before anyone reads the help.
+            const target = flags.find((flag) => flag.required && out[flag.key] === undefined);
+            if (target)
+                slots.push(target);
+        }
+        for (const [index, word] of bare.entries()) {
+            const slot = slots[index];
+            if (!slot)
+                throw new UsageError(`Unexpected argument '${word}'.`);
+            if (out[slot.key] !== undefined && !slot.repeatable)
+                throw new UsageError(`${slot.flag} was given twice.`);
+            assign(slot, coerce(slot, word));
+        }
+    }
+    return out;
+}
+export function missingRequired(flags, args) {
+    return flags.filter((flag) => flag.required && args[flag.key] === undefined);
+}

package/dist/cli/help.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a person sees before they know what to type.
+ */
+import type { App } from "../app.js";
+import type { Tool } from "../tool.js";
+/** The words the CLI owns, which no tool command may take. */
+export declare const BUILTINS: readonly ["help", "tools", "schema", "agent-context", "which", "doctor", "login", "completion", "version", "data", "install"];
+export declare const GLOBAL_FLAGS: Array<[string, string]>;
+export declare function renderList(app: App, tools: readonly Tool[], bin: string): string;
+/** An example's arguments as the command someone would type. */
+export declare function exampleCommand(bin: string, tool: Tool, args: Record<string, unknown>): string;
+export declare function renderToolHelp(tool: Tool, bin: string): string;
+export declare function renderGeneralHelp(app: App, bin: string): string;
+/** One line per tool, for search results and listings. */
+export declare function toolLine(tool: Tool): string;

package/dist/cli/help.js

@@ -0,0 +1,213 @@
+/**
+ * What a person sees before they know what to type.
+ */
+import { EXIT } from "../errors.js";
+import { policyEnvNames, riskMark } from "../policy.js";
+import { firstSentence } from "../search.js";
+import { flagsFor } from "./flags.js";
+const COLUMN = 30;
+/** The words the CLI owns, which no tool command may take. */
+export const BUILTINS = ["help", "tools", "schema", "agent-context", "which", "doctor", "login", "completion", "version", "data", "install"];
+export const GLOBAL_FLAGS = [
+    ["--json", "pretty JSON"],
+    ["--compact", "one-line JSON"],
+    ["--jsonl", "one JSON value per line, for lists"],
+    ["--csv / --tsv", "a table, for lists of records"],
+    ["--quiet", "one value per line: ids, or the one --select field"],
+    ["--select <a,b.c>", "keep only these fields; dotted paths descend"],
+    ["--agent", "JSON, compact, no prompts, no color. Never confirms anything"],
+    ["--out <file>", "write the output to a new file instead of stdout"],
+    ["--input <json|@file|->", "all arguments as one JSON object; flags override it"],
+    ["--dry-run", "check everything and print what would run, without running it"],
+    ["--wait", "for a job: wait until it finishes, however long that takes"],
+    ["--refresh", "skip the local cache and fetch again"],
+    ["--timeout <ms>", "give up after this long"],
+];
+function line(left, help) {
+    if (!help)
+        return [left];
+    return left.length < COLUMN ? [`${left.padEnd(COLUMN)}${help}`] : [left, `${" ".repeat(COLUMN)}${help}`];
+}
+function riskWords(tool) {
+    const base = tool.risk === "read" ? "read only" : tool.risk === "write" ? "writes, reversible" : "public or irreversible";
+    return tool.requireConfirm ? `${base}, runs only with --confirm` : base;
+}
+export function renderList(app, tools, bin) {
+    const width = Math.max(10, ...tools.map((tool) => tool.command.length)) + 2;
+    const lines = [``, `${app.title} ${app.version}${app.description ? `: ${app.description}` : ""}`, ``];
+    const toolsets = app.definition.toolsets ?? {};
+    const groups = new Map();
+    for (const tool of tools) {
+        const group = tool.tags[0] ?? "";
+        groups.set(group, [...(groups.get(group) ?? []), tool]);
+    }
+    const ordered = [...groups.entries()].sort(([a], [b]) => (a === "" ? -1 : b === "" ? 1 : a.localeCompare(b)));
+    const grouped = ordered.length > 1 || (ordered[0]?.[0] ?? "") !== "";
+    lines.push(`Commands (${tools.length})`);
+    for (const [group, members] of ordered) {
+        if (grouped)
+            lines.push(``, `  ${group || "general"}${group && toolsets[group] ? `: ${toolsets[group]}` : ""}`);
+        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 a command takes, with examples`, `  ${bin} which <words>          find the command for a task`, `  ${bin} schema <command>       the JSON Schema an MCP client sees`, `  ${bin} agent-context          everything above, as JSON for an agent`, `  ${bin} doctor                 check the setup`, `  ${bin} install <client>       add it to an MCP client: codex, claude-code, cursor…`, ``);
+    const hidden = app.allTools.length - tools.length;
+    if (hidden > 0) {
+        const names = policyEnvNames(app.envPrefix);
+        lines.push(`  ${hidden} more ${hidden === 1 ? "command is" : "commands are"} off: see ${names.readOnly} and ${names.toolsets} in \`${bin} help\`.`, ``);
+    }
+    return lines.join("\n");
+}
+function shellQuote(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** An example's arguments as the command someone would type. */
+export function exampleCommand(bin, tool, args) {
+    const parts = [bin, tool.command];
+    const rest = { ...args };
+    for (const key of tool.positional) {
+        const value = rest[key];
+        if (value === undefined || typeof value === "object")
+            break;
+        parts.push(shellQuote(String(value)));
+        delete rest[key];
+    }
+    for (const [key, value] of Object.entries(rest)) {
+        const flag = `--${key.replace(/_/g, "-")}`;
+        if (value === true)
+            parts.push(flag);
+        else if (value === false)
+            parts.push(`${flag}=false`);
+        else if (Array.isArray(value) && value.every((item) => typeof item !== "object"))
+            for (const item of value)
+                parts.push(flag, shellQuote(String(item)));
+        else if (value !== null && typeof value === "object")
+            parts.push(flag, shellQuote(JSON.stringify(value)));
+        else if (value !== undefined)
+            parts.push(flag, shellQuote(String(value)));
+    }
+    return parts.join(" ");
+}
+function placeholder(flag) {
+    if (flag.kind === "boolean")
+        return "";
+    if (flag.choices)
+        return flag.choices.length <= 6 ? ` <${flag.choices.join("|")}>` : " <choice>";
+    return ` <${flag.kind === "json" ? "json|@file" : flag.kind}>`;
+}
+export function renderToolHelp(tool, bin) {
+    const flags = flagsFor(tool.jsonSchema).filter((flag) => flag.key !== "confirm");
+    const required = flags.filter((flag) => flag.required);
+    const optional = flags.filter((flag) => !flag.required);
+    const positional = tool.positional.length ? tool.positional : required[0] ? [required[0].key] : [];
+    const usage = [
+        `${bin} ${tool.command}`,
+        ...required.map((flag) => (positional.includes(flag.key) ? `<${flag.key}>` : `${flag.flag}${placeholder(flag)}`)),
+        optional.length ? "[options]" : "",
+        tool.requireConfirm ? "--confirm" : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+    const lines = [``, `${tool.title}`, ``, tool.description, ``, `Usage:`, `  ${usage}`, ``];
+    const describe = (list, heading) => {
+        if (!list.length)
+            return;
+        lines.push(`${heading}:`);
+        for (const flag of list) {
+            const extra = [flag.repeatable ? "Repeatable." : "", flag.default !== undefined ? `Default ${JSON.stringify(flag.default)}.` : ""]
+                .filter(Boolean)
+                .join(" ");
+            lines.push(...line(`  ${flag.flag}${placeholder(flag)}`, [flag.help, extra].filter(Boolean).join(" ")));
+        }
+        lines.push(``);
+    };
+    describe(required, "Required");
+    describe(optional, "Options");
+    if (tool.requireConfirm) {
+        lines.push(`Safety:`, ...line("  --confirm", "required: this runs only when you mean it"), ``);
+    }
+    if (tool.paginate) {
+        lines.push(`Pages:`, ...line("  --all", "follow every page and print all items"), ...line("  --max-items <n>", "stop after this many items"), ``);
+    }
+    if (tool.job) {
+        const check = tool.statusOf ? "" : `${tool.command}-status <job-id>`;
+        lines.push(`Job:`, ...line("  --wait", "wait until the job finishes"), ...line("  --wait-seconds <n>", "wait this long, then print the job to check later"), ...(check ? line(`  ${check}`, "check on it later") : []), ``);
+    }
+    if (tool.examples.length) {
+        lines.push(`Examples:`);
+        for (const example of tool.examples)
+            lines.push(`  # ${example.description}`, `  ${exampleCommand(bin, tool, example.args)}`, ``);
+    }
+    lines.push(`Output:`);
+    for (const [flag, help] of GLOBAL_FLAGS)
+        lines.push(...line(`  ${flag}`, help));
+    lines.push(``, `Risk: ${riskWords(tool)}`, ``);
+    return lines.join("\n");
+}
+export function renderGeneralHelp(app, bin) {
+    const names = policyEnvNames(app.envPrefix);
+    const lines = [
+        ``,
+        `${app.title} ${app.version}${app.description ? `: ${app.description}` : ""}`,
+        ``,
+        `Usage:`,
+        `  ${app.bins.mcp}                      run the MCP server over stdio (what an MCP client launches)`,
+        `  ${app.bins.mcp} --http [--port N]    run it over HTTP`,
+        `  ${bin}                      list every command`,
+        `  ${bin} <command> [flags]    run one`,
+        ``,
+        `Commands:`,
+        ...line("  <command> --help", "what a command takes, with examples"),
+        ...line("  which <words>", "find the command for a task"),
+        ...line("  schema <command>", "the JSON Schema an MCP client sees (--output for the result's)"),
+        ...line("  agent-context", "commands, flags, risk, exit codes and settings as JSON"),
+        ...line("  doctor [--network]", "check the setup and say what is wrong"),
+        ...line("  login", "how to connect an account"),
+        ...line("  install <client>", "add this server to claude-code, codex, claude-desktop, cursor, vscode or gemini"),
+        ...line("  completion <shell>", "tab completion for bash, zsh or fish"),
+        ...line("  version", "print the version"),
+        ``,
+        ...(app.allTools.some((tool) => tool.cache || tool.sync)
+            ? [
+                `Local data:`,
+                ...line("  data", "what is kept on this machine, and where"),
+                ...(app.allTools.some((tool) => tool.sync)
+                    ? [
+                        ...line("  data sync <command>", "copy every page of a list to this machine"),
+                        ...line("  data search <words>", "search synced records offline (--in <command>)"),
+                        ...line('  data sql "<select>"', "query local data with read-only SQL"),
+                    ]
+                    : []),
+                ...line("  data clear [<command>]", "delete this account's local data (--cache for cached results only)"),
+                ``,
+            ]
+            : []),
+        `Output flags, on any command:`,
+        ...GLOBAL_FLAGS.flatMap(([flag, help]) => line(`  ${flag}`, help)),
+        ``,
+        ...(app.definition.settings?.length
+            ? [`${app.title} settings:`, ...app.definition.settings.flatMap((setting) => line(`  ${setting.env}`, setting.description)), ``]
+            : []),
+        `Settings:`,
+        ...line(`  ${names.readOnly}=1`, "hide and refuse every write"),
+        ...line(`  ${names.allowDestructive}=0`, "keep writes, refuse the irreversible ones"),
+        ...line(`  ${names.toolsets}=a,b`, "only these toolsets (or all)"),
+        ...line(`  ${names.surface}=search`, "MCP lists three tools that find, describe and run the rest"),
+        ...line(`  ${names.auditLog}=<file>`, "append every attempted write to this file"),
+        ...line(`  ${names.toolTimeoutMs}=<ms>`, "give up on any tool after this long"),
+        ...line(`  ${names.confirm}=model`, "let confirm: true alone confirm, for an agent with no person to ask"),
+        ...(app.allTools.some((tool) => tool.cache) ? line(`  ${names.cache}=0`, "never answer from the local cache") : []),
+        ...(app.allTools.some((tool) => tool.cache || tool.sync) ? line(`  ${names.dataDir}=<dir>`, "keep local data in this folder") : []),
+        ``,
+        `Exit codes:`,
+        `  ${EXIT.ok} ok   ${EXIT.usage} usage or refused write   ${EXIT.notFound} not found   ${EXIT.auth} auth   ${EXIT.api} API   ${EXIT.rateLimited} rate limited   ${EXIT.notConfigured} nothing configured`,
+        ``,
+    ];
+    if (app.definition.links?.repository)
+        lines.push(app.definition.links.repository, ``);
+    return lines.join("\n");
+}
+/** One line per tool, for search results and listings. */
+export function toolLine(tool) {
+    return `${riskMark(tool.risk)} ${tool.command}  ${tool.title}: ${firstSentence(tool.description, 80)}`;
+}

package/dist/cli/install.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `install <client>` from a terminal: plan the change, show it, make it.
+ */
+import type { App, CliIO } from "../app.js";
+import type { Format } from "./output.js";
+export declare function runInstall(app: App, io: CliIO, tokens: string[], options: {
+    agent: boolean;
+    dryRun: boolean;
+    format: Format;
+}): Promise<number>;

package/dist/cli/install.js

@@ -0,0 +1,65 @@
+/**
+ * `install <client>` from a terminal: plan the change, show it, make it.
+ */
+import { EXIT, UsageError } from "../errors.js";
+import { applyInstall, CLIENTS, planInstall } from "../install.js";
+function value(tokens, name) {
+    const at = tokens.findIndex((token) => token === name || token.startsWith(`${name}=`));
+    if (at === -1)
+        return undefined;
+    const token = tokens[at];
+    const found = token.includes("=") ? token.slice(name.length + 1) : tokens[at + 1];
+    if (found === undefined || found.startsWith("--"))
+        throw new UsageError(`${name} expects a value.`);
+    return found;
+}
+function describe(plan) {
+    const lines = [];
+    if (plan.run)
+        lines.push(`  ${[plan.run.command, ...plan.run.args.map((arg) => (/^[A-Za-z0-9_./:@=-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`))].join(" ")}`);
+    else
+        lines.push(...(typeof plan.entry === "string" ? plan.entry : JSON.stringify({ [plan.name]: plan.entry }, null, 2)).split("\n").map((line) => `  ${line}`));
+    return lines.join("\n");
+}
+export async function runInstall(app, io, tokens, options) {
+    const client = tokens.find((token) => !token.startsWith("--") && !["--scope", "--name"].includes(tokens[tokens.indexOf(token) - 1] ?? ""));
+    const ids = Object.keys(CLIENTS);
+    if (!client || !ids.includes(client)) {
+        throw new UsageError(`install expects one of: ${ids.join(", ")}.`, { hint: `${io.bin} install codex --dry-run shows the change without making it.` });
+    }
+    const scope = (value(tokens, "--scope") ?? CLIENTS[client].scopes[0]);
+    if (scope !== "user" && scope !== "project")
+        throw new UsageError(`--scope expects user or project, got '${scope}'.`);
+    const name = value(tokens, "--name") ?? app.name;
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(name))
+        throw new UsageError("--name expects letters, digits, '-' or '_'.");
+    const plan = planInstall(app, { client, scope, name, copyEnv: tokens.includes("--copy-env"), local: tokens.includes("--local") }, { env: io.env, cwd: io.cwd ?? process.cwd() });
+    const title = CLIENTS[client].title;
+    const machine = options.agent || options.format !== "auto";
+    if (options.dryRun) {
+        if (machine)
+            io.stdout(`${JSON.stringify({ dry_run: true, ...plan, text: undefined })}\n`);
+        else {
+            const where = plan.run ? "would run" : `would write ${plan.file}`;
+            io.stdout([``, `${title} (${scope}): ${where}`, ``, describe(plan), ``, ...plan.notes.map((note) => `${note}`), ``].join("\n"));
+        }
+        return EXIT.ok;
+    }
+    const result = await applyInstall(plan, io);
+    if (result.ran && result.ran.code !== 0) {
+        const missing = result.ran.code === 127;
+        const exists = /already exists/i.test(result.ran.output);
+        throw new UsageError(missing ? "The claude command is not on PATH, so nothing was added." : exists ? `${name} is already in Claude Code (${scope}).` : `claude mcp add-json failed: ${result.ran.output}`, { hint: missing ? `Install Claude Code, or run it yourself:\n${describe(plan)}` : exists ? `Remove it first with \`claude mcp remove ${name} --scope ${scope}\`, then run install again.` : undefined });
+    }
+    if (machine) {
+        io.stdout(`${JSON.stringify({ installed: true, client, scope, name, ...(plan.file ? { file: plan.file } : {}), ...(result.backup ? { backup: result.backup } : {}), env: plan.env, notes: plan.notes })}\n`);
+    }
+    else {
+        const lines = [``, `Added ${name} to ${title} (${scope})${plan.file ? `: ${plan.file}` : "."}`];
+        if (result.backup)
+            lines.push(`The previous file is saved as ${result.backup}.`);
+        lines.push(``, describe(plan), ``, ...plan.notes, `Restart ${title} to load it.`, ``);
+        io.stdout(lines.join("\n"));
+    }
+    return EXIT.ok;
+}