@hamedb89/localghost 0.1.6 → 0.1.9

package/README.md

@@ -9,9 +9,9 @@ Buh. Friendly local hostnames for app repos.
 [![CI](https://github.com/hamedb89/localghost/actions/workflows/ci.yml/badge.svg)](https://github.com/hamedb89/localghost/actions/workflows/ci.yml)
 [![GitHub Pages](https://github.com/hamedb89/localghost/actions/workflows/pages.yml/badge.svg)](https://github.com/hamedb89/localghost/actions/workflows/pages.yml)
 [![Publish npm](https://github.com/hamedb89/localghost/actions/workflows/publish-npm.yml/badge.svg)](https://github.com/hamedb89/localghost/actions/workflows/publish-npm.yml)
-[![npm version](https://img.shields.io/badge/npm-v0.1.6-CB3837?logo=npm)](https://www.npmjs.com/package/@hamedb89/localghost)
+[![npm version](https://img.shields.io/badge/npm-v0.1.9-CB3837?logo=npm)](https://www.npmjs.com/package/@hamedb89/localghost)
 
-Localghost is a tiny Node.js CLI for friendly local domains in app repos. It gives each project one small contract for `.localhost` hostnames, Caddy reverse proxies, Vite `allowedHosts`, and the system hosts file, so developers can open `http://app.localhost/` instead of remembering which localhost port belongs to which process.
+Localghost is a tiny Node.js CLI for friendly local domains in app repos. Add it as a dev dependency, run `yarn dev`, and use `http://app.localhost/` instead of remembering which localhost port belongs to which process.
 
 [Website](https://hamedb89.github.io/localghost/) · [npm](https://www.npmjs.com/package/@hamedb89/localghost) · [GitHub](https://github.com/hamedb89/localghost)
 
@@ -31,6 +31,7 @@ Localghost is a tiny Node.js CLI for friendly local domains in app repos. It giv
 
 - CI runs typecheck, build, site build, and npm package dry-run on Node 20 and 22.
 - GitHub Pages is deployed by Actions from the checked-in `site/` and `assets/` sources.
+- Preview the exact Pages artifact locally with `npm run site:serve`, then open `http://127.0.0.1:4173/`.
 - npm publish is guarded by `prepublishOnly` and the release workflow publishes with npm provenance.
 - Runtime dependencies are intentionally small: `commander` for the CLI and `execa` for process execution. Vite is an optional peer dependency for the Vite plugin.
 - No postinstall scripts, hidden Homebrew installs, or broad hosts-file rewrites.
@@ -40,21 +41,62 @@ Localghost is a tiny Node.js CLI for friendly local domains in app repos. It giv
   <img src="./assets/localghost-app-icon.png" alt="Localghost app icon" width="180">
 </p>
 
-## Install
+## Start Here
 
 ```sh
 yarn add -D @hamedb89/localghost
 ```
 
-## Quick Start
+That is the entrypoint you are optimizing for: install the dev dependency, keep using the dev command your team already knows, and let Localghost handle the local-domain setup around it.
 
-Create the project config and optional package scripts:
+For Vite apps, add the plugin once:
+
+```ts
+import { defineConfig } from "vite";
+import { localGhostPlugin } from "@hamedb89/localghost/vite";
+
+export default defineConfig({
+  plugins: [localGhostPlugin()]
+});
+```
+
+Now your daily command is just:
+
+```sh
+yarn dev
+```
+
+And you are ready.
+
+On the first interactive `yarn dev`, Localghost can create `.localghost`, explain the `/etc/hosts` change, write the local Caddyfile, and then print the browser-facing URL:
+
+```txt
+localghost
+local:  http://app.localhost/
+also:   http://www.app.localhost/
+target: http://127.0.0.1:5173/
+```
+
+If your project does not use Vite, or you want one command that starts Caddy and then your app process, wrap your raw dev script:
+
+```json
+{
+  "scripts": {
+    "dev": "localghost run -- yarn dev:raw",
+    "dev:raw": "next dev"
+  }
+}
+```
+
+Then the daily command stays the same:
 
 ```sh
-yarn localghost init --write-scripts
+yarn dev
 ```
 
-This creates `.localghost`:
+## Configuration
+
+Most apps only need a `.localghost` file when they want explicit hostnames or multiple services:
 
 ```txt
 # Buh. Friendly names for local services.
@@ -64,6 +106,12 @@ www.app.localhost 5173
 api.app.localhost 8787
 ```
 
+If `.localghost` is missing, the Vite plugin can prompt to create it during `yarn dev`. You can also create it directly:
+
+```sh
+yarn localghost init
+```
+
 Check the machine:
 
 ```sh
@@ -78,35 +126,41 @@ Run: brew install caddy
 Localghost will not install it for you. No surprise spells.
 ```
 
-First time on a machine:
+Prepare or repair the machine setup directly:
 
 ```sh
-yarn localghost:setup
+yarn localghost setup
 ```
 
 Check that the hosts block and Caddyfile are ready:
 
 ```sh
-yarn localghost:ready
+yarn localghost status --ready
 ```
 
-Daily proxy:
+Run only the proxy when your app server is started separately:
 
 ```sh
-yarn localghost:proxy
+yarn localghost dev
 ```
 
 Use HTTPS only when you explicitly want Caddy local certificates:
 
 ```sh
-yarn localghost:proxy:https
+yarn localghost dev --https
+```
+
+Trust Caddy's local HTTPS CA when you want browsers to stop showing local certificate warnings:
+
+```sh
+yarn localghost trust
 ```
 
 Reset generated setup without deleting `.localghost`:
 
 ```sh
-yarn localghost:reset
-yarn localghost:setup
+yarn localghost reset
+yarn localghost setup
 ```
 
 Prefer `.localhost` names. `.local` is supported, but Localghost warns because `.local` can collide with mDNS/Bonjour.
@@ -146,6 +200,7 @@ The Vite plugin accepts the same shape through `fileName`, `configFiles`, or `co
     "localghost:proxy:https": "localghost dev --https",
     "localghost:run": "localghost run --",
     "localghost:ready": "localghost status --ready",
+    "localghost:trust": "localghost trust",
     "localghost:ps": "localghost ps",
     "localghost:print": "localghost print",
     "localghost:routes": "localghost routes",
@@ -165,8 +220,7 @@ A full app might compose them with its own servers:
 ```json
 {
   "scripts": {
-    "dev": "localghost run -- vite",
-    "dev:dynamic": "localghost run --dynamic-port -- vite",
+    "dev": "localghost run -- yarn dev:raw",
     "dev:raw": "vite"
   }
 }
@@ -177,7 +231,7 @@ In Turborepo, let Localghost wrap the dev runner and keep dev uncached:
 ```json
 {
   "scripts": {
-    "dev": "localghost run --dynamic-port -- turbo dev",
+    "dev": "localghost run -- yarn dev:raw",
     "dev:raw": "turbo dev"
   }
 }
@@ -193,7 +247,117 @@ Then keep persistent dev tasks uncached:
 }
 ```
 
-`localghost run` resolves one shared Localghost context, starts Caddy, passes the selected port to the child command through `LOCALGHOST_PORT` and `VITE_PORT`, and stops Caddy when the child exits. With `--dynamic-port`, Localghost starts at the configured port, checks `127.0.0.1:<port>`, and walks upward until it finds a free port.
+`localghost run` resolves one shared Localghost context, starts Caddy, handles the optional HTTPS trust prompt, then starts the child command. That keeps Localghost setup/proxy output before Vite's ready log. It passes the selected port to the child command through `LOCALGHOST_PORT` and `VITE_PORT`, and stops Caddy when the child exits. Dynamic ports are on by default: Localghost starts at the configured port, checks `127.0.0.1:<port>`, and walks upward until it finds a free port. Use `--dynamic-port=no` when you want strict fixed-port behavior.
+
+Most repos do not need `localghost.config.mjs`. Localghost derives `project` from `package.json`, defaults to port `5173`, keeps HTTPS off by default, enables dynamic ports by default, and adds `www.` aliases by default. Add `localghost.config.mjs` only when you want to override those defaults:
+
+```js
+import { defineLocalghostConfig } from "@hamedb89/localghost";
+
+export default defineLocalghostConfig({
+  https: true
+});
+```
+
+Then the daily script can stay small:
+
+```json
+{
+  "scripts": {
+    "dev": "localghost run -- yarn dev:raw",
+    "dev:raw": "vite"
+  }
+}
+```
+
+`www.` aliases are enabled by default. A `.localghost` entry like `app.localhost 5173` also sets up `www.app.localhost` unless `wwwAlias: false` is set in `localghost.config.mjs`.
+
+`ghostTunnel` is the production opt-in for a wildcard product entrypoint on top of your deployed Vite app. The default namespace is `<route>-<project>-<owner>.ghost.<domain>`, and omitted domains are shown as `*` in logs:
+
+```js
+import { defineLocalghostConfig } from "@hamedb89/localghost";
+
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    domains: "socialworkouts.app",
+    mode: "manual"
+  }
+});
+```
+
+With `ghostTunnel: { domains }`, local route and Vite startup logs use local defaults for `route`, `project`, and `owner`, then fill the configured domain:
+
+```txt
+localghost ghost tunnel
+  mode: manual
+  expected: https://app-decision-layer-hamed.ghost.socialworkouts.app/
+```
+
+Without `domains`, the expected URL stays wildcarded:
+
+```txt
+localghost ghost tunnel
+  mode: manual
+  expected: https://app-decision-layer-hamed.ghost.*/
+```
+
+`ghostTunnel: "manual"` and `ghostTunnel: "public"` are shorthand modes. `manual` is the default; use `enabled: false` to keep domains/config in the file without exposing the tunnel surface.
+
+Use object form to override defaults or provide a concrete preview URL:
+
+```js
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    domains: "socialworkouts.app",
+    preview: {
+      route: "plan",
+      project: "summer-base",
+      owner: "hamed"
+    }
+  }
+});
+```
+
+Production apps can read that flag without requiring the local `.localghost` file, then construct and validate tunnel URLs:
+
+```ts
+import {
+  assertSecureGhostTunnelRequest,
+  constructGhostTunnelUrl,
+  readLocalghostProjectConfig
+} from "@hamedb89/localghost";
+
+const { config } = await readLocalghostProjectConfig();
+const url = constructGhostTunnelUrl({
+  domain: "socialworkouts.app",
+  route: "plan",
+  project: "summer-base",
+  owner: "hamed",
+  ghostTunnel: config.ghostTunnel
+});
+
+const route = assertSecureGhostTunnelRequest({
+  host: request.headers.get("host") ?? "",
+  domain: "socialworkouts.app",
+  protocol: "https",
+  authenticated: Boolean(session),
+  ghostTunnel: config.ghostTunnel
+});
+```
+
+That constructs `https://plan-summer-base-hamed.ghost.socialworkouts.app/`, validates the same host shape, requires HTTPS by default, and requires the app to confirm auth by default. See [Ghost Tunnel](./docs/ghost-tunnel.md) for the production DNS and routing flow.
+
+When `ghostTunnel.preview` is configured, local route and Vite startup logs include the concrete URL as `expected: https://plan-summer-base-hamed.ghost.socialworkouts.app/`. In an interactive Vite terminal, press `g` to show the Ghost Tunnel configuration and open a numbered concrete URL. Wildcard `*` URLs are shown for clarity, but the menu only opens configured concrete domains.
+
+Relay guardrails are private-by-default: public requests never choose the local target, route registration requires a matching local-agent bearer token, signed route claims are exact/scoped/expiring, and default targets are limited to `localhost`, `127.0.0.1`, and `::1` with dangerous ports blocked. The package exports relay helpers for registration, target validation, header stripping, log redaction, limits, and safe offline responses.
+
+Local security checks:
+
+```sh
+npm test
+npm run test:cli
+npm run test:coverage
+```
 
 `localghost dev` and `localghost run` also register their active sessions in a user-local activity file. Use `localghost ps` to see the Localghost apps currently running on the machine:
 
@@ -209,6 +373,19 @@ app  run: vite
 
 Pass `--json` when another helper, such as a menu bar app, needs to poll the same state.
 
+## macOS Widget
+
+Localghost includes a tiny native macOS widget in `apps/macos-widget`. One widget tracks all active Localghost sessions across the machine. It shows `LG n` in the top bar and opens a small floating desktop panel with the Localghost route list, target ports, and listening state.
+
+Build it from source:
+
+```sh
+npm run build
+npm run macos:widget:build
+```
+
+The app bundle is written to `dist/LocalghostWidget.app`. See [docs/macos-widget.md](./docs/macos-widget.md) for local development notes.
+
 ## Vite
 
 ```ts
@@ -219,14 +396,13 @@ export default defineConfig({
   plugins: [
     localGhostPlugin({
       port: 5173,
-      dynamicPort: true,
       configFiles: [".localghost.private", ".localghost"]
     })
   ]
 });
 ```
 
-The plugin binds Vite to `127.0.0.1` by default, prints the selected Localghost domain, generates an explicit `server.allowedHosts` list from the selected config file, and does not set `allowedHosts: true`. It runs only during local `vite serve`; production/build mode no-ops. When `dynamicPort` is enabled, the plugin uses the configured port when available and otherwise moves to the next free port before Vite starts.
+The plugin binds Vite to `127.0.0.1` by default, prints the selected Localghost domain, generates an explicit `server.allowedHosts` list from the selected config file, and does not set `allowedHosts: true`. It runs only during local `vite serve`; production/build mode no-ops. Dynamic ports are enabled by default, so the plugin uses the configured port when available and otherwise moves to the next free port before Vite starts. Set `dynamicPort: false` when strict fixed-port behavior matters.
 
 If `.localghost` is missing and Vite is running in an interactive terminal, the plugin asks whether to create one, prompts for the primary domain and optional extra domains, and then asks whether to run setup. Before touching `/etc/hosts`, it explains why macOS may ask for your password and confirms that only Localghost's managed block is changed.
 
@@ -253,6 +429,7 @@ localghost setup
 localghost setup --project app
 localghost setup --config .localghost.preview
 localghost setup --https
+localghost trust
 localghost status
 localghost status --ready
 localghost ps
@@ -263,7 +440,8 @@ localghost teardown --remove-caddyfile
 localghost update
 localghost --no-update-check doctor
 localghost run -- vite
-localghost run --dynamic-port -- turbo dev
+localghost run --trust -- vite
+localghost run --dynamic-port=no -- vite
 localghost dev --config-pattern '^\.localghost\.'
 localghost dev --https
 localghost print
@@ -273,6 +451,8 @@ Localghost checks npm for newer releases after successful commands. The check ha
 
 `setup`, `dev`, and `teardown` refuse to run in production-like environments such as `NODE_ENV=production`, `VERCEL_ENV=production`, or `LOCALGHOST_ENV=production`.
 
+When HTTPS is enabled, `localghost dev` and `localghost run` ask once whether to trust Caddy's local HTTPS CA. If you accept, macOS may ask for your password so Caddy can add its local CA to Keychain. Localghost records the result in `ops/local/localghost-state.json`; use `localghost trust` or `localghost run --trust -- ...` when you want to rerun the trust step intentionally.
+
 `setup` writes only a managed block in the system hosts file:
 
 ```txt

package/apps/macos-widget/LocalghostWidget.entitlements

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>com.apple.security.app-sandbox</key>
+  <true/>
+  <key>com.apple.security.application-groups</key>
+  <array>
+    <string>group.app.localghost</string>
+  </array>
+</dict>
+</plist>