@wirecat/cli-core 0.407.0 → 0.409.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## 0.409.0 — 24.10.2026
+
+### Added
+
+- **Shared lists declare typed queries, including bots, schedules, forum topics, calls and stickers.** Stored bot chats, recipients, send history,
+  profiles and schedules filter at their native readers; forum title terms go to the provider. Message predicates
+  require `--offline` and run in SQLite before the limit, reporting interpreted time bounds. Provider lists that
+  accept no filters refuse terms before connecting, instead of filtering an incomplete response. Existing empty
+  queries keep their previous behavior. Shared list-result contracts include the template schema for provider CLIs.
+
+## 0.408.0 — 24.10.2026
+
+### Fixed
+
+- **MCP discovery retains permission-denied commands.** Full listings and searches return each command's
+  current `availability`, including a reason and permission key when blocked. With a named profile,
+  CLI help and command discovery also show current availability without hiding commands. Read-only profiles and process
+  locks keep writing commands discoverable. Calls still recheck permissions and refuse before execution;
+  seeing a command does not grant access. Bot MCP also lists bot-scoped `config show|set|unset` behind the
+  existing authority rules, without exposing options that could select personal-account settings. Consumers
+  that pin MCP catalogues should refresh them and use availability rather than absence to determine access.
+
 ## 0.407.0 — 24.10.2026
 
 ### Added

package/dist/background/schedules.d.ts

@@ -75,7 +75,7 @@ export declare const scheduledRuns: (state: string) => {
     job: string;
     last: LastRun | undefined;
 }[];
-export declare const listSchedules: (state: string) => Schedule[];
+export declare const listSchedules: (state: string, filter?: Partial<Pick<Schedule, "name" | "kind">>) => Schedule[];
 export declare const describeWhen: (when: When) => string;
 /** How one operating system starts `argv` at the schedule's times. Every timer runs the same thing: `<cli> schedule exec <file>`. */
 export interface Timer {

package/dist/background/schedules.js

@@ -98,11 +98,13 @@ export const scheduledRuns = (state) => {
         return [];
     }
 };
-export const listSchedules = (state) => existsSync(schedulesDir(state))
+export const listSchedules = (state, filter = {}) => existsSync(schedulesDir(state))
     ? readdirSync(schedulesDir(state))
         .map((name) => scheduleFile(state, name))
         .filter((file) => existsSync(file))
         .map(readSchedule)
+        .filter((schedule) => (filter.name === undefined || schedule.name === filter.name) &&
+        (filter.kind === undefined || schedule.kind === filter.kind))
         .sort((a, b) => a.name.localeCompare(b.name))
     : [];
 export const describeWhen = (when) => "every" in when

package/dist/cli/bot/admins.js

@@ -6,10 +6,12 @@ import { guardedWrite } from "../../sends/guarded.js";
 import { newOperationId } from "../../sends/send-id.js";
 import { REMOTE_READ, REMOTE_WRITE } from "../effects.js";
 import { renderAnswer, snakeKeys } from "../envelope.js";
+import { listQuery, typedQuery, withQuery } from "../list-query.js";
 import { rightsOf } from "../messenger/admin-commands.js";
 import { renderItem, wholeList } from "../messenger/chat-answers.js";
 import { botContext, online } from "./context.js";
 import { botExamples } from "./examples.js";
+import { BOT_ADMINS_QUERY } from "./list-queries.js";
 import { botCan } from "./messages.js";
 const CHAT = "a chat id, or the title of a chat this bot has seen";
 const PERSON = "the person's user id";
@@ -24,10 +26,10 @@ const personOf = (typed) => {
 export const botAdminsCommand = (bot) => {
     const offered = bot.adminRights ?? ADMIN_RIGHTS;
     const command = new Command("admins").description("the admins of a chat the bot is an admin in");
-    annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "chats admins list Team") })
+    withQuery(annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "chats admins list Team") })
         .description("the chat's admins and what each may do")
-        .argument("<chat>", CHAT)
-        .action(async function (chat) {
+        .argument("<chat>", CHAT), BOT_ADMINS_QUERY).action(async function (chat, words) {
+        listQuery(typedQuery(words), BOT_ADMINS_QUERY, "bot chats admins list");
         const context = online(botContext(this, bot), this);
         const ref = context.chatRef(chat);
         await context.run(async (events) => {

package/dist/cli/bot/command.js

@@ -6,10 +6,14 @@ import { guardedWrite } from "../../sends/guarded.js";
 import { newOperationId } from "../../sends/send-id.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE, REMOTE_READ, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { withQuery } from "../list-query.js";
 import { renderItem, wholeList } from "../messenger/chat-answers.js";
+import { RECIPIENTS_QUERY, recipientFilter } from "../messenger/recipients-query.js";
+import { SENDS_QUERY, sendFilter } from "../messenger/sends-query.js";
 import { botAdminsCommand, botMembersCommand } from "./admins.js";
 import { botContext, online } from "./context.js";
 import { botExamples } from "./examples.js";
+import { BOT_CHATS_QUERY, BOT_PROFILES_QUERY, botChatFilter, botProfileName } from "./list-queries.js";
 import { botMcpCommand } from "./mcp.js";
 import { botCan, botIdOf, botMessagesCommand } from "./messages.js";
 import { botModerateCommand, botRulesCommand } from "./moderation.js";
@@ -114,11 +118,12 @@ const meCommand = (bot) => annotate(new Command("me"), { effects: REMOTE_READ, e
         }
     });
 });
-const listCommand = (bot, tokenVariable) => annotate(new Command("list"), { effects: LOCAL_READ, examples: botExamples(bot, "list", "list --check") })
+const listCommand = (bot, tokenVariable) => withQuery(annotate(new Command("list"), { effects: LOCAL_READ, examples: botExamples(bot, "list", "list --check") }), BOT_PROFILES_QUERY)
     .description(`every name on this machine that has a bot token; --check asks ${bot.name ?? "the messenger"} which bot each is`)
     .summary("every bot profile on this machine; --check asks which bot each is")
     .option("--check", "ask the messenger who each bot is, with its token")
-    .action(async function () {
+    .action(async function (words) {
+    const wanted = botProfileName(words);
     const context = botContext(this, bot);
     const check = this.opts().check === true;
     if (check)
@@ -132,6 +137,8 @@ const listCommand = (bot, tokenVariable) => annotate(new Command("list"), { effe
         }
         const rows = [];
         for (const name of names) {
+            if (wanted !== undefined && name !== wanted)
+                continue;
             const tokens = bot.tokenStore?.(this, name) ??
                 new BotTokenStore({
                     app: bot.app,
@@ -161,11 +168,12 @@ const recipientsCommand = (bot) => {
     const command = new Command("recipients")
         .description("the chats this bot may write to; with no list, every chat — `clear` removes the list")
         .summary("the chats this bot may write to; with no list, every chat");
-    annotate(command.command("list"), { effects: LOCAL_READ, examples: botExamples(bot, "recipients list") })
+    withQuery(annotate(command.command("list"), { effects: LOCAL_READ, examples: botExamples(bot, "recipients list") }), RECIPIENTS_QUERY)
         .description("the chats on the list, or nothing when there is no list")
-        .action(async function () {
+        .action(async function (words) {
+        const filter = recipientFilter(words, "bot recipients list");
         const context = botContext(this, bot);
-        await context.run(async () => renderAnswer(this, context, wholeList("bot recipients list", (context.recipients().read() ?? []).map(snakeKeys))));
+        await context.run(async () => renderAnswer(this, context, wholeList("bot recipients list", context.recipients().list(filter).items.map(snakeKeys))));
     });
     grantsAuthority(annotate(command.command("add"), {
         effects: LOCAL_WRITE,
@@ -203,21 +211,23 @@ const recipientsCommand = (bot) => {
 const sendsCommand = (bot) => new Command("sends")
     .description("what this bot sent, edited and deleted from this machine — ids and outcomes, never text")
     .summary("what this bot sent, edited and deleted from here — never the text")
-    .addCommand(annotate(new Command("list"), { effects: LOCAL_READ, examples: botExamples(bot, "sends list") })
+    .addCommand(withQuery(annotate(new Command("list"), { effects: LOCAL_READ, examples: botExamples(bot, "sends list") }), SENDS_QUERY)
     .description("every send, edit and delete this bot made from this machine, with its outcome")
-    .action(async function () {
+    .action(async function (words) {
+    const filter = sendFilter(words, "bot sends list");
     const context = botContext(this, bot);
-    await context.run(async () => renderAnswer(this, context, wholeList("bot sends list", context.journal().entries().map(snakeKeys))));
+    await context.run(async () => renderAnswer(this, context, wholeList("bot sends list", context.journal().entries(filter).map(snakeKeys))));
 }));
 const chatsCommand = (bot) => {
     const command = new Command("chats")
         .description(`the chats this bot is in — ${bot.name ?? "the messenger"} gives a bot no list of them, so \`list\` shows the ones it has seen`)
         .summary("the chats this bot is in, and what it does there");
-    annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "chats list") })
+    withQuery(annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "chats list") }), BOT_CHATS_QUERY)
         .description(`chats this bot has seen on this machine — not a complete list from ${bot.name ?? "the messenger"}`)
-        .action(async function () {
+        .action(async function (words) {
+        const filter = botChatFilter(words);
         const context = botContext(this, bot);
-        await context.run(async () => renderAnswer(this, context, wholeList("bot chats list", context.registry.list().map(snakeKeys))));
+        await context.run(async () => renderAnswer(this, context, wholeList("bot chats list", context.registry.list(filter).map(snakeKeys))));
     });
     annotate(command.command("show"), { effects: REMOTE_READ, examples: botExamples(bot, "chats show Team") })
         .description(`one chat from ${bot.name ?? "the messenger"}, and remember it`)

package/dist/cli/bot/list-queries.d.ts

@@ -0,0 +1,27 @@
+import { type QueryRegistry } from "@wirecat/cli-base/query";
+import { type QueryWords } from "../list-query.js";
+import type { SeenChat } from "./registry.js";
+export declare const BOT_PROFILES_QUERY: QueryRegistry;
+export declare const botProfileName: (words: QueryWords) => string | undefined;
+export declare const BOT_CHATS_QUERY: QueryRegistry;
+export declare const botChatFilter: (words: QueryWords) => Partial<Pick<SeenChat, "id" | "title" | "kind">>;
+export declare const BOT_MESSAGES_QUERY: QueryRegistry;
+export declare const botMessageWindow: (words: QueryWords) => {
+    window: {
+        before?: string | undefined;
+        since?: string | undefined;
+        threadId?: string | undefined;
+        outgoing?: boolean | undefined;
+        starred?: boolean | undefined;
+    };
+    meta: {
+        timezone: string;
+        window: {
+            since?: string;
+            until?: string;
+        };
+    } | undefined;
+};
+export declare const BOT_ADMINS_QUERY: QueryRegistry;
+export declare const BOT_MENU_QUERY: QueryRegistry;
+export declare const BOT_WEBHOOKS_QUERY: QueryRegistry;

package/dist/cli/bot/list-queries.js

@@ -0,0 +1,83 @@
+import { queryError, queryFieldsOf } from "@wirecat/cli-base/query";
+import { botAdmin, botMenuEntry, botProfile, botSeenChat, botWebhook, message } from "../../entities/index.js";
+import { listQuery, nativeTerms, queryTerms, timeBounds, typedQuery, unfilteredQuery, } from "../list-query.js";
+const termsOnly = (registry) => ({
+    ...registry,
+    fields: registry.fields.map((field) => field.native
+        ? {
+            ...field,
+            operators: field.operators.filter((operator) => operator === "term" || operator === "phrase"),
+        }
+        : field),
+});
+export const BOT_PROFILES_QUERY = termsOnly({
+    entity: "bot_profile",
+    backend: "native",
+    fields: queryFieldsOf(botProfile, { native: ["name"], examples: { name: "name:sales" } }),
+});
+export const botProfileName = (words) => queryTerms(words, BOT_PROFILES_QUERY, "bot list").get("name");
+export const BOT_CHATS_QUERY = termsOnly({
+    entity: "bot_seen_chat",
+    backend: "native",
+    fields: queryFieldsOf(botSeenChat, {
+        native: ["id", "title", "kind"],
+        examples: { id: "id:7", title: 'title:"Book club"', kind: "kind:group" },
+    }),
+});
+export const botChatFilter = (words) => {
+    const terms = queryTerms(words, BOT_CHATS_QUERY, "bot chats list");
+    const id = terms.get("id"), title = terms.get("title");
+    const kind = botSeenChat.entries.kind.wrapped.options.find((value) => value === terms.get("kind"));
+    return {
+        ...(id === undefined ? {} : { id }),
+        ...(title === undefined ? {} : { title }),
+        ...(kind === undefined ? {} : { kind }),
+    };
+};
+export const BOT_MESSAGES_QUERY = {
+    entity: "message",
+    backend: "native",
+    fields: queryFieldsOf(message, {
+        native: ["id", "timestamp", "thread_id", "outgoing", "starred"],
+        examples: {
+            id: "id<42",
+            timestamp: "timestamp>2026-10-01",
+            thread_id: "thread_id:12",
+            outgoing: "outgoing:false",
+            starred: "starred:true",
+        },
+    }).map((field) => {
+        if (field.name === "id" || field.name === "timestamp")
+            return { ...field, operators: ["range"] };
+        return field.native ? { ...field, operators: ["term"] } : field;
+    }),
+};
+export const botMessageWindow = (words) => {
+    const command = "bot messages list";
+    const terms = nativeTerms(listQuery(typedQuery(words), BOT_MESSAGES_QUERY, command), command);
+    const id = terms.get("id");
+    if (id && (id.value !== "*" || !id.upper || id.upper === "*" || id.upper_inclusive !== false))
+        queryError("query.unsupported-operator", id.span, "id takes an exclusive upper bound here: id<42", { command });
+    const timestamp = terms.get("timestamp");
+    const bounds = timeBounds(timestamp);
+    if (timestamp && (bounds.since === undefined || bounds.until !== undefined))
+        queryError("query.unsupported-operator", timestamp.span, "timestamp takes a lower bound here: timestamp>7d", {
+            command,
+        });
+    const topic = terms.get("thread_id")?.value;
+    const outgoing = terms.get("outgoing")?.value.toLowerCase();
+    const starred = terms.get("starred")?.value.toLowerCase();
+    return {
+        window: {
+            ...(id?.upper === undefined ? {} : { before: id.upper }),
+            ...(bounds.since === undefined ? {} : { since: new Date(bounds.since).toISOString() }),
+            ...(topic === undefined ? {} : { threadId: topic }),
+            ...(outgoing === undefined ? {} : { outgoing: outgoing === "true" }),
+            ...(starred === undefined ? {} : { starred: starred === "true" }),
+        },
+        meta: bounds.meta,
+    };
+};
+export const BOT_ADMINS_QUERY = unfilteredQuery("bot_admin", botAdmin);
+export const BOT_MENU_QUERY = unfilteredQuery("bot_menu_entry", botMenuEntry);
+export const BOT_WEBHOOKS_QUERY = unfilteredQuery("bot_webhook", botWebhook);

package/dist/cli/bot/messages.js

@@ -9,12 +9,14 @@ import { readAttachments } from "../../sends/upload.js";
 import { environmentOf } from "../context.js";
 import { ownerOnlyOption, REMOTE_READ, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { typedQuery, withQuery } from "../list-query.js";
 import { wholeList } from "../messenger/chat-answers.js";
 import { messageItem } from "../messenger/message-items.js";
 import { readAll } from "../messenger/stdin.js";
 import { positiveCount } from "../paging.js";
 import { botContext } from "./context.js";
 import { botExamples } from "./examples.js";
+import { BOT_MESSAGES_QUERY, botMessageWindow } from "./list-queries.js";
 /** The adapter's `method`, or a refusal naming what this messenger's bot cannot do. */
 export const botCan = (adapter, method, bot, what) => {
     const found = adapter[method];
@@ -32,10 +34,10 @@ export const botIdOf = async (context, adapter) => {
     context.registry.rememberBot(id);
     return id;
 };
-const show = (command, context, bot, botId, messages, one = false) => {
+const show = (command, context, bot, botId, messages, one = false, meta) => {
     const reader = context.copy.accountOf(botId);
     const items = messages.map((message) => messageItem(message, reader));
-    renderAnswer(command, context, one && items[0] ? itemOf(items[0]) : wholeList("bot messages list", items), () => renderMessages(messages, {
+    renderAnswer(command, context, one && items[0] ? itemOf(items[0]) : { ...wholeList("bot messages list", items), ...(meta ? { meta } : {}) }, () => renderMessages(messages, {
         color: context.color,
         verbosity: context.settings.detail,
         senderColors: context.settings.senderColors,
@@ -124,33 +126,37 @@ const sendCommand = (bot) => annotate(new Command("send"), {
         renderAnswer(this, context, written(context, botId, { operationId }, message));
     });
 });
-const listCommand = (bot) => annotate(new Command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "messages list Team --limit 20") })
+const listCommand = (bot) => withQuery(annotate(new Command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "messages list Team --limit 20") })
     .description(`the latest messages in a chat; where ${bot.name ?? "the messenger"} gives a bot no history, and with --offline, ` +
     "the ones this bot has seen on this machine")
     .summary("the latest messages in a chat")
-    .argument("<chat>", "a chat id, user:<id> for a person, or the title of a chat this bot has seen")
+    .argument("<chat>", "a chat id, user:<id> for a person, or the title of a chat this bot has seen"), BOT_MESSAGES_QUERY)
+    .addHelpText("after", "\nQueries filter the stored copy before limiting results; add --offline. The Bot API does not accept these filters.")
     .option("--limit <n>", "how many, the newest", positiveCount("--limit"))
-    .action(async function (chat) {
+    .action(async function (chat, words) {
+    const narrowed = botMessageWindow(words);
     const context = botContext(this, bot);
+    if (typedQuery(words).trim() && !context.settings.offline)
+        throw new CliError("validation_error", "bot message queries filter the local copy; add --offline");
     const ref = context.chatRef(chat);
     const limit = this.opts().limit ?? context.settings.limit;
     await context.run(async (events) => {
         const fromCopy = async (botId) => {
-            const page = await context.copy.read((store) => store.messages.messages(context.copy.accountOf(botId), ref, { limit }));
+            const page = await context.copy.read((store) => store.messages.messages(context.copy.accountOf(botId), ref, { limit, ...narrowed.window }));
             return page.items;
         };
         if (context.settings.offline) {
             const botId = context.registry.botId();
             if (!botId)
                 throw nothingKept(context);
-            show(this, context, bot, botId, await fromCopy(botId));
+            show(this, context, bot, botId, await fromCopy(botId), false, narrowed.meta);
             return;
         }
         const adapter = await context.authenticated({ events });
         const botId = await botIdOf(context, adapter);
         if (!adapter.history) {
             context.renderer.note(`${bot.name ?? "the messenger"} gives a bot no history: these are the messages it kept`);
-            show(this, context, bot, botId, await fromCopy(botId));
+            show(this, context, bot, botId, await fromCopy(botId), false, narrowed.meta);
             return;
         }
         const messages = await adapter.history(ref, { limit });

package/dist/cli/bot/registry.d.ts

@@ -24,7 +24,7 @@ export declare const botFiles: (app: AppIdentity, profile: string, env?: NodeJS.
 export declare class ChatRegistry {
     #private;
     constructor(app: AppIdentity, profile: string, env?: NodeJS.ProcessEnv);
-    list(): SeenChat[];
+    list(filter?: Partial<Pick<SeenChat, "id" | "title" | "kind">>): SeenChat[];
     /** The bot's own user id, once any command has learned it — the key its messages are stored under. */
     botId(): string | undefined;
     rememberBot(id: string): void;

package/dist/cli/bot/registry.js

@@ -26,9 +26,11 @@ export class ChatRegistry {
     constructor(app, profile, env = process.env) {
         this.#path = botFiles(app, profile, env).registry;
     }
-    list() {
+    list(filter = {}) {
         const { chats } = this.#read();
-        return Array.isArray(chats) ? chats : [];
+        return (Array.isArray(chats) ? chats : []).filter((chat) => (filter.id === undefined || chat.id === filter.id) &&
+            (filter.kind === undefined || chat.kind === filter.kind) &&
+            (filter.title === undefined || chat.title?.toLocaleLowerCase() === filter.title?.toLocaleLowerCase()));
     }
     /** The bot's own user id, once any command has learned it — the key its messages are stored under. */
     botId() {

package/dist/cli/bot/setup.js

@@ -5,9 +5,11 @@ import { guardedWrite } from "../../sends/guarded.js";
 import { newOperationId } from "../../sends/send-id.js";
 import { REMOTE_READ, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { listQuery, typedQuery, withQuery } from "../list-query.js";
 import { wholeList } from "../messenger/chat-answers.js";
 import { botContext, online } from "./context.js";
 import { botExamples } from "./examples.js";
+import { BOT_MENU_QUERY, BOT_WEBHOOKS_QUERY } from "./list-queries.js";
 import { botCan } from "./messages.js";
 import { botFiles } from "./registry.js";
 import { PressLog } from "./updates.js";
@@ -31,9 +33,10 @@ const botWrite = (context, key, write) => guardedWrite(context.guard(), { operat
 /** `bot commands`: the menu people see when they type `/`. */
 export const botMenuCommand = (bot) => {
     const command = new Command("commands").description("the bot's command menu — what people see after /");
-    annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "commands list") })
+    withQuery(annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "commands list") }), BOT_MENU_QUERY)
         .description("the commands in the menu now")
-        .action(async function () {
+        .action(async function (words) {
+        listQuery(typedQuery(words), BOT_MENU_QUERY, "bot commands list");
         const context = online(botContext(this, bot), this);
         await context.run(async (events) => {
             const adapter = await context.authenticated({ events });
@@ -111,9 +114,10 @@ export const botWebhooksCommand = (bot) => {
     const command = new Command("webhooks")
         .description("where the messenger pushes this bot's updates — while one is set, `bot watch` gets nothing")
         .summary("where the messenger pushes this bot's updates");
-    annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "webhooks list") })
+    withQuery(annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "webhooks list") }), BOT_WEBHOOKS_QUERY)
         .description("the webhooks this bot has")
-        .action(async function () {
+        .action(async function (words) {
+        listQuery(typedQuery(words), BOT_WEBHOOKS_QUERY, "bot webhooks list");
         const context = online(botContext(this, bot), this);
         await context.run(async (events) => {
             const adapter = await context.authenticated({ events });

package/dist/cli/command-availability.d.ts

@@ -0,0 +1,14 @@
+import type { CommandInfo } from "@wirecat/cli-base/commands";
+import { type Level, type PermissionKey } from "../sends/permissions.js";
+export type AvailabilityCommand = Pick<CommandInfo, "path" | "effects" | "lifetime" | "reaches">;
+export interface DiscoveredCommand extends CommandInfo {
+    availability?: CommandAvailability;
+    commands: readonly DiscoveredCommand[];
+}
+export interface CommandAvailability {
+    available: boolean;
+    reason?: string;
+    permission?: string;
+}
+/** Discovery and execution use the same permission decision. */
+export declare const commandAvailability: (info: AvailabilityCommand, levels: Readonly<Record<PermissionKey, Level>>, keyOf?: (path: readonly string[]) => PermissionKey | null | undefined, authority?: (path: readonly string[]) => boolean, readOnly?: boolean, mcp?: boolean) => CommandAvailability;

package/dist/cli/command-availability.js

@@ -0,0 +1,25 @@
+import { writes } from "@wirecat/cli-base/standards";
+import { AUTHORITY_KEY, authorityAllowed, BOT_API_KEY, botApiAllowed, isBotApi, keyForCommand, levelFor, readKeysForCommand, } from "../sends/permissions.js";
+import { changesMessenger } from "./effects.js";
+/** Discovery and execution use the same permission decision. */
+export const commandAvailability = (info, levels, keyOf, authority, readOnly = false, mcp = true) => {
+    const blocked = (reason, permission) => ({
+        available: false,
+        reason,
+        ...(permission ? { permission } : {}),
+    });
+    if (readOnly && (changesMessenger(info) || authority?.(info.path)))
+        return blocked("the read-only lock blocks this change");
+    if (mcp && authority?.(info.path) && !authorityAllowed(levels))
+        return blocked(`the profile keeps ${AUTHORITY_KEY} off`, AUTHORITY_KEY);
+    if (mcp && isBotApi(info.path) && !botApiAllowed(levels))
+        return blocked(`the profile requires ${BOT_API_KEY}: allow`, BOT_API_KEY);
+    const key = keyOf?.(info.path) ?? keyForCommand(info.path);
+    const level = key ? levelFor(levels, key).level : "allow";
+    if (level === "deny")
+        return blocked(`the profile denies ${key}`, key ?? undefined);
+    if (level === "readonly" && writes(info.effects))
+        return blocked(`${key} is readonly in this profile`, key ?? undefined);
+    const denied = readKeysForCommand(info.path).find((read) => levelFor(levels, read).level === "deny");
+    return denied ? blocked(`the profile denies ${denied}`, denied) : { available: true };
+};

package/dist/cli/commands-command.d.ts

@@ -7,6 +7,6 @@ import type { AppIdentity } from "../ports/app.js";
 export declare const CONTRACT = 3;
 /**
  * The discovery surface an agent reads instead of `--help`. It opens no store, no session and no
- * settings file: which commands exist does not depend on whether this machine has logged in.
+ * settings file without a named profile. A named profile adds availability without hiding commands.
  */
 export declare const commandsCommand: (app: AppIdentity) => Command;

package/dist/cli/commands-command.js

@@ -1,8 +1,8 @@
 import { CliError, EXIT_CODES, GENERIC_FAILURE } from "@wirecat/cli-base";
-import { annotate, describeOptions, describeProgram } from "@wirecat/cli-base/commands";
+import { annotate, describeOptions, describeProgram, metaOf } from "@wirecat/cli-base/commands";
 import { CRASH_CODE } from "@wirecat/cli-base/standards";
 import { Command } from "commander";
-import { commandContract, findCommand } from "./command-contract.js";
+import { commandContract, commandPathOf, findCommand } from "./command-contract.js";
 import { environmentOf, outputFor } from "./context.js";
 import { NO_EFFECTS } from "./effects.js";
 import { renderDocument } from "./envelope.js";
@@ -15,7 +15,7 @@ import { rootOf } from "./profile.js";
 export const CONTRACT = 3;
 /**
  * The discovery surface an agent reads instead of `--help`. It opens no store, no session and no
- * settings file: which commands exist does not depend on whether this machine has logged in.
+ * settings file without a named profile. A named profile adds availability without hiding commands.
  */
 export const commandsCommand = (app) => {
     const command = annotate(new Command("commands"), { effects: NO_EFFECTS })
@@ -30,7 +30,12 @@ export const commandsCommand = (app) => {
         .action(function (path) {
         const root = rootOf(this);
         const output = outputFor(this);
-        const all = describeProgram(root);
+        const available = environmentOf(this).discoveryAvailability;
+        const annotateAvailability = (infos) => infos.map((info) => {
+            const availability = available?.(info);
+            return { ...info, ...(availability ? { availability } : {}), commands: annotateAvailability(info.commands) };
+        });
+        const all = annotateAvailability(describeProgram(root));
         const scoped = path.length > 0 ? scopeOf(root, all, path) : undefined;
         const commands = scoped ? [scoped.command] : all;
         const { json, jsonl } = this.optsWithGlobals();
@@ -62,6 +67,14 @@ export const commandsCommand = (app) => {
             version: app.version,
             contract: CONTRACT,
             ...commandContract(findCommand(rootOf(this), path)),
+            ...(() => {
+                const found = findCommand(rootOf(this), path);
+                const availability = environmentOf(this).discoveryAvailability?.({
+                    ...metaOf(found),
+                    path: commandPathOf(found),
+                });
+                return availability ? { availability } : {};
+            })(),
         });
     }));
     return command;

package/dist/cli/context.d.ts

@@ -11,6 +11,7 @@ import { type Closeable } from "./deadline.js";
 import type { GlobalFlags, ResolveOptions, Settings } from "./settings.js";
 /** What every CLI's commands write to, when it is not the real terminal. A CLI adds its own fields. */
 export interface BaseEnvironment {
+    discoveryAvailability?: (command: import("./command-availability.js").AvailabilityCommand) => import("./command-availability.js").CommandAvailability | undefined;
     streams?: Streams;
     /** Whether a person is looking. Defaults to whether stdout is a terminal. */
     tty?: boolean;

package/dist/cli/effects.d.ts

@@ -14,7 +14,7 @@ export declare const NO_EFFECTS: Effects;
 /**
  * Marks a local write that changes what a later run may do: a schedule, a setting, the recipient list, an
  * auto-reply, an agent's setup. `<PREFIX>_READ_ONLY` refuses it, or an agent under the lock could hand an
- * unlocked run the send it may not make itself (SEC-47). For the same reason an MCP server offers it only where the
+ * unlocked run the send it may not make itself (SEC-47). For the same reason an MCP server permits execution only where the
  * profile allows `mcp.authority`, which is off until the owner turns it on (NEED-1662).
  * `unless` names a flag that makes the run only look (`upgrade --check`), which the lock lets through.
  */

package/dist/cli/effects.js

@@ -16,7 +16,7 @@ const AUTHORITY = new WeakMap();
 /**
  * Marks a local write that changes what a later run may do: a schedule, a setting, the recipient list, an
  * auto-reply, an agent's setup. `<PREFIX>_READ_ONLY` refuses it, or an agent under the lock could hand an
- * unlocked run the send it may not make itself (SEC-47). For the same reason an MCP server offers it only where the
+ * unlocked run the send it may not make itself (SEC-47). For the same reason an MCP server permits execution only where the
  * profile allows `mcp.authority`, which is off until the owner turns it on (NEED-1662).
  * `unless` names a flag that makes the run only look (`upgrade --check`), which the lock lets through.
  */

package/dist/cli/help/command-help.js

@@ -1,6 +1,7 @@
 import { metaOf } from "@wirecat/cli-base/commands";
 import { writes } from "@wirecat/cli-base/standards";
 import { commandPathOf, outputOf } from "../command-contract.js";
+import { environmentOf } from "../context.js";
 import { PROFILE_FREE } from "../profile.js";
 import { commandAt } from "../steps.js";
 import { short } from "./commands-text.js";
@@ -195,7 +196,23 @@ const LABEL = 15;
 export const commandHelpText = (command) => {
     const { returns, next, examples } = commandHelp(command);
     const rows = (label, values) => values.map((value, at) => `${(at === 0 ? label : "").padEnd(LABEL)}${value}`);
-    return ["", ...rows("Returns:", [returns]), ...rows("Next usually:", next), ...rows("Example:", examples), ""].join("\n");
+    const availability = environmentOf(command).discoveryAvailability?.({
+        ...metaOf(command),
+        path: commandPathOf(command),
+    });
+    const access = availability
+        ? rows("Availability:", [
+            availability.available ? "available for this profile" : `unavailable — ${availability.reason}`,
+        ])
+        : [];
+    return [
+        "",
+        ...access,
+        ...rows("Returns:", [returns]),
+        ...rows("Next usually:", next),
+        ...rows("Example:", examples),
+        "",
+    ].join("\n");
 };
 /** The same, as Markdown lines for `docs/commands.md`: hand it to cli-base's `commandsPage` per command. */
 export const commandHelpMarkdown = (root, path) => {

package/dist/cli/help/commands-text.d.ts

@@ -1,5 +1,5 @@
-import type { CommandInfo } from "@wirecat/cli-base/commands";
 import type { Command } from "commander";
+import type { DiscoveredCommand as CommandInfo } from "../command-availability.js";
 /** The first clause that fits: a line per command is the point, the whole text is in `--help`. */
 export declare const short: (text: string) => string;
 /**

package/dist/cli/help/commands-text.js

@@ -33,10 +33,11 @@ export const commandsText = (root, commands, scope) => {
         if (infos.length === 0)
             continue;
         lines.push("", SECTIONS[section]);
-        for (const { usage, summary, description, effects } of infos) {
+        for (const { usage, summary, description, effects, availability } of infos) {
             const what = short(summary ?? description);
             const mark = effects === undefined || writes(effects) ? " (writes)" : "";
-            lines.push(`  ${usage.padEnd(COLUMN)}  ${what}${mark}`.trimEnd());
+            const access = availability?.available === false ? ` [unavailable: ${availability.reason}]` : "";
+            lines.push(`  ${usage.padEnd(COLUMN)}  ${what}${mark}${access}`.trimEnd());
         }
     }
     return `${lines.join("\n")}\n`;

package/dist/cli/index.d.ts

@@ -1,5 +1,6 @@
 export { AI_ENTRIES, AI_SETTING_KEYS, type AISettings, resolveAISettings } from "../analysis/settings.js";
 export { parseDuration } from "../domain/duration.js";
+export { botTemplate } from "../entities/list-results.js";
 export { syncProgress } from "../entities/store-records.js";
 export { isCliFailure, isCommanderFailure } from "../errors/failures.js";
 export { type AppErrors, failureContext } from "../errors/reasons.js";
@@ -49,6 +50,7 @@ export { BOT_ACTIONS, type BotAction, type BotAdapter, type BotCallbacks, type B
 export { botFiles, botsDirectory, ChatRegistry, registryProfiles, type SeenChat } from "./bot/registry.js";
 export { BotTokenStore, type BotTokenStoreOptions } from "./bot/token.js";
 export { PressLog, UpdatesCursor } from "./bot/updates.js";
+export type { CommandAvailability, DiscoveredCommand } from "./command-availability.js";
 export { commandContract, type JsonSchema, SCHEMA_DIALECT } from "./command-contract.js";
 export { CONTRACT, commandsCommand } from "./commands-command.js";
 export { configCommand, refuseUnknownKey } from "./config-command.js";

package/dist/cli/index.js

@@ -1,5 +1,6 @@
 export { AI_ENTRIES, AI_SETTING_KEYS, resolveAISettings } from "../analysis/settings.js";
 export { parseDuration } from "../domain/duration.js";
+export { botTemplate } from "../entities/list-results.js";
 export { syncProgress } from "../entities/store-records.js";
 export { isCliFailure, isCommanderFailure } from "../errors/failures.js";
 export { failureContext } from "../errors/reasons.js";