@rathnasgala/cli 0.0.17 → 0.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala/cli",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "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_.-]+$/;
@@ -26,7 +27,10 @@ export async function generateRepositoryFromTemplate({
   owner,
   repository,
   description,
-  fetchImpl = fetch
+  fetchImpl = fetch,
+  sleep,
+  readinessAttempts,
+  readinessIntervalMs
 }) {
   const token = requiredString(accessToken, 'accessToken');
   const sourceOwner = repositorySegment(templateOwner, 'templateOwner');
@@ -57,7 +61,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') {
@@ -84,9 +88,53 @@ export async function generateRepositoryFromTemplate({
     throw new TypeError('GitHub repository response contains an invalid clone_url');
   }
 
+  // Last, so a malformed response fails immediately instead of after the readiness wait.
+  await awaitRepositoryContent({
+    accessToken: token, owner: targetOwner, repository: targetRepository, fetchImpl,
+    ...(sleep == null ? {} : { sleep }),
+    ...(readinessAttempts == null ? {} : { attempts: readinessAttempts }),
+    ...(readinessIntervalMs == null ? {} : { intervalMs: readinessIntervalMs })
+  });
+
   return Object.freeze({ fullName, cloneUrl: cloneUrl.href });
 }
 
+/**
+ * Waits for a generated repository to actually contain the template.
+ *
+ * Generating from a template is asynchronous: GitHub answers 201 with the repository's full name
+ * and clone URL, and copies the content in afterwards. Cloning on the 201 produced
+ * "warning: You appear to have cloned an empty repository", and scaffolding then failed on a
+ * missing site.config.yml — a confusing error about a file the template certainly contains.
+ *
+ * Readiness is the presence of a branch. `size` is not usable: GitHub still reported 0 for a
+ * repository that already had `main` and commits.
+ */
+export async function awaitRepositoryContent({
+  accessToken, owner, repository, fetchImpl = fetch,
+  sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  attempts = 30, intervalMs = 1_000
+}) {
+  const url = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/branches?per_page=1`;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (attempt > 0) await sleep(intervalMs);
+    const response = await fetchImpl(url, {
+      headers: {
+        accept: 'application/vnd.github+json',
+        authorization: `Bearer ${accessToken}`,
+        'x-github-api-version': GITHUB_API_VERSION
+      }
+    });
+    if (!response.ok) throw new Error(await describeHttpFailure(response, 'GitHub branch lookup'));
+    const branches = await response.json();
+    if (Array.isArray(branches) && branches.length > 0) return;
+  }
+  throw new Error(
+    `GitHub created ${owner}/${repository} from the template but it was still empty after `
+    + `${Math.round((attempts * intervalMs) / 1000)}s. Re-run scaffold with --resume once it has content.`
+  );
+}
+
 export function cloneRepository({ cloneUrl, target, spawnProcess = spawn }) {
   const source = new URL(requiredString(cloneUrl, 'cloneUrl'));
   if (

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/publication-creation-client.js

@@ -0,0 +1,78 @@
+/**
+ * Creates the publication repository the way the browser editor does.
+ *
+ * The CLI used to call `POST /repos/{template}/generate` itself. That is a second, worse
+ * implementation of something the API already does and does properly:
+ *
+ *  - it tries the template, then falls back to creating an empty repository and seeding it, then
+ *    reports that the writer must do it by hand — the CLI's single attempt had no rung below it;
+ *  - it waits for the Gala App installation to actually reach the new repository before calling it
+ *    ready, which is why repositories the CLI created never appeared in the web UI;
+ *  - it returns the installation id, so registration cannot disagree with creation about which
+ *    installation owns the repository.
+ *
+ * One implementation, exercised by both clients, is the only way the two stay in step.
+ */
+import { describeHttpFailure } from './http-failure.js';
+import { exchangeGithubAuthorization } from './site-registration-client.js';
+
+export async function createPublication({
+  apiBaseUrl = 'https://api.gala67.com',
+  galaAccessToken,
+  githubAccessToken,
+  name,
+  fetchImpl = fetch,
+  authorize = exchangeGithubAuthorization
+}) {
+  const authorization = await authorize({
+    apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl
+  });
+  const response = await fetchImpl(`${String(apiBaseUrl).replace(/\/$/, '')}/v1/auth/github/publications`, {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${galaAccessToken}`,
+      'content-type': 'application/json',
+      'GitHub-Authorization': authorization
+    },
+    body: JSON.stringify({ name })
+  });
+  if (!response.ok) throw new Error(await describeHttpFailure(response, 'Gala publication creation'));
+
+  const payload = await response.json();
+  const status = payload?.status;
+  const owner = payload?.owner;
+  const repository = payload?.name;
+
+  if (status === 'NEEDS_SHARING') {
+    throw new Error(
+      `${owner}/${repository} was created from the template, but the Gala GitHub App cannot reach `
+      + 'it yet. Open https://github.com/settings/installations, give the App access to that '
+      + 'repository, then run scaffold again with --resume.'
+    );
+  }
+  if (status !== 'READY') {
+    throw new Error(
+      `Gala could not create the publication repository (${payload?.outcome ?? status}). `
+      + 'Create it from https://github.com/rathnasgala/site-template yourself, then run scaffold '
+      + 'with --empty-existing-repository.'
+    );
+  }
+  if (typeof owner !== 'string' || typeof repository !== 'string') {
+    throw new TypeError('Gala publication creation returned no repository identity');
+  }
+  const installationId = Number(payload?.installationId);
+  if (!Number.isSafeInteger(installationId) || installationId <= 0) {
+    throw new TypeError('Gala publication creation returned no installation');
+  }
+
+  return Object.freeze({
+    owner,
+    repository,
+    installationId,
+    outcome: payload?.outcome ?? null,
+    // The server names the repository it actually made, which may differ from what was asked for.
+    fullName: `${owner}/${repository}`,
+    cloneUrl: `https://github.com/${owner}/${repository}.git`
+  });
+}

package/src/scaffold-site.js

@@ -4,7 +4,8 @@ import path from 'node:path';
 import { configureSite } from './configure-site.js';
 import { readGalaCredential } from './gala-credential-store.js';
 import { readGithubCredential } from './github-credential-store.js';
-import { cloneRepository, generateRepositoryFromTemplate } from './github-template-repository.js';
+import { awaitRepositoryContent, cloneRepository } from './github-template-repository.js';
+import { createPublication } from './publication-creation-client.js';
 import { installRepositoryVariable } from './github-repository-variable.js';
 import { provisionGithubPages } from './github-pages-provisioning.js';
 import { registerSite } from './site-registration-client.js';
@@ -51,7 +52,7 @@ export async function scaffoldSite({
   buildMode = 'build-and-deploy', templateOwner = 'rathnasgala',
   templateRepository = 'site-template',
   readGithub = readGithubCredential, readGala = readGalaCredential,
-  generate = generateRepositoryFromTemplate, clone = cloneRepository,
+  createRepository = createPublication, awaitContent = awaitRepositoryContent, clone = cloneRepository,
   configure = configureSite, register = registerSite, finalize = writeRegisteredSiteConfiguration,
   writeWorkflow = writePublishWorkflow,
   installVariable = installRepositoryVariable,
@@ -59,9 +60,11 @@ export async function scaffoldSite({
   commit = commitScaffold, verifyEmpty = verifyEmptyRepository, setOrigin = setRepositoryOrigin,
   verifyCheckout = verifyRepositoryOrigin
 }) {
-  const repositoryOwner = segment(owner, 'owner');
-  const repositoryName = segment(repository, 'repository');
-  const location = registrationLocation(repositoryOwner, topology, canonicalBaseUrl);
+  const requestedOwner = segment(owner, 'owner');
+  const requestedName = segment(repository, 'repository');
+  // Validated now so a bad --topology/--canonical-base-url combination fails before a repository
+  // exists. The value used later is recomputed once the server says who actually owns it.
+  registrationLocation(requestedOwner, topology, canonicalBaseUrl);
   // 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
@@ -72,9 +75,20 @@ export async function scaffoldSite({
     throw new TypeError('target must be a non-root local path');
   }
   const [github, gala] = await Promise.all([readGithub(), readGala()]);
+  // Creation reports which installation owns the new repository, so registration cannot disagree.
+  let resolvedInstallationId = githubInstallationId ?? null;
   if (emptyExistingRepository && resumeExistingCheckout) {
     throw new TypeError('emptyExistingRepository and resumeExistingCheckout are mutually exclusive');
   }
+  /*
+   * The server decides the owner, not this process. It creates under the account the Gala App
+   * installation belongs to, which is not always the account behind the writer's OAuth token — an
+   * installation on an organisation they belong to gives a different owner entirely. Deriving the
+   * canonical URL, the idempotency key, the registration and the Pages target from the local guess
+   * would register a publication against a repository that does not exist.
+   */
+  let repositoryOwner = requestedOwner;
+  let repositoryName = requestedName;
   let generated;
   let root;
   if (resumeExistingCheckout) {
@@ -89,22 +103,36 @@ export async function scaffoldSite({
       cloneUrl: `https://github.com/${templateOwner}/${templateRepository}.git`
     };
   } else {
-    generated = await generate({
-      accessToken: github.accessToken, templateOwner, templateRepository,
-      owner: repositoryOwner, repository: repositoryName,
-      description: siteOptions?.siteName ?? ''
+    /*
+     * Created through the API, the same call the browser editor makes. Doing it here meant a second
+     * implementation with no fallback and no wait for the App installation to reach the result,
+     * which is why CLI-created repositories never appeared in the web UI.
+     */
+    const created = await createRepository({
+      apiBaseUrl: gala.apiBaseUrl, galaAccessToken: gala.accessToken,
+      githubAccessToken: github.accessToken, name: repositoryName
+    });
+    repositoryOwner = segment(created.owner, 'owner');
+    repositoryName = segment(created.repository, 'repository');
+    resolvedInstallationId = created.installationId;
+    generated = { fullName: created.fullName, cloneUrl: created.cloneUrl };
+    // Creation is asynchronous: GitHub answers before the template content lands, and cloning into
+    // that window produces an empty checkout and a missing site.config.yml.
+    await awaitContent({
+      accessToken: github.accessToken, owner: created.owner, repository: created.repository
     });
   }
   if (!resumeExistingCheckout) {
     root = await clone({ cloneUrl: generated.cloneUrl, target });
     if (emptyExistingRepository) await setOrigin({ root, owner: repositoryOwner, repository: repositoryName });
   }
+  const location = registrationLocation(repositoryOwner, topology, canonicalBaseUrl);
   const configured = await configure(root, siteOptions ?? {});
   const idempotencyKey = `scaffold-${createHash('sha256').update(`${repositoryOwner.toLowerCase()}/${repositoryName.toLowerCase()}`).digest('hex')}`;
   const registration = await register({
     apiBaseUrl: gala.apiBaseUrl, galaAccessToken: gala.accessToken,
     githubAccessToken: github.accessToken, idempotencyKey,
-    githubInstallationId, repositoryOwner, repositoryName,
+    githubInstallationId: resolvedInstallationId, repositoryOwner, repositoryName,
     topology: location.topology, canonicalBaseUrl: location.canonicalBaseUrl
   });
   await finalize(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}$/;
@@ -17,7 +18,14 @@ function apiUrl(apiBaseUrl) {
   return new URL('/v1/sites', base).href;
 }
 
-async function authorizeGitHub({ apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl }) {
+/**
+ * Exchanges the stored GitHub token for the short-lived capability the API's GitHub-scoped
+ * endpoints require. Exported because publication creation needs the same capability, and two
+ * copies of an auth exchange is how they drift.
+ */
+export async function exchangeGithubAuthorization({
+  apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl
+}) {
   if (typeof githubAccessToken !== 'string' || githubAccessToken === '') {
     throw new Error('GitHub authentication is missing; run `gala auth`');
   }
@@ -34,7 +42,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}$/);
@@ -55,7 +63,7 @@ export async function registerSite({
   if (typeof galaAccessToken !== 'string' || galaAccessToken === '') {
     throw new Error('Gala authentication is missing; run `gala auth`');
   }
-  const githubAuthorization = await authorizeGitHub({
+  const githubAuthorization = await exchangeGithubAuthorization({
     apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl
   });
   required(idempotencyKey, 'idempotencyKey', IDEMPOTENCY_KEY);
@@ -103,7 +111,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');