symbiot 0.39.0 → 0.40.1

package/README.md

@@ -89,7 +89,9 @@ it's already running just opens the existing window instead of starting a second
 copy (`SYMBIOT_FORCE_NEW=1` starts one anyway). If something else holds the port,
 it falls back to a free one.
 It works on **Linux, macOS and Windows**; with no Chromium-family browser to open
-the chrome-less window, it uses your default browser.
+the chrome-less window, it uses your default browser. On an Android phone it runs
+in Termux ([experimental](#on-your-phone-android-in-termux)), or as an
+[Android app](#the-android-app-apk) of its own.
 
 ### Every week, and at login
 
@@ -110,6 +112,95 @@ repo is now archived), without Electron:
   then opens that copy's window. Switch it off to remove the entry. It needs an
   installed Symbiot (`npm install -g symbiot`), not `npx`.
 
+### On your phone (Android, in Termux)
+
+Experimental, and not yet tried on a real phone. Symbiot is a Node CLI, so it runs
+in [Termux](https://termux.dev) (install it from F-Droid; the Play Store build is
+out of date) next to the coding agent you use there. It works on the repos on your
+phone, the same way it works on your computer's:
+
+```bash
+pkg install nodejs git gh termux-api        # gh: Approve opens the PR; termux-api: notifications
+npm install -g symbiot
+symbiot app                                 # opens in your phone's browser
+```
+
+- The app opens in Symbiot's Android app if it's installed (below), else in the
+  phone's browser (through `termux-open-url`), and is laid out
+  for a phone screen: Tasks, Agents (with your agent's questions), Approve and
+  Settings all work there. Set your agent command in Settings as on a computer
+  (Claude Code is detected if it's on Termux's `PATH`). "Add to Home screen" in
+  Chrome gives it an icon.
+- Clone repos into Termux's home (`~`), which Symbiot scans by default, along
+  with the home folders (`/root`, `/home/<you>`) of any Linux you run with
+  `proot-distro`. To reach
+  the phone's shared storage, run `termux-setup-storage` and add `~/storage/shared`
+  (or a folder in it) under Settings → Folders to scan.
+- **Write my week and notify me** sends an Android notification when the
+  `termux-api` package and the Termux:API app are installed.
+- **Start Symbiot in the background when the phone starts** writes a
+  [Termux:Boot](https://wiki.termux.com/wiki/Termux:Boot) script
+  (`~/.termux/boot/symbiot`) that takes a wake lock, so Android doesn't stop it.
+  Install Termux:Boot and open it once.
+- **Screens** can't capture the screen from Termux; **Load image** still works.
+
+### The Android app (APK)
+
+Experimental, and so far tried in the Android emulator (Android 14) and on one
+phone (a Galaxy A26, Android 16). The app is Symbiot on its own, with no Termux needed: Node, git and `gh`
+are inside it (the same builds Termux installs), and it shows Symbiot full screen
+with its own icon.
+
+- **Install:** on your phone, download `symbiot-aarch64.apk` from the
+  [latest release](https://github.com/GarthGhostai/symbiot/releases/latest)
+  (or copy `symbiot-<version>-aarch64.apk` over from a computer that built it)
+  and open it (allow your browser or file manager to install apps). Android may warn that the
+  app was built for an older version of Android. That's on purpose: it's what lets
+  an app run programs it carries, like Node and git, the same reason Termux does.
+  It also keeps the app off the Play Store.
+- **First start** unpacks Node, git and gh (a few seconds), then asks for **All
+  files access**, so it can find the repos in your phone's shared storage. It scans
+  shared storage (for example the folders Termux's `~/storage/shared` points at)
+  instead of a home folder. Until it has that access, the Map says so and has an
+  **Allow file access** button. Once you allow it and come back, the Map scans again.
+- **Its own Symbiot only sees shared storage.** Projects in Termux's home folder
+  (`~`) are private to Termux, and no other app can read them. Keep a project in
+  shared storage (in Termux, run `termux-setup-storage` once, then work under
+  `~/storage/shared`), or have the app show the Symbiot running in Termux (next
+  point). The repos on your computer aren't on the phone either, so clone the
+  ones you want.
+- **Your Termux projects: show the Symbiot running in Termux.** A Symbiot started
+  in Termux sees everything in its home folder and runs your agent there, and the
+  app can be its window. **Open Termux** (on the Map when it finds no repos, and
+  in Settings → Projects in Termux) copies a command that installs Node and
+  Symbiot in Termux if they're missing, then runs `symbiot app`. Paste it in
+  Termux (it also updates Symbiot there if it's older than the app's). Termux
+  then opens Symbiot's link in the app, as a `symbiot://` link that only the app
+  takes, and the app shows that Symbiot instead of its own, and stops its own. It
+  keeps doing so until you tap **Use the app's own Symbiot**. If that Symbiot
+  stops, the app says so and offers both buttons. If the page opens in your
+  browser instead, it offers **Open in the app**. Termux from
+  Google Play can't take commands from other apps (it
+  has no `RUN_COMMAND`), so the app can't start Symbiot there by itself.
+- It keeps running with its window closed (a quiet "Symbiot is running"
+  notification has **Stop**), so the weekly write-up, agent runs and Approve keep
+  going. **Start Symbiot in the background when the phone starts** and **Write my
+  week and notify me** work as they do on a computer, with Android notifications.
+  **Update & restart** updates it from npm, as on a computer.
+- **Your coding agent isn't inside it.** Keep running Claude Code (or your agent)
+  in Termux, on the same repos in shared storage, the way you do now.
+- **Screens:** no capture and no Map page (a phone has no desktop browser to
+  drive); **Load image** works.
+
+To build it yourself: `android/build.sh` (or `android/build.sh x86_64` for the
+emulator) writes `android/build/symbiot-<version>-<arch>.apk`. It needs Node, the
+Android SDK and a JDK 17 (or Docker). The script's header lists the details,
+including the signing key to keep (`~/.android/symbiot.jks`): an update has to be
+signed with the same key. Each release also builds the aarch64 APK and attaches it
+to a GitHub release tagged `apk-<version>`, signed with that same key once it's
+in the repo's `SYMBIOT_KEYSTORE_B64` and `SYMBIOT_KEYSTORE_PASS` secrets (see
+`.github/workflows/publish.yml`).
+
 ## Hand tasks to your coding agent: `symbiot push`
 
 ```bash
@@ -416,7 +507,53 @@ Hovering shows the pixel under the pointer. Each region keeps its position and s
 in the screenshot's own pixels, plus its **centre**, the point a click would aim at.
 **Copy blueprint** copies them as JSON; everything is also saved in
 `~/.config/symbiot/screens/screens.json` (next to each screen's PNG), where an
-agent or script can read it.
+agent or script can read it. Screenshots and that file are readable by you only.
+
+**A web page maps itself.** Type a site next to **Map page** (`gmail`,
+`github.com/pulls` or a full address) and Symbiot opens it in a hidden (headless)
+browser, takes its screenshot and marks every button, link and field on it by
+itself, named from the page (`Compose`, `Search mail`, …) with what each one is
+and a CSS selector to find it again. Nothing to bring to the front, nothing to
+drag. Only what you could click right now counts: anything hidden, below the
+fold or covered by something else is left out. **Press** on a region clicks it
+in that hidden browser and maps the page it leads to as a new screen, so map,
+press, map is how an agent finds its way around a site. **Type** on a field types
+your text into it there (replacing what was in it) and, with **Type, then Enter**
+ticked, presses Enter, which is how a search or a one-line form is sent; the
+result is mapped as a new screen too. The hidden browser stays open for five
+minutes after each map, press or type, so a press or type on the screen it just
+mapped carries on from that page as it is: type into a field without Enter, then
+press the form's own button (**Send**, **Next**) on the new screen. On an older
+screen, or once the browser has closed, it opens the page from its address again,
+and anything typed there is gone. Press and
+Type act on the real site, signed in as you, so they ask first, unless the site
+is under **Trusted sites** in Settings: there, they go ahead without asking, for
+you and for agents. A trusted site covers its subdomains (`google.com` covers
+`mail.google.com`), and only you add sites, in Settings (there's no command for
+an agent to do it). The hidden browser is your
+Chrome, Chromium, Edge or Brave, with a profile of its own
+(`~/.config/symbiot/browser`, separate from your everyday one). For a site behind
+a sign-in, **Sign in** opens it there as a normal window. Sign in once, close the
+window, and later maps are signed in. When a map lands on a sign-in page, Symbiot
+says so. It works for web pages only. A desktop app still needs **Capture screen**.
+
+From a terminal, or for your coding agent, the same thing prints JSON:
+
+```bash
+symbiot screens map gmail              # the screen's id, and each region's id, label, kind, centre and selector
+symbiot screens press <id> Compose --yes   # press a region (by id or label), map where it lands
+symbiot screens type <id> "Search mail" "invoice" --enter --yes   # type into a field, press Enter, map the result
+                                       # (--yes isn't needed on a site under Trusted sites in Settings)
+symbiot screens type <id> To "sam@example.com" --yes   # without --enter: the text stays in the field...
+symbiot screens press <new id> Send --yes  # ...for a press on the screen that just printed
+symbiot screens show <id>              # a saved screen's blueprint
+symbiot screens signin gmail           # sign in once, in Symbiot's browser window
+symbiot screens                        # list them
+```
+
+While the app is running, these commands use its hidden browser, so it stays
+open between them as it does in the app. Without the app, each command opens the
+browser and closes it when done.
 
 **More than one display?** Symbiot reads how your displays are laid out
 (`cosmic-randr`, `wlr-randr`, `kscreen-doctor` or `xrandr` on Linux, PowerShell on
@@ -435,7 +572,7 @@ on your real screen. It asks you to confirm every time, and can wait 3, 5 or 10
 seconds first so you can bring the right window to the front. It clicks with
 `cliclick` on macOS (`brew install cliclick`), with PowerShell on Windows (nothing to
 install), and on Linux with `xdotool` on X11 or `ydotool` on Wayland (which needs
-access to `/dev/uinput`, and `ydotoold` running for ydotool 1.x). Nothing types yet.
+access to `/dev/uinput`, and `ydotoold` running for ydotool 1.x). Nothing types on your real screen yet (Type works on a mapped web page only).
 
 Capture uses the screenshot tool your system has: `screencapture` on macOS,
 PowerShell on Windows, and on Linux `gnome-screenshot`, `spectacle`,

package/core.mjs

@@ -3,7 +3,7 @@
 import { execSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync } from "node:fs";
 
 // ---- config ---------------------------------------------------------------
 const CONFIG_DIR = join(homedir(), ".config", "symbiot");
@@ -31,6 +31,27 @@ function sh(cmd) {
 }
 // "Is this command available?": command -v on posix, where on win.
 function hasCmd(cmd) { try { return !!sh(process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`).trim(); } catch { return false; } }
+// A Chromium-family browser, per OS: the app's chrome-less --app window, and
+// Screens' hidden (headless) browser.
+function chromeBinary() {
+  const p = process.platform;
+  const exists = (f) => { try { return existsSync(f) ? f : null; } catch { return null; } };
+  if (p === "darwin") {
+    return ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium",
+      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"].map(exists).find(Boolean) || null;
+  }
+  if (p === "win32") {
+    const bases = [process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.LOCALAPPDATA].filter(Boolean);
+    const rels = ["Google\\Chrome\\Application\\chrome.exe", "Chromium\\Application\\chrome.exe",
+      "Microsoft\\Edge\\Application\\msedge.exe", "BraveSoftware\\Brave-Browser\\Application\\brave.exe"];
+    for (const base of bases) for (const r of rels) { const f = exists(join(base, r)); if (f) return f; }
+    const w = sh("where chrome 2>NUL").split(/\r?\n/).map((s) => s.trim()).find(Boolean);
+    return w || null;
+  }
+  return ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "brave-browser", "microsoft-edge"].find(hasCmd) || null;
+}
 // Working-tree state, incl. detecting a stale/old checkout (not new work).
 function repoState(repoPath) {
   const branch = sh(`git -C ${JSON.stringify(repoPath)} rev-parse --abbrev-ref HEAD 2>/dev/null`).trim();
@@ -50,4 +71,4 @@ function repoState(repoPath) {
   return { branch, dirty, del, mod, add, stale, staleBy, behind };
 }
 
-export { CONFIG_DIR, CONFIG_PATH, loadConfig, saveConfig, loadTasks, saveTasks, sh, hasCmd, repoState };
+export { CONFIG_DIR, CONFIG_PATH, loadConfig, saveConfig, loadTasks, saveTasks, sh, hasCmd, chromeBinary, repoState };

package/desktop.mjs

@@ -7,9 +7,14 @@
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, unlinkSync, readdirSync, statSync, chmodSync } from "node:fs";
 import { CONFIG_DIR, loadConfig, saveConfig, hasCmd } from "./core.mjs";
 
+// The Android app (android/) runs this same code with SYMBIOT_ANDROID_APP=1. Its
+// Java side posts the notifications and starts Symbiot at boot, so here it's an
+// OS of its own: "android-app" (Termux on Android is plain "android").
+const OS = process.env.SYMBIOT_ANDROID_APP === "1" ? "android-app" : process.platform;
+
 // ---- weekly write-up --------------------------------------------------------
 // config.weekly = { on, day (0 = Sunday … 6 = Saturday), hour (0-23), last (ms) }.
 // Each run saves the write-up to ~/.config/symbiot/weeks/<date>.md.
@@ -73,30 +78,39 @@ function startWeekly(produce) {
 
 // ---- desktop notification (no dependencies) ---------------------------------
 // [cmd, args] for this OS, or null when there's nothing to notify with.
-function notifyCmd(title, body, platform = process.platform) {
+function notifyCmd(title, body, platform = OS) {
   if (platform === "darwin") return ["osascript", ["-e", `display notification ${JSON.stringify(body)} with title ${JSON.stringify(title)}`]];
   if (platform === "win32") {
     const q = (s) => "'" + String(s).replace(/'/g, "''") + "'";
     return ["powershell", ["-NoProfile", "-WindowStyle", "Hidden", "-Command", `Add-Type -AssemblyName System.Windows.Forms; $n = New-Object System.Windows.Forms.NotifyIcon; $n.Icon = [System.Drawing.SystemIcons]::Information; $n.Visible = $true; $n.ShowBalloonTip(10000, ${q(title)}, ${q(body)}, 'Info'); Start-Sleep -Seconds 11; $n.Dispose()`]];
   }
+  // Android (Termux): termux-notification, from the termux-api package + the Termux:API app
+  if (platform === "android") return hasCmd("termux-notification") ? ["termux-notification", ["--id", "symbiot", "--title", title, "--content", body]] : null;
   return hasCmd("notify-send") ? ["notify-send", ["--app-name=Symbiot", title, body]] : null;
 }
-function desktopNotify(title, body) {
-  const c = notifyCmd(title, body); if (!c) return false;
+// In the app: a line in a file its service watches, and it posts the notification.
+function desktopNotify(title, body, platform = OS, dir = CONFIG_DIR) {
+  if (platform === "android-app") { try { mkdirSync(dir, { recursive: true }); appendFileSync(join(dir, "android-notify.jsonl"), JSON.stringify({ title, body }) + "\n"); return true; } catch { return false; } }
+  const c = notifyCmd(title, body, platform); if (!c) return false;
   try { const ch = spawn(c[0], c[1], { detached: true, stdio: "ignore" }); ch.on("error", () => {}); ch.unref(); return true; } catch { return false; }
 }
 
 // ---- start at login -----------------------------------------------------------
 // One file per OS, in the place that OS starts things from at login: an XDG
-// autostart entry (Linux), a LaunchAgent (macOS), the Startup folder (Windows).
+// autostart entry (Linux), a LaunchAgent (macOS), the Startup folder (Windows),
+// a Termux:Boot script (Android, run when the phone starts). The Android app
+// starts itself at boot while its flag file is there.
 // It runs `symbiot app` with SYMBIOT_NO_OPEN=1, so no window pops up. PATH is
 // saved too, so agents and git resolve as they do in your terminal.
-function autostartFile(platform = process.platform, home = homedir()) {
+function autostartFile(platform = OS, home = homedir()) {
+  if (platform === "android-app") return join(home, ".config", "symbiot", "android-boot");
   if (platform === "darwin") return join(home, "Library", "LaunchAgents", "co.symbiot.app.plist");
   if (platform === "win32") return join(home, "AppData", "Roaming", "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "symbiot.cmd");
+  if (platform === "android") return join(home, ".termux", "boot", "symbiot");
   return join(home, ".config", "autostart", "symbiot.desktop");
 }
-function autostartContent(node, script, platform = process.platform, path = process.env.PATH || "") {
+function autostartContent(node, script, platform = OS, path = process.env.PATH || "") {
+  if (platform === "android-app") return "While this file exists, Symbiot's Android app starts itself when the phone starts.\n";
   if (platform === "darwin") {
     const x = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
     return `<?xml version="1.0" encoding="UTF-8"?>
@@ -109,13 +123,19 @@ function autostartContent(node, script, platform = process.platform, path = proc
 </dict></plist>
 `;
   }
+  if (platform === "android") {
+    // sh single quotes; the wake lock stops Android from stopping Termux while Symbiot runs
+    const sq = (s) => "'" + String(s).replace(/'/g, "'\\''") + "'";
+    return ["#!/data/data/com.termux/files/usr/bin/sh", "command -v termux-wake-lock >/dev/null && termux-wake-lock",
+      "export SYMBIOT_NO_OPEN=1 PATH=" + sq(path), "exec " + sq(node) + " " + sq(script) + " app", ""].join("\n");
+  }
   if (platform === "win32") return ["@echo off", "set SYMBIOT_NO_OPEN=1", `start "Symbiot" /min "${node}" "${script}" app`, ""].join("\r\n");
   // Desktop Entry Exec quoting: double quotes, with " ` $ \ backslash-escaped
   const q = (s) => '"' + String(s).replace(/(["`$\\])/g, "\\$1") + '"';
   return ["[Desktop Entry]", "Type=Application", "Name=Symbiot", "Comment=Symbiot in the background: the weekly write-up and its notification",
     `Exec=env SYMBIOT_NO_OPEN=1 ${q("PATH=" + path)} ${q(node)} ${q(script)} app`, "Terminal=false", "NoDisplay=true", "X-GNOME-Autostart-enabled=true", ""].join("\n");
 }
-function autostartState() { const file = autostartFile(); return { on: existsSync(file), file }; }
+function autostartState() { const file = autostartFile(); return { on: existsSync(file), file, ...(OS === "android-app" ? { phone: "app" } : OS === "android" ? { phone: "termux" } : {}) }; }
 // `script` is index.mjs's real path. From npx that's a cache folder that goes
 // away, so it has to be installed for this to keep working.
 function setAutostart(on, script) {
@@ -125,6 +145,7 @@ function setAutostart(on, script) {
     if (/[\\/]_npx[\\/]/.test(String(script))) return { ...autostartState(), error: "Symbiot is running from npx. Install it first (npm install -g symbiot), then switch this on." };
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, autostartContent(process.execPath, script));
+    if (OS === "android") chmodSync(file, 0o700); // Termux:Boot only runs executable scripts
     return autostartState();
   } catch (e) { return { ...autostartState(), error: String((e && e.message) || e) }; }
 }