haoleme 0.1.0__tar.gz

haoleme-0.1.0/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: haoleme
+Version: 0.1.0
+Summary: Run commands with Haoleme monitoring and expose their status to the mobile app.
+Author: Haoleme
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42
+Requires-Dist: qrcode>=7.4
+
+# 好了么
+
+好了么 is a command monitor for Linux/macOS machines with Android and iOS apps.
+
+The project has three parts:
+
+- `haoleme`: a Python package that installs the `hao` command. Put `hao` before a command to record its status, output tail, exit code, and timestamps.
+- `android/`: a native Android app for pairing, device switching, run history, console output, deletion, and finish notifications.
+- `ios/`: a native SwiftUI iOS app that uses the same 好了么 Cloud account, devices, runs, pairing, and console APIs.
+
+## Python monitor
+
+Install the local package in a virtual environment:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+```
+
+Or install the built wheel:
+
+```bash
+.venv/bin/python -m pip install dist/haoleme-0.1.0-py3-none-any.whl
+```
+
+Start the status server on the Linux machine:
+
+```bash
+hao server --host 0.0.0.0 --port 8765 --token change-this-token
+```
+
+Run commands through 好了么:
+
+```bash
+hao sleep 5
+hao run -- bash -lc 'echo hello && sleep 2 && echo done'
+hao status
+```
+
+The command name is intentionally short: `hao`.
+
+## Cloud sync
+
+The recommended setup is cloud sync. The Linux machine does not need a public IP, ngrok, or port forwarding. The command runner uploads status to 好了么 Cloud, and the Android app reads the same account from the cloud API.
+
+The default cloud relay is:
+
+```text
+http://106.14.246.204
+```
+
+After deploying the Docker cloud server on Aliyun or the Cloudflare Worker in `cloudflare/`, log in once on each new machine:
+
+```bash
+pip install -U haoleme
+hao login
+```
+
+The command prints a QR code and a 6-digit pair code. The cloud URL is built in and hidden from the normal UI. Pair codes expire after 5 minutes and are cancelled automatically when `hao login` exits without pairing.
+If the machine is already logged in, `hao login` asks before replacing the login. Press Enter to continue, or type `n` to cancel.
+
+```text
+847291
+```
+
+Tap Scan in the Android app to scan the QR code with the built-in camera scanner, or scan it with the phone camera to open 好了么 and pair automatically. If QR scanning is unavailable, enter the 6-digit code; the app pairs automatically when all 6 digits are entered. After pairing, the app saves the cloud account, shows the paired device name, and normal commands sync automatically:
+
+```bash
+hao run -- python train.py
+hao run -- sh -c 'for i in $(seq 1 10); do echo tick $i; sleep 1; done'
+```
+
+New pairings use end-to-end encryption for command text, working directory, and console output. 好了么 Cloud keeps the encrypted payload plus operational metadata such as device id, status, and timestamps, so filtering and online state still work while the sensitive run details are decrypted only in the app.
+
+Each computer that runs `hao login` is bound as a device on the same phone account. Use names such as `我的 Mac`, `服务器 A`, or `实验机 B`:
+
+```bash
+hao login --device "服务器 A"
+```
+
+The Android app shows an `All` device view plus one button for each paired computer, so you can switch between all runs and a single machine. Select one device and tap Rename, or long-press a device button, to rename it. Tap Revoke to disable that device's upload token without deleting old history.
+
+Useful cloud commands:
+
+```bash
+hao heartbeat status
+hao heartbeat start
+hao heartbeat stop
+hao cloud-status
+hao cloud-logout
+```
+
+After login, `hao` starts a small background heartbeat automatically. The cloud marks a device online when it has been seen in the last 90 seconds; each device sends a heartbeat every 60 seconds with a device-specific 0-59 second startup offset to avoid synchronized traffic spikes.
+
+Advanced/manual login is still available:
+
+```bash
+hao cloud-login --api-url https://your-haoleme-cloud.workers.dev --account ethan --token <TOKEN>
+```
+
+Cloud sync uses the app's account token as the account key. Anyone with that token can delete that account's run history and read unencrypted legacy records, so treat it like a password.
+
+### Deploy 好了么 Cloud with Docker
+
+The Docker cloud server exposes the same API as the Cloudflare Worker and stores data in SQLite:
+
+```bash
+docker build -f Dockerfile.cloud -t haoleme-cloud .
+docker run -d --name haoleme-cloud --restart unless-stopped \
+  -p 80:8000 \
+  -v /opt/haoleme-cloud-data:/data \
+  haoleme-cloud
+```
+
+Check it:
+
+```bash
+curl http://106.14.246.204/health
+```
+
+For production, prefer putting a domain and HTTPS reverse proxy in front of it. Plain HTTP works for quick testing because the Android app allows cleartext traffic, but HTTPS is safer.
+
+### Deploy 好了么 Cloud
+
+The included Cloudflare Worker is a small relay service. It stores only command metadata and output tails in Cloudflare KV. The Python runner also keeps a local SQLite database at `~/.reminder/reminder.db`, and the Android app caches the latest run list and console output locally so the previous results are visible when the app opens.
+
+```bash
+cd cloudflare
+npm create cloudflare@latest
+npx wrangler kv namespace create RUNS
+```
+
+Copy the returned KV namespace id into `cloudflare/wrangler.toml`, then deploy:
+
+```bash
+npx wrangler deploy
+```
+
+Cloudflare Workers can run this kind of small personal relay on the free plan within their free usage limits. For many users, long logs, or heavy polling, use a paid plan or a small VPS.
+
+The server exposes:
+
+- `GET /health`
+- `GET /api/runs?limit=50`
+- `GET /api/runs/{id}`
+- `GET /api/events?since=<updatedAt>`
+
+By default the SQLite database lives at `~/.reminder/reminder.db`. Set `REMINDER_HOME=/path/to/dir` to change that location.
+
+## Direct public access
+
+Direct public access is still supported for testing and compatibility. If you do not want cloud sync and do not have a public IP, use a Cloudflare quick tunnel:
+
+```bash
+hao public
+```
+
+This starts the local server and runs `cloudflared tunnel --url http://127.0.0.1:8765`. It prints a public `https://*.trycloudflare.com` URL and a token. Newer Android builds default to the built-in cloud pairing flow, so direct server entry is kept only for development and compatibility:
+
+```text
+Server: https://example.trycloudflare.com
+Token:  generated-token
+```
+
+If `cloudflared` is missing, install it first:
+
+```bash
+brew install cloudflared
+```
+
+Cloudflare quick tunnel URLs are random. If you need the same URL every time and do not own a domain, use ngrok's free Dev Domain:
+
+```bash
+brew install ngrok/ngrok/ngrok
+ngrok config add-authtoken <YOUR_NGROK_AUTHTOKEN>
+hao ngrok --domain <YOUR_DEV_DOMAIN>.ngrok-free.dev
+```
+
+Older Android builds with manual server entry can use:
+
+```text
+Server: https://<YOUR_DEV_DOMAIN>.ngrok-free.dev
+Token:  generated-token
+```
+
+If the Android app needs to connect to a server that already has a public IP or a public domain:
+
+```bash
+hao server --host 0.0.0.0 --port 8765 --token a-long-random-token
+```
+
+Then open TCP port `8765` in the cloud security group or firewall.
+
+In the Android app:
+
+```text
+Server: http://<public-ip>:8765
+Token:  a-long-random-token
+```
+
+For real public use, prefer HTTPS through a reverse proxy or tunnel. Plain `http://<public-ip>:8765` works for testing, but the token can be observed on an untrusted network.
+
+## Android app
+
+Open the `android/` directory in Android Studio.
+
+For an emulator, the default server URL is:
+
+```text
+http://10.0.2.2:8765
+```
+
+For a physical phone, start the server with `--host 0.0.0.0`, put the phone on the same network, then set the app server URL to:
+
+```text
+http://<linux-machine-ip>:8765
+```
+
+If the server was started with `--token`, enter the same token in the app's Token field.
+
+Tap Save to lock the Server and Token fields. Tap Unlock before editing them again.
+
+Tap Delete on a run in the history list to delete it from the server.
+
+Tap a run, or tap Console, to open the run's terminal output. Use Back to return to the main list.
+
+## App updates
+
+Sideloaded APKs cannot discover updates by themselves unless the app can read a public version file.
+GitHub is not required. For mainland China, prefer a mirror such as Gitee, Aliyun OSS, Tencent COS, Qiniu, or Upyun, and keep GitHub as a fallback.
+
+This app defaults to checking these sources in order:
+
+```text
+https://gitee.com/hushuguo/reminder/raw/main/update.json
+https://raw.githubusercontent.com/hushuguo/Reminder/main/update.json
+```
+
+Create a public JSON file like `update.json`:
+
+```json
+{
+  "android": {
+    "versionCode": 34,
+    "versionName": "0.6.23",
+    "apkUrl": "http://106.14.246.204/downloads/Haoleme-0.6.38.apk",
+    "apkUrls": [
+      "http://106.14.246.204/downloads/Haoleme-0.6.38.apk"
+    ],
+    "notes": "Keeps deleted run records consistent between All, device views, filters, and cached details."
+  }
+}
+```
+
+The update URLs are built into the app and are not shown to users. On startup, the app checks for updates in the background.
+If `versionCode` is higher than the installed APK, the app shows an update label with the new version in the top-right corner. Tap it to download the APK in-app with progress shown in the status area. If download or installation fails, the installed version is left untouched.
+
+This prototype polls every 5 seconds while the app process is alive. A later version should move polling into a foreground service or push channel if you want reliable notifications while the app is fully backgrounded.

haoleme-0.1.0/README.md

@@ -0,0 +1,258 @@
+# 好了么
+
+好了么 is a command monitor for Linux/macOS machines with Android and iOS apps.
+
+The project has three parts:
+
+- `haoleme`: a Python package that installs the `hao` command. Put `hao` before a command to record its status, output tail, exit code, and timestamps.
+- `android/`: a native Android app for pairing, device switching, run history, console output, deletion, and finish notifications.
+- `ios/`: a native SwiftUI iOS app that uses the same 好了么 Cloud account, devices, runs, pairing, and console APIs.
+
+## Python monitor
+
+Install the local package in a virtual environment:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+```
+
+Or install the built wheel:
+
+```bash
+.venv/bin/python -m pip install dist/haoleme-0.1.0-py3-none-any.whl
+```
+
+Start the status server on the Linux machine:
+
+```bash
+hao server --host 0.0.0.0 --port 8765 --token change-this-token
+```
+
+Run commands through 好了么:
+
+```bash
+hao sleep 5
+hao run -- bash -lc 'echo hello && sleep 2 && echo done'
+hao status
+```
+
+The command name is intentionally short: `hao`.
+
+## Cloud sync
+
+The recommended setup is cloud sync. The Linux machine does not need a public IP, ngrok, or port forwarding. The command runner uploads status to 好了么 Cloud, and the Android app reads the same account from the cloud API.
+
+The default cloud relay is:
+
+```text
+http://106.14.246.204
+```
+
+After deploying the Docker cloud server on Aliyun or the Cloudflare Worker in `cloudflare/`, log in once on each new machine:
+
+```bash
+pip install -U haoleme
+hao login
+```
+
+The command prints a QR code and a 6-digit pair code. The cloud URL is built in and hidden from the normal UI. Pair codes expire after 5 minutes and are cancelled automatically when `hao login` exits without pairing.
+If the machine is already logged in, `hao login` asks before replacing the login. Press Enter to continue, or type `n` to cancel.
+
+```text
+847291
+```
+
+Tap Scan in the Android app to scan the QR code with the built-in camera scanner, or scan it with the phone camera to open 好了么 and pair automatically. If QR scanning is unavailable, enter the 6-digit code; the app pairs automatically when all 6 digits are entered. After pairing, the app saves the cloud account, shows the paired device name, and normal commands sync automatically:
+
+```bash
+hao run -- python train.py
+hao run -- sh -c 'for i in $(seq 1 10); do echo tick $i; sleep 1; done'
+```
+
+New pairings use end-to-end encryption for command text, working directory, and console output. 好了么 Cloud keeps the encrypted payload plus operational metadata such as device id, status, and timestamps, so filtering and online state still work while the sensitive run details are decrypted only in the app.
+
+Each computer that runs `hao login` is bound as a device on the same phone account. Use names such as `我的 Mac`, `服务器 A`, or `实验机 B`:
+
+```bash
+hao login --device "服务器 A"
+```
+
+The Android app shows an `All` device view plus one button for each paired computer, so you can switch between all runs and a single machine. Select one device and tap Rename, or long-press a device button, to rename it. Tap Revoke to disable that device's upload token without deleting old history.
+
+Useful cloud commands:
+
+```bash
+hao heartbeat status
+hao heartbeat start
+hao heartbeat stop
+hao cloud-status
+hao cloud-logout
+```
+
+After login, `hao` starts a small background heartbeat automatically. The cloud marks a device online when it has been seen in the last 90 seconds; each device sends a heartbeat every 60 seconds with a device-specific 0-59 second startup offset to avoid synchronized traffic spikes.
+
+Advanced/manual login is still available:
+
+```bash
+hao cloud-login --api-url https://your-haoleme-cloud.workers.dev --account ethan --token <TOKEN>
+```
+
+Cloud sync uses the app's account token as the account key. Anyone with that token can delete that account's run history and read unencrypted legacy records, so treat it like a password.
+
+### Deploy 好了么 Cloud with Docker
+
+The Docker cloud server exposes the same API as the Cloudflare Worker and stores data in SQLite:
+
+```bash
+docker build -f Dockerfile.cloud -t haoleme-cloud .
+docker run -d --name haoleme-cloud --restart unless-stopped \
+  -p 80:8000 \
+  -v /opt/haoleme-cloud-data:/data \
+  haoleme-cloud
+```
+
+Check it:
+
+```bash
+curl http://106.14.246.204/health
+```
+
+For production, prefer putting a domain and HTTPS reverse proxy in front of it. Plain HTTP works for quick testing because the Android app allows cleartext traffic, but HTTPS is safer.
+
+### Deploy 好了么 Cloud
+
+The included Cloudflare Worker is a small relay service. It stores only command metadata and output tails in Cloudflare KV. The Python runner also keeps a local SQLite database at `~/.reminder/reminder.db`, and the Android app caches the latest run list and console output locally so the previous results are visible when the app opens.
+
+```bash
+cd cloudflare
+npm create cloudflare@latest
+npx wrangler kv namespace create RUNS
+```
+
+Copy the returned KV namespace id into `cloudflare/wrangler.toml`, then deploy:
+
+```bash
+npx wrangler deploy
+```
+
+Cloudflare Workers can run this kind of small personal relay on the free plan within their free usage limits. For many users, long logs, or heavy polling, use a paid plan or a small VPS.
+
+The server exposes:
+
+- `GET /health`
+- `GET /api/runs?limit=50`
+- `GET /api/runs/{id}`
+- `GET /api/events?since=<updatedAt>`
+
+By default the SQLite database lives at `~/.reminder/reminder.db`. Set `REMINDER_HOME=/path/to/dir` to change that location.
+
+## Direct public access
+
+Direct public access is still supported for testing and compatibility. If you do not want cloud sync and do not have a public IP, use a Cloudflare quick tunnel:
+
+```bash
+hao public
+```
+
+This starts the local server and runs `cloudflared tunnel --url http://127.0.0.1:8765`. It prints a public `https://*.trycloudflare.com` URL and a token. Newer Android builds default to the built-in cloud pairing flow, so direct server entry is kept only for development and compatibility:
+
+```text
+Server: https://example.trycloudflare.com
+Token:  generated-token
+```
+
+If `cloudflared` is missing, install it first:
+
+```bash
+brew install cloudflared
+```
+
+Cloudflare quick tunnel URLs are random. If you need the same URL every time and do not own a domain, use ngrok's free Dev Domain:
+
+```bash
+brew install ngrok/ngrok/ngrok
+ngrok config add-authtoken <YOUR_NGROK_AUTHTOKEN>
+hao ngrok --domain <YOUR_DEV_DOMAIN>.ngrok-free.dev
+```
+
+Older Android builds with manual server entry can use:
+
+```text
+Server: https://<YOUR_DEV_DOMAIN>.ngrok-free.dev
+Token:  generated-token
+```
+
+If the Android app needs to connect to a server that already has a public IP or a public domain:
+
+```bash
+hao server --host 0.0.0.0 --port 8765 --token a-long-random-token
+```
+
+Then open TCP port `8765` in the cloud security group or firewall.
+
+In the Android app:
+
+```text
+Server: http://<public-ip>:8765
+Token:  a-long-random-token
+```
+
+For real public use, prefer HTTPS through a reverse proxy or tunnel. Plain `http://<public-ip>:8765` works for testing, but the token can be observed on an untrusted network.
+
+## Android app
+
+Open the `android/` directory in Android Studio.
+
+For an emulator, the default server URL is:
+
+```text
+http://10.0.2.2:8765
+```
+
+For a physical phone, start the server with `--host 0.0.0.0`, put the phone on the same network, then set the app server URL to:
+
+```text
+http://<linux-machine-ip>:8765
+```
+
+If the server was started with `--token`, enter the same token in the app's Token field.
+
+Tap Save to lock the Server and Token fields. Tap Unlock before editing them again.
+
+Tap Delete on a run in the history list to delete it from the server.
+
+Tap a run, or tap Console, to open the run's terminal output. Use Back to return to the main list.
+
+## App updates
+
+Sideloaded APKs cannot discover updates by themselves unless the app can read a public version file.
+GitHub is not required. For mainland China, prefer a mirror such as Gitee, Aliyun OSS, Tencent COS, Qiniu, or Upyun, and keep GitHub as a fallback.
+
+This app defaults to checking these sources in order:
+
+```text
+https://gitee.com/hushuguo/reminder/raw/main/update.json
+https://raw.githubusercontent.com/hushuguo/Reminder/main/update.json
+```
+
+Create a public JSON file like `update.json`:
+
+```json
+{
+  "android": {
+    "versionCode": 34,
+    "versionName": "0.6.23",
+    "apkUrl": "http://106.14.246.204/downloads/Haoleme-0.6.38.apk",
+    "apkUrls": [
+      "http://106.14.246.204/downloads/Haoleme-0.6.38.apk"
+    ],
+    "notes": "Keeps deleted run records consistent between All, device views, filters, and cached details."
+  }
+}
+```
+
+The update URLs are built into the app and are not shown to users. On startup, the app checks for updates in the background.
+If `versionCode` is higher than the installed APK, the app shows an update label with the new version in the top-right corner. Tap it to download the APK in-app with progress shown in the status area. If download or installation fails, the installed version is left untouched.
+
+This prototype polls every 5 seconds while the app process is alive. A later version should move polling into a foreground service or push channel if you want reliable notifications while the app is fully backgrounded.

haoleme-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "haoleme"
+version = "0.1.0"
+description = "Run commands with Haoleme monitoring and expose their status to the mobile app."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Haoleme" }]
+dependencies = ["cryptography>=42", "qrcode>=7.4"]
+
+[project.scripts]
+hao = "haoleme.cli:main"
+haoleme-cloud = "haoleme.cloud_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

haoleme-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

haoleme-0.1.0/src/haoleme/__init__.py

@@ -0,0 +1,3 @@
+from remindrun import __version__
+
+__all__ = ["__version__"]

haoleme-0.1.0/src/haoleme/__main__.py

@@ -0,0 +1,5 @@
+from remindrun.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

haoleme-0.1.0/src/haoleme/cli.py

@@ -0,0 +1,3 @@
+from remindrun.cli import main
+
+__all__ = ["main"]

haoleme-0.1.0/src/haoleme/cloud_server.py

@@ -0,0 +1,3 @@
+from remindrun.cloud_server import main
+
+__all__ = ["main"]