@grinev/opencode-telegram-bot 0.1.0-rc.8 → 0.1.0

package/.env.example

@@ -1,7 +1,7 @@
 # Telegram Bot Token (from @BotFather)
 TELEGRAM_BOT_TOKEN=
 
-# Allowed Telegram User ID (fron @userinfobot)
+# Allowed Telegram User ID (from @userinfobot)
 TELEGRAM_ALLOWED_USER_ID=
 
 # OpenCode API URL (optional, default: http://localhost:4096)

package/README.md

@@ -1,72 +1,205 @@
-# OpenCode Telegram Client
+# OpenCode Telegram Bot
 
-Мобильный клиент для OpenCode в Telegram, позволяющий управлять задачами разработки на локальном компьютере.
+[![npm version](https://img.shields.io/npm/v/@grinev/opencode-telegram-bot)](https://www.npmjs.com/package/@grinev/opencode-telegram-bot)
+[![CI](https://github.com/grinev/opencode-telegram-bot/actions/workflows/ci.yml/badge.svg)](https://github.com/grinev/opencode-telegram-bot/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
-## Требования
+Control your [OpenCode](https://opencode.ai) coding agent from your phone. Send tasks, switch models, monitor progress — all through Telegram.
 
-- Node.js 20+
-- Установленный OpenCode CLI (`opencode`)
+No open ports, no exposed APIs. The bot runs on your machine alongside OpenCode and communicates exclusively through the Telegram Bot API.
 
-## Установка
+<p align="center">
+  <img src="assets/Screenshot-1.png" width="32%" alt="Sending a coding task and receiving file edit results" />
+  <img src="assets/Screenshot-2.png" width="32%" alt="Live session status with context usage and changed files" />
+  <img src="assets/Screenshot-3.png" width="32%" alt="Switching between AI models from favorites" />
+</p>
 
-1. Клонируйте репозиторий.
-2. Установите зависимости:
-   ```bash
-   npm install
-   ```
-3. Скопируйте файл с переменными окружения:
-   ```bash
-   cp .env.example .env
-   ```
-4. Заполните `.env` файл (токен бота, ваш ID и путь к проекту).
-5. Настройте избранные модели в OpenCode (Desktop/TUI). Бот автоматически читает их из локального state файла OpenCode (`model.json`).
-6. Если избранные модели недоступны или файл не читается, бот использует fallback из `.env`:
-   - `OPENCODE_MODEL_PROVIDER`
-   - `OPENCODE_MODEL_ID`
+## Features
 
-## Переменные окружения
+- **Remote coding** — send prompts to OpenCode from anywhere, receive complete results with code sent as files
+- **Session management** — create new sessions or continue existing ones, just like in the TUI
+- **Live status** — pinned message with current project, model, context usage, and changed files list, updated in real time
+- **Model switching** — pick any model from your OpenCode favorites directly in the chat
+- **Agent modes** — switch between Plan and Build modes on the fly
+- **Interactive Q&A** — answer agent questions and approve permissions via inline buttons
+- **Context control** — compact context when it gets too large, right from the chat
+- **Security** — strict user ID whitelist; no one else can access your bot, even if they find it
+- **Localization** — English and Russian UI (`BOT_LOCALE=en|ru`)
 
-Основные переменные в `.env`:
+## Prerequisites
 
-- `TELEGRAM_BOT_TOKEN` — токен бота (обязательно).
-- `TELEGRAM_ALLOWED_USER_ID` — ваш Telegram user ID (обязательно).
-- `OPENCODE_MODEL_PROVIDER` — провайдер модели по умолчанию (обязательно).
-- `OPENCODE_MODEL_ID` — ID модели по умолчанию (обязательно).
-- `SESSIONS_LIST_LIMIT` — сколько последних сессий показывать в `/sessions` (опционально, по умолчанию `10`).
+- **Node.js 20+** — [download](https://nodejs.org)
+- **OpenCode** — install from [opencode.ai](https://opencode.ai) or [GitHub](https://github.com/sst/opencode)
+- **Telegram Bot** — you'll create one during setup (takes 1 minute)
 
-## Сборка и запуск
+## Quick Start
 
-### Режим разработки
+### 1. Create a Telegram Bot
 
-Запуск без автоматической перезагрузки процесса:
+1. Open [@BotFather](https://t.me/BotFather) in Telegram and send `/newbot`
+2. Follow the prompts to choose a name and username
+3. Copy the **bot token** you receive (e.g. `123456:ABC-DEF1234...`)
 
-> В этом проекте auto-restart (watch/restart) намеренно не используется для runtime-бота,
-> чтобы не ломать активные SSE/polling соединения.
+You'll also need your **Telegram User ID** — send any message to [@userinfobot](https://t.me/userinfobot) and it will reply with your numeric ID.
+
+### 2. Start OpenCode Server
+
+In your project directory, start the OpenCode server:
+
+```bash
+opencode serve
+```
+
+> The bot connects to the OpenCode API at `http://localhost:4096` by default.
+
+### 3. Install & Run
+
+The fastest way — run directly with `npx`:
+
+```bash
+npx @grinev/opencode-telegram-bot
+```
+
+On first launch, an interactive wizard will guide you through the configuration — it will ask for your bot token, user ID, and OpenCode API URL. After that, you're ready to go. Open your bot in Telegram and start sending tasks.
+
+#### Alternative: Global Install
+
+```bash
+npm install -g @grinev/opencode-telegram-bot
+opencode-telegram start
+```
+
+To reconfigure at any time:
+
+```bash
+opencode-telegram config
+```
+
+## Supported Platforms
+
+| Platform | Status                                                                                                                               |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| macOS    | Fully supported                                                                                                                      |
+| Windows  | Fully supported                                                                                                                      |
+| Linux    | Experimental — should work, but has not been extensively tested. You may need additional steps such as granting execute permissions. |
+
+## Bot Commands
+
+| Command           | Description                                             |
+| ----------------- | ------------------------------------------------------- |
+| `/status`         | Server health, current project, session, and model info |
+| `/new`            | Create a new session                                    |
+| `/stop`           | Abort the current task                                  |
+| `/sessions`       | Browse and switch between recent sessions               |
+| `/projects`       | Switch between OpenCode projects                        |
+| `/model`          | Choose a model from your favorites                      |
+| `/agent`          | Switch agent mode (Plan / Build)                        |
+| `/opencode_start` | Start the OpenCode server remotely                      |
+| `/opencode_stop`  | Stop the OpenCode server remotely                       |
+| `/help`           | Show available commands                                 |
+
+Any regular text message is sent as a prompt to the coding agent.
+
+> `/opencode_start` and `/opencode_stop` are intended as emergency commands — for example, if you need to restart a stuck server while away from your computer. Under normal usage, start `opencode serve` yourself before launching the bot.
+
+## Configuration
+
+### Environment Variables
+
+When installed via npm, the configuration wizard handles the initial setup. The `.env` file is stored in your platform's app data directory:
+
+- **macOS:** `~/Library/Application Support/opencode-telegram-bot/.env`
+- **Windows:** `%APPDATA%\opencode-telegram-bot\.env`
+- **Linux:** `~/.config/opencode-telegram-bot/.env`
+
+| Variable                   | Description                                  | Required | Default                 |
+| -------------------------- | -------------------------------------------- | :------: | ----------------------- |
+| `TELEGRAM_BOT_TOKEN`       | Bot token from @BotFather                    |   Yes    | —                       |
+| `TELEGRAM_ALLOWED_USER_ID` | Your numeric Telegram user ID                |   Yes    | —                       |
+| `OPENCODE_API_URL`         | OpenCode server URL                          |    No    | `http://localhost:4096` |
+| `OPENCODE_SERVER_USERNAME` | Server auth username                         |    No    | `opencode`              |
+| `OPENCODE_SERVER_PASSWORD` | Server auth password                         |    No    | —                       |
+| `OPENCODE_MODEL_PROVIDER`  | Default model provider                       |   Yes    | `opencode`              |
+| `OPENCODE_MODEL_ID`        | Default model ID                             |   Yes    | `big-pickle`            |
+| `BOT_LOCALE`               | Bot UI language (`en` or `ru`)               |    No    | `en`                    |
+| `SESSIONS_LIST_LIMIT`      | Max sessions shown in `/sessions`            |    No    | `10`                    |
+| `CODE_FILE_MAX_SIZE_KB`    | Max file size (KB) to send as document       |    No    | `100`                   |
+| `LOG_LEVEL`                | Log level (`debug`, `info`, `warn`, `error`) |    No    | `info`                  |
+
+> **Keep your `.env` file private.** It contains your bot token. Never commit it to version control.
+
+### Model Configuration
+
+The bot picks up your **favorite models** from OpenCode. To add a model to favorites:
+
+1. Open OpenCode TUI (`opencode`)
+2. Go to model selection
+3. Hover over the model you want and press **Ctrl+F** to add it to favorites
+
+These favorites will appear in the `/model` command menu in Telegram.
+
+A free model (`opencode/big-pickle`) is configured as the default fallback — if you haven't set up any favorites yet, the bot will use it automatically.
+
+## Security
+
+The bot enforces a strict **user ID whitelist**. Only the Telegram user whose numeric ID matches `TELEGRAM_ALLOWED_USER_ID` can interact with the bot. Messages from any other user are silently ignored and logged as unauthorized access attempts.
+
+Since the bot runs locally on your machine and connects to your local OpenCode server, there is no external attack surface beyond the Telegram Bot API itself.
+
+## Development
+
+### Running from Source
+
+```bash
+git clone https://github.com/grinev/opencode-telegram-bot.git
+cd opencode-telegram-bot
+npm install
+cp .env.example .env
+# Edit .env with your bot token, user ID, and model settings
+```
+
+Build and run:
 
 ```bash
 npm run dev
 ```
 
-### Продакшн
+### Available Scripts
+
+| Script                  | Description                         |
+| ----------------------- | ----------------------------------- |
+| `npm run dev`           | Build and start (development)       |
+| `npm run build`         | Compile TypeScript                  |
+| `npm start`             | Run compiled code                   |
+| `npm run lint`          | ESLint check (zero warnings policy) |
+| `npm run format`        | Format code with Prettier           |
+| `npm test`              | Run tests (Vitest)                  |
+| `npm run test:coverage` | Tests with coverage report          |
+
+> **Note:** No file watcher or auto-restart is used. The bot maintains persistent SSE and long-polling connections — automatic restarts would break them mid-task. After making changes, restart manually with `npm run dev`.
+
+## Troubleshooting
+
+**Bot doesn't respond to messages**
+
+- Make sure `TELEGRAM_ALLOWED_USER_ID` matches your actual Telegram user ID (check with [@userinfobot](https://t.me/userinfobot))
+- Verify the bot token is correct
+
+**"OpenCode server is not available"**
+
+- Ensure `opencode serve` is running in your project directory
+- Check that `OPENCODE_API_URL` points to the correct address (default: `http://localhost:4096`)
+
+**No models in `/model` menu**
 
-1. Соберите проект:
-   ```bash
-   npm run build
-   ```
-2. Запустите собранный код:
-   ```bash
-   npm start
-   ```
+- Add models to your OpenCode favorites: open OpenCode TUI, go to model selection, press **Ctrl+F** on desired models
 
-## Команды
+**Linux: permission denied errors**
 
-- `npm run lint` — проверка кода линтером.
-- `npm run format` — форматирование кода через Prettier.
-- `npm run test` — запуск тестов через Vitest.
-- `npm run test:coverage` — запуск тестов с coverage-отчётом.
+- Make sure the CLI binary has execute permission: `chmod +x $(which opencode-telegram)`
+- Check that the config directory is writable: `~/.config/opencode-telegram-bot/`
 
-## Функционал
+## License
 
-Подробное описание функционала и плана разработки находится в [PRODUCT.md](./PRODUCT.md).
-План технических улучшений (архитектура + тесты) — в [TECHNICAL_IMPROVEMENTS.md](./TECHNICAL_IMPROVEMENTS.md).
-Инструкции для разработчиков и описание архитектуры — в [AGENTS.md](./AGENTS.md).
+[MIT](LICENSE) © Ruslan Grinev

package/dist/utils/logger.js

@@ -1,25 +1,57 @@
 import { config } from "../config.js";
+/**
+ * Mapping of log levels to numeric values for comparison
+ * Used to determine if a message should be logged based on configured level
+ */
 const LOG_LEVELS = {
     debug: 0,
     info: 1,
     warn: 2,
     error: 3,
 };
+/**
+ * Normalizes a string value to a valid LogLevel
+ * Falls back to 'info' if the value is invalid
+ *
+ * @param value - The log level string to normalize
+ * @returns A valid LogLevel
+ */
 function normalizeLogLevel(value) {
     if (value in LOG_LEVELS) {
         return value;
     }
     return "info";
 }
+/**
+ * Formats the log message prefix with timestamp and level
+ *
+ * @param level - The log level for the message
+ * @returns Formatted prefix string
+ */
 function formatPrefix(level) {
     return `[${new Date().toISOString()}] [${level.toUpperCase()}]`;
 }
+/**
+ * Formats individual arguments for logging
+ * Special handling for Error objects to extract stack trace
+ *
+ * @param arg - The argument to format
+ * @returns Formatted argument
+ */
 function formatArg(arg) {
     if (arg instanceof Error) {
         return arg.stack ?? `${arg.name}: ${arg.message}`;
     }
     return arg;
 }
+/**
+ * Prepends formatted prefix to log arguments
+ * Handles different argument formats (string vs non-string first argument)
+ *
+ * @param level - The log level for prefix formatting
+ * @param args - The arguments to log
+ * @returns Array with prefix prepended
+ */
 function withPrefix(level, args) {
     const formattedArgs = args.map((arg) => formatArg(arg));
     const prefix = formatPrefix(level);
@@ -31,26 +63,62 @@ function withPrefix(level, args) {
     }
     return [prefix, ...formattedArgs];
 }
+/**
+ * Determines if a message should be logged based on configured log level
+ * Messages with level >= configured level will be logged
+ *
+ * @param level - The level of the message to check
+ * @returns True if the message should be logged
+ */
 function shouldLog(level) {
     const configLevel = normalizeLogLevel(config.server.logLevel);
     return LOG_LEVELS[level] >= LOG_LEVELS[configLevel];
 }
+/**
+ * Logger interface with methods for different log levels
+ * Each method checks if the message should be logged based on configured level
+ * and formats the output with timestamp and level prefix
+ */
 export const logger = {
+    /**
+     * Logs debug-level messages (most verbose)
+     * Used for detailed diagnostics and internal operations
+     *
+     * @param args - Arguments to log
+     */
     debug: (...args) => {
         if (shouldLog("debug")) {
             console.log(...withPrefix("debug", args));
         }
     },
+    /**
+     * Logs info-level messages
+     * Used for important events and general information
+     *
+     * @param args - Arguments to log
+     */
     info: (...args) => {
         if (shouldLog("info")) {
             console.log(...withPrefix("info", args));
         }
     },
+    /**
+     * Logs warning-level messages
+     * Used for recoverable errors and potential issues
+     *
+     * @param args - Arguments to log
+     */
     warn: (...args) => {
         if (shouldLog("warn")) {
             console.warn(...withPrefix("warn", args));
         }
     },
+    /**
+     * Logs error-level messages
+     * Used for critical failures and exceptions
+     *
+     * @param args - Arguments to log
+     */
     error: (...args) => {
         if (shouldLog("error")) {
             console.error(...withPrefix("error", args));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grinev/opencode-telegram-bot",
-  "version": "0.1.0-rc.8",
+  "version": "0.1.0",
   "description": "Telegram bot client for OpenCode to run and monitor coding tasks from chat.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,6 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "npm run build && npm start",
-    "list-providers": "tsx scripts/list-providers.ts",
     "release:prepare": "node scripts/release-prepare.mjs",
     "release:rc": "node scripts/release-prepare.mjs rc",
     "lint": "eslint src --ext .ts --max-warnings=0",
@@ -34,7 +33,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/grinev/my-telegram-opencode-bot.git"
+    "url": "git+https://github.com/grinev/opencode-telegram-bot.git"
   },
   "keywords": [
     "opencode",
@@ -47,15 +46,14 @@
   "author": "grinev",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/grinev/my-telegram-opencode-bot/issues"
+    "url": "https://github.com/grinev/opencode-telegram-bot/issues"
   },
-  "homepage": "https://github.com/grinev/my-telegram-opencode-bot#readme",
+  "homepage": "https://github.com/grinev/opencode-telegram-bot#readme",
   "dependencies": {
     "@grammyjs/menu": "^1.3.1",
     "@opencode-ai/sdk": "^1.1.21",
     "dotenv": "^17.2.3",
-    "grammy": "^1.39.2",
-    "pino": "^10.2.0"
+    "grammy": "^1.39.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.8",
@@ -64,7 +62,6 @@
     "@vitest/coverage-v8": "^3.2.4",
     "eslint": "^8.57.1",
     "eslint-config-prettier": "^10.1.8",
-    "pino-pretty": "^13.1.3",
     "prettier": "^3.8.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",