@hamedb89/localghost 0.1.13 → 0.2.0

package/docs/flows.md

@@ -120,7 +120,9 @@ The plugin defaults to HTTP. Pass `https: true` only when Vite is expected to si
 
 If `.localghost` is missing, an interactive development run asks whether to create it, asks for the primary `.localhost` domain, allows extra domains, explains the `/etc/hosts` password prompt, and runs setup when confirmed. Non-interactive runs fail with the exact setup command instead of guessing.
 
-## Ghost Tunnel
+## Ghost Tunnel (Experimental)
+
+Ghost Tunnel is an experimental opt-in feature. Its configuration, transports, CLI behavior, and public APIs may change between releases and should not be used for production-critical access.
 
 As a production app, I want one opt-in flag that makes `<route>-<project>-<owner>.ghost.<domain>` a known product entrypoint on top of the deployed Vite app, without running local Caddy or requiring the local `.localghost` file.
 

package/docs/ghost-tunnel.md

@@ -1,4 +1,7 @@
-# Ghost Tunnel
+# Ghost Tunnel (Experimental)
+
+> [!WARNING]
+> Ghost Tunnel is experimental. Its configuration, transport protocol, CLI behavior, and public APIs may change between releases. Do not rely on it for production-critical access. Review authentication, exposed routes, Redis credentials, and network reachability before sharing a tunnel.
 
 Ghost Tunnel is the production-facing Localghost entrypoint for apps that want a stable wildcard route on top of their existing Vite product:
 

package/docs/localghost.1.md

@@ -9,21 +9,24 @@ localghost - friendly local hostnames for app repos
 ```sh
 localghost [--cwd path] [--dry-run]
 localghost init [--write-scripts] [--config file] [--host host] [--port port]
-localghost doctor
+localghost doctor [--cwd path] [--config file] [--config-pattern regex] [--json]
 localghost setup [--project name] [--config file] [--config-pattern regex] [--https|--ssl]
+localghost repair [--project name] [--config file] [--config-pattern regex] [--https|--ssl] [--trust] [--reallocate-port] [--prune-registry]
 localghost trust [--project name] [--config file] [--config-pattern regex] [--https|--ssl]
 localghost reset [--project name]
 localghost teardown [--project name] [--remove-caddyfile]
 localghost status [--ready] [--json]
 localghost ps [--json]
+localghost guide [--agent] [--json]
 localghost tunnel [--cwd path] [--config file] [--config-pattern regex] [--ghost-config file] [--target-host host]
+localghost release <patch|minor|major>
 localghost update [--json]
 localghost dev [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--trust]
 localghost run [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--trust] [--dynamic-port] -- command
 localghost print [--config file] [--config-pattern regex]
 ```
 
-With no subcommand, Localghost detects npm, pnpm, Yarn, or Bun from `packageManager` or a lockfile, prefers a non-recursive `dev:raw` script, falls back to `dev`, and runs the result through the normal Caddy lifecycle. `--dry-run` prints the detected command without checking or changing machine setup. Set `command: ["<package-manager>", "dev:web"]` in `localghost.config.mjs` when inference should be explicit.
+With no subcommand, Localghost detects npm, pnpm, Yarn, or Bun from `packageManager` or a lockfile, prefers a non-recursive `dev:raw` script, falls back to `dev`, and runs the result through the normal Caddy lifecycle. Supported runtime flags such as `--https`, `--clean-caddy`, `--auto-repair`, and `--dynamic-port` are forwarded to that lifecycle. `--dry-run` prints the detected command without checking or changing machine setup. Set `command: ["<package-manager>", "dev:web"]` in `localghost.config.mjs` when inference should be explicit.
 
 For multiple independently started applications, configure `services` in `localghost.config.mjs`. Each service declares a unique name and host plus its project-relative working directory, requested port, and optional command. Bare `localghost` starts one Caddy process and all service commands, passes service-specific `LOCALGHOST_PORT`, `VITE_PORT`, and `LOCALGHOST_SERVICE` variables, and stops the group when any process exits.
 
@@ -69,13 +72,13 @@ Options:
 
 ### doctor
 
-Checks machine prerequisites.
+Checks machine prerequisites, the configured project port, and Localghost registry state. Use `--json` for agent-readable output. The command reports occupied ports, stale leases, and duplicate allocations without changing state.
 
 ```sh
 localghost doctor
 ```
 
-Currently checks Caddy and prints `brew install caddy` when missing.
+It checks Caddy and prints `brew install caddy` when missing.
 
 ### setup
 
@@ -95,11 +98,12 @@ localghost trust
 
 ### repair
 
-Reconciles the managed hosts block, regenerates and validates the Caddyfile, and refreshes project setup state. Use `--https --trust` to also re-run Caddy's local certificate trust step.
+Reconciles the managed hosts block, regenerates and validates the Caddyfile, and refreshes project setup state. Use `--https --trust` to also re-run Caddy's local certificate trust step. `--reallocate-port` selects and remembers a stable available replacement for an occupied port without editing `.localghost`. `--prune-registry` removes expired or dead leases.
 
 ```sh
 localghost repair
 localghost repair --https --trust
+localghost repair --reallocate-port --prune-registry
 ```
 
 ### teardown
@@ -136,7 +140,20 @@ localghost ps
 localghost ps --json
 ```
 
-### tunnel
+### guide
+
+Prints the recommended repository integration and command workflow. Use `--agent` for the coding-agent-oriented guide and `--json` for machine-readable integration hints.
+
+```sh
+localghost guide --agent
+localghost guide --agent --json
+```
+
+Localghost stores remembered project and instance port assignments in `~/.localghost`. Only Localghost-managed processes are represented there; unrelated processes are still checked by the operating system when a port is selected.
+
+### tunnel (experimental)
+
+Ghost Tunnel is experimental. Its configuration, transport protocol, CLI behavior, and public APIs may change between releases; do not rely on it for production-critical access.
 
 Runs the local Ghost Tunnel agent for `ghostTunnel.transport: "tunnel"`. The command reads the Localghost project config, reads exact public hosts from `.ghosttunnel`, sends route heartbeats to the configured Redis REST store, polls for queued requests, and serves them from the matching local port.
 
@@ -154,6 +171,18 @@ Checks npm for a newer Localghost release. Pass `--json` for scripts and agents.
 localghost update
 ```
 
+### release
+
+Dispatches the repository's guarded GitHub Actions release pipeline from `main`. The command requires an installed and authenticated GitHub CLI.
+
+```sh
+localghost release patch
+localghost release minor
+localghost release major
+```
+
+The pipeline synchronizes version metadata, runs package and runtime verification, creates the version commit and tag, publishes npm with provenance, and creates generated GitHub release notes.
+
 ### routes
 
 Prints the local domain layer as `domain -> upstream` routes. HTTP is the default. Pass `--https` or `--ssl` if the browser-facing domain should be shown as HTTPS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamedb89/localghost",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "description": "Friendly local hostnames for app repos with .localghost, Caddy, /etc/hosts, and Vite.",
   "type": "module",
   "bin": {