@hamedb89/localghost 0.1.0

package/docs/github.md

@@ -0,0 +1,129 @@
+# GitHub Discoverability
+
+Use this copy for the GitHub repo About box, topics, and social cards. Keep it specific enough for search, but still human.
+
+## Repository Description
+
+Friendly local HTTPS hostnames for app repos. A tiny CLI for `.localghost` configs, `/etc/hosts` blocks, Caddy reverse proxies, and Vite `allowedHosts`.
+
+Shorter alternative:
+
+Friendly local HTTPS hostnames for app repos, powered by `.localghost`, Caddy, `/etc/hosts`, and Vite.
+
+## Topics
+
+Recommended GitHub topics:
+
+```txt
+localghost
+localhost
+local-development
+local-dev
+local-https
+https
+caddy
+vite
+vite-plugin
+nodejs
+cli
+developer-tools
+reverse-proxy
+hosts-file
+npm-package
+```
+
+If GitHub topic limits force trimming, keep these first:
+
+```txt
+localhost
+local-development
+local-https
+caddy
+vite
+vite-plugin
+nodejs
+cli
+developer-tools
+reverse-proxy
+```
+
+## Search Phrases To Own
+
+- local HTTPS hostnames for Vite
+- Caddy localhost reverse proxy
+- friendly localhost domains
+- manage /etc/hosts for local development
+- Vite allowedHosts local domains
+- project-local hostname config
+
+## GitHub CLI Setup
+
+After creating `hamedb89/localghost`, this sets the public repo metadata:
+
+```sh
+gh repo edit hamedb89/localghost \
+  --description "Friendly local HTTPS hostnames for app repos. A tiny CLI for .localghost configs, /etc/hosts blocks, Caddy reverse proxies, and Vite allowedHosts." \
+  --homepage "https://hamedb89.github.io/localghost/" \
+  --add-topic localhost \
+  --add-topic local-development \
+  --add-topic local-https \
+  --add-topic caddy \
+  --add-topic vite \
+  --add-topic vite-plugin \
+  --add-topic nodejs \
+  --add-topic cli \
+  --add-topic developer-tools \
+  --add-topic reverse-proxy
+```
+
+## README Opening Shape
+
+The first visible paragraph should say what it is, who it is for, and what tools it touches:
+
+```txt
+Localghost is a tiny Node.js CLI for local HTTPS domains in app repos. It gives each project one small contract for `.localhost` hostnames, Caddy reverse proxies, Vite `allowedHosts`, and the system hosts file.
+```
+
+That phrasing helps GitHub search and npm search without making the README feel like SEO sludge.
+
+## GitHub Pages
+
+The repo ships a static marketing page in `site/` and deploys it with `.github/workflows/pages.yml`.
+
+Local build:
+
+```sh
+npm run site:build
+```
+
+The build script writes `_site/`, copies `site/` into it, then copies the existing `assets/` folder into `_site/assets`. This keeps GitHub Pages support out of the npm package payload and avoids committing duplicate images.
+
+After the repo is created, enable GitHub Pages with GitHub Actions as the source. The site URL should be:
+
+```txt
+https://hamedb89.github.io/localghost/
+```
+
+Recommended repo homepage:
+
+```txt
+https://hamedb89.github.io/localghost/
+```
+
+## CI And Publishing
+
+`.github/workflows/ci.yml` runs on pull requests and pushes to `main`. It uses `npm ci`, then runs:
+
+```sh
+npm run release:check
+```
+
+That command typechecks, builds the package, builds the static site, and runs `npm pack --dry-run`.
+
+`.github/workflows/publish-npm.yml` publishes to npm from a published GitHub release or manual workflow dispatch. The workflow reruns `npm run release:check` before publishing and uses:
+
+```sh
+npm publish --access public --provenance
+```
+
+Configure npm trusted publishing for `hamedb89/localghost` before relying on the release workflow. Local manual publishes are guarded by the `prepublishOnly` package hook, which runs the same release check.

package/docs/localghost.1.md

@@ -0,0 +1,124 @@
+# localghost(1)
+
+## Name
+
+localghost - friendly local hostnames for app repos
+
+## Synopsis
+
+```sh
+localghost init [--write-scripts] [--config file] [--host host] [--port port]
+localghost doctor
+localghost setup [--project name] [--config file] [--config-pattern regex]
+localghost teardown [--project name] [--remove-caddyfile]
+localghost status [--json]
+localghost update [--json]
+localghost dev [--config file] [--config-pattern regex]
+localghost print [--config file] [--config-pattern regex]
+```
+
+## Description
+
+Localghost reads `.localghost`, writes a managed `/etc/hosts` block, records `ops/local/localghost-state.json`, generates `ops/local/Caddyfile`, and runs a Caddy local HTTPS proxy. It is intentionally small and explicit: no hidden installs, no full hosts-file rewrites, and no broad Vite `allowedHosts: true` shortcut.
+
+Localghost checks npm for newer releases after successful commands. The check is best-effort, cached for 24 hours, and can be disabled with `LOCALGHOST_NO_UPDATE_CHECK=1` or `--no-update-check`.
+
+## Commands
+
+### init
+
+Creates `.localghost` in the current project by default. Pass `--config <file>` to create a differently named config file.
+
+```sh
+localghost init --write-scripts
+```
+
+Options:
+
+- `--cwd <path>`: project directory.
+- `--host <host>`: primary hostname.
+- `--port <number>`: primary app port.
+- `--api-host <host>`: API hostname.
+- `--api-port <number>`: API port.
+- `--package-manager <npm|yarn|pnpm>`: package manager for suggested commands.
+- `--write-scripts`: add Localghost scripts to `package.json`.
+- `--force`: overwrite an existing config file.
+
+### doctor
+
+Checks machine prerequisites.
+
+```sh
+localghost doctor
+```
+
+Currently checks Caddy and prints `brew install caddy` when missing.
+
+### setup
+
+Updates the managed Localghost block in `/etc/hosts`, writes `ops/local/Caddyfile`, and validates it with Caddy. Pass `--config <file>` to look for a specific config file. Repeat `--config` to use the first existing file from an ordered list. Pass `--config-pattern <regex>` to search matching filenames in the project root.
+
+```sh
+localghost setup --project app
+```
+
+### teardown
+
+Removes the managed Localghost block from `/etc/hosts` for the selected project and records the action in `ops/local/localghost-state.json`. It leaves `ops/local/Caddyfile` in place unless `--remove-caddyfile` is passed.
+
+```sh
+localghost teardown --remove-caddyfile
+```
+
+### status
+
+Prints Localghost's project-local state file. Pass `--json` for scripts and agents.
+
+```sh
+localghost status --json
+```
+
+### update
+
+Checks npm for a newer Localghost release. Pass `--json` for scripts and agents.
+
+```sh
+localghost update
+```
+
+### routes
+
+Prints the local domain layer as `domain -> upstream` routes. Pass `--http` if the browser-facing domain should be shown as plain HTTP.
+
+```sh
+localghost routes
+```
+
+### dev
+
+Writes `ops/local/Caddyfile`, validates it, and runs Caddy. Supports `--config` and `--config-pattern`.
+
+```sh
+localghost dev
+```
+
+### print
+
+Prints parsed Localghost config entries as JSON. Supports `--config` and `--config-pattern`.
+
+```sh
+localghost print
+```
+
+## Files
+
+- `.localghost`: default project hostname config.
+- custom config files: pass `--config <file>` or `--config-pattern <regex>`.
+- `ops/local/Caddyfile`: generated local Caddy config.
+- `ops/local/localghost-state.json`: last setup or teardown action.
+- `/etc/hosts`: managed block only, bounded by `# localghost:start` and `# localghost:end`.
+
+## Exit Status
+
+- `0`: command completed successfully.
+- `1`: missing prerequisite, invalid config, or failed system command.

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@hamedb89/localghost",
+  "version": "0.1.0",
+  "description": "Friendly local HTTPS hostnames for app repos with .localghost, Caddy, /etc/hosts, and Vite.",
+  "type": "module",
+  "bin": {
+    "localghost": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    }
+  },
+  "files": [
+    "dist",
+    "assets",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "localghost",
+    "localhost",
+    "local-dev",
+    "local-development",
+    "local-https",
+    "https",
+    "caddy",
+    "vite",
+    "vite-plugin",
+    "hosts-file",
+    "reverse-proxy",
+    "developer-tools",
+    "cli"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsup src/index.ts src/vite.ts src/cli.ts --format esm --dts",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run release:check",
+    "pack:dry": "npm pack --dry-run",
+    "release:check": "npm run typecheck && npm run build && npm run site:build && npm pack --dry-run",
+    "site:build": "node scripts/build-site.mjs",
+    "publish:public": "npm publish --access public --provenance"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "execa": "^9.0.0"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vite": ">=5"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hamedb89/localghost.git"
+  },
+  "homepage": "https://hamedb89.github.io/localghost/",
+  "bugs": {
+    "url": "https://github.com/hamedb89/localghost/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "npm@10.9.8",
+  "overrides": {
+    "esbuild": "0.28.1"
+  }
+}