mk-https 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,256 @@
+# mk-https
+
+Zero to `https://myapp.local` in one command. Wraps [mkcert](https://github.com/FiloSottile/mkcert) to generate trusted local certificates, manage `/etc/hosts` entries, and print framework config snippets for Next.js, Vite, Express, and Angular.
+
+---
+
+## Requirements
+
+- **Node.js** 20 LTS or later
+- **mkcert** (installed automatically if missing via `brew`, `snap`, `apt-get`, `choco`, or `scoop`)
+- macOS, Linux, or Windows
+
+---
+
+## Installation
+
+```bash
+npm install -g mk-https
+# or
+npx mk-https init
+```
+
+---
+
+## Commands
+
+### `mk-https init`
+
+Set up HTTPS for the current project from scratch.
+
+- Prompts for domain(s) if no config file exists yet (or pass `--domain` to skip the prompt)
+- Auto-detects your framework (Next.js, Vite, Angular, Express) from config files and `package.json`
+- Installs `mkcert` if it is not already present
+- Installs the local CA if not yet trusted
+- Generates `cert.pem` and `key.pem` into `.mk-https/`
+- Adds entries to `/etc/hosts` (requires elevated privileges — will prompt for `sudo`)
+- Appends `.mk-https/` to `.gitignore`
+- Writes `.mk-https/mk-https.json`
+- Prints a config snippet for your framework
+
+```bash
+mk-https init
+
+# Non-interactive (for CI/scripts):
+mk-https init --domain myapp.local --domain api.myapp.local
+```
+
+### `mk-https add <domain>`
+
+Add an additional domain to the existing HTTPS setup.
+
+- Validates the domain format (must end in `.local`, `.test`, `.localhost`, or `.internal`)
+- Regenerates the certificate to cover all domains
+- Adds the new entry to `/etc/hosts`
+- Updates `mk-https.json`
+
+```bash
+mk-https add api.myapp.local
+```
+
+### `mk-https remove <domain>`
+
+Remove a domain from the HTTPS setup.
+
+- Regenerates the certificate without the removed domain
+- Removes the entry from `/etc/hosts`
+- Updates `mk-https.json`
+
+```bash
+mk-https remove api.myapp.local
+```
+
+### `mk-https status`
+
+Show the current state of the HTTPS setup for this project.
+
+- Lists configured domains
+- Reports certificate expiry date (warns if expiring within 30 days)
+- Checks local CA trust
+- Checks `/etc/hosts` entries
+
+```bash
+mk-https status
+```
+
+### `mk-https renew`
+
+Regenerate the certificate for existing domains without touching `/etc/hosts`.
+
+```bash
+mk-https renew
+```
+
+### `mk-https clean`
+
+Remove all mk-https configuration for this project.
+
+- Strips the marker block from `/etc/hosts`
+- Deletes the `.mk-https/` directory (certs and config)
+- Strips the marker block from `.gitignore`
+- Does **not** remove `mkcert` or the local CA — those are system-level
+
+```bash
+mk-https clean
+```
+
+### `mk-https doctor`
+
+Run a full environment health check and print a pass/fail summary for each item:
+
+```
+  ✔ mkcert installed
+  ✔ Local CA trusted (OS cert store)
+  ✘ Firefox trust (NSS certutil present) — install libnss3-tools for Firefox support
+  ✔ Cert file exists
+  ✔ Key file exists
+  ✔ Cert covers all configured domains
+  ✔ Cert validity — expires Thu Jan 01 2026 (365 days)
+  ✔ /etc/hosts entries present
+  ✔ mk-https.json schema version current
+```
+
+```bash
+mk-https doctor
+```
+
+---
+
+## Framework setup
+
+`mk-https init` detects your framework and prints the config snippet you need. You can also run `mk-https doctor` any time to check the full environment.
+
+### Next.js (≥ 13.1)
+
+```ts
+// next.config.ts
+const nextConfig = {
+  experimental: {
+    https: {
+      key: '.mk-https/key.pem',
+      cert: '.mk-https/cert.pem',
+    },
+  },
+};
+
+export default nextConfig;
+```
+
+> **Next.js 14+ App Router note:** Local HTTPS dev works with `experimental.https`, but some middleware and edge features may behave differently over HTTPS in development.
+
+### Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import fs from 'fs';
+
+export default defineConfig({
+  server: {
+    https: {
+      key: fs.readFileSync('.mk-https/key.pem'),
+      cert: fs.readFileSync('.mk-https/cert.pem'),
+    },
+  },
+});
+```
+
+### Express
+
+```js
+import https from 'https';
+import { readFileSync } from 'fs';
+import app from './app.js';
+
+const server = https.createServer(
+  {
+    key: readFileSync('.mk-https/key.pem'),
+    cert: readFileSync('.mk-https/cert.pem'),
+  },
+  app,
+);
+
+server.listen(443);
+```
+
+### Angular
+
+```json
+// angular.json — projects.<name>.architect.serve.options
+{
+  "ssl": true,
+  "sslKey": ".mk-https/key.pem",
+  "sslCert": ".mk-https/cert.pem"
+}
+```
+
+Or via CLI:
+
+```bash
+ng serve --ssl --ssl-key .mk-https/key.pem --ssl-cert .mk-https/cert.pem
+```
+
+---
+
+## How it works
+
+1. **mkcert** creates a local Certificate Authority (CA) and installs it into the OS cert store (and Chrome/Edge on macOS/Windows).
+2. mk-https uses that CA to issue a certificate for your local domain(s) (`.local`, `.test`, `.localhost`, or `.internal`).
+3. Entries are added to `/etc/hosts` so the domain resolves to `127.0.0.1` and `::1` (IPv6).
+4. Your browser trusts the cert because it trusts the local CA.
+
+### Firefox
+
+Firefox uses its own NSS cert store. `mkcert -install` covers this automatically **if** `certutil` is present. Install it with:
+
+- **Linux:** `sudo apt-get install libnss3-tools`
+- **macOS:** `brew install nss`
+
+Run `mk-https doctor` to check if `certutil` is available.
+
+### Elevation / sudo
+
+Writing to `/etc/hosts` requires administrator privileges. When needed, mk-https re-invokes itself with `sudo` (macOS/Linux) or via a UAC-elevated PowerShell process (Windows). You will see a password prompt the first time. On Linux/macOS you can also pre-authorize with `sudo -v`.
+
+---
+
+## Project config (`.mk-https/mk-https.json`)
+
+```json
+{
+  "version": "1.0.0",
+  "domains": ["myapp.local", "api.myapp.local"],
+  "certPath": ".mk-https/cert.pem",
+  "keyPath": ".mk-https/key.pem",
+  "framework": "nextjs",
+  "createdAt": "2024-01-01T00:00:00.000Z",
+  "updatedAt": "2024-01-01T00:00:00.000Z"
+}
+```
+
+The `.mk-https/` directory is automatically added to `.gitignore` — never commit your local certs.
+
+---
+
+## Notes
+
+- mk-https never runs side effects during `npm install` (no `postinstall` scripts).
+- All paths are resolved relative to the current working directory (`process.cwd()`).
+- Framework config files are **not** modified — only a snippet is printed for you to copy.
+- `mk-https clean` removes project-level HTTPS config but does **not** uninstall `mkcert` or the local CA.
+
+---
+
+## License
+
+MIT