@rathnasgala/cli 0.0.7 → 0.0.12

package/README.md

@@ -0,0 +1,283 @@
+# 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) installed for the account that will own the publication
+
+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
+
+### 1. Authenticate with Gala
+
+```console
+npx --yes @rathnasgala/cli@latest auth
+```
+
+The CLI displays a short code and opens the platform authorization page. The resulting Gala token is stored in your operating system's application-config directory, never in the publication repository.
+
+### 2. Authenticate with GitHub
+
+```console
+npx --yes @rathnasgala/cli@latest auth github
+```
+
+GitHub OAuth Apps cannot restrict `repo` access to one repository. The CLI therefore requests:
+
+- `repo` to create the publication repository and install its Actions secret
+- `workflow` for initial scaffolding and explicit Action-major migrations
+
+The GitHub token is stored outside the repository with private file permissions. Gala does not require `workflow` for ordinary publishing or patch upgrades.
+
+### 3. Install the GitHub App
+
+Open the [Gala GitHub App installation page](https://github.com/apps/gala67-app/installations/new). For a new publication, select **All repositories** temporarily because the target repository does not exist yet.
+
+After installation, GitHub redirects to a URL ending in a number, for example:
+
+```text
+https://github.com/settings/installations/153144989
+```
+
+That final number is the installation ID required by `scaffold`.
+
+### 4. Scaffold the publication
+
+Replace every capitalized placeholder:
+
+```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
+```
+
+Scaffolding creates a public repository from `rathnasgala/site-template`, registers the site, installs the one-time site secret as a GitHub Actions secret, writes the publication workflow, commits the generated configuration, and enables GitHub Pages.
+
+After scaffolding succeeds, open [GitHub App settings](https://github.com/settings/installations) and restrict the App to the publication repository.
+
+### 5. Write, preview, and publish
+
+```console
+cd YOUR_REPOSITORY_NAME
+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.
+
+## 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` | Create and register a publication | `--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 \
+  --owner YOUR_GITHUB_USERNAME \
+  --repository YOUR_REPOSITORY_NAME \
+  --target ./YOUR_REPOSITORY_NAME \
+  --installation-id YOUR_INSTALLATION_ID \
+  --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 \
+  --owner YOUR_GITHUB_USERNAME \
+  --repository YOUR_REPOSITORY_NAME \
+  --target ./YOUR_REPOSITORY_NAME \
+  --installation-id YOUR_INSTALLATION_ID \
+  --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
+```
+
+### `githubInstallationId must be a positive integer`
+
+Open [GitHub App settings](https://github.com/settings/installations), select Gala, and copy the number at the end of the browser URL.
+
+### 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.7",
+  "version": "0.0.12",
   "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/github-pages-provisioning.js

@@ -25,6 +25,7 @@ async function json(response, operation) {
 
 export async function provisionGithubPages({
   owner, repository, accessToken, commitSha, fetchImpl = fetch,
+  customDomain = null,
   sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
   pollIntervalMs = 5_000, maxPolls = 120
 }) {
@@ -32,6 +33,10 @@ export async function provisionGithubPages({
   const normalizedRepository = required(repository, 'repository', SEGMENT);
   const token = required(accessToken, 'accessToken');
   const sha = required(commitSha, 'commitSha', SHA);
+  if (customDomain != null && (typeof customDomain !== 'string'
+      || !/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(customDomain))) {
+    throw new TypeError('customDomain is invalid');
+  }
   if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 0) {
     throw new TypeError('pollIntervalMs must be a non-negative safe integer');
   }
@@ -69,6 +74,15 @@ export async function provisionGithubPages({
     if (configuration.source?.branch !== 'gh-pages' || configuration.source?.path !== '/') {
       throw new Error('Existing GitHub Pages configuration does not use gh-pages at /');
     }
+    if ((configuration.cname ?? null) !== customDomain) {
+      const updated = await fetchImpl(`${repositoryUrl}/pages`, {
+        method: 'PUT', headers: requestHeaders,
+        body: JSON.stringify({ cname: customDomain, source: { branch: 'gh-pages', path: '/' } })
+      });
+      if (updated.status !== 204) {
+        throw new Error(`GitHub Pages custom-domain update failed with HTTP ${updated.status}`);
+      }
+    }
     return Object.freeze({ created: false, url: configuration.html_url, runUrl: run.html_url });
   }
   if (current.status !== 404) {
@@ -79,5 +93,14 @@ export async function provisionGithubPages({
     body: JSON.stringify({ source: { branch: 'gh-pages', path: '/' } })
   });
   const configuration = await json(created, 'Pages activation');
+  if (customDomain != null) {
+    const updated = await fetchImpl(`${repositoryUrl}/pages`, {
+      method: 'PUT', headers: requestHeaders,
+      body: JSON.stringify({ cname: customDomain, source: { branch: 'gh-pages', path: '/' } })
+    });
+    if (updated.status !== 204) {
+      throw new Error(`GitHub Pages custom-domain update failed with HTTP ${updated.status}`);
+    }
+  }
   return Object.freeze({ created: true, url: configuration.html_url, runUrl: run.html_url });
 }

package/src/index.js

@@ -20,9 +20,12 @@ 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 { 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 +35,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');
@@ -75,11 +78,15 @@ if (command === 'auth') {
     return index === -1 ? undefined : args[index + 1];
   };
   const installationId = Number(valueFor('--installation-id'));
+  const topology = valueFor('--topology') ?? 'provider-default';
   const result = await scaffoldSite({
     owner: valueFor('--owner'),
     repository: valueFor('--repository'),
     target: valueFor('--target'),
     githubInstallationId: installationId,
+    topology,
+    canonicalBaseUrl: valueFor('--canonical-base-url'),
+    actionRef: valueFor('--action-ref'),
     siteOptions: parseScaffoldOptions(args),
     buildMode: valueFor('--mode') ?? 'build-and-deploy',
     emptyExistingRepository: args.includes('--empty-existing-repository'),
@@ -93,6 +100,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];
@@ -187,6 +215,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-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';
@@ -25,15 +24,36 @@ function providerDefaultBase(owner) {
   return `https://${owner.toLowerCase()}.github.io`;
 }
 
+function registrationLocation(owner, topology, canonicalBaseUrl) {
+  if (topology === 'provider-default') {
+    if (canonicalBaseUrl != null) {
+      throw new TypeError('--canonical-base-url is valid only with --topology custom-domain');
+    }
+    return { topology: 'PROVIDER_DEFAULT', canonicalBaseUrl: providerDefaultBase(owner) };
+  }
+  if (topology !== 'custom-domain') {
+    throw new TypeError('topology must be provider-default or custom-domain');
+  }
+  if (typeof canonicalBaseUrl !== 'string') {
+    throw new TypeError('--canonical-base-url is required with --topology custom-domain');
+  }
+  const canonical = new URL(canonicalBaseUrl);
+  if (canonical.protocol !== 'https:' || canonical.username || canonical.password
+      || canonical.port || canonical.search || canonical.hash || canonical.pathname !== '/') {
+    throw new TypeError('canonicalBaseUrl must be a credential-free HTTPS origin');
+  }
+  return { topology: 'CUSTOM_DOMAIN', canonicalBaseUrl: canonical.origin };
+}
+
 export async function scaffoldSite({
   owner, repository, target, githubInstallationId, siteOptions, emptyExistingRepository = false,
-  resumeExistingCheckout = false,
+  resumeExistingCheckout = false, topology = 'provider-default', canonicalBaseUrl, actionRef,
   buildMode = 'build-and-deploy', templateOwner = 'rathnasgala',
   templateRepository = 'site-template',
   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,
@@ -41,6 +61,7 @@ export async function scaffoldSite({
 }) {
   const repositoryOwner = segment(owner, 'owner');
   const repositoryName = segment(repository, 'repository');
+  const location = registrationLocation(repositoryOwner, topology, canonicalBaseUrl);
   if (!Number.isSafeInteger(githubInstallationId) || githubInstallationId <= 0) {
     throw new TypeError('githubInstallationId must be a positive integer');
   }
@@ -76,25 +97,22 @@ export async function scaffoldSite({
     if (emptyExistingRepository) await setOrigin({ root, owner: repositoryOwner, repository: repositoryName });
   }
   const configured = await configure(root, siteOptions ?? {});
-  const canonicalBaseUrl = providerDefaultBase(repositoryOwner);
   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: 'PROVIDER_DEFAULT', canonicalBaseUrl
+    topology: location.topology, canonicalBaseUrl: location.canonicalBaseUrl
   });
   await finalize(root, {
     siteId: registration.siteId,
     canonicalBaseUrl: registration.canonicalBaseUrl,
     pathPrefix: registration.pathPrefix,
-    topology: 'provider-default'
+    topology
   });
   await writeWorkflow({
-    root, siteId: registration.siteId, timezone: configured.site.timezone, buildMode
-  });
-  await installSecret({
-    owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken,
-    secretName: 'GALA_SITE_SECRET', secretValue: registration.siteSecret
+    root, siteId: registration.siteId, timezone: configured.site.timezone, buildMode,
+    ...(actionRef == null ? {} : { actionRef })
   });
   await installVariable({
     owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken,
@@ -102,7 +120,8 @@ export async function scaffoldSite({
   });
   const commitSha = await commit(root);
   const pages = buildMode === 'build-and-deploy' ? await provisionPages({
-    owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken, commitSha
+    owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken, commitSha,
+    customDomain: location.topology === 'CUSTOM_DOMAIN' ? new URL(location.canonicalBaseUrl).hostname : null
   }) : null;
   return Object.freeze({
     root, fullName: generated.fullName, siteId: registration.siteId, commitSha, pages

package/src/site-config-registration.js

@@ -6,7 +6,9 @@ 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 (topology !== 'provider-default') throw new TypeError('Only provider-default topology is implemented');
+  if (!['provider-default', 'custom-domain', 'domain-root', 'domain-subpath'].includes(topology)) {
+    throw new TypeError('topology is invalid');
+  }
   const canonical = new URL(canonicalBaseUrl);
   if (canonical.protocol !== 'https:' || canonical.username || canonical.password || canonical.search
       || canonical.hash || canonical.pathname !== '/') {

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 })

package/src/workflow-command.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
-const ACTION_REF = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/.github\/workflows\/[A-Za-z0-9_.-]+\.ya?ml@v[1-9][0-9]*$/;
+const ACTION_REF = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/.github\/workflows\/[A-Za-z0-9_.-]+\.ya?ml@v(?:[1-9][0-9]*|[0-9]+\.[0-9]+\.[0-9]+)$/;
 const BRANCH = /^(?![./])(?!.*\.\.)(?!.*[~^:?*\[\\])[A-Za-z0-9._/-]+(?<![/.])$/;
 
 export function deriveNightlySchedule(siteId) {
@@ -28,7 +28,9 @@ export async function writePublishWorkflow({
   buildMode = 'build-and-deploy'
 }) {
   validateTimezone(timezone);
-  if (!ACTION_REF.test(actionRef)) throw new TypeError('actionRef must pin a reusable workflow to a major version');
+  if (!ACTION_REF.test(actionRef)) {
+    throw new TypeError('actionRef must pin a reusable workflow to a major or immutable semver tag');
+  }
   if (!BRANCH.test(defaultBranch)) throw new TypeError('Invalid default branch');
   if (!['build-only', 'build-and-deploy'].includes(buildMode)) throw new TypeError('Invalid build mode');