@rathnasgala/cli 0.0.16 → 0.0.18

package/package.json

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

package/src/github-empty-repository.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { describeHttpFailure } from './http-failure.js';
 
 const API_VERSION = '2026-03-10';
 
@@ -11,7 +12,7 @@ export async function verifyEmptyRepository({ owner, repository, accessToken, fe
   const response = await fetchImpl(repositoryUrl, {
     headers
   });
-  if (!response.ok) throw new Error(`GitHub repository lookup failed with HTTP ${response.status}`);
+  if (!response.ok) throw new Error(await describeHttpFailure(response, 'GitHub repository lookup'));
   const payload = await response.json();
   if (payload.full_name?.toLowerCase() !== `${owner}/${repository}`.toLowerCase()) {
     throw new TypeError('GitHub returned an unexpected repository');
@@ -21,7 +22,7 @@ export async function verifyEmptyRepository({ owner, repository, accessToken, fe
       ...headers
     }
   });
-  if (!branchesResponse.ok) throw new Error(`GitHub branch lookup failed with HTTP ${branchesResponse.status}`);
+  if (!branchesResponse.ok) throw new Error(await describeHttpFailure(branchesResponse, 'GitHub branch lookup'));
   const branches = await branchesResponse.json();
   if (payload.size !== 0 || !Array.isArray(branches) || branches.length !== 0) {
     throw new Error('Existing repository is not empty; explicit non-empty adoption is not implemented');

package/src/github-identity.js

@@ -1,3 +1,4 @@
+import { describeHttpFailure } from './http-failure.js';
 const GITHUB_API_VERSION = '2026-03-10';
 
 /**
@@ -19,7 +20,7 @@ export async function resolveGithubLogin({ accessToken, fetchImpl = fetch }) {
       'x-github-api-version': GITHUB_API_VERSION
     }
   });
-  if (!response.ok) throw new Error(`GitHub account lookup failed with HTTP ${response.status}`);
+  if (!response.ok) throw new Error(await describeHttpFailure(response, 'GitHub account lookup'));
   const payload = await response.json();
   const login = payload?.login;
   // The same shape `scaffold` demands of `--owner`. Refusing here beats a confusing failure four

package/src/github-pages-provisioning.js

@@ -1,3 +1,4 @@
+import { describeHttpFailure } from './http-failure.js';
 const GITHUB_API_VERSION = '2026-03-10';
 const SEGMENT = /^[A-Za-z0-9_.-]+$/;
 const SHA = /^[0-9a-f]{40}$/;
@@ -19,7 +20,7 @@ function headers(accessToken) {
 }
 
 async function json(response, operation) {
-  if (!response.ok) throw new Error(`GitHub ${operation} failed with HTTP ${response.status}`);
+  if (!response.ok) throw new Error(await describeHttpFailure(response, `GitHub ${operation}`));
   return response.json();
 }
 
@@ -86,7 +87,7 @@ export async function provisionGithubPages({
     return Object.freeze({ created: false, url: configuration.html_url, runUrl: run.html_url });
   }
   if (current.status !== 404) {
-    throw new Error(`GitHub Pages configuration request failed with HTTP ${current.status}`);
+    throw new Error(await describeHttpFailure(current, 'GitHub Pages configuration request'));
   }
   const created = await fetchImpl(`${repositoryUrl}/pages`, {
     method: 'POST', headers: requestHeaders,

package/src/github-repository-variable.js

@@ -1,3 +1,4 @@
+import { describeHttpFailure } from './http-failure.js';
 const GITHUB_API_VERSION = '2026-03-10';
 const OWNER_OR_REPOSITORY = /^[A-Za-z0-9_.-]+$/;
 const VARIABLE_NAME = /^[A-Z_][A-Z0-9_]*$/;
@@ -42,7 +43,7 @@ export async function installRepositoryVariable({
   });
   if (update.ok) return;
   if (update.status !== 404) {
-    throw new Error(`GitHub repository variable update failed with HTTP ${update.status}`);
+    throw new Error(await describeHttpFailure(update, 'GitHub repository variable update'));
   }
   const create = await fetchImpl(baseUrl, {
     method: 'POST',
@@ -50,6 +51,6 @@ export async function installRepositoryVariable({
     body: JSON.stringify({ name: normalizedName, value })
   });
   if (!create.ok) {
-    throw new Error(`GitHub repository variable creation failed with HTTP ${create.status}`);
+    throw new Error(await describeHttpFailure(create, 'GitHub repository variable creation'));
   }
 }

package/src/github-template-repository.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import path from 'node:path';
+import { describeHttpFailure } from './http-failure.js';
 
 const GITHUB_API_VERSION = '2026-03-10';
 const REPOSITORY_IDENTITY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
@@ -57,7 +58,7 @@ export async function generateRepositoryFromTemplate({
     }
   );
   if (response.status !== 201) {
-    throw new Error(`GitHub template generation failed with HTTP ${response.status}`);
+    throw new Error(await describeHttpFailure(response, 'GitHub template generation'));
   }
   const payload = await response.json();
   if (payload == null || Array.isArray(payload) || typeof payload !== 'object') {

package/src/http-failure.js

@@ -0,0 +1,55 @@
+/**
+ * What the server actually said, instead of only what it scored.
+ *
+ * Every failure in this CLI reported `failed with HTTP 403` and discarded the response body. GitHub
+ * puts the reason there and nowhere else — an organisation's OAuth App restrictions, a missing
+ * scope, a rename, a rate limit all arrive as 403 with a sentence explaining which — so the one
+ * fact worth having was the one being thrown away. Diagnosing anything meant guessing between
+ * causes the server had already distinguished.
+ *
+ * Only the response is read. Request bodies, tokens and secrets never pass through here.
+ */
+const MAX_DETAIL = 400;
+
+export async function describeHttpFailure(response, action) {
+  const status = response?.status ?? 0;
+  let detail = '';
+  try {
+    // Cloned so a caller that also reads the body still can; a response whose body is already
+    // consumed simply yields no detail rather than a second failure on top of the first.
+    const text = await (typeof response.clone === 'function' ? response.clone() : response).text();
+    detail = extract(text);
+  } catch {
+    detail = '';
+  }
+  return `${action} failed with HTTP ${status}${detail === '' ? '' : `: ${detail}`}`;
+}
+
+function extract(text) {
+  if (typeof text !== 'string' || text.trim() === '') return '';
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return truncate(text);
+  }
+  if (payload == null || typeof payload !== 'object') return truncate(text);
+  const parts = [];
+  if (typeof payload.message === 'string' && payload.message.trim() !== '') parts.push(payload.message.trim());
+  // GitHub's `errors` array carries the specific field or reason behind a generic message.
+  if (Array.isArray(payload.errors)) {
+    for (const error of payload.errors) {
+      const reason = typeof error === 'string' ? error : error?.message ?? error?.code;
+      if (typeof reason === 'string' && reason.trim() !== '') parts.push(reason.trim());
+    }
+  }
+  if (typeof payload.error_description === 'string') parts.push(payload.error_description.trim());
+  if (typeof payload.code === 'string' && parts.length === 0) parts.push(payload.code);
+  if (typeof payload.documentation_url === 'string') parts.push(`See ${payload.documentation_url}`);
+  return truncate(parts.length === 0 ? text : parts.join(' — '));
+}
+
+function truncate(value) {
+  const flattened = value.replace(/\s+/g, ' ').trim();
+  return flattened.length > MAX_DETAIL ? `${flattened.slice(0, MAX_DETAIL)}…` : flattened;
+}

package/src/scaffold-preflight.js

@@ -5,7 +5,6 @@ import { authenticateGithub } from './github-auth-command.js';
 import { readGalaCredential } from './gala-credential-store.js';
 import { readGithubCredential } from './github-credential-store.js';
 import { resolveGithubLogin } from './github-identity.js';
-import { resolveInstallationId } from './gala-installation-client.js';
 import { galaCredentialAccepted } from './gala-credential-health.js';
 import { openInBrowser } from './open-browser.js';
 import { forgetGalaCredential } from './gala-credential-store.js';
@@ -36,8 +35,6 @@ export async function prepareScaffold({
   cwd = process.cwd(),
   notify = () => {},
   ask,
-  installUrl = GITHUB_APP_INSTALL_URL,
-  installAttempts = 3,
   openUrl = openInBrowser,
   readGala = readGalaCredential,
   readGithub = readGithubCredential,
@@ -46,7 +43,6 @@ export async function prepareScaffold({
   signInGala = authenticateGala,
   signInGithub = authenticateGithub,
   resolveLogin = resolveGithubLogin,
-  resolveInstallation = resolveInstallationId,
   apiBaseUrl = DEFAULT_API_BASE_URL
 } = {}) {
   const gala = await ensureGala({
@@ -65,20 +61,18 @@ export async function prepareScaffold({
   // directory the writer is standing in. Everywhere else the repository names its own folder.
   const resolvedTarget = target ?? `./${resolvedRepository}`;
 
-  const resolvedInstallation = githubInstallationId
-    ?? await ensureInstallation({
-      apiBaseUrl: gala.apiBaseUrl ?? apiBaseUrl,
-      galaAccessToken: gala.accessToken,
-      githubAccessToken: github.accessToken,
-      owner: resolvedOwner,
-      notify, ask, installUrl, installAttempts, resolveInstallation, openUrl
-    });
-
+  /*
+   * No installation lookup. The id is an internal GitHub identifier for an App the server owns, and
+   * nothing here can discover it reliably: a GitHub App token could list installations and the CLI
+   * cannot hold one, while the repository inventory only carries the id once a repository exists —
+   * which, in the flow that creates the first repository, is never. The server resolves it during
+   * registration. `--installation-id` still overrides, for an account with several.
+   */
   return Object.freeze({
     owner: resolvedOwner,
     repository: resolvedRepository,
     target: resolvedTarget,
-    githubInstallationId: resolvedInstallation
+    githubInstallationId: githubInstallationId ?? null
   });
 }
 
@@ -133,47 +127,6 @@ async function ensureGithub({ notify, readGithub, signInGithub, openUrl }) {
   }
 }
 
-/**
- * Confirms the Gala GitHub App is installed, walking the writer through installing it if not.
- *
- * This is the step that used to be a manual detour through GitHub's settings to copy a number out
- * of a redirect URL. The loop is what makes it a step rather than a failure: the writer installs
- * the App in the browser, comes back, presses enter, and the run continues.
- */
-async function ensureInstallation({
-  apiBaseUrl, galaAccessToken, githubAccessToken, owner,
-  notify, ask, installUrl, installAttempts, resolveInstallation, openUrl
-}) {
-  for (let attempt = 0; attempt < Math.max(1, installAttempts); attempt += 1) {
-    const installationId = await resolveInstallation({
-      apiBaseUrl, galaAccessToken, githubAccessToken, owner
-    });
-    if (installationId != null) return installationId;
-
-    if (typeof ask !== 'function') {
-      throw new Error(
-        `The Gala GitHub App is not installed on ${owner}. Install it at ${installUrl} and run `
-        + 'scaffold again, or pass --installation-id explicitly.'
-      );
-    }
-
-    // An installation belongs to one account. Installing it on a personal account when the
-    // publication is meant for an organisation looks like it worked and changes nothing here, so
-    // the account being checked is named every time rather than assumed.
-    notify(attempt === 0
-      ? `The Gala GitHub App is not installed on ${owner} yet.`
-      : `Still not seeing the App on ${owner}. Check that you installed it on ${owner} itself `
-        + 'and not on another account or organisation you belong to.');
-    notify(`${openUrl(installUrl) ? 'Opened' : 'Open'} ${installUrl}`);
-    await ask('Press enter once the App is installed. ');
-  }
-  throw new Error(
-    `The Gala GitHub App still does not cover ${owner}. Install it at ${installUrl} for ${owner} `
-    + 'specifically, then run scaffold again. If the App is installed under a different account, '
-    + 'pass --owner for that account, or --installation-id to name the installation directly.'
-  );
-}
-
 /** GitHub repository names allow letters, digits, dot, underscore and hyphen, and nothing else. */
 export function repositoryNameFrom(siteName) {
   if (typeof siteName !== 'string') return null;

package/src/scaffold-site.js

@@ -62,7 +62,10 @@ export async function scaffoldSite({
   const repositoryOwner = segment(owner, 'owner');
   const repositoryName = segment(repository, 'repository');
   const location = registrationLocation(repositoryOwner, topology, canonicalBaseUrl);
-  if (!Number.isSafeInteger(githubInstallationId) || githubInstallationId <= 0) {
+  // Optional: the server resolves the installation from the owner when none is supplied. An
+  // explicit value is still validated, because a wrong one fails much later and less clearly.
+  if (githubInstallationId != null
+      && (!Number.isSafeInteger(githubInstallationId) || githubInstallationId <= 0)) {
     throw new TypeError('githubInstallationId must be a positive integer');
   }
   if (target == null || path.resolve(target) === path.parse(path.resolve(target)).root) {

package/src/site-registration-client.js

@@ -1,3 +1,4 @@
+import { describeHttpFailure } from './http-failure.js';
 const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
 const REPOSITORY_PART = /^[A-Za-z0-9_.-]+$/;
 const IDEMPOTENCY_KEY = /^[A-Za-z0-9._:-]{16,128}$/;
@@ -34,7 +35,7 @@ async function authorizeGitHub({ apiBaseUrl, galaAccessToken, githubAccessToken,
     throw new Error('GitHub or Gala authentication expired; run `gala auth` again');
   }
   if (response.status !== 200) {
-    throw new Error(`GitHub repository authorization failed with HTTP ${response.status}`);
+    throw new Error(await describeHttpFailure(response, 'GitHub repository authorization'));
   }
   const payload = await response.json();
   return required(payload?.authorization, 'GitHub authorization', /^[A-Za-z0-9_-]{43}$/);
@@ -61,7 +62,8 @@ export async function registerSite({
   required(idempotencyKey, 'idempotencyKey', IDEMPOTENCY_KEY);
   required(repositoryOwner, 'repositoryOwner', REPOSITORY_PART);
   required(repositoryName, 'repositoryName', REPOSITORY_PART);
-  if (!Number.isSafeInteger(githubInstallationId) || githubInstallationId <= 0) {
+  if (githubInstallationId != null
+      && (!Number.isSafeInteger(githubInstallationId) || githubInstallationId <= 0)) {
     throw new TypeError('githubInstallationId must be a positive integer');
   }
   if (!['PROVIDER_DEFAULT', 'CUSTOM_DOMAIN'].includes(topology)) {
@@ -77,7 +79,8 @@ export async function registerSite({
       'idempotency-key': idempotencyKey
     },
     body: JSON.stringify({
-      githubInstallationId,
+      // Omitted rather than sent as null: the server resolves it from the owner.
+      ...(githubInstallationId == null ? {} : { githubInstallationId }),
       repositoryOwner,
       repositoryName,
       topology,
@@ -91,9 +94,17 @@ export async function registerSite({
     throw new Error(`GitHub App installation does not cover ${repositoryOwner}/${repositoryName}`);
   }
   if (response.status === 409) {
+    const failure = await response.clone().json().catch(() => null);
+    if (failure?.code === 'GITHUB_APP_NOT_INSTALLED') {
+      throw new Error(
+        `The Gala GitHub App is not installed on ${repositoryOwner}. Install it at `
+        + 'https://github.com/apps/gala67-app/installations/new for that account, then run scaffold '
+        + 'again.'
+      );
+    }
     throw new Error('Site registration conflicts with existing protected state; use the recovery command');
   }
-  if (response.status !== 201) throw new Error(`Gala site registration failed with HTTP ${response.status}`);
+  if (response.status !== 201) throw new Error(await describeHttpFailure(response, 'Gala site registration'));
   const payload = await response.json();
   if (!ULID.test(payload?.siteId) || typeof payload.siteSecret !== 'string' || payload.siteSecret === '') {
     throw new TypeError('Gala site registration response is invalid');

package/src/gala-installation-client.js

@@ -1,105 +0,0 @@
-/**
- * Which Gala GitHub App installation covers this writer's account.
- *
- * The installation ID is an internal GitHub identifier that `scaffold` has to send when it
- * registers a site. Until now the writer supplied it by installing the App, watching GitHub
- * redirect to `https://github.com/settings/installations/153144989`, and copying the number out of
- * the address bar — an internal identifier, read out of a URL, by hand.
- *
- * The Gala API already knows it. `GET /v1/auth/github/repositories` answers with
- * `{ installationId, owner, name, status }` per repository, so the CLI can ask the same service it
- * is about to register with rather than guess. Reaching that endpoint needs the bounded capability
- * from `POST /v1/auth/github/device-authorizations`, which is bound to the Gala user and takes the
- * GitHub token the CLI already holds.
- */
-function endpoint(apiBaseUrl, path) {
-  return `${String(apiBaseUrl).replace(/\/$/, '')}${path}`;
-}
-
-export async function exchangeGithubAuthorization({
-  apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl = fetch
-}) {
-  const response = await fetchImpl(endpoint(apiBaseUrl, '/v1/auth/github/device-authorizations'), {
-    method: 'POST',
-    headers: {
-      accept: 'application/json',
-      authorization: `Bearer ${galaAccessToken}`,
-      'content-type': 'application/json'
-    },
-    body: JSON.stringify({ accessToken: githubAccessToken })
-  });
-  if (response.status === 409) {
-    // The API distinguishes "the App is not installed on this account" from "your credential is
-    // finished". Only the first is something the writer can fix in a browser, so it is signalled
-    // rather than thrown: the caller offers the installation page and waits.
-    return null;
-  }
-  if (response.status === 401) {
-    // Either credential can be the one at fault and the caller cannot tell them apart, so say so
-    // rather than printing a status code the writer has no way to interpret.
-    throw new Error(
-      'Gala refused the GitHub authorization. Run `npx --yes @rathnasgala/cli@latest auth` and '
-      + '`auth github` again, then retry.'
-    );
-  }
-  if (!response.ok) {
-    throw new Error(`GitHub authorization exchange failed with HTTP ${response.status}`);
-  }
-  const payload = await response.json();
-  if (typeof payload?.authorization !== 'string') {
-    throw new TypeError('GitHub authorization exchange returned no capability');
-  }
-  return payload.authorization;
-}
-
-/**
- * Both credentials are required, and they are not interchangeable.
- *
- * The endpoint is `.authenticated()` and its handler takes the Gala principal, so the bearer says
- * who is asking; `GitHub-Authorization` is the short-lived capability that says what they may see.
- * Sending only the capability gets a bare 401 from the security filter, before any handler runs —
- * which reads as "your GitHub authorization was refused" and is nothing of the kind.
- */
-export async function listAuthorizedRepositories({
-  apiBaseUrl, authorization, galaAccessToken, fetchImpl = fetch
-}) {
-  const response = await fetchImpl(endpoint(apiBaseUrl, '/v1/auth/github/repositories'), {
-    headers: {
-      accept: 'application/json',
-      authorization: `Bearer ${galaAccessToken}`,
-      'GitHub-Authorization': authorization
-    }
-  });
-  if (!response.ok) {
-    throw new Error(`Authorized repository lookup failed with HTTP ${response.status}`);
-  }
-  const payload = await response.json();
-  if (!Array.isArray(payload)) throw new TypeError('Authorized repository lookup returned no list');
-  return payload;
-}
-
-/**
- * Returns the installation covering `owner`, or null when the App is not installed there.
- *
- * An installation belongs to an account, not to one repository, so any repository the App can
- * already see under that owner carries the id the new one will use. Null is an ordinary answer —
- * it means "not installed yet" — and the caller turns it into an instruction, not an error.
- */
-export async function resolveInstallationId({
-  apiBaseUrl, galaAccessToken, githubAccessToken, owner, fetchImpl = fetch,
-  exchange = exchangeGithubAuthorization, list = listAuthorizedRepositories
-}) {
-  const authorization = await exchange({
-    apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl
-  });
-  // null means the App is not installed yet, which the caller turns into an instruction.
-  if (authorization == null) return null;
-  const repositories = await list({ apiBaseUrl, authorization, galaAccessToken, fetchImpl });
-  const wanted = String(owner).toLowerCase();
-  for (const repository of repositories) {
-    if (String(repository?.owner).toLowerCase() !== wanted) continue;
-    const installationId = Number(repository?.installationId);
-    if (Number.isSafeInteger(installationId) && installationId > 0) return installationId;
-  }
-  return null;
-}