@dikacode/telegram-mcp 1.0.1 → 1.0.2

package/README.md

@@ -150,7 +150,7 @@ telegram-mcp
 }
 ```
 
-Pin a version if you want reproducible installs: `npx -y @dikacode/telegram-mcp@1.0.1`.
+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.1/dikacode-telegram-mcp-1.0.1.tgz
+npm install -g https://github.com/dikaglorya/telegram-mcp/releases/download/v1.0.2/dikacode-telegram-mcp-1.0.2.tgz
 telegram-mcp
 ```
 
@@ -188,13 +188,33 @@ npm fetches the repository, installs dependencies, runs the `prepare` build, and
 
 ## Updating
 
-How you installed it decides whether you have to do anything.
+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.1` (pinned) | **Never.** That is the point of pinning. |
-| `npm install -g @dikacode/telegram-mcp` | **Manual**, one command: `npm update -g @dikacode/telegram-mcp` |
+| `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. |
 
@@ -202,7 +222,8 @@ Check what you are running:
 
 ```bash
 telegram-mcp --version
-npm outdated -g @dikacode/telegram-mcp     # global installs only
+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
@@ -528,7 +549,8 @@ 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 the upgrade command it prints, or set `TELEGRAM_UPDATE_CHECK=0` if you pin versions on purpose. |
+| `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
@@ -565,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
@@ -592,7 +614,7 @@ The TypeScript is built with `tsc` to `dist/`. There is no bundler; the publishe
 
 ## Release
 
-**v1.0.1** is the current release, published to npm as
+**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.
@@ -602,6 +624,8 @@ The TypeScript is built with `tsc` to `dist/`. There is no bundler; the publishe
 - 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);
 });

package/dist/cli/update.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/**
+ * `telegram-mcp update` — bring the installed copy up to date.
+ *
+ * The hard part is not the upgrade, it is knowing *how* this copy was
+ * installed. A global npm install is upgraded with `npm i -g`, an npx run is
+ * replaced by asking npx for @latest, and a git checkout is updated with
+ * `git pull` plus a rebuild. Guessing wrong either does nothing (npm refuses
+ * to touch a package it does not own) or silently reinstalls the same version.
+ *
+ * So detection is made from the filesystem, not from a flag the user has to
+ * remember:
+ *   - the real path of this file lives under node_modules   -> npm package
+ *     - under a global prefix (`npm root -g`)               -> global install
+ *     - anywhere else (npx cache, local dep)                -> npx
+ *   - a sibling `.git` directory                            -> git checkout
+ *
+ * With `--check` nothing is installed; it only reports. That is what
+ * `telegram-mcp update --check` and the doctor use, and it never writes.
+ */
+import "../env.js";
+import { spawn, execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PACKAGE_NAME, SERVER_VERSION, compareVersions } from "../version.js";
+import { getUpdateInfo } from "../update-check.js";
+import { banner, gap, hint, info, sym, theme } from "../ui.js";
+const out = (text) => void process.stdout.write(text);
+/**
+ * Where npm puts globally installed packages. Asking npm is more reliable than
+ * reconstructing `process.execPath`, which differs between Homebrew, nvm,
+ * Volta and the Windows installer. `NPM_CONFIG_PREFIX` still applies, so a
+ * custom prefix is detected too.
+ */
+function npmGlobalRoot() {
+    try {
+        const root = execFileSync("npm", ["root", "-g"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 10_000,
+            shell: process.platform === "win32",
+        }).trim();
+        return root || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Candidates for the global prefix. `npm root -g` is authoritative, but it is
+ * skipped when npm is not on PATH (clients do strip it), and an explicit
+ * `npm i -g --prefix <dir>` is easy to miss. The real path of this file gives
+ * the answer either way: it ends in
+ *   <prefix>/lib/node_modules/<name>/dist/cli/update.js   (POSIX)
+ *   <prefix>/node_modules/<name>/dist/cli/update.js       (Windows)
+ */
+function globalRoots() {
+    const candidates = new Set();
+    const fromNpm = npmGlobalRoot();
+    if (fromNpm)
+        candidates.add(fromNpm);
+    const marker = process.platform === "win32" ? "/node_modules/" : "/lib/node_modules/";
+    const here = fileURLToPath(import.meta.url).replace(/\\/g, "/");
+    const at = here.lastIndexOf(marker);
+    if (at !== -1)
+        candidates.add(here.slice(0, at + marker.length - 1));
+    return [...candidates].map((dir) => path.resolve(dir)).filter((dir) => fs.existsSync(dir));
+}
+/** Walk up looking for a package root (a directory with package.json + .git or dist). */
+function findPackageRoot(start) {
+    let dir = start;
+    for (let i = 0; i < 6; i++) {
+        if (fs.existsSync(path.join(dir, "package.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+export function detectInstall() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const root = findPackageRoot(here) ?? here;
+    const normalized = root.replace(/\\/g, "/");
+    // A git checkout is the only layout that carries its own .git.
+    if (fs.existsSync(path.join(root, ".git"))) {
+        return { kind: "source", location: root };
+    }
+    if (/\/node_modules\//.test(`${normalized}/`)) {
+        const global = globalRoots().map((p) => p.replace(/\\/g, "/").replace(/\/+$/, ""));
+        if (global.some((g) => normalized === g || normalized.startsWith(`${g}/`))) {
+            return { kind: "global", location: root };
+        }
+        // Anything else under node_modules was put there by npx, or by a project
+        // that lists this package as a dependency, and both are refreshed by
+        // asking npm for @latest rather than by a -g install.
+        return { kind: "npx", location: root };
+    }
+    return { kind: "unknown", location: root };
+}
+export async function plan(allowNetwork = true) {
+    const { kind, location } = detectInstall();
+    const info = await getUpdateInfo({ allowNetwork });
+    const latest = info.source === "disabled" ? null : info.latest;
+    const outdated = latest !== null ? compareVersions(latest, SERVER_VERSION) > 0 : false;
+    const base = {
+        kind,
+        location,
+        current: SERVER_VERSION,
+        latest: latest ?? null,
+        outdated,
+    };
+    if (kind === "source") {
+        // A detached HEAD, a shallow clone or a checkout without an upstream all
+        // fail `pull --ff-only`. Ask git about the tracked upstream instead of
+        // assuming `origin/main` exists.
+        const upstream = git(location, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
+        if (!upstream) {
+            return {
+                ...base,
+                command: null,
+                note: "this checkout has no upstream branch; update it with `git pull` yourself, then npm install && npm run build",
+            };
+        }
+        return {
+            ...base,
+            command: ["git", "-C", location, "pull", "--ff-only"],
+            note: "then rebuild: npm install && npm run build",
+        };
+    }
+    if (kind === "global") {
+        // Respect a custom prefix: `npm i -g --prefix /opt/x` is a global install
+        // too, and upgrading it with a plain `npm i -g` would land in a different
+        // tree and leave the old copy in place.
+        const prefix = globalPrefix();
+        return {
+            ...base,
+            command: prefix
+                ? ["npm", "install", "-g", "--prefix", prefix, `${PACKAGE_NAME}@latest`]
+                : ["npm", "install", "-g", `${PACKAGE_NAME}@latest`],
+        };
+    }
+    if (kind === "npx") {
+        return {
+            ...base,
+            command: null,
+            note: `this copy was loaded from a node_modules folder; restart with \`npx -y ${PACKAGE_NAME}@latest\` and npx will fetch the newest release`,
+        };
+    }
+    return { ...base, command: null, note: "cannot tell how this copy was installed; use npm install -g @latest" };
+}
+/** Run git and return trimmed stdout, or null when it fails. Never throws. */
+function git(cwd, args) {
+    try {
+        const result = execFileSync("git", ["-C", cwd, ...args], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5_000,
+        }).trim();
+        return result || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The prefix a global install lives under, or null when it is the default one.
+ * Read from the resolved global root (`<prefix>/lib/node_modules` on POSIX,
+ * `<prefix>/node_modules` on Windows) so no extra npm call is needed.
+ */
+function globalPrefix() {
+    // Applies to the global root that contains the running copy: a custom
+    // prefix must be reused, or the upgrade would install next to it instead of
+    // over it.
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const normalized = here.replace(/\\/g, "/");
+    for (const root of globalRoots()) {
+        const g = root.replace(/\\/g, "/").replace(/\/+$/, "");
+        if (normalized.startsWith(`${g}/`)) {
+            return process.platform === "win32" ? path.dirname(root) : path.dirname(path.dirname(root));
+        }
+    }
+    return null;
+}
+function run(command) {
+    return new Promise((resolve) => {
+        const child = spawn(command[0], command.slice(1), {
+            stdio: "inherit",
+            shell: process.platform === "win32",
+        });
+        child.on("error", () => resolve(1));
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+function printPlan(p, checkOnly) {
+    const label = p.kind === "global"
+        ? "global npm package"
+        : p.kind === "npx"
+            ? "npx or project dependency"
+            : p.kind === "source"
+                ? "git checkout"
+                : "unknown";
+    out(`\n  ${theme.label("installed")}   ${theme.bold(p.current)}  ${theme.muted(p.location)}\n`);
+    out(`  ${theme.label("latest")}      ${p.latest ? theme.bold(p.latest) : theme.muted("unknown")}\n`);
+    out(`  ${theme.label("install")}     ${label}\n`);
+    if (p.latest === null) {
+        hint("could not reach the npm registry; check the network or TELEGRAM_UPDATE_CHECK");
+        return;
+    }
+    if (!p.outdated) {
+        out(`\n  ${theme.success(`${sym.ok} already up to date`)}\n\n`);
+        return;
+    }
+    out(`\n  ${theme.warn(`${sym.warn} ${theme.bold(`${p.current} -> ${p.latest}`)} available`)}\n`);
+    if (p.note)
+        hint(p.note);
+    if (checkOnly) {
+        if (p.command)
+            hint(`to upgrade, run ${theme.label(p.command.join(" "))}`);
+        hint("run without --check to apply it");
+        out("\n");
+        return;
+    }
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const checkOnly = argv.includes("--check") || argv.includes("--dry-run");
+    if (argv.includes("--help") || argv.includes("-h")) {
+        out([
+            "",
+            `  ${theme.bold("telegram-mcp update")}          upgrade this install to the latest release`,
+            `  ${theme.bold("telegram-mcp update --check")}  report only; install nothing`,
+            "",
+            "  The command is chosen from how this copy was installed:",
+            `    ${theme.accent("global install")}  npm install -g ${PACKAGE_NAME}@latest`,
+            `    ${theme.accent("npx run")}         restart with npx -y ${PACKAGE_NAME}@latest`,
+            `    ${theme.accent("git checkout")}    git pull --ff-only, then npm install && npm run build`,
+            "",
+        ].join("\n"));
+        return;
+    }
+    banner({ subtitle: "update", compact: true });
+    const p = await plan(true);
+    printPlan(p, checkOnly);
+    if (checkOnly || !p.outdated || !p.command) {
+        if (!checkOnly && p.outdated && !p.command && p.note) {
+            gap();
+            hint("nothing was installed; this copy is refreshed by the command above");
+            out("\n");
+        }
+        return;
+    }
+    info(`${theme.label("running")} ${p.command.join(" ")}`);
+    const code = await run(p.command);
+    if (code !== 0) {
+        out(`\n  ${theme.fail(`${sym.fail} update command exited with ${code}`)}\n\n`);
+        process.exitCode = code;
+        return;
+    }
+    if (p.kind === "source") {
+        info(`${theme.label("rebuilding")} npm install && npm run build`);
+        const install = await run(["npm", "install"]);
+        if (install === 0)
+            await run(["npm", "run", "build"]);
+    }
+    gap();
+    out(`  ${theme.success(`${sym.ok} updated to ${p.latest}`)}\n`);
+    hint("restart your MCP client so it spawns the new copy");
+    out("\n");
+}
+/**
+ * Only run when this file is the entrypoint. `detectInstall` is imported by the
+ * unit checks, and importing a module must not print a report or spawn npm.
+ */
+function invokedDirectly() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return path.resolve(entry) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    void main().catch((err) => {
+        process.stderr.write(`${theme.fail(`${sym.fail} update failed: ${err instanceof Error ? err.message : String(err)}`)}\n`);
+        process.exit(1);
+    });
+}

package/dist/index.js

@@ -12,65 +12,123 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { buildServer } from "./server.js";
 import { ensureDirs, getConfig, redact } from "./config.js";
 import { shutdownLogin } from "./login-tools.js";
-import { PACKAGE_NAME, SERVER_NAME, SERVER_VERSION } from "./version.js";
+import { PACKAGE_NAME, SERVER_VERSION } from "./version.js";
 import { warnIfOutdated } from "./update-check.js";
-const HELP = `${SERVER_NAME} ${SERVER_VERSION}
-
-An MCP server for a personal Telegram account, spoken over stdio.
-
-Usage:
-  telegram-mcp                 serve MCP on stdio (what an MCP client runs)
-  telegram-mcp --version, -v   print the version and exit
-  telegram-mcp --help, -h      print this help and exit
-
-Setup:
-  1. Get api_id and api_hash from https://my.telegram.org/apps
-  2. Provide them as TELEGRAM_API_ID / TELEGRAM_API_HASH, or let the agent call
-     telegram_setup
-  3. Log in with telegram_login_start (the agent can do this for you)
-
-Updating:
-  npx -y ${PACKAGE_NAME}@latest               # npx, always current
-  npm install -g ${PACKAGE_NAME}@latest       # global install
-
-Docs: https://github.com/dikaglorya/telegram-mcp
-`;
+import { banner, gap, hint, info, muted, sym, theme } from "./ui.js";
+function help() {
+    const rows = [
+        ["telegram-mcp", "serve MCP on stdio (what an MCP client runs)"],
+        ["telegram-mcp --version", "print the version and exit"],
+        ["telegram-mcp --help", "print this help and exit"],
+        ["telegram-mcp login", "log in from this terminal instead of chat"],
+        ["telegram-mcp doctor", "check config, session and connectivity"],
+        ["telegram-mcp update", "upgrade this install to the latest release"],
+        ["telegram-mcp update --check", "report the available version, install nothing"],
+    ];
+    const width = Math.max(...rows.map(([cmd]) => cmd.length));
+    const usage = rows
+        .map(([cmd, desc]) => `  ${theme.accent(cmd.padEnd(width))}  ${theme.muted(desc)}`)
+        .join("\n");
+    return [
+        `${theme.title("▀█▀ █▀▀ █░░ █▀▀ █▀▀ █▀█ ▄▀█ █▀▄▀█")}`,
+        `${theme.title("░█░ █▀▀ █░░ ██▄ █▄█ █▀▄ █▀█ █░▀░█")}  ${theme.muted(SERVER_VERSION)}`,
+        "",
+        theme.label("An MCP server for a personal Telegram account, over MTProto."),
+        "",
+        theme.bold("Usage"),
+        usage,
+        "",
+        theme.bold("Setup"),
+        `  ${theme.accent("1.")} Get api_id and api_hash from ${theme.underline("https://my.telegram.org/apps")}`,
+        `  ${theme.accent("2.")} Provide them as ${theme.label("TELEGRAM_API_ID")} / ${theme.label("TELEGRAM_API_HASH")},`,
+        `     or let the agent call ${theme.label("telegram_setup")}`,
+        `  ${theme.accent("3.")} Log in with ${theme.label("telegram_login_start")} (the agent can do it),`,
+        `     or run ${theme.label("telegram-mcp login")} in a terminal`,
+        "",
+        theme.bold("Updating"),
+        `  ${theme.accent("telegram-mcp update".padEnd(42))} ${theme.muted("detects how it was installed")}`,
+        `  ${theme.accent("telegram-mcp update --check".padEnd(42))} ${theme.muted("report only")}`,
+        `  ${theme.accent(`npx -y ${PACKAGE_NAME}@latest`.padEnd(42))} ${theme.muted("npx, always current")}`,
+        `  ${theme.accent(`npm install -g ${PACKAGE_NAME}@latest`.padEnd(42))} ${theme.muted("global install")}`,
+        "",
+        `${theme.muted("Docs")}  ${theme.underline("https://github.com/dikaglorya/telegram-mcp")}`,
+        "",
+    ].join("\n");
+}
+/** Subcommands that act like a CLI instead of serving stdio. */
+function dispatchSubcommand(argv) {
+    const command = argv[0];
+    if (command !== "login" && command !== "doctor" && command !== "update")
+        return false;
+    // Each module runs its own main() on import; they keep the same behaviour as
+    // `npm run login` and `npm run doctor`, just reachable from one binary.
+    const targets = {
+        login: "./cli/login.js",
+        doctor: "./cli/doctor.js",
+        update: "./cli/update.js",
+    };
+    const target = targets[command];
+    void import(target).catch((err) => {
+        process.stderr.write(`${theme.fail(`${sym.fail} cannot start ${command}: ${err instanceof Error ? err.message : String(err)}`)}\n`);
+        process.exit(1);
+    });
+    return true;
+}
+/** Handled before the transport is created, so stdout stays parseable. */
 function handleCliFlags(argv) {
-    const flags = new Set(argv.slice(2));
-    if (flags.has("--version") || flags.has("-v")) {
+    // Claude Desktop (and a few other clients) launch the server with
+    // `mcp-server-<name>` as an argument. That is not a subcommand, so anything
+    // unrecognised must fall through to serving rather than be interpreted.
+    const args = argv.slice(2).filter((a) => !/^mcp-server-/.test(a));
+    if (args.includes("--version") || args.includes("-v")) {
         process.stdout.write(`${SERVER_VERSION}\n`);
         return true;
     }
-    if (flags.has("--help") || flags.has("-h")) {
-        process.stdout.write(HELP);
+    if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
+        process.stdout.write(help());
         return true;
     }
-    return false;
+    return dispatchSubcommand(args);
+}
+function startupBanner(configured, allowAll, allowlist) {
+    if (configured) {
+        banner({ subtitle: "your Telegram account, as an MCP server", compact: true });
+        info(`${theme.success(sym.ok)} serving over stdio ${theme.muted(`(allowAll=${allowAll}, allowlist=${allowlist})`)}`);
+        return;
+    }
+    banner({ subtitle: "not configured yet", compact: true });
+    info(`${theme.warn(`${sym.warn} ${theme.bold("not configured")} — no api_id/api_hash yet`)}`);
+    hint(`get them from ${theme.underline("https://my.telegram.org/apps")}`);
+    hint(`then call ${theme.label("telegram_setup")} from chat, or run ${theme.label("telegram-mcp login")}`);
+    gap();
+    muted(`serving anyway — waiting for the agent`);
 }
 async function main() {
     // A missing .env must NOT be fatal: the user needs telegram_setup (and the
     // doctor) to be reachable so they can fix it from chat. Only a genuinely
     // broken server would exit here.
     let config = null;
+    let reason = "";
     try {
         config = getConfig();
         ensureDirs(config);
     }
     catch (err) {
-        process.stderr.write(`[telegram-mcp] not configured yet: ${err instanceof Error ? err.message : String(err)}\n` +
-            `[telegram-mcp] serving anyway — call telegram_setup to create .env, then telegram_login_start.\n`);
+        reason = redact(err instanceof Error ? err.message : String(err));
     }
     const server = buildServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(config
-        ? `[telegram-mcp] serving over stdio (allowAll=${config.allowAllChats}, allowlist=${config.allowlist.length})\n`
-        : `[telegram-mcp] serving over stdio (unconfigured — telegram_setup required)\n`);
+    startupBanner(Boolean(config), config?.allowAllChats ?? false, config?.allowlist.length ?? 0);
+    if (!config && reason) {
+        hint(theme.muted(reason.split(".")[0]));
+        hint(theme.muted("this server keeps running so the agent can call telegram_setup"));
+    }
     // After the transport is live, so a slow or unreachable registry can never
     // delay the first tool call.
     warnIfOutdated();
     const shutdown = async (signal) => {
-        process.stderr.write(`[telegram-mcp] ${signal}, shutting down\n`);
+        muted(`${signal}, shutting down`);
         try {
             // Drops any half-finished login socket too, not just the main client.
             await shutdownLogin();
@@ -85,7 +143,7 @@ async function main() {
 }
 if (!handleCliFlags(process.argv)) {
     main().catch((err) => {
-        process.stderr.write(`[telegram-mcp] fatal: ${redact(err instanceof Error ? err.stack ?? err.message : String(err))}\n`);
+        process.stderr.write(`${theme.fail(`${sym.fail} fatal: ${redact(err instanceof Error ? err.stack ?? err.message : String(err))}`)}\n`);
         process.exit(1);
     });
 }

package/dist/ui.js

@@ -0,0 +1,237 @@
+/**
+ * Terminal presentation: colour, symbols, a banner and small animations.
+ *
+ * Rules this module enforces, in order of importance:
+ *
+ *   1. **stdout is never touched.** Only stderr goes through here. stdout is the
+ *      MCP JSON-RPC channel, and a single ANSI escape sequence written there
+ *      corrupts the stream and gets the server dropped by the client.
+ *   2. **Degrade silently.** Colour needs a TTY, a terminal that is not dumb,
+ *      and no NO_COLOR. Piped output, CI logs and `npx ... > file` get plain
+ *      text with no escape codes at all.
+ *   3. **Animation is optional and cannot hang.** Every animation has a hard
+ *      time cap and is skipped when `TERM=dumb`, when stderr is not a TTY, when
+ *      the terminal is narrow, or when TELEGRAM_NO_ANIMATION is set.
+ *
+ * The exported surface is small on purpose: the rest of the codebase should not
+ * be threading `isTTY` checks through every message.
+ */
+import { SERVER_NAME, SERVER_VERSION } from "./version.js";
+/* ------------------------------------------------------------------ */
+/* Capability detection                                                */
+/* ------------------------------------------------------------------ */
+const isWindows = process.platform === "win32";
+function stderrIsTty() {
+    return Boolean(process.stderr.isTTY);
+}
+/**
+ * Colour support. `NO_COLOR` is the de-facto standard opt-out and takes
+ * priority over everything (https://no-color.org). `FORCE_COLOR` exists for the
+ * case where output is piped into a colour-aware pager.
+ */
+export function colorEnabled() {
+    if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "")
+        return false;
+    const forced = process.env.FORCE_COLOR;
+    if (forced !== undefined && forced !== "" && forced !== "0")
+        return true;
+    if (forced === "0")
+        return false;
+    if (!stderrIsTty())
+        return false;
+    if (process.env.TERM === "dumb")
+        return false;
+    // Windows Terminal and VS Code advertise themselves; plain conhost does not
+    // reliably handle SGR, so it stays plain unless FORCE_COLOR says otherwise.
+    if (isWindows && !process.env.WT_SESSION && !process.env.TERM_PROGRAM)
+        return false;
+    return true;
+}
+/** Whether the fancy stuff (banner frame, spinner) should run at all. */
+export function animationEnabled() {
+    if (process.env.TELEGRAM_NO_ANIMATION && process.env.TELEGRAM_NO_ANIMATION !== "0")
+        return false;
+    if (!stderrIsTty())
+        return false;
+    if (process.env.TERM === "dumb")
+        return false;
+    const columns = process.stderr.columns ?? 0;
+    if (columns > 0 && columns < 60)
+        return false;
+    return colorEnabled();
+}
+function sgr(open, close = 0) {
+    return (text) => (colorEnabled() ? `\u001b[${open}m${text}\u001b[${close}m` : text);
+}
+/** 256-colour foreground, falling back to cyan when colour is off. */
+function c256(code, fallback) {
+    return (text) => colorEnabled() ? `\u001b[38;5;${code}m${text}\u001b[0m` : `\u001b[${fallback}m${text}\u001b[0m`;
+}
+const basic = !process.env.TELEGRAM_256_COLORS;
+/**
+ * Low-level painters, for the rare call that needs one word emphasised inside a
+ * sentence. Prefer `theme` in new code; these are aliases kept small on purpose.
+ */
+export const paint = {
+    bold: sgr(1, 22),
+    dim: sgr(2, 22),
+    underline: sgr(4, 24),
+};
+/**
+ * The palette: cool cyan/teal for structure, warm accents for emphasis.
+ * Names are semantic (`success`, `fail`) so call sites read as intent.
+ */
+export const theme = {
+    bold: paint.bold,
+    dim: paint.dim,
+    underline: paint.underline,
+    border: basic ? sgr(90) : c256(244, 90),
+    title: basic ? sgr(96) : c256(51, 96),
+    label: basic ? sgr(97) : c256(252, 97),
+    accent: basic ? sgr(96) : c256(45, 96),
+    success: basic ? sgr(92) : c256(48, 92),
+    fail: basic ? sgr(91) : c256(203, 91),
+    warn: basic ? sgr(93) : c256(214, 93),
+    muted: basic ? sgr(90) : c256(242, 90),
+};
+/* ------------------------------------------------------------------ */
+/* Symbols                                                             */
+/* ------------------------------------------------------------------ */
+// Unicode box drawing and symbols are fine on every modern terminal, but
+// Windows conhost with a legacy code page mangles them, so ASCII is used there.
+const unicodeSymbols = !isWindows || Boolean(process.env.WT_SESSION);
+export const sym = {
+    ok: unicodeSymbols ? "✔" : "v",
+    fail: unicodeSymbols ? "✖" : "x",
+    warn: unicodeSymbols ? "▲" : "!",
+    arrow: unicodeSymbols ? "→" : "->",
+    bullet: unicodeSymbols ? "·" : "-",
+    bar: unicodeSymbols ? "│" : "|",
+    tl: unicodeSymbols ? "╭" : "+",
+    tr: unicodeSymbols ? "╮" : "+",
+    bl: unicodeSymbols ? "╰" : "+",
+    br: unicodeSymbols ? "╯" : "+",
+    h: unicodeSymbols ? "─" : "-",
+};
+/* ------------------------------------------------------------------ */
+/* Message helpers — stderr only                                       */
+/* ------------------------------------------------------------------ */
+function write(text) {
+    process.stderr.write(text);
+}
+/** The canonical diagnostic line. `[telegram-mcp] ...` stays greppable. */
+export function info(message) {
+    write(`${theme.title(`[${SERVER_NAME}]`)} ${message}\n`);
+}
+export function muted(message) {
+    write(`${theme.muted(`[${SERVER_NAME}]`)} ${message}\n`);
+}
+export function success(message) {
+    write(`${theme.success(sym.ok)} ${message}\n`);
+}
+export function warn(message) {
+    write(`${theme.warn(`${sym.warn} ${message}`)}\n`);
+}
+export function error(message) {
+    write(`${theme.fail(`${sym.fail} ${message}`)}\n`);
+}
+export function hint(message) {
+    write(`  ${theme.muted(`${sym.bullet} ${message}`)}\n`);
+}
+/** A blank line, but only when the terminal can afford it. */
+export function gap() {
+    if (animationEnabled())
+        write("\n");
+}
+/* ------------------------------------------------------------------ */
+/* Banner                                                              */
+/* ------------------------------------------------------------------ */
+/** Two-row block wordmark: readable at small widths, unlike a huge figlet. */
+const WORDMARK = [
+    "▀█▀ █▀▀ █░░ █▀▀ █▀▀ █▀█ ▄▀█ █▀▄▀█",
+    "░█░ █▀▀ █░░ ██▄ █▄█ █▀▄ █▀█ █░▀░█",
+];
+/**
+ * Print the banner. Deliberately quiet on repeated runs: the full frame is for
+ * CLI commands (login, doctor, --help), while a server start uses the compact
+ * form so an agent's log does not fill up with art.
+ */
+export function banner(opts = {}) {
+    const version = opts.version ?? SERVER_VERSION;
+    const subtitle = opts.subtitle ?? "your Telegram account, as an MCP server";
+    if (opts.compact || !animationEnabled()) {
+        write(`${theme.title(SERVER_NAME)} ${theme.muted(version)} ${theme.muted(sym.bullet)} ${theme.label(subtitle)}\n`);
+        return;
+    }
+    const width = Math.max(...WORDMARK.map((row) => [...row].length)) + 4;
+    write(`${theme.border(`${sym.tl}${sym.h.repeat(width)}${sym.tr}`)}\n`);
+    for (const row of WORDMARK)
+        write(`${theme.border(sym.bar)}  ${theme.title(row)}\n`);
+    write(`${theme.border(sym.bar)}  ${theme.muted(version)} ${theme.muted(sym.bullet)} ${theme.label(subtitle)}\n`);
+    write(`${theme.border(`${sym.bl}${sym.h.repeat(width)}${sym.br}`)}\n`);
+}
+/* ------------------------------------------------------------------ */
+/* Spinner                                                             */
+/* ------------------------------------------------------------------ */
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Redraw the current line in place. Only valid when animation is on. */
+function redraw(text) {
+    write(`\u001b[2K\r${text}`);
+}
+function clearLine() {
+    write("\u001b[2K\r");
+}
+/**
+ * A one-line spinner with a hard time cap, so a stuck network call cannot leave
+ * something spinning in a log forever. `stop()` erases the line and optionally
+ * replaces it with a final message.
+ */
+export function spinner(text, opts = {}) {
+    const maxMs = opts.maxMs ?? 6000;
+    if (!animationEnabled()) {
+        write(`${theme.muted(`${sym.bullet} ${text}`)}\n`);
+        return { stop: () => undefined };
+    }
+    let frame = 0;
+    const started = Date.now();
+    let stopped = false;
+    const stop = (final) => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+        clearLine();
+        if (final)
+            write(`${final}\n`);
+    };
+    const draw = () => redraw(`${theme.accent(FRAMES[frame++ % FRAMES.length])} ${text}`);
+    draw();
+    const timer = setInterval(() => {
+        if (Date.now() - started > maxMs) {
+            // Give up quietly: the caller still prints its own outcome line.
+            stop();
+            return;
+        }
+        draw();
+    }, 90);
+    // Never let the animation be the reason the process stays alive.
+    timer.unref?.();
+    return { stop };
+}
+/** A numbered step header, e.g. `[1/3] Connecting to Telegram`. */
+export function step(index, total, text) {
+    write(`${theme.accent(`[${theme.muted(`${index}/${total}`)}]`)} ${theme.bold(text)}\n`);
+}
+/**
+ * The three-step onboarding footer shown once credentials are written. It is
+ * the answer to "ok, and now what?" — the most common question after setup.
+ */
+export function nextSteps(steps) {
+    if (!steps.length)
+        return;
+    gap();
+    write(`${theme.label(theme.bold("Next"))}\n`);
+    steps.forEach((text, i) => {
+        write(`  ${theme.accent(String(i + 1))}${theme.muted(".")} ${text}\n`);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dikacode/telegram-mcp",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Local MCP server that connects CLI agents (OpenCode, Codex CLI, Claude Code, ...) to a personal Telegram account over MTProto.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "start": "node dist/index.js",
     "login": "tsx cli/login.ts",
     "doctor": "tsx cli/doctor.ts",
+    "preview": "node harness/preview.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "login:force": "tsx cli/login.ts --force",
     "test": "npm run build && node harness/unit.mjs",