@rathnasgala/cli 0.0.14 → 0.0.15

package/package.json

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

package/src/index.js

@@ -20,6 +20,7 @@ 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';
@@ -44,6 +45,15 @@ function reportAndExit(failure) {
   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]';
 
@@ -77,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`);
@@ -87,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

@@ -7,6 +7,7 @@ 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';
@@ -37,6 +38,7 @@ export async function prepareScaffold({
   ask,
   installUrl = GITHUB_APP_INSTALL_URL,
   installAttempts = 3,
+  openUrl = openInBrowser,
   readGala = readGalaCredential,
   readGithub = readGithubCredential,
   credentialAccepted = galaCredentialAccepted,
@@ -48,9 +50,9 @@ export async function prepareScaffold({
   apiBaseUrl = DEFAULT_API_BASE_URL
 } = {}) {
   const gala = await ensureGala({
-    apiBaseUrl, notify, readGala, signInGala, credentialAccepted, forgetGala
+    apiBaseUrl, notify, readGala, signInGala, credentialAccepted, forgetGala, openUrl
   });
-  const github = await ensureGithub({ notify, readGithub, signInGithub });
+  const github = await ensureGithub({ notify, readGithub, signInGithub, openUrl });
 
   const resolvedOwner = owner ?? await resolveLogin({ accessToken: github.accessToken });
 
@@ -69,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({
@@ -88,7 +90,9 @@ export async function prepareScaffold({
  * 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 }) {
+async function ensureGala({
+  apiBaseUrl, notify, readGala, signInGala, credentialAccepted, forgetGala, openUrl
+}) {
   let stored = null;
   try {
     stored = await readGala();
@@ -110,12 +114,12 @@ async function ensureGala({ apiBaseUrl, notify, readGala, signInGala, credential
   await signInGala({
     apiBaseUrl,
     showInstructions: ({ verificationUri, userCode }) =>
-      notify(`Open ${verificationUri}\nEnter code: ${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 {
@@ -123,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();
   }
@@ -138,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({
@@ -148,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.'
   );
 }