herdrchat 1.2.1 → 1.3.1

package/README.md

@@ -12,47 +12,111 @@ Every terminal hc runs, in the chat app you already use: Feishu or Telegram.
 
 </div>
 
-herdr-app has official phone and desktop apps. But to use them away from your desk, your
-phone has to reach the machine that runs hc, so you first need a VPN or a private network.
-And on a small phone screen, working with an agent is clumsy.
+[herdr](https://herdr.dev) runs your coding agents (Claude Code, codex, pi, …) in
+terminals that stay alive: **hc** (herdr-core) keeps them running, **herdr-app** shows
+them in spaces and tabs. herdr-app has phone and desktop apps, but your phone has to
+reach the machine that runs hc, so you first need a VPN or a private network, and working
+with an agent on a small phone screen is clumsy.
+
+herdrchat puts them in a chat app instead. It connects out to Feishu or Telegram by
+itself, so there is nothing to set up on your network: no public IP, no VPN. Each
+herdr-app tab gets its own Feishu group, or a topic in your private chat with the
+Telegram bot. You read what the agent says while it works, tap buttons to answer its
+questions, send and receive images, and see all terminals in one overview. A new group or
+topic starts with the conversation so far, and your phone rings only when an agent needs
+you or is done (on Feishu once you have sent `/auth` to the bot; on Telegram right away).
+
+Claude Code is mirrored fully. Other agents show their screen when you type to them,
+until herdrchat learns to read their conversations too.
+
+## You need
+
+- **hc** running on this machine, with at least one session ([herdr.dev](https://herdr.dev)).
+- **Node.js 20** or newer, on **macOS or Linux**.
+- **Feishu**: a Feishu team (not Lark) where you may create a custom app and publish it.
+  **Telegram**: a Telegram account. Use one app, or both at once.
+
+A few words used below: a **session** is one hc core (its terminals); a **space** and a
+**tab** are how herdr-app groups terminals; a **profile** is one herdrchat setup for one
+chat app (`default` unless you name another).
 
-Your chat app is already on your phone. herdrchat connects out to it by itself, so there
-is nothing to set up on your network: no public IP, no VPN. Each herdr-app tab becomes a
-Feishu group, or a topic in your private chat with the Telegram bot. You read what the
-agent says while it works, tap buttons to answer its questions, send and receive images,
-and see all terminals on one overview. A new room starts with the conversation so far.
-Your phone rings only when an agent needs you or is done. It works with any agent hc
-runs.
+## Install
 
-Use one app or both at once (a profile each). Slack and Discord may follow.
+```bash
+npm install -g herdrchat                    # the herdrchat command
+npx skills add zhangxiangliang/herdrchat    # optional: the skill, for your coding agent
+```
 
-## Install
+The skill teaches your coding agent (Claude Code, Codex, …) to set herdrchat up and look
+after it for you. When the `skills` tool asks Copy or Symlink, pick Symlink, so updates
+reach the agent.
+
+## Set up
+
+**With your agent:** ask it `/herdrchat setup`. It asks which chat app, then walks you
+through everything, clicking in the Feishu console for you when it can.
+
+**By hand:**
 
 ```bash
-npx skills add zhangxiangliang/herdrchat   # the skill, for your agent (pick Symlink)
-npm install -g herdrchat                   # the herdrchat command it runs
+herdrchat init --chat telegram   # or --chat feishu; it prints where the settings file is
+# fill in that file (each line says where its value comes from), then:
+herdrchat start                  # starts it and waits until it is connected
+herdrchat install                # once it works: start at login, come back after a crash
 ```
 
-Then ask your agent:
+The steps for each app (making the Feishu app, or the Telegram bot) are in the
+[guide](docs/guide.md#set-up-telegram).
+
+## Use
+
+In your chat app: type in a terminal's group or topic to talk to it; tap a card's buttons
+to answer a question. In the direct chat with the bot: `/ls` for the overview, `/new` to
+start a terminal, `/kill` to end one.
 
-| Command | What it does |
+| Ask your agent | What it does |
 |---|---|
 | `/herdrchat setup` | Sets everything up with you: the Feishu app or the Telegram bot, the settings, the first start. |
 | `/herdrchat status` | Says whether it runs, and what is wrong if anything is. |
 | `/herdrchat fix` | Finds the cause of a problem and fixes it. |
-| `/herdrchat config` | Changes a setting: which terminals, which groups stay quiet, tags. |
-| `/herdrchat feishu <task>` | Does a task in the Feishu developer console for you. |
+| `/herdrchat config` | Changes a setting: which terminals, which ones stay quiet, tags. |
+| `/herdrchat start`, `stop`, `install`, `logs`, `auth` | The same as the commands below, with checks first. |
+| `/herdrchat feishu <task>` | Does a task in the Feishu developer console (with the [Ego Lite](https://lite.ego.app/) browser, or step by step). |
 | `/herdrchat telegram <task>` | The Telegram bot, from @BotFather to the first topic. |
 
-On the command line, without an agent: `herdrchat init`, `start`, `stop`, `status`, `logs`;
-`herdrchat install` runs it as a service that starts at login and comes back after a
-crash. Add `--profile <name>` for a second chat app.
+On the command line: `herdrchat init`, `start`, `stop`, `status`, `logs`, `install`,
+`uninstall`, `version`; `herdrchat` alone lists them. Add `--profile <name>` to run a
+second chat app beside the first.
+
+## Update
+
+```bash
+npm install -g herdrchat@latest && npx skills add zhangxiangliang/herdrchat
+herdrchat start                  # for each profile: it keeps the old code until then
+```
 
 ## Where things are
 
 Settings in `~/.config/herdrchat/<profile>/config.env`, everything the bot writes in
-`~/.local/state/herdrchat/<profile>/` (the profile is `default` unless you name one).
-Updating or reinstalling herdrchat never touches them.
+`~/.local/state/herdrchat/<profile>/`. Updating or reinstalling herdrchat never touches
+them. `herdrchat status` prints both.
+
+## Privacy and safety
+
+- What your terminals show goes to Feishu's or Telegram's servers. Telegram bot chats are
+  not end-to-end encrypted.
+- Only the owner set in `config.env` can type into your terminals; everyone else is
+  ignored.
+- Keep the Feishu app secret or the Telegram bot token like a password: whoever has it
+  can drive your terminals.
+- On Feishu, the bot's tags are visible to your whole team (`HERDR_BOT_TAGS=off` turns
+  them off).
+
+## Remove
+
+`herdrchat uninstall` (for each profile), `npm rm -g herdrchat`, delete
+`~/.config/herdrchat` and `~/.local/state/herdrchat`, then delete the Feishu app or the
+Telegram bot (@BotFather, `/deletebot`).
 
 How it works and every setting: [docs/guide.md](docs/guide.md).
 

package/README.zh.md

@@ -12,42 +12,96 @@ hc 跑的每个终端，都能在你常用的聊天软件里看到和回复：
 
 </div>
 
-herdr-app 官方有手机端和电脑端。但想在外面用，手机得能连到跑 hc 的机器，
-所以要先折腾 VPN 或内网环境；而且在手机的小屏幕上和 agent 交互，体验并不好。
+[herdr](https://herdr.dev) 让你的编程 agent（Claude Code、codex、pi……）跑在不会断的终端里：
+**hc**（herdr-core）让它们一直跑着，**herdr-app** 按空间和标签页把它们展示出来。herdr-app 有手机端和电脑端，
+但手机得能连到跑 hc 的机器，所以要先折腾 VPN 或内网；而且在手机的小屏幕上和 agent 交互，体验并不好。
 
-聊天软件本来就在你手机上。herdrchat 自己主动连过去，网络上什么都不用配：不要公网 IP，也不要 VPN。
+herdrchat 把它们搬进聊天软件。它自己主动连到飞书或 Telegram，网络上什么都不用配：不要公网 IP，也不要 VPN。
 herdr-app 的每个标签页，在飞书里是一个群，在 Telegram 里是和 bot 私聊中的一个话题：
 agent 干活时说的话实时可见，它问你的问题点按钮就能回答，图片双向都能传，所有终端汇总在一张总览里。
-新开的群或话题会先补上之前的对话。只有 agent 需要你、或者做完的时候手机才会响。
-hc 能跑的 agent 都能用，我们自己用下来非常顺畅。
+新开的群或话题会先补上之前的对话；只有 agent 需要你、或者做完的时候手机才会响
+（飞书要先给 bot 发一次 `/auth`；Telegram 直接就是这样）。
 
-可以只用一个，也可以两个同时用（各开一个 profile）。后面有精力的话，也会考虑接入 Slack、Discord。
+目前 Claude Code 是完整同步的。其他 agent 在你给它发消息时会回一次屏幕内容，
+等 herdrchat 学会读它们的对话记录以后，也会完整同步。
+
+## 需要什么
+
+- 这台机器上在跑 **hc**，至少有一个 session（[herdr.dev](https://herdr.dev)）。
+- **Node.js 20** 或更新版本，系统是 **macOS 或 Linux**。
+- **飞书**：一个能创建并发布企业自建应用的飞书团队（暂不支持 Lark 国际版）。
+  **Telegram**：一个 Telegram 账号。可以只用一个，也可以两个同时用。
+
+下面会用到几个词：**session** 是一个 hc 核心（以及它的终端）；**空间**和**标签页**是 herdr-app 给终端分组的方式；
+**profile** 是 herdrchat 对一个聊天软件的一套配置（不指定就叫 `default`）。
 
 ## 安装
 
 ```bash
-npx skills add zhangxiangliang/herdrchat   # 给 agent 用的 skill（选 Symlink）
-npm install -g herdrchat                   # skill 要用到的 herdrchat 命令
+npm install -g herdrchat                    # herdrchat 命令
+npx skills add zhangxiangliang/herdrchat    # 可选：给编程 agent 用的 skill
+```
+
+skill 会教你的编程 agent（Claude Code、Codex……）替你配置和照看 herdrchat。
+`skills` 工具问你选 Copy 还是 Symlink 时，选 Symlink，以后更新才会同步给 agent。
+
+## 配置
+
+**让 agent 帮你：** 对它说 `/herdrchat setup`。它会先问你用哪个聊天软件，然后一步步带你配好，
+能自动点的飞书后台操作它会替你点。
+
+**自己动手：**
+
+```bash
+herdrchat init --chat telegram   # 或者 --chat feishu；它会告诉你配置文件在哪
+# 填好那个文件（每一行上面都写了值从哪来），然后：
+herdrchat start                  # 启动，并等到真的连上
+herdrchat install                # 跑通以后：装成系统服务，开机自动启动，崩溃自动重启
 ```
 
-然后对你的 agent 说：
+每个聊天软件的具体步骤（建飞书应用，或者建 Telegram bot）在[详细说明](docs/guide.md#set-up-telegram)里（英文）。
 
-| 命令 | 做什么 |
+## 使用
+
+在聊天软件里：在某个终端的群或话题里打字，就是在跟它说话；点卡片上的按钮回答它的问题。
+在和 bot 的私聊里：`/ls` 看总览，`/new` 启动一个终端，`/kill` 结束一个终端。
+
+| 对 agent 说 | 做什么 |
 |---|---|
 | `/herdrchat setup` | 和你一起从零配好：飞书应用或 Telegram bot、配置、第一次启动。 |
 | `/herdrchat status` | 告诉你它在不在跑，有问题的话问题在哪。 |
 | `/herdrchat fix` | 找出问题的原因并修好。 |
-| `/herdrchat config` | 改配置：接哪些终端、哪些群保持安静、标签。 |
-| `/herdrchat feishu <任务>` | 替你在飞书开发者后台完成操作。 |
+| `/herdrchat config` | 改配置：接哪些终端、哪些保持安静、标签。 |
+| `/herdrchat start`、`stop`、`install`、`logs`、`auth` | 和下面的命令一样，只是会先检查。 |
+| `/herdrchat feishu <任务>` | 替你在飞书开发者后台完成操作（用 [Ego Lite](https://lite.ego.app/) 浏览器，或者一步步带你点）。 |
 | `/herdrchat telegram <任务>` | Telegram bot：从 @BotFather 一直到第一个话题。 |
 
-不用 agent 也可以直接在命令行里用：`herdrchat init`、`start`、`stop`、`status`、`logs`；
-`herdrchat install` 把它装成系统服务，开机自动启动，崩溃后自动重启。第二个聊天软件加 `--profile <名字>`。
+命令行：`herdrchat init`、`start`、`stop`、`status`、`logs`、`install`、`uninstall`、`version`；
+只输入 `herdrchat` 会列出全部。加上 `--profile <名字>`，可以再开一个聊天软件。
+
+## 更新
+
+```bash
+npm install -g herdrchat@latest && npx skills add zhangxiangliang/herdrchat
+herdrchat start                  # 每个 profile 都要：在这之前它还跑着旧代码
+```
 
 ## 文件在哪
 
-配置在 `~/.config/herdrchat/<profile>/config.env`，bot 写的东西都在 `~/.local/state/herdrchat/<profile>/`（没指定 profile 时就是 `default`）。
-更新或重装 herdrchat 都不会动它们。
+配置在 `~/.config/herdrchat/<profile>/config.env`，bot 写的东西都在 `~/.local/state/herdrchat/<profile>/`。
+更新或重装 herdrchat 都不会动它们。`herdrchat status` 会把这两个位置都打印出来。
+
+## 隐私和安全
+
+- 终端里显示的内容会发到飞书或 Telegram 的服务器上。Telegram 的 bot 聊天不是端到端加密的。
+- 只有 `config.env` 里设置的 owner 能往你的终端里输入；其他人发的都会被忽略。
+- 飞书的 App Secret、Telegram 的 bot token 要像密码一样保管：谁拿到了，谁就能操作你的终端。
+- 飞书里 bot 打的标签，你整个团队都看得见（`HERDR_BOT_TAGS=off` 可以关掉）。
+
+## 卸载
+
+每个 profile 运行一次 `herdrchat uninstall`，然后 `npm rm -g herdrchat`，删掉 `~/.config/herdrchat`
+和 `~/.local/state/herdrchat`，最后删掉飞书应用或 Telegram bot（在 @BotFather 里用 `/deletebot`）。
 
 工作原理和全部配置：[docs/guide.md](docs/guide.md)（英文）。
 

package/bin/cli.mjs

@@ -9,8 +9,9 @@
 //     start      start (or restart) it: the service, or else its own hc terminal
 //     stop       stop it
 //     status     how it runs, its folders, sessions, its chat app, errors today
-//     logs       today's log (-n <lines>, --errors for ERROR and WARN only)
+//     logs       today's log (-n <lines>, --errors for ERROR and WARN only, --day <date>)
 //     run        run in the foreground (what start keeps running)
+//     version    which herdrchat this is
 //
 // The profile is --profile or HERDRCHAT_PROFILE (default "default"); where its files are
 // is in lib/core/config.mjs.
@@ -19,40 +20,97 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GUIDE = 'https://github.com/zhangxiangliang/herdrchat/blob/main/docs/guide.md';
 const USAGE = `herdrchat <command> [--profile <name>]
 
-  init       make the profile's config.env from the example when it is missing
-  install    run it as a service of the system: starts at login, back after a crash
-  uninstall  no service any more (it is stopped)
+  init       make the profile's config.env (--chat feishu|telegram picks the app)
   start      start (or restart) it: the service, or else its own hc terminal
   stop       stop it
   status     how it runs, its folders, sessions, its chat app, errors today
-  logs       today's log (-n <lines>, --errors for ERROR and WARN only)
-  run        run in the foreground (what start keeps running)`;
+  logs       today's log (-n <lines>, --errors for ERROR and WARN only, --day <date>)
+  install    run it as a service of the system: starts at login, back after a crash
+  uninstall  no service any more (it is stopped)
+  run        run in the foreground (what start keeps running)
+  version    which herdrchat this is
+
+First time: herdrchat init, fill in the file it names, then herdrchat start.
+A second chat app: add --profile <name> to every command.
+Environment: HERDRCHAT_PROFILE (same as --profile), HERDRCHAT_HOME (one folder for a
+profile's settings and state).
+Guide: ${GUIDE}`;
+
+// "herdrchat foo | head" closing the pipe is not an error
+process.stdout.on('error', (err) => { if (err.code === 'EPIPE') process.exit(0); throw err; });
+
+function fail(message, code = 2) {
+  console.error(message);
+  process.exit(code);
+}
 
 const argv = process.argv.slice(2);
-const flag = (name) => {
+const flag = (name, what) => {
   const i = argv.indexOf(name);
   if (i < 0) return undefined;
   const value = argv[i + 1];
+  if (value === undefined || value.startsWith('-')) fail(`${name} needs ${what}, for example ${name} ${name === '--profile' ? 'telegram' : name === '--chat' ? 'telegram' : name === '--day' ? '2026-01-31' : '100'}`);
   argv.splice(i, 2);
   return value;
 };
-const profile = flag('--profile');
-if (profile) process.env.HERDRCHAT_PROFILE = profile;
-const lines = Number(flag('-n') || 40);
+const profile = flag('--profile', 'a name');
+if (profile) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(profile)) fail(`Profile "${profile}": use letters, digits, - and _ only.`);
+  process.env.HERDRCHAT_PROFILE = profile;
+}
+const linesRaw = flag('-n', 'a number of lines');
+if (linesRaw !== undefined && !/^\d+$/.test(linesRaw)) fail('-n needs a number of lines, for example -n 100');
+const lines = Number(linesRaw || 40);
+const day = flag('--day', 'a date');
+if (day !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(day)) fail('--day needs a date as YYYY-MM-DD, for example --day 2026-01-31');
+const chatFlag = flag('--chat', 'feishu or telegram');
 const errorsOnly = argv.includes('--errors');
+const helpAsked = argv.some((a) => ['-h', '--help', 'help'].includes(a));
+const versionAsked = argv.some((a) => ['-v', '--version', 'version'].includes(a));
 const command = argv.find((a) => !a.startsWith('-'));
+if (versionAsked) {
+  console.log(JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version);
+  process.exit(0);
+}
+if (helpAsked || !command) {
+  console.log(USAGE);
+  process.exit(0);
+}
+if (process.env.HERDRCHAT_PROFILE && !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(process.env.HERDRCHAT_PROFILE)) fail(`HERDRCHAT_PROFILE "${process.env.HERDRCHAT_PROFILE}": use letters, digits, - and _ only.`);
 
 // after the profile is set: lib/core/config.mjs reads it when it loads
-const { CONFIG_FILE, STATE_DIR, loadConfig, makeDirs, placesOf } = await import('../lib/core/config.mjs');
-const { hc } = await import('../lib/core/hc.mjs');
+const { CONFIG_FILE, STATE_DIR, chatOf, loadConfig, makeDirs, placesOf } = await import('../lib/core/config.mjs');
+const { chatModule, chatNames } = await import('../lib/chats/index.mjs');
+const { coreUp, hc, sessionsHere } = await import('../lib/core/hc.mjs');
 const { serviceOf } = await import('../lib/core/service.mjs');
 const places = placesOf();
 
 const shellQuote = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
-const firstSession = () => loadConfig().sessions[0];
-const CONNECT_WAIT_MS = 30000;
+const again = profile || (places.profile !== 'default' ? places.profile : null) ? ` --profile ${places.profile}` : '';
+// the settings, or a plain word on what to do when there are none yet
+function config() {
+  if (!fs.existsSync(CONFIG_FILE)) fail(`No settings yet at ${CONFIG_FILE}.\nRun \`herdrchat init${again}\`, fill it in, then \`herdrchat start${again}\`.`, 1);
+  return loadConfig();
+}
+const firstSession = () => config().sessions[0];
+// the settings the bot needs to start, checked here so a missing key says so at once
+// instead of a bot that waits and fails
+function readyConfig() {
+  config();
+  const cfg = loadConfig({ requires: chatModule(chatOf()).requires || [] });
+  // a session not on this machine would be made by hc as the bot asks for it: a typo
+  const here = sessionsHere();
+  const unknown = cfg.sessions.filter((s) => !here.includes(s));
+  if (unknown.length) fail(`HERDR_SESSIONS in ${CONFIG_FILE} names ${unknown.join(', ')}, which ${unknown.length > 1 ? 'are' : 'is'} not an hc session on this machine.\nThe sessions here: ${here.join(', ') || 'none (start hc first)'}.`, 1);
+  return cfg;
+}
+// a day's log file: the local date, as the log names its files
+const today = () => { const d = new Date(); return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`; };
+const logFile = (date = today()) => path.join(STATE_DIR, 'logs', `${date}.log`);
+const CONNECT_WAIT_MS = 60000; // a first attempt that times out (15 s) is tried again
 
 // hc's full path, from HERDRCHAT_HC or PATH
 function findHc() {
@@ -71,7 +129,7 @@ function findHc() {
 // The bot runs in the first session listed; after that list changes, an older one may
 // still run in another, and two bots answer every message: it is stopped everywhere.
 async function stopEverywhere() {
-  for (const session of loadConfig().sessions) {
+  for (const session of config().sessions) {
     await hc(session, ['kill', places.terminal]).catch(() => {});
     await hc(session, ['rm', places.terminal]).catch(() => {});
   }
@@ -80,7 +138,7 @@ async function stopEverywhere() {
 // Started is not running: wait until today's log says the bot reached Feishu after
 // `since`, and hand back the errors it wrote meanwhile when it does not.
 async function waitConnected(since) {
-  const log = path.join(STATE_DIR, 'logs', `${new Date().toISOString().slice(0, 10)}.log`);
+  const log = logFile();
   const until = Date.now() + CONNECT_WAIT_MS;
   let errors = [];
   while (Date.now() < until) {
@@ -97,13 +155,13 @@ async function waitConnected(since) {
 // Nothing else, so no agent's variables come along.
 function botEnv() {
   const hcPath = findHc();
-  if (!hcPath) throw new Error('hc is not on PATH: install herdr-core first (https://herdr.app)');
+  if (!hcPath) throw new Error('hc is not on PATH: install herdr-core first (https://herdr.dev)');
   const env = { HERDRCHAT_HC: hcPath, HERDRCHAT_PROFILE: places.profile };
   for (const k of ['PATH', 'HERDRCHAT_HOME', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME']) if (process.env[k]) env[k] = process.env[k];
   return env;
 }
 
-const service = () => serviceOf({ profile: places.profile, root: ROOT, node: process.execPath, env: botEnv(), stateDir: STATE_DIR });
+const service = () => serviceOf({ profile: places.id, root: ROOT, node: process.execPath, env: botEnv(), stateDir: STATE_DIR });
 
 function failedToConnect(where, result) {
   console.error(`${where} but did not reach its chat app within ${CONNECT_WAIT_MS / 1000} s.`);
@@ -122,14 +180,17 @@ async function terminalState(session) {
 
 const commands = {
   init() {
+    const chatName = chatFlag || 'feishu';
+    if (!chatNames().includes(chatName)) fail(`--chat ${chatName}: the chat apps are ${chatNames().join(', ')}`);
     makeDirs();
     if (fs.existsSync(CONFIG_FILE)) {
-      console.log(`${CONFIG_FILE} is there already; edit it.`);
+      console.log(`${CONFIG_FILE} is there already; open it and edit it, then run \`herdrchat start${again}\`.`);
       return;
     }
-    fs.copyFileSync(path.join(ROOT, 'config.env.example'), CONFIG_FILE);
-    fs.chmodSync(CONFIG_FILE, 0o600);
-    console.log(`Made ${CONFIG_FILE}: fill in the app id, the secret and HERDR_SESSIONS.`);
+    const example = fs.readFileSync(path.join(ROOT, 'config.env.example'), 'utf8').replace(/^HERDRCHAT_CHAT=.*$/m, `HERDRCHAT_CHAT=${chatName}`);
+    fs.writeFileSync(CONFIG_FILE, example, { mode: 0o600 });
+    const keys = (chatModule(chatName).requires || []).join(', ');
+    console.log(`Made ${CONFIG_FILE} (only you can read it) for ${chatName}.\nOpen it and fill in ${keys} and HERDR_SESSIONS (the hc sessions to mirror), then run \`herdrchat start${again}\`.\nThe guide walks through it: ${GUIDE}`);
   },
 
   // The service file is written again each time (a moved node or hc is picked up), and
@@ -137,7 +198,7 @@ const commands = {
   async install() {
     const svc = service();
     if (!svc) throw new Error(`no launchd or systemd on ${process.platform}: run \`herdrchat start\` instead`);
-    loadConfig(); // a config that cannot start the bot fails here, not in the service
+    readyConfig(); // a config that cannot start the bot fails here, not in the service
     await stopEverywhere();
     svc.unload();
     svc.write(svc.content);
@@ -161,6 +222,7 @@ const commands = {
   },
 
   async start() {
+    readyConfig();
     await stopEverywhere();
     const svc = service();
     const since = new Date().toISOString();
@@ -190,25 +252,39 @@ const commands = {
   },
 
   async status() {
-    console.log(`profile   ${places.profile}`);
-    console.log(`settings  ${CONFIG_FILE}${fs.existsSync(CONFIG_FILE) ? '' : '  (missing: run `herdrchat init`)'}`);
+    console.log(`profile   ${places.profile}${places.id !== places.profile ? ` (named ${places.id} for its own folder)` : ''}`);
+    console.log(`settings  ${CONFIG_FILE}${fs.existsSync(CONFIG_FILE) ? '' : `  (none yet: run \`herdrchat init${again}\`)`}`);
     console.log(`state     ${STATE_DIR}`);
     if (!fs.existsSync(CONFIG_FILE)) return;
-    const cfg = loadConfig();
-    console.log(`sessions  ${cfg.sessions.join(', ')}`);
+    const cfg = loadConfig({ sessions: false }); // what is filled in so far, empty or not
+    const hcThere = Boolean(findHc());
+    // each session, and whether its hc core answers
+    const here = sessionsHere();
+    const sessionWords = [];
+    for (const session of cfg.sessions) {
+      if (!here.includes(session)) sessionWords.push(`${session} (no such session here; this machine has: ${here.join(', ') || 'none'})`);
+      else sessionWords.push(`${session} (${(await coreUp(session)) ? 'core up' : 'core not running'})`);
+    }
+    console.log(`sessions  ${sessionWords.join(', ') || 'none yet: set HERDR_SESSIONS (`ls ~/.local/state/herdr-core` lists them)'}`);
     // how it runs: the service, an hc terminal, or not at all
-    const svc = service();
-    const inTerminal = (await terminalState(cfg.sessions[0])) === 'live';
-    if (svc?.installed()) {
-      const st = svc.state();
-      console.log(`running   ${st.running ? `yes, as the ${svc.kind} service ${svc.name}${st.pid ? ` (pid ${st.pid})` : ''}` : `no: the ${svc.kind} service ${svc.name} is stopped (\`herdrchat start\`)`}`);
-      const gone = svc.nodeGone();
-      if (gone) console.log(`          the service runs ${gone}, which is gone (node moved): \`herdrchat install\` again`);
-      if (inTerminal) console.log(`          also in hc terminal ${places.terminal}: two bots; \`herdrchat start\` keeps one`);
+    const svc = hcThere ? service() : null;
+    if (!hcThere) {
+      console.log('running   unknown: hc is not on PATH (install herdr-core: https://herdr.dev)');
     } else {
-      console.log(`running   ${inTerminal ? `yes, in hc terminal ${places.terminal} (session ${cfg.sessions[0]}); \`herdrchat install\` makes it a service` : 'no (`herdrchat start`, or `herdrchat install` for a service)'}`);
+      const inTerminal = cfg.sessions.length ? (await terminalState(cfg.sessions[0])) === 'live' : false;
+      if (svc?.installed()) {
+        const st = svc.state();
+        console.log(`running   ${st.running ? `yes, as the ${svc.kind} service ${svc.name}${st.pid ? ` (pid ${st.pid})` : ''}` : `no: the ${svc.kind} service ${svc.name} is stopped (\`herdrchat start${again}\`)`}`);
+        const gone = svc.nodeGone();
+        if (gone) console.log(`          the service runs ${gone}, which is gone (node moved): \`herdrchat install${again}\` again`);
+        if (inTerminal) console.log(`          also in hc terminal ${places.terminal}: two bots; \`herdrchat start${again}\` keeps one`);
+      } else {
+        console.log(`running   ${inTerminal ? `yes, in hc terminal ${places.terminal} (session ${cfg.sessions[0]}); \`herdrchat install${again}\` makes it a service` : `no (\`herdrchat start${again}\`, or \`herdrchat install${again}\` for a service)`}`);
+      }
     }
     // what its chat app needs, without printing a secret
+    const set = (value, missing) => (value ? 'set' : missing);
+    const owner = 'not set: message the bot, it says what to put in config.env';
     console.log(`chat      ${cfg.chat}`);
     if (cfg.chat === 'feishu') {
       let token = null;
@@ -217,24 +293,26 @@ const commands = {
       } catch {
         // no /auth yet
       }
-      console.log(`owner     ${cfg.ownerOpenId ? 'set' : 'not set: message the bot, it says what to put in config.env'}`);
-      console.log(`/auth     ${!token ? 'not done (muting, labels and pins need it)' : (token.refreshUntil || 0) > Date.now() ? 'done' : 'expired: send /auth again'}`);
+      console.log(`app id    ${set(cfg.appId, 'missing: FEISHU_APP_ID, from the Feishu developer console')}`);
+      console.log(`secret    ${set(cfg.appSecret, 'missing: FEISHU_APP_SECRET, from the Feishu developer console')}`);
+      console.log(`owner     ${set(cfg.ownerOpenId, owner)}`);
+      console.log(`/auth     ${!token ? 'not done (muting, labels and pins need it: send /auth to the bot)' : (token.refreshUntil || 0) > Date.now() ? 'done' : 'expired: send /auth to the bot again'}`);
     } else if (cfg.chat === 'telegram') {
-      console.log(`token     ${cfg.env.TELEGRAM_BOT_TOKEN ? 'set' : 'missing: TELEGRAM_BOT_TOKEN from @BotFather'}`);
-      console.log(`owner     ${cfg.env.TELEGRAM_OWNER_ID ? 'set' : 'not set: message the bot, it says what to put in config.env'}`);
+      console.log(`token     ${set(cfg.env.TELEGRAM_BOT_TOKEN, 'missing: TELEGRAM_BOT_TOKEN, from @BotFather')}`);
+      console.log(`owner     ${set(cfg.env.TELEGRAM_OWNER_ID, owner)}`);
     }
-    const log = path.join(STATE_DIR, 'logs', `${new Date().toISOString().slice(0, 10)}.log`);
+    const log = logFile();
     if (fs.existsSync(log)) {
       const text = fs.readFileSync(log, 'utf8');
-      const count = (level) => (text.match(new RegExp(` ${level} `, 'g')) || []).length;
-      console.log(`today     ${count('ERROR')} errors, ${count('WARN')} warnings (herdrchat logs --errors)`);
+      const count = (level, word) => { const n = (text.match(new RegExp(` ${level} `, 'g')) || []).length; return `${n} ${word}${n === 1 ? '' : 's'}`; };
+      console.log(`today     ${count('ERROR', 'error')}, ${count('WARN', 'warning')} (herdrchat logs --errors${again})`);
     }
   },
 
   logs() {
-    const log = path.join(STATE_DIR, 'logs', `${new Date().toISOString().slice(0, 10)}.log`);
+    const log = logFile(day);
     if (!fs.existsSync(log)) {
-      console.log(`No log today (${log}).`);
+      console.log(`No log for ${day || 'today'} (${log}).${day ? '' : ' Older days: --day YYYY-MM-DD.'}`);
       return;
     }
     let out = fs.readFileSync(log, 'utf8').trimEnd().split('\n');
@@ -248,8 +326,9 @@ const commands = {
 };
 
 if (!commands[command]) {
-  console.log(USAGE);
-  process.exit(command ? 2 : 0);
+  console.error(`Unknown command: ${command}\n`);
+  console.error(USAGE);
+  process.exit(2);
 }
 try {
   await commands[command]();

package/bin/herdrchat.mjs

@@ -8,7 +8,7 @@ import path from 'node:path';
 import { STATE_DIR, chatOf, loadConfig, makeDirs, readState, writeState } from '../lib/core/config.mjs';
 import { createEngine } from '../lib/core/engine.mjs';
 import { followEvents } from '../lib/core/events.mjs';
-import { cores, getTerminal, hc, keys, machines, put, run, screenTail, send } from '../lib/core/hc.mjs';
+import { cores, getTerminal, hc, keys, machines, nameTab, put, run, screenTail, send } from '../lib/core/hc.mjs';
 import { createLog } from '../lib/core/log.mjs';
 import * as readers from '../lib/core/readers/index.mjs';
 import { chatModule, createChat } from '../lib/chats/index.mjs';
@@ -67,7 +67,7 @@ logger.capture({ onCrash: sayCrash });
 engine = createEngine({
   cfg,
   chat,
-  hc: { followEvents, cores, machines, getTerminal, screenTail, send, keys, put, run, kill: (session, address) => hc(session, ['kill', address]) },
+  hc: { followEvents, cores, machines, getTerminal, screenTail, send, keys, put, run, nameTab, kill: (session, address) => hc(session, ['kill', address]) },
   readers,
   store,
   log,

package/config.env.example

@@ -1,32 +1,49 @@
-# herdrchat settings, the example of config.env. `herdrchat init` copies it to where the
-# profile reads it (~/.config/herdrchat/default/config.env, ~/.config/herdrchat/<profile>/
-# with --profile, or HERDRCHAT_HOME), private; then fill it in.
+# herdrchat settings. `herdrchat init` copies this file to your profile's folder (only
+# you can read it there). Fill in what is empty above the line, then run
+# `herdrchat start`. Every setting is explained in docs/guide.md, "Settings".
+# A key set in the environment wins over this file.
 
-# the chat app this profile mirrors into: feishu (default) or telegram. To use both, run
-# one profile each (herdrchat start --profile telegram).
+# Which chat app: feishu or telegram. To use both, run one profile each
+# (`herdrchat init --profile telegram --chat telegram`).
 HERDRCHAT_CHAT=feishu
 
-# feishu
-FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
-FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# The hc sessions to mirror, comma-separated (machines they reach come along).
+# `ls ~/.local/state/herdr-core` lists the sessions on this machine.
+HERDR_SESSIONS=
+
+# --- Feishu only ---
+# From the Feishu developer console: your app's App ID and App Secret.
+FEISHU_APP_ID=
+FEISHU_APP_SECRET=
+# You. Leave it empty: message the bot once and it tells you the line to put here.
 FEISHU_OWNER_OPEN_ID=
 
-# telegram: the token from @BotFather (turn topic mode on there); your user id, which the
-# bot tells you when you message it
+# --- Telegram only ---
+# The token @BotFather gave you (turn on Threaded Mode in BotFather's mini app too).
 TELEGRAM_BOT_TOKEN=
+# You. Leave it empty: message the bot once and it tells you the line to put here.
 TELEGRAM_OWNER_ID=
 
-HERDR_SESSIONS=session-a,session-b
-# spaces whose rooms are quiet, so only "needs you" and "done" ring (Feishu: groups muted
-# once /auth is done; Telegram: silent posts): `all` (default), empty for none, or spaces,
-# comma-separated; elsewhere every post rings
+# ------------------------------------------------------------------------------------
+# The rest has good defaults; change it when you want to.
+
+# Quiet spaces: only "needs you" and "done" make a sound there.
+# Values: all (default), none (empty), or space names, comma-separated.
+# Feishu does this once you send /auth to the bot; Telegram does it right away.
 HERDR_MUTED_SPACES=all
-# spaces where nothing rings, not even "needs you": empty (default), `all`, or spaces
+
+# Fully silent spaces: nothing makes a sound there, not even "needs you".
+# Values: none (empty, default), all, or space names, comma-separated.
 HERDR_SILENT_SPACES=
-# the bot's tags next to group names (tenant tags): on (default) or off
+
+# What a new group or topic gets of the conversation before it:
+# file,folded (default: all of it as a file, its newest part in a folded post),
+# file, folded, or empty for nothing. /history posts both whenever you ask.
+HERDR_HISTORY=file,folded
+
+# (Feishu only) The bot's tags next to group names: the session or machine, and "ended".
+# They are visible to your whole Feishu team. on (default) or off.
 HERDR_BOT_TAGS=on
-# your sidebar labels, once /auth is done: on (default) or off
+
+# (Feishu only) Your own sidebar labels, once /auth is done. on (default) or off.
 HERDR_USER_TAGS=on
-# what a new room gets of the conversation before it: file,folded (default: all of it as a
-# file, the newest part in a folded post), file, folded, or empty for nothing
-HERDR_HISTORY=file,folded