@rathnasgala/cli 0.0.21 → 1.0.0

package/src/commands/init.js

@@ -0,0 +1,197 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+import { galaApi } from '../api/gala.js';
+import { githubApi } from '../api/github.js';
+import { galaCredential } from '../auth/gala.js';
+import { githubCredential } from '../auth/github.js';
+import { cloneRepository, createGit } from '../git.js';
+import { UsageError } from '../cli/args.js';
+
+/**
+ * Creates a publication and leaves a working checkout behind.
+ *
+ * The shape of this command is the lesson of v0. Everything it used to do itself now belongs to
+ * whoever can do it correctly:
+ *
+ *   - The **server** creates the repository, because it is the same call the browser editor makes:
+ *     it falls back from template to empty-and-seed, waits for the App installation to actually
+ *     reach the result, and reports the installation id. The CLI's own version had none of that,
+ *     which is why repositories it created never appeared in the web UI.
+ *   - The **server** writes `site.config.yml` and the publish workflow during registration. The CLI
+ *     used to write its own versions afterwards and commit them, producing a second commit whose
+ *     entire content was rewriting one line and stripping comments — and a second workflow run that
+ *     collided with the first one's deployment record and failed.
+ *   - **GitHub** turns on Pages by itself once publishing creates a `gh-pages` branch. The CLI used
+ *     to poll ten minutes for a run it had caused, then call an API that changed nothing.
+ *
+ * What is left is genuinely the CLI's: asking what to call it, cloning, and reporting the address.
+ */
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export async function init({ terminal, options, cwd = process.cwd() }) {
+  const explicitName = options.value('name');
+  const here = options.on('here');
+  const target = here ? cwd : undefined;
+
+  const gala = await galaCredential({ terminal, apiBaseUrl: options.value('api-base-url') });
+  const github = await githubCredential({ terminal });
+
+  const name = await publicationName({ terminal, explicitName, here, cwd });
+  const directory = path.resolve(cwd, target ?? name);
+  await refuseOccupied(directory, here);
+
+  const api = galaApi({ baseUrl: gala.apiBaseUrl, token: gala.accessToken });
+  const capability = await api.githubCapability(github.accessToken);
+
+  terminal.step(`Creating ${name}`);
+  const created = await createPublication({ terminal, api, capability, name, github });
+
+  terminal.step('Waiting for GitHub to copy the template');
+  await waitForContent(githubApi(github.accessToken), created.owner, created.name);
+
+  terminal.step('Cloning');
+  await cloneRepository({
+    url: `https://github.com/${created.owner}/${created.name}.git`,
+    target: directory,
+    token: github.accessToken
+  });
+
+  terminal.step('Registering the publication');
+  const git = createGit({ root: directory, token: github.accessToken });
+  const registration = await api.registerSite({
+    capability,
+    idempotencyKey: idempotencyKey(created.owner, created.name),
+    repositoryOwner: created.owner,
+    repositoryName: created.name,
+    topology: 'PROVIDER_DEFAULT',
+    canonicalBaseUrl: `https://${created.owner.toLowerCase()}.github.io`
+  });
+
+  await githubApi(github.accessToken)
+    .setVariable(created.owner, created.name, 'GALA_API_BASE_URL', api.baseUrl);
+
+  // Registration wrote the managed files into the repository; bring them into the checkout so the
+  // writer's copy is the publication as it actually exists.
+  await git.takeRemote();
+
+  terminal.done(`Created ${created.owner}/${created.name}`);
+  terminal.result(publicationUrl(registration, created));
+  terminal.note(path.relative(cwd, directory) || '.');
+  terminal.blank();
+  terminal.note('gala new "Your first post"');
+
+  return { owner: created.owner, name: created.name, siteId: registration.siteId, root: directory };
+}
+
+/**
+ * Creation is a conversation, not a single call.
+ *
+ * `NEEDS_SHARING` means the repository exists with the right content and the App installation
+ * simply cannot see it — an installation scoped to selected repositories, which is the right way to
+ * have it. That is one grant away from working, and GitHub offers no API to do it on the writer's
+ * behalf: adding a repository to an installation is documented as classic-PAT-only. So it is asked
+ * for, with a link to the one page that grants it.
+ */
+async function createPublication({ terminal, api, capability, name, github }) {
+  let created = false;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const result = await api.createPublication({ capability, name });
+    if (result?.status === 'READY') {
+      if (typeof result.owner !== 'string' || typeof result.name !== 'string') {
+        throw new Error('Gala created the publication but did not say where');
+      }
+      return result;
+    }
+
+    // Once the repository exists a further refusal reports UNSUPPORTED rather than NEEDS_SHARING:
+    // the same situation under a different name.
+    const shareable = result?.status === 'NEEDS_SHARING' || created;
+    if (!shareable) {
+      throw new Error(
+        `Gala could not create the publication (${result?.outcome ?? result?.status}). `
+        + 'Install the Gala GitHub App at https://github.com/apps/gala67-app and try again.'
+      );
+    }
+    created = true;
+
+    const owner = result?.owner ?? '';
+    terminal.blank();
+    terminal.step(`${owner}/${result?.name ?? name} exists, but Gala cannot reach it yet`);
+    terminal.note('its installation covers only selected repositories — add this one');
+    terminal.openUrl(installationUrl(result?.installationId, owner, await viewerOf(github)));
+    if (!await terminal.waitForEnter('Once Gala can access it')) {
+      throw new Error(`Add ${owner}/${result?.name ?? name} to the Gala GitHub App, then run this again.`);
+    }
+  }
+  throw new Error(`Gala still cannot reach the repository for ${name}.`);
+}
+
+let viewerCache;
+async function viewerOf(github) {
+  viewerCache ??= await githubApi(github.accessToken).viewer();
+  return viewerCache;
+}
+
+/** User and organisation installations live on different settings paths. */
+export function installationUrl(installationId, owner, selfLogin) {
+  const id = Number(installationId);
+  if (!Number.isSafeInteger(id) || id <= 0) return 'https://github.com/settings/installations';
+  return owner && selfLogin && owner.toLowerCase() !== selfLogin.toLowerCase()
+    ? `https://github.com/organizations/${encodeURIComponent(owner)}/settings/installations/${id}`
+    : `https://github.com/settings/installations/${id}`;
+}
+
+/**
+ * GitHub answers the creation call before the template content lands. Cloning into that window
+ * gives an empty checkout and a missing site.config.yml — a confusing error about a file the
+ * template certainly contains.
+ */
+async function waitForContent(github, owner, name, { attempts = 30, intervalMs = 1000 } = {}) {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (await github.hasContent(owner, name)) return;
+    await new Promise((resolve) => { setTimeout(resolve, intervalMs); });
+  }
+  throw new Error(`${owner}/${name} was created but is still empty. Try again in a moment.`);
+}
+
+async function publicationName({ terminal, explicitName, here, cwd }) {
+  const proposed = explicitName ?? (here ? path.basename(path.resolve(cwd)) : undefined);
+  const answer = proposed ?? await terminal.ask('What should this publication be called?');
+  const name = slugify(answer);
+  if (name == null) {
+    throw new UsageError(`"${answer}" cannot be a repository name — use letters, numbers and hyphens`);
+  }
+  return name;
+}
+
+export function slugify(value) {
+  if (typeof value !== 'string') return null;
+  const slug = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return NAME.test(slug) ? slug : null;
+}
+
+async function refuseOccupied(directory, here) {
+  const { readdir } = await import('node:fs/promises');
+  let entries;
+  try {
+    entries = await readdir(directory);
+  } catch (missing) {
+    if (missing?.code === 'ENOENT') return;
+    throw missing;
+  }
+  if (entries.length === 0) return;
+  throw new UsageError(here
+    ? 'This folder is not empty. Run it in an empty folder, or without --here.'
+    : `${path.basename(directory)} already exists and is not empty.`);
+}
+
+function publicationUrl(registration, created) {
+  const base = registration?.canonicalBaseUrl ?? `https://${created.owner.toLowerCase()}.github.io`;
+  const prefix = registration?.pathPrefix ?? `/${created.name}`;
+  return `${base}${prefix === '/' ? '' : prefix}/`;
+}
+
+function idempotencyKey(owner, name) {
+  return `init-${createHash('sha256').update(`${owner.toLowerCase()}/${name.toLowerCase()}`).digest('hex')}`;
+}

package/src/commands/new.js

@@ -0,0 +1,76 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  createPostMetadata,
+  isContentId,
+  parseFrontmatter,
+  repositoryEvaluationDate,
+  slugifyTitle
+} from '@rathnasgala/content-validation';
+import { stringify } from 'yaml';
+
+import { UsageError } from '../cli/args.js';
+import { postUrl, readPublication } from '../publication.js';
+
+/**
+ * Starts a post.
+ *
+ * The article id is the part worth being careful about: every language variant of one post shares
+ * it, and it is what lets a folder be renamed without the published URL moving. So an existing
+ * variant's id is adopted rather than a new one minted, and conflicting ids are refused instead of
+ * guessed at.
+ */
+export async function createPost({ terminal, options, cwd = process.cwd(), now = Date.now }) {
+  const root = path.resolve(options.value('root') ?? cwd);
+  const title = options.positional[0] ?? await terminal.ask('What is this post called?');
+  if (typeof title !== 'string' || title.trim() === '') throw new UsageError('a post needs a title');
+
+  const timestamp = now();
+  const language = options.value('language') ?? 'en';
+  const publishAfterDate = options.value('today')
+    ?? await repositoryEvaluationDate({ root, now: () => timestamp });
+
+  const metadata = createPostMetadata({ title, language, today: publishAfterDate, timestamp });
+  const directory = path.join(root, 'content', 'posts', slugifyTitle(title));
+  const file = path.join(directory, `index.${metadata.language}.md`);
+
+  await mkdir(directory, { recursive: true });
+  const existing = await siblingId(directory);
+  if (existing != null) metadata.id = existing;
+  await mkdir(path.join(directory, 'media'), { recursive: true });
+
+  // `wx` so an existing variant is never overwritten by a second run.
+  await writeFile(file, `---\n${stringify(metadata).trimEnd()}\n---\n\n# ${title}\n`, {
+    encoding: 'utf8', flag: 'wx'
+  });
+
+  terminal.done('Post created');
+  terminal.result(path.relative(cwd, file));
+
+  // Where it will be, once published. The language segment is not obvious from anything the writer
+  // typed, and hunting for your own post is a poor first minute with a publishing tool.
+  const address = postUrl(await readPublication(root), path.basename(directory), metadata.language);
+  if (address != null) terminal.note(`will appear at ${address}`);
+
+  terminal.blank();
+  terminal.note('write below the second --- line, then: gala preview');
+  return { file, metadata };
+}
+
+/** The id shared by every language variant already in this folder. */
+async function siblingId(directory) {
+  const variants = (await readdir(directory, { withFileTypes: true }))
+    .filter((entry) => entry.isFile() && /^index\.[^.]+\.md$/.test(entry.name));
+
+  const ids = new Set();
+  for (const variant of variants) {
+    const file = path.join(directory, variant.name);
+    const parsed = parseFrontmatter(await readFile(file, 'utf8'));
+    if (parsed.errors.length > 0) throw new Error(`${file} has invalid frontmatter`);
+    if (!isContentId(parsed.data.id)) throw new Error(`${file} is missing a valid article id`);
+    ids.add(parsed.data.id);
+  }
+  if (ids.size > 1) throw new Error(`${directory} has variants with conflicting article ids`);
+  return ids.size === 1 ? ids.values().next().value : null;
+}

package/src/commands/preview.js

@@ -0,0 +1,92 @@
+import { spawn } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+
+import { checkContent } from '../content.js';
+import { readPublication } from '../publication.js';
+
+/**
+ * Builds the site and serves it locally.
+ *
+ * Eleventy is run from the publication's own `node_modules`, so the preview uses the exact
+ * framework version the repository is pinned to — the same one the publish workflow will use. A
+ * preview that agrees with the local machine but not with production is worse than no preview.
+ *
+ * That pin is also why this installs dependencies when they are missing. A freshly cloned
+ * publication has no `node_modules`, and v0 spawned eleventy from it regardless: the writer's first
+ * preview died with a raw Node module-resolution stack, which says nothing about what to do. They
+ * should not need to know npm is involved at all.
+ */
+export async function preview({
+  terminal, options, cwd = process.cwd(), spawnProcess = spawn, regenerate
+}) {
+  const root = path.resolve(options.value('root') ?? cwd);
+  const today = options.value('today');
+
+  terminal.step('Checking content');
+  await checkContent({ terminal, root, today, ...(regenerate == null ? {} : { regenerate }) });
+  terminal.done('Content is valid');
+
+  const eleventy = path.join(root, 'node_modules', '@11ty', 'eleventy', 'cmd.cjs');
+  if (!await exists(eleventy)) {
+    terminal.step('Installing what this publication needs — first time only');
+    await install(root, spawnProcess);
+    if (!await exists(eleventy)) {
+      throw new Error('The preview tooling is still missing after installing. Check package.json.');
+    }
+    terminal.done('Installed');
+  }
+
+  const publication = await readPublication(root);
+  terminal.step('Starting the preview — stop it with Ctrl-C');
+  if (publication != null) terminal.note(`this is ${publication.name ?? 'your publication'} as it will look`);
+  terminal.blank();
+
+  const child = spawnProcess(process.execPath, [eleventy, '--serve', '--watch'], {
+    cwd: root,
+    env: { ...process.env, ...(today == null ? {} : { GALA_EVALUATION_DATE: today }) },
+    shell: false,
+    stdio: 'inherit'
+  });
+
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      // Ctrl-C is how a writer stops a preview; it is not a failure to report.
+      if (signal === 'SIGINT' || signal === 'SIGTERM' || code === 0 || code === 130) resolve();
+      else if (signal) reject(new Error(`Preview stopped by ${signal}`));
+      else reject(new Error(`Preview exited with ${code}`));
+    });
+  });
+}
+
+async function exists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Output is captured; it is npm's, not the writer's, unless something goes wrong. */
+function install(root, spawnProcess) {
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess('npm', ['install', '--no-audit', '--no-fund'], {
+      cwd: root, shell: false, stdio: ['ignore', 'pipe', 'pipe']
+    });
+    let said = '';
+    child.stdout?.on('data', (chunk) => { said += chunk; });
+    child.stderr?.on('data', (chunk) => { said += chunk; });
+    child.once('error', reject);
+    child.once('exit', (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      const failure = new Error('Installing the preview tooling failed');
+      failure.detail = said.trim();
+      reject(failure);
+    });
+  });
+}

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-manifest.js

@@ -0,0 +1,58 @@
+import { auth } from './commands/auth.js';
+import { doctor } from './commands/doctor.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';
+
+/**
+ * Six 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 and clone it here',
+    usage: 'gala init [--name my-notes] [--here]',
+    flags: ['name', 'api-base-url'],
+    switches: ['here'],
+    run: init
+  },
+  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
+  },
+  doctor: {
+    summary: 'Check a publication and say what is wrong',
+    flags: ['root', 'api-base-url'],
+    run: doctor
+  }
+};

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/git.js

@@ -0,0 +1,143 @@
+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);
+    });
+  });
+}