caracms 0.2.0 → 0.3.0

package/src/live/git.ts

@@ -42,9 +42,11 @@ import { movesKey } from './autosaves.ts';
 import type { WaitingChange } from '../editor/types.ts';
 import { MissingBranchError, StaleHeadError, type Branch, type CommitSummary, type Comparison, type GitBackend, type Head, type Heads, type TreeChange } from './backend.ts';
 import { HttpError } from './github.ts';
+import { runningCommitFrom } from './mode.ts';
 import { mergeFile } from './merge.ts';
 import { draftMessage, mergeMessage, parseMessage, publishMessage, type Person } from './messages.ts';
 import type { RedisClient } from './redis.ts';
+import { landed, StatusCache } from './status-cache.ts';
 import { DEFAULT_TIMINGS, type LiveTimings } from './timings.ts';
 import { publishState, waitingFromCommits, type DeploymentFact, type PublishRecord, type PublishState, type WaitingFile } from './status.ts';
 
@@ -103,14 +105,20 @@ export interface HistoryEntry {
 	state: PublishState;
 }
 
-export interface RailwayConfig {
-	/** CARACMS_RAILWAY_TOKEN: a project token (Decision 12). */
-	token: string;
-	serviceId: string;
-	environmentId: string;
-	/** For tests. Default: global fetch. */
-	fetch?: typeof fetch;
-}
+/**
+ * Try again's redeployer (runs-anywhere Decision 11): Railway's API with a project token
+ * (`CARACMS_RAILWAY_TOKEN`, M4 Decision 12), or a deploy hook (`CARACMS_DEPLOY_HOOK_URL`):
+ * one bare POST, any 2xx a success. The hook's URL is a secret: never logged or sent on.
+ */
+export type Redeployer =
+	| { kind: 'railway'; token: string; serviceId: string; environmentId: string; fetch?: typeof fetch }
+	| { kind: 'hook'; url: string; fetch?: typeof fetch; timeoutMs?: number };
+
+/** A deploy hook that hasn't answered in this long has failed (it's one POST; nothing retries by itself). */
+export const DEPLOY_HOOK_TIMEOUT_MS = 20_000;
+
+/** Try again's answer when no redeployer is set: no host's name (Decision 11). */
+export const NO_REDEPLOYER_REASON = "Try again isn't set up on this site: a developer can redeploy it.";
 
 export interface LiveGitOptions {
 	backend: GitBackend;
@@ -119,12 +127,16 @@ export interface LiveGitOptions {
 	now?: () => number;
 	sleep?: (ms: number) => Promise<void>;
 	log?: (line: string) => void;
-	/** The running server's commit, read on every status (tests move it). Default: CARACMS_RUNNING_COMMIT or RAILWAY_GIT_COMMIT_SHA. */
+	/** The running server's commit, read on every status (tests move it). Default: mode.ts → `runningCommitFrom` over the environment and `bakedCommit`. */
 	runningCommit?: () => string | null;
+	/** The commit baked in at build (runs-anywhere Decision 9), for the default `runningCommit`. */
+	bakedCommit?: string | null;
 	timings?: Partial<LiveTimings>;
-	railway?: RailwayConfig | null;
+	redeployer?: Redeployer | null;
 	/** Redis key prefix. Default `caracms:`. */
 	keyPrefix?: string;
+	/** The status poll's cache (Redis diet), told of the publish lock, the publish record and the moves Publish clears. Default: one of its own. */
+	statusCache?: StatusCache;
 }
 
 /** The site file that holds Site Settings, relative to the site (Decision 15). Defined in config.ts (M5a: the reserved `settings` collection). */
@@ -153,6 +165,12 @@ export class LiveGit {
 	readonly redis: RedisClient;
 	readonly timings: LiveTimings;
 	readonly now: () => number;
+	/**
+	 * The status poll's write-through cache (status-cache.ts, Redis diet Decisions 1–5),
+	 * one per process: kept here because this module writes some of what it holds; the
+	 * live editor's autosaves, locks and notices write through the same one.
+	 */
+	readonly statusCache: StatusCache;
 	/** Phase 2 fills this: commit every pending autosave (Decision 10 step 1; Decision 8 before a merge). */
 	commitPending: () => Promise<void> = async () => {};
 	/**
@@ -168,7 +186,7 @@ export class LiveGit {
 	private readonly sleep: (ms: number) => Promise<void>;
 	private readonly log: (line: string) => void;
 	private readonly runningCommit: () => string | null;
-	private readonly railway: RailwayConfig | null;
+	private readonly redeployer: Redeployer | null;
 	private readonly keyPrefix: string;
 
 	private copyHead: Head | null = null;
@@ -194,9 +212,11 @@ export class LiveGit {
 		this.now = options.now ?? Date.now;
 		this.sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
 		this.log = options.log ?? ((line) => console.log(`[caracms] ${line}`));
-		this.runningCommit = options.runningCommit ?? (() => process.env.CARACMS_RUNNING_COMMIT || process.env.RAILWAY_GIT_COMMIT_SHA || null);
-		this.railway = options.railway ?? null;
+		const baked = options.bakedCommit ?? null;
+		this.runningCommit = options.runningCommit ?? (() => runningCommitFrom(process.env, baked));
+		this.redeployer = options.redeployer ?? null;
 		this.keyPrefix = options.keyPrefix ?? 'caracms:';
+		this.statusCache = options.statusCache ?? new StatusCache({ redis: this.redis, maxAgeMs: this.timings.statusCacheMs, now: this.now });
 		this.prefix = repoPrefix(options.site);
 		// Every collection's folder, shared blocks' included (M5a Decision 8); Site Settings is its one file (inScope).
 		this.folders = Object.values(options.site.collections)
@@ -241,6 +261,20 @@ export class LiveGit {
 		return `${this.keyPrefix}${name}`;
 	}
 
+	/** The Publish lock's key (one Publish at a time) and the newest publish's record's (Decision 10, 12). */
+	get publishLockKey(): string {
+		return this.key('publish:lock');
+	}
+	get publishRecordKey(): string {
+		return this.key('publish:last');
+	}
+
+	private async setPublishRecord(record: PublishRecord): Promise<void> {
+		const raw = JSON.stringify(record);
+		await landed(this.statusCache, this.publishRecordKey, () => this.redis.set(this.publishRecordKey, raw));
+		this.statusCache.string(this.publishRecordKey, raw);
+	}
+
 	/** Run `fn` alone among this server's git operations, so the copy is never changed by two at once. */
 	private exclusive<T>(fn: () => Promise<T>): Promise<T> {
 		const run = this.queue.then(fn, fn);
@@ -642,9 +676,11 @@ export class LiveGit {
 	 * Redis lock); a second press while one runs joins it.
 	 */
 	async publish(by: Person): Promise<PublishResult> {
-		const lock = this.key('publish:lock');
+		const lock = this.publishLockKey;
 		const token = randomBytes(12).toString('base64url');
-		if (!(await this.redis.set(lock, token, { nx: true, px: this.timings.publishLockMs }))) {
+		const taken = await landed(this.statusCache, lock, () => this.redis.set(lock, token, { nx: true, px: this.timings.publishLockMs }));
+		if (taken) this.statusCache.string(lock, token);
+		else {
 			const until = this.now() + this.timings.publishLockMs;
 			while (this.now() < until && (await this.redis.get(lock)) !== null) await this.sleep(500);
 			return { kind: 'joined', record: await this.lastPublish() };
@@ -659,7 +695,10 @@ export class LiveGit {
 				throw new Error(`caracms: publish gave up after ${MAX_ATTEMPTS} tries (main or drafts kept moving).`);
 			});
 		} finally {
-			await this.redis.compareAndDelete(lock, token).catch(() => {});
+			// Let go: gone when it was still ours; otherwise (it expired and someone else took it, or the call failed) not known here.
+			const gone = await this.redis.compareAndDelete(lock, token).catch(() => false);
+			if (gone) this.statusCache.string(lock, null);
+			else this.statusCache.drop(lock);
 		}
 	}
 
@@ -710,16 +749,28 @@ export class LiveGit {
 		this.historyCache = null;
 		// The moves this publish took live are done with (a move made since stays waiting).
 		const published = [...records].filter(([old]) => files.includes(old)).map(([old]) => old);
-		if (published.length) await this.redis.hdel(movesKey(this.keyPrefix), ...published).catch(() => 0);
+		if (published.length) {
+			const moves = movesKey(this.keyPrefix);
+			const cleared = await this.redis.hdel(moves, ...published).then(
+				() => true,
+				() => false,
+			);
+			if (cleared) this.statusCache.hash(moves, {}, published);
+			else this.statusCache.drop(moves);
+		}
 		const record: PublishRecord = { commit, by, at: new Date(this.now()).toISOString(), files, titles, tryAgainAt: null };
-		await this.redis.set(this.key('publish:last'), JSON.stringify(record));
+		await this.setPublishRecord(record);
 		this.log(`published ${commit.slice(0, 7)} (attempt ${attempt}): ${titles.join(', ')}`);
 		return { kind: 'published', record, attempts: attempt, fileTitles };
 	}
 
 	/** The newest publish, from Redis. */
 	async lastPublish(): Promise<PublishRecord | null> {
-		const raw = await this.redis.get(this.key('publish:last'));
+		return LiveGit.publishRecordFrom(await this.redis.get(this.publishRecordKey));
+	}
+
+	/** A publish record from its text as read (the status cache's, on a poll). */
+	static publishRecordFrom(raw: string | null): PublishRecord | null {
 		if (!raw) return null;
 		try {
 			return JSON.parse(raw) as PublishRecord;
@@ -842,14 +893,15 @@ export class LiveGit {
 	// ── Publish status (Decision 12) ────────────────────────────────────────────
 
 	/** The newest publish's state. Asks GitHub at most every `deploymentReadMs`, and only while it isn't live. */
-	async publishStatus(): Promise<PublishStatus> {
-		const record = await this.lastPublish();
+	async publishStatus(options: { record?: PublishRecord | null } = {}): Promise<PublishStatus> {
+		// `record`: the newest publish as the caller read it (the status poll's cache); otherwise read here.
+		const record = options.record !== undefined ? options.record : await this.lastPublish();
 		if (!record) return { state: 'none', record: null, assumed: false, canTryAgain: false };
 		const running = this.runningCommit();
 		if (running === null) {
 			if (!this.assumedLogged) {
 				this.assumedLogged = true;
-				this.log('no RAILWAY_GIT_COMMIT_SHA or CARACMS_RUNNING_COMMIT: no deploy pipeline, so a publish reads as live once its refs moved');
+				this.log('no running commit known (CARACMS_RUNNING_COMMIT, a host\'s commit variable, or one baked in at build): a publish reads as live once its refs moved');
 			}
 			return { state: 'live', record, assumed: true, canTryAgain: false };
 		}
@@ -858,8 +910,8 @@ export class LiveGit {
 			let facts: DeploymentFact[] = [];
 			let later = new Set<string>();
 			if (!includes) ({ facts, later } = await this.deploymentFacts(record));
-			const { state } = publishState({ record, running, runningIncludesPublish: includes, laterOnMain: later, deployments: facts });
-			return { state, record, assumed: false, canTryAgain: state === 'failed' && this.railway !== null };
+			const { state } = publishState({ record, running, runningIncludesPublish: includes, laterOnMain: later, deployments: facts, now: this.now(), slowAfterMs: this.timings.publishSlowMs });
+			return { state, record, assumed: false, canTryAgain: (state === 'failed' || state === 'slow') && this.redeployer !== null };
 		});
 	}
 
@@ -904,7 +956,7 @@ export class LiveGit {
 		} catch (error) {
 			if (error instanceof HttpError && (error.status === 403 || error.status === 404)) {
 				this.deploymentsDenied = true;
-				this.log(`can't read GitHub Deployments (${error.status}): the App needs "Deployments: read". A publish will show as publishing until the server runs it.`);
+				this.log(`can't read GitHub Deployments (${error.status}): the site's GitHub token or App needs "Deployments: read" to tell a failed publish. Without it, a publish shows as publishing until the server runs it, then as taking longer than usual.`);
 				return { facts: [], later: new Set() };
 			}
 			throw error;
@@ -930,7 +982,7 @@ export class LiveGit {
 				const parsed = parseMessage(c.message);
 				if (parsed.kind !== 'publish') return;
 				const live = running === null || (runningAt !== -1 && i >= runningAt) || (status.record?.commit === c.sha && status.state === 'live');
-				const pending: PublishState = status.state === 'failed' ? 'failed' : 'publishing';
+				const pending: PublishState = status.state === 'failed' || status.state === 'slow' ? status.state : 'publishing';
 				entries.push({ commit: c.sha, by: parsed.publishedBy, at: c.date, titles: parsed.titles, files: parsed.publishedFiles, state: live ? 'live' : pending });
 			});
 			this.historyCache = { at: this.now(), entries };
@@ -940,13 +992,26 @@ export class LiveGit {
 
 	// ── Try again (Decision 12) ─────────────────────────────────────────────────
 
-	/** Redeploy through Railway's API with the project token. Never publishes again. */
+	/**
+	 * Redeploy through the redeployer (runs-anywhere Decision 11): Railway's API with the
+	 * project token, or the deploy hook's one POST. Never publishes again, and never
+	 * retries by itself. A success restarts the "taking longer than usual" clock.
+	 */
 	async tryAgain(): Promise<{ ok: true } | { ok: false; reason: string }> {
-		if (!this.railway) return { ok: false, reason: 'No CARACMS_RAILWAY_TOKEN: a developer can redeploy from Railway.' };
+		if (!this.redeployer) return { ok: false, reason: NO_REDEPLOYER_REASON };
 		const record = await this.lastPublish();
 		if (!record) return { ok: false, reason: 'Nothing has been published.' };
-		const { token, serviceId, environmentId } = this.railway;
-		const res = await (this.railway.fetch ?? fetch)(RAILWAY_API, {
+		const r = this.redeployer.kind === 'hook' ? await this.callHook(this.redeployer) : await this.redeployOnRailway(this.redeployer);
+		if (!r.ok) return r;
+		await this.setPublishRecord({ ...record, tryAgainAt: new Date(this.now()).toISOString() });
+		this.deploymentsCache = null;
+		this.log(`try again: ${this.redeployer.kind === 'hook' ? 'the deploy hook took it' : 'Railway is redeploying'} (publish ${record.commit.slice(0, 7)})`);
+		return { ok: true };
+	}
+
+	private async redeployOnRailway(railway: Extract<Redeployer, { kind: 'railway' }>): Promise<{ ok: true } | { ok: false; reason: string }> {
+		const { token, serviceId, environmentId } = railway;
+		const res = await (railway.fetch ?? fetch)(RAILWAY_API, {
 			method: 'POST',
 			headers: { 'content-type': 'application/json', 'project-access-token': token },
 			body: JSON.stringify({
@@ -956,15 +1021,28 @@ export class LiveGit {
 		});
 		const body = (await res.json().catch(() => ({}))) as { data?: { serviceInstanceRedeploy?: boolean }; errors?: { message: string }[] };
 		if (!res.ok || body.errors?.length || !body.data?.serviceInstanceRedeploy) {
-			const reason = body.errors?.map((e) => e.message).join('; ') || `Railway answered ${res.status}`;
+			const reason = body.errors?.map((e) => e.message).join('; ') || `the host answered ${res.status}`;
 			this.log(`try again: Railway refused the redeploy (${reason})`);
 			return { ok: false, reason };
 		}
-		await this.redis.set(this.key('publish:last'), JSON.stringify({ ...record, tryAgainAt: new Date(this.now()).toISOString() }));
-		this.deploymentsCache = null;
-		this.log(`try again: Railway is redeploying (publish ${record.commit.slice(0, 7)})`);
 		return { ok: true };
 	}
+
+	/** The deploy hook: one POST, no body, no extra headers; any 2xx is success. The URL is never logged or returned. */
+	private async callHook(hook: Extract<Redeployer, { kind: 'hook' }>): Promise<{ ok: true } | { ok: false; reason: string }> {
+		let reason: string;
+		try {
+			const res = await (hook.fetch ?? fetch)(hook.url, { method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(hook.timeoutMs ?? DEPLOY_HOOK_TIMEOUT_MS) });
+			await res.body?.cancel().catch(() => {});
+			if (res.status >= 200 && res.status < 300) return { ok: true };
+			reason = `the deploy hook answered ${res.status}`;
+		} catch (error) {
+			const name = error instanceof Error ? error.name : '';
+			reason = name === 'TimeoutError' || name === 'AbortError' ? "the deploy hook didn't answer in time" : "the deploy hook couldn't be reached";
+		}
+		this.log(`try again: ${reason}`);
+		return { ok: false, reason };
+	}
 }
 
 export interface Moves {

package/src/live/github.ts

@@ -1,6 +1,9 @@
 /**
- * GitHub as the site's App (M4 Phase 1; lifted from M1's spike, `spikes/git/src/github.ts`).
+ * GitHub as the site's App or a fine-grained token (M4 Phase 1, lifted from M1's spike,
+ * `spikes/git/src/github.ts`; the token from runs-anywhere Decision 3).
  *
+ * - **A fine-grained token** (`CARACMS_GITHUB_TOKEN`) is the bearer as it is. GitHub sends
+ *   its expiry on every response, which is kept for the editor (Decision 5).
  * - **The App's JWT**: RS256, signed with the App's private key, `iat` backdated a
  *   minute for clock drift, nine minutes long (GitHub's limit is ten).
  * - **An installation token scoped to the one repo**: the installation is found with
@@ -14,16 +17,18 @@
  *   that stops answering fails the operation instead of holding it (and Publish's or
  *   the check's callers) forever.
  *
- * The private key is never logged.
+ * - **Access problems** (Decision 5): every response is watched for a refused credential
+ *   (401), a write refused for lack of a permission (403 "not accessible"), and, for a
+ *   token, an expiry within 14 days. `accessProblem()` says which holds now; a later
+ *   success clears the first two.
+ *
+ * The private key and the token are never logged.
  */
 import { createSign } from 'node:crypto';
 
 const API = 'https://api.github.com';
 
-export interface AppConnection {
-	appId: string;
-	/** The PEM. Railway variables often carry it with literal `\n`s; those are turned back into newlines. */
-	privateKey: string;
+interface ConnectionBase {
 	owner: string;
 	repo: string;
 	/** For tests. Default: global fetch. */
@@ -34,6 +39,63 @@ export interface AppConnection {
 	timeoutMs?: number;
 }
 
+export interface AppConnection extends ConnectionBase {
+	appId: string;
+	/** The PEM. Railway variables often carry it with literal `\n`s; those are turned back into newlines. */
+	privateKey: string;
+}
+
+/** A fine-grained personal access token on the one repo (Decision 3). */
+export interface TokenConnection extends ConnectionBase {
+	token: string;
+}
+
+export type GitHubConnection = AppConnection | TokenConnection;
+
+/**
+ * What's wrong with GitHub access right now (Decision 5), shown in the editor while it holds.
+ * `credential` says which one the site uses, so the sentence names the right fix.
+ */
+export type GitHubAccessProblem =
+	| { kind: 'refused'; credential: 'app' | 'token' }
+	| { kind: 'permission'; credential: 'app' | 'token'; permission: string }
+	| { kind: 'expiring'; credential: 'token'; expires: string };
+
+/** A token expiring within this long shows in the editor (Decision 5). */
+export const TOKEN_EXPIRY_WARNING_MS = 14 * 24 * 60 * 60_000;
+
+/** The permission every write needs; Deployments read is optional and never shown (Decision 10). */
+const CONTENTS_PERMISSION = 'Contents: Read and write';
+
+/**
+ * `github-authentication-token-expiration`: "2026-11-03 10:00:00 UTC" or "… -0700".
+ * Null when it doesn't parse.
+ */
+export function parseTokenExpiry(value: string | null): number | null {
+	const m = value && /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}(?::\d{2})?)\s*(UTC|Z|[+-]\d{2}:?\d{2})?$/i.exec(value.trim());
+	if (!m) return null;
+	const zone = !m[3] || /^(utc|z)$/i.test(m[3]) ? 'Z' : m[3].replace(/^([+-]\d{2}):?(\d{2})$/, '$1:$2');
+	const at = Date.parse(`${m[1]}T${m[2]}${zone}`);
+	return Number.isNaN(at) ? null : at;
+}
+
+/** The sentence the editor shows for an access problem, for the developer it's forwarded to. */
+export function accessProblemMessage(problem: GitHubAccessProblem): string {
+	const what = problem.credential === 'token' ? 'GitHub token (CARACMS_GITHUB_TOKEN)' : 'GitHub App';
+	switch (problem.kind) {
+		case 'refused':
+			return problem.credential === 'token'
+				? `GitHub refused this site's ${what}: it may have expired or been revoked. Changes can't be saved to GitHub until a developer makes a new fine-grained token and sets it.`
+				: `GitHub refused this site's ${what}: it may have been uninstalled from the repo or suspended. Changes can't be saved to GitHub until a developer reinstalls it.`;
+		case 'permission':
+			return `GitHub refused a change because this site's ${what} lacks the "${problem.permission}" permission. A developer can add it in the ${problem.credential === 'token' ? "token's settings" : "App's settings"}.`;
+		case 'expiring': {
+			const date = new Date(problem.expires).toLocaleDateString('en-IE', { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'UTC' });
+			return `This site's ${what} expires on ${date}. After that, changes can't be saved to GitHub: a developer can regenerate it, or make a new one, and set it before then.`;
+		}
+	}
+}
+
 /** A GitHub request that takes longer than this fails (its caller treats it as any failure). */
 export const GITHUB_TIMEOUT_MS = 20_000;
 
@@ -143,6 +205,8 @@ export class GitHubClient {
 	readonly tracker: Tracker;
 	readonly owner: string;
 	readonly repo: string;
+	/** Which credential this client signs in with. */
+	readonly credential: 'app' | 'token';
 	private readonly appId: string;
 	private readonly key: string;
 	private readonly fetcher: typeof fetch;
@@ -151,10 +215,23 @@ export class GitHubClient {
 	private token = '';
 	private tokenExpires = 0;
 	private signingIn: Promise<void> | null = null;
+	/** Decision 5: what the last responses said about access. */
+	private refused = false;
+	private missingPermission: string | null = null;
+	private personalTokenExpires: number | null = null;
 
-	constructor(connection: AppConnection, tracker: Tracker) {
-		this.appId = connection.appId;
-		this.key = connection.privateKey.includes('\\n') ? connection.privateKey.replace(/\\n/g, '\n') : connection.privateKey;
+	constructor(connection: GitHubConnection, tracker: Tracker) {
+		if ('token' in connection) {
+			this.credential = 'token';
+			this.appId = '';
+			this.key = '';
+			this.token = connection.token;
+			this.tokenExpires = Number.POSITIVE_INFINITY;
+		} else {
+			this.credential = 'app';
+			this.appId = connection.appId;
+			this.key = connection.privateKey.includes('\\n') ? connection.privateKey.replace(/\\n/g, '\n') : connection.privateKey;
+		}
 		this.owner = connection.owner;
 		this.repo = connection.repo;
 		this.fetcher = connection.fetch ?? fetch;
@@ -163,6 +240,37 @@ export class GitHubClient {
 		this.tracker = tracker;
 	}
 
+	/** What's wrong with GitHub access now, the most serious first; null when nothing is (Decision 5). */
+	accessProblem(): GitHubAccessProblem | null {
+		if (this.refused) return { kind: 'refused', credential: this.credential };
+		if (this.missingPermission) return { kind: 'permission', credential: this.credential, permission: this.missingPermission };
+		const expires = this.personalTokenExpires;
+		if (this.credential === 'token' && expires !== null && expires - this.now() < TOKEN_EXPIRY_WARNING_MS) {
+			return { kind: 'expiring', credential: 'token', expires: new Date(expires).toISOString() };
+		}
+		return null;
+	}
+
+	/**
+	 * Keep what a response says about access. A 401 is a refused credential. A write
+	 * refused for lack of a permission (`notPermitted`: a 403 or a GraphQL error saying
+	 * "not accessible") is a missing permission, except on Deployments (optional,
+	 * Decision 10); a rate limit's 403 isn't one. Any success clears a refusal; a
+	 * successful write clears a missing permission.
+	 */
+	private observe(res: Response, path: string, write: boolean, notPermitted: boolean, hadErrors = false): void {
+		if (this.credential === 'token') {
+			const expires = parseTokenExpiry(res.headers.get('github-authentication-token-expiration'));
+			if (expires !== null) this.personalTokenExpires = expires;
+		}
+		if (res.status === 401) this.refused = true;
+		else if (res.ok && !notPermitted) {
+			this.refused = false;
+			if (write && !hadErrors) this.missingPermission = null; // a GraphQL 200 carrying errors didn't land
+		}
+		if (notPermitted && write && !/\/deployments/.test(path)) this.missingPermission = CONTENTS_PERMISSION;
+	}
+
 	get nameWithOwner() {
 		return `${this.owner}/${this.repo}`;
 	}
@@ -176,6 +284,7 @@ export class GitHubClient {
 		const jwt = appJwt(this.appId, this.key, Math.floor(this.now() / 1000));
 		const install = (await this.request('GET', this.repoPath('/installation'), undefined, jwt).catch((error: unknown) => {
 			if (error instanceof HttpError && error.status === 404) {
+				this.refused = true;
 				throw new Error(`The GitHub App (id ${this.appId}) isn't installed on ${this.nameWithOwner}. Install it on that repo.`);
 			}
 			throw error;
@@ -188,8 +297,9 @@ export class GitHubClient {
 		this.tokenExpires = Date.parse(tok.expires_at);
 	}
 
-	/** The installation token, refreshed five minutes before it expires. */
+	/** The installation token, refreshed five minutes before it expires; a personal token as it is. */
 	private async auth(): Promise<string> {
+		if (this.credential === 'token') return this.token;
 		if (!this.token || this.now() > this.tokenExpires - 5 * 60_000) {
 			this.signingIn ??= this.signIn().finally(() => {
 				this.signingIn = null;
@@ -207,6 +317,7 @@ export class GitHubClient {
 	async bytes(path: string): Promise<Buffer> {
 		const res = await this.fetcher(`${API}${path}`, { headers: this.headers(await this.auth()), redirect: 'follow', signal: this.signal() });
 		this.tracker.record({ endpoint: `GET ${shorten(path.replace(/^\/repos\/[^/]+\/[^/]+/, '').replace(/\?.*$/, ''))}`, status: res.status, creating: false });
+		this.observe(res, path, false, false);
 		if (!res.ok) throw new HttpError(res.status, `GET ${path} -> ${res.status}`, await res.text().catch(() => ''));
 		return Buffer.from(await res.arrayBuffer());
 	}
@@ -234,7 +345,8 @@ export class GitHubClient {
 			signal: this.signal(),
 		});
 		const endpointPath = path.replace(/^\/repos\/[^/]+\/[^/]+/, '').replace(/\?.*$/, '');
-		this.tracker.record({ endpoint: `${method} ${shorten(endpointPath)}`, status: res.status, creating: !notCreating && isContentCreating(method, path, false) });
+		const creating = !notCreating && isContentCreating(method, path, false);
+		this.tracker.record({ endpoint: `${method} ${shorten(endpointPath)}`, status: res.status, creating });
 		const text = await res.text();
 		let json: unknown = null;
 		try {
@@ -242,14 +354,15 @@ export class GitHubClient {
 		} catch {
 			json = text;
 		}
+		const message = (json as { message?: string } | null)?.message ?? text.slice(0, 200);
+		this.observe(res, path, creating, res.status === 403 && /not accessible/i.test(message));
 		if (!res.ok) {
-			const message = (json as { message?: string } | null)?.message ?? text.slice(0, 200);
 			throw new HttpError(res.status, `${method} ${endpointPath} -> ${res.status}: ${message}`, json);
 		}
 		return json;
 	}
 
-	/** GraphQL as the installation. Throws GraphQLError when the answer has `errors`. */
+	/** GraphQL as the installation (or the token). Throws GraphQLError when the answer has `errors`. */
 	async graphql<T = unknown>(query: string, variables: Record<string, unknown>, name: string): Promise<T> {
 		const isMutation = /^\s*mutation\b/.test(query);
 		const res = await this.fetcher(`${API}/graphql`, {
@@ -264,6 +377,8 @@ export class GitHubClient {
 			if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) throw error; // timed out mid-body
 			return {};
 		})) as { data?: T; errors?: { type?: string; message?: string }[] };
+		const notPermitted = (json.errors ?? []).some((e) => e.type === 'FORBIDDEN' || /not accessible/i.test(e.message ?? ''));
+		this.observe(res, '/graphql', isMutation, notPermitted, (json.errors?.length ?? 0) > 0);
 		if (!res.ok && !json.errors) throw new HttpError(res.status, `graphql ${name} -> ${res.status}`, json);
 		if (json.errors?.length) throw new GraphQLError(json.errors);
 		return json.data as T;