@link-assistant/hive-mind 1.55.0 → 1.56.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @link-assistant/hive-mind
 
+## 1.56.0
+
+### Minor Changes
+
+- 391dbde: Add `hive-screens` bin command. Converts the `hive-screens.sh` script that was
+  embedded in README.md into a real JavaScript command shipped with the package.
+  Supports `--list` (safe preview), `--enter` (attach), and `--close` (terminate)
+  across detached GNU screen sessions that completed a mergeable solve run.
+  `--list`, `--enter`, and `--close` share the same matching predicate, so any
+  session visible under `--list` is guaranteed to be actionable by the other
+  flags. Selection flags `--oldest` (default), `--newest`, and `--all` are
+  preserved from the legacy script. Closes #1649.
+
 ## 1.55.0
 
 ### Minor Changes

package/README.md

@@ -818,124 +818,34 @@ s=$(screen -ls | awk '/Detached/ {last=$1} END{print last}'); echo "Entering $s"
 
 ### Script for managing screens
 
-```bash
-cat <<'EOF' > hive-screens.sh
-#!/usr/bin/env bash
-
-enter=false
-close=false
-oldest=false
-newest=false
-all=false
-
-# --- parse args ---
-for arg in "$@"; do
-  case "$arg" in
-    --enter) enter=true ;;
-    --close) close=true ;;
-    --oldest) oldest=true ;;
-    --newest) newest=true ;;
-    --all) all=true ;;
-    *)
-      echo "Unknown option: $arg"
-      exit 1
-      ;;
-  esac
-done
-
-# --- validate ---
-if ! $enter && ! $close; then
-  echo "Must specify --enter or --close"
-  exit 1
-fi
-
-# --- default ---
-if ! $oldest && ! $newest && ! $all; then
-  oldest=true
-fi
-
-matches=()
-
-# --- sorting ---
-if $newest; then
-  sorter="sort -nr"
-else
-  sorter="sort -n"
-fi
-
-# --- scan sessions ---
-while read -r sess; do
-  tmp=$(mktemp)
-  clean=$(mktemp)
-
-  # FIX: better capture
-  screen -S "$sess" -X scrollback 200000 2>/dev/null
-  sleep 0.15
-  screen -S "$sess" -X hardcopy -h "$tmp" 2>/dev/null
-
-  # strip garbage / non-printable chars
-  tr -cd '\11\12\15\40-\176' < "$tmp" > "$clean"
-
-  if grep -qi 'process completed' "$clean" &&
-     grep -qiE 'pr is mergeable!|pr merged!' "$clean"; then
-
-    log_path=$(tac "$clean" | grep -m1 -i 'full log file:' \
-      | sed 's/.*Full log file:[[:space:]]*//')
-
-    issue=$(tac "$clean" | grep -m1 -i 'Issue:[[:space:]]*https://github\.com/' \
-      | sed 's/Issue:[[:space:]]*//')
-
-    matches+=("$sess|$log_path|$issue")
-  fi
-
-  rm -f "$tmp" "$clean"
-done < <(screen -ls | awk '/Detached/ {print $1}' | $sorter)
-
-# --- no matches ---
-if [ ${#matches[@]} -eq 0 ]; then
-  echo "No matching sessions"
-  exit 0
-fi
-
-process_one() {
-  IFS="|" read -r sess log issue <<< "$1"
-
-  echo "Session: $sess"
-
-  if $enter; then
-    echo "Entering $sess"
-    screen -r "$sess"
-    echo "Left $sess"
-  fi
+The legacy `hive-screens.sh` script has been promoted to a first-class command:
+`hive-screens`. It ships with `@link-assistant/hive-mind`, so once the package is
+installed (globally, through `npx`, or in a project) it is available on `PATH`.
 
-  [ -n "$log" ] && echo "Log: $log" || echo "Log: (not found)"
-  [ -n "$issue" ] && echo "Issue: $issue" || echo "Issue: (not found)"
+It scans detached GNU screen sessions, looks for solve runs that are done and
+mergeable (scrollback contains both `process completed` and `PR is mergeable!`
+or `PR merged!`), and then either lists, enters, or closes them. `--list`,
+`--enter`, and `--close` share the **same matching predicate**, so anything
+you see under `--list` is guaranteed to be the same set `--close` will act on
+— use `--list` first to debug, then rerun with `--close`.
 
-  if $close; then
-    echo "Closing $sess"
-    screen -S "$sess" -X stuff $'exit\n'
-  fi
-
-  echo "-----------------------------------"
-}
+```bash
+# Safe preview — show every finished, mergeable solve session.
+hive-screens --list --all
 
-# --- execution ---
-if $all; then
-  for m in "${matches[@]}"; do
-    process_one "$m"
-  done
-elif $oldest; then
-  process_one "${matches[0]}"
-elif $newest; then
-  last_index=$((${#matches[@]} - 1))
-  process_one "${matches[$last_index]}"
-fi
+# Close the oldest finished session (same as the legacy script's default).
+hive-screens --close
 
-EOF
+# Attach to the newest finished session.
+hive-screens --enter --newest
 
-chmod +x hive-screens.sh
+# Close every finished session.
+hive-screens --close --all
 ```
 
+Selection defaults to `--oldest`. Supply `--newest` or `--all` to change it.
+Run `hive-screens --help` for the full option list.
+
 ### Reboot server.
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",
@@ -11,10 +11,11 @@
     "review": "./src/review.mjs",
     "configure-claude": "./src/configure-claude.mjs",
     "start-screen": "./src/start-screen.mjs",
+    "hive-screens": "./src/hive-screens.mjs",
     "hive-telegram-bot": "./src/telegram-bot.mjs"
   },
   "scripts": {
-    "test": "node tests/solve-queue.test.mjs && node tests/limits-display.test.mjs && node tests/test-usage-limit.mjs && node tests/test-codex-support.mjs && node tests/test-build-cost-info-string.mjs && node tests/test-claude-code-install-method.mjs && node tests/test-claude-quiet-config.mjs && node tests/test-configure-claude-bin.mjs && node tests/test-docker-release-order.mjs && node tests/test-docker-box-migration.mjs && node tests/test-issue-1616-pr-issue-link-preservation.mjs && node tests/test-pre-pr-failure-notifier-1640.mjs && node tests/test-ready-to-merge-pagination-1645.mjs && node tests/test-require-gh-paginate-rule.mjs && node tests/test-telegram-message-filters.mjs && node tests/test-telegram-bot-command-aliases.mjs && node tests/test-solve-queue-command.mjs && node tests/test-queue-display-1267.mjs && node tests/test-telegram-bot-launcher.mjs",
+    "test": "node tests/solve-queue.test.mjs && node tests/limits-display.test.mjs && node tests/test-usage-limit.mjs && node tests/test-codex-support.mjs && node tests/test-build-cost-info-string.mjs && node tests/test-claude-code-install-method.mjs && node tests/test-claude-quiet-config.mjs && node tests/test-configure-claude-bin.mjs && node tests/test-docker-release-order.mjs && node tests/test-docker-box-migration.mjs && node tests/test-hive-screens.mjs && node tests/test-issue-1616-pr-issue-link-preservation.mjs && node tests/test-pre-pr-failure-notifier-1640.mjs && node tests/test-ready-to-merge-pagination-1645.mjs && node tests/test-require-gh-paginate-rule.mjs && node tests/test-telegram-message-filters.mjs && node tests/test-telegram-bot-command-aliases.mjs && node tests/test-solve-queue-command.mjs && node tests/test-queue-display-1267.mjs && node tests/test-telegram-bot-launcher.mjs",
     "test:queue": "node tests/solve-queue.test.mjs",
     "test:limits-display": "node tests/limits-display.test.mjs",
     "test:usage-limit": "node tests/test-usage-limit.mjs",
@@ -26,7 +27,7 @@
     "changeset": "changeset",
     "changeset:version": "changeset version",
     "changeset:publish": "npm run build:pre && changeset publish",
-    "build:pre": "chmod +x src/hive.mjs && chmod +x src/solve.mjs && chmod +x src/configure-claude.mjs",
+    "build:pre": "chmod +x src/hive.mjs && chmod +x src/solve.mjs && chmod +x src/configure-claude.mjs && chmod +x src/hive-screens.mjs",
     "prepare": "husky"
   },
   "repository": {

package/src/hive-screens.lib.mjs

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+
+/**
+ * Shared runner for the `hive-screens` bin command. Scans detached GNU
+ * screen sessions for completed solve runs and lists, enters, or closes
+ * them. Ports the `hive-screens.sh` script that previously lived in
+ * README.md, and keeps a single matching function so that `--list` is
+ * a safe preview for `--close` / `--enter`.
+ *
+ * See issue #1649.
+ */
+
+import { exec as execCallback } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(execCallback);
+
+export const HIVE_SCREENS_HELP = `Usage: hive-screens (--list | --enter | --close) [--oldest|--newest|--all]
+
+Scan detached GNU screen sessions for completed solve runs and either list,
+enter, or close them. A session matches when its scrollback contains both
+"process completed" and either "pr is mergeable!" or "pr merged!" (case
+insensitive) — the exact predicate from the legacy hive-screens.sh script.
+
+Actions (one required):
+      --list           Print matching sessions without touching them
+      --enter          Attach to the selected match (blocking)
+      --close          Send \`exit\\n\` to the selected match so it terminates
+
+Selection (optional, default: --oldest):
+      --oldest         Act on the oldest match (default)
+      --newest         Act on the newest match
+      --all            Act on every match in oldest-first order
+
+Options:
+  -h, --help           Show this help and exit
+
+Examples:
+  hive-screens --list                   # safe preview of matches
+  hive-screens --list --all             # preview every match
+  hive-screens --close --oldest         # close the oldest finished run
+  hive-screens --enter --newest         # attach to the newest finished run
+
+Reference: https://github.com/link-assistant/hive-mind/issues/1649
+`;
+
+const ACTION_FLAGS = new Set(['--enter', '--close', '--list']);
+const SELECTION_FLAGS = new Set(['--oldest', '--newest', '--all']);
+
+/**
+ * Parse the argv for `hive-screens`. Returns the parsed flags plus an
+ * `error` string when validation fails (so callers can print it and exit
+ * with a non-zero status without throwing).
+ */
+export const parseHiveScreensArgs = argv => {
+  const result = {
+    enter: false,
+    close: false,
+    list: false,
+    selection: null,
+    help: false,
+    error: null,
+  };
+
+  for (const arg of argv) {
+    if (arg === '--help' || arg === '-h') {
+      result.help = true;
+      continue;
+    }
+    if (ACTION_FLAGS.has(arg)) {
+      if (arg === '--enter') result.enter = true;
+      else if (arg === '--close') result.close = true;
+      else result.list = true;
+      continue;
+    }
+    if (SELECTION_FLAGS.has(arg)) {
+      if (result.selection && result.selection !== arg.slice(2)) {
+        result.error = `Conflicting selection flags: --${result.selection} and ${arg}`;
+        return result;
+      }
+      result.selection = arg.slice(2);
+      continue;
+    }
+    result.error = `Unknown option: ${arg}`;
+    return result;
+  }
+
+  if (result.help) return result;
+
+  const actions = [result.enter, result.close, result.list].filter(Boolean).length;
+  if (actions === 0) {
+    result.error = 'Must specify --list, --enter, or --close';
+    return result;
+  }
+  if (actions > 1) {
+    result.error = 'Specify only one of --list, --enter, --close';
+    return result;
+  }
+
+  if (!result.selection) result.selection = 'oldest';
+  return result;
+};
+
+/**
+ * List detached screen sessions in oldest-first order. GNU screen prints
+ * them newest-first, so we reverse to mirror `sort -n` (ascending PID) on
+ * the typical `NNNNN.name` session names.
+ */
+export const listDetachedSessions = async ({ exec = execAsync } = {}) => {
+  let stdout = '';
+  try {
+    ({ stdout } = await exec('screen -ls'));
+  } catch (err) {
+    // `screen -ls` exits 1 when there are no sessions. It still prints the
+    // session header to stdout, so keep parsing whatever we got.
+    stdout = err.stdout || '';
+  }
+  const sessions = [];
+  for (const rawLine of stdout.split('\n')) {
+    const line = rawLine.trim();
+    if (!/\((?:Detached|Attached)\)/i.test(line)) continue;
+    if (!/Detached/i.test(line)) continue;
+    const match = line.match(/^(\S+)/);
+    if (match) sessions.push(match[1]);
+  }
+  return sessions.sort((a, b) => {
+    const na = parseInt(a, 10);
+    const nb = parseInt(b, 10);
+    if (Number.isNaN(na) || Number.isNaN(nb)) return a.localeCompare(b);
+    return na - nb;
+  });
+};
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+const stripNonPrintable = text => text.replace(/[^\t\n\r\x20-\x7E]/g, '');
+
+/**
+ * Capture the scrollback of a single screen session. Mirrors the sh
+ * script: bump scrollback to 200000, settle, `hardcopy -h`, read, strip.
+ */
+export const captureSessionScrollback = async (session, { exec = execAsync, fsModule = fs, tmpDir = os.tmpdir(), scrollback = 200000, settleMs = 150 } = {}) => {
+  const tmpFile = path.join(tmpDir, `hive-screens-${session}-${Date.now()}-${Math.random().toString(36).slice(2)}.hardcopy`);
+  const shellSession = session.replace(/'/g, "'\\''");
+  const shellTmp = tmpFile.replace(/'/g, "'\\''");
+  try {
+    await exec(`screen -S '${shellSession}' -X scrollback ${scrollback}`).catch(() => {});
+    if (settleMs > 0) await sleep(settleMs);
+    await exec(`screen -S '${shellSession}' -X hardcopy -h '${shellTmp}'`).catch(() => {});
+    let raw = '';
+    try {
+      raw = await fsModule.readFile(tmpFile, 'utf-8');
+    } catch {
+      raw = '';
+    }
+    return stripNonPrintable(raw);
+  } finally {
+    await fsModule.unlink(tmpFile).catch(() => {});
+  }
+};
+
+/**
+ * The single source of truth for session matching. `--list`, `--enter`,
+ * and `--close` all route through this predicate, so a session visible in
+ * `--list` is guaranteed to be actionable by the other two flags.
+ */
+export const sessionMatches = text => {
+  if (!text) return { matched: false, logPath: null, issueUrl: null };
+  const hasCompletion = /process completed/i.test(text);
+  const hasMerge = /pr is mergeable!|pr merged!/i.test(text);
+  if (!hasCompletion || !hasMerge) {
+    return { matched: false, logPath: null, issueUrl: null };
+  }
+  const logMatches = [...text.matchAll(/Full log file:\s*(\S+)/gi)];
+  const issueMatches = [...text.matchAll(/Issue:\s*(https:\/\/github\.com\/\S+)/gi)];
+  return {
+    matched: true,
+    logPath: logMatches.length ? logMatches[logMatches.length - 1][1] : null,
+    issueUrl: issueMatches.length ? issueMatches[issueMatches.length - 1][1] : null,
+  };
+};
+
+/**
+ * Scan every detached session and return the ones that pass
+ * `sessionMatches`, in the requested order.
+ */
+export const findMatchingSessions = async ({ exec = execAsync, fsModule = fs, tmpDir = os.tmpdir(), order = 'oldest', captureOptions = {} } = {}) => {
+  const sessions = await listDetachedSessions({ exec });
+  const ordered = order === 'newest' ? [...sessions].reverse() : sessions;
+  const matches = [];
+  for (const session of ordered) {
+    const text = await captureSessionScrollback(session, { exec, fsModule, tmpDir, ...captureOptions });
+    const result = sessionMatches(text);
+    if (result.matched) {
+      matches.push({ session, logPath: result.logPath, issueUrl: result.issueUrl });
+    }
+  }
+  return matches;
+};
+
+/**
+ * Apply `--oldest / --newest / --all` to the ordered match list produced
+ * by `findMatchingSessions`. The orderer already did the directional
+ * sort, so picking element 0 is always "the selected one" in that order.
+ */
+export const selectMatches = (matches, selection) => {
+  if (!matches.length) return [];
+  if (selection === 'all') return matches;
+  return [matches[0]];
+};
+
+const printSession = ({ session, logPath, issueUrl }, { log }) => {
+  log(`Session: ${session}`);
+  log(logPath ? `Log: ${logPath}` : 'Log: (not found)');
+  log(issueUrl ? `Issue: ${issueUrl}` : 'Issue: (not found)');
+};
+
+const SEPARATOR = '-----------------------------------';
+
+/**
+ * Top-level orchestrator used by the bin. `deps` is injected so tests can
+ * stub `exec`, `fs`, stdio, and process spawning without touching real
+ * screen sessions.
+ */
+export const runHiveScreens = async (argv, deps = {}) => {
+  const { exec = execAsync, fsModule = fs, tmpDir = os.tmpdir(), log = (...args) => console.log(...args), error = (...args) => console.error(...args), spawnScreen, captureOptions } = deps;
+
+  const args = parseHiveScreensArgs(argv);
+  if (args.help) {
+    log(HIVE_SCREENS_HELP);
+    return 0;
+  }
+  if (args.error) {
+    error(args.error);
+    return 1;
+  }
+
+  const order = args.selection === 'newest' ? 'newest' : 'oldest';
+  const matches = await findMatchingSessions({ exec, fsModule, tmpDir, order, captureOptions });
+
+  if (!matches.length) {
+    log('No matching sessions');
+    return 0;
+  }
+
+  const selected = selectMatches(matches, args.selection);
+
+  for (const match of selected) {
+    printSession(match, { log });
+    if (args.enter) {
+      log(`Entering ${match.session}`);
+      if (spawnScreen) {
+        await spawnScreen(match.session);
+      } else {
+        await attachScreen(match.session);
+      }
+      log(`Left ${match.session}`);
+    }
+    if (args.close) {
+      log(`Closing ${match.session}`);
+      const shellSession = match.session.replace(/'/g, "'\\''");
+      await exec(`screen -S '${shellSession}' -X stuff $'exit\\n'`).catch(err => {
+        error(`Failed to send exit to ${match.session}: ${err.message}`);
+      });
+    }
+    log(SEPARATOR);
+  }
+
+  return 0;
+};
+
+/**
+ * Default `--enter` side-effect: spawn `screen -r <session>` attached to
+ * the parent stdio so the user can actually interact with it. Split from
+ * `runHiveScreens` so tests can inject a no-op spawn.
+ */
+const attachScreen = async session => {
+  const { spawn } = await import('node:child_process');
+  return new Promise((resolve, reject) => {
+    const child = spawn('screen', ['-r', session], { stdio: 'inherit' });
+    child.on('error', reject);
+    child.on('exit', () => resolve());
+  });
+};

package/src/hive-screens.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+/**
+ * `hive-screens` — list, enter, or close detached GNU screen sessions
+ * produced by `solve` / `hive` runs that have completed a mergeable PR.
+ *
+ * Replaces the embedded `hive-screens.sh` script that previously lived
+ * in README.md. The matching predicate is shared across `--list`,
+ * `--enter`, and `--close`, so any session visible under `--list` is
+ * guaranteed to be actionable by the other two flags.
+ *
+ * See issue #1649.
+ */
+
+import { runHiveScreens } from './hive-screens.lib.mjs';
+
+const exitCode = await runHiveScreens(process.argv.slice(2));
+process.exit(exitCode);