pageship 0.5.0 → 0.6.1

package/README.md

@@ -14,7 +14,7 @@ pnpm add -g pageship
 bun add -g pageship
 ```
 
-Then run `pageship --version` to check that the shell finds it. To have an agent install the CLI and the Pageship skills and sign you in, give it the [setup guide](https://pageship.dev/setup-guide) instead.
+Then run `pageship --version` to check that the shell finds it. Run `pageship update` later to update it with the same package manager. To have an agent install the CLI and the Pageship skills and sign you in, give it the [setup guide](https://pageship.dev/setup-guide) instead.
 
 ## Get started
 

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { execFile } from "node:child_process";
+import { exec, execFile, spawn } from "node:child_process";
 import { access, cp, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -675,30 +675,18 @@ const documentsRestore = (options) => (options.client ?? client).post({
 		...options.headers
 	}
 });
-const documentsUpdateVisibility = (options) => (options.client ?? client).patch({
-	url: "/api/v1/documents/{id}/visibility",
-	...options,
-	headers: {
-		"Content-Type": "application/json",
-		...options.headers
-	}
-});
 const viewersList = (options) => (options.client ?? client).get({
 	url: "/api/v1/documents/{id}/viewers",
 	...options
 });
-const viewersAdd = (options) => (options.client ?? client).post({
-	url: "/api/v1/documents/{id}/viewers",
+const viewersUpdateSharing = (options) => (options.client ?? client).patch({
+	url: "/api/v1/documents/{id}/sharing",
 	...options,
 	headers: {
 		"Content-Type": "application/json",
 		...options.headers
 	}
 });
-const viewersRemove = (options) => (options.client ?? client).delete({
-	url: "/api/v1/documents/{id}/viewers/{githubAccountId}",
-	...options
-});
 const githubGetUser = (options) => (options.client ?? client).get({
 	url: "/api/v1/github/users/{login}",
 	...options
@@ -797,10 +785,12 @@ function validRevision(value, documentId) {
 var DocumentRequestError = class extends Error {
 	status;
 	httpStatus;
-	constructor(status, message, httpStatus) {
+	account;
+	constructor(status, message, httpStatus, account) {
 		super(message);
 		this.status = status;
 		this.httpStatus = httpStatus;
+		this.account = account;
 	}
 };
 function failed(response, error) {
@@ -921,29 +911,6 @@ async function restoreDocumentRevision(baseUrl, id, input, options = {}) {
 	if (record(data) && data.status === "idempotency_conflict") return { status: "idempotency_conflict" };
 	throw new Error("Invalid document restoration response. Retry with the same idempotency key.");
 }
-async function updateDocumentVisibility(baseUrl, id, visibility, options = {}) {
-	const { data: received, response, error } = await documentsUpdateVisibility({
-		...changeOptions(baseUrl, options),
-		path: { id },
-		body: { visibility }
-	});
-	if (!response?.ok) {
-		if (response?.status === 400) throw new DocumentRequestError("invalid_visibility", "Choose private or public.", 400);
-		if (response?.status === 401) throw new DocumentRequestError("signed_out", "Sign in to update this document.", 401);
-		if (response?.status === 403) throw new DocumentRequestError("uninvited", "Access unavailable.", 403);
-		if (response?.status === 404) throw new DocumentRequestError("unavailable", "Document unavailable.", 404);
-		throw new Error("Could not update document visibility. Try again.", { cause: error });
-	}
-	const data = received;
-	const updated = record(data) && data.status === "visibility_updated" ? normalizeDocument(data.document) : void 0;
-	const removedViewers = record(data) && data.removedViewers !== void 0 ? data.removedViewers : 0;
-	if (updated?.visibility === visibility && typeof removedViewers === "number" && Number.isSafeInteger(removedViewers) && removedViewers >= 0) return {
-		status: "visibility_updated",
-		document: updated,
-		removedViewers
-	};
-	throw new Error("Invalid document visibility response.");
-}
 async function publishDocument(baseUrl, input, options = {}) {
 	if (input.action) {
 		if (!(await getDocumentLimits(baseUrl, options)).publicationActions.includes(input.action)) throw new DocumentRequestError("publication_action_unsupported", "This server does not support explicit publication actions. Ask the operator to update the server. No HTML was uploaded.", 400);
@@ -990,7 +957,21 @@ function isGitHubAccountId(value) {
 	return typeof value === "string" && /^[1-9][0-9]{0,19}(?![\s\S])/u.test(value);
 }
 function validViewer(value) {
-	return record(value) && isGitHubAccountId(value.githubAccountId) && isGitHubLogin(value.login) && (value.name === null || typeof value.name === "string") && typeof value.addedAt === "number" && Number.isSafeInteger(value.addedAt) && value.addedAt >= 0;
+	return record(value) && isGitHubAccountId(value.githubAccountId) && isGitHubLogin(value.login) && (value.name === null || typeof value.name === "string") && typeof value.addedAt === "number" && Number.isSafeInteger(value.addedAt) && value.addedAt >= 0 && typeof value.viewCount === "number" && Number.isSafeInteger(value.viewCount) && value.viewCount >= 0 && (value.lastViewedAt === null || typeof value.lastViewedAt === "number" && Number.isSafeInteger(value.lastViewedAt) && value.lastViewedAt >= 0);
+}
+function normalizeViewer(value) {
+	if (!record(value)) return;
+	const normalized = {
+		...value,
+		...value.viewCount === void 0 ? { viewCount: 0 } : {},
+		...value.lastViewedAt === void 0 ? { lastViewedAt: null } : {}
+	};
+	return validViewer(normalized) ? normalized : void 0;
+}
+function normalizeViewers(value) {
+	if (!Array.isArray(value)) return;
+	const viewers = value.map(normalizeViewer);
+	return viewers.every((viewer) => viewer !== void 0) ? viewers : void 0;
 }
 function validUserMatch(value) {
 	return record(value) && isGitHubAccountId(value.githubAccountId) && isGitHubLogin(value.login);
@@ -1014,13 +995,14 @@ const viewerRefusals = {
 	owner_account: "You already have access to your own document.",
 	github_sign_in_required: "GitHub refused your sign-in. Sign in to Pageship again.",
 	github_rate_limited: "GitHub is limiting requests. Try again in a minute.",
-	github_unavailable: "GitHub is unavailable. Try again."
+	github_unavailable: "GitHub is unavailable. Try again.",
+	invalid_sharing: "A change can't both add and remove the same account."
 };
 function isViewerRefusal(value) {
 	return typeof value === "string" && Object.hasOwn(viewerRefusals, value);
 }
 function viewerFailed(response, error) {
-	if (response && record(error) && isViewerRefusal(error.status)) throw new DocumentRequestError(error.status, viewerRefusals[error.status], response.status);
+	if (response && record(error) && isViewerRefusal(error.status)) throw new DocumentRequestError(error.status, validUserMatch(error.account) && typeof error.message === "string" ? error.message : viewerRefusals[error.status], response.status, validUserMatch(error.account) ? error.account : void 0);
 	failed(response, error);
 }
 async function getDocumentViewers(baseUrl, id, options = {}) {
@@ -1029,35 +1011,45 @@ async function getDocumentViewers(baseUrl, id, options = {}) {
 		path: { id }
 	});
 	if (!response?.ok) viewerFailed(response, error);
-	if (data?.status === "listed" && Array.isArray(data.viewers) && data.viewers.every(validViewer)) return data;
+	const viewers = data?.status === "listed" ? normalizeViewers(data.viewers) : void 0;
+	if (data && viewers) return {
+		...data,
+		viewers
+	};
 	throw new Error("Invalid document viewer listing response.");
 }
-/** Adds the account the owner confirmed. The server looks the login up again before adding it. */
-async function addDocumentViewer(baseUrl, id, user, options = {}) {
-	const { data, response, error } = await viewersAdd({
+/**
+* The most accounts one sharing change adds and removes. The contract's DocumentSharingChange
+* refuses more; tests/document-contract.test.ts keeps the two equal.
+*/
+const sharingLimits = {
+	add: 20,
+	remove: 50
+};
+/**
+* Changes visibility and viewers together or not at all. The server looks up each added account
+* that isn't a viewer yet, as addDocumentViewer does.
+*/
+async function updateDocumentSharing(baseUrl, id, change, options = {}) {
+	const { data, response, error } = await viewersUpdateSharing({
 		...changeOptions(baseUrl, options),
 		path: { id },
-		body: {
-			githubAccountId: user.githubAccountId,
-			login: user.login
-		}
+		body: change
 	});
 	if (!response?.ok) viewerFailed(response, error);
-	if (data?.status === "added" && validViewer(data.viewer) && data.viewer.githubAccountId === user.githubAccountId) return data;
-	throw new Error("Invalid document viewer response.");
-}
-/** Removing an account that isn't a viewer succeeds. */
-async function removeDocumentViewer(baseUrl, id, githubAccountId, options = {}) {
-	const { data, response, error } = await viewersRemove({
-		...changeOptions(baseUrl, options),
-		path: {
-			id,
-			githubAccountId
-		}
-	});
-	if (!response?.ok) viewerFailed(response, error);
-	if (data?.status === "removed") return { status: "removed" };
-	throw new Error("Invalid document viewer removal response.");
+	const updated = data?.status === "sharing_updated" ? data : void 0;
+	const document = updated && normalizeDocument(updated.document);
+	const viewers = updated && normalizeViewers(updated.viewers);
+	const added = updated && normalizeViewers(updated.added);
+	const removed = updated && normalizeViewers(updated.removed);
+	if (updated && document && viewers && added && removed && (change.visibility === void 0 || document.visibility === change.visibility)) return {
+		...updated,
+		document,
+		viewers,
+		added,
+		removed
+	};
+	throw new Error("Invalid document sharing response.");
 }
 async function getGitHubUser(baseUrl, login, options = {}) {
 	const { data, response, error } = await githubGetUser({
@@ -1448,6 +1440,8 @@ const outcomes = {
 	restored: "succeeded",
 	viewers_updated: "succeeded",
 	skills_installed: "succeeded",
+	cli_updated: "succeeded",
+	cli_current: "succeeded",
 	authorization_pending: "pending",
 	expired: "pending",
 	signed_out: "pending",
@@ -1483,6 +1477,8 @@ const outcomes = {
 	document_id_taken: "failed",
 	publication_action_unsupported: "failed",
 	skills_modified: "failed",
+	install_unknown: "failed",
+	update_failed: "failed",
 	ambiguous_viewer: "failed",
 	document_public: "failed",
 	github_user_not_found: "failed",
@@ -1504,7 +1500,8 @@ const commandNames = [
 	"visibility",
 	"viewers",
 	"restore",
-	"skills"
+	"skills",
+	"update"
 ];
 const isCommandName = (value) => commandNames.some((name) => name === value);
 /** Exit codes follow the outcome, except an interruption, which exits 130. */
@@ -1554,7 +1551,7 @@ function commandLine(command, args) {
 }
 //#endregion
 //#region package.json
-var version = "0.5.0";
+var version = "0.6.1";
 //#endregion
 //#region src/publish.ts
 const execute = promisify(execFile);
@@ -2427,10 +2424,12 @@ function downloadDocument(options) {
 }
 function changeVisibility(options) {
 	return asOwner(options.server, options.signal, async ({ origin }, request) => {
-		const result = await updateDocumentVisibility(origin, options.documentId, options.visibility, request);
-		const { document, removedViewers } = result;
+		const { document, removed } = await updateDocumentSharing(origin, options.documentId, { visibility: options.visibility }, request);
+		const removedViewers = removed.length;
 		return {
-			...result,
+			status: "visibility_updated",
+			document,
+			removedViewers,
 			message: document.visibility === "public" ? `${document.id} is public.${removedViewers ? ` Removed its ${viewerCount(removedViewers)}.` : ""} Anyone with the URL can read its current revision: ${document.url}` : `${document.id} is private. Only you and its ${document.sharedWith ? viewerCount(document.sharedWith) : "viewers"} can read it after signing in: ${document.url}`
 		};
 	});
@@ -2510,6 +2509,10 @@ const installNext = {
 	command: "skills",
 	args: ["install"]
 };
+const updateNext = {
+	command: "update",
+	args: []
+};
 /** The output of `node --version` from PATH, or undefined when it does not run. */
 const nodeOnPath = () => new Promise((resolve) => {
 	execFile("node", ["--version"], {
@@ -2594,6 +2597,7 @@ async function replaceFolder(source, target) {
 	}
 }
 const parseMajor = (version) => Number(/^v?(\d+)\./u.exec(version)?.[1] ?? NaN);
+/** Whether version `installed` is older than `cli`. An unreadable `installed` counts as older. */
 const older = (installed, cli) => {
 	const parts = (version) => version.split(/[.+-]/u).slice(0, 3).map(Number);
 	const [a, b] = [parts(installed), parts(cli)];
@@ -2617,7 +2621,7 @@ async function inspectCli(environment, signal) {
 	return {
 		cli: "older",
 		latest,
-		message: `A newer Pageship CLI is published (${latest}; this is ${environment.version}). Update it with the package manager that installed it, then run ${commandLine(installNext.command, installNext.args)}.`
+		message: `A newer Pageship CLI is published (${latest}; this is ${environment.version}). Run ${commandLine(updateNext.command, updateNext.args)} to update it, then run ${commandLine(installNext.command, installNext.args)}.`
 	};
 }
 /** The recommended skills and Node that the CLI could not find. It installs none of them. */
@@ -2909,7 +2913,7 @@ function viewerList(documentId, viewers) {
 }
 /**
 * Lists a document's viewers, or changes them. Every removal is matched and every added username
-* looked up before anything changes. Removals run first, then additions.
+* looked up first, then one sharing change applies them all or none.
 */
 function manageViewers(options) {
 	const { documentId, add, remove } = options;
@@ -2927,13 +2931,11 @@ function manageViewers(options) {
 				...add.flatMap((value) => ["--add", value])
 			]
 		};
+		if (add.length > sharingLimits.add || remove.length > sharingLimits.remove) return {
+			status: "usage_error",
+			message: `Add up to ${sharingLimits.add} and remove up to ${sharingLimits.remove} viewers at a time. Nothing was changed.`
+		};
 		const progress = [];
-		const added = [];
-		const removed = [];
-		const changed = () => added.length || removed.length ? {
-			added,
-			removed
-		} : {};
 		try {
 			const { viewers } = await getDocumentViewers(origin, documentId, request);
 			if (!add.length && !remove.length) return {
@@ -2965,38 +2967,39 @@ function manageViewers(options) {
 					user,
 					message: `${account(user)} is ${user.type === "organization" ? "an organization" : "not a personal account"}. Only a personal GitHub account can be a viewer. Nothing was changed.`
 				};
+				if (removals.some(({ githubAccountId }) => githubAccountId === user.githubAccountId)) return {
+					status: "usage_error",
+					message: `${account(user)} is both added and removed. Nothing was changed.`
+				};
 				progress.push(`Found ${account(user)}.`);
 				if (!accounts.some(({ githubAccountId }) => githubAccountId === user.githubAccountId)) accounts.push(user);
 			}
-			for (const viewer of removals) {
-				await removeDocumentViewer(origin, documentId, viewer.githubAccountId, request);
-				removed.push(viewer);
-				progress.push(`Removed ${account(viewer)}.`);
-			}
-			for (const user of accounts) {
-				const { viewer } = await addDocumentViewer(origin, documentId, user, request);
-				added.push(viewer);
-				progress.push(`Added ${account(viewer)}.`);
-			}
-			const current = await getDocumentViewers(origin, documentId, request);
+			const { added, removed, ...shared } = await updateDocumentSharing(origin, documentId, {
+				add: accounts.map(({ githubAccountId, login }) => ({
+					githubAccountId,
+					login
+				})),
+				remove: removals.map(({ githubAccountId }) => githubAccountId)
+			}, request);
 			return {
 				status: "viewers_updated",
 				documentId,
 				added,
 				removed,
 				notViewers,
-				viewers: current.viewers,
+				viewers: shared.viewers,
 				message: [
 					...progress,
+					...removed.map((viewer) => `Removed ${account(viewer)}.`),
+					...added.map((viewer) => `Added ${account(viewer)}.`),
 					...notViewers.map((value) => `${value} is not a viewer of ${documentId}.`),
-					viewerList(documentId, current.viewers)
+					viewerList(documentId, shared.viewers)
 				].join("\n")
 			};
 		} catch (error) {
 			const prefix = (result) => ({
 				...result,
 				documentId,
-				...changed(),
 				message: [...progress, result.message].join("\n")
 			});
 			if (isRefusal(error)) {
@@ -3013,20 +3016,182 @@ function manageViewers(options) {
 				});
 				return prefix(refusal(error, login));
 			}
-			if (!added.length && !removed.length) throw error;
 			return prefix(options.signal.aborted ? {
 				status: "interrupted",
 				message: `Operation interrupted. Run ${commandLine(next.command, next.args)} to finish.`,
 				next
 			} : {
 				status: "request_failed",
-				message: `${error instanceof Error ? error.message : String(error)} Run ${commandLine(next.command, next.args)} to finish.`,
+				message: `${error instanceof Error ? error.message : String(error)} Run ${commandLine(next.command, next.args)} to retry.`,
 				next
 			});
 		}
 	});
 }
 //#endregion
+//#region src/update.ts
+/**
+* The command that updates a global install with each manager. Keep in sync with the setup
+* guide. The package names an exact version where one is known: pnpm resolves `latest` to the
+* newest version older than its minimum release age, so a fresh release would not install.
+*/
+const updateCommand$1 = (manager, spec) => ({
+	npm: [
+		"npm",
+		"i",
+		"-g",
+		spec
+	],
+	pnpm: [
+		"pnpm",
+		"add",
+		"-g",
+		spec
+	],
+	bun: [
+		"bun",
+		"add",
+		"-g",
+		spec
+	],
+	yarn: [
+		"yarn",
+		"global",
+		"add",
+		spec
+	],
+	vp: [
+		"vp",
+		"install",
+		"-g",
+		spec
+	]
+})[manager];
+const npmRoot = (signal) => new Promise((resolve) => {
+	exec("npm root -g", {
+		timeout: 1e4,
+		windowsHide: true,
+		signal
+	}, (error, stdout) => resolve(error ? void 0 : stdout.trim() || void 0));
+});
+/**
+* Run a command with the terminal attached, or, for `--json`, with its output collected so
+* standard output stays one JSON value.
+*/
+const runCommand = (json) => (argv, signal) => new Promise((resolve, reject) => {
+	const [command, ...args] = argv;
+	if (!json) console.log(`Running ${argv.join(" ")}`);
+	const stdio = json ? [
+		"ignore",
+		"pipe",
+		"pipe"
+	] : "inherit";
+	const child = process.platform === "win32" ? spawn(argv.join(" "), {
+		stdio,
+		shell: true,
+		windowsHide: true
+	}) : spawn(command, args, { stdio });
+	const stop = () => child.kill("SIGTERM");
+	signal.addEventListener("abort", stop, { once: true });
+	const settle = () => signal.removeEventListener("abort", stop);
+	let output = "";
+	const collect = (chunk) => {
+		output = (output + chunk.toString()).slice(-4e3);
+	};
+	child.stdout?.on("data", collect);
+	child.stderr?.on("data", collect);
+	child.once("error", (error) => {
+		settle();
+		reject(error);
+	});
+	child.once("close", (exitCode) => {
+		settle();
+		resolve({
+			exitCode,
+			output
+		});
+	});
+});
+/** A path with forward slashes and a trailing slash, compared without case on Windows. */
+function comparable(path, platform) {
+	const slashed = `${path.replaceAll("\\", "/").replace(/\/+$/u, "")}/`;
+	return platform === "win32" ? slashed.toLowerCase() : slashed;
+}
+/**
+* Which manager installed this CLI globally, from where its package is. Undefined for anything
+* else, such as a project dependency or an npx cache, which `update` must not replace.
+*/
+async function detectManager(environment, signal) {
+	const { platform, env } = environment;
+	const root = comparable(environment.packageRoot, platform);
+	const installed = (folders, layout) => folders.some((folder) => {
+		if (!folder) return false;
+		const base = comparable(folder, platform);
+		const index = root.lastIndexOf(base);
+		return index !== -1 && layout.test(root.slice(index + base.length));
+	});
+	if (installed(["/vite-plus/packages/"], /^pageship\/[^/]+\/(?:lib\/)?node_modules\/pageship\/$/u)) return "vp";
+	if (installed(["/pnpm/global/", env.PNPM_HOME && join(env.PNPM_HOME, "global")], /^[^/]+\/(?:[^/]+\/)?node_modules\/\.pnpm\/pageship@[^/]+\/node_modules\/pageship\/$/u)) return "pnpm";
+	if (installed(["/.bun/", env.BUN_INSTALL], /^install\/global\/node_modules\/pageship\/$/u) || installed([env.BUN_INSTALL_GLOBAL_DIR], /^node_modules\/pageship\/$/u)) return "bun";
+	if (installed(["/yarn/global/", "/yarn/data/global/"], /^node_modules\/pageship\/$/u)) return "yarn";
+	const npm = await environment.npmRoot(signal);
+	const parent = root.slice(0, root.lastIndexOf("/", root.length - 2) + 1);
+	if (npm !== void 0 && parent === comparable(npm, platform)) return "npm";
+}
+/**
+* Update this CLI to the version npm publishes as latest, with the package manager that
+* installed it. It changes nothing when this CLI is already the latest.
+*/
+async function update(environment, signal) {
+	const { version } = environment;
+	const latest = await environment.publishedVersion(signal);
+	if (latest !== void 0 && !older(version, latest)) return {
+		status: "cli_current",
+		message: `Pageship ${version} is the latest version.`,
+		version,
+		latest
+	};
+	const manager = await detectManager(environment, signal);
+	signal.throwIfAborted();
+	if (manager === void 0) return {
+		status: "install_unknown",
+		message: `This Pageship CLI, in ${environment.packageRoot}, was not installed globally by npm, pnpm, bun, Yarn or Vite+, so update cannot tell how to replace it. Update it the way you installed it.`,
+		version,
+		...latest === void 0 ? {} : { latest },
+		path: environment.packageRoot
+	};
+	const argv = updateCommand$1(manager, `pageship@${latest ?? "latest"}`);
+	const run = argv.join(" ");
+	const ran = await environment.run(argv, signal).catch((error) => {
+		if (signal.aborted) throw error;
+		return {
+			exitCode: null,
+			output: error instanceof Error ? error.message : String(error)
+		};
+	});
+	signal.throwIfAborted();
+	if (ran.exitCode !== 0) return {
+		status: "update_failed",
+		message: [ran.exitCode === null ? `Could not run ${run}.` : `${run} failed with exit code ${ran.exitCode}.`, ran.output.trim()].filter(Boolean).join("\n"),
+		version,
+		...latest === void 0 ? {} : { latest },
+		manager,
+		run,
+		exitCode: ran.exitCode,
+		output: ran.output
+	};
+	const skills = await stat(join(environment.home, ".agents", "skills", "pageship")).then(() => true, () => false);
+	return {
+		status: "cli_updated",
+		message: [latest === void 0 ? `Updated Pageship from ${version} with ${run}.` : `Updated Pageship from ${version} to ${latest} with ${run}.`, ...skills ? [`Run ${commandLine(installNext.command, installNext.args)} to update the Pageship skills to match.`] : []].join("\n"),
+		version,
+		...latest === void 0 ? {} : { latest },
+		manager,
+		run,
+		...skills ? { next: installNext } : {}
+	};
+}
+//#endregion
 //#region src/cli.ts
 const args = process.argv.slice(2);
 const separator = args.indexOf("--");
@@ -3093,6 +3258,13 @@ const skills = Command.make("skills").pipe(Command.withDescription("Manage the P
 	force,
 	signal
 }))).pipe(Command.withDescription("Install the Pageship skills in ~/.agents/skills, and link them in ~/.claude/skills when ~/.claude exists."))]));
+const updateCommand = Command.make("update", {}, () => authCommand("update", (signal) => update({
+	...skillsEnvironment,
+	packageRoot: dirname(dirname(fileURLToPath(import.meta.url))),
+	env: process.env,
+	npmRoot,
+	run: runCommand(json)
+}, signal))).pipe(Command.withDescription("Update this CLI to the latest version with the package manager that installed it: npm, pnpm, bun, Yarn or Vite+."));
 const login = Command.make("login", {
 	complete: Flag.boolean("complete").pipe(Flag.withDefault(false), Flag.withDescription("Check a pending authorization once, without waiting.")),
 	restart: Flag.boolean("restart").pipe(Flag.withDefault(false), Flag.withDescription("Start a new authorization code.")),
@@ -3253,7 +3425,7 @@ function authCommand(name, operation) {
 			settle(name, result);
 			if (json) return;
 			if (thrown) {
-				console.error(`${name === "status" ? "Could not check status" : name === "skills" ? "Could not install the Pageship skills" : "Pageship request failed"}: ${result.message}`);
+				console.error(`${name === "status" ? "Could not check status" : name === "skills" ? "Could not install the Pageship skills" : name === "update" ? "Could not update Pageship" : "Pageship request failed"}: ${result.message}`);
 				return;
 			}
 			console.log(result.message);
@@ -3264,7 +3436,7 @@ function authCommand(name, operation) {
 		}
 	});
 }
-const command = Command.make("pageship").pipe(Command.withDescription("Pageship publishes private HTML documents on the hosted Pageship service.\n\nEarly development: check whether this installation is ready with the status command. Authorize this installation with login, then publish one HTML file with publish. Manage published documents with list, history, download, visibility, viewers and restore. Install the Pageship skills for your agents with skills install."), Command.withSubcommands([
+const command = Command.make("pageship").pipe(Command.withDescription("Pageship publishes private HTML documents on the hosted Pageship service.\n\nEarly development: check whether this installation is ready with the status command. Authorize this installation with login, then publish one HTML file with publish. Manage published documents with list, history, download, visibility, viewers and restore. Install the Pageship skills for your agents with skills install, and update the CLI with update."), Command.withSubcommands([
 	status,
 	login,
 	whoami,
@@ -3275,7 +3447,8 @@ const command = Command.make("pageship").pipe(Command.withDescription("Pageship
 	visibility,
 	viewers,
 	restore,
-	skills
+	skills,
+	updateCommand
 ]), Command.withGlobalFlags([jsonFlag]));
 const effectiveArgs = args.every((arg, index) => arg === "--json" || arg.startsWith("--json=") && booleanValue(arg.slice(7)) !== void 0 || index > 0 && args[index - 1] === "--json" && booleanValue(arg) !== void 0) ? [...args, "--help"] : args;
 const program = Command.runWith(command, {

package/dist/skills/pageship/SKILL.md

@@ -3,7 +3,7 @@ name: pageship
 description: Publish an HTML file to Pageship and manage what is published. Use when the user asks to publish, share or get a link to a document, update its published copy, change its visibility or viewers, list, inspect history, download or restore published documents, or sign in to Pageship. To write, edit, rename or move a document, load pageship-docs instead.
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Pageship
@@ -33,6 +33,7 @@ With `--json`, the CLI prints one JSON object on one line. Parse it before you d
 - `next` is one follow-up command. `resolutions` holds named alternatives for a decision, each a follow-up command or a list of them.
 - Other fields depend on the status, such as `document`, `candidates`, `choices`, `user` or `idempotencyKey`.
 - `skills install` returns `skills_installed` or `skills_modified`, as described in [Install the Pageship skills](#install-the-pageship-skills).
+- `update` returns `cli_updated`, `cli_current`, `install_unknown` or `update_failed`, as described in [Update the CLI](#update-the-cli).
 
 A follow-up has a `command` and an `args` array. Run it as `pageship --json <command> <args...>` with `args` unchanged. They already carry the server, target document, expected revision and retry key, so never rebuild them from memory.
 
@@ -50,7 +51,17 @@ pageship --json status
 
 Status only reads; it never signs in, claims an address or uploads. On `admitted`, sign-in and the workspace address are set, unless `next` is a `login`: that comes from an older server that does not report the address, and running it confirms the address. A `next` of `skills install` on `admitted` is about the skills, below. On `signed_out` or `address_required`, sign in as described below. On `uninvited`, report the `message`: the user must ask the server owner for an invitation, or sign in with another account using `login --restart`. On `unreachable`, `client_too_old`, `server_too_old`, `unsupported` or `configuration_unreadable`, report the `message`; signing in does not fix these. A ready status does not prove that a publish will succeed.
 
-Status also reports the Pageship skills in `skills`: `missing`, `current` or `older` than the CLI. They never block publishing, and a status that is otherwise ready still succeeds. When `skills` is `missing` or `older`, tell the user, and install them as below only if they agree. Never run a `skills install` from `next` without asking. When `cli` is `older`, a newer CLI is published: tell the user, and offer to update it with the package manager that installed it before installing the skills.
+Status also reports the Pageship skills in `skills`: `missing`, `current` or `older` than the CLI. They never block publishing, and a status that is otherwise ready still succeeds. When `skills` is `missing` or `older`, tell the user, and install them as below only if they agree. Never run a `skills install` from `next` without asking. When `cli` is `older`, a newer CLI is published: tell the user, and offer to update it, as below, before installing the skills.
+
+## Update the CLI
+
+With the user's agreement, update the CLI with the package manager that installed it:
+
+```sh
+pageship --json update
+```
+
+On `cli_updated`, the new version is installed. Its `next` is a `skills install`, present when the Pageship skills are installed, since they still match the old version: install them as below if the user agrees. On `cli_current`, the CLI is already the latest. On `install_unknown`, no supported package manager installed it globally, so nothing ran; tell the user to update it the way they installed it. On `update_failed`, report the `message`, which carries the package manager's error.
 
 ## Install the Pageship skills
 

package/dist/skills/pageship/references/viewers.md

@@ -12,7 +12,7 @@ Set `PAGESHIP_DOCUMENT` to the document's `id`, then add each named username wit
 pageship --json viewers "$PAGESHIP_DOCUMENT" --add octocat --add hubot
 ```
 
-The CLI looks each username up on GitHub before it changes anything. `added` holds each account it added, with `login`, `name` and `githubAccountId`, on `viewers_updated` and on a failure partway through. Whatever the status, show the user every account in `added` by `login` and `name`, and ask them to confirm each is the person they meant. A username can belong to someone else. If one is wrong, remove it as below. Then give the user the document's `url` to send: Pageship sends no invitations.
+The CLI looks each username up on GitHub before it changes anything. On `viewers_updated`, `added` holds each account it added, with `login`, `name` and `githubAccountId`. Show the user every account in `added` by `login` and `name`, and ask them to confirm each is the person they meant. A username can belong to someone else. If one is wrong, remove it as below. Then give the user the document's `url` to send: Pageship sends no invitations.
 
 ## List and remove viewers
 
@@ -40,4 +40,4 @@ pageship --json viewers "$PAGESHIP_DOCUMENT" --remove octocat
 - `github_sign_in_required`: GitHub refused the sign-in Pageship uses to look up users. Ask the user to sign in to the Pageship dashboard again with GitHub, then run the returned `next`. A CLI `login` doesn't fix this.
 - `github_rate_limited` or `github_unavailable`: wait a minute, then run the returned `next`.
 
-A failure partway through keeps the changes already made, listed in `added` and `removed`. Its `next` repeats the command, which finishes the rest without adding or removing anyone twice.
+The command adds and removes everyone together or no one. On any failure, nothing changed. Its `next` repeats the whole command. It takes up to 20 `--add` and 50 `--remove` values; split a longer list across several commands.

package/dist/skills/pageship-chart/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-chart
 description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for charts in a Pageship HTML document, loaded by a pageship- kind skill before it draws a chart."
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Chart

package/dist/skills/pageship-code-block/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-code-block
 description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for code in a Pageship HTML document, such as source code, commands, configuration or logs, loaded by a pageship- kind skill before the first code block."
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Code block

package/dist/skills/pageship-decision-record/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-decision-record
 description: HTML decision records, as the second step of pageship-docs. For any request to record, write, regenerate, edit or move a decision, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Decision record

package/dist/skills/pageship-diagram/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-diagram
 description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for diagrams in a Pageship HTML document, such as a process, a timeline, a system map or states, loaded by a pageship- kind skill before it draws a diagram."
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Diagram

package/dist/skills/pageship-docs/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-docs
 description: First step for any document people read, such as a report, plan, spec, explainer, review, decision record or slide deck, in HTML or Markdown. Load it before any other pageship- skill. Use when the user asks for one of these documents, asks to regenerate, redesign, edit, rename, move or copy an HTML source file, or asks to record whether they want HTML or Markdown.
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Pageship documents

package/dist/skills/pageship-docs/references/check.md

@@ -12,7 +12,7 @@ Run the linter, html-validate with the config and rules in this folder:
 npx --yes html-validate@11.17.0 --config <pageship-docs folder>/references/html-validate.json <file>
 ```
 
-It reports HTML errors, accessibility problems such as a missing `lang` or `alt` or a skipped heading level, and breaks of three rules: [one standalone file](file.md#one-standalone-file) and [trusted libraries only](file.md#trusted-libraries-only) in the file rules, and **Height** in [the design rules](design.md#base-rules-every-file-meets). Fix each problem it reports and run it again. Done when it reports nothing. When `npx` can't run, such as without Node or network, check the file against those three rules by reading it, and say in the hand-over that the linter didn't run.
+It reports HTML errors, accessibility problems such as a missing `lang` or `alt` or a skipped heading level, and breaks of four rules: [one standalone file](file.md#one-standalone-file), [trusted libraries only](file.md#trusted-libraries-only) and [link previews](file.md#link-previews) in the file rules, and **Height** in [the design rules](design.md#base-rules-every-file-meets). Fix each problem it reports and run it again. Done when it reports nothing. When `npx` can't run, such as without Node or network, check the file against those four rules by reading it, and say in the hand-over that the linter didn't run.
 
 Then:
 
@@ -51,7 +51,7 @@ Then use every control by keyboard and confirm it works and shows focus. Done wh
 
 ## Claims
 
-Read the file sentence by sentence beside the source, captions, labels and tooltips included. Keep each claim the source states. A claim one step past it goes, or becomes an open question: a cause, when something starts or ends, a count, how far a rule reaches, or a new name for something the source names. A caption claims only what its figure draws. Done when you can point to the source's words behind every sentence.
+Read the file sentence by sentence beside the source, captions, labels, tooltips and the link preview's description included. Keep each claim the source states. A claim one step past it goes, or becomes an open question: a cause, when something starts or ends, a count, how far a rule reaches, or a new name for something the source names. A caption claims only what its figure draws. Done when you can point to the source's words behind every sentence.
 
 ## The structure you added
 

package/dist/skills/pageship-docs/references/file.md

@@ -32,6 +32,39 @@ Mermaid, only when a pattern skill calls for it:
 
 Hosted fonts from `https://fonts.googleapis.com/css2?...` through a `<link rel="stylesheet">`, which can't carry `integrity`.
 
+## Link previews
+
+Chat apps and social sites show a card for a shared link, built from tags in the file's `<head>`. Every file carries them, after `<meta charset>`, the viewport and `<title>`:
+
+```html
+<title>Q3 support report</title>
+<meta
+  name="description"
+  content="Ticket volume rose 18% in Q3 while first-reply time held at 2 hours."
+/>
+<meta property="og:type" content="article" />
+<meta property="og:title" content="Q3 support report" />
+<meta
+  property="og:description"
+  content="Ticket volume rose 18% in Q3 while first-reply time held at 2 hours."
+/>
+<meta property="og:image" content="https://example.com/q3/tickets-by-week.png" />
+<meta property="og:image:alt" content="Tickets by week, July to September" />
+<meta property="og:image:width" content="1200" />
+<meta property="og:image:height" content="630" />
+<meta name="twitter:card" content="summary_large_image" />
+<meta name="twitter:image:alt" content="Tickets by week, July to September" />
+```
+
+- **Title.** `<title>` and `og:title` hold the same text: the document's title, as its `h1` gives it.
+- **Description.** `description` and `og:description` hold the same one or two sentences, up to about 160 characters, that state the document's main point as its first lines do. It follows the [content rules](content.md) like any other text in the file.
+- **Type.** `og:type` is `article`.
+- **Image.** The card's image is the first of these that is a PNG, JPEG or GIF file at an `https://` URL: the image or chart that leads the page, then the first image in the page with alt text. Its `alt` becomes `og:image:alt` and `twitter:image:alt`. Its size in pixels, when you measured the image file itself, becomes `og:image:width` and `og:image:height`; a size the page displays it at is not that size, so without a measured size leave those two out. Sites can't show an inline SVG or a `data:` URL, so a page whose images and charts are only those leaves out every image tag.
+- **Card.** `twitter:card` is `summary_large_image` with an image and `summary` without. X reads the title, description and image from the `og:` tags, so the only other `twitter:` tag is `twitter:image:alt`.
+- **No address.** Leave out `og:url` and `<link rel="canonical">`: the file doesn't know where it will be published, and sites use the address they fetched.
+
+An edit that changes the title, the main point or the image updates these tags to match.
+
 ## The Pageship sandbox
 
 A published file runs with scripts allowed and everything else blocked, so it works without these:

package/dist/skills/pageship-docs/references/html-validate-rules.mjs

@@ -316,11 +316,105 @@ class NoViewportHeight extends Rule {
   }
 }
 
+const entities = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+
+/** Text with its character references decoded and its runs of white space as single spaces. */
+const plainText = (text) =>
+  text
+    .replace(/&(?:#(\d+)|#x([\da-f]+)|(\w+));/giu, (match, decimal, hex, name) =>
+      decimal || hex
+        ? String.fromCodePoint(Number.parseInt(decimal ?? hex, decimal ? 10 : 16))
+        : (entities[name.toLowerCase()] ?? match),
+    )
+    .replace(/\s+/gu, " ")
+    .trim();
+
+/** The tags a link preview reads. Others, such as one `theme-color` per colour scheme, may repeat. */
+const previewTags = /^(?:description|og:.+|twitter:.+)$/u;
+
+/** An `https://` URL whose path doesn't end in `.svg`, which link previews don't show. */
+const previewImage = /^https:\/\/(?![^?#]*\.svg(?:[?#]|$))/iu;
+
+class LinkPreview extends Rule {
+  documentation() {
+    return {
+      description:
+        "Give the file the link preview tags in the file rules (references/file.md): a description, og:type, og:title and og:description matching the title and description, twitter:card, and an og:image only at an https:// URL to an image that isn't SVG, with og:image:alt and twitter:image:alt.",
+    };
+  }
+
+  setup() {
+    this.on("dom:ready", ({ document }) => {
+      const head = document.querySelector("head");
+      if (!head) return;
+      /** Each `<meta>` content by its `name` or `property`, with the element that has it. */
+      const metas = new Map();
+      for (const element of document.querySelectorAll("meta")) {
+        const key = attributeValue(element, "property") ?? attributeValue(element, "name");
+        if (!previewTags.test(key ?? "")) continue;
+        if (metas.has(key)) {
+          this.report(element, `The file has a second ${key} tag: keep one`);
+          continue;
+        }
+        metas.set(key, { element, content: plainText(attributeValue(element, "content") ?? "") });
+      }
+      const content = (key) => metas.get(key)?.content ?? "";
+      const at = (key) => metas.get(key)?.element ?? head;
+
+      for (const key of ["description", "og:type", "og:title", "og:description", "twitter:card"]) {
+        if (!content(key)) {
+          this.report(
+            at(key),
+            `The file needs the ${key} tag with content, as the file rules give`,
+          );
+        }
+      }
+      const title = document.querySelector("title");
+      if (title && content("og:title") && content("og:title") !== plainText(title.textContent)) {
+        this.report(at("og:title"), "og:title must hold the same text as <title>");
+      }
+      if (content("og:description") && content("og:description") !== content("description")) {
+        this.report(at("og:description"), "og:description must hold the same text as description");
+      }
+
+      const image = content("og:image");
+      if (metas.has("og:image") && !image) {
+        this.report(
+          at("og:image"),
+          "og:image is empty: give the image's URL, or leave out the image tags",
+        );
+      }
+      if (image && !previewImage.test(image)) {
+        this.report(
+          at("og:image"),
+          `og:image "${image}" is not an https:// URL to an image a link preview shows, such as a PNG or JPEG file: use one, or leave out the image tags`,
+        );
+      }
+      for (const key of ["og:image:alt", "twitter:image:alt"]) {
+        if (image && !content(key)) {
+          this.report(at("og:image"), `og:image needs ${key}, the image's alt text`);
+        }
+      }
+      if (!image && (metas.has("og:image:alt") || metas.has("twitter:image:alt"))) {
+        this.report(head, "The file has image alt tags but no og:image: leave them out too");
+      }
+      const card = image ? "summary_large_image" : "summary";
+      if (content("twitter:card") && content("twitter:card") !== card) {
+        this.report(
+          at("twitter:card"),
+          `twitter:card must be "${card}" for a file ${image ? "with" : "without"} og:image`,
+        );
+      }
+    });
+  }
+}
+
 export default {
   name: "pageship",
   rules: {
     "pageship/trusted-libraries": TrustedLibraries,
     "pageship/no-relative-paths": NoRelativePaths,
     "pageship/no-viewport-height": NoViewportHeight,
+    "pageship/link-preview": LinkPreview,
   },
 };

package/dist/skills/pageship-docs/references/html-validate.json

@@ -8,6 +8,7 @@
     "heading-level": ["error", { "allowMultipleH1": false }],
     "pageship/trusted-libraries": "error",
     "pageship/no-relative-paths": "error",
-    "pageship/no-viewport-height": "error"
+    "pageship/no-viewport-height": "error",
+    "pageship/link-preview": "error"
   }
 }

package/dist/skills/pageship-explainer/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-explainer
 description: HTML explainers, as the second step of pageship-docs. For any request to explain how something works, or to write, regenerate, edit or move an explainer, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Explainer

package/dist/skills/pageship-interaction/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-interaction
 description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for controls in a Pageship HTML document, such as stepping through stages, tracing a path, tabs, filters, revealing detail and pointer states on charts and diagrams, loaded by a pageship- kind skill before it adds any control."
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Interaction

package/dist/skills/pageship-key-figures/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-key-figures
 description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for the few numbers and callouts a Pageship HTML document opens with, loaded by a pageship- kind skill before it writes key figures."
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Key figures

package/dist/skills/pageship-media/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-media
 description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for images, video and audio in a Pageship HTML document, loaded by a pageship- kind skill before it shows media."
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Media

package/dist/skills/pageship-motion/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-motion
 description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for animation and transitions in a Pageship HTML document, such as a chart that grows into view, a sequence that plays through a diagram, or a marker moving along a path, loaded by a pageship- kind skill before it draws a chart, a graphic or a sequence, or before anything else on the page moves."
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Motion

package/dist/skills/pageship-plan/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-plan
 description: HTML plans, as the second step of pageship-docs. For any request to write, regenerate, edit or move a plan, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Plan

package/dist/skills/pageship-report/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-report
 description: HTML reports, as the second step of pageship-docs. For any request to write, regenerate, edit or move a report, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Report

package/dist/skills/pageship-review-report/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-review-report
 description: HTML review reports, as the second step of pageship-docs. For any request to review a change or a plan and write up the findings, or to write, regenerate, edit or move a review report, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Review report

package/dist/skills/pageship-slide-deck/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-slide-deck
 description: HTML slide decks, as the second step of pageship-docs. For any request to make slides or a presentation, or to regenerate, edit or move a deck, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Slide deck

package/dist/skills/pageship-spec/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-spec
 description: HTML specs, as the second step of pageship-docs. For any request to write, regenerate, edit or move a spec, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Spec

package/dist/skills/pageship-table/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-table
 description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for tables in a Pageship HTML document, loaded by a pageship- kind skill before it writes a table."
 license: MIT
 metadata:
-  version: "0.5.0"
+  version: "0.6.1"
 ---
 
 # Table

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pageship",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Pageship CLI for checking server API compatibility.",
   "license": "UNLICENSED",
   "repository": {