@sandboxsonny/ace-kit 0.3.0 → 0.4.0

package/dist/cli.js

@@ -3,6 +3,7 @@
 // src/cli/environment.ts
 import { spawn } from "child_process";
 import { hostname } from "os";
+import { pathToFileURL } from "url";
 
 // src/auth/file-store.ts
 import { mkdir, readFile, rename, writeFile } from "fs/promises";
@@ -170,7 +171,7 @@ function createLastApiUrl(path) {
 }
 
 // src/cli/version.ts
-var aceKitVersion = true ? "0.3.0" : "development";
+var aceKitVersion = true ? "0.4.0" : "development";
 
 // src/cli/environment.ts
 var runCommand = (command, commandArguments, input) => new Promise((resolve2, reject) => {
@@ -201,6 +202,19 @@ async function openBrowser(platform, address) {
     });
   });
 }
+async function importModule(path) {
+  try {
+    return await import(pathToFileURL(path).href);
+  } catch (error) {
+    if (error.code === "ERR_UNKNOWN_FILE_EXTENSION") {
+      throw new Error(
+        "this version of Node can't run TypeScript files. Use Node 22.18 or newer, or write the schema in .js.",
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+}
 async function createRealEnvironment() {
   try {
     process.loadEnvFile(".env");
@@ -219,6 +233,8 @@ async function createRealEnvironment() {
     fetchImplementation: (input, init) => fetch(input, init),
     sleep: (milliseconds) => new Promise((resolve2) => setTimeout(resolve2, milliseconds)),
     now: Date.now,
+    workingDirectory: process.cwd(),
+    importModule,
     openBrowser: (address) => openBrowser(platform, address),
     store: await chooseLoginStore({ platform, variables, run: runCommand }),
     lastApiUrl: createLastApiUrl(defaultLastApiUrlFile(variables, platform))
@@ -348,6 +364,8 @@ function typeOfField(field) {
       return { type: "string" };
     case "link":
       return { type: "AceLinkData", uses: "AceLinkData" };
+    case "sections":
+      return { type: "AceSection[]", uses: "AceSection" };
     default:
       return { type: "unknown" };
   }
@@ -566,6 +584,26 @@ async function resolveLogin(options) {
   return { token: stored.token, email: stored.email, source: options.store.description };
 }
 
+// src/cli/api-url.ts
+async function resolveApiUrl(fromOption, environment) {
+  const address = fromOption ?? 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 normaliseApiUrl(address);
+  } catch (error) {
+    environment.error(error instanceof Error ? error.message : String(error));
+    return null;
+  }
+}
+function isLocalApiUrl(apiUrl) {
+  return ["localhost", "127.0.0.1", "[::1]"].includes(new URL(apiUrl).hostname);
+}
+
 // src/cli/login-commands.ts
 var loginUsage = `ace-kit login: sign in to CMS Ace from the command line.
 
@@ -589,19 +627,8 @@ async function readApiUrl(commandArguments, environment) {
     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;
-  }
+  const apiUrl = await resolveApiUrl(values["api-url"], environment);
+  return apiUrl === null ? null : { apiUrl };
 }
 function webAddress(address) {
   try {
@@ -611,7 +638,6 @@ function webAddress(address) {
     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;
@@ -620,7 +646,7 @@ async function loginCommand(commandArguments, environment) {
     return 0;
   }
   const { apiUrl } = read;
-  if (apiUrl.startsWith("http://") && !isLocal(apiUrl)) {
+  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.`
     );
@@ -729,11 +755,382 @@ async function whoamiCommand(commandArguments, environment) {
   }
 }
 
+// src/cli/sync-command.ts
+import { parseArgs as parseArgs3 } from "util";
+
+// src/sections/find-schemas.ts
+import { readdir } from "fs/promises";
+import { join as join3, relative } from "path";
+var schemaFilePattern = /\.schema\.(?:ts|mts|js|mjs)$/;
+var skippedFolders = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".astro",
+  ".react-router",
+  ".output",
+  "coverage"
+]);
+async function findSchemaFiles(root, folder = "src") {
+  const start = join3(root, folder);
+  const found = [];
+  async function walk(directory) {
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const path = join3(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (!skippedFolders.has(entry.name)) await walk(path);
+      } else if (entry.isFile() && schemaFilePattern.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+        found.push(path);
+      }
+    }
+  }
+  await walk(start);
+  return found.sort((first, second) => {
+    const [firstName, secondName] = [relative(root, first), relative(root, second)];
+    return firstName < secondName ? -1 : firstName > secondName ? 1 : 0;
+  });
+}
+
+// src/sections/load-schemas.ts
+import { relative as relative2 } from "path";
+
+// src/sections/payload.ts
+var handlePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var maximumHandleLength = 64;
+var maximumNameLength = 200;
+var fieldTypes = [
+  "text",
+  "textarea",
+  "number",
+  "checkbox",
+  "select",
+  "image",
+  "richtext",
+  "date",
+  "link"
+];
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isHandle = (value) => typeof value === "string" && value.length <= maximumHandleLength && handlePattern.test(value);
+var handleRule = 'lowercase letters, numbers and hyphens (such as "call-to-action")';
+function checkFields(fields, where, problems) {
+  if (fields === void 0) return;
+  if (!Array.isArray(fields)) {
+    problems.push(`${where}: fields must be a list.`);
+    return;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  fields.forEach((field, index) => {
+    if (!isObject(field)) {
+      problems.push(`${where}: field ${index + 1} must be an object with a handle, a label and a type.`);
+      return;
+    }
+    const name = isHandle(field.handle) ? `field "${field.handle}"` : `field ${index + 1}`;
+    if (!isHandle(field.handle)) problems.push(`${where}: ${name} needs a handle of ${handleRule}.`);
+    else if (seen.has(field.handle)) problems.push(`${where}: ${name} is defined twice.`);
+    else seen.add(field.handle);
+    if (typeof field.label !== "string" || field.label.trim() === "" || field.label.length > maximumNameLength) {
+      problems.push(`${where}: ${name} needs a label.`);
+    }
+    if (typeof field.type !== "string" || !fieldTypes.includes(field.type)) {
+      const given = typeof field.type === "string" ? ` "${field.type}"` : "";
+      problems.push(`${where}: ${name} has a type${given} that isn't one of ${fieldTypes.join(", ")}.`);
+    } else if (field.type === "select") {
+      const { options } = field;
+      if (!Array.isArray(options) || options.length === 0 || options.some((option) => typeof option !== "string" || option === "")) {
+        problems.push(`${where}: ${name} is a select, so it needs options: a list of the choices, as text.`);
+      }
+    }
+    if (field.required !== void 0 && typeof field.required !== "boolean") {
+      problems.push(`${where}: ${name} has a required that isn't true or false.`);
+    }
+  });
+}
+function checkSectionDefinition(definition, where = "this section") {
+  const problems = [];
+  if (!isObject(definition)) {
+    return [`${where}: the default export must be the result of defineSection({ ... }).`];
+  }
+  if (!isHandle(definition.handle)) {
+    problems.push(`${where}: needs a handle of ${handleRule}.`);
+  }
+  if (typeof definition.name !== "string" || definition.name.trim() === "" || definition.name.length > maximumNameLength) {
+    problems.push(`${where}: needs a name.`);
+  }
+  checkFields(definition.fields, where, problems);
+  if (definition.blocks !== void 0) {
+    if (!isObject(definition.blocks)) {
+      problems.push(`${where}: blocks must be an object of the kinds of block, by handle.`);
+    } else {
+      for (const [handle, block] of Object.entries(definition.blocks)) {
+        const blockWhere = `${where}, block "${handle}"`;
+        if (!isHandle(handle)) problems.push(`${blockWhere}: the handle must be ${handleRule}.`);
+        if (!isObject(block)) {
+          problems.push(`${blockWhere}: must be an object with a name and fields.`);
+          continue;
+        }
+        if (typeof block.name !== "string" || block.name.trim() === "") problems.push(`${blockWhere}: needs a name.`);
+        checkFields(block.fields, blockWhere, problems);
+      }
+    }
+  }
+  return problems;
+}
+function apiFields(fields) {
+  return (fields ?? []).map((field) => ({
+    handle: field.handle,
+    label: field.label,
+    component_key: field.type,
+    config: {
+      ...field.required ? { required: true } : {},
+      ...field.type === "select" ? { options: [...field.options] } : {}
+    }
+  }));
+}
+function sectionTypesPayload(definitions) {
+  return {
+    sections: definitions.map((definition) => ({
+      handle: definition.handle,
+      name: definition.name,
+      fields: apiFields(definition.fields),
+      blocks: Object.entries(definition.blocks ?? {}).map(([handle, block]) => ({
+        handle,
+        name: block.name,
+        fields: apiFields(block.fields)
+      }))
+    }))
+  };
+}
+
+// src/sections/load-schemas.ts
+async function loadSchemas(files, root, importModule2) {
+  const definitions = [];
+  const problems = [];
+  const handleToFile = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const name = relative2(root, file);
+    let exported;
+    try {
+      const module = await importModule2(file);
+      exported = module.default;
+    } catch (error) {
+      problems.push(`${name}: could not be loaded: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    const fileProblems = checkSectionDefinition(exported, name);
+    if (fileProblems.length > 0) {
+      problems.push(...fileProblems);
+      continue;
+    }
+    const definition = exported;
+    const earlier = handleToFile.get(definition.handle);
+    if (earlier) {
+      problems.push(`${name}: the handle "${definition.handle}" is already used by ${earlier}.`);
+      continue;
+    }
+    handleToFile.set(definition.handle, name);
+    definitions.push({ file, definition });
+  }
+  return { definitions, problems };
+}
+
+// src/sections/sync.ts
+var requestTimeoutMilliseconds4 = 2e4;
+async function readMessage2(response, fallback) {
+  try {
+    const body = await response.json();
+    if (typeof body.error === "string") return body.error;
+  } catch {
+  }
+  return fallback;
+}
+async function syncSectionTypes(options) {
+  const { apiUrl, siteDomain, token, payload, fetchImplementation } = options;
+  const headers = { Accept: "application/json", Authorization: `Bearer ${token}` };
+  let sitesResponse;
+  try {
+    sitesResponse = await fetchImplementation(`${apiUrl}/sites`, {
+      headers,
+      signal: AbortSignal.timeout(requestTimeoutMilliseconds4)
+    });
+  } catch {
+    return { kind: "unreachable" };
+  }
+  if (sitesResponse.status === 401) return { kind: "login-ended" };
+  if (!sitesResponse.ok)
+    return {
+      kind: "rejected",
+      message: await readMessage2(sitesResponse, `The CMS answered with an error (${sitesResponse.status}).`)
+    };
+  const sites = await sitesResponse.json().catch(() => []);
+  const wanted = siteDomain.trim().toLowerCase();
+  const site = sites.find((candidate) => candidate.domain.toLowerCase() === wanted);
+  if (!site)
+    return { kind: "site-not-found", domain: siteDomain, available: sites.map((candidate) => candidate.domain) };
+  let response;
+  try {
+    response = await fetchImplementation(`${apiUrl}/sites/${site.id}/section-types`, {
+      method: "PUT",
+      headers: { ...headers, "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(requestTimeoutMilliseconds4)
+    });
+  } catch {
+    return { kind: "unreachable" };
+  }
+  if (response.status === 401) return { kind: "login-ended" };
+  if (response.status === 403) {
+    return {
+      kind: "forbidden",
+      message: "Your account can't change this site's sections: only a site's owners and super admins can."
+    };
+  }
+  if (!response.ok)
+    return {
+      kind: "rejected",
+      message: await readMessage2(response, `The CMS answered with an error (${response.status}).`)
+    };
+  const body = await response.json().catch(() => null);
+  return {
+    kind: "synced",
+    site: { id: site.id, domain: site.domain },
+    sections: (body?.sections ?? []).map((section) => ({
+      handle: section.handle,
+      name: section.name,
+      retired: section.retired_at !== void 0
+    })),
+    warnings: body?.warnings ?? []
+  };
+}
+
+// src/cli/sync-command.ts
+var syncUsage = `ace-kit sync: send the section types your code defines to CMS Ace.
+
+Usage:
+  ace-kit sync [--api-url <address>] [--domain <domain>] [--dir <folder>]
+
+It finds every *.schema.ts file in the folder (src by default), checks them, and makes the CMS's section types for your
+site match. The dev server does this for you whenever a schema file is saved; run it yourself for a one-off sync, or on a
+build server (with ACE_TOKEN set).
+
+Nothing is deleted: a section type, block or field you take out of your code is kept in the CMS, hidden, so the content
+written in it survives. If any schema file can't be loaded, nothing is synced.
+
+Options:
+  --api-url   Where the CMS Ace API lives (default: ACE_API_URL, else http://localhost:8080).
+  --domain    The domain your site has in the CMS (default: ACE_SITE_DOMAIN, else localhost).
+  --dir       The folder to look in (default: src).
+  --help      Show this message.
+`;
+var defaultApiUrl = "http://localhost:8080";
+var isSwitchedOff = (value) => ["false", "off", "no", "0"].includes((value ?? "").trim().toLowerCase());
+async function syncCommand(commandArguments, environment) {
+  const { values } = parseArgs3({
+    // eslint-disable-next-line id-denylist -- "args" is the name node's parseArgs gives this option.
+    args: commandArguments,
+    options: {
+      "api-url": { type: "string" },
+      domain: { type: "string" },
+      dir: { type: "string" },
+      // Set by the dev server, which syncs on its own: it stays quiet when there is nothing to do, and keeps to a
+      // local CMS unless told otherwise.
+      automatic: { type: "boolean" },
+      help: { type: "boolean" }
+    }
+  });
+  if (values.help) {
+    environment.out(syncUsage);
+    return 0;
+  }
+  const automatic = values.automatic === true;
+  if (automatic && isSwitchedOff(environment.variables.ACE_SYNC_SECTIONS)) return 0;
+  let apiUrl;
+  try {
+    apiUrl = normaliseApiUrl(values["api-url"] ?? environment.variables.ACE_API_URL ?? defaultApiUrl);
+  } catch (error) {
+    environment.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+  const siteDomain = values.domain ?? environment.variables.ACE_SITE_DOMAIN ?? "localhost";
+  const aimedAtDevSite = environment.variables.ACE_DEV_SITE_ACTIVE === "1";
+  if (automatic && !aimedAtDevSite && !isLocalApiUrl(apiUrl) && environment.variables.ACE_SYNC_SECTIONS?.trim().toLowerCase() !== "remote") {
+    environment.out(
+      `Section sync is off while ${apiUrl} is a hosted CMS, so a half-written change can't reach a live site. To sync on every save to it anyway, set ACE_SYNC_SECTIONS=remote. (npx ace-kit sync always works.)`
+    );
+    return 0;
+  }
+  const files = await findSchemaFiles(environment.workingDirectory, values.dir ?? "src");
+  if (files.length === 0) {
+    if (!automatic) {
+      environment.out(
+        `No *.schema.ts files found in ${values.dir ?? "src"}, so nothing was synced (syncing none would retire every section).`
+      );
+    }
+    return 0;
+  }
+  const login = await resolveLogin({
+    apiUrl,
+    variables: environment.variables,
+    store: environment.store,
+    now: environment.now
+  });
+  if (!login) {
+    environment.out(`Section sync is waiting for you to sign in. Run: npx ace-kit login --api-url ${apiUrl}`);
+    return automatic ? 0 : 1;
+  }
+  const loaded = await loadSchemas(files, environment.workingDirectory, environment.importModule);
+  if (loaded.problems.length > 0) {
+    for (const problem of loaded.problems) environment.error(problem);
+    environment.error("Nothing was synced, because syncing only some of your sections would retire the rest.");
+    return 1;
+  }
+  const outcome = await syncSectionTypes({
+    apiUrl,
+    siteDomain,
+    token: login.token,
+    payload: sectionTypesPayload(loaded.definitions.map((entry) => entry.definition)),
+    fetchImplementation: environment.fetchImplementation
+  });
+  switch (outcome.kind) {
+    case "synced": {
+      const defined = outcome.sections.filter((section) => !section.retired).map((section) => section.handle);
+      const retired = outcome.sections.filter((section) => section.retired).map((section) => section.handle);
+      environment.out(
+        `Synced ${defined.length} section type${defined.length === 1 ? "" : "s"} (${defined.join(", ")}) to ${outcome.site.domain} (${apiUrl}).` + (retired.length > 0 ? ` No longer in your code, kept but hidden: ${retired.join(", ")}.` : "")
+      );
+      for (const warning of outcome.warnings) environment.error(`Warning: ${warning}`);
+      return 0;
+    }
+    case "login-ended":
+      environment.out(`Your login has ended. Run: npx ace-kit login --api-url ${apiUrl}`);
+      return automatic ? 0 : 1;
+    case "site-not-found":
+      environment.error(
+        `The CMS at ${apiUrl} has no site with the domain "${outcome.domain}" that you can see` + (outcome.available.length > 0 ? ` (your sites: ${outcome.available.join(", ")})` : "") + ". Set ACE_SITE_DOMAIN or pass --domain."
+      );
+      return 1;
+    case "forbidden":
+    case "rejected":
+      environment.error(outcome.message);
+      return 1;
+    case "unreachable":
+      environment.error(`Could not reach the CMS at ${apiUrl}.`);
+      return 1;
+  }
+}
+
 // src/cli/main.ts
 var usage = `ace-kit: tools for sites built on CMS Ace.
 
 Commands:
   ace-kit generate   Write TypeScript types for your content types.
+  ace-kit sync       Send the section types your code defines to the CMS.
   ace-kit login      Sign in from the command line (opens the admin app).
   ace-kit logout     Sign out.
   ace-kit whoami     Say who you are signed in as.
@@ -745,6 +1142,8 @@ async function runCli(commandArguments, environment) {
   switch (command) {
     case "generate":
       return generateCommand(rest, environment);
+    case "sync":
+      return syncCommand(rest, environment);
     case "login":
       return loginCommand(rest, environment);
     case "logout":