@cliftonc/cfld 0.2.0 → 0.2.1

package/README.md

@@ -4,17 +4,44 @@
 
 `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
-# one-off, no install
-npx @cliftonc/cfld            # detect your dev port, reuse-or-create a tunnel, go live
+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
+# 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 +73,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

@@ -1555,6 +1555,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 +1571,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 +1589,7 @@ async function initCommand(flags) {
   );
   writeProjectConfig(cwd, {
     name,
-    zone,
+    zone: ctx.zone,
     uuid: result.uuid,
     hostname,
     port,
@@ -1592,7 +1597,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 +2197,7 @@ function resolveExec(afterDash, execFlag) {
   return void 0;
 }
 var SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "setup",
   "login",
   "init",
   "list",
@@ -2074,11 +2211,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 +2289,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 +2326,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.1",
   "description": "Zero-token, persistent Cloudflare tunnel CLI for local dev — same public HTTPS URL every run.",
   "type": "module",
   "bin": {