@termhub/agent 0.7.1 → 0.8.0

package/dist/cli.js

@@ -38,6 +38,8 @@ var SESSION_RE = /^[A-Za-z0-9_-]+$/;
 var sessionName = z.string().min(1).max(128).regex(SESSION_RE);
 var machinePath = z.string().min(1).max(4096).refine((p) => (p === "~" || p.startsWith("~/") || p.startsWith("/")) && !/[\0\n\r]/.test(p), "invalid path");
 var pasteName = z.string().min(1).max(255).regex(/^[A-Za-z0-9._-]+$/);
+var DOC_PATH_RE = /^docs\/superpowers\/(specs|plans)\/[A-Za-z0-9._-]{1,200}\.md$/;
+var docPath = z.string().regex(DOC_PATH_RE);
 var aiProvider = z.enum(["claude", "chatgpt", "gemini", "antigravity"]);
 var UDID_RE = /^[A-Fa-f0-9-]{8,64}$/;
 var udid = z.string().regex(UDID_RE);
@@ -120,7 +122,18 @@ var RPC = {
   /** Writes ~/.termhub/wda-setup.sh and runs it in tmux `termhub-wda-setup`; `started: false` when already running. */
   "wda.setup.start": def(z.object({}), z.object({ started: z.boolean() }), 1e4),
   /** Raw `STATE:/VERSION:/TAIL:` text; `parseSetupOutput` on the server reads it. */
-  "wda.setup.state": def(z.object({}), z.object({ stdout: z.string() }))
+  "wda.setup.state": def(z.object({}), z.object({ stdout: z.string() })),
+  /**
+   * Manifest of `docs/superpowers/{specs,plans}/*.md` under `cwd`: `F\t<sha256>\t<size>\t<relpath>`
+   * lines, `@termhub/machine-ops`'s `parseDocsScan` reads them back (since agent 0.8.0).
+   */
+  "docs.scan": def(z.object({ cwd: machinePath }), z.object({ stdout: z.string() }), 15e3),
+  /**
+   * Base64 bodies for up to 20 chosen paths, each re-validated against the same tree on the
+   * machine (defence in depth — `docPath` already restricts what reaches this call); a file over
+   * `DOCS_MAX_BYTES` is skipped silently. `parseDocsRead` reads the output back (since agent 0.8.0).
+   */
+  "docs.read": def(z.object({ cwd: machinePath, paths: z.array(docPath).min(1).max(20) }), z.object({ stdout: z.string() }), 2e4)
 };
 var RPC_METHODS = Object.keys(RPC);
 var rpcMethod = z.enum(RPC_METHODS);
@@ -576,6 +589,79 @@ function buildMkdirScript(quotedParent, quotedName, opts = {}) {
   ].join("; ");
 }
 
+// ../../packages/machine-ops/dist/docs-script.js
+var DOCS_MAX_BYTES = 256 * 1024;
+var DOCS_MAX_FILES = 200;
+var DOCS_READ_MAX_BYTES = 600 * 1024;
+var SYMLINKED_DIR_GUARD = [
+  `specs_ok=1; plans_ok=1`,
+  `[ ! -L docs ] || { specs_ok=0; plans_ok=0; }`,
+  `[ ! -L docs/superpowers ] || { specs_ok=0; plans_ok=0; }`,
+  `[ ! -L docs/superpowers/specs ] || specs_ok=0`,
+  `[ ! -L docs/superpowers/plans ] || plans_ok=0`
+].join("\n");
+function buildDocsScanScript(cwdQuoted) {
+  return [
+    `P=${cwdQuoted}`,
+    EXPAND_HOME,
+    `cd -- "$P" 2>/dev/null || { echo 'ERR:notfound'; exit 0; }`,
+    `if command -v sha256sum >/dev/null 2>&1; then H='sha256sum'`,
+    `elif command -v shasum >/dev/null 2>&1; then H='shasum -a 256'`,
+    `else echo 'ERR:nohash'; exit 0`,
+    `fi`,
+    SYMLINKED_DIR_GUARD,
+    `n=0`,
+    `for d in docs/superpowers/specs docs/superpowers/plans; do`,
+    `  [ -d "$d" ] || continue`,
+    `  case "$d" in`,
+    `    docs/superpowers/specs) [ "$specs_ok" = 1 ] || continue ;;`,
+    `    docs/superpowers/plans) [ "$plans_ok" = 1 ] || continue ;;`,
+    `  esac`,
+    `  for f in "$d"/*.md; do`,
+    `    [ -f "$f" ] && [ ! -L "$f" ] && [ -r "$f" ] || continue`,
+    `    case "$f" in *[!A-Za-z0-9._/-]*) continue;; esac`,
+    `    n=$((n+1)); [ "$n" -le ${DOCS_MAX_FILES} ] || break 2`,
+    `    s=$(wc -c < "$f" | tr -d ' ')`,
+    `    [ -n "$s" ] || continue`,
+    `    if [ "$s" -le ${DOCS_MAX_BYTES} ]; then`,
+    `      h=$($H "$f" | cut -d' ' -f1)`,
+    `      printf 'F\\t%s\\t%s\\t%s\\n' "$h" "$s" "$f"`,
+    `    else`,
+    `      printf 'S\\t%s\\t%s\\n' "$s" "$f"`,
+    `    fi`,
+    `  done`,
+    `done`
+  ].join("\n");
+}
+function buildDocsReadScript(cwdQuoted, quotedPaths) {
+  return [
+    `P=${cwdQuoted}`,
+    EXPAND_HOME,
+    `cd -- "$P" 2>/dev/null || { echo 'ERR:notfound'; exit 0; }`,
+    SYMLINKED_DIR_GUARD,
+    `total=0`,
+    `for f in ${quotedPaths.join(" ")}; do`,
+    `  case "$f" in`,
+    `    docs/superpowers/specs/*.md) [ "$specs_ok" = 1 ] || continue ;;`,
+    `    docs/superpowers/plans/*.md) [ "$plans_ok" = 1 ] || continue ;;`,
+    `    *) continue ;;`,
+    `  esac`,
+    `  case "$f" in docs/superpowers/specs/*/*|docs/superpowers/plans/*/*) continue;; esac`,
+    `  case "$f" in *[!A-Za-z0-9._/-]*) continue;; esac`,
+    `  [ -f "$f" ] && [ ! -L "$f" ] && [ -r "$f" ] || continue`,
+    `  s=$(wc -c < "$f" | tr -d ' ')`,
+    `  [ -n "$s" ] || continue`,
+    `  [ "$s" -le ${DOCS_MAX_BYTES} ] || continue`,
+    `  newtotal=$((total + s))`,
+    `  [ "$newtotal" -le ${DOCS_READ_MAX_BYTES} ] || break`,
+    `  total=$newtotal`,
+    `  printf 'B\\t%s\\t%s\\n' "$s" "$f"`,
+    `  base64 < "$f"`,
+    `  echo E`,
+    `done`
+  ].join("\n");
+}
+
 // ../../packages/machine-ops/dist/paste.js
 import { randomBytes } from "crypto";
 var PASTE_MAX_BYTES = 20 * 1024 * 1024;
@@ -2053,21 +2139,40 @@ async function linkSession(params) {
   return { status: status4 };
 }
 
-// src/rpc/fs.ts
+// src/rpc/docs.ts
 function processFailure(method, r) {
   if (r.timedOut) return new RpcFailure("timeout", `${method} timed out`);
   if (r.code !== 0) return new RpcFailure("internal", `${method} exited with code ${r.code}`);
   return null;
 }
+async function scan(params) {
+  const r = await sh(buildDocsScanScript(shellQuote(params.cwd)));
+  const failure = processFailure("docs.scan", r);
+  if (failure) throw failure;
+  return { stdout: r.stdout };
+}
+async function read(params) {
+  const r = await sh(buildDocsReadScript(shellQuote(params.cwd), params.paths.map(shellQuote)));
+  const failure = processFailure("docs.read", r);
+  if (failure) throw failure;
+  return { stdout: r.stdout };
+}
+
+// src/rpc/fs.ts
+function processFailure2(method, r) {
+  if (r.timedOut) return new RpcFailure("timeout", `${method} timed out`);
+  if (r.code !== 0) return new RpcFailure("internal", `${method} exited with code ${r.code}`);
+  return null;
+}
 async function list(params) {
   const r = await sh(buildFsListScript(shellQuote(params.path)));
-  const failure = processFailure("fs.list", r);
+  const failure = processFailure2("fs.list", r);
   if (failure) throw failure;
   return { stdout: r.stdout };
 }
 async function mkdir2(params) {
   const r = await sh(buildMkdirScript(shellQuote(params.parent), shellQuote(params.name), { recursive: params.recursive === true }));
-  const failure = processFailure("fs.mkdir", r);
+  const failure = processFailure2("fs.mkdir", r);
   if (failure) throw failure;
   return { stdout: r.stdout };
 }
@@ -2123,7 +2228,7 @@ async function boot(params) {
 // src/rpc/tmux.ts
 import { randomUUID } from "crypto";
 var ENTER_PAUSE_MS = 300;
-function processFailure2(r) {
+function processFailure3(r) {
   if (r.timedOut) return new RpcFailure("timeout", "tmux timed out");
   if (r.error === "enoent") return new RpcFailure("no_tmux", "tmux not found");
   if (r.error === "maxbuffer") return new RpcFailure("internal", "output too large");
@@ -2131,7 +2236,7 @@ function processFailure2(r) {
 }
 async function list3(_params) {
   const r = await run(tmuxPath(), ["list-sessions", "-F", "#{session_name}"]);
-  const failure = processFailure2(r);
+  const failure = processFailure3(r);
   if (failure) throw failure;
   if (r.code !== 0) return { sessions: [] };
   const sessions = r.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
@@ -2139,13 +2244,13 @@ async function list3(_params) {
 }
 async function kill(params) {
   const r = await run(tmuxPath(), ["kill-session", "-t", `=${params.session}`]);
-  const failure = processFailure2(r);
+  const failure = processFailure3(r);
   if (failure) throw failure;
   return { killed: r.code === 0 };
 }
 async function capture(params) {
   const r = await run(tmuxPath(), ["capture-pane", "-p", ...params.escapes ? ["-e"] : [], "-S", `-${params.lines}`, "-t", `=${params.session}:`]);
-  const failure = processFailure2(r);
+  const failure = processFailure3(r);
   if (failure) throw failure;
   if (r.code !== 0) throw new RpcFailure("notfound", "session not found");
   return params.escapes ? { text: r.stdout, escapes: true } : { text: r.stdout };
@@ -2154,11 +2259,11 @@ var pane = (session) => `=${session}:`;
 var why = (stderr, fallback) => stderr.trim().split("\n")[0] || fallback;
 async function ensure(params) {
   const has = await run(tmuxPath(), ["has-session", "-t", `=${params.session}`]);
-  const hasFailure = processFailure2(has);
+  const hasFailure = processFailure3(has);
   if (hasFailure) throw hasFailure;
   if (has.code === 0) return { created: false };
   const made = await run(tmuxPath(), ["new-session", "-d", "-s", params.session, "-c", params.cwd]);
-  const madeFailure = processFailure2(made);
+  const madeFailure = processFailure3(made);
   if (madeFailure) throw madeFailure;
   if (made.code !== 0) throw new RpcFailure("failed", why(made.stderr, "tmux new-session falhou"), params.cwd);
   return { created: true };
@@ -2167,11 +2272,11 @@ async function pasteText(session, text) {
   const bufferName = `termhub-paste-${randomUUID()}`;
   try {
     const loaded = await run(tmuxPath(), ["load-buffer", "-b", bufferName, "-"], { input: Buffer.from(text, "utf8") });
-    const loadFailure = processFailure2(loaded);
+    const loadFailure = processFailure3(loaded);
     if (loadFailure) throw loadFailure;
     if (loaded.code !== 0) throw new RpcFailure("internal", why(loaded.stderr, "tmux load-buffer failed"));
     const pasted = await run(tmuxPath(), ["paste-buffer", "-p", "-d", "-b", bufferName, "-t", pane(session)]);
-    const pasteFailure = processFailure2(pasted);
+    const pasteFailure = processFailure3(pasted);
     if (pasteFailure) throw pasteFailure;
     if (pasted.code !== 0) throw new RpcFailure("notfound", why(pasted.stderr, "session not found"));
   } finally {
@@ -2184,7 +2289,7 @@ async function sendText(params) {
       await pasteText(params.session, params.text);
     } else {
       const typed = await run(tmuxPath(), ["send-keys", "-t", pane(params.session), "-l", "--", params.text]);
-      const failure = processFailure2(typed);
+      const failure = processFailure3(typed);
       if (failure) throw failure;
       if (typed.code !== 0) throw new RpcFailure("notfound", why(typed.stderr, "session not found"));
     }
@@ -2192,7 +2297,7 @@ async function sendText(params) {
   }
   if (params.enter) {
     const entered = await run(tmuxPath(), ["send-keys", "-t", pane(params.session), "Enter"]);
-    const failure = processFailure2(entered);
+    const failure = processFailure3(entered);
     if (failure) throw failure;
     if (entered.code !== 0) throw new RpcFailure("notfound", why(entered.stderr, "session not found"));
   }
@@ -2200,7 +2305,7 @@ async function sendText(params) {
 }
 async function sendKey(params) {
   const r = await run(tmuxPath(), ["send-keys", "-t", pane(params.session), params.key]);
-  const failure = processFailure2(r);
+  const failure = processFailure3(r);
   if (failure) throw failure;
   if (r.code !== 0) throw new RpcFailure("notfound", why(r.stderr, "session not found"));
   return { sent: true };
@@ -2436,7 +2541,7 @@ async function status3() {
 }
 
 // src/version.ts
-var AGENT_VERSION = "0.7.1";
+var AGENT_VERSION = "0.8.0";
 
 // src/rpc/update.ts
 var PACKAGE = "@termhub/agent";
@@ -2557,6 +2662,8 @@ var handlers = {
   "fs.mkdir": mkdir2,
   "ai.credential": credential,
   "claude.linkSession": linkSession,
+  "docs.scan": scan,
+  "docs.read": read,
   "file.paste": pasteFile,
   "hooks.install": install,
   "hooks.uninstall": uninstall,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termhub/agent",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "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,