phonedex-cli 0.1.0__tar.gz

phonedex_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Austin Harvey
+
+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.

phonedex_cli-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: phonedex-cli
+Version: 0.1.0
+Summary: An optional animated terminal cockpit and setup companion for PhoneDex
+Author: Austin Harvey
+License: MIT
+Keywords: phonedex,terminal,sip,telephony,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich<16,>=13.7
+Requires-Dist: psutil<8,>=5.9
+Dynamic: license-file
+
+# PhoneDex CLI
+
+**An optional, colorful terminal control deck for [PhoneDex](https://github.com/dexifried/Phonedex).**
+
+A Rich-powered ASCII dashboard, short startup animations, step-by-step setup, diagnostic panels, a managed-controller switchboard, and safe calling controls. **PhoneDex CLI is a separate frontend**, not a fork of the SIP bridge. Uninstalling it leaves PhoneDex's existing installation, config, and calls intact.
+
+```text
+  ____  _                     ____
+ |  _ \| |__   ___  _ __   ___|  _ \  _____  __
+ | |_) | '_ \ / _ \| '_ \ / _ \ | | |/ _ \ \/ /
+ |  __/| | | | (_) | | | |  __/ |_| |  __/>  <
+ |_|   |_| |_|\___/|_| |_|\___|____/ \___/_/\_\
+
+    TERMINAL CONTROL // an optional PhoneDex companion
+```
+
+## Quickstart
+
+Requires Python **3.11+**. Linux, macOS and Windows use the same commands. Git is needed **only** if you want the CLI to clone PhoneDex for you.
+
+```bash
+# Clone or unpack this separate phonedex-cli project
+cd phonedex-cli
+python -m pip install -e .
+
+# First-time users: interactive setup wizard
+phonedex-cli wizard
+
+# Regular users: animated control deck
+phonedex-cli
+```
+
+On some systems use `python3` and `python3 -m pip`. The installation above is editable/developer mode; end users can instead use `python -m pip install .` from the unpacked project. For isolation use a dedicated virtual environment. **This repository has not yet been released on PyPI.** Do not assume `pip install phonedex-cli` works from PyPI.
+
+### Existing PhoneDex installation?
+
+Either choose **existing** in `phonedex-cli wizard` or use:
+
+```bash
+phonedex-cli --checkout /path/to/Phonedex status
+phonedex-cli --checkout /path/to/Phonedex doctor --mode local
+```
+
+`PHONEDEX_HOME=/path/to/Phonedex` is also supported. The wizard saves the source path to a local config file, not the PhoneDex checkout. It never overwrites an existing `.env`.
+
+### Commands
+
+| Command | Behavior |
+| --- | --- |
+| `phonedex-cli` or `phonedex-cli menu` | Interactive ASCII/Rich terminal dashboard |
+| `phonedex-cli wizard` | Link/clone source, run optional bootstrap, local Codex login, delegate to official setup, inspect diagnostics |
+| `phonedex-cli doctor --mode local` | Official read-only source checks; change to `remote` when using a Worker |
+| `phonedex-cli setup --mode local` | Delegates to the existing core setup wizard |
+| `phonedex-cli status` | Local checkout, Codex command presence, privacy mode, CLI-managed process state |
+| `phonedex-cli start` | Start a CLI-managed controller **only with confirmation**; queued work can dispatch calls |
+| `phonedex-cli stop` | Stop **only** the controller this CLI started and recorded |
+| `phonedex-cli restart` | Confirm and restart a CLI-managed controller |
+| `phonedex-cli logs --lines 40` | Recent managed-controller logs (best-effort masking of secret-bearing lines) |
+| `phonedex-cli settings` | Private local editor: transcripts, retention, daily call cap, allowlisted phone numbers |
+| `phonedex-cli dial --to +14165550123` | Allowlisted **dry run** (no call) |
+| `phonedex-cli dial --to +14165550123 --place-call` | Explicit, **potentially billable** real call, requires confirmation |
+
+Use `--no-color --no-animation` for inaccessible or non-interactive terminals. Animation is automatically disabled when the output isn't a terminal or when `CI` is set. `--yes` applies **only** to `dial --place-call` and bypasses its second confirmation for deliberate automation; it still requires an allowlisted number and upstream PhoneDex safeguards.
+
+## Architecture and privacy
+
+```text
+phonedex-cli (optional UI)
+     │
+     ├─ ~/.config/phonedex-cli/config.json  → installed source path only
+     ├─ controller.json / controller.log    → CLI-managed subprocess only
+     │
+     └─ invokes official PhoneDex commands:
+          phonedex.py setup / doctor / dial / controller
+                         │
+          core .env, SIP gateway, GPT Live, optional Worker
+```
+
+- The CLI does **not** request or store SIP passwords, OAuth tokens, or AgentPhone keys. The official PhoneDex setup handles provider secrets privately.
+- The separate CLI only edits four whitelisted **non-secret** `.env` settings. It uses owner-restricted atomic replacement on POSIX, preserves unrelated variables and comments, and refuses symlink writes.
+- Configuration edits take effect for new PhoneDex processes. An already-running controller generally needs a restart; this CLI never restarts it automatically.
+- The CLI does **not** configure DNS, TLS certificates, Cloudflare resources, firewalls, port forwarding, telephony numbers, or SIP trunks.
+- Setup, status, diagnostics, and default dialing perform **no real phone call**. Starting the controller can execute requests already queued in a configured Worker; it requires confirmation.
+- Transcript storage defaults to `off` in the core. Choosing `worker` or `both` shares transcript text with **your own** Worker/KV. Changes apply to new calls and don't erase existing data.
+- The log viewer masks lines with common secret labels on a best-effort basis. Logs may still reveal phone numbers, call content, and metadata. Do not publish raw logs.
+- The controller PID registry records creation time and exact script path. **Stop will refuse** to terminate an unrelated process or a stale/reused PID. Controllers started outside this CLI are deliberately not managed.
+- Operational correctness and carrier compatibility depend on the PhoneDex core and your provider. Use [PhoneDex's release status](https://github.com/dexifried/Phonedex/blob/main/docs/RELEASE_STATUS.md).
+
+**Note:** PhoneDex uses an undocumented GPT Live subscription endpoint. Its availability and permission to use it may change. This CLI provides no guarantee of service or compliant use and is not affiliated with OpenAI, Codex, or AgentPhone.
+
+## Development
+
+```bash
+python -m pip install -e . pytest
+python -m pytest -q
+python -m phonedex_cli --no-animation --no-color status
+```
+
+Offline tests cover config preservation, allowlisting, confirmation gates, symlink protection, stale-process safety, and dry-run defaults. CI is configured for Windows, Linux and macOS, but actual results depend on running the workflow. Live carrier calls are **not** part of these tests.
+
+Licensed MIT. © 2026 Austin Harvey.

phonedex_cli-0.1.0/README.md

@@ -0,0 +1,101 @@
+# PhoneDex CLI
+
+**An optional, colorful terminal control deck for [PhoneDex](https://github.com/dexifried/Phonedex).**
+
+A Rich-powered ASCII dashboard, short startup animations, step-by-step setup, diagnostic panels, a managed-controller switchboard, and safe calling controls. **PhoneDex CLI is a separate frontend**, not a fork of the SIP bridge. Uninstalling it leaves PhoneDex's existing installation, config, and calls intact.
+
+```text
+  ____  _                     ____
+ |  _ \| |__   ___  _ __   ___|  _ \  _____  __
+ | |_) | '_ \ / _ \| '_ \ / _ \ | | |/ _ \ \/ /
+ |  __/| | | | (_) | | | |  __/ |_| |  __/>  <
+ |_|   |_| |_|\___/|_| |_|\___|____/ \___/_/\_\
+
+    TERMINAL CONTROL // an optional PhoneDex companion
+```
+
+## Quickstart
+
+Requires Python **3.11+**. Linux, macOS and Windows use the same commands. Git is needed **only** if you want the CLI to clone PhoneDex for you.
+
+```bash
+# Clone or unpack this separate phonedex-cli project
+cd phonedex-cli
+python -m pip install -e .
+
+# First-time users: interactive setup wizard
+phonedex-cli wizard
+
+# Regular users: animated control deck
+phonedex-cli
+```
+
+On some systems use `python3` and `python3 -m pip`. The installation above is editable/developer mode; end users can instead use `python -m pip install .` from the unpacked project. For isolation use a dedicated virtual environment. **This repository has not yet been released on PyPI.** Do not assume `pip install phonedex-cli` works from PyPI.
+
+### Existing PhoneDex installation?
+
+Either choose **existing** in `phonedex-cli wizard` or use:
+
+```bash
+phonedex-cli --checkout /path/to/Phonedex status
+phonedex-cli --checkout /path/to/Phonedex doctor --mode local
+```
+
+`PHONEDEX_HOME=/path/to/Phonedex` is also supported. The wizard saves the source path to a local config file, not the PhoneDex checkout. It never overwrites an existing `.env`.
+
+### Commands
+
+| Command | Behavior |
+| --- | --- |
+| `phonedex-cli` or `phonedex-cli menu` | Interactive ASCII/Rich terminal dashboard |
+| `phonedex-cli wizard` | Link/clone source, run optional bootstrap, local Codex login, delegate to official setup, inspect diagnostics |
+| `phonedex-cli doctor --mode local` | Official read-only source checks; change to `remote` when using a Worker |
+| `phonedex-cli setup --mode local` | Delegates to the existing core setup wizard |
+| `phonedex-cli status` | Local checkout, Codex command presence, privacy mode, CLI-managed process state |
+| `phonedex-cli start` | Start a CLI-managed controller **only with confirmation**; queued work can dispatch calls |
+| `phonedex-cli stop` | Stop **only** the controller this CLI started and recorded |
+| `phonedex-cli restart` | Confirm and restart a CLI-managed controller |
+| `phonedex-cli logs --lines 40` | Recent managed-controller logs (best-effort masking of secret-bearing lines) |
+| `phonedex-cli settings` | Private local editor: transcripts, retention, daily call cap, allowlisted phone numbers |
+| `phonedex-cli dial --to +14165550123` | Allowlisted **dry run** (no call) |
+| `phonedex-cli dial --to +14165550123 --place-call` | Explicit, **potentially billable** real call, requires confirmation |
+
+Use `--no-color --no-animation` for inaccessible or non-interactive terminals. Animation is automatically disabled when the output isn't a terminal or when `CI` is set. `--yes` applies **only** to `dial --place-call` and bypasses its second confirmation for deliberate automation; it still requires an allowlisted number and upstream PhoneDex safeguards.
+
+## Architecture and privacy
+
+```text
+phonedex-cli (optional UI)
+     │
+     ├─ ~/.config/phonedex-cli/config.json  → installed source path only
+     ├─ controller.json / controller.log    → CLI-managed subprocess only
+     │
+     └─ invokes official PhoneDex commands:
+          phonedex.py setup / doctor / dial / controller
+                         │
+          core .env, SIP gateway, GPT Live, optional Worker
+```
+
+- The CLI does **not** request or store SIP passwords, OAuth tokens, or AgentPhone keys. The official PhoneDex setup handles provider secrets privately.
+- The separate CLI only edits four whitelisted **non-secret** `.env` settings. It uses owner-restricted atomic replacement on POSIX, preserves unrelated variables and comments, and refuses symlink writes.
+- Configuration edits take effect for new PhoneDex processes. An already-running controller generally needs a restart; this CLI never restarts it automatically.
+- The CLI does **not** configure DNS, TLS certificates, Cloudflare resources, firewalls, port forwarding, telephony numbers, or SIP trunks.
+- Setup, status, diagnostics, and default dialing perform **no real phone call**. Starting the controller can execute requests already queued in a configured Worker; it requires confirmation.
+- Transcript storage defaults to `off` in the core. Choosing `worker` or `both` shares transcript text with **your own** Worker/KV. Changes apply to new calls and don't erase existing data.
+- The log viewer masks lines with common secret labels on a best-effort basis. Logs may still reveal phone numbers, call content, and metadata. Do not publish raw logs.
+- The controller PID registry records creation time and exact script path. **Stop will refuse** to terminate an unrelated process or a stale/reused PID. Controllers started outside this CLI are deliberately not managed.
+- Operational correctness and carrier compatibility depend on the PhoneDex core and your provider. Use [PhoneDex's release status](https://github.com/dexifried/Phonedex/blob/main/docs/RELEASE_STATUS.md).
+
+**Note:** PhoneDex uses an undocumented GPT Live subscription endpoint. Its availability and permission to use it may change. This CLI provides no guarantee of service or compliant use and is not affiliated with OpenAI, Codex, or AgentPhone.
+
+## Development
+
+```bash
+python -m pip install -e . pytest
+python -m pytest -q
+python -m phonedex_cli --no-animation --no-color status
+```
+
+Offline tests cover config preservation, allowlisting, confirmation gates, symlink protection, stale-process safety, and dry-run defaults. CI is configured for Windows, Linux and macOS, but actual results depend on running the workflow. Live carrier calls are **not** part of these tests.
+
+Licensed MIT. © 2026 Austin Harvey.

phonedex_cli-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "phonedex-cli"
+version = "0.1.0"
+description = "An optional animated terminal cockpit and setup companion for PhoneDex"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{name = "Austin Harvey"}]
+dependencies = ["rich>=13.7,<16", "psutil>=5.9,<8"]
+keywords = ["phonedex", "terminal", "sip", "telephony", "cli"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Telephony",
+]
+
+[project.scripts]
+phonedex-cli = "phonedex_cli.app:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

phonedex_cli-0.1.0/setup.cfg

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

phonedex_cli-0.1.0/src/phonedex_cli/__init__.py

@@ -0,0 +1,2 @@
+"""Optional terminal cockpit for the PhoneDex core."""
+__version__ = "0.1.0"

phonedex_cli-0.1.0/src/phonedex_cli/__main__.py

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

phonedex_cli-0.1.0/src/phonedex_cli/app.py

@@ -0,0 +1,369 @@
+"""Rich-powered PhoneDex companion. No SIP internals are duplicated here."""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from rich import box
+from rich.align import Align
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.prompt import Confirm, IntPrompt, Prompt
+from rich.table import Table
+from rich.text import Text
+
+from . import __version__
+from . import core
+
+ASCII = r"""
+  ____  _                     ____
+ |  _ \| |__   ___  _ __   ___|  _ \  _____  __
+ | |_) | '_ \ / _ \| '_ \ / _ \ | | |/ _ \ \/ /
+ |  __/| | | | (_) | | | |  __/ |_| |  __/>  <
+ |_|   |_| |_|\___/|_| |_|\___|____/ \___/_/\_\
+"""
+
+class Cockpit:
+    def __init__(self, *, no_color: bool = False, no_animation: bool = False, checkout: str | None = None):
+        self.console = Console(no_color=no_color or bool(os.environ.get("NO_COLOR")))
+        self.animations = not no_animation and self.console.is_terminal and not os.environ.get("CI")
+        self.checkout_override = checkout
+
+    def banner(self) -> None:
+        art = Text(ASCII, style="bold bright_cyan")
+        if self.animations:
+            # A short, skippable terminal-only text reveal; never animates in CI/pipes.
+            with Live(Align.center(Text("Initializing PhoneDex", style="bright_cyan")),
+                      console=self.console, transient=True, auto_refresh=False) as live:
+                for shown in range(0, len(ASCII) + 16, max(12, len(ASCII) // 9)):
+                    live.update(Align.center(Text(ASCII[:shown], style="bold bright_cyan")), refresh=True)
+                    time.sleep(0.025)
+        self.console.print(Align.center(art))
+        self.console.print(Align.center(Text("TERMINAL CONTROL  //  an optional PhoneDex companion", style="bold magenta")))
+        self.console.print(Align.center(Text(f"v{__version__} · local-first · separate from the SIP engine", style="dim")))
+        self.console.print()
+
+    def transition(self, message: str) -> None:
+        if not self.animations:
+            return
+        with self.console.status(f"[cyan]{message}[/cyan]", spinner="dots12"):
+            time.sleep(0.32)
+
+    def root(self) -> Path | None:
+        return core.get_checkout(self.checkout_override)
+
+    def require_root(self) -> Path:
+        root = self.root()
+        if root is None:
+            raise RuntimeError("PhoneDex source checkout not configured. Run 'phonedex-cli wizard' first.")
+        return root
+
+    def status(self) -> None:
+        root = self.root()
+        state, record = core.controller_status(root)
+        table = Table(title="PhoneDex system overview", box=box.ROUNDED, header_style="bold cyan")
+        table.add_column("Component", style="bold")
+        table.add_column("Status")
+        table.add_column("Detail", overflow="fold")
+        table.add_row("Core checkout", "[green]Found[/green]" if root else "[yellow]Not configured[/yellow]", str(root) if root else "Run wizard")
+        table.add_row("Python", "[green]Available[/green]" if sys.version_info >= (3, 11) else "[red]Too old[/red]", sys.version.split()[0])
+        table.add_row("Codex CLI", "[green]Detected[/green]" if shutil.which("codex") else "[yellow]Not in PATH[/yellow]", "Sign in locally using codex login" if shutil.which("codex") else "Install separately before GPT Live use")
+        label = {"running": "[green]Running[/green]", "stopped": "[dim]Stopped[/dim]", "stale": "[yellow]Not running (stale PID)[/yellow]", "other-checkout": "[yellow]Different checkout[/yellow]"}[state]
+        table.add_row("Managed controller", label, f"PID {record.get('pid')}" if state == "running" else "")
+        if root:
+            details = core.parse_env(root / ".env")
+            mode = details.get("PHONEDEX_TRANSCRIPT_MODE", "off")
+            table.add_row("Local config", "[green]Present[/green]" if (root / ".env").is_file() else "[yellow]Not set up[/yellow]", f"transcripts={mode}; recipients={len([n for n in details.get('PHONEDEX_ALLOWED_RECIPIENTS', '').split(',') if n.strip()])}")
+            venv = root / ".venv"
+            table.add_row("Python environment", "[green]Isolated[/green]" if venv.is_dir() else "[yellow]Not bootstrapped[/yellow]", str(venv) if venv.is_dir() else "Run wizard bootstrap")
+        self.console.print(table)
+        self.console.print("[dim]Status shows only processes started by this CLI. It does not inspect or control unrelated live gateways.[/dim]")
+
+    def check(self, mode: str = "local") -> int:
+        root = self.require_root()
+        self.transition("Reading readiness diagnostics")
+        results = [
+            ("Setup readiness", core.core_argv(root, "setup", "--mode", mode, "--check")),
+            ("Runtime doctor", core.core_argv(root, "doctor", "--mode", mode)),
+        ]
+        result_code = 0
+        for name, command in results:
+            self.console.rule(f"[cyan]{name}[/cyan]")
+            try:
+                result = core.safe_exec(command, cwd=root)
+            except (OSError, subprocess.TimeoutExpired) as exc:
+                self.console.print(f"[red]{name} could not run:[/red] {exc}")
+                result_code = 1
+                continue
+            for line in core.redact(result.stdout).splitlines():
+                if "=" in line and not line.startswith("["):
+                    key, _, value = line.partition("=")
+                    if value.strip() in {"ok", "valid", "none", "true"}:
+                        self.console.print(f"[green]●[/green] {key}: {value}")
+                    else:
+                        self.console.print(f"[cyan]•[/cyan] {key}: {value}")
+                else:
+                    self.console.print(line)
+            if result.stderr:
+                self.console.print("[yellow]Runtime detail:[/yellow] " + core.redact(result.stderr)[-1200:])
+            if result.returncode:
+                result_code = 1
+        self.console.print("[dim]Read-only checks. No call placed, firewall changed, or Worker deployed.[/dim]")
+        return result_code
+
+    def setup(self, mode: str = "local") -> int:
+        root = self.require_root()
+        self.console.print(Panel("This delegates to the [bold]official PhoneDex setup wizard[/bold].\nIt only writes local configuration with your permission; it cannot provision a provider or place calls.", title="Official core setup", border_style="cyan"))
+        if (root / ".env").exists():
+            self.console.print("[yellow]An existing .env was found. The core wizard refuses to overwrite it.[/yellow]")
+        if not Confirm.ask("Launch PhoneDex's local setup now?", default=True):
+            return 0
+        return subprocess.call(core.core_argv(root, "setup", "--mode", mode), cwd=root)
+
+    def wizard(self) -> None:
+        self.banner()
+        self.console.print(Panel("[bold]1[/bold]  Connect a PhoneDex checkout\n[bold]2[/bold]  Prepare Python dependencies\n[bold]3[/bold]  Codex login (performed locally)\n[bold]4[/bold]  SIP/provider configuration\n[bold]5[/bold]  Read-only diagnostics", title="First-run wizard", border_style="bright_cyan"))
+        root = self.root()
+        if root:
+            self.console.print(f"[green]✓[/green] Existing PhoneDex checkout: [bold]{root}[/bold]")
+            if not Confirm.ask("Use this checkout?", default=True):
+                root = None
+        if root is None:
+            action = Prompt.ask("PhoneDex source", choices=["existing", "clone"], default="clone")
+            if action == "existing":
+                while True:
+                    candidate = Path(Prompt.ask("Absolute or relative path to PhoneDex checkout")).expanduser()
+                    try:
+                        root = core.validate_checkout(candidate)
+                        break
+                    except ValueError as exc:
+                        self.console.print(f"[red]{exc}[/red]")
+                        if not Confirm.ask("Try another path?", default=True):
+                            return
+            else:
+                default = str(Path.home() / "PhoneDex")
+                target = Path(Prompt.ask("Clone into", default=default)).expanduser()
+                self.console.print("Clone source: [cyan]https://github.com/dexifried/Phonedex[/cyan]")
+                if not Confirm.ask(f"Clone the official public source to {target}?", default=True):
+                    return
+                self.transition("Preparing checkout")
+                core.clone_checkout(target)
+                root = core.validate_checkout(target)
+            core.set_checkout(root)
+        self.console.print(f"[green]✓[/green] Source linked: {root}")
+        mode = Prompt.ask("Setup mode", choices=["local", "remote"], default="local")
+        self.console.print("[dim]Local = outbound calling without Cloudflare. Remote = optional Worker-based agent control.[/dim]")
+        if Confirm.ask("Run the official dependency bootstrap?", default=True):
+            bootstrap = [sys.executable, str(root / "scripts" / "bootstrap.py")]
+            self.console.print("[dim]Core bootstrap asks before creating its .venv or installing dependencies.[/dim]")
+            code = subprocess.call(bootstrap, cwd=root)
+            if code:
+                self.console.print(f"[yellow]Bootstrap exited with code {code}. You can retry from the core checkout.[/yellow]")
+        if shutil.which("codex"):
+            if Confirm.ask("Open Codex's own local login flow now?", default=False):
+                subprocess.call(["codex", "login"])
+        else:
+            self.console.print("[yellow]Codex CLI is not in PATH. Install it and run 'codex login' before actual use.[/yellow]")
+        if Confirm.ask("Open the official PhoneDex SIP setup wizard?", default=True):
+            try:
+                self.setup(mode)
+            except (OSError, FileNotFoundError) as exc:
+                self.console.print(f"[yellow]Could not launch setup: {exc}[/yellow]")
+        if Confirm.ask("Run read-only readiness checks?", default=True):
+            self.check(mode)
+        self.console.print(Panel("[bold green]Wizard finished.[/bold green] No calls have been placed.\nCheck networking, provider settings, and the approved-recipient allowlist before any live call.", border_style="green"))
+
+    def start(self) -> None:
+        root = self.require_root()
+        self.console.print("[yellow]Starting the remote controller can accept queued call requests and potentially trigger billable calls.[/yellow]")
+        self.console.print("[dim]Only use this on a configured, trusted Worker with caller allowlisting and billing limits.[/dim]")
+        if not Confirm.ask("Start the local PhoneDex controller process?", default=False):
+            self.console.print("Cancelled; controller not started.")
+            return
+        pid = core.start_controller(root)
+        self.console.print(f"[green]Controller started[/green] (PID {pid}). Use [bold]phonedex-cli stop[/bold] to stop this CLI-managed process.")
+
+    def stop(self) -> None:
+        root = self.require_root()
+        if core.stop_controller(root):
+            self.console.print("[green]Controller stopped.[/green]")
+        else:
+            self.console.print("[yellow]No running controller managed by this CLI for this checkout.[/yellow]")
+
+    def restart(self) -> None:
+        root = self.require_root()
+        state, _ = core.controller_status(root)
+        self.console.print("[yellow]Restarting may resume queued call dispatch.[/yellow]")
+        if not Confirm.ask("Restart the CLI-managed controller?", default=False):
+            return
+        if state == "running":
+            if not core.stop_controller(root):
+                raise RuntimeError("Could not stop controller")
+        pid = core.start_controller(root)
+        self.console.print(f"[green]Controller running[/green] (PID {pid})")
+
+    def logs(self, lines: int = 40) -> None:
+        logfile = core.home_dir() / "controller.log"
+        if not logfile.is_file():
+            self.console.print("[yellow]No CLI-managed controller logs yet.[/yellow]")
+            return
+        self.console.print("[yellow]Logs may contain personal call metadata. The viewer masks obvious secret-bearing lines, not phone numbers.[/yellow]")
+        # Avoid huge log reads: tail by seeking from end, in binary mode.
+        with logfile.open("rb") as fh:
+            fh.seek(0, os.SEEK_END)
+            pos = fh.tell()
+            data = bytearray()
+            while pos > 0 and data.count(b"\n") <= lines:
+                read = min(pos, 4096)
+                pos -= read
+                fh.seek(pos)
+                data[:0] = fh.read(read)
+                if len(data) > 1024 * 1024:
+                    break
+        text = data.decode("utf-8", errors="replace")
+        self.console.print(core.redact("\n".join(text.splitlines()[-lines:])), markup=False, highlight=False)
+
+    def settings(self) -> None:
+        root = self.require_root()
+        env = root / ".env"
+        if not env.is_file():
+            raise RuntimeError("Core .env not configured. Run wizard or setup first.")
+        while True:
+            values = core.parse_env(env)
+            self.console.print(Panel(f"Transcript storage: [bold]{values.get('PHONEDEX_TRANSCRIPT_MODE','off')}[/bold]\n"
+                         f"Local retention: [bold]{values.get('PHONEDEX_TRANSCRIPT_RETENTION_DAYS','7')} days[/bold]\n"
+                         f"Daily call cap: [bold]{values.get('PHONEDEX_MAX_CALLS_PER_DAY','12')}[/bold]\n"
+                         f"Allowlisted recipients: [bold]{len([v for v in values.get('PHONEDEX_ALLOWED_RECIPIENTS','').split(',') if v.strip()])}[/bold]",
+                         title="Private settings", border_style="magenta"))
+            choice = Prompt.ask("Edit", choices=["privacy", "retention", "limit", "allowlist", "back"], default="back")
+            if choice == "back":
+                return
+            if choice == "privacy":
+                self.console.print("[dim]off=none; local=SQLite; worker=Worker/KV; both=local+Worker. Changes affect new calls only.[/dim]")
+                value = Prompt.ask("Transcript mode", choices=["off", "local", "worker", "both"], default=values.get("PHONEDEX_TRANSCRIPT_MODE", "off"))
+                if value in ("worker", "both") and not Confirm.ask("This uploads transcript text to your configured Worker. Continue?", default=False):
+                    continue
+                key = "PHONEDEX_TRANSCRIPT_MODE"
+            elif choice == "retention":
+                key, value = "PHONEDEX_TRANSCRIPT_RETENTION_DAYS", str(IntPrompt.ask("Local retention (1-90 days)", default=7))
+            elif choice == "limit":
+                key, value = "PHONEDEX_MAX_CALLS_PER_DAY", str(IntPrompt.ask("Maximum calls per day (1-1000)", default=12))
+            else:
+                key = "PHONEDEX_ALLOWED_RECIPIENTS"
+                self.console.print("[dim]E.164 format, separated by commas. Leave blank to block all outbound recipients.[/dim]")
+                value = Prompt.ask("Allowed numbers", default=values.get(key, ""), show_default=False)
+            core.update_env(env, key, value)
+            self.console.print("[green]Setting saved.[/green] New PhoneDex processes will read it. Restart any already-running controller to apply changes there.")
+
+    def dial(self, to: str, mode: str = "normal", place_call: bool = False, yes: bool = False, duration: int = 60) -> int:
+        root = self.require_root()
+        if not core.E164.fullmatch(to):
+            raise ValueError("Use E.164 recipient format, e.g. +14165550123")
+        configured = core.parse_env(root / ".env")
+        allowed = {n.strip() for n in configured.get("PHONEDEX_ALLOWED_RECIPIENTS", "").split(",") if n.strip()}
+        if to not in allowed:
+            raise ValueError("Recipient not in PHONEDEX_ALLOWED_RECIPIENTS (default-deny)")
+        if not 20 <= duration <= 300:
+            raise ValueError("Duration must be between 20 and 300 seconds")
+        argv = core.core_argv(root, "dial", "--to", to, "--mode", mode, "--duration", str(duration))
+        if place_call:
+            self.console.print(Panel(f"[bold yellow]REAL, POTENTIALLY BILLABLE CALL[/bold yellow]\nRecipient: {to}\nMax duration: {duration} seconds", border_style="yellow"))
+            if not yes and not Confirm.ask("Place this live call now?", default=False):
+                self.console.print("Call cancelled.")
+                return 0
+            argv += ["--place-call"]
+        else:
+            self.console.print("[green]Dry run only.[/green] No live call will be placed.")
+        return subprocess.call(argv, cwd=root)
+
+    def menu(self) -> None:
+        self.banner()
+        while True:
+            self.status()
+            self.console.print(Panel("[cyan]1[/cyan] Setup wizard     [cyan]2[/cyan] Readiness doctor     [cyan]3[/cyan] Start controller\n"
+                                     "[cyan]4[/cyan] Stop controller   [cyan]5[/cyan] Restart controller    [cyan]6[/cyan] View logs\n"
+                                     "[cyan]7[/cyan] Settings          [cyan]8[/cyan] Dial (dry run first)  [cyan]0[/cyan] Exit",
+                                     border_style="bright_magenta", title="Control deck"))
+            choice = Prompt.ask("Select", choices=list("012345678"), default="0")
+            if choice == "0":
+                return
+            try:
+                if choice == "1": self.wizard()
+                elif choice == "2": self.check()
+                elif choice == "3": self.start()
+                elif choice == "4": self.stop()
+                elif choice == "5": self.restart()
+                elif choice == "6": self.logs()
+                elif choice == "7": self.settings()
+                else:
+                    number = Prompt.ask("E.164 destination")
+                    minutes = IntPrompt.ask("Max duration (seconds)", default=60)
+                    self.dial(number, duration=minutes)
+                    if Confirm.ask("Try a real call to this approved number?", default=False):
+                        self.dial(number, duration=minutes, place_call=True)
+            except (ValueError, RuntimeError, OSError, subprocess.SubprocessError) as exc:
+                self.console.print(f"[red]Action failed:[/red] {exc}")
+            self.console.print()
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description="Optional Rich terminal interface for PhoneDex")
+    p.add_argument("--checkout", help="Path to existing official PhoneDex source checkout")
+    p.add_argument("--no-color", action="store_true", help="Disable ANSI coloring")
+    p.add_argument("--no-animation", action="store_true", help="Disable startup transitions")
+    p.add_argument("--version", action="version", version=__version__)
+    commands = p.add_subparsers(dest="action")
+    commands.add_parser("menu", help="Interactive terminal control deck")
+    commands.add_parser("wizard", help="Guided first-run setup")
+    commands.add_parser("status", help="Show configuration and managed controller status")
+    doc = commands.add_parser("doctor", help="Run official read-only PhoneDex diagnostics")
+    doc.add_argument("--mode", choices=["local", "remote"], default="local")
+    setup = commands.add_parser("setup", help="Run official PhoneDex setup wizard")
+    setup.add_argument("--mode", choices=["local", "remote"], default="local")
+    commands.add_parser("start", help="Start local controller with explicit confirmation")
+    commands.add_parser("stop", help="Stop only the controller started by this CLI")
+    commands.add_parser("restart", help="Restart CLI-managed controller with confirmation")
+    logs = commands.add_parser("logs", help="Display recent CLI-managed controller logs")
+    logs.add_argument("--lines", type=int, default=40)
+    commands.add_parser("settings", help="Change non-secret PhoneDex settings locally")
+    dial = commands.add_parser("dial", help="Allowlisted dry run by default; real calls opt-in")
+    dial.add_argument("--to", required=True, help="E.164 approved destination")
+    dial.add_argument("--mode", choices=["normal", "business"], default="normal")
+    dial.add_argument("--duration", type=int, default=60)
+    dial.add_argument("--place-call", action="store_true", help="Opt in to an actual carrier call")
+    dial.add_argument("--yes", action="store_true", help="Skip interactive live-call confirmation (automation only)")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    cli = Cockpit(no_color=args.no_color, no_animation=args.no_animation, checkout=args.checkout)
+    action = args.action or "menu"
+    try:
+        if action == "menu": cli.menu()
+        elif action == "wizard": cli.wizard()
+        elif action == "status": cli.banner(); cli.status()
+        elif action == "doctor": return cli.check(args.mode)
+        elif action == "setup": return cli.setup(args.mode)
+        elif action == "start": cli.start()
+        elif action == "stop": cli.stop()
+        elif action == "restart": cli.restart()
+        elif action == "logs": cli.logs(max(1, min(args.lines, 500)))
+        elif action == "settings": cli.settings()
+        elif action == "dial": return cli.dial(args.to, args.mode, args.place_call, args.yes, args.duration)
+        return 0
+    except (ValueError, RuntimeError, OSError, subprocess.SubprocessError) as exc:
+        cli.console.print(f"[red]PhoneDex CLI:[/red] {exc}")
+        return 2
+    except KeyboardInterrupt:
+        cli.console.print("\n[dim]Exited. Background controller, if running, is unchanged.[/dim]")
+        return 130
+
+if __name__ == "__main__":
+    raise SystemExit(main())

phonedex_cli-0.1.0/src/phonedex_cli/core.py

@@ -0,0 +1,276 @@
+"""Side-effect-aware local integration with the public PhoneDex checkout.
+
+Nothing in this module provisions a SIP trunk, forwards ports or places a call.
+The CLI delegates actual SIP work and configuration validation to PhoneDex.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import psutil
+
+UPSTREAM = "https://github.com/dexifried/Phonedex.git"
+E164 = re.compile(r"\+[1-9]\d{6,14}\Z")
+CONFIGURABLE = {"PHONEDEX_TRANSCRIPT_MODE", "PHONEDEX_TRANSCRIPT_RETENTION_DAYS",
+                "PHONEDEX_MAX_CALLS_PER_DAY", "PHONEDEX_ALLOWED_RECIPIENTS"}
+SENSITIVE = re.compile(r"(password|token|secret|api.?key|authorization|bearer)", re.I)
+
+
+def home_dir() -> Path:
+    override = os.environ.get("PHONEDEX_CLI_HOME")
+    if override:
+        return Path(override).expanduser()
+    if os.name == "nt" and os.environ.get("APPDATA"):
+        return Path(os.environ["APPDATA"]) / "PhoneDexCLI"
+    return Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "phonedex-cli"
+
+
+def preferences_file() -> Path:
+    return home_dir() / "config.json"
+
+
+def managed_file() -> Path:
+    return home_dir() / "controller.json"
+
+
+def _private_write(path: Path, data: str) -> None:
+    """Atomic owner-only write on POSIX; inherits local user ACLs on Windows."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.is_symlink():
+        raise ValueError(f"Refusing to write through symlink: {path}")
+    temp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    fd = os.open(temp, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as out:
+            out.write(data)
+            out.flush()
+            os.fsync(out.fileno())
+        os.replace(temp, path)
+    finally:
+        temp.unlink(missing_ok=True)
+
+
+def preferences() -> dict:
+    try:
+        val = json.loads(preferences_file().read_text(encoding="utf-8"))
+        return val if isinstance(val, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def set_checkout(path: Path) -> None:
+    path = validate_checkout(path)
+    prefs = preferences()
+    prefs["checkout"] = str(path)
+    _private_write(preferences_file(), json.dumps(prefs, indent=2) + "\n")
+
+
+def get_checkout(explicit: str | None = None) -> Path | None:
+    raw = explicit or os.environ.get("PHONEDEX_HOME") or preferences().get("checkout")
+    if not raw:
+        return None
+    try:
+        return validate_checkout(Path(raw))
+    except (ValueError, OSError):
+        return None
+
+
+def validate_checkout(path: Path) -> Path:
+    candidate = path.expanduser().resolve()
+    for file in ("phonedex.py", "onboarding.py", "scripts/bootstrap.py"):
+        if not (candidate / file).is_file():
+            raise ValueError(f"Not a compatible PhoneDex checkout (missing {file}): {candidate}")
+    return candidate
+
+
+def core_python(root: Path) -> str:
+    if os.name == "nt":
+        venv = root / ".venv" / "Scripts" / "python.exe"
+    else:
+        venv = root / ".venv" / "bin" / "python"
+    return str(venv) if venv.is_file() else sys.executable
+
+
+def core_argv(root: Path, *args: str) -> list[str]:
+    return [core_python(root), str(root / "phonedex.py"), *args]
+
+
+def safe_exec(argv: list[str], *, cwd: Path | None = None, timeout: int = 90) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(argv, cwd=cwd, text=True, encoding="utf-8", errors="replace",
+                          capture_output=True, timeout=timeout, check=False)
+
+
+def parse_env(path: Path) -> dict[str, str]:
+    result: dict[str, str] = {}
+    if not path.exists():
+        return result
+    for line in path.read_text(encoding="utf-8-sig").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        key = k.strip()
+        if not re.fullmatch(r"PHONEDEX_[A-Z0-9_]+", key):
+            continue
+        v = v.strip()
+        if len(v) >= 2 and v[0] in "\"'" and v[-1] == v[0]:
+            v = v[1:-1]
+        result[key] = v
+    return result
+
+
+def update_env(path: Path, key: str, value: str) -> None:
+    if key not in CONFIGURABLE:
+        raise ValueError(f"Setting not supported by CLI editor: {key}")
+    if path.is_symlink():
+        raise ValueError("Refusing to edit symlinked .env")
+    if not path.is_file():
+        raise ValueError("No .env found. Run PhoneDex setup first.")
+    if "\n" in value or "\r" in value or "#" in value:
+        raise ValueError("Invalid configuration value")
+    if key == "PHONEDEX_TRANSCRIPT_MODE" and value not in {"off", "local", "worker", "both"}:
+        raise ValueError("Invalid transcript mode")
+    if key == "PHONEDEX_TRANSCRIPT_RETENTION_DAYS" and not (value.isascii() and value.isdecimal() and 1 <= int(value) <= 90):
+        raise ValueError("Retention must be 1–90 days")
+    if key == "PHONEDEX_MAX_CALLS_PER_DAY" and not (value.isascii() and value.isdecimal() and 1 <= int(value) <= 1000):
+        raise ValueError("Daily limit must be 1–1000")
+    if key == "PHONEDEX_ALLOWED_RECIPIENTS":
+        numbers = [n.strip() for n in value.split(",") if n.strip()]
+        if any(not E164.fullmatch(n) for n in numbers) or len(numbers) != len(set(numbers)):
+            raise ValueError("Only unique E.164 phone numbers are allowed")
+        value = ",".join(numbers)
+    original = path.read_text(encoding="utf-8-sig")
+    parts = original.splitlines(keepends=True)
+    found = False
+    for i, line in enumerate(parts):
+        if re.match(r"^\s*" + re.escape(key) + r"\s*=", line):
+            if found:
+                raise ValueError("Duplicate setting present; resolve it manually")
+            parts[i] = key + "=" + value + ("\r\n" if line.endswith("\r\n") else "\n")
+            found = True
+    if not found:
+        if parts and not parts[-1].endswith(("\r", "\n")):
+            parts.append("\n")
+        parts.append(key + "=" + value + "\n")
+    _private_write(path, "".join(parts))
+
+
+def _record() -> dict:
+    try:
+        record = json.loads(managed_file().read_text(encoding="utf-8"))
+        return record if isinstance(record, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _matches(record: dict) -> psutil.Process | None:
+    try:
+        pid, created, script, root = int(record["pid"]), float(record["created"]), record["script"], record["root"]
+        if pid == os.getpid():
+            return None
+        proc = psutil.Process(pid)
+        if not proc.is_running() or proc.status() == psutil.STATUS_ZOMBIE or abs(proc.create_time() - created) >= 2:
+            return None
+        cmd = proc.cmdline()
+        # A stale or PID-reused record must never terminate another process.
+        if str(Path(script).resolve()) not in [str(Path(c).resolve()) for c in cmd]:
+            return None
+        if "controller" not in cmd:
+            return None
+        if str(Path(script).resolve().parent) != str(Path(root).resolve()):
+            return None
+        return proc
+    except (psutil.Error, OSError, ValueError, KeyError, TypeError):
+        return None
+
+
+def controller_status(root: Path | None = None) -> tuple[str, dict]:
+    record = _record()
+    if not record:
+        return "stopped", {}
+    proc = _matches(record)
+    if proc is None:
+        return "stale", record
+    if root is not None and Path(record["root"]).resolve() != root.resolve():
+        return "other-checkout", record
+    return "running", record
+
+
+def start_controller(root: Path) -> int:
+    state, _ = controller_status()
+    if state == "running":
+        raise RuntimeError("A controller managed by this CLI is already running")
+    logfile = home_dir() / "controller.log"
+    logfile.parent.mkdir(parents=True, exist_ok=True)
+    argv = core_argv(root, "controller")
+    options = {"cwd": root, "stdin": subprocess.DEVNULL}
+    if os.name == "nt":
+        options["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS
+    else:
+        options["start_new_session"] = True
+    with logfile.open("a", encoding="utf-8") as output:
+        proc = subprocess.Popen(argv, stdout=output, stderr=subprocess.STDOUT, **options)
+    try:
+        started = psutil.Process(proc.pid).create_time()
+        _private_write(managed_file(), json.dumps({"pid": proc.pid, "created": started,
+                  "root": str(root.resolve()), "script": str((root / "phonedex.py").resolve()),
+                  "log": str(logfile)}, indent=2) + "\n")
+    except Exception:
+        # Never orphan a controller if we cannot register it safely.
+        proc.terminate()
+        raise
+    time.sleep(0.2)
+    if proc.poll() is not None:
+        return_code = proc.returncode
+        managed_file().unlink(missing_ok=True)
+        raise RuntimeError(f"Controller exited during startup (code {return_code}); view logs")
+    return proc.pid
+
+
+def stop_controller(root: Path) -> bool:
+    state, record = controller_status(root)
+    if state != "running":
+        return False
+    proc = _matches(record)
+    if proc is None:
+        return False
+    proc.terminate()
+    try:
+        proc.wait(timeout=8)
+    except psutil.TimeoutExpired:
+        # Do not force-kill; callers can inspect process and stop it manually.
+        raise RuntimeError("Controller did not stop within 8 seconds; not force-killing")
+    managed_file().unlink(missing_ok=True)
+    return True
+
+
+def clone_checkout(dest: Path) -> None:
+    if dest.exists():
+        raise ValueError("Destination already exists; refusing to overwrite it")
+    git = shutil.which("git")
+    if not git:
+        raise RuntimeError("Git was not found; install Git or point the CLI to an existing checkout")
+    # Public upstream only; no credentials or local arbitrary URLs.
+    completed = safe_exec([git, "clone", "--depth", "1", UPSTREAM, str(dest)], timeout=180)
+    if completed.returncode:
+        raise RuntimeError("Git clone failed: " + completed.stderr[-1500:])
+    validate_checkout(dest)
+
+
+def redact(text: str) -> str:
+    """Best-effort log/output redaction; never claim complete sanitization."""
+    clean = []
+    for line in text.splitlines():
+        if SENSITIVE.search(line):
+            clean.append("[redacted sensitive line]")
+        else:
+            clean.append(line)
+    return "\n".join(clean)

phonedex_cli-0.1.0/src/phonedex_cli.egg-info/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: phonedex-cli
+Version: 0.1.0
+Summary: An optional animated terminal cockpit and setup companion for PhoneDex
+Author: Austin Harvey
+License: MIT
+Keywords: phonedex,terminal,sip,telephony,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich<16,>=13.7
+Requires-Dist: psutil<8,>=5.9
+Dynamic: license-file
+
+# PhoneDex CLI
+
+**An optional, colorful terminal control deck for [PhoneDex](https://github.com/dexifried/Phonedex).**
+
+A Rich-powered ASCII dashboard, short startup animations, step-by-step setup, diagnostic panels, a managed-controller switchboard, and safe calling controls. **PhoneDex CLI is a separate frontend**, not a fork of the SIP bridge. Uninstalling it leaves PhoneDex's existing installation, config, and calls intact.
+
+```text
+  ____  _                     ____
+ |  _ \| |__   ___  _ __   ___|  _ \  _____  __
+ | |_) | '_ \ / _ \| '_ \ / _ \ | | |/ _ \ \/ /
+ |  __/| | | | (_) | | | |  __/ |_| |  __/>  <
+ |_|   |_| |_|\___/|_| |_|\___|____/ \___/_/\_\
+
+    TERMINAL CONTROL // an optional PhoneDex companion
+```
+
+## Quickstart
+
+Requires Python **3.11+**. Linux, macOS and Windows use the same commands. Git is needed **only** if you want the CLI to clone PhoneDex for you.
+
+```bash
+# Clone or unpack this separate phonedex-cli project
+cd phonedex-cli
+python -m pip install -e .
+
+# First-time users: interactive setup wizard
+phonedex-cli wizard
+
+# Regular users: animated control deck
+phonedex-cli
+```
+
+On some systems use `python3` and `python3 -m pip`. The installation above is editable/developer mode; end users can instead use `python -m pip install .` from the unpacked project. For isolation use a dedicated virtual environment. **This repository has not yet been released on PyPI.** Do not assume `pip install phonedex-cli` works from PyPI.
+
+### Existing PhoneDex installation?
+
+Either choose **existing** in `phonedex-cli wizard` or use:
+
+```bash
+phonedex-cli --checkout /path/to/Phonedex status
+phonedex-cli --checkout /path/to/Phonedex doctor --mode local
+```
+
+`PHONEDEX_HOME=/path/to/Phonedex` is also supported. The wizard saves the source path to a local config file, not the PhoneDex checkout. It never overwrites an existing `.env`.
+
+### Commands
+
+| Command | Behavior |
+| --- | --- |
+| `phonedex-cli` or `phonedex-cli menu` | Interactive ASCII/Rich terminal dashboard |
+| `phonedex-cli wizard` | Link/clone source, run optional bootstrap, local Codex login, delegate to official setup, inspect diagnostics |
+| `phonedex-cli doctor --mode local` | Official read-only source checks; change to `remote` when using a Worker |
+| `phonedex-cli setup --mode local` | Delegates to the existing core setup wizard |
+| `phonedex-cli status` | Local checkout, Codex command presence, privacy mode, CLI-managed process state |
+| `phonedex-cli start` | Start a CLI-managed controller **only with confirmation**; queued work can dispatch calls |
+| `phonedex-cli stop` | Stop **only** the controller this CLI started and recorded |
+| `phonedex-cli restart` | Confirm and restart a CLI-managed controller |
+| `phonedex-cli logs --lines 40` | Recent managed-controller logs (best-effort masking of secret-bearing lines) |
+| `phonedex-cli settings` | Private local editor: transcripts, retention, daily call cap, allowlisted phone numbers |
+| `phonedex-cli dial --to +14165550123` | Allowlisted **dry run** (no call) |
+| `phonedex-cli dial --to +14165550123 --place-call` | Explicit, **potentially billable** real call, requires confirmation |
+
+Use `--no-color --no-animation` for inaccessible or non-interactive terminals. Animation is automatically disabled when the output isn't a terminal or when `CI` is set. `--yes` applies **only** to `dial --place-call` and bypasses its second confirmation for deliberate automation; it still requires an allowlisted number and upstream PhoneDex safeguards.
+
+## Architecture and privacy
+
+```text
+phonedex-cli (optional UI)
+     │
+     ├─ ~/.config/phonedex-cli/config.json  → installed source path only
+     ├─ controller.json / controller.log    → CLI-managed subprocess only
+     │
+     └─ invokes official PhoneDex commands:
+          phonedex.py setup / doctor / dial / controller
+                         │
+          core .env, SIP gateway, GPT Live, optional Worker
+```
+
+- The CLI does **not** request or store SIP passwords, OAuth tokens, or AgentPhone keys. The official PhoneDex setup handles provider secrets privately.
+- The separate CLI only edits four whitelisted **non-secret** `.env` settings. It uses owner-restricted atomic replacement on POSIX, preserves unrelated variables and comments, and refuses symlink writes.
+- Configuration edits take effect for new PhoneDex processes. An already-running controller generally needs a restart; this CLI never restarts it automatically.
+- The CLI does **not** configure DNS, TLS certificates, Cloudflare resources, firewalls, port forwarding, telephony numbers, or SIP trunks.
+- Setup, status, diagnostics, and default dialing perform **no real phone call**. Starting the controller can execute requests already queued in a configured Worker; it requires confirmation.
+- Transcript storage defaults to `off` in the core. Choosing `worker` or `both` shares transcript text with **your own** Worker/KV. Changes apply to new calls and don't erase existing data.
+- The log viewer masks lines with common secret labels on a best-effort basis. Logs may still reveal phone numbers, call content, and metadata. Do not publish raw logs.
+- The controller PID registry records creation time and exact script path. **Stop will refuse** to terminate an unrelated process or a stale/reused PID. Controllers started outside this CLI are deliberately not managed.
+- Operational correctness and carrier compatibility depend on the PhoneDex core and your provider. Use [PhoneDex's release status](https://github.com/dexifried/Phonedex/blob/main/docs/RELEASE_STATUS.md).
+
+**Note:** PhoneDex uses an undocumented GPT Live subscription endpoint. Its availability and permission to use it may change. This CLI provides no guarantee of service or compliant use and is not affiliated with OpenAI, Codex, or AgentPhone.
+
+## Development
+
+```bash
+python -m pip install -e . pytest
+python -m pytest -q
+python -m phonedex_cli --no-animation --no-color status
+```
+
+Offline tests cover config preservation, allowlisting, confirmation gates, symlink protection, stale-process safety, and dry-run defaults. CI is configured for Windows, Linux and macOS, but actual results depend on running the workflow. Live carrier calls are **not** part of these tests.
+
+Licensed MIT. © 2026 Austin Harvey.

phonedex_cli-0.1.0/src/phonedex_cli.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/phonedex_cli/__init__.py
+src/phonedex_cli/__main__.py
+src/phonedex_cli/app.py
+src/phonedex_cli/core.py
+src/phonedex_cli.egg-info/PKG-INFO
+src/phonedex_cli.egg-info/SOURCES.txt
+src/phonedex_cli.egg-info/dependency_links.txt
+src/phonedex_cli.egg-info/entry_points.txt
+src/phonedex_cli.egg-info/requires.txt
+src/phonedex_cli.egg-info/top_level.txt
+tests/test_app.py
+tests/test_core.py

phonedex_cli-0.1.0/src/phonedex_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

phonedex_cli-0.1.0/src/phonedex_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+phonedex-cli = phonedex_cli.app:main

phonedex_cli-0.1.0/src/phonedex_cli.egg-info/requires.txt

@@ -0,0 +1,2 @@
+rich<16,>=13.7
+psutil<8,>=5.9

phonedex_cli-0.1.0/src/phonedex_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+phonedex_cli

phonedex_cli-0.1.0/tests/test_app.py

@@ -0,0 +1,54 @@
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from phonedex_cli import app
+from phonedex_cli import core
+
+
+def test_version(capsys):
+    with pytest.raises(SystemExit) as exc:
+        app.main(["--version"])
+    assert exc.value.code == 0
+    assert "0.1.0" in capsys.readouterr().out
+
+
+def test_dial_requires_existing_checkout():
+    with patch.object(core, "get_checkout", return_value=None):
+        assert app.main(["--no-animation", "dial", "--to", "+12125550123"]) == 2
+
+
+def test_dial_dry_run_default(tmp_path, monkeypatch):
+    (tmp_path / ".env").write_text("PHONEDEX_ALLOWED_RECIPIENTS=+12125550123\n")
+    with patch.object(core, "get_checkout", return_value=tmp_path):
+        with patch.object(app.subprocess, "call", return_value=0) as call:
+            assert app.main(["--no-color", "--no-animation", "dial", "--to", "+12125550123"]) == 0
+            argv = call.call_args[0][0]
+            assert "--place-call" not in argv
+            assert "dial" in argv
+
+
+def test_dial_not_allowlisted(tmp_path):
+    (tmp_path / ".env").write_text("PHONEDEX_ALLOWED_RECIPIENTS=\n")
+    with patch.object(core, "get_checkout", return_value=tmp_path):
+        with patch.object(app.subprocess, "call") as call:
+            assert app.main(["--no-animation", "dial", "--to", "+12125550123", "--place-call", "--yes"]) == 2
+            call.assert_not_called()
+
+
+def test_real_call_requires_confirmation(tmp_path):
+    (tmp_path / ".env").write_text("PHONEDEX_ALLOWED_RECIPIENTS=+12125550123\n")
+    with patch.object(core, "get_checkout", return_value=tmp_path):
+        with patch.object(app.Confirm, "ask", return_value=False):
+            with patch.object(app.subprocess, "call") as call:
+                assert app.main(["--no-animation", "dial", "--to", "+12125550123", "--place-call"]) == 0
+                call.assert_not_called()
+
+
+def test_start_requires_explicit_confirmation(tmp_path):
+    with patch.object(core, "get_checkout", return_value=tmp_path):
+        with patch.object(app.Confirm, "ask", return_value=False):
+            with patch.object(core, "start_controller") as start:
+                assert app.main(["--no-animation", "start"]) == 0
+                start.assert_not_called()

phonedex_cli-0.1.0/tests/test_core.py

@@ -0,0 +1,119 @@
+import json
+import os
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from phonedex_cli import core
+
+
+def valid_root(tmp_path):
+    for rel in ["phonedex.py", "onboarding.py", "scripts/bootstrap.py"]:
+        path = tmp_path / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("# stub\n")
+    return tmp_path
+
+
+def test_checkout_validation(tmp_path):
+    with pytest.raises(ValueError, match="missing phonedex.py"):
+        core.validate_checkout(tmp_path)
+    assert core.validate_checkout(valid_root(tmp_path)) == tmp_path.resolve()
+
+
+def test_preference_keeps_checkout_without_touching_core(tmp_path, monkeypatch):
+    monkeypatch.setenv("PHONEDEX_CLI_HOME", str(tmp_path / "settings"))
+    src = valid_root(tmp_path / "core")
+    core.set_checkout(src)
+    assert core.get_checkout() == src.resolve()
+    assert not (src / ".env").exists()
+    assert json.loads(core.preferences_file().read_text())["checkout"] == str(src)
+
+
+def test_update_env_preserves_existing_secrets_and_comments(tmp_path):
+    p = tmp_path / ".env"
+    p.write_text("# private settings\nPHONEDEX_SIP_PASSWORD=do-not-leak\nPHONEDEX_TRANSCRIPT_MODE=off\n", encoding="utf-8")
+    core.update_env(p, "PHONEDEX_TRANSCRIPT_MODE", "local")
+    content = p.read_text()
+    assert "PHONEDEX_SIP_PASSWORD=do-not-leak" in content
+    assert "# private settings" in content
+    assert "PHONEDEX_TRANSCRIPT_MODE=local" in content
+    assert core.parse_env(p)["PHONEDEX_TRANSCRIPT_MODE"] == "local"
+    if os.name != "nt":
+        assert (p.stat().st_mode & 0o077) == 0
+
+
+def test_update_env_guards(tmp_path):
+    p = tmp_path / ".env"
+    p.write_text("PHONEDEX_ALLOWED_RECIPIENTS=\n")
+    for bad in ["123", "+1212\nPHONEDEX_SIP_PASSWORD=pwn", "+12125550101,+12125550101"]:
+        with pytest.raises(ValueError):
+            core.update_env(p, "PHONEDEX_ALLOWED_RECIPIENTS", bad)
+    with pytest.raises(ValueError):
+        core.update_env(p, "PHONEDEX_SIP_PASSWORD", "change-me")
+    with pytest.raises(ValueError):
+        core.update_env(p, "PHONEDEX_TRANSCRIPT_MODE", "everything")
+    core.update_env(p, "PHONEDEX_ALLOWED_RECIPIENTS", "+12125550101,+14165550123")
+    assert core.parse_env(p)["PHONEDEX_ALLOWED_RECIPIENTS"] == "+12125550101,+14165550123"
+    for bad in ["0", "91", "-1", "2x"]:
+        with pytest.raises(ValueError):
+            core.update_env(p, "PHONEDEX_TRANSCRIPT_RETENTION_DAYS", bad)
+
+
+def test_update_env_rejects_duplicate_key(tmp_path):
+    path = tmp_path / ".env"
+    path.write_text("PHONEDEX_TRANSCRIPT_MODE=off\nPHONEDEX_TRANSCRIPT_MODE=both\n")
+    with pytest.raises(ValueError, match="Duplicate"):
+        core.update_env(path, "PHONEDEX_TRANSCRIPT_MODE", "local")
+
+
+def test_update_env_refuses_symlink(tmp_path):
+    original = tmp_path / "target"
+    original.write_text("PHONEDEX_TRANSCRIPT_MODE=off\n")
+    link = tmp_path / ".env"
+    try:
+        link.symlink_to(original)
+    except (OSError, NotImplementedError):
+        pytest.skip("Symlink creation unsupported")
+    with pytest.raises(ValueError, match="symlink"):
+        core.update_env(link, "PHONEDEX_TRANSCRIPT_MODE", "local")
+
+
+def test_no_arbitrary_git_url(tmp_path, monkeypatch):
+    monkeypatch.setattr(core.shutil, "which", lambda _: None)
+    with pytest.raises(RuntimeError, match="Git was not found"):
+        core.clone_checkout(tmp_path / "fresh")
+    with pytest.raises(ValueError, match="exists"):
+        core.clone_checkout(tmp_path)
+
+
+def test_pid_reuse_cannot_target_another_process(tmp_path):
+    process = MagicMock()
+    process.is_running.return_value = True
+    process.status.return_value = "running"
+    process.create_time.return_value = 1234
+    process.cmdline.return_value = ["python", "something-else.py", "controller"]
+    record = {"pid": 50001, "created": 1234, "script": str(tmp_path / "phonedex.py"), "root": str(tmp_path)}
+    with patch.object(core.psutil, "Process", return_value=process):
+        assert core._matches(record) is None
+    process.cmdline.return_value = ["python", str(tmp_path / "phonedex.py"), "controller"]
+    process.create_time.return_value = 1
+    with patch.object(core.psutil, "Process", return_value=process):
+        assert core._matches(record) is None
+
+
+def test_controller_cannot_stop_unmanaged(tmp_path, monkeypatch):
+    monkeypatch.setenv("PHONEDEX_CLI_HOME", str(tmp_path / "settings"))
+    assert core.stop_controller(tmp_path) is False
+    core._private_write(core.managed_file(), json.dumps({"pid": 99999, "created": 20, "script": "/other", "root": "/other"}))
+    with patch.object(core.psutil, "Process", side_effect=core.psutil.NoSuchProcess(99999)):
+        assert core.stop_controller(tmp_path) is False
+
+
+def test_redacts_secret_lines():
+    value = "SIP_PASSWORD=hunter2\nCHECK_MODE=local\nAuthorization: Bearer test\n"
+    result = core.redact(value)
+    assert "hunter2" not in result
+    assert "Bearer test" not in result
+    assert "CHECK_MODE=local" in result