ctb 1.0.0

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "ctb",
+	"version": "1.0.0",
+	"description": "Control Claude Code from Telegram - run multiple bot instances per project",
+	"type": "module",
+	"bin": {
+		"ctb": "./src/cli.ts"
+	},
+	"scripts": {
+		"start": "bun run src/bot.ts",
+		"dev": "bun --watch run src/bot.ts",
+		"ctb": "bun run src/cli.ts",
+		"typecheck": "bun run --bun tsc --noEmit"
+	},
+	"keywords": [
+		"claude",
+		"telegram",
+		"bot",
+		"cli",
+		"ai",
+		"anthropic"
+	],
+	"author": "",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/htlin/claude-telegram-bot"
+	},
+	"engines": {
+		"bun": ">=1.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "latest"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"@anthropic-ai/claude-agent-sdk": "^0.1.76",
+		"@grammyjs/runner": "^2.0.3",
+		"@modelcontextprotocol/sdk": "^1.25.1",
+		"grammy": "^1.38.4",
+		"openai": "^6.15.0",
+		"zod": "^4.2.1"
+	}
+}

package/src/__tests__/formatting.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Unit tests for formatting module.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { convertMarkdownToHtml, escapeHtml } from "../formatting";
+
+describe("escapeHtml", () => {
+	test("escapes ampersand", () => {
+		expect(escapeHtml("a & b")).toBe("a & b");
+	});
+
+	test("escapes less than", () => {
+		expect(escapeHtml("a < b")).toBe("a &lt; b");
+	});
+
+	test("escapes greater than", () => {
+		expect(escapeHtml("a > b")).toBe("a &gt; b");
+	});
+
+	test("escapes quotes", () => {
+		expect(escapeHtml('say "hello"')).toBe("say &quot;hello&quot;");
+	});
+
+	test("escapes multiple special characters", () => {
+		expect(escapeHtml('<script>"alert"</script>')).toBe(
+			"&lt;script&gt;&quot;alert&quot;&lt;/script&gt;",
+		);
+	});
+
+	test("handles empty string", () => {
+		expect(escapeHtml("")).toBe("");
+	});
+
+	test("returns unchanged text without special chars", () => {
+		expect(escapeHtml("Hello World")).toBe("Hello World");
+	});
+});
+
+describe("convertMarkdownToHtml", () => {
+	test("converts bold with double asterisks", () => {
+		expect(convertMarkdownToHtml("**bold**")).toBe("<b>bold</b>");
+	});
+
+	test("converts bold with single asterisks", () => {
+		expect(convertMarkdownToHtml("*bold*")).toBe("<b>bold</b>");
+	});
+
+	test("converts bold with double underscores", () => {
+		expect(convertMarkdownToHtml("__bold__")).toBe("<b>bold</b>");
+	});
+
+	test("converts italic with single underscores", () => {
+		expect(convertMarkdownToHtml("_italic_")).toBe("<i>italic</i>");
+	});
+
+	test("converts inline code", () => {
+		expect(convertMarkdownToHtml("`code`")).toBe("<code>code</code>");
+	});
+
+	test("converts code blocks", () => {
+		const input = "```\nconst x = 1;\n```";
+		expect(convertMarkdownToHtml(input)).toContain("<pre>");
+		expect(convertMarkdownToHtml(input)).toContain("const x = 1;");
+		expect(convertMarkdownToHtml(input)).toContain("</pre>");
+	});
+
+	test("converts code blocks with language hint", () => {
+		const input = "```javascript\nconst x = 1;\n```";
+		expect(convertMarkdownToHtml(input)).toContain("<pre>");
+	});
+
+	test("converts headers to bold", () => {
+		expect(convertMarkdownToHtml("# Header")).toContain("<b>Header</b>");
+		expect(convertMarkdownToHtml("## Header")).toContain("<b>Header</b>");
+		expect(convertMarkdownToHtml("### Header")).toContain("<b>Header</b>");
+	});
+
+	test("converts links", () => {
+		expect(convertMarkdownToHtml("[text](https://example.com)")).toBe(
+			'<a href="https://example.com">text</a>',
+		);
+	});
+
+	test("converts bullet lists", () => {
+		expect(convertMarkdownToHtml("- item")).toBe("• item");
+		expect(convertMarkdownToHtml("* item")).toBe("• item");
+	});
+
+	test("escapes HTML in regular text", () => {
+		expect(convertMarkdownToHtml("<script>")).toBe("&lt;script&gt;");
+	});
+
+	test("escapes HTML inside code blocks", () => {
+		const input = "```\n<div>test</div>\n```";
+		const result = convertMarkdownToHtml(input);
+		expect(result).toContain("&lt;div&gt;");
+	});
+
+	test("handles nested formatting", () => {
+		// Bold inside text
+		const input = "This is **bold** text";
+		expect(convertMarkdownToHtml(input)).toBe("This is <b>bold</b> text");
+	});
+
+	test("collapses multiple newlines", () => {
+		const input = "line1\n\n\n\nline2";
+		expect(convertMarkdownToHtml(input)).toBe("line1\n\nline2");
+	});
+
+	test("handles empty string", () => {
+		expect(convertMarkdownToHtml("")).toBe("");
+	});
+
+	test("handles plain text without markdown", () => {
+		expect(convertMarkdownToHtml("Hello World")).toBe("Hello World");
+	});
+});

package/src/__tests__/security.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Unit tests for security module.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { checkCommandSafety, isAuthorized, isPathAllowed } from "../security";
+
+describe("isPathAllowed", () => {
+	test("allows paths under ALLOWED_PATHS", () => {
+		// Note: actual allowed paths depend on environment
+		expect(isPathAllowed("/tmp/test")).toBe(true);
+		expect(isPathAllowed("/tmp/telegram-bot/file.txt")).toBe(true);
+	});
+
+	test("allows temp paths", () => {
+		expect(isPathAllowed("/tmp/foo")).toBe(true);
+		expect(isPathAllowed("/private/tmp/bar")).toBe(true);
+	});
+
+	test("rejects system paths", () => {
+		expect(isPathAllowed("/etc/passwd")).toBe(false);
+		expect(isPathAllowed("/usr/bin/bash")).toBe(false);
+		expect(isPathAllowed("/root/.ssh")).toBe(false);
+	});
+
+	test("handles path traversal attempts", () => {
+		expect(isPathAllowed("/tmp/../etc/passwd")).toBe(false);
+	});
+
+	test("handles tilde expansion", () => {
+		// Should expand ~ to home directory
+		const result = isPathAllowed("~/Documents/test.txt");
+		// Result depends on whether ~/Documents is in ALLOWED_PATHS
+		expect(typeof result).toBe("boolean");
+	});
+
+	test("handles non-existent paths", () => {
+		// Should not throw for non-existent paths
+		expect(() => isPathAllowed("/nonexistent/path/file.txt")).not.toThrow();
+	});
+});
+
+describe("checkCommandSafety", () => {
+	test("allows safe commands", () => {
+		expect(checkCommandSafety("ls -la")).toEqual([true, ""]);
+		expect(checkCommandSafety("git status")).toEqual([true, ""]);
+		expect(checkCommandSafety("cat file.txt")).toEqual([true, ""]);
+	});
+
+	test("blocks fork bomb", () => {
+		const [safe, reason] = checkCommandSafety(":(){ :|:& };:");
+		expect(safe).toBe(false);
+		expect(reason).toContain("Blocked pattern");
+	});
+
+	test("blocks dangerous rm commands", () => {
+		const [safe1, reason1] = checkCommandSafety("rm -rf /");
+		expect(safe1).toBe(false);
+		expect(reason1).toContain("Blocked pattern");
+
+		const [safe2, reason2] = checkCommandSafety("rm -rf ~");
+		expect(safe2).toBe(false);
+		expect(reason2).toContain("Blocked pattern");
+
+		const [safe3, reason3] = checkCommandSafety("sudo rm -rf /home");
+		expect(safe3).toBe(false);
+		expect(reason3).toContain("Blocked pattern");
+	});
+
+	test("blocks disk destruction commands", () => {
+		const [safe1] = checkCommandSafety("> /dev/sda");
+		expect(safe1).toBe(false);
+
+		const [safe2] = checkCommandSafety("mkfs.ext4 /dev/sda");
+		expect(safe2).toBe(false);
+
+		const [safe3] = checkCommandSafety("dd if=/dev/zero of=/dev/sda");
+		expect(safe3).toBe(false);
+	});
+
+	test("validates rm paths against allowed list", () => {
+		// rm to temp directory should be allowed
+		const [safe1] = checkCommandSafety("rm /tmp/test.txt");
+		expect(safe1).toBe(true);
+
+		// rm to system paths should be blocked
+		const [safe2, reason2] = checkCommandSafety("rm /etc/passwd");
+		expect(safe2).toBe(false);
+		expect(reason2).toContain("outside allowed paths");
+	});
+
+	test("handles rm with flags", () => {
+		// Should allow rm -f to temp
+		const [safe1] = checkCommandSafety("rm -f /tmp/test.txt");
+		expect(safe1).toBe(true);
+
+		// Should block rm -rf to system paths
+		const [safe2] = checkCommandSafety("rm -rf /var/log");
+		expect(safe2).toBe(false);
+	});
+});
+
+describe("isAuthorized", () => {
+	const allowedUsers = [123, 456, 789];
+
+	test("returns true for allowed users", () => {
+		expect(isAuthorized(123, allowedUsers)).toBe(true);
+		expect(isAuthorized(456, allowedUsers)).toBe(true);
+		expect(isAuthorized(789, allowedUsers)).toBe(true);
+	});
+
+	test("returns false for unauthorized users", () => {
+		expect(isAuthorized(999, allowedUsers)).toBe(false);
+		expect(isAuthorized(0, allowedUsers)).toBe(false);
+	});
+
+	test("returns false for undefined userId", () => {
+		expect(isAuthorized(undefined, allowedUsers)).toBe(false);
+	});
+
+	test("returns false when allowed users list is empty", () => {
+		expect(isAuthorized(123, [])).toBe(false);
+	});
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,8 @@
+/**
+ * Test setup - sets required environment variables for tests.
+ */
+
+// Set dummy values for required environment variables
+process.env.TELEGRAM_BOT_TOKEN = "test-token-12345";
+process.env.TELEGRAM_ALLOWED_USERS = "123,456,789";
+process.env.CLAUDE_WORKING_DIR = "/tmp";

package/src/bookmarks.ts

@@ -0,0 +1,106 @@
+/**
+ * Bookmarks management for Claude Telegram Bot.
+ *
+ * Stores and retrieves directory bookmarks.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+const BOOKMARKS_FILE = "/tmp/claude-telegram-bookmarks.json";
+
+export interface Bookmark {
+	path: string;
+	name: string;
+	addedAt: string;
+}
+
+/**
+ * Load bookmarks from file.
+ */
+export function loadBookmarks(): Bookmark[] {
+	try {
+		if (!existsSync(BOOKMARKS_FILE)) {
+			return [];
+		}
+		const text = readFileSync(BOOKMARKS_FILE, "utf-8");
+		const data = JSON.parse(text);
+		return Array.isArray(data) ? data : [];
+	} catch (error) {
+		console.warn("Failed to load bookmarks:", error);
+		return [];
+	}
+}
+
+/**
+ * Save bookmarks to file.
+ */
+export function saveBookmarks(bookmarks: Bookmark[]): void {
+	try {
+		writeFileSync(BOOKMARKS_FILE, JSON.stringify(bookmarks, null, 2));
+	} catch (error) {
+		console.error("Failed to save bookmarks:", error);
+	}
+}
+
+/**
+ * Add a bookmark.
+ */
+export function addBookmark(path: string): boolean {
+	const bookmarks = loadBookmarks();
+
+	// Resolve and normalize path
+	const resolvedPath = resolvePath(path);
+
+	// Check if already bookmarked
+	if (bookmarks.some((b) => b.path === resolvedPath)) {
+		return false;
+	}
+
+	// Extract name from path
+	const name = resolvedPath.split("/").pop() || resolvedPath;
+
+	bookmarks.push({
+		path: resolvedPath,
+		name,
+		addedAt: new Date().toISOString(),
+	});
+
+	saveBookmarks(bookmarks);
+	return true;
+}
+
+/**
+ * Remove a bookmark by path.
+ */
+export function removeBookmark(path: string): boolean {
+	const bookmarks = loadBookmarks();
+	const resolvedPath = resolvePath(path);
+
+	const index = bookmarks.findIndex((b) => b.path === resolvedPath);
+	if (index === -1) {
+		return false;
+	}
+
+	bookmarks.splice(index, 1);
+	saveBookmarks(bookmarks);
+	return true;
+}
+
+/**
+ * Check if a path is bookmarked.
+ */
+export function isBookmarked(path: string): boolean {
+	const bookmarks = loadBookmarks();
+	const resolvedPath = resolvePath(path);
+	return bookmarks.some((b) => b.path === resolvedPath);
+}
+
+/**
+ * Resolve path with ~ expansion.
+ */
+export function resolvePath(path: string): string {
+	const expanded = path.replace(/^~/, homedir());
+	return resolve(expanded);
+}

package/src/bot.ts

@@ -0,0 +1,151 @@
+/**
+ * Claude Telegram Bot - Bot startup module
+ *
+ * This module is imported by cli.ts after environment setup.
+ * Can also be run directly with `bun run src/bot.ts` for backwards compatibility.
+ */
+
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { run, sequentialize } from "@grammyjs/runner";
+import { Bot } from "grammy";
+import {
+	ALLOWED_USERS,
+	RESTART_FILE,
+	TELEGRAM_TOKEN,
+	WORKING_DIR,
+} from "./config";
+import {
+	handleBookmarks,
+	handleCallback,
+	handleCd,
+	handleDocument,
+	handleNew,
+	handlePhoto,
+	handleRestart,
+	handleResume,
+	handleRetry,
+	handleStart,
+	handleStatus,
+	handleStop,
+	handleText,
+	handleVoice,
+} from "./handlers";
+
+// Create bot instance
+const bot = new Bot(TELEGRAM_TOKEN);
+
+// Sequentialize non-command messages per user (prevents race conditions)
+// Commands bypass sequentialization so they work immediately
+bot.use(
+	sequentialize((ctx) => {
+		// Commands are not sequentialized - they work immediately
+		if (ctx.message?.text?.startsWith("/")) {
+			return undefined;
+		}
+		// Messages with ! prefix bypass queue (interrupt)
+		if (ctx.message?.text?.startsWith("!")) {
+			return undefined;
+		}
+		// Callback queries (button clicks) are not sequentialized
+		if (ctx.callbackQuery) {
+			return undefined;
+		}
+		// Other messages are sequentialized per chat
+		return ctx.chat?.id.toString();
+	}),
+);
+
+// ============== Command Handlers ==============
+
+bot.command("start", handleStart);
+bot.command("new", handleNew);
+bot.command("stop", handleStop);
+bot.command("status", handleStatus);
+bot.command("resume", handleResume);
+bot.command("restart", handleRestart);
+bot.command("retry", handleRetry);
+bot.command("cd", handleCd);
+bot.command("bookmarks", handleBookmarks);
+
+// ============== Message Handlers ==============
+
+// Text messages
+bot.on("message:text", handleText);
+
+// Voice messages
+bot.on("message:voice", handleVoice);
+
+// Photo messages
+bot.on("message:photo", handlePhoto);
+
+// Document messages
+bot.on("message:document", handleDocument);
+
+// ============== Callback Queries ==============
+
+bot.on("callback_query:data", handleCallback);
+
+// ============== Error Handler ==============
+
+bot.catch((err) => {
+	console.error("Bot error:", err);
+});
+
+// ============== Startup ==============
+
+console.log("=".repeat(50));
+console.log("Claude Telegram Bot");
+console.log("=".repeat(50));
+console.log(`Working directory: ${WORKING_DIR}`);
+console.log(`Allowed users: ${ALLOWED_USERS.length}`);
+console.log("Starting bot...");
+
+// Get bot info first
+const botInfo = await bot.api.getMe();
+console.log(`Bot started: @${botInfo.username}`);
+
+// Check for pending restart message to update
+if (existsSync(RESTART_FILE)) {
+	try {
+		const data = JSON.parse(readFileSync(RESTART_FILE, "utf-8"));
+		const age = Date.now() - data.timestamp;
+
+		// Only update if restart was recent (within 30 seconds)
+		if (age < 30000 && data.chat_id && data.message_id) {
+			await bot.api.editMessageText(
+				data.chat_id,
+				data.message_id,
+				"✅ Bot restarted",
+			);
+		}
+		unlinkSync(RESTART_FILE);
+	} catch (e) {
+		console.warn("Failed to update restart message:", e);
+		try {
+			unlinkSync(RESTART_FILE);
+		} catch {}
+	}
+}
+
+// Start with concurrent runner (commands work immediately)
+const runner = run(bot);
+
+// Graceful shutdown
+const stopRunner = () => {
+	if (runner.isRunning()) {
+		console.log("Stopping bot...");
+		runner.stop();
+	}
+};
+
+process.on("SIGINT", () => {
+	console.log("Received SIGINT");
+	stopRunner();
+	process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+	console.log("Received SIGTERM");
+	stopRunner();
+	process.exit(0);
+});