@thenavidm/slipway 0.1.0

package/dist/check.js

@@ -0,0 +1,313 @@
+/**
+ * `slipway check`: the release gate.
+ *
+ * Unit tests prove a handler works. They do not prove that what a client
+ * receives matches what the CLI offers, that a schema will be accepted, that an
+ * example in the README still runs, or that the server answers when nothing is
+ * configured. Those are the failures that reach users, so they are checked here,
+ * against the real server, over the real protocol.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { agentContext } from "./cli/context.js";
+import { flagsFor } from "./cli/flags.js";
+import { BUILTINS, GLOBAL_FLAGS, renderToolHelp } from "./cli/help.js";
+import { connectInMemory } from "./rpc.js";
+import { repeatedDefinitions, schemaBytes, validate, formatIssues } from "./schema.js";
+import { REQUIRES_USER_INTERACTION } from "./server.js";
+const PROPERTY = /^[A-Za-z0-9_.-]{1,64}$/;
+const DEFAULT_BUDGET = { warnBytes: 16 * 1024, errorBytes: 128 * 1024 };
+function strip(schema) {
+    const { $schema: _ignored, ...rest } = schema;
+    return rest;
+}
+function stable(value) {
+    return JSON.stringify(value, (_key, inner) => inner && typeof inner === "object" && !Array.isArray(inner)
+        ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => a.localeCompare(b)))
+        : inner);
+}
+/** Draft 2020-12 meta-schema validation, the check Claude Code runs before accepting a tool. Needs ajv. */
+async function metaValidator() {
+    try {
+        const module = (await import("ajv/dist/2020.js"));
+        const ajv = new module.default({ strict: false, validateFormats: false });
+        return (schema) => (ajv.validateSchema(schema) ? undefined : ajv.errorsText(ajv.errors));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function checkApp(app, options = {}) {
+    const env = options.env ?? process.env;
+    const budget = options.schemaBudget ?? DEFAULT_BUDGET;
+    const findings = [];
+    const add = (level, check, message, tool) => findings.push({ level, check, message, ...(tool ? { tool } : {}) });
+    const tools = app.tools(env);
+    const meta = await metaValidator();
+    if (!meta)
+        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 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);
+        }
+        const words = tool.description.split(/\s+/).filter(Boolean).length;
+        if (tool.description.length < 30 || words < 5) {
+            add("warn", "descriptions", "The description is too thin to choose this tool by. Say what it does and when to use it.", tool.name);
+        }
+        if (tool.title.length > 60)
+            add("warn", "descriptions", "The title is long for a picker; keep it under 60 characters.", tool.name);
+        if (tool.requireConfirm && !tool.summary) {
+            add("warn", "safety", "A confirmed tool with no summary shows only its name in the refusal and the audit log.", tool.name);
+        }
+        const schema = tool.jsonSchema;
+        if (schema.type !== "object")
+            add("error", "schema", "The input schema's root must be an object.", tool.name);
+        for (const key of ["anyOf", "oneOf", "allOf"]) {
+            if (key in schema)
+                add("warn", "schema", `A root-level ${key} is flattened by some clients; nest it inside a property.`, tool.name);
+        }
+        const properties = schema.properties ?? {};
+        for (const name of Object.keys(properties)) {
+            if (!PROPERTY.test(name))
+                add("error", "schema", `Property '${name}' must be 1-64 letters, digits, '_', '.' or '-'.`, tool.name);
+        }
+        const undocumented = Object.entries(properties).filter(([name, prop]) => name !== "confirm" && !prop.description).map(([name]) => name);
+        if (undocumented.length)
+            add("warn", "descriptions", `No description for: ${undocumented.join(", ")}.`, tool.name);
+        const problem = meta?.(schema);
+        if (problem)
+            add("error", "schema", `Not valid JSON Schema 2020-12: ${problem}`, tool.name);
+        const bytes = schemaBytes(schema);
+        totalBytes += bytes;
+        if (!largest || bytes > largest.bytes)
+            largest = { name: tool.name, bytes };
+        if (bytes > budget.errorBytes)
+            add("error", "size", `The schema is ${Math.round(bytes / 1024)} KB. Advertise a short schema and validate the full one in the handler.`, tool.name);
+        else if (bytes > budget.warnBytes)
+            add("warn", "size", `The schema is ${Math.round(bytes / 1024)} KB, which a model pays for every time it loads this tool.`, tool.name);
+        const repeated = repeatedDefinitions(schema);
+        if (repeated.length)
+            add("warn", "size", `Definitions appear more than once: ${repeated.slice(0, 5).join(", ")}${repeated.length > 5 ? "…" : ""}.`, tool.name);
+        for (const example of tool.examples) {
+            const result = await validate(tool.schema, example.args);
+            if (!result.ok)
+                add("error", "examples", `Example "${example.description}" does not match the schema: ${formatIssues(result.issues)}`, tool.name);
+        }
+        try {
+            renderToolHelp(tool, app.bins.cli);
+            flagsFor(schema);
+        }
+        catch (error) {
+            add("error", "cli", `The CLI cannot describe this tool: ${error.message}`, tool.name);
+        }
+    }
+    if (!app.definition.package) {
+        add("warn", "install", "No package is set, so `install` points clients at this copy on disk instead of the published one. Set package to the npm name.");
+    }
+    const instructions = app.instructions ?? "";
+    if (!instructions)
+        add("warn", "instructions", "No server instructions. Clients use them to decide when to reach for these tools.");
+    else if (instructions.length > 512) {
+        const opening = instructions.slice(0, 512).toLowerCase();
+        if (!opening.includes(app.name.toLowerCase()) && !opening.includes(app.title.toLowerCase())) {
+            add("warn", "instructions", `Some clients read only the first 512 characters, and those never say what ${app.title} is.`);
+        }
+    }
+    try {
+        agentContext(app, env, app.bins.cli);
+    }
+    catch (error) {
+        add("error", "cli", `agent-context failed: ${error.message}`);
+    }
+    await checkParity(app, env, tools, add);
+    for (const file of options.docs ?? [])
+        checkDocs(app, file, add);
+    let startupMs;
+    if (options.bin)
+        startupMs = await checkStartup(options.bin, add);
+    const errors = findings.filter((finding) => finding.level === "error").length;
+    return {
+        ok: errors === 0,
+        errors,
+        warnings: findings.length - errors,
+        findings,
+        stats: {
+            tools: tools.length,
+            allTools: app.allTools.length,
+            reads: tools.filter((tool) => tool.risk === "read").length,
+            writes: tools.filter((tool) => tool.risk === "write").length,
+            irreversible: tools.filter((tool) => tool.risk === "destructive").length,
+            confirmed: tools.filter((tool) => tool.requireConfirm).length,
+            typedOutput: tools.filter((tool) => tool.output).length,
+            schemaBytes: totalBytes,
+            ...(largest ? { largestTool: largest } : {}),
+            ...(startupMs !== undefined ? { startupMs } : {}),
+        },
+    };
+}
+/**
+ * What an MCP client receives must be exactly what the CLI offers, on both
+ * protocol revisions a client may open with.
+ */
+async function checkParity(app, env, tools, add) {
+    const policy = app.policy(env);
+    if (policy.surface === "search")
+        return;
+    const seen = new Set();
+    // The same problem on both revisions is reported once.
+    const once = (level, check, message, tool) => {
+        const key = `${check}\0${message}\0${tool ?? ""}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        add(level, check, message, tool);
+    };
+    for (const era of ["legacy", "modern"])
+        await checkParityIn(era, app, env, tools, once);
+}
+async function checkParityIn(era, app, env, tools, add) {
+    const policy = app.policy(env);
+    let client;
+    try {
+        client = await connectInMemory(app, env, { era });
+    }
+    catch (error) {
+        add("error", "mcp", `The MCP server did not start (${era === "modern" ? "2026-07-28" : "2025"} protocol): ${error.message}`);
+        return;
+    }
+    try {
+        if ((client.initialize.instructions ?? "") !== (app.instructions ?? ""))
+            add("error", "mcp", "The instructions a client receives differ from the app's.");
+        const listed = await client.listTools();
+        const byName = new Map(listed.map((tool) => [tool.name, tool]));
+        for (const tool of tools) {
+            const wire = byName.get(tool.name);
+            if (!wire) {
+                add("error", "mcp", "The CLI offers this tool but the MCP server does not list it.", tool.name);
+                continue;
+            }
+            if (stable(strip(wire.inputSchema)) !== stable(strip(tool.jsonSchema))) {
+                add("error", "mcp", "The schema a client receives differs from the one the CLI derives its flags from.", tool.name);
+            }
+            const annotations = wire.annotations ?? {};
+            if (annotations.readOnlyHint !== (tool.risk === "read") || annotations.destructiveHint !== (tool.risk === "destructive")) {
+                add("error", "mcp", "The annotations a client receives do not match the tool's risk.", tool.name);
+            }
+            if (tool.requireConfirm && policy.confirm === "human" && wire._meta?.[REQUIRES_USER_INTERACTION] !== true) {
+                add("error", "mcp", "A confirmed tool is missing its request for a person's approval.", tool.name);
+            }
+            if (tool.output && !wire.outputSchema)
+                add("error", "mcp", "The tool declares an output schema that clients never receive.", tool.name);
+        }
+        for (const wire of listed) {
+            if (!tools.some((tool) => tool.name === wire.name))
+                add("error", "mcp", "The MCP server lists a tool the CLI does not offer.", wire.name);
+        }
+    }
+    catch (error) {
+        add("error", "mcp", `Listing tools failed: ${error.message}`);
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+/** Every command and flag a README or SKILL.md tells someone to type must exist. */
+function checkDocs(app, file, add) {
+    if (!existsSync(file)) {
+        add("error", "docs", `${file} does not exist.`);
+        return;
+    }
+    const text = readFileSync(file, "utf8");
+    const bins = [app.bins.cli, app.bins.mcp].map((bin) => bin.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+    const pattern = new RegExp(`(?:^|[\\s\`'"(])(?:${bins})((?:[ \\t]+[^\\s\`'"|;&)]+)*)`, "gm");
+    const globals = new Set(GLOBAL_FLAGS.flatMap(([flag]) => flag.split(" / ").map((part) => part.split(" ")[0])).concat("--help", "-h", "--version", "-v", "--plain", "--confirm", "--wait", "--refresh", "--in", "--limit", "--cache", "--scope", "--name", "--copy-env", "--local", "--all", "--max-items", "--network", "--output", "--brief", "--http", "--port", "--no-color", "--no-input", "--yes", "--agent"));
+    // Only code is something a reader copies and runs. A sentence that mentions
+    // the binary ("if it fails, STOP") is prose and is not checked.
+    for (const segment of codeSegments(text))
+        for (const match of segment.code.matchAll(pattern)) {
+            // Everything after a shell comment is prose, not arguments.
+            const raw = (match[1] ?? "").trim().split(/\s+/).filter(Boolean).map((token) => token.replace(/[.,;:]+$/, ""));
+            const comment = raw.findIndex((token) => token.startsWith("#"));
+            const tokens = comment === -1 ? raw : raw.slice(0, comment);
+            const command = tokens.find((token) => !token.startsWith("-"));
+            if (!command || /^[<$[{…]/.test(command))
+                continue;
+            // 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))
+                continue;
+            const tool = app.find(command);
+            if (!tool) {
+                add("error", "docs", `${file}:${line} names '${command}', which is not a command.`);
+                continue;
+            }
+            const known = new Set(flagsFor(tool.jsonSchema).flatMap((flag) => [flag.flag, `--${flag.key}`, ...(flag.kind === "boolean" ? [`--no-${flag.flag.slice(2)}`] : [])]));
+            for (const token of tokens) {
+                if (!token.startsWith("--"))
+                    continue;
+                const flag = token.split("=")[0];
+                if (!known.has(flag) && !globals.has(flag))
+                    add("error", "docs", `${file}:${line} passes ${flag} to '${command}', which does not take it.`, tool.name);
+            }
+        }
+}
+/** Fenced code blocks and inline code spans, with where each starts in the file. */
+function codeSegments(text) {
+    const segments = [];
+    const fenced = [];
+    for (const match of text.matchAll(/^(```|~~~)[^\n]*\n([\s\S]*?)^\1[ \t]*$/gm)) {
+        const start = (match.index ?? 0) + match[0].indexOf("\n") + 1;
+        segments.push({ code: match[2] ?? "", offset: start });
+        fenced.push([match.index ?? 0, (match.index ?? 0) + match[0].length]);
+    }
+    for (const match of text.matchAll(/`([^`\n]+)`/g)) {
+        const at = match.index ?? 0;
+        if (fenced.some(([start, end]) => at >= start && at < end))
+            continue;
+        segments.push({ code: match[1] ?? "", offset: at + 1 });
+    }
+    return segments;
+}
+/**
+ * Start the built server the way a client does, with nothing configured, and
+ * expect an answer. A server that exits or hangs here is broken for every new
+ * user, however good its tests are.
+ */
+function checkStartup(bin, add) {
+    return new Promise((resolve) => {
+        const home = mkdtempSync(join(tmpdir(), "slipway-check-"));
+        const started = performance.now();
+        const child = spawn(process.execPath, [bin], { cwd: home, env: { PATH: process.env.PATH ?? "", HOME: home, TMPDIR: home }, stdio: ["pipe", "pipe", "pipe"] });
+        let output = "";
+        let done = false;
+        const finish = (ms) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            child.kill("SIGKILL");
+            resolve(ms);
+        };
+        const timer = setTimeout(() => {
+            add("error", "startup", "The server did not answer initialize within 10 seconds with nothing configured.");
+            finish();
+        }, 10_000);
+        child.on("exit", (code) => {
+            if (!done) {
+                add("error", "startup", `The server exited with code ${code} before answering. It must start and explain what is missing instead.`);
+                finish();
+            }
+        });
+        child.stdout.on("data", (chunk) => {
+            output += chunk.toString();
+            if (output.includes('"protocolVersion"'))
+                finish(Math.round(performance.now() - started));
+        });
+        child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "slipway-check", version: "0" } } })}\n`);
+    });
+}

package/dist/cli/completion.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tab completion, generated from the same tool list as everything else.
+ */
+import type { App } from "../app.js";
+export declare function completionScript(app: App, shell: string | undefined, bin: string, env: NodeJS.ProcessEnv): string;

package/dist/cli/completion.js

@@ -0,0 +1,72 @@
+/**
+ * Tab completion, generated from the same tool list as everything else.
+ */
+import { UsageError } from "../errors.js";
+import { flagsFor } from "./flags.js";
+import { BUILTINS, GLOBAL_FLAGS } from "./help.js";
+function globalFlags() {
+    return GLOBAL_FLAGS.flatMap(([flag]) => flag.split(" / ").map((part) => part.split(" ")[0])).concat("--help");
+}
+function toolFlags(tool) {
+    return flagsFor(tool.jsonSchema).map((flag) => flag.flag);
+}
+function bash(bin, tools) {
+    const fn = `_${bin.replace(/[^A-Za-z0-9]/g, "_")}`;
+    const commands = [...tools.map((tool) => tool.command), ...BUILTINS].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") ) ;;`)
+        .join("\n");
+    return `# ${bin} completion for bash
+${fn}() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${commands}" -- "$cur") )
+    return
+  fi
+  case "\${COMP_WORDS[1]}" in
+${cases}
+    schema|help) COMPREPLY=( $(compgen -W "${tools.map((tool) => tool.command).join(" ")}" -- "$cur") ) ;;
+    completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") ) ;;
+    doctor) COMPREPLY=( $(compgen -W "--network --json" -- "$cur") ) ;;
+    *) COMPREPLY=( $(compgen -W "${globals}" -- "$cur") ) ;;
+  esac
+}
+complete -F ${fn} ${bin}
+`;
+}
+function zsh(bin, tools) {
+    return `#compdef ${bin}
+# ${bin} completion for zsh, through zsh's bash compatibility layer.
+autoload -U +X bashcompinit && bashcompinit
+${bash(bin, tools)}`;
+}
+function fishEscape(text) {
+    return text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+function fish(bin, tools) {
+    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)}'`);
+        for (const flag of flagsFor(tool.jsonSchema)) {
+            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 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);
+    if (shell === "bash")
+        return bash(bin, tools);
+    if (shell === "zsh")
+        return zsh(bin, tools);
+    if (shell === "fish")
+        return fish(bin, tools);
+    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

@@ -0,0 +1,97 @@
+/**
+ * The CLI described to an agent in one read.
+ *
+ * An agent that has to run `--help` on every command before using one spends a
+ * round trip per command. `agent-context` hands it every command, flag, risk,
+ * example, exit code and setting at once, as JSON it can act on.
+ */
+import type { App } from "../app.js";
+export declare const SLIPWAY_VERSION: string;
+export declare const EXIT_MEANINGS: Record<number, string>;
+export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: string, options?: {
+    brief?: boolean;
+}): {
+    name: string;
+    title: string;
+    version: string;
+    framework: {
+        name: string;
+        version: string;
+    };
+    description?: string | undefined;
+    binaries: {
+        mcp: string;
+        cli: string;
+    };
+    usage: {
+        run: string;
+        help: string;
+        agent_mode: string;
+        confirm_flag: string;
+        note: string;
+    };
+    exit_codes: Record<number, string>;
+    global_flags: {
+        flag: string;
+        description: string;
+    }[];
+    settings: ({
+        env: string;
+        set: boolean;
+        secret?: boolean | undefined;
+        description: string;
+    } | {
+        env: string;
+        value: boolean;
+        description: string;
+    } | {
+        env: string;
+        value: string | string[];
+        description: string;
+    } | {
+        env: string;
+        value: string | null;
+        description: string;
+    } | {
+        env: string;
+        value: number | null;
+        description: string;
+    })[];
+    toolsets?: Record<string, string> | undefined;
+    hidden_commands: number;
+    commands: ({
+        command: string;
+        title: string;
+        risk: import("../tool.js").Risk;
+        requires_confirm: boolean;
+    } | {
+        command: string;
+        tool: string;
+        title: string;
+        description: string;
+        risk: import("../tool.js").Risk;
+        requires_confirm: boolean;
+        toolsets?: readonly string[] | undefined;
+        positional?: readonly string[] | undefined;
+        flags: {
+            flag: string;
+            type: import("./flags.js").FlagKind;
+            required: boolean;
+            repeatable?: boolean | undefined;
+            choices?: string[] | undefined;
+            default?: {} | null | undefined;
+            description?: string | undefined;
+        }[];
+        output_schema?: import("../schema.js").JsonSchema | undefined;
+        paginates?: boolean | undefined;
+        job?: {
+            status_command: string;
+            background: boolean;
+        } | undefined;
+        checks_jobs_of?: string | undefined;
+        examples?: {
+            description: string;
+            command: string;
+        }[] | undefined;
+    })[];
+};

package/dist/cli/context.js

@@ -0,0 +1,94 @@
+/**
+ * The CLI described to an agent in one read.
+ *
+ * An agent that has to run `--help` on every command before using one spends a
+ * round trip per command. `agent-context` hands it every command, flag, risk,
+ * example, exit code and setting at once, as JSON it can act on.
+ */
+import { createRequire } from "node:module";
+import { EXIT } from "../errors.js";
+import { policyEnvNames } from "../policy.js";
+import { outputJsonSchema } from "../schema.js";
+import { exampleCommand, GLOBAL_FLAGS } from "./help.js";
+import { flagsFor } from "./flags.js";
+const require = createRequire(import.meta.url);
+export const SLIPWAY_VERSION = require("../../package.json").version;
+export const EXIT_MEANINGS = {
+    [EXIT.ok]: "ok",
+    [EXIT.error]: "unexpected error",
+    [EXIT.usage]: "usage error, or a write the guard refused",
+    [EXIT.notFound]: "not found",
+    [EXIT.auth]: "authentication or permission",
+    [EXIT.api]: "upstream API error or timeout",
+    [EXIT.rateLimited]: "rate limited",
+    [EXIT.notConfigured]: "nothing configured",
+};
+export function agentContext(app, env, bin, options = {}) {
+    const policy = app.policy(env);
+    const names = policyEnvNames(app.envPrefix);
+    const tools = app.tools(env);
+    return {
+        name: app.name,
+        title: app.title,
+        version: app.version,
+        framework: { name: "slipway", version: SLIPWAY_VERSION },
+        ...(app.description ? { description: app.description } : {}),
+        binaries: app.bins,
+        usage: {
+            run: `${bin} <command> [flags]`,
+            help: `${bin} <command> --help`,
+            agent_mode: "--agent",
+            confirm_flag: "--confirm",
+            note: "--agent never confirms a write. A command that requires --confirm runs only when it is passed explicitly.",
+        },
+        exit_codes: EXIT_MEANINGS,
+        global_flags: GLOBAL_FLAGS.map(([flag, description]) => ({ flag, description })),
+        settings: [
+            ...(app.definition.settings ?? []).map((setting) => ({
+                env: setting.env,
+                set: Boolean(env[setting.env]),
+                ...(setting.secret ? { secret: true } : {}),
+                description: setting.description,
+            })),
+            { env: names.readOnly, value: policy.readOnly, description: "hide and refuse every write" },
+            { env: names.allowDestructive, value: policy.allowDestructive, description: "allow public or irreversible writes" },
+            { env: names.toolsets, value: policy.toolsets === "all" ? "all" : [...policy.toolsets], description: "toolsets that are on" },
+            { env: names.surface, value: policy.surface, description: "full tool list, or search for very large catalogs" },
+            { 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" },
+        ],
+        ...(app.definition.toolsets ? { toolsets: app.definition.toolsets } : {}),
+        hidden_commands: app.allTools.length - tools.length,
+        commands: tools.map((tool) => options.brief
+            ? { command: tool.command, title: tool.title, risk: tool.risk, requires_confirm: tool.requireConfirm }
+            : {
+                command: tool.command,
+                tool: tool.name,
+                title: tool.title,
+                description: tool.description,
+                risk: tool.risk,
+                requires_confirm: tool.requireConfirm,
+                ...(tool.tags.length ? { toolsets: tool.tags } : {}),
+                ...(tool.positional.length ? { positional: tool.positional } : {}),
+                flags: flagsFor(tool.jsonSchema)
+                    .filter((flag) => flag.key !== "confirm")
+                    .map((flag) => ({
+                    flag: flag.flag,
+                    type: flag.kind,
+                    required: flag.required,
+                    ...(flag.repeatable ? { repeatable: true } : {}),
+                    ...(flag.choices ? { choices: flag.choices } : {}),
+                    ...(flag.default !== undefined ? { default: flag.default } : {}),
+                    ...(flag.help ? { description: flag.help } : {}),
+                })),
+                ...(tool.output ? { output_schema: outputJsonSchema(tool.output) } : {}),
+                ...(tool.paginate ? { paginates: true } : {}),
+                ...(tool.job && !tool.statusOf ? { job: { status_command: `${tool.command}-status`, background: "background" in tool.job } } : {}),
+                ...(tool.statusOf ? { checks_jobs_of: tool.statusOf.replace(/_/g, "-") } : {}),
+                ...(tool.examples.length
+                    ? { examples: tool.examples.map((example) => ({ description: example.description, command: exampleCommand(bin, tool, example.args) })) }
+                    : {}),
+            }),
+    };
+}

package/dist/cli/data.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `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 type { App, CliIO } from "../app.js";
+import { type Format } from "./output.js";
+export type DataOptions = {
+    format: Format;
+    select?: string[];
+    agent: boolean;
+};
+export declare function runData(app: App, io: CliIO, tokens: string[], options: DataOptions): Promise<number>;