@basein/runner 0.2.12 → 0.3.0

package/scripts/install.ps1

@@ -45,6 +45,12 @@
       BIR_NODE_ARCHIVE  a local node-v<V>-win-<arch>.zip instead of the download
       BIR_TARBALL       a local @basein/runner .tgz instead of the registry
       BIR_NO_CLAUDE=1   do not install Claude Code
+      BIR_UNINSTALL=1   the other direction: `bir uninstall --all` - every
+                        project on this machine put back as it was, every
+                        recorder stopped - so ~\.baseinstrunner can be deleted
+                        without breaking anything. Downloads nothing, needs no
+                        folder and no token:
+                          $env:BIR_UNINSTALL="1"; irm https://api.<domain>/install.ps1 | iex
       BIR_DRY_RUN=1     print every action and perform none: no download, no
                         install, no registry write, no `bir setup`. For support:
                         it shows what the line would do on a given machine.
@@ -167,13 +173,44 @@ function Invoke-BirInstall {
         return $null
     }
 
-    # --use-system-ca exists from Node 22.15; with it a corporate root in the
-    # Windows store is trusted without NODE_EXTRA_CA_CERTS.
+    # --use-system-ca exists from Node 22.15, 23.8 and 24 (not 23.0-23.7, which
+    # exit on it as a bad option); with it a corporate root in the Windows store
+    # is trusted without NODE_EXTRA_CA_CERTS. The version table is for a Node
+    # not on disk yet (the private one, in a dry run); a node that exists is
+    # asked instead (Get-SystemCaFlags).
     function Get-NodeFlags([int]$Major, [int]$Minor) {
-        if (($Major -gt 22) -or ($Major -eq 22 -and $Minor -ge 15)) { return @('--use-system-ca') }
+        if (($Major -ge 24) -or ($Major -eq 23 -and $Minor -ge 8) -or ($Major -eq 22 -and $Minor -ge 15)) { return @('--use-system-ca') }
         return @()
     }
 
+    # True when this node binary accepts a flag: it is asked, not guessed from a
+    # version. Node's fetch ignores HTTPS_PROXY unless started with
+    # --use-env-proxy (recent Node 22 and 24 have it), so behind a proxy-only
+    # network every call the runner makes would wait out a connect timeout.
+    function Test-NodeFlag([string]$NodeExe, [string]$Flag) {
+        if (-not $NodeExe -or -not (Test-Path -LiteralPath $NodeExe -PathType Leaf)) { return $false }
+        $r = Invoke-Tool $NodeExe @($Flag, '-e', '0') -Quiet
+        return ($r.Code -eq 0)
+    }
+
+    # True when NO_PROXY sends 127.0.0.1 past the proxy. With --use-env-proxy
+    # Node sends the runner's own loopback calls to the proxy too - the hooks'
+    # recorder, a proxy registering, `bir setup` waiting for the recorder -
+    # unless NO_PROXY names 127.0.0.1, '*', or a suffix of it such as .0.0.1
+    # ('localhost' alone is not enough). Windows has one variable for both
+    # spellings.
+    function Test-LoopbackBypassesProxy {
+        $value = $env:NO_PROXY
+        if (-not $value -or -not $value.Trim()) { return $false }
+        foreach ($entry in ($value -split '[\s,]+')) {
+            $e = $entry.Trim().ToLowerInvariant()
+            if (-not $e) { continue }
+            if ($e -eq '*' -or $e -eq '127.0.0.1') { return $true }
+            if ($e.StartsWith('.') -and '127.0.0.1'.EndsWith($e)) { return $true }
+        }
+        return $false
+    }
+
     # A per-shell or per-version directory: fnm's multishell links vanish with
     # the shell, and nvm, Volta, Scoop, asdf and mise switch or remove versions
     # under the same path. The SessionStart hook pins an absolute node path, so
@@ -394,6 +431,40 @@ public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, UIntPtr wP
     try {
         if ($dryRun) { Write-Warn 'BIR_DRY_RUN=1: printing what would happen; nothing is downloaded, installed or written.' }
 
+        # -- uninstall mode ---------------------------------------------------------
+        #
+        # BIR_UNINSTALL=1: undo `bir setup` in every project on this machine
+        # before its files go. Every wrapped MCP server and every hook names a
+        # file under ~\.baseinstrunner; deleting that first would break them
+        # all, in every project, with no `bir` left to repair it.
+        if ($env:BIR_UNINSTALL -eq '1') {
+            Write-Step 'Removing the runner from every project on this machine'
+            $birCmd = Join-Path $birHome 'bin\bir.cmd'
+            if (-not (Test-Path -LiteralPath $birCmd -PathType Leaf)) {
+                # A global npm install: its .cmd shim, never the .ps1 one, which
+                # the execution policy may refuse.
+                $found = @(Get-Command 'bir.cmd' -CommandType Application -ErrorAction SilentlyContinue)
+                if ($found.Count -ge 1) { $birCmd = $found[0].Source } else { $birCmd = '' }
+            }
+            if (-not $birCmd) {
+                Write-Note "bir is not installed here ($birHome\bin\bir.cmd is missing), so nothing on this machine is wired to this install."
+                Write-Note "If $birHome is still there, it can be deleted."
+                return
+            }
+            if ($dryRun) {
+                Write-Would "run: $birCmd uninstall --all"
+                return
+            }
+            $r = Invoke-Tool $birCmd @('uninstall', '--all')
+            if ($r.Code -ne 0) {
+                throw "bir uninstall --all could not undo everything (the lines above say what). Keep $birHome until it can: those entries still name files in it."
+            }
+            Write-Step 'Done: nothing on this machine runs through the runner now'
+            Write-Note "To delete its files too:  Remove-Item -Recurse -Force `"$birHome`""
+            Write-Note "and take $birHome\bin off your user Path (Settings, Environment Variables)."
+            return
+        }
+
         # -- 00. the folder, before anything is downloaded ----------------------
         #
         # A terminal opened from Start begins in the home folder, and that is
@@ -486,9 +557,13 @@ public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, UIntPtr wP
                     else {
                         $nodeExe = $realPath
                         $npmCli = $candidateCli
-                        # @(...) around the call: a one-element array unrolls to a
-                        # string on assignment, and string + array is one string.
-                        $nodeFlags = @(Get-NodeFlags $parts.Major $parts.Minor)
+                        # This node exists, so it is asked whether it knows the
+                        # flag rather than trusted to by its version: a 23.0-23.7
+                        # exits on it, and the npm install below would fail.
+                        # @(...) around the value: a one-element array unrolls to
+                        # a string on assignment, and string + array is one string.
+                        $nodeFlags = @()
+                        if (Test-NodeFlag $realPath '--use-system-ca') { $nodeFlags = @('--use-system-ca') }
                         Write-Note "node v$($parts.Text) at $realPath"
                     }
                 }
@@ -558,6 +633,22 @@ public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, UIntPtr wP
         Write-Step 'Putting bir on your PATH'
         $binDir = Join-Path $birHome 'bin'
         if (-not $dryRun) { New-Item -ItemType Directory -Path $binDir -Force | Out-Null }
+        # Behind a proxy, `bir` and everything it wires (proxies, hooks, the
+        # recorder) carry --use-env-proxy too, when this Node knows it AND
+        # NO_PROXY exempts 127.0.0.1: without that the flag would send the
+        # runner's own loopback calls to the proxy and break every hook, where
+        # leaving it out only costs reaching the service. npm needs nothing, it
+        # reads HTTPS_PROXY itself.
+        if ($proxy -and -not (Test-LoopbackBypassesProxy)) {
+            Write-Note 'HTTPS_PROXY is set but NO_PROXY does not name 127.0.0.1, so the runner will not use the proxy (it would swallow its own loopback calls). To use it: set NO_PROXY=127.0.0.1,localhost,::1 (plus your own entries) and run this again'
+        }
+        elseif ($proxy -and (Test-NodeFlag $nodeExe '--use-env-proxy')) {
+            $nodeFlags = @($nodeFlags) + @('--use-env-proxy')
+            Write-Note 'node runs with --use-env-proxy, so the runner reaches the service through the proxy'
+        }
+        elseif ($proxy) {
+            Write-Note 'this node has no --use-env-proxy; the runner itself will not use the proxy (a newer Node 22 or 24 has the flag)'
+        }
         # The launchers carry the same node flags this run used, so a `bir setup`
         # typed later - and everything it wires - trusts the same certificates.
         Write-Launcher (Join-Path $binDir 'bir.cmd') $nodeExe $nodeFlags $birJs

package/scripts/install.sh

@@ -28,6 +28,9 @@
 #
 # Safe to re-run; re-running is also the upgrade path. To record another project
 # later: cd there and run `bir setup` (no token needed, the sign-in is kept).
+# To take it out of every project before deleting it (BIR_UNINSTALL below):
+#
+#   curl -fsSL https://api.bi2202.com/install.sh | BIR_UNINSTALL=1 sh
 #
 # Environment:
 #   BIR_SETUP_TOKEN    one-time setup token from the console. Copied and removed
@@ -36,6 +39,8 @@
 #   BIR_AUTH_URL       the API address. Needed only when this is the raw file from
 #                      the repository — the copy the API serves has it filled in.
 #   BIR_VERSION        runner version to install (default: the served one, else latest).
+#                      Going back to an OLDER runner: run `bir uninstall --all` with
+#                      the one installed now first, then this line, then `bir setup`.
 #   BIR_PROJECT        the project directory (default: the current one).
 #   BIR_NODE_VERSION   private Node version (default 24.21.0). Any other version
 #                      is verified against nodejs.org's SHASUMS256.txt instead of
@@ -44,6 +49,10 @@
 #                      of the download (air-gapped machines). Still digest-checked.
 #   BIR_TARBALL        a local @basein/runner .tgz instead of the registry (air-gapped).
 #   BIR_NO_CLAUDE=1    do not install Claude Code.
+#   BIR_UNINSTALL=1    the other direction: `bir uninstall --all` — every project
+#                      on this machine put back as it was, every recorder stopped —
+#                      so ~/.baseinstrunner can be deleted without breaking anything.
+#                      Downloads nothing; needs no folder and no token.
 #   BIR_DRY_RUN=1      print every action; download, install and write nothing.
 #   HTTPS_PROXY, HTTP_PROXY, NO_PROXY, NODE_EXTRA_CA_CERTS pass through to node and npm.
 #
@@ -79,6 +88,31 @@ ver_minor() {
   printf '%s\n' "$_v"
 }
 
+# True when NO_PROXY (either spelling) sends 127.0.0.1 past the proxy. With
+# --use-env-proxy Node sends the runner's own loopback calls to the proxy too -
+# the hooks' recorder, a proxy registering, `bir setup` waiting for the
+# recorder - unless NO_PROXY names 127.0.0.1, '*', or a suffix of it such as
+# .0.0.1 ('localhost' alone is not enough). Every spelling that is set must say
+# so: node and its fetch disagree on which one wins. A subshell, for set -f.
+loopback_bypasses_proxy() (
+  set -f
+  _seen=''
+  for _np in "${NO_PROXY:-}" "${no_proxy:-}"; do
+    [ -n "$(printf '%s' "$_np" | tr -d ' 	,')" ] || continue
+    _seen=1
+    _ok=''
+    for _e in $(printf '%s' "$_np" | tr ',' ' '); do
+      _e=$(printf '%s' "$_e" | tr '[:upper:]' '[:lower:]')
+      case "$_e" in
+        '*'|127.0.0.1) _ok=1 ;;
+        .*) case 127.0.0.1 in *"$_e") _ok=1 ;; esac ;;
+      esac
+    done
+    [ -n "$_ok" ] || exit 1
+  done
+  [ -n "$_seen" ]
+)
+
 # True when a Node of this version understands --use-system-ca: 22.15+, 23.8+, 24+.
 node_has_system_ca() {
   _maj=$(ver_major "$1"); _min=$(ver_minor "$1")
@@ -313,12 +347,44 @@ write_launcher() {
   mkdir -p "$bin_dir"
   # The launcher carries the node flag this run used (--use-system-ca when the
   # Node knows it), so a `bir setup` typed later trusts the same certificates.
-  printf '#!/bin/sh\nexec "%s"%s "%s/dist/bin/%s" "$@"\n' "$node_bin" "${system_ca:+ --use-system-ca}" "$runner_dir" "$2" > "$_launcher.tmp"
+  printf '#!/bin/sh\nexec "%s"%s%s "%s/dist/bin/%s" "$@"\n' "$node_bin" "${system_ca:+ --use-system-ca}" "${env_proxy:+ --use-env-proxy}" "$runner_dir" "$2" > "$_launcher.tmp"
   chmod +x "$_launcher.tmp"
   mv -f "$_launcher.tmp" "$_launcher"
   note "$_launcher"
 }
 
+# BIR_UNINSTALL=1: undo `bir setup` in every project on this machine before its
+# files go. Every wrapped MCP server and every hook names a file under
+# ~/.baseinstrunner; deleting that first would break them all, in every project,
+# with no `bir` left to repair it. Exits; nothing is downloaded.
+uninstall_everywhere() {
+  step "Removing the runner from every project on this machine"
+  if [ -x "$bin_dir/bir" ]; then
+    bir_cmd="$bin_dir/bir"
+  elif command -v bir >/dev/null 2>&1; then
+    bir_cmd=$(command -v bir)
+  else
+    note "bir is not installed here ($bin_dir/bir is missing), so nothing on this machine is wired to this install."
+    note "If $bir_home is still there, it can be deleted."
+    exit 0
+  fi
+  if [ "$DRY_RUN" = 1 ]; then
+    dry "\"$bir_cmd\" uninstall --all"
+    exit 0
+  fi
+  un_rc=0
+  "$bir_cmd" uninstall --all || un_rc=$?
+  printf '\n'
+  if [ "$un_rc" -ne 0 ]; then
+    printf '%serror: %s%s\n' "$C_ERR" "bir uninstall --all could not undo everything (the lines above say what). Keep $bir_home until it can: those entries still name files in it." "$C_OFF" >&2
+    exit "$un_rc"
+  fi
+  step "Done: nothing on this machine runs through the runner now"
+  note "To delete its files too:  rm -rf \"$bir_home\""
+  note "and remove this line from your shell profile:  $path_line"
+  exit 0
+}
+
 # find_claude → the path of `claude`, from PATH or the native installer's
 # ~/.local/bin. Fails when there is none.
 find_claude() {
@@ -373,6 +439,11 @@ main() {
   # shellcheck disable=SC2016
   path_line='export PATH="$HOME/.baseinstrunner/bin:$PATH"'
 
+  if [ "${BIR_UNINSTALL:-}" = 1 ]; then
+    if [ "$DRY_RUN" = 1 ]; then note "dry run (BIR_DRY_RUN=1): nothing is changed"; fi
+    uninstall_everywhere
+  fi
+
   # 00. The folder — before anything is downloaded. A terminal opened from the
   #     Dock or the applications menu starts in the home directory, and that is
   #     where a first paste tends to land.
@@ -454,6 +525,25 @@ main() {
   # where a company CA usually is. Older Nodes need NODE_EXTRA_CA_CERTS.
   system_ca=''
   if node_has_system_ca "$node_ver"; then system_ca=1; fi
+  # Node's fetch ignores HTTPS_PROXY unless node runs with --use-env-proxy, so
+  # behind a proxy-only network every call the runner makes would wait out a
+  # connect timeout. The node is asked whether it knows the flag, not guessed
+  # from a version; the launchers and `bir setup` (and so everything it wires)
+  # carry it. Only when NO_PROXY exempts 127.0.0.1, though: otherwise the flag
+  # sends the runner's own loopback calls to the proxy and breaks every hook,
+  # where leaving it out only costs reaching the service. npm needs nothing: it
+  # reads HTTPS_PROXY itself.
+  env_proxy=''
+  if [ -n "${HTTPS_PROXY:-}${https_proxy:-}${HTTP_PROXY:-}${http_proxy:-}" ] && ! loopback_bypasses_proxy; then
+    note "HTTPS_PROXY is set but NO_PROXY does not name 127.0.0.1, so the runner will not use the proxy (it would swallow its own loopback calls). To use it: set NO_PROXY=127.0.0.1,localhost,::1 (plus your own entries) and run this again"
+  elif [ -n "${HTTPS_PROXY:-}${https_proxy:-}${HTTP_PROXY:-}${http_proxy:-}" ] && [ -x "$node_bin" ]; then
+    if "$node_bin" --use-env-proxy -e 0 >/dev/null 2>&1; then
+      env_proxy=1
+      note "node runs with --use-env-proxy, so the runner reaches the service through the proxy"
+    else
+      note "this node has no --use-env-proxy; the runner itself will not use the proxy (a newer Node 22 or 24 has the flag)"
+    fi
+  fi
 
   # 2. The runner — one code path for both Nodes: always the private prefix,
   #    never the machine's (root-owned after a .pkg or apt install; per-version
@@ -471,6 +561,10 @@ main() {
   note "into $prefix (the machine's npm prefix is left alone; no sudo)"
   runner_dir="$prefix/lib/node_modules/$PACKAGE"
   runner_js="$runner_dir/dist/bin/bir.js"
+  if [ -n "${BIR_VERSION:-}" ] && [ -f "$runner_dir/package.json" ]; then
+    # A rollback: an older runner cannot read everything a newer one wrote.
+    note "BIR_VERSION=$BIR_VERSION replaces the runner installed now. Going back to an OLDER one? Run: bir uninstall --all (with the current one) first"
+  fi
   if [ "$DRY_RUN" = 1 ]; then
     dry "\"$node_bin\"${system_ca:+ --use-system-ca} \"$npm_cli\" install -g --prefix \"$prefix\" --no-fund --no-audit $spec"
   else
@@ -548,19 +642,22 @@ main() {
   fi
 
   # 4. Setup: sign in, wire the project, start the recorder. The token goes into
-  #    this child's environment and nowhere else.
+  #    this child's environment and nowhere else. The PHYSICAL project path
+  #    (pwd -P): setup, the recorder and Claude Code all key the project by the
+  #    resolved path, and a symlinked one (macOS's /tmp, a linked ~/code) made
+  #    setup wait for a recorder it was looking for under the other spelling.
   step "Setting up the runner in $project"
   setup_rc=0
   if [ "$DRY_RUN" = 1 ]; then
     token_note=''
     if [ -n "$setup_token" ]; then token_note=' (with BIR_SETUP_TOKEN in its environment)'; fi
-    dry "\"$node_bin\"${system_ca:+ --use-system-ca} \"$runner_js\" setup --auth-url $auth_url --project \"$project\"$token_note"
+    dry "\"$node_bin\"${system_ca:+ --use-system-ca}${env_proxy:+ --use-env-proxy} \"$runner_js\" setup --auth-url $auth_url --project \"$project_phys\"$token_note"
   elif [ -n "$setup_token" ]; then
-    BIR_SETUP_TOKEN=$setup_token "$node_bin" ${system_ca:+--use-system-ca} "$runner_js" setup \
-      --auth-url "$auth_url" --project "$project" || setup_rc=$?
+    BIR_SETUP_TOKEN=$setup_token "$node_bin" ${system_ca:+--use-system-ca} ${env_proxy:+--use-env-proxy} "$runner_js" setup \
+      --auth-url "$auth_url" --project "$project_phys" || setup_rc=$?
   else
-    "$node_bin" ${system_ca:+--use-system-ca} "$runner_js" setup \
-      --auth-url "$auth_url" --project "$project" || setup_rc=$?
+    "$node_bin" ${system_ca:+--use-system-ca} ${env_proxy:+--use-env-proxy} "$runner_js" setup \
+      --auth-url "$auth_url" --project "$project_phys" || setup_rc=$?
   fi
 
   printf '\n'