nazar-bridge 0.1.0__tar.gz

nazar_bridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+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. 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.

nazar_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: nazar-bridge
+Version: 0.1.0
+Summary: Nazar bridge daemon — relays phone prompts to local `claude -p` over a long-lived WebSocket.
+Author: Arman
+Maintainer: Arman
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/arm-yan/nazar
+Project-URL: Repository, https://github.com/arm-yan/nazar
+Project-URL: Issues, https://github.com/arm-yan/nazar/issues
+Keywords: nazar,claude,claude-code,daemon,websocket,bridge,ai-assistant,remote-control
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets<17,>=15
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: dev
+Requires-Dist: pytest==9.0.3; extra == "dev"
+Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
+Requires-Dist: ruff==0.15.12; extra == "dev"
+Requires-Dist: mypy==2.1.0; extra == "dev"
+Dynamic: license-file
+
+# nazar-bridge
+
+`nazar-bridge` is a small, open-source daemon that lets you drive
+[Claude Code](https://claude.com/claude-code) on your own machine from the
+[Nazar](https://github.com/arm-yan/nazar) phone dashboard.
+
+It holds a single long-lived **outbound** WebSocket connection to the Nazar
+API, registers your local Claude-Code project directories, and — when you send
+a prompt from your phone — spawns `claude -p` in the matching project and
+streams the output back. Nothing listens for inbound connections on your
+machine; the daemon dials out, so there are no ports to open.
+
+The source is intentionally small and auditable — read it before you install
+it. That's the whole trust model (see [Trust & supply chain](#trust--supply-chain)).
+
+---
+
+## Prerequisites
+
+- **Python 3.12+** on your machine.
+- **[Claude Code](https://claude.com/claude-code) installed and authenticated.**
+  The daemon shells out to the `claude` CLI using *your* logged-in session, so
+  `claude` must be on your `PATH` and already signed in.
+- **A Nazar account on a Pro or Unlimited plan.** The bridge is a paid-tier
+  feature — **the Free plan has no bridge** and cannot mint daemon tokens.
+
+---
+
+## Install
+
+Recommended (isolated tool install via [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uv tool install nazar-bridge
+```
+
+Alternative (via [pipx](https://pipx.pypa.io/)):
+
+```bash
+pipx install nazar-bridge
+```
+
+Upgrade later:
+
+```bash
+uv tool upgrade nazar-bridge      # or: pipx upgrade nazar-bridge
+```
+
+Both put a `nazar-bridge` command on your `PATH`.
+
+---
+
+## Connect
+
+1. **Get a daemon token.** In the Nazar dashboard, open **/code → Bridge
+   tokens** and create one. It looks like `nazar_bridge_xxxxxxxxxxxxxxxx`.
+   Copy it now — it's shown only once.
+
+2. **Configure the daemon** with the token (and, if your API host differs from
+   the default, the WebSocket URL):
+
+   ```bash
+   nazar-bridge configure --token nazar_bridge_xxxxxxxxxxxxxxxx
+   # to point at a self-hosted / dev API instead of the default:
+   nazar-bridge configure --token nazar_bridge_xxxx --api-url wss://your-host/api/bridge/ws
+   ```
+
+3. **Register the project directories** you want reachable from your phone:
+
+   ```bash
+   nazar-bridge add /path/to/your/project
+   nazar-bridge add /path/to/another/project
+   nazar-bridge list
+   ```
+
+4. **Run it.** Either start it once in a terminal:
+
+   ```bash
+   nazar-bridge run            # add --debug for verbose logs
+   ```
+
+   …or install it as a login autostart service (recommended — see below) so it
+   reconnects automatically after a reboot.
+
+`run --once` exits right after the first successful register — handy for
+smoke-testing a freshly-configured daemon.
+
+---
+
+## Autostart at login (recommended)
+
+Instead of leaving a terminal open, register the daemon to start at login and
+restart on failure. One cross-platform command detects your OS and writes the
+right unit:
+
+```bash
+nazar-bridge service install      # Windows / macOS / Linux
+nazar-bridge service status       # is it installed / running?
+nazar-bridge service uninstall    # remove it
+```
+
+| OS      | What `service install` creates                                            |
+| ------- | ------------------------------------------------------------------------- |
+| Windows | A Task Scheduler task **"Nazar Bridge"** that runs at logon (windowless). |
+| macOS   | A launchd LaunchAgent `app.nazar.bridge` in `~/Library/LaunchAgents`.     |
+| Linux   | A systemd `--user` unit `nazar-bridge.service` (enabled + started).       |
+
+The service always runs **as your own user** (never root/SYSTEM) because the
+daemon spawns `claude` with your personal Claude Code login — `service install`
+refuses to run as root. On Linux, run `loginctl enable-linger $USER` if you
+want the daemon up even when you're not logged in interactively.
+
+Logs go to the daemon's rotating log file (see below) regardless of how it's
+started. For live debugging, run `nazar-bridge run` in a terminal to watch
+output directly.
+
+> **Windows note:** earlier releases shipped
+> `scripts/install-windows-startup.ps1`. That script still works and adds a
+> richer restart policy, but `nazar-bridge service install` is now the
+> recommended, cross-platform path.
+
+---
+
+## Where config & logs live
+
+| OS      | Config file                                          | Daemon log                  |
+| ------- | ---------------------------------------------------- | --------------------------- |
+| Windows | `%APPDATA%\nazar-bridge\config.toml`                 | `%APPDATA%\nazar-bridge\daemon.log` |
+| macOS   | `~/.config/nazar-bridge/config.toml`                 | `~/.config/nazar-bridge/daemon.log` |
+| Linux   | `$XDG_CONFIG_HOME/nazar-bridge/config.toml` or       | `…/nazar-bridge/daemon.log`         |
+|         | `~/.config/nazar-bridge/config.toml`                 |                             |
+
+The token is stored **plaintext** in `config.toml` — it's the daemon's only
+credential. Protect it with filesystem permissions:
+
+- **Windows:** `icacls "%APPDATA%\nazar-bridge\config.toml" /inheritance:r /grant:r "%USERNAME%:F"`
+- **macOS / Linux:** `chmod 600 ~/.config/nazar-bridge/config.toml`
+
+Rotating the token is two commands: `nazar-bridge configure --force --token <new>`
+(your project list is preserved).
+
+---
+
+## Trust & supply chain
+
+The bridge runs on your machine and runs Claude Code with full permissions, so
+its trustworthiness matters. The design keeps that auditable:
+
+- **Open source.** Every line is on GitHub:
+  [arm-yan/nazar](https://github.com/arm-yan/nazar) under `apps/bridge`. Read it
+  before installing.
+- **Published from PyPI, not a private host.** `uv tool install nazar-bridge`
+  pulls the package and its only two runtime dependencies (`websockets`,
+  `pydantic`) from PyPI. Nothing is downloaded from a private or vendor server.
+- **Signed provenance.** Releases are published to PyPI via GitHub Actions
+  **Trusted Publishing (OIDC)** with attestations — no long-lived upload token
+  exists, and each artifact carries signed build provenance you can verify back
+  to the tagged commit.
+
+---
+
+## Security model
+
+Be deliberate about what this daemon does:
+
+- When a prompt arrives from your authenticated Nazar dashboard, the daemon
+  spawns Claude Code **with `--dangerously-skip-permissions`** — Claude can read,
+  write, and run commands in the registered project directory without per-action
+  prompts. This is intentional: it's *your* machine, *your* Claude login, and
+  *your* token, and the point of the bridge is hands-off remote execution.
+- The **trust boundary is your daemon token plus your single-user host.** Anyone
+  who holds the token can drive Claude on your machine through the Nazar API.
+  Treat the token like an SSH key: keep `config.toml` locked down, and
+  rotate/revoke the token (from the dashboard) if it leaks.
+- The daemon only ever makes an **outbound** WebSocket connection — it opens no
+  listening port on your machine.
+
+If that posture isn't acceptable for a given machine, don't install the bridge
+there.
+
+---
+
+## Wire protocol
+
+The daemon and API speak JSON text frames over the WebSocket. The source of
+truth for the schemas is `apps/api/nazar_api/schemas/bridge.py`; the daemon's
+`nazar_bridge/wire.py` mirrors the relevant subset so the daemon stays
+installable independently of the API package.
+
+---
+
+## Develop / test
+
+```bash
+cd apps/bridge
+python -m pip install -e ".[dev]"
+pytest
+ruff check nazar_bridge tests
+mypy nazar_bridge
+```
+
+Build the distributables locally:
+
+```bash
+python -m build          # produces dist/*.whl and dist/*.tar.gz
+twine check dist/*
+```

nazar_bridge-0.1.0/README.md

@@ -0,0 +1,207 @@
+# nazar-bridge
+
+`nazar-bridge` is a small, open-source daemon that lets you drive
+[Claude Code](https://claude.com/claude-code) on your own machine from the
+[Nazar](https://github.com/arm-yan/nazar) phone dashboard.
+
+It holds a single long-lived **outbound** WebSocket connection to the Nazar
+API, registers your local Claude-Code project directories, and — when you send
+a prompt from your phone — spawns `claude -p` in the matching project and
+streams the output back. Nothing listens for inbound connections on your
+machine; the daemon dials out, so there are no ports to open.
+
+The source is intentionally small and auditable — read it before you install
+it. That's the whole trust model (see [Trust & supply chain](#trust--supply-chain)).
+
+---
+
+## Prerequisites
+
+- **Python 3.12+** on your machine.
+- **[Claude Code](https://claude.com/claude-code) installed and authenticated.**
+  The daemon shells out to the `claude` CLI using *your* logged-in session, so
+  `claude` must be on your `PATH` and already signed in.
+- **A Nazar account on a Pro or Unlimited plan.** The bridge is a paid-tier
+  feature — **the Free plan has no bridge** and cannot mint daemon tokens.
+
+---
+
+## Install
+
+Recommended (isolated tool install via [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uv tool install nazar-bridge
+```
+
+Alternative (via [pipx](https://pipx.pypa.io/)):
+
+```bash
+pipx install nazar-bridge
+```
+
+Upgrade later:
+
+```bash
+uv tool upgrade nazar-bridge      # or: pipx upgrade nazar-bridge
+```
+
+Both put a `nazar-bridge` command on your `PATH`.
+
+---
+
+## Connect
+
+1. **Get a daemon token.** In the Nazar dashboard, open **/code → Bridge
+   tokens** and create one. It looks like `nazar_bridge_xxxxxxxxxxxxxxxx`.
+   Copy it now — it's shown only once.
+
+2. **Configure the daemon** with the token (and, if your API host differs from
+   the default, the WebSocket URL):
+
+   ```bash
+   nazar-bridge configure --token nazar_bridge_xxxxxxxxxxxxxxxx
+   # to point at a self-hosted / dev API instead of the default:
+   nazar-bridge configure --token nazar_bridge_xxxx --api-url wss://your-host/api/bridge/ws
+   ```
+
+3. **Register the project directories** you want reachable from your phone:
+
+   ```bash
+   nazar-bridge add /path/to/your/project
+   nazar-bridge add /path/to/another/project
+   nazar-bridge list
+   ```
+
+4. **Run it.** Either start it once in a terminal:
+
+   ```bash
+   nazar-bridge run            # add --debug for verbose logs
+   ```
+
+   …or install it as a login autostart service (recommended — see below) so it
+   reconnects automatically after a reboot.
+
+`run --once` exits right after the first successful register — handy for
+smoke-testing a freshly-configured daemon.
+
+---
+
+## Autostart at login (recommended)
+
+Instead of leaving a terminal open, register the daemon to start at login and
+restart on failure. One cross-platform command detects your OS and writes the
+right unit:
+
+```bash
+nazar-bridge service install      # Windows / macOS / Linux
+nazar-bridge service status       # is it installed / running?
+nazar-bridge service uninstall    # remove it
+```
+
+| OS      | What `service install` creates                                            |
+| ------- | ------------------------------------------------------------------------- |
+| Windows | A Task Scheduler task **"Nazar Bridge"** that runs at logon (windowless). |
+| macOS   | A launchd LaunchAgent `app.nazar.bridge` in `~/Library/LaunchAgents`.     |
+| Linux   | A systemd `--user` unit `nazar-bridge.service` (enabled + started).       |
+
+The service always runs **as your own user** (never root/SYSTEM) because the
+daemon spawns `claude` with your personal Claude Code login — `service install`
+refuses to run as root. On Linux, run `loginctl enable-linger $USER` if you
+want the daemon up even when you're not logged in interactively.
+
+Logs go to the daemon's rotating log file (see below) regardless of how it's
+started. For live debugging, run `nazar-bridge run` in a terminal to watch
+output directly.
+
+> **Windows note:** earlier releases shipped
+> `scripts/install-windows-startup.ps1`. That script still works and adds a
+> richer restart policy, but `nazar-bridge service install` is now the
+> recommended, cross-platform path.
+
+---
+
+## Where config & logs live
+
+| OS      | Config file                                          | Daemon log                  |
+| ------- | ---------------------------------------------------- | --------------------------- |
+| Windows | `%APPDATA%\nazar-bridge\config.toml`                 | `%APPDATA%\nazar-bridge\daemon.log` |
+| macOS   | `~/.config/nazar-bridge/config.toml`                 | `~/.config/nazar-bridge/daemon.log` |
+| Linux   | `$XDG_CONFIG_HOME/nazar-bridge/config.toml` or       | `…/nazar-bridge/daemon.log`         |
+|         | `~/.config/nazar-bridge/config.toml`                 |                             |
+
+The token is stored **plaintext** in `config.toml` — it's the daemon's only
+credential. Protect it with filesystem permissions:
+
+- **Windows:** `icacls "%APPDATA%\nazar-bridge\config.toml" /inheritance:r /grant:r "%USERNAME%:F"`
+- **macOS / Linux:** `chmod 600 ~/.config/nazar-bridge/config.toml`
+
+Rotating the token is two commands: `nazar-bridge configure --force --token <new>`
+(your project list is preserved).
+
+---
+
+## Trust & supply chain
+
+The bridge runs on your machine and runs Claude Code with full permissions, so
+its trustworthiness matters. The design keeps that auditable:
+
+- **Open source.** Every line is on GitHub:
+  [arm-yan/nazar](https://github.com/arm-yan/nazar) under `apps/bridge`. Read it
+  before installing.
+- **Published from PyPI, not a private host.** `uv tool install nazar-bridge`
+  pulls the package and its only two runtime dependencies (`websockets`,
+  `pydantic`) from PyPI. Nothing is downloaded from a private or vendor server.
+- **Signed provenance.** Releases are published to PyPI via GitHub Actions
+  **Trusted Publishing (OIDC)** with attestations — no long-lived upload token
+  exists, and each artifact carries signed build provenance you can verify back
+  to the tagged commit.
+
+---
+
+## Security model
+
+Be deliberate about what this daemon does:
+
+- When a prompt arrives from your authenticated Nazar dashboard, the daemon
+  spawns Claude Code **with `--dangerously-skip-permissions`** — Claude can read,
+  write, and run commands in the registered project directory without per-action
+  prompts. This is intentional: it's *your* machine, *your* Claude login, and
+  *your* token, and the point of the bridge is hands-off remote execution.
+- The **trust boundary is your daemon token plus your single-user host.** Anyone
+  who holds the token can drive Claude on your machine through the Nazar API.
+  Treat the token like an SSH key: keep `config.toml` locked down, and
+  rotate/revoke the token (from the dashboard) if it leaks.
+- The daemon only ever makes an **outbound** WebSocket connection — it opens no
+  listening port on your machine.
+
+If that posture isn't acceptable for a given machine, don't install the bridge
+there.
+
+---
+
+## Wire protocol
+
+The daemon and API speak JSON text frames over the WebSocket. The source of
+truth for the schemas is `apps/api/nazar_api/schemas/bridge.py`; the daemon's
+`nazar_bridge/wire.py` mirrors the relevant subset so the daemon stays
+installable independently of the API package.
+
+---
+
+## Develop / test
+
+```bash
+cd apps/bridge
+python -m pip install -e ".[dev]"
+pytest
+ruff check nazar_bridge tests
+mypy nazar_bridge
+```
+
+Build the distributables locally:
+
+```bash
+python -m build          # produces dist/*.whl and dist/*.tar.gz
+twine check dist/*
+```

nazar_bridge-0.1.0/nazar_bridge/__init__.py

@@ -0,0 +1,21 @@
+"""nazar-bridge — daemon that relays phone-prompts to local ``claude -p``.
+
+The daemon maintains a persistent outbound WebSocket connection to the
+Nazar API, registers the founder's local Claude Code project
+directories, and (in a follow-up ticket #26) shells out to
+``claude -p`` to execute prompts pushed from the dashboard.
+
+This module is intentionally tiny — every concern is split into a
+dedicated submodule:
+
+* :mod:`nazar_bridge.config`     — TOML config file load/save.
+* :mod:`nazar_bridge.client`     — async WebSocket client + reconnect.
+* :mod:`nazar_bridge.runner`     — long-running ``run()`` entrypoint.
+* :mod:`nazar_bridge.cli`        — argparse-based console script.
+* :mod:`nazar_bridge.wire`       — Pydantic wire-protocol schemas.
+* :mod:`nazar_bridge.exceptions` — typed errors surfaced to the CLI.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

nazar_bridge-0.1.0/nazar_bridge/__main__.py

@@ -0,0 +1,13 @@
+"""Allow ``python -m nazar_bridge`` as an equivalent to the console script.
+
+Useful when the package is installed but the ``nazar-bridge`` script
+isn't on the ``PATH`` (e.g. a venv that's been activated by absolute
+``python`` path).
+"""
+
+from __future__ import annotations
+
+from nazar_bridge.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())