@rathnasgala/cli 0.0.1

package/src/scaffold-options.js

@@ -0,0 +1,58 @@
+export const scaffoldOptionNames = Object.freeze([
+  'theme',
+  'layout',
+  'palette',
+  'typography',
+  'spacing',
+  'radius',
+  'density',
+  'motion',
+  'componentStyle'
+]);
+
+const singleValueOptions = Object.freeze({
+  'site-name': 'siteName',
+  author: 'siteAuthor',
+  language: 'defaultLanguage',
+  timezone: 'timezone'
+});
+
+function requireValue(args, index, name) {
+  const value = args[index + 1];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`Missing value for --${name}`);
+  }
+  return value;
+}
+
+export function parseScaffoldOptions(args) {
+  const values = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (!argument.startsWith('--')) continue;
+
+    const name = argument.slice(2);
+    if (name === 'share-target') {
+      const value = requireValue(args, index, name);
+      values.shareTargets = [...(values.shareTargets ?? []), value];
+      index += 1;
+      continue;
+    }
+    if (name === 'social-profile') {
+      const value = requireValue(args, index, name);
+      values.socialProfiles = [...(values.socialProfiles ?? []), value];
+      index += 1;
+      continue;
+    }
+
+    const targetName = singleValueOptions[name] ?? name;
+    if (!scaffoldOptionNames.includes(name) && singleValueOptions[name] == null) continue;
+
+    const value = requireValue(args, index, name);
+    values[targetName] = value;
+    index += 1;
+  }
+
+  return values;
+}

package/src/scaffold-site.js

@@ -0,0 +1,110 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+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';
+import { writeRegisteredSiteConfiguration } from './site-config-registration.js';
+import { writePublishWorkflow } from './workflow-command.js';
+import { commitScaffold } from './scaffold-git.js';
+import {
+  setRepositoryOrigin, verifyEmptyRepository, verifyRepositoryOrigin
+} from './github-empty-repository.js';
+
+function segment(value, field) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_.-]+$/.test(value)) throw new TypeError(`${field} is invalid`);
+  return value;
+}
+
+function providerDefaultBase(owner, repository) {
+  const rootRepository = repository.toLowerCase() === `${owner}.github.io`.toLowerCase();
+  return `https://${owner.toLowerCase()}.github.io${rootRepository ? '/' : `/${repository}/`}`;
+}
+
+export async function scaffoldSite({
+  owner, repository, target, githubInstallationId, siteOptions, emptyExistingRepository = false,
+  resumeExistingCheckout = false,
+  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,
+  installVariable = installRepositoryVariable,
+  provisionPages = provisionGithubPages,
+  commit = commitScaffold, verifyEmpty = verifyEmptyRepository, setOrigin = setRepositoryOrigin,
+  verifyCheckout = verifyRepositoryOrigin
+}) {
+  const repositoryOwner = segment(owner, 'owner');
+  const repositoryName = segment(repository, 'repository');
+  if (!Number.isSafeInteger(githubInstallationId) || githubInstallationId <= 0) {
+    throw new TypeError('githubInstallationId must be a positive integer');
+  }
+  if (target == null || path.resolve(target) === path.parse(path.resolve(target)).root) {
+    throw new TypeError('target must be a non-root local path');
+  }
+  const [github, gala] = await Promise.all([readGithub(), readGala()]);
+  if (emptyExistingRepository && resumeExistingCheckout) {
+    throw new TypeError('emptyExistingRepository and resumeExistingCheckout are mutually exclusive');
+  }
+  let generated;
+  let root;
+  if (resumeExistingCheckout) {
+    root = await verifyCheckout({
+      root: path.resolve(target), owner: repositoryOwner, repository: repositoryName
+    });
+    generated = { fullName: `${repositoryOwner}/${repositoryName}` };
+  } else if (emptyExistingRepository) {
+    await verifyEmpty({ owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken });
+    generated = {
+      fullName: `${repositoryOwner}/${repositoryName}`,
+      cloneUrl: `https://github.com/${templateOwner}/${templateRepository}.git`
+    };
+  } else {
+    generated = await generate({
+      accessToken: github.accessToken, templateOwner, templateRepository,
+      owner: repositoryOwner, repository: repositoryName,
+      description: siteOptions?.siteName ?? ''
+    });
+  }
+  if (!resumeExistingCheckout) {
+    root = await clone({ cloneUrl: generated.cloneUrl, target });
+    if (emptyExistingRepository) await setOrigin({ root, owner: repositoryOwner, repository: repositoryName });
+  }
+  const configured = await configure(root, siteOptions ?? {});
+  const canonicalBaseUrl = providerDefaultBase(repositoryOwner, repositoryName);
+  const idempotencyKey = `scaffold-${createHash('sha256').update(`${repositoryOwner.toLowerCase()}/${repositoryName.toLowerCase()}`).digest('hex')}`;
+  const registration = await register({
+    apiBaseUrl: gala.apiBaseUrl, galaAccessToken: gala.accessToken, idempotencyKey,
+    githubInstallationId, repositoryOwner, repositoryName,
+    topology: 'PROVIDER_DEFAULT', canonicalBaseUrl
+  });
+  await finalize(root, {
+    siteId: registration.siteId,
+    canonicalBaseUrl: registration.canonicalBaseUrl,
+    topology: 'provider-default'
+  });
+  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
+  });
+  await installVariable({
+    owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken,
+    variableName: 'GALA_API_BASE_URL', variableValue: gala.apiBaseUrl
+  });
+  const commitSha = await commit(root);
+  const pages = buildMode === 'build-and-deploy' ? await provisionPages({
+    owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken, commitSha
+  }) : null;
+  return Object.freeze({
+    root, fullName: generated.fullName, siteId: registration.siteId, commitSha, pages
+  });
+}

package/src/site-config-registration.js

@@ -0,0 +1,37 @@
+import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse, stringify } from 'yaml';
+
+export async function writeRegisteredSiteConfiguration(root, { siteId, canonicalBaseUrl, 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');
+  const canonical = new URL(canonicalBaseUrl);
+  if (canonical.protocol !== 'https:' || canonical.username || canonical.password || canonical.search || canonical.hash) {
+    throw new TypeError('canonicalBaseUrl must be credential-free HTTPS');
+  }
+  const target = path.resolve(root, 'site.config.yml');
+  const metadata = await lstat(target);
+  if (!metadata.isFile() || metadata.isSymbolicLink()) throw new TypeError('site.config.yml must be a regular file');
+  const config = parse(await readFile(target, 'utf8'));
+  if (config?.schemaVersion !== 1 || config.site == null || config.hosting == null) {
+    throw new TypeError('Unsupported site configuration schema');
+  }
+  config.site.id = siteId;
+  config.hosting.provider = 'github-pages';
+  config.hosting.topology = topology;
+  config.hosting.canonicalBaseUrl = canonical.href.replace(/\/$/, '');
+  config.hosting.pathPrefix = canonical.pathname === '/' ? '/' : canonical.pathname.replace(/\/$/, '');
+  const temporary = `${target}.gala-register-${process.pid}`;
+  const backup = `${target}.gala-backup-${process.pid}`;
+  try {
+    await writeFile(temporary, stringify(config), { flag: 'wx' });
+    await rename(target, backup);
+    try { await rename(temporary, target); }
+    catch (error) { await rename(backup, target); throw error; }
+    await rm(backup);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+  return config;
+}

package/src/site-registration-client.js

@@ -0,0 +1,87 @@
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const REPOSITORY_PART = /^[A-Za-z0-9_.-]+$/;
+const IDEMPOTENCY_KEY = /^[A-Za-z0-9._:-]{16,128}$/;
+
+function required(value, field, pattern) {
+  if (typeof value !== 'string' || !pattern.test(value)) throw new TypeError(`${field} is invalid`);
+  return value;
+}
+
+function apiUrl(apiBaseUrl) {
+  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', base).href;
+}
+
+export async function registerSite({
+  apiBaseUrl = 'https://api.gala67.com',
+  galaAccessToken,
+  idempotencyKey,
+  githubInstallationId,
+  repositoryOwner,
+  repositoryName,
+  topology,
+  canonicalBaseUrl,
+  fetchImpl = fetch
+}) {
+  if (typeof galaAccessToken !== 'string' || galaAccessToken === '') {
+    throw new Error('Gala authentication is missing; run `gala auth`');
+  }
+  required(idempotencyKey, 'idempotencyKey', IDEMPOTENCY_KEY);
+  required(repositoryOwner, 'repositoryOwner', REPOSITORY_PART);
+  required(repositoryName, 'repositoryName', REPOSITORY_PART);
+  if (!Number.isSafeInteger(githubInstallationId) || githubInstallationId <= 0) {
+    throw new TypeError('githubInstallationId must be a positive integer');
+  }
+  if (!['PROVIDER_DEFAULT', 'CUSTOM_DOMAIN'].includes(topology)) {
+    throw new TypeError('topology is invalid');
+  }
+  const response = await fetchImpl(apiUrl(apiBaseUrl), {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${galaAccessToken}`,
+      'content-type': 'application/json',
+      'idempotency-key': idempotencyKey
+    },
+    body: JSON.stringify({
+      githubInstallationId,
+      repositoryOwner,
+      repositoryName,
+      topology,
+      canonicalBaseUrl
+    })
+  });
+  if (response.status === 401) {
+    throw new Error('Gala authentication expired; run `gala auth` again');
+  }
+  if (response.status === 404) {
+    throw new Error(`GitHub App installation does not cover ${repositoryOwner}/${repositoryName}`);
+  }
+  if (response.status === 409) {
+    throw new Error('Site registration conflicts with existing protected state; use the recovery command');
+  }
+  if (response.status !== 201) throw new Error(`Gala site registration failed with HTTP ${response.status}`);
+  const payload = await response.json();
+  if (!ULID.test(payload?.siteId) || typeof payload.siteSecret !== 'string' || payload.siteSecret === '') {
+    throw new TypeError('Gala site registration response is invalid');
+  }
+  const canonical = new URL(payload.canonicalBaseUrl);
+  if (canonical.protocol !== 'https:' || canonical.username || canonical.password
+      || canonical.search || canonical.hash) {
+    throw new TypeError('Gala site registration returned an invalid canonicalBaseUrl');
+  }
+  const location = response.headers?.get?.('location');
+  if (location !== `/v1/sites/${payload.siteId}`) {
+    throw new TypeError('Gala site registration returned an invalid Location header');
+  }
+  return Object.freeze({
+    siteId: payload.siteId,
+    siteSecret: payload.siteSecret,
+    canonicalBaseUrl: canonical.href
+  });
+}

package/src/theme-package.js

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import * as tar from 'tar';
+
+const MAX_COMPRESSED_BYTES = 10 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 10 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+const MAX_ENTRIES = 2_048;
+const EXACT_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+function registryUrl(name, version) {
+  if (name !== '@rathnasgala/theme' || !EXACT_VERSION.test(version)) {
+    throw new TypeError('theme package name and exact version are required');
+  }
+  return `https://registry.npmjs.org/${encodeURIComponent(name)}/${encodeURIComponent(version)}`;
+}
+
+async function boundedBody(response) {
+  const length = Number(response.headers.get('content-length'));
+  if (Number.isFinite(length) && length > MAX_COMPRESSED_BYTES) throw new Error('Theme archive exceeds compressed-size limit');
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > MAX_COMPRESSED_BYTES) {
+      await reader.cancel();
+      throw new Error('Theme archive exceeds compressed-size limit');
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks, size);
+}
+
+function verifyIntegrity(bytes, integrity) {
+  const match = /^(sha512|sha384|sha256)-([A-Za-z0-9+/=]+)$/.exec(integrity ?? '');
+  if (match == null) throw new Error('Theme package has no supported registry integrity value');
+  const actual = createHash(match[1]).update(bytes).digest('base64');
+  if (actual !== match[2]) throw new Error('Theme package integrity verification failed');
+}
+
+async function validateArchive(archive) {
+  let entries = 0;
+  let total = 0;
+  await new Promise((resolve, reject) => {
+    const inspector = tar.t({
+      strict: true,
+      onReadEntry(entry) {
+        entries += 1;
+        total += entry.size;
+        const normalized = entry.path.replaceAll('\\', '/');
+        let error;
+        if (normalized !== 'package/' && !normalized.startsWith('package/')) error = 'Theme archive entry is outside package/';
+        else if (entry.type === 'SymbolicLink' || entry.type === 'Link') error = 'Theme archive links are forbidden';
+        else if (path.posix.isAbsolute(normalized) || normalized.split('/').includes('..')) error = 'Theme archive path is unsafe';
+        else if (entries > MAX_ENTRIES || entry.size > MAX_ENTRY_BYTES || total > MAX_TOTAL_BYTES) {
+          error = 'Theme archive exceeds extraction limits';
+        }
+        entry.resume();
+        if (error) inspector.abort(new Error(error));
+      }
+    });
+    inspector.once('error', reject);
+    inspector.once('close', resolve);
+    inspector.end(archive);
+  });
+}
+
+export async function fetchVerifiedThemePackage({ name, version, fetchImpl = fetch }) {
+  const metadataResponse = await fetchImpl(registryUrl(name, version), { headers: { Accept: 'application/json' } });
+  if (!metadataResponse.ok) throw new Error(`Theme metadata request failed with HTTP ${metadataResponse.status}`);
+  const metadata = await metadataResponse.json();
+  if (metadata.name !== name || metadata.version !== version || typeof metadata.dist?.tarball !== 'string') {
+    throw new Error('Theme registry metadata does not match the requested package');
+  }
+  if (!metadata.dist.integrity) throw new Error('Theme package registry metadata has no integrity value');
+  const archiveResponse = await fetchImpl(metadata.dist.tarball);
+  if (!archiveResponse.ok || archiveResponse.body == null) {
+    throw new Error(`Theme archive request failed with HTTP ${archiveResponse.status}`);
+  }
+  const archive = await boundedBody(archiveResponse);
+  verifyIntegrity(archive, metadata.dist.integrity);
+  await validateArchive(archive);
+
+  const staging = await mkdtemp(path.join(tmpdir(), 'gala-theme-'));
+  try {
+    await mkdir(staging, { recursive: true });
+    await new Promise((resolve, reject) => {
+      const extractor = tar.x({
+        cwd: staging,
+        strip: 1,
+        preservePaths: false,
+        strict: true
+      });
+      extractor.once('error', reject);
+      extractor.once('close', resolve);
+      extractor.end(archive);
+    });
+    const payloadRoot = path.join(staging, 'payload');
+    const manifest = JSON.parse(await readFile(path.join(payloadRoot, '.gala', 'managed-files.json'), 'utf8'));
+    if (manifest.themePackage?.name !== name || manifest.themePackage?.version !== version) {
+      throw new Error('Extracted theme manifest does not match registry identity');
+    }
+    for (const [relative, expected] of Object.entries(manifest.files ?? {})) {
+      const sourceRelative = manifest.artifactSources?.[relative] ?? relative;
+      const source = path.resolve(payloadRoot, sourceRelative);
+      const target = path.resolve(payloadRoot, relative);
+      if (path.relative(payloadRoot, source).startsWith('..') || path.relative(payloadRoot, target).startsWith('..')) {
+        throw new Error('Theme manifest path is unsafe');
+      }
+      const actual = createHash('sha256').update(await readFile(source)).digest('hex');
+      if (actual !== expected) throw new Error(`Theme file hash mismatch: ${relative}`);
+      if (source !== target) {
+        await mkdir(path.dirname(target), { recursive: true });
+        await copyFile(source, target);
+      }
+    }
+    return { staging: payloadRoot, cleanupRoot: staging, manifest };
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}

package/src/upgrade-command.js

@@ -0,0 +1,73 @@
+import { lstat, readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { parse, stringify } from 'yaml';
+
+import { repairFramework } from './doctor-command.js';
+import { fetchVerifiedThemePackage } from './theme-package.js';
+
+const NAME = '@rathnasgala/theme';
+const ACTION_WORKFLOW = '.github/workflows/publish.yml';
+const ACTION_REFERENCE = /rathnasgala\/publish\/\.github\/workflows\/publish\.yml@v([1-9][0-9]*)/g;
+const ACTION_TAG = /^v([1-9][0-9]*)(?:\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?)?$/;
+
+async function registryMetadata(fetchImpl) {
+  const response = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(NAME)}`, {
+    headers: { Accept: 'application/json' }
+  });
+  if (!response.ok) throw new Error(`Theme registry request failed with HTTP ${response.status}`);
+  return response.json();
+}
+
+export async function inspectActionUpgrade({ root, fetchImpl = fetch }) {
+  const workflowPath = path.resolve(root, ACTION_WORKFLOW);
+  const metadata = await lstat(workflowPath);
+  if (!metadata.isFile() || metadata.isSymbolicLink()) {
+    throw new TypeError('Publish workflow must be a regular file');
+  }
+  const workflow = await readFile(workflowPath, 'utf8');
+  const majors = [...workflow.matchAll(ACTION_REFERENCE)].map((match) => Number(match[1]));
+  if (majors.length === 0 || new Set(majors).size !== 1) {
+    throw new Error('Publish workflow must reference exactly one Gala action major');
+  }
+  const response = await fetchImpl('https://api.github.com/repos/rathnasgala/publish/tags?per_page=100', {
+    headers: { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2026-03-10' }
+  });
+  if (!response.ok) throw new Error(`Action release lookup failed with HTTP ${response.status}`);
+  const tags = await response.json();
+  if (!Array.isArray(tags)) throw new TypeError('Action release response must be an array');
+  const releasedMajors = tags.map((tag) => ACTION_TAG.exec(tag?.name)?.[1])
+    .filter((major) => major != null).map(Number);
+  const currentMajor = majors[0];
+  const latestMajor = releasedMajors.length === 0 ? currentMajor : Math.max(...releasedMajors);
+  return Object.freeze({ currentMajor, latestMajor, newerAvailable: latestMajor > currentMajor });
+}
+
+export async function upgradeTheme({ root, channel, confirm, fetchImpl = fetch }) {
+  const configPath = path.resolve(root, 'site.config.yml');
+  const config = parse(await readFile(configPath, 'utf8'));
+  const installed = config?.framework?.themePackage?.version;
+  const [metadata, action] = await Promise.all([
+    registryMetadata(fetchImpl), inspectActionUpgrade({ root, fetchImpl })
+  ]);
+  const selectedChannel = channel ?? (metadata['dist-tags']?.next === installed ? 'next' : 'latest');
+  if (!['latest', 'next'].includes(selectedChannel)) throw new TypeError('theme channel must be latest or next');
+  const version = metadata['dist-tags']?.[selectedChannel];
+  if (typeof version !== 'string') throw new Error(`Theme channel ${selectedChannel} has no resolved version`);
+  if (version === installed) return { changed: false, channel: selectedChannel, version, repaired: [], action };
+  if (typeof confirm !== 'function' || !await confirm({ name: NAME, installed, channel: selectedChannel, version })) {
+    return { changed: false, cancelled: true, channel: selectedChannel, version, repaired: [], action };
+  }
+  const downloaded = await fetchVerifiedThemePackage({ name: NAME, version, fetchImpl });
+  try {
+    if (!downloaded.manifest.themePackage.availableDesignThemes?.includes(config?.design?.theme)) {
+      throw new Error(`Visual theme ${String(config?.design?.theme)} is unavailable in ${NAME}@${version}`);
+    }
+    config.framework.themePackage = { name: NAME, version };
+    const repaired = await repairFramework(root, downloaded.staging, {
+      siteConfiguration: stringify(config)
+    });
+    return { changed: true, channel: selectedChannel, version, repaired, action };
+  } finally {
+    await rm(downloaded.cleanupRoot, { recursive: true, force: true });
+  }
+}

package/src/validate-command.js

@@ -0,0 +1,5 @@
+export {
+  BUILD_MANIFEST_PATH,
+  regenerateBuildManifest,
+  validateContent
+} from '@rathnasgala/content-validation';

package/src/workflow-command.js

@@ -0,0 +1,85 @@
+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 BRANCH = /^(?![./])(?!.*\.\.)(?!.*[~^:?*\[\\])[A-Za-z0-9._/-]+(?<![/.])$/;
+
+export function deriveNightlySchedule(siteId) {
+  if (typeof siteId !== 'string' || siteId.trim() === '') throw new TypeError('siteId is required');
+  const digest = createHash('sha256').update(siteId, 'utf8').digest();
+  return { minute: digest.readUInt16BE(0) % 60, hour: digest.readUInt16BE(2) % 24 };
+}
+
+function validateTimezone(timezone) {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: timezone }).format(0);
+  } catch {
+    throw new TypeError(`Invalid IANA timezone: ${timezone}`);
+  }
+}
+
+export async function writePublishWorkflow({
+  root,
+  siteId,
+  timezone,
+  actionRef = 'rathnasgala/publish/.github/workflows/publish.yml@v1',
+  defaultBranch = 'main',
+  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 (!BRANCH.test(defaultBranch)) throw new TypeError('Invalid default branch');
+  if (!['build-only', 'build-and-deploy'].includes(buildMode)) throw new TypeError('Invalid build mode');
+
+  const resolvedRoot = path.resolve(root);
+  const templatePath = path.join(resolvedRoot, '.gala', 'publish.yml.template');
+  const target = path.join(resolvedRoot, '.github', 'workflows', 'publish.yml');
+  const templateMetadata = await lstat(templatePath);
+  if (!templateMetadata.isFile() || templateMetadata.isSymbolicLink()) {
+    throw new TypeError('Workflow template must be a regular file');
+  }
+  try {
+    const targetMetadata = await lstat(target);
+    if (targetMetadata.isSymbolicLink() || !targetMetadata.isFile()) {
+      throw new TypeError('Workflow target must be a regular file');
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
+  const { minute, hour } = deriveNightlySchedule(siteId);
+  const workflow = (await readFile(templatePath, 'utf8'))
+    .replaceAll('__DEFAULT_BRANCH__', defaultBranch)
+    .replaceAll('__CRON__', `${minute} ${hour} * * *`)
+    .replaceAll('__TIMEZONE__', timezone)
+    .replaceAll('__SITE_ID__', siteId)
+    .replaceAll('__ACTION_REF__', actionRef)
+    .replaceAll('__BUILD_MODE__', buildMode);
+  if (/__[A-Z_]+__/.test(workflow)) throw new TypeError('Workflow template contains unresolved placeholders');
+
+  await mkdir(path.dirname(target), { recursive: true });
+  const temporary = `${target}.gala-workflow-${process.pid}`;
+  const backup = `${target}.gala-backup-${process.pid}`;
+  let backedUp = false;
+  try {
+    await writeFile(temporary, workflow, { flag: 'wx' });
+    try {
+      await rename(target, backup);
+      backedUp = true;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    try {
+      await rename(temporary, target);
+    } catch (error) {
+      if (backedUp) await rename(backup, target);
+      throw error;
+    }
+    if (backedUp) await rm(backup);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+  return { target, minute, hour };
+}