@sandboxsonny/ace-kit 0.6.0 → 0.7.1

package/dist/{main-YRQQWLHX.js → main-IAQ2IL3M.js}

@@ -126,12 +126,6 @@ async function createSite(options) {
       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(
@@ -140,8 +134,7 @@ async function createSite(options) {
       [
         "# 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")}
@@ -149,7 +142,7 @@ async function createSite(options) {
   } 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.example", [`# The site's domain in CMS Ace.`, domainLine].join("\n"));
     await writeNew(folder, ".env", [domainLine.trim(), ...extraSettings].join("\n") + "\n");
   }
   await writeNew(folder, "README.md", readme({ name, domain, framework: options.framework }));
@@ -182,7 +175,7 @@ var richText = (text) => ({
   type: "doc",
   content: text.split("\n\n").map((paragraph) => ({ type: "paragraph", content: [{ type: "text", text: paragraph }] }))
 });
-var frameworksWithSections = ["astro"];
+var frameworksWithSections = ["astro", "react-router"];
 function pageFields(framework) {
   const fields = [
     { componentKey: "text", label: "Headline", handle: "headline", config: { required: true } },
@@ -396,6 +389,9 @@ async function resolveApiUrl(fromOption, environment) {
     return null;
   }
 }
+var cmsName = (apiUrl) => apiUrl === hostedApiUrl ? "CMS Ace" : `the CMS at ${apiUrl}`;
+var cmsLabel = (apiUrl) => apiUrl === hostedApiUrl ? "CMS Ace" : apiUrl;
+var loginCommandFor = (apiUrl) => apiUrl === hostedApiUrl ? "npx ace-kit login" : `npx ace-kit login --api-url ${apiUrl}`;
 function isLocalApiUrl(apiUrl) {
   return ["localhost", "127.0.0.1", "[::1]"].includes(new URL(apiUrl).hostname);
 }
@@ -525,13 +521,12 @@ async function waitForApproval(dependencies) {
 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.
+  ace-kit login    Sign in. Opens the admin app, where you type the code shown here.
+  ace-kit logout   Sign out, and forget the login kept on this machine.
+  ace-kit whoami   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.
+  --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.
@@ -565,7 +560,7 @@ async function loginCommand(commandArguments, environment) {
   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.`
+      `Warning: ${cmsName(apiUrl)} is not encrypted (http://), so the login could be read on the way. Use https:// if you can.`
     );
   }
   try {
@@ -589,7 +584,7 @@ async function signIn(apiUrl, environment) {
       "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(`Signing in to ${cmsLabel(apiUrl)}
 `);
   environment.out(`  1. Go to   ${page}`);
   environment.out(`  2. Type    ${request.userCode}
@@ -619,7 +614,7 @@ async function logoutCommand(commandArguments, environment) {
   const { apiUrl } = read;
   const stored = await environment.store.read(apiUrl);
   if (!stored) {
-    environment.out(`Not signed in to ${apiUrl}.`);
+    environment.out(`Not signed in to ${cmsLabel(apiUrl)}.`);
     return 0;
   }
   const ended = await environment.fetchImplementation(`${apiUrl}/auth/logout`, {
@@ -632,7 +627,7 @@ async function logoutCommand(commandArguments, environment) {
   );
   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.`
+    ended ? `Signed out of ${cmsLabel(apiUrl)}.` : `Forgot the login for ${cmsLabel(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;
 }
@@ -651,7 +646,7 @@ async function whoamiCommand(commandArguments, environment) {
     now: environment.now
   });
   if (!login) {
-    environment.out(`Not signed in to ${apiUrl}. Run: ace-kit login`);
+    environment.out(`Not signed in to ${cmsLabel(apiUrl)}. Run: ${loginCommandFor(apiUrl).replace("npx ", "")}`);
     return 1;
   }
   try {
@@ -668,10 +663,10 @@ async function whoamiCommand(commandArguments, environment) {
       return 1;
     }
     const me = await response.json();
-    environment.out(`Signed in to ${apiUrl} as ${String(me.email)}, using the login in ${login.source}.`);
+    environment.out(`Signed in to ${cmsLabel(apiUrl)} as ${String(me.email)}, using the login in ${login.source}.`);
     return 0;
   } catch {
-    environment.error(`Could not reach the CMS at ${apiUrl}.`);
+    environment.error(`Could not reach ${cmsName(apiUrl)}.`);
     return 1;
   }
 }
@@ -680,7 +675,7 @@ async function whoamiCommand(commandArguments, environment) {
 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>]
+  ace-kit create <folder> <domain> [--framework astro|react-router] [--name <name>]
 
 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
@@ -691,7 +686,6 @@ 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) {
@@ -742,7 +736,7 @@ ${createUsage}`);
   }
   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.`
+      `Warning: ${cmsName(apiUrl)} is not encrypted (http://), so your login could be read on the way. Use https:// if you can.`
     );
   }
   let login = await resolveLogin({
@@ -797,7 +791,7 @@ Nothing was made.`);
   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.`
+        `Made ${created.domain} in ${apiUrl === hostedApiUrl ? "CMS Ace" : `CMS Ace (${apiUrl})`} with a Pages type, ${seeded.entries} entries and a main menu.`
       );
       break;
     case "exists":
@@ -822,10 +816,462 @@ Next:
   return seeded.kind === "failed" ? 1 : 0;
 }
 
+// src/cli/doctor-command.ts
+import { readFile as readFile3 } from "fs/promises";
+import { join as join4 } from "path";
+import { parseArgs as parseArgs3 } 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"
+]);
+var defaultSchemaFolders = ["src", "app"];
+async function findSchemaFiles(root, folder) {
+  const folders = folder === void 0 ? defaultSchemaFolders : [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);
+      }
+    }
+  }
+  for (const name of folders) await walk(join3(root, name));
+  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/cli/doctor-command.ts
+var doctorUsage = `ace-kit doctor: check that this site is set up to work with CMS Ace.
+
+Usage:
+  ace-kit doctor [--site <domain>] [--dir <folder>]
+
+Run it in your site's folder. It changes nothing and never prints your login. It checks your Node version, that Ace Kit
+is installed, which CMS and site the settings point at, that the CMS can be reached and knows the site, that you are
+signed in, that the site has its Pages content, and that the section types in your code match the CMS. Each problem
+says what to do. It exits with 1 if anything is wrong.
+
+Options:
+  --site      The domain your site has in the CMS (default: ACE_SITE_DOMAIN, else Astro's \`site\` setting).
+  --dir       The folder holding your *.schema.ts files (default: src and app).
+  --help      Show this message.
+`;
+var symbols = { ok: "\u2713", warn: "!", fail: "\u2717", info: "-" };
+var requestTimeoutMilliseconds4 = 15e3;
+var plain = (text) => String(text).replace(/\p{Cc}/gu, "").slice(0, 200);
+var isOlderThan = (version, major, minor) => {
+  const [actualMajor = 0, actualMinor = 0] = version.split(".").map(Number);
+  return actualMajor < major || actualMajor === major && actualMinor < minor;
+};
+async function readText(path) {
+  try {
+    return await readFile3(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+async function domainFromAstroConfig(root) {
+  for (const name of ["astro.config.mjs", "astro.config.ts", "astro.config.js", "astro.config.mts"]) {
+    const text = await readText(join4(root, name));
+    const found = text?.match(/\bsite\s*:\s*["']([^"']+)["']/);
+    if (found?.[1]) return domainFromSite(found[1]);
+  }
+  return null;
+}
+async function doctorCommand(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" },
+      dir: { type: "string" },
+      help: { type: "boolean" }
+    }
+  });
+  if (values.help) {
+    environment.out(doctorUsage);
+    return 0;
+  }
+  const checks = [];
+  const add = (status, label, hint) => checks.push({ status, label, hint });
+  const root = environment.workingDirectory;
+  if (isOlderThan(environment.nodeVersion, 22, 12))
+    add(
+      "fail",
+      `Node ${environment.nodeVersion} is too old`,
+      "Ace Kit needs Node 22.12 or newer. If you use mise, nvm or fnm, check which version it picks in this folder."
+    );
+  else add("ok", `Node ${environment.nodeVersion}`);
+  const manifestText = await readText(join4(root, "package.json"));
+  let framework = null;
+  if (manifestText === null) {
+    add("fail", "No package.json in this folder", "Run this in your site's folder.");
+  } else {
+    let manifest = {};
+    try {
+      manifest = JSON.parse(manifestText);
+    } catch {
+      add("fail", "package.json isn't valid JSON");
+    }
+    const dependencies = { ...manifest.devDependencies, ...manifest.dependencies };
+    if ("astro" in dependencies) framework = "astro";
+    else if ("react-router" in dependencies) framework = "react-router";
+    add(
+      framework ? "ok" : "info",
+      framework ? framework === "astro" ? "An Astro site" : "A React Router site" : "Not an Astro or React Router site"
+    );
+    const installed = await readText(join4(root, "node_modules", "@sandboxsonny", "ace-kit", "package.json"));
+    if (!("@sandboxsonny/ace-kit" in dependencies)) {
+      add("fail", "Ace Kit isn't a dependency of this site", "Run: npm install @sandboxsonny/ace-kit");
+    } else if (installed === null) {
+      add("fail", "Ace Kit isn't installed", "Run: npm install");
+    } else {
+      let version = "unknown";
+      try {
+        version = String(JSON.parse(installed).version ?? "unknown");
+      } catch {
+      }
+      add("ok", `Ace Kit ${version} is installed`);
+      if (version !== environment.version && environment.version !== "development")
+        add("info", `This command is Ace Kit ${environment.version}; the site uses ${version}`);
+    }
+  }
+  let apiUrl = null;
+  try {
+    apiUrl = normaliseApiUrl(values["api-url"] ?? environment.variables.ACE_API_URL ?? hostedApiUrl);
+    add("ok", apiUrl === hostedApiUrl ? "Connected to CMS Ace" : `CMS: ${apiUrl}`);
+  } catch (error) {
+    add("fail", `The CMS address is wrong: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const given = values.site ?? environment.variables.ACE_SITE_DOMAIN;
+  const domain = given ? domainFromSite(given) : framework === "astro" ? await domainFromAstroConfig(root) : null;
+  if (domain) add("ok", `Site: ${domain}`);
+  else
+    add(
+      "fail",
+      "Can't tell which site this is",
+      framework === "astro" ? 'Set `site: "https://your-domain.com"` in astro.config.mjs, or ACE_SITE_DOMAIN in .env.' : "Set ACE_SITE_DOMAIN=your-domain.com in .env."
+    );
+  if (apiUrl) await checkTheCms(apiUrl, domain);
+  return finish();
+  async function request(path, headers = {}) {
+    try {
+      const response = await environment.fetchImplementation(`${apiUrl}${path}`, {
+        headers: { Accept: "application/json", ...headers },
+        signal: AbortSignal.timeout(requestTimeoutMilliseconds4)
+      });
+      return { status: response.status, body: await response.json().catch(() => null) };
+    } catch {
+      return null;
+    }
+  }
+  async function checkTheCms(address, siteDomain) {
+    const health = await request("/health");
+    if (!health || health.status >= 500 || health.status === 404) {
+      add(
+        "fail",
+        `Can't reach the CMS at ${address}`,
+        isLocalApiUrl(address) ? "Is your local CMS running? (docker compose -p cms-backend up -d)" : "Check the address and your connection."
+      );
+      return;
+    }
+    add("ok", "CMS Ace answers");
+    if (!siteDomain) return;
+    const asSite = { "X-Ace-Site-Domain": siteDomain };
+    const site = await request("/public/site", asSite);
+    if (site?.status === 404) {
+      add(
+        "fail",
+        `The CMS has no site with the domain ${siteDomain}`,
+        "Make it with `npx @sandboxsonny/ace-kit create`, or in the admin app, or fix the domain."
+      );
+    } else if (site?.status === 200) {
+      add("ok", `The CMS knows the site: "${plain(site.body?.name)}"`);
+      await checkContent(asSite);
+    } else {
+      add("fail", `The CMS answered with an error (${site?.status ?? "no answer"}) when asked about the site`);
+    }
+    await checkLogin(address, siteDomain);
+  }
+  async function checkContent(asSite) {
+    const types = await request("/public/content-types", asSite);
+    const typeList = Array.isArray(types?.body) ? types.body : [];
+    if (!typeList.some((type) => type.handle === "pages")) {
+      add(
+        "warn",
+        "The site has no Pages content type",
+        "The starter's pages read one. Add it in the admin app (Content types)."
+      );
+      return;
+    }
+    const entries = await request("/public/entries?content_type=pages&limit=100", asSite);
+    const list = Array.isArray(entries?.body) ? entries.body : [];
+    if (list.some((entry) => entry.handle === "home"))
+      add("ok", `Pages has ${list.length} published ${list.length === 1 ? "entry" : "entries"}, including home`);
+    else
+      add(
+        "warn",
+        "Pages has no published entry called home",
+        "The site's front page (/) reads it. Add one in the admin app and publish it."
+      );
+  }
+  async function checkLogin(address, siteDomain) {
+    const login = await resolveLogin({
+      apiUrl: address,
+      variables: environment.variables,
+      store: environment.store,
+      now: environment.now
+    });
+    if (!login) {
+      add("warn", "Not signed in", `Run: ${loginCommandFor(address)}. Section sync and dev sites need it.`);
+      return;
+    }
+    const authorised = { Authorization: `Bearer ${login.token}` };
+    const me = await request("/auth/me", authorised);
+    if (me?.status === 401) {
+      add("warn", "Your login has ended", "Run: npx ace-kit login");
+      return;
+    }
+    if (me?.status !== 200) {
+      add("warn", `Couldn't check your login (${me?.status ?? "no answer"})`);
+      return;
+    }
+    add("ok", `Signed in as ${plain(me.body?.email)}`);
+    const sites = await request("/sites", authorised);
+    const visible = Array.isArray(sites?.body) ? sites.body : [];
+    const mine = visible.find((candidate) => candidate.kind !== "dev" && candidate.domain.toLowerCase() === siteDomain);
+    if (!mine) {
+      add("info", "This login can't see that site, so its section types and preview address weren't checked");
+      return;
+    }
+    if (mine.preview_url) add("ok", `Preview address: ${plain(mine.preview_url)}`);
+    else if (isLocalApiUrl(address))
+      add(
+        "warn",
+        "The site has no Preview address",
+        "Set it in the site's Settings (for example http://localhost:4321) so the customiser can show your site."
+      );
+    await checkSections(address, mine.id, authorised);
+  }
+  async function checkSections(address, siteId, authorised) {
+    const files = await findSchemaFiles(root, values.dir);
+    if (files.length === 0) {
+      add("info", "No section schemas (*.schema.ts) in your code");
+      return;
+    }
+    const loaded = await loadSchemas(files, root, environment.importModule);
+    if (loaded.problems.length > 0) {
+      for (const problem of loaded.problems) add("fail", `Section schema problem: ${plain(problem)}`);
+      return;
+    }
+    const inCode = loaded.definitions.map(({ definition }) => definition.handle);
+    add("ok", `${inCode.length} section type${inCode.length === 1 ? "" : "s"} in your code (${inCode.join(", ")})`);
+    const cms = await request(`/sites/${siteId}/section-types`, authorised);
+    if (!Array.isArray(cms?.body)) return;
+    const active = new Set(
+      cms.body.filter((type) => !type.retired_at).map((type) => type.handle)
+    );
+    const missing = inCode.filter((handle) => !active.has(handle));
+    const unused = [...active].filter((handle) => !inCode.includes(handle));
+    if (missing.length > 0)
+      add(
+        "warn",
+        `Not in the CMS yet: ${missing.join(", ")}`,
+        `Run: npx ace-kit sync${isLocalApiUrl(address) ? ` --api-url ${address}` : ""} (the dev server does this on save)`
+      );
+    else add("ok", "The CMS has all of them");
+    if (unused.length > 0)
+      add(
+        "info",
+        `In the CMS but not in your code: ${unused.join(", ")} (a sync would retire ${unused.length === 1 ? "it" : "them"})`
+      );
+  }
+  function finish() {
+    environment.out("ace-kit doctor\n");
+    for (const check of checks) {
+      environment.out(`  ${symbols[check.status]} ${check.label}`);
+      if (check.hint) environment.out(`      ${check.hint}`);
+    }
+    const failed = checks.filter((check) => check.status === "fail").length;
+    const warned = checks.filter((check) => check.status === "warn").length;
+    environment.out(
+      failed > 0 ? `
+${failed} problem${failed === 1 ? "" : "s"} to fix${warned > 0 ? `, and ${warned} warning${warned === 1 ? "" : "s"}` : ""}.` : warned > 0 ? `
+Nothing is broken; ${warned} warning${warned === 1 ? "" : "s"}.` : "\nAll good."
+    );
+    return failed > 0 ? 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";
+import { parseArgs as parseArgs4 } from "util";
 
 // src/client/errors.ts
 var AcePreviewExpiredError = class extends Error {
@@ -842,7 +1288,7 @@ var AceUnavailableError = class extends Error {
 };
 
 // src/client/create-client.ts
-var requestTimeoutMilliseconds4 = 5e3;
+var requestTimeoutMilliseconds5 = 5e3;
 var maximumCachedAnswers = 500;
 function createAceClient({
   apiUrl,
@@ -866,7 +1312,7 @@ function createAceClient({
     try {
       response = await fetchImplementation(`${apiUrl.replace(/\/+$/, "")}${path}`, {
         headers: { Accept: "application/json", "X-Ace-Site-Domain": siteDomain, "X-Forwarded-Host": siteDomain },
-        signal: AbortSignal.timeout(requestTimeoutMilliseconds4)
+        signal: AbortSignal.timeout(requestTimeoutMilliseconds5)
       });
     } catch {
       throw new AceUnavailableError("Could not reach the CMS.");
@@ -985,16 +1431,15 @@ export {};
 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>]
+  ace-kit generate [--site <domain>] [--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({
+  const { values } = parseArgs4({
     // eslint-disable-next-line id-denylist -- "args" is the name node's parseArgs gives this option.
     args: commandArguments,
     options: {
@@ -1033,192 +1478,10 @@ async function generateCommand(commandArguments, environment) {
 }
 
 // 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 };
-}
+import { parseArgs as parseArgs5 } from "util";
 
 // src/sections/sync.ts
-var requestTimeoutMilliseconds5 = 2e4;
+var requestTimeoutMilliseconds6 = 2e4;
 async function readMessage2(response, fallback) {
   try {
     const body = await response.json();
@@ -1234,7 +1497,7 @@ async function syncSectionTypes(options) {
   try {
     sitesResponse = await fetchImplementation(`${apiUrl}/sites`, {
       headers,
-      signal: AbortSignal.timeout(requestTimeoutMilliseconds5)
+      signal: AbortSignal.timeout(requestTimeoutMilliseconds6)
     });
   } catch {
     return { kind: "unreachable" };
@@ -1256,7 +1519,7 @@ async function syncSectionTypes(options) {
       method: "PUT",
       headers: { ...headers, "Content-Type": "application/json" },
       body: JSON.stringify(payload),
-      signal: AbortSignal.timeout(requestTimeoutMilliseconds5)
+      signal: AbortSignal.timeout(requestTimeoutMilliseconds6)
     });
   } catch {
     return { kind: "unreachable" };
@@ -1290,9 +1553,9 @@ async function syncSectionTypes(options) {
 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>]
+  ace-kit sync [--site <domain>] [--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
+It finds every *.schema.ts file in the folder (src and app 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).
 
@@ -1300,15 +1563,14 @@ Nothing is deleted: a section type, block or field you take out of your code is
 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).
+  --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 (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).
+  --dir       The folder to look in (default: src and app).
   --help      Show this message.
 `;
 var isSwitchedOff = (value) => ["false", "off", "no", "0"].includes((value ?? "").trim().toLowerCase());
 async function syncCommand(commandArguments, environment) {
-  const { values } = parseArgs4({
+  const { values } = parseArgs5({
     // eslint-disable-next-line id-denylist -- "args" is the name node's parseArgs gives this option.
     args: commandArguments,
     options: {
@@ -1344,11 +1606,11 @@ async function syncCommand(commandArguments, environment) {
     );
     return 0;
   }
-  const files = await findSchemaFiles(environment.workingDirectory, values.dir ?? "src");
+  const files = await findSchemaFiles(environment.workingDirectory, values.dir);
   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).`
+        `No *.schema.ts files found in ${values.dir ?? "src or app"}, so nothing was synced (syncing none would retire every section).`
       );
     }
     return 0;
@@ -1360,7 +1622,7 @@ async function syncCommand(commandArguments, environment) {
     now: environment.now
   });
   if (!login) {
-    environment.out(`Section sync is waiting for you to sign in. Run: npx ace-kit login --api-url ${apiUrl}`);
+    environment.out(`Section sync is waiting for you to sign in. Run: ${loginCommandFor(apiUrl)}`);
     return automatic ? 0 : 1;
   }
   const loaded = await loadSchemas(files, environment.workingDirectory, environment.importModule);
@@ -1381,17 +1643,17 @@ async function syncCommand(commandArguments, environment) {
       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(", ")}.` : "")
+        `Synced ${defined.length} section type${defined.length === 1 ? "" : "s"} (${defined.join(", ")}) to ${outcome.site.domain}${apiUrl === hostedApiUrl ? "" : ` (${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}`);
+      environment.out(`Your login has ended. Run: ${loginCommandFor(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."
+        `${cmsName(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":
@@ -1399,7 +1661,7 @@ async function syncCommand(commandArguments, environment) {
       environment.error(outcome.message);
       return 1;
     case "unreachable":
-      environment.error(`Could not reach the CMS at ${apiUrl}.`);
+      environment.error(`Could not reach ${cmsName(apiUrl)}.`);
       return 1;
   }
 }
@@ -1409,6 +1671,7 @@ var usage = `ace-kit: tools for sites built on CMS Ace.
 
 Commands:
   ace-kit create     Make a new site from a starter.
+  ace-kit doctor     Check this site is set up to work with CMS Ace.
   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).
@@ -1422,6 +1685,8 @@ async function runCli(commandArguments, environment) {
   switch (command) {
     case "create":
       return createCommand(rest, environment);
+    case "doctor":
+      return doctorCommand(rest, environment);
     case "generate":
       return generateCommand(rest, environment);
     case "sync":
@@ -1447,6 +1712,7 @@ ${usage}`);
 }
 export {
   createUsage,
+  doctorUsage,
   generateUsage,
   loginUsage,
   runCli,