@cliftonc/cfld 0.2.0 → 0.2.2

package/README.md

@@ -1,20 +1,49 @@
 # cfld
 
+**`cfld` = cloudflare local dev.**
+
 **One command to give your localhost a permanent public HTTPS URL — no API tokens, no teardown.**
 
 `cfld` wraps [`cloudflared`](https://github.com/cloudflare/cloudflared) into a frictionless dev experience: the **same** custom URL every run (not a random `trycloudflare.com` one), authorized with a **browser login** (zero API tokens), reusing the same named tunnel and DNS record across restarts instead of churning them. It runs a **live dashboard** (URL, connection count, request/latency counters, tailing logs), **auto-reconnects** on edge blips, and **guards** against stealing a DNS record that belongs to another tunnel.
 
+## Getting started
+
+**New here? Just run this — it walks you through everything, no account or config needed to start:**
+
+```bash
+npx @cliftonc/cfld setup
+```
+
+`setup` is the front door. It checks `cloudflared` for you, then lets you pick:
+
+1. **A public URL right now** — free, no account, no domain (a temporary `trycloudflare.com` URL). Great for a webhook, a demo, or just trying it.
+2. **A persistent custom URL** — opens the browser to sign in (or **sign up** — it's free), then wires up the same URL for every future run.
+
+You don't even have to remember `setup`: the **first time you run bare `cfld`** in a fresh project, it drops you into this same guided flow so you're never stuck guessing.
+
+Already know what you want? Skip straight to it:
+
 ```bash
-# one-off, no install
-npx @cliftonc/cfld            # detect your dev port, reuse-or-create a tunnel, go live
+# instant public URL in seconds — no account, no config
+npx @cliftonc/cfld --quick 3000   # temporary trycloudflare.com URL
+
+# the everyday command — reuse-or-create your persistent tunnel and go live
+npx @cliftonc/cfld            # detect your dev port, go live on the same URL
 npx @cliftonc/cfld 3000       # explicit port
-npx @cliftonc/cfld --quick    # ephemeral trycloudflare.com URL — no domain needed
 
 # or install once and use the short `cfld` command everywhere
 npm i -g @cliftonc/cfld
-cfld
+cfld setup
 ```
 
+### What it costs
+
+`cfld` is built to get you going at zero → near-zero cost, and it's honest about the one thing it can't automate:
+
+- **Instant URL** — `cfld --quick`: **free**, no account, no domain. The URL is temporary and changes each run.
+- **Cloudflare account** — **free**. `cfld` opens the browser to sign in (the same page has a **Sign up** link); there's no API token to create. Account signup itself can't be scripted — Cloudflare requires a browser, terms acceptance, and email verification.
+- **Persistent custom URL** — needs a **domain on Cloudflare**. Free if you already own one (just add the site); otherwise a domain is a few dollars/year via [Cloudflare Registrar](https://dash.cloudflare.com/?to=/:account/domains/register). No account has a free permanent subdomain.
+
 ## Why not just `cloudflared`?
 
 The persistent-tunnel flow normally means: create an API token in the dashboard, find your zone/account IDs, `tunnel create`, hand-write a `config.yml`, `route dns`, and remember not to delete anything. `cfld` collapses all of that into one idempotent command and adds the dev niceties (auto port detection, deterministic hostname, `.env` write-back, a live status view).
@@ -46,10 +75,11 @@ A machine-wide registry at `~/.cfld/registry.json` indexes every tunnel, so you
 
 | Command | What it does |
 |---|---|
+| `cfld --quick [port]` | Instant `trycloudflare.com` URL — no account, no cert/domain (temporary). |
+| `cfld setup` | Guided first-run — pick the instant free URL or set up a persistent one. |
 | `cfld [port]` | Ensure + run a persistent tunnel (reuses the same URL). |
-| `cfld --quick [port]` | Ephemeral `trycloudflare.com` URL — no cert/domain. |
 | `cfld login [--reauth]` | Authorize with Cloudflare in your browser. `--reauth` adds another domain. |
-| `cfld init` | Interactive setup wizard — configure a project without running it. |
+| `cfld init` | Configure a persistent tunnel without running it. |
 | `cfld list` | List all tunnels across projects/domains. |
 | `cfld status [name]` | Show details for a tunnel. |
 | `cfld up <name>` | Run a registered tunnel by name from anywhere. |

package/dist/cli.js

@@ -700,9 +700,20 @@ function startChild(options) {
   const exited = new Promise((resolve) => {
     markExited = resolve;
   });
+  const trackedPgids = /* @__PURE__ */ new Set();
+  const trackTree = () => {
+    const pid = child.pid;
+    if (pid === void 0) return;
+    for (const g of descendantPgids(pid)) {
+      if (g > 1 && g !== process.pid) trackedPgids.add(g);
+    }
+  };
+  const poll = setInterval(trackTree, options.pollTreeMs ?? 1500);
+  poll.unref();
   wireLines2(child, "stdout", options.onLine);
   wireLines2(child, "stderr", options.onLine);
   child.on("error", (err) => {
+    clearInterval(poll);
     markExited();
     if (stopped) return;
     stopped = true;
@@ -710,11 +721,18 @@ function startChild(options) {
     options.onLine?.(String(err.message ?? err), "stderr");
   });
   child.on("exit", (code, signal) => {
+    clearInterval(poll);
     markExited();
     if (stopped) return;
     stopped = true;
     options.onExit?.(code, signal);
   });
+  const signalTree = (signal) => {
+    trackTree();
+    const pid = child.pid;
+    if (pid !== void 0) trySignalGroup(pid, signal);
+    for (const g of trackedPgids) trySignalGroup(g, signal);
+  };
   return {
     exited,
     get pid() {
@@ -723,63 +741,64 @@ function startChild(options) {
     stop() {
       if (stopped) return;
       stopped = true;
-      killGroup(child, "SIGINT");
+      clearInterval(poll);
+      signalTree("SIGINT");
       const t = setTimeout(() => {
-        if (child.exitCode === null && !child.signalCode) killGroup(child, "SIGKILL");
+        if (child.exitCode === null && !child.signalCode) signalTree("SIGKILL");
       }, 4e3);
       t.unref();
     },
     kill() {
-      killGroup(child, "SIGKILL");
+      clearInterval(poll);
+      signalTree("SIGKILL");
     }
   };
 }
-function descendantPids(pid) {
+function descendantPgids(pid) {
   let out = "";
   try {
-    out = execSync("ps -A -o pid=,ppid=", { encoding: "utf8" });
+    out = execSync("ps -A -o pid=,ppid=,pgid=", { encoding: "utf8" });
   } catch {
     return [];
   }
   const childrenOf = /* @__PURE__ */ new Map();
+  const pgidOf = /* @__PURE__ */ new Map();
   for (const line of out.split("\n")) {
-    const m = line.trim().match(/^(\d+)\s+(\d+)$/);
+    const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)$/);
     if (!m) continue;
-    const child = Number(m[1]);
+    const proc = Number(m[1]);
     const parent = Number(m[2]);
+    pgidOf.set(proc, Number(m[3]));
     const list = childrenOf.get(parent);
-    if (list) list.push(child);
-    else childrenOf.set(parent, [child]);
+    if (list) list.push(proc);
+    else childrenOf.set(parent, [proc]);
   }
-  const found = [];
+  const pgids = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Set();
   const stack = [pid];
   while (stack.length) {
     for (const child of childrenOf.get(stack.pop()) ?? []) {
-      if (!found.includes(child)) {
-        found.push(child);
-        stack.push(child);
-      }
+      if (seen.has(child)) continue;
+      seen.add(child);
+      stack.push(child);
+      const g = pgidOf.get(child);
+      if (g !== void 0) pgids.add(g);
     }
   }
-  return found;
+  return [...pgids];
 }
-function signalPids(pids, signal) {
-  for (const pid of pids) {
-    try {
-      process.kill(pid, signal);
-    } catch {
-    }
+function trySignalGroup(pgid, signal) {
+  try {
+    process.kill(-pgid, signal);
+  } catch {
   }
 }
 function reapChild(child, graceMs = 3e3) {
-  const tree = child.pid ? descendantPids(child.pid) : [];
   child.stop();
-  signalPids(tree, "SIGINT");
   return new Promise((resolve) => {
     const done2 = () => {
       clearTimeout(grace);
       child.kill();
-      signalPids(tree, "SIGKILL");
       resolve();
     };
     const grace = setTimeout(done2, graceMs);
@@ -787,18 +806,6 @@ function reapChild(child, graceMs = 3e3) {
     child.exited.then(done2);
   });
 }
-function killGroup(child, signal) {
-  const pid = child.pid;
-  if (pid === void 0) return;
-  try {
-    process.kill(-pid, signal);
-  } catch {
-    try {
-      child.kill(signal);
-    } catch {
-    }
-  }
-}
 function wireLines2(child, stream, onLine) {
   const source = stream === "stdout" ? child.stdout : child.stderr;
   if (!source || !onLine) return;
@@ -1555,6 +1562,11 @@ async function initCommand(flags) {
     zone = normalizeZone(await askText("Domain (zone) on Cloudflare?", "example.com"));
   }
   const certPath = await ensureCert(zone, { interactive: true });
+  await configureProject(flags, { zone, certPath, cwd });
+  note("Run `cfld` to go live.");
+}
+async function configureProject(flags, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
   const defaultSlug = deriveSlug(cwd, flags.name);
   const name = slugify(await askText("Project name (used in the URL)", defaultSlug) || defaultSlug);
   const detected = await detectDevPorts();
@@ -1566,13 +1578,13 @@ async function initCommand(flags) {
   if (!Number.isInteger(port) || port <= 0) {
     throw new CfldError(`"${portStr}" is not a valid port.`);
   }
-  const hostname = flags.host ?? buildHostname(name, zone);
+  const hostname = flags.host ?? buildHostname(name, ctx.zone);
   const result = await reconcile(
     {
       slug: name,
       tunnelName: tunnelNameForSlug(name),
-      zone,
-      certPath,
+      zone: ctx.zone,
+      certPath: ctx.certPath,
       routes: [{ hostname, port }],
       projectDir: cwd,
       force: flags.force
@@ -1584,7 +1596,7 @@ async function initCommand(flags) {
   );
   writeProjectConfig(cwd, {
     name,
-    zone,
+    zone: ctx.zone,
     uuid: result.uuid,
     hostname,
     port,
@@ -1592,7 +1604,138 @@ async function initCommand(flags) {
   });
   if (ensureGitignored(cwd, ".cfld.json")) info("Added .cfld.json to .gitignore.");
   done(`Configured https://${hostname} \u2192 localhost:${port}`);
-  note("Run `cfld` to go live.");
+  return { name, hostname, port };
+}
+
+// src/commands/setup.ts
+async function setupCommand(flags) {
+  if (!isInteractive()) {
+    throw new CfldError(
+      "`cfld setup` is interactive.",
+      "In scripts, use `cfld --quick`, or `cfld` with --zone/--host/--name flags."
+    );
+  }
+  step("Let's get cfld set up.");
+  await preflightCloudflared();
+  const cwd = process.cwd();
+  const knownZones = Array.from(
+    /* @__PURE__ */ new Set([...listStoredZones(), ...listEntries().map((e) => e.zone)])
+  );
+  const alreadyAuthorized = knownZones.length > 0 || certHasZone(defaultCertPath());
+  if (alreadyAuthorized) {
+    const config = readProjectConfig(cwd);
+    if (config?.uuid || config?.zone) {
+      done("You're already set up \u2014 run `cfld` to go live.");
+      return;
+    }
+    info("You're already authorized with Cloudflare. Let's configure this project.");
+    const zone2 = await askAuthorizedZone(knownZones);
+    const certPath2 = await ensureCert(zone2, { interactive: true });
+    await configureProject(flags, { zone: zone2, certPath: certPath2, cwd });
+    await offerGoLive(flags, zone2);
+    return;
+  }
+  const path = await askSelect("How do you want to start?", [
+    {
+      value: "quick",
+      label: "Get a public URL right now \u2014 free, no account (temporary URL)"
+    },
+    {
+      value: "persistent",
+      label: "Set up a persistent URL \u2014 free Cloudflare account + a domain"
+    }
+  ]);
+  if (path === "quick") {
+    note(
+      "  Starting a temporary tunnel. Run `cfld setup` again anytime to set up a persistent URL."
+    );
+    await quickCommand(flags);
+    return;
+  }
+  note(
+    [
+      "",
+      "  A browser window will open to authorize cfld with Cloudflare.",
+      `    \u2022 No account yet? Click "Sign up" on that page \u2014 it's free.`,
+      "    \u2022 Then pick (or add) the domain you want to use.",
+      "  Prefer to create the account first? Open:",
+      "      https://dash.cloudflare.com/sign-up",
+      ""
+    ].join("\n")
+  );
+  if (!await askConfirm("Open the browser to authorize now?")) {
+    note(
+      "No problem \u2014 run `cfld setup` again when you're ready, or `cfld --quick` for a temporary URL."
+    );
+    return;
+  }
+  await runLogin();
+  if (!certHasZone(defaultCertPath())) {
+    printZeroZoneGuidance();
+    if (await askConfirm("Start a temporary quick tunnel now instead?")) {
+      await quickCommand(flags);
+      return;
+    }
+    throw new CfldError(
+      "Your Cloudflare account has no domain yet, so a persistent URL isn't possible.",
+      "Add a domain (see above), then run `cfld setup` again."
+    );
+  }
+  const zone = await askAuthorizedZone(knownZones);
+  const certPath = importCert(zone);
+  info(`Saved cert for ${zone}.`);
+  await configureProject(flags, { zone, certPath, cwd });
+  await offerGoLive(flags, zone);
+}
+async function preflightCloudflared() {
+  try {
+    const bin = await resolveBinary();
+    const res = await exec(bin, ["--version"]);
+    const version = (res.stdout.trim() || res.stderr.trim()).split("\n")[0];
+    done(`cloudflared ready${version ? ` \u2014 ${version}` : ""}`);
+  } catch {
+    warn("cloudflared isn't installed, and the bundled binary couldn't load.");
+    note(
+      [
+        "",
+        "  Install it, then run `cfld setup` again:",
+        "    macOS     brew install cloudflared",
+        "    Linux     apt / dnf / pacman install cloudflared",
+        "    Windows   winget install --id Cloudflare.cloudflared",
+        "    Any OS    https://developers.cloudflare.com/tunnel/downloads/",
+        ""
+      ].join("\n")
+    );
+    throw new CfldError(
+      "cloudflared is required to continue.",
+      "Install it (see above), or set CFLD_CLOUDFLARED to its path."
+    );
+  }
+}
+function isBlankFirstRun(flags, cwd, interactive = isInteractive()) {
+  if (!interactive) return false;
+  if (flags.zone || flags.host || flags.quick) return false;
+  if (readProjectConfig(cwd)) return false;
+  if (listStoredZones().length > 0) return false;
+  if (certHasZone(defaultCertPath())) return false;
+  return true;
+}
+async function askAuthorizedZone(knownZones) {
+  if (knownZones.length) {
+    const picked = await askSelect("Which domain did you authorize?", [
+      ...knownZones.map((z) => ({ value: z, label: z })),
+      { value: "__new__", label: "A different domain\u2026" }
+    ]);
+    if (picked !== "__new__") return picked;
+  }
+  return normalizeZone(await askText("Which domain did you authorize?", "example.com"));
+}
+async function offerGoLive(flags, zone) {
+  if (await askConfirm("Go live now?")) {
+    await runCommand({ ...flags, zone });
+  } else {
+    note("Run `cfld` to go live.");
+  }
 }
 
 // src/commands/list.ts
@@ -2061,6 +2204,7 @@ function resolveExec(afterDash, execFlag) {
   return void 0;
 }
 var SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "setup",
   "login",
   "init",
   "list",
@@ -2074,11 +2218,12 @@ var SUBCOMMANDS = /* @__PURE__ */ new Set([
 var HELP = `${pc7.bold("cfld")} \u2014 persistent Cloudflare tunnels for local dev
 
 ${pc7.bold("Usage")}
+  cfld --quick [port]      Instant public URL, no account needed (temporary)
+  cfld setup               Guided first-run: free instant URL, or persistent setup
   cfld [port]              Ensure + run a persistent tunnel (reuses the same URL)
   cfld [port] -- <cmd>     Run + supervise your dev server too (one lifecycle)
-  cfld --quick [port]      Ephemeral trycloudflare.com URL (no domain needed)
   cfld login [--reauth]    Authorize with Cloudflare in your browser
-  cfld init                Interactive setup wizard (configure, don't run)
+  cfld init                Configure a persistent tunnel (don't run)
   cfld list                List all tunnels across projects/domains
   cfld status [name]       Show details for a tunnel
   cfld up <name>           Run a registered tunnel by name from anywhere
@@ -2151,6 +2296,9 @@ async function main(rawArgv) {
       case "help":
         process.stdout.write(HELP);
         return;
+      case "setup":
+        await setupCommand(flags);
+        return;
       case "login":
         await loginCommand(flags);
         return;
@@ -2185,6 +2333,8 @@ async function main(rawArgv) {
   }
   if (flags.quick) {
     await quickCommand(flags);
+  } else if (isBlankFirstRun(flags, process.cwd())) {
+    await setupCommand(flags);
   } else {
     await runCommand(flags);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliftonc/cfld",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Zero-token, persistent Cloudflare tunnel CLI for local dev — same public HTTPS URL every run.",
   "type": "module",
   "bin": {