@rathnasgala/cli 0.0.1

package/src/index.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+import { parseScaffoldOptions } from './scaffold-options.js';
+import { regenerateBuildManifest } from './validate-command.js';
+import { createPost } from './new-command.js';
+import {
+  diagnoseFramework,
+  diagnosePublicationState,
+  repairFramework
+} from './doctor-command.js';
+import { configureSite } from './configure-site.js';
+import { previewSite } from './preview-command.js';
+import { writePublishWorkflow } from './workflow-command.js';
+import { publishSite } from './publish-command.js';
+import { installPrePushHook } from './hook-command.js';
+import { reportRepositoryLimitWarnings } from './repository-limits.js';
+import { recordDeployment } from './record-deployment-command.js';
+import { authenticateGala } from './auth-command.js';
+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';
+
+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]';
+
+if (command === 'help' || args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(`${usage}\n`);
+  process.exit(0);
+}
+
+const recognizedCommands = new Set([
+  'auth', 'configure', 'validate', 'new', 'doctor', 'preview',
+  'workflow', 'publish', 'record-deployment', 'hook', 'upgrade'
+]);
+function commandRoot() {
+  const rootIndex = args.indexOf('--root');
+  if (rootIndex !== -1) return args[rootIndex + 1];
+  if (command === 'doctor' || command === 'validate') {
+    return args.find((argument, index) =>
+      !argument.startsWith('--')
+      && !['--today', '--source'].includes(args[index - 1])
+    ) ?? process.cwd();
+  }
+  return process.cwd();
+}
+if (recognizedCommands.has(command)) {
+  await reportRepositoryLimitWarnings(commandRoot());
+}
+
+if (command === 'auth') {
+  if (args[0] === 'github') {
+    const result = await authenticateGithub({
+      showScopeWarning: ({ explanation }) => process.stdout.write(`GitHub authorization: ${explanation}\n`),
+      showInstructions: ({ verificationUri, userCode }) => {
+        process.stdout.write(`Open ${verificationUri}\nEnter code: ${userCode}\n`);
+      }
+    });
+    process.stdout.write(`GitHub authentication stored securely with scopes: ${result.scopes.join(', ')}.\n`);
+  } else {
+    const apiIndex = args.indexOf('--api-base-url');
+    const apiBaseUrl = apiIndex === -1 ? 'https://api.gala67.com' : args[apiIndex + 1];
+    const result = await authenticateGala({
+      apiBaseUrl,
+      showInstructions: ({ verificationUri, userCode }) => {
+        process.stdout.write(`Open ${verificationUri}\nEnter code: ${userCode}\n`);
+      }
+    });
+    process.stdout.write(`Gala authentication stored securely until ${result.expiresAt.toISOString()}.\n`);
+  }
+} else if (command === 'scaffold') {
+  const valueFor = (name) => {
+    const index = args.indexOf(name);
+    return index === -1 ? undefined : args[index + 1];
+  };
+  const installationId = Number(valueFor('--installation-id'));
+  const result = await scaffoldSite({
+    owner: valueFor('--owner'),
+    repository: valueFor('--repository'),
+    target: valueFor('--target'),
+    githubInstallationId: installationId,
+    siteOptions: parseScaffoldOptions(args),
+    buildMode: valueFor('--mode') ?? 'build-and-deploy',
+    emptyExistingRepository: args.includes('--empty-existing-repository'),
+    resumeExistingCheckout: args.includes('--resume')
+  });
+  await reportRepositoryLimitWarnings(result.root);
+  process.stdout.write(`Scaffolded ${result.fullName} as Gala site ${result.siteId} in ${result.root}.\n`);
+} else if (command === 'configure') {
+  const rootIndex = args.indexOf('--root');
+  const root = rootIndex === -1 ? process.cwd() : args[rootIndex + 1];
+  const options = parseScaffoldOptions(args);
+  const config = await configureSite(root, options);
+  process.stdout.write(`${JSON.stringify(config.design, null, 2)}\n`);
+} else if (command === 'validate') {
+  const todayIndex = args.indexOf('--today');
+  const today = todayIndex === -1 ? undefined : args[todayIndex + 1];
+  const root = args.find((argument) => !argument.startsWith('--') && argument !== today) ?? process.cwd();
+  const { results } = await regenerateBuildManifest({ root, today });
+  const failures = results.filter(({ errors }) => errors.length > 0);
+
+  for (const result of failures) {
+    for (const error of result.errors) process.stderr.write(`${result.file}: ${error}\n`);
+  }
+  for (const result of results) {
+    for (const warning of result.warnings) process.stderr.write(`${result.file}: warning: ${warning}\n`);
+  }
+  process.stdout.write(`Validated ${results.length} post variant(s); ${failures.length} failed.\n`);
+  if (failures.length > 0) process.exitCode = 1;
+} else if (command === 'new') {
+  const valueFor = (name) => {
+    const index = args.indexOf(name);
+    return index === -1 ? undefined : args[index + 1];
+  };
+  const title = valueFor('--title');
+  const language = valueFor('--language');
+  const today = valueFor('--today');
+  const root = valueFor('--root') ?? process.cwd();
+  const result = await createPost({ root, title, language, today });
+  process.stdout.write(`Created ${result.postPath}\n`);
+} else if (command === 'doctor') {
+  const positional = args.filter((argument, index) =>
+    !argument.startsWith('--') && args[index - 1] !== '--source'
+  );
+  const root = positional[0] ?? process.cwd();
+  if (args.includes('--fix')) {
+    const sourceIndex = args.indexOf('--source');
+    const sourceRoot = sourceIndex === -1 ? undefined : args[sourceIndex + 1];
+    if (!sourceRoot) throw new Error('doctor --fix requires --source <trusted-template-root>');
+    const repaired = await repairFramework(root, sourceRoot);
+    process.stdout.write(`Repaired ${repaired.length} managed file(s).\n`);
+  }
+  const findings = await diagnoseFramework(root);
+  const drift = findings.filter(({ status }) => status !== 'intact');
+  findings.forEach(({ path: file, status }) => process.stdout.write(`${status}\t${file}\n`));
+  const publicationState = await diagnosePublicationState(root);
+  process.stdout.write(`${publicationState.status}\t${publicationState.path}\n`);
+  if (publicationState.status === 'invalid') process.exitCode = 1;
+  if (drift.length > 0) process.exitCode = 1;
+} else if (command === 'preview') {
+  const valueFor = (name) => {
+    const index = args.indexOf(name);
+    return index === -1 ? undefined : args[index + 1];
+  };
+  await previewSite({
+    root: valueFor('--root') ?? process.cwd(),
+    today: valueFor('--today')
+  });
+} else if (command === 'workflow') {
+  const valueFor = (name) => {
+    const index = args.indexOf(name);
+    return index === -1 ? undefined : args[index + 1];
+  };
+  const result = await writePublishWorkflow({
+    root: valueFor('--root') ?? process.cwd(),
+    siteId: valueFor('--site-id'),
+    timezone: valueFor('--timezone'),
+    actionRef: valueFor('--action-ref'),
+    defaultBranch: valueFor('--default-branch') ?? 'main',
+    buildMode: valueFor('--mode') ?? 'build-and-deploy'
+  });
+  process.stdout.write(`Wrote ${result.target} (${result.minute} ${result.hour} * * *)\n`);
+} else if (command === 'publish') {
+  const valueFor = (name) => {
+    const index = args.indexOf(name);
+    return index === -1 ? undefined : args[index + 1];
+  };
+  await publishSite({
+    root: valueFor('--root') ?? process.cwd(),
+    today: valueFor('--today'),
+    force: args.includes('--force')
+  });
+} else if (command === 'record-deployment') {
+  const valueFor = (name) => {
+    const index = args.indexOf(name);
+    return index === -1 ? undefined : args[index + 1];
+  };
+  const root = valueFor('--root') ?? process.cwd();
+  const result = await recordDeployment({
+    root,
+    deployedOn: valueFor('--today'),
+    deployedCommitSha: valueFor('--commit-sha')
+  });
+  process.stdout.write(
+    `${result.pushed ? 'Pushed' : 'No change for'} successful deployment `
+    + `of ${result.state.posts.length} article(s).\n`
+    + `Recorded state SHA: ${result.recordedStateSha}\n`
+  );
+} else if (command === 'upgrade') {
+  const valueFor = (name) => {
+    const index = args.indexOf(name);
+    return index === -1 ? undefined : args[index + 1];
+  };
+  const terminalConfirm = async ({ installed, version, channel }) => {
+    if (args.includes('--yes')) return true;
+    const terminal = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      const answer = await terminal.question(`Upgrade theme ${installed} -> ${version} (${channel})? [y/N] `);
+      return /^(?:y|yes)$/i.test(answer.trim());
+    } finally { terminal.close(); }
+  };
+  const result = await upgradeTheme({
+    root: valueFor('--root') ?? process.cwd(),
+    channel: valueFor('--channel'),
+    confirm: terminalConfirm
+  });
+  process.stdout.write(result.cancelled ? 'Theme upgrade cancelled.\n'
+    : result.changed ? `Upgraded theme to ${result.version}.\n`
+      : `Theme ${result.version} is already installed.\n`);
+  process.stdout.write(
+    `Action major v${result.action.currentMajor}; `
+    + (result.action.newerAvailable
+      ? `v${result.action.latestMajor} is available.\n`
+      : 'no newer major is available.\n')
+  );
+} else if (command === 'hook' && args[0] === 'install') {
+  const rootIndex = args.indexOf('--root');
+  const root = rootIndex === -1 ? process.cwd() : args[rootIndex + 1];
+  const result = await installPrePushHook(root);
+  process.stdout.write(`${result.installed ? 'Installed' : 'Already installed'} ${result.target}\n`);
+} else {
+  process.stderr.write(`${usage}\n`);
+  process.exitCode = 1;
+}

package/src/new-command.js

@@ -0,0 +1,54 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  createPostMetadata,
+  isContentId,
+  parseFrontmatter,
+  slugifyTitle
+} from '@rathnasgala/content-validation';
+import { stringify } from 'yaml';
+import { repositoryEvaluationDate } from './evaluation-date.js';
+
+export async function createPost({ root, title, language, today, now = Date.now }) {
+  const siteRoot = path.resolve(root);
+  const creationTimestamp = now();
+  const publishAfterDate = today ?? await repositoryEvaluationDate({
+    root: siteRoot,
+    now: () => creationTimestamp
+  });
+  const metadata = createPostMetadata({
+    title,
+    language,
+    today: publishAfterDate,
+    timestamp: creationTimestamp
+  });
+  const postDirectory = path.join(siteRoot, 'content', 'posts', slugifyTitle(title));
+  const mediaDirectory = path.join(postDirectory, 'media');
+  const postPath = path.join(postDirectory, `index.${metadata.language}.md`);
+
+  await mkdir(postDirectory, { recursive: true });
+  const variants = (await readdir(postDirectory, { withFileTypes: true }))
+    .filter((entry) => entry.isFile() && /^index\.[^.]+\.md$/.test(entry.name));
+  const existingIds = new Set();
+  for (const variant of variants) {
+    const variantPath = path.join(postDirectory, variant.name);
+    const parsed = parseFrontmatter(await readFile(variantPath, 'utf8'));
+    if (parsed.errors.length > 0) {
+      throw new Error(`Existing variant has invalid frontmatter: ${variantPath}`);
+    }
+    if (!isContentId(parsed.data.id)) {
+      throw new Error(`Existing variant is missing a valid article id: ${variantPath}`);
+    }
+    existingIds.add(parsed.data.id);
+  }
+  if (existingIds.size > 1) {
+    throw new Error(`Existing variants have conflicting article ids: ${postDirectory}`);
+  }
+  if (existingIds.size === 1) metadata.id = existingIds.values().next().value;
+
+  await mkdir(mediaDirectory, { recursive: true });
+  const source = `---\n${stringify(metadata).trimEnd()}\n---\n\n# ${title}\n`;
+  await writeFile(postPath, source, { encoding: 'utf8', flag: 'wx' });
+  return { metadata, postPath, mediaDirectory };
+}

package/src/preview-command.js

@@ -0,0 +1,60 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+import { regenerateBuildManifest } from './validate-command.js';
+
+const BUILD_WARNING_DELAY_MS = (5 * 60 * 1000) + 1;
+const INITIAL_BUILD_COMPLETE = /\bWrote \d+ files?\b/;
+
+export async function previewSite({
+  root,
+  today,
+  spawnProcess = spawn,
+  schedule = setTimeout,
+  cancel = clearTimeout,
+  output = process.stdout,
+  warningOutput = process.stderr
+}) {
+  const siteRoot = path.resolve(root);
+  const { results: validation } = await regenerateBuildManifest({ root: siteRoot, today });
+  const failures = validation.filter(({ errors }) => errors.length > 0);
+  if (failures.length > 0) {
+    throw new Error(`Preview refused: ${failures.length} post variant(s) failed validation`);
+  }
+
+  const cli = path.join(siteRoot, 'node_modules', '@11ty', 'eleventy', 'cmd.cjs');
+  const child = spawnProcess(process.execPath, [cli, '--serve', '--watch'], {
+    cwd: siteRoot,
+    env: { ...process.env, GALA_EVALUATION_DATE: today },
+    shell: false,
+    stdio: ['inherit', 'pipe', 'pipe']
+  });
+
+  return new Promise((resolve, reject) => {
+    let initialOutput = '';
+    let warningTimer = schedule(() => {
+      warningOutput.write('warning\tbuild-duration-5m\n');
+      warningTimer = undefined;
+    }, BUILD_WARNING_DELAY_MS);
+    const stopTimer = () => {
+      if (warningTimer !== undefined) cancel(warningTimer);
+      warningTimer = undefined;
+    };
+    child.stdout?.on('data', (chunk) => {
+      output.write(chunk);
+      initialOutput = `${initialOutput}${chunk}`.slice(-256);
+      if (INITIAL_BUILD_COMPLETE.test(initialOutput)) stopTimer();
+    });
+    child.stderr?.on('data', (chunk) => warningOutput.write(chunk));
+    child.once('error', (error) => {
+      stopTimer();
+      reject(error);
+    });
+    child.once('exit', (code, signal) => {
+      stopTimer();
+      if (signal) reject(new Error(`Preview terminated by signal ${signal}`));
+      else if (code !== 0) reject(new Error(`Preview exited with code ${code}`));
+      else resolve();
+    });
+  });
+}

package/src/publication-state.js

@@ -0,0 +1,7 @@
+import {
+  PUBLICATION_STATE_PATH,
+  readPublicationState,
+  recordSuccessfulDeployment
+} from '@rathnasgala/content-validation';
+
+export { PUBLICATION_STATE_PATH, readPublicationState, recordSuccessfulDeployment };

package/src/publish-command.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { regenerateBuildManifest } from './validate-command.js';
+
+export async function publishSite({
+  root,
+  today,
+  force = false,
+  spawnProcess = spawn,
+  warn = (message) => process.stderr.write(`${message}\n`)
+}) {
+  const siteRoot = path.resolve(root);
+  if (!force) {
+    const { results } = await regenerateBuildManifest({ root: siteRoot, today });
+    const failures = results.filter(({ errors }) => errors.length > 0);
+    if (failures.length > 0) {
+      throw new Error(`Publish refused: ${failures.length} post variant(s) failed validation`);
+    }
+    for (const result of results) {
+      for (const warning of result.warnings) warn(`${result.file}: warning: ${warning}`);
+    }
+  }
+
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['-C', siteRoot, 'push'], {
+      cwd: siteRoot,
+      shell: false,
+      stdio: 'inherit'
+    });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) reject(new Error(`Publish terminated by signal ${signal}`));
+      else if (code !== 0) reject(new Error(`Git push exited with code ${code}`));
+      else resolve();
+    });
+  });
+}

package/src/record-deployment-command.js

@@ -0,0 +1,147 @@
+import { readFile } from 'node:fs/promises';
+import { lstat } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { parseFrontmatter } from '@rathnasgala/content-validation';
+
+import { repositoryEvaluationDate } from './evaluation-date.js';
+import { recordSuccessfulDeployment } from './publication-state.js';
+import { BUILD_MANIFEST_PATH } from './validate-command.js';
+
+function runGit(root, args, spawnProcess) {
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['-C', root, ...args], {
+      cwd: root,
+      shell: false,
+      stdio: 'inherit'
+    });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) reject(new Error(`Git terminated by signal ${signal}`));
+      else resolve(code);
+    });
+  });
+}
+
+function readHead(root, spawnProcess) {
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['-C', root, 'rev-parse', '--verify', 'HEAD'], {
+      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 terminated by signal ${signal}`));
+      else if (code !== 0) reject(new Error(`Git rev-parse exited with code ${code}`));
+      else {
+        const sha = output.trim();
+        if (!/^[0-9a-f]{40}$/.test(sha)) reject(new Error('Git returned an invalid HEAD SHA'));
+        else resolve(sha);
+      }
+    });
+  });
+}
+
+async function assignedContentPaths(root, manifest) {
+  const assigned = manifest.assignedContentIds ?? [];
+  if (!Array.isArray(assigned)) throw new TypeError('assignedContentIds must be a list');
+  const sources = new Set();
+  for (const item of assigned) {
+    if (item == null
+        || typeof item.source !== 'string'
+        || !/^content\/posts\/[a-z0-9]+(?:-[a-z0-9]+)*\/index\.[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*\.md$/.test(item.source)
+        || typeof item.id !== 'string'
+        || !/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/.test(item.id)
+        || typeof item.fileHash !== 'string'
+        || !/^[a-f0-9]{64}$/.test(item.fileHash)
+        || sources.has(item.source)) {
+      throw new TypeError('assignedContentIds contains an invalid entry');
+    }
+    const file = path.resolve(root, item.source);
+    const metadata = await lstat(file);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) {
+      throw new TypeError(`Assigned-ID source must be a regular file: ${item.source}`);
+    }
+    const bytes = await readFile(file);
+    if (createHash('sha256').update(bytes).digest('hex') !== item.fileHash) {
+      throw new Error(`Assigned-ID source changed after the deployed build: ${item.source}`);
+    }
+    const parsed = parseFrontmatter(bytes.toString('utf8'));
+    if (parsed.errors.length > 0 || parsed.data.id !== item.id) {
+      throw new Error(`Assigned-ID source no longer contains its deployed ULID: ${item.source}`);
+    }
+    sources.add(item.source);
+  }
+  return [...sources].sort();
+}
+
+export async function recordDeployment({
+  root,
+  deployedOn,
+  now,
+  deployedCommitSha,
+  spawnProcess = spawn
+}) {
+  const siteRoot = path.resolve(root);
+  const manifestPath = path.join(siteRoot, BUILD_MANIFEST_PATH);
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error('Current validated build manifest is missing; deployment cannot be recorded');
+    }
+    throw new TypeError(`Current validated build manifest is invalid: ${error.message}`);
+  }
+  const date = deployedOn ?? await repositoryEvaluationDate({ root: siteRoot, now });
+  if (typeof deployedCommitSha !== 'string' || !/^[0-9a-f]{40}$/.test(deployedCommitSha)) {
+    throw new TypeError('record-deployment requires --commit-sha <lowercase 40-character SHA>');
+  }
+  const head = await readHead(siteRoot, spawnProcess);
+  if (deployedCommitSha !== head) {
+    throw new Error(`Deployment SHA ${deployedCommitSha} does not match checkout HEAD ${head}`);
+  }
+  const state = await recordSuccessfulDeployment({
+    root: siteRoot,
+    manifest,
+    deployedOn: date,
+    deployedCommitSha
+  });
+  const statePath = '.gala/publication-state.yml';
+  const contentPaths = await assignedContentPaths(siteRoot, manifest);
+  const committedPaths = [statePath, ...contentPaths];
+  const addCode = await runGit(siteRoot, ['add', '--', ...committedPaths], spawnProcess);
+  if (addCode !== 0) throw new Error(`Git add exited with code ${addCode}`);
+  const diffCode = await runGit(
+    siteRoot,
+    ['diff', '--cached', '--quiet', '--exit-code', '--', ...committedPaths],
+    spawnProcess
+  );
+  if (diffCode === 0) return { state, pushed: false, recordedStateSha: head };
+  if (diffCode !== 1) throw new Error(`Git diff exited with code ${diffCode}`);
+  const assignmentTrailers = (manifest.assignedContentIds ?? []).map(
+    ({ id, source }) => `Gala-Assigned-ID: ${id} ${source}`
+  );
+  const commitMessage = [
+    'chore(gala): record successful deployment [skip ci]',
+    '',
+    `Gala-Deployed-SHA: ${deployedCommitSha}`,
+    ...assignmentTrailers
+  ].join('\n');
+  const commitCode = await runGit(siteRoot, [
+    'commit', '--only', '-m', commitMessage,
+    '--', ...committedPaths
+  ], spawnProcess);
+  if (commitCode !== 0) throw new Error(`Git commit exited with code ${commitCode}`);
+  const recordedStateSha = await readHead(siteRoot, spawnProcess);
+  if (recordedStateSha === deployedCommitSha) {
+    throw new Error('Git did not create a distinct recorded-state commit');
+  }
+  const pushCode = await runGit(siteRoot, ['push'], spawnProcess);
+  if (pushCode !== 0) throw new Error(`Git push exited with code ${pushCode}`);
+  return { state, pushed: true, recordedStateSha };
+}

package/src/repository-limits.js

@@ -0,0 +1,94 @@
+import { spawn } from 'node:child_process';
+import { lstat, readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+const MEBIBYTE = 1024 * 1024;
+
+function gitRepositoryBytes(root, spawnProcess) {
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['-C', root, 'count-objects', '-v'], {
+      cwd: root,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    let output = '';
+    let errors = '';
+    child.stdout.on('data', (chunk) => { output += chunk; });
+    child.stderr.on('data', (chunk) => { errors += chunk; });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) return reject(new Error(`Repository inspection terminated by signal ${signal}`));
+      if (code !== 0) return reject(new Error(`Repository inspection failed: ${errors.trim()}`));
+      const values = Object.fromEntries(output.trim().split('\n').map((line) => {
+        const separator = line.indexOf(':');
+        return [line.slice(0, separator), Number(line.slice(separator + 1).trim())];
+      }));
+      if (!Number.isFinite(values.size) || !Number.isFinite(values['size-pack'])) {
+        return reject(new Error('Git returned invalid repository size metadata'));
+      }
+      resolve((values.size + values['size-pack']) * 1024);
+    });
+  });
+}
+
+async function countPosts(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const counts = await Promise.all(entries.map((entry) => {
+    if (entry.isDirectory()) return countPosts(path.join(directory, entry.name));
+    return Promise.resolve(entry.isFile() && /^index\.[^.]+\.md$/.test(entry.name) ? 1 : 0);
+  }));
+  return counts.reduce((total, count) => total + count, 0);
+}
+
+export function repositoryLimitWarnings({ repositoryBytes, postCount, buildDurationMs }) {
+  const warnings = [];
+  if (repositoryBytes > 800 * MEBIBYTE) {
+    warnings.push({ severity: 'critical', code: 'repository-size-800mb' });
+  } else if (repositoryBytes > 500 * MEBIBYTE) {
+    warnings.push({ severity: 'warning', code: 'repository-size-500mb' });
+  }
+  if (postCount > 1000) warnings.push({ severity: 'warning', code: 'post-count-1000' });
+  if (buildDurationMs != null && buildDurationMs > 5 * 60 * 1000) {
+    warnings.push({ severity: 'warning', code: 'build-duration-5m' });
+  }
+  return warnings;
+}
+
+export async function inspectRepositoryLimits(root, { spawnProcess = spawn, buildDurationMs } = {}) {
+  const resolvedRoot = path.resolve(root);
+  const [repositoryBytes, postCount] = await Promise.all([
+    gitRepositoryBytes(resolvedRoot, spawnProcess),
+    countPosts(path.join(resolvedRoot, 'content', 'posts'))
+  ]);
+  return {
+    repositoryBytes,
+    postCount,
+    warnings: repositoryLimitWarnings({ repositoryBytes, postCount, buildDurationMs })
+  };
+}
+
+export async function reportRepositoryLimitWarnings(
+  root,
+  { spawnProcess = spawn, output = process.stderr } = {}
+) {
+  const resolvedRoot = path.resolve(root);
+  try {
+    const [gitMetadata, config, posts] = await Promise.all([
+      lstat(path.join(resolvedRoot, '.git')),
+      lstat(path.join(resolvedRoot, 'site.config.yml')),
+      lstat(path.join(resolvedRoot, 'content', 'posts'))
+    ]);
+    if ((!gitMetadata.isDirectory() && !gitMetadata.isFile())
+      || !config.isFile() || config.isSymbolicLink()
+      || !posts.isDirectory() || posts.isSymbolicLink()) {
+      return [];
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+
+  const { warnings } = await inspectRepositoryLimits(resolvedRoot, { spawnProcess });
+  for (const { severity, code } of warnings) output.write(`${severity}\t${code}\n`);
+  return warnings;
+}

package/src/scaffold-git.js

@@ -0,0 +1,41 @@
+import { spawn } from 'node:child_process';
+
+function run(root, args, spawnProcess, acceptedExitCodes = [0]) {
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['-C', root, ...args], { cwd: root, shell: false, stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) reject(new Error(`Git ${args[0]} terminated by signal ${signal}`));
+      else if (!acceptedExitCodes.includes(code)) reject(new Error(`Git ${args[0]} exited with code ${code}`));
+      else resolve(code);
+    });
+  });
+}
+
+function capture(root, args, spawnProcess) {
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['-C', root, ...args], {
+      cwd: root, shell: false, stdio: ['ignore', 'pipe', 'inherit']
+    });
+    let stdout = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) reject(new Error(`Git ${args[0]} terminated by signal ${signal}`));
+      else if (code !== 0) reject(new Error(`Git ${args[0]} exited with code ${code}`));
+      else resolve(stdout.trim());
+    });
+  });
+}
+
+export async function commitScaffold(root, { spawnProcess = spawn } = {}) {
+  await run(root, ['add', '--', 'site.config.yml', '.github/workflows/publish.yml'], spawnProcess);
+  const unchanged = await run(root, ['diff', '--cached', '--quiet', '--exit-code'], spawnProcess, [0, 1]);
+  if (unchanged === 1) {
+    await run(root, ['commit', '-m', 'chore(gala): configure site'], spawnProcess);
+  }
+  await run(root, ['push', 'origin', 'HEAD'], spawnProcess);
+  const commitSha = await capture(root, ['rev-parse', 'HEAD'], spawnProcess);
+  if (!/^[0-9a-f]{40}$/.test(commitSha)) throw new Error('Git returned an invalid scaffold commit SHA');
+  return commitSha;
+}