@rathnasgala/cli 0.0.5 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala/cli",
-  "version": "0.0.5",
+  "version": "0.0.8",
   "type": "module",
   "files": [
     "src"
@@ -14,7 +14,9 @@
   },
   "scripts": {
     "test": "node --test",
-    "lint": "node scripts/lint.js"
+    "lint": "node scripts/lint.js",
+    "preversion": "npm test && npm run lint",
+    "push": "node scripts/push.js"
   },
   "engines": {
     "node": ">=18"
@@ -24,7 +26,7 @@
     "url": "git+https://github.com/rathnasgala/cli.git"
   },
   "dependencies": {
-    "@rathnasgala/content-validation": "0.0.1",
+    "@rathnasgala/content-validation": "0.0.2",
     "libsodium-wrappers": "0.8.4",
     "tar": "7.5.22",
     "yaml": "2.9.0"

package/src/github-pages-provisioning.js

@@ -25,6 +25,7 @@ async function json(response, operation) {
 
 export async function provisionGithubPages({
   owner, repository, accessToken, commitSha, fetchImpl = fetch,
+  customDomain = null,
   sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
   pollIntervalMs = 5_000, maxPolls = 120
 }) {
@@ -32,6 +33,10 @@ export async function provisionGithubPages({
   const normalizedRepository = required(repository, 'repository', SEGMENT);
   const token = required(accessToken, 'accessToken');
   const sha = required(commitSha, 'commitSha', SHA);
+  if (customDomain != null && (typeof customDomain !== 'string'
+      || !/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(customDomain))) {
+    throw new TypeError('customDomain is invalid');
+  }
   if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 0) {
     throw new TypeError('pollIntervalMs must be a non-negative safe integer');
   }
@@ -69,6 +74,15 @@ export async function provisionGithubPages({
     if (configuration.source?.branch !== 'gh-pages' || configuration.source?.path !== '/') {
       throw new Error('Existing GitHub Pages configuration does not use gh-pages at /');
     }
+    if ((configuration.cname ?? null) !== customDomain) {
+      const updated = await fetchImpl(`${repositoryUrl}/pages`, {
+        method: 'PUT', headers: requestHeaders,
+        body: JSON.stringify({ cname: customDomain, source: { branch: 'gh-pages', path: '/' } })
+      });
+      if (updated.status !== 204) {
+        throw new Error(`GitHub Pages custom-domain update failed with HTTP ${updated.status}`);
+      }
+    }
     return Object.freeze({ created: false, url: configuration.html_url, runUrl: run.html_url });
   }
   if (current.status !== 404) {
@@ -79,5 +93,14 @@ export async function provisionGithubPages({
     body: JSON.stringify({ source: { branch: 'gh-pages', path: '/' } })
   });
   const configuration = await json(created, 'Pages activation');
+  if (customDomain != null) {
+    const updated = await fetchImpl(`${repositoryUrl}/pages`, {
+      method: 'PUT', headers: requestHeaders,
+      body: JSON.stringify({ cname: customDomain, source: { branch: 'gh-pages', path: '/' } })
+    });
+    if (updated.status !== 204) {
+      throw new Error(`GitHub Pages custom-domain update failed with HTTP ${updated.status}`);
+    }
+  }
   return Object.freeze({ created: true, url: configuration.html_url, runUrl: run.html_url });
 }

package/src/index.js

@@ -75,11 +75,15 @@ if (command === 'auth') {
     return index === -1 ? undefined : args[index + 1];
   };
   const installationId = Number(valueFor('--installation-id'));
+  const topology = valueFor('--topology') ?? 'provider-default';
   const result = await scaffoldSite({
     owner: valueFor('--owner'),
     repository: valueFor('--repository'),
     target: valueFor('--target'),
     githubInstallationId: installationId,
+    topology,
+    canonicalBaseUrl: valueFor('--canonical-base-url'),
+    actionRef: valueFor('--action-ref'),
     siteOptions: parseScaffoldOptions(args),
     buildMode: valueFor('--mode') ?? 'build-and-deploy',
     emptyExistingRepository: args.includes('--empty-existing-repository'),

package/src/scaffold-site.js

@@ -21,14 +21,34 @@ function segment(value, field) {
   return value;
 }
 
-function providerDefaultBase(owner, repository) {
-  const rootRepository = repository.toLowerCase() === `${owner}.github.io`.toLowerCase();
-  return `https://${owner.toLowerCase()}.github.io${rootRepository ? '/' : `/${repository}/`}`;
+function providerDefaultBase(owner) {
+  return `https://${owner.toLowerCase()}.github.io`;
+}
+
+function registrationLocation(owner, topology, canonicalBaseUrl) {
+  if (topology === 'provider-default') {
+    if (canonicalBaseUrl != null) {
+      throw new TypeError('--canonical-base-url is valid only with --topology custom-domain');
+    }
+    return { topology: 'PROVIDER_DEFAULT', canonicalBaseUrl: providerDefaultBase(owner) };
+  }
+  if (topology !== 'custom-domain') {
+    throw new TypeError('topology must be provider-default or custom-domain');
+  }
+  if (typeof canonicalBaseUrl !== 'string') {
+    throw new TypeError('--canonical-base-url is required with --topology custom-domain');
+  }
+  const canonical = new URL(canonicalBaseUrl);
+  if (canonical.protocol !== 'https:' || canonical.username || canonical.password
+      || canonical.port || canonical.search || canonical.hash || canonical.pathname !== '/') {
+    throw new TypeError('canonicalBaseUrl must be a credential-free HTTPS origin');
+  }
+  return { topology: 'CUSTOM_DOMAIN', canonicalBaseUrl: canonical.origin };
 }
 
 export async function scaffoldSite({
   owner, repository, target, githubInstallationId, siteOptions, emptyExistingRepository = false,
-  resumeExistingCheckout = false,
+  resumeExistingCheckout = false, topology = 'provider-default', canonicalBaseUrl, actionRef,
   buildMode = 'build-and-deploy', templateOwner = 'rathnasgala',
   templateRepository = 'site-template',
   readGithub = readGithubCredential, readGala = readGalaCredential,
@@ -42,6 +62,7 @@ export async function scaffoldSite({
 }) {
   const repositoryOwner = segment(owner, 'owner');
   const repositoryName = segment(repository, 'repository');
+  const location = registrationLocation(repositoryOwner, topology, canonicalBaseUrl);
   if (!Number.isSafeInteger(githubInstallationId) || githubInstallationId <= 0) {
     throw new TypeError('githubInstallationId must be a positive integer');
   }
@@ -77,20 +98,21 @@ export async function scaffoldSite({
     if (emptyExistingRepository) await setOrigin({ root, owner: repositoryOwner, repository: repositoryName });
   }
   const configured = await configure(root, siteOptions ?? {});
-  const canonicalBaseUrl = providerDefaultBase(repositoryOwner, repositoryName);
   const idempotencyKey = `scaffold-${createHash('sha256').update(`${repositoryOwner.toLowerCase()}/${repositoryName.toLowerCase()}`).digest('hex')}`;
   const registration = await register({
     apiBaseUrl: gala.apiBaseUrl, galaAccessToken: gala.accessToken, idempotencyKey,
     githubInstallationId, repositoryOwner, repositoryName,
-    topology: 'PROVIDER_DEFAULT', canonicalBaseUrl
+    topology: location.topology, canonicalBaseUrl: location.canonicalBaseUrl
   });
   await finalize(root, {
     siteId: registration.siteId,
     canonicalBaseUrl: registration.canonicalBaseUrl,
-    topology: 'provider-default'
+    pathPrefix: registration.pathPrefix,
+    topology
   });
   await writeWorkflow({
-    root, siteId: registration.siteId, timezone: configured.site.timezone, buildMode
+    root, siteId: registration.siteId, timezone: configured.site.timezone, buildMode,
+    ...(actionRef == null ? {} : { actionRef })
   });
   await installSecret({
     owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken,
@@ -102,7 +124,8 @@ export async function scaffoldSite({
   });
   const commitSha = await commit(root);
   const pages = buildMode === 'build-and-deploy' ? await provisionPages({
-    owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken, commitSha
+    owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken, commitSha,
+    customDomain: location.topology === 'CUSTOM_DOMAIN' ? new URL(location.canonicalBaseUrl).hostname : null
   }) : null;
   return Object.freeze({
     root, fullName: generated.fullName, siteId: registration.siteId, commitSha, pages

package/src/site-config-registration.js

@@ -2,12 +2,22 @@ import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parse, stringify } from 'yaml';
 
-export async function writeRegisteredSiteConfiguration(root, { siteId, canonicalBaseUrl, topology }) {
+export async function writeRegisteredSiteConfiguration(root, {
+  siteId, canonicalBaseUrl, pathPrefix, topology
+}) {
   if (!/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/.test(siteId)) throw new TypeError('siteId is invalid');
-  if (topology !== 'provider-default') throw new TypeError('Only provider-default topology is implemented');
+  if (!['provider-default', 'custom-domain'].includes(topology)) {
+    throw new TypeError('topology is invalid');
+  }
   const canonical = new URL(canonicalBaseUrl);
-  if (canonical.protocol !== 'https:' || canonical.username || canonical.password || canonical.search || canonical.hash) {
-    throw new TypeError('canonicalBaseUrl must be credential-free HTTPS');
+  if (canonical.protocol !== 'https:' || canonical.username || canonical.password || canonical.search
+      || canonical.hash || canonical.pathname !== '/') {
+    throw new TypeError('canonicalBaseUrl must be a credential-free HTTPS origin; put the URL path in pathPrefix');
+  }
+  const normalizedPrefix = pathPrefix === '' ? '/' : pathPrefix;
+  if (typeof normalizedPrefix !== 'string'
+      || !/^\/(?:[^/?#]+(?:\/[^/?#]+)*)?$/.test(normalizedPrefix)) {
+    throw new TypeError('pathPrefix must be a normalized URL path');
   }
   const target = path.resolve(root, 'site.config.yml');
   const metadata = await lstat(target);
@@ -19,8 +29,8 @@ export async function writeRegisteredSiteConfiguration(root, { siteId, canonical
   config.site.id = siteId;
   config.hosting.provider = 'github-pages';
   config.hosting.topology = topology;
-  config.hosting.canonicalBaseUrl = canonical.href.replace(/\/$/, '');
-  config.hosting.pathPrefix = canonical.pathname === '/' ? '/' : canonical.pathname.replace(/\/$/, '');
+  config.hosting.canonicalBaseUrl = canonical.origin;
+  config.hosting.pathPrefix = normalizedPrefix;
   const temporary = `${target}.gala-register-${process.pid}`;
   const backup = `${target}.gala-backup-${process.pid}`;
   try {

package/src/site-registration-client.js

@@ -72,9 +72,13 @@ export async function registerSite({
   }
   const canonical = new URL(payload.canonicalBaseUrl);
   if (canonical.protocol !== 'https:' || canonical.username || canonical.password
-      || canonical.search || canonical.hash) {
+      || canonical.search || canonical.hash || canonical.pathname !== '/') {
     throw new TypeError('Gala site registration returned an invalid canonicalBaseUrl');
   }
+  if (typeof payload.pathPrefix !== 'string'
+      || !/^\/(?:[^/?#]+(?:\/[^/?#]+)*)?$/.test(payload.pathPrefix)) {
+    throw new TypeError('Gala site registration returned an invalid pathPrefix');
+  }
   const location = response.headers?.get?.('location');
   if (location !== `/v1/sites/${payload.siteId}`) {
     throw new TypeError('Gala site registration returned an invalid Location header');
@@ -82,6 +86,7 @@ export async function registerSite({
   return Object.freeze({
     siteId: payload.siteId,
     siteSecret: payload.siteSecret,
-    canonicalBaseUrl: canonical.href
+    canonicalBaseUrl: canonical.origin,
+    pathPrefix: payload.pathPrefix === '' ? '/' : payload.pathPrefix
   });
 }

package/src/workflow-command.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
-const ACTION_REF = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/.github\/workflows\/[A-Za-z0-9_.-]+\.ya?ml@v[1-9][0-9]*$/;
+const ACTION_REF = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/.github\/workflows\/[A-Za-z0-9_.-]+\.ya?ml@v(?:[1-9][0-9]*|[0-9]+\.[0-9]+\.[0-9]+)$/;
 const BRANCH = /^(?![./])(?!.*\.\.)(?!.*[~^:?*\[\\])[A-Za-z0-9._/-]+(?<![/.])$/;
 
 export function deriveNightlySchedule(siteId) {
@@ -28,7 +28,9 @@ export async function writePublishWorkflow({
   buildMode = 'build-and-deploy'
 }) {
   validateTimezone(timezone);
-  if (!ACTION_REF.test(actionRef)) throw new TypeError('actionRef must pin a reusable workflow to a major version');
+  if (!ACTION_REF.test(actionRef)) {
+    throw new TypeError('actionRef must pin a reusable workflow to a major or immutable semver tag');
+  }
   if (!BRANCH.test(defaultBranch)) throw new TypeError('Invalid default branch');
   if (!['build-only', 'build-and-deploy'].includes(buildMode)) throw new TypeError('Invalid build mode');