@rathnasgala/cli 1.1.8 → 1.1.10

package/README.md

@@ -1,6 +1,6 @@
 # Gala CLI
 
-Create a publication, write posts, preview them, and publish — from your terminal.
+Create a publication, write posts, preview them, and publish - from your terminal.
 
 ## Requirements
 
@@ -39,7 +39,7 @@ On the first run, it opens GitHub's Gala App installation page. Choose the accou
 finish the installation, and return to the terminal; the same command resumes automatically.
 
 If the Gala GitHub App has not been given access to the new repository, it says so and links to the
-one page that grants it — GitHub has no way for an app to grant itself access, so that click is
+one page that grants it - GitHub has no way for an app to grant itself access, so that click is
 unavoidable. Everything else is automatic.
 
 ## Write
@@ -63,7 +63,7 @@ npx --yes @rathnasgala/cli@latest preview
 ```
 
 Builds the publication and serves it locally, using the exact framework version the repository is
-pinned to — so what you see is what gets published. The first run installs that tooling, which takes
+pinned to - so what you see is what gets published. The first run installs that tooling, which takes
 a moment. Stop it with Ctrl-C.
 
 ```console
@@ -118,7 +118,7 @@ npx --yes @rathnasgala/cli@latest upgrade
 
 Reports on your sign-ins, the publication folder, the publishing workflow, and anything you have
 written but not sent. Each check either passes, names what is wrong and how to fix it, or says it
-could not be determined — never one of those disguised as another.
+could not be determined - never one of those disguised as another.
 
 ## Commands
 
@@ -134,13 +134,13 @@ Run any command with `--help`.
 | `prism` | Manage author-approved reading configurations | `--root`, `--language`, `--depth`, `--intent`, `--modality`, `--file`, `--reason`, `--yes` |
 | `upgrade` | Inspect and apply a verified managed-theme update | `--root`, `--channel`, `--yes` |
 | `doctor` | Check a publication and say what is wrong | `--root` |
-| `auth` | Sign in to Gala and GitHub | — |
+| `auth` | Sign in to Gala and GitHub | - |
 
 `auth` is never a prerequisite you have to remember: any command that needs a credential obtains
-one. It exists for when you want to do it deliberately — a new machine, or a different account.
+one. It exists for when you want to do it deliberately - a new machine, or a different account.
 
 Every command prompts for what it needs when run in a terminal, and every prompt has an option that
-supplies it instead. With no terminal attached — in CI — nothing is ever prompted for: a value that
+supplies it instead. With no terminal attached - in CI - nothing is ever prompted for: a value that
 cannot be worked out is an error naming the option, so an automated run fails immediately rather
 than waiting for an answer that will not come.
 
@@ -155,7 +155,7 @@ directory, with private file permissions. Your GitHub sign-in expires after eigh
 asks you to sign in again rather than quietly using a credential the server will refuse.
 
 Git operations use that same sign-in, not whatever credential your machine happens to have
-configured — so publishing works on a machine where those differ, or where none is configured.
+configured - so publishing works on a machine where those differ, or where none is configured.
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala/cli",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "type": "module",
   "files": [
     "src"

package/src/api/gala.js

@@ -3,8 +3,8 @@ import { request, requestJson } from './http.js';
 /**
  * The Gala API.
  *
- * Only the calls the six commands make. v0 carried a generated client covering the whole surface —
- * comments, reactions, admin, moderation — none of which a CLI ever touches.
+ * Only the calls the six commands make. v0 carried a generated client covering the whole surface -
+ * comments, reactions, admin, moderation - none of which a CLI ever touches.
  */
 export const DEFAULT_API_BASE_URL = 'https://api.gala67.com';
 

package/src/api/github.js

@@ -5,7 +5,7 @@ import { requestJson } from './http.js';
  *
  * The CLI holds a GitHub App user token, not an OAuth App token. That single difference is what
  * separates this from v0: an App token can list installations, is not blocked by an organisation's
- * OAuth App restrictions, and reaches only repositories the App has been given — rather than every
+ * OAuth App restrictions, and reaches only repositories the App has been given - rather than every
  * repository the writer can see, which is what `repo` scope meant.
  */
 const API = 'https://api.github.com';
@@ -33,7 +33,7 @@ export function githubApi(token) {
      * Whether a repository has content yet.
      *
      * Creating a repository is asynchronous: GitHub answers with a clone URL before the template
-     * lands. Cloning into that window produces an empty checkout and a missing site.config.yml —
+     * lands. Cloning into that window produces an empty checkout and a missing site.config.yml -
      * a confusing error about a file the template certainly contains. `size` is not usable as the
      * signal; GitHub still reported 0 for a repository that already had commits.
      */

package/src/api/http.js

@@ -1,7 +1,7 @@
 /**
  * Every HTTP call the CLI makes, and every failure it reports.
  *
- * v0 threw away the response body at all twenty failure sites — `failed with HTTP 403` and nothing
+ * v0 threw away the response body at all twenty failure sites - `failed with HTTP 403` and nothing
  * else. GitHub explains which 403 it is in that body and nowhere else: an organisation's OAuth App
  * restrictions, a missing permission, a rename and a rate limit all arrive as 403 with a sentence
  * telling them apart. Diagnosing anything meant guessing between causes the server had already
@@ -67,6 +67,6 @@ function describe(body) {
   if (parts.length === 0 && typeof body.raw === 'string') parts.push(body.raw);
   if (typeof body.documentation_url === 'string') parts.push(`See ${body.documentation_url}`);
 
-  const detail = parts.join(' — ').replace(/\s+/g, ' ').trim();
+  const detail = parts.join(' - ').replace(/\s+/g, ' ').trim();
   return detail.length > MAX_DETAIL ? `${detail.slice(0, MAX_DETAIL)}…` : detail;
 }

package/src/auth/gala.js

@@ -5,7 +5,7 @@ import { credentialPath, forgetCredential, readCredential, writeCredential } fro
  * The Gala sign-in.
  *
  * A stored credential is checked against the server before anything depends on it, because one
- * that parses and has not expired can still be one the API refuses — and discovering that four
+ * that parses and has not expired can still be one the API refuses - and discovering that four
  * calls later, as an opaque 401 from whichever endpoint got there first, is how a "sign in again"
  * became a stack trace.
  */

package/src/auth/github.js

@@ -26,7 +26,7 @@ export async function githubCredential({
   if (stored != null) return stored;
 
   // No scopes. A GitHub App's permissions are fixed on the app and granted when the writer installs
-  // it, so there is nothing to negotiate — and nothing to warn them about, which is why the broad
+  // it, so there is nothing to negotiate - and nothing to warn them about, which is why the broad
   // "read/write on every repository you can access" notice is gone.
   const authorization = await post(DEVICE_CODE_URL, { client_id: clientId }, 'GitHub sign-in');
   terminal.step('Sign in to GitHub');
@@ -37,7 +37,7 @@ export async function githubCredential({
   await writeCredential(target, {
     accessToken: token.access_token,
     // The app expires user tokens after eight hours and issues a refresh token with each. Exchanging
-    // one needs the app's client secret, which a published CLI cannot hold — so it is kept for the
+    // one needs the app's client secret, which a published CLI cannot hold - so it is kept for the
     // API-side refresh, and until that exists an expired credential asks for one sign-in rather
     // than failing as an unexplained 401 somewhere deeper.
     ...(token.expires_in ? { expiresAt: new Date(now() + token.expires_in * 1000).toISOString() } : {}),

package/src/auth/store.js

@@ -8,7 +8,7 @@ import path from 'node:path';
  * Two rules matter more than the storage itself, both learned the hard way:
  *
  * A credential is only valid if the server still accepts it. v0 checked expiry and nothing else, so
- * a token the API had already decided to refuse — it stopped issuing a claim these carried — was
+ * a token the API had already decided to refuse - it stopped issuing a claim these carried - was
  * handed out for weeks, and every command failed as an unexplained 401 several calls deep.
  *
  * A credential whose shape has changed is not upgradable in place. Bumping `schemaVersion` and

package/src/cli/invocation.js

@@ -0,0 +1,9 @@
+export const CLI_INVOCATION = 'npx --yes @rathnasgala/cli@latest';
+
+export function cliCommand(argumentsText = '') {
+  return argumentsText === '' ? CLI_INVOCATION : `${CLI_INVOCATION} ${argumentsText}`;
+}
+
+export function shellArgument(value) {
+  return /^[A-Za-z0-9_./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}

package/src/cli/terminal.js

@@ -7,7 +7,7 @@ import { spawn } from 'node:child_process';
  * v0 wrote to stdout from a dozen modules with no shared shape, so a scaffold emitted raw git
  * output, bare status codes and half-sentences in whatever order they happened to occur. The
  * failure mode that cost the most was subtler: prompts and browser launches were decided
- * separately in each module, so behaviour with no terminal attached varied by code path — some
+ * separately in each module, so behaviour with no terminal attached varied by code path - some
  * hung, some crashed, some silently skipped.
  *
  * One object, created once, knows whether there is a terminal. Nothing else has to ask.
@@ -50,7 +50,7 @@ export function createTerminal({
     async ask(question, { fallback } = {}) {
       if (!interactive) {
         if (fallback !== undefined) return fallback;
-        throw new Error(`${question} — no terminal to ask; pass it as an option instead`);
+        throw new Error(`${question} - no terminal to ask; pass it as an option instead`);
       }
       const reader = createInterface({ input, output });
       try {

package/src/commands/auth.js

@@ -5,7 +5,7 @@ import { githubCredential } from '../auth/github.js';
  * Signs in to both, and says so.
  *
  * Not a prerequisite the writer has to remember: every command that needs a credential obtains one.
- * This exists for the times they want to do it deliberately — a new machine, a different account,
+ * This exists for the times they want to do it deliberately - a new machine, a different account,
  * or after a token has expired.
  */
 export async function auth({ terminal, options }) {
@@ -13,8 +13,8 @@ export async function auth({ terminal, options }) {
   const github = await githubCredential({ terminal });
 
   terminal.blank();
-  terminal.done(`Gala   — valid until ${new Date(gala.expiresAt).toLocaleString()}`);
+  terminal.done(`Gala   - valid until ${new Date(gala.expiresAt).toLocaleString()}`);
   terminal.done(github.expiresAt
-    ? `GitHub — valid until ${new Date(github.expiresAt).toLocaleString()}`
-    : 'GitHub — signed in');
+    ? `GitHub - valid until ${new Date(github.expiresAt).toLocaleString()}`
+    : 'GitHub - signed in');
 }

package/src/commands/doctor.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { galaApi } from '../api/gala.js';
 import { galaCredential } from '../auth/gala.js';
 import { githubCredential } from '../auth/github.js';
+import { cliCommand } from '../cli/invocation.js';
 import { createGit } from '../git.js';
 
 /**
@@ -11,7 +12,7 @@ import { createGit } from '../git.js';
  *
  * Every check reports one of three things and never guesses between them: it is fine, it is wrong
  * and here is the fix, or it could not be determined. That third state is the one v0 kept
- * collapsing into the second — an unreachable GitHub reported as "the App is not installed" sent
+ * collapsing into the second - an unreachable GitHub reported as "the App is not installed" sent
  * writers to install something that was already installed, repeatedly.
  */
 export async function doctor({ terminal, options, cwd = process.cwd() }) {
@@ -23,7 +24,7 @@ export async function doctor({ terminal, options, cwd = process.cwd() }) {
     const accepted = await galaApi({ baseUrl: gala.apiBaseUrl, token: gala.accessToken }).accepted();
     return accepted
       ? ok(`valid until ${new Date(gala.expiresAt).toLocaleString()}`)
-      : wrong('the API no longer accepts it', 'gala auth');
+      : wrong('the API no longer accepts it', cliCommand('auth'));
   }));
 
   checks.push(await checkCredential('GitHub sign-in', async () => {
@@ -45,7 +46,7 @@ export async function doctor({ terminal, options, cwd = process.cwd() }) {
     const source = await readFile(workflow, 'utf8');
     const siteId = /site-id:\s*([0-9A-Z]{26})/.exec(source)?.[1];
     return siteId == null
-      ? wrong('no site id — this publication may not be registered', 'gala init')
+      ? wrong('no site id - this publication may not be registered', cliCommand('init'))
       : ok(siteId);
   }, 'the workflow is missing; registration writes it'));
 
@@ -53,16 +54,16 @@ export async function doctor({ terminal, options, cwd = process.cwd() }) {
     const git = createGit({ root });
     const dirty = await git.run(['status', '--porcelain'], { capture: true });
     const ahead = await git.run(['rev-list', '--count', '@{upstream}..HEAD'], { capture: true, allow: [0, 128] });
-    if (dirty !== '') return wrong(`${dirty.split('\n').length} file(s) not recorded`, 'gala publish');
-    if (ahead !== '' && ahead !== '0') return wrong(`${ahead} commit(s) not sent`, 'gala publish');
+    if (dirty !== '') return wrong(`${dirty.split('\n').length} file(s) not recorded`, cliCommand('publish'));
+    if (ahead !== '' && ahead !== '0') return wrong(`${ahead} commit(s) not sent`, cliCommand('publish'));
     return ok('everything is on GitHub');
   }, 'this folder is not a git checkout'));
 
   terminal.blank();
   for (const { name, state, detail, fix } of checks) {
-    if (state === 'ok') terminal.done(`${name} — ${detail}`);
-    else if (state === 'wrong') terminal.fail(`${name} — ${detail}`);
-    else terminal.step(`${name} — could not be determined: ${detail}`);
+    if (state === 'ok') terminal.done(`${name} - ${detail}`);
+    else if (state === 'wrong') terminal.fail(`${name} - ${detail}`);
+    else terminal.step(`${name} - could not be determined: ${detail}`);
     if (fix) terminal.note(fix);
   }
 

package/src/commands/domain.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { galaApi } from '../api/gala.js';
 import { galaCredential } from '../auth/gala.js';
 import { UsageError } from '../cli/args.js';
+import { cliCommand } from '../cli/invocation.js';
 import { customDomain } from '../domain.js';
 import { readPublication } from '../publication.js';
 
@@ -16,7 +17,7 @@ export async function domain({ terminal, options, cwd = process.cwd() }) {
   }
   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]');
+    throw new UsageError(`Use: ${cliCommand('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`);
@@ -45,7 +46,7 @@ export async function domain({ terminal, options, cwd = process.cwd() }) {
       pathPrefix: '/',
     });
     terminal.done(`Reserved ${checked.host}`);
-    terminal.note('Verify it in the repository owner’s GitHub account, then run: gala domain check');
+    terminal.note(`Verify it in the repository owner’s GitHub account, then run: ${cliCommand('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;
   }
@@ -83,7 +84,7 @@ export async function domain({ terminal, options, cwd = process.cwd() }) {
       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');
+      terminal.note(`After DNS propagates, run: ${cliCommand('domain check')}`);
       return configured;
     }
     const committed = await api.commitTopologyChange(publication.siteId, pending.changeId);
@@ -119,6 +120,6 @@ function dnsInstruction(host, target) {
 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.');
+  if (pending.state === 'PREPARED') terminal.note(`Next: verify ownership, then run ${cliCommand('domain check')}.`);
+  else terminal.note(`Next: configure DNS, then run ${cliCommand('domain check')}.`);
 }

package/src/commands/init.js

@@ -7,6 +7,7 @@ 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 { CLI_INVOCATION, shellArgument } from '../cli/invocation.js';
 import { customDomain } from '../domain.js';
 
 /**
@@ -21,7 +22,7 @@ import { customDomain } from '../domain.js';
  *     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
+ *     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.
@@ -119,7 +120,7 @@ export async function init({ terminal, options, cwd = process.cwd() }) {
  * 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
+ * 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.
@@ -151,7 +152,7 @@ async function createPublication({ terminal, api, capability, name, github, inst
     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.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')) {
@@ -217,7 +218,7 @@ export function installationUrl(installationId, owner, selfLogin) {
 
 /**
  * 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
+ * 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 } = {}) {
@@ -233,7 +234,7 @@ async function publicationName({ terminal, explicitName, 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`);
+    throw new UsageError(`"${answer}" cannot be a repository name - use letters, numbers and hyphens`);
   }
   return name;
 }
@@ -291,7 +292,7 @@ export function reportCreatedPublication({
   directoryLabel,
   hasDomainChange = false
 }) {
-  const run = 'npx --yes @rathnasgala/cli@latest';
+  const run = CLI_INVOCATION;
   terminal.done(`Created ${owner}/${name}`);
   terminal.note('The first deployment is running in GitHub Actions. The public site is not live yet.');
   terminal.note(`track it at https://github.com/${owner}/${name}/actions`);
@@ -313,10 +314,6 @@ export function reportCreatedPublication({
   terminal.note('lists every available command');
 }
 
-function shellArgument(value) {
-  return /^[A-Za-z0-9_./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
-}
-
 function idempotencyKey(owner, name) {
   return `init-${createHash('sha256').update(`${owner.toLowerCase()}/${name.toLowerCase()}`).digest('hex')}`;
 }

package/src/commands/new.js

@@ -11,6 +11,7 @@ import {
 import { stringify } from 'yaml';
 
 import { UsageError } from '../cli/args.js';
+import { cliCommand } from '../cli/invocation.js';
 import { postUrl, readPublication } from '../publication.js';
 
 /**
@@ -54,7 +55,7 @@ export async function createPost({ terminal, options, cwd = process.cwd(), now =
   if (address != null) terminal.note(`will appear at ${address}`);
 
   terminal.blank();
-  terminal.note('write below the second --- line, then: npx --yes @rathnasgala/cli@latest preview');
+  terminal.note(`write below the second --- line, then: ${cliCommand('preview')}`);
   return { file, metadata };
 }
 

package/src/commands/preview.js

@@ -9,7 +9,7 @@ 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
+ * 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
@@ -24,21 +24,23 @@ export async function preview({
   const today = options.value('today');
 
   terminal.step('Checking content');
-  await checkContent({ terminal, root, today, ...(regenerate == null ? {} : { regenerate }) });
+  await checkContent({
+    terminal, root, today, preview: true, ...(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');
+    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.');
+      throw new Error('Gala installed the publication dependencies, but the preview tool is still missing. Restore the managed package.json and package-lock.json files, then run preview again.');
     }
     terminal.done('Installed');
   }
 
   const publication = await readPublication(root);
-  terminal.step('Starting the preview — stop it with Ctrl-C');
+  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();
 
@@ -50,12 +52,17 @@ export async function preview({
   });
 
   return new Promise((resolve, reject) => {
-    child.once('error', reject);
+    child.once('error', (error) => {
+      reject(new Error(`The preview could not start: ${error.message}`));
+    });
     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}`));
+      else if (signal) {
+        reject(new Error(`The preview process was stopped by ${signal}. Review the build output above, correct the reported problem, and run preview again.`));
+      } else {
+        reject(new Error(`The preview build failed with exit code ${code}. Review the build output above, correct the reported problem, and run preview again.`));
+      }
     });
   });
 }
@@ -84,7 +91,7 @@ function install(root, spawnProcess) {
         resolve();
         return;
       }
-      const failure = new Error('Installing the preview tooling failed');
+      const failure = new Error('Gala could not install the preview dependencies. The package-manager output below contains the cause.');
       failure.detail = said.trim();
       reject(failure);
     });

package/src/commands/prism.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { galaApi } from '../api/gala.js';
 import { galaCredential } from '../auth/gala.js';
 import { UsageError } from '../cli/args.js';
+import { cliCommand } from '../cli/invocation.js';
 import { createGit } from '../git.js';
 import { readPublication } from '../publication.js';
 
@@ -25,7 +26,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   const [action = 'status', ...args] = options.positional;
 
   if (action === 'status') {
-    requireArgs(args, 0, 'gala prism status');
+    requireArgs(args, 0, cliCommand('prism status'));
     const state = await api.json(`/v1/sites/${publication.siteId}/prism`, { action: 'Prism status' });
     terminal.result(`Prism ${state.publishedMode}`);
     terminal.note(`Mode: requested ${state.requestedMode}; published ${state.publishedMode}`);
@@ -39,7 +40,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   const expectedRepositoryHeadSha = inventory.headSha;
 
   if (action === 'mode') {
-    requireArgs(args, 1, 'gala prism mode <off|presentation-only|manual|assisted>');
+    requireArgs(args, 1, cliCommand('prism mode <off|presentation-only|manual|assisted>'));
     const mode = MODES.get(args[0]);
     if (!mode) throw new UsageError('Prism mode must be off, presentation-only, manual, or assisted.');
     if (mode === 'OFF' || mode === 'PRESENTATION_ONLY') await confirm(terminal, options, `Change Prism mode to ${args[0]}?`);
@@ -52,7 +53,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   if (action === 'link-policy') {
     const [scope, target, value] = args;
     if (scope === 'site') {
-      requireArgs(args, 2, 'gala prism link-policy site <nofollow|follow>');
+      requireArgs(args, 2, cliCommand('prism link-policy site <nofollow|follow>'));
       const policy = policyValue(target);
       const result = await mutate(api, `/v1/sites/${publication.siteId}/prism`, 'PUT', {
         configurationLinkPolicy: policy, expectedRepositoryHeadSha,
@@ -60,7 +61,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
       return settleMutation(api, terminal, publication, result);
     }
     if (scope === 'work') {
-      requireArgs(args, 3, 'gala prism link-policy work <slug> <inherit|nofollow|follow>');
+      requireArgs(args, 3, cliCommand('prism link-policy work <slug> <inherit|nofollow|follow>'));
       const post = resolvePost(inventory, target, options.value('language'), publication.defaultLanguage);
       if (value === 'inherit') {
         const result = await mutate(api,
@@ -76,11 +77,14 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
         }, 'Prism work link policy');
       return settleMutation(api, terminal, publication, result);
     }
-    throw new UsageError('Use: gala prism link-policy site <nofollow|follow> or work <slug> <inherit|nofollow|follow>');
+    throw new UsageError(
+      `Use: ${cliCommand('prism link-policy site <nofollow|follow>')} or `
+        + cliCommand('prism link-policy work <slug> <inherit|nofollow|follow>')
+    );
   }
 
   if (action === 'list') {
-    requireArgs(args, 1, 'gala prism list <slug> [--language en]');
+    requireArgs(args, 1, cliCommand('prism list <slug> [--language en]'));
     const post = resolvePost(inventory, args[0], options.value('language'), publication.defaultLanguage);
     const result = await configurations(api, publication.siteId, post);
     terminal.result(`${result.configurations.length} configuration${result.configurations.length === 1 ? '' : 's'}`);
@@ -91,7 +95,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   }
 
   if (action === 'create') {
-    requireArgs(args, 1, 'gala prism create <slug> --language en --depth brief --intent orientation');
+    requireArgs(args, 1, cliCommand('prism create <slug> --language en --depth brief --intent orientation'));
     const post = resolvePost(inventory, args[0], options.value('language'), publication.defaultLanguage);
     const current = await configurations(api, publication.siteId, post);
     const result = await mutate(api,
@@ -108,7 +112,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   }
 
   if (!['edit', 'generate', 'submit', 'approve', 'reject', 'revoke'].includes(action)) {
-    throw new UsageError('Unknown Prism action. Run gala prism --help.');
+    throw new UsageError(`Unknown Prism action. Run ${cliCommand('prism --help')}.`);
   }
 
   const configurationId = args[0];
@@ -119,7 +123,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   const base = `/v1/sites/${publication.siteId}/articles/${post.articleId}/configurations/${configurationId}`;
 
   if (action === 'edit') {
-    requireArgs(args, 1, 'gala prism edit <configuration-id> --file proposal.md');
+    requireArgs(args, 1, cliCommand('prism edit <configuration-id> --file proposal.md'));
     const filename = options.value('file');
     if (!filename) throw new UsageError('Prism edit needs --file proposal.md.');
     const markdown = await readFile(path.resolve(root, filename), 'utf8');
@@ -132,7 +136,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   }
 
   if (action === 'generate') {
-    requireArgs(args, 1, 'gala prism generate <configuration-id>');
+    requireArgs(args, 1, cliCommand('prism generate <configuration-id>'));
     const result = await mutate(api, `${base}/generation-jobs`, 'POST', {
       expectedSourceContentHash: collection.sourceRevisionHash,
       hashContract: collection.hashContract,
@@ -146,7 +150,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
     throw new UsageError(`${action} needs a revision ID when there is no working revision.`);
   }
   if (action === 'submit') {
-    if (args.length > 2) throw new UsageError('Use: gala prism submit <configuration-id> [revision-id]');
+    if (args.length > 2) throw new UsageError(`Use: ${cliCommand('prism submit <configuration-id> [revision-id]')}`);
     if (revisionId !== configuration.workingRevision?.revisionId) {
       throw new UsageError('Only the current working revision can be submitted. Refresh the configuration and try again.');
     }
@@ -165,7 +169,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
 
   const reason = options.value('reason');
   if (action === 'approve') {
-    if (args.length > 2) throw new UsageError('Use: gala prism approve <configuration-id> [revision-id] [--yes]');
+    if (args.length > 2) throw new UsageError(`Use: ${cliCommand('prism approve <configuration-id> [revision-id] [--yes]')}`);
     if (revisionId !== configuration.workingRevision?.revisionId) {
       throw new UsageError('Only the current working revision can be approved. Refresh the configuration and try again.');
     }
@@ -292,7 +296,7 @@ async function settleMutation(api, terminal, publication, result) {
     throw new UsageError(`Repository update failed (${state.errorCode ?? 'unknown error'}). Run the command again after correcting the cause.`);
   }
   if (state.status !== 'COMMITTED') {
-    throw new UsageError('Repository update did not finish before the 31-minute tracking deadline. Check gala prism status before retrying.');
+    throw new UsageError(`Repository update did not finish before the 31-minute tracking deadline. Check ${cliCommand('prism status')} before retrying.`);
   }
   if (!state.publicationAttemptSha) {
     terminal.result('Repository updated. No publication attempt was returned.');

package/src/commands/publish.js

@@ -8,16 +8,15 @@ 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
+ * 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.
+ * anything - catching up is the normal condition, not a race fix. It has to happen *before*
+ * validation, because publish validation assigns a content id to any post still missing one. Local
+ * preview is deliberately read-only and can therefore never create a competing ID before this sync.
  *
  * 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.

package/src/commands/upgrade.js

@@ -4,6 +4,8 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { x as extractTar } from 'tar';
 
+import { cliCommand } from '../cli/invocation.js';
+
 const PACKAGE = '@rathnasgala/theme';
 const REGISTRY = 'https://registry.npmjs.org';
 const PROTECTED = ['.git/', 'content/', 'custom.css', 'site.config.yml'];
@@ -81,7 +83,7 @@ async function assertNoManagedDrift(root, installed) {
   for (const [managed, expected] of Object.entries(installed.files)) {
     const file = path.join(root, managed);
     if (!await exists(file) || (await lstat(file)).isSymbolicLink() || sha256(await readFile(file)) !== expected) {
-      throw new Error(`${managed} has local changes; restore it with gala doctor before upgrading`);
+      throw new Error(`${managed} has local changes; restore it with ${cliCommand('doctor')} before upgrading`);
     }
   }
 }
@@ -168,6 +170,6 @@ export async function upgrade({ terminal, options, cwd = process.cwd(), fetchImp
     await rm(unpacked.temporary, { recursive: true, force: true });
   }
   terminal.done(`Upgraded managed theme to ${release.version}`);
-  terminal.note('Run gala preview, then gala publish when the result is approved.');
+  terminal.note(`Run ${cliCommand('preview')}, then ${cliCommand('publish')} when the result is approved.`);
   return { changed: true, version: release.version };
 }

package/src/commands-manifest.js

@@ -7,6 +7,7 @@ import { preview } from './commands/preview.js';
 import { publish } from './commands/publish.js';
 import { prism } from './commands/prism.js';
 import { upgrade } from './commands/upgrade.js';
+import { cliCommand } from './cli/invocation.js';
 
 /**
  * Commands in the order a writer meets them.
@@ -17,7 +18,7 @@ import { upgrade } from './commands/upgrade.js';
  * 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
+ * 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
@@ -31,19 +32,19 @@ export const COMMANDS = {
   },
   init: {
     summary: 'Create a publication in an empty directory',
-    usage: 'gala init [directory] [--name my-notes] [--domain blog.example.com]',
+    usage: cliCommand('init [directory] [--name my-notes] [--domain blog.example.com]'),
     flags: ['name', 'domain', 'api-base-url'],
     run: init
   },
   domain: {
     summary: 'Inspect or change this publication’s custom domain',
-    usage: 'gala domain [status|set <hostname>|check|cancel|remove] [--root path]',
+    usage: cliCommand('domain [status|set <hostname>|check|cancel|remove] [--root path]'),
     flags: ['root', 'api-base-url'],
     run: domain
   },
   new: {
     summary: 'Start a post',
-    usage: 'gala new "A durable idea" [--language en]',
+    usage: cliCommand('new "A durable idea" [--language en]'),
     flags: ['root', 'language', 'today'],
     run: createPost
   },
@@ -60,14 +61,14 @@ export const COMMANDS = {
   },
   prism: {
     summary: 'Manage author-approved Prism configurations',
-    usage: 'gala prism <status|mode|link-policy|list|create|edit|generate|submit|approve|reject|revoke> [arguments]',
+    usage: cliCommand('prism <status|mode|link-policy|list|create|edit|generate|submit|approve|reject|revoke> [arguments]'),
     flags: ['root', 'api-base-url', 'language', 'depth', 'intent', 'modality', 'file', 'reason'],
     switches: ['yes'],
     run: prism
   },
   upgrade: {
     summary: 'Inspect and apply a verified managed-theme update',
-    usage: 'gala upgrade [--channel latest|next] [--yes]',
+    usage: cliCommand('upgrade [--channel latest|next] [--yes]'),
     flags: ['root', 'channel'],
     switches: ['yes'],
     run: upgrade

package/src/content.js

@@ -1,10 +1,20 @@
+import path from 'node:path';
+
 import { regenerateBuildManifest } from '@rathnasgala/content-validation';
 
+function shownPath(root, file) {
+  if (!path.isAbsolute(file)) return file;
+  const relative = path.relative(root, file);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)
+    ? relative
+    : file;
+}
+
 /**
  * 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.
+ * 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.
  *
@@ -12,20 +22,32 @@ import { regenerateBuildManifest } from '@rathnasgala/content-validation';
  * 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 });
+export async function checkContent({
+  terminal, root, today, preview = false, regenerate = regenerateBuildManifest
+}) {
+  const { results } = await regenerate({ root, today, preview });
   const failed = results.filter(({ errors }) => errors.length > 0);
 
   for (const result of results) {
-    for (const warning of result.warnings ?? []) terminal.note(`${result.file}: ${warning}`);
+    for (const warning of result.warnings ?? []) {
+      terminal.note(`${shownPath(root, 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();
+  const details = [];
   for (const result of failed) {
-    for (const error of result.errors) terminal.fail(`${result.file}: ${error}`);
+    details.push(shownPath(root, result.file));
+    for (const error of result.errors) details.push(`  - ${error}`);
   }
-  throw new Error(`${failed.length} post${failed.length === 1 ? '' : 's'} cannot be published yet`);
+  const problemCount = failed.reduce((count, result) => count + result.errors.length, 0);
+  details.push(`Fix ${problemCount === 1 ? 'this problem' : 'these problems'}, then run the command again.`);
+  const failure = new Error(
+    `Content check failed: ${problemCount} problem${problemCount === 1 ? '' : 's'} `
+    + `in ${failed.length} post${failed.length === 1 ? '' : 's'}`
+  );
+  failure.detail = details.join('\n');
+  throw failure;
 }

package/src/git.js

@@ -8,7 +8,7 @@ import path from 'node:path';
  * 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.
+ * 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`.
@@ -100,11 +100,9 @@ export function createGit({ root, token, spawnProcess = spawn } = {}) {
      * 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.
+     * dirty tree. Doing it the other way round - record first, then rebase - lets the publication
+     * workflow and the local publish independently update the same file. Taking the remote first
+     * makes the post-publish validation pass the sole local writer of any missing content ID.
      */
     async takeRemote() {
       const branch = await git.branch();

package/src/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { UsageError, parseArguments } from './cli/args.js';
+import { CLI_INVOCATION, cliCommand } from './cli/invocation.js';
 import { createTerminal } from './cli/terminal.js';
 import { COMMANDS } from './commands-manifest.js';
 
@@ -20,7 +21,7 @@ if (command == null) {
 }
 
 if (argv.includes('--help') || argv.includes('-h')) {
-  process.stdout.write(`\n  ${command.usage ?? `gala ${name}`}\n  ${command.summary}\n\n`);
+  process.stdout.write(`\n  ${command.usage ?? cliCommand(name)}\n  ${command.summary}\n\n`);
   process.exit(0);
 }
 
@@ -56,5 +57,6 @@ 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`);
+  process.stdout.write(`\n  ${CLI_INVOCATION} <command>\n\n${lines}\n\n`
+    + `    Run ${CLI_INVOCATION} <command> --help for details.\n\n`);
 }

package/src/publication.js

@@ -8,8 +8,8 @@ import { parse } from 'yaml';
  *
  * 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
+ * `{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) {