@rathnasgala/cli 1.1.9 → 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.9",
+  "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/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

@@ -12,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() }) {
@@ -46,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', cliCommand('init'))
+      ? wrong('no site id - this publication may not be registered', cliCommand('init'))
       : ok(siteId);
   }, 'the workflow is missing; registration writes it'));
 
@@ -61,9 +61,9 @@ export async function doctor({ terminal, options, cwd = process.cwd() }) {
 
   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/init.js

@@ -22,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.
@@ -120,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.
@@ -152,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')) {
@@ -218,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 } = {}) {
@@ -234,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;
 }

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

@@ -18,7 +18,7 @@ import { cliCommand } from './cli/invocation.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

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/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) {