@dikacode/telegram-mcp 1.0.0 → 1.0.2

package/README.md

@@ -11,7 +11,6 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@dikacode/telegram-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@dikacode/telegram-mcp?style=flat-square&color=5eead4&label=npm"></a>
-  <a href="https://www.npmjs.com/package/@dikacode/telegram-mcp"><img alt="downloads" src="https://img.shields.io/npm/dm/@dikacode/telegram-mcp?style=flat-square&color=38bdf8"></a>
   <a href="https://github.com/dikaglorya/telegram-mcp/actions/workflows/ci.yml"><img alt="ci" src="https://github.com/dikaglorya/telegram-mcp/actions/workflows/ci.yml/badge.svg"></a>
   <img alt="node" src="https://img.shields.io/badge/node-%E2%89%A5%2020-0ea5e9?style=flat-square">
   <img alt="tools" src="https://img.shields.io/badge/tools-69-a78bfa?style=flat-square">
@@ -78,6 +77,7 @@ The server speaks MCP over stdio, so the last command is only a manual check. Th
 - [Architecture](#architecture)
 - [Requirements](#requirements)
 - [Install](#install)
+- [Updating](#updating)
 - [Credentials](#credentials)
 - [First login — from chat](#first-login--from-chat)
 - [Connect your agent](#connect-your-agent)
@@ -150,7 +150,7 @@ telegram-mcp
 }
 ```
 
-Pin a version if you want reproducible installs: `npx -y @dikacode/telegram-mcp@1.0.0`.
+Pin a version if you want reproducible installs: `npx -y @dikacode/telegram-mcp@1.0.2`.
 
 ### 2. Clone and link
 
@@ -170,7 +170,7 @@ npm link             # optional: makes `telegram-mcp` available on PATH
 Download the tarball attached to the latest release and install it globally:
 
 ```bash
-npm install -g https://github.com/dikaglorya/telegram-mcp/releases/download/v1.0.0/dikacode-telegram-mcp-1.0.0.tgz
+npm install -g https://github.com/dikaglorya/telegram-mcp/releases/download/v1.0.2/dikacode-telegram-mcp-1.0.2.tgz
 telegram-mcp
 ```
 
@@ -186,6 +186,59 @@ npx -y github:dikaglorya/telegram-mcp
 
 npm fetches the repository, installs dependencies, runs the `prepare` build, and starts the launcher.
 
+## Updating
+
+One command, whichever way it was installed:
+
+```bash
+telegram-mcp update
+```
+
+It works out how *this* copy got here and runs the right thing — `npm install
+-g @latest` for a global install (reusing a custom `--prefix`), `git pull
+--ff-only` plus a rebuild for a checkout, and a plain restart instruction for an
+npx run, where nothing on disk needs changing. `--check` reports and installs
+nothing.
+
+```text
+telegram-mcp 1.0.2 · update
+
+  installed   1.0.1  /home/you/.local/lib/node_modules/@dikacode/telegram-mcp
+  latest      1.0.2
+  install     global npm package
+
+  ▲ 1.0.1 -> 1.0.2 available
+```
+
+| Installed with | Behaviour |
+| --- | --- |
+| `npx -y @dikacode/telegram-mcp` (unpinned) | **Automatic.** npm resolves `latest` on every start, so the next client restart picks up a new release. |
+| `npx -y @dikacode/telegram-mcp@1.0.2` (pinned) | **Never.** That is the point of pinning. |
+| `npm install -g @dikacode/telegram-mcp` | **`telegram-mcp update`**, or `npm update -g @dikacode/telegram-mcp`. |
+| Release tarball | **Manual.** Reinstall from the newer tarball. |
+| `npx -y github:dikaglorya/telegram-mcp` | **Not automatic.** npm caches the fetched repo; clear the cache or pin a ref (`#main`) to move forward. |
+
+Check what you are running:
+
+```bash
+telegram-mcp --version
+telegram-mcp update --check                 # newer release available? installs nothing
+npm outdated -g @dikacode/telegram-mcp      # global installs only
+```
+
+The server also tells you. When a newer release exists it prints one line to
+stderr at startup, after the MCP transport is already serving:
+
+```
+[telegram-mcp] update available: 1.0.1 -> 1.0.2. Run `npm install -g @dikacode/telegram-mcp@latest`, or set TELEGRAM_UPDATE_CHECK=0 to silence this.
+```
+
+That check is a single request to the npm registry with an 800 ms timeout,
+cached for 24 hours, and it never blocks startup or writes to stdout. If you
+want zero outbound traffic that is not Telegram itself, set
+`TELEGRAM_UPDATE_CHECK=0`. `telegram_doctor` shows the version it knows about
+without touching the network.
+
 ## Credentials
 
 1. Open [my.telegram.org/apps](https://my.telegram.org/apps) and log in with your phone number.
@@ -477,6 +530,8 @@ All settings are environment variables. The server also loads a `.env` next to t
 | `TELEGRAM_EXPORT_DIR` | `~/.telegram-mcp/exports` | History exports. |
 | `TELEGRAM_AUDIT_LOG` | `~/.telegram-mcp/audit.log` | Call log. |
 | `TELEGRAM_MAX_DOWNLOAD_BYTES` | `0` (unlimited) | Hard cap for one download. A non-numeric value is refused rather than treated as unlimited. |
+| `TELEGRAM_UPDATE_CHECK` | `true` | Set to `0` to stop the startup check for a newer npm release. |
+| `TELEGRAM_UPDATE_CHECK_TIMEOUT_MS` | `800` | Timeout for that check, capped at 10 s. |
 | `TELEGRAM_MCP_NODE` | current Node | Launcher override, for exotic Node installs. |
 
 `~` and `~\` are both expanded. Relative paths resolve against the current working directory.
@@ -494,6 +549,9 @@ All settings are environment variables. The server also loads a `.env` next to t
 | `Cannot find module .../dist/index.js` | The package was installed without building. Run `npm run build`, or use the release tarball. |
 | Login works, then the next run asks again | `TELEGRAM_SESSION_PATH` changed between runs. Keep it stable, or leave it unset. |
 | Window/terminal closes when started by hand | Expected: the server speaks MCP on stdio. Start it through a client, or use `npm run login` for the standalone CLI. |
+| `update available: …` on every start | A newer release is on npm. Run `telegram-mcp update`, or set `TELEGRAM_UPDATE_CHECK=0` if you pin versions on purpose. |
+| `telegram-mcp update` finds no upgrade command | The copy lives in a `node_modules` tree npm does not manage as a global prefix (npx cache, or a project dependency). Restart it as `npx -y @dikacode/telegram-mcp@latest`, or upgrade the project dependency. |
+| `telegram-mcp --version` prints nothing | You are on `1.0.0`, which predates the flag. Upgrade to `1.0.1` or newer. |
 
 ## Development
 
@@ -503,7 +561,7 @@ The repository ships with a unit suite and a real MCP harness that spawns the bu
 npm install
 npm run build
 
-npm run test:unit          # 64 offline checks
+npm run test:unit          # 72 offline checks
 npm run test:mcp           # read-only end-to-end pass
 npm run test:mcp:write     # + self-cleaning writes
 npm run test:destructive   # + disposable chats (opt-in, flood-limited)
@@ -529,7 +587,7 @@ The harness also supports `--json`, `--only=tool_a,tool_b`, `--cleanup`, `--recl
 ```
 telegram-mcp/
 ├── bin/telegram-mcp.js      portable launcher (finds Node, then dist/index.js)
-├── cli/                     standalone login and doctor commands
+├── cli/                     standalone login, doctor and update commands
 ├── assets/                  animated README art (SVG, no scripts)
 ├── harness/                 unit checks + end-to-end MCP harness
 ├── index.ts                 stdio entrypoint
@@ -556,7 +614,8 @@ The TypeScript is built with `tsc` to `dist/`. There is no bundler; the publishe
 
 ## Release
 
-**v1.0.0** is the first public release.
+**v1.0.2** is the current release, published to npm as
+[`@dikacode/telegram-mcp`](https://www.npmjs.com/package/@dikacode/telegram-mcp).
 
 - 69 MCP tools, all registered with strict input schemas.
 - In-chat login, including two-step verification.
@@ -564,6 +623,9 @@ The TypeScript is built with `tsc` to `dist/`. There is no bundler; the publishe
 - Read-back verification for state-changing tools.
 - Optional allowlist, audited calls, redacted secrets.
 - Cross-platform launcher; no hardcoded paths.
+- `--version` / `--help`, and a startup notice when a newer release exists.
+- `telegram-mcp update` upgrades whichever layout is installed; `--check`
+  reports without touching anything.
 - End-to-end harness with paging, policy probes and artifact cleanup.
 
 See [CHANGELOG.md](https://github.com/dikaglorya/telegram-mcp/blob/main/CHANGELOG.md) for the full release notes. Release artifacts are on the [releases page](https://github.com/dikaglorya/telegram-mcp/releases).

package/dist/cli/doctor.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 /**
  * Doctor: validate config, session presence, permissions, live connectivity.
- * Prints pass/fail. Never prints secrets.
+ * Never prints secrets.
+ *
+ * Output is a framed report on stdout when run as a CLI — this is a human
+ * command, not an MCP server, so stdout is free. Under `--quiet` (or when
+ * piped) it prints one line per check with no colour, which is what CI wants.
  */
 import "../env.js";
 import fs from "node:fs";
@@ -9,8 +13,14 @@ import path from "node:path";
 import { ensureDirs, getConfig, hasSession, readSessionString, redact } from "../config.js";
 import { lockFile } from "../perms.js";
 import { getClient, disconnect } from "../telegram.js";
-function line(okFlag, label, detail = "") {
-    process.stdout.write(`[${okFlag ? "PASS" : "FAIL"}] ${label}${detail ? ` — ${detail}` : ""}\n`);
+import { banner, colorEnabled, gap, paint, sym, theme } from "../ui.js";
+const out = (text) => void process.stdout.write(text);
+const rows = [];
+function record(pass, label, detail = "") {
+    rows.push({ pass, label, detail });
+}
+function icon(pass) {
+    return pass ? theme.success(sym.ok) : theme.fail(sym.fail);
 }
 async function main() {
     let failures = 0;
@@ -19,49 +29,55 @@ async function main() {
         config = getConfig();
     }
     catch (err) {
-        line(false, "config", err instanceof Error ? err.message : String(err));
+        record(false, "config", err instanceof Error ? err.message : String(err));
+        report();
         process.exit(1);
     }
     ensureDirs(config);
-    line(true, "config", `api_id=${config.apiId}, allowAll=${config.allowAllChats}, allowlist=${config.allowlist.length}`);
-    line(fs.existsSync(path.dirname(config.sessionPath)), "state dir", path.dirname(config.sessionPath));
+    record(true, "config", `api_id=${config.apiId}, allowAll=${config.allowAllChats}, allowlist=${config.allowlist.length}`);
+    record(fs.existsSync(path.dirname(config.sessionPath)), "state dir", path.dirname(config.sessionPath));
     const has = hasSession(config);
-    line(has, "session present", config.sessionPath);
+    record(has, "session present", config.sessionPath);
     if (!has)
         failures++;
     if (has) {
         if (process.platform === "win32") {
-            line(true, "session permissions", "skipped on Windows (inherits user profile ACLs)");
+            record(true, "session permissions", "skipped on Windows (inherits user profile ACLs)");
         }
         else {
             try {
                 const mode = fs.statSync(config.sessionPath).mode & 0o777;
                 const good = (mode & 0o077) === 0;
-                line(good, "session permissions", `mode=${mode.toString(8)}`);
-                if (!good) {
+                if (good) {
+                    record(true, "session permissions", `mode=${mode.toString(8)}`);
+                }
+                else {
                     lockFile(config.sessionPath);
-                    line(true, "session permissions", "repaired to 600");
+                    const fixed = (fs.statSync(config.sessionPath).mode & 0o777 & 0o077) === 0;
+                    record(fixed, "session permissions", fixed ? "repaired to 600" : `mode=${mode.toString(8)}`);
+                    if (!fixed)
+                        failures++;
                 }
             }
             catch (err) {
-                line(false, "session permissions", err instanceof Error ? err.message : String(err));
+                record(false, "session permissions", err instanceof Error ? err.message : String(err));
                 failures++;
             }
         }
         try {
-            line(readSessionString(config).length > 0, "session readable");
+            record(readSessionString(config).length > 0, "session readable");
         }
         catch (err) {
-            line(false, "session readable", err instanceof Error ? err.message : String(err));
+            record(false, "session readable", err instanceof Error ? err.message : String(err));
             failures++;
         }
         try {
             const client = await getClient();
             const authorized = await client.isUserAuthorized();
-            line(authorized, "telegram authorized");
+            record(authorized, "telegram authorized");
             if (authorized) {
                 const me = (await client.getMe());
-                line(true, "account", `id=${String(me.id ?? "")} username=${me.username ?? "none"}`);
+                record(true, "account", `id=${String(me.id ?? "")} username=${me.username ?? "none"}`);
             }
             else {
                 failures++;
@@ -69,14 +85,48 @@ async function main() {
             await disconnect();
         }
         catch (err) {
-            line(false, "telegram connectivity", redact(err instanceof Error ? err.message : String(err)));
+            record(false, "telegram connectivity", redact(err instanceof Error ? err.message : String(err)));
             failures++;
         }
     }
-    process.stdout.write(failures === 0 ? "\nall checks passed.\n" : `\n${failures} check(s) failed.\n`);
+    report(failures);
     process.exit(failures === 0 ? 0 : 1);
 }
+function report(failures) {
+    const plain = !colorEnabled() || process.argv.includes("--quiet");
+    if (!plain) {
+        banner({ subtitle: "health check", compact: true });
+        gap();
+    }
+    const width = Math.max(...rows.map((r) => r.label.length));
+    for (const row of rows) {
+        if (plain) {
+            out(`[${row.pass ? "PASS" : "FAIL"}] ${row.label}${row.detail ? ` - ${row.detail}` : ""}\n`);
+        }
+        else {
+            const detail = row.detail ? `  ${theme.muted(row.detail)}` : "";
+            // padEnd measures code units; the icon is one glyph, so this aligns.
+            out(`  ${icon(row.pass)} ${theme.label(row.label.padEnd(width))}${detail}\n`);
+        }
+    }
+    if (failures === undefined)
+        return;
+    if (plain) {
+        out(failures === 0 ? "\nall checks passed.\n" : `\n${failures} check(s) failed.\n`);
+        return;
+    }
+    gap();
+    out(failures === 0
+        ? `  ${theme.success(`${sym.ok} ${paint.bold("all checks passed")}`)}\n`
+        : `  ${theme.fail(`${sym.fail} ${failures} check(s) failed`)}\n`);
+    if (failures !== 0 && hasHint()) {
+        out(`  ${theme.muted(`${sym.bullet} run ${paint.bold("telegram-mcp login")} to issue a fresh session`)}\n`);
+    }
+}
+function hasHint() {
+    return rows.some((r) => !r.pass && /session|authorized/i.test(r.label));
+}
 main().catch((err) => {
-    process.stderr.write(`[doctor] fatal: ${redact(err instanceof Error ? err.message : String(err))}\n`);
+    process.stderr.write(`${theme.fail(`[doctor] fatal: ${redact(err instanceof Error ? err.message : String(err))}`)}\n`);
     process.exit(1);
 });

package/dist/cli/login.js

@@ -15,6 +15,7 @@ import { TelegramClient } from "telegram";
 import { StringSession } from "telegram/sessions/index.js";
 import { ensureDirs, getConfig, hasSession, readSessionString, writeSessionString, redact, } from "../config.js";
 import { createLogger } from "../logger.js";
+import { banner, gap, hint, nextSteps, paint, spinner, step, success, sym, theme, warn } from "../ui.js";
 function ask(question) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     return new Promise((resolve) => rl.question(question, (answer) => {
@@ -22,6 +23,9 @@ function ask(question) {
         resolve(answer.trim());
     }));
 }
+function askPlain(question) {
+    return ask(`${theme.accent(`${sym.arrow} `)}${theme.label(question)} `);
+}
 /**
  * Ask a question without echoing the answer. readline's `terminal` mode masks
  * the prompt on POSIX and Windows alike; it falls back to a plain read when
@@ -57,6 +61,9 @@ function askSecret(question) {
 async function main() {
     const config = getConfig();
     ensureDirs(config);
+    banner({ subtitle: "interactive login", compact: true });
+    gap();
+    step(1, 3, "Checking the existing session");
     // Re-running login silently mints a NEW auth key for the same account. Telegram
     // then treats the previous key as AUTH_KEY_DUPLICATED and every client holding
     // it stops working. Refuse to overwrite a session that still works.
@@ -65,25 +72,35 @@ async function main() {
             connectionRetries: 2,
             baseLogger: createLogger(),
         });
+        const check = spinner("verifying the saved session");
         try {
             await probe.connect();
             const ok = await probe.isUserAuthorized();
             if (ok) {
                 const me = (await probe.getMe());
-                process.stderr.write(`[login] already authorized as ${me.username ?? String(me.id ?? "")} — nothing to do.\n` +
-                    `[login] session: ${config.sessionPath}\n` +
-                    `[login] pass --force to overwrite it with a fresh auth key.\n`);
+                check.stop(`${theme.success(sym.ok)} already authorized as ${theme.label(String(me.username ?? me.id ?? ""))}`);
+                gap();
+                hint(`session kept at ${config.sessionPath}`);
+                hint(`pass ${theme.label("--force")} to overwrite it with a fresh auth key`);
                 await probe.disconnect().catch(() => undefined);
                 return;
             }
+            check.stop(`${theme.warn(`${sym.warn} saved session is no longer authorized`)}`);
         }
         catch {
+            check.stop(`${theme.warn(`${sym.warn} saved session is unusable — issuing a fresh one`)}`);
             /* dead or duplicated session — fall through and replace it */
         }
         await probe.disconnect().catch(() => undefined);
-        process.stderr.write(`[login] existing session is unusable, issuing a fresh one\n`);
     }
-    process.stderr.write(`[login] session will be stored at ${config.sessionPath}\n`);
+    else {
+        hint(hasSession(config) ? `overwriting the session because of ${theme.label("--force")}` : "no session on disk yet");
+    }
+    gap();
+    step(2, 3, "Signing in to Telegram");
+    hint(`the session will be stored at ${config.sessionPath}`);
+    if (!process.stdin.isTTY)
+        hint(`stdin is not a terminal — prompts may not echo correctly`);
     const existing = hasSession(config) ? readSessionString(config) : "";
     const session = new StringSession(existing);
     const client = new TelegramClient(session, config.apiId, config.apiHash, {
@@ -97,28 +114,40 @@ async function main() {
             phoneNumber: async () => {
                 const stored = process.env.TELEGRAM_PHONE?.trim();
                 if (stored) {
-                    process.stderr.write(`[login] using phone from .env\n`);
+                    hint(`using ${theme.label("TELEGRAM_PHONE")} from .env`);
                     return stored;
                 }
-                return ask("Phone number (international, e.g. +15551234567): ");
+                return askPlain("Phone number (international, e.g. +15551234567)");
+            },
+            phoneCode: async () => {
+                hint("Telegram is sending a code to your other devices");
+                return askPlain("Login code");
+            },
+            password: async () => {
+                hint("two-step verification is on for this account");
+                return askSecret("2FA password (leave blank if none)");
             },
-            phoneCode: async () => ask("Login code from Telegram: "),
-            password: async () => askSecret("2FA password (leave blank if none)"),
             onError: (err) => {
                 // The update loop keeps pinging after we disconnect; those late
                 // rejections are noise, not auth failures.
                 const msg = err instanceof Error ? err.message : String(err);
                 if (msg === "TIMEOUT" || msg.includes("TIMEOUT"))
                     return;
-                process.stderr.write(`[login] auth error: ${redact(msg)}\n`);
+                warn(`auth error: ${redact(msg)}`);
             },
         });
         const me = (await client.getMe());
         const serialized = client.session.save();
         writeSessionString(config, serialized);
-        process.stderr.write(`[login] authorized as id=${String(me.id ?? "")} username=${me.username ?? "none"}\n`);
-        process.stderr.write(`[login] session saved to ${config.sessionPath}\n`);
-        process.stderr.write("[login] you can close this and start the MCP server.\n");
+        gap();
+        step(3, 3, "Saving");
+        success(`authorized as ${paint.bold(String(me.username ?? me.id ?? ""))}`);
+        hint(`session saved to ${config.sessionPath} ${theme.muted("(0600)")}`);
+        nextSteps([
+            `start your MCP client — it spawns ${theme.label("telegram-mcp")} from the config you already added`,
+            `or run ${theme.label("telegram-mcp doctor")} to confirm everything is healthy`,
+        ]);
+        gap();
     }
     finally {
         // gramJS fires the update-ping loop the moment we connect. Disconnecting
@@ -136,6 +165,9 @@ async function main() {
 }
 main().catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`[login] failed: ${redact(msg)}\n`);
+    process.stderr.write(`${theme.fail(`${sym.fail} login failed: ${redact(msg)}`)}\n`);
+    if (/not set|invalid/i.test(msg)) {
+        process.stderr.write(`  ${theme.muted(`${sym.bullet} get api_id/api_hash from `)}${theme.underline("https://my.telegram.org/apps")}\n`);
+    }
     process.exit(1);
 });