@rathnasgala/cli 0.0.13 → 0.0.15

package/package.json

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

package/src/gala-credential-health.js

@@ -0,0 +1,34 @@
+/**
+ * Whether a stored Gala credential is one the server will still accept.
+ *
+ * `readGalaCredential` can only check what is written in the file — schema and expiry — and a
+ * credential can satisfy both while the API refuses it outright. It happened: the API stopped
+ * putting a `tenant` claim in its tokens and now rejects any token that still carries one
+ * (Rs256JwtCodec: "Legacy tenant-bearing token requires reauthentication"). Tokens minted before
+ * that change have a month-long expiry, so every command using one sent a bearer the server had
+ * already decided to refuse, and reported it as whatever call happened to fail first.
+ *
+ * Expiry is not the only way a credential dies. It can be revoked, the signing key can rotate, the
+ * claim set can change again. So this does not special-case the `tenant` claim: it asks the server,
+ * once, and treats 401 as "this credential is finished" — which is true whatever the reason.
+ */
+const PROBE_PATH = '/v1/me/sites';
+
+/**
+ * Answers whether the API still accepts this credential.
+ *
+ * A network failure is deliberately not an answer: refusing to run because the machine is briefly
+ * offline, or forcing a sign-in the writer does not need, are both worse than letting the real
+ * call fail with its own error.
+ */
+export async function galaCredentialAccepted({ apiBaseUrl, accessToken, fetchImpl = fetch }) {
+  let response;
+  try {
+    response = await fetchImpl(`${String(apiBaseUrl).replace(/\/$/, '')}${PROBE_PATH}`, {
+      headers: { accept: 'application/json', authorization: `Bearer ${accessToken}` }
+    });
+  } catch {
+    return true;
+  }
+  return response.status !== 401;
+}

package/src/gala-credential-store.js

@@ -102,3 +102,14 @@ export async function readGalaCredential({ target = galaCredentialPath(), now =
     expiresAt
   });
 }
+
+/**
+ * Removes a credential the server no longer accepts.
+ *
+ * Leaving a refused token on disk means every later command rediscovers that it is refused, and
+ * `readGalaCredential` cannot tell the difference — the file is well-formed and unexpired. Deleting
+ * it is what makes the next run ask for a sign-in instead of failing again.
+ */
+export async function forgetGalaCredential({ target = galaCredentialPath() } = {}) {
+  await rm(target, { force: true });
+}

package/src/gala-installation-client.js

@@ -28,6 +28,20 @@ export async function exchangeGithubAuthorization({
     },
     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}`);
   }
@@ -64,6 +78,8 @@ export async function resolveInstallationId({
   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, fetchImpl });
   const wanted = String(owner).toLowerCase();
   for (const repository of repositories) {

package/src/index.js

@@ -20,11 +20,40 @@ import { createInterface } from 'node:readline/promises';
 import { upgradeTheme } from './upgrade-command.js';
 import { authenticateGithub } from './github-auth-command.js';
 import { scaffoldSite } from './scaffold-site.js';
+import { openInBrowser } from './open-browser.js';
 import { prepareScaffold } from './scaffold-preflight.js';
 import { refreshEngagementSnapshot } from './refresh-command.js';
 import { switchTopology } from './topology-command.js';
 import { acquireAttributionEntitlement } from './entitlement-command.js';
 
+/*
+ * A failed command should say what went wrong and what to do about it. Node's default for a
+ * rejected top-level await is a stack trace through node_modules, which tells a writer nothing and
+ * buries the one line that matters. The stack is still available behind GALA_DEBUG for anyone
+ * debugging the CLI itself.
+ */
+process.on('uncaughtException', reportAndExit);
+process.on('unhandledRejection', reportAndExit);
+
+function reportAndExit(failure) {
+  if (process.env.GALA_DEBUG) {
+    process.stderr.write(`${failure instanceof Error ? failure.stack : String(failure)}\n`);
+  } else {
+    const message = failure instanceof Error ? failure.message : String(failure);
+    process.stderr.write(`${message}\n`);
+  }
+  process.exit(1);
+}
+
+/**
+ * Opens the page and says so, or falls back to asking for it to be opened by hand. The URL is
+ * printed either way — it is the thing the writer may need to move to another device.
+ */
+function announce(verificationUri, userCode) {
+  const opened = openInBrowser(verificationUri);
+  return `${opened ? 'Opened' : 'Open'} ${verificationUri}\nEnter code: ${userCode}\n`;
+}
+
 const [command, ...args] = process.argv.slice(2);
 const usage = 'Usage: gala <auth|configure|entitlement|scaffold|topology|validate|new|doctor|hook|preview|publish|record-deployment|refresh|upgrade|workflow> [options]';
 
@@ -58,7 +87,7 @@ if (command === 'auth') {
     const result = await authenticateGithub({
       showScopeWarning: ({ explanation }) => process.stdout.write(`GitHub authorization: ${explanation}\n`),
       showInstructions: ({ verificationUri, userCode }) => {
-        process.stdout.write(`Open ${verificationUri}\nEnter code: ${userCode}\n`);
+        process.stdout.write(announce(verificationUri, userCode));
       }
     });
     process.stdout.write(`GitHub authentication stored securely with scopes: ${result.scopes.join(', ')}.\n`);
@@ -68,7 +97,7 @@ if (command === 'auth') {
     const result = await authenticateGala({
       apiBaseUrl,
       showInstructions: ({ verificationUri, userCode }) => {
-        process.stdout.write(`Open ${verificationUri}\nEnter code: ${userCode}\n`);
+        process.stdout.write(announce(verificationUri, userCode));
       }
     });
     process.stdout.write(`Gala authentication stored securely until ${result.expiresAt.toISOString()}.\n`);

package/src/open-browser.js

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Opens a URL in the writer's browser, best effort.
+ *
+ * Printing "Open https://…" and a code asks someone to copy a URL out of a terminal by hand, three
+ * times over in one scaffold. The URL is still always printed — this only saves the copying, and it
+ * has to keep working when it cannot: over SSH, in a container, in CI, on a machine with no browser
+ * at all. So nothing here is allowed to fail the command.
+ *
+ * Deliberately not attempted when there is no terminal. A CI job that silently spawns a browser
+ * process is a hang waiting to happen, and there is nobody there to look at it.
+ */
+export function openInBrowser(url, {
+  platform = process.platform,
+  environment = process.env,
+  interactive = process.stdin.isTTY === true,
+  spawnProcess = spawn
+} = {}) {
+  if (!interactive) return false;
+  // Respected by convention across CLI tooling, and the escape hatch for anyone who does not want
+  // their browser taken over.
+  if (environment.GALA_NO_BROWSER || environment.CI || environment.NO_BROWSER) return false;
+  if (!/^https:\/\//.test(url)) return false;
+
+  const [command, args] = platform === 'darwin' ? ['open', [url]]
+    : platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+
+  try {
+    const child = spawnProcess(command, args, { stdio: 'ignore', detached: true, shell: false });
+    // Without this the CLI waits for the browser to exit before it can finish.
+    child.unref?.();
+    // A missing opener is an ordinary outcome on a headless box, not something to report.
+    child.on?.('error', () => {});
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/scaffold-preflight.js

@@ -6,6 +6,9 @@ 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';
 
 export const GITHUB_APP_INSTALL_URL = 'https://github.com/apps/gala67-app/installations/new';
 
@@ -35,16 +38,21 @@ export async function prepareScaffold({
   ask,
   installUrl = GITHUB_APP_INSTALL_URL,
   installAttempts = 3,
+  openUrl = openInBrowser,
   readGala = readGalaCredential,
   readGithub = readGithubCredential,
+  credentialAccepted = galaCredentialAccepted,
+  forgetGala = forgetGalaCredential,
   signInGala = authenticateGala,
   signInGithub = authenticateGithub,
   resolveLogin = resolveGithubLogin,
   resolveInstallation = resolveInstallationId,
   apiBaseUrl = DEFAULT_API_BASE_URL
 } = {}) {
-  const gala = await ensureGala({ apiBaseUrl, notify, readGala, signInGala });
-  const github = await ensureGithub({ notify, readGithub, signInGithub });
+  const gala = await ensureGala({
+    apiBaseUrl, notify, readGala, signInGala, credentialAccepted, forgetGala, openUrl
+  });
+  const github = await ensureGithub({ notify, readGithub, signInGithub, openUrl });
 
   const resolvedOwner = owner ?? await resolveLogin({ accessToken: github.accessToken });
 
@@ -63,7 +71,7 @@ export async function prepareScaffold({
       galaAccessToken: gala.accessToken,
       githubAccessToken: github.accessToken,
       owner: resolvedOwner,
-      notify, ask, installUrl, installAttempts, resolveInstallation
+      notify, ask, installUrl, installAttempts, resolveInstallation, openUrl
     });
 
   return Object.freeze({
@@ -74,22 +82,44 @@ export async function prepareScaffold({
   });
 }
 
-/** A missing or expired credential is a step to take, not an error to report. */
-async function ensureGala({ apiBaseUrl, notify, readGala, signInGala }) {
+/**
+ * A missing, expired or refused credential is a step to take, not an error to report.
+ *
+ * The stored file is checked against the server before anything depends on it, because a
+ * credential that parses and has not expired can still be one the API refuses — and finding that
+ * out four calls later, as an opaque 401 from whichever endpoint got there first, is how a
+ * "sign in again" turned into a stack trace.
+ */
+async function ensureGala({
+  apiBaseUrl, notify, readGala, signInGala, credentialAccepted, forgetGala, openUrl
+}) {
+  let stored = null;
   try {
-    return await readGala();
+    stored = await readGala();
   } catch {
-    notify('Signing in to Gala.');
-    await signInGala({
-      apiBaseUrl,
-      showInstructions: ({ verificationUri, userCode }) =>
-        notify(`Open ${verificationUri}\nEnter code: ${userCode}`)
-    });
-    return readGala();
+    stored = null;
   }
+
+  if (stored != null) {
+    const base = stored.apiBaseUrl ?? apiBaseUrl;
+    if (await credentialAccepted({ apiBaseUrl: base, accessToken: stored.accessToken })) {
+      return stored;
+    }
+    // Leaving it on disk would make every later command repeat this discovery.
+    await forgetGala();
+    notify('Your Gala sign-in is no longer valid.');
+  }
+
+  notify('Signing in to Gala.');
+  await signInGala({
+    apiBaseUrl,
+    showInstructions: ({ verificationUri, userCode }) =>
+      notify(`${openUrl(verificationUri) ? 'Opened' : 'Open'} ${verificationUri}\nEnter code: ${userCode}`)
+  });
+  return readGala();
 }
 
-async function ensureGithub({ notify, readGithub, signInGithub }) {
+async function ensureGithub({ notify, readGithub, signInGithub, openUrl }) {
   try {
     return await readGithub();
   } catch {
@@ -97,7 +127,7 @@ async function ensureGithub({ notify, readGithub, signInGithub }) {
     await signInGithub({
       showScopeWarning: ({ explanation }) => notify(`GitHub authorization: ${explanation}`),
       showInstructions: ({ verificationUri, userCode }) =>
-        notify(`Open ${verificationUri}\nEnter code: ${userCode}`)
+        notify(`${openUrl(verificationUri) ? 'Opened' : 'Open'} ${verificationUri}\nEnter code: ${userCode}`)
     });
     return readGithub();
   }
@@ -112,7 +142,7 @@ async function ensureGithub({ notify, readGithub, signInGithub }) {
  */
 async function ensureInstallation({
   apiBaseUrl, galaAccessToken, githubAccessToken, owner,
-  notify, ask, installUrl, installAttempts, resolveInstallation
+  notify, ask, installUrl, installAttempts, resolveInstallation, openUrl
 }) {
   for (let attempt = 0; attempt < Math.max(1, installAttempts); attempt += 1) {
     const installationId = await resolveInstallation({
@@ -122,15 +152,25 @@ async function ensureInstallation({
 
     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.'
+        `The Gala GitHub App is not installed on ${owner}. Install it at ${installUrl} and run `
+        + 'scaffold again, or pass --installation-id explicitly.'
       );
     }
-    notify(`The Gala GitHub App is not installed on ${owner} yet.\nOpen ${installUrl}`);
+
+    // 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}, then run scaffold again.`
+    `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.'
   );
 }