@rathnasgala/cli 0.0.21 → 1.0.0

package/src/index.js

@@ -1,313 +1,60 @@
 #!/usr/bin/env node
+import { UsageError, parseArguments } from './cli/args.js';
+import { createTerminal } from './cli/terminal.js';
+import { COMMANDS } from './commands-manifest.js';
 
-import { parseScaffoldOptions } from './scaffold-options.js';
-import { regenerateBuildManifest } from './validate-command.js';
-import { createPost } from './new-command.js';
-import {
-  diagnoseFramework,
-  diagnosePublicationState,
-  repairFramework
-} from './doctor-command.js';
-import { configureSite } from './configure-site.js';
-import { previewSite } from './preview-command.js';
-import { writePublishWorkflow } from './workflow-command.js';
-import { publishSite } from './publish-command.js';
-import { installPrePushHook } from './hook-command.js';
-import { reportRepositoryLimitWarnings } from './repository-limits.js';
-import { recordDeployment } from './record-deployment-command.js';
-import { authenticateGala } from './auth-command.js';
-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);
+const [name, ...argv] = process.argv.slice(2);
+const terminal = createTerminal();
 
-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);
+if (name == null || name === 'help' || name === '--help' || name === '-h') {
+  usage();
+  process.exit(name == null ? 1 : 0);
 }
 
-/**
- * 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 = COMMANDS[name];
+if (command == null) {
+  terminal.fail(`there is no ${name} command`);
+  usage();
+  process.exit(1);
 }
 
-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]';
-
-if (command === 'help' || command === '--help' || command === '-h'
-    || args.includes('--help') || args.includes('-h')) {
-  process.stdout.write(`${usage}\n`);
+if (argv.includes('--help') || argv.includes('-h')) {
+  process.stdout.write(`\n  ${command.usage ?? `gala ${name}`}\n  ${command.summary}\n\n`);
   process.exit(0);
 }
 
-const recognizedCommands = new Set([
-  'auth', 'configure', 'validate', 'new', 'doctor', 'preview',
-  'workflow', 'publish', 'record-deployment', 'refresh', 'hook', 'upgrade', 'topology', 'entitlement'
-]);
-function commandRoot() {
-  const rootIndex = args.indexOf('--root');
-  if (rootIndex !== -1) return args[rootIndex + 1];
-  if (command === 'doctor' || command === 'validate') {
-    return args.find((argument, index) =>
-      !argument.startsWith('--')
-      && !['--today', '--source'].includes(args[index - 1])
-    ) ?? process.cwd();
-  }
-  return process.cwd();
-}
-if (recognizedCommands.has(command)) {
-  await reportRepositoryLimitWarnings(commandRoot());
+try {
+  const options = parseArguments(argv, { flags: command.flags ?? [], switches: command.switches ?? [] });
+  await command.run({ terminal, options });
+} catch (failure) {
+  report(failure);
+  process.exit(1);
 }
 
-if (command === 'auth') {
-  if (args[0] === 'github') {
-    const result = await authenticateGithub({
-      showScopeWarning: ({ explanation }) => process.stdout.write(`GitHub authorization: ${explanation}\n`),
-      showInstructions: ({ verificationUri, userCode }) => {
-        process.stdout.write(announce(verificationUri, userCode));
-      }
-    });
-    process.stdout.write(`GitHub authentication stored securely with scopes: ${result.scopes.join(', ')}.\n`);
-  } else {
-    const apiIndex = args.indexOf('--api-base-url');
-    const apiBaseUrl = apiIndex === -1 ? 'https://api.gala67.com' : args[apiIndex + 1];
-    const result = await authenticateGala({
-      apiBaseUrl,
-      showInstructions: ({ verificationUri, userCode }) => {
-        process.stdout.write(announce(verificationUri, userCode));
-      }
-    });
-    process.stdout.write(`Gala authentication stored securely until ${result.expiresAt.toISOString()}.\n`);
-  }
-} else if (command === 'scaffold') {
-  const valueFor = (name) => {
-    const index = args.indexOf(name);
-    return index === -1 ? undefined : args[index + 1];
-  };
-  const explicitInstallationId = valueFor('--installation-id');
-  const topology = valueFor('--topology') ?? 'provider-default';
-  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: 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({
-    notify: (message) => process.stdout.write(`${message}\n`),
-    ask,
-    openUrl: openInBrowser,
-    owner: prepared.owner,
-    repository: prepared.repository,
-    target: prepared.target,
-    githubInstallationId: prepared.githubInstallationId,
-    topology,
-    canonicalBaseUrl: valueFor('--canonical-base-url'),
-    actionRef: valueFor('--action-ref'),
-    siteOptions,
-    buildMode: valueFor('--mode') ?? 'build-and-deploy',
-    emptyExistingRepository: args.includes('--empty-existing-repository'),
-    resumeExistingCheckout: args.includes('--resume')
-  });
-  await reportRepositoryLimitWarnings(result.root);
-  process.stdout.write(`Scaffolded ${result.fullName} as Gala site ${result.siteId} in ${result.root}.\n`);
-} else if (command === 'configure') {
-  const rootIndex = args.indexOf('--root');
-  const root = rootIndex === -1 ? process.cwd() : args[rootIndex + 1];
-  const options = parseScaffoldOptions(args);
-  const config = await configureSite(root, options);
-  process.stdout.write(`${JSON.stringify(config.design, null, 2)}\n`);
-} else if (command === 'topology') {
-  const valueFor = (name) => {
-    const index = args.indexOf(name);
-    return index === -1 ? undefined : args[index + 1];
-  };
-  const result = await switchTopology({
-    root: valueFor('--root') ?? process.cwd(),
-    owner: valueFor('--owner'),
-    repository: valueFor('--repository'),
-    canonicalBaseUrl: valueFor('--canonical-base-url'),
-    pathPrefix: valueFor('--path-prefix') ?? '/'
-  });
-  process.stdout.write(`Committed topology ${result.changeId} at ${result.commitSha}.\n`);
-} else if (command === 'entitlement') {
-  const rootIndex = args.indexOf('--root');
-  const result = await acquireAttributionEntitlement({
-    root: rootIndex === -1 ? process.cwd() : args[rootIndex + 1]
-  });
-  process.stdout.write(result.changed
-    ? `Stored the signed attribution entitlement for ${result.siteId}.\n`
-    : `Attribution entitlement for ${result.siteId} is current.\n`);
-} else if (command === 'validate') {
-  const todayIndex = args.indexOf('--today');
-  const today = todayIndex === -1 ? undefined : args[todayIndex + 1];
-  const root = args.find((argument) => !argument.startsWith('--') && argument !== today) ?? process.cwd();
-  const { results } = await regenerateBuildManifest({ root, today });
-  const failures = results.filter(({ errors }) => errors.length > 0);
-
-  for (const result of failures) {
-    for (const error of result.errors) process.stderr.write(`${result.file}: ${error}\n`);
-  }
-  for (const result of results) {
-    for (const warning of result.warnings) process.stderr.write(`${result.file}: warning: ${warning}\n`);
+/**
+ * One line the writer can act on.
+ *
+ * A rejected top-level await prints a stack through node_modules by default, which buries the only
+ * line that matters. The stack is still there behind GALA_DEBUG for anyone debugging the CLI
+ * itself, which is a different audience from anyone trying to publish.
+ */
+function report(failure) {
+  if (process.env.GALA_DEBUG) {
+    process.stderr.write(`${failure instanceof Error ? failure.stack : String(failure)}\n`);
+    return;
   }
-  process.stdout.write(`Validated ${results.length} post variant(s); ${failures.length} failed.\n`);
-  if (failures.length > 0) process.exitCode = 1;
-} else if (command === 'new') {
-  const valueFor = (name) => {
-    const index = args.indexOf(name);
-    return index === -1 ? undefined : args[index + 1];
-  };
-  const title = valueFor('--title');
-  const language = valueFor('--language');
-  const today = valueFor('--today');
-  const root = valueFor('--root') ?? process.cwd();
-  const result = await createPost({ root, title, language, today });
-  process.stdout.write(`Created ${result.postPath}\n`);
-} else if (command === 'doctor') {
-  const positional = args.filter((argument, index) =>
-    !argument.startsWith('--') && args[index - 1] !== '--source'
-  );
-  const root = positional[0] ?? process.cwd();
-  if (args.includes('--fix')) {
-    const sourceIndex = args.indexOf('--source');
-    const sourceRoot = sourceIndex === -1 ? undefined : args[sourceIndex + 1];
-    if (!sourceRoot) throw new Error('doctor --fix requires --source <trusted-template-root>');
-    const repaired = await repairFramework(root, sourceRoot);
-    process.stdout.write(`Repaired ${repaired.length} managed file(s).\n`);
+  terminal.fail(failure instanceof Error ? failure.message : String(failure));
+  // Captured output from a subprocess is the most useful thing on screen at exactly this moment.
+  if (typeof failure?.detail === 'string' && failure.detail !== '') {
+    for (const line of failure.detail.split('\n')) terminal.note(line);
   }
-  const findings = await diagnoseFramework(root);
-  const drift = findings.filter(({ status }) => status !== 'intact');
-  findings.forEach(({ path: file, status }) => process.stdout.write(`${status}\t${file}\n`));
-  const publicationState = await diagnosePublicationState(root);
-  process.stdout.write(`${publicationState.status}\t${publicationState.path}\n`);
-  if (publicationState.status === 'invalid') process.exitCode = 1;
-  if (drift.length > 0) process.exitCode = 1;
-} else if (command === 'preview') {
-  const valueFor = (name) => {
-    const index = args.indexOf(name);
-    return index === -1 ? undefined : args[index + 1];
-  };
-  await previewSite({
-    root: valueFor('--root') ?? process.cwd(),
-    today: valueFor('--today')
-  });
-} else if (command === 'workflow') {
-  const valueFor = (name) => {
-    const index = args.indexOf(name);
-    return index === -1 ? undefined : args[index + 1];
-  };
-  const result = await writePublishWorkflow({
-    root: valueFor('--root') ?? process.cwd(),
-    siteId: valueFor('--site-id'),
-    timezone: valueFor('--timezone'),
-    actionRef: valueFor('--action-ref'),
-    defaultBranch: valueFor('--default-branch') ?? 'main',
-    buildMode: valueFor('--mode') ?? 'build-and-deploy'
-  });
-  process.stdout.write(`Wrote ${result.target} (${result.minute} ${result.hour} * * *)\n`);
-} else if (command === 'publish') {
-  const valueFor = (name) => {
-    const index = args.indexOf(name);
-    return index === -1 ? undefined : args[index + 1];
-  };
-  await publishSite({
-    root: valueFor('--root') ?? process.cwd(),
-    today: valueFor('--today'),
-    force: args.includes('--force')
-  });
-} else if (command === 'record-deployment') {
-  const valueFor = (name) => {
-    const index = args.indexOf(name);
-    return index === -1 ? undefined : args[index + 1];
-  };
-  const root = valueFor('--root') ?? process.cwd();
-  const result = await recordDeployment({
-    root,
-    deployedOn: valueFor('--today'),
-    deployedCommitSha: valueFor('--commit-sha')
-  });
-  process.stdout.write(
-    `${result.pushed ? 'Pushed' : 'No change for'} successful deployment `
-    + `of ${result.state.posts.length} article(s).\n`
-    + `Recorded state SHA: ${result.recordedStateSha}\n`
-  );
-} else if (command === 'refresh') {
-  const rootIndex = args.indexOf('--root');
-  const root = rootIndex === -1 ? process.cwd() : args[rootIndex + 1];
-  const result = await refreshEngagementSnapshot({ root });
-  process.stdout.write(result.changed
-    ? 'Refreshed, committed, and pushed the engagement snapshot.\n'
-    : 'Engagement snapshot is already current.\n');
-} else if (command === 'upgrade') {
-  const valueFor = (name) => {
-    const index = args.indexOf(name);
-    return index === -1 ? undefined : args[index + 1];
-  };
-  const terminalConfirm = async ({ installed, version, channel }) => {
-    if (args.includes('--yes')) return true;
-    const terminal = createInterface({ input: process.stdin, output: process.stdout });
-    try {
-      const answer = await terminal.question(`Upgrade theme ${installed} -> ${version} (${channel})? [y/N] `);
-      return /^(?:y|yes)$/i.test(answer.trim());
-    } finally { terminal.close(); }
-  };
-  const result = await upgradeTheme({
-    root: valueFor('--root') ?? process.cwd(),
-    channel: valueFor('--channel'),
-    confirm: terminalConfirm
-  });
-  process.stdout.write(result.cancelled ? 'Theme upgrade cancelled.\n'
-    : result.changed ? `Upgraded theme to ${result.version}.\n`
-      : `Theme ${result.version} is already installed.\n`);
-  process.stdout.write(
-    `Action major v${result.action.currentMajor}; `
-    + (result.action.newerAvailable
-      ? `v${result.action.latestMajor} is available.\n`
-      : 'no newer major is available.\n')
-  );
-} else if (command === 'hook' && args[0] === 'install') {
-  const rootIndex = args.indexOf('--root');
-  const root = rootIndex === -1 ? process.cwd() : args[rootIndex + 1];
-  const result = await installPrePushHook(root);
-  process.stdout.write(`${result.installed ? 'Installed' : 'Already installed'} ${result.target}\n`);
-} else {
-  process.stderr.write(`${usage}\n`);
-  process.exitCode = 1;
+  if (failure instanceof UsageError) usage();
+}
+
+function usage() {
+  const lines = Object.entries(COMMANDS)
+    .map(([key, { summary }]) => `    ${key.padEnd(9)} ${summary}`)
+    .join('\n');
+  process.stdout.write(`\n  gala <command>\n\n${lines}\n\n    Run any command with --help.\n\n`);
 }

package/src/publication.js

@@ -0,0 +1,37 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { parse } from 'yaml';
+
+/**
+ * Where a publication and its posts actually live on the web.
+ *
+ * The CLI knew every part of this and never said it: `new` printed a file path, `publish` said the
+ * site would appear shortly, and the writer was left to assemble
+ * `{canonicalBaseUrl}{pathPrefix}/{language}/{slug}/` themselves. That is easy to get wrong — the
+ * language segment is not obvious from anything they typed — and being unable to find your own post
+ * is a poor first minute with a publishing tool.
+ */
+export async function readPublication(root) {
+  try {
+    const configuration = parse(await readFile(path.join(root, 'site.config.yml'), 'utf8'));
+    const base = configuration?.hosting?.canonicalBaseUrl;
+    if (typeof base !== 'string') return null;
+    const prefix = typeof configuration?.hosting?.pathPrefix === 'string'
+      ? configuration.hosting.pathPrefix
+      : '/';
+    return {
+      name: configuration?.site?.name,
+      defaultLanguage: configuration?.site?.defaultLanguage ?? 'en',
+      url: `${base.replace(/\/$/, '')}${prefix === '/' ? '' : prefix}/`
+    };
+  } catch {
+    // Not being able to read it is never worth failing a command over; the caller simply says less.
+    return null;
+  }
+}
+
+export function postUrl(publication, slug, language) {
+  if (publication == null) return null;
+  return `${publication.url}${language ?? publication.defaultLanguage}/${slug}/`;
+}

package/src/assign-content-ids.js

@@ -1 +0,0 @@
-export { assignMissingContentIds } from '@rathnasgala/content-validation';

package/src/auth-command.js

@@ -1,36 +0,0 @@
-import { pollForGalaToken, requestGalaDeviceCode } from './gala-device-flow.js';
-import { writeGalaCredential } from './gala-credential-store.js';
-
-export async function authenticateGala({
-  apiBaseUrl = 'https://api.gala67.com',
-  clientId = 'gala-cli',
-  fetchImpl = fetch,
-  sleep,
-  now = Date.now,
-  showInstructions,
-  credentialTarget
-} = {}) {
-  if (typeof showInstructions !== 'function') throw new TypeError('showInstructions is required');
-  const authorization = await requestGalaDeviceCode({ apiBaseUrl, clientId, fetchImpl });
-  showInstructions({
-    verificationUri: authorization.verificationUri,
-    verificationUriComplete: authorization.verificationUriComplete,
-    userCode: authorization.userCode
-  });
-  const token = await pollForGalaToken({
-    ...authorization,
-    apiBaseUrl,
-    clientId,
-    fetchImpl,
-    ...(sleep == null ? {} : { sleep }),
-    now
-  });
-  const expiresAt = new Date(now() + token.expiresInSeconds * 1000);
-  const target = await writeGalaCredential({
-    accessToken: token.accessToken,
-    expiresAt,
-    apiBaseUrl,
-    ...(credentialTarget == null ? {} : { target: credentialTarget })
-  });
-  return Object.freeze({ target, expiresAt });
-}

package/src/configure-site.js

@@ -1,102 +0,0 @@
-import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { normalizeSiteConfigurationOptions } from '@rathnasgala/content-validation';
-import { parseDocument } from 'yaml';
-
-import { scaffoldOptionNames } from './scaffold-options.js';
-
-const IMPLEMENTED_DESIGN_VALUES = Object.freeze({
-  layout: Object.freeze(['article-first', 'portfolio']),
-  palette: Object.freeze(['default', 'ocean'])
-});
-
-function nonEmptyString(value, field) {
-  if (typeof value !== 'string' || value.trim() === '') {
-    throw new TypeError(`${field} must be a non-empty string`);
-  }
-  return value.trim();
-}
-
-export async function configureSite(root, designOptions) {
-  const configPath = path.resolve(root, 'site.config.yml');
-  const relation = path.relative(path.resolve(root), configPath);
-  if (relation.startsWith('..') || path.isAbsolute(relation)) {
-    throw new TypeError('site.config.yml escapes the site root');
-  }
-
-  const metadata = await lstat(configPath);
-  if (metadata.isSymbolicLink() || !metadata.isFile()) {
-    throw new TypeError('site.config.yml must be a regular file');
-  }
-
-  let config;
-  let document;
-  try {
-    document = parseDocument(await readFile(configPath, 'utf8'));
-    if (document.errors.length > 0) throw document.errors[0];
-    config = document.toJS();
-  } catch (error) {
-    throw new TypeError(`Invalid site.config.yml: ${error.message}`);
-  }
-  if (config.schemaVersion !== 1 || config.design == null || Array.isArray(config.design)) {
-    throw new TypeError('Unsupported site configuration schema');
-  }
-  if (Object.keys(designOptions).length === 0) return config;
-
-  const siteOptions = Object.fromEntries(
-    Object.entries(designOptions).filter(([name]) => !scaffoldOptionNames.includes(name))
-  );
-  const normalizedSiteOptions = normalizeSiteConfigurationOptions(siteOptions);
-
-  for (const [name, value] of Object.entries(designOptions)) {
-    if (scaffoldOptionNames.includes(name)) {
-      config.design[name] = nonEmptyString(value, `Design option ${name}`);
-      if (IMPLEMENTED_DESIGN_VALUES[name]?.includes(config.design[name]) === false) {
-        throw new TypeError(`Unsupported design ${name}: ${config.design[name]}`);
-      }
-      document.setIn(['design', name], config.design[name]);
-    }
-  }
-  if (normalizedSiteOptions.siteName != null) {
-    config.site.name = normalizedSiteOptions.siteName;
-    document.setIn(['site', 'name'], config.site.name);
-  }
-  if (normalizedSiteOptions.siteAuthor != null) {
-    config.site.author = normalizedSiteOptions.siteAuthor;
-    document.setIn(['site', 'author'], config.site.author);
-  }
-  if (normalizedSiteOptions.defaultLanguage != null) {
-    config.site.defaultLanguage = normalizedSiteOptions.defaultLanguage;
-    document.setIn(['site', 'defaultLanguage'], config.site.defaultLanguage);
-  }
-  if (normalizedSiteOptions.timezone != null) {
-    config.site.timezone = normalizedSiteOptions.timezone;
-    document.setIn(['site', 'timezone'], config.site.timezone);
-  }
-  if (normalizedSiteOptions.shareTargets != null) {
-    config.sharing.targets = normalizedSiteOptions.shareTargets;
-    document.setIn(['sharing', 'targets'], config.sharing.targets);
-  }
-  if (normalizedSiteOptions.socialProfiles != null) {
-    config.sharing.socialProfiles = normalizedSiteOptions.socialProfiles;
-    document.setIn(['sharing', 'socialProfiles'], config.sharing.socialProfiles);
-  }
-
-  const temporary = `${configPath}.gala-config-${process.pid}`;
-  const backup = `${configPath}.gala-backup-${process.pid}`;
-  try {
-    await writeFile(temporary, String(document), { flag: 'wx' });
-    await rename(configPath, backup);
-    try {
-      await rename(temporary, configPath);
-    } catch (error) {
-      await rename(backup, configPath);
-      throw error;
-    }
-    await rm(backup);
-  } catch (error) {
-    await rm(temporary, { force: true });
-    throw error;
-  }
-  return config;
-}

package/src/content-files.js

@@ -1 +0,0 @@
-export { markdownPostFiles } from '@rathnasgala/content-validation';