@logicseek/hello-cc 0.1.0 → 0.1.2

package/bin/hcc.mjs

@@ -16,9 +16,10 @@ const _libDir = path.resolve(fileURLToPath(import.meta.url), '..', '..', 'lib');
 async function loadDiscover() { return import(path.join(_libDir, 'discover.mjs')); }
 async function loadSetup()    { return import(path.join(_libDir, 'setup.mjs')); }
 
-const VERSION = '0.1.0';
+const VERSION = '0.1.2';
 const PRODUCT_NAME = 'hello-cc';
 const CLI_NAME = 'hcc';
+const NPM_PACKAGE_NAME = '@logicseek/hello-cc';
 const DEFAULT_LOCK_TTL = 900;
 const ACTIVE_PEER_TTL = 600;
 // Directory under .hello-cc/ for optional external PTY buffer files.
@@ -128,6 +129,14 @@ function parseOpts(args, spec = {}) {
   return opts;
 }
 
+function wantsHelp(args) {
+  const stop = args.indexOf('--');
+  const scan = stop >= 0 ? args.slice(0, stop) : args;
+  const index = scan.findIndex((arg) => arg === '--help' || arg === '-h');
+  if (index < 0) return false;
+  return index <= 1 || !String(scan[index - 1] || '').startsWith('--');
+}
+
 function validateOpts(command, opts, allowed = []) {
   const allowedSet = new Set(['_', ...allowed]);
   for (const key of Object.keys(opts)) {
@@ -2289,7 +2298,7 @@ async function cmdPeers(ctx, args) {
 
 async function cmdTask(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpTask();
+  if (!sub || wantsHelp(args)) return helpTask();
   if (sub === 'create') return taskCreate(ctx, args.slice(1));
   if (sub === 'list') return taskList(ctx, args.slice(1));
   if (sub === 'claim') return taskClaim(ctx, args.slice(1));
@@ -2467,7 +2476,7 @@ async function taskDone(ctx, args) {
 
 async function cmdMsg(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpMsg();
+  if (!sub || wantsHelp(args)) return helpMsg();
   if (sub === 'send') return msgSend(ctx, args.slice(1));
   if (sub === 'inbox') return msgInbox(ctx, args.slice(1));
   if (sub === 'ack') return msgAck(ctx, args.slice(1));
@@ -2598,7 +2607,7 @@ async function cmdInject(ctx, args) {
 
 async function cmdPeer(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpPeer();
+  if (!sub || wantsHelp(args)) return helpPeer();
   if (sub === 'list') return peerList(ctx, args.slice(1));
   if (sub === 'start') return peerStart(ctx, args.slice(1));
   if (sub === 'attach') return peerAttach(ctx, args.slice(1));
@@ -2748,7 +2757,7 @@ async function peerStop(ctx, args) {
 
 async function cmdLock(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpLock();
+  if (!sub || wantsHelp(args)) return helpLock();
   if (sub === 'acquire') return lockAcquire(ctx, args.slice(1));
   if (sub === 'release') return lockRelease(ctx, args.slice(1));
   if (sub === 'renew') return lockRenew(ctx, args.slice(1));
@@ -2847,7 +2856,7 @@ async function lockList(ctx, args) {
 
 async function cmdHandoff(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpHandoff();
+  if (!sub || wantsHelp(args)) return helpHandoff();
   if (sub === 'create') return handoffCreate(ctx, args.slice(1));
   if (sub === 'list') return handoffList(ctx, args.slice(1));
   throw new CliError('BAD_ARGS', `Unknown handoff command: ${sub}`);
@@ -2900,7 +2909,7 @@ async function handoffList(ctx, args) {
 
 async function cmdEvent(ctx, args) {
   const sub = args[0];
-  if (!sub || sub === '--help' || sub === '-h') return helpEvent();
+  if (!sub || wantsHelp(args)) return helpEvent();
   if (sub === 'tail') return eventTail(ctx, args.slice(1));
   throw new CliError('BAD_ARGS', `Unknown event command: ${sub}`);
 }
@@ -4107,7 +4116,7 @@ function webIndexHtml() {
         // The server streams the tmux pane's raw output, so xterm renders
         // incrementally (no reset/redraw → no flicker) and the program's own
         // escape sequences carry the cursor.
-        if (msg.type === 'snapshot') { term.write(msg.data || '', () => { term.scrollToBottom(); }); }
+        if (msg.type === 'snapshot') { term.reset(); term.write(msg.data || '', () => { term.scrollToBottom(); }); }
         if (msg.type === 'data') { term.write(msg.data || '', pinned ? () => { term.scrollToBottom(); } : undefined); }
         if (msg.type === 'replace') { term.reset(); term.write(msg.data || '', pinned ? () => { term.scrollToBottom(); } : undefined); }
         if (msg.type === 'exit') { refreshSessions().catch(console.error); }
@@ -4535,6 +4544,30 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       (payload.visible ? '[?25h' : '[?25l');
   }
 
+  function tmuxSnapshot(session) {
+    const captured = tmuxCapturePane(session.pane);
+    return captured + cursorEscape(tmuxCursorPayload(captured, tmuxCursorInfo(session.pane)));
+  }
+
+  function refreshTmuxSnapshot(session) {
+    if (session.type !== 'tmux' || !session.pane) return session.buffer || '';
+    try {
+      session.buffer = tmuxSnapshot(session);
+    } catch {
+      // Keep the previous buffer if the pane disappears during capture.
+    }
+    return session.buffer || '';
+  }
+
+  function scheduleTmuxReplace(session) {
+    if (session.type !== 'tmux' || !session.pane) return;
+    if (session.replaceTimer) clearTimeout(session.replaceTimer);
+    session.replaceTimer = setTimeout(() => {
+      session.replaceTimer = null;
+      broadcast(session, { type: 'replace', data: refreshTmuxSnapshot(session) });
+    }, 80);
+  }
+
   // Stream the tmux pane's RAW output (escape sequences and all) into the
   // browser via `tmux pipe-pane`, so xterm.js renders incrementally — no
   // screenshot-poll, no full-screen reset, no flicker — and the program's own
@@ -4547,8 +4580,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     // Capture the existing screen once for the initial paint; pipe-pane only
     // forwards output produced after it is enabled.
     try {
-      const captured = tmuxCapturePane(session.pane);
-      session.buffer = captured + cursorEscape(tmuxCursorPayload(captured, tmuxCursorInfo(session.pane)));
+      session.buffer = tmuxSnapshot(session);
     } catch {}
 
     // Use a FIFO rather than an append-only regular file. The old file-backed
@@ -4612,6 +4644,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
 
   function stopTmuxStream(session) {
     if (session.streamPoller) { clearInterval(session.streamPoller); session.streamPoller = null; }
+    if (session.replaceTimer) { clearTimeout(session.replaceTimer); session.replaceTimer = null; }
     // Turn piping back off for this pane (no command toggles it off).
     try { runTmux(['pipe-pane', '-t', session.pane]); } catch {}
     if (session.streamFd !== null && session.streamFd !== undefined) {
@@ -5202,7 +5235,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     }
     wss.handleUpgrade(req, socket, head, (ws) => {
       session.clients.add(ws);
-      ws.send(JSON.stringify({ type: 'snapshot', data: session.buffer }));
+      ws.send(JSON.stringify({ type: 'snapshot', data: refreshTmuxSnapshot(session) }));
       ws.on('message', (raw) => {
         try {
           const msg = JSON.parse(String(raw));
@@ -5213,6 +5246,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
             const cols = Math.max(20, Number.parseInt(msg.cols || 100, 10));
             const rows = Math.max(8, Number.parseInt(msg.rows || 30, 10));
             resizeSession(session, cols, rows);
+            scheduleTmuxReplace(session);
           }
         } catch {
           // Ignore malformed terminal frames.
@@ -5514,6 +5548,8 @@ Commands:
   web                          Start coordination, shims, tmux, and browser console
   up                           Initialize local coordination only
   down                         Stop the running hello-cc web runtime
+  update                       Update the global npm install of hello-cc
+  uninstall                    Remove hooks, shims, and optional project data
   init                         Initialize .hello-cc/mesh.db and guidance
   register --peer ID           Register or update a peer session identity
   join --peer ID               Register this shell and print eval-able env
@@ -5755,6 +5791,24 @@ Stops the web runtime started by hcc web for this project.
 `);
 }
 
+function helpUpdate() {
+  console.log(`${CLI_NAME} update
+
+Usage:
+  ${CLI_NAME} update [--tag TAG] [--registry URL] [--dry-run]
+
+Examples:
+  ${CLI_NAME} update
+  ${CLI_NAME} update --tag latest
+  ${CLI_NAME} update --dry-run
+
+Updates the global npm install by running:
+  npm install -g ${NPM_PACKAGE_NAME}@TAG
+
+The default TAG is latest.
+`);
+}
+
 function helpWeb() {
   console.log(`${CLI_NAME} web
 
@@ -6078,6 +6132,46 @@ async function cmdSetup(ctx, args) {
   log('\nDone. Run `hcc web` for the default coordinated terminal experience.');
 }
 
+// ─── hcc update ──────────────────────────────────────────────────────────────
+
+async function cmdUpdate(ctx, args) {
+  if (args[0] === '--help' || args[0] === '-h') return helpUpdate();
+
+  const opts = parseOpts(args, { booleans: ['dry-run'] });
+  validateOpts('update', opts, ['tag', 'registry', 'dry-run']);
+  const tag = opts.tag || 'latest';
+  if (!/^[A-Za-z0-9._+-]+$/.test(tag)) {
+    throw new CliError('BAD_ARGS', '--tag must be an npm dist-tag or version');
+  }
+
+  const packageSpec = `${NPM_PACKAGE_NAME}@${tag}`;
+  const npmArgs = ['install', '-g', packageSpec];
+  if (opts.registry) npmArgs.push('--registry', opts.registry);
+  const command = shellCommand(['npm', ...npmArgs]);
+  const data = { package: NPM_PACKAGE_NAME, tag, registry: opts.registry || null, command, dry_run: Boolean(opts['dry-run']) };
+
+  if (opts['dry-run']) {
+    printResult(ctx, data, () => `would run: ${command}`);
+    return;
+  }
+
+  const result = spawnSync('npm', npmArgs, {
+    encoding: ctx.json ? 'utf8' : undefined,
+    stdio: ctx.json ? ['ignore', 'pipe', 'pipe'] : 'inherit'
+  });
+  if (result.error) {
+    throw new CliError('UPDATE_FAILED', `npm update command failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const output = ctx.json
+      ? [result.stdout, result.stderr].filter(Boolean).join('\n').trim()
+      : '';
+    throw new CliError('UPDATE_FAILED', output || `npm exited with status ${result.status}`);
+  }
+
+  printResult(ctx, data, () => `updated ${packageSpec}`);
+}
+
 // ─── hcc uninstall ───────────────────────────────────────────────────────────
 
 async function cmdUninstall(ctx, args) {
@@ -6301,6 +6395,7 @@ async function dispatch(ctx, rest) {
   if (command === '--version' || command === 'version') return console.log(VERSION);
   if (command === 'up') return cmdUp(ctx, args);
   if (command === 'down') return cmdDown(ctx, args);
+  if (command === 'update') return cmdUpdate(ctx, args);
   if (command === 'uninstall') return cmdUninstall(ctx, args);
   if (command === 'init') return cmdInit(ctx, args);
   if (command === 'register') return cmdRegister(ctx, args);

package/docs/README.md

@@ -0,0 +1,22 @@
+# hello-cc Documentation
+
+Start with the [project README](../README.md) when you only need the project
+summary and first command. Use these docs when you need more detail.
+
+## User Docs
+
+- [User Guide](guide.md): install, start, Web console, coordination semantics,
+  workflow, stable peer identity, and environment behavior.
+- [Command Reference](commands.md): compact list of public commands and the
+  intended use of each command group.
+- [Changelog](../CHANGELOG.md): release notes for published versions.
+- Release notes: run `npm run release:check` before publishing, and use
+  `npm run release:notes` to print the current changelog section for GitHub
+  Release notes.
+
+## Design And Implementation
+
+- [Design Notes](design.md): product boundary, project boundary, capability
+  levels, coordination semantics, and provider-session binding.
+- [Implementation Notes](implementation.md): architecture, protocol, command
+  surface, stack, shim behavior, and implementation plan.

package/docs/README.zh-CN.md

@@ -0,0 +1,22 @@
+# hello-cc 文档
+
+只需要项目简介和第一条命令时，先看[仓库 README](../README.zh-CN.md)。
+需要更多细节时，再看下面的文档。
+
+## 用户文档
+
+- [用户指南](guide.zh-CN.md)：安装、启动、Web 控制台、协作语义、工作流、稳定
+  peer 身份和环境变量行为。
+- [命令参考](commands.zh-CN.md)：公共命令的紧凑清单，以及每组命令的用途。
+- [更新日志](../CHANGELOG.md)：已发布版本的 release notes。
+- 发行说明：发布前运行 `npm run release:check`，用
+  `npm run release:notes` 输出当前版本的 changelog 小节，作为 GitHub
+  Release 描述。
+
+## 设计和实现
+
+- [设计说明](design.md)：产品边界、项目边界、能力层级、协作语义和 provider
+  session 绑定。
+- [实现说明](implementation.md)：架构、协议、命令面、技术栈、shim 行为和实现计划。
+
+设计和实现文档目前只有英文版。

package/docs/commands.md

@@ -0,0 +1,104 @@
+# hello-cc Command Reference
+
+Use `hcc --help` for the current top-level command list. Most subcommands also
+accept `--help`, for example `hcc update --help`, `hcc peer --help`, and
+`hcc task --help`.
+
+## Install Maintenance
+
+```text
+hcc update [--tag TAG] [--registry URL] [--dry-run]
+hcc uninstall [--purge --yes]
+```
+
+`hcc update` updates the global npm install. `hcc uninstall` removes local
+hooks and shims; add `--purge --yes` only when you also want to remove the
+current project's `.hello-cc` data and guidance blocks.
+
+## Start And Stop
+
+```text
+hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-discover] [--no-guidance]
+hcc down
+hcc up [--no-discover] [--no-guidance]
+```
+
+`hcc web` is the default entry. It initializes coordination, installs hooks and
+shims, starts or reuses the Web console, and returns the terminal to you. Use
+`hcc up` only when you want coordination without the Web console or shims.
+
+## Peers And Status
+
+```text
+hcc peers
+hcc status [--peer ID]
+hcc scan [--register]
+hcc prompt --peer ID [--kind codex|claude|shell|other] [--role ROLE]
+hcc join --peer ID [--kind codex|claude|shell|other] [--role ROLE]
+hcc env --peer ID
+hcc heartbeat [--peer ID] [--renew-locks --ttl 900]
+hcc run --peer ID --kind codex|claude|shell --role ROLE -- COMMAND [ARGS...]
+```
+
+Use these commands to inspect live project state, register terminals, and run a
+CLI with `HCC_PEER`, `HCC_ROOT`, and `HCC_DB` set.
+
+## Browser-Controllable Terminals
+
+```text
+hcc peer list
+hcc peer start PEER [--kind K] [--role R] [--cwd DIR] [--restart-env] -- COMMAND [ARGS...]
+hcc peer start PEER --kind codex --resume SESSION_ID [--restart-env]
+hcc peer start PEER --kind codex --last
+hcc peer start PEER --kind claude --resume SESSION_ID [--restart-env]
+hcc peer start PEER --kind claude --continue
+hcc peer attach PEER [--pane PANE] [--kind K] [--role R] [--cwd DIR]
+hcc peer stop PEER
+hcc inject PEER TEXT [--no-enter]
+```
+
+These commands create or attach tmux-backed terminals that can be viewed and
+controlled from the Web console.
+
+## Messages
+
+```text
+hcc msg send [--from ID] [--to ID|all] --body TEXT [--task N] [--kind note|task|handoff]
+hcc msg inbox [--peer ID] [--wait SEC] [--all] [--limit N]
+hcc msg ack [--peer ID] --id N
+hcc ask PEER MESSAGE [--from ID] [--task N] [--inject]
+hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
+```
+
+Messages are addressed mailbox items. `ask` and `broadcast` also support live
+terminal injection with `--inject`.
+
+## Tasks
+
+```text
+hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
+hcc task list [--status S] [--peer ID] [--all]
+hcc task claim [--peer ID] --id N
+hcc task next [--peer ID]
+hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
+hcc task done [--peer ID] --id N --summary TEXT
+```
+
+Tasks are shared project facts. They remain visible until marked `done` or
+`abandoned`.
+
+## Locks, Handoffs, And Events
+
+```text
+hcc lock acquire [--peer ID] --resource PATH [--task N] [--ttl SEC] [--reason TEXT]
+hcc lock renew [--peer ID] --resource PATH [--ttl SEC]
+hcc lock release [--peer ID] --resource PATH [--force]
+hcc lock list [--all]
+hcc handoff create [--from ID] --summary TEXT [--task N] [--to ID] [--changed-files JSON_OR_CSV] [--tests TEXT] [--risks TEXT]
+hcc handoff list [--task N] [--limit N]
+hcc event tail [--limit N]
+hcc gc [--older-than DAYS] [--yes]
+```
+
+Locks are advisory coordination locks with TTLs. Handoffs preserve the result,
+tests, changed files, and remaining risks when work moves between peers.

package/docs/commands.zh-CN.md

@@ -0,0 +1,101 @@
+# hello-cc 命令参考
+
+使用 `hcc --help` 查看当前顶层命令列表。大多数子命令也支持 `--help`，
+例如 `hcc update --help`、`hcc peer --help` 和 `hcc task --help`。
+
+## 安装维护
+
+```text
+hcc update [--tag TAG] [--registry URL] [--dry-run]
+hcc uninstall [--purge --yes]
+```
+
+`hcc update` 更新全局 npm 安装。`hcc uninstall` 移除本机 hooks 和 shims；
+只有在确定也要删除当前项目的 `.hello-cc` 数据和指导块时，才加
+`--purge --yes`。
+
+## 启动和停止
+
+```text
+hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-discover] [--no-guidance]
+hcc down
+hcc up [--no-discover] [--no-guidance]
+```
+
+`hcc web` 是默认入口。它会初始化协作状态，安装 hooks 和 shims，启动或复用
+Web 控制台，然后把终端还给你。只想使用本地协作、不需要 Web 或 shims 时，
+再使用 `hcc up`。
+
+## Peers 和状态
+
+```text
+hcc peers
+hcc status [--peer ID]
+hcc scan [--register]
+hcc prompt --peer ID [--kind codex|claude|shell|other] [--role ROLE]
+hcc join --peer ID [--kind codex|claude|shell|other] [--role ROLE]
+hcc env --peer ID
+hcc heartbeat [--peer ID] [--renew-locks --ttl 900]
+hcc run --peer ID --kind codex|claude|shell --role ROLE -- COMMAND [ARGS...]
+```
+
+这些命令用于查看项目状态、注册终端，以及用 `HCC_PEER`、`HCC_ROOT`、
+`HCC_DB` 环境运行 CLI。
+
+## Web 可控终端
+
+```text
+hcc peer list
+hcc peer start PEER [--kind K] [--role R] [--cwd DIR] [--restart-env] -- COMMAND [ARGS...]
+hcc peer start PEER --kind codex --resume SESSION_ID [--restart-env]
+hcc peer start PEER --kind codex --last
+hcc peer start PEER --kind claude --resume SESSION_ID [--restart-env]
+hcc peer start PEER --kind claude --continue
+hcc peer attach PEER [--pane PANE] [--kind K] [--role R] [--cwd DIR]
+hcc peer stop PEER
+hcc inject PEER TEXT [--no-enter]
+```
+
+这些命令创建或接入 tmux-backed 终端，让 Web 控制台可以观察和操作它们。
+
+## 消息
+
+```text
+hcc msg send [--from ID] [--to ID|all] --body TEXT [--task N] [--kind note|task|handoff]
+hcc msg inbox [--peer ID] [--wait SEC] [--all] [--limit N]
+hcc msg ack [--peer ID] --id N
+hcc ask PEER MESSAGE [--from ID] [--task N] [--inject]
+hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
+```
+
+消息是带收件人的邮箱记录。`ask` 和 `broadcast` 加 `--inject` 后，也会把内容
+实时注入到终端。
+
+## 任务
+
+```text
+hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
+hcc task list [--status S] [--peer ID] [--all]
+hcc task claim [--peer ID] --id N
+hcc task next [--peer ID]
+hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
+hcc task done [--peer ID] --id N --summary TEXT
+```
+
+任务是项目共享事实。任务会一直可见，直到被标记为 `done` 或 `abandoned`。
+
+## 锁、交接和事件
+
+```text
+hcc lock acquire [--peer ID] --resource PATH [--task N] [--ttl SEC] [--reason TEXT]
+hcc lock renew [--peer ID] --resource PATH [--ttl SEC]
+hcc lock release [--peer ID] --resource PATH [--force]
+hcc lock list [--all]
+hcc handoff create [--from ID] --summary TEXT [--task N] [--to ID] [--changed-files JSON_OR_CSV] [--tests TEXT] [--risks TEXT]
+hcc handoff list [--task N] [--limit N]
+hcc event tail [--limit N]
+hcc gc [--older-than DAYS] [--yes]
+```
+
+锁是带 TTL 的协作式 advisory lock。交接记录用于保存结果、测试、变更文件和
+剩余风险，方便工作在多个 peer 之间继续。