@tarfa/cli 0.0.0 → 0.1.1

package/package.json

@@ -1,15 +1,32 @@
 {
   "name": "@tarfa/cli",
-  "version": "0.0.0",
-  "description": "Tarfa: reach your coding-agent terminal sessions from your phone. Placeholder; the first release is coming.",
-  "license": "MIT",
-  "author": "abumalick",
+  "version": "0.1.1",
+  "description": "Tarfa agent and CLI: serves your Claude Code terminal sessions (tmux workspaces) to the Tarfa phone app.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/abumalick/perch.git"
+    "url": "https://github.com/abumalick/tarfa",
+    "directory": "packages/agent"
+  },
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "tarfa": "./dist/cli.js",
+    "perch": "./dist/cli.js"
   },
   "files": [
-    "README.md"
+    "dist",
+    "src/hooks/tarfa-hook.sh",
+    "src/hooks/tarfa-guard.sh",
+    "templates"
   ],
-  "bin": {}
-}
+  "dependencies": {
+    "node-pty": "1.2.0-beta.18",
+    "qr": "^0.7.0",
+    "ws": "^8.18.0",
+    "zod": "^3.25.76"
+  },
+  "scripts": {}
+}

package/src/hooks/tarfa-guard.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Tarfa PreToolUse guard for Claude Code and Codex: refuse Bash commands that kill processes by
+# name or en masse from inside a workspace, and the plain commands that would post into another
+# session's message socket or set the tmux options Tarfa reads a workspace's orchestrator and
+# Codex thread from (docs/MESSAGING.md).
+#
+# The tmux server, the agent and every workspace's CLI run as the same user, so a pattern kill
+# from any one workspace (`pkill -f x` matches nearly every command line) takes all of them down
+# at once. Nothing at the OS level can stop a process signalling its own user's processes, so
+# this refuses the command before it runs. It is a guard against accidents, not a security
+# boundary: a determined command can always get past a text match.
+#
+# Only commands run inside a tmux pane are checked. A quoted string is one argument, so a grep
+# pattern or a commit message that names these commands passes; a `sh -c` script is checked as
+# a command line of its own. A heredoc body is read as commands, and an apostrophe in one can
+# throw the quote tracking off for the rest of the line: the cost of a text match.
+[ -n "${TMUX_PANE:-}" ] || exit 0
+[ -t 0 ] && exit 0
+payload=$(cat) || exit 0
+
+# No jq on every agent machine: take tool_input.command from the JSON by hand.
+re='"command"[[:space:]]*:[[:space:]]*"(([^"\\]|\\.)*)"'
+[[ $payload =~ $re ]] || exit 0
+cmd=${BASH_REMATCH[1]}
+cmd=${cmd//\\\\/$'\x01'}
+cmd=${cmd//\\n/$'\n'}
+cmd=${cmd//\\t/ }
+cmd=${cmd//\\\"/\"}
+cmd=${cmd//$'\x01'/\\}
+
+deny() {
+  printf 'Blocked by Tarfa: %s The tmux server, the Tarfa agent and every other workspace run as this same user, so a kill by name or en masse can end all of them at once. Look first with `pgrep -af <pattern>`, then `kill <pid>` the explicit pids that belong to this task.\n' "$1" >&2
+  exit 2
+}
+
+refuse() {
+  printf 'Blocked by Tarfa: %s Every workspace runs as this same user, so a receiving session cannot tell such a message from a real one. Message a workspace with `tarfa send <id> "…"` and start a child with `tarfa spawn --child`.\n' "$1" >&2
+  exit 2
+}
+
+word_end='([[:space:])}"'"'"'`]|$)'
+# tmux accepts any unambiguous prefix of a command name; kill-ser is the shortest for kill-server.
+kill_server_re="[[:space:]]kill-ser[a-z]*$word_end"
+kill_others_re="[[:space:]]kill-session([[:space:]].*)?[[:space:]]-a$word_end"
+shell_c_re='^([^[:space:]]*/)?(ba|z|da)?sh([[:space:]]+-[a-zA-Z]+)*[[:space:]]+-[a-zA-Z]*c[[:space:]]+'
+has_socket_flag() { [[ $1 =~ (^|[[:space:]])-[A-Za-z]*[SL]([[:space:]]|[^[:space:]]|$) ]]; }
+
+# Another session's message socket: Claude Code's, the Tarfa inbox Pi reads, the Codex app server.
+inbox_re='(cc-socks/|\.(tarfa|perch)/inbox/|app-server-control/)'
+# tmux takes `set`, `setw` and any prefix of `set-option` or `set-window-option`; a window option
+# answers `#{@tarfa_parent}` as well as a session option does.
+reparent_re='[[:space:]](set|setw|set-o[a-z]*|set-w[a-z-]*)[[:space:]].*@(tarfa|perch)_(parent|codex_thread)([^[:alnum:]_]|$)'
+
+# A pid list computed from a name is a kill by name.
+pgrep_kill_re='(^|[^[:alnum:]_-])kill[[:space:]][^;&|]*(\$\(|`)[[:space:]]*(pgrep|pidof)([[:space:]]|$)'
+[[ $cmd =~ $pgrep_kill_re ]] && deny 'kill $(pgrep …) kills by name.'
+
+# One simple command per line: split on separators outside quotes, so a quoted `a|pkill|b`
+# (a grep pattern, a commit message) stays one argument. `$(` and a backquote split inside
+# double quotes too, since they run there. Newlines inside quotes become spaces.
+segments() {
+  printf '%s' "$1" | LC_ALL=C awk -v sq="'" '
+    BEGIN { RS = "\001" }
+    {
+      n = length($0); q = ""; out = ""
+      for (i = 1; i <= n; i++) {
+        c = substr($0, i, 1); c2 = substr($0, i, 2)
+        if (q == sq) { if (c == sq) q = ""; out = out (c == "\n" ? " " : c); continue }
+        if (c == "\\") { out = out (c2 == "\\\n" ? " " : c2); i++; continue }
+        if (c2 == "$(") { print out; out = ""; i++; continue }
+        if (c == "`") { print out; out = ""; continue }
+        if (q == "\"") { if (c == "\"") q = ""; out = out (c == "\n" ? " " : c); continue }
+        if (c == sq || c == "\"") { q = c; out = out c; continue }
+        if (c2 == "&&" || c2 == "||") { print out; out = ""; i++; continue }
+        if (c == ";" || c == "|" || c == "&" || c == "\n") { print out; out = ""; continue }
+        out = out c
+      }
+      print out
+    }'
+}
+
+check() {
+local seg s word payload args i
+while IFS= read -r seg; do
+  s="$seg"
+  # Strip what can precede the command word: grouping, keywords, VAR=value, wrappers, and a
+  # `sh -c '` prefix (later commands inside the wrapper arrive as their own segments).
+  while :; do
+    s="${s#"${s%%[![:space:]]*}"}"
+    case "$s" in
+      '('* | '{'* | '!'* | \'* | '"'* | '`'*) s="${s:1}" ;;
+      then\ * | do\ * | else\ * | time\ * | exec\ * | sudo\ * | command\ * | nohup\ * | nice\ * | setsid\ *) s="${s#* }" ;;
+      timeout\ *)
+        s="${s#timeout }"
+        while [[ $s =~ ^[[:space:]]*(-[^[:space:]]+)[[:space:]]+ ]]; do s="${s:${#BASH_REMATCH[0]}}"; done
+        [[ $s =~ ^[[:space:]]*[0-9.]+[smhd]?[[:space:]]+ ]] && s="${s:${#BASH_REMATCH[0]}}"
+        ;;
+      env\ *)
+        s="${s#env }"
+        while [[ $s =~ ^[[:space:]]*(-u[[:space:]]+[^[:space:]]+|-[^[:space:]]+)[[:space:]]+ ]]; do
+          s="${s:${#BASH_REMATCH[0]}}"
+        done
+        ;;
+      *)
+        if [[ $s =~ $shell_c_re ]]; then
+          s="${s:${#BASH_REMATCH[0]}}"
+          # A quoted script is a command line of its own: check every command in it.
+          case "$s" in
+            \'*) payload="${s:1}"; check "${payload%%\'*}"; continue 2 ;;
+            '"'*) payload="${s:1}"; check "${payload%%\"*}"; continue 2 ;;
+          esac
+        elif [[ $s =~ ^[A-Za-z_][A-Za-z0-9_]*=(\"[^\"]*\"|\'[^\']*\'|[^[:space:]]*)[[:space:]]+ ]]; then
+          s="${s:${#BASH_REMATCH[0]}}"
+        else
+          break
+        fi
+        ;;
+    esac
+  done
+
+  word=${s%%[[:space:]]*}
+  word=${word##*/}
+  word=${word%%[\"\']*}
+  case "$word" in
+    pkill) deny 'pkill kills by name.' ;;
+    killall) deny 'killall kills by name.' ;;
+    xargs) [[ $s =~ [[:space:]]kill([[:space:]]|$) ]] && deny 'xargs kill kills a computed pid list.' ;;
+    kill)
+      # `-1` as a target (not the first argument, where it names a signal) is every process.
+      read -ra args <<< "${s#kill}"
+      for ((i = 1; i < ${#args[@]}; i++)); do
+        [ "${args[i]}" = "-1" ] && deny 'kill -1 signals every process you own.'
+      done
+      ;;
+    nc | nc.* | ncat | netcat | socat | curl | websocat)
+      [[ $s =~ $inbox_re ]] && refuse "$word would write to another session's message socket directly, past the header and sender check that tarfa send puts on every message."
+      ;;
+    tmux)
+      has_socket_flag "$s" && continue
+      [[ $s =~ $reparent_re ]] && refuse 'Setting @tarfa_parent or @tarfa_codex_thread by hand changes which workspace the agent treats as an orchestrator or a Codex thread, so messages would carry authority nobody granted.'
+      [[ $s =~ $kill_server_re ]] && deny 'tmux kill-server without -S/-L ends the shared tmux server every workspace runs in.'
+      [[ $s =~ $kill_others_re ]] && deny 'tmux kill-session -a kills every other workspace; kill one by its exact name with -t '\''=<name>'\''.'
+      ;;
+  esac
+done < <(segments "$1")
+}
+
+check "$cmd"
+exit 0

package/src/hooks/tarfa-hook.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Tarfa hook for Claude Code and Codex: notify the local agent of an attention event.
+# Usage: tarfa-hook.sh <Event> <port> [agent]   (the CLI's JSON payload arrives on stdin)
+# `agent` names a CLI other than Claude Code (`codex`). It is spliced into the JSON body without
+# escaping, so only a plain lowercase name is passed on.
+event="$1"
+port="${2:-8787}"
+agent_field=""
+[[ "${3:-}" =~ ^[a-z]+$ ]] && agent_field=",\"agent\":\"$3\""
+# The workspace is the tmux session of the pane this hook runs in, and the hook names no session
+# unless it can prove which one that is. TMUX and TMUX_PANE alone prove nothing: Codex runs its
+# hooks in a shared background server that kept the environment of whichever pane started it,
+# and an untargeted `tmux display-message` falls back to the most recently active session. Either
+# would stamp the status onto an unrelated workspace, so the pane's own process must be one of
+# this script's ancestors.
+pane_session() {
+  [ -z "${TMUX:-}" ] || [ -z "${TMUX_PANE:-}" ] && return 1
+  local pane_pid session pid
+  read -r pane_pid session < <(tmux display-message -p -t "${TMUX_PANE}" '#{pane_pid} #S' 2>/dev/null)
+  [ -z "${session:-}" ] && return 1
+  pid=$$
+  for _ in $(seq 1 32); do
+    [ "${pid}" = "${pane_pid}" ] && break
+    pid="$(ps -o ppid= -p "${pid}" 2>/dev/null | tr -d ' ')"
+    [ -z "${pid}" ] || [ "${pid}" -le 1 ] && return 1
+  done
+  [ "${pid}" = "${pane_pid}" ] || return 1
+  printf '%s' "${session}"
+}
+# Claude's payload is forwarded verbatim as a nested object so the agent can read
+# `background_tasks` without this script needing jq (not installed on every agent machine) or
+# any bash JSON parsing. The tty check keeps a hand-run hook from blocking forever on stdin.
+payload=null
+[ -t 0 ] || payload="$(cat)"
+[ -z "$payload" ] && payload=null
+if session="$(pane_session)"; then
+  target="\"sessionName\":\"${session}\""
+elif [ "${3:-}" = codex ] && [[ "${payload}" =~ \"session_id\"[[:space:]]*:[[:space:]]*\"([0-9A-Za-z-]+)\" ]]; then
+  # A Codex bound to the app-server daemon runs hooks in the daemon, under no pane; its
+  # session_id is the thread id the agent recorded for the workspace, and the agent maps it.
+  # Only id characters are taken, since the value is spliced into the body unescaped.
+  target="\"thread\":\"${BASH_REMATCH[1]}\""
+else
+  exit 0
+fi
+token=""
+[ -r "${HOME}/.tarfa/token" ] && token="$(cat "${HOME}/.tarfa/token")"
+# Every local user can read a process's argv, so the secret goes in as a header file and the body
+# on stdin: `printf` is a shell builtin and puts neither on any command line.
+printf '{%s,"event":"%s"%s,"claude":%s}' "${target}" "${event}" "${agent_field}" "${payload}" |
+  curl -s -m 2 -X POST "http://127.0.0.1:${port}/hooks" \
+    -H 'content-type: application/json' \
+    -H @<(printf 'authorization: Bearer %s\n' "${token}") \
+    --data-binary @- >/dev/null 2>&1 || true
+exit 0

package/templates/app.tarfa.agent.plist

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>app.tarfa.agent</string>
+  <key>ProgramArguments</key>
+  <array>
+    AGENT_ARGUMENTS
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>LOG_DIR/agent.log</string>
+  <key>StandardErrorPath</key><string>LOG_DIR/agent.err.log</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+</dict>
+</plist>

package/templates/tarfa-agent.service

@@ -0,0 +1,16 @@
+[Unit]
+Description=Tarfa agent
+After=network-online.target
+
+[Service]
+ExecStart=AGENT_COMMAND
+Restart=always
+RestartSec=3
+# The agent spawns the tmux server as a child, so it lives in this unit's
+# cgroup. With the default KillMode=control-group a restart would SIGTERM the
+# whole cgroup and kill every workspace session. KillMode=process stops only
+# the agent, leaving the tmux server and its sessions running across restarts.
+KillMode=process
+
+[Install]
+WantedBy=default.target

package/templates/tarfa-agent.sh

@@ -0,0 +1,49 @@
+#!/bin/sh
+# The agent service's stable entry point: the unit or plist names this file, never a versioned
+# path, so upgrading the package changes what runs without touching the service definition.
+set -eu
+# Kept apart from $HOME: agent.env is sourced below, and a HOME= line there must not move the lookups.
+home="$HOME"
+state="$home/.tarfa"
+if [ ! -f "$state/agent.env" ]; then
+  echo "tarfa-agent: $state/agent.env is missing: run tarfa setup" >&2
+  exit 1
+fi
+set -a
+# shellcheck disable=SC1091
+. "$state/agent.env"
+set +a
+TARFA_AGENT_ENV="$state/agent.env"
+export TARFA_AGENT_ENV
+
+# A checkout named by agent-source runs instead of the release (deploy/serve-agent.sh writes it).
+# A path that is gone, say a removed worktree, must not crash-loop the service.
+if [ -f "$state/agent-source" ]; then
+  checkout=""
+  IFS= read -r checkout < "$state/agent-source" || true
+  if [ -n "$checkout" ] && [ -f "$checkout/deploy/run-agent.sh" ]; then
+    exec bash "$checkout/deploy/run-agent.sh"
+  fi
+  echo "tarfa-agent: $state/agent-source names $checkout, which has no deploy/run-agent.sh; running the released agent" >&2
+fi
+
+# Service managers do not inherit an interactive PATH, so find mise as deploy/run-agent.sh does.
+# From $home, so no project's mise.toml picks the runtime.
+cd "$home"
+# `mise exec` would install every tool missing from the global config before starting the agent:
+# slow, and a tool that cannot install would block it for good. So run the installed package with
+# its node directly, as the tarfa wrapper does, and keep mise's shims on PATH for what the agent's
+# panes and child tools run.
+PATH="$home/.local/bin:${MISE_DATA_DIR:-$home/.local/share/mise}/shims:$PATH"
+export PATH
+for mise_bin in "$home/.local/bin/mise" /opt/homebrew/bin/mise /usr/local/bin/mise; do
+  if [ -x "$mise_bin" ]; then
+    install="$("$mise_bin" --cd "$home" where npm:@tarfa/cli 2>/dev/null || true)"
+    node_home="$("$mise_bin" --cd "$home" where node 2>/dev/null || true)"
+    if [ -n "$install" ] && [ -n "$node_home" ] && [ -x "$node_home/bin/node" ] && [ -f "$install/bin/tarfa" ]; then
+      exec "$node_home/bin/node" "$install/bin/tarfa" serve
+    fi
+    exec "$mise_bin" exec -- tarfa serve
+  fi
+done
+exec tarfa serve

package/templates/tarfa-cli-wrapper.sh

@@ -0,0 +1,48 @@
+#!/bin/sh
+# tarfa-cli-wrapper (managed by tarfa): written by `tarfa setup` and `tarfa apply`, replaced when
+# it differs. Runs the installed @tarfa/cli from the caller's own folder, so `tarfa spawn .` means
+# the caller's project, whatever mise config that folder holds.
+#
+# The install and its node are looked up from $HOME: a mise shim would take the caller's folder's
+# mise.toml, which dies with a trust error in an untrusted folder and runs Tarfa under that
+# project's node in a trusted one.
+set -u
+
+mise_bin=""
+for candidate in "$HOME/.local/bin/mise" /opt/homebrew/bin/mise /usr/local/bin/mise; do
+  if [ -x "$candidate" ]; then
+    mise_bin="$candidate"
+    break
+  fi
+done
+if [ -z "$mise_bin" ]; then
+  mise_bin="$(command -v mise 2>/dev/null || true)"
+fi
+
+if [ -n "$mise_bin" ]; then
+  install="$("$mise_bin" --cd "$HOME" where npm:@tarfa/cli 2>/dev/null || true)"
+  node_home="$("$mise_bin" --cd "$HOME" where node 2>/dev/null || true)"
+  if [ -n "$install" ] && [ -n "$node_home" ] && [ -x "$node_home/bin/node" ] && [ -f "$install/bin/tarfa" ]; then
+    exec "$node_home/bin/node" "$install/bin/tarfa" "$@"
+  fi
+fi
+
+# No mise, or it knows no install: the next tarfa on PATH that is not this file.
+if [ -n "${TARFA_CLI_WRAPPER:-}" ]; then
+  echo "tarfa: no installed @tarfa/cli found (mise use -g npm:@tarfa/cli)" >&2
+  exit 1
+fi
+TARFA_CLI_WRAPPER=1
+export TARFA_CLI_WRAPPER
+old_ifs="$IFS"
+IFS=:
+for dir in $PATH; do
+  candidate="${dir:-.}/tarfa"
+  if [ -f "$candidate" ] && [ -x "$candidate" ] && ! [ "$candidate" -ef "$0" ]; then
+    IFS="$old_ifs"
+    exec "$candidate" "$@"
+  fi
+done
+IFS="$old_ifs"
+echo "tarfa: no installed @tarfa/cli found (mise use -g npm:@tarfa/cli)" >&2
+exit 1

package/README.md

@@ -1,3 +0,0 @@
-# @tarfa/cli
-
-Placeholder for the Tarfa CLI and agent. The first release is coming.