@charlescms/astro 0.1.0

package/scripts/setup.js

@@ -0,0 +1,719 @@
+#!/usr/bin/env node
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { createPrivateKey, randomUUID } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import readline from "node:readline";
+
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+
+const args = process.argv.slice(2);
+const command = args.find((arg) => !arg.startsWith("-")) || "setup";
+const deployRequested = args.includes("--deploy") || process.env.CHARLESCMS_SETUP_DEPLOY === "1";
+const openBrowserRequested = args.includes("--open") || process.env.CHARLESCMS_SETUP_OPEN === "1";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const projectRoot = process.cwd();
+const connectorDir = join(projectRoot, ".charlescms", "connector");
+const statePath = join(connectorDir, "setup-state.json");
+
+if (args.includes("--help") || args.includes("-h") || command === "help") {
+  printHelp();
+  process.exit(0);
+}
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(readPackageVersion());
+  process.exit(0);
+}
+if (!["setup", "doctor"].includes(command)) {
+  console.error(`Unknown command "${command}". Run \`charlescms --help\` to see usage.`);
+  process.exit(1);
+}
+
+main().catch((error) => {
+  console.error(error?.message || String(error));
+  process.exit(1);
+});
+
+async function main() {
+  if (command === "doctor") {
+    await doctor();
+  } else {
+    await setup();
+  }
+}
+
+function readPackageVersion() {
+  try {
+    return JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")).version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function printHelp() {
+  console.log(`${BOLD}charlescms${RESET} ${DIM}v${readPackageVersion()}${RESET} — connect an Astro site to GitHub for visual editing
+
+${BOLD}Usage${RESET}
+  npx charlescms <command> [options]
+
+${BOLD}Commands${RESET}
+  ${CYAN}setup${RESET}              Answer a few questions and scaffold the connector
+                     (.charlescms/connector: worker.js, wrangler.toml, state).
+  ${CYAN}doctor${RESET} [url]       Check the connector: files, reachability, and a live
+                     /api/verify (repo access, origin, branch). Pass the Worker
+                     URL, or omit it to reuse the last one.
+
+${BOLD}Options${RESET}
+  --deploy           After scaffolding, create the GitHub App, store the Worker
+                     secrets, and run \`wrangler deploy\`.
+  --open             Open the GitHub App setup page in your browser automatically.
+  -h, --help         Show this help.
+  -v, --version      Print the version.
+
+${BOLD}Examples${RESET}
+  npx charlescms setup --deploy --open
+  npx charlescms doctor https://my-connector.workers.dev
+
+${DIM}Tip: the editor password is the Worker secret AUTH_SECRET; editors enter it on /cms.${RESET}`);
+}
+
+async function setup() {
+  const existing = await readSetupState();
+  if (!process.stdin.isTTY) {
+    const repo = process.env.CHARLESCMS_SETUP_REPO || existing.repo || guessRepo();
+    const config = validateSetupConfig({
+      repo,
+      origin: process.env.CHARLESCMS_SETUP_ORIGIN || existing.origin || "http://localhost:4321",
+      workerName: process.env.CHARLESCMS_SETUP_WORKER || existing.workerName || safeWorkerName(repo),
+      // Detect the repo's real default branch so edits never target a missing
+      // "main" on a "master" repo (the #1 silent publish failure).
+      branch: process.env.CHARLESCMS_SETUP_BRANCH || existing.branch || (await detectDefaultBranch(repo)) || "main"
+    });
+    await writeScaffold(config);
+    if (deployRequested) {
+      const authSecret = process.env.CHARLESCMS_SETUP_AUTH_SECRET || "";
+      if (!authSecret) {
+        throw new Error("CHARLESCMS_SETUP_AUTH_SECRET is required for non-interactive deployment.");
+      }
+      await deployConnector(config, { authSecret });
+    }
+    return;
+  }
+
+  console.log(`\n${BOLD}CharlesCMS connector setup${RESET}`);
+  console.log(`${DIM}You need a GitHub repository and a Cloudflare account. The Worker fits Cloudflare's free tier for typical small sites.${RESET}`);
+  console.log(`${DIM}This setup creates the connector files; --deploy also creates the GitHub App, stores secrets, and publishes the Worker.${RESET}`);
+  console.log(`${DIM}Suggested answers are filled in — press Enter to accept, or type to change. (Lists: ↑/↓ then Enter.)${RESET}`);
+  if (existing.updatedAt) {
+    console.log(`${DIM}Your previous answers are pre-filled too.${RESET}`);
+  }
+
+  const repo = await promptText({
+    title: "Your GitHub repository",
+    hint: "Format: owner/repo   ·   example: your-name/your-site",
+    defaultValue: validRepoPath(existing.repo) ? existing.repo : "",
+    validate: validRepoPath,
+    error: "Enter the full owner/repo path, e.g. your-name/your-site."
+  });
+
+  const origin = await promptOrigin(existing);
+
+  const workerName = await promptText({
+    title: "Name for the connector (a Cloudflare Worker)",
+    hint: "Lowercase letters, numbers and hyphens. Becomes part of its address: <name>.workers.dev",
+    defaultValue: validWorkerName(existing.workerName) ? existing.workerName : safeWorkerName(repo),
+    validate: validWorkerName,
+    error: "Use only lowercase letters, numbers, and hyphens — e.g. acme-cms."
+  });
+
+  // Look up the repo's real default branch so the answer is correct by default
+  // and nobody has to know whether their repo uses main or master.
+  const detectedBranch = await detectDefaultBranch(repo);
+  const branch = await promptText({
+    title: "Which branch should edits be published to?",
+    hint: detectedBranch
+      ? `Detected your repository's default branch: ${detectedBranch}. Press Enter to use it.`
+      : "Usually main. Older projects sometimes use master.",
+    defaultValue: validBranch(existing.branch) ? existing.branch : (detectedBranch || "main"),
+    validate: validBranch,
+    error: "Enter a branch name, for example main."
+  });
+
+  const authSecret = await resolveEditorPassword();
+
+  const config = validateSetupConfig({ repo, origin, workerName, branch });
+  printSummary(config, { protected: Boolean(authSecret) });
+  await writeScaffold(config);
+  if (deployRequested) {
+    await deployConnector(config, { authSecret });
+  } else if (authSecret) {
+    console.log(`\n${DIM}Run \`npx charlescms setup --deploy\` (or the wrangler command above) to store the editor password.${RESET}`);
+  }
+}
+
+// The editor password (Worker secret AUTH_SECRET) is mandatory because the
+// connector deliberately fails closed without it.
+// Kept out of setup-state.json on disk; it is only ever sent to `wrangler secret`.
+async function resolveEditorPassword() {
+  if (process.env.CHARLESCMS_SETUP_AUTH_SECRET) return process.env.CHARLESCMS_SETUP_AUTH_SECRET;
+  if (!process.stdin.isTTY) return "";
+  const choice = await promptSelect({
+    title: "Create the required editor password",
+    hint: "Editors enter this on /cms before they can publish. It is stored only as the Worker's AUTH_SECRET.",
+    options: [
+      { label: "Generate one for me", value: "generate", hint: "a strong random password" },
+      { label: "Type my own", value: "custom", hint: "pick your own" }
+    ],
+    defaultValue: "generate"
+  });
+  if (choice === "custom") {
+    return promptText({
+      title: "Choose an editor password",
+      hint: "At least 8 characters. Editors type this on /cms.",
+      validate: (value) => value.trim().length >= 8,
+      error: "Use at least 8 characters."
+    });
+  }
+  const secret = randomUUID();
+  console.log(`\n  ${BOLD}Editor password:${RESET} ${GREEN}${secret}${RESET}`);
+  console.log(`  ${DIM}Save this now. Editors type it on /cms. Change it later with: npx wrangler secret put AUTH_SECRET${RESET}`);
+  return secret;
+}
+
+async function promptOrigin(existing) {
+  // Local development (http://localhost:4321) is always allowed, so the only
+  // thing to ask is the public website address. It's optional: you can add it
+  // now or later (re-running setup keeps localhost and merges in this URL), and
+  // the connector accepts edits from both.
+  const existingDomain = parseOrigins(existing.origin).find((origin) => !isLocalOrigin(origin)) || "";
+  return promptText({
+    title: "Your live website address (optional)",
+    hint: "The public URL where you'll open the editor in production, e.g. https://www.yoursite.com. Leave blank for now — local development always works and you can add this later.",
+    defaultValue: existingDomain,
+    validate: (value) => value === "" || validHttpUrl(value),
+    error: "Enter a full address including https://, e.g. https://www.yoursite.com — or leave it blank."
+  });
+}
+
+function printSummary(config, options = {}) {
+  console.log(`\n${BOLD}Configuration summary${RESET}`);
+  console.log(`  ${DIM}Repository${RESET}  ${config.repo}`);
+  console.log(`  ${DIM}Branch${RESET}      ${config.branch}`);
+  console.log(`  ${DIM}Editor at${RESET}   ${config.origin}`);
+  console.log(`  ${DIM}Connector${RESET}   ${config.workerName}.workers.dev`);
+  console.log(`  ${DIM}Password${RESET}    ${options.protected ? "set (editors enter it on /cms)" : "set during deployment"}`);
+}
+
+async function writeScaffold({ repo, origin, workerName, branch }) {
+  const config = { repo, origin, workerName, branch };
+  await mkdir(connectorDir, { recursive: true });
+  await copyFile(join(packageRoot, "connector", "worker.js"), join(connectorDir, "worker.js"));
+  const wrangler = await renderWrangler({ workerName, origin, repo, branch });
+  await writeFile(join(connectorDir, "wrangler.toml"), wrangler);
+  await writeSetupState(config);
+
+  console.log("\nConnector files created. Your site source was not changed:");
+  console.log(`  ${join(connectorDir, "worker.js")}`);
+  console.log(`  ${join(connectorDir, "wrangler.toml")}`);
+  console.log(`  ${statePath}`);
+  console.log("\nTo deploy the connector yourself:");
+  console.log(`  cd ${connectorDir}`);
+  console.log("  npx wrangler login");
+  console.log("  npx wrangler secret put GITHUB_APP_ID");
+  console.log("  npx wrangler secret put GITHUB_PRIVATE_KEY");
+  console.log("  npx wrangler secret put AUTH_SECRET   # required editor password");
+  console.log("  npx wrangler deploy");
+  console.log("\nEasiest next step: run `npx charlescms setup --deploy --open`.");
+  console.log("It creates the GitHub App, stores the secrets, deploys the Worker, and prints the connector URL for /cms.");
+}
+
+async function deployConnector(config, { authSecret = "" } = {}) {
+  console.log("\nDeploying the connector…");
+  const app = process.env.CHARLESCMS_SETUP_GITHUB_APP_ID && process.env.CHARLESCMS_SETUP_GITHUB_PRIVATE_KEY
+    ? {
+        id: process.env.CHARLESCMS_SETUP_GITHUB_APP_ID,
+        client_id: process.env.CHARLESCMS_SETUP_GITHUB_CLIENT_ID || "",
+        pem: process.env.CHARLESCMS_SETUP_GITHUB_PRIVATE_KEY,
+        slug: process.env.CHARLESCMS_SETUP_GITHUB_APP_SLUG || ""
+      }
+    : await runGitHubManifestFlow(config);
+  await putWranglerSecret("GITHUB_APP_ID", String(app.id));
+  if (app.client_id) await putWranglerSecret("GITHUB_CLIENT_ID", String(app.client_id));
+  await putWranglerSecret("GITHUB_PRIVATE_KEY", normalizeGitHubPrivateKey(app.pem));
+  await writeSetupState({ ...config, githubAppId: String(app.id), githubClientId: String(app.client_id || ""), githubAppSlug: app.slug || "" });
+  if (app.html_url) console.log(`  GitHub App created: ${app.html_url}`);
+
+  if (authSecret) await putWranglerSecret("AUTH_SECRET", authSecret);
+
+  await runWrangler(["deploy"], "deploy the Cloudflare Worker");
+
+  // The GitHub App is created but not yet installed on the repo — this is the
+  // step users miss most, so surface it loudly and open it for them.
+  const installUrl = app.slug ? `https://github.com/apps/${app.slug}/installations/new` : "";
+  if (installUrl) {
+    console.log(`\n${BOLD}Last step — install the GitHub App on your repository:${RESET}`);
+    console.log(`  ${CYAN}${installUrl}${RESET}`);
+    console.log(`  ${DIM}Choose "${config.repo}" → Install. Without this the connector cannot read or commit.${RESET}`);
+    if (process.stdin.isTTY) openBrowser(installUrl).catch(() => {});
+  }
+
+  console.log("\nThen verify:");
+  console.log(`  npx charlescms doctor https://${config.workerName}.<your-workers-subdomain>.workers.dev`);
+}
+
+async function runGitHubManifestFlow(config) {
+  const state = randomUUID();
+  const server = createServer();
+  const callback = await new Promise((resolve, reject) => {
+    server.on("request", (req, res) => {
+      const url = new URL(req.url, "http://127.0.0.1");
+      if (url.pathname === "/") {
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        res.end(renderGitHubManifestPage({ config, state, redirectUrl: callbackUrl(server) }));
+        return;
+      }
+      if (url.pathname === "/callback") {
+        if (url.searchParams.get("state") !== state) {
+          res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+          res.end("CharlesCMS setup state did not match. Return to the terminal and try again.");
+          reject(new Error("GitHub App manifest state mismatch."));
+          server.close();
+          return;
+        }
+        const code = url.searchParams.get("code");
+        res.writeHead(code ? 200 : 400, { "content-type": "text/plain; charset=utf-8" });
+        res.end(code ? "CharlesCMS received the GitHub App code. You can return to the terminal." : "GitHub did not send a code.");
+        if (code) resolve(code);
+        else reject(new Error("GitHub did not return a manifest code."));
+        server.close();
+        return;
+      }
+      res.writeHead(404).end();
+    });
+    server.on("error", reject);
+    server.listen(Number(process.env.CHARLESCMS_SETUP_CALLBACK_PORT || 0), "127.0.0.1", () => {
+      const url = callbackUrl(server);
+      console.log(`  Open this local setup page: ${url}`);
+      console.log("  It submits a GitHub App manifest and waits for GitHub to redirect back here.");
+      if (openBrowserRequested) openBrowser(url).catch((error) => console.log(`  Could not open browser automatically: ${error.message}`));
+    });
+  });
+  return convertGitHubManifest(callback);
+}
+
+function callbackUrl(server) {
+  const address = server.address();
+  return `http://127.0.0.1:${address.port}`;
+}
+
+function renderGitHubManifestPage({ config, state, redirectUrl }) {
+  const appName = config.workerName.slice(0, 34);
+  const appOwner = process.env.CHARLESCMS_SETUP_GITHUB_APP_OWNER || "user";
+  const repoOwner = config.repo.split("/")[0];
+  const manifest = {
+    name: appName,
+    url: config.origin,
+    redirect_url: `${redirectUrl}/callback`,
+    callback_urls: [`${redirectUrl}/callback`],
+    public: false,
+    default_events: [],
+    default_permissions: {
+      contents: "write",
+      metadata: "read"
+    },
+    description: `CharlesCMS connector for ${config.repo}`
+  };
+  const action = appOwner === "org"
+    ? `https://github.com/organizations/${encodeURIComponent(repoOwner)}/settings/apps/new?state=${encodeURIComponent(state)}`
+    : `https://github.com/settings/apps/new?state=${encodeURIComponent(state)}`;
+  return `<!doctype html>
+<html lang="en">
+  <meta charset="utf-8">
+  <title>CharlesCMS GitHub App setup</title>
+  <body>
+    <p>Creating a GitHub App for CharlesCMS...</p>
+    <form action="${escapeHtml(action)}" method="post">
+      <input type="hidden" name="manifest" value="${escapeHtml(JSON.stringify(manifest))}">
+      <button type="submit">Continue to GitHub</button>
+    </form>
+    <script>document.querySelector("form").submit();</script>
+  </body>
+</html>`;
+}
+
+async function convertGitHubManifest(code) {
+  const res = await fetch(`https://api.github.com/app-manifests/${encodeURIComponent(code)}/conversions`, {
+    method: "POST",
+    headers: {
+      accept: "application/vnd.github+json",
+      "user-agent": "charlescms-setup",
+      "x-github-api-version": "2022-11-28"
+    }
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`GitHub App manifest conversion failed (${res.status}): ${data.message || "request failed"}`);
+  if (!data.id || !data.pem) throw new Error("GitHub App manifest conversion did not return an app id and private key.");
+  return data;
+}
+
+async function putWranglerSecret(name, value) {
+  console.log(`  Storing Worker secret ${name}`);
+  await runWrangler(["secret", "put", name], `store ${name}`, value);
+}
+
+function runWrangler(args, label, stdinValue = null) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("npx", ["wrangler", ...args], {
+      cwd: connectorDir,
+      stdio: ["pipe", "inherit", "pipe"],
+      // On Windows, npm/npx are .cmd batch files that only resolve via a shell.
+      shell: process.platform === "win32"
+    });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Could not ${label}. Wrangler exited with ${code}: ${stderr.trim()}`));
+    });
+    if (stdinValue) child.stdin.end(`${stdinValue}\n`);
+    else child.stdin.end();
+  });
+}
+
+function openBrowser(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "ignore" });
+    child.on("error", reject);
+    child.on("close", (code) => code === 0 ? resolve() : reject(new Error(`${command} exited with ${code}`)));
+  });
+}
+
+async function doctor() {
+  let ok = true;
+
+  console.log("Connector files:");
+  for (const file of ["worker.js", "wrangler.toml", "setup-state.json"]) {
+    const path = join(connectorDir, file);
+    const exists = existsSync(path);
+    console.log(`  ${exists ? "OK     " : "MISSING"} ${path}`);
+    ok &&= exists;
+  }
+
+  const state = await readSetupState();
+  const url = String(process.argv[3] || process.env.CHARLESCMS_CONNECTOR_URL || state.connectorUrl || "")
+    .trim()
+    .replace(/\/+$/, "");
+
+  if (!url) {
+    console.log("\nNo connector URL yet — skipping the live check.");
+    console.log("After you deploy, run:  charlescms doctor https://<your-worker>.workers.dev");
+    process.exit(ok ? 0 : 1);
+  }
+
+  // Remember the URL so future runs can just be `charlescms doctor`.
+  if (url !== state.connectorUrl) await writeSetupState({ ...state, connectorUrl: url });
+
+  // setup-state stores origins as a comma-separated allow-list, but an HTTP
+  // Origin header is a single value — send just one (the first), or the check
+  // 403s with "Origin is not allowed" even when configured correctly.
+  const origin = parseOrigins(state.origin)[0] || "http://localhost:4321";
+  const repo = state.repo || "";
+  const branch = state.branch || "main";
+
+  console.log(`\nLive connector check (${url}):`);
+
+  // 1) Is the Worker deployed and reachable? (403 still means it answered.)
+  try {
+    const res = await fetch(url, { headers: { origin } });
+    const up = res.ok || res.status === 403;
+    console.log(`  ${up ? "OK     " : "FAIL   "} reachable (HTTP ${res.status})`);
+    if (!up) process.exit(1);
+  } catch (error) {
+    console.log(`  FAIL    not reachable — is the Worker deployed? (${error.message})`);
+    process.exit(1);
+  }
+
+  // 2) One /api/verify call exercises the whole chain: origin allow-list, repo
+  // allow-list, secrets, and the GitHub App actually reaching the repo.
+  // If the connector enforces an editor password (AUTH_SECRET), every /api/* call —
+  // including verify — needs the x-charlescms-auth header, so send it here too.
+  const verify = (secret) => fetch(`${url}/api/verify`, {
+    method: "POST",
+    headers: { "content-type": "application/json", origin, ...(secret ? { "x-charlescms-auth": secret } : {}) },
+    body: JSON.stringify({ repo, branch })
+  });
+  try {
+    let res = await verify(process.env.CHARLESCMS_AUTH_SECRET || "");
+    if (res.status === 401 && !process.env.CHARLESCMS_AUTH_SECRET && process.stdin.isTTY) {
+      const secret = await promptText({
+        title: "This connector requires an editor password",
+        hint: "Enter it to finish the check (or set CHARLESCMS_AUTH_SECRET to skip this prompt).",
+        validate: (value) => value.length > 0,
+        error: "Enter the editor password."
+      });
+      res = await verify(secret);
+    }
+    const data = await res.json().catch(() => ({}));
+    if (res.ok) {
+      console.log(`  OK      repo access: ${repo} (default branch "${data.defaultBranch}", ${data.private ? "private" : "public"})`);
+      // The #1 silent failure: edits target a branch that does not exist (e.g.
+      // the config says "main" but the repo's default is "master"). verify still
+      // succeeds because it reads repo metadata, so flag the mismatch loudly.
+      if (data.defaultBranch && branch && branch !== data.defaultBranch) {
+        console.log(`  WARN    you publish to "${branch}", but the repository's default branch is "${data.defaultBranch}".`);
+        console.log(`    → If "${branch}" doesn't exist, every publish fails with 404. Set the branch to "${data.defaultBranch}"`);
+        console.log(`      (re-run setup, or reconnect on /cms and leave the branch field blank to use the default).`);
+        process.exit(1);
+      }
+      console.log("\nConnector is configured correctly. ✅");
+      process.exit(ok ? 0 : 1);
+    }
+    console.log(`  FAIL    verify (HTTP ${res.status}): ${data.error || "request failed"}`);
+    console.log(diagnoseVerify(res.status, origin, repo, data.error));
+    if (res.status === 404 && state.githubAppSlug) {
+      console.log(`    Install it here: https://github.com/apps/${state.githubAppSlug}/installations/new`);
+    }
+    process.exit(1);
+  } catch (error) {
+    console.log(`  FAIL    verify request failed (${error.message})`);
+    process.exit(1);
+  }
+}
+
+function diagnoseVerify(status, origin, repo, error = "") {
+  // The connector's own allow-list rejections say "not allowed"; a 403 without
+  // that phrasing came from GitHub downstream (often a missing User-Agent header
+  // or revoked credentials), not from ALLOWED_ORIGINS/ALLOWED_REPOS.
+  if (status === 401) {
+    return "  → The connector requires an editor password. Set CHARLESCMS_AUTH_SECRET (or enter it when prompted) to the same value as the Worker's AUTH_SECRET secret.";
+  }
+  if (status === 403 && /not allowed/i.test(error)) {
+    return `  → The connector rejected origin "${origin}" or repo "${repo}".\n    Check ALLOWED_ORIGINS and ALLOWED_REPOS in .charlescms/connector/wrangler.toml, then redeploy.`;
+  }
+  if (status === 403) {
+    return `  → GitHub returned 403 for "${repo}". The GitHub App may lack access, or the deployed Worker is outdated — redeploy it with \`npx wrangler deploy\`.`;
+  }
+  if (status === 404) {
+    return `  → Repo "${repo}" not found, or the GitHub App isn't installed on it. Install the app on the repo.`;
+  }
+  if (status >= 500) {
+    return "  → Connector error — usually missing/invalid secrets. Re-run `npx wrangler secret put GITHUB_APP_ID` and `GITHUB_PRIVATE_KEY`.";
+  }
+  return "";
+}
+
+async function readSetupState() {
+  try {
+    return JSON.parse(await readFile(statePath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+async function writeSetupState(config) {
+  await writeFile(statePath, `${JSON.stringify({ ...config, updatedAt: new Date().toISOString() }, null, 2)}\n`);
+}
+
+async function renderWrangler({ workerName, origin, repo, branch }) {
+  const template = await readFile(join(packageRoot, "connector", "wrangler.toml"), "utf8");
+  return template
+    .replace(/^name = .+$/m, `name = ${JSON.stringify(workerName)}`)
+    .replace(/^ALLOWED_ORIGINS = .+$/m, `ALLOWED_ORIGINS = ${JSON.stringify(origin)}`)
+    .replace(/^ALLOWED_REPOS = .+$/m, `ALLOWED_REPOS = ${JSON.stringify(repo)}`)
+    .replace(/^DEFAULT_BRANCH = .+$/m, `DEFAULT_BRANCH = ${JSON.stringify(branch)}`);
+}
+
+// Arrow-key single-select. Falls back to the default when stdin isn't a TTY
+// (piped input, CI) so non-interactive runs never hang.
+function promptSelect({ title, hint, options, defaultValue }) {
+  return new Promise((resolve) => {
+    let index = Math.max(0, options.findIndex((option) => option.value === defaultValue));
+    if (title) console.log(`\n  ${BOLD}${title}${RESET}`);
+    if (hint) console.log(`  ${DIM}${hint}${RESET}`);
+    if (!process.stdin.isTTY) {
+      resolve(options[index].value);
+      return;
+    }
+
+    const stdin = process.stdin;
+    readline.emitKeypressEvents(stdin);
+    stdin.setRawMode(true);
+    stdin.resume();
+    console.log(`  ${DIM}(use ↑/↓ or 1-${options.length}, then Enter)${RESET}`);
+
+    let drawn = false;
+    const draw = () => {
+      if (drawn) process.stdout.write(`\x1b[${options.length}A`);
+      drawn = true;
+      options.forEach((option, i) => {
+        const active = i === index;
+        const pointer = active ? `${CYAN}❯${RESET}` : " ";
+        const label = active ? `${CYAN}${option.label}${RESET}` : option.label;
+        const tail = option.hint ? `  ${DIM}${option.hint}${RESET}` : "";
+        process.stdout.write(`\x1b[2K  ${pointer} ${label}${tail}\n`);
+      });
+    };
+    draw();
+
+    const onKey = (str, key) => {
+      if (!key) return;
+      if (key.name === "up") index = (index - 1 + options.length) % options.length;
+      else if (key.name === "down") index = (index + 1) % options.length;
+      else if (/^[1-9]$/.test(str || "") && Number(str) <= options.length) index = Number(str) - 1;
+      else if (key.name === "return") return finish();
+      else if (key.ctrl && key.name === "c") { finish(); console.log(); process.exit(130); }
+      else return;
+      draw();
+    };
+    const finish = () => {
+      stdin.removeListener("keypress", onKey);
+      stdin.setRawMode(false);
+      stdin.pause();
+      process.stdout.write(`\x1b[${options.length}A`);
+      options.forEach((option, i) => {
+        const chosen = i === index ? `${GREEN}✔${RESET} ${option.label}` : `${DIM}  ${option.label}${RESET}`;
+        process.stdout.write(`\x1b[2K  ${chosen}\n`);
+      });
+      resolve(options[index].value);
+    };
+    stdin.on("keypress", onKey);
+  });
+}
+
+// Free-text prompt with a title + dimmed hint and inline default. Re-asks until
+// the value validates.
+function promptText({ title, hint, defaultValue = "", validate, error }) {
+  return new Promise((resolve) => {
+    if (title) console.log(`\n  ${BOLD}${title}${RESET}`);
+    if (hint) console.log(`  ${DIM}${hint}${RESET}`);
+    const ask = () => {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      rl.question(`  ${CYAN}❯${RESET} `, (answer) => {
+        rl.close();
+        const value = (answer || "").trim() || defaultValue;
+        if (!validate || validate(value)) {
+          resolve(value);
+          return;
+        }
+        console.log(`  ${RED}${error || "Please try again."}${RESET}`);
+        ask();
+      });
+      // Pre-fill the suggested answer as editable text so it's obvious that
+      // pressing Enter accepts it (and you can just edit/clear it to change it).
+      if (defaultValue) rl.write(defaultValue);
+    };
+    ask();
+  });
+}
+
+function validateSetupConfig(config) {
+  const errors = [];
+  if (!validRepoPath(config.repo)) errors.push("repo must be a full owner/repo path");
+  // The origin is optional (localhost is always added). Only reject a value that
+  // was provided but isn't a usable http(s) URL.
+  if (String(config.origin || "").trim() && !parseOrigins(config.origin).length) {
+    errors.push("origin must be a full http:// or https:// URL");
+  }
+  if (!validWorkerName(config.workerName)) errors.push("worker name must contain only letters, numbers, and hyphens");
+  if (!validBranch(config.branch)) errors.push("branch is required");
+  if (errors.length) throw new Error(`Invalid CharlesCMS setup: ${errors.join("; ")}.`);
+  return {
+    ...config,
+    repo: String(config.repo).trim().replace(/^\/+|\/+$/g, ""),
+    origin: mergeOrigins(config.origin),
+    workerName: String(config.workerName).trim(),
+    branch: String(config.branch).trim()
+  };
+}
+
+function validRepoPath(value) {
+  const repo = String(value || "").trim().replace(/^\/+|\/+$/g, "");
+  return /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo);
+}
+
+function validHttpUrl(value) {
+  try {
+    const url = new URL(String(value || "").trim());
+    return ["http:", "https:"].includes(url.protocol) && Boolean(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+function parseOrigins(value) {
+  return String(value || "")
+    .split(",")
+    .map(normalizeUrl)
+    .filter(Boolean)
+    .filter(validHttpUrl);
+}
+
+function mergeOrigins(value) {
+  return [...new Set(["http://localhost:4321", ...parseOrigins(value)])].join(",");
+}
+
+function isLocalOrigin(value) {
+  return /^https?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?$/i.test(String(value || ""));
+}
+
+function validWorkerName(value) {
+  return /^[a-z0-9][a-z0-9-]{0,62}$/i.test(String(value || "").trim());
+}
+
+function validBranch(value) {
+  return Boolean(String(value || "").trim());
+}
+
+function normalizeUrl(value) {
+  return String(value || "").trim().replace(/\/+$/, "");
+}
+
+// Ask GitHub for the repository's default branch (public repos need no auth).
+// Returns "" on any failure so setup falls back to the user's answer / "main".
+async function detectDefaultBranch(repo) {
+  if (!validRepoPath(repo)) return "";
+  try {
+    const res = await fetch(`https://api.github.com/repos/${repo}`, {
+      headers: { accept: "application/vnd.github+json", "user-agent": "charlescms-setup", "x-github-api-version": "2022-11-28" }
+    });
+    if (!res.ok) return "";
+    const data = await res.json();
+    return typeof data.default_branch === "string" ? data.default_branch : "";
+  } catch {
+    return "";
+  }
+}
+
+function guessRepo() {
+  return "owner/site";
+}
+
+function safeWorkerName(repo) {
+  return `charlescms-${String(repo || "site").replace(/[^a-z0-9-]+/gi, "-").replace(/^-+|-+$/g, "").toLowerCase()}`;
+}
+
+function normalizeGitHubPrivateKey(pem) {
+  return createPrivateKey(String(pem)).export({ type: "pkcs8", format: "pem" });
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}