@rathnasgala/cli 0.0.12 → 0.0.13

package/README.md

@@ -9,7 +9,7 @@ The quick start below begins with the required accounts and tools and does not a
 - [Git](https://git-scm.com/downloads)
 - [Node.js 24](https://nodejs.org/en/download) recommended; the CLI package supports Node.js 18 or newer
 - A [GitHub account](https://github.com/signup)
-- The [Gala GitHub App](https://github.com/apps/gala67-app/installations/new) installed for the account that will own the publication
+- The [Gala GitHub App](https://github.com/apps/gala67-app/installations/new) — `scaffold` walks you through installing it if it is not already
 
 Check your local tools:
 
@@ -28,42 +28,47 @@ git version 2.50.1 (Apple Git-155)
 
 ## Quick start
 
-### 1. Authenticate with Gala
+One command, run inside an empty folder named after the publication you want:
 
 ```console
-npx --yes @rathnasgala/cli@latest auth
-```
-
-The CLI displays a short code and opens the platform authorization page. The resulting Gala token is stored in your operating system's application-config directory, never in the publication repository.
-
-### 2. Authenticate with GitHub
-
-```console
-npx --yes @rathnasgala/cli@latest auth github
+mkdir field-notes && cd field-notes
+npx --yes @rathnasgala/cli@latest scaffold --target ./ --mode build-and-deploy
 ```
 
-GitHub OAuth Apps cannot restrict `repo` access to one repository. The CLI therefore requests:
+That single command does all of the following, and asks only for what it cannot work out:
 
-- `repo` to create the publication repository and install its Actions secret
-- `workflow` for initial scaffolding and explicit Action-major migrations
+1. **Signs you in to Gala** if no valid token is stored, showing a code to enter in the browser.
+2. **Signs you in to GitHub** the same way, requesting `repo` to create the publication and install
+   its Actions secret, and `workflow` for the initial scaffold. Ordinary publishing needs neither.
+3. **Reads your GitHub account** from that token, so there is no username to type.
+4. **Finds the Gala GitHub App installation** for your account. If the App is not installed yet it
+   prints the installation page, waits while you install it, and carries on — the installation ID
+   is never something you have to read out of a URL.
+5. **Names the publication** after the folder you are standing in.
+6. **Creates the repository** from the site template, registers it, installs its one-time secret,
+   writes the publication workflow, commits, and enables GitHub Pages.
 
-The GitHub token is stored outside the repository with private file permissions. Gala does not require `workflow` for ordinary publishing or patch upgrades.
+Both sign-ins are skipped when a valid credential is already stored, so re-running is cheap.
 
-### 3. Install the GitHub App
+After scaffolding succeeds, open [GitHub App settings](https://github.com/settings/installations)
+and restrict the App to the publication repository if you installed it against all of them.
 
-Open the [Gala GitHub App installation page](https://github.com/apps/gala67-app/installations/new). For a new publication, select **All repositories** temporarily because the target repository does not exist yet.
+### Write, preview, and publish
 
-After installation, GitHub redirects to a URL ending in a number, for example:
-
-```text
-https://github.com/settings/installations/153144989
+```console
+npx --yes @rathnasgala/cli@latest new --title "My first post" --language en
+npx --yes @rathnasgala/cli@latest preview
+npx --yes @rathnasgala/cli@latest publish
 ```
 
-That final number is the installation ID required by `scaffold`.
+`new` prints the Markdown file it created. Write below the second `---` line, save the file,
+preview it locally, then publish it through GitHub.
 
-### 4. Scaffold the publication
+### Overriding what scaffold works out
 
-Replace every capitalized placeholder:
+Every derived value is still an explicit flag, for the cases where the default is wrong — a
+publication owned by an organisation, a folder named differently from the repository, or more than
+one App installation on the account:
 
 ```console
 npx --yes @rathnasgala/cli@latest scaffold \
@@ -74,20 +79,9 @@ npx --yes @rathnasgala/cli@latest scaffold \
   --mode build-and-deploy
 ```
 
-Scaffolding creates a public repository from `rathnasgala/site-template`, registers the site, installs the one-time site secret as a GitHub Actions secret, writes the publication workflow, commits the generated configuration, and enables GitHub Pages.
-
-After scaffolding succeeds, open [GitHub App settings](https://github.com/settings/installations) and restrict the App to the publication repository.
-
-### 5. Write, preview, and publish
-
-```console
-cd YOUR_REPOSITORY_NAME
-npx --yes @rathnasgala/cli@latest new --title "My first post" --language en
-npx --yes @rathnasgala/cli@latest preview
-npx --yes @rathnasgala/cli@latest publish
-```
-
-`new` prints the Markdown file it created. Write below the second `---` line, save the file, preview it locally, then publish it through GitHub.
+`--repository` is otherwise taken from `--target`, then from `--site-name`, and only then asked
+for. Outside a terminal — in CI — nothing is ever prompted for: a value that cannot be derived is
+an error, so an automated run fails fast instead of waiting for an answer that will not come.
 
 ## Command reference
 
@@ -103,7 +97,7 @@ Inside the table below, `gala` is shorthand for that prefix.
 | --- | --- | --- |
 | `gala auth` | Authenticate the author with Gala | `--api-base-url URL` for a non-production API |
 | `gala auth github` | Authenticate the CLI with GitHub | Browser device flow; requests `repo workflow` |
-| `gala scaffold` | Create and register a publication | `--owner`, `--repository`, `--target`, `--installation-id`, `--mode` |
+| `gala scaffold` | Sign in if needed, then create and register a publication | All derived; override with `--owner`, `--repository`, `--target`, `--installation-id`, `--mode` |
 | `gala configure` | Update author-owned site and design settings | `--root`, plus the configuration options below |
 | `gala new` | Create a Markdown post variant | `--root`, `--title`, `--language`, `--today` |
 | `gala validate` | Validate repository content without publishing | optional root path, `--today` |
@@ -148,10 +142,7 @@ Use this only when the exact GitHub repository already exists and has no branche
 
 ```console
 npx --yes @rathnasgala/cli@latest scaffold \
-  --owner YOUR_GITHUB_USERNAME \
   --repository YOUR_REPOSITORY_NAME \
-  --target ./YOUR_REPOSITORY_NAME \
-  --installation-id YOUR_INSTALLATION_ID \
   --empty-existing-repository
 ```
 
@@ -161,10 +152,8 @@ The target must already be a checkout whose HTTPS origin exactly matches the req
 
 ```console
 npx --yes @rathnasgala/cli@latest scaffold \
-  --owner YOUR_GITHUB_USERNAME \
   --repository YOUR_REPOSITORY_NAME \
   --target ./YOUR_REPOSITORY_NAME \
-  --installation-id YOUR_INSTALLATION_ID \
   --resume
 ```
 
@@ -237,9 +226,12 @@ Gala author tokens expire and do not use a refresh token. Run:
 npx --yes @rathnasgala/cli@latest auth
 ```
 
-### `githubInstallationId must be a positive integer`
+### `The Gala GitHub App is not installed on YOUR_ACCOUNT`
 
-Open [GitHub App settings](https://github.com/settings/installations), select Gala, and copy the number at the end of the browser URL.
+`scaffold` could not find an installation covering that account. At a terminal it prints the
+installation page and waits; in CI it stops, because there is nobody to install it. Install the App
+at [the installation page](https://github.com/apps/gala67-app/installations/new) and run `scaffold`
+again, or pass `--installation-id` explicitly.
 
 ### The App cannot access the new repository
 

package/package.json

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

package/src/gala-installation-client.js

@@ -0,0 +1,75 @@
+/**
+ * Which Gala GitHub App installation covers this writer's account.
+ *
+ * The installation ID is an internal GitHub identifier that `scaffold` has to send when it
+ * registers a site. Until now the writer supplied it by installing the App, watching GitHub
+ * redirect to `https://github.com/settings/installations/153144989`, and copying the number out of
+ * the address bar — an internal identifier, read out of a URL, by hand.
+ *
+ * The Gala API already knows it. `GET /v1/auth/github/repositories` answers with
+ * `{ installationId, owner, name, status }` per repository, so the CLI can ask the same service it
+ * is about to register with rather than guess. Reaching that endpoint needs the bounded capability
+ * from `POST /v1/auth/github/device-authorizations`, which is bound to the Gala user and takes the
+ * GitHub token the CLI already holds.
+ */
+function endpoint(apiBaseUrl, path) {
+  return `${String(apiBaseUrl).replace(/\/$/, '')}${path}`;
+}
+
+export async function exchangeGithubAuthorization({
+  apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl = fetch
+}) {
+  const response = await fetchImpl(endpoint(apiBaseUrl, '/v1/auth/github/device-authorizations'), {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${galaAccessToken}`,
+      'content-type': 'application/json'
+    },
+    body: JSON.stringify({ accessToken: githubAccessToken })
+  });
+  if (!response.ok) {
+    throw new Error(`GitHub authorization exchange failed with HTTP ${response.status}`);
+  }
+  const payload = await response.json();
+  if (typeof payload?.authorization !== 'string') {
+    throw new TypeError('GitHub authorization exchange returned no capability');
+  }
+  return payload.authorization;
+}
+
+export async function listAuthorizedRepositories({ apiBaseUrl, authorization, fetchImpl = fetch }) {
+  const response = await fetchImpl(endpoint(apiBaseUrl, '/v1/auth/github/repositories'), {
+    headers: { accept: 'application/json', 'GitHub-Authorization': authorization }
+  });
+  if (!response.ok) {
+    throw new Error(`Authorized repository lookup failed with HTTP ${response.status}`);
+  }
+  const payload = await response.json();
+  if (!Array.isArray(payload)) throw new TypeError('Authorized repository lookup returned no list');
+  return payload;
+}
+
+/**
+ * Returns the installation covering `owner`, or null when the App is not installed there.
+ *
+ * An installation belongs to an account, not to one repository, so any repository the App can
+ * already see under that owner carries the id the new one will use. Null is an ordinary answer —
+ * it means "not installed yet" — and the caller turns it into an instruction, not an error.
+ */
+export async function resolveInstallationId({
+  apiBaseUrl, galaAccessToken, githubAccessToken, owner, fetchImpl = fetch,
+  exchange = exchangeGithubAuthorization, list = listAuthorizedRepositories
+}) {
+  const authorization = await exchange({
+    apiBaseUrl, galaAccessToken, githubAccessToken, fetchImpl
+  });
+  const repositories = await list({ apiBaseUrl, authorization, fetchImpl });
+  const wanted = String(owner).toLowerCase();
+  for (const repository of repositories) {
+    if (String(repository?.owner).toLowerCase() !== wanted) continue;
+    const installationId = Number(repository?.installationId);
+    if (Number.isSafeInteger(installationId) && installationId > 0) return installationId;
+  }
+  return null;
+}

package/src/github-identity.js

@@ -0,0 +1,31 @@
+const GITHUB_API_VERSION = '2026-03-10';
+
+/**
+ * The GitHub account the stored credential belongs to.
+ *
+ * `scaffold` used to make the writer pass `--owner`, which is a value the token already knows and
+ * they can only get wrong. The credential file holds the token and its scopes and nothing else, so
+ * this is a live lookup rather than something cached at `auth github` time — a login can be
+ * changed, and a stale one would create the repository under a name that no longer exists.
+ */
+export async function resolveGithubLogin({ accessToken, fetchImpl = fetch }) {
+  if (typeof accessToken !== 'string' || accessToken === '') {
+    throw new TypeError('accessToken is required');
+  }
+  const response = await fetchImpl('https://api.github.com/user', {
+    headers: {
+      accept: 'application/vnd.github+json',
+      authorization: `Bearer ${accessToken}`,
+      'x-github-api-version': GITHUB_API_VERSION
+    }
+  });
+  if (!response.ok) throw new Error(`GitHub account lookup failed with HTTP ${response.status}`);
+  const payload = await response.json();
+  const login = payload?.login;
+  // The same shape `scaffold` demands of `--owner`. Refusing here beats a confusing failure four
+  // API calls later.
+  if (typeof login !== 'string' || !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/.test(login)) {
+    throw new TypeError('GitHub returned an unusable account login');
+  }
+  return login;
+}

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 { prepareScaffold } from './scaffold-preflight.js';
 import { refreshEngagementSnapshot } from './refresh-command.js';
 import { switchTopology } from './topology-command.js';
 import { acquireAttributionEntitlement } from './entitlement-command.js';
@@ -77,17 +78,37 @@ if (command === 'auth') {
     const index = args.indexOf(name);
     return index === -1 ? undefined : args[index + 1];
   };
-  const installationId = Number(valueFor('--installation-id'));
+  const explicitInstallationId = valueFor('--installation-id');
   const topology = valueFor('--topology') ?? 'provider-default';
-  const result = await scaffoldSite({
+  const siteOptions = parseScaffoldOptions(args);
+  // Prompting only makes sense at a terminal. In CI there is nobody to answer, so a missing value
+  // has to stay a clear error rather than a process that hangs waiting for enter.
+  const interactive = process.stdin.isTTY === true;
+  const ask = interactive
+    ? async (question) => {
+      const terminal = createInterface({ input: process.stdin, output: process.stdout });
+      try { return await terminal.question(question); } finally { terminal.close(); }
+    }
+    : undefined;
+  const prepared = await prepareScaffold({
     owner: valueFor('--owner'),
     repository: valueFor('--repository'),
     target: valueFor('--target'),
-    githubInstallationId: installationId,
+    githubInstallationId: explicitInstallationId == null ? undefined : Number(explicitInstallationId),
+    siteName: siteOptions.siteName,
+    apiBaseUrl: valueFor('--api-base-url') ?? 'https://api.gala67.com',
+    notify: (message) => process.stdout.write(`${message}\n`),
+    ask
+  });
+  const result = await scaffoldSite({
+    owner: prepared.owner,
+    repository: prepared.repository,
+    target: prepared.target,
+    githubInstallationId: prepared.githubInstallationId,
     topology,
     canonicalBaseUrl: valueFor('--canonical-base-url'),
     actionRef: valueFor('--action-ref'),
-    siteOptions: parseScaffoldOptions(args),
+    siteOptions,
     buildMode: valueFor('--mode') ?? 'build-and-deploy',
     emptyExistingRepository: args.includes('--empty-existing-repository'),
     resumeExistingCheckout: args.includes('--resume')

package/src/scaffold-preflight.js

@@ -0,0 +1,154 @@
+import path from 'node:path';
+
+import { authenticateGala } from './auth-command.js';
+import { authenticateGithub } from './github-auth-command.js';
+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';
+
+export const GITHUB_APP_INSTALL_URL = 'https://github.com/apps/gala67-app/installations/new';
+
+const DEFAULT_API_BASE_URL = 'https://api.gala67.com';
+
+/**
+ * Everything `scaffold` needs, worked out rather than demanded.
+ *
+ * `scaffold` used to require four values up front — `--owner`, `--repository`, `--target` and
+ * `--installation-id` — and it failed outright if `auth` or `auth github` had not been run first,
+ * telling the writer to go and run them. Three of those four are derivable and the two sign-ins
+ * can simply happen. Every one of them is still accepted as an explicit override; nothing that
+ * worked before stops working.
+ *
+ * The steps are ordered so nothing is created until everything is known: the App installation is
+ * confirmed before a repository exists, rather than after, so an interrupted run leaves no
+ * half-connected repository behind.
+ */
+export async function prepareScaffold({
+  owner,
+  repository,
+  target,
+  githubInstallationId,
+  siteName,
+  cwd = process.cwd(),
+  notify = () => {},
+  ask,
+  installUrl = GITHUB_APP_INSTALL_URL,
+  installAttempts = 3,
+  readGala = readGalaCredential,
+  readGithub = readGithubCredential,
+  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 resolvedOwner = owner ?? await resolveLogin({ accessToken: github.accessToken });
+
+  const resolvedRepository = repository
+    ?? (target == null ? null : path.basename(path.resolve(cwd, target)))
+    ?? repositoryNameFrom(siteName)
+    ?? await askForRepository(ask);
+
+  // `--target ./` is the common case and means "here", so the repository takes its name from the
+  // directory the writer is standing in. Everywhere else the repository names its own folder.
+  const resolvedTarget = target ?? `./${resolvedRepository}`;
+
+  const resolvedInstallation = githubInstallationId
+    ?? await ensureInstallation({
+      apiBaseUrl: gala.apiBaseUrl ?? apiBaseUrl,
+      galaAccessToken: gala.accessToken,
+      githubAccessToken: github.accessToken,
+      owner: resolvedOwner,
+      notify, ask, installUrl, installAttempts, resolveInstallation
+    });
+
+  return Object.freeze({
+    owner: resolvedOwner,
+    repository: resolvedRepository,
+    target: resolvedTarget,
+    githubInstallationId: resolvedInstallation
+  });
+}
+
+/** A missing or expired credential is a step to take, not an error to report. */
+async function ensureGala({ apiBaseUrl, notify, readGala, signInGala }) {
+  try {
+    return await readGala();
+  } catch {
+    notify('Signing in to Gala.');
+    await signInGala({
+      apiBaseUrl,
+      showInstructions: ({ verificationUri, userCode }) =>
+        notify(`Open ${verificationUri}\nEnter code: ${userCode}`)
+    });
+    return readGala();
+  }
+}
+
+async function ensureGithub({ notify, readGithub, signInGithub }) {
+  try {
+    return await readGithub();
+  } catch {
+    notify('Signing in to GitHub.');
+    await signInGithub({
+      showScopeWarning: ({ explanation }) => notify(`GitHub authorization: ${explanation}`),
+      showInstructions: ({ verificationUri, userCode }) =>
+        notify(`Open ${verificationUri}\nEnter code: ${userCode}`)
+    });
+    return readGithub();
+  }
+}
+
+/**
+ * Confirms the Gala GitHub App is installed, walking the writer through installing it if not.
+ *
+ * This is the step that used to be a manual detour through GitHub's settings to copy a number out
+ * of a redirect URL. The loop is what makes it a step rather than a failure: the writer installs
+ * the App in the browser, comes back, presses enter, and the run continues.
+ */
+async function ensureInstallation({
+  apiBaseUrl, galaAccessToken, githubAccessToken, owner,
+  notify, ask, installUrl, installAttempts, resolveInstallation
+}) {
+  for (let attempt = 0; attempt < Math.max(1, installAttempts); attempt += 1) {
+    const installationId = await resolveInstallation({
+      apiBaseUrl, galaAccessToken, githubAccessToken, owner
+    });
+    if (installationId != null) return installationId;
+
+    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.'
+      );
+    }
+    notify(`The Gala GitHub App is not installed on ${owner} yet.\nOpen ${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.`
+  );
+}
+
+/** GitHub repository names allow letters, digits, dot, underscore and hyphen, and nothing else. */
+export function repositoryNameFrom(siteName) {
+  if (typeof siteName !== 'string') return null;
+  const slug = siteName
+    .trim().toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug === '' ? null : slug;
+}
+
+async function askForRepository(ask) {
+  if (typeof ask !== 'function') {
+    throw new TypeError('repository is required; pass --repository or --site-name');
+  }
+  const answer = repositoryNameFrom(await ask('What should the publication repository be called? '));
+  if (answer == null) throw new TypeError('A repository name is required');
+  return answer;
+}