@rathnasgala/cli 1.1.7 → 1.1.9

package/README.md

@@ -31,8 +31,9 @@ accepted and its `.git` directory is preserved. To reserve a custom domain durin
 before activating it.
 
 It signs you in to Gala and to GitHub if you are not already, creates the repository, registers the
-publication, and leaves a working checkout in the folder. When it finishes it prints the address
-your publication will live at.
+publication, and leaves a working checkout in the folder. GitHub starts the first deployment in the
+background. The command links to that deployment rather than presenting the public address as live
+before GitHub has finished.
 
 On the first run, it opens GitHub's Gala App installation page. Choose the account Gala may use,
 finish the installation, and return to the terminal; the same command resumes automatically.
@@ -43,12 +44,19 @@ unavoidable. Everything else is automatic.
 
 ## Write
 
+Every command continues to run through `npx`; `init` does not install a global `gala` executable.
+To see every command, run:
+
+```console
+npx --yes @rathnasgala/cli@latest --help
+```
+
 ```console
 npx --yes @rathnasgala/cli@latest new "The places we return to"
 ```
 
-This creates the Markdown file and tells you the address the post will appear at. Write below the
-second `---` line.
+This creates a local Markdown draft; it does not publish anything. It also tells you the address the
+post will use after a successful publication. Write below the second `---` line.
 
 ```console
 npx --yes @rathnasgala/cli@latest preview

package/package.json

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

package/src/cli/invocation.js

@@ -0,0 +1,9 @@
+export const CLI_INVOCATION = 'npx --yes @rathnasgala/cli@latest';
+
+export function cliCommand(argumentsText = '') {
+  return argumentsText === '' ? CLI_INVOCATION : `${CLI_INVOCATION} ${argumentsText}`;
+}
+
+export function shellArgument(value) {
+  return /^[A-Za-z0-9_./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}

package/src/commands/doctor.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { galaApi } from '../api/gala.js';
 import { galaCredential } from '../auth/gala.js';
 import { githubCredential } from '../auth/github.js';
+import { cliCommand } from '../cli/invocation.js';
 import { createGit } from '../git.js';
 
 /**
@@ -23,7 +24,7 @@ export async function doctor({ terminal, options, cwd = process.cwd() }) {
     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');
+      : wrong('the API no longer accepts it', cliCommand('auth'));
   }));
 
   checks.push(await checkCredential('GitHub sign-in', async () => {
@@ -45,7 +46,7 @@ export async function doctor({ terminal, options, cwd = process.cwd() }) {
     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')
+      ? wrong('no site id — this publication may not be registered', cliCommand('init'))
       : ok(siteId);
   }, 'the workflow is missing; registration writes it'));
 
@@ -53,8 +54,8 @@ export async function doctor({ terminal, options, cwd = process.cwd() }) {
     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');
+    if (dirty !== '') return wrong(`${dirty.split('\n').length} file(s) not recorded`, cliCommand('publish'));
+    if (ahead !== '' && ahead !== '0') return wrong(`${ahead} commit(s) not sent`, cliCommand('publish'));
     return ok('everything is on GitHub');
   }, 'this folder is not a git checkout'));
 

package/src/commands/domain.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { galaApi } from '../api/gala.js';
 import { galaCredential } from '../auth/gala.js';
 import { UsageError } from '../cli/args.js';
+import { cliCommand } from '../cli/invocation.js';
 import { customDomain } from '../domain.js';
 import { readPublication } from '../publication.js';
 
@@ -16,7 +17,7 @@ export async function domain({ terminal, options, cwd = process.cwd() }) {
   }
   const [action = 'status', value, ...extra] = options.positional;
   if (extra.length > 0 || !['status', 'set', 'check', 'cancel', 'remove'].includes(action)) {
-    throw new UsageError('Use: gala domain [status|set <hostname>|check|cancel|remove]');
+    throw new UsageError(`Use: ${cliCommand('domain [status|set <hostname>|check|cancel|remove]')}`);
   }
   if (action === 'set' && value == null) throw new UsageError('domain set needs a hostname');
   if (action !== 'set' && value != null) throw new UsageError(`domain ${action} takes no hostname`);
@@ -45,7 +46,7 @@ export async function domain({ terminal, options, cwd = process.cwd() }) {
       pathPrefix: '/',
     });
     terminal.done(`Reserved ${checked.host}`);
-    terminal.note('Verify it in the repository owner’s GitHub account, then run: gala domain check');
+    terminal.note(`Verify it in the repository owner’s GitHub account, then run: ${cliCommand('domain check')}`);
     terminal.openUrl('https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages');
     return change;
   }
@@ -83,7 +84,7 @@ export async function domain({ terminal, options, cwd = process.cwd() }) {
       const configured = await api.configureTopologyChange(publication.siteId, pending.changeId);
       terminal.done(`GitHub verified ${configured.cname}`);
       terminal.note(dnsInstruction(configured.cname, await providerHost(api, publication.siteId)));
-      terminal.note('After DNS propagates, run: gala domain check');
+      terminal.note(`After DNS propagates, run: ${cliCommand('domain check')}`);
       return configured;
     }
     const committed = await api.commitTopologyChange(publication.siteId, pending.changeId);
@@ -119,6 +120,6 @@ function dnsInstruction(host, target) {
 function showPending(terminal, pending) {
   terminal.result(`${pending.canonicalBaseUrl}${pending.pathPrefix}`);
   terminal.note(`State: ${pending.state}`);
-  if (pending.state === 'PREPARED') terminal.note('Next: verify ownership, then run gala domain check.');
-  else terminal.note('Next: configure DNS, then run gala domain check.');
+  if (pending.state === 'PREPARED') terminal.note(`Next: verify ownership, then run ${cliCommand('domain check')}.`);
+  else terminal.note(`Next: configure DNS, then run ${cliCommand('domain check')}.`);
 }

package/src/commands/init.js

@@ -7,6 +7,7 @@ import { galaCredential } from '../auth/gala.js';
 import { githubCredential } from '../auth/github.js';
 import { cloneRepository, createGit, populateEmptyRepository } from '../git.js';
 import { UsageError } from '../cli/args.js';
+import { CLI_INVOCATION, shellArgument } from '../cli/invocation.js';
 import { customDomain } from '../domain.js';
 
 /**
@@ -26,7 +27,8 @@ import { customDomain } from '../domain.js';
  *   - **GitHub** turns on Pages by itself once publishing creates a `gh-pages` branch. The CLI used
  *     to poll ten minutes for a run it had caused, then call an API that changed nothing.
  *
- * What is left is genuinely the CLI's: asking what to call it, cloning, and reporting the address.
+ * What is left is genuinely the CLI's: asking what to call it, cloning, and explaining the next
+ * steps without presenting a deployment as live before GitHub has finished it.
  */
 const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const GITHUB_APP_INSTALLATION_URL = 'https://github.com/apps/gala67-app/installations/new';
@@ -87,10 +89,6 @@ export async function init({ terminal, options, cwd = process.cwd() }) {
   // writer's copy is the publication as it actually exists.
   await git.takeRemote();
 
-  terminal.done(`Created ${created.owner}/${created.name}`);
-  terminal.result(publicationUrl(registration, created));
-  terminal.note(path.relative(cwd, directory) || '.');
-
   let domainChange;
   if (checkedDomain?.host) {
     terminal.step(`Reserving ${checkedDomain.host}`);
@@ -107,9 +105,13 @@ export async function init({ terminal, options, cwd = process.cwd() }) {
     }
   }
 
-  terminal.blank();
-  terminal.note('gala new "Your first post"');
-  if (domainChange) terminal.note('gala domain check');
+  reportCreatedPublication({
+    terminal,
+    owner: created.owner,
+    name: created.name,
+    directoryLabel: path.relative(cwd, directory) || '.',
+    hasDomainChange: domainChange != null
+  });
 
   return { owner: created.owner, name: created.name, siteId: registration.siteId, root: directory };
 }
@@ -283,10 +285,33 @@ async function hasReference(directory) {
   return false;
 }
 
-function publicationUrl(registration, created) {
-  const base = registration?.canonicalBaseUrl ?? `https://${created.owner.toLowerCase()}.github.io`;
-  const prefix = registration?.pathPrefix ?? `/${created.name}`;
-  return `${base}${prefix === '/' ? '' : prefix}/`;
+export function reportCreatedPublication({
+  terminal,
+  owner,
+  name,
+  directoryLabel,
+  hasDomainChange = false
+}) {
+  const run = CLI_INVOCATION;
+  terminal.done(`Created ${owner}/${name}`);
+  terminal.note('The first deployment is running in GitHub Actions. The public site is not live yet.');
+  terminal.note(`track it at https://github.com/${owner}/${name}/actions`);
+
+  terminal.blank();
+  terminal.result('Next steps');
+  if (directoryLabel !== '.') terminal.note(`cd ${shellArgument(directoryLabel)}`);
+  terminal.note(`${run} new "Your first post"`);
+  terminal.note('creates a local Markdown draft; it does not publish');
+  terminal.note(`${run} preview`);
+  terminal.note('builds and serves the publication locally');
+  terminal.note(`${run} publish`);
+  terminal.note('checks and sends the work to GitHub');
+  if (hasDomainChange) {
+    terminal.note(`${run} domain check`);
+    terminal.note('checks whether the custom domain is ready');
+  }
+  terminal.note(`${run} --help`);
+  terminal.note('lists every available command');
 }
 
 function idempotencyKey(owner, name) {

package/src/commands/new.js

@@ -11,6 +11,7 @@ import {
 import { stringify } from 'yaml';
 
 import { UsageError } from '../cli/args.js';
+import { cliCommand } from '../cli/invocation.js';
 import { postUrl, readPublication } from '../publication.js';
 
 /**
@@ -54,7 +55,7 @@ export async function createPost({ terminal, options, cwd = process.cwd(), now =
   if (address != null) terminal.note(`will appear at ${address}`);
 
   terminal.blank();
-  terminal.note('write below the second --- line, then: gala preview');
+  terminal.note(`write below the second --- line, then: ${cliCommand('preview')}`);
   return { file, metadata };
 }
 

package/src/commands/prism.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { galaApi } from '../api/gala.js';
 import { galaCredential } from '../auth/gala.js';
 import { UsageError } from '../cli/args.js';
+import { cliCommand } from '../cli/invocation.js';
 import { createGit } from '../git.js';
 import { readPublication } from '../publication.js';
 
@@ -25,7 +26,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   const [action = 'status', ...args] = options.positional;
 
   if (action === 'status') {
-    requireArgs(args, 0, 'gala prism status');
+    requireArgs(args, 0, cliCommand('prism status'));
     const state = await api.json(`/v1/sites/${publication.siteId}/prism`, { action: 'Prism status' });
     terminal.result(`Prism ${state.publishedMode}`);
     terminal.note(`Mode: requested ${state.requestedMode}; published ${state.publishedMode}`);
@@ -39,7 +40,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   const expectedRepositoryHeadSha = inventory.headSha;
 
   if (action === 'mode') {
-    requireArgs(args, 1, 'gala prism mode <off|presentation-only|manual|assisted>');
+    requireArgs(args, 1, cliCommand('prism mode <off|presentation-only|manual|assisted>'));
     const mode = MODES.get(args[0]);
     if (!mode) throw new UsageError('Prism mode must be off, presentation-only, manual, or assisted.');
     if (mode === 'OFF' || mode === 'PRESENTATION_ONLY') await confirm(terminal, options, `Change Prism mode to ${args[0]}?`);
@@ -52,7 +53,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   if (action === 'link-policy') {
     const [scope, target, value] = args;
     if (scope === 'site') {
-      requireArgs(args, 2, 'gala prism link-policy site <nofollow|follow>');
+      requireArgs(args, 2, cliCommand('prism link-policy site <nofollow|follow>'));
       const policy = policyValue(target);
       const result = await mutate(api, `/v1/sites/${publication.siteId}/prism`, 'PUT', {
         configurationLinkPolicy: policy, expectedRepositoryHeadSha,
@@ -60,7 +61,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
       return settleMutation(api, terminal, publication, result);
     }
     if (scope === 'work') {
-      requireArgs(args, 3, 'gala prism link-policy work <slug> <inherit|nofollow|follow>');
+      requireArgs(args, 3, cliCommand('prism link-policy work <slug> <inherit|nofollow|follow>'));
       const post = resolvePost(inventory, target, options.value('language'), publication.defaultLanguage);
       if (value === 'inherit') {
         const result = await mutate(api,
@@ -76,11 +77,14 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
         }, 'Prism work link policy');
       return settleMutation(api, terminal, publication, result);
     }
-    throw new UsageError('Use: gala prism link-policy site <nofollow|follow> or work <slug> <inherit|nofollow|follow>');
+    throw new UsageError(
+      `Use: ${cliCommand('prism link-policy site <nofollow|follow>')} or `
+        + cliCommand('prism link-policy work <slug> <inherit|nofollow|follow>')
+    );
   }
 
   if (action === 'list') {
-    requireArgs(args, 1, 'gala prism list <slug> [--language en]');
+    requireArgs(args, 1, cliCommand('prism list <slug> [--language en]'));
     const post = resolvePost(inventory, args[0], options.value('language'), publication.defaultLanguage);
     const result = await configurations(api, publication.siteId, post);
     terminal.result(`${result.configurations.length} configuration${result.configurations.length === 1 ? '' : 's'}`);
@@ -91,7 +95,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   }
 
   if (action === 'create') {
-    requireArgs(args, 1, 'gala prism create <slug> --language en --depth brief --intent orientation');
+    requireArgs(args, 1, cliCommand('prism create <slug> --language en --depth brief --intent orientation'));
     const post = resolvePost(inventory, args[0], options.value('language'), publication.defaultLanguage);
     const current = await configurations(api, publication.siteId, post);
     const result = await mutate(api,
@@ -108,7 +112,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   }
 
   if (!['edit', 'generate', 'submit', 'approve', 'reject', 'revoke'].includes(action)) {
-    throw new UsageError('Unknown Prism action. Run gala prism --help.');
+    throw new UsageError(`Unknown Prism action. Run ${cliCommand('prism --help')}.`);
   }
 
   const configurationId = args[0];
@@ -119,7 +123,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   const base = `/v1/sites/${publication.siteId}/articles/${post.articleId}/configurations/${configurationId}`;
 
   if (action === 'edit') {
-    requireArgs(args, 1, 'gala prism edit <configuration-id> --file proposal.md');
+    requireArgs(args, 1, cliCommand('prism edit <configuration-id> --file proposal.md'));
     const filename = options.value('file');
     if (!filename) throw new UsageError('Prism edit needs --file proposal.md.');
     const markdown = await readFile(path.resolve(root, filename), 'utf8');
@@ -132,7 +136,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
   }
 
   if (action === 'generate') {
-    requireArgs(args, 1, 'gala prism generate <configuration-id>');
+    requireArgs(args, 1, cliCommand('prism generate <configuration-id>'));
     const result = await mutate(api, `${base}/generation-jobs`, 'POST', {
       expectedSourceContentHash: collection.sourceRevisionHash,
       hashContract: collection.hashContract,
@@ -146,7 +150,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
     throw new UsageError(`${action} needs a revision ID when there is no working revision.`);
   }
   if (action === 'submit') {
-    if (args.length > 2) throw new UsageError('Use: gala prism submit <configuration-id> [revision-id]');
+    if (args.length > 2) throw new UsageError(`Use: ${cliCommand('prism submit <configuration-id> [revision-id]')}`);
     if (revisionId !== configuration.workingRevision?.revisionId) {
       throw new UsageError('Only the current working revision can be submitted. Refresh the configuration and try again.');
     }
@@ -165,7 +169,7 @@ export async function prism({ terminal, options, cwd = process.cwd() }) {
 
   const reason = options.value('reason');
   if (action === 'approve') {
-    if (args.length > 2) throw new UsageError('Use: gala prism approve <configuration-id> [revision-id] [--yes]');
+    if (args.length > 2) throw new UsageError(`Use: ${cliCommand('prism approve <configuration-id> [revision-id] [--yes]')}`);
     if (revisionId !== configuration.workingRevision?.revisionId) {
       throw new UsageError('Only the current working revision can be approved. Refresh the configuration and try again.');
     }
@@ -292,7 +296,7 @@ async function settleMutation(api, terminal, publication, result) {
     throw new UsageError(`Repository update failed (${state.errorCode ?? 'unknown error'}). Run the command again after correcting the cause.`);
   }
   if (state.status !== 'COMMITTED') {
-    throw new UsageError('Repository update did not finish before the 31-minute tracking deadline. Check gala prism status before retrying.');
+    throw new UsageError(`Repository update did not finish before the 31-minute tracking deadline. Check ${cliCommand('prism status')} before retrying.`);
   }
   if (!state.publicationAttemptSha) {
     terminal.result('Repository updated. No publication attempt was returned.');

package/src/commands/upgrade.js

@@ -4,6 +4,8 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { x as extractTar } from 'tar';
 
+import { cliCommand } from '../cli/invocation.js';
+
 const PACKAGE = '@rathnasgala/theme';
 const REGISTRY = 'https://registry.npmjs.org';
 const PROTECTED = ['.git/', 'content/', 'custom.css', 'site.config.yml'];
@@ -81,7 +83,7 @@ async function assertNoManagedDrift(root, installed) {
   for (const [managed, expected] of Object.entries(installed.files)) {
     const file = path.join(root, managed);
     if (!await exists(file) || (await lstat(file)).isSymbolicLink() || sha256(await readFile(file)) !== expected) {
-      throw new Error(`${managed} has local changes; restore it with gala doctor before upgrading`);
+      throw new Error(`${managed} has local changes; restore it with ${cliCommand('doctor')} before upgrading`);
     }
   }
 }
@@ -168,6 +170,6 @@ export async function upgrade({ terminal, options, cwd = process.cwd(), fetchImp
     await rm(unpacked.temporary, { recursive: true, force: true });
   }
   terminal.done(`Upgraded managed theme to ${release.version}`);
-  terminal.note('Run gala preview, then gala publish when the result is approved.');
+  terminal.note(`Run ${cliCommand('preview')}, then ${cliCommand('publish')} when the result is approved.`);
   return { changed: true, version: release.version };
 }

package/src/commands-manifest.js

@@ -7,6 +7,7 @@ import { preview } from './commands/preview.js';
 import { publish } from './commands/publish.js';
 import { prism } from './commands/prism.js';
 import { upgrade } from './commands/upgrade.js';
+import { cliCommand } from './cli/invocation.js';
 
 /**
  * Commands in the order a writer meets them.
@@ -31,19 +32,19 @@ export const COMMANDS = {
   },
   init: {
     summary: 'Create a publication in an empty directory',
-    usage: 'gala init [directory] [--name my-notes] [--domain blog.example.com]',
+    usage: cliCommand('init [directory] [--name my-notes] [--domain blog.example.com]'),
     flags: ['name', 'domain', 'api-base-url'],
     run: init
   },
   domain: {
     summary: 'Inspect or change this publication’s custom domain',
-    usage: 'gala domain [status|set <hostname>|check|cancel|remove] [--root path]',
+    usage: cliCommand('domain [status|set <hostname>|check|cancel|remove] [--root path]'),
     flags: ['root', 'api-base-url'],
     run: domain
   },
   new: {
     summary: 'Start a post',
-    usage: 'gala new "A durable idea" [--language en]',
+    usage: cliCommand('new "A durable idea" [--language en]'),
     flags: ['root', 'language', 'today'],
     run: createPost
   },
@@ -60,14 +61,14 @@ export const COMMANDS = {
   },
   prism: {
     summary: 'Manage author-approved Prism configurations',
-    usage: 'gala prism <status|mode|link-policy|list|create|edit|generate|submit|approve|reject|revoke> [arguments]',
+    usage: cliCommand('prism <status|mode|link-policy|list|create|edit|generate|submit|approve|reject|revoke> [arguments]'),
     flags: ['root', 'api-base-url', 'language', 'depth', 'intent', 'modality', 'file', 'reason'],
     switches: ['yes'],
     run: prism
   },
   upgrade: {
     summary: 'Inspect and apply a verified managed-theme update',
-    usage: 'gala upgrade [--channel latest|next] [--yes]',
+    usage: cliCommand('upgrade [--channel latest|next] [--yes]'),
     flags: ['root', 'channel'],
     switches: ['yes'],
     run: upgrade

package/src/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { UsageError, parseArguments } from './cli/args.js';
+import { CLI_INVOCATION, cliCommand } from './cli/invocation.js';
 import { createTerminal } from './cli/terminal.js';
 import { COMMANDS } from './commands-manifest.js';
 
@@ -20,7 +21,7 @@ if (command == null) {
 }
 
 if (argv.includes('--help') || argv.includes('-h')) {
-  process.stdout.write(`\n  ${command.usage ?? `gala ${name}`}\n  ${command.summary}\n\n`);
+  process.stdout.write(`\n  ${command.usage ?? cliCommand(name)}\n  ${command.summary}\n\n`);
   process.exit(0);
 }
 
@@ -56,5 +57,6 @@ 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`);
+  process.stdout.write(`\n  ${CLI_INVOCATION} <command>\n\n${lines}\n\n`
+    + `    Run ${CLI_INVOCATION} <command> --help for details.\n\n`);
 }