ctb 1.1.0 → 1.3.0

package/src/bot.ts

@@ -18,17 +18,24 @@ import {
 	handleBookmarks,
 	handleCallback,
 	handleCd,
+	handleCompact,
+	handleCost,
 	handleDocument,
+	handleFile,
+	handleModel,
 	handleNew,
 	handlePhoto,
-	handlePreview,
+	handlePlan,
 	handleRestart,
 	handleResume,
 	handleRetry,
+	handleSkill,
 	handleStart,
 	handleStatus,
 	handleStop,
 	handleText,
+	handleThink,
+	handleUndo,
 	handleVoice,
 } from "./handlers";
 
@@ -61,12 +68,22 @@ bot.use(
 bot.command("start", handleStart);
 bot.command("new", handleNew);
 bot.command("stop", handleStop);
+bot.command("c", handleStop);
+bot.command("kill", handleStop);
+bot.command("dc", handleStop);
 bot.command("status", handleStatus);
 bot.command("resume", handleResume);
 bot.command("restart", handleRestart);
 bot.command("retry", handleRetry);
 bot.command("cd", handleCd);
-bot.command("preview", handlePreview);
+bot.command("skill", handleSkill);
+bot.command("file", handleFile);
+bot.command("model", handleModel);
+bot.command("cost", handleCost);
+bot.command("think", handleThink);
+bot.command("plan", handlePlan);
+bot.command("compact", handleCompact);
+bot.command("undo", handleUndo);
 bot.command("bookmarks", handleBookmarks);
 
 // ============== Message Handlers ==============
@@ -113,8 +130,15 @@ await bot.api.setMyCommands([
 	{ command: "resume", description: "Resume last session" },
 	{ command: "stop", description: "Interrupt current query" },
 	{ command: "status", description: "Check what Claude is doing" },
+	{ command: "model", description: "Switch model (sonnet/opus/haiku)" },
+	{ command: "cost", description: "Show token usage and cost" },
+	{ command: "think", description: "Force extended thinking" },
+	{ command: "plan", description: "Toggle planning mode" },
+	{ command: "compact", description: "Trigger context compaction" },
+	{ command: "undo", description: "Revert file changes" },
 	{ command: "cd", description: "Change working directory" },
-	{ command: "preview", description: "Download a file" },
+	{ command: "skill", description: "Invoke a Claude Code skill" },
+	{ command: "file", description: "Download a file" },
 	{ command: "bookmarks", description: "Manage directory bookmarks" },
 	{ command: "retry", description: "Retry last message" },
 	{ command: "restart", description: "Restart the bot" },

package/src/cli.ts

@@ -23,6 +23,7 @@ interface CliOptions {
 	dir?: string;
 	help?: boolean;
 	version?: boolean;
+	tut?: boolean;
 }
 
 function parseArgs(args: string[]): CliOptions {
@@ -33,6 +34,8 @@ function parseArgs(args: string[]): CliOptions {
 			options.help = true;
 		} else if (arg === "--version" || arg === "-v") {
 			options.version = true;
+		} else if (arg === "tut" || arg === "tutorial") {
+			options.tut = true;
 		} else if (arg.startsWith("--token=")) {
 			options.token = arg.slice(8);
 		} else if (arg.startsWith("--users=")) {
@@ -53,6 +56,7 @@ Run a Telegram bot that controls Claude Code in your project directory.
 
 USAGE:
   ctb [options]
+  ctb tut              Show setup tutorial
 
 OPTIONS:
   --help, -h       Show this help message
@@ -75,6 +79,91 @@ Multiple instances can run simultaneously in different directories.
 `);
 }
 
+function showTutorial(): void {
+	console.log(`
+╔══════════════════════════════════════════════════════════════════╗
+║                    CTB Setup Tutorial                            ║
+╚══════════════════════════════════════════════════════════════════╝
+
+Follow these steps to set up your Claude Telegram Bot:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 1: Create a Telegram Bot
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. Open Telegram and search for @BotFather
+2. Send /newbot
+3. Follow the prompts:
+   - Choose a name (e.g., "My Claude Bot")
+   - Choose a username (must end in "bot", e.g., "my_claude_bot")
+4. Copy the token that looks like:
+   1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 2: Get Your Telegram User ID
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. Open Telegram and search for @userinfobot
+2. Send any message to it
+3. It will reply with your user ID (a number like 123456789)
+4. Copy this number
+
+   Tip: Add multiple user IDs separated by commas for team access
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 3: Configure the Bot
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Option A: Interactive setup (easiest)
+  Just run: ctb
+  It will prompt you for the token and user IDs.
+
+Option B: Create a .env file
+  Create a file named .env in your project directory:
+
+  TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+  TELEGRAM_ALLOWED_USERS=123456789,987654321
+
+Option C: Use command-line arguments
+  ctb --token=YOUR_TOKEN --users=YOUR_USER_ID
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 4: Set Up Bot Commands (Optional)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. Go back to @BotFather
+2. Send /setcommands
+3. Select your bot
+4. Paste this command list:
+
+start - Show status and user ID
+new - Start a fresh session
+resume - Resume last session
+stop - Interrupt current query
+status - Check what Claude is doing
+undo - Revert file changes
+cd - Change working directory
+file - Download a file
+bookmarks - Manage directory bookmarks
+retry - Retry last message
+restart - Restart the bot
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 5: Start the Bot
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  cd ~/your-project
+  ctb
+
+The bot will start and show "Bot started: @your_bot_username"
+Open Telegram and message your bot to start using Claude!
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Need help? https://github.com/htlin/claude-telegram-bot
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`);
+}
+
 async function prompt(question: string): Promise<string> {
 	const rl = createInterface({
 		input: process.stdin,
@@ -226,6 +315,11 @@ async function main(): Promise<void> {
 		process.exit(0);
 	}
 
+	if (options.tut) {
+		showTutorial();
+		process.exit(0);
+	}
+
 	// Determine working directory
 	const workingDir = options.dir ? resolve(options.dir) : process.cwd();
 

package/src/errors.ts

@@ -0,0 +1,58 @@
+/**
+ * User-friendly error message formatting.
+ */
+
+interface ErrorPattern {
+	pattern: RegExp;
+	message: string;
+}
+
+const ERROR_PATTERNS: ErrorPattern[] = [
+	{
+		pattern: /timeout/i,
+		message:
+			"The operation took too long. Try a simpler request or break it into smaller steps.",
+	},
+	{
+		pattern: /too many requests|rate limit|retry after/i,
+		message: "Claude is busy right now. Please wait a moment and try again.",
+	},
+	{
+		pattern: /etimedout|econnreset|enotfound/i,
+		message: "Connection issue. Please check your network and try again.",
+	},
+	{
+		pattern: /cancelled|aborted/i,
+		message: "Request was cancelled.",
+	},
+	{
+		pattern: /unsafe command|blocked/i,
+		message: "That operation isn't allowed for safety reasons.",
+	},
+	{
+		pattern: /file access|outside allowed paths/i,
+		message: "Claude can't access that file location.",
+	},
+	{
+		pattern: /authentication|unauthorized|401/i,
+		message: "Authentication issue. Please check your credentials.",
+	},
+];
+
+/**
+ * Convert technical errors to user-friendly messages.
+ */
+export function formatUserError(error: Error): string {
+	const errorStr = error.message || String(error);
+
+	for (const { pattern, message } of ERROR_PATTERNS) {
+		if (pattern.test(errorStr)) {
+			return message;
+		}
+	}
+
+	// Generic fallback with truncation
+	const truncated =
+		errorStr.length > 200 ? errorStr.slice(0, 200) + "..." : errorStr;
+	return `Error: ${truncated || "An unexpected error occurred"}`;
+}

package/src/events.ts

@@ -0,0 +1,57 @@
+/**
+ * Lightweight event emitter for decoupling modules.
+ * Eliminates circular dependencies between session and utils.
+ */
+
+type EventCallback<T> = (data: T) => void;
+
+interface BotEventsMap {
+	sessionRunning: boolean;
+	stopRequested: undefined;
+	interruptRequested: undefined;
+}
+
+class BotEventEmitter {
+	private listeners = new Map<
+		keyof BotEventsMap,
+		Set<EventCallback<unknown>>
+	>();
+	private sessionRunning = false;
+
+	on<K extends keyof BotEventsMap>(
+		event: K,
+		callback: EventCallback<BotEventsMap[K]>,
+	): () => void {
+		if (!this.listeners.has(event)) {
+			this.listeners.set(event, new Set());
+		}
+		this.listeners.get(event)?.add(callback as EventCallback<unknown>);
+
+		return () => {
+			this.listeners.get(event)?.delete(callback as EventCallback<unknown>);
+		};
+	}
+
+	emit<K extends keyof BotEventsMap>(event: K, data: BotEventsMap[K]): void {
+		if (event === "sessionRunning") {
+			this.sessionRunning = data as boolean;
+		}
+
+		const callbacks = this.listeners.get(event);
+		if (callbacks) {
+			for (const callback of callbacks) {
+				try {
+					callback(data);
+				} catch (error) {
+					console.error(`Event handler error for ${event}:`, error);
+				}
+			}
+		}
+	}
+
+	getSessionState(): boolean {
+		return this.sessionRunning;
+	}
+}
+
+export const botEvents = new BotEventEmitter();