@cmdop/bot 2026.2.26 → 2026.2.28

package/dist/index.d.cts

@@ -1,9 +1,46 @@
 import { z } from 'zod/v4';
 import { CMDOPClient } from '@cmdop/node';
+import { ConsolaInstance } from 'consola';
 import { WebClient } from '@slack/web-api';
 import { InlineKeyboardButton } from 'grammy/types';
 import { RESTPostAPIChatInputApplicationCommandsJSONBody } from 'discord.js';
 
+declare const PermissionLevelSchema: z.ZodEnum<{
+    NONE: "NONE";
+    READ: "READ";
+    EXECUTE: "EXECUTE";
+    FILES: "FILES";
+    ADMIN: "ADMIN";
+}>;
+type PermissionLevel = z.infer<typeof PermissionLevelSchema>;
+declare const PERMISSION_ORDER: Record<PermissionLevel, number>;
+declare const UserIdentitySchema: z.ZodObject<{
+    platform: z.ZodString;
+    platformId: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    displayName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type UserIdentity = z.infer<typeof UserIdentitySchema>;
+declare const BotUserSchema: z.ZodObject<{
+    id: z.ZodString;
+    identity: z.ZodObject<{
+        platform: z.ZodString;
+        platformId: z.ZodString;
+        username: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    permission: z.ZodEnum<{
+        NONE: "NONE";
+        READ: "READ";
+        EXECUTE: "EXECUTE";
+        FILES: "FILES";
+        ADMIN: "ADMIN";
+    }>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    lastSeenAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+type BotUser = z.infer<typeof BotUserSchema>;
+
 declare const AttachmentSchema: z.ZodObject<{
     type: z.ZodEnum<{
         photo: "photo";
@@ -71,42 +108,6 @@ declare const OutgoingMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "type">;
 type OutgoingMessage = z.infer<typeof OutgoingMessageSchema>;
 
-declare const PermissionLevelSchema: z.ZodEnum<{
-    NONE: "NONE";
-    READ: "READ";
-    EXECUTE: "EXECUTE";
-    FILES: "FILES";
-    ADMIN: "ADMIN";
-}>;
-type PermissionLevel = z.infer<typeof PermissionLevelSchema>;
-declare const PERMISSION_ORDER: Record<PermissionLevel, number>;
-declare const UserIdentitySchema: z.ZodObject<{
-    platform: z.ZodString;
-    platformId: z.ZodString;
-    username: z.ZodOptional<z.ZodString>;
-    displayName: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-type UserIdentity = z.infer<typeof UserIdentitySchema>;
-declare const BotUserSchema: z.ZodObject<{
-    id: z.ZodString;
-    identity: z.ZodObject<{
-        platform: z.ZodString;
-        platformId: z.ZodString;
-        username: z.ZodOptional<z.ZodString>;
-        displayName: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    permission: z.ZodEnum<{
-        NONE: "NONE";
-        READ: "READ";
-        EXECUTE: "EXECUTE";
-        FILES: "FILES";
-        ADMIN: "ADMIN";
-    }>;
-    createdAt: z.ZodCoercedDate<unknown>;
-    lastSeenAt: z.ZodCoercedDate<unknown>;
-}, z.core.$strip>;
-type BotUser = z.infer<typeof BotUserSchema>;
-
 declare const ParsedCommandSchema: z.ZodObject<{
     name: z.ZodString;
     args: z.ZodArray<z.ZodString>;
@@ -346,6 +347,7 @@ declare abstract class BaseChannel implements ChannelProtocol {
     abstract onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
     /**
      * Process an incoming message: parse command → check permission → dispatch → send result.
+     * Plain text (non-command) is routed to the agent handler automatically.
      * Channels call this from their platform event handler.
      */
     protected processMessage(msg: IncomingMessage): Promise<void>;
@@ -450,9 +452,36 @@ declare const BotSettingsSchema: z.ZodObject<{
 type BotSettings = z.infer<typeof BotSettingsSchema>;
 declare function loadSettings(env?: NodeJS.ProcessEnv): BotSettings;
 
+interface DemoChannelOptions {
+    /** Called for every outgoing message (default: JSON to stdout) */
+    onOutput?: (text: string, message: OutgoingMessage) => void;
+}
+/**
+ * DemoChannel — stdio-based channel for local testing and CLI usage.
+ * No real platform; messages are injected programmatically via injectMessage().
+ */
+declare class DemoChannel extends BaseChannel {
+    private messageHandlers;
+    private readonly onOutput;
+    constructor(permissions: PermissionManager, dispatcher: MessageDispatcher, logger: LoggerProtocol, options?: DemoChannelOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(_userId: string, message: OutgoingMessage): Promise<void>;
+    onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
+    /**
+     * Inject a message as if it came from a real platform user.
+     * Primarily used in tests and CLI demos.
+     */
+    injectMessage(input: {
+        userId?: string;
+        text: string;
+    }): Promise<void>;
+}
+
 type TelegramOptions = TelegramChannelOptions;
 type DiscordOptions = DiscordChannelOptions;
 type SlackOptions = SlackChannelOptions;
+
 interface HubOptions {
     /** CMDOP cloud API key. If omitted, uses local IPC connection. */
     apiKey?: string;
@@ -464,6 +493,12 @@ interface HubOptions {
     permissionStore?: PermissionStoreProtocol;
     /** Admin user IDs (always have ADMIN permission). */
     adminUsers?: string[];
+    /**
+     * Default permission level for new/unknown users.
+     * Set to 'EXECUTE' to allow all users to run commands without explicit grants.
+     * Default: 'NONE'
+     */
+    defaultPermission?: PermissionLevel;
     /** Logger instance. Default: stderr JSON logger at info level. */
     logger?: LoggerProtocol;
     /** Bot settings. Default: loaded from environment variables. */
@@ -509,6 +544,11 @@ declare class IntegrationHub {
      * Requires `@slack/bolt` and `@slack/web-api` to be installed.
      */
     addSlack(options: SlackOptions): Promise<this>;
+    /**
+     * Create and register a DemoChannel for CLI testing.
+     * No external dependencies — messages are injected via the returned channel's `injectMessage()`.
+     */
+    addDemo(options?: DemoChannelOptions): DemoChannel;
     registerHandler(handler: HandlerProtocol): this;
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -554,7 +594,13 @@ declare abstract class BaseHandler implements HandlerProtocol {
 }
 
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-declare function createLogger(level?: LogLevel): LoggerProtocol;
+/**
+ * Create a bot logger backed by consola.
+ * Pretty output in dev, structured JSON when CMDOP_LOG_JSON=1.
+ */
+declare function createLogger(level?: LogLevel): LoggerProtocol & {
+    consola: ConsolaInstance;
+};
 
 declare const UserSessionSchema: z.ZodObject<{
     userId: z.ZodString;
@@ -704,32 +750,6 @@ declare class HelpHandler extends BaseHandler {
     handle(_ctx: CommandContext): Promise<HandlerResult>;
 }
 
-interface DemoChannelOptions {
-    /** Called for every outgoing message (default: JSON to stdout) */
-    onOutput?: (text: string, message: OutgoingMessage) => void;
-}
-/**
- * DemoChannel — stdio-based channel for local testing and CLI usage.
- * No real platform; messages are injected programmatically via injectMessage().
- */
-declare class DemoChannel extends BaseChannel {
-    private messageHandlers;
-    private readonly onOutput;
-    constructor(permissions: PermissionManager, dispatcher: MessageDispatcher, logger: LoggerProtocol, options?: DemoChannelOptions);
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    send(_userId: string, message: OutgoingMessage): Promise<void>;
-    onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
-    /**
-     * Inject a message as if it came from a real platform user.
-     * Primarily used in tests and CLI demos.
-     */
-    injectMessage(input: {
-        userId?: string;
-        text: string;
-    }): Promise<void>;
-}
-
 declare class TelegramFormatter implements FormatterProtocol {
     /**
      * Escape plain text for safe inclusion in MarkdownV2 messages.
@@ -748,6 +768,23 @@ declare class TelegramFormatter implements FormatterProtocol {
      * Format a file listing entry line.
      */
     formatFileEntry(name: string, isDir: boolean, size?: number): string;
+    /**
+     * Escape HTML special chars, then convert basic markdown to HTML tags.
+     * Handles: **bold**, `code`, ```code blocks```, _italic_
+     */
+    formatTextHtml(text: string): string;
+    /**
+     * Format code block as HTML <pre>.
+     */
+    formatCodeHtml(code: string, language?: string): string;
+    /**
+     * Format error message as HTML.
+     */
+    formatErrorHtml(message: string): string;
+    /**
+     * Format file entry as HTML.
+     */
+    formatFileEntryHtml(name: string, isDir: boolean, size?: number): string;
     private escapeInline;
 }
 

package/dist/index.d.ts

@@ -1,9 +1,46 @@
 import { z } from 'zod/v4';
 import { CMDOPClient } from '@cmdop/node';
+import { ConsolaInstance } from 'consola';
 import { WebClient } from '@slack/web-api';
 import { InlineKeyboardButton } from 'grammy/types';
 import { RESTPostAPIChatInputApplicationCommandsJSONBody } from 'discord.js';
 
+declare const PermissionLevelSchema: z.ZodEnum<{
+    NONE: "NONE";
+    READ: "READ";
+    EXECUTE: "EXECUTE";
+    FILES: "FILES";
+    ADMIN: "ADMIN";
+}>;
+type PermissionLevel = z.infer<typeof PermissionLevelSchema>;
+declare const PERMISSION_ORDER: Record<PermissionLevel, number>;
+declare const UserIdentitySchema: z.ZodObject<{
+    platform: z.ZodString;
+    platformId: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    displayName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type UserIdentity = z.infer<typeof UserIdentitySchema>;
+declare const BotUserSchema: z.ZodObject<{
+    id: z.ZodString;
+    identity: z.ZodObject<{
+        platform: z.ZodString;
+        platformId: z.ZodString;
+        username: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    permission: z.ZodEnum<{
+        NONE: "NONE";
+        READ: "READ";
+        EXECUTE: "EXECUTE";
+        FILES: "FILES";
+        ADMIN: "ADMIN";
+    }>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    lastSeenAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+type BotUser = z.infer<typeof BotUserSchema>;
+
 declare const AttachmentSchema: z.ZodObject<{
     type: z.ZodEnum<{
         photo: "photo";
@@ -71,42 +108,6 @@ declare const OutgoingMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "type">;
 type OutgoingMessage = z.infer<typeof OutgoingMessageSchema>;
 
-declare const PermissionLevelSchema: z.ZodEnum<{
-    NONE: "NONE";
-    READ: "READ";
-    EXECUTE: "EXECUTE";
-    FILES: "FILES";
-    ADMIN: "ADMIN";
-}>;
-type PermissionLevel = z.infer<typeof PermissionLevelSchema>;
-declare const PERMISSION_ORDER: Record<PermissionLevel, number>;
-declare const UserIdentitySchema: z.ZodObject<{
-    platform: z.ZodString;
-    platformId: z.ZodString;
-    username: z.ZodOptional<z.ZodString>;
-    displayName: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-type UserIdentity = z.infer<typeof UserIdentitySchema>;
-declare const BotUserSchema: z.ZodObject<{
-    id: z.ZodString;
-    identity: z.ZodObject<{
-        platform: z.ZodString;
-        platformId: z.ZodString;
-        username: z.ZodOptional<z.ZodString>;
-        displayName: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    permission: z.ZodEnum<{
-        NONE: "NONE";
-        READ: "READ";
-        EXECUTE: "EXECUTE";
-        FILES: "FILES";
-        ADMIN: "ADMIN";
-    }>;
-    createdAt: z.ZodCoercedDate<unknown>;
-    lastSeenAt: z.ZodCoercedDate<unknown>;
-}, z.core.$strip>;
-type BotUser = z.infer<typeof BotUserSchema>;
-
 declare const ParsedCommandSchema: z.ZodObject<{
     name: z.ZodString;
     args: z.ZodArray<z.ZodString>;
@@ -346,6 +347,7 @@ declare abstract class BaseChannel implements ChannelProtocol {
     abstract onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
     /**
      * Process an incoming message: parse command → check permission → dispatch → send result.
+     * Plain text (non-command) is routed to the agent handler automatically.
      * Channels call this from their platform event handler.
      */
     protected processMessage(msg: IncomingMessage): Promise<void>;
@@ -450,9 +452,36 @@ declare const BotSettingsSchema: z.ZodObject<{
 type BotSettings = z.infer<typeof BotSettingsSchema>;
 declare function loadSettings(env?: NodeJS.ProcessEnv): BotSettings;
 
+interface DemoChannelOptions {
+    /** Called for every outgoing message (default: JSON to stdout) */
+    onOutput?: (text: string, message: OutgoingMessage) => void;
+}
+/**
+ * DemoChannel — stdio-based channel for local testing and CLI usage.
+ * No real platform; messages are injected programmatically via injectMessage().
+ */
+declare class DemoChannel extends BaseChannel {
+    private messageHandlers;
+    private readonly onOutput;
+    constructor(permissions: PermissionManager, dispatcher: MessageDispatcher, logger: LoggerProtocol, options?: DemoChannelOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(_userId: string, message: OutgoingMessage): Promise<void>;
+    onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
+    /**
+     * Inject a message as if it came from a real platform user.
+     * Primarily used in tests and CLI demos.
+     */
+    injectMessage(input: {
+        userId?: string;
+        text: string;
+    }): Promise<void>;
+}
+
 type TelegramOptions = TelegramChannelOptions;
 type DiscordOptions = DiscordChannelOptions;
 type SlackOptions = SlackChannelOptions;
+
 interface HubOptions {
     /** CMDOP cloud API key. If omitted, uses local IPC connection. */
     apiKey?: string;
@@ -464,6 +493,12 @@ interface HubOptions {
     permissionStore?: PermissionStoreProtocol;
     /** Admin user IDs (always have ADMIN permission). */
     adminUsers?: string[];
+    /**
+     * Default permission level for new/unknown users.
+     * Set to 'EXECUTE' to allow all users to run commands without explicit grants.
+     * Default: 'NONE'
+     */
+    defaultPermission?: PermissionLevel;
     /** Logger instance. Default: stderr JSON logger at info level. */
     logger?: LoggerProtocol;
     /** Bot settings. Default: loaded from environment variables. */
@@ -509,6 +544,11 @@ declare class IntegrationHub {
      * Requires `@slack/bolt` and `@slack/web-api` to be installed.
      */
     addSlack(options: SlackOptions): Promise<this>;
+    /**
+     * Create and register a DemoChannel for CLI testing.
+     * No external dependencies — messages are injected via the returned channel's `injectMessage()`.
+     */
+    addDemo(options?: DemoChannelOptions): DemoChannel;
     registerHandler(handler: HandlerProtocol): this;
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -554,7 +594,13 @@ declare abstract class BaseHandler implements HandlerProtocol {
 }
 
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-declare function createLogger(level?: LogLevel): LoggerProtocol;
+/**
+ * Create a bot logger backed by consola.
+ * Pretty output in dev, structured JSON when CMDOP_LOG_JSON=1.
+ */
+declare function createLogger(level?: LogLevel): LoggerProtocol & {
+    consola: ConsolaInstance;
+};
 
 declare const UserSessionSchema: z.ZodObject<{
     userId: z.ZodString;
@@ -704,32 +750,6 @@ declare class HelpHandler extends BaseHandler {
     handle(_ctx: CommandContext): Promise<HandlerResult>;
 }
 
-interface DemoChannelOptions {
-    /** Called for every outgoing message (default: JSON to stdout) */
-    onOutput?: (text: string, message: OutgoingMessage) => void;
-}
-/**
- * DemoChannel — stdio-based channel for local testing and CLI usage.
- * No real platform; messages are injected programmatically via injectMessage().
- */
-declare class DemoChannel extends BaseChannel {
-    private messageHandlers;
-    private readonly onOutput;
-    constructor(permissions: PermissionManager, dispatcher: MessageDispatcher, logger: LoggerProtocol, options?: DemoChannelOptions);
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    send(_userId: string, message: OutgoingMessage): Promise<void>;
-    onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
-    /**
-     * Inject a message as if it came from a real platform user.
-     * Primarily used in tests and CLI demos.
-     */
-    injectMessage(input: {
-        userId?: string;
-        text: string;
-    }): Promise<void>;
-}
-
 declare class TelegramFormatter implements FormatterProtocol {
     /**
      * Escape plain text for safe inclusion in MarkdownV2 messages.
@@ -748,6 +768,23 @@ declare class TelegramFormatter implements FormatterProtocol {
      * Format a file listing entry line.
      */
     formatFileEntry(name: string, isDir: boolean, size?: number): string;
+    /**
+     * Escape HTML special chars, then convert basic markdown to HTML tags.
+     * Handles: **bold**, `code`, ```code blocks```, _italic_
+     */
+    formatTextHtml(text: string): string;
+    /**
+     * Format code block as HTML <pre>.
+     */
+    formatCodeHtml(code: string, language?: string): string;
+    /**
+     * Format error message as HTML.
+     */
+    formatErrorHtml(message: string): string;
+    /**
+     * Format file entry as HTML.
+     */
+    formatFileEntryHtml(name: string, isDir: boolean, size?: number): string;
     private escapeInline;
 }