hello-python - sample bridge (Python)

@@ -27,7 +27,7 @@     "install_hint": "",     "version_cmd": ""   },-  "readme": "# Sample bridge: hello-python\n\n## What this is\n\n`hello-python` is a **minimal third-party bridge** for Adom Desktop, written in ~80 lines of Python stdlib. It exists so you can install one command, run two verbs, and have a complete mental model of what writing a bridge actually involves \u2014 before you commit to integrating your real tool (Altium, MATLAB, an oscilloscope, an inventory system, whatever).\n\nPair it with its twin [`hello-rust`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-rust-bridge) (same surface, different language) for a side-by-side comparison of the two implementation flavors Adom Desktop supports: `kind: \"python\"` (interpreted) vs. `kind: \"exe\"` (native single-binary).\n\nIf you're getting started, also read the [bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges) for the `bridge.json` schema and packaging conventions.\n\n## Try it in 30 seconds\n\n```bash\n# 1. Install from the wiki (anonymous, no GitHub account needed)\nadom-desktop bridge_install '{\"manifestUrl\":\"https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/hello-python-bridge-manifest.json\"}'\n\n# 2. Ping it (auto-spawns the bridge process)\nadom-desktop hellopy_ping\n# \u2192 {\"success\":true,\"output\":\"Hello from the Python sample bridge v1.2.0!\",\"language\":\"python\",...}\n\n# 3. Echo something back\nadom-desktop hellopy_echo '{\"message\":\"world\"}'\n# \u2192 {\"success\":true,\"output\":\"echo (python): world\",\"echoed\":\"world\",\"language\":\"python\"}\n\n# 4. Confirm it's registered\nadom-desktop bridge_list   # look for \"hello-python\" with verbs hellopy_*\n\n# 5. Uninstall when done\nadom-desktop bridge_uninstall '{\"name\":\"hello-python\"}'\n```\n\nThe bridge process auto-spawns on the first `hellopy_*` call, listens on an OS-assigned ephemeral port (v1.8.31+ dynamic port allocation \u2014 no collision with any other bridge), and is killed cleanly on `bridge_uninstall` or app shutdown.\n\n## What's in the box\n\n```\nhello-python/\n\u251c\u2500\u2500 bridge.json         \u2190 manifest (verb prefixes, spawn config, platforms)\n\u251c\u2500\u2500 BRIDGE_VERSION      \u2190 semver, kept in sync with bridge.json\n\u251c\u2500\u2500 server.py           \u2190 ~80 lines, http.server.BaseHTTPRequestHandler\n\u2514\u2500\u2500 README.md           \u2190 lifecycle notes\n```\n\nThat's the entire bridge. No external pip dependencies \u2014 just the Python stdlib.\n\n## The two endpoints every bridge exposes\n\n| Endpoint | When | What it returns |\n|---|---|---|\n| `GET /status` | Adom Desktop polls this after spawn to confirm the bridge is alive | `{\"ok\": true, \"bridge\": \"hello-python\", \"version\": \"...\", \"uptimeSec\": N}` |\n| `POST /command` | Every CLI verb call routes through here | `{\"success\": bool, \"output\": ..., \"error\": ...}` (response shape is conventional, not enforced) |\n\n## How verb routing works\n\n1. `bridge.json` declares `verbPrefixes: [\"hellopy_\"]`\n2. Adom Desktop's registry records that `hellopy_*` belongs to this bridge\n3. When you type `adom-desktop hellopy_ping`, the Tauri runtime:\n   - Spawns `python server.py --port <ephemeral>` if not already running\n   - Polls `/status` until ready\n   - POSTs `{\"command\":\"hellopy_ping\",\"args\":{}}` to `/command`\n   - Streams the JSON response back through the CLI\n\n## The two verbs\n\n| Verb | Args | Returns |\n|---|---|---|\n| `hellopy_ping` | (none) | `{success, output, bridge, language: \"python\", version, uptimeSec, _hint}` |\n| `hellopy_echo` | `{\"message\": \"<str>\"}` | `{success, output, echoed, language: \"python\"}` |\n\nTry `adom-desktop status hellopy_ping` to see the AI-friendly help-map entry that drives Docker Claude usage.\n\n## Forking for your own bridge\n\nThe fastest way to get to a real bridge:\n\n```bash\n# 1. Get the source (anonymous \u2014 no GitHub account needed)\ncurl -O https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/hello-python-bridge.zip\nunzip hello-python-bridge.zip && cd hello-python\n\n# 2. Rename the bridge end-to-end\n#    - bridge.json: change \"name\", \"displayName\", \"verbPrefixes\", \"verbs\"\n#    - server.py:   change __version__, rename the if/elif command branches\n#    - BRIDGE_VERSION: reset to 0.1.0\n\n# 3. Replace the verb implementations with calls into your tool's SDK\n#    (Altium COM, MATLAB Engine, instrument SCPI, your REST API, etc.)\n\n# 4. Test locally without packaging:\npython server.py --port 8890   # in one terminal\nadom-desktop bridge_install '{\"manifestUrl\":\"file:///abs/path/to/your/bridge.json\"}'\n\n# 5. Package + ship \u2014 see the SDK guide\n```\n\nThe full source tree (with the dynamic-port v1.8.31 wiring intact) is at [`scripts/sample-bridges/hello-python/`](https://github.com/adom-inc/adom-desktop/tree/main/scripts/sample-bridges/hello-python) in the Adom Desktop repo, mirroring what `bridge_install` extracts to your cache dir.\n\n## When Python is the right choice\n\nPick `hello-python` (vs. the Rust flavor) when:\n\n- **Your tool has Python bindings.** KiCad, Fusion 360, OpenCV, NumPy ecosystem \u2014 Python is the natural shim.\n- **I/O-bound work.** REST calls, file walks, slow vendor SDKs \u2014 Python's overhead is invisible.\n- **Fast iteration.** No compile step. `Ctrl+S` then re-run.\n- **End users already have Python.** Engineers running Adom Desktop on a workstation typically have it.\n\nPick [`hello-rust`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-rust-bridge) when you need a single static binary, no runtime install, type safety, or CPU-bound performance.\n\n## License\n\nMIT. Fork freely, sell what you build on top.\n\n## See also\n\n- [Adom Desktop bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges) \u2014 `bridge.json` schema, packaging, lifecycle\n- [`hello-rust`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-rust-bridge) \u2014 Rust port of this same surface\n- [Bridges registry](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges-registry) \u2014 community-maintained list of installable bridges\n- [Reference bridges: KiCad, Fusion 360, Puppeteer](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges-registry) \u2014 full-complexity production examples\n",+  "readme": "# Sample bridge: hello-python\n\n## What this is\n\n`hello-python` is a **minimal third-party bridge** for Adom Desktop, written in ~80 lines of Python stdlib. It exists so you can install one command, run two verbs, and have a complete mental model of what writing a bridge actually involves — before you commit to integrating your real tool (Altium, MATLAB, an oscilloscope, an inventory system, whatever).\n\nPair it with its twin [`hello-rust`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-rust-bridge) (same surface, different language) for a side-by-side comparison of the two implementation flavors Adom Desktop supports: `kind: \"python\"` (interpreted) vs. `kind: \"exe\"` (native single-binary).\n\nIf you're getting started, also read the [bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges) for the `bridge.json` schema and packaging conventions.\n\n## Try it in 30 seconds\n\n```bash\n# 1. Install from the wiki (anonymous, no GitHub account needed)\nadom-desktop bridge_install '{\"manifestUrl\":\"https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/hello-python-bridge-manifest.json\"}'\n\n# 2. Ping it (auto-spawns the bridge process)\nadom-desktop hellopy_ping\n# → {\"success\":true,\"output\":\"Hello from the Python sample bridge v1.2.0!\",\"language\":\"python\",...}\n\n# 3. Echo something back\nadom-desktop hellopy_echo '{\"message\":\"world\"}'\n# → {\"success\":true,\"output\":\"echo (python): world\",\"echoed\":\"world\",\"language\":\"python\"}\n\n# 4. Confirm it's registered\nadom-desktop bridge_list   # look for \"hello-python\" with verbs hellopy_*\n\n# 5. Uninstall when done\nadom-desktop bridge_uninstall '{\"name\":\"hello-python\"}'\n```\n\nThe bridge process auto-spawns on the first `hellopy_*` call, listens on an OS-assigned ephemeral port (v1.8.31+ dynamic port allocation — no collision with any other bridge), and is killed cleanly on `bridge_uninstall` or app shutdown.\n\n## What's in the box\n\n```\nhello-python/\n├── bridge.json         ← manifest (verb prefixes, spawn config, platforms)\n├── BRIDGE_VERSION      ← semver, kept in sync with bridge.json\n├── server.py           ← ~80 lines, http.server.BaseHTTPRequestHandler\n└── README.md           ← lifecycle notes\n```\n\nThat's the entire bridge. No external pip dependencies — just the Python stdlib.\n\n## The two endpoints every bridge exposes\n\n| Endpoint | When | What it returns |\n|---|---|---|\n| `GET /status` | Adom Desktop polls this after spawn to confirm the bridge is alive | `{\"ok\": true, \"bridge\": \"hello-python\", \"version\": \"...\", \"uptimeSec\": N}` |\n| `POST /command` | Every CLI verb call routes through here | `{\"success\": bool, \"output\": ..., \"error\": ...}` (response shape is conventional, not enforced) |\n\n## How verb routing works\n\n1. `bridge.json` declares `verbPrefixes: [\"hellopy_\"]`\n2. Adom Desktop's registry records that `hellopy_*` belongs to this bridge\n3. When you type `adom-desktop hellopy_ping`, the Tauri runtime:\n   - Spawns `python server.py --port <ephemeral>` if not already running\n   - Polls `/status` until ready\n   - POSTs `{\"command\":\"hellopy_ping\",\"args\":{}}` to `/command`\n   - Streams the JSON response back through the CLI\n\n## The two verbs\n\n| Verb | Args | Returns |\n|---|---|---|\n| `hellopy_ping` | (none) | `{success, output, bridge, language: \"python\", version, uptimeSec, _hint}` |\n| `hellopy_echo` | `{\"message\": \"<str>\"}` | `{success, output, echoed, language: \"python\"}` |\n\nTry `adom-desktop status hellopy_ping` to see the AI-friendly help-map entry that drives Docker Claude usage.\n\n## Forking for your own bridge\n\nThe fastest way to get to a real bridge:\n\n```bash\n# 1. Get the source (anonymous — no GitHub account needed)\ncurl -O https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/hello-python-bridge.zip\nunzip hello-python-bridge.zip && cd hello-python\n\n# 2. Rename the bridge end-to-end\n#    - bridge.json: change \"name\", \"displayName\", \"verbPrefixes\", \"verbs\"\n#    - server.py:   change __version__, rename the if/elif command branches\n#    - BRIDGE_VERSION: reset to 0.1.0\n\n# 3. Replace the verb implementations with calls into your tool's SDK\n#    (Altium COM, MATLAB Engine, instrument SCPI, your REST API, etc.)\n\n# 4. Test locally without packaging:\npython server.py --port 8890   # in one terminal\nadom-desktop bridge_install '{\"manifestUrl\":\"file:///abs/path/to/your/bridge.json\"}'\n\n# 5. Package + ship — see the SDK guide\n```\n\nThe full source tree (with the dynamic-port v1.8.31 wiring intact) is at [`scripts/sample-bridges/hello-python/`](https://github.com/adom-inc/adom-desktop/tree/main/scripts/sample-bridges/hello-python) in the Adom Desktop repo, mirroring what `bridge_install` extracts to your cache dir.\n\n## When Python is the right choice\n\nPick `hello-python` (vs. the Rust flavor) when:\n\n- **Your tool has Python bindings.** KiCad, Fusion 360, OpenCV, NumPy ecosystem — Python is the natural shim.\n- **I/O-bound work.** REST calls, file walks, slow vendor SDKs — Python's overhead is invisible.\n- **Fast iteration.** No compile step. `Ctrl+S` then re-run.\n- **End users already have Python.** Engineers running Adom Desktop on a workstation typically have it.\n\nPick [`hello-rust`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-rust-bridge) when you need a single static binary, no runtime install, type safety, or CPU-bound performance.\n\n## License\n\nMIT. Fork freely, sell what you build on top.\n\n## See also\n\n- [Adom Desktop bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges) — `bridge.json` schema, packaging, lifecycle\n- [`hello-rust`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-rust-bridge) — Rust port of this same surface\n- [Bridges registry](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges-registry) — community-maintained list of installable bridges\n- [Reference bridges: KiCad, Fusion 360, Puppeteer](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges-registry) — full-complexity production examples\n",   "author": {     "id": "695820315b5f1e4db2fcf602",     "name": "Kyle Bergstedt",