@rathnasgala/cli 0.0.17 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala/cli",
-  "version": "0.0.17",
+  "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/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}$/);
@@ -103,7 +104,7 @@ export async function registerSite({
     }
     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');