@rathnasgala/cli 0.0.21 → 1.0.0

package/src/auth/gala.js

@@ -0,0 +1,52 @@
+import { galaApi, DEFAULT_API_BASE_URL } from '../api/gala.js';
+import { credentialPath, forgetCredential, readCredential, writeCredential } from './store.js';
+
+/**
+ * The Gala sign-in.
+ *
+ * A stored credential is checked against the server before anything depends on it, because one
+ * that parses and has not expired can still be one the API refuses — and discovering that four
+ * calls later, as an opaque 401 from whichever endpoint got there first, is how a "sign in again"
+ * became a stack trace.
+ */
+export async function galaCredential({
+  terminal,
+  apiBaseUrl = DEFAULT_API_BASE_URL,
+  target = credentialPath('credentials'),
+  now = Date.now
+}) {
+  const stored = await readCredential(target);
+  if (stored != null) {
+    const accepted = await galaApi({ baseUrl: stored.apiBaseUrl ?? apiBaseUrl, token: stored.accessToken }).accepted();
+    if (accepted) return stored;
+    // Leaving it on disk makes every later command rediscover that it is refused.
+    await forgetCredential(target);
+    terminal.step('Your Gala sign-in is no longer valid');
+  }
+
+  const api = galaApi({ baseUrl: apiBaseUrl });
+  const authorization = await api.startDeviceAuthorization();
+  terminal.step('Sign in to Gala');
+  terminal.openUrl(authorization.verification_uri);
+  terminal.note(`code ${authorization.user_code}`);
+
+  const token = await poll(api, authorization, now);
+  await writeCredential(target, {
+    accessToken: token.access_token,
+    apiBaseUrl,
+    expiresAt: new Date(now() + token.expires_in * 1000).toISOString()
+  });
+  terminal.done('Signed in to Gala');
+  return readCredential(target);
+}
+
+async function poll(api, authorization, now) {
+  const deadline = now() + authorization.expires_in * 1000;
+  const interval = Math.max(1, authorization.interval ?? 5) * 1000;
+  while (now() < deadline) {
+    await new Promise((resolve) => { setTimeout(resolve, interval); });
+    const token = await api.pollDeviceAuthorization(authorization.device_code);
+    if (token != null) return token;
+  }
+  throw new Error('Gala sign-in expired before it was authorized');
+}

package/src/auth/github.js

@@ -0,0 +1,78 @@
+import { credentialPath, readCredential, writeCredential } from './store.js';
+
+/**
+ * The GitHub sign-in, as the Gala App.
+ *
+ * v0 authenticated as a separate OAuth App while the browser editor used the GitHub App. They are
+ * two different identity systems and every difference fell on the CLI: an OAuth token cannot list
+ * App installations, organisations with OAuth App restrictions refuse it outright, and it inherits
+ * none of the App's repository grants. The editor hit none of that, which is why the two behaved
+ * so differently for so long.
+ *
+ * Client IDs are public; this is the value `GET /apps/gala67-app` publishes.
+ */
+export const APP_CLIENT_ID = 'Iv23liIg7Hi1lMesiaon';
+
+const DEVICE_CODE_URL = 'https://github.com/login/device/code';
+const ACCESS_TOKEN_URL = 'https://github.com/login/oauth/access_token';
+
+export async function githubCredential({
+  terminal,
+  clientId = APP_CLIENT_ID,
+  target = credentialPath('github-credentials'),
+  now = Date.now
+}) {
+  const stored = await readCredential(target);
+  if (stored != null) return stored;
+
+  // No scopes. A GitHub App's permissions are fixed on the app and granted when the writer installs
+  // it, so there is nothing to negotiate — and nothing to warn them about, which is why the broad
+  // "read/write on every repository you can access" notice is gone.
+  const authorization = await post(DEVICE_CODE_URL, { client_id: clientId }, 'GitHub sign-in');
+  terminal.step('Sign in to GitHub');
+  terminal.openUrl(authorization.verification_uri);
+  terminal.note(`code ${authorization.user_code}`);
+
+  const token = await poll(clientId, authorization, now);
+  await writeCredential(target, {
+    accessToken: token.access_token,
+    // The app expires user tokens after eight hours and issues a refresh token with each. Exchanging
+    // one needs the app's client secret, which a published CLI cannot hold — so it is kept for the
+    // API-side refresh, and until that exists an expired credential asks for one sign-in rather
+    // than failing as an unexplained 401 somewhere deeper.
+    ...(token.expires_in ? { expiresAt: new Date(now() + token.expires_in * 1000).toISOString() } : {}),
+    ...(token.refresh_token ? { refreshToken: token.refresh_token } : {})
+  });
+  terminal.done('Signed in to GitHub');
+  return readCredential(target);
+}
+
+async function poll(clientId, authorization, now) {
+  const deadline = now() + authorization.expires_in * 1000;
+  let interval = Math.max(1, authorization.interval ?? 5) * 1000;
+  while (now() < deadline) {
+    await new Promise((resolve) => { setTimeout(resolve, interval); });
+    const payload = await post(ACCESS_TOKEN_URL, {
+      client_id: clientId,
+      device_code: authorization.device_code,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code'
+    }, 'GitHub sign-in');
+    if (typeof payload.access_token === 'string' && payload.access_token !== '') return payload;
+    if (payload.error === 'slow_down') interval += 5000;
+    else if (payload.error !== 'authorization_pending') {
+      throw new Error(`GitHub sign-in failed: ${payload.error_description ?? payload.error}`);
+    }
+  }
+  throw new Error('GitHub sign-in expired before it was authorized');
+}
+
+async function post(url, form, action) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { accept: 'application/json', 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(form).toString()
+  });
+  const payload = await response.json().catch(() => null);
+  if (payload == null) throw new Error(`${action} returned an unreadable response`);
+  return payload;
+}

package/src/auth/store.js

@@ -0,0 +1,88 @@
+import { chmod, mkdir, lstat, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Where credentials live, and the rules for reading them.
+ *
+ * Two rules matter more than the storage itself, both learned the hard way:
+ *
+ * A credential is only valid if the server still accepts it. v0 checked expiry and nothing else, so
+ * a token the API had already decided to refuse — it stopped issuing a claim these carried — was
+ * handed out for weeks, and every command failed as an unexplained 401 several calls deep.
+ *
+ * A credential whose shape has changed is not upgradable in place. Bumping `schemaVersion` and
+ * refusing the old one sends the writer through one sign-in, which is the only honest answer.
+ *
+ * Plaintext at 0600 protects against other users and stray backups, not against anything running
+ * as the writer. Moving to the OS keychain is tracked separately; the file stays as the fallback
+ * for platforms without one.
+ */
+const SCHEMA_VERSION = 2;
+
+export function credentialPath(name, { platform = process.platform, environment = process.env, home = os.homedir() } = {}) {
+  if (platform === 'win32') {
+    if (!environment.APPDATA) throw new Error('APPDATA is required to store credentials on Windows');
+    return path.join(environment.APPDATA, 'Gala', `${name}.json`);
+  }
+  if (platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'Gala', `${name}.json`);
+  }
+  return path.join(environment.XDG_CONFIG_HOME || path.join(home, '.config'), 'gala', `${name}.json`);
+}
+
+export async function writeCredential(target, record) {
+  const directory = path.dirname(path.resolve(target));
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+  await refuseSymbolicLink(target);
+
+  const temporary = `${target}.gala-${process.pid}`;
+  try {
+    await writeFile(temporary, `${JSON.stringify({ schemaVersion: SCHEMA_VERSION, ...record })}\n`, {
+      flag: 'wx', mode: 0o600
+    });
+    await chmod(temporary, 0o600);
+    // Renaming over the target is what makes a half-written credential impossible.
+    await rename(temporary, target);
+    return path.resolve(target);
+  } catch (failure) {
+    await rm(temporary, { force: true });
+    throw failure;
+  }
+}
+
+/** Returns null when there is nothing usable, so callers branch on presence rather than on errors. */
+export async function readCredential(target, { now = new Date() } = {}) {
+  let payload;
+  try {
+    await refuseSymbolicLink(target);
+    payload = JSON.parse(await readFile(target, 'utf8'));
+  } catch (missing) {
+    if (missing?.code === 'ENOENT') return null;
+    if (missing instanceof SyntaxError) return null;
+    throw missing;
+  }
+  if (payload?.schemaVersion !== SCHEMA_VERSION) return null;
+  if (typeof payload.accessToken !== 'string' || payload.accessToken === '') return null;
+  if (typeof payload.expiresAt === 'string') {
+    const expiresAt = new Date(payload.expiresAt);
+    if (Number.isNaN(expiresAt.getTime()) || expiresAt <= now) return null;
+  }
+  return payload;
+}
+
+export async function forgetCredential(target) {
+  await rm(target, { force: true });
+}
+
+async function refuseSymbolicLink(target) {
+  try {
+    const metadata = await lstat(target);
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+      throw new TypeError('Credential must be a regular file');
+    }
+  } catch (missing) {
+    if (missing?.code !== 'ENOENT') throw missing;
+  }
+}

package/src/cli/args.js

@@ -0,0 +1,56 @@
+/**
+ * Argument parsing, deliberately small.
+ *
+ * v0 read arguments with `args.indexOf(name)` at each use site, so a mistyped flag was silently
+ * ignored and the same flag could be read twice with different defaults in two places. Parsing
+ * once and rejecting anything unrecognised is the difference between a typo that fails immediately
+ * and one that quietly changes what the command does.
+ */
+export function parseArguments(argv, { flags = [], switches = [] } = {}) {
+  const values = new Map();
+  const positional = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+
+    const [name, inline] = splitOnce(token.slice(2));
+    if (switches.includes(name)) {
+      if (inline != null) throw new UsageError(`--${name} takes no value`);
+      values.set(name, true);
+      continue;
+    }
+    if (!flags.includes(name)) throw new UsageError(`unknown option --${name}`);
+    if (values.has(name)) throw new UsageError(`--${name} given more than once`);
+
+    const value = inline ?? argv[index + 1];
+    if (value == null || (inline == null && value.startsWith('--'))) {
+      throw new UsageError(`--${name} needs a value`);
+    }
+    if (inline == null) index += 1;
+    values.set(name, value);
+  }
+
+  return {
+    positional,
+    value: (name) => (typeof values.get(name) === 'string' ? values.get(name) : undefined),
+    on: (name) => values.get(name) === true
+  };
+}
+
+/** Supports `--name value` and `--name=value`; only the first `=` separates. */
+function splitOnce(token) {
+  const at = token.indexOf('=');
+  return at === -1 ? [token, undefined] : [token.slice(0, at), token.slice(at + 1)];
+}
+
+/** How the command was invoked is wrong, as opposed to something failing while it ran. */
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}

package/src/cli/terminal.js

@@ -0,0 +1,104 @@
+import { createInterface } from 'node:readline/promises';
+import { spawn } from 'node:child_process';
+
+/**
+ * Everything the writer sees or is asked, in one place.
+ *
+ * v0 wrote to stdout from a dozen modules with no shared shape, so a scaffold emitted raw git
+ * output, bare status codes and half-sentences in whatever order they happened to occur. The
+ * failure mode that cost the most was subtler: prompts and browser launches were decided
+ * separately in each module, so behaviour with no terminal attached varied by code path — some
+ * hung, some crashed, some silently skipped.
+ *
+ * One object, created once, knows whether there is a terminal. Nothing else has to ask.
+ */
+export function createTerminal({
+  input = process.stdin,
+  output = process.stdout,
+  errorOutput = process.stderr,
+  environment = process.env,
+  spawnProcess = spawn
+} = {}) {
+  const interactive = input.isTTY === true && output.isTTY === true;
+  const plain = !interactive || environment.NO_COLOR != null || environment.TERM === 'dumb';
+  const paint = (code, text) => (plain ? text : `\u001b[${code}m${text}\u001b[0m`);
+
+  return {
+    interactive,
+
+    /** A step that is happening now. */
+    step: (message) => output.write(`  ${paint('90', '·')} ${message}\n`),
+
+    /** A step that finished. */
+    done: (message) => output.write(`  ${paint('32', '✓')} ${message}\n`),
+
+    /** The thing the writer wanted, at the end. */
+    result: (message) => output.write(`\n  ${paint('1', message)}\n`),
+
+    note: (message) => output.write(`    ${paint('90', message)}\n`),
+
+    blank: () => output.write('\n'),
+
+    fail: (message) => errorOutput.write(`\n  ${paint('31', 'x')} ${message}\n\n`),
+
+    /**
+     * Asks a question, or refuses to.
+     *
+     * Returning a default without a terminal is what keeps CI honest: a prompt that silently
+     * resolves to a guess is worse than one that stops and names the flag to pass instead.
+     */
+    async ask(question, { fallback } = {}) {
+      if (!interactive) {
+        if (fallback !== undefined) return fallback;
+        throw new Error(`${question} — no terminal to ask; pass it as an option instead`);
+      }
+      const reader = createInterface({ input, output });
+      try {
+        const answer = await reader.question(`  ${paint('36', '?')} ${question} `);
+        return answer.trim();
+      } finally {
+        reader.close();
+      }
+    },
+
+    /** Waits for the writer to finish something in a browser. */
+    async waitForEnter(message) {
+      if (!interactive) return false;
+      await this.ask(`${message} (press enter)`);
+      return true;
+    },
+
+    /**
+     * Opens a URL, best effort, and always prints it.
+     *
+     * Never attempted without a terminal: a CI job spawning a browser is a hang waiting to happen
+     * and there is nobody there to look at it. The URL is printed either way, because it is the
+     * thing a writer moves to another device.
+     */
+    openUrl(url) {
+      const opened = interactive
+        && environment.CI == null
+        && environment.NO_BROWSER == null
+        && environment.GALA_NO_BROWSER == null
+        && /^https:\/\//.test(url)
+        && launch(url, spawnProcess);
+      output.write(`    ${paint('90', opened ? 'opened' : 'open')} ${paint('4', url)}\n`);
+      return opened;
+    }
+  };
+}
+
+function launch(url, spawnProcess) {
+  const [command, args] = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  try {
+    const child = spawnProcess(command, args, { stdio: 'ignore', detached: true, shell: false });
+    child.unref?.();
+    // A machine with no opener is an ordinary outcome, not something to report.
+    child.on?.('error', () => {});
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/commands/auth.js

@@ -0,0 +1,20 @@
+import { galaCredential } from '../auth/gala.js';
+import { githubCredential } from '../auth/github.js';
+
+/**
+ * Signs in to both, and says so.
+ *
+ * Not a prerequisite the writer has to remember: every command that needs a credential obtains one.
+ * This exists for the times they want to do it deliberately — a new machine, a different account,
+ * or after a token has expired.
+ */
+export async function auth({ terminal, options }) {
+  const gala = await galaCredential({ terminal, apiBaseUrl: options.value('api-base-url') });
+  const github = await githubCredential({ terminal });
+
+  terminal.blank();
+  terminal.done(`Gala   — valid until ${new Date(gala.expiresAt).toLocaleString()}`);
+  terminal.done(github.expiresAt
+    ? `GitHub — valid until ${new Date(github.expiresAt).toLocaleString()}`
+    : 'GitHub — signed in');
+}

package/src/commands/doctor.js

@@ -0,0 +1,98 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { galaApi } from '../api/gala.js';
+import { galaCredential } from '../auth/gala.js';
+import { githubCredential } from '../auth/github.js';
+import { createGit } from '../git.js';
+
+/**
+ * Answers "why is this not working" without the writer having to know where to look.
+ *
+ * Every check reports one of three things and never guesses between them: it is fine, it is wrong
+ * and here is the fix, or it could not be determined. That third state is the one v0 kept
+ * collapsing into the second — an unreachable GitHub reported as "the App is not installed" sent
+ * writers to install something that was already installed, repeatedly.
+ */
+export async function doctor({ terminal, options, cwd = process.cwd() }) {
+  const root = path.resolve(options.value('root') ?? cwd);
+  const checks = [];
+
+  checks.push(await checkCredential('Gala sign-in', async () => {
+    const gala = await galaCredential({ terminal, apiBaseUrl: options.value('api-base-url') });
+    const accepted = await galaApi({ baseUrl: gala.apiBaseUrl, token: gala.accessToken }).accepted();
+    return accepted
+      ? ok(`valid until ${new Date(gala.expiresAt).toLocaleString()}`)
+      : wrong('the API no longer accepts it', 'gala auth');
+  }));
+
+  checks.push(await checkCredential('GitHub sign-in', async () => {
+    const github = await githubCredential({ terminal });
+    return ok(github.expiresAt
+      ? `valid until ${new Date(github.expiresAt).toLocaleString()}`
+      : 'signed in');
+  }));
+
+  checks.push(await check('Publication folder', async () => {
+    const config = path.join(root, 'site.config.yml');
+    await stat(config);
+    const posts = await countPosts(root);
+    return ok(`${posts} post${posts === 1 ? '' : 's'}`);
+  }, 'run this inside a publication, or pass --root'));
+
+  checks.push(await check('Publishing workflow', async () => {
+    const workflow = path.join(root, '.github', 'workflows', 'publish.yml');
+    const source = await readFile(workflow, 'utf8');
+    const siteId = /site-id:\s*([0-9A-Z]{26})/.exec(source)?.[1];
+    return siteId == null
+      ? wrong('no site id — this publication may not be registered', 'gala init')
+      : ok(siteId);
+  }, 'the workflow is missing; registration writes it'));
+
+  checks.push(await check('Unsent work', async () => {
+    const git = createGit({ root });
+    const dirty = await git.run(['status', '--porcelain'], { capture: true });
+    const ahead = await git.run(['rev-list', '--count', '@{upstream}..HEAD'], { capture: true, allow: [0, 128] });
+    if (dirty !== '') return wrong(`${dirty.split('\n').length} file(s) not recorded`, 'gala publish');
+    if (ahead !== '' && ahead !== '0') return wrong(`${ahead} commit(s) not sent`, 'gala publish');
+    return ok('everything is on GitHub');
+  }, 'this folder is not a git checkout'));
+
+  terminal.blank();
+  for (const { name, state, detail, fix } of checks) {
+    if (state === 'ok') terminal.done(`${name} — ${detail}`);
+    else if (state === 'wrong') terminal.fail(`${name} — ${detail}`);
+    else terminal.step(`${name} — could not be determined: ${detail}`);
+    if (fix) terminal.note(fix);
+  }
+
+  const broken = checks.filter(({ state }) => state === 'wrong');
+  if (broken.length > 0) throw new Error(`${broken.length} problem(s) found`);
+  terminal.blank();
+  terminal.note('Nothing looks wrong.');
+}
+
+const ok = (detail) => ({ state: 'ok', detail });
+const wrong = (detail, fix) => ({ state: 'wrong', detail, fix });
+
+/** Distinguishes "this is wrong" from "I could not tell", which are different answers. */
+async function check(name, run, unknownHint) {
+  try {
+    return { name, ...await run() };
+  } catch (failure) {
+    return { name, state: 'unknown', detail: failure.message, fix: unknownHint };
+  }
+}
+
+/** Credentials are obtained rather than merely inspected, so doctor can also repair a sign-in. */
+const checkCredential = check;
+
+async function countPosts(root) {
+  try {
+    const posts = path.join(root, 'content', 'posts');
+    const entries = await readdir(posts, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).length;
+  } catch {
+    return 0;
+  }
+}