@rathnasgala/cli 0.0.21 → 1.0.0

package/README.md

@@ -1,275 +1,129 @@
 # Gala CLI
 
-Create, validate, preview, publish, and maintain a GitHub-backed Gala publication from your terminal.
-
-The quick start below begins with the required accounts and tools and does not assume a global CLI installation.
+Create a publication, write posts, preview them, and publish — from your terminal.
 
 ## Requirements
 
 - [Git](https://git-scm.com/downloads)
-- [Node.js 24](https://nodejs.org/en/download) recommended; the CLI package supports Node.js 18 or newer
+- [Node.js 20](https://nodejs.org/en/download) or newer
 - A [GitHub account](https://github.com/signup)
-- The [Gala GitHub App](https://github.com/apps/gala67-app/installations/new) — `scaffold` walks you through installing it if it is not already
 
-Check your local tools:
+Nothing to install. Every command runs through `npx`.
 
-```console
-node --version
-npm --version
-git --version
-```
+## Start a publication
 
-You should see something like this:
-```console
-v22.18.0
-10.9.3
-git version 2.50.1 (Apple Git-155)
-```
-
-## Quick start
-
-One command, run inside an empty folder named after the publication you want:
+Make a folder named after the publication you want, and run one command inside it:
 
 ```console
 mkdir field-notes && cd field-notes
-npx --yes @rathnasgala/cli@latest scaffold --target ./ --mode build-and-deploy
-```
-
-That single command does all of the following, and asks only for what it cannot work out:
-
-1. **Signs you in to Gala** if no valid token is stored, showing a code to enter in the browser.
-2. **Signs you in to GitHub** the same way, requesting `repo` to create the publication and install
-   its Actions secret, and `workflow` for the initial scaffold. Ordinary publishing needs neither.
-3. **Reads your GitHub account** from that token, so there is no username to type.
-4. **Finds the Gala GitHub App installation** for your account. If the App is not installed yet it
-   prints the installation page, waits while you install it, and carries on — the installation ID
-   is never something you have to read out of a URL.
-5. **Names the publication** after the folder you are standing in.
-6. **Creates the repository** from the site template, registers it, installs its one-time secret,
-   writes the publication workflow, commits, and enables GitHub Pages.
-
-Both sign-ins are skipped when a valid credential is already stored, so re-running is cheap.
-
-After scaffolding succeeds, open [GitHub App settings](https://github.com/settings/installations)
-and restrict the App to the publication repository if you installed it against all of them.
-
-### Write, preview, and publish
-
-```console
-npx --yes @rathnasgala/cli@latest new --title "My first post" --language en
-npx --yes @rathnasgala/cli@latest preview
-npx --yes @rathnasgala/cli@latest publish
-```
-
-`new` prints the Markdown file it created. Write below the second `---` line, save the file,
-preview it locally, then publish it through GitHub.
-
-### Overriding what scaffold works out
-
-Every derived value is still an explicit flag, for the cases where the default is wrong — a
-publication owned by an organisation, a folder named differently from the repository, or more than
-one App installation on the account:
-
-```console
-npx --yes @rathnasgala/cli@latest scaffold \
-  --owner YOUR_GITHUB_USERNAME \
-  --repository YOUR_REPOSITORY_NAME \
-  --target ./YOUR_REPOSITORY_NAME \
-  --installation-id YOUR_INSTALLATION_ID \
-  --mode build-and-deploy
-```
-
-`--repository` is otherwise taken from `--target`, then from `--site-name`, and only then asked
-for. Outside a terminal — in CI — nothing is ever prompted for: a value that cannot be derived is
-an error, so an automated run fails fast instead of waiting for an answer that will not come.
-
-## Command reference
-
-Run commands through `npx` without installing a global package:
-
-```console
-npx --yes @rathnasgala/cli@latest COMMAND [options]
+npx --yes @rathnasgala/cli@latest init --here
 ```
 
-Inside the table below, `gala` is shorthand for that prefix.
-
-| Command | Purpose | Common options |
-| --- | --- | --- |
-| `gala auth` | Authenticate the author with Gala | `--api-base-url URL` for a non-production API |
-| `gala auth github` | Authenticate the CLI with GitHub | Browser device flow; requests `repo workflow` |
-| `gala scaffold` | Sign in if needed, then create and register a publication | All derived; override with `--owner`, `--repository`, `--target`, `--installation-id`, `--mode` |
-| `gala configure` | Update author-owned site and design settings | `--root`, plus the configuration options below |
-| `gala new` | Create a Markdown post variant | `--root`, `--title`, `--language`, `--today` |
-| `gala validate` | Validate repository content without publishing | optional root path, `--today` |
-| `gala preview` | Validate and run the local Eleventy preview | `--root`, `--today` |
-| `gala publish` | Validate, commit, and push publication changes | `--root`, `--today`, `--force` |
-| `gala doctor` | Report managed-framework drift and publication-state validity | optional root path; `--fix --source TRUSTED_ROOT` |
-| `gala hook install` | Install the pre-push validation hook | `--root` |
-| `gala refresh` | Refresh and commit the engagement snapshot | `--root` |
-| `gala upgrade` | Verify and install an exact theme-package release | `--root`, `--channel`, `--yes` |
-| `gala topology` | Switch canonical origin/path topology transactionally | `--root`, `--owner`, `--repository`, `--canonical-base-url`, `--path-prefix` |
-| `gala entitlement` | Retrieve and commit the current paid attribution artifact | `--root` |
-| `gala workflow` | Write the reusable GitHub Actions workflow | `--root`, `--site-id`, `--timezone`, `--action-ref`, `--default-branch`, `--mode` |
-| `gala record-deployment` | Record state after a successful deployment | `--root`, `--today`, `--commit-sha` |
-
-### Scaffold and configure options
-
-The same author-owned options are accepted by `scaffold` and `configure`:
-
-```text
---site-name
---author
---language
---timezone
---theme
---layout
---palette
---typography
---spacing
---radius
---density
---motion
---componentStyle
---share-target       repeatable
---social-profile     repeatable
-```
+It signs you in to Gala and to GitHub if you are not already, creates the repository, registers the
+publication, and leaves a working checkout in the folder. When it finishes it prints the address
+your publication will live at.
 
-Use only identities supported by the installed theme package. Validation rejects unavailable layout, palette, and theme identities instead of silently substituting another design.
+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
+unavoidable. Everything else is automatic.
 
-### Scaffold an existing empty repository
-
-Use this only when the exact GitHub repository already exists and has no branches or content:
+## Write
 
 ```console
-npx --yes @rathnasgala/cli@latest scaffold \
-  --repository YOUR_REPOSITORY_NAME \
-  --empty-existing-repository
+npx --yes @rathnasgala/cli@latest new "The places we return to"
 ```
 
-### Resume interrupted scaffolding
-
-The target must already be a checkout whose HTTPS origin exactly matches the requested repository:
+This creates the Markdown file and tells you the address the post will appear at. Write below the
+second `---` line.
 
 ```console
-npx --yes @rathnasgala/cli@latest scaffold \
-  --repository YOUR_REPOSITORY_NAME \
-  --target ./YOUR_REPOSITORY_NAME \
-  --resume
+npx --yes @rathnasgala/cli@latest preview
 ```
 
-Scaffolding is designed to converge after partial failure. It will not adopt a non-empty unrelated repository.
-
-### Build without deploying
+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
+a moment. Stop it with Ctrl-C.
 
 ```console
-npx --yes @rathnasgala/cli@latest scaffold ... --mode build-only
+npx --yes @rathnasgala/cli@latest publish
 ```
 
-`build-only` writes and validates the site but does not provision GitHub Pages. `build-and-deploy` is the default.
-
-## Everyday workflow
+Checks your content, records it, and sends it to GitHub. GitHub builds and deploys from there; the
+site updates a minute or two later.
 
-Create another post:
+## When something is wrong
 
 ```console
-npx --yes @rathnasgala/cli@latest new --title "A durable idea" --language en
+npx --yes @rathnasgala/cli@latest doctor
 ```
 
-Validate without running a preview server:
+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.
 
-```console
-npx --yes @rathnasgala/cli@latest validate
-```
+## Commands
 
-Preview locally:
+Run any command with `--help`.
 
-```console
-npx --yes @rathnasgala/cli@latest preview
-```
+| Command | What it does | Options |
+| --- | --- | --- |
+| `init` | Create a publication and clone it here | `--name`, `--here` |
+| `new` | Start a post | `--language`, `--root`, `--today` |
+| `preview` | Build and serve the publication locally | `--root`, `--today` |
+| `publish` | Check, record and send your work to GitHub | `--root`, `--today`, `--skip-checks` |
+| `doctor` | Check a publication and say what is wrong | `--root` |
+| `auth` | Sign in to Gala and GitHub | — |
 
-Publish:
+`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.
 
-```console
-npx --yes @rathnasgala/cli@latest publish
-```
+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
+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.
 
-Check managed files and recorded publication state:
+## Access
 
-```console
-npx --yes @rathnasgala/cli@latest doctor
-```
+The CLI signs in as the **Gala GitHub App**. It reaches only the repositories you have given that
+App, and never asks for the broad `repo` scope, which would have meant read and write access to
+every repository you can see.
 
-## Security and ownership
+Credentials are stored outside the publication, in your operating system's application-config
+directory, with private file permissions. Your GitHub sign-in expires after eight hours and the CLI
+asks you to sign in again rather than quietly using a credential the server will refuse.
 
-- Your repository remains the canonical source for publication content and configuration.
-- Gala credentials and GitHub OAuth credentials are stored outside the repository.
-- Credential directories are created with private permissions; credential files use mode `0600` on operating systems that support POSIX modes.
-- The site signing secret is returned once by the API and sealed directly into GitHub Actions secrets.
-- Do not copy credential files into the repository, dotfiles, cloud-sync folders, or `/tmp`.
-- The generated workflow pins the public Gala Action contract; managed framework files are integrity-checked before repair or upgrade.
+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.
 
 ## Troubleshooting
 
-### `GitHub authentication is missing`
+### `GitHub authentication expired`
 
-Run:
-
-```console
-npx --yes @rathnasgala/cli@latest auth github
-```
-
-### Gala authentication expired
-
-Gala author tokens expire and do not use a refresh token. Run:
+Sign in again:
 
 ```console
 npx --yes @rathnasgala/cli@latest auth
 ```
 
-### `The Gala GitHub App is not installed on YOUR_ACCOUNT`
-
-`scaffold` could not find an installation covering that account. At a terminal it prints the
-installation page and waits; in CI it stops, because there is nobody to install it. Install the App
-at [the installation page](https://github.com/apps/gala67-app/installations/new) and run `scaffold`
-again, or pass `--installation-id` explicitly.
-
-### The App cannot access the new repository
-
-Open [GitHub App settings](https://github.com/settings/installations) and add the publication repository to the Gala installation. The platform verifies access to the exact repository; the existence of an installation alone is insufficient.
+### Gala cannot reach the repository
 
-### The target folder already exists
+The Gala GitHub App is installed but has not been given this repository. The command prints a link
+to the installation that needs it; add the one repository and continue. Nothing else needs granting.
 
-Do not delete or overwrite it blindly. Use `--resume` only when it is the intended repository checkout. Use `--empty-existing-repository` only when the remote GitHub repository is genuinely empty.
+### A post is not appearing
 
-### Validation refuses a post
+Run `doctor`. The most common cause is work written but never sent, which it reports along with the
+command to fix it.
 
-The error includes the source file and violated rule. Correct the file and run:
+### Something failed and the message was not enough
 
 ```console
-npx --yes @rathnasgala/cli@latest validate
+GALA_DEBUG=1 npx --yes @rathnasgala/cli@latest publish
 ```
 
-Do not use `publish --force` as a routine bypass. It skips content validation but does not force-push Git history.
-
-### Managed files have drifted
-
-Inspect first:
-
-```console
-npx --yes @rathnasgala/cli@latest doctor
-```
-
-Repair requires a trusted, hash-verified theme source:
-
-```console
-npx --yes @rathnasgala/cli@latest doctor --fix --source PATH_TO_TRUSTED_THEME
-```
+Prints the full stack. Without it, failures are one line you can act on.
 
 ## Package and source
 
-- npm: [`@rathnasgala/cli`](https://www.npmjs.com/package/@rathnasgala/cli)
-- source: [`rathnasgala/cli`](https://github.com/rathnasgala/cli)
-
-## License
-
-The repository does not currently declare a license. Copyright remains with its owner unless and until a license is added.
+Published as [`@rathnasgala/cli`](https://www.npmjs.com/package/@rathnasgala/cli). Source at
+[rathnasgala/cli](https://github.com/rathnasgala/cli).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala/cli",
-  "version": "0.0.21",
+  "version": "1.0.0",
   "type": "module",
   "files": [
     "src"
@@ -13,13 +13,13 @@
     "gala": "src/index.js"
   },
   "scripts": {
-    "test": "node --test",
+    "test": "node --test test/*.test.js",
     "lint": "node scripts/lint.js",
     "preversion": "npm test && npm run lint",
     "push": "node scripts/push.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "repository": {
     "type": "git",

package/src/api/gala.js

@@ -0,0 +1,126 @@
+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.
+ */
+export const DEFAULT_API_BASE_URL = 'https://api.gala67.com';
+
+export function galaApi({ baseUrl = DEFAULT_API_BASE_URL, token } = {}) {
+  const root = String(baseUrl).replace(/\/$/, '');
+  const authorized = (action, extra = {}) => ({
+    action,
+    ...extra,
+    headers: {
+      accept: 'application/json',
+      ...(token == null ? {} : { authorization: `Bearer ${token}` }),
+      ...extra.headers
+    }
+  });
+
+  return {
+    baseUrl: root,
+
+    /** Cheap authenticated call, used to find out whether a stored credential is still accepted. */
+    async accepted() {
+      try {
+        const response = await fetch(`${root}/v1/me/sites`, {
+          headers: { accept: 'application/json', authorization: `Bearer ${token}` }
+        });
+        // 403 means "not an author yet", which is a stage of the product, not a dead credential.
+        return response.status !== 401;
+      } catch {
+        // Offline is not an answer. Forcing a sign-in the writer does not need is worse than
+        // letting the real call fail with its own error.
+        return true;
+      }
+    },
+
+    /** Exchanges the GitHub token for the short-lived capability the GitHub-scoped routes require. */
+    async githubCapability(githubToken) {
+      const body = await requestJson(`${root}/v1/auth/github/device-authorizations`,
+        authorized('GitHub authorization', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ accessToken: githubToken })
+        }));
+      if (typeof body?.authorization !== 'string') {
+        throw new TypeError('GitHub authorization returned no capability');
+      }
+      return body.authorization;
+    },
+
+    /**
+     * Creates the publication repository, the same call the browser editor makes.
+     *
+     * v0 called GitHub's template endpoint itself: a second implementation with no fallback and no
+     * wait for the App installation to reach the result, which is why repositories the CLI created
+     * never appeared in the web UI.
+     */
+    createPublication({ capability, name }) {
+      return requestJson(`${root}/v1/auth/github/publications`,
+        authorized('Publication creation', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'GitHub-Authorization': capability },
+          body: JSON.stringify({ name })
+        }));
+    },
+
+    registerSite({ capability, idempotencyKey, repositoryOwner, repositoryName, topology, canonicalBaseUrl }) {
+      return requestJson(`${root}/v1/sites`,
+        authorized('Site registration', {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            'GitHub-Authorization': capability,
+            'idempotency-key': idempotencyKey
+          },
+          body: JSON.stringify({ repositoryOwner, repositoryName, topology, canonicalBaseUrl })
+        }));
+    },
+
+    listPublications() {
+      return requestJson(`${root}/v1/me/sites`, authorized('Publication list'));
+    },
+
+    /** Not in the OpenAPI document, though the endpoint exists and is public. */
+    async signInConfiguration() {
+      return requestJson(`${root}/v1/auth/configuration`, { action: 'Sign-in configuration' });
+    },
+
+    /*
+     * Form-encoded, not JSON. These are RFC 8628 device-flow endpoints and the spec declares them
+     * as `application/x-www-form-urlencoded`; sending JSON gets a bare "Authentication is required",
+     * which reads as a credential problem and is nothing of the kind.
+     */
+    async startDeviceAuthorization() {
+      return requestJson(`${root}/v1/auth/device/code`, {
+        action: 'Gala sign-in',
+        method: 'POST',
+        headers: { accept: 'application/json', 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ client_id: 'gala-cli' }).toString()
+      });
+    },
+
+    /** Returns the token, or null while the writer has not finished authorizing. */
+    async pollDeviceAuthorization(deviceCode) {
+      const response = await fetch(`${root}/v1/auth/device/token`, {
+        method: 'POST',
+        headers: { accept: 'application/json', 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+          grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+          device_code: deviceCode,
+          client_id: 'gala-cli'
+        }).toString()
+      });
+      const body = await response.json().catch(() => null);
+      if (response.ok) return body;
+      if (body?.error === 'authorization_pending' || body?.error === 'slow_down') return null;
+      throw new Error(`Gala sign-in failed: ${body?.error_description ?? body?.error ?? response.status}`);
+    },
+
+    request: (path, options) => request(`${root}${path}`, authorized(options?.action ?? path, options))
+  };
+}

package/src/api/github.js

@@ -0,0 +1,63 @@
+import { requestJson } from './http.js';
+
+/**
+ * GitHub, as the Gala App.
+ *
+ * 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
+ * repository the writer can see, which is what `repo` scope meant.
+ */
+const API = 'https://api.github.com';
+const API_VERSION = '2026-03-10';
+
+export function githubApi(token) {
+  const headers = {
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${token}`,
+    'x-github-api-version': API_VERSION
+  };
+
+  return {
+    /** The account behind the token. Works for every token type and needs no permission. */
+    async viewer() {
+      const body = await requestJson(`${API}/user`, { action: 'GitHub account lookup', headers });
+      const login = body?.login;
+      if (typeof login !== 'string' || login === '') {
+        throw new TypeError('GitHub returned an unusable account login');
+      }
+      return login;
+    },
+
+    /**
+     * 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 —
+     * 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.
+     */
+    async hasContent(owner, repository) {
+      const branches = await requestJson(
+        `${API}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/branches?per_page=1`,
+        { action: 'GitHub branch lookup', headers }
+      );
+      return Array.isArray(branches) && branches.length > 0;
+    },
+
+    setVariable(owner, repository, name, value) {
+      const base = `${API}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/actions/variables`;
+      return requestJson(`${base}/${encodeURIComponent(name)}`, {
+        action: 'GitHub repository variable',
+        method: 'PATCH',
+        headers: { ...headers, 'content-type': 'application/json' },
+        body: JSON.stringify({ name, value })
+      }).catch(() => requestJson(base, {
+        action: 'GitHub repository variable',
+        method: 'POST',
+        headers: { ...headers, 'content-type': 'application/json' },
+        body: JSON.stringify({ name, value })
+      }));
+    }
+  };
+}

package/src/api/http.js

@@ -0,0 +1,72 @@
+/**
+ * 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
+ * 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
+ * distinguished, and it cost days.
+ *
+ * Only the response is read here. Request bodies, tokens and secrets never pass through.
+ */
+const MAX_DETAIL = 400;
+
+export class HttpError extends Error {
+  constructor(status, action, detail, code) {
+    super(detail === '' ? `${action} failed with HTTP ${status}` : `${action} failed: ${detail}`);
+    this.name = 'HttpError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export async function request(url, { action, ...options } = {}) {
+  let response;
+  try {
+    response = await fetch(url, options);
+  } catch (unreachable) {
+    throw new Error(`${action} could not reach ${new URL(url).host}: ${unreachable.message}`);
+  }
+  if (response.ok) return response;
+
+  const body = await readBody(response);
+  throw new HttpError(response.status, action, describe(body), body?.code);
+}
+
+export async function requestJson(url, options) {
+  const response = await request(url, options);
+  if (response.status === 204) return undefined;
+  return response.json();
+}
+
+async function readBody(response) {
+  try {
+    const text = await response.text();
+    if (text.trim() === '') return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { raw: text };
+    }
+  } catch {
+    return null;
+  }
+}
+
+function describe(body) {
+  if (body == null) return '';
+  const parts = [];
+  if (typeof body.message === 'string' && body.message.trim() !== '') parts.push(body.message.trim());
+  // GitHub's `errors` array carries the specific field or reason behind a generic message.
+  for (const error of Array.isArray(body.errors) ? body.errors : []) {
+    const reason = typeof error === 'string' ? error : error?.message ?? error?.code;
+    if (typeof reason === 'string' && reason.trim() !== '') parts.push(reason.trim());
+  }
+  if (typeof body.error_description === 'string') parts.push(body.error_description.trim());
+  if (parts.length === 0 && typeof body.code === 'string') parts.push(body.code);
+  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();
+  return detail.length > MAX_DETAIL ? `${detail.slice(0, MAX_DETAIL)}…` : detail;
+}