@rathnasgala/cli 0.0.8 → 0.0.13

package/README.md

@@ -0,0 +1,275 @@
+# Gala CLI
+
+Create, validate, preview, publish, and maintain a GitHub-backed Gala publication from your terminal.
+
+The quick start below begins with the required accounts and tools and does not assume a global CLI installation.
+
+## Requirements
+
+- [Git](https://git-scm.com/downloads)
+- [Node.js 24](https://nodejs.org/en/download) recommended; the CLI package supports Node.js 18 or newer
+- A [GitHub account](https://github.com/signup)
+- The [Gala GitHub App](https://github.com/apps/gala67-app/installations/new) — `scaffold` walks you through installing it if it is not already
+
+Check your local tools:
+
+```console
+node --version
+npm --version
+git --version
+```
+
+You should see something like this:
+```console
+v22.18.0
+10.9.3
+git version 2.50.1 (Apple Git-155)
+```
+
+## Quick start
+
+One command, run inside an empty folder named after the publication you want:
+
+```console
+mkdir field-notes && cd field-notes
+npx --yes @rathnasgala/cli@latest scaffold --target ./ --mode build-and-deploy
+```
+
+That single command does all of the following, and asks only for what it cannot work out:
+
+1. **Signs you in to Gala** if no valid token is stored, showing a code to enter in the browser.
+2. **Signs you in to GitHub** the same way, requesting `repo` to create the publication and install
+   its Actions secret, and `workflow` for the initial scaffold. Ordinary publishing needs neither.
+3. **Reads your GitHub account** from that token, so there is no username to type.
+4. **Finds the Gala GitHub App installation** for your account. If the App is not installed yet it
+   prints the installation page, waits while you install it, and carries on — the installation ID
+   is never something you have to read out of a URL.
+5. **Names the publication** after the folder you are standing in.
+6. **Creates the repository** from the site template, registers it, installs its one-time secret,
+   writes the publication workflow, commits, and enables GitHub Pages.
+
+Both sign-ins are skipped when a valid credential is already stored, so re-running is cheap.
+
+After scaffolding succeeds, open [GitHub App settings](https://github.com/settings/installations)
+and restrict the App to the publication repository if you installed it against all of them.
+
+### Write, preview, and publish
+
+```console
+npx --yes @rathnasgala/cli@latest new --title "My first post" --language en
+npx --yes @rathnasgala/cli@latest preview
+npx --yes @rathnasgala/cli@latest publish
+```
+
+`new` prints the Markdown file it created. Write below the second `---` line, save the file,
+preview it locally, then publish it through GitHub.
+
+### Overriding what scaffold works out
+
+Every derived value is still an explicit flag, for the cases where the default is wrong — a
+publication owned by an organisation, a folder named differently from the repository, or more than
+one App installation on the account:
+
+```console
+npx --yes @rathnasgala/cli@latest scaffold \
+  --owner YOUR_GITHUB_USERNAME \
+  --repository YOUR_REPOSITORY_NAME \
+  --target ./YOUR_REPOSITORY_NAME \
+  --installation-id YOUR_INSTALLATION_ID \
+  --mode build-and-deploy
+```
+
+`--repository` is otherwise taken from `--target`, then from `--site-name`, and only then asked
+for. Outside a terminal — in CI — nothing is ever prompted for: a value that cannot be derived is
+an error, so an automated run fails fast instead of waiting for an answer that will not come.
+
+## Command reference
+
+Run commands through `npx` without installing a global package:
+
+```console
+npx --yes @rathnasgala/cli@latest COMMAND [options]
+```
+
+Inside the table below, `gala` is shorthand for that prefix.
+
+| Command | Purpose | Common options |
+| --- | --- | --- |
+| `gala auth` | Authenticate the author with Gala | `--api-base-url URL` for a non-production API |
+| `gala auth github` | Authenticate the CLI with GitHub | Browser device flow; requests `repo workflow` |
+| `gala scaffold` | Sign in if needed, then create and register a publication | All derived; override with `--owner`, `--repository`, `--target`, `--installation-id`, `--mode` |
+| `gala configure` | Update author-owned site and design settings | `--root`, plus the configuration options below |
+| `gala new` | Create a Markdown post variant | `--root`, `--title`, `--language`, `--today` |
+| `gala validate` | Validate repository content without publishing | optional root path, `--today` |
+| `gala preview` | Validate and run the local Eleventy preview | `--root`, `--today` |
+| `gala publish` | Validate, commit, and push publication changes | `--root`, `--today`, `--force` |
+| `gala doctor` | Report managed-framework drift and publication-state validity | optional root path; `--fix --source TRUSTED_ROOT` |
+| `gala hook install` | Install the pre-push validation hook | `--root` |
+| `gala refresh` | Refresh and commit the engagement snapshot | `--root` |
+| `gala upgrade` | Verify and install an exact theme-package release | `--root`, `--channel`, `--yes` |
+| `gala topology` | Switch canonical origin/path topology transactionally | `--root`, `--owner`, `--repository`, `--canonical-base-url`, `--path-prefix` |
+| `gala entitlement` | Retrieve and commit the current paid attribution artifact | `--root` |
+| `gala workflow` | Write the reusable GitHub Actions workflow | `--root`, `--site-id`, `--timezone`, `--action-ref`, `--default-branch`, `--mode` |
+| `gala record-deployment` | Record state after a successful deployment | `--root`, `--today`, `--commit-sha` |
+
+### Scaffold and configure options
+
+The same author-owned options are accepted by `scaffold` and `configure`:
+
+```text
+--site-name
+--author
+--language
+--timezone
+--theme
+--layout
+--palette
+--typography
+--spacing
+--radius
+--density
+--motion
+--componentStyle
+--share-target       repeatable
+--social-profile     repeatable
+```
+
+Use only identities supported by the installed theme package. Validation rejects unavailable layout, palette, and theme identities instead of silently substituting another design.
+
+### Scaffold an existing empty repository
+
+Use this only when the exact GitHub repository already exists and has no branches or content:
+
+```console
+npx --yes @rathnasgala/cli@latest scaffold \
+  --repository YOUR_REPOSITORY_NAME \
+  --empty-existing-repository
+```
+
+### Resume interrupted scaffolding
+
+The target must already be a checkout whose HTTPS origin exactly matches the requested repository:
+
+```console
+npx --yes @rathnasgala/cli@latest scaffold \
+  --repository YOUR_REPOSITORY_NAME \
+  --target ./YOUR_REPOSITORY_NAME \
+  --resume
+```
+
+Scaffolding is designed to converge after partial failure. It will not adopt a non-empty unrelated repository.
+
+### Build without deploying
+
+```console
+npx --yes @rathnasgala/cli@latest scaffold ... --mode build-only
+```
+
+`build-only` writes and validates the site but does not provision GitHub Pages. `build-and-deploy` is the default.
+
+## Everyday workflow
+
+Create another post:
+
+```console
+npx --yes @rathnasgala/cli@latest new --title "A durable idea" --language en
+```
+
+Validate without running a preview server:
+
+```console
+npx --yes @rathnasgala/cli@latest validate
+```
+
+Preview locally:
+
+```console
+npx --yes @rathnasgala/cli@latest preview
+```
+
+Publish:
+
+```console
+npx --yes @rathnasgala/cli@latest publish
+```
+
+Check managed files and recorded publication state:
+
+```console
+npx --yes @rathnasgala/cli@latest doctor
+```
+
+## Security and ownership
+
+- Your repository remains the canonical source for publication content and configuration.
+- Gala credentials and GitHub OAuth credentials are stored outside the repository.
+- Credential directories are created with private permissions; credential files use mode `0600` on operating systems that support POSIX modes.
+- The site signing secret is returned once by the API and sealed directly into GitHub Actions secrets.
+- Do not copy credential files into the repository, dotfiles, cloud-sync folders, or `/tmp`.
+- The generated workflow pins the public Gala Action contract; managed framework files are integrity-checked before repair or upgrade.
+
+## Troubleshooting
+
+### `GitHub authentication is missing`
+
+Run:
+
+```console
+npx --yes @rathnasgala/cli@latest auth github
+```
+
+### Gala authentication expired
+
+Gala author tokens expire and do not use a refresh token. Run:
+
+```console
+npx --yes @rathnasgala/cli@latest auth
+```
+
+### `The Gala GitHub App is not installed on YOUR_ACCOUNT`
+
+`scaffold` could not find an installation covering that account. At a terminal it prints the
+installation page and waits; in CI it stops, because there is nobody to install it. Install the App
+at [the installation page](https://github.com/apps/gala67-app/installations/new) and run `scaffold`
+again, or pass `--installation-id` explicitly.
+
+### The App cannot access the new repository
+
+Open [GitHub App settings](https://github.com/settings/installations) and add the publication repository to the Gala installation. The platform verifies access to the exact repository; the existence of an installation alone is insufficient.
+
+### The target folder already exists
+
+Do not delete or overwrite it blindly. Use `--resume` only when it is the intended repository checkout. Use `--empty-existing-repository` only when the remote GitHub repository is genuinely empty.
+
+### Validation refuses a post
+
+The error includes the source file and violated rule. Correct the file and run:
+
+```console
+npx --yes @rathnasgala/cli@latest validate
+```
+
+Do not use `publish --force` as a routine bypass. It skips content validation but does not force-push Git history.
+
+### Managed files have drifted
+
+Inspect first:
+
+```console
+npx --yes @rathnasgala/cli@latest doctor
+```
+
+Repair requires a trusted, hash-verified theme source:
+
+```console
+npx --yes @rathnasgala/cli@latest doctor --fix --source PATH_TO_TRUSTED_THEME
+```
+
+## Package and source
+
+- npm: [`@rathnasgala/cli`](https://www.npmjs.com/package/@rathnasgala/cli)
+- source: [`rathnasgala/cli`](https://github.com/rathnasgala/cli)
+
+## License
+
+The repository does not currently declare a license. Copyright remains with its owner unless and until a license is added.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala/cli",
-  "version": "0.0.8",
+  "version": "0.0.13",
   "type": "module",
   "files": [
     "src"
@@ -26,7 +26,7 @@
     "url": "git+https://github.com/rathnasgala/cli.git"
   },
   "dependencies": {
-    "@rathnasgala/content-validation": "0.0.2",
+    "@rathnasgala/content-validation": "0.0.8",
     "libsodium-wrappers": "0.8.4",
     "tar": "7.5.22",
     "yaml": "2.9.0"

package/src/configure-site.js

@@ -5,6 +5,11 @@ import { parseDocument } from 'yaml';
 
 import { scaffoldOptionNames } from './scaffold-options.js';
 
+const IMPLEMENTED_DESIGN_VALUES = Object.freeze({
+  layout: Object.freeze(['article-first', 'portfolio']),
+  palette: Object.freeze(['default', 'ocean'])
+});
+
 function nonEmptyString(value, field) {
   if (typeof value !== 'string' || value.trim() === '') {
     throw new TypeError(`${field} must be a non-empty string`);
@@ -46,6 +51,9 @@ export async function configureSite(root, designOptions) {
   for (const [name, value] of Object.entries(designOptions)) {
     if (scaffoldOptionNames.includes(name)) {
       config.design[name] = nonEmptyString(value, `Design option ${name}`);
+      if (IMPLEMENTED_DESIGN_VALUES[name]?.includes(config.design[name]) === false) {
+        throw new TypeError(`Unsupported design ${name}: ${config.design[name]}`);
+      }
       document.setIn(['design', name], config.design[name]);
     }
   }

package/src/entitlement-client.js

@@ -0,0 +1,26 @@
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const FIELDS = ['expiresAt', 'issuedAt', 'keyId', 'signature', 'siteId', 'tier'];
+
+export async function fetchAttributionEntitlement({ siteId, credential, fetchImpl = fetch }) {
+  if (!ULID.test(siteId)) throw new TypeError('siteId must be a canonical ULID');
+  const endpoint = new URL(`/v1/sites/${siteId}/attribution-entitlement`, credential.apiBaseUrl);
+  const loopback = endpoint.protocol === 'http:'
+    && ['127.0.0.1', 'localhost', '::1'].includes(endpoint.hostname);
+  if ((endpoint.protocol !== 'https:' && !loopback) || endpoint.username || endpoint.password) {
+    throw new TypeError('Gala API URL must be credential-free HTTPS or HTTP loopback');
+  }
+  const response = await fetchImpl(endpoint, {
+    headers: { Authorization: `Bearer ${credential.accessToken}`, Accept: 'application/json' }
+  });
+  if (!response.ok) throw new Error(`Attribution entitlement retrieval failed with HTTP ${response.status}`);
+  const artifact = await response.json();
+  if (artifact == null || Array.isArray(artifact) || typeof artifact !== 'object'
+      || Object.keys(artifact).sort().join('\0') !== FIELDS.join('\0')
+      || artifact.siteId !== siteId || artifact.tier !== 'PAID'
+      || !['issuedAt', 'expiresAt', 'keyId', 'signature'].every(
+        (field) => typeof artifact[field] === 'string' && artifact[field].length > 0
+      )) {
+    throw new TypeError('Attribution entitlement response is invalid');
+  }
+  return artifact;
+}

package/src/entitlement-command.js

@@ -0,0 +1,74 @@
+import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { parse } from 'yaml';
+import { readGalaCredential } from './gala-credential-store.js';
+import { fetchAttributionEntitlement } from './entitlement-client.js';
+
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const ARTIFACT = '.gala/entitlement.json';
+
+async function runGit(root, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', ['-C', root, ...args], { shell: false, stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) reject(new Error(`git terminated by signal ${signal}`));
+      else if (code !== 0) reject(new Error(`git ${args[0]} exited with code ${code}`));
+      else resolve();
+    });
+  });
+}
+
+async function commitArtifact(root) {
+  await runGit(root, ['add', '--', ARTIFACT]);
+  await runGit(root, ['commit', '--message', 'chore(gala): update attribution entitlement', '--', ARTIFACT]);
+  await runGit(root, ['push']);
+}
+
+export async function acquireAttributionEntitlement({
+  root = process.cwd(), readCredential = readGalaCredential,
+  fetchEntitlement = fetchAttributionEntitlement, commit = commitArtifact
+} = {}) {
+  const siteRoot = path.resolve(root);
+  const configTarget = path.join(siteRoot, 'site.config.yml');
+  const metadata = await lstat(configTarget);
+  if (!metadata.isFile() || metadata.isSymbolicLink()) {
+    throw new TypeError('site.config.yml must be a regular file');
+  }
+  const config = parse(await readFile(configTarget, 'utf8'));
+  const siteId = config?.site?.id;
+  if (!ULID.test(siteId)) throw new TypeError('site.config.yml site.id must be a canonical ULID');
+  const artifact = await fetchEntitlement({ siteId, credential: await readCredential() });
+  const directory = path.join(siteRoot, '.gala');
+  await mkdir(directory, { recursive: true });
+  const directoryMetadata = await lstat(directory);
+  if (!directoryMetadata.isDirectory() || directoryMetadata.isSymbolicLink()) {
+    throw new TypeError('.gala must be a real directory');
+  }
+  const target = path.join(siteRoot, ARTIFACT);
+  try {
+    const current = await lstat(target);
+    if (!current.isFile() || current.isSymbolicLink()) {
+      throw new TypeError('Attribution entitlement must be a regular file');
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const serialized = `${JSON.stringify(artifact, null, 2)}\n`;
+  try {
+    if (await readFile(target, 'utf8') === serialized) return Object.freeze({ changed: false, siteId });
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const temporary = `${target}.gala-${process.pid}`;
+  try {
+    await writeFile(temporary, serialized, { flag: 'wx' });
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+  await commit(siteRoot);
+  return Object.freeze({ changed: true, siteId });
+}

package/src/gala-installation-client.js

@@ -0,0 +1,75 @@
+/**
+ * Which Gala GitHub App installation covers this writer's account.
+ *
+ * The installation ID is an internal GitHub identifier that `scaffold` has to send when it
+ * registers a site. Until now the writer supplied it by installing the App, watching GitHub
+ * redirect to `https://github.com/settings/installations/153144989`, and copying the number out of
+ * the address bar — an internal identifier, read out of a URL, by hand.
+ *
+ * The Gala API already knows it. `GET /v1/auth/github/repositories` answers with
+ * `{ installationId, owner, name, status }` per repository, so the CLI can ask the same service it
+ * is about to register with rather than guess. Reaching that endpoint needs the bounded capability
+ * from `POST /v1/auth/github/device-authorizations`, which is bound to the Gala user and takes the
+ * GitHub token the CLI already holds.
+ */
+function endpoint(apiBaseUrl, path) {
+  return `${String(apiBaseUrl).replace(/\/$/, '')}${path}`;
+}
+
+export async function exchangeGithubAuthorization({
+  apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl = fetch
+}) {
+  const response = await fetchImpl(endpoint(apiBaseUrl, '/v1/auth/github/device-authorizations'), {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${galaAccessToken}`,
+      'content-type': 'application/json'
+    },
+    body: JSON.stringify({ accessToken: githubAccessToken })
+  });
+  if (!response.ok) {
+    throw new Error(`GitHub authorization exchange failed with HTTP ${response.status}`);
+  }
+  const payload = await response.json();
+  if (typeof payload?.authorization !== 'string') {
+    throw new TypeError('GitHub authorization exchange returned no capability');
+  }
+  return payload.authorization;
+}
+
+export async function listAuthorizedRepositories({ apiBaseUrl, authorization, fetchImpl = fetch }) {
+  const response = await fetchImpl(endpoint(apiBaseUrl, '/v1/auth/github/repositories'), {
+    headers: { accept: 'application/json', 'GitHub-Authorization': authorization }
+  });
+  if (!response.ok) {
+    throw new Error(`Authorized repository lookup failed with HTTP ${response.status}`);
+  }
+  const payload = await response.json();
+  if (!Array.isArray(payload)) throw new TypeError('Authorized repository lookup returned no list');
+  return payload;
+}
+
+/**
+ * Returns the installation covering `owner`, or null when the App is not installed there.
+ *
+ * An installation belongs to an account, not to one repository, so any repository the App can
+ * already see under that owner carries the id the new one will use. Null is an ordinary answer —
+ * it means "not installed yet" — and the caller turns it into an instruction, not an error.
+ */
+export async function resolveInstallationId({
+  apiBaseUrl, galaAccessToken, githubAccessToken, owner, fetchImpl = fetch,
+  exchange = exchangeGithubAuthorization, list = listAuthorizedRepositories
+}) {
+  const authorization = await exchange({
+    apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl
+  });
+  const repositories = await list({ apiBaseUrl, authorization, fetchImpl });
+  const wanted = String(owner).toLowerCase();
+  for (const repository of repositories) {
+    if (String(repository?.owner).toLowerCase() !== wanted) continue;
+    const installationId = Number(repository?.installationId);
+    if (Number.isSafeInteger(installationId) && installationId > 0) return installationId;
+  }
+  return null;
+}

package/src/github-identity.js

@@ -0,0 +1,31 @@
+const GITHUB_API_VERSION = '2026-03-10';
+
+/**
+ * The GitHub account the stored credential belongs to.
+ *
+ * `scaffold` used to make the writer pass `--owner`, which is a value the token already knows and
+ * they can only get wrong. The credential file holds the token and its scopes and nothing else, so
+ * this is a live lookup rather than something cached at `auth github` time — a login can be
+ * changed, and a stale one would create the repository under a name that no longer exists.
+ */
+export async function resolveGithubLogin({ accessToken, fetchImpl = fetch }) {
+  if (typeof accessToken !== 'string' || accessToken === '') {
+    throw new TypeError('accessToken is required');
+  }
+  const response = await fetchImpl('https://api.github.com/user', {
+    headers: {
+      accept: 'application/vnd.github+json',
+      authorization: `Bearer ${accessToken}`,
+      'x-github-api-version': GITHUB_API_VERSION
+    }
+  });
+  if (!response.ok) throw new Error(`GitHub account lookup failed with HTTP ${response.status}`);
+  const payload = await response.json();
+  const login = payload?.login;
+  // The same shape `scaffold` demands of `--owner`. Refusing here beats a confusing failure four
+  // API calls later.
+  if (typeof login !== 'string' || !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/.test(login)) {
+    throw new TypeError('GitHub returned an unusable account login');
+  }
+  return login;
+}

package/src/index.js

@@ -20,9 +20,13 @@ import { createInterface } from 'node:readline/promises';
 import { upgradeTheme } from './upgrade-command.js';
 import { authenticateGithub } from './github-auth-command.js';
 import { scaffoldSite } from './scaffold-site.js';
+import { prepareScaffold } from './scaffold-preflight.js';
+import { refreshEngagementSnapshot } from './refresh-command.js';
+import { switchTopology } from './topology-command.js';
+import { acquireAttributionEntitlement } from './entitlement-command.js';
 
 const [command, ...args] = process.argv.slice(2);
-const usage = 'Usage: gala <auth|configure|scaffold|validate|new|doctor|hook|preview|publish|record-deployment|upgrade|workflow> [options]';
+const usage = 'Usage: gala <auth|configure|entitlement|scaffold|topology|validate|new|doctor|hook|preview|publish|record-deployment|refresh|upgrade|workflow> [options]';
 
 if (command === 'help' || command === '--help' || command === '-h'
     || args.includes('--help') || args.includes('-h')) {
@@ -32,7 +36,7 @@ if (command === 'help' || command === '--help' || command === '-h'
 
 const recognizedCommands = new Set([
   'auth', 'configure', 'validate', 'new', 'doctor', 'preview',
-  'workflow', 'publish', 'record-deployment', 'hook', 'upgrade'
+  'workflow', 'publish', 'record-deployment', 'refresh', 'hook', 'upgrade', 'topology', 'entitlement'
 ]);
 function commandRoot() {
   const rootIndex = args.indexOf('--root');
@@ -74,17 +78,37 @@ if (command === 'auth') {
     const index = args.indexOf(name);
     return index === -1 ? undefined : args[index + 1];
   };
-  const installationId = Number(valueFor('--installation-id'));
+  const explicitInstallationId = valueFor('--installation-id');
   const topology = valueFor('--topology') ?? 'provider-default';
-  const result = await scaffoldSite({
+  const siteOptions = parseScaffoldOptions(args);
+  // Prompting only makes sense at a terminal. In CI there is nobody to answer, so a missing value
+  // has to stay a clear error rather than a process that hangs waiting for enter.
+  const interactive = process.stdin.isTTY === true;
+  const ask = interactive
+    ? async (question) => {
+      const terminal = createInterface({ input: process.stdin, output: process.stdout });
+      try { return await terminal.question(question); } finally { terminal.close(); }
+    }
+    : undefined;
+  const prepared = await prepareScaffold({
     owner: valueFor('--owner'),
     repository: valueFor('--repository'),
     target: valueFor('--target'),
-    githubInstallationId: installationId,
+    githubInstallationId: explicitInstallationId == null ? undefined : Number(explicitInstallationId),
+    siteName: siteOptions.siteName,
+    apiBaseUrl: valueFor('--api-base-url') ?? 'https://api.gala67.com',
+    notify: (message) => process.stdout.write(`${message}\n`),
+    ask
+  });
+  const result = await scaffoldSite({
+    owner: prepared.owner,
+    repository: prepared.repository,
+    target: prepared.target,
+    githubInstallationId: prepared.githubInstallationId,
     topology,
     canonicalBaseUrl: valueFor('--canonical-base-url'),
     actionRef: valueFor('--action-ref'),
-    siteOptions: parseScaffoldOptions(args),
+    siteOptions,
     buildMode: valueFor('--mode') ?? 'build-and-deploy',
     emptyExistingRepository: args.includes('--empty-existing-repository'),
     resumeExistingCheckout: args.includes('--resume')
@@ -97,6 +121,27 @@ if (command === 'auth') {
   const options = parseScaffoldOptions(args);
   const config = await configureSite(root, options);
   process.stdout.write(`${JSON.stringify(config.design, null, 2)}\n`);
+} else if (command === 'topology') {
+  const valueFor = (name) => {
+    const index = args.indexOf(name);
+    return index === -1 ? undefined : args[index + 1];
+  };
+  const result = await switchTopology({
+    root: valueFor('--root') ?? process.cwd(),
+    owner: valueFor('--owner'),
+    repository: valueFor('--repository'),
+    canonicalBaseUrl: valueFor('--canonical-base-url'),
+    pathPrefix: valueFor('--path-prefix') ?? '/'
+  });
+  process.stdout.write(`Committed topology ${result.changeId} at ${result.commitSha}.\n`);
+} else if (command === 'entitlement') {
+  const rootIndex = args.indexOf('--root');
+  const result = await acquireAttributionEntitlement({
+    root: rootIndex === -1 ? process.cwd() : args[rootIndex + 1]
+  });
+  process.stdout.write(result.changed
+    ? `Stored the signed attribution entitlement for ${result.siteId}.\n`
+    : `Attribution entitlement for ${result.siteId} is current.\n`);
 } else if (command === 'validate') {
   const todayIndex = args.indexOf('--today');
   const today = todayIndex === -1 ? undefined : args[todayIndex + 1];
@@ -191,6 +236,13 @@ if (command === 'auth') {
     + `of ${result.state.posts.length} article(s).\n`
     + `Recorded state SHA: ${result.recordedStateSha}\n`
   );
+} else if (command === 'refresh') {
+  const rootIndex = args.indexOf('--root');
+  const root = rootIndex === -1 ? process.cwd() : args[rootIndex + 1];
+  const result = await refreshEngagementSnapshot({ root });
+  process.stdout.write(result.changed
+    ? 'Refreshed, committed, and pushed the engagement snapshot.\n'
+    : 'Engagement snapshot is already current.\n');
 } else if (command === 'upgrade') {
   const valueFor = (name) => {
     const index = args.indexOf(name);

package/src/refresh-command.js

@@ -0,0 +1,104 @@
+import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { parse } from 'yaml';
+
+import { readGalaCredential } from './gala-credential-store.js';
+
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const UTC_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+const SNAPSHOT_PATH = '.engagement-snapshot.json';
+
+async function runGit(root, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', ['-C', root, ...args], { shell: false, stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) reject(new Error(`git terminated by signal ${signal}`));
+      else if (code !== 0) reject(new Error(`git ${args[0]} exited with code ${code}`));
+      else resolve();
+    });
+  });
+}
+
+async function commitRefreshedSnapshot(root, relativePath) {
+  await runGit(root, [
+    'commit', '--only', '--message', 'chore(gala): refresh engagement snapshot', '--', relativePath
+  ]);
+  await runGit(root, ['push']);
+}
+
+function validateSnapshot(payload) {
+  if (payload?.schemaVersion !== 1 || !UTC_INSTANT.test(payload.refreshedAt)
+      || payload.articles == null || Array.isArray(payload.articles)
+      || typeof payload.articles !== 'object') {
+    throw new TypeError('Engagement snapshot response is invalid');
+  }
+  for (const [articleId, counts] of Object.entries(payload.articles)) {
+    if (!ULID.test(articleId) || counts == null || Array.isArray(counts)
+        || typeof counts !== 'object'
+        || Object.keys(counts).sort().join(',') !== 'comments,reactions,views'
+        || !['reactions', 'comments', 'views'].every(
+          (field) => Number.isSafeInteger(counts[field]) && counts[field] >= 0
+        )) {
+      throw new TypeError('Engagement snapshot response is invalid');
+    }
+  }
+  return payload;
+}
+
+async function requireRegularFile(target, label, { allowMissing = false } = {}) {
+  try {
+    const metadata = await lstat(target);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) {
+      throw new TypeError(`${label} must be a regular file`);
+    }
+    return true;
+  } catch (error) {
+    if (allowMissing && error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function refreshEngagementSnapshot({
+  root = process.cwd(),
+  readCredential = readGalaCredential,
+  fetchImpl = fetch,
+  commitSnapshot = commitRefreshedSnapshot
+} = {}) {
+  const siteRoot = path.resolve(root);
+  const configPath = path.join(siteRoot, 'site.config.yml');
+  await requireRegularFile(configPath, 'site.config.yml');
+  const config = parse(await readFile(configPath, 'utf8'));
+  const siteId = config?.site?.id;
+  if (!ULID.test(siteId)) throw new TypeError('site.config.yml site.id must be a canonical ULID');
+
+  const credential = await readCredential();
+  const endpoint = new URL(`/v1/sites/${siteId}/engagement-snapshot`, credential.apiBaseUrl);
+  const loopback = endpoint.protocol === 'http:'
+    && ['127.0.0.1', 'localhost', '::1'].includes(endpoint.hostname);
+  if ((endpoint.protocol !== 'https:' && !loopback) || endpoint.username || endpoint.password) {
+    throw new TypeError('Gala API URL must be credential-free HTTPS or HTTP loopback');
+  }
+  const response = await fetchImpl(endpoint, {
+    method: 'GET',
+    headers: { Authorization: `Bearer ${credential.accessToken}`, Accept: 'application/json' }
+  });
+  if (!response.ok) throw new Error(`Engagement snapshot refresh failed with HTTP ${response.status}`);
+  const snapshot = validateSnapshot(await response.json());
+  const next = `${JSON.stringify(snapshot, null, 2)}\n`;
+  const target = path.join(siteRoot, SNAPSHOT_PATH);
+  const exists = await requireRegularFile(target, 'Engagement snapshot', { allowMissing: true });
+  if (exists && await readFile(target, 'utf8') === next) return Object.freeze({ changed: false });
+
+  const temporary = `${target}.gala-${process.pid}`;
+  try {
+    await writeFile(temporary, next, { flag: 'wx' });
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+  await commitSnapshot(siteRoot, SNAPSHOT_PATH);
+  return Object.freeze({ changed: true });
+}

package/src/scaffold-preflight.js

@@ -0,0 +1,154 @@
+import path from 'node:path';
+
+import { authenticateGala } from './auth-command.js';
+import { authenticateGithub } from './github-auth-command.js';
+import { readGalaCredential } from './gala-credential-store.js';
+import { readGithubCredential } from './github-credential-store.js';
+import { resolveGithubLogin } from './github-identity.js';
+import { resolveInstallationId } from './gala-installation-client.js';
+
+export const GITHUB_APP_INSTALL_URL = 'https://github.com/apps/gala67-app/installations/new';
+
+const DEFAULT_API_BASE_URL = 'https://api.gala67.com';
+
+/**
+ * Everything `scaffold` needs, worked out rather than demanded.
+ *
+ * `scaffold` used to require four values up front — `--owner`, `--repository`, `--target` and
+ * `--installation-id` — and it failed outright if `auth` or `auth github` had not been run first,
+ * telling the writer to go and run them. Three of those four are derivable and the two sign-ins
+ * can simply happen. Every one of them is still accepted as an explicit override; nothing that
+ * worked before stops working.
+ *
+ * The steps are ordered so nothing is created until everything is known: the App installation is
+ * confirmed before a repository exists, rather than after, so an interrupted run leaves no
+ * half-connected repository behind.
+ */
+export async function prepareScaffold({
+  owner,
+  repository,
+  target,
+  githubInstallationId,
+  siteName,
+  cwd = process.cwd(),
+  notify = () => {},
+  ask,
+  installUrl = GITHUB_APP_INSTALL_URL,
+  installAttempts = 3,
+  readGala = readGalaCredential,
+  readGithub = readGithubCredential,
+  signInGala = authenticateGala,
+  signInGithub = authenticateGithub,
+  resolveLogin = resolveGithubLogin,
+  resolveInstallation = resolveInstallationId,
+  apiBaseUrl = DEFAULT_API_BASE_URL
+} = {}) {
+  const gala = await ensureGala({ apiBaseUrl, notify, readGala, signInGala });
+  const github = await ensureGithub({ notify, readGithub, signInGithub });
+
+  const resolvedOwner = owner ?? await resolveLogin({ accessToken: github.accessToken });
+
+  const resolvedRepository = repository
+    ?? (target == null ? null : path.basename(path.resolve(cwd, target)))
+    ?? repositoryNameFrom(siteName)
+    ?? await askForRepository(ask);
+
+  // `--target ./` is the common case and means "here", so the repository takes its name from the
+  // directory the writer is standing in. Everywhere else the repository names its own folder.
+  const resolvedTarget = target ?? `./${resolvedRepository}`;
+
+  const resolvedInstallation = githubInstallationId
+    ?? await ensureInstallation({
+      apiBaseUrl: gala.apiBaseUrl ?? apiBaseUrl,
+      galaAccessToken: gala.accessToken,
+      githubAccessToken: github.accessToken,
+      owner: resolvedOwner,
+      notify, ask, installUrl, installAttempts, resolveInstallation
+    });
+
+  return Object.freeze({
+    owner: resolvedOwner,
+    repository: resolvedRepository,
+    target: resolvedTarget,
+    githubInstallationId: resolvedInstallation
+  });
+}
+
+/** A missing or expired credential is a step to take, not an error to report. */
+async function ensureGala({ apiBaseUrl, notify, readGala, signInGala }) {
+  try {
+    return await readGala();
+  } catch {
+    notify('Signing in to Gala.');
+    await signInGala({
+      apiBaseUrl,
+      showInstructions: ({ verificationUri, userCode }) =>
+        notify(`Open ${verificationUri}\nEnter code: ${userCode}`)
+    });
+    return readGala();
+  }
+}
+
+async function ensureGithub({ notify, readGithub, signInGithub }) {
+  try {
+    return await readGithub();
+  } catch {
+    notify('Signing in to GitHub.');
+    await signInGithub({
+      showScopeWarning: ({ explanation }) => notify(`GitHub authorization: ${explanation}`),
+      showInstructions: ({ verificationUri, userCode }) =>
+        notify(`Open ${verificationUri}\nEnter code: ${userCode}`)
+    });
+    return readGithub();
+  }
+}
+
+/**
+ * Confirms the Gala GitHub App is installed, walking the writer through installing it if not.
+ *
+ * This is the step that used to be a manual detour through GitHub's settings to copy a number out
+ * of a redirect URL. The loop is what makes it a step rather than a failure: the writer installs
+ * the App in the browser, comes back, presses enter, and the run continues.
+ */
+async function ensureInstallation({
+  apiBaseUrl, galaAccessToken, githubAccessToken, owner,
+  notify, ask, installUrl, installAttempts, resolveInstallation
+}) {
+  for (let attempt = 0; attempt < Math.max(1, installAttempts); attempt += 1) {
+    const installationId = await resolveInstallation({
+      apiBaseUrl, galaAccessToken, githubAccessToken, owner
+    });
+    if (installationId != null) return installationId;
+
+    if (typeof ask !== 'function') {
+      throw new Error(
+        `The Gala GitHub App is not installed on ${owner}. Install it at ${installUrl} and run scaffold again, `
+        + 'or pass --installation-id explicitly.'
+      );
+    }
+    notify(`The Gala GitHub App is not installed on ${owner} yet.\nOpen ${installUrl}`);
+    await ask('Press enter once the App is installed. ');
+  }
+  throw new Error(
+    `The Gala GitHub App still does not cover ${owner}. Install it at ${installUrl}, then run scaffold again.`
+  );
+}
+
+/** GitHub repository names allow letters, digits, dot, underscore and hyphen, and nothing else. */
+export function repositoryNameFrom(siteName) {
+  if (typeof siteName !== 'string') return null;
+  const slug = siteName
+    .trim().toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug === '' ? null : slug;
+}
+
+async function askForRepository(ask) {
+  if (typeof ask !== 'function') {
+    throw new TypeError('repository is required; pass --repository or --site-name');
+  }
+  const answer = repositoryNameFrom(await ask('What should the publication repository be called? '));
+  if (answer == null) throw new TypeError('A repository name is required');
+  return answer;
+}

package/src/scaffold-site.js

@@ -5,7 +5,6 @@ import { configureSite } from './configure-site.js';
 import { readGalaCredential } from './gala-credential-store.js';
 import { readGithubCredential } from './github-credential-store.js';
 import { cloneRepository, generateRepositoryFromTemplate } from './github-template-repository.js';
-import { installRepositorySecret } from './github-repository-secret.js';
 import { installRepositoryVariable } from './github-repository-variable.js';
 import { provisionGithubPages } from './github-pages-provisioning.js';
 import { registerSite } from './site-registration-client.js';
@@ -54,7 +53,7 @@ export async function scaffoldSite({
   readGithub = readGithubCredential, readGala = readGalaCredential,
   generate = generateRepositoryFromTemplate, clone = cloneRepository,
   configure = configureSite, register = registerSite, finalize = writeRegisteredSiteConfiguration,
-  writeWorkflow = writePublishWorkflow, installSecret = installRepositorySecret,
+  writeWorkflow = writePublishWorkflow,
   installVariable = installRepositoryVariable,
   provisionPages = provisionGithubPages,
   commit = commitScaffold, verifyEmpty = verifyEmptyRepository, setOrigin = setRepositoryOrigin,
@@ -100,7 +99,8 @@ export async function scaffoldSite({
   const configured = await configure(root, siteOptions ?? {});
   const idempotencyKey = `scaffold-${createHash('sha256').update(`${repositoryOwner.toLowerCase()}/${repositoryName.toLowerCase()}`).digest('hex')}`;
   const registration = await register({
-    apiBaseUrl: gala.apiBaseUrl, galaAccessToken: gala.accessToken, idempotencyKey,
+    apiBaseUrl: gala.apiBaseUrl, galaAccessToken: gala.accessToken,
+    githubAccessToken: github.accessToken, idempotencyKey,
     githubInstallationId, repositoryOwner, repositoryName,
     topology: location.topology, canonicalBaseUrl: location.canonicalBaseUrl
   });
@@ -114,10 +114,6 @@ export async function scaffoldSite({
     root, siteId: registration.siteId, timezone: configured.site.timezone, buildMode,
     ...(actionRef == null ? {} : { actionRef })
   });
-  await installSecret({
-    owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken,
-    secretName: 'GALA_SITE_SECRET', secretValue: registration.siteSecret
-  });
   await installVariable({
     owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken,
     variableName: 'GALA_API_BASE_URL', variableValue: gala.apiBaseUrl

package/src/site-config-registration.js

@@ -6,7 +6,7 @@ export async function writeRegisteredSiteConfiguration(root, {
   siteId, canonicalBaseUrl, pathPrefix, topology
 }) {
   if (!/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/.test(siteId)) throw new TypeError('siteId is invalid');
-  if (!['provider-default', 'custom-domain'].includes(topology)) {
+  if (!['provider-default', 'custom-domain', 'domain-root', 'domain-subpath'].includes(topology)) {
     throw new TypeError('topology is invalid');
   }
   const canonical = new URL(canonicalBaseUrl);

package/src/site-registration-client.js

@@ -17,9 +17,33 @@ function apiUrl(apiBaseUrl) {
   return new URL('/v1/sites', base).href;
 }
 
+async function authorizeGitHub({ apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl }) {
+  if (typeof githubAccessToken !== 'string' || githubAccessToken === '') {
+    throw new Error('GitHub authentication is missing; run `gala auth`');
+  }
+  const response = await fetchImpl(new URL('/v1/auth/github/device-authorizations', apiBaseUrl), {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${galaAccessToken}`,
+      'content-type': 'application/json'
+    },
+    body: JSON.stringify({ accessToken: githubAccessToken })
+  });
+  if (response.status === 401) {
+    throw new Error('GitHub or Gala authentication expired; run `gala auth` again');
+  }
+  if (response.status !== 200) {
+    throw new Error(`GitHub repository authorization failed with HTTP ${response.status}`);
+  }
+  const payload = await response.json();
+  return required(payload?.authorization, 'GitHub authorization', /^[A-Za-z0-9_-]{43}$/);
+}
+
 export async function registerSite({
   apiBaseUrl = 'https://api.gala67.com',
   galaAccessToken,
+  githubAccessToken,
   idempotencyKey,
   githubInstallationId,
   repositoryOwner,
@@ -31,6 +55,9 @@ export async function registerSite({
   if (typeof galaAccessToken !== 'string' || galaAccessToken === '') {
     throw new Error('Gala authentication is missing; run `gala auth`');
   }
+  const githubAuthorization = await authorizeGitHub({
+    apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl
+  });
   required(idempotencyKey, 'idempotencyKey', IDEMPOTENCY_KEY);
   required(repositoryOwner, 'repositoryOwner', REPOSITORY_PART);
   required(repositoryName, 'repositoryName', REPOSITORY_PART);
@@ -46,6 +73,7 @@ export async function registerSite({
       accept: 'application/json',
       authorization: `Bearer ${galaAccessToken}`,
       'content-type': 'application/json',
+      'github-authorization': githubAuthorization,
       'idempotency-key': idempotencyKey
     },
     body: JSON.stringify({

package/src/topology-client.js

@@ -0,0 +1,43 @@
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+
+function endpoint(apiBaseUrl, siteId, suffix) {
+  if (!ULID.test(siteId)) throw new TypeError('siteId is invalid');
+  const base = new URL(apiBaseUrl);
+  const loopback = ['localhost', '127.0.0.1', '::1'].includes(base.hostname);
+  if ((base.protocol !== 'https:' && !(loopback && base.protocol === 'http:'))
+      || base.username || base.password || base.search || base.hash) {
+    throw new TypeError('apiBaseUrl must be a credential-free HTTPS URL (or HTTP loopback for testing)');
+  }
+  return new URL(`/v1/sites/${siteId}/topology-changes/${suffix}`, base).href;
+}
+
+async function response(response, operation) {
+  if (response.status === 401) throw new Error('Gala authentication expired; run `gala auth` again');
+  if (response.status === 404) throw new Error('Site is unavailable');
+  if (response.status === 409) throw new Error(`Topology ${operation} conflicts with protected state`);
+  if (!response.ok) throw new Error(`Topology ${operation} failed with HTTP ${response.status}`);
+  const payload = await response.json();
+  if (!ULID.test(payload?.changeId)) throw new TypeError('Topology response is invalid');
+  return Object.freeze(payload);
+}
+
+export async function prepareTopologyChange({
+  apiBaseUrl, accessToken, siteId, canonicalBaseUrl, pathPrefix, fetchImpl = fetch
+}) {
+  const result = await fetchImpl(endpoint(apiBaseUrl, siteId, 'prepare'), {
+    method: 'POST',
+    headers: { accept: 'application/json', authorization: `Bearer ${accessToken}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ canonicalBaseUrl, pathPrefix })
+  });
+  return response(result, 'prepare');
+}
+
+export async function commitTopologyChange({
+  apiBaseUrl, accessToken, siteId, changeId, fetchImpl = fetch
+}) {
+  if (!ULID.test(changeId)) throw new TypeError('changeId is invalid');
+  const result = await fetchImpl(endpoint(apiBaseUrl, siteId, `${changeId}/commit`), {
+    method: 'POST', headers: { accept: 'application/json', authorization: `Bearer ${accessToken}` }
+  });
+  return response(result, 'commit');
+}

package/src/topology-command.js

@@ -0,0 +1,70 @@
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from 'yaml';
+import { spawn } from 'node:child_process';
+import { readGalaCredential } from './gala-credential-store.js';
+import { readGithubCredential } from './github-credential-store.js';
+import { writeRegisteredSiteConfiguration } from './site-config-registration.js';
+import { prepareTopologyChange, commitTopologyChange } from './topology-client.js';
+import { provisionGithubPages } from './github-pages-provisioning.js';
+
+function run(root, args, spawnProcess, accepted = [0]) {
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['-C', root, ...args], { cwd: root, shell: false, stdio: ['ignore', 'pipe', 'inherit'] });
+    let output = '';
+    child.stdout?.on('data', (chunk) => { output += chunk; });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) reject(new Error(`Git ${args[0]} terminated by signal ${signal}`));
+      else if (!accepted.includes(code)) reject(new Error(`Git ${args[0]} exited with code ${code}`));
+      else resolve({ code, output: output.trim() });
+    });
+  });
+}
+
+export async function switchTopology({
+  root, owner, repository, canonicalBaseUrl, pathPrefix = '/',
+  readGala = readGalaCredential, readGithub = readGithubCredential,
+  prepare = prepareTopologyChange, commit = commitTopologyChange,
+  provisionPages = provisionGithubPages, spawnProcess = spawn
+}) {
+  if (typeof owner !== 'string' || !/^[A-Za-z0-9_.-]+$/.test(owner)
+      || typeof repository !== 'string' || !/^[A-Za-z0-9_.-]+$/.test(repository)) {
+    throw new TypeError('owner and repository are required GitHub path segments');
+  }
+  const siteRoot = path.resolve(root);
+  const config = parse(await readFile(path.join(siteRoot, 'site.config.yml'), 'utf8'));
+  const siteId = config?.site?.id;
+  if (!/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/.test(siteId)) throw new TypeError('site.config.yml has no valid site id');
+  const [gala, github] = await Promise.all([readGala(), readGithub()]);
+  const pending = await prepare({
+    apiBaseUrl: gala.apiBaseUrl, accessToken: gala.accessToken, siteId, canonicalBaseUrl, pathPrefix
+  });
+  // A site served under a path holds no domain of its own — GitHub lends it the one on the
+  // owner's main site — so the absence of a cname no longer means the provider address.
+  const topology = pending.canonicalBaseUrl === `https://${owner.toLowerCase()}.github.io`
+    ? 'provider-default' : (pending.pathPrefix === '/' ? 'domain-root' : 'domain-subpath');
+  await writeRegisteredSiteConfiguration(siteRoot, {
+    siteId, canonicalBaseUrl: pending.canonicalBaseUrl,
+    pathPrefix: pending.pathPrefix, topology
+  });
+  const cnamePath = path.join(siteRoot, 'CNAME');
+  if (pending.cname == null) await rm(cnamePath, { force: true });
+  else await writeFile(cnamePath, `${pending.cname}\n`, { encoding: 'utf8' });
+  await run(siteRoot, ['add', '-A', '--', 'site.config.yml', 'CNAME'], spawnProcess);
+  const unchanged = await run(siteRoot, ['diff', '--cached', '--quiet', '--exit-code'], spawnProcess, [0, 1]);
+  if (unchanged.code === 1) {
+    await run(siteRoot, ['commit', '-m', `chore(gala): switch topology to ${topology}`], spawnProcess);
+  }
+  await run(siteRoot, ['push', 'origin', 'HEAD'], spawnProcess);
+  const { output: commitSha } = await run(siteRoot, ['rev-parse', 'HEAD'], spawnProcess);
+  if (!/^[0-9a-f]{40}$/.test(commitSha)) throw new Error('Git returned an invalid topology commit SHA');
+  await provisionPages({
+    owner, repository, accessToken: github.accessToken, commitSha, customDomain: pending.cname
+  });
+  const committed = await commit({
+    apiBaseUrl: gala.apiBaseUrl, accessToken: gala.accessToken,
+    siteId, changeId: pending.changeId
+  });
+  return Object.freeze({ ...committed, commitSha });
+}

package/src/upgrade-command.js

@@ -45,6 +45,14 @@ export async function inspectActionUpgrade({ root, fetchImpl = fetch }) {
 export async function upgradeTheme({ root, channel, confirm, fetchImpl = fetch }) {
   const configPath = path.resolve(root, 'site.config.yml');
   const config = parse(await readFile(configPath, 'utf8'));
+  if (config?.canonicalPolicy != null) {
+    if (config.canonicalPolicy !== 'self' || config.hosting == null || Array.isArray(config.hosting)
+        || (config.hosting.canonicalPolicy != null && config.hosting.canonicalPolicy !== 'self')) {
+      throw new TypeError('Legacy canonicalPolicy cannot be migrated safely');
+    }
+    config.hosting.canonicalPolicy = 'self';
+    delete config.canonicalPolicy;
+  }
   const installed = config?.framework?.themePackage?.version;
   const [metadata, action] = await Promise.all([
     registryMetadata(fetchImpl), inspectActionUpgrade({ root, fetchImpl })