@rathnasgala/cli 1.0.0 → 1.1.4

package/README.md

@@ -12,13 +12,24 @@ Nothing to install. Every command runs through `npx`.
 
 ## Start a publication
 
-Make a folder named after the publication you want, and run one command inside it:
+Create it in the current empty folder:
 
 ```console
 mkdir field-notes && cd field-notes
-npx --yes @rathnasgala/cli@latest init --here
+npx --yes @rathnasgala/cli@latest init
 ```
 
+Or name a new destination directly:
+
+```console
+npx --yes @rathnasgala/cli@latest init field-notes
+```
+
+The destination must be empty. An initialized Git repository with no commits and no files is also
+accepted and its `.git` directory is preserved. To reserve a custom domain during setup, add
+`--domain blog.example.com`; Gala still requires GitHub ownership verification and healthy DNS
+before activating it.
+
 It signs you in to Gala and to GitHub if you are not already, creates the repository, registers the
 publication, and leaves a working checkout in the folder. When it finishes it prints the address
 your publication will live at.
@@ -51,12 +62,49 @@ npx --yes @rathnasgala/cli@latest publish
 Checks your content, records it, and sends it to GitHub. GitHub builds and deploys from there; the
 site updates a minute or two later.
 
+## Prism configurations
+
+Prism keeps one canonical work while letting you explicitly approve alternate reading depths and
+intents. The CLI uses Gala's public lifecycle API; it never writes approval artifacts itself.
+
+```console
+npx --yes @rathnasgala/cli@latest prism status
+npx --yes @rathnasgala/cli@latest prism create my-post --language en --depth brief --intent orientation
+npx --yes @rathnasgala/cli@latest prism list my-post --language en
+```
+
+Use `prism edit`, `submit`, `approve`, `reject`, and `revoke` to advance a configuration. Approval,
+rejection, revocation, and reducing the publication mode require terminal confirmation or `--yes`.
+Configuration links default to `nofollow`; change the publication or one work with
+`prism link-policy` when ordinary followed links are intentional. Commands that change repository
+artifacts stay attached through Gala's materialization and GitHub Pages publication states, then
+print the live publication address or a concrete terminal failure. Proposal generation likewise
+waits until its revision is ready for review or generation fails.
+
+## Custom domain
+
+Reserve a domain after setup, then advance the verified GitHub Pages flow as DNS propagates:
+
+```console
+npx --yes @rathnasgala/cli@latest domain set blog.example.com
+npx --yes @rathnasgala/cli@latest domain check
+```
+
+`domain status` resumes an interrupted change, `domain cancel` abandons it, and `domain remove`
+returns the publication to its GitHub Pages address. After removal, delete the old DNS records.
+
 ## When something is wrong
 
 ```console
 npx --yes @rathnasgala/cli@latest doctor
 ```
 
+Inspect a verified managed-theme release without changing anything unless you confirm it:
+
+```console
+npx --yes @rathnasgala/cli@latest upgrade
+```
+
 Reports on your sign-ins, the publication folder, the publishing workflow, and anything you have
 written but not sent. Each check either passes, names what is wrong and how to fix it, or says it
 could not be determined — never one of those disguised as another.
@@ -67,10 +115,13 @@ Run any command with `--help`.
 
 | Command | What it does | Options |
 | --- | --- | --- |
-| `init` | Create a publication and clone it here | `--name`, `--here` |
+| `init` | Create a publication in the current or named empty directory | `--name`, `--domain` |
+| `domain` | Inspect or change the custom domain | `--root` |
 | `new` | Start a post | `--language`, `--root`, `--today` |
 | `preview` | Build and serve the publication locally | `--root`, `--today` |
 | `publish` | Check, record and send your work to GitHub | `--root`, `--today`, `--skip-checks` |
+| `prism` | Manage author-approved reading configurations | `--root`, `--language`, `--depth`, `--intent`, `--modality`, `--file`, `--reason`, `--yes` |
+| `upgrade` | Inspect and apply a verified managed-theme update | `--root`, `--channel`, `--yes` |
 | `doctor` | Check a publication and say what is wrong | `--root` |
 | `auth` | Sign in to Gala and GitHub | — |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala/cli",
-  "version": "1.0.0",
+  "version": "1.1.4",
   "type": "module",
   "files": [
     "src"

package/src/api/gala.js

@@ -59,12 +59,19 @@ export function galaApi({ baseUrl = DEFAULT_API_BASE_URL, token } = {}) {
      * wait for the App installation to reach the result, which is why repositories the CLI created
      * never appeared in the web UI.
      */
-    createPublication({ capability, name }) {
+    createPublication({ capability, name, installationId }) {
       return requestJson(`${root}/v1/auth/github/publications`,
         authorized('Publication creation', {
           method: 'POST',
           headers: { 'content-type': 'application/json', 'GitHub-Authorization': capability },
-          body: JSON.stringify({ name })
+          body: JSON.stringify({ name, installationId })
+        }));
+    },
+
+    githubInstallationAccounts({ capability }) {
+      return requestJson(`${root}/v1/auth/github/accounts`,
+        authorized('GitHub installation accounts', {
+          headers: { 'GitHub-Authorization': capability }
         }));
     },
 
@@ -85,6 +92,35 @@ export function galaApi({ baseUrl = DEFAULT_API_BASE_URL, token } = {}) {
       return requestJson(`${root}/v1/me/sites`, authorized('Publication list'));
     },
 
+    prepareTopologyChange(siteId, body) {
+      return requestJson(`${root}/v1/sites/${encodeURIComponent(siteId)}/topology-changes/prepare`,
+        authorized('Custom domain reservation', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(body)
+        }));
+    },
+
+    pendingTopologyChange(siteId) {
+      return requestJson(`${root}/v1/sites/${encodeURIComponent(siteId)}/topology-changes/pending`,
+        authorized('Custom domain status'));
+    },
+
+    configureTopologyChange(siteId, changeId) {
+      return requestJson(`${root}/v1/sites/${encodeURIComponent(siteId)}/topology-changes/${encodeURIComponent(changeId)}/configure`,
+        authorized('GitHub Pages domain verification', { method: 'POST' }));
+    },
+
+    commitTopologyChange(siteId, changeId) {
+      return requestJson(`${root}/v1/sites/${encodeURIComponent(siteId)}/topology-changes/${encodeURIComponent(changeId)}/commit`,
+        authorized('Custom domain activation', { method: 'POST' }));
+    },
+
+    discardTopologyChange(siteId, changeId) {
+      return request(`${root}/v1/sites/${encodeURIComponent(siteId)}/topology-changes/${encodeURIComponent(changeId)}`,
+        authorized('Custom domain cancellation', { method: 'DELETE' }));
+    },
+
     /** Not in the OpenAPI document, though the endpoint exists and is public. */
     async signInConfiguration() {
       return requestJson(`${root}/v1/auth/configuration`, { action: 'Sign-in configuration' });
@@ -121,6 +157,7 @@ export function galaApi({ baseUrl = DEFAULT_API_BASE_URL, token } = {}) {
       throw new Error(`Gala sign-in failed: ${body?.error_description ?? body?.error ?? response.status}`);
     },
 
-    request: (path, options) => request(`${root}${path}`, authorized(options?.action ?? path, options))
+    request: (path, options) => request(`${root}${path}`, authorized(options?.action ?? path, options)),
+    json: (path, options) => requestJson(`${root}${path}`, authorized(options?.action ?? path, options))
   };
 }

package/src/commands/domain.js

@@ -0,0 +1,124 @@
+import path from 'node:path';
+
+import { galaApi } from '../api/gala.js';
+import { galaCredential } from '../auth/gala.js';
+import { UsageError } from '../cli/args.js';
+import { customDomain } from '../domain.js';
+import { readPublication } from '../publication.js';
+
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+
+export async function domain({ terminal, options, cwd = process.cwd() }) {
+  const root = path.resolve(options.value('root') ?? cwd);
+  const publication = await readPublication(root);
+  if (!publication || !ULID.test(publication.siteId ?? '')) {
+    throw new UsageError('Run this inside a registered Gala publication, or pass --root.');
+  }
+  const [action = 'status', value, ...extra] = options.positional;
+  if (extra.length > 0 || !['status', 'set', 'check', 'cancel', 'remove'].includes(action)) {
+    throw new UsageError('Use: gala domain [status|set <hostname>|check|cancel|remove]');
+  }
+  if (action === 'set' && value == null) throw new UsageError('domain set needs a hostname');
+  if (action !== 'set' && value != null) throw new UsageError(`domain ${action} takes no hostname`);
+
+  const credential = await galaCredential({
+    terminal, apiBaseUrl: options.value('api-base-url'),
+  });
+  const api = galaApi({ baseUrl: credential.apiBaseUrl, token: credential.accessToken });
+
+  if (action === 'status') {
+    const pending = await api.pendingTopologyChange(publication.siteId);
+    if (!pending) {
+      terminal.result((await ownedSite(api, publication.siteId)).publicationUrl);
+      terminal.note('No domain change is pending.');
+      return null;
+    }
+    showPending(terminal, pending);
+    return pending;
+  }
+
+  if (action === 'set') {
+    const checked = customDomain(value);
+    if (checked.error) throw new UsageError(checked.error);
+    const change = await api.prepareTopologyChange(publication.siteId, {
+      canonicalBaseUrl: `https://${checked.host}`,
+      pathPrefix: '/',
+    });
+    terminal.done(`Reserved ${checked.host}`);
+    terminal.note('Verify it in the repository owner’s GitHub account, then run: gala domain check');
+    terminal.openUrl('https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages');
+    return change;
+  }
+
+  if (action === 'remove') {
+    const existing = await api.pendingTopologyChange(publication.siteId);
+    if (existing) {
+      throw new UsageError('No second domain change can start while another one is pending; cancel it first.');
+    }
+    const site = await ownedSite(api, publication.siteId);
+    const [owner, repository] = site.repository.split('/');
+    const host = `${owner.toLowerCase()}.github.io`;
+    const prefix = repository.toLowerCase() === host ? '/' : `/${repository}`;
+    const change = await api.prepareTopologyChange(publication.siteId, {
+      canonicalBaseUrl: `https://${host}`,
+      pathPrefix: prefix,
+    });
+    const committed = await api.commitTopologyChange(publication.siteId, change.changeId);
+    terminal.done(`Returned to ${committed.canonicalBaseUrl}${prefix === '/' ? '/' : `${prefix}/`}`);
+    terminal.note('Remove the old custom-domain records from your DNS provider.');
+    return committed;
+  }
+
+  const pending = await api.pendingTopologyChange(publication.siteId);
+  if (!pending) throw new UsageError('No domain change is pending.');
+
+  if (action === 'cancel') {
+    await api.discardTopologyChange(publication.siteId, pending.changeId);
+    terminal.done('Cancelled the pending domain change');
+    return null;
+  }
+
+  if (action === 'check') {
+    if (pending.cname && pending.state === 'PREPARED') {
+      const configured = await api.configureTopologyChange(publication.siteId, pending.changeId);
+      terminal.done(`GitHub verified ${configured.cname}`);
+      terminal.note(dnsInstruction(configured.cname, await providerHost(api, publication.siteId)));
+      terminal.note('After DNS propagates, run: gala domain check');
+      return configured;
+    }
+    const committed = await api.commitTopologyChange(publication.siteId, pending.changeId);
+    terminal.done(committed.cname
+      ? `${committed.cname} is live with enforced HTTPS`
+      : 'The GitHub Pages address is live again');
+    if (!committed.cname) {
+      terminal.note('Remove the old custom-domain records from your DNS provider.');
+    }
+    return committed;
+  }
+
+  throw new UsageError(`Unsupported domain action: ${action}`);
+}
+
+async function ownedSite(api, siteId) {
+  const sites = await api.listPublications();
+  const site = Array.isArray(sites) ? sites.find((candidate) => candidate.siteId === siteId) : null;
+  if (!site || typeof site.repository !== 'string' || typeof site.publicationUrl !== 'string') {
+    throw new Error('Publication is not available');
+  }
+  return site;
+}
+
+async function providerHost(api, siteId) {
+  return (await ownedSite(api, siteId)).repository.split('/')[0].toLowerCase() + '.github.io';
+}
+
+function dnsInstruction(host, target) {
+  return `For a subdomain: CNAME ${host} → ${target}. For an apex domain, use GitHub’s documented A/AAAA records.`;
+}
+
+function showPending(terminal, pending) {
+  terminal.result(`${pending.canonicalBaseUrl}${pending.pathPrefix}`);
+  terminal.note(`State: ${pending.state}`);
+  if (pending.state === 'PREPARED') terminal.note('Next: verify ownership, then run gala domain check.');
+  else terminal.note('Next: configure DNS, then run gala domain check.');
+}

package/src/commands/init.js

@@ -5,8 +5,9 @@ import { galaApi } from '../api/gala.js';
 import { githubApi } from '../api/github.js';
 import { galaCredential } from '../auth/gala.js';
 import { githubCredential } from '../auth/github.js';
-import { cloneRepository, createGit } from '../git.js';
+import { cloneRepository, createGit, populateEmptyRepository } from '../git.js';
 import { UsageError } from '../cli/args.js';
+import { customDomain } from '../domain.js';
 
 /**
  * Creates a publication and leaves a working checkout behind.
@@ -28,34 +29,45 @@ import { UsageError } from '../cli/args.js';
  * What is left is genuinely the CLI's: asking what to call it, cloning, and reporting the address.
  */
 const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const GITHUB_APP_INSTALLATION_URL = 'https://github.com/apps/gala67-app/installations/new';
 
 export async function init({ terminal, options, cwd = process.cwd() }) {
   const explicitName = options.value('name');
-  const here = options.on('here');
-  const target = here ? cwd : undefined;
+  if (options.positional.length > 1) {
+    throw new UsageError('init accepts at most one destination directory');
+  }
+  const directory = path.resolve(cwd, options.positional[0] ?? '.');
+  const requestedDomain = options.value('domain');
+  const checkedDomain = requestedDomain == null ? null : customDomain(requestedDomain);
+  if (checkedDomain?.error) throw new UsageError(checkedDomain.error);
+
+  const destination = await inspectDestination(directory);
 
   const gala = await galaCredential({ terminal, apiBaseUrl: options.value('api-base-url') });
   const github = await githubCredential({ terminal });
 
-  const name = await publicationName({ terminal, explicitName, here, cwd });
-  const directory = path.resolve(cwd, target ?? name);
-  await refuseOccupied(directory, here);
+  const name = await publicationName({ terminal, explicitName, directory });
 
   const api = galaApi({ baseUrl: gala.apiBaseUrl, token: gala.accessToken });
   const capability = await api.githubCapability(github.accessToken);
+  const installation = await publicationAccount({ terminal, api, capability });
 
   terminal.step(`Creating ${name}`);
-  const created = await createPublication({ terminal, api, capability, name, github });
+  const created = await createPublication({
+    terminal, api, capability, name, github, installationId: installation.installationId
+  });
 
   terminal.step('Waiting for GitHub to copy the template');
   await waitForContent(githubApi(github.accessToken), created.owner, created.name);
 
   terminal.step('Cloning');
-  await cloneRepository({
+  const checkout = {
     url: `https://github.com/${created.owner}/${created.name}.git`,
     target: directory,
     token: github.accessToken
-  });
+  };
+  if (destination === 'empty-git') await populateEmptyRepository(checkout);
+  else await cloneRepository(checkout);
 
   terminal.step('Registering the publication');
   const git = createGit({ root: directory, token: github.accessToken });
@@ -78,8 +90,26 @@ export async function init({ terminal, options, cwd = process.cwd() }) {
   terminal.done(`Created ${created.owner}/${created.name}`);
   terminal.result(publicationUrl(registration, created));
   terminal.note(path.relative(cwd, directory) || '.');
+
+  let domainChange;
+  if (checkedDomain?.host) {
+    terminal.step(`Reserving ${checkedDomain.host}`);
+    try {
+      domainChange = await api.prepareTopologyChange(registration.siteId, {
+        canonicalBaseUrl: `https://${checkedDomain.host}`,
+        pathPrefix: '/'
+      });
+    } catch (failure) {
+      throw new Error(
+        `${created.owner}/${created.name} was created, but ${checkedDomain.host} was not reserved: `
+          + `${failure instanceof Error ? failure.message : 'unknown error'}`
+      );
+    }
+  }
+
   terminal.blank();
   terminal.note('gala new "Your first post"');
+  if (domainChange) terminal.note('gala domain check');
 
   return { owner: created.owner, name: created.name, siteId: registration.siteId, root: directory };
 }
@@ -93,10 +123,9 @@ export async function init({ terminal, options, cwd = process.cwd() }) {
  * behalf: adding a repository to an installation is documented as classic-PAT-only. So it is asked
  * for, with a link to the one page that grants it.
  */
-async function createPublication({ terminal, api, capability, name, github }) {
-  let created = false;
-  for (let attempt = 0; attempt < 3; attempt += 1) {
-    const result = await api.createPublication({ capability, name });
+async function createPublication({ terminal, api, capability, name, github, installationId }) {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const result = await api.createPublication({ capability, name, installationId });
     if (result?.status === 'READY') {
       if (typeof result.owner !== 'string' || typeof result.name !== 'string') {
         throw new Error('Gala created the publication but did not say where');
@@ -104,22 +133,26 @@ async function createPublication({ terminal, api, capability, name, github }) {
       return result;
     }
 
-    // Once the repository exists a further refusal reports UNSUPPORTED rather than NEEDS_SHARING:
-    // the same situation under a different name.
-    const shareable = result?.status === 'NEEDS_SHARING' || created;
-    if (!shareable) {
+    if (result?.status === 'SETUP_PENDING') {
+      terminal.note(`${result.owner ?? ''}/${result.name ?? name} exists; GitHub is still copying it`);
+      await new Promise((resolve) => { setTimeout(resolve, 1000); });
+      continue;
+    }
+
+    if (result?.status !== 'NEEDS_SHARING') {
       throw new Error(
         `Gala could not create the publication (${result?.outcome ?? result?.status}). `
-        + 'Install the Gala GitHub App at https://github.com/apps/gala67-app and try again.'
+        + `Continue at ${result?.recoveryUrl ?? GITHUB_APP_INSTALLATION_URL} `
+        + 'and try again.'
       );
     }
-    created = true;
 
     const owner = result?.owner ?? '';
     terminal.blank();
     terminal.step(`${owner}/${result?.name ?? name} exists, but Gala cannot reach it yet`);
     terminal.note('its installation covers only selected repositories — add this one');
-    terminal.openUrl(installationUrl(result?.installationId, owner, await viewerOf(github)));
+    terminal.openUrl(result?.recoveryUrl
+      ?? installationUrl(result?.installationId, owner, await viewerOf(github)));
     if (!await terminal.waitForEnter('Once Gala can access it')) {
       throw new Error(`Add ${owner}/${result?.name ?? name} to the Gala GitHub App, then run this again.`);
     }
@@ -127,6 +160,27 @@ async function createPublication({ terminal, api, capability, name, github }) {
   throw new Error(`Gala still cannot reach the repository for ${name}.`);
 }
 
+export async function publicationAccount({ terminal, api, capability }) {
+  const state = await api.githubInstallationAccounts({ capability });
+  const accounts = Array.isArray(state?.accounts) ? state.accounts : [];
+  if (accounts.length === 0) {
+    throw new Error(
+      `Install or request the Gala GitHub App at ${state?.installationUrl
+        ?? GITHUB_APP_INSTALLATION_URL} and try again.`
+    );
+  }
+  const personal = accounts.find((account) => account?.organization === false);
+  if (personal) return personal;
+  if (accounts.length === 1) return accounts[0];
+
+  const choices = accounts.map((account) => account.login).join(', ');
+  const selected = (await terminal.ask(`Which GitHub account should own it? (${choices})`)).trim();
+  const account = accounts.find((candidate) =>
+    candidate.login.toLowerCase() === selected.toLowerCase());
+  if (!account) throw new UsageError(`Choose one of these GitHub accounts: ${choices}`);
+  return account;
+}
+
 let viewerCache;
 async function viewerOf(github) {
   viewerCache ??= await githubApi(github.accessToken).viewer();
@@ -155,8 +209,8 @@ async function waitForContent(github, owner, name, { attempts = 30, intervalMs =
   throw new Error(`${owner}/${name} was created but is still empty. Try again in a moment.`);
 }
 
-async function publicationName({ terminal, explicitName, here, cwd }) {
-  const proposed = explicitName ?? (here ? path.basename(path.resolve(cwd)) : undefined);
+async function publicationName({ terminal, explicitName, directory }) {
+  const proposed = explicitName ?? path.basename(directory);
   const answer = proposed ?? await terminal.ask('What should this publication be called?');
   const name = slugify(answer);
   if (name == null) {
@@ -171,19 +225,44 @@ export function slugify(value) {
   return NAME.test(slug) ? slug : null;
 }
 
-async function refuseOccupied(directory, here) {
-  const { readdir } = await import('node:fs/promises');
+export async function inspectDestination(directory) {
+  const { readFile, readdir, stat } = await import('node:fs/promises');
   let entries;
   try {
     entries = await readdir(directory);
   } catch (missing) {
-    if (missing?.code === 'ENOENT') return;
+    if (missing?.code === 'ENOENT') return 'missing';
     throw missing;
   }
-  if (entries.length === 0) return;
-  throw new UsageError(here
-    ? 'This folder is not empty. Run it in an empty folder, or without --here.'
-    : `${path.basename(directory)} already exists and is not empty.`);
+  if (entries.length === 0) return 'empty';
+  if (entries.length === 1 && entries[0] === '.git') {
+    const gitDirectory = path.join(directory, '.git');
+    if (!(await stat(gitDirectory)).isDirectory()) {
+      throw new UsageError('The destination has a linked .git file; use a new empty directory.');
+    }
+    const head = (await readFile(path.join(gitDirectory, 'HEAD'), 'utf8')).trim();
+    const branch = /^ref: (refs\/heads\/.+)$/.exec(head)?.[1];
+    if (branch) {
+      const packed = await readFile(path.join(gitDirectory, 'packed-refs'), 'utf8')
+        .then((source) => source.split('\n').some((line) => line && !line.startsWith('#')),
+          (failure) => failure?.code === 'ENOENT' ? false : Promise.reject(failure));
+      if (!await hasReference(path.join(gitDirectory, 'refs')) && !packed) return 'empty-git';
+    }
+  }
+  throw new UsageError('Gala needs an empty destination directory (an empty git repository is allowed).');
+}
+
+async function hasReference(directory) {
+  const { readdir } = await import('node:fs/promises');
+  const entries = await readdir(directory, { withFileTypes: true }).catch((failure) => {
+    if (failure?.code === 'ENOENT') return [];
+    throw failure;
+  });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) return true;
+    if (await hasReference(path.join(directory, entry.name))) return true;
+  }
+  return false;
 }
 
 function publicationUrl(registration, created) {

package/src/commands/prism.js

@@ -0,0 +1,360 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { galaApi } from '../api/gala.js';
+import { galaCredential } from '../auth/gala.js';
+import { UsageError } from '../cli/args.js';
+import { createGit } from '../git.js';
+import { readPublication } from '../publication.js';
+
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const MODES = new Map([
+  ['off', 'OFF'], ['presentation-only', 'PRESENTATION_ONLY'], ['manual', 'MANUAL'],
+  ['assisted', 'ASSISTED'],
+]);
+const POLICIES = new Map([['nofollow', 'NOFOLLOW'], ['follow', 'FOLLOW']]);
+
+export async function prism({ terminal, options, cwd = process.cwd() }) {
+  const root = path.resolve(options.value('root') ?? cwd);
+  const publication = await readPublication(root);
+  if (!publication || !ULID.test(publication.siteId ?? '')) {
+    throw new UsageError('Run this inside a registered Gala publication, or pass --root.');
+  }
+  const credential = await galaCredential({ terminal, apiBaseUrl: options.value('api-base-url') });
+  const api = galaApi({ baseUrl: credential.apiBaseUrl, token: credential.accessToken });
+  const [action = 'status', ...args] = options.positional;
+
+  if (action === 'status') {
+    requireArgs(args, 0, 'gala prism status');
+    const state = await api.json(`/v1/sites/${publication.siteId}/prism`, { action: 'Prism status' });
+    terminal.result(`Prism ${state.publishedMode}`);
+    terminal.note(`Mode: requested ${state.requestedMode}; published ${state.publishedMode}`);
+    terminal.note(`Configuration links: requested ${state.requestedConfigurationLinkPolicy}; published ${state.publishedConfigurationLinkPolicy}`);
+    return state;
+  }
+
+  const inventory = await api.json(`/v1/sites/${publication.siteId}/posts`, {
+    action: 'Published post inventory',
+  });
+  const expectedRepositoryHeadSha = inventory.headSha;
+
+  if (action === 'mode') {
+    requireArgs(args, 1, 'gala prism mode <off|presentation-only|manual|assisted>');
+    const mode = MODES.get(args[0]);
+    if (!mode) throw new UsageError('Prism mode must be off, presentation-only, manual, or assisted.');
+    if (mode === 'OFF' || mode === 'PRESENTATION_ONLY') await confirm(terminal, options, `Change Prism mode to ${args[0]}?`);
+    const result = await mutate(api, `/v1/sites/${publication.siteId}/prism`, 'PUT', {
+      mode, expectedRepositoryHeadSha,
+    }, 'Prism mode');
+    return settleMutation(api, terminal, publication, result);
+  }
+
+  if (action === 'link-policy') {
+    const [scope, target, value] = args;
+    if (scope === 'site') {
+      requireArgs(args, 2, 'gala prism link-policy site <nofollow|follow>');
+      const policy = policyValue(target);
+      const result = await mutate(api, `/v1/sites/${publication.siteId}/prism`, 'PUT', {
+        configurationLinkPolicy: policy, expectedRepositoryHeadSha,
+      }, 'Prism link policy');
+      return settleMutation(api, terminal, publication, result);
+    }
+    if (scope === 'work') {
+      requireArgs(args, 3, 'gala prism link-policy work <slug> <inherit|nofollow|follow>');
+      const post = resolvePost(inventory, target, options.value('language'), publication.defaultLanguage);
+      if (value === 'inherit') {
+        const result = await mutate(api,
+          `/v1/sites/${publication.siteId}/articles/${post.articleId}/prism?fields=configurationLinkPolicy`,
+          'DELETE', undefined, 'Prism work link policy', {
+            'x-expected-repository-head': expectedRepositoryHeadSha,
+          });
+        return settleMutation(api, terminal, publication, result);
+      }
+      const result = await mutate(api,
+        `/v1/sites/${publication.siteId}/articles/${post.articleId}/prism`, 'PUT', {
+          configurationLinkPolicy: policyValue(value), expectedRepositoryHeadSha,
+        }, 'Prism work link policy');
+      return settleMutation(api, terminal, publication, result);
+    }
+    throw new UsageError('Use: gala prism link-policy site <nofollow|follow> or work <slug> <inherit|nofollow|follow>');
+  }
+
+  if (action === 'list') {
+    requireArgs(args, 1, 'gala prism list <slug> [--language en]');
+    const post = resolvePost(inventory, args[0], options.value('language'), publication.defaultLanguage);
+    const result = await configurations(api, publication.siteId, post);
+    terminal.result(`${result.configurations.length} configuration${result.configurations.length === 1 ? '' : 's'}`);
+    for (const item of result.configurations) {
+      terminal.note(`${item.configurationId}  ${item.depth}/${item.intent}/${item.modality}  ${item.lifecycle}/${item.deliveryState}`);
+    }
+    return result;
+  }
+
+  if (action === 'create') {
+    requireArgs(args, 1, 'gala prism create <slug> --language en --depth brief --intent orientation');
+    const post = resolvePost(inventory, args[0], options.value('language'), publication.defaultLanguage);
+    const current = await configurations(api, publication.siteId, post);
+    const result = await mutate(api,
+      `/v1/sites/${publication.siteId}/articles/${post.articleId}/configurations`, 'POST', {
+        language: post.language,
+        depth: enumValue(options.value('depth') ?? 'brief', ['signal', 'brief', 'standard', 'complete', 'methods-references'], 'depth'),
+        intent: enumValue(options.value('intent') ?? 'orientation', ['orientation', 'story', 'proof', 'practice'], 'intent'),
+        modality: enumValue(options.value('modality') ?? 'text', ['text'], 'modality'),
+        expectedSourceContentHash: current.sourceRevisionHash,
+        hashContract: current.hashContract,
+      }, 'Create Prism configuration');
+    terminal.result(result.configurationId);
+    return result;
+  }
+
+  if (!['edit', 'generate', 'submit', 'approve', 'reject', 'revoke'].includes(action)) {
+    throw new UsageError('Unknown Prism action. Run gala prism --help.');
+  }
+
+  const configurationId = args[0];
+  if (!ULID.test(configurationId ?? '')) throw new UsageError(`${action} needs a configuration ID.`);
+  const resolved = await findConfiguration(api, publication, inventory, configurationId,
+    options.value('language'));
+  const { post, collection, configuration } = resolved;
+  const base = `/v1/sites/${publication.siteId}/articles/${post.articleId}/configurations/${configurationId}`;
+
+  if (action === 'edit') {
+    requireArgs(args, 1, 'gala prism edit <configuration-id> --file proposal.md');
+    const filename = options.value('file');
+    if (!filename) throw new UsageError('Prism edit needs --file proposal.md.');
+    const markdown = await readFile(path.resolve(root, filename), 'utf8');
+    const result = await mutate(api, `${base}/revisions`, 'POST', {
+      markdown, expectedSourceContentHash: collection.sourceRevisionHash,
+      hashContract: collection.hashContract,
+    }, 'Save Prism revision');
+    terminal.result(result.revisionId);
+    return result;
+  }
+
+  if (action === 'generate') {
+    requireArgs(args, 1, 'gala prism generate <configuration-id>');
+    const result = await mutate(api, `${base}/generation-jobs`, 'POST', {
+      expectedSourceContentHash: collection.sourceRevisionHash,
+      hashContract: collection.hashContract,
+    }, 'Generate Prism proposal');
+    return settleGeneration(api, terminal, publication.siteId, post.articleId,
+      configurationId, result);
+  }
+
+  const revisionId = args[1] ?? configuration.workingRevision?.revisionId;
+  if (action !== 'revoke' && !ULID.test(revisionId ?? '')) {
+    throw new UsageError(`${action} needs a revision ID when there is no working revision.`);
+  }
+  if (action === 'submit') {
+    if (args.length > 2) throw new UsageError('Use: gala prism submit <configuration-id> [revision-id]');
+    if (revisionId !== configuration.workingRevision?.revisionId) {
+      throw new UsageError('Only the current working revision can be submitted. Refresh the configuration and try again.');
+    }
+    const warnings = configuration.workingRevision.literalFindings
+      ?.filter((item) => item.severity === 'WARNING') ?? [];
+    for (const warning of warnings) terminal.note(`Warning ${warning.id}: ${warning.message}`);
+    if (warnings.length > 0) {
+      await confirm(terminal, options, `Acknowledge all ${warnings.length} listed warning${warnings.length === 1 ? '' : 's'}?`);
+    }
+    const result = await mutate(api, `${base}/submit`, 'POST', expectation(collection, {
+      revisionId, acknowledgedWarningIds: warnings.map((warning) => warning.id),
+    }), 'Submit Prism revision');
+    terminal.result(`${result.revisionId} ${result.reviewState}`);
+    return result;
+  }
+
+  const reason = options.value('reason');
+  if (action === 'approve') {
+    if (args.length > 2) throw new UsageError('Use: gala prism approve <configuration-id> [revision-id] [--yes]');
+    if (revisionId !== configuration.workingRevision?.revisionId) {
+      throw new UsageError('Only the current working revision can be approved. Refresh the configuration and try again.');
+    }
+    const changed = await createGit({ root }).run(
+      ['status', '--porcelain', '--', `content/posts/${post.slug}`], { capture: true });
+    if (changed) throw new UsageError('The canonical post has uncommitted edits. Publish or revert them before approval.');
+    const warnings = configuration.workingRevision?.literalFindings
+      ?.filter((item) => item.severity === 'WARNING').map((item) => item.id) ?? [];
+    for (const warning of configuration.workingRevision?.literalFindings
+      ?.filter((item) => item.severity === 'WARNING') ?? []) {
+      terminal.note(`Warning ${warning.id}: ${warning.message}`);
+    }
+    if (warnings.length > 0) {
+      await confirm(terminal, options, `Acknowledge all ${warnings.length} listed warning${warnings.length === 1 ? '' : 's'}?`);
+    }
+    await confirm(terminal, options, 'Approve this revision and publish it?');
+    const result = await mutate(api, `${base}/approve`, 'POST', expectation(collection, {
+      revisionId, expectedRepositoryHeadSha, acknowledgedWarningIds: warnings,
+    }), 'Approve Prism revision');
+    return settleMutation(api, terminal, publication, result);
+  }
+  if (!reason) throw new UsageError(`Prism ${action} needs --reason.`);
+  await confirm(terminal, options, `${action === 'reject' ? 'Reject this revision' : 'Revoke this configuration'}?`);
+  const suffix = action === 'reject' ? '/reject' : '/revoke';
+  const body = action === 'reject'
+    ? expectation(collection, { revisionId, reason })
+    : expectation(collection, { expectedRepositoryHeadSha, reason });
+  const result = await mutate(api, `${base}${suffix}`, 'POST', body, `Prism ${action}`);
+  if (result.materialization) return settleMutation(api, terminal, publication, result);
+  terminal.result(result.reviewState ?? action);
+  return result;
+}
+
+function requireArgs(args, count, usage) {
+  if (args.length !== count) throw new UsageError(`Use: ${usage}`);
+}
+
+function resolvePost(inventory, slug, requestedLanguage, defaultLanguage) {
+  const variants = inventory.posts.filter((post) => post.slug === slug);
+  const post = variants.find((item) => item.language === requestedLanguage)
+    ?? variants.find((item) => item.language === defaultLanguage)
+    ?? variants[0];
+  if (!post) throw new UsageError(`No published work uses the slug ${slug}.`);
+  if (!post.articleId) throw new UsageError('Publish this work once before creating configurations.');
+  return post;
+}
+
+async function findConfiguration(api, publication, inventory, id, language) {
+  for (const post of inventory.posts.filter((item) => item.articleId
+    && (!language || item.language === language))) {
+    const collection = await configurations(api, publication.siteId, post);
+    const configuration = collection.configurations.find((item) => item.configurationId === id);
+    if (configuration) return { post, collection, configuration };
+  }
+  throw new UsageError(`Configuration ${id} is not part of this publication.`);
+}
+
+function configurations(api, siteId, post) {
+  return api.json(`/v1/sites/${siteId}/articles/${post.articleId}/configurations?language=${encodeURIComponent(post.language)}`, {
+    action: 'Prism configurations',
+  });
+}
+
+function mutate(api, path, method, body, action, extraHeaders = {}) {
+  return api.json(path, {
+    action, method,
+    headers: {
+      'content-type': 'application/json', 'idempotency-key': crypto.randomUUID(), ...extraHeaders,
+    },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+}
+
+function expectation(collection, extra) {
+  return {
+    ...extra,
+    expectedSourceContentHash: collection.sourceRevisionHash,
+    hashContract: collection.hashContract,
+  };
+}
+
+function policyValue(value) {
+  const policy = POLICIES.get(value);
+  if (!policy) throw new UsageError('Link policy must be nofollow or follow.');
+  return policy;
+}
+
+function enumValue(value, allowed, name) {
+  if (!allowed.includes(value)) throw new UsageError(`${name} must be one of: ${allowed.join(', ')}.`);
+  return value.replaceAll('-', '_').toUpperCase();
+}
+
+async function confirm(terminal, options, question) {
+  if (options.on('yes')) return;
+  const answer = await terminal.ask(`${question} Type yes to continue.`);
+  if (answer.toLowerCase() !== 'yes') throw new UsageError('Cancelled.');
+}
+
+function showMutation(terminal, result) {
+  terminal.result(`Queued ${result.materialization?.materializationId ?? result.materializationId}`);
+  if (result.settings?.requestedEffectiveMode) {
+    terminal.note(`Effective when published: ${result.settings.requestedEffectiveMode} / ${result.settings.requestedEffectiveConfigurationLinkPolicy}`);
+  } else if (result.settings) {
+    terminal.note(`Requested: ${result.settings.requestedMode} / ${result.settings.requestedConfigurationLinkPolicy}`);
+  }
+}
+
+async function settleMutation(api, terminal, publication, result) {
+  showMutation(terminal, result);
+  const initial = result.materialization;
+  if (!initial?.materializationId) return result;
+
+  let state = initial;
+  const deadline = Date.now() + 31 * 60_000;
+  while (!['COMMITTED', 'FAILED'].includes(state.status) && Date.now() < deadline) {
+    await delay(state.status === 'RETRY_WAIT' ? 10_000 : 3_000);
+    state = await api.json(
+      `/v1/sites/${publication.siteId}/prism/materializations/${initial.materializationId}`,
+      { action: 'Prism repository materialization' },
+    );
+    terminal.note(`Repository: ${state.status} (attempt ${state.attemptCount})`);
+  }
+  if (state.status === 'FAILED') {
+    throw new UsageError(`Repository update failed (${state.errorCode ?? 'unknown error'}). Run the command again after correcting the cause.`);
+  }
+  if (state.status !== 'COMMITTED') {
+    throw new UsageError('Repository update did not finish before the 31-minute tracking deadline. Check gala prism status before retrying.');
+  }
+  if (!state.publicationAttemptSha) {
+    terminal.result('Repository updated. No publication attempt was returned.');
+    return { ...result, materialization: state };
+  }
+
+  terminal.note(`Repository committed at ${state.commitSha ?? state.publicationAttemptSha}. Verifying publication.`);
+  const publicationState = await waitForPublication(api, terminal, publication.siteId,
+    state.publicationAttemptSha, deadline);
+  if (publicationState.status === 'FAILED') {
+    throw new UsageError(`Publication failed (${publicationState.errors?.[0]?.message ?? 'unknown error'}).`);
+  }
+  if (publicationState.status !== 'PUBLISHED') {
+    throw new UsageError('Publication did not finish before the 31-minute tracking deadline.');
+  }
+  const live = publicationUrl(publication);
+  terminal.result(live ? `Published at ${live}` : 'Published.');
+  return { ...result, materialization: state, publicationAttempt: publicationState };
+}
+
+async function waitForPublication(api, terminal, siteId, commitSha, deadline) {
+  let state;
+  do {
+    state = await api.json(`/v1/sites/${siteId}/publication-attempts/${commitSha}`, {
+      action: 'Prism publication attempt',
+    });
+    terminal.note(`Publication: ${state.status}`);
+    if (['PUBLISHED', 'FAILED'].includes(state.status)) return state;
+    await delay(5_000);
+  } while (Date.now() < deadline);
+  return state;
+}
+
+function publicationUrl(publication) {
+  if (publication.url) return publication.url.replace(/\/$/, '');
+  const base = publication.canonicalBaseUrl ?? publication.hosting?.canonicalBaseUrl;
+  const prefix = publication.pathPrefix ?? publication.hosting?.pathPrefix ?? '';
+  return base ? `${base.replace(/\/$/, '')}/${prefix.replace(/^\//, '').replace(/\/$/, '')}`.replace(/\/$/, '') : undefined;
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function settleGeneration(api, terminal, siteId, articleId, configurationId, initial) {
+  terminal.result(`${initial.jobId} ${initial.status}`);
+  let state = initial;
+  const deadline = Date.now() + 31 * 60_000;
+  while (!['SUCCEEDED', 'FAILED'].includes(state.status) && Date.now() < deadline) {
+    await delay(3_000);
+    state = await api.json(
+      `/v1/sites/${siteId}/articles/${articleId}/configurations/${configurationId}/generation-jobs/${initial.jobId}`,
+      { action: 'Prism generation job' },
+    );
+    terminal.note(`Generation: ${state.status} (attempt ${state.attemptCount})`);
+  }
+  if (state.status === 'FAILED') {
+    throw new UsageError(`Proposal generation failed (${state.errorCode ?? 'unknown error'}).`);
+  }
+  if (state.status !== 'SUCCEEDED') {
+    throw new UsageError('Proposal generation did not finish before the 31-minute tracking deadline.');
+  }
+  terminal.result(`Proposal revision ${state.revisionId} is ready for review.`);
+  return state;
+}

package/src/commands/upgrade.js

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import { copyFile, lstat, mkdtemp, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { x as extractTar } from 'tar';
+
+const PACKAGE = '@rathnasgala/theme';
+const REGISTRY = 'https://registry.npmjs.org';
+const PROTECTED = ['.git/', 'content/', 'custom.css', 'site.config.yml'];
+
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const safeManagedPath = (value) => typeof value === 'string' && value !== ''
+  && !path.isAbsolute(value) && !value.split('/').includes('..')
+  && !PROTECTED.some((protectedPath) => value === protectedPath || value.startsWith(protectedPath));
+
+async function exists(file) {
+  try { await stat(file); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+function verifyIntegrity(bytes, integrity) {
+  const [algorithm, expected] = String(integrity ?? '').split('-', 2);
+  if (!['sha512', 'sha256'].includes(algorithm) || !expected) {
+    throw new Error('The registry did not provide supported package integrity metadata');
+  }
+  const actual = createHash(algorithm).update(bytes).digest('base64');
+  if (actual !== expected) throw new Error('The downloaded theme failed registry integrity verification');
+}
+
+async function registryRelease(channel, fetchImpl) {
+  const response = await fetchImpl(`${REGISTRY}/${encodeURIComponent(PACKAGE)}`, {
+    headers: { Accept: 'application/json' },
+  });
+  if (!response.ok) throw new Error(`Theme registry lookup failed with HTTP ${response.status}`);
+  const metadata = await response.json();
+  const version = metadata?.['dist-tags']?.[channel];
+  const release = metadata?.versions?.[version];
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version ?? '') || !release?.dist?.tarball) {
+    throw new Error(`Theme channel ${channel} has no valid release`);
+  }
+  if (release.scripts && Object.keys(release.scripts).length > 0) {
+    throw new Error('Theme release contains lifecycle scripts and was refused');
+  }
+  return { version, tarball: release.dist.tarball, integrity: release.dist.integrity };
+}
+
+async function unpackRelease(release, fetchImpl) {
+  const response = await fetchImpl(release.tarball);
+  if (!response.ok) throw new Error(`Theme download failed with HTTP ${response.status}`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  verifyIntegrity(bytes, release.integrity);
+  const temporary = await mkdtemp(path.join(tmpdir(), 'gala-theme-upgrade-'));
+  const archive = path.join(temporary, 'theme.tgz');
+  const extracted = path.join(temporary, 'unpacked');
+  await mkdir(extracted);
+  await writeFile(archive, bytes);
+  await extractTar({ file: archive, cwd: extracted, strip: 1, strict: true });
+  return { temporary, payload: path.join(extracted, 'payload') };
+}
+
+async function readManifest(file) {
+  const manifest = JSON.parse(await readFile(file, 'utf8'));
+  if (manifest?.schemaVersion !== 1 || typeof manifest.files !== 'object') {
+    throw new Error('Theme managed-file manifest is invalid');
+  }
+  for (const managed of Object.keys(manifest.files)) {
+    if (!safeManagedPath(managed)) throw new Error(`Theme release contains protected path: ${managed}`);
+  }
+  return manifest;
+}
+
+async function verifyPayload(payload, manifest) {
+  for (const [managed, expected] of Object.entries(manifest.files)) {
+    const artifact = manifest.artifactSources?.[managed] ?? managed;
+    if (!safeManagedPath(artifact)) throw new Error(`Theme artifact path is unsafe: ${artifact}`);
+    const bytes = await readFile(path.join(payload, artifact));
+    if (sha256(bytes) !== expected) throw new Error(`Theme payload hash mismatch: ${managed}`);
+  }
+}
+
+async function assertNoManagedDrift(root, installed) {
+  for (const [managed, expected] of Object.entries(installed.files)) {
+    const file = path.join(root, managed);
+    if (!await exists(file) || (await lstat(file)).isSymbolicLink() || sha256(await readFile(file)) !== expected) {
+      throw new Error(`${managed} has local changes; restore it with gala doctor before upgrading`);
+    }
+  }
+}
+
+async function replaceFile(target, bytes) {
+  await mkdir(path.dirname(target), { recursive: true });
+  const temporary = `${target}.gala-upgrade-${process.pid}`;
+  await writeFile(temporary, bytes);
+  await rename(temporary, target);
+}
+
+async function applyRelease(root, payload, installed, available) {
+  const configFile = path.join(root, 'site.config.yml');
+  const manifestFile = path.join(root, '.gala', 'managed-files.json');
+  const config = await readFile(configFile, 'utf8');
+  const updated = config.replace(
+    /(themePackage:\s*\n(?:\s+.*\n)*?\s+version:\s*)[^\s#]+/,
+    `$1${available.themePackage.version}`,
+  );
+  if (updated === config) throw new Error('site.config.yml has no framework.themePackage.version');
+  const backup = await mkdtemp(path.join(tmpdir(), 'gala-theme-rollback-'));
+  const previousFiles = Object.keys(installed.files);
+  try {
+    for (const managed of previousFiles) {
+      const target = path.join(root, managed);
+      const saved = path.join(backup, managed);
+      await mkdir(path.dirname(saved), { recursive: true });
+      await copyFile(target, saved);
+    }
+    await copyFile(configFile, path.join(backup, 'site.config.yml'));
+    await copyFile(manifestFile, path.join(backup, 'managed-files.json'));
+    for (const managed of previousFiles) {
+      if (available.files[managed] == null) await rm(path.join(root, managed));
+    }
+    for (const managed of Object.keys(available.files)) {
+      const artifact = available.artifactSources?.[managed] ?? managed;
+      await replaceFile(path.join(root, managed), await readFile(path.join(payload, artifact)));
+    }
+    await replaceFile(configFile, updated);
+    await replaceFile(manifestFile, `${JSON.stringify(available, null, 2)}\n`);
+  } catch (error) {
+    for (const managed of Object.keys(available.files)) {
+      if (installed.files[managed] == null) await rm(path.join(root, managed), { force: true });
+    }
+    for (const managed of previousFiles) {
+      await replaceFile(path.join(root, managed), await readFile(path.join(backup, managed)));
+    }
+    await replaceFile(configFile, await readFile(path.join(backup, 'site.config.yml')));
+    await replaceFile(manifestFile, await readFile(path.join(backup, 'managed-files.json')));
+    throw error;
+  } finally {
+    await rm(backup, { recursive: true, force: true });
+  }
+}
+
+export async function upgrade({ terminal, options, cwd = process.cwd(), fetchImpl = fetch }) {
+  const root = path.resolve(options.value('root') ?? cwd);
+  const channel = options.value('channel') ?? 'latest';
+  if (!['latest', 'next'].includes(channel)) throw new Error('channel must be latest or next');
+  const installed = await readManifest(path.join(root, '.gala', 'managed-files.json'));
+  const release = await registryRelease(channel, fetchImpl);
+  terminal.result(`Theme ${installed.themePackage.version} → ${release.version} (${channel})`);
+  if (installed.themePackage.version === release.version) {
+    terminal.note('Already current.');
+    return { changed: false, version: release.version };
+  }
+  if (!options.on('yes')) {
+    const answer = await terminal.ask('Apply this managed theme upgrade? [y/N]', { fallback: 'no' });
+    if (!/^y(?:es)?$/i.test(answer)) {
+      terminal.note('Nothing changed.');
+      return { changed: false, version: release.version };
+    }
+  }
+  await assertNoManagedDrift(root, installed);
+  const unpacked = await unpackRelease(release, fetchImpl);
+  try {
+    const available = await readManifest(path.join(unpacked.payload, '.gala', 'managed-files.json'));
+    if (available.themePackage.version !== release.version) {
+      throw new Error('Theme package version does not match its managed manifest');
+    }
+    await verifyPayload(unpacked.payload, available);
+    await applyRelease(root, unpacked.payload, installed, available);
+  } finally {
+    await rm(unpacked.temporary, { recursive: true, force: true });
+  }
+  terminal.done(`Upgraded managed theme to ${release.version}`);
+  terminal.note('Run gala preview, then gala publish when the result is approved.');
+  return { changed: true, version: release.version };
+}

package/src/commands-manifest.js

@@ -1,12 +1,15 @@
 import { auth } from './commands/auth.js';
 import { doctor } from './commands/doctor.js';
+import { domain } from './commands/domain.js';
 import { init } from './commands/init.js';
 import { createPost } from './commands/new.js';
 import { preview } from './commands/preview.js';
 import { publish } from './commands/publish.js';
+import { prism } from './commands/prism.js';
+import { upgrade } from './commands/upgrade.js';
 
 /**
- * Six commands, in the order a writer meets them.
+ * Commands in the order a writer meets them.
  *
  * v0 had fifteen, and the extra nine were the ones nobody could keep working: a `validate` a hook
  * ran behind the writer's back, a `workflow` writer for a file the server owns, a
@@ -27,12 +30,17 @@ export const COMMANDS = {
     run: auth
   },
   init: {
-    summary: 'Create a publication and clone it here',
-    usage: 'gala init [--name my-notes] [--here]',
-    flags: ['name', 'api-base-url'],
-    switches: ['here'],
+    summary: 'Create a publication in an empty directory',
+    usage: 'gala init [directory] [--name my-notes] [--domain blog.example.com]',
+    flags: ['name', 'domain', 'api-base-url'],
     run: init
   },
+  domain: {
+    summary: 'Inspect or change this publication’s custom domain',
+    usage: 'gala domain [status|set <hostname>|check|cancel|remove] [--root path]',
+    flags: ['root', 'api-base-url'],
+    run: domain
+  },
   new: {
     summary: 'Start a post',
     usage: 'gala new "A durable idea" [--language en]',
@@ -50,6 +58,20 @@ export const COMMANDS = {
     switches: ['skip-checks'],
     run: publish
   },
+  prism: {
+    summary: 'Manage author-approved Prism configurations',
+    usage: 'gala prism <status|mode|link-policy|list|create|edit|generate|submit|approve|reject|revoke> [arguments]',
+    flags: ['root', 'api-base-url', 'language', 'depth', 'intent', 'modality', 'file', 'reason'],
+    switches: ['yes'],
+    run: prism
+  },
+  upgrade: {
+    summary: 'Inspect and apply a verified managed-theme update',
+    usage: 'gala upgrade [--channel latest|next] [--yes]',
+    flags: ['root', 'channel'],
+    switches: ['yes'],
+    run: upgrade
+  },
   doctor: {
     summary: 'Check a publication and say what is wrong',
     flags: ['root', 'api-base-url'],

package/src/domain.js

@@ -0,0 +1,33 @@
+// Generated by scripts/generate-custom-domain.mjs. Do not edit.
+const HOST = new RegExp("^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$");
+const MAXIMUM_HOSTNAME_LENGTH = 63;
+const FORBIDDEN_PREFIXES = ["www.www."];
+const FORBIDDEN_SUFFIXES = [".github.io"];
+const MESSAGE = {
+  "empty": "Enter a domain such as blog.example.com.",
+  "components": "Enter only the hostname, without a protocol, path, port or credentials.",
+  "policy": "Enter a valid custom hostname shorter than 64 characters and outside github.io.",
+  "labels": "Enter a complete domain with valid DNS labels.",
+  "invalid": "Enter a valid domain such as blog.example.com."
+};
+
+export function customDomain(value) {
+  const source = typeof value === 'string' ? value.trim().toLowerCase().replace(/\.$/, '') : '';
+  if (!source) return { error: MESSAGE.empty };
+  try {
+    const parsed = new URL(`https://${source}`);
+    if (parsed.username || parsed.password || parsed.port || parsed.pathname !== '/'
+        || parsed.search || parsed.hash || parsed.hostname !== source) {
+      return { error: MESSAGE.components };
+    }
+    if (source.length > MAXIMUM_HOSTNAME_LENGTH
+        || FORBIDDEN_PREFIXES.some((prefix) => source.startsWith(prefix))
+        || FORBIDDEN_SUFFIXES.some((suffix) => source.endsWith(suffix))) {
+      return { error: MESSAGE.policy };
+    }
+    if (!HOST.test(source)) return { error: MESSAGE.labels };
+    return { host: source };
+  } catch {
+    return { error: MESSAGE.invalid };
+  }
+}

package/src/git.js

@@ -141,3 +141,20 @@ export function cloneRepository({ url, target, token, spawnProcess = spawn }) {
     });
   });
 }
+
+/** Populate a deliberately empty git repository without replacing its .git directory. */
+export async function populateEmptyRepository({ url, target, token, spawnProcess = spawn }) {
+  const git = createGit({ root: target, token, spawnProcess });
+  const hasOrigin = await git.run(['remote', 'get-url', 'origin'], { allow: [0, 2] });
+  await git.run(hasOrigin === 0
+    ? ['remote', 'set-url', 'origin', url]
+    : ['remote', 'add', 'origin', url]);
+  await git.run(['fetch', 'origin']);
+  const remoteHead = await git.run(['ls-remote', '--symref', 'origin', 'HEAD'], { capture: true });
+  const branch = /^ref: refs\/heads\/([^\s]+)\s+HEAD$/m.exec(remoteHead)?.[1];
+  if (!branch || !/^[A-Za-z0-9._/-]+$/.test(branch)) {
+    throw new Error('GitHub did not report a usable default branch');
+  }
+  await git.run(['checkout', '-B', branch, '--track', `origin/${branch}`]);
+  return path.resolve(target);
+}

package/src/publication.js

@@ -21,6 +21,8 @@ export async function readPublication(root) {
       ? configuration.hosting.pathPrefix
       : '/';
     return {
+      siteId: configuration?.site?.id,
+      repository: configuration?.site?.repository,
       name: configuration?.site?.name,
       defaultLanguage: configuration?.site?.defaultLanguage ?? 'en',
       url: `${base.replace(/\/$/, '')}${prefix === '/' ? '' : prefix}/`