pinggy 0.4.9 → 0.5.1

package/CLAUDE.md

@@ -0,0 +1,112 @@
+## Project Overview 
+
+Pinggy CLI (`@pinggy/cli`) is a Node.js CLI tool for creating and managing Pinggy tunnels. It runs as **two processes**: a short-lived foreground CLI that the user invokes, and a long-running daemon that owns every tunnel. The CLI talks to the daemon over HTTP + WebSocket on `127.0.0.1`. Built with TypeScript, wraps the `@pinggy/pinggy` SDK in the daemon, and ships a blessed-based TUI plus remote control via WebSocket.
+
+## Common Commands
+
+```bash
+# Build (produces CJS + ESM in dist/)
+npm run build
+
+# TypeScript type-check only (output to dist_tsc/)
+npm run build:tsc
+
+# Dev workflow (link SDK, build, link locally)
+npm run dev
+
+# Build platform binaries (via pkg)
+npm run pack:all
+
+# E2E suite against a packaged binary (see test/e2e/README.md)
+node test/e2e/run.cjs out/pinggy-<platform>
+```
+
+## Architecture
+
+### Two-process model
+
+The CLI binary has 3 entry modes, dispatched in `src/main.ts`:
+
+1. **Daemon child** (`--_daemon-child` flag). Calls `runDaemonChild()` in `src/daemon/daemonChild.ts`. The CLI re-execs itself with this flag when it needs to spawn a daemon; users never invoke it directly.
+2. **Subcommand** (`config`, `start`, `stop`, `ps`, `attach`, `daemon`, `d`). Routes to `handleSubcommand()` in `src/cli/subcommands.ts`.
+3. **Legacy single-tunnel** (no subcommand). Routes to `buildAndStartTunnel()` for flags like `-l 3000` or `-R0:localhost:3000`.
+
+The daemon owns the `TunnelManager` singleton, the `@pinggy/pinggy` SDK, the web debugger server, and any `--serve` file servers. The CLI owns argument parsing, the TUI, the remote-management WebSocket client, and the IPC client to the daemon.
+
+### IPC: HTTP + WebSocket on localhost
+
+The daemon listens on `127.0.0.1` with an OS-assigned port (recorded in `daemon.json`):
+
+- **HTTP** for request/response (`src/daemon/ipcServer.ts`): `GET /ping`, `GET /tunnels`, `POST /tunnels/start`, `POST /tunnels/start-config`, `POST /tunnels/stop`, `POST /tunnels/restart`, `POST /shutdown`, plus v1 compatibility routes used by remote management.
+- **WebSocket** for streaming tunnel events (schema in `src/daemon/wsProtocol.ts`). Client subscribes by `tunnelId`; daemon emits `tunnel_event` frames keyed by event name.
+
+CLI code calls `TunnelClient` (`src/daemon/tunnelClient.ts`), the public facade that combines HTTP RPC with WebSocket event dispatch. `IPCClient` (`src/daemon/ipcClient.ts`) is the raw HTTP wrapper underneath; nothing outside `tunnelClient.ts` should touch it.
+
+### Daemon discovery and lifecycle
+
+`getDaemonInfo()` in `src/daemon/daemonManager.ts` reads `daemon.json`, validates the PID with `process.kill(pid, 0)`, deletes the file if stale, and returns `null` if no live daemon is found. `startDaemon()` spawns a detached daemon child and polls `daemon.json` for up to 8s.
+
+Single daemon per user. State lives under `~/.config/pinggy/` on Linux/macOS or `%APPDATA%/pinggy/` on Windows (helper: `src/utils/configDir.ts`):
+
+- `daemon.json`: `{pid, port, startedAt}`.
+- `daemon-state.json`: detached tunnel configs for crash recovery (`src/daemon/stateStore.ts`). Deleted on clean shutdown; replayed on next start.
+- `daemon.log`: SDK + daemon logs. CLI logs stay separate.
+- `tunnels/<name>_<configId>.json`: saved tunnel configs from `pinggy config save`.
+
+### Foreground vs detached tunnels
+
+`SessionTracker` (`src/daemon/sessionTracker.ts`) maps each `tunnelId` to a `sessionId` plus a mode:
+
+- **Foreground**: CLI holds an open WebSocket subscription. If the subscription closes, a 5-second grace period starts; if no other CLI re-attaches, the daemon stops the tunnel.
+- **Detached** (`-b` flag, or remote-management tunnels): tunnel persists in the daemon regardless of CLI presence and is recorded in `daemon-state.json`.
+
+`pinggy attach <name|id>` reopens a foreground subscription and renders the TUI.
+
+**Core types** are in `src/types.ts`: `TunnelStatus`, `Status`, `TunnelStateType` enum (`idle/starting/running/live/closed/exited`), `FinalConfig` (extends SDK's `TunnelConfigurationV1`). Browse `src/daemon/` and `src/cli/` for the rest of the module layout.
+
+## Subcommands (user-facing) 
+
+| Command | Purpose |
+|---|---|
+| `pinggy config list \| show \| save \| update \| delete \| auto \| noauto` | CRUD on saved tunnel configs |
+| `pinggy start <name...> [-b] [--all]` | Start saved tunnel(s). `-b` detaches; `--all` starts every auto-start config |
+| `pinggy stop <name\|id>` | Stop running tunnel(s) by name or ID prefix |
+| `pinggy ps` | Table of running tunnels (ID, name, status, local, URL) |
+| `pinggy attach <name\|id>` | Re-attach TUI to a running tunnel |
+| `pinggy daemon start \| stop \| status \| install-service \| uninstall-service` (alias `d`) | Daemon lifecycle and system-service installation |
+
+## Build System
+
+tsup bundles to `dist/` (CJS + ESM). tsc type-checks only (`npm run build:tsc`). pkg builds standalone platform binaries (`out/pinggy-<platform>`). ts-jest with the ESM preset for unit tests (`jest.config.cjs`).
+
+## Testing
+
+**Unit tests** live in `src/_tests_/`. Use `@jest/globals` imports (no global `jest`). `TunnelManager` is a singleton, so reset it between tests with `TunnelManager.instance = undefined`, and call `jest.clearAllMocks()` in `beforeEach`.
+
+**End-to-end tests** live in `test/e2e/`. They run against a packaged `pkg` binary, spawn real Pinggy free-tier tunnels, and assert HTTP/TCP/UDP behavior over the live edge. See `test/e2e/README.md` for layout, framework helpers, and how to add a case. CI runs them across 6 platform binaries via `.github/workflows/e2e-test.yml`.
+
+## Key Patterns
+
+- **Singletons** inside the daemon: `TunnelManager`, Winston `logger`, `CLIPrinter`. Access via `getInstance()` or static methods.
+- **Listener/observer maps** for SDK callbacks: `Map<tunnelId, Map<listenerId, fn>>`. Register/unregister by `listenerId` to avoid leaks.
+- **Zod validation** on remote-management payloads (`src/remote_management/remote_schema.ts`), V1 and V2.
+- **Worker threads** for file serving (`src/workers/file_serve_worker.ts`).
+- **DaemonTunnelHandler**. Remote management lives in the CLI, but every tunnel operation it receives is forwarded to the daemon via this adapter in `src/daemon/tunnelClient.ts`. Same code path as user-typed subcommands.
+
+## English Style
+
+- **No em-dashes.** Use a period, colon, or restructure the sentence. No obvious characters or constructions used by LLMs and AI.
+- **Short phrases.** Enough to convey technical meaning. Nothing more.
+- **No filler words.** Cut: "in order to", "it is important to note", "please note that", "essentially", "basically", "simply".
+- **No passive voice** unless the subject is unknown or irrelevant.
+- **No nominalizations.** Prefer "detect" over "perform detection"; "configure" over "apply configuration".
+- **One idea per sentence.** Split compound sentences.
+- **No throat-clearing openers.** Never start with "This document describes...", "The purpose of this is...", "As mentioned above...".
+- **Prefer concrete over abstract.** Name the thing: `navigator.webdriver`, not "the relevant browser property".
+- **Present tense.** "The system routes requests." Not "The system will route requests."
+- **No redundant qualifiers.** "Persistent storage" not "persistent, durable, long-lived storage".
+- **Numbers.** Use digits for all quantities: "3 retries", "50 sessions", "300ms".
+
+## Code Style
+- **No dead code.** Remove unused imports, functions, and variables immediately. `ruff` enforces this.
+- **Small functions.** If a function needs a comment to explain its sections, split it.

package/README.md

@@ -1,6 +1,6 @@
-# Pinggy CLI 
+# Pinggy CLI
 
-Create secure, shareable tunnels to your localhost and manage them from the command line. 
+Create secure, shareable tunnels to your localhost and manage them from the command line.
 
 
 ## Key features
@@ -8,8 +8,12 @@ Create secure, shareable tunnels to your localhost and manage them from the comm
 - SSH-style and user-friendly flags
 - Web debugger for HTTP tunnels
 - Extended options for auth, header manipulation, IP allowlists, CORS handling, etc.
+- Persistent background daemon owns every tunnel; CLI invocations are short-lived
+- Foreground (live TUI) and detached (`-b`) tunnel modes
+- Lifecycle commands: `ps`, `start`, `stop`, `restart`, `attach`
+- Per-tunnel and per-daemon log files with `pinggy logs` (tail, follow, rotation-safe)
+- System-service install for auto-start at boot (systemd, launchd, Task Scheduler)
 - Remote management via secure WebSocket connection (works with Pinggy Dashboard)
-- Configurable logging to file and/or stdout
 - Save and load configuration files
 - Config store for saving, listing, updating, and starting named tunnel configs
 - Auto-start support for launching saved tunnels automatically
@@ -17,6 +21,11 @@ Create secure, shareable tunnels to your localhost and manage them from the comm
 - Built-in TUI (Text User Interface) for viewing tunnel statistics, requests, and responses in real time
 
 
+## Architecture at a glance
+The CLI runs as two processes. A short-lived foreground process is what you invoke. A long-running daemon owns every tunnel and the `@pinggy/pinggy` SDK. They talk over HTTP and WebSocket on `127.0.0.1`.
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full breakdown of the two-process model, IPC routes, daemon discovery, session ownership, and filesystem layout.
+
 ## Requirements
 - Node.js 18+ (recommended). The CLI uses modern ESM and WebSocket features.
 - A network connection that allows outgoing WebSocket/HTTPS traffic.
@@ -38,7 +47,7 @@ After install, verify:
 
 ## Quick start
 - Start a basic HTTP tunnel to localhost:3000:
- 
+
  ```bash
   pinggy -R0:localhost:3000
  ```
@@ -57,7 +66,164 @@ pinggy -R0:localhost:8000 -L4300:localhost:4300
 - Use a token and region/domain-like arg:
   pinggy mytoken@a.example.com -p 3000. For more info read [docs](https://pinggy.io/docs/)
 
-The CLI prints generated public URLs (HTTP/HTTPS or TCP) and keeps running until you press Ctrl+C.
+The CLI prints generated public URLs (HTTP/HTTPS or TCP) and keeps the TUI attached until you press Ctrl+C. Tunnels run inside a background daemon. See [Daemon](#daemon) and [Running tunnels](#running-tunnels) for `ps`, `stop`, and detached (`-b`) mode.
+
+## Config management
+
+The CLI includes a built-in config store for saving, listing, and starting tunnel configurations. Configs are persisted as JSON files under the platform config directory (see [State and file locations](#state-and-file-locations)).
+
+Configs can be looked up by name (exact match) or by configId prefix (partial match) in every `config` and `start`/`stop`/`restart`/`attach` subcommand.
+
+### Save a tunnel config
+```bash
+pinggy config save my-tunnel -l 3000 token@pro.pinggy.io
+```
+
+### Save with auto-start enabled
+```bash
+pinggy config save my-tunnel --auto -l 3000
+```
+
+### List all saved configs
+```bash
+pinggy config list
+pinggy config ls          # alias for list
+```
+
+### View details of a saved config
+```bash
+pinggy config show my-tunnel
+pinggy config show my-tunnel other-tunnel    # View multiple configs
+pinggy config my-tunnel                      # Shorthand: same as `config show`
+```
+
+### Update a saved config
+```bash
+pinggy config update my-tunnel -l 4000
+```
+
+### Enable or disable auto-start
+```bash
+pinggy config auto my-tunnel
+pinggy config noauto my-tunnel
+pinggy config auto tunnel1 tunnel2           # Multiple configs at once
+```
+
+### Delete a saved config
+```bash
+pinggy config delete my-tunnel
+pinggy config delete tunnel1 tunnel2         # Delete multiple
+```
+
+
+## Running tunnels
+
+Every tunnel runs inside the daemon. The CLI either holds a live TUI subscription to it (foreground) or starts it and exits (detached).
+
+### Foreground vs detached
+
+- **Foreground** (default): `pinggy start <name>`. The CLI keeps a WebSocket open to the tunnel and renders the TUI. Use ctrl+C to close the TUI and stop the tunnel.
+- **Detached** (`-b`): `pinggy start -b <name>`. The CLI prints the public URL, then exits. The tunnel persists in the daemon until you stop it explicitly with `pinggy stop`.
+
+### Start a saved tunnel
+```bash
+pinggy start my-tunnel              # foreground, TUI attached
+pinggy start -b my-tunnel           # detached, CLI exits immediately
+```
+
+### Start with runtime overrides
+```bash
+pinggy start my-tunnel -l 4000
+```
+
+### Start multiple tunnels
+```bash
+pinggy start tunnel1 tunnel2
+```
+
+> Runtime overrides (`-l`, `--type`, `--token`, ...) only apply when starting a single tunnel. For multiple tunnels, update the saved config first with `pinggy config update`.
+
+### Start all auto-start tunnels
+```bash
+pinggy start --all
+```
+Runs through the daemon as detached tunnels. Useful for scripting and service startup.
+
+### Start with remote management
+```bash
+pinggy start --all --remote-management <API_KEY>
+pinggy start tunnel1 tunnel2 --remote-management <API_KEY>
+```
+
+### Start with logging enabled
+```bash
+pinggy start my-tunnel --vvv
+pinggy start --all --logfile /tmp/pinggy.log --loglevel DEBUG
+```
+
+### List running tunnels
+```bash
+pinggy ps
+```
+Prints a table of ID, name, status, local endpoint, and public URL.
+
+### Stop tunnels
+```bash
+pinggy stop my-tunnel
+pinggy stop my-tunnel other-tunnel       # multiple
+pinggy stop abc12345                     # by configId prefix
+```
+
+### Restart a tunnel
+```bash
+pinggy restart my-tunnel
+```
+Preserves the existing mode (foreground stays foreground, detached stays detached).
+
+### Re-attach the TUI to a running tunnel
+```bash
+pinggy attach my-tunnel
+```
+Opens a fresh TUI session against a tunnel that is already running. Useful to inspect a detached tunnel live.
+
+
+## Daemon
+
+The daemon is the long-running process that owns every tunnel. The CLI starts it automatically when needed, so most users never call these commands directly. They exist for explicit control, scripting, and boot-time service install.
+
+Both `pinggy daemon` and the alias `pinggy d` work.
+
+### Start the daemon
+```bash
+pinggy daemon start
+```
+Lists which configs will auto-start (any tagged with `config auto`).
+
+### Stop the daemon
+```bash
+pinggy daemon stop
+```
+Stops every running tunnel and shuts the daemon down cleanly.
+
+### Show daemon status
+```bash
+pinggy daemon status
+```
+Prints PID, port, start time, and uptime.
+
+
+## Remote management
+You can control tunnels remotely using a secure WebSocket connection.
+
+- Start remote management with a token:
+```bash
+ pinggy --remote-management <API KEY>
+```
+
+- Specify a management server (default is wss://dashboard.pinggy.io):
+```bash
+ pinggy --remote-management <API KEY> --manage wss://custom.example.com
+```
 
 
 ## Usage
@@ -99,6 +265,8 @@ The CLI supports both SSH-style flags and more descriptive long flags. Below is
 | `--vv` | Detailed logs (Node.js SDK + Libpinggy) |
 | `--vvv` | Enable logs from CLI, SDK, and Libpinggy |
 
+These flags apply to the CLI invocation. For daemon-wide log level and per-tunnel log files, see [Logging](#logging).
+
 ---
 
 ### **Config (File-based)**
@@ -132,6 +300,15 @@ The CLI supports both SSH-style flags and more descriptive long flags. Below is
 
 ---
 
+### **Tunnel lifecycle**
+| Flag | Description |
+|------|-------------|
+| `-b` | Start the tunnel detached (daemon keeps it alive after the CLI exits). Pairs with `pinggy start`. |
+| `--all` | Start every config marked auto-start. Pairs with `pinggy start`. |
+| `--auto` | Mark a saved config as auto-start. Pairs with `pinggy config save`. |
+
+---
+
 ### **Misc**
 | Flag | Description |
 |------|-------------|
@@ -164,35 +341,9 @@ Examples:
 To generate advanced CLI arguments, use [Configure from Pinggy.io](https://pinggy.io/)
 
 
-## Remote management
-You can control tunnels remotely using a secure WebSocket connection.
-
-- Start remote management with a token:
-```bash
- pinggy --remote-management <API KEY>
-```
-
-- Specify a management server (default is wss://dashboard.pinggy.io):
-```bash
- pinggy --remote-management <API KEY> --manage wss://custom.example.com
-```
-
-
-
-## Logging
-You can control logs via CLI flags (which override environment variables). If logfile is provided, the log directory will be created if it does not exist.
-
-- To log to file and stdout at INFO level:
-```bash
-  pinggy -p 3000 --logfile ~/.pinggy/pinggy.log --loglevel INFO --v
-```
-If you provide `--v`, `--vv`, or `--vvv` without specifying a log level, the default log level is INFO.
-
-
-
 ## Saving and loading configuration
 - Save current options to a file:
-```bash  
+```bash
   pinggy -p 443 -L4300:localhost:4300 -t -R0:127.0.0.1:8000 qr+force@free.pinggy.io   x:noreverseproxy x:passpreflight x:xff --saveconf myconfig.json
 ```
 - Use a config as base and override with flags:
@@ -201,93 +352,59 @@ pinggy --conf ./myconfig.json -p 8080
 ```
 
 
-## Config management
-
-The CLI includes a built-in config store for saving, listing, and starting tunnel configurations. Configs are persisted as JSON files in your platform's config directory (`~/.config/pinggy/tunnels/` on Linux/macOS, `%APPDATA%/pinggy/tunnels/` on Windows).
-
-### Save a tunnel config
-```bash
-pinggy config save my-tunnel -l 3000 token@pro.pinggy.io
-```
-
-### Save with auto-start enabled
-```bash
-pinggy config save my-tunnel --auto -l 3000
-```
-
-### List all saved configs
-```bash
-pinggy config list
-```
+## Logging
 
-### View details of a saved config
-```bash
-pinggy config show my-tunnel
-pinggy config show my-tunnel other-tunnel    # View multiple configs
-```
+The CLI has two layers of logging: per-invocation flags that affect what the current command prints, and daemon-wide log commands that read the persistent log files the daemon writes.
 
-### Update a saved config
-```bash
-pinggy config update my-tunnel -l 4000
-```
+### Per-invocation flags
+Pass these on any command that starts or interacts with a tunnel.
 
-### Enable or disable auto-start
 ```bash
-pinggy config auto my-tunnel
-pinggy config noauto my-tunnel
-pinggy config auto tunnel1 tunnel2           # Multiple configs at once
+pinggy -p 3000 --logfile ~/.pinggy/pinggy.log --loglevel INFO --v
 ```
+If you pass `--v`, `--vv`, or `--vvv` without a log level, the default is INFO. If a logfile path is provided, the log directory is created if it does not exist.
 
-### Delete a saved config
-```bash
-pinggy config delete my-tunnel
-pinggy config delete tunnel1 tunnel2         # Delete multiple
-```
+### Daemon and per-tunnel log files
+The daemon writes its own log file and a separate log per tunnel under the platform log directory (see [State and file locations](#state-and-file-locations)).
 
-### Shorthand: view config details
+#### Tail the daemon log
 ```bash
-pinggy config my-tunnel                      # Same as: pinggy config show my-tunnel
+pinggy logs              # last 100 lines of the daemon log
+pinggy logs -f           # follow new daemon log lines
 ```
 
-Configs can be looked up by name (exact match) or by configId prefix (partial match).
-
-
-## Starting saved tunnels
-
-### Start a saved tunnel
+#### Tail a tunnel log
 ```bash
-pinggy start my-tunnel
+pinggy logs my-tunnel    # last 100 lines of that tunnel's log
+pinggy logs my-tunnel -f # follow new lines (survives log rotation)
 ```
 
-### Start with runtime overrides
+#### Print the log file path
 ```bash
-pinggy start my-tunnel -l 4000
+pinggy log path                # daemon log path
+pinggy log path my-tunnel      # path to a specific tunnel's log
 ```
 
-### Start multiple tunnels
+#### Get or set the daemon log level
 ```bash
-pinggy start tunnel1 tunnel2
+pinggy log level                       # print current level
+pinggy log level debug                 # set to debug, info, or error
 ```
+Setting the level persists in `daemon-config.json` and applies to the daemon and any new tunnels. To pick up the new level on a tunnel that is already running, restart it with `pinggy restart <name>`.
 
-### Start all auto-start tunnels
-```bash
-pinggy start --all
-```
 
-### Start with remote management
-```bash
-pinggy start --all --remote-management <API_KEY>
-pinggy start tunnel1 tunnel2 --remote-management <API_KEY>
-```
+## State and file locations
 
-### Start with logging enabled
-```bash
-pinggy start my-tunnel --vvv
-pinggy start --all --logfile /tmp/pinggy.log --loglevel DEBUG
-```
+Config dir varies by OS:
+- Linux/macOS: `~/.config/pinggy/`
+- Windows: `%APPDATA%\pinggy\`
 
-> **Note:** Runtime overrides (`-l`, `--type`, `--token`, etc.) can only be used when starting a single tunnel. For multiple tunnels, update the saved config first with `pinggy config update`.
+Log dir varies by OS:
+- Linux: `~/.local/state/pinggy-cli/logs/` (honors `$XDG_STATE_HOME`)
+- macOS: `~/Library/Logs/Pinggy-CLI/`
+- Windows: `%LOCALAPPDATA%\Pinggy-CLI\Logs\`
 
+Use `pinggy log path` to print the exact resolved paths on your system.
 
 ## File server mode
 Serve a local directory quickly over a tunnel:
@@ -296,8 +413,10 @@ Optionally combine with other flags (auth, IP whitelist) as needed.
 
 
 ## Signals and shutdown
-Press Ctrl+C to stop. The CLI traps SIGINT and gracefully stops active tunnels before exiting.
 
+- **Foreground tunnel**: Ctrl+C closes the TUI. The daemon arms a 5-second grace timer and stops the tunnel if no other CLI re-attaches.
+- **Detached tunnel** (`-b`): the CLI already exited. Stop it with `pinggy stop <name|id>`.
+- **Everything at once**: `pinggy daemon stop` stops every tunnel and shuts the daemon down cleanly. `daemon-state.json` is cleared, so nothing replays on next start.
 
 
 ## Versioning

package/dist/TunnelManager-OPUMAZFX.js

@@ -0,0 +1,11 @@
+import {
+  TunnelAlreadyRunningError,
+  TunnelManager
+} from "./chunk-DLNUDW6G.js";
+import "./chunk-UB26QJ4T.js";
+import "./chunk-7G6SJEEA.js";
+import "./chunk-GBYF2H4H.js";
+export {
+  TunnelAlreadyRunningError,
+  TunnelManager
+};