@sandboxsonny/ace-kit 0.5.0 → 0.6.0

package/dist/vite.js

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

package/docs/command-line.md

@@ -1,8 +1,9 @@
 # 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.
+`ace-kit` is also a command. It makes new sites, signs you in to CMS Ace from your terminal, and writes types for your content.
 
 ```sh
+npx @sandboxsonny/ace-kit create my-site --site my-site.com   # make a new site (see Making a site)
 npx ace-kit login      # sign in
 npx ace-kit whoami     # who am I signed in as?
 npx ace-kit logout     # sign out
@@ -12,6 +13,34 @@ 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`.
 
+## Making a site
+
+```sh
+npx @sandboxsonny/ace-kit create my-site my-site.com
+```
+
+One command makes everything a new site needs:
+
+1. **Checks** the folder, the domain and the name, before anything is made.
+2. **Signs you in** if you aren't already (your browser opens; type the code from the terminal, as in [Signing in](#signing-in)).
+3. **Makes the site in CMS Ace** and gives it a starter: a `pages` content type, Home, About and Contact entries, a main menu and, for the Astro starter, the three example section types (hero, FAQ, gallery).
+4. **Copies a starter site** into `my-site/` with its name, domain and package name filled in.
+
+If a site with that domain already exists in CMS Ace, it is **left alone** (nothing is added to it, in case it has real content), a warning says so, and only the folder is made. If the CMS refuses to make the site (for instance, you have made as many as your account allows) nothing is made at all.
+
+Your account must be a **partner or super admin** (only they can make sites). The login `create` uses can set up the site it just made, for an hour, and no other site: it can't write content anywhere else.
+
+| Option                            | Meaning                                                                                |
+| --------------------------------- | -------------------------------------------------------------------------------------- |
+| `<domain>` (or `--site <domain>`) | The domain the site has in CMS Ace. Required.                                          |
+| `--framework astro\|react-router` | `astro` (the default) or `react-router`. The React Router starter has no sections yet. |
+| `--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`.
+
 ## Signing in
 
 ```sh

package/docs/getting-started.md

@@ -2,6 +2,14 @@
 
 Ace Kit is everything a website needs to use CMS Ace (see the [README](../README.md)): a typed client for the public API, addressing (`/{content type}/{entry}`), responsive images, menus, rich text, live preview support, and thin Astro and React adapters. It has no runtime dependencies.
 
+## Starting from nothing
+
+```sh
+npx @sandboxsonny/ace-kit create my-site my-site.com
+```
+
+makes an Astro (or, with `--framework react-router`, a React Router) site with everything below already wired up. See [the command line](./command-line.md#making-a-site). To add the kit to a site you already have, read on.
+
 ## Install
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxsonny/ace-kit",
-  "version": "0.5.0",
+  "version": "0.6.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",
@@ -29,6 +29,7 @@
   "files": [
     "dist",
     "astro",
+    "templates",
     "docs",
     "CHANGELOG.md",
     "LICENSE"
@@ -87,8 +88,10 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "typecheck": "tsc --noEmit",
-    "check": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build && npm run check:package",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build && npm run check:package && npm run check:templates",
     "check:package": "node scripts/check-package.mjs",
+    "check:templates": "node scripts/sync-templates.mjs --check",
+    "sync:templates": "node scripts/sync-templates.mjs",
     "pack:local": "npm run build && npm pack",
     "storybook": "storybook dev -p 6006",
     "build:storybook": "storybook build",

package/templates/astro/.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.astro
+.env
+.env.*
+!.env.example
+.vscode

package/templates/astro/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      # Small upgrades arrive together as one pull request. A major version of anything is its own pull request, so
+      # one that needs a deliberate look (a new Astro or Ace Kit major) doesn't hold back the rest.
+      minor-and-patch:
+        update-types: [minor, patch]
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

package/templates/astro/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          # Matches the Dockerfile's node:24-alpine, so CI tests what production runs.
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      # Format, lint, types, tests and a build.
+      - run: npm run check

package/templates/astro/.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.astro
+public
+package-lock.json
+src/ace-kit.generated.d.ts

package/templates/astro/.prettierrc.json

@@ -0,0 +1,20 @@
+{
+  "printWidth": 120,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "plugins": ["prettier-plugin-astro"],
+  "overrides": [
+    {
+      "files": "*.astro",
+      "options": {
+        "parser": "astro"
+      }
+    }
+  ]
+}

package/templates/astro/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

package/templates/astro/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

package/templates/astro/AGENTS.md

@@ -0,0 +1,22 @@
+## Development
+
+When starting the dev server, use background mode:
+
+```
+astro dev --background
+```
+
+Manage the background server with `astro dev stop`, `astro dev status`, and `astro dev logs`.
+
+## Documentation
+
+Full documentation: https://docs.astro.build
+
+Consult these guides before working on related tasks:
+
+- [Adding pages, dynamic routes, or middleware](https://docs.astro.build/en/guides/routing/)
+- [Working with Astro components](https://docs.astro.build/en/basics/astro-components/)
+- [Using React, Vue, Svelte, or other framework components](https://docs.astro.build/en/guides/framework-components/)
+- [Adding or managing content](https://docs.astro.build/en/guides/content-collections/)
+- [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/)
+- [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/)

package/templates/astro/Dockerfile

@@ -0,0 +1,17 @@
+FROM node:24-alpine AS production-dependencies-env
+COPY ./package.json package-lock.json /app/
+WORKDIR /app
+RUN npm ci --omit=dev
+
+FROM node:24-alpine AS build-env
+COPY . /app/
+WORKDIR /app
+RUN npm ci && npm run build
+
+FROM node:24-alpine
+ENV HOST=0.0.0.0
+COPY ./package.json package-lock.json /app/
+COPY --from=production-dependencies-env /app/node_modules /app/node_modules
+COPY --from=build-env /app/dist /app/dist
+WORKDIR /app
+CMD ["node", "dist/server/entry.mjs"]

package/templates/astro/_gitignore

@@ -0,0 +1,26 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/
+.env.*
+!.env.example

package/templates/astro/astro.config.mjs

@@ -0,0 +1,18 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+
+import node from "@astrojs/node";
+import ace from "@sandboxsonny/ace-kit/astro/integration";
+
+// https://astro.build/config
+export default defineConfig({
+  // The site's domain in CMS Ace. Ace Kit reads it from here (ACE_SITE_DOMAIN, if set, wins), so the dev server can find
+  // or make your own private copy of this site to work on.
+  site: "https://example.adamsdevelopment.co.uk",
+  // Pages are rendered on each request so they always show the CMS's live content.
+  output: "server",
+  adapter: node({ mode: "standalone" }),
+  // Ace Kit connects the site to CMS Ace: it declares ACE_API_URL, ACE_SITE_DOMAIN and ACE_PREVIEW_ADMIN_ORIGIN, and
+  // lets the CMS's admin app frame the site for live preview.
+  integrations: [ace()],
+});

package/templates/astro/eslint.config.js

@@ -0,0 +1,56 @@
+import eslint from "@eslint/js";
+import astro from "eslint-plugin-astro";
+import prettierConfig from "eslint-config-prettier";
+import globals from "globals";
+import typescriptEslint from "typescript-eslint";
+
+export default typescriptEslint.config(
+  { ignores: ["node_modules", "dist", ".astro", "public"] },
+
+  eslint.configs.recommended,
+  ...typescriptEslint.configs.recommended,
+  ...astro.configs.recommended,
+
+  {
+    files: ["**/*.{ts,astro,mjs}"],
+    languageOptions: { globals: { ...globals.browser, ...globals.node } },
+    rules: {
+      // Types are imported with `import type` from src/types.
+      "@typescript-eslint/consistent-type-imports": ["error", { fixStyle: "separate-type-imports" }],
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }],
+
+      // No abbreviated names in code. Spell it out: `request`, `response`, `message`...
+      "id-denylist": [
+        "error",
+        "req",
+        "res",
+        "resp",
+        "cfg",
+        "msg",
+        "btn",
+        "tmp",
+        "idx",
+        "evt",
+        "cb",
+        "fn",
+        "opts",
+        "args",
+        "val",
+        "num",
+        "str",
+        "obj",
+        "arr",
+      ],
+
+      eqeqeq: ["error", "always"],
+      "no-console": ["warn", { allow: ["error", "warn"] }],
+      "prefer-const": "error",
+    },
+  },
+
+  // Command-line scripts report what they did on the console.
+  { files: ["scripts/**"], rules: { "no-console": "off" } },
+
+  // Must stay last: turns off any rule that would fight with Prettier.
+  prettierConfig,
+);

package/templates/astro/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "example-astro-site",
+  "type": "module",
+  "version": "0.0.1",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "astro check",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build",
+    "test": "vitest run --passWithNoTests",
+    "generate": "ace-kit generate"
+  },
+  "dependencies": {
+    "@astrojs/node": "^11.1.7",
+    "@sandboxsonny/ace-kit": "^0.5.0",
+    "astro": "^7.3.8"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.12.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-astro": "^1.7.0",
+    "globals": "^17.13.0",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.9.10",
+    "prettier-plugin-astro": "^1.1.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.4"
+  }
+}

package/templates/astro/public/favicon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 128 128">
+    <path d="M50.4 78.5a75.1 75.1 0 0 0-28.5 6.9l24.2-65.7c.7-2 1.9-3.2 3.4-3.2h29c1.5 0 2.7 1.2 3.4 3.2l24.2 65.7s-11.6-7-28.5-7L67 45.5c-.4-1.7-1.6-2.8-2.9-2.8-1.3 0-2.5 1.1-2.9 2.7L50.4 78.5Zm-1.1 28.2Zm-4.2-20.2c-2 6.6-.6 15.8 4.2 20.2a17.5 17.5 0 0 1 .2-.7 5.5 5.5 0 0 1 5.7-4.5c2.8.1 4.3 1.5 4.7 4.7.2 1.1.2 2.3.2 3.5v.4c0 2.7.7 5.2 2.2 7.4a13 13 0 0 0 5.7 4.9v-.3l-.2-.3c-1.8-5.6-.5-9.5 4.4-12.8l1.5-1a73 73 0 0 0 3.2-2.2 16 16 0 0 0 6.8-11.4c.3-2 .1-4-.6-6l-.8.6-1.6 1a37 37 0 0 1-22.4 2.7c-5-.7-9.7-2-13.2-6.2Z" />
+    <style>
+        path { fill: #000; }
+        @media (prefers-color-scheme: dark) {
+            path { fill: #FFF; }
+        }
+    </style>
+</svg>

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

@@ -0,0 +1,24 @@
+// Generated by ace-kit from localhost. Do not edit: run `ace-kit generate` to update it.
+import type { AceImageData, AceLinkData, AceRichTextDocument, AceSection } from "@sandboxsonny/ace-kit";
+
+declare module "@sandboxsonny/ace-kit" {
+  interface AceContentTypes {
+    /** Pages */
+    "pages": {
+      /** Headline */
+      "headline": string;
+      /** Body */
+      "body"?: AceRichTextDocument;
+      /** Hero image */
+      "hero"?: AceImageData;
+      /** Published */
+      "published"?: string;
+      /** Button */
+      "button"?: AceLinkData;
+      /** Content */
+      "content"?: AceSection[];
+    };
+  }
+}
+
+export {};

package/templates/astro/src/components/PageContent.astro

@@ -0,0 +1,113 @@
+---
+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 { formatAceDate } from "@sandboxsonny/ace-kit";
+import type { AceEntry } from "@sandboxsonny/ace-kit";
+
+import AceSections from "@sandboxsonny/ace-kit/astro/AceSections.astro";
+
+import Faq from "~/components/sections/Faq.astro";
+import Gallery from "~/components/sections/Gallery.astro";
+import Hero from "~/components/sections/Hero.astro";
+
+import type { PageValues } from "~/types/page";
+
+type Props = {
+  entry: AceEntry<PageValues>;
+};
+
+const { entry } = Astro.props;
+const { headline, body, hero, published, button, content } = entry.values;
+---
+
+<section class="section">
+  <div class="container prose">
+    <h1>{headline || entry.title}</h1>
+    {entry.description && <p class="intro">{entry.description}</p>}
+    {
+      // A date field is a day with no time of day, so it is the same day wherever the server runs.
+      published && (
+        <p class="published">
+          Published <time datetime={published}>{formatAceDate(published, { locale: "en-GB" }) ?? published}</time>
+        </p>
+      )
+    }
+    {hero && (
+      <figure>
+        <AceImage image={hero} sizes="(min-width: 64rem) 64rem, 100vw" lazy={false} />
+      </figure>
+    )}
+    {
+      // A site made before its Body field was rich text still has plain text, with blank lines between paragraphs.
+      typeof body === "string" ? (
+        <AceTextArea value={body} />
+      ) : body ? (
+        <div class="rich-text">
+          <AceRichText document={body} />
+        </div>
+      ) : null
+    }
+    {
+      // A link field: the editor's words and where it goes, already worked out by the CMS.
+      button && (
+        <p class="actions">
+          <AceLink link={button} class="button" />
+        </p>
+      )
+    }
+  </div>
+</section>
+<AceSections sections={content} components={{ hero: Hero, faq: Faq, gallery: Gallery }} />
+<style>
+  .prose {
+    max-width: 42rem;
+  }
+  .intro {
+    color: var(--colour-muted);
+    font-size: 1.125rem;
+  }
+  .published {
+    color: var(--colour-muted);
+    font-size: 0.9rem;
+  }
+  .actions {
+    margin-top: 2rem;
+  }
+  figure {
+    margin: 2rem 0;
+  }
+  figure :global(img) {
+    border-radius: 0.5rem;
+  }
+  .rich-text :global(* + *) {
+    margin-top: 1rem;
+  }
+  .rich-text :global(h2) {
+    font-size: 1.75rem;
+  }
+  .rich-text :global(h3) {
+    font-size: 1.4rem;
+  }
+  .rich-text :global(h4) {
+    font-size: 1.15rem;
+  }
+  .rich-text :global(ul) {
+    list-style: disc;
+    padding-left: 1.5rem;
+  }
+  .rich-text :global(ol) {
+    list-style: decimal;
+    padding-left: 1.5rem;
+  }
+  .rich-text :global(blockquote) {
+    border-left: 4px solid var(--colour-muted);
+    padding-left: 1rem;
+    font-style: italic;
+  }
+  .rich-text :global(img) {
+    max-width: 100%;
+    height: auto;
+  }
+</style>

package/templates/astro/src/components/SiteFooter.astro

@@ -0,0 +1,19 @@
+---
+const year = new Date().getFullYear();
+---
+
+<footer class="site-footer">
+  <div class="container">
+    <p>© {year} Example Site. A test site for CMS Ace.</p>
+  </div>
+</footer>
+
+<style>
+  .site-footer {
+    margin-top: 3rem;
+    padding-block: 2rem;
+    background: var(--colour-surface);
+    color: var(--colour-muted);
+    font-size: 0.9rem;
+  }
+</style>