@rathnasgala/cli 0.0.18 → 0.0.20

package/package.json

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

package/src/github-template-repository.js

@@ -27,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');
@@ -85,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/index.js

@@ -130,6 +130,9 @@ if (command === 'auth') {
     ask
   });
   const result = await scaffoldSite({
+    notify: (message) => process.stdout.write(`${message}\n`),
+    ask,
+    openUrl: openInBrowser,
     owner: prepared.owner,
     repository: prepared.repository,
     target: prepared.target,

package/src/publication-creation-client.js

@@ -0,0 +1,115 @@
+/**
+ * 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,
+  notify = () => {},
+  ask,
+  openUrl = () => false,
+  shareAttempts = 3,
+  installationsUrl = 'https://github.com/settings/installations'
+}) {
+  let created = false;
+  for (let attempt = 0; attempt < Math.max(1, shareAttempts); attempt += 1) {
+    const result = await requestPublication({
+      apiBaseUrl, galaAccessToken, githubAccessToken, name, fetchImpl, authorize
+    });
+    if (result.ready) return result.publication;
+
+    /*
+     * The repository exists with the right content; the App installation simply cannot see it,
+     * because it is scoped to selected repositories rather than all of them. Sharing it is a click,
+     * and asking again then returns READY — the server short-circuits on a repository it can
+     * already see. The browser editor recovers the same way; without this the CLI dead-ends on a
+     * state that is one click from working.
+     *
+     * After the first attempt the repository exists, so a further refusal reports UNSUPPORTED
+     * rather than NEEDS_SHARING — the same situation under a different name.
+     */
+    const shareable = result.status === 'NEEDS_SHARING' || created;
+    created = created || result.status === 'NEEDS_SHARING';
+    if (!shareable || typeof ask !== 'function') throw result.failure;
+
+    notify(`${result.owner ?? ''}/${result.repository ?? name} exists, but the Gala GitHub App `
+      + 'cannot reach it yet — its installation covers only selected repositories.');
+    notify(`${openUrl(installationsUrl) ? 'Opened' : 'Open'} ${installationsUrl}`);
+    await ask('Press enter once the App can access that repository. ');
+  }
+  throw new Error(
+    `The Gala GitHub App still cannot reach the repository for ${name}. Give it access at `
+    + `${installationsUrl}, then run scaffold again.`
+  );
+}
+
+async function requestPublication({
+  apiBaseUrl, galaAccessToken, githubAccessToken, name, fetchImpl, authorize
+}) {
+  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 !== 'READY') {
+    return {
+      ready: false, status, owner, repository,
+      failure: new Error(
+        `Gala could not create the publication repository (${payload?.outcome ?? status}). `
+        + 'Give the Gala GitHub App access to it at https://github.com/settings/installations, or '
+        + 'create it from https://github.com/rathnasgala/site-template yourself and 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 { ready: true, status, owner, repository, publication: 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';
@@ -47,11 +48,12 @@ function registrationLocation(owner, topology, canonicalBaseUrl) {
 
 export async function scaffoldSite({
   owner, repository, target, githubInstallationId, siteOptions, emptyExistingRepository = false,
+  notify = (message) => process.stdout.write(`${message}\n`), ask, openUrl,
   resumeExistingCheckout = false, topology = 'provider-default', canonicalBaseUrl, actionRef,
   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 +61,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 +76,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 +104,37 @@ 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,
+      notify, ask, openUrl
+    });
+    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

@@ -18,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`');
   }
@@ -56,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);