@termhub/agent 0.1.0 → 0.1.2

package/README.md

@@ -21,7 +21,8 @@ termhub-agent connect --url https://app.termhub.dev
 
 You'll be prompted to paste an agent token generated from the termhub web app (Machines → Add
 machine). `--token <token>` and the `TERMHUB_URL`/`TERMHUB_TOKEN` environment variables work too,
-for non-interactive setups. On success the agent keeps running in the foreground until Ctrl-C.
+for non-interactive setups. On success the pairing is saved and the command exits; start the agent
+with `termhub-agent service install` (background) or `termhub-agent run` (foreground).
 
 ## Run as a background service
 
@@ -51,3 +52,10 @@ macOS's TCC (Transparency, Consent and Control) can block the agent from listing
 special privileges. If `doctor` or `service install` reports this, grant the agent's Node binary
 Full Disk Access: **Ajustes → Privacidade e Segurança → Acesso Total ao Disco**, then add the
 `node` binary path `doctor` printed.
+
+## Troubleshooting
+
+- **Terminals fail to open with `posix_spawnp failed.`** (visible in `~/.termhub/agent.log`): node-pty's
+  prebuilt `spawn-helper` lost its exec bit — npm 11 skips the postinstall that sets it unless the
+  package is approved. The agent repairs this itself on startup and in `termhub-agent doctor`; if the
+  file is not writable by your user, `doctor` prints the exact `chmod +x` to run.

package/dist/cli.js

@@ -529,10 +529,10 @@ function ptyEnv(base, shell) {
 // src/exec.ts
 var DEFAULT_TIMEOUT_MS = 8e3;
 var RpcFailure = class extends Error {
-  constructor(code, message, path8) {
+  constructor(code, message, path9) {
     super(message);
     this.code = code;
-    this.path = path8;
+    this.path = path9;
   }
   code;
   path;
@@ -689,6 +689,7 @@ function createPtyManager(deps) {
         const spawn = await resolveSpawn();
         proc = spawn(tmux, ["-u", "new-session", "-A", "-s", params.session, "-c", cwd], { name: "xterm-256color", cols, rows, cwd, env });
       } catch (err) {
+        deps.log("pty open failed", { ch, session: params.session, tmux, cwd: params.cwd, error: err instanceof Error ? err.message : String(err) });
         socket.sendControl({
           type: "open_error",
           ch,
@@ -770,6 +771,37 @@ function createPtyManager(deps) {
   };
 }
 
+// src/pty-health.ts
+import fs3 from "fs";
+import path3 from "path";
+import { createRequire } from "module";
+function findSpawnHelper(resolveFrom = import.meta.url) {
+  let pkgJson;
+  try {
+    pkgJson = createRequire(resolveFrom).resolve("node-pty/package.json");
+  } catch {
+    return null;
+  }
+  const root = path3.dirname(pkgJson);
+  const candidates = [
+    path3.join(root, "prebuilds", `${process.platform}-${process.arch}`, "spawn-helper"),
+    path3.join(root, "build", "Release", "spawn-helper")
+  ];
+  return candidates.find((p) => fs3.existsSync(p)) ?? null;
+}
+var EXEC_BITS = 73;
+function ensureSpawnHelperExecutable(helper = findSpawnHelper()) {
+  if (!helper) return { path: null, executable: true, repaired: false };
+  try {
+    const mode = fs3.statSync(helper).mode;
+    if (mode & EXEC_BITS) return { path: helper, executable: true, repaired: false };
+    fs3.chmodSync(helper, (mode | 493) & 4095);
+    return { path: helper, executable: true, repaired: true };
+  } catch (err) {
+    return { path: helper, executable: false, repaired: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 // src/rpc/ai.ts
 async function credential(params) {
   let prefix;
@@ -820,9 +852,9 @@ async function pasteFile(params) {
   if (r.timedOut) throw new RpcFailure("timeout", "file.paste timed out");
   if (r.code !== 0) throw new RpcFailure("internal", `file.paste exited with code ${r.code}`);
   const lines = r.stdout.split("\n").map((l) => l.trim()).filter(Boolean);
-  const path8 = lines[lines.length - 1] ?? "";
-  if (!path8.startsWith("/")) throw new RpcFailure("internal", "unexpected paste output");
-  return { path: path8 };
+  const path9 = lines[lines.length - 1] ?? "";
+  if (!path9.startsWith("/")) throw new RpcFailure("internal", "unexpected paste output");
+  return { path: path9 };
 }
 
 // src/rpc/tmux.ts
@@ -877,9 +909,9 @@ var handlers = {
 };
 
 // src/service/launchd.ts
-import fs3 from "fs";
+import fs4 from "fs";
 import os3 from "os";
-import path3 from "path";
+import path4 from "path";
 var LABEL = "dev.termhub.agent";
 function renderPlist({ label, node, script, logPath }) {
   const escape = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -918,7 +950,7 @@ function renderPlist({ label, node, script, logPath }) {
 `;
 }
 function plistPath() {
-  return path3.join(os3.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+  return path4.join(os3.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
 }
 function gui() {
   return `gui/${process.getuid ? process.getuid() : 0}`;
@@ -927,8 +959,8 @@ async function install(opts, deps = {}) {
   const runFn = deps.run ?? run;
   const file = plistPath();
   const plist = renderPlist({ label: LABEL, node: opts.node, script: opts.script, logPath: opts.logPath });
-  fs3.mkdirSync(path3.dirname(file), { recursive: true });
-  fs3.writeFileSync(file, plist, "utf8");
+  fs4.mkdirSync(path4.dirname(file), { recursive: true });
+  fs4.writeFileSync(file, plist, "utf8");
   await runFn("launchctl", ["bootout", gui(), file]);
   const result = await runFn("launchctl", ["bootstrap", gui(), file]);
   if (result.code !== 0) {
@@ -940,7 +972,7 @@ async function uninstall(deps = {}) {
   const file = plistPath();
   await runFn("launchctl", ["bootout", gui(), file]);
   try {
-    fs3.unlinkSync(file);
+    fs4.unlinkSync(file);
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
@@ -961,7 +993,7 @@ async function status(deps = {}) {
 }
 
 // src/version.ts
-var AGENT_VERSION = "0.1.0";
+var AGENT_VERSION = "0.1.2";
 
 // src/run.ts
 function detectOs(platform = process.platform) {
@@ -1039,6 +1071,9 @@ async function runAgent(config, opts) {
     process.exit(1);
   }
   const hello = await buildHello(osName);
+  const helper = ensureSpawnHelperExecutable();
+  if (helper.repaired) opts.log("spawn-helper exec bit repaired", { path: helper.path });
+  else if (!helper.executable) opts.log("spawn-helper is not executable and could not be fixed", { path: helper.path, error: helper.error });
   const pty = createPtyManager({ log: opts.log });
   const dispatch = createDispatcher({ handlers, pty, log: opts.log });
   try {
@@ -1134,8 +1169,11 @@ async function connectCommand(values, log2) {
   }
   const config = { url, token, machine_id: "", machine_name: "", created_at: (/* @__PURE__ */ new Date()).toISOString() };
   writeConfig(config);
-  console.log("Conectado. Agora rode: termhub-agent service install");
-  await runForegroundUntilSignal(config, log2);
+  console.log("Conectado. Configura\xE7\xE3o salva.");
+  console.log("Pr\xF3ximos passos:");
+  console.log("  termhub-agent service install   # mant\xE9m o agente rodando em segundo plano");
+  console.log("  termhub-agent doctor            # confere tmux e acesso \xE0s pastas");
+  console.log("(ou termhub-agent run para rodar em primeiro plano)");
 }
 
 // src/commands/disconnect.ts
@@ -1145,17 +1183,17 @@ function disconnectCommand() {
 }
 
 // src/doctor.ts
-import fs4 from "fs";
+import fs5 from "fs";
 import os5 from "os";
-import path4 from "path";
+import path5 from "path";
 var SERVER_CHECK_TIMEOUT_MS = 5e3;
 function defaultDoctorPaths() {
   const home = os5.homedir();
-  const paths = [home, path4.join(home, "Documents"), path4.join(home, "Desktop")];
+  const paths = [home, path5.join(home, "Documents"), path5.join(home, "Desktop")];
   if (process.platform === "darwin") {
     try {
-      for (const entry of fs4.readdirSync("/Volumes", { withFileTypes: true })) {
-        if (entry.isDirectory()) paths.push(path4.join("/Volumes", entry.name));
+      for (const entry of fs5.readdirSync("/Volumes", { withFileTypes: true })) {
+        if (entry.isDirectory()) paths.push(path5.join("/Volumes", entry.name));
       }
     } catch {
     }
@@ -1168,7 +1206,7 @@ function pathErrorCode(err) {
   if (e?.code) return e.code;
   return err instanceof Error ? err.message : String(err);
 }
-function checkPathAccess(p, fsImpl = fs4) {
+function checkPathAccess(p, fsImpl = fs5) {
   try {
     fsImpl.readdirSync(p);
     return { path: p, ok: true };
@@ -1180,7 +1218,7 @@ function fullDiskAccessNote(execPath = process.execPath) {
   return `Conceda Acesso Total ao Disco a ${execPath} em Ajustes \u2192 Privacidade e Seguran\xE7a \u2192 Acesso Total ao Disco`;
 }
 async function runDoctor(paths, deps = {}) {
-  const fsImpl = deps.fs ?? fs4;
+  const fsImpl = deps.fs ?? fs5;
   const connect = deps.connect ?? checkServerConnection;
   const config = readConfig();
   const configReport = { ok: config !== null, path: configPath() };
@@ -1195,7 +1233,9 @@ async function runDoctor(paths, deps = {}) {
     nodePty = { ok: false, error: err instanceof Error ? err.message : String(err) };
   }
   const pathsReport = paths.map((p) => checkPathAccess(p, fsImpl));
-  return { config: configReport, server, tmux, nodePty, paths: pathsReport };
+  const helper = ensureSpawnHelperExecutable();
+  const spawnHelper = { ok: helper.executable, path: helper.path, repaired: helper.repaired, ...helper.error ? { error: helper.error } : {} };
+  return { config: configReport, server, tmux, nodePty, spawnHelper, paths: pathsReport };
 }
 function mark(ok) {
   return ok ? "\u2713" : "\u2717";
@@ -1208,6 +1248,11 @@ function formatDoctor(report, deps = {}) {
   lines.push(`${mark(report.server.ok)} Servidor${report.server.ok ? "" : report.server.error ? `: ${report.server.error}` : ""}`);
   lines.push(`${mark(report.tmux.ok)} tmux${report.tmux.path ? ` (${report.tmux.path})` : ""}`);
   lines.push(`${mark(report.nodePty.ok)} node-pty${report.nodePty.ok ? "" : report.nodePty.error ? `: ${report.nodePty.error}` : ""}`);
+  const sh2 = report.spawnHelper;
+  if (sh2.path) {
+    lines.push(`${mark(sh2.ok)} spawn-helper do node-pty ${sh2.ok ? sh2.repaired ? "(permiss\xE3o de execu\xE7\xE3o corrigida agora)" : "execut\xE1vel" : `sem permiss\xE3o de execu\xE7\xE3o${sh2.error ? `: ${sh2.error}` : ""}`}`);
+    if (!sh2.ok) lines.push(`  \u2192 rode: chmod +x "${sh2.path}"`);
+  }
   for (const p of report.paths) {
     lines.push(`${mark(p.ok)} ${p.path}${p.ok ? "" : p.error ? `: ${p.error}` : ""}`);
     if (!p.ok && p.error === "eperm" && platform === "darwin") {
@@ -1243,18 +1288,18 @@ async function runCommand(log2) {
 import os7 from "os";
 
 // src/service/index.ts
-import path7 from "path";
+import path8 from "path";
 
 // src/paths.ts
 import { realpathSync } from "fs";
-import path5 from "path";
+import path6 from "path";
 import { pathToFileURL } from "url";
 function resolveScriptPath(argv1) {
   if (!argv1) return "";
   try {
     return realpathSync(argv1);
   } catch {
-    return path5.resolve(argv1);
+    return path6.resolve(argv1);
   }
 }
 function isMainModule(importMetaUrl, argv1) {
@@ -1263,9 +1308,9 @@ function isMainModule(importMetaUrl, argv1) {
 }
 
 // src/service/systemd.ts
-import fs5 from "fs";
+import fs6 from "fs";
 import os6 from "os";
-import path6 from "path";
+import path7 from "path";
 var UNIT_NAME = "termhub-agent";
 function renderUnit({ node, script, logPath }) {
   const lines = [
@@ -1287,14 +1332,14 @@ function renderUnit({ node, script, logPath }) {
   return lines.join("\n");
 }
 function unitPath() {
-  return path6.join(os6.homedir(), ".config", "systemd", "user", `${UNIT_NAME}.service`);
+  return path7.join(os6.homedir(), ".config", "systemd", "user", `${UNIT_NAME}.service`);
 }
 async function install2(opts, deps = {}) {
   const runFn = deps.run ?? run;
   const file = unitPath();
   const unit = renderUnit({ node: opts.node, script: opts.script, logPath: opts.logPath });
-  fs5.mkdirSync(path6.dirname(file), { recursive: true });
-  fs5.writeFileSync(file, unit, "utf8");
+  fs6.mkdirSync(path7.dirname(file), { recursive: true });
+  fs6.writeFileSync(file, unit, "utf8");
   const reload = await runFn("systemctl", ["--user", "daemon-reload"]);
   if (reload.code !== 0) throw new Error(`systemctl daemon-reload failed (code ${reload.code}): ${reload.stderr.trim()}`);
   const enable = await runFn("systemctl", ["--user", "enable", "--now", UNIT_NAME]);
@@ -1305,7 +1350,7 @@ async function uninstall2(deps = {}) {
   const runFn = deps.run ?? run;
   await runFn("systemctl", ["--user", "disable", "--now", UNIT_NAME]);
   try {
-    fs5.unlinkSync(unitPath());
+    fs6.unlinkSync(unitPath());
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
@@ -1322,7 +1367,7 @@ function serviceFileOptions() {
   return {
     node: process.execPath,
     script: resolveScriptPath(process.argv[1]),
-    logPath: path7.join(agentHome(), "agent.log")
+    logPath: path8.join(agentHome(), "agent.log")
   };
 }
 function assertSupported(platform) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termhub/agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agente do termhub: conecta esta máquina ao servidor por WebSocket de saída (sem SSH) e expõe os terminais tmux no navegador.",
   "license": "MIT",
   "private": false,