@sandboxsonny/ace-kit 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @sandboxsonny/ace-kit
 
+## 0.3.0
+
+### Minor Changes
+
+- a9d7700: `ace-kit login`, `ace-kit logout` and `ace-kit whoami`: sign in to CMS Ace from the command line.
+  
+  `ace-kit login` uses the OAuth device flow: the terminal shows a short code and opens the admin app, where you type the code and approve it. No password goes into the terminal. The login is kept in the macOS Keychain, or in a file only you can read on other systems, and is what the dev-server sync for sections will use. It can do much less than a browser login and ends after 30 days unused. Needs a CMS Ace API with command-line sign-in (its migration 00020). Set `ACE_TOKEN` to use a token instead (for a build server).
+  
+  `ace-kit generate` is unchanged.
+
+## 0.2.0
+
+### Minor Changes
+
+- 801266d: Support for the CMS's new Date and Link field types.
+  
+  - `ace-kit generate` types a Date field as `string` (a day written `YYYY-MM-DD`) and a Link field as the new `AceLinkData` (`{ href, label? }`). Before, both were `unknown`.
+  - `AceLink` draws a link field: `AceLink.astro` for Astro, `AceLink` from `@sandboxsonny/ace-kit/react`, and a version from `@sandboxsonny/ace-kit/react-router` that uses the router's `Link` for pages of the site. It shows the editor's words, or yours as children, and draws nothing for an address that can't be trusted.
+  - `linkAttributes(link)` is what those components use, for sites that draw links their own way.
+  - `formatAceDate(date, format?)` turns a Date field's day into words in any language, and never shifts the day with the server's time zone.
+  
+  Needs a CMS Ace API with the Date and Link field types (the API's migration 00018). Against an older API nothing changes.
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -51,6 +51,7 @@ const about = await getEntry("pages", "about");
 | [React](docs/react.md)                     | Components for any React framework           |
 | [Live preview](docs/live-preview.md)       | What a site must do for the editor's preview |
 | [Typed content](docs/typed-content.md)     | `ace-kit generate`                           |
+| [The command line](docs/command-line.md)   | `ace-kit login`, `logout`, `whoami`          |
 | [Rich text](docs/rich-text.md)             | The document format and how it is drawn      |
 | [API reference](docs/api-reference.md)     | Every export                                 |
 | [Releasing](docs/releasing.md)             | Versions, the changelog and publishing       |

package/astro/AceLink.astro

@@ -0,0 +1,20 @@
+---
+import { linkAttributes } from "../dist/index.js";
+import type { AceLinkData } from "../dist/index.js";
+
+type Props = {
+  /** A link field's value: `entry.values.button`. */
+  link: AceLinkData;
+  class?: string;
+};
+
+const { link, class: className } = Astro.props;
+const attributes = linkAttributes(link);
+const hasContent = Astro.slots.has("default");
+---
+
+{attributes && (
+  <a href={attributes.href} class={className}>
+    {hasContent ? <slot /> : (attributes.label ?? attributes.href)}
+  </a>
+)}

package/dist/astro.d.ts

@@ -2,7 +2,7 @@
 type AceFieldSchema = {
   handle: string;
   label: string;
-  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image` or `richtext`. */
+  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image`, `richtext`, `date` or `link`. */
   component_key: string;
   config: { required?: boolean; options?: string[] } | null;
 };

package/dist/{chunk-KEV3YAWN.js → chunk-2MXND4HG.js}

@@ -1,4 +1,4 @@
-import { imageAttributes, textAreaSingleLine, textAreaParagraphs, textAreaLines, richTextImageSizes, listStart, headingLevel, linkAddress } from './chunk-URLKW2YS.js';
+import { imageAttributes, linkAttributes, textAreaSingleLine, textAreaParagraphs, textAreaLines, richTextImageSizes, listStart, headingLevel, linkAddress } from './chunk-FVR55GIU.js';
 import { listenForPreviewRefresh } from './chunk-YN7LJWGI.js';
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import { Fragment as Fragment$1, useEffect } from 'react';
@@ -7,7 +7,13 @@ function AceImage({ image, sizes, lazy, ...rest }) {
   const attributes = imageAttributes(image, { sizes, lazy });
   return /* @__PURE__ */ jsx("img", { ...rest, ...attributes });
 }
-var PlainLink = ({ href, children }) => /* @__PURE__ */ jsx("a", { href, children });
+var PlainLink = ({ href, children, className }) => /* @__PURE__ */ jsx("a", { href, className, children });
+function AceLink({ link, children, className, as: Link = PlainLink }) {
+  const attributes = linkAttributes(link);
+  if (!attributes) return null;
+  return /* @__PURE__ */ jsx(Link, { href: attributes.href, className, children: children ?? attributes.label ?? attributes.href });
+}
+var PlainLink2 = ({ href, children }) => /* @__PURE__ */ jsx("a", { href, children });
 function renderText(node, Link) {
   return (node.marks ?? []).reduce((inner, mark) => {
     if (mark.type === "bold") return /* @__PURE__ */ jsx("strong", { children: inner });
@@ -46,7 +52,7 @@ function Node({ node, Link }) {
       return null;
   }
 }
-function AceRichText({ document, link = PlainLink }) {
+function AceRichText({ document, link = PlainLink2 }) {
   return /* @__PURE__ */ jsx(Fragment, { children: renderNodes(document.content, link) });
 }
 function AceTextArea({ value, multiline = true }) {
@@ -63,4 +69,4 @@ function usePreviewRefresh(adminOrigin, refresh) {
   }, [adminOrigin, refresh]);
 }
 
-export { AceImage, AceRichText, AceTextArea, usePreviewRefresh };
+export { AceImage, AceLink, AceRichText, AceTextArea, usePreviewRefresh };

package/dist/{chunk-URLKW2YS.js → chunk-FVR55GIU.js}

@@ -26,6 +26,10 @@ function linkAddress(address) {
 function isInternalPath(address) {
   return address.startsWith("/") && !address.startsWith("//");
 }
+function linkAttributes(link) {
+  const href = linkAddress(link.href);
+  return href ? { href, label: link.label ? link.label : null } : null;
+}
 
 // src/helpers/text-area.ts
 var escapes = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
@@ -104,4 +108,4 @@ function renderRichText(document) {
   return (document.content ?? []).map(renderNode).join("");
 }
 
-export { headingLevel, imageAttributes, isInternalPath, linkAddress, listStart, renderRichText, renderTextArea, richTextImageSizes, textAreaLines, textAreaParagraphs, textAreaSingleLine };
+export { headingLevel, imageAttributes, isInternalPath, linkAddress, linkAttributes, listStart, renderRichText, renderTextArea, richTextImageSizes, textAreaLines, textAreaParagraphs, textAreaSingleLine };

package/dist/cli.js

@@ -1,8 +1,233 @@
 #!/usr/bin/env node
 
-// src/generate/cli.ts
-import { mkdir, writeFile } from "fs/promises";
-import { dirname, resolve } from "path";
+// src/cli/environment.ts
+import { spawn } from "child_process";
+import { hostname } from "os";
+
+// src/auth/file-store.ts
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+// src/auth/login-store.ts
+function normaliseApiUrl(address) {
+  let parsed;
+  try {
+    parsed = new URL(address.trim());
+  } catch {
+    throw new Error(`"${address}" is not a web address. Write the API address like http://localhost:8080.`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`The API address must start with http:// or https:// (it was "${address}").`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error("The API address must not contain a username or password.");
+  }
+  return `${parsed.origin}${parsed.pathname.replace(/\/+$/, "")}`;
+}
+function hasExpired(login, now) {
+  const endsAt = Date.parse(login.expiresAt);
+  return Number.isNaN(endsAt) || endsAt <= now;
+}
+function parseStoredLogin(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const { token, expiresAt, email } = value;
+  if (typeof token !== "string" || token === "" || typeof expiresAt !== "string" || typeof email !== "string")
+    return null;
+  return { token, expiresAt, email };
+}
+
+// src/auth/file-store.ts
+function defaultLoginFile(variables, platform) {
+  if (platform === "win32" && variables.APPDATA) return join(variables.APPDATA, "ace-kit", "credentials.json");
+  const configFolder = variables.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(configFolder, "ace-kit", "credentials.json");
+}
+function createFileStore(path) {
+  async function readAll() {
+    let text;
+    try {
+      text = await readFile(path, "utf8");
+    } catch {
+      return {};
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return {};
+    }
+    const found = {};
+    if (typeof parsed === "object" && parsed !== null) {
+      for (const [address, value] of Object.entries(parsed)) {
+        const login = parseStoredLogin(value);
+        if (login) found[address] = login;
+      }
+    }
+    return found;
+  }
+  async function writeAll(logins) {
+    await mkdir(dirname(path), { recursive: true, mode: 448 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(logins, null, 2)}
+`, { mode: 384 });
+    await rename(temporary, path);
+  }
+  return {
+    description: path,
+    async read(apiUrl) {
+      return (await readAll())[normaliseApiUrl(apiUrl)] ?? null;
+    },
+    async write(apiUrl, login) {
+      const logins = await readAll();
+      logins[normaliseApiUrl(apiUrl)] = login;
+      await writeAll(logins);
+    },
+    async remove(apiUrl) {
+      const logins = await readAll();
+      delete logins[normaliseApiUrl(apiUrl)];
+      await writeAll(logins);
+    }
+  };
+}
+
+// src/auth/keychain-store.ts
+var keychainService = "ace-kit";
+function createKeychainStore(run) {
+  async function read(apiUrl) {
+    const found = await run("security", [
+      "find-generic-password",
+      "-s",
+      keychainService,
+      "-a",
+      normaliseApiUrl(apiUrl),
+      "-w"
+    ]);
+    if (found.exitCode !== 0) return null;
+    try {
+      return parseStoredLogin(JSON.parse(Buffer.from(found.stdout.trim(), "base64").toString("utf8")));
+    } catch {
+      return null;
+    }
+  }
+  return {
+    description: "the macOS Keychain",
+    read,
+    async write(apiUrl, login) {
+      const account = normaliseApiUrl(apiUrl);
+      if (/["\\\s]/.test(account)) throw new Error("That API address can't be kept in the Keychain.");
+      const secret = Buffer.from(JSON.stringify(login), "utf8").toString("base64");
+      await run(
+        "security",
+        ["-i"],
+        `add-generic-password -s "${keychainService}" -a "${account}" -l "Ace Kit login" -w "${secret}" -U
+`
+      );
+      const kept = await read(apiUrl);
+      if (kept?.token !== login.token) throw new Error("The login could not be saved in the macOS Keychain.");
+    },
+    async remove(apiUrl) {
+      await run("security", ["delete-generic-password", "-s", keychainService, "-a", normaliseApiUrl(apiUrl)]);
+    }
+  };
+}
+
+// src/auth/choose-store.ts
+async function chooseLoginStore(options) {
+  const file = createFileStore(defaultLoginFile(options.variables, options.platform));
+  if (options.platform !== "darwin" || options.variables.ACE_KIT_CREDENTIALS === "file") return file;
+  try {
+    await options.run("security", ["help"]);
+    return createKeychainStore(options.run);
+  } catch {
+    return file;
+  }
+}
+
+// src/auth/last-api-url.ts
+import { mkdir as mkdir2, readFile as readFile2, rename as rename2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join as join2 } from "path";
+function defaultLastApiUrlFile(variables, platform) {
+  return join2(dirname2(defaultLoginFile(variables, platform)), "last-api-url");
+}
+function createLastApiUrl(path) {
+  return {
+    async read() {
+      try {
+        return normaliseApiUrl((await readFile2(path, "utf8")).trim());
+      } catch {
+        return null;
+      }
+    },
+    async write(apiUrl) {
+      await mkdir2(dirname2(path), { recursive: true, mode: 448 });
+      const temporary = `${path}.${process.pid}.tmp`;
+      await writeFile2(temporary, `${normaliseApiUrl(apiUrl)}
+`, { mode: 384 });
+      await rename2(temporary, path);
+    }
+  };
+}
+
+// src/cli/version.ts
+var aceKitVersion = true ? "0.3.0" : "development";
+
+// src/cli/environment.ts
+var runCommand = (command, commandArguments, input) => new Promise((resolve2, reject) => {
+  const child = spawn(command, commandArguments, { stdio: ["pipe", "pipe", "ignore"] });
+  let stdout = "";
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk.toString("utf8");
+  });
+  child.on("error", reject);
+  child.on("close", (exitCode) => resolve2({ exitCode: exitCode ?? 1, stdout }));
+  child.stdin.on("error", () => {
+  });
+  child.stdin.end(input ?? "");
+});
+function browserCommand(platform, address) {
+  if (platform === "darwin") return { command: "open", commandArguments: [address] };
+  if (platform === "win32") return { command: "rundll32", commandArguments: ["url.dll,FileProtocolHandler", address] };
+  return { command: "xdg-open", commandArguments: [address] };
+}
+async function openBrowser(platform, address) {
+  const { command, commandArguments } = browserCommand(platform, address);
+  await new Promise((resolve2) => {
+    const child = spawn(command, commandArguments, { stdio: "ignore", detached: true });
+    child.on("error", () => resolve2());
+    child.on("spawn", () => {
+      child.unref();
+      resolve2();
+    });
+  });
+}
+async function createRealEnvironment() {
+  try {
+    process.loadEnvFile(".env");
+  } catch {
+  }
+  const variables = { ...process.env };
+  const platform = process.platform;
+  return {
+    variables,
+    platform,
+    hostname: hostname(),
+    version: aceKitVersion,
+    out: (text) => process.stdout.write(`${text}
+`),
+    error: (text) => console.error(text),
+    fetchImplementation: (input, init) => fetch(input, init),
+    sleep: (milliseconds) => new Promise((resolve2) => setTimeout(resolve2, milliseconds)),
+    now: Date.now,
+    openBrowser: (address) => openBrowser(platform, address),
+    store: await chooseLoginStore({ platform, variables, run: runCommand }),
+    lastApiUrl: createLastApiUrl(defaultLastApiUrlFile(variables, platform))
+  };
+}
+
+// src/cli/generate-command.ts
+import { mkdir as mkdir3, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname3, resolve } from "path";
 import { parseArgs } from "util";
 
 // src/client/errors.ts
@@ -119,6 +344,10 @@ function typeOfField(field) {
       return { type: "AceImageData", uses: "AceImageData" };
     case "richtext":
       return { type: "AceRichTextDocument", uses: "AceRichTextDocument" };
+    case "date":
+      return { type: "string" };
+    case "link":
+      return { type: "AceLinkData", uses: "AceLinkData" };
     default:
       return { type: "unknown" };
   }
@@ -156,8 +385,8 @@ export {};
 // src/helpers/package-name.ts
 var packageName = "@sandboxsonny/ace-kit";
 
-// src/generate/cli.ts
-var usage = `ace-kit generate: write TypeScript types for your CMS Ace content types.
+// src/cli/generate-command.ts
+var generateUsage = `ace-kit generate: write TypeScript types for your CMS Ace content types.
 
 Usage:
   ace-kit generate [--api-url <address>] [--domain <domain>] [--out <file>]
@@ -168,13 +397,10 @@ Options:
   --out       Where to write the types (default: src/ace-kit.generated.d.ts).
   --help      Show this message.
 `;
-async function main() {
-  try {
-    process.loadEnvFile(".env");
-  } catch {
-  }
-  const { positionals, values } = parseArgs({
-    allowPositionals: true,
+async function generateCommand(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" },
       domain: { type: "string" },
@@ -182,27 +408,365 @@ async function main() {
       help: { type: "boolean" }
     }
   });
-  if (values.help || positionals[0] !== "generate") {
-    console.log(usage);
-    return values.help ? 0 : 1;
+  if (values.help) {
+    environment.out(generateUsage);
+    return 0;
   }
-  const apiUrl = values["api-url"] ?? process.env.ACE_API_URL;
-  const siteDomain = values.domain ?? process.env.ACE_SITE_DOMAIN;
+  const apiUrl = values["api-url"] ?? environment.variables.ACE_API_URL;
+  const siteDomain = values.domain ?? environment.variables.ACE_SITE_DOMAIN;
   if (!apiUrl || !siteDomain) {
-    console.error(
+    environment.error(
       "Give the API address and the site's domain: --api-url and --domain, or ACE_API_URL and ACE_SITE_DOMAIN."
     );
     return 1;
   }
-  const client = createAceClient({ apiUrl, siteDomain, cacheSeconds: 0 });
+  const client = createAceClient({
+    apiUrl,
+    siteDomain,
+    cacheSeconds: 0,
+    fetchImplementation: environment.fetchImplementation
+  });
   const contentTypes = await client.getContentTypes();
   const file = resolve(values.out ?? "src/ace-kit.generated.d.ts");
-  await mkdir(dirname(file), { recursive: true });
-  await writeFile(file, generateTypes(contentTypes, packageName, siteDomain));
-  console.log(`Wrote types for ${contentTypes.length} content type${contentTypes.length === 1 ? "" : "s"} to ${file}.`);
+  await mkdir3(dirname3(file), { recursive: true });
+  await writeFile3(file, generateTypes(contentTypes, packageName, siteDomain));
+  environment.out(
+    `Wrote types for ${contentTypes.length} content type${contentTypes.length === 1 ? "" : "s"} to ${file}.`
+  );
   return 0;
 }
-main().then(
+
+// src/cli/login-commands.ts
+import { parseArgs as parseArgs2 } 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/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/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 } = parseArgs2({
+    // 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 address = values["api-url"] ?? environment.variables.ACE_API_URL ?? await environment.lastApiUrl.read();
+  if (!address) {
+    environment.error(
+      "Give the API address: --api-url, or ACE_API_URL in the environment or a .env file. (Once you have signed in, that address is remembered.)"
+    );
+    return null;
+  }
+  try {
+    return { apiUrl: normaliseApiUrl(address) };
+  } catch (error) {
+    environment.error(error instanceof Error ? error.message : String(error));
+    return null;
+  }
+}
+function webAddress(address) {
+  try {
+    const parsed = new URL(address);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.href : null;
+  } catch {
+    return null;
+  }
+}
+var isLocal = (apiUrl) => ["localhost", "127.0.0.1", "[::1]"].includes(new URL(apiUrl).hostname);
+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://") && !isLocal(apiUrl)) {
+    environment.error(
+      `Warning: ${apiUrl} is not encrypted (http://), so the login could be read on the way. Use https:// if you can.`
+    );
+  }
+  try {
+    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 0;
+  } catch (error) {
+    environment.error(`
+${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+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/main.ts
+var usage = `ace-kit: tools for sites built on CMS Ace.
+
+Commands:
+  ace-kit generate   Write TypeScript types for your content types.
+  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 "generate":
+      return generateCommand(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;
+  }
+}
+
+// src/cli/bin.ts
+createRealEnvironment().then((environment) => runCli(process.argv.slice(2), environment)).then(
   (code) => process.exit(code),
   (error) => {
     console.error(error instanceof Error ? error.message : error);

package/dist/index.d.ts

@@ -13,7 +13,7 @@ type AceClientOptions = {
 type AceFieldSchema = {
   handle: string;
   label: string;
-  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image` or `richtext`. */
+  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image`, `richtext`, `date` or `link`. */
   component_key: string;
   config: { required?: boolean; options?: string[] } | null;
 };
@@ -178,6 +178,25 @@ type AceImageAttributes = {
 /** What to put on an `<img>`: a web-sized `src`, `srcset` when there are copies, and the size so the page doesn't jump. */
 declare function imageAttributes(image: AceImageData, { sizes, lazy }: AceImageOptions): AceImageAttributes;
 
+type AceDateFormat = Intl.DateTimeFormatOptions & {
+    /** A language such as "en-GB". The default is the one the server or browser runs in. */
+    locale?: string;
+};
+/**
+ * A date field's day (a text such as "2026-10-13") as words, or null if it isn't a real day. A date field holds a
+ * day with no time of day, so this never shifts it with a time zone: 13 October is 13 October everywhere.
+ */
+declare function formatAceDate(date: string, format?: AceDateFormat): string | null;
+
+/**
+ * What a link field holds in an entry's values, as visitors get it: where it goes, already worked out (a link to a
+ * page of the site is its address, such as "/pages/about"), and the words it is shown with, if the editor gave any.
+ */
+type AceLinkData = {
+  href: string;
+  label?: string;
+};
+
 /**
  * Where a link in rich text goes, or null if it can't be trusted. The CMS only allows paths, web addresses,
  * mailto: and tel:; this checks again so the page stays safe even if something else ever gets into the text.
@@ -185,6 +204,16 @@ declare function imageAttributes(image: AceImageData, { sizes, lazy }: AceImageO
 declare function linkAddress(address: string): string | null;
 /** Whether a link stays on this site: a path such as "/pages/about", not "//elsewhere", "https://..." or "mailto:...". */
 declare function isInternalPath(address: string): boolean;
+/** What to draw for a link field: where it goes and its words (null when the editor gave none). */
+type AceLinkAttributes = {
+    href: string;
+    label: string | null;
+};
+/**
+ * What a link field's value is drawn with, or null if its address can't be trusted. The CMS only allows paths, web
+ * addresses, mailto: and tel:; this checks again so the page stays safe even if something else ever gets into the data.
+ */
+declare function linkAttributes(link: AceLinkData): AceLinkAttributes | null;
 
 /** A CMS menu as links ready to draw. An entry link to the home entry goes to "/" so it isn't a redirect. */
 declare function linksFromMenu(menu: AceMenu): AceNavigationLink[];
@@ -308,4 +337,4 @@ declare const listStart: (node: AceRichTextNode) => number | undefined;
  */
 declare function renderRichText(document: AceRichTextDocument): string;
 
-export { type AceAddress, type AceClient, type AceClientOptions, type AceContentTypeHandle, type AceContentTypeSchema, type AceContentTypes, type AceEntry, type AceFieldSchema, type AceImageAttributes, type AceImageData, type AceImageOptions, type AceMenu, type AceMenuItem, type AceNavigationLink, type AcePage, AcePreviewExpiredError, type AceRichTextDocument, type AceRichTextMark, type AceRichTextNode, AceUnavailableError, type AceValuesOf, addFramingPolicy, addressFromPath, createAceClient, framingPolicy, headingLevel, homeAddress, imageAttributes, isCurrentPage, isHomeAddress, isInternalPath, isRefreshRequest, linkAddress, linksFromMenu, listStart, listenForPreviewRefresh, loadMenuLinks, loadPage, originOf, pageNotices, pathOfAddress, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, refreshPageContent, renderRichText, renderTextArea, richTextImageSizes, 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, AceUnavailableError, type AceValuesOf, addFramingPolicy, addressFromPath, createAceClient, 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, swapPageContent, visitablePath };

package/dist/index.js

@@ -1,6 +1,24 @@
 export { pageNotices } from './chunk-XPZY5R5A.js';
-export { headingLevel, imageAttributes, isInternalPath, linkAddress, listStart, renderRichText, renderTextArea, richTextImageSizes } from './chunk-URLKW2YS.js';
+export { headingLevel, imageAttributes, isInternalPath, linkAddress, linkAttributes, listStart, renderRichText, renderTextArea, richTextImageSizes } from './chunk-FVR55GIU.js';
 export { listenForPreviewRefresh, refreshPageContent } from './chunk-YN7LJWGI.js';
 export { AcePreviewExpiredError, AceUnavailableError, createAceClient, isCurrentPage, linksFromMenu, loadMenuLinks, loadPage } from './chunk-XYOW63V6.js';
 export { addressFromPath, homeAddress, isHomeAddress, pathOfAddress, visitablePath } from './chunk-M5WR5TCR.js';
 export { addFramingPolicy, framingPolicy, isRefreshRequest, originOf, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, swapPageContent } from './chunk-YLO6IAXF.js';
+
+// src/helpers/dates.ts
+var defaultFormat = { dateStyle: "long" };
+function formatAceDate(date, format = {}) {
+  const parts = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+  if (!parts) return null;
+  const [year, month, day] = [Number(parts[1]), Number(parts[2]), Number(parts[3])];
+  const moment = new Date(Date.UTC(year, month - 1, day));
+  if (moment.getUTCFullYear() !== year || moment.getUTCMonth() !== month - 1 || moment.getUTCDate() !== day)
+    return null;
+  const { locale, ...options } = format;
+  return new Intl.DateTimeFormat(locale, {
+    ...Object.keys(options).length > 0 ? options : defaultFormat,
+    timeZone: "UTC"
+  }).format(moment);
+}
+
+export { formatAceDate };

package/dist/react-router-server.d.ts

@@ -75,7 +75,7 @@ type AceClientOptions = {
 type AceFieldSchema = {
   handle: string;
   label: string;
-  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image` or `richtext`. */
+  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image`, `richtext`, `date` or `link`. */
   component_key: string;
   config: { required?: boolean; options?: string[] } | null;
 };

package/dist/react-router.d.ts

@@ -29,6 +29,25 @@ type AceImageProps = AceImageOptions & {
 /** An image from the CMS as an `<img>` with a web-sized `src`, `srcset`, its size and its alt text. */
 declare function AceImage({ image, sizes, lazy, ...rest }: AceImageProps): react.JSX.Element;
 
+/**
+ * What a link field holds in an entry's values, as visitors get it: where it goes, already worked out (a link to a
+ * page of the site is its address, such as "/pages/about"), and the words it is shown with, if the editor gave any.
+ */
+type AceLinkData = {
+  href: string;
+  label?: string;
+};
+
+/**
+ * A link field, drawn with React Router's `Link` for a page of this site. Everything else is as `AceLink` from
+ * `@sandboxsonny/ace-kit/react`: its words by default, nothing drawn for an address that can't be trusted.
+ */
+declare function AceLink({ link, children, className, }: {
+    link: AceLinkData;
+    children?: React.ReactNode;
+    className?: string;
+}): react.JSX.Element;
+
 type AceTextAreaProps = {
     /** The text area field's value. Missing or blank draws nothing. */
     value: string | undefined;
@@ -152,4 +171,4 @@ type AceRootData = {
   };
 };
 
-export { AceImage, AceNotice, AceRichText, type AceRootData, AceTextArea, createMeta, meta, useAceMenu, useAcePreview };
+export { AceImage, AceLink, AceNotice, AceRichText, type AceRootData, AceTextArea, createMeta, meta, useAceMenu, useAcePreview };

package/dist/react-router.js

@@ -1,14 +1,22 @@
 import { pageNotices } from './chunk-XPZY5R5A.js';
-import { AceRichText, usePreviewRefresh } from './chunk-KEV3YAWN.js';
-export { AceImage, AceTextArea } from './chunk-KEV3YAWN.js';
-import { isInternalPath } from './chunk-URLKW2YS.js';
+import { AceLink, AceRichText, usePreviewRefresh } from './chunk-2MXND4HG.js';
+export { AceImage, AceTextArea } from './chunk-2MXND4HG.js';
+import { isInternalPath } from './chunk-FVR55GIU.js';
 import './chunk-YN7LJWGI.js';
 import './chunk-M5WR5TCR.js';
 import './chunk-YLO6IAXF.js';
 import { Link, useRevalidator, useRouteLoaderData } from 'react-router';
-import { jsxs, jsx } from 'react/jsx-runtime';
+import { jsx, jsxs } from 'react/jsx-runtime';
 import { useCallback } from 'react';
 
+var RouterLink = ({ href, children, className }) => isInternalPath(href) ? /* @__PURE__ */ jsx(Link, { to: href, className, children }) : /* @__PURE__ */ jsx("a", { href, className, children });
+function AceLink2({
+  link,
+  children,
+  className
+}) {
+  return /* @__PURE__ */ jsx(AceLink, { link, className, as: RouterLink, children });
+}
 function AceNotice({ page, className }) {
   const { heading, message } = pageNotices[page.kind];
   return /* @__PURE__ */ jsxs("div", { className, children: [
@@ -17,9 +25,9 @@ function AceNotice({ page, className }) {
     page.kind === "preview-expired" ? null : /* @__PURE__ */ jsx(Link, { to: "/", children: "Back to the home page" })
   ] });
 }
-var RouterLink = ({ href, children }) => isInternalPath(href) ? /* @__PURE__ */ jsx(Link, { to: href, children }) : /* @__PURE__ */ jsx("a", { href, children });
+var RouterLink2 = ({ href, children }) => isInternalPath(href) ? /* @__PURE__ */ jsx(Link, { to: href, children }) : /* @__PURE__ */ jsx("a", { href, children });
 function AceRichText2({ document }) {
-  return /* @__PURE__ */ jsx(AceRichText, { document, link: RouterLink });
+  return /* @__PURE__ */ jsx(AceRichText, { document, link: RouterLink2 });
 }
 
 // src/react-router/meta.ts
@@ -52,4 +60,4 @@ function useAcePreview() {
   usePreviewRefresh(useAceRootData()?.previewAdminOrigin, refresh);
 }
 
-export { AceNotice, AceRichText2 as AceRichText, createMeta, meta, useAceMenu, useAcePreview };
+export { AceLink2 as AceLink, AceNotice, AceRichText2 as AceRichText, createMeta, meta, useAceMenu, useAcePreview };

package/dist/react.d.ts

@@ -29,6 +29,15 @@ type AceImageProps = AceImageOptions & {
 /** An image from the CMS as an `<img>` with a web-sized `src`, `srcset`, its size and its alt text. */
 declare function AceImage({ image, sizes, lazy, ...rest }: AceImageProps): react.JSX.Element;
 
+/**
+ * What a link field holds in an entry's values, as visitors get it: where it goes, already worked out (a link to a
+ * page of the site is its address, such as "/pages/about"), and the words it is shown with, if the editor gave any.
+ */
+type AceLinkData = {
+  href: string;
+  label?: string;
+};
+
 /** A mark on a piece of text. A link's address is already worked out: an entry link comes as its path. */
 type AceRichTextMark = { type: "bold" } | { type: "italic" } | { type: "link"; attrs: { href: string } };
 
@@ -51,6 +60,7 @@ type AceRichTextDocument = { type: "doc"; content?: AceRichTextNode[] };
 type AceRichTextLink = ComponentType<{
     href: string;
     children: ReactNode;
+    className?: string;
 }>;
 type AceRichTextProps = {
     document: AceRichTextDocument;
@@ -63,6 +73,18 @@ type AceRichTextProps = {
  */
 declare function AceRichText({ document, link }: AceRichTextProps): react.JSX.Element;
 
+type AceLinkProps = {
+    /** A link field's value: `entry.values.button`. */
+    link: AceLinkData;
+    /** What to show instead of the editor's words, which are the default (or the address when there are none). */
+    children?: ReactNode;
+    className?: string;
+    /** Draws the link; the default is a plain `<a>`. Give one that uses your router's link to keep navigation client-side. */
+    as?: AceRichTextLink;
+};
+/** A link field, drawn as a link. Nothing is drawn if the address can't be trusted. */
+declare function AceLink({ link, children, className, as: Link }: AceLinkProps): react.JSX.Element | null;
+
 type AceTextAreaProps = {
     /** The text area field's value. Missing or blank draws nothing. */
     value: string | undefined;
@@ -85,4 +107,4 @@ declare function AceTextArea({ value, multiline }: AceTextAreaProps): react.JSX.
  */
 declare function usePreviewRefresh(adminOrigin: string | null | undefined, refresh?: () => Promise<void>): void;
 
-export { AceImage, AceRichText, type AceRichTextLink, AceTextArea, usePreviewRefresh };
+export { AceImage, AceLink, AceRichText, type AceRichTextLink, AceTextArea, usePreviewRefresh };

package/dist/react.js

@@ -1,5 +1,5 @@
-export { AceImage, AceRichText, AceTextArea, usePreviewRefresh } from './chunk-KEV3YAWN.js';
-import './chunk-URLKW2YS.js';
+export { AceImage, AceLink, AceRichText, AceTextArea, usePreviewRefresh } from './chunk-2MXND4HG.js';
+import './chunk-FVR55GIU.js';
 import './chunk-YN7LJWGI.js';
 import './chunk-M5WR5TCR.js';
 import './chunk-YLO6IAXF.js';

package/docs/api-reference.md

@@ -29,6 +29,13 @@ Everything below is exported from `@sandboxsonny/ace-kit` unless a path is given
 | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
 | `imageAttributes(image, { sizes, lazy? })` | The attributes for an `<img>`: `src`, `srcSet`, `sizes`, `width`, `height`, `alt`, `loading`, `decoding`, `fetchPriority`. |
 
+## Links and dates
+
+|                                |                                                                                                                                                                                                                                                                                   |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `linkAttributes(link)`         | What to draw for a link field: `{ href, label }` (`label` is `null` when the editor gave no words), or `null` if the address can't be trusted.                                                                                                                                    |
+| `formatAceDate(date, format?)` | A date field's day (`"2026-10-13"`) as words, in the language asked for (`{ locale: "en-GB" }`), or `null` if it isn't a real day. Takes the options of `Intl.DateTimeFormat`; the default is `dateStyle: "long"`. A day has no time of day, so it never shifts with a time zone. |
+
 ## Menus
 
 |                                            |                                                                            |
@@ -60,7 +67,7 @@ Everything below is exported from `@sandboxsonny/ace-kit` unless a path is given
 
 ## Types
 
-`AceEntry<Values>`, `AceImageData`, `AceMenu`, `AceMenuItem`, `AceNavigationLink`, `AceRichTextDocument`, `AceRichTextNode`, `AceRichTextMark`, `AceContentTypeSchema`, `AceFieldSchema`, `AceAddress`, `AcePage`, `AceClient`, `AceClientOptions`, `AceImageAttributes`, `AceImageOptions`, and the ones generation fills in: `AceContentTypes`, `AceContentTypeHandle`, `AceValuesOf`.
+`AceEntry<Values>`, `AceImageData`, `AceLinkData`, `AceLinkAttributes`, `AceDateFormat`, `AceMenu`, `AceMenuItem`, `AceNavigationLink`, `AceRichTextDocument`, `AceRichTextNode`, `AceRichTextMark`, `AceContentTypeSchema`, `AceFieldSchema`, `AceAddress`, `AcePage`, `AceClient`, `AceClientOptions`, `AceImageAttributes`, `AceImageOptions`, and the ones generation fills in: `AceContentTypes`, `AceContentTypeHandle`, `AceValuesOf`.
 
 ## Astro
 
@@ -76,7 +83,7 @@ Everything below is exported from `@sandboxsonny/ace-kit` unless a path is given
 | `applyPage(response, page)`                                                               | Puts a page's status and headers on a response.                                                                                                           |
 | `ace`                                                                                     | The client these use.                                                                                                                                     |
 
-Components, by file: `AceImage.astro`, `AceRichText.astro`, `AceTextArea.astro`, `AceMenu.astro`, `AceNotice.astro`, `AcePreviewRefresh.astro`.
+Components, by file: `AceImage.astro`, `AceLink.astro`, `AceRichText.astro`, `AceTextArea.astro`, `AceMenu.astro`, `AceNotice.astro`, `AcePreviewRefresh.astro`.
 
 ## React Router 7
 
@@ -84,11 +91,11 @@ Components, by file: `AceImage.astro`, `AceRichText.astro`, `AceTextArea.astro`,
 
 `@sandboxsonny/ace-kit/react-router` (browser-safe):
 
-|                                                       |                                                                      |
-| ----------------------------------------------------- | -------------------------------------------------------------------- |
-| `AceRichText`, `AceTextArea`, `AceImage`, `AceNotice` | Components; rich text links are router links.                        |
-| `createMeta({ siteName? })`, `meta`                   | The route's `meta`.                                                  |
-| `useAceMenu()`, `useAcePreview()`                     | Read the header menu; keep a preview fresh. Need `createRootLoader`. |
+|                                                                  |                                                                                   |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `AceRichText`, `AceTextArea`, `AceImage`, `AceLink`, `AceNotice` | Components; rich text links and `AceLink` are router links for pages of the site. |
+| `createMeta({ siteName? })`, `meta`                              | The route's `meta`.                                                               |
+| `useAceMenu()`, `useAcePreview()`                                | Read the header menu; keep a preview fresh. Need `createRootLoader`.              |
 
 `@sandboxsonny/ace-kit/react-router/server` (server only):
 
@@ -102,4 +109,4 @@ Components, by file: `AceImage.astro`, `AceRichText.astro`, `AceTextArea.astro`,
 
 ## React (`@sandboxsonny/ace-kit/react`)
 
-`AceImage`, `AceRichText` (with `link`), `usePreviewRefresh(adminOrigin, refresh?)`.
+`AceImage`, `AceLink` (with `as`), `AceRichText` (with `link`), `usePreviewRefresh(adminOrigin, refresh?)`.

package/docs/astro.md

@@ -69,6 +69,7 @@ Import them by file:
 ```astro
 ---
 import AceImage from "@sandboxsonny/ace-kit/astro/AceImage.astro";
+import AceLink from "@sandboxsonny/ace-kit/astro/AceLink.astro";
 import AceRichText from "@sandboxsonny/ace-kit/astro/AceRichText.astro";
 import AceTextArea from "@sandboxsonny/ace-kit/astro/AceTextArea.astro";
 import AceMenu from "@sandboxsonny/ace-kit/astro/AceMenu.astro";
@@ -78,11 +79,13 @@ import AcePreviewRefresh from "@sandboxsonny/ace-kit/astro/AcePreviewRefresh.ast
 <AceMenu handle="main-menu" />
 <AceImage image={entry.values.hero} sizes="(min-width: 64rem) 64rem, 100vw" lazy={false} />
 <AceRichText document={entry.values.body} />
+<AceLink link={entry.values.button} class="button" />
 <AcePreviewRefresh />
 ```
 
 - **AceMenu** draws a whole menu as a `<nav>` with nested lists, marking the current page with `aria-current="page"`. Props: `handle`, `fallback`, `label` (what a screen reader calls it) and `class`. It is deliberately unstyled (`.ace-menu`, `.ace-menu__list`, `.ace-menu__sublist` are the hooks); to control the markup, use `getMenuLinks` and draw it yourself.
 - **AceImage** writes an `<img>` with `src`, `srcset`, `sizes`, `width`, `height`, `alt`, `loading` and `decoding`. Set `sizes` to how wide the image is shown, and `lazy={false}` for the image at the top of the page.
+- **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.
 - **AcePreviewRefresh** goes once in your layout. It does nothing unless the page was opened by the CMS's editor.

package/docs/command-line.md

@@ -0,0 +1,51 @@
+# The command line
+
+`ace-kit` is also a command. It signs you in to CMS Ace from your terminal, and writes types for your content.
+
+```sh
+npx ace-kit login      # sign in
+npx ace-kit whoami     # who am I signed in as?
+npx ace-kit logout     # sign out
+npx ace-kit generate   # write TypeScript types (see Typed content)
+```
+
+Every command takes `--api-url`, or reads `ACE_API_URL` from the environment or a `.env` file in the folder you run it in. Failing both, it uses the address you last signed in to (kept in a small file beside your logins), so after `ace-kit login --api-url …` you can simply run `ace-kit whoami` from anywhere.
+
+## Signing in
+
+```sh
+npx ace-kit login --api-url http://localhost:8080
+```
+
+```
+Signing in to http://localhost:8080
+
+  1. Go to   http://localhost:5173/device
+  2. Type    BCDF-GHJK
+
+Check the code on that page matches. Waiting for you to approve it (Ctrl-C to cancel)...
+```
+
+Your browser opens the CMS admin app's approval page. **Type the code from your terminal** into it (it is deliberately not in the link), check that the tool and the address it shows are yours, and choose **Approve**. The terminal then says who you are signed in as. This is the OAuth device flow, the same shape as `gh auth login`: no password is ever typed into the terminal, and nothing secret is written in a file inside your project.
+
+Only approve a login you started just now, from your own terminal. If the code on the page doesn't match the one in your terminal, or you didn't ask for a login, choose **Turn it down**.
+
+## Where the login is kept
+
+- **On a Mac:** the macOS Keychain, as an item named `ace-kit` whose account is the API address. You can see it in Keychain Access. Ace Kit uses the `security` program that comes with macOS, so nothing native is installed, and the login is handed to it on standard input, never as an argument other users of the machine could read.
+- **Anywhere else:** a file only you can read, `~/.config/ace-kit/credentials.json` (mode `0600`, in a folder of mode `0700`; `%APPDATA%\ace-kit` on Windows). Set `XDG_CONFIG_HOME` to move it.
+- Set `ACE_KIT_CREDENTIALS=file` to use the file even on a Mac.
+
+One login is kept per API address, so you can be signed in to a local CMS and a hosted one at once.
+
+## What a command-line login can do
+
+Much less than you can in the browser. It can see which sites you can reach, read their content types, and read and sync their section types (the last only on a site where you are an owner, or a super admin). It cannot manage members, passwords or other logins, read or change entries and images, or approve another command-line login. It lasts 90 days at most and ends after 30 days unused. A super admin sees it on the Sessions screen, named after your machine, and can end it from there.
+
+## Build servers
+
+A build server has nobody to approve a login in a browser. Set `ACE_TOKEN` to a token instead and Ace Kit uses it in place of a stored login. (Tokens for this are not made yet; for now sign in on the machine that needs it.)
+
+## Signing out
+
+`npx ace-kit logout` ends the login at the CMS and forgets it on this machine. If the CMS can't be reached it still forgets it here, and says so.

package/docs/getting-started.md

@@ -22,7 +22,7 @@ npm install @sandboxsonny/ace-kit
 | `@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` |
 | `@sandboxsonny/ace-kit/vite`                             | A Vite plugin: reads `ACE_` settings from `.env` in development and keeps one copy of React                                                                       |
-| `ace-kit` (command)                                      | `ace-kit generate`, which writes TypeScript types for your content                                                                                                |
+| `ace-kit` (command)                                      | `ace-kit generate` (TypeScript types for your content), `login`, `logout`, `whoami` (see [the command line](./command-line.md))                                   |
 
 ## The client
 

package/docs/react-router.md

@@ -93,6 +93,7 @@ export default function App() {
 From `@sandboxsonny/ace-kit/react-router` (these are safe in the browser):
 
 - **AceRichText** draws a rich text field. Links to pages of this site are router `Link`s, so navigating doesn't reload the page. It renders bare elements; style them from a wrapper.
+- **AceLink** draws a link field. A link to a page of this site is a router `Link`; any other is a plain `<a>`. It shows the editor's words (or the address), or your children instead, and draws nothing for an address that can't be trusted. Dates are text: format them with `formatAceDate` from `@sandboxsonny/ace-kit`.
 - **AceTextArea** draws a Textarea field (plain text): `multiline` (the default) makes paragraphs and line breaks, `multiline={false}` is one line of text.
 - **AceImage** is an `<img>` with `src`, `srcset`, `sizes`, size and alt text. Set `sizes` to how wide it is shown, and `lazy={false}` for the image at the top of the page.
 - **AceNotice** is the heading and message for a page that isn't an entry. Give it a `className`.

package/docs/react.md

@@ -3,7 +3,7 @@
 Needs `react` 18 or newer. The components work with any React framework (React Router, Next.js, Remix, plain Vite). **On React Router 7, use the [React Router adapter](./react-router.md) instead of wiring this up yourself.** Fetch with the [client](./getting-started.md#the-client) on the server (a loader, a server component, `getServerSideProps`), then draw.
 
 ```tsx
-import { AceImage, AceRichText } from "@sandboxsonny/ace-kit/react";
+import { AceImage, AceLink, AceRichText } from "@sandboxsonny/ace-kit/react";
 ```
 
 ## AceImage
@@ -14,6 +14,18 @@ import { AceImage, AceRichText } from "@sandboxsonny/ace-kit/react";
 
 An `<img>` with `src`, `srcset`, `sizes`, `width`, `height` and `alt`. Any other `<img>` prop (`className`, `style`, `onLoad`...) is passed through. `lazy` defaults to `true`; turn it off for the image at the top of the page.
 
+## AceLink
+
+```tsx
+{
+  entry.values.button ? <AceLink link={entry.values.button} className="button" /> : null;
+}
+```
+
+A link field as an `<a>` with the editor's words, or the address when there are none; children replace the words. Nothing is drawn if the address can't be trusted. Give it your router's link with `as` so navigation stays in the browser (`as={({ href, children, className }) => <Link to={href} className={className}>{children}</Link>}`).
+
+A date field is text: `formatAceDate(entry.values.published, { locale: "en-GB" })` gives "13 October 2026" whatever the server's time zone, and `<time dateTime={entry.values.published}>` takes the raw value.
+
 ## AceRichText
 
 ```tsx

package/docs/typed-content.md

@@ -35,15 +35,17 @@ about?.values.headline; // string
 cms.getEntry("pagez", "about"); // type error: no such content type
 ```
 
-| Field                            | Type                                                |
-| -------------------------------- | --------------------------------------------------- |
-| Text, Textarea                   | `string`                                            |
-| Number                           | `number`                                            |
-| Checkbox                         | `boolean`                                           |
-| Select                           | a union of its options, e.g. `"formal" \| "casual"` |
-| Image                            | `AceImageData`                                      |
-| Rich text                        | `AceRichTextDocument`                               |
-| a kind this version doesn't know | `unknown`                                           |
+| Field                            | Type                                                       |
+| -------------------------------- | ---------------------------------------------------------- |
+| Text, Textarea                   | `string`                                                   |
+| Number                           | `number`                                                   |
+| Checkbox                         | `boolean`                                                  |
+| Select                           | a union of its options, e.g. `"formal" \| "casual"`        |
+| Image                            | `AceImageData`                                             |
+| Rich text                        | `AceRichTextDocument`                                      |
+| Date                             | `string`, a day written `YYYY-MM-DD` (see `formatAceDate`) |
+| Link                             | `AceLinkData`: `{ href, label? }`                          |
+| a kind this version doesn't know | `unknown`                                                  |
 
 A field is optional unless it is marked required in the CMS. Before you generate, handles are plain `string` and values are `Record<string, unknown>`, so nothing breaks.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxsonny/ace-kit",
-  "version": "0.1.2",
+  "version": "0.3.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",