caracms 0.8.0 → 0.8.1

package/src/editor/types.ts

@@ -26,6 +26,16 @@ export interface DocRef {
 /** `pages/services/branding`: a document's id, for keys, storage and the Recent list. */
 export const docId = (ref: DocRef): string => `${ref.collection}/${ref.path}`;
 
+/**
+ * Whether the editor opens a listed document. One whose only trouble is a missing title
+ * does (caracms-cloud adversarial review, finding 15): it's kept off the site and marked,
+ * and opening it is how the title goes back. Invalid JSON and a nested index.json don't.
+ */
+export const opensInEditor = (doc: Pick<DocumentEntry, 'warning'>): boolean => !doc.warning || doc.warning.code === 'no-title';
+
+/** The screen reader's words for a listed document's warning mark. */
+export const warnedWords = (doc: Pick<DocumentEntry, 'warning'>): string => (doc.warning?.code === 'no-title' ? ', needs a title' : ", can't be opened");
+
 export const sameDoc = (a: DocRef | null | undefined, b: DocRef | null | undefined): boolean =>
 	!!a && !!b && a.collection === b.collection && a.path === b.path;
 
@@ -297,6 +307,8 @@ export const ENDPOINTS = {
 	history: '/_caracms/history',
 	tryAgain: '/_caracms/try-again',
 	notice: '/_caracms/notice',
+	// Discard changes (live mode only): one document back to what's live.
+	discard: '/_caracms/discard',
 	// M6 Decision 9: the inbox, both modes (forms/inbox.ts has each route).
 	submissions: '/_caracms/submissions',
 } as const;
@@ -342,6 +354,42 @@ export interface LastChange {
 	version: string | null;
 	/** ISO. */
 	at: string | null;
+	/**
+	 * Discard changes: someone put the document back to what's live (within the last week),
+	 * and when. Edits held in a browser from before then are dropped, not re-sent (keeper.ts → verdict).
+	 */
+	discarded?: { by: Person; at: string } | null;
+}
+
+/**
+ * POST /_caracms/discard `{ file }` (live mode only): put one waiting document back to what's
+ * live. A changed one reads as `main` has it, a new one is removed, a deleted one comes back,
+ * a moved one goes back to its old address (its file `movedBack`). `{ file, seen: true }`: this
+ * tab has let go of its copy of a document someone discarded (`open.discarded`).
+ */
+export interface DiscardRequest {
+	file: string;
+	seen?: true;
+}
+
+export interface DiscardResponse {
+	ok: true;
+	file: string;
+	/** What it was: `changed`, `new` (now removed) or `deleted` (now back). */
+	change: WaitingChange;
+	/** Every file put back as `main` has it. */
+	files: string[];
+	/** A moved document: where it is again (its collection and path), else null. */
+	movedBack: { collection: string; path: string; file: string } | null;
+}
+
+/**
+ * Discard's refusals: `not-waiting` (404: nothing to discard), `locked` (409: someone is
+ * editing it now), `publishing` (409), `busy` (409: the sweep is busy on another server),
+ * `held-move` (409: it moved with the page that holds it), `bad-request`/`bad-path` (400).
+ */
+export interface DiscardRefusal extends ApiError {
+	code: 'not-waiting' | 'locked' | 'publishing' | 'busy' | 'held-move' | 'swap' | 'bad-request' | 'bad-path' | 'no-tab' | 'signed-out' | 'unavailable';
 }
 
 /** 401 from any editor API in live mode with no session (Phase 3's guard, Decision 11). */
@@ -414,6 +462,11 @@ export interface WaitingView {
 	movedFrom?: string;
 	/** With `movedFrom`: Site Settings' redirects send visitors from the old address here (the editor may have taken it out). */
 	movedRedirect?: boolean;
+	/**
+	 * caracms-cloud adversarial review, finding 15: why Publish will leave it waiting ("its title
+	 * is empty"), read from the document as it will publish; absent when it will go out.
+	 */
+	heldBack?: string;
 }
 
 /**
@@ -444,7 +497,9 @@ export type NoticeView =
 	/** "Home was also changed outside the editor. Your draft was kept; check it before publishing" (Decision 7). */
 	| { id: string; kind: 'draft-kept'; file: string; title: string }
 	/** "Aoife published Home as it stood at 14:20" (Decision 10), for the people who had it open. */
-	| { id: string; kind: 'published-as-it-stood'; file: string; title: string; by: Person; at: string };
+	| { id: string; kind: 'published-as-it-stood'; file: string; title: string; by: Person; at: string }
+	/** "Aoife discarded the unpublished changes to About" (Discard changes), for the people who had edits in it or had it open. */
+	| { id: string; kind: 'discarded'; file: string; title: string; by: Person; at: string };
 
 export interface PublishRecordView {
 	commit: string;
@@ -493,6 +548,12 @@ export interface StatusResponse {
 		 * who deleted it and when, when that's known (`by` null: not known). Null while it exists.
 		 */
 		deleted: { by: Person | null; at: string | null } | null;
+		/**
+		 * Discard changes: someone put the document back to what's live while this tab had it
+		 * (open, or edits in it), so this tab's copy is stale: it lets go (`POST discard { file,
+		 * seen }`) and reads it again. Its writes are refused (409 `discarded`) until then.
+		 */
+		discarded?: { by: Person; at: string } | null;
 	} | null;
 	waiting: WaitingView[];
 	locks: LockView[];
@@ -505,9 +566,33 @@ export interface StatusResponse {
 	 * missing permission, or a token expiring within 14 days. `message` names the fix,
 	 * for the developer it's forwarded to. Null when nothing is wrong. `cloud` (caracms-cloud
 	 * M2 Decision 14): CaraCMS Cloud refused a token; `message` is the cloud's sentence and
-	 * `link` the install link it names, if any, which the note shows as a link.
+	 * `link` the install link it names, if any, which the note shows as a link. `renamed`
+	 * (caracms-cloud adversarial review, finding 7) is information, not a problem: the repo
+	 * was renamed or transferred on GitHub and work carries on under the new name, shown
+	 * until the server restarts.
+	 */
+	githubAccess: { kind: 'refused' | 'permission' | 'expiring' | 'cloud' | 'renamed'; title: string; message: string; link?: string | null } | null;
+	/**
+	 * caracms-cloud adversarial review, finding 4: edits are waiting in Redis and the draft
+	 * commits that should carry them to GitHub have failed several times in a row (git.ts →
+	 * `COMMIT_TROUBLE_AFTER`). The save bar stops saying Kept and says so; `message` is the
+	 * whole sentence. Null otherwise, and again once a commit goes through. (Absent from an
+	 * older server: read it as null.)
+	 */
+	commitTrouble?: { since: string; failures: number; message: string } | null;
+	/**
+	 * Finding 5: a start found the `drafts` branch gone and could only make it again from
+	 * `main`, so what it held since the last Publish is gone. `commit` is its last recorded
+	 * head (null: none was recorded). Shown to everyone for a week, or until the next Publish.
+	 */
+	draftsLost?: { title: string; message: string; commit: string | null; at: string } | null;
+	/**
+	 * caracms-cloud adversarial review, force-push note: `main` no longer has the last
+	 * Publish's commit (`publish`), so its history was rewritten, and what was rolled back is
+	 * waiting again. Shown to everyone until the next Publish, or once nothing is waiting.
+	 * (Absent from an older server: read it as null.)
 	 */
-	githubAccess: { kind: 'refused' | 'permission' | 'expiring' | 'cloud'; title: string; message: string; link?: string | null } | null;
+	mainRolledBack?: { title: string; message: string; publish: string; main: string; at: string } | null;
 	/**
 	 * The brand as committed in Site Settings (M5a Decision 10: read from `drafts`, never
 	 * an autosave), so the chrome picks up a change on the next poll with no reload.
@@ -534,8 +619,11 @@ export interface LockResponse {
 
 /** POST /_caracms/publish. */
 export interface PublishResponse {
-	result: 'published' | 'nothing-waiting' | 'joined';
+	/** `held-back` (finding 15): everything waiting would break the reader, so nothing was published. */
+	result: 'published' | 'nothing-waiting' | 'joined' | 'held-back';
 	publish: PublishView;
+	/** Finding 15: what was left waiting, and why ("its title is empty"); absent or empty when nothing was. */
+	held?: { file: string; title: string; reason: string }[];
 }
 
 export interface HistoryEntryView {

package/src/forms/cloud-store.ts

@@ -39,7 +39,10 @@ function submissionOf(value: unknown, what: string): StoredSubmission {
 	if (!s || typeof s !== 'object' || !isSubmissionId(s.id) || typeof s.form !== 'string' || typeof s.receivedAt !== 'string' || !s.fields || typeof s.fields !== 'object') {
 		throw malformed(what);
 	}
-	return { ...s, v: 1, readAt: typeof s.readAt === 'string' ? s.readAt : null };
+	const { filesNote, ...rest } = s;
+	// The attachments-not-kept sentence (caracms-cloud's attachment limit): kept only as a non-empty string.
+	const note = typeof filesNote === 'string' && filesNote.trim() ? { filesNote: filesNote.trim() } : {};
+	return { ...rest, v: 1, readAt: typeof s.readAt === 'string' ? s.readAt : null, ...note };
 }
 
 export function cloudStore(connection: CloudConnection): SubmissionStore {

package/src/forms/inbox.ts

@@ -24,7 +24,8 @@
 import type { ResolvedSite } from '../config.ts';
 import { checkOrigin, WriteRefused } from '../editor/server/write.ts';
 import { FILE_TYPES, isSubmissionId, senderName, shownFileName, submissionSnippet, type ResolvedFormField } from './rules.ts';
-import { fileExtension, readSubmissionsConfig, submissionStore, type StoredSubmission, type SubmissionStore } from './store.ts';
+import { fileExtension, readSubmissionsConfig, submissionStore, type EmailOutcome, type StoredSubmission, type SubmissionStore } from './store.ts';
+import { readCappedText } from '../body.ts';
 
 type Env = Record<string, string | undefined>;
 
@@ -48,8 +49,10 @@ export interface SubmissionRow {
 	readAt: string | null;
 	/** How many files came with it. */
 	files: number;
-	/** The email's outcome, or null when it's unknown (the server died between storing and recording). */
-	emailStatus: 'sent' | 'failed' | 'skipped' | null;
+	/** The email's outcome (`held`: the cloud's, behind the site's daily limit), or null when it's unknown (the server died between storing and recording). */
+	emailStatus: EmailOutcome['status'] | null;
+	/** True when the cloud didn't keep its attachments (`StoredSubmission.filesNote`); absent otherwise. */
+	filesNotKept?: true;
 }
 
 export interface SubmissionsListResponse {
@@ -103,6 +106,7 @@ export function rowOf(site: Pick<ResolvedSite, 'forms'>, s: StoredSubmission): S
 		readAt: s.readAt ?? null,
 		files: s.files?.length ?? 0,
 		emailStatus: s.email?.status ?? null,
+		...(s.filesNote ? { filesNotKept: true as const } : {}),
 	};
 }
 
@@ -125,8 +129,9 @@ export function attachmentHeader(name: string): string {
 export const downloadType = (key: string): string => FILE_TYPES[fileExtension(key)]?.[0] ?? 'application/octet-stream';
 
 async function readJsonBody(request: Request): Promise<Record<string, unknown>> {
-	const text = await request.text().catch(() => '');
-	if (text.length > 4096) return {};
+	// caracms-cloud adversarial review, finding 10: 4 KB counted as it's read, never the whole body first.
+	const text = await readCappedText(request, 4096).catch(() => '');
+	if (text === null) return {};
 	try {
 		const value = JSON.parse(text || '{}') as unknown;
 		return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};

package/src/forms/store.ts

@@ -53,10 +53,16 @@ export interface StoredFile {
 }
 
 export interface EmailOutcome {
-	status: 'sent' | 'failed' | 'skipped';
+	/**
+	 * `held` is only ever the cloud's answer (caracms-cloud adversarial review, finding 20): the
+	 * email waits behind the site's daily limit and goes out when it's raised or the next UTC day.
+	 * It's never stored by the package's own stores.
+	 */
+	status: 'sent' | 'failed' | 'skipped' | 'held';
+	/** When it was sent, failed or was skipped; for `held`, when it was held. */
 	at: string;
 	to: string[];
-	/** Resend's message on failure, or why it was skipped. */
+	/** Resend's message on failure, why it was skipped, or the cloud's sentence for a held one. */
 	error?: string;
 }
 
@@ -76,6 +82,12 @@ export interface StoredSubmission {
 	readAt: string | null;
 	/** Absent: not attempted yet, or the server died mid-way (the inbox says "unknown"). */
 	email?: EmailOutcome;
+	/**
+	 * Only ever the cloud's: why the attachments that came with it weren't kept (the site
+	 * reached its daily attachment limit in CaraCMS Cloud), as a sentence the inbox shows in
+	 * place of "No files". Absent otherwise.
+	 */
+	filesNote?: string;
 }
 
 export interface NewFile {

package/src/index.ts

@@ -139,6 +139,7 @@ export const EDITOR_ROUTES = [
 	{ pattern: '/_caracms/history', entrypoint: 'editor/routes/history.ts' },
 	{ pattern: '/_caracms/try-again', entrypoint: 'editor/routes/try-again.ts' },
 	{ pattern: '/_caracms/notice', entrypoint: 'editor/routes/notice.ts' },
+	{ pattern: '/_caracms/discard', entrypoint: 'editor/routes/discard.ts' },
 	// M6 Decision 9: the inbox, both modes (the guard's prefix rule covers it in live mode).
 	{ pattern: '/_caracms/submissions/[...path]', entrypoint: 'editor/routes/submissions.ts' },
 ] as const;
@@ -281,18 +282,27 @@ export function trustedDomains(
 	return domains;
 }
 
-/**
- * The browser side of the editor imports React and idiomorph from the package.
- * Pre-bundled up front (dev only), so Vite doesn't discover them on the first
- * visit to /admin and reload the page to optimise them (a flicker, M2 Decision 9).
- */
 /** Vite's cache for every command but `astro dev`, apart from dev's `node_modules/.vite` (see its use). Relative to the site's root. */
 export const BUILD_VITE_CACHE = 'node_modules/.vite-caracms-build';
 
+/**
+ * Every bare import the package's browser code makes (the editor, and the site's own
+ * components such as the video player), pre-bundled up front in dev. Two reasons:
+ * - Vite doesn't discover them on the first visit to /admin and reload the page to
+ *   optimise them (a flicker, M2 Decision 9).
+ * - Installed from the registry (npm or pnpm), the package sits in the site's node_modules,
+ *   and Vite serves a bare import from it that isn't listed here as the dependency's raw
+ *   file. For a CommonJS one (react-dom) the browser refuses the module and the editor never
+ *   starts (caracms-cloud adversarial review, finding 12). The workspace's linked copy hides
+ *   this, so any new bare import in browser code goes here; test/pack-install.release.test.ts
+ *   checks it in a real browser.
+ */
 export const EDITOR_CLIENT_DEPS = [
 	'caracms > react',
 	'caracms > react/jsx-runtime',
 	'caracms > react/jsx-dev-runtime',
+	// Arrange pages' createPortal (arrange/ArrangeStage.tsx). react-dom's root is CommonJS.
+	'caracms > react-dom',
 	'caracms > react-dom/client',
 	'caracms > idiomorph',
 	// M5a: the rich-text field's editor (Tiptap on ProseMirror), browser only.
@@ -306,6 +316,9 @@ export const EDITOR_CLIENT_DEPS = [
 	'caracms > @tiptap/pm/view',
 	// M5b: a clip's upload straight to Mux, imported on the first one (client/media/store.ts).
 	'caracms > @mux/upchunk',
+	// The site's video player, imported on the first click on Play (components/media-player.ts).
+	// ESM, so served raw it still loaded, but unbundled, and one CommonJS file in its tree would break it.
+	'caracms > @mux/mux-player',
 	// The date field's calendar (pre-M7 polish).
 	'caracms > react-day-picker',
 ];

package/src/live/auth/login.ts

@@ -54,6 +54,7 @@ import {
 	type PageAssets,
 	type SafeHtml,
 } from './views.ts';
+import { readCappedText } from '../../body.ts';
 
 export const CONFIRM_PATH = `${LOGIN_PATH}/confirm`;
 export const SIGNOUT_PATH = `${LOGIN_PATH}/signout`;
@@ -80,9 +81,9 @@ const BASE_HEADERS = {
 class BodyTooLarge extends Error {}
 
 async function readBody(request: Request): Promise<string> {
-	if (Number(request.headers.get('content-length') ?? 0) > MAX_BODY_BYTES) throw new BodyTooLarge();
-	const text = await request.text();
-	if (Buffer.byteLength(text) > MAX_BODY_BYTES) throw new BodyTooLarge();
+	// caracms-cloud adversarial review, finding 10: counted as it's read, so a chunked body stops at the cap too.
+	const text = await readCappedText(request, MAX_BODY_BYTES);
+	if (text === null) throw new BodyTooLarge();
 	return text;
 }
 

package/src/live/auth/views.ts

@@ -313,8 +313,15 @@ export function emailView(input: { next: string; value?: string; invalid?: strin
  * rate-limited, send failed). It repeats the address typed, which the person already
  * knows, and says nothing about it.
  */
+/**
+ * caracms-cloud adversarial review, editor wording note (B3): the same answer for every
+ * address, so it never says whether one has access; this line tells someone who mistyped
+ * theirs, or wasn't invited, why nothing may come.
+ */
+export const SENT_BY_INVITATION = 'Sign-in is by invitation. If nothing arrives in a few minutes, check the address or ask whoever invited you.';
+
 export function sentView(input: { email: string; next: string; again: boolean; backupEnabled: boolean }): SafeHtml {
-	return html`<section class="si-card">${input.again ? html`<p class="notice ok" role="status">${ic('check', 'i-sm')}Sent again.</p>` : ''}<h1>Check your email</h1><p>If <strong>${input.email}</strong> can sign in, a link is on its way. It expires in 15 minutes.</p><p class="fine">Not there? Check spam, or send again.</p><div class="row-acts"><form method="post" action="${LOGIN_PATH}"><input type="hidden" name="email" value="${input.email}"><input type="hidden" name="next" value="${input.next}"><input type="hidden" name="again" value="1"><button class="btn" type="submit">Send again</button></form><a class="linkbtn" href="${loginHref({}, input.next)}">Use a different address</a></div></section>${input.backupEnabled ? backupLink(input.next) : ''}`;
+	return html`<section class="si-card">${input.again ? html`<p class="notice ok" role="status">${ic('check', 'i-sm')}Sent again.</p>` : ''}<h1>Check your email</h1><p>If <strong>${input.email}</strong> can sign in, a link is on its way. It expires in 15 minutes.</p><p class="fine">${SENT_BY_INVITATION}</p><p class="fine">Not there? Check spam, or send again.</p><div class="row-acts"><form method="post" action="${LOGIN_PATH}"><input type="hidden" name="email" value="${input.email}"><input type="hidden" name="next" value="${input.next}"><input type="hidden" name="again" value="1"><button class="btn" type="submit">Send again</button></form><a class="linkbtn" href="${loginHref({}, input.next)}">Use a different address</a></div></section>${input.backupEnabled ? backupLink(input.next) : ''}`;
 }
 
 /** Runs-anywhere Decision 7: the site was opened at an address that isn't its own (request.ts → `addressNotice`). */

package/src/live/autosaves.ts

@@ -4,8 +4,11 @@
  * - **`caracms:autosave:<file>`**: the whole document as the tab last sent it, with the
  *   base it was edited from, its text (`applyEdits(base, document)`), its editor and
  *   tab, and two times for the sweep: the first write since the last commit (the
- *   five-minute cap) and the newest write (the idle time). Expires after a week, as a
- *   backstop (`autosaveTtlMs`).
+ *   five-minute cap) and the newest write (the idle time). **It never expires**: it's an
+ *   edit that hasn't reached GitHub, so while commits fail (a lost token, an uninstalled
+ *   App) it waits for the sweep however long that takes (caracms-cloud adversarial review,
+ *   finding 4). Once committed it's deleted, and what's left of it, the committed record
+ *   below, expires a week later as before.
  * - **`caracms:committed:<file>`**: what the sweep last committed from a tab's editing
  *   session (its tab, its base, and the text it committed). The next commit from the
  *   same session merges against that text, not the session's first base, so the
@@ -40,6 +43,13 @@
  * moving it back to where it was drops the record, as does deleting it. A record only
  * counts while its old file is gone and its new file is there (`movesIn`, git.ts).
  *
+ * **Discards** (Discard changes) ride on **`caracms:changed:<file>`** (`ChangeRecord.discard`),
+ * which every poll on the document and every write to it already read, so a discard costs
+ * them no command of their own: who put the document back to what's live, when, and the tabs
+ * that had it open or were editing it then. Those tabs' writes are refused until each says it
+ * has let go of its copy (`ackDiscard`), so a tab that hasn't heard yet can't bring the
+ * discarded edits back. A write carries the discard forward for a week (`carryDiscard`).
+ *
  * Paths are site-relative (`content/pages/index.json`). Values are JSON text.
  *
  * **The status cache** (status-cache.ts, Redis diet Decision 2): every write here of a
@@ -110,6 +120,16 @@ export interface ChangeRecord {
 	at: string;
 	/** M5a: this change deleted the document (`by` deleted it). */
 	gone?: boolean;
+	/** Discard changes: the last time someone put the document back to what's live (see the header). */
+	discard?: DiscardRecord;
+}
+
+/** A document put back to what's live (Discard changes): `tabs` are the tabs whose copies are stale until they let go. */
+export interface DiscardRecord {
+	by: Person;
+	/** ISO. */
+	at: string;
+	tabs: string[];
 }
 
 /** A value with the raw text it was read as, for compare-and-swap. */
@@ -169,11 +189,9 @@ export class Autosaves {
 	readonly changedKey = (file: string) => `${this.prefix}changed:${file}`;
 	readonly movesKey = () => movesKey(this.prefix);
 
-	/** A compare-and-swap (or delete) on an autosave key, and the status cache told what came of it. */
+	/** A compare-and-swap (or delete) on an autosave key, and the status cache told what came of it. No expiry: a SET without PX also clears one an older version left. */
 	private async swap(key: string, expected: string | null, raw: string | null): Promise<boolean> {
-		const ok = await landed(this.cache, key, () =>
-			raw === null ? this.redis.compareAndDelete(key, expected!) : this.redis.compareAndSet(key, expected, raw, { px: this.timings.autosaveTtlMs }),
-		);
+		const ok = await landed(this.cache, key, () => (raw === null ? this.redis.compareAndDelete(key, expected!) : this.redis.compareAndSet(key, expected, raw)));
 		if (ok) this.cache?.string(key, raw);
 		else this.cache?.drop(key);
 		return ok;
@@ -212,11 +230,81 @@ export class Autosaves {
 		return this.swap(this.key(read.value.file), read.raw, null);
 	}
 
+	/**
+	 * An autosave written by caracms 0.8.0 or before, with the week's expiry it set: written
+	 * again as it is, with none (the sweep's startup check). Only if it's still what was read.
+	 */
+	async keepForever(read: Read<Autosave>): Promise<boolean> {
+		if ((await this.redis.pttl(this.key(read.value.file))) < 0) return false;
+		return this.swap(this.key(read.value.file), read.raw, read.raw);
+	}
+
 	/** Replace it only if it's still what was read. */
 	replaceIf(read: Read<Autosave>, next: Autosave): Promise<boolean> {
 		return this.swap(this.key(next.file), read.raw, JSON.stringify(next));
 	}
 
+	/**
+	 * Discard changes: delete the autosave whatever it holds (a newer write is deleted too),
+	 * returning each one deleted, so the caller knows whose tabs had it.
+	 */
+	async removeAll(file: string): Promise<Autosave[]> {
+		const gone: Autosave[] = [];
+		for (let attempt = 0; attempt < 8; attempt++) {
+			const read = await this.get(file);
+			if (!read) return gone;
+			if (await this.removeIf(read)) gone.push(read.value);
+		}
+		throw new Error(`caracms: the autosave for ${file} kept changing under the discard.`);
+	}
+
+	/** Discard changes: the session's committed record goes with the edit it recorded. */
+	async forgetCommitted(file: string): Promise<void> {
+		await this.redis.del(this.committedKey(file));
+	}
+
+	/** Discard changes: every move record from or to these files, and their live addresses, go. */
+	async forgetMovesOf(files: readonly string[]): Promise<void> {
+		const key = movesKey(this.prefix);
+		const all = Object.entries(await this.redis.hgetall(key));
+		const drop = all
+			.filter(([k, v]) => (k.startsWith(ADDRESS_FIELD) ? files.includes(k.slice(ADDRESS_FIELD.length)) : files.includes(k) || files.includes(v)))
+			.map(([k]) => k);
+		if (drop.length === 0) return;
+		await landed(this.cache, key, () => this.redis.hdel(key, ...drop));
+		this.cache?.hash(key, {}, drop);
+	}
+
+	/** The autosave and the change record in one MGET (the write route reads both: Discard changes costs it no command). */
+	async getWithChange(file: string): Promise<[Read<Autosave> | null, ChangeRecord | null]> {
+		const [raw, changed] = await this.redis.mget([this.key(file), this.changedKey(file)]);
+		const value = parse<Autosave>(raw ?? null);
+		return [raw !== null && raw !== undefined && value ? { raw, value } : null, Autosaves.changedFrom(changed ?? null)];
+	}
+
+	/** The discard a write should keep on the change record it makes: the one there, while under a week old. */
+	carryDiscard(record: ChangeRecord | null): Pick<ChangeRecord, 'discard'> {
+		const d = record?.discard;
+		return d && this.now() - Date.parse(d.at) < this.timings.autosaveTtlMs ? { discard: d } : {};
+	}
+
+	/** A tab has let go of its copy of a discarded document: its writes are taken again. */
+	async ackDiscard(file: string, tab: string): Promise<void> {
+		const key = this.changedKey(file);
+		for (let attempt = 0; attempt < 5; attempt++) {
+			const raw = await this.redis.get(key);
+			const record = Autosaves.changedFrom(raw);
+			if (!record?.discard || !record.discard.tabs.includes(tab)) return;
+			const next = JSON.stringify({ ...record, discard: { ...record.discard, tabs: record.discard.tabs.filter((t) => t !== tab) } });
+			const ok = await landed(this.cache, key, () => this.redis.compareAndSet(key, raw, next));
+			if (ok) {
+				this.cache?.string(key, next);
+				return;
+			}
+			this.cache?.drop(key);
+		}
+	}
+
 	async committed(file: string): Promise<Committed | null> {
 		return parse<Committed>(await this.redis.get(this.committedKey(file)));
 	}

package/src/live/cloud.ts

@@ -12,11 +12,18 @@
  * - `cloudSettings()`: the site's repo from those settings (`github.repo`; null is
  *   `no_repo`, with the cloud's own sentence). Only the editor needs a repo.
  * - `cloudToken()`: `POST /v1/github/token`, a fresh installation token on the site's repo,
- *   about an hour long. `GitHubClient` calls it and refreshes five minutes early.
+ *   about an hour long. `GitHubClient` calls it and refreshes five minutes early. It waits
+ *   35 s (`CLOUD_TOKEN_TIMEOUT_MS`), every other call 20 s (`CLOUD_TIMEOUT_MS`).
+ * - `confirmCloudRepo()`: a token answer naming another repo is a rename or transfer on
+ *   GitHub (the cloud's M2b: "A `full_name` change GitHub reports updates the site's repo").
+ *   The settings are read again; when they name it too, the held copy takes the new repo
+ *   and `GitHubClient` carries on under it.
  * - **A refusal** (any answer that isn't 2xx, carrying `{ error, message }`) throws a
  *   `CloudRefusal` with the cloud's `message` as it came, and `installUrl` when there is
  *   one. A cloud that can't be reached, or answers with something else, throws a
- *   `CloudRefusal` whose `error` is `unreachable`, with the package's own sentence.
+ *   `CloudRefusal` whose `error` is `unreachable`, with the package's own sentence and a
+ *   `detail` for logs (timed out, the connection failed, or the status of an answer that
+ *   wasn't the API's).
  *
  * - `cloudUnavailable()`: the sign-in guard's 503 for a refusal at start (Decision 14),
  *   the sentence escaped and the install link a link.
@@ -33,19 +40,37 @@ export const CLOUD_KEY_SHAPE = /^cck_[A-Za-z0-9_-]{43}$/;
 export const CLOUD_UNREACHABLE = "CaraCMS Cloud couldn't be reached, so the editor can't start. Try again in a minute.";
 /** M3 Decision 20: the build's own sentence for a cloud it can't reach. */
 export const CLOUD_UNREACHABLE_BUILD = "CaraCMS Cloud couldn't be reached, so the site can't be built. Try again in a minute.";
-/** The cloud's own `no_repo` sentence (Contracts), for `github.repo: null` in the settings. */
-export const CLOUD_NO_REPO = 'This site has no GitHub repo in CaraCMS Cloud yet. Ask CaraCMS to set one.';
-/** Decision 13: a token answer named another repo than the one the server started with. */
-export const CLOUD_REPO_CHANGED = (repo: string) => `This site's repo was changed in CaraCMS Cloud to ${repo}. Restart the server to use it.`;
+/**
+ * The cloud's own `no_repo` sentence, word for word (caracms-cloud `convex/http.ts`, the token
+ * route), for `github.repo: null` in the settings, which carry no sentence of their own. The
+ * token route's `no_repo` refusal is shown as it came (`cloudCall`); this is only the copy for
+ * the settings (caracms-cloud adversarial review, seam note: it was M1's "Ask CaraCMS to set one").
+ */
+export const CLOUD_NO_REPO = 'This site has no GitHub repo in CaraCMS Cloud yet. A team owner can pick one in app.caracms.com.';
+/**
+ * A token answer named another repo than the one the server is on, and the settings, read
+ * again, don't say so yet (or couldn't be read): this refresh fails, and the next one asks
+ * again (caracms-cloud adversarial review, finding 7; once the settings agree, the new name
+ * is taken, github.ts).
+ */
+export const CLOUD_REPO_CHANGED = (repo: string) =>
+	`This site's repo is now ${repo} on GitHub, but CaraCMS Cloud's settings don't say so yet, so changes can't be saved to GitHub for now. The editor tries again on its own; if this stays, ask CaraCMS to check the site.`;
 
 /** How long a call to the cloud may take before it counts as unreachable. */
 export const CLOUD_TIMEOUT_MS = 20_000;
+/**
+ * The token call's own, longer timeout (caracms-cloud adversarial review, seam note): the
+ * cloud's worst case, an id mint refused and then the installation found and a token minted
+ * by name (10 s to GitHub each), can pass 20 s, which would read as `unreachable`.
+ */
+export const CLOUD_TOKEN_TIMEOUT_MS = 35_000;
 
 export interface CloudConnection {
 	key: string;
 	url: string;
 	/** For tests. Default: global fetch. */
 	fetch?: typeof fetch;
+	/** Default: `CLOUD_TIMEOUT_MS`, or `CLOUD_TOKEN_TIMEOUT_MS` for `cloudToken()`. */
 	timeoutMs?: number;
 }
 
@@ -66,27 +91,30 @@ export function isCloudRefusal(value: unknown): value is CloudRefusal {
 /** The cloud said no (or couldn't be reached). `message` is safe to show and to log. */
 export class CloudRefusal extends Error {
 	readonly [REFUSAL_BRAND] = true;
-	/** The cloud's `error` (`no_repo`, `app_not_installed`, `unknown_key`…), or the package's `unreachable` / `repo_changed`. */
+	/** The cloud's `error` (`no_repo`, `app_not_installed`, `unknown_key`…), or the package's `unreachable` / `repo_changed` (finding 7: a rename the settings don't confirm yet). */
 	readonly error: string;
 	/** An `https://` link the message names (the App's install page), or null. */
 	readonly installUrl: string | null;
-	constructor(error: string, message: string, installUrl: string | null = null) {
+	/** For `unreachable`, what happened, for a log line (never a secret): `timed out`, `answered HTTP 502`… */
+	readonly detail: string | null;
+	constructor(error: string, message: string, installUrl: string | null = null, detail: string | null = null) {
 		super(message);
 		this.name = 'CloudRefusal';
 		this.error = error;
 		this.installUrl = installUrl;
+		this.detail = detail;
 	}
 }
 
-const unreachable = () => new CloudRefusal('unreachable', CLOUD_UNREACHABLE);
+const unreachable = (detail: string | null = null) => new CloudRefusal('unreachable', CLOUD_UNREACHABLE, null, detail);
 
 /**
  * One call to the API: `path` with its query, a JSON `body` for a POST. The answer's JSON
  * object, or a `CloudRefusal` (the cloud's own, or `unreachable`). The media bucket
  * (editor/server/media/cloud-bucket.ts) calls it too.
  */
-export async function cloudCall(connection: CloudConnection, method: 'GET' | 'POST', path: string, body?: unknown): Promise<Record<string, unknown>> {
-	let res: Response;
+export async function cloudCall(connection: CloudConnection, method: 'GET' | 'POST', path: string, body?: unknown, defaultTimeoutMs = CLOUD_TIMEOUT_MS): Promise<Record<string, unknown>> {
+	let res: Response | undefined;
 	let answer: unknown;
 	try {
 		res = await (connection.fetch ?? fetch)(`${connection.url}${path}`, {
@@ -98,17 +126,18 @@ export async function cloudCall(connection: CloudConnection, method: 'GET' | 'PO
 				...(body === undefined ? {} : { 'content-type': 'application/json' }),
 			},
 			...(body === undefined ? {} : { body: JSON.stringify(body) }),
-			signal: AbortSignal.timeout(connection.timeoutMs ?? CLOUD_TIMEOUT_MS),
+			signal: AbortSignal.timeout(connection.timeoutMs ?? defaultTimeoutMs),
 		});
 		answer = await res.json();
-	} catch {
-		throw unreachable();
+	} catch (error) {
+		const timedOut = (error as { name?: unknown } | null)?.name === 'TimeoutError';
+		throw unreachable(timedOut ? 'timed out' : res ? `answered HTTP ${res.status}, not with JSON` : 'the connection failed');
 	}
 	const object = answer && typeof answer === 'object' && !Array.isArray(answer) ? (answer as Record<string, unknown>) : null;
-	if (!object) throw unreachable();
+	if (!object) throw unreachable(`answered HTTP ${res.status}, not with an object`);
 	if (!res.ok) {
 		const { error, message, installUrl } = object;
-		if (typeof error !== 'string' || typeof message !== 'string' || !message.trim()) throw unreachable();
+		if (typeof error !== 'string' || typeof message !== 'string' || !message.trim()) throw unreachable(`answered HTTP ${res.status} without a reason`);
 		throw new CloudRefusal(error, message, typeof installUrl === 'string' && /^https:\/\//i.test(installUrl) ? installUrl : null);
 	}
 	return object;
@@ -147,9 +176,9 @@ export async function fetchCloudSettings(connection: CloudConnection): Promise<C
 	const github = answer.github as { repo?: unknown } | undefined;
 	const media = answer.media as { bucket?: unknown; imageHost?: unknown } | undefined;
 	const pair = answer.imgproxy as { key?: unknown; salt?: unknown } | undefined;
-	if (!github || typeof github !== 'object') throw unreachable();
+	if (!github || typeof github !== 'object') throw unreachable('answered settings without github');
 	const m = typeof github.repo === 'string' ? REPO.exec(github.repo) : null;
-	if (github.repo !== null && !m) throw unreachable();
+	if (github.repo !== null && !m) throw unreachable('answered settings with a malformed repo');
 	const folder = str(answer.folder);
 	const bucket = str(media && typeof media === 'object' ? media.bucket : null);
 	const imageHost = str(media && typeof media === 'object' ? media.imageHost : null);
@@ -221,14 +250,29 @@ export function heldCloudSettings(connection: Pick<CloudConnection, 'key' | 'url
 	return h.failure ? { kind: 'failed', refusal: h.failure } : null;
 }
 
+/**
+ * caracms-cloud adversarial review, finding 7: a token answer named `fullName`, not the repo
+ * the server is on. `GET /v1/settings` afresh: when it names `fullName` too, that repo is
+ * returned and the held copy takes it (a start later in this process begins on it; the media
+ * are left as held). Null when the settings name another repo, or none, or can't be read.
+ */
+export async function confirmCloudRepo(connection: CloudConnection, fullName: string): Promise<{ owner: string; repo: string } | null> {
+	const settings = await fetchCloudSettings(connection).catch(() => null);
+	const repo = settings?.repo ?? null;
+	if (!repo || `${repo.owner}/${repo.repo}`.toLowerCase() !== fullName.toLowerCase()) return null;
+	const h = held()[HELD];
+	if (h?.value && h.key === connection.key && h.url === connection.url) h.value = { ...h.value, repo };
+	return repo;
+}
+
 /** Forget the held settings (tests). */
 export function resetCloudSettings(): void {
 	delete held()[HELD];
 }
 
-/** A fresh installation token on the site's repo, from `POST /v1/github/token`. */
+/** A fresh installation token on the site's repo, from `POST /v1/github/token` (35 s unless `timeoutMs` says otherwise). */
 export async function cloudToken(connection: CloudConnection): Promise<{ token: string; expiresAt: number; repo: string }> {
-	const answer = await cloudCall(connection, 'POST', '/v1/github/token');
+	const answer = await cloudCall(connection, 'POST', '/v1/github/token', undefined, CLOUD_TOKEN_TIMEOUT_MS);
 	const { token, expiresAt, repo } = answer;
 	const at = typeof expiresAt === 'string' ? Date.parse(expiresAt) : Number.NaN;
 	if (typeof token !== 'string' || !token || Number.isNaN(at) || typeof repo !== 'string') throw unreachable();