caddy-subdomain 0.0.0-stage β†’ 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,15 @@
1
+ ISC License
2
+
3
+ Copyright (c) KeshavSoft
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted, provided that the above
7
+ copyright notice and this permission notice appear in all copies.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
10
+ REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11
+ AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
12
+ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13
+ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
14
+ OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15
+ PERFORMANCE OF THIS SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,298 @@
1
- # Temporary Holding Version
1
+ # caddy-subdomain
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/caddy-subdomain.svg?color=amber&style=flat-square)](https://www.npmjs.com/package/caddy-subdomain)
4
+ [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg?style=flat-square)](https://opensource.org/licenses/ISC)
5
+ [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-emerald.svg?style=flat-square)](https://keshavsoft.github.io/caddy-subdomain/)
6
+ [![GitHub](https://img.shields.io/badge/github-keshavsoft%2Fcaddy--subdomain-zinc.svg?style=flat-square&logo=github)](https://github.com/keshavsoft/caddy-subdomain)
7
+ [![Caddy Docs](https://img.shields.io/badge/official-caddyserver.com-00ADD8.svg?style=flat-square)](https://caddyserver.com/docs/)
8
+
9
+ > **The Single-Purpose Subdomain Engine for Caddy JSON.**
10
+ > Safely test DNS & automatic HTTPS with zero-dependency smoke probes, then promote to reverse proxies with automatic backups and zero downtime.
11
+
12
+ ---
13
+
14
+ ## πŸ“‘ Table of Contents
15
+
16
+ - [The Subdomain Lifecycle](#-the-subdomain-lifecycle)
17
+ - [Level 1: The Smoke Test Probe (Zero Dependencies)](#level-1-the-smoke-test-probe-zero-dependencies)
18
+ - [Level 2: Promote to Backend Reverse Proxy](#level-2-promote-to-backend-reverse-proxy)
19
+ - [Interactive Documentation Portal](#-interactive-documentation-portal)
20
+ - [Quick Start with `npx`](#-quick-start-with-npx)
21
+ - [CLI Command Reference](#-cli-command-reference)
22
+ - [`caddy-subdomain probe`](#1-caddy-subdomain-probe-domain)
23
+ - [`caddy-subdomain add`](#2-caddy-subdomain-add-domain-port)
24
+ - [`caddy-subdomain list`](#3-caddy-subdomain-list-configpath)
25
+ - [`caddy-subdomain check`](#4-caddy-subdomain-check-domain)
26
+ - [Programmatic ESM Library Reference](#-programmatic-esm-library-reference)
27
+ - [Safety & Auto-Backups](#-safety--auto-backups)
28
+ - [Troubleshooting & FAQ](#-troubleshooting--faq)
29
+
30
+ ---
31
+
32
+ ## 🧭 The Subdomain Lifecycle
33
+
34
+ When creating a new subdomain (e.g. on GoDaddy, Cloudflare, or Namecheap), trying to configure your Node.js application, ports, Caddy reverse proxy, and SSL certificate all at the same time is prone to frustrating connection errors.
35
+
36
+ `caddy-subdomain` introduces a **two-stage verification workflow**:
37
+
38
+ ```mermaid
39
+ flowchart TD
40
+ DNS["1. GoDaddy / DNS Provider<br>Add A Record: call βž” 103.174.102.116"]
41
+ DNS --> Probe["2. Level 1: Caddy Probe<br>npx caddy-subdomain probe call.keshavsoft.com"]
42
+ Probe --> Verify{"3. Visit https://call.keshavsoft.com"}
43
+ Verify -->|Green Padlock + 200 OK| Promoted["4. Level 2: Promote to Node.js<br>npx caddy-subdomain add call.keshavsoft.com 5000"]
44
+ Verify -->|Connection Error| FixDNS["Fix DNS propagation or Port 443 firewall<br>(Node app wasn't even touched!)"]
45
+ ```
46
+
47
+ ---
48
+
49
+ ### Level 1: The Smoke Test Probe (Zero Dependencies)
50
+ Before starting Node.js or allocating ports, verify that **DNS points to your server** and that **Caddy's Automatic HTTPS issued an SSL certificate**:
51
+
52
+ ```bash
53
+ npx caddy-subdomain probe call.keshavsoft.com
54
+ ```
55
+
56
+ **How it works under the hood:**
57
+ - **Zero Config Passing:** Automatically discovers `/etc/caddy/caddy.json` on your VPS or `./caddy.json` locally.
58
+ - **Automatic Reload:** Executes hot-reload automatically without needing flags.
59
+ - **Zero Port/Process Overhead:** Injects a native Caddy `static_response` handler (HTTP 200 OK).
60
+ - **Direct Terminal Feedback:**
61
+ ```text
62
+ Subdomain: call.keshavsoft.com
63
+ Present in Caddy: Yes (Probe Active)
64
+ Caddy Reload: Success
65
+ Live HTTPS: Yes (200 OK - Verified)
66
+ ```
67
+
68
+ ---
69
+
70
+ ### Level 2: Promote to Backend Reverse Proxy
71
+ Now that the domain and SSL certificate are proven live, promote the subdomain to your actual application:
72
+
73
+ ```bash
74
+ npx caddy-subdomain add call.keshavsoft.com 5000
75
+ ```
76
+
77
+ - Replaces the probe with a clean `reverse_proxy` pointing to `localhost:5000`.
78
+ - Automatically executes hot-reload in memory.
79
+ - Retains existing TLS certificatesβ€”zero re-negotiation downtime!
80
+
81
+ ---
82
+
83
+ ## 🌐 Interactive Documentation Portal
84
+
85
+ Explore live examples, visual flowcharts, and the interactive command builder:
86
+ πŸ‘‰ **[https://keshavsoft.github.io/caddy-subdomain/](https://keshavsoft.github.io/caddy-subdomain/)**
87
+ πŸ‘‰ Dedicated NPX Command Catalog: **[https://keshavsoft.github.io/caddy-subdomain/npx/](https://keshavsoft.github.io/caddy-subdomain/npx/)**
88
+
89
+ ---
90
+
91
+ ## πŸš€ Quick Start with `npx`
92
+
93
+ Zero installation and zero path configuration required:
94
+
95
+ ```bash
96
+ # 1. Probe a new domain (Level 1 Flight Check: auto-detects config & auto-reloads)
97
+ npx caddy-subdomain probe call.keshavsoft.com
98
+
99
+ # 2. Add or promote to a Node / Python / Go backend port
100
+ npx caddy-subdomain add call.keshavsoft.com 5000
101
+
102
+ # 3. Check if a domain already exists in Caddy (Instant Yes / No answer)
103
+ npx caddy-subdomain check call.keshavsoft.com
104
+
105
+ # 4. List all configured subdomains
106
+ npx caddy-subdomain list
107
+ ```
108
+
109
+ ---
110
+
111
+ ## βš™οΈ CLI Command Reference
112
+
113
+ ### Default Config Resolution
114
+ `caddy-subdomain` automatically checks in priority order:
115
+ 1. `/etc/caddy/caddy.json` (standard Linux/VPS path).
116
+ 2. `./caddy.json` in current directory.
117
+ 3. Sibling/parent configuration files.
118
+
119
+ ---
120
+
121
+ ### 1. `caddy-subdomain probe <domain>`
122
+ Injects a Level-1 test probe route, auto-reloads Caddy, and probes live HTTPS:
123
+
124
+ ```bash
125
+ npx caddy-subdomain probe call.keshavsoft.com
126
+ ```
127
+
128
+ **Terminal Output:**
129
+ ```text
130
+ Subdomain: call.keshavsoft.com
131
+ Present in Caddy: Yes (Probe Active)
132
+ Caddy Reload: Success
133
+ Live HTTPS: Yes (200 OK - Verified)
134
+ ```
135
+
136
+ ---
137
+
138
+ ### 2. `caddy-subdomain add <domain> <port>`
139
+ Appends or updates a reverse proxy route forwarding traffic to your backend target:
140
+
141
+ ```bash
142
+ npx caddy-subdomain add call.keshavsoft.com 5000
143
+ ```
144
+
145
+ **Terminal Output:**
146
+ ```text
147
+ Subdomain: call.keshavsoft.com
148
+ Target: localhost:5000
149
+ Caddy Reload: Success
150
+ Status: Active
151
+ ```
152
+
153
+ ---
154
+
155
+ ### 3. `caddy-subdomain check <domain>`
156
+ Direct presence check. Returns a clean binary **Yes** or **No**:
157
+
158
+ ```bash
159
+ npx caddy-subdomain check call.keshavsoft.com
160
+ ```
161
+
162
+ **Terminal Output:**
163
+ ```text
164
+ Subdomain: call.keshavsoft.com
165
+ Present in Caddy: Yes
166
+ ```
167
+
168
+ ---
169
+
170
+ ### 4. `caddy-subdomain list`
171
+ Prints an indexed list of every unique subdomain registered in Caddy:
172
+
173
+ ```bash
174
+ npx caddy-subdomain list
175
+ ```
176
+
177
+ **Terminal Output:**
178
+ ```text
179
+ Config: /etc/caddy/caddy.json
180
+ Subdomains (3):
181
+ 1. quotation.keshavsoft.com
182
+ 2. call.keshavsoft.com
183
+ 3. appointment.keshavsoft.com
184
+ ```
185
+
186
+ ---
187
+
188
+ ## πŸ“¦ Programmatic ESM Library Reference
189
+
190
+ Use `caddy-subdomain` directly in your Node.js scripts and microservices:
191
+
192
+ ```javascript
193
+ import {
194
+ readCaddyConfig,
195
+ writeCaddyConfig,
196
+ listSubdomains,
197
+ hasSubdomain,
198
+ buildProbeRoute,
199
+ addProbeSubdomainToFile,
200
+ buildProxyRoute,
201
+ addSubdomainToFile
202
+ } from "caddy-subdomain";
203
+ ```
204
+
205
+ ### Methods
206
+
207
+ #### `readCaddyConfig(filePath)`
208
+ Safely loads and parses Caddy JSON.
209
+ ```javascript
210
+ const config = readCaddyConfig("./caddy.json");
211
+ ```
212
+
213
+ #### `listSubdomains(config)`
214
+ Returns an array of unique domain strings: `string[]`.
215
+ ```javascript
216
+ const domains = listSubdomains(config);
217
+ // ['api.keshavsoft.com', 'call.keshavsoft.com']
218
+ ```
219
+
220
+ #### `hasSubdomain(config, domain)`
221
+ Returns boolean `true` if domain exists (case-insensitive).
222
+ ```javascript
223
+ if (hasSubdomain(config, "call.keshavsoft.com")) {
224
+ console.log("Domain taken!");
225
+ }
226
+ ```
227
+
228
+ #### `addProbeSubdomainToFile(filePath, options)`
229
+ Adds Level-1 probe route to file with backup.
230
+ ```javascript
231
+ const result = addProbeSubdomainToFile("/etc/caddy/caddy.json", {
232
+ domain: "call.keshavsoft.com",
233
+ backup: true
234
+ });
235
+ console.log(result.backupFile); // /etc/caddy/caddy.json.bak.1795123000
236
+ ```
237
+
238
+ #### `addSubdomainToFile(filePath, options)`
239
+ Adds Level-2 reverse proxy route to file with backup.
240
+ ```javascript
241
+ const result = addSubdomainToFile("/etc/caddy/caddy.json", {
242
+ domain: "call.keshavsoft.com",
243
+ port: 5000,
244
+ force: true, // Replaces the Level-1 probe
245
+ backup: true
246
+ });
247
+ ```
248
+
249
+ ---
250
+
251
+ ## πŸ›‘οΈ Safety & Auto-Backups
252
+
253
+ Whenever a write operation occurs (`add` or `probe`), `caddy-subdomain` writes a timestamped snapshot before touching the live file:
254
+
255
+ ```text
256
+ /etc/caddy/
257
+ β”œβ”€β”€ caddy.json # Active live config
258
+ β”œβ”€β”€ caddy.json.bak.1795132001 # Backup created before probe
259
+ └── caddy.json.bak.1795132500 # Backup created before promote
260
+ ```
261
+
262
+ If an issue ever occurs, restoring is as simple as:
263
+ ```bash
264
+ cp /etc/caddy/caddy.json.bak.<timestamp> /etc/caddy/caddy.json
265
+ caddy reload --config /etc/caddy/caddy.json
266
+ ```
267
+
268
+ ---
269
+
270
+ ## ❓ Troubleshooting & FAQ
271
+
272
+ ### 1. Probe route returns connection refused in browser
273
+ - **Cause**: DNS hasn't propagated yet or VPS firewall is blocking port 80 / 443.
274
+ - **Verification**: Run `nslookup call.keshavsoft.com` on your local PC. Ensure the IP matches your VPS. Ensure ports 80 and 443 are open (`ufw allow 80 && ufw allow 443`).
275
+
276
+ ### 2. Can Caddy issue SSL certificates for private IP addresses?
277
+ - **Answer**: No, Let's Encrypt and ZeroSSL require a public DNS A/AAAA record pointing to a public IP address (such as your GoDaddy DNS record).
278
+
279
+ ### 3. How do I switch a probe to my Node.js application?
280
+ - Run `add` with `--force`:
281
+ ```bash
282
+ npx caddy-subdomain add <domain> <port> --force --reload
283
+ ```
284
+ `--force` seamlessly replaces the static probe route with the reverse proxy.
285
+
286
+ ---
287
+
288
+ ## πŸ”— The KeshavSoft Caddy Suite
289
+
290
+ - **[caddy-subdomain](https://github.com/keshavsoft/caddy-subdomain)**: Subdomain management, smoke probes, and collision detection.
291
+ - **[caddy-template](https://github.com/keshavsoft/caddy-template)**: Battle-tested Caddy JSON route blueprints.
292
+ - **[caddy-cli](https://github.com/keshavsoft/caddy-cli)**: High-level orchestrator and port inspector.
293
+
294
+ ---
295
+
296
+ ## πŸ“„ License
297
+
298
+ [ISC](LICENSE) &copy; [KeshavSoft](https://github.com/keshavsoft)
package/bin/index.js ADDED
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { run } from "../src/cli.js";
4
+
5
+ run();