kiro-telegram-bot 1.5.1

package/docs/INSTALL.md

@@ -0,0 +1,143 @@
+# 📦 Install guide
+
+Get the Kiro Telegram Bot running in a few minutes. Pick one of three ways:
+
+- **[Option A — npm (recommended)](#option-a--npm-recommended)** — one command,
+  global `kiro-tg` CLI, easiest to update.
+- **[Option B — 1-click installer](#option-b--1-click-installer)** — download a
+  release zip and double-click the installer.
+- **[Option C — manual / from source](#option-c--manual--from-source)** — clone
+  the repo (best for contributors).
+
+## Prerequisites
+
+- **Kiro CLI** installed and authenticated — run `kiro-cli chat` once to confirm.
+- **Node.js 20+**.
+- A **bot token** from [@BotFather](https://t.me/BotFather).
+- Your **Telegram user ID** from [@userinfobot](https://t.me/userinfobot).
+
+---
+
+## Option A — npm (recommended)
+
+Install the CLI once, globally. It ships with the `tsx` runtime, so there's no
+build step.
+
+```bash
+npm install -g kiro-telegram-bot
+```
+
+This gives you the **`kiro-tg`** command (alias: `kiro-telegram-bot`). Everything
+operates on the **current folder** — your `.env`, `logs/` and `data/` live there,
+so keep one folder per bot instance:
+
+```bash
+mkdir my-bot && cd my-bot       # a home for this bot's config + logs + data
+kiro-tg setup                   # auto-detects kiro-cli, writes ./.env
+#   (or pass values directly:  kiro-tg setup <BOT_TOKEN> <YOUR_USER_ID>)
+# edit .env: set TELEGRAM_BOT_TOKEN and ALLOWED_USERS
+kiro-tg run                     # run in the foreground (Ctrl-C to stop)
+```
+
+> ⚠️ **Set `ALLOWED_USERS`** in `.env` to your Telegram user ID(s). Empty means
+> *anyone* who finds the bot can run commands on your machine.
+
+### Startup options (`kiro-tg <command>`)
+
+| Command | What it does |
+|---|---|
+| `kiro-tg setup [token] [userId]` | Create/update `.env` in this folder (auto-detects `kiro-cli` + project roots). |
+| `kiro-tg run` | Run the bot in the foreground. |
+| `kiro-tg install` | Install + start a **24/7 background service** that autostarts on boot/login. |
+| `kiro-tg status` | Show install + running state of the service. |
+| `kiro-tg logs [n]` | Tail the last `n` log lines (default 100). |
+| `kiro-tg stop` / `restart` / `start` | Control the running service. |
+| `kiro-tg uninstall` | Stop + remove the background service. |
+| `kiro-tg help` | Show all commands. |
+
+The background service is **user-level** and auto-detected per platform — a
+hidden Scheduled Task on Windows, a `systemd` **user** service on Linux (with
+linger for boot-without-login), and a launchd **LaunchAgent** on macOS. It runs
+the bot bound to the folder you installed it from, so its `.env`/`logs`/`data`
+stay in that folder.
+
+Update later with `npm install -g kiro-telegram-bot@latest`.
+
+> **Try without installing:** `npx kiro-telegram-bot setup` then
+> `npx kiro-telegram-bot run` works too (slower first run).
+
+---
+
+## Option B — 1-click installer
+
+Every [release](https://github.com/artickc/kiro-telegram-bot/releases) ships a
+clean `kiro-telegram-bot-<version>.zip` (no `node_modules`, `.env`, logs or data)
+that contains the 1-click installers.
+
+1. **Download** the latest `kiro-telegram-bot-<version>.zip` and unzip it (or
+   `git clone` the repo).
+2. **Run the installer for your OS** from the unzipped folder. It installs
+   dependencies, auto-detects `kiro-cli`, writes `.env`, asks for your bot
+   token, and optionally sets up the 24/7 background service.
+
+   **Windows** — double-click `install.cmd`, or in a terminal:
+
+   ```powershell
+   .\install.cmd
+   ```
+
+   **Linux / macOS**:
+
+   ```bash
+   chmod +x install.sh && ./install.sh
+   ```
+
+3. **Set access control.** Open `.env` and set `ALLOWED_USERS` to your Telegram
+   user ID(s).
+
+---
+
+## Option C — manual / from source
+
+Best for contributors (run with auto-reload, no build step).
+
+```bash
+git clone https://github.com/artickc/kiro-telegram-bot.git
+cd kiro-telegram-bot
+npm install
+npm run setup            # auto-detects kiro-cli + project roots, writes .env
+# edit .env: set TELEGRAM_BOT_TOKEN and ALLOWED_USERS
+npm start                # or: npm run dev  (auto-reload)
+```
+
+Run it 24/7 as a background service:
+
+```bash
+npm run install:service     # install + start, enable autostart on boot/login
+npm run service -- status   # show install + running state
+npm run service -- logs 200 # tail the log file
+npm run uninstall:service   # stop + remove
+```
+
+No build step — TypeScript runs directly via `tsx`.
+
+---
+
+## Configuration
+
+All options live in `.env`. See the **Configuration** table in the
+[README](../README.md) for every variable and its default. By default the bot
+keeps `.env`, `logs/` and `data/` in the folder you run it from (override log
+location with `LOG_DIR` / `LOG_FILE` and data with `DATA_DIR`).
+
+## Troubleshooting
+
+- **Bot doesn't respond** — confirm your ID is in `ALLOWED_USERS` and the token
+  is correct; check `logs/kiro-telegram-bot.log` (run `kiro-tg logs`).
+- **`kiro-cli` not found** — set `KIRO_CLI_PATH` in `.env` to the binary's full
+  path.
+- **`kiro-tg: command not found`** — ensure your global npm bin dir is on `PATH`
+  (`npm bin -g`), or use `npx kiro-telegram-bot <command>`.
+- **"high volume of traffic" / transient errors** — the bot auto-retries with
+  backoff (6s → 60s) and shows the real error; switch model with the 🧩 menu or
+  `/model <id>` if a model stays busy.

package/docs/ops/RELEASE_CHECKLIST.md

@@ -0,0 +1,39 @@
+# Release checklist
+
+A release ships a **batch of merged pull requests** as one versioned tag. The
+heavy lifting (zip + notes + publish) is automated by
+`.github/workflows/release.yml`; this checklist covers the manual steps.
+
+## 1. Pre-flight (on `main`)
+
+- [ ] All intended PRs for this batch are **merged into `main`**.
+- [ ] `git checkout main && git pull` — local `main` matches origin.
+- [ ] `npm ci && npm run typecheck` passes with no errors.
+- [ ] Manual smoke test where relevant (`npm start`, basic Telegram round-trip).
+
+## 2. Changelog & version
+
+- [ ] Add a new `## [X.Y.Z] - YYYY-MM-DD` section to `CHANGELOG.md` with the
+      user-facing features/fixes (this becomes the GitHub Release notes).
+- [ ] Add the matching link reference at the bottom of `CHANGELOG.md`.
+- [ ] Choose the bump per SemVer: `patch` (fixes), `minor` (features),
+      `major` (breaking).
+
+## 3. Tag & publish
+
+```bash
+npm version minor          # bumps package.json, commits, creates the v* tag
+git push --follow-tags     # pushing the tag triggers the Release workflow
+```
+
+- [ ] Watch the **Release** workflow in the Actions tab finish green.
+- [ ] Confirm the GitHub Release exists with:
+  - [ ] the correct title (`vX.Y.Z`),
+  - [ ] notes matching the CHANGELOG section,
+  - [ ] the attached `kiro-telegram-bot-X.Y.Z.zip`,
+  - [ ] GitHub's auto-generated Source code archives.
+
+## 4. Post-release
+
+- [ ] Announce / update any docs that reference the version.
+- [ ] Open the next batch of feature branches off the new `main`.

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "kiro-telegram-bot",
+  "version": "1.5.1",
+  "description": "Control Kiro CLI from Telegram over the Agent Client Protocol (ACP). Switch projects, resume and attach to live coding sessions, stream responses with diffs, queue follow-ups, and run 24/7 as a cross-platform background service.",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "kiro-tg": "bin/kiro-tg.mjs",
+    "kiro-telegram-bot": "bin/kiro-tg.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "scripts",
+    "tsconfig.json",
+    ".env.example",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck",
+    "setup": "node scripts/setup.mjs",
+    "service": "tsx src/cli.ts",
+    "install:service": "tsx src/cli.ts install",
+    "uninstall:service": "tsx src/cli.ts uninstall",
+    "service:status": "tsx src/cli.ts status",
+    "service:logs": "tsx src/cli.ts logs"
+  },
+  "keywords": [
+    "kiro",
+    "kiro-cli",
+    "acp",
+    "agent-client-protocol",
+    "telegram",
+    "telegram-bot",
+    "ai-agent",
+    "ai-coding-assistant",
+    "mobile-coding",
+    "chatops",
+    "devtools",
+    "daemon",
+    "cross-platform",
+    "grammy"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/artickc/kiro-telegram-bot.git"
+  },
+  "homepage": "https://github.com/artickc/kiro-telegram-bot#readme",
+  "bugs": {
+    "url": "https://github.com/artickc/kiro-telegram-bot/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "diff": "^7.0.0",
+    "dotenv": "^16.4.7",
+    "grammy": "^1.30.0",
+    "tsx": "^4.19.2"
+  },
+  "devDependencies": {
+    "@types/diff": "^7.0.0",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  }
+}

package/scripts/mq.ts

@@ -0,0 +1,25 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+const kiro = join(homedir(),"AppData","Local","Kiro-Cli","kiro-cli.exe");
+function run(label:string, fn:(send:(m:string,p:any)=>void, getSid:()=>string)=>void, waitMs=5000): Promise<void> {
+  return new Promise((resolve)=>{
+    const p = spawn(kiro,["acp","--trust-all-tools"],{stdio:["pipe","pipe","pipe"]});
+    let buf=""; let id=0; const pend=new Map<number,string>(); let sid=""; let exited=false;
+    const send=(method:string,params:any)=>{ const i=++id; pend.set(i,method); try{p.stdin.write(JSON.stringify({jsonrpc:"2.0",id:i,method,params})+"\n");}catch{} };
+    p.on("exit",(c)=>{ exited=true; console.log(`  [${label}] PROCESS EXITED code=${c}`); });
+    p.stdout.setEncoding("utf8");
+    p.stdout.on("data",(c:string)=>{ buf+=c; let n; while((n=buf.indexOf("\n"))!==-1){ const line=buf.slice(0,n).trim(); buf=buf.slice(n+1); if(!line)continue; let m:any; try{m=JSON.parse(line)}catch{continue;}
+      if(m.id!==undefined && pend.has(m.id) && m.method===undefined){ const meth=pend.get(m.id)!; pend.delete(m.id); if(meth==="session/new"){ sid=m.result.sessionId; fn(send,()=>sid); } else if(meth!=="initialize"){ console.log(`  [${label}] ${meth} =>`, JSON.stringify(m.result??{error:m.error}).slice(0,500)); } }
+      else if(m.method && /model/i.test(JSON.stringify(m))){ console.log(`  [${label}] NOTIF ${m.method} =>`, JSON.stringify(m.params).slice(0,500)); }
+    }});
+    send("initialize",{protocolVersion:1,clientCapabilities:{fs:{readTextFile:true,writeTextFile:true},terminal:true},clientInfo:{name:"p",version:"1"}});
+    setTimeout(()=>send("session/new",{cwd:process.cwd(),mcpServers:[]}),600);
+    setTimeout(()=>{ if(!exited)p.kill(); resolve(); }, waitMs);
+  });
+}
+await run("REAL", (send,getSid)=> send("session/set_model",{sessionId:getSid(),modelId:"claude-opus-4.8"}));
+await run("INVALID", (send,getSid)=> send("session/set_model",{sessionId:getSid(),modelId:"nope-xyz-1"}));
+await run("EXEC", (send,getSid)=> send("_kiro.dev/commands/execute",{sessionId:getSid(),command:"/model"}), 5000);
+await run("OPTS", (send,getSid)=>{ send("_kiro.dev/commands/options",{sessionId:getSid(),commandName:"/model"}); send("_kiro.dev/commands/options",{sessionId:getSid(),name:"/model",arguments:""}); }, 5000);
+process.exit(0);

package/scripts/setup.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Easy setup: creates .env from .env.example, auto-detects the kiro-cli binary
+ * and sensible PROJECT_ROOTS, and optionally writes the bot token / user id
+ * passed as arguments:
+ *
+ *   node scripts/setup.mjs <TELEGRAM_BOT_TOKEN> [ALLOWED_USER_ID]
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+// .env lives in the instance dir (the user's folder); the template ships in the
+// package. For a cloned/zip checkout run in place these are the same folder.
+const instanceDir = process.env.KIRO_TG_CWD?.trim() || process.cwd();
+const envPath = join(instanceDir, ".env");
+const examplePath = join(root, ".env.example");
+
+const [, , tokenArg, userArg] = process.argv;
+
+function detectKiro() {
+  const candidates = [
+    join(homedir(), "AppData", "Local", "Kiro-Cli", "kiro-cli.exe"),
+    join(homedir(), ".local", "bin", "kiro-cli"),
+    "/usr/local/bin/kiro-cli",
+  ];
+  return candidates.find((p) => existsSync(p)) || "";
+}
+
+function detectRoots() {
+  const guesses = ["H:\\Lucru\\Domains", "C:\\Lucru\\Domains", join(homedir(), "projects")];
+  return guesses.filter((p) => existsSync(p));
+}
+
+let env = existsSync(envPath)
+  ? readFileSync(envPath, "utf-8")
+  : readFileSync(examplePath, "utf-8");
+
+function setVar(key, value) {
+  if (value === undefined || value === "") return;
+  const re = new RegExp(`^${key}=.*$`, "m");
+  const line = `${key}=${value}`;
+  env = re.test(env) ? env.replace(re, line) : `${env.trimEnd()}\n${line}\n`;
+}
+
+const kiro = detectKiro();
+if (kiro) {
+  setVar("KIRO_CLI_PATH", kiro);
+  console.log(`✓ Found kiro-cli: ${kiro}`);
+} else {
+  console.log("! kiro-cli not auto-detected — set KIRO_CLI_PATH in .env or ensure it's on PATH.");
+}
+
+const roots = detectRoots();
+if (roots.length) {
+  setVar("PROJECT_ROOTS", roots.join(","));
+  console.log(`✓ PROJECT_ROOTS: ${roots.join(", ")}`);
+}
+
+if (tokenArg) {
+  setVar("TELEGRAM_BOT_TOKEN", tokenArg);
+  console.log("✓ Wrote TELEGRAM_BOT_TOKEN");
+}
+if (userArg) {
+  setVar("ALLOWED_USERS", userArg);
+  console.log(`✓ Wrote ALLOWED_USERS=${userArg}`);
+}
+
+writeFileSync(envPath, env, "utf-8");
+console.log(`\n✓ .env written to ${envPath}`);
+
+if (!/^TELEGRAM_BOT_TOKEN=.+/m.test(env)) {
+  console.log("\nNext: open .env and paste your bot token from @BotFather, then run `kiro-tg run` (or `npm start`).");
+} else {
+  console.log("\nReady! Run `kiro-tg run` (or `npm start`).");
+}