create-shopify-firebase-app 2.0.6 → 2.1.0

package/lib/preflight.js

@@ -0,0 +1,358 @@
+/**
+ * Preflight — environment doctor
+ *
+ * Runs FIRST, before any scaffolding, provisioning or network work, so the
+ * user never discovers a missing tool six minutes into a long flow.
+ *
+ * Modelled on `flutter doctor`: check everything at once, report it in one
+ * compact aligned block, fix what can be fixed, and be explicit about what is
+ * merely degraded versus what actually blocks the run.
+ *
+ * Checks:
+ * - Node.js       >= 20                (fatal — templates target Node 22)
+ * - npm                                (fatal — installs everything else)
+ * - git                                (warn  — only used for `git init`)
+ * - firebase-tools                     (fatal — offers to install)
+ * - @shopify/cli                       (fatal — offers to install)
+ * - gcloud                             (warn  — API enablement / billing link)
+ *
+ * The five CLI probes are slow subprocess calls, so they run in parallel.
+ */
+
+import { execSync, spawn } from "node:child_process";
+import prompts from "prompts";
+
+// ─── ANSI helpers ─────────────────────────────────────────────────────
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  cyan: "\x1b[36m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+};
+
+const ok   = (msg) => console.log(`  ${c.green}✔${c.reset} ${msg}`);
+const warn = (msg) => console.log(`  ${c.yellow}⚠${c.reset} ${msg}`);
+const info = (msg) => console.log(`  ${c.cyan}ℹ${c.reset} ${msg}`);
+const fail = (msg) => console.log(`  ${c.red}✘${c.reset} ${msg}`);
+const section = (title) => {
+  console.log();
+  console.log(`  ${c.cyan}===${c.reset} ${c.bold}${title}${c.reset} ${c.cyan}===${c.reset}`);
+  console.log();
+};
+
+// ─── Requirements ─────────────────────────────────────────────────────
+
+/** Cloud Functions templates target the Node 22 runtime; the CLI needs modern ESM. */
+const MIN_NODE_MAJOR = 20;
+
+/** Width of the name column in the report — keeps every result line aligned. */
+const LABEL_WIDTH = 14;
+
+// ─── Shell helpers ────────────────────────────────────────────────────
+
+/**
+ * Run a probe command without ever throwing.
+ *
+ * shell:true is required on Windows, where npm/firebase/shopify are .cmd
+ * shims that spawn() cannot execute directly (ENOENT).
+ *
+ * @returns {Promise<{ ok: boolean, stdout: string, stderr: string, error?: string }>}
+ */
+function probe(cmd, timeout = 30000) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let child = null;
+    let settled = false;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { child?.kill(); } catch {}
+      resolve(result);
+    };
+
+    const timer = setTimeout(
+      () => finish({ ok: false, stdout, stderr, error: `timed out after ${Math.round(timeout / 1000)}s` }),
+      timeout,
+    );
+
+    try {
+      child = spawn(cmd, {
+        shell: true,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      });
+    } catch (e) {
+      finish({ ok: false, stdout, stderr, error: e.message });
+      return;
+    }
+
+    child.stdout?.on("data", (d) => (stdout += d.toString()));
+    child.stderr?.on("data", (d) => (stderr += d.toString()));
+    child.on("error", (e) => finish({ ok: false, stdout, stderr, error: e.message }));
+    child.on("close", (code) => finish({ ok: code === 0, stdout, stderr }));
+  });
+}
+
+/**
+ * Pull a version out of CLI output.
+ *
+ * Prefers a line that is *only* a version ("13.35.1") so update notices and
+ * banners cannot win; falls back to the first version-shaped token, which is
+ * what "git version 2.47.0" and "Google Cloud SDK 542.0.0" need.
+ */
+function parseVersion(text) {
+  const lines = String(text || "").split("\n");
+  for (const line of lines) {
+    const bare = line.trim().match(/^v?(\d+\.\d+(?:\.\d+)?)/);
+    if (bare) return bare[1];
+  }
+  const any = String(text || "").match(/\d+\.\d+(?:\.\d+)?/);
+  return any ? any[0] : null;
+}
+
+/** Install a global npm package, showing npm's own progress. Never throws. */
+function installGlobal(pkg) {
+  try {
+    execSync(`npm install -g ${pkg}`, { stdio: "inherit", timeout: 300000 });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: (e?.message || "").toString().trim() };
+  }
+}
+
+// ─── Individual checks ────────────────────────────────────────────────
+// Every check resolves to { name, ok, fatal, version, message }.
+// `fatal` means "this failure blocks the run", so it is always false when
+// ok === true, and false for the optional tools (git, gcloud) even when they
+// are missing.
+
+/** Node.js — read from the running process, no subprocess needed. */
+function checkNode() {
+  try {
+    const version = process.versions?.node || String(process.version || "").replace(/^v/, "");
+    const major = parseInt(String(version).split(".")[0], 10);
+
+    if (!Number.isFinite(major)) {
+      return {
+        name: "Node.js",
+        ok: false,
+        fatal: true,
+        version: null,
+        message: "could not determine the running Node version",
+      };
+    }
+    if (major < MIN_NODE_MAJOR) {
+      return {
+        name: "Node.js",
+        ok: false,
+        fatal: true,
+        version,
+        message: `v${version} — Node ${MIN_NODE_MAJOR}+ required (templates target the Node 22 runtime)`,
+      };
+    }
+    return { name: "Node.js", ok: true, fatal: false, version, message: `v${version}` };
+  } catch (e) {
+    return { name: "Node.js", ok: false, fatal: true, version: null, message: e?.message || "check failed" };
+  }
+}
+
+async function checkNpm() {
+  const r = await probe("npm --version");
+  const version = r.ok ? parseVersion(r.stdout) : null;
+  if (r.ok) return { name: "npm", ok: true, fatal: false, version, message: version || "installed" };
+  return {
+    name: "npm",
+    ok: false,
+    fatal: true,
+    version: null,
+    message: "not found — npm ships with Node.js and is needed to install everything else",
+  };
+}
+
+async function checkGit() {
+  const r = await probe("git --version");
+  const version = r.ok ? parseVersion(r.stdout) : null;
+  if (r.ok) return { name: "git", ok: true, fatal: false, version, message: version || "installed" };
+  return {
+    name: "git",
+    ok: false,
+    fatal: false,
+    version: null,
+    message: "not found — the project will be created without 'git init' (non-blocking)",
+  };
+}
+
+async function checkFirebase() {
+  const r = await probe("firebase --version", 60000);
+  const version = r.ok ? parseVersion(r.stdout) : null;
+  if (r.ok) return { name: "Firebase CLI", ok: true, fatal: false, version, message: version || "installed" };
+  return {
+    name: "Firebase CLI",
+    ok: false,
+    fatal: true,
+    version: null,
+    message: "not found — required to create the project, Firestore and Hosting",
+  };
+}
+
+async function checkShopify() {
+  // `shopify version` is slow the first time it runs — give it room.
+  const r = await probe("shopify version", 90000);
+  const version = r.ok ? parseVersion(r.stdout) : null;
+  if (r.ok) return { name: "Shopify CLI", ok: true, fatal: false, version, message: version || "installed" };
+  return {
+    name: "Shopify CLI",
+    ok: false,
+    fatal: true,
+    version: null,
+    message: "not found — required to create and link the Shopify app",
+  };
+}
+
+async function checkGcloud() {
+  const r = await probe("gcloud --version", 60000);
+  const version = r.ok ? parseVersion(r.stdout) : null;
+  if (r.ok) return { name: "gcloud", ok: true, fatal: false, version, message: version || "installed" };
+  return {
+    name: "gcloud",
+    ok: false,
+    fatal: false,
+    version: null,
+    message: "not found — billing and API enablement will need manual steps",
+  };
+}
+
+// ─── The two CLIs preflight can install for you ───────────────────────
+const INSTALLABLE = [
+  { name: "Firebase CLI", pkg: "firebase-tools", recheck: checkFirebase },
+  { name: "Shopify CLI",  pkg: "@shopify/cli",   recheck: checkShopify },
+];
+
+// ─── Reporting ────────────────────────────────────────────────────────
+
+/** One compact aligned line: `✔ Node.js        v22.20.0`. */
+function line(check) {
+  const label = String(check.name).padEnd(LABEL_WIDTH);
+  const detail = check.ok
+    ? `${c.cyan}${check.message}${c.reset}`
+    : check.message;
+  return `${label} ${detail}`;
+}
+
+function print(check) {
+  if (check.ok) ok(line(check));
+  else if (check.fatal) fail(line(check));
+  else warn(line(check));
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────
+
+/**
+ * Verify the local toolchain before anything else runs.
+ *
+ * @param {object} options
+ * @param {boolean} [options.autoInstall]     Install missing firebase/shopify CLIs without asking.
+ * @param {boolean} [options.nonInteractive]  Never prompt — report only.
+ * @returns {Promise<{ ok: boolean, checks: Array<{ name: string, ok: boolean, fatal: boolean, version: string|null, message: string }> }>}
+ */
+export async function preflight(options = {}) {
+  const isCI = !!options.nonInteractive;
+  let checks = [];
+
+  try {
+    section("Environment Check");
+
+    // ── 1. Probe everything at once ─────────────────────────────
+    // These are slow subprocess calls (the Shopify CLI alone can take
+    // seconds), so they must not run one after another.
+    const node = checkNode();
+    const [npm, git, firebase, shopify, gcloud] = await Promise.all([
+      checkNpm(),
+      checkGit(),
+      checkFirebase(),
+      checkShopify(),
+      checkGcloud(),
+    ]);
+
+    checks = [node, npm, git, firebase, shopify, gcloud];
+    for (const check of checks) print(check);
+
+    // ── 2. Fix what can be fixed ────────────────────────────────
+    for (const spec of INSTALLABLE) {
+      const idx = checks.findIndex((ch) => ch.name === spec.name);
+      if (idx < 0 || checks[idx].ok) continue;
+
+      console.log();
+
+      let shouldInstall = false;
+      if (isCI) {
+        info(`Install it with: ${c.dim}npm install -g ${spec.pkg}${c.reset}`);
+      } else if (options.autoInstall) {
+        shouldInstall = true;
+      } else {
+        const answer = await prompts({
+          type: "confirm",
+          name: "shouldInstall",
+          message: `Install ${spec.name} now (npm install -g ${spec.pkg})?`,
+          initial: true,
+        });
+        shouldInstall = !!answer.shouldInstall;
+      }
+
+      if (!shouldInstall) {
+        if (!isCI) info(`Skipped — install later: ${c.dim}npm install -g ${spec.pkg}${c.reset}`);
+        continue;
+      }
+
+      info(`Installing ${spec.name}...`);
+      const result = installGlobal(spec.pkg);
+
+      if (result.ok) {
+        checks[idx] = await spec.recheck();
+        print(checks[idx]);
+      } else {
+        warn(`Could not install ${spec.pkg} automatically`);
+        info(`Install manually: ${c.dim}npm install -g ${spec.pkg}${c.reset}`);
+        if (result.error) info(`${c.dim}${result.error.split("\n")[0]}${c.reset}`);
+      }
+    }
+
+    // ── 3. Verdict ──────────────────────────────────────────────
+    const blockers = checks.filter((ch) => !ch.ok && ch.fatal);
+    const degraded = checks.filter((ch) => !ch.ok && !ch.fatal);
+
+    console.log();
+    if (blockers.length === 0) {
+      if (degraded.length > 0) {
+        ok(`Environment ready ${c.dim}(${degraded.length} optional tool${degraded.length > 1 ? "s" : ""} missing)${c.reset}`);
+      } else {
+        ok("Environment ready");
+      }
+    } else {
+      fail(`Cannot continue — ${blockers.length} required tool${blockers.length > 1 ? "s" : ""} missing or out of date`);
+      for (const b of blockers) info(`${b.name}: ${b.message}`);
+      if (blockers.some((b) => b.name === "Node.js")) {
+        info(`Upgrade Node: ${c.cyan}https://nodejs.org${c.reset}`);
+      }
+    }
+
+    return { ok: blockers.length === 0, checks };
+  } catch (e) {
+    // Preflight must never be the thing that crashes the CLI.
+    fail(`Environment check failed: ${e?.message || e}`);
+    checks.push({
+      name: "preflight",
+      ok: false,
+      fatal: true,
+      version: null,
+      message: e?.message || "unexpected error during the environment check",
+    });
+    return { ok: false, checks };
+  }
+}

package/lib/provision.js

@@ -81,6 +81,38 @@ function firebaseExec(args, projectId, timeout = 60000) {
   }
 }
 
+/** Sleep — used by the retry/backoff loops below. */
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ─── gcloud CLI wrappers ──────────────────────────────────────────────
+
+/** True when the gcloud CLI is installed and on PATH. */
+function hasGcloud() {
+  try {
+    execSync("gcloud --version", { timeout: 30000, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Run gcloud command, return raw stdout string or { error, message }. */
+function gcloudRaw(args, timeout = 180000) {
+  try {
+    return execSync(`gcloud ${args}`, {
+      encoding: "utf8",
+      timeout,
+      cwd: _cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch (e) {
+    return {
+      error: true,
+      message: (e.stderr || e.stdout || e.message || "").trim(),
+    };
+  }
+}
+
 // ─── Service checks ───────────────────────────────────────────────────
 
 function checkLogin() {
@@ -91,6 +123,41 @@ function checkLogin() {
   return { ok: false };
 }
 
+/**
+ * Direct existence probe — a project-scoped call that only succeeds when the
+ * project really exists for this account. Unlike projects:list it is not
+ * served from an eventually-consistent index.
+ */
+function projectExistsDirect(projectId) {
+  // apps:list is cheap and project-scoped: it errors on a missing project but
+  // succeeds (possibly with zero apps) on one that exists.
+  const r = firebaseJson("apps:list", projectId);
+  if (r?.status === "success") return true;
+  // Secondary probe — `firebase use` resolves the project id server-side.
+  return firebaseExec(`use ${projectId}`);
+}
+
+/**
+ * Confirm a project exists, tolerating the eventual consistency of
+ * `firebase projects:list`. A project created seconds earlier (by index.js)
+ * is often absent from that list, which used to produce a bogus
+ * "Create Firebase project X?" prompt for a project that already exists.
+ */
+async function confirmProjectExists(projectId, listed = []) {
+  if (listed.some((p) => p.projectId === projectId)) return true;
+  if (projectExistsDirect(projectId)) return true;
+
+  info("Waiting for the project to appear in Firebase...");
+  for (const delay of [1500, 3000, 5000]) {
+    await sleep(delay);
+    const r = firebaseJson("projects:list");
+    const projects = r?.status === "success" ? r.result || [] : [];
+    if (projects.some((p) => p.projectId === projectId)) return true;
+    if (projectExistsDirect(projectId)) return true;
+  }
+  return false;
+}
+
 function checkFirestore(projectId) {
   const r = firebaseJson("firestore:databases:list", projectId);
   if (r?.status === "success") {
@@ -110,6 +177,77 @@ function createFirestoreDb(projectId, region) {
   return { ok: false, error: out.message };
 }
 
+/** Google API that must be enabled before the first Firestore call. */
+const FIRESTORE_API = "firestore.googleapis.com";
+
+/**
+ * True for the "API not enabled" 403. Google reports this with status
+ * PERMISSION_DENIED, so it must be tested *before* the billing/permission
+ * branches or it gets misdiagnosed as a billing problem.
+ */
+function isApiDisabledError(message = "") {
+  return (
+    message.includes("has not been used in project") ||
+    message.includes("SERVICE_DISABLED") ||
+    message.includes("accessNotConfigured") ||
+    (message.includes(FIRESTORE_API) &&
+      (message.includes("403") || message.includes("is disabled")))
+  );
+}
+
+/**
+ * Ensure the Cloud Firestore API is enabled on a (possibly brand-new) project.
+ *
+ * A fresh GCP project has firestore.googleapis.com disabled, so the very first
+ * `firestore:databases:create` fails with 403. The firebase CLI has no command
+ * to enable an API, so shell out to gcloud when it is available.
+ *
+ * @returns {{ enabled: boolean, reason?: string, error?: string }}
+ */
+function ensureFirestoreApi(projectId) {
+  if (!hasGcloud()) return { enabled: false, reason: "no-gcloud" };
+
+  const out = gcloudRaw(
+    `services enable ${FIRESTORE_API} --project=${projectId}`,
+  );
+  if (typeof out === "string") return { enabled: true };
+  return { enabled: false, reason: "failed", error: out.message };
+}
+
+/** Actionable guidance for the "API not enabled" 403 (retrying will not help). */
+function printApiDisabledHelp(projectId, region) {
+  warn(`The Cloud Firestore API is not enabled on project "${projectId}"`);
+  info("Re-running the same create command will fail identically until it is.");
+  info(
+    `Enable: ${c.cyan}https://console.cloud.google.com/apis/library/${FIRESTORE_API}?project=${projectId}${c.reset}`,
+  );
+  info(
+    `Or run: ${c.dim}gcloud services enable ${FIRESTORE_API} --project=${projectId}${c.reset}`,
+  );
+  info("Then (allow ~1 min for it to propagate):");
+  info(
+    `  firebase firestore:databases:create "(default)" --location=${region} --project=${projectId}`,
+  );
+}
+
+/**
+ * Set the Cloud Functions artifact cleanup policy.
+ *
+ * `firebase deploy` prompts for this on the first functions deploy. In a
+ * non-interactive shell that prompt aborts the run *after* functions deploy
+ * but *before* the hosting release, leaving Hosting UNRELEASED (site 404s).
+ * Setting the policy up-front removes the prompt from the user's later deploy.
+ */
+function setArtifactPolicy(projectId) {
+  const out = firebaseRaw(
+    "functions:artifacts:setpolicy --force",
+    projectId,
+    120000,
+  );
+  if (typeof out === "string") return { ok: true, output: out };
+  return { ok: false, error: out.message };
+}
+
 function fetchLocations() {
   const raw = firebaseRaw("firestore:locations");
   if (typeof raw !== "string") return null;
@@ -207,9 +345,9 @@ export async function provisionFirebase(config, options = {}) {
   }
 
   // ── 2. Project ──────────────────────────────────────────────
-  const projectExists = (login.projects || []).some(
-    (p) => p.projectId === projectId,
-  );
+  // projects:list is eventually consistent, so a project created moments ago
+  // may be missing from it — confirm properly before offering to create one.
+  const projectExists = await confirmProjectExists(projectId, login.projects);
 
   if (!projectExists && !isCI) {
     warn(`Project "${projectId}" not found in your Firebase account`);
@@ -283,10 +421,35 @@ export async function provisionFirebase(config, options = {}) {
     }
 
     if (region) {
+      // A brand-new GCP project has firestore.googleapis.com disabled, which
+      // makes the very first create return 403 — enable the API first.
+      info("Ensuring the Cloud Firestore API is enabled...");
+      const api = ensureFirestoreApi(projectId);
+      if (api.enabled) {
+        ok("Cloud Firestore API enabled");
+      } else if (api.reason === "no-gcloud") {
+        info("gcloud not found — skipping API pre-enable");
+      } else {
+        warn("Could not enable the Cloud Firestore API automatically");
+      }
+
       info(`Provisioning Firestore in ${c.cyan}${region}${c.reset}...`);
-      const result = createFirestoreDb(projectId, region);
+      let result = createFirestoreDb(projectId, region);
+
+      // A freshly enabled API takes a moment to go live — retry once.
+      if (api.enabled && !result.ok && isApiDisabledError(result.error)) {
+        info("API just enabled — waiting for it to propagate, then retrying...");
+        await sleep(10000);
+        result = createFirestoreDb(projectId, region);
+      }
+
       if (result.ok) {
         ok(`Firestore: ${c.cyan}${region}${c.reset}`);
+      } else if (isApiDisabledError(result.error)) {
+        // Reported as PERMISSION_DENIED but it is not a billing/permission
+        // problem — handle it before those branches so the advice is correct.
+        fail("Firestore provisioning failed — Cloud Firestore API not enabled");
+        printApiDisabledHelp(projectId, region);
       } else {
         fail("Firestore provisioning failed");
         if (
@@ -378,7 +541,26 @@ export async function provisionFirebase(config, options = {}) {
     );
   }
 
-  // ── 6. Cloud Functions / billing ────────────────────────────
+  // ── 6. Deploy prerequisites ─────────────────────────────────
+  // Do this now so the user's later plain `firebase deploy` never hits the
+  // artifact cleanup-policy prompt, which aborts between the functions deploy
+  // and the hosting release. Non-fatal — warn only.
+  console.log();
+  info("Setting Functions artifact cleanup policy...");
+  const policy = setArtifactPolicy(projectId);
+
+  if (policy.ok) {
+    ok("Artifact cleanup policy set — 'firebase deploy' will not prompt");
+  } else {
+    warn("Could not set the artifact cleanup policy (non-fatal)");
+    info("If 'firebase deploy' stops before releasing Hosting, run:");
+    info(
+      `  firebase functions:artifacts:setpolicy --force --project=${projectId}`,
+    );
+    info("  or deploy with: firebase deploy --force");
+  }
+
+  // ── 7. Cloud Functions / billing ────────────────────────────
   console.log();
   info(
     `${c.bold}Cloud Functions${c.reset} require the Blaze (pay-as-you-go) plan`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-shopify-firebase-app",
-  "version": "2.0.6",
+  "version": "2.1.0",
   "description": "Create Shopify apps powered by Firebase — multi-page dashboard, App Bridge, Polaris components, TypeScript or JavaScript. Deploy for free.",
   "keywords": [
     "shopify",

package/templates/js/functions/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "main": "src/index.js",
   "engines": {
-    "node": "20"
+    "node": "22"
   },
   "scripts": {
     "serve": "firebase emulators:start --only functions,firestore",
@@ -15,10 +15,10 @@
     "deploy:all": "firebase deploy"
   },
   "dependencies": {
-    "cors": "^2.8.5",
-    "express": "^4.21.0",
-    "firebase-admin": "^13.0.0",
-    "firebase-functions": "^6.3.0",
-    "jsonwebtoken": "^9.0.2"
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
+    "firebase-admin": "^14.2.0",
+    "firebase-functions": "^7.3.2",
+    "jsonwebtoken": "^9.0.3"
   }
 }

package/templates/js/functions/src/admin-api.js

@@ -10,7 +10,7 @@ adminApiRouter.use(verifySessionToken);
 
 // Shopify API version — update when Shopify releases new versions
 // Docs: https://shopify.dev/docs/api/usage/versioning
-const API_VERSION = "2026-01";
+const API_VERSION = "2026-07";
 
 // Default app settings — returned when no settings are saved yet
 const DEFAULT_SETTINGS = {