@sandboxsonny/ace-kit 0.5.0 → 0.6.0

package/dist/main-YRQQWLHX.js

@@ -0,0 +1,1454 @@
+#!/usr/bin/env node
+import {
+  hasExpired,
+  normaliseApiUrl
+} from "./chunk-7M26C36M.js";
+
+// src/cli/create-command.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join2, relative, resolve as resolve2 } from "path";
+import { parseArgs as parseArgs2 } from "util";
+
+// src/auth/resolve-login.ts
+async function resolveLogin(options) {
+  const fromEnvironment = options.variables.ACE_TOKEN?.trim();
+  if (fromEnvironment) return { token: fromEnvironment, source: "the ACE_TOKEN setting" };
+  const stored = await options.store.read(options.apiUrl);
+  if (!stored || hasExpired(stored, options.now())) return null;
+  return { token: stored.token, email: stored.email, source: options.store.description };
+}
+
+// src/create/create-site.ts
+import { cp, mkdir, readdir, readFile, rename, writeFile } from "fs/promises";
+import { basename, dirname, join, resolve } from "path";
+
+// src/helpers/package-name.ts
+var packageName = "@sandboxsonny/ace-kit";
+
+// src/helpers/platform.ts
+var hostedApiUrl = "https://api.ace-cms.co.uk";
+function domainFromSite(site) {
+  const trimmed = site.trim();
+  if (trimmed.includes("://")) {
+    try {
+      return new URL(trimmed).hostname.toLowerCase();
+    } catch {
+      return trimmed.toLowerCase();
+    }
+  }
+  return trimmed.replace(/\/.*$/, "").replace(/:\d+$/, "").toLowerCase();
+}
+
+// src/create/create-site.ts
+var frameworks = ["astro", "react-router"];
+var validName = /^[\p{L}\p{N}][\p{L}\p{N} .,-]{0,59}$/u;
+var validDomain = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+function nameFromFolder(folder) {
+  return basename(resolve(folder)).split(/[-_.\s]+/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function packageNameFromFolder(folder) {
+  return basename(resolve(folder)).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+|[-]+$/g, "");
+}
+function checkDomain(site) {
+  const domain = domainFromSite(site);
+  if (!validDomain.test(domain))
+    throw new Error(`"${site}" is not a domain: give the site's domain, for example example.com.`);
+  return domain;
+}
+async function isEmptyOrMissing(folder) {
+  try {
+    return (await readdir(folder)).length === 0;
+  } catch (error) {
+    if (error.code === "ENOENT") return true;
+    throw error;
+  }
+}
+async function listFiles(folder, base = folder) {
+  const files = [];
+  for (const entry of await readdir(folder, { withFileTypes: true })) {
+    const path = join(folder, entry.name);
+    if (entry.isDirectory()) files.push(...await listFiles(path, base));
+    else files.push(path.slice(base.length + 1));
+  }
+  return files;
+}
+async function writeNew(folder, file, text) {
+  await mkdir(dirname(join(folder, file)), { recursive: true });
+  await writeFile(join(folder, file), text, { flag: "wx" });
+}
+function replaceOnce(file, text, pattern, replacement) {
+  if (!pattern.test(text)) throw new Error(`the starter's ${file} has changed: could not find ${pattern}.`);
+  return text.replace(pattern, () => replacement);
+}
+async function planSite(options) {
+  const folder = resolve(options.folder);
+  const domain = checkDomain(options.site);
+  const name = options.name ?? nameFromFolder(folder);
+  const siteName = packageNameFromFolder(folder);
+  if (!validName.test(name))
+    throw new Error(
+      `"${name}" can't be the site's name: use letters, numbers, spaces, full stops, commas and hyphens, up to 60.`
+    );
+  if (!siteName)
+    throw new Error(`Can't make a package name from "${basename(folder)}": give the folder a name with letters in it.`);
+  if (!await isEmptyOrMissing(folder))
+    throw new Error(`${folder} is not empty. Choose a folder that doesn't exist yet.`);
+  return { folder, domain, name, packageName: siteName };
+}
+async function createSite(options) {
+  const { folder, domain, name, packageName: siteName } = await planSite(options);
+  const template = join(options.templatesDirectory, options.framework);
+  await mkdir(folder, { recursive: true });
+  await cp(template, folder, { recursive: true });
+  await rename(join(folder, "_gitignore"), join(folder, ".gitignore"));
+  const kitSpec = options.kitVersion === "development" ? "latest" : `^${options.kitVersion}`;
+  const manifestPath = join(folder, "package.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  manifest.name = siteName;
+  if (!(packageName in manifest.dependencies))
+    throw new Error(`the starter's package.json does not depend on ${packageName}.`);
+  manifest.dependencies[packageName] = kitSpec;
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  const wording = [
+    ["Example Site. A test site for CMS Ace.", `${name}.`],
+    ["A simple example site for testing CMS Ace.", `${name}, built on CMS Ace.`],
+    ["Example Site", name]
+  ];
+  for (const file of await listFiles(folder)) {
+    if (file === "package.json" || file.endsWith(".ico")) continue;
+    const path = join(folder, file);
+    const original = await readFile(path, "utf8");
+    if (original.includes("\0")) continue;
+    let text = original;
+    for (const [from, to] of wording) text = text.replaceAll(from, () => to);
+    if (file === "astro.config.mjs")
+      text = replaceOnce(file, text, /site: "https?:\/\/[^"]+"/, `site: "https://${domain}"`);
+    if (text !== original) await writeFile(path, text);
+  }
+  const settings = [
+    "# Where CMS Ace runs. Leave these out for the hosted CMS Ace; they are for a CMS on your own machine.",
+    "# ACE_API_URL=http://localhost:8080",
+    "# ACE_PREVIEW_ADMIN_ORIGIN=http://localhost:5173",
+    ""
+  ];
+  const extraSettings = Object.entries(options.environmentSettings ?? {}).map(([name2, value]) => `${name2}=${value}`);
+  if (options.framework === "astro") {
+    await writeNew(
+      folder,
+      ".env.example",
+      [
+        "# The site's domain in CMS Ace is the `site` setting in astro.config.mjs. Set this only to override it.",
+        "# ACE_SITE_DOMAIN=" + domain,
+        "",
+        ...settings
+      ].join("\n")
+    );
+    if (extraSettings.length > 0) await writeNew(folder, ".env", `${extraSettings.join("\n")}
+`);
+  } else {
+    const domainLine = `ACE_SITE_DOMAIN=${domain}
+`;
+    await writeNew(folder, ".env.example", [`# The site's domain in CMS Ace.`, domainLine, ...settings].join("\n"));
+    await writeNew(folder, ".env", [domainLine.trim(), ...extraSettings].join("\n") + "\n");
+  }
+  await writeNew(folder, "README.md", readme({ name, domain, framework: options.framework }));
+  return { folder, framework: options.framework, name, packageName: siteName, domain };
+}
+function readme(site) {
+  const frameworkName = site.framework === "astro" ? "Astro" : "React Router";
+  return `# ${site.name}
+
+A ${frameworkName} site on [CMS Ace](https://github.com/sandboxSonny/ace-kit#readme), made with \`npx ${packageName} create\`. Its domain in the CMS is \`${site.domain}\`.
+
+## Start
+
+\`npm install\`, then \`npm run dev\`. The dev server works on your own private copy of the site in CMS Ace, so nothing you try touches the live one. (\`npx ace-kit login\` signs you in again if you need to.)
+
+## Commands
+
+- \`npm run dev\` runs the site, syncing the section types in your code to the CMS.
+- \`npm run generate\` writes TypeScript types for your content types (run it after changing them).
+- \`npm run check\` runs Prettier, ESLint, the type check, the tests and a build.
+
+## Sections
+
+Each kind of page section is a component with a \`*.schema.ts\` file beside it saying what an editor can fill in. See [Sections](https://github.com/sandboxSonny/ace-kit/blob/main/docs/sections.md) in the Ace Kit docs.
+`;
+}
+
+// src/create/starter-content.ts
+var richText = (text) => ({
+  type: "doc",
+  content: text.split("\n\n").map((paragraph) => ({ type: "paragraph", content: [{ type: "text", text: paragraph }] }))
+});
+var frameworksWithSections = ["astro"];
+function pageFields(framework) {
+  const fields = [
+    { componentKey: "text", label: "Headline", handle: "headline", config: { required: true } },
+    { componentKey: "richtext", label: "Body", handle: "body", config: {} },
+    { componentKey: "image", label: "Hero image", handle: "hero", config: {} },
+    { componentKey: "date", label: "Published", handle: "published", config: {} },
+    { componentKey: "link", label: "Button", handle: "button", config: {} }
+  ];
+  if (frameworksWithSections.includes(framework))
+    fields.push({ componentKey: "sections", label: "Content", handle: "content", config: {} });
+  return fields;
+}
+function starterEntries(framework, siteName) {
+  const withSections = frameworksWithSections.includes(framework);
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const entries = [
+    {
+      handle: "home",
+      title: "Home",
+      description: `Welcome to ${siteName}.`,
+      values: {
+        headline: `Welcome to ${siteName}`,
+        body: richText(
+          "Edit this text in the CMS and reload the page to see it change.\n\nPages are rendered on each request, so there is nothing to rebuild."
+        ),
+        button: { href: "https://github.com/sandboxSonny/ace-kit", label: "See Ace Kit" },
+        ...withSections && {
+          content: [
+            {
+              id: "home-hero",
+              type: "hero",
+              values: {
+                heading: "Build pages from sections",
+                subheading: "Each section below is a component in this site. Add, reorder and fill them in from the CMS.",
+                button: { href: "/pages/about", label: "About this site" }
+              },
+              blocks: []
+            },
+            {
+              id: "home-faq",
+              type: "faq",
+              values: { heading: "Questions" },
+              blocks: [
+                {
+                  id: "home-faq-1",
+                  type: "question",
+                  values: {
+                    question: "What is a section?",
+                    answer: richText("A part of a page with its own fields, defined in this site's code.")
+                  }
+                },
+                {
+                  id: "home-faq-2",
+                  type: "question",
+                  values: {
+                    question: "What is a block?",
+                    answer: richText("One item of a list inside a section, like one of these questions.")
+                  }
+                },
+                {
+                  id: "home-faq-3",
+                  type: "question",
+                  values: {
+                    question: "Can I change the order?",
+                    answer: richText("Yes: move sections and blocks up and down in the editor.")
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      handle: "about",
+      title: "About",
+      description: `About ${siteName}.`,
+      values: {
+        headline: "About",
+        body: richText(
+          "Say who you are and what you do.\n\nThis text is an entry in the CMS: editing it there changes this page."
+        ),
+        published: today,
+        ...withSections && {
+          content: [
+            { id: "about-gallery", type: "gallery", values: { heading: "Gallery", published: today }, blocks: [] }
+          ]
+        }
+      }
+    },
+    {
+      handle: "contact",
+      title: "Contact",
+      description: `How to reach ${siteName}.`,
+      values: {
+        headline: "Contact",
+        body: richText("Tell people how to get in touch."),
+        // A link to another entry of the site: it needs About's ID, which exists by now.
+        button: (entryIds) => ({ entryId: entryIds.about, label: "Learn about us" })
+      }
+    }
+  ];
+  return entries;
+}
+
+// src/create/seed-site.ts
+var requestTimeoutMilliseconds = 6e4;
+var CmsError = class extends Error {
+};
+async function createAndSeedSite(options) {
+  const { apiUrl, token, name, domain, framework, fetchImplementation } = options;
+  async function request(method, path, body) {
+    let response;
+    try {
+      response = await fetchImplementation(`${apiUrl}${path}`, {
+        method,
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${token}`,
+          ...body === void 0 ? {} : { "Content-Type": "application/json" }
+        },
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: AbortSignal.timeout(requestTimeoutMilliseconds)
+      });
+    } catch (error) {
+      const cause = error.cause;
+      const reason = cause?.code ?? cause?.message ?? (error instanceof Error ? error.message : String(error));
+      throw new CmsError(`Could not reach the CMS at ${apiUrl} (${reason}).`);
+    }
+    const text = await response.text();
+    let reply = null;
+    try {
+      reply = text ? JSON.parse(text) : null;
+    } catch {
+    }
+    if (response.status === 401) throw new CmsError("The login has ended. Run: npx ace-kit login");
+    if (!response.ok) {
+      const message = reply?.error;
+      const readable = typeof message === "string" ? message.replace(/\p{Cc}/gu, "").slice(0, 300) : "";
+      throw new CmsError(readable || `The CMS answered with an error (${response.status}).`);
+    }
+    return reply;
+  }
+  let siteMade = false;
+  try {
+    const sites = await request("GET", "/sites");
+    const existing = sites.find((site2) => site2.kind !== "dev" && site2.domain.toLowerCase() === domain);
+    if (existing) return { kind: "exists", name: existing.name };
+    const site = await request("POST", "/sites", {
+      name,
+      domain,
+      ...options.previewUrl && { preview_url: options.previewUrl }
+    });
+    siteMade = true;
+    const sitePath = `/sites/${site.id}`;
+    if (frameworksWithSections.includes(framework))
+      await request("PUT", `${sitePath}/section-types`, options.sectionTypes);
+    const components = await request("GET", "/components");
+    const fields = pageFields(framework).map(({ componentKey, label, handle, config }) => {
+      const component = components.find((candidate) => candidate.key === componentKey);
+      if (!component) throw new CmsError(`The CMS has no "${componentKey}" field type.`);
+      return { component_id: component.id, label, handle, config };
+    });
+    const pagesType = await request("POST", `${sitePath}/content-types`, {
+      name: "Pages",
+      handle: "pages",
+      fields
+    });
+    const entryIds = {};
+    for (const entry of starterEntries(framework, name)) {
+      const values = Object.fromEntries(
+        Object.entries(entry.values).map(([handle, value]) => [
+          handle,
+          typeof value === "function" ? value(entryIds) : value
+        ])
+      );
+      const created = await request("POST", `${sitePath}/entries`, {
+        content_type_id: pagesType.id,
+        handle: entry.handle,
+        title: entry.title,
+        description: entry.description,
+        values
+      });
+      entryIds[entry.handle] = created.id;
+    }
+    const link = (label, handle) => ({
+      label,
+      kind: "entry",
+      entry_id: entryIds[handle],
+      children: []
+    });
+    await request("POST", `${sitePath}/menus`, {
+      name: "Main menu",
+      handle: "main-menu",
+      items: [link("Home", "home"), link("About", "about"), link("Contact", "contact")]
+    });
+    return { kind: "seeded", siteId: site.id, entries: Object.keys(entryIds).length };
+  } catch (error) {
+    if (error instanceof CmsError) return { kind: "failed", message: error.message, siteMade };
+    throw error;
+  }
+}
+
+// src/cli/api-url.ts
+async function resolveApiUrl(fromOption, environment) {
+  const address = fromOption ?? environment.variables.ACE_API_URL ?? await environment.lastApiUrl.read() ?? hostedApiUrl;
+  try {
+    return normaliseApiUrl(address);
+  } catch (error) {
+    environment.error(error instanceof Error ? error.message : String(error));
+    return null;
+  }
+}
+function isLocalApiUrl(apiUrl) {
+  return ["localhost", "127.0.0.1", "[::1]"].includes(new URL(apiUrl).hostname);
+}
+
+// src/cli/login-commands.ts
+import { parseArgs } from "util";
+
+// src/auth/device-login.ts
+var DeviceLoginError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "DeviceLoginError";
+    this.reason = reason;
+  }
+};
+var requestTimeoutMilliseconds2 = 15e3;
+var maximumFailures = 5;
+async function post(dependencies, apiUrl, path, body) {
+  return dependencies.fetchImplementation(`${apiUrl}${path}`, {
+    method: "POST",
+    headers: { Accept: "application/json", "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(requestTimeoutMilliseconds2)
+  });
+}
+async function readMessage(response) {
+  try {
+    const body = await response.json();
+    if (typeof body.error === "string") return body.error;
+  } catch {
+  }
+  return `The CMS answered with an error (${response.status}).`;
+}
+async function startDeviceLogin(dependencies) {
+  let response;
+  try {
+    response = await post(dependencies, dependencies.apiUrl, "/auth/device", { client_name: dependencies.clientName });
+  } catch {
+    throw new DeviceLoginError("unavailable", `Could not reach the CMS at ${dependencies.apiUrl}.`);
+  }
+  if (response.status === 503) throw new DeviceLoginError("unsupported", await readMessage(response));
+  if (response.status === 429)
+    throw new DeviceLoginError("unavailable", "Too many attempts. Wait a minute and try again.");
+  if (response.status === 404) {
+    throw new DeviceLoginError(
+      "unsupported",
+      `${dependencies.apiUrl} does not offer command-line sign-in. Is it a CMS Ace API, and is it up to date?`
+    );
+  }
+  if (!response.ok) throw new DeviceLoginError("unavailable", await readMessage(response));
+  const body = await response.json().catch(() => null);
+  const { device_code, user_code, verification_uri, expires_in, interval } = body ?? {};
+  if (typeof device_code !== "string" || typeof user_code !== "string" || typeof verification_uri !== "string" || typeof expires_in !== "number" || typeof interval !== "number") {
+    throw new DeviceLoginError(
+      "unavailable",
+      "The CMS sent a reply this version of ace-kit can't read. Update ace-kit."
+    );
+  }
+  return {
+    deviceCode: device_code,
+    userCode: user_code,
+    verificationUri: verification_uri,
+    expiresInSeconds: expires_in,
+    intervalSeconds: Math.max(1, interval)
+  };
+}
+async function waitForApproval(dependencies) {
+  const { apiUrl, request, sleep, now } = dependencies;
+  const deadline = now() + request.expiresInSeconds * 1e3;
+  let intervalSeconds = request.intervalSeconds;
+  let failures = 0;
+  for (; ; ) {
+    await sleep(intervalSeconds * 1e3);
+    if (now() > deadline)
+      throw new DeviceLoginError("expired", "The code ran out before it was approved. Run ace-kit login again.");
+    let response;
+    try {
+      response = await post(dependencies, apiUrl, "/auth/device/token", { device_code: request.deviceCode });
+    } catch {
+      failures += 1;
+      if (failures >= maximumFailures)
+        throw new DeviceLoginError("unavailable", `Lost contact with the CMS at ${apiUrl}.`);
+      continue;
+    }
+    if (response.status === 404) {
+      throw new DeviceLoginError("expired", "The CMS no longer knows this login. Run ace-kit login again.");
+    }
+    if (response.status === 429) {
+      intervalSeconds += 5;
+      continue;
+    }
+    if (!response.ok) {
+      failures += 1;
+      if (failures >= maximumFailures) throw new DeviceLoginError("unavailable", await readMessage(response));
+      continue;
+    }
+    failures = 0;
+    const body = await response.json().catch(() => null);
+    switch (body?.status) {
+      case "pending":
+        continue;
+      case "slow_down":
+        intervalSeconds += 5;
+        continue;
+      case "denied":
+        throw new DeviceLoginError("denied", "The login was turned down in the admin app.");
+      case "expired":
+        throw new DeviceLoginError("expired", "The code ran out before it was approved. Run ace-kit login again.");
+      case "approved": {
+        const user = body.user;
+        if (typeof body.token !== "string" || typeof body.expires_at !== "string" || typeof user?.email !== "string") {
+          throw new DeviceLoginError("unavailable", "The CMS approved the login but sent a reply that can't be read.");
+        }
+        return { token: body.token, expiresAt: body.expires_at, email: user.email };
+      }
+      default:
+        throw new DeviceLoginError(
+          "unavailable",
+          "The CMS sent a reply this version of ace-kit can't read. Update ace-kit."
+        );
+    }
+  }
+}
+
+// src/cli/login-commands.ts
+var loginUsage = `ace-kit login: sign in to CMS Ace from the command line.
+
+Usage:
+  ace-kit login  [--api-url <address>]    Sign in. Opens the admin app, where you type the code shown here.
+  ace-kit logout [--api-url <address>]    Sign out, and forget the login kept on this machine.
+  ace-kit whoami [--api-url <address>]    Say who you are signed in as.
+
+Options:
+  --api-url   Where the CMS Ace API lives (or set ACE_API_URL, in the environment or a .env file).
+  --help      Show this message.
+
+The login is kept in the macOS Keychain, or in a file only you can read on other systems. On a build server,
+where nobody can approve a login in a browser, set ACE_TOKEN instead.
+`;
+var requestTimeoutMilliseconds3 = 15e3;
+async function readApiUrl(commandArguments, environment) {
+  const { values } = parseArgs({
+    // eslint-disable-next-line id-denylist -- "args" is the name node's parseArgs gives this option.
+    args: commandArguments,
+    options: { "api-url": { type: "string" }, help: { type: "boolean" } }
+  });
+  if (values.help) return { help: true };
+  const apiUrl = await resolveApiUrl(values["api-url"], environment);
+  return apiUrl === null ? null : { apiUrl };
+}
+function webAddress(address) {
+  try {
+    const parsed = new URL(address);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.href : null;
+  } catch {
+    return null;
+  }
+}
+async function loginCommand(commandArguments, environment) {
+  const read = await readApiUrl(commandArguments, environment);
+  if (!read) return 1;
+  if ("help" in read) {
+    environment.out(loginUsage);
+    return 0;
+  }
+  const { apiUrl } = read;
+  if (apiUrl.startsWith("http://") && !isLocalApiUrl(apiUrl)) {
+    environment.error(
+      `Warning: ${apiUrl} is not encrypted (http://), so the login could be read on the way. Use https:// if you can.`
+    );
+  }
+  try {
+    await signIn(apiUrl, environment);
+    return 0;
+  } catch (error) {
+    environment.error(`
+${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+async function signIn(apiUrl, environment) {
+  const request = await startDeviceLogin({
+    fetchImplementation: environment.fetchImplementation,
+    apiUrl,
+    clientName: `ace-kit ${environment.version} on ${environment.hostname}`
+  });
+  const page = webAddress(request.verificationUri);
+  if (!page)
+    throw new DeviceLoginError(
+      "unsupported",
+      "The CMS sent an approval address that isn't a web address, so it was not opened."
+    );
+  environment.out(`Signing in to ${apiUrl}
+`);
+  environment.out(`  1. Go to   ${page}`);
+  environment.out(`  2. Type    ${request.userCode}
+`);
+  environment.out("Check the code on that page matches. Waiting for you to approve it (Ctrl-C to cancel)...");
+  await environment.openBrowser(page).catch(() => void 0);
+  const login = await waitForApproval({
+    fetchImplementation: environment.fetchImplementation,
+    apiUrl,
+    request,
+    sleep: environment.sleep,
+    now: environment.now
+  });
+  await environment.store.write(apiUrl, login);
+  await environment.lastApiUrl.write(apiUrl).catch(() => void 0);
+  environment.out(`
+Signed in as ${login.email}. The login is kept in ${environment.store.description}.`);
+  return login;
+}
+async function logoutCommand(commandArguments, environment) {
+  const read = await readApiUrl(commandArguments, environment);
+  if (!read) return 1;
+  if ("help" in read) {
+    environment.out(loginUsage);
+    return 0;
+  }
+  const { apiUrl } = read;
+  const stored = await environment.store.read(apiUrl);
+  if (!stored) {
+    environment.out(`Not signed in to ${apiUrl}.`);
+    return 0;
+  }
+  const ended = await environment.fetchImplementation(`${apiUrl}/auth/logout`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${stored.token}` },
+    signal: AbortSignal.timeout(requestTimeoutMilliseconds3)
+  }).then(
+    (response) => response.ok || response.status === 401,
+    () => false
+  );
+  await environment.store.remove(apiUrl);
+  environment.out(
+    ended ? `Signed out of ${apiUrl}.` : `Forgot the login for ${apiUrl} on this machine, but could not reach the CMS to end it there. It ends by itself after 30 days unused; a super admin can also end it from the Sessions screen.`
+  );
+  return 0;
+}
+async function whoamiCommand(commandArguments, environment) {
+  const read = await readApiUrl(commandArguments, environment);
+  if (!read) return 1;
+  if ("help" in read) {
+    environment.out(loginUsage);
+    return 0;
+  }
+  const { apiUrl } = read;
+  const login = await resolveLogin({
+    apiUrl,
+    variables: environment.variables,
+    store: environment.store,
+    now: environment.now
+  });
+  if (!login) {
+    environment.out(`Not signed in to ${apiUrl}. Run: ace-kit login`);
+    return 1;
+  }
+  try {
+    const response = await environment.fetchImplementation(`${apiUrl}/auth/me`, {
+      headers: { Accept: "application/json", Authorization: `Bearer ${login.token}` },
+      signal: AbortSignal.timeout(requestTimeoutMilliseconds3)
+    });
+    if (response.status === 401) {
+      environment.out(`The login from ${login.source} has ended. Run: ace-kit login`);
+      return 1;
+    }
+    if (!response.ok) {
+      environment.error(`The CMS answered with an error (${response.status}).`);
+      return 1;
+    }
+    const me = await response.json();
+    environment.out(`Signed in to ${apiUrl} as ${String(me.email)}, using the login in ${login.source}.`);
+    return 0;
+  } catch {
+    environment.error(`Could not reach the CMS at ${apiUrl}.`);
+    return 1;
+  }
+}
+
+// src/cli/create-command.ts
+var createUsage = `ace-kit create: make a new site that uses CMS Ace.
+
+Usage:
+  ace-kit create <folder> <domain> [--framework astro|react-router] [--name <name>] [--api-url <address>]
+
+It signs you in if you aren't already (your browser opens to approve it), makes the site in CMS Ace with starter
+content (a Pages type, Home, About and Contact, a main menu), and copies a starter site into the folder with your
+site's name, domain and package name filled in. If a site with that domain already exists in CMS Ace it is left alone
+and only the folder is made.
+
+Options:
+  <domain>      The domain the site has in CMS Ace, e.g. example.com. (--site <domain> means the same.)
+  --framework   astro (the default) or react-router.
+  --name        The name shown to visitors (default: made from the folder's name, so my-site is "My Site").
+  --api-url     Where the CMS Ace API lives (or set ACE_API_URL). Only for a CMS on your own machine.
+  --help        Show this message.
+`;
+async function createCommand(commandArguments, environment) {
+  const { values, positionals } = parseArgs2({
+    // eslint-disable-next-line id-denylist -- "args" is the name node's parseArgs gives this option.
+    args: commandArguments,
+    allowPositionals: true,
+    options: {
+      site: { type: "string" },
+      framework: { type: "string" },
+      name: { type: "string" },
+      "api-url": { type: "string" },
+      help: { type: "boolean" }
+    }
+  });
+  if (values.help) {
+    environment.out(createUsage);
+    return 0;
+  }
+  const [folder, domainArgument, ...extra] = positionals;
+  const site = values.site ?? domainArgument;
+  if (!folder || extra.length > 0 || values.site !== void 0 && domainArgument !== void 0) {
+    environment.error(`Give a folder and the site's domain.
+
+${createUsage}`);
+    return 1;
+  }
+  if (!site) {
+    environment.error(`Give the site's domain, for example: ace-kit create ${folder} example.com
+
+${createUsage}`);
+    return 1;
+  }
+  const framework = values.framework ?? "astro";
+  if (!frameworks.includes(framework)) {
+    environment.error(`--framework must be ${frameworks.join(" or ")}, not "${framework}".`);
+    return 1;
+  }
+  const options = { folder: resolve2(environment.workingDirectory, folder), site, name: values.name };
+  let plan;
+  let apiUrl;
+  try {
+    plan = await planSite(options);
+    apiUrl = normaliseApiUrl(values["api-url"] ?? environment.variables.ACE_API_URL ?? hostedApiUrl);
+  } catch (error) {
+    environment.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+  if (apiUrl.startsWith("http://") && !isLocalApiUrl(apiUrl)) {
+    environment.error(
+      `Warning: ${apiUrl} is not encrypted (http://), so your login could be read on the way. Use https:// if you can.`
+    );
+  }
+  let login = await resolveLogin({
+    apiUrl,
+    variables: environment.variables,
+    store: environment.store,
+    now: environment.now
+  });
+  if (!login) {
+    try {
+      login = await signIn(apiUrl, environment);
+    } catch (error) {
+      environment.error(`
+${error instanceof Error ? error.message : String(error)}`);
+      return 1;
+    }
+    environment.out("");
+  }
+  let sectionTypes = null;
+  if (frameworksWithSections.includes(framework)) {
+    sectionTypes = JSON.parse(
+      await readFile2(join2(environment.templatesDirectory, `${framework}.section-types.json`), "utf8")
+    );
+  }
+  const onThisMachine = isLocalApiUrl(apiUrl);
+  const devPort = framework === "react-router" ? 4322 : 4321;
+  const seeded = await createAndSeedSite({
+    apiUrl,
+    token: login.token,
+    name: plan.name,
+    domain: plan.domain,
+    previewUrl: onThisMachine ? `http://localhost:${devPort}` : void 0,
+    framework,
+    sectionTypes,
+    fetchImplementation: environment.fetchImplementation
+  });
+  if (seeded.kind === "failed" && !seeded.siteMade) {
+    environment.error(`Could not make the site in CMS Ace: ${seeded.message}
+Nothing was made.`);
+    return 1;
+  }
+  const created = await createSite({
+    ...options,
+    framework,
+    templatesDirectory: environment.templatesDirectory,
+    environmentSettings: apiUrl === hostedApiUrl ? void 0 : {
+      ACE_API_URL: apiUrl,
+      ...onThisMachine && { ACE_PREVIEW_ADMIN_ORIGIN: "http://localhost:5173" }
+    },
+    kitVersion: environment.version
+  });
+  switch (seeded.kind) {
+    case "seeded":
+      environment.out(
+        `Made ${created.domain} in CMS Ace (${apiUrl}) with a Pages type, ${seeded.entries} entries and a main menu.`
+      );
+      break;
+    case "exists":
+      environment.out(
+        `Warning: ${created.domain} already exists in CMS Ace (as "${seeded.name}"), so it was left alone: nothing was added to it.`
+      );
+      break;
+    case "failed":
+      environment.error(
+        `The site ${created.domain} was made in CMS Ace but setting it up stopped: ${seeded.message}
+It is half set up: finish it in the admin app, or delete it there and run this again.`
+      );
+      break;
+  }
+  const shown = relative(environment.workingDirectory, created.folder) || ".";
+  environment.out(`Made ${created.name} (${created.framework}) in ${shown}.
+
+Next:
+  1. cd ${shown}
+  2. npm install
+  3. npm run dev`);
+  return seeded.kind === "failed" ? 1 : 0;
+}
+
+// src/cli/generate-command.ts
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, resolve as resolve3 } from "path";
+import { parseArgs as parseArgs3 } from "util";
+
+// src/client/errors.ts
+var AcePreviewExpiredError = class extends Error {
+  constructor() {
+    super("The preview link has expired.");
+    this.name = "AcePreviewExpiredError";
+  }
+};
+var AceUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AceUnavailableError";
+  }
+};
+
+// src/client/create-client.ts
+var requestTimeoutMilliseconds4 = 5e3;
+var maximumCachedAnswers = 500;
+function createAceClient({
+  apiUrl,
+  siteDomain,
+  cacheSeconds = 5,
+  fetchImplementation = (input, init) => fetch(input, init),
+  now = Date.now
+}) {
+  const cache = /* @__PURE__ */ new Map();
+  function forgetSomeAnswers() {
+    for (const [path, answer] of cache) if (answer.expiresAt <= now()) cache.delete(path);
+    for (const path of cache.keys()) {
+      if (cache.size < maximumCachedAnswers) break;
+      cache.delete(path);
+    }
+  }
+  async function get(path, options = { cached: true }) {
+    const cached = options.cached ? cache.get(path) : void 0;
+    if (cached && cached.expiresAt > now()) return cached.value;
+    let response;
+    try {
+      response = await fetchImplementation(`${apiUrl.replace(/\/+$/, "")}${path}`, {
+        headers: { Accept: "application/json", "X-Ace-Site-Domain": siteDomain, "X-Forwarded-Host": siteDomain },
+        signal: AbortSignal.timeout(requestTimeoutMilliseconds4)
+      });
+    } catch {
+      throw new AceUnavailableError("Could not reach the CMS.");
+    }
+    let value = null;
+    if (response.status === 404) {
+      const reply = await response.json().catch(() => ({}));
+      if (reply.error === "no site for this domain") {
+        throw new AceUnavailableError(`The CMS has no site with the domain "${siteDomain}".`);
+      }
+    } else if (response.status === 403 && !options.cached) {
+      throw new AcePreviewExpiredError();
+    } else if (response.ok) {
+      value = await response.json().catch(() => {
+        throw new AceUnavailableError("The CMS sent a reply that could not be read.");
+      });
+    } else {
+      throw new AceUnavailableError(`The CMS answered with an error (${response.status}).`);
+    }
+    if (options.cached && cacheSeconds > 0) {
+      if (cache.size >= maximumCachedAnswers) forgetSomeAnswers();
+      cache.set(path, { expiresAt: now() + cacheSeconds * 1e3, value });
+    }
+    return value;
+  }
+  return {
+    /**
+     * One live entry of a content type, by its handle; null if the site has no such entry. With a preview token the
+     * entry the token was made for comes back with its draft applied (never cached); a token that has run out throws
+     * AcePreviewExpiredError.
+     */
+    async getEntry(contentTypeHandle, handle, options = {}) {
+      const path = `/public/entries/${encodeURIComponent(handle)}`;
+      const entry = options.previewToken ? await get(`${path}?preview=${encodeURIComponent(options.previewToken)}`, {
+        cached: false
+      }) : await get(path);
+      return entry && entry.content_type_handle === contentTypeHandle ? entry : null;
+    },
+    /** The live entries of a content type, newest first. */
+    async getEntries(contentTypeHandle, options = {}) {
+      const query = new URLSearchParams({ content_type: contentTypeHandle });
+      if (options.limit) query.set("limit", String(options.limit));
+      return await get(`/public/entries?${query}`) ?? [];
+    },
+    /** One of the site's navigation menus by its handle, with every link worked out; null if the site has none. */
+    getMenu(handle) {
+      return get(`/public/menus/${encodeURIComponent(handle)}`);
+    },
+    /** What the site's content types and fields are, which is what type generation reads. */
+    async getContentTypes() {
+      return await get("/public/content-types") ?? [];
+    }
+  };
+}
+
+// src/helpers/generate-types.ts
+var quote = (text) => JSON.stringify(text);
+function typeOfField(field) {
+  switch (field.component_key) {
+    case "text":
+    case "textarea":
+      return { type: "string" };
+    case "number":
+      return { type: "number" };
+    case "checkbox":
+      return { type: "boolean" };
+    case "select": {
+      const options = field.config?.options ?? [];
+      return { type: options.length > 0 ? options.map(quote).join(" | ") : "string" };
+    }
+    case "image":
+      return { type: "AceImageData", uses: "AceImageData" };
+    case "richtext":
+      return { type: "AceRichTextDocument", uses: "AceRichTextDocument" };
+    case "date":
+      return { type: "string" };
+    case "link":
+      return { type: "AceLinkData", uses: "AceLinkData" };
+    case "sections":
+      return { type: "AceSection[]", uses: "AceSection" };
+    default:
+      return { type: "unknown" };
+  }
+}
+function generateTypes(contentTypes, packageName2, source) {
+  const used = /* @__PURE__ */ new Set();
+  const blocks = contentTypes.map((contentType) => {
+    const lines = contentType.fields.map((field) => {
+      const { type, uses } = typeOfField(field);
+      if (uses) used.add(uses);
+      const optional = field.config?.required === true ? "" : "?";
+      return `      /** ${field.label.replace(/\*\//g, "* /")} */
+      ${quote(field.handle)}${optional}: ${type};`;
+    });
+    const body = lines.length > 0 ? `{
+${lines.join("\n")}
+    }` : "Record<string, never>";
+    return `    /** ${contentType.name.replace(/\*\//g, "* /")} */
+    ${quote(contentType.handle)}: ${body};`;
+  });
+  const imports = used.size > 0 ? `import type { ${[...used].sort().join(", ")} } from ${quote(packageName2)};
+
+` : "";
+  return `// Generated by ace-kit from ${source}. Do not edit: run \`ace-kit generate\` to update it.
+${imports}declare module ${quote(packageName2)} {
+  interface AceContentTypes {
+${blocks.join("\n")}
+  }
+}
+
+export {};
+`;
+}
+
+// src/cli/generate-command.ts
+var generateUsage = `ace-kit generate: write TypeScript types for your CMS Ace content types.
+
+Usage:
+  ace-kit generate [--site <domain>] [--api-url <address>] [--out <file>]
+
+Options:
+  --site      The domain your site has in the CMS, e.g. example.com (or set ACE_SITE_DOMAIN). --domain means the same.
+  --api-url   Where the CMS Ace API lives (or set ACE_API_URL). Only for a CMS on your own machine.
+  --out       Where to write the types (default: src/ace-kit.generated.d.ts).
+  --help      Show this message.
+`;
+async function generateCommand(commandArguments, environment) {
+  const { values } = parseArgs3({
+    // eslint-disable-next-line id-denylist -- "args" is the name node's parseArgs gives this option.
+    args: commandArguments,
+    options: {
+      "api-url": { type: "string" },
+      site: { type: "string" },
+      domain: { type: "string" },
+      out: { type: "string" },
+      help: { type: "boolean" }
+    }
+  });
+  if (values.help) {
+    environment.out(generateUsage);
+    return 0;
+  }
+  const apiUrl = values["api-url"] ?? environment.variables.ACE_API_URL ?? hostedApiUrl;
+  const given = values.site ?? values.domain ?? environment.variables.ACE_SITE_DOMAIN;
+  if (!given) {
+    environment.error("Give the site's domain: --site, or ACE_SITE_DOMAIN.");
+    return 1;
+  }
+  const siteDomain = domainFromSite(given);
+  const client = createAceClient({
+    apiUrl,
+    siteDomain,
+    cacheSeconds: 0,
+    fetchImplementation: environment.fetchImplementation
+  });
+  const contentTypes = await client.getContentTypes();
+  const file = resolve3(values.out ?? "src/ace-kit.generated.d.ts");
+  await mkdir2(dirname2(file), { recursive: true });
+  await writeFile2(file, generateTypes(contentTypes, packageName, siteDomain));
+  environment.out(
+    `Wrote types for ${contentTypes.length} content type${contentTypes.length === 1 ? "" : "s"} to ${file}.`
+  );
+  return 0;
+}
+
+// src/cli/sync-command.ts
+import { parseArgs as parseArgs4 } from "util";
+
+// src/sections/find-schemas.ts
+import { readdir as readdir2 } from "fs/promises";
+import { join as join3, relative as relative2 } from "path";
+var schemaFilePattern = /\.schema\.(?:ts|mts|js|mjs)$/;
+var skippedFolders = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".astro",
+  ".react-router",
+  ".output",
+  "coverage"
+]);
+async function findSchemaFiles(root, folder = "src") {
+  const start = join3(root, folder);
+  const found = [];
+  async function walk(directory) {
+    let entries;
+    try {
+      entries = await readdir2(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const path = join3(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (!skippedFolders.has(entry.name)) await walk(path);
+      } else if (entry.isFile() && schemaFilePattern.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+        found.push(path);
+      }
+    }
+  }
+  await walk(start);
+  return found.sort((first, second) => {
+    const [firstName, secondName] = [relative2(root, first), relative2(root, second)];
+    return firstName < secondName ? -1 : firstName > secondName ? 1 : 0;
+  });
+}
+
+// src/sections/load-schemas.ts
+import { relative as relative3 } from "path";
+
+// src/sections/payload.ts
+var handlePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var maximumHandleLength = 64;
+var maximumNameLength = 200;
+var fieldTypes = [
+  "text",
+  "textarea",
+  "number",
+  "checkbox",
+  "select",
+  "image",
+  "richtext",
+  "date",
+  "link"
+];
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isHandle = (value) => typeof value === "string" && value.length <= maximumHandleLength && handlePattern.test(value);
+var handleRule = 'lowercase letters, numbers and hyphens (such as "call-to-action")';
+function checkFields(fields, where, problems) {
+  if (fields === void 0) return;
+  if (!Array.isArray(fields)) {
+    problems.push(`${where}: fields must be a list.`);
+    return;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  fields.forEach((field, index) => {
+    if (!isObject(field)) {
+      problems.push(`${where}: field ${index + 1} must be an object with a handle, a label and a type.`);
+      return;
+    }
+    const name = isHandle(field.handle) ? `field "${field.handle}"` : `field ${index + 1}`;
+    if (!isHandle(field.handle)) problems.push(`${where}: ${name} needs a handle of ${handleRule}.`);
+    else if (seen.has(field.handle)) problems.push(`${where}: ${name} is defined twice.`);
+    else seen.add(field.handle);
+    if (typeof field.label !== "string" || field.label.trim() === "" || field.label.length > maximumNameLength) {
+      problems.push(`${where}: ${name} needs a label.`);
+    }
+    if (typeof field.type !== "string" || !fieldTypes.includes(field.type)) {
+      const given = typeof field.type === "string" ? ` "${field.type}"` : "";
+      problems.push(`${where}: ${name} has a type${given} that isn't one of ${fieldTypes.join(", ")}.`);
+    } else if (field.type === "select") {
+      const { options } = field;
+      if (!Array.isArray(options) || options.length === 0 || options.some((option) => typeof option !== "string" || option === "")) {
+        problems.push(`${where}: ${name} is a select, so it needs options: a list of the choices, as text.`);
+      }
+    }
+    if (field.required !== void 0 && typeof field.required !== "boolean") {
+      problems.push(`${where}: ${name} has a required that isn't true or false.`);
+    }
+  });
+}
+function checkSectionDefinition(definition, where = "this section") {
+  const problems = [];
+  if (!isObject(definition)) {
+    return [`${where}: the default export must be the result of defineSection({ ... }).`];
+  }
+  if (!isHandle(definition.handle)) {
+    problems.push(`${where}: needs a handle of ${handleRule}.`);
+  }
+  if (typeof definition.name !== "string" || definition.name.trim() === "" || definition.name.length > maximumNameLength) {
+    problems.push(`${where}: needs a name.`);
+  }
+  checkFields(definition.fields, where, problems);
+  if (definition.blocks !== void 0) {
+    if (!isObject(definition.blocks)) {
+      problems.push(`${where}: blocks must be an object of the kinds of block, by handle.`);
+    } else {
+      for (const [handle, block] of Object.entries(definition.blocks)) {
+        const blockWhere = `${where}, block "${handle}"`;
+        if (!isHandle(handle)) problems.push(`${blockWhere}: the handle must be ${handleRule}.`);
+        if (!isObject(block)) {
+          problems.push(`${blockWhere}: must be an object with a name and fields.`);
+          continue;
+        }
+        if (typeof block.name !== "string" || block.name.trim() === "") problems.push(`${blockWhere}: needs a name.`);
+        checkFields(block.fields, blockWhere, problems);
+      }
+    }
+  }
+  return problems;
+}
+function apiFields(fields) {
+  return (fields ?? []).map((field) => ({
+    handle: field.handle,
+    label: field.label,
+    component_key: field.type,
+    config: {
+      ...field.required ? { required: true } : {},
+      ...field.type === "select" ? { options: [...field.options] } : {}
+    }
+  }));
+}
+function sectionTypesPayload(definitions) {
+  return {
+    sections: definitions.map((definition) => ({
+      handle: definition.handle,
+      name: definition.name,
+      fields: apiFields(definition.fields),
+      blocks: Object.entries(definition.blocks ?? {}).map(([handle, block]) => ({
+        handle,
+        name: block.name,
+        fields: apiFields(block.fields)
+      }))
+    }))
+  };
+}
+
+// src/sections/load-schemas.ts
+async function loadSchemas(files, root, importModule) {
+  const definitions = [];
+  const problems = [];
+  const handleToFile = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const name = relative3(root, file);
+    let exported;
+    try {
+      const module = await importModule(file);
+      exported = module.default;
+    } catch (error) {
+      problems.push(`${name}: could not be loaded: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    const fileProblems = checkSectionDefinition(exported, name);
+    if (fileProblems.length > 0) {
+      problems.push(...fileProblems);
+      continue;
+    }
+    const definition = exported;
+    const earlier = handleToFile.get(definition.handle);
+    if (earlier) {
+      problems.push(`${name}: the handle "${definition.handle}" is already used by ${earlier}.`);
+      continue;
+    }
+    handleToFile.set(definition.handle, name);
+    definitions.push({ file, definition });
+  }
+  return { definitions, problems };
+}
+
+// src/sections/sync.ts
+var requestTimeoutMilliseconds5 = 2e4;
+async function readMessage2(response, fallback) {
+  try {
+    const body = await response.json();
+    if (typeof body.error === "string") return body.error;
+  } catch {
+  }
+  return fallback;
+}
+async function syncSectionTypes(options) {
+  const { apiUrl, siteDomain, token, payload, fetchImplementation } = options;
+  const headers = { Accept: "application/json", Authorization: `Bearer ${token}` };
+  let sitesResponse;
+  try {
+    sitesResponse = await fetchImplementation(`${apiUrl}/sites`, {
+      headers,
+      signal: AbortSignal.timeout(requestTimeoutMilliseconds5)
+    });
+  } catch {
+    return { kind: "unreachable" };
+  }
+  if (sitesResponse.status === 401) return { kind: "login-ended" };
+  if (!sitesResponse.ok)
+    return {
+      kind: "rejected",
+      message: await readMessage2(sitesResponse, `The CMS answered with an error (${sitesResponse.status}).`)
+    };
+  const sites = await sitesResponse.json().catch(() => []);
+  const wanted = siteDomain.trim().toLowerCase();
+  const site = sites.find((candidate) => candidate.domain.toLowerCase() === wanted);
+  if (!site)
+    return { kind: "site-not-found", domain: siteDomain, available: sites.map((candidate) => candidate.domain) };
+  let response;
+  try {
+    response = await fetchImplementation(`${apiUrl}/sites/${site.id}/section-types`, {
+      method: "PUT",
+      headers: { ...headers, "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(requestTimeoutMilliseconds5)
+    });
+  } catch {
+    return { kind: "unreachable" };
+  }
+  if (response.status === 401) return { kind: "login-ended" };
+  if (response.status === 403) {
+    return {
+      kind: "forbidden",
+      message: "Your account can't change this site's sections: only a site's owners and super admins can."
+    };
+  }
+  if (!response.ok)
+    return {
+      kind: "rejected",
+      message: await readMessage2(response, `The CMS answered with an error (${response.status}).`)
+    };
+  const body = await response.json().catch(() => null);
+  return {
+    kind: "synced",
+    site: { id: site.id, domain: site.domain },
+    sections: (body?.sections ?? []).map((section) => ({
+      handle: section.handle,
+      name: section.name,
+      retired: section.retired_at !== void 0
+    })),
+    warnings: body?.warnings ?? []
+  };
+}
+
+// src/cli/sync-command.ts
+var syncUsage = `ace-kit sync: send the section types your code defines to CMS Ace.
+
+Usage:
+  ace-kit sync [--site <domain>] [--api-url <address>] [--dir <folder>]
+
+It finds every *.schema.ts file in the folder (src by default), checks them, and makes the CMS's section types for your
+site match. The dev server does this for you whenever a schema file is saved; run it yourself for a one-off sync, or on a
+build server (with ACE_TOKEN set).
+
+Nothing is deleted: a section type, block or field you take out of your code is kept in the CMS, hidden, so the content
+written in it survives. If any schema file can't be loaded, nothing is synced.
+
+Options:
+  --site      The domain your site has in the CMS, e.g. example.com (default: ACE_SITE_DOMAIN, else localhost).
+              (--domain means the same.)
+  --api-url   Where the CMS Ace API lives (default: ACE_API_URL, else the hosted CMS Ace). Only for a CMS on your own machine.
+  --dir       The folder to look in (default: src).
+  --help      Show this message.
+`;
+var isSwitchedOff = (value) => ["false", "off", "no", "0"].includes((value ?? "").trim().toLowerCase());
+async function syncCommand(commandArguments, environment) {
+  const { values } = parseArgs4({
+    // eslint-disable-next-line id-denylist -- "args" is the name node's parseArgs gives this option.
+    args: commandArguments,
+    options: {
+      "api-url": { type: "string" },
+      site: { type: "string" },
+      domain: { type: "string" },
+      dir: { type: "string" },
+      // Set by the dev server, which syncs on its own: it stays quiet when there is nothing to do, and keeps to a
+      // local CMS unless told otherwise.
+      automatic: { type: "boolean" },
+      help: { type: "boolean" }
+    }
+  });
+  if (values.help) {
+    environment.out(syncUsage);
+    return 0;
+  }
+  const automatic = values.automatic === true;
+  if (automatic && isSwitchedOff(environment.variables.ACE_SYNC_SECTIONS)) return 0;
+  let apiUrl;
+  try {
+    apiUrl = normaliseApiUrl(values["api-url"] ?? environment.variables.ACE_API_URL ?? hostedApiUrl);
+  } catch (error) {
+    environment.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+  const given = values.site ?? values.domain ?? environment.variables.ACE_SITE_DOMAIN;
+  const siteDomain = given ? domainFromSite(given) : "localhost";
+  const aimedAtDevSite = environment.variables.ACE_DEV_SITE_ACTIVE === "1";
+  if (automatic && !aimedAtDevSite && !isLocalApiUrl(apiUrl) && environment.variables.ACE_SYNC_SECTIONS?.trim().toLowerCase() !== "remote") {
+    environment.out(
+      `Section sync is off while ${apiUrl} is a hosted CMS, so a half-written change can't reach a live site. To sync on every save to it anyway, set ACE_SYNC_SECTIONS=remote. (npx ace-kit sync always works.)`
+    );
+    return 0;
+  }
+  const files = await findSchemaFiles(environment.workingDirectory, values.dir ?? "src");
+  if (files.length === 0) {
+    if (!automatic) {
+      environment.out(
+        `No *.schema.ts files found in ${values.dir ?? "src"}, so nothing was synced (syncing none would retire every section).`
+      );
+    }
+    return 0;
+  }
+  const login = await resolveLogin({
+    apiUrl,
+    variables: environment.variables,
+    store: environment.store,
+    now: environment.now
+  });
+  if (!login) {
+    environment.out(`Section sync is waiting for you to sign in. Run: npx ace-kit login --api-url ${apiUrl}`);
+    return automatic ? 0 : 1;
+  }
+  const loaded = await loadSchemas(files, environment.workingDirectory, environment.importModule);
+  if (loaded.problems.length > 0) {
+    for (const problem of loaded.problems) environment.error(problem);
+    environment.error("Nothing was synced, because syncing only some of your sections would retire the rest.");
+    return 1;
+  }
+  const outcome = await syncSectionTypes({
+    apiUrl,
+    siteDomain,
+    token: login.token,
+    payload: sectionTypesPayload(loaded.definitions.map((entry) => entry.definition)),
+    fetchImplementation: environment.fetchImplementation
+  });
+  switch (outcome.kind) {
+    case "synced": {
+      const defined = outcome.sections.filter((section) => !section.retired).map((section) => section.handle);
+      const retired = outcome.sections.filter((section) => section.retired).map((section) => section.handle);
+      environment.out(
+        `Synced ${defined.length} section type${defined.length === 1 ? "" : "s"} (${defined.join(", ")}) to ${outcome.site.domain} (${apiUrl}).` + (retired.length > 0 ? ` No longer in your code, kept but hidden: ${retired.join(", ")}.` : "")
+      );
+      for (const warning of outcome.warnings) environment.error(`Warning: ${warning}`);
+      return 0;
+    }
+    case "login-ended":
+      environment.out(`Your login has ended. Run: npx ace-kit login --api-url ${apiUrl}`);
+      return automatic ? 0 : 1;
+    case "site-not-found":
+      environment.error(
+        `The CMS at ${apiUrl} has no site with the domain "${outcome.domain}" that you can see` + (outcome.available.length > 0 ? ` (your sites: ${outcome.available.join(", ")})` : "") + ". Set ACE_SITE_DOMAIN or pass --site."
+      );
+      return 1;
+    case "forbidden":
+    case "rejected":
+      environment.error(outcome.message);
+      return 1;
+    case "unreachable":
+      environment.error(`Could not reach the CMS at ${apiUrl}.`);
+      return 1;
+  }
+}
+
+// src/cli/main.ts
+var usage = `ace-kit: tools for sites built on CMS Ace.
+
+Commands:
+  ace-kit create     Make a new site from a starter.
+  ace-kit generate   Write TypeScript types for your content types.
+  ace-kit sync       Send the section types your code defines to the CMS.
+  ace-kit login      Sign in from the command line (opens the admin app).
+  ace-kit logout     Sign out.
+  ace-kit whoami     Say who you are signed in as.
+
+Run a command with --help for more.
+`;
+async function runCli(commandArguments, environment) {
+  const [command, ...rest] = commandArguments;
+  switch (command) {
+    case "create":
+      return createCommand(rest, environment);
+    case "generate":
+      return generateCommand(rest, environment);
+    case "sync":
+      return syncCommand(rest, environment);
+    case "login":
+      return loginCommand(rest, environment);
+    case "logout":
+      return logoutCommand(rest, environment);
+    case "whoami":
+      return whoamiCommand(rest, environment);
+    case "--help":
+    case "-h":
+    case "help":
+    case void 0:
+      environment.out(usage);
+      return command === void 0 ? 1 : 0;
+    default:
+      environment.error(`Unknown command "${command}".
+
+${usage}`);
+      return 1;
+  }
+}
+export {
+  createUsage,
+  generateUsage,
+  loginUsage,
+  runCli,
+  syncUsage
+};