@rathnasgala/cli 0.0.22 → 1.1.4

package/src/commands/domain.js

@@ -0,0 +1,124 @@
+import path from 'node:path';
+
+import { galaApi } from '../api/gala.js';
+import { galaCredential } from '../auth/gala.js';
+import { UsageError } from '../cli/args.js';
+import { customDomain } from '../domain.js';
+import { readPublication } from '../publication.js';
+
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+
+export async function domain({ terminal, options, cwd = process.cwd() }) {
+  const root = path.resolve(options.value('root') ?? cwd);
+  const publication = await readPublication(root);
+  if (!publication || !ULID.test(publication.siteId ?? '')) {
+    throw new UsageError('Run this inside a registered Gala publication, or pass --root.');
+  }
+  const [action = 'status', value, ...extra] = options.positional;
+  if (extra.length > 0 || !['status', 'set', 'check', 'cancel', 'remove'].includes(action)) {
+    throw new UsageError('Use: gala domain [status|set <hostname>|check|cancel|remove]');
+  }
+  if (action === 'set' && value == null) throw new UsageError('domain set needs a hostname');
+  if (action !== 'set' && value != null) throw new UsageError(`domain ${action} takes no hostname`);
+
+  const credential = await galaCredential({
+    terminal, apiBaseUrl: options.value('api-base-url'),
+  });
+  const api = galaApi({ baseUrl: credential.apiBaseUrl, token: credential.accessToken });
+
+  if (action === 'status') {
+    const pending = await api.pendingTopologyChange(publication.siteId);
+    if (!pending) {
+      terminal.result((await ownedSite(api, publication.siteId)).publicationUrl);
+      terminal.note('No domain change is pending.');
+      return null;
+    }
+    showPending(terminal, pending);
+    return pending;
+  }
+
+  if (action === 'set') {
+    const checked = customDomain(value);
+    if (checked.error) throw new UsageError(checked.error);
+    const change = await api.prepareTopologyChange(publication.siteId, {
+      canonicalBaseUrl: `https://${checked.host}`,
+      pathPrefix: '/',
+    });
+    terminal.done(`Reserved ${checked.host}`);
+    terminal.note('Verify it in the repository owner’s GitHub account, then run: gala domain check');
+    terminal.openUrl('https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages');
+    return change;
+  }
+
+  if (action === 'remove') {
+    const existing = await api.pendingTopologyChange(publication.siteId);
+    if (existing) {
+      throw new UsageError('No second domain change can start while another one is pending; cancel it first.');
+    }
+    const site = await ownedSite(api, publication.siteId);
+    const [owner, repository] = site.repository.split('/');
+    const host = `${owner.toLowerCase()}.github.io`;
+    const prefix = repository.toLowerCase() === host ? '/' : `/${repository}`;
+    const change = await api.prepareTopologyChange(publication.siteId, {
+      canonicalBaseUrl: `https://${host}`,
+      pathPrefix: prefix,
+    });
+    const committed = await api.commitTopologyChange(publication.siteId, change.changeId);
+    terminal.done(`Returned to ${committed.canonicalBaseUrl}${prefix === '/' ? '/' : `${prefix}/`}`);
+    terminal.note('Remove the old custom-domain records from your DNS provider.');
+    return committed;
+  }
+
+  const pending = await api.pendingTopologyChange(publication.siteId);
+  if (!pending) throw new UsageError('No domain change is pending.');
+
+  if (action === 'cancel') {
+    await api.discardTopologyChange(publication.siteId, pending.changeId);
+    terminal.done('Cancelled the pending domain change');
+    return null;
+  }
+
+  if (action === 'check') {
+    if (pending.cname && pending.state === 'PREPARED') {
+      const configured = await api.configureTopologyChange(publication.siteId, pending.changeId);
+      terminal.done(`GitHub verified ${configured.cname}`);
+      terminal.note(dnsInstruction(configured.cname, await providerHost(api, publication.siteId)));
+      terminal.note('After DNS propagates, run: gala domain check');
+      return configured;
+    }
+    const committed = await api.commitTopologyChange(publication.siteId, pending.changeId);
+    terminal.done(committed.cname
+      ? `${committed.cname} is live with enforced HTTPS`
+      : 'The GitHub Pages address is live again');
+    if (!committed.cname) {
+      terminal.note('Remove the old custom-domain records from your DNS provider.');
+    }
+    return committed;
+  }
+
+  throw new UsageError(`Unsupported domain action: ${action}`);
+}
+
+async function ownedSite(api, siteId) {
+  const sites = await api.listPublications();
+  const site = Array.isArray(sites) ? sites.find((candidate) => candidate.siteId === siteId) : null;
+  if (!site || typeof site.repository !== 'string' || typeof site.publicationUrl !== 'string') {
+    throw new Error('Publication is not available');
+  }
+  return site;
+}
+
+async function providerHost(api, siteId) {
+  return (await ownedSite(api, siteId)).repository.split('/')[0].toLowerCase() + '.github.io';
+}
+
+function dnsInstruction(host, target) {
+  return `For a subdomain: CNAME ${host} → ${target}. For an apex domain, use GitHub’s documented A/AAAA records.`;
+}
+
+function showPending(terminal, pending) {
+  terminal.result(`${pending.canonicalBaseUrl}${pending.pathPrefix}`);
+  terminal.note(`State: ${pending.state}`);
+  if (pending.state === 'PREPARED') terminal.note('Next: verify ownership, then run gala domain check.');
+  else terminal.note('Next: configure DNS, then run gala domain check.');
+}

package/src/commands/init.js

@@ -0,0 +1,276 @@
+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, populateEmptyRepository } from '../git.js';
+import { UsageError } from '../cli/args.js';
+import { customDomain } from '../domain.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]+)*$/;
+const GITHUB_APP_INSTALLATION_URL = 'https://github.com/apps/gala67-app/installations/new';
+
+export async function init({ terminal, options, cwd = process.cwd() }) {
+  const explicitName = options.value('name');
+  if (options.positional.length > 1) {
+    throw new UsageError('init accepts at most one destination directory');
+  }
+  const directory = path.resolve(cwd, options.positional[0] ?? '.');
+  const requestedDomain = options.value('domain');
+  const checkedDomain = requestedDomain == null ? null : customDomain(requestedDomain);
+  if (checkedDomain?.error) throw new UsageError(checkedDomain.error);
+
+  const destination = await inspectDestination(directory);
+
+  const gala = await galaCredential({ terminal, apiBaseUrl: options.value('api-base-url') });
+  const github = await githubCredential({ terminal });
+
+  const name = await publicationName({ terminal, explicitName, directory });
+
+  const api = galaApi({ baseUrl: gala.apiBaseUrl, token: gala.accessToken });
+  const capability = await api.githubCapability(github.accessToken);
+  const installation = await publicationAccount({ terminal, api, capability });
+
+  terminal.step(`Creating ${name}`);
+  const created = await createPublication({
+    terminal, api, capability, name, github, installationId: installation.installationId
+  });
+
+  terminal.step('Waiting for GitHub to copy the template');
+  await waitForContent(githubApi(github.accessToken), created.owner, created.name);
+
+  terminal.step('Cloning');
+  const checkout = {
+    url: `https://github.com/${created.owner}/${created.name}.git`,
+    target: directory,
+    token: github.accessToken
+  };
+  if (destination === 'empty-git') await populateEmptyRepository(checkout);
+  else await cloneRepository(checkout);
+
+  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) || '.');
+
+  let domainChange;
+  if (checkedDomain?.host) {
+    terminal.step(`Reserving ${checkedDomain.host}`);
+    try {
+      domainChange = await api.prepareTopologyChange(registration.siteId, {
+        canonicalBaseUrl: `https://${checkedDomain.host}`,
+        pathPrefix: '/'
+      });
+    } catch (failure) {
+      throw new Error(
+        `${created.owner}/${created.name} was created, but ${checkedDomain.host} was not reserved: `
+          + `${failure instanceof Error ? failure.message : 'unknown error'}`
+      );
+    }
+  }
+
+  terminal.blank();
+  terminal.note('gala new "Your first post"');
+  if (domainChange) terminal.note('gala domain check');
+
+  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, installationId }) {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const result = await api.createPublication({ capability, name, installationId });
+    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;
+    }
+
+    if (result?.status === 'SETUP_PENDING') {
+      terminal.note(`${result.owner ?? ''}/${result.name ?? name} exists; GitHub is still copying it`);
+      await new Promise((resolve) => { setTimeout(resolve, 1000); });
+      continue;
+    }
+
+    if (result?.status !== 'NEEDS_SHARING') {
+      throw new Error(
+        `Gala could not create the publication (${result?.outcome ?? result?.status}). `
+        + `Continue at ${result?.recoveryUrl ?? GITHUB_APP_INSTALLATION_URL} `
+        + 'and try again.'
+      );
+    }
+
+    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(result?.recoveryUrl
+      ?? 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}.`);
+}
+
+export async function publicationAccount({ terminal, api, capability }) {
+  const state = await api.githubInstallationAccounts({ capability });
+  const accounts = Array.isArray(state?.accounts) ? state.accounts : [];
+  if (accounts.length === 0) {
+    throw new Error(
+      `Install or request the Gala GitHub App at ${state?.installationUrl
+        ?? GITHUB_APP_INSTALLATION_URL} and try again.`
+    );
+  }
+  const personal = accounts.find((account) => account?.organization === false);
+  if (personal) return personal;
+  if (accounts.length === 1) return accounts[0];
+
+  const choices = accounts.map((account) => account.login).join(', ');
+  const selected = (await terminal.ask(`Which GitHub account should own it? (${choices})`)).trim();
+  const account = accounts.find((candidate) =>
+    candidate.login.toLowerCase() === selected.toLowerCase());
+  if (!account) throw new UsageError(`Choose one of these GitHub accounts: ${choices}`);
+  return account;
+}
+
+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, directory }) {
+  const proposed = explicitName ?? path.basename(directory);
+  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;
+}
+
+export async function inspectDestination(directory) {
+  const { readFile, readdir, stat } = await import('node:fs/promises');
+  let entries;
+  try {
+    entries = await readdir(directory);
+  } catch (missing) {
+    if (missing?.code === 'ENOENT') return 'missing';
+    throw missing;
+  }
+  if (entries.length === 0) return 'empty';
+  if (entries.length === 1 && entries[0] === '.git') {
+    const gitDirectory = path.join(directory, '.git');
+    if (!(await stat(gitDirectory)).isDirectory()) {
+      throw new UsageError('The destination has a linked .git file; use a new empty directory.');
+    }
+    const head = (await readFile(path.join(gitDirectory, 'HEAD'), 'utf8')).trim();
+    const branch = /^ref: (refs\/heads\/.+)$/.exec(head)?.[1];
+    if (branch) {
+      const packed = await readFile(path.join(gitDirectory, 'packed-refs'), 'utf8')
+        .then((source) => source.split('\n').some((line) => line && !line.startsWith('#')),
+          (failure) => failure?.code === 'ENOENT' ? false : Promise.reject(failure));
+      if (!await hasReference(path.join(gitDirectory, 'refs')) && !packed) return 'empty-git';
+    }
+  }
+  throw new UsageError('Gala needs an empty destination directory (an empty git repository is allowed).');
+}
+
+async function hasReference(directory) {
+  const { readdir } = await import('node:fs/promises');
+  const entries = await readdir(directory, { withFileTypes: true }).catch((failure) => {
+    if (failure?.code === 'ENOENT') return [];
+    throw failure;
+  });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) return true;
+    if (await hasReference(path.join(directory, entry.name))) return true;
+  }
+  return false;
+}
+
+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);
+    });
+  });
+}