caracms 0.7.0 → 0.8.1

package/README.md

@@ -10,8 +10,17 @@ is, under the MIT license.
 
 ## Start
 
-caracms goes into an existing Astro site (Astro 7, on Node 22.12 or later). From the
-site's root, in a clean git checkout, install it and commit the install:
+Two steps: create an Astro site, then add caracms to it with `npx caracms init`.
+(`npm create caracms` says the same.)
+
+**1. Create the Astro site** (Astro 7, on Node 22.12 or later), or use one you have:
+
+```sh
+npm create astro@latest
+```
+
+**2. In it, add caracms.** From the site's root, in a clean git checkout, install it and
+commit the install:
 
 ```sh
 npm install caracms --save-exact
@@ -27,8 +36,10 @@ one diff to review. Then look at what `init` would do:
 npx caracms init
 ```
 
-It prints every file it would add and every edit it would make, as a diff, and changes
-nothing. When it looks right, apply it and install what it added:
+It asks where the site will run, [CaraCMS Cloud](#caracms-cloud) or self-hosted, then
+prints every file it would add and every edit it would make, as a diff, and changes
+nothing. (It asks only in a terminal: an agent or a script passes `--cloud` or
+`--self-hosted`.) When it looks right, apply it and install what it added:
 
 ```sh
 npx caracms init --write
@@ -45,9 +56,12 @@ job of the `caracms-adopt` skill, one page at a time.
 
 Run from the site's root:
 
-- `caracms init [--write] [--railway]`: add caracms to an Astro site, or bring a set-up
-  site's skills, schemas and CLAUDE.md block up to date. `--railway` also writes a
-  Railway setup; without it, `init` prints the variables any host needs (Hosting, below).
+- `caracms init [--write] [--railway] [--cloud | --self-hosted]`: add caracms to an Astro
+  site, or bring a set-up site's skills, schemas and CLAUDE.md block up to date.
+  `--cloud` or `--self-hosted` says where the site runs, written into `caracms.config.ts`
+  as `services` ([Where the site runs](#where-the-site-runs-services)); `--cloud` on a
+  self-hosted site also prints the steps of the move. `--railway` also writes a Railway
+  setup; without it, `init` prints the variables any host needs (Hosting, below).
 - `caracms validate [--fix] [--json]`: check the content against `caracms.config.ts`.
   Exits 1 when there are errors. `--fix` runs `caracms schemas` first, then lays each
   content file out as the editor saves it (two-space JSON; only whitespace changes).
@@ -59,8 +73,8 @@ Run from the site's root:
   keeping every key ([Moving a site's images in](#moving-a-sites-images-in)).
 - `caracms start`: serve the built site (Hosting, below).
 
-The skills (`caracms-content`, `caracms-blocks` and `caracms-adopt`, in `skills/`) say how
-the rest works, matching the installed version.
+The skills (`caracms-content`, `caracms-blocks`, `caracms-adopt`, `caracms-tina` and
+`caracms-hosting`, in `skills/`) say how the rest works, matching the installed version.
 
 ## Collections and addresses
 
@@ -204,7 +218,8 @@ It prints where the IP comes from when it starts.
 - Commit: `RAILWAY_GIT_COMMIT_SHA`, which Railway sets.
 - `caracms init --railway` writes `.railway/railway.ts`, which describes the whole
   project (the site, Redis, the buckets, imgproxy). Railway's own variables cover the
-  repo, so `GITHUB_REPO` isn't needed.
+  repo, so `GITHUB_REPO` isn't needed. With `--cloud` it writes only the site and Redis:
+  the cloud brings the rest.
 - Try again: `CARACMS_RAILWAY_TOKEN`, a project token. Railway has no deploy hook.
 
 ### Render
@@ -315,8 +330,78 @@ site, signs every commit, and isn't tied to a person. Use it for anyone running
 a handful of sites, or a repo that requires signed commits. Install it on the site's repo
 only, with the same permissions as the token.
 
+**Protect `drafts` from deletion.** It holds every change saved since the last Publish,
+and to a branch tidy-up it looks like any stale branch. In the repo's Settings → Rules →
+Rulesets, add a branch ruleset that targets `drafts` and turns on "Restrict deletions"
+only (leave "Block force pushes" off: Publish moves `drafts` with a forced update). If
+`drafts` goes anyway, the next start makes it again from the last commit the server
+recorded, while GitHub still has that commit; when it can't, the editor says what was lost.
+
+**Roll the site back with `git revert`, never a force-push.** A revert is a new commit on
+`main`, which `drafts` takes in like any push; resetting `main` to an older commit and
+force-pushing leaves the rolled-back content waiting in the editor, so the next Publish puts
+it back (the editor warns everyone when it sees one).
+
 ### CaraCMS Cloud
 
+#### Where the site runs: `services`
+
+`caracms.config.ts` says where the site's services (GitHub access, images, forms and
+email, video) come from, and nothing else decides it:
+
+```ts
+export default defineSite({
+	services: 'cloud', // or 'self-hosted'
+	collections: { … },
+	…
+});
+```
+
+- **`'cloud'`**: everything comes through `CARACMS_CLOUD_KEY`. The self-hosted variables
+  (the GitHub token or App and `GITHUB_REPO`, the image, video, and form and email ones
+  below) are **ignored**, never read, and each is named once in the build log and once
+  when the server starts:
+
+  > S3_BUCKET is set, but this site runs on CaraCMS Cloud (caracms.config.ts): it's ignored. Remove it once the old bucket and imgproxy are retired.
+
+  So a site can move with its old variables still set, and remove them afterwards. A
+  production build or server with no key fails with "This site runs on CaraCMS Cloud
+  (caracms.config.ts), but CARACMS_CLOUD_KEY isn't set. Make a key for it in
+  app.caracms.com." (the build fails; a running server's `/admin` answers 503 with it, and
+  the public site keeps serving). It never falls back to the self-hosted variables.
+  `astro dev` without a key is local mode, as always.
+- **`'self-hosted'`**: the site's own variables, as [the variables](#the-variables) list
+  them. A `CARACMS_CLOUD_KEY` beside them is ignored the same way.
+- **Not set** (a site from before caracms 0.8.0): the key decides, and setting it beside
+  the site's own variables is refused, as each section below says. The next `caracms init`
+  adds the field.
+
+`caracms init --cloud` or `--self-hosted` writes the field (as the first line inside
+`defineSite({`). With neither, `init` asks in a terminal and, run by an agent or a script,
+leaves a set-up site's mode unset (and says so) or stops on a new one. Once the field is
+there, `init` reads it and never asks again.
+
+**Moving a self-hosted site onto the cloud.** `caracms init --cloud` on a self-hosted site
+writes the field and prints the steps of the move, in order, each with the check that it
+worked: make the site, its key and the App's install in app.caracms.com; push the field
+(the host's build fails until the key is set: the old deployment keeps serving); copy the
+images in with [`caracms media push`](#moving-a-sites-images-in); set the key on the host;
+upload the video clips again; remove every variable the cloud replaces (it names them all,
+marking the ones it found in `.env` and `.railway/railway.ts`; it can't see the host's own
+page, so check that too); retire what the cloud replaced; and, last, cut
+`.railway/railway.ts` down to the site and Redis. `init` never edits an existing
+`.railway/railway.ts`: `railway config apply` would remove the buckets with it. With a key
+in the environment or `.env`, `init --cloud` also checks it, showing the site, its team,
+the linked repo and whether the App is installed on it, or the cloud's reason for refusing
+it (it never prints the key). The `caracms-hosting` skill walks through all of this.
+
+**Leaving.** `caracms init --self-hosted` on a cloud site writes the field back and prints
+the way back: set up the site's own services ([Hosting](#hosting)), copy the site's folder
+from the cloud's media bucket to a bucket of your own (the keys in content stay the same),
+set the variables, then remove the key.
+
+#### GitHub access on CaraCMS Cloud
+
 A site run by CaraCMS can take its GitHub access from CaraCMS Cloud instead of a token or
 an App of its own. The cloud gives the site's server a short-lived token for the site's
 repo, and only that repo, about once an hour.
@@ -329,8 +414,9 @@ repo, and only that repo, about once an hour.
    site's server.
 
 The key replaces `CARACMS_GITHUB_TOKEN` (or `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`)
-and `GITHUB_REPO`: the repo comes from the cloud when the server starts, so setting
-`GITHUB_REPO` beside the key is refused, and so is setting a token or an App as well. It
+and `GITHUB_REPO`: the repo comes from the cloud when the server starts. With `services: 'cloud'`
+they're ignored; on a site whose config doesn't say, setting `GITHUB_REPO` beside the key is
+refused, and so is setting a token or an App as well. It
 also replaces the image variables ([Images](#images-on-caracms-cloud), below), the
 video ones ([Video](#video-on-caracms-cloud)), and the form and email ones
 ([Forms and email](#forms-and-email-on-caracms-cloud)).
@@ -350,7 +436,8 @@ start.
 With the key, the site's images live in its own folder of CaraCMS Cloud's media bucket and
 are served, resized and signed, from `img.caracms.cloud`. Set none of `S3_ENDPOINT`,
 `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `IMGPROXY_KEY`,
-`IMGPROXY_SALT` or `CARACMS_MEDIA_URL`: setting any of them beside the key is refused with
+`IMGPROXY_SALT` or `CARACMS_MEDIA_URL`. With `services: 'cloud'` they're ignored; on a site
+whose config doesn't say, setting any of them beside the key is refused with
 
 > Set CARACMS_CLOUD_KEY or the site's own media variables, not both: remove S3_BUCKET.
 
@@ -374,8 +461,9 @@ site's `.env`), with the same rules and output, and its uploads count like any o
 
 With the key, the site needs no submissions bucket and no Resend account. Set none of
 `SUBMISSIONS_S3_BUCKET`, `SUBMISSIONS_S3_ACCESS_KEY_ID`, `SUBMISSIONS_S3_SECRET_ACCESS_KEY`,
-`RESEND_API_KEY` or `FORMS_FROM`: setting any of them beside the key is refused, at build
-and when the server starts, with
+`RESEND_API_KEY` or `FORMS_FROM`. With `services: 'cloud'` they're ignored; on a site whose
+config doesn't say, setting any of them beside the key is refused, at build and when the
+server starts, with
 
 > Set CARACMS_CLOUD_KEY or the site's own forms and email variables, not both: remove RESEND_API_KEY and FORMS_FROM.
 
@@ -406,8 +494,9 @@ them.
 
 `caracms media push` copies everything under `uploads/` in the site's own bucket into its
 CaraCMS Cloud folder, under the same keys, so the content doesn't change. It's the one
-command that takes both credentials, so give the site's own `S3_*` on its command line
-rather than in `.env` (the running site refuses both):
+command that takes both credentials. The old bucket's `S3_*` can stay in `.env` once the
+config says `services: 'cloud'` (the running site ignores them); on a site whose config
+doesn't say, give them on its command line instead (it refuses both):
 
 ```bash
 S3_ENDPOINT=https://t3.storageapi.dev S3_REGION=auto S3_BUCKET=… S3_ACCESS_KEY_ID=… S3_SECRET_ACCESS_KEY=… npx caracms media push
@@ -423,8 +512,8 @@ CaraCMS to raise it, then run it again.
 
 With the key, the site's clips are uploaded to CaraCMS Cloud's Mux and listed from the
 site's own clips there; the editor works exactly as it does with a Mux account of your
-own. Set neither `MUX_TOKEN_ID` nor `MUX_TOKEN_SECRET`: setting either beside the key is
-refused with
+own. Set neither `MUX_TOKEN_ID` nor `MUX_TOKEN_SECRET`. With `services: 'cloud'` they're
+ignored; on a site whose config doesn't say, setting either beside the key is refused with
 
 > Set CARACMS_CLOUD_KEY or the site's own Mux variables, not both: remove MUX_TOKEN_ID.
 

package/bin/caracms.mjs

@@ -31,7 +31,9 @@ import { createGate, describeClientIpSource, markProcessGated, parsePrelaunch, p
 
 const USAGE = `Usage: caracms <command>, from the site's root
 
-  init [--write] [--railway]  Add caracms to an existing Astro site. Shows the change; --write applies it.
+  init [--write] [--railway] [--cloud | --self-hosted]
+                              Add caracms to an existing Astro site, and say where it runs (CaraCMS
+                              Cloud or self-hosted). Shows the change; --write applies it.
   schemas                     Write schemas/ from caracms.config.ts, and add $schema to content files.
   validate [--fix] [--json]   Check content against caracms.config.ts. --fix runs \`schemas\` first,
                               then lays content files out as the editor saves them;
@@ -180,10 +182,16 @@ async function main(argv) {
 			if (rest.length) return usage(`start takes no arguments.`);
 			return start();
 		case 'init': {
-			const f = flags('init', rest, ['--write', '--railway']);
+			const f = flags('init', rest, ['--write', '--railway', '--cloud', '--self-hosted']);
 			if (f.error) return usage(f.error);
 			const { run } = await import('./init.mjs');
-			process.exitCode = await run({ root: process.cwd(), write: f.set.has('--write'), railway: f.set.has('--railway') });
+			process.exitCode = await run({
+				root: process.cwd(),
+				write: f.set.has('--write'),
+				railway: f.set.has('--railway'),
+				cloud: f.set.has('--cloud'),
+				selfHosted: f.set.has('--self-hosted'),
+			});
 			return;
 		}
 		case 'schemas':