@rathnasgala/cli 0.0.22 → 1.1.4

package/src/commands/prism.js

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

package/src/commands/publish.js

@@ -0,0 +1,57 @@
+import path from 'node:path';
+
+import { checkContent } from '../content.js';
+import { createGit } from '../git.js';
+import { githubCredential } from '../auth/github.js';
+import { readPublication } from '../publication.js';
+
+/**
+ * Validates, records the writer's work, and sends it to GitHub.
+ *
+ * v0 only sent — the writer had to remember to record their changes first, and a run that appeared
+ * to succeed could ship nothing at all. It also used the machine's git credential rather than the
+ * one the CLI holds, which fails for anyone whose accounts differ.
+ *
+ * The order below is the whole of the difficulty. Every successful publish adds a deployment record
+ * to the branch from the workflow, so the checkout is behind by one before the writer has touched
+ * anything — catching up is the normal condition, not a race fix. It has to happen *before*
+ * validation, because validation assigns a content id to any post missing one and the workflow
+ * assigns ids remotely as well; the other order has both sides edit the same file with different
+ * ids, which git can only report as a conflict.
+ *
+ * Publishing itself happens on GitHub: the workflow in the repository builds and deploys. This
+ * command's job ends when the work is on the branch.
+ */
+export async function publish({ terminal, options, cwd = process.cwd(), regenerate }) {
+  const root = path.resolve(options.value('root') ?? cwd);
+  const today = options.value('today');
+
+  const github = await githubCredential({ terminal });
+  const git = createGit({ root, token: github.accessToken });
+
+  terminal.step('Catching up with GitHub');
+  await git.takeRemote();
+
+  if (!options.on('skip-checks')) {
+    terminal.step('Checking content');
+    await checkContent({ terminal, root, today, ...(regenerate == null ? {} : { regenerate }) });
+    terminal.done('Content is valid');
+  }
+
+  const recorded = await git.record('Publish', ['.']);
+  if (!recorded) {
+    terminal.done('Nothing new to send');
+    return;
+  }
+  terminal.done('Changes recorded');
+
+  terminal.step('Sending to GitHub');
+  await git.send();
+
+  terminal.done('Sent');
+
+  const publication = await readPublication(root);
+  if (publication != null) terminal.result(publication.url);
+  terminal.blank();
+  terminal.note('GitHub is building it now; give it a minute or two.');
+}

package/src/commands/upgrade.js

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

package/src/commands-manifest.js

@@ -0,0 +1,80 @@
+import { auth } from './commands/auth.js';
+import { doctor } from './commands/doctor.js';
+import { domain } from './commands/domain.js';
+import { init } from './commands/init.js';
+import { createPost } from './commands/new.js';
+import { preview } from './commands/preview.js';
+import { publish } from './commands/publish.js';
+import { prism } from './commands/prism.js';
+import { upgrade } from './commands/upgrade.js';
+
+/**
+ * Commands in the order a writer meets them.
+ *
+ * v0 had fifteen, and the extra nine were the ones nobody could keep working: a `validate` a hook
+ * ran behind the writer's back, a `workflow` writer for a file the server owns, a
+ * `record-deployment` nothing called, a `configure` duplicating options another command took.
+ * Each was a surface to keep correct and a way to be wrong.
+ *
+ * This lives apart from the dispatcher so the README can be checked against it. v0's README
+ * outlived its commands by weeks — it taught a command that never existed — because nothing tied
+ * the two together.
+ *
+ * Each entry carries its own options. Nothing is parsed globally, so an option cannot mean two
+ * things in two places, which is how one ended up read twice with different defaults.
+ */
+export const COMMANDS = {
+  auth: {
+    summary: 'Sign in to Gala and GitHub',
+    flags: ['api-base-url'],
+    run: auth
+  },
+  init: {
+    summary: 'Create a publication in an empty directory',
+    usage: 'gala init [directory] [--name my-notes] [--domain blog.example.com]',
+    flags: ['name', 'domain', 'api-base-url'],
+    run: init
+  },
+  domain: {
+    summary: 'Inspect or change this publication’s custom domain',
+    usage: 'gala domain [status|set <hostname>|check|cancel|remove] [--root path]',
+    flags: ['root', 'api-base-url'],
+    run: domain
+  },
+  new: {
+    summary: 'Start a post',
+    usage: 'gala new "A durable idea" [--language en]',
+    flags: ['root', 'language', 'today'],
+    run: createPost
+  },
+  preview: {
+    summary: 'Build and serve the publication locally',
+    flags: ['root', 'today'],
+    run: preview
+  },
+  publish: {
+    summary: 'Check, record and send your work to GitHub',
+    flags: ['root', 'today'],
+    switches: ['skip-checks'],
+    run: publish
+  },
+  prism: {
+    summary: 'Manage author-approved Prism configurations',
+    usage: 'gala prism <status|mode|link-policy|list|create|edit|generate|submit|approve|reject|revoke> [arguments]',
+    flags: ['root', 'api-base-url', 'language', 'depth', 'intent', 'modality', 'file', 'reason'],
+    switches: ['yes'],
+    run: prism
+  },
+  upgrade: {
+    summary: 'Inspect and apply a verified managed-theme update',
+    usage: 'gala upgrade [--channel latest|next] [--yes]',
+    flags: ['root', 'channel'],
+    switches: ['yes'],
+    run: upgrade
+  },
+  doctor: {
+    summary: 'Check a publication and say what is wrong',
+    flags: ['root', 'api-base-url'],
+    run: doctor
+  }
+};