@rathnasgala/cli 0.0.22 → 1.1.4

package/src/content.js

@@ -0,0 +1,31 @@
+import { regenerateBuildManifest } from '@rathnasgala/content-validation';
+
+/**
+ * Content validation, shared by preview and publish.
+ *
+ * v0 exposed this as its own `validate` command and then called it from two others, so a writer had
+ * three ways to learn the same thing and one of them — the pre-push hook — ran it behind their back.
+ * Validation is not a task; it is a precondition of showing or shipping. It runs where those happen
+ * and nowhere else.
+ *
+ * `regenerate` is injectable because the real validator compares the configuration against the
+ * theme package installed in the publication's node_modules. That belongs in a test of the
+ * validator, not of how this reports what it found.
+ */
+export async function checkContent({ terminal, root, today, regenerate = regenerateBuildManifest }) {
+  const { results } = await regenerate({ root, today });
+  const failed = results.filter(({ errors }) => errors.length > 0);
+
+  for (const result of results) {
+    for (const warning of result.warnings ?? []) terminal.note(`${result.file}: ${warning}`);
+  }
+  if (failed.length === 0) return results;
+
+  // Every problem, in one pass. Stopping at the first means fixing one thing, running again, and
+  // only then learning about the next.
+  terminal.blank();
+  for (const result of failed) {
+    for (const error of result.errors) terminal.fail(`${result.file}: ${error}`);
+  }
+  throw new Error(`${failed.length} post${failed.length === 1 ? '' : 's'} cannot be published yet`);
+}

package/src/domain.js

@@ -0,0 +1,33 @@
+// Generated by scripts/generate-custom-domain.mjs. Do not edit.
+const HOST = new RegExp("^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$");
+const MAXIMUM_HOSTNAME_LENGTH = 63;
+const FORBIDDEN_PREFIXES = ["www.www."];
+const FORBIDDEN_SUFFIXES = [".github.io"];
+const MESSAGE = {
+  "empty": "Enter a domain such as blog.example.com.",
+  "components": "Enter only the hostname, without a protocol, path, port or credentials.",
+  "policy": "Enter a valid custom hostname shorter than 64 characters and outside github.io.",
+  "labels": "Enter a complete domain with valid DNS labels.",
+  "invalid": "Enter a valid domain such as blog.example.com."
+};
+
+export function customDomain(value) {
+  const source = typeof value === 'string' ? value.trim().toLowerCase().replace(/\.$/, '') : '';
+  if (!source) return { error: MESSAGE.empty };
+  try {
+    const parsed = new URL(`https://${source}`);
+    if (parsed.username || parsed.password || parsed.port || parsed.pathname !== '/'
+        || parsed.search || parsed.hash || parsed.hostname !== source) {
+      return { error: MESSAGE.components };
+    }
+    if (source.length > MAXIMUM_HOSTNAME_LENGTH
+        || FORBIDDEN_PREFIXES.some((prefix) => source.startsWith(prefix))
+        || FORBIDDEN_SUFFIXES.some((suffix) => source.endsWith(suffix))) {
+      return { error: MESSAGE.policy };
+    }
+    if (!HOST.test(source)) return { error: MESSAGE.labels };
+    return { host: source };
+  } catch {
+    return { error: MESSAGE.invalid };
+  }
+}

package/src/git.js

@@ -0,0 +1,160 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+/**
+ * Git, authenticated as the writer's Gala credential rather than as the machine.
+ *
+ * v0 let every git call fall through to whatever credential helper the machine had configured,
+ * which is a different identity from the one the CLI just authenticated with. On the machine where
+ * this surfaced the token belonged to one account and git's stored credential to another, so a
+ * scaffold created the repository through the API and was then refused when it tried to write to
+ * it. Anyone with no credential configured at all — a fresh machine, or SSH-only — had no chance.
+ *
+ * The token travels in the environment, never in the argument list, because arguments are readable
+ * machine-wide through `ps`. Nothing is written to `.git/config`.
+ */
+const TOKEN_VARIABLE = 'GALA_GIT_TOKEN';
+
+function credentialArguments(token) {
+  if (typeof token !== 'string' || token === '') return [];
+  return [
+    // The empty helper first, or the machine's keychain answers before ours does.
+    '-c', 'credential.helper=',
+    '-c', `credential.helper=!f() { test "$1" = get && echo username=x-access-token && echo "password=$${TOKEN_VARIABLE}"; }; f`
+  ];
+}
+
+function environmentFor(token) {
+  if (typeof token !== 'string' || token === '') return process.env;
+  // Nothing on this path may block waiting for a username at a terminal.
+  return { ...process.env, [TOKEN_VARIABLE]: token, GIT_TERMINAL_PROMPT: '0' };
+}
+
+export function createGit({ root, token, spawnProcess = spawn } = {}) {
+  const cwd = root == null ? process.cwd() : path.resolve(root);
+
+  /*
+   * Git's own output is captured, not inherited.
+   *
+   * v0 let it through, so a writer's terminal filled with `Cloning into '/long/path'`, rebase
+   * plumbing and push refspecs interleaved with the CLI's own lines. None of it is addressed to
+   * them. On failure every captured line is emitted, because that is exactly when git's text is
+   * the most useful thing on screen.
+   */
+  const run = (args, { allow = [0], capture = false } = {}) => new Promise((resolve, reject) => {
+    const child = spawnProcess('git', ['-C', cwd, ...credentialArguments(token), ...args], {
+      cwd,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: environmentFor(token)
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk) => { stdout += chunk; });
+    child.stderr?.on('data', (chunk) => { stderr += chunk; });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal || !allow.includes(code)) {
+        const said = `${stdout}${stderr}`.trim();
+        const failure = new Error(signal
+          ? `git ${args[0]} stopped by ${signal}`
+          : `git ${args[0]} exited with ${code}`);
+        failure.detail = said;
+        reject(failure);
+        return;
+      }
+      resolve(capture ? stdout.trim() : code);
+    });
+  });
+
+  const git = {
+    root: cwd,
+    run,
+
+    async branch() {
+      const name = await run(['rev-parse', '--abbrev-ref', 'HEAD'], { capture: true });
+      if (name === 'HEAD' || !/^[A-Za-z0-9._/-]+$/.test(name)) {
+        throw new Error('This checkout is not on a named branch');
+      }
+      return name;
+    },
+
+    async head() {
+      const sha = await run(['rev-parse', 'HEAD'], { capture: true });
+      if (!/^[0-9a-f]{40}$/.test(sha)) throw new Error('git returned an unusable commit id');
+      return sha;
+    },
+
+    /** True when something was recorded; false when the tree already matched. */
+    async record(message, paths) {
+      await run(['add', '--', ...paths]);
+      const unchanged = await run(['diff', '--cached', '--quiet', '--exit-code'], { allow: [0, 1] });
+      if (unchanged === 0) return false;
+      await run(['commit', '-m', message]);
+      return true;
+    },
+
+    send: () => run(['push', 'origin', 'HEAD']),
+
+    /**
+     * Brings the remote's commits in, over the top of anything uncommitted.
+     *
+     * `--autostash` matters: this runs before the writer's work is recorded, and a rebase refuses a
+     * dirty tree. Doing it the other way round — record first, then rebase — is what produced
+     * conflicts in `content/posts/*`: validation assigns a content id to any post missing one, and
+     * the publish workflow assigns one remotely too. Both sides edit the same file, pick different
+     * ids, and git can only call that a conflict. Taking the remote first means the local pass sees
+     * ids that already exist and changes nothing.
+     */
+    async takeRemote() {
+      const branch = await git.branch();
+      await run(['fetch', 'origin', branch]);
+      await run(['rebase', '--autostash', `origin/${branch}`]);
+      return git.head();
+    }
+  };
+
+  return git;
+}
+
+export function cloneRepository({ url, target, token, spawnProcess = spawn }) {
+  const resolved = path.resolve(target);
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('git', [...credentialArguments(token), 'clone', url, resolved], {
+      cwd: path.dirname(resolved),
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: environmentFor(token)
+    });
+    let said = '';
+    child.stdout?.on('data', (chunk) => { said += chunk; });
+    child.stderr?.on('data', (chunk) => { said += chunk; });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal || code !== 0) {
+        const failure = new Error(signal ? `clone stopped by ${signal}` : `clone exited with ${code}`);
+        failure.detail = said.trim();
+        reject(failure);
+        return;
+      }
+      resolve(resolved);
+    });
+  });
+}
+
+/** Populate a deliberately empty git repository without replacing its .git directory. */
+export async function populateEmptyRepository({ url, target, token, spawnProcess = spawn }) {
+  const git = createGit({ root: target, token, spawnProcess });
+  const hasOrigin = await git.run(['remote', 'get-url', 'origin'], { allow: [0, 2] });
+  await git.run(hasOrigin === 0
+    ? ['remote', 'set-url', 'origin', url]
+    : ['remote', 'add', 'origin', url]);
+  await git.run(['fetch', 'origin']);
+  const remoteHead = await git.run(['ls-remote', '--symref', 'origin', 'HEAD'], { capture: true });
+  const branch = /^ref: refs\/heads\/([^\s]+)\s+HEAD$/m.exec(remoteHead)?.[1];
+  if (!branch || !/^[A-Za-z0-9._/-]+$/.test(branch)) {
+    throw new Error('GitHub did not report a usable default branch');
+  }
+  await git.run(['checkout', '-B', branch, '--track', `origin/${branch}`]);
+  return path.resolve(target);
+}

package/src/index.js

@@ -1,310 +1,60 @@
 #!/usr/bin/env node
+import { UsageError, parseArguments } from './cli/args.js';
+import { createTerminal } from './cli/terminal.js';
+import { COMMANDS } from './commands-manifest.js';
 
-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';
-import { openInBrowser } from './open-browser.js';
-import { prepareScaffold } from './scaffold-preflight.js';
-import { refreshEngagementSnapshot } from './refresh-command.js';
-import { switchTopology } from './topology-command.js';
-import { acquireAttributionEntitlement } from './entitlement-command.js';
 
-/*
- * A failed command should say what went wrong and what to do about it. Node's default for a
- * rejected top-level await is a stack trace through node_modules, which tells a writer nothing and
- * buries the one line that matters. The stack is still available behind GALA_DEBUG for anyone
- * debugging the CLI itself.
- */
-process.on('uncaughtException', reportAndExit);
-process.on('unhandledRejection', reportAndExit);
+const [name, ...argv] = process.argv.slice(2);
+const terminal = createTerminal();
 
-function reportAndExit(failure) {
-  if (process.env.GALA_DEBUG) {
-    process.stderr.write(`${failure instanceof Error ? failure.stack : String(failure)}\n`);
-  } else {
-    const message = failure instanceof Error ? failure.message : String(failure);
-    process.stderr.write(`${message}\n`);
-  }
-  process.exit(1);
+if (name == null || name === 'help' || name === '--help' || name === '-h') {
+  usage();
+  process.exit(name == null ? 1 : 0);
 }
 
-/**
- * Opens the page and says so, or falls back to asking for it to be opened by hand. The URL is
- * printed either way — it is the thing the writer may need to move to another device.
- */
-function announce(verificationUri, userCode) {
-  const opened = openInBrowser(verificationUri);
-  return `${opened ? 'Opened' : 'Open'} ${verificationUri}\nEnter code: ${userCode}\n`;
+const command = COMMANDS[name];
+if (command == null) {
+  terminal.fail(`there is no ${name} command`);
+  usage();
+  process.exit(1);
 }
 
-const [command, ...args] = process.argv.slice(2);
-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')) {
-  process.stdout.write(`${usage}\n`);
+if (argv.includes('--help') || argv.includes('-h')) {
+  process.stdout.write(`\n  ${command.usage ?? `gala ${name}`}\n  ${command.summary}\n\n`);
   process.exit(0);
 }
 
-const recognizedCommands = new Set([
-  'auth', 'configure', 'validate', 'new', 'doctor', 'preview',
-  'workflow', 'publish', 'record-deployment', 'refresh', 'hook', 'upgrade', 'topology', 'entitlement'
-]);
-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());
+try {
+  const options = parseArguments(argv, { flags: command.flags ?? [], switches: command.switches ?? [] });
+  await command.run({ terminal, options });
+} catch (failure) {
+  report(failure);
+  process.exit(1);
 }
 
-if (command === 'auth') {
-  if (args[0] === 'github') {
-    await authenticateGithub({
-      showInstructions: ({ verificationUri, userCode }) => {
-        process.stdout.write(announce(verificationUri, userCode));
-      }
-    });
-    process.stdout.write('GitHub authentication stored securely.\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(announce(verificationUri, userCode));
-      }
-    });
-    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 explicitInstallationId = valueFor('--installation-id');
-  const topology = valueFor('--topology') ?? 'provider-default';
-  const siteOptions = parseScaffoldOptions(args);
-  // Prompting only makes sense at a terminal. In CI there is nobody to answer, so a missing value
-  // has to stay a clear error rather than a process that hangs waiting for enter.
-  const interactive = process.stdin.isTTY === true;
-  const ask = interactive
-    ? async (question) => {
-      const terminal = createInterface({ input: process.stdin, output: process.stdout });
-      try { return await terminal.question(question); } finally { terminal.close(); }
-    }
-    : undefined;
-  const prepared = await prepareScaffold({
-    owner: valueFor('--owner'),
-    repository: valueFor('--repository'),
-    target: valueFor('--target'),
-    githubInstallationId: explicitInstallationId == null ? undefined : Number(explicitInstallationId),
-    siteName: siteOptions.siteName,
-    apiBaseUrl: valueFor('--api-base-url') ?? 'https://api.gala67.com',
-    notify: (message) => process.stdout.write(`${message}\n`),
-    ask
-  });
-  const result = await scaffoldSite({
-    notify: (message) => process.stdout.write(`${message}\n`),
-    ask,
-    openUrl: openInBrowser,
-    owner: prepared.owner,
-    repository: prepared.repository,
-    target: prepared.target,
-    githubInstallationId: prepared.githubInstallationId,
-    topology,
-    canonicalBaseUrl: valueFor('--canonical-base-url'),
-    siteOptions,
-    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 === '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];
-  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`);
+/**
+ * One line the writer can act on.
+ *
+ * A rejected top-level await prints a stack through node_modules by default, which buries the only
+ * line that matters. The stack is still there behind GALA_DEBUG for anyone debugging the CLI
+ * itself, which is a different audience from anyone trying to publish.
+ */
+function report(failure) {
+  if (process.env.GALA_DEBUG) {
+    process.stderr.write(`${failure instanceof Error ? failure.stack : String(failure)}\n`);
+    return;
   }
-  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`);
+  terminal.fail(failure instanceof Error ? failure.message : String(failure));
+  // Captured output from a subprocess is the most useful thing on screen at exactly this moment.
+  if (typeof failure?.detail === 'string' && failure.detail !== '') {
+    for (const line of failure.detail.split('\n')) terminal.note(line);
   }
-  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 === '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);
-    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;
+  if (failure instanceof UsageError) usage();
+}
+
+function usage() {
+  const lines = Object.entries(COMMANDS)
+    .map(([key, { summary }]) => `    ${key.padEnd(9)} ${summary}`)
+    .join('\n');
+  process.stdout.write(`\n  gala <command>\n\n${lines}\n\n    Run any command with --help.\n\n`);
 }

package/src/publication.js

@@ -0,0 +1,39 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { parse } from 'yaml';
+
+/**
+ * Where a publication and its posts actually live on the web.
+ *
+ * The CLI knew every part of this and never said it: `new` printed a file path, `publish` said the
+ * site would appear shortly, and the writer was left to assemble
+ * `{canonicalBaseUrl}{pathPrefix}/{language}/{slug}/` themselves. That is easy to get wrong — the
+ * language segment is not obvious from anything they typed — and being unable to find your own post
+ * is a poor first minute with a publishing tool.
+ */
+export async function readPublication(root) {
+  try {
+    const configuration = parse(await readFile(path.join(root, 'site.config.yml'), 'utf8'));
+    const base = configuration?.hosting?.canonicalBaseUrl;
+    if (typeof base !== 'string') return null;
+    const prefix = typeof configuration?.hosting?.pathPrefix === 'string'
+      ? configuration.hosting.pathPrefix
+      : '/';
+    return {
+      siteId: configuration?.site?.id,
+      repository: configuration?.site?.repository,
+      name: configuration?.site?.name,
+      defaultLanguage: configuration?.site?.defaultLanguage ?? 'en',
+      url: `${base.replace(/\/$/, '')}${prefix === '/' ? '' : prefix}/`
+    };
+  } catch {
+    // Not being able to read it is never worth failing a command over; the caller simply says less.
+    return null;
+  }
+}
+
+export function postUrl(publication, slug, language) {
+  if (publication == null) return null;
+  return `${publication.url}${language ?? publication.defaultLanguage}/${slug}/`;
+}

package/src/assign-content-ids.js

@@ -1 +0,0 @@
-export { assignMissingContentIds } from '@rathnasgala/content-validation';

package/src/auth-command.js

@@ -1,36 +0,0 @@
-import { pollForGalaToken, requestGalaDeviceCode } from './gala-device-flow.js';
-import { writeGalaCredential } from './gala-credential-store.js';
-
-export async function authenticateGala({
-  apiBaseUrl = 'https://api.gala67.com',
-  clientId = 'gala-cli',
-  fetchImpl = fetch,
-  sleep,
-  now = Date.now,
-  showInstructions,
-  credentialTarget
-} = {}) {
-  if (typeof showInstructions !== 'function') throw new TypeError('showInstructions is required');
-  const authorization = await requestGalaDeviceCode({ apiBaseUrl, clientId, fetchImpl });
-  showInstructions({
-    verificationUri: authorization.verificationUri,
-    verificationUriComplete: authorization.verificationUriComplete,
-    userCode: authorization.userCode
-  });
-  const token = await pollForGalaToken({
-    ...authorization,
-    apiBaseUrl,
-    clientId,
-    fetchImpl,
-    ...(sleep == null ? {} : { sleep }),
-    now
-  });
-  const expiresAt = new Date(now() + token.expiresInSeconds * 1000);
-  const target = await writeGalaCredential({
-    accessToken: token.accessToken,
-    expiresAt,
-    apiBaseUrl,
-    ...(credentialTarget == null ? {} : { target: credentialTarget })
-  });
-  return Object.freeze({ target, expiresAt });
-}