diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a557cc6..371dbe3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,85 @@ -# Contributing +# Contributing to PocketPort -PocketPort wants real compatibility data, not theoretical "works on Linux" claims. +PocketPort is an Android-first compatibility project. The most valuable contributions are concrete, reproducible failures and small fixes that make one class of repository behave better without breaking another. -Useful contributions: -- a repo that fails in Termux -- the exact failure log -- Android version and architecture -- whether native Termux or PRoot fixed it -- a minimal repeatable patch +## Good contributions -Keep recipes small and reproducible. +Useful reports include: + +- a public repository that fails in Termux +- the exact command that failed +- the smallest useful error log +- Android version +- device architecture +- Termux package / environment details +- whether native Termux, hybrid handling, or PRoot changed the result +- a minimal patch or regression fixture when possible + +A vague "doesn't work on Android" report gives everyone the rare opportunity to learn absolutely nothing. + +## Before opening a PR + +Run the test suite: + +```bash +python -m pip install -e . +pytest +``` + +For scanner or patcher changes, add or update a regression test. + +For runtime changes, include the device and environment used for validation. + +## Design rules + +PocketPort follows a few non-negotiable rules: + +1. Prefer a visible failure over a destructive guess. +2. Automatic rewrites must be narrow and testable. +3. Do not silently execute generated commands. +4. Keep Android-specific behavior explicit. +5. Keep the core engine independent from the UI. +6. Do not include secrets, tokens, private repository data, or proprietary source in fixtures. + +## Compatibility reports + +When opening a compatibility issue, include: + +```text +Repository: +Commit / tag: +Android version: +Architecture: +Termux version: +Strategy tried: native / hybrid / proot + +Command: + + +Failure: + + +What changed the result: + +``` + +## Pull requests + +Keep PRs focused. A compatibility fix should ideally solve one class of failure and contain a regression test that demonstrates why the change is safe. + +The PR template asks for safety impact and Android / Termux validation. Fill those sections in rather than decorating them with optimism. + +## Scope + +PocketPort is not trying to emulate an entire desktop Linux distribution inside Android. + +Changes fit the project when they improve one or more of these areas: + +- repository compatibility detection +- execution-strategy selection +- conservative Android / Termux rewrites +- local workspace preparation +- localhost bridge behavior +- Android companion UX +- reproducible compatibility evidence +- tests, documentation, or security hardening diff --git a/LICENSE b/LICENSE index c6d02c8..e48a8fb 100644 --- a/LICENSE +++ b/LICENSE @@ -14,4 +14,8 @@ copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 04a5681..4418178 100644 --- a/README.md +++ b/README.md @@ -4,134 +4,196 @@

Run more GitHub tools on Android.
- Scan a repository, choose the safest Termux path, prepare the workspace, and hand off the exact command to your phone. + PocketPort scans desktop-first repositories, finds the assumptions that break on phones, chooses the safest Termux / hybrid / PRoot path, and prepares an explicit local execution plan.

- Web scanner · - Architecture · - DeepSeek Harness proof · - Launch kit -

- -

- PocketPort on Android + Try the web scanner + · + Roadmap + · + Architecture + · + DeepSeek Harness proof

+ status: public alpha tests Android + Termux Python 3.10+ - MIT + license: MIT

-## Why PocketPort +

+ PocketPort on Android +

+ +> **Public alpha.** The compatibility engine and reference Android flow are real and testable today. The native companion is still being finished, the UX is moving quickly, and breaking changes are expected before the first stable release. + +## The problem + +Useful developer tools keep assuming there is a laptop somewhere nearby. + +They expect Docker, systemd, glibc, distro package managers, fixed Linux paths, x86 binaries, desktop browser launchers, CUDA, or native modules that were never built for Android. -A lot of useful GitHub projects assume a desktop Linux machine. PocketPort checks those assumptions and tells you what can actually run on Android. +PocketPort asks a narrower question: -It chooses one of three paths: +> **What would it take to run this repository locally on an Android phone without pretending Android is desktop Linux?** -| Path | What it means | +It scans first, chooses a strategy, applies only conservative fixes, and keeps the final execution visible. + +## What works today + +| Area | Current state | +| --- | --- | +| Repository scanning | Working | +| Desktop / Linux assumption detection | Working | +| Native / hybrid / PRoot strategy selection | Working | +| Conservative compatibility rewrites | Working | +| Execution-plan generation | Working | +| Isolated workspace preparation | Working | +| Localhost phone bridge | Working | +| Web scanner | Working | +| DeepSeek Harness reference flow | Validated on Android 16 / aarch64 | +| Native Android companion | In active development | +| Stable APK release | Not published yet | +| Compatibility registry | Planned | + +PocketPort is intentionally **not** presented as finished. The goal right now is to make the engine trustworthy before polishing the last 10% of the app shell into a very convincing lie. Software has enough of those already. + +## How PocketPort decides + +PocketPort chooses one of three execution paths: + +| Strategy | Meaning | | --- | --- | | **native** | Run directly in Termux | -| **hybrid** | Apply conservative fixes and keep a PRoot fallback | -| **proot** | Use a rootless Linux userland when desktop-Linux assumptions are real | +| **hybrid** | Apply narrow Android-safe fixes while retaining a PRoot fallback | +| **proot** | Use a rootless Linux userland when the project genuinely depends on desktop Linux assumptions | -PocketPort does **not** claim every repo magically works on Android. It scans first, patches only when the change is unambiguous, and keeps execution explicit. +The important rule is simple: -## Android flow +**visible failure > destructive guess** -**01 Scan repo → 02 Connect phone → 03 Run in Termux** +If PocketPort cannot confidently rewrite something, it leaves it alone and reports the problem. -The native Android companion talks to PocketPort Core on localhost. The APK is the control surface; Termux remains the execution environment. +## Android flow -Current companion flow: +```text +GitHub repository + | + v + scan + | + v +compatibility report + | + v +native / hybrid / proot + | + v + safe patch + execution plan + | + v + prepared local workspace + | + v +PocketPort companion -> Termux +``` -- scan a GitHub repository -- inspect compatibility and execution strategy -- show fixes and plan details -- prepare a local PocketPort workspace -- open the repo on GitHub -- copy the generated command -- hand off to Termux with **Run in Termux** +The APK is a control surface. Termux remains the execution environment. + +That keeps one compatibility engine instead of duplicating behavior in Kotlin and Python and then spending the rest of human history debugging why they disagree. ## Quick start +PocketPort currently targets Android + Termux. + ```bash pkg update -y pkg install -y git python + git clone https://github.com/levomm/pocketport cd pocketport + python -m pip install -e . pocketport doctor ``` -Start the phone bridge: +Start the local bridge: ```bash pocketport serve ``` -Scan and prepare: +Scan a repository: ```bash pocketport scan https://github.com/owner/repo +``` + +Prepare the current repository: + +```bash pocketport prepare . ``` -Or let PocketPort prepare an isolated workspace for a public repository: +Or let PocketPort create an isolated workspace for a public repository: ```bash pocketport run https://github.com/owner/repo ``` -## DeepSeek Harness proof +## DeepSeek Harness reference proof -PocketPort has been tested end-to-end against [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) on **Android 16 / aarch64 Termux**. +PocketPort has been used as a real Android compatibility layer for [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness). -Validated in the tested flow: +Tested on **Android 16 / aarch64 / Termux**: -- installation +- dependency installation - Web UI startup - real model / agent turn - shell execution - session persistence - filesystem write + read -- direct Termux execution with a narrow PocketPort runtime shim +- direct Termux execution with a narrow runtime shim - no PRoot required for the tested path -Detailed notes: [experiments/deepseek-harness.md](experiments/deepseek-harness.md) +This proves the current compatibility path. It does **not** mean every repository or every future Harness version is automatically supported. + +Full notes: [experiments/deepseek-harness.md](./experiments/deepseek-harness.md) -## What it scans +## What PocketPort scans for -PocketPort looks for things that usually break desktop-first projects on Android: +Common Android failure points include: -- Docker / Docker Compose assumptions +- Docker and Docker Compose assumptions - systemd / `systemctl` - distro package managers - hard-coded `/usr/bin` and `/bin/bash` +- glibc-only binaries - CUDA / NVIDIA dependencies - x86-only assumptions - native Node modules - native / heavy Python dependencies +- browser / desktop launch assumptions - runtime capability mismatches ## Conservative patching Safe rewrites currently include: -- desktop bash shebangs → Termux bash +- desktop bash shebangs -> Termux bash - narrow `sudo` removal before known external commands -- `xdg-open` → `termux-open` -- simple distro package install/update commands → `pkg` +- `xdg-open` -> `termux-open` +- simple distro package install/update commands -> `pkg` - common package-name translations - unambiguous npm script rewrites -Ambiguous shell logic is left alone. +Ambiguous shell logic stays untouched. -> A patcher that confidently destroys working projects is not automation. It is vandalism with branding. - -## Generated files +Generated artifacts are kept visible: ```text .pocketport/report.json @@ -141,33 +203,57 @@ termux-install.sh termux-run.sh ``` -## Project map +## Project layout ```text -GitHub repo - | - v -scan -> semantics -> component analysis - | | - +---- strategy ------+ - | - native / hybrid / proot - | - safe patching - | - execution plan - | - Android companion - | - Termux +pocketport/ +├── pocketport/ Python core + CLI +├── android-companion/ native Android companion +├── api/ hosted scan API +├── web/ mobile-first web scanner +├── experiments/ real compatibility reports +├── tests/ regression coverage +├── docs/ architecture, roadmap, launch notes +└── assets/ PocketPort brand assets ``` -## Status +For the deeper model, see [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md). + +## Road to the first stable release + +The current work is focused on: + +1. finishing and validating the native Android companion +2. installing the generated APK on the reference Android 16 device +3. adding native report / log views +4. publishing a tagged GitHub release with the APK attached +5. adding a second reference project with a different stack +6. recording a short end-to-end demo +7. tightening web metadata and public compatibility reporting + +Track the actual checklist in [docs/ROADMAP.md](./docs/ROADMAP.md). + +## Contributing + +PocketPort needs ugly real-world repositories more than theoretical compatibility claims. + +Useful contributions include: + +- repositories that fail in Termux +- exact failure logs +- Android version + architecture +- native Termux vs PRoot results +- narrow reproducible compatibility patches +- regression tests for previously broken behavior + +Start with [CONTRIBUTING.md](./CONTRIBUTING.md). + +## Security -PocketPort is still early and moving quickly. The current focus is repo-aware execution, safer Android handoff, isolated prepared workspaces, compatibility proof, and a polished native companion. +PocketPort executes locally and may prepare commands derived from third-party repositories. Treat untrusted repositories as untrusted code. -Contributions, test repos, failure reports, and Android edge cases are useful. +Security policy and reporting guidance: [SECURITY.md](./SECURITY.md). ## License -MIT. +MIT. See [LICENSE](./LICENSE).