@sandboxsonny/ace-kit 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @sandboxsonny/ace-kit
 
+## 0.8.0
+
+### Minor Changes
+
+- 7b85a62: Add `AceSeo` for Astro: one component for a page's title, description, canonical address, robots and sharing tags, built on `astro-seo` (with `siteName` ending the title) and filled from the entry's SEO title and description. Every content type in the CMS now has those two required fields, so the Astro starter depends on `astro-seo`, uses `AceSeo` in its layout, and fills them in on its starter pages. `seoProperties` is exported for any other framework.
+
+## 0.7.1
+
+### Patch Changes
+
+- 98f4d58: The command line no longer shows where CMS Ace lives. `--help`, the messages and a new site's `.env.example` talk about CMS Ace, not an address, and connect to it without being told. `--api-url` and `ACE_API_URL` still work for a CMS on your own machine; they are just not advertised (see CONTRIBUTING.md).
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -58,7 +58,7 @@ const about = await getEntry("pages", "about");
 | [API reference](docs/api-reference.md)     | Every export                                 |
 | [Releasing](docs/releasing.md)             | Versions, the changelog and publishing       |
 
-The same pages, with live examples of the React components, are in Storybook: `npm run storybook`.
+The same pages, with live examples of the React components, are in Storybook: **https://sandboxsonny.github.io/ace-kit/** (or `npm run storybook` to run it yourself).
 
 ## Status
 

package/astro/AceSeo.astro

@@ -0,0 +1,12 @@
+---
+import { SEO } from "astro-seo";
+
+import { seoProperties } from "../dist/index.js";
+import type { AceSeoOptions } from "../dist/index.js";
+
+type Props = AceSeoOptions;
+
+const properties = seoProperties(Astro.props);
+---
+
+<SEO {...properties} />

package/dist/astro-integration.js

@@ -1,4 +1,4 @@
-import { startDevSite, sectionSync } from './chunk-T7DKI2U3.js';
+import { startDevSite, sectionSync } from './chunk-2W2NWDKV.js';
 import { domainFromSite, hostedAdminOrigin, hostedApiUrl } from './chunk-N5DIMG3X.js';
 import { envField } from 'astro/config';
 import { fileURLToPath } from 'url';

package/dist/{chunk-T7DKI2U3.js → chunk-2W2NWDKV.js}

@@ -140,6 +140,13 @@ async function chooseLoginStore(options) {
     return file;
   }
 }
+
+// src/cli/api-url.ts
+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);
+}
 var runCommand = (command, commandArguments, input) => new Promise((resolve, reject) => {
   const child = spawn(command, commandArguments, { stdio: ["pipe", "pipe", "ignore"] });
   let stdout = "";
@@ -236,11 +243,6 @@ async function resolveLogin(options) {
   return { token: stored.token, email: stored.email, source: options.store.description };
 }
 
-// src/cli/api-url.ts
-function isLocalApiUrl(apiUrl) {
-  return ["localhost", "127.0.0.1", "[::1]"].includes(new URL(apiUrl).hostname);
-}
-
 // src/dev-site/prepare-dev-site.ts
 var off = ["false", "off", "no", "0"];
 var on = ["true", "on", "yes", "1"];
@@ -305,7 +307,7 @@ async function startDevSite(options) {
       return null;
     case "waiting-for-login":
       log.warn(
-        `You are not signed in to ${outcome.apiUrl}, so this is showing the live site and section sync is off. Run: npx ace-kit login --api-url ${outcome.apiUrl}`
+        `You are not signed in to ${cmsLabel(outcome.apiUrl)}, so this is showing the live site and section sync is off. Run: ${loginCommandFor(outcome.apiUrl)}`
       );
       return null;
     case "problem":

package/dist/cli.js

@@ -9,8 +9,8 @@ if (major < 22 || major === 22 && minor < 12) {
   process.exit(1);
 }
 try {
-  const { createRealEnvironment } = await import("./environment-J4VYOHDK.js");
-  const { runCli } = await import("./main-AGLPUGNN.js");
+  const { createRealEnvironment } = await import("./environment-NGXBLWXM.js");
+  const { runCli } = await import("./main-JOA27GX6.js");
   const environment = await createRealEnvironment();
   process.exit(await runCli(process.argv.slice(2), environment));
 } catch (error) {

package/dist/{environment-J4VYOHDK.js → environment-NGXBLWXM.js}

@@ -145,7 +145,7 @@ function createLastApiUrl(path) {
 }
 
 // src/cli/version.ts
-var aceKitVersion = true ? "0.7.0" : "development";
+var aceKitVersion = true ? "0.8.0" : "development";
 
 // src/cli/environment.ts
 var runCommand = (command, commandArguments, input) => new Promise((resolve, reject) => {

package/dist/index.d.ts

@@ -447,6 +447,54 @@ declare function refreshPageContent(): Promise<void>;
  */
 declare function listenForPreviewRefresh(adminOrigin: string, refresh?: () => Promise<void>): () => void;
 
+/** The two values every entry has, whatever its content type: what a search engine shows for it. */
+declare const seoTitleHandle = "seo-title";
+declare const seoDescriptionHandle = "seo-description";
+type AceSeoOptions = {
+    /** The entry the page shows. Its SEO title and description are used, falling back to its title and description. */
+    entry?: Pick<AceEntry, "title" | "description" | "values">;
+    /** Used when there is no entry, or the entry has no title of its own. */
+    title?: string;
+    /** Used when there is no entry, or the entry has no description of its own. */
+    description?: string;
+    /** The site's name: it ends the page's `<title>` ("About us | Acme") and is the shared link's `og:site_name`. */
+    siteName?: string;
+    /** The page's address, if it isn't the one requested. Left out, the requested address is used. */
+    canonical?: string;
+    /** A picture to show when the page is shared: a full web address. */
+    image?: string;
+    /** Tells search engines to leave the page out, as for a draft shown in preview. */
+    noindex?: boolean;
+};
+type Meta = {
+    property?: string;
+    name?: string;
+    content: string;
+};
+/** What `astro-seo`'s `<SEO>` takes (only the parts used here). */
+type AceSeoProperties = {
+    title?: string;
+    description?: string;
+    canonical?: string;
+    noindex: boolean;
+    twitter: {
+        card: "summary" | "summary_large_image";
+        title?: string;
+        description?: string;
+        image?: string;
+    };
+    extend: {
+        meta: Meta[];
+    };
+};
+/**
+ * Works out what a page's search and sharing tags say. An entry's SEO title and description win; if the editor left
+ * them out (an entry saved before they were required, say) its own title and description are used, then the
+ * options'. The site's name ends the `<title>` (not the sharing titles), unless the title already is the name.
+ * Open Graph is written as plain meta tags, so a page with no picture needs no placeholder.
+ */
+declare function seoProperties(options: AceSeoOptions): AceSeoProperties;
+
 /**
  * A text area field's text as HTML. With `multiline` (the default) blank lines start new paragraphs (`<p>`) and a
  * single new line is a line break; without it the text is one line, with no element around it. Every piece of text
@@ -488,4 +536,4 @@ type AceSection = {
   blocks: AceSectionBlock[];
 };
 
-export { type AceAddress, type AceClient, type AceClientOptions, type AceContentTypeHandle, type AceContentTypeSchema, type AceContentTypes, type AceDateFormat, type AceEntry, type AceFieldSchema, type AceImageAttributes, type AceImageData, type AceImageOptions, type AceLinkAttributes, type AceLinkData, type AceMenu, type AceMenuItem, type AceNavigationLink, type AcePage, AcePreviewExpiredError, type AceRichTextDocument, type AceRichTextMark, type AceRichTextNode, type AceSection, type AceSectionBlock, AceUnavailableError, type AceValuesOf, type BlockDefinition, type SectionDefinition, type SectionFieldDefinition, type SectionFieldType, type SectionOf, type SectionTypesPayload, type ValuesOfFields, addFramingPolicy, addressFromPath, checkSectionDefinition, createAceClient, defineSection, formatAceDate, framingPolicy, headingLevel, homeAddress, imageAttributes, isCurrentPage, isHomeAddress, isInternalPath, isRefreshRequest, linkAddress, linkAttributes, linksFromMenu, listStart, listenForPreviewRefresh, loadMenuLinks, loadPage, originOf, pageNotices, pathOfAddress, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, refreshPageContent, renderRichText, renderTextArea, richTextImageSizes, sectionTypesPayload, swapPageContent, visitablePath };
+export { type AceAddress, type AceClient, type AceClientOptions, type AceContentTypeHandle, type AceContentTypeSchema, type AceContentTypes, type AceDateFormat, type AceEntry, type AceFieldSchema, type AceImageAttributes, type AceImageData, type AceImageOptions, type AceLinkAttributes, type AceLinkData, type AceMenu, type AceMenuItem, type AceNavigationLink, type AcePage, AcePreviewExpiredError, type AceRichTextDocument, type AceRichTextMark, type AceRichTextNode, type AceSection, type AceSectionBlock, type AceSeoOptions, type AceSeoProperties, AceUnavailableError, type AceValuesOf, type BlockDefinition, type SectionDefinition, type SectionFieldDefinition, type SectionFieldType, type SectionOf, type SectionTypesPayload, type ValuesOfFields, addFramingPolicy, addressFromPath, checkSectionDefinition, createAceClient, defineSection, formatAceDate, framingPolicy, headingLevel, homeAddress, imageAttributes, isCurrentPage, isHomeAddress, isInternalPath, isRefreshRequest, linkAddress, linkAttributes, linksFromMenu, listStart, listenForPreviewRefresh, loadMenuLinks, loadPage, originOf, pageNotices, pathOfAddress, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, refreshPageContent, renderRichText, renderTextArea, richTextImageSizes, sectionTypesPayload, seoDescriptionHandle, seoProperties, seoTitleHandle, swapPageContent, visitablePath };

package/dist/index.js

@@ -133,4 +133,35 @@ function formatAceDate(date, format = {}) {
   }).format(moment);
 }
 
-export { checkSectionDefinition, defineSection, formatAceDate, sectionTypesPayload };
+// src/helpers/seo.ts
+var seoTitleHandle = "seo-title";
+var seoDescriptionHandle = "seo-description";
+var textValue = (value) => typeof value === "string" ? value.trim() : "";
+function seoProperties(options) {
+  const { entry } = options;
+  const title = textValue(entry?.values?.[seoTitleHandle]) || textValue(entry?.title) || textValue(options.title);
+  const description = textValue(entry?.values?.[seoDescriptionHandle]) || textValue(entry?.description) || textValue(options.description);
+  const meta = [{ property: "og:type", content: "website" }];
+  if (title) meta.push({ property: "og:title", content: title });
+  if (description) meta.push({ property: "og:description", content: description });
+  if (options.siteName) meta.push({ property: "og:site_name", content: options.siteName });
+  if (options.canonical) meta.push({ property: "og:url", content: options.canonical });
+  if (options.image) meta.push({ property: "og:image", content: options.image });
+  const siteName = options.siteName?.trim();
+  const pageTitle = title && siteName && title !== siteName ? `${title} | ${siteName}` : title;
+  return {
+    ...pageTitle && { title: pageTitle },
+    ...description && { description },
+    ...options.canonical && { canonical: options.canonical },
+    noindex: options.noindex === true,
+    twitter: {
+      card: options.image ? "summary_large_image" : "summary",
+      ...title && { title },
+      ...description && { description },
+      ...options.image && { image: options.image }
+    },
+    extend: { meta }
+  };
+}
+
+export { checkSectionDefinition, defineSection, formatAceDate, sectionTypesPayload, seoDescriptionHandle, seoProperties, seoTitleHandle };

package/dist/{main-AGLPUGNN.js → main-JOA27GX6.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 }));
@@ -204,6 +197,8 @@ function starterEntries(framework, siteName) {
       title: "Home",
       description: `Welcome to ${siteName}.`,
       values: {
+        "seo-title": `${siteName} | Welcome`,
+        "seo-description": `Welcome to ${siteName}.`,
         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."
@@ -261,6 +256,8 @@ function starterEntries(framework, siteName) {
       title: "About",
       description: `About ${siteName}.`,
       values: {
+        "seo-title": `About | ${siteName}`,
+        "seo-description": `About ${siteName}.`,
         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."
@@ -278,6 +275,8 @@ function starterEntries(framework, siteName) {
       title: "Contact",
       description: `How to reach ${siteName}.`,
       values: {
+        "seo-title": `Contact | ${siteName}`,
+        "seo-description": `How to reach ${siteName}.`,
         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.
@@ -396,6 +395,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 +527,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 +566,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 +590,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 +620,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 +633,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 +652,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 +669,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 +681,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 +692,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 +742,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 +797,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":
@@ -1014,7 +1014,7 @@ async function loadSchemas(files, root, importModule) {
 var doctorUsage = `ace-kit doctor: check that this site is set up to work with CMS Ace.
 
 Usage:
-  ace-kit doctor [--site <domain>] [--api-url <address>] [--dir <folder>]
+  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
@@ -1023,7 +1023,6 @@ 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).
-  --api-url   Where the CMS Ace API lives (default: ACE_API_URL, else the hosted CMS Ace).
   --dir       The folder holding your *.schema.ts files (default: src and app).
   --help      Show this message.
 `;
@@ -1111,7 +1110,7 @@ async function doctorCommand(commandArguments, environment) {
   let apiUrl = null;
   try {
     apiUrl = normaliseApiUrl(values["api-url"] ?? environment.variables.ACE_API_URL ?? hostedApiUrl);
-    add("ok", `CMS: ${apiUrl}${apiUrl === hostedApiUrl ? " (the hosted CMS Ace)" : ""}`);
+    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)}`);
   }
@@ -1147,7 +1146,7 @@ async function doctorCommand(commandArguments, environment) {
       );
       return;
     }
-    add("ok", "The CMS answers");
+    add("ok", "CMS Ace answers");
     if (!siteDomain) return;
     const asSite = { "X-Ace-Site-Domain": siteDomain };
     const site = await request("/public/site", asSite);
@@ -1195,11 +1194,7 @@ async function doctorCommand(commandArguments, environment) {
       now: environment.now
     });
     if (!login) {
-      add(
-        "warn",
-        "Not signed in",
-        `Run: npx ace-kit login${isLocalApiUrl(address) ? ` --api-url ${address}` : ""}. Section sync and dev sites need it.`
-      );
+      add("warn", "Not signed in", `Run: ${loginCommandFor(address)}. Section sync and dev sites need it.`);
       return;
     }
     const authorised = { Authorization: `Bearer ${login.token}` };
@@ -1442,11 +1437,10 @@ 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.
 `;
@@ -1565,7 +1559,7 @@ 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 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
@@ -1575,9 +1569,8 @@ 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 and app).
   --help      Show this message.
 `;
@@ -1635,7 +1628,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);
@@ -1656,17 +1649,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":
@@ -1674,7 +1667,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;
   }
 }

package/dist/vite.js

@@ -1,4 +1,4 @@
-import { startDevSite, startSectionSync } from './chunk-T7DKI2U3.js';
+import { startDevSite, startSectionSync } from './chunk-2W2NWDKV.js';
 import './chunk-N5DIMG3X.js';
 import { resolve } from 'path';
 import { loadEnv } from 'vite';

package/docs/astro.md

@@ -15,21 +15,19 @@ export default defineConfig({
 });
 ```
 
-The integration declares three settings, adds the middleware that lets the CMS's admin app (and only it) frame the site for [live preview](./live-preview.md), and makes Vite process the kit. The settings are read when the server starts, not baked into the build, so one build runs anywhere:
+The integration declares the site's settings, adds the middleware that lets the CMS's admin app (and only it) frame the site for [live preview](./live-preview.md), and makes Vite process the kit. The settings are read when the server starts, not baked into the build, so one build runs anywhere:
 
-| Setting                    | Default                                              | Meaning                                                   |
-| -------------------------- | ---------------------------------------------------- | --------------------------------------------------------- |
-| `ACE_API_URL`              | `https://api.ace-cms.co.uk`                          | where the CMS Ace API lives                               |
-| `ACE_SITE_DOMAIN`          | the host of Astro's `site` setting, else `localhost` | the domain this site has in the CMS (the port is ignored) |
-| `ACE_PREVIEW_ADMIN_ORIGIN` | `https://app.ace-cms.co.uk`                          | where the CMS admin app runs                              |
+| Setting           | Default                                              | Meaning                                                   |
+| ----------------- | ---------------------------------------------------- | --------------------------------------------------------- |
+| `ACE_SITE_DOMAIN` | the host of Astro's `site` setting, else `localhost` | the domain this site has in the CMS (the port is ignored) |
 
-CMS Ace is a hosted platform, so a site normally sets none of these except its domain, and it does that with Astro's own `site` setting, which Astro needs for canonical addresses anyway:
+A site connects to CMS Ace by itself and only needs to say which site it is, which it does with Astro's own `site` setting, which Astro needs for canonical addresses anyway:
 
 ```js
 export default defineConfig({ site: "https://www.example.com", integrations: [ace()] });
 ```
 
-To try a site without editing the config, `npm run dev -- --site https://www.example.com` does the same. `ACE_SITE_DOMAIN`, when set, wins. Set `ACE_API_URL` and `ACE_PREVIEW_ADMIN_ORIGIN` (in `.env`) only to use a CMS running on your own machine, for example `http://localhost:8080` and `http://localhost:5173`.
+To try a site without editing the config, `npm run dev -- --site https://www.example.com` does the same. `ACE_SITE_DOMAIN`, when set, wins.
 
 ## Pages
 
@@ -94,6 +92,7 @@ import AcePreviewRefresh from "@sandboxsonny/ace-kit/astro/AcePreviewRefresh.ast
 - **AceLink** draws a link field as an `<a>` with the editor's words (or the address when there are none; put your own words in the slot to replace them). Nothing is drawn if the address can't be trusted, so check for a missing link yourself if you need a fallback. A date field is plain text: `formatAceDate(entry.values.published, { locale: "en-GB" })` gives "13 October 2026", and `<time datetime={entry.values.published}>` takes the raw value.
 - **AceRichText** draws a rich text field as HTML. It outputs bare elements (`h2`, `p`, `ul`, `a`...); style them from a wrapping element. Astro scopes styles, so reach them with `:global`, e.g. `.rich-text :global(h2) { ... }`.
 - **AceTextArea** draws a Textarea field (plain text): `multiline` (the default) makes paragraphs of blocks and a `<br>` of a new line; `multiline={false}` is one line of text with no element around it.
+- **AceSeo** goes in your layout's `<head>`: the page's `<title>`, description, canonical address, robots and Open Graph / Twitter tags, built on [astro-seo](https://github.com/jonasmerlin/astro-seo) (a site made by `ace-kit create` already depends on it; add `astro-seo` to a site you made by hand). Give it the entry and it uses the entry's SEO title and description (every content type has those two required fields), falling back to the entry's title and description, then to its own `title` and `description` props. Other props: `siteName` (ends the `<title>`, as "About us | Acme", and is the shared link's site name; leave it out if editors write the whole title), `canonical`, `image` (a full web address, for sharing) and `noindex` (set it for a draft shown in preview). On another framework, `seoProperties(options)` gives the same answer as plain data.
 - **AcePreviewRefresh** goes once in your layout. It does nothing unless the page was opened by the CMS's editor.
 - **AceNotice** is the message for a page that isn't an entry.
 

package/docs/command-line.md

@@ -12,7 +12,7 @@ npx ace-kit generate   # write TypeScript types (see Typed content)
 npx ace-kit sync       # send your section types to the CMS (see Sections)
 ```
 
-Commands talk to the hosted CMS Ace unless told otherwise. Only for a CMS on your own machine, give `--api-url`, or set `ACE_API_URL` in the environment or a `.env` file in the folder you run it in. Failing both, a command uses the address you last signed in to (kept in a small file beside your logins), and failing that the hosted one, so `ace-kit login` and `ace-kit whoami` need no flags at all. Commands about a site (`sync`, `generate`) take `--site example.com`, or read `ACE_SITE_DOMAIN`.
+Commands connect to CMS Ace for you, so `ace-kit login` and `ace-kit whoami` need no flags at all. Commands about a site (`sync`, `generate`, `doctor`) take `--site example.com`, or read `ACE_SITE_DOMAIN`.
 
 ## Making a site
 
@@ -36,9 +36,6 @@ Your account must be a **partner or super admin** (only they can make sites). Th
 | `<domain>` (or `--site <domain>`) | The domain the site has in CMS Ace. Required.                                         |
 | `--framework astro\|react-router` | `astro` (the default) or `react-router`. Both have the same three example sections.   |
 | `--name <name>`                   | The name shown to visitors. Default: made from the folder, so `my-site` is "My Site". |
-| `--api-url <address>`             | Only for a CMS on your own machine (or set `ACE_API_URL`).                            |
-
-Against a CMS on your own machine (`--api-url` or `ACE_API_URL` set to `http://localhost:8080`), it also writes a `.env` in the new folder with `ACE_API_URL` and `ACE_PREVIEW_ADMIN_ORIGIN=http://localhost:5173`, and sets the site's Preview address to the local dev server (`http://localhost:4321`, or 4322 for React Router), so the site and live preview work with no more setup. Against the hosted CMS Ace none of that is needed.
 
 The folder must not exist yet (or must be empty). The starter is a small server-rendered site with a header, footer, rich text, live preview and Prettier, ESLint, tests and a CI workflow. When it finishes: `cd my-site`, `npm install`, `npm run dev`.
 
@@ -64,7 +61,7 @@ Run it in your site's folder when something isn't working. It changes nothing, n
   ✓ The CMS has all of them
 ```
 
-It checks your Node version, that Ace Kit is installed, which CMS and site your settings point at, that the CMS can be reached and knows the site, that the site has its Pages content, that you are signed in, the site's preview address, and that the section types in your code match the CMS. `✗` is a problem (the command exits with 1), `!` is a warning, `-` is a note. It takes `--site`, `--api-url` and `--dir` like `sync`.
+It checks your Node version, that Ace Kit is installed, which CMS and site your settings point at, that the CMS can be reached and knows the site, that the site has its Pages content, that you are signed in, the site's preview address, and that the section types in your code match the CMS. `✗` is a problem (the command exits with 1), `!` is a warning, `-` is a note. It takes `--site` and `--dir` like `sync`.
 
 ## Signing in
 

package/docs/dev-sites.md

@@ -34,7 +34,7 @@ A dev site is never merged into the live site. When your change is ready, deploy
 
 ## If something stops it
 
-The dev server says so once, and carries on showing the **live site**, read-only, with section sync off: you aren't signed in (run `npx ace-kit login --api-url <address>`), your account can't have a dev site, the site isn't one you can see, or the CMS can't be reached.
+The dev server says so once, and carries on showing the **live site**, read-only, with section sync off: you aren't signed in (run `npx ace-kit login`), your account can't have a dev site, the site isn't one you can see, or the CMS can't be reached.
 
 ## Housekeeping
 

package/docs/getting-started.md

@@ -25,7 +25,7 @@ npm install @sandboxsonny/ace-kit
 | `@sandboxsonny/ace-kit`                                  | The framework-free core: the client, errors, `loadPage`, addressing, image attributes, menu helpers, rich text to HTML, preview helpers, all the types            |
 | `@sandboxsonny/ace-kit/astro/integration`                | The Astro integration: add it to `astro.config.mjs` and an Astro site is wired up                                                                                 |
 | `@sandboxsonny/ace-kit/astro`                            | What an Astro page calls: `getPage`, `getEntry`, `getEntries`, `getMenuLinks`, `getMenu`, `ace` (the client)                                                      |
-| `@sandboxsonny/ace-kit/astro/AceImage.astro` and friends | Astro components: `AceImage`, `AceRichText`, `AceMenu`, `AceNotice`, `AcePreviewRefresh`                                                                          |
+| `@sandboxsonny/ace-kit/astro/AceImage.astro` and friends | Astro components: `AceImage`, `AceRichText`, `AceSeo`, `AceMenu`, `AceNotice`, `AcePreviewRefresh`                                                                |
 | `@sandboxsonny/ace-kit/react`                            | `AceImage`, `AceRichText`, `usePreviewRefresh`                                                                                                                    |
 | `@sandboxsonny/ace-kit/react-router`                     | React Router 7, browser-safe: `AceRichText` (router links), `AceImage`, `AceNotice`, `createMeta`, `useAceMenu`, `useAcePreview`                                  |
 | `@sandboxsonny/ace-kit/react-router/server`              | React Router 7, server only: `createPageLoader`, `createRootLoader`, `handleRequest` (the server entry), `getEntry`, `getEntries`, `getMenuLinks`, `getAceClient` |

package/docs/react-router.md

@@ -26,13 +26,11 @@ export default defineConfig({ plugins: [ace(), reactRouter()] });
 
 The settings are environment variables, read when the server starts, so one build runs anywhere. Put them in `.env` for development and in the host's environment for production:
 
-| Variable                   | Default                     | Meaning                                                   |
-| -------------------------- | --------------------------- | --------------------------------------------------------- |
-| `ACE_API_URL`              | `https://api.ace-cms.co.uk` | where the CMS Ace API lives                               |
-| `ACE_SITE_DOMAIN`          | `localhost`                 | the domain this site has in the CMS (the port is ignored) |
-| `ACE_PREVIEW_ADMIN_ORIGIN` | `https://app.ace-cms.co.uk` | where the CMS admin app runs                              |
+| Variable          | Default     | Meaning                                                   |
+| ----------------- | ----------- | --------------------------------------------------------- |
+| `ACE_SITE_DOMAIN` | `localhost` | the domain this site has in the CMS (the port is ignored) |
 
-CMS Ace is a hosted platform, so a site normally sets only `ACE_SITE_DOMAIN`. Set the other two only to use a CMS on your own machine (`http://localhost:8080` and `http://localhost:5173`).
+A site connects to CMS Ace by itself and only needs to say which site it is, with `ACE_SITE_DOMAIN`.
 
 **2. The server entry**, which renders pages and lets the CMS's admin app (and only it) frame the site for [live preview](./live-preview.md):
 

package/docs/typed-content.md

@@ -12,7 +12,7 @@ or with the settings in the environment:
 ACE_SITE_DOMAIN=www.example.com npx ace-kit generate
 ```
 
-Add `--api-url http://localhost:8080` (or `ACE_API_URL`) only for a CMS on your own machine. It reads `GET /public/content-types` (no login: it describes field names and kinds, never entries) and writes `src/ace-kit.generated.d.ts` (change it with `--out`). Make sure the file is inside your `tsconfig` `include`. Commit it, and run the command again whenever content types change (a good moment is a CI step, or a `generate` script next to `dev`).
+It reads `GET /public/content-types` (no login: it describes field names and kinds, never entries) and writes `src/ace-kit.generated.d.ts` (change it with `--out`). Make sure the file is inside your `tsconfig` `include`. Commit it, and run the command again whenever content types change (a good moment is a CI step, or a `generate` script next to `dev`).
 
 ```ts
 // ace-kit.generated.d.ts (generated)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxsonny/ace-kit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Everything a website needs to use CMS Ace: a typed client, addressing, images, menus, rich text, live preview, and Astro and React adapters.",
   "keywords": [
     "cms",
@@ -105,7 +105,8 @@
     "react-router": ">=7",
     "react-dom": ">=18",
     "@react-router/node": ">=7",
-    "vite": ">=5"
+    "vite": ">=5",
+    "astro-seo": ">=1"
   },
   "peerDependenciesMeta": {
     "astro": {
@@ -125,6 +126,9 @@
     },
     "vite": {
       "optional": true
+    },
+    "astro-seo": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -139,6 +143,7 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "astro": "^7.3.8",
+    "astro-seo": "^1.2.0",
     "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-astro": "^1.7.0",

package/templates/astro/package.json

@@ -21,8 +21,9 @@
   },
   "dependencies": {
     "@astrojs/node": "^11.1.7",
-    "@sandboxsonny/ace-kit": "^0.5.0",
-    "astro": "^7.3.8"
+    "@sandboxsonny/ace-kit": "file:../ace-kit/sandboxsonny-ace-kit-0.7.0.tgz",
+    "astro": "^7.3.8",
+    "astro-seo": "^1.2.0"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",

package/templates/astro/src/ace-kit.generated.d.ts

@@ -17,6 +17,10 @@ declare module "@sandboxsonny/ace-kit" {
       "button"?: AceLinkData;
       /** Content */
       "content"?: AceSection[];
+      /** SEO title */
+      "seo-title": string;
+      /** SEO description */
+      "seo-description": string;
     };
   }
 }

package/templates/astro/src/layouts/BaseLayout.astro

@@ -1,17 +1,22 @@
 ---
 import AcePreviewRefresh from "@sandboxsonny/ace-kit/astro/AcePreviewRefresh.astro";
+import AceSeo from "@sandboxsonny/ace-kit/astro/AceSeo.astro";
+import type { AceEntry } from "@sandboxsonny/ace-kit";
 import SiteFooter from "~/components/SiteFooter.astro";
 import SiteHeader from "~/components/SiteHeader.astro";
 import "~/styles/global.css";
 
 type Props = {
+  /** The entry the page shows: its SEO title and description fill the page's search and sharing tags. */
+  entry?: AceEntry;
+  /** Used when there is no entry (a notice page), and when an entry has no title of its own. */
   title: string;
   description?: string;
   /** True when the page is showing a draft inside the CMS's preview frame. */
   preview?: boolean;
 };
 
-const { title, description = "A simple example site for testing CMS Ace.", preview = false } = Astro.props;
+const { entry, title, description = "A simple example site for testing CMS Ace.", preview = false } = Astro.props;
 ---
 
 <!doctype html>
@@ -19,11 +24,17 @@ const { title, description = "A simple example site for testing CMS Ace.", previ
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="description" content={description} />
     <meta name="generator" content={Astro.generator} />
-    {preview && <meta name="robots" content="noindex" />}
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <title>{title}</title>
+    {/* Title, description, canonical address, robots and sharing tags. A draft shown in preview is kept out of search. */}
+    <AceSeo
+      entry={entry}
+      {title}
+      {description}
+      siteName="Example Site"
+
+      noindex={preview}
+    />
   </head>
   <body>
     <SiteHeader />

package/templates/astro/src/pages/[...slug].astro

@@ -15,11 +15,7 @@ const isPreview = Boolean(page.headers["Cache-Control"]);
 ---
 
 {page.kind === "entry" ? (
-  <BaseLayout
-    title={`${page.entry.title} | Example Site`}
-    description={page.entry.description || undefined}
-    preview={isPreview}
-  >
+  <BaseLayout entry={page.entry} title={page.entry.title} preview={isPreview}>
     <PageContent entry={page.entry} />
   </BaseLayout>
 ) : (