herdrchat 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhangxiangliang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# herdrchat
+
+Every terminal hc runs, in the chat app you already use. Feishu first.
+
+[English](README.md) · [简体中文](README.zh.md)
+
+[![npm](https://img.shields.io/npm/v/herdrchat.svg)](https://www.npmjs.com/package/herdrchat)
+[![CI](https://github.com/zhangxiangliang/herdrchat/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangxiangliang/herdrchat/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/herdrchat.svg)](https://github.com/zhangxiangliang/herdrchat/blob/main/LICENSE)
+
+</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.
+
+Feishu is already on your phone. herdrchat connects out to Feishu by itself, so there is
+nothing to set up on your network: no public IP, no VPN. Each terminal becomes a Feishu
+group. 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 card. Your phone rings
+only when an agent needs you or is done. It works with any agent hc runs.
+
+Feishu comes first. When we have time, Slack, Discord and Telegram may follow.
+
+## Install
+
+```bash
+npx skills add zhangxiangliang/herdrchat   # the skill, for your agent (pick Symlink)
+npm install -g herdrchat                   # the herdrchat command it runs
+```
+
+Then ask your agent:
+
+| Command | What it does |
+|---|---|
+| `/herdrchat setup` | Sets everything up with you: the Feishu app, 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. |
+
+On the command line, without an agent: `herdrchat init`, `start`, `stop`, `status`, `logs`.
+
+## Where things are
+
+Settings in `~/.config/herdrchat/default/config.env`, everything the bot writes in
+`~/.local/state/herdrchat/default/`. Updating or reinstalling herdrchat never touches them.
+
+How it works and every setting: [docs/guide.md](docs/guide.md).
+
+## License
+
+MIT © [zhangxiangliang](https://github.com/zhangxiangliang)

package/README.zh.md

@@ -0,0 +1,53 @@
+<div align="center">
+
+# herdrchat
+
+hc 跑的每个终端，都能在你常用的聊天软件里看到和回复。先支持飞书。
+
+[English](README.md) · [简体中文](README.zh.md)
+
+[![npm](https://img.shields.io/npm/v/herdrchat.svg)](https://www.npmjs.com/package/herdrchat)
+[![CI](https://github.com/zhangxiangliang/herdrchat/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangxiangliang/herdrchat/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/herdrchat.svg)](https://github.com/zhangxiangliang/herdrchat/blob/main/LICENSE)
+
+</div>
+
+herdr-app 官方有手机端和电脑端。但想在外面用，手机得能连到跑 hc 的机器，
+所以要先折腾 VPN 或内网环境；而且在手机的小屏幕上和 agent 交互，体验并不好。
+
+飞书本来就在你手机上。herdrchat 自己主动连到飞书，网络上什么都不用配：不要公网 IP，也不要 VPN。
+每个终端就是一个飞书群：agent 干活时说的话实时可见，它问你的问题点按钮就能回答，
+图片双向都能传，所有终端汇总在一张总览卡片上。只有 agent 需要你、或者做完的时候手机才会响。
+hc 能跑的 agent 都能用，我们自己用下来非常顺畅。
+
+先支持飞书。后面有精力的话，也会考虑接入 Slack、Discord、Telegram 等其他聊天软件。
+
+## 安装
+
+```bash
+npx skills add zhangxiangliang/herdrchat   # 给 agent 用的 skill（选 Symlink）
+npm install -g herdrchat                   # skill 要用到的 herdrchat 命令
+```
+
+然后对你的 agent 说：
+
+| 命令 | 做什么 |
+|---|---|
+| `/herdrchat setup` | 和你一起从零配好：飞书应用、配置、第一次启动。 |
+| `/herdrchat status` | 告诉你它在不在跑，有问题的话问题在哪。 |
+| `/herdrchat fix` | 找出问题的原因并修好。 |
+| `/herdrchat config` | 改配置：接哪些终端、哪些群保持安静、标签。 |
+| `/herdrchat feishu <任务>` | 替你在飞书开发者后台完成操作。 |
+
+不用 agent 也可以直接在命令行里用：`herdrchat init`、`start`、`stop`、`status`、`logs`。
+
+## 文件在哪
+
+配置在 `~/.config/herdrchat/default/config.env`，bot 写的东西都在 `~/.local/state/herdrchat/default/`。
+更新或重装 herdrchat 都不会动它们。
+
+工作原理和全部配置：[docs/guide.md](docs/guide.md)（英文）。
+
+## 许可证
+
+MIT © [zhangxiangliang](https://github.com/zhangxiangliang)

package/bin/cli.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// herdrchat's command line: set up, start, stop and look at one profile.
+//
+//   herdrchat <command> [--profile <name>]
+//     init     make the profile's config.env from the example when it is missing
+//     start    start (or restart) it in its own hc terminal, kept running
+//     stop     stop it
+//     status   running or not, its folders, sessions, /auth, errors today
+//     logs     today's log (-n <lines>, --errors for ERROR and WARN only)
+//     run      run in the foreground (what start keeps running)
+//
+// The profile is --profile or HERDRCHAT_PROFILE (default "default"); where its files are
+// is in lib/config.mjs.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const USAGE = `herdrchat <command> [--profile <name>]
+
+  init     make the profile's config.env from the example when it is missing
+  start    start (or restart) it in its own hc terminal, kept running
+  stop     stop it
+  status   running or not, its folders, sessions, /auth, errors today
+  logs     today's log (-n <lines>, --errors for ERROR and WARN only)
+  run      run in the foreground (what start keeps running)`;
+
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const i = argv.indexOf(name);
+  if (i < 0) return undefined;
+  const value = argv[i + 1];
+  argv.splice(i, 2);
+  return value;
+};
+const profile = flag('--profile');
+if (profile) process.env.HERDRCHAT_PROFILE = profile;
+const lines = Number(flag('-n') || 40);
+const errorsOnly = argv.includes('--errors');
+const command = argv.find((a) => !a.startsWith('-'));
+
+// after the profile is set: lib/config.mjs reads it when it loads
+const { CONFIG_FILE, STATE_DIR, loadConfig, makeDirs, placesOf } = await import('../lib/config.mjs');
+const { hc } = await import('../lib/hc.mjs');
+const places = placesOf();
+
+const shellQuote = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+const firstSession = () => loadConfig().sessions[0];
+
+async function terminalState(session) {
+  try {
+    return JSON.parse(await hc(session, ['get', places.terminal, '--json'])).state;
+  } catch {
+    return null;
+  }
+}
+
+const commands = {
+  init() {
+    makeDirs();
+    if (fs.existsSync(CONFIG_FILE)) {
+      console.log(`${CONFIG_FILE} is there already; edit it.`);
+      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.`);
+  },
+
+  async start() {
+    const session = firstSession();
+    // hc starts a program with its own environment: the profile and folders go along
+    const env = ['HERDRCHAT_PROFILE', 'HERDRCHAT_HOME', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME']
+      .filter((k) => process.env[k])
+      .map((k) => `${k}=${shellQuote(process.env[k])}`)
+      .join(' ');
+    const run = `env ${env} ${shellQuote(process.execPath)} ${shellQuote(path.join(ROOT, 'bin', 'herdrchat.mjs'))}`;
+    const loop = `while true; do ${run}; echo 'herdrchat exited, restarting in 3 s'; sleep 3; done`;
+    await hc(session, ['kill', places.terminal]).catch(() => {});
+    await hc(session, ['rm', places.terminal]).catch(() => {});
+    await hc(session, ['run', '--bg', '--no-parent', '--name', places.terminal, '--cwd', ROOT, '--', 'sh', '-c', loop]);
+    console.log(`Started ${places.terminal} (profile ${places.profile}) in hc session ${session}.`);
+  },
+
+  async stop() {
+    const session = firstSession();
+    await hc(session, ['kill', places.terminal]).catch(() => {});
+    await hc(session, ['rm', places.terminal]).catch(() => {});
+    console.log(`Stopped ${places.terminal}.`);
+  },
+
+  async status() {
+    console.log(`profile   ${places.profile} (hc terminal ${places.terminal})`);
+    console.log(`settings  ${CONFIG_FILE}${fs.existsSync(CONFIG_FILE) ? '' : '  (missing: run `herdrchat init`)'}`);
+    console.log(`state     ${STATE_DIR}`);
+    if (!fs.existsSync(CONFIG_FILE)) return;
+    const cfg = loadConfig();
+    console.log(`sessions  ${cfg.sessions.join(', ')}`);
+    console.log(`running   ${(await terminalState(cfg.sessions[0])) === 'live' ? 'yes' : 'no (`herdrchat start`)'}`);
+    let token = null;
+    try {
+      token = JSON.parse(fs.readFileSync(path.join(STATE_DIR, 'user-token.json'), 'utf8'));
+    } catch {
+      // no /auth yet
+    }
+    console.log(`/auth     ${!token ? 'not done' : (token.refreshUntil || 0) > Date.now() ? 'done' : 'expired: send /auth again'}`);
+    const log = path.join(STATE_DIR, 'logs', `${new Date().toISOString().slice(0, 10)}.log`);
+    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)`);
+    }
+  },
+
+  logs() {
+    const log = path.join(STATE_DIR, 'logs', `${new Date().toISOString().slice(0, 10)}.log`);
+    if (!fs.existsSync(log)) {
+      console.log(`No log today (${log}).`);
+      return;
+    }
+    let out = fs.readFileSync(log, 'utf8').trimEnd().split('\n');
+    if (errorsOnly) out = out.filter((l) => / (ERROR|WARN) /.test(l));
+    console.log(out.slice(-lines).join('\n'));
+  },
+
+  async run() {
+    await import('./herdrchat.mjs');
+  },
+};
+
+if (!commands[command]) {
+  console.log(USAGE);
+  process.exit(command ? 2 : 0);
+}
+try {
+  await commands[command]();
+} catch (err) {
+  console.error(err.message);
+  process.exit(1);
+}